GHC.IO.Handle

data Handle Исходный код

Haskell определяет операции для чтения и записи символов из файлов и в файлы, представленные значениями типа Handle. Каждое значение этого типа — это дескриптор файла: запись, используемая системой выполнения Haskell для управления вводом-выводом с файловыми объектами. Дескриптор файла имеет как минимум следующие свойства:

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

Большинство дескрипторов файлов также будут иметь текущую позицию ввода-вывода, указывающую, где произойдёт следующая операция ввода-вывода. Дескриптор файла является читаемым, если он управляет только вводом или и вводом, и выводом; аналогично, он является записываемым, если он управляет только выводом или и вводом, и выводом. Дескриптор файла является открытым при первом выделении. После закрытия его нельзя больше использовать ни для ввода, ни для вывода, хотя реализация не может повторно использовать его хранилище, пока к нему есть ссылки. Дескрипторы файлов находятся в классах Show и Eq. Строка, полученная при отображении дескриптора файла, зависит от системы; она должна содержать достаточно информации для идентификации дескриптора файла для отладки. Дескриптор файла равен согласно == только самому себе; попытки сравнить внутреннее состояние разных дескрипторов файлов для равенства не предпринимаются.

data BufferMode Исходный код

Поддерживаются три вида буферизации: строчная, блочная или без буферизации. Эти режимы оказывают следующие эффекты. Для вывода элементы выводятся или сбрасываются из внутреннего буфера в соответствии с режимом буферизации:

• строчная буферизация: весь буфер вывода сбрасывается всякий раз, когда выводится новая строка, буфер переполняется, выпущен hFlush, или дескриптор файла закрыт.
• блочная буферизация: весь буфер выводится всякий раз, когда он переполняется, выпущен hFlush, или дескриптор файла закрыт.
• без буферизации: вывод записывается немедленно и никогда не хранится в буфере.

Реализация может сбрасывать буфер чаще, но не реже, чем указано выше. Буфер вывода очищается сразу же после записи.

Аналогичным образом, ввод происходит в соответствии с режимом буферизации для дескриптора файла:

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

Режим буферизации по умолчанию при открытии дескриптора файла зависит от реализации и может зависеть от файлового объекта, прикреплённого к этому дескриптору. Для большинства реализаций физические файлы обычно будут иметь блочную буферизацию, а терминалы обычно будут иметь строчную буферизацию.

mkFileHandle Исходный код

создает новый Handle

mkDuplexHandle :: (IODevice dev, BufferedIO dev, Typeable dev) => dev -> FilePath -> Maybe TextEncoding -> NewlineMode -> IO Handle Исходный код

подобно mkFileHandle, за исключением того, что создаётся Handle с двумя независимыми буферами, одним для чтения и одним для записи. Используется для полнодуплексных потоков, таких как сетевые сокеты.

hFileSize :: Handle -> IO Integer Source

Для дескриптора hdl , который прикреплен к физическому файлу, hFileSize hdl возвращает размер этого файла в байтах.

hSetFileSize :: Handle -> Integer -> IO () Source

hSetFileSize hdl size обрезает физический файл с дескриптором hdl до size байт.

hIsEOF :: Handle -> IO Bool Source

Для доступного для чтения дескриптора hdl, hIsEOF hdl возвращает True , если из hdl нельзя получить дополнительный ввод или для физического файла, если текущая позиция ввода-вывода равна длине файла. В противном случае возвращает False.

ПРИМЕЧАНИЕ: hIsEOF может заблокироваться, поскольку ему необходимо попытаться прочитать из потока, чтобы определить, есть ли еще какие-либо данные для чтения.

isEOF :: IO Bool Source

Вычисление isEOF идентично hIsEOF, за исключением того, что оно работает только с stdin.

hLookAhead :: Handle -> IO Char Source

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

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

• isEOFError если достигнут конец файла.

hSetBuffering :: Handle -> BufferMode -> IO () Source

Вычисление hSetBuffering hdl mode устанавливает режим буферизации для дескриптора hdl при последующих операциях чтения и записи.

Если режим буферизации изменён с BlockBuffering или LineBuffering на NoBuffering, то

• если hdl доступен для записи, буфер очищается как для hFlush;
• если hdl недоступен для записи, содержимое буфера отбрасывается.

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

• isPermissionError если дескриптор уже использовался для чтения или записи, и реализация не позволяет изменить режим буферизации.

hSetBinaryMode :: Handle -> Bool -> IO () Source

Выбор двоичного режима (True) или текстового режима (False) для открытого дескриптора. (См. также openBinaryFile.)

Это имеет тот же эффект, что и вызов hSetEncoding с char8, вместе с hSetNewlineMode с noNewlineTranslation.

