{{fbdoc item="title" value="OPEN PIPE"}}----
Opens an external process' standard input (//stdin//) or output (//stdout//) stream for 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 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.

**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"}}