System.Directory

Copyright	(c) The University of Glasgow 2001
License	BSD-style (see the file libraries/base/LICENSE)
Maintainer	libraries@haskell.org
Stability	stable
Portability	portable
Safe Haskell	Trustworthy
Language	Haskell2010

Каталог содержит ряд записей, каждая из которых является именованной ссылкой на объект файловой системы (файл, каталог и т. д.). Некоторые записи могут быть скрытыми, недоступными или иметь некоторую административную функцию (например, . или `..' в POSIX http://www.opengroup.org/onlinepubs/009695399/), но в этом стандарте все такие записи считаются частью содержимого каталога. Записи во вложенных каталогах, однако, не считаются частью содержимого каталога.

Каждая объект файловой системы указывается с помощью пути. Обычно существует как минимум один абсолютный путь к каждому объекту файловой системы. В некоторых операционных системах также могут быть пути, которые являются относительными к текущему каталогу.

Действия с каталогами

createDirectory :: FilePath -> IO () Source

createDirectory dir создаёт новый каталог dir, который изначально пуст, или максимально приближен к пустому, насколько это позволяет операционная система.

Операция может завершиться ошибкой:

• isPermissionError / PermissionDenied Процесс не имеет достаточных прав для выполнения операции. [EROFS, EACCES]
• isAlreadyExistsError / AlreadyExists Операнд ссылается на каталог, который уже существует. [EEXIST]
• HardwareFault Произошла ошибка физического ввода-вывода. [EIO]
• InvalidArgument Операнд не является допустимым именем каталога. [ENAMETOOLONG, ELOOP]
• NoSuchThing Отсутствует путь к каталогу. [ENOENT, ENOTDIR]
• ResourceExhausted Недостаточно ресурсов (виртуальная память, дескрипторы файлов процесса, физическое пространство на диске и т. д.) для выполнения операции. [EDQUOT, ENOSPC, ENOMEM, EMLINK]
• InappropriateType Путь ссылается на существующий объект, который не является каталогом. [EEXIST]

createDirectoryIfMissing Source

createDirectoryIfMissing parents dir создаёт новый каталог dir, если он не существует. Если первый аргумент равен True, функция также создаст все родительские каталоги, если они отсутствуют.

removeDirectory :: FilePath -> IO () Source

removeDirectory dir удаляет существующий каталог dir. Реализация может указывать дополнительные ограничения, которые должны быть выполнены, прежде чем каталог может быть удалён (например, каталог должен быть пустым или не может использоваться другими процессами). Недопустимо для реализации частично удалять каталог, если не удаляется весь каталог. Соответствующая реализация не обязана поддерживать удаление каталогов во всех ситуациях (например, удаление корневого каталога).

Операция может завершиться ошибкой:

• HardwareFault Произошла ошибка физического ввода-вывода. [EIO]
• InvalidArgument Операнд не является допустимым именем каталога. [ENAMETOOLONG, ELOOP]
• isDoesNotExistError / NoSuchThing Каталог не существует. [ENOENT, ENOTDIR]
• isPermissionError / PermissionDenied Процесс не имеет достаточных прав для выполнения операции. [EROFS, EACCES, EPERM]
• UnsatisfiedConstraints Не выполнены зависящие от реализации ограничения. [EBUSY, ENOTEMPTY, EEXIST]
• UnsupportedOperation Реализация не поддерживает удаление в этой ситуации. [EINVAL]
• InappropriateType Операнд ссылается на существующий объект, который не является каталогом. [ENOTDIR]

removeDirectoryRecursive :: FilePath -> IO () Source

removeDirectoryRecursive dir удаляет существующий каталог dir вместе с его содержимым и подкаталогами. Символические ссылки удаляются без влияния на их цели.

renameDirectory :: FilePath -> FilePath -> IO () Source

renameDirectory old new изменяет имя существующего каталога с old на new. Если каталог new уже существует, он атомарно заменяется каталогом old. Если каталог new не является каталогом old и не является его псевдонимом, он удаляется как с помощью removeDirectory. Соответствующая реализация не обязана поддерживать переименование каталогов во всех ситуациях (например, переименование в существующий каталог или на разные физические устройства), но ограничения должны быть задокументированы.

На платформах Win32, renameDirectory завершается ошибкой, если каталог new уже существует.

Операция может завершиться ошибкой:

• HardwareFault Произошла ошибка физического ввода-вывода. [EIO]
• InvalidArgument Один из операндов не является допустимым именем каталога. [ENAMETOOLONG, ELOOP]
• isDoesNotExistError / NoSuchThing Исходный каталог не существует, или отсутствует путь к цели. [ENOENT, ENOTDIR]
• isPermissionError / PermissionDenied Процесс не имеет достаточных прав для выполнения операции. [EROFS, EACCES, EPERM]
• ResourceExhausted Недостаточно ресурсов для выполнения операции. [EDQUOT, ENOSPC, ENOMEM, EMLINK]
• UnsatisfiedConstraints Не выполнены зависящие от реализации ограничения. [EBUSY, ENOTEMPTY, EEXIST]
• UnsupportedOperation Реализация не поддерживает переименование в этой ситуации. [EINVAL, EXDEV]
• InappropriateType Один из путей ссылается на существующий объект, который не является каталогом. [ENOTDIR, EISDIR]

getDirectoryContents :: FilePath -> IO [FilePath] Source

getDirectoryContents dir возвращает список всех записей в dir.

Операция может завершиться ошибкой:

• HardwareFault Произошла ошибка физического ввода-вывода. [EIO]
• InvalidArgument Операнд не является допустимым именем каталога. [ENAMETOOLONG, ELOOP]
• isDoesNotExistError / NoSuchThing Каталог не существует. [ENOENT, ENOTDIR]
• isPermissionError / PermissionDenied Процесс не имеет достаточных прав для выполнения операции. [EACCES]
• ResourceExhausted Недостаточно ресурсов для выполнения операции. [EMFILE, ENFILE]
• InappropriateType Путь ссылается на существующий объект, который не является каталогом. [ENOTDIR]

getCurrentDirectory :: IO FilePath Source

Если операционная система имеет понятие текущих каталогов, getCurrentDirectory возвращает абсолютный путь к текущему каталогу вызывающего процесса.

Операция может завершиться ошибкой:

• HardwareFault Произошла ошибка физического ввода-вывода. [EIO]
• isDoesNotExistError / NoSuchThing Отсутствует путь, ссылающийся на текущий каталог. [EPERM, ENOENT, ESTALE...]
• isPermissionError / PermissionDenied Процесс не имеет достаточных прав для выполнения операции. [EACCES]
• ResourceExhausted Недостаточно ресурсов для выполнения операции.
• UnsupportedOperation Операционная система не имеет понятия текущего каталога.

Обратите внимание, что в многопоточной программе текущий каталог является глобальным состоянием, общим для всех потоков процесса. При использовании операций файловой системы из нескольких потоков, поэтому настоятельно рекомендуется использовать абсолютные, а не относительные FilePaths.

setCurrentDirectory :: FilePath -> IO () Source

Если операционная система имеет понятие текущих каталогов, setCurrentDirectory dir изменяет текущий каталог вызывающего процесса на dir.

Операция может завершиться ошибкой:

• HardwareFault Произошла физическая ошибка ввода-вывода. [EIO]
• InvalidArgument Операнд не является допустимым именем каталога. [ENAMETOOLONG, ELOOP]
• isDoesNotExistError / NoSuchThing Каталог не существует. [ENOENT, ENOTDIR]
• isPermissionError / PermissionDenied У процесса недостаточно привилегий для выполнения операции. [EACCES]
• UnsupportedOperation Операционная система не имеет понятия о текущем каталоге или текущий каталог не может быть динамически изменён.
• InappropriateType Путь ссылается на существующий объект, который не является каталогом. [ENOTDIR]

Обратите внимание, что в многопоточном приложении текущий каталог является глобальным состоянием, разделяемым между всеми потоками процесса. Поэтому при использовании операций с файловой системой из нескольких потоков рекомендуется использовать абсолютные, а не относительные FilePath.

Предопределённые каталоги

getHomeDirectory :: IO FilePath Source

Возвращает домашний каталог текущего пользователя.

Ожидается, что возвращаемый каталог будет доступен для записи текущим пользователем, но обратите внимание, что хранение прикладных данных в нём — не лучшая практика; используйте getAppUserDataDirectory вместо этого.

В Unix, getHomeDirectory возвращает значение переменной среды HOME. В Windows, система запрашивает подходящий путь; типичный путь может быть C:/Documents And Settings/user.

Операция может завершиться ошибкой:

• UnsupportedOperation Операционная система не имеет понятия о домашнем каталоге.
• isDoesNotExistError Домашний каталог текущего пользователя не существует или не может быть найден.

getAppUserDataDirectory :: String -> IO FilePath Source

Возвращает путь к каталогу, в котором могут храниться данные, специфичные для приложения и текущего пользователя. Результат getAppUserDataDirectory для данного приложения специфичен для текущего пользователя.

Аргумент должен быть именем приложения, которое будет использовано для построения пути (избегайте использования необычных символов, которые могут привести к недопустимому имени пути).

Примечание: каталог может не существовать и его может потребоваться создать. Ожидается, что родительский каталог существует и доступен для записи.

В Unix, эта функция возвращает $HOME/.appName. В Windows, типичный путь может быть

C:/Users/user/AppData/Roaming/appName

Операция может завершиться ошибкой:

• UnsupportedOperation Операционная система не имеет понятия о каталоге данных приложения.
• isDoesNotExistError Домашний каталог текущего пользователя не существует или не может быть найден.

getUserDocumentsDirectory :: IO FilePath Source

Возвращает каталог документов текущего пользователя.

Ожидается, что возвращаемый каталог будет доступен для записи текущим пользователем, но обратите внимание, что хранение прикладных данных в нём — не лучшая практика; используйте getAppUserDataDirectory вместо этого.

В Unix, getUserDocumentsDirectory возвращает значение переменной среды HOME. В Windows, система запрашивает подходящий путь; типичный путь может быть C:/Documents And Settings/user/My Documents.

Операция может завершиться ошибкой:

• UnsupportedOperation Операционная система не имеет понятия о каталоге документов.
• isDoesNotExistError Каталог документов текущего пользователя не существует или не может быть найден.

getTemporaryDirectory :: IO FilePath Source

Возвращает текущий каталог для временных файлов.

В Unix, getTemporaryDirectory возвращает значение переменной среды TMPDIR или "/tmp", если переменная не определена. В Windows функция проверяет наличие переменных среды в следующем порядке и использует первый найденный путь:

• Переменная среды TMP.
• Переменная среды TEMP.
• Переменная среды USERPROFILE.
• Каталог Windows

Операция может завершиться ошибкой:

• UnsupportedOperation Операционная система не имеет понятия о временном каталоге.

Функция не проверяет существование пути.

Действия с файлами

removeFile :: FilePath -> IO () Source

removeFile file удаляет запись о существующем файле file, где file не является каталогом. Реализация может указывать дополнительные ограничения, которые должны быть выполнены перед удалением файла (например, файл может быть занят другими процессами).

Операция может завершиться ошибкой:

• HardwareFault Произошла физическая ошибка ввода-вывода. [EIO]
• InvalidArgument Операнд не является допустимым именем файла. [ENAMETOOLONG, ELOOP]
• isDoesNotExistError / NoSuchThing Файл не существует. [ENOENT, ENOTDIR]
• isPermissionError / PermissionDenied У процесса недостаточно привилегий для выполнения операции. [EROFS, EACCES, EPERM]
• UnsatisfiedConstraints Не выполнены зависящие от реализации ограничения. [EBUSY]
• InappropriateType Операнд ссылается на существующий каталог. [EPERM, EINVAL]

renameFile :: FilePath -> FilePath -> IO () Source

renameFile old new изменяет имя существующего объекта файловой системы с old на new. Если объект new уже существует, он атомарно заменяется объектом old. Ни один путь не должен ссылаться на существующий каталог. Соответствующая реализация может не поддерживать переименование файлов во всех ситуациях (например, переименование между разными физическими устройствами), но ограничения должны быть задокументированы.

Операция может завершиться ошибкой:

• HardwareFault Произошла физическая ошибка ввода-вывода. [EIO]
• InvalidArgument Любой операнд не является допустимым именем файла. [ENAMETOOLONG, ELOOP]
• isDoesNotExistError / NoSuchThing Исходный файл не существует или нет пути к целевому файлу. [ENOENT, ENOTDIR]
• isPermissionError / PermissionDenied У процесса недостаточно привилегий для выполнения операции. [EROFS, EACCES, EPERM]
• ResourceExhausted Недостаточно ресурсов для выполнения операции. [EDQUOT, ENOSPC, ENOMEM, EMLINK]
• UnsatisfiedConstraints Не выполнены зависящие от реализации ограничения. [EBUSY]
• UnsupportedOperation Реализация не поддерживает переименование в этой ситуации. [EXDEV]
• InappropriateType Любой путь ссылается на существующий каталог. [ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]

copyFile :: FilePath -> FilePath -> IO () Source

copyFile old new копирует существующий файл из old в new. Если файл new уже существует, он атомарно заменяется файлом old. Ни один путь не может ссылаться на существующий каталог. Права доступа к old копируются в new, если это возможно.

canonicalizePath :: FilePath -> IO FilePath Source

Канонизирует путь к существующему файлу или каталогу. Цель состоит в том, чтобы два пути, ссылающиеся на один и тот же файл/каталог, отображались на один и тот же канонический путь.

Примечание: если вам нужен только абсолютный путь, используйте makeAbsolute вместо этого, что более надежно и не имеет неопределённого поведения на несуществующих путях.

Гарантировать, что (один и тот же файл/каталог <=> один и тот же канонический путь) выполняется в обоих направлениях невозможно: данная функция может только сделать лучшую попытку.

Точное поведение соответствует функции POSIX realpath (или GetFullPathNameW в Windows). В частности, поведение на путях, которые не существуют, может различаться в зависимости от платформы. Некоторые платформы не изменяют вход, некоторые изменяют, а некоторые выбрасывают исключение.

Пустой путь считается эквивалентным текущему каталогу.

Известная(ые) ошибка(и): в Windows эта функция не обрабатывает символические ссылки.

makeAbsolute :: FilePath -> IO FilePath Source

Сделайте путь абсолютным, добавив текущий каталог (если он не абсолютный) и применив normalise к результату.

Операция может завершиться ошибкой с теми же исключениями, что и getCurrentDirectory.

С момента: 1.2.2.0

makeRelativeToCurrentDirectory :: FilePath -> IO FilePath Источник

makeRelative текущий каталог.

findExecutable :: String -> IO (Maybe FilePath) Источник

Учитывая имя исполняемого файла, ищет такой файл в каталогах, перечисленных в переменной окружения PATH. Возвращаемое значение — путь к найденному исполняемому файлу или Nothing, если исполняемый файл с заданным именем не найден. Например, (findExecutable "ghc") даёт вам путь к GHC.

Путь, возвращаемый findExecutable соответствует программе, которая будет выполнена createProcess при передаче той же строки (как RawCommand, а не ShellCommand).

В Windows findExecutable вызывает функцию Win32 SearchPath, которая может искать в других местах, прежде чем проверять каталоги в PATH. Точное место поиска зависит от настроек реестра, но, в частности, включает каталог, содержащий текущий исполняемый файл. Более подробную информацию см. в http://msdn.microsoft.com/en-us/library/aa365527.aspx.

findExecutables :: String -> IO [FilePath] Источник

Учитывая имя файла, ищет файл и возвращает список всех его вхождений, которые являются исполняемыми.

С момента: 1.2.2.0

findFile :: [FilePath] -> String -> IO (Maybe FilePath) Источник

Поиск заданного файла в заданном наборе каталогов. Используется findExecutable на платформах, отличных от Windows.

findFiles :: [FilePath] -> String -> IO [FilePath] Источник

Поиск заданного файла в заданном наборе каталогов и возвращает список путей, где заданный файл существует.

С момента: 1.2.1.0

findFilesWith :: (FilePath -> IO Bool) -> [FilePath] -> String -> IO [FilePath] Источник

Поиск заданного файла в заданном наборе каталогов с заданным свойством (обычно разрешениями) и возвращает список путей, где заданный файл существует и имеет это свойство.

С момента: 1.2.1.0

Проверки существования

doesFileExist :: FilePath -> IO Bool Источник

Операция doesFileExist возвращает True, если файл аргумента существует и не является каталогом, и False в противном случае.

doesDirectoryExist :: FilePath -> IO Bool Источник

Операция doesDirectoryExist возвращает True, если файл аргумента существует и является каталогом или символической ссылкой на каталог, и False в противном случае.

Разрешения

Тип Permissions используется для записи, разрешены ли определённые операции над файлом/каталогом. getPermissions и setPermissions соответственно получают и устанавливают эти разрешения. Разрешения применяются как к файлам, так и к каталогам. Для каталогов поле executable будет False, а для файлов — searchable False. Обратите внимание, что каталоги могут быть доступны для поиска без чтения, если разрешение было предоставлено для их использования в качестве части пути, но не для проверки содержимого каталога.

Обратите внимание, что для изменения некоторых, но не всех разрешений, необходимо использовать конструкцию на следующих строках.

 makeReadable f = do
    p <- getPermissions f
    setPermissions f (p {readable = True})

data Permissions Источник

emptyPermissions :: Permissions Источник

readable :: Permissions -> Bool Источник

writable :: Permissions -> Bool Источник

executable :: Permissions -> Bool Источник

searchable :: Permissions -> Bool Источник

setOwnerReadable :: Bool -> Permissions -> Permissions Источник

setOwnerWritable :: Bool -> Permissions -> Permissions Источник

setOwnerExecutable :: Bool -> Permissions -> Permissions Источник

setOwnerSearchable :: Bool -> Permissions -> Permissions Источник

getPermissions :: FilePath -> IO Permissions Источник

Операция getPermissions возвращает разрешения для файла или каталога.

Операция может завершиться ошибкой:

• isPermissionError если пользователю запрещен доступ к разрешениям; или
• isDoesNotExistError если файл или директория не существует.

setPermissions :: FilePath -> Permissions -> IO () Source

Операция setPermissions устанавливает разрешения для файла или директории.

Операция может завершиться неудачно в случае:

• isPermissionError если пользователю запрещено устанавливать разрешения; или
• isDoesNotExistError если файл или директория не существует.

copyPermissions :: FilePath -> FilePath -> IO () Source

Марки времени

getModificationTime :: FilePath -> IO UTCTime Source

Операция getModificationTime возвращает время, когда файл или директория были в последний раз изменены.

Операция может завершиться неудачно в случае:

• isPermissionError если пользователю запрещен доступ к времени изменения; или
• isDoesNotExistError если файл или директория не существует.

Примечание: Эта функция возвращает отметку времени с разрешением до долей секунды только в том случае, если этот пакет скомпилирован с unix-2.6.0.0 или более поздней версией для систем Unix, и Win32-2.3.1.0 или более поздней версией для систем Windows. Конечно, это также требует, чтобы файловая система поддерживала такие отметки времени с высоким разрешением.