Print this page
Garrett's man page edits.

*** 1,6 **** --- 1,7 ---- '\" te + .\" Copyright 2014 Garrett D'Amore <garrett@damore.org> .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 1989 AT&T .\" Portions Copyright (c) 1994 Man-cgi 1.15, Panagiotis Christias (christia@softlab.ntua.gr) .\" Portions Copyright (c) 1996-2008 Modified for NetBSD by Kimmo Suominen (kimmo@suominen.com) .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
*** 9,196 **** .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. .\" This notice shall appear on any product containing this material. .\" 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 3C "Jun 19, 2013" .SH NAME ! string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat, strncat, strlcat, strchr, strrchr, strcmp, strncmp, strcpy, strncpy, strlcpy, strcspn, strspn, strdup, strlen, strnlen, strpbrk, strsep, strstr, strtok, strtok_r \- string operations .SH SYNOPSIS .LP .nf #include <strings.h> \fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi - .LP .nf \fBint\fR \fBstrcasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBlocale_t\fR \fIloc\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 \fBint\fR \fBstrncasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR, \fBlocale_t\fR \fIloc\fR); .fi - .LP .nf #include <string.h> \fBchar *\fR\fBstrcat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); .fi - .LP .nf \fBchar *\fR\fBstrncat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\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\fIs\fR, \fBint\fR \fIc\fR); .fi - .LP .nf \fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\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 *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); .fi - .LP .nf \fBchar *\fR\fBstrncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\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 \fBsize_t\fR \fBstrcspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\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 \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\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi - .LP .nf \fBchar *\fR\fBstrsep\fR(\fBchar **\fR\fIstringp\fR, \fBconst char *\fR\fIdelim\fR); .fi - .LP .nf \fBchar *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi - .LP .nf \fBchar *\fR\fBstrtok\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); .fi - .LP .nf \fBchar *\fR\fBstrtok_r\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBchar **restrict\fR \fIlasts\fR); .fi - .SS "ISO C++" .LP .nf #include <string.h> \fBconst char *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); .fi - .LP .nf \fBconst char *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi - .LP .nf \fBconst char *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); .fi - .LP .nf \fBconst char *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi - .LP .nf #include <cstring> \fBchar *std::\fR\fBstrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR); .fi - .LP .nf \fBchar *std::\fR\fBstrpbrk\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi - .LP .nf \fBchar *std::\fR\fBstrrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR); .fi - .LP .nf \fBchar *std::\fR\fBstrstr\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi - .SH DESCRIPTION - .sp .LP 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, \fBstrsep()\fR, \fBstrtok()\fR, and \fBstrtok_r()\fR functions --- 10,165 ---- .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. .\" This notice shall appear on any product containing this material. .\" 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 3C "Jun 21, 2013" .SH NAME ! string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat, strncat, ! strlcat, strchr, strrchr, strcmp, strncmp, strcpy, strncpy, strlcpy, strcspn, strspn, strdup, strlen, strnlen, strpbrk, strsep, strstr, strtok, strtok_r \- string operations .SH SYNOPSIS .LP .nf #include <strings.h> \fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi .LP .nf \fBint\fR \fBstrcasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBlocale_t\fR \fIloc\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 \fBint\fR \fBstrncasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR, \fBlocale_t\fR \fIloc\fR); .fi .LP .nf #include <string.h> \fBchar *\fR\fBstrcat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); .fi .LP .nf \fBchar *\fR\fBstrncat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\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\fIs\fR, \fBint\fR \fIc\fR); .fi .LP .nf \fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\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 *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); .fi .LP .nf \fBchar *\fR\fBstrncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\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 \fBsize_t\fR \fBstrcspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\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 \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\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi .LP .nf \fBchar *\fR\fBstrsep\fR(\fBchar **\fR\fIstringp\fR, \fBconst char *\fR\fIdelim\fR); .fi .LP .nf \fBchar *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi .LP .nf \fBchar *\fR\fBstrtok\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR); .fi .LP .nf \fBchar *\fR\fBstrtok_r\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBchar **restrict\fR \fIlasts\fR); .fi .SS "ISO C++" .LP .nf #include <string.h> \fBconst char *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); .fi .LP .nf \fBconst char *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi .LP .nf \fBconst char *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR); .fi .LP .nf \fBconst char *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi .LP .nf #include <cstring> \fBchar *std::\fR\fBstrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR); .fi .LP .nf \fBchar *std::\fR\fBstrpbrk\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi .LP .nf \fBchar *std::\fR\fBstrrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR); .fi .LP .nf \fBchar *std::\fR\fBstrstr\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); .fi .SH DESCRIPTION .LP 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, \fBstrsep()\fR, \fBstrtok()\fR, and \fBstrtok_r()\fR functions
*** 199,227 **** .SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR" .sp .LP 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 "\fBstrcasecmp_l()\fR, \fBstrncasecmp_l()\fR" - .sp .LP The \fBstrcasecmp_l()\fR and \fBstrncasecmp_l()\fR functions behave identically to \fBstrcasecmp()\fR and \fBstrncasecmp()\fR, except instead of operating in the current locale, they instead operate in the locale specified by \fIloc\fR. .SS "\fBstrcat()\fR, \fBstrncat()\fR, \fBstrlcat()\fR" - .sp .LP 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. 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 --- 168,206 ---- .SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR" .sp .LP The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive versions of \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below. ! .LP ! The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions compare two strings ! byte-by-byte, after ! converting each upper-case character to lower-case (as determined by the ! \fBLC_CTYPE\fR category of the current locale). Note that neither the contents ! pointed to by \fIs1\fR nor \fIs2\fR are modified. ! .LP ! The functions return 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 ! .LP ! The \fBstrncasecmp()\fR function examines at most \fIn\fR bytes from each ! string. .SS "\fBstrcasecmp_l()\fR, \fBstrncasecmp_l()\fR" .LP The \fBstrcasecmp_l()\fR and \fBstrncasecmp_l()\fR functions behave identically to \fBstrcasecmp()\fR and \fBstrncasecmp()\fR, except instead of operating in the current locale, they instead operate in the locale specified by \fIloc\fR. .SS "\fBstrcat()\fR, \fBstrncat()\fR, \fBstrlcat()\fR" .LP 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. 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. .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
*** 239,259 **** .nf if (strlcat(dst, src, dstsize) >= dstsize) return \(mi1; .fi .in -2 - .SS "\fBstrchr()\fR, \fBstrrchr()\fR" - .sp .LP 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" - .sp .LP 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 --- 218,235 ----
*** 261,280 **** 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" - .sp .LP 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. Each function returns \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 --- 237,254 ----
*** 286,416 **** return \(mi1; .fi .in -2 .SS "\fBstrcspn()\fR, \fBstrspn()\fR" - .sp .LP The \fBstrcspn()\fR function returns the length of the initial segment of string \fIs1\fR that consists entirely of characters not from string \fIs2\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" - .sp .LP The \fBstrdup()\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 \fBfree()\fR. The space for the new string is obtained using \fBmalloc\fR(3C). If the new string cannot be created, a null pointer is returned and \fBerrno\fR may be set to \fBENOMEM\fR to indicate that the storage space available is insufficient. .SS "\fBstrlen()\fR, \fBstrnlen()\fR" .sp - .LP 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 "\fBstrpbrk()\fR" - .sp .LP The \fBstrpbrk()\fR function returns a pointer to the first occurrence in string \fIs1\fR of any character from string \fIs2\fR, or a null pointer if no character from \fIs2\fR exists in \fIs1\fR. .SS "\fBstrsep()\fR" - .sp .LP The \fBstrsep()\fR function locates, in the null-terminated string referenced by *\fIstringp\fR, the first occurrence of any character in the string \fIdelim\fR (or the terminating `\e0' character) and replaces it with a `\e0'. The location of the next character after the delimiter character (or \fINULL\fR, if the end of the string was reached) is stored in *\fIstringp\fR. The original value of *\fIstringp\fR is returned. - .sp .LP An ``empty'' field (one caused by two adjacent delimiter characters) can be detected by comparing the location referenced by the pointer returned by \fBstrsep()\fR to `\e0'. - .sp .LP If *\fIstringp\fR is initially \fINULL\fR, \fBstrsep()\fR returns \fINULL\fR. .SS "\fBstrstr()\fR" - .sp .LP The \fBstrstr()\fR function locates the first occurrence of the string \fIs2\fR (excluding the terminating null character) in string \fIs1\fR and returns a pointer to the located string, or a null pointer if the string is not found. If \fIs2\fR points to a string with zero length (that is, the string \fB""\fR), the function returns \fIs1\fR. .SS "\fBstrtok()\fR" - .sp .LP A sequence of calls to \fBstrtok()\fR breaks the string pointed to by \fIs1\fR into a sequence of tokens, each of which is delimited by a byte from the string pointed to by \fIs2\fR. The first call in the sequence has \fIs1\fR as its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by \fIs2\fR can be different from call to call. - .sp .LP The first call in the sequence searches the string pointed to by \fIs1\fR for the first byte that is not contained in the current separator string pointed to by \fIs2\fR. If no such byte is found, then there are no tokens in the string pointed to by \fIs1\fR and \fBstrtok()\fR returns a null pointer. If such a byte is found, it is the start of the first token. - .sp .LP The \fBstrtok()\fR function then searches from there for a byte that is contained in the current separator string. If no such byte is found, the current token extends to the end of the string pointed to by \fIs1\fR, and subsequent searches for a token return a null pointer. If such a byte is found, it is overwritten by a null byte that terminates the current token. The \fBstrtok()\fR function saves a pointer to the following byte in thread-specific data, from which the next search for a token starts. - .sp .LP Each subsequent call, with a null pointer as the value of the first argument, starts searching from the saved pointer and behaves as described above. - .sp .LP See Example 1, 2, and 3 in the \fBEXAMPLES\fR section for examples of \fBstrtok()\fR usage and the explanation in \fBNOTES\fR. .SS "\fBstrtok_r()\fR" - .sp .LP 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. - .sp .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. - .sp .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. - .sp .LP See Example 3 in the \fBEXAMPLES\fR section for an example of \fBstrtok_r()\fR usage and the explanation in \fBNOTES\fR. .SH EXAMPLES .LP \fBExample 1 \fRSearch for word separators. - .sp .LP The following example searches for tokens separated by space characters. .sp .in +2 --- 260,371 ----
*** 429,439 **** .fi .in -2 .LP \fBExample 2 \fRBreak a Line. - .sp .LP The following example uses strtok to break a line into two character strings separated by any combination of SPACEs, TABs, or NEWLINEs. .sp --- 384,393 ----
*** 454,464 **** .fi .in -2 .LP \fBExample 3 \fRSearch for tokens. - .sp .LP The following example uses both \fBstrtok()\fR and \fBstrtok_r()\fR to search for tokens separated by one or more characters from the string pointed to by the second argument, "/". --- 408,417 ----
*** 493,503 **** } } .fi .in -2 - .sp .LP When compiled and run, this example produces the following output: .sp .in +2 --- 446,455 ----
*** 513,577 **** token = "45" .fi .in -2 .SH ATTRIBUTES - .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: - .sp - - .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ ! Interface Stability Committed _ MT-Level See below. _ Standard See below. .TE - .sp .LP The \fBstrtok()\fR and \fBstrdup()\fR functions are MT-Safe. The remaining functions are Async-Signal-Safe. - .sp .LP For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see \fBstandards\fR(5). .SH SEE ALSO - .sp .LP ! \fBmalloc\fR(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C), \fBattributes\fR(5), ! \fBstandards\fR(5) .SH NOTES - .sp .LP When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be defined on the compile line. This flag should only be used in multithreaded applications. - .sp .LP A single-threaded application can gain access to \fBstrtok_r()\fR only by defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value greater than or equal to 199506L. - .sp .LP ! All of these functions assume the default locale ``C.'' For some locales, \fBstrxfrm\fR(3C) should be applied to the strings before they are passed to the functions. - .sp .LP The \fBstrtok()\fR function is safe to use in multithreaded applications because it saves its internal state in a thread-specific data area. However, its use is discouraged, even for single-threaded applications. The \fBstrtok_r()\fR function should be used instead. - .sp .LP Do not pass the address of a character string literal as the argument \fIs1\fR to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer to the address of a character string literal as the argument \fIstringp\fR to \fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR --- 465,523 ---- token = "45" .fi .in -2 .SH ATTRIBUTES .LP See \fBattributes\fR(5) for descriptions of the following attributes: .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ ! Interface Stability See below. _ MT-Level See below. _ Standard See below. .TE .LP + The + \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR functions are Committed. + All the rest are Standard. + .LP The \fBstrtok()\fR and \fBstrdup()\fR functions are MT-Safe. The remaining functions are Async-Signal-Safe. .LP For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see \fBstandards\fR(5). .SH SEE ALSO .LP ! \fBmalloc\fR(3C), ! \fBnewlocale(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C), \fBuselocale\fR(3C), ! \fBattributes\fR(5), \fBstandards\fR(5) .SH NOTES .LP When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be defined on the compile line. This flag should only be used in multithreaded applications. .LP A single-threaded application can gain access to \fBstrtok_r()\fR only by defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value greater than or equal to 199506L. .LP ! Except where noted otherwise, all of these functions assume the default ! locale ``C.'' For some locales, \fBstrxfrm\fR(3C) should be applied to the strings before they are passed to the functions. .LP The \fBstrtok()\fR function is safe to use in multithreaded applications because it saves its internal state in a thread-specific data area. However, its use is discouraged, even for single-threaded applications. The \fBstrtok_r()\fR function should be used instead. .LP Do not pass the address of a character string literal as the argument \fIs1\fR to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer to the address of a character string literal as the argument \fIstringp\fR to \fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR