# 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:
```text
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:
```text
[]
```
where `` may be a combination of
- **u**: user
- **g**: group
- **o**: other/non-group
- **a**: all
`` may be a combination of
- **r**: read
- **w**: write
- **x**: execute
- **X**: special execute
- **s**: setuid/gid on execution
- **t**: sticky
and `` 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,
```text
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
```javascript
var umask = require( '@stdlib/process/umask' );
```
#### umask( \[mask,] \[options] )
Returns the process mask.
```javascript
var mask = umask();
// returns
```
To set the process mask, provide a `mask` argument. When provided a `mask`, the function returns the previous mask value.
```javascript
var mask = umask();
// returns
var prev = umask( 0 );
// returns
var bool = ( prev === mask );
// returns true
```
The `mask` argument may be either an integer value or a `string` representing the mask using symbolic notation.
```javascript
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`.
```javascript
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.
```javascript
umask( parseInt( '0777', 8 ) );
```
- See [umask(2)][umask].
## Examples
```javascript
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
```text
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
```bash
$ umask
```
To print the mask in command format, set the `-p` flag.
```bash
$ umask -p
```
[umask]: http://man7.org/linux/man-pages/man2/umask.2.html