sigtimedwait()--Synchronously Accept a Signal for Interval of Time
Syntax
#include <signal.h> int sigtimedwait( const sigset_t *set, siginfo_t *info, const struct timespec *timeout );
Service Program Name: QPOSSRV1
Default Public Authority: *USE
Threadsafe: Yes
The sigtimedwait() function selects a pending signal from set, clears it from the set of pending signals for the thread or process, and returns that signal number in the si_signo member in the structure that is referenced by info. If prior to the call to sigtimedwait() there are multiple pending instances of a single signal number, upon successful return the number of remaining signals for that signal number is decremented by one.
If no signal in set is pending at the time of the call, the thread shall be suspended for the time interval in the timespec structure referenced by timeout. The thread does not resume until either one or more signals in set become pending or the time interval has elapsed. If the timespec structure referenced by timeout has a value of zero and none of the signals specified by set are pending, then sigtimedwait() is not successful and an [EAGAIN] error is returned.
The signals defined by set are required to be blocked at the time of the call to sigtimedwait(); otherwise, sigtimedwait() is not successful, and an [EINVAL] error is returned. The signal SIGKILL or SIGStop cannot be selected. Any attempt to use sigprocmask() to select these signals is simply ignored, and no error is returned.
The signal action for the signal in set that is returned in the member si_signo in the structure referenced by info is not taken.
If more than one thread is using a sigwait function to wait for the same signal, only one of these threads will return from the sigwait function with the signal number. If more than one thread is waiting for the same signal, the first thread to wait on the signal will return from the sigwait function.
Authorities and Locks
None.
Parameters
- *set
- (Input) A pointer to a signal set to be waited upon.
- *info
- (Output) A pointer to the storage location where
sigtimedwait() can store the signal related information for the signal
number that completed the wait. This value may be NULL. The siginfo_t
structure is described in sigaction()--Examine and Change
Signal Action.
- *timeout
- (Input) A pointer to the storage location specifying the time interval sigtimedwait() should wait. This value may be NULL. If timeout is NULL, the thread will be suspended until one or more signals in set become pending.
Return Value
0 | sigtimedwait() was successful. |
-1 | sigtimedwait() was not successful. The errno variable is set to indicate the reason. |
Error Conditions
If sigtimedwait() is not successful, errno usually indicates the following error. Under some conditions, errno could indicate an error other than that listed here.
- [EINVAL]
-
The value specified for the argument is not correct.
A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.
An argument value is not valid, out of range, or NULL.
One of the following has occurred:
- The signal set pointed to by set contains a signal that is not
within the valid range or a signal that is not supported.
- A signal in the signal set pointed to by set contains a signal
that is not blocked.
- The tv_nsec member in the timespec structure pointed to by timeout is greater than or equal to 1,000,000,000.
- The signal set pointed to by set contains a signal that is not
within the valid range or a signal that is not supported.
- [EAGAIN]
-
Operation would have caused the process to be suspended.
- [ENOTSIGINIT]
-
Process not enabled for signals.
An attempt was made to call a signal function under one of the following conditions:
- The signal function is being called for a process that is not enabled for
asynchronous signals.
- The signal function is being called when the system signal controls have not been initialized.
- The signal function is being called for a process that is not enabled for
asynchronous signals.
Usage Notes
The sigtimedwait() function enables a process for signals if the process is not already enabled for signals. For details, see Qp0sEnableSignals()--Enable Process for Signals. If the system has not been enabled for signals, sigtimedwait() is not successful, and an [ENOTSIGINIT] error is returned.
Related Information
- The <signal.h> file (see Header
Files for UNIX®-Type Functions)
- Qp0sDisableSignals()--Disable Process for
Signals
- Qp0sEnableSignals()--Enable Process for
Signals
- sigaction()--Examine and Change Signal Action
- sigpending()--Examine Pending Signals
- sigprocmask()--Examine and Change Blocked
Signals
- sigsuspend()--Wait for Signal
- sigwait()--Synchronously Accept a Signal
- sigwaitinfo()--Synchronously Accept a Signal and Signal Data
Example
The following example suspends processing by using the sigtimedwait() function and determines the current time.
The signal catching function is not called.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <signal.h> #include <stdio.h> #include <time.h> void catcher( int sig ) { printf( "Signal catcher called for signal %d\n", sig ); } void timestamp( char *str ) { time_t t; time( T ); printf( "The time %s is %s\n", str, ctime(T) ); } int main( int argc, char *argv[] ) { int result = 0; struct sigaction sigact; struct sigset_t waitset; siginfo_t info; struct timespec timeout; sigemptyset( &sigact.sa_mask ); sigact.sa_flags = 0; sigact.sa_handler = catcher; sigaction( SIGALRM, &sigact, NULL ); sigemptyset( &waitset ); sigaddset( &waitset, SIGALRM ); sigprocmask( SIG_BLOCK, &waitset, NULL ); timeout.tv_sec = 10; /* Number of seconds to wait */ timeout.tv_nsec = 1000; /* Number of nanoseconds to wait */ alarm( 10 ); timestamp( "before sigtimedwait()" ); result = sigtimedwait( &waitset, &info, &timeout ); printf("sigtimedwait() returned for signal %d\n", info.si_signo ); timestamp( "after sigtimedwait()" ); return( result ); }
Output:
The time before sigtimedwait() is Mon Feb 17 11:09:08 1997 sigtimedwait() returned for signal 14 The time after sigtimedwait() is Mon Feb 17 11:09:18 1997
API introduced: V4R2