1string(3C)               Standard C Library Functions               string(3C)
2
3
4

NAME

6       string, strcasecmp, strncasecmp, strcat, strncat, strlcat, strchr, str‐
7       rchr, strcmp,  strncmp,  strcpy,  strncpy,  strlcpy,  strcspn,  strspn,
8       strdup,  strlen,  strnlen,  strpbrk, strsep, strstr, strtok, strtok_r -
9       string operations
10

SYNOPSIS

12       #include <strings.h>
13
14       int strcasecmp(const char *s1, const char *s2);
15
16
17       int strncasecmp(const char *s1, const char *s2, size_t n);
18
19
20       #include <string.h>
21
22       char *strcat(char *restrict s1, const char *restrict s2);
23
24
25       char *strncat(char *restrict s1, const char *restrict s2, size_t n);
26
27
28       size_t strlcat(char *dst, const char *src, size_t dstsize);
29
30
31       char *strchr(const char *s, int c);
32
33
34       char *strrchr(const char *s, int c);
35
36
37       int strcmp(const char *s1, const char *s2);
38
39
40       int strncmp(const char *s1, const char *s2, size_t n);
41
42
43       char *strcpy(char *restrict s1, const char *restrict s2);
44
45
46       char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
47
48
49       size_t strlcpy(char *dst, const char *src, size_t dstsize);
50
51
52       size_t strcspn(const char *s1, const char *s2);
53
54
55       size_t strspn(const char *s1, const char *s2);
56
57
58       char *strdup(const char *s1);
59
60
61       size_t strlen(const char *s);
62
63
64       size_t strnlen(const char *s, size_t n);
65
66
67       char *strpbrk(const char *s1, const char *s2);
68
69
70       char *strsep(char **stringp, const char *delim);
71
72
73       char *strstr(const char *s1, const char *s2);
74
75
76       char *strtok(char *restrict s1, const char *restrict s2);
77
78
79       char *strtok_r(char *s1, const char *s2, char **lasts);
80
81
82   ISO C++
83       #include <string.h>
84
85       const char *strchr(const char *s, int c);
86
87
88       const char *strpbrk(const char *s1, const char *s2);
89
90
91       const char *strrchr(const char *s, int c);
92
93
94       const char *strstr(const char *s1, const char *s2);
95
96
97       #include <cstring>
98
99       char *std::strchr(char *s, int c);
100
101
102       char *std::strpbrk(char *s1, const char *s2);
103
104
105       char *std::strrchr(char *s, int c);
106
107
108       char *std::strstr(char *s1, const char *s2);
109
110

DESCRIPTION

