Алфавитный список функций установления соединения и ввода/вывода

Алфавитный список функций установления соединения и ввода/вывода

В данном разделе в алфавитном порядке приведен список точек входа в функции установления соединения и ввода/вывода, которые вы можете заполнять самостоятельно (эти две таблицы затем передаются функции pathname_attach()). Помните, что если вы просто вызываете функцию iofunc_func_init(), все эти точки входа будут заполнены соответствующими значениями по умолчанию; вам следует переопределять конкретные точки входа только в том случае, если вы собираетесь обрабатывать данное конкретное сообщение самостоятельно. Ниже, в разделе «Примеры», вы увидите несколько примеров общеупотребительных функций.

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

Чтобы не путать точки входа в функции-обработчики сообщений с вызовами клиентской Си-библиотеки (например, open()), к именам всех приведенных здесь функций добавлен префикс «io_». Например, обработчик функции установления соединения open() будет называться io_open().

io_chmod()

int io_chmod(resmgr_context_t *ctp, io_chmod_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_chmod_default()

Вспомогательные функции: iofunc_chmod()

Клиентская функция: chmod(), fchmod()

Сообщения: _IO_CHMOD

Структура данных:

struct _io_chmod {

 uint16_t type;

 uint16_t combine_len;

 mode_t   mode;

};

typedef union {

 struct _io_chmod i;

} io_chmod_t;

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

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_chown()

int io_chown(resmgr_context_t *ctp, io_chown_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_chown_default()

Вспомогательные функции: iofunc_chown()

Клиентская функция: chown(), fchown()

Сообщения: _IO_CHOWN

Структура данных:

struct _io_chown {

 uint16_t type;

 uint16_t combine_len;

 int32_t  gid;

 int32_t  uid;

};

typedef union {

 struct _io_chown i;

} io_chown_t;

Описание: Ответственна за изменение полей идентификатора пользователя и группы для ресурса, указанному в переданном ей параметре ocb, соответственно в значения uid и gid. Отметим, что чтобы узнать, позволяет ли данная файловая система выполнять chown() кому-либо, кроме суперпользователя (root), надо проверить запись точки монтирования на предмет флага IOFUNC_PC_CHOWN_RESTRICTED, а также поле flags в OCB.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_close_dup()

int io_close_dup(resmgr_context_t *ctp, io_close_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_close_dup_default()

Вспомогательные функции: iofunc_close_dup()

Клиентская функция. close(), fclose()

Сообщения: _IO_CLOSE_DUP

Структура данных:

struct _io_close {

 uint16_t type;

 uint16_t combine_len;

};

typedef union {

 struct _io_close i;

} io_close_t;

Описание: Это реальный обработчик клиентских вызовов close() и fclose(). Отметим, что вам почти никогда не придется переназначать эту функцию; оставляйте в таблице функций ввода/вывода значение iofunc_close_dup_default(). Причиной этому служит то, что базовый уровень библиотеки отслеживает число сообщений open(), dup() и close(), выданных по каждому OCB, и синтезирует вызов io_close_ocb() (см. ниже) после получения для данного OCB последнего сообщения close(). Отметим, что идентификаторы отправителей, расположенные в ctp->rcvid, могут и не совпадать с переданными функции io_open(); однако, совпадение по меньшей мере одного идентификатора гарантируется. «Лишние» идентификаторы отправителей являются результатом (возможно, внутренних) вызовов типа dup().

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_close_ocb()

int io_close_ocb(resmgr_context_t *ctp, void* reserved,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода (синтезируется библиотекой)

Обработчик по умолчанию: iofunc_close_default()

Вспомогательные функции: Нет

Клиентская функция: Нет (синтезируется библиотекой)

Сообщения: Нет (синтезируется библиотекой)

Структура данных:

// Синтезируется библиотекой

struct _io_close {

 uint16_t type;

 uint16_t combine_len;

};

typedef union {

 struct _io_close i;

} io_close_t;

Описание: Это функция, которая синтезируется базовым уровнем библиотеки, когда для некоего OCB получено последнее сообщение close(). Это то самое место, где вам следует «подчистить» все перед уничтожением OCB. Отметим, что идентификатор отправителя в ctp->rcvid есть нуль (0), потому что данная функция синтезируется библиотекой и не обязательно соответствует какому-либо конкретному сообщению.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_devctl()

int io_devctl(resmgr_context_t *ctp, io_devctl_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_devctl_default()

Вспомогательные функции: iofunc_devctl()

Клиентская функция: devctl(), ioctl()

Сообщения: _IO_DEVCTL

Структура данных:

struct _io_devctl {

 uint16_t type;

 uint16_t combine_len;

 int32_t  dcmd;

 int32_t  nbytes;

 int32_t  zero;

};

struct _io_devctl_reply {

 uint32_t zero;

 int32_t  ret_val;

 int32_t  nbytes;

 int32_t  zero2;

};

typedef union {

 struct _io_devctl       i;

 struct _io_devctl_reply o;

} io_devctl_t;

Описание: Выполняет над устройством операцию ввода/вывода, переданную от клиентской функции devctl() в параметре dcmd. Клиент кодирует направление передачи данных двумя старшими разрядами dcmd, указывая этим, как функция devctl() должна передавать данные (поле «to» соответствует биту _POSIX_DEVDIR_TO, поле «from» — биту _POSIX_DEVDIR_FROM):

В случае, когда передачи данных нет, предполагается, что драйвер просто выполняет команду, заданную в dcmd. В случае передачи данных предполагается, что драйвер передает данные клиенту и/или обратно, используя вспомогательные функции resmgr_msgreadv() и resmgr_msgwritev(). Клиент указывает размер передачи в поле nbytes; драйвер должен установить число передаваемых байт в поле nbytes исходящей структуры.

Отметим, что структуры данных, предназначенные для ввода и вывода, дополнены нулями, чтобы быть выровненными друг относительно друга. Это означает, что неявная область данных начинается в этих структурах с того же самого адреса.

Если вы используете вспомогательную функцию iofunc_devctl(), то имейте в виду, что если она не сможет сделать что-либо с сообщением devctl(), она возвратит вам константу _RESMGR_DEFAULT. Эта сделано для отделения корректных значений errno от возвращаемого признака «нераспознанная команда». Получив _RESMGR_DEFAULT, базовый уровень библиотеки ответит установкой errno в значение ENOSYS, которое будет транслировано клиентской библиотечной функцией devctl() в значение ENOTTY, «корректное» с точки зрения POSIX.

Проверка режима открытия и сопоставление его с выполняемой операцией лежит всецело на совести вашей функции — ни в клиентской devctl(), ни в библиотеке администратора ресурсов никаких проверок не выполняется. Например, можно открыть администратор ресурса в режиме «только для чтения», а затем выдать ему посредством devctl() команду «отформатировать жесткий диск» (которая, в общем, является весьма нехилой операцией записи). Так вот, с точки зрения администратора было бы весьма предусмотрительно до выполнения такой операции сначала проверить режим открытия ресурса.

Отметим, что диапазон доступных пользователю значений dcmd ограничен (значения от 0x0000 до 0x0FFF включительно зарезервированы QSSL). Другие значения можно смело использовать — см. заголовочные файлы с именами <sys/dcmd_*.h>.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS, и буфер приема (с ответными данными, если надо).

Для примера см. ниже параграф «Простой пример функции io_devctl()».

io_dup()

int io_dup(resmgr_context_t *ctp, io_dup_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: NULL (обрабатывается базовым уровнем)

Вспомогательные функции: Нет

Клиентская функция: dup(), dup2(), fcntl(), fork(), spawn*(), fork()

Сообщения: _IO_DUP

Структура данных:

struct _io_dup {

 uint16_t         type;

 uint16_t         combine_len;

 struct _msg_info info;

 uint32_t         reserved;

 uint32_t         key;

};

typedef union {

 struct _io_dup i;

} io_dup_t;

Описание: Это обработчик сообщений dup(). Как и в случае с io_close_dup(), вы вряд ли будете обрабатывать это сообщение самостоятельно. За вас это сделает базовый уровень библиотеки.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_fdinfo()

int io_fdinfo(resmgr_context_t *ctp, io_fdinfo_t *msg,

 RESMGR_OCB_T *ocb)

Данная функция зарезервирована QSSL для будущего использования. Вам следует инициализировать таблицу функций ввода/вывода при помощи iofunc_func_init() и не изменять данную точку входа.

io_link()

int io_link(resmgr_context_t *ctp, io_link_t *msg,

 RESMGR_HANDLE_T* handle, io_link_extra_t* extra)

Классификация: Функция установления соединения

Обработчик по умолчанию: Нет

Вспомогательные функции: iofunc_link()

Клиентская функция: link()

Сообщения: _IO_CONNECT, подтип IO_CONNECT_LINK

Структура данных:

struct _io_connect {

 // Внутренние поля (как описано выше)

 uint16_t path_len;

 uint8_t  extra_type;

 uint16_t extra_len;

 char     path[1];

};

struct _io_connect_link_reply {

 uint32_t reserved1[2];

 uint8_t  eflag;

 uint8_t  reserved2[3];

 uint32_t umask;

 uint16_t nentries;

 uint16_t path_len;

};

typedef union {

 struct _io_connect            connect;

 struct _io_connect_link_reply link_reply;

} io_link_t;

typedef union _io_link_extra {

 struct _msg_info             info;

 void                         *ocb;

 char                         path[1];

 struct _io_resmgr_link_extra resmgr;

} io_link_extra_t;

Описание: Создает новую связь (линк) с именем, заданным в поле path структуры msg, к уже существующему имени пути, указанному в поле path параметра extra (переданного вашей функции). Для удобства поле ocb параметра extra содержит указатель на OCB существующего имени пути.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_lock()

int io_lock(resmgr_context_t *ctp, io_lock_t *msg,

 RESMGR_OCB_T *ocb)

Данная функция зарезервирована QSSL для будущего использования. Вам следует инициализировать таблицу функций ввода/вывода, используя iofunc_func_init(), и не изменять данную точку входа.

io_lock_ocb()

int io_lock_ocb(resmgr_context_t *ctp, void *reserved,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода (синтезируется библиотекой)

Обработчик по умолчанию: iofunc_lock_ocb_default()

Вспомогательные функции: Нет

Клиентская функция: Все

Сообщения: Нет (синтезируются библиотекой)

Структура данных: Нет

Описание: Эта функция отвечает за блокировку атрибутной записи, на которую указывает OCB. Это сделано для того, чтобы гарантировать одновременный доступ не более одного потока как к самому OCB, так и к соответствующей атрибутной записи. Функции блокировки (и соответствующие функции разблокировки) синтезируются библиотекой администратора ресурсов до начала обработки сообщения и после ее завершения соответственно. Более подробно это описано выше в параграфе «Составные сообщения». Вы почти никогда не будете использовать этот вызов самостоятельно; вместо этого используйте функцию POSIX-уровня по умолчанию.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_lseek()

int io_lseek(resmgr_context_t *ctp, io_lseek_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_lseek_default()

Вспомогательные функции: iofunc_lseek()

Клиентская функции: lseek(), fseek(), rewinddir()

Сообщения: _IO_LSEEK

Структура данных:

struct _io_lseek {

 uint16_t type;

 uint16_t combine_len;

 short    whence;

 uint16_t zero;

 uint64_t offset;

};

typedef union {

 struct _io_lseek i;

 uint64_t         o;

} io_lseek_t;

Описание: Обрабатывает клиентскую функцию lseek(). Отметьте, что администратору ресурса, который обрабатывает каталоги, придется также интерпретировать сообщение _IO_LSEEK для операций с каталогами. Параметры whence и offset передаются от клиентской функции lseek(). После интерпретации параметров whence и offset клиентского сообщения подпрограмма должна скорректировать у OCB параметр offset и затем возвратить новое значение offset или возвратить признак ошибки.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS, а также (не обязательно) текущее смещение.

io_mknod()

int io_mknod(resmgr_context_t *ctp, io_mknod_t *msg,

 RESMGR_HANDLE_T *handle, void *reserved)

Классификация: Функция установления соединения

Обработчик по умолчанию: Нет

Вспомогательные функции: iofunc_mknod()

Клиентская функция: mknod(), mkdir(), mkfifo()

Сообщения: _IO_CONNECT, подтип _IO_CONNECT_MKNOD

Структура данных:

struct _io_connect {

 // Внутренние поля (как описано выше)

 uint16_t path_len;

 uint8_t  extra_type;

 uint16_t extra_len;

 char     path[1];

};

struct _io_connect_link_reply {

 uint32_t reserved1[2];

 uint8_t  eflag;

 uint8_t  reserved2[3];

 uint32_t umask;

 uint16_t nentries;

 uint16_t path_len;

};

typedef union {

 struct _io_connect            connect;

 struct _io_connect_link_reply link_reply;

} io_mknod_t;

Описание: Создает новую точку входа в файловую систему. Сообщение выдается для создания файла с именем, указанным в path, и типом, закодированным в поле mode (оно из «внутренних полей» структуры struct _io_connect и здесь не показано).

Реально это используется только для клиентских функций mkfifo() и mkdir().

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_mmap()

int io_mmap(resmgr_context_t *ctp, io_mmap_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_mmap_default()

Вспомогательные функции: iofunc_mmap()

Клиентская функция: mmap(), munmap(), mmap_device_io(), mmap_device_memory()

Сообщения: _IO_MMAP

Структура данных:

struct _io_mmap {

 uint16_t         type;

 uint16_t         combine_len;

 uint32_t         prot;

 uint64_t         offset;

 struct _msg_info info;

 uint32_t         zero[6];

};

struct _io_mmap_reply {

 uint32_t zero;

 uint32_t flags;

 uint64_t offset;

 int32_t  coid;

 int32_t  fd;

};

typedef union {

struct _io_mmap       i;

struct _io_mmap_reply o;

} io_mmap_t;

Описание: Позволяет администратору процессов применять к файлам вашего администратора ресурсов операцию mmap(). В общем случае самостоятельно программировать эту функцию не следует (используйте обработчик по умолчанию, предоставляемый iofunc_func_init()), если только вы не хотите ее преднамеренно отключить (например, драйвер последовательного порта мог бы запросто возвратить ENOSYS, поэтому для него эта операция не имеет никакого смысла).

Данную функцию администратора ресурсов может вызвать только администратор процессов

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

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_mount()

int io_mount(resmgr_context_t *ctp, io_mount_t *msg,

 RESMGR_HANDLE_T* handle, io_mount_extra_t* extra)

Данная функция зарезервирована QSSL для будущего использования. Вам следует инициализировать таблицу функций ввода/вывода, используя iofunc_func_init(), и не изменять данную точку входа.

io_msg()

int io_msg(resmgr_context_t *ctp, io_msg_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: Нет

Вспомогательные функции: Нет

Клиентская функция: Нет (создается «вручную» и передается посредством MsgSend())

Сообщения: _IO_MSG

Структура данных:

struct _io_msg {

 uint16_t type;

 uint16_t combine_len;

 uint16_t mgrid;

 uint16_t subtype;

};

typedef union {

 struct _io_msg i;

} io_msg_t;

Описание: Интерфейс _IO_MSG является более общей, но менее переносимой вариацией на тему ioctl() и devctl(). Поле mgrid идентифицирует конкретный администратор — вы не должны выполнять никаких действий по запросам, не соответствующим идентификатору вашего администратора. Поле subtype фактически задает команду, которую клиент хочет выполнить. Любые неявно передаваемые данные следуют за входной структурой. Данные, возвращаемые клиенту, передаются сами по себе; код завершения возвращается через макрос _RESMGR_STATUS. Уникальный «идентификатор администратора» (manager ID) вы можете получить в QSSL.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_notify()

int io_notify(resmgr_context_t *ctp, io_notify_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: Нет

Вспомогательные функции: iofunc_notify(), iofunc_notify_remove(), iofunc_notify_trigger()

Клиентская функция: select(), ionotify()

Сообщения: _IO_NOTIFY

Структура данных:

struct _io_notify {

 uint16_t        type;

 uint16_t        combine_len;

 int32_t         action;

 int32_t         flags;

 struct sigevent event;

};

struct _io_notify_reply {

 uint32_t zero;

 uint32_t flags;

};

typedef union {

 struct _io_notify       i;

 struct _io_notify_reply o;

} io_notify_t;

Описание: Данный обработчик отвечает за установку, опрос или удаление обработчика уведомлений. Параметры action (действие) и flags (флаги) определяют тип операции уведомления и условия; параметр event (событие) является структурой типа struct sigevent, которая определяет событие уведомления (если оно есть), которое клиент хочет получить. Событие event клиенту доставляется функцией MsgDeliverEvent() или функцией iofunc_notify_trigger().

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS; флаги возвращается ответным сообщением.

io_open()

int io_open(resmgr_context_t *ctp, io_open_t *msg,

 RESMGR_HANDLE_T *handle, void *extra)

Классификация: Функция установления соединения

Обработчик по умолчанию: iofunc_open_default()

Вспомогательные функции: iofunc_open(), iofunc_ocb_attach()

Клиентская функция: open(), fopen(), sopen() и др.

Сообщения: _IO_CONNECT, подтипы _IO_CONNECT_COMBINE, _IO_CONNECT_COMBINE_CLOSE и _IO_CONNECT_OPEN.

Структура данных:

struct _io_connect {

 // Внутренние поля (как описано выше)

 uint16_t path_len;

 uint8_t  extra_type;

 uint16_t extra_len;

 char     path[1];

};

struct _io_connect_link_reply {

 uint32_t reserved1[2];

 uint8_t  eflag;

 uint8_t  reserved2[3];

 uint32_t umask;

 uint16_t nentries;

 uint16_t path_len;

};

typedef union {

 struct _io_connect            connect;

 struct _io_connect_link_reply link_reply;

} io_open_t;

Описание: Это основная точка входа в администратор ресурсов. Она выполняет проверку, действительно ли клиент имеет соответствующие права на открытие файла, привязывает OCB к внутренним структурам библиотеки (посредством функций resmgr_bind_ocb() или iofunc_ocb_attach()) и возвращает errno. Отметим, что для данной функции релевантны не все поля структур ввода и вывода.

Возвращает: Код завершения, при помощи вспомогательного макроса _IO_SET_CONNECT_RET.

io_openfd()

int io_openfd(resmgx_context_t *ctp, io_openfd_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_openfd_default()

Вспомогательные функции: iofunc_openfd()

Клиентская функция: openfd()

Сообщения: _IO_OPENFD

Структура данных:

struct _io_openfd {

 uint16_t         type;

 uint16_t         combine_len;

 uint32_t         ioflag;

 uint16_t         sflag;

 uint16_t         reserved1;

 struct _msg_info info;

 uint32_t         reserved2;

 uint32_t         key;

};

typedef union {

 struct _io_openfd i;

} io_openfd_t;

Описание: Данная функция аналогична предоставляемому обработчику io_open() — за исключением того, что вместо имени пути передается дескриптор уже открытого файла (в силу передачи вам параметра ocb в вызове функции).

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_pathconf()

int io_pathconf(resmgr_context_t *ctp, io_pathconf_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_pathconf_default()

Вспомогательные функции: iofunc_pathconf()

Клиентская функция: fpathconf(), pathconf()

Сообщения: IO_PATHCONF

Структура данных:

struct _io_pathconf {

 uint16_t type;

 uint16_t combine_len;

 short    name;

 uint16_t zero;

};

typedef union {

 struct _io_pathconf i;

] io_pathconf_t;

Описание: Обработчик этого сообщения отвечает за возврат значения настраиваемого параметра name для ресурса, связанного с данным OCB. Используйте функцию по умолчанию и расширьте ее дополнительными вариантами элемента name, соответствующими вашему устройству.

Возвращает: Код завершения, при помощи вспомогательного макроса _IO_SET_PATHCONF_VALUE; флаги возвращаются в ответном сообщении.

io_read()

int io_read(resmgr_context_t *ctp, io_read_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_read_default()

Вспомогательные функции: iofunc_read(), iofunc_read_verify()

Клиентская функция: read(), readdir()

Сообщение: IO_READ

Структура данных:

struct _io_read {

 uint16_t type;

 uint16_t combine_len;

 int32_t  nbytes;

 uint32_t xtype;

};

typedef union {

 struct _io_read i;

} io_read_t;

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

Отметим, что элемент xtype может устанавливать для отдельных сообщений флаг переопределения, поэтому его надо проверять. Если вы не поддерживаете никаких расширенных флагов переопределения, вы должны возвратить EINVAL. Далее, в примерах функций io_read() и io_write(), мы рассмотрим обработку одного очень важного (и очень непростого!) флага переопределения, называемого _IO_XTYPE_OFFSET.

Отметим также, что сообщение _IO_READ приходит не только для обычных файлов, но также и для чтения содержимого каталогов. В варианте с каталогом вы должны гарантированно обеспечить возврат целого (integral) числа элементов struct dirent. За дополнительной информацией по возврату элементов каталога см. пример в параграфе «Возврат элементов каталога» раздела «Дополнительно».

Чтобы удостовериться, что файл был открыт в режиме, совместимом с операцией чтения, надо вызвать вспомогательную функцию iofunc_read_verify(). Также, следует вызвать функцию iofunc_sync_verify(), чтобы проверить, надо ли синхронизировать данные с носителем.

Возвращает: Число считанных байтов или код завершения, при помощи вспомогательного макроса _IO_SET_READ_NBYTES, а также собственно данные — ответным сообщением.

В качестве примера с возвратом только данных см. ниже раздел «Простой пример функции io_read()». Более сложный пример с одновременным возвратом как данных, так и элементов каталогов, см. в параграфе «Возврат элементов каталога» раздела «Дополнительно».

io_readlink()

int io_readlink(resmgr_context_t *ctp, io_readlink_t *msg,

 RESMGR_HANDLE_T *handle, void* reserved)

Классификация: Функция установления соединения

Обработчик по умолчанию: Нет

Вспомогательные функции: iofunc_readlink()

Клиентская функция: readlink()

Сообщения: IO_CONNECT, подтип IO_CONNECT_READLINK

Структура данных:

struct _io_connect {

 // Внутренние поля (как описано выше)

 uint16_t path_len;

 uint8_t  extra_type;

 uint16_t extra_len;

 char     path[1];

};

struct _io_connect_link_reply {

 uint32_t reserved1[2];

 uint8_t  eflag;

 uint8_t  reserved2[3];

 uint32_t umask;

 uint16_t nentries;

 uint16_t path_len;

};

typedef union {

 struct _io_connect            connect;

 struct _io_connect_link_reply link_reply;

} io_open_t;

Описание: Отвечает за чтение содержимого символьной связи (линка), как определено полем path входной структуры. Возвращаемые байты представляют собой содержимое символьной связи; возвращаемый код состояния представляет собой число байт в ответе. Допустимый возврат должен быть сделано только для символьной связи. Все другие доступы должны возвратить код ошибки.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS, и данные в ответном сообщении.

io_rename()

int io_rename(resmgr_context_t *ctp, io_rename_t *msg,

 RESMGR_HANDLE_T *handle, io_rename_extra_t* extra)

Классификация: Функция установления соединения

Обработчик по умолчанию: Нет

Вспомогательные функции: iofunc_rename()

Клиентская функция: rename()

Сообщение: _IO_CONNECT, подтип _IO_CONNECT_RENAME

Структура данных:

struct _io_connect {

 // internal fields (as described above)

 uint16_t path_len;

 uint8_t  extra_type;

 uint16_t extra_len;

 char     path[1];

};

struct _io_connect_link_reply {

 uint32_t reserved1[2];

 uint8_t  eflag;

 uint8_t  reserved2[3];

 uint32_t umask;

 uint16_t nentries;

 uint16_t path_len;

};

typedef union _io_rename_extra {

 char path[1];

} io_rename_extra_t;

typedef union {

 struct _io_connect            connect;

 struct _io_connect_link_reply link_reply;

} io_rename_t;

Описание: Выполняет операцию переименования, получив на вход первоначальное имя в элементе path и новое имя в поле path переданного параметра extra. Замечание по реализации: для первоначального имени задается имя пути (а не OCB) — это делается специально для случая переименования файла, который является жесткой связью к другому файлу. Если бы был задан OCB, две (или более) жестких связей к одному и тому же файлу различить было бы нельзя.

Данная функция будет вызываться только для тех двух имен файлов, которые принадлежат одной и той же файловой системе (то есть одному и тому же устройству). Поэтому в проверке случаев, в которых надо было бы возвращать EXDEV, нет никакой необходимости. Это ничуть не мешает вам возвращать EXDEV — например, если вы не хотите выполнять rename() самостоятельно (например, операция переименования из одного каталога в другой может оказаться очень сложной). В случае возврата EXDEV командно-строковая утилита mv выполнит сначала cp, а потом rm (библиотечная функция rename() этого не сделает — она просто установит errno в EXDEV).

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

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_shutdown()

int io_shutdown(resmgr_context_t *ctp, io_shutdown_t *msg,

 RESMGR_OCB_T *ocb)

Данная функция зарезервирована QSSL для будущего использования. Вам следует инициализировать таблицу функций ввода/вывода, используя iofunc_func_init(), и не изменять данную точку входа.

io_space()

int io_space(resmgr_context_t *ctp, io_space_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: Нет

Вспомогательные функции: iofunc_space_verify()

Клиентская функция: chsize(), fcntl(), ftruncate(), ltrunc()

Сообщение _IO_SPACE

Структура данных:

struct _io_space {

 uint16_t type;

 uint16_t combine_len;

 uint16_t subtype;

 short    whence;

 uint64_t start;

 uint64_t len;

};

typedef union {

 struct _io_space i;

 uint64_t         o;

} io_space_t;

Описание: Эта функция применяется для выделения или освобождения занимаемого ресурсом пространства. Параметр subtype («подтип») указывает на то, следует ли это пространство выделить (если равен F_ALLOCSP) или освободить (если равен F_FREESP). Комбинация параметров whence («откуда») и start («начало») указывает, где следует начать выделение/ освобождение; элемент len указывает размер операции.

Возвращает: Число байтов (размер ресурса), посредством вспомогательного макроса _RESMGR_STATUS.

io_stat()

int io_stat(resmgr_context_t *ctp, io_stat_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_stat_default()

Вспомогательные функции: iofunc_stat()

Клиентская функция: stat(), lstat(), fstat()

Сообщения: _IO_STAT

Структура данных:

struct _io_stat {

 uint16_t type;

 uint16_t combine_len;

 uint32_t zero;

};

typedef union (

 struct _io_stat i;

 struct stat     o;

} io_stat_t;

Описание: Обрабатывает сообщение, запрашивающее информацию о ресурсе, связанном с переданным OCB. Заметьте, что атрибутная запись содержит всю информацию, необходимую для выполнения запроса stat(). Вспомогательная функция iofunc_stat() заполняет структуру struct stat, базированную на атрибутной записи. Эта вспомогательная функция также изменяет сохраненные элементы dev/rdev так, чтобы они были уникальны с точки зрения единичного узла (это используется для выполнения вызовов stat() в отношении файлов по сети). Писать этот обработчик самостоятельно особого смысла нет.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS, и структуру struct stat — в ответном сообщении.

io_sync()

int io_sync(resmgr_context_t *ctp, io_sync_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_sync_default()

Вспомогательные функции: iofunc_sync_verify(), iofunc_sync()

Клиентская функция: fsync(), fdatasync()

Сообщения: _IO_SYNC

Структура данных:

struct _io_sync {

 uint16_t type;

 uint16_t сombine_len;

 uint32_t flag;

};

typedef union {

 struct _io_sync i;

} io_sync_t;

Описание: Это точка входа команды flush (синхронизация носителя информации с буферами — например, диска с дисковым кэшем — прим. ред.). Вспомогательная функция iofunc_sync() принимает поле flag входного сообщения и возвращает одно из следующих значений, которые указывают, какие действия ваш администратор ресурсов должен выполнить:

• 0 — не делать ничего;

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

• O_DSYNC — присутствовать на носителе и быть восстанавливаемыми с него должны только данные файла.

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

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_umount()

int io_umount(resmgr_context_t *ctp, void *msg,

 RESMGR_OCB_T *ocb)

Данная функция зарезервирована QSSL для будущего использования. Вам следует инициализировать таблицу функций ввода/вывода, используя iofunc_func_init(), и не изменять данную точку входа.

io_unblock() [установление соединения]

int io_unblock(resmgr_context_t *ctp, io_pulse_t *msg,

 RESMGR_HANDLE_T *handle, void* reserved)

Классификация: Функция установления соединения (синтезируется ядром и библиотекой)

Обработчик по умолчанию: Нет

Вспомогательные функции: iofunc_unblock()

Клиентская функция: Нет (вызывается ядром вследствие сигнала или тайм-аута)

Сообщения: Нет (синтезируется библиотекой)

Структура данных: (см. вариант io_unblock() для ввода/вывода, ниже)

Описание: Это версия разблокирующего вызова в форме сообщения установления соединения, синтезируемая библиотекой в ответ на импульс от ядра, возникший в результате желания клиента разблокироваться на этапе установления соединения. См. вариант этой функции для ввода/вывода ниже.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

См. подробное обсуждение стратегий разблокирования в главе «Обмен сообщениями», параграф «Применение флага _NTO_MI_UNBLOCK_REQ».

io_unblock() [ввод/вывод]

int io_unblock(resmgr_context_t *ctp, io_pulse_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода (синтезируется ядром и библиотекой)

Обработчик по умолчанию: iofunc_unblock_default()

Вспомогательные функции: iofunc_unblock()

Клиентская функция: Нет (реакция ядра на сигнал или тайм-аут)

Сообщения: Нет (синтезируется библиотекой)

Структура данных: указательна структуру, содержащую прерываемое сообщение

Описание: Это версия разблокирующего вызова для сообщения ввода/вывода, синтезируемая библиотекой в результате импульса от ядра, возникшего вследствие попытки клиента разблокироваться на этапе ввода/вывода. Обработчик io_unblock() для фазы установления соединения почти аналогичен (см. предыдущий параграф).

Общим для обеих обработчиков разблокировки (как для функций установления соединения, так и для функций ввода/вывода) является желание клиента разблокироваться с разрешения администратора ресурсов. Администратор ресурсов обязан ответить на клиентское сообщение, чтобы разблокировать клиента. (Мы это обсуждали в главе «Обмен сообщениями», когда говорили о флагах функции ChannelCreate() — в частности, о флаге _NTO_CHF_UNBLOCK).

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

Подробное обсуждение стратегий разблокирования см. в разделе «Применение флага _NTO_MI_UNBLOCK_REQ» в главе «Обмен сообщениями».

io_unlink()

int io_unlink(resmgr_context_t *ctp, io_unlink_t *msg,

 RESMGR_HANDLE_T* handle, void* reserved)

Классификация: Функция установления соединения

Обработчик по умолчанию: Нет

Вспомогательные функции: iofunc_unlink()

Клиентская функция: unlink()

Сообщение: _IO_CONNECT, подтип _IO_CONNECT_UNLINK

Структура данных:

struct _io_connect {

 // Внутренние поля (как описано выше)

 uint16_t path_len;

 uint8_t  extra_type;

 uint16_t extra_len;

 char     path[1];

};

struct _io_connect_link_reply {

 uint32_t reserved1[2];

 uint8_t  eflag;

 uint8_t  reserved2[3];

 uint32_t umask;

 uint16_t nentries;

 uint16_t path_len;

};

typedef union {

 struct _io_connect            connect;

 struct _io_connect_link_reply link_reply;

} io_unlink_t;

Описание: Отвечает за уничтожение связей (unlinking) файла, имя пути которого передается в поле path структуры входящего сообщения.

Возвращает: Состояние по применению вспомогательного макроса _RESMGR_STATUS.

io_unlock_ocb()

int io_unlock_ocb(resmgr_context_t *ctp, void *reserved,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода (синтезируется библиотекой)

Обработчик по умолчанию: iofunc_unlock_ocb_default()

Вспомогательные функции: Нет

Клиентская функция: Все

Сообщения: Нет (синтезируется библиотекой)

Структура данных: Нет

Описание: Действует противоположно вышеописанной функции io_lock_ocb(), т.е. отвечает за разблокирование атрибутной записи, на которую указывает OCB. Эта операция освобождает атрибутную запись, чтобы другие администратора ресурсов могли с ней работать. Подробности см. выше в разделе «Составные сообщения».

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_utime()

int io_utime(resmgr_context_t *ctp, io_utime_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_utime_default()

Вспомогательные функции: iofunc_utime()

Клиентская функция: utime()

Сообщения: _IO_UTIME

Структура данных:

struct _io_utime {

 uint16_t       type;

 uint16_t       combine_len;

 int32_t        cur_flag;

 struct utimbuf times;

};

typedef union {

 struct _io_utime i;

} io_utime_t;

Описание: Устанавливает времена последнего доступа и модификации либо в «текущий момент» (если они равны нулю), либо в заданные значения. Заметьте, что согласно правилам POSIX этот обработчик сообщения может быть необходим для модификации флагов IOFUNC_ATTR_* в атрибутной записи. Вам почти никогда не придется самостоятельно использовать этот обработчик; вместо этого вы будете использовать вспомогательную функцию POSIX-уровня.

Возвращает: Код завершения, при помощи вспомогательного макроса _RESMGR_STATUS.

io_write()

int io_write(resmgr_context_t *ctp, io_write_t *msg,

 RESMGR_OCB_T *ocb)

Классификация: Функция ввода/вывода

Обработчик по умолчанию: iofunc_write_default()

Вспомогательные функции: iofunc_write_verify()

Клиентская функция: write(), fwrite(), и т.п.

Сообщения: _IO_WRITE

Структура данных:

struct _io_write {

 uint16_t type;

 uint16_t combine_len;

 int32_t  nbytes;

 uint32_t xtype;

};

typedef union {

 struct _io_write i;

} io_write_t;

Описание: Данный обработчик отвечает за получение данных, которые клиент записал в администратор ресурсов. Обработчику передается число байт, которые клиент пытается записать, в элементе nbytes; данные неявно следуют за входной структурой (если параметр xtype не установлен в _IO_XTYPE_OFFSET; см. ниже параграф «Простой пример функции io_write()»!). Согласно реализации, потребуется повторное считывание от клиента части сообщения с данными при помощи функции resmgr_msgreadv() или ей эквивалентной. Код завершения дает число байт, фактически записанных, либо устанавливает признак ошибки в errno.

Отметьте, что чтобы удостовериться, что файл был открыт в режиме, совместимом с записью, следует вызвать вспомогательную функцию iofunc_write_verify(). Также следует вызывать функцию iofunc_sync_verify() для проверки необходимости синхронизации данных с носителем.

Возвращает: Код завершения, при помощи вспомогательного макроса _IO_SET_WRITE_NBYTES.

Пример см. ниже в параграфе «Простой пример функции io_write()».