تحديد متطلبات ماكرو اختبار الميزات في صفحات الدليل¶

عندما تتطلب دالة تعريف ماكرو اختبار ميزات، تتضمن صفحة الدليل SYNOPSIS عادةً ملاحظة بالشكل التالي (هذا المثال من صفحة دليل acct(2)):

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

يعني || أنه للحصول على تعريف acct(2) من <unistd.h>، يجب تعريف أحد تعريفات الماكرو التالية قبل تضمين أي ملفات رأس:

#define _BSD_SOURCE
#define _XOPEN_SOURCE        /* or any value < 500 */

بدلاً من ذلك، يمكن تضمين تعريفات مكافئة في أمر الترجمة:

cc -D_BSD_SOURCE
cc -D_XOPEN_SOURCE           # Or any value < 500

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

في حالات قليلة، تستخدم صفحات الدليل اختصارًا للتعبير عن متطلبات ماكرو اختبار الميزات (هذا المثال من readahead(2)):

#define _GNU_SOURCE
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>

ssize_t readahead(int fd, off_t *offset, size_t count);

يُستخدم هذا التنسيق عندما تضمن وحدات ماكرو اختبار الميزات ظهور تعريفات الدوال الصحيحة، ولا يتم تعريف وحدات الماكرو افتراضيًا.

وحدات ماكرو اختبار الميزات التي تفهمها glibc¶

تشرح الفقرات أدناه كيفية معالجة وحدات ماكرو اختبار الميزات في glibc 2.x، x > 0.

أولاً، مع ذلك، ملخص لبعض التفاصيل لغير الصبورين:

•

الماكروات التي تحتاج غالبًا لاستخدامها في الشيفرة المصدرية الحديثة هي _POSIX_C_SOURCE (للتعريفات من إصدارات مختلفة من POSIX.1)، و_XOPEN_SOURCE (للتعريفات من إصدارات مختلفة من SUS)، و_GNU_SOURCE (لأمور GNU و/أو لينكس الخاصة)، و_DEFAULT_SOURCE (للحصول على تعريفات تُقدم عادةً بشكل مبدئي).

•

تُعرف بعض الماكروات بقيم مبدئية. لذا، على الرغم من أن ماكروًا واحدًا أو أكثر قد يُشار إليه كمطلوب في SYNOPSIS لصفحة دليل، فقد لا يكون من الضروري تعريفها صراحةً. تُعطى التفاصيل الكاملة للمبدئيات لاحقًا في صفحة الدليل هذه.

•

تعريف _XOPEN_SOURCE بقيمة 600 أو أكبر يُنتج نفس التأثيرات كتعريف _POSIX_C_SOURCE بقيمة 200112L أو أكبر. حيث يُرى

_POSIX_C_SOURCE >= 200112L
    

في متطلبات ماكرو اختبار الميزات في SYNOPSIS لصفحة دليل، يُفهم ضمنيًا أن التالي له نفس التأثير:

_XOPEN_SOURCE >= 600
    

•

تعريف _XOPEN_SOURCE بقيمة 700 أو أكبر يُنتج نفس التأثيرات كتعريف _POSIX_C_SOURCE بقيمة 200809L أو أكبر. حيث يُرى

_POSIX_C_SOURCE >= 200809L
    

في متطلبات ماكرو اختبار الميزات في SYNOPSIS لصفحة دليل، يُفهم ضمنيًا أن التالي له نفس التأثير:

_XOPEN_SOURCE >= 700
    

يفهم glibc ماكروات اختبار الميزات التالية:

__STRICT_ANSI__

C القياسي ISO. يُعرف هذا الماكرو ضمنيًا بواسطة gcc(1) عند استدعائه مع، على سبيل المثال، العلم -std=c99 أو -ansi.

_POSIX_C_SOURCE

تعريف هذا الماكرو يتسبب في كشف ملفات الرأس للتعريفات كما يلي:

_POSIX_SOURCE

تعريف هذا الماكرو القديم بأي قيمة يعادل تعريف _POSIX_C_SOURCE بالقيمة 1.

بما أن هذا الماكرو قديم، لا يُوثق استخدامه عمومًا عند مناقشة متطلبات ماكرو اختبار الميزات في صفحات الدليل.

_XOPEN_SOURCE

تعريف هذا الماكرو يتسبب في كشف ملفات الرأس للتعريفات كما يلي:

