The <files.h> Header File

Routines for accessing files (needs AMS 2.00 or later)

This set of routines (available only in AMS 2.00 or later) gives the possibility of managing custom type files.

They give a 'higher' level way for managing custom type symbols in the Variable Allocation Table than the routines in vat.h.

They can in any case be used in conjunction with the vat.h routines.

However, files.h routines are different from the file routines contained in stdio.h. First of all, they do not use the same files structures. Moreover, stdio.h file functions are GCC4TI library functions working with any AMS versions while files.h functions are AMS (TIOS) functions which are only available under AMS 2.00 and later. They do have the advantage of not requiring extra code in your program, unlike stdio.h.

Therefore the following routines must never be used with stdio.h file routines for the same file stream at the same time.

Functions

FAccess
Check to see if a file can be opened for a given mode without modifying the file.
FClose
Close a file.
FCreate
Create an empty file.
FDelete
Deletes a file.
FEof
Returns TRUE if a file is at the end.
FFindFirst
Find the first file of a given type.
FFindNext
Find the next symbol as set up by a call to FFindFirst.
FGetC
Read a byte from an open file.
FGetPos
Return the current file position.
FGetSize
Return the number of bytes currently stored in an opened file.
FOpen
Open a file for a specific mode.
FPutC
Write a byte to a file opened in write mode.
FRead
Read a given number of bytes from an open file.
FSetBufSize
Set the buffer size of a file.
FSetPos
Set the position of the next read or write for an opened file.
FSetSize
Truncate the size of a file opened in write mode.
FSetVer
Change the version number of an opened file.
FStatus
Return the status of a file.
FType
Gives the type of a specified file.
FWrite
Write a specified number of bytes to a file.

Predefined Types

fileMode
An enumeration for describing possible file modes.
FILES
A structure for defining a file.
FileStatusEnum
An enumeration for describing possible file statuses.
FindOptions
Describes options for SymFindFirst and FFindFirst.
HSym
A structure representing a symbol reference.
SYM_ENTRY
A structure representing a VAT symbol entry.

See also: stdio.h, vat.h


FAccess

AMS 2.00 or higher

unsigned short FAccess (const char *fileName, unsigned short mode, const char *typeName);

Check to see if a file can be opened for a given mode without modifying the file.

FAccess checks to see if the file fileName can be opened for the given mode mode without modifying the file first. The file, if it exists, must have the same type as typeName. fileName and typeName are normal zero-terminated C strings (i.e. you do not have to tokenize them).

mode is the given mode to be checked. This parameter can either be FM_READ_ACCESS or FM_WRITE_ACCESS.

typeName is a string which gives the type of the file to open. typeName is a normal-zero terminated C string which must contain one to four characters.

The value returned by FAccess is one of the following, as described in the FileStatusEnum enum:
FS_OKThe file can be opened in the given mode.
FS_ERRORThe file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type.)
FS_NOT_FOUNDfileName does not exist.
FS_BAD_NAMEfileName is invalid.

See also: FOpen, FCreate


FClose

AMS 2.00 or higher

unsigned short FClose (FILES *fsPtr);

Close a file.

FClose closes the file fsPtr. This is required for files opened in WRITE mode. For files in READ mode, FClose just updates the fsPtr->fileMode and fsPtr->fileStatus fields in the FILES structure.

fsPtr is a pointer to a FILES structure that was previously opened with FOpen.

FClose returns FS_OK if the file was successfully closed. There is extra overhead required for a file that is always kept around by the file system and so closing a file will only return an error if the file or the heap has been damaged.

See also: FAccess, FOpen, FStatus


FCreate

AMS 2.00 or higher

unsigned short FCreate (const char *fileName, const char *typeName);

Create an empty file.

FCreate creates an empty file with the name fileName and the type typeName. It is normally only needed if multiple files must be simultaneously opened in write mode. Filename is not a tokenized variable name (as required by the symbol table code) but rather a normal zero-terminated C string of characters. It must not be a reserved name. If filename does not contain a folder name, the file will be stored in the current folder. Internally, files are stored as custom (third-party) data type files (i.e. they are defined with the OTH_TAG). They will show up to the user in the VAR-LINK screen as the type specified when the FILE was opened (up to four letters).

typeName must point to a normal zero-terminated C string of at most four characters which describes the file type (FS_ERROR is returned if it does not).

FCreate returns one of the following values, as described in the FileStatusEnum enum:
FS_OKThe file was opened for the specified mode.
FS_ERRORThe file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type.)
FS_BAD_NAMEfileName is invalid.
FS_MEMORYNot enough memory.

