Module `Shell`Source

Process handling

Shell scripting in OCaml.

This module contains basic blocks for shell scripting in OCaml. It tends to be safer than just using Unix.system because it handles errors more strictly.

Source

type 'a with_process_flags =
  ?use_extra_path:bool ->
  ?timeout:Core.Time.Span.t option ->
  ?working_dir:string ->
  ?setuid:int ->
  ?setgid:int ->
  ?env:
    [ `Extend of (string * string) list | `Replace of (string * string) list ] ->
  ?verbose:bool ->
  ?echo:bool ->
  ?input:string ->
  ?keep_open:bool ->
  ?tail_len:int ->
  'a

This type is an umbrella type for all the command that dispatch a process. It comes with a list of arguments whose default value can be tweaked by set_defaults.

use_extra_path : if we fail to find the command in the path then we look for it extra_path
timeout : the command will raise Failed if the program doesn't do any IO for this period of time
working_dir : run the command in this directory
verbose : prints the output of the command
echo : print out the command before running it
input : a string to pipe through the program's standard in
env : controls the environment variables passed to the command
preserve_euid : pass the '-p' option to bash when running the command; this should disable the default bash behavior of replacing the effective user ID with the current value of the real user ID, useful in programs where privileges are escalated and de-escalated using seteuid(2)

WARNING: the input argument to this function should not be used because it can deadlock if the input is too big (~160kb?)

Sourcetype 'a with_run_flags = ?expect:int list -> 'a with_process_flags

This is the list of flags for normal process dispatch. It is an extension of with_process_flags.

expect : an int list of valid return codes. default value is [0], if the return code of the dispatched is not in this list we will blowup with Process.Failure

Basic run functions

In all the functions below the command is specified with two arguments. The first one is a string representing the process to run. The second one is the list of arguments to pass.

Although the arguments do not need to be escaped there is still a risk that they might be interpreted as flags when they aren't. Most basic unix utilities provide the ability to pass arguments after "--" to avoid this.

Usage example:

  let patch = run_full ~expect:[0;1] "diff" ["-u";"--";file1;file2]

Sourcetype 'a cmd = string -> string list -> 'a

Sourceval run : unit cmd with_run_flags

Runs a command and discards its output.

Sourceval run_lines : ?eol:char -> string list cmd with_run_flags

Runs a command and returns its output line separated. Note: most commands print a newline at the end of their output so the shell prompt appears on its own line. If the output ends in a newline, it is stripped before splitting the output into a string list to avoid there being a final element in the list containing just the empty string.

In some cases, the newline should not be stripped (e.g., "cat" will not "add" a newline). If you care, use run_full for the entire buffer.

Sourceval run_first_line : ?eol:char -> string option cmd with_run_flags

Returns the first line of the command's output.

This function might terminate the program early the same way that piping through head -n 1 would. When that happens, exit code of the program gets ignored!

Sourceval run_first_line_exn : ?eol:char -> string cmd with_run_flags

Sourceval run_one_line : ?eol:char -> string Core.Or_error.t cmd with_run_flags

Returns the only line of the command's output. If the command prints zero or multiple lines this returns an Error.

If the command exits with non-zero exit code it raises an exception.

Sourceval run_one_line_exn : ?eol:char -> string cmd with_run_flags

Sourceval run_one : ?eol:char -> string option cmd with_run_flags

deprecated [since 2017-11] Use [run_one_line] to get a different behavior or [run_first_line] to get the old behavior

Sourceval run_one_exn : ?eol:char -> string cmd with_run_flags

deprecated [since 2017-11] Use [run_one_line_exn] to get a different behavior or [run_first_line_exn] to get the old behavior

Sourceval run_full : string cmd with_run_flags

Return the full command's output in one string. See the note in run_lines.

Source

val run_fold : 
  ?eol:char ->
  init:'a ->
  f:('a -> string -> 'a * [ `Continue | `Stop ]) ->
  'a cmd with_run_flags

Fold over the lines in the stdout of a process; The `Continue/`Stop argument is there to allow early returning. eol specifies the end of line character used to separate the lines outputted by the the program

Dispatch to /bin/bash

All these function take a format (like printf) and run it through the shell.

Usage example:

  sh "cp -- %s %s" (Filename.quote file1)  (Filename.quote file2)

In general it is recommended to avoid using those too much and to prefer the run* family of function instead because it avoids pitfall like escaping issues and is much more straightforward to think about.

Sourcetype ('a, 'ret) sh_cmd = ('a, unit, string, 'ret) Core.format4 -> 'a

