| blob | 3c7935b0d93fec57957d8b22a894e3e2ecb10011 |
1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
2 .\"
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
7 .\"
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
12 .\"
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
19 .\" professionally.
20 .\"
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" %%%LICENSE_END
24 .\"
25 .\" Modified 1995-07-22 by Michael Chastain <mec@duracef.shout.net>:
26 .\" 'gethostname' is real system call on Linux/Alpha.
27 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
28 .\" Modified 2000-06-04, 2001-12-15 by aeb
29 .\" Modified 2004-06-17 by mtk
30 .\" Modified 2008-11-27 by mtk
31 .\"
32 .TH GETHOSTNAME 2 2021-03-22 "Linux" "Linux Programmer's Manual"
33 .SH NAME
34 gethostname, sethostname \- get/set hostname
35 .SH SYNOPSIS
36 .nf
37 .B #include <unistd.h>
38 .PP
39 .BI "int gethostname(char *" name ", size_t " len );
40 .BI "int sethostname(const char *" name ", size_t " len );
41 .fi
42 .PP
43 .RS -4
44 Feature Test Macro Requirements for glibc (see
45 .BR feature_test_macros (7)):
46 .RE
47 .PP
48 .BR gethostname ():
49 .nf
50 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
51 || /* Glibc 2.19 and earlier */ _BSD_SOURCE
52 .\" The above is something of a simplification
53 .\" also in glibc before 2.3 there was a bit churn
54 .fi
55 .PP
56 .BR sethostname ():
57 .nf
58 Since glibc 2.21:
59 .\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8
60 _DEFAULT_SOURCE
61 In glibc 2.19 and 2.20:
62 _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
63 Up to and including glibc 2.19:
64 _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
65 .fi
66 .SH DESCRIPTION
67 These system calls are used to access or to change the system hostname.
68 More precisely, they operate on the hostname associated with the calling
69 process's UTS namespace.
70 .PP
71 .BR sethostname ()
72 sets the hostname to the value given in the character array
73 .IR name .
74 The
75 .I len
76 argument specifies the number of bytes in
77 .IR name .
78 (Thus,
79 .I name
80 does not require a terminating null byte.)
81 .PP
82 .BR gethostname ()
83 returns the null-terminated hostname in the character array
84 .IR name ,
85 which has a length of
86 .I len
87 bytes.
88 If the null-terminated hostname is too large to fit,
89 then the name is truncated, and no error is returned (but see NOTES below).
90 POSIX.1 says that if such truncation occurs,
91 then it is unspecified whether the returned buffer
92 includes a terminating null byte.
93 .SH RETURN VALUE
94 On success, zero is returned.
95 On error, \-1 is returned, and
96 .I errno
97 is set to indicate the error.
98 .SH ERRORS
99 .TP
100 .B EFAULT
101 .I name
102 is an invalid address.
103 .TP
104 .B EINVAL
105 .I len
106 is negative
107 .\" Can't occur for gethostbyname() wrapper, since 'len' has an
108 .\" unsigned type; can occur for the underlying system call.
109 or, for
110 .BR sethostname (),
111 .I len
112 is larger than the maximum allowed size.
113 .TP
114 .B ENAMETOOLONG
115 .RB "(glibc " gethostname ())
116 .I len
117 is smaller than the actual size.
118 (Before version 2.1, glibc uses
119 .BR EINVAL
120 for this case.)
121 .TP
122 .B EPERM
123 For
124 .BR sethostname (),
125 the caller did not have the
126 .B CAP_SYS_ADMIN
127 capability in the user namespace associated with its UTS namespace (see
128 .BR namespaces (7)).
129 .SH CONFORMING TO
130 SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD).
131 POSIX.1-2001 and POSIX.1-2008 specify
132 .BR gethostname ()
133 but not
134 .BR sethostname ().
135 .SH NOTES
136 SUSv2 guarantees that "Host names are limited to 255 bytes".
137 POSIX.1 guarantees that "Host names (not including
138 the terminating null byte) are limited to
139 .B HOST_NAME_MAX
140 bytes".
141 On Linux,
142 .B HOST_NAME_MAX
143 is defined with the value 64, which has been the limit since Linux 1.0
144 (earlier kernels imposed a limit of 8 bytes).
145 .SS C library/kernel differences
146 The GNU C library does not employ the
147 .BR gethostname ()
148 system call; instead, it implements
149 .BR gethostname ()
150 as a library function that calls
151 .BR uname (2)
152 and copies up to
153 .I len
154 bytes from the returned
155 .I nodename
156 field into
157 .IR name .
158 Having performed the copy, the function then checks if the length of the
159 .I nodename
160 was greater than or equal to
161 .IR len ,
162 and if it is, then the function returns \-1 with
163 .I errno
164 set to
165 .BR ENAMETOOLONG ;
166 in this case, a terminating null byte is not included in the returned
167 .IR name .
168 .PP
169 Versions of glibc before 2.2
170 .\" At least glibc 2.0 and 2.1, older versions not checked
171 handle the case where the length of the
172 .I nodename
173 was greater than or equal to
174 .I len
175 differently: nothing is copied into
176 .I name
177 and the function returns \-1 with
178 .I errno
179 set to
180 .BR ENAMETOOLONG .
181 .SH SEE ALSO
182 .BR hostname (1),
183 .BR getdomainname (2),
184 .BR setdomainname (2),
185 .BR uname (2),
186 .BR uts_namespaces (7)