[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP TCP/IP Services for OpenVMS
Sockets API and System Services Programming


Previous Contents Index


gethostname()

Returns the fully-qualified name of the local host.

Format

#include <types.h>

#include <socket.h>

int gethostname ( char *name, int namelen) ;

(_DECC_V4_SOURCE)
int gethostname ( char *name, size_t namelen) ;

(not_DECC_V4_SOURCE)


Arguments

name

The address of a buffer where the name should be returned. The returned name is null terminated unless sufficient space is not provided.

namelen

The size of the buffer pointed to by name.

Description

This function returns the translation of the logical names TCPIP$INET_HOST and TCPIP$INET_DOMAIN when used with the TCP/IP Services software.

Return Values

0 Indicates successful completion.
-1 Indicates an error occurred. The value of errno indicates the error.

Errors

EFAULT The buffer described by name and namelen is not a valid, writable part of the user address space.

getnameinfo()

Maps addresses to names in a protocol-independent way.

Format

#include <socket.h>

#include <netdb.h>

int getnameinfo ( const struct sockaddr *sa, size_t salen, char *node, size_t nodelen, char *service, size_t servicelen, int flags );


Arguments

sa

Points either to a sockaddr_in structure (for IPv4) or to a sockaddr_in6 structure (for IPv6) that holds the IP address and port number.

salen

Specifies the length of either the sockaddr_in structure or the sockaddr_in6 structure.

node

Points to a buffer in which to receive the null-terminated network node name or alias corresponding to the address contained in the sa. A NULL pointer instructs getnameinfo() to not return a node name. The node argument and service argument must not both be zero.

nodelen

Specifies the length of the node buffer. A value of zero instructs getnameinfo() to not return a node name.

service

Points to a buffer in which to receive the null-terminated network service name associated with the port number contained in sa. A NULL pointer instructs getnameinfo() to not return a service name. The node argument and service argument must not both be 0.

servicelen

Specifies the length of the service buffer. A value of zero instructs getnameinfo() to not return a service name.

flags

Specifies changes to the default actions of getnameinfo() . By default, getnameinfo() searches for the fully-qualified domain name of the node in the hosts database and returns it. See Table 4-3 for a list of flags and their meanings.

Description

This function looks up an IP address and port number in a sockaddr structure specified by sa and returns node name and service name text strings in the buffers pointed to by the node and service arguments, respectively.

If the node name is not found, getnameinfo() returns the numeric form of the node address, regardless of the value of the flags argument. If the service name is not found, getnameinfo() returns the numeric form of the service address (port number) regardless of the value of the flags argument.

The application must provide buffers large enough to hold the fully-qualified domain name and the service name, including the terminating null characters.

Table 4-3 describes the flag bits and, if set, their meanings. The flags are defined in the NETDB.H header file.

Table 4-3 getnameinfo() Flags
Flag Value Description
NI_DGRAM Specifies that the service is a datagram service (SOCK_DGRAM). The default assumes a stream service (SOCK_STREAM). This is required for the few ports (512-514) that have different services for UDP and TCP.
NI_NAMEREQD Returns an error if the host name cannot be located in the hosts database.
NI_NOFQDN Searches the hosts database and returns the node name portion of the fully-qualified domain name for local hosts.
NI_NUMERICHOST 1 Returns the numeric form of the host's address instead of its name. Resolution of the host name is not performed.
NI_NUMERICSERV 1 Returns the numeric form (port number) of the service address instead of its name. The host name is not resolved.

1The two NI_NUMERIC* flags are required to support the -n flag that many commands provide.


Return Values

0 Indicates success.
x Indicates an error occurred. The value of errno indicates the error.

Errors

EAI_AGAIN The name could not be resolved at this time. Future attempts may succeed.
EAI_BADFLAGS The flags argument had an invalid value.
EAI_FAIL A nonrecoverable error occurred when attempting to resolve the name.
EAI_FAMILY The address family was not recognized.
EAI_MEMORY There was a memory allocation failure when trying to allocate storage for the return value.
EAI_NONAME The name does not resolve for the supplied parameters. Neither the node name nor the service name were supplied. At least one of these must be supplied.
EAI_SYSTEM A system error occurred; the error code can be found in errno .

getnetbyaddr()

Searches the network database that is referenced by the TCPIP$NETWORK logical name for a network record with the specified address. If the network record is not found, this function may invoke the BIND resolver to search TCPIP$SYSTEM:NETWORKS.DAT.

The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETNETBYADDR subfunction code.


Format

#include <netdb.h>

struct netent *getnetbyaddr ( long net, int type) ;


Arguments

net

The network number, in host byte order, of the networks database entry required.

type

The type of network being sought (AF_INET or AF_INET6).

Description

This function finds the first network record in the networks database with the given address.

The getnetbyaddr() and getnetbyname() functions use a common static area for their return values. Subsequent calls to any of these functions overwrite any previously returned network entry. You must make a copy of the network entry if you want to save it.


Return Values

x A pointer to an object having the netent structure. See Section 3.2.9 for a description of the netent structure.
NULL Indicates end of file or an error.

Errors

EINVAL The net argument is invalid.
ESRCH The search failed.

getnetbyname()

Searches the networks database for a network record with a specified name or alias. If the network record is not found, this function may invoke the BIND resolver to search TCPIP$SYSTEM:NETWORKS.DAT.

The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETNETBYNAME subfunction code.


Format

#include <netdb.h>

struct netent *getnetbyname ( char *name );


Argument

name

A pointer to a null-terminated character string containing either the network name or an alias for the network name.

Description

This function finds the first network record in the networks database with the given name or alias.

The getnetbyaddr() and getnetbyname() functions use a common static area for their return values. Subsequent calls to any of these functions overwrite previously returned network entries. You must make a copy of the network entry if you want to save it.


Return Values

NULL Indicates end of file or an error.
x A pointer to an object having the netent structure. See Section 3.2.9 for a description of the netent structure.

Errors

EFAULT The buffer described by name is not a valid, writable part of the user address space.
EINVAL The name argument is invalid.
ESRCH The search failed.

getnetent()

Retrieves an entry from the networks database file.

Format

#include <netdb.h>

struct netent *getnetnet (void);


Description

This function opens and sequentially reads the networks database file (TCPIP$SYSTEM:NETWORKS.DAT) to retrieve network information.

Returns a pointer to a netent structure that contains the equivalent fields for a network description line in the networks database file. The netent structure is defined in the NETDB.H header file.

The networks database file remains open after a call by the getservent() function. Use the endnetent() function to close the networks database file. Use the setnetent() function to open the networks database file and reset the file marker to the beginning of the file.

The getnetent() function uses a common static area for its return values, so subsequent calls to this function overwrite any existing network entry. To save the network entry, you must make a copy of it.

Related Functions

See also setnetent and endnetent .


Return Values

x A pointer to a netent structure.
0 Indicates an error or end of file.

getpeername()

Returns the name of the connected peer.

The $QIO equivalent is the IO$_SENSEMODE function with the p4 argument.


Format

#include <types.h>

#include <socket.h>

int getpeername ( int s, struct sockaddr *name, int *namelen );

(_DECC_V4_SOURCE)
int getpeername ( int s, struct sockaddr *name, size_t *namelen );

(not_DECC_V4_SOURCE)


Arguments

s

A socket descriptor created using socket() .

name

A pointer to a buffer where the peer name is to be returned.

namelen

An address of an integer that specifies the size of the name buffer. On return, it is modified to reflect the actual length, in bytes, of the name returned.

Description

This function returns the name of the peer connected to the specified socket descriptor.

Related Functions

See also bind() , socket() , and getsockname() .


Return Values

0 Successful completion.
-1 Error; errno is set to indicate the error.

Errors

EBADF The descriptor is invalid.
EFAULT The name argument is not a valid part of the user address space.
EINVAL The socket has been shut down.
ENOBUFS The system has insufficient resources to complete the call.
ENOTCONN The socket is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The operation is not supported for the socket protocol.

getprotobyname()

Searches the protocols table until a matching protocol name is found or until the end of the table is encountered.

Format

#include <netdb.h>

struct protoent *getprotobyname ( char *name );


Argument

name

A pointer to a string containing the desired protocol name.

Description

This function returns a pointer to a protoent structure containing data from the protocols table. For information about the protoent structure, refer to Section 3.2.10.

All information is contained in a static area, so it must be copied to be saved.

Related Functions

See also getprotoent() and getprotobynumber() .


Return Values

NULL Indicates the end of the table or an error.
x A pointer to a protoent structure.

getprotobynumber()

Searches the protocols table until a matching protocol number is found or until the end of the table is encountered.

Format

#include <netdb.h>

struct protoent *getprotobynumber ( int *proto ) ;


Argument

proto

A pointer to a string containing the desired protocol number.

Description

This function returns a pointer to a protoent structure containing the data from the protocols table. For information about the protoent structure, refer to Section 3.2.10.

All information is contained in a static area, so it must be copied to be saved.

Related Functions

See also getprotoent() and getprotobyname() .


Return Values

NULL Indicates end of table or an error.
x A pointer to a protoent structure.

getprotoent()

Reads the next entry from the protocols table.

Format

#include <netdb.h>

struct protoent *getprotoent();


Description

This function returns a pointer to a protoent structure containing the data from the protocols table. For information about the protoent structure, refer to Section 3.2.10.

The getprotoent() function keeps an index to the table, allowing successive calls to be used to search the entire table.

All information is contained in a static area, so it must be copied to be saved.

Related Functions

See also getprotobyname() and getprotobynumber() .


Return Values

NULL Indicates the end of the table or an error.
x A pointer to a protoent structure.

getservbyname()

Gets information on the specified service from the services database that is referenced by the TCPIP$SERVICE logical name. If not found there, this function may invoke the BIND resolver to search TCPIP$ETC:SERVICES.DAT.

Format

#include <netdb.h>

struct servent *getservbyname ( char *name, char *proto );


Arguments

name

A pointer to a string containing the name of the service about which information is required.

proto

A pointer to a string containing the name of the protocol (TCP or UDP) for which to search.

Description

This function searches the services database until a matching service name is found or the end of file is encountered. If a protocol name is also supplied, searches must also match the protocol.

This function returns a pointer to a servent structure containing the data from the network services database. For information about the servent structure, refer to Section 3.2.11.

All information is contained in a static area, so it must be copied to be saved.

Related Functions

See also getservbyport() .


Return Values

NULL Indicates end of file or an error.
x A pointer to a servent structure.

getservbyport()

Gets information on the specified port from the services database that is referenced by the TCPIP$SERVICE logical name. If the specified port is not found, this function may invoke the BIND resolver to search TCPIP$ETC:SERVICES.DAT.

Format

#include <netdb.h>

struct servent *getservbyport ( int port, char *proto );


Arguments

port

The port number for which to search. This port number should be specified in network byte order. You can use the htons() function to convert the port number to network byte order.

proto

A pointer to a string containing the name of the protocol (TCP or UDP) for which to search.

Description

This function searches the services database until a matching port is found, or until end of file is encountered. If a protocol name is also supplied, searches must also match the protocol.

This function returns a pointer to a servent structure containing the broken-out fields of the requested line in the network services database. For information about the servent structure, refer to Section 3.2.11.

All information is contained in a static area, so it must be copied to be saved.

Related Functions

See also getservbyname() .


Return Values

NULL Indicates end of file or an error.
x A pointer to a servent structure.

Errors

EPERM Not owner. Indicates that the wrong port number was specified.


Previous Next Contents Index