From d82eeac05d2899fa30704e2c40e9dd603ff2c581 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Sat, 17 Aug 2002 07:55:51 +0000 Subject: [PATCH] UNIX sockets --- doc/client.xml | 36 +++++++++++++++------ doc/comstack.xml | 85 +++++++++++++++++++++++++++++++++----------------- doc/frontend.xml | 50 +++++++++++++++++++---------- doc/installation.xml | 17 +++++----- doc/introduction.xml | 29 ++++++++++------- 5 files changed, 144 insertions(+), 73 deletions(-) diff --git a/doc/client.xml b/doc/client.xml index 92b3860..48c699d 100644 --- a/doc/client.xml +++ b/doc/client.xml @@ -1,4 +1,4 @@ - + The YAZ client Introduction @@ -16,15 +16,24 @@ It can be started by typing - - yaz-client [options] [zurl] - + + yaz-client + -m fname + -a fname + -c fname + -v level + -p target + -u auth + -k size + zurl + + in a UNIX shell / WIN32 console. The zurl, specifies a Z39.50 host and, if specified, the client first tries to establish connection with the Z39.50 target on the host. - Options are, as usual, are prefixed by - - followed by a particular letter. + Options are prefixed by - followed by a + particular letter. The following options are supported: @@ -66,6 +75,7 @@ debug, warn, log, + malloc, all, none. @@ -80,7 +90,7 @@ - -u authentication + -u auth Specifies authentication. Usually the form user/password @@ -90,7 +100,7 @@ - -k kilobytes + -k size Specifies the maximum messages size in kilobytes. The default maximum messages for the YAZ client is 1024 @@ -114,6 +124,14 @@ yaz-client -a - localhost + + The following command connects to a local server via UNIX + socket /tmp/yaz and sets maximum message size to + 5 MB. + + + yaz-client -k 5120 unix:/tmp/yaz + Commands @@ -140,7 +158,7 @@ Syntax: - [(tcp|ssl)':']host + [(tcp|ssl|unix)':']host [:port][/base>] diff --git a/doc/comstack.xml b/doc/comstack.xml index 7409e64..4c2c6ba 100644 --- a/doc/comstack.xml +++ b/doc/comstack.xml @@ -1,10 +1,10 @@ - + The COMSTACK Module - + Synopsis (blocking mode) - + - + COMSTACK stack; char *buf = 0; int size = 0, length_incoming; @@ -61,14 +61,15 @@ if (buf) The &comstack; subsystem provides a transparent interface to different types of transport stacks for the exchange of BER-encoded data. At present, the - RFC1729 method (BER over TCP/IP), and an experimental SSL stack - are supported, but others may be added in time. The philosophy of the + RFC1729 method (BER over TCP/IP), local UNIX socket and an + experimental SSL stack are supported, but others may be added in time. + The philosophy of the module is to provide a simple interface by hiding unused options and facilities of the underlying libraries. This is always done at the risk of losing generality, and it may prove that the interface will need extension later on. - + There hasn't been interest in the XTImOSI stack for some years. @@ -105,17 +106,35 @@ if (buf) COMSTACK cs_create(CS_TYPE type, int blocking, int protocol); - + Creates an instance of the protocol stack - a communications endpoint. The type parameter determines the mode - of communication. - At present, the values - tcpip_type - and - ssl_type - are recognized. The function returns a null-pointer if a system error - occurs. The blocking parameter should be one if + of communication. At present the following values are supported: + + + + tcpip_type + TCP/IP (BER over TCP/IP) + + + ssl_type + Secure Socket Layer (SSL). This COMSTACK + is experimental and is not fully implemented. + + + unix_type + Unix socket (unix only). Fast local transfer via + file socket. See unix + 7. + + + + + + The cs_create function returns a null-pointer + if a system error occurs. + The blocking parameter should be one if you wish the association to operate in blocking mode, zero otherwise. The protocol field should be PROTO_Z3950. @@ -167,8 +186,8 @@ if (buf) - Receives a PDU from the peer. Returns the number of bytes - read. In nonblocking mode, it is possible that not all of the packet can be + Receives a PDU from the peer. Returns the number of bytes read. + In nonblocking mode, it is possible that not all of the packet can be read at once. In this case, the function returns 1. To simplify the interface, the function is responsible for managing the size of the buffer. It will be reallocated @@ -406,7 +425,7 @@ if (buf) - The format for TCP/IP addresses is straightforward: + The format for TCP/IP and SSL addresses is: @@ -419,12 +438,17 @@ if (buf) - In all transport modes, the special hostname "@" is mapped - to any local address (the manifest constant INADDR_ANY). + For TCP/IP and SSL transport modes, the special hostname "@" + is mapped to any local address + (the manifest constant INADDR_ANY). It is used to establish local listening endpoints in the server role. + For UNIX sockets, the format of an address is the socket filename. + + + When a connection has been established, you can use @@ -450,15 +474,16 @@ if (buf) cs_straddr. The str is similar to that described for cs_straddr but with a prefix denoting the &comstack; type. Prefixes supported - are tcp: and ssl: for - TCP/IP and SSL respectively. If no prefix is given, then TCP/IP - is used. The blocking is passed to + are tcp:, unix: and + ssl: for TCP/IP, UNIX and SSL respectively. + If no prefix is given, then TCP/IP is used. + The blocking is passed to function cs_create. The third parameter vp is a pointer to &comstack; stack type specific values. For SSL (ssl_type) vp is an already create - OpenSSL CTX. For TCP/IP vp is unused (can be - set to NULL. + OpenSSL CTX. For TCP/IP and UNIX vp + is unused (can be set to NULL. @@ -510,10 +535,12 @@ if (buf) Summary and Synopsis - - #include <comstack.h> - - #include <tcpip.h> /* this is for TCP/IP and SSL support */ + + #include <yaz/comstack.h> + + #include <yaz/tcpip.h> /* this is for TCP/IP and SSL support */ + #include <yaz/unix.h> /* this is for UNIX sockeL support */ + COMSTACK cs_create(CS_TYPE type, int blocking, int protocol); diff --git a/doc/frontend.xml b/doc/frontend.xml index 57b5471..297c5f3 100644 --- a/doc/frontend.xml +++ b/doc/frontend.xml @@ -1,4 +1,4 @@ - + Generic server Introduction @@ -680,7 +680,7 @@ typedef struct bend_scan_rr { - appname [-szSiTu -a apdufile -l logfile -v loglevel -c config] + appname [-szSiT1 -u uid -a apdufile -l logfile -v loglevel -c config] [listener ...] @@ -690,7 +690,7 @@ typedef struct bend_scan_rr { -a - file + apdufile Specify a file for dumping PDUs (for diagnostic purposes). The special name "-" sends output to @@ -706,6 +706,12 @@ typedef struct bend_scan_rr { current users. + -1 + + Like -S but after one session the server + exits. This mode is for debugging only. + + -T Operate the server in threaded mode. The server creates a thread @@ -745,11 +751,11 @@ typedef struct bend_scan_rr { level The log level. Use a comma-separated list of members of the set - {fatal,debug,warn,log,all,none}. + {fatal,debug,warn,log,malloc,all,none}. -u - userid + uid Set user ID. Sets the real UID of the server process to that of the given user. It's useful if you aren't comfortable with having the @@ -760,7 +766,10 @@ typedef struct bend_scan_rr { -w dir - Working directory. + The server changes to this directory during before listening + on incoming connections. This option is useful + when the server is operating from the inetd + daemon (see -i). -i @@ -771,36 +780,39 @@ typedef struct bend_scan_rr { -install - Use this to install the server as an NT service (Windows 2000/NT only). + Use this to install the server as an NT service + (Windows 2000/NT only). Control the server by going to the Services in the Control Panel. -remove - Use this to remove the server from the NT services (Windows 2000/NT only). + Use this to remove the server from the NT services + (Windows 2000/NT only). - + -t minutes Idle session timeout, in minutes. - + -k - size + size Maximum record size/message size, in kilobytes. - + - + A listener specification consists of a transport mode followed by a colon (:) followed by a listener address. The transport mode is - either tcp or ssl. + either tcp, unix: or + ssl. - + For TCP and SSL, an address has the form @@ -814,6 +826,10 @@ typedef struct bend_scan_rr { + For UNIX local socket the address is the name local file. + + + Examples @@ -821,10 +837,12 @@ typedef struct bend_scan_rr { tcp:dranet.dra.com ssl:ssl.enterprise.com:3000 + + unix:/tmp/yaz - In both cases, the special hostname "@" is mapped to + For TCP/IP and SSL, the special hostname "@" is mapped to the address INADDR_ANY, which causes the server to listen on any local interface. diff --git a/doc/installation.xml b/doc/installation.xml index 60f1aa9..101ec67 100644 --- a/doc/installation.xml +++ b/doc/installation.xml @@ -1,4 +1,4 @@ - + Compilation and Installation Introduction @@ -22,7 +22,8 @@ HP/UX SunOS/Solaris DEC Unix - OpenBSD/FreeBSD + BSDs: FreeBSD, OpenBSD, NetBSD, MAC OSX + Linux IBM AIX Data General DG/UX (with some CFLAGS tinkering) @@ -45,8 +46,8 @@ let us know about it. If you run into difficulties, we will try to help if we can, and if you solve the problems, we would be happy to include your fixes in the next release. So far, we have mostly avoided - #ifdefs for individual platforms, and we'd like to keep it that - way as far as it makes sense. + #ifdefs for individual platforms, and we'd + like to keep it that way as far as it makes sense. @@ -54,7 +55,9 @@ bug-fixes, as well as general discussion. Subscribe by sending mail to yaz-request@indexdata.dk - . + or fill-in the form + + here. General questions and problems can be directed at yaz-help@indexdata.dk @@ -67,14 +70,14 @@ Note that if your system doesn't have a native ANSI C compiler, you may have to acquire one separately. We recommend - GCC. + GCC. For UNIX, the GNU tools Autoconf, Automake and Libtool - is used to generate Makefiles and configure &yaz; for the system. + are used to generate Makefiles and configure &yaz; for the system. You do not these tools unless you're using the CVS version of &yaz;. Generally it should be sufficient to run configure without options, diff --git a/doc/introduction.xml b/doc/introduction.xml index f531c74..3ef6a0b 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,4 +1,4 @@ - + Introduction @@ -56,16 +56,21 @@ specification of the protocol (generally Z39.50-1995). In the case of base types (those originating in the ASN.1 standard itself), the prefix Odr_ is sometimes seen. Either way, look for - the actual definition in either proto.h (for the types + the actual definition in either z-core.h (for the types from the protocol), odr.h (for the primitive ASN.1 - types, or odr_use.h (for the ASN.1 - useful types). The &asn; library also - provides functions (which are, in turn, defined using &odr; - primitives) for encoding and decoding data values. Their general form is + types). + The &asn; library also provides functions (which are, in turn, + defined using &odr; primitives) for encoding and decoding data values. + Their general form is - - int z_xxx(ODR o, Z_xxx **p, int optional, const char *name); - + + int z_xxx + ODR o + Z_xxx **p + int optional + const char *name + + (note the lower-case "z" in the function name) @@ -85,7 +90,7 @@ (passively or actively, depending on the role of your application), and for exchanging BER-encoded PDUs over that connection. When you create a connection endpoint, you need to specify what transport to - use (TCP/IP or SSL). + use (TCP/IP, SSL or UNIX sockets). For the remainder of the connection's lifetime, you don't have to worry about the underlying transport protocol at all - the &comstack; will ensure that the correct mechanism is used. @@ -104,8 +109,8 @@ can use SNACC or BERUtils instead, and still have the benefits of the transparent transport approach of the &comstack; module. Secondly, we realize that you may have to fit the toolkit into an existing - event-processing structure, in a way that - is incompatible with the &comstack; interface or some other part of &yaz;. + event-processing structure, in a way that is incompatible with + the &comstack; interface or some other part of &yaz;. -- 1.7.10.4