Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/215.lha/Pipe_v2.02/pipe.doc

Text File | 1996-02-15 | 5.3 KB | 146 lines

PIPE.DOC    Version 2.00        Matthew Dillon

    Matthew Dillon
    891 Regal Rd.
    Berkeley, Ca. 94708

    ..ihnp4|ucbvax|dillon
    [e-mail]


    I have completely re-written my PIPE: handler from scratch.  The PIPE:
device now supports bi-directional connections through a single file-handle,
dynamic buffer sizing, signaling capability, and several other options for
supporting virtual terminals (i.e. slaving a CLI).

    It is upward compatible with the old version in that you still
redirect from PIPE:name and to PIPE:name (with the same name) to make
a pipe.

    The PIPE: normally has a 4K buffer associated with it, but you should
not count on an application not blocking when writing to it unless you give
the PIPE: the /n option (example:  pipe:a/n).  this option allows the
buffer to grow to any size.

 *  --------------------------- Warning, technical discussion follows ------
 *
 *  A given PIPE path has a notion of MASTER and SLAVE.  The MASTER portion
 *  refers to the named PIPE when openned with modes 1006 (NEWFILE).  The
 *  SLAVE portion refers to the named PIPE when openned with modes 1005
 *  (OLDFILE).    Most applications of the PIPE use only a single direction.
 *
 *  However, some applications require data transmission over both
 *  directions.  For instance, you can specify:
 *
 *  NEWCLI pipe:a    (see example below for more practical use with a CLI)
 *
 *  The CLI is the SLAVE.  You can then write a driving program by openning
 *  the pipe mode 1006.  You must read and write using that mode (i.e. if
 *  you openned with 1005 and did a read, you would simply be reading the
 *  data you sent with the 1006 filehandle rather than what the CLI is
 *  giving back to us).
 *
 *  The pipe supports several options using the following naming format:
 *
 *  PIPE:name[/options]
 *
 *  options:    t    Read()'s block if no data is available, but return
 *            as soon as data is available (not necc. on newline
 *            boundries).  Thus, a minimum of one byte is returned
 *            until you get to the End Of the File, in which case
 *            0 is returned.    I.E. make it look sortof like a
 *            terminal.
 *
 *        n    simple way of saying "no maximum" for the dynamic
 *            buffering on writes.  Basically, any writes you
 *            do to this filehandle always return immediately
 *            unless you run out of memory.
 *
 *        b#    Set the maxmimum dynamic buffer size (default 4096)
 *            Can be set arbitrarily high.  Writes will not
 *            block unless the dynamic buffer size excedes this
 *            value or you run out of memory.
 *
 *            Only buffer room for the actual amount of queued data
 *            is allocated.
 *
 *        s#    When read data is available on file handle, signal
 *            my task with signal number # (0..31).
 *
 *            THIS ALSO EFFECTS READS: If no data is currently
 *            available, a Read() will return 0.  Read()s can
 *            now return less than the requested number of bytes
 *            as in the 't' option.
 *
 *            -1 is returned on EOF instead of 0.
 *
 *        q    Query if the other end of this PIPE: is active.
 *            .e.g. if you open with modes 1005(SLAVE), the
 *            open will succede if there is something connected
 *            to the MASTER part, and visa versa.  Otherwise,
 *            the open fails.
 *
 *  EXAMPLES:    pipe:a        -normal pipe
 *        pipe:a/b16384    -use a slightly larger write buffer.
 *        pipe:a/s31    -have the PIPE handler signal your
 *                 task when read data becomes available
 *                 on this filehandle.
 *
 *  EXAMPLE:    Slaving a NEWCLI:
 *
 *    Execute("newcli pipe:name/t",0L,0L);
 *    fh = Open("pipe:name/tns31", 1006);
 *
 *    -signal will come in whenever read data becomes available on fh.
 *    -you should Read() all available data.    Check for a -1 return
 *     value indicating that the slave closed his connection.
 *
 *    -write to the same filehandle to send data to the slave.  The
 *     slave gets the data immediately due to the '/t' option even
 *     if it may be less than his pending Read().
 *
 *     We pass the 'n' option to ensure our writes do not block
 *     (be careful!) to prevent a lockout situation.
 *
 *    NOTE NOTE NOTE NOTE NOTE.  A CLI does not recognize EOF's
 *    (i.e. you closing your filehandle).  (A) You can re-open the
 *    same file handle at some later time and continue talking to the
 *    CLI.  (B) You MUST send an 'ENDCLI' to actually cause the CLI
 *    to quit.  With this example, you can recognize when the CLI has
 *    closed it's connection when your Read() returns -1.
 *
 *  Additions for 2.02 from 2.01:
 *    high and low water marks implemented for better efficiency
 *
 *



    EXAMPLE:    Slaving a NEWCLI:

    Execute("newcli pipe:name/t",0L,0L);
    fh = Open("pipe:name/tns31", 1006);

    -signal will come in whenever read data becomes available on fh.
    -you should Read() all available data.    Check for a -1 return
     value indicating that the slave closed his connection.

    -write to the same filehandle to send data to the slave.  The
     slave gets the data immediately due to the '/t' option even
     if it may be less than his pending Read().

     We pass the 'n' option to ensure our writes do not block
     (be careful!) to prevent a lockout situation.

    NOTE NOTE NOTE NOTE NOTE.  A CLI does not recognize EOF's
    (i.e. you closing your filehandle).  (A) You can re-open the
    same file handle at some later time and continue talking to the
    CLI.  (B) You MUST send an 'ENDCLI' to actually cause the CLI
    to quit.  With this example, you can recognize when the CLI has
    closed it's connection when your Read() returns -1.