sleep, nsleep or usleep Subroutine
Purpose
Suspends a current process from execution.
Library
Standard C Library (libc.a)
Syntax
unsigned int sleep ( Seconds)
useconds_t Useconds;
Description
The sleep, usleep, or nsleep subroutines suspend the current process until:
- The time interval specified by the Seconds, Useconds, or Rqtp parameter elapses.
- A signal is delivered to the calling process that starts a signal-catching function or end the process.
- The process is notified of an event through an event notification function.
The suspension time might be longer than requested time due to the scheduling of other activity by the system. Upon return, the location that is specified by the Rmtp parameter is updated to show the time that is left in the interval, or 0 if the full interval is elapsed.
Parameters
| Item | Description |
|---|---|
| Rqtp | Time interval specified for suspension of execution. |
| Rmtp | Specifies the time is left on the interval timer or 0. |
| Seconds | Specifies time interval in seconds. |
| Useconds | Specifies time interval in microseconds. This parameter is available only for the usleep subroutine. |
Compatibility Interfaces
The sleep and usleep subroutines are simplified forms for the nsleep subroutine. These subroutines ensure compatibility with older versions of the Portable Operating System Interface (POSIX) and Linux® specifications. The sleep subroutine suspends the current process for whole seconds. The usleep subroutine suspends the current process in microseconds, and the nsleep subroutine suspends the current process in nanoseconds.
In AIX® Version 5.1, or later, time is measured in nanoseconds. The nsleep subroutine is the system call that is used by the AIX operating system to suspend thread execution. The sleep and usleep subroutines serve as front end to the nsleep subroutine.
The actual time interval for which the process is suspended is approximate. The time interval to suspend a process might take long time because of the other activities that are scheduled by the system, or the process suspension might take less time because of a signal that preempts the suspension.
For the nsleep subroutine, your must specify the Rqtp (Requested Time Pause) and Rmtp (Remaining Time Pause) parameters so that the actual time for which the process is suspended can be identified. Normally, the value in Rmtp parameter is the equivalent of zero. By design, the maximum value that might be used in the Rqtp parameter is the number of nanoseconds in one second.
Example
sleep (10)Return Values
The nsleep, sleep, and usleep subroutines return a value of 0 if the requested time is elapsed.
If the nsleep subroutine returns a value of -1, the notification of a signal or event was received and the Rmtp parameter is updated to the requested time minus the time slept (unslept time), and the errno global variable is set.
If the sleep subroutine returns because of a premature arousal due to delivery of a signal, the return value is the unslept amount (the requested time minus the time slept) in seconds.
Error Codes
If the nsleep subroutine fails, a value of -1 is returned and the errno global variable is set to one of the following error codes:
| Item | Description |
|---|---|
| EINTR | A signal was detected by the calling process and control is returned from the signal-catching routine, or the process is notified of an event through an event notification function. |
| EINVAL | The Rqtp parameter specified a nanosecond value less than zero or greater than or equal to 1 second. |
| EFAULT | An argument address referenced informed memory. Note: An errno can be set to
EFAULT as well.
|
The sleep subroutine is always successful and no return value is reserved to indicate an error.