hSetEncoding :: Handle -> TextEncoding -> IO () Source

Действие hSetEncoding hdl encoding изменяет кодировку текста для дескриптора hdl на encoding. По умолчанию при создании дескриптора Handle используется localeEncoding, а именно кодировка по умолчанию для текущего языка.

Чтобы создать дескриптор Handle без кодировки, используйте openBinaryFile. Чтобы остановить дальнейшую кодировку или декодирование для существующего дескриптора Handle, используйте hSetBinaryMode.

hSetEncoding может потребоваться очистить данные в буфере, чтобы изменить кодировку.

hGetEncoding :: Handle -> IO (Maybe TextEncoding) Source

Возвращает текущую TextEncoding для указанного Handle, или Nothing , если Handle находится в двоичном режиме.

Обратите внимание, что TextEncoding ничего не запоминает о состоянии используемого кодера/декодера для данного Handle. Например, если используемая кодировка — UTF-16, использование hGetEncoding и hSetEncoding для сохранения и восстановления кодировки может привести к записи дополнительного порядка байтов в файл.

hFlush :: Handle -> IO () Source

Действие hFlush hdl заставляет любые элементы, буферизованные для вывода в дескрипторе hdl, быть отправленными в операционную систему немедленно.

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

• isFullError если устройство заполнено;
• isPermissionError если превышен предел системных ресурсов. Не определено, будут ли символы в буфере отброшены или сохранены в этих обстоятельствах.

hFlushAll :: Handle -> IO () Source

Действие hFlushAll hdl очищает все буферизованные данные в hdl, включая любые буферизованные данные чтения. Буферизованные данные чтения очищаются путём возвращения позиции файла обратно к точке до чтения буферизованных данных, и поэтому работает только если hdl является позиционируемым (см. hIsSeekable).

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

• isFullError если устройство заполнено;
• isPermissionError если превышен предел системных ресурсов. Не определено, будут ли символы в буфере отброшены или сохранены в этих обстоятельствах;
• isIllegalOperation если hdl имеет буферизованные данные чтения и не является позиционируемым.

hDuplicate :: Handle -> IO Handle Source

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

hDuplicateTo :: Handle -> Handle -> IO () Source

Делает второй дескриптор дубликатом первого дескриптора. Второй дескриптор будет закрыт в первую очередь, если он ещё не закрыт.

Это может быть использовано для перенаправления стандартных дескрипторов, например:

do h <- openFile "mystdout" WriteMode
   hDuplicateTo h stdout

hClose :: Handle -> IO () Source

Вычисление hClose hdl закрывает дескриптор hdl . Перед завершением вычисления, если hdl доступен для записи, его буфер очищается как для hFlush. Выполнение hClose на дескрипторе, который уже закрыт, не имеет эффекта; это не ошибка. Все остальные операции на закрытом дескрипторе завершатся ошибкой. Если hClose завершится ошибкой по какой-либо причине, все последующие операции (кроме hClose) на дескрипторе все равно завершатся ошибкой, как если бы hdl был успешно закрыт.

hClose_help :: Handle__ -> IO (Handle__, Maybe SomeException) Source

data LockMode Source

Указывает режим блокировки файла.

hLock :: Handle -> LockMode -> IO () Source

Если ссылка Handle указывает на дескриптор файла, попытаться заблокировать содержимое файла в соответствующем режиме. Если файл уже заблокирован в несовместимом режиме, эта функция блокируется до установления блокировки. Блокировка автоматически снимается при закрытии Handle.

Рекомендации:

1) Эта функция может заблокироваться внутри вызова C. Если это произойдёт, чтобы иметь возможность прервать её асинхронными исключениями и/или для продолжения работы другим потокам, НЕОБХОДИМО использовать многопоточную версию системы выполнения.

2) Реализация использует LockFileEx в Windows и flock в противном случае, поэтому все их предостережения также относятся сюда.

3) На платформах, не являющихся Windows, которые не поддерживают flock (например, Solaris), эта функция выбросит FileLockingNotImplemented. Мы намеренно выбрали не предоставлять блокировку на основе fcntl из-за её некорректной семантики.

С версии: base-4.10.0.0

hTryLock :: Handle -> LockMode -> IO Bool Source

Неблокирующая версия hLock.

С версии: base-4.10.0.0

type HandlePosition = Integer Source

data HandlePosn Source

hGetPosn :: Handle -> IO HandlePosn Source

Вычисление hGetPosn hdl возвращает текущую позицию ввода-вывода hdl как значение абстрактного типа HandlePosn.

hSetPosn :: HandlePosn -> IO () Source

