STRING(3C) | Standard C Library Functions | STRING(3C) |
#include <strings.h> int strcasecmp(const char *s1, const char *s2);
int strcasecmp_l(const char *s1, const char *s2, locale_t loc);
int strncasecmp(const char *s1, const char *s2, size_t n);
int strncasecmp_l(const char *s1, const char *s2, size_t n, locale_t loc);
#include <string.h> char *strcat(char *restrict s1, const char *restrict s2);
char *strncat(char *restrict s1, const char *restrict s2, size_t n);
size_t strlcat(char *dst, const char *src, size_t dstsize);
char *strchr(const char *s, int c);
char *strrchr(const char *s, int c);
int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, size_t n);
char *stpcpy(char *restrict s1, const char *restrict s2);
char *stpncpy(char *restrict s1, const char *restrict s2, size_t n);
char *strcpy(char *restrict s1, const char *restrict s2);
char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
size_t strlcpy(char *dst, const char *src, size_t dstsize);
size_t strcspn(const char *s1, const char *s2);
size_t strspn(const char *s1, const char *s2);
char *strdup(const char *s1);
char *strndup(const char *s1, size_t n);
char *strdupa(const char *s1);
char *strndupa(const char *s1, size_t n);
size_t strlen(const char *s);
size_t strnlen(const char *s, size_t n);
char *strpbrk(const char *s1, const char *s2);
char *strsep(char **stringp, const char *delim);
char *strstr(const char *s1, const char *s2);
char *strnstr(const char *s1, const char *s2, size_t n);
char *strcasestr(const char *s1, const char *s2);
char *strcasestr_l(const char *s1, const char *s2, locale_t loc);
char *strtok(char *restrict s1, const char *restrict s2);
char *strtok_r(char *restrict s1, const char *restrict s2, char **restrict lasts);
#include <string.h> const char *strchr(const char *s, int c);
const char *strchrnul(const char *s, int c);
const char *strpbrk(const char *s1, const char *s2);
const char *strrchr(const char *s, int c);
const char *strstr(const char *s1, const char *s2);
#include <cstring> char *std::strchr(char *s, int c);
char *std::strpbrk(char *s1, const char *s2);
char *std::strrchr(char *s, int c);
char *std::strstr(char *s1, const char *s2);
The strcasecmp() and strncasecmp() functions compare two strings byte-by-byte, after converting each upper-case character to lower-case (as determined by the LC_CTYPE category of the current locale). Note that neither the contents pointed to by s1 nor s2 are modified.
The functions return an integer greater than, equal to, or less than 0, if the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2 respectively. The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes that differ in the
The strncasecmp() function examines at most n bytes from each string.
The strlcat() function appends at most (dstsize-strlen(dst)-1) characters of src to dst (dstsize being the size of the string buffer dst). If the string pointed to by dst contains a null-terminated string that fits into dstsize bytes when strlcat() is called, the string pointed to by dst will be a null-terminated string that fits in dstsize bytes (including the terminating null character) when it completes, and the initial character of src will override the null character at the end of dst. If the string pointed to by dst is longer than dstsize bytes when strlcat() is called, the string pointed to by dst will not be changed. The function returns min{dstsize,strlen(dst)}+strlen(src). Buffer overflow can be checked as follows:
if (strlcat(dst, src, dstsize) >= dstsize) return −1;
The strlcpy() function copies at most dstsize−1 characters (dstsize being the size of the string buffer dst) from src to dst, truncating src if necessary. The result is always null-terminated. The function returns strlen(src). Buffer overflow can be checked as follows:
if (strlcpy(dst, src, dstsize) >= dstsize) return −1;
The functions strdupa() and strndupa() behave identically to strdup() and strndup() respectively; however, instead of allocating memory using malloc(3C), they use alloca(3C). These functions are provided for compatibility only, their use is strongly discouraged due to their use of alloca(3C).
The strnlen() function returns the smaller of n or the number of bytes in s, not including the terminating null character. The strnlen() function never examines more than n bytes of the string pointed to by s.
An ``empty'' field (one caused by two adjacent delimiter characters) can be detected by comparing the location referenced by the pointer returned by strsep() to `\0'.
If *stringp is initially NULL, strsep() returns NULL.
The strcasestr() and strcasestr_l() functions are similar to strstr(), but both functions ignore the case of both s1 and s2. Where as the strcasestr() function operates in the current locale, the strcasestr_l() function operates in the locale specified by loc.
The first call in the sequence searches the string pointed to by s1 for the first byte that is not contained in the current separator string pointed to by s2. If no such byte is found, then there are no tokens in the string pointed to by s1 and strtok() returns a null pointer. If such a byte is found, it is the start of the first token.
The strtok() function then searches from there for a byte that is contained in the current separator string. If no such byte is found, the current token extends to the end of the string pointed to by s1, and subsequent searches for a token return a null pointer. If such a byte is found, it is overwritten by a null byte that terminates the current token. The strtok() function saves a pointer to the following byte in thread-specific data, from which the next search for a token starts.
Each subsequent call, with a null pointer as the value of the first argument, starts searching from the saved pointer and behaves as described above.
See Example 1, 2, and 3 in the EXAMPLES section for examples of strtok() usage and the explanation in NOTES.
In the first call to strtok_r(), s1 points to a null-terminated string, s2 to a null-terminated string of separator characters, and the value pointed to by lasts is ignored. The strtok_r() function returns a pointer to the first character of the first token, writes a null character into s1 immediately following the returned token, and updates the pointer to which lasts points.
In subsequent calls, s1 is a null pointer and lasts is unchanged from the previous call so that subsequent calls move through the string s1, returning successive tokens until no tokens remain. The separator string s2 can be different from call to call. When no token remains in s1, a null pointer is returned.
See Example 3 in the EXAMPLES section for an example of strtok_r() usage and the explanation in NOTES.
The following example searches for tokens separated by space characters.
#include <string.h> ... char *token; char line[] = "LINE TO BE SEPARATED"; char *search = " "; /* Token will point to "LINE". */ token = strtok(line, search); /* Token will point to "TO". */ token = strtok(NULL, search);
Example 2 Break a Line.
The following example uses strtok to break a line into two character strings separated by any combination of SPACEs, TABs, or NEWLINEs.
#include <string.h> ... struct element { char *key; char *data; }; ... char line[LINE_MAX]; char *key, *data; ... key = strtok(line, " \n"); data = strtok(NULL, " \n");
Example 3 Search for tokens.
The following example uses both strtok() and strtok_r() to search for tokens separated by one or more characters from the string pointed to by the second argument, "/".
#define __EXTENSIONS__ #include <stdio.h> #include <string.h> int main() { char *buf="5/90/45"; char *token; char *lasts; printf("tokenizing \"%s\" with strtok():\n", buf); if ((token = strtok(buf, "/")) != NULL) { printf("token = "%s\"\n", token); while ((token = strtok(NULL, "/")) != NULL) { printf("token = \"%s\"\n", token); } } buf = "//5//90//45//"; printf("\ntokenizing \"%s\" with strtok_r():\n", buf); if ((token = strtok_r(buf, "/", &lasts)) != NULL) { printf("token = \"%s\"\n", token); while ((token = strtok_r(NULL, "/", &lasts)) != NULL) { printf("token = \"%s\"\n", token); } } }
When compiled and run, this example produces the following output:
tokenizing "5/90/45" with strtok(): token = "5" token = "90" token = "45" tokenizing "//5//90//45//" with strtok_r(): token = "5" token = "90" token = "45"
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
Interface Stability | See below. |
MT-Level | See below. |
Standard | See below. |
The strlcat(), strlcpy(), and strsep() functions are Committed. All the rest are Standard.
The strtok(), strdup(), and strndup() functions are MT-Safe. The remaining functions are Async-Signal-Safe.
For all except strlcat(), strlcpy(), and strsep(), see standards(7).
A single-threaded application can gain access to strtok_r() only by defining __EXTENSIONS__ or by defining _POSIX_C_SOURCE to a value greater than or equal to 199506L.
Except where noted otherwise, all of these functions assume the default locale ``C.'' For some locales, strxfrm(3C) should be applied to the strings before they are passed to the functions.
The strtok() function is safe to use in multithreaded applications because it saves its internal state in a thread-specific data area. However, its use is discouraged, even for single-threaded applications. The strtok_r() function should be used instead.
Do not pass the address of a character string literal as the argument s1 to either strtok() or strtok_r(). Similarly, do not pass a pointer to the address of a character string literal as the argument stringp to strsep(). These functions can modify the storage pointed to by s1 in the case of strtok() and strtok_r() or *stringp in the case of strsep(). The C99 standard specifies that attempting to modify the storage occupied by a string literal results in undefined behavior. This allows compilers (including gcc and the Sun Studio compilers when the -xstrconst flag is used) to place string literals in read-only memory. Note that in Example 1 above, this problem is avoided because the variable line is declared as a writable array of type char that is initialized by a string literal rather than a pointer to char that points to a string literal.
March 23, 2016 | OmniOS |