Namespace: joker.os

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms

Summary

Provides a platform-independent interface to operating system functionality.

Index

• SIGABRT
• SIGALRM
• SIGFPE
• SIGHUP
• SIGILL
• SIGINT
• SIGKILL
• SIGPIPE
• SIGQUIT
• SIGSEGV
• SIGTERM
• SIGTRAP
• args
• chdir
• chmod
• chown
• chtimes
• clearenv
• close
• create
• create-temp
• cwd
• egid
• env
• euid
• exec
• executable
• exists?
• exit
• expand-env
• get-env
• gid
• groups
• hostname
• kill
• lchown
• link
• ls
• lstat
• mkdir
• mkdir-all
• mkdir-temp
• open
• pagesize
• path-separator?
• pid
• ppid
• read-link
• remove
• remove-all
• rename
• set-env
• sh
• sh-from
• signal
• start
• stat
• symlink
• temp-dir
• truncate
• uid
• unset-env
• user-cache-dir
• user-config-dir
• user-home-dir

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

• SIGABRT

  Int v1.0.1

  SIGABRT

• SIGALRM

  Int v1.0.1

  SIGALRM

• SIGFPE

  Int v1.0.1

  SIGFPE

• SIGHUP

  Int v1.0.1

  SIGHUP

• SIGILL

  Int v1.0.1

  SIGILL

• SIGINT

  Int v1.0.1

  SIGINT

• SIGKILL

  Int v1.0.1

  SIGKILL

• SIGPIPE

  Int v1.0.1

  SIGPIPE

• SIGQUIT

  Int v1.0.1

  SIGQUIT

• SIGSEGV

  Int v1.0.1

  SIGSEGV

• SIGTERM

  Int v1.0.1

  SIGTERM

• SIGTRAP

  Int v1.0.1

  SIGTRAP

Variables

(None.)

Functions, Macros, and Special Forms

• args

  Function v1.0

  (args)
  

  Returns a sequence of the command line arguments, starting with the program name (normally, joker).

• chdir

  Function v1.0

  (chdir dirname)
  

  Changes the current working directory to the named directory.

• chmod

  Function v1.0

  (chmod name mode)
  

  Changes the mode of the named file to mode. If the file is a symbolic link, it changes the mode of the link's target.

• chown

  Function v1.0

  (chown name uid gid)
  

  Changes the numeric uid and gid of the named file. If the file is a symbolic link,
  it changes the uid and gid of the link's target. A uid or gid of -1 means to not change that value.

• chtimes

  Function v1.0

  (chtimes name atime mtime)
  

  Changes the access and modification times of the named file, similar to the Unix utime() or utimes() functions.

• clearenv

  Function v1.0

  (clearenv)
  

  Deletes all environment variables.

• close

  Function v1.0

  (close f)
  

  Closes the file, rendering it unusable for I/O.

• create

  Function v1.0

  (create name)
  

  Creates the named file with mode 0666 (before umask), truncating it if it already exists.

• create-temp

  Function v1.0

  (create-temp dir pattern)
  

  Creates a new temporary file in the directory dir, opens the file for reading and writing,
  and returns the resulting File. The filename is generated by taking pattern and adding a
  random string to the end. If pattern includes a "*", the random string replaces the last "*".
  If dir is the empty string, uses the default directory for temporary files (see joker.os/temp-dir).
  Multiple programs calling joker.os/make-temp-file simultaneously will not choose the same file.
  The caller can use (name f) to find the pathname of the file.
  It is the caller's responsibility to remove the file when no longer needed.

• cwd

  Function v1.0

  (cwd)
  

  Returns a rooted path name corresponding to the current directory. If the current directory can
  be reached via multiple paths (due to symbolic links), cwd may return any one of them.

• egid

  Function v1.0

  (egid)
  

  Returns the numeric effective group id of the caller.

• env

  Function v1.0

  (env)
  

  Returns a map representing the environment.

• euid

  Function v1.0

  (euid)
  

  Returns the numeric effective user id of the caller.

