os

This module exposes low level operating system facilities / syscalls.

Functions

os.abort()

Aborts the execution of the process and forces a core dump.

See also

abort(3)

os.chdir(path)

Changes the current working directory of the calling process to the directory specified in path.

See also

chdir(2)

os.cloexec(fd, set)

Sets or clears the O_CLOEXEC flag on the given fd. Since version 0.3.0 all fds are created with O_CLOEXEC set.

os.close(fd)

Close the given file descriptor.

See also

close(2)

os.dup(oldfd)

Duplicates the given file descriptor, returning the lowest available one.

See also

dup(2)

Note

Since version 0.3.0 the fds are created with O_CLOEXEC set. You can undo this using os.cloexec().

os.dup2(oldfd, newfd[, cloexec])

Duplicates oldfd into newfd, setting the O_CLOEXEC flag if indicated. It defaults to true;

See also

dup2(2)

os.execv(path[, args])
os.execvp(file[, args])
os.execve(path[, args][, envp])
os.execvpe(file[, args][, envp])

The exec* family of functions replace the current process image with a new process image.

Arguments:
  • file – file or path indicate file to be used for the new process image. The functions which contain a p in their name will search for the file in the PATH environment variable, or in the current directory in its absence.
  • args – Arguments for the program. If an Array is passed, the first element should be the program filename.
  • envp – Object containing the environment for the new program. The functions which do not take ab environment object will inherit it from their parent process.

See also

execve(3)

os.exit([status])

Ends the process with the specified status. It defaults to 0.

See also

exit(3)

Note

At the moment no clean shutdown is performed.

os._exit(status)

Terminate the calling process “immediately”.

See also

_exit(2)

os.fork()

Creates a new process duplicating the calling process. See os.waitpid() for how to wait for the child process.

See also

fork(2)

os.fstat(fd)

Same as os.stat() but for an already opened file descriptor.

See also

fstat(2)

os.getegid()

Returns the effective group ID of the calling process.

See also

getegid(2)

os.geteuid()

Returns the effective user ID of the calling process.

See also

geteuid(2)

os.getgid()

Returns the real group ID of the calling process.

See also

getgid(2)

os.getgroups()

Returns the supplementary group IDs of the calling process.

See also

getgroups(2)

os:getpid()

Returns the process id of the calling process.

See also

getpid(2)

os:getppid()

Returns the process id of the parent of the calling process.

See also

getppid(2)

os.getuid()

Returns the real user ID of the calling process.

See also

getuid(2)

os.isatty(fd)

Returns true if the given fd refers to a valid terminal type device, false otherwise.

See also

isatty(3)

os.nonblock(fd, set)

Sets or clears the O_NONBLOCK flag on the given fd.

os.open(path, flags, mode)

Opens a file.

Arguments:
  • path – The file path to be opened.
  • flags –

    How the file will be opened. It can be a string or an OR-ed mask of constants (listed below). Here are the supported possibilities:

    • ’r’ = O_RDONLY: open the file just for reading
    • ’r+’ = O_RDWR: open the file for reading and writing
    • ’w’ = O_TRUNC | O_CREAT | O_WRONLY: open the file for writing only, truncating it if it exists and creating it otherwise
    • ’wx’ = O_TRUNC | O_CREAT | O_WRONLY | O_EXCL: like ‘w’, but fails if the path exists
    • ’w+’ = O_TRUNC | O_CREAT | O_RDWR: open the file for reading and writing, truncating it if it exists and creating it otherwise
    • ’wx+’ = O_TRUNC | O_CREAT | O_RDWR | O_EXCL: like ‘w+’ but fails if the path exists
    • ’a’ = O_APPEND | O_CREAT | O_WRONLY: open the file for apending, creating it if it doesn’t exist
    • ’ax’ = O_APPEND | O_CREAT | O_WRONLY | O_EXCL: like ‘a’ but fails if the path exists
    • ’a+’ = O_APPEND | O_CREAT | O_RDWR: open the file for reading and apending, creating it if it doesn’t exist
    • ’ax+’ = O_APPEND | O_CREAT | O_RDWR | O_EXCL: like ‘a+’ but fails if the path exists
  • mode – Sets the file mode (permissions and sticky bits).
