libc -- Library

Standard C library
/lib/libc.a

libc is  the library that  contains most functions linked  into C programs.
It contains  many general-purpose functions, as well  as stubs for COHERENT
system calls.  The following summarizes these functions.

Binary Data

The following functions manipulate binary data types, that is, integers and
floating-point numbers.

abs()..........Return the absolute value of an integer
decvax_d().....Convert a double from IEEE to DECVAX format
decvax_f().....Convert a float from IEEE to DECVAX format
div()..........Perform integer division
frexp()........Separate fraction and exponent
ieee_d().......Convert a double from DECVAX to IEEE format
ieee_f().......Convert a float from DECVAX to IEEE format
ldexp()........Combine fraction and exponent
ldiv().........Perform long integer division
modf().........Separate integral part and fraction

Binary Data and Strings

The following functions convert binary data forms to strings, or strings to
binary forms.

atof().........Convert ASCII strings to floating point
atoi().........Convert ASCII strings to integers
atol().........Convert ASCII strings to long integers
ecvt().........Convert floating-point numbers to strings
fcvt().........Convert floating-point numbers to strings
gcvt().........Convert floating-point numbers to strings
strtod().......Convert string to floating-point number
strtol().......Convert string to long integer
strtoul()......Convert string to unsigned long integer

ctype Functions

The  ctype functions  test  a character's  type.  Some  can transform  some
characters  into  others.  ``ctype''  is  an  abbreviation for  ``character
type''; all  are declared  or defined  in the header  file <ctype.h>.
They are as follows:

_tolower().....Convert an upper-case character to lower case
_toupper().....Convert a lower-case character to upper case
isalnum()......Test if alphanumeric character
isalpha()......Test if alphabetic character
isascii()......Test if ASCII character
iscntrl()......Test if a control character
isdigit()......Test if a numeric digit
isgraph()......Test if a graphics character
islower()......Test if lower-case character
isprint()......Test if printable character
ispunct()......Test if punctuation mark
isspace()......Test if a tab, space, or return
isupper()......Test if upper-case character
isxdigit().....Test if hexadecimal numeral
toascii()......Convert a character to ASCII
tolower()......Convert an upper-case character to lower case
toupper()......Convert a lower-case character to upper case

Files and Directories

The following  functions are used to manipulate  files and directories, and
their names.

_getwd().......Get current working directory name
closedir().....Close a directory stream
dup2().........Duplicate a file descriptor
getcwd().......Get current working directory
mktemp().......Generate a temporary file name
opendir()......Open a directory stream
path().........Build a path name for a file
readdir()......Read a directory stream
remove().......Remove a file
rewinddir()....Rewind a directory stream
seekdir()......Reset the position within a directory stream
telldir()......Return position within a directory stream

Interprocess Communication

The following functions perform interprocess communcation.

ftok().........Generate keys for interprocess communication
msgctl().......Control message operation
msgget().......Get a message queue
msgrcv().......Receive a message
msgsnd().......Send a message
semctl().......Control semaphore operations
semget().......Get a set of semaphores
semop()........Perform semaphore operations
shmat()........Attach a shared-memory segment to a process
shmctl().......Manipulate shared memory
shmdt()........Detach a shared-memory segment from a process
shmget().......Get the shared-memory segment

Memory Management

The following functions help to manage memory.

alloca().......Dynamically allocate space on the stack
calloc().......Allocate dynamic memory
free().........Return dynamic memory to free memory pool
malloc().......Allocate dynamic memory
realloc()......Reallocate dynamic memory
sbrk().........Increase a program's data space

Passwords and Groups

The   following   functions  manipulate   the   system  files   /etc/group,
/etc/password, and /etc/shadow, and uses the information found therein.

endgrent().....Close group file
endpwent().....Close password file
endspent().....Close the shadow-password file
getgrent().....Get group file information
getgrgid().....Get group file information, by group id
getgrnam().....Get group file information, by group name
getlogin().....Get login name
getpass()......Get password with prompting
getpw()........Search password file
getpwent().....Get password file information
getpwnam().....Get password file information, by name
getpwuid().....Get password file information, by identifier
getspent().....Get a shadow-password record
getspnam().....Get a shadow-password record, by user name
initgroups()...Initialize the supplementary group-access list
setgrent().....Rewind group file
setpwent().....Rewind password file
setspent().....Rewind the shadow-password file

Processes

The following functions execute  and terminate.  For information on how the
exec() functions differ, see the Lexicon entry execution.

_exit()........Terminate a process
abort()........End program immediately
atexit().......Register a function to be called when the program exits
ctermid()......Name the terminal device that controls the current process
execl()........Execute a load module
execle().......Execute a load module
execlp().......Execute a load module
execlpe()......Execute a load module
execv()........Execute a load module
execvp().......Execute a load module
execvpe()......Execute a load module
raise()........Let a process send a signal to itself
sleep()........Suspend execution

Random Number

libc contains the following functions for generating pseudo-random numbers:

