man3/gethostid.3

   1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   2 .\"
   3 .\" Updated with additions from Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
   4 .\" Portions Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
   9 .TH gethostid 3 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 gethostid, sethostid \- get or set the unique identifier of the current host
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <unistd.h>
  18 .PP
  19 .B long gethostid(void);
  20 .BI "int sethostid(long " hostid );
  21 .fi
  22 .PP
  23 .RS -4
  24 Feature Test Macro Requirements for glibc (see
  25 .BR feature_test_macros (7)):
  26 .RE
  27 .PP
  28 .BR gethostid ():
  29 .nf
  30     Since glibc 2.20:
  31         _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500
  32 .\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  33     Up to and including glibc 2.19:
  34         _BSD_SOURCE || _XOPEN_SOURCE >= 500
  35 .\"        || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  36 .fi
  37 .PP
  38 .BR sethostid ():
  39 .nf
  40     Since glibc 2.21:
  41 .\"             commit 266865c0e7b79d4196e2cc393693463f03c90bd8
  42         _DEFAULT_SOURCE
  43     In glibc 2.19 and 2.20:
  44         _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
  45     Up to and including glibc 2.19:
  46         _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
  47 .fi
  48 .SH DESCRIPTION
  49 .BR gethostid ()
  50 and
  51 .BR sethostid ()
  52 respectively get or set a unique 32-bit identifier for the current machine.
  53 The 32-bit identifier was intended to be unique among all UNIX systems in
  54 existence.
  55 This normally resembles the Internet address for the local
  56 machine, as returned by
  57 .BR gethostbyname (3),
  58 and thus usually never needs to be set.
  59 .PP
  60 The
  61 .BR sethostid ()
  62 call is restricted to the superuser.
  63 .SH RETURN VALUE
  64 .BR gethostid ()
  65 returns the 32-bit identifier for the current host as set by
  66 .BR sethostid ().
  67 .PP
  68 On success,
  69 .BR sethostid ()
  70 returns 0; on error, \-1 is returned, and
  71 .I errno
  72 is set to indicate the error.
  73 .SH ERRORS
  74 .BR sethostid ()
  75 can fail with the following errors:
  76 .TP
  77 .B EACCES
  78 The caller did not have permission to write to the file used
  79 to store the host ID.
  80 .TP
  81 .B EPERM
  82 The calling process's effective user or group ID is not the same
  83 as its corresponding real ID.
  84 .SH ATTRIBUTES
  85 For an explanation of the terms used in this section, see
  86 .BR attributes (7).
  87 .ad l
  88 .nh
  89 .TS
  90 allbox;
  91 lb lb lbx
  92 l l l.
  93 Interface       Attribute       Value
  94 T{
  95 .BR gethostid ()
  96 T}      Thread safety   T{
  97 MT-Safe hostid env locale
  98 T}
  99 T{
 100 .BR sethostid ()
 101 T}      Thread safety   T{
 102 MT-Unsafe const:hostid
 103 T}
 104 .TE
 105 .hy
 106 .ad
 107 .sp 1
 108 .SH STANDARDS
 109 4.2BSD; these functions were dropped in 4.4BSD.
 110 SVr4 includes
 111 .BR gethostid ()
 112 but not
 113 .BR sethostid ().
 114 .PP
 115 POSIX.1-2001 and POSIX.1-2008 specify
 116 .BR gethostid ()
 117 but not
 118 .BR sethostid ().
 119 .SH NOTES
 120 In the glibc implementation, the
 121 .I hostid
 122 is stored in the file
 123 .IR /etc/hostid .
 124 (In glibc versions before 2.2, the file
 125 .I /var/adm/hostid
 126 was used.)
 127 .\" libc5 used /etc/hostid; libc4 didn't have these functions
 128 .PP
 129 In the glibc implementation, if
 130 .BR gethostid ()
 131 cannot open the file containing the host ID,
 132 then it obtains the hostname using
 133 .BR gethostname (2),
 134 passes that hostname to
 135 .BR gethostbyname_r (3)
 136 in order to obtain the host's IPv4 address,
 137 and returns a value obtained by bit-twiddling the IPv4 address.
 138 (This value may not be unique.)
 139 .SH BUGS
 140 It is impossible to ensure that the identifier is globally unique.
 141 .SH SEE ALSO
 142 .BR hostid (1),
 143 .BR gethostbyname (3)