1.\" Copyright (C) 2000 Jason Evans <[email protected]>. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd Sep 11, 2000 31.Dt TIMER_CREATE 2 32.Os 33.Sh NAME 34.Nm timer_create 35.Nd create a per-process timer (REALTIME) 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In time.h 40.Ft int 41.Fn timer_create "clockid_t clockid" "struct sigevent *restrict evp" "timer_t *restrict timerid" 42.Sh DESCRIPTION 43The 44.Fn timer_create 45function creates a per-process timer using the specified clock, 46.Fa clock_id , 47as the timing base. The 48.Fn timer_create 49function returns, in the location referenced by 50.Fa timerid , 51a timer ID of type timer_t used to identify the timer in timer requests. 52This timer ID is unique within the calling process until the timer is deleted. 53The particular clock, 54.Fa clock_id , 55is defined in 56.In time.h . 57The timer whose ID is returned is in a disarmed state upon return from 58.Fn timer_create . 59.Pp 60The 61.Fa evp 62argument, if non-NULL, points to a sigevent structure. This structure, 63allocated by the application, defines the asynchronous notification to occur 64when the timer expires. If the 65.Fa evp 66argument is NULL, the effect is as if the evp argument pointed to a sigevent 67structure with the sigev_notify member having the value SIGEV_SIGNAL, the 68sigev_signo having a default signal number, and the sigev_value member having 69the value of the timer ID. 70.Pp 71The implementations supports a clock_id of CLOCK_REALTIME or CLOCK_MONOTONIC. 72.Pp 73If evp->sigev_sigev_notify is SIGEV_THREAD and sev->sigev_notify_attributes 74is not NULL, if the attribute pointed to by sev->sigev_notify_attributes has 75a thread stack address specified by a call to 76.Fn pthread_attr_setstack 77or 78.Fn pthread_attr_setstackaddr , 79the results are unspecified if the signal is generated more than once. 80.Sh RETURN VALUES 81If the call succeeds, 82.Fn timer_create 83returns zero and update the location referenced by 84.Fa timerid 85to a timer_t, which can be passed to the per-process timer calls. If an error 86occurs, the function shall return a value of -1 and set errno to indicate the 87error. The value of timerid is undefined if an error occurs. 88.Sh ERRORS 89The 90.Fn timer_create 91will fail if: 92.Bl -tag -width Er 93.It Bq Er EAGAIN 94The calling process has already created all of the timers it is allowed by 95this implementation 96.It Bq Er EINVAL 97The specified clock ID is not supported. 98.It Bq Er EFAULT 99Any arguments point outside the allocated address space or there is a 100memory protection fault. 101.El 102.Sh SEE ALSO 103.Xr clock_getres 2 , 104.Xr timer_delete 2 , 105.Xr timer_getoverun 2 106.Sh STANDARDS 107The 108.Fn timer_create 109function conforms to 110.St -p1003.1-96 . 111