PATH(3)

NAME
path - procedures for managing search paths in libmagicutils.a

SYNOPSIS
#include <stdio.h>
#include utils.h

int PaConvertTilde(psource, pdest, size)
char **psource, **pdest;
int size;

FILE *PaOpen(file, mode, ext, path, libpath, prealname)
char *file, *mode, *ext;
char *path, *libpath;
char **prealname;

char *PaSubsWD(path, newWD)
char *path, *newWD;

int PaEnum(path, file, func, cdata)
char *path, *file;
int (*func)(name, cdata);
ClientData cdata;

DESCRIPTION
These procedures implement a path mechanism, whereby several places may be searched for files.

PaConvertTilde is used to convert csh(1)-style tilde notation for users' home directories (e.g., ``~wss'', ``~/mydir/file.o'') to standard directory names as understood by open(2), etc. If **psource is a tilde (``~''), then the name following the tilde up to the first slash or end of string is converted to a home directory and stored in the string pointed to by *pdest. Then remaining characters in the file name at *psource are copied to *pdest (the file name is terminated by white space, a NULL character, or a colon) and *psource is updated. Upon return, *psource points to the terminating character in the source file name, and *pdest points to the null character terminating the expanded name. If a tilde cannot be converted because the user name cannot be found, *psource is still advanced past the current entry, but nothing is stored at the destination. At most size characters (including the terminating null character) will be stored at *pdest. The name consisting of a single tilde, i.e, ``~'' with no user name, expands to the current user's home directory. PaConvertTilde returns the number of bytes of space left in the destination area if successful, or -1 if the user name couldn't be found in the password file.

PaOpen opens a file, looking it up in the current path and supplying a default extension. It either returns a pointer to a FILE, as does fopen(3s), or NULL if no file could be opened. The mode of the file opened is determined by mode, also as in fopen. If ext is specified, then it is tacked onto the end of name to construct the name of the file PaOpen will attempt to find. (Ext must begin with a dot if that is the extension separator; none is inserted automatically.) If the first character of name is a tilde or slash, PaOpen tries to look up the file with the original name (and extension), doing tilde expansion if necessary and returning the result. Otherwise, it goes through the search path path (a colon-separated list of directories much as in csh(1)) one entry at a time, trying to look up the file once for each path entry by prepending the path entry to the original file name. This concatenated name is stored in a static string and made available to the caller by setting *prealName to point to it if prealName is non-NULL and if the open succeeds. If the entire path is tried, and still nothing works, then we try each entry in the library path libpath next. The static string will be trashed on the next call to this routine. Also, no individual file name is allowed to be more than 200 characters long; excess characters are lost.

PaSubsWD replaces all uses of the working directory in a path by some fixed directory. It returns a pointer to a path that is just like path, except that every implicit or explicit use of the working directory (``.'') is replaced by the newWD argument. The result is a static array, which will be trashed on the next call to this procedure.

PaEnum is used to call a client procedure with each directory in path prepended to the string file. The client procedure is of the form (*func)(name, cdata), where name is a directory in the path prepended to file, and cdata is the same as cdata passed to PaEnum. This client procedure should return 0 normally, or 1 to abort the path enumeration. If a directory in the search path refers to a non-existent user name (using the ``~user'' syntax), we skip that component. PaEnum returns 0 if all clients returned 0, or 1 if some client returned 1. If some client returns 1, the enumeration is aborted.

SEE ALSO
magicutils(3)