DeskLib 2.90a:File.h


Contents


Introduction and Overview

This header defines a number of functions for handling files. These functions use RISC OS file handles, and may be quicker than the standard C file access functions (though obviously less portable).

It also defines a load of macros for various filetypes to save you having to make your own.


Functions


File_Delete

os_error * File_Delete(const char *filename);

Attempts to delete the named file. Use carefully!


File_Size

int File_Size(const char *filename);

Reads the size (in bytes) of the file. A return value of -1 indicates that an error occurred (which usually means that the file doesn't exist).


File_Exists

BOOL File_Exists(const char *filename);

This returns TRUE if the given filename is a file of some kind. This includes the file being an "image file". To check for the existence of a directory, use File_IsDirectory.


File_Open

file_handle File_Open(const char *filename, file_access access);

This attempts to open the given file for reading and/or writing depending on the 'access' asked for.

It returns the file handle, or NULL if it cannot open the file.

This sets file_lasterror, but in this case there may be no error message generated even if the file couldn't be opened, so check that it isn't NULL before using it to report an error.


File_Close

os_error * File_Close(file_handle handle);

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.

This function sets file_lasterror.


File_EOF

BOOL File_EOF(file_handle handle);

Returns TRUE if the end of the file has been reached.

This function sets file_lasterror.


File_Seek

os_error * File_Seek(file_handle handle, file_position position);

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.

This function sets file_lasterror.


File_ReturnPos

file_position File_ReturnPos(file_handle handle);

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.

This function sets file_lasterror.


File_WriteBytes

os_error * File_WriteBytes(file_handle handle, const void *buffer, int numbytes);

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.

This function sets file_lasterror.


File_ReadBytes

int File_ReadBytes(file_handle handle, void *buffer, int numbytes);

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)

This function sets file_lasterror.


File_Write8

os_error * File_Write8(file_handle handle, int byte);

Writes an 8-bit value (a byte/char) to the given output file.

This function sets file_lasterror.


File_Read8

int File_Read8(file_handle handle);

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

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;

Of course, you should be checking for errors, so it is probably a bad idea anyway.


File_Write32

os_error * File_Write32(file_handle handle, int word);

Writes an 32-bit value (a word/int/long) to the given output file.

This function sets file_lasterror.


File_Read32

int File_Read32(file_handle handle);

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


File_Read32R

int File_Read32R(file_handle handle);

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

This function sets file_lasterror.


File_Write32R

os_error * File_Write32R(file_handle handle, int word);

Same as Write32, but reverses the byte order before writing. See File_Read32R for more details about why you'd want to do this.

This function sets file_lasterror.


File_SetType

void File_SetType(const char *filename, int type);

Attempts to change the filetype of the named file.


File_GetType

int File_GetType(const char *filename);

Returns the filetype of the named file, or -1 if there is an error.


File_IsDirectory

BOOL File_IsDirectory(const char *pathname);

This returns TRUE if the given object exists and is either a directory or an image file. To check for a normal file, use File_Exists.


File_LoadTo

os_error * File_LoadTo(const char *filename, void *address, int *size);

This function loads the file whose filename is given into memory at the address specified. If 'size' is not NULL, the file size will be returned in *size.


File_Date

void File_Date(const char *filename, unsigned char *fivebytedate);

This reads the datestamp of a file into a five byte block suitable for use with, for example, Time_ConvertDateAndTime.


File_AllocLoad0

char * File_AllocLoad0(const char *filename);

This allocates space for the file with malloc, loads it, and appends a '\0'. The intention is to allow text-files to be loaded and dealt with as strings.

Returns a pointer to the loaded file, or NULL if an error occurred.


File_printf

int File_printf(file_handle file, const char *format, ... );

This is equivalent to fprintf, but taking a RISC OS file handle instead of a C stream. It prints a string to the open file whose handle is 'file' under the control of the printf-style format string format.

It returns the number of characters written or a -ve number for an error.

Note: This uses a 512 byte buffer to compose the string to be output. If your string overflows this, your program will crash or else have even nastier side-effects.


File_ReadExtent

int File_ReadExtent(file_handle handle);

Returns the current file extent (or -1 if an error occurrs)

This function sets file_lasterror.


Function-like macros


File_Copy

#define File_Copy(srce, dest, flags) \
  SWI(4, 0, SWI_OS_FSControl, 26, srce, dest, flags)

