fanotify_init.2, fanotify.7: Document FAN_REPORT_TID

[thirdparty/man-pages.git] / man3 / gethostid.3

diff --git a/man3/gethostid.3 b/man3/gethostid.3
index 7ebb55ff559865a95d463b519bcb6767965dc3b6..4fef906cb82c9b684aab29a9f114260809381bd5 100644 (file)
--- a/man3/gethostid.3
+++ b/man3/gethostid.3
@@ -1,7 +1,9 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
 .\"
+.\" Updated with additions from Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
+.\" Portions Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
 .\" preserved on all copies.
@@ -21,71 +23,118 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
-.\"
-.\" Updated with additions from Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
-.\" Portions Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
+.\" %%%LICENSE_END
 .\"
 .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
-.TH GETHOSTID 3 2008-01-13 "Linux" "Linux Programmer's Manual"
+.TH GETHOSTID 3 2017-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
 gethostid, sethostid \- get or set the unique identifier of the current host
 .SH SYNOPSIS
 .B #include <unistd.h>
-.sp
+.PP
 .B long gethostid(void);
 .br
 .BI "int sethostid(long " hostid );
-.sp
+.PP
 .in -4n
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
 .in
-.sp
+.PP
 .ad l
+.br
+.BR gethostid ():
+.RS 4
+_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
+.\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+.RE
 .BR sethostid ():
-_BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500)
+.nf
+    Since glibc 2.21:
+.\"             commit 266865c0e7b79d4196e2cc393693463f03c90bd8
+        _DEFAULT_SOURCE
+    In glibc 2.19 and 2.20:
+        _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500)
+    Up to and including glibc 2.19:
+        _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500)
+.fi
 .ad b
 .SH DESCRIPTION
 .BR gethostid ()
 and
 .BR sethostid ()
 respectively get or set a unique 32-bit identifier for the current machine.
-The 32-bit identifier is intended to be unique among all Unix systems in
+The 32-bit identifier is intended to be unique among all UNIX systems in
 existence.
 This normally resembles the Internet address for the local
 machine, as returned by
 .BR gethostbyname (3),
 and thus usually never needs to be set.
-
+.PP
 The
 .BR sethostid ()
 call is restricted to the superuser.
-
-The
-.I hostid
-argument is stored in the file
-.IR /etc/hostid .
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 .BR gethostid ()
 returns the 32-bit identifier for the current host as set by
 .BR sethostid ().
-.SH FILES
-.I /etc/hostid
-.SH "CONFORMING TO"
+.PP
+On success,
+.BR sethostid ()
+returns 0; on error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.BR sethostid ()
+can fail with the following errors:
+.TP
+.B EACCES
+The caller did not have permission to write to the file used
+to store the host ID.
+.TP
+.B EPERM
+The calling process's effective user or group ID is not the same
+as its corresponding real ID.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lbw25
+l l l.
+Interface      Attribute       Value
+T{
+.BR gethostid ()
+T}     Thread safety   MT-Safe hostid env locale
+T{
+.BR sethostid ()
+T}     Thread safety   MT-Unsafe const:hostid
+.TE
+.sp 1
+.SH CONFORMING TO
 4.2BSD; these functions were dropped in 4.4BSD.
 SVr4 includes
 .BR gethostid ()
 but not
 .BR sethostid ().
-POSIX.1-2001 specifies
+.PP
+POSIX.1-2001 and POSIX.1-2008 specify
 .BR gethostid ()
 but not
 .BR sethostid ().
 .SH NOTES
+In the glibc implementation, the
+.I hostid
+is stored in the file
+.IR /etc/hostid .
+(In glibc versions before 2.2, the file
+.I /var/adm/hostid
+was used.)
+.\" libc5 used /etc/hostid; libc4 didn't have these functions
+.PP
 In the glibc implementation, if
 .BR gethostid ()
-cannot open
-.IR /etc/hostid ,
+cannot open the file containing the host ID,
 then it obtains the hostname using
 .BR gethostname (2),
 passes that hostname to
@@ -95,6 +144,6 @@ and returns a value obtained by bit-twiddling the IPv4 address.
 (This value may not be unique.)
 .SH BUGS
 It is impossible to ensure that the identifier is globally unique.
-.SH "SEE ALSO"
+.SH SEE ALSO
 .BR hostid (1),
 .BR gethostbyname (3)