dlsym(3)

الاسم
dlsym, dlvsym - الحصول على عنوان رمز في كائن مشترك أو ملف تنفيذي

المكتبة
مكتبة الربط الديناميكي (libdl، -ldl)

موجز
#include <dlfcn.h>

void *dlsym(void *restrict handle, const char *restrict symbol);

#define _GNU_SOURCE
#include <dlfcn.h>

void *dlvsym(void *restrict handle, const char *restrict symbol,
             const char *restrict version);

الوصف
تأخذ الدالة dlsym() "مقبض" كائن مشترك محمل ديناميكيًا أُعيد بواسطة dlopen(3) مع اسم رمز منتهي بقيمة خالية، وتُعيد العنوان الذي حُمّل فيه ذلك الرمز في الذاكرة. إذا لم يُعثر على الرمز، في الكائن المحدد أو أي من الكائنات المشتركة التي حُمّلت آليًا بواسطة dlopen(3) عند تحميل ذلك الكائن، تُعيد dlsym() NULL. (البحث الذي تُجريه dlsym() هو بحث عرضي أول عبر شجرة التبعية لهذه الكائنات المشتركة.)

في حالات غير اعتيادية (انظر الملاحظات) قد تكون قيمة الرمز NULL فعليًا. لذلك، لا يجب أن يشير إرجاع NULL من dlsym() بالضرورة إلى خطأ. الطريقة الصحيحة للتمييز بين خطأ ورمز قيمته NULL هي استدعاء dlerror(3) لمسح أي شروط خطأ قديمة، ثم استدعاء dlsym()، ثم استدعاء dlerror(3) مرة أخرى، مع حفظ قيمته المُعادة في متغير، والتحقق مما إذا كانت هذه القيمة المحفوظة ليست NULL.

يوجد مقبضان شبه خاصان يمكن تحديدهما في handle:

RTLD_DEFAULT
    اعثر على أول ظهور للرمز المطلوب باستخدام ترتيب البحث المبدئي للكائن المشترك. سيتضمن البحث الرموز العامة في الملف التنفيذي وتبعياته، بالإضافة إلى الرموز في الكائنات المشتركة التي حُمّلت ديناميكيًا مع العلم RTLD_GLOBAL.

RTLD_NEXT
    اعثر على الظهور التالي للرمز المطلوب في ترتيب البحث بعد الكائن الحالي. يسمح هذا بتوفير غلاف حول دالة في كائن مشترك آخر، بحيث، على سبيل المثال، يمكن لتعريف دالة في كائن مشترك مُحمّل مسبقًا (انظر LD_PRELOAD في ld.so(8)) العثور على الدالة "الحقيقية" المُقدمة في كائن مشترك آخر واستدعائها (أو في هذا الشأن، التعريف "التالي" للدالة في حالات وجود طبقات متعددة من التحميل المسبق).

يجب تعريف ماكرو اختبار الميزة _GNU_SOURCE للحصول على تعريفات RTLD_DEFAULT و RTLD_NEXT من <dlfcn.h>.

تقوم الدالة dlvsym() بنفس ما تفعله dlsym() ولكنها تأخذ سلسلة محارف إصدار كمعامل إضافي.

قيمة الإرجاع
عند النجاح، تُعيد هذه الدوال العنوان المرتبط بـ symbol. عند الفشل، تُعيد NULL؛ يمكن تشخيص الخطأ باستخدام dlerror(3).

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

المعايير

dlsym()
    POSIX.1-2008.

dlvsym()
    GNU.

التاريخ

dlsym()
    glibc 2.0. POSIX.1-2001.

dlvsym()
    glibc 2.1.

ملاحظات
توجد عدة سيناريوهات يكون فيها عنوان رمز عام NULL. على سبيل المثال، يمكن وضع رمز عند عنوان صفري بواسطة الرابط، عبر نص رابط أو مع خيار سطر الأوامر --defsym. الرموز الضعيفة غير المعرفة لها أيضًا قيمة NULL. أخيرًا، قد تكون قيمة الرمز نتيجة دالة محل لـ GNU غير مباشر (IFUNC) تُعيد NULL كقيمة محلولة. في الحالة الأخيرة، تُعيد dlsym() أيضًا NULL بدون خطأ. ومع ذلك، في الحالتين الأوليين، يكون سلوك الرابط الديناميكي لـ GNU غير متناسق: تنجح معالجة إعادة التوطين ويمكن ملاحظة أن الرمز له قيمة NULL، لكن dlsym() تفشل ويشير dlerror() إلى خطأ بحث.

  السجل
الدالة dlsym() هي جزء من واجهة برمجة تطبيقات dlopen، المشتقة من SunOS. هذا النظام لا يحتوي على dlvsym().

أمثلة
انظر dlopen(3).

انظر أيضًا
dl_iterate_phdr(3), dladdr(3), dlerror(3), dlinfo(3), dlopen(3), ld.so(8)

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

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

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