Standard C Library Functions string(3C)
NAME
string, strcasecmp, strncasecmp, strcat, strncat, strlcat,
strchr, strrchr, strcmp, strncmp, strcpy, strncpy, strlcpy,
strcspn, strspn, strdup, strlen, strnlen, strpbrk, strsep,
strstr, strtok, strtokr - string operations
SYNOPSIS
#include
int strcasecmp(const char *s1, const char *s2);
int strncasecmp(const char *s1, const char *s2, sizet n);
#include
char *strcat(char *restrict s1, const char *restrict s2);
char *strncat(char *restrict s1, const char *restrict s2, sizet n);
sizet strlcat(char *dst, const char *src, sizet dstsize);
char *strchr(const char *s, int c);
char *strrchr(const char *s, int c);
int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, sizet n);
char *strcpy(char *restrict s1, const char *restrict s2);
char *strncpy(char *restrict s1, const char *restrict s2, sizet n);
sizet strlcpy(char *dst, const char *src, sizet dstsize);
sizet strcspn(const char *s1, const char *s2);
sizet strspn(const char *s1, const char *s2);
SunOS 5.11 Last change: 1 Aug 2008 1
Standard C Library Functions string(3C)
char *strdup(const char *s1);
sizet strlen(const char *s);
sizet strnlen(const char *s, sizet n);
char *strpbrk(const char *s1, const char *s2);
char *strsep(char **stringp, const char *delim);
char *strstr(const char *s1, const char *s2);
char *strtok(char *restrict s1, const char *restrict s2);
char *strtokr(char *s1, const char *s2, char **lasts);
ISO C]
#include
const char *strchr(const char *s, int c);
const char *strpbrk(const char *s1, const char *s2);
const char *strrchr(const char *s, int c);
const char *strstr(const char *s1, const char *s2);
#include
char *std::strchr(char *s, int c);
char *std::strpbrk(char *s1, const char *s2);
char *std::strrchr(char *s, int c);
char *std::strstr(char *s1, const char *s2);
SunOS 5.11 Last change: 1 Aug 2008 2
Standard C Library Functions string(3C)
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(),
strsep(), strtok(), and strtokr() functions all alter their
first argument. Additionally, the strcat() and strcpy()
functions do not check for overflow of the array.
strcasecmp(), strncasecmp()
The strcasecmp() and strncasecmp() functions are case-
insensitive versions of strcmp() and strncmp() respec-
tively, described below. They assume the ASCI character
set and ignore differences in case when comparing lower and
upper case characters.
strcat(), strncat(), 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. 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 com-
pletes, 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.
SunOS 5.11 Last change: 1 Aug 2008 3
Standard C Library Functions string(3C)
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 deter-
mined 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 charac-
ter 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. Each function returns 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;
strcspn(), strspn()
The strcspn() function returns the length of the initial
segment of string s1 that consists entirely of characters
not from string s2. The strspn() function returns the length
of the initial segment of string s1 that consists entirely
of characters from string s2.
strdup()
The 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 free(). The space for the new
string is obtained using malloc(3C). If the new string can-
not be created, a null pointer is returned and errno may be
set to ENOMEM to indicate that the storage space available
is insufficient.
strlen(), strnlen()
SunOS 5.11 Last change: 1 Aug 2008 4
Standard C Library Functions string(3C)
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.
strpbrk()
The strpbrk() function returns a pointer to the first
occurrence in string s1 of any character from string s2, or
a null pointer if no character from s2 exists in s1.
strsep()
The strsep() function locates, in the null-terminated string
referenced by *stringp, the first occurrence of any charac-
ter in the string delim (or the terminating `\0' character)
and replaces it with a `\0'. The location of the next char-
acter after the delimiter character (or NUL, if the end of
the string was reached) is stored in *stringp. The original
value of *stringp is returned.
An ``empty'' field (one caused by two adjacent delimiter
characters) can be detected by comparing the location refer-
enced by the pointer returned by strsep() to `\0'.
If *stringp is initially NUL, strsep() returns NUL.
strstr()
The strstr() function locates the first occurrence of the
string s2 (excluding the terminating null character) in
string s1 and returns a pointer to the located string, or a
null pointer if the string is not found. If s2 points to a
string with zero length (that is, the string ""), the func-
tion returns s1.
strtok()
A sequence of calls to strtok() breaks the string pointed to
by s1 into a sequence of tokens, each of which is delimited
by a byte from the string pointed to by s2. The first call
in the sequence has s1 as its first argument, and is fol-
lowed by calls with a null pointer as their first argument.
The separator string pointed to by s2 can be different from
call to call.
The first call in the sequence searches the string pointed
to by s1 for the first byte that is not contained in the
current separator string pointed to by s2. If no such byte
SunOS 5.11 Last change: 1 Aug 2008 5
Standard C Library Functions string(3C)
is found, then there are no tokens in the string pointed to
by s1 and strtok() returns a null pointer. If such a byte is
found, it is the start of the first token.
The strtok() 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 s1, 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 strtok() function saves a pointer to the follow-
ing byte in thread-specific data, from which the next search
for a token starts.
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.
See Example 1, 2, and 3 in the EXAMPLES section for examples
of strtok() usage and the explanation in NOTES.
strtokr()
The strtokr() 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 strtokr()
to continue scanning the same string.
In the first call to strtokr(), s1 points to a null-
terminated string, s2 to a null-terminated string of separa-
tor characters, and the value pointed to by lasts is
ignored. The strtokr() 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 dif-
ferent from call to call. When no token remains in s1, a
null pointer is returned.
See Example 3 in the EXAMPLES section for an example of
strtokr() usage and the explanation in NOTES.
SunOS 5.11 Last change: 1 Aug 2008 6
Standard C Library Functions string(3C)
EXAMPLES
Example 1 Search for word separators.
The following example searches for tokens separated by space
characters.
#include
...
char *token;
char line[] = "LINE TO BE SEPARATED";
char *search = " ";
/* Token will point to "LINE". */
token = strtok(line, search);
/* Token will point to "TO". */
token = strtok(NUL, search);
Example 2 Break a Line.
The following example uses strtok to break a line into two
character strings separated by any combination of SPACEs,
TABs, or NEWLINEs.
#include
...
struct element {
char *key;
char *data;
};
...
char line[LINEMAX];
char *key, *data;
...
key = strtok(line, " \n");
data = strtok(NUL, " \n");
Example 3 Search for tokens.
The following example uses both strtok() and strtokr() to
search for tokens separated by one or more characters from
the string pointed to by the second argument, "/".
#define EXTENSIONS
SunOS 5.11 Last change: 1 Aug 2008 7
Standard C Library Functions string(3C)
#include
#include
int
main() {
char *buf="5/90/45";
char *token;
char *lasts;
printf("tokenizing \"%s\" with strtok():\n", buf);
if ((token = strtok(buf, "/")) != NUL) {
printf("token = "%s\"\n", token);
while ((token = strtok(NUL, "/")) != NUL) {
printf("token = \"%s\"\n", token);
}
}
buf = "/5/90/45/";
printf("\ntokenizing \"%s\" with strtokr():\n", buf);
if ((token = strtokr(buf, "/", &lasts)) != NUL) {
printf("token = \"%s\"\n", token);
while ((token = strtokr(NUL, "/", &lasts)) != NUL) {
printf("token = \"%s\"\n", token);
}
}
}
When compiled and run, this example produces the following
output:
tokenizing "5/90/45" with strtok():
token = "5"
token = "90"
token = "45"
tokenizing "/5/90/45/" with strtokr():
token = "5"
token = "90"
token = "45"
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 1 Aug 2008 8
Standard C Library Functions string(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level See below.
Standard See below.
The strtok() and strdup() functions are MT-Safe. The remain-
ing functions are Async-Signal-Safe.
For all except strlcat(), strlcpy(), and strsep(), see stan-
dards(5).
SEE ALSO
malloc(3C), setlocale(3C), strxfrm(3C), attributes(5), stan-
dards(5)
NOTES
When compiling multithreaded applications, the RENTRANT
flag must be defined on the compile line. This flag should
only be used in multithreaded applications.
A single-threaded application can gain access to strtokr()
only by defining EXTENSIONS or by defining
POSIXCSOURCE to a value greater than or equal to 199506L.
All of these functions assume the default locale ``C.'' For
some locales, strxfrm(3C) should be applied to the strings
before they are passed to the functions.
The strtok() function is safe to use in multithreaded appli-
cations because it saves its internal state in a thread-
specific data area. However, its use is discouraged, even
for single-threaded applications. The strtokr() function
should be used instead.
Do not pass the address of a character string literal as the
argument s1 to either strtok() or strtokr(). Similarly, do
not pass a pointer to the address of a character string
literal as the argument stringp to strsep(). These functions
can modify the storage pointed to by s1 in the case of
strtok() and strtokr() or *stringp in the case of strsep().
SunOS 5.11 Last change: 1 Aug 2008 9
Standard C Library Functions string(3C)
The C99 standard specifies that attempting to modify the
storage occupied by a string literal results in undefined
behavior. This allows compilers (including gcc and the Sun
Studio compilers when the -xstrconst flag is used) to place
string literals in read-only memory. Note that in Example 1
above, this problem is avoided because the variable line is
declared as a writable array of type char that is initial-
ized by a string literal rather than a pointer to char that
points to a string literal.
SunOS 5.11 Last change: 1 Aug 2008 10
|
