From dc2c7169226001061050134399de1b4aa7a45526 Mon Sep 17 00:00:00 2001 From: Philip Guenthe Date: Tue, 13 Mar 2012 15:55:47 +0000 Subject: Add manpages for __thrsigdivert, __thrsleep, and __thrwakeup. Various syntax and grammar fixes from jmc@ --- lib/libc/sys/Makefile.inc | 6 +- lib/libc/sys/__thrsigdivert.2 | 128 +++++++++++++++++++++++++ lib/libc/sys/__thrsleep.2 | 214 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 346 insertions(+), 2 deletions(-) create mode 100644 lib/libc/sys/__thrsigdivert.2 create mode 100644 lib/libc/sys/__thrsleep.2 (limited to 'lib/libc') diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index affed8158c4..dcf2d4cb688 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.inc,v 1.97 2012/01/17 02:34:18 guenther Exp $ +# $OpenBSD: Makefile.inc,v 1.98 2012/03/13 15:55:46 guenther Exp $ # $NetBSD: Makefile.inc,v 1.35 1995/10/16 23:49:07 jtc Exp $ # @(#)Makefile.inc 8.1 (Berkeley) 6/17/93 @@ -235,7 +235,8 @@ MAN+= accept.2 access.2 acct.2 adjfreq.2 adjtime.2 bind.2 brk.2 chdir.2 \ setpgid.2 setregid.2 setreuid.2 setresuid.2 setsid.2 setuid.2 \ shutdown.2 sigaction.2 sigaltstack.2 sigpending.2 sigprocmask.2 \ sigreturn.2 sigsuspend.2 socket.2 socketpair.2 stat.2 \ - statfs.2 swapctl.2 symlink.2 sync.2 sysarch.2 syscall.2 truncate.2 \ + statfs.2 swapctl.2 symlink.2 sync.2 sysarch.2 syscall.2 \ + __thrsigdivert.2 __thrsleep.2 truncate.2 \ umask.2 unlink.2 utimes.2 vfork.2 wait.2 write.2 MAN+= msgctl.2 shmctl.2 shmat.2 semop.2 semget.2 semctl.2 msgsnd.2 msgrcv.2 \ @@ -297,6 +298,7 @@ MLINKS+=stat.2 S_ISFIFO.2 stat.2 S_ISLNK.2 stat.2 S_ISREG.2 stat.2 S_ISSOCK.2 MLINKS+=statfs.2 fstatfs.2 MLINKS+=symlink.2 symlinkat.2 MLINKS+=syscall.2 __syscall.2 +MLINKS+=__thrsleep.2 __thrwakeup.2 MLINKS+=truncate.2 ftruncate.2 MLINKS+=unlink.2 unlinkat.2 MLINKS+=utimes.2 futimens.2 utimes.2 futimes.2 utimes.2 utimensat.2 diff --git a/lib/libc/sys/__thrsigdivert.2 b/lib/libc/sys/__thrsigdivert.2 new file mode 100644 index 00000000000..085ab64687a --- /dev/null +++ b/lib/libc/sys/__thrsigdivert.2 @@ -0,0 +1,128 @@ +.\" $OpenBSD: __thrsigdivert.2,v 1.1 2012/03/13 15:55:46 guenther Exp $ +.\" +.\" Copyright (c) 2012 Philip Guenther +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: March 13 2012 $ +.Dt __THRSIGDIVERT 3 +.Os +.Sh NAME +.Nm __thrsigdivert +.Nd synchronously accept a signal +.Sh SYNOPSIS +.In sys/signal.h +.In sys/time.h +.Ft int +.Fn __thrsigdivert "sigset_t set" "siginfo_t *info" "const struct timespec *timeout" +.Sh DESCRIPTION +The +.Fn __thrsigdivert +function is used to implement +.Fn sigwait . +It selects a signal pending for the calling thread or process from +.Fa set , +atomically clears it from that set of pending signals, +and returns that signal number. +If prior to the call to +.Fn __thrsigdivert +there are multiple pending instances of a single signal number, +it is undefined whether upon successful return there are any remaining +pending signals for that signal number. +If no signal in +.Fa set +is pending at the time of the call, +the thread shall be suspended until one or more becomes pending. +The signals defined by +.Fa set +should have been blocked in all threads in the process at the time +of the call to +.Fn __thrsigdivert ; +otherwise the signal may be delivered to some thread that does not +have it blocked. +.Pp +If more than one thread is using +.Fn __thrsigdivert +to wait for the same signal, +no more than one of these threads shall return from +.Fn __thrsigdivert +for any given signal that is sent. +Which thread returns from +.Fn __thrsigdivert +if more than a single thread is waiting is unspecified. +.Pp +If the +.Fa info +argument is not +.Dv NULL , +then a +.Vt siginfo_t +will be stored there which has the selected signal number in its +.Fa si_signo +member and the cause of the signal in its +.Fa si_code +member. +.Pp +If the +.Fa timeout +argument is not +.Dv NULL +and no selected signal is currently pending, +then +.Fn __thrsigdivert +will wait no longer than the specified time period for a signal to +arrive before failing. +.Sh RETURN VALUES +If successful, +the number of the signal that was accepted is returned. +Otherwise, a value of -1 is returned and +.Dv errno +is set to indicate the error. +.Sh ERRORS +.Fn __thrsigdivert +will succeed unless: +.Bl -tag -width Er +.It Bq Er EWOULDBLOCK +The timeout was reached before a selected signal was received. +.It Bq Er ENOTSUP +The kern.rthreads sysctl was not enabled. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigprocmask 2 , +.Xr sigwait 3 +.Sh STANDARDS +The +.Fn __thrsigdivert +function is specific to +.Ox +and should not be used in portable applications. +.Sh HISTORY +The +.Fn __thrsigdivert +function appeared in +.Ox 3.? . +The +.Fa info +and +.Fa timeout +arguments were added in +.Ox 4.9 . +.Sh AUTHORS +.An -nosplit +The +.Fn thrsigdivert +syscall was created by +.An Ted Unangst Aq tedu@OpenBSD.org . +This manual page was written by +.An Philip Guenther Aq guenther@OpenBSD.org . diff --git a/lib/libc/sys/__thrsleep.2 b/lib/libc/sys/__thrsleep.2 new file mode 100644 index 00000000000..5faacbca33d --- /dev/null +++ b/lib/libc/sys/__thrsleep.2 @@ -0,0 +1,214 @@ +.\" $OpenBSD: __thrsleep.2,v 1.1 2012/03/13 15:55:46 guenther Exp $ +.\" +.\" Copyright (c) 2012 Philip Guenther +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: March 13 2012 $ +.Dt __THRSLEEP 3 +.Os +.Sh NAME +.Nm __thrsleep , +.Nm __thrwakeup +.Nd userspace thread sleep and wakeup +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn __thrsleep "const volatile void *id" "clockid_t clock_id" "const struct timespec *abstime" "void *lock" "const int *abort" +.Ft int +.Fn __thrwakeup "const volatile void *id" "int count" +.Sh DESCRIPTION +The +.Fn __thrsleep +and +.Fn __thrwakeup +functions provide thread sleep and wakeup primitives with which +synchronization primitives such as mutexes and condition variables +can be implemented. +.Fn __thrsleep +blocks the calling thread on the abstract +.Dq wait channel +identified by the +.Fa id +argument until another thread calls +.Fn __thrwakeup +with the same +.Fa id +value. +If the +.Fa abstime +argument is not +.Dv NULL , +then it specifies an absolute time, +measured against the +.Fa clock_id +clock, +after which +.Fn __thrsleep +should time out and return. +If the specified time is in the past then +.Fn __thrsleep +will return immediately without blocking. +.Pp +The +.Fa lock +argument, +if not +.Dv NULL , +points to a locked spinlock that will be unlocked by +.Fn __thrsleep +atomically with respect to calls to +.Fn __thrwakeup , +such that if another thread locks the spinlock before calling +.Fn __thrwakeup +with the same +.Fa id , +then the thread that called +.Fn __thrsleep +will be eligible for being woken up and unblocked. +.Pp +The +.Fa abort +argument, +if not +.Dv NULL , +points to an +.Vt int +that will be examined after unlocking the spinlock pointed to by +.Fa lock +and immediately before blocking. +If that +.Vt int +is non-zero then +.Fn __thrsleep +will immediately return +.Er EINTR +without blocking. +This provides a mechanism for a signal handler to keep a call to +.Fn __thrsleep +from blocking, +even if the signal is delivered immediately before the call. +.Pp +The +.Fn __thrwakeup +function unblocks one or more threads that are sleeping on the +wait channel identified by +.Fa id . +The number of threads unblocked is specified by the +.Fa count +argument, +except that if zero is specified then all threads sleeping on that +.Fa id +are unblocked. +.Sh RETURN VALUES +.Fn __thrsleep +will return zero if woken by a matching call to +.Fn __thrwakeup , +otherwise an error number will be returned to indicate the error. +.Pp +.Fn __thrwakeup +will return zero if at least one matching call to +.Fn __thrsleep +was unblocked, +otherwise an error number will be returned to indicate the error. +.Sh ERRORS +.Fn __thrsleep +and +.Fn __thrwakeup +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ident +argument is +.Dv NULL . +.It Bq Er ENOTSUP +The kern.rthreads sysctl was not enabled. +.El +.Pp +In addition, +.Fn __thrsleep +may return one of the following errors: +.Bl -tag -width Er +.It Bq Er EWOULDBLOCK +The time specified by the +.Fa abstime +and +.Fa clock_id +arguments was reached. +.It Bq Er EINTR +A signal arrived or the +.Fa abort +argument pointed to a non-zero value. +.It Bq Er EINVAL +The +.Fa clock_id +argument is neither +.Dv CLOCK_REALTIME +nor +.Dv CLOCK_MONOTONIC . +.El +.Pp +.Fn __thrwakeup +may return the following error: +.Bl -tag -width Er +.It Bq Er ESRCH +No threads calling +.Fn __thrsleep +with the same +.Fa id +were found. +.El +.Sh SEE ALSO +.Xr pthread_cond_wait 3 , +.Xr pthread_mutex_lock 3 , +.Xr tsleep 9 +.Sh STANDARDS +The +.Fn __thrsleep +and +.Fn __thrwakeup +functions are specific to +.Ox +and should not be used in portable applications. +.Sh HISTORY +The +.Fn thrsleep +and +.Fn thrwakeup +syscalls appeared in +.Ox 4.1 . +The +.Fa clock_id +and +.Fa abstime +arguments were added in +.Ox 4.9 . +The functions were renamed to +.Fn __thrsleep +and +.Fn __thrwakeup +and the +.Fa abort +argument was added in +.Ox 5.1 +.Sh AUTHORS +.An -nosplit +The +.Fn thrsleep +and +.Fn thrwakeup +syscalls were created by +.An Ted Unangst Aq tedu@OpenBSD.org . +This manual page was written by +.An Philip Guenther Aq guenther@OpenBSD.org . -- cgit v1.2.3