ИМЯ¶

xdr - библиотечные процедуры для внешнего представления данных

LIBRARY¶

Standard C library (libc, -lc)

ОБЗОР И ОПИСАНИЕ¶

Эти процедуры позволяют программистам на C описывать произвольные структуры данных машинонезависимым способом. Данные для дистанционного вызова процедур передаются с помощью этих процедур.

Представленные ниже прототипы объявлены в <rpc/xdr.h> и позволяют использовать следующие типы:

typedef int bool_t;

typedef bool_t (*xdrproc_t)(XDR *, void *,...);

Объявление типа XDR приведено в <rpc/xdr.h>.

bool_t xdr_array(XDR *xdrs, char **arrp, unsigned int *sizep,
                 unsigned int maxsize, unsigned int elsize,
                 xdrproc_t elproc);

Фильтр-примитив, преобразует массивы переменной длины в соответствующее им внешнее представление (и наоборот). В параметре arrp указывается адрес указателя на массив, а в sizep адрес счётчика элементов в массиве; этот счётчик не может превышать значение maxsize. В параметре elsize указывается sizeof каждого из элементов массива, а в elproc указывается фильтр XDR, который преобразует массив элементов формата С в их внешнее представление (и наоборот). Процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_bool(XDR *xdrs, bool_t *bp);

Фильтр-примитив, преобразует логические переменные (целочисленные в С) в их внешнее представление (и наоборот). Перекодируя данные, этот фильтр выдает либо единицу, либо ноль. Процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_bytes(XDR *xdrs, char **sp, unsigned int *sizep,
                 unsigned int maxsize);

Фильтр-примитив, преобразует строки с известной длиной в их внешнее представление (и наоборот). В аргументе sp указывается адрес указателя строки. Длина строки указывается по адресу sizep; строки не могут быть длиннее maxsize. Процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_char(XDR *xdrs, char *cp);

A filter primitive that translates between C characters and their external representations. This routine returns one if it succeeds, zero otherwise. Note: encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider xdr_bytes(), xdr_opaque(), or xdr_string().

void xdr_destroy(XDR *xdrs);

Макрос, который запускает процедуру уничтожения, связанную с потоком XDR xdrs. Уничтожение обычно включает в себя освобождение структур частных данных, связанных с потоком. Результат использования xdrs после запуска xdr_destroy() непредсказуем.

bool_t xdr_double(XDR *xdrs, double *dp);

Фильтр-примитив, преобразует значение чисел с точностью типа double языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_enum(XDR *xdrs, enum_t *ep);

Фильтр-примитив, преобразует значения типа enum (представляющие собой целые числа) языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_float(XDR *xdrs, float *fp);

Фильтр-примитив, преобразует значения типа float языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

void xdr_free(xdrproc_t proc, char *objp);

Общая процедура высвобождения. Первым параметром для освобождаемого объекта является процедура XDR. Вторым параметром является указатель на сам объект. Замечание: указатель, переданный этой программе, не освобождается, освобождается (рекурсивно) объект, на который он указывает.

unsigned int xdr_getpos(XDR *xdrs);

Макрос, который запускает процедуру получения позиции, связанной с потоком XDR xdrs. Процедура возвращает беззнаковое целое, которое указывает на позицию XDR потока байтов. Удобное свойство потока XDR: с этим числом можно выполнять простые арифметические действия, хотя экземплярам потоков XDR этого можно не гарантировать.

long *xdr_inline(XDR *xdrs, int len);

Макрос, который запускает встроенную процедуру, связанную с потоком XDR xdrs. Процедура возвращает указатель на непрерывную часть буфера потока; в len задаётся длина нужного буфера в байтах. Замечание: указатель приводится к long *.

Предупреждение: xdr_inline() может возвратить NULL (0), если не сможет выделить непрерывную часть буфера. Следовательно, поведение может меняться в разных экземплярах потока; вообще, она предназначена для обеспечения общей эффективности работы.

bool_t xdr_int(XDR *xdrs, int *ip);

Фильтр-примитив, преобразует значения целого типа языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_long(XDR *xdrs, long *lp);

