freebsd-nq/lib/libc/sys/nanosleep.2

.\"	$OpenBSD: nanosleep.2,v 1.1 1997/04/20 20:56:20 tholo Exp $
.\"	$NetBSD: nanosleep.2,v 1.1 1997/04/17 18:12:02 jtc Exp $
.\"
.\" Copyright (c) 1986, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)sleep.3	8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd April 17, 1997
.Dt NANOSLEEP 2
.Os
.Sh NAME
.Nm nanosleep
.Nd suspend process execution for an interval measured in nanoseconds
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In time.h
.Ft int
.Fn nanosleep "const struct timespec *rqtp" "struct timespec *rmtp"
.Sh DESCRIPTION
The
.Fn nanosleep
system call
causes the calling thread to sleep until the time interval specified by
.Fa rqtp
has elapsed.
An unmasked signal will
cause it to terminate the sleep early, regardless of the
.Dv SA_RESTART
value on the interrupting signal.
.Sh RETURN VALUES
If the
.Fn nanosleep
system call returns because the requested time has elapsed, the value
returned will be zero.
.Pp
If the
.Fn nanosleep
system call returns due to the delivery of a signal, the value returned
will be -1, and the global variable
.Va errno
will be set to indicate the interruption.
If
.Fa rmtp
is
.No non- Ns Dv NULL ,
the timespec structure it references is updated to contain the
unslept amount (the request time minus the time actually slept).
.Sh ERRORS
The
.Fn nanosleep
system call fails if:
.Bl -tag -width Er
.It Bq Er EFAULT
Either
.Fa rqtp
or
.Fa rmtp
points to memory that is not a valid part of the process
address space.
.It Bq Er EINTR
The
.Fn nanosleep
system call
was interrupted by the delivery of a signal.
.It Bq Er EINVAL
The
.Fa rqtp
argument
specified a nanosecond value less than zero
or greater than or equal to 1000 million.
.It Bq Er ENOSYS
The
.Fn nanosleep
system call
is not supported by this implementation.
.El
.Sh SEE ALSO
.Xr sigsuspend 2 ,
.Xr sleep 3
.Sh STANDARDS
The
.Fn nanosleep
system call conforms to
.St -p1003.1b-93 .
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.\" $OpenBSD: nanosleep.2,v 1.1 1997/04/20 20:56:20 tholo Exp $`
			`.\" $NetBSD: nanosleep.2,v 1.1 1997/04/17 18:12:02 jtc Exp $`
			`.\"`
			`.\" Copyright (c) 1986, 1991, 1993`
			`.\" The Regents of the University of California. All rights reserved.`
			`.\"`
			`.\" Redistribution and use in source and binary forms, with or without`
			`.\" modification, are permitted provided that the following conditions`
			`.\" are met:`
			`.\" 1. Redistributions of source code must retain the above copyright`
			`.\" notice, this list of conditions and the following disclaimer.`
			`.\" 2. Redistributions in binary form must reproduce the above copyright`
			`.\" notice, this list of conditions and the following disclaimer in the`
			`.\" documentation and/or other materials provided with the distribution.`
			`.\" 4. Neither the name of the University nor the names of its contributors`
			`.\" may be used to endorse or promote products derived from this software`
			`.\" without specific prior written permission.`
			`.\"`
			.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
			`.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE`
			`.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE`
			`.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE`
			`.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL`
			`.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS`
			`.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)`
			`.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT`
			`.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY`
			`.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF`
			`.\" SUCH DAMAGE.`
			`.\"`
			`.\" @(#)sleep.3 8.1 (Berkeley) 6/4/93`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`.\" $FreeBSD$`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.\"`
			`.Dd April 17, 1997`
			`.Dt NANOSLEEP 2`
mdoc(7) police: removed HISTORY info from the .Os call. 2001-07-10 13:41:46 +00:00			`.Os`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Sh NAME`
Nuke signanosleep() 1998-05-14 11:36:16 +00:00			`.Nm nanosleep`
Name Description (.Nd macro) added. Style and punctuation errors fixes. ERRORS section included to RETURN VALUES because it's describing return values instead of errors and their handling. Reviewed by: mpp 1999-09-05 06:59:34 +00:00			`.Nd suspend process execution for an interval measured in nanoseconds`
Introduce ".Lb" macro to libc manpages. More libraries manpages updates following. 2000-04-21 09:42:15 +00:00			`.Sh LIBRARY`
			`.Lb libc`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Sh SYNOPSIS`
