%sccs.include.proprietary.man%

@(#)Clib.ms 8.1 (Berkeley) 06/08/93

.so /k3/unx/MACROS/cmac1 .CH 3 "C LIBRARIES" .H 1 "C LIBRARIES" .H 2 "GENERAL"

This chapter and Chapter 4 describe the libraries that are supported on the UNIX operating system. A library is a collection of related functions and/or declarations that simplify programming effort by linking only what is needed, allowing use of locally produced functions, etc. All of the functions described are also described in Part 3 of the "UNIX System Programmer Reference Manual" . Most of the declarations described are in Part 5 of the "UNIX System Programmer Reference Manual" . The three main libraries on the UNIX system are: .tr ~ .VL 20 .LI ~C~library This is the basic library for C language programs. The C library is composed of functions and declarations used for file access, string testing and manipulation, character testing and manipulation, memory allocation, and other functions. This library is described later in this chapter. .tr ~ .LE .VL 20 .LI ~Object~file This library provides functions for the access and manipulation of object files. This library is described in Chapter 4. .tr ~ .LE .VL 20 .LI ~Math~library This library provides exponential, bessel functions, logarithmic, hyperbolic, and trigonometric functions. This library is described in Chapter 4. .LE

Some libraries consist of two portions - functions and declarations. In some cases, the user must request that the functions (and/or declarations) of a specific library be included in a program being compiled. In other cases, the functions (and/or declarations) are included automatically. .H 3 "Including Functions"

When a program is being compiled, the compiler will automatically search the C language library to locate and include functions that are used in the program. This is the case only for the C library and no other library. In order for the compiler to locate and include functions from other libraries, the user must specify these libraries on the command line for the compiler. For example, when using functions of the math library, the user must request that the math library be searched by including the argument -lm on the command line, such as: I cc file.c -lm The argument -lm must come after all files that reference functions in the math library in order for the link editor to know which functions to include in the a.out file.

0 This method should be used for all functions that are not part of the C language library. .H 3 "Including Declarations"

Some functions require a set of declarations in order to operate properly. A set of declarations is stored in a file under the /usr/include directory. These files are referred to as header files. In order to include a certain header file, the user must specify this request within the C language program. The request is in the form: I #include <file.h>

0 where file.h is the name of the file. Since the header files define the type of the functions and various preprocessor constants, they must be included before invoking the functions they declare.

The remainder of this chapter describes the functions and header files of the C Library. The description of the library begins with the actions required by the user to include the functions and/or header files in a program being compiled (if any). Following the description of the actions required is information in three-column format of the form: L function\^ reference\^(N) Brief description.

0 The functions are grouped by type while the reference refers to section `N' in the "UNIX System Programmer Reference Manual" . Following this, are descriptions of the header files associated with these functions (if any). .H 2 "THE C LIBRARY"

The C library consists of several types of functions. All the functions of the C library are loaded automatically by the compiler. Various declarations must sometimes be included by the user as required. The functions of the C library are divided into the following types: L 6 1 .LI Input/output control .LI String manipulation .LI Character manipulation .LI Time functions .LI Miscellaneous functions. .LE .H 3 "Input/Output Control"

These functions of the C library are automatically included as needed during the compiling of a C language program. No command line request is needed.

The header file required by the input/output functions should be included in the program being compiled. This is accomplished by including the line: I #include <stdio.h>

0 near the beginning of each file that references an input or output function.

The input/output functions are grouped into the following categories: L 6 1 .LI File access .LI File status .LI Input .LI Output .LI Miscellaneous. .LE .H 3 "File Access Functions"

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

fclose\^ fclose\^(3S) Close an open stream.

fdopen\^ fopen\^(3S) Associate stream with

an open(2) ed file.

fileno\^ ferror\^(3S) File descriptor associated

with an open stream.

fopen\^ fopen\^(3S) Open a file with

specified permissions.

Fopen returns a pointer

to a stream which is

used in subsequent

references to the file.

freopen\^ fopen\^(3S) Substitute named file

in place of open

stream.

fseek\^ fseek\^(3S) Reposition the file

pointer.

pclose\^ popen\^(3S) Close a stream opened

by popen.

popen\^ popen\^(3S) Create pipe as a stream

between calling process

and command.

rewind\^ fseek\^(3S) Reposition file

pointer at beginning

of file.

setbuf\^ setbuf\^(3S) Assign buffering to

stream.

vsetbuf setbuf(3S) Similar to setbuf, but

allowing finer control.

.H 3 "File Status Functions"

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

clearerr\^ ferror\^(3S) Reset error condition on

stream.

feof ferror(3S) Test for ``end of file''

on stream.

ferror\^ ferror\^(3S) Test for error condition

on stream.

.SP

ftell\^ fseek\^(3S) Return current position

in the file.

.H 3 "Input Functions"

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

fgetc\^ getc\^(3S) True function for getc\^

(3S).

fgets\^ gets\^(3S) Read string from stream.

fread\^ fread\^(3S) General buffered read

from stream.

fscanf\^ scanf\^(3S) Formatted read from

stream.

getc\^ getc\^(3S) Read character from

stream.

getchar\^ getc\^(3S) Read character from

standard input.

gets\^ gets\^(3S) Read string from standard input.

getw\^ getc\^(3S) Read word from stream.

scanf\^ scanf\^(3S) Read using format from

standard input.

sscanf\^ scanf\^(3S) Formatted from

string.

ungetc\^ ungetc\^(3S) Put back one character on

stream.

.H 3 "Output Functions"

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

fflush\^ fclose\^(3S) Write all currently buffered

characters from stream.

fprintf\^ printf\^(3S) Formatted write to

stream.

fputc\^ putc\^(3S) True function for putc\^

(3S).

fputs\^ puts\^(3S) Write string to stream.

fwrite\^ fread\^(3S) General buffered write to

stream.

printf\^ printf\^(3S) Print using format to

standard output.

putc\^ putc\^(3S) Write character to

standard output.

putchar\^ putc\^(3S) Write character to

standard output.

puts\^ puts\^(3S) Write string to

standard output.

putw\^ putc\^(3S) Write word to stream.

sprintf\^ printf\^(3S) Formatted write to

string.

vfprintf vprint(3C) Print using format to

stream by varargs(5)

argument list.

vprintf vprint(3C) Print using format to

standard output by

varargs(5) argument list.

vsprintf vprintf(3C) Print using format to

stream string by

varargs(5) argument list.

.H 3 "Miscellaneous Functions"

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

ctermid\^ ctermid\^(3S) Return file name for

controlling terminal.

cuserid\^ cuserid\^(3S) Return login name for

owner of current process.

system\^ system\^(3S) Execute shell command.

tempnam\^ tempnam\^(3S) Create temporary file

name using directory and

prefix.

tmpnam\^ tmpnam\^(3S) Create temporary file

name.

tmpfile\^ tmpfile\^(3S) Create temporary file.

.H 3 "String Manipulation Functions"

These functions are used to locate characters within a string, copy, concatenate, and compare strings. These functions are automatically located and loaded during the compiling of a C language program. No command line request is needed since these functions are part of the C library. The string manipulation functions are declared in a header file that may be included in the program being compiled. This is accomplished by including the line: I #include <string.h> near the beginning of each file that uses one of these functions.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

strcat\^ string\^(3C) Concatenate two strings.

strchr\^ string\^(3C) Search string for

character.

strcmp\^ string\^(3C) Compares two strings.

strcpy\^ string\^(3C) Copy string.

strcspn\^ string\^(3C) Length of initial string

not containing set of

characters.

strlen\^ string\^(3C) Length of string.

strncat\^ string\^(3C) Concatenate two strings

with a maximum length.

strncmp\^ string\^(3C) Compares two strings

with a maximum length.

strncpy\^ string\^(3C) Copy string over string

with a maximum length.

strpbrk\^ string\^(3C) Search string for any

set of characters.

strrchr\^ string\^(3C) Search string backwards

for character.

strspn\^ string\^(3C) Length of initial string

containing set of

characters.

strtok\^ string\^(3C) Search string for token

separated by any of a

set of characters.

.H 3 "Character Manipulation"

The following functions and declarations are used for testing and translating ASCII characters. These functions are located and loaded automatically during the compiling of a C language program. No command line request is needed since these functions are part of the C library.

The declarations associated with these functions should be included in the program being compiled. This is accomplished by including the line: I #include <ctype.h>

0 near the beginning of the file being compiled. .H 3 "Character Testing Functions"

These functions can be used to identify characters as uppercase or lowercase letters, digits, punctuation, etc.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

isalnum\^ ctype\^(3C) Is character

alphanumeric?

isalpha\^ ctype\^(3C) Is character alphabetic?

isascii\^ ctype\^(3C) Is integer ASCII

character?

iscntrl\^ ctype\^(3C) Is character a control

character?

isdigit\^ ctype\^(3C) Is character a digit?

isgraph\^ ctype\^(3C) Is character a printable

character?

islower\^ ctype\^(3C) Is character a

lowercase letter?

isprint\^ ctype\^(3C) Is character a printing

character including

space?

ispunct\^ ctype\^(3C) Is character a

punctuation character?

isspace\^ ctype\^(3C) Is character a white

space character?

isupper\^ ctype\^(3C) Is character an uppercase

letter?

isxdigit\^ ctype\^(3C) Is character a hex digit?

.H 3 "Character Translation Functions"

These functions provide translation of uppercase to lowercase, lowercase to uppercase, and integer to ASCII.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

toascii\^ conv\^(3C) Convert integer to

ASCII character.

tolower\^ conv\^(3C) Convert character to

lowercase.

toupper\^ conv\^(3C) Convert character to

uppercase.

.H 3 "Time Functions"

These functions are used for accessing and reformatting the systems idea of the current date and time. These functions are located and loaded automatically during the compiling of a C language program. No command line request is needed since these functions are part of the C library.

The header file associated with these functions should be included in the program being compiled. This is accomplished by including the line: I #include <time.h>

0 near the beginning of any file using the time functions.

These functions (except tzset) convert a time such as returned by time(2).

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

asctime\^ ctime\^(3C) Return string

representation

of date and time.

ctime\^ ctime\^(3C) Return string

representation of

date and time, given

integer form.

gmtime\^ ctime\^(3C) Return Greenwich

Mean Time.

localtime\^ ctime\^(3C) Return local time.

tzset\^ ctime\^(3C) Set time zone field

from environment

variable.

0 .H 3 "Miscellaneous Functions"

These functions support a wide variety of operations. Some of these are numerical conversion, password file and group file access, memory allocation, random number generation, and table management. These functions are automatically located and included in a program being compiled. No command line request is needed since these functions are part of the C library.

Some of these functions require declarations to be included. These are described following the descriptions of the functions. .H 3 "Numerical Conversion"

The following functions perform numerical conversion.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

a64l\^ a64l\^(3C) Convert string to

base 64 ASCII.

atof\^ atof\^(3C) Convert string to

floating.

atoi\^ atof\^(3C) Convert string to

integer.

atol\^ atof\^(3C) Convert string to long.

frexp\^ frexp\^(3C) Split floating into

mantissa and exponent.

l3tol\^ l3tol\^(3C) Convert 3-byte integer

to long.

ltol3\^ l3tol\^(3C) Convert long to 3-byte

integer.

ldexp\^ frexp\^(3C) Combine mantissa and

exponent.

l64a\^ a64l\^(3C) Convert base 64 ASCII

to string.

modf\^ frexp\^(3C) Split mantissa into

integer and fraction.

.H 3 "DES Algorithm Access"

The following functions allow access to the Data Encryption Standard (DES) algorithm used on the UNIX operating system. The DES algorithm is implemented with variations to frustrate use of hardware implementations of the DES for key search.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

crypt\^ crypt\^(3C) Encode string.

encrypt\^ crypt\^(3C) Encode/decode string of

0s and 1s.

setkey\^ crypt\^(3C) Initialize for subsequent

use of encrypt.

.H 3 "Group File Access"

The following functions are used to obtain entries from the group file. Declarations for these functions must be included in the program being compiled with the line: I #include <grp.h>

0

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

endgrent\^ getgrent\^(3C) Close group file being

processed.

getgrent\^ getgrent\^(3C) Get next group file

entry.

getgrgid\^ getgrent\^(3C) Return next group with

matching gid.

getgrnam\^ getgrent\^(3C) Return next group with

matching name.

setgrent\^ getgrent\^(3C) Rewind group file being

processed.

fgetgrent getgrent(3C) Get next group file entry

from a specified file.

.H 3 "Password File Access"

These functions are used to search and access information stored in the password file (/etc/passwd). Some functions require declarations that can be included in the program being compiled by adding the line: I #include <pwd.h>

0

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

endpwent\^ getpwent\^(3C) Close password file

being processed.

getpw\^ getpw\^(3C) Search password file

for uid.

getpwent\^ getpwent\^(3C) Get next password file

entry.

getpwnam\^ getpwent\^(3C) Return next entry with

matching name.

getpwuid\^ getpwent\^(3C) Return next entry with

matching uid.

putpwent\^ putpwent\^(3C) Write entry on stream.

setpwent\^ getpwent\^(3C) Rewind password file

being accessed.

fgetpwent getpwent(3C) Get next password file

entry from a specified

file.

.H 3 "Parameter Access"

The following functions provide access to several different types of paramenters. None require any declarations.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

getopt\^ getopt\^(3C) Get next option from

option list.

getcwd\^ getcwd\^(3C) Return string

representation of

current working directory.

getenv\^ getenv\^(3C) Return string value

associated with

environment variable.

getpass\^ getpass\^(3C) Read string from terminal

without echoing.

putenv putenv(3C) Change or add value

of an environment

variable.

.H 3 "Hash Table Management"

The following functions are used to manage hash search tables. The header file associated with these functions should be included in the program being compiled. This is accomplished by including the line: I #include <search.h> near the beginning of any file using the search functions.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

hcreate\^ hsearch\^(3C) Create hash table.

hdestroy\^ hsearch\^(3C) Destroy hash table.

hsearch\^ hsearch\^(3C) Search hash table for

entry.

.H 3 "Binary Tree Management"

The following functions are used to manage a binary tree. The header file associated with these functions should be included in the program being compiled. This is accomplished by including the line: I #include <search.h> near the beginning of any file using the search functions.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

tdelete\^ tsearch\^(3C) Deletes nodes from

binary tree.

tfind tsearch(3C) Find element in

binary tree.

tsearch\^ tsearch\^(3C) Look for and add

element to binary

tree.

twalk\^ tsearch\^(3C) Walk binary tree.

.H 3 "Table Management"

The following functions are used to manage a table. Since none of these functions allocate storage, sufficient memory must be allocated before using these functions. The header file associated with these functions should be included in the program being compiled. This is accomplished by including the line: I #include <search.h> near the beginning of any file using the search functions.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

bsearch\^ bsearch\^(3C) Search table using

binary search.

lfind lsearch(3C) Find element in

library tree.

lsearch\^ lsearch\^(3C) Look for and add

element in binary

tree.

qsort\^ qsort\^(3C) Sort table using

quick-sort algorithm.

.H 3 "Memory Allocation"

The following functions provide a means by which memory can be dynamically allocated or freed.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

calloc\^ malloc\^(3C) Allocate zeroed storage.

free\^ malloc\^(3C) Free previously allocated

storage.

malloc\^ malloc\^(3C) Allocate storage.

realloc\^ malloc\^(3C) Change size of allocated

storage.

The following is another set of memory allocation functions available.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

calloc malloc(3X) Allocate zeroed storage.

free malloc(3X) Free previously allocated

storage.

malloc malloc(3X) Allocate storage.

mallopt malloc(3X) Control allocation

algorithm.

mallinfo malloc(3X) Space usage.

realoc malloc(3X) Change size of

allocated storage.

.H 3 "Pseudorandom Number Generation"

The following functions are used to generate pseudorandom numbers. The functions that end with 48 are a family of interfaces to a pseudorandom number generator based upon the linear congruent algorithm and 48-bit integer arithmetic. The rand\^ and srand\^ functions provide an interface to a multiplicative congruential random number generator with period of 232.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

drand48\^ drand48\^(3C) Random double over

the interval [0 to 1).

lcong48\^ drand48\^(3C) Set parameters for

drand48\^, lrand48\^,

and mrand48.

lrand48\^ drand48\^(3C) Random long over the

interval [0 to 2\v'-0.3'31\v'0.3').

mrand48\^ drand48\^(3C) Random long over the

interval [-2\v'-0.3'31\v'0.3' to 2\v'-0.3'31\v'0.3').

rand\^ rand\^(3C) Random integer over the

interval [0 to 32767).

seed48\^ drand48\^(3C) Seed the generator for

drand48\^, lrand48\^, and

mrand48.

srand\^ rand\^(3C) Seed the generator

for rand.

srand48\^ drand48\^(3C) Seed the generator for

drand48\^, lrand48\^, and

mrand48 using a long.

.tr ~ .H 3 "Signal Handling Functions"

The functions gsignal\^ and ssignal\^ implement a software facility similar to signal(2) in the "UNIX System Programmer Reference Manual" . This facility enables users to indicate the disposition of error conditions and allows users to handle signals for their own purposes. The declarations associated with these functions can be included in the program being complied by the line I #include <signal.h>

0 These declarations define ASCII names for the 15 software signals.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

gsignal\^ ssignal\^(3C) Send a software signal.

ssignal\^ ssignal\^(3C) Arrange for handling

of software signals.

.H 3 "Miscellaneous"

The following functions do not fall into any previously described category.

0

2

FUNCTION REFERENCE BRIEF DESCRIPTION

abort\^ abort\^(3C) Cause an IOT signal

to be sent to the

process.

abs\^ abs\^(3C) Return the absolute

integer value.

ecvt\^ ecvt\^(3C) Convert double to

string.

fcvt\^ ecvt\^(3C) Convert double to

string using Fortran

Format.

gcvt\^ ecvt\^(3C) Convert double to

string using Fortran

F or E format.

isatty\^ ttyname\^(3C) Test whether integer

file descriptor is

associated with a

terminal.

mktemp\^ mktemp\^(3C) Create file name

using template.

monitor\^ monitor\^(3C) Cause process to record

a histogram of program

counter location.

swab\^ swab\^(3C) Swap and copy bytes.

ttyname\^ ttyname\^(3C) Return pathname of

terminal associated with

integer file descriptor.

.TC 2 1 3 0