.. zsh-module-meta::
   :name: zsh/files
   :summary: Some basic file manipulation commands as builtins.

.. index:: single: files, manipulating; Command

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:

.. code-block:: zsh
   :class: example

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

The commands loaded by default are:

.. index:: single: chgrp; Function

``chgrp`` [ ``-hRs`` ] :var:`group` :var:`filename` ...
    
    Changes group of files specified.  This is equivalent to ``chown`` with
    a :var:`user-spec` argument of ``:``:var:`group`.
    

.. index:: single: chmod; Function

``chmod`` [ ``-Rs`` ] :var:`mode` :var:`filename` ...
    
    Changes mode of files specified.
    
    The specified :var:`mode` must be in octal.
    
    The ``-R`` option causes ``chmod`` to recursively descend into directories,
    changing the mode of all files in the directory after
    changing the mode of the directory itself.
    
    The ``-s`` option is a zsh extension to ``chmod`` functionality.  It enables
    paranoid behaviour, intended to avoid security problems involving
    a ``chmod`` being tricked into affecting files other than the ones
    intended.  It will refuse to follow symbolic links, so that (for example)
    ```chmod 600 /tmp/foo/passwd``' can't accidentally chmod ``/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 chmod of
    a deep directory tree can't end up recursively chmoding ``/usr`` as
    a result of directories being moved up the tree.
    

.. index:: single: chown; Function

``chown`` [ ``-hRs`` ] :var:`user-spec` :var:`filename` ...
    
    Changes ownership and group of files specified.
    
    The :var:`user-spec` can be in four forms:
    
    
    :var:`user`
        change owner to :var:`user`; do not change group
    
    :var:`user`\ ``::``
        change owner to :var:`user`; do not change group
    
    :var:`user`\ ``:``
        change owner to :var:`user`; change group to :var:`user`'s primary group
    
    :var:`user`\ ``:``:var:`group`
        change owner to :var:`user`; change group to :var:`group`
    
    ``:``:var:`group`
        do not change owner; change group to :var:`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 :var:`user` and :var:`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)
    ```chown luser /tmp/foo/passwd``' 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.
    

.. index:: single: ln; Function

``ln`` [ ``-dfhins`` ] :var:`filename` :var:`dest`

``ln`` [ ``-dfhins`` ] :var:`filename` ... :var:`dir`
    
    Creates hard (or, with ``-s``, symbolic) links.  In the first form, the
    specified :var:`dest`\ination is created, as a link to the specified
    :var:`filename`.  In the second form, each of the :var:`filename`\s is
    taken in turn, and linked to a pathname in the specified :var:`dir`\ectory
    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.
    

.. index:: single: mkdir; Function

``mkdir`` [ ``-p`` ] [ ``-m`` :var:`mode` ] :var:`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 :manpage:`umask(2)`) is used.
    

.. index:: single: mv; Function

``mv`` [ ``-fi`` ] :var:`filename` :var:`dest`

``mv`` [ ``-fi`` ] :var:`filename` ... :var:`dir`
    
    Moves files.  In the first form, the specified :var:`filename` is moved
    to the specified :var:`dest`\ination.  In the second form, each of the
    :var:`filename`\s is
    taken in turn, and moved to a pathname in the specified :var:`dir`\ectory
    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.
    

.. index:: single: rm; Function

``rm`` [ ``-dfiRrs`` ] :var:`filename` ...
    
    Removes files and directories specified.
    
    Normally, ``rm`` will not remove directories (except with the ``-R`` or ``-r``
    options).  The ``-d`` option causes ``rm`` to try removing directories
    with ``unlink`` (see :manpage:`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`` and ``-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`` and ``-r`` options cause ``rm`` to recursively descend into
    directories, deleting all files in the directory before removing the directory
    with the ``rmdir`` system call (see :manpage:`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)
    ```rm /tmp/foo/passwd``' 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.
    

.. index:: single: rmdir; Function

``rmdir`` :var:`dir` ...
    
    Removes empty directories specified.
    

.. index:: single: sync; Function

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

