Tribblix: manual page: string.9f

STRING(9F) Kernel Functions for Drivers STRING(9F)

NAME

string, strcasecmp, strncasecmp, strcat, strncat, strlcat, strchr,
strrchr, strcmp, strncmp, strcpy, strncpy, strlcpy, strfree, strspn,
strdup, ddi_strdup, strlen, strnlen, strtok_r - string operations

SYNOPSIS

#include <sys/ddi.h>
#include <sys/sunddi.h>

int strcasecmp(const char *s1, const char *s2);

int strncasecmp(const char *s1, const char *s2, size_t n);

char *strcat(char * s1, const char * s2);

char *strncat(char * s1, const char * s2, size_t n);

size_t strlcat(char *dst, const char *src, size_t dstsize);

char *strchr(const char *str, int chr);

char *strrchr(const char *str, int chr);

int strcmp(const char *s1, const char *s2);

int strncmp(const char *s1, const char *s2, size_t n);

char *strcpy(char * dst, const char * src);

char *strncpy(char * dst, const char * src, size_t n);

size_t strlcpy(char *dst, const char *src, size_t dstsize);

void strfree(char *s);

size_t strspn(const char *s1, const char *s2);

char *strdup(const char *s1);

char *ddi_strdup(const char *s1, int flag);

size_t strlen(const char *s);

size_t strnlen(const char *s, size_t n);

char *strtok_r(char *s1, const char *s2, char **lasts);

INTERFACE LEVEL

illumos DDI specific (illumos DDI).

DESCRIPTION

The arguments s, s1, and s2 point to strings (arrays of characters
terminated by a null character). The strcat(), strncat(), strlcat(),
strcpy(), strncpy(), strlcpy(), strfree(), and strtok_r()all alter
their first argument. Additionally, the strcpy() function does not
check for overflow of the array.

strcasecmp(), strncasecmp()
The strcasecmp() and strncasecmp() functions are case-insensitive
versions of strcmp() and strncmp() respectively, described below.
They assume the ASCII character set and ignore differences in case
when comparing lower and upper case characters.

strcat(), strncat(), and strlcat()
The strcat() function appends a copy of string s2, including the
terminating null character, to the end of string s1. The strncat()
function appends at most n characters of s2 to s1, not including any
terminating null character, and then appends a null character. Each
returns a pointer to the null-terminated result. The initial
character of s2 overrides the null character at the end of s1. If
copying takes place between objects that overlap, the behavior of
strcat(), strncat(), and strlcat() is undefined.

The strlcat() function appends at most (dstsize-strlen(dst)-1)
characters of src to dst (dstsize being the size of the string
buffer dst). If the string pointed to by dst contains a null-
terminated string that fits into dstsize bytes when strlcat() is
called, the string pointed to by dst will be a null-terminated string
that fits in dstsize bytes (including the terminating null character)
when it completes, and the initial character of src will override the
null character at the end of dst. If the string pointed to by dst is
longer than dstsize bytes when strlcat() is called, the string
pointed to by dst will not be changed. The function returns
min{dstsize,strlen(dst)}+strlen(src). Buffer overflow can be checked
as follows:

if (strlcat(dst, src, dstsize) >= dstsize)
return -1;

strchr(), strrchr()
The strchr() function returns a pointer to the first occurrence of c
(converted to a char) in string s, or a null pointer if c does not
occur in the string. The strrchr() function returns a pointer to the
last occurrence of c. The null character terminating a string is
considered to be part of the string.

strcmp(), strncmp()
The strcmp() function compares two strings byte-by-byte, according to
the ordering of your machine's character set. The function returns
an integer greater than, equal to, or less than 0, if the string
pointed to by s1 is greater than, equal to, or less than the string
pointed to by s2 respectively. The sign of a non-zero return value is
determined by the sign of the difference between the values of the
first pair of bytes that differ in the strings being compared. The
strncmp() function makes the same comparison but looks at a maximum
of n bytes. Bytes following a null byte are not compared.

strcpy(), strncpy(), strlcpy()
The strcpy() function copies string s2 to s1, including the
terminating null character, stopping after the null character has
been copied. The strncpy() function copies exactly n bytes,
truncating s2 or adding null characters to s1 if necessary. The
result will not be null-terminated if the length of s2 is n or more.
Both the strcpy() and strncpy() functions return s1. If copying takes
place between objects that overlap, the behavior of strcpy(),
strncpy(), and strlcpy() is undefined.

The strlcpy() function copies at most dstsize-1 characters (dstsize
being the size of the string buffer dst) from src to dst,
truncating src if necessary. The result is always null-terminated.
The function returns strlen(src). Buffer overflow can be checked as
follows:

if (strlcpy(dst, src, dstsize) >= dstsize)
return -1;

strfree()
The strfree() function frees the memory associated with the string
pointed to by s. This memory pointed to by s must be of size
strlen(s)+1, and must have been allocated (either directly or
indirectly) by kmem_alloc(9F) or kmem_zalloc(9F).

strspn()
The strspn() function returns the length of the initial segment of
string s1 that consists entirely of characters from string s2.

strdup(), ddi_strdup()
The ddi_strdup() function returns a pointer to a new string that is a
duplicate of the string pointed to by s1. The returned pointer can be
passed to strfree() or kmem_free(9F). The space for the new string is
obtained using kmem_alloc(). flag can be either KM_SLEEP or
KM_NOSLEEP, and determines whether the caller can sleep for memory.
KM_SLEEP allocations may sleep but are guaranteed to succeed.
KM_NOSLEEP allocations are guaranteed not to sleep but may fail
(return NULL) if no memory is currently available.

The strdup() function behaves the same as the ddi_strdup() when
called with the KM_SLEEP flag. This means that strdup() can sleep
until memory is available and will always succeed.

strlen(), strnlen()
The strlen() function returns the number of bytes in s, not including
the terminating null character.

The strnlen() function returns the smaller of n or the number of
bytes in s, not including the terminating null character. The
strnlen() function never examines more than n bytes of the string
pointed to by s.

strtok_r()
The strtok_r() function considers the null-terminated string s1 as a
sequence of zero or more text tokens separated by spans of one or
more characters from the separator string s2. The argument lasts
points to a user-provided pointer which points to stored information
necessary for strtok_r() to continue scanning the same string.

In the first call to strtok_r(), s1 points to a null-terminated
string, s2 to a null-terminated string of separator characters, and
the value pointed to by lasts is ignored. The strtok_r() function
returns a pointer to the first character of the first token, writes a
null character into s1 immediately following the returned token, and
updates the pointer to which lasts points.

In subsequent calls, s1 is a null pointer and lasts is unchanged from
the previous call so that subsequent calls move through the string
s1, returning successive tokens until no tokens remain. The separator
string s2 can be different from call to call. When no token remains
in s1, a null pointer is returned.

CONTEXT

The strdup() and ddi_strdup() functions can be called from user or
kernel context.

The ddi_strdup() function can be called from interrupt context only
if the KM_NOSLEEP flag is set.

All the other string manipulation functions can be called from user,
interrupt, or kernel context.

ATTRIBUTES

NOTES

If copying takes place between objects that overlap, the behavior of
strlcat(), strncat(), strcpy(), strlcpy(), and strncpy() is
undefined.

May 20, 2022 STRING(9F)