dbopen(3)

الاسم
dbopen - دوال الوصول إلى قواعد البيانات

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

موجز
#include <sys/types.h>
#include <limits.h>
#include <db.h>
#include <fcntl.h>

DB *dbopen(const char *path, int flags, int mode, DBTYPE type,
           const void *openinfo);

الوصف
ملاحظة جيدة: توثق هذه الصفحة الواجهات المقدمة حتى glibc 2.1. ومنذ الإصدار glibc 2.2، لم تعد glibc توفر هذه الواجهات. من المحتمل أنك تبحث عن واجهات برمجة التطبيقات (APIs) التي توفرها مكتبة libdb بدلاً من ذلك.

dbopen() هي واجهة المكتبة لملفات قواعد البيانات. صيغ الملفات المدعومة هي btree، و hashed، والملفات الموجهة لـ UNIX. صيغة btree هي تمثيل لبنية شجرية مرتبة ومتوازنة. صيغة hashed هي مخطط تجزئة ديناميكي قابل للتوسع. صيغة الملف المسطح هي ملف تيار بايت بسجلات ذات طول ثابت أو متغير. تُوصف الصيغ والمعلومات الخاصة بكل صيغة ملف بالتفصيل في صفحات الدليل الخاصة بها btree(3)، و hash(3)، و recno(3).

dbopen() تفتح path للقراءة و/أو الكتابة. يمكن إنشاء ملفات غير مخصصة للحفظ على القرص بضبط معامل path إلى NULL.

معاملات flags و mode هي كما هو محدد لدالة open(2)، ولكن فقط الأعلام O_CREAT، و O_EXCL، و O_EXLOCK، و O_NONBLOCK، و O_RDONLY، و O_RDWR، و O_SHLOCK، و O_TRUNC ذات معنى. (ملاحظة، فتح ملف قاعدة بيانات بـ O_WRONLY غير ممكن.)

معامل type هو من نوع DBTYPE (كما هو معرف في ملف التضمين <db.h>) ويمكن ضبطه إلى DB_BTREE، أو DB_HASH، أو DB_RECNO.

معامل openinfo هو مؤشر لبنية خاصة بطريقة الوصول موصوفة في صفحة دليل طريقة الوصول. إذا كان openinfo هو NULL، فستستخدم كل طريقة وصول مبدئيات مناسبة للنظام وطريقة الوصول.

dbopen() تُرجع مؤشرًا لبنية DB عند النجاح و NULL عند الخطأ. بنية DB معرّفة في ملف التضمين <db.h>، وتحتوي على الأقل على الحقول التالية:

    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;

تصف هذه العناصر نوع قاعدة بيانات ومجموعة دوال تؤدي إجراءات متنوعة. تأخذ هذه الدوال مؤشرًا لبنية كما هو مُرجَع من dbopen()، وأحيانًا مؤشرًا واحدًا أو أكثر لبنى مفتاح/بيانات وقيمة علم.

type
    نوع طريقة الوصول الأساسية (وصيغة الملف).

close
    مؤشر لدالة لتفريغ أي معلومات مخبأة إلى القرص، وتحرير أي موارد مخصصة، وإغلاق الملف (الملفات) الأساسية. نظرًا لأن أزواج المفتاح/البيانات قد تُخبأ في الذاكرة، فإن الفشل في مزامنة الملف مع دالة close أو sync قد يؤدي إلى معلومات غير متناسقة أو مفقودة. تُرجع دوال close -1 عند الخطأ (ضبط errno) و 0 عند النجاح.

del مؤشر لدالة لإزالة أزواج المفتاح/البيانات من قاعدة البيانات.

    يمكن ضبط معامل flag إلى القيمة التالية:

    R_CURSOR
        احذف السجل المشار إليه بالمؤشر. يجب أن يكون المؤشر قد هُيئ مسبقًا.

    تُرجع دوال delete -1 عند الخطأ (ضبط errno)، و 0 عند النجاح، و 1 إذا لم يكن key المحدد موجودًا في الملف.

fd  مؤشر إلى روتين يُعيد واصف ملف ممثلًا لقاعدة البيانات الأساسية. سيُعاد واصف ملف يُشير إلى نفس الملف لجميع العمليات التي تستدعي dbopen() بنفس اسم الملف path. يمكن استخدام واصف الملف هذا بأمان كمعامل لدوال القفل fcntl(2) و flock(2). لا يرتبط واصف الملف بالضرورة بأي من الملفات الأساسية المستخدمة بواسطة طريقة الوصول. لا يتوفر واصف ملف لقواعد البيانات في الذاكرة. تُعيد روتينات fd -1 عند الخطأ (ضبط errno)، وواصف الملف عند النجاح.

