Fix up markup etc. in recently born manpage.

This commit is contained in:
Ruslan Ermilov 2005-11-18 11:53:23 +00:00
parent 78ad54210f
commit 5507a2aed5
5 changed files with 316 additions and 152 deletions

View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2005 David Xu <davidxu@freebsd.org>
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -27,12 +27,12 @@
.\"
.\" $FreeBSD$
.\"
.Dd Nov 11, 2005
.Dd November 11, 2005
.Dt SIGQUEUE 2
.Os
.Sh NAME
.Nm sigqueue
.Nd queue a signal to a process (REALTIME)
.Nd "queue a signal to a process (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@ -42,7 +42,7 @@
.Sh DESCRIPTION
The
.Fn sigqueue
function causes the signal specified by
system call causes the signal specified by
.Fa signo
to be sent with the value specified by
.Fa value
@ -51,18 +51,24 @@ to the process specified by
If
.Fa signo
is zero (the null signal), error checking is performed but
no signal is actually sent. The null signal can be used to check the
validity of pid.
no signal is actually sent.
The null signal can be used to check the
validity of PID.
.Pp
The conditions required for a process to have permission to queue a
signal to another process are the same as for the
.Fn kill
function.
.Xr kill 2
system call.
The
.Fn sigqueue
function queues a signal to a single process specified by the pid argument.
system call queues a signal to a single process specified by the
.Fa pid
argument.
.Pp
The sigqueue() function returns immediately. If the resources were
The
.Fn sigqueue
system call returns immediately.
If the resources were
available to queue the signal, the signal will be queued and sent to
the receiving process.
.Pp
@ -76,31 +82,36 @@ is not blocked for the calling thread and if no other thread has
.Fa signo
unblocked or is waiting in a
.Fn sigwait
function for
system call for
.Fa signo ,
either
.Fa signo
or at least the pending, unblocked signal will be delivered to the
calling thread before the
calling thread before
.Fn sigqueue
function returns. Should any multiple pending signals in the range
SIGRTMIN to SIGRTMAX be selected for delivery, it is the lowest numbered
one. The selection order between realtime and non-realtime signals, or
returns.
Should any multiple pending signals in the range
.Dv SIGRTMIN
to
.Dv SIGRTMAX
be selected for delivery, it is the lowest numbered
one.
The selection order between realtime and non-realtime signals, or
between multiple pending non-realtime signals, is unspecified.
.Sh RETURN VALUES
Upon successful completion, the specified signal has been queued, and
the
.Fn sigqueue
function returns a value of zero. Otherwise, the function returns a value
of -1 and set errno to indicate the error.
.Rv -std
.Sh ERRORS
The
.Fn sigqueue
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
No resources are available to queue the signal. The process has already
queued {SIGQUEUE_MAX} signals that are still pending at the receiver(s),
No resources are available to queue the signal.
The process has already
queued
.Brq Dv SIGQUEUE_MAX
signals that are still pending at the receiver(s),
or a system-wide resource limit has been exceeded.
.It Bq Er EINVAL
The value of the
@ -110,20 +121,22 @@ argument is an invalid or unsupported signal number.
The process does not have the appropriate privilege to send the signal
to the receiving process.
.It Bq Er ESRCH
The process pid does not exist.
The process
.Fa pid
does not exist.
.El
.Sh SEE ALSO
.Xr sigwait 2 ,
.Xr sigtimedwait 2 ,
.Xr sigwaitinfo 2 ,
.Xr sigqueue 2 ,
.Xr sigaction 2 ,
.Xr sigpending 2 ,
.Xr sigqueue 2 ,
.Xr sigsuspend 2 ,
.Xr sigtimedwait 2 ,
.Xr sigwait 2 ,
.Xr sigwaitinfo 2 ,
.Xr pause 3 ,
.Xr pthread_sigmask 3
.Sh STANDARDS
The
.Fn sigqueue
function conforms to
system call conforms to
.St -p1003.1-96 .

