# DIGITAL TCP/IP Services for OpenVMS
System Services and C Socket Programming

Previous | Contents

The members of this structure are:

p_name | The official name of the protocol.
p_aliases | A zero-terminated list of alternate names for the protocol.
p_proto | The protocol number.

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

See also getprotoent() and getprotobynumber().

## Return Values

> NULL | Indicates end of file or an error.
> x | A pointer to a protoent structure.

# getprotobynumber()

> Searches the protocols database until a matching protocol number is found or until end of file 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:

>     struct  protoent {
>             char   *p_name;       /* official name of protocol */
>             char   **p_aliases;   /* alias list */
>             long   p_proto;       /* protocol number */
>     };

> The members of this structure are:

> p_name | The official name of the protocol.
> p_aliases | A zero-terminated list of alternate names for the protocol.
> p_proto | The protocol number.

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

> See also getprotoent() and getprotobyname().

## Return Values

> NULL | Indicates end of file or an error.
> x | A pointer to a protoent structure.

# getprotoent()

> Reads the next line from the protocols database.

## Format

> ### #include <netdb.h>

> ### struct protoent *getprotoent();

## DESCRIPTION

> This routine returns a pointer to a protoent structure containing the broken-out fields of the next line in the protocols database:

>     struct  protoent {
>             char   *p_name;       /* official name of protocol */
>             char   **p_aliases;   /* alias list */
>             long   p_proto;       /* protocol number */
>     };

> The members of this structure are:

> p_name | The official name of the protocol.
> p_aliases | A zero-terminated list of alternate names for the protocol.
> p_proto | The protocol number.

> The getprotoent() routine keeps a pointer in the database, allowing successive calls to be used to search the entire file.

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

> See also getprotobyname() and getprotobynumber().

## Return Values

> NULL | Indicates an error.
> x | A pointer to a protoent structure.

# 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 ("tcp" or "udp") for which to search.

## DESCRIPTION

> This routine searches sequentially from the beginning of the file until a matching service name is found, or until end of file 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:

>     struct  servent {
>             char    *s_name;        /* official name of service */
>             char    **s_aliases;    /* alias list */
>             long    s_port;         /* port service resides at */
>             char    *s_proto;       /* protocol to use */
>     };

> The members of this structure are:

> s_name | The official name of the service.
> s_aliases | A zero-terminated list of alternate names for the service.
> s_port | The port number at which the service resides. Port numbers are returned in network-byte order.
> s_proto | The name of the protocol to use when contacting the service.

> All information is contained in a static area, so you must copy it if you want it saved.

> 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 network services database.

## 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.

> ### proto

> A pointer to a string containing the name of the protocol ("tcp" or "udp") for which to search.

## DESCRIPTION

> This routine searches sequentially from the beginning of the file until a matching port is found, or until end of file 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:

>     struct  servent {
>             char    *s_name;        /* official name of service */
>             char    **s_aliases;    /* alias list */
>             long    s_port;         /* port service resides at */
>             char    *s_proto;       /* protocol to use */
>     };

> The members of this structure are:

> s_name | The official name of the service.
> s_aliases | A zero-terminated list of alternate names for the service.
> s_port | The port number at which the service resides. Port numbers are returned in network-byte order.
> s_proto | The name of the protocol to use when contacting the service.

> All information is contained in a static area, so you must copy it if you it saved.

> See also getservbyname().

## Return Values

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

# getsockname()

> Returns the name associated with a socket.

> The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR function with the p3 argument.

## Format

> ### #include <types.h>

> ### #include <socket.h>

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

## ARGUMENTS

> ### s

> A socket descriptor created with socket() routine and bound to the socket name with bind() routine.

> ### 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.

> The bind() routine makes the association of the name to the socket, not the getsockname() routine.

> See also bind() and socket().

## Return Values

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

## Errors

