Janet 1.17.1-e1c4fc2 Documentation
(Other Versions: 1.16.1 1.15.0 1.13.1 1.12.2 1.11.1 1.10.1 1.9.1 1.8.1 1.7.0 1.6.0 1.5.1 1.5.0 1.4.0 1.3.1 )

OS Module

The os module contains most Operating System specific functionality as well as routines for interacting with the host OS. There is also some functionality for interacting with the file system. The functionality in this module can be much reduced by setting the JANET_REDUCED_OS define in janetconf.h.


os/arch os/cd os/chmod os/clock os/cryptorand os/cwd os/date os/dir os/environ os/execute os/exit os/getenv os/link os/lstat os/mkdir os/mktime os/open os/perm-int os/perm-string os/pipe os/proc-close os/proc-kill os/proc-wait os/readlink os/realpath os/rename os/rm os/rmdir os/setenv os/shell os/sleep os/spawn os/stat os/symlink os/time os/touch os/umask os/which

os/arch cfunction source

Check the ISA that janet was compiled for. Returns one of:

* :x86

* :x86-64

* :arm

* :aarch64

* :sparc

* :wasm

* :unknown
Community Examples

os/cd cfunction source
(os/cd path)

Change current directory to path. Returns nil on success, errors on failure.
Community Examples

os/chmod cfunction source
(os/chmod path mode)

Change file permissions, where mode is a permission string as returned by os/perm-string, or an integer as returned by os/perm-int. When mode is an integer, it is interpreted as a Unix permission value, best specified in octal, like 8r666 or 8r400. Windows will not differentiate between user, group, and other permissions, and thus will combine all of these permissions. Returns nil.
Community Examples

os/clock cfunction source

Return the number of whole + fractional seconds since some fixed point in time. The clock is guaranteed to be non decreasing in real time.
Community Examples

os/cryptorand cfunction source
(os/cryptorand n &opt buf)

Get or append n bytes of good quality random data provided by the OS. Returns a new buffer or buf.
Community Examples

os/cwd cfunction source

Returns the current working directory.
Community Examples

os/date cfunction source
(os/date &opt time local)

Returns the given time as a date struct, or the current time if `time` is not given. Returns a struct with following key values. Note that all numbers are 0-indexed. Date is given in UTC unless `local` is truthy, in which case the date is formatted for the local timezone.

* :seconds - number of seconds [0-61]

* :minutes - number of minutes [0-59]

* :hours - number of hours [0-23]

* :month-day - day of month [0-30]

* :month - month of year [0, 11]

* :year - years since year 0 (e.g. 2019)

* :week-day - day of the week [0-6]

* :year-day - day of the year [0-365]

* :dst - if Day Light Savings is in effect
Community Examples

os/dir cfunction source
(os/dir dir &opt array)

Iterate over files and subdirectories in a directory. Returns an array of paths parts, with only the file name or directory name and no prefix.
Community Examples

os/environ cfunction source

Get a copy of the os environment table.
Community Examples

os/execute cfunction source
(os/execute args &opt flags env)

Execute a program on the system and pass it string arguments. `flags` is a keyword that modifies how the program will execute.
* :e - enables passing an environment to the program. Without :e, the current environment is inherited.
* :p - allows searching the current PATH for the binary to execute. Without this flag, binaries must use absolute paths.
* :x - raise error if exit code is non-zero.
* :d - Don't try and terminate the process on garbage collection (allow spawning zombies).
`env` is a table or struct mapping environment variables to values. It can also contain the keys :in, :out, and :err, which allow redirecting stdio in the subprocess. These arguments should be core/file values. One can also pass in the :pipe keyword for these arguments to create files that will read (for :err and :out) or write (for :in) to the file descriptor of the subprocess. This is only useful in `os/spawn`, which takes the same parameters as `os/execute`, but will return an object that contains references to these files via (return-value :in), (return-value :out), and (return-value :err). Returns the exit status of the program.
Community Examples

os/exit cfunction source
(os/exit &opt x)

Exit from janet with an exit code equal to x. If x is not an integer, the exit with status equal the hash of x.
Community Examples

os/getenv cfunction source
(os/getenv variable &opt dflt)

Get the string value of an environment variable.
Community Examples

os/link cfunction source
(os/link oldpath newpath &opt symlink)

Create a link at newpath that points to oldpath and returns nil. Iff symlink is truthy, creates a symlink. Iff symlink is falsey or not provided, creates a hard link. Does not work on Windows.
Community Examples

os/lstat cfunction source
(os/lstat path &opt tab|key)

Like os/stat, but don't follow symlinks.
Community Examples

os/mkdir cfunction source
(os/mkdir path)

Create a new directory. The path will be relative to the current directory if relative, otherwise it will be an absolute path. Returns true if the directory was created, false if the directory already exists, and errors otherwise.
Community Examples

os/mktime cfunction source
(os/mktime date-struct &opt local)

Get the broken down date-struct time expressed as the number of seconds since January 1, 1970, the Unix epoch. Returns a real number. Date is given in UTC unless local is truthy, in which case the date is computed for the local timezone.

