C Portability Function Library Reference Manual

functions to supplement vendor libraries

October 1997

by Stephen McConnel

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

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

2.1 abs

2.1.1 Syntax

#include "cportlib.h"

int abs(int x);

2.1.2 Description

abs computes the absolute value of the integer x.

abs has one argument:

x: is an integer.

2.1.3 Return Value

the absolute value of the input integer

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

2.1.5 Source File

`abs.c'

2.1.6 Standards SVID 3, POSIX, BSD 4.3, ISO 9899

2.2 bcmp

2.2.1 Syntax

#include "cportlib.h"

int bcmp(char * buffer1,
         char * buffer2,
         int    size);

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

2.2.3 Return Value

zero if the byte arrays are identical, otherwise nonzero

2.2.4 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 */
    {
    ...
    }

2.2.5 Source File

`bcmp.c'

2.2.6 Standards BSD 4.3

2.3 bcopy

2.3.1 Syntax

#include "cportlib.h"

char * bcopy(char * src,
             char * dest,
             int    size);

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

2.3.3 Return Value

none

2.3.4 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));

2.3.5 Source File

`bcopy.c'

2.3.6 Standards BSD 4.3

2.4 bsearch

2.4.1 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));

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

2.4.3 Return Value

address of the item found, or NULL if the key is not in the table

2.4.4 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);

2.4.5 Source File

`bsearch.c'

2.4.6 Standards SVID 3, BSD 4.3, ISO 9899

2.5 bzero

2.5.1 Syntax

#include "cportlib.h"

void bzero(char *   buffer,
           unsigned size);

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

2.5.3 Return Value

none

2.5.4 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);

2.5.5 Source File

`bzero.c'

2.5.6 Standards BSD 4.3

2.6 ccommand

2.6.1 Syntax

#include "cportlib.h"

int ccommand(char ***argvp);

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

2.6.3 Return Value

the number of command line arguments

2.6.4 Example #include "cportlib.h" ... int argc; char ** argv; ... argc = ccommand(&argv);

2.6.5 Source File

`ccommand.c'

2.6.6 Standards

2.7 concat

2.7.1 Syntax

#include "cportlib.h"

char * concat(char * buffer,
              ...);

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

2.7.3 Return Value

the address of the output buffer

2.7.4 Example

#include "cportlib.h"
...
char buffer[100];
...
concat(buffer, "This", " ", "is", " ", "a", " ", "test", ".", NULL);

2.7.5 Source File

`concat.c'

2.7.6 Standards

2.8 cpystr

2.8.1 Syntax

#include "cportlib.h"

char * cpystr(char * dest,
              char * src);

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

2.8.3 Return Value

the address of the NUL byte which terminates dest

2.8.4 Example

#include "cportlib.h"
...
char buffer[100];
...
buffer[0] = NUL;
cpystr(cpystr(cpystr(buffer, "This "), "is a "), "test.");

2.8.5 Source File

`cpystr.c'

2.8.6 Standards

2.9 ctermid

2.9.1 Syntax

#include "cportlib.h"

char * ctermid(char * buffer);

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

2.9.3 Return Value

the address of the pathname of the controlling terminal--either buffer or an internal static array

2.9.4 Example

#include "config.h"
#ifdef STDC_HEADERS
#include <stdio.h>
#endif
#ifndef HAVE_CTERMID
#include "cportlib.h"
#endif
...
char   name[L_ctermid];
...
ctermid(name);

2.9.5 Source File

`ctermid.c'

2.9.6 Standards POSIX.1

2.10 ffs

2.10.1 Syntax

#include "cportlib.h"

int ffs(int x);

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

2.10.3 Return Value

the index of first bit in x which is set to 1; -1 if i is zero

2.10.4 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);

2.10.5 Source File

`ffs.c'

2.10.6 Standards BSD 4.3

2.11 fgetss

2.11.1 Syntax

#include <stdio.h>
#include "cportlib.h"

char * fgetss(char * buffer,
              int    n,
              FILE * fp);

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

2.11.3 Return Value

the address of the input buffer; or NULL if an error occurs or the end of the file has been reached already

2.11.4 Example

#include <stdio.h>
#include "cportlib.h"
...
FILE * fp;
char   buffer[100];
...
while (fgetss(buffer, 100, fp) != NULL)
    {
    ...
    }

2.11.5 Source File

