Package: Interfaces.C

Package: Interfaces.C_Streams

Dependencies

with Unchecked_Conversion;
with System.Parameters;

Description

This package is a thin binding to selected functions in the C library that provide a complete interface for handling C streams.

Header

package Interfaces.C_Streams is

pragma Elaborate_Body (C_Streams);

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.

Type Summary

`long`
`size_t`

Constants and Named Numbers

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

L_tmpnam : constant int;

Maximum length of file name that can be returned by tmpnam

NULL_Stream : constant FILEs;

Value returned (NULL in C) to indicate an fdopen/fopen/tmpfile error

SEEK_CUR : constant int;

SEEK_END : constant int;

SEEK_SET : constant int;

Used to indicate origin for fseek call

Variables

max_path_len : Integer;

Maximum length of an allowable full path name on the system, including a terminating NUL character.

Other Items:

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;

Note: the above type is a subtype deliberately, and it is part of this spec that the above correspondence is guaranteed. This means that it is legitimate to, for example, use Integer instead of int. We provide this synonym 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 long is range -(2 ** (System.Parameters.long_bits - 1))
   .. +(2 ** (System.Parameters.long_bits - 1)) - 1;

Note: the above type also used to be a subtype, but the correspondence was unused so it was made into a parameterized type to avoid having multiple versions of this spec for systems where long /= Long_Integer.

type size_t is mod 2 ** Standard'Address_Size;

function stdin  return FILEs;

function stdout return FILEs;

function stderr return FILEs;

Streams associated with standard files

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 fread
  (buffer : voids;
   index  : size_t;
   size   : size_t;
   count  : size_t;
   stream : FILEs)
   return   size_t;

Same as normal fread, but has a parameter 'index' that indicates the starting index for the read within 'buffer' (which must be the address of the beginning of a whole array object with an assumed zero base). This is needed for systems that do not support taking the address of an element within an array.

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 setvbuf
  (stream : FILEs;
   buffer : chars;
   mode   : int;
   size   : size_t)
   return   int;

procedure tmpnam (string : chars);

The parameter must be a pointer to a string buffer of at least L_tmpnam bytes (the call with a null parameter is not supported). The returned value, which is just a copy of the input argument, is discarded.

function tmpfile return FILEs;

function ungetc (c : int; stream : FILEs) return int;

function unlink (filename : chars) return int;

Extra functions

function file_exists (name : chars) return int;

Tests if given name corresponds to an existing file.

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).

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.

private

   --  Implementation-defined ...

end Interfaces.C_Streams;