View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2005 David Xu <davidxu@freebsd.org>
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -27,61 +27,68 @@
.\"
.\" $FreeBSD$
.\"
.Dd Nov 11, 2005
.Dd November 11, 2005
.Dt SIGTIMEDWAIT 2
.Os
.Sh NAME
.Nm sigtimedwait,
.Nm sigwaitinfo
.Nd wait for queued signals (REALTIME)
.Nm sigtimedwait , sigwaitinfo
.Nd "wait for queued signals (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In signal.h
.Ft int
.Fn sigtimedwait "const sigset_t *restrict set" "siginfo_t *restrict info" "const struct timespec *restrict timeout"
.Fo sigtimedwait
.Fa "const sigset_t *restrict set" "siginfo_t *restrict info"
.Fa "const struct timespec *restrict timeout"
.Fc
.Ft int
.Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info"
.Sh DESCRIPTION
The
.Fn sigtimedwait
function is equivalent to
system call is equivalent to
.Fn sigwaitinfo
except that if none of the signals specified by
.Fa set
are pending,
.Fn
sigtimedwait
.Fn sigtimedwait
waits for the time interval specified in the
.Sy
timespec
.Vt timespec
structure referenced by
.Fa timeout .
If the
.Sy
timespec
.Vt timespec
structure pointed to by
.Fa timeout
is zero-valued and if none of the signals specified by
.Fa set
are pending, then
.Fn sigtimedwait
returns immediately with an error. If
returns immediately with an error.
If
.Fa timeout
is the NULL pointer, the behavior is unspecified. CLOCK_MONOTONIC
is the
.Dv NULL
pointer, the behavior is unspecified.
.Dv CLOCK_MONOTONIC
clock is used to measure the time interval specified by the
.Fa timeout
argument.
.Pp
The
.Fn sigwaitinfo
function selects the pending signal from the set specified by
system call selects the pending signal from the set specified by
.Fa set .
Should any of multiple pending signals in the range SIGRTMIN to
SIGRTMAX be selected, it shall be the lowest numbered one. The
Should any of multiple pending signals in the range
.Dv SIGRTMIN
to
.Dv SIGRTMAX
be selected, it shall be the lowest numbered one.
The
selection order between realtime and non-realtime signals, or
between multiple pending non-realtime signals, is unspecified.
If no signal in
If no signal in
.Fa set
is pending at the time of the call, the calling thread
is suspended until one or more signals in
@ -90,37 +97,57 @@ become pending or until it is interrupted by an unblocked, caught signal.
.Pp
The
.Fn sigwaitinfo
function is equivalent to the
system call is equivalent to the
.Fn sigwait
function if the
system call if the
.Fa info
argument is NULL. If the
argument is
.Dv NULL .
If the
.Fa info
argument is non-NULL, the
argument is
.Pf non- Dv NULL ,
the
.Fn sigwaitinfo
function is equivalent to
.Fn sigwait ,
except that the selected signal number shall be stored in the
si_signo member, and the cause of the signal shall be stored in the si_code
member. If any value is queued to the selected signal, the first such queued
value is dequeued and, if the info argument is non-NULL, the value is stored
in the si_value member of info. The system resource used to queue the signal
is released and returned to the system for other use. If no value is queued,
the content of the si_value member is zero-valued. If no further signals are
.Va si_signo
member, and the cause of the signal shall be stored in the
.Va si_code
member.
If any value is queued to the selected signal, the first such queued
value is dequeued and, if the info argument is
.Pf non- Dv NULL ,
the value is stored in the
.Va si_value
member of
.Fa info .
The system resource used to queue the signal
is released and returned to the system for other use.
If no value is queued,
the content of the
.Va si_value
member is zero-valued.
If no further signals are
queued for the selected signal, the pending indication for that signal
is reset.
.Sh RETURN VALUES
Upon successful completion (that is, one of the signals specified by
.Fa set
is pending or is generated)
is pending or is generated)
.Fn sigwaitinfo
and
.Fn sigtimedwait
return the selected signal number. Otherwise, the function return a value of -1
and set errno to indicate the error.
return the selected signal number.
Otherwise, the functions return a value of \-1
and set the global variable
.Va errno
to indicate the error.
.Sh ERRORS
The
.Fn sigtimedwait
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
@ -131,7 +158,7 @@ The
.Fn sigtimedwait
and
.Fn sigwaitinfo
functions fail if:
system calls fail if:
.Bl -tag -width Er
.It Bq Er EINTR
The wait was interrupted by an unblocked, caught signal.
@ -142,22 +169,24 @@ memory protection fault.
.El
The
.Fn sigtimedwait
function may also fail if:
system call may also fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa timeout
argument specified a tv_nsec value less than zero or greater than or equal
argument specified a
.Va tv_nsec
value less than zero or greater than or equal
to 1000 million.
Kernel only checks for this error if no signal is pending in set and it
is necessary to wait.
.El
.Sh SEE ALSO
.Xr sigwait 2 ,
.Xr sigqueue 2 ,
.Xr sigaction 2 ,
.Xr sigpending 2 ,
.Xr sigqueue 2 ,
.Xr sigsuspend 2 ,
.Xr sigwait 2 ,
.Xr pause 3 ,
.Xr pthread_sigmask 3
.Sh STANDARDS
@ -165,5 +194,5 @@ The
.Fn sigtimedwait
and
.Fn sigwaitinfo
functions conform to
system calls conform to
.St -p1003.1-96 .

