.\" -*- coding: UTF-8 -*- .\" Copyright 1990-1993, The Regents of the University of California. .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: BSD-4-Clause-UC .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH dbopen 3 "17 مايو 2025" "صفحات دليل لينكس 6.18" .UC 7 .SH الاسم dbopen \- دوال الوصول إلى قواعد البيانات .SH المكتبة مكتبة سي المعيارية (\fIlibc\fP،\ \fI\-lc\fP) .SH موجز .nf \fB#include \fP \fB#include \fP \fB#include \fP \fB#include \fP .P \fBDB *dbopen(const char *\fP\fIpath\fP\fB, int \fP\fIflags\fP\fB, int \fP\fImode\fP\fB, DBTYPE \fP\fItype\fP\fB,\fP \fB const void *\fP\fIopeninfo\fP\fB);\fP .fi .SH الوصف \fIملاحظة جيدة\fP: توثق هذه الصفحة الواجهات المقدمة حتى glibc 2.1. ومنذ الإصدار glibc 2.2، لم تعد glibc توفر هذه الواجهات. من المحتمل أنك تبحث عن واجهات برمجة التطبيقات (APIs) التي توفرها مكتبة \fIlibdb\fP بدلاً من ذلك. .P \fBdbopen\fP() هي واجهة المكتبة لملفات قواعد البيانات. صيغ الملفات المدعومة هي btree، و hashed، والملفات الموجهة لـ UNIX. صيغة btree هي تمثيل لبنية شجرية مرتبة ومتوازنة. صيغة hashed هي مخطط تجزئة ديناميكي قابل للتوسع. صيغة الملف المسطح هي ملف تيار بايت بسجلات ذات طول ثابت أو متغير. تُوصف الصيغ والمعلومات الخاصة بكل صيغة ملف بالتفصيل في صفحات الدليل الخاصة بها \fBbtree\fP(3)، و \fBhash\fP(3)، و \fBrecno\fP(3). .P \fBdbopen\fP() تفتح \fIpath\fP للقراءة و/أو الكتابة. يمكن إنشاء ملفات غير مخصصة للحفظ على القرص بضبط معامل \fIpath\fP إلى NULL. .P .\"Three additional options may be specified by ORing .\"them into the .\".I flags .\"argument. .\".TP .\"DB_LOCK .\"Do the necessary locking in the database to support concurrent access. .\"If concurrent access isn't needed or the database is read-only this .\"flag should not be set, as it tends to have an associated performance .\"penalty. .\".TP .\"DB_SHMEM .\"Place the underlying memory pool used by the database in shared .\"memory. .\"Necessary for concurrent access. .\".TP .\"DB_TXN .\"Support transactions in the database. .\"The DB_LOCK and DB_SHMEM flags must be set as well. معاملات \fIflags\fP و \fImode\fP هي كما هو محدد لدالة \fBopen\fP(2)، ولكن فقط الأعلام \fBO_CREAT\fP، و \fBO_EXCL\fP، و \fBO_EXLOCK\fP، و \fBO_NONBLOCK\fP، و \fBO_RDONLY\fP، و \fBO_RDWR\fP، و \fBO_SHLOCK\fP، و \fBO_TRUNC\fP ذات معنى. (ملاحظة، فتح ملف قاعدة بيانات بـ \fBO_WRONLY\fP غير ممكن.) .P معامل \fItype\fP هو من نوع \fIDBTYPE\fP (كما هو معرف في ملف التضمين \fI\fP) ويمكن ضبطه إلى \fBDB_BTREE\fP، أو \fBDB_HASH\fP، أو \fBDB_RECNO\fP. .P معامل \fIopeninfo\fP هو مؤشر لبنية خاصة بطريقة الوصول موصوفة في صفحة دليل طريقة الوصول. إذا كان \fIopeninfo\fP هو NULL، فستستخدم كل طريقة وصول مبدئيات مناسبة للنظام وطريقة الوصول. .P \fBdbopen\fP() تُرجع مؤشرًا لبنية \fIDB\fP عند النجاح و NULL عند الخطأ. بنية \fIDB\fP معرّفة في ملف التضمين \fI\fP، وتحتوي على الأقل على الحقول التالية: .P .in +4n .EX typedef struct { DBTYPE type; int (*close)(const DB *db); int (*del)(const DB *db, const DBT *key, unsigned int flags); int (*fd)(const DB *db); int (*get)(const DB *db, DBT *key, DBT *data, unsigned int flags); int (*put)(const DB *db, DBT *key, const DBT *data, unsigned int flags); int (*sync)(const DB *db, unsigned int flags); int (*seq)(const DB *db, DBT *key, DBT *data, unsigned int flags); } DB; .EE .in .P تصف هذه العناصر نوع قاعدة بيانات ومجموعة دوال تؤدي إجراءات متنوعة. تأخذ هذه الدوال مؤشرًا لبنية كما هو مُرجَع من \fBdbopen\fP()، وأحيانًا مؤشرًا واحدًا أو أكثر لبنى مفتاح/بيانات وقيمة علم. .TP \fItype\fP نوع طريقة الوصول الأساسية (وصيغة الملف). .TP \fIclose\fP مؤشر لدالة لتفريغ أي معلومات مخبأة إلى القرص، وتحرير أي موارد مخصصة، وإغلاق الملف (الملفات) الأساسية. نظرًا لأن أزواج المفتاح/البيانات قد تُخبأ في الذاكرة، فإن الفشل في مزامنة الملف مع دالة \fIclose\fP أو \fIsync\fP قد يؤدي إلى معلومات غير متناسقة أو مفقودة. تُرجع دوال \fIclose\fP \-1 عند الخطأ (ضبط \fIerrno\fP) و 0 عند النجاح. .TP \fIdel\fP مؤشر لدالة لإزالة أزواج المفتاح/البيانات من قاعدة البيانات. .IP يمكن ضبط معامل \fIflag\fP إلى القيمة التالية: .RS .TP \fBR_CURSOR\fP احذف السجل المشار إليه بالمؤشر. يجب أن يكون المؤشر قد هُيئ مسبقًا. .RE .IP تُرجع دوال \fIdelete\fP \-1 عند الخطأ (ضبط \fIerrno\fP)، و 0 عند النجاح، و 1 إذا لم يكن \fIkey\fP المحدد موجودًا في الملف. .TP \fIfd\fP مؤشر إلى روتين يُعيد واصف ملف ممثلًا لقاعدة البيانات الأساسية. سيُعاد واصف ملف يُشير إلى نفس الملف لجميع العمليات التي تستدعي \fBdbopen\fP() بنفس اسم الملف \fIpath\fP. يمكن استخدام واصف الملف هذا بأمان كمعامل لدوال القفل \fBfcntl\fP(2) و \fBflock\fP(2). لا يرتبط واصف الملف بالضرورة بأي من الملفات الأساسية المستخدمة بواسطة طريقة الوصول. لا يتوفر واصف ملف لقواعد البيانات في الذاكرة. تُعيد روتينات \fIfd\fP \-1 عند الخطأ (ضبط \fIerrno\fP)، وواصف الملف عند النجاح. .TP \fIget\fP مؤشر إلى دالة تمثل الواجهة لاسترجاع المفاتيح من قاعدة البيانات. يُعاد عنوان وطول البيانات المرتبطة بالمفتاح المُحدد \fIkey\fP في البنية المشار إليها بواسطة \fIdata\fP. تُرجع دوال \fIget\fP \-1 عند الخطأ (مع ضبط \fIerrno\fP)، و0 عند النجاح، و1 إذا لم يكن \fIkey\fP موجودًا في الملف. .TP \fIput\fP مؤشر إلى دالة لتخزين أزواج المفتاح/البيانات في قاعدة البيانات. .IP يمكن ضبط المعامل \fIflag\fP على إحدى القيم التالية: .RS .TP \fBR_CURSOR\fP استبدال زوج المفتاح/البيانات المشار إليه بواسطة المؤشر. يجب أن يكون المؤشر قد تمت تهيئته مسبقًا. .TP \fBR_IAFTER\fP إلحاق البيانات فورًا بعد البيانات المشار إليها بواسطة \fIkey\fP، مع إنشاء زوج مفتاح/بيانات جديد. يُعاد رقم السجل لزوج المفتاح/البيانات المُلحق في بنية \fIkey\fP. (ينطبق فقط على أسلوب الوصول \fBDB_RECNO\fP.) .TP \fBR_IBEFORE\fP إدراج البيانات فورًا قبل البيانات المشار إليها بواسطة \fIkey\fP، مع إنشاء زوج مفتاح/بيانات جديد. يُعاد رقم السجل لزوج المفتاح/البيانات المُدرج في بنية \fIkey\fP. (ينطبق فقط على أسلوب الوصول \fBDB_RECNO\fP.) .TP \fBR_NOOVERWRITE\fP إدخال زوج المفتاح/البيانات الجديد فقط إذا لم يكن المفتاح موجودًا مسبقًا. .TP \fBR_SETCURSOR\fP تخزين زوج المفتاح/البيانات، مع ضبط أو تهيئة موضع المؤشر للإشارة إليه. (ينطبق فقط على أسلوبي الوصول \fBDB_BTREE\fP و\fBDB_RECNO\fP.) .RE .IP \fBR_SETCURSOR\fP متاح فقط لأسلوبي الوصول \fBDB_BTREE\fP و\fBDB_RECNO\fP لأنه يفترض أن المفاتيح لها ترتيب جوهري لا يتغير. .IP \fBR_IAFTER\fP و\fBR_IBEFORE\fP متاحان فقط لأسلوب الوصول \fBDB_RECNO\fP لأن كلًا منهما يفترض أن أسلوب الوصول قادر على إنشاء مفاتيح جديدة. هذا صحيح فقط إذا كانت المفاتيح مرتبة ومستقلة، مثل أرقام السجلات. .IP السلوك المبدئي لدوال \fIput\fP هو إدخال زوج المفتاح/البيانات الجديد، مع استبدال أي مفتاح موجود مسبقًا. .IP تُرجع دوال \fIput\fP \-1 عند الخطأ (مع ضبط \fIerrno\fP)، و0 عند النجاح، و1 إذا تم ضبط \fBR_NOOVERWRITE\fP \fIflag\fP وكان المفتاح موجودًا بالفعل في الملف. .TP \fIseq\fP مؤشر إلى دالة تمثل الواجهة للاسترجاع التسلسلي من قاعدة البيانات. يُعاد عنوان وطول المفتاح في البنية المشار إليها بواسطة \fIkey\fP، ويُعاد عنوان وطول البيانات في البنية المشار إليها بواسطة \fIdata\fP. .IP يمكن بدء الاسترجاع التسلسلي لأزواج المفتاح/البيانات في أي وقت، ولا يتأثر موضع "المؤشر" باستدعاءات دوال \fIdel\fP أو \fIget\fP أو \fIput\fP أو \fIsync\fP. ستنعكس التعديلات على قاعدة البيانات أثناء المسح التسلسلي في المسح، أي أن السجلات المُدرجة خلف المؤشر لن تُعاد بينما ستُعاد السجلات المُدرجة أمام المؤشر. .IP \fBيجب\fP تعيين قيمة العلامة إلى إحدى القيم التالية: .RS .TP \fBR_CURSOR\fP تُعاد البيانات المرتبطة بالمفتاح المُحدد. يختلف هذا عن دوال \fIget\fP في أنه يضبط أو يهيئ المؤشر إلى موقع المفتاح أيضًا. (ملاحظة: بالنسبة لطريقة الوصول \fBDB_BTREE\fP، فإن المفتاح المُعاد ليس بالضرورة مطابقًا تمامًا للمفتاح المُحدد. المفتاح المُعاد هو أصغر مفتاح أكبر من أو يساوي المفتاح المُحدد، مما يسمح بمطابقات جزئية للمفاتيح وبحوث النطاق.) .TP \fBR_FIRST\fP يُعاد أول زوج مفتاح/بيانات من قاعدة البيانات، ويُضبط المؤشر أو يُهيأ للإشارة إليه. .TP \fBR_LAST\fP يُعاد آخر زوج مفتاح/بيانات من قاعدة البيانات، ويُضبط المؤشر أو يُهيأ للإشارة إليه. (ينطبق فقط على طريقتي الوصول \fBDB_BTREE\fP و \fBDB_RECNO\fP.) .TP \fBR_NEXT\fP استرجع زوج المفتاح/البيانات مباشرة بعد المؤشر. إذا لم يُضبط المؤشر بعد، فهذا مماثل للعلامة \fBR_FIRST\fP. .TP \fBR_PREV\fP استرجع زوج المفتاح/البيانات مباشرة قبل المؤشر. إذا لم يُضبط المؤشر بعد، فهذا مماثل للعلامة \fBR_LAST\fP. (ينطبق فقط على طريقتي الوصول \fBDB_BTREE\fP و \fBDB_RECNO\fP.) .RE .IP \fBR_LAST\fP و \fBR_PREV\fP متاحان فقط لطريقتي الوصول \fBDB_BTREE\fP و \fBDB_RECNO\fP لأن كل منهما يفترض أن للمفاتيح ترتيبًا جوهريًا لا يتغير. .IP تُرجع دوال \fIseq\fP \-1 عند الخطأ (مع تعيين \fIerrno\fP)، و0 عند النجاح، و1 إذا لم تكن هناك أزواج مفتاح/بيانات أصغر من أو أكبر من المفتاح المُحدد أو الحالي. إذا كانت طريقة الوصول \fBDB_RECNO\fP قيد الاستخدام، وكان ملف قاعدة البيانات ملفًا خاصًا بالأحرف ولا تتوفر أزواج مفتاح/بيانات كاملة حاليًا، تُرجع دوال \fIseq\fP 2. .TP \fIsync\fP مؤشر إلى دالة لتفريغ أي معلومات مخبأة إلى القرص. إذا كانت قاعدة البيانات في الذاكرة فقط، فإن دالة \fIsync\fP ليس لها تأثير وستنجح دائمًا. .IP يمكن تعيين قيمة العلامة إلى القيمة التالية: .RS .TP \fBR_RECNOSYNC\fP إذا كانت طريقة الوصول \fBDB_RECNO\fP قيد الاستخدام، تتسبب هذه العلامة في تطبيق دالة المزامنة على ملف btree الذي يقوم عليه ملف recno، وليس على ملف recno نفسه. (انظر حقل \fIbfname\fP في صفحة الدليل \fBrecno\fP(3) لمزيد من المعلومات.) .RE .IP تُرجع دوال \fIsync\fP \-1 عند الخطأ (مع تعيين \fIerrno\fP) و0 عند النجاح. .SS "أزواج المفتاح/البيانات" الوصول إلى جميع أنواع الملفات يعتمد على أزواج المفتاح/البيانات. يتم تمثيل كل من المفاتيح والبيانات بواسطة بنية البيانات التالية: .P .in +4n .EX typedef struct { void *data; size_t size; } DBT; .EE .in .P يُعرّف عناصر بنية \fIDBT\fP كما يلي: .TP \fIdata\fP مؤشر إلى سلسلة محارف. .TP \fIsize\fP طول سلسلة المحارف. .P قد تشير سلاسل محارف المفتاح والبيانات إلى سلاسل ذات طول غير محدود جوهريًا، على الرغم من أن أي اثنين منها يجب أن يتسعا في الذاكرة المتاحة في نفس الوقت. تجدر الإشارة إلى أن طرق الوصول لا تقدم أي ضمانات حول محاذاة سلسلة المحارف. .SH الأخطاء قد تفشل روتين \fBdbopen\fP() وتضبط \fIerrno\fP لأي من الأخطاء المحددة لروتينات المكتبة \fBopen\fP(2) و \fBmalloc\fP(3) أو ما يلي: .TP \fBEFTYPE\fP ملف ذو تنسيق غير صحيح. .TP \fBEINVAL\fP تم تحديد معامل (دالة تجزئة، بايت حشو، إلخ) غير متوافق مع مواصفات الملف الحالية أو غير ذي معنى للدالة (على سبيل المثال، استخدام المؤشر دون تهيئة مسبقة) أو يوجد عدم تطابق بين رقم إصدار الملف والبرنامج. .P قد تفشل روتينات \fIclose\fP وتضبط \fIerrno\fP لأي من الأخطاء المحددة لروتينات المكتبة \fBclose\fP(2)، \fBread\fP(2)، \fBwrite\fP(2)، \fBfree\fP(3)، أو \fBfsync\fP(2). .P قد تفشل روتينات \fIdel\fP، \fIget\fP، \fIput\fP، و \fIseq\fP وتضبط \fIerrno\fP لأي من الأخطاء المحددة لروتينات المكتبة \fBread\fP(2)، \fBwrite\fP(2)، \fBfree\fP(3)، أو \fBmalloc\fP(3). .P ستفشل روتينات \fIfd\fP وتضبط \fIerrno\fP إلى \fBENOENT\fP لقواعد البيانات في الذاكرة. .P قد تفشل روتينات \fIsync\fP وتضبط \fIerrno\fP لأي من الأخطاء المحددة لروتين المكتبة \fBfsync\fP(2). .SH العلل الاسم المستعار \fIDBT\fP هو اختصار لـ "data base thang"، واستُخدم لأنه لم يستطع أحد التفكير في اسم معقول غير مستخدم بالفعل. .P واجهة واصف الملف هي حل مؤقت وسيُحذف في إصدار مستقبلي من الواجهة. .P لا توفر أي من طرق الوصول أي شكل من أشكال الوصول المتزامن أو القفل أو المعاملات. .SH "انظر أيضًا" \fBbtree\fP(3), \fBhash\fP(3), \fBmpool\fP(3), \fBrecno\fP(3) .P \fILIBTP: Portable, Modular Transactions for UNIX\fP، مارغو سيلتزر، مايكل أولسون، وقائع USENIX، شتاء 1992. .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .