Operations on C Streams (GNAT Reference Manual)

### 12.14 Operations on C Streams ¶

The package `Interfaces.C_Streams` provides an Ada program with direct access to the C library functions for operations on C streams:

    package Interfaces.C_Streams is
      -- Note: the reason we do not use the types that are in
      -- Interfaces.C is that we want to avoid dragging in the
      -- code in this unit if possible.
      subtype chars is System.Address;
      -- Pointer to null-terminated array of characters
      subtype FILEs is System.Address;
      -- Corresponds to the C type FILE*
      subtype voids is System.Address;
      -- Corresponds to the C type void*
      subtype int is Integer;
      subtype long is Long_Integer;
      -- Note: the above types are subtypes deliberately, and it
      -- is part of this spec that the above correspondences are
      -- guaranteed.  This means that it is legitimate to, for
      -- example, use Integer instead of int.  We provide these
      -- synonyms for clarity, but in some cases it may be
      -- convenient to use the underlying types (for example to
      -- avoid an unnecessary dependency of a spec on the spec
      -- of this unit).
      type size_t is mod 2 ** Standard'Address_Size;
      NULL_Stream : constant FILEs;
      -- Value returned (NULL in C) to indicate an
      -- fdopen/fopen/tmpfile error
      ----------------------------------
      -- Constants Defined in stdio.h --
      ----------------------------------
      EOF : constant int;
      -- Used by a number of routines to indicate error or
      -- end of file
      IOFBF : constant int;
      IOLBF : constant int;
      IONBF : constant int;
      -- Used to indicate buffering mode for setvbuf call
      SEEK_CUR : constant int;
      SEEK_END : constant int;
      SEEK_SET : constant int;
      -- Used to indicate origin for fseek call
      function stdin return FILEs;
      function stdout return FILEs;
      function stderr return FILEs;
      -- Streams associated with standard files
      --------------------------
      -- Standard C functions --
      --------------------------
      -- The functions selected below are ones that are
      -- available in UNIX (but not necessarily in ANSI C).
      -- These are very thin interfaces
      -- which copy exactly the C headers.  For more
      -- documentation on these functions, see the Microsoft C
      -- "Run-Time Library Reference" (Microsoft Press, 1990,
      -- ISBN 1-55615-225-6), which includes useful information
      -- on system compatibility.
      procedure clearerr (stream : FILEs);
      function fclose (stream : FILEs) return int;
      function fdopen (handle : int; mode : chars) return FILEs;
      function feof (stream : FILEs) return int;
      function ferror (stream : FILEs) return int;
      function fflush (stream : FILEs) return int;
      function fgetc (stream : FILEs) return int;
      function fgets (strng : chars; n : int; stream : FILEs)
          return chars;
      function fileno (stream : FILEs) return int;
      function fopen (filename : chars; Mode : chars)
          return FILEs;
      -- Note: to maintain target independence, use
      -- text_translation_required, a boolean variable defined in
      -- a-sysdep.c to deal with the target dependent text
      -- translation requirement.  If this variable is set,
      -- then  b/t should be appended to the standard mode
      -- argument to set the text translation mode off or on
      -- as required.
      function fputc (C : int; stream : FILEs) return int;
      function fputs (Strng : chars; Stream : FILEs) return int;
      function fread
         (buffer : voids;
          size : size_t;
          count : size_t;
          stream : FILEs)
          return size_t;
      function freopen
         (filename : chars;
          mode : chars;
          stream : FILEs)
          return FILEs;
      function fseek
         (stream : FILEs;
          offset : long;
          origin : int)
          return int;
      function ftell (stream : FILEs) return long;
      function fwrite
         (buffer : voids;
          size : size_t;
          count : size_t;
          stream : FILEs)
          return size_t;
      function isatty (handle : int) return int;
      procedure mktemp (template : chars);
      -- The return value (which is just a pointer to template)
      -- is discarded
      procedure rewind (stream : FILEs);
      function rmtmp return int;
      function setvbuf
         (stream : FILEs;
          buffer : chars;
          mode : int;
          size : size_t)
          return int;

      function tmpfile return FILEs;
      function ungetc (c : int; stream : FILEs) return int;
      function unlink (filename : chars) return int;
      ---------------------
      -- Extra functions --
      ---------------------
      -- These functions supply slightly thicker bindings than
      -- those above.  They are derived from functions in the
      -- C Run-Time Library, but may do a bit more work than
      -- just directly calling one of the Library functions.
      function is_regular_file (handle : int) return int;
      -- Tests if given handle is for a regular file (result 1)
      -- or for a non-regular file (pipe or device, result 0).
      ---------------------------------
      -- Control of Text/Binary Mode --
      ---------------------------------
      -- If text_translation_required is true, then the following
      -- functions may be used to dynamically switch a file from
      -- binary to text mode or vice versa.  These functions have
      -- no effect if text_translation_required is false (i.e., in
      -- normal UNIX mode).  Use fileno to get a stream handle.
      procedure set_binary_mode (handle : int);
      procedure set_text_mode (handle : int);
      ----------------------------
      -- Full Path Name support --
      ----------------------------
      procedure full_name (nam : chars; buffer : chars);
      -- Given a NUL terminated string representing a file
      -- name, returns in buffer a NUL terminated string
      -- representing the full path name for the file name.
      -- On systems where it is relevant the   drive is also
      -- part of the full path name.  It is the responsibility
      -- of the caller to pass an actual parameter for buffer
      -- that is big enough for any full path name.  Use
      -- max_path_len given below as the size of buffer.
      max_path_len : integer;
      -- Maximum length of an allowable full path name on the
      -- system, including a terminating NUL character.
    end Interfaces.C_Streams;