112       The arguments s, s1, and s2 point to strings (arrays of characters ter‐
113       minated  by a null character). The strcat(), strncat(), strlcat(), str‐
114       cpy(), strncpy(), strlcpy(), strsep(), strtok(), and  strtok_r()  func‐
115       tions  all  alter  their first argument. Additionally, the strcat() and
116       strcpy() functions do not check for overflow of the array.
117
118   strcasecmp(), strncasecmp()
119       The strcasecmp() and strncasecmp() functions are case-insensitive  ver‐
120       sions  of   strcmp() and strncmp() respectively, described below.  They
121       assume the ASCII character set and ignore differences in case when com‐
122       paring lower and upper case characters.
123
124   strcat(), strncat(), strlcat()
125       The strcat() function appends a copy of string s2, including the termi‐
126       nating null character, to the end of string s1. The strncat()  function
127       appends at most n characters. Each returns a pointer to the null-termi‐
128       nated result. The initial character of  s2 overrides the null character
129       at  the end of s1. If copying takes place between objects that overlap,
130       the behavior of strcat(), strncat(), and strlcat() is undefined.
131
132
133       The strlcat() function appends  at most  (dstsize-strlen(dst)-1)  char‐
134       acters  of  src  to  dst (dstsize being the  size of the  string buffer
135       dst). If the string pointed to by dst contains a null-terminated string
136       that  fits  into  dstsize  bytes  when  strlcat() is called, the string
137       pointed to by dst will be a null-terminated string that fits in dstsize
138       bytes (including the terminating null character) when it completes, and
139       the initial character of src will override the null character  at   the
140       end  of  dst.  If  the  string pointed to by dst is longer than dstsize
141       bytes when strlcat() is called, the string pointed to by dst  will  not
142       be  changed. The function returns min{dstsize,strlen(dst)}+strlen(src).
143       Buffer overflow can be checked as  follows:
144
145         if (strlcat(dst, src, dstsize) >= dstsize)
146                 return −1;
147
148
149   strchr(), strrchr()
150       The strchr() function returns a pointer to the first  occurrence  of  c
151       (converted  to  a   char)  in string s, or a null pointer if c does not
152       occur in the string. The strrchr() function returns a  pointer  to  the
153       last  occurrence  of c. The null character terminating a string is con‐
154       sidered to be part of the string.
155
156   strcmp(), strncmp()
157       The strcmp() function compares two strings byte-by-byte,  according  to
158       the  ordering of your machine's character set.  The function returns an
159       integer greater than, equal to, or less than 0, if  the string  pointed
160       to  by s1 is greater than, equal to, or less than the string pointed to
161       by s2 respectively. The sign of a non-zero return value  is  determined
162       by  the  sign of the difference between the values of the first pair of
163       bytes that differ in the strings being compared. The strncmp() function
164       makes the same comparison but looks at a maximum of n bytes. Bytes fol‐
165       lowing a null byte are not compared.
166
167   strcpy(), strncpy(), strlcpy()
168       The strcpy() function copies string s2 to s1, including the terminating
169       null  character, stopping after the null character has been copied. The
170       strncpy() function copies exactly n bytes, truncating s2 or adding null
171       characters  to  s1 if necessary. The result will not be null-terminated
172       if the length of s2 is n or more. Each function returns s1.  If copying
173       takes  place  between  objects  that overlap, the behavior of strcpy(),
174       strncpy(), and strlcpy() is undefined.
175
176
177       The strlcpy() function copies  at most  dstsize−1  characters  (dstsize
178       being the  size of the  string buffer dst) from src to dst,  truncating
179       src if necessary.  The  result is always null-terminated. The  function
180       returns strlen(src). Buffer overflow can be checked as  follows:
181
182         if (strlcpy(dst, src, dstsize) >= dstsize)
183                 return −1;
184
185
186   strcspn(), strspn()
187       The  strcspn()  function  returns  the length of the initial segment of
188       string s1 that consists entirely of characters not from string s2.  The
189       strspn()  function  returns the length of the initial segment of string
190       s1 that consists entirely of characters from string s2.
191
192   strdup()
193       The strdup() function returns a pointer to  a  new  string  that  is  a
194       duplicate  of the string pointed to by  s1. The returned pointer can be
195       passed to free(). The space for the new string is obtained  using  mal‐
196       loc(3C).  If  the  new  string  cannot  be  created,  a null pointer is
197       returned and errno may be set to ENOMEM to indicate  that  the  storage
198       space available is insufficient.
199
200   strlen(), strnlen()
201       The  strlen()  function returns the number of bytes in s, not including
202       the terminating null character.
203
204
205       The strnlen() function returns the smaller of n or the number of  bytes
206       in s, not including the terminating null character. The strnlen() func‐
207       tion never examines more than n bytes of the string pointed to by s.
208
209   strpbrk()
210       The strpbrk() function returns a pointer to  the  first  occurrence  in
211       string  s1  of  any  character  from string s2, or a null pointer if no
212       character from s2 exists in s1.
213
214   strsep()
215       The strsep() function locates, in the null-terminated string referenced
216       by  *stringp, the first occurrence of any character in the string delim
217       (or the terminating `\0' character) and replaces it with a  `\0'.   The
218       location  of the next character after the delimiter character (or NULL,
219       if the end of the string was reached) is stored in *stringp.  The orig‐
220       inal value of *stringp is returned.
221
222
223       An  ``empty''  field  (one caused by two adjacent delimiter characters)
224       can be detected by comparing the location  referenced  by  the  pointer
225       returned by strsep() to `\0'.
226
227
228       If *stringp is initially NULL, strsep() returns NULL.
229
230   strstr()
231       The  strstr()  function  locates  the first occurrence of the string s2
232       (excluding the terminating null character) in string s1 and  returns  a
233       pointer  to  the located string, or a null pointer if the string is not
234       found. If  s2 points to a string with zero length (that is, the  string
235       ""), the function returns  s1.
236
237   strtok()
238       A sequence of calls to strtok() breaks the string pointed to by s1 into
239       a sequence of tokens, each of which is delimited by  a  byte  from  the
240       string  pointed  to by s2. The first call in the sequence has s1 as its
241       first argument, and is followed by calls with a null pointer  as  their
242       first  argument. The separator string pointed to by s2 can be different
243       from call to call.
244
245
246       The first call in the sequence searches the string pointed to by s1 for
247       the  first  byte  that is not contained in the current separator string
248       pointed to by s2. If no such byte is found, then there are no tokens in
249       the  string  pointed  to  by s1 and strtok() returns a null pointer. If
250       such a byte is found, it is the start of the first token.
251
252
253       The strtok() function then searches from there for a byte that is  con‐
254       tained  in  the current separator string. If no such byte is found, the
255       current token extends to the end of the string pointed to  by  s1,  and
256       subsequent  searches  for a token return a null pointer. If such a byte
257       is found, it is overwritten by a null byte that terminates the  current
258       token.  The  strtok() function saves a pointer to the following byte in
259       thread-specific data, from which the next search for a token starts.
260
261
262       Each subsequent call, with a null pointer as the  value  of  the  first
263       argument,  starts  searching  from  the  saved  pointer  and behaves as
264       described above.
265
266
267       See Example 1, 2, and 3 in the EXAMPLES section for  examples  of  str‐
268       tok() usage and the explanation in NOTES.
269
270   strtok_r()
271       The  strtok_r()  function  considers the null-terminated string s1 as a
272       sequence of zero or more text tokens separated by spans of one or  more
273       characters from the separator string s2. The argument lasts points to a
274       user-provided pointer which points to stored information necessary  for
275       strtok_r() to continue scanning the same string.
276
277
278       In the first call to strtok_r(), s1 points to a null-terminated string,
279       s2 to a null-terminated string of separator characters, and  the  value
280       pointed  to  by  lasts  is  ignored.  The strtok_r() function returns a
281       pointer to the first character of the first token, writes a null  char‐
282       acter into s1 immediately following the returned token, and updates the
283       pointer to which lasts points.
284
285
286       In subsequent calls, s1 is a null pointer and lasts is  unchanged  from
287       the  previous call so that subsequent calls move through the string s1,
288       returning successive tokens  until  no  tokens  remain.  The  separator
289       string  s2 can be different from call to call. When no token remains in
290       s1, a null pointer is returned.
291
292
293       See Example 3 in the EXAMPLES section  for  an  example  of  strtok_r()
294       usage and the explanation in NOTES.
295

EXAMPLES

297       Example 1 Search for word separators.
298
299
300       The  following  example  searches for tokens separated by space charac‐
301       ters.
302
303
304         #include <string.h>
305         ...
306         char *token;
307         char line[] = "LINE TO BE SEPARATED";
308         char *search = " ";
309
310         /* Token will point to "LINE". */
311         token = strtok(line, search);
312
313         /* Token will point to "TO". */
314         token = strtok(NULL, search);
315
316
317       Example 2 Break a Line.
318
319
320       The following example uses strtok to break a line  into  two  character
321       strings separated by any combination of SPACEs, TABs, or NEWLINEs.
322
323
324         #include <string.h>
325         ...
326         struct element {
327                char *key;
328                char *data;
329         };
330         ...
331         char line[LINE_MAX];
332         char *key, *data;
333         ...
334         key = strtok(line, " \n");
335         data = strtok(NULL, " \n");
336
337
338       Example 3 Search for tokens.
339
340
341       The  following  example uses both strtok() and strtok_r() to search for
342       tokens separated by one or more characters from the string  pointed  to
343       by the second argument, "/".
344
345
346         #define __EXTENSIONS__
347         #include <stdio.h>
348         #include <string.h>
349
350         int
351         main() {
352                 char *buf="5/90/45";
353                 char *token;
354                 char *lasts;
355
356                 printf("tokenizing \"%s\" with strtok():\n", buf);
357                 if ((token = strtok(buf, "/")) != NULL) {
358                         printf("token = "%s\"\n", token);
359                         while ((token = strtok(NULL, "/")) != NULL) {
360                                 printf("token = \"%s\"\n", token);
361                         }
362                 }
363
364                 buf = "//5//90//45//";
365                 printf("\ntokenizing \"%s\" with strtok_r():\n", buf);
366                 if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
367                         printf("token = \"%s\"\n", token);
368                         while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
369                                 printf("token = \"%s\"\n", token);
370                         }
371                 }
372         }
373
374
375
376       When compiled and run, this example produces the following output:
377
378
379         tokenizing "5/90/45" with strtok():
380         token = "5"
381         token = "90"
382         token = "45"
383
384         tokenizing "//5//90//45//" with strtok_r():
385         token = "5"
386         token = "90"
387         token = "45"
388
389

ATTRIBUTES

391       See attributes(5) for descriptions of the following attributes:
392
393
394
395
396       ┌─────────────────────────────┬─────────────────────────────┐
397       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
398       ├─────────────────────────────┼─────────────────────────────┤
399       │Interface Stability          │Committed                    │
400       ├─────────────────────────────┼─────────────────────────────┤
401       │MT-Level                     │See below.                   │
402       ├─────────────────────────────┼─────────────────────────────┤
403       │Standard                     │See below.                   │
404       └─────────────────────────────┴─────────────────────────────┘
405
406
407       The  strtok()  and  strdup() functions are MT-Safe. The remaining func‐
408       tions are Async-Signal-Safe.
409
410
411       For all except strlcat(), strlcpy(), and strsep(), see standards(5).
412

SEE ALSO

414       malloc(3C), setlocale(3C), strxfrm(3C), attributes(5), standards(5)
415

NOTES

417       When compiling multithreaded applications, the _REENTRANT flag must  be
418       defined  on  the  compile line. This flag should only be used in multi‐
419       threaded applications.
420
421
422       A single-threaded application can gain access  to  strtok_r()  only  by
423       defining  __EXTENSIONS__  or  by  defining  _POSIX_C_SOURCE  to a value
424       greater than or equal to 199506L.
425
426
427       All of these functions  assume  the  default  locale  ``C.''  For  some
428       locales,  strxfrm(3C)  should be applied to the strings before they are
429       passed to the functions.
430
431
432       The strtok() function is safe  to  use  in  multithreaded  applications
433       because  it  saves  its  internal state in a thread-specific data area.
434       However, its use is discouraged, even for single-threaded applications.
435       The strtok_r() function should be used instead.
436
437
438       Do  not  pass the address of a character string literal as the argument
439       s1 to either strtok() or strtok_r(). Similarly, do not pass  a  pointer
440       to the address of a character string literal as the argument stringp to
441       strsep(). These functions can modify the storage pointed to  by  s1  in
442       the  case  of  strtok()  and  strtok_r()  or  *stringp  in  the case of
443       strsep(). The C99 standard specifies  that  attempting  to  modify  the
444       storage  occupied  by  a  string literal results in undefined behavior.
445       This allows compilers (including gcc and the Sun Studio compilers  when
446       the -xstrconst flag is used) to place string literals in read-only mem‐
447       ory. Note that in Example 1 above, this problem is avoided because  the
448       variable line is declared as a writable array of type char that is ini‐
449       tialized by a string literal rather than a pointer to char that  points
450       to a string literal.
451
452
453
454SunOS 5.11                        1 Aug 2008                        string(3C)
Impressum