zsh: The zsh/files Module

Next: The zsh/langinfo Module, Previous: The zsh/example Module, Up: Zsh Modules [Contents][Index]

### 22.14 The zsh/files Module

The `zsh/files` module makes available some common commands for file manipulation as builtins; these commands are probably not needed for many normal situations but can be useful in emergency recovery situations with constrained resources. The commands do not implement all features now required by relevant standards committees.

For all commands, a variant beginning `zf_` is also available and loaded automatically. Using the features capability of zmodload will let you load only those names you want. Note that it’s possible to load only the builtins with zsh-specific names using the following command:

    zmodload -m -F zsh/files b:zf_\*

The commands loaded by default are:

`chgrp` [ `-hRs` ] group filename ...

  Changes group of files specified. This is equivalent to `chown` with a user-spec argument of ‘`:`group’.

`chown` [ `-hRs` ] user-spec filename ...

  Changes ownership and group of files specified.

  The user-spec can be in four forms:

  user

    change owner to user; do not change group

  user`::`

    change owner to user; do not change group

  user`:`

    change owner to user; change group to user’s primary group

  user`:`group

    change owner to user; change group to group

  `:`group

    do not change owner; change group to group

  In each case, the ‘`:`’ may instead be a ‘`.`’. The rule is that if there is a ‘`:`’ then the separator is ‘`:`’, otherwise if there is a ‘`.`’ then the separator is ‘`.`’, otherwise there is no separator.

  Each of user and group may be either a username (or group name, as appropriate) or a decimal user ID (group ID). Interpretation as a name takes precedence, if there is an all-numeric username (or group name).

  If the target is a symbolic link, the `-h` option causes `chown` to set the ownership of the link instead of its target.

  The `-R` option causes `chown` to recursively descend into directories, changing the ownership of all files in the directory after changing the ownership of the directory itself.

  The `-s` option is a zsh extension to `chown` functionality. It enables paranoid behaviour, intended to avoid security problems involving a `chown` being tricked into affecting files other than the ones intended. It will refuse to follow symbolic links, so that (for example) {No value for ‘dsbq’}`chown luser /tmp/foo/passwd`{No value for ‘dsq’} can’t accidentally chown `/etc/passwd` if `/tmp/foo` happens to be a link to `/etc`. It will also check where it is after leaving directories, so that a recursive chown of a deep directory tree can’t end up recursively chowning `/usr` as a result of directories being moved up the tree.

`ln` [ `-dfhins` ] filename dest
`ln` [ `-dfhins` ] filename ... dir

  Creates hard (or, with `-s`, symbolic) links. In the first form, the specified destination is created, as a link to the specified filename. In the second form, each of the filenames is taken in turn, and linked to a pathname in the specified directory that has the same last pathname component.

  Normally, `ln` will not attempt to create hard links to directories. This check can be overridden using the `-d` option. Typically only the super-user can actually succeed in creating hard links to directories. This does not apply to symbolic links in any case.

  By default, existing files cannot be replaced by links. The `-i` option causes the user to be queried about replacing existing files. The `-f` option causes existing files to be silently deleted, without querying. `-f` takes precedence.

  The `-h` and `-n` options are identical and both exist for compatibility; either one indicates that if the target is a symlink then it should not be dereferenced. Typically this is used in combination with `-sf` so that if an existing link points to a directory then it will be removed, instead of followed. If this option is used with multiple filenames and the target is a symbolic link pointing to a directory then the result is an error.

`mkdir` [ `-p` ] [ `-m` mode ] dir ...

  Creates directories. With the `-p` option, non-existing parent directories are first created if necessary, and there will be no complaint if the directory already exists. The `-m` option can be used to specify (in octal) a set of file permissions for the created directories, otherwise mode 777 modified by the current `umask` (see man page umask(2)) is used.

`mv` [ `-fi` ] filename dest
`mv` [ `-fi` ] filename ... dir

  Moves files. In the first form, the specified filename is moved to the specified destination. In the second form, each of the filenames is taken in turn, and moved to a pathname in the specified directory that has the same last pathname component.

  By default, the user will be queried before replacing any file that the user cannot write to, but writable files will be silently removed. The `-i` option causes the user to be queried about replacing any existing files. The `-f` option causes any existing files to be silently deleted, without querying. `-f` takes precedence.

  Note that this `mv` will not move files across devices. Historical versions of `mv`, when actual renaming is impossible, fall back on copying and removing files; if this behaviour is desired, use `cp` and `rm` manually. This may change in a future version.

`rm` [ `-dfirs` ] filename ...

  Removes files and directories specified.

  Normally, `rm` will not remove directories (except with the `-r` option). The `-d` option causes `rm` to try removing directories with `unlink` (see man page unlink(2)), the same method used for files. Typically only the super-user can actually succeed in unlinking directories in this way. `-d` takes precedence over `-r`.

  By default, the user will be queried before removing any file that the user cannot write to, but writable files will be silently removed. The `-i` option causes the user to be queried about removing any files. The `-f` option causes files to be silently deleted, without querying, and suppresses all error indications. `-f` takes precedence.

  The `-r` option causes `rm` to recursively descend into directories, deleting all files in the directory before removing the directory with the `rmdir` system call (see man page rmdir(2)).

  The `-s` option is a zsh extension to `rm` functionality. It enables paranoid behaviour, intended to avoid common security problems involving a root-run `rm` being tricked into removing files other than the ones intended. It will refuse to follow symbolic links, so that (for example) {No value for ‘dsbq’}`rm /tmp/foo/passwd`{No value for ‘dsq’} can’t accidentally remove `/etc/passwd` if `/tmp/foo` happens to be a link to `/etc`. It will also check where it is after leaving directories, so that a recursive removal of a deep directory tree can’t end up recursively removing `/usr` as a result of directories being moved up the tree.

`rmdir` dir ...

  Removes empty directories specified.

`sync`

  Calls the system call of the same name (see man page sync(2)), which flushes dirty buffers to disk. It might return before the I/O has actually been completed.

Next: The zsh/langinfo Module, Previous: The zsh/example Module, Up: Zsh Modules [Contents][Index]