get مؤشر إلى دالة تمثل الواجهة لاسترجاع المفاتيح من قاعدة البيانات. يُعاد عنوان وطول البيانات المرتبطة بالمفتاح المُحدد key في البنية المشار إليها بواسطة data. تُرجع دوال get -1 عند الخطأ (مع ضبط errno)، و0 عند النجاح، و1 إذا لم يكن key موجودًا في الملف.

put مؤشر إلى دالة لتخزين أزواج المفتاح/البيانات في قاعدة البيانات.

    يمكن ضبط المعامل flag على إحدى القيم التالية:

    R_CURSOR
        استبدال زوج المفتاح/البيانات المشار إليه بواسطة المؤشر. يجب أن يكون المؤشر قد تمت تهيئته مسبقًا.

    R_IAFTER
        إلحاق البيانات فورًا بعد البيانات المشار إليها بواسطة key، مع إنشاء زوج مفتاح/بيانات جديد. يُعاد رقم السجل لزوج المفتاح/البيانات المُلحق في بنية key. (ينطبق فقط على أسلوب الوصول DB_RECNO.)

    R_IBEFORE
        إدراج البيانات فورًا قبل البيانات المشار إليها بواسطة key، مع إنشاء زوج مفتاح/بيانات جديد. يُعاد رقم السجل لزوج المفتاح/البيانات المُدرج في بنية key. (ينطبق فقط على أسلوب الوصول DB_RECNO.)

    R_NOOVERWRITE
        إدخال زوج المفتاح/البيانات الجديد فقط إذا لم يكن المفتاح موجودًا مسبقًا.

    R_SETCURSOR
        تخزين زوج المفتاح/البيانات، مع ضبط أو تهيئة موضع المؤشر للإشارة إليه. (ينطبق فقط على أسلوبي الوصول DB_BTREE وDB_RECNO.)

    R_SETCURSOR متاح فقط لأسلوبي الوصول DB_BTREE وDB_RECNO لأنه يفترض أن المفاتيح لها ترتيب جوهري لا يتغير.

    R_IAFTER وR_IBEFORE متاحان فقط لأسلوب الوصول DB_RECNO لأن كلًا منهما يفترض أن أسلوب الوصول قادر على إنشاء مفاتيح جديدة. هذا صحيح فقط إذا كانت المفاتيح مرتبة ومستقلة، مثل أرقام السجلات.

    السلوك المبدئي لدوال put هو إدخال زوج المفتاح/البيانات الجديد، مع استبدال أي مفتاح موجود مسبقًا.

    تُرجع دوال put -1 عند الخطأ (مع ضبط errno)، و0 عند النجاح، و1 إذا تم ضبط R_NOOVERWRITE flag وكان المفتاح موجودًا بالفعل في الملف.

seq مؤشر إلى دالة تمثل الواجهة للاسترجاع التسلسلي من قاعدة البيانات. يُعاد عنوان وطول المفتاح في البنية المشار إليها بواسطة key، ويُعاد عنوان وطول البيانات في البنية المشار إليها بواسطة data.

    يمكن بدء الاسترجاع التسلسلي لأزواج المفتاح/البيانات في أي وقت، ولا يتأثر موضع "المؤشر" باستدعاءات دوال del أو get أو put أو sync. ستنعكس التعديلات على قاعدة البيانات أثناء المسح التسلسلي في المسح، أي أن السجلات المُدرجة خلف المؤشر لن تُعاد بينما ستُعاد السجلات المُدرجة أمام المؤشر.

    يجب تعيين قيمة العلامة إلى إحدى القيم التالية:

    R_CURSOR
        تُعاد البيانات المرتبطة بالمفتاح المُحدد. يختلف هذا عن دوال get في أنه يضبط أو يهيئ المؤشر إلى موقع المفتاح أيضًا. (ملاحظة: بالنسبة لطريقة الوصول DB_BTREE، فإن المفتاح المُعاد ليس بالضرورة مطابقًا تمامًا للمفتاح المُحدد. المفتاح المُعاد هو أصغر مفتاح أكبر من أو يساوي المفتاح المُحدد، مما يسمح بمطابقات جزئية للمفاتيح وبحوث النطاق.)

    R_FIRST
        يُعاد أول زوج مفتاح/بيانات من قاعدة البيانات، ويُضبط المؤشر أو يُهيأ للإشارة إليه.

    R_LAST
        يُعاد آخر زوج مفتاح/بيانات من قاعدة البيانات، ويُضبط المؤشر أو يُهيأ للإشارة إليه. (ينطبق فقط على طريقتي الوصول DB_BTREE و DB_RECNO.)

    R_NEXT
        استرجع زوج المفتاح/البيانات مباشرة بعد المؤشر. إذا لم يُضبط المؤشر بعد، فهذا مماثل للعلامة R_FIRST.

    R_PREV
        استرجع زوج المفتاح/البيانات مباشرة قبل المؤشر. إذا لم يُضبط المؤشر بعد، فهذا مماثل للعلامة R_LAST. (ينطبق فقط على طريقتي الوصول DB_BTREE و DB_RECNO.)

    R_LAST و R_PREV متاحان فقط لطريقتي الوصول DB_BTREE و DB_RECNO لأن كل منهما يفترض أن للمفاتيح ترتيبًا جوهريًا لا يتغير.

    تُرجع دوال seq -1 عند الخطأ (مع تعيين errno)، و0 عند النجاح، و1 إذا لم تكن هناك أزواج مفتاح/بيانات أصغر من أو أكبر من المفتاح المُحدد أو الحالي. إذا كانت طريقة الوصول DB_RECNO قيد الاستخدام، وكان ملف قاعدة البيانات ملفًا خاصًا بالأحرف ولا تتوفر أزواج مفتاح/بيانات كاملة حاليًا، تُرجع دوال seq 2.

