     [file front.txi not included]

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 <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 terminalemdasheither 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 0endash32767

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