4.11 STRING HANDLING 4.11.1 String function conventions The header declares one type and several functions, and defines one macro useful for manipulating arrays of character type and other objects treated as arrays of character type./119/ The type is size_t and the macro is NULL (both described in $4.1.5). Various methods are used for determining the lengths of the arrays, but in all cases a char * or void * argument points to the initial (lowest addressed) character of the array. If an array is accessed beyond the end of an object, the behavior is undefined. 4.11.2 Copying functions 4.11.2.1 The memcpy function Synopsis #include void *memcpy(void *s1, const void *s2, size_t n); Description The memcpy function copies n characters from the object pointed to by s2 into the object pointed to by s1 . If copying takes place between objects that overlap, the behavior is undefined. Returns The memcpy function returns the value of s1 . 4.11.2.2 The memmove function Synopsis #include void *memmove(void *s1, const void *s2, size_t n); Description The memmove function copies n characters from the object pointed to by s2 into the object pointed to by s1 . Copying takes place as if the n characters from the object pointed to by s2 are first copied into a temporary array of n characters that does not overlap the objects pointed to by s1 and s2 , and then the n characters from the temporary array are copied into the object pointed to by s1 . Returns The memmove function returns the value of s1 . 4.11.2.3 The strcpy function Synopsis #include char *strcpy(char *s1, const char *s2); Description The strcpy function copies the string pointed to by s2 (including the terminating null character) into the array pointed to by s1 . If copying takes place between objects that overlap, the behavior is undefined. Returns The strcpy function returns the value of s1 . 4.11.2.4 The strncpy function Synopsis #include char *strncpy(char *s1, const char *s2, size_t n); Description The strncpy function copies not more than n characters (characters that follow a null character are not copied) from the array pointed to by s2 to the array pointed to by s1 . If copying takes place between objects that overlap, the behavior is undefined. 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. Returns The strncpy function returns the value of s1 . 4.11.3 Concatenation functions 4.11.3.1 The strcat function Synopsis #include char *strcat(char *s1, const char *s2); Description The strcat function appends a copy of the string pointed to by s2 (including the terminating null character) to the end of the string pointed to by s1 . The initial character of s2 overwrites the null character at the end of s1 . If copying takes place between objects that overlap, the behavior is undefined. Returns The strcat function returns the value of s1 . 4.11.3.2 The strncat function Synopsis #include char *strncat(char *s1, const char *s2, size_t n); Description The strncat function appends not more than n characters (a null character and characters that follow it are not appended) from the array pointed to by s2 to the end of the string pointed to by s1 . The initial character of s2 overwrites the null character at the end of s1 . A terminating null character is always appended to the result. If copying takes place between objects that overlap, the behavior is undefined. Returns The strncat function returns the value of s1 . Forward references: the strlen function ($4.11.6.3). 4.11.4 Comparison functions The sign of a nonzero value returned by the comparison functions is determined by the sign of the difference between the values of the first pair of characters (both interpreted as unsigned char ) that differ in the objects being compared. 4.11.4.1 The memcmp function Synopsis #include int memcmp(const void *s1, const void *s2, size_t n); Description The memcmp function compares the first n characters of the object pointed to by s1 to the first n characters of the object pointed to by s2 . Returns The memcmp function returns an integer greater than, equal to, or less than zero, according as the object pointed to by s1 is greater than, equal to, or less than the object pointed to by s2 . 4.11.4.2 The strcmp function Synopsis #include int strcmp(const char *s1, const char *s2); Description The strcmp function compares the string pointed to by s1 to the string pointed to by s2 . Returns The strcmp function returns an integer greater than, equal to, or less than zero, according as the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2 . 4.11.4.3 The strcoll function Synopsis #include int strcoll(const char *s1, const char *s2); Description The strcoll function compares the string pointed to by s1 to the string pointed to by s2 , both interpreted as appropriate to the LC_COLLATE category of the current locale. Returns The strcoll function returns an integer greater than, equal to, or less than zero, according as the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2 when both are interpreted as appropriate to the current locale. 4.11.4.4 The strncmp function Synopsis #include int strncmp(const char *s1, const char *s2, size_t n); Description The strncmp function compares not more than n characters (characters that follow a null character are not compared) from the array pointed to by s1 to the array pointed to by s2 . Returns The strncmp function returns an integer greater than, equal to, or less than zero, according as the possibly null-terminated array pointed to by s1 is greater than, equal to, or less than the possibly null-terminated array pointed to by s2 . 4.11.4.5 The strxfrm function Synopsis #include size_t strxfrm(char *s1, const char *s2, size_t n); Description The strxfrm function transforms the string pointed to by s2 and places the resulting string into the array pointed to by s1 . The transformation is such that if the strcmp function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the strcoll function applied to the same two original strings. No more than n characters are placed into the resulting array pointed to by s1 , including the terminating null character. If n is zero, s1 is permitted to be a null pointer. If copying takes place between objects that overlap, the behavior is undefined. Returns The strxfrm function returns the length of the transformed string (not including the terminating null character). If the value returned is n or more, the contents of the array pointed to by s1 are indeterminate. Example The value of the following expression is the size of the array needed to hold the transformation of the string pointed to by s . 1 + strxfrm(NULL, s, 0) 4.11.5 Search functions 4.11.5.1 The memchr function Synopsis #include void *memchr(const void *s, int c, size_t n); Description The memchr function locates the first occurrence of c (converted to an unsigned char ) in the initial n characters (each interpreted as unsigned char ) of the object pointed to by s . Returns The memchr function returns a pointer to the located character, or a null pointer if the character does not occur in the object. 4.11.5.2 The strchr function Synopsis #include char *strchr(const char *s, int c); Description The strchr function locates the first occurrence of c (converted to a char ) in the string pointed to by s . The terminating null character is considered to be part of the string. Returns The strchr function returns a pointer to the located character, or a null pointer if the character does not occur in the string. 4.11.5.3 The strcspn function Synopsis #include size_t strcspn(const char *s1, const char *s2); Description The strcspn function computes the length of the maximum initial segment of the string pointed to by s1 which consists entirely of characters not from the string pointed to by s2 . Returns The strcspn function returns the length of the segment. 4.11.5.4 The strpbrk function Synopsis #include char *strpbrk(const char *s1, const char *s2); Description The strpbrk function locates the first occurrence in the string pointed to by s1 of any character from the string pointed to by s2 . Returns The strpbrk function returns a pointer to the character, or a null pointer if no character from s2 occurs in s1 . 4.11.5.5 The strrchr function Synopsis #include char *strrchr(const char *s, int c); Description The strrchr function locates the last occurrence of c (converted to a char ) in the string pointed to by s . The terminating null character is considered to be part of the string. Returns The strrchr function returns a pointer to the character, or a null pointer if c does not occur in the string. 4.11.5.6 The strspn function Synopsis #include size_t strspn(const char *s1, const char *s2); Description The strspn function computes the length of the maximum initial segment of the string pointed to by s1 which consists entirely of characters from the string pointed to by s2 . Returns The strspn function returns the length of the segment. 4.11.5.7 The strstr function Synopsis #include char *strstr(const char *s1, const char *s2); Description The strstr function locates the first occurrence in the string pointed to by s1 of the sequence of characters (excluding the terminating null character) in the string pointed to by s2 Returns The strstr function returns a pointer to the located string, or a null pointer if the string is not found. If s2 points to a string with zero length, the function returns s1 . 4.11.5.8 The strtok function Synopsis #include char *strtok(char *s1, const char *s2); Description A sequence of calls to the strtok function breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a character from the string pointed to by s2 . The first call in the sequence has s1 as its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by s2 may be different from call to call. The first call in the sequence searches the string pointed to by s1 for the first character that is not contained in the current separator string pointed to by s2 . If no such character is found, then there are no tokens in the string pointed to by s1 and the strtok function returns a null pointer. If such a character is found, it is the start of the first token. The strtok function then searches from there for a character that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by s1 , and subsequent searches for a token will return a null pointer. If such a character is found, it is overwritten by a null character, which terminates the current token. The strtok function saves a pointer to the following character, from which the next search for a token will start. 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. The implementation shall behave as if no library function calls the strtok function. Returns The strtok function returns a pointer to the first character of a token, or a null pointer if there is no token. Example #include static char str[] = "?a???b,,,#c"; char *t; t = strtok(str, "?"); /* t points to the token "a" */ t = strtok(NULL, ","); /* t points to the token "??b" */ t = strtok(NULL, "#,"); /* t points to the token "c" */ t = strtok(NULL, "?"); /* t is a null pointer */ 4.11.6 Miscellaneous functions 4.11.6.1 The memset function Synopsis #include void *memset(void *s, int c, size_t n); Description The memset function copies the value of c (converted to an unsigned char ) into each of the first n characters of the object pointed to by s . Returns The memset function returns the value of s . 4.11.6.2 The strerror function Synopsis #include char *strerror(int errnum); Description The strerror function maps the error number in errnum to an error message string. The implementation shall behave as if no library function calls the strerror function. Returns The strerror function returns a pointer to the string, the contents of which are implementation-defined. The array pointed to shall not be modified by the program, but may be overwritten by a subsequent call to the strerror function. 4.11.6.3 The strlen function Synopsis #include size_t strlen(const char *s); Description The strlen function computes the length of the string pointed to by s . Returns The strlen function returns the number of characters that precede the terminating null character. 4.12 DATE AND TIME 4.12.1 Components of time The header defines two macros, and declares four types and several functions for manipulating time. Many functions deal with a calendar time that represents the current date (according to the Gregorian calendar) and time. Some functions deal with local time ,which is the calendar time expressed for some specific time zone, and with Daylight Saving Time ,which is a temporary change in the algorithm for determining local time. The local time zone and Daylight Saving Time are implementation-defined. The macros defined are NULL (described in $4.1.5); and CLK_TCK which is the number per second of the value returned by the clock function. The types declared are size_t (described in $4.1.5); clock_t and time_t which are arithmetic types capable of representing times; and struct tm which holds the components of a calendar time, called the broken-down time .The structure shall contain at least the following members, in any order. The semantics of the members and their normal ranges are expressed in the comments./123/ int tm_sec; /* seconds after the minute --- [0, 60] */ int tm_min; /* minutes after the hour --- [0, 59] */ int tm_hour; /* hours since midnight --- [0, 23] */ int tm_mday; /* day of the month --- [1, 31] */ int tm_mon; /* months since January --- [0, 11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday --- [0, 6] */ int tm_yday; /* days since January 1 --- [0, 365] */ int tm_isdst; /* Daylight Saving Time flag */ The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight Saving Time is not in effect, and negative if the information is not available. 4.12.2 Time manipulation functions 4.12.2.1 The clock function Synopsis #include clock_t clock(void); Description The clock function determines the processor time used. Returns The clock function returns the implementation's best approximation to the processor time used by the program since the beginning of an implementation-defined era related only to the program invocation. To determine the time in seconds, the value returned by the clock function should be divided by the value of the macro CLK_TCK . If the processor time used is not available or its value cannot be represented, the function returns the value (clock_t)-1 . 4.12.2.2 The difftime function Synopsis #include double difftime(time_t time1, time_t time0); Description The difftime function computes the difference between two calendar times: time1 - time0 . Returns The difftime function returns the difference expressed in seconds as a double . 4.12.2.3 The mktime function Synopsis #include time_t mktime(struct tm *timeptr); Description The mktime function converts the broken-down time, expressed as local time, in the structure pointed to by timeptr into a calendar time value with the same encoding as that of the values returned by the time function. The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated above. On successful completion, the values of the tm_wday and tm_yday components of the structure are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to the ranges indicated above; the final value of tm_mday is not set until tm_mon and tm_year are determined. Returns The mktime function returns the specified calendar time encoded as a value of type time_t . If the calendar time cannot be represented, the function returns the value (time_t)-1 . Example What day of the week is July 4, 2001? #include #include static const char *const wday[] = { "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "-unknown-" }; struct tm time_str; time_str.tm_year = 2001 - 1900; time_str.tm_mon = 7 - 1; time_str.tm_mday = 4; time_str.tm_hour = 0; time_str.tm_min = 0; time_str.tm_sec = 1; time_str.tm_isdst = -1; if (mktime(&time_str) =^= -1) time_str.tm_wday = 7; printf("%s\n", wday[time_str.tm_wday]); 4.12.2.4 The time function Synopsis #include time_t time(time_t *timer); Description The time function determines the current calendar time. The encoding of the value is unspecified. Returns The time function returns the implementation's best approximation to the current calendar time. The value (time_t)-1 is returned if the calendar time is not available. If timer is not a null pointer, the return value is also assigned to the object it points to. 4.12.3 Time conversion functions Except for the strftime function, these functions return values in one of two static objects: a broken-down time structure and an array of char . Execution of any of the functions may overwrite the information returned in either of these objects by any of the other functions. The implementation shall behave as if no other library functions call these functions. 4.12.3.1 The asctime function Synopsis #include char *asctime(const struct tm *timeptr); Description The asctime function converts the broken-down time in the structure pointed to by timeptr into a string in the form Sun Sep 16 01:03:52 1973\n\0 using the equivalent of the following algorithm. char *asctime(const struct tm *timeptr) { static const char wday_name[7][3] = { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" }; static const char mon_name[12][3] = { "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" }; static char result[26]; sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n", wday_name[timeptr->tm_wday], mon_name[timeptr->tm_mon], timeptr->tm_mday, timeptr->tm_hour, timeptr->tm_min, timeptr->tm_sec, 1900 + timeptr->tm_year); return result; } Returns The asctime function returns a pointer to the string. 4.12.3.2 The ctime function Synopsis #include char *ctime(const time_t *timer); Description The ctime function converts the calendar time pointed to by timer to local time in the form of a string. It is equivalent to asctime(localtime(timer)) Returns The ctime function returns the pointer returned by the asctime function with that broken-down time as argument. Forward references: the localtime function ($4.12.3.4). 4.12.3.3 The gmtime function Synopsis #include struct tm *gmtime(const time_t *timer); Description The gmtime function converts the calendar time pointed to by timer into a broken-down time, expressed as Coordinated Universal Time (UTC). Returns The gmtime function returns a pointer to that object, or a null pointer if UTC is not available. 4.12.3.4 The localtime function Synopsis #include struct tm *localtime(const time_t *timer); Description The localtime function converts the calendar time pointed to by timer into a broken-down time, expressed as local time. Returns The localtime function returns a pointer to that object. 4.12.3.5 The strftime function Synopsis #include size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr); Description The strftime function places characters into the array pointed to by s as controlled by the string pointed to by format . The format shall be a multibyte character sequence, beginning and ending in its initial shift state. The format string consists of zero or more conversion specifications and ordinary multibyte characters. A conversion specification consists of a % character followed by a character that determines the conversion specification's behavior. All ordinary multibyte characters (including the terminating null character) are copied unchanged into the array. If copying takes place between objects that overlap, the behavior is undefined. No more than maxsize characters are placed into the array. Each conversion specification is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the program's locale and by the values contained in the structure pointed to by timeptr . is replaced by the locale's abbreviated weekday name. is replaced by the locale's full weekday name. is replaced by the locale's abbreviated month name. is replaced by the locale's full month name. is replaced by the locale's appropriate date and time representation. is replaced by the day of the month as a decimal number ( 01 - 31 ). is replaced by the hour (24-hour clock) as a decimal number ( 00 - 23 ). is replaced by the hour (12-hour clock) as a decimal number ( 01 - 12 ). is replaced by the day of the year as a decimal number ( 001 - 366 ). is replaced by the month as a decimal number ( 01 - 12 ). is replaced by the minute as a decimal number ( 00 - 59 ). is replaced by the locale's equivalent of either AM or PM . is replaced by the second as a decimal number ( 00 - 60 ). is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number ( 00 - 53 ). is replaced by the weekday as a decimal number [ 0 (Sunday)- 6 ]. is replaced by the week number of the year (Monday as the first day of the week) as a decimal number ( 00 - 53 ). is replaced by the locale's appropriate date representation. is replaced by the locale's appropriate time representation. is replaced by the year without century as a decimal number ( 00 - 99 ). is replaced by the year with century as a decimal number. is replaced by the time zone name, or by no characters if no time zone is determinable. is replaced by % . If a conversion specification is not one of the above, the behavior is undefined. Returns If the total number of resulting characters including the terminating null character is not more than maxsize , the strftime function returns the number of characters placed into the array pointed to by s not including the terminating null character. Otherwise, zero is returned and the contents of the array are indeterminate. 4.13 FUTURE LIBRARY DIRECTIONS The following names are grouped under individual headers for convenience. All external names described below are reserved no matter what headers are included by the program. 4.13.1 Errors Macros that begin with E and a digit or E and an upper-case letter (followed by any combination of digits, letters and underscore) may be added to the declarations in the header. 4.13.2 Character handling Function names that begin with either is or to , and a lower-case letter (followed by any combination of digits, letters and underscore) may be added to the declarations in the header. 4.13.3 Localization Macros that begin with LC_ and an upper-case letter (followed by any combination of digits, letters and underscore) may be added to the definitions in the header. 4.13.4 Mathematics The names of all existing functions declared in the header, suffixed with f or l , are reserved respectively for corresponding functions with float and long double arguments and return values. 4.13.5 Signal handling Macros that begin with either SIG and an upper-case letter or SIG_ and an upper-case letter (followed by any combination of digits, letters and underscore) may be added to the definitions in the header. 4.13.6 Input/output Lower-case letters may be added to the conversion specifiers in fprintf and fscanf . Other characters may be used in extensions. 4.13.7 General utilities Function names that begin with str and a lower-case letter (followed by any combination of digits, letters and underscore) may be added to the declarations in the header. 4.13.8 String handling Function names that begin with str , mem , or wcs and a lower-case letter (followed by any combination of digits, letters and underscore) may be added to the declarations in the header.