CCUnix (containers.containers.unix.CCUnix)

High-level Functions on top of Unix

Some useful functions built on top of Unix.

status: unstable

since 0.10

Sourcetype 'a or_error = ('a, string) Stdlib.result

Sourcetype 'a gen = unit -> 'a option

Calling Commands

Sourceval escape_str : string -> string

Escape a string so it can be a shell argument.

Source

type call_result =
  < stdout : string
  ; stderr : string
  ; status : Unix.process_status
  ; errcode : int >

Source

val call_full : 
  ?bufsize:int ->
  ?stdin:[ `Gen of string gen | `Str of string ] ->
  ?env:string array ->
  ('a, Stdlib.Buffer.t, unit, call_result) Stdlib.format4 ->
  'a

call_full cmd wraps the result of Unix.open_process_full cmd into an object. It reads the full stdout and stderr of the subprocess before returning. cmd can be a format string as in Printf.

parameter stdin
if provided, the generator or string is consumed and fed to the subprocess input channel, which is then closed.

parameter bufsize
buffer size used to read stdout and stderr.

parameter env
environment to run the command in.

Example:

  # CCUnix.call_full "ls %s" (CCUnix.escape_str "/");;

Source

val call : 
  ?bufsize:int ->
  ?stdin:[ `Gen of string gen | `Str of string ] ->
  ?env:string array ->
  ('a, Stdlib.Buffer.t, unit, string * string * int) Stdlib.format4 ->
  'a

call cmd is similar to call_full but returns a tuple stdout, stderr, errcode instead of an object.

Source

val call_stdout : 
  ?bufsize:int ->
  ?stdin:[ `Gen of string gen | `Str of string ] ->
  ?env:string array ->
  ('a, Stdlib.Buffer.t, unit, string) Stdlib.format4 ->
  'a

Sourcetype line = string

Source

type async_call_result =
  < stdout : line gen
  ; stderr : line gen
  ; stdin : line -> unit
  ; close_in : unit
  ; close_err : unit
  ; close_out : unit
  ; close_all : unit
  ; wait : Unix.process_status
  ; wait_errcode : int >

A subprocess for interactive usage (read/write channels line by line)

since 0.11

Source

val async_call : 
  ?env:string array ->
  ('a, Stdlib.Buffer.t, unit, async_call_result) Stdlib.format4 ->
  'a

Spawns a subprocess, like call, but the subprocess's channels are line generators and line sinks (for stdin). If p is async_call "cmd", then p#wait waits for the subprocess to die. Channels can be closed independently.

since 0.11

Accessors

since 0.11

Sourceval stdout : < stdout : 'a.. > -> 'a

Sourceval stderr : < stderr : 'a.. > -> 'a

Sourceval status : < status : 'a.. > -> 'a

Sourceval errcode : < errcode : 'a.. > -> 'a

Simple IO

Source

val with_in : 
  ?mode:int ->
  ?flags:Unix.open_flag list ->
  string ->
  f:(Stdlib.in_channel -> 'a) ->
  'a

Open an input file with the given optional flag list, calls the function on the input channel. When the function raises or returns, the channel is closed.

parameter flags
opening flags. Unix.O_RDONLY is used in any cases.

since 0.16

Source

val with_out : 
  ?mode:int ->
  ?flags:Unix.open_flag list ->
  string ->
  f:(Stdlib.out_channel -> 'a) ->
  'a

Same as with_in but for an output channel.

parameter flags
opening flags (default [Unix.O_CREAT; Unix.O_TRUNC]) Unix.O_WRONLY is used in any cases.

since 0.16

Subprocesses

Sourceval with_process_in : string -> f:(Stdlib.in_channel -> 'a) -> 'a

Open a shell command in a subprocess and obtain a handle to its stdout.

  CCUnix.with_process_in "ls /tmp" ~f:CCIO.read_lines_l;;

since 0.16

Sourceval with_process_out : string -> f:(Stdlib.out_channel -> 'a) -> 'a

Open a shell command in a subprocess and obtain a handle to its stdin.

since 0.16

Source

type process_full =
  < stdin : Stdlib.out_channel
  ; stdout : Stdlib.in_channel
  ; stderr : Stdlib.in_channel
  ; close : Unix.process_status >

Handle to a subprocess.

since 0.16

Source

val with_process_full : 
  ?env:string array ->
  string ->
  f:(process_full -> 'a) ->
  'a

Open a subprocess and obtain a handle to its channels.

parameter env
environment to pass to the subprocess.

since 0.16

Sourceval ensure_session_leader : unit -> unit

On unix, call Unix.setsid() to make sure subprocesses die at the same time as the current process. Does nothing on windows. Idempotent: it can be called several times but will only have effects, if any, the first time.

since 2.8

Networking

Source

val with_connection : 
  Unix.sockaddr ->
  f:(Stdlib.in_channel -> Stdlib.out_channel -> 'a) ->
  'a

Wrap Unix.open_connection with a handler.

since 0.16

Sourceexception ExitServer

Source

val establish_server : 
  Unix.sockaddr ->
  f:(Stdlib.in_channel -> Stdlib.out_channel -> _) ->
  unit

Listen on the address and calls the handler in a blocking fashion. Using Thread is recommended if handlers might take time. The callback should raise ExitServer to stop the loop.

since 0.16

File lock

Sourceval with_file_lock : kind:[ `Read | `Write ] -> string -> (unit -> 'a) -> 'a

with_file_lock ~kind filename f puts a lock on the offset 0 of the file named filename, calls f and returns its result after the file is unlocked. If f () raises an exception the exception is re-raised after the file is unlocked.

parameter kind
specifies whether the lock is read-only or read-write.

since 1.2

Infix Functions

Sourcemodule Infix : sig ... end

include module type of Infix

Sourceval (?|) : ('a, Stdlib.Buffer.t, unit, call_result) Stdlib.format4 -> 'a

Infix version of call.

since 0.11

Sourceval (?|&) : ('a, Stdlib.Buffer.t, unit, async_call_result) Stdlib.format4 -> 'a

Infix version of async_call.

since 0.11

Temporary directory

Sourceval with_temp_dir : ?mode:int -> ?dir:string -> string -> (string -> 'a) -> 'a

Create a temporary directory, call the function, and then destroy the directory afterwards. Usage with_temp_dir pattern f.

parameter pattern
the naming pattern for the temporary directory. Helps avoiding collisions.

parameter mode
mode for the directory

parameter dir
the directory under which to make a temporary directory (default /tmp)

Note that this is implemented following the discussion at: https://discuss.ocaml.org/t/how-to-create-a-temporary-directory-in-ocaml/1815/

since 2.8