НАИМЕНОВАНИЕ

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

БИБЛИОТЕКА

Стандартная библиотека языка C (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);

: Примитив фильтра, который производит преобразования между символьными значениями языка C и их внешним представлением. Данная подпрограмма возвращает 1 при успешном завершении, иначе 0. Замечание: закодированные символы не упакованы, и каждый занимает 4 байта. В случае с массивом символов целесообразнее использовать xdr_bytes(), xdr_opaque() или 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(), за исключением того, что в отличие от 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. Замечание: поле op потока XDR должно быть установлено вызывающим.
: Предупреждение: для чтения из потока XDR, созданного данным программным интерфейсом, вы должны сначала вызвать xdrrec_skiprecord(), прежде чем производить какие-либо другие API-вызовы XDR. Это вставляет дополнительные байты в поток для предоставления информации о границе записи. Кроме того, потоки XDR, созданные разными API-функциями 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.
: Предупреждение: эта подпрограмма не работает с нулевыми указателями. Используйте вместо неё 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);

: Примитив фильтра, который производит преобразования между беззнаковыми целочисленными значения типа unsigned языка 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 union) языка 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).

Интерфейс	Атрибут	Значение
xdr_array(), xdr_bool(), xdr_bytes(), xdr_char(), xdr_destroy(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_getpos(), xdr_inline(), xdr_int(), xdr_long(), xdrmem_create(), xdr_opaque(), xdr_pointer(), xdrrec_create(), xdrrec_eof(), xdrrec_endofrecord(), xdrrec_skiprecord(), xdr_reference(), xdr_setpos(), xdr_short(), xdrstdio_create(), xdr_string(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_union(), xdr_vector(), xdr_void(), xdr_wrapstring()	Безвредность в нитях	MT-Safe

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

rpc(3)

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

Стандарт представления внешних данных: спецификация протокола
Представление внешних данных: технические замечания Sun.
XDR: External Data Representation Standard, RFC 1014, Sun Microsystems, Inc., USC-ISI.

ПЕРЕВОД

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

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

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

Fwd: [RFR] po4a://manpages-l10n/po/ru/man3/xdr.3.po