Technical Reference: Base Operating System and Extensions , Volume 2

sleep, nsleep or usleep Subroutine

Purpose

Suspends a current process from execution.

Syntax

#include <unistd.h> unsigned int sleep ( Seconds)

#include <sys/time.h> int nsleep ( Rqtp, Rmtp) struct timestruc_t *Rqtp, *Rmtp;

int usleep ( Useconds) useconds_t Useconds;

Description

The nsleep subroutine is an extended form of the sleep subroutine. The sleep or nsleep subroutines suspend the current process until:

The time interval specified by the Rqtp parameter elapses.
A signal is delivered to the calling process that invokes a signal-catching function or terminates the process.
The process is notified of an event through an event notification function.

The suspension time may be longer than requested due to the scheduling of other activity by the system. Upon return, the location specified by the Rmtp parameter shall be updated to contain the amount of time remaining in the interval, or 0 if the full interval has elapsed.

Parameters

Rqtp	Time interval specified for suspension of execution.
Rmtp	Specifies the time remaining on the interval timer or 0.
Seconds	Specifies time interval in seconds.
Useconds	Specifies time interval in microseconds.

Compatibility Interfaces

The sleep and usleep subroutines are provided to ensure compatibility with older versions of the operating system, AT&T System V and BSD systems. They are implemented simply as front-ends to the nsleep subroutine. Programs linking with the libbsd.a library get a BSD compatible version of the sleep subroutine. The return value from the BSD compatible sleep subroutine has no significance and should be ignored.

Return Values

The nsleep, sleep, and usleep subroutines return a value of 0 if the requested time has 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 actually 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 will be the unslept amount (the requested time minus the time actually 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:

EINTR	A signal was caught by the calling process and control has been returned from the signal-catching routine, or the process has been 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 one second.

The sleep subroutine is always successful and no return value is reserved to indicate an error.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The alarm subroutine, pause subroutine, sigaction (sigaction, sigvec, or signal Subroutine) subroutine.

List of Time Data Manipulation Services in AIX 5L Version 5.1 System Management Concepts: Operating System and Devices.

Subroutines Overview in AIX 5L Version 5.1 System Management Guide: Operating System and Devices.