Если вызов hGetPosn hdl возвращает позицию p, то вычисление hSetPosn p устанавливает позицию hdl в позицию, которая была у неё в момент вызова hGetPosn.

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

• isPermissionError если будет превышен системный лимит ресурсов.

data SeekMode Source

Режим, определяющий действие hSeek hdl mode i.

hSeek :: Handle -> SeekMode -> Integer -> IO () Исходный код

Вычисление hSeek hdl mode i устанавливает положение обработчика hdl в зависимости от mode. Смещение i задаётся в байтах по 8 бит.

Если hdl является буферизованным по блокам или строкам, то перемещение к позиции, не находящейся в текущем буфере, сначала приведёт к записи в устройство любых элементов в выходном буфере, а затем к удалению входного буфера. Некоторые обработчики могут быть неперемещаемыми (см. hIsSeekable), или поддерживать только подмножество возможных операций позиционирования (например, может быть возможным перемещение только до конца ленты или на положительное смещение от начала или текущего положения). Невозможно установить отрицательное положение ввода-вывода или, для физического файла, позицию ввода-вывода, превышающую текущий конец файла.

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

• isIllegalOperationError если Handle неперемещаемый или не поддерживает запрошенный режим перемещения.
• isPermissionError если будет превышен системный лимит ресурсов.

hTell :: Handle -> IO Integer Исходный код

Вычисление hTell hdl возвращает текущую позицию обработчика hdl, как число байт от начала файла. Возвращаемое значение может быть затем передано в hSeek для перемещения обработчика в текущую позицию.

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

• isIllegalOperationError если Handle неперемещаемый.

hIsOpen :: Handle -> IO Bool Исходный код

hIsClosed :: Handle -> IO Bool Исходный код

hIsReadable :: Handle -> IO Bool Исходный код

hIsWritable :: Handle -> IO Bool Исходный код

hGetBuffering :: Handle -> IO BufferMode Исходный код

Вычисление hGetBuffering hdl возвращает текущий режим буферизации для hdl.

hIsSeekable :: Handle -> IO Bool Исходный код

hSetEcho :: Handle -> Bool -> IO () Исходный код

Установить статус отображения для обработчика, подключённого к терминалу.

hGetEcho :: Handle -> IO Bool Исходный код

Получить статус отображения для обработчика, подключённого к терминалу.

hIsTerminalDevice :: Handle -> IO Bool Исходный код

Подключён ли обработчик к терминалу?

hSetNewlineMode :: Handle -> NewlineMode -> IO () Исходный код

Установить NewlineMode на указанном Handle. Все данные в буфере сбрасываются сначала.

data Newline Исходный код

Представление новой строки во внешнем файле или потоке.

'\n'

'\r\n'

data РежимПереводаНовыхСтрок Исходный код

Указывает перевод символов новой строки, если таковой имеется, между внутренними строками и внешним файлом или потоком. Строки Haskell предполагаются представляющими новые строки символом %%%НЕ_ПЕРЕВОДИТСЯ_146%%%; режим новой строки указывает, как преобразовать %%%НЕ_ПЕРЕВОДИТСЯ_147%%% при выводе и что преобразовать в %%%НЕ_ПЕРЕВОДИТСЯ_148%%% при вводе.

nativeNewline :: НоваяСтрока Исходный код

Представление новой строки для текущей платформы: LF на системах Unix, CRLF на Windows.

noNewlineTranslation :: РежимПереводаНовыхСтрок Исходный код

Не производить перевод новых строк вообще.

noNewlineTranslation  = NewlineMode { inputNL  = LF, outputNL = LF }

universalNewlineMode :: РежимПереводаНовыхСтрок Исходный код

Преобразовывать '\r\n' в '\n' при вводе и '\n' в представление новой строки по умолчанию при выводе. Этот режим можно использовать на любой платформе и он работает с текстовыми файлами, использующими любой формат новой строки. Недостатком является то, что readFile >>= writeFile может привести к изменению файла.

universalNewlineMode  = NewlineMode { inputNL  = CRLF,
                                      outputNL = nativeNewline }

nativeNewlineMode :: РежимПереводаНовыхСтрок Исходный код

Использовать представление новой строки по умолчанию как для ввода, так и для вывода.

nativeNewlineMode  = NewlineMode { inputNL  = nativeNewline
                                   outputNL = nativeNewline }

hShow :: Дескриптор -> IO Строка Исходный код

hShow находится в IO монаде и обеспечивает более полную вывод, чем чистый пример Show для Handle.

hWaitForInput :: Дескриптор -> Целое -> IO Булево Исходный код

