mife(3) FreeBSD Library Functions Manual mife(3) NAME mife_open, mife_opef, mife_opes, mife_opem, mife_read, mife_get, mife_close, mife_writ, mife_eolinit, mife_eoldetect, mife_aopen, mife_aput, mife_aclose -- еще одна библиотека ввода-вывода для отображе- ния входного потока в окно в памяти. LIBRARY library ``libmife'' SYNOPSIS #include #include #include mife_descriptor * mife_open(u_int32_t flags, const char *path); mife_descriptor * mife_opef(u_int32_t flags, int fd); mife_descriptor * mife_opes(u_int32_t flags, const char *mem, size_t size); mife_descriptor * mife_opem(u_int32_t flags, char *mem, size_t size); ssize_t mife_read(mife_descriptor *mife, ssize_t ordlen, off_t offset); void * mife_get(mife_descriptor *mife, off_t offset); int mife_close(mife_descriptor *mife); ssize_t mife_writ(int fd, const void *buf, size_t size); ssize_t mife_eolinit(mife_descriptor *mife, const char *eoln); ssize_t mife_eoldetect(mife_descriptor *mife); mife_aout * mife_aopen(u_int32_t flag, int fd); int mife_aput(mife_aout *aso, int src); int mife_aclose(mife_aout *aso); DESCRIPTION Функция mife_open() открывает объект с именем path и создает структуру для чтения из этого объекта или отображения его в память. mife_opef() отличается от mife_open() тем, что использует уже открытый дескриптор fd какого либо объекта, из которого можно читать. mife_opes() создает такую же структуру, но вместо входного файла исполь- зуется массив mem длинной size в памяти. mife_opem() отличается от mife_opes() тем, что входной массив не копиру- ется, а используется как задан. В составе создаваемой структуры имеется буфер, который используется как окно для доступа к данным в подлежащем объекте. Это окно можно переме- щать только в направлении с начала в конец, буфер этого окна доступен для локальных модификаций, которые не распространяются на подлежащий объект, кроме случая, когда структура открыта при помощи mife_opes(). mife_read() обеспечивает наличие в буфере-окне не менее ordlen байтов со смещения в файле или потоке offset, или если размера файла или потока недостаточно, то буферизуется все содержимое до конца файла или потока. Если ordlen равен нулю, то буферизуется все, что есть в объекте, если не задан MIFE_SLID. Если же при помощи mife_eolinit() был установлен eoln не NULL, тогда при чтении из потока проверяется наличие этой строки в прочитанном, и если искомая строка найдена, то попыток дочитать до заданного размера не дела- ется. Эта строка может быть пустой, тогда ей удовлетворяет любое содержи- мое буфера. mife_get() выдает указатель на буфер, где содержится информация из подле- жащего объекта со смещением offset. Размер окна, которым пользуется вызвавшая mife_get() программа, должен быть согласован с параметрами пре- дыдущего вызова mife_read(). mife_close() освобождает ресурсы, занятые структурой mife. mife_writ() не взаимодействует со всеми остальными процедурами, описан- ными здесь. Она помещает в объект, заданный дескриптором fd size байтов из массива buf, или если size задан нулевым, то строку buf до нулевого байта (но не включая этот нулевой байт). Временные ошибки или несогласо- вания размеров буфера обмена с mtu обрабатываются внутри mife_writ(). mife_eolinit() готовит детектор маркера конца записи к обнаружению мар- кера eoln. mife_eoldetect() проверяет наличие маркера конца записи в буфере. Пока нет хорошего описания, лучше не использовать напрямую, используется кос- венно при чтении в буфер. mife_aopen() создает структуру для управления асинхронным выводом в дескриптор fd. mife_aput() помещает один символ src в буфер и при необходимости запус- кает асинхронный вывод буфера и готовит следующий. Если разрешено флагом MIFE_EOFL, то входной символ EOF вызывает выполнение mife_aclose(). mife_aclose() довыводит недовыведенные буферы и освобождает память от структуры управления асинхронным выводом. Параметр flags предназначен для описания объекта mife. Его биты: #define MIFE_RTRY 0x000000FF (чтение) #define MIFE_BUFL 0x00000F00 (чтение и асинхронная запись) #define MIFE_SLID 0x00001000 (чтение) #define MIFE_SYNC 0x00002000 (асинхронная запись) #define MIFE_EOFL 0x00100000 (чтение и асинхронная запись) #define MIFE_FULL 0x00200000 (чтение) #define MIFE_BUFX 0x00800000 (чтение) #define BLIN_VER1 0x01000000 #define BLIN_VER2 0x02000000 #define BLIN_VER3 0x04000000 #define BLIN_VER4 0x08000000 #define BLIN_VER5 0x10000000 MIFE_EOFL Устанавливается библиотекой при обнаружении конца потока при чтении. Разрешает интерпретировать EOF во входном потоке как сигнал на закрытие выходного файла при асинхронной записи. MIFE_RTRY Если отлично от нуля, содержит количество попыток повторного чтения при возникновении временной ошибки. MIFE_BUFL При чтении, если ненулевое, то используется в вычислении мак- симального размера буфера окна. Зависимость примерно экспо- ненциальная. Точнее, буфер окна 64Kбайт * (1 << MIFE_BUFL), если не попадает под другие ограничения. При асинхронной записи задает количество выходных буферов на 1 большее, чем MIFE_BUFL. MIFE_FULL Задает, что в конце окна всегда будет нулевой байт - ограничи- тель строки. MIFE_BUFX Указывает, что при вычислении максимального буфера надо поль- зоваться только значением MIFE_BUFL и не использовать лимиты процесса. MIFE_CLOS При закрытии асинхронного вывода закрывать и дескриптор потока. MIFE_SYNC Не использоввать AIO. Функции mife_a*() при недоступности асинхронного используют синхронный вывод, этим флагом можно форсировать использование синхронного вывода вне зависимости от наличия асинхронного. MIFE_SLID Не пытаться буферизовать файл целиком, если желаемый размер буфера не задан (ordlen == 0), но задан конец записи (eoln). BLIN_VER1 Включает печать сообщений в stderr об ошибках. BLIN_VER2 и выше предназначены для отладки. Поля, неопределенные для ввода, при вызове mife_opeX() должны быть уста- новлены в 0. Поля, неопределенные для асинхронного вывода, при вызове mife_aopen() должны быть установлены в 0. Определены так же макрокоманды: getMIFE_RTRY(a) извлечение значения поля MIFE_RTRY из флагов a setMIFE_RTRY(a, x) установка значения x в поле MIFE_RTRY флагов a getMIFE_BUFL(a) извлечение значения поля MIFE_BUFL из флагов a setMIFE_BUFL(a, x) установка значения x в поле MIFE_BUFL флагов a kukMIFE_RTRY(x) не описана. kukMIFE_BUFL(x) не описана. RETURN VALUES Результатом выполнения функций семейства mife_opeX() является следующая структура: struct mife_descriptor { u_int32_t flag; /* Флаги */ int fd; /* Дескриптор файла или потока */ ssize_t mindelta; size_t actlen; /* Длинна прочитанного в буфере */ size_t buflen; /* Длинна буфера */ void *buffer; /* Буфер */ off_t offset; /* Начало буфера в файле или потоке */ off_t st_size; /* Длинна файла (если есть) */ mode_t st_mode; /* Тип потока */ .... /* Другие переменные */ }; Функция mife_read() возвращает длинну окна в памяти после заданного off. Функция mife_get() возвращает указатель на начало окна с заданным off. Этот параметр может не совпадать с заданным в прешествующей mife_read() (быть больше, но в пределах len). mife_writ() возвращает размер реально записанной информации или -1 при возникновении неисправимой ошибки. mife_close() возвращает 0 при успехе и -1 (или может другое ненулевое значение) если при закрытии случились ошибки. mife_eolinit() возвращает длинну строки - маркера конца записи. Если маркер не задан, то возвращает 0. mife_eoldetect() не описана. mife_aopen() возвращает структура управления асинхронным выводом: struct mife_aout { u_int32_t flag; /* Флаги */ union { size_t pos; struct { u_int16_t lo; u_int16_t hi; } wr; } towrite; /* Позиция в буфере для записи */ off_t offset; /* Начало буфера в файле или потоке */ .... /* Другие переменные */ }; mife_aput() возвращает 0 или больше при успехе и -1 при ошибке. mife_aclose() возвращает 0 или больше при успехе и -1 при ошибке. ERRORS Функции семейства mife_opeX() при ошибке возвращает NULL вместо ссылки на структуру и устанавливает errno. mife_read() при ошибке возвращает -1 и устанавливает errno. mife_get() при ошибке возвращает NULL и устанавливает errno. mife_eolinit() при ошибке возвращает -1 и устанавливает errno. mife_aopen() при ошибке возвращает NULL и устанавливает errno. mife_aput() при ошибке возвращает -1 и устанавливает errno. mife_aclose() при ошибке возвращает -1 и устанавливает errno. Ошибки могут возникать при выполнении процедур из Standard C Library (libc, -lc) а так же устанавливаться: [ENOMEM] не выделено достаточно памяти. [ESPIPE] mife_get() получила требование за пределами размещен- ного окна или mife_read() не может разместить заказан- ное окно из-за недостаточного количества информации в подлежащем объекте. Та же ошибка возникает и при попытке заказать окно ближе к началу, чем предыдущий заказ. [EDOM] параметр за пределами допустимого. [EINVAL] неверный параметр. [EBADF] отсутствует управляющая структура (mife_descriptor или mife_aout). SEE ALSO malloc(3), open(2), write(2), mmap(2), stat(2), close(2), aio_write(2), aio_error(2), aio_suspend(2), aio_return(2). BUGS Документация ни к черту. Не описана mife_eoldetect(). Не определены действия библиотеки, если задано чтение из каталога, нераз- решимого симлинка или S_IFWHT. MTU асинхронного вывода всегда 64Кбайта и не регулируется. В библиотеке при асинхронном выводе предполагается, что выравнивания всех структур на 16 байтов достаточно. AUTHOR Aleksandr A. Babaylov (aka @BABOLO) .@babolo.ru http://www.babolo.ru/ FreeBSD 4.11 26 January 2004 FreeBSD 4.11