NAME

fpath -- find file by path (fpath_findName,fpath_fopen,fpath_add...)

PROTOTYPES

fpath_t * fpath_new(char *tDescription, char *tPathInit)

fpath_t * fpath_add(fpath_t* psF, char* tAddPath, int iAppend)

fpath_t * fpath_set(fpath_t* psF, char* tNewPath)

char * fpath_mod(fpath_t* psF, char* tAddPath, char cMode)

char* fpath_findName(fpath_t* psF, char* tFileName)

FILE* fpath_fopen(char *acRetCom, fpath_t* psF, char* tFileName, char* tMode)

char* fpath_getLastName(fpath_t* psF)

char* fpath_getComment(void)

int fcloseNotStd (FILE *fp)

ARGUMENTS

char *tDescription
path type
char *tPathInit
initial search path
fpath_t* psF
fpath struct fpath struct fpath struct fpath struct fpath struct
char* tAddPath
further path segment new path segment
int iAppend
indicate if appended=1 or prepended=0
char* tNewPath
new path segment, replace previous
char cMode
indicate set, appended, or prepended
char* tFileName
relative (or abs) file name file name part
char *acRetCom
return comment in preallocated string [gt.100]
char* tMode
mode "r", "w", "w~" or "a"
FILE *fp
file opened by fpath_fopen()

DESCRIPTION:

The main purpose of this stand-alone mini package is to facilitate easy searching and opening of existing files via a search path. The search path can be easily expanded. Backup copies are produced on the w~ fopen mode.

    include "fpath.h"
    fpath_t* psPath;
    psPath = fpath_new( "data", ".:~/data $DATADIR" );

fpath_t is a structure dynamically allocated by fpath_new(). tDescription is a short identifier, tPathInit the search path. Path segments are colon (sh-like) or with-space separated. All environment variables (e.g. $ARCH) are substituted if they exist (defined). The tilde is substituted by the $HOME environment variable (see example). Alternatively to fpath_new() the structure can be statically defined, e.g.:

     fpath_t gsData={ "data", ".:~/data:../wd", 0};
     fpath_t gsCirc={ "lib", "o.$ARCH:../o.$ARCH:/vol/nst/lib", 0};
     fpath_t gsExpl={ "example", "../demos:/vol/nst/share/examples", 0};

Here, the third part must be initialised to zero, to indicate static allocation. In both creation cases further path segments can be prepended or appended to the search path using fpath_add() (prepend if iAppend==0 else append).

    fpath_add(psPath, "/vol/nst/share/contrib/walter/data", 1);

The search path can later be set using fpath_set(). The function fpath_mod() offers to choose the modify operation by the char cMode. The path segment tAddPath is prepended if cMode is p P - or \\0. The resulting path is set equal to the tAddPath if cMode is = s S or \\02. Appending is performed if cMode is a A + \\01 or the default. If cMode='?' and the first path character is contained in "-=+" then tAddPath[0] is interpreted as operator instead.

    printf("modified search path (%s, mode %c)\n now: %s\n",
          argv[0], argv[1][0], fpath_mod(psPath, *argv, argv[1][0]));

Searching Filename:

fpath_findName() searches for an existing file tFileName based on the path psF. It returns the absolute or relative filename successfully found first, NULL else. If the file name starts with "/" or "./" the search path is ignored.

    if((tFile = fpath_findName(psPath, "mydata23"))!=NULL) {
       printf("found file %s\\n", tFile);
    }
    

fpath_fopen() returns the opened file with the specified mode tMode= r, w, or a. It returns NULL on failure. On write-more the search path is ignored. A verbose comment is written into the supplied string acRet. If acRet is NULL this comment is stored and (the last) can be inspected using (char*) fpath_getComment(void). The special file names tFileName= -, stdin, stdout, and stderr are recognized in the appropriate modes (- as stdin on r, or stdout on w). In order not to close standard file descriptors one should use fcloseNotStd() to close the returned FILE.
mode w~ convenient backup mode:
finds first existing file, renames is to suffix "~" and opens a new file with the found filename. If no file is found it behaves as the w mode:
mode w:
tries to open the given file name, ignoring the search path.
mode a:
appends to the first found existing file, otherwise behaves as mode w (ignoring path).
The last found file name can be accessed by calling fpath_getLastName. fpath_free() deallocates the structure fpath_t appropriately.

    char acCom[200]; FILE* fp;
    fp = fpath_fopen(acCom, psPath, "mydata23", "r");
    printf("Open comment: %s\n", acCom);
    printf("File name: %s\n", fpath_getLastName(psPath) );
                /* make auto-backup */
    fp = fpath_fopen(NULL, psPath, "mydata", "w~");
                /* handle standard descriptors */
    fp = fpath_fopen(NULL, psPath, "-", "r");
    printf("last open message was %s;\n", fpath_getComment());
                /* -- or -- */
    fp = fpath_fopen(NULL, psPath, "stderr", "w");
    fcloseNotStd(fp);

The source file containes code for a test program. JW 07-97.

FILE

/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/fpath.c