Gambas Documentation
Application Repository
Code Snippets
Compilation & Installation
Components
Controls pictures
Deprecated components
Developer Documentation
Development Environment Documentation
Documents
Error Messages
Gambas Playground
How To's
Language Index
#Else
#Endif
#If
+INF
-INF
Abs
Access
ACos
ACosh
Alloc
AND
AND IF
Ang
APPEND
Arithmetic Operators
Array Declaration
AS
Asc
ASin
ASinh
Asl
Asr
ASSERT
Assignment Operators
Assignments
ATan
ATan2
ATanh
Base$
Base64$
BChg
BClr
BEGINS
Bin$
Binary Data Representation
Bool@
Boolean@
BREAK
BSet
BTst
BYREF
Byte@
CASE
CATCH
CBool
Cbr
CByte
CDate
Ceil
CFloat
CHGRP
CHMOD
Choose
CHOWN
Chr$
CInt
CInteger
CLASS
CLong
CLOSE
Comp
Comparison methods
Complex numbers
CONST
Constant Declaration
Constant Expression
CONTINUE
Conv$
Conversion Functions
COPY
Cos
Cosh
CPointer
CREATE
CREATE PRIVATE
CREATE STATIC
CShort
CSingle
CStr
CString
CVariant
Datatypes
Date
Date@
DateAdd
DateDiff
Day
DConv$
DEBUG
DEC
Dec
DEFAULT
Deg
DFree
DIM
Dir
DIV
DO
DOWNTO
EACH
ELSE
END
ENDIF
ENDS
END SELECT
END STRUCT
END WITH
ENUM
Enumeration declaration
Eof
ERROR
ERROR TO
Eval
Even
EVENT
Event Loop
Events declaration
EXEC
Exist
Exp
Exp2
Exp10
Expm
EXPORT
EXTERN
External Function Declaration
External Function Management
FALSE
FAST
FAST UNSAFE
File & Directory Paths
FINALLY
Fix
Float@
Floor
FLUSH
FOR
FOR EACH
Format$
Frac
Free
FromBase
FromBase64$
FromUrl$
FUNCTION
Global Special Event Handlers
GOSUB
GOTO
Hex$
Hour
Html$
Hyp
IF
IIf
IN
INC
INCLUDE or #INCLUDE
INHERITS
Inline Arrays
Inline Collections
INPUT
INPUT FROM
InStr
Int
Int@
Integer@
IS
IsAlnum
IsAscii
IsBlank
IsBoolean
IsDate
IsDigit
IsDir
IsFloat
IsHexa
IsInf
IsInteger
IsLCase
IsLetter
IsLong
IsLower
IsMissing
IsNaN
IsNull
IsNumber
IsPunct
IsSpace
IsUCase
IsUpper
KILL
Labels
Language Constants
LAST
LCase$
Left$
Len
LET
LIBRARY
LIKE
LINE INPUT
LINK
Localization and Translation Functions
Local Variable Declaration
LOCK
Lof
Log
Log2
Log10
Logical Operators
Logp
Long@
LOOP
Lsl
Lsr
LTrim$
Mag
MATCH
Max
ME
Method Declaration
Mid$
Min
Minute
MkBool$
MkBoolean$
MkByte$
MkDate$
MKDIR
MkFloat$
MkInt$
MkInteger$
MkLong$
MkPointer$
MkShort$
MkSingle$
MOD
Month
MOVE
NEW
NEXT
NOT
Now
NULL
Oct$
Odd
ON GOSUB
ON GOTO
OPEN
OPEN MEMORY
OPEN MEMORY
OPEN NULL
OPEN PIPE
OPEN PIPE
OPEN STRING
Operator Evaluation Order
OPTIONAL
OR
OR IF
OUTPUT
OUTPUT TO
PEEK
Pi
Pointer@
PRINT
PRIVATE
PROCEDURE
PROPERTY
Property Declaration
PUBLIC
QUIT
Quote$
Rad
RAISE
Rand
RANDOMIZE
RDir
READ
Realloc
REPEAT
Replace$
RETURN
Right$
RInStr
RMDIR
Rnd
Rol
Ror
Round
RTrim$
Scan
SConv$
Second
SEEK
Seek
SELECT
Sgn
SHELL
Shell$
Shl
Short@
Shr
Sin
Single@
Sinh
SizeOf
SLEEP
Space$
Special Methods
Split
Sqr
Stat
STATIC
STEP
STOP
STOP EVENT
Str$
Str@
String$
String@
String Operators
StrPtr
STRUCT
Structure declaration
SUB
Subst$
SUPER
SWAP
Swap$
Tan
Tanh
Temp$
THEN
Time
Timer
TO
Tr$
Trim$
TRUE
TRY
TypeOf
UCase$
UnBase64$
UNLOCK
UnQuote$
UNTIL
Url$
USE
User-defined formats
Using reserved keywords as identifiers
Val
Variable Declaration
VarPtr
WAIT
WATCH
Week
WeekDay
WEND
WHILE
WITH
WRITE
XOR
Year
Language Overviews
Last Changes
Lexicon
README
Search the wiki
To Do
Topics
Tutorials
Wiki License
Wiki Manual

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.

Since 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.

Since 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.

Since 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.