inet_net_pton(3)

الاسم
inet_net_pton, inet_net_ntop - تحويل رقم شبكة الإنترنت

المكتبة
مكتبة الحلّال (libresolv، -lresolv)

موجز
#include <arpa/inet.h>

int inet_net_pton(size_t nsize;
                  int af, const char *pres,
                  void netp[nsize], size_t nsize);
char *inet_net_ntop(int bits, size_t psize;
                  int af,
                  const void netp[(bits - CHAR_BIT + 1) / CHAR_BIT],
                  int bits,
                  char pres[psize], size_t psize);

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

inet_net_pton(), inet_net_ntop():
    منذ glibc 2.20:
        _DEFAULT_SOURCE
    قبل glibc 2.20:
        _BSD_SOURCE || _SVID_SOURCE

الوصف
تحوّل هاتان الدالتان أرقام الشبكة بين صيغة العرض (أي القابلة للطباعة) وصيغة الشبكة (أي الثنائية).

بالنسبة لكلتا الدالتين، يُحدد af عائلة العنوان للتحويل؛ القيمة الوحيدة المدعومة هي AF_INET.

  inet_net_pton()
تحوّل الدالة inet_net_pton() سلسلة المحارف pres المنتهية بقيمة خالية والتي تحتوي على رقم شبكة إنترنت بصيغة العرض إلى صيغة الشبكة. تُوضع نتيجة التحويل، والتي هي بترتيب بايت الشبكة، في المخزن المؤقت المشار إليه بواسطة netp. (يشير معامل netp عادةً إلى بنية in_addr.) يُحدد معامل nsize عدد البايتات المتاحة في netp.

عند النجاح، تُرجع inet_net_pton() عدد البتات في حقل رقم الشبكة للنتيجة الموضوعة في netp. لمناقشة صيغة عرض الإدخال وقيمة الإرجاع، انظر الملاحظات.

ملاحظة: يجب تصفير المخزن المؤقت المشار إليه بواسطة netp قبل استدعاء inet_net_pton()، لأن الاستدعاء يكتب فقط عدد البايتات المطلوبة لرقم الشبكة (أو كما هو محدد صراحة بواسطة pres)، والذي قد يكون أقل من عدد البايتات في عنوان شبكة كامل.

  inet_net_ntop()
تحوّل الدالة inet_net_ntop() رقم الشبكة في المخزن المؤقت المشار إليه بواسطة netp إلى صيغة العرض؛ يُفسر *netp كقيمة بترتيب بايت الشبكة. يُحدد معامل bits عدد البتات في رقم الشبكة في *netp.

تُوضع سلسلة المحارف بصيغة العرض المنتهية بقيمة خالية في المخزن المؤقت المشار إليه بواسطة pres. يُحدد معامل psize عدد البايتات المتاحة في pres. سلسلة العرض تكون بصيغة CIDR: رقم عشري منقط يمثل عنوان الشبكة، متبوعًا بشرطة مائلة، وحجم رقم الشبكة بالبتات.

قيمة الإرجاع
عند النجاح، تُرجع inet_net_pton() عدد البتات في رقم الشبكة. عند الخطأ، تُرجع -1، ويُضبط errno للإشارة إلى الخطأ.

عند النجاح، تُرجع inet_net_ntop() pres. عند الخطأ، تُرجع NULL، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

EAFNOSUPPORT
    حدد af قيمة غير AF_INET.

EMSGSIZE
    كان حجم المخزن المؤقت للإخراج غير كافٍ.

ENOENT
    (inet_net_pton()) لم يكن pres بصيغة عرض صحيحة.

المعايير
لا شيء.

ملاحظات

  صيغة عرض الإدخال لـ inet_net_pton()
يمكن تحديد رقم الشبكة إما كقيمة ست عشرية أو بترميز عشري منقط.

تُشار إلى القيم الست عشرية ببادئة "0x" أو "0X". تملأ الأرقام الست عشرية الأنصاف (نصف الثمانيات) من رقم الشبكة من اليسار إلى اليمين بترتيب بايتات الشبكة.

في الترميز العشري المنقط، يُحدد حتى أربع ثمانيات، كأرقام عشرية مفصولة بنقاط. وبالتالي، تُقبل أي من الصيغ التالية:

    a.b.c.d
    a.b.c
    a.b
    a

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

بالنسبة للصيغة الست عشرية أو العشرية المنقطة، يمكن اختياريًا أن يتبع رقم الشبكة بشرطة مائلة ورقم في النطاق من 0 إلى 32، والذي يحدد حجم رقم الشبكة بالبتات.

  قيمة إرجاع inet_net_pton()
قيمة إرجاع inet_net_pton() هي عدد البتات في حقل رقم الشبكة. إذا انتهت سلسلة العرض المدخلة بشرطة مائلة وقيمة حجم صريحة، فإن ذلك الحجم يصبح قيمة إرجاع inet_net_pton(). وإلا، يُستنتج قيمة الإرجاع، bits، كالتالي:

