.\" -*- coding: UTF-8 -*- '\" t .\" Copyright 1993, Ulrich Drepper .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH hsearch 3 "8 فبراير 2026" "صفحات دليل لينكس 6.18" .SH الاسم hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r \- إدارة جدول التجزئة .SH المكتبة مكتبة سي المعيارية (\fIlibc\fP،\ \fI\-lc\fP) .SH موجز .nf \fB#include \fP .P \fBint hcreate(size_t \fP\fInel\fP\fB);\fP \fBvoid hdestroy(void);\fP .P \fBENTRY *hsearch(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB);\fP .P \fB#define _GNU_SOURCE\fP /* انظر feature_test_macros(7) */ \fB#include \fP .P \fBint hcreate_r(size_t \fP\fInel\fP\fB, struct hsearch_data *\fP\fIhtab\fP\fB);\fP \fBvoid hdestroy_r(struct hsearch_data *\fP\fIhtab\fP\fB);\fP .P \fBint hsearch_r(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB, ENTRY **\fP\fIretval\fP\fB,\fP \fB struct hsearch_data *\fP\fIhtab\fP\fB);\fP .fi .SH الوصف الدوال الثلاث \fBhcreate\fP() و \fBhsearch\fP() و \fBhdestroy\fP() تسمح للمستدعي بإنشاء وإدارة جدول بحث تجزئة يحتوي على مدخلات تتكون من مفتاح (سلسلة محارف) وبيانات مرتبطة. باستخدام هذه الدوال، يمكن استخدام جدول تجزئة واحد فقط في كل مرة. .P الدوال الثلاث \fBhcreate_r\fP() و \fBhsearch_r\fP() و \fBhdestroy_r\fP() هي إصدارات قابلة لإعادة الدخول تسمح للبرنامج باستخدام أكثر من جدول بحث تجزئة في نفس الوقت. المعامل الأخير \fIhtab\fP يشير إلى بنية تصف الجدول الذي ستعمل عليه الدالة. يجب على المبرمج معاملة هذه البنية كبنية معتمة (أي لا يحاول الوصول المباشر أو تعديل الحقول في هذه البنية). .P .\" e.g., in glibc it is raised to the next higher prime number أولاً، يجب إنشاء جدول تجزئة باستخدام \fBhcreate\fP(). المعامل \fInel\fP يحدد الحد الأقصى لعدد المدخلات في الجدول. (لا يمكن تغيير هذا الحد الأقصى لاحقًا، لذا اختره بحكمة.) قد يعدل التطبيق هذه القيمة لأعلى لتحسين أداء جدول التجزئة الناتج. .P الدالة \fBhcreate_r\fP() تؤدي نفس مهمة \fBhcreate\fP()، ولكن للجدول الموصوف بواسطة البنية \fI*htab\fP. يجب تصفير البنية المشار إليها بواسطة \fIhtab\fP قبل الاستدعاء الأول لـ \fBhcreate_r\fP(). .P الدالة \fBhdestroy\fP() تحرر الذاكرة التي يشغلها جدول التجزئة الذي أُنشئ بواسطة \fBhcreate\fP(). بعد استدعاء \fBhdestroy\fP()، يمكن إنشاء جدول تجزئة جديد باستخدام \fBhcreate\fP(). الدالة \fBhdestroy_r\fP() تؤدي المهمة المماثلة لجدول تجزئة موصوف بواسطة \fI*htab\fP، والذي أُنشئ سابقًا باستخدام \fBhcreate_r\fP(). .P الدالة \fBhsearch\fP() تبحث في جدول التجزئة عن عنصر بنفس مفتاح \fIitem\fP (حيث يُحدد "نفس" باستخدام \fBstrcmp\fP(3))، وإذا نجحت، تُرجع مؤشرًا إليه. .P المعامل \fIitem\fP من النوع \fIENTRY\fP، والذي يُعرف في \fI\fP كالتالي: .P .in +4n .EX typedef struct entry { char *key; void *data; } ENTRY; .EE .in .P الحقل \fIkey\fP يشير إلى سلسلة محارف منتهية بقيمة خالية وهي مفتاح البحث. الحقل \fIdata\fP يشير إلى بيانات مرتبطة بذلك المفتاح. .P المعامل \fIaction\fP يحدد ما تفعله \fBhsearch\fP() بعد بحث غير ناجح. يجب أن يكون لهذا المعامل إما القيمة \fBENTER\fP، بمعنى إدراج نسخة من \fIitem\fP (وإرجاع مؤشر إلى مدخل جدول التجزئة الجديد كنتيجة للدالة)، أو القيمة \fBFIND\fP، بمعنى أنه يجب إرجاع NULL. (إذا كان \fIaction\fP هو \fBFIND\fP، فسيتم تجاهل \fIdata\fP.) .P الدالة \fBhsearch_r\fP() تشبه \fBhsearch\fP() ولكنها تعمل على جدول التجزئة الموصوف بواسطة \fI*htab\fP. تختلف الدالة \fBhsearch_r\fP() عن \fBhsearch\fP() في أن مؤشرًا إلى العنصر الموجود يُرجع في \fI*retval\fP، بدلاً من كونه نتيجة الدالة. .SH "قيمة الإرجاع" \fBhcreate\fP() و \fBhcreate_r\fP() تُرجعان قيمة غير صفرية عند النجاح. تُرجعان 0 عند الخطأ، مع تعيين \fIerrno\fP للإشارة إلى الخطأ. .P عند النجاح، \fBhsearch\fP() تُرجع مؤشرًا إلى مدخل في جدول التجزئة. \fBhsearch\fP() تُرجع NULL عند الخطأ، أي إذا كان \fIaction\fP هو \fBENTER\fP وجدول التجزئة ممتلئ، أو \fIaction\fP هو \fBFIND\fP ولا يمكن العثور على \fIitem\fP في جدول التجزئة. \fBhsearch_r\fP() تُرجع قيمة غير صفرية عند النجاح، و0 عند الخطأ. في حالة حدوث خطأ، تعيّن هاتان الدالتان \fIerrno\fP للإشارة إلى الخطأ. .SH الأخطاء يمكن أن تفشل \fBhcreate_r\fP() و \fBhdestroy_r\fP() للأسباب التالية: .TP \fBEINVAL\fP \fIhtab\fP هو NULL. .P قد تفشل \fBhsearch\fP() و \fBhsearch_r\fP() للأسباب التالية: .TP \fBENOMEM\fP كان \fIaction\fP هو \fBENTER\fP، ولم يُعثر على \fIkey\fP في الجدول، ولم تكن هناك مساحة في الجدول لإضافة مدخل جديد. .TP \fBESRCH\fP كان \fIaction\fP هو \fBFIND\fP، ولم يُعثر على \fIkey\fP في الجدول. .P .\" PROX.1-2001, POSIX.1-2008 يحدد POSIX.1 خطأ \fBENOMEM\fP فقط. .SH السمات للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. الواجهة السمة القيمة T{ .na .nh \fBhcreate\fP(), \fBhsearch\fP(), \fBhdestroy\fP() T} سلامة الخيوط MT\-Unsafe race:hsearch T{ .na .nh \fBhcreate_r\fP(), \fBhsearch_r\fP(), \fBhdestroy_r\fP() T} سلامة الخيوط MT\-Safe race:htab .TE .SH المعايير .TP \fBhcreate\fP() .TQ \fBhsearch\fP() .TQ \fBhdestroy\fP() POSIX.1\-2008. .TP \fBhcreate_r\fP() .TQ \fBhsearch_r\fP() .TQ \fBhdestroy_r\fP() GNU. .SH التاريخ .TP \fBhcreate\fP() .TQ \fBhsearch\fP() .TQ \fBhdestroy\fP() SVr4, POSIX.1\-2001. .TP \fBhcreate_r\fP() .TQ \fBhsearch_r\fP() .TQ \fBhdestroy_r\fP() GNU. .SH ملاحظات تكون تطبيقات جداول التجزئة عادةً أكثر كفاءة عندما يحتوي الجدول على مساحة خالية كافية لتقليل التصادمات. عادةً، يعني هذا أن \fInel\fP يجب أن يكون أكبر بنسبة 25% على الأقل من الحد الأقصى لعدد العناصر التي يتوقع المتصل تخزينها في الجدول. .P لا تحرر الدالتان \fBhdestroy\fP() و \fBhdestroy_r\fP() المخازن المؤقتة المشار إليها بواسطة عنصري \fIkey\fP و \fIdata\fP في مدخلات جدول التجزئة. (لا تستطيع فعل ذلك لأنها لا تعرف ما إذا كانت هذه المخازن المؤقتة قد خُصصت ديناميكيًا.) إذا احتاجت هذه المخازن المؤقتة إلى التحرير (ربما لأن البرنامج ينشئ ويدمر جداول التجزئة بشكل متكرر، بدلاً من إنشاء جدول واحد يتطابق عمره مع عمر البرنامج)، فيجب على البرنامج الحفاظ على هياكل بيانات محاسبية تسمح له بتحريرها. .SH العلل تحدد SVr4 و POSIX.1\-2001 أن \fIaction\fP مهم فقط للبحث غير الناجح، بحيث لا ينبغي لـ \fBENTER\fP فعل أي شيء للبحث الناجح. في libc و glibc (قبل glibc 2.3)، يخالف التطبيق المواصفات، حيث يُحدّث \fIdata\fP للمفتاح \fIkey\fP المُعطى في هذه الحالة. .P يمكن إضافة مدخلات جدول التجزئة الفردية، ولكن لا يمكن حذفها. .SH أمثلة يُدرج البرنامج التالي 24 عنصرًا في جدول تجزئة، ثم يطبع بعضًا منها. .P .\" SRC BEGIN (hsearch.c) .EX #include #include #include \& static char *data[] = { "alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf", "hotel", "india", "juliet", "kilo", "lima", "mike", "november", "oscar", "papa", "quebec", "romeo", "sierra", "tango", "uniform", "victor", "whisky", "x\-ray", "yankee", "zulu" }; \& int main(void) { ENTRY e; ENTRY *ep; \& hcreate(30); \& for (size_t i = 0; i < 24; i++) { e.key = data[i]; /* data is just an integer, instead of a pointer to something */ e.data = (void *) i; ep = hsearch(e, ENTER); /* there should be no failures */ if (ep == NULL) { fprintf(stderr, "entry failed\[rs]n"); exit(EXIT_FAILURE); } } \& for (size_t i = 22; i < 26; i++) { /* print two entries from the table, and show that two are not in the table */ e.key = data[i]; ep = hsearch(e, FIND); printf("%9.9s \-> %9.9s:%d\[rs]n", e.key, ep ? ep\->key : "NULL", ep ? (int) ep\->data : 0); } hdestroy(); exit(EXIT_SUCCESS); } .EE .\" SRC END .SH "انظر أيضًا" \fBbsearch\fP(3)، \fBlsearch\fP(3)، \fBmalloc\fP(3)، \fBtsearch\fP(3) .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .