pfFile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFile(3pf)NAME
pfCreateFile, pfOpenFile, pfCloseFile, pfReadFile, pfSeekFile,
pfWriteFile, pfGetFileStatus, pfGetFileClassType - Asynchronous real-time
file access operations
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfFile * pfCreateFile(char *path, mode_t mode);
pfFile * pfOpenFile(char *fname, int oflag, ...);
int pfCloseFile(pfFile *file);
int pfReadFile(pfFile *file, char *buf, int nbyte);
off_t pfSeekFile(pfFile *file, off_t off, int whence);
int pfWriteFile(pfFile *file, char *buf, int nbyte);
int pfGetFileStatus(const pfFile *file, int attr);
pfType * pfGetFileClassType(void);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfFile is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfFile. Casting an object of class
pfFile to an object of class pfObject is taken care of automatically.
This is also true for casts to objects of ancestor classes of class
pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfFile can also be used with these functions
designed for objects of class pfMemory.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
Page 1
pfFile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFile(3pf)
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
DESCRIPTION
The functions pfCreateFile, pfOpenFile, pfCloseFile, pfReadFile,
pfWriteFile, and pfSeekFile operate in an identical fashion and take
similar arguments as the standard UNIX file I/O functions: creat, open,
close, read, write, and lseek. The difference is that they return
immediately without blocking while the physical file-system access
operation completes and also that instead of an integer file descriptor,
a pfFile handle is used. OpenGL Performer supports a maximum of
PFRTF_MAXREQ pending file I/O requests.
When called, pfOpenFile and pfCreateFile create a new process using the
sproc mechanism that manages the file operations asynchronously with the
calling process. If the calling process has super-user privileges, the
new process will assign itself to processor 0, and lower its priority.
The spawned process will exit when either its pfFile is closed via
pfCloseFile or when its parent process (that which called pfOpenFile or
pfCreateFile) exits.
pfCloseFile closes the open file and terminates the I/O process created
by pfOpenFile or pfCreateFile. pfCloseFile does not free file - use
pfDelete for that purpose.
pfGetFileClassType returns the pfType* for the class pfFile. The pfType*
returned by pfGetFileClassType is the same as the pfType* returned by
invoking pfGetType on any instance of class pfFile. Because OpenGL
Performer allows subclassing of built-in types, when decisions are made
based on the type of an object, it is usually better to use pfIsOfType to
test if an object is of a type derived from a Performer type rather than
to test for strict equality of the pfType*'s.
pfGetFileStatus returns the status of file corresponding to attr which
may be one of:
PFRTF_STATUS Return 0 if last action complete and no other
actions pending. 1 if action in progress, and
-1 if last action failed.
Page 2
pfFile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFile(3pf)
PFRTF_CMD Return the current (or last) file I/O action,
one of the following:
PFRTF_NOACTION
PFRTF_CREATE
PFRTF_OPEN
PFRTF_READ
PFRTF_WRITE
PFRTF_SEEK
PFRTF_CLOSE
PFRTF_PENDING
PFRTF_BYTES Return the number of bytes from the last read or
write action.
PFRTF_OFFSET Return the offset from the last seek action.
PFRTF_PID Return the process id of the I/O process
associated with file.
NOTES
OpenGL Performer for Linux does not currently support Direct File I/O.
The need for the pfFile facility has been largely superseded by the IRIX
5 asynchronous I/O facility. These capabilities are accessible through
aio_cancel, aio_error, aio_init, aio_read, aio_return, aio_suspend, and
aio_write. Users are encouraged to use the aio functions for performing
asynchronous file operations in programs now in development.
The calling process should always call pfCloseFile to close a file before
exiting. If the calling program exits without doing so, the file will
not be closed. Such files can be challenging to remove from the file
system.
SEE ALSO
access, aio_cancel, aio_error, aio_init, aio_read, aio_return,
aio_suspend, aio_write, close, creat, fcntl, lseek, open, read, write
Page 3