MACRO: os_error *File_Copy(char *source, char *dest, int flags);

Copies a filer object from the source location to the destination location. The source filename can contain normal OS wildcards. The destination may only contain '*' meaning "take destination leafname from source leafname".

There are 14 flag bits to define the exact action - full details are in the PRMs. Some of the more useful ones are bit 0 to enable recursive copying; bit 1 to force overwriting of of existing files; bit 3 to ask for confirmation before copying; bit 7 to delete the source files after copying them, to move files between filing systems; bit 12 to only copy if the source is newer than the destination.


File_CreateDir

#define File_CreateDir(pathname) \
  SWI(5, 0, SWI_OS_File, 8, (pathname), NULL, NULL, 0)

MACRO: os_error *File_CreateDir(char *filename);

Creates a directory of the given name. It is not an error if the directory already exists.


File_GetLength

#define File_GetLength(filename, size_ptr) \
  SWI(2, 5, SWI_OS_File, 5, (filename), NULL, NULL, NULL, NULL, (size_ptr))

MACRO: os_error *File_GetLength(char *filename, int *size_ptr);

This gets the size of the given file and places it into size_ptr.

It differs from File_Size in that it returns a standard error block if the size cannot be read for some reason.


FILETYPE

#define FILETYPE(x) (((x) & 0xFFF00) >> 8)

MACRO: int FILETYPE(int loadaddr);

This simply returns a filetype from a load address. Note that for the filetype to be valid, the top twelve bits of the load address must be set. ie. (loadaddr & 0xFFF00000) == 0xFFF00000.


Macros


file_READERROR

#define file_READERROR (-1)

Used to indicate an error while reading from a file


File_WriteByte

#define File_WriteByte File_Write8

Simply an alias for File_Write8.


File_WriteChar

#define File_WriteChar File_Write8

Simply an alias for File_Write8.


File_ReadByte

#define File_ReadByte File_Read8

Alias for File_Read8.


File_ReadChar

#define File_ReadChar File_Read8

Alias for File_Read8.


File_WriteWord

#define File_WriteWord File_Write32

Alias for File_Write32.


File_WriteInt

#define File_WriteInt  File_Write32

Alias for File_Write32.


File_WriteLong

#define File_WriteLong File_Write32

Alias for File_Write32.


File_ReadWord

#define File_ReadWord File_Read32

Alias for File_Read32.


File_ReadInt

#define File_ReadInt  File_Read32

Alias for File_Read32.


File_ReadLong

#define File_ReadLong File_Read32

Alias for File_Read32.


File_ReadWordR

#define File_ReadWordR File_Read32R

Alias for File_Read32R.


File_ReadIntR

#define File_ReadIntR  File_Read32R

Alias for File_Read32R.


File_ReadLongR

#define File_ReadLongR File_Read32R

Alias for File_Read32R.


File_WriteWordR

#define File_WriteWordR File_Write32R

Alias for File_Write32R.


File_WriteIntR

#define File_WriteIntR  File_Write32R

Alias for File_Write32R.


File_WriteLongR

#define File_WriteLongR File_Write32R

Alias for File_Write32R.


filetype_AIM

#define filetype_AIM        0x004

filetype_CLEAR

#define filetype_CLEAR      0x690

filetype_DEGAS

#define filetype_DEGAS      0x691

filetype_IMG

#define filetype_IMG        0x692

filetype_AMIGAIFF

#define filetype_AMIGAIFF   0x693

filetype_MACPAINT

#define filetype_MACPAINT   0x694

filetype_GIF

#define filetype_GIF        0x695

filetype_PCX

#define filetype_PCX        0x697

filetype_QRT

#define filetype_QRT        0x698

filetype_MTV

#define filetype_MTV        0x699

filetype_CADSOFT

#define filetype_CADSOFT    0x69A

filetype_IRLAM

#define filetype_IRLAM      0x69B

filetype_BMP

#define filetype_BMP        0x69C

filetype_TARGA

#define filetype_TARGA      0x69D

filetype_PBMPlus

#define filetype_PBMPlus    0x69E

filetype_ZVDA

#define filetype_ZVDA       0x69F

filetype_MSX2

#define filetype_MSX2       0x6A0

filetype_RLE

#define filetype_RLE        0x6A1

