1 /** @file  ../include/string.h

     2 @internalComponent

     3 */

     4 

     5 /** @fn  memccpy(void *t, const void *f, int c, size_t n)

     6 @param t

     7 @param f

     8 @param c

     9 @param n

    10 @return   memccpy function returns a pointer to the next character in t after c, or NULL if c was not found in the first n characters of f.

    11 

    12   The memccpy function

    13 copies bytes from string f to string t. If the character c (as converted to an unsigned char) occurs in the string f, the copy stops and a pointer to the byte after the copy of c in the string t is returned.

    14 Otherwise, n bytes are copied, and a NULL pointer is returned.

    15 

    16 Examples:

    17 @code

    18 #include <string.h>

    19 #include <stdio.h>

    20 int main()

    21 {

    22     char one[50] = {"\0"};

    23     (void) memccpy(one, "abcdefgh",8,3);

    24     printf("String after memcpy %s

    25 ",one);

    26     (void) memccpy(one, "Hello",5,1);

    27     printf("String after memcpy %s

    28 ",one);

    29     return 0;

    30 }

    31 

    32 @endcode

    33  Output

    34 @code

    35 String after memcpy abc

    36 String after memcpy Hbc

    37 

    38 @endcode

    39 @see bcopy()

    40 @see memcpy()

    41 @see memmove()

    42 @see strcpy()

    43 

    44 

    45  

    46 

    47 @publishedAll

    48 @externallyDefinedApi

    49 */

    50 

    51 /** @fn  memchr(const void *s, int c, size_t n)

    52 @param s

    53 @param c

    54 @param n

    55 

    56 @return   The memchr function

    57 returns a pointer to the byte located,

    58 or NULL if no such byte exists within n bytes.

    59 

    60   The memchr function

    61 locates the first occurrence of c (converted to an unsigned char)

    62 in string s.

    63 

    64 Examples:

    65 @code

    66 #include <string.h>

    67 #include <stdio.h>

    68 int main()

    69 {

    70     char one[50];

    71     char* ret;

    72     strcpy(one,"abcd");

    73     ret = memchr("abcd", ’c’,4);

    74     if(!strncmp(one+2,ret,1)) printf("\ ’c\ ’ found in string \"abcd\"\n");

    75     ret = memchr(one, ’z’,4);

    76     if(ret == NULL) printf("\ ’z\ ’ not found in string \"abcd\"\n");           

    77     return 0;

    78 }

    79 

    80 @endcode

    81  Output

    82 @code

    83  ’c’ found in string "abcd"

    84  ’z’ not found in string "abcd"

    85 

    86 @endcode

    87 @see strchr()

    88 @see strcspn()

    89 @see strpbrk()

    90 @see strsep()

    91 @see strstr()

    92 @see strtok()

    93 

    94 

    95  

    96 

    97 @publishedAll

    98 @externallyDefinedApi

    99 */

   100 

   101 /** @fn  memcmp(const void *s1, const void *s2, size_t n)

   102 @param s1

   103 @param s2

   104 @param n

   105 

   106 @return   The memcmp function

   107 returns zero if the two strings are identical,

   108 otherwise returns the difference between the first two differing bytes

   109 (treated as unsigned char values, so that '\\200'

   110 is greater than '\\0'

   111 for example).

   112 Zero-length strings are always identical.

   113 

   114   The memcmp function

   115 compares byte string s1 against byte string s2. Both strings are assumed to be n bytes long.

   116 

   117 Examples:

   118 @code

   119 #include <string.h>

   120 #include <stdio.h>

   121 int main()

   122 {

   123    char str1[]  = "abcdefg";

   124    char str2[] =  "abcdefr";

   125    int result;

   126    printf( "Compare ’%.6s’ to ’%.6s\n", str1, str2 );

   127    result = memcmp( str1, str2, 6);

   128    if( result < 0 )

   129       printf( "str1 is less than str2.\n" );

   130    else if( result == 0 )

   131       printf( "str1 is equal to str2.\n" );

   132    else if( result > 0 )

   133       printf( "str1 is greater than str2.\n" );

   134    printf( "Compare ’%.7s’ to ’%.7s\n", str1, str2 );

   135    result = memcmp( str1, str2, 7 );

   136    if( result < 0 )

   137       printf( "str1 is less than str2.\n" );

   138    else if( result == 0 )

   139       printf( "str1 is equal to str2.\n" );

   140    else if( result > 0 )

   141       printf( "str1 is greater than str2.\n" );

   142    return 0;    

   143 }

   144 

   145 @endcode

   146  Output

   147 @code

   148 Compare ’abcdef’ to ’abcdef

   149 str1 is equal to str2.

   150 Compare ’abcdefg’ to ’abcdefr

   151 str1 is less than str2.

   152 

   153 @endcode

   154 @see bcmp()

   155 @see strcasecmp()

   156 @see strcmp()

   157 @see strcoll()

   158 @see strxfrm()

   159 

   160 

   161  

   162 

   163 @publishedAll

   164 @externallyDefinedApi

   165 */

   166 

   167 /** @fn  memcpy(void *dst, const void *src, size_t len)

   168 @param dst

   169 @param src

   170 @param len

   171 @return   The memcpy function

   172 returns the original value of dst.

   173 

   174   The memcpy function

   175 copies len bytes from string src to string dst.

   176 

   177 Examples:

   178 @code

   179 #include <string.h>

   180 #include <stdio.h>

   181 int main()

   182 {

   183     char one[50] = {"\0"};

   184     (void) memcpy(one, "abcdefgh",8);

   185     printf("String after memcpy %s

   186 ",one);

   187     (void) memcpy(one, "Hello",5);

   188     printf("String after memcpy %s

   189 ",one);

   190     return 0;   

   191 }

   192 

   193 @endcode

   194  Output

   195 @code

   196 String after memcpy abcdefgh

   197 String after memcpy Hellofgh

   198 

   199 @endcode

   200 @see bcopy()

   201 @see memccpy()

   202 @see memmove()

   203 @see strcpy()

   204 

   205 

   206  

   207 

   208 @publishedAll

   209 @externallyDefinedApi

   210 */

   211 

   212 /** @fn  memmove(void *dst, const void *src, size_t len)

   213 @param dst

   214 @param src

   215 @param len

   216 

   217   The memmove function copies len bytes from string src to string dst. The two strings may overlap. The copy is always done in a non-destructive 

   218 manner.

   219 

   220 Examples:

   221 @code

   222 #include <string.h>

   223 #include <stdio.h>

   224 int main()

   225 {

   226     char one[50];

   227     (void) strcpy(one, "abcdefgh");

   228     printf("String before memmove %s

   229 ",one);

   230     (void) memmove(one+1, "xyz", 2);

   231     printf("String after memmove %s

   232 ",one);

   233     (void) strcpy(one, "abcdefgh");

   234     printf("String before memmove %s

   235 ",one);

   236     (void) memmove(one+1, "xyz", 0);

   237     printf("String after memmove %s

   238 ",one);

   239     return 0;   

   240 }

   241 

   242 @endcode

   243  Output

   244 @code

   245 String before memmove abcdefgh

   246 String after memmove axydefgh

   247 String before memmove abcdefgh

   248 String after memmove abcdefgh

   249 

   250 @endcode

   251 @return   The memmove function returns pointer to dst dst.

   252 

   253 @see bcopy()

   254 @see memcpy()

   255 @see strcpy()

   256 

   257 

   258  

   259 

   260 @publishedAll

   261 @externallyDefinedApi

   262 */

   263 

   264 /** @fn  memset(void *dst0, int c0, size_t length)

   265 @param dst0

   266 @param c0

   267 @param length

   268 

   269   The memset function

   270 writes length bytes of value c0 (converted to an unsigned char) to the string dst0.

   271 

   272 Examples:

   273 @code

   274 #include <string.h>

   275 #include <stdio.h>

   276 int main()

   277 {

   278     char one[50];       

   279     strcpy(one, "abcdefgh");

   280     printf("String before memset %s

   281 ",one);

   282     memset(one+1, 'x', 3);

   283     printf("String after calling memset first time %s

   284 ",one);          

   285     memset(one+2, 'y', 0);

   286     printf("String after calling memset second time %s

   287 ",one);

   288     return 0;   

   289 }

   290 

   291 @endcode

   292  Output

   293 @code

   294 String before memset abcdefgh

   295 String after calling memset first time axxxefgh

   296 String after calling memset second time axxxefgh

   297 

   298 @endcode

   299 @return   The memset function returns its first argument.

   300 

   301 @see bzero()

   302 @see swab()

   303 

   304 

   305  

   306 

   307 @publishedAll

   308 @externallyDefinedApi

   309 */

   310 

   311 /** @fn  stpcpy(char *to, const char *from)

   312 @param to

   313 @param from

   314 

   315 Note: This description also covers the following functions -

   316  strcpy()  strncpy() 

   317 

   318 @return   The strcpy and strncpy functions

   319 return to. The stpcpy function returns a pointer to the terminating ‘\\0’

   320 character of to.

   321 

   322   The stpcpy and strcpy functions

   323 copy the string from to to (including the terminating ‘\\0’

   324 character.)

   325 

   326  The strncpy function copies at most len characters from from into to. If from is less than len characters long,

   327 the remainder of to is filled with '\\0'

   328 characters.

   329 Otherwise, to is not terminated.

   330 

   331 Examples:

   332 @code

   333 #include <string.h>

   334 #include <stdio.h>

   335 int main()

   336 {

   337     char one[50] = {"abcdefgh"};        

   338     printf("String before strcpy %s

   339 ",one);

   340     strcpy(one,"Hello");

   341     printf("String after strcpy %s

   342 ",one);

   343     strncpy(one + 5, " ",1);

   344     strncpy(one + 6, "World",5);

   345     printf("String after strncpy %s

   346 ",one);

   347     return 0;   

   348 }

   349 

   350 @endcode

   351  Output

   352 @code

   353 String before strcpy abcdefgh

   354 String after strcpy Hello

   355 String after strncpy Hello World

   356 

   357 @endcode

   358 Examples:

   359  The following sets chararray to "abc\\0\\0\\0"

   360 @code

   361 char chararray[6];

   362 (void)strncpy(chararray, "abc", sizeof(chararray));

   363 

   364 @endcode

   365  The following sets chararray to "abcdef:"

   366 @code

   367 char chararray[6];

   368 (void)strncpy(chararray, "abcdefgh", sizeof(chararray));

   369 

   370 @endcode

   371  Note that it does not NULL terminate chararray because the length of the source string is greater than or equal

   372 to the length argument. The following copies as many characters from input to buf as will fit and NULL terminates the result.

   373 Because strncpy does not guarantee to NULL terminate the string itself, this must be done explicitly.

   374 @code

   375 char buf[1024];

   376 (void)strncpy(buf, input, sizeof(buf) - 1);

   377 buf[sizeof(buf) - 1] = ’\0’;

   378 

   379 @endcode

   380 

   381 Security considerations:

   382 

   383  The strcpy function is easily misused in a manner which enables malicious users

   384 to arbitrarily change a running program's functionality through a

   385 buffer overflow attack.

   386 @see bcopy()

   387 @see memcpy()

   388 @see memmove()

   389 

   390 

   391  

   392 

   393 @publishedAll

   394 @externallyDefinedApi

   395 */

   396 

   397 /** @fn  strcasestr(const char *s, const char *find)

   398 @param s

   399 @param find

   400 

   401 Refer to  strstr() for the documentation

   402 @see memchr()

   403 @see strchr()

   404 @see strcspn()

   405 @see strpbrk()

   406 @see strrchr()

   407 @see strsep()

   408 @see strspn()

   409 @see strtok()

   410 

   411 

   412  

   413 

   414 @publishedAll

   415 @externallyDefinedApi

   416 */

   417 

   418 /** @fn  strcat(char *  s, const char *  append)

   419 @param s

   420 @param append

   421 

   422 Note: This description also covers the following functions -

   423  strncat() 

   424 

   425 @return   The strcat and strncat functions

   426 return the pointer s.

   427 

   428   The strcat and strncat functions

   429 append a copy of the null-terminated string append to the end of the null-terminated string s, then add a terminating ‘\\0’

   430 The string s must have sufficient space to hold the result.

   431 

   432  The strncat function

   433 appends not more than count characters from append, and then adds a terminating ‘\\0’

   434 

   435 Examples:

   436 @code

   437 #include <string.h>

   438 #include <stdio.h>

   439 int main()

   440 {

   441     char one[50] = {"\0"};              

   442     strcpy(one,"Hello");

   443     strcat(one," World");

   444     printf("Concatenated String %s

   445 ",one);

   446     return 0;   

   447 }

   448 

   449 @endcode

   450  Output

   451 @code

   452 Concatenated String Hello World

   453 

   454 @endcode

   455 

   456 Security considerations:

   457 

   458  The strcat function is easily misused in a manner

   459 which enables malicious users to arbitrarily change

   460 a running program's functionality through a buffer overflow attack. Avoid using strcat. Instead, use strncat or strlcat and ensure that no more characters are copied to the destination buffer

   461 than it can hold. Note that strncat can also be problematic.

   462 It may be a security concern for a string to be truncated at all.

   463 Since the truncated string will not be as long as the original,

   464 it may refer to a completely different resource

   465 and usage of the truncated resource

   466 could result in very incorrect behavior.

   467 Example:

   468 

   469 @see bcopy()

   470 @see memcpy()

   471 @see memmove()

   472 @see strcpy()

   473 

   474 

   475  

   476 

   477 @publishedAll

   478 @externallyDefinedApi

   479 */

   480 

   481 /** @fn  strchr(const char *s, int c)

   482 @param s

   483 @param c

   484 

   485 Note: This description also covers the following functions -

   486  strrchr() 

   487 

   488 @return   The functions strchr and strrchr return a pointer to the located character, or NULL if the character does not appear in the string.

   489 

   490   The strchr function locates the first occurrence of c (converted to a char)

   491 in the string pointed to by s. The terminating null character is considered part of the string;

   492 therefore if c is ‘\\0’

   493 the functions locate the terminating ‘\\0’

   494 

   495  The strrchr function is identical to strchr except it locates the last occurrence of c.

   496 

   497 Examples:

   498 @code

   499 #include <string.h>

   500 #include <stdio.h>

   501 int main()

   502 {

   503         char one[50];

   504         char* ret;

   505         strcpy(one,"abcd");

   506         ret = strchr("abcd", 'c');

   507         if(!strncmp(one+2,ret,1)) printf("\ 'c\ ' found in string \"abcd\"

   508 ");

   509         ret = strchr(one, 'z');

   510         if(ret == NULL) printf("\ 'z\ ' not found in string \"abcd\"

   511 ");               

   512         return 0;

   513 }

   514 

   515 @endcode

   516  Output

   517 @code

   518  ’c’ found in string "abcd"

   519  ’z’ not found in string "abcd"

   520 

   521 @endcode

   522 @see memchr()

   523 @see strcspn()

   524 @see strpbrk()

   525 @see strsep()

   526 @see strspn()

   527 @see strstr()

   528 @see strtok()

   529 

   530 

   531  

   532 

   533 @publishedAll

   534 @externallyDefinedApi

   535 */

   536 

   537 /** @fn  strcmp(const char *s1, const char *s2)

   538 @param s1

   539 @param s2

   540 

   541 Note: This description also covers the following functions -

   542  strncmp() 

   543 

   544 @return   The strcmp and strncmp return an integer greater than, equal to, or less than 0, according 

   545 to whether the string s1 is greater than, equal to, or less than the string s2.

   546 

   547   The strcmp and strncmp functions

   548 lexicographically compare the null-terminated strings s1 and s2.

   549 

   550  The strncmp function

   551 compares not more than len characters.

   552 Because strncmp is designed for comparing strings rather than binary data,

   553 characters that appear after a ‘\\0’

   554 character are not compared.

   555 

   556 Examples:

   557 @code

   558 #include <string.h>

   559 #include <stdio.h>

   560 int main()

   561 {

   562    char str1[]  = "abcdefg";

   563    char str2[] =  "abcdefr";

   564    int result;

   565    printf( "Compare '%s' to '%s

   566 ", str1, str2 );

   567    result = strcmp( str1, str2);

   568    if( result < 0 )

   569       printf( "str1 is less than str2.

   570 " );

   571    else if( result == 0 )

   572       printf( "str1 is equal to str2.

   573 " );

   574    else if( result > 0 )

   575       printf( "str1 is greater than str2.

   576 " );

   577    printf( "Compare '%.6s' to '%.6s

   578 ", str1, str2 );

   579    result = strncmp( str1, str2, 6 );

   580    if( result < 0 )

   581       printf( "str1 is less than str2.

   582 " );

   583    else if( result == 0 )

   584       printf( "str1 is equal to str2.

   585 " );

   586    else if( result > 0 )

   587       printf( "str1 is greater than str2.

   588 " );

   589    return 0;    

   590 }

   591 

   592 @endcode

   593  Output

   594 @code

   595 Compare ’abcdefg’ to ’abcdefr

   596 str1 is less than str2.

   597 Compare ’abased’ to ’abcdef

   598 str1 is equal to str2.

   599 

   600 @endcode

   601 @see bcmp()

   602 @see memcmp()

   603 @see strcasecmp()

   604 @see strcoll()

   605 @see strxfrm()

   606 

   607 

   608  

   609 

   610 @publishedAll

   611 @externallyDefinedApi

   612 */

   613 

   614 /** @fn  strcoll(const char *s1, const char *s2)

   615 @param s1   

   616 @param s2      

   617 

   618   This function lexicographically compares the null-terminated strings s1 and s2 according to the current locale collation, if locale is set. 

   619   Calls strcmp and returns an integer greater than, equal to, or less than 0, to whether s1 is greater than, equal to, or less than s2 if C locale is set.

   620   Otherwise it will compare the strings according to the smartphone's locale collation.

   621 

   622 Examples:

   623 @code

   624 #include <string.h>

   625 #include <stdio.h>

   626 #include <locale.h>

   627 int main()

   628 {

   629     int res;

   630     setlocale(LC_ALL,"ar_AE.ISO-8859-6");

   631     if(strcoll("abcde","abcde")==0)

   632        printf("Strings are same

   633 ");

   634     return 0;

   635 }

   636 

   637 @endcode

   638  Output

   639 @code

   640 Strings are same

   641 

   642 @endcode

   643 @return   This  function  returns  an  integer  less than, equal to, or

   644 greater than zero if s1 is found, respectively, to  be  less  than,  to

   645 match,  or be greater than s2, when both are interpreted as appropriate

   646 for the current locale.

   647 

   648 @see setlocale()

   649 @see strcmp()

   650 @see strxfrm()

   651 @see wcscoll()

   652 

   653 

   654  

   655 

   656 @publishedAll

   657 @externallyDefinedApi

   658 */

   659 

   660 /** @fn  strcpy(char *  from, const char *  to)

   661 @param from

   662 @param to

   663 

   664 Refer to  stpcpy() for the documentation

   665 @see bcopy()

   666 @see memcpy()

   667 @see memmove()

   668 

   669 

   670  

   671 

   672 @publishedAll

   673 @externallyDefinedApi

   674 */

   675 

   676 /** @fn  strcspn(const char *s, const char *charset)

   677 @param s

   678 @param charset

   679 @return   The strcspn function

   680 returns the number of characters spanned.

   681 

   682   The strcspn function

   683 spans the initial part of the null-terminated string s as long as the characters from s do not occur in string charset (it

   684 spans the complement of charset). In other words, it computes the string array index in s of the first character of s which is also in charset, else the index of the first null character.

   685 

   686 Examples:

   687 @code

   688 #include <string.h>

   689 #include <stdio.h>

   690 int main()

   691 {

   692     printf("Number of characters present in s

   693  which are not in charset is %d",strcspn("abcde","df"));

   694     return 0;

   695 }

   696 

   697 @endcode

   698  Output

   699 @code

   700 Number of characters present in s

   701  which are not in charset is 3

   702 

   703 @endcode

   704 @see memchr()

   705 @see strchr()

   706 @see strpbrk()

   707 @see strrchr()

   708 @see strsep()

   709 @see strspn()

   710 @see strstr()

   711 @see strtok()

   712 

   713 

   714  

   715 

   716 @publishedAll

   717 @externallyDefinedApi

   718 */

   719 

   720 /** @fn  strdup(const char *str)

   721 @param str

   722 

   723   The strdup function

   724 allocates sufficient memory for a copy

   725 of the string str ,

   726 does the copy, and returns a pointer to it.

   727 The pointer may subsequently be used as an

   728 argument to the function free .

   729 

   730  If insufficient memory is available, NULL is returned and errno is set to ENOMEM .

   731 

   732 Examples:

   733 @code

   734 #include <string.h>

   735 #include <stdio.h>

   736 int main()

   737 {

   738     char* ptr;

   739     ptr = (char *)strdup("abcde");

   740     printf("Duplicated string %s

   741 ",ptr);

   742     ptr = (char *)strdup("Hello Hi");

   743     printf("Duplicated string %s

   744 ",ptr);

   745     return 0;   

   746 }

   747 

   748 @endcode

   749  Output

   750 @code

   751 Duplicated string abcde

   752 Duplicated string Hello Hi

   753 

   754 @endcode

   755 @return   The  strdup()  function  returns a pointer to the duplicated string, or

   756 NULL if insufficient memory was available.

   757 

   758 @see free()

   759 @see malloc()

   760 

   761 

   762  

   763 

   764 @publishedAll

   765 @externallyDefinedApi

   766 */

   767 

   768 /** @fn  strndup(const char *old, size_t sz)

   769 @param old

   770 @param sz

   771 

   772   The strndup function

   773 allocates sufficient memory for a copy

   774 of the string old ,

   775 does the copy of at most sz characters, and returns a pointer to it.

   776 If old is longer than sz, only sz characters are copied and a terminating NULL is added.

   777 The pointer may subsequently be used as an

   778 argument to the function free .

   779 

   780  If insufficient memory is available, NULL is returned and errno is set to ENOMEM .

   781 

   782 Examples:

   783 @code

   784 #include <string.h>

   785 #include <stdio.h>

   786 #include <stdlib.h>

   787 int main()

   788 {

   789     char* ptr;

   790     ptr = (char *)strndup("abcde",3);

   791     printf("Duplicated string %s

   792 ",ptr);

   793     ptr = (char *)strndup("Hello Hi",5);

   794     printf("Duplicated string %s

   795 ",ptr);

   796     free(ptr);

   797     return 0;   

   798 }

   799 

   800 @endcode

   801  Output

   802 @code

   803 Duplicated string abc

   804 Duplicated string Hello

   805 

   806 @endcode

   807 @return   The  strdup()  function  returns a pointer to the duplicated string, or

   808 NULL if insufficient memory was available.

   809 

   810 @see free()

   811 @see malloc()

   812 

   813 

   814  

   815 

   816 @publishedAll

   817 @externallyDefinedApi

   818 */

   819 

   820 /** @fn strnlen(const char *s, size_t len)

   821 @param s

   822 @param len

   823 

   824 @return The  strnlen function returns strlen(s), if that is less than len, or len if there is no "\\0" character among the first len characters pointed to by s.

   825 

   826 Examples:

   827 @code

   828 #include <string.h>

   829 #include <stdio.h>

   830 int main()

   831 {

   832     char one[50];

   833     int ret;

   834     strcpy(one,"abcdef");

   835     ret = strnlen(one,5);

   836     printf("Length obtained using strnlen = %d\n",ret);

   837     ret = strnlen(one,10);

   838     printf("Length obtained using strnlen = %d\n",ret);

   839 }

   840 

   841 @endcode

   842  Output

   843 @code

   844 Length obtained using strnlen = 5

   845 Length obtained using strnlen = 6

   846 

   847 @endcode

   848 Feedback For additional information or queries on this page send feedback

   849  

   850 

   851 @publishedAll

   852 @externallyDefinedApi

   853 */

   854 

   855 

   856 /** @fn  strerror(int num)

   857 @param num

   858 

   859 Refer to  perror() for the documentation

   860 @see intro()

   861 

   862 

   863  

   864 

   865 @publishedAll

   866 @externallyDefinedApi

   867 */

   868 

   869 /** @fn  strerror_r(int errnum, char *strerrbuf, size_t buflen)

   870 @param errnum

   871 @param strerrbuf

   872 @param buflen

   873 

   874 Refer to  perror() for the documentation

   875 @see intro()

   876 

   877 

   878  

   879 

   880 @publishedAll

   881 @externallyDefinedApi

   882 */

   883 

   884 /** @fn  strlcat(char *dst, const char *src, size_t size)

   885 @param dst

   886 @param src

   887 @param size

   888 

   889 Refer to  strlcpy() for the documentation

   890 @see snprintf()

   891 @see strncat()

   892 @see strncpy()

   893 

   894 

   895  

   896 

   897 @publishedAll

   898 @externallyDefinedApi

   899 */

   900 

   901 /** @fn  strlcpy(char *dst, const char *src, size_t size)

   902 @param dst

   903 @param src

   904 @param size

   905 

   906 Note: This description also covers the following functions -

   907  strlcat() 

   908 

   909 @return   The strlcpy and strlcat functions return the total length of the string they tried to

   910 create.

   911 For strlcpy that means the length of src .

   912 For strlcat that means the initial length of dst plus

   913 the length of src .

   914 While this may seem somewhat confusing it was done to make

   915 truncation detection simple. Note however, that if strlcat traverses size characters without finding a NULL, the length of the string is 

   916   considered to be size and the destination string will not be NULL-terminated (since there 

   917   was no space for the NULL). This prevents strlcat from running off the end of a string. In practice this should 

   918   not happen (as it means that either size is incorrect or that dst is not a proper "C" string). The check exists to prevent potential security problems in incorrect 

   919   code.

   920 

   921   The strlcpy and strlcat functions copy and concatenate strings respectively. They are 

   922 designed to be safer, more consistent, and less error prone replacements for strncpy and strncat. Unlike those functions, strlcpy and strlcat take the full size of the buffer (not just the length) and guarantee 

   923 to NULL-terminate the result (as long as size is larger than 0 or, in the case of strlcat , as long as there is at least one byte free in dst ). Note that you should include a byte for the NULL in size . Also note that strlcpy and strlcat only operate on true "C" strings. This means that for strlcpy src must be NUL-terminated and for strlcat both src and dst must be NULL-terminated.

   924 

   925  The strlcpy function copies up to size - 1 characters from the NULL-terminated string src to dst , NULL-terminating the result.

   926 

   927  The strlcat function appends the NULL-terminated string src to the end of dst . It will append at most size - strlen(dst) - 1 bytes, NULL-terminating the result.

   928 

   929 

   930 

   931 Examples:

   932  The following code fragment illustrates the simple case:

   933 @code

   934 char *s, *p, buf[BUFSIZ];

   935 ...

   936 (void)strlcpy(buf, s, sizeof(buf));

   937 (void)strlcat(buf, p, sizeof(buf));

   938 

   939 @endcode

   940  To detect truncation, perhaps while building a pathname, something

   941 like the following might be used:

   942 @code

   943 char *dir, *file, pname[MAXPATHLEN];

   944 ...

   945 if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))

   946         goto toolong;

   947 if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))

   948         goto toolong;

   949 

   950 @endcode

   951  Since we know how many characters we copied the first time, we can

   952 speed things up a bit by using a copy instead of an append:

   953 @code

   954 char *dir, *file, pname[MAXPATHLEN];

   955 size_t n;

   956 ...

   957 n = strlcpy(pname, dir, sizeof(pname));

   958 if (n >= sizeof(pname))

   959         goto toolong;

   960 if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)

   961         goto toolong;

   962 

   963 @endcode

   964  However, one may question the validity of such optimizations, as they

   965 defeat the whole purpose of strlcpy and strlcat .

   966 As a matter of fact, the first version of this manual page got it wrong.

   967 Examples:

   968 @code

   969 #include <string.h>

   970 #include <stdio.h>

   971 int main()

   972 {

   973     char one[50] = {"abcdefgh"};

   974     printf("String before strcpy %s

   975 ",one);

   976     strlcpy(one,"Hello");

   977     printf("String after strcpy %s

   978 ",one);

   979     strlcpy(one + 5, " ",1);

   980     strlcpy(one + 6, "World",5);

   981     printf("String after strncpy %s

   982 ",one);

   983     return 0;

   984 }

   985 

   986 @endcode

   987 @see snprintf()

   988 @see strncat()

   989 @see strncpy()

   990 

   991 

   992  

   993 

   994 @publishedAll

   995 @externallyDefinedApi

   996 */

   997 

   998 /** @fn  strlen(const char *str)

   999 @param str

  1000 @return  The strlen() function shall return the length of s; no return value shall be reserved to indicate an error.

  1001 

  1002 The strlen() function shall compute the number of bytes in the string to which s points,

  1003  not including the terminating null byte.

  1004 

  1005 Examples:

  1006 @code

  1007 #include <string.h>

  1008 #include <stdio.h>

  1009 int main()

  1010 {

  1011     char one[50];

  1012     int ret;

  1013     strcpy(one,"abcdef");

  1014     ret = strnlen(one,5);

  1015     printf("Length obtained using strnlen = %d

  1016 ",ret);

  1017     ret = strnlen(one,10);

  1018     printf("Length obtained using strnlen = %d

  1019 ",ret);

  1020 }

  1021 

  1022 @endcode

  1023  Output

  1024 @code

  1025 Length obtained using strnlen = 5

  1026 Length obtained using strnlen = 6

  1027 @endcode

  1028 

  1029  

  1030 

  1031 @publishedAll

  1032 @externallyDefinedApi

  1033 */

  1034 

  1035 /** @fn  strncat(char * dst, const char * src, size_t n)

  1036 @param dst

  1037 @param src

  1038 @param n

  1039 

  1040 Refer to  strcat() for the documentation

  1041 @see bcopy()

  1042 @see memcpy()

  1043 @see memmove()

  1044 @see strcpy()

  1045 

  1046 

  1047  

  1048 

  1049 @publishedAll

  1050 @externallyDefinedApi

  1051 */

  1052 

  1053 /** @fn  strncmp(const char *s1, const char *s2, size_t n)

  1054 @param s1

  1055 @param s2

  1056 @param n

  1057 

  1058 Refer to  strcmp() for the documentation

  1059 @see bcmp()

  1060 @see memcmp()

  1061 @see strcasecmp()

  1062 @see strcoll()

  1063 @see strxfrm()

  1064 

  1065 

  1066  

  1067 

  1068 @publishedAll

  1069 @externallyDefinedApi

  1070 */

  1071 

  1072 /** @fn  strncpy(char *  dst, const char *  src, size_t n)

  1073 @param dst

  1074 @param src

  1075 @param n

  1076 

  1077 Refer to  stpcpy() for the documentation

  1078 @see bcopy()

  1079 @see memcpy()

  1080 @see memmove()

  1081 

  1082 

  1083  

  1084 

  1085 @publishedAll

  1086 @externallyDefinedApi

  1087 */

  1088 

  1089 /** @fn  strnstr(const char *s, const char *find, size_t slen)

  1090 @param s

  1091 @param find

  1092 @param slen

  1093 

  1094 Refer to  strstr() for the documentation

  1095 @see memchr()

  1096 @see strchr()

  1097 @see strcspn()

  1098 @see strpbrk()

  1099 @see strrchr()

  1100 @see strsep()

  1101 @see strspn()

  1102 @see strtok()

  1103 

  1104 

  1105  

  1106 

  1107 @publishedAll

  1108 @externallyDefinedApi

  1109 */

  1110 

  1111 /** @fn  strpbrk(const char *s1, const char *s2)

  1112 @param s1

  1113 @param s2

  1114 

  1115   The strpbrk function

  1116 locates in the null-terminated string s1 the first occurrence of any character in the string s2 and returns a pointer to this character.

  1117 If no characters from s2 occur anywhere in s1 strpbrk returns NULL.

  1118 

  1119 Examples:

  1120 @code

  1121 #include <string.h>

  1122 #include <stdio.h>

  1123 int main()

  1124 {

  1125     char one[50];

  1126     char *res;

  1127     strcpy(one,"acdb");

  1128     res = strpbrk(one, "bc");

  1129     if(res != NULL)

  1130        printf("%s

  1131 ",res);

  1132     return 0;

  1133 }

  1134