lliibbcc -- Library

Standard C library
/lliibb/lliibbcc.aa

lliibbcc 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.

_B_i_n_a_r_y _D_a_t_a
The following functions manipulate binary data types, that is, integers and
floating-point numbers.

aabbss()..........Return the absolute value of an integer
ddeeccvvaaxx_dd().....Convert a ddoouubbllee from IEEE to DECVAX format
ddeeccvvaaxx_ff().....Convert a ffllooaatt from IEEE to DECVAX format
ddiivv()..........Perform integer division
ffrreexxpp()........Separate fraction and exponent
iieeeeee_dd().......Convert a ddoouubbllee from DECVAX to IEEE format
iieeeeee_ff().......Convert a ffllooaatt from DECVAX to IEEE format
llddeexxpp()........Combine fraction and exponent
llddiivv().........Perform long integer division
mmooddff().........Separate integral part and fraction

_B_i_n_a_r_y _D_a_t_a _a_n_d _S_t_r_i_n_g_s
The following functions convert binary data forms to strings, or strings to
binary forms.

aattooff().........Convert ASCII strings to floating point
aattooii().........Convert ASCII strings to integers
aattooll().........Convert ASCII strings to long integers
eeccvvtt().........Convert floating-point numbers to strings
ffccvvtt().........Convert floating-point numbers to strings
ggccvvtt().........Convert floating-point numbers to strings
ssttrrttoodd().......Convert string to floating-point number
ssttrrttooll().......Convert string to long integer
ssttrrttoouull()......Convert string to unsigned long integer

_c_t_y_p_e _F_u_n_c_t_i_o_n_s
The  ccttyyppee functions  test  a character's  _t_y_p_e.  Some  can transform  some
characters  into  others.  ``ctype''  is  an  abbreviation for  ``character
type''; all are declared or defined  in the header file <ccttyyppee.hh>. They are
as follows:

_ttoolloowweerr().....Convert an upper-case character to lower case
_ttoouuppppeerr().....Convert a lower-case character to upper case
iissaallnnuumm()......Test if alphanumeric character
iissaallpphhaa()......Test if alphabetic character
iissaasscciiii()......Test if ASCII character
iissccnnttrrll()......Test if a control character
iissddiiggiitt()......Test if a numeric digit
iissggrraapphh()......Test if a graphics character
iisslloowweerr()......Test if lower-case character
iisspprriinntt()......Test if printable character
iissppuunncctt()......Test if punctuation mark
iissssppaaccee()......Test if a tab, space, or return
iissuuppppeerr()......Test if upper-case character
iissxxddiiggiitt().....Test if hexadecimal numeral
ttooaasscciiii()......Convert a character to ASCII
ttoolloowweerr()......Convert an upper-case character to lower case
ttoouuppppeerr()......Convert a lower-case character to upper case

_F_i_l_e_s _a_n_d _D_i_r_e_c_t_o_r_i_e_s
The following  functions are used to manipulate  files and directories, and
their names.

_ggeettwwdd().......Get current working directory name
cclloosseeddiirr().....Close a directory stream
dduupp22().........Duplicate a file descriptor
ggeettccwwdd().......Get current working directory
mmkktteemmpp().......Generate a temporary file name
ooppeennddiirr()......Open a directory stream
ppaatthh().........Build a path name for a file
rreeaaddddiirr()......Read a directory stream
rreemmoovvee().......Remove a file
rreewwiinnddddiirr()....Rewind a directory stream
sseeeekkddiirr()......Reset the position within a directory stream
tteellllddiirr()......Return position within a directory stream

_I_n_t_e_r_p_r_o_c_e_s_s _C_o_m_m_u_n_i_c_a_t_i_o_n
The following functions perform interprocess communcation.

ffttookk().........Generate keys for interprocess communication
mmssggccttll().......Control message operation
mmssggggeett().......Get a message queue
mmssggrrccvv().......Receive a message
mmssggssnndd().......Send a message
sseemmccttll().......Control semaphore operations
sseemmggeett().......Get a set of semaphores
sseemmoopp()........Perform semaphore operations
sshhmmaatt()........Attach a shared-memory segment to a process
sshhmmccttll().......Manipulate shared memory
sshhmmddtt()........Detach a shared-memory segment from a process
sshhmmggeett().......Get the shared-memory segment

