HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


sigmask

Constructs the mask for a given signal number.

Format

#include <signal.h>

int sigmask (signum);


Argument

signum

The signal number for which the mask is to be constructed.

Description

The sigmask function is used to construct the mask for a given signum. This mask can be used with the sigblock function.

Return Value

x The mask constructed for signum

signal

Allows you to specify the way in which the signal sig is to be handled: use the default handling for the signal, ignore the signal, or call the signal handler at the address specified.

Format

#include <signal.h>

void (*signal (int sig, void (*func) (int))) (int);


Arguments

sig

The number or mnemonic associated with a signal. This argument is usually one of the mnemonics defined in the <signal.h> header file.

func

Either the action to take when the signal is raised, or the address of a function needed to handle the signal.

Description

If func is the constant SIG_DFL, the action for the given signal is reset to the default action, which is to terminate the receiving process. If the argument is SIG_IGN, the signal is ignored. Not all signals can be ignored.

If func is neither SIG_DFL nor SIG_IGN, it specifies the address of a signal-handling function. When the signal is raised, the addressed function is called with sig as its argument. When the addressed function returns, the interrupted process continues at the point of interruption. (This is called catching a signal. Signals are reset to SIG_DFL after they are intercepted, except as shown in Chapter 4.)

You must call the signal function each time you want to catch a signal.

See Section 4.2 for more information on signal handling.

To cause an OpenVMS exception or a signal to generate a UNIX style signal, OpenVMS condition handlers must return SS$_RESIGNAL upon receiving any exception that they do not want to handle. Returning SS$_CONTINUE prevents the correct generation of a UNIX style signal. See Chapter 4 for a list of OpenVMS exceptions that correspond to UNIX signals.


Return Values

x The address of the function previously established to handle the signal.
SIG_ERR Indicates that the sig argument is out of range.

sigpause

Assigns mask to the current set of masked signals and then waits for a signal.

Format

#include <signal.h>

int sigpause (int mask);


Argument

mask

The signals to be blocked.

Description

See the sigblock function for information about the mask argument.

When control returns to sigpause , the function restores the previous set of masked signals, sets errno to EINTR, and returns - 1 to indicate an interrupt. The value EINTR is defined in the <errno.h> header file.


Return Value

- 1 Indicates an interrupt. errno is set to EINTR.

sigpending

Examines pending signals.

Format

#include <signal.h>

int sigpending (sigset_t *set);


Argument

set

A pointer to a sigset_t structure.

Description

The sigpending function stores the set of signals that are blocked from delivery and pending to the calling process in the location pointed to by the set argument.

Call either the sigemptyset or the sigfillset function at least once for each object of type sigset_t prior to any other use of that object. If you do not initialize an object in this way and supply an argument to the sigpending function, the result is undefined.

See also sigemptyset and sigfillset in this section.


Return Values

0 Indicates success.
- 1 Indicates an error; errno is set to the following value:
  • SIGSEGV -- Bad mask argument.

sigprocmask

Sets the current signal mask.

Format

#include <signal.h>

int sigprocmask (int how, const sigset_t *set, sigset_t *o_set);


Arguments

how

An integer value that indicates how to change the set of masked signals. Use one of the following values:
SIG_BLOCK The resulting set is the union of the current set and the signal set pointed to by the set argument.
SIG_UNBLOCK The resulting set is the intersection of the current set and the complement of the signal set pointed to by the set argument.
SIG_SETMASK The resulting set is the signal set pointed to by the set argument.

set

The signal set. If the value of the set argument is:

o_set

A non-NULL pointer to the location where the signal mask in effect at the time of the call is stored.

Description

The sigprocmask function is used to examine or change the signal mask of the calling process.

Typically, use the sigprocmask SIG_BLOCK value to block signals during a critical section of code, then use the sigprocmask SIG_SETMASK value to restore the mask to the previous value returned by the sigprocmask SIG_BLOCK value.

If there are any unblocked signals pending after the call to the sigprocmask function, at least one of those signals is delivered before the sigprocmask function returns.

