summaryrefslogtreecommitdiff
path: root/lib/libc/sys
diff options
context:
space:
mode:
authoruwe <uwe@NetBSD.org>2022-12-04 16:17:50 +0000
committeruwe <uwe@NetBSD.org>2022-12-04 16:17:50 +0000
commit659700f404cfdab81bd8f2ea58e606b3b2004fba (patch)
tree2488d63c227c61826bec23ab04d0b8b3ded8730e /lib/libc/sys
parent1f8089d08cef16ee99c9b865ccf7d37c7c24305f (diff)
Tweak markup in _lwp_*(2) manual pages
Use .Rv where possible. Some manual pages claimed that the error "is returned", but RTFS and some quick testing indicate that this is wrong. The commit message from 2003 says that: Note our current implementation mis-matches [man pages] slightly (error codes are stuffed into errno, where they should simply be returned by these calls). This will be addressed shortly. That hasn't happened in the 20 years, so we might as well make the man pages reflect the reality.
Diffstat (limited to 'lib/libc/sys')
-rw-r--r--lib/libc/sys/_lwp_create.227
-rw-r--r--lib/libc/sys/_lwp_ctl.223
-rw-r--r--lib/libc/sys/_lwp_detach.29
-rw-r--r--lib/libc/sys/_lwp_getname.210
-rw-r--r--lib/libc/sys/_lwp_kill.29
-rw-r--r--lib/libc/sys/_lwp_park.220
-rw-r--r--lib/libc/sys/_lwp_setname.210
-rw-r--r--lib/libc/sys/_lwp_suspend.213
-rw-r--r--lib/libc/sys/_lwp_unpark.29
-rw-r--r--lib/libc/sys/_lwp_unpark_all.224
-rw-r--r--lib/libc/sys/_lwp_wait.29
-rw-r--r--lib/libc/sys/_lwp_wakeup.29
12 files changed, 77 insertions, 95 deletions
diff --git a/lib/libc/sys/_lwp_create.2 b/lib/libc/sys/_lwp_create.2
index 1af13e7d092..c7c07a405e7 100644
--- a/lib/libc/sys/_lwp_create.2
+++ b/lib/libc/sys/_lwp_create.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_create.2,v 1.10 2022/12/04 11:25:09 uwe Exp $
+.\" $NetBSD: _lwp_create.2,v 1.11 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -51,20 +51,23 @@ The signal stack of the newly created light-weight process is reset to
disabled.
If this context specifies invalid register values (for example privilege
escalation by setting machine dependent bits forbidden for user processes),
-or does not specify cpu register values (uc_flags does not have the
-_UC_CPU bit set), the call will fail and errno will be set to
+or does not specify cpu register values
+.Fa ( uc_flags
+does not have the
+.Dv _UC_CPU
+bit set), the call will fail and errno will be set to
.Er EINVAL .
.Pp
The following flags affect the creation of the new LWP:
-.Bl -tag -width LWP_SUSPENDED
-.It LWP_DETACHED
+.Bl -tag -width Dv
+.It Dv LWP_DETACHED
The LWP is created detached.
The resources associated with a detached LWP will be automatically
reclaimed by the system when the LWP exits.
Otherwise, a terminated LWP's resources will not be reclaimed until
its status is reported to another LWP via
.Xr _lwp_wait 2 .
-.It LWP_SUSPENDED
+.It Dv LWP_SUSPENDED
The LWP is created suspended, and will not begin execution until
it is resumed by another LWP via
.Xr _lwp_continue 2 .
@@ -74,15 +77,11 @@ it is resumed by another LWP via
The LWP ID of the new LWP is stored in the location pointed to by
.Fa new_lwp .
.Sh RETURN VALUES
-Upon successful completion,
-.Fn _lwp_create
-returns a value of 0.
-Otherwise, a value of -1 is returned and errno is set to one of the values
-documented below.
+.Rv -std _lwp_create
.Sh ERRORS
.Fn _lwp_create
will fail and no LWP will be created if:
-.Bl -tag -width 10n
+.Bl -tag -width Er
.It Bq Er EAGAIN
The system-imposed limit on the total
number of LWPs under execution would be exceeded.
@@ -94,7 +93,9 @@ or
.Fa new_lwp
is outside the process's allocated address space.
.It Bq Er EINVAL
-The ucontext_t passed is invalid.
+The
+.Vt ucontext_t
+passed is invalid.
.It Bq Er ENOMEM
There is insufficient swap space for the new LWP.
.El
diff --git a/lib/libc/sys/_lwp_ctl.2 b/lib/libc/sys/_lwp_ctl.2
index f1ef6e9938a..32f06f821f8 100644
--- a/lib/libc/sys/_lwp_ctl.2
+++ b/lib/libc/sys/_lwp_ctl.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_ctl.2,v 1.5 2012/04/13 15:14:58 yamt Exp $
+.\" $NetBSD: _lwp_ctl.2,v 1.6 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c)2007 YAMAMOTO Takashi,
.\" All rights reserved.
@@ -49,7 +49,7 @@ It takes the following arguments.
.Bl -tag -width features
.It Fa features
The bitwise-OR of the following flags.
-.Bl -tag -width LWPCTL_FEATURE_CURCPU
+.Bl -tag -width Dv
.It Dv LWPCTL_FEATURE_CURCPU
Request
.Vt lc_curcpu .
@@ -68,8 +68,8 @@ The per-LWP communication area is described by an
structure.
It has following members, depending on
.Fa features .
-.Bl -tag -width int_lc_curcpu
-.It Vt int lc_curcpu
+.Bl -tag -width Fa
+.It Vt int Fa lc_curcpu
The integral identifier of the CPU on which the LWP is running,
or
.Dv LWPCTL_CPU_NONE
@@ -79,10 +79,13 @@ userland.
It's available only if requested with the
.Dv LWPCTL_FEATURE_CURCPU
flag.
-.It Vt int lc_pctr
+.It Vt int Fa lc_pctr
The integer which is incremented on every context switches to the LWP.
-It can be used to detect preemption of the LWP.
-(thus its name "preemption counter".)
+It can be used to detect preemption of the LWP
+.Po
+thus its name
+.Dq preemption counter .
+.Pc
It's updated by the kernel and should be considered as read-only for
userland.
It's available only if requested with the
@@ -91,11 +94,7 @@ flag.
.El
.\" ------------------------------------------------------------
.Sh RETURN VALUES
-.Fn _lwp_ctl
-returns 0 on success.
-Otherwise, \-1 is returned and
-.Va errno
-is set to indicate the error.
+.Rv -std _lwp_ctl
.\" ------------------------------------------------------------
.\".Sh ERRORS
.\" ------------------------------------------------------------
diff --git a/lib/libc/sys/_lwp_detach.2 b/lib/libc/sys/_lwp_detach.2
index 6c9f01ff962..7b1fe71eac5 100644
--- a/lib/libc/sys/_lwp_detach.2
+++ b/lib/libc/sys/_lwp_detach.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_detach.2,v 1.4 2008/04/30 13:10:51 martin Exp $
+.\" $NetBSD: _lwp_detach.2,v 1.5 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -52,12 +52,9 @@ Conversely, an attached LWP's resources will not be reclaimed until
its status is reported to another LWP via
.Xr _lwp_wait 2 .
.Sh RETURN VALUES
-A 0 value indicates that the call succeeded.
-A \-1 return value indicates an error occurred and
-.Va errno
-is set to indicate the reason.
+.Rv -std _lwp_detach
.Sh ERRORS
-.Bl -tag -width [EINVAL]
+.Bl -tag -width Er
.It Bq Er EINVAL
The LWP is already detached.
.It Bq Er ESRCH
diff --git a/lib/libc/sys/_lwp_getname.2 b/lib/libc/sys/_lwp_getname.2
index 486af3ec0b4..3b032bc892e 100644
--- a/lib/libc/sys/_lwp_getname.2
+++ b/lib/libc/sys/_lwp_getname.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_getname.2,v 1.2 2009/05/18 14:49:35 wiz Exp $
+.\" $NetBSD: _lwp_getname.2,v 1.3 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c)2007 YAMAMOTO Takashi,
.\" All rights reserved.
@@ -44,7 +44,7 @@
.Fn _lwp_getname
gets the descriptive name of the LWP.
It takes the following arguments.
-.Bl -tag -width target
+.Bl -tag -width Fa
.It Fa target
The LWP whose descriptive name will be obtained.
.It Fa name
@@ -56,11 +56,7 @@ in bytes.
.El
.\" ------------------------------------------------------------
.Sh RETURN VALUES
-.Fn _lwp_getname
-returns 0 on success.
-Otherwise, \-1 is returned and
-.Va errno
-is set to indicate the error.
+.Rv -std _lwp_getname
.\" ------------------------------------------------------------
.\".Sh ERRORS
.\" ------------------------------------------------------------
diff --git a/lib/libc/sys/_lwp_kill.2 b/lib/libc/sys/_lwp_kill.2
index 8b75445286d..87f2f72cca7 100644
--- a/lib/libc/sys/_lwp_kill.2
+++ b/lib/libc/sys/_lwp_kill.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_kill.2,v 1.4 2009/06/24 22:19:14 zafer Exp $
+.\" $NetBSD: _lwp_kill.2,v 1.5 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -60,12 +60,9 @@ they will affect all LWPs in the process.
Signals will be posted successfully to suspended LWPs, but will not be
handled further until the LWP has been continued.
.Sh RETURN VALUES
-A 0 value indicates that the call succeeded.
-A \-1 return value indicates an error occurred and
-.Va errno
-is set to indicate the reason.
+.Rv -std _lwp_kill
.Sh ERRORS
-.Bl -tag -width [EINVAL]
+.Bl -tag -width Er
.It Bq Er EINVAL
.Fa sig
is not a valid signal number.
diff --git a/lib/libc/sys/_lwp_park.2 b/lib/libc/sys/_lwp_park.2
index 2076bf6713e..13e4574b8eb 100644
--- a/lib/libc/sys/_lwp_park.2
+++ b/lib/libc/sys/_lwp_park.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_park.2,v 1.12 2019/07/31 23:53:25 pgoyette Exp $
+.\" $NetBSD: _lwp_park.2,v 1.13 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003, 2007, 2017 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -55,7 +55,7 @@ and the time it specifies has passed.
The
.Fa ts
time can be a relative interval to wait if the
-.Ar flags
+.Fa flags
argument does not contain
.Dv TIMER_ABSTIME
or it can be an absolute time.
@@ -125,17 +125,21 @@ If
.Fa unpark
is non-zero, the system will behave as if the following call had been made
before the calling thread begins to wait:
-.Bd -literal
- _lwp_unpark(unpark, unparkhint);
-.Ed
+.Pp
+.Dl _lwp_unpark(unpark, unparkhint);
.Sh RETURN VALUES
+.\" Rv -std _lwp_park
+.\" The "if successful" language in .Rv -std is misleading, but try to
+ \" follow its phrasing as close as possible.
+The
.Fn _lwp_park
-may return a value of 0.
-Otherwise, \-1 is returned and
+.\" XXX: TODO: when? be more precise
+function may return the value of 0.
+Otherwise the value \-1 is returned and the global variable
.Va errno
is set to provide more information.
.Sh ERRORS
-.Bl -tag -width [EINVAL]
+.Bl -tag -width Er
.It Bq Er EALREADY
A request was made to wake the LWP before it began to wait in
the kernel.
diff --git a/lib/libc/sys/_lwp_setname.2 b/lib/libc/sys/_lwp_setname.2
index 969e6f149bf..e557fcf70b9 100644
--- a/lib/libc/sys/_lwp_setname.2
+++ b/lib/libc/sys/_lwp_setname.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_setname.2,v 1.2 2009/05/18 14:50:03 wiz Exp $
+.\" $NetBSD: _lwp_setname.2,v 1.3 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c)2007 YAMAMOTO Takashi,
.\" All rights reserved.
@@ -44,7 +44,7 @@
.Fn _lwp_setname
sets the descriptive name of the LWP.
It takes the following arguments.
-.Bl -tag -width target
+.Bl -tag -width Fa
.It Fa target
The LWP whose descriptive name will be set.
.It Fa name
@@ -56,11 +56,7 @@ The name is used by
when showing LWPs, for example.
.\" ------------------------------------------------------------
.Sh RETURN VALUES
-.Fn _lwp_setname
-returns 0 on success.
-Otherwise, \-1 is returned and
-.Va errno
-is set to indicate the error.
+.Rv -std _lwp_setname
.\" ------------------------------------------------------------
.\".Sh ERRORS
.\" ------------------------------------------------------------
diff --git a/lib/libc/sys/_lwp_suspend.2 b/lib/libc/sys/_lwp_suspend.2
index 0f28e5c162f..a12eb3376a7 100644
--- a/lib/libc/sys/_lwp_suspend.2
+++ b/lib/libc/sys/_lwp_suspend.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_suspend.2,v 1.4 2008/04/30 13:10:51 martin Exp $
+.\" $NetBSD: _lwp_suspend.2,v 1.5 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -59,18 +59,13 @@ Once an LWP is resumed, subsequent calls to
.Fn _lwp_continue
have no effect.
.Sh RETURN VALUES
-Upon successful completion,
-.Fn _lwp_suspend
-and
-.Fn _lwp_continue
-return a value of 0.
-Otherwise, an error code is returned to indicate the error.
+.Rv -std _lwp_continue _lwp_suspend
.Sh ERRORS
.Fn _lwp_suspend
and
.Fn _lwp_continue
will fail if:
-.Bl -tag -width [EDEADLK]
+.Bl -tag -width Er
.It Bq Er ESRCH
No LWP can be found in the current process corresponding to that
specified by
@@ -79,7 +74,7 @@ specified by
.Pp
.Fn _lwp_suspend
will fail if:
-.Bl -tag -width [EDEADLK]
+.Bl -tag -width Er
.It Bq Er EDEADLK
The LWP specified by
.Fa lwp
diff --git a/lib/libc/sys/_lwp_unpark.2 b/lib/libc/sys/_lwp_unpark.2
index 840da0c5a31..f5c16288e45 100644
--- a/lib/libc/sys/_lwp_unpark.2
+++ b/lib/libc/sys/_lwp_unpark.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_unpark.2,v 1.4 2010/11/02 20:49:47 skrll Exp $
+.\" $NetBSD: _lwp_unpark.2,v 1.5 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -57,12 +57,9 @@ for a description of the
.Fa hint
argument.
.Sh RETURN VALUES
-A 0 value indicates that the call succeeded.
-A \-1 return value indicates an error occurred and
-.Va errno
-is set to indicate the reason.
+.Rv -std _lwp_unpark
.Sh ERRORS
-.Bl -tag -width [EINVAL]
+.Bl -tag -width Er
.It Bq Er ESRCH
No LWP can be found in the current process corresponding to that
specified by
diff --git a/lib/libc/sys/_lwp_unpark_all.2 b/lib/libc/sys/_lwp_unpark_all.2
index d08508f8a9a..f88657acac9 100644
--- a/lib/libc/sys/_lwp_unpark_all.2
+++ b/lib/libc/sys/_lwp_unpark_all.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_unpark_all.2,v 1.7 2014/04/08 13:02:14 pooka Exp $
+.\" $NetBSD: _lwp_unpark_all.2,v 1.8 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003, 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -52,16 +52,18 @@ If any of the target LWPs are not currently waiting, those LWPs will return
immediately upon the next call to
.Fn _lwp_park .
.Pp
-The value pointed to by
+The
.Fa ntargets
-specifies the size of the array pointed to by
+argument specifies the size of the array pointed to by
.Fa targets .
+.Pp
If the
.Fa targets
argument is given as
.Dv NULL ,
-the maximum size of the array (expressed
-as the number of entries) is returned.
+the maximum size of the array
+.Pq expressed as the number of entries
+is returned.
.Pp
See
.Xr _lwp_park 2
@@ -69,14 +71,18 @@ for a description of the
.Fa hint
argument.
.Sh RETURN VALUES
+.\" XXX: almsost, but we need the initial "if" clause...
+.\" .Rv -std _lwp_unpark_all
If the maximum size of the
.Fa targets
-array is not being queried, a return of 0 indicates that the call succeeded.
-A \-1 return value indicates an error occurred and
+array is not being queried, the
+.Fn _lwp_unpark_all
+function returns the value 0 if successful;
+otherwise the value \-1 is returned and the global variable
.Va errno
-is set to indicate the reason.
+is set to indicate the error.
.Sh ERRORS
-.Bl -tag -width [EINVAL]
+.Bl -tag -width Er
.It Bq Er EFAULT
The value specified for
.Fa targets
diff --git a/lib/libc/sys/_lwp_wait.2 b/lib/libc/sys/_lwp_wait.2
index 5f2fd21b293..6afd6cf8d87 100644
--- a/lib/libc/sys/_lwp_wait.2
+++ b/lib/libc/sys/_lwp_wait.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_wait.2,v 1.5 2020/02/23 20:41:41 ad Exp $
+.\" $NetBSD: _lwp_wait.2,v 1.6 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003, 2020 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -58,14 +58,11 @@ is not
then it points to the location where the LWP ID of
the exited LWP is stored.
.Sh RETURN VALUES
-Upon successful completion,
-.Fn _lwp_wait
-returns a value of 0.
-Otherwise, an error code is returned to indicate the error.
+.Rv -std _lwp_wait
.Sh ERRORS
.Fn _lwp_wait
will fail if:
-.Bl -tag -width [EDEADLK]
+.Bl -tag -width Er
.It Bq Er ESRCH
No LWP can be found in the current process corresponding to that
specified by
diff --git a/lib/libc/sys/_lwp_wakeup.2 b/lib/libc/sys/_lwp_wakeup.2
index c30c77eae50..bbac980200b 100644
--- a/lib/libc/sys/_lwp_wakeup.2
+++ b/lib/libc/sys/_lwp_wakeup.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: _lwp_wakeup.2,v 1.5 2008/04/30 13:10:51 martin Exp $
+.\" $NetBSD: _lwp_wakeup.2,v 1.6 2022/12/04 16:17:50 uwe Exp $
.\"
.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -47,14 +47,11 @@ state.
Unblocking the LWP does not guarantee that it will make progress; it
may block again as soon as it resumes execution in the kernel.
.Sh RETURN VALUES
-Upon successful completion,
-.Fn _lwp_wakeup
-returns a value of 0.
-Otherwise, an error code is returned to indicate the error.
+.Rt -std _lwp_wakeup
.Sh ERRORS
.Fn _lwp_wakeup
will fail if:
-.Bl -tag -width [ENODEV]
+.Bl -tag -width Er
.It Bq Er ESRCH
No LWP can be found in the current process corresponding to that
specified by