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

.. _`file handles`:

File Handles
============

File handles are the entities through which we perform input and
output to the file system.  They are one underlying implementation of
:ref:`handles <handle type>`.

Ordinarily you would create input or output file handles with
:samp:`open-input-file {filename}` and :samp:`open-output-file
{filename}` respectively but you can also :samp:`open-file {filename}
{mode}` for some choice of :samp:`{mode}`.


File Handle Predicates
^^^^^^^^^^^^^^^^^^^^^^


.. _`file-handle?`:

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


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


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

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


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


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

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


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


File Handle Constructors
^^^^^^^^^^^^^^^^^^^^^^^^


.. _`open-input-file`:

.. idio:function:: open-input-file name


   open input file `name`					
   							
   :param name: file name					
   :type name: string					
   :return: file handle					
   :rtype: handle						


.. _`open-output-file`:

.. idio:function:: open-output-file name


   open output file `name`					
   							
   :param name: file name					
   :type name: string					
   :return: file handle					
   :rtype: handle						


.. _`open-file`:

.. idio:function:: open-file name mode


   open input file `name` using mode `mode`		
   							
   :param name: file name					
   :type name: string					
   :param mode: open mode					
   :type mode: string					
   :return: file handle					
   :rtype: handle						

   `mode` can be one of the usual :manpage:`fopen(3)` mode characters but
   must start with `r`, `w` or `a`:
   
   .. csv-table::
      :header: flag, :manpage:`open(2)`
      :widths: auto
      :align: left
   
      ``r``, ``O_RDONLY``
      ``w``, ``O_WRONLY`` | ``O_CREAT`` | ``O_TRUNC``
      ``a``, ``O_WRONLY`` | ``O_CREAT`` | ``O_APPEND``
   
      ``+``, ``O_RDWR`` in place of ``O_RDONLY`` or ``O_WRONLY``
      ``b``, ignored
      ``e``, ``O_CLOEXEC``
      ``x``, ``O_EXCL``
   
      
   

.. _`open-file-from-fd`:

.. idio:function:: open-file-from-fd fd [name [mode]]


   construct an input file 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: 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-input-file-from-fd`:

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


   construct an input file 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: 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-file-from-fd`:

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


   construct an output file 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: file handle					
   :rtype: handle						
   							
   Use ``#n`` for `name` if you only want to set `mode`	
   							
   See :ref:`open-file <open-file>` for `mode` values.	


File Handle Attributes
^^^^^^^^^^^^^^^^^^^^^^


.. _`file-handle-fd`:

.. idio:function:: file-handle-fd fh


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




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