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


Previous Contents Index


write()

Writes a buffer of data to a socket or file.

The $QIO equivalent is the IO$_WRITEVBLK function.


Format

#include <unixio.h>

int write (int d, void *buffer, int nbytes);


Arguments

d

A descriptor that must refer to a socket or file.

buffer

The address of contiguous storage from which the output data is taken.

nbytes

The maximum number of bytes involved in the write operation.

Description

This routine attempts to write a buffer of data to a socket or file.

See also socket().


Return Values

x The number of bytes written to the socket or file.
--1 Error; errno is set to indicate the error.

Errors

[EBADF] The d argument is not a valid descriptor open for writing.
[EPIPE] An attempt was made to write to a socket that is not open for reading by any process.
[EFAULT] Part of the array pointed to by iov or data to be written to the file points outside the process's allocated address space.
[EWOULDBLOCK] The NBIO (nonblocking) flag is set for the socket descriptor and the process is delayed during the write operation.
[EINVAL] The nbytes argument is negative.

6.2 Communication Support Routines

This section describes the communication support routines.


decc$get_sdc()

Returns the socket device channel (SDC) associated with a socket descriptor for direct use with DIGITAL TCP/IP Services for OpenVMS software.

Format

#include <socket.h>

short int decc$get_sdc (int s);


Argument

s

A socket descriptor.

Description

This routine returns the SDC associated with a socket. C Socket descriptors are normally used either as file descriptors or with one of the routines that takes an explicit socket descriptor as its argument. C Sockets are implemented using TCP/IP socket device channels. This routine returns the SDC used by a given socket descriptor so you can use the TCP/IP facilities directly by means of various I/O system services ($QIO).

Note

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

Return Values

0 Indicates that s is not an open socket descriptor.
x The SDC number.

gethostbyaddr()

Searches the hosts database sequentially from the beginning of the database for a host record with a given address.

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


Format

#include <netdb.h>

struct hostent *gethostbyaddr (char *addr, int len, int type);


Arguments

addr

A pointer to a series of bytes in network order specifying the address of the host sought. This argument does not point to an ASCII string.

len

The number of bytes in the address pointed to by the addr argument.

type

The type of address format being sought. Currently, only AF_INET is supported.

Description

This routine finds the first host record in the hosts database with the given address.

The gethostbyaddr() routine uses a common static area for its return values. This means that subsequent calls to this routine overwrite previously returned host entries. You must make a copy of the host entry if you want to save it.


Return Values

NULL Indicates an error.
x A pointer to an object having the hostent structure. See Section 5.8.1 for a description of the hostent structure.

gethostbyname()

Searches the hosts database sequentially from the beginning of the database for a host record with a given name or alias. This routine also invokes the BIND resolver to query the appropriate name server if the information requested is not in the hosts database.

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


Format

#include <netdb.h>

struct hostent *gethostbyname (char *name);


Argument

name

A pointer to a null-terminated character string containing the name or an alias of the host sought.

Description

This routine finds the first host in the hosts database with the given name or alias.

The gethostbyname() routine uses a common static area for its return values. This means that subsequent calls to this routine overwrite previously returned host entries. You must make a copy of the host entry if you want to save it.


Return Values

NULL Indicates an error.
x A pointer to an object having the hostent structure. See Section 5.8.1 for a description of the hostent structure.

gethostname()

Returns the fully qualified name of the local host.

Format

#include <types.h>

#include <socket.h>

int gethostname (char *name, int namelen);


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

Errors

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

getnetbyaddr()

Searches the networks database sequentially from the beginning of the database for a network record with a given address.

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 sought. Currently, only AF_INET is supported.

Description

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

The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines will overwrite any previously returned network entry. 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 5.8.6 for a description of the netent structure.

getnetbyname()

Searches the networks database sequentially from the beginning of the database for a network record with a given name or alias.

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 of the name or an alias of the network sought.

Description

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

The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines 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 5.8.6 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.

getnetent()

Reads the next record in the networks database, opening the database if necessary.

Format

#include <netdb.h>

struct netent *getnetent();


Description

This routine allows the records in the networks database to be read sequentially in the order in which they appear in the database.

The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines 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 5.8.6 for a description of the netent structure.

getpeername()

Returns the name of the connected peer.

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


Format

#include <types.h>

#include <socket.h>

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


Arguments

s

A socket descriptor created using socket().

name

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

namelen

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

Description

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

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.
[ENOTSOCK] The socket descriptor references a file, not a socket.
[ENOTCONN] The socket is not connected.
[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.

getprotobyname()

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


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


Previous Next Contents Index