gethostbyname(3)

الاسم
gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r, gethostbyname_r, gethostent_r - الحصول على إدخال المضيف الشبكي

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

موجز
#include <netdb.h>

void sethostent(int stayopen);
void endhostent(void);

[[deprecated]] extern int h_errno;

[[deprecated]] struct hostent *gethostbyname(const char *name);
[[deprecated]] struct hostent *gethostbyaddr(socklen_t size;
                                             const void addr[size],
                                             socklen_t size, int type);

[[deprecated]] void herror(const char *s);
[[deprecated]] const char *hstrerror(int err);

/* System V/POSIX extension */
struct hostent *gethostent(void);

/* GNU extensions */
[[deprecated]]
struct hostent *gethostbyname2(const char *name, int af);

int gethostent_r(size_t bufsize;
                 struct hostent *restrict ret,
                 char buf[restrict bufsize], size_t bufsize,
                 struct hostent **restrict result,
                 int *restrict h_errnop);

[[deprecated]]
int gethostbyaddr_r(socklen_t size, size_t bufsize;
                 const void addr[restrict size], socklen_t size,
                 int type,
                 struct hostent *restrict ret,
                 char buf[restrict bufsize], size_t bufsize,
                 struct hostent **restrict result,
                 int *restrict h_errnop);
[[deprecated]]
int gethostbyname_r(size_t bufsize;
                 const char *restrict name,
                 struct hostent *restrict ret,
                 char buf[restrict bufsize], size_t bufsize,
                 struct hostent **restrict result,
                 int *restrict h_errnop);
[[deprecated]]
int gethostbyname2_r(size_t bufsize;
                 const char *restrict name, int af,
                 struct hostent *restrict ret,
                 char buf[restrict bufsize], size_t bufsize,
                 struct hostent **restrict result,
                 int *restrict h_errnop);

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

gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(), gethostbyname2_r():
    منذ glibc 2.19:
        _DEFAULT_SOURCE
    حتى glibc 2.19:
        _BSD_SOURCE || _SVID_SOURCE

herror(), hstrerror():
    منذ glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.8 إلى glibc 2.19:
        _BSD_SOURCE || _SVID_SOURCE
    قبل glibc 2.8:
        none

h_errno:
    منذ glibc 2.19
        _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
    glibc 2.12 إلى glibc 2.19:
        _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
    قبل glibc 2.12:
        none

الوصف
الدوال gethostbyname*(), gethostbyaddr*(), herror(), و hstrerror() مهملة. يجب على التطبيقات استخدام getaddrinfo(3), getnameinfo(3), و gai_strerror(3) بدلاً من ذلك.

تحدد الدالة sethostent()، إذا كان stayopen صحيحًا (1)، أنه يجب استخدام مقبس TCP متصل لاستعلامات خادم الأسماء وأن الاتصال يجب أن يبقى مفتوحًا خلال الاستعلامات المتتالية. وإلا، ستستخدم استعلامات خادم الأسماء مخططات بيانات UDP.

تنهي الدالة endhostent() استخدام اتصال TCP لاستعلامات خادم الأسماء.

ترجع الدالة gethostbyname() بنية من النوع hostent للمضيف المُعطى name. هنا name إما اسم مضيف أو عنوان IPv4 بترميز النقطة القياسي (كما في inet_addr(3)). إذا كان name عنوان IPv4، لا يُجرى بحث وتقوم gethostbyname() ببساطة بنسخ name إلى الحقل h_name وما يعادله من struct in_addr إلى الحقل h_addr_list[0] من بنية hostent المرجعة. إذا لم ينتهِ name بنقطة وتم تعيين متغير البيئة HOSTALIASES، سيُبحث أولاً عن name في ملف الأسماء المستعارة المشار إليه بواسطة HOSTALIASES (انظر hostname(7) لتنسيق الملف). يُبحث في النطاق الحالي ونطاقاته الأم ما لم ينتهِ name بنقطة.

ترجع الدالة gethostbyaddr() بنية من النوع hostent لعنوان المضيف المُعطى addr بحجم size ونوع العنوان type. أنواع العناوين الصالحة هي AF_INET و AF_INET6 (المُعرفة في <sys/socket.h>). وسيطة عنوان المضيف هي مؤشر إلى بنية من نوع يعتمد على نوع العنوان، على سبيل المثال struct in_addr * (التي تم الحصول عليها ربما عبر استدعاء inet_addr(3)) لنوع العنوان AF_INET.

