4.6.3 Executing a file

The POSIX functions in the family exec* execute a file and replace the current Vicare process with the new process; when these functions are successful: they do not return.

NOTE For a clean subprocess execution: before executing the command we must call close-ports-in-close-on-exec-mode. All the exec* functions below perform this call automatically.

Function: execv filename argv

Interface to the C function execv(), (libc)execv. filename must be the pathname of an executable file; argv must be a list of strings representing command line arguments. Execute the command; if the function returns: an error has occurred, an exception is raised.

Example that runs ls:

(import (vicare)
  (prefix (vicare posix) px.))

(px.execv "/bin/ls" '("ls" "-l"))

Function: execve filename argv env

Interface to the C function execve(), (libc)execve. filename must be the pathname of an executable file; argv must be a list of strings representing command line arguments; env must be a list of strings representing environment variables assignments. Execute the command; if the function returns: an error has occurred, an exception is raised.

Example that runs sh:

(import (vicare)
  (prefix (vicare posix) px.))

(px.execve "/bin/sh" '("sh" "-c" "echo A is $A") '("A=1"))

Function: execvp filename argv

Interface to the C function execvp(), (libc)execvp. filename must be the pathname of an executable file reachable in the current PATH; argv must be a list of strings representing command line arguments. Execute the command; if the function returns: an error has occurred, an exception is raised.

Example that runs ls:

(import (vicare)
  (prefix (vicare posix) px.))

(px.execvp "ls" '("ls" "-l"))

Function: execl filename arg0 arg ...

Like execv but allows the arguments to be given explicitly. Example that runs ls:

(import (vicare)
  (prefix (vicare posix) px.))

(px.execl "/bin/ls" "ls" "-l")

Function: execle filename argv0 arg … env

Like execve but allows the arguments to be given explicitly. Example that runs sh:

(import (vicare)
  (prefix (vicare posix) px.))

(px.execle "/bin/sh" "sh" "-c" "echo A is $A" '("A=123"))

Function: execlp filename arg0 arg ...

Like execvp but allows the arguments to be given explicitly. Example that runs ls:

(import (vicare)
  (prefix (vicare posix) px.))

(px.execlp "ls" "ls" "-l")

Finding executable files

Function: find-executable-as-bytevector bv-pathname

Function: find-executable-as-string str-pathname

Given an absolute or relative file pathname or just the name of a file, search the file system for a matching executable file; when found return its absolute pathname as bytevector or Scheme string, else return #f. If an error occurs while inspecting the file system: raise an exception.

bv-pathname must be a bytevector, str-pathname must be a string.

#!vicare
(import (vicare)
  (prefix (vicare posix) px.))

(px.find-executable-as-string "/usr/local/bin/vicare")
⇒ "/usr/local/bin/vicare"

(px.find-executable-as-string "vicare")
⇒ "/usr/local/bin/vicare"

(px.find-executable-as-string "this-cannot-exist")
⇒ #f

(px.find-executable-as-string "ls")
⇒ "/usr/bin/ls"

Function: vicare-executable-as-bytevector

Function: vicare-executable-as-string

Acquire the return value of vicare-argv0 and search the file system for a matching executable file; when found return its absolute pathname as bytevector or Scheme string, else return #f. If an error occurs while inspecting the file system: raise an exception.

Upon starting a Vicare process:

• If the executable vicare is specified as pathname relative to the current working directory: these functions will return the wrong absolute path when the current working directory is changed before a call to them.
• If the executable vicare is specified as file name with no directory part: these functions may return the wrong absolute path when the environment variable PATH is changed before a call to them.

For these reasons: these functions are both invoked upon loading the library (vicare posix) and they cache the result internally. Beware to neither change the current working directory nor change the PATH before loading (vicare posix).