_M_e_m_o_r_y _M_a_n_a_g_e_m_e_n_t
The following functions help to manage memory.

aallllooccaa().......Dynamically allocate space on the stack
ccaalllloocc().......Allocate dynamic memory
ffrreeee().........Return dynamic memory to free memory pool
mmaalllloocc().......Allocate dynamic memory
rreeaalllloocc()......Reallocate dynamic memory
ssbbrrkk().........Increase a program's data space

_P_a_s_s_w_o_r_d_s _a_n_d _G_r_o_u_p_s
The  following  functions manipulate  the  system  files /eettcc/ppaasssswwoorrdd  and
/eettcc/ggrroouupp, and uses the information found therein.

eennddggrreenntt().....Close group file
eennddppwweenntt().....Close password file
ggeettggrreenntt().....Get group file information
ggeettggrrggiidd().....Get group file information, by group id
ggeettggrrnnaamm().....Get group file information, by group name
ggeettllooggiinn().....Get login name
ggeettppaassss()......Get password with prompting
ggeettppww()........Search password file
ggeettppwweenntt().....Get password file information
ggeettppwwnnaamm().....Get password file information, by name
ggeettppwwuuiidd().....Get password file information, by id
iinniittggrroouuppss()...Initialize the supplementary group-access list
sseettggrreenntt().....Rewind group file
sseettppwweenntt().....Rewind password file

_P_r_o_c_e_s_s_e_s
The following functions execute  and terminate.  For information on how the
eexxeecc() functions differ, see the Lexicon entry eexxeeccuuttiioonn.

_eexxiitt()........Terminate a process
aabboorrtt()........End program immediately
aatteexxiitt().......Register a function to be called when the program exits
eexxeeccll()........Execute a load module
eexxeeccllee().......Execute a load module
eexxeeccllpp().......Execute a load module
eexxeeccllppee()......Execute a load module
eexxeeccvv()........Execute a load module
eexxeeccvvpp().......Execute a load module
eexxeeccvvppee()......Execute a load module
rraaiissee()........Let a process send a signal to itself
sslleeeepp()........Suspend execution

_S_T_D_I_O
_S_T_D_I_O is an abbreviation for _s_t_a_n_d_a_r_d _i_n_p_u_t _a_n_d _o_u_t_p_u_t.  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:

cclleeaarreerrrr().....Present status stream
ffcclloossee().......Close a file stream
ffddooppeenn().......Open a file stream for I/O
ffeeooff().........Discover a file stream's status
ffeerrrroorr().......Discover a file stream's status
fffflluusshh().......Flush an output buffer
ffggeettcc()........Get a character
ffggeettppooss()......Read the file-position indicator
ffggeettss()........Get a string
ffggeettww()........Get a word
ffiilleennoo().......Get a file descriptor from a FFIILLEE structure
ffooppeenn()........Open a file stream
ffpprriinnttff()......Format and print to a file stream
ffppuuttcc()........Output a character
ffppuuttss()........Output a string
ffppuuttww()........Output a word
ffrreeaadd()........Read a file stream
ffrreeooppeenn()......Open a file stream
ffssccaannff().......Format and read from a file stream
ffsseeeekk()........Seek in a file stream
ffsseettppooss()......Set the file-position indicator
fftteellll()........Return file pointer position
ffwwrriittee().......Write to a file stream
ggeettcc().........Get a character
ggeettcchhaarr()......Get a character
ggeettss().........Get a string
ggeettww().........Get a word
ppcclloossee().......Close a pipe
ppooppeenn()........Open a pipe
pprriinnttff().......Print a formatted string
ppuuttcc().........Output a character
ppuuttcchhaarr()......Output a character
ppuuttss().........Output a string
ppuuttww().........Output a word
rreewwiinndd().......Reset a file pointer
ssccaannff()........Format and input from standard input
sseettbbuuff().......Set alternative file-stream buffer
sseettvvbbuuff()......Set alternative file-stream buffer
sspprriinnttff()......Format and print to a string
ssssccaannff().......Format and read from a string
ttmmppffiillee()......Create a temporary file
ttmmppnnaamm().......Generate a unique name for a temporary file
uunnggeettcc().......Return character to file stream
vvffpprriinnttff().....Format and print to a file stream
vvpprriinnttff()......Print a formatted string
vvsspprriinnttff().....Format and print to a string