mdoc(7) police: Use the new .In macro for #include statements. 2001-10-01 16:09:29 +00:00			`.In time.h`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Ft int`
			`.Fn nanosleep "const struct timespec rqtp" "struct timespec rmtp"`
Doc signanosleep, add to links 1997-06-01 09:47:06 +00:00			`.Sh DESCRIPTION`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`The`
			`.Fn nanosleep`
			`system call`
In nanosleep(2), note that the calling thread is put to sleep, not the whole process. Also explicitely name the parameter that specifies sleep interval. 2009-10-11 16:23:11 +00:00			`causes the calling thread to sleep until the time interval specified by`
			`.Fa rqtp`
			`has elapsed.`
Mechanically kill hard sentence breaks. 2004-07-02 23:52:20 +00:00			`An unmasked signal will`
Doc signanosleep, add to links 1997-06-01 09:47:06 +00:00			`cause it to terminate the sleep early, regardless of the`
			`.Dv SA_RESTART`
			`value on the interrupting signal.`
Name Description (.Nd macro) added. Style and punctuation errors fixes. ERRORS section included to RETURN VALUES because it's describing return values instead of errors and their handling. Reviewed by: mpp 1999-09-05 06:59:34 +00:00			`.Sh RETURN VALUES`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`If the`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Fn nanosleep`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call returns because the requested time has elapsed, the value`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`returned will be zero.`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Pp`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`If the`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Fn nanosleep`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call returns due to the delivery of a signal, the value returned`
Grammatical fixup: s/be the -1/be -1/ MFC after: 1 day 2002-12-19 21:48:43 +00:00			`will be -1, and the global variable`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Va errno`
			`will be set to indicate the interruption.`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`If`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Fa rmtp`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`is`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`.No non- Ns Dv NULL ,`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`the timespec structure it references is updated to contain the`
			`unslept amount (the request time minus the time actually slept).`
Isolate the ERRORS section from the RETURN VALUES one. Reviewed by: ru 2001-08-14 14:10:01 +00:00			`.Sh ERRORS`
			`The`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`.Fn nanosleep`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call fails if:`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Bl -tag -width Er`
			`.It Bq Er EFAULT`
			`Either`
			`.Fa rqtp`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`or`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Fa rmtp`
			`points to memory that is not a valid part of the process`
			`address space.`
			`.It Bq Er EINTR`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`The`
Name Description (.Nd macro) added. Style and punctuation errors fixes. ERRORS section included to RETURN VALUES because it's describing return values instead of errors and their handling. Reviewed by: mpp 1999-09-05 06:59:34 +00:00			`.Fn nanosleep`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`was interrupted by the delivery of a signal.`
			`.It Bq Er EINVAL`
mdoc(7) police: "The .Fa argument.". 2002-12-19 09:40:28 +00:00			`The`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Fa rqtp`
mdoc(7) police: "The .Fa argument.". 2002-12-19 09:40:28 +00:00			`argument`
Fixed off by 1 error. 1997-08-21 19:44:41 +00:00			`specified a nanosecond value less than zero`
			`or greater than or equal to 1000 million.`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.It Bq Er ENOSYS`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`The`
Name Description (.Nd macro) added. Style and punctuation errors fixes. ERRORS section included to RETURN VALUES because it's describing return values instead of errors and their handling. Reviewed by: mpp 1999-09-05 06:59:34 +00:00			`.Fn nanosleep`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`is not supported by this implementation.`
			`.El`
			`.Sh SEE ALSO`
Sort cross refereces in section SEE ALSO. 1997-09-29 19:11:55 +00:00			`.Xr sigsuspend 2 ,`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.Xr sleep 3`
			`.Sh STANDARDS`
			`The`
			`.Fn nanosleep`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call conforms to`
manpage for nanosleep(2) Obtained from: NetBSD (I think jtc@netbsd.org wrote it) 1997-05-12 12:15:35 +00:00			`.St -p1003.1b-93 .`