From 38da4384d3b4630787430b9b38bd4726e00cc7d9 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Fri, 4 Dec 2020 08:50:42 +0000
Subject:  Add documenting comments to exec.h

---
 src/include/skalibs/exec.h | 45 +++++++++++++++++++--------------------------
 1 file changed, 19 insertions(+), 26 deletions(-)

(limited to 'src/include')

diff --git a/src/include/skalibs/exec.h b/src/include/skalibs/exec.h
index 67fed27..57d355e 100644
--- a/src/include/skalibs/exec.h
+++ b/src/include/skalibs/exec.h
@@ -10,11 +10,19 @@
 #include <skalibs/gccattributes.h>
 
 
- /* Without environment modifications */
-
 extern void xexecvep (char const *, char const *const *, char const *const *, char const *) gccattr_noreturn ;
 extern void xexecvep_loose (char const *, char const *const *, char const *const *, char const *) gccattr_noreturn ;
 
+
+ /*
+    Direct execution with PATH (calls execvep).
+    (was called pathexec_run in earlier skalibs versions)
+    a for provided file name (default: argv[0])
+    e for provided envp (default: environ)
+    foo0 exits 0 if argv[0] is NULL
+    xfoo dies if the exec fails
+ */
+
 extern void exec_ae (char const *, char const *const *, char const *const *) ;
 #define exec_a(file, argv) exec_ae(file, (argv), (char const *const *)environ)
 #define exec_e(argv, envp) exec_ae((argv)[0], (argv), envp)
@@ -36,7 +44,15 @@ extern void xexec0_ae (char const *, char const *const *, char const *const *) g
 #define xexec0(argv) xexec0_a((argv)[0], (argv))
 
 
- /* With environment modifications : env_merge and exec */
+ /*
+    Execution with environment modifications : env_merge and exec.
+    (was called pathexec in earlier skalibs versions)
+    a for provided file name (default: argv[0])
+    e for provided envp (default: environ)
+    f for provided envp *and* length of the envp
+    m for provided modif string plus its length (the length is always needed because the modifs are null-terminated)
+    n for provided modif string, length *and* number of modifs
+ */
 
 extern int env_mexec (char const *, char const *) ;
 
@@ -136,27 +152,4 @@ extern void xmexec0_af (char const *, char const *const *, char const *const *,
 #define xmexec0_m(argv, modif, modiflen) xmexec0_am((argv)[0], (argv), modif, modiflen)
 #define xmexec0(argv) xmexec0_a((argv)[0], (argv))
 
-
- /* Compatibility */
-
-#if 0
-#define pathexec_run(file, argv, envp) exec_ae(file, argv, envp)
-#define pathexec0_run(argv, envp) exec0_e(argv, envp)
-#define xpathexec_run(file, argv, envp) xexec_ae(file, argv, envp)
-#define xpathexec0_run(argv, envp) xexec0_e(argv, envp)
-
-#define pathexec_env(key, value) env_mexec(key, value)
-#define pathexec_fromenv(argv, envp, envlen) mexec_f(argv, envp, envlen)
-#define pathexec(argv) mexec(argv)
-#define pathexec0(argv) mexec0(argv)
-#define xpathexec_fromenv(argv, envp, envlen) xmexec_f(argv, envp, envlen)
-#define xpathexec(argv) xmexec(argv)
-#define xpathexec0(argv) xmexec0(argv)
-
-#define pathexec_r_name(file, argv, envp, envlen, modif, modiflen) mexec_afm(file, argv, envp, envlen, modif, modiflen)
-#define pathexec_r(argv, envp, envlen, modif, modiflen) mexec_fm(argv, envp, envlen, modif, modiflen)
-#define xpathexec_r_name(file, argv, envp, envlen, modif, modiflen) xmexec_afm(file, argv, envp, envlen, modif, modiflen)
-#define xpathexec_r(argv, envp, envlen, modif, modiflen) xmexec_fm(argv, envp, envlen, modif, modiflen)
-#endif
-
 #endif
-- 
cgit v1.2.3