Subroutines differ from actions because they generally only affect internal DTrace state. Therefore, there are no destructive subroutines, and subroutines never trace data into buffers. Many subroutines have analogs in the Section 9F or Section 3C interfaces. See Intro ( 9F ) and Intro ( 3 ) for more information on the corresponding subroutines.
void *alloca(size_t size
)
alloca
allocates size
bytes out of scratch space, and returns a pointer to the allocated memory. The returned pointer is guaranteed to have 8–byte alignment. Scratch space is only valid for the duration of a clause. Memory allocated with alloca
will be deallocated when the clause completes. If insufficient scratch space is available, no memory is allocated and an error is generated.
string basename(char *str
)
basename
is a D analogue for
basename
(
1
)
. This subroutine creates a string that consists of a copy of the specified string, but without any prefix that ends in /
. The returned string is allocated out of scratch memory, and is therefore valid only for the duration of the clause. If insufficient scratch space is available, basename
does not execute and an error is generated.
void bcopy(void *src
, void *dest
, size_tsize
)
bcopy
copies size
bytes from the memory pointed to by src
to the memory pointed to by dest
. All of the source memory must lie outside of scratch memory and all of the destination memory must lie within it. If these conditions are not met, no copying takes place and an error is generated.
string cleanpath(char *str
)
cleanpath
creates a string that consists of a copy of the path indicated by str
, but with certain redundant elements eliminated. In particular “/./
” elements in the path are removed, and “/../
” elements are collapsed. The collapsing of /../
elements in the path occurs without regard to symbolic links. Therefore, it is possible that cleanpath
could take a valid path and return a shorter, invalid one.
For example, if str
were “/foo/../bar
” and /foo
were a symbolic link to /net/foo/export
, cleanpath
would return the string “/bar
” even though bar
might only be in /net/foo
not /
. This limitation is due to the fact that cleanpath
is called in the context of a firing probe, where full symbolic link resolution or arbitrary names is not possible. The returned string is allocated out of scratch memory, and is therefore valid only for the duration of the clause. If insufficient scratch space is available, cleanpath
does not execute and an error is generated.
void *copyin(uintptr_taddr
, size_tsize
)
copyin
copies the specified size in bytes from the specified user address into a DTrace scratch buffer, and returns the address of this buffer. The user address is interpreted as an address in the space of the process associated with the current thread. The resulting buffer pointer is guaranteed to have 8-byte alignment. The address in question must correspond to a faulted-in page in the current process. If the address does not correspond to a faulted-in page, or if insufficient scratch space is available, NULL
is returned, and an error is generated. See Chapter 33, User Process Tracing for techniques to reduce the likelihood of copyin
errors.
string copyinstr(uintptr_t addr
)
copyinstr
copies a null-terminated C string from the specified user address into a DTrace scratch buffer, and returns the address of this buffer. The user address is interpreted as an address in the space of the process associated with the current thread. The string length is limited to the value set by the strsize
option; see Chapter 16, Options and Tunables for details. As with copyin
, the specified address must correspond to a faulted-in page in the current process. If the address does not correspond to a faulted-in page, or if insufficient scratch space is available, NULL
is returned, and an error is generated. See Chapter 33, User Process Tracing for techniques to reduce the likelihood of copyinstr
errors.
void copyinto(uintptr_taddr
, size_tsize
, void *dest
)
copyinto
copies the specified size in bytes from the specified user address into the DTrace scratch buffer specified by dest
. The user address is interpreted as an address in the space of the process associated with the current thread. The address in question must correspond to a faulted-in page in the current process. If the address does not correspond to a faulted-in page, or if any of the destination memory lies outside scratch space, no copying takes place, and an error is generated. See Chapter 33, User Process Tracing for techniques to reduce the likelihood of copyinto
errors.
string dirname(char *str
)
dirname
is a D analogue for
dirname
(
1
)
. This subroutine creates a string that consists of all but the last level of the pathname specified by str
. The returned string is allocated out of scratch memory, and is therefore valid only for the duration of the clause. If insufficient scratch space is available, dirname
does not execute and an error is generated.
size_t msgdsize(mblk_t *mp
)
msgdsize
returns the number of bytes in the data message pointed to by mp
. See
msgdsize
(
9F
)
for details. msgdsize
only includes data blocks of type M_DATA
in the count.
size_t msgsize(mblk_t *mp
)
msgsize
returns the number of bytes in the message pointed to by mp
. Unlike msgdsize
, which returns only the number of data bytes, msgsize
returns the total number of bytes in the message.
int mutex_owned(kmutex_t *mutex
)
mutex_owned
is an implementation of
mutex_owned
(
9F
)
. mutex_owned
returns non-zero if the calling thread currently holds the specified kernel mutex, or zero if the specified adaptive mutex is currently unowned.
kthread_t *mutex_owner(kmutex_t *mutex
)
mutex_owner
returns the thread pointer of the current owner of the specified adaptive kernel mutex. mutex_owner
returns NULL
if the specified adaptive mutex is currently unowned, or if the specified mutex is a spin mutex. See
mutex_owned
(
9F
)
.
int mutex_type_adaptive(kmutex_t *mutex
)
mutex_type_adaptive
returns non-zero if the specified kernel mutex is of type MUTEX_ADAPTIVE
, or zero if it is not. Mutexes are adaptive if they meet one or more of the following conditions:
The mutex is declared statically
The mutex is created with an interrupt block cookie of NULL
The mutex is created with an interrupt block cookie that does not correspond to a high-level interrupt
See mutex_init ( 9F ) for more details on mutexes. The majority of mutexes in the Solaris kernel are adaptive.
int progenyof(pid_t pid
)
progenyof
returns non-zero if the calling process (the process associated with the thread that is currently triggering the matched probe) is among the progeny of the specified process ID.
int rand(void)
rand
returns a pseudo-random integer. The number returned is a weak pseudo-random number, and should not be used for any cryptographic application.
int rw_iswriter(krwlock_t *rwlock
)
rw_iswriter
returns non-zero if the specified reader-writer lock is either held or desired by a writer. If the lock is held only by readers and no writer is blocked, or if the lock is not held at all, rw_iswriter
returns zero. See
rw_init
(
9F
)
.
int rw_write_held(krwlock_t *rwlock
)
rw_write_held
returns non-zero if the specified reader-writer lock is currently held by a writer. If the lock is held only by readers or not held at all, rw_write_held
returns zero. See
rw_init
(
9F
)
.
int speculation(void)
speculation
reserves a speculative trace buffer for use with speculate
and returns an identifier for this buffer. See Chapter 13, Speculative Tracing for details.
string strjoin(char *str1
, char *str2
)
strjoin
creates a string that consists of str1
concatenated with str2
. The returned string is allocated out of scratch memory, and is therefore valid only for the duration of the clause. If insufficient scratch space is available, strjoin
does not execute and an error is generated.