United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

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 also 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 Compaq 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 Compaq 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 Compaq 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 caught.
2Cannot be caught 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 Compaq 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 Compaq 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.

A signal handler can be installed for more than one signal. Use the `sigaction` routine with the flag SA_RESETHAND to control this.

## 4.2.3 Signal-Handling Concepts

A signal is said to be generated for (or sent to) a process when the event that causes the signal first occurs. Examples of such events include detection of hardware faults, timer expiration, and terminal activity, as well as the invocation of `kill` . In some circumstances, the same event generates signals for multiple processes.

Each process has an action to be taken in response to each signal defined by the system. A signal is said to be delivered to a process when the appropriate action for the process and signal is taken.

During the time between the generation of a signal and its delivery, the signal is said to pending. Ordinarily, this interval cannot be detected by an application. However, a signal can be blocked from delivery to a process:

- If the action associated with a blocked signal is anything other than to ignore the signal, and if that signal is generated for the process, the signal remains pending until either it is unblocked or the action associated with it is set to ignore the signal.
- If the action associated with a blocked signal is to ignore the signal and if that signal is generated for the process, it is unspecified whether the signal is discarded immediately upon generation or remains pending.

Each process has a signal mask that defines the set of signals currently blocked from delivery to it. The signal mask for a process is initialized from that of its parent. The `sigaction` , `sigprocmask` , and `sigsuspend` function control the manipulation of the signal mask.

The determination of which action is taken in response to a signal is made at the time the signal is delivered, allowing for any changes since the time of generation. This determination is independent of the means by which the signal was originally generated. If a subsequent occurrence of a pending signal is generated, it is implementation-dependent as to whether the signal is delivered more than once. The Compaq C RTL delivers the signal only once. The order in which multiple, simultaneously pending signals are delivered to a process is unspecified.

## 4.2.4 Signal Actions

This section applies to the `sigaction` , `signal` , `sigvec` , and `ssignal` functions.

There are three types of action that can be associated with a signal:

> SIG_DFL
> SIG_IGN
> pointer to a function

Initially, all signals are set to SIG_DFL or SIG_IGN prior to entry of the `main` routine (see the `exec` functions.) The actions prescribed by these values are:

> SIG_DFL --- signal-specific default action
> - The default actions for the signals defined in this document are specified under `<signal.h>` .
> - If the default action is to stop the process, the execution of that process is temporarily suspended. When a process stops, a SIGCHLD signal is generated for its parent process, unless the parent process has set the SA_NOCLDSTOP flag. While a process is stopped, any additional signals that are sent to the process are not delivered until the process is continued, except SIGKILL which always terminates the receiving process. A process that is a member of an orphaned process group is not allowed to stop in response to the SIGSTOP, SIGTTIN, or SIGTTOU signals. In cases where delivery of one of these signals would stop such a process, the signal is discarded.
> - Setting a signal action to SIG_DFL for a signal that is pending and whose default action is to ignore the signal (for example, SIGCHLD), causes the pending signal to be discarded, whether or not it is blocked.
> SIG_IGN --- ignore signal
> - Delivery of the signal has no effect on the process. The behavior of a process is undefined after it ignores a SIGFPE, SIGILL, or SIGSEGV signal that was not generated by `kill` or `raise` .
> - The system does not allow the action for the SIGKILL or SIGSTOP signals to be set to SIG_IGN.
> - Setting a signal action to SIG_IGN for a signal that is pending causes the pending signal to be discarded, whether or not it is blocked.
> - If a process sets the action for the SIGCHLD signal to SIG_IGN, the behavior is unspecified.
> pointer to a function --- catch signal
> - On delivery of the signal, the receiving process executes the signal-catching function at the specified address. After returning from the signal-catching function, the receiving process resumes execution at the point at which it was interrupted.
> - Specify the signal-catching function as:

>       void func(int signo);

>   Where func is the specified signal-catching function and signo is the signal number of the signal being delivered.
> - The behavior of a process is undefined after it returns normally form a signal-catching function for a SIGFPE, SIGKILL, or SIGSEGV signal that was not generated by `kill` or `raise` .
> - The system does not allow a process to catch the signals SIGKILL and SIGSTOP.
> - If a process establishes a signal-catching function for the SIGCHLD signal while it has a terminated child process for which it has not waited, it is unspecified whether a SIGCHLD signal is generated to indicate that child process.

## 4.2.5 Signal Handling and OpenVMS Exception Handling

This section discusses how Compaq C RTL signal handling is implemented with and interacts with OpenVMS exception handling. Information in this section allows you to write OpenVMS exception handlers that do not conflict with Compaq C RTL signal handling. For information on OpenVMS exception handling, see the VAX Procedure Calling and Condition Handling Standard.

