OPEN PIPE

Stream = [ OPEN ] PIPE PipeName 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. Once data is read using the "read" descriptor, it 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.

Sinds 3.5

As of Gambas 3.15 pipes DO NOT block when opening.
(See hint at base of page about backward compatibility and for a workaround for blocking on previous gambas versions)

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 pipe, then the event handler File_Read() is called.

    • If at least one byte can be written into the pipe, then the event handler File_Write() is called.

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

Pipe streams are never buffered.

Sinds 3.5

The OPEN PIPE syntax is available since Gambas 3.5.

If no process opens the pipe for writing, then any program using GTK+ and watching the pipe for reading will start to busy loop, eating 100% CPU.

This is a GTK+ feature.

The only workaround is opening the pipe both for reading and writing in the process that maintains it, so that there is always at least one writer.

Sinds 3.17

Since Gambas 3.17, pipes are always internally open for writing to workaround the problem. Beware that you still can write on the pipe only if you explicitly specify the WRITE flag.

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
' Start that running in one window then do : ls > /tmp/FIFO1

Dim hFile AS File
Dim sLine AS String

hFile = Pipe "/tmp/FIFO1" For Read

Do
  Read #hFile, sLine, -256
  If Not sLine Then Break
  Print sLine;
Loop

' Another way of reading a pipe if you know that the data is a bunch of text lines

Dim hFile As File
Dim sLine As String

hFile = Pipe "/tmp/FIFO1" For Read

Do
  Line Input #hFile, sLine
  If hFile.EndOfFile Then Break
  Print sLine
Loop

See also

Hint:
In versions of Gambas below V 3.15 opening the pipe even for Watch would use the Linux default behaviour of locking your program until the pipe received some text.
A simple fix for this was to 'echo' something to the pipe using the Shell command just before opening like this...

 Shell "echo '' >/tmp/fifo1"
 hFile = Pipe "/tmp/fifo1" For Watch

Then opening the pipe would instantly receive some text and your program would continue to run.

As from Gambas V3.15+ Opening a pipe no longer locks the program waiting for text to be received as this behaviour was not considered useful.

So using the echo command is no longer needed but for backward compatibility (If your app is intended for others) it is advisable to still use it as your program will work okay on Gambas V3.15 without it but will lock on a lesser version runtime.