# filesystem utils

1.0.0

A collection of utilities for filesystem interaction.

## About Filesystem-Utils

This is an extension library to pathname-utils, to allow dealing with common problems with filesystems, such as listing files, probing file types, determining default directories, etc.

## How To

Since this is a purely utility/toolkit library, simply having a look at the symbol index should give you the best idea of what is offered.

## Also See

- pathname-utils For pathname manipulation functions
- file-attributes For extra information on files available on the filesystem

## System Information

Version: 1.0.0
Dependencies:

- trivial-features
- pathname-utils
- documentation-utils
- sb-posix

Author: Nicolas Hafner
License: zlib
Homepage: https://Shinmera.github.io/filesystem-utils/
Sources: https://github.com/Shinmera/filesystem-utils.git

## Definition Index

- ### ORG.SHIRAKUMO.FILESYSTEM-UTILS

  No documentation provided.
  - EXTERNAL FUNCTION

    #### COPY-FILE

    - FILE
    - TO
    - &KEY
    - REPLACE
    - SKIP-ROOT
    Source

        Copies the file from FILE to TO.

        REPLACE may be one of:
          - NIL       Never replaces the destination, and instead skips it.
          - T         Always replaces the destination.
          - :IF-NEWER Only replaces the destination if the source has a more
                      recent FILE-WRITE-DATE.

        When FILE is a directory, all children are copied to the target. If
        SKIP-ROOT is NIL, then the directory-name of FILE is replicated as the
        root of all contents within TO. Otherwise, the contents of FILE are
        copied directly to TO.

  - EXTERNAL FUNCTION

    #### CREATE-SYMBOLIC-LINK

    - LINK-FILE
    - DESTINATION-FILE
    Source

        Attempts to create a symbolic link file at LINK-FILE, pointing to DESTINATION-FILE.

        This may signal an error for a variety of reasons:
        - The filesystem does not support symbolic links
        - The implementation does not support creating symbolic links
        - The implementation is not permitted to create symbolic links
        - The target filesystem cannot be pointed to

  - EXTERNAL FUNCTION

    #### CURRENT-DIRECTORY

    Source

        Accesses the "current working directory".

        Note that setting this directory is not multithreading safe, as the
        directory is global to the process.

        See WITH-CURRENT-DIRECTORY

  - EXTERNAL FUNCTION

    #### (SETF CURRENT-DIRECTORY)

    - NEW
    Source
    No documentation provided.
  - EXTERNAL FUNCTION

    #### DIRECTORY*

    - DIRECTORY
    - &REST
    - ARGS
    - &KEY
    - &ALLOW-OTHER-KEYS
    Source

        Lists files matching the wild DIRECTORY pathname.

        Like CL:DIRECTORY, but tries *not* to resolve any symlinks of the
        listing, returning direct descendants of the directory root.

  - EXTERNAL FUNCTION

    #### DIRECTORY-P

    - FILE
    Source

        Returns T if the given pathname points to a directory.

        This differs from PATHNAME-UTILS:DIRECTORY-P in the following way:
        If the pathname is not a directory pathname and instead points to a
        file, but the file is actually a directory file, this function still
        returns T.

        See PATHNAME-UTILS:DIRECTORY-P

  - EXTERNAL FUNCTION

    #### ENSURE-DELETED

    - PATHNAME
    Source

        Deletes the given file if it still exists.

        See FILE-EXISTS-P

  - EXTERNAL FUNCTION

    #### FILE-EXISTS-P

    - PATHNAME
    Source

        Returns the truename of the file if it exists.

  - EXTERNAL FUNCTION

    #### FILE-P

    - FILE
    Source

        Returns T if the given pathname points to a regular file.

        This differs from PATHNAME-UTILS:FILE-P in the following way:
        If the pathname is a file pathname, but points to a file that is not a
        regular file (and thus a directory, device, or other type of file
        node), then this function returns NIL.

        See PATHNAME-UTILS:FILE-P

  - EXTERNAL FUNCTION

    #### LIST-CONTENTS

    - DIRECTORY
    Source

        Lists all files and directories within DIRECTORY.

        See DIRECTORY*

  - EXTERNAL FUNCTION

    #### LIST-DEVICES

    - &OPTIONAL
    - HOST
    Source

        Lists all known pathname devices.

        The HOST may be given as a hint for devices to list under the given
        host. The implementation may disregard this hint, however.

        This may return NIL if the implementation cannot enumerate the devices.

  - EXTERNAL FUNCTION

    #### LIST-DIRECTORIES

    - DIRECTORY
    Source

        Lists all directories within DIRECTORY.

        This excludes any files that don't denote directories, and
        specifically returns them as directory pathnames.

        See DIRECTORY*
        See DIRECTORY-P

  - EXTERNAL FUNCTION

    #### LIST-FILES

    - DIRECTORY
    Source

        Lists all files within DIRECTORY.

        This excludes any subdirectories.
        Note that non-regular files are still included in this listing,
        meaning that not all returned files are necessarily FILE-P.

        See DIRECTORY*
        See DIRECTORY-P

  - EXTERNAL FUNCTION

    #### LIST-HOSTS

    Source

        List all known pathname hosts.

        This may return NIL if the implementation cannot enumerate the hosts.

  - EXTERNAL FUNCTION

    #### MAKE-TEMPORARY-FILE

    - &KEY
    - NAME
    - TYPE
    Source

        Create a path to a temporary file.

        If you pass NAME, it is up to you to ensure that the path can be
        re-used if it exists already. Otherwise, the file is guaranteed to not
        exist yet.

        The file will always be in the system's temporary directory.

        See TEMPORARY-DIRECTORY
        See WITH-TEMPORARY-FILE

  - EXTERNAL FUNCTION

    #### RENAME-FILE*

    - FILE
    - TO
    Source

        Renames FILE to TO, overwriting TO if it exists.

        Like RENAME-FILE on most implementations, but ensures the destination
        is overwritten if it exists.

  - EXTERNAL FUNCTION

    #### RESOLVE-SYMBOLIC-LINKS

    - PATHNAME
    Source

        Resolve symbolic links in the pathname as much as possible.

        This does nothing for paths that are not absolute, physical pathnames.
        For absolute, physical pathnames it attempts to resolve all symbolic
        links or relative components in the pathname to arrive at a canonical
        pathname for the file.

  - EXTERNAL FUNCTION

    #### RUNTIME-DIRECTORY

    Source

        Returns the directory the executable was spawned from.

  - EXTERNAL FUNCTION

    #### SYMBOLIC-LINK-P

    - FILE
    Source

        Returns T if the given pathname points to a symbolic link file.

        See FILE-P
        See DIRECTORY-P
        See CREATE-SYMBOLIC-LINK

  - EXTERNAL FUNCTION

    #### TEMPORARY-DIRECTORY

    Source

        Returns the directory for temporary files.

        Note: This makes no guarantee about the "temporary-ness" of the
        files. They may be cleared out after a reboot, after the lisp process
        terminates, or only at the user's discretion. If you crate temporary
        files within this directory, you should delete them after they're no
        longer needed.

        See MAKE-TEMPORARY-FILE

  - EXTERNAL FUNCTION

    #### TRUENAME*

    - PATHNAME
    Source

        Like TRUENAME but ensures that it works on directory files as well on every implementation.

  - EXTERNAL MACRO

    #### WITH-CURRENT-DIRECTORY

    - DIRECTORY
    - &BODY
    - BODY
    Source

        Execute body while the current working directory is changed.

        This guarantees the following invariant: the value of
        CURRENT-DIRECTORY is the same before entering BODY as it is after BODY
        exits for any reason. the value of CURRENT-DIRECTORY is equivalent to
        the passed DIRECTORY when BODY begins execution.

        See CURRENT-DIRECTORY

  - EXTERNAL MACRO

    #### WITH-TEMPORARY-FILE

    - PATH
    - &REST
    - ARGS
    - &BODY
    - BODY
    Source

        Execute BODY with a temporary file pathname bout to PATH.

        ARGS are passed on to MAKE-TEMPORARY-FILE.
        The file is automatically deleted when BODY exits for any reason.

        See MAKE-TEMPORARY-FILE
        See ENSURE-DELETED