Base System Definition Addendum
LEVEL Levell
Levell.
Page 90 Base System Definition Addendum
NAME
signal - specify what to do upon receipt of a signal SYNOPSIS
#include <signaI.h>
void (*signal(sig, fune» () int sig;
void (*fune) ();
DESCRIPTION
SIGNAL(BA_OS)
The function signal allows the calling-process to choose one of three ways in which it is possible to handle the receipt of a specific signal.
The argument sig specifies the signal and the argument fune specifies the choice. The argument sig can be assigned anyone of the following signals except SIGKILL:
SIGHUP hangup SIGINT interrupt SIGQUIT quit*
SIGILL illegal instruction (not reset when caught)*
SIGTRAP trace trap (not reset when caught)*
SIGABRT abort*
SIGFPE floating point exception*
SIGKILL kill (cannot be caught or ignored) SIGSYS bad argument to routine*
SIGPIPE write on a pipe with no one to read it SIGALRM alarm clock
SIGTERM software termination signal
* The default action for these signals is an abnormal process termination. See SIGJ>FL.
SIGNAL(BLOS)
SIGUSRI user-defined signal!
SIGUSR2 user-defined signal 2
For portability, application-programs should use or catch only the signals listed above; other signals are hardware- and implementation-dependent and may have very different meanings or results across systems. (For example, the System V signals SIGEMT, SIGBUS, SIGSEGV, and SIGIOT are implementation-dependent and are not listed above.) Specific imple-mentations may have other implementation-dependent signals.
The argument fune is assigned one of three values: SIG-DFL, SIG-IGN, or an address of a signal-catching function. The argument fune is declared as type pointer to a function returning void. The following actions are prescribed by these values:
SIG_DFL Terminate process upon receipt of a signal.
SIG-IGN with an asterisk above, implementation-dependent abnormal process termination routines, such as a core dump, may be invoked.
Ignore signal.
The signal sig is to be ignored.
NOTE: The signal SIGKILL cannot be ignored.
Catch signal.
Upon receipt of the signal sig, the receiving process is to exe-cute the signal-catching function pointed to by fune. The sig-nal number sig will be passed as the only argument to the signal-catching function. Additional arguments may be passed to the signal-catching function for hardware-generated signals.
Before entering the signal-catching function, the value of fune for the caught signal will be set to SIG-DFL unless the signal is SIGILL or SIGTRAP.
The function signal will not catch an invalid function argu-ment, fune, and results are undefined when an attempt is made to execute the function at the bad address.
Base System Definition Addendum
SIGNAL(BA_OS)
Upon return from the signal-catching function, the receiving process will resume execution at the point at which it was interrupted, except for implementation defined signals where this may not be true.
When a signal to be caught occurs during a non-atomic opera-tion such as a call to the READ(BA-OS), WRITE(BA_OS), OPEN(BA-OS), or IOCTL(BA-OS) routine on a slow device (such as a terminal); or occurs during a PAUSE(BA-OS) routine; or occurs during a WAIT(BA-OS) routine that does not return immediately, the signal-catching function will be executed and then the interrupted routine may return a -1 to the calling-process with errno set to EINTR.
NOTE: The signal SIGKILL cannot be caught.
A call to the function signal cancels a pending signal sig except for a pending SIGKILL signal.
RETURN VALUE
If successful, the function signal will return the previous value of the argu-ment fune for the specified signal sig; otherwise, it will return SIG_ERR and errno will indicate the error.
ERRORS
The function signal will fail and will set errno to:
EINV AL if sig is an illegal signal number or SIGKILL.
APPLICATION USAGE
Signals may be sent by the system to an application-program (user-level process) or signals may be sent by one user-level process to another using the KILL(BA_OS) routine. An application-program can catch signals and specify the action to be taken using the SIGNAL(BA-OS) routine. The sig-nals that a portable application-program may send are: SIGKILL, SIGTERM, SIGUSRl, and SIGUSR2.
For portability, application-programs should use only the symbolic names of signals rather than their values and use only the set of signals defined here.
Specific implementations may have additional signals.
SEE ALSO
KILL(BA_OS), PAUSE(BA-OS), WAIT(BA_OS), SET JMP(BA-LlB).
SIGNAL(BA_OS)
FUTURE DIRECTIONS
The end-user level utility KILL(BU_CMD) will be changed to use symbolic signal names rather than numbers.
LEVEL Levell.
Page 94 Base System Definition Addendum
NAME
sigset, sighold, sigrelse, sigignore - signal management SYNOPSIS
#inelude <signal.h>
void (*sigset(sig, fune» () int sig;
void (*fune) ();
int sighold(sig) int sig;
int sigrelse(sig) int sig;
int sigignore(sig) int sig;
DESCRIPTION
SIGSET(BA_OS)tt
The functions sigset, sighold, sigrelse, and sigignore enhance the signal facility and provide signal management for application processes.
The argument sig specifies the signal and the argument fune specifies the choice. The argument sig can be assigned anyone of the following signals except SIGKILL:
SIGHUP hangup SIGINT interrupt SIGQUIT quit*
SIGILL illegal instruction (not reset when caught)*
SIGTRAP trace trap (not reset when caught)*
SIGABRT abort*
SIGFPE floating point exception*
* The default action for these signals is an abnormal process termination. See SIG-DFL.
SIGSET(BA_OS)tt
SIGKILL kill (cannot be caught or ignored) SIGSYS bad argument to routine*
SIGPIPE write on a pipe with no one to read it SIGALRM alarm clock
SIGTERM software termination signal SIGUSRI user-defined signal 1 SIGUSR2 user-defined signal 2
For portability, application-programs should use or catch only the signals listed above; other signals are hardware- and implementation-dependent and may have very different meanings or results across systems. (For example, the System V signals SIGEMT, SIGBUS, SIGSEGV, and SIGIOT are implementation-dependent and are not listed above.) Specific imple-mentations may have other implementation-dependent signals.
The argument fune is assigned one of four values: SIG_DFL, SIG_IGN, SIG_HOLD, or an address of a signal-catching function. The argument fune is declared as type pointer to a function returning void. The follow-ing actions are prescribed by these values:
SIG_DFL Terminate process upon receipt of a signal.
Upon receipt of the signal sig, the receiving process is to be terminated with all of the consequences outlined in EXIT(BA_OS). In addition, if sig is one of the signals marked with an asterisk above, implementation-dependent abnormal process termination routines, such as a core dump, may be invoked.
Ignore signal.
Any pending signal sig is discarded. A pending signal is a sig-nal that has occurred but for which no action has been taken.
The system signal action is set to ignore future occurrences of this signal type.
SIG_HOLD Hold signal.
Page 96
The signal sig is to be held. Any pending signal of this type remains held. Only one signal of each type is held.
Base System Definition Addendum
address retained across calls to the other signal management functions, sighold and sigrelse. The signal number sig will be passed as the only argument to the signal-catching function. Before entering the signal-catching function, the value of fune for the caught signal will be set to SIG_HOLD. During normal return from the signal-catching handler, the system signal action is restored to fune and any held signal of this type is released. If a non-local goto [see SET JMP(BA-LlB)] is taken, the function sigrelse must be invoked to restore the system signal action and to release any held signal of this type.
Upon return from the signal-catching function, the receiving process will resume execution at the point at which it was interrupted, except for implementation defined signals where this may not be true.
When a signal to be caught occurs during a non-atomic opera-tion such as a call to the READ(BA-OS), WRITE(BA-OS), OPEN(BA-OS), or IOCTL(BA-OS) routine on a slow device (such as a terminal); or occurs during a PAUSE(BA-OS) routine; or occurs during a WAIT(BA-OS) routine that does not return immediately, the signal-catching function will be executed and then the interrupted routine may return a -1 to the calling-process with errno set to EINTR.
The function sigset specifies the system signal action to be taken upon receipt of the argument sig.
The function sighold and the function sigrelse establish critical regions of code. A call to the function sighold is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by the function sigrelse. The function sigrelse restores the system signal action to the action that was previously specified by the function sigset.
The function sigignore sets the action for the argument sig to SIG-IGN.
RETURN VALUE
If successful, the function sigset will return the previous value of the sys-tem signal action for the specified signal sig; otherwise, it will return SIG_ERR and errno will indicate the error.
SIGSET(B.LOS)tt
For the functions sighold, sigrelse, and sigignore a value of 0 will be returned upon success. Otherwise, a value of -1 will be returned and errno will indicate the error.
ERRORS
Under the following conditions, the functions sigset, sighold, sigrelse, and sigignore will fail and will set errno to:
EINV AL if sig is an illegal signal number or SIGKILL or if the default handling of sig cannot be changed.
APPLICATION USAGE
The functions sigset, sighold, sigrelse, and sigignore were added in System V Release 3.0.
For portability, application-programs should use only the symbolic names of signals rather than their values and use only the set of signals defined here.
Specific implementations may have additional signals.
The other signal management routine, SIGNAL(BA_OS), should not be used in conjunction with these routines for a particular signal type.
SEE ALSO
KILL(B~OS), PAUSE(BA_OS), SIGNAL(B~OS), WAIT(BA_OS), SET JMP(B~LlB).
LEVEL Level 1.
Page 98 Base System Definition Addendum
NAME
time - get time SYNOPSIS
#include <sys/types.h>
time_t time ( tloc) time_t *tloc;
DESCRIPTION
TIME(BA_OS)
The function time returns the value of time in seconds since 00:00:00 GMT, January 1, 1970.
As long as the argument tloc is not a null-pointer, the return value is also stored in the location to which the argument tloc points.
The actions of the function time are undefined if the argument tloc points to an invalid address.
RETURN VALUE
If successful, the function time will return the value of time; otherwise, it will return -1.
SEE ALSO
STIME(BA-OS).
LEVEL LevelL
USTAT(BA-OS)
NAME
ustat - get file system statistics SYNOPSIS
#include <sysjtypes.h>
#include <ustat.h>
int ustat(dev, buf) dev_t dev;
struct ustat *buf;
DESCRIPTION
The function ustat returns information about a mounted file system.
The argument dev is a device number identifying a device containing a mounted file-system. The value of dev is obtained from the field st_dev of the structure stat [see STAT(BA_OS)].
The argument buf is a pointer to a ustat structure that includes the follow-ing elements:
daddr t f_tfree; 1* total free blocks *1 ino - t f_tinode; 1* number of free i-nodes *1 char f_fname[6]; 1* file-system name or null *1 char f_fpack[6]; 1* file-system pack or null *1 The last two fields, f_fname and f_fpack may not have significant infor-mation on all systems, and, in that case, will contain the null character.
RETURN VALUE
If successful, the function ustat will return 0; otherwise, it will return -1 and errno will indicate the error.
ERRORS
Under the following conditions, the function ustat will fail and will set errno to:
EINV AL if dev is not the device number of a device containing a mounted file-system.
SEE ALSO
STAT(BA_OS).
LEVEL Levell.
Page 100 Base System Definition Addendum
NAME
write - write on a file SYNOPSIS
int write(fildes, buf, nbyte) int fildes;
char *buf;
unsigned nbyte;
DESCRIPTION
WRITE(BLOS)
The function write attempts to write nbyte bytes from the buffer pointed to by the argument buf to the file associated with the argument fildes.
The argument fildes is an open file-descriptor [see file-descriptor in Chapter 4 - Definitions].
On devices capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file-pointer associated with the argu-ment fildes. Upon returning from the function write, the file-pointer is incremented by the number of bytes actually written.
On devices incapable of seeking, such as a terminal, writing always takes place starting at the current position. The value of a file-pointer associated with such a device is undefined [see OPEN(BA-OS)].
If the O-APPEND flag of the file status flags is set, the file-pointer will be set to the end of the file prior to each write operation.
For ordinary files, if the O_SYNC flag of the file status flags is set, the write should not return until both the file data and file status have been physically updated. For block special files, if O_SYNC is set, the write should not return until the data has been physically updated. The way the data reaches the physical media is implementation- and hardware-dependent.
When attempting to write to an ordinary file with enforced record locking enabled [see CHMOD(BA-OS)]. and all or part of the file to be written has a read or write lock owned by another process (i.e., a blocking lock):
If O.-NDELA Y is set, the function write will return -1 and errno will be set to EAGAIN.
If O.-NDELAY is clear, the function write will sleep until all blocking locks are removed, or the function write is terminated by a signal.
If a write requests that more bytes be written than there is room for (e.g., beyond the user process' file size limit [see ULlMIT(BA_OS)] or the physical end of a medium), only as many bytes as there is room for will be written.
For example, suppose there is space for 20 bytes more in a file before reach-ing a limit. A write of 512-bytes will return 20-bytes. The next write of a non-zero number of bytes will give a failure return (except as noted for pipes and FIFOs below).
If a write to a pipe (or FIFO) of {PIPE~UF} bytes or less is requested and less than nbytes bytes of free space is available in the pipe, one of the following will occur:
If the O_NDELAY flag is clear, the process will block until at least nbytes of space is available in the pipe and then the write will take place, or
If the O_NDELA Y flag is set, the process will not block and the function write will return O.
If a write to a pipe (or FIFO) of more than {PIPE~UF} bytes is requested, one of the following will occur:
If the O_NDELAY flag is clear, the process will block if the pipe is full. As space becomes available in the pipe, the data from the write request will be written piecemeal - in multiple smaller amounts until the request is fulfilled. Thus, data from a write request of more than {PIPE~UF} bytes may be interleaved on arbitrary byte boundaries with data written by other processes.
If the O_NDELA Y flag is set and the pipe is full, the process will not block and the function write will return O.
If the O_NDELA Y flag is set and the pipe is not full, the process will not block and as much data as will currently fit in the pipe will be written, and the function write will return the number of bytes written. In this case, only part of the data are written, but what data are written will not be interleaved with data from other processes.
In contrast to write requests of more than {PIPE~UF} bytes, data from a write request of {PIPE~UF} bytes or less will never be interleaved in the pipe with data from other processes.
Page 102 Base System Definition Addendum
WRITE(BA_OS)
RETURN VALUE
If successful, the function write will return the number of bytes actually written; otherwise, it will return -1, the file-pointer will remain unchanged, and errno will indicate the error.
ERRORS is not open for reading by any process.
EFBIG file-descriptor is a block-special or character-special file and the file-pointer value is out of
WRITE(BJLOS)
APPLICATION USAGE
Normally, applications should use the stdio routines to open, close, read and write files. Thus, if an application had used the FOPEN(BA-OS) stdio rou-tine to open a file, it would use the FWRITE(BA-OS) stdio routine rather than the WRITE(BA-OS) routine to write it.
Because they are not atomic, write requests of nbytes greater than {PIPE-BUF} bytes to a pipe (or FIFO) should only be used when just two cooperating processes, one reader and one writer, are using a pipe.
When O~DELAY is set, portable application-programs should test for two conditions to determine that no data is currently available, for example:
fildes = open(path, O_WRONLY I O_NDELAY);
ret = write(fildes, buf, nbyte);
i f (ret == 0 " (ret == -1 && errno == EAGAIN»
1* Data not available now. *1
Use of the O_SYNC flag should be used by applications that require extra reliability at the cost of performance.
SEE ALSO
CREAT(BA-OS), DUP(BA_OS), LSEEK(BA-OS), OPEN(BA_OS), PIPE(BA_OS), U LI M IT(BA-OS).
LEVEL Levell.
Page 104 Base System Definition Addendum