I think this could use some sprucing. NAME
- "stop until signal" -> "wait for a signal" Feels more natural to me. DESCRIPTION - It's "the calling thread" that blocks, not "a process". - Nothing is "forced". - It "blocks", it doesn't "pause". Saying pause(3) "pauses" is too circular. - No need to enumerate the ways a signal can be delivered. That is better left to other manpages. Nix kill(2) and setitimer(2) from the DESCRIPTION. - No need to mention that we don't return until the signal handler returns either, that's just basic signal(3) stuff. - Should we explicitly mention the underlying implementation system calls or not? I'm unsure. RETURN VALUES - Pull ERRORS into this section. No need to put the one error in a .Bl/.El, we can just mention it inline. SEE ALSO - Nix select(2) and setitimer(2), they aren't directly relevant. - Add sigprocmask(2) and signal(3). They are very relevant. HISTORY - We still have sigpause(3) and sigblock(3) in userspace. Should we .Xr them? They aren't systems calls anymore, but they were at that time. Unsure what to do here. Index: pause.3 =================================================================== RCS file: /cvs/src/lib/libc/gen/pause.3,v retrieving revision 1.16 diff -u -p -r1.16 pause.3 --- pause.3 9 Nov 2022 06:48:29 -0000 1.16 +++ pause.3 9 Nov 2022 16:44:33 -0000 @@ -32,7 +32,7 @@ .Os .Sh NAME .Nm pause -.Nd stop until signal +.Nd wait for a signal .Sh SYNOPSIS .In unistd.h .Ft int @@ -40,40 +40,30 @@ .Sh DESCRIPTION .Bf -symbolic .Fn pause -is made obsolete by +is obsoleted by .Xr sigsuspend 2 . .Ef .Pp -The .Fn pause -function forces a process to pause until a signal is received from either the -.Xr kill 2 -function or an interval timer -(see -.Xr setitimer 2 ) . +blocks the calling thread until it receives an unmasked signal. .Pp -Upon termination of a signal handler started during a -.Fn pause , -the +On +.Ox , .Fn pause -call will return. +is implemented with +.Xr sigsuspend 2 . .Sh RETURN VALUES -Always returns \-1. -.Sh ERRORS -The +On receipt of a signal, .Fn pause -function may set the global variable +returns \-1 and sets .Va errno -to the following error: -.Bl -tag -width Er -.It Bq Er EINTR -The call was interrupted. -.El +to +.Er EINTR . .Sh SEE ALSO .Xr kill 2 , -.Xr select 2 , -.Xr setitimer 2 , -.Xr sigsuspend 2 +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr signal 3 .Sh HISTORY A .Fn pause @@ -82,15 +72,16 @@ system call first appeared outside of Be tape for .At v6 . It was first officially released with PWB/UNIX 1.0. -It was reimplemented as a wrapper around the -.Fn sigpause -and -.Fn sigblock -system calls in -.Bx 4.2 , -and around the -.Xr sigsuspend 2 +In +.Bx 4.2 +it was moved to userspace and reimplemented with +.Xr sigpause 3 and +.Xr sigblock 3 . +In +.Bx 4.3 Reno +it was reimplemented yet again, +this time with .Xr sigprocmask 2 -system calls in -.Bx 4.3 Reno . +and +.Xr sigsuspend 2 .
