Hi, Jan Klemkow wrote on Wed, Jan 29, 2014 at 08:44:05PM +0100:
> I've made a little diff to clean up some manpages with references to the > obsoleted functions usleep(1), alarm(3). Actually, i like this diff and would like to commit it, for the following reason: We include pointers in SEE ALSO when they are likely to help readers. That's not the case here. >From section 1 pages, pointers to section 2 and 3 are rarely helpful because readers of section 1 usually look for ready-to-use utilities, not for programming interfaces. Still, i like keeping a very small number of pointers to the main syscalls and library functions used for the implementation because that may help programmers to find the most important code examples more quickly than by wading through /usr/src/. But in sleep(1), this is clearly overdone, and Jan's diff trims it down to a more reasonable level. I might even remove sleep(3) as well, nanosleep(2) points to it anyway, and sleep(1) doesn't even use it. >From sleep(3), a pointer to usleep(3) is no longer helpful. If you are considering to use sleep(3) in your code, you might reconsider and use nanosleep(2) or setitimer(2) instead, when you discover their existence. But it doesn't make sense at all to use usleep(3) instead, that would merely harm portability for no benefit. So why point to it? On the other hand, if you find usleep(3) in old code and wonder what it does, you are looking at the usleep(3) manual in the first place and don't need the pointer either. OK? Ingo > Index: bin/sleep/sleep.1 > =================================================================== > RCS file: /cvs/src/bin/sleep/sleep.1,v > retrieving revision 1.19 > diff -u -p -r1.19 sleep.1 > --- bin/sleep/sleep.1 3 Sep 2010 09:53:20 -0000 1.19 > +++ bin/sleep/sleep.1 29 Jan 2014 19:39:14 -0000 > @@ -109,9 +109,7 @@ done > .Xr at 1 , > .Xr nanosleep 2 , > .Xr setitimer 2 , > -.Xr alarm 3 , > -.Xr sleep 3 , > -.Xr usleep 3 > +.Xr sleep 3 > .Sh STANDARDS > The > .Nm > Index: lib/libc/gen/sleep.3 > =================================================================== > RCS file: /cvs/src/lib/libc/gen/sleep.3,v > retrieving revision 1.14 > diff -u -p -r1.14 sleep.3 > --- lib/libc/gen/sleep.3 18 Jul 2013 10:14:49 -0000 1.14 > +++ lib/libc/gen/sleep.3 29 Jan 2014 19:39:31 -0000 > @@ -70,7 +70,7 @@ slept) in seconds. > .Sh SEE ALSO > .Xr sleep 1 , > .Xr nanosleep 2 , > -.Xr usleep 3 > +.Xr setitimer 2 > .Sh STANDARDS > The > .Fn sleep >