`fgetss.c'

2.11.6 Standards

2.12 fputss

2.12.1 Syntax

#include <stdio.h>
#include "cportlib.h"

void fputss(char * string,
            FILE * fp);

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

2.12.3 Return Value

none

2.12.4 Example

#include <stdio.h>
#include "cportlib.h"
...
char   buffer[100];
FILE * fp;
...
fputss(buffer, fp);

2.12.5 Source File

`fputss.c'

2.12.6 Standards

2.13 fsize

2.13.1 Syntax

#include <stdio.h>
#include "cportlib.h"

long fsize(FILE * fp);

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

2.13.3 Return Value

the input file size, or possibly the available space for an output file

2.13.4 Example

#include <stdio.h>
#include "cportlib.h"
...
FILE * fp;
long   size;
...
size = fsize(fp);

2.13.5 Source File

`fsize.c'

2.13.6 Standards

2.14 getopt

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

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

2.14.3 Return Value

the option letter, a question mark (?) if the option is not recognized, or EOF if there are no more options

2.14.4 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;
        }
    }

2.14.5 Source File

`getopt.c'

2.14.6 Standards POSIX.1

2.15 index

2.15.1 Syntax

#include "cportlib.h"

char * index(char * string,
             int    c);

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

2.15.3 Return Value

the address of the first occurrence of c in string, or NULL if c does not occur in string

2.15.4 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');

2.15.5 Source File

`index.c'

2.15.6 Standards BSD 4.3

2.16 iscntrl

2.16.1 Syntax

#include "cportlib.h"

int iscntrl(int c);

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

2.16.3 Return Value

zero if c is not a control character, otherwise nonzero if it is an ASCII character

2.16.4 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))
    {
    ...
    }

2.16.5 Source File

`iscntrl.c'

2.16.6 Standards ANSI C, BSD 4.3

2.17 isgraph

2.17.1 Syntax

#include "cportlib.h"

int isgraph(int c);

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

2.17.3 Return Value

zero if c is an ASCII control character or the space character, otherwise nonzero if it is an ASCII character

2.17.4 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))
    {
    ...
    }

2.17.5 Source File

`isgraph.c'

2.17.6 Standards ANSI C, BSD 4.3

2.18 isodigit

2.18.1 Syntax

#include "cportlib.h"

int isodigit(char c);

2.18.2 Description

isodigit tests whether the character c is an ASCII octal digit.

isodigit has one argument:

c: is a character to test.

2.18.3 Return Value

nonzero if c is in "01234567", otherwise zero

2.18.4 Example

#include "cportlib.h"
...
int c;
...
if (isodigit(c))
    {
    ...
    }

2.18.5 Source File

`isodigit.c'

2.18.6 Standards

2.19 ispunct

2.19.1 Syntax

#include "cportlib.h"

int ispunct(int c);

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

2.19.3 Return Value

nonzero if c is an ASCII punctuation character, otherwise zero if it is an ASCII character

2.19.4 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))
    {
    ...
    }

2.19.5 Source File

`ispunct.c'

2.19.6 Standards ANSI C, BSD 4.3

2.20 itoa

2.20.1 Syntax

#include "cportlib.h"

char * itoa(int    value,
            char * buffer);

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

2.20.3 Return Value

the address of NUL byte which terminates the string

2.20.4 Example

#include "config.h"
#ifndef HAVE_ITOA
#include "cportlib.h"
#endif
...
int  i;
char buffer[100];
...
itoa(i, buffer);

2.20.5 Source File

`itoa.c'

2.20.6 Standards

2.21 itoa8

2.21.1 Syntax

#include "cportlib.h"

char * itoa8(int    value,
             char * buffer);

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

2.21.3 Return Value

the address of NUL byte which terminates the string

2.21.4 Example

#include "config.h"
#ifndef HAVE_ITOA8
#include "cportlib.h"
#endif
...
int  i;
char buffer[100];
...
itoa8(i, buffer);

2.21.5 Source File

`itoa8.c'

2.21.6 Standards

2.22 itoax

2.22.1 Syntax

#include "cportlib.h"

char * itoax(int    value,
             char * buffer);

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

2.22.3 Return Value

the address of NUL byte which terminates the string

2.22.4 Example

#include "config.h"
#ifndef HAVE_ITOAX
#include "cportlib.h"
#endif
...
int  i;
char buffer[100];
...
itoax(i, buffer);

2.22.5 Source File

`itoax.c'

2.22.6 Standards

2.23 labs

2.23.1 Syntax

#include "cportlib.h"

