Table 4-1 lists and describes all the error- and signal-handling functions found in the HP C Run-Time Library (RTL). For more detailed information on each function, see the Reference Section.

Table 4-1 Error- and Signal-Handling Functions

Function	Description
abort	Raises the signal SIGABRT that terminates the execution of the program.
assert	Puts diagnostics into programs.
atexit	Registers a function to be called at program termination.
exit, _exit	Terminates the current program.
perror	Writes a short error message to stderr describing the current errno value.
strerror	Maps the error code in errno to an error message string.
alarm	Sends the signal SIGALARM to the invoking process after the number of seconds indicated by its argument has elapsed.
gsignal	Generates a specified software signal.
kill	Sends a SIGKILL signal to the process specified by a process ID.
longjmp	Transfers control from a nested series of function invocations back to a predefined point without returning normally.
pause	Causes the process to wait until it receives a signal.
raise	Generates a specified signal.
setjmp	Establishes the context for a later transfer of control from a nested series of function invocations, without returning normally.
sigaction	Specifies the action to take upon delivery of a signal.
sigaddset	Adds the specified individual signal.
sigblock	Causes the signals in its argument to be added to the current set of signals being blocked from delivery.
sigdelset	Deletes a specified individual signal.
sigemptyset	Initializes the signal set to exclude all signals.
sigfillset	Initializes the signal set to include all signals.
sighold	Adds the specified signal to the calling process's signal mask.
sigignore	Sets the disposition of the specified signal to SIG_IGN.
sigismember	Tests whether a specified signal is a member of the signal set.
siglongjmp	Nonlocal goto with signal handling.
sigmask	Constructs the mask for a given signal number.
signal	Catches or ignores a signal.
sigpause	Blocks a specified set of signals and then waits for a signal that was not blocked.
sigpending	Examines pending signals.
sigprocmask	Sets the current signal mask.
sigrelse	Removes the specified signal from the calling process's signal mask.
sigsetjmp	Sets the jump point for a nonlocal goto.
sigsetmask	Establishes the signals that are blocked from delivery.
sigstack	Defines an alternate stack on which to process signals.
sigsuspend	Atomically changes the set of blocked signals and waits for a signal.
sigtimedwait	Suspends a calling thread and waits for queued signals to arrive.
sigvec	Permanently assigns a handler for a specific signal.
sigwait	Suspends a calling thread and waits for queued signals to arrive.
sigwaitinfo	Suspends a calling thread and waits for queued signals to arrive.
ssignal	Allows you to specify the action to be taken when a particular signal is raised.
VAXC$ESTABLISH	Establishes an application exception handler in a way that is compatible with HP C RTL exception handling.

4.1 Error Handling

When an error occurs during a call to any of the HP C RTL functions, the function returns an unsuccessful status. Many RTL routines also set the external variable errno to a value that indicates the reason for the failure. You should always check the return value for an error situation.

The <errno.h> header file declares errno and symbolically defines the possible error codes. By including the <errno.h> header file in your program, you can check for specific error codes after a HP C RTL function call.

At program startup, the value of errno is 0. The value of errno can be set to a nonzero value by many HP C RTL functions. It is not reset to 0 by any HP C RTL function, so it is only valid to use errno after a HP C RTL function call has been made and a failure status returned. Table 4-2 lists the symbolic values that may be assigned to errno by the HP C RTL.

Table 4-2 The Error Code Symbolic Values

Symbolic Constant	Description
E2BIG	Argument list too long
EACCES	Permission denied
EADDRINUSE	Address already in use
EADDRNOTAVAIL	Can't assign requested address
EAFNOSUPPORT	Address family not supported
EAGAIN	No more processes
EALIGN	Alignment error
EALREADY	Operation already in progress
EBADF	Bad file number
EBADCAT	Bad message catalog format
EBADMSG	Corrupted message detected
EBUSY	Mount device busy
ECANCELED	Operation canceled
ECHILD	No children
ECONNABORTED	Software caused connection abort
ECONNREFUSED	Connection refused
ECONNRESET	Connection reset by peer
EDEADLK	Resource deadlock avoided
EDESTADDRREQ	Destination address required
EDOM	Math argument
EDQUOT	Disk quota exceeded
EEXIST	File exists
EFAIL	Cannot start operation
EFAULT	Bad address
EFBIG	File too large
EFTYPE	Inappropriate operation for file type
EHOSTDOWN	Host is down
EHOSTUNREACH	No route to host
EIDRM	Identifier removed
EILSEQ	Illegal byte sequence
EINPROGRESS	Operation now in progress
EINPROG	Asynchronous operation in progress
EINTR	Interrupted system call
EINVAL	Invalid argument
EIO	I/O error
EISCONN	Socket is already connected
EISDIR	Is a directory
ELOOP	Too many levels of symbolic links
EMFILE	Too many open files
EMLINK	Too many links
EMSGSIZE	Message too long
ENAMETOOLONG	File name too long
ENETDOWN	Network is down
ENETRESET	Network dropped connection on reset
ENETUNREACH	Network is unreachable
ENFILE	File table overflow
ENOBUFS	No buffer space available
ENODEV	No such device
ENOENT	No such file or directory
ENOEXEC	Exec format error
ENOLCK	No locks available
ENOMEM	Not enough core
ENOMSG	No message of desired type
ENOPROTOOPT	Protocol not available
ENOSPC	No space left on device
ENOSYS	Function not implemented
ENOTBLK	Block device required
ENOTCONN	Socket is not connected
ENOTDIR	Not a directory
ENOTEMPTY	Directory not empty
ENOTSOCK	Socket operation on nonsocket
ENOTSUP	Function not implemented
ENOTTY	Not a typewriter
ENWAIT	No waiting processes
ENXIO	No such device or address
EOPNOTSUPP	Operation not supported on socket
EPERM	Not owner
EPFNOSUPPORT	Protocol family not supported
EPIPE	Broken pipe
EPROCLIM	Too many processes
EPROTONOSUPPORT	Protocol not supported
EPROTOTYPE	Protocol wrong type for socket
ERANGE	Result too large
EREMOTE	Too many levels of remote in path
EROFS	Read-only file system
ESHUTDOWN	Can't send after socket shutdown
ESOCKTNOSUPPORT	Socket type not supported
ESPIPE	Illegal seek
ESRCH	No such process
ESTALE	Stale NFS file handle
ETIMEDOUT	Connection timed out
ETOOMANYREFS	Too many references: can't splice
ETXTBSY	Text file busy
EUSERS	Too many users
EVMSERR	OpenVMS specific nontranslatable error code
EWOULDBLOCK	I/O operation would block channel
EXDEV	Cross-device link