الدالة (المهجورة) herror() تطبع رسالة الخطأ المرتبطة بالقيمة الحالية لـ h_errno على stderr.

الدالة (المهجورة) hstrerror() تأخذ رقم خطأ (عادةً h_errno) وتُعيد سلسلة المحارف المقابلة للرسالة.

استعلامات أسماء النطاقات التي تنفذها gethostbyname() و gethostbyaddr() تعتمد على المصادر المهيأة لمبدل خدمة الأسماء (nsswitch.conf(5)) أو خادم أسماء محلي (named(8)). الإجراء المبدئي هو استعلام المصادر المهيأة لمبدل خدمة الأسماء (nsswitch.conf(5))، وفي حال فشل ذلك، خادم أسماء محلي (named(8)).

  تاريخي
ملف nsswitch.conf(5) هو الطريقة الحديثة للتحكم في ترتيب عمليات البحث عن المضيف.

في glibc 2.4 والإصدارات السابقة، استُخدمت الكلمة المفتاحية order للتحكم في ترتيب عمليات بحث المضيف كما هو معرف في /etc/host.conf (host.conf(5)).

بنية hostent معرّفة في <netdb.h> كما يلي:

    struct hostent {
        char  *h_name;            /* الاسم الرسمي للمضيف */
        char **h_aliases;         /* قائمة الأسماء المستعارة */
        int    h_addrtype;        /* نوع عنوان المضيف */
        int    h_length;          /* حجم العنوان */
        char **h_addr_list;       /* قائمة العناوين */
    }
    #define h_addr h_addr_list[0] /* للتوافقية مع الإصدارات السابقة */

أعضاء بنية hostent هم:

h_name
    الاسم الرسمي للمضيف.

h_aliases
    مصفوفة من الأسماء البديلة للمضيف، منتهية بمؤشر فارغ.

h_addrtype
    نوع العنوان؛ دائمًا AF_INET أو AF_INET6 في الوقت الحالي.

h_length
    حجم العنوان بالبايت.

h_addr_list
    مصفوفة من المؤشرات لعناوين الشبكة للمضيف (بترتيب بايت الشبكة)، منتهية بمؤشر فارغ.

h_addr
    العنوان الأول في h_addr_list للتوافق مع الإصدارات السابقة.

قيمة الإرجاع
الدالتان gethostbyname() و gethostbyaddr() تُعيدان بنية hostent أو مؤشرًا فارغًا إذا حدث خطأ. عند الخطأ، يحمل المتغير h_errno رقم خطأ. عندما لا يكون فارغًا، قد تشير القيمة المُعادة إلى بيانات ثابتة، انظر الملاحظات أدناه.

الأخطاء
يمكن للمتغير h_errno أن يأخذ القيم التالية:

HOST_NOT_FOUND
    المضيف المحدد غير معروف.

NO_DATA
    الاسم المطلوب صالح ولكن ليس لديه عنوان IP. قد يُعيد نوع آخر من الطلبات إلى خادم الأسماء لهذا النطاق إجابة. الثابت NO_ADDRESS هو مرادف لـ NO_DATA.

NO_RECOVERY
    حدث خطأ غير قابل للاسترداد في خادم الأسماء.

TRY_AGAIN
    حدث خطأ مؤقت على خادم أسماء موثوق. حاول مرة أخرى لاحقًا.

الملفات

/etc/host.conf
    ملف تضبيط الحلّال (resolver)

/etc/hosts
    ملف قاعدة بيانات المضيف

/etc/nsswitch.conf
    تهيئة مبدل خدمة الأسماء

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
gethostbyname() | سلامة الخيوط | MT-Unsafe race:hostbyname env locale
gethostbyaddr() | سلامة الخيوط | MT-Unsafe race:hostbyaddr env locale
sethostent()، endhostent()، gethostent_r() | سلامة الخيوط | MT-Unsafe race:hostent env locale
herror()، hstrerror() | سلامة الخيوط | MT-Safe
gethostent() | سلامة الخيوط | MT-Unsafe race:hostent race:hostentbuf env locale
gethostbyname2() | سلامة الخيوط | MT-Unsafe race:hostbyname2 env locale
gethostbyaddr_r()، gethostbyname_r()، gethostbyname2_r() | سلامة الخيوط | بيئة محلية آمنة لتعدد الخيوط (MT-Safe)

