4.6 Subroutines

4.6.1 alloca
4.6.2 basename
4.6.3 bcopy
4.6.4 cleanpath
4.6.5 copyin
4.6.6 copyinstr
4.6.7 copyinto
4.6.8 d_path
4.6.9 dirname
4.6.10 getmajor
4.6.11 getminor
4.6.12 htonl
4.6.13 htonll
4.6.14 htons
4.6.15 index
4.6.16 inet_ntoa
4.6.17 inet_ntoa6
4.6.18 inet_ntop
4.6.19 lltostr
4.6.20 mutex_owned
4.6.21 mutex_owner
4.6.22 mutex_type_adaptive
4.6.23 mutex_type_spin
4.6.24 ntohl
4.6.25 ntohll
4.6.26 ntohs
4.6.27 progenyof
4.6.28 rand
4.6.29 rindex
4.6.30 rw_iswriter
4.6.31 rw_read_held
4.6.32 rw_write_held
4.6.33 speculation
4.6.34 strchr
4.6.35 strjoin
4.6.36 strlen
4.6.37 strrchr
4.6.38 strstr
4.6.39 strtok
4.6.40 substr

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 application programming interfaces that are described in the section 3 manual pages.

4.6.1 alloca

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.

4.6.2 basename

string basename(char *str)

basename creates a string that consists of a copy of the specified string, but excluding any prefix that ends in /, such as a directory path. 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.

4.6.3 bcopy

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.

4.6.4 cleanpath

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 exist in /net/foo and not in /. 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.

4.6.5 copyin

void *copyin(uintptr_t addr, size_t size)

copyin copies the specified size in bytes from the specified user address addr 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.

4.6.6 copyinstr

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

copyinstr copies a null-terminated C string from the specified user address addr 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 maxlen parameter, if specified, sets a limit on the number of bytes past addr that are examined (the resulting string is always null-terminated). The resulting string's length is limited to the value set by the strsize option; see Chapter 10, 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.

4.6.7 copyinto

void copyinto(uintptr_t addr, size_t size, void *dest)

copyinto copies the specified size in bytes from the specified user address addr 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.

4.6.8 d_path

string d_path(struct path *ptr)

d_path creates a string that contains the absolute pathname of the struct path pointed to by ptr. 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, d_path does not execute and an error is generated.

4.6.9 dirname

string dirname(char *str)

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

4.6.10 getmajor

dev_t getmajor(dev_t dev)

getmajor returns the major device number for the device specified by dev.

4.6.11 getminor

dev_t getminor(dev_t dev)

getminor returns the minor device number for the device specified by dev.

4.6.12 htonl

uint32_t htonl(uint32_t hostlong)

htonl converts hostlong from host-byte order to network-byte order.

4.6.13 htonll

uint64_t htonll(uint64_t hostlonglong)

htonll converts hostlonglong from host-byte order to network-byte order.

4.6.14 htons

uint16_t htons(uint16_t hostshort)

htons converts hostshort from host-byte order to network-byte order.

4.6.15 index

int index(const char *s, const char *subs)
int index(const char *s, const char *subs, int start)

index locates the position of the first occurrence of the substring subs in the string s, starting at the optional position start. If the specified value of start is less than 0, it is implicitly set to 0. If s is an empty string, index returns 0. If no match is found for subs in s, index returns -1.

4.6.16 inet_ntoa

string inet_ntoa(ipaddr_t *addr)

inet_ntoa takes a pointer addr to an IPv4 address and returns it as a dotted quad decimal string. 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.

4.6.17 inet_ntoa6

string inet_ntoa6(in6_addr_t *addr)

inet_ntoa6 takes a pointer addr 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.

4.6.18 inet_ntop

string inet_ntop(int af, void *addr)

inet_ntop takes a pointer addr to an IP address and returns a string version depending on the provided address family. Supported address families are AF_INET and AF_INET6, both of which are 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.

4.6.19 lltostr

string lltostr(int64_t longlong)

lltostr converts longlong to a string. 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, lltostr does not execute and an error is generated.

4.6.20 mutex_owned

int mutex_owned(kmutex_t *mutex)

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.

4.6.21 mutex_owner

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.

4.6.22 mutex_type_adaptive

int mutex_type_adaptive(kmutex_t *mutex)

All mutexes in the Oracle Linux kernel are adaptive, so this function always returns 1.

4.6.23 mutex_type_spin

int mutex_type_spin(kmutex_t *mutex)

All mutexes in the Oracle Linux kernel are adaptive, so this function always returns 0.

4.6.24 ntohl

uint32_t ntohl(uint32_t netlong)

ntohl converts netlong from host-byte order to network-byte order.

4.6.25 ntohll

uint64_t ntohll(uint64_t netlonglong)

ntohll converts nestlonglong from host-byte order to network-byte order.

4.6.26 ntohs

uint16_t ntohs(uint16_t netshort)

ntohs converts netshort from host-byte order to network-byte order.

4.6.27 progenyof

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

4.6.28 rand

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.

4.6.29 rindex

int rindex(const char *s, const char *subs)
int rindex(const char *s, const char *subs, int start)

rindex locates the position of the last occurrence of the substring subs in the string s, starting at the optional position start. If the specified value of start is less than 0, it is implicitly set to 0. If s is an empty string, rindex returns 0. If no match is found for subs in s, rindex returns -1.

4.6.30 rw_iswriter

int rw_iswriter(krwlock_t *rwlock)

rw_iswriter returns non-zero if the specified reader-writer lock rwlock is held by a writer. If the lock is desired by a writer, is held only by readers and no writer is blocked, or if the lock is not held at all, rw_iswriter returns zero.

4.6.31 rw_read_held

int rw_read_held(krwlock_t *rwlock)

rw_read_held returns non-zero if the specified reader-writer lock rwlock is currently held by a reader. If the lock is held only by writers or is not held at all, rw_read_held returns zero.

4.6.32 rw_write_held

int rw_write_held(krwlock_t *rwlock)

rw_write_held returns non-zero if the specified reader-writer lock rwlock is currently held by a writer. If the lock is held only by readers or is not held at all, rw_write_held returns zero.

4.6.33 speculation

int speculation(void)

speculation reserves a speculative trace buffer for use with speculate and returns an identifier for this buffer. See Chapter 7, Speculative Tracing for details.

4.6.34 strchr

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, strstr returns 0. This function does not work with wide or multi-byte characters.

4.6.35 strjoin

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.

4.6.36 strlen

size_t strlen(string str)

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

4.6.37 strrchr

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, strrstr returns 0. This function does not work with wide or multi-byte characters.

4.6.38 strstr

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.

4.6.39 strtok

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

strtok parses a string into a sequence of tokens 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 enablings of the same probe. That is, it behaves like an implicit clause-local variable. strtok returns NULL if there are no more tokens.

4.6.40 substr

string substr(const char *s, int index)
string substr(const char *s, int index, int length)

substr returns the substring of the string s starting at the position index. If length is specified, substr limits the substring to that length.