(html (head (title "sph-lib (sph process create)") (link (@ (rel "stylesheet") (type "text/css") (href "/css/sph.css"))) (meta (@ (name "viewport") (content "width=device-width,initial-scale=1"))) #f) (body () (div (@ (class top)) (nav (a (@ (href "/")) "start") ", " (a (@ (href "/feed.xml")) "feed")) "") (div (@ (class "middle")) (div (@ (class mtime) (title "last modification time of the current page")) "2023-04-05") (section (h1 "(sph process create)") (div (p "create child processes and process chains") (p "part of " (a (@ (href "../../sph-lib.html")) "sph-lib")) (#f (section (@ (class "library-name")) (h1 "module name") (p "(sph process create)")) (section (@ (class "library-exports")) (h1 "exported bindings") (div (div (@ (class "doc-bindings")) (div (@ (id "doc-b-" "execute-with-pipes") (class "doc-b")) (div (span (@ (class "type")) "procedure") ": " (span (@ (class "name")) "execute-with-pipes") " " (span (@ (class "first-sig")) "proc path arguments #:search-path? [input? output? error?] ->")) (div (@ (class "rest-sig")) (div "procedure:{port ... -> any} string list boolean boolean boolean -> any:proc-result integer:exit-status")) (div (@ (class "description")) (("executes a program and calls proc with pipes to or from the standard streams depending on if input/output/error are true." (br) "path is a filesystem path to an executable." (br) "you might have to close ports for proc to return." (br) "pipe ports are closed when proc returns." (br) "example:" (br) "(execute-with-pipes (l (input error) #t) \\\"/usr/bin/echo\\\" (list \\\"test\\\") #t #f #t)")))) (div (@ (id "doc-b-" "process-chain") (class "doc-b")) (div (span (@ (class "type")) "procedure") ": " (span (@ (class "name")) "process-chain") " " (span (@ (class "first-sig")) "first-input last-output execute-arguments #:search-path? ->")) (div (@ (class "rest-sig")) (div "port/any port/any (string/(string:executable string:argument ...) ...) -> (integer:pid ...)")) (div (@ (class "description")) (("creates a new process for each execute-argument and sets standard input and output of the processes in a chaining manner:" (br) "input is the first-input or the input from the previous process, the output is the output to the next process or the last-output." (br) "error port for each process is the current-error-port of the process calling process-chain pipes." (br) "if any process could not be created then all previously created processed are sent SIGTERM and the result is an empty list." (br) "tip: if you want to call procedures in between you could start guile processes or use pipe-chain, create the processes yourself and threads for guile code")))) (div (@ (id "doc-b-" "process-chain->string") (class "doc-b")) (div (span (@ (class "type")) "procedure") ": " (span (@ (class "name")) "process-chain->string") " " (span (@ (class "first-sig")) "first-input process-chain-arguments ... ->")) (div (@ (class "rest-sig")) (div "false/port any ... -> string")) "") (div (@ (id "doc-b-" "process-chain-finish") (class "doc-b")) (div (span (@ (class "type")) "procedure") ": " (span (@ (class "name")) "process-chain-finish") " " (span (@ (class "first-sig")) "process-chain-result ->")) (div (@ (class "rest-sig")) (div "false/(integer:pid ...) -> integer")) (div (@ (class "description")) (("wait for the termination of the processes and return the exit status")))) (div (@ (id "doc-b-" "process-chain-finish-success?") (class "doc-b")) (div (span (@ (class "type")) "procedure") ": " (span (@ (class "name")) "process-chain-finish-success?") " " (span (@ (class "first-sig")) "process-chain-result ->")) (div (@ (class "rest-sig")) (div "false/(integer:pid ...) -> boolean")) (div (@ (class "description")) (("wait for the termination of the processes and check if its exit status is 0")))) (div (@ (id "doc-b-" "process-chain-path-pipe") (class "doc-b")) (div (span (@ (class "type")) "procedure") ": " (span (@ (class "name")) "process-chain-path-pipe") " " (span (@ (class "first-sig")) "first-input last-output config #:search-path? ->")) (div (@ (class "rest-sig")) (div "port/string/any port/string/any (#(symbol symbol string/(string:executable string ...)/procedure:{false/string false/string -> string/(string:executable string ...)}) ...) -> (integer:pid ...)") (div "first-input last-output (#(port/path/nothing port/path/nothing path/(path argument ...)/procedure:{path-in path-out -> execute-arguments} ...) ...) -> (integer:pid ...)")) (div (@ (class "description")) (("like process-chain but uses path-pipe-chain internally and so allows automatically created paths (named pipes) between processes." (br) "example:" (br) "(path-pipe-process-chain #f (current-output-port)" (br) "  (list" (br) "    (vector (q nothing) (q port) (list \\\"echo\\\" \\\"test\\\"))" (br) "    (vector (q path) (q path) (l (in out) (\\\"program\\\" \\\"--from\\\" in \\\"--to\\\" out)))))" (br) "expected result:" (br) "assuming that \\\"program\\\" reads from file in and writes to file out, \\\"test\\\" should appear on the current output port")))) (div (@ (id "doc-b-" "process-create") (class "doc-b")) (div (span (@ (class "type")) "procedure") ": " (span (@ (class "name")) "process-create") " " (span (@ (class "first-sig")) "executable #:env #:keep-descriptors #:search-path? #:path-open-flags [arguments input-port output-port error-port] ->")) (div (@ (class "rest-sig")) (div "string:path/file-name [(string ...) port/string/integer/false ... #:key (env (environ)) (keep-descriptors (list)) search-path? (path-open-flags integer)] -> process-id")) (div (@ (class "description")) (("\\\"executable\\\" is the path or file name (if search-path? is true) of a file to execute to become the new process." (br) "if the given string for \\\"executable\\\" does not start with a slash and search-path? is true (default is false for security), it is searched in the directories in the PATH environment variable." (br) "the optional parameters are to set the standard streams." (br) "with the key parameters the environment variables for the new process can be set in the format (environ) returns." (br) "no file descriptors from the parent process are transferred to the child except if listed in keep-descriptors or given using the input/output/error-port parameters." (br) "when a string is given as port argument, it is interpreted as a filesystem path and #:path-open-flags can be used to add to O_WRONLY|O_CREAT." (br) "returns the process id of the newly created child process or false if the process could not be created")))) (div (@ (id "doc-b-" "sph-process-create-description") (class "doc-b")) (div (span (@ (class "type")) "variable") ": " (span (@ (class "name")) "sph-process-create-description")) "" "")))))))) ()))