You cannot block SIGKILL or SIGSTOP signals with the sigprocmask function. If a program attempts to block one of these signals, the sigprocmask function gives no indication of the error.


Example

The following example shows how to set the signal mask to block only the SIGINT signal from delivery:


  #include <signal.h> 
 
  int return_value; 
  sigset_t newset; 
   . . . 
  sigemptyset(&newset); 
  sigaddset(&newset, SIGINT); 
  return_value = sigprocmask (SIG_SETMASK, &newset, NULL); 


Return Values

0 Indicates success.
- 1 Indicates an error. The signal mask of the process is unchanged. errno is set to one of the following values:
  • EINVAL -- The value of the how argument is not equal to one of the defined values.
  • EFAULT -- The set or o_set argument points to a location outside the allocated address space of the process.

sigrelse (INTEGRITY SERVERS, ALPHA)

Removes the specified signal from the calling process's signal mask.

Format

#include <signal.h>

int sigrelse (int signal);


Argument

signal

The specified signal. The signal argument can be assigned any of the signals defined in the <signal.h> header file, except SIGKILL and SIGSTOP.

Description

The sighold , sigrelse , and sigignore functions provide simplified signal management:

The sighold function, in conjunction with sigrelse and sigpause , can be used to establish critical regions of code that require the delivery of a signal to be temporarily deferred.

Upon success, the sigrelse function returns a value of 0. Otherwise, a value of - 1 is returned, and errno is set to indicate the error.

Note

These interfaces are provided for compatibility only. New programs should use sigaction and sigprocmask to control the disposition of signals.

Return Values

0 Indicates success.
- 1 Indicates an error; errno is set to the following value:
  • EINVAL -- The value of the signal argument is either an invalid signal number or SIGKILL.

sigsetjmp

Sets a jump point for a nonlocal goto.

Format

#include <setjmp.h>

init sigsetjmp (sigjmp_buf env, int savemask);


Arguments

env

An address for a sigjmp_buf structure.

savemask

An integer value that specifies whether you need to save the current signal mask.

Description

The sigsetjmp function saves its calling environment in its env argument for later use by the siglongjmp function.

If the value of savemask is not 0 (zero), sigsetjmp also saves the process's current signal mask as part of the calling environment.

See also siglongjmp .


Restrictions

You cannot invoke the longjmp function from an OpenVMS condition handler. However, you may invoke longjmp from a signal handler that has been established for any signal supported by the HP C RTL, subject to the following nesting restrictions:

Return Values

0 Indicates success.
nonzero The return is a call to the siglongjmp function.

sigsetmask

Establishes those signals that are blocked from delivery.

Format

#include <signal.h>

int sigsetmask (int mask);


Argument

mask

The signals to be blocked.

Description

See the sigblock function for information about the mask argument.

Return Value

x The previous set of masked signals.

sigsuspend

Atomically changes the set of blocked signals and waits for a signal.

Format

#include <signal.h>

int sigsuspend (const sigset_t *signal_mask);


Argument

signal_mask

A pointer to a set of signals.

Description

The sigsuspend function replaces the signal mask of the process with the set of signals pointed to by the signal_mask argument. Then it suspends execution of the process until delivery of a signal whose action is either to execute a signal catching function or to terminate the process. You cannot block the SIGKILL or SIGSTOP signals with the sigsuspend function. If a program attempts to block either of these signals, sigsuspend gives no indication of the error.

If delivery of a signal causes the process to terminate, sigsuspend does not return. If delivery of a signal causes a signal catching function to execute, sigsuspend returns after the signal catching function returns, with the signal mask restored to the set that existed prior to the call to sigsuspend .

The sigsuspend function sets the signal mask and waits for an unblocked signal as one atomic operation. This means that signals cannot occur between the operations of setting the mask and waiting for a signal. If a program invokes sigprocmask SIG_SETMASK and sigsuspend separately, a signal that occurs between these functions is often not noticed by sigsuspend .