long labs(long x);

2.23.2 Description

labs has one argument:

x: is a long integer.

2.23.3 Return Value

abs computes the absolute value of the long integer x.

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

2.23.5 Source File

`labs.c'

2.23.6 Standards SVID 3, BSD 4.3, ISO 9899

2.24 memccpy

2.24.1 Syntax

#include "cportlib.h"

void * memccpy(void *       dest,
               const void * src,
               int          c,
               size_t       n);

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

2.24.3 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

2.24.4 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';
    ...
    }

2.24.5 Source File

`memccpy.c'

2.24.6 Standards SVID 3, BSD 4.3

2.25 memchr

2.25.1 Syntax

#include "cportlib.h"

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

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

2.25.3 Return Value

the address of the first occurrence of c in buffer, or NULL if c does not occur in buffer

2.25.4 Example

#include "config.h"
#ifndef HAVE_MEMCHR
#include "cportlib.h"
#endif
...
char   buffer[100];
char * p;
...
p = memchr(buffer, 'z', 100);

2.25.5 Source File

`memchr.c'

2.25.6 Standards SVID 3, BSD 4.3, ISO 9899

2.26 memcmp

2.26.1 Syntax

#include "cportlib.h"

int memcmp(const void * buffer1,
           const void * buffer2,
           size_t       n);

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

2.26.3 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

2.26.4 Example

#include "config.h"
#ifndef HAVE_MEMCMP
#include "cportlib.h"
#endif
...
char buffer1[100], buffer2[100];
...
if (memcmp(buffer1, buffer2, 100) == 0)
    {
    ...
    }

2.26.5 Source File

`memcmp.c'

2.26.6 Standards SVID 3, BSD 4.3, ISO 9899

2.27 memcpy

2.27.1 Syntax

#include "cportlib.h"

void * memcpy(void *       dest,
              const void * src,
              size_t       n);

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

2.27.3 Return Value

dest (the address of the output buffer)

2.27.4 Example

#include "config.h"
#ifndef HAVE_MEMCPY
#include "cportlib.h"
#endif
...
char buffer1[100], buffer2[100];
...
memcpy(buffer1, buffer2, 100);

2.27.5 Source File

`memcpy.c'

2.27.6 Standards SVID 3, BSD 4.3, ISO 9899

2.28 memmove

2.28.1 Syntax

#include "cportlib.h"

void * memmove(void *       dest,
               const void * src,
               size_t       n);

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

2.28.3 Return Value

dest (the address of the output buffer)

2.28.4 Example

#include "config.h"
#ifndef HAVE_MEMMOVE
#include "cportlib.h"
#endif
...
char buffer[100];
...
memmove(buffer, buffer + 20, 60);

2.28.5 Source File

`memmove.c'

2.28.6 Standards SVID 3, BSD 4.3, ISO 9899

2.29 memset

2.29.1 Syntax

#include "cportlib.h"

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

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

2.29.3 Return Value

dest (the address of the output buffer)

2.29.4 Example

#include "config.h"
#ifndef HAVE_MEMSET
#include "cportlib.h"
#endif
...
char buffer[100];
...
memset(buffer, '\0', 100);

2.29.5 Source File

`memset.c'

2.29.6 Standards SVID 3, BSD 4.3, ISO 9899

2.30 rand

2.30.1 Syntax

#include "cportlib.h"

int rand(void);
void srand(unsigned seed);

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

2.30.3 Return Value

a pseudo-random integer in the range of 0-32767

2.30.4 Example

#include "config.h"
#ifndef HAVE_RAND
#include "cportlib.h"
#endif

2.30.5 Source File

`rand.c'

2.30.6 Standards SVID 3, BSD 4.3, ISO 9899

2.31 rindex

2.31.1 Syntax

#include "cportlib.h"

char * rindex(char * string,
              int    c);

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

2.31.3 Return Value

the address of the last occurrence of c in string, or NULL if c does not occur in string

2.31.4 Example

#include "config.h"
#ifndef HAVE_RINDEX
#include "cportlib.h"
#endif
...
char   buffer[100];
char * p;
...
p = rindex(buffer, 'x');

2.31.5 Source File

`rindex.c'

2.31.6 Standards BSD 4.3

2.32 strcasecmp

2.32.1 Syntax

#include "cportlib.h"

int strcasecmp(const char * string1,
               const char * string2);

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

2.32.3 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

2.32.4 Example

#include "config.h"
#ifndef HAVE_STRCASECMP
#include "cportlib.h"
#endif
...
char buffer1[100], buffer2[100];
...
if (strcasecmp(buffer1, buffer2) == 0)
    {
    ...
    }

2.32.5 Source File

`strcasec.c'