Sourceval sh : ('a, unit) sh_cmd with_run_flags

Sourceval sh_lines : ('a, string list) sh_cmd with_run_flags

Sourceval sh_full : ('a, string) sh_cmd with_run_flags

Sourceval sh_one : ('a, string option) sh_cmd with_run_flags

deprecated [since 2017-11] Use [sh_one_line] to get a different behavior or [sh_first_line] to get the old behavior

Sourceval sh_one_exn : ('a, string) sh_cmd with_run_flags

deprecated [since 2017-11] Use [sh_one_line_exn] to get a different behavior or [sh_first_line_exn] to get the old behavior

Sourceval sh_one_line : ('a, string Core.Or_error.t) sh_cmd with_run_flags

Sourceval sh_one_line_exn : ('a, string) sh_cmd with_run_flags

Sourceval sh_first_line : ('a, string option) sh_cmd with_run_flags

Sourceval sh_first_line_exn : ('a, string) sh_cmd with_run_flags

Sourceval noninteractive_ssh_options : string list

Sourceval noninteractive_no_hostkey_checking_options : string list

Source

type 'a with_ssh_flags =
  ?ssh_options:string list ->
  ?user:string ->
  host:string ->
  'a

Sourceval ssh : ('a, unit) sh_cmd with_run_flags with_ssh_flags

Sourceval ssh_lines : ('a, string list) sh_cmd with_run_flags with_ssh_flags

Sourceval ssh_full : ('a, string) sh_cmd with_run_flags with_ssh_flags

Sourceval ssh_one : ('a, string option) sh_cmd with_run_flags with_ssh_flags

deprecated [since 2017-11] Use [ssh_one_line] to get a different behavior or [ssh_first_line] to get the old behavior

Sourceval ssh_one_exn : ('a, string) sh_cmd with_run_flags with_ssh_flags

deprecated [since 2017-11] Use [ssh_one_line_exn] to get a different behavior or [ssh_first_line_exn] to get the old behavior

Source

val ssh_one_line : 
  ('a, string Core.Or_error.t) sh_cmd with_run_flags with_ssh_flags

Sourceval ssh_one_line_exn : ('a, string) sh_cmd with_run_flags with_ssh_flags

Sourceval ssh_first_line : ('a, string option) sh_cmd with_run_flags with_ssh_flags

Sourceval ssh_first_line_exn : ('a, string) sh_cmd with_run_flags with_ssh_flags

Test dispatches

Usage example:

  if Shell.test "diff" ["-q";"--";file1;file2] then
    Printf.printf "Files %S and %S are the same\n%!" file1 file2;

Source

type 'a with_test_flags =
  ?true_v:int list ->
  ?false_v:int list ->
  'a with_process_flags

This is the list of flags for dispatching processes in test mode. This is used to test the return code of the dispatched program. The return value of these functions will be :

true if the exit code is in true_v.
false if the exit code is in false_v and not in true_v.
Raises Process.Failure otherwise

The default values are:

true_v: default value [0]
false_v: default_value [1]

Sourceval test : bool cmd with_test_flags

Sourceval sh_test : ('a, bool) sh_cmd with_test_flags

Sourceval ssh_test : ('a, bool) sh_cmd with_test_flags with_ssh_flags

Sourceval extra_path : string list Core.ref

variable used by dispatch command to find binaries not in the path. The default values contains only directory which should be in PATH and is only useful in environments where the PATH variable has been blown away.

Sourcemodule Process : sig ... end

Process dispatching

Small helper commands

Sourceval mkdir : ?p:unit -> ?perm:int -> string -> unit

Source

val cp : 
  ?overwrite:bool ->
  ?perm:Core.Unix.file_perm ->
  string ->
  string ->
  unit

Sourceval ln : ?s:unit -> ?f:unit -> string -> string -> unit

Sourceval rm : ?r:unit -> ?f:unit -> string -> unit

Sourceval mv : string -> string -> unit

Raises "Failed_command"

Sourceval whoami : ?real:bool -> unit -> string

Get the username. By default, the effective username. If real is true, get the real username.

Sourceval which : ?use_extra_path:bool -> string -> string option

Source

val scp : 
  ?compress:bool ->
  ?recurse:bool ->
  ?user:string ->
  host:string ->
  string ->
  string ->
  unit

scp user host from to copy local file from to to

Install

Dune Dependency

Authors

Maintainers

Sources

doc/shell/Shell/index.html

Module `Shell`Source

Process handling

Basic run functions

Dispatch to /bin/bash

Test dispatches

Small helper commands

package shell

Install

Dune Dependency

Authors

Maintainers

Sources

doc/shell/Shell/index.html

Module ShellSource

Process handling

Basic run functions

Dispatch to /bin/bash

Test dispatches

Small helper commands

Module `Shell`Source