diff options
author | davidxu <davidxu@FreeBSD.org> | 2005-11-11 07:48:38 +0000 |
---|---|---|
committer | davidxu <davidxu@FreeBSD.org> | 2005-11-11 07:48:38 +0000 |
commit | c96b2417aa9b2485314d3fcf3909169c16c50bfb (patch) | |
tree | 74560fc5cb6c13d40ea30866073d6225f4feb053 /lib | |
parent | ed1132ceab2c722cdbb8d3cf5a717b07ee5ff2c0 (diff) | |
download | FreeBSD-src-c96b2417aa9b2485314d3fcf3909169c16c50bfb.zip FreeBSD-src-c96b2417aa9b2485314d3fcf3909169c16c50bfb.tar.gz |
Add POSIX timer manuals.
Diffstat (limited to 'lib')
-rw-r--r-- | lib/libc/sys/Makefile.inc | 2 | ||||
-rw-r--r-- | lib/libc/sys/timer_create.2 | 110 | ||||
-rw-r--r-- | lib/libc/sys/timer_delete.2 | 70 | ||||
-rw-r--r-- | lib/libc/sys/timer_settime.2 | 186 |
4 files changed, 368 insertions, 0 deletions
diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index 93aa9aa..ca719ae 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -81,6 +81,7 @@ MAN+= _exit.2 accept.2 access.2 acct.2 adjtime.2 \ sigreturn.2 sigstack.2 sigsuspend.2 sigwait.2 sigwaitinfo.2 \ socket.2 socketpair.2 stat.2 statfs.2 \ swapon.2 symlink.2 sync.2 sysarch.2 syscall.2 \ + timer_create.2 timer_delete.2 timer_settime.2 \ truncate.2 umask.2 undelete.2 \ unlink.2 utimes.2 utrace.2 uuidgen.2 vfork.2 wait.2 write.2 .if !defined(NO_P1003_1B) @@ -139,6 +140,7 @@ MLINKS+=stat.2 fstat.2 stat.2 lstat.2 MLINKS+=statfs.2 fstatfs.2 MLINKS+=syscall.2 __syscall.2 MLINKS+=swapon.2 swapoff.2 +MLINKS+=timer_settime.2 timer_gettime.2 timer_settime.2 timer_getoverrun.2 MLINKS+=truncate.2 ftruncate.2 MLINKS+=utimes.2 futimes.2 utimes.2 lutimes.2 MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2 diff --git a/lib/libc/sys/timer_create.2 b/lib/libc/sys/timer_create.2 new file mode 100644 index 0000000..406800c --- /dev/null +++ b/lib/libc/sys/timer_create.2 @@ -0,0 +1,110 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" $FreeBSD$ +.\" +.Dd Sep 11, 2000 +.Dt TIMER_CREATE 2 +.Os +.Sh NAME +.Nm timer_create +.Nd create a per-process timer (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_create "clockid_t clockid" "struct sigevent *restrict evp" "timer_t *restrict timerid" +.Sh DESCRIPTION +The +.Fn timer_create +function creates a per-process timer using the specified clock, +.Fa clock_id , +as the timing base. The +.Fn timer_create +function returns, in the location referenced by +.Fa timerid , +a timer ID of type timer_t used to identify the timer in timer requests. +This timer ID is unique within the calling process until the timer is deleted. +The particular clock, +.Fa clock_id , +is defined in +.In time.h . +The timer whose ID is returned is in a disarmed state upon return from +.Fn timer_create . +.Pp +The +.Fa evp +argument, if non-NULL, points to a sigevent structure. This structure, +allocated by the application, defines the asynchronous notification to occur +when the timer expires. If the +.Fa evp +argument is NULL, the effect is as if the evp argument pointed to a sigevent +structure with the sigev_notify member having the value SIGEV_SIGNAL, the +sigev_signo having a default signal number, and the sigev_value member having +the value of the timer ID. +.Pp +The implementations supports a clock_id of CLOCK_REALTIME or CLOCK_MONOTONIC. +.Pp +If evp->sigev_sigev_notify is SIGEV_THREAD and sev->sigev_notify_attributes +is not NULL, if the attribute pointed to by sev->sigev_notify_attributes has +a thread stack address specified by a call to +.Fn pthread_attr_setstack +or +.Fn pthread_attr_setstackaddr , +the results are unspecified if the signal is generated more than once. +.Sh RETURN VALUES +If the call succeeds, +.Fn timer_create +returns zero and update the location referenced by +.Fa timerid +to a timer_t, which can be passed to the per-process timer calls. If an error +occurs, the function shall return a value of -1 and set errno to indicate the +error. The value of timerid is undefined if an error occurs. +.Sh ERRORS +The +.Fn timer_create +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The calling process has already created all of the timers it is allowed by +this implementation +.It Bq Er EINVAL +The specified clock ID is not supported. +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.El +.Sh SEE ALSO +.Xr clock_getres 2 , +.Xr timer_delete 2 , +.Xr timer_getoverun 2 +.Sh STANDARDS +The +.Fn timer_create +function conforms to +.St -p1003.1-96 . diff --git a/lib/libc/sys/timer_delete.2 b/lib/libc/sys/timer_delete.2 new file mode 100644 index 0000000..3c98e8e --- /dev/null +++ b/lib/libc/sys/timer_delete.2 @@ -0,0 +1,70 @@ +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" $FreeBSD$ +.\" +.Dd Sep 11, 2000 +.Dt TIMER_DELETE 2 +.Os +.Sh NAME +.Nm timer_delete +.Nd delete a per-process timer (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_delete "timer_t timerid" +.Sh DESCRIPTION +The +.Fn timer_delete +deletes the specified timer, +.Fa timerid , +previously created by the +.Fn timer_create +function. If the timer is armed when +.Fn timer_delete +is called, the behavior is as if the timer is automatically disarmed before +removal. Pending signals for the deleted timer is cleared. +.Sh RETURN VALUES +If successful, the +.Fn timer_delete +function shall return a value of zero. Otherwise, the function shall return +a value of -1 and set errno to indicate the error. +.Sh ERRORS +The +.Fn timer_delete +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The timer ID specified by timerid is not a valid timer ID. +.El +.Sh SEE ALSO +.Xr timer_create 2 +.Sh STANDARDS +The +.Fn timer_delete +function conforms to +.St -p1003.1-96 . diff --git a/lib/libc/sys/timer_settime.2 b/lib/libc/sys/timer_settime.2 new file mode 100644 index 0000000..506b69a --- /dev/null +++ b/lib/libc/sys/timer_settime.2 @@ -0,0 +1,186 @@ +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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. +.\" +.\" $FreeBSD$ +.\" +.Dd Sep 11, 2000 +.Dt TIMER_SETTIME 2 +.Os +.Sh NAME +.Nm timer_getoverrun +.Nm timer_gettime +.Nm timer_settime +.Nd per-process timers (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_getoverrun "timer_t timerid" +.Ft int +.Fn timer_gettime "timer_t timerid" "struct itimerspec *value" +.Ft int +.Fn timer_settime "timer_t timerid" "int flags" "const struct itimerspec *restrict value" "struct itimerspec *restrict ovalue" +.Sh DESCRIPTION +The +.Fn timer_gettime +function stores the amount of time until the specified timer, +.Fa timerid , +expires and the reload value of the timer into the space pointed to by the +.Fa value +argument. The it_value member of this structure contains the amount of time +before the timer expires, or zero if the timer is disarmed. This value is +returned as the interval until timer expiration, even if the timer was armed +with absolute time. The it_interval member of value contains the reload +value last set by +.Fn timer_settime . +.Pp +The +.Fn timer_settime +function sets the time until the next expiration of the timer specified +by +.Fa timerid +from the it_value member of the value argument and arm the timer if the +it_value member of value is non-zero. If the specified timer was already +armed when +.Fn timer_settime +is called, this call resets the time until next expiration to the value +specified. If the it_value member of value is zero, the timer is disarmed. +If the timer is disarmed, then pending signal is removed. +.Pp +If the flag TIMER_ABSTIME is not set in the argument +.Fa flags , +.Fn timer_settime +behaves as if the time until next expiration is set to +be equal to the interval specified by the it_value member of value. That is, +the timer expires in it_value nanoseconds from when the call is made. If the +flag TIMER_ABSTIME is set in the argument flags, +.Fn timer_settime +behaves as if the time until next expiration is set to be equal to the +difference between the absolute time specified by the it_value member of +value and the current value of the clock associated with +.Fa timerid . +That is, the timer expires when the clock reaches the value specified by the +it_value member of value. If the specified time has already passed, the +function succeeds and the expiration notification is made. +.Pp +The reload value of the timer is set to the value specified by the it_interval +member of value. When a timer is armed with a non-zero it_interval, a periodic +(or repetitive) timer is specified. +.Pp +Time values that are between two consecutive non-negative integer multiples of +the resolution of the specified timer is rounded up to the larger multiple of +the resolution. Quantization error will not cause the timer to expire earlier +than the rounded time value. +.Pp +If the argument ovalue is not NULL, the +.Fn timer_settime +function stores, in the location referenced by ovalue, a value representing +the previous amount of time before the timer would have expired, or zero if the +timer was disarmed, together with the previous timer reload value. Timers is not +expire before their scheduled time. +.Pp +Only a single signal is queued to the process for a given timer at any point in +time. When a timer for which a signal is still pending expires, no signal is +queued, and a timer overrun will occur. When a timer expiration signal is +accepted by a process, the +.Fn timer_getoverrun +function returns the timer expiration overrun count for the specified timer. +The overrun count returned contains the number of extra timer expirations that +occurred between the time the signal was generated (queued) and when it was +accepted, up to but not including an maximum of {DELAYTIMER_MAX}. If the number of +such extra expirations is greater than or equal to {DELAYTIMER_MAX}, then the +overrun count is set to {DELAYTIMER_MAX}. The value returned by +.Fn timer_getoverrun +applies to the most recent expiration signal acceptance for the timer. If no +expiration signal has been delivered for the timer, the return value of +.Fn timer_getoverrun +is unspecified. +.Sh RETURN VALUES +If the +.Fn timer_getoverrun +function succeeds, it returns the timer expiration overrun count as explained +above. +.Pp +If the +.Fn timer_gettime +or +.Fn timer_settime +functions succeed, a value of 0 is returned. +.Pp +If an error occurs for any of these functions, the value -1 is returned, and +errno set to indicate the error. +.Sh ERRORS +The +.Fn timer_settime +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A value structure specified a nanosecond value less than zero or greater than +or equal to 1000 million, and the it_value member of that structure did not +specify zero seconds and nanoseconds. +.El +.Pp +These functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa timerid +argument does not correspond to an ID returned by +.Fn timer_create +but not yet deleted by +.Fn timer_delete . +.El +.Pp +The timer_settime() function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The it_interval member of value is not zero and the timer was created with +notification by creation of a new thread ( sigev_sigev_notify was SIGEV_THREAD) +and a fixed stack address has been set in the thread attribute pointed to by +sigev_notify_attributes. +.El +.Pp +The +.Fn timer_gettime +and +.Fn timer_settime +may fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.El +.Sh SEE ALSO +.Xr clock_getres 2 , +.Xr timer_create 2 +.Sh STANDARDS +The +.Fn timer_getoverrun , +.Fn timer_gettime , +and +.Fn timer_settime +function conform to +.St -p1003.1-96 . |