7.4.13 <string.h>

Defines functions for handling character arrays.

Type

Definition Name

Description

Function

memcpy

Copies contents of a source storage area of a specified length to a destination storage area.

strcpy

Copies contents of a source string including the null character to a destination storage area.

strncpy

Copies a source string of a specified length to a destination storage area.

strcat

Concatenates a string after another string.

strncat

Concatenates a string of a specified length after another string.

memcmp

Compares two storage areas specified.

strcmp

Compares two strings specified.

strncmp

Compares two strings specified for a specified length.

memchr

Searches a specified storage area for the first occurrence of a specified character.

strchr

Searches a specified string for the first occurrence of a specified character.

strcspn

Checks a specified string from the beginning and counts the number of consecutive characters at the beginning that are not included in another string specified.

strpbrk

Searches a specified string for the first occurrence of any character that is included in another string specified.

strrchr

Searches a specified string for the last occurrence of a specified character.

strspn

Checks a specified string from the beginning and counts the number of consecutive characters at the beginning that are included in another string specified.

strstr

Searches a specified string for the first occurrence of another string specified.

strtok

Divides a specified string into some tokens.

memset

Sets a specified character for a specified number of times at the beginning of a specified storage area.

strerror

Sets an error message.

strlen

Calculates the length of a string.

memmove

Copies contents of a source storage area of a specified length to a destination storage area. Even if a part of the source storage area and a part of the destination storage area overlap, correct copy is performed.

Implementation-Defined Specifications

Item

Compiler Specifications

Error message returned by the strerror function

Refer to section 11.3, Standard Library Error Messages.

 

When using functions defined in this standard include file, note the following.

(1) On copying a string, if the destination area is smaller than the source area, correct operation is not guaranteed.

Example

   char a[]="abc";
   char b[3];
         .
         .
         .
   strcpy (b, a);

In the above example, the size of array a (including the null character) is 4 bytes. Copying by strcpy overwrites data beyond the boundary of array b.

 

(2) On copying a string, if the source area overlaps the destination area, correct operation is not guaranteed.

Example

   int a[ ]="a";
       :
       :
   strcpy(&a[1], a);
       :

In the above example, before the null character of the source is read, 'a' is written over the null character. Then the subsequent data after the source string is overwritten in succession.

 

memcpy

Copies the contents of a source storage area of a specified length to a destination storage area.

[Format]

#include <string.h>
void *memcpy (void *s1, const void *s2, size_t n);

[Parameters]

s1 Pointer to destination storage area

s2 Pointer to source storage area

n Number of characters to be copied

[Return values]

s1 value

 

strcpy

Copies the contents of a source string including the null character to a destination storage area.

[Format]

#include <string.h>
char *strcpy (char *s1, const char *s2);

[Parameters]

s1 Pointer to destination storage area

s2 Pointer to source string

[Return values]

s1 value

 

strncpy

Copies a source string of a specified length to a destination storage area.

[Format]

#include <string.h>
char *strncpy (char *s1, const char *s2, size_t n);

[Parameters]

s1 Pointer to destination storage area

s2 Pointer to source string

n Number of characters to be copied

[Return values]

s1 value

[Remarks]

The strncpy function copies up to n characters from the beginning of the string pointed by s2 to a storage area pointed by s1. If the length of the string specified by s2 is shorter than n characters, the function elongates the string to the length by padding with null characters.

If the length of the string specified by s2 is longer than n characters, the copied string in s1 storage area ends with a character other than the null character.

 

strcat

Concatenates a string after another string.

[Format]

#include <string.h>
char *strcat (char *s1, const char *s2);

[Parameters]

s1 Pointer to the string after which another string is appended

s2 Pointer to the string to be appended after the other string

[Return values]

s1 value

[Remarks]

The strcat function concatenates the string specified by s2 at the end of another string specified by s1. The null character indicating the end of the s2 string is also copied. The null character at the end of the s1 string is deleted.

 

strncat

Concatenates a string of a specified length after another string.

[Format]

#include <string.h>
char *strncat (char *s1, const char *s2, size_t n);

[Parameters]

s1 Pointer to the string after which another string is appended

s2 Pointer to the string to be appended after the other string

n Number of characters to concatenate

[Return values]

s1 value

[Remarks]

The strncat function concatenates up to n characters from the beginning of the string specified by s2 at the end of another string specified by s1. The null character at the end of the s1 string is replaced by the first character of the s2 string. A null character is appended to the end of the concatenated string.

 