Вычисление hWaitForInput hdl t ожидает, пока входные данные не появятся в обработчике hdl. Оно возвращает True как только входные данные появятся в hdl, или False если входные данные не появятся в течение t миллисекунд. Обратите внимание, что hWaitForInput ожидает, пока один или несколько полных символов не станут доступными, что означает необходимость декодирования, и, следовательно, может завершиться ошибкой декодирования.

Если t меньше нуля, то hWaitForInput ожидает неопределённое время.

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

• isEOFError если достигнут конец файла.
• ошибкой декодирования, если входные данные начинаются с недопустимой последовательности байтов в кодировке этого обработчика.

ПРИМЕЧАНИЕ для пользователей GHC: если вы не используете флаг -threaded, hWaitForInput hdl t где t >= 0 заблокирует все другие потоки Haskell на время вызова. В этом отношении он ведёт себя как safe внешнее вызов.

hGetChar :: Handle -> IO Char Источник

Вычисление hGetChar hdl считывает символ из файла или канала, управляемого hdl, ожидая, пока символ не станет доступным.

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

• isEOFError если достигнут конец файла.

hGetLine :: Handle -> IO String Источник

Вычисление hGetLine hdl считывает строку из файла или канала, управляемого hdl.

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

• isEOFError если при чтении первого символа строки встречается конец файла.

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

hGetContents :: Handle -> IO String Источник

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

Любая операция, которая завершается ошибкой из-за закрытия обработчика, также завершается ошибкой, если обработчик полузакрыт. Исключение составляет hClose. Полузакрытый обработчик становится закрытым:

• если к нему применяется hClose;
• если при чтении элемента из обработчика возникает ошибка ввода-вывода;
• или после того, как весь контент обработчика был прочитан.

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

Любые ошибки ввода-вывода, возникающие, когда обработчик полузакрыт, просто игнорируются.

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

• isEOFError если достигнут конец файла.

hPutChar :: Handle -> Char -> IO () Источник

Вычисление hPutChar hdl ch записывает символ ch в файл или канал, управляемый hdl. Символы могут быть буферизованы, если буферизация включена для hdl.

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

• isFullError если устройство заполнено; или
• isPermissionError если превышен другой системный лимит ресурсов.

hPutStr :: Handle -> String -> IO () Источник

Вычисление hPutStr hdl s записывает строку s в файл или канал, управляемый hdl.

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

• isFullError если устройство заполнено; или
• isPermissionError если превышен другой системный лимит ресурсов.

hGetBuf :: Handle -> Ptr a -> Int -> IO Int Источник

hGetBuf hdl buf count считывает данные из обработчика hdl в буфер buf до тех пор, пока не будет достигнут конец файла или не будут прочитаны count 8-битных байтов. Возвращает количество фактически прочитанных байтов. Может быть нулём, если конец файла был достигнут до чтения каких-либо данных (или если count равно нулю).

hGetBuf никогда не генерирует исключение EOF, вместо этого возвращает значение меньше count.

Если обработчик является каналом или сокетом, а конец записи закрыт, hGetBuf будет вести себя так, как будто достигнут конец файла.

hGetBuf игнорирует действующую TextEncoding и NewlineMode на Handle, и считывает байты напрямую.

hGetBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int Источник

hGetBufNonBlocking hdl buf count считывает данные из обработчика hdl в буфер buf до тех пор, пока не будет достигнут конец файла, не будут прочитаны count 8-битных байтов или не станет доступно больше данных для непосредственного чтения.

hGetBufNonBlocking идентично hGetBuf, за исключением того, что оно никогда не будет блокироваться в ожидании появления данных, вместо этого оно возвращает только доступные данные. Чтобы подождать появления данных перед вызовом hGetBufNonBlocking, используйте hWaitForInput.

Если обработчик является каналом или сокетом, а конец записи закрыт, hGetBufNonBlocking будет вести себя так, как будто достигнут конец файла.

hGetBufNonBlocking игнорирует действующую TextEncoding и NewlineMode на Handle, и считывает байты напрямую.

ПРИМЕЧАНИЕ: в Windows эта функция работает некорректно; она ведет себя идентично hGetBuf.

hPutBuf :: Handle -> Ptr a -> Int -> IO () Источник

hPutBuf hdl buf count записывает count 8-битных байтов из буфера buf в обработчик hdl. Возвращает ().

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

hPutBuf игнорирует действующую TextEncoding и NewlineMode на Handle, и записывает байты напрямую.

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

• ResourceVanished если обработчик является каналом или сокетом, а конец чтения закрыт. (Если это POSIX-система, и программа не попросила игнорировать SIGPIPE, то вместо этого может быть доставлено SIGPIPE, стандартным действием которого является завершение программы).

hPutBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int Источник