time-to-botec/js/node_modules/@stdlib/process/umask/README.md
NunoSempere b6addc7f05 feat: add the node modules
Necessary in order to clearly see the squiggle hotwiring.
2022-12-03 12:44:49 +00:00

6.3 KiB

umask

Get/set the process mask.

A mask is a set of bits, each of which restricts how its corresponding permission is set for newly created files. On POSIX platforms, each file has a set of attributes that control who can read, write, or execute that file. Upon creating a file, file permissions must be set to an initial setting. The process mask restricts those permission settings.

If the mask contains a bit set to 1, the corresponding initial file permission is disabled. If the mask contains a bit set to 0, the corresponding permission is left to be determined by the requesting process and the system. The process mask is thus a filter that removes permissions as a file is created; i.e., each bit set to a 1 removes its corresponding permission.

In octal representation, a mask is a four digit number comprised as follows (using 0077 as an example):

  • 0: special permissions (setuid, setgid, sticky bit)
  • 0: (u)ser/owner permissions
  • 7: (g)roup permissions
  • 7: (o)thers/non-group permissions

Octal codes correspond to the following permissions:

  • 0: read, write, execute
  • 1: read, write
  • 2: read, execute
  • 3: read
  • 4: write, execute
  • 5: write
  • 6: execute
  • 7: no permissions

If provided fewer than four digits, the mask is left-padded with zeros. Note, however, that only the last three digits (i.e., the file permissions digits) of the mask are actually used when the mask is applied (i.e., mask & 0777).

Permissions can be represented using the following symbolic form:

u=rwx,g=rwx,o=rwx

where

  • u: user permissions
  • g: group permissions
  • o: other/non-group permissions
  • r: read
  • w: write
  • x: execute

When setting permissions using symbolic notation, one may use a mask expression of the form:

[<classes>]<operator><symbols>

where <classes> may be a combination of

  • u: user
  • g: group
  • o: other/non-group
  • a: all

<symbols> may be a combination of

  • r: read
  • w: write
  • x: execute
  • X: special execute
  • s: setuid/gid on execution
  • t: sticky

and <operator> may be one of

  • +: enable
  • -: disable
  • =: enable specified and disable unspecified permissions

For example,

  • u-w: disable user write permissions
  • u+w: enable user write permissions
  • u=w: enable user write permissions and disable user read and execute

To specify multiple changes, one can specify a comma-separated list of mask expressions. For example,

u+rwx,g-x,o=r

would enable user read, write, and execute permissions, disable group execute permissions, enable other read permissions, and disable other write and execute permissions.

The a class indicates "all", which is the same as specifying ugo. This is the default class if a class is omitted when specifying permissions. For example, +x is equivalent to a+x which is equivalent to ugo+x which is equivalent to u+x,g+x,o+x and enables execution for all classes.

Usage

var umask = require( '@stdlib/process/umask' );

umask( [mask,] [options] )

Returns the process mask.

var mask = umask();
// returns <number>

To set the process mask, provide a mask argument. When provided a mask, the function returns the previous mask value.

var mask = umask();
// returns <number>

var prev = umask( 0 );
// returns <number>

var bool = ( prev === mask );
// returns true

The mask argument may be either an integer value or a string representing the mask using symbolic notation.

var mask = umask( 'u=rwx,g=rw,o=rw' );

The function accepts the following options:

  • symbolic: boolean indicating whether to return the mask in symbolic notation. Default: false.

To return the process mask in symbolic notation, set the symbolic option to true.

var opts = {
    'symbolic': true
};

// Get the mask:
var mask = umask( opts );
// e.g., returns 'u=rwx,g=rw,o=rw'

// Set the mask:
mask = umask( 0, opts );
// e.g., returns 'u=rwx,g=rw,o=rw'

Notes

  • To set the process mask using an octal string (e.g., 0777), use parseInt to convert the string to an integer value.

    umask( parseInt( '0777', 8 ) );
    
  • See umask(2).

Examples

var lpad = require( '@stdlib/string/left-pad' );
var umask = require( '@stdlib/process/umask' );

var mask;
var opts;

// Print the process mask as an integer:
mask = umask();
console.log( mask.toString() );

// Print the process mask as an octal string:
console.log( lpad( mask.toString(), 4, '0' ) );

// Print the process mask using symbolic notation:
opts = {
    'symbolic': true
};
console.log( umask( opts ) );

CLI

Usage

Usage: umask [options]

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
  -p,    --print               Print the mask command.
  -S,    --symbolic            Print the mask using symbolic notation.

Examples

$ umask

To print the mask in command format, set the -p flag.

$ umask -p