'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2022 Tintri by DDN, Inc. All rights reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH STRING 9F "May 20, 2022"
.SH 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
.SH SYNOPSIS
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
.fi

.LP
.nf
\fBint\fR \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
.fi

.LP
.nf
\fBchar *\fR\fBstrcat\fR(\fBchar *\fR \fIs1\fR, \fBconst char *\fR \fIs2\fR);
.fi

.LP
.nf
\fBchar *\fR\fBstrncat\fR(\fBchar *\fR \fIs1\fR, \fBconst char *\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
.fi

.LP
.nf
\fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
.fi

.LP
.nf
\fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fIchr\fR);
.fi

.LP
.nf
\fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fIchr\fR);
.fi

.LP
.nf
\fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
.fi

.LP
.nf
\fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
.fi

.LP
.nf
\fBchar *\fR\fBstrcpy\fR(\fBchar *\fR \fIdst\fR, \fBconst char *\fR \fIsrc\fR);
.fi

.LP
.nf
\fBchar *\fR\fBstrncpy\fR(\fBchar *\fR \fIdst\fR, \fBconst char *\fR \fIsrc\fR, \fBsize_t\fR \fIn\fR);
.fi

.LP
.nf
\fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
.fi

.LP
.nf
\fBvoid\fR \fBstrfree\fR(\fBchar *\fR\fIs\fR);
.fi

.LP
.nf
\fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
.fi

.LP
.nf
\fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR);
.fi

.LP
.nf
\fBchar *\fR\fBddi_strdup\fR(\fBconst char *\fR\fIs1\fR, \fBint\fR \fIflag\fR);
.fi

.LP
.nf
\fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR);
.fi

.LP
.nf
\fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR);
.fi