The Compaq C RTL implements signals with OpenVMS exceptions. When `gsignal` or `raise` is called, the signal number is translated to a particular OpenVMS exception, which is used in a call to LIB$SIGNAL. This mechanism is necessary to catch an OpenVMS exception resulting from a user error and translate it into a corresponding UNIX signal. For example, an ACCVIO resulting from a write to a NULL pointer is translated to a SIGBUS or SIGSEGV signal.

Tables 4_4 and 4-5 list the Compaq C RTL signal names, the corresponding OpenVMS VAX and OpenVMS Alpha exceptions, the event that generates the signal, and the optional signal code for use with the `gsignal` and `raise` functions.

Table 4-4 Compaq C RTL Signals and Corresponding OpenVMS VAX Exceptions (VAX ONLY)
Name | OpenVMS Exception | Generated By | Code
--- | --- | --- | ---
SIGABRT | SS$_OPCCUS | The `abort` function | --
SIGALRM | SS$_ASTFLT | The `alarm` function | --
SIGBUS | SS$_ACCVIO | Access violation | --
SIGBUS | SS$_CMODUSER | Change mode user | --
SIGCHLD | C$_SIGCHLD | Child process stopped | --
SIGEMT | SS$_COMPAT | Compatibility mode trap | --
SIGFPE | SS$_DECOVF | Decimal overflow trap | FPE_DECOVF_TRAP
SIGFPE | SS$_FLTDIV | Floating/decimal division by 0 | FPE_FLTDIV_TRAP
SIGFPE | SS$_FLTDIV_F | Floating divide by 0 fault | FPE_FLTDIV_FAULT
SIGFPE | SS$_FLTOVF | Floating overflow trap | FPE_FLTOVF_TRAP
SIGFPE | SS$_FLTOVF_F | Floating overflow fault | FPE_FLTOVF_FAULT
SIGFPE | SS$_FLTUND | Floating undeflow trap | FPE_FLTUND_TRAP
SIGFPE | SS$_FLTUND_F | Floating undeflow fault | FPE_FLTUND_FAULT
SIGFPE | SS$_INTDIV | Integer division by 0 | FPE_INTDIV_TRAP
SIGFPE | SS$_INTOVF | Integer overflow | FPE_INTOVF_TRAP
SIGFPE | SS$_SUBRNG | Subscript-range | FPE_SUBRNG_TRAP
SIGHUP | SS$_HANGUP | Data set hangup | --
SIGILL | SS$_OPCDEC | Reserved instruction | ILL_PRIVIN_FAULT
SIGILL | SS$_RADRMOD | Reserved addressing | ILL_RESAD_FAULT
SIGILL | SS$_ROPRAND | Reserved operand | ILL_RESOP_FAULT
SIGINT | SS$_CONTROLC | OpenVMS Ctrl/C interrupt | --
SIGIOT | SS$_OPCCUS | Customer-reserved opcode | --
SIGKILL | SS$_ABORT | External signal only | --
SIGQUIT | SS$_CONTROLY | The `raise` function | --
SIGPIPE | SS$_NOMBX | No mailbox | --
SIGSEGV | SS$_ACCVIO | Length violation | --
SIGSEGV | SS$_CMODUSER | Change mode user | --
SIGSYS | SS$_BADPARAM | Bad argument to system call | --
SIGTERM | Not implemented | -- | --
SIGTRAP | SS$_TBIT | TBIT trace trap | --
SIGTRAP | SS$_BREAK | Breakpoint fault instruction | --
SIGUSR1 | C$_SIGUSR1 | The `raise` function | --
SIGUSR2 | C$_SIGUSR2 | The `raise` function | --
SIGWINCH 1 | C$_SIGWINCH 2 | The `raise` function | --

1Supported on OpenVMS Version 7.3 and higher.
2SS$_BADWINCNT when C$_SIGWINCH not defined (OpenVMS versions before 7.3).

To call a signal handler that you have established with `signal` or `sigvec` , the Compaq C RTL intercepts the OpenVMS exceptions that correspond to signals by having an OpenVMS exception handler in the main routine of the program. If your program has a `main` function, then this exception handler is automatically established. If you do not have a `main` function, or if your main function is written in a language other than Compaq C, then you must invoke the `VAXC$CRTL_INIT` routine to establish this handler.

The Compaq C RTL uses OpenVMS exceptions to implement the `setjmp` and `longjmp` functions. When the `longjmp` function is called, a C$_LONGJMP OpenVMS exception is signaled. To prevent the C$_LONGJMP exception from being interfered with by user exception handlers, use the `VAXC$ESTABLISH` routine to establish user OpenVMS exception handlers instead of calling LIB$ESTABLISH. The C$_LONGJMP mnemonic is defined in the `<errnodef.h>` header file.