إذا لم يُعرف __STRICT_ANSI__، أو عُرف _XOPEN_SOURCE بقيمة أكبر من أو تساوي 500 و لم يُعرف صراحةً لا _POSIX_SOURCE ولا _POSIX_C_SOURCE، فإن الكليّات التالية تُعرف ضمنيًا:

بالإضافة إلى ذلك، تعريف _XOPEN_SOURCE بقيمة 500 أو أكبر يُنتج نفس التأثيرات كتعريف _XOPEN_SOURCE_EXTENDED.

_XOPEN_SOURCE_EXTENDED

إذا عُرفت هذه الكلية، و عُرف _XOPEN_SOURCE، فتُظهر تعريفات مقابلة لامتدادات UNIX XPG4v2 (SUSv1) (UNIX 95). تعريف _XOPEN_SOURCE بقيمة 500 أو أكثر يُنتج أيضًا نفس التأثير كتعريف _XOPEN_SOURCE_EXTENDED. يجب تجنب استخدام _XOPEN_SOURCE_EXTENDED في شيفرة مصدرية جديدة.

بما أن تعريف _XOPEN_SOURCE بقيمة 500 أو أكثر له نفس تأثير تعريف _XOPEN_SOURCE_EXTENDED، فإن الكلية الأخيرة (المهجورة) لاختبار الميزة لا تُوصف عمومًا في SYNOPSIS في صفحات الدليل.

_ISOC99_SOURCE (منذ glibc 2.1.3)

يكشف عن التصريحات المتوافقة مع معيار ISO C99.

الإصدارات الأقدم من glibc 2.1.x تعرفت على كليّة مكافئة باسم _ISOC9X_SOURCE (لأن معيار C99 لم يكن قد أُنهي بعد). على الرغم من أن استخدام هذه الكليّة مهمل، إلا أن glibc يستمر في التعرف عليها للتوافق العكسي.

تعريف _ISOC99_SOURCE يكشف أيضًا عن تعريفات ISO C (1990) التعديل 1 ("C95"). (التغيير الرئيسي في C95 كان دعم مجموعات الأحرف الدولية.)

استدعاء مترجم C بالخيار -std=c99 يُنتج نفس التأثيرات كتعريف هذه الكلية.

_ISOC11_SOURCE (منذ glibc 2.16)

تُظهر تصريحات متوافقة مع معيار ISO C11. تعريف هذه الكلية يُفعّل أيضًا ميزات C99 و C95 (مثل _ISOC99_SOURCE).

استدعاء مترجم C بالخيار -std=c11 يُنتج نفس التأثيرات كتعريف هذه الكلية.

_LARGEFILE64_SOURCE