filetype_COLORIX

#define filetype_COLORIX    0x6A2

filetype_FITS

#define filetype_FITS       0x6A3

filetype_HAWKV9

#define filetype_HAWKV9     0x6A4

filetype_REPLAY

#define filetype_REPLAY     0xAE7

filetype_ALARMS

#define filetype_ALARMS     0xAE9

filetype_DRAWFILE

#define filetype_DRAWFILE   0xAFF

filetype_BBCROM

#define filetype_BBCROM     0xBBC

filetype_AUDIOWRK

#define filetype_AUDIOWRK   0xBD6

filetype_RENDPIC

#define filetype_RENDPIC    0xD58

filetype_ARCHIVE

#define filetype_ARCHIVE    0xDDC

filetype_PROART

#define filetype_PROART     0xDE2

filetype_PICTURE

#define filetype_PICTURE    0xDFA

filetype_HTML

#define filetype_HTML       0xFAF

filetype_PRNTDEFN

#define filetype_PRNTDEFN   0xFC6

filetype_DOSDISC

#define filetype_DOSDISC    0xFC8

filetype_SUNRASTR

#define filetype_SUNRASTR   0xFC9

filetype_DEVICE

#define filetype_DEVICE     0xFCC

filetype_CACHE

#define filetype_CACHE      0xFCF

filetype_PCEMCONF

#define filetype_PCEMCONF   0xFD0

filetype_DEBIMAGE

#define filetype_DEBIMAGE   0xFD3

filetype_MIDI

#define filetype_MIDI       0xFD4

filetype_TASKEXEC

#define filetype_TASKEXEC   0xFD6

filetype_TASKOBEY

#define filetype_TASKOBEY   0xFD7

filetype_MAKEFILE

#define filetype_MAKEFILE   0xFE1

filetype_DOS

#define filetype_DOS        0xFE4

filetype_DESKTOP

#define filetype_DESKTOP    0xFEA

filetype_OBEY

#define filetype_OBEY       0xFEB

filetype_TEMPLATE

#define filetype_TEMPLATE   0xFEC

filetype_PALETTE

#define filetype_PALETTE    0xFED

filetype_TIFF

#define filetype_TIFF       0xFF0

filetype_CONFIG

#define filetype_CONFIG     0xFF2

filetype_PRINTOUT

#define filetype_PRINTOUT   0xFF4

filetype_POSCRIPT

#define filetype_POSCRIPT   0xFF5

filetype_FONT

#define filetype_FONT       0xFF6

filetype_BBCFONT

#define filetype_BBCFONT    0xFF7

filetype_ABSOLUTE

#define filetype_ABSOLUTE   0xFF8

filetype_SPRITE

#define filetype_SPRITE     0xFF9

filetype_MODULE

#define filetype_MODULE     0xFFA

filetype_BASIC

#define filetype_BASIC      0xFFB

filetype_UTILITY

#define filetype_UTILITY    0xFFC

filetype_DATA

#define filetype_DATA       0xFFD

filetype_COMMAND

#define filetype_COMMAND    0xFFE

filetype_TEXT

#define filetype_TEXT       0xFFF

Types


file_position

typedef int file_position;

This is a type capable of holding a sequential file pointer.


file_handle

typedef int file_handle;

This is a type capable of holding an OS handle for an open file.


file_access

typedef enum
{
file_READ = 0x40,
file_WRITE = 0x80,
file_APPEND = 0xC0
} file_access;

These are used when opening files.

file_READ opens for reading. file_WRITE opens for writing, creating a new file or wiping an old one as necessary. file_APPEND opens an existing file for read/write access.

All modes open with the file pointer (position in the file) set to zero.


Variable


file_lasterror

extern os_error *file_lasterror;

file_lasterror is used to provide a more convenient SWI veneer for some of the file operations by returning handles or values directly. This leaves no convenient way to return error details from these functions.

file_lasterror is set by many of the functions, but as it is just a pointer to the error returned by the SWI it *must* by used immediately after the call or else it may be invalid. For instance, if you wish to close a file before returning the error, you must take a copy of the error first.

If no error occurred on the last file operation, file_lasterror will be NULL. Most of the functions which set it will return another value which will indicate an error at which point you can check file_lasterror for more information. Some of the functions return the error, but still set file_lasterror for convenience.