            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
***********************

The specifications for these function have come from a variety of
places.  Those that are known are listed following the name of the
function in the menu below.

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 <stdlib.h>
     #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 <string.h>     /* 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 <string.h>     /* 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 <stdlib.h>
     #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 <string.h>     /* 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 <NUL> 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 <stdio.h>
     #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 <string.h>     /* 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 <stdio.h>
     #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 <stdio.h>
     #include "cportlib.h"
     ...
     FILE * fp;
     char   buffer[100];
     ...
     while (fgetss(buffer, 100, fp) != NULL)
         {
         ...
         }

Source File
-----------

`fgetss.c'

Standards
---------

fputss
======

Syntax
------

     #include <stdio.h>
     #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 <stdio.h>
     #include "cportlib.h"
     ...
     char   buffer[100];
     FILE * fp;
     ...
     fputss(buffer, fp);

Source File
-----------

`fputss.c'

Standards
---------

fsize
=====

Syntax
------

     #include <stdio.h>
     #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 <stdio.h>
     #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 <unistd.h>     /* 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 <string.h>     /* 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 <ctype.h>      /* 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 <ctype.h>      /* 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 <ctype.h>      /* 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 <stdlib.h>
     #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 <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').  `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
---------