.. include:: ../../global.rst

.. _`pipe handles`:

Pipe Handles
------------

Pipe handles are the entities through which we perform command
orchestration pipelines.  They are one underlying implementation of
:ref:`handles <handle type>`.

Pipe handles only really differ from file handles in that you cannot
*seek* on a pipe handle.

You can open pipe handles directly and there are command orchestration
meta-commands like ``pipe-into`` and ``pipe-from`` which will return
pipe handles.


Pipe Handle Predicates
^^^^^^^^^^^^^^^^^^^^^^


.. _`pipe-handle?`:

.. idio:function:: pipe-handle? o


   test if `o` is a pipe handle			
   						
   :param o: object to test			
   :return: ``#t`` if `o` is a pipe handle, ``#f`` otherwise	


.. _`input-pipe-handle?`:

.. idio:function:: input-pipe-handle? o


   test if `o` is an input pipe handle		
   						
   :param o: object to test			
   :return: ``#t`` if `o` is an input pipe handle, ``#f`` otherwise	


.. _`output-pipe-handle?`:

.. idio:function:: output-pipe-handle? o


   test if `o` is an output pipe handle		
   						
   :param o: object to test			
   :return: ``#t`` if `o` is an output pipe handle, ``#f`` otherwise	


Pipe Handle Constructors
^^^^^^^^^^^^^^^^^^^^^^^^


.. _`open-input-pipe`:

.. idio:function:: open-input-pipe fd [name [mode]]


   construct an input pipe handle from `fd` using the name	
   `name` and mode `mode`			 		
   							
   :param fd: file descriptor				
   :type fd: C/int						
   :param name: file name for display, defaults to :file:`/dev/fd/{fd}`	
   :type name: string, optional				
   :param mode: file mode for opening, defaults to ``"r"``	
   :type mode: string, optional				
   :return: pipe file handle				
   :rtype: handle						
   							
   Use ``#n`` for `name` if you only want to set `mode`	
   							
   See :ref:`open-file <open-file>` for `mode` values.	


.. _`open-output-pipe`:

.. idio:function:: open-output-pipe fd [name [mode]]


   construct an output pipe handle from `fd` using the name	
   `name` and mode `mode`			 		
   							
   :param fd: file descriptor				
   :type fd: C/int						
   :param name: file name for display, defaults to :file:`/dev/fd/{fd}`	
   :type name: string, optional				
   :param mode: file mode for opening, defaults to ``"w"``	
   :type mode: string, optional				
   :return: pipe file handle				
   :rtype: handle						
   							
   Use ``#n`` for `name` if you only want to set `mode`	
   							
   See :ref:`open-file <open-file>` for `mode` values.	


Pipe Handle Attributes
^^^^^^^^^^^^^^^^^^^^^^


.. _`pipe-handle-fd`:

.. idio:function:: pipe-handle-fd ph


   return the file descriptor associated with	
   pipe handle `ph`				
   						
   :param ph: pipe handle to query			
   :type ph: pipe handle				
   :return: file descriptor			
   :rtype: C/int					




.. include:: ../../commit.rst