الاسم¶

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 إلى القيمة التالية:

تُرجع دوال 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_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_LAST و R_PREV متاحان فقط لطريقتي الوصول DB_BTREE و DB_RECNO لأن كل منهما يفترض أن للمفاتيح ترتيبًا جوهريًا لا يتغير.

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

sync

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

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

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

typedef struct {


    void  *data;


    size_t size;
} DBT;

الأخطاء¶

قد تفشل روتين 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 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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