Pipes in MagiC from V3.00 onwards
---------------------------------

Andreas Kromke
24.1.98

Last change: English translation: Peter West, April 99
Tabulator width: 5


1. What are pipes ?
===================

Pipes are blocks of memory that are used for communication 
between processes (programs). For using the pipes the DOS
calls (Fcreate(),Fopen(),...) are used.
For each pipe a pseudo-file is created in U:\PIPE.


2. Unidirectional pipes
=======================

Unidirectional pipes are used for input/output redirection in UNIX
shells, e.g. also in Mupfel. With "ls | more" a pipe is created that 
redirects output from "ls" and the input from "more" into the pipe. 
The system kernel looks after the asynchronous data exchange 
("more", for instance, will wait until "ls" supplies data once more).
Unidirectional pipes can be created with Fcreate("U:\PIPE\....") or 
via Fpipe(). (=> MGX_DOS.TXT)
Unidirectional pipes have only one buffer (2048 bytes).


3. Bidirectional pipes
======================

Bidirectional pipes are used for the MultiTOS-conform Drag&Drop 
protocol. They can only be created with Fcreate("U:\PIPE\....").
(=> MGX_DOS.TXT)
Bidirectional pipes have two buffers each of 2048 bytes. Which of 
the two buffers is used depends on the caller. Due to the somewhat
diffuse documentation of MiNT a small incompatibility to MagiC has
crept in, unfortunately, though this does not appear in general 
practice, namely for Drag&Drop:

- In MagiC the process that created the pipe always reads from 
  buffer 1 and writes always to buffer 2.
  Every other process that opens the pipe reads from buffer 2 
  and writes to buffer 1.
- In MiNT the handle returned by Fcreate() always reads from
  buffer 1 and writes to buffer 2.
  For each (!) further opening, no matter whether from the same 
  or another process, one always reads from buffer 2 and writes 
  to buffer 1.


4. Variants
===========

Fpipe() creates a unidirectional pipe with attribute 1; other 
variants can be created with Fcreate(), for which the bits of
the attribute have the following meaning:

   Bit 0 = 0      Bidirectional pipe (e.g. for Drag&Drop)
         = 1      Unidirectional pipe (e.g. for I/O-redirection)
   Bit 1 = 0      Writing to a pipe that is not otherwise open 
                  for reading does not create a SIGPIPE signal,
                  but waits for any desired length of time.
                  Reading to a pipe that is not otherwise open 
                  for writing does not return an EOF, but waits
                  for any desired length of time.
         = 1      Writing to a pipe that is not otherwise open
                  for reading creates a SIGPIPE signal.
                  Reading to a pipe that is not otherwise open 
                  for writing creates EOF, i.e. the number of
                  bytes read (possibly 0) will be returned.
   Bit 2 = 0      A "normal" pipe will be created.
         = 1      A "pseudo TTY" will be created.
   Bit 5 = 0      Reading from a pipe will only be terminated 
                  by EOF (pipe not opened for writing) or by
                  reading all the bytes.
         = 1      Reading will be terminated without a pause  
                  when actually one byte has been read in.


5. Restrictions in MagiC
========================

Only up to 32 pipes are possible simultaneously.

SIGPIPE is not supported, i.e. never created.

Pseudo-TTYs are not supported.

In MagiC only bit 0 is evaluated with Fcreate(). The behaviour during 
reading and writing can not be influenced; instead, reading from a pipe 
not opened for writing as well as writing to a pipe not opened for 
reading will always return EOF.

During opening of a pipe it may happen that the handle > 31, in which 
case Fselect() is not possible.


6. Notes
========

The access to pipes is always purely asynchronous; applications wait 
for reading/writing and reawaken another application if appropriate 
while reading/writing.

Fseek to pipes leads basically to the return of 0L (i.e. the file 
pointer can not be influenced).

Pipes are cleared automatically after closing. Pipes appear in the 
directory with the size of 2 kB (unidirectional) or 4 kB (bidirectional)
and with the correct creation date-stamp.

