man2/gethostname.2

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