=encoding UTF-8


=head1 НАИМЕНОВАНИЕ

BH_IO - Подсистема ввода-вывода


=head1 СИНТАКСИС

 #include <BH/io.h>

 BH_IO *io = BH_FileNew("input.txt", BH_FILE_WRITE | BH_FILE_TRUNCATE, NULL);
 BH_IOWrite(io, "Hello, world!", 13, NULL);
 BH_IOFree(io);

 cc prog.c -o prog -lbh


=head1 ОПИСАНИЕ

BH_IO предоставляет подсистему, позволяющей работать с различными объектами
(файлы, сокеты, память) через единый интерфейс ввода-вывода. Это позволяет
писать код, непривязанный к конкретной системе ввода-вывода.

Гарантируется, что любой объект BH_IO поддерживает следующие операции:
L</BH_IORead>, L</BH_IOWrite>, L</BH_IOCtl> и L</BH_IOCap>.

В зависимости от реализации того или иного объекта BH_IO, могут быть доступны
дополнительные операции: L</BH_IOFlags>, L</BH_IOClear>, L</BH_IOFlush>,
L</BH_IOSize>, L</BH_IOTell>, L</BH_IOSeek>, L</BH_IOPeek> и другие.

По-умолчанию подсистема ввода-вывода позволяет работать с файлами
(L</BH_FileNew>) или оперативной памятью (L</BH_BytesNew>), а также
буферизировать ввод-вывод (L</BH_BufferNew>).


=head1 РАСШИРЕНИЕ

BH_IO предоставляет разработчику возможность создавать собственные реализации
устройств ввода-вывода. Пример:

 typedef struct BH_MyIO
 {
     BH_IO parent;
     int flags;
 };

 static int ioDestroy(BH_MyIO *io)
 {
     /* Ommitted for the example */
 }

 static int ioRead(BH_MyIO *io,
                   BH_IOReadInfo *info)
 {
     /* Ommitted for the example */
 }

 static int ioWrite(BH_MyIO *io,
                    BH_IOWriteInfo *info)
 {
     /* Ommited for the example */
 }

 static int ioFlags(BH_MyIO *io,
                    int *flags)
 {
     *flags = io->flags;
     return BH_OK;
 }

 static int ioCap(BH_MyIO *io,
                  int *op)
 {
     BH_UNUSED(io);

     switch (*op)
     {
     case BH_IO_CTL_FLAGS:
         return BH_OK;

     default:
         return BH_NOIMPL;
     }
 }

 static int ioCtl(BH_MyIO *io,
                  BH_IOCtlInfo *info)
 {
     switch (info->op)
     {
     case BH_IO_CTL_FLAGS:
         return ioFlags(io, (int *)info->arg);

     default:
         return BH_NOIMPL;
     }
 }

 static int ioCallback(BH_MyIO *io,
                       int type,
                       void *arg)
 {
     switch (type)
     {
     case BH_IO_OP_DESTROY:  return ioDestroy(io);
     case BH_IO_OP_READ:     return ioRead(io, (BH_IOReadInfo *)arg);
     case BH_IO_OP_WRITE:    return ioWrite(io, (BH_IOWriteInfo *)arg);
     case BH_IO_OP_CTL:      return ioCtl(io, (BH_IOCtlInfo *)arg);
     case BH_IO_OP_CAP:      return ioCap(io, (int*)arg);
     default:                return BH_NOIMPL;
     }
 }

 BH_IO *BH_MyIONew(int *result)
 {
     BH_MyIO *io;
     int code;

     code = BH_OOM;
     if ((io = malloc(sizeof(*io))))
     {
         io->parent.callback = (BH_IOCallback)ioCallback;
         io->flags = 0;
     }

     if (result)
         *result = code;

     return (BH_IO*)io;
 }


=head1 API ВЫЗОВЫ


=head2 BH_FileNew

 BH_IO *BH_FileNew(const char *path,
                   int mode,
                   int *result);

Создает устройство ввода-вывода для работы с файлом по пути I<path>.

Параметр I<mode> может принимать комбинацию из следующих значений:

=over

=item B<BH_FILE_READ>

Открывает файл на чтение

=item B<BH_FILE_WRTIE>

Открывает файл на запись

=item B<BH_FILE_APPEND>

Открывает файл в режиме добавление в конец

=item B<BH_FILE_TRUNCATE>

