C Portability Function Library Reference Manual functions to supplement vendor libraries October 1997 by Stephen McConnel Copyright (C) 2000 SIL International Published by: Language Software Development SIL International 7500 W. Camp Wisdom Road Dallas, TX 75236 U.S.A. Permission is granted to make and distribute verbatim copies of this file provided the copyright notice and this permission notice are preserved in all copies. The author may be reached at the address above or via email as `steve@acadcomp.sil.org'. Introduction to the C Portability function library ************************************************** This document gives the proper usage information about each of the functions found in the C Portability function library. For each function that the library provides, this includes information on which header files to include in your source to obtain prototypes and type definitions relevent to the use of that function. C Portability functions *********************** abs === Syntax ------ #include "cportlib.h" int abs(int x); Description ----------- `abs' computes the absolute value of the integer `x'. `abs' has one argument: `x' is an integer. Return Value ------------ the absolute value of the input integer Example ------- #include "config.h" #ifdef STDC_HEADERS #include #endif #ifndef HAVE_ABS #include "cportlib.h" #endif ... int i, j; ... j = abs(i); /* set j to the absolute value of i */ Source File ----------- `abs.c' Standards --------- SVID 3, POSIX, BSD 4.3, ISO 9899 bcmp ==== Syntax ------ #include "cportlib.h" int bcmp(char * buffer1, char * buffer2, int size); Description ----------- `bcmp' compares the first `size' bytes of `buffer1' to the first `size' bytes of `buffer2'. The arguments to `bcmp' are as follows: `buffer1' points to a block of memory. `buffer2' points to another block of memory. `size' is the size (in bytes) of the blocks of memory. Return Value ------------ zero if the byte arrays are identical, otherwise nonzero Example ------- #include "config.h" #ifdef STDC_HEADERS #include /* at least on Linux */ #endif #ifndef HAVE_BCMP #include "cportlib.h" #endif ... char buffer1[100], buffer2[100]; ... if (bcmp(buffer1, buffer2, 100) == 0) /* compare the byte arrays */ { ... } Source File ----------- `bcmp.c' Standards --------- BSD 4.3 bcopy ===== Syntax ------ #include "cportlib.h" char * bcopy(char * src, char * dest, int size); Description ----------- `bcopy' copies `size' bytes from `src' to `dest'. Note that overlapping moves are not guaranteed to work properly. The arguments to `bcopy' are as follows: `src' points to a block of memory. `dest' points to another block of memory. `size' is the size (in bytes) of the blocks of memory. Return Value ------------ none Example ------- #include "config.h" #ifdef STDC_HEADERS #include /* at least on Linux */ #endif #ifndef HAVE_BCOPY #include "cportlib.h" #endif ... int buffer1[100], buffer2[100]; ... bcopy(buffer1, buffer2, 100 * sizeof(int)); Source File ----------- `bcopy.c' Standards --------- BSD 4.3 bsearch ======= Syntax ------ #include "cportlib.h" void * bsearch(const void * key, const void * table, size_t count, size_t size, int (* compar)(const void * key, const void * element)); Description ----------- `bsearch' is a generalized binary search function, analagous to `qsort' for sorting. `bsearch' looks for `key' in `table', an array of `count' elements, each `size' bytes long. The `table' must be sorted in ascending order as defined by the `compar' function. If there are multiple equal items in the `table' that match the `key', the return value may point to any one of them. The arguments to `bsearch' are as follows: `key' points to something to search for, which may a character string, a number, or an arbitrary data structure. `table' points to an array of arbitrary items, which presumably provide data that can be meaningfully compared to the key. `count' is the number of elements in the input array (`table'). `size' is the size (in bytes) of each element in the input array. `compar' points to a function for comparing two elements of the input array. It must return an integer less than, equal to, or greater than zero depending on whether its first argument (the key) is considered less than, equal to, or greater than the second argument (an array element). `key' points to the key originally passed to `bsearch'. `element' points to an element in the input array passed to `bsearch'. Return Value ------------ address of the item found, or NULL if the `key' is not in the `table' Example ------- #include "config.h" #ifdef STDC_HEADERS #include #endif #ifndef HAVE_BSEARCH #include "cportlib.h" #endif ... int cmpStrings(const void * a, const void * b) { return strcmp(*(const char **)a, *(const char **)b); } ... char * table[100]; char * p; ... p = bsearch("Steve", table, 100, sizeof(char *), cmpStrings); Source File ----------- `bsearch.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 bzero ===== Syntax ------ #include "cportlib.h" void bzero(char * buffer, unsigned size); Description ----------- `bzero' sets all `size' bytes in `buffer' to zero. The arguments to `bzero' are as follows: `buffer' points to a block of memory. `size' is the size (in bytes) of the block of memory. Return Value ------------ none Example ------- #include "config.h" #ifdef STDC_HEADERS #include /* at least on Linux */ #endif #ifndef HAVE_BZERO #include "cportlib.h" #endif ... char buffer[100]; ... bzero(buffer, 100); Source File ----------- `bzero.c' Standards --------- BSD 4.3 ccommand ======== Syntax ------ #include "cportlib.h" int ccommand(char ***argvp); Description ----------- `ccommand' reads a command line from the keyboard and parses it into a dynamically allocated array of arguments. This is useful for systems that do not support a native command line interface (Microsoft Windows and Apple Macintosh). `ccommand' has one argument: `argvp' is the address of a pointer to an array of character strings. This array is dynamically allocated by `ccommand'. Return Value ------------ the number of command line arguments Example ------- #include "cportlib.h" ... int argc; char ** argv; ... argc = ccommand(&argv); Source File ----------- `ccommand.c' Standards --------- concat ====== Syntax ------ #include "cportlib.h" char * concat(char * buffer, ...); Description ----------- `concat' concatenates a number of strings, storing the result in `buffer'. The last input argument must be `NULL'. The arguments to `concat' are as follows: `buffer' points to a block of memory for storing the concatenated strings. `...' is an arbitrary number of character strings (pointers), ending with a `NULL'. Return Value ------------ the address of the output `buffer' Example ------- #include "cportlib.h" ... char buffer[100]; ... concat(buffer, "This", " ", "is", " ", "a", " ", "test", ".", NULL); Source File ----------- `concat.c' Standards --------- cpystr ====== Syntax ------ #include "cportlib.h" char * cpystr(char * dest, char * src); Description ----------- `cpystr' copies `src' to `dest'. It is identical to `strcpy' except for the return value. The arguments to `cpystr' are as follows: `dest' points to a block of memory for storing a character string. `src' points to a character string. Return Value ------------ the address of the byte which terminates `dest' Example ------- #include "cportlib.h" ... char buffer[100]; ... buffer[0] = NUL; cpystr(cpystr(cpystr(buffer, "This "), "is a "), "test."); Source File ----------- `cpystr.c' Standards --------- ctermid ======= Syntax ------ #include "cportlib.h" char * ctermid(char * buffer); Description ----------- `ctermid' fills a buffer with the pathname of the controlling terminal. If `buffer' is `NULL', an internal static array is used. `buffer' must be at least `L_ctermid' characters long. `ctermid' has one argument: `buffer' points to a block of memory for storing the terminal (screen / keyboard) pathname, or is `NULL'. Return Value ------------ the address of the pathname of the controlling terminal-either `buffer' or an internal static array Example ------- #include "config.h" #ifdef STDC_HEADERS #include #endif #ifndef HAVE_CTERMID #include "cportlib.h" #endif ... char name[L_ctermid]; ... ctermid(name); Source File ----------- `ctermid.c' Standards --------- POSIX.1 ffs === Syntax ------ #include "cportlib.h" int ffs(int x); Description ----------- `ffs' finds the first bit set in the integer `x', starting with the least significant bit. The least significant bit has an index value of zero. `ffs' has one argument: `x' is an integer. Return Value ------------ the index of first bit in `x' which is set to 1; -1 if `i' is zero Example ------- #include "config.h" #ifdef STDC_HEADERS #include /* at least on Linux */ #endif #ifndef HAVE_FFS #include "cportlib.h" #endif ... int i, j; ... j = ffs(i); Source File ----------- `ffs.c' Standards --------- BSD 4.3 fgetss ====== Syntax ------ #include #include "cportlib.h" char * fgetss(char * buffer, int n, FILE * fp); Description ----------- `fgetss' reads a line from the file opened for `fp', storing up to `n' bytes in `buffer'. The trailing newline is removed. `fgetss' is identical to `fgets', except that treats newlines the same as `gets'. The arguments to `fgetss' are as follows: `buffer' points to a block of memory. `n' is the size (in bytes) of the block of memory. `fp' is an input `FILE' pointer. Return Value ------------ the address of the input buffer; or `NULL' if an error occurs or the end of the file has been reached already Example ------- #include #include "cportlib.h" ... FILE * fp; char buffer[100]; ... while (fgetss(buffer, 100, fp) != NULL) { ... } Source File ----------- `fgetss.c' Standards --------- fputss ====== Syntax ------ #include #include "cportlib.h" void fputss(char * string, FILE * fp); Description ----------- `fputss' writes `string' to the file `fp'. It works like `fputs', but appends a newline like `puts'. The arguments to `fputss' are as follows: `string' points to a `NUL'-terminated character string. `fp' is an output `FILE' pointer. Return Value ------------ none Example ------- #include #include "cportlib.h" ... char buffer[100]; FILE * fp; ... fputss(buffer, fp); Source File ----------- `fputss.c' Standards --------- fsize ===== Syntax ------ #include #include "cportlib.h" long fsize(FILE * fp); Description ----------- If `fp' is an input file, `fsize' returns its size in bytes. Otherwise, `fsize' returns the amount of available space on the disk. For Unix, this is the soft limit on file size, which may not mean much. For MSDOS, this is the amount of space available on the current default disk, which may not even be where the file is located. `fsize' has one argument: `fp' is an open `FILE' pointer. Return Value ------------ the input file size, or possibly the available space for an output file Example ------- #include #include "cportlib.h" ... FILE * fp; long size; ... size = fsize(fp); Source File ----------- `fsize.c' Standards --------- getopt ====== Syntax ------ #include "cportlib.h" int getopt(int argc, char * const argv[], const char * opts); extern char * optarg; extern int optind; extern int opterr; extern int optopt; Description ----------- `getopt' parses a command argument array like those passed to `main'. `getopt' has a number of associated global variables. `optarg' points to the option argument, if there is one. `optind' is the current argument array index. `opterr' flags whether to print error messages for illegal options. (The default is `TRUE'.) `optopt' is the currently matched option character. The arguments to `getopt' are as follows: `argc' is the number of command line arguments. `argv' points to the array of command line arguments (character strings). `opts' points to a string encoding the defined options. The string contains all of the characters (usually letters) used for command line options. Each option that takes an argument has a colon (`:') following its character in the string. Return Value ------------ the option letter, a question mark (`?') if the option is not recognized, or `EOF' if there are no more options Example ------- #include "config.h" #ifdef HAVE_UNISTD_H #include /* this may not work for gcc -ansi */ #endif #ifndef HAVE_GETOPT #include "cportlib.h" #endif ... char * opt_a = NULL; int opt_b = 0; /* 1 or 0 */ char * opt_c = NULL; int opt_d = 0; /* count */ ... int main(int argc, char * argv[]) { ... while (getopt(argc, argv, "ab:cd:") != EOF) { switch (optopt) { case 'a': opt_a = 1; break; case 'b': opt_b = optarg; break; case 'c': ++opt_c; break; case 'd': opt_d = optarg; break; default: ... break; } } Source File ----------- `getopt.c' Standards --------- POSIX.1 index ===== Syntax ------ #include "cportlib.h" char * index(char * string, int c); Description ----------- `index' searches for the first occurrence of the character `c' in `string'. This is identical to `strchr'. The arguments to `index' are as follows: `string' points to a `NUL'-terminated character string. `c' is the character to search for in the string. Return Value ------------ the address of the first occurrence of `c' in `string', or `NULL' if `c' does not occur in `string' Example ------- #include "config.h" #ifdef STDC_HEADERS #include /* at least on Linux */ #endif #ifndef HAVE_INDEX #include "cportlib.h" #endif ... char * p; char buffer [100]; ... p = index(buffer, 'i'); Source File ----------- `index.c' Standards --------- BSD 4.3 iscntrl ======= Syntax ------ #include "cportlib.h" int iscntrl(int c); Description ----------- `iscntrl' tests whether the character `c' is an ASCII control character (value < 040 or > 0176). `iscntrl' has one argument: `c' is a character to test. Return Value ------------ zero if `c' is not a control character, otherwise nonzero if it is an ASCII character Example ------- #include "config.h" #ifdef STDC_HEADERS #include /* at least on Linux */ #endif #ifndef HAVE_ISCNTRL #include "cportlib.h" #endif ... int c; ... if (iscntrl(c)) { ... } Source File ----------- `iscntrl.c' Standards --------- ANSI C, BSD 4.3 isgraph ======= Syntax ------ #include "cportlib.h" int isgraph(int c); Description ----------- `isgraph' tests whether the character `c' is a printing ASCII character which deposits ink. `isgraph' has one argument: `c' is a character to test. Return Value ------------ zero if `c' is an ASCII control character or the space character, otherwise nonzero if it is an ASCII character Example ------- #include "config.h" #ifdef STDC_HEADERS #include /* at least on Linux */ #endif #ifndef HAVE_ISGRAPH #include "cportlib.h" #endif ... int c; ... if (isgraph(c)) { ... } Source File ----------- `isgraph.c' Standards --------- ANSI C, BSD 4.3 isodigit ======== Syntax ------ #include "cportlib.h" int isodigit(char c); Description ----------- `isodigit' tests whether the character `c' is an ASCII octal digit. `isodigit' has one argument: `c' is a character to test. Return Value ------------ nonzero if `c' is in "01234567", otherwise zero Example ------- #include "cportlib.h" ... int c; ... if (isodigit(c)) { ... } Source File ----------- `isodigit.c' Standards --------- ispunct ======= Syntax ------ #include "cportlib.h" int ispunct(int c); Description ----------- `ispunct' tests whether the character `c' is an ASCII punctuation character (neither control, nor alphanumeric, nor space). `ispunct' has one argument: `c' is a character to test. Return Value ------------ nonzero if `c' is an ASCII punctuation character, otherwise zero if it is an ASCII character Example ------- #include "config.h" #ifdef STDC_HEADERS #include /* at least on Linux */ #endif #ifndef HAVE_ISPUNCT #include "cportlib.h" #endif ... int c; ... if (ispunct(c)) { ... } Source File ----------- `ispunct.c' Standards --------- ANSI C, BSD 4.3 itoa ==== Syntax ------ #include "cportlib.h" char * itoa(int value, char * buffer); Description ----------- `itoa' converts the integer `value' to a signed decimal character (digit) string stored in `buffer'. The arguments to `itoa' are as follows: `value' is an integer. `buffer' points to a block of memory used to store the signed decimal character string representation of `value'. Return Value ------------ the address of NUL byte which terminates the string Example ------- #include "config.h" #ifndef HAVE_ITOA #include "cportlib.h" #endif ... int i; char buffer[100]; ... itoa(i, buffer); Source File ----------- `itoa.c' Standards --------- itoa8 ===== Syntax ------ #include "cportlib.h" char * itoa8(int value, char * buffer); Description ----------- `itoa8' converts the integer `value' to an unsigned octal character (digit) string stored in `buffer'. The arguments to `itoa8' are as follows: `value' is an integer. `buffer' points to a block of memory used to store the unsigned octal character string representation of `value'. Return Value ------------ the address of NUL byte which terminates the string Example ------- #include "config.h" #ifndef HAVE_ITOA8 #include "cportlib.h" #endif ... int i; char buffer[100]; ... itoa8(i, buffer); Source File ----------- `itoa8.c' Standards --------- itoax ===== Syntax ------ #include "cportlib.h" char * itoax(int value, char * buffer); Description ----------- `itoax' converts the integer `value' to an unsigned hexadecimal character (digit) string stored in `buffer'. The arguments to `itoax' are as follows: `value' is an integer. `buffer' points to a block of memory used to store the unsigned hexadecimal character string representation of `value'. Return Value ------------ the address of NUL byte which terminates the string Example ------- #include "config.h" #ifndef HAVE_ITOAX #include "cportlib.h" #endif ... int i; char buffer[100]; ... itoax(i, buffer); Source File ----------- `itoax.c' Standards --------- labs ==== Syntax ------ #include "cportlib.h" long labs(long x); Description ----------- `labs' has one argument: `x' is a long integer. Return Value ------------ `abs' computes the absolute value of the long integer `x'. Example ------- the absolute value of the input integer #include "config.h" #ifdef STDC_HEADERS #include #endif #ifndef HAVE_LABS #include "cportlib.h" #endif ... long i, j; ... j = labs(i); /* set j to the absolute value of i */ Source File ----------- `labs.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 memccpy ======= Syntax ------ #include "cportlib.h" void * memccpy(void * dest, const void * src, int c, size_t n); Description ----------- `memccpy' copies characters from `src' to `dest', stopping after `n' characters have been transferred, or after the first occurrence of the character `c' has been copied, whichever comes first. Note that overlapping moves are unpredictable. `memccpy(d, s, '\0', n)' is the same as `strncpy(d, s, n)'. The arguments to `memccpy' are as follows: `dest' points to a block of memory. `src' points to another block of memory, one that holds some data to copy. `c' is the byte value that flags the end of the data to copy. `n' is the maximum size (in bytes) of the data to copy. Return Value ------------ the address of the character after the copy of `c' in `dest', or NULL if `c' is not found in the first `n' characters of `src' Example ------- #include "config.h" #ifndef HAVE_MEMCCPY #include "cportlib.h" #endif ... char buffer[100], buffer2[100]; ... if (memccpy(buffer, buffer2, '\0', 99) == NULL) { buffer[99] = '\0'; ... } Source File ----------- `memccpy.c' Standards --------- SVID 3, BSD 4.3 memchr ====== Syntax ------ #include "cportlib.h" void * memchr(const void * buffer, int c, size_t n); Description ----------- `memchr' searches for the first occurrence of the character `c' in the first `n' characters of `buffer'. The arguments to `memchr' are as follows: `buffer' points to a block of memory. `c' is a byte value to search for in the block of memory. `n' is the size (in bytes) of the block of memory. Return Value ------------ the address of the first occurrence of `c' in `buffer', or `NULL' if `c' does not occur in `buffer' Example ------- #include "config.h" #ifndef HAVE_MEMCHR #include "cportlib.h" #endif ... char buffer[100]; char * p; ... p = memchr(buffer, 'z', 100); Source File ----------- `memchr.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 memcmp ====== Syntax ------ #include "cportlib.h" int memcmp(const void * buffer1, const void * buffer2, size_t n); Description ----------- `memcmp' compares the first `n' characters of `buffer1' to the first `n' characters of `buffer2'. The arguments to `memcmp' are as follows: `buffer1' points to a block of memory. `buffer2' points to another block of memory. `n' is the size (in bytes) of the blocks of memory. Return Value ------------ an integer less than, equal to, or greater than zero, indicating that `buffer1' is lexicographically less than, equal to, or greater than `buffer2' Example ------- #include "config.h" #ifndef HAVE_MEMCMP #include "cportlib.h" #endif ... char buffer1[100], buffer2[100]; ... if (memcmp(buffer1, buffer2, 100) == 0) { ... } Source File ----------- `memcmp.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 memcpy ====== Syntax ------ #include "cportlib.h" void * memcpy(void * dest, const void * src, size_t n); Description ----------- `memcpy' copies `n' characters from `src' to `dest'. Note that overlapping moves are unpredictable. The arguments to `memcpy' are as follows: `dest' points to a block of memory. `src' points to another block of memory, one that holds some data to copy. `n' is the size (in bytes) of the blocks of memory. Return Value ------------ `dest' (the address of the output buffer) Example ------- #include "config.h" #ifndef HAVE_MEMCPY #include "cportlib.h" #endif ... char buffer1[100], buffer2[100]; ... memcpy(buffer1, buffer2, 100); Source File ----------- `memcpy.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 memmove ======= Syntax ------ #include "cportlib.h" void * memmove(void * dest, const void * src, size_t n); Description ----------- `memmove' copies `n' characters from `src' to `dest', handling overlaps properly (characters get copied before they get overwritten). The arguments to `memmove' are as follows: `dest' points to a block of memory. `src' points to another block of memory, one that holds some data to copy. `n' is the size (in bytes) of the blocks of memory. Return Value ------------ `dest' (the address of the output buffer) Example ------- #include "config.h" #ifndef HAVE_MEMMOVE #include "cportlib.h" #endif ... char buffer[100]; ... memmove(buffer, buffer + 20, 60); Source File ----------- `memmove.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 memset ====== Syntax ------ #include "cportlib.h" void * memset(void * dest, int c, size_t n); Description ----------- `memset' sets the first `n' characters of `dest' to the value of the character `c'. The arguments to `memset' are as follows: `dest' points to a block of memory. `c' is a byte value. `n' is the size (in bytes) of the block of memory. Return Value ------------ `dest' (the address of the output buffer) Example ------- #include "config.h" #ifndef HAVE_MEMSET #include "cportlib.h" #endif ... char buffer[100]; ... memset(buffer, '\0', 100); Source File ----------- `memset.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 rand ==== Syntax ------ #include "cportlib.h" int rand(void); void srand(unsigned seed); Description ----------- `rand' computes the next pseudo-random integer from the sequence defined by next = next * 1103515245L + 12345L; The top 16 bits of the number are returned with the top bit cleared. `srand' sets a "seed" value for `rand'. `rand' does not have any arguments. `srand' has one argument: `seed' is an initial value for the pseudo-random sequence generated by `rand'. Return Value ------------ a pseudo-random integer in the range of 0-32767 Example ------- #include "config.h" #ifndef HAVE_RAND #include "cportlib.h" #endif Source File ----------- `rand.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 rindex ====== Syntax ------ #include "cportlib.h" char * rindex(char * string, int c); Description ----------- `rindex' searches for the last occurrence of the character `c' in `string'. It is identical to `strrchr'. The arguments to `rindex' are as follows: `string' points to a `NUL'-terminated character string. `c' is a character to search for in the string. Return Value ------------ the address of the last occurrence of `c' in `string', or NULL if `c' does not occur in `string' Example ------- #include "config.h" #ifndef HAVE_RINDEX #include "cportlib.h" #endif ... char buffer[100]; char * p; ... p = rindex(buffer, 'x'); Source File ----------- `rindex.c' Standards --------- BSD 4.3 strcasecmp ========== Syntax ------ #include "cportlib.h" int strcasecmp(const char * string1, const char * string2); Description ----------- `strcasecmp' compares two strings like `strcmp', but in a case independent fashion (for example, 'A' == 'a'). It is identical to `stricmp'. The arguments to `strcasecmp' are as follows: `string1' points to a `NUL'-terminated character string. `string2' points to another `NUL'-terminated character string. Return Value ------------ an integer less than, equal to, or greater than zero, indicating that `string1' is lexicographically less than, equal to, or greater than `string2' Example ------- #include "config.h" #ifndef HAVE_STRCASECMP #include "cportlib.h" #endif ... char buffer1[100], buffer2[100]; ... if (strcasecmp(buffer1, buffer2) == 0) { ... } Source File ----------- `strcasec.c' Standards --------- BSD 4.3 strchr ====== Syntax ------ #include "cportlib.h" char * strchr(const char * string, int c); Description ----------- `strchr' searches for the first occurrence of the character `c' in `string'. It is identical to `index'. The arguments to `strchr' are as follows: `string' points to a `NUL'-terminated character string. `c' is a character to search for in the string. Return Value ------------ the address of the first occurrence of `c' in `string', or `NULL' if `c' does not occur in `string' Example ------- #include "config.h" #ifndef HAVE_STRCHR #include "cportlib.h" #endif ... char buffer[100]; char * p; ... p = strchr(buffer); Source File ----------- `strchr.c' Standards --------- SVID 3, POSIX, BSD 4.3, ISO 9899 strcspn ======= Syntax ------ #include "cportlib.h" size_t strcspn(const char * string, const char * reject); Description ----------- `strcspn' counts the number of characters at the beginning of `string' which are not found in `reject'. If none of the characters in `string' are found in `reject', then `strcspn' returns the length of `string'. The arguments to `strcspn' are as follows: `string' points to a `NUL'-terminated character string. `reject' points to a `NUL'-terminated set of characters (that is, a string). Return Value ------------ the length of the initial segment of `string' which consists entirely of characters not from `reject' Example ------- #include "config.h" #ifndef HAVE_STRCSPN #include "cportlib.h" #endif ... char buffer[100]; size_t len; ... len = strcspn(buffer, "aeiou"); Source File ----------- `strcspn.c' Standards --------- SVID 3, POSIX, BSD 4.3, ISO 9899 streq ===== Syntax ------ #include "cportlib.h" int streq(const char * string1, const char * string2); Description ----------- `streq' compares two strings for equality. The arguments to `streq' are as follows: `string1' points to a `NUL'-terminated character string. `string2' points to another `NUL'-terminated character string. Return Value ------------ nonzero if the two strings are identical, zero otherwise Example ------- #include "cportlib.h" ... char buffer1[100], buffer2[100]; ... if (streq(buffer1, buffer2)) { ... } Source File ----------- `streq.c' Standards --------- stricmp ======= Syntax ------ #include "cportlib.h" int stricmp(const char * string1, const char * string2); Description ----------- `stricmp' compares two strings like `strcmp', but in a case independent fashion (for example, 'A' == 'a'). It is identical to `strcasecmp'. The arguments to `stricmp' are as follows: `string1' points to a `NUL'-terminated character string. `string2' points to another `NUL'-terminated character string. Return Value ------------ an integer less than, equal to, or greater than zero, indicating that `string1' is lexicographically less than, equal to, or greater than `string2' Example ------- #include "config.h" #ifndef HAVE_STRICMP #include "cportlib.h" #endif ... char buffer1[100], buffer2[100]; ... if (stricmp(buffer1, buffer2) == 0) { ... } Source File ----------- `stricmp.c' Standards --------- strlwr ====== Syntax ------ #include "cportlib.h" char * strlwr(char * string); Description ----------- Convert all upper case ASCII letters in `string' to lower case. `strlwr' has one argument: `string' points to a `NUL'-terminated character string. Return Value ------------ `string' (the address of the input/output buffer) Example ------- #include "config.h" #ifndef HAVE_STRLWR #include "cportlib.h" #endif ... char buffer[100]; ... strlwr(buffer); Source File ----------- `strlwr.c' Standards --------- strpbrk ======= Syntax ------ #include "cportlib.h" char * strpbrk(const char * string, const char * accept); Description ----------- `strpbrk' searches for the first occurrence in `string' of any character from `accept'. The arguments to `strpbrk' are as follows: `string' points to a `NUL'-terminated character string. `accept' points to a `NUL'-terminated set of characters (that is, a string). Return Value ------------ the address of the first occurrence in `string' of any character from `accept', or `NULL' if no character from `accept' occurs in `string' Example ------- #include "config.h" #ifndef HAVE_STRPBRK #include "cportlib.h" #endif ... char buffer[100]; char * p; ... p = strpbrk(buffer, "aeiou"); Source File ----------- `strpbrk.c' Standards --------- SVID 3, POSIX, BSD 4.3, ISO 9899 strpos ====== Syntax ------ #include "cportlib.h" int strpos(const char * string, int c); Description ----------- `strpos' searches for the first occurrence of the character `c' in `string'. If the character `c' is found in `string', the position of its first occurrence is returned. (The first character of `string' is considered to be at position 0). The terminating character is considered to be part of `string' for the purposes of the search, so searching for returns the position of the terminating (which is equal to the length of `string'). `strpos(s,'\0')' is therefore equivalent to `strlen(s)'. The arguments to `strpos' are as follows: `string' points to a `NUL'-terminated character string. `c' is a character to search for in the string. Return Value ------------ the position of the first occurrence of `c' in `string', or -1 if `c' does not occur in `string' Example ------- #include "config.h" #ifndef HAVE_STRPOS #include "cportlib.h" #endif ... char buffer[100]; int pos; ... pos = strpos(buffer, 'a'); Source File ----------- `strpos.c' Standards --------- strrchr ======= Syntax ------ #include "cportlib.h" char * strrchr(const char * string, int c); Description ----------- `strrchr' searches for the last occurrence of the character `c' in `string'. It is identical to `rindex'. The arguments to `strrchr' are as follows: `string' points to a `NUL'-terminated character string. `c' is a character to search for in the string. Return Value ------------ the address of the last occurrence of `c' in `s', or `NULL' if `c' does not occur in `string' Example ------- #include "config.h" #ifndef HAVE_STRRCHR #include "cportlib.h" #endif ... char buffer[100]; char * p; ... p = strrchr(buffer, 'x'); Source File ----------- `strrchr.c' Standards --------- SVID 3, POSIX, BSD 4.3, ISO 9899 strrpbrk ======== Syntax ------ #include "cportlib.h" char * strrpbrk(char * string, char * accept); Description ----------- `strrpbrk' searches `string' for occurrences of characters from `accept'. The second argument is regarded as a set of characters; the order of the characters or duplications does not matter. If any characters from `accept' is found in `string', then a pointer to the last such character is returned. See also `strpbrk', which searches for the first character in `string' that is also in `accept'. The arguments to `strrpbrk' are as follows: `string' points to a `NUL'-terminated character string. `accept' points to a `NUL'-terminated set of characters (that is, a string). Return Value ------------ the address of the last occurrence in `string' of any character from `accept', or `NULL' if no character from `accept' occurs in `string' Example ------- #include "config.h" #ifndef HAVE_STRRPBRK #include "cportlib.h" #endif ... char buffer[100]; char * p; ... p = strrpbrk(buffer, "aeiou"); Source File ----------- `strrpbrk.c' Standards --------- strrpos ======= Syntax ------ #include "cportlib.h" int strrpos(char * string, int c); Description ----------- `strrpos' searches `string' for the last occurrence of the character `c'. If the character `c' is found in `string', the position of its last occurrence is returned. (The first character of `string' is considered to be at position 0). The terminating `NUL' character is considered to be part of `string' for the purposes of the search, so searching for `NUL' returns the position of the terminating `NUL' (which is equal to the length of `string'). `strrpos(s,'\0')' is therefore the same as `strpos(s,'\0')', and equivalent to `strlen(s)'. The arguments to `strrpos' are as follows: `string' points to a `NUL'-terminated character string. `c' is a character to search for in the string. Return Value ------------ the position of the last occurrence of `c' in `string', or -1 if `c' does not occur in `string' Example ------- #include "config.h" #ifndef HAVE_STRRPOS #include "cportlib.h" #endif ... char buffer[100]; int pos; ... pos = strrpos(buffer, 'a'); Source File ----------- `strrpos.c' Standards --------- strspn ====== Syntax ------ #include "cportlib.h" size_t strspn(const char * string, const char * accept); Description ----------- `strspn' counts the number of characters at the beginning of `string' which are found in `accept'. The arguments to `strspn' are as follows: `string' points to a `NUL'-terminated character string. `accept' points to a `NUL'-terminated set of characters (that is, a string). Return Value ------------ the length of the initial segment of `string' which consists entirely of characters from `accept' Example ------- #include "config.h" #ifndef HAVE_STRSPN #include "cportlib.h" #endif ... char buffer[100]; size_t len; ... len = strspn(buffer, "aeiou"); Source File ----------- `strspn.c' Standards --------- SVID 3, POSIX, BSD 4.3, ISO 9899 strstr ====== Syntax ------ #include "cportlib.h" char * strstr(const char * string1, const char * string2); Description ----------- `strstr' searches for the position of the second string in the first. The arguments to `strstr' are as follows: `string1' points to a `NUL'-terminated character string. `string2' points to a `NUL'-terminated character string to search for in the first string. Return Value ------------ the address of the first location of `string2' within `string1', or `NULL' if the `string2' is not a substring of `string1' Example ------- #include "config.h" #ifndef HAVE_STRSTR #include "cportlib.h" #endif ... char buffer[100]; char * p; ... p = strstr(buffer, "xyzzy"); Source File ----------- `strstr.c' Standards --------- ANSI C strtok ====== Syntax ------ #include "cportlib.h" char * strtok(char * string, const char * delim); Description ----------- `strtok' splits `string' into a sequence of zero or more text tokens separated by spans of one or more characters from `delim'. Only the initial call to `strtok' provides a value for `string'; successive calls must use `NULL' for the first argument. The first separating character following the token in `string' is replaced by `NUL'. Subsequent calls to `strtok' work through `string' sequentially. Note that `delim' may change from one call to the next. The arguments to `strtok' are as follows: `string' points to a `NUL'-terminated character string. `delim' points to a `NUL'-terminated set of characters (that is, a string). Return Value ------------ the address of the next token from `string', or `NULL' if no more tokens exist Example ------- #include "config.h" #ifndef HAVE_STRTOK #include "cportlib.h" #endif ... char buffer[100]; char * p; ... for ( p = strtok(buffer, " \t\r\n\f"); p != NULL ; p = strtok(NULL, " \t\r\n\f") ) { ... } Source File ----------- `strtok.c' Standards --------- SVID 3, POSIX, BSD 4.3, ISO 9899 strtol ====== Syntax ------ #include "cportlib.h" long strtol(const char * string, char ** endptr, int base); Description ----------- `strtol' converts the value represented by `string' to a long integer in the given `base'. Leading whitespace is ignored, and an optional sign (`+' or `-') character is allowed. If `base' is between 2 and 36, it is used as the number base for the conversion. If `base' is zero, the number string itself is used to determine the base according to the normal C conventions. (Leading `0x' means hexadecimal, and leading `0' means octal.) If `endptr' is not `NULL', the address of the character terminating the scan is stored in the location pointed to by `endptr'. Note that overflow conditions are ignored. In this implementation, invalid values for `base' cause `0L' to be returned, with no adjustment to *`endptr'. The arguments to `strtol' are as follows: `string' points to a `NUL'-terminated character string. `endptr' is the address of a pointer for storing the end of the number, or `NULL'. `base' is the number base for the conversion, or zero to interpret as a C literal number. Return Value ------------ the long integer equivalent of the ASCII number string Example ------- #include "config.h" #ifndef HAVE_STRTOL #include "cportlib.h" #endif ... long val; char buffer[100]; char * p; ... val = strtol(buffer, &p, 10); Source File ----------- `strtol.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 strtoul ======= Syntax ------ #include "cportlib.h" unsigned long strtoul(const char * string, char ** endptr, int base); Description ----------- `strtoul' converts the value represented by `string' to an unsigned long integer in the given `base'. Leading whitespace is ignored. If `base' is between 2 and 36, it is used as the number base for the conversion. If `base' is zero, the number string itself is used to determine the base according to the normal C conventions. (Leading `0x' means hexadecimal, and leading `0' means octal.) If `endptr' is not `NULL', the address of the character terminating the scan is stored in the location pointed to by `endptr'. Note that overflow conditions are ignored. In this implementation, invalid values for `base' cause `0L' to be returned, with no adjustment to *`endptr'. The arguments to `strtoul' are as follows: `string' points to a `NUL'-terminated character string. `endptr' is the address of a pointer for storing the end of the number, or `NULL'. `base' is the number base for the conversion, or zero to interpret as a C literal number. Return Value ------------ the unsigned long integer equivalent of the ASCII number string Example ------- #include "config.h" #ifndef HAVE_STRTOUL #include "cportlib.h" #endif ... long val; char buffer[100]; char * p; ... val = strtoul(buffer, &p, 10); Source File ----------- `strtoul.c' Standards --------- SVID 3, BSD 4.3, ISO 9899 strupr ====== Syntax ------ #include "cportlib.h" char * strupr(char * string); Description ----------- Convert all lower case ASCII letters in `string' to upper case. `strupr' has one argument: `string' points to a `NUL'-terminated character string. Return Value ------------ `string' (the address of the input/output buffer) Example ------- #include "config.h" #ifndef HAVE_STRUPR #include "cportlib.h" #endif ... char buffer[100]; ... strupr(buffer); Source File ----------- `strupr.c' Standards --------- swapmem ======= Syntax ------ #include "cportlib.h" void swapmem(char * src, char * dest, int n); Description ----------- `swapmem' swaps the `n' characters at `src' and `dest'. No provision is made for overlapping swaps. (Note that both `src' and `dest' serve as both the source and destination for data in this function.) The arguments to `swapmem' are as follows: `src' points to a block of memory. `dest' points to another block of memory. `n' is the size (in bytes) of the blocks of memory. Return Value ------------ none Example ------- #include "cportlib.h" ... char buffer1[100], buffer2[100]; ... swapmem(buffer1, buffer2, 100); Source File ----------- `swapmem.c' Standards --------- toint ===== Syntax ------ #include "cportlib.h" int toint(int c); Description ----------- `toint' returns the "weight" of a hexadecimal digit: 0 for `'0'', 1 for `'1'', ..., 9 for `'9'', 10 for either `'A'' or `'a'', ..., and 15 for either `'F'' or `'f''. `toint' returns -1 if `c' is not a hexadecimal digit character. `toint' has one argument: `c' is a character, presumably a hexadecimal digit character. Return Value ------------ the integer value of an ASCII hexadecimal character, or -1 if invalid Example ------- #include "cportlib.h" ... int h; char buffer[100]; ... h = toint(buffer[0]); if (h == -1) { ... } Source File ----------- `toint.c' Standards --------- tolower ======= Syntax ------ #include "cportlib.h" int tolower(int c); Description ----------- If `c' is an uppercase ASCII character, `tolower' produces the lowercase equivalent. `tolower' has one argument: `c' is a character. Return Value ------------ either the lowercase equivalent or the original value of `c' Example ------- #include "config.h" #ifndef HAVE_TOLOWER #include "cportlib.h" #endif ... int c; char buffer[100]; ... c = tolower(buffer[0]); Source File ----------- `tolower.c' Standards --------- ANSI C, BSD 4.3 toupper ======= Syntax ------ #include "cportlib.h" int toupper(char c); Description ----------- If `c' is an lowercase ASCII character, `toupper' produces the uppercase equivalent. `toupper' has one argument: `c' is a character. Return Value ------------ either the uppercase equivalent or the original value of `c' Example ------- #include "config.h" #ifndef HAVE_TOUPPER #include "cportlib.h" #endif ... int c; char buffer[100]; ... c = toupper(buffer[0]); Source File ----------- `toupper.c' Standards --------- ANSI C, BSD 4.3 zapnl ===== Syntax ------ #include "cportlib.h" char * zapnl(char * string); Description ----------- `zapnl' removes any trailing newlines from `string'. `zapnl' has one argument: `string' points to a `NUL'-terminated character string. Return Value ------------ `string' (the address of the input/output buffer) Example ------- #include "cportlib.h" ... char buffer[100]; ... zapnl(buffer); Source File ----------- `zapnl.c' Standards --------- Table of Contents ***************** Introduction to the C Portability function library C Portability functions abs bcmp bcopy bsearch bzero ccommand concat cpystr ctermid ffs fgetss fputss fsize getopt index iscntrl isgraph isodigit ispunct itoa itoa8 itoax labs memccpy memchr memcmp memcpy memmove memset rand rindex strcasecmp strchr strcspn streq stricmp strlwr strpbrk strpos strrchr strrpbrk strrpos strspn strstr strtok strtol strtoul strupr swapmem toint tolower toupper zapnl