Inverse function to os/date.
Community Examples

os/open cfunction source
(os/open path &opt flags mode)

Create a stream from a file, like the POSIX open system call. Returns a new stream. mode should be a file mode as passed to os/chmod, but only if the create flag is given. The default mode is 8r666. Allowed flags are as follows:

 * :r - open this file for reading
 * :w - open this file for writing
 * :c - create a new file (O_CREATE)
 * :e - fail if the file exists (O_EXCL)
 * :t - shorten an existing file to length 0 (O_TRUNC)

Posix only flags:

 * :a - append to a file (O_APPEND)
 * :x - O_SYNC
 * :C - O_NOCTTY

Windows only flags:

 * :R - share reads (FILE_SHARE_READ)
 * :W - share writes (FILE_SHARE_WRITE)
  * :D - share deletes (FILE_SHARE_DELETE)
Community Examples

os/perm-int cfunction source
(os/perm-int bytes)

Parse a 9 character permission string and return an integer that can be used by chmod.
Community Examples

os/perm-string cfunction source
(os/perm-string int)

Convert a Unix octal permission value from a permission integer as returned by os/stat to a human readable string, that follows the formatting of unix tools like ls. Returns the string as a 9 character string of r, w, x and - characters. Does not include the file/directory/symlink character as rendered by `ls`.
Community Examples

os/pipe cfunction source

Create a readable stream and a writable stream that are connected. Returns a two element tuple where the first element is a readable stream and the second element is the writable stream.
Community Examples

os/proc-close cfunction source
(os/proc-close proc)

Wait on a process if it has not been waited on, and close pipes created by `os/spawn` if they have not been closed. Returns nil.
Community Examples

os/proc-kill cfunction source
(os/proc-kill proc &opt wait)

Kill a subprocess by sending SIGKILL to it on posix systems, or by closing the process handle on windows. If wait is truthy, will wait for the process to finsih and returns the exit code. Otherwise, returns proc.
Community Examples

os/proc-wait cfunction source
(os/proc-wait proc)

Block until the subprocess completes. Returns the subprocess return code.
Community Examples

os/readlink cfunction source
(os/readlink path)

Read the contents of a symbolic link. Does not work on Windows.
Community Examples

os/realpath cfunction source
(os/realpath path)

Get the absolute path for a given path, following ../, ./, and symlinks. Returns an absolute path as a string. Will raise an error on Windows.
Community Examples

os/rename cfunction source
(os/rename oldname newname)

Rename a file on disk to a new path. Returns nil.
Community Examples

os/rm cfunction source
(os/rm path)

Delete a file. Returns nil.
Community Examples

os/rmdir cfunction source
(os/rmdir path)

Delete a directory. The directory must be empty to succeed.
Community Examples

os/setenv cfunction source
(os/setenv variable value)

Set an environment variable.
Community Examples

os/shell cfunction source
(os/shell str)

Pass a command string str directly to the system shell.
Community Examples

os/sleep cfunction source
(os/sleep n)

Suspend the program for n seconds. 'nsec' can be a real number. Returns nil.
Community Examples

os/spawn cfunction source
(os/spawn args &opt flags env)

Execute a program on the system and return a handle to the process. Otherwise, the same arguments as os/execute. Does not wait for the process.
Community Examples

os/stat cfunction source
(os/stat path &opt tab|key)

Gets information about a file or directory. Returns a table if the second argument is a keyword, returns only that information from stat. If the file or directory does not exist, returns nil. The keys are:

* :dev - the device that the file is on

* :mode - the type of file, one of :file, :directory, :block, :character, :fifo, :socket, :link, or :other

* :int-permissions - A Unix permission integer like 8r744

* :permissions - A Unix permission string like "rwxr--r--"

* :uid - File uid

* :gid - File gid

* :nlink - number of links to file

* :rdev - Real device of file. 0 on windows.

* :size - size of file in bytes

* :blocks - number of blocks in file. 0 on windows

* :blocksize - size of blocks in file. 0 on windows

* :accessed - timestamp when file last accessed

* :changed - timestamp when file last changed (permissions changed)

* :modified - timestamp when file last modified (content changed)
Community Examples

os/symlink cfunction source
(os/symlink oldpath newpath)

Create a symlink from oldpath to newpath, returning nil. Same as (os/link oldpath newpath true).
Community Examples

os/time cfunction source

Get the current time expressed as the number of whole seconds since January 1, 1970, the Unix epoch. Returns a real number.
Community Examples

os/touch cfunction source
(os/touch path &opt actime modtime)

Update the access time and modification times for a file. By default, sets times to the current time.
Community Examples

os/umask cfunction source
(os/umask mask)

Set a new umask, returns the old umask.
Community Examples

os/which cfunction source

Check the current operating system. Returns one of:

* :windows

* :macos

* :web - Web assembly (emscripten)

* :linux

* :freebsd

* :openbsd

* :netbsd

* :posix - A POSIX compatible system (default)

May also return a custom keyword specified at build time.
Community Examples