char *getenv(const char *name);

• Searches an environment list provided by the host environment.
  See your DEC C library routine documentation for a detailed description of this function.

int *system(const char *string);

• Passes the string pointed to by string to the host environment for execution by a command processor. A null pointer can be specified to inquire whether a command processor exists. If the argument is a null pointer, the system function returns nonzero if a command processor is available or 0 if one is not available. If the argument is not a null pointer, the return value is the status returned by the command processor or 0 if a command processor is not available.
  See your DEC C library routine documentation for a detailed description of this function.

Searching and Sorting Utilities

void *bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *));

• Searches an array of nmemb objects for an element that matches the object pointed to by key. The first element of the array is pointed to by base; the size of each element is specified by size.
  You must first sort the array in ascending order according to the function pointed to by compar. The bsearch function calls the specified comparison function pointed to by compar with two arguments that point to the objects being compared (the key object and an array element). The comparison function returns:
  • An integer less than 0, if the first argument is less than the second argument
  • An integer greater than 0, if the first argument is greater than the second argument
  • An integer equal to 0, if the first argument equals the second argument
  
  The bsearch function returns a pointer to the matching element of the array, or a null pointer if no match is found.

void qsort(void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *));

• Sorts an array of nmemb objects in place. The first element of the array is pointed to by base; the size of each element is specified by size.
  The contents of the array are sorted in ascending order according to a comparison function pointed to by compar, which is called with two arguments that point to the objects being compared. The comparison function returns:
  • An integer less than 0, if the first argument is less than the second argument
  • An integer greater than 0, if the first argument is greater than the second argument
  • An integer equal to 0, if the first argument equals the second argument
  
  If two compared elements are equal, their order in the sorted array is unspecified.
  The qsort function returns no value.

Integer Arithmetic Functions

int abs(int j);

• Returns the absolute value of an integer j.

div_t div(int numer, int denom);

• Computes the quotient and remainder of the division of numer by denom. The div function returns a structure of type div_t containing the quotient and remainder:

  int quot; /* quotient */ int rem; /* remainder */

long int labs(long int j);

• Returns the absolute value of a long integer j.

ldiv_t ldiv(long int numer, long int denom);

• Similar to the div function, except that the arguments and the members of the returned structure (which has type ldiv_t) all have type long int.

Multibyte Character Functions

int mblen(const char *s, size_t n);

• If s is not a null pointer, mblen determines the number of bytes comprising the multibyte character pointed to by s. The mblen function is equivalent to the following, except that the shift state of the mbtowc is not affected:

  mbtowc((wchar_t *)0, s, n);

  
  If s is a null pointer, the mblen function returns a nonzero value if multibyte character encodings have state-dependent encodings, and 0 if they do not.
  If s is not a null pointer, the mblen function returns one of the following values:

  • 0, if s points to the null character
  • The number of bytes that comprise the multibyte character, if the next n or fewer bytes form a valid multibyte character
  • --1, if they do not form a valid multibyte character

int mbtowc(wchar_t *pwc, const char *s, size_t n);

• If s is not a null pointer, mbtowc determines the number of bytes comprising the multibyte character pointed to by s. It then determines the code for the value of type wchar_t that corresponds to that multibyte character. (The value of the code corresponding to the null character is 0.) If the multibyte character is valid and pwc is not a null pointer, mbtowc stores the code in the object pointed to by pwc. At most, n bytes of the array pointed to by s are examined.
  If s is a null pointer, the mbtowc function returns a nonzero value if multibyte character encodings have state-dependent encodings, and 0 if they do not.
  If s is not a null pointer, the mbtowc function returns one of the following values:
  • 0, if s points to the null character
  • The number of bytes that comprise the converted multibyte character, if the next n or fewer bytes form a valid multibyte character
  • --1, if they do not form a valid multibyte character

int wctomb(char *s, wchar_t wchar);

• Determines the number of bytes needed to represent the multibyte character corresponding to the code whose value is wchar, including any change in shift state. This function then stores the multibyte character representation in the array object pointed to by s, if s is not a null pointer. At most, MB_CUR_MAX characters are stored. If the value of wchar is 0, the wctomb function is left in the initial shift state.
  If s is a null pointer, the wctomb function returns a nonzero value if multibyte character encodings have state-dependent encodings, and 0 if they do not.
  If s is not a null pointer, the wctomb function returns one of the following values:
  • --1, if the value of wchar does not correspond to a valid multibyte character
  • the number of bytes that comprise the multibyte character corresponding to the value of wchar

Multibyte String Functions

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);

• Converts a sequence of multibyte characters that begin in the initial shift state from the array pointed to by s into a sequence of corresponding codes, and stores not more than n codes into the array pointed to by pwcs. A null character is converted to a code value of zero. No multibyte characters that follow a null character are examined or converted. Each multibyte character is converted as if by a call to mbtowc, except that the shift state of mbtowc is not affected.
  If an invalid multibyte character is encountered, the mbstowcs function returns (size_t) - 1. Otherwise, it returns the number of array elements modified, not including a terminating zero code, if any.

