libs/vfork/README

   1 vfork-exec-wrapper
   2 ==================
   3
   4 A tiny tool that redirects stdio file-descriptors and executes a program.
   5
   6 Motivation
   7 ----------
   8
   9 Ardour can start external helper applications for various purposes
  10 (e.g. video-server, video-monitor, plugin-scanner, post-export scripts,...)
  11 and has the need to bidirectionally communicate with the external app.
  12
  13 On POSIX platforms (OSX, GNU/Linux, BSD,..) launching an external app is a
  14 combination of fork() and execve(2). The problem with that is that fork(2)
  15 duplicates the complete page-table (incl. allocated locked memory, and
  16 file-descriptors) which -  even if fork(2) is done from a non-realtime
  17 thread - may cause audio I/O glitches or worse out-of-memory errors if
  18 the mlock(2) limit is reached.
  19
  20 vfork(2) on the other hand "is a special case of clone(2). It is used to
  21 create new processes without copying the page tables of the parent process.
  22 It may be useful in performance-sensitive applications where a child is
  23 created which then immediately issues an execve(2)." [vfork man page].
  24
  25 The problem with vfork(2) is that file-descriptors are not cloned, which
  26 makes bi-directional communication impossible without additional work.
  27 This is exactly what this vfork-exec-wrapper does: It takes a list of
  28 file-descriptors, re-directs them to stdio and calls execve(2) again.
  29
  30 This code was previously in pbd/system_exec.cc (done after fork(2),
  31 which become a NOOP with vfork(2)).
  32
  33 Usage
  34 -----
  35
  36 ardour-exec-wrapper <file-des> <mode> <nice> <command> [args]
  37
  38 ardour-exec-wrapper takes three pairs of file-descriptors, stderr mode,
  39 nice-level followed by the command to execute and optional arguments.
  40
  41 The first set FDs is used to communicate failure back to the parent process.
  42 They are closed if execve(2) succeeds. The following two FDs are stdin and
  43 stdout. The mode specifies handling of stderr: 0: keep stderr, 1: close and
  44 ignore, 2: merge stderr into stdout.