Open Pipe
Opens an external process' standard input (stdin) or output (stdout) stream for file operations.
Open Pipe shell_command For Input As [#]filenumber
Open Pipe shell_command For Output As [#]filenumber
Open Pipe shell_command For Binary access_type [#]filenumber
result = Open Pipe( command[,] For {Input|Output}[,] As filenumber )
shell_command
In the first usage, Open Pipe returns zero (0) on success and a non-zero error code otherwise.
Open Pipe executes another process in the command shell and opens either its stdin or stdout streams for reading or writing. A file number is bound to the stream, which is used in subsequent file operations, such as Input #. An available filenumber can be retrieved with FreeFile. If the external process does not exist, a runtime error is thrown.
The Input and Output file modes open the external process' stdin and stdout streams, respectively, for sequential text I/O, useful for reading or writing plain text. Characters, words or whole lines can then be read or written using text-mode file operations, such as Line Input # and Print #.
The Binary file mode opens the external process' stdin or stdout streams - depending on the access type specified (see description of the access_type parameter above) - for random-access reading or writing of arbitrarily sized and interpreted raw data. Simple data type values, like Byte and LongInt, and whole chunks of memory can be read from or written to the streams with binary-mode file operations like Get # and Put #.
Bidirectional pipes are not supported by FB and must be implemented using the OS' API functions.
Runtime errors:
Open Pipe throws one of the following runtime errors:
(1) Illegal function call
Syntax
Open Pipe shell_command For Input As [#]filenumber
Open Pipe shell_command For Output As [#]filenumber
Open Pipe shell_command For Binary access_type [#]filenumber
Usage
result = Open Pipe( command[,] For {Input|Output}[,] As filenumber )
or,
result = Open Pipe( command[,] For Binary[,] access_type[,] As filenumber )(or in the QB-like syntax,)
Open Pipe filename For {Input|Output} As filenumber(or,)
Open Pipe filename For Binary access_type As filenumberParameters
shell_command
The external process to execute in the operating system command shell. Relative file paths are relative to the current directory (see CurDir). When opening a pipe for a process that requires double quotes in either its executable path, or its arguments, the entire pipe string should be nested inside of double quotes.
access_typeThe type of read or write access requested by the calling process.
- Access {Read|Write} (either the stdin or stdout stream of the external process can be opened)
An available file number to bind to the external process' stdin or stdout stream.
Return Value
In the first usage, Open Pipe returns zero (0) on success and a non-zero error code otherwise.
Description
Open Pipe executes another process in the command shell and opens either its stdin or stdout streams for reading or writing. A file number is bound to the stream, which is used in subsequent file operations, such as Input #. An available filenumber can be retrieved with FreeFile. If the external process does not exist, a runtime error is thrown.
The Input and Output file modes open the external process' stdin and stdout streams, respectively, for sequential text I/O, useful for reading or writing plain text. Characters, words or whole lines can then be read or written using text-mode file operations, such as Line Input # and Print #.
The Binary file mode opens the external process' stdin or stdout streams - depending on the access type specified (see description of the access_type parameter above) - for random-access reading or writing of arbitrarily sized and interpreted raw data. Simple data type values, like Byte and LongInt, and whole chunks of memory can be read from or written to the streams with binary-mode file operations like Get # and Put #.
Bidirectional pipes are not supported by FB and must be implemented using the OS' API functions.
Runtime errors:
Open Pipe throws one of the following runtime errors:
(1) Illegal function call
- filenumber was not free at the time. use FreeFile to ensure that filenumber is free.
Example
'' This example uses Open Pipe to run a shell command and retrieve its output.
#ifdef __FB_UNIX__
Const TEST_COMMAND = "ls *"
#else
Const TEST_COMMAND = "dir *.*"
#endif
Open Pipe TEST_COMMAND For Input As #1
Dim As String ln
Do Until EOF(1)
Line Input #1, ln
Print ln
Loop
Close #1
#ifdef __FB_UNIX__
Const TEST_COMMAND = "ls *"
#else
Const TEST_COMMAND = "dir *.*"
#endif
Open Pipe TEST_COMMAND For Input As #1
Dim As String ln
Do Until EOF(1)
Line Input #1, ln
Print ln
Loop
Close #1
Platform Differences
- The Binary file mode is not supported on all platforms; Open Pipe will throw an error if it is unable to open the external process' stdin or stdout streams in binary mode.
Differences from QB
- New to FreeBASIC
See also