/ lang / pipe
PIPE
Syntax

    hStream = PIPE sPipeName FOR [ READ ] [ WRITE ] [ WATCH ]

Opens a named pipe for reading, writing or both. If the pipe does not exist it will be automatically created.

A pipe provides unidirectional flow of communication between processes within the same system. In other words, they are half-duplex, that is, data flows in only one direction.

One major feature of a pipe is that the data flowing through the communication medium is transient - data once read from the read descriptor cannot be read again. Also, if we write data continuously into the write descriptor, then we will be able to read the data only in the order in which the data was written.

However, a pipe has to be open at both ends simultaneously before you can proceed to do any input or output operations on it. Opening a pipe for reading normally blocks until some other process opens the same pipe for writing.

Gambas implements a FIFO(First-In, First-out) pipe. For further information look at MKFIFO in the Linux/ Unix manual pages.

- If the `READ` keyword is specified, then the pipe is opened for reading.

- If the `WRITE` keyword is specified, then the pipe is opened for writing.

- If the `WATCH` keyword is specified, the pipe is watched by the interpreter :
  - If at least one byte can be read from the file, then the event handler `Pipe_Read()` is called.
  - If at least one byte can be written into the file, then the event handler `Pipe_Write()` is called.

If the pipe is successfully opened, a stream object is returned to the variable hStream.

| Pipe streams are never buffered.

### Errors

Message | Description
--- | ---
Access forbidden (#43) | The requested access to the pipe is not allowed, or search permission is denied for one of the directories in the path prefix of pathname, or write access to the parent directory is not allowed.
Device is full (#37) | File name was to be created but the device containing Pipe name has no room for the new file.
Not a directory (#49) | A component used as a directory in Pipe name is not, in fact, a directory.
System error... (#42) | Other possible system errors: Too many symbolic links were encountered in resolving path. The length of the path argument exceeds maximum path or a pathname component is longer than maximum name. A component of the path prefix specified by path does not name an existing directory or path is an empty string. The directory that would contain the new file cannot be extended or the file system is out of file-allocation resources. The system limit on the total number of open files has been reached. Pipe name refers to a file on a read-only filesystem and write access was requested.

### Examples

    ' Prints the messages sent to a pipe

    DIM hFile AS File
    DIM sLine AS String

    hFile = PIPE "/tmp/FIFO1" FOR INPUT

    WHILE NOT Eof(hFile)
      LINE INPUT #hFile, sLine
      PRINT sLine
    WEND

    Start the above running in one window then do : ls > /tmp/FIFO1

### See also

Stream & Input/Output functions File & Directory Functions Stream