2.32.6 Standards BSD 4.3

2.33 strchr

2.33.1 Syntax

#include "cportlib.h"

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

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

2.33.3 Return Value

the address of the first occurrence of c in string, or NULL if c does not occur in string

2.33.4 Example

#include "config.h"
#ifndef HAVE_STRCHR
#include "cportlib.h"
#endif
...
char   buffer[100];
char * p;
...
p = strchr(buffer);

2.33.5 Source File

`strchr.c'

2.33.6 Standards SVID 3, POSIX, BSD 4.3, ISO 9899

2.34 strcspn

2.34.1 Syntax

#include "cportlib.h"

size_t strcspn(const char * string,
               const char * reject);

2.34.2 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).

2.34.3 Return Value

the length of the initial segment of string which consists entirely of characters not from reject

2.34.4 Example

#include "config.h"
#ifndef HAVE_STRCSPN
#include "cportlib.h"
#endif
...
char   buffer[100];
size_t len;
...
len = strcspn(buffer, "aeiou");

2.34.5 Source File

`strcspn.c'

2.34.6 Standards SVID 3, POSIX, BSD 4.3, ISO 9899

2.35 streq

2.35.1 Syntax

#include "cportlib.h"

int streq(const char * string1,
          const char * string2);

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

2.35.3 Return Value

nonzero if the two strings are identical, zero otherwise

2.35.4 Example

#include "cportlib.h"
...
char buffer1[100], buffer2[100];
...
if (streq(buffer1, buffer2))
    {
    ...
    }

2.35.5 Source File

`streq.c'

2.35.6 Standards

2.36 stricmp

2.36.1 Syntax

#include "cportlib.h"

int stricmp(const char * string1,
            const char * string2);

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

2.36.3 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

2.36.4 Example

#include "config.h"
#ifndef HAVE_STRICMP
#include "cportlib.h"
#endif
...
char buffer1[100], buffer2[100];
...
if (stricmp(buffer1, buffer2) == 0)
    {
    ...
    }

2.36.5 Source File

`stricmp.c'

2.36.6 Standards

2.37 strlwr

2.37.1 Syntax

#include "cportlib.h"

char * strlwr(char * string);

2.37.2 Description

Convert all upper case ASCII letters in string to lower case.

strlwr has one argument:

string: points to a NUL-terminated character string.

2.37.3 Return Value

string (the address of the input/output buffer)

2.37.4 Example

#include "config.h"
#ifndef HAVE_STRLWR
#include "cportlib.h"
#endif
...
char buffer[100];
...
strlwr(buffer);

2.37.5 Source File

`strlwr.c'

2.37.6 Standards

2.38 strpbrk

2.38.1 Syntax

#include "cportlib.h"

char * strpbrk(const char * string,
               const char * accept);

2.38.2 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).

2.38.3 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

2.38.4 Example

#include "config.h"
#ifndef HAVE_STRPBRK
#include "cportlib.h"
#endif
...
char   buffer[100];
char * p;
...
p = strpbrk(buffer, "aeiou");

2.38.5 Source File

`strpbrk.c'

2.38.6 Standards SVID 3, POSIX, BSD 4.3, ISO 9899

2.39 strpos

2.39.1 Syntax

#include "cportlib.h"

int strpos(const char * string,
           int          c);

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

2.39.3 Return Value

the position of the first occurrence of c in string, or -1 if c does not occur in string

2.39.4 Example

#include "config.h"
#ifndef HAVE_STRPOS
#include "cportlib.h"
#endif
...
char buffer[100];
int  pos;
...
pos = strpos(buffer, 'a');

2.39.5 Source File

`strpos.c'

2.39.6 Standards

2.40 strrchr

2.40.1 Syntax

#include "cportlib.h"

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

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

2.40.3 Return Value

the address of the last occurrence of c in s, or NULL if c does not occur in string

2.40.4 Example

#include "config.h"
#ifndef HAVE_STRRCHR
#include "cportlib.h"
#endif
...
char   buffer[100];
char * p;
...
p = strrchr(buffer, 'x');

2.40.5 Source File

`strrchr.c'

2.40.6 Standards SVID 3, POSIX, BSD 4.3, ISO 9899

