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:
|
| [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.
- 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().
- 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.
- The first character must be either an English alphabetic character or a
numeric character.
Related Information
gethostname()--Retrieve Host Name
API introduced: V3R1