memcmp

Compares the contents of two storage areas specified.

[Format]

#include <string.h>
long memcmp (const void *s1, const void *s2, size_t n);

[Parameters]

s1 Pointer to the reference storage area to be compared

s2 Pointer to the storage area to compare to the reference

n Number of characters to compare

[Return values]

If storage area pointed by s1 > storage area pointed by s2: Positive value

If storage area pointed by s1 == storage area pointed by s2: 0

If storage area pointed by s1 < storage area pointed by s2: Negative value

[Remarks]

The memcmp function compares the contents of the first n characters in the storage areas pointed by s1 and s2. The rules of comparison are implementation-defined.

 

strcmp

Compares the contents of two strings specified.

[Format]

#include <string.h>
long strcmp (const char *s1, const char *s2);

[Return values]

If string pointed by s1 > string pointed by s2: Positive value

If string pointed by s1 == string pointed by s2: 0

If string pointed by s1 < string pointed by s2: Negative value

[Parameters]

s1 Pointer to the reference string to be compared

s2 Pointer to the string to compare to the reference

[Remarks]

The strcmp function compares the contents of the strings pointed by s1 and s2, and sets up the comparison result as a return value. The rules of comparison are implementation-defined.

 

strncmp

Compares two strings specified up to a specified length.

[Format]

#include <string.h>
long strncmp (const char *s1, const char *s2, size_t n);

[Parameters]

s1 Pointer to the reference string to be compared

s2 Pointer to the string to compare to the reference

n Maximum number of characters to compare

[Return values]

If string pointed by s1 > string pointed by s2: Positive value

If string pointed by s1 == string pointed by s2: 0

If string pointed by s1 < string pointed by s2: Negative value

[Remarks]

The strncmp function compares the contents of the strings pointed by s1 and s2, up to n characters. The rules of comparison are implementation-defined.

 

memchr

Searches a specified storage area for the first occurrence of a specified character.

[Format]

#include <string.h>
void *memchr (const void *s, long c, size_t n);

[Parameters]

s Pointer to the storage area to be searched

c Character to search for

n Number of characters to search

[Return values]

If the character is found: Pointer to the found character

If the character is not found: NULL

[Remarks]

The memchr function searches the storage area specified by s from the beginning up to n characters, looking for the first occurrence of the character specified as c. If the c character is found, the function returns the pointer to the found character.

 

strchr

Searches a specified string for the first occurrence of a specified character.

[Format]

char *strchr (const char *s, long c);

[Parameters]

s Pointer to the string to be searched

c Character to search for

[Return values]

If the character is found: Pointer to the found character

If the character is not found: NULL

[Remarks]

The strchr function searches the string specified by s looking for the first occurrence of the character specified as c. If the c character is found, the function returns the pointer to the found character.

The null character at the end of the s string is included in the search object.

 

strcspn

Checks a specified string from the beginning and counts the number of consecutive characters at the beginning that are not included in another string specified.

[Format]

#include <string.h>
size_t strcspn (const char *s1, const char *s2);

[Parameters]

s1 Pointer to the string to be checked

s2 Pointer to the string used to check s1

[Return values]

Number of characters at the beginning of the s1 string that are not included in the s2 string

[Remarks]

The strcspn function checks from the beginning of the string specified by s1, counts the number of consecutive characters that are not included in another string specified by s2, and returns that length.

The null character at the end of the s2 string is not taken as a part of the s2 string.

 

strpbrk

Searches a specified string for the first occurrence of the character that is included in another string specified.

[Format]

#include <string.h>
char *strpbrk (const char *s1, const char *s2);

[Parameters]

s1 Pointer to the string to be searched

s2 Pointer to the string that indicates the characters to search s1 for

[Return values]

If the character is found: Pointer to the found character

If the character is not found: NULL

[Remarks]

The strpbrk function searches the string specified by s1 looking for the first occurrence of any character included in the string specified by s2. If any searched character is found, the function returns the pointer to the first occurrence.

 

strrchr

Searches a specified string for the last occurrence of a specified character.

[Format]

#include <string.h>
char *strrchr (const char *s, long c);

[Parameters]

s Pointer to the string to be searched

c Character to search for

[Return values]

If the character is found: Pointer to the found character

If the character is not found: NULL

[Remarks]

The strrchr function searches the string specified by s looking for the last occurrence of the character specified by c. If the c character is found, the function returns the pointer to the last occurrence of that character.