• exec

  Function v1.0

  (exec name opts)
  

  Executes the named program with the given arguments. opts is a map with the following keys (all optional):
  :args - vector of arguments (all arguments must be strings),
  :dir - if specified, working directory will be set to this value before executing the program,
  :stdin - if specified, provides stdin for the program. Can be either a string or an IOReader.
  If it's a string, the string's content will serve as stdin for the program. IOReader can be, for example,
  *in* (in which case Joker's stdin will be redirected to the program's stdin) or the value returned by (joker.os/open).
  :stdout - if specified, must be an IOWriter. It can be, for example, *out* (in which case the program's stdout will be redirected
  to Joker's stdout) or the value returned by (joker.os/create).
  :stderr - the same as :stdout, but for stderr.
  Returns a map with the following keys:
  :success - whether or not the execution was successful,
  :err-msg (present iff :success if false) - string capturing error object returned by Go runtime
  :exit - exit code of program (or attempt to execute it),
  :out - string capturing stdout of the program (unless :stdout option was passed)
  :err - string capturing stderr of the program (unless :stderr option was passed).

• executable

  Function v1.0

  (executable)
  

  Returns the path name for the executable that started the current process.

• exists?

  Function v1.0

  (exists? path)
  

  Returns true if file or directory with the given path exists. Otherwise returns false.

• exit

  Function v1.0

  (exit code)
  (exit)
  

  Causes the current program to exit with the given status code (defaults to 0).

• expand-env

  Function v1.0

  (expand-env s)
  

  Replaces ${var} or $var in the string according to the values of the current environment variables.
  References to undefined variables are replaced by the empty string.

• get-env

  Function v1.0

  (get-env key)
  

  Returns the value of the environment variable named by the key or nil if the variable is not present in the environment.

• gid

  Function v1.0

  (gid)
  

  Returns the numeric group id of the caller.

• groups

  Function v1.0

  (groups)
  

  Returns a list of the numeric ids of groups that the caller belongs to.

• hostname

  Function v1.0

  (hostname)
  

  Returns the host name reported by the kernel.

• kill

  Function v1.0.1

  (kill pid)
  

  Causes the process with the given PID to exit immediately.
  Only kills the process itself, not any other processes it may have started.

• lchown

  Function v1.0

  (lchown name uid gid)
  

  Changes the numeric uid and gid of the named file. If the file is a symbolic link,
  it changes the uid and gid of the link itself.

• link

  Function v1.0

  (link oldname newname)
  

  Creates newname as a hard link to the oldname file.

• ls

  Function v1.0

  (ls dirname)
  

  Reads the directory named by dirname and returns a list of directory entries sorted by filename.
  Each entry is a map with the following keys:
  :name - name (String)
  :size - size in bytes (Int)
  :mode - mode (Int)
  :dir? - true if the file is a directory (Boolean)
  :modtime - modification time (unix timestamp) (Int)

• lstat

  Function v1.0

  (lstat filename)
  

  Like stat, but if the file is a symbolic link, the result describes the symbolic link.

• mkdir

  Function v1.0

  (mkdir name perm)
  

  Creates a new directory with the specified name and permission bits.

• mkdir-all

  Function v1.0

  (mkdir-all name perm)
  

  Creates a directory named path, along with any necessary parents, and returns nil, or else throws an error.
  The permission bits perm (before umask) are used for all directories that mkdir-all creates.
  If path is already a directory, mkdir-all does nothing and returns nil.

• mkdir-temp

  Function v1.0

  (mkdir-temp dir pattern)
  

  Creates a new temporary directory in the directory dir.
  The directory name is generated by taking pattern and applying a random string to the end.
  If pattern includes a "*", the random string replaces the last "*".
  Returns the name of the new directory. If dir is the empty string,
  uses the default directory for temporary files (see joker.os/temp-dir).
  Multiple programs calling joker.os/mkdir-temp simultaneously will not choose the same directory.
  It is the caller's responsibility to remove the directory when no longer needed.

• open

  Function v1.0

  (open name)
  

  Opens the named file for reading. If successful, the file can be used for reading;
  the associated file descriptor has mode O_RDONLY.

• pagesize

  Function v1.0

  (pagesize)
  

  Returns the underlying system's memory page size.

• path-separator?

  Function v1.0

  (path-separator? c)
  

  Reports whether c is a directory separator character.

• pid

  Function v1.0

  (pid)
  

  Returns the process id of the caller.

• ppid

  Function v1.0

  (ppid)
  

  Returns the process id of the caller's parent.

• read-link

  Function v1.0

  (read-link name)
  

  Returns the destination of the named symbolic link.

• remove

  Function v1.0

  (remove name)
  

  Removes the named file or (empty) directory.

• remove-all

  Function v1.0

  (remove-all path)
  

  Removes path and any children it contains.
  
  It removes everything it can, then panics with the first error (if
  any) it encountered.

• rename

  Function v1.0

  (rename oldpath newpath)
  

  Renames (moves) oldpath to newpath. If newpath already exists and is not a directory, rename replaces it.

• set-env

  Function v1.0

  (set-env key value)
  

  Sets the value of the environment variable named by the key.

• sh

  Function v1.0

  (sh name & arguments)
  

  Executes the named program with the given arguments. Returns a map with the following keys:
  :success - whether or not the execution was successful,
  :err-msg (present iff :success if false) - string capturing error object returned by Go runtime
  :exit - exit code of program (or attempt to execute it),
  :out - string capturing stdout of the program,
  :err - string capturing stderr of the program.

• sh-from

  Function v1.0

  (sh-from dir name & arguments)
  

  Executes the named program with the given arguments and working directory set to dir.
  Returns a map with the following keys:
  :success - whether or not the execution was successful,
  :err-msg (present iff :success if false) - string capturing error object returned by Go runtime
  :exit - exit code of program (or attempt to execute it),
  :out - string capturing stdout of the program,
  :err - string capturing stderr of the program.

• signal

  Function v1.0.1

  (signal pid signal)
  

  Sends signal to the process with the given PID.

• start

  Function v1.0.1

  (start name opts)
  

  Starts a new process with the program specified by name.
  opts is a map with the same keys as in exec.
  Doesn't wait for the process to finish.
  Returns the process's PID.

• stat

  Function v1.0

  (stat filename)
  

  Returns a map describing the named file. The info map has the following attributes:
  :name - base name of the file
  :size - length in bytes for regular files; system-dependent for others
  :mode - file mode bits
  :modtime - modification time
  :dir? - true if file is a directory

• symlink

  Function v1.0

  (symlink oldname newname)
  

  Creates newname as a symbolic link to oldname.

• temp-dir

  Function v1.0

  (temp-dir)
  

  Returns the default directory to use for temporary files.
  On Unix systems, it returns $TMPDIR if non-empty, else /tmp.
  On Windows, it uses GetTempPath, returning the first non-empty
  value from %TMP%, %TEMP%, %USERPROFILE%, or the Windows directory.
  The directory is neither guaranteed to exist nor have accessible permissions.

• truncate

  Function v1.0

  (truncate name size)
  

  Changes the size of the named file. If the file is a symbolic link, it changes the size of the link's target.

• uid

  Function v1.0

  (uid)
  

  Returns the numeric user id of the caller.

• unset-env

  Function v1.0

  (unset-env key)
  

  Unsets a single environment variable.

• user-cache-dir

  Function v1.0

  (user-cache-dir)
  

  Returns the default root directory to use for user-specific cached data.
  Users should create their own application-specific subdirectory within this one and use that.
  
  On Unix systems, it returns $XDG_CACHE_HOME as specified by https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
  if non-empty, else $HOME/.cache. On Darwin, it returns $HOME/Library/Caches. On Windows, it returns %LocalAppData%.
  On Plan 9, it returns $home/lib/cache.
  
  If the location cannot be determined (for example, $HOME is not defined), then it will throw an error.

• user-config-dir

  Function v1.0

  (user-config-dir)
  

  Returns the default root directory to use for user-specific configuration data.
  Users should create their own application-specific subdirectory within this one and use that.
  
  On Unix systems, it returns $XDG_CONFIG_HOME as specified by https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
  if non-empty, else $HOME/.config. On Darwin, it returns $HOME/Library/Application Support. On Windows, it returns %AppData%.
  On Plan 9, it returns $home/lib.
  
  If the location cannot be determined (for example, $HOME is not defined), then it will throw an error.

• user-home-dir

  Function v1.0

  (user-home-dir)
  

  Returns the current user's home directory.
  
  On Unix, including macOS, it returns the $HOME environment variable. On Windows, it returns %USERPROFILE%.
  On Plan 9, it returns the $home environment variable.