getrandom(2)

الاسم
getrandom - الحصول على سلسلة من البايتات العشوائية

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

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

ssize_t getrandom(size_t size;
                  void buf[size], size_t size, unsigned int flags);

الوصف
استدعاء النظام getrandom() يملأ المخزن المؤقت المشار إليه بـ buf بما يصل إلى size بايت عشوائي. يمكن استخدام هذه البايتات لتغذية مولدات الأرقام العشوائية في مساحة المستخدم أو لأغراض التشفير.

مبدئيًا، يسحب getrandom() الإنتروبيا من مصدر urandom (أي نفس مصدر الجهاز /dev/urandom). يمكن تغيير هذا السلوك عبر وسيط flags.

إذا يُهيئ مصدر urandom، فإن القراءات التي تصل إلى 256 بايت ستعيد دائمًا عدد البايتات المطلوبة ولن تقاطعها الإشارات. لا تنطبق هذه الضمانات على أحجام المخازن الأكبر. على سبيل المثال، إذا قاطع معالج إشارة الاستدعاء، فقد يعيد مخزنًا ممتلئًا جزئيًا، أو يفشل مع الخطأ EINTR.

إذا لم يُهيئ مصدر urandom بعد، فسيحظر getrandom()، ما لم يتم تحديد GRND_NONBLOCK في flags.

وسيط flags هو قناع بت يمكن أن يحتوي على صفر أو أكثر من القيم التالية مجمعة بـ OR:

GRND_RANDOM
    إذا عُينت هذه البتة، فسيتم سحب البايتات العشوائية من مصدر random (أي نفس مصدر الجهاز /dev/random) بدلاً من مصدر urandom. مصدر random محدود بناءً على الإنتروبيا التي يمكن الحصول عليها من الضوضاء البيئية. إذا كان عدد البايتات المتاحة في مصدر random أقل من المطلوب في size، يعيد الاستدعاء البايتات العشوائية المتاحة فقط. إذا لم تكن هناك بايتات عشوائية متاحة، يعتمد السلوك على وجود GRND_NONBLOCK في وسيط flags.

GRND_NONBLOCK
    مبدئيًا، عند القراءة من مصدر random، يحظر getrandom() إذا لم تكن هناك بايتات عشوائية متاحة، وعند القراءة من مصدر urandom، يحظر إذا لم يتم تهيئة تجمع الإنتروبيا بعد. إذا تم تعيين العلم GRND_NONBLOCK، فإن getrandom() لا يحظر في هذه الحالات، بل يعيد فورًا -1 مع تعيين errno إلى EAGAIN.

قيمة الإرجاع
عند النجاح، يعيد getrandom() عدد البايتات التي تم نسخها إلى المخزن المؤقت buf. قد يكون هذا أقل من عدد البايتات المطلوبة عبر size إذا تم تحديد GRND_RANDOM في flags وكانت الإنتروبيا غير كافية في مصدر random أو إذا قاطع إشارة استدعاء النظام.

عند الخطأ، تُعاد القيمة -1، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

EAGAIN
    الإنتروبيا المطلوبة لم تكن متاحة، وكان getrandom() سيحظر إذا لم يتم تعيين العلم GRND_NONBLOCK.

EFAULT
    العنوان المشار إليه بـ buf خارج مساحة العنوان القابلة للوصول.

EINTR
    قاطع معالج إشارة الاستدعاء؛ انظر وصف كيفية معالجة استدعاءات read(2) المقاطعة على الأجهزة "البطيئة" مع وبدون العلم SA_RESTART في صفحة الدليل signal(7).

EINVAL
    تم تحديد علم غير صالح في flags.

ENOSYS
    حددت دالة الغلاف glibc لـ getrandom() أن النواة الأساسية لا تنفذ استدعاء النظام هذا.

المعايير
لينكس.

التاريخ
Linux 3.17, glibc 2.25.