drand48()......Return 48-bit pseudo-random number as double
erand48()......Return 48-bit pseudo-random number as double
jrand48()......Return 48-bit pseudo-random number as long integer
lcong48()......Initialize values from which 48-bit random numbers are computed
lrand48()......Return 48-bit pseudo-random number as non-negative long integer
mrand48()......Return 48-bit pseudo-random number as long integer
nrand48()......Return 48-bit pseudo-random number as non-negative long integer
rand().........Generate pseudo-random numbers
seed48().......Initialize values from which 48-bit random numbers are computed
srand()........Seed random number generator
srand48()......Seed 48-bit pseudo-random number routines

Regular Expressions

The following functions read and interpret UNIX-style regular expressions:

regcomp()......Compile a regular expression into a structure
regerror().....Return an error message from a regular-expression function
regexec()......Compare a string with a regular expression
regsub().......Use regular expression to build a string

STDIO

STDIO is an abbreviation for standard input and output.  It refers to a set
of  standard library  functions  that accompany  all C  compilers and  that
govern  input and  output with peripheral  devices.  COHERENT  includes the
following STDIO routines:

clearerr().....Present status stream
fclose().......Close a file stream
fdopen().......Open a file stream for I/O
feof().........Discover a file stream's status
ferror().......Discover a file stream's status
fflush().......Flush an output buffer
fgetc()........Get a character
fgetpos()......Read the file-position indicator
fgets()........Get a string
fgetw()........Get a word
fileno().......Get a file descriptor from a FILE structure
fopen()........Open a file stream
fprintf()......Format and print to a file stream
fputc()........Output a character
fputs()........Output a string
fputw()........Output a word
fread()........Read a file stream
freopen()......Open a file stream
fscanf().......Format and read from a file stream
fseek()........Seek in a file stream
fsetpos()......Set the file-position indicator
ftell()........Return file pointer position
fwrite().......Write to a file stream
getc().........Get a character
getchar()......Get a character
gets().........Get a string
getw().........Get a word
pclose().......Close a pipe
popen()........Open a pipe
printf().......Print a formatted string
putc().........Output a character
putchar()......Output a character
puts().........Output a string
putw().........Output a word
rewind().......Reset a file pointer
scanf()........Format and input from standard input
setbuf().......Set alternative file-stream buffer
setvbuf()......Set alternative file-stream buffer
sprintf()......Format and print to a string
sscanf().......Format and read from a string
tmpfile()......Create a temporary file
tmpnam().......Generate a unique name for a temporary file
ungetc().......Return character to file stream
vfprintf().....Format and print to a file stream
vprintf()......Print a formatted string
vsprintf().....Format and print to a string

String Functions

