NAME

thrd_sleep — suspend execution for an interval

SYNOPSIS

#include <threads.h>

int thrd_sleep(const struct timespec *duration,
       struct timespec *remaining);


DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.

The thrd_sleep() function shall suspend execution of the calling thread until either the interval specified by duration has elapsed or a signal is delivered to the calling thread whose action is to invoke a signal-catching function or to terminate the process. If interrupted by a signal and the remaining argument is not null, the amount of time remaining (the requested interval minus the time actually slept) shall be stored in the interval it points to. The duration and remaining arguments can point to the same object.

The suspension time may be longer than requested because the interval is rounded up to an integer multiple of the sleep resolution or because of the scheduling of other activity by the system. But, except for the case of being interrupted by a signal, the suspension time shall not be less than that specified, as measured by the system clock TIME_UTC.

RETURN VALUE

The thrd_sleep() function shall return zero if the requested time has elapsed, -1 if it has been interrupted by a signal, or a negative value (which may also be -1) if it fails for any other reason. ^[CX] If it returns a negative value, it shall set errno to indicate the error.

ERRORS

^[CX] The thrd_sleep() function shall fail if:

[EINTR]

The thrd_sleep() function was interrupted by a signal.

[EINVAL]

The duration argument specified a nanosecond value less than zero or greater than or equal to 1000 million.

EXAMPLES

None.

APPLICATION USAGE

Since the return value may be -1 for errors other than [EINTR], applications should examine errno to distinguish [EINTR] from other errors (and thus determine whether the unslept time is available in the interval pointed to by remaining).

RATIONALE

The thrd_sleep() function is identical to the nanosleep() function except that the return value may be any negative value when it fails with an error other than [EINTR].

FUTURE DIRECTIONS

None.

SEE ALSO

nanosleep

XBD <threads.h>, <time.h>

CHANGE HISTORY

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.