sethostname()--Set Host Name

Syntax

 #include <sys/types.h>
 #include <sys/socket.h>

 int sethostname(char *name,
                 int length)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

The sethostname() function is used to set the name of the host for a system.

Parameters

name: (Input) The pointer to a character array where the host name is stored.
length: (Input) The length of the name parameter.

Authorities

No authorization is required.

Return Value

sethostname() returns an integer. Possible values are:

-1 (unsuccessful)
0 (successful)

Error Conditions

When sethostname() fails, errno can be set to one of the following:

[EFAULT]	Bad address. The system detected an address which was not valid while attempting to access the name parameter.
[EINVAL]	Parameter not valid. This error code indicates one of the following: The length parameter specifies a negative value or a value that is greater than the allowed maximum length. The host name pointed to by the name parameter contains characters that are not invariant.
[EPERM]	Operation not permitted. The process does not have the appropriate privileges to use sethostname().
[EIO]	Input/output error.
[EUNKNOWN]	Unknown system state.

Error Messages

Message ID	Error Message Text
CPE3418 E	Possible APAR condition or hardware failure.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFA081 E	Unable to set return value or error code.

Usage Notes

A process must have the *iosyscfg special authority to use the sethostname().
Maximum length of host names is defined by [MAXHOSTNAMELEN] (defined in <sys/param.h>).
The host name can be set in the following two ways (and users should be aware of the implications of the way they choose):
- By using option 12 (Change local domain and host names) on the Configure TCP/IP (CFGTCP) menu. When option 12 is used to change the local domain name or local host name, the system appends the local domain name to the local host name and stores the value for access by sethostname() and gethostname().
- By using the sethostname() function. When sethostname() is used to set the host name, the TCP/IP configuration file is not affected. Only the field that is accessed by sethostname() and gethostname() is changed.
The name of the host is set to NULL when the pointer to the host name (pointed to by the name parameter) is set to NULL.
The host name is assumed to be in the default coded character set identifier (CCSID) currently in effect for the job. In addition, the host name must adhere to the following conventions.
- The first character must be either an English alphabetic character or a numeric character.
- The last character must be either an English alphabetic character, a numeric character, or a period (.).
- Blanks are not allowed (trailing blanks are removed).
- The special characters period(.), underscore(_), and minus(-) are allowed.
- Parts of the name separated by periods (.) cannot exceed 63 characters in length.
  Note: Each part of the name separated by periods must begin and end with an English alphanumeric character.
- Internet address names (in the form nnn.nnn.nnn.nnn (where nnn is a decimal number)) are not allowed.
- Names must be from 1 to 255 characters in length.

Related Information

gethostname()--Retrieve Host Name

API introduced: V3R1

Top | UNIX-Type APIs | APIs by category