Фильтр-примитив, преобразует значения типа long языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

void xdrmem_create(XDR *xdrs, char *addr, unsigned int size,
                   enum xdr_op op);

Эта процедура инициализирует объект потока XDR, на который указывает xdrs. Данные потока считываются из куска памяти или записываются в него с позиции addr, длина которого не больше size байтов. В op указывается направление потока XDR (XDR_ENCODE, XDR_DECODE или XDR_FREE).

bool_t xdr_opaque(XDR *xdrs, char *cp, unsigned int cnt);

Фильтр-примитив, преобразует значения типа со скрытым форматом фиксированного размера(«чёрным ящиком») в их внешнее представление и наоборот. В аргументе cp указывает адрес с «чёрным ящиком», а в cnt указывается его размер в байтах. Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_pointer(XDR *xdrs, char **objpp,
                   unsigned int objsize, xdrproc_t xdrobj);

Работает аналогично xdr_reference(), за исключением того, что может обрабатывать указатели null, в отличие от xdr_reference(). Таким образом, xdr_pointer() может представлять рекурсивные структуры данных, например, двоичные деревья или связанные списки.

void xdrrec_create(XDR *xdrs, unsigned int sendsize,
                   unsigned int recvsize, char *handle,
                   int (*readit)(char *, char *, int),
                   int (*writeit)(char *, char *, int));

Эта процедура инициализирует объект потока XDR, на который указывает xdrs. Данные потока записываются в буфер размером sendsize; значение ноль указывает на то, что система должна использовать значение, подходящее по умолчанию. Данные потока считываются из буфера размером recvsize; его размер также может быть равно нулю, что указывает на значение, подходящее по умолчанию. Когда буфер записи потока заполнен, вызывается writeit. Аналогично этому, когда буфер чтения потока пуст, вызывается readit. Поведение этих двух процедур аналогично системным вызовам read(2) и write(2), исключая то, что handle передается вызывающей процедуре в качестве первого параметра. Замечание: у потока XDR поле op должно быть установлено вызывающим.

Предупреждение: для чтения из потока XDR, созданного данным программным интерфейсом, самым первым должен быть вызов xdrrec_skiprecord(). Это вставит дополнительные байты в поток для предоставления информации о границе записи. Также, потоки XDR, созданные разными программными интерфейсами xdr*_create, не совместимы по той же причине.

bool_t xdrrec_endofrecord(XDR *xdrs, int sendnow);

Эта процедура может запускаться только для потоков, созданных xdrrec_create(). Данные в буфере вывода помечены как полная запись; буфер вывода также записывается, если параметр sendnow не равен нулю. Эта процедура возвращает 1 при успешном завершении работы, иначе возвращается 0.

bool_t xdrrec_eof(XDR *xdrs);

Эта процедура может запускаться только для потоков, созданных xdrrec_create(). После поглощения остатка текущей записи в потоке процедура возвращает 1, если на входе потока нет больше данных; иначе возвращается 0.

bool_t xdrrec_skiprecord(XDR *xdrs);

Эта процедура может запускаться только для потоков, созданных xdrrec_create(). Она сообщает реализации XDR, что оставшаяся часть текущей записи в буфере ввода потока должна быть отброшена. Эта процедура возвращает 1 при успешном завершении работы, иначе возвращается 0.

bool_t xdr_reference(XDR *xdrs, char **pp, unsigned int size,
                     xdrproc_t proc);

Примитив, обеспечивающий курсирование указателя по структурам. В аргументе pp указывается адрес указателя; size задаётся в виде sizeof структуры, на которую указывает *pp; в proc указывается процедура XDR, которая преобразует структуру языка С в её внешнее представление. Программа возвращает 1 при успешном завершении работы, иначе возвращается 0.

Предупреждение: эта процедура не работает с указателями null. Используйте вместо неё xdr_pointer().

xdr_setpos(XDR *xdrs, unsigned int pos);

Макрос, вызываемый для установки позиции процедуры, связанной с потоком XDR xdrs. В аргументе pos задаётся значение позиции, полученное с помощью xdr_getpos(). Эта процедура возвращает 1, если по потоку XDR можно перемещаться, иначе возвращается 0.

