The Datafile PD-CD 2/DATAFILE_PDCD2.iso/utilities2/desklib/!DeskLib/h/File

Text File | 1993-07-12 | 8.3 KB | 241 lines

/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    File.h
    Author:  Copyright © 1993 Jason Williams
    Version: 1.00 (12 Jul 1993)
    Purpose: Low level file operations, much faster than stdio equivalents,
             and more convenient when interacting with other code that uses
             RISC OS file handles to refer to files.
*/


#ifndef __dl_file_h
#define __dl_file_h

#ifndef __dl_core_h
#include "Core.h"
#endif


extern os_error *file_lasterror;

/*  IMPORTANT NOTE
 *  file_lasterror is used to provide a more convenient SWI veneer for certain
 *  file operations (Open, reading, etc, return handles/values directly,
 *  rather than you having to provide the address of a variable for the
 *  returned value, leaving no convenient way of returning errors!)
 *
 *  Thus, file_lasterror is set by the file operations:
 *    Open, Close, EOF, Read8/32/Bytes, Write8/32/Bytes, Seek, ReturnPos
 *
 *  However, note that it is just a pointer to the error returned by the SWI
 *  call, so it MUST be used immediately after the call, or else it may be
 *  invalid or possibly even dangerously corrupted
 *  If for example, you wish to close the file before reporting the error,
 *  you must first copy the error into your own os_error block.
 *
 *  If no error occurred on the last file op, file_lasterror will be NULL.
 *  Most of the above functions also return values (filehandle = NULL etc)
 *  that will indicate when an error may have occurred, at which time you
 *  can interrogate file_lasterror to work out what the error was.
 *
 *  Note also that all of the above calls which do not have a specific
 *  return value (Close, Write*, Seek) return the os_error pointer directly
 *  as well as setting file_lasterror, for convenience.
 */


 /*  File_Delete
  *  Attempts to delete the named file. Use carefully!
  */
extern os_error *File_Delete(char *filename);


 /*  File_Size
  *  Reads the size (in bytes) of the file. A return value of 0 indicates
  *  either the file is 0 bytes long, or an error occurred (which usually
  *  means that the file doesn't exist)
  */
extern int File_Size(char *filename);


/*  File_Exists
 *  This returns TRUE if the file exists.
 *  (It attempts to open the file for reading - it returns TRUE if successful)
 */
extern BOOL File_Exists(char *filename);



typedef int file_position;
typedef int file_handle;

#define file_READERROR (-1)


 /*  file_access values
  *  These are used when opening files. NOTE that they correspond directly
  *  to OS_File opening flags (OS_File register 0 entry value)
  */

typedef enum
{
  file_READ   = 0x40,          /* Open the file for reading                 */
  file_WRITE  = 0x80,          /* CREATE/WIPE the file, open it for writing */
  file_APPEND = 0xC0           /* Open for appending to existing file. NOTE
                                * that I don't have the PRMs so I can't tell
                                * you where this puts the initial file pointer
                                */
} file_access;


 /*  File_Open
  *  Opens the given file for reading or writing (see file_access's above)
  *  Returns the file handle, or NULL if it failed
  *  (if NULL, you can check file_lasterror for the reason)
  *
  *  NOTE that the OS will return a NULL file handle if we try to open a
  *  non existent file, but does NOT flag this as an error (i.e. File_Open
  *  returns NULL, but file_lasterror is ALSO NULL). You must therefore
  *  check file_lasterror before blindly trying to use it to report an error.
  */
extern file_handle File_Open(char *filename, file_access access);


 /*  File_Close
  *  Closes an open file stream, using the handle returned by File_Open
  *  After a close, the file_handle is no longer valid, so do not try
  *  to use it.
  */
extern os_error *File_Close(file_handle handle);


 /*  File_EOF
  *  Returns TRUE if the end of the file has been reached
  */
