mod: bump version

README.md

@@ -9,7 +9,7 @@ but I don't like any of them. So let's overview.
 
 * `os.execvp()`, `os.execve()` — cross-platform versions of the C functions of the same name.
 
-* `os.execute()`, `os.execute_opt()`, `os.execute_or_exit()`, `os.execute_or_panic()` — starts and waits for a command to completed. Under the hood, they perform a dirty hack by calling shell with stream redirection `'exec 2>&1;${cmd}'`. Only stdout and exit_code are available in Result.
+* `os.execute()`, `os.execute_opt()`, `os.execute_or_exit()`, `os.execute_or_panic()` — starts and waits for a command to completed. Under the hood, they perform a dirty hack by calling shell with stream redirection `'exec 2>&1;${cmd}'`.
 
 * `util.execute_with_timeout()` (from `os.util`) — just an `os.execute()` wrapper.
 

cmd.v

@@ -27,9 +27,9 @@ pub mut:
 	// `maps` module: `maps.merge(os.environ(), {'MYENV': 'value'})`
 	env map[string]string
 
-	// dir specifies the current working directory for the child
-	// process. If not specified, the current working directory will
-	// be used.
+	// dir specifies the working directory for the child process.
+	// If not specified, the current working directory of parent
+	// will be used.
 	dir string
 
 	// If true create pipes for standart in/out/err streams and
@@ -69,6 +69,11 @@ pub mut:
 	// if context is timed out or canceled.
 	cancel ?CommandCancelFn
 
+	// pre_exec_hooks will be called before starting the command in
+	// the child process. Hooks can be used to modify a child's envi-
+	// ronment, for example to perform a chroot.
+	pre_exec_hooks []ProcessHookFn
+
 	// process holds the underlying Process once started.
 	process ?&Process
 
@@ -94,7 +99,7 @@ mut:
 	stdio_copy_fns []IOCopyFn
 }
 
-// run starts a specified command and waits for it. After call see the .state
+// run starts a specified command and waits for it. After call see the `.state`
 // value to get finished process identifier, exit status and other attributes.
 // `run()` is shorthand for:
 // ```v
