man2/gethostname.2

   1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified 1995-07-22 by Michael Chastain <mec@duracef.shout.net>:
   6 .\"   'gethostname' is real system call on Linux/Alpha.
   7 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
   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 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  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 .PP
  22 .BI "int gethostname(char *" name ", size_t " len );
  23 .BI "int sethostname(const char *" name ", size_t " len );
  24 .fi
  25 .PP
  26 .RS -4
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .RE
  30 .PP
  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 in glibc before 2.3 there was a bit churn
  37 .fi
  38 .PP
  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 .PP
  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 .PP
  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 version 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 STANDARDS
 113 SVr4, 4.4BSD  (these interfaces first appeared in 4.2BSD).
 114 POSIX.1-2001 and POSIX.1-2008 specify
 115 .BR gethostname ()
 116 but not
 117 .BR sethostname ().
 118 .SH NOTES
 119 SUSv2 guarantees that "Host names are limited to 255 bytes".
 120 POSIX.1 guarantees that "Host names (not including
 121 the terminating null byte) are limited to
 122 .B HOST_NAME_MAX
 123 bytes".
 124 On Linux,
 125 .B HOST_NAME_MAX
 126 is defined with the value 64, which has been the limit since Linux 1.0
 127 (earlier kernels imposed a limit of 8 bytes).
 128 .SS C library/kernel differences
 129 The GNU C library does not employ the
 130 .BR gethostname ()
 131 system call; instead, it implements
 132 .BR gethostname ()
 133 as a library function that calls
 134 .BR uname (2)
 135 and copies up to
 136 .I len
 137 bytes from the returned
 138 .I nodename
 139 field into
 140 .IR name .
 141 Having performed the copy, the function then checks if the length of the
 142 .I nodename
 143 was greater than or equal to
 144 .IR len ,
 145 and if it is, then the function returns \-1 with
 146 .I errno
 147 set to
 148 .BR ENAMETOOLONG ;
 149 in this case, a terminating null byte is not included in the returned
 150 .IR name .
 151 .PP
 152 Versions of glibc before 2.2
 153 .\" At least glibc 2.0 and 2.1, older versions not checked
 154 handle the case where the length of the
 155 .I nodename
 156 was greater than or equal to
 157 .I len
 158 differently: nothing is copied into
 159 .I name
 160 and the function returns \-1 with
 161 .I errno
 162 set to
 163 .BR ENAMETOOLONG .
 164 .SH SEE ALSO
 165 .BR hostname (1),
 166 .BR getdomainname (2),
 167 .BR setdomainname (2),
 168 .BR uname (2),
 169 .BR uts_namespaces (7)