Janet 1.8.1-5b6b9f1 Documentation
(Other Versions: 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/readlink os/realpath os/rename os/rm os/rmdir os/setenv os/shell os/sleep os/stat os/symlink os/time os/touch os/which

os/arch cfunction

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


os/cd cfunction
(os/cd path)

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

os/chmod cfunction
(os/chmod path mode)

Change file permissions, where mode is a permission string as returned by os/stat, or an integer. 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. Returns nil.

os/clock cfunction

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

os/cryptorand cfunction
(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.

os/cwd cfunction

Returns the current working directory.

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

Returns the given time as a date struct, or the current time if no time is 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 formated 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

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

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

os/environ cfunction

Get a copy of the os environment table.

os/execute cfunction
(os/execute args &opts 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.

env is a table or struct mapping environment variables to values. Returns the exit status of the program.

os/exit cfunction
(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.

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

Get the string value of an environment variable.

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

Create a symlink from oldpath to newpath, returning nil. The 3rd optional paramater enables a symlink iff truthy, hard link otherwise or if not provided. Does not work on Windows.

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

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

os/mkdir cfunction
(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 create, false if the directoyr already exists, and errors otherwise.

os/mktime cfunction
(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.

os/readlink cfunction
(os/readlink path)

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

os/realpath cfunction
(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.

os/rename cfunction
(os/rename oldname newname)

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

os/rm cfunction
(os/rm path)

Delete a file. Returns nil.

os/rmdir cfunction
(os/rmdir path)

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

os/setenv cfunction
(os/setenv variable value)

Set an environment variable.

os/shell cfunction
(os/shell str)

Pass a command string str directly to the system shell.

os/sleep cfunction
(os/sleep nsec)

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

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

Gets information about a file or directory. Returns a table If the third 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
	:permissions - A unix permission string like "rwx--x--x". On windows, a string like "rwx".
	: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 chnaged (permissions changed)
	:modified - timestamp when file last modified (content changed)

os/symlink cfunction
(os/symlink oldpath newpath)

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

os/time cfunction

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

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

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

os/which cfunction

Check the current operating system. Returns one of:

	:web - Web assembly (emscripten)
	:posix - A POSIX compatible system (default)