$!+ $! FACILITY: LIBCMU $! $! Abstract: $! Creates LIBCMU.DOC by extracting comments from LIBCMU.C Output from $! procedure shoud be redirected to a file using the /OUTPUT qualifier. $! $! v1.0.0 $! 8-DEC-1993 Mike O'Malley, 1956 $! creator -- it's alive! $!- $ v = f$verify(0) LIBCMU, Copyright (C) 1993,1994 by Mike O'Malley This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Facility: LIBCMU Abstract: Socket interface routines for CMU-OpenVMS/IP v6.6 Module Description: This collection of routines provides the standard `C' programming interface CMU-OpenVMS/IP network transport. Routine provided: int socket(int domain, int type, int protocol) int bind(int s, struct sockaddr *name, int namelen) int connect(int s, struct sockaddr *name, int namelen) int listen (int s, int backlog) int accept(int s, struct sockaddr *addr, int *addrlen) int recv(int s, char *buf, int len, int flags) int recvfrom(int s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen) int send(int s, char *msg, int len, int flags) int sendto(int s, char *msg, int len, int flags, struct sockaddr *to, int tolen) int shutdown(int s, int how) int select(int nfds, int *readfds, int *writefds, int *execptfds, struct timeval *timeout) int getsockname(int s, struct sockaddr *name, int *namelen) int getpeername(int s, struct sockaddr *name, int *namelen) int getsockopt(int s, int level, int optname, char *optval, int *optlen) int setsockopt(int s, int level, int optname, char *optval, int *optlen) int gethostname(char *name, int namelen) struct servent *getservbyname(char *name, char *proto) struct servent *getservbyport(int port, char *proto) struct hostent *gethostbyname(char *name) struct hostent *gethostbyaddr(char *addr, int len, int type) int ioctl(int s, int request, char *argp) int fcntl(int s, int request, int arg) The following routines were named to prevent conflict with routine names in the VAXCRTL: int cmu_read(int s, char *buf, int len) int cmu_write(int s, char *msg, int len, int flags) int cmu_close(int s) The following routines may be called from outside this library: int *cmu_stdin_open(char *name) int cmu_stdin_read(flags,buf,len,prompt,mask) int cmu_get_sdc(int s) int cmu_trnlnm(char *table, char *name, char *mode, char *buff) int cmu_get_errno(NetIO_Status_Block *iosb) The following routines should not be accessed outside this library: int cmu_listen_accept(int s) int cmu_queue_listen(int s) int cmu_read_ast(int s) int cmu_write_ast(int s) int cmu_queue_net_read(int s) Acknowledgements: Guidence, concepts, examples derived from the works of: UNIXSHR - unknown NETLIB - Matt Madison, RPI Author: Mike O'Malley (mlo) September 1993 Digital Equipment Corp. Sandia National Laboratories Digital Consulting Scientific Computing Center, User Support Albuquerque, NM Mike.OMalley@aqo.mts.dec.com mlomall@sandia.GOV With modifications by: Chen He (che) (617)566-0001 Ext.2919 IDX Systems Corp. he@chen.idx.com THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE. THIS SOFTWARE SHOULD NOT BE CONSTRUED AS SUPPORTED, OR A COMMITMENT OF SUPPORT, BY DIGITAL EQUIPMENT CORPORATION. Modifications: 14-MAR-1994 mlo 1.2 Added getpeername routine. Modified all qio calls to use vaxc$errno for status; modified get_cmu_errno to return EVMSERR when the IOSB is zero; perror() will now print the vms specific error. 14-MAR-1994 mlo 1.1.3 Modified all qio calls that use cmu_read_ast to NOT use the event flag. Set the event flag in the cmu_read_ast routine. In cmu_read_ast make the socket invalid if a socket shutdown was detected. In select insure that all sockets are still valid. Modified exception conditions in cmu_read_ast routine. 8-FEB-1994 che 1.1.2 Fixed accept function to return the remote host information. 4-FEB-1994 che 1.1.1 Fixed problem in gethostbyaddr; it worked after called gethostbyname but would get access violation when it was called first time. 18-JAN-1994 mlo 1.1.0 Removed references to `sys/', `vnet/', `netinet/' from include files. 18-JAN-1994 mlo 1.0.8 Fixed serious problems in gethostbyaddr; never worked! 10-DEC-1993 mlo 1.0.7 In cmu_read_ast detect `socket close by peer' event. 10-DEC-1993 mlo 1.0.6 detect ENOCONN in connect. Seems that the TCP$OPEN qio does not fail when the remote system is not reachable. 28-NOV-1993 mlo 1.0.5 in recvfrom don't check error status if socket is not ready to read. Caused bad return status. 8-NOV-1993 mlo 1.0.4 detect numeric address passed to gethostbyname 18-OCT-1993 mlo 1.0.3 corrected return from cmu_get_errno 7-OCT-1993 mlo 1.0.2 add write and exception events to select. 6-OCT-1993 mlo 1.0.1 add better error reporting via errno 16-SEP-1993 mlo 1.0.0 original #include #include int socket(int domain, int type, int protocol) Description: Creates an endpoint of a connection. domain - AF_INET is the only address domain supported at this time. type - SOCK_STREAM or SOCK_DGRAM protocol - IPPROTO_TCP, IPPROTO_UDP. If IPPROTO_IP (default) is specified protocol will be chosen that matches `type'. Returns: If successful a socket number is returned, otherwise, a -1 is returned and errno is set. #include #include int bind(int s, struct sockaddr *name, int namelen) Description: binds a name (address/port) to a socket. Socket (s) must have been created with call to socket. s - valid socket descriptor name - address of sockaddr structure for local host port information namelen - length of the name structure in bytes Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. #include #include int connect(int s, struct sockaddr *name, int namelen) Description: initiates a connection on a socket. s - valid socket descriptor name - pointer to an address structure for the remote port namelen - length of the name structure in bytes Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. int listen (int s, int backlog) Description: Sets the maximum limit of outstanding connection requests for a socket that is connection-oriented. s - a valid socket descriptor of type SOCK_STREAM backlog - maximum number of pending connections that may be queued Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. #include #include int accept(int s, struct sockaddr *addr, int *addrlen) Description: Accepts a connection on a socket. s - valid socket that is listening addr - sockaddr address structure filled with information from the accepted connection addrlen - length of returned address structure Returns: Nonnegative integer that is the descriptor for the accepted socket or -1 on error. Addition error information is specified in the global variable errno. #include #include int recv(int s, char *buf, int len, int flags) Description: Receive bytes from a connected socket. s - a valid socket descriptor buf - address of buffer to where input data is placed len - max size of buf flags - 0 or MSG_PEEK may be specified. Returns: Number of bytes read from the socket, -1 on error. Addition error information is specified in the global variable errno. #include #include int recvfrom(int s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen) Description: receives bytes from a socket from any source. s - a valid socket descriptor buf - address of buffer to where input data is placed len - max size of buf flags - 0 or MSG_PEEK may be specified. from - address of sockaddr structure address of the socket which the data is received from. May be specified as 0; no information will be returned. fromlen - length of from structure returned. Returns: Number of bytes read from the socket, -1 on error. Addition error information is specified in the global variable errno. #include #include int send(int s, char *msg, int len, int flags) Description: Send bytes through a socket to its connected peer. s - a valid socket descriptor buf - address of buffer of data to be sent len - size of buf flags - 0 or MSG_PEEK may be specified. Returns: Number of bytes written to the socket, -1 on error. Addition error information is specified in the global variable errno. #include #include int sendto(int s, char *msg, int len, int flags, struct sockaddr *to, int tolen) Description: Send bytes through a socket to any other socket. s - a valid socket descriptor buf - address of buffer of data to be sent len - size of buf flags - none supported. to - address of sockaddr structure which contains the address of the socket which the data is to be written. tolen - length of from structure returned. Returns: Number of bytes written to the socket, -1 on error. Addition error information is specified in the global variable errno. #include int shutdown(int s, int how) Description: Shuts down all or part of a connection on a socket. s - a valid socket how - one of: 0 - no more receives 1 - no more sends 2 - no more receives or sends Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. #include #include int select(int nfds, int *readfds, int *writefds, int *execptfds, struct timeval *timeout) Description: Allows the user to poll or check a group of sockets for I/O activity. It can check what sockets are ready to be read or written, or what sockets have a pending exception. Notes: This routine (and library) only handles 32 file descriptors max (0-31). The `fd_set' type is long int. To select on file descriptor 0 (stdin) the routine cmu_stdin_open must be used to setup the file descriptor. See routines cmu_stdin_open and cmu_stdin_read for further information. nfds - maximum file descriptor +1 to scan readfds - address of descriptor bit mask to scan for read events writefds - address of descriptor bit mask to scan for write events exceptfds - address of descriptor bit mask to scan for exception events timeout - specifies how long to wait for a read, write, or exception event. If timeout argument is NULL select will block until one of the specified descriptors is ready. Returns: Number of socket descriptors ready for I/O or that have exceptions, 0 if the operation timed out, -1 on error. Addition error information is specified in the global variable errno. #include #include int getsockname(int s, struct sockaddr *name, int *namelen) Description: Returns the name associated with a socket s - a valid socket descriptor name - sockaddr address structure where data is to be written namelen - number of bytes written to name Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. #include #include int getpeername(int s, struct sockaddr *name, int *namelen) Description: Returns the name associated with a socket s - a valid socket descriptor name - sockaddr address structure where data is to be written namelen - number of bytes written to name Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. #include #include int getsockopt(int s, int level, int optname, char *optval, int *optlen) Description: Returns the options set on a socket. Note: This routine does nothing. Always returns -1 with errno set to ENOPROTOOPT. Returns: (if it did do something) 0 on success, -1 on error. Addition error information is specified in the global variable errno. #include #include int setsockopt(int s, int level, int optname, char *optval, int *optlen) Description: (if it did do something) Set the options on a socket. Note: This routine does nothing. Always returns -1 with errno set to ENOPROTOOPT. Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. int gethostname(char *name, int namelen) Description: Returns the name currently associated to the host. name - address of buffer to write name of host namelen - length of name buffer Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. struct servent *getservbyname(char *name, char *proto); Description: returns a servent structure filled in with information about the requested service. name - pointer to character string of service to search for proto - pointer to character string of protocol type desired (tcp, udp) Notes: The usual services text file is not supported. Instead, services are are logical names defined in the system logical name table. Services logical names are defined as follows: $ DEFINE /SYSTEM INET$SERVICE_service_name_protocol value Example: To define the service telnet, protocol tcp, port 23 use the following statement: $ DEFINE/SYSTEM INET$SERVICE_TELNET_TCP 23 Returns: Returns the address of a servent structure on success, the NULL pointer on error (see cmu_trnlnm). struct servent *getservbyport(int port, char *proto); Description: returns a servent structure filled in with information about the requested port. port - int value of port number to search for proto - pointer to character string of protocol type desired (tcp, udp) Notes: The usual services text file is not supported. Instead, services are are logical names defined in the system logical name table. Services logical names are defined as follows: $ DEFINE /SYSTEM INET$SERVICE_port_number_protocol service Example: To define the service telnet, protocol tcp, port 23 use the following statement: $ DEFINE/SYSTEM INET$SERVICE_23_TCP TELNET Returns: Returns the address of a servent structure on success, the NULL pointer on error (see cmu_trnlnm). struct hostent *gethostbyname(char *name) Description: returns the host address associated with the given name. name - pointer to a character string that contains the host/domain name to search for. Return: Returns the address of a hostent structure on success, the NULL pointer on error. Additional error information is returned in the global variable errno. struct hostent *gethostbyaddr(char *addr, int len, int type) Description: Return official name of host given the host address. addr - a pointer to a series of bytes in network order specifying the address of the host to search for. len - number of bytes in the addr type - address format. Only AF_INET is supported. Return: Returns the address of a hostent structure on success, the NULL pointer on error. Additional error information is returned in the global variable errno. #include int ioctl(int s, int request, char *argp) Description: control device. s - a valid socket descriptor request - one of: FIOCLEX - set exclusive use on socket FIONCLEX - remove exclusive use FIONBIO - set/clear non-blocking i/o FIONREAD - get # bytes ready to be read SIOCGIFADDR - get ifnet addres SIOCGIFFLAGS - get ifnet flags SIOCGIFCONF - get ifnet list argp - address of buffer for return information Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. #include int fcntl(int s, int request, int arg) Description: file control. s - a valid socket descriptor request - One of: F_GETFL - get file flags F_SETFL - set file flags arg - flags to set Returns: Value of flags or -1 on error. Addition error information is specified in the global variable errno. #include #include int cmu_read(int s, char *buf, int len) Description: Receive bytes from a connected socket. To avoid conflict and link warnings regarding the `read' routine in the standard VAXCRTL this routine name is `cmu_read'. A direct call to cmu_read(s,b,l) is required to read a socket. s - a valid socket descriptor buf - address of buffer to where input data is placed len - max size of buf Returns: Number of bytes read from the socket, -1 on error. Addition error information is specified in the global variable errno. #include #include int cmu_write(int s, char *msg, int len, int flags) Description: Send bytes through a socket to its connected peer. s - a valid socket descriptor buf - address of buffer of data to be sent len - size of buf Returns: Number of bytes written to the socket, -1 on error. Addition error information is specified in the global variable errno. int cmu_close(int s) Description: Closes a connection and deletes a socket descriptor. To avoid confusion and link warnings regarding the `close' routine for other file descriptors this routine name is `cmu_close'. A "#define close(s) cmu_close(s)" or direct call to cmu_close(s) is needed in routines close sockets managed by this library. If this routine is called with a socket descriptor that is not managed by this library it will pass that descriptor to the system close routine. s - an open socket descriptor Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. #include "libcmu.h" int *cmu_stdin_open(char *name) Description: To have stdin a device that can be selected the descriptor needs to be allocated within the domain of these routines. This routine allocates the file descriptor and returns the address of the FD_ENTRY so the user can control reads/writes and still use select to see if the descriptor is ready. Optionally the user can use the following routine to queue reads on stdin. name - character string device name of the device to assign a channel to. Returns: Address of an FD_ENTRY structure on success, -1 on error. Addition error information is specified in the global variable errno. int cmu_stdin_read(int flags, char *buf, int len, char *prompt, int mask) Description: queue an i/o to the descriptor described in sd[0]. Since this read is ment to be used with the select call a non-blocking qio is done. The completion routine will set the file descriptor and event flag on read completion. flags - qio read modifiers buf - to receive characters read len - max characters to read prompt - prompt string for read mask - read terminator mask Returns: Status from the SYS$QIO system service call. int cmu_get_sdc(int s) Description: Returns the assigned VMS channel for a particular file descriptor s - a valid socket descriptor Returns: If successful a VMS i/o channel number is returned otherwise a 0 is returned and errno is set. int cmu_trnlnm(char *table, char *name, char *mode, char *buff, int len) Description: Translate a logical name. Terminate the output buffer with a null character. table - pointer to string that describes the logical name table to search name - pointer to character string of logical name to search for mode - mimimum access mode of logical name (kernel, exec, super, user) buff - pointer to buffer that is to receive the translation len - size of buff Returns: 0 on success. -1 on error. vaxc$errno is set to status of sys$trnlnm service call and errno is set to EVMSERR. int cmu_get_errno(NetIO_Status_Block *iosb) Description: returns best guess value for errno be examining the i/o status block. iosb - address of an i/o status block. Returns: Returns an errno value. int cmu_listen_accept(int s) Description: AST completion routine called when a connection completes on an open listening socket. s - valid socket descriptor Returns: None. int cmu_queue_listen(int s) Description: Queue a read that will accept a TCP connection s - a valid socket descriptor Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno. int cmu_read_ast(int s) Description: AST read completion routine. Sets the global sys_readfds to indicate the socket is ready to read or sys_exceptfds if there was an error. s - valid socket descriptor Returns: Nothing. int cmu_write_ast(int s) Description: AST write completion routine. Sets the global sys_writefds to indicate the socket is ready to be written or sys_exceptfds if there was an error. s - valid socket descriptor Returns: Nothing. int cmu_queue_net_read(int s) Description: Queue a read on socket `s' to be completed by net_read_ast. This routine will also allocate an event flag and receive buffer if necessary. s - valid socket descriptor Returns: 0 on success, -1 on error. Addition error information is specified in the global variable errno.