الاسم¶

BIO_read_ex، BIO_write_ex، BIO_read، BIO_write، BIO_gets، BIO_get_line، BIO_puts - دوال الإدخال/الإخراج لـ BIO

موجز¶

 #include <openssl/bio.h>
 int BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes);
 int BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written);
 int BIO_read(BIO *b, void *data, int dlen);
 int BIO_gets(BIO *b, char *buf, int size);
 int BIO_get_line(BIO *b, char *buf, int size);
 int BIO_write(BIO *b, const void *data, int dlen);
 int BIO_puts(BIO *b, const char *buf);

الوصف¶

تحاول BIO_read_ex() قراءة dlen بايت من BIO b وتضع البيانات في data. إذا قُرئت أي بايتات بنجاح، يُخزَّن عدد البايتات المقروءة في *readbytes.

تحاول BIO_write_ex() كتابة dlen بايت من data إلى BIO b. إذا نجحت، يُخزَّن عدد البايتات المكتوبة في *written ما لم يكن written هو NULL.

تحاول BIO_read() قراءة len بايت من BIO b وتضع البيانات في buf.

BIO_gets() تُنفذ عملية "gets" لـ BIO وتضع البيانات في buf. عادةً، ستحاول هذه العملية قراءة سطر من البيانات من BIO بطول أقصى size-1. هناك استثناءات لهذا، مع ذلك؛ على سبيل المثال، BIO_gets() على BIO ملخص ستحسب وتُرجع الملخص وقد لا تدعم BIOs الأخرى BIO_gets() على الإطلاق. السلسلة المُعادة دائمًا منتهية بـ NUL ويُحتفظ بـ '\n' إذا كان موجودًا في بيانات الإدخال. على الإدخال الثنائي، قد تكون هناك أحرف NUL داخل السلسلة؛ في هذه الحالة، قد تُعطي القيمة المُعادة (إذا كانت غير سالبة) طولًا غير صحيح.

BIO_get_line() تحاول القراءة من BIO b سطرًا من البيانات حتى الوصول إلى '\n' التالي أو الوصول إلى الحد الأقصى للطول size-1 وتضع البيانات في buf. السلسلة المُعادة دائمًا منتهية بـ NUL ويُحتفظ بـ '\n' إذا كان موجودًا في بيانات الإدخال. على الإدخال الثنائي، قد تكون هناك أحرف NUL داخل السلسلة؛ في هذه الحالة، تُعطي القيمة المُعادة (إذا كانت غير سالبة) الطول الفعلي المقروء. لتنفيذ هذا، للأسف، يجب قراءة البيانات بايتًا بايتًا.

تحاول BIO_write() كتابة len بايت من buf إلى BIO b.

BIO_puts() تحاول كتابة سلسلة منتهية بـ NUL buf إلى BIO b، بدون البايت NUL الختامي وبدون إلحاق '\n' (لذا، مشابهة لـ fputs(3)، وليس puts(3)).

القيم المُرجعة¶

تُعيد BIO_read_ex() 1 إذا قُرئت البيانات بنجاح، و0 خلاف ذلك.

تُعيد BIO_write_ex() 1 إذا لم يُواجه خطأ في كتابة البيانات، و0 خلاف ذلك. طلب كتابة 0 بايت لا يُعتبر خطأ.

تُعيد BIO_write() -2 إذا لم تُنفَّذ عملية "write" بواسطة BIO أو -1 في أخطاء أخرى. خلاف ذلك، تُعيد عدد البايتات المكتوبة. قد يكون هذا 0 إذا كان BIO b هو NULL أو dlen <= 0.

تُعيد BIO_gets() -2 إذا لم تُنفَّذ عملية "gets" بواسطة BIO أو -1 في أخطاء أخرى. خلاف ذلك، تُعيد عادةً كمية البيانات المقروءة، ولكن اعتمادًا على التنفيذ، قد تُعيد فقط الطول حتى أول حرف NUL موجود في البيانات المقروءة. في أي حال، لا يُضمَّن NUL اللاحق الذي يُضاف بعد البيانات المقروءة في الطول المُعاد.

جميع الدوال الأخرى تُعيد إما كمية البيانات المقروءة أو المكتوبة بنجاح (إذا كانت القيمة المُعادة موجبة) أو أن لا بيانات قُرئت أو كُتبت بنجاح إذا كانت النتيجة 0 أو -1. إذا كانت القيمة المُعادة -2، فإن العملية لم تُنفَّذ في نوع BIO المحدد.

ملاحظات¶

إعادة 0 أو -1 ليست بالضرورة مؤشرًا على خطأ. على وجه الخصوص، عندما يكون المصدر/المستقبل غير محظور أو من نوع معين، قد يكون مجرد مؤشر على أن لا بيانات متاحة حاليًا وأن التطبيق يجب أن يعيد محاولة العملية لاحقًا.

إحدى التقنيات المستخدمة أحيانًا مع المقابس المحظورة هي استخدام استدعاء نظام (مثل select() أو poll() أو ما يعادله) لتحديد متى تكون البيانات متاحة ثم استدعاء read() لقراءة البيانات. المكافئ مع BIOs (أي استدعاء select() على بنية الإدخال/الإخراج الأساسية ثم استدعاء BIO_read() لقراءة البيانات) يجب لا يُستخدم لأن استدعاء واحد لـ BIO_read() يمكن أن يسبب عدة قراءات (وكتابات في حالة BIOs SSL) على بنية الإدخال/الإخراج الأساسية وقد يحظر نتيجة لذلك. بدلاً من ذلك، يجب دمج select() (أو ما يعادله) مع إدخال/إخراج غير محظور بحيث تطلب القراءات المتتالية إعادة محاولة بدلاً من الحظر.

انظر BIO_should_retry(3) للتفاصيل حول كيفية تحديد سبب إعادة المحاولة ومشكلات الإدخال/الإخراج الأخرى.

إذا لم تكن طريقة "gets" مدعومة من BIO، فيمكن استخدام BIO_get_line(). من الممكن أيضًا جعل BIO_gets() قابلة للاستخدام حتى لو لم تكن طريقة "gets" مدعومة بإضافة BIO تخزين مؤقت BIO_f_buffer(3) إلى السلسلة.

انظر أيضًا¶

BIO_should_retry(3)

التاريخ¶

BIO_gets() في الإصدار 1.1.0 والأقدم عند استدعائها على BIO القائم على BIO_fd() لم تحتفظ بـ '\n' في نهاية السطر في المخزن المؤقت.

BIO_get_line() أُضيفت في OpenSSL 3.0.

BIO_write_ex() تُرجع 1 إذا كان حجم البيانات المراد كتابتها هو 0 ويمكن أن تكون المعلمة written للدالة NULL منذ OpenSSL 3.0.

حقوق النسخ¶

حقوق النشر 2000-2026 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

مرخص بموجب رخصة Apache 2.0 (المشار إليها فيما يلي بـ ”الرخصة“). لا يجوز لك استخدام هذا الملف إلا وفقًا لشروط الرخصة. يمكنك الحصول على نسخة منها في الملف LICENSE الموجود في حزمة التوزيع المصدرية أو على الرابط <https://www.openssl.org/source/license.html>.

ترجمة¶

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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