summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTavian Barnes <tavianator@tavianator.com>2018-09-19 18:41:33 -0400
committerTavian Barnes <tavianator@tavianator.com>2018-09-19 18:41:33 -0400
commitb5c9656a2f5be060491fae98f589f66855b8a638 (patch)
treedfdbbefcb877d4265ef705f3ca0a4158c85332da
parenta68b6d13ef4137596d4d9ec6f653c76503cc7702 (diff)
downloadbfs-b5c9656a2f5be060491fae98f589f66855b8a638.tar.xz
spawn: Add some docs
-rw-r--r--spawn.c19
-rw-r--r--spawn.h44
2 files changed, 54 insertions, 9 deletions
diff --git a/spawn.c b/spawn.c
index a54303f..ffc3d2e 100644
--- a/spawn.c
+++ b/spawn.c
@@ -63,6 +63,7 @@ int bfs_spawn_setflags(struct bfs_spawn *ctx, enum bfs_spawn_flags flags) {
return 0;
}
+/** Add a spawn action to the chain. */
static struct bfs_spawn_action *bfs_spawn_add(struct bfs_spawn *ctx, enum bfs_spawn_op op) {
struct bfs_spawn_action *action = malloc(sizeof(*action));
if (action) {
@@ -91,17 +92,19 @@ int bfs_spawn_addfchdir(struct bfs_spawn *ctx, int fd) {
}
}
-static int bfs_execvpe(const char *file, char **argv, char **envp) {
+/** Facade for execvpe() which is non-standard. */
+static int bfs_execvpe(const char *exe, char **argv, char **envp) {
#if __GLIBC__ || __linux__ || __NetBSD__ || __OpenBSD__
- return execvpe(file, argv, envp);
+ return execvpe(exe, argv, envp);
#else
extern char **environ;
environ = envp;
- return execvp(file, argv);
+ return execvp(exe, argv);
#endif
}
-static void bfs_spawn_exec(const char *file, const struct bfs_spawn *ctx, char **argv, char **envp, int pipefd[2]) {
+/** Actually exec() the new process. */
+static void bfs_spawn_exec(const char *exe, const struct bfs_spawn *ctx, char **argv, char **envp, int pipefd[2]) {
int error;
enum bfs_spawn_flags flags = ctx ? ctx->flags : 0;
const struct bfs_spawn_action *actions = ctx ? ctx->actions : NULL;
@@ -119,9 +122,9 @@ static void bfs_spawn_exec(const char *file, const struct bfs_spawn *ctx, char *
}
if (flags & BFS_SPAWN_USEPATH) {
- bfs_execvpe(file, argv, envp);
+ bfs_execvpe(exe, argv, envp);
} else {
- execve(file, argv, envp);
+ execve(exe, argv, envp);
}
fail:
@@ -131,7 +134,7 @@ fail:
_Exit(127);
}
-pid_t bfs_spawn(const char *file, const struct bfs_spawn *ctx, char **argv, char **envp) {
+pid_t bfs_spawn(const char *exe, const struct bfs_spawn *ctx, char **argv, char **envp) {
// Use a pipe to report errors from the child
int pipefd[2];
if (pipe_cloexec(pipefd) != 0) {
@@ -149,7 +152,7 @@ pid_t bfs_spawn(const char *file, const struct bfs_spawn *ctx, char **argv, char
return -1;
} else if (pid == 0) {
// Child
- bfs_spawn_exec(file, ctx, argv, envp, pipefd);
+ bfs_spawn_exec(exe, ctx, argv, envp, pipefd);
}
// Parent
diff --git a/spawn.h b/spawn.h
index 6a8a15c..ef510e1 100644
--- a/spawn.h
+++ b/spawn.h
@@ -21,23 +21,65 @@
#include <signal.h>
#include <sys/types.h>
+/**
+ * bfs_spawn() flags.
+ */
enum bfs_spawn_flags {
+ /** Use the PATH variable to resolve the executable (like execvp()). */
BFS_SPAWN_USEPATH = 1 << 0,
};
+/**
+ * bfs_spawn() attributes, controlling the context of the new process.
+ */
struct bfs_spawn {
enum bfs_spawn_flags flags;
struct bfs_spawn_action *actions;
struct bfs_spawn_action **tail;
};
+/**
+ * Create a new bfs_spawn() context.
+ *
+ * @return 0 on success, -1 on failure.
+ */
int bfs_spawn_init(struct bfs_spawn *ctx);
+
+/**
+ * Destroy a bfs_spawn() context.
+ *
+ * @return 0 on success, -1 on failure.
+ */
int bfs_spawn_destroy(struct bfs_spawn *ctx);
+/**
+ * Set the flags for a bfs_spawn() context.
+ *
+ * @return 0 on success, -1 on failure.
+ */
int bfs_spawn_setflags(struct bfs_spawn *ctx, enum bfs_spawn_flags flags);
+/**
+ * Add an fchdir() action to a bfs_spawn() context.
+ *
+ * @return 0 on success, -1 on failure.
+ */
int bfs_spawn_addfchdir(struct bfs_spawn *ctx, int fd);
-pid_t bfs_spawn(const char *file, const struct bfs_spawn *ctx, char **argv, char **envp);
+/**
+ * Spawn a new process.
+ *
+ * @param exe
+ * The executable to run.
+ * @param ctx
+ * The context for the new process.
+ * @param argv
+ * The arguments for the new process.
+ * @param envp
+ * The environment variables for the new process.
+ * @return
+ * The PID of the new process, or -1 on error.
+ */
+pid_t bfs_spawn(const char *exe, const struct bfs_spawn *ctx, char **argv, char **envp);
#endif // BFS_SPAWN_H