_S_t_r_i_n_g _F_u_n_c_t_i_o_n_s
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 (_n_o_t 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 ssttrriinngg.hh:

ffnnmmaattcchh()......Match a string with a normal expression
iinnddeexx()........Search string for a character; use ssttrrcchhrr() instead
mmeemmccccppyy()......Copy a region of memory up to a set character
mmeemmcchhrr().......Search a region of memory for a character
mmeemmccmmpp().......Compare two regions of memory
mmeemmccppyy().......Copy one region of memory into another
mmeemmmmoovvee()......Copy one region of memory into another with which it overlaps
mmeemmsseett().......Fill a region of memory with a character
ppnnmmaattcchh()......Match string pattern
rriinnddeexx().......Find rightmost occurrence of a character in a string
ssttrrccaatt().......Concatenate two strings
ssttrrccmmpp().......Compare two strings
ssttrrnnccaatt()......Append one string onto another
ssttrrnnccmmpp()......Compare two lengths for a set number of bytes
ssttrrccppyy().......Copy a string
ssttrrnnccppyy()......Copy a portion of a string
ssttrrccoollll()......Compare two strings, using locale information
ssttrrccssppnn()......Return length one string excludes characters in another
ssttrrdduupp().......Duplicate a string
ssttrreerrrroorr().....Translate an error number into a string
ssttrrlleenn().......Measure a string
ssttrrppbbrrkk()......Find first occurrence in string of character from another string
ssttrrcchhrr().......Find leftmost occurrence of character in a string
ssttrrrrcchhrr()......Find rightmost occurrence of character in a string
ssttrrssppnn().......Return length one string includes character in another
ssttrrssttrr().......Find one string within another string
ssttrrttookk().......Break a string into tokens
ssttrrxxffrrmm()......Transform a string, using locale information

_T_e_r_m_i_n_a_l_s
The following functions help you cope with terminals.

iissaattttyy().......Check if a device is a terminal
ttttyynnaammee()......Identify a terminal
ttttyysslloott()......Return a terminal's line number

_S_t_a_n_d_a_r_d _T_i_m_e _F_u_n_c_t_i_o_n_s
lliibbcc includes the following functions to manipulate time:

aassccttiimmee()......Convert time structure to ASCII string cclloocckk()Get  processor
time ccttiimmee()...Convert system time to an ASCII string ddiiffffttiimmee()Return
difference between two times ggmmttiimmee()Convert   system   time  to   calendar
structure llooccaallttiimmee()Convert system time to calendar structure mmkkttiimmee() Turn
broken-down time into calendar time ssttrrffttiimmee()Format  locale-specific  time
ttzzsseett()........Set local time zone

_S_y_s_t_e_m _C_a_l_l_s
The COHERENT  kernel makes many services available to  the C programmer.  A
programmer can use a COHERENT service through a system call.  lliibbcc includes
intefaces to the following system calls:

aacccceessss().......Check if file can be accessed in given mode
aacccctt().........Enable/disable process accounting
aallaarrmm()........Set an alarm
bbrrkk()..........Change size of data area
cchhddiirr()........Change working directory
cchhmmoodd()........Change file protection modes
cchhoowwnn()........Change ownership of a file
cchhrroooott().......Change process's root directory
cchhssiizzee().......Change the size of a file
cclloossee()........Close a file
ccrreeaatt()........Create/truncate a file
dduupp()..........Duplicate a file descriptor
eexxeeccvvee().......Execute a load module
eexxiitt().........Terminate a program gracefully
ffccnnttll()........Manipulate an open file
ffoorrkk().........Create a new process
ffppaatthhccoonnff()....Get a file variable by file descriptor
ffssttaatt()........Get information about a file system
ffssttaattffss()......Get information about a file system
ffttiimmee()........Get current system time
ggeettddeennttss().....Read directory entries
ggeetteeggiidd()......Get effective group id
ggeetteeuuiidd()......Get effective user id
ggeettggiidd().......Get real group id
ggeettggrroouuppss()....Read the supplemental group-access list
ggeettmmssgg().......Get the next message from a stream
ggeettppggrrpp()......Get process-group identifier
ggeettppiidd().......Get process id
ggeettppppiidd()......Get process id of parent process
ggeettuuiidd().......Get real user id
ggttttyy().........Get terminal modes
iiooccttll()........Device-dependent control
kkiillll().........Send a signal to a process
lliinnkk().........Create a link
llsseeeekk()........Set read/write position
mmkkddiirr()........Create a directory
mmkkffiiffoo().......Create a FIFO
mmkknnoodd()........Create a special file
mmoouunntt()........Mount a file system
nnaapp()..........Sleep briefly
ooppeenn().........Open a file
ppaatthhccoonnff().....Get a file variable by path name
ppaauussee()........Wait for signal
ppiippee().........Create a pipe
ppoollll().........Query several I/O devices
ppttrraaccee().......Trace process execution
ppuuttmmssgg().......Place a message onto a stream
rreeaadd().........Read from a file
rreennaammee().......Rename a file
rrmmddiirr()........Remove a directory
sseettggiidd().......Set group id and user id
sseettggrroouuppss()....Set the supplemental group-access list
sseettppggiidd()......Set the process-group identifier
sseettppggrrpp()......Make a process a process-group leader
sseettssiidd().......Set session identifier
sseettuuiidd().......Set user id
ssiiggaaccttiioonn()....Perform detailed signal management
ssiigghhoolldd()......Place a signal on hold
ssiiggiiggnnoorree()....Tell the system to ignore a signal
ssiiggnnaall().......Specify action to take upon receipt of a given signal
ssiiggppaauussee().....Pause until a given signal is received
ssiiggppeennddiinngg()...Examine signals that are blocked and pending
ssiiggpprrooccmmaasskk()..Examine or change the signal mask
ssiiggrreellssee().....Release a signal for processing
ssiiggsseett().......Specify action to take upon receipt of a given signal
ssiiggssuussppeenndd()...Install a signal mask and suspend process
ssttaatt().........Find file attributes
ssttaattffss().......Get information about a file system
ssttiimmee()........Set the time
ssttttyy().........Set terminal modes
ssyynncc().........Flush system buffers
ssyyssccoonnff()......Get configurable system variables
ssyyssii8866().......Identify parts within Intel-based machines
ttiimmee().........Get current system time
ttiimmeess()........Obtain process execution times
uulliimmiitt().......Get/set limits for a process
uummaasskk()........Set file creation mask
uummoouunntt().......Unmount a file system
uunnaammee()........Get name and version of COHERENT
uunnlliinnkk().......Remove a file
uussttaatt()........Get statistics on a file system
uuttiimmee()........Change file access and modification times
wwaaiitt().........Await completion of child process
wwaaiittppiidd()......Wait for a process to terminate
wwrriittee()........Write to a file

_M_i_s_c_e_l_l_a_n_e_o_u_s
The following functions do not fit neatly into any of the above categories.

bbsseeaarrcchh()......Search an array
ccooffffnnlliisstt()....Symbol table lookup
ccrryypptt()........Encryption using rotor algorithm
ggeetteennvv().......Read environmental variable
ggeettoopptt().......Get a command-line option
ll33ttooll()........Convert file system block number to long integer
lloocckkff()........Lock a file or a section of a file
lloonnggjjmmpp()......Perform a non-local goto
llttooll33()........Convert long integer to file system block number
mmttyyppee()........Return symbolic machine type
ppeerrrroorr().......System call error messages
ppuutteennvv().......Add a string to the environment
qqssoorrtt()........Sort arrays in memory
rraanndd().........Generate pseudo-random numbers
sseettjjmmpp().......Save machine state for non-local goto
ssiigglloonnggjjmmpp()...Perform a non-local goto and restore signal mask
ssiiggsseettjjmmpp()....Save machine state and signal mask for non-local jump
sshheellllssoorrtt()....Sort arrays in memory
ssrraanndd()........Seed random number generator
sswwaabb().........Swap a pair of bytes
ssyysstteemm().......Pass a command to the shell for execution
tteemmppnnaamm()......Generate a unique name for a temporary file

_S_e_e _A_l_s_o
lliibbrraarriieess

_N_o_t_e_s
You do not need to link lliibbcc explicitly into your programs.  The command cccc
always includes it by default.
