nanosleep.3p (4649B)
- '\" et
- .TH NANOSLEEP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- nanosleep
- \(em high resolution sleep
- .SH SYNOPSIS
- .LP
- .nf
- #include <time.h>
- .P
- int nanosleep(const struct timespec *\fIrqtp\fP, struct timespec *\fIrmtp\fP);
- .fi
- .SH DESCRIPTION
- The
- \fInanosleep\fR()
- function shall cause the current thread to be suspended from execution
- until either the time interval specified by the
- .IR rqtp
- argument has elapsed or a signal is delivered to the calling thread,
- and its action is to invoke a signal-catching function or to terminate
- the process. The suspension time may be longer than requested because
- the argument value 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 the time specified by
- .IR rqtp ,
- as measured by the system clock CLOCK_REALTIME.
- .P
- The use of the
- \fInanosleep\fR()
- function has no effect on the action or blockage of any signal.
- .SH "RETURN VALUE"
- If the
- \fInanosleep\fR()
- function returns because the requested time has elapsed, its return
- value shall be zero.
- .P
- If the
- \fInanosleep\fR()
- function returns because it has been interrupted by a signal, it
- shall return a value of \-1 and set
- .IR errno
- to indicate the interruption. If the
- .IR rmtp
- argument is non-NULL, the
- .BR timespec
- structure referenced by it is updated to contain the amount of time
- remaining in the interval (the requested time minus the time actually
- slept). The
- .IR rqtp
- and
- .IR rmtp
- arguments can point to the same object. If the
- .IR rmtp
- argument is NULL, the remaining time is not returned.
- .P
- If
- \fInanosleep\fR()
- fails, it shall return a value of \-1 and set
- .IR errno
- to indicate the error.
- .SH ERRORS
- The
- \fInanosleep\fR()
- function shall fail if:
- .TP
- .BR EINTR
- The
- \fInanosleep\fR()
- function was interrupted by a signal.
- .TP
- .BR EINVAL
- The
- .IR rqtp
- argument specified a nanosecond value less than zero or greater than or
- equal to 1\|000 million.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- It is common to suspend execution of a thread for an interval in order
- to poll the status of a non-interrupting function. A large number of
- actual needs can be met with a simple extension to
- \fIsleep\fR()
- that provides finer resolution.
- .P
- In the POSIX.1\(hy1990 standard and SVR4, it is possible to implement such a routine,
- but the frequency of wakeup is limited by the resolution of the
- \fIalarm\fR()
- and
- \fIsleep\fR()
- functions. In 4.3 BSD, it is possible to write such a routine using
- no static storage and reserving no system facilities. Although it is
- possible to write a function with similar functionality to
- \fIsleep\fR()
- using the remainder of the
- .IR timer_* (\|)
- functions, such a function requires the use of signals and the
- reservation of some signal number. This volume of POSIX.1\(hy2017 requires that
- \fInanosleep\fR()
- be non-intrusive of the signals function.
- .P
- The
- \fInanosleep\fR()
- function shall return a value of 0 on success and \-1 on failure or if
- interrupted. This latter case is different from
- \fIsleep\fR().
- This was done because the remaining time is returned via an argument
- structure pointer,
- .IR rmtp ,
- instead of as the return value.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIclock_nanosleep\fR\^(\|)",
- .IR "\fIsleep\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<time.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .