home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / util / shell / apipe-handler / readme < prev   
Encoding:
Text File  |  1994-12-18  |  6.8 KB  |  177 lines
  1. ################################################################################
  2. #
  3. #   APipe-Handler for AmigaDOS 2.04 or higher.
  4. #
  5. #   Copyright (C) 1991-1994 by Per Bojsen.  All Rights Reserved.
  6. #
  7. #   Permission is granted to any individual or institution to use, copy,
  8. #   modify, and distribute this software, provided that this complete
  9. #   copyright and permission notice is maintained, intact, in all copies
  10. #   and supporting documentation.
  11. #
  12. #   This software is provided on an "as is" basis without express or
  13. #   implied warranty.
  14. #
  15.  
  16. NOTE: See the CAVEAT section (3) for some important information on the
  17.       implementation of the APipe-Handler.
  18. NOTE: Update information is included at the end of this file.
  19.  
  20. This archive contains the source for the APipe-Handler.  The archive should
  21. include the following files:
  22.  
  23.         child.asm
  24.         pgmpipe.c
  25.         APipe-Handler
  26.         APipe-Handler_rev.h
  27.         APipe-Handler_rev.i
  28.         APipe-Handler_rev.rev
  29.         Makefile
  30.         Mountlist
  31.         README
  32.  
  33. APipe-Handler is a pre-made generic (no CPU specific optimizations)
  34. APipe-Handler for your convenience.
  35.  
  36.  
  37. 1) Introduction
  38.  
  39. Some weeks ago I got a strange idea for a new kind of pipe handler.  Let's
  40. call it `APipe-Handler' and its DOS device name `APIPE:'.  The special
  41. thing about this handler is that it interprets the name after the prefix
  42. `APIPE:' as a command line to be executed.  If the `APIPE:<command line>'
  43. file is opened as MODE_OLDFILE the standard output from the command will be
  44. available for reading; if the file is opened as MODE_NEWFILE the command will
  45. get its standard input from the data written to the file.
  46.  
  47. Here's some examples on the usage of this pipe handler:
  48.  
  49.     1> search APIPE:alias list ; print the aliases containing list
  50.  
  51.     2> sort "APIPE:list nohead" CONSOLE: ; sorted list
  52.  
  53.     3> comm -12 "APIPE:grep list APIPE:alias" "APIPE:grep nohead APIPE:alias"
  54.  
  55.     4> status >"APIPE:grep uucico" ; does not work with SAS grep: use GNU!
  56.  
  57.     5> grep uucico APIPE:status
  58.  
  59. The first two examples show things that could be done in a shell that
  60. supported anonymous pipes `|' *if* the standard AmigaDOS utilities had the
  61. ability to read from their standard input.
  62.  
  63. The third example shows something that is impossible to do with `|' command
  64. line pipes, and requires several lines (or shells) with PIPE: (comm is a
  65. program from the GNU text utilities that prints line in common between to
  66. sorted files).
  67.  
  68. Example four and five should produce equivalent results.
  69.  
  70. Other possible uses of APIPE: is as a file to save to from an editor,
  71. i.e., you could prepare some script or data file and save it directly to
  72. the command/program from your editor.  Or you could insert the output
  73. from a command into the file you're editing.  The editor you're using does
  74. not need any special support for this besides the ability to save and
  75. load files :-)
  76.  
  77. One nice thing about this handler is that it allows for a really simple
  78. implememtation of the UNIX popen()/pclose() functions: just append the
  79. command line to `APIPE:' and call fopen() on this string;  pclose() is
  80. simply a wrapper around fclose().  This was the main reason I came up with
  81. the idea, by the way.
  82.  
  83.  
  84. 2) How to build APipe-Handler
  85.  
  86. The build instructions assume you have SAS/C 6.51.
  87.  
  88. Edit the Makefile to reflect your installation.  You may choose to
  89. activate the machine architecture macros if you have a faster processor.
  90. Alternatively, specify the macros you want to activate on the command
  91. line when invoking make.
  92.  
  93. After you have customized the Makefile, run your make program to build
  94. the handler.
  95.  
  96.  
  97. 3) Installation
  98.  
  99. Install the APipe-Handler in the directory where you keep third-party
  100. handlers or in L: if you prefer to do so.  Following that, either
  101. edit the system wide Mountlist file in SYS:Devs to include the mountlist
  102. entry in the Mountlist file distributed with APipe-Handler, or place
  103. the Mountlist file somewhere where you like to keep third-party mountlist
  104. files/entries.  Add the command to mount APIPE: to your S:User-Startup.
  105.  
  106. Note that the `Handler' line in the mountlist entry specifies the file
  107. name of the handler relative to the current directory of any process
  108. invoking APIPE: unless the file name is specified with an absolute path,
  109. e.g., `L:APipe-Handler' rather than simply `APipe-Handler'.  Since
  110. APipe-Handler is loaded on demand, the system does not actually check
  111. whether the APipe-Handler is loadable at mount time.  Thus, it is possible
  112. to mount APIPE: even if the handler file cannot be loaded.
  113.  
  114. Unfortunately, earlier versions of APipe-Handler included a mountlist
  115. entry which did not specify an absolute path for APipe-Handler, and this
  116. turned out to cause a lot of confusion.  I apologize for this, and I
  117. have included a fixed mountlist entry as of version 37.6.
  118.  
  119.  
  120. 4) CAVEAT
  121.  
  122. The APipe-Handler needs to copy the environment of the requester process
  123. for the child process which runs the specified command line.  The enviroment
  124. includes the path, IO, current directory, shell variables, and aliases.
  125.  
  126. Unfortunately, there's currently no way to copy this environment safely
  127. which is safe under all circumstances.  The handler may fail if the process
  128. opening a file on the handler messes with its environment (like changing
  129. its path, changing shell variables, etc.) while the ACTION_FINDINPUT or
  130. ACTION_FINDOUTPUT packet is still pending.  Furthermore, the process
  131. must run with a higher or same priority than the handler process which
  132. normally runs at priority 5.
  133.  
  134. Since most programs seems to use the dos.library call Open() to open
  135. their files the caveat above is probably not a big problem in practice.
  136.  
  137. If you know of any program that might fall into the category covered by
  138. the caveat, please let me know.  I will try to convince Commodore to
  139. add some features to new versions of the OS that will make it possible
  140. to implement the APipe-Handler in a completely safe way.  This will be
  141. easier if many people use/need the APipe-Handler, so if you like the
  142. concept then give your friends a copy of it!
  143.  
  144. 5) Send bug reports (and praise/support) to one of
  145.  
  146.         bojsen@moria.home.id.dtu.dk
  147.         bojsen@id.dtu.dk
  148.         pb@delta.dk
  149.  
  150.    Snail mail:
  151.  
  152.         Per Bojsen
  153.         Maglegaards Alle 51 st. th.
  154.         DK-2860 Soeborg
  155.         Denmark
  156.  
  157.    Phone:
  158.  
  159.         +45 39 66 31 86
  160.  
  161. 6) Release notes.
  162.  
  163.    37.2  First publically released version.
  164.    37.3  Now uses the UserShell when starting programs.
  165.    37.4  Fixed bug in handling multiple outstanding read packets at
  166.          EOF.  The bug caused the handler to wait forever.
  167.    37.5  Improved cloning of filehandles so that >> redirection and
  168.          mixed reading/writing between parent and child process work
  169.          better.
  170.    37.6  Updated source and Makefile to SAS/C 6.
  171.    37.7  Bumped version number to avoid confusion with `unauthorized'
  172.          37.6 release.
  173.  
  174.                                     --**--
  175.  
  176. End of README.
  177.