ملاحظات
للحصول على نظرة عامة ومقارنة للواجهات المختلفة التي يمكن استخدامها للحصول على العشوائية، راجع random(7).

على عكس /dev/random و /dev/urandom، لا يتضمن getrandom() استخدام أسماء المسارات أو واصفات الملفات. وبالتالي، يمكن أن يكون getrandom() مفيدًا في الحالات التي يجعل فيها chroot(2) أسماء مسارات /dev غير مرئية، وحيث يغلق تطبيق (مثل خفي أثناء بدء التشغيل) واصف ملف لأحد هذه الملفات الذي فتحته مكتبة.

  الحد الأقصى لعدد البايتات المعادة
اعتبارًا من Linux 3.19، تنطبق الحدود التالية:

•   عند القراءة من مصدر urandom، يعيد استدعاء واحد لـ getrandom() حدًا أقصى يبلغ 32Mi-1 بايت على الأنظمة التي يكون فيها حجم int 32 بت.

•   عند القراءة من مصدر random، يعيد حدًا أقصى يبلغ 512 بايت.

  المقاطعة بواسطة معالج إشارة
عند القراءة من مصدر urandom (لم يتم تعيين GRND_RANDOM)، سيحظر getrandom() حتى يتم تهيئة تجمع الإنتروبيا (ما لم يتم تحديد العلم GRND_NONBLOCK). إذا تم تقديم طلب لقراءة عدد كبير من البايتات (أكثر من 256)، سيحظر getrandom() حتى يتم إنشاء تلك البايتات ونقلها من ذاكرة النواة إلى buf. عند القراءة من مصدر random (تم تعيين GRND_RANDOM)، سيحظر getrandom() حتى تصبح بعض البايتات العشوائية متاحة (ما لم يتم تحديد العلم GRND_NONBLOCK).

يعتمد السلوك عندما يقاطع معالج إشارة استدعاء لـ getrandom() محظور أثناء القراءة من مصدر urandom على حالة تهيئة مخزن الإنتروبيا وحجم الطلب size. إذا لم يتم تهيئة الإنتروبيا بعد، يفشل الاستدعاء مع الخطأ EINTR. إذا تم تهيئة تجمع الإنتروبيا وكان حجم الطلب كبيرًا (size > 256)، إما أن ينجح الاستدعاء، معيدًا مخزنًا ممتلئًا جزئيًا، أو يفشل مع الخطأ EINTR. إذا تم تهيئة تجمع الإنتروبيا وكان حجم الطلب صغيرًا (size <= 256)، فلن يفشل getrandom() مع EINTR. بدلاً من ذلك، سيعيد جميع البايتات التي تم طلبها.

عند القراءة من مصدر random، يمكن لمعالج إشارة مقاطعة طلبات الحظر من أي حجم (يفشل الاستدعاء مع الخطأ EINTR).

استخدام getrandom() لقراءة مخازن صغيرة (<= 256 بايت) من مصدر urandom هو وضع الاستخدام المفضل.

المعالجة الخاصة للقيم الصغيرة لـ size صُممت للتوافق مع getentropy(3) الخاص بـ OpenBSD، والذي تدعمه glibc حاليًا.

يجب على مستخدم getrandom() أن يتحقق دائمًا من القيمة المُرجَعة، لتحديد ما إذا حدث خطأ أو تم إرجاع عدد بايتات أقل من المطلوب. في الحالة التي لا يُحدد فيها GRND_RANDOM وكانت size أقل من أو تساوي 256، لا ينبغي أبدًا أن يحدث إرجاع عدد بايتات أقل من المطلوب، لكن المبرمج الحريص سيتحقق من ذلك على أي حال!

العلل
اعتبارًا من Linux 3.19، يوجد الخلل التالي:

•   اعتمادًا على حمل وحدة المعالجة المركزية، لا يستجيب getrandom() للمقاطعات قبل قراءة جميع البايتات المطلوبة.

انظر أيضًا
getentropy(3)، random(4)، urandom(4)، random(7)، signal(7)

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

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

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