gethostname()--Retrieve Host Name

BSD 4.3 Syntax

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

 int gethostname(char *name,
                 int length)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

UNIX^® 98 Compatible Syntax

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

 int gethostname(char *name,
                 socklen_t length)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

The gethostname() function is used to retrieve the name of the host from the system.

There are two versions of the API, as shown above. The base IBM^® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

Parameters

name: (Output) The pointer to a character array where the host name is to be stored. The host name is NULL-terminated unless the length of the host name exceeds the length of the name parameter, in which case the host name is truncated to the size of the name parameter.
length: (Input) The length of the name parameter.

Authorities

No authorization is required.

Return Value

gethostname() returns an integer. Possible values are:

-1 (unsuccessful)
0 (successful)

Error Conditions

When gethostname() 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.

The length parameter specifies a negative value.

[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

Maximum length of host names is defined by {MAXHOSTNAMELEN} (defined in <sys/param.h>).
When a process issues a sethostname(), the host name can be accessed by any process that issues a gethostname().
On an initial program load, the host name is set to whatever was configured with System i^® Navigator or with option 12 (Change TCP/IP domain information) on the Configure TCP/IP (CFGTCP) menu. The local domain name is appended with the local host name and stored in system-wide storage. This combined name is the host name that can be retrieved by gethostname(). If the local host name and local domain name are not set, the host name is set to NULL.
The host name is returned in the default coded character set identifier (CCSID) currently in effect for the job.
When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the gethostname() API is mapped to qso_gethostname98().

Related Information

_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
sethostname()--Set Host Name
gethostid()--Retrieve Host ID Address
sethostid()--Set Host ID Address

API introduced: V3R1

[ Back to top | UNIX-Type APIs | APIs by category ]