diff options
Diffstat (limited to 'man3p/nanosleep.3p')
| -rw-r--r-- | man3p/nanosleep.3p | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/man3p/nanosleep.3p b/man3p/nanosleep.3p new file mode 100644 index 000000000..d2fb63aae --- /dev/null +++ b/man3p/nanosleep.3p @@ -0,0 +1,108 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NANOSLEEP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nanosleep +.SH NAME +nanosleep \- high resolution sleep (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include <time.h> +.br +.sp +int nanosleep(const struct timespec *\fP\fIrqtp\fP\fB, struct timespec +*\fP\fIrmtp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fInanosleep\fP() function shall cause the current thread to be +suspended from execution until either the time interval +specified by the \fIrqtp\fP 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 \fIrqtp\fP, +as measured by the system clock CLOCK_REALTIME. +.LP +The use of the \fInanosleep\fP() function has no effect on the action +or blockage of any signal. +.SH RETURN VALUE +.LP +If the \fInanosleep\fP() function returns because the requested time +has elapsed, its return value shall be zero. +.LP +If the \fInanosleep\fP() function returns because it has been interrupted +by a signal, it shall return a value of -1 and set +\fIerrno\fP to indicate the interruption. If the \fIrmtp\fP argument +is non-NULL, the \fBtimespec\fP structure referenced by it +is updated to contain the amount of time remaining in the interval +(the requested time minus the time actually slept). If the +\fIrmtp\fP argument is NULL, the remaining time is not returned. +.LP +If \fInanosleep\fP() fails, it shall return a value of -1 and set +\fIerrno\fP to indicate the error. +.SH ERRORS +.LP +The \fInanosleep\fP() function shall fail if: +.TP 7 +.B EINTR +The \fInanosleep\fP() function was interrupted by a signal. +.TP 7 +.B EINVAL +The \fIrqtp\fP argument specified a nanosecond value less than zero +or greater than or equal to 1000 million. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +It is common to suspend execution of a process 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\fP() that +provides finer resolution. +.LP +In the POSIX.1-1990 standard and SVR4, it is possible to implement +such a routine, but the frequency of wakeup is limited by the +resolution of the \fIalarm\fP() and \fIsleep\fP() +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\fP() +using the +remainder of the \fItimer_*\fP() functions, such a function requires +the use of signals +and the reservation of some signal number. This volume of IEEE\ Std\ 1003.1-2001 +requires that \fInanosleep\fP() be +non-intrusive of the signals function. +.LP +The \fInanosleep\fP() function shall return a value of 0 on success +and -1 on failure or if interrupted. This latter case is +different from \fIsleep\fP(). This was done because the remaining +time is returned via an +argument structure pointer, \fIrmtp\fP, instead of as the return value. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIsleep\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI<time.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |