pfFilePath(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfFilePath, pfFilePathv, pfGetFilePath, pfFindFile - Locate files using a
search path.
FUNCTION SPECIFICATION
#include <unistd.h>
#include <Performer/pr.h>
void pfFilePath(const char *path);
void pfFilePathv(const char *s, ...);
const char * pfGetFilePath(void);
int pfFindFile(const char *file, char path[PF_MAXSTRING],
int amode);
DESCRIPTION
pfFilePath specifies one or more search path locations. These locations
are directories to be searched for data files by OpenGL Performer
applications. This information is used by the pfFindFile function. The
path argument to pfFilePath is a colon or semi-colon separated list of
directory pathnames similar to the PATH environment variable. Here is a
simple example:
pfFilePath("/usr/bin:/usr/sbin:/usr/local/bin");
pfFilePathv performs the same operation as pfFilePath but uses a NULL
terminated string in lieu of a colon or semi-colon separated string.
Using pfFilePathv, the example above could be re-written as:
pfFilePathv("/usr/bin", "/usr/sbin", "/usr/local/bin", NULL):
Using pfFilePathv ensures that the proper path separator token gets
inserted depending on the target platform. Note that a maximum of 64
paths may be specified using this function.
pfGetFilePath returns the path list set using pfFilePath or NULL if no
path has yet been set. The string returned is identical in format to the
one set via pfFilePath; each of the directory names is colon or semi-
colon separated.
pfFindFile attempts to find file amongst the paths set in the environment
variable PFPATH and by pfFilePath. It also tests the file's access mode
against the amode argument. OpenGL Performer routines which access files
use pfFindFile.
Page 1
pfFilePath(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
The PFPATH environment variable is interpreted in the same format used
for the pfFilePath. A C-shell example that specifies the directories
"/usr/data" and "/usr/share/Performer/data" is:
setenv PFPATH "/usr/data:/usr/share/Performer/data"
The search logic used by pfFindFile is this:
1. First the file is sought exactly as named by file. If it
exists and passes the subsequent access test described below,
then file will be returned in the path argument.
2. If the file was not found or was not accessible, then each of
the locations defined by the PFPATH environment variable are
prepended to the file argument and tested. If it exists and
passes the subsequent access test described below, then the
complete path name will be returned in the path argument.
3. If the file has still not been successfully located, then each
of the locations defined by the most recent call to pfFilePath
will be prepended to the file argument and tested. If it
exists and passes the subsequent access test described below,
then the complete path name will be returned in the path
argument.
4. If all of these efforts are fruitless, then pfFindFile will
give up and return a NULL string in the path argument.
The mere existence of file in one of the indicated directories is not
sufficient, the file must also be accessible in the access mode defined
by amode. This mode is a bitfield composed by OR-ing together the
permission attributes defined in <unistd.h> and listed in the following
table:
Mode Token Mode Value Action
____________________________________________
R_OK 0x4 Read permission
W_OK 0x2 Write permission
X_OK 0x1 Execute and search
F_OK 0x0 Existence of file
|
|
If the bits set in amode are also set in the file's access permission
mode, then the complete path is copied into path and TRUE is returned
indicating success. If the access modes are not similar, then the search
continues until there are no more paths to search and FALSE is returned
indicating failure.
NOTES
pfFile::create and pfFile::open do not use pfFindFile. This is because
the search implied can be unpredictably slow when remote directories are
present in the search path.
Page 2
pfFilePath(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
SEE ALSO
access
Page 3