.LP
.nf
\fBchar *\fR\fBstrtok_r\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBchar **\fR\fIlasts\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH DESCRIPTION
The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of
characters terminated by a null character). The \fBstrcat()\fR,
\fBstrncat()\fR, \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstrncpy()\fR,
\fBstrlcpy()\fR, \fBstrfree()\fR, and \fBstrtok_r()\R functions all alter their
first argument.
Additionally, the \fBstrcpy()\fR function does not check for overflow of the
array.
.SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR"
The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive
versions of  \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below.
They assume the \fBASCII\fR character set and ignore differences in case when
comparing lower and upper case characters.
.SS "\fBstrcat()\fR, \fBstrncat()\fR, and \fBstrlcat()\fR"
The \fBstrcat()\fR function appends a copy of string \fIs2\fR, including the
terminating null character, to the end of string \fIs1\fR. The \fBstrncat()\fR
function appends at most \fIn\fR characters of \fIs2\fR to \fIs1\fR, 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
\fIs2\fR overrides the null character at the end of \fIs1\fR. If copying takes
place between objects that overlap, the behavior of \fBstrcat()\fR,
\fBstrncat()\fR, and \fBstrlcat()\fR is undefined.
.sp
.LP
The \fBstrlcat()\fR function appends  at most
(\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR
(\fIdstsize\fR being the  size of the  string buffer \fIdst\fR). If the string
pointed to by \fIdst\fR contains a null-terminated string that fits into
\fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by
\fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes
(including the terminating null character) when it completes, and the initial
character of \fIsrc\fR will override the null character at  the end of
\fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR
bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will
not be changed. The function returns
\fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR).
Buffer overflow can be checked as  follows:
.sp
.in +2
.nf
if (strlcat(dst, src, dstsize) >= dstsize)
        return \(mi1;
.fi
.in -2

.SS "\fBstrchr()\fR, \fBstrrchr()\fR"
The \fBstrchr()\fR function returns a pointer to the first occurrence of
\fIc\fR (converted to a  \fBchar\fR) in string \fIs\fR, or a null pointer if
\fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a
pointer to the last occurrence of \fIc\fR. The null character terminating a
string is considered to be part of the string.
.SS "\fBstrcmp()\fR, \fBstrncmp()\fR"
The \fBstrcmp()\fR 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 \fIs1\fR
is greater than, equal to, or less than the string pointed to by \fIs2\fR
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 \fBstrncmp()\fR function makes the same comparison
but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not
compared.
.SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR"
The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the
terminating null character, stopping after the null character has been copied.
The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR
or adding null characters to \fIs1\fR if necessary. The result will not be
null-terminated if the length of \fIs2\fR is \fIn\fR or more. Both the
\fBstrcpy()\fR and \fBstrncpy()\fR functions return \fIs1\fR. If copying takes
place between objects that overlap, the behavior of \fBstrcpy()\fR,
\fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined.
.sp
.LP
The \fBstrlcpy()\fR function copies  at most \fIdstsize\fR\(mi1 characters
(\fIdstsize\fR being the  size of the  string buffer \fIdst\fR) from \fIsrc\fR
to \fIdst\fR,  truncating \fIsrc\fR if necessary.  The  result is always
null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow
can be checked as  follows:
.sp
.in +2
.nf
if (strlcpy(dst, src, dstsize) >= dstsize)
        return \(mi1;
.fi
.in -2

.SS "\fBstrfree()\fR"
The \fBstrfree()\fR function frees the memory associated with the string
pointed to by \fIs\fR.  This memory pointed to by \fIs\fR must be of size
\fBstrlen\fR(\fIs\fR)+1, and must have been allocated (either directly or
indirectly) by \fBkmem_alloc\fR(9F) or \fBkmem_zalloc\fR(9F).
.SS "\fBstrspn()\fR"
The \fBstrspn()\fR function returns the length of the initial segment of string
\fIs1\fR that consists entirely of characters from string \fIs2\fR.
.SS "\fBstrdup()\fR, \fBddi_strdup()\fR"
The \fBddi_strdup()\fR function returns a pointer to a new string that is a
duplicate of the string pointed to by \fIs1\fR. The returned pointer can be
passed to \fBstrfree()\fR or \fBkmem_free\fR(9F). The space for the new string
is obtained using \fBkmem_alloc()\fR. flag can be either \fBKM_SLEEP\fR or
\fBKM_NOSLEEP\fR, and determines whether the caller can sleep for memory.
\fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed.
\fBKM_NOSLEEP\fR allocations are guaranteed not to sleep but may fail (return
\fINULL\fR) if no memory is currently available.
.sp
.LP
The \fBstrdup()\fR function behaves the same as the \fBddi_strdup()\fR when
called with the \fBKM_SLEEP\fR flag. This means that \fBstrdup()\fR can sleep
until memory is available and will always succeed.
.SS "\fBstrlen()\fR, \fBstrnlen()\fR"
The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not
including the terminating null character.
.sp
.LP
The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of
bytes in \fIs\fR, not including the terminating null character. The
\fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string
pointed to by \fIs\fR.
.SS "\fBstrtok_r()\fR"
The \fBstrtok_r()\fR function considers the null-terminated string \fIs1\fR as
a sequence of zero or more text tokens separated by spans of one or more
characters from the separator string \fIs2\fR. The argument \fIlasts\fR points
to a user-provided pointer which points to stored information necessary for
\fBstrtok_r()\fR to continue scanning the same string.
.LP
In the first call to \fBstrtok_r()\fR, \fIs1\fR points to a null-terminated
string, \fIs2\fR to a null-terminated string of separator characters, and the
value pointed to by \fIlasts\fR is ignored. The \fBstrtok_r()\fR function
returns a pointer to the first character of the first token, writes a null
character into \fIs1\fR immediately following the returned token, and updates
the pointer to which \fIlasts\fR points.
.LP
In subsequent calls, \fIs1\fR is a null pointer and \fIlasts\fR is unchanged
from the previous call so that subsequent calls move through the string
\fIs1\fR, returning successive tokens until no tokens remain. The separator
string \fIs2\fR can be different from call to call. When no token remains in
\fIs1\fR, a null pointer is returned.
.SH CONTEXT
The \fBstrdup()\fR and \fBddi_strdup()\fR functions can be called from user or
kernel context.
.sp
.LP
The \fBddi_strdup()\fR function can be called from interrupt context only if
the \fBKM_NOSLEEP\fR flag is set.
.sp
.LP
All the other string manipulation functions can be called from user, interrupt,
or kernel context.
.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.BR string (3C),
.BR attributes (7),
.BR bcopy (9F),
.BR ddi_copyin (9F),
.BR kmem_alloc (9F)
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
If copying takes place between objects that overlap, the behavior of
\fBstrlcat()\fR, \fBstrncat()\fR, \fBstrcpy()\fR, \fBstrlcpy()\fR, and
\fBstrncpy()\fR is undefined.