getnameinfo(3)

الاسم
getnameinfo - ترجمة العنوان إلى الاسم بطريقة مستقلة عن البروتوكول

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

موجز
#include <sys/socket.h>
#include <netdb.h>

int getnameinfo(socklen_t hostlen, socklen_t servlen;
                const struct sockaddr *restrict addr, socklen_t addrlen,
                char host[_Nullable restrict hostlen],
                socklen_t hostlen,
                char serv[_Nullable restrict servlen],
                socklen_t servlen,
                int flags);

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

getnameinfo():
    منذ glibc 2.22:
        _POSIX_C_SOURCE >= 200112L
    glibc 2.21 وما قبله:
        _POSIX_C_SOURCE

الوصف
دالة getnameinfo() هي عكس getaddrinfo(3): فهي تحول عنوان مقبس إلى مضيف وخدمة مقابلين، بطريقة مستقلة عن البروتوكول. تجمع بين وظائف gethostbyaddr(3) و getservbyport(3)، ولكن على عكس تلك الدوال، فإن getnameinfo() قابلة لإعادة الدخول وتسمح للبرامج بإزالة التبعيات بين IPv4 و IPv6.

المعامل addr هو مؤشر إلى بنية عنوان مقبس عامة (من النوع sockaddr_in أو sockaddr_in6) بحجم addrlen تحتوي على عنوان IP ورقم المنفذ المدخلين. المعاملان host و serv هما مؤشران إلى مخازن مخصصة من قبل المستدعي (بحجم hostlen و servlen على التوالي) يضع فيهما getnameinfo() سلاسل محارف منتهية بقيمة خالية تحتوي على اسمي المضيف والخدمة على التوالي.

يمكن للمستدعي تحديد أن اسم مضيف (أو اسم خدمة) غير مطلوب بتوفير معامل host (أو serv) بقيمة NULL أو معامل hostlen (أو servlen) بقيمة صفر. ومع ذلك، يجب طلب واحد على الأقل من اسم المضيف أو اسم الخدمة.

يعدل المعامل flags سلوك getnameinfo() كما يلي:

NI_NAMEREQD
    إذا تم تعيينه، فسيتم إرجاع خطأ إذا تعذر تحديد اسم المضيف.

NI_DGRAM
    إذا تم تعيينه، فإن الخدمة تكون قائمة على الرزم (UDP) بدلاً من التيار (TCP). هذا مطلوب للمنافذ القليلة (512–514) التي لها خدمات مختلفة لـ UDP و TCP.

NI_NOFQDN
    إذا تم تعيينه، فسيتم إرجاع جزء اسم المضيف فقط من اسم النطاق المؤهل بالكامل للمضيفين المحليين.

NI_NUMERICHOST
    إذا تم تعيينه، فسيتم إرجاع الشكل الرقمي لاسم المضيف. (عند عدم تعيينه، سيحدث هذا أيضًا في حال تعذر تحديد اسم العقدة.)

NI_NUMERICSERV
    إذا تم تعيينه، فسيتم إرجاع الشكل الرقمي لعنوان الخدمة. (عند عدم تعيينه، سيحدث هذا أيضًا في حال تعذر تحديد اسم الخدمة.)

  إضافات إلى getnameinfo() لأسماء النطاقات المعولمة
بدءًا من glibc 2.3.4، تم توسيع getnameinfo() للسماح بشكل انتقائي بتحويل أسماء المضيفين بشكل شفاف من وإلى تنسيق اسم النطاق المعولم (IDN) (انظر RFC 3490، تعوليم أسماء النطاقات في التطبيقات (IDNA)). تم تعريف ثلاث علامات جديدة:

NI_IDN
    إذا استُخدمت هذه العلامة، فإن الاسم الموجود في عملية البحث يُحوَّل من تنسيق IDN إلى ترميز المحلية إذا لزم الأمر. الأسماء التي تحتوي فقط على ASCII لا تتأثر بالتحويل، مما يجعل هذه العلامة قابلة للاستخدام في البرامج والبيئات الحالية.

NI_IDN_ALLOW_UNASSIGNED
NI_IDN_USE_STD3_ASCII_RULES
    سيؤدي ضبط هذه الأعلام إلى تفعيل علم IDNA_ALLOW_UNASSIGNED (السماح بنقاط كود يونيكود غير المعينة) وعلم IDNA_USE_STD3_ASCII_RULES (فحص المخرجات للتأكد من أنها اسم مضيف متوافق مع STD3) على التوالي، لاستخدامهما في معالجة IDNA.

