gen/FreeBSD/gethostname.3

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)gethostname.3       8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/gen/gethostname.3,v 1.17 2007/01/09 00:27:54 imp Exp $
  30 .\"
  31 .Dd August 18, 2003
  32 .Dt GETHOSTNAME 3
  33 .Os
  34 .Sh NAME
  35 .Nm gethostname ,
  36 .Nm sethostname
  37 .Nd get/set name of current host
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In unistd.h
  42 .Ft int
  43 .Fn gethostname "char *name" "size_t namelen"
  44 .Ft int
  45 .Fn sethostname "const char *name" "int namelen"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn gethostname
  49 function
  50 returns the standard host name for the current processor, as
  51 previously set by
  52 .Fn sethostname .
  53 The
  54 .Fa namelen
  55 argument
  56 specifies the size of the
  57 .Fa name
  58 array.
  59 The returned name is null-terminated, unless insufficient space is provided.
  60 .Pp
  61 The
  62 .Fn sethostname
  63 function
  64 sets the name of the host machine to be
  65 .Fa name ,
  66 which has length
  67 .Fa namelen .
  68 This call is restricted to the super-user and
  69 is normally used only when the system is bootstrapped.
  70 .Pp
  71 Host names are limited in length to
  72 .Brq Dv sysconf(_SC_HOST_NAME_MAX)
  73 characters, not including the trailing null, currently 255.
  74 .Sh RETURN VALUES
  75 .Rv -std
  76 .Sh ERRORS
  77 The following errors may be returned by these calls:
  78 .Bl -tag -width Er
  79 .It Bq Er EFAULT
  80 The
  81 .Fa name
  82 or
  83 .Fa namelen
  84 argument gave an
  85 invalid address.
  86 .It Bq Er ENAMETOOLONG
  87 The current host name is longer than
  88 .Fa namelen .
  89 (For
  90 .Fn gethostname
  91 only.)
  92 .It Bq Er EPERM
  93 The caller tried to set the host name and was not the super-user.
  94 .El
  95 .Sh SEE ALSO
  96 .Xr sysconf 3 ,
  97 .Xr sysctl 3
  98 .Sh STANDARDS
  99 The
 100 .Fn gethostname
 101 function conforms to
 102 .St -p1003.1-2001 .
 103 Callers should be aware that
 104 .Brq Dv sysconf(_SC_HOST_NAME_MAX)
 105 may be variable or infinite, but is guaranteed to be no less than
 106 .Brq Dv _POSIX_HOST_NAME_MAX .
 107 On older systems, this limit was defined in the non-standard header
 108 .In sys/param.h
 109 as
 110 .Dv MAXHOSTNAMELEN ,
 111 and counted the terminating null.
 112 The
 113 .Fn sethostname
 114 function and the error returns for
 115 .Fn gethostname
 116 are not standardized.
 117 .Sh HISTORY
 118 The
 119 .Fn gethostname
 120 function appeared in
 121 .Bx 4.2 .
 122 The
 123 .Fa namelen
 124 argument to
 125 .Fn gethostname
 126 was changed to
 127 .Vt size_t
 128 in
 129 .Fx 5.2
 130 for alignment with
 131 .St -p1003.1-2001 .