From 226b4082f42ee7d005960963428701d0ccf9abea Mon Sep 17 00:00:00 2001 From: christos Date: Sat, 13 Sep 2003 22:22:29 +0000 Subject: [PATCH] Add timer man pages. Hi Nathan! --- lib/libc/sys/Makefile.inc | 6 +- lib/libc/sys/timer_create.2 | 120 ++++++++++++++++++++++++ lib/libc/sys/timer_delete.2 | 81 +++++++++++++++++ lib/libc/sys/timer_settime.2 | 172 +++++++++++++++++++++++++++++++++++ 4 files changed, 377 insertions(+), 2 deletions(-) create mode 100644 lib/libc/sys/timer_create.2 create mode 100644 lib/libc/sys/timer_delete.2 create mode 100644 lib/libc/sys/timer_settime.2 diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index e4e3d4a08a41..a83916c13b18 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -1,4 +1,4 @@ -# $NetBSD: Makefile.inc,v 1.141 2003/08/01 17:03:58 lukem Exp $ +# $NetBSD: Makefile.inc,v 1.142 2003/09/13 22:22:29 christos Exp $ # @(#)Makefile.inc 8.3 (Berkeley) 10/24/94 # sys sources @@ -151,7 +151,8 @@ MAN+= accept.2 access.2 acct.2 adjtime.2 bind.2 brk.2 chdir.2 \ sigprocmask.2 sigreturn.2 sigstack.2 sigsuspend.2 sigtimedwait.2 \ socket.2 \ socketpair.2 stat.2 statfs.2 swapctl.2 swapon.3 symlink.2 \ - sync.2 sysarch.2 syscall.2 truncate.2 umask.2 undelete.2 \ + sync.2 sysarch.2 syscall.2 timer_create.2 timer_delete.2 \ + truncate.2 umask.2 undelete.2 \ unlink.2 utimes.2 utrace.2 vfork.2 wait.2 write.2 MLINKS+=_exit.2 _Exit.2 @@ -195,6 +196,7 @@ MLINKS+=send.2 sendmsg.2 send.2 sendto.2 MLINKS+=setpgid.2 setpgrp.2 MLINKS+=setuid.2 setegid.2 setuid.2 seteuid.2 setuid.2 setgid.2 MLINKS+=shmat.2 shmdt.2 +MLINKS+=timer_settime.2 timer_gettime.2 timer_settime.2 timer_getoverrun.2 MLINKS+=sigtimedwait.2 sigwaitinfo.2 MLINKS+=sigtimedwait.2 sigwait.2 MLINKS+=stat.2 fstat.2 stat.2 lstat.2 diff --git a/lib/libc/sys/timer_create.2 b/lib/libc/sys/timer_create.2 new file mode 100644 index 000000000000..5144b14cee69 --- /dev/null +++ b/lib/libc/sys/timer_create.2 @@ -0,0 +1,120 @@ +.\" $NetBSD: timer_create.2,v 1.1 2003/09/13 22:22:30 christos Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.Dd September 13, 2003 +.Dt TIMER_CREATE 2 +.Os +.Sh NAME +.Nm timer_create +.Nd create a per-process timer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.In signal.h +.Ft int +.Fn timer_create "clockid_t clockid" "struct sigevent *evp" "timer_t *timerid" +.Sh DESCRIPTION +The +.Fn timer_create +function creates a per-process timer using the clock specified in the +.Ar clockid +argument. +If it succeeds, the +.Fn timer_create +function fills in the +.Ar timerid +argument with an id accociated with the timer created that can be used by +other timer related calls. The +.Ar clockid +must be a valid clock id as defined in +.In time.h . +The timer is created in a disarmed state. +.Pp +An optional (non- +.Dv NULL +sigevent argument can be specified by the +.Ar evp +argument. If the +.Ar evp +argument is +.Dv NULL , +then it defaults to +.Fa sigev_notify +set to +.Dv SIGEV_SIGVAL +and +.Fa sigev_value +set to +.Ar timerid . +See +.Xr siginfo 5 +for accessing those values from a signal handler. +.Sh NOTES +Timers are not inherited after a +.Xr fork 2 +and are disarmed and deleted by an +.Xr exec 2 . +.Sh RETURN VALUES +If the +.Fn timer_create +call succeed, it returns 0, and fills in the +.Ar timerid +argument with the id of the new timer that was created. +If the call fails, it returns -1, and sets errno to indicate the error. +.Sh ERRORS +The +.Fn timer_create +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system is out of resources to satisfy this request, or the process has +created all the timers it is allowed. +.It Bq Er EINVAL +The clock id in the +.Ar clockid +is invalid. +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr clock_settime 2 , +.Xr clock_getres 2 , +.Xr timer_delete 2 , +.Xr timer_gettime 2 , +.Xr timer_getoverrun 2 , +.Xr timer_settime 2 +.Sh STANDARDS +.St -p1003.1b-93 , +.St -p1003.1i-95 diff --git a/lib/libc/sys/timer_delete.2 b/lib/libc/sys/timer_delete.2 new file mode 100644 index 000000000000..9f472b27bc81 --- /dev/null +++ b/lib/libc/sys/timer_delete.2 @@ -0,0 +1,81 @@ +.\" $NetBSD: timer_delete.2,v 1.1 2003/09/13 22:22:30 christos Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.Dd September 13, 2003 +.Dt TIMER_DELETE 2 +.Os +.Sh NAME +.Nm timer_delete +.Nd delete a per-process timer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_delete "timer_t timerid" +.Sh DESCRIPTION +The +.Fn timer_delete +functions deletes the timer specified in the +.Ar timerid +argument. The +.Ar timerid +argument must point to valid timer id, created by +.Xr timer_create 2 . +If the deletion is successful, the timer is disarmed and deleted. +Pending notification events (signals) may or may not be delivered. +.Sh RETURN VALUES +The +.Fn timer_delete +functions returns 0 if it succeeds and -1 on error, setting errno to indicate +the nature of the error. +.Sh ERRORS +The +.Fn timer_delete +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The timer id specified in the +.Ar timerid +argument is not valid. +.Sh SEE ALSO +.Xr timer_create 2 , +.Xr timer_gettime 2 , +.Xr timer_getoverrun 2 , +.Xr timer_settime 2 +.Sh STANDARDS +.St -p1003.1b-93 , +.St -p1003.1i-95 diff --git a/lib/libc/sys/timer_settime.2 b/lib/libc/sys/timer_settime.2 new file mode 100644 index 000000000000..217a5caa1217 --- /dev/null +++ b/lib/libc/sys/timer_settime.2 @@ -0,0 +1,172 @@ +.\" $NetBSD: timer_settime.2,v 1.1 2003/09/13 22:22:30 christos Exp $ +.\" +.\" Copyright (c) 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.Dd September 13, 2003 +.Dt TIMER_SETTIME 2 +.Os +.Sh NAME +.Nm timer_settime, timer_gettime, timer_getoverrun +.Nd process timer manipulation +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_settime "timer_t timerid" "int flags" "const struct itimerspec *tim" "struct itimerspec *otim" +.Ft int +.Fn timer_gettime "timer_t timerid" "struct itimerspec *tim" +.Ft int +.Fn timer_getoverrun "timer_t timerid" +.Sh DESCRIPTION +The +.Fn timer_settime +sets the next expiration time of the timer who's id is specified by +.Ar timerid +to the +.Fa it_value +specified in the +.Ar tim +argument. +If the value is 0, the timer is disarmed. +If the argument +.Ar otim +is not +.Dv NULL +the old timer settingas are returned. +If the +.Ar flags +argument is set to +.Dv TIMER_RELTIME +then the expiration time is set to the value in nanoseconds specified in +the +.Ar tim +argument from the time the call to +.Fn timer_settime +was made. If the +.Ar flags +argument is set to +.Dv TIMER_ABSTIME +then the expiration time is set to be equal to the difference between the +clock associated with this timer, and the value specified in the +.Ar tim +argument. If that time has already passed, then the call succeeds, and the +expiration notification occurs. +.Pp +If the +.Fa it_interval +of the +.Ar tim +argument is non zero, then the timer reloads upon expiration. +.Pp +The +.Fn timer_gettime +function returns the current settings of the timer +specified by the +.Ar timerid +argument in the +.Ar tim +argument. +.Pp +Only one notification event (signal) can be pending for a given timer +and process. +If a timer expires while the signal is still queued for delivery, then +the overrun counter for that timer is increased. The counter can store +values up to +.Dv DELAYTIMER_MAX . +When the signal is finally delivered to the process, then the +.Fn timer_getoverrun +function can be used to retrieve the overrun counter for the timer +specified in the +.Ar timerid +argument. +.Sh NOTES +Expiration time values are always rounded up to the resolution of the timer, +so a notification will never be sent before the requested time. +Values returned +in the +.Ar otim +argument of +.Fn timer_settime +or in the +.Ar tim +argment of +.Fn timer_gettime +are subject to the above rounding effect and might not exactly match the +requested values by the user. +.Sh RETURN VALUES +The +.Fn timer_gettime +and +.Fn timer_settime +functions return 0 on success or -1 on failure with errno set to indicate the +error. +The +.Fn timer_getoverrun +returns the expiration overrun count for the specified timer when it succeeds, +or -1 with errno set to indicated the error. +.Sh ERRORS +The +.Fn timer_gettime , +.Fn timer_getoverrun , +and +.Fn timer_settime +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Ar timerid +argument does not correspond to a valid timer id as returned by +.Fn timer_create +or that timer id has been deleted by +.Fn timer_delete . +.El +.Pp +The +.Fn timer_settime +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A nanosecond field in the +.Ar tim +structure specified a value less than zero or greater than or equal to 10e9. +.El +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr timer_create 2 , +.Xr timer_delete 2 +.Sh STANDARDS +.St -p1003.1b-93 , +.St -p1003.1i-95