Go to main content

Oracle® Solaris 11.4 DTrace (Dynamic Tracing) Guide

Exit Print View

Updated: September 2020
 
 

DTrace Subroutines

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. For more information, see Intro(9F) and intro(3) man pages.

alloca Subroutine

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.

basename Subroutine

string basename(char *str)

basename is a D analog 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.

bcopy Subroutine

void bcopy(void *src, void *dest, size_t size)

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.

cleanpath Subroutine

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 of 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.

copyin Subroutine

void *copyin(uintptr_t addr, size_t size)

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. For information about techniques to reduce the likelihood of copyin errors, see User Process Tracing.

copyinstr Subroutine

string copyinstr(uintptr_t addr)
string copyinstr(uintptr_t addr, size_t maxlength)

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 maxlength parameter, if specified, sets a limit on the number of bytes past addr which will be examined (the resulting string will always be null-terminated). The resulting string's length is limited to the value set by the strsize option; see DTrace 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 User Process Tracing for techniques to reduce the likelihood of copyinstr errors.

copyinto Subroutine

void copyinto(uintptr_t addr, size_t size, 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 User Process Tracing for techniques to reduce the likelihood of copyinto errors.

dirname Subroutine

string dirname(char *str)

dirname is a D analog for dirname(1). This subroutine creates a string that consists of all but the last level of the path name 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.

inet_ntoa Subroutine

string inet_ntoa(ipaddr_t *addr)

inet_ntoa takes a pointer to an IPv4 address and returns it as a dotted quad decimal string. This is similar to inet_ntoa() from libnsl as described in inet(3C), however this D version takes a pointer to the IPv4 address rather than the address itself. 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, inet_ntoa does not execute and an error is generated.

inet_ntoa6 Subroutine

string inet_ntoa6(in6_addr_t *addr)

inet_ntoa6 takes a pointer to an IPv6 address and returns it as an RFC 1884 convention 2 string, with lower case hexadecimal digits. 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, inet_ntoa6 does not execute and an error is generated.

inet_ntop Subroutine

string inet_ntop(int af, void *addr)

inet_ntop takes a pointer to an IP address and returns a string version depending on the provided address family. This is similar to inet_ntop from libnsl as described in inet(3C). Supported address families are AF_INET and AF_INET6, both of which have been defined for use in D programs. 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, inet_ntop does not execute and an error is generated.

msgdsize Subroutine

size_t msgdsize(mblk_t *mp)

msgdsize returns the number of bytes in the data message pointed to by mp. msgdsize only includes data blocks of type M_DATA in the count. For more information, see msgdsize(9F).

msgsize Subroutine

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.

mutex_owned Subroutine

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 returns zero if the specified adaptive mutex is currently unowned.

mutex_owner Subroutine

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. For more information, see mutex_owned(9F).

mutex_type_adaptive Subroutine

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.

For more information about mutexes, see mutex_init(9F). The majority of mutexes in the Oracle Solaris kernel are adaptive.

progenyof Subroutine

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.

rand Subroutine

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.

rw_iswriter Subroutine

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).

rw_write_held Subroutine

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).

speculation Subroutine

int speculation(void)

speculation reserves a speculative trace buffer for use with speculate and returns an identifier for this buffer. For information, see Speculative Tracing in DTrace.

strchr Subroutine

string strchr(const char *s, char c)

strchr returns a pointer to the first occurrence of the character c in the string s. If no match is found, strchr returns 0. This function does not work with wide or multi-byte characters.

strjoin Subroutine

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.

strlen Subroutine

size_t strlen(string str)

strlen returns the length of the specified string in bytes, excluding the terminating null byte.

strrchr Subroutine

string strrchr(const char *s, char c)

strrchr returns a pointer to the last occurrence of the character c in the string s. If no match is found, strrchr returns 0. This function does not work with wide or multi-byte characters.

strstr Subroutine

string strstr(const char *s, const char *subs)

strstr returns a pointer to the first occurrence of the substring subs in the string s. If s is an empty string, strstr returns a pointer to an empty string. If no match is found, strstr returns 0.

strtok Subroutine

string strtok(const char *s, const char *delim)

strtok parses a string into a sequence of tokens by using delim as the delimiting string . When you first call strtok, specify the string to be parsed in s. In each subsequent call to obtain the next token, specify str as NULL. You can specify a different delimiter for each call. The internal pointer that strtok uses to traverse s is only valid within multiple calls to the same probe. That is, it behaves like an implicit clause-local variable. strtok returns NULL if there are no more tokens.