osPfsReadWriteFile osPfsReadWriteFile (function)

Reads/writes game note game data

Syntax

#include <ultra64.h>        /* os.h */
s32 osPfsReadWriteFile(OSPfs *pfs, s32 file_no, u8 flag, int offset, int nbytes, 
                       u8 * data_buffer);

Description

The osPfsReadWriteFile reads from and writes to game notes. If PFS_READ is specified for the flag argument, data is read from the game note; if PFS_WRITE is specified data is written to the game note.

When data is read, the amount of data specified by the nbytes argument is read, beginning from the offset byte of the game data area specified by the offset argument, and stored in the area pointed to by the data_buffer argument. When data is written, nbytes of data in the area specified by data_buffer is written to the game data area beginning from the offset byte. Both the offset and nbytes arguments must be set to a multiple of BLOCKSIZE (32 bytes) and must be smaller than the file size. The arguments cannot, of course, be set so that data is read from or written to areas outside of those that have been assigned.

The file_no argument specifies the note number (file descriptor). To obtain its value, call the osPfsAllocateFile or osPfsFindFile function.

The OSPfs structure pointed to by the pfs argument is a file handle initialized by the osPfsInitPak function. For information on creating this handle, please see osPfsInitPak.

If this function is called successfully, 0 is returned. If an error occurs, one of the following error codes is returned:

PFS_ERR_NOPACK
Either the Controller Pak is not inserted into the specified Controller or the Controller is not properly connected. To determine which is the case, use osContStartQuery or osContGetQuery.

PFS_ERR_NEW_PACK
A different Controller Pak has been inserted. To use the inserted Controller Pak, initialize it by calling osPfsInitPak.

PFS_ERR_INCONSISTENT
There is a problem in the file system's management area. Usually this error does not occur because osPfsChecker is called internally when you initialize the file system by calling osPfsInitPak. If this error is returned, either the Controller Pak is not connected properly, or the Controller Pak itself is damaged.

PFS_ERR_CONTRFAIL
Data transfer to or from the Controller has failed. If a transfer error occurs, up to three tries will be done internally. Therefore, it is rather rare to see this error. If this error has returned, it is possible that either the Controller is not connected properly, or the Controller Pak or Controller Socket is damaged.

PFS_ERR_INVALID
If this error is returned, an incorrect argument was specified when this function was called, the specified game note does not exist, or the Pfs function has been called without being initialized using osPfsInitPak. Also, if the functions for the Controller were executed after the file handle structure pfs was initialized by other than osPfsInitPak, this error occurs.For instance, if osPfsReadWriteFile is executed after the initialization function for rumble pak osMotorInit is used to initialize OSPfs structure, then this error occurs.

PFS_ERR_BAD_DATA
This is returned when the function osPfsReadWriteFile attempts to read data even though the data has not yet been written. If data is written, the PFS_WRITE bit is set to indicate the status of the file information area. When data is read, this bit is checked; if it is not set, this error is returned.

See Also

osContInit, osContStartQuery, osContGetQuery, osPfsAllocateFile, osPfsChecker, osPfsDeleteFile, osPfsFileState, osPfsFindFile, osPfsFreeBlocks, osPfsInitPak, osPfsIsPlug, and osPfsReadWriteFile

Revision History

1999/02/01 Completely revised
1999/04/30 Changed format