sethostname

Name

sethostname -- set host name

Synopsis

#include <unistd.h>
#include <sys/param.h.h>
#include <sys/utsname.h>

int sethostname(const char * name, size_t len);

Description

If the process has appropriate privileges, the sethostname() function shall change the host name for the current machine. The name shall point to a null-terminated string of at most len bytes that holds the new hostname.

If the symbol HOST_NAME_MAX is defined, or if sysconf(_SC_HOST_NAME_MAX)() returns a value greater than 0, this value shall represent the maximum length of the new hostname. Otherwise, if the symbol MAXHOSTLEN is defined, this value shall represent the maximum length for the new hostname. If none of these values are defined, the maximum length shall be the size of the nodename field of the utsname structure.

Return Value

On success, 0 is returned. On error, -1 is returned and the global variable errno is set appropriately.

Errors

EINVAL 

len is negative or larger than the maximum allowed size.

EPERM 

the process did not have appropriate privilege.

EFAULT 

name is an invalid address.

Rationale

ISO POSIX (2003) guarantees that:

Maximum length of a host name (not including the terminating null) as returned from the gethostname() function shall be at least 255 bytes.

The glibc C library does not currently define HOST_NAME_MAX, and although it provides the name _SC_HOST_NAME_MAX a call to sysconf() returns -1 and does not alter errno in this case (indicating that there is no restriction on the hostname length). However, the glibc manual idicates that some implementations may have MAXHOSTNAMELEN as a means of detecting the maximum length, while the Linux kernel at release 2.4 and 2.6 stores this hostname in the utsname structure. While the glibc manual suggests simply shortening the name until sethostname() succeeds, the LSB requires that one of the first four mechanisms works. Future versions of glibc may provide a more reasonable result from sysconf(_SC_HOST_NAME_MAX).