@@ -110,12 +115,15 @@ pub fn (mut c Command) run() ! {
 // status is non-zero `ExitError` error is returned.
 // Example:
 // ```v
+// import runcmd
+//
 // mut okcmd := runcmd.new('sh', '-c', 'echo Hello, World!')
-// output := okcmd.output()!
+// ok_out := okcmd.output()!
+// println(ok_out)
 // // Hello, World!
 //
 // mut badcmd := runcmd.new('sh', '-c', 'echo -n Error! >&2; false')
-// output := badcmd.output() or {
+// bad_out := badcmd.output() or {
 // 	if err is runcmd.ExitError {
 // 		eprintln(err)
 // 		exit(err.code())
@@ -124,14 +132,15 @@ pub fn (mut c Command) run() ! {
 // 		panic(err)
 // 	}
 // }
+// println(bad_out)
 // // &runcmd.ExitError{
 // //    state: exit status 1
 // //    stderr: 'Error!'
 // // }
 // ```
 pub fn (mut c Command) output() !string {
-	mut out := strings.new_builder(4096)
-	mut err := strings.new_builder(4096)
+	mut out := strings.new_builder(2048)
+	mut err := strings.new_builder(2048)
 	c.redirect_stdio = true
 	c.stdout = out
 	c.stderr = err
@@ -152,8 +161,10 @@ pub fn (mut c Command) output() !string {
 // reading from the corresponding file descriptors is done concurrently.
 // Example:
 // ```v
+// import runcmd
 // mut cmd := runcmd.new('sh', '-c', 'echo Hello, STDOUT!; echo Hello, STDERR! >&2')
 // output := cmd.combined_output()!
+// println(output)
 // // Hello, STDOUT!
 // // Hello, STDERR!
 // ```
@@ -183,7 +194,7 @@ pub fn (mut c Command) start() !int {
 		pipes[2] = pipe()! // stderr
 	}
 
-	post_fork_parent_cb := fn [mut c, pipes] (mut p Process) ! {
+	parent_pipes_hook := fn [mut c, pipes] (mut p Process) ! {
 		if !c.redirect_stdio {
 			return
 		}
@@ -195,7 +206,8 @@ pub fn (mut c Command) start() !int {
 		fd_close(pipes[2].w)!
 	}
 
-	post_fork_child_cb := fn [mut c, pipes] (mut p Process) ! {
+	child_pipes_hook := fn [mut c, pipes] (mut p Process) ! {
+		printdbg('child pipes hook!')
 		if !c.redirect_stdio {
 			return
 		}
@@ -210,6 +222,9 @@ pub fn (mut c Command) start() !int {
 		fd_close(pipes[2].w)!
 	}
 
+	mut pre_exec_hooks := [child_pipes_hook]
+	pre_exec_hooks << c.pre_exec_hooks
+
 	if c.redirect_stdio {
 		if c.stdin != none {
 			c.stdio_copy_fns << fn [mut c] () ! {
@@ -247,14 +262,15 @@ pub fn (mut c Command) start() !int {
 
 	// Prepare and start child process.
 	path := look_path(c.path)!
+	printdbg('${@METHOD}: executable found: ${path}')
 	c.path = path
 	c.process = &Process{
-		path:                path
-		argv:                c.args
-		env:                 if c.env.len == 0 { os.environ() } else { c.env }
-		dir:                 if c.dir == '' { os.getwd() } else { c.dir }
-		post_fork_parent_cb: post_fork_parent_cb
-		post_fork_child_cb:  post_fork_child_cb
+		path:      path
+		argv:      c.args
+		env:       if c.env.len == 0 { os.environ() } else { c.env }
+		dir:       c.dir
+		post_fork: [parent_pipes_hook]
+		pre_exec:  pre_exec_hooks
 	}
 
 	mut pid := -1
@@ -335,8 +351,8 @@ pub fn (mut c Command) release() ! {
 }
 
 // stdin returns an open file descriptor associated with the standard
-// input stream of the child process. This descriptor is writable only
-// by the parent process.
+// input stream of the child process. This descriptor is write-only for
+// the parent process.
 pub fn (c Command) stdin() !WriteFd {
 	return if c.stdio[0] != -1 {
 		WriteFd{c.stdio[0]}

examples/command_with_chroot.c.v

@@ -0,0 +1,68 @@
+/*
+	Note: chroot() call requires privilege escalation in the operating system.
+	Therefore, to run this example, run: `sudo v run command_with_chroot.c.v`
+*/
+import os
+import runcmd
+import term
+
+fn C.chroot(&char) i32
+
+fn main() {
+	// Create new root filesystem for demonstration.
+	new_root := '/tmp/new_root'
+
+	// Create dirtree and copy `ls` utility with shared objects...
+	paths := {
+		0: os.join_path(new_root, 'usr', 'bin')
+		1: os.join_path(new_root, 'usr', 'lib')
+		2: os.join_path(new_root, 'lib64')
+	}
+	for _, path in paths {
+		os.mkdir_all(path)!
+	}
+	os.cp('/usr/bin/ls', paths[0])!
+	os.cp('/usr/lib/libcap.so.2', paths[1])!
+	os.cp('/usr/lib/libc.so.6', paths[1])!
+	os.cp('/lib64/ld-linux-x86-64.so.2', paths[2])!
+
+	// Create a test file in the new root.
+	os.write_file(os.join_path_single(new_root, 'HELLO_FROM_CHROOT'), 'TEST')!
+
+	// Cleanup demo root filesystem at exit.
+	defer {
+		os.rmdir_all(new_root) or {}
+	}
+
+	// Prepare the command.
+	mut cmd := runcmd.new('ls', '-alFh', '/')
+
+	// Add pre-exec hook to perform chroot().
+	cmd.pre_exec_hooks << fn [new_root] (mut p runcmd.Process) ! {
+		if C.chroot(&char(new_root.str)) == -1 {
+			return os.last_error()
+		}
+	}
+
+	// Run command and read its output.
+	out := cmd.output() or {
+		if err is runcmd.ExitError {
+			eprintln(err)
+			exit(err.code())
+		} else {
+			panic(err)
+		}
+	}
+
+	// Expected output:
+	//
+	// total 4.0K
+	// drwxr-xr-x 4 0 0 100 Jan  8 06:39 ./
+	// drwxr-xr-x 4 0 0 100 Jan  8 06:39 ../
+	// -rw-r--r-- 1 0 0   4 Jan  8 06:39 HELLO_FROM_CHROOT
+	// drwxr-xr-x 2 0 0  60 Jan  8 06:39 lib64/
+	// drwxr-xr-x 4 0 0  80 Jan  8 06:39 usr/
+
+	println('Command output: ${term.yellow(out)}')
+	println('Child state: ${cmd.state}')
+}

examples/command_with_timeout.v

@@ -11,16 +11,17 @@ fn main() {
 	mut cmd := runcmd.with_context(ctx, 'sleep', '120')
 
 	// Start a command.
-	started := time.now()
-	println('Start command at ${started}')
 	cmd.start()!
+	started := time.now()
+	println('Command started at ${started}')
 
 	// Wait for command.
 	cmd.wait()!
 
 	// The `sleep 120` command would run for two minutes without a timeout.
 	// But in this example, it will time out after 10 seconds.
-	println('Command finished after ${time.now() - started}')
+	finished := time.now()
+	println('Command finished at ${finished} after ${finished - started}')
 
 	// Since command has been terminated, the state would be: `signal: 15 (SIGTERM)`
 	println('Child state: ${cmd.state}')

examples/write_to_child_stdin.v

@@ -1,4 +1,3 @@
-import io.string_reader
 import strings
 import runcmd
 
@@ -6,12 +5,11 @@ fn main() {
 	input := 'Hello from parent process!'
 
 	// Prepare reader and writer.
-	//
 	// * `reader` reads input from the parent process; it will be copied to the
 	//    standard input of the child process.
 	// * `writer` accepts data from the child process; it will be copied from the
 	//    standard output of the child process.
-	mut reader := string_reader.StringReader.new(reader: runcmd.buffer(input.bytes()), source: input)
+	mut reader := runcmd.buffer(input.bytes())
 	mut writer := strings.new_builder(4096)
 
 	// Prepare the command.

proc.c.v

@@ -2,7 +2,7 @@ module runcmd
 
 import os
 
-pub type ProcCallbackFn = fn (mut p Process) !
+pub type ProcessHookFn = fn (mut p Process) !
 
 pub struct Process {
 pub:
@@ -18,14 +18,13 @@ pub:
 	// Working directory for the child process.
 	dir string
 
-	// The *_cb fields stores callback functions that will be executed respectively:
-	// - before calling fork();
-	// - after calling fork() in the parent process, until the function exits;
-	// - after calling fork() in the child process, until the working directory is
-	//   changed and execve() is called.
-	pre_fork_cb         ProcCallbackFn = fn (mut p Process) ! {}
-	post_fork_parent_cb ProcCallbackFn = fn (mut p Process) ! {}
-	post_fork_child_cb  ProcCallbackFn = fn (mut p Process) ! {}
+	// The pre_* and post_* fields store the functions that will be executed, respectively:
+	// - before fork() call in the parent process;
+	// - after fork() call in the parent process;
+	// - after fork() call and before execve() call in the child process.
+	pre_fork  []ProcessHookFn
+	post_fork []ProcessHookFn
+	pre_exec  []ProcessHookFn
 mut:
 	pid int = -1
 }
@@ -98,34 +97,57 @@ pub fn (s ProcessState) str() string {
 // [execve(3p)](https://man7.org/linux/man-pages/man3/exec.3p.html)
 // calls. Return value is the child process identifier.
 pub fn (mut p Process) start() !int {
-	printdbg('${@METHOD}: current pid before fork() = ${v_getpid()}')
-	printdbg('${@METHOD}: executing pre-fork callback')
-	p.pre_fork_cb(mut p)!
+	if p.pid != -1 {
+		return error('runcmd: process already started')
+	}
+
+	printdbg('${@METHOD}: executing pre-fork hooks (parent)')
+	for hook in p.pre_fork {
+		hook(mut p)!
+	}
+
 	pid := os.fork()
 	p.pid = pid
-	printdbg('${@METHOD}: pid after fork() = ${pid}')
+	if pid == -1 {
+		return os.last_error()
+	}
+
+	printdbg('${@METHOD}: child pid = ${pid}')
 
 	if pid != 0 {
 		//
-		// This is the parent process after the fork
+		// This is the parent process
 		//
-		printdbg('${@METHOD}: executing post-fork parent callback')
-		p.post_fork_parent_cb(mut p)!
-		return pid
+
+		printdbg('${@METHOD}: executing post-fork hooks (parent)')
+		for hook in p.post_fork {
+			hook(mut p)!
+		}
+	} else {
+		//
+		// This is the child process
+		//
+
+		printdbg('${@METHOD}: executing pre-exec hooks (child)')
+		for hook in p.pre_exec {
+			hook(mut p)!
+		}
+
+		mut env := []string{}
+		for k, v in p.env {
+			env << k + '=' + v
+		}
+
+		// If the working directory change was performed in a pre-exec hook,
+		// then calling os.chdir() again should be avoided. So current working
+		// directory could be checked here.
+		if p.dir != '' && os.getwd() != p.dir {
+			os.chdir(p.dir)!
+		}
+
+		os.execve(p.path, p.argv, env)!
 	}
-	//
-	// This is the child process
-	//
-	printdbg('${@METHOD}: executing post-fork child callback')
-	p.post_fork_child_cb(mut p)!
-	if p.dir != '' {
-		os.chdir(p.dir)!
-	}
-	mut env := []string{}
-	for k, v in p.env {
-		env << k + '=' + v
-	}
-	os.execve(p.path, p.argv, env)!
+
 	return pid
 }
 
@@ -154,7 +176,7 @@ pub fn (p &Process) signal(sig os.Signal) ! {
 	}
 }
 
-// kill send SIGKILL to the child process.
+// kill sends SIGKILL to the child process.
 pub fn (p &Process) kill() ! {
 	p.signal(.kill)!
 }

runcmd.v

@@ -33,9 +33,10 @@ pub fn is_present(cmd string) bool {
 }
 
 // look_path returns the absolute path to executable file. cmd may be a command
-// name or filepath (relative or absolute). If the name contains a slash, then the
-// PATH search is not performed, instead the path will be resolved and the file
-// existence and its permissions will be checked (execution must be allowed).
+// name or filepath (relative or absolute). The command is searched in PATH. If
+// the name contains a slash, then the PATH search is not performed, instead the
+// path will be resolved and the file existence will be checked. In both cases
+// the file must have the execute permission bit enabled.
 // Note: To use executables located in the current working directory use './file'
 // instead of just 'file'. Searching for executable files in the current directory
 // is disabled for security reasons. See https://go.dev/blog/path-security.

v.mod

@@ -1,7 +1,7 @@
 Module {
 	name: 'runcmd'
 	description: 'Run external commands'
-	version: '0.2.1'
+	version: '0.3.0'
 	license: 'Unlicense'
 	repo_url: 'https://github.com/gechandesu/runcmd'
 	dependencies: []