في الجدول أعلاه، يشير hostent في race:hostent إلى أنه إذا استُخدمت أي من الدوال sethostent()، gethostent()، gethostent_r()، أو endhostent() بالتوازي في خيوط مختلفة من برنامج، فقد تحدث سباقات بيانات.

المعايير

sethostent()
endhostent()
gethostent()
    POSIX.1-2008.

gethostent_r()
    GNU.

أخرى:
    لا شيء.

التاريخ

sethostent()
endhostent()
gethostent()
    POSIX.1-2001.

gethostbyname()
gethostbyaddr()
h_errno
    وُسِمَت بالتقادم في POSIX.1-2001. أُزيلت في POSIX.1-2008، مُوصيةً باستخدام getaddrinfo(3) وgetnameinfo(3) بدلاً منها.

ملاحظات
قد تُعيد الدالتان gethostbyname() وgethostbyaddr() مؤشراتٍ إلى بيانات ثابتة، قد تُستبدل باستدعاءات لاحقة. لا يكفي نسخ struct hostent لأنه يحتوي على مؤشرات؛ يلزم نسخ عميق.

في تطبيق BSD الأصلي، كان معامل size للدالة gethostbyname() من النوع int. معيار SUSv2 معيب ويُصرّح بأن معامل size للدالة gethostbyaddr() من النوع size_t. (هذا خطأ، لأنه يجب أن يكون int، وsize_t ليس كذلك. POSIX.1-2001 يجعله socklen_t، وهذا صحيح.) انظر أيضًا accept(2).

النموذج الأولي في BSD للدالة gethostbyaddr() يستخدم const char * للمعامل الأول.

  إضافة System V/POSIX
يتطلب POSIX استدعاء gethostent()، الذي يجب أن يُعيد الإدخال التالي في قاعدة بيانات المضيف. عند استخدام DNS/BIND، لا معنى كبير لذلك، لكنه قد يكون معقولاً إذا كانت قاعدة بيانات المضيف ملفًا يمكن قراءته سطرًا سطرًا. على العديد من الأنظمة، يقرأ روتين بهذا الاسم من الملف /etc/hosts. قد يكون متاحًا فقط عندما بُنيت المكتبة دون دعم DNS. ستتجاهل نسخة glibc إدخالات ipv6. هذه الدالة غير قابلة لإعادة الدخول، وتُضيف glibc نسخة قابلة لإعادة الدخول gethostent_r().

  امتدادات جنو
لدى glibc2 أيضًا gethostbyname2() تعمل مثل gethostbyname()، لكنها تسمح بتحديد عائلة العنوان التي يجب أن ينتمي إليها العنوان.

لدى glibc2 أيضًا نسخ قابلة لإعادة الدخول gethostent_r() وgethostbyaddr_r() وgethostbyname_r() وgethostbyname2_r(). يُزوّد المستدعي بنية hostent ret التي ستملأ عند النجاح، ومخزن عمل مؤقت buf بحجم bufsize. بعد الاستدعاء، سيشير result إلى النتيجة عند النجاح. في حالة خطأ أو إذا لم يُعثر على إدخال، سيكون result NULL. تُعيد الدوال 0 عند النجاح ورقم خطأ غير صفري عند الفشل. بالإضافة إلى الأخطاء التي تُعيدها النسخ غير القابلة لإعادة الدخول لهذه الدوال، إذا كان buf صغيرًا جدًا، فستُعيد الدوال ERANGE، ويجب إعادة محاولة الاستدعاء بمخزن أكبر. المتغير العام h_errno لا يُعدّل، لكن عنوان متغير لتخزين أرقام الأخطاء يُمرّر في h_errnop.

العلل
لا تتعرف gethostbyname() على مكونات سلسلة عنوان IPv4 المنقّطة المُعبّر عنها بالنظام الست عشري.

انظر أيضًا
getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3), resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)

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

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

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