Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src/lib/libc/sys Tweak markup in _lwp_*(2) manual pages
details: https://anonhg.NetBSD.org/src/rev/958996211e17
branches: trunk
changeset: 372516:958996211e17
user: uwe <uwe%NetBSD.org@localhost>
date: Sun Dec 04 16:17:50 2022 +0000
description:
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:
lib/libc/sys/_lwp_create.2 | 27 ++++++++++++++-------------
lib/libc/sys/_lwp_ctl.2 | 23 +++++++++++------------
lib/libc/sys/_lwp_detach.2 | 9 +++------
lib/libc/sys/_lwp_getname.2 | 10 +++-------
lib/libc/sys/_lwp_kill.2 | 9 +++------
lib/libc/sys/_lwp_park.2 | 20 ++++++++++++--------
lib/libc/sys/_lwp_setname.2 | 10 +++-------
lib/libc/sys/_lwp_suspend.2 | 13 ++++---------
lib/libc/sys/_lwp_unpark.2 | 9 +++------
lib/libc/sys/_lwp_unpark_all.2 | 24 +++++++++++++++---------
lib/libc/sys/_lwp_wait.2 | 9 +++------
lib/libc/sys/_lwp_wakeup.2 | 9 +++------
12 files changed, 77 insertions(+), 95 deletions(-)
diffs (truncated from 452 to 300 lines):
diff -r d7da74e3622c -r 958996211e17 lib/libc/sys/_lwp_create.2
--- a/lib/libc/sys/_lwp_create.2 Sun Dec 04 11:25:08 2022 +0000
+++ b/lib/libc/sys/_lwp_create.2 Sun Dec 04 16:17:50 2022 +0000
@@ -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 @@
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 @@
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 @@
.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 -r d7da74e3622c -r 958996211e17 lib/libc/sys/_lwp_ctl.2
--- a/lib/libc/sys/_lwp_ctl.2 Sun Dec 04 11:25:08 2022 +0000
+++ b/lib/libc/sys/_lwp_ctl.2 Sun Dec 04 16:17:50 2022 +0000
@@ -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 @@
.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 @@
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 @@
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 @@
.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 -r d7da74e3622c -r 958996211e17 lib/libc/sys/_lwp_detach.2
--- a/lib/libc/sys/_lwp_detach.2 Sun Dec 04 11:25:08 2022 +0000
+++ b/lib/libc/sys/_lwp_detach.2 Sun Dec 04 16:17:50 2022 +0000
@@ -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 @@
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 -r d7da74e3622c -r 958996211e17 lib/libc/sys/_lwp_getname.2
--- a/lib/libc/sys/_lwp_getname.2 Sun Dec 04 11:25:08 2022 +0000
+++ b/lib/libc/sys/_lwp_getname.2 Sun Dec 04 16:17:50 2022 +0000
@@ -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 @@
.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 -r d7da74e3622c -r 958996211e17 lib/libc/sys/_lwp_kill.2
--- a/lib/libc/sys/_lwp_kill.2 Sun Dec 04 11:25:08 2022 +0000
+++ b/lib/libc/sys/_lwp_kill.2 Sun Dec 04 16:17:50 2022 +0000
@@ -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 @@
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 -r d7da74e3622c -r 958996211e17 lib/libc/sys/_lwp_park.2
--- a/lib/libc/sys/_lwp_park.2 Sun Dec 04 11:25:08 2022 +0000
+++ b/lib/libc/sys/_lwp_park.2 Sun Dec 04 16:17:50 2022 +0000
@@ -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 @@
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 @@
.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 -r d7da74e3622c -r 958996211e17 lib/libc/sys/_lwp_setname.2
--- a/lib/libc/sys/_lwp_setname.2 Sun Dec 04 11:25:08 2022 +0000
+++ b/lib/libc/sys/_lwp_setname.2 Sun Dec 04 16:17:50 2022 +0000
@@ -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 @@
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 -r d7da74e3622c -r 958996211e17 lib/libc/sys/_lwp_suspend.2
--- a/lib/libc/sys/_lwp_suspend.2 Sun Dec 04 11:25:08 2022 +0000
+++ b/lib/libc/sys/_lwp_suspend.2 Sun Dec 04 16:17:50 2022 +0000
@@ -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 @@
.Fn _lwp_continue
have no effect.
.Sh RETURN VALUES
-Upon successful completion,
-.Fn _lwp_suspend
-and
-.Fn _lwp_continue
-return a value of 0.
Home |
Main Index |
Thread Index |
Old Index