Michael Kerrisk [Fri, 9 Dec 2016 10:22:08 +0000 (11:22 +0100)]
feature_test_macros.7: Improve the text on _REENTRANT/_THREAD_SAFE deprecation
[mtk] I did a little code spelunking and found the following:
1. In glibc 1.09 (tagged 1995-03-02 in the git history),
__USE_REENTRANT, _THREAD_SAFE, and _REENTRANT do not appear.
2. In glibc-1.93 (tagged 1996-08-29 in the git history),
__USE_REENTRANT governs the exposure of some "_r()"
functions from about a dozen header files. However, it is
defined in <features.h> via
#if defined (__USE_GNU) || defined (__USE_MISC)
#define __USE_REENTRANT 1
#endif
_REENTRANT and _THREAD_SAFE solely govern declarations in
<stdio.h>, where they expose declarations of a few "unlocked"
stdio functions and use #define to redirect a few stdio
function names to "locked" versions.
3. THREAD_SAFE and _REENTRANT first appear in the git logs
1996-05-09.
4. About 9 months later, glibc 2.0.1 arrives on 1997-02-04
(timestamp and tarball taken from
https://ftp.gnu.org/gnu/libc/, since there is no tag in the
git history; casual inspection of the logs suggests the
glibc 2.0 release was about a week earlier.
By now we have the following in <features.h>:
#if defined _REENTRANT || defined _THREAD_SAFE
#define __USE_REENTRANT 1
#endif
And _THREAD_SAFE, and _REENTRANT do not appear appear in
other headers. However, by now, __USE_REENTRANT governs only
the declarations of tmpnam_r() and getlogin_r()
In other words, the window of time where _REENTRANT and
_THREAD_SAFE did anything much in glibc was quite short, IIUC.
Cowritten-by: Zack Weinberg <zackw@panix.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Fri, 9 Dec 2016 11:51:23 +0000 (12:51 +0100)]
bind.2, connect.2, getpeername.2, getsockname.2, getsockopt.2: Replace discussion of 'socklen_t' with reference to accept(2)
The discussion of 'socklen_t' editorializes and is repeated
across several pages. Replace it with a reference to accept(2),
where some details about this type are provided.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Pavel Emelyanov [Wed, 7 Dec 2016 13:59:43 +0000 (16:59 +0300)]
sock_diag.7: New page documenting NETLINK_SOCK_DIAG interface
Co-authored-by: Dmitry V. Levin <ldv@altlinux.org> Signed-off-by: Pavel Emelyanov <xemul@virtuozzo.com> Signed-off-by: Dmitry V. Levin <ldv@altlinux.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Tue, 6 Dec 2016 15:23:33 +0000 (16:23 +0100)]
close.2: Further clarify how to treat an error return
Further clarify that an error return should be used only
for diagnostic or remedial purposes.
Lifting Linus's words freely from
http://lkml.iu.edu/hypermail/linux/kernel/0207.2/0409.html
Re: close return value (was Re: [ANNOUNCE] Ext3 vs Reiserfs benchmarks)
Date: Wed Jul 17 2002 - 12:43:57 EST
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Tue, 6 Dec 2016 15:03:51 +0000 (16:03 +0100)]
close.2: Other UNIX implementations also close the FD, even if reporting an error
Looking at some historical source code (mostly from [1]) suggests
that the "close() always closes regardless of error return"
behavior has a long history, predating even POSIX.1-1990.
For example, in SVR4 for x86 (from the file sysvr4.tar.bz2 at
[1]), we see the following:
int
close(uap, rvp)
register struct closea *uap;
rval_t *rvp;
{
file_t *fp;
register int error;
In the above, getf() can return EBADF. The other errors are
returned by closef(), but the file descriptor is deallocated
regardless of errors by setf().
A similar pattern seems to have been preserved into at least late
OpenSolaris days (verified from looking at the initial commit of
the illumos source code). There we find the following in
closeandsetf() (called by close()):
error = closef(fp);
setf(fd, newfp);
return (error);
Looking at the code of closef() in AIX 4.1.3 suggests that, as on
on Linux and FreeBSD, the open file is always released, regardless
of errors.
For Irix, 6.5.5, I'm not sure (the code is not so easy to quickly
read); it may be that it does return errors while leaving the FD
open.
Michael Kerrisk [Tue, 6 Dec 2016 14:09:55 +0000 (15:09 +0100)]
close.2: Rework initial paragraph in NOTES on checking close() errors
As Daniel Wagner noted, saying on the one hand that failing
to check the return value of close() is a "serious error"
seems contradicted by the next paragraph that notes that
the return value should be used for "just diagnostics".
Rework the text to resolve the apparent contradiction.
Reported-by: Daniel Wagner <wagi@monom.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Carlos O'Donell [Mon, 5 Dec 2016 16:09:54 +0000 (11:09 -0500)]
resolv.conf.5: Timeout does not map to resolver API calls
I'm posting this patch to clarify the timeout behaviour because
there have been developers who expect this timeout to mean
something it is not.
The timeout (and by proxy attempts) does not map to resolver API
calls. For example a single call to getent might involve multiple
resolution requests to the resolvers listed in resolv.conf and
each request will use TIMEOUT and be attempted at least ATTEMPT
times. A developer using the resolver API cannot easily compute
any given timeout because the implementation may change e.g. A and
AAAA queries made in parallel. A system administrator uses this
setting to ensure there is a desirable timeout on any request to
any of the nameservers listed in resolv.conf, but no guarantees
exist beyond that.
Reviewed-by: Florian Weimer <fweimer@redhat.com> Signed-off-by: Carlos O'Donell <carlos@redhat.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Mon, 5 Dec 2016 13:23:20 +0000 (14:23 +0100)]
close.2: Further clarify that close() should not be retried after an error
See Linus ancient comments re EINTR in
https://lkml.org/lkml/headers/2005/9/10/129
Date Sat, 10 Sep 2005 12:00:01 -0700 (PDT)
From Linus Torvalds <>
Subject Re: [patch 7/7] uml: retry host close() on EINTR
The FreeBSD 11.0 close() man page says similar:
In case of any error except EBADF, the supplied file
descriptor is deallocated and therefore is no longer valid.
For AIX:
http://publib16.boulder.ibm.com/doc_link/en_US/a_doc_lib/libs/basetrf1/close.htm
If the FileDescriptor parameter refers to a device and the
close subroutine actually results in a device close, and the
device close routine returns an error, the error is returned
to the application. However, the FileDescriptor parameter is
considered closed and it may not be used in any subsequent
calls.
See also:
http://austingroupbugs.net/view.php?id=529
and in particular:
http://austingroupbugs.net/view.php?id=529#c1200
Reported-by: Daniel Wagner <wagi@monom.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>