diff options
| author | uwe <uwe@NetBSD.org> | 2022-12-04 16:17:50 +0000 |
|---|---|---|
| committer | uwe <uwe@NetBSD.org> | 2022-12-04 16:17:50 +0000 |
| commit | 659700f404cfdab81bd8f2ea58e606b3b2004fba (patch) | |
| tree | 2488d63c227c61826bec23ab04d0b8b3ded8730e /lib/libc/sys | |
| parent | 1f8089d08cef16ee99c9b865ccf7d37c7c24305f (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.2 | 27 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_ctl.2 | 23 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_detach.2 | 9 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_getname.2 | 10 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_kill.2 | 9 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_park.2 | 20 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_setname.2 | 10 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_suspend.2 | 13 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_unpark.2 | 9 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_unpark_all.2 | 24 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_wait.2 | 9 | ||||
| -rw-r--r-- | lib/libc/sys/_lwp_wakeup.2 | 9 |
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 |