Усекает файл

=item B<BH_FILE_CREATE>

Файл должен быть создан

=item B<BH_FILE_EXIST>

Файл должен существовать

=back

Опциональный параметр I<result> возвращает 0 или код ошибки.

Данная функция возвращает указатель на новый BH_IO объект или NULL.


=head2 BH_IOIsFile

 int BH_IOIsFile(BH_IO *device);

Проверяет, является ли устройство ввода-вывода файлом.


=head2 BH_BufferNew

 BH_IO *BH_BufferNew(BH_IO *device,
                     size_t size,
                     int *result);

Создает устройство ввода-вывода для буферизации данных к другому устройству
I<device>.

Параметр I<size> отвечает за размер буферов чтения и записи.

Опциональный параметр I<result> возвращает 0 или код ошибки.

В случае успеха, данная функция возвращает указатель на новый BH_IO объект или
NULL в случае ошибки.


=head2 BH_IOIsBuffer

 int BH_IOIsBuffer(BH_IO *device);

Проверяет, является ли устройство ввода-вывода буфером.


=head2 BH_BytesNew

 BH_IO *BH_BytesNew(char *data,
                    size_t size,
                    int *result);

Создает устройство ввода-вывода для региона памяти I<data> с размером I<size>.

Опциональный параметр I<result> возвращает код ошибки.

В случае успеха, данная функция возвращает указатель на новый BH_IO объект или
NULL в случае ошибки.


=head2 BH_IOIsBytes

 int BH_IOIsBytes(BH_IO *device);

Проверяет, является ли устройство ввода-вывода регионом памяти.


=head2 BH_IOFree

 void BH_IOFree(BH_IO *device);

Уничтожает устройство ввода-вывода.


=head2 BH_IORead

 int BH_IORead(BH_IO *device,
               char *buffer,
               size_t size,
               size_t *actual);

Читает до I<size> байт из устройства ввода-вывода и записывает данные в
I<buffer>.

Опциональный параметр I<actual> возвращает число байт, которое было фактически
прочитано.

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOWrite

 int BH_IOWrite(BH_IO *io,
                const char *buffer,
                size_t size,
                size_t *actual);

Записывает до I<size> байт в устройство ввода-вывода из I<buffer>.

Опциональный параметр I<actual> возвращает число байт, которое было записано.

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOCtl

 int BH_IOCtl(BH_IO *device,
              int op,
              void *arg);

Манипулирует параметрами устройства ввода-вывода с помощью команды I<op> и
параметра I<arg>.

Возможные значения I<op>:

=over

=item B<BH_IO_CTL_FLAGS>

Аргумент: int *

Вернуть флаги устройства ввода-вывода.

=item B<BH_IO_CTL_CLEAR>

Сбросить ошибки устройства ввода-вывода.

=item B<BH_IO_CTL_PEEK>

Аргумент: L<BH_IOReadInfo *|/BH_IOReadInfo>

Читает без извлечения данные из устройства ввода-вывода.

=item B<BH_IO_CTL_FLUSH>

Записать буферизированные данные в устройство ввода-вывода.

=item B<BH_IO_CTL_SIZE>

Аргумент: int64_t *

Получить размер устройства ввода-вывода.

=item B<BH_IO_CTL_TELL>

Аргумент: int64_t *

Читает текущее смещение указателя чтения устройства ввода-вывода.

=item B<BH_IO_CTL_SEEK>

Аргумент: L<BH_IOSeekInfo *|/BH_IOSeekInfo>

Изменяет текущее положение указателя чтения устройства ввода-вывода.

=item B<BH_IO_CTL_GET_IO>

Аргумент: L<BH_IO **|/BH_IO>|void *

Получает объект устройства, используемый в реализации.

=item B<BH_IO_CTL_SET_IO>

Аргумент: L<BH_IO *|/BH_IO>|void *

Устанавливает объект устройства, который будет использоваться в реализации.

=back

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOCap

 int BH_IOCap(BH_IO *device,
              int op);

Проверяет возможность выполнения команды I<op> на устройстве ввода-вывода.

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOFlags

 int BH_IOFlags(BH_IO *device,
                int *flags);

Возвращает текущие флаги I<flags> устройства ввода-вывода.

Возможные флаги (и их комбинации):

=over

=item B<BH_IO_FLAG_ERROR>