You can translate the error codes to a message, similar to that found in UNIX systems, by using the perror or strerror function. If errno is set to EVMSERR, perror cannot translate the error code and prints the following message, followed by the OpenVMS error message associated with the value:

%s:nontranslatable vms error code: xxxxxx vms message:

In the message, %s is the string you supply to perror ; xxxxxx is the OpenVMS condition value.

If errno is set to EVMSERR, then the OpenVMS condition value is available in the vaxc$errno variable declared in the <errno.h> header file. The vaxc$errno variable is guaranteed to have a valid value only if errno is set to EVMSERR; if errno is set to a value other than EVMSERR, the value of vaxc$errno is undefined.

See the strerror function in the Reference Section for another way to translate error codes.

4.2 Signal Handling

A signal is a form of software interrupt to the normal execution of a user process. Signals occur as a result of a variety of events, including any of the following:

• Typing Ctrl/C at a terminal
• Certain programming errors
• A call to the gsignal or raise function
• A wake-up action

Both OpenVMS and UNIX systems provide signal-handling mechanisms that behave differently but use similar terminology. With the HP C RTL, you can program using either signal-handling mechanism. Before describing the signal-handling routines, some terminology must be established.

The UNIX term for a software interrupt is signal. A routine called by the UNIX system to process a signal is termed a signal handler.

A software interrupt on an OpenVMS system is referred to as a signal, condition, or exception. A routine called by the OpenVMS system to process software interrupts is termed a signal handler, condition handler, or exception handler.

To prevent confusion, the terms signal and signal handler in this manual refer to UNIX interrupts and interrupt processing routines, while the terms exception and exception handler refer to OpenVMS interrupts and interrupt processing routines.

4.2.2 UNIX Signals and the HP C RTL

Signals are represented by mnemonics defined in the <signal.h> header file. Table 4-3 lists the supported signal mnemonics and the corresponding event that causes each signal to be generated on the OpenVMS operating system.

Table 4-3 HP C RTL Signals

Name	Description	Generated by
SIGABRT 1	Abort	abort ()
SIGALRM	Alarm clock	Timer AST, alarm routine
SIGBUS	Bus error	Access violation or change mode user
SIGCHLD	Child process stopped	Child process terminated or stopped
SIGEMT	EMT instruction	Compatibility mode trap or opcode reserved to customer
SIGFPE	Floating-point exception	Floating-point overflow/underflow
SIGHUP	Hang up	Data set hang up
SIGILL 1	Illegal instruction	Illegal instruction, reserved operand, or reserved address mode
SIGINT 4	Interrupt	OpenVMS Ctrl/C interrupt
SIGIOT 1	IOT instruction	Opcode reserved to customer
SIGKILL 2, 3	Kill	External signal only
SIGQUIT 5	Quit	Not implemented.
SIGPIPE	Broken pipe	Write to a pipe with no readers.
SIGSEGV	Segment violation	Length violation or change mode user
SIGSYS	System call error	Bad argument to system call
SIGTERM	Software terminate	External signal only
SIGTRAP 1	Trace trap	TBIT trace trap or breakpoint fault instruction
SIGUSR1	User-defined signal	Explicit program call to raise the signal
SIGUSR2	User-defined signal	Explicit program call to raise the signal
SIGWINCH 6	Window size changed	Explicit program call to raise the signal

By default, when a signal (except for SIGCHLD) occurs, the process is terminated. However, you can choose to have the signal ignored by using one of the following functions:

sigaction
signal
sigvec
ssignal

You can have the signal blocked by using one of the following functions:

sigblock
sigsetmask
sigprocmask
sigsuspend
sigpause

Table 4-3 indicates those signals that cannot be ignored or blocked.

You can also establish a signal handler to catch and process a signal by using one of the following functions:

sigaction
signal
sigvec
ssignal

Unless noted in Table 4-3, each signal can be reset. A signal is reset if the signal handler function calls signal or ssignal to re-establish itself to catch the signal. Example 4-1 shows how to establish a signal handler and reset the signal.

The calling interface to a signal handler is:

void handler (int sigint);

Where sigint is the signal number of the raised signal that caused this handler to be called.