Module CCUnix

High-level Functions on top of Unix

Some useful functions built on top of Unix.

status: unstable

since
0.10
type 'a or_error = ('a, string) Result.result
type 'a gen = unit -> 'a option

Calling Commands

val escape_str : string -> string

Escape a string so it can be a shell argument.

type call_result = < stdout : string; stderr : string; status : Unix.process_status; errcode : int; >
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.

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.

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 cmd but returns a tuple stdout, stderr, errcode instead of an object.

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
type line = string
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
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
val stdout : < stdout : 'a; .. > -> 'a
val stderr : < stderr : 'a; .. > -> 'a
val status : < status : 'a; .. > -> 'a
val errcode : < errcode : 'a; .. > -> 'a

Simple IO

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
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
val with_process_in : string -> f:(Stdlib.in_channel -> 'a) -> 'a

Open a subprocess and obtain a handle to its stdout.

CCUnix.with_process_in "ls /tmp" ~f:CCIO.read_lines_l;;
since
0.16
val with_process_out : string -> f:(Stdlib.out_channel -> 'a) -> 'a

Open a subprocess and obtain a handle to its stdin.

since
0.16
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
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
val with_connection : Unix.sockaddr -> f:(Stdlib.in_channel -> Stdlib.out_channel -> 'a) -> 'a

Wrap Unix.open_connection with a handler.

since
0.16
exception ExitServer
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
val 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

module Infix : sig ... end
include module type of Infix
val (?|) : ('a, Stdlib.Buffer.t, unit, call_result) Stdlib.format4 -> 'a

Infix version of call.

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

Infix version of async_call.

since
0.11