{{fbdoc item="title" value="OPEN PIPE"}}----
Opens an external process' standard input (//stdin//) or output (//stdout//) stream, using it as if it were file operations.

{{fbdoc item="syntax"}}##
	**Open Pipe** //shell_command// **For** **[[KeyPgInputfilemode|Input]]** **As** [**#**]//filenumber//
	**Open Pipe** //shell_command// **For** **[[KeyPgOutput|Output]]** **As** [**#**]//filenumber//
	**Open Pipe** //shell_command// **For** **[[KeyPgBinary|Binary]]** //access_type// [**#**]//filenumber//
##
{{fbdoc item="usage"}}##
	//result// = **Open Pipe**( //command//[,] **For** {**[[KeyPgInputfilemode|Input]]**|**[[KeyPgOutput|Output]]**}[,] **As** //filenumber// )
		##//or,//##
	//result// = **Open Pipe**( //command//[,] **For** **[[KeyPgBinary|Binary]]**[,] //access_type//[,] **As** //filenumber// )
		##//(or in the QB-like syntax,)//##
	**Open Pipe** //filename// **For** {**[[KeyPgInputfilemode|Input]]**|**[[KeyPgOutput|Output]]**} **As** //filenumber//
		##//(or,)//##
	**Open Pipe** //filename// **For** **[[KeyPgBinary|Binary]]** //access_type// **As** //filenumber//
##
{{fbdoc item="param"}}
	##//shell_command//##
		The external process to execute in the operating system command shell. Relative file paths are relative to the current directory (see ##[[KeyPgCurdir|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_type//##
		The type of read or write access requested by the calling process.
			- ##[[KeyPgAccess|Access]]## {##Read##|##Write##} //(either the //stdin// or //stdout// stream of the external process can be opened)//
	##//filenumber//##
		An available file number to bind to the external process' //stdin// or //stdout// stream.

{{fbdoc item="ret"}}
	In the first usage, ##**Open Pipe()**## returns a 32 bit ##[[KeyPgLong|Long]]##: a zero (##0##) on success and a non-zero error code otherwise.

{{fbdoc item="desc"}}
	##**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 ##[[KeyPgInputPp|Input #]]##. An available ##//filenumber//## can be retrieved with ##[[KeyPgFreefile|Freefile]]##. If the external process does not exist, a runtime error is thrown.
	
	The ##[[KeyPgInputfilemode|Input]]## and ##[[KeyPgOutput|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 ##[[KeyPgLineinput|Line Input #]]## and ##[[KeyPgPrintPp|Print #]]##.
	
	The ##[[KeyPgBinary|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 ##[[KeyPgByte|Byte]]## and ##[[KeyPgLongint|Longint]]##, and whole chunks of memory can be read from or written to the streams with binary-mode file operations like ##[[KeyPgGetfileio|Get #]]## and ##[[KeyPgPutfileio|Put #]]##.
	Bidirectional pipes are not supported by FB and must be implemented using the OS' API functions.
	
	The error code returned by ##**Open Pipe**## can be checked using ##[[KeyPgErr|Err]]## in the next line. The function version of  ##**Open Pipe**## returns directly the error code as a 32 bit ##[[KeyPgLong|Long]]##.

**Runtime errors:**
	##**Open Pipe**## throws one of the following [[ProPgErrorHandling|runtime errors]]:
	
	//(##1##) Illegal function call//
		- ##//filenumber//## was not free at the time. use ##[[KeyPgFreefile|Freefile]]## to ensure that ##//filenumber//## is free.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/fileio/openpipe.bas"}}%%(freebasic)
'' 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
%%

{{fbdoc item="target"}}
	- The ##[[KeyPgBinary|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.

{{fbdoc item="diff"}}
	- New to ""FreeBASIC""

{{fbdoc item="see"}}
	- ##[[KeyPgShell|Shell]]##
	- ##[[KeyPgOpen|Open]]##
	- ##[[KeyPgOpenCons|Open Cons]]##
	- ##[[KeyPgOpenErr|Open Err]]##
	- ##[[KeyPgFreefile|Freefile]]##

{{fbdoc item="back" value="CatPgFile|File I/O Functions"}}