Fresh Fish 5

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / util / fifolib-37.4.lha / FifoLib-37.4 / fifo.doc < prev next >

Wrap

Text File | 1993-10-03 | 11.2 KB | 301 lines

FIFO.DOC (c) Copyright 1990, Matthew Dillon, All Rights Reserved BIX: mdillon UUCP: dillon@overload.Berkeley.CA.US Version 3.2 (1) INSTALLATION To Install the system you must install both FIFO-HANDLER and FIFO.LIBRARY. 1> lharc -r -x -a x fifo3.lzh 1> cd fifolib 1> Copy l/fifo-handler l: 1> Copy libs/fifo.library libs: THERE IS NO MOUNTLIST OR MOUNT FOR FIFO: ... To start the handler and make FIFO: available to programs, you must RUN it from your startup-sequence. Generally the easiest way to do this is to include the following line: run <nil: >nil: l:fifo-handler IF YOU HAVE A FIFO: ENTRY IN YOUR MOUNTLIST, PLEASE DELETE IT TO PREVENT ACCIDENTLY TRYING TO MOUNT IT. (2) SIMPLE EXAMPLE TO GET YOU STARTED This is a simple example to get you started. Please refer to section (3) below for a description of the options. 1> type fifo:r 1> run type s:startup-sequence >fifo:wmKe This particular examples requires that the reader be started first (due to the 'K' flag in the writer) but also allows you to ^C the reader (the first type command) without locking up the writer. (3) USAGE FOR FIFO: FIFO: is like PIPE: but is based on fifo.library rather than its own implementation. Full master/slave support exists. Since FIFO: uses fifo.library, programs that require non-blocking IO capability can access one side of a FIFO: connection via the fifo.library instead of FIFO: The implementation of FIFO: and fifo.library is a billion times better than that for my original PIPE: handler. The primary difference with FIFO: is that it is based on a MASTER-SLAVE connection. Two MASTER-SLAVE connections going in opposite directions yields a full-duplex connection. When using FIFO: to direct one program's output to another's input you must explicitly specify one of the FIFO:'s to be the master and the other the slave, as well as specify read & write flags. The general format for accessing the FIFO: handler is as follows: FIFO:<name>/<flags> <name>: a valid fifo name name may be any combination of alpha numerics up to 64 chars long, and is case sensitive. FIFO: will append either "_m" or "_s" to the name it supplies to fifo.library depending on whether master mode or slave mode is selected. <flags>: a valid combination of flags r open for read. Allows you to read from this fifo. w open for write. Allows you to write to this fifo rw open for read & write (full duplex). This opens a full duplex connection, generally useful only in remote-shell applications. c open in cooked mode - must be specified on one side only, usually the slave side. Any data received by the slave side is cooked before continuing on to the slave. This allows the slave side, usually a shell and/or program, to change between cooked and raw mode with the standard SCREEN_MODE packet. e EOF mode (when combined with 'w'). When this file handle is closed, an EOF will be sent to the other side. If not specified, you can cause several programs to 'append' their output onto a single FIFO all of which is read by a single program. This can be useful in log-recorder applications, for example. Specifying the 'e' flag generates an EOF after the last byte of data is written to the FIFO and the writer closes it. A reader will read the data and then receive the EOF, generally terminating reader operations. k KEEP mode. If a writer opens a fifo, writes data, then closes the fifo before a reader has a chance to open the fifo, this flag prevents the data from being lost. If not specified, the data will be lost. Generally you want to specify this flag. K READER REQUIRED mode. When specified, any Write() operation to a fifo for which there is no reader will FAIL. This will prevent lockups from occuring when you use FIFO: to pipe several processes together and then ^C the last one. ** This can be an important option to use to prevent hung processes!!! ** m select master side (else slave). For example, the master side writer "mw" is paired with the slave side reader "r": mw -> r mr <- w mrw <-> rw When operating a pipe where you have a writer into the fifo and then a reader from the same fifo, one of the two must be a MASTER, with the 'm' flag specified, and the other side must be a SLAVE, with the 'm' flag NOT specified, as per the example in section (2). t tee read. Usually specified "rt" or "mrt" depending on what you want to monitor. This option causes the read stream to be a copy of available read data such that it does NOT interfere with other readers. Otherwise this fifo will compete with other fifos for read data. For a remote shell, tee operation is not desireable as a default but is useful to monitor the shell from an independant program. see the REMCLI example below. s SHELL mode, creates a separate message port for the handle, allowing the shell & progams to find their STDERR handle. (i.e. the open-* packet works properly). WARNING: use of this option increases overhead in the FIFO: device and is generally required to be specified for the slave side of a shell (i.e. newshell fifo:name/rwkecs) see the REMCLI example below. C Send ^C to all (slaves or masters) D Send ^D to all (slaves or masters) E Send ^E to all (slaves or masters) F Send ^F to all (slaves or masters) You can send one or more signal to all the slaves (or masters if 'm' is also included) using these flags. note that it is not necessary to open a file handle to so, specifying a string like this: "FIFO:fubar/C" would result in sending a ^C to all fubar slaves even though the Open() fails due to the lack of a 'r' or 'w' in the specification. SEE REMCLI.C FOR EXAMPLE IMPLEMENTATION OF COOKED MODE AND SIGNALS. (4) TECHNICAL, INTERACTION BETWEEN FIFO: and FIFO.LIBRARY LINKED FIFOS FIFO: provides a full duplex connection using TWO fifo.library FIFOS. Openning a fifo in master mode verses slave mode determines which names are used for reading and writing. You should note that when a FIFO: handle is openned for both read and write, reading from the handle actually accesses a different physical fifo than writing to the handle. Openning a FIFO: for only one direction ('r' *or* 'w') results in a half duplex connection. It is important to properly specify the rw modes for the fifo. FIFO: device fifo.library Open("FIFO:junk/w", 1005); junk_s Open("FIFO:junk/r", 1005); junk_m Open("FIFO:junk/rw",1005); junk_s (w), junk_m (r) Open("FIFO:junk/wm", 1005); junk_m Open("FIFO:junk/rm", 1005); junk_s Open("FIFO:junk/rwm", 1005); junk_m (w), junk_s (r) (5) REMOTE SHELL APPLICATIONS It is extremely easy to set up a fifo to interface a program with a remote shell. The FIFO: fully supports remote shells including the ability to propogate ^C through ^F and handle stderr ("*"). Not only that, but programs which need to be able to access the master side of a shell in a non-blocking fashion may access the master side directly through FIFO.LIBRARY calls. See FIFOLIB.DOC for the function call list, see REMCLI.C for a working example. 1> NewShell FIFO:name/rwkecs 1> run remcli name Generally the shell is run off the slave side and the controlling program is run off the master side. The side that runs the shell MUST specify the 's' option, as shown above. Here is a description of the flags used in the NewShell line: rw full duplex connection. shell 'reads' from the master and 'writes' results back to the msater. k if slave side is started up first, as in the above example, any writes it does will NOT be lost. Not really required since the slave side shell does not endcli itself. e when slave side closes the handle, an EOF will be sent to the master side. c run slave side in COOKED mode. FIFO: will do command line editing on any data sent to the slave side. You do not specify COOKED mode for the master side. I repeat, do NOT specify cooked mode for the master side. (you can't in the above example since the master is the 'remcli' program. note that in COOKED mode, FIFO: echo's characters received on the slave side back to the master, just like the console device. s SHELL support, required on the slave specification when run from NewShell, causes the handle to get its own message port. (required to support Open("*", ...); NOTE: YOU CAN RUN 'remcli name' MULTIPLE TIMES SIMULTANIOUSLY USING THE SAME FIFO NAME. All remcli's talking to the same shell will get all output from the shell and additionally be able to issue commands. This can be extremely useful as a monitoring tool. 1> run remcli name 1> run remcli name You can also capture all shell interaction with this: 1> copy FIFO:name/rmt t:capture The 't' (TEE) specification is required to ensure you do not screw up any other readers. There is no limit on the number of 'readers' monitoring a named fifo. The RemCLI program uses the fifo.library to access the master side and thus TEEs automatically. If RemCLI tries to talk to a fifo that does not exist, it will 'freeze' until the slave side does exist. Meaning you can run RemCLI before you start up the shell. CLOSING THE REMCLI WINDOW DOES NOT END THE SHELL. You must type 'endcli' or 'endshell' to cause it to exit. On the otherhand, closing the remcli window and then reopenning will yield the previous shell (which never exited). PIPEING You can use the FIFO: device to pipe output from one program to the input of another. Note that you want to be sure to use the 'k' flag in case the program generating the output generates only a little (and is able to exit before you have a chance to start the reader). You also want to use the 'e' (EOF) option or the reader will not receive an EOF, and you must make one side a master. 1> type s:startup-sequence >FIFO:xx/wkme 1> type FIFO:xx/r If you do not specify the 'e' EOF option then you can run multiple program's output through the pipe sequentially, specifying the eof option only for the last one. WARNING: If you ^C the reader before it gets the EOF and exits on its own, and if the writer is still writing, the writer will freeze up when the fifo becomes full (requiring a reader to unfreeze it). Additionally, if the 'k' option is not used, even if the writer does not freeze up there may be unwanted data left in the fifo even though nobody is referencing it. To safely recover from a broken reader, the program controlling the pipe must do the following steps: (1) break the writer if it has not exited (but it may be frozen, so...) (2) open a reader /r and a writer /wme, then immediately close the writer. (3) read from the reader until EOF. Even if the original writer had already exited, the fact that you open and close a dummy one will regenerate the EOF.