1 STRING(3C)               Standard C Library Functions               STRING(3C)
   2 
   3 
   4 
   5 NAME
   6        string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat,
   7        strncat, strlcat, strchr, strchrnul, strrchr, strcmp, strncmp, stpcpy,
   8        stpncpy, strcpy, strncpy, strlcpy, strcspn, strspn, strdup, strndup,
   9        strdupa, strndupa, strlen, strnlen, strpbrk, strsep, strstr, strnstr,
  10        strcasestr, strtok, strtok_r - string operations
  11 
  12 SYNOPSIS
  13        #include <strings.h>
  14 
  15        int strcasecmp(const char *s1, const char *s2);
  16 
  17        int strcasecmp_l(const char *s1, const char *s2, locale_t loc);
  18 
  19        int strncasecmp(const char *s1, const char *s2, size_t n);
  20 
  21        int strncasecmp_l(const char *s1, const char *s2, size_t n, locale_t loc);
  22 
  23        #include <string.h>
  24 
  25        char *strcat(char *restrict s1, const char *restrict s2);
  26 
  27        char *strncat(char *restrict s1, const char *restrict s2, size_t n);
  28 
  29        size_t strlcat(char *dst, const char *src, size_t dstsize);
  30 
  31        char *strchr(const char *s, int c);
  32 
  33        char *strrchr(const char *s, int c);
  34 
  35        int strcmp(const char *s1, const char *s2);
  36 
  37        int strncmp(const char *s1, const char *s2, size_t n);
  38 
  39        char *stpcpy(char *restrict s1, const char *restrict s2);
  40 
  41        char *stpncpy(char *restrict s1, const char *restrict s2, size_t n);
  42 
  43        char *strcpy(char *restrict s1, const char *restrict s2);
  44 
  45        char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
  46 
  47        size_t strlcpy(char *dst, const char *src, size_t dstsize);
  48 
  49        size_t strcspn(const char *s1, const char *s2);
  50 
  51        size_t strspn(const char *s1, const char *s2);
  52 
  53        char *strdup(const char *s1);
  54 
  55        char *strndup(const char *s1, size_t n);
  56 
  57        char *strdupa(const char *s1);
  58 
  59        char *strndupa(const char *s1, size_t n);
  60 
  61        size_t strlen(const char *s);
  62 
  63        size_t strnlen(const char *s, size_t n);
  64 
  65        char *strpbrk(const char *s1, const char *s2);
  66 
  67        char *strsep(char **stringp, const char *delim);
  68 
  69        char *strstr(const char *s1, const char *s2);
  70 
  71        char *strnstr(const char *s1, const char *s2, size_t n);
  72 
  73        char *strcasestr(const char *s1, const char *s2);
  74 
  75        char *strcasestr_l(const char *s1, const char *s2, locale_t loc);
  76 
  77        char *strtok(char *restrict s1, const char *restrict s2);
  78 
  79        char *strtok_r(char *restrict s1, const char *restrict s2,
  80             char **restrict lasts);
  81 
  82    ISO C++
  83        #include <string.h>
  84 
  85        const char *strchr(const char *s, int c);
  86 
  87        const char *strchrnul(const char *s, int c);
  88 
  89        const char *strpbrk(const char *s1, const char *s2);
  90 
  91        const char *strrchr(const char *s, int c);
  92 
  93        const char *strstr(const char *s1, const char *s2);
  94 
  95        #include <cstring>
  96 
  97        char *std::strchr(char *s, int c);
  98 
  99        char *std::strpbrk(char *s1, const char *s2);
 100 
 101        char *std::strrchr(char *s, int c);
 102 
 103        char *std::strstr(char *s1, const char *s2);
 104 
 105 DESCRIPTION
 106        The arguments s, s1, and s2 point to strings (arrays of characters
 107        terminated by a null character). The strcat(), strncat(), strlcat(),
 108        strcpy(), stpcpy(), stpncpy(), strncpy(), strlcpy(), strsep(),
 109        strtok(), and strtok_r() functions all alter their first argument.
 110        Additionally, the strcat(), stpcpy(), and strcpy() functions do not
 111        check for overflow of the array.
 112 
 113    strcasecmp(), strncasecmp()
 114        The strcasecmp() and strncasecmp() functions are case-insensitive
 115        versions of  strcmp() and strncmp() respectively, described below.
 116 
 117        The strcasecmp() and strncasecmp() functions compare two strings byte-
 118        by-byte, after converting each upper-case character to lower-case (as
 119        determined by the LC_CTYPE category of the current locale).  Note that
 120        neither the contents pointed to by s1 nor s2 are modified.
 121 
 122        The functions return an integer greater than, equal to, or less than 0,
 123        if the string pointed to by s1 is greater than, equal to, or less than
 124        the string pointed to by s2 respectively. The sign of a non-zero return
 125        value is determined  by the sign of the difference between the values
 126        of the first pair of bytes that differ in the
 127 
 128        The strncasecmp() function examines at most n bytes from each string.
 129 
 130    strcasecmp_l(), strncasecmp_l()
 131        The strcasecmp_l() and strncasecmp_l() functions behave identically to
 132        strcasecmp() and strncasecmp(), except instead of operating in the
 133        current locale, they instead operate in the locale specified by loc.
 134 
 135    strcat(), strncat(), strlcat()
 136        The strcat() function appends a copy of string s2, including the
 137        terminating null character, to the end of string s1. The strncat()
 138        function appends at most n characters of s2 to s1, not including any
 139        terminating null character, and then appends a null character.  Each
 140        returns a pointer to the null-terminated result. The initial character
 141        of s2 overrides the null character at the end of s1. If copying takes
 142        place between objects that overlap, the behavior of strcat(),
 143        strncat(), and strlcat() is undefined.
 144 
 145        The strlcat() function appends  at most (dstsize-strlen(dst)-1)
 146        characters of src to dst (dstsize being the  size of the  string buffer
 147        dst). If the string pointed to by dst contains a null-terminated string
 148        that fits into dstsize bytes when strlcat() is called, the string
 149        pointed to by dst will be a null-terminated string that fits in dstsize
 150        bytes (including the terminating null character) when it completes, and
 151        the initial character of src will override the null character at  the
 152        end of dst. If the string pointed to by dst is longer than dstsize
 153        bytes when strlcat() is called, the string pointed to by dst will not
 154        be changed. The function returns min{dstsize,strlen(dst)}+strlen(src).
 155        Buffer overflow can be checked as  follows:
 156 
 157          if (strlcat(dst, src, dstsize) >= dstsize)
 158                  return -1;
 159 
 160    strchr(), strrchr(), strchrnul()
 161        The strchr() function returns a pointer to the first occurrence of c
 162        (converted to a  char) in string s, or a null pointer if c does not
 163        occur in the string. The strrchr() function returns a pointer to the
 164        last occurrence of c. The null character terminating a string is
 165        considered to be part of the string. The strchrnul() function behaves
 166        similarly to strchr(), except when the character c is not found, it
 167        returns a pointer to the null terminator of the string s and not a null
 168        pointer.
 169 
 170    strcmp(), strncmp()
 171        The strcmp() function compares two strings byte-by-byte, according to
 172        the ordering of your machine's character set.  The function returns an
 173        integer greater than, equal to, or less than 0, if  the string pointed
 174        to by s1 is greater than, equal to, or less than the string pointed to
 175        by s2 respectively. The sign of a non-zero return value is determined
 176        by the sign of the difference between the values of the first pair of
 177        bytes that differ in the strings being compared. The strncmp() function
 178        makes the same comparison but looks at a maximum of n bytes. Bytes
 179        following a null byte are not compared.
 180 
 181    strcpy(), strncpy(), strlcpy()
 182        The strcpy() function copies string s2 to s1, including the terminating
 183        null character, stopping after the null character has been copied.  The
 184        strncpy() function copies exactly n bytes, truncating s2 or adding null
 185        characters to s1 if necessary. The result will not be null-terminated
 186        if the length of s2 is n or more. Both the strcpy() and strncpy()
 187        functions return s1. If copying takes place between objects that
 188        overlap, the behavior of strcpy(), strncpy(), and strlcpy() is
 189        undefined.
 190 
 191        The strlcpy() function copies  at most dstsize-1 characters (dstsize
 192        being the  size of the  string buffer dst) from src to dst,  truncating
 193        src if necessary.  The  result is always null-terminated. The function
 194        returns strlen(src). Buffer overflow can be checked as  follows:
 195 
 196          if (strlcpy(dst, src, dstsize) >= dstsize)
 197                  return -1;
 198 
 199    stpcpy(), stpncpy()
 200        The stpcpy() and stpncpy() functions behave identically to strcpy() and
 201        strncpy() respectively; however, instead of returning a pointer to the
 202        beginning of s1, they return a pointer to the terminating null
 203        character.
 204 
 205    strcspn(), strspn()
 206        The strcspn() function returns the length of the initial segment of
 207        string s1 that consists entirely of characters not from string s2.  The
 208        strspn() function returns the length of the initial segment of string
 209        s1 that consists entirely of characters from string s2.
 210 
 211    strdup(), strndup(), strdupa(), strndupa()
 212        The strdup() function returns a pointer to a new string that is a
 213        duplicate of the string pointed to by  s1. The returned pointer can be
 214        passed to free(). The space for the new string is obtained using
 215        malloc(3C). If the new string cannot be created, a null pointer is
 216        returned and errno may be set to ENOMEM to indicate that the storage
 217        space available is insufficient. The strndup() function is identical to
 218        strdup(), except it copies at most n bytes from s1 and ensures the
 219        copied string is always null terminated.
 220 
 221        The functions strdupa() and strndupa() behave identically to strdup()
 222        and strndup() respectively; however, instead of allocating memory using
 223        malloc(3C), they use alloca(3C). These functions are provided for
 224        compatibility only, their use is strongly discouraged due to their use
 225        of alloca(3C).
 226 
 227    strlen(), strnlen()
 228        The strlen() function returns the number of bytes in s, not including
 229        the terminating null character.
 230 
 231        The strnlen() function returns the smaller of n or the number of bytes
 232        in s, not including the terminating null character. The strnlen()
 233        function never examines more than n bytes of the string pointed to by
 234        s.
 235 
 236    strpbrk()
 237        The strpbrk() function returns a pointer to the first occurrence in
 238        string s1 of any character from string s2, or a null pointer if no
 239        character from s2 exists in s1.
 240 
 241    strsep()
 242        The strsep() function locates, in the null-terminated string referenced
 243        by *stringp, the first occurrence of any character in the string delim
 244        (or the terminating `\0' character) and replaces it with a `\0'.  The
 245        location of the next character after the delimiter character (or NULL,
 246        if the end of the string was reached) is stored in *stringp.  The
 247        original value of *stringp is returned.
 248 
 249        An ``empty'' field (one caused by two adjacent delimiter characters)
 250        can be detected by comparing the location referenced by the pointer
 251        returned by strsep() to `\0'.
 252 
 253        If *stringp is initially NULL, strsep() returns NULL.
 254 
 255    strstr(), strnstr(), strcasestr(), strcasestr_l()
 256        The strstr() function locates the first occurrence of the string s2
 257        (excluding the terminating null character) in string s1 and returns a
 258        pointer to the located string, or a null pointer if the string is not
 259        found. If s2 points to a string with zero length (that is, the string
 260        ""), the function returns  s1. The strnstr() function performs the same
 261        search as strstr(), but only considers up to n bytes of s1.  Bytes
 262        following a null byte are not compared.
 263 
 264 
 265        The strcasestr() and strcasestr_l() functions are similar to strstr(),
 266        but both functions ignore the case of both s1 and s2. Where as the
 267        strcasestr() function operates in the current locale, the
 268        strcasestr_l() function operates in the locale specified by loc.
 269 
 270    strtok()
 271        A sequence of calls to strtok() breaks the string pointed to by s1 into
 272        a sequence of tokens, each of which is delimited by a byte from the
 273        string pointed to by s2. The first call in the sequence has s1 as its
 274        first argument, and is followed by calls with a null pointer as their
 275        first argument. The separator string pointed to by s2 can be different
 276        from call to call.
 277 
 278        The first call in the sequence searches the string pointed to by s1 for
 279        the first byte that is not contained in the current separator string
 280        pointed to by s2. If no such byte is found, then there are no tokens in
 281        the string pointed to by s1 and strtok() returns a null pointer. If
 282        such a byte is found, it is the start of the first token.
 283 
 284        The strtok() function then searches from there for a byte that is
 285        contained in the current separator string. If no such byte is found,
 286        the current token extends to the end of the string pointed to by s1,
 287        and subsequent searches for a token return a null pointer. If such a
 288        byte is found, it is overwritten by a null byte that terminates the
 289        current token. The strtok() function saves a pointer to the following
 290        byte in thread-specific data, from which the next search for a token
 291        starts.
 292 
 293        Each subsequent call, with a null pointer as the value of the first
 294        argument, starts searching from the saved pointer and behaves as
 295        described above.
 296 
 297        See Example 1, 2, and 3 in the EXAMPLES section for examples of
 298        strtok() usage and the explanation in NOTES.
 299 
 300    strtok_r()
 301        The strtok_r() function considers the null-terminated string s1 as a
 302        sequence of zero or more text tokens separated by spans of one or more
 303        characters from the separator string s2. The argument lasts points to a
 304        user-provided pointer which points to stored information necessary for
 305        strtok_r() to continue scanning the same string.
 306 
 307        In the first call to strtok_r(), s1 points to a null-terminated string,
 308        s2 to a null-terminated string of separator characters, and the value
 309        pointed to by lasts is ignored. The strtok_r() function returns a
 310        pointer to the first character of the first token, writes a null
 311        character into s1 immediately following the returned token, and updates
 312        the pointer to which lasts points.
 313 
 314        In subsequent calls, s1 is a null pointer and lasts is unchanged from
 315        the previous call so that subsequent calls move through the string s1,
 316        returning successive tokens until no tokens remain. The separator
 317        string s2 can be different from call to call. When no token remains in
 318        s1, a null pointer is returned.
 319 
 320        See Example 3 in the EXAMPLES section for an example of strtok_r()
 321        usage and the explanation in NOTES.
 322 
 323 EXAMPLES
 324        Example 1 Search for word separators.
 325 
 326        The following example searches for tokens separated by space
 327        characters.
 328 
 329 
 330          #include <string.h>
 331          ...
 332          char *token;
 333          char line[] = "LINE TO BE SEPARATED";
 334          char *search = " ";
 335 
 336          /* Token will point to "LINE". */
 337          token = strtok(line, search);
 338 
 339          /* Token will point to "TO". */
 340          token = strtok(NULL, search);
 341 
 342 
 343        Example 2 Break a Line.
 344 
 345        The following example uses strtok to break a line into two character
 346        strings separated by any combination of SPACEs, TABs, or NEWLINEs.
 347 
 348 
 349          #include <string.h>
 350          ...
 351          struct element {
 352                 char *key;
 353                 char *data;
 354          };
 355          ...
 356          char line[LINE_MAX];
 357          char *key, *data;
 358          ...
 359          key = strtok(line, " \n");
 360          data = strtok(NULL, " \n");
 361 
 362 
 363        Example 3 Search for tokens.
 364 
 365        The following example uses both strtok() and strtok_r() to search for
 366        tokens separated by one or more characters from the string pointed to
 367        by the second argument, "/".
 368 
 369 
 370          #define __EXTENSIONS__
 371          #include <stdio.h>
 372          #include <string.h>
 373 
 374          int
 375          main() {
 376                  char *buf="5/90/45";
 377                  char *token;
 378                  char *lasts;
 379 
 380                  printf("tokenizing \"%s\" with strtok():\n", buf);
 381                  if ((token = strtok(buf, "/")) != NULL) {
 382                          printf("token = "%s\"\n", token);
 383                          while ((token = strtok(NULL, "/")) != NULL) {
 384                                  printf("token = \"%s\"\n", token);
 385                          }
 386                  }
 387 
 388                  buf = "//5//90//45//";
 389                  printf("\ntokenizing \"%s\" with strtok_r():\n", buf);
 390                  if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
 391                          printf("token = \"%s\"\n", token);
 392                          while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
 393                                  printf("token = \"%s\"\n", token);
 394                          }
 395                  }
 396          }
 397 
 398 
 399        When compiled and run, this example produces the following output:
 400 
 401 
 402          tokenizing "5/90/45" with strtok():
 403          token = "5"
 404          token = "90"
 405          token = "45"
 406 
 407          tokenizing "//5//90//45//" with strtok_r():
 408          token = "5"
 409          token = "90"
 410          token = "45"
 411 
 412 
 413 ATTRIBUTES
 414        See attributes(5) for descriptions of the following attributes:
 415 
 416        +--------------------+-----------------+
 417        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 418        +--------------------+-----------------+
 419        |Interface Stability | See below.      |
 420        +--------------------+-----------------+
 421        |MT-Level            | See below.      |
 422        +--------------------+-----------------+
 423        |Standard            | See below.      |
 424        +--------------------+-----------------+
 425 
 426        The strlcat(), strlcpy(), and strsep() functions are Committed.  All
 427        the rest are Standard.
 428 
 429        The strtok(), strdup(), and strndup() functions are MT-Safe.  The
 430        remaining functions are Async-Signal-Safe.
 431 
 432        For all except strlcat(), strlcpy(), and strsep(), see standards(5).
 433 
 434 SEE ALSO
 435        malloc(3C), newlocale(3C), setlocale(3C), strxfrm(3C), uselocale(3C),
 436        attributes(5), standards(5)
 437 
 438 NOTES
 439        When compiling multithreaded applications, the _REENTRANT flag must be
 440        defined on the compile line. This flag should only be used in
 441        multithreaded applications.
 442 
 443        A single-threaded application can gain access to strtok_r() only by
 444        defining __EXTENSIONS__ or by defining _POSIX_C_SOURCE to a value
 445        greater than or equal to 199506L.
 446 
 447        Except where noted otherwise, all of these functions assume the default
 448        locale ``C.'' For some locales, strxfrm(3C) should be applied to the
 449        strings before they are passed to the functions.
 450 
 451        The strtok() function is safe to use in multithreaded applications
 452        because it saves its internal state in a thread-specific data area.
 453        However, its use is discouraged, even for single-threaded applications.
 454        The strtok_r() function should be used instead.
 455 
 456        Do not pass the address of a character string literal as the argument
 457        s1 to either strtok() or strtok_r(). Similarly, do not pass a pointer
 458        to the address of a character string literal as the argument stringp to
 459        strsep(). These functions can modify the storage pointed to by s1 in
 460        the case of strtok() and strtok_r() or *stringp in the case of
 461        strsep(). The C99 standard specifies that attempting to modify the
 462        storage occupied by a string literal results in undefined behavior.
 463        This allows compilers (including gcc and the Sun Studio compilers when
 464        the -xstrconst flag is used) to place string literals in read-only
 465        memory.  Note that in Example 1 above, this problem is avoided because
 466        the variable line is declared as a writable array of type char that is
 467        initialized by a string literal rather than a pointer to char that
 468        points to a string literal.
 469 
 470 
 471 
 472                                 March 23, 2016                      STRING(3C)