Module Name: src
Committed By: uwe
Date: Sun Dec 4 16:17:50 UTC 2022
Modified Files:
src/lib/libc/sys: _lwp_create.2 _lwp_ctl.2 _lwp_detach.2 _lwp_getname.2
_lwp_kill.2 _lwp_park.2 _lwp_setname.2 _lwp_suspend.2 _lwp_unpark.2
_lwp_unpark_all.2 _lwp_wait.2 _lwp_wakeup.2
Log Message:
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.
To generate a diff of this commit:
cvs rdiff -u -r1.10 -r1.11 src/lib/libc/sys/_lwp_create.2
cvs rdiff -u -r1.5 -r1.6 src/lib/libc/sys/_lwp_ctl.2 \
src/lib/libc/sys/_lwp_wait.2 src/lib/libc/sys/_lwp_wakeup.2
cvs rdiff -u -r1.4 -r1.5 src/lib/libc/sys/_lwp_detach.2 \
src/lib/libc/sys/_lwp_kill.2 src/lib/libc/sys/_lwp_suspend.2 \
src/lib/libc/sys/_lwp_unpark.2
cvs rdiff -u -r1.2 -r1.3 src/lib/libc/sys/_lwp_getname.2 \
src/lib/libc/sys/_lwp_setname.2
cvs rdiff -u -r1.12 -r1.13 src/lib/libc/sys/_lwp_park.2
cvs rdiff -u -r1.7 -r1.8 src/lib/libc/sys/_lwp_unpark_all.2
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/sys/_lwp_create.2
diff -u src/lib/libc/sys/_lwp_create.2:1.10 src/lib/libc/sys/_lwp_create.2:1.11
--- src/lib/libc/sys/_lwp_create.2:1.10 Sun Dec 4 11:25:09 2022
+++ src/lib/libc/sys/_lwp_create.2 Sun Dec 4 16:17:50 2022
@@ -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 li
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
Index: src/lib/libc/sys/_lwp_ctl.2
diff -u src/lib/libc/sys/_lwp_ctl.2:1.5 src/lib/libc/sys/_lwp_ctl.2:1.6
--- src/lib/libc/sys/_lwp_ctl.2:1.5 Fri Apr 13 15:14:58 2012
+++ src/lib/libc/sys/_lwp_ctl.2 Sun Dec 4 16:17:50 2022
@@ -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 descri
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
.\" ------------------------------------------------------------
Index: src/lib/libc/sys/_lwp_wait.2
diff -u src/lib/libc/sys/_lwp_wait.2:1.5 src/lib/libc/sys/_lwp_wait.2:1.6
--- src/lib/libc/sys/_lwp_wait.2:1.5 Sun Feb 23 20:41:41 2020
+++ src/lib/libc/sys/_lwp_wait.2 Sun Dec 4 16:17:50 2022
@@ -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
Index: src/lib/libc/sys/_lwp_wakeup.2
diff -u src/lib/libc/sys/_lwp_wakeup.2:1.5 src/lib/libc/sys/_lwp_wakeup.2:1.6
--- src/lib/libc/sys/_lwp_wakeup.2:1.5 Wed Apr 30 13:10:51 2008
+++ src/lib/libc/sys/_lwp_wakeup.2 Sun Dec 4 16:17:50 2022
@@ -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
Index: src/lib/libc/sys/_lwp_detach.2
diff -u src/lib/libc/sys/_lwp_detach.2:1.4 src/lib/libc/sys/_lwp_detach.2:1.5
--- src/lib/libc/sys/_lwp_detach.2:1.4 Wed Apr 30 13:10:51 2008
+++ src/lib/libc/sys/_lwp_detach.2 Sun Dec 4 16:17:50 2022
@@ -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
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
Index: src/lib/libc/sys/_lwp_kill.2
diff -u src/lib/libc/sys/_lwp_kill.2:1.4 src/lib/libc/sys/_lwp_kill.2:1.5
--- src/lib/libc/sys/_lwp_kill.2:1.4 Wed Jun 24 22:19:14 2009
+++ src/lib/libc/sys/_lwp_kill.2 Sun Dec 4 16:17:50 2022
@@ -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.
Index: src/lib/libc/sys/_lwp_suspend.2
diff -u src/lib/libc/sys/_lwp_suspend.2:1.4 src/lib/libc/sys/_lwp_suspend.2:1.5
--- src/lib/libc/sys/_lwp_suspend.2:1.4 Wed Apr 30 13:10:51 2008
+++ src/lib/libc/sys/_lwp_suspend.2 Sun Dec 4 16:17:50 2022
@@ -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
.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
Index: src/lib/libc/sys/_lwp_unpark.2
diff -u src/lib/libc/sys/_lwp_unpark.2:1.4 src/lib/libc/sys/_lwp_unpark.2:1.5
--- src/lib/libc/sys/_lwp_unpark.2:1.4 Tue Nov 2 20:49:47 2010
+++ src/lib/libc/sys/_lwp_unpark.2 Sun Dec 4 16:17:50 2022
@@ -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
Index: src/lib/libc/sys/_lwp_getname.2
diff -u src/lib/libc/sys/_lwp_getname.2:1.2 src/lib/libc/sys/_lwp_getname.2:1.3
--- src/lib/libc/sys/_lwp_getname.2:1.2 Mon May 18 14:49:35 2009
+++ src/lib/libc/sys/_lwp_getname.2 Sun Dec 4 16:17:50 2022
@@ -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
.\" ------------------------------------------------------------
Index: src/lib/libc/sys/_lwp_setname.2
diff -u src/lib/libc/sys/_lwp_setname.2:1.2 src/lib/libc/sys/_lwp_setname.2:1.3
--- src/lib/libc/sys/_lwp_setname.2:1.2 Mon May 18 14:50:03 2009
+++ src/lib/libc/sys/_lwp_setname.2 Sun Dec 4 16:17:50 2022
@@ -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
.\" ------------------------------------------------------------
Index: src/lib/libc/sys/_lwp_park.2
diff -u src/lib/libc/sys/_lwp_park.2:1.12 src/lib/libc/sys/_lwp_park.2:1.13
--- src/lib/libc/sys/_lwp_park.2:1.12 Wed Jul 31 23:53:25 2019
+++ src/lib/libc/sys/_lwp_park.2 Sun Dec 4 16:17:50 2022
@@ -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.
Index: src/lib/libc/sys/_lwp_unpark_all.2
diff -u src/lib/libc/sys/_lwp_unpark_all.2:1.7 src/lib/libc/sys/_lwp_unpark_all.2:1.8
--- src/lib/libc/sys/_lwp_unpark_all.2:1.7 Tue Apr 8 13:02:14 2014
+++ src/lib/libc/sys/_lwp_unpark_all.2 Sun Dec 4 16:17:50 2022
@@ -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 curren
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
