usr/src/man/man3c/gethostname.3c

   1 '\" te
   2 .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
   3 .\" Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.  Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
   4 .TH GETHOSTNAME 3C "Feb 7, 2015"
   5 .SH NAME
   6 gethostname, sethostname \- get or set name of current host
   7 .SH SYNOPSIS
   8 .LP
   9 .nf
  10 #include <unistd.h>
  11
  12 \fBint\fR \fBgethostname\fR(\fBchar *\fR\fIname\fR, \fBint\fR \fInamelen\fR);
  13 .fi
  14
  15 .LP
  16 .nf
  17 \fBint\fR \fBsethostname\fR(\fBchar *\fR\fIname\fR, \fBint\fR \fInamelen\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .LP
  22 The \fBgethostname()\fR function returns the standard host name for the current
  23 machine, as previously set by \fBsethostname()\fR. The  \fInamelen\fR
  24 argument specifies the size of the array pointed to by \fIname\fR. The returned
  25 name is null-terminated unless insufficient space is provided.
  26 .sp
  27 .LP
  28 The \fBsethostname()\fR function sets the name of the host machine to be
  29 \fIname\fR, which has length \fInamelen\fR. This call is restricted to the
  30 superuser and is normally used only when the system is bootstrapped.
  31 .sp
  32 .LP
  33 Host names are limited to \fBMAXHOSTNAMELEN\fR characters, currently 256,
  34 defined in the <\fBnetdb.h\fR> header.
  35 .SH RETURN VALUES
  36 .LP
  37 Upon successful completion, \fBgethostname()\fR and \fBsethostname()\fR return
  38 0. Otherwise, they return \(mi1 and set \fBerrno\fR to indicate the error.
  39 .SH ERRORS
  40 .LP
  41 The \fBgethostname()\fR and \fBsethostname()\fR functions will fail if:
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fBEFAULT\fR\fR
  46 .ad
  47 .RS 10n
  48 The \fIname\fR or \fInamelen\fR argument gave an invalid address.
  49 .RE
  50
  51 .sp
  52 .LP
  53 The \fBsethostname()\fR function will fail if:
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBEPERM\fR\fR
  58 .ad
  59 .RS 9n
  60 The {\fBPRIV_SYS_ADMIN\fR} privilege was not asserted in the effective set of
  61 the calling process.
  62 .RE
  63
  64 .SH ATTRIBUTES
  65 .LP
  66 See \fBattributes\fR(5) for descriptions of the following attributes:
  67 .sp
  68
  69 .sp
  70 .TS
  71 box;
  72 c | c
  73 l | l .
  74 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  75 _
  76 Interface Stability     Standard
  77 _
  78 MT-Level        MT-Safe
  79 .TE
  80
  81 .SH SEE ALSO
  82 .LP
  83 \fBsysinfo\fR(2), \fBuname\fR(2), \fBgethostid\fR(3C), \fBattributes\fR(5),
  84 \fBstandards\fR(5)