قيمة الإرجاع
عند النجاح، يُعاد 0، وتُملأ أسماء العقدة والخدمة، إذا طُلبت، بسلسلة محارف منتهية بقيمة فارغة، وقد تُقتطع لتناسب أطوال المخازن المؤقتة المحددة. عند الخطأ، يُعاد أحد رموز الخطأ غير الصفرية التالية:

EAI_AGAIN
    لا يمكن حل الاسم في هذا الوقت. حاول مرة أخرى لاحقًا.

EAI_BADFLAGS
    المعامل flags له قيمة غير صالحة.

EAI_FAIL
    حدث خطأ غير قابل للاسترداد.

EAI_FAMILY
    لم يتم التعرف على عائلة العنوان، أو كان طول العنوان غير صالح للعائلة المحددة.

EAI_MEMORY
    نفدت الذاكرة.

EAI_NONAME
    لا يُحل الاسم للوسائط المقدمة. NI_NAMEREQD مضبوط ولا يمكن تحديد اسم المضيف، أو لم يُطلب اسم المضيف ولا اسم الخدمة.

EAI_OVERFLOW
    المخزن المؤقت المشار إليه بواسطة host أو serv كان صغيرًا جدًا.

EAI_SYSTEM
    حدث خطأ في النظام. يمكن العثور على رمز الخطأ في errno.

ترجم الدالة gai_strerror(3) رموز الخطأ هذه إلى سلسلة نصية مقروءة للبشر، مناسبة للإبلاغ عن الأخطاء.

الملفات
/etc/hosts
/etc/nsswitch.conf
/etc/resolv.conf

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
getnameinfo() | سلامة الخيوط | بيئة محلية آمنة لتعدد الخيوط (MT-Safe)

المعايير
POSIX.1-2008. RFC 2553.

التاريخ
glibc 2.1. POSIX.1-2001.

قبل glibc 2.2، كانت الوسائط hostlen و servlen مكتوبة كنوع size_t.

ملاحظات
لمساعدة المبرمج في اختيار أحجام معقولة للمخازن المؤقتة المقدمة، يُعرّف <netdb.h> الثوابت

    #define NI_MAXHOST      1025
    #define NI_MAXSERV      32

منذ glibc 2.8، تُعرض هذه التعريفات فقط إذا عُرفت وحدات ماكرو اختبار الميزات المناسبة، وهي: _GNU_SOURCE، _DEFAULT_SOURCE (منذ glibc 2.19)، أو (في إصدارات glibc حتى 2.19) _BSD_SOURCE أو _SVID_SOURCE.

الأول هو الثابت MAXDNAME في الإصدارات الحديثة من ملف الرأس <arpa/nameser.h> الخاص بـ BIND. والثاني هو تخمين بناءً على الخدمات المدرجة في RFC الأرقام المخصصة الحالي.

أمثلة
يحاول الكود التالي الحصول على اسم المضيف العددي واسم الخدمة، لعنوان مقبس معين. لاحظ أنه لا يوجد مرجع مُرمّز آليًا لعائلة عناوين معينة.

    struct sockaddr *addr;     /* input */
    socklen_t addrlen;         /* input */
    char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];

    if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf,
                sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
        printf("host=%s, serv=%s\n", hbuf, sbuf);

يتحقق الإصدار التالي مما إذا كان عنوان المقبس لديه تعيين عنوان عكسي.

    struct sockaddr *addr;     /* input */
    socklen_t addrlen;         /* input */
    char hbuf[NI_MAXHOST];

    if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
                NULL, 0, NI_NAMEREQD))
        printf("could not resolve hostname");
    else
        printf("host=%s\n", hbuf);

يمكن العثور على برنامج مثال يستخدم getnameinfo() في getaddrinfo(3).

انظر أيضًا
accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2), getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3), inet_ntop(3), hosts(5), services(5), hostname(7), named(8)

R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Interface Extensions for IPv6, RFC 2553, March 1999.

Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped Addresses, internet draft, work in progress ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt.

Craig Metz, Protocol Independence Using the Sockets API, Proceedings of the freenix track: 2000 USENIX annual technical conference, June 2000 http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html.

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

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

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