See also: FClose, FOpen


FDelete

AMS 2.00 or higher

unsigned short FDelete (const char *fileName);

Deletes a file.

FDelete deletes the file fileName. fileName is a normal zero-terminated C string (i.e. it musn't be tokenized).
Note: FDelete may invalidate any current HSyms.

FDelete may return one of the following values as described in the FileStatusEnum enum:
FS_OKFile deleted.
FS_BAD_NAMEBad filename.
FS_ERRORFile not deleted because it is locked, in use, a folder, in Flash, or it does not exist.

See also: FCreate


FEof

AMS 2.00 or higher

short FEof (FILES *fsPtr);

Returns TRUE if a file is at the end.

FEof returns TRUE if the file fsPtr is at the end of File mark, and FALSE otherwise. fsPtr must be a pointer to a FILES structure opened with FOpen.

Note that this is not an error condition (as returned by FStatus) and can be changed not only by reading from a file but also by changing the current file position.

See also: FOpen, FSetPos, FGetPos


FFindFirst

AMS 2.00 or higher

SYM_ENTRY *FFindFirst (unsigned short Options, const char *typeName, const char *folderName);

Find the first file of a given type.

FFindFirst finds the first file of the type typeName and returns a SYM_ENTRY pointer to it (or NULL if none found). typeName must point to a normal zero-terminated C string (i.e. not a tokenized form) of at most four characters which describes the file type. Use FFindNext to find subsequent entries, NULL will be returned after the last entry is found.

Options can be one of the following flags as described in the FindOptions enum:
FO_NONEWhen this flag is set, folderName is a string pointer to the folder to search.
FO_RECURSEWhen this flag is set, FFindFirst searches all folders (folderName is ignored).


FFindFirst returns a SYM_ENTRY pointer to the first file with a type matching typeName or NULL if none found. The Name field of the SYM_ENTRY contains the name of the file being searched for as an 8 character string. If using FO_RECURSE, then calling SymFindFolderName will return the folder of the symbol just found.

Note: SYM_ENTRY pointers are only valid until heap compression is done or another symbol is added to the symbol table.

See also: FFindNext, SymFindFolderName


FFindNext

AMS 2.00 or higher

SYM_ENTRY *FFindNext (void);

Find the next symbol as set up by a call to FFindFirst.

FFindNext finds the next symbol as set up by a call to FFindFirst and returns a SYM_ENTRY pointer to it, or NULL if no more symbols can be found.
The pointer returned by FFindNext is a SYM_ENTRY pointer to a file with a type matching the one set up by a previous call to FFindFirst. If using FO_RECURSE, then calling SymFindFolderName will return the folder of the symbol just found.
Note that FFindFirst must have been called previously to find the first symbol.

Note: SYM_ENTRY pointers are only valid until heap compression is done or another symbol is added to the symbol table.

See also: FFindFirst, SymFindFolderName


FGetC

AMS 2.00 or higher

unsigned short FGetC (FILES *fsPtr);

Read a byte from an open file.

FGetC reads a byte from the open file fsPtr (which may be opened in either READ or WRITE mode) at the current file position and returns the byte, or FS_EOF if the end of file was reached.
fsPtr is a pointer to a FILES structure previously opened with FOpen.

Note that the FILES structure pointed to by fsPtr must have been opened with FOpen.

FGetC returns the next byte in the file, or FS_EOF if the end of file has been reached.

See also: FOpen, FPutC, FRead, FSetPos


FGetPos

AMS 2.00 or higher

unsigned short FGetPos (FILES *fsPtr);

Return the current file position.

FGetPos returns the current file position (where the next read or write would occur) for the file pointed to by fsPtr.fsPtr is a pointer to a FILES structure previously opened with FOpen.

Note that the FILES structure pointed to by fsPtr must have been previously opened with FOpen.

FGetPos returns the current file position.

See also: FOpen, FSetPos, FEof


FGetSize

AMS 2.00 or higher

unsigned short FGetSize (FILES *fsPtr);

Return the number of bytes currently stored in an opened file.

FGetSize returns the number of bytes currently stored in the opened file fsPtr.

The FILES structure pointed to by fsPtr must have been previously opened with FOpen (either in read or in write mode).

See also: FOpen, FSetSize


FOpen

AMS 2.00 or higher

unsigned short FOpen (const char *fileName, FILES *fsPtr, unsigned short mode, const char *typeName);

Open a file for a specific mode.

FOpen opens the file fileName for the mode mode. fileName is not a tokenized variable name (as required by the symbol table code), but rather a normal zero-terminated C string of characters. It must not be a reserved name. If fileName does not contain a folder name, the file will be stored in (or read from) the current folder. Internally, files are stored as custom (third-party) data-type files (OTH_TAG). They will show up to the user in the VAR-LINK screen as the type specified when the file was opened (up to four letters).

When a file is opened with FOpen in FM_WRITE or FM_APPEND mode, the associated variable is locked and inaccessible by any other routines in the system. It must be closed with FClose to return the variable to a not-in-use mode, to write the file type and the OTH_TAG, and to close the associated buffer. For files opened in FM_READ mode, the call to FClose will merely update the mode of the file in the FILES structure to closed and clear the associated error status.

There is no separate mode to open a file for both reading and writing. However, if a file is opened in FM_APPEND mode, the contents of the file are not erased and the file may be subsequently positioned to any location in the file (random access) and either read from or written to. For all access modes, the given name must not be a system variable. For FM_READ and FM_APPEND the name must correspond to an existing file of a custom data-type. For FM_WRITE the file must either not exist or correspond to a file of a custom data-type which is not locked or marked in-use.

Note that for files in read mode, FClose merely updates the fsPtr->fileMode field in the FILES structure to indicate it is closed. For write mode, it must be called to update information in the file needed by the system. While a file is in write mode, it is marked as in-use so that no other application, nor the system itself, will try to access it (it will not be visible in the VAR-LINK screen either). Files in write or append mode may be accessed randomly by using FSetPos.

Note: Any number of files may be simultaneously opened in read mode. If multiple files are opened simultaneously in write (or append) mode, all but the first file must already exist before they are opened. Use the FCreate routine if they need to be created as empty files before they are opened with FOpen.

typeName must point to a normal (non-tokenized) zero-terminated C string of at most four characters which describes the file type (FS_ERROR is returned if it does not). If there is an existing file with the same name as fileName, the types must match.

fsPtr is a pointer to a structure of type FILES.

The parameter mode can be one of the following commands, as described in the fileMode enum:
FM_READThe file must exist and can only be read.
FM_WRITEOpen the file for writing and erase its contents. Create the file if it does not exist.
FM_APPENDIf the file exists, open it for writing at the end of the file. If it does not exist, then create it and open it for writing.

FOpen returns one of the following values as described in the FileStatusEnum enum:
FS_OKThe file was opened for the specified mode.
FS_ERRORThe file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type, or typeName may be invalid.)
FS_BAD_NAMEfileName is invalid.
FS_MEMORYNot enough memory.

