manual/LDP_man-pages/original/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 2008-11-27 "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 .BR gethostname ():
  49 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
  50 .br
  51 .BR sethostname ():
  52 _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500)
  53 .ad b
  54 .SH DESCRIPTION
  55 These system calls are used to access or to change the hostname of the
  56 current processor.
  57
  58 .BR sethostname ()
  59 sets the hostname to the value given in the character array
  60 .IR name .
  61 The
  62 .I len
  63 argument specifies the number of bytes in
  64 .IR name .
  65 (Thus,
  66 .I name
  67 does not require a terminating null byte.)
  68
  69 .BR gethostname ()
  70 returns the null-terminated hostname in the character array
  71 .IR name ,
  72 which has a length of
  73 .I len
  74 bytes.
  75 If the null-terminated hostname is too large to fit,
  76 then the name is truncated, and no error is returned (but see NOTES below).
  77 POSIX.1-2001 says that if such truncation occurs,
  78 then it is unspecified whether the returned buffer
  79 includes a terminating null byte.
  80 .SH "RETURN VALUE"
  81 On success, zero is returned.
  82 On error, \-1 is returned, and
  83 .I errno
  84 is set appropriately.
  85 .SH ERRORS
  86 .TP
  87 .B EFAULT
  88 .I name
  89 is an invalid address.
  90 .TP
  91 .B EINVAL
  92 .I len
  93 is negative
  94 .\" Can't occur for gethostbyname() wrapper, since 'len' has an
  95 .\" unsigned type; can occur for the underlying system call.
  96 or, for
  97 .BR sethostname (),
  98 .I len
  99 is larger than the maximum allowed size.
 100 .TP
 101 .B ENAMETOOLONG
 102 .RB "(glibc " gethostname ())
 103 .I len
 104 is smaller than the actual size.
 105 (Before version 2.1, glibc uses
 106 .BR EINVAL
 107 for this case.)
 108 .TP
 109 .B EPERM
 110 For
 111 .BR sethostname (),
 112 the caller did not have the
 113 .B CAP_SYS_ADMIN
 114 capability.
 115 .SH "CONFORMING TO"
 116 SVr4, 4.4BSD  (these interfaces first appeared in 4.2BSD).
 117 POSIX.1-2001 specifies
 118 .BR gethostname ()
 119 but not
 120 .BR sethostname ().
 121 .SH NOTES
 122 SUSv2 guarantees that "Host names are limited to 255 bytes".
 123 POSIX.1-2001 guarantees that "Host names (not including
 124 the terminating null byte) are limited to
 125 .B HOST_NAME_MAX
 126 bytes".
 127 On Linux,
 128 .B HOST_NAME_MAX
 129 is defined with the value 64, which has been the limit since Linux 1.0
 130 (earlier kernels imposed a limit of 8 bytes).
 131 .SS Glibc Notes
 132 The GNU C library does not employ the
 133 .BR gethostname ()
 134 system call; instead, it implements
 135 .BR gethostname ()
 136 as a library function that calls
 137 .BR uname (2)
 138 and copies up to
 139 .I len
 140 bytes from the returned
 141 .I nodename
 142 field into
 143 .IR name .
 144 Having performed the copy, the function then checks if the length of the
 145 .I nodename
 146 was greater than or equal to
 147 .IR len ,
 148 and if it is, then the function returns \-1 with
 149 .I errno
 150 set to
 151 .BR ENAMETOOLONG ;
 152 in this case, no null-terminator is included in the returned
 153 .IR name .
 154
 155 Versions of glibc before 2.2
 156 .\" At least glibc 2.0 and 2.1, older versions not checked
 157 handle the case where the length of the
 158 .I nodename
 159 was greater than or equal to
 160 .I len
 161 differently: nothing is copied into
 162 .I name
 163 and the function returns \-1 with
 164 .I errno
 165 set to
 166 .BR ENAMETOOLONG .
 167 .SH "SEE ALSO"
 168 .BR getdomainname (2),
 169 .BR setdomainname (2),
 170 .BR uname (2)