getprotobyname

Searches the protocols database until a matching protocol name is found or until EOF 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 routine returns a pointer to a protoent structure containing the broken-out fields of the requested line from the protocols database.

See the <netdb.h> header file for a description of the protoent structure.

See also getprotoent and getprotobynumber in this section.

Return Values

NULL	Indicates EOF or an error.
x	A pointer to a protoent structure.

getprotobynumber

Searches the protocols database until a matching protocol number is found or until an EOF 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 routine returns a pointer to a protoent structure containing the broken-out fields of the requested line from the protocols database.

See the <netdb.h> header file for a description of the protoent structure.

See also getprotoent and getprotobyname in this section.

Return Values

NULL	Indicates EOF or an error.
x	A pointer to a protoent structure.

getprotoent

Gets a protocol database entry from the protocols database file.

Format

#include <netdb.h>

struct protoent *getprotoent (void);

Description

The getprotoent routine reads the next entry of the database, opening a connection to the database, if necessary.

See the <netdb.h> header file for a description of the protoent structure.

See also getprotobyname , getprotobynumber , setprotoent , and endprotoent in this section.

Return Values

x	A pointer to a protoent structure.
NULL	Indicates an error or EOF.

getservbyname

Gets information on the named service from the network services database.

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 to search for.

Description

This routine searches sequentially from the beginning of the file until a matching service name is found, or until an EOF is encountered. If a protocol name is also supplied (non-NULL), searches must also match the protocol.

This routine returns a pointer to a servent structure containing the broken-out fields of the requested line in the network services database.

See the <netdb.h> header file for a description of the servent structure.

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

See also getservbyport in this section.

Return Values

NULL	Indicates EOF or an error.
x	A pointer to a servent structure.

getservbyport

Gets information on the specified port from the network services database.

Format

#include <netdb.h>

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

Arguments

port

The port number to search for.

proto

A pointer to a string containing the name of the protocol to search for.

Description

This routine searches sequentially from the beginning of the file until a matching port is found, or until an EOF is encountered. If a protocol name is also supplied (non-NULL), searches must also match the protocol.

This routine returns a pointer to a servent structure containing the broken-out fields of the requested line in the network services database. See the <netdb.h> header file for a description of the servent structure.

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

See also getservbyname in this section.

Return Values

NULL	Indicates EOF or an error.
x	A pointer to a servent structure.

getservent

Gets a services file entry from the network services database file.

Format

#include <netdb.h>

struct servent *getservent (void);

Description

The getservent routine reads the next line of the network services database file, opening a connection to the database, if necessary.

This routine returns a servent structure that contains fields for a line of information from the network services database file. See the <netdb.h> header file for a description of the hostent structure.

This routine uses a common static area for its return values, so subsequent calls to this routine overwrite any existing network entry. You must make a copy of the network services entry, if you wish to save it.

See also setservent , and endservent in this section.

Return Values

x	A pointer to a servent structure.
NULL	Indicates an error or EOF.

getsockname

Returns the name associated with a socket.

Format

#include <socket.h>

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

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

(NOT _DECC_V4_SOURCE)

Arguments

s

A socket descriptor created with socket and bound to the socket name with bind .

name

A pointer to the buffer in which getsockname should return the socket name.

namelen

A pointer to an integer specifying the size of the buffer pointed to by name. On return, the integer contains the actual size of the name returned, in bytes.

Description

This routine returns the current name for the specified socket descriptor. The name is a format specific to the address family (AF_INET) assigned to the socket.

bind makes the association of the name to the socket, not getsockname .

See also bind and socket in this appendix.

Return Values

0	Indicates success.
--1	Indicates an error; errno is set to one of the following: EBADF -- The descriptor is invalid. ENOTSOCK -- The socket descriptor references a file, not a socket. ENOBUFS -- Resources were insufficient in the system to perform the operation. EFAULT -- The name parameter is not a valid part of the user address space.

getsockopt

Returns the options set on a socket.

Format

#include <socket.h>

int getsockopt (int s, int level, int optname, char *optval, int *optlen);

(_DECC_V4_SOURCE) int getsockopt (int s, int level, int optname, void *optval, size_t *optlen);

(NOT _DECC_V4_SOURCE)

Arguments

s

A socket descriptor created by socket .

level

The protocol level for which the socket options are desired. It may have one of the following values:

SOL_SOCKET	Get the options at the socket level.
p	Any protocol number. Get the options for protocol level p. See the <in.h> file for the various IPPROTO values.

optname

Is interpreted by the protocol that is specified in the level. Options at each protocol level are documented with the protocol. See setsockopt in this section for socket level options.

optval

Points to a buffer in which the value of the specified option should be placed by getsockopt .

optlen

Points to an integer containing the size of the buffer pointed to by optval. On return, the integer will be modified to contain the actual size of the option value returned.

Description

This routine gets information on socket options. See the appropriate protocol for information on available options at each protocol level.

Return Values

