Add POSIX timer manuals.
This commit is contained in:
David Xu
parent
d09ed26fd8
commit
bb5eebe6f2
@ -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
|
||||
|
||||
110
lib/libc/sys/timer_create.2
Normal file
110
lib/libc/sys/timer_create.2
Normal file
@ -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 .
|
||||
70
lib/libc/sys/timer_delete.2
Normal file
70
lib/libc/sys/timer_delete.2
Normal file
@ -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 .
|
||||
186
lib/libc/sys/timer_settime.2
Normal file
186
lib/libc/sys/timer_settime.2
Normal file
@ -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 .
|
||||
Loading…
x
Reference in New Issue
Block a user