[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


Chapter 4
Error and Signal Handling

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.
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 Filename 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

4.2.1 OpenVMS Versus UNIX Terminology

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

1Cannot be reset when intercepted.
2Cannot be intercepted or ignored.
3Cannot be blocked.
4Setting SIGINT can affect processing of Ctrl/Y interrupts. For example, in response to a caller's request to block or ignore SIGINT, the HP C RTL disables the Ctrl/Y interrupt.
5"Not implemented" for SIGQUIT means that there is no external event, including a Ctrl/Y interrupt, that would trigger a SIGQUIT signal, thereby causing a signal handler established for SIGQUIT to be invoked. This signal can be generated only through an appropriate HP C RTL function, such as raise.
6Supported on OpenVMS Version 7.3 and higher.

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.

A signal handler installed with sigvec remains installed until it is changed.

A signal handler installed with signal or signal remains installed until the signal is generated.


Previous Next Contents Index