xdr(3)

الاسم
xdr - دوال مكتبة لتمثيل البيانات الخارجي

المكتبة
مكتبة سي المعيارية (libc، -lc)

الملخص والوصف
تسمح هذه الدوال لمبرمجي C بوصف هياكل بيانات عشوائية بطريقة مستقلة عن الآلة. تُنقل بيانات استدعاءات الإجراءات البعيدة باستخدام هذه الدوال.

النماذج الأولية أدناه مُصرَّح بها في <rpc/xdr.h> وتستخدم الأنواع التالية:

        typedef int bool_t;

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

للإعلان عن النوع 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 يترجم بين شكل C لعناصر المصفوفة وتمثيلها الخارجي. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    أولية مرشح تترجم بين القيم المنطقية (أعداد صحيحة C) وتمثيلاتها الخارجية. عند ترميز البيانات، يُنتج هذا المرشح قيمًا إما واحد أو صفر. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    أولية مرشح تترجم بين سلاسل البايت المعدودة وتمثيلاتها الخارجية. الوسيط sp هو عنوان مؤشر السلسلة. يقع طول السلسلة في العنوان sizep؛ لا يمكن أن تكون السلاسل أطول من maxsize. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    أولية مرشح تترجم بين محارف C وتمثيلاتها الخارجية. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا بخلاف ذلك. ملاحظة: المحارف المُعمَّاة غير مضغوطة، وتشغل 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 وتمثيلاتها الخارجية. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    أولية مرشح تترجم بين التعدادات enum في C (أعداد صحيحة فعليًا) وتمثيلاتها الخارجية. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    أولية مرشح تترجم بين الأعداد العائمة float في C وتمثيلاتها الخارجية. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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 وتمثيلاتها الخارجية. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا خلاف ذلك.

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

    أولية ترشيح تُترجم بين الأعداد الصحيحة من نوع long في لغة C وتمثيلاتها الخارجية. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا خلاف ذلك.

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 هو حجمه بالبايت. تُرجع هذه الدالة واحدًا إذا نجحت، صفرًا خلاف ذلك.

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,
                   typeof(int (char *, char *, int)) *readit,
                   typeof(int (char *, char *, int)) *writeit);

    تُهيئ هذه الدالة كائن دفق XDR المُشار إليه بواسطة xdrs. تُكتب بيانات الدفق إلى مخبأ بحجم sendsize؛ قيمة صفر تُشير إلى أن النظام يجب أن يستخدم مبدئيًا مناسبًا. تُقرأ بيانات الدفق من مخبأ بحجم recvsize؛ يمكن أيضًا ضبطه على مبدئي مناسب بتمرير قيمة صفر. عندما يمتلئ مخبأ الإخراج للدفق، تُستدعى writeit. وبالمثل، عندما يفرغ مخبأ الإدخال للدفق، تُستدعى readit. سلوك هاتين الدالتين مشابه لاستدعاءات النظام read(2) وwrite(2)، باستثناء أن handle يُمرر للدالتين السابقتين كوسيط أول. ملاحظة: يجب على المُستدعي تعيين حقل op لدفق XDR.

    تحذير: للقراءة من دفق XDR مُنشأ بواسطة واجهة البرمجة هذه، ستحتاج استدعاء xdrrec_skiprecord() أولاً قبل استدعاء أي دوال XDR أخرى. يُدخل هذا بايتات إضافية في الدفق لتوفير معلومات حدود السجل. أيضًا، دفقات XDR المُنشأة بواجهات برمجة xdr*_create مختلفة غير متوافقة لنفس السبب.

bool_t xdrrec_endofrecord(XDR *xdrs, int sendnow);

    لا يمكن استدعاء هذه الروتين إلا على التدفقات المنشأة بواسطة xdrrec_create(). تُوسم البيانات في المخزن المؤقت للمخرجات كسجل مكتمل، ويُكتب المخزن المؤقت للمخرجات اختياريًا إذا كان sendnow غير صفري. يُرجع هذا الروتين واحدًا إذا نجح، وصفرًا خلاف ذلك.

bool_t xdrrec_eof(XDR *xdrs);

    لا يمكن استدعاء هذه الروتين إلا على التدفقات المنشأة بواسطة xdrrec_create(). بعد استهلاك باقي السجل الحالي في التدفق، يُرجع هذا الروتين واحدًا إذا لم يكن للتدفق أي مدخلات أخرى، وصفرًا خلاف ذلك.