View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2005 David Xu <davidxu@freebsd.org>
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -27,28 +27,34 @@
.\"
.\" $FreeBSD$
.\"
.Dd Sep 11, 2000
.Dd September 11, 2000
.Dt TIMER_CREATE 2
.Os
.Sh NAME
.Nm timer_create
.Nd create a per-process timer (REALTIME)
.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"
.Fo timer_create
.Fa "clockid_t clockid" "struct sigevent *restrict evp"
.Fa "timer_t *restrict timerid"
.Fc
.Sh DESCRIPTION
The
.Fn timer_create
function creates a per-process timer using the specified clock,
system call creates a per-process timer using the specified clock,
.Fa clock_id ,
as the timing base. The
as the timing base.
The
.Fn timer_create
function returns, in the location referenced by
system call returns, in the location referenced by
.Fa timerid ,
a timer ID of type timer_t used to identify the timer in timer requests.
a timer ID of type
.Vt 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 ,
@ -59,19 +65,51 @@ The timer whose ID is returned is in a disarmed state upon return from
.Pp
The
.Fa evp
argument, if non-NULL, points to a sigevent structure. This structure,
argument, if
.Pf non- Dv NULL ,
points to a
.Vt sigevent
structure.
This structure,
allocated by the application, defines the asynchronous notification to occur
when the timer expires. If the
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
argument is
.Dv NULL ,
the effect is as if the
.Fa evp
argument pointed to a
.Vt sigevent
structure with the
.Va sigev_notify
member having the value
.Dv SIGEV_SIGNAL ,
the
.Va sigev_signo
having a default signal number, and the
.Va sigev_value
member having
the value of the timer ID.
.Pp
The implementations supports a clock_id of CLOCK_REALTIME or CLOCK_MONOTONIC.
The implementations supports a
.Fa clock_id
of
.Dv CLOCK_REALTIME
or
.Dv 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
If
.Fa evp->sigev_sigev_notify
is
.Dv SIGEV_THREAD
and
.Fa sev->sigev_notify_attributes
is not
.Dv NULL ,
if the attribute pointed to by
.Fa sev->sigev_notify_attributes
has
a thread stack address specified by a call to
.Fn pthread_attr_setstack
or
@ -80,19 +118,29 @@ 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
returns zero and updates 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.
to a
.Vt timer_t ,
which can be passed to the per-process timer calls.
If an error
occurs, the system call returns a value of \-1
and the global variable
.Va errno
is set to indicate the
error.
The value of
.Fa timerid
is undefined if an error occurs.
.Sh ERRORS
The
.Fn timer_create
system call
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
this implementation.
.It Bq Er EINVAL
The specified clock ID is not supported.
.It Bq Er EFAULT
@ -106,5 +154,5 @@ memory protection fault.
.Sh STANDARDS
The
.Fn timer_create
function conforms to
system call conforms to
.St -p1003.1-96 .

View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2005 David Xu <davidxu@freebsd.org>
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -27,12 +27,12 @@
.\"
.\" $FreeBSD$
.\"
.Dd Sep 11, 2000
.Dd September 11, 2000
.Dt TIMER_DELETE 2
.Os
.Sh NAME
.Nm timer_delete
.Nd delete a per-process timer (REALTIME)
.Nd "delete a per-process timer (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@ -42,31 +42,34 @@
.Sh DESCRIPTION
The
.Fn timer_delete
system call
deletes the specified timer,
.Fa timerid ,
previously created by the
.Fn timer_create
function. If the timer is armed when
.Xr timer_create 2
system call.
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.
removal.
Pending signals for the deleted timer are 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.
.Rv -std
.Sh ERRORS
The
.Fn timer_delete
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The timer ID specified by timerid is not a valid timer ID.
The timer ID specified by
.Fa timerid
is not a valid timer ID.
.El
.Sh SEE ALSO
.Xr timer_create 2
.Sh STANDARDS
The
.Fn timer_delete
function conforms to
system call conforms to
.St -p1003.1-96 .

