Debian Codegraph @

upstream/debian-trixie/man3/gethostid.3

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