workbench/fs/pipe/README

   1 README file for pipe-handler (version 1.2 13-Jun-87)
   2 ====================================================
   3
   4 This program and source are freely distributable, provided the file headers
   5 remain intact (i.e., my name is on them!!!).
   6
   7 Ed Puckett accepts no responsibility for others' use of this program.
   8
   9 ...but you shouldn't have any problems!
  10
  11
  12 WHAT IS THIS?
  13 -------------
  14 Pipe-handler is an AmigaDOS device.  It supports OPEN, CLOSE, READ and
  15 WRITE (of course), and also LOCK, EXAMINE, EXNEXT.  Therefore, you can
  16 CD to the handler, use Dir and List on it, and ASSIGN to it as well as
  17 to individual pipes in it.  Here is a complete list of the packet
  18 types it supports:
  19
  20         MODE_READWRITE
  21         ACTION_FINDINPUT  (syn: MODE_READONLY, MODE_OLDFILE)
  22         ACTION_FINDOUTPUT (syn: MODE_NEWFILE)
  23         ACTION_END
  24         ACTION_READ
  25         ACTION_WRITE
  26         ACTION_LOCATE_OBJECT
  27         ACTION_COPY_DIR
  28         ACTION_FREE_LOCK
  29         ACTION_EXAMINE_OBJECT
  30         ACTION_EXAMINE_NEXT
  31         ACTION_PARENT
  32
  33 You cannot Seek() pipes nor can you create pipe subdirectories.
  34
  35
  36 INSTALLATION
  37 ------------
  38 1. Perform the following:
  39         <uudecode phl.uue to produce pipe-handler-l>
  40         <uudecode ph.uue  to produce pipe-handler>
  41         Copy pipe-handler-l L:pipe-handler-loader
  42         Copy pipe-handler   L:pipe-handler
  43
  44 2. Add to S:Startup-Sequence (do not include !'s - they denote start of line):
  45         !Mount P:
  46         !Dir >NIL: P:
  47
  48 3. Add to DEVS:Mountlist (do not include !'s - they denote start of line):
  49         !P:      Handler = L:pipe-handler-loader
  50         !        Stacksize = 3000
  51         !        Priority = 5
  52         !#
  53
  54 4. Reboot
  55
  56
  57 NOTES ON INSTALLATION
  58 ---------------------
  59 * The handler, once installed, requires approximately 18k of memory.  This
  60   memory cannot be reclaimed (unless you reboot and do not load the handler).
  61   Each pipe requires additional memory while it exists (its buffer size +
  62   about 100 bytes or so).
  63
  64 * You can skip the reboot, and just perform the "Mount" and "Dir" from the
  65   startup-sequence manually.
  66
  67 * After the "Dir", the pipe-handler is loaded into the system, and the files
  68   "L:pipe-handler-loader" and "L:pipe-handler" will not be accessed until the
  69   next reboot.  This means you may remove them from L: if you want (until
  70   next  reboot).  I do this because I copy L: into Ram:.
  71
  72 * TO CHANGE THE HANDLER NAME: change "P:" to whatever you want (e.g., "PIPE:")
  73   in the following 2 files:
  74         DEVS:Mountlist          (1 occurrence)
  75         S:Startup-Sequence      (2 occurrences)
  76
  77 * Feel free to shorten or otherwise change the names "pipe-handler-loader"
  78   and "pipe-handler".  Just be sure to reflect those changes in
  79   "S:Startup-Sequence" and "DEVS:Mountlist".
  80
  81
  82 TAPS
  83 ----
  84 The handler also supports "taps".  These are essentially tees off of the
  85 pipe, and can specify any destination to which a copy of the pipe's stream
  86 is to be sent.  One interesting application of this is tapping to a
  87 CON: window; you can then see what is going through the pipe, and you
  88 can also stop pipe throughput by typing a character into this window.
  89 Taps can also be other pipes.
  90
  91 For an interesting demo of taps, EXECUTE the file "tap_demo".
  92
  93 All pipe I/O is asynchronous, so you will not be able to lock up the
  94 handler by stopping one of its pipes.  A single reader / single writer
  95 discipline in enforced.
  96
  97 Pipe buffers are dynamically allocated.  A pipe is removed from memory
  98 when all openers have closed it and it is empty.  The size of a pipe buffer
  99 may be specified as part of its name.  Otherwise, pipe buffers have a default
 100 size of 4096 bytes.
 101
 102 Pipes behave in most respects like ordinary files.  Some differences follow:
 103 Pipes block for writing (i.e., the write request is suspended) when the
 104 pipe's buffer is full, and block for reading when the pipe's buffer is
 105 empty.  Thus, pipes are sort of like bounded ram: files.  EOF is returned
 106 for reading when the pipe's buffer is empty and no process has the pipe
 107 open for writing.
 108
 109
 110 NAME SYNTAX
 111 -----------
 112 In addition to the pipe's identifier, its name can specify its size
 113 and a tap.  The syntax is
 114
 115         name[/size][/[tapname]]
 116
 117 where the parts enclosed in "[]" are optional.  The size must begin with
 118 a digit in the range 0-9.  If first digit is not "0", the size is
 119 interpreted as decimal.  If the size begins with "0x", it is interpreted
 120 as hexadecimal.  Otherwise, if the size begins with "0" but not "0x", it
 121 is interpreted as octal.
 122
 123 If an empty tapname is specified, the default tap CON:10/15/300/70/name
 124 is used (where "name" is the pipe's name given).
 125
 126 You can use a pipe name of '*' to specify an autonamed pipe. The
 127 dos.library/NameFromFH() call can be used to get the name of the
 128 opposite end, which can then be passed to Open()
 129
 130
 131 EXAMPLES OF PIPE NAMES
 132 ----------------------
 133
 134 The following assume that the pipe-handler is mounted as device P:
 135
 136 P:x                             Opens a pipe named "x" with buffer size 4096
 137
 138 P:x/100                         Opens a pipe named "x" with buffer size 100
 139
 140 P:hold/                         Opens a pipe named "hold" with buffer size
 141                                 4096, and also opens a window which displays
 142                                 the data which passes through the pipe.
 143
 144 P:xyzzy/plugh                   Opens a pipe named "xyzzy" with buffer size
 145                                 4096, and also directs the data passing
 146                                 through into the file "plugh".  (Note that
 147                                 taps may be specified without specifying
 148                                 a size.)
 149
 150 P:thru/0x40/ram:thru-log        Opens a pipe named "thru" with buffer size
 151                                 64 (decimal), and also directs the data
 152                                 passing through the pipe into the file
 153                                 "ram:thru-log".
 154
 155
 156 WHAT IS THIS SILLY "LOADER" FILE?
 157 ---------------------------------
 158 According to _The_AmigaDOS_Manual_ (Bantam Books, Feb 1986), page 291:
 159
 160         If you write your device handler in C, you cannot use the automatic
 161         load and process creation provided by the kernel.  In this case you
 162         must load the code yourself . . . .
 163
 164 Well, I know others have gotten around this, and I did, too.  The "prelude"
 165 version of the handler (see the Makefile) does it all with one file.
 166 However, I noticed that doing it this way, the handler would take about
 167 3 seconds to "Mount" (after first access to it).  This made me very nervous -
 168 visions of wild linking through memory, etc.  The loader version mounts
 169 almost immediately.
 170
 171 Anyway, due to my (possibly unfounded) paranoia, I instead use the BCPL-like
 172 assembly module "pipe-handler-loader" which LoadSeg()'s pipe-handler.  There
 173 are undoubtedly better ways of handling this, but this works and, for me,
 174 it is not too annoying to put up with the extra file.
 175
 176
 177 COMPILATION
 178 -----------
 179 The supplied C source files were compiled with Lattice v3.03.
 180 The assembly programs were assembled using the Commodore Assembler.
 181
 182 See the Makefile for information on creating a debugging version
 183 (this puts up a window and tells you what packets are received by
 184 the handler - fun!).  Basically, you just compile with a -DDEBUG
 185 option and link in the debugging modules.
 186
 187 The Makefile will make either a "prelude" version (no "loader file)
 188 or a "loader" version (the default).
 189
 190 I use an EXECUTE file "cc" to driver the compiler.  It is supplied.
 191
 192
 193 INQUIRIES / COMMENTS / SUGGESTIONS
 194 ----------------------------------
 195 Ed Puckett
 196
 197 US Mail:  MIT Branch PO - PO Box 61
 198           Cambridge, MA  02139
 199
 200 E Mail:  ...!ihnp4!mit-eddie!mit-oz!qix