28 System
| (require denxi/system) | package: denxi |
denxi/system extends and reprovides racket/system. It specializes process management in the context of packages.
setting
DENXI_SUBPROCESS_TIMEOUT_S : (>=/c 0) = 1800
value
ALL_OS_SYMS : (listof symbol?)
syntax-class
procedure
(run [ #:expected-exit-codes expected-exit-codes #:timeout timeout #:stdin stdin #:fail-on-stderr? fail-on-stderr? #:controller controller #:cwd wd] command arguments ...) → subprogram? expected-exit-codes : (listof (integer-in 0 255)) = '(0) timeout : exact-positive-integer? = (* 60 60) stdin : (or/c #f input-port?) = #f fail-on-stderr? : boolean? = #t controller : any/c = private wd : path-string? = (current-directory) command : path-string? arguments : (or/c path-string? string-no-nuls? bytes-no-nuls?)
P creates a subprocess with the given command and arguments, with wd set as the working directory. P will ensure the subprocess finishes before returning control.
Denxi prohibits execution of any file that the user does not trust.
The result is FAILURE if the command is not found, the subprocess takes longer than timeout seconds, if the exit code of the subprocess is not a member of expected-exit-codes (when expected-exit-codes is not null), or if standard error holds at least one byte when fail-on-stderr? is #t. Otherwise, the result is (void).
The subprogram log will gain either a $subprocess:report if the subprocess ran, or a $subprocess:command-not-found if command was not found.
Standard input is drawn from stdin. If stdin is #f, then no standard input will be available to the subprocess. Otherwise, a new file stream port is opened on the subprocess and all contents from stdin are copied to the subprocess before analyzing the subprocess’ behavior.
Standard output and standard error are both forwarded to (current-output-port) and (current-error-port), respectively.
The controller argument is private. It’s used to mock the effects of subprocesses on program flow for testing purposes. The default value tells run not to mock any operations.
struct
(struct $subprocess $message ())
struct
cmd : string?
struct
(struct $subprocess:report $message ( cmd args max-runtime actual-runtime expected-exit-codes actual-exit-code stderr?)) cmd : path-string? args : (listof (or/c path-string? string-no-nuls? bytes-no-nuls?)) max-runtime : exact-positive-integer? actual-runtime : (>=/c 0) expected-exit-codes : (listof (integer-in 0 255)) actual-exit-code : (integer-in 0 255) stderr? : boolean?
Note that cmd is bound to the path of the command that actually ran, not the path passed to a call to run. If cmd is a relative path, then the path is with respect to the directory in which a package was executing.
max-runtime is bound to the value passed as the timeout argument in run. actual-runtime is the number of seconds the subprocess took to finish, rounded down.
expected-exit-codes is bound to the value passed to the same argument in run. actual-exit-code is the exit code returned from the subprocess.
If the subprocess places one byte on standard error, then stderr? is #t.