---
name: "gethostname"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["freebsd", "macos"]
url: "https://new.carta.tech/gethostname/3"
---

# gethostname(3)

get/set name of current host

## NAME

**gethostname**, **sethostname** – get/set name of current host

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

**#include \<unistd.h\>**

*int*\

**gethostname**(*char \*name*, *size\_t namelen*);

*int*\

**sethostname**(*const char \*name*, *int namelen*);

## DESCRIPTION

The **gethostname**() function returns the standard host name for the current processor, as previously set by **sethostname**(). The *namelen* argument specifies the size of the *name* array. The returned name is null-terminated, unless insufficient space is provided.

The **sethostname**() function sets the name of the host machine to be *name*, which has length *namelen*. This call is restricted to the super-user and is normally used only when the system is bootstrapped.

Host names are limited in length to {sysconf(\_SC\_HOST\_NAME\_MAX)} characters, not including the trailing null, currently 255.

## RETURN VALUES

The **gethostname()** function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

## ERRORS

The following errors may be returned by these calls:

- \[EFAULT\]

  The *name* or *namelen* argument gave an invalid address.

- \[ENAMETOOLONG\]

  The current host name is longer than *namelen*. (For **gethostname**() only.)

- \[EPERM\]

  The caller tried to set the host name and was not the super-user.

## SEE ALSO

[sysconf(3)](/sysconf/3.md), [sysctl(3)](/sysctl/3.md)

## STANDARDS

The **gethostname**() function conforms to IEEE Std 1003.1-2001 (“POSIX.1”). Callers should be aware that {sysconf(\_SC\_HOST\_NAME\_MAX)} may be variable or infinite, but is guaranteed to be no less than {\_POSIX\_HOST\_NAME\_MAX}. On older systems, this limit was defined in the non-standard header ⟨sys/param.h⟩ as MAXHOSTNAMELEN, and counted the terminating null. The **sethostname**() function and the error returns for **gethostname**() are not standardized.

## HISTORY

The **gethostname**() function appeared in 4.2BSD. The *namelen* argument to **gethostname**() was changed to *size\_t* in FreeBSD 5.2 for alignment with IEEE Std 1003.1-2001 (“POSIX.1”).