0	Indicates success.
--1	Indicates an error; errno is set to one of the following: EBADF -- The descriptor is invalid. ENOTSOCK -- The socket descriptor references a file, not a socket. ENOPROTOOPT -- The option is unknown or the protocol is unsupported.

herror

Writes a message to standard error explaining h_error .

Format

#include <netdb.h>

void herror (const char *string);

Arguments

string

A user-printable string.

Description

The herror routine maps the error number in the external variable h_errno to a locale-dependent error message.

hstrerror

Returns an error message string.

Format

#include <string.h>

char *hstrerror (int errnum);

Arguments

errnum

An error number specifying a value of h_errno .

Description

The hstrerror routine maps the error number specified by the errnum parameter to a locale-dependent error message string and returns a pointer to the string. The string pointed to by the return value cannot be modified by the program, but could be overwritten by subsequent calls to this routine.

Return Values

x	A pointer to the generated message string.
--1	On error, errno might be set, but no return value is reserved to indicate an error.

Errors

If the hstrerror routine fails, errno is set to one of the following values: EINVAL -- The errnum parameter is an invalid error number.

hostalias

Searches for host aliases associated with a name.

Format

#include <resolv.h>

char *hostalias (const char *name);

Arguments

name

Points to the name of the host that you want to retrieve aliases from.

Description

The hostalias routine searches for the alias associated with the name parameter. The HOSTALIASES environment variable defines the name of a file where you can find the host aliases, in the form:

host alias

Return Values

x	The host alias.
NULL	Indicates an error.

htonl

Converts longwords from host to network byte order.

Format

#include <in.h>

unsigned long int htonl (unsigned long int hostlong);

Argument

hostlong

A longword in host (VAX system) byte order. All integers on VAX systems are in host byte order unless otherwise specified.

Description

This routine converts 32-bit unsigned integers from host byte order to network byte order.

The network byte order is the format in which data bytes are supposed to be transmitted through a network. All hosts on a network must send data in network byte order. Not all hosts have an internal data representation format that is identical to the network byte order. The host byte order is the format in which bytes are ordered internally on a specific host.

The host byte order on VAX systems differs from the network order.

This routine is most often used with Internet addresses and ports as returned by gethostent and getservent , and when manipulating values in the structures. Network byte-order places the byte with the most significant bits at lower addresses; VAX systems place the most significant bits at the highest address.

Return Value

x	A longword in network byte order.

htons

Converts short integers from host to network byte order.

Format

#include <in.h>

unsigned short int htons (unsigned short int hostshort);

Argument

hostshort

A short integer in host (VAX system) byte order. All short integers on VAX systems are in host byte order unless otherwise specified.

Description

This routine converts 16-bit unsigned integers from host byte order to network byte order.

The network byte order is the format in which data bytes are supposed to be transmitted through a network. All hosts on a network must send data in network byte order. Not all hosts have an internal data representation format that is identical to the network byte order. The host byte order is the format in which bytes are ordered internally on a specific host.

The host byte order on VAX systems differs from the network order.

This routine is most often used with Internet addresses and ports as returned by gethostent and getservent , and when manipulating values in the structures. Network byte order places the byte with the most significant bits at lower addresses; VAX systems place the most significant bits at the highest address.

Return Value

x	A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on VAX systems.

inet_addr

Converts Internet addresses in text form into numeric (binary) Internet addresses.

Format

#include <in.h>

#include <inet.h>

int inet_addr (char *cp);

Argument

cp

A pointer to a null-terminated character string containing an Internet address in the standard Internet "." format.

Description

This routine returns an Internet address in network byte order when given as its argument an ASCIZ (null-terminated) string representing the address in the Internet standard "." notation.

Internet addresses specified using the "." notation take one of the following forms:

a.b.c.d a.b.c a.b a

When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. Note that when an Internet address is viewed as a 32-bit integer quantity on VAX systems, the bytes previously referred to appear in binary as " d.c.b.a ". That is, VAX bytes are ordered from least significant to most significant.

When only one part is given, the value is stored directly in the network address without any byte rearrangement.

All numbers supplied as "parts" in a "." address expression may be decimal, octal, or hexadecimal, as specified in the C language (that is, a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal).

Return Values

--1	Indicates that cp does not point to a proper Internet address.
x	An Internet address in network byte order.

inet_lnaof

Returns the local network address portion of an Internet address.

Format

#include <in.h>

#include <inet.h>

int inet_lnaof (struct in_addr in);

Argument

in

An Internet address.

Description

This routine returns the local network address (LNA) portion of a full Internet address.

Return Value

x	The LNA portion of an Internet address in host byte order.

inet_makeaddr

Returns an Internet address given a network address and a local address on that network.

Format

#include <in.h>

#include <inet.h>

struct in_addr inet_makeaddr (int net, int lna);

Arguments

net

An Internet network address in host byte order.

lna

A local network address on network net in host byte order.

Description

This routine combines the net and lna arguments into a single Internet address.

Return Value

x	An Internet address in network byte order.