sleep()--Suspend Processing for Interval of Time

 #include <unistd.h>

 unsigned int sleep( unsigned int seconds );   

The sleep() function suspends a thread for a specified number of seconds. (Because of processor delays, the thread can sleep slightly longer than this specified time.) If an unblocked signal is received during this time and its action is to call a signal-catching function, to end the request, or to end the process, sleep() returns immediately with the amount of sleep time remaining.

If a SIGALRM signal is generated for the calling process while sleep() is running and if the SIGALRM signal is being ignored or blocked from delivery, sleep() does not return when the SIGALRM signal is scheduled. If the SIGALRM signal is blocked from delivery, the SIGALRM remains pending after sleep() returns.

If a SIGALRM signal is generated for the calling process while sleep() is running (except as a result of a previous call to alarm()) and if the SIGALRM is not being ignored or blocked from delivery, the SIGALRM signal has no effect on sleep() other than causing it to return.

A signal-catching function that interrupts sleep() can examine and change the time a SIGALRM is scheduled to be generated, the action associated with the SIGALRM signal, and whether SIGALRM is blocked from delivery.

If a signal-catching function interrupts sleep() and calls siglongjmp() or longjmp() to restore an environment saved prior to sleep(), the sleep() function is canceled. The action associated with the SIGALRM signal and the time at which a SIGALRM signal is scheduled to be generated are unchanged. The SIGALRM blocking action remains unchanged, unless the thread's signal mask is restored as part of the environment.

Authorities and Locks

None.

Parameters

seconds

(Input) The number of real seconds for which the process is to be suspended.

Return Value

Error Conditions

If sleep() is not successful, errno usually indicates the following error. Under some conditions, errno could indicate an error other than that listed here.

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

[ETIMEDOUT]

A remote host did not respond within the timeout period.

[EWOULDBLOCK]

Operation would have caused the process to be suspended.

The current thread state would prevent the signal function from completing.

Usage Notes

The sleep() 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, sleep() is not successful, and an [ENOTSIGINIT] error is returned.

Related Information

• The <unistd.h> file (see Header Files for UNIX-Type Functions)
  
  
• alarm()--Set Schedule for Alarm Signal
  
  
• pause()--Suspend Process Until Signal Received
  
  
• Qp0sDisableSignals()--Disable Process for Signals
  
  
• Qp0sEnableSignals()--Enable Process for Signals
  
  
• sigaction()--Examine and Change Signal Action
  
  
• siglongjmp()--Perform Nonlocal Goto with Signal Handling
  
  
• sigsetjmp()--Set Jump Point for Nonlocal Goto
  
  
• sigsuspend()--Wait for Signal
  
  
• sigtimedwait()--Synchronously Accept a Signal for Interval of Time
  
  
• sigwait()--Synchronously Accept a Signal
  
  
• sigwaitinfo()--Synchronously Accept a Signal and Signal Data
  
  
• usleep()--Suspend Processing for Interval of Time

Example

See Code disclaimer information for information pertaining to code examples.

The following example uses the sleep() function to suspend processing for a specified time:

#include <unistd.h>
#include <stdio.h>
#include <time.h>

void timestamp( char *str ) {

    time_t t;

    time( &t );
    printf( "%s the time is %s\n", str, ctime(&t) );
}

int main( int argc, char *argv[] ) {

    unsigned int ret;

    timestamp( "before sleep()" );
    ret = sleep( 10 );
    timestamp( "after sleep()" );

    printf( "sleep() returned %d\n", ret );

    return( 0 );
}

Output:

    before sleep() the time is Sun Jan 22 17:25:17 1995
    after sleep() the time is Sun Jan 22 17:25:28 1995
    sleep() returned 0