Technical Reference: Communications, Volume 2

sethostname Subroutine

Syntax

int sethostname ( Name, NameLength) char *Name; int NameLength;

Description

The sethostname subroutine sets the name of a host machine. Only programs with a root user ID can use this subroutine.

The sethostname subroutine allows a calling process with root user authority to set the internal host name of a machine on a network.

Parameters

Name	Specifies the name of the host machine.
NameLength	Specifies the length of the Name array.

Return Values

Upon successful completion, the system returns a value of 0.

If the sethostname subroutine is unsuccessful, the subroutine handler performs the following functions:

Returns a value of -1 to the calling program.
Moves an error code, indicating the specific error, into the errno global variable. For further explanation of the errno variable see Error Notification Object Class in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

Error Codes

The sethostname subroutine is unsuccessful if any of the following errors occurs:

EFAULT	The Name parameter or NameLength parameter gives an address that is not valid.
EPERM	The calling process did not have an effective root user ID.

Implementation Specifics

The sethostname subroutine is part of Base Operating System (BOS) Runtime.

All applications containing the sethostname subroutine must be compiled with _BSD set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

Related Information

The gethostid subroutine, gethostname subroutine, sethostid subroutine.

Sockets Overview and Understanding Network Address Translation in AIX 5L Version 5.1 Communications Programming Concepts.