This chapter describes the purpose and format of each MultiNet socket library function.
The socket functions described in this chapter are available in the shareable image MULTINET:MULTINET_SOCKET_LIBRARY.EXE, included in the standard MultiNet distribution. The include files and example programs are part of the optional MultiNet Programmers' Kit, and should be installed as described in the MultiNet for OpenVMS Installation and Administrator’s Guide before you use the programming interface.
In addition to supporting the MultiNet socket library, applications developed for the HP OpenVMS/ULTRIX Connection (UCX) software using the VAX C socket library (UCX$IPC.OLB) will run over MultiNet, using an emulation of UCX$IPC_SHR.EXE.
Note! To avoid potential conflicts between MultiNet socket library definitions and C compiler definitions, include a reference to the file MULTINET_ROOT:[MULTINET.INCLUDE.SYS]TYPES.H before any other header file references.
MultiNet provides a call tracing facility that can be used to debug and trace the use of the sockets API for many applications. This facility works for both the MultiNet socket library and the API that the newer versions of the C compiler work with. This does NOT log QIO operations. To enable the tracing define the MULTINET_SOCKET_TRACE logical name. The value of the logical name can be used in the following ways:
• As a bit mask for types of operations to trace. Bit 0 (zero) signifies control operations, bit 1signifies read operations and bit 2 signifies write operations. When these values are used the information is writen to SYS$OUTPUT:.
• As a partial or full file name. When used as a partial file name the default name specified to open the file is: SYS$SCRATCH:MULTINET_SOCKET_<process_name>.LOG. Control, read and write operations are logged when logging is done to a file.
The MultiNet socket library is based on the equivalent UNIX programming library, and was therefore not designed with reentrancy in mind. If you call into the socket library with AST delivery disabled, some of the library routines will suspend execution and fail to return control to the caller.
This situation occurs most often when applications try to call those functions from within an AST routine where AST delivery is not possible.
Any routine that relies on the select() function is subject to this restriction (including the select() call itself, and most of the domain name resolution routines such as gethostbyname(), and so on).
Another reentrancy consideration is the socket library's use of static internal data structures, some of which are passed back to the application, as in the case of the hostent structure address returned by gethostbyname(). Other functions use these data structures internally to maintain context.
In either case, it is dangerous to call into these routines from an AST because it is possible to interrupt a similar call already in progress, using the same static buffer, thereby corrupting the contents of the buffer.
Another consideration is the use of routines that send and receive data. Every socket in the kernel contains two fixed-size buffers for sending and receiving data. If an application tries to transmit data when there is insufficient buffer space, that call will block (or suspend execution) until buffer space becomes available. This can become an issue if the application blocks while attempting to transmit a large data buffer, and an AST routine tries to transmit a small data buffer. The small data buffer is transmitted before the large one.
The same situation applies to the functions that read data from the network. This situation may also arise if multiple reads and writes are performed on sockets which have been set up to be non-blocking (NBIO).
These considerations might seem overly restrictive; however, the MultiNet socket library is a port of the BSD socket library, which is subject to all of the same restrictions. Applications which need to perform I/O from within AST routines should use the SYS$QIO system service to talk directly to the MultiNet device driver.
Therefore, none of the socket routines should be considered AST reentrant.
The following are the Socket Library functions:
|
accept()/a |
ntohl() |
|
bcmp() |
ntohs() |
|
bind()/b |
recv()/r |
|
Domain Name Resolver Routines |
recvfrom()re/recvfrom_44() |
|
endhostent() |
recvmsg()/r |
|
endnetent() |
select() |
|
endprotoent() |
select_wake() |
|
endservent() |
send()/s |
|
freeaddrinfo() |
gaistrerror() |
|
getaddrinfo() |
getnameinfo() |
|
getdtablesize() |
sendmsg()/s |
|
gethostbyaddr()/g |
sendto()/s/sendto_44() |
|
gethostbysockaddr()/g |
sethostent() |
|
gethostname() |
setnetent() |
|
getnetbyaddr() |
setprotoent() |
|
getnetbyname() |
setservent() |
|
getpeername()/g |
setsockopt() |
|
getprotobyname() |
shutdown() |
|
getprotobynumber() |
socket() |
|
getprotoent() |
socket_close() |
|
getservbyname() |
socket_ioctl() |
|
getservbyport() |
socket ioctl FIONBIO |
|
getservent() |
socket ioctl FIONREAD |
|
getsockname()/g |
socket ioctl SIOCADDRT |
|
getsockopt() |
socket ioctl SIOCDELRT |
|
gettimeofday() |
socket ioctl SIOCATMARK |
|
hostalias() |
socket ioctl SIOCDARP |
|
htonl() |
socket ioctl SIOCGARP |
|
htons() |
socket ioctl SIOCSARP |
|
inet_addr() |
socket ioctl SIOCGIFADDR |
|
inet_lnaof() |
socket ioctl SIOCSIFADDR |
|
inet_makeaddr() |
socket ioctl SIOCGIFBRDADDR |
|
inet_netof() |
socket ioctl SIOCSIFBRDADDR |
|
inet_network() |
socket ioctl SIOCGIFCONF |
|
inet_ntoa() |
socket ioctl SIOCGIFDSTADDR |
|
klread() |
socket ioctl SIOCSIFDSTADDR |
|
klseek() |
socket ioctl SIOCGIFFLAGS |
|
klwrite() |
socket ioctl SIOCSIFFLAGS |
|
listen() |
socket ioctl SIOCGIFMETRIC |
|
multinet_kernel_nlist |
socket ioctl SIOCSIFMETRIC |
|
nlist() |
socket ioctl SIOCGIFNETMASK |
|
socket option SO_BROADCAST |
socket ioctl SIOCSIFNETMASK |
|
socket option SO_DEBUG |
socket option SO_REUSEADDR |
|
socket option SO_DONTROUTE |
socket option SO_SNDBUF |
|
socket option SO_ERROR |
socket option SO_SNDLOWAT |
|
socket option SO_KEEPALIVE |
socket option SO_SNDTIMEO |
|
socket option SO_LINGER |
socket option SO_TYPE |
|
socket option SO_OOBINLINE |
socket option TCP_KEEPALIVE |
|
socket option SO_RCVBUF |
socket option TCP_NODELAY |
|
socket option SO_RCVLOWAT |
socket_perror() |
|
socket option SO_RCVTIMEO |
socket_read() |
|
vms_errno_string() |
socket_write() |
Extracts the first connection from the queue of pending connections on a socket, creates a new socket with the same properties as the original socket, and assigns a new OpenVMS channel to the new socket. If no pending connections are present on the queue, accept() blocks the caller until a new connection is present. The original socket remains open and can be used to accept more connections, but the new socket cannot be used to accept additional connections.
The original socket is created with the socket() function, bound to an address with bind(), and is listening for connections after a listen().
The accept() function is used with connection-based socket types. Currently the only connection-based socket is SOCK_STREAM, which, together with AF_INET, constitutes a TCP socket.
The accept_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
New_VMS_Channel = accept(VMS_Channel,
Address, AddrLen);
short New_VMS_Channel, VMS_Channel;
struct sockaddr *Address;
unsigned int *AddrLen;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the original socket from which to accept the connection.
Address
VMS Usage: socket_address
type: struct sockaddr
access: write only
mechanism: by reference
The optional Address argument is a result parameter. It is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the Address argument is determined by the domain in which the communication is occurring.
AddrLen
VMS Usage: socket_address_length
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, the optional AddrLen argument contains the length of the space pointed to by Address, in bytes. On return, it contains the actual length, in bytes, of the address returned.
RETURNS
If the accept() is successful, an OpenVMS channel number is returned. If an error occurs, a value of -1 is returned, and a more specific message is returned in the global variables socket_errno and vmserrno.
An error code of ENETDOWN can indicate
that the program has run out of VMS channels to use in creating new sockets.
This can be due to either the SYSGEN parameter CHANNELCNT being too low for the
number of connections in use by the program, or to a socket leak in the code.
Make sure the code closes the socket (using close()) when it is done
with the socket.
Compares a range of memory. This function operates on variable-length strings of bytes and does not check for null bytes as strcmp() does.
bcmp() is part of the 4.3BSD run-time library, but is not provided by Hewlett-Packard as part of the VAX C run-time library. It is provided here for compatibility with the 4.3BSD library.
FORMAT
Status = bcmp(String1, String2, Length);
char *String1, *String2;
unsigned int Length;
ARGUMENTS
String1,String2
VMS Usage: arbitrary
type: byte buffer
access: read only
mechanism: by reference
Pointers to the two buffers to be compared.
Length
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The number of bytes to be compared.
RETURNS
The bcmp() function returns zero
if the strings are identical. It returns a nonzero value if they are different.
Copies memory from one location to another. This function operates on variable-length strings of bytes and does not check for null bytes as strcpy() does.
bcopy() is part of the 4.3BSD run-time library, but is not provided by Hewlett-Packard as part of the VAX C run-time library. It is provided here for compatibility with the 4.3BSD library.
FORMAT
(void) bcopy(String1, String2, Length);
char *String1, *String2;
unsigned int Length;
ARGUMENTS
String1
VMS Usage arbitrary
type: byte buffer
access: read only
mechanism: by reference
The source buffer for the copy operation.
String2
VMS Usage: arbitrary
type: byte buffer
access: write only
mechanism: by reference
The destination buffer for the copy operation.
Length
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The number of bytes to be copied.
Assigns an address to an unnamed socket. When a socket is created with socket(), it exists in a name space (address family) but has no assigned address. bind() requests that the address be assigned to the socket.
If the port number specified in the sin_port field of the sockaddr structure is less than 1024, SYSPRV is required to use this function.
The bind_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = bind(VMS_Channel, Name,
NameLen);
short VMS_Channel;
struct sockaddr *Name;
unsigned int NameLen;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Name
VMS Usage: socket_address
type: struct sockaddr
access: read only
mechanism: by reference
The address to which the socket should be bound. The exact format of the Address argument is determined by the domain in which the socket was created.
NameLen
VMS Usage: socket_address_length
type: longword (unsigned)
access: read only
mechanism: by value
The length of the Name argument, in bytes.
RETURNS
If the bind() is successful, a
value of 0 is returned. If an error occurs, a value of -1 is returned, and a
more specific message is returned in the global variables socket_errno
and vmserrno.
Fills memory with zeros.
bzero() is part of the 4.3BSD run-time library, but is not provided by Hewlett-Packard as part of the VAX C run-time library. It is provided here for compatibility with the 4.3BSD library.
FORMAT
(void) bzero(String, Length);
char *String;
unsigned int Length;
ARGUMENTS
String
VMS Usage: arbitrary
type: byte buffer
access: write only
mechanism: by reference
The address of the buffer to receive the zeros.
Length
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The number of bytes to be zeroed.
When used on a SOCK_STREAM socket, connect() attempts to make a connection to another socket. This function, when used on a SOCK_DGRAM socket, permanently specifies the peer to which datagrams are sent to and received from. The peer socket is specified by name, which is an address in the communications domain of the socket. Each communications domain interprets the name parameter in its own way. If the address of the local socket has not yet been specified with bind(), the local address is also set to an unused port number when connect() is called.
The connect_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = connect(VMS_Channel, Name,
NameLen);
short VMS_Channel;
struct sockaddr *Name;
unsigned int NameLen;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Name
VMS Usage: socket_address
type: struct sockaddr
access: read only
mechanism: by reference
The address of the peer to which the socket should be connected. The exact format of the Address argument is determined by the domain in which the socket was created.
NameLen
VMS Usage: socket_address_length
type: longword (unsigned)
access: read only
mechanism: by value
The length of the Name argument, in bytes.
RETURNS
If the connect() is successful, a value of 0 is returned. If an error occurs, a value of -1 is returned, and a more specific message is returned in the global variables socket_errno and vmserrno.
The following functions exist for compatibility with UNIX 4.3BSD programs that call the DNS Name Resolver directly rather than through gethostbyname(). The arguments and calling conventions are compatible with BIND Version 4.8.3. They are subject to change and are not documented here.
The h_errno variable in the MultiNet socket library that contains the error status of the resolver routine is accessible to C programs.
dn_comp() p_rr()
dn_expand() p_type()
dn_skip() putlong()
dn_skipname() putshort()
fp_query() _res_close()
_getlong() res_init()
_getshort() res_mkquery()
herror() res_query()
p_cdname() res_querydomain()
p_class() res_search()
p_query() res_send()
Tells the DNS Name Resolver to close the TCP connection to the DNS Name Server that may have been opened as the result of calling sethostent() with StayOpen set to 1.
FORMAT
(void) endhostent();
Tells the DNS Name Resolver to close the TCP connection to the DNS Name Server that may have been opened as the result of using setnetent() with StayOpen set to 1.
FORMAT
(void) endnetent();
Tells the host table routines that the scan started by getprotoent() is complete. endprotoent() is provided only for compatibility with UNIX 4.3BSD, and is ignored by the MultiNet software.
FORMAT
(void) endprotoent();
Tells the host table routines that the scan started by getservent() is complete. endservent() is provided only for compatibility with UNIX 4.3BSD, and is ignored by the MultiNet software.
FORMAT
(void) endservent();
Returns the maximum number of channels available to a process. This function is normally used to determine the Width argument to the select() function.
FORMAT
Width = getdtablesize();
RETURNS
The size of the channel table.
Looks up a host by its address in the binary host table or the DNS Name Server and returns information about that host. An alternate entry point _gethostbyaddr(), that looks only in the binary host table, is also available.
Note! The MultiNet socket library is not reentrant. If you call into it from an AST (interrupt) routine, the results are unpredictable.
The gethostbyaddr_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
(struct hostent *) gethostbyaddr(Addr,
Length, Family);
(struct hostent *) _gethostbyaddr(Addr, Length, Family);
char *Addr;
unsigned int Length;
unsigned int Family;
ARGUMENTS
Addr
VMS Usage: address
type: dependent on Family
access: read only
mechanism: by reference
A pointer to the address to look up. The type is dependent on the Family argument. For Internet (AF_INET family) addresses, Addr is a pointer to an in_addr structure.
Length
VMS Usage: address_length
type: longword (unsigned)
access: read only
mechanism: by value
The size, in bytes, of the buffer pointed to by Addr.
Family
VMS Usage: address_family
type: longword (unsigned)
access: read only
mechanism: by value
The address family, and consequently the interpretation of the Addr argument. Normally, this is AF_INET, indicating the Internet family of addresses.
RETURNS
If gethostbyaddr() succeeds, it
returns a pointer to a structure of type hostent. (See gethostbyname()
for more information on the hostent structure.) If this function fails, a value
of 0 is returned, and the global variable h_errno is set to one of the
DNS Name Server error codes defined in the file multinet_root:[multinet.include]netdb.h.
Looks up hostname and/or service name and returns results. This call supports both IPv4 and IPv6 requests.
FORMAT
int getaddrinfo(hostname, servname,
hints, res)
char *hostname, *servname;
struct addrinfo *hints, **res;
ARGUMENTS
hostname
VMS Usage: host_name
type: ASCIZ string
access: read only
mechanism: by reference
A C-language string containing the name of the host to look up.
servname
VMS Usage: service_name
type: ASCIZ string
access: read only
mechanism: by reference
A C-language string containing the name of the service to look up.
hints
VMS Usage: hints
type: struct addrinfo
access: read only
mechanism: by reference
An addrinfo structure that provides hints on the lookups to be performed.
res
VMS Usage: results
type: pointer
access: write only
mechanism: by reference
A linked list of addrinfo structures that contain the results of the operation.
RETURNS
An integer value is returned. Zero is success, non-zero is failure. Failure values can be interpretted with gaistrerror().
struct addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
char *ai_canonname;
struct sockaddr *ai_addr;
struct addrinfo *ai_next;
};
Use freeaddrinfo(res) to free the chain
of data structures returned when the program is done using it.
Returns hostname and/or servicename information from a sockaddr structures. This call can handle both IPv6 and IPv4 requests.
FORMAT
int getnameinfo(sa, salen, host, hostlen,
serv, servlen, flags)
struct sockaddr *sa;
size_t salen, hostlen, servlen;
char *host, *serv;
int flags;
ARGUMENTS
sa
VMS Usage: sockaddr
type: sockaddr
access: read only
mechanism: by reference
A pointer to a sockaddr to obtain information on.
salen
VMS Usage: sockaddr length
type: integer
access: read only
mechanism: by value
The length of the sockaddr structure.
host
VMS Usage: hostname
type: ASCIZ string
access: write only
mechanism: by reference
Storage area for a hostname to be returned.
hostlen
VMS Usage: length of hostname string space
type: integer
access: read only
mechanism: by value
The amount of space available in the host string for storing the hostname.
serv
VMS Usage: service_name
type: ASCIZ string
access: write only
mechanism: by reference
Storage area for a service name to be returned.
servlen
VMS Usage: length of servicename string space
type: integer
access: read only
mechanism: by value
The amount of space available in the serv string for storing the service name
RETURNS
An integer value is returned. Zero is
success, non-zero is failure. Failure values can be interpretted with
gaistrerror().
Looks up a host by name in the binary host table or the DNS Name Server and returns information about that host. An alternate entry point _gethostbyname(), that looks only in the binary host table, is also available.
Note! The MultiNet socket library is not reentrant. If you call into it from an AST (interrupt) routine, the results are unpredictable
The gethostbyname_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
(struct hostent *) gethostbyname(Name);
(struct hostent *) _gethostbyname(Name);
char *Name;
ARGUMENTS
Name
VMS Usage: host_name
type: ASCIZ string
access: read only
mechanism: by reference
A C-language string containing the name of the host to look up.
RETURNS
If gethostbyname() succeeds, it returns a pointer to a structure of type hostent. If this function fails, a value of 0 is returned, and the global variable h_errno is set to one of the DNS Name Server error codes defined in the file multinet_root:[multinet.include]netdb.h.
The hostent structure is defined as follows:
struct hostent {
char *h_name; /* official name */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
#define h_addr h_addr_list[0] /* address, for compat */
char *h_cputype; /* cpu type */
char *h_opsys; /* operating system */
char **h_protos; /* protocols */
struct sockaddr *h_addresses; /* sockaddr form */
};
Looks up a host by socket address in the binary host table or the DNS Name Server and returns information about that host. An alternate entry point _gethostbysockaddr(), that looks only in the binary host table, is also available. gethostbysockaddr() is identical in functionality to gethostbyaddr(), but takes its arguments in a different form.
Note! The MultiNet socket library is not reentrant. If you call into it from an AST (interrupt) routine, the results are unpredictable.
The gethostbysockaddr_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
(struct hostent *) gethostbysockaddr(Addr,
Length);
struct sockaddr *Addr;
unsigned int Length;
ARGUMENTS
Addr
VMS Usage: socket_address
type: struct sockaddr
access: read only
mechanism: by reference
A pointer to a sockaddr structure describing the address to look up.
Length
VMS Usage: socket_address_length
type: longword (unsigned)
access: read only
mechanism: by value
The size, in bytes, of the sockaddr structure pointed to by Addr.
RETURNS
If gethostbysockaddr() succeeds,
it returns a pointer to a structure of type hostent. (See gethostbyname()
for more information on the hostent structure.) If this function fails,
a value of 0 is returned, and the global variable h_errno is set to one
of the DNS Name Server error codes defined in the file multinet_root:[multinet.include]netdb.h.
Returns the Internet name of the host it is executed on. This name comes from the logical name MULTINET_HOST_NAME and can be set using the SET HOST-NAME command in the MultiNet Network Configuration utility (NET-CONFIG).
FORMAT
Status = gethostname(String, Length);
char *String;
unsigned int Length;
ARGUMENTS
String
VMS Usage: hostname
type: ASCIZ string
access: write only
mechanism: by reference
A pointer to a buffer to receive the host name.
Length
VMS Usage: hostname_length
type: longword (unsigned)
access: read only
mechanism: by value
The length of the buffer, in bytes. The buffer should be at least 33 bytes long to guarantee that the complete host name is returned.
RETURNS
If the gethostname() function is
successful, it returns a 0. It returns a -1 if it is unable to translate the
logical name.
Looks up a network by its network number in the binary host table or the DNS Name Server and returns information about that network. An alternate entry point _getnetbyaddr(), that looks only in the binary host table, is also available.
FORMAT
(struct netent *) getnetbyaddr(Net,
Protocol);
(struct netent *) _getnetbyaddr(Net, Protocol);
unsigned int Net, Protocol;
ARGUMENTS
Net
VMS Usage: network_number
type: longword (unsigned)
access: read only
mechanism: by value
The network number to look up.
Protocol
VMS Usage: protocol_number
type: longword (unsigned)
access: read only
mechanism: by value
The address family of the network to look up. For Internet networking, this should be specified as AF_INET.
RETURNS
If getnetbyaddr() succeeds, it
returns a pointer to a structure of type netent. (See getnetbyname()
for more information on the netent structure.) If this function fails, a value
of 0 is returned, and the global variable h_errno is set to one of the
DNS Name Server error codes defined in multinet_root:[multinet.include]netdb.h.
Looks up a network by name in the binary host table or the DNS Name Server and returns information about that network. An alternate entry point _getnetbyname(), that looks only in the binary host table, is also available.
FORMAT
(struct netent *) getnetbyname(Name);
(struct netent *) _getnetbyname(Name);
char *Name;
ARGUMENTS
Name
VMS Usage: network_name
type: ASCIZ string
access: read only
mechanism: by reference
A pointer to a C-language string containing the name of the network.
RETURNS
If getnetbyname() succeeds, it returns a pointer to a structure of type netent. If this function fails, a value of 0 is returned, and the global variable h_errno is set to one of the DNS Name Server error codes defined in multinet_root:[multinet.include]netdb.h.
The netent structure is defined as follows:
struct netent {
char *n_name; /* official name */
char **n_aliases; /* alias list */
int n_addrtype; /* address type */
unsigned long n_net; /* network # */
struct sockaddr *n_addresses; /* sockaddr form */
};
Returns the name of the peer connected to the specified socket.
The accept_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = getpeername(VMS_Channel,
Address, AddrLen);
short VMS_Channel;
struct sockaddr *Address;
unsigned int *AddrLen;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Address
VMS Usage: socket_address
type: struct sockaddr
access: write only
mechanism: by reference
A result parameter. This argument is filled in with the address of the peer, as known to the communications layer. The exact format of the Address argument is determined by the domain in which the communication is occurring.
AddrLen
VMS Usage: socket_address_length
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, contains the length of the space pointed to by Address, in bytes. On return, it contains the actual length, in bytes, of the address returned.
RETURNS
If the getpeername() is
successful, a value of 0 is returned. If an error occurs, a value of -1 is
returned, and a more specific message is returned in the global variables socket_errno
and vmserrno.
Looks up a protocol by name in the binary host table and returns information about that protocol.
FORMAT
(struct protoent *) getprotobyname(Name);
char *Name;
ARGUMENTS
Name
VMS Usage: protocol_name
type: ASCIZ string
access: read only
mechanism: by reference
A pointer to a C-language string containing the name of the protocol.
RETURNS
If getprotobyname() succeeds, it returns a pointer to a structure of type protoent. If this function fails, a value of 0 is returned.
The protoent structure is defined as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol # */
};
Looks up a protocol by number in the binary host table and returns information about that protocol.
FORMAT
(struct protoent *)
getprotobynumber(Number);
unsigned int Number;
ARGUMENTS
Number
VMS Usage: protocol_number
type: longword (unsigned)
access: read only
mechanism: by value
The numeric value of the protocol.
RETURNS
If getprotobynumber() succeeds, it returns a pointer to a structure of type protoent. If this function fails, a value of 0 is returned.
The protoent structure is defined as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol # */
};
Returns the next protocol entry from the binary host table. It is used with setprotoent() and endprotoent() to scan through the protocol table. The scan is initialized with setprotoent(), run by calling getprotoent() until it returns a 0, and terminated by calling endprotoent().
FORMAT
(struct protoent *) getprotoent();
RETURNS
The getprotoent() function returns either a 0, indicating that there are no more entries, or a pointer to a structure of type protoent.
The protoent structure is defined as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol # */
};
Looks up a service by name in the binary host table and returns information about that service.
The service must be present in the HOSTS.SERVICES or HOSTS.LOCAL file, and the host table must be compiled into binary form using the host table compiler. See the MultiNet for OpenVMS Installation and Administrator’s Guide for more information about editing and compiling the host table files.
FORMAT
(struct servent *) getservbyname(Name, Protocol);
char *Name, *Protocol;
ARGUMENTS
Name
VMS Usage: service_name
type: ASCIZ string
access: read only
mechanism: by reference
A pointer to a C-language string containing the name of the service.
Protocol
VMS Usage: protocol_name
type: ASCIZ string
access: read only
mechanism: by reference
A pointer to a C-language string containing the name of the protocol associated with the service, such as "TCP".
RETURNS
If getservbyname() succeeds, it returns a pointer to a structure of type servent. If this function fails, a value of 0 is returned.
The servent structure is defined as follows:
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port # */
char *s_proto; /* protocol to use */
};
Looks up a service by protocol port in the binary host table and returns information about that service.
The service must be present in the HOSTS.SERVICES or HOSTS.LOCAL file, and the host table must be compiled into binary form using the host table compiler. See the MultiNet for OpenVMS Installation and Administrator’s Guide for more information about editing and compiling the host table files.
FORMAT
(struct servent *) getservbyport(Number,
Protocol);
unsigned int Number;
char *Protocol;
ARGUMENTS
Number
VMS Usage: service_number
type: longword (unsigned)
access: read only
mechanism: by value
The numeric value of the service port.
Protocol
VMS Usage: protocol_name
type: ASCIZ string
access: read only
mechanism: by reference
A pointer to a C-language string containing the name of the protocol associated with the service, such as "TCP".
RETURNS
If getservbyport() succeeds, it
returns a pointer to a structure of type servent. (See getservbyname()
for the format of the servent structure.) If this function fails, a
value of 0 is returned.
Returns the next server entry from the binary host table. This function is used with setservent() and endservent() to scan through the service table. The scan is initialized with setservent(), run by calling getservent() until it returns a 0, and terminated by calling endservent().
FORMAT
(struct servent *) getservent();
RETURNS
If getservent() succeeds, it
returns a pointer to a structure of type servent. (See getservbyname()
for the format of the servent structure.) If this function fails, a
value of 0 is returned.
Returns the current name of the specified socket.
The getsockname_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = getsockname(VMS_Channel,
Address, AddrLen);
short VMS_Channel;
struct sockaddr *Address;
unsigned int *AddrLen;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Address
VMS Usage: socket_address
type: struct sockaddr
access: write only
mechanism: by reference
A result parameter. It is filled in with the address of the local socket, as known to the communications layer. The exact format of the Address argument is determined by the domain in which the communication is occurring.
AddrLen
VMS Usage: socket_address_length
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, contains the length of the space pointed to by Address, in bytes. On return, it contains the actual length, in bytes, of the address returned.
RETURNS
If getsockname() is successful, a
,value of 0 is returned. If an error occurs, a value of -1 is returned and a
more specific message is returned in the global variables socket_errno
and vmserrno.
Retrieves the options associated with a socket. Options can exist at multiple protocol levels; however, they are always present at the uppermost socket level.
When manipulating socket options, you must specify the level at which the option resides and the name of the option. To manipulate options at the socket level, specify Level as SOL_SOCKET. To manipulate options at any other level, specify the protocol number of the appropriate protocol controlling the option. For example, to indicate that an option will be interpreted by the TCP protocol, set Level to the protocol number of TCP, which can be determined by calling getprotobyname().
OptName and any specified options are passed without modification to the appropriate protocol module for interpretation. The include file multinet_root:[multinet.include.sys]socket.h contains definitions for socket-level options. Options at other protocol levels vary in format and name.
For more information on what socket options may be retrieved with getsockopt(), see socket options.
FORMAT
Status = getsockopt(VMS_Channel, Level,
OptName, OptVal, OptLen);
short VMS_Channel;
unsigned int Level, OptName, *OptLen;
char *OptVal;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Level
VMS Usage: option_level
type: longword (unsigned)
access: read only
mechanism: by value
The protocol level at which the option will be manipulated. Specify Level as SOL_SOCKET, or as a protocol number as returned by getprotobyname().
OptName
VMS Usage: option_name
type: longword (unsigned)
access: read only
mechanism: by value
The option to be manipulated.
OptVal
VMS Usage: dependent on OptName
type: byte buffer
access: write only
mechanism: by reference
A pointer to a buffer that will receive the current value of the option. The format of this buffer is dependent on the option requested.
OptLen
VMS Usage: option_length
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, contains the length of the space pointed to by OptVal, in bytes. On return, it contains the actual length, in bytes, of the option returned.
RETURNS
If the getsockopt() is successful,
a value of 0 is returned. If an error occurs, a value of -1 is returned, and a
more specific message is returned in the global variables socket_errno
and vmserrno.
Returns the current time of day in UNIX format. This is the number of seconds and microseconds elapsed since January 1, 1970.
gettimeofday() is part of the 4.3BSD run-time library, but is not provided by Hewlett-Packard as part of the VAX C run-time library. It is provided here for compatibility with the 4.3BSD library.
FORMAT
Status = gettimeofday(TimeVal);
struct timeval *TimeVal;
ARGUMENTS
TimeVal
VMS Usage: UNIX_time
type: struct timeval
access: write only
mechanism: by reference
A pointer to a structure that receives the current time. The timeval structure is defined as follows:
struct timeval {
long tv_sec; /* seconds */
long tv_usec; /* and microseconds */
};
RETURNS
The gettimeofday() function always
returns a value of 0, which indicates it was successful.
Examines the user-specific host alias table (if the user has set one by defining the MULTINET_HOSTALIASES logical name) to see if the specified host name is a valid alias for another host name. This is normally called by gethostbyname() and res_search() automatically.
FORMAT
(char *) hostalias(Name);
char *Name;
ARGUMENTS
Name
VMS Usage: host_name
type: ASCIZ string
access: read only
mechanism: by reference
A C-language string containing the name of the host to look up in the host alias table.
RETURNS
If successful, the hostalias()
function returns a pointer to the character string of the canonical name of the
host. Otherwise, it returns a 0 to indicate that no alias exists.
Swaps the byte order of a four-byte integer from OpenVMS byte order to network byte order. This allows you to develop programs that are independent of the hardware architecture on which they are running.
FORMAT
RetVal = htonl(Val);
unsigned long Val;
ARGUMENTS
Val
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The four-byte integer to convert to network byte order.
RETURNS
The htonl() function returns the
byte-swapped integer that corresponds to Val. For example, if Val
is 0xc029e401, the returned value is 0x01e429c0.
Swaps the byte order of a two-byte integer from OpenVMS byte order to network byte order. This allows you to develop programs that are independent of the hardware architecture on which they are running.
FORMAT
RetVal = htons(Val);
unsigned short Val;
ARGUMENTS
Val
VMS Usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
The two-byte integer to convert to network byte order.
RETURNS
The htons() function returns the
byte-swapped integer that corresponds to Val. For example, if Val
is 0x0017, the returned value is 0x1700.
Converts Internet addresses represented in the ASCII form "xx.yy.zz.ww" to a binary representation in network byte order.
FORMAT
RetVal = inet_addr(Address);
char *Address;
ARGUMENTS
Address
VMS Usage: internet_address_string
type: ASCIZ string
access: read only
mechanism: by reference
A pointer to a C-language string containing an ASCII representation of the Internet address to convert.
RETURNS
If successful, the inet_addr()
function returns an integer corresponding to the binary representation of the
Internet address in network byte order. It returns a -1 to indicate that it
could not parse the specified Address string.
Returns the local network address portion of the specified Internet address. For example, the class A address 0x0a050010 (10.5.0.16) is returned as 0x00050010 (5.0.16).
FORMAT
RetVal = inet_lnaof(Address);
struct in_addr Address;
ARGUMENTS
Address
VMS Usage: internet_address
type: struct in_addr
access: read only
mechanism: by value
The Internet address from which to extract the local network address portion. The Internet address is specified in network byte order.
RETURNS
The inet_lnaof() function returns
the local network address portion of the Internet address in OpenVMS byte
order.
Builds a complete Internet address from the separate host and network portions.
FORMAT
RetVal = inet_makeaddr(Network, Host);
unsigned int Network, Host;
ARGUMENTS
Network
VMS Usage: network_number
type: longword (unsigned)
access: read only
mechanism: by value
The network portion of the Internet address to be constructed. The network portion is specified in OpenVMS byte order.
Host
VMS Usage: host_number
type: longword (unsigned)
access: read only
mechanism: by value
The host portion of the Internet address to be constructed. The host portion is specified in OpenVMS byte order.
RETURNS
The inet_makeaddr() function
returns the complete Internet address in network byte order.
Returns the network number portion of the specified Internet address. For example, the class A address 0x0a050010 (10.5.0.16) is returned as 0x0a (10).
FORMAT
RetVal = inet_netof(Address);
struct in_addr Address;
ARGUMENTS
Address
VMS Usage: internet_address
type: struct in_addr
access: read only
mechanism: by value
The Internet address from which to extract the network number portion. The Internet address is specified in network byte order.
RETURNS
The inet_netof() routine returns
the network portion of the Internet address in OpenVMS byte order.
Interprets Internet network numbers represented in the ASCII form "xx", "xx.yy", or "xx.yy.zz", and converts them into a binary representation in OpenVMS byte order.
FORMAT
RetVal = inet_network(Address);
char *Address;
ARGUMENTS
Address
VMS Usage: network_address_string
type: ASCIZ string
access: read only
mechanism: by reference
A pointer to a C-language string containing an ASCII representation of the Internet network number to convert.
RETURNS
If successful, the inet_network()
function returns an integer corresponding to the binary representation of the
Internet network in OpenVMS byte order. It returns a -1 to indicate that it
could not parse the specified string.
Converts an Internet address represented in binary form into an ASCII string suitable for printing.
FORMAT
(char *) inet_ntoa(Address);
struct in_addr Address;
ARGUMENTS
Address
VMS Usage: internet_address
type: struct in_addr
access: read only
mechanism: by value
The Internet address in binary form. The Internet address is specified in network byte order.
RETURNS
The inet_ntoa() function returns a
pointer to a C- language string corresponding to the Internet address.
Used with klseek() and multinet_kernel_nlist() to emulate the UNIX 4.3BSD nlist() function and the reading of the /dev/kmem device. klread() and klseek() read OpenVMS kernel memory through an interface that is similar to using read() and lseek() on the /dev/kmem device.
The OpenVMS CMKRNL privilege is required to use klread().
Before calling klread(), specify the address to read from using klseek().
FORMAT
Status = klread(Buffer, Size);
char *Buffer;
unsigned int Size;
ARGUMENTS
Buffer
VMS Usage: arbitrary
type: byte buffer
access: write only
mechanism: by reference
The address to which to return the kernel memory.
Size
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The number of bytes to read.
RETURNS
If successful, the klread()
function returns the number of bytes read. It returns a -1 to indicate that it
failed because the kernel memory was not readable. This usually indicates that
the current position, as set by klseek(), is invalid.
Used with klread() and multinet_kernel_nlist() to emulate the UNIX 4.3BSD nlist() function and reading the /dev/kmem device. klread() and klseek() read OpenVMS kernel memory through an interface that is similar to using read() and lseek() on the /dev/kmem device.
Use klseek() to set the current position in the network kernel. This position will be used by klread() and klwrite() in the next attempt to read or write data.
FORMAT
Status = klseek(Position);
unsigned int Position;
ARGUMENTS
Position
VMS Usage: kernel_address
type: longword (unsigned)
access: read only
mechanism: by value
The address in the network kernel to make the current position for the next klread() or klwrite() call.
RETURNS
The klseek() routine returns the
current position as a success status.
Used with klseek() and multinet_kernel_nlist() to emulate the UNIX 4.3BSD nlist() and writing the /dev/kmem device. klwrite() and klseek() write OpenVMS kernel memory through an interface that is similiar to using write() and lseek() on the /dev/kmem device.
The OpenVMS CMKRNL privilege is required to use klwrite().
Before calling klwrite(), specify the address to write using klseek().
FORMAT
Status = klwrite(Buffer, Size);
char *Buffer;
unsigned int Size;
ARGUMENTS
Buffer
VMS Usage: arbitrary
type: byte buffer
access: read only
mechanism: by reference
The address of the data to write into kernel memory.
Size
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The number of bytes to write.
RETURNS
If successful, the klwrite()
function returns the number of bytes written. It returns a -1 to indicate that
it failed because the kernel memory was not writable. This usually indicates
that the current position, as set by klseek(), is invalid.
Specifies the number of incoming connections that may be queued waiting to be accepted. This backlog must be specified before accepting a connection on a socket. The listen() function applies only to sockets of type SOCK_STREAM.
FORMAT
Status = listen(VMS_Channel, Backlog);
short VMS_Channel;
unsigned int Backlog;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Backlog
VMS Usage: connection_backlog
type: longword (unsigned)
access: read only
mechanism: by value
The maximum length of the queue of pending connections. If a connection request arrives when the queue is full, the request is ignored. The backlog queue length is limited to 5.
RETURNS
If listen() is successful, a value
of 0 is returned. If an error occurs, a value of -1 is returned, and a more
specific message is returned in the global variables socket_errno and vmserrno.
A special version of the UNIX 4.3BSD nlist() function that reads the symbol table to the MultiNet kernel. Unlike the UNIX 4.3BSD kernel, the MultiNet kernel's symbol table must be relocated before you can use klseek(), klread(), or klwrite() to examine the networking kernel.
Many of the same kernel symbols available under 4.3BSD are also available under the MultiNet software. Use of this interface is unsupported, as the symbol names and data types may change in future releases of the Berkeley TCP/IP networking code and in future releases of the MultiNet software.
To access the symbol table to the MultiNet image that is currently running, read from the file indicated by the logical name MULTINET_NETWORK_IMAGE:.
For more information about how to use multinet_kernel
nlist(), see nlist().
Examines the symbol table in an executable image or symbol table file.
FORMAT
Status = nlist(Filename, nl);
char *Filename;
struct nlist nl[];
ARGUMENTS
Filename
VMS Usage: filename
type: ASCIZ string
access: read only
mechanism: by reference
The file name of the executable image or symbol table file to read.
nl
VMS Usage: symbol_table_info
type: array of struct nlist
access: modify
mechanism: by reference
An array of nlist structures. The n_name field of each element specifies the name of the symbol to look up; the array is terminated by a null name. Each symbol is looked up in the file. If the symbol is found, the n_type and n_value fields are filled in with the type and value of the symbol. Otherwise, they are set to 0.
RETURNS
If successful, the nlist()
function returns a 0. Otherwise, it returns a -1.
Swaps the byte order of a four-byte integer from network byte order to OpenVMS byte order. This allows you to develop programs that are independent of the hardware architecture on which they are running.
FORMAT
RetVal = ntohl(Val);
unsigned long Val;
ARGUMENTS
Val
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The four-byte integer to convert to OpenVMS byte order.
RETURNS
The ntohl() function returns the
byte-swapped integer that corresponds to Val. For example, if Val
is 0x01e429c0, the returned value is 0xc029e401.
Swaps the byte order of a two-byte integer from network byte order to OpenVMS byte order. This allows you to develop programs that are independent of the hardware architecture on which they are running.
FORMAT
RetVal = ntohs(Val);
unsigned short Val;
ARGUMENTS
Val
VMS Usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
The two-byte integer to convert to OpenVMS byte order.
RETURNS
The ntohs() function returns the
byte-swapped integer that corresponds to Val. For example, if Val
is 0x1700, the returned value is 0x0017.
Receives messages from a socket. This function is equivalent to a recvfrom() function called with the From and FromLen arguments specified as zero. The socket_read() function is equivalent to a recv() function called with the Flags argument specified as zero.
The length of the message received is returned as the status. If a message is too long to fit in the supplied buffer and the socket is type SOCK_DGRAM, excess bytes are discarded.
If no messages are at the socket, the receive function waits for a message to arrive, unless the socket is non-blocking (see socket ioctl FIONBIO). In this case, a status of -1 is returned and the global variable socket_errno is set to EWOULDBLOCK.
The recv_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = int recv (short VMS_Channel, char *Buffer, int Size, int Flags);
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Buffer
VMS Usage: arbitrary
type: byte buffer
access: write only
mechanism: by reference
The address of a buffer in which to place the data read.
Size
VMS Usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
The length of the buffer specified by Buffer. The actual number of bytes read is returned in the Status.
Flags
VMS Usage: mask_word
type: word (unsigned)
access: read only
mechanism: by value
Control information that affects the recv() function. The Flags argument is formed by ORing one or more of the following values:
#define MSG_OOB 0x1 /*
process out-of-band data */
#define MSG_PEEK 0x2 /* peek at incoming message */
The MSG_OOB flag causes recv() to read any out-of-band data that has arrived on the socket.
The MSG_PEEK flag causes recv() to read the data present in the socket without removing the data. This allows the caller to view the data, but leaves it in the socket for future recv() calls.
RETURNS
If recv() is successful, a count
of the number of characters received is returned. A return value of 0 indicates
an end-of-file; that is, the connection has been closed. A return value of -1
indicates an error occurred. A more specific message is returned in the global
variables socket_errno and vmserrno.
Receives messages from a socket. This function is equivalent to the recv() function, but takes two additional arguments that allow the caller to determine the remote address from which the message was received.
The length of the message received is returned as the status. If a message is too long to fit in the supplied buffer and the socket is type SOCK_DGRAM, excess bytes are discarded.
If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is non-blocking (see socket ioctl FIONBIO). In this case, a status of -1 is returned and the global variable socket_errno is set to EWOULDBLOCK.
The recvfrom_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = int recvfrom (short VMS_Channel, char *Buffer, int Size, int Flags, struct sockaddr *From, unsigned int *FromLen);
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Buffer
VMS Usage: arbitrary
type: byte buffer
access: write only
mechanism: by reference
The address of a buffer in which to place the data read.
Size
VMS Usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
The length of the buffer specified by Buffer. The actual number of bytes read is returned in the Status.
Flags
VMS Usage: mask_word
type: word (unsigned)
access: read only
mechanism: by value
Control information that affects the recvfrom() function. The Flags argument is formed by ORing one or more of the following values:
#define MSG_OOB 0x1 /*
process out-of-band data */
#define MSG_PEEK 0x2 /* peek at incoming message */
The MSG_OOB flag causes recvfrom() to read any out-of-band data that has arrived on the socket.
The MSG_PEEK flag causes recvfrom() to read the data present in the socket without removing the data. This allows the caller to view the data, but leaves it in the socket for future recvfrom() calls.
From
VMS Usage: socket_address
type: struct sockaddr
access: write only
mechanism: by reference
On return, this optional argument is filled in with the address of the host that transmitted the packet, as known to the communications layer. The exact format of the Address argument is determined by the domain in which the communication is occurring.
FromLen
VMS Usage: socket_address_length
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, this optional argument contains the length of the space pointed to by From, in bytes. On return, it contains the actual length, in bytes, of the address returned.
RETURNS
If recvfrom() is successful, a
count of the number of characters received is returned. A return value of 0
indicates an end-of-file condition; that is, the connection has been closed. If
an error occurs, a value of -1 is returned, and a more specific message is
returned in the global variables socket_errno and vmserrno.
Receives messages from a socket. This function is equivalent to the recvfrom() function, but takes its arguments in a different fashion and can receive into noncontiguous buffers.
The length of the message received is returned as the status. If a message is too long to fit in the supplied buffer and the socket is type SOCK_DGRAM, excess bytes are discarded.
If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is non-blocking (see socket ioctl FIONBIO). In this case, a status of -1 is returned and the global variable socket_errno is set to EWOULDBLOCK.
The recvmsg_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = recvmsg(VMS_Channel, Message,
Flags);
short VMS_Channel;
struct msghdr *Message;
unsigned int Flags;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Message
VMS Usage: message header
type: struct msghdr
access: read only
mechanism: by reference
A pointer to a "msghdr" structure that describes the buffer to be received into. The access rights portion of the structure is unused.
Flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Control information that affects the recvmsg() function. The Flags argument is formed by ORing one or more of the following values:
#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_PEEK 0x2 /* peek at incoming message */
The MSG_OOB flag causes recvmsg() to read any out-of-band data that has arrived on the socket.
The MSG_PEEK flag causes recvmsg() to read the data present in the socket without removing the data. This allows the caller to view the data, but leaves it in the socket for future recvmsg() calls.
RETURNS
If recvmsg() is successful, a
count of the number of characters received is returned. A return value of 0
indicates an end-of-file condition; that is, the connection has been closed. If
an error occurs, a value of -1 is returned, and a more specific message is
returned in the global variables socket_errno and vmserrno.
Examines the OpenVMS Channel sets whose addresses are passed in ReadFds, WriteFds, and ExceptFds to see if some of their Channels are ready for reading, ready for writing, or have an exceptional condition pending. On return, select() replaces the given Channel sets with subsets consisting of the Channels that are ready for the requested operation. The total number of ready Channels in all the sets is returned.
The select() function is only useful for NETWORK file descriptors and cannot be used for any other OpenVMS I/O device.
The Channel sets are stored as bit fields in arrays of integers. The following macros are provided for manipulating such Channel sets: FD_ZERO(&fdset) initializes a Channel set fdset to the null set; FD_SET(VMS_Channel, &fdset) includes a particular Channel VMS_Channel in fdset; FD_CLR(VMS_Channel, &fdset) removes VMS_Channel from fdset; FD_ISSET(VMS_Channel, &fdset) is nonzero if VMS_Channel is a member of fdset, otherwise it is zero. The behavior of these macros is undefined if a Channel value is less than zero or greater than or equal to FD_SETSIZE * CHANNELSIZE, which is normally at least equal to the maximum number of Channels supported by the system. Make sure that the definition of these macros comes from the MultiNet types.h file, as the definitions differ from the UNIX definitions.
Caution! Process Software recommends that you do not change the value of FD_SETSIZE. However, if you must change it, make sure its value is equal to the maximum number of channels your system can handle.
Note! The MultiNet socket library is not reentrant. If you call into it from an AST (interrupt) routine, the results are unpredictable. The select() call must not be used while ASTs have been disabled. If the select() call is performed with ASTs disabled, the select() call will never return and will hang the program from which it was called. Instances when this improper call to select() can occur are as follows:
• A call to select() is performed within an AST routine (that is, executing an AST routine disables the delivery of other ASTs at the same (user-mode) priority).
• You have explicitly disabled AST delivery in normal (non-AST) code using the $SETAST system service.
FORMAT
Status = int select(int Width, fd_set,
*ReadFds, fd_set, *WriteFds, fd_set, *ExceptFds,
struct timeval, *Timeout);
FD_SET (VMS_Channel, &fdset)
FD_CLR (VMS_Channel, &fdset)
FD_ISSET (VMS_Channel, &fdset)
FD_ZERO (&fdset)
fd_set fdset;
ARGUMENTS
Width
VMS Usage: channel count
type: long (unsigned)
access: read only
mechanism: by value
The number of bits to be checked in each bit mask that represents a Channel; the Channels from 0 through Width-1 in the Channel sets are examined. Typically, width has the value returned by getdtablesize for the maximum number of Channels.
ReadFds
VMS Usage: channel bitmask
type: struct fd_set
access: modify
mechanism: by reference
A bit-mask of the Channels that select() should test for the ready for reading status. May be specified as a NULL pointer if no Channels are of interest. Selecting true for reading on a Channel on which a listen() call has been performed indicates that a subsequent accept() call on that Channel will not block.
WriteFds
VMS Usage: channel bitmask
type: struct fd_set
access: modify
mechanism: by reference
A bit-mask of the Channels that select() should test for the ready for writing status. May be specified as a NULL pointer if no Channels are of interest.
ExceptFds
VMS Usage: channel bitmask
type: struct fd_set
access: modify
mechanism: by reference
A bit-mask of the Channels that select() should test for exceptional conditions pending. May be specified as a NULL pointer if no Channels are of interest. Selecting true for exception conditions indicates that out-of-band data is present in the Channel's input buffers.
Timeout
VMS Usage: timeout
type: struct timeval
access: read only
mechanism: by reference
A maximum interval to wait for the selection to complete. If Timeout is a NULL pointer, the select blocks indefinitely. To effect a poll, the Timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure.
RETURNS
select() returns the number of
ready Channels that are contained in the Channel sets, or -1 if an error
occurred. If the time limit expires, select() returns 0. If select()
returns with an error, the Channel sets are unmodified.
Wakes a process waiting in a select() call, aborting the select() operation. This function may be called from an AST (interrupt) routine, in which case the select() call will be aborted when the AST routine completes.
FORMAT
select_wake();
Transmits a message to another socket. This function is equivalent to a sendto() called with the To and ToLen arguments specified as zero. The socket_write() function is equivalent to a send() function called with Flags specified as zero. Use the send() function only when a socket has been connected with connect(); however, you can use sendto() at any time.
If no message space is available at the socket to hold the message to be transmitted, send() blocks unless the socket has been placed in non-blocking I/O mode via the socket ioctl FIONBIO. If the socket is type SOCK_DGRAM and the message is too long to pass through the underlying protocol in a single unit, the error EMSGSIZE is returned and the message is not transmitted.
The send_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = int send (short VMS_Channel, char *Buffer, int Size[, int Flags]);
If Flags are not specified, then 0 (zero) is used.
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Buffer
VMS Usage: arbitrary
type: byte buffer
access: read only
mechanism: by reference
The address of a buffer containing the data to send.
Size
VMS Usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
The length of the buffer specified by Buffer.
RETURNS
If the send() function is
successful, the count of the number of characters sent is returned. If an error
occurs, a value of -1 is returned, and a more specific message is returned in
the global variables socket_errno and vmserrno.
Transmits a message to another socket. It is equivalent to sendto(), but takes its arguments in a different fashion and can send noncontiguous data.
If no message space is available at the socket to hold the message to be transmitted, sendmsg() blocks unless the socket has been placed in non-blocking I/O mode via the socket ioctl FIONBIO. If the socket is type SOCK_DGRAM and the message is too long to pass through the underlying protocol in a single unit, the error EMSGSIZE is returned and the message is not transmitted.
The sendmsg_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = sendmsg(VMS_Channel, Message,
Flags);
short VMS_Channel;
struct msghdr *Message;
unsigned int Flags;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Message
VMS Usage: message header
type: struct msghdr
access: read only
mechanism: by reference
A pointer to a "msghdr" structure that describes the data to be sent and the address to send it to. The access rights portion of the structure is unused.
Flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Control information that affects the sendto() function. The Flags argument can be zero or the following:
#define MSG_OOB 0x1 /* process out-of-band data */
The MSG_OOB flag causes sendto() to send out-of-band data on sockets that support this operation (such as SOCK_STREAM).
RETURNS
If the sendmsg() function is
successful, the count of the number of characters sent is returned. If an error
occurs, a value of -1 is returned, and a more specific message is returned in
the global variables socket_errno and vmserrno.
Transmits a message to another socket. It is equivalent to send(), but also allows the caller to specify the address to which to send the message. The sendto() function can be used on unconnected sockets, while send() and socket_write() cannot.
If no message space is available at the socket to hold the message to be transmitted, sendto() blocks unless the socket has been placed in non-blocking I/O mode via the socket ioctl FIONBIO. If the socket is type SOCK_DGRAM and the message is too long to pass through the underlying protocol in a single unit, the error EMSGSIZE is returned and the message is not transmitted.
The sendto_44() function is the BSD 4.4 sockaddr variant of this call. This call is used automatically when MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]IN.H is used and the program is compiled with USE_BSD44_ENTRIES defined.
FORMAT
Status = sendto(VMS_Channel, Buffer, Size,
Flags, To, ToLen);
short VMS_Channel;
char *Buffer;
int Size;
unsigned short Flags;
struct sockaddr *To;
unsigned int ToLen;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Buffer
VMS Usage: arbitrary
type: byte buffer
access: read only
mechanism: by reference
The address of a buffer containing the data to send.
Size
VMS Usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
The length of the buffer specified by Buffer.
Flags
VMS Usage: mask_word
type: word (unsigned)
access: read only
mechanism: by value
Control information that affects the sendto() function. The Flags argument can be zero or the following:
#define MSG_OOB 0x1 /* process out-of-band data */
The MSG_OOB flag causes sendto() to send out-of-band data on sockets that support this operation (such as SOCK_STREAM).
To
VMS Usage: socket_address
type: struct sockaddr
access: read only
mechanism: by reference
This optional argument is a pointer to the address to which the packet should be transmitted. The exact format of the Address argument is determined by the domain in which the communication is occurring.
ToLen
VMS Usage: socket_address_length
type: longword (unsigned)
access: read only
mechanism: by value
This optional argument contains the length of the address pointed to by the To argument.
RETURNS
If the sendto() function is
successful, the count of the number of characters sent is returned. If an error
occurs, a value of -1 is returned, and a more specific message is returned in
the global variables socket_errno and vmserrno.
Initializes the host table and DNS Name Server routines. It is usually unnecessary to call this function because the host table and Name Server routines are initialized automatically when any of the other host table routines are called.
FORMAT
(void) sethostent(StayOpen);
unsigned int StayOpen;
ARGUMENTS
StayOpen
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Specifies whether the DNS Name Resolver
should use TCP or UDP to communicate with the DNS Name Server. A nonzero value
indicates TCP, and a value of 0 (the default if sethostent() is not
called) indicates UDP.
Initializes the host table and DNS Name Server routines. It is usually unnecessary to call this function because the host table and Name Server routines are initialized automatically when any of the other host table routines are called.
FORMAT
(void) setnetent(StayOpen);
unsigned int StayOpen;
ARGUMENTS
StayOpen
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Specifies whether the DNS Name Resolver
should use TCP or UDP to communicate with the DNS Name Server. A nonzero value
indicates TCP, and a value of 0 (the default if setnetent() is not
called) indicates UDP.
Initializes the host table routines and sets the next protocol entry returned by getprotoent() to be the first entry.
FORMAT
(void) setprotoent(StayOpen);
unsigned int StayOpen;
ARGUMENTS
StayOpen
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Provided only for compatibility with UNIX
4.3BSD, and is ignored by the MultiNet software.
Initializes the host table routines and sets the next service entry returned by getservent() to be the first entry.
FORMAT
(void) setservent(StayOpen);
unsigned int StayOpen;
ARGUMENTS
StayOpen
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Provided only for compatibility with UNIX
4.3BSD, and is ignored by the MultiNet software.
Manipulates options associated with a socket. Options may exist at multiple protocol levels; however, they are always present at the uppermost socket level.
When manipulating socket options, you must specify the level at which the option resides and the name of the option. To manipulate options at the socket level, specify Level as SOL_SOCKET. To manipulate options at any other level, specify the protocol number of the appropriate protocol controlling the option. For example, to indicate that an option is to be interpreted by the TCP protocol, set Level to the protocol number of TCP; see getprotobyname().
OptName and any specified options are passed without modification to the appropriate protocol module for interpretation. The include file multinet_root:[multinet.include.sys]socket.h contains definitions for socket-level options. Options at other protocol levels vary in format and name.
FORMAT
Status = setsockopt(VMS_Channel, Level,
OptName, OptVal, OptLen);
short VMS_Channel;
unsigned int Level, OptName, OptLen;
char *OptVal;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Level
VMS Usage: option_level
type: longword (unsigned)
access: read only
mechanism: by value
The protocol level at which the option is to be manipulated. Level can be specified as SOL_SOCKET, or a protocol number as returned by getprotobyname().
OptName
VMS Usage: option_name
type: longword (unsigned)
access: read only
mechanism: by value
The option that is to be manipulated.
OptVal
VMS Usage: dependent on OptName
type: byte buffer
access: read only
mechanism: by reference
A pointer to a buffer that contains the new value of the option. The format of this buffer depends on the option requested.
OptLen
VMS Usage: option_length
type: longword (unsigned)
access: read only
mechanism: by value
The length of the buffer pointed to by OptVal.
RETURNS
If the setsockopt() is successful,
a value of 0 is returned. If an error occurs, a value of -1 is returned, and a
more specific message is returned in the global variables socket_errno
and vmserrno.
Shuts down all or part of a full-duplex connection on the socket associated with VMS_Channel. This function is usually used to signal an end-of-file to the peer without closing the socket, which would prevent further data from being received.
FORMAT
Status = shutdown(VMS_Channel, How);
short VMS_Channel;
unsigned int How;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
How
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Controls which part of the full-duplex connection to shut down. If How is 0, further receive operations are disallowed. If How is 1, further send operations are disallowed. If How is 2, further send and receive operations are disallowed.
RETURNS
If shutdown() is successful, a
value of 0 is returned. If an error occurs, a value of -1 is returned, and a
more specific error message is returned in the global variables socket_errno
and vmserrno.
Creates an end point for communication and returns an OpenVMS channel that describes the end point.
FORMAT
VMS_Channel = socket(Address_Family,
Type, Protocol);
short VMS_Channel;
unsigned int Address_Family, Type, Protocol;
ARGUMENTS
Address_Family
VMS Usage: address_family
type: longword (unsigned)
access: read only
mechanism: by value
An address family with which addresses specified in later operations using the socket should be interpreted. The following formats are currently supported; they are defined in the include file multinet_root:[multinet.include.sys]socket.h:
|
AF_INET |
Internet (TCP/IP) addresses |
Type
VMS Usage: socket_type
type: longword (unsigned)
access: read only
mechanism: by value
The semantics of communication using the created socket. The following types are currently defined:
|
SOCK_STREAM |
SOCK_DGRAM |
SOCK_RAW |
A SOCK_STREAM socket provides a sequenced, reliable, two-way connection-oriented byte stream with an out- of-band data transmission mechanism. A SOCK_DGRAM socket supports communication by connectionless, unreliable messages of a fixed (typically small) maximum length. SOCK_RAW sockets provide access to internal network interfaces. The type SOCK_RAW is available only to users with SYSPRV privilege.
The Type argument, together with the Address_Family argument, specifies the protocol to be used. For example, a socket created with AF_INET and SOCK_STREAM is a TCP socket, and a socket created with AF_INET and SOCK_DGRAM is a UDP socket.
Protocol
VMS Usage: protocol_number
type: longword (unsigned)
access: read only
mechanism: by value
A particular protocol to be used with the socket. Normally, only a single protocol exists to support a particular socket type using a given address format. However, it is possible that many protocols may exist, in which case a particular protocol must be specified by Protocol. The protocol number to use depends on the communication domain in which communication will take place.
For TCP and UDP sockets, the protocol number MUST be specified as 0. For SOCK_RAW sockets, the protocol number should be the value returned by getprotobyname().
RETURNS
If the socket() is successful, an
OpenVMS channel is returned. If an error occurs, a value of -1 is returned, and
a more specific error message is returned in the global variables socket_errno
and vmserrno.
Deassigns the OpenVMS channel from the MultiNet INET: device. When the last channel assigned to the device is deassigned, the device and attached socket are deleted.
If the SO_LINGER socket option is set and data remains in the socket's output queue, socket_close() deletes only the device. The attached socket remains in the system until the data is sent, after which it is deleted. Once socket_close() is called, there is no way to reference this socket.
Normally, channels are automatically deassigned at image exit. However, because there is a limit on the number of open channels per process, the socket_close() function is necessary for programs that deal with many connections.
FORMAT
Status = socket_close(VMS_Channel);
short VMS_Channel;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket to close.
RETURNS
If the socket_close() is
successful, a value of 0 is returned. If an error occurs, a value of -1 is
returned, and a more specific error message is returned in the global variables
socket_errno and vmserrno.
Performs a variety of functions on the network. In particular, it manipulates socket characteristics, routing tables, ARP tables, and interface characteristics. A socket_ioctl() request has encoded in it whether the argument is an input or output parameter, and the size of the argument, in bytes. Macro and define statements used in specifying a socket_ioctl() request are located in the file multinet_root:[multinet.include.sys]ioctl.h.
FORMAT
Status = socket_ioctl(VMS_Channel,
Request, ArgP);
short VMS_Channel;
unsigned int Request;
char *ArgP;
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Request
VMS Usage: ioctl_request
type: longword (unsigned)
access: read only
mechanism: by value
Which socket_ioctl() function to perform.
ArgP
VMS Usage: arbitrary
type: byte buffer
access: read, write, or modify depending on Request
mechanism: by reference
A pointer to a buffer whose format and function depend on the Request specified.
RETURNS
If the socket_ioctl() is successful, a value of 0 is returned. If an error occurs, a value of -1 is returned, and a more specific error message is returned in the global variables socket_errno and vmserrno.
For a list of the socket_ioctl()
functions supported by MultiNet, see the following pages.
Controls nonblocking I/O on a socket. If nonblocking I/O is enabled and another function is called that would have to wait for a connection, for data to arrive, or for data to be transmitted, the function completes with a -1 error return, and the global variable socket_errno is set to EWOULDBLOCK.
FORMAT
Status = socket_ioctl(VMS_Channel,
FIONBIO, Enable);
unsigned int *Enable;
ARGUMENTS
Enable
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer that specifies
whether nonblocking I/O is enabled or disabled. A value of 1 enables
nonblocking I/O, and a value of 0 disables nonblocking I/O. By default,
nonblocking I/O is disabled when a socket is created.
Retrieves the number of bytes waiting to be read. A return of 0 indicates that no data is buffered.
FORMAT
Status = socket_ioctl(VMS_Channel,
FIONREAD, Count);
unsigned int *Count;
ARGUMENTS
Count
VMS Usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
A pointer to an integer buffer that will
receive a count of the number of characters waiting to be read.
Adds routing information to the network routing tables. This function does not modify the socket itself, but rather modifies the operation of the network in general. It does not matter what the state of the socket is. Normally, to modify Internet routing tables, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCADDRT, Route);
struct rtentry *Route;
ARGUMENTS
Route
VMS Usage: routing_entry
type: struct rtentry
access: read only
mechanism: by reference
A pointer to the address of a rtentry structure that describes the route to be added. The rtentry structure is defined in multinet_root:[multinet.include.net]route.h as follows:
struct rtentry {
u_long rt_hash;
struct sockaddr rt_dst;
struct sockaddr rt_gateway;
short rt_flags;
short rt_refcnt;
u_long rt_use;
struct ifnet *rt_ifp;
};
|
Field |
Description |
|
rt_hash, rt_refcnt, rt_use, and rt_ifp |
Are ignored by SIOCADDRT and should be set to zero. |
|
rt_dst |
Specifies the address of the destination host or network. |
|
rt_gateway |
Specifies the address of the local gateway to this host or network. |
|
rt_flags |
Specifies one or more of the following flags that affect a routing entry: #define RTF_UP 0x1 /*
route useable */ RTF_UP — Indicates that the route is usable. It should always be specified. RTF_GATEWAY — Indicates that the next hop to the destination is a gateway, so that the output routines know to address the gateway rather than the destination directly. RTF_HOST — Indicates that the address specified in rt_dst is an Internet host, rather than an Internet network (the default). |
Deletes routing information from the network routing tables. This function does not modify the socket itself, but rather modifies the operation of the network in general. It does not matter what the state of the socket is. Normally, to modify Internet routing tables, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
It is impossible to obtain a list of the routes installed via socket_ioctl(). To delete a route, you must either know it already exists or use multinet_kernel_nlist() to read the routing tables directly from the networking kernel.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCDELRT, Route);
struct rtentry *Route;
ARGUMENTS
Route
VMS Usage: routing_entry
type: struct rtentry
access: read only
mechanism: by reference
A pointer to the address of a rtentry structure that describes the route to be deleted. The rtentry structure is defined in multinet_root:[multinet.include.net]route.h as follows:
struct rtentry {
u_long rt_hash;
struct sockaddr rt_dst;
struct sockaddr rt_gateway;
short rt_flags;
short rt_refcnt;
u_long rt_use;
struct ifnet *rt_ifp;
};
|
Field |
Description |
|
rt_hash, rt_refcnt, rt_use, and rt_ifp |
Are ignored by SIOCDELRT and should be set to zero. |
|
rt_dst |
Specifies the address of the destination host or network. |
|
rt_gateway |
Specifies the address of the local gateway to this host or network. |
|
rt_flags |
Specifies one or more of the following flags that affect a routing entry: #define RTF_UP 0x1 /*
route useable */ RTF_UP — Indicates that the route is usable. It should always be specified. RTF_GATEWAY — Indicates that the next hop to the destination is a gateway, so that the output routines know to address the gateway rather than the destination directly. RTF_HOST — Indicates that the address specified in rt_dst is an Internet host, rather than an Internet network (the default). |
Retrieves an indication as to whether the next byte in the stream coincides with an out-of-band or URGENT data mark.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCATMARK, AtMark);
unsigned int *AtMark;
ARGUMENTS
AtMark
VMS Usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
A pointer to an integer buffer that will
receive the indication. The buffer is set to 0 if the socket is not at the
out-of-band mark. It is set to nonzero if the socket is at the out-of-band mark.
Deletes an entry from the ARP table. This format is compatible with the UNIX 4.3BSD function of the same name.
FORMAT
Status = socket_ioctl (VMS_Channel,
SIOCDARP, ARP_Req);
struct arpreq *ARP_Req;
ARGUMENTS
ARP_Req
VMS Usage: arp_request
type: struct arpreq
access: read only
mechanism: by reference
The address of an arpreq structure that contains the protocol address and the hardware address. The arpreq structure is defined in multinet_root:[multinet.include.net]if_arp.h as follows:
struct arpreq {
struct sockaddr arp_pa; /* protocol address */
struct sockaddr arp_ha; /* hardware address */
int arp_flags; /* flags */
};
/* arp_flags and at_flags field values */
#define ATF_INUSE 0x01 /* entry in use */
#define ATF_COM 0x02 /* completed entry (enaddr valid) */
#define ATF_PERM 0x04 /* permanent entry */
#define ATF_PUBL 0x08 /* publish entry (respond for other host)
*/
#define ATF_USETRAILERS 0x10 /* has requested trailers */
#define ATF_PROXY 0x20 /* Do PROXY arp */
The arp_pa field is a sockaddr field that is set to the ip address the remote interface uses.
The arp_ha.sa_data field is 6
bytes of binary data that represents the Ethernet address of the remote
interface.
Displays an entry in the ARP table. This function is compatible with the UNIX 4.3BSD function of the same name.
FORMAT
Status = socket_ioctl (VMS_Channel,
SIOCGARP, ARP_Req);
struct arpreq *ARP_Req;
ARGUMENTS
ARP_Req
VMS Usage: arp_request
type: struct arpreq
access: modify
mechanism: by reference
The address of an arpreq structure that contains the protocol address and the hardware address. The arpreq structure is defined in multinet_root:[multinet.include.net]if_arp.h as follows:
struct arpreq {
struct sockaddr arp_pa; /* protocol address */
struct sockaddr arp_ha; /* hardware address */
int arp_flags; /* flags */
};
/* arp_flags and at_flags field values */
#define ATF_INUSE 0x01 /* entry in use */
#define ATF_COM 0x02 /* completed entry (enaddr valid) */
#define ATF_PERM 0x04 /* permanent entry */
#define ATF_PUBL 0x08 /* publish entry (respond for other host)
*/
#define ATF_USETRAILERS 0x10 /* has requested trailers */
#define ATF_PROXY 0x20 /* Do PROXY arp */
The arp_pa field is a sockaddr field that is set to the ip address the remote interface uses.
The arp_ha.sa_data field is 6
bytes of binary data that represents the Ethernet address of the remote
interface.
Adds an entry to the ARP table. This function is compatible with the UNIX 4.3BSD function of the same name.
FORMAT
Status = socket_ioctl (VMS_Channel,
SIOCSARP, ARP_Req);
struct arpreq *ARP_Req;
ARGUMENTS
ARP_Req
VMS Usage: arp_request
type: struct arpreq
access: read only
mechanism: by reference
The address of an arpreq structure that contains the protocol address and the hardware address. The arpreq structure is defined in multinet_root:[multinet.include.net]if_arp.h as follows:
struct arpreq {
struct sockaddr arp_pa; /* protocol address */
struct sockaddr arp_ha; /* hardware address */
int arp_flags; /* flags */
};
/* arp_flags and at_flags field values */
#define ATF_INUSE 0x01 /* entry in use */
#define ATF_COM 0x02 /* completed entry (enaddr valid) */
#define ATF_PERM 0x04 /* permanent entry */
#define ATF_PUBL 0x08 /* publish entry (respond for other host)
*/
#define ATF_USETRAILERS 0x10 /* has requested trailers */
#define ATF_PROXY 0x20 /* Do PROXY arp */
The arp_pa field is a sockaddr field that is set to the ip address the remote interface uses.
The arp_ha.sa_data field is 6
bytes of binary data that represents the Ethernet address of the remote
interface.
Retrieves the Internet address of a network interface. This function does not modify the socket itself, but rather examines the operation of the network in general. It does not matter what the state of the socket is. Normally, to examine Internet addresses, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCGIFADDR, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: modify
mechanism: by reference
The address of an ifreq structure that describes the interface from which to retrieve the address. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
struct sockaddr ifr_addr;
};
The ifr_name field is a null-terminated string specifying the name of the interface to be examined, such as "se0".
The ifr_addr field is a sockaddr
structure that is set to the address of the interface.
Sets the Internet address of a network interface. Normally, this is done using the MULTINET SET/INTERFACE command. This function does not modify the socket itself, but rather modifies the operation of the network in general. It does not matter what the state of the socket is. Normally, to modify Internet addresses, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCSIFADDR, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: read only
mechanism: by reference
The address of an ifreq structure that describes the address to be set. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
struct sockaddr ifr_addr;
};
The ifr_name field is a null-terminated string specifying the name of the interface to be modified, such as "se0".
The ifr_addr field is a sockaddr
structure specifying the address to be set.
Retrieves the Internet broadcast address of a network interface. This function does not modify the socket itself, but rather examines the operation of the network in general. It does not matter what the state of the socket is. Normally, to examine Internet broadcast addresses, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCGIFBRDADDR, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: modify
mechanism: by reference
The address of an ifreq structure that describes the interface from which to retrieve the broadcast address. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
struct sockaddr ifr_broadaddr;
};
The ifr_name field is a null-terminated string specifying the name of the interface to be examined, such as "se0".
The ifr_broadaddr field is a sockaddr
structure that is set to the broadcast address of the interface.
Sets the Internet broadcast address of a network interface. Normally, this is done using the MULTINET SET/INTERFACE command. This function does not modify the socket itself, but rather modifies the operation of the network in general. It does not matter what the state of the socket is. Normally, to modify Internet broadcast addresses, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCSIFBRDADDR, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: read only
mechanism: by reference
The address of an ifreq structure that describes the interface on which to set the broadcast address. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
struct sockaddr ifr_broadaddr;
};
The ifr_name field is a null-terminated string specifying the name of the interface to be modified, such as "se0".
The ifr_broadaddr field is a sockaddr
structure specifying the broadcast address to be set.
Retrieves the list of network interfaces from the networking kernel for further examination by the other SIOCGxxxx functions. This function does not modify the socket itself, but rather examines the operation of the network in general. It does not matter what the state of the socket is. Normally, to examine the network configuration, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCGIFCONF, Interface_Config);
struct ifconf *Interface_Config;
ARGUMENTS
Interface_Config
VMS Usage: interface_configuration_request
type: struct ifconf
access: modify
mechanism: by reference
The address of an ifconf structure describing a buffer in which to return the interface configuration. The ifconf structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifconf {
int ifc_len; /* size of buffer */
union {
caddr_t ifcu_buf;
struct ifreq *ifcu_req;
} ifc_ifcu;
#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */
#define ifc_req ifc_ifcu.ifcu_req /* array of structures */
};
The ifc_len field should be set to the length of the buffer specified by ifc_buf. Upon return, the ifc_len field contains the actual number of bytes written into the buffer.
The ifc_buf field should be set to a buffer large enough to hold the entire network configuration. Upon return, if VMS_Channel is an AF_INET socket the ifc_req buffer contains an array of ifreq structures, one for each interface and address. If VMS_Channel is an AF_INET6 socket, then the ifc_req buffer contains an array of ifreq6 structures, one for each address present. The array of ifreq6 structures may contain both IPv4 and IPv6 addresses.
The following short fragment of C-language code prints all Internet family interfaces and shows how to decode the ifconf structure:
n = ifc.ifc_len/sizeof(struct
ifreq);
for (ifr = ifc.ifc_req; n > 0; n--, ifr++) {
if (ifr->ifr_addr.sa_family != AF_INET) continue;
printf("%s\n",ifr->ifr_name);
}
The ifreq6 structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq6 {
char ifr_name[16];
struct sockaddr_in6 ifr_addr;
};
Retrieves the destination Internet address of a point-to-point network interface. This function does not modify the socket itself, but rather examines the operation of the network in general. It does not matter what the state of the socket is. Normally, to examine Internet addresses, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCGIFDSTADDR, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: modify
mechanism: by reference
The address of an ifreq structure that describes the interface from which to retrieve the destination address. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
struct sockaddr ifr_dstaddr;
};
The ifr_name field is a null-terminated string specifying the name of the interface to be examined, such as "se0".
The ifr_dstaddr field is a sockaddr
structure that is set to the destination address of the interface.
Sets the destination Internet address of a point-to-point network interface. Normally, this is done using the MULTINET SET/INTERFACE command. This function does not modify the socket itself, but rather modifies the operation of the network in general. It does not matter what the state of the socket is. Normally, to modify Internet addresses, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCSIFDSTADDR, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: read only
mechanism: by reference
The address of an ifreq structure that describes the interface on which to set the destination address. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
struct sockaddr ifr_dstaddr;
};
The ifr_name field is a null-terminated string specifying the name of the interface to be modified, such as "se0".
The ifr_dstaddr field is a sockaddr
structure specifying the destination address to be set.
Retrieves various control flags from a network interface. This function does not modify the socket itself, but rather examines the operation of the network in general. It does not matter what the state of the socket is. Normally, to examine interface flags, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCSIFFLAGS, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: modify
mechanism: by reference
The address of an ifreq structure that describes the state of the flags. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
short ifr_flags;
char Xfill[14];
};
The ifr_name field is a null-terminated string specifying the name of the interface to be examined, such as "se0".
The ifr_flags field receives the state of the interface flags. The following flag bits are valid:
#define IFF_UP 0x1 /*
interface is up */
#define IFF_BROADCAST 0x2 /* broadcast address valid */
#define IFF_DEBUG 0x4 /* turn on debugging */
#define IFF_LOOPBACK 0x8 /* is a loopback net */
#define IFF_POINTOPOINT 0x10 /* interface is ptp link */
#define IFF_NOTRAILERS 0x20 /* avoid use of trailers */
#define IFF_RUNNING 0x40 /* resources allocated */
#define IFF_NOARP 0x80 /* no ARP protocol */
Sets various control flags on a network
interface. Normally this is done using the MULTINET
SET/INTERFACE command.
To modify the state of a flag, first call the SIOCGIFFLAGS socket_ioctl() function, change whichever bits are necessary, and then reset the flags by calling SIOCSIFFLAGS socket_ioctl().
This function does not modify the socket itself, but rather modifies the operation of the network in general. It does not matter what the state of the socket is. Normally, to modify interface flags, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCSIFFLAGS, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: read only
mechanism: by reference
The address of an ifreq structure that describes the new state of the flags. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
short ifr_flags;
char Xfill[14];
};
The ifr_name field is a null-terminated string specifying the name of the interface to be modified, such as "se0".
The ifr_flags field specifies the new state of the interface flags. The following flags can be set or cleared:
#define IFF_UP 0x1 /*
interface is up */
#define IFF_DEBUG 0x4 /* turn on debugging */
#define IFF_NOTRAILERS 0x20 /* avoid use of trailers */
#define IFF_NOAR 0x80 /* no ARP protocol */
Retrieves the network interface metric,
or cost. The interface metric is ignored by the MultiNet software, and is not
documented further here.
Sets the network interface metric, or
cost. The interface metric is ignored by the MultiNet software, and is not
documented further here.
Retrieves the Internet address mask of a network interface. This function does not modify the socket itself, but rather examines the operation of the network in general. It does not matter what the state of the socket is. Normally, to examine Internet address masks, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCGIFNETMASK, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: modify
mechanism: by reference
The address of an ifreq structure that describes the interface from which to retrieve the address mask. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
struct sockaddr ifr_addr;
};
The ifr_name field is a null-terminated string specifying the name of the interface to be examined, such as "se0".
The ifr_addr field is a sockaddr
structure that is set to the address mask of the interface.
Sets the Internet address mask of a network interface. Normally, this is done using the MULTINET SET/INTERFACE command. This function does not modify the socket itself, but rather modifies the operation of the network in general. It does not matter what the state of the socket is. Normally, to modify Internet address masks, you use a socket created with the AF_INET and SOCK_DGRAM arguments.
FORMAT
Status = socket_ioctl(VMS_Channel,
SIOCSIFNETMASK, Interface_Req);
struct ifreq *Interface_Req;
ARGUMENTS
Interface_Req
VMS Usage: interface_request
type: struct ifreq
access: read only
mechanism: by reference
The address of an ifreq structure that describes the interface on which to set the address mask. The ifreq structure is defined in multinet_root:[multinet.include.net]if.h as follows:
struct ifreq {
char ifr_name[16];
struct sockaddr ifr_addr;
};
The ifr_name field is a null-terminated string specifying the name of the interface to be modified, such as "se0".
The ifr_addr field is a sockaddr
structure specifying the address mask to be set.
Enables transmission of broadcast messages on the specified socket.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_BROADCAST, On, sizeof(*On));
unsigned int *On;
ARGUMENTS
On
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that
specifies whether the transmission of broadcast messages is enabled or
disabled. A nonzero value enables the transmission of broadcast messages, a
value of 0 disables the transmission.
Controls the recording of debugging information by the MultiNet networking kernel.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_DEBUG, On, sizeof(*On));
unsigned int *On;
ARGUMENTS
On
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that
specifies whether debugging is enabled or disabled. A nonzero value enables
debugging. A value of 0 disables debugging.
Indicates that outgoing messages bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface, as determined by the network portion of the destination address.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_DONTROUTE, On, sizeof(*On));
unsigned int *On;
ARGUMENTS
On
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that
specifies whether SO_DONTROUTE is enabled or disabled. A nonzero value
enables SO_DONTROUTE. A value of 0 disables SO_DONTROUTE.
Retrieves and clears any error status pending on the socket. This function is only valid with the getsockopt() function.
FORMAT
Status = getsockopt(VMS_Channel,
SOL_SOCKET, SO_ERROR, Value, Length);
unsigned int *Value;
unsigned int *Length;
ARGUMENTS
Value
VMS Usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
A pointer to an integer buffer that receives the value of errno (the error number) that is pending on the socket.
Length
VMS Usage: longword_unsigned
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, contains the length of the
space pointed to by Value, in bytes. On return, it contains the actual
length, in bytes, of the Value returned.
Enables periodic transmission of messages on an idle connected socket. If the connected party fails to respond to these messages, the connection is considered broken and processes using the socket are notified via an error returned by a read.
Keepalives are a questionable use of the network in that they cause idle connections to add network traffic by constantly probing their peer. Avoid keepalives if another mechanism is available to detect the loss of a peer, such as timeouts.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_KEEPALIVE, On, sizeof(*On));
unsigned int *On;
ARGUMENTS
On
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that specifies
whether keepalives are enabled or disabled. A nonzero value enables keepalives.
A value of 0 disables keepalives.
Controls the action taken when unsent messages are queued on a socket and a socket_close() function call is issued. If the socket promises reliable delivery of data and SO_LINGER is set, socket_close() deletes only the device. The attached socket remains in the system until this data is sent or until it determines that it cannot deliver the information (a timeout period, termed the linger interval, is specified in the setsockopt() function). Only then is the attached socket deleted.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_LINGER, Linger, sizeof(*Linger));
struct linger *Linger;
ARGUMENTS
Linger
VMS Usage: linger_structure
type: struct linger
access: read only
mechanism: by reference
A pointer to a structure describing whether the SO_LINGER option is enabled or disabled.
struct linger {
int l_onoff; /* option on/off */
int l_linger; /* linger time */
};
When the l_onoff field is nonzero,
SO_LINGER is enabled. When it is 0, SO_LINGER is disabled. If SO_LINGER
is being enabled, the l_linger field specifies the timeout period, in
seconds.
Enables receipt of out-of-band data along with the regular data stream. You can use this option instead of specifying the MSG_OOB flag to the recv() or recvfrom() functions.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_OOBINLINE, On, sizeof(*On));
unsigned int *On;
ARGUMENTS
On
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that
specifies whether the SO_OOBINLINE option is enabled or disabled. A
nonzero value enables SO_OOBINLINE. A value of 0 disables SO_OOBINLINE.
Specifies the amount of buffer space that can be used to buffer received data on the socket. The default value is 6144. You can specify this option to raise the TCP window size, increase the maximum size of UDP datagrams that can be received, or increase buffer space in general.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_RCVBUF, Value, sizeof(*Value));
unsigned int *Value;
ARGUMENTS
Value
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that
specifies the new size of the receive buffer, in bytes.
This option exists only for compatibility
with UNIX 4.3BSD and has no effect on MultiNet sockets.
This option exists only for compatibility
with UNIX 4.3BSD and has no effect on MultiNet sockets.
Specifies how to reuse local addresses.
When SO_REUSEADDR is enabled, bind() allows a local port number to be used even if sockets using the same local port number already exist, provided that these sockets are connected to a unique remote port. This option allows a server to bind() to a socket to listen for new connections, even if connections are already in progress on this port.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_REUSEADDR, On, sizeof(*On));
unsigned int *On;
ARGUMENTS
On
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that
specifies whether SO_REUSEADDR is enabled or disabled. A nonzero value
enables SO_REUSEADDR. A value of 0 disables SO_REUSEADDR.
Specifies the amount of buffer space that can be used to buffer transmitted data on the socket. The default value is 6144 for TCP and 2048 for UDP. You can specify this option to raise the TCP window size, increase the maximum size of UDP datagrams that can be transmitted, or increase buffer space in general.
FORMAT
Status = setsockopt(VMS_Channel,
SOL_SOCKET, SO_SNDBUF, Value, sizeof(*Value));
unsigned int *Value;
ARGUMENTS
Value
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that
specifies the new size of the transmit buffer, in bytes.
This option exists only for compatibility
with UNIX 4.3BSD and has no effect on MultiNet sockets.
This option exists only for compatibility
with UNIX 4.3BSD and has no effect on MultiNet sockets.
Retrieves the socket type (such as SOCK_DGRAM or SOCK_STREAM). This function is only valid with the getsockopt() function.
FORMAT
Status = getsockopt(VMS_Channel,
SOL_SOCKET, SO_TYPE, sizeof(*Value));
unsigned int *Value;
ARGUMENTS
Value
VMS Usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
A pointer to an integer buffer that
receives the socket type.
Lets you specify how long an idle socket remains open if the SO_KEEPALIVE option is enabled.
If SO_KEEPALIVE is enabled, TCP_KEEPALIVE lets you specify:
|
Idle time |
The amount of time a TCP socket should remain idle before sending the first keepalive packet. |
|
Probe interval |
The amount of time between keepalive packets. |
|
Probe count |
The number of keepalive packets to be sent before the connection is closed. |
This feature is available to both the INETDRIVER and the UCXDRIVER, although it is usually accessed through the UCXDRIVER.
FORMAT
Status = setsockopt(VMS_Channel,
IPPROTO_TCP, TCP_KEEPALIVE, keepalive), sizeof(struct tcp_keepalive));
struct tcp_keepalive *keepalive
ARGUMENTS
Keepalive
VMS Usage: keepalive_structure
type: struct tcp_keepalive
access: read only
mechanism: by reference
A pointer to a structure specifying the keepalive parameter values idle_time, probe_intvl, and probe_count.
The structure TCP_KEEPALIVE definition can be found in the include file TCP.H, as follows:
struct tcp_keepalive {
int idle_time; /*Time before first probe */
int probe_intvl; /*Time between probes */
int probe_count; /*Number of probes before closing connection */
};
The idle_time and probe_intvl values are specified in seconds; probe_count is the number of probes to send before closing the connection.
The minimum value for idle_time is 75 seconds. If a value less than 75 is specified, 75 is used.
If a value of 0 (zero) is specified for any of the entries in the structure, the current value is retained.
Note! The
system default values are an idle_time value of 120 minutes, a probe_intvl
value of 75 seconds, and a probe_count value of 8.
Disables the Nagle algorithm (RFC 896) which causes TCP to have, at most, one outstanding unacknowledged small segment. By default, the Nagle algorithm is enabled, delaying small segments of output data up to 200 ms so that they can be packaged into larger segments. If you enable TCP_NODELAY, TCP sends small segments as soon as possible, without waiting for acknowledgments from the receiver or for the 200 ms TCP fast timer to expire.
FORMAT
Status = setsockopt(VMS_Channel,
IPPROTO_TCP, TCP_NODELAY, On, sizeof(*On));
unsigned int *On;
ARGUMENTS
On
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
A pointer to an integer buffer that
specifies whether the TCP_NODELAY option is enabled or disabled. A value
of 0 disables TCP_NODELAY.
Formats and prints the error code that is placed in the global variables socket_errno and vmserrno when an error occurs in one of the other socket functions. The error message is printed on the OpenVMS equivalent to the UNIX "stdout" device (normally SYS$OUTPUT), and is prefixed by the specified string.
A typical use of socket_perror() might be the following:
if (connect(s, &sin,
sizeof(sin)) < 0) {
socket_perror("connect failed");
exit(1);
}
FORMAT
(void) socket_perror(String);
char *String;
ARGUMENTS
String
VMS Usage: arbitrary_string
type: ASCIZ string
access: read only
mechanism: by reference
A C-language string with information
about the last call to fail. This is printed as a prefix to the error message.
Reads messages from a socket. See also recv() and recvfrom(). This function is equivalent to a recv() function called with Flags specified as zero. The length of the message received is returned as the status. If a message is too long to fit in the supplied buffer and the socket is type SOCK_DGRAM, excess bytes are discarded.
If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is non-blocking (see socket_ioctl()). In this case, a status of -1 is returned, and the global variable socket_errno is set to EWOULDBLOCK.
FORMAT
int socket_read (short VMS_Channel, char *Buffer, int Size);
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Buffer
VMS Usage: arbitrary
type: byte buffer
access: write only
mechanism: by reference
The address of a buffer into which to place the data read.
Size
VMS Usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
The length of the buffer specified by Buffer. The actual number of bytes read is returned in the Status.
RETURNS
If the socket_read() routine is
successful, the count of the number of characters received is returned. A
return value of 0 indicates an end-of-file condition; that is, the connection
has been closed. If an error occurs, a value of -1 is returned, and a more
specific message is returned in the global variables socket_errno and vmserrno.
Writes a message to another socket. This function is equivalent to a send() function called with Flags specified as zero.
This function can be used only when a socket has been connected with connect().
If no message space is available at the socket to hold the message to be transmitted, socket_write() blocks unless the socket has been placed in non-blocking I/O mode via the socket ioctl FIONBIO. If the socket is type SOCK_DGRAM and the message is too long to pass through the underlying protocol in a single unit, the error EMSGSIZE is returned and the message is not transmitted.
FORMAT
int socket_write (short VMS_Channel, char *Buffer, int Size);
ARGUMENTS
VMS_Channel
VMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Buffer
VMS Usage: arbitrary
type: byte buffer
access: read only
mechanism: by reference
The address of a buffer containing the data to send.
Size
VMS Usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
The length of the buffer specified by Buffer.
RETURNS
If the socket_write() routine is
successful, the count of the number of characters sent is returned. If an error
occurs, a value of -1 is returned, and a more specific error message is
returned in the global variables socket_errno and vmserrno.
Formats a string corresponding to the error code that is placed in socket_errno and vmserrno when an error occurs in one of the other socket functions.
FORMAT
(char *) vms_errno_string();
RETURNS
The vms_errno_string() function
returns a pointer to the string.
Support for SCTP (Stream Control Transport Protocol) has been added to the MultiNet C socket library, with the shareable image MULTINET:TCPIP$SCTP_SHR.EXE. SCTP provides end-to-end guaranteed delivery without the potential of blocking that TCP can encounter. SCTP also allows for multiple streams within a conventional pairing of sockets between two IP addresses. Messages on one stream can be sent and received independently of other streams on the connection. See RFC 4960 for more information about SCTP.
Definitions for routines and constants
are in MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]SCTP.H
MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]SCTP_CONSTANTS.H
MULTINET_ROOT:[MULTINET.INCLUDE.NETINET]SCTP_UIO.H.
To use SCTP create a socket with the following parameters:
socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)
The following routines are supported:
Description
sctp_opt_info is a wrapper library function that can be used to get SCTP level options on a
socket.
Parameter Usage
sd is the socket descriptor for which the option is requested.
For one-to-many style sockets, id
specifies the association to query.
For one-to-one style sockets, id is ignored.
opt specifes the SCTP socket option to get.
arg is an option-specific structure buffer provided by the caller. size is a value-result parameter,
initially containing the size of the buffer pointed to by arg and modified on return to indicate the
actual size of the value returned.
Returns
On success, sctp_opt_info returns 0 and on failure -1 is returned with errno
set to the appropriate error code.
Supported Options:
SCTP_RTOINFO
SCTP_ASSOCINFO
SCTP_INITMSG
SCTP_NODELAY
SCTP_AUTOCLOSE
SCTP_PRIMARY_ADDR
SCTP_DISABLE_FRAGMENTS
SCTP_PEER_ADDR_PARAMS
SCTP_EVENTS
SCTP_I_WANT_MAPPED_V4_ADDR
SCTP_MAXSEG
SCTP_STATUS
SCTP_GET_PEER_ADDR_INFO
Description
sctp_bindx adds or removes a set of bind addresses passed in the array addrs
to/from the socket sd. addrcnt is the number of addresses in the array and the
flags parameter indicates if the addresses need to be added or removed.
An application can use SCTP_BINDX_ADD_ADDR to associate additional addresses
with an endpoint after calling bind(2). SCTP_BINDX_REM_ADDR directs SCTP to
remove the given addresses from the association. A caller may not remove all
addresses from an association. It will fail with EINVAL.
Parameter Usage
If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. If sd is
an IPv6 socket, the addresses passed can be either IPv4 or IPv6 addresses.
addrs is a pointer to an array of one or more socket addresses. Each address
is contained in its appropriate structure (i.e. struct sockaddr_in or struct
sockaddr_in6). The family of the address type must be used to distinguish the
address length.
The caller specifies the number of addresses in the array with addrcnt.
The flags parameter can be either SCTP_BINDX_ADD_ADDR or SCTP_BINDX_REM_ADDR.
Return Value
On success, 0 is returned. On failure, -1 is returned, and errno is set appropriately.
Errors
EBADF - sd is not a valid descriptor.
ENOTSOCK
- sd is a descriptor for a file, not a socket.
EFAULT
- Error while copying in or out from the user address space.
EINVAL
- Invalid port or address or trying to remove all addresses from an association.
EACCES
- The address is protected, and the user
is not the super-user.
Description
sctp_getpaddrs returns all peer addresses in an association. On return, addrs
will point to a dynamically allocated packed array of sockaddr structures of
the appropriate type for each address. The caller should use sctp_freepaddrs
to free the memory. Note that the in/out parameter addrs must not be NULL.
Parameter Usage
If sd is an IPv4 socket, the addresses returned will be all IPv4 addresses. If
sd is an IPv6 socket, the addresses returned can be a mix of IPv4 or IPv6
addresses.
For one-to-many style sockets, id specifies the association to query. For
one-to-one style sockets, id is ignored.
sctp_freepaddrs frees all the resources allocated by sctp_getpaddrs.
Return Value
On success, sctp_getpaddrs returns the number of peer addresses in the
association. If there is no association on this socket, 0 is returned and the
value of *addrs is undefined. On error, sctp_getpaddrs returns -1 and the
value of *addrs is undefined.
The sctp_freepaddrs() and sctp_freeladdrs() functions are used to release the
memory allocated by previous calls to sctp_getpaddrs() or sctp_getladdrs()
respectively.
Description
sctp_getladdrs returns all locally bound addresses on a socket. On return,
addrs will point to a dynamically allocated packed array of sockaddr
structures of the appropriate type for each local address. The caller should
use sctp_freeladdrs to free the memory. Note that the in/out parameter addrs
must not be NULL.
Parameter Usage
If sd is an IPv4 socket, the addresses returned will be all IPv4 addresses. If
sd is an IPv6 socket, the addresses returned can be a mix of IPv4 or IPv6
addresses.
For one-to-many style sockets, id specifies the association to query. For
one-to-one style sockets, id is ignored.
If the id field is set to 0, then the locally bound addresses are returned
without regard to any particular association.
sctp_freeladdrs frees all the resources allocated by sctp_getladdrs
Return Value
On success, sctp_getladdrs returns the number of local addresses bound to the
socket. If the socket is unbound, 0 is returned and the value of *addrs is undefined. On error, sctp_getladdrs returns -1 and the value of *addrs is
undefined.
Description
The sctp_freepaddrs() and sctp_freeladdrs() functions are used to release the
memory allocated by previous calls to
sctp_getpaddrs() or sctp_getladdrs() respectively.
Description
sctp_connectx initiates a connection to a set of addresses passed in the array
addrs to/from the socket sd. addrcnt is the number of addresses in the array.
Paramter Usage
If sd is an IPv4 socket, the addresses passed must be IPv4 addresses. If sd is
an IPv6 socket, the addresses passed can be either IPv4 or IPv6 addresses.
addrs is a pointer to an array of one or more socket addresses. Each address
is contained in its appropriate structure (i.e. struct sockaddr_in or struct sockaddr_in6). The family of the address type must be used to distinguish the
address length.
The caller specifies the number of addresses in the array with
addrcnt.
Return Value
On success, 0 is returned. On failure, -1 is returned, and errno is set
appropriately.
Errors
EBADF
- sd is not a valid descriptor.
ENOTSOCK
- sd is a descriptor for a file, not a
socket.
EFAULT
- Error while copying in or out from the
user address space.
EINVAL
- Invalid port or address.
EACCES
- The address is protected, and the user
is not the super-user.
EISCONN
- The socket is already connected.
ECONNREFUSED
- No one listening on the remote
address.
ETIMEDOUT
- Timeout while attempting connection. The server may be too busy to accept
new connections. Note that for IP sockets the timeout may be very long when
syncookies are enabled on the server.
ENETUNREACH
- Network is unreachable.
EADDRINUSE
- Local address is already in use.
EINPROGRESS
- The socket is non-blocking and the connection cannot be completed
immediately. It is possible to select(2) or poll(2) for completion by
selecting the socket for writing. After select indicates writability, use
getsockopt(2) to read the SO_ERROR option at level SOL_SOCKET to determine
whether connect completed successfully (SO_ERROR is zero) or unsuccessfully
(SO_ERROR is one of the usual error codes listed here, explaining the reason
for the failure).
EALREADY
- The socket is non-blocking and a previous connection attempt has not yet
been completed.
EAGAIN
- No more free local ports or insufficient entries in the routing cache. For
PF_INET see the net.ipv4.ip_local_port_range sysctl in ip(7) on how to
increase the number of local ports.
EAFNOSUPPORT
- The passed address didn't have the correct address family in its sa_family
field.
EACCES, EPERM
- The user tried to connect to a broadcast address without having the socket
broadcast flag enabled or the connection request failed because of a local
firewall rule.
Description
sctp_getassocid -- return an association id for a specified socket
address.
The sctp_getassocid() call attempts to look up the specified socket
address addr and find the respective association identification.
Return Values
The call returns the association id upon success and 0 is returned upon
failure.
Errors
The sctp_getassocid() function can return
the following errors.
ENOENT- The address does not have an
association setup to it.
EBADF - The argument s is not a valid descriptor.
ENOTSOCK - The argument s is not a socket.
Description
sctp_getaddrlen - return the address length of an address family
The sctp_getaddrlen() function returns the size of a specific address family.
This function is provided for application binary compatibility since it provides
the application with the size the operating system thinks the specific address
family is. Note that the function will actually create an SCTP socket and then
gather the information via a getsockopt() system calls. If for some reason a
SCTP socket cannot be created or the getsockopt() call fails, an error will be
returned with errno set as specified in the socket() or getsockopt() system call.
Return Values
The call returns the number of bytes that the operating system expects for the
specific address family or SOCKET_ERROR (-1).
Errors
The sctp_getaddrlen() function can
return the following errors:
EINVAL - The address family specified does NOT exist.