تكشف عن تعريفات لواجهة برمجة التطبيقات البديلة المحددة من قبل LFS (قمة الملفات الكبيرة) كـ "امتداد انتقالي" لمواصفات UNIX الموحدة. (انظر http://opengroup.org/platform/lfs.html.) تتكون واجهة برمجة التطبيقات البديلة من مجموعة من الكائنات الجديدة (أي الدوال والأنواع) التي تُلحق أسماؤها بـ "64" (مثل off64_t مقابل off_t، lseek64() مقابل lseek()، إلخ.). لا ينبغي للبرامج الجديدة استخدام هذا الماكرو؛ بدلاً من ذلك، يجب استخدام _FILE_OFFSET_BITS=64.

_LARGEFILE_SOURCE

تم استخدام هذا الماكرو تاريخيًا لكشف دوال معينة (تحديدًا fseeko(3) و ftello(3)) التي تعالج قيود واجهات برمجة التطبيقات السابقة (fseek(3) و ftell(3)) التي تستخدم long لإزاحات الملف. يتم تعريف هذا الماكرو ضمنيًا إذا تم تعريف _XOPEN_SOURCE بقيمة أكبر من أو تساوي 500. لا ينبغي للبرامج الجديدة استخدام هذا الماكرو؛ تعريف _XOPEN_SOURCE كما هو موصوف أو تعريف _FILE_OFFSET_BITS بالقيمة 64 هو الآلية المفضلة لتحقيق نفس النتيجة.

_FILE_OFFSET_BITS

تعريف هذا الماكرو بالقيمة 64 يحول آليًا المراجع إلى دوال وأنواع بيانات 32 بت المتعلقة بإدخال/إخراج الملف وعمليات نظام الملفات إلى مراجع لنظيراتها 64 بت. هذا مفيد لأداء الإدخال/الإخراج على ملفات كبيرة (أكبر من 2 جيجابايت) على أنظمة 32 بت. كما أنه مفيد عند استدعاء دوال مثل copy_file_range(2) التي أُضيفت مؤخرًا وتأتي فقط بنكهات 64 بت. (تعريف هذا الماكرو يسمح للبرامج المكتوبة بشكل صحيح باستخدام الملفات الكبيرة مع اشتراط إعادة ترجمة فقط.)

تسمح أنظمة 64 بت بطبيعة الحال بأحجام ملفات أكبر من 2 جيجابايت، وليس لهذا الماكرو أي تأثير على تلك الأنظمة.

_TIME_BITS

تعريف هذا الماكرو بالقيمة 64 يُغير عرض time_t(3type) إلى 64 بت مما يسمح بمعالجة الطوابع الزمنية بعد عام 2038. يرتبط ارتباطًا وثيقًا بـ _FILE_OFFSET_BITS وقد يتطلب تعيينه اعتمادًا على التنفيذ. هذا الماكرو متاح اعتبارًا من glibc 2.34.

_BSD_SOURCE (مهمل منذ glibc 2.20)

تعريف هذا الماكرو بأي قيمة يتسبب في كشف ملفات الرأس عن تعريفات مشتقة من BSD.

في إصدارات glibc حتى 2.18، يتسبب تعريف هذا الماكرو أيضًا في تفضيل تعريفات BSD في بعض المواقف حيث تتعارض المعايير، ما لم يتم تعريف واحد أو أكثر من _SVID_SOURCE أو _POSIX_SOURCE أو _POSIX_C_SOURCE أو _XOPEN_SOURCE أو _XOPEN_SOURCE_EXTENDED أو _GNU_SOURCE، وفي هذه الحالة لا تُفضل تعريفات BSD. منذ glibc 2.19، لم يعد _BSD_SOURCE يتسبب في تفضيل تعريفات BSD في حالة التعارضات.

منذ glibc 2.20، هذا الماكرو مهمل. له الآن نفس تأثير تعريف _DEFAULT_SOURCE، لكنه يُنشئ تحذيرًا في وقت الترجمة (ما لم يتم تعريف _DEFAULT_SOURCE أيضًا). استخدم _DEFAULT_SOURCE بدلاً من ذلك. للسماح للكود الذي يتطلب _BSD_SOURCE في glibc 2.19 والإصدارات الأقدم و _DEFAULT_SOURCE في glibc 2.20 والإصدارات الأحدث بالترجمة دون تحذيرات، قم بتعريف كليهما _BSD_SOURCE و _DEFAULT_SOURCE.

_SVID_SOURCE (مهمل منذ glibc 2.20)

تعريف هذا الماكرو بأي قيمة يتسبب في كشف ملفات الرأس عن تعريفات مشتقة من System V. (SVID == تعريف واجهة System V؛ انظر standards(7).)

منذ glibc 2.20، هذا الماكرو مهمل بنفس طريقة _BSD_SOURCE.

_DEFAULT_SOURCE (منذ glibc 2.19)

يمكن تعريف هذا الماكرو لضمان توفير التعريفات "الافتراضية" حتى عندما يتم تعطيل الافتراضيات بخلاف ذلك، كما يحدث عندما يتم تعريف ماكرو فردي بشكل صريح، أو يتم استدعاء المترجم في أحد أوضاعه "القياسية" (مثل cc -std=c99). تعريف _DEFAULT_SOURCE دون تعريف ماكرو فردي آخر أو استدعاء المترجم في أحد أوضاعه "القياسية" ليس له أي تأثير.

تتضمن التعريفات "الافتراضية" تلك المطلوبة بواسطة POSIX.1-2008 و ISO C99، بالإضافة إلى تعريفات متنوعة مشتقة أصلاً من BSD و System V. في glibc 2.19 والإصدارات الأقدم، كانت هذه الافتراضيات مكافئة تقريبًا لتعريف ما يلي بشكل صريح:

cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809
    

_ATFILE_SOURCE (منذ glibc 2.4)

تحديد هذه الكلية بأي قيمة يجعل ملفات الرأس تعرض تصريحات لمجموعة من الدوال ذات اللاحقة "at"؛ انظر openat(2). منذ glibc 2.10، تُعرّف هذه الكلية ضمنيًا أيضًا إذا عُرّفت _POSIX_C_SOURCE بقيمة أكبر من أو تساوي 200809L.

_GNU_SOURCE

تحديد هذه الكلية (بأي قيمة) يُعرّف ضمنيًا _ATFILE_SOURCE، _LARGEFILE64_SOURCE، _ISOC99_SOURCE، _XOPEN_SOURCE_EXTENDED، _POSIX_SOURCE، _POSIX_C_SOURCE بالقيمة 200809L (200112L قبل glibc 2.10؛ 199506L قبل glibc 2.5؛ 199309L قبل glibc 2.1) و _XOPEN_SOURCE بالقيمة 700 (600 قبل glibc 2.10؛ 500 قبل glibc 2.2). بالإضافة إلى ذلك، تُعرض أيضًا إضافات متنوعة خاصة بـ GNU.

منذ glibc 2.19، تحديد _GNU_SOURCE له أيضًا تأثير تعريف _DEFAULT_SOURCE ضمنيًا. قبل glibc 2.20، تحديد _GNU_SOURCE كان له أيضًا تأثير تعريف _BSD_SOURCE و _SVID_SOURCE ضمنيًا.

_REENTRANT

تاريخيًا، في مكتبات C متنوعة، كان من الضروري تعريف هذه الكلية في كل الشيفرة متعددة الخيوط. (قد تظل بعض مكتبات C تتطلب هذا.) في glibc، عرضت هذه الكلية أيضًا تعريفات لدوال معينة قابلة لإعادة الدخول.

مع ذلك، glibc آمن للخيوط مبدئيًا لسنوات عديدة؛ منذ glibc 2.3، التأثير الوحيد لتعريف _REENTRANT هو تمكين تصريح واحد أو اثنين من نفس التصريحات التي تُمكن أيضًا بتعريف _POSIX_C_SOURCE بقيمة 199606L أو أكبر.

_REENTRANT أصبحت الآن مهملة. في glibc 2.25 وما بعده، تعريف _REENTRANT يعادل تعريف _POSIX_C_SOURCE بالقيمة 199606L. إذا اختير مستوى توافق POSIX أعلى بأي وسيلة أخرى (مثل _POSIX_C_SOURCE نفسها، _XOPEN_SOURCE، _DEFAULT_SOURCE، أو _GNU_SOURCE)، فإن تعريف _REENTRANT ليس له أي تأثير.

تُعرّف هذه الكلية آليًا إذا جُمّع باستخدام cc -pthread.

_THREAD_SAFE

مرادف لـ _REENTRANT (المهملة)، مُوفّر للتوافق مع بعض التطبيقات الأخرى.

_FORTIFY_SOURCE (منذ glibc 2.3.4)

تحديد هذه الكلية يُسبب إجراء بعض الفحوصات الخفيفة لاكتشاف بعض أخطار تجاوز سعة المخزن المؤقت عند استخدام دوال متنوعة لمعالجة السلاسل والذاكرة (مثلًا، memcpy(3)، memset(3)، stpcpy(3)، strcpy(3)، strncpy(3)، strcat(3)، strncat(3)، sprintf(3)، snprintf(3)، vsprintf(3)، vsnprintf(3)، gets(3)، ومتغيرات الأحرف العريضة منها). لبعض الدوال، يُفحص تناسق الوسائط؛ مثلًا، يُفحص أن open(2) زُوّد بوسيطة mode عندما تتضمن الأعلام المحددة O_CREAT. لا تُكتشف كل المشكلات، فقط بعض الحالات الشائعة.

إذا ضُبطت _FORTIFY_SOURCE إلى 1، مع مستوى تحسين المترجم 1 (gcc -O1) وما فوق، تُجرى فحوصات لا ينبغي أن تغير سلوك البرامج المطابقة. مع ضبط _FORTIFY_SOURCE إلى 2، يُضاف بعض الفحص الإضافي، لكن بعض البرامج المطابقة قد تفشل.

بعض الفحوصات يمكن إجراؤها في وقت التجميع (عبر منطق الكليات المُنفّذ في ملفات الرأس)، وتنتج عنها تحذيرات المترجم؛ فحوصات أخرى تحدث في وقت التشغيل، وتنتج عنها خطأ في وقت التشغيل إذا فشل الفحص.

مع ضبط _FORTIFY_SOURCE إلى 3، يُضاف فحص إضافي لاعتراض بعض استدعاءات الدوال المستخدمة مع وسيطة ذات حجم متغير حيث يمكن للمترجم استنتاج حد أعلى لقيمتها. مثلًا، برنامج حيث وسيطة الحجم لـ malloc(3) متغيرة يمكن الآن تحصينه.

استخدام هذه الكلية يتطلب دعم المترجم، المتاح منذ gcc 4.0 و clang 2.6. استخدام _FORTIFY_SOURCE المضبوطة إلى 3 يتطلب gcc 12.0 أو أحدث، أو clang 9.0 أو أحدث، بالتزامن مع glibc 2.33 أو أحدث.

التعريفات المبدئية، التعريفات الضمنية، ودمج التعريفات¶

إذا لم تُعرّف أي كليات اختبار ميزات بشكل صريح، فإن كليات اختبار الميزات التالية تُعرّف مبدئيًا: _BSD_SOURCE (في glibc 2.19 وما قبله)، _SVID_SOURCE (في glibc 2.19 وما قبله)، _DEFAULT_SOURCE (منذ glibc 2.19)، _POSIX_SOURCE، و _POSIX_C_SOURCE=200809L (200112L قبل glibc 2.10؛ 199506L قبل glibc 2.4؛ 199309L قبل glibc 2.1).

إذا عُرّف صراحة أي من __STRICT_ANSI__ أو _ISOC99_SOURCE أو _ISOC11_SOURCE (منذ glibc 2.18) أو _POSIX_SOURCE أو _POSIX_C_SOURCE أو _XOPEN_SOURCE أو _XOPEN_SOURCE_EXTENDED (في glibc 2.11 وما قبله) أو _BSD_SOURCE (في glibc 2.19 وما قبله) أو _SVID_SOURCE (في glibc 2.19 وما قبله)، فإن _BSD_SOURCE و_SVID_SOURCE و_DEFAULT_SOURCE لا تُعرّف مبدئيًا.

إذا لم يُعرّف _POSIX_SOURCE و _POSIX_C_SOURCE بشكل صريح، وإما لم يُعرّف __STRICT_ANSI__ أو عُرّف _XOPEN_SOURCE بقيمة 500 أو أكثر، فإن

•

_POSIX_SOURCE تُعرّف بالقيمة 1؛ و

•

_POSIX_C_SOURCE تُعرّف بإحدى القيم التالية:

يمكن تعريف عدة كليات؛ النتائج تراكمية.

مصدر البرنامج¶

/* ftm.c */
#include <stdint.h>
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
#ifdef _POSIX_SOURCE


    printf("_POSIX_SOURCE defined\n");
#endif
#ifdef _POSIX_C_SOURCE


    printf("_POSIX_C_SOURCE defined: %jdL\n",


            (intmax_t) _POSIX_C_SOURCE);
#endif
#ifdef _ISOC99_SOURCE


    printf("_ISOC99_SOURCE defined\n");
#endif
#ifdef _ISOC11_SOURCE


    printf("_ISOC11_SOURCE defined\n");
#endif
#ifdef _XOPEN_SOURCE


    printf("_XOPEN_SOURCE defined: %d\n", _XOPEN_SOURCE);
#endif
#ifdef _XOPEN_SOURCE_EXTENDED


    printf("_XOPEN_SOURCE_EXTENDED defined\n");
#endif
#ifdef _LARGEFILE64_SOURCE


    printf("_LARGEFILE64_SOURCE defined\n");
#endif
#ifdef _FILE_OFFSET_BITS


    printf("_FILE_OFFSET_BITS defined: %d\n", _FILE_OFFSET_BITS);
#endif
#ifdef _TIME_BITS


    printf("_TIME_BITS defined: %d\n", _TIME_BITS);
#endif
#ifdef _BSD_SOURCE


    printf("_BSD_SOURCE defined\n");
#endif
#ifdef _SVID_SOURCE


    printf("_SVID_SOURCE defined\n");
#endif
#ifdef _DEFAULT_SOURCE


    printf("_DEFAULT_SOURCE defined\n");
#endif
#ifdef _ATFILE_SOURCE


    printf("_ATFILE_SOURCE defined\n");
#endif
#ifdef _GNU_SOURCE


    printf("_GNU_SOURCE defined\n");
#endif
#ifdef _REENTRANT


    printf("_REENTRANT defined\n");
#endif
#ifdef _THREAD_SAFE


    printf("_THREAD_SAFE defined\n");
#endif
#ifdef _FORTIFY_SOURCE


    printf("_FORTIFY_SOURCE defined\n");
#endif


    exit(EXIT_SUCCESS);
}