•   إذا كان البايت الأكثر دلالة من رقم الشبكة أكبر من أو يساوي 240، فإن bits هو 32.

•   وإلا، إذا كان البايت الأكثر دلالة من رقم الشبكة أكبر من أو يساوي 224، فإن bits هو 4.

•   وإلا، إذا كان البايت الأكثر دلالة من رقم الشبكة أكبر من أو يساوي 192، فإن bits هو 24.

•   وإلا، إذا كان البايت الأكثر دلالة من رقم الشبكة أكبر من أو يساوي 128، فإن bits هو 16.

•   وإلا، فإن bits هو 8.

إذا كانت قيمة bits الناتجة من الخطوات أعلاه أكبر من أو تساوي 8، لكن عدد الثمانيات المحدد في رقم الشبكة يتجاوز bits/8، فإن bits يُضبط على 8 أضعاف عدد الثمانيات المحددة فعليًا.

أمثلة
يُظهر البرنامج أدناه استخدام inet_net_pton() وinet_net_ntop(). يستخدم inet_net_pton() لتحويل عنوان الشبكة بصيغة العرض المُقدم في وسيط سطر الأوامر الأول إلى صيغة ثنائية، ويعرض قيمة الإرجاع من inet_net_pton(). ثم يستخدم inet_net_ntop() لتحويل الصيغة الثنائية مرة أخرى إلى صيغة العرض، ويعرض السلسلة الناتجة.

لإظهار أن inet_net_pton() قد لا يكتب إلى جميع بايتات وسيطه netp، يسمح البرنامج بوسيط سطر أوامر ثانٍ اختياري، وهو رقم يُستخدم لتهيئة المخزن المؤقت قبل استدعاء inet_net_pton(). كسطر إخراج أخير، يعرض البرنامج جميع بايتات المخزن المؤقت التي أرجعها inet_net_pton() مما يسمح للمستخدم برؤية أي البايتات لم تُلمس بواسطة inet_net_pton().

تشغيل مثال، يُظهر أن inet_net_pton() يستنتج عدد البتات في رقم الشبكة:

    $ ./a.out 193.168;
    أرجع inet_net_pton(): 24
    أنتج inet_net_ntop():  193.168.0/24
    العنوان الخام:              c1a80000

أظهر أن inet_net_pton() لا يُصفّر البايتات غير المستخدمة في مخزنه الناتج:

    $ ./a.out 193.168 0xffffffff;
    أرجع inet_net_pton(): 24
    أنتج inet_net_ntop():  193.168.0/24
    العنوان الخام:              c1a800ff

أظهر أن inet_net_pton() ستوسع الحجم المستنتج لرقم الشبكة، إذا تجاوز عدد البايتات المقدمة في سلسلة العرض القيمة المستنتجة:

    $ ./a.out 193.168.1.128;
    inet_net_pton() returned: 32
    inet_net_ntop() yielded:  193.168.1.128/32
    Raw address:              c1a80180

تجاوز تحديد حجم رقم الشبكة صراحةً أي استنتاج حول حجمه (ولكن أي بايتات إضافية تم تحديدها صراحةً ستظل تُستخدم بواسطة inet_net_pton(): لملء مخزن النتيجة):

    $ ./a.out 193.168.1.128/24;
    inet_net_pton() returned: 24
    inet_net_ntop() yielded:  193.168.1/24
    Raw address:              c1a80180

  مصدر البرنامج
    /* Link with "-lresolv" */

    #include <arpa/inet.h>
    #include <err.h>
    #include <stdio.h>
    #include <stdlib.h>

    int
    main(int argc, char *argv[])
    {
        char buf[100];
        struct in_addr addr;
        int bits;

        if (argc < 2) {
            fprintf(stderr,
                    "Usage: %s presentation-form [addr-init-value]\n",
                    argv[0]);
            exit(EXIT_FAILURE);
        }

        /* If argv[2] is supplied (a numeric value), use it to initialize
           the output buffer given to inet_net_pton(), so that we can see
           that inet_net_pton() initializes only those bytes needed for
           the network number.  If argv[2] is not supplied, then initialize
           the buffer to zero (as is recommended practice).  */

        addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0;

        /* Convert presentation network number in argv[1] to binary.  */

        bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr));
        if (bits == -1)
            err(EXIT_FAILURE, "inet_net_ntop");

        printf("inet_net_pton() returned: %d\n", bits);

        /* Convert binary format back to presentation, using 'bits'
           returned by inet_net_pton().  */

        if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL)
            err(EXIT_FAILURE, "inet_net_ntop");

        printf("inet_net_ntop() yielded:  %s\n", buf);

        /* Display 'addr' in raw form (in network byte order), so we can
           see bytes not displayed by inet_net_ntop(); some of those bytes
           may not have been touched by inet_net_ntop(), and so will still
           have any initial value that was specified in argv[2].  */

        printf("Raw address:              %x\n", htonl(addr.s_addr));

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
inet(3), networks(5)

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

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

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