If you want to use OpenVMS exception handlers and UNIX signals in your C program, your OpenVMS exception handler must be prepared to accept and resignal the OpenVMS exceptions listed in Tables 4_4 (VAX ONLY) and 4-5 (ALPHA ONLY) , as well as the C$_LONGJMP exception and any C$ facility exception that might be introduced in future versions of the Compaq C RTL. This is because UNIX signals are global in context, whereas OpenVMS exceptions are stack-frame based.

Consequently, an OpenVMS exception handler always receives the exception that corresponds to the UNIX signal before the Compaq C RTL exception handler in the main routine does. By resignaling the OpenVMS exception, you allow the Compaq C RTL exception handler to receive the exception. You can intercept any of those OpenVMS exceptions yourself, but in doing so you will disable the corresponding UNIX signal.

Table 4-5 Compaq C RTL Signals and Corresponding OpenVMS Alpha Exceptions (ALPHA ONLY)
Name | OpenVMS Exception | Generated By | Code
--- | --- | --- | ---
SIGABRT | SS$_OPCCUS | The `abort` function | --
SIGALRM | SS$_ASTFLT | The `alarm` function | --
SIGBUS | SS$_ACCVIO | Access violation | --
SIGBUS | SS$_CMODUSER | Change mode user | --
SIGCHLD | C$_SIGCHLD | Child process stopped | --
SIGEMT | SS$_COMPAT | Compatibility mode trap | --
SIGFP | SS$_DECDIV | Decimal divide trap | FPE_DECDIV_TRAP
SIGFPE | SS$_DECINV | Decimal invalid operand trap | FPE_DECINV_TRAP
SIGFPE | SS$_DECOVF | Decimal overflow trap | FPE_DECOVF_TRAP
SIGFPE | SS$_HPARITH | Floating/decimal division by 0 | FPE_FLTDIV_TRAP
SIGFPE | SS$_HPARITH | Floating overflow trap | FPE_FLTOVF_TRAP
SIGFPE | SS$_HPARITH | Floating undeflow trap | FPE_FLTUND_TRAP
SIGFPE | SS$_HPARITH | Integer overflow | FPE_INTOVF_TRAP
SIGFPE | SS$_HPARITH | Invalid operand | FPE_INVOPR_TRAP
SIGFPE | SS$_HPARITH | Inexact result | FPE_INXRES_TRAP
SIGFPE | SS$_INTDIV | Integer div by zero | FPE_INTDIV_TRAP
SIGFPE | SS$_SUBRNG | Subscript out of range | FPE_SUBRNG_TRAP
SIGFPE | SS$_SUBRNG1 | Subscript1 out of range | FPE_SUBRNG1_TRAP
SIGFPE | SS$_SUBRNG2 | Subscript2 out of range | FPE_SUBRNG2_TRAP
SIGFPE | SS$_SUBRNG3 | Subscript3 out of range | FPE_SUBRNG3_TRAP
SIGFPE | SS$_SUBRNG4 | Subscript4 out of range | FPE_SUBRNG4_TRAP
SIGFPE | SS$_SUBRNG5 | Subscript5 out of range | FPE_SUBRNG5_TRAP
SIGFPE | SS$_SUBRNG6 | Subscript6 out of range | FPE_SUBRNG6_TRAP
SIGFPE | SS$_SUBRNG7 | Subscript7 out of range | FPE_SUBRNG7_TRAP
SIGHUP | SS$_HANGUP | Data set hangup | --
SIGILL | SS$_OPCDEC | Reserved instruction | ILL_PRIVIN_FAULT
SIGILL | SS$_ROPRAND | Reserved operand | ILL_RESOP_FAULT
SIGINT | SS$_CONTROLC | OpenVMS Ctrl/C interrupt | --
SIGIOT | SS$_OPCCUS | Customer-reserved opcode | --
SIGKILL | SS$_ABORT | External signal only | --
SIGQUIT | SS$_CONTROLY | The `raise` function | --
SIGPIPE | SS$_NOMBX | No mailbox | --
SIGSEGV | SS$_ACCVIO | Length violation | --
SIGSEGV | SS$_CMODUSER | Change mode user | --
SIGSYS | SS$_BADPARAM | Bad argument to system call | --
SIGTERM | Not implemented | -- | --
SIGTRAP | SS$_BREAK | Breakpoint fault instruction | --
SIGUSR1 | C$_SIGUSR1 | The `raise` function | --
SIGUSR2 | C$_SIGUSR2 | The `raise` function | --
SIGWINCH 1 | C$_SIGWINCH 2 | The `raise` function | --

1Supported on OpenVMS Version 7.3 and higher.
2SS$_BADWINCNT when C$_SIGWINCH not defined (OpenVMS versions before 7.3).

Previous | Next | Contents | Index

privacy and legal statement