STRING(3C) Silicon Graphics STRING(3C) NAME string: strcat, strdup, strncat, strcmp, strncmp, strcasecmp, strncasecmp, strcpy, strncpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strstr, strcoll, strxfrm, index, rindex - string operations SYNOPSIS #include <string.h> char *strcat (char *s1, const char *s2); char *strdup (const char *s1); char *strncat (char *s1, const char *s2, size_t n); int strcmp (const char *s1, const char *s2); int strncmp (const char *s1, const char *s2, size_t n); int strcasecmp (const char *s1, const char *s2); int strncasecmp (const char *s1, const char *s2, size_t n); char *strcpy (char *s1, const char *s2); char *strncpy (char *s1, const char *s2, size_t n); size_t strlen (const char *s); char *strchr (const char *s, int c); char *strrchr (const char *s, int c); char *strpbrk (const char *s1, const char *s2); size_t strspn (const char *s1, const char *s2); size_t strcspn (const char *s1, const char *s2); char *strtok (char *s1, const char *s2); char *strstr (const char *s1, const char *s2); int strcoll (const char *s1, const char *s2); size_t strxfrm (const char *s1, const char *s2, size_t n); #include <strings.h> char *index (const char *s, int c); Page 1 Release 3.10 June 1992 STRING(3C) Silicon Graphics STRING(3C) char *rindex (const char *s, int c); DESCRIPTION The arguments s1, s2 and s point to strings (arrays of characters terminated by a null character). The functions strcat, strncat, strcpy, strxfrm, and strncpy all alter s1. These functions do not check for overflow of the array pointed to by s1, or for overlap between s1 and s2. If overflow of s1 occurs, or copying takes place when s1 and s2 overlap, the behavior is undefined. Strcat appends a copy of string s2 (including the terminating null character) to the end of string s1. The terminating null character of s1 is overwritten with the first character of s2. Strncat is similar to strcat, but appends at most n characters. The result is always null-terminated. Strcat and strncat each return s1. Strdup returns a pointer to a new string which is a duplicate of the string pointed to by s1. The space for the new string is obtained using malloc(3C,3X). If the new string cannot be created, NULL is returned. Strcmp compares its arguments and returns an integer less than, equal to, or greater than 0, indicating whether s1 is lexicographically less than, equal to, or greater than s2. Strncmp makes the same comparison but looks at no more than n characters. Strcasecmp and strncasecmp are identical in function, but are case-insensitive. The returned lexicographic difference reflects a conversion to lower-case. Strcpy copies string s2 to s1, stopping after the null character has been copied. It returns s1. Strncpy copies not more than n characters, (characters in s2 following a null character are not copied) from the array pointed to by s2 to the array pointed to by s1. The result will not be null-terminated if the length of s2 is n or more. If the array pointed to by s2 is a string that is shorter than n characters, null characters are appended to the copy in the array pointed to by s1 until n characters in all have been written. Strncpy returns s1. Strlen returns the number of characters in s, not including the terminating null character. Strchr (strrchr) returns a pointer to the first (last) occurrence of [the char value of] c in string s, or a NULL pointer if c does not occur in the string. For the purposes of strchr and strrchr, the terminating null character is considered part of the string. Index (rindex) are included as duplicates of strchr (strrchr) for compatibility (see Notes). Strpbrk 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. Page 2 Release 3.10 June 1992 STRING(3C) Silicon Graphics STRING(3C) Strspn (strcspn) returns the length of the initial segment of string s1 which consists entirely of characters from (not from) string s2. Strtok considers the string s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string s2. The first call (with pointer s1 specified) returns a pointer to the first character of the first token, and will have written a null character into s1 immediately following the token. Strtok saves a pointer to the first character following this null character. Subsequent calls made to strtok with NULL as the value of s1 continue the search from the last saved position, repeating the behavior described above. When no more tokens can be found, strtok returns NULL. The contents of the separator string s2 need not be constant between invocations of strtok, even when using a NULL s1. Strstr locates the first occurrence in the string s1 of the sequence of characters (excluding the terminating null character) in the string s2, returning a pointer to it (or NULL if s2 does not occur in s1). If s2 points to a string with zero length, strstr returns s1. Strcoll compares the string s1 to the string s2. It interprets the strings as appropriate for the LC_COLLATE category of the current locale, and returns an integer less than, equal to, or greater than 0, according as s1 is less than, equal to, or greater than s2 under this interpretation. Strxfrm transforms the string s2, placing the resulting string into the array s1. The transformation performed by strxfrm is such that if strcmp is given two strings transformed by strxfrm, it will return the same value as would the strcoll function applied to the original strings. No more than n characters are placed into the resulting array s1, including the terminating NULL character. If the value of n is zero, s1 is allowed to be NULL. Strxfrm returns the length of the transformed string, not including the terminating null character. If the value returned is n or more, the contents of s1 are indeterminate. All of these functions are declared in the <string.h> header file. NOTES Declarations for index and rindex are specifically omitted from <string.h> due to possible naming conflicts. Instead, they are declared in <strings.h>. The index, rindex, strcasecmp, strncasecmp routines are from the 4.3BSD or 4.3BSD-tahoe standard C library. SEE ALSO malloc(3C), malloc(3X), strerror(3C), memory(3C), setlocale(3C). CAVEATS Strcmp, strncmp, strcasecmp, and strncasecmp are implemented by using the most natural character comparison on the machine. Thus the sign of the Page 3 Release 3.10 June 1992 STRING(3C) Silicon Graphics STRING(3C) value returned when one of the characters has its high-order bit set not the same in all implementations and should not be relied upon. As character movement is performed differently in different implementations, copying operations between overlapping regions may produce different results. Page 4 Release 3.10 June 1992