In normal usage, a signal is blocked by using the sigprocmask function at the beginning of a critical section. The process then determines whether there is work for it to do. If there is no work, the process waits for work by calling sigsuspend with the mask previously returned by sigprocmask .

If a signal is intercepted by the calling process and control is returned from the signal handler, the calling process resumes execution after sigsuspend , which always returns a value of - 1 and sets errno to EINTR.

See also sigpause and sigprocmask .


sigtimedwait (INTEGRITY SERVERS, ALPHA)

Suspends a calling thread and waits for queued signals to arrive.

Format

#include <signal.h>

int sigtimedwait (const sigset_t set, siginfo_t *info, const struct timespec *timeout);


Arguments

set

The set of signals to wait for.

info

Pointer to a siginfo structure that is receiving data describing the signal, including any application-defined data specified when the signal was posted.

timeout

A timeout for the wait. If timeout is NULL, the argument is ignored.

Description

The sigtimedwait function behaves the same as the sigwaitinfo function except that if none of the signals specified by set are pending, sigtimedwait waits for the time interval specified in the timespec structure referenced by timeout. If the timespec structure pointed to by timeout is zero-valued and if none of the signals specified by set are pending, then sigtimedwait returns immediately with an error.

See also sigwait and sigwaitinfo .

See Section 4.2 for more information on signal handling.


Return Values

x Upon successful completion, the signal number selected is returned.
- 1 Indicates that an error occurred; errno is set to one of the following values:
  • EINVAL -- The timeout argument specified a tv_nsec value less than 0 or greater than or equal to 1 billion.
  • EINTR -- The wait was interrupted by an unblocked, intercepted signal.
  • EAGAIN -- No signal specified by set was generated within the specified timeout period.

sigvec

Permanently assigns a handler for a specific signal.

Format

#include <signal.h>

int sigvec (int sigint, struct sigvec *sv, struct sigvec *osv);


Arguments

sigint

The signal identifier.

sv

Pointer to a sigvec structure (see the Description section).

osv

If osv is not NULL, the previous handling information for the signal is returned.

Description

If sv is not NULL, it specifies the address of a structure containing a pointer to a handler routine and mask to be used when delivering the specified signal, and a flag indicating whether the signal is to be processed on an alternative stack. If sv-->onstack has a value of 1, the system delivers the signal to the process on a signal stack specified with sigstack .

The sigvec function establishes a handler that remains established until explicitly removed or until the image terminates.

The sigvec structure is defined in the <signal.h> header file:


struct sigvec 
   { 
      int   (*handler)(); 
      int   mask; 
      int   onstack; 
   }; 
 

See Section 4.2 for more information on signal handling.


Return Values

0 Indicates that the call succeeded.
- 1 Indicates that an error occurred.

sigwait (INTEGRITY SERVERS, ALPHA)

Suspends a calling thread and waits for queued signals to arrive.

Format

#include <signal.h>

int sigwait (const sigset_t set, int *sig);


Arguments

set

The set of signals to wait for.

sig

Returns the signal number of the selected signal.

Description

The sigwait function suspends the calling thread until at least one of the signals in the set argument is in the caller's set of pending signals. When this happens, one of those signals is automatically selected and removed from the set of pending signals. The signal number identifying that signal is then returned in the location referenced by sig.

The effect is unspecified if any signals in the set argument are not blocked when the sigwait function is called.

The set argument is created using the set manipulation functions sigemptyset , sigfillset , sigaddset , and sigdelset .

If, while the sigwait function is waiting, a signal occurs that is eligible for delivery (that is, not blocked by the signal mask), that signal is handled asynchronously and the wait is interrupted.

See also sigtimedwait and sigwaitinfo .

See Section 4.2 for more information on signal handling.


Return Values

0 Upon successful completion, sigwait stores the signal number of the received signal at the location referenced by sig and returns 0.
nonzero Indicates that an error occurred; errno is set to the following value:
  • EINVAL -- The set argument contains an invalid or unsupported signal number.


Previous Next Contents Index