View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2005 David Xu <davidxu@freebsd.org>
.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -27,14 +27,14 @@
.\"
.\" $FreeBSD$
.\"
.Dd Sep 11, 2000
.Dd September 11, 2000
.Dt TIMER_SETTIME 2
.Os
.Sh NAME
.Nm timer_getoverrun
.Nm timer_gettime
.Nm timer_getoverrun ,
.Nm timer_gettime ,
.Nm timer_settime
.Nd per-process timers (REALTIME)
.Nd "per-process timers (REALTIME)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@ -44,108 +44,169 @@
.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"
.Fo timer_settime
.Fa "timer_t timerid" "int flags" "const struct itimerspec *restrict value"
.Fa "struct itimerspec *restrict ovalue"
.Fc
.Sh DESCRIPTION
The
.Fn timer_gettime
function stores the amount of time until the specified timer,
system call 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
argument.
The
.Va 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
with absolute time.
The
.Va it_interval
member of
.Fa 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
system call 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
from the
.Va it_value
member of the
.Fa value
argument and arms the timer if the
.Va it_value
member of
.Fa 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.
specified.
If the
.Va it_value
member of
.Fa 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
If the flag
.Dv 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,
be equal to the interval specified by the
.Va it_value
member of
.Fa value .
That is,
the timer expires in
.Va it_value
nanoseconds from when the call is made.
If the flag
.Dv TIMER_ABSTIME
is set in the argument
.Fa 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.
.Va it_value
member of
.Fa value .
If the specified time has already passed, the
system call 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
The reload value of the timer is set to the value specified by the
.Va it_interval
member of
.Fa value .
When a timer is armed with a non-zero
.Va 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
the resolution of the specified timer are 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
If the argument
.Fa ovalue
is not
.Dv NULL ,
the
.Fn timer_settime
function stores, in the location referenced by ovalue, a value representing
system call stores, in the location referenced by
.Fa 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
timer was disarmed, together with the previous timer reload value.
Timers do 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
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.
system call 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
accepted, up to but not including an maximum of
.Brq Dv DELAYTIMER_MAX .
If the number of
such extra expirations is greater than or equal to
.Brq Dv DELAYTIMER_MAX ,
then the overrun count is set to
.Brq Dv DELAYTIMER_MAX .
The value returned by
.Fn timer_getoverrun
applies to the most recent expiration signal acceptance for the timer. If no
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
system call succeeds, it returns the timer expiration overrun count as explained
above.
Otherwise the value \-1 is returned, and the global variable
.Va errno
is set to indicate the error.
.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.
.Rv -std timer_gettime timer_settime
.Sh ERRORS
The
.Fn timer_settime
system call
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
A
.Fa value
structure specified a nanosecond value less than zero or greater than
or equal to 1000 million, and the
.Va it_value
member of that structure did not
specify zero seconds and nanoseconds.
.El
.Pp
These functions may fail if:
These system calls may fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
@ -156,19 +217,29 @@ but not yet deleted by
.Fn timer_delete .
.El
.Pp
The timer_settime() function may fail if:
The
.Fn timer_settime
system call 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)
The
.Va it_interval
member of
.Fa value
is not zero and the timer was created with
notification by creation of a new thread
.Va ( sigev_sigev_notify
was
.Dv SIGEV_THREAD )
and a fixed stack address has been set in the thread attribute pointed to by
sigev_notify_attributes.
.Va sigev_notify_attributes .
.El
.Pp
The
.Fn timer_gettime
and
.Fn timer_settime
system calls
may fail if:
.Bl -tag -width Er
.It Bq Er EFAULT
@ -176,7 +247,7 @@ Any arguments point outside the allocated address space or there is a
memory protection fault.
.El
.Sh SEE ALSO
.Xr clock_getres 2 ,
.Xr clock_getres 2 ,
.Xr timer_create 2
.Sh STANDARDS
The
@ -184,5 +255,5 @@ The
.Fn timer_gettime ,
and
.Fn timer_settime
function conform to
system calls conform to
.St -p1003.1-96 .