bool_t xdrrec_skiprecord(XDR *xdrs);

    لا يمكن استدعاء هذه الروتين إلا على التدفقات المنشأة بواسطة xdrrec_create(). يُخبر تطبيق XDR بأن باقي السجل الحالي في المخزن المؤقت للإدخال للتدفق يجب التخلص منه. يُرجع هذا الروتين واحدًا إذا نجح، وصفرًا خلاف ذلك.

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

    بدائية توفر تتبع المؤشرات داخل الهياكل. الوسيط pp هو عنوان المؤشر؛ size هو sizeof الهيكل الذي يشير إليه *pp؛ و proc هو إجراء XDR يُرشح الهيكل بين شكله في C وتمثيله الخارجي. يُرجع هذا الروتين واحدًا إذا نجح، وصفرًا خلاف ذلك.

    تحذير: لا يفهم هذا الروتين المؤشرات الفارغة. استخدم xdr_pointer() بدلاً من ذلك.

xdr_setpos(XDR *xdrs, unsigned int pos);

    كليّة تستدعي روتين تعيين الموضع المرتبط بتدفق XDR xdrs. الوسيط pos هو قيمة موضع تم الحصول عليها من xdr_getpos(). يُرجع هذا الروتين واحدًا إذا أمكن إعادة وضع تدفق XDR، وصفرًا خلاف ذلك.

    تحذير: من الصعب إعادة وضع بعض أنواع تدفقات XDR، لذا قد يفشل هذا الروتين مع نوع واحد من التدفقات وينجح مع آخر.

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

    بدائية ترشيح تترجم بين الأعداد الصحيحة القصيرة short في C وتمثيلاتها الخارجية. يُرجع هذا الروتين واحدًا إذا نجح، وصفرًا خلاف ذلك.

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 هو عنوان مؤشر السلسلة. يُرجع هذا الروتين واحدًا إذا نجح، وصفرًا خلاف ذلك.

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

    بدائية ترشيح تترجم بين محارف C غير المُشار إليها وتمثيلاتها الخارجية. تُرجع هذه الروتين واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    بدائية ترشيح تترجم بين أعداد صحيحة C غير مُشار إليها وتمثيلاتها الخارجية. تُرجع هذه الروتين واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    بدائية ترشيح تترجم بين أعداد صحيحة C غير مُشار إليها طويلة وتمثيلاتها الخارجية. تُرجع هذه الروتين واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    بدائية ترشيح تترجم بين أعداد صحيحة C غير مُشار إليها قصيرة وتمثيلاتها الخارجية. تُرجع هذه الروتين واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    بدائية ترشيح تترجم بين اتحاد C مُميَّز وتمثيله الخارجي المُقابل. تُترجم أولاً مميِّز الاتحاد الموجود في dscmp. هذا المميِّز هو دائمًا enum_t. بعد ذلك، يُترجم الاتحاد الموجود في unp. المُعامل choices هو مؤشر لمصفوفة من بنى xdr_discrim(). تحتوي كل بنية على زوج مُرتَّب من [value,proc]. إذا كان مميِّز الاتحاد مساويًا لـ value المُقابل، فتُستدعى proc لترجمة الاتحاد. يُشار إلى نهاية مصفوفة بنى xdr_discrim() بروتين قيمته NULL. إذا لم يُوجد المميِّز في مصفوفة choices، فتُستدعى إجراءات defaultarm (إذا لم تكن NULL). تُرجع واحدًا إذا نجحت، صفرًا بخلاف ذلك.

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

    بدائية ترشيح تترجم بين مصفوفات ثابتة الطول وتمثيلاتها الخارجية المُقابلة. المُعامل arrp هو عنوان المؤشر للمصفوفة، بينما size هو عدد عناصر المصفوفة. المُعامل elsize هو sizeof كل عنصر من عناصر المصفوفة، وelproc هو مرشح XDR يترجم بين شكل C لعناصر المصفوفة وتمثيلها الخارجي. يُرجع هذا الروتين واحدًا إذا نجح، صفرًا بخلاف ذلك.

bool_t xdr_void(void);

    يُرجع هذا الروتين واحدًا دائمًا. قد يُمرَّر إلى روتينات RPC التي تتطلب مُعامل دالة، حيث لا يُفعل شيء.

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

    بدائية تستدعي xdr_string(xdrs, sp,MAXUN.UNSIGNED ); حيث MAXUN.UNSIGNED هي القيمة القصوى لعدد صحيح غير مُشار إليه. xdr_wrapstring() مُفيدة لأن حزمة RPC تُمرِّر حدًا أقصى من روتينين XDR كمُعاملات، وxdr_string()، إحدى البدائيات الأكثر استخدامًا، تتطلب ثلاثة. تُرجع واحدًا إذا نجحت، صفرًا بخلاف ذلك.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر 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)

كتيبات الأدلة التالية:
    معيار تمثيل البيانات الخارجي: مواصفات البروتوكول
    تمثيل البيانات الخارجي: ملاحظات تقنية من صن
    XDR: معيار تمثيل البيانات الخارجي، RFC 1014، شركة صن ميكروسيستمز، USC-ISI.

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.