README.TXT SOCKETSHR V0.9-D 25-Jan-1995 Eckart Meyer meyer@ifn.ing.tu-bs.de NOTE: SOCKETSHR is still in beta test. Many people have tested SOCKETSHR meanwhile and it should be quite stable now. V0.9-D is only tested on UCX V3.2 and CMU/IP V6.6-5A. I've no access to other TCP/IP packages - I've left that for you ;-) What is SOCKETSHR ? ------------------- SOCKETSHR is a TCP/IP package independent socket library for OpenVMS (VAX and Alpha). All TCP/IP packages come with their own socket library, why do we need another one? The advantage of SOCKETSHR is that it is implemented as a shared image which can be used with all well known TCP/IP packages. Programs linked to it may run on all of them *without relinking*. This makes it possible to use only one executable if different TCP/IP packages are used in a network. It makes it much easier to distribute a program in binary form to the public. Many programs like ARCHIE, GOPHER, MOSAIC, FINGER, TALK, etc. may benefit from being linked against SOCKETSHR and distributed as binaries. SOCKETSHR also supports the standard i/o routines like fputs() etc. How to get it? -------------- The beta test versions can be obtained via anonymous FTP from 'ftp.ifn.ing.tu-bs.de' in directory 'vms/socketshr': SOCKETSHR_BIN_???.ZIP - shared images for OpenVMS VAX and AXP SOCKETSHR_SRC_???.ZIP - sources containing the UCX and the NETLIB V1 Version. NETLIB017.ZIP - Matt Madisons NETLIB V1.7 kit. This is a site in Germany at the Technical University of Braunschweig. Later it may appear on other well known servers. How to install ? ---------------- This is really easy. Unzip the appropriate .ZIP file to a temporay directory and move the shared images to SYS$COMMON:[SYSLIB] or to any other directory (when moving socketshr.h into another directory, you should define VAXC$INCLUDE or DECC$SYSTEM_INCLUDE to also point to this directory). Define the logical SOCKETSHR to point to the image file, e.g.: $ define/system socketshr sys$share:socketshr_netlib1.exe Add this command to the system startup file (SYS$MANAGER:SYSTARTUP_V5.COM). SOCKETSHR_BIN_???.ZIP contains: README.TXT This file SOCKETSHR.H Header file with #define's SOCKETSHR_NETLIB1.EXE VAX shared image for NETLIB V1 SOCKETSHR_NETLIB1.ALPHA_EXE Alpha shared image for NETLIB V1 SOCKETSHR_UCX.EXE VAX shared image for UCX only SOCKETSHR_UCX.ALPHA_EXE Alpha shared image for UCX only TYPES.H, IOCTL.H and FILE.H Header files used in programs. PROTOCOLS. IP protocol definitions. Used by the getproto* routines. SERVICES. service definitions. Used by the getserv* routines. *.OLB, *.OBJ, *.OPT Object files, libraries and option files to link the shared image. LINK.COM Used to link SOCKETSHR_xxx.EXE The Alpha versions may be renamed to .EXE. You may relink the shared image by typing "@LINK". The NETLIB version implements a socket library and network I/O is based on NETLIB. You must install NETLIB V1.7 or higher to use this version. ** This is the recommended version **. The UCX version is based on the UCX socket library. SOCKETSHR_UCX provides the SOCKETSHR interface which additionally contains the standard i/o routines. It has all bugs of the UCX socket library... (the NETLIB version has its own bugs :-). You may switch between the different versions by simply redefine the logical SOCKETSHR to one of the shared images. No relinking is required. How is it implemented? ---------------------- SOCKETSHR comes as a shared image containing entries named SI_routinename, e.g. SI_SOCKET, SI_GETHOSTBYNAME. The file SOCKETSHR.H should be included in a C program, which contains Definitions like "#define socket si_socket" ("SI" stands for "Socket Interface"). Also, SOCKETSHR.H defines routine prototypes. The first approach to implement SOCKETSHR was to only have some jacket routines which subsequently call the package specific routines. A Version for CMU/IP's UNIXSHR library has been built some years ago (in fact, this was simply the socket handling routines stolen from UNIXSHR and some additional routines - even the prefix SI was stolen from UNIXSHR). Later, a version for UCX and one for LIBCMU have been built. To make it useful for other packages, the current version is built on Matt Madison's NETLIB V1, thus SOCKETSHR supports all TCP/IP packages which NETLIB supports. Most of the code of the NETLIB Version of SOCKETSHR is stolen from LIBCMU (a socket library implementation for CMU/IP by Mike O'Malley). What is supported? ------------------ In addition to the traditional socket routines SOCKETSHR also supports the standard I/O routines like fgets(), fread(), etc, including fdopen() and fileno(). These routines are simply jacket routines, which call the VAXC/DECC RTL-Routines if used with file pointers other than those used with sockets and send/recv with file pointers associated with sockets. There is no additional buffering. Here is a list of all implemented routines: Socket routines: socket returns a fd, starting with 3 bind connect listen accept recv recvfrom send sendto read write writev select 32 fd's, sockets and terminal only ioctl only a small subset, e.g. FIONBIO shutdown close getsockopt nothing implemented - NOP setsockopt dito. si_get_sdc returns VMS channel like vaxc$get_sdc For historical reasons (and may be used in future): signal directly transfered to VAXC/DECC sigvec dito. alarm dito. Database routines: getservbyname read file 'services.' getservbyport getservent setservent endservent getprotobyname read file 'protocols.' getprotobynumber getprotoent setprotoent endprotoent gethostbyname gethostbyaddr gethostname gethostent dummy, always returns NULL sethostent dummy endhostent dummy getsockname getpeername Conversion routines: inet_addr inet_ntoa ntohl ntohs htonl htons Standard I/O routines: fgetc fputc fgets fputs fread fwrite fprintf fcntl only a small subset supported fdopen only one FILE * for a socket. (fileno obsolete) fclose rewind NOP on sockets fflush NOP on sockets The getserv* and getproto* routines used the standard UNIX files 'services' and 'protocols'. They should reside in SYS$LIBRARY. A logical SOCKETSHR_SERVICES or SOCKETSHR_PROTOCOLS can be used to point to the files, e.g. $ define/system SOCKETSHR_SERVICES mydev:[mydir]services.dat Implementation Notes -------------------- The files types.h (added the FD_SET definitions for select()), ioctl.h and file.h (add definitions for fcntl()) are provided. No other .h files have been provided currently. Use the header files provided by the VAX-C or DEC-C compiler (e.g. socket.h). When compiling software ported from UNIX, define logicals SYS, NETINET etc. to point to SYS$LIBRARY. To link a program against SOCKETSHR, add to the option file: SOCKETSHR/SHARE (provided that the logical SOCKETSHR has been setup properly) VAX: SOCKETSHR has been built with VAX C. The current shared image ident is 1,3. The shared image provides two universal symbols for each routine not already defined in VAXCRTL. One entry has the SI_ prefix, the other entry is without prefix. Routines like read(), write(), close() and all standard I/O routines only have one universal symbol with prefix SI_. Without including socketshr.h those routines cannot be used with sockets. The recommended way is to include socketshr.h. AXP: SOCKETSHR has been built with DEC C. The current shared image ident is 2,3. The shared image provides two universal symbols for each routine (with the exception of SI_GET_SDC), one with the prefix SI_ and one without. This does not interfere with DECC$SHR since this image prefixes all routines with DECC$. Using the compiler switch /prefix=ansi prevents the compiler from prefixing socket routines with DECC$, thus no #defines are neccessary. Of course, read(), write(), close() and all standard I/O routines cannot be used in this case, since they *are* prefixed by DEC-C. Including socketshr.h redefines all routines to have the SI_ prefix. In this case, all routines may be used. This is the recommended use. Since AST's with UDP are supported only from NETLIB V1.7 and above, you must install at least this version. You can find the kit in the same directory as SOCKETSHR. TRACE output: The logical SOCKETSHR_DEBUG may be defined as a bit mask: 1 - show routine entries and parameters 2 - show data Output is to the terminal, but may be redirected by defining the logical SOCKETSHR_LOGFILE to a valid vms file specification. Mail list --------- A mail list has been created for diskussion of SOCKETSHR. To subscribe send a one-line message to: socketshr-request@ifn.ing.tu-bs.de The body must be one line containing subscribe The subject line is ignored. Send articles to socketshr@ifn.ing.tu-bs.de Building from sources --------------------- MMS may be used to control the building. If you don't have MMS get the clone MMK from ftp.spc.edu or ftp.wku.edu or their mirrors. (I don't have MMS, I always used MMK). Alternatively use BUILD.COM Create a directory (for example [mydir.SOCKETSHR]). If building for both VAX and Alpha the following must be executed on both architectures. $ SET DEFAULT [mydir.SOCKETSHR] Get SOCKETSHR_SRC_???.ZIP and unzip it: $ UNZIP SOCKETSHR_SRC_???.ZIP For building the NETLIB version, $ SET DEFAULT [.NETLIB] $ @SETUP ! defines some logicals If building both the VAX and Alpha version: $ @[-]arch This switches from VAX to Alpha and vice versa. Then: $ MMS or $ MMS/MACRO=(TRACE=1) !enable trace output (recommended) or $ @BUILD ! always build with trace enabled SOCKETSHR_NETLIB1.EXE will be created in the the current directory. The same procedure applies to other SOCKETSHR implementations. The prebuilt objects and binaries have the trace capabilities enabled. License ------- SOCKETSHR may be freely used and distributed. All copyright notices must be retained. 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. Bug-Reports ----------- Please report errors and suggestions to meyer@ifn.ing.tu-bs.de Eckart Meyer Institute for Telecommunications Technical University of Braunschweig Schleinitzstr. 23 38092 Braunschweig Germany Phone: +49 531 391 2454 Fax: +49 531 391 5192