The null character at the end of the s string is included in the search objective.

 

strspn

Checks a specified string from the beginning and counts the number of consecutive characters at the beginning that are included in another string specified.

[Format]

#include <string.h>
size_t strspn (const char *s1, const char *s2);

[Parameters]

s1 Pointer to the string to be checked

s2 Pointer to the string used to check s1

[Return values]

Number of characters at the beginning of the s1 string that are included in the s2 string

[Remarks]

The strspn function checks from the beginning of the string specified by s1, counts the number of consecutive characters that are included in another string specified by s2, and returns that length.

 

strstr

Searches a specified string for the first occurrence of another string specified.

[Format]

#include <string.h>
char *strstr (const char *s1, const char *s2);

[Parameters]

s1 Pointer to the string to be searched

s2 Pointer to the string to search for

[Return values]

If the string is found: Pointer to the found string

If the string is not found: NULL

[Remarks]

The strstr function searches the string specified by s1 looking for the first occurrence of another string specified by s2, and returns the pointer to the first occurrence.

 

strtok

Divides a specified string into some tokens.

[Format]

#include <string.h>
char *strtok (char *s1, const char *s2);

[Return values]

If division into tokens is successful: Pointer to the first token divided

If division into tokens is unsuccessful: NULL

[Parameters]

s1 Pointer to the string to be divided into some tokens

s2 Pointer to the string representing string-dividing characters

[Remarks]

The strtok function should be repeatedly called to divide a string.

(a) First call
The string pointed by s1 is divided at a character included in the string pointed by s2. If a token has been separated, the function returns a pointer to the beginning of that token. Otherwise, the function returns NULL.

 

(b) Second and subsequent calls
Starting from the next character separated before as the token, the function repeats division at a character included in the string pointed by s2. If a token has been separated, the function returns a pointer to the beginning of that token. Otherwise, the function returns NULL.

At the second and subsequent calls, specify NULL as the first parameter. The string pointed by s2 can be changed at each call. The null character is appended at the end of a separated token.

An example of use of the strtok function is shown below.

Example

	1  #include <string.h>	2  static char s1[ ]="a@b, @c/@d";	3  char *ret;	4	5  ret = strtok(s1, "@");	6  ret = strtok(NULL, ",@");	7  ret = strtok(NULL, "/@");	8  ret = strtok(NULL, "@");

Explanation:

The above example program uses the strtok function to divide string "a@b, @c/@d" into tokens a, b, c, and d.

The second line specifies string "a@b, @c/@d" as an initial value for string s1.

The fifth line calls the strtok function to divide tokens using '@' as the delimiter. As a result, a pointer to character 'a' is returned, and the null character is embedded at '@,' the first delimiter after character 'a.' Thus string 'a' has been separated.

Specify NULL for the first parameter to consecutively separate tokens from the same string, and repeat calling the strtok function.

Consequently, the function separates strings 'b,' 'c,' and 'd.'

 

memset

Sets a specified character a specified number of times at the beginning of a specified storage area.

[Format]

#include <string.h>
void *memset (void *s, long c, size_t n);

[Parameters]

s Pointer to storage area to set characters in

c Character to be set

n Number of characters to be set

[Return values]

Value of s

[Remarks]

The memset function sets the character specified by c a number of times specified by n in the storage area specified by s.

 

strerror

Returns an error message corresponding to a specified error number.

[Format]

#include <string.h>
char *strerror (long s);

[Parameters]

s Error number

[Return values]

Pointer to the error message (string) corresponding to the specified error number

[Remarks]

The strerror function receives an error number specified by s and returns an error message corresponding to the number. Contents of error messages are implementation-defined.

If the returned error message is modified, correct operation is not guaranteed.

 

strlen

Calculates the length of a string.

[Format]

#include <string.h>
size_t strlen (const char *s);

[Parameters]

s Pointer to the string to check the length of

[Return values]

Number of characters in the string

[Remarks]

The null character at the end of the s string is excluded from the string length.

 

memmove

Copies the specified size of the contents of a source area to a destination storage area. If part of the source storage area and the destination storage area overlap, data is copied to the destination storage area before the overlapped source storage area is overwritten. Therefore, correct copy is enabled.

[Format]

#include <string.h>
void *memmove (void *s1, const void *s2, size_t n);

[Parameters]

s1 Pointer to the destination storage area

s2 Pointer to the source storage area

n Number of characters to be copied

[Return values]

Value of s1