В процессе выполнения возникла ошибка.

=item B<BH_IO_FLAG_EOF>

Устройство достигло конца файла.

=back

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOClear

 int BH_IOClear(BH_IO *device);

Очищает устройство ввода-вывода от ошибок.

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOPeek

 int BH_IOPeek(BH_IO *device,
               char *buffer,
               size_t size,
               size_t *actual);

Читает без извлечения до I<size> байт из устройства ввода-вывода и записывает
данные в I<buffer>.

Опциональный параметр I<actual> возвращает число байт, которое было фактически
прочитано.

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOFlush

 int BH_IOFlush(BH_IO *device);

Записывает буферизированные значения в устройство ввода-вывода.

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOSize

 int BH_IOSize(BH_IO *device,
               int64_t *size);

Читает текущий размер устройства ввода-вывода в байтах и записывает значение в
I<size>.

Для различных типов устройств ввода-вывода данное значение может означать разные
вещи (к примеру: текущий размер файла, размер выделенной для ввода-вывода памяти
и т.д.).

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOTell

 int BH_IOTell(BH_IO *device,
               int64_t *offset);

Читает текущее смещение указателя чтения устройства ввода-вывода относительно
начала и записывает значение в I<offset>.

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOSeek

 int BH_IOSeek(BH_IO *device,
               int64_t offset,
               int whence);

Изменяет текущее положение указателя чтения устройства ввода-вывода с учетом
смещения I<offset> и начальной позиции I<whence>.

Возможные значения начальной позиции I<whence>:

=over

=item B<BH_IO_SEEK_SET>

Смещение относительно начала устройства.

=item B<BH_IO_SEEK_CUR>

Смещение относительно текущей позиции устройства.

=item B<BH_IO_SEEK_END>

Смещение относительно конца устройства.

=back

В случае успеха, данная функция возвращает 0 или код ошибки.


=head2 BH_IOError

 int BH_IOError(BH_IO *device);

Проверяет, находится ли устройство ввода-вывода в состоянии ошибки.

Данная функция эквивалентна следующему коду:

 (BH_IOFlags(device) & BH_IO_FLAG_ERROR)


=head2 BH_IOEndOfFile

 int BH_IOEndOfFile(BH_IO *device);

Проверяет, достигло ли устройство ввода-вывода конца.

Данная функция эквивалентна следующему коду:

 (BH_IOFlags(device) & BH_IO_FLAG_EOF)


=head2 BH_IOReadLine

 char *BH_IOReadLine(BH_IO *device,
                     char *str,
                     size_t size);

Читает строку размером до I<size - 1> байт из устройства ввода-вывода и
записывает данные в I<str>. Результирующая строка нуль-терминированная.

Останавливается на символе I<\n> или конце потока (EOF). Если строка длиннее
буфера, её остаток остаётся в устройстве ввода-вывода для последующего чтения.

Данная функция возвращает указатель на новый I<str> или NULL.


=head2 BH_IOReadLineFull

 char *BH_IOReadLineFull(BH_IO *device,
                         char *str,
                         size_t size);

Читает строку размером до I<size - 1> байт из устройства ввода-вывода и
записывает данные в I<str>. Результирующая строка нуль-терминированная.

Останавливается на символе I<\n> или конце потока (EOF). Полностью читает строку
из устройства ввода-вывода, отбрасывая избыточные данные.

Данная функция возвращает указатель на новый I<str> или NULL.


=head1 СТРУКТУРЫ ДАННЫХ


=head2 BH_IO

 typedef struct BH_IO
 {
     BH_IOCallback callback;
 } BH_IO;


=head2 BH_IOReadInfo

 typedef struct BH_IOReadInfo
 {
     char *data;
     size_t size;
     size_t *actual;
 } BH_IOReadInfo;


=head2 BH_IOWriteInfo

 typedef struct BH_IOWriteInfo
 {
     const char *data;
     size_t size;
     size_t *actual;
 } BH_IOWriteInfo;


=head2 BH_IOCtlInfo

 typedef struct BH_IOCtlInfo
 {
     int op;
     void *arg;
 } BH_IOCtlInfo;


=head2 BH_IOSeekInfo

 typedef struct BH_IOSeekInfo
 {
     int64_t offset;
     int whence;
 } BH_IOSeekInfo;


=head1 СМ. ТАКЖЕ

L<BH>