> You can set errno to the following values:
> [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.

> The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR function.

## Format

> ### #include <types.h>

> ### #include <socket.h>

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

## ARGUMENTS

> ### s

> A socket descriptor created by socket().

> ### level

> The protocol level for which the socket options are desired. It can 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

> Interpreted by the protocol 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 is 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 | Successful completion.
> --1 | Error; errno is set to indicate the error.

## Errors

> You can set errno to the following values:
> [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.

# 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 byte order (OpenVMS systems). All integers on OpenVMS 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 expected to be transmitted through a network. All hosts on a network should 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 OpenVMS systems differs from the network order.

> This routine is most often used with internet addresses. Network byte order places the byte with the most significant bits at lower addresses, whereas the OpenVMS system places the most significant bits at the highest address.

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## 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 byte order (OpenVMS system). All short integers on the OpenVMS system 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 expected to be transmitted through a network. All hosts on a network should 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 OpenVMS systems differs from the network order.

> This routine is most often used with ports as returned by getservent(). Network byte order places the byte with the most significant bits at lower addresses, whereas the OpenVMS system places the most significant bits at the highest address.

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## Return Value

> x | A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on the OpenVMS system.

# inet_addr()

> Converts internet addresses in text form into numeric (binary) internet addresses in dotted decimal format.

## 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 dotted decimal format.

## DESCRIPTION

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

> Internet addresses specified with 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 4 bytes of an internet address. Note that when an internet address is viewed as a 32-bit integer quantity on the OpenVMS system, the bytes appear in binary as "d.c.b.a". That is, OpenVMS 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 can 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).

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## 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 portion of a full internet address.

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## Return Value

> x | The local network address 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.

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## Return Value

> x | An internet address in network byte order.

# inet_netof()

> Returns the internet network address portion of an internet address.

## Format

> ### #include <in.h>

> ### #include <inet.h>

> ### int inet_netof (struct in_addr in);

## ARGUMENT

> ### in

> An internet address.

## DESCRIPTION

> This routine returns the internet network address (NET) portion of a full internet address.

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## Return Value

> x | The internet network portion of an internet address in host byte order.

# inet_network()

> Converts a null-terminated text string representing an internet address into a network address in local host format.

## Format

> ### #include <in.h>

> ### #include <inet.h>

> ### int inet_network (char *cp);

## ARGUMENT

> ### cp

> A pointer to an ASCII (null-terminated) character string containing a network address in the standard internet "." format.

## DESCRIPTION

> This routine returns an internet network address as local host integer values when given as its argument an ASCII string representing the address in the internet standard "." notation.

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## Return Values

> --1 | Indicates that cp does not point to a proper internet network address.
> x | An internet network address as local host integer values.

# inet_ntoa()

> Converts an internet address into a text string representing the address in the standard internet "." notation.

## Format

> ### #include <in.h>

> ### #include <inet.h>

> ### char *inet_ntoa (struct in_addr in);

## ARGUMENT

> ### in

> An internet address in network byte order.

## DESCRIPTION

> This routine converts an internet address into an ASCII (null-terminated) string representing that address in the standard internet "." notation.

> > Warning

> > Arguments should not be passed as integers because of how DEC C handles struct arguments.

> Because the string is returned in a static buffer that is overwritten by subsequent calls to inet_ntoa(), DIGITAL recommends copying the string to a safe place.

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## Return Value

> x | A pointer to a string containing the internet address in "." notation.

# ntohl()

> Converts longwords from network byte order to host byte order.

## Format

> ### #include <in.h>

> ### unsigned long int ntohl (unsigned long int netlong);

## ARGUMENT

> ### netlong

> A longword in network byte order. Integers in network byte order cannot be used for arithmetic computation on the OpenVMS system.

## DESCRIPTION

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

> The network byte order is the format in which data bytes are expected to be transmitted through a network. All hosts on a network should 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 OpenVMS systems differs from the network order.

> This routine is most often used with internet addresses. Network byte order places the byte with the most significant bits at lower addresses, whereas the OpenVMS system places the most significant bits at the highest address.

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## Return Value

> x | A longword in host byte order.

# ntohs()

> Converts short integers from network byte order to host byte order.

## Format

> ### #include <in.h>

> ### unsigned short int ntohs (unsigned short int netshort);

## ARGUMENT

> ### netshort

> A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on the OpenVMS system.

## DESCRIPTION

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

> The network byte order is the format in which data bytes are expected to be transmitted through a network. All hosts on a network should 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 OpenVMS systems differs from the network order.

> This routine is most often used with internet ports as returned by getservent(). Network byte order places the byte with the most significant bits at lower addresses, whereas the OpenVMS system places the most significant bits at the highest address.

## Return Value

> x | A short integer in host byte order (OpenVMS).

# setsockopt()

> Sets options on a socket.

> The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function.

## Format

> ### #include <types.h>

> ### #include <socket.h>

> ### int setsockopt (int s, int level, int optname, char *optval, int optlen);

## ARGUMENTS

> ### s

> A socket descriptor created by socket().

> ### level

> The protocol level for which the socket options are to be modified. It can have one of the following values:

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

> ### optname

> Interpreted by the protocol specified in level. Options at each protocol level are documented with the protocol.

> Previous | Next | Contents