The  character string  is a  common formation in  C programs.   The runtime
representation  of  a  string is  an  array  of  ASCII  characters that  is
terminated by  a null character (`\0').   COHERENT uses this representation
when a program contains a string constant; for example:

               "I am a string constant"

The address  of the first character  in the string is  used as the starting
point of the string.  A pointer to a string holds only this address.  Note,
too, that an  array of 20 characters can hold  a string of 19 (not 20) non-
null characters;  the 20th character is the  null character that terminates
the string.

The  following routines  are  available to  help  manipulate strings.   The
prototypes for most are declared in the header file string.h:

bcmp().........Berkeley function to compare two chunks of memory
bcopy()........Berkeley function to copy memory
bzero()........Berkeley function to initialize memory to NUL
fnmatch()......Match a string with a normal expression
index()........Search string for a character; use strchr() instead
memccpy()......Copy a region of memory up to a set character
memchr().......Search a region of memory for a character
memcmp().......Compare two regions of memory
memcpy().......Copy one region of memory into another
memmove()......Copy one region of memory into another with which it overlaps
memset().......Fill a region of memory with a character
pnmatch()......Match string pattern
rindex().......Find rightmost occurrence of a character in a string
strcat().......Concatenate two strings
strcmp().......Compare two strings
strncat()......Append one string onto another
strncmp()......Compare two lengths for a set number of bytes
strcpy().......Copy a string
strncpy()......Copy a portion of a string
strcoll()......Compare two strings, using locale information
strcspn()......Return length one string excludes characters in another
strdup().......Duplicate a string
strerror().....Translate an error number into a string
strlen().......Measure a string
strpbrk()......Find first occurrence in string of character from another string
strchr().......Find leftmost occurrence of character in a string
strrchr()......Find rightmost occurrence of character in a string
strspn().......Return length one string includes character in another
strstr().......Find one string within another string
strtok().......Break a string into tokens
strxfrm()......Transform a string, using locale information

System Logs

The following  functions manipulate the files  /etc/utmp and /usr/adm/wtmp,
which record  login events on  your system.  The former  file records every
login that is still executing (i.e., the user has logged in and has not yet
logged), and every past login.

endutent().....Close the logging file.
getutent().....Read the next entry from /etc/utmp.
getutid()......Find an entry in /etc/utmp by login identifier.
getutline()....Find an entry in /etc/utmp by login device.
pututline()....Write a record into /etc/utmp.
setutent().....Rewind the input stream that is reading /etc/utmp
utmpname().....Manipulate a file other than /etc/utmp.

Terminals

The following functions help you cope with terminals.

isatty().......Check if a device is a terminal
ttyname()......Identify a terminal
ttyslot()......Return a terminal's line number

Standard Time Functions

libc includes the following functions to manipulate time:

asctime()......Convert time structure to ASCII string
clock()........Get processor time
ctime()........Convert system time to an ASCII string
difftime().....Return difference between two times
gmtime().......Convert system time to calendar structure
localtime()....Convert system time to calendar structure
mktime().......Turn broken-down time into calendar time
strftime().....Format locale-specific time
tzset()........Set local time zone

System Calls

The COHERENT  kernel makes many services available to  the C programmer.  A
programmer can use a COHERENT service through a system call.  libc includes
intefaces to the following system calls:

access().......Check if file can be accessed in given mode
acct().........Enable/disable process accounting
alarm()........Set an alarm
brk()..........Change size of data area
chdir()........Change working directory
chmod()........Change file protection modes
chown()........Change ownership of a file
chroot().......Change process's root directory
chsize().......Change the size of a file
close()........Close a file
creat()........Create/truncate a file
dup()..........Duplicate a file descriptor
execve().......Execute a load module
exit().........Terminate a program gracefully
fcntl()........Manipulate an open file
fork().........Create a new process
fpathconf()....Get a file variable by file descriptor
fstat()........Get information about a file system
fstatfs()......Get information about a file system
ftime()........Get current system time
getdents().....Read directory entries
getegid()......Get effective group id
geteuid()......Get effective user id
getgid().......Get real group id
getgroups()....Read the supplemental group-access list
getmsg().......Get the next message from a stream
getpgrp()......Get process-group identifier
getpid().......Get process id
getppid()......Get process id of parent process
getuid().......Get real user id
gtty().........Get terminal modes
ioctl()........Device-dependent control
kill().........Send a signal to a process
link().........Create a link
lseek()........Set read/write position
mkdir()........Create a directory
mkfifo().......Create a FIFO
mknod()........Create a special file
mount()........Mount a file system
nap()..........Sleep briefly
open().........Open a file
pathconf().....Get a file variable by path name
pause()........Wait for signal
pipe().........Create a pipe
poll().........Query several I/O devices
ptrace().......Trace process execution
putmsg().......Place a message onto a stream
read().........Read from a file
rename().......Rename a file
rmdir()........Remove a directory
setgid().......Set group id and user id
setgroups()....Set the supplemental group-access list
setpgid()......Set the process-group identifier
setpgrp()......Make a process a process-group leader
setsid().......Set session identifier
setuid().......Set user id
sigaction()....Perform detailed signal management
sigaddset()....Add a signal to a set of signals
sigdelset()....Delete a signal from a set
sigemptyset()..Initialize a set of signals
sigfillset()...Initialize a set of signals
sighold()......Place a signal on hold
sigignore()....Tell the system to ignore a signal
sigismember()..Check if a signal is a member of a set
signal().......Specify action to take upon receipt of a given signal
sigpause().....Pause until a given signal is received
sigpending()...Examine signals that are blocked and pending
sigprocmask()..Examine or change the signal mask
sigrelse().....Release a signal for processing
sigset().......Specify action to take upon receipt of a given signal
sigsuspend()...Install a signal mask and suspend process
stat().........Find file attributes
statfs().......Get information about a file system
stime()........Set the time
stty().........Set terminal modes
sync().........Flush system buffers
sysconf()......Get configurable system variables
sysi86().......Identify parts within Intel-based machines
time().........Get current system time
times()........Obtain process execution times
ulimit().......Get/set limits for a process
umask()........Set file creation mask
umount().......Unmount a file system
uname()........Get name and version of COHERENT
unlink().......Remove a file
ustat()........Get statistics on a file system
utime()........Change file access and modification times
wait().........Await completion of child process
waitpid()......Wait for a process to terminate
write()........Write to a file

Miscellaneous

The following functions do not fit neatly into any of the above categories.

bsearch()......Search an array
coffnlist()....Symbol table lookup
crypt()........Encryption using rotor algorithm
getenv().......Read environmental variable
getopt().......Get a command-line option
l3tol()........Convert file system block number to long integer
lockf()........Lock a file or a section of a file
longjmp()......Perform a non-local goto
ltol3()........Convert long integer to file system block number
mtype()........Return symbolic machine type
perror().......System call error messages
putenv().......Add a string to the environment
qsort()........Sort arrays in memory
setjmp().......Save machine state for non-local goto
siglongjmp()...Perform a non-local goto and restore signal mask
sigsetjmp()....Save machine state and signal mask for non-local jump
shellsort()....Sort arrays in memory
swab().........Swap a pair of bytes
system().......Pass a command to the shell for execution
tempnam()......Generate a unique name for a temporary file

See Also

libraries

Notes

You do not need to link libc explicitly into your programs.  The command cc
always includes it by default.

The macro offsetof() is not described above because it does not ``live'' in
libc; however,  it is a  useful, general-purpose entity.   For details, see
its Lexicon entry.

© 2012 by Stephen A. Ness