The return value is also stored in fsPtr->fileStatus in the FILES structure.
The FILES pointer fsPtr may then be used in subsequent file routines.

This routine may cause heap compression or invalidate any current HSyms.

See also: FAccess, FClose, FRead, FGetC, FSetPos, FStatus, FWrite, FPutC


FPutC

AMS 2.00 or higher

unsigned short FPutC (short byte, FILES *fsPtr);

Write a byte to a file opened in write mode.

FPutC writes the byte byte to the file fsPtr opened in write mode at the current file position. The FILES structure pointed to by fsPtr must have been opened with FOpen in write mode.

FPutC returns FS_OK if successful, FS_ERROR if the file is not opened for write mode or FS_MEMORY if the system is out of memory.

Note: Any error will cause the file status to be set to FS_ERROR so that multiple writes may be performed without checking the return status as long as an FStatus is done at the end to make sure all of the writes were successful.

This routine may cause heap compression.

See also: FOpen, FGetC, FWrite, FSetPos, FStatus


FRead

AMS 2.00 or higher

unsigned short FRead (void *buffer, unsigned short bytesToRead, FILES *fsPtr);

Read a given number of bytes from an open file.

FRead reads bytesToRead bytes from the open file fsPtr (which may be opened in either read or write mode) into buffer. fsPtr must be a pointer to a FILES structure previously opened with FOpen. buffer must be a pointer to a buffer at least bytesToRead bytes long.

FRead returns FS_OK if the file read was successful or FS_EOF if it read past the end of the file.

See also: FOpen, FWrite, FGetC, FSetPos


FSetBufSize

AMS 2.00 or higher

unsigned short FSetBufSize (FILES *fsPtr, unsigned short newBufSize);

Set the buffer size of a file.

FSetBufSize sets the buffer size of the file fsPtr to a new one: newBufSize. The buffer size determines how much memory is reallocated to the file every time a write needs more memory from the heap. The default size (128 bytes) is set when the file is opened and should be sufficient for most uses. Setting a larger value will make writes faster but at the cost of possibly prematurely running out of memory.

FSetBufSize returns the value stored in newBufSize.

See also: FOpen, FWrite