size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);

• Converts a sequence of codes that correspond to multibyte characters from the array pointed to by pwcs into a sequence of multibyte characters that begins in the initial shift state, and stores these multibyte characters into the array pointed to by s. The conversion stops if a multibyte character would exceed the limit of n total bytes or if a null character is stored.
  Each code is converted as if by a call to wctomb, except that the shift state of wctomb is not affected.
  If a code is encountered that does not correspond to a valid multibyte character, the wcstombs function returns (size_t) - 1. Otherwise, it returns the number of bytes modified, not including a terminating null character, if any.

The <string.h> header file declares one type and several functions, and defines one macro useful for manipulating character arrays that other objects treat as character arrays.

There are two kinds of string functions declared. The first, with names beginning with str, manipulate character arrays; the second, with names beginning with mem, manipulate other objects treated as character arrays. Except for memmove, function behavior is undefined if copying takes place between overlapping objects.

Type

size_t

• An unsigned integral type of the result of the sizeof operator.

Macro

NULL

• Expands to an implementation-defined null pointer constant.

Functions

void *memcpy(void *s1, const void *s2, size_t n);

• Copies n characters from the object pointed to by s2 to the object pointed to by s1. The function returns s1.

void *memmove(void *s1, const void *s2, size_t n);

• Copies n characters from the object pointed to by s2 to 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 object pointed to by s1 and s2, and then the n characters from the temporary array are copied into the object pointed to by s1. The memmove function returns s1.

void *memchr(const void *s, int c, size_t n);

• Locates the first occurrence of c (converted to an unsigned char) in the first n unsigned characters of the object pointed to by s. The memchr function returns a pointer to the located character, or a null pointer if the character was not found.

int memcmp(const void *s1, const void *s2, size_t n);

• Compares the first n characters of the object pointed to by s1 to the first n characters of the object pointed to by s2. The memcmp function returns an integer less than, equal to, or greater than 0, depending on whether the object pointed to by s1 is less than, equal to, or greater than the object pointed to by s2.

void *memset(void *s, int c, size_t n);

• Copies the value of c (converted to an unsigned char) into each of the first n characters pointed to by s. The function returns s.

char *strcpy(char *s1, const char *s2);

• Copies the string pointed to by s2 (including the terminating null character) to the string pointed to by s1. The strcpy function returns s1.

char *strncpy(char *s1, const char *s2, size_t n);

• Copies no more than n characters from the string pointed to by s2 to the string pointed to by s1, up to but not including the null terminator of the string pointed to by s2; returns s1. If the string pointed to by s2 is less than n characters, strncpy pads the copy with null characters.

char *strcat(char *s1, const char *s2);

• Appends a copy of the the string pointed to by s2 (including the terminating null character) to the end of the string pointed to by s1. The strcat function returns s1. The first character of s2 overwrites the null character of s1.

char *strncat(char *s1, const char *s2, size_t n);

• Appends no more than n characters from the string pointed to by s2 (up to but not including a null character) to the string pointed to by s1. The strncat function returns s1. The first character of s2 overwrites the null character of s1. A terminating null character is appended to the result. The first character of s2 overwrites the null character of s1.

int strcmp(const char *s1, const char *s2);

• Compares the string pointed to by s1 to the string pointed to by s2. The strcmp function returns an integer less than, equal to, or greater than 0, depending on whether the string pointed to by s1 is less than, equal to, or greater than the string pointed to by s2.

int strcoll(const char *s1, const char *s2);

• 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 (see Section 9.5). The strcoll function returns an integer less than, equal to, or greater than 0, depending on whether the string pointed to by s1 is less than, equal to, or greater than the string pointed to by s2, when both are interpreted as appropriate to the current locale.

int strncmp(const char *s1, const char *s2, size_t n);

• Compares no more than n characters from the string pointed to by s1 to the string pointed to by s2. The strings are compared until a null character is encountered, the strings differ, or n is reached. The strncmp function returns an integer less than, equal to, or greater than 0, depending on whether the string pointed to by s1 is less than, equal to, or greater than the string pointed to by s2.

size_t strxfrm(char *s1, const char *s2, size_t n);

• Transforms the string pointed to by s2 and places the resulting string into the array pointed to by s1.
  See your DEC C library routine documentation for a detailed description of this function.

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

• 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. The function returns a pointer to the located character, or a null pointer if the character was not found.

size_t strcspn(const char *s1, const char *s2);

• Computes the length of the maximum initial segment of the string pointed to by s1 that consists entirely of characters not found in the string pointed to by s2. The strcspn function returns the length of the segment.

char *strpbrk(const char *s1, const char *s2);