Предупреждение: очень трудно изменить положение некоторых типов потока XDR, так что эта процедура может не работать с одним типом потока, но успешно работать с другим.

bool_t xdr_short(XDR *xdrs, short *sp);

Фильтр-примитив, преобразует значения типа short языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

void xdrstdio_create(XDR *xdrs, FILE *file, enum xdr_op op);

Эта процедура инициализирует объект потока XDR, на который указывает xdrs. Данные потока XDR записываются или считываются из stdio потока, указанного в file. В op указывается направление потока XDR (XDR_ENCODE, XDR_DECODE или XDR_FREE).

Предупреждение: процедура уничтожения, связанная с такими потоками XDR, вызывает fflush(3) для потока file, но не вызывает fclose(3).

bool_t xdr_string(XDR *xdrs, char **sp, unsigned int maxsize);

Фильтр-примитив, преобразует значения строк языка C в их внешнее представление (и наоборот). Длина строк не может быть больше чем maxsize. Замечание: значение sp представляет собой адрес на указатель строки. Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_u_char(XDR *xdrs, unsigned char *ucp);

Фильтр-примитив, преобразует unsigned символы языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_u_int(XDR *xdrs, unsigned int *up);

Фильтр-примитив, преобразует беззнаковые целые языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);

Фильтр-примитив, преобразует целые unsigned long языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);

Фильтр-примитив, преобразует значения типа unsigned short языка C в их внешнее представление (и наоборот). Эта процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_union(XDR *xdrs, enum_t *dscmp, char *unp,
                 const struct xdr_discrim *choices,
                 xdrproc_t defaultarm);     /* may equal NULL */

Фильтр-примитив, преобразует различимые (discriminated) объединения языка C в их внешнее представление (и наоборот). Сначала преобразуется дискриминант объединения, расположенный в dscmp. Этот дискриминант всегда имеет тип enum_t. Затем преобразуется объединение, расположенное в unp. Параметр choices представляет собой указатель на массив структур xdr_discrim(). Каждая структура содержит упорядоченную пару [значение,процедура]. Если дискриминант объединения равен соответствующему значению, то для преобразования объединения вызывается процедура. Конец массива структур xdr_discrim() обозначается процедурой со значением NULL. Если дискриминант не найден в массиве choices, то вызывается процедура defaultarm (если данное значение не равно NULL). Возвращает 1 при успешном завершении работы, иначе возвращается 0.

bool_t xdr_vector(XDR *xdrs, char *arrp, unsigned int size,
                  unsigned int elsize, xdrproc_t elproc);

Фильтр-примитив, преобразует массивы постоянной длины в соответствующее им внешнее представление (и наоборот). В параметре arrp указывается адрес указателя на массив, а в size — адрес счётчика элементов в массиве. В параметре elsize указывается sizeof каждого из элементов массива, а в elproc указывается фильтр XDR, который преобразует массив элементов формата С в их внешнее представление (и наоборот). Процедура возвращает 1 при успешном выполнении работы, иначе 0.

bool_t xdr_void(void);

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

bool_t xdr_wrapstring(XDR *xdrs, char **sp);

Примитив, вызывающий xdr_string(xdrs, sp, MAXUN.UNSIGNED); где MAXUN.UNSIGNED равно максимальному значению беззнакового целого. Процедура xdr_wrapstring() удобна, потому что пакет RPC передаёт максимум две процедуры XDR в качестве параметров, а для xdr_string(), являющейся одной из наиболее часто используемых процедур, требует три. Процедура возвращает 1 при успешном завершении работы, иначе возвращается 0.

АТРИБУТЫ¶

Описание терминов данного раздела смотрите в attributes(7).

СМОТРИТЕ ТАКЖЕ¶

rpc(3)

Следующие руководства:

ПЕРЕВОД¶

Русский перевод этой страницы руководства разработал Azamat Hackimov <azamat.hackimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику по его адресу электронной почты или по адресу списка рассылки русских переводчиков.