Debian Codegraph @

upstream/debian-trixie/man2/gethostname.2

raw
1 .\" Copyright 1993 Rickard E. Faith ([email protected])
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\" Modified 1995-07-22 by Michael Chastain <[email protected]>:
6 .\" 'gethostname' is real system call on Linux/Alpha.
7 .\" Modified 1997-01-31 by Eric S. Raymond <[email protected]>
8 .\" Modified 2000-06-04, 2001-12-15 by aeb
9 .\" Modified 2004-06-17 by mtk
10 .\" Modified 2008-11-27 by mtk
11 .\"
12 .TH gethostname 2 2024-05-02 "Linux man-pages 6.9.1"
13 .SH NAME
14 gethostname, sethostname \- get/set hostname
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <unistd.h>
21 .P
22 .BI "int gethostname(char *" name ", size_t " len );
23 .BI "int sethostname(const char *" name ", size_t " len );
24 .fi
25 .P
26 .RS -4
27 Feature Test Macro Requirements for glibc (see
28 .BR feature_test_macros (7)):
29 .RE
30 .P
31 .BR gethostname ():
32 .nf
33 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
34 || /* glibc 2.19 and earlier */ _BSD_SOURCE
35 .\" The above is something of a simplification
36 .\" also before glibc 2.3 there was a bit churn
37 .fi
38 .P
39 .BR sethostname ():
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 These system calls are used to access or to change the system hostname.
51 More precisely, they operate on the hostname associated with the calling
52 process's UTS namespace.
53 .P
54 .BR sethostname ()
55 sets the hostname to the value given in the character array
56 .IR name .
57 The
58 .I len
59 argument specifies the number of bytes in
60 .IR name .
61 (Thus,
62 .I name
63 does not require a terminating null byte.)
64 .P
65 .BR gethostname ()
66 returns the null-terminated hostname in the character array
67 .IR name ,
68 which has a length of
69 .I len
70 bytes.
71 If the null-terminated hostname is too large to fit,
72 then the name is truncated, and no error is returned (but see NOTES below).
73 POSIX.1 says that if such truncation occurs,
74 then it is unspecified whether the returned buffer
75 includes a terminating null byte.
76 .SH RETURN VALUE
77 On success, zero is returned.
78 On error, \-1 is returned, and
79 .I errno
80 is set to indicate the error.
81 .SH ERRORS
82 .TP
83 .B EFAULT
84 .I name
85 is an invalid address.
86 .TP
87 .B EINVAL
88 .I len
89 is negative
90 .\" Can't occur for gethostbyname() wrapper, since 'len' has an
91 .\" unsigned type; can occur for the underlying system call.
92 or, for
93 .BR sethostname (),
94 .I len
95 is larger than the maximum allowed size.
96 .TP
97 .B ENAMETOOLONG
98 .RB "(glibc " gethostname ())
99 .I len
100 is smaller than the actual size.
101 (Before glibc 2.1, glibc uses
102 .B EINVAL
103 for this case.)
104 .TP
105 .B EPERM
106 For
107 .BR sethostname (),
108 the caller did not have the
109 .B CAP_SYS_ADMIN
110 capability in the user namespace associated with its UTS namespace (see
111 .BR namespaces (7)).
112 .SH VERSIONS
113 SUSv2 guarantees that "Host names are limited to 255 bytes".
114 POSIX.1 guarantees that "Host names (not including
115 the terminating null byte) are limited to
116 .B HOST_NAME_MAX
117 bytes".
118 On Linux,
119 .B HOST_NAME_MAX
120 is defined with the value 64, which has been the limit since Linux 1.0
121 (earlier kernels imposed a limit of 8 bytes).
122 .SS C library/kernel differences
123 The GNU C library does not employ the
124 .BR gethostname ()
125 system call; instead, it implements
126 .BR gethostname ()
127 as a library function that calls
128 .BR uname (2)
129 and copies up to
130 .I len
131 bytes from the returned
132 .I nodename
133 field into
134 .IR name .
135 Having performed the copy, the function then checks if the length of the
136 .I nodename
137 was greater than or equal to
138 .IR len ,
139 and if it is, then the function returns \-1 with
140 .I errno
141 set to
142 .BR ENAMETOOLONG ;
143 in this case, a terminating null byte is not included in the returned
144 .IR name .
145 .SH STANDARDS
146 .TP
147 .BR gethostname ()
148 POSIX.1-2008.
149 .TP
150 .BR sethostname ()
151 None.
152 .SH HISTORY
153 SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
154 POSIX.1-2001 and POSIX.1-2008 specify
155 .BR gethostname ()
156 but not
157 .BR sethostname ().
158 .P
159 Versions of glibc before glibc 2.2
160 .\" At least glibc 2.0 and glibc 2.1, older versions not checked
161 handle the case where the length of the
162 .I nodename
163 was greater than or equal to
164 .I len
165 differently: nothing is copied into
166 .I name
167 and the function returns \-1 with
168 .I errno
169 set to
170 .BR ENAMETOOLONG .
171 .SH SEE ALSO
172 .BR hostname (1),
173 .BR getdomainname (2),
174 .BR setdomainname (2),
175 .BR uname (2),
176 .BR uts_namespaces (7)