qlibs:

Section: Misc. Reference Manual Pages (pathexec)
Updated: 3
Index Return to Main Contents

NAME

pathexec - run a program within a given environment

SYNTAX

#include "pathexec.h"

pathexec_run(const char *p,char **a,char **e);
pathexec(char *const *a);
pathexec_env(const char *s,char *t);

DESCRIPTION

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.

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 =.

RETURN CODES

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.

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