GHC.IO.Handle

Авторские права	(c) Университет Глазго, 1994-2009
Лицензия	см. libraries/base/LICENSE
Поддержка	libraries@haskell.org
Устойчивость	предварительная
Переносимость	непереносимая
Безопасный Haskell	Достоверный
Язык	Haskell2010

тип Handle Источник

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

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

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

тип BufferMode Источник

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

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

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

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

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

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

mkFileHandle Источник

создаёт новый дескриптор файла

hIsEOF :: Handle -> IO Bool Источник

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

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

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 если обработчик в двоичном режиме.

Обратите внимание, что обработчик 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

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 задаётся в байтах.

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

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

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

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

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

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

• isIllegalOperationError если дескриптор не поддерживает перемещение.

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 Исходный код

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

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

Определяет преобразование символов новой строки между внутренними строками и внешним файлом или потоком. Предполагается, что Haskell-строки представляют символы новой строки как '\n'; режим новой строки определяет, как преобразовать '\n' при выводе и что преобразовать в '\n' при вводе.

nativeNewline :: Newline Исходный код

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

noNewlineTranslation :: NewlineMode Исходный код

Отключить преобразование символов новой строки.

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

universalNewlineMode :: NewlineMode Исходный код

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

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

nativeNewlineMode :: NewlineMode Source

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

nativeNewlineMode  = NewlineMode { inputNL  = nativeNewline
                                   outputNL = nativeNewline }

hShow :: Handle -> IO String Source

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

hWaitForInput :: Handle -> Int -> IO Bool Source

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

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

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

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

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

hGetChar :: Handle -> IO Char Source

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

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

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

hGetLine :: Handle -> IO String Source

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

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

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

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

hGetContents :: Handle -> IO String Source

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

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

• если hClose применяется к нему;
• если при чтении элемента из объекта handle произошла ошибка ввода/вывода;
• или после прочтения всего содержимого объекта handle.

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

Любые ошибки ввода/вывода, возникшие в то время, когда объект handle был полузакрытым, просто игнорируются.

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

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

hPutChar :: Handle -> Char -> IO () Source

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

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

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

hPutStr :: Handle -> String -> IO () Source

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

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

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

hGetBuf :: Handle -> Ptr a -> Int -> IO Int Source

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

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

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

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

hGetBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int Source

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

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

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

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

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

hPutBuf :: Handle -> Ptr a -> Int -> IO () Source

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

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

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

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

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

hPutBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int Source