• Locates the first occurrence in the string pointed to by s1 of any character from the string pointed to by s2. The function returns a pointer to the character, or a null pointer if no character in s1 occurs in s2.

char *strrchr(const char *s, int c);

• 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. The function returns a pointer to the located character, or a null pointer if the character was not found.

size_t strspn(const char *s1, const char *s2);

• Computes the length of the maximum initial segment of the string pointed to by s1 that consists entirely of characters from the string pointed to by s2. The strspn function returns the length of the segment.

char *strstr(const char *s1, const char *s2);

• Locates the first occurrence in the string pointed to by s1 of the sequence of characters (excluding the terminal null character) in the string pointed to by s2. The strstr function returns a pointer to the located string, or a null pointer if the string was not found. If s2 points to a string of zero length, the function returns s1.

char *strtok(const char *s1, char *s2);

• 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 to strtok() skips characters, looking for the first one that is not in s2. The function keeps track of its position in the string pointed to by s1 between calls and, as successive calls are made, the function works through this string, identifying the text token following the one identified by the previous call. When the function finds a character in s1 that matches a character in s2, it replaces the character in s1 with a null character. The strtok function returns a pointer to the first character of the token, or a null pointer if there is no token.

char *strerror(int errnum);

• Maps the error number in errnum to an error message string; returns a pointer to the string. The string pointed to must not be modified by the program, but can be overwritten by a subsequent call to strerror.

size_t strlen(const char *s);

• Computes the length of the string pointed to by s. The function returns the number of characters that precede the terminating null character.

The <time.h> header file defines two macros, and declares four types and several functions for manipulating time and date information. Some functions process local time, which may differ from calendar time because of time zone.

Types

size_t

• An unsigned integral type of the result of the sizeof operator.

clock_t time_t

• Arithmetic types capable of representing times.

struct tm

• Holds the components of a calendar time, called the broken-down time. The structure contains the following members:

  int tm_sec; /* seconds after the minute -- [0,61] */ 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 -- 0 if */ /* DST not in effect; positive if it is; */ /* negative if information is not available. */

Macros

NULL

• Expands to an implementation-defined null pointer constant.

CLOCKS_PER_SEC

• The number per second of the value returned by the clock function.

Time Conversion Functions

char *asctime(const struct tm *timeptr);

• Converts a broken-down time in the structure pointed to by timeptr into a 26-character string in the form of this example:

  Sat Sep 08 08:10:32 1990\n\0

  
  A pointer to the string is returned.

char *ctime(const time_t *timer);

• Converts the calendar time pointed to by timer to local time in a string of the form generated by the asctime function. A pointer to the string is returned. The ctime function is equivalent to the following:

  asctime(localtime(timer))

struct tm *gmtime(const time_t *timer);

• Converts the calendar time pointed to by timer into a broken-down time expressed as Coordinated Universal Time (UTC). The gmtime function returns a pointer to the broken-down time, or a null pointer if UTC is not available.

struct tm *localtime(const time_t *timer);

• Converts the calendar time pointed to by timer into a broken-down time expressed as local time. The localtime function returns a pointer to the broken-down time.

size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr);

• Places characters into the array pointed to by s as controlled by the string pointed to by format. The format string consists of zero or more conversion specifiers and ordinary multibyte characters. All ordinary multibyte characters (including the terminating null character) are copied unchanged into the array. Each conversion specifier is replaced by the appropriate characters as shown in Table 9-2. The appropriate characters are determined by the LC_TIME category of the current locale and by the values contained in the structure pointed to by timeptr.

  Table 9-2 strftime Conversion Specifiers

  Specifier	Replaced by
  %a	The locale's abbreviated weekday name
  %A	The locale's full weekday name
  %b	The locale's abbreviated month name
  %B	The locale's full month name
  %c	The locale's appropriate date and time representation
  %d	The day of the month as a decimal number (01 -- 31)
  %H	The hour (24-hour clock) as a decimal number (00 -- 23)
  %I	The hour (12-hour clock) as a decimal number (01 -- 12)
  %j	The day of the year as a decimal number (001 -- 366)
  %m	The month as a decimal number (01 -- 12)
  %M	The minute as a decimal number (00 -- 59)
  %p	The locale's equivalent of the AM/PM designations associated with a 12-hour clock
  %S	The second as a decimal number (00 -- 61)
  %U	The week number of the year (the first Sunday as the first day of week 1) as a decimal number (00 -- 53)
  %w	The weekday as a decimal number (0 [Sunday] -- 6)
  %W	The week number of the year (the first Monday as the first day of week 1) as a decimal number (00 -- 53)
  %x	The locale's appropriate date representation
  %X	The locale's appropriate time representation
  %y	The year without century as a decimal number (00 -- 99)
  %Y	The year with century as a decimal number
  %Z	The time zone name or abbreviation, or by no characters if no time zone can be determined
  %%	%

  
  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, 0 is returned, and the array contents are indeterminate.