2.41 strrpbrk

2.41.1 Syntax

#include "cportlib.h"

char * strrpbrk(char * string,
                char * accept);

2.41.2 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).

2.41.3 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

2.41.4 Example

#include "config.h"
#ifndef HAVE_STRRPBRK
#include "cportlib.h"
#endif
...
char   buffer[100];
char * p;
...
p = strrpbrk(buffer, "aeiou");

2.41.5 Source File

`strrpbrk.c'

2.41.6 Standards

2.42 strrpos

2.42.1 Syntax

#include "cportlib.h"

int strrpos(char * string,
            int    c);

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

2.42.3 Return Value

the position of the last occurrence of c in string, or -1 if c does not occur in string

2.42.4 Example

#include "config.h"
#ifndef HAVE_STRRPOS
#include "cportlib.h"
#endif
...
char buffer[100];
int  pos;
...
pos = strrpos(buffer, 'a');

2.42.5 Source File

`strrpos.c'

2.42.6 Standards

2.43 strspn

2.43.1 Syntax

#include "cportlib.h"

size_t strspn(const char * string,
              const char * accept);

2.43.2 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).

2.43.3 Return Value

the length of the initial segment of string which consists entirely of characters from accept

2.43.4 Example

#include "config.h"
#ifndef HAVE_STRSPN
#include "cportlib.h"
#endif
...
char   buffer[100];
size_t len;
...
len = strspn(buffer, "aeiou");

2.43.5 Source File

`strspn.c'

2.43.6 Standards SVID 3, POSIX, BSD 4.3, ISO 9899

2.44 strstr

2.44.1 Syntax

#include "cportlib.h"

char * strstr(const char * string1,
              const char * string2);

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

2.44.3 Return Value

the address of the first location of string2 within string1, or NULL if the string2 is not a substring of string1

2.44.4 Example

#include "config.h"
#ifndef HAVE_STRSTR
#include "cportlib.h"
#endif
...
char   buffer[100];
char * p;
...
p = strstr(buffer, "xyzzy");

2.44.5 Source File

`strstr.c'

2.44.6 Standards ANSI C

2.45 strtok

2.45.1 Syntax

#include "cportlib.h"

char * strtok(char *       string,
              const char * delim);

2.45.2 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).

2.45.3 Return Value

the address of the next token from string, or NULL if no more tokens exist

2.45.4 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") )
    {
    ...
    }

2.45.5 Source File

`strtok.c'

2.45.6 Standards SVID 3, POSIX, BSD 4.3, ISO 9899

2.46 strtol

2.46.1 Syntax

#include "cportlib.h"

long strtol(const char * string,
            char **      endptr,
            int          base);

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

2.46.3 Return Value

the long integer equivalent of the ASCII number string

2.46.4 Example

#include "config.h"
#ifndef HAVE_STRTOL
#include "cportlib.h"
#endif
...
long   val;
char   buffer[100];
char * p;
...
val = strtol(buffer, &p, 10);

2.46.5 Source File

`strtol.c'

2.46.6 Standards SVID 3, BSD 4.3, ISO 9899

2.47 strtoul

2.47.1 Syntax

#include "cportlib.h"

unsigned long strtoul(const char * string,
                      char **      endptr,
                      int          base);

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

2.47.3 Return Value

the unsigned long integer equivalent of the ASCII number string

2.47.4 Example

#include "config.h"
#ifndef HAVE_STRTOUL
#include "cportlib.h"
#endif
...
long   val;
char   buffer[100];
char * p;
...
val = strtoul(buffer, &p, 10);

2.47.5 Source File

`strtoul.c'

2.47.6 Standards SVID 3, BSD 4.3, ISO 9899

2.48 strupr

2.48.1 Syntax

#include "cportlib.h"

char * strupr(char * string);

2.48.2 Description

Convert all lower case ASCII letters in string to upper case.

strupr has one argument:

string: points to a NUL-terminated character string.

2.48.3 Return Value

string (the address of the input/output buffer)

2.48.4 Example

#include "config.h"
#ifndef HAVE_STRUPR
#include "cportlib.h"
#endif
...
char buffer[100];
...
strupr(buffer);

2.48.5 Source File

`strupr.c'

2.48.6 Standards

2.49 swapmem

2.49.1 Syntax

#include "cportlib.h"

void swapmem(char * src,
             char * dest,
             int    n);

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

2.49.3 Return Value

none

2.49.4 Example

