1 files changed, 149 insertions, 0 deletions
diff --git a/man/man3/gethostid.3 b/man/man3/gethostid.3
new file mode 100644
index 000000000..daaaf548a
--- /dev/null
+++ b/man/man3/gethostid.3
@@ -0,0 +1,149 @@
+'\" t
+.\" 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>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
+.TH gethostid 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+gethostid, sethostid \- get or set the unique identifier of the current host
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.B long gethostid(void);
+.BI "int sethostid(long " hostid );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR gethostid ():
+.nf
+    Since glibc 2.20:
+        _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500
+.\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+    Up to and including glibc 2.19:
+        _BSD_SOURCE || _XOPEN_SOURCE >= 500
+.\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+.fi
+.P
+.BR sethostid ():
+.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
+.SH DESCRIPTION
+.BR gethostid ()
+and
+.BR sethostid ()
+respectively get or set a unique 32-bit identifier for the current machine.
+The 32-bit identifier was 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.
+.P
+The
+.BR sethostid ()
+call is restricted to the superuser.
+.SH RETURN VALUE
+.BR gethostid ()
+returns the 32-bit identifier for the current host as set by
+.BR sethostid ().
+.P
+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 lbx
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR gethostid ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Safe hostid env locale
+T}
+T{
+.na
+.nh
+.BR sethostid ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe const:hostid
+T}
+.TE
+.SH VERSIONS
+In the glibc implementation, the
+.I hostid
+is stored in the file
+.IR /etc/hostid .
+(Before glibc 2.2, the file
+.I /var/adm/hostid
+was used.)
+.\" libc5 used /etc/hostid; libc4 didn't have these functions
+.P
+In the glibc implementation, if
+.BR gethostid ()
+cannot open the file containing the host ID,
+then it obtains the hostname using
+.BR gethostname (2),
+passes that hostname to
+.BR gethostbyname_r (3)
+in order to obtain the host's IPv4 address,
+and returns a value obtained by bit-twiddling the IPv4 address.
+(This value may not be unique.)
+.SH STANDARDS
+.TP
+.BR gethostid ()
+POSIX.1-2008.
+.TP
+.BR sethostid ()
+None.
+.SH HISTORY
+4.2BSD; dropped in 4.4BSD.
+SVr4 and POSIX.1-2001 include
+.BR gethostid ()
+but not
+.BR sethostid ().
+.SH BUGS
+It is impossible to ensure that the identifier is globally unique.
+.SH SEE ALSO
+.BR hostid (1),
+.BR gethostbyname (3)