From 96cf8dffe4f7b0b910f790066ae622dc429eb522 Mon Sep 17 00:00:00 2001
From: Jannis Hoffmann <jannis@fehcom.de>
Date: Tue, 9 Jul 2024 13:02:45 +0200
Subject: initial commit of version 23

---
 man/pathexec.3 | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 man/pathexec.3

(limited to 'man/pathexec.3')

diff --git a/man/pathexec.3 b/man/pathexec.3
new file mode 100644
index 0000000..41dc978
--- /dev/null
+++ b/man/pathexec.3
@@ -0,0 +1,124 @@
+.TH qlibs: pathexec 3
+.SH NAME
+pathexec \- run a program within a given environment
+.SH SYNTAX
+.B #include \(dqpathexec.h\(dq
+
+\fBpathexec_run\fP(const char *\fIp\fR,char **\fIa\fR,char **\fIe\fR);
+.br
+\fBpathexec\fP(char *const *\fIa\fR);
+.br
+\fBpathexec_env\fP(const char *\fIs\fR,char *\fIt\fR);
+.SH DESCRIPTION
+.B pathexec_run 
+searches for a program named 
+.IR p . 
+It replaces the current process with a copy of that program. 
+The main function in that program will be given arguments 
+.I a 
+and environment 
+.IR  e .
+.B pathexec_run 
+looks for 
+.I p 
+as specified by the 
+.I $PATH 
+environment variable. 
+.I $PATH 
+is a colon-separated list of directories 
+.IR d ;
+.B pathexec_run 
+tries 
+.B execve 
+on files named 
+.IR d/p , 
+in the order that the directories appear inside 
+.IR $PATH . 
+An empty directory name is treated as a single dot.
+
+If 
+.I $PATH 
+is not set, 
+.B pathexec_run 
+uses the path 
+.IR  /bin:/usr/bin ; 
+i.e., it tries 
+.B execve 
+on 
+.IR /bin/p , 
+then 
+.IR /usr/bin/p .
+
+If 
+.I p 
+contains a slash, 
+.B pathexec_run 
+ignores 
+.I $PATH 
+and simply runs 
+.B execve 
+on a file named 
+.IR p .
+
+.B pathexec 
+calls 
+.B pathexec_run 
+with program name 
+.IR a[0] , 
+arguments 
+.IR a , 
+and the same environment as the current process, 
+modified as described below. 
+.B pathexec 
+has the same return behavior as 
+.BR pathexec_run .
+.B pathexec_env 
+modifies the environment used by 
+.BR pathexec . 
+It removes a variable named 
+.IR s, 
+if one exists. It then adds a variable named 
+.I s 
+with value 
+.IR t, 
+if the pointer 
+.I t 
+is nonzero. The name 
+.I s 
+must not contain 
+.IR = .
+.SH "RETURN CODES"
+Normally
+.B pathexec_run
+does not return, because the process has been replaced.
+However, if all the
+.B execve
+attempts fail,
+.B pathexec_run
+returns, setting
+.I errno
+to the most interesting error returned by
+.BR execve .
+Furthermore,
+.B pathexec_run
+returns immediately if an
+.B execve
+attempt fails with an error other than
+.IR error_noent ,
+.IR error_acces ,
+.IR error_perm ,
+or
+.IR  error_isdir .
+This list is subject to change.
+
+Normally 
+.B pathexec_env 
+returns 
+.IR 1 . 
+If it is unable to allocate memory, it returns 
+.IR 0 , 
+leaving the 
+.B pathexec 
+environment alone.
+.SH "SEE ALSO"
+error(3)
-- 
cgit v1.2.3