extern BOOL File_EOF(file_handle handle);


 /*  File_Seek
  *  Seeks the file pointer to the given position (an offset in terms of
  *  bytes offset from the start of the file). Subsequent read/write
  *  operations will read from or write to that part of the file.
  */
extern os_error *File_Seek(file_handle handle, file_position position);


 /*  File_ReturnPos
  *  Returns the current file pointer position.
  *  This is a value which, when passed to File_Seek, will return you to the
  *  same position you were at when you called File_ReturnPos
  */
extern file_position File_ReturnPos(file_handle handle);


 /*  File_WriteBytes
  *  This writes a chunk of data to the current position in a file opened
  *  for writing. 'numbytes' bytes will be written from the given buffer.
  *  It is important to check for errors from this call as Disc Full errors
  *  are a common occurrence.
  */
extern os_error *File_WriteBytes(file_handle handle,
                                 void *buffer, int numbytes);


 /*  File_ReadBytes
  *  Reads the given number of bytes of data from the given file, into the
  *  given buffer. Returns the number of bytes NOT successfully read.
  *  (i.e. if you hit EOF during the read, the return value will be non-zero)
  */
extern int File_ReadBytes(file_handle handle, void *buffer, int numbytes);


 /*  File_Write8
  *  Writes an 8-bit value (a byte/char) to the given output file.
  */
extern os_error *File_Write8(file_handle handle, int byte);

#define File_WriteByte File_Write8
#define File_WriteChar File_Write8


 /*  File_Read8
  *  Reads an 8-bit value (a byte/char) from the given input file.
  *  If an error (typically EOF) occurs during the read, file_READERROR
  *  will be returned.
  *
  *  VERY IMPORTANT NOTE!
  *  DO NOT use File_Read8() in a line like the following:
  *    shortvalue = File_Read8(infile) | (File_Read8(infile) << 8);
  *
  *  The problem here is that the C compiler is allowed to evaluate the 2
  *  functions in any order it sees fit, so may read the two bytes in the
  *  incorrect order. You MUST therefore do such an operation with code
  *  in the following form if you are to sure it will work:
  *    shortvalue = File_Read8(infile);
  *    shortvalue |= File_Read8(infile) << 8;
  */
extern int File_Read8(file_handle handle);

#define File_ReadByte File_Read8
#define File_ReadChar File_Read8


 /*  File_Write32
  *  Writes an 32-bit value (a word/int/long) to the given output file.
  */
extern os_error *File_Write32(file_handle handle, int word);

#define File_WriteWord File_Write32
#define File_WriteInt  File_Write32
#define File_WriteLong File_Write32


 /*  File_Read32
  *  Reads a 32-bit value (a word/int/long) from the given input file.
  *  If an error (typically EOF) occurs during the read, file_READERROR
  *  will be returned. (Note that this is a perfectly legal value to read
  *  from the file, though, so you should check file_lasterror to see if
  *  an error occurred).
  */
extern int File_Read32(file_handle handle);

#define File_ReadWord File_Read32
#define File_ReadInt  File_Read32
#define File_ReadLong File_Read32


 /*  File_Read32R
  *  Identical to File_Read32, but reverses the byte ordering as it reads
  *  (converts from little endian to big endian format). This is very useful
  *  for reading textual tags from files, as they can then be compared to
  *  integer constants of the form 'aTag' rather than having to reverse the
  *  byte order manually (i.e. using the tag 'gaTa' which is less human
  *  readable)
  */
extern int File_Read32R(file_handle handle);
#define File_ReadWordR File_Read32R
#define File_ReadIntR  File_Read32R
#define File_ReadLongR File_Read32R


 /*  File_Write32R
  *  Same as Write32, but reverses the byte order before writing. See
  *  Read32r for more details about why you'd want to do this.
  */
extern os_error *File_Write32R(file_handle handle, int word);

#define File_WriteWordR File_Write32R
#define File_WriteIntR  File_Write32R
#define File_WriteLongR File_Write32R

#endif