getprotoent_r(3)

الاسم
getprotoent_r, getprotobyname_r, getprotobynumber_r - الحصول على مدخل البروتوكول (قابل لإعادة الدخول)

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

موجز
#include <netdb.h>

int getprotoent_r(size_t size;
                  struct protoent *restrict result_buf,
                  char buf[restrict size], size_t size,
                  struct protoent **restrict result);
int getprotobyname_r(size_t size;
                  const char *restrict name,
                  struct protoent *restrict result_buf,
                  char buf[restrict size], size_t size,
                  struct protoent **restrict result);
int getprotobynumber_r(size_t size;
                  int proto,
                  struct protoent *restrict result_buf,
                  char buf[restrict size], size_t size,
                  struct protoent **restrict result);

    متطلبات ماكروات اختبار الميزات لـ glibc (انظر feature_test_macros(7)):

getprotoent_r(), getprotobyname_r(), getprotobynumber_r():
    منذ glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.19 وما قبله:
        _BSD_SOURCE || _SVID_SOURCE

الوصف
الدوال getprotoent_r() و getprotobyname_r() و getprotobynumber_r() هي المكافئات القابلة لإعادة الدخول لـ getprotoent(3) و getprotobyname(3) و getprotobynumber(3) على التوالي. تختلف في طريقة إرجاع بنية protoent، وفي توقيع استدعاء الدالة وقيمة الإرجاع. تصف صفحة الدليل هذه الاختلافات فقط عن الدوال غير القابلة لإعادة الدخول.

بدلاً من إرجاع مؤشر إلى بنية protoent مخصصة بشكل ثابت كنتيجة للدالة، تنسخ هذه الدوال البنية إلى الموقع المشار إليه بواسطة result_buf.

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

إذا حصل استدعاء الدالة بنجاح على سجل بروتوكول، فسيُضبط *result ليشير إلى result_buf؛ وإلا، فسيُضبط *result على NULL.

قيمة الإرجاع
تُعيد هذه الدوال 0 عند النجاح. وتُعيد أحد أرقام الأخطاء الموجبة المدرجة في قسم ERRORS عند حدوث خطأ.

عند الخطأ، أو عدم العثور على السجل (getprotobyname_r()، getprotobynumber_r())، أو نهاية الإدخال (getprotoent_r())، يُضبط result على NULL.

الأخطاء

ENOENT
    (getprotoent_r()) لا مزيد من السجلات في قاعدة البيانات.

ERANGE
    المخزن المؤقت buf صغير جدًا. حاول مرة أخرى بمخزن أكبر (وزيادة size).

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
getprotoent_r(), getprotobyname_r(), getprotobynumber_r() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)

الإصدارات
توجد دوال بأسماء مماثلة في بعض الأنظمة الأخرى، وإن كان ذلك عادةً بتواقيع استدعاء مختلفة.

المعايير
GNU.

أمثلة
يستخدم البرنامج أدناه getprotobyname_r() لاسترداد سجل البروتوكول للبروتوكول المسمى في وسيط سطر الأوامر الأول. إذا تم توفير وسيط سطر أوامر ثانٍ (عدد صحيح)، فسيُستخدم كقيمة مبدئية لـ size؛ إذا فشل getprotobyname_r() مع الخطأ ERANGE، يعيد البرنامج المحاولة بأحجام مخزن مؤقت أكبر. تُظهر جلسة الصدفة التالية بعض عمليات التشغيل النموذجية:

    $ ./a.out tcp 1
    ERANGE! Retrying with larger buffer
    getprotobyname_r() returned: 0 (success)  (size=78)
    p_name=tcp; p_proto=6; aliases=TCP
    $ ./a.out xxx 1
    ERANGE! Retrying with larger buffer
    getprotobyname_r() returned: 0 (success)  (size=100)
    Call failed/record not found

  مصدر البرنامج
    #define _GNU_SOURCE
    #include <ctype.h>
    #include <errno.h>
    #include <netdb.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>

    #define MAX_BUF 10000

    int
    main(int argc, char *argv[])
    {
        int size, erange_cnt, s;
        struct protoent result_buf;
        struct protoent *result;
        char buf[MAX_BUF];

        if (argc < 2) {
            printf("Usage: %s proto-name [size]\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        size = 1024;
        if (argc > 2)
            size = atoi(argv[2]);

        if (size > MAX_BUF) {
            printf("Exceeded buffer limit (%d)\n", MAX_BUF);
            exit(EXIT_FAILURE);
        }

        erange_cnt = 0;
        do {
            s = getprotobyname_r(argv[1], &result_buf,
                                 buf, size, &result);
            if (s == ERANGE) {
                if (erange_cnt == 0)
                    printf("ERANGE! Retrying with larger buffer\n");
                erange_cnt++;

                /* Increment a byte at a time so we can see exactly
                   what size buffer was required.  */

                size++;

                if (size > MAX_BUF) {
                    printf("Exceeded buffer limit (%d)\n", MAX_BUF);
                    exit(EXIT_FAILURE);
                }
            }
        } while (s == ERANGE);

        printf("getprotobyname_r() returned: %s  (size=%d)\n",
               (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
               strerror(s), size);

        if (s != 0 || result == NULL) {
            printf("Call failed/record not found\n");
            exit(EXIT_FAILURE);
        }

        printf("p_name=%s; p_proto=%d; aliases=",
               result_buf.p_name, result_buf.p_proto);
        for (char **p = result_buf.p_aliases; *p != NULL; p++)
            printf("%s ", *p);
        printf("\n");

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
getprotoent(3), protocols(5)

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

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

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