pathfind(), pathfind_r()

Search for a file in a list of directories

Synopsis:

#include <libgen.h>

char *pathfind( const char *path,
                const char *name,
                const char *mode );

char *pathfind_r( const char *path,
                  const char *name,
                  const char *mode,
                  char *buff,
                  size_t buff_size );

Library:

libc

Description:

The pathfind() function searches the directories named in path for the file name. The pathfind_r() function is a thread-safe version of pathfind().

The directories named in path are separated by colons. The mode argument is a string of option letters chosen from:

r

Readable.

w

Writable.

x

Executable.

f

Normal file.

b

Block special.

c

Character special.

d

Directory.

p

FIFO (pipe).

u

Set user ID bit.

g

Set group ID bit.

k

Sticky bit.

s

Size nonzero.

Options read, write, and execute are checked relative to the real (not the effective) user ID and group ID of the current process.

If the file name, with all the characteristics specified by mode, is found in any of the directories specified by path, then these functions return a pointer to a string containing the member of path, followed by a slash character (/), followed by name.

If name begins with a slash, it's treated as an absolute pathname, and path is ignored.

An empty path member is treated as the current directory. If name is found in the current directory, a slash isn't prepended to it; the unadorned name is returned.

The pathfind_r() also includes a buffer, buff, and its size, buff_size. This buffer is used to hold the path of the file found.

Returns:

The path found, or NULL if the file couldn't be found.

Examples:

Find the ls command using the PATH environment variable:

pathfind (getenv ("PATH"), "ls", "rx");

Classification:

Unix

pathfind()

pathfind_r()

Caveats:

The string pointed to by the returned pointer is stored in an area that's reused on subsequent calls to pathfind(). Don't free this string.

Use pathfind_r() in multithreaded applications.

See also:

access(), getenv(), mknod(), stat()

sh in the Utilities reference