sync
    مؤشر إلى دالة لتفريغ أي معلومات مخبأة إلى القرص. إذا كانت قاعدة البيانات في الذاكرة فقط، فإن دالة sync ليس لها تأثير وستنجح دائمًا.

    يمكن تعيين قيمة العلامة إلى القيمة التالية:

    R_RECNOSYNC
        إذا كانت طريقة الوصول DB_RECNO قيد الاستخدام، تتسبب هذه العلامة في تطبيق دالة المزامنة على ملف btree الذي يقوم عليه ملف recno، وليس على ملف recno نفسه. (انظر حقل bfname في صفحة الدليل recno(3) لمزيد من المعلومات.)

    تُرجع دوال sync -1 عند الخطأ (مع تعيين errno) و0 عند النجاح.

  أزواج المفتاح/البيانات
الوصول إلى جميع أنواع الملفات يعتمد على أزواج المفتاح/البيانات. يتم تمثيل كل من المفاتيح والبيانات بواسطة بنية البيانات التالية:

    typedef struct {
        void  *data;
        size_t size;
    } DBT;

يُعرّف عناصر بنية DBT كما يلي:

data
    مؤشر إلى سلسلة محارف.

size
    طول سلسلة المحارف.

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

الأخطاء
قد تفشل روتين dbopen() وتضبط errno لأي من الأخطاء المحددة لروتينات المكتبة open(2) و malloc(3) أو ما يلي:

EFTYPE
    ملف ذو تنسيق غير صحيح.

EINVAL
    تم تحديد معامل (دالة تجزئة، بايت حشو، إلخ) غير متوافق مع مواصفات الملف الحالية أو غير ذي معنى للدالة (على سبيل المثال، استخدام المؤشر دون تهيئة مسبقة) أو يوجد عدم تطابق بين رقم إصدار الملف والبرنامج.

قد تفشل روتينات close وتضبط errno لأي من الأخطاء المحددة لروتينات المكتبة close(2)، read(2)، write(2)، free(3)، أو fsync(2).

قد تفشل روتينات del، get، put، و seq وتضبط errno لأي من الأخطاء المحددة لروتينات المكتبة read(2)، write(2)، free(3)، أو malloc(3).

ستفشل روتينات fd وتضبط errno إلى ENOENT لقواعد البيانات في الذاكرة.

قد تفشل روتينات sync وتضبط errno لأي من الأخطاء المحددة لروتين المكتبة fsync(2).

العلل
الاسم المستعار DBT هو اختصار لـ "data base thang"، واستُخدم لأنه لم يستطع أحد التفكير في اسم معقول غير مستخدم بالفعل.

واجهة واصف الملف هي حل مؤقت وسيُحذف في إصدار مستقبلي من الواجهة.

لا توفر أي من طرق الوصول أي شكل من أشكال الوصول المتزامن أو القفل أو المعاملات.

انظر أيضًا
btree(3), hash(3), mpool(3), recno(3)

LIBTP: Portable, Modular Transactions for UNIX، مارغو سيلتزر، مايكل أولسون، وقائع USENIX، شتاء 1992.

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

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

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