#include "cportlib.h"
...
char buffer1[100], buffer2[100];
...
swapmem(buffer1, buffer2, 100);

2.49.5 Source File

`swapmem.c'

2.49.6 Standards

2.50 toint

2.50.1 Syntax

#include "cportlib.h"

int toint(int c);

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

2.50.3 Return Value

the integer value of an ASCII hexadecimal character, or -1 if invalid

2.50.4 Example

#include "cportlib.h"
...
int  h;
char buffer[100];
...
h = toint(buffer[0]);
if (h == -1)
    {
    ...
    }

2.50.5 Source File

`toint.c'

2.50.6 Standards

2.51 tolower

2.51.1 Syntax

#include "cportlib.h"

int tolower(int c);

2.51.2 Description

If c is an uppercase ASCII character, tolower produces the lowercase equivalent.

tolower has one argument:

c: is a character.

2.51.3 Return Value

either the lowercase equivalent or the original value of c

2.51.4 Example

#include "config.h"
#ifndef HAVE_TOLOWER
#include "cportlib.h"
#endif
...
int  c;
char buffer[100];
...
c = tolower(buffer[0]);

2.51.5 Source File

`tolower.c'

2.51.6 Standards ANSI C, BSD 4.3

2.52 toupper

2.52.1 Syntax

#include "cportlib.h"

int toupper(char c);

2.52.2 Description

If c is an lowercase ASCII character, toupper produces the uppercase equivalent.

toupper has one argument:

c: is a character.

2.52.3 Return Value

either the uppercase equivalent or the original value of c

2.52.4 Example

#include "config.h"
#ifndef HAVE_TOUPPER
#include "cportlib.h"
#endif
...
int  c;
char buffer[100];
...
c = toupper(buffer[0]);

2.52.5 Source File

`toupper.c'

2.52.6 Standards ANSI C, BSD 4.3

2.53 zapnl

2.53.1 Syntax

#include "cportlib.h"

char * zapnl(char * string);

2.53.2 Description

zapnl removes any trailing newlines from string.

zapnl has one argument:

string: points to a NUL-terminated character string.

2.53.3 Return Value

string (the address of the input/output buffer)

2.53.4 Example

#include "cportlib.h"
...
char buffer[100];
...
zapnl(buffer);

2.53.5 Source File

`zapnl.c'

2.53.6 Standards

This document was generated on 20 March 2003 using texi2html 1.56k.

C Portability Function Library Reference Manual

functions to supplement vendor libraries

October 1997

Table of Contents

2.1.1 Syntax

2.1.2 Description

2.1.3 Return Value

2.1.5 Source File

2.2.1 Syntax

2.2.2 Description

2.2.3 Return Value

2.2.5 Source File

2.3.1 Syntax

2.3.2 Description

2.3.3 Return Value

2.3.5 Source File

2.4.1 Syntax

2.4.2 Description

2.4.3 Return Value

2.4.5 Source File

2.5.1 Syntax

2.5.2 Description

2.5.3 Return Value

2.5.5 Source File

2.6.1 Syntax

2.6.2 Description

2.6.3 Return Value

2.6.5 Source File

2.7.1 Syntax

2.7.2 Description

2.7.3 Return Value

2.7.5 Source File

2.8.1 Syntax

2.8.2 Description

2.8.3 Return Value

2.8.5 Source File

2.9.1 Syntax

2.9.2 Description

2.9.3 Return Value

2.9.5 Source File

2.10.1 Syntax

2.10.2 Description

2.10.3 Return Value

2.10.5 Source File

2.11.1 Syntax

2.11.2 Description

2.11.3 Return Value

2.11.5 Source File

2.12.1 Syntax

2.12.2 Description

2.12.3 Return Value

2.12.5 Source File

2.13.1 Syntax

2.13.2 Description

2.13.3 Return Value

2.13.5 Source File

2.14.1 Syntax

2.14.2 Description

2.14.3 Return Value

2.14.5 Source File

2.15.1 Syntax

2.15.2 Description

2.15.3 Return Value

2.15.5 Source File

2.16.1 Syntax

2.16.2 Description

2.16.3 Return Value

2.16.5 Source File

2.17.1 Syntax

2.17.2 Description

2.17.3 Return Value

2.17.5 Source File

2.18.1 Syntax

2.18.2 Description

2.18.3 Return Value

2.18.5 Source File

2.19.1 Syntax

2.19.2 Description

2.19.3 Return Value

2.19.5 Source File