On this page:
ALL_  OS_  SYMS
os-sym
run
$subprocess
$subprocess:  command-not-found
$subprocess:  report
8.0

26 System

 (require xiden/system) package: xiden

xiden/system extends and reprovides racket/system. It specializes process management in the context of packages.

A manually maintained list of every known value returned from (system-type 'os).

syntax-class

os-sym

A syntax class that matches members of ALL_OS_SYMS.

procedure

(run [#:expected-exit-codes expected-exit-codes    
  #:timeout timeout    
  #:stdin stdin    
  #:fail-on-stderr? fail-on-stderr?    
  #:controller controller    
  #:cwd wd]    
  command    
  arguments ...)  logged?
  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?)
Returns a logged procedure P called for its effect.

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.

Xiden prohibits execution of any file that the user does not trust.

P will search for an executable with the name bound to command. It starts by checking (file-exists? command). If a file does not exist, then P will use find-executable-path.

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 program 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.

A message pertaining to a subprocess.

A subprocess could not start because the cmd was not found on the system.

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?
A message about a subprocess started using cmd and args.

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.