Returns:

The opened file descriptor.

See also

open(2)

Note

Since version 0.3.0 the fds are created with O_CLOEXEC set. You can undo this using os.cloexec().

os.pipe()

Creates a pipe (an object that allows unidirectional data flow) and allocates a pair of file descriptors. The first descriptor connects to the read end of the pipe; the second connects to the write end. File descriptors are returned in an array: [read_fd, write_fd].

See also

pipe(2)

Note

Since version 0.3.0 the fds are created with O_CLOEXEC set. You can undo this using os.cloexec().

os.read([nread])

Read data from the file descriptor.

Arguments:
  • nread – Amount of data to receive. If not specified it defaults to 4096. Alternatively, a Buffer can be passed, and data will be read into it.
Returns:

The data that was read as a Uint8Array or the amount of data read as a number, if a Buffer was passed.

See also

read(2)

os.scandir(path)

Lists all files in the given path.

See also

scandir(3)

os.setgid(gid)

Sets the effective group ID of the calling process.

See also

setgid(2)

os.setgroups(groups)

Sets the supplementary group IDs for the calling process.

See also

setgroups(2)

os.setuid(uid)

Sets the effective user ID of the calling process.

See also

setuid(2)

os.setsid()

Create a new session if the calling process is not a process group leader.

See also

setsid(2)

os.stat(path)

Obtain information about the file pointed to by path.

Returns an object with the following properties:

  • dev
  • mode
  • nlink
  • uid
  • gid
  • rdev
  • ino
  • size
  • blksize
  • blocks
  • flags
  • gen
  • atime
  • mtime
  • ctime
  • birthtime

The atime, mtime, ctime and birthtime fields are of type Date.

See also

stat(2)

os.ttyname(fd)

Returns the related device name of the given fd for which os.isatty() is true.

See also

ttyname(3)

Unlinks (usually this means completely removing) the given path.

See also

unlink(3)

os.urandom(bytes)

Get bytes from the system CSPRNG. This is implemented by reading from /dev/urandom. On Linux systems supporting the getrandom(2) syscall that one is used, and in OSX arc4random_buf(3).

bytes can be an integer or a Buffer object. If it’s an integer a Buffer will be returned of the specified size. If it’s already a Buffer, if will be filled.

os.waitpid(pid[, options])

Wait for state changes in a child of the calling process. The return value is an object with pid and status properties. The os.W* family of functions can be used to get more information about the status.

See also

waitpid(2)

os.write(data)

Write data on the file descriptor.

Arguments:
  • data – The data that will be written (can be a string or a Buffer).
Returns:

The number of bytes from data which were actually written.

See also

write(2)

os.S_IMODE(mode)

Returns the permissions bits out of the mode field obtained with os.stat().

os.S_ISDIR(mode)

Returns true if the mode of the file indicates it’s a directory.

os.S_ISCHR(mode)

Returns true if the mode of the file indicates it’s a character device.

os.S_ISBLK(mode)

Returns true if the mode of the file indicates it’s a block device.

os.S_ISREG(mode)

Returns true if the mode of the file indicates it’s a regular file.

os.S_ISFIFO(mode)

Returns true if the mode of the file indicates it’s a FIFO.

Returns true if the mode of the file indicates it’s a symbolic link.

os.S_ISSOCK(mode)

Returns true if the mode of the file indicates it’s a socket.

os.WIFEXITED(status)
os.WEXITSTATUS(status)
os.WIFSIGNALED(status)
os.WTERMSIG(status)
os.WIFSTOPPED(status)
os.WSTOPSIG(status)
os.WIFCONTINUED(status)

Helper functions to get status information from a child process. See the man page: waitpid(2).

Constants

os.O_*

Constants used as flags in os.open().

os.S_IF*

Flags used to check the file type in os.stat().

os.S_I*

Flags for file mode used in os.stat().

os.W*

Flags used in the options field on os.waitpid().

os.STD{IN,OUT,ERR}_FILENO

Constants represendint default file descriptors for stdio.