D. J. Bernstein

The pathexec library interface

     #include <pathexec.h>

     pathexec_run(p,a,e);

     char *p;
     char **a;
     char **e;
pathexec_run searches for a program named p. It replaces the current process with a copy of that program. The main function in that program will be given arguments a and environment e.

pathexec_run looks for p as specified by the $PATH environment variable. $PATH is a colon-separated list of directories d; pathexec_run tries execve on files named d/p, in the order that the directories appear inside $PATH. An empty directory name is treated as a single dot.

If $PATH is not set, pathexec_run uses the path /bin:/usr/bin; i.e., it tries execve on /bin/p, then /usr/bin/p.

If p contains a slash, pathexec_run ignores $PATH and simply runs execve on a file named p.

Normally pathexec_run does not return, because the process has been replaced. However, if all the execve attempts fail, pathexec_run returns, setting errno to the most interesting error returned by execve. Furthermore, pathexec_run returns immediately if an execve attempt fails with an error other than error_noent, error_acces, error_perm, or error_isdir. This list is subject to change. 

     #include <pathexec.h>

     pathexec(a);
     pathexec_env(s,t);

     char **a;
     char *s;
     char *t;
pathexec calls pathexec_run with program name a[0], arguments a, and the same environment as the current process, modified as described below. pathexec has the same return behavior as pathexec_run.

pathexec_env modifies the environment used by pathexec. It removes a variable named s, if one exists. It then adds a variable named s with value t, if the pointer t is nonzero. The name s must not contain =.

Normally pathexec_env returns 1. If it is unable to allocate memory, it returns 0, leaving the pathexec environment alone.

Compatibility notes

pathexec is intended as a replacement for execvp. It is also intended as a replacement for setenv, putenv, and unsetenv in programs that are merely setting up a post-exec environment.

execvp runs sh manually if execve returns an executable-format error. pathexec_run doesn't; it relies on the kernel to decide how to run programs.

execvp pauses and tries again later if execve returns an executable-busy error. pathexec_run doesn't; the caller must handle temporary failures properly.

Some versions of execvp use .:/bin:/usr/bin as the default path. Some versions of execvp use /bin:/usr/bin:. as the default path.