FSetPos

AMS 2.00 or higher

unsigned short FSetPos (FILES *fsPtr, unsigned short pos);

Set the position of the next read or write for an opened file.

FSetPos sets the position pos of the next read or write for the opened file fsPtr and returns the new position (which may be less than specified if the end of the file is exceeded). fsPtr must be a pointer to a FILES structure previously opened with FOpen.

pos is the file position (0 being the first byte in the file) to set.

See also: FOpen, FGetPos, FEof


FSetSize

AMS 2.00 or higher

unsigned short FSetSize (FILES *fsPtr, unsigned short fileSize);

Truncate the size of a file opened in write mode.

FSetSize truncates the size of the file opened in write mode to fileSize, which may not exceed the current file size. Return the new file size, but no more than the current size. Note that in read mode, the current file size is always returned without making any changes. fsPtr must be a pointer to a FILES structure previously opened with FOpen for writing.

See also: FOpen, FGetSize


FSetVer

AMS 2.00 or higher

unsigned char FSetVer (FILES *fsPtr, unsigned char newVer);

Change the version number of an opened file.

FSetVer changes the version number of the opened file fsPtr to the new one newVer and returns the old version number. Note that the file can be in read or write mode. fsPtr is a pointer to a FILES structure previously opened with FOpen in either read or write mode. The version number of a file is stored in the file’s symbol table entry. It is a byte and is used internally by TIOS to verify that a newer version of a symbol is not sent to an older TI-89, TI-92, or TI-92 Plus.

See also: FOpen


FStatus

AMS 2.00 or higher

unsigned short FStatus (FILES *fsPtr);

Return the status of a file.

FStatus returns the status of the file fsPtr: FS_OK if no errors have occurred, or FS_ERROR if any errors have occurred. Note that errors accumulate so that multiple writes may be done on a file as long as the status is checked after the last write. The only way to clear the status is to close the file.

fsPtr must be a pointer to a FILES structure previously opened with FOpen.

See also: FOpen, FClose, FWrite, FPutC


FType

AMS 2.00 or higher

unsigned short FType (const char *fileName, char *buf);

Gives the type of a specified file.

FType writes the type of the file fileName into the buffer buf as a zero-terminated string. The buffer should be a least 5 bytes long (four bytes + a zero terminating byte). fileName file must not be opened for write mode.

FType can return one of the following values as enumerated in the FileStatusEnum enum:
FS_OKFtype successfully wrote the type of the file into buf.
FS_ERRORAn error occured while opening the file, or the file was opened successfully, but the type field is invalid.
FS_BAD_NAMEfileName is invalid.

Note that FType will always fail if the given file is already opened for write mode.

See also: FOpen


FWrite

AMS 2.00 or higher

unsigned short FWrite (const void *buffer, unsigned short bytesToWrite, FILES *fsPtr);

Write a specified number of bytes to a file.

FWrite writes bytesToWrite bytes of data from the buffer buffer to the output file associated with the FILES structure pointed to by fsPtr. The data written begins at the current file position. buffer is a pointer to any object.

FWrite returns one of the following values as enumerated in the FileStatusEnum enum:
FS_OKThe write was successful.
FS_ERRORThe file fsPtr is not opened in write mode.
FS_MEMORYOut of memory.

Note: Any error will cause the file status to be set to FS_ERROR so that multiple writes may be performed without checking the return status as long as an FStatus is done at the end to make sure all of the writes were successful.

See also: FOpen, FPutC, FRead, FClose


fileMode

enum fileMode {
FM_CLOSED=0, FM_READ=1, FM_WRITE=2, FM_APPEND=3, FM_READ_ACCESS=1, FM_WRITE_ACCESS=4
};

An enumeration for describing possible file modes.

These constants describe the file modes stored in the FILES structure and needed by nearly every files.h function.


FILES

typedef struct fileStruct {
unsigned short dataLen;
unsigned short dataPos;
unsigned short bufSize;
HANDLE dataH;
unsigned char fileFlags, fileMode;
unsigned short fileStatus;
HSym hSym;
char type[5];
} FILES;

A structure for defining a file.

fileStruct is a structure for defining a file, used in commands like FOpen.


FileStatusEnum

enum FileStatusEnum {FS_OK = 0x0000, FS_EOF = 0xFFFF, FS_ERROR = 0xFFFE, FS_BAD_NAME = 0xFFFD, FS_MEMORY = 0xFFFC, FS_NOT_FOUND = 0xFFFB};

An enumeration for describing possible file statuses.

These constants describe the file status codes stored in the FILES structure and returned by nearly every files.h function.


Return to the main index