.\" -*- coding: UTF-8 -*- .\" Copyright 2019, Aleksa Sarai .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH openat2 2 "8 فبراير 2026" "صفحات دليل لينكس 6.18" .SH الاسم openat2 \- فتح ملف وربما إنشاؤه (موسع) .SH المكتبة مكتبة سي المعيارية (\fIlibc\fP،\ \fI\-lc\fP) .SH موجز .nf \fB#include \fP /* تعريف ثوابت \fBO_*\fP و \fBS_*\fP */ \fB#include \fP /* تعريف ثوابت \fBRESOLVE_*\fP */ \fB#include \fP /* تعريف ثوابت \fBSYS_*\fP */ \fB#include \fP .P \fBlong syscall(SYS_openat2, int \fP\fIdirfd\fP\fB, const char *\fP\fIpath\fP\fB,\fP \fB struct open_how *\fP\fIhow\fP\fB, size_t \fP\fIsize\fP\fB);\fP .fi .P \fIملاحظة\fP: لا توفر glibc غلافًا لـ \fBopenat2\fP()، مما يستلزم استخدام \fBsyscall\fP(2). .SH الوصف استدعاء النظام \fBopenat2\fP() هو امتداد لـ \fBopenat\fP(2) ويوفر مجموعة شاملة من وظائفه. .P يفتح استدعاء النظام \fBopenat2\fP() الملف المحدد بواسطة \fIpath\fP. إذا لم يكن الملف المحدد موجودًا، فقد يُنشئ اختياريًا (إذا حُددت \fBO_CREAT\fP في \fIhow.flags\fP). .P كما في \fBopenat\fP(2)، إذا كان \fIpath\fP نسبيًا، فإنه يُفسر بالنسبة للدليل المشار إليه بواصف الملف \fIdirfd\fP (أو دليل العمل الحالي للعملية المستدعية، إذا كان \fIdirfd\fP هو القيمة الخاصة \fBAT_FDCWD\fP). إذا كان \fIpath\fP مطلقًا، فسيُتجاهل \fIdirfd\fP (إلا إذا كان \fIhow.resolve\fP يحتوي على \fBRESOLVE_IN_ROOT\fP، وفي هذه الحالة يُحل \fIpath\fP بالنسبة لـ \fIdirfd\fP). .P .\" بدلاً من أخذ وسيط واحد \fIflags\fP، يُمرر هيكل قابل للتوسيع (\fIhow\fP) للسماح بالامتدادات المستقبلية. يجب تحديد الوسيط \fIsize\fP كـ \fIsizeof(struct open_how)\fP. .SS "هيكل open_how" يحدد الوسيط \fIhow\fP كيفية فتح \fIpath\fP، ويعمل كمجموعة شاملة لوسيطي \fIflags\fP و \fImode\fP لـ \fBopenat\fP(2). هذا الوسيط هو مؤشر لهيكل \fIopen_how\fP، الموصوف في \fBopen_how\fP(2type). .P ستٌنفذ أي امتدادات مستقبلية لـ \fBopenat2\fP() كحقول جديدة ملحقة بهيكل \fIopen_how\fP، مع قيمة صفرية في حقل جديد تؤدي إلى تصرف النواة كما لو أن حقل الامتداد هذا غير موجود. لذلك، \fIيجب\fP على المستدعي ملء هذا الهيكل بالأصفار عند التهيئة. (انظر قسم "قابلية التوسيع" في \fBملاحظات\fP لمزيد من التفاصيل حول سبب ضرورة ذلك.) .P حقول هيكل \fIopen_how\fP هي كما يلي: .TP \fIflags\fP يحدد هذا الحقل أعلام إنشاء الملف وحالة الملف لاستخدامها عند فتح الملف. جميع أعلام \fBO_*\fP المعرفة لـ \fBopenat\fP(2) هي قيم أعلام صالحة لـ \fBopenat2\fP(). .IP بينما يتجاهل \fBopenat\fP(2) البتات غير المعروفة في وسيط \fIflags\fP الخاص به، يُرجع \fBopenat2\fP() خطأً إذا حُددت أعلام غير معروفة أو متعارضة في \fIhow.flags\fP. .TP \fImode\fP يحدد هذا الحقل وضع الملف الجديد، بدلالات مطابقة لوسيط \fImode\fP لـ \fBopenat\fP(2). .IP بينما يتجاهل \fBopenat\fP(2) البتات غير الموجودة في النطاق \fI07777\fP في وسيط \fImode\fP الخاص به، يُرجع \fBopenat2\fP() خطأً إذا كان \fIhow.mode\fP يحتوي على بتات غير \fI07777\fP. وبالمثل، يُرجع خطأً إذا اُستدعي \fBopenat2\fP() بقيمة غير صفرية لـ \fIhow.mode\fP ولا يحتوي \fIhow.flags\fP على \fBO_CREAT\fP أو \fBO_TMPFILE\fP. .TP \fIresolve\fP هذا قناع بتات من الأعلام التي تعدل الطريقة التي سيُحل بها \fBجميع\fP مكونات \fIpath\fP. (انظر \fBpath_resolution\fP(7) للحصول على معلومات أساسية.) .IP الاستخدام الأساسي لهذه الأعلام هو السماح للبرامج الموثوقة بتقييد كيفية حل المسارات غير الموثوقة (أو المسارات داخل الدلائل غير الموثوقة). القائمة الكاملة لأعلام \fIresolve\fP هي كما يلي: .RS .TP \fBRESOLVE_BENEATH\fP .\" commit adb21d2b526f7f196b2f3fdca97d80ba05dd14a0 لا تسمح بنجاح حل المسار إذا كان أي مكون من مكونات الحل ليس سليلاً للدليل المشار إليه بواسطة \fIdirfd\fP. يؤدي هذا إلى ربط الروابط الرمزية المطلقة (والقيم المطلقة لـ \fIpath\fP). .IP حاليًا، يعطل هذا العلم أيضًا حل الروابط السحرية (انظر أدناه). ومع ذلك، قد يتغير هذا في المستقبل. لذلك، لضمان عدم حل الروابط السحرية، يجب على المستدعي تحديد \fBRESOLVE_NO_MAGICLINKS\fP صراحةً. .TP \fBRESOLVE_IN_ROOT\fP .\" commit 8db52c7e7ee1bd861b6096fcafc0fe7d0f24a994 عامل الدليل المشار إليه بواسطة \fIdirfd\fP كدليل الجذر أثناء حل \fIpath\fP. تُفسر الروابط الرمزية المطلقة بالنسبة لـ \fIdirfd\fP. إذا كان مكون بادئة من \fIpath\fP يساوي \fIdirfd\fP، فإن المكون التالي مباشرة \fI..\&\fP يساوي أيضًا \fIdirfd\fP (تمامًا كما أن \fI/..\&\fP مكافئ تقليديًا لـ \fI/\fP). إذا كان \fIpath\fP مطلقًا، فإنه يُفسر أيضًا بالنسبة لـ \fIdirfd\fP. .IP تأثير هذا العلم كما لو أن العملية المستدعية استخدمت \fBchroot\fP(2) لتعديل دليل جذرها (مؤقتًا) (إلى الدليل المشار إليه بواسطة \fIdirfd\fP). ومع ذلك، على عكس \fBchroot\fP(2) (الذي يغير جذر نظام الملفات بشكل دائم لعملية ما)، يسمح \fBRESOLVE_IN_ROOT\fP للبرنامج بتقييد حل المسار بكفاءة على أساس كل فتحة. .IP حاليًا، يعطل هذا العلم أيضًا حل الروابط السحرية. ومع ذلك، قد يتغير هذا في المستقبل. لذلك، لضمان عدم حل الروابط السحرية، يجب على المستدعي تحديد \fBRESOLVE_NO_MAGICLINKS\fP صراحةً. .TP \fBRESOLVE_NO_MAGICLINKS\fP .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a تعطيل حل جميع الروابط السحرية أثناء تحليل المسار. .IP الروابط السحرية هي كائنات تشبه الروابط الرمزية توجد بشكل بارز في \fBproc\fP(5)؛ تتضمن الأمثلة \fI/proc/\fPpid\fI/exe\fP و \fI/proc/\fPpid\fI/fd/*\fP. (انظر \fBsymlink\fP(7) لمزيد من التفاصيل.) .IP قد يكون فتح الروابط السحرية دون علم محفوفًا بالمخاطر لبعض التطبيقات. تتضمن أمثلة هذه المخاطر ما يلي: .RS .IP \[bu] 3 إذا كانت العملية التي تفتح اسم مسار هي عملية تحكم ليس لديها حاليًا طرفية تحكم (انظر \fBcredentials\fP(7))، فإن فتح رابط سحري داخل \fI/proc/\fPpid\fI/fd\fP يشير بالصدفة إلى طرفية سيؤدي إلى حصول العملية على طرفية تحكم. .IP \[bu] .\" From https://lwn.net/Articles/796868/: .\" The presence of this flag will prevent a path lookup operation .\" from traversing through one of these magic links, thus blocking .\" (for example) attempts to escape from a container via a /proc .\" entry for an open file descriptor. في بيئة محتواة، قد يشير رابط سحري داخل \fI/proc\fP إلى كائن خارج الحاوية، وبالتالي قد يوفر وسيلة للهروب من الحاوية. .RE .IP بسبب هذه المخاطر، قد يفضل أحد التطبيقات تعطيل حل الرابط السحري باستخدام العلم \fBRESOLVE_NO_MAGICLINKS\fP. .IP إذا كان المكون التالي (أي اسم الأساس) لـ \fIpath\fP رابطًا سحريًا، ويحتوي \fIhow.resolve\fP على \fBRESOLVE_NO_MAGICLINKS\fP، ويحتوي \fIhow.flags\fP على كل من \fBO_PATH\fP و \fBO_NOFOLLOW\fP، فسيُرجع واصف ملف \fBO_PATH\fP يشير إلى الرابط السحري. .TP \fBRESOLVE_NO_SYMLINKS\fP .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a تعطيل حل الروابط الرمزية أثناء تحليل المسار. يستلزم هذا الخيار \fBRESOLVE_NO_MAGICLINKS\fP. .IP إذا كان المكون التالي (أي اسم الأساس) لـ \fIpath\fP رابطًا رمزيًا، ويحتوي \fIhow.resolve\fP على \fBRESOLVE_NO_SYMLINKS\fP، ويحتوي \fIhow.flags\fP على كل من \fBO_PATH\fP و \fBO_NOFOLLOW\fP، فسيُرجع واصف ملف \fBO_PATH\fP يشير إلى الرابط الرمزي. .IP لاحظ أن تأثير العلم \fBRESOLVE_NO_SYMLINKS\fP، الذي يؤثر على معالجة الروابط الرمزية في جميع مكونات \fIpath\fP، يختلف عن تأثير علم إنشاء الملف \fBO_NOFOLLOW\fP (في \fIhow.flags\fP)، الذي يؤثر على معالجة الروابط الرمزية فقط في المكون الأخير من \fIpath\fP. .IP يُشجع التطبيقات التي تستخدم العلم \fBRESOLVE_NO_SYMLINKS\fP على جعل استخدامه قابلاً للتكوين (إلا إذا اُستخدم لغرض أمني محدد)، لأن الروابط الرمزية تُستخدم على نطاق واسع جدًا من قبل المستخدمين النهائيين. قد يؤدي تعيين هذا العلم بشكل عشوائي\[em]أي لأغراض لا تتعلق تحديدًا بالأمان\[em]لجميع استخدامات \fBopenat2\fP() إلى أخطاء زائفة على أنظمة كانت تعمل سابقًا. قد يحدث هذا إذا، على سبيل المثال، عُدل اسم مسار نظام يستخدمه تطبيق (مثلًا في إصدار توزيعة جديد) بحيث يحتوي مكون اسم المسار (الآن) على رابط رمزي. .TP \fBRESOLVE_NO_XDEV\fP .\" commit 72ba29297e1439efaa54d9125b866ae9d15df339 تعطيل عبور نقاط الوصل أثناء تحليل المسار (بما في ذلك جميع وصلات الربط). وبالتالي، يجب أن يكون \fIpath\fP إما على نفس الوصل مثل الدليل المشار إليه بواسطة \fIdirfd\fP، أو على نفس الوصل مثل دليل العمل الحالي إذا حُدد \fIdirfd\fP كـ \fBAT_FDCWD\fP. .IP يُشجع التطبيقات التي تستخدم العلم \fBRESOLVE_NO_XDEV\fP على جعل استخدامه قابلاً للتكوين (إلا إذا اُستخدم لغرض أمني محدد)، لأن وصلات الربط تُستخدم على نطاق واسع من قبل المستخدمين النهائيين. قد يؤدي تعيين هذا العلم بشكل عشوائي\[em]أي لأغراض لا تتعلق تحديدًا بالأمان\[em]لجميع استخدامات \fBopenat2\fP() إلى أخطاء زائفة على أنظمة كانت تعمل سابقًا. قد يحدث هذا إذا، على سبيل المثال، عُدل اسم مسار نظام يستخدمه تطبيق (مثلًا في إصدار توزيعة جديد) بحيث يحتوي مكون اسم المسار (الآن) على وصل ربط. .TP \fBRESOLVE_CACHED\fP (منذ لينكس 5.12) .\" commit 99668f618062816ca7ba639b007eb145b9d3d41e جعل عملية الفتح تفشل ما لم تكن جميع مكونات المسار موجودة بالفعل في خبيئة البحث الخاصة بالنواة. إذا كان أي نوع من إعادة التحقق أو الإدخال/الإخراج مطلوبًا لتلبية البحث، يفشل \fBopenat2\fP() مع الخطأ \fBEAGAIN\fP. هذا مفيد في توفير فتح سريع يمكن تنفيذه دون اللجوء إلى تفريغ الخيوط، أو آليات أخرى قد يستخدمها التطبيق لتفريغ العمليات الأبطأ. .RE .IP إذا عُينت أي بتات غير تلك المذكورة أعلاه في \fIhow.resolve\fP، يُرجع خطأ. .SH "قيمة الإرجاع" عند النجاح، يُرجع واصف ملف جديد. عند الخطأ، يُرجع \-1، ويعُين \fIerrno\fP للإشارة إلى الخطأ. .SH الأخطاء تتضمن مجموعة الأخطاء التي يُرجعها \fBopenat2\fP() جميع الأخطاء التي يُرجعها \fBopenat\fP(2)، بالإضافة إلى الأخطاء الإضافية التالية: .TP \fBE2BIG\fP حُدد امتداد لا تدعمه هذه النواة في \fIhow\fP. (انظر قسم "قابلية التوسع" في \fBNOTES\fP لمزيد من التفاصيل حول كيفية معالجة الامتدادات.) .TP \fBEAGAIN\fP يحتوي \fIhow.resolve\fP إما على \fBRESOLVE_IN_ROOT\fP أو \fBRESOLVE_BENEATH\fP، ولم تتمكن النواة من ضمان عدم هروب مكون ".." (بسبب حالة سباق أو هجوم محتمل). قد يختار المتصل إعادة محاولة استدعاء \fBopenat2\fP(). .TP \fBEAGAIN\fP عُين \fBRESOLVE_CACHED\fP، ولا يمكن تنفيذ عملية الفتح باستخدام المعلومات المخبأة فقط. يجب على المتصل إعادة المحاولة دون تعيين \fBRESOLVE_CACHED\fP في \fIhow.resolve\fP. .TP \fBEINVAL\fP حُدد علم غير معروف أو قيمة غير صالحة في \fIhow\fP. .TP \fBEINVAL\fP \fImode\fP غير صفري، لكن \fIhow.flags\fP لا يحتوي على \fBO_CREAT\fP أو \fBO_TMPFILE\fP. .TP \fBEINVAL\fP كان \fIsize\fP أصغر من أي إصدار معروف من \fIstruct open_how\fP. .TP \fBELOOP\fP يحتوي \fIhow.resolve\fP على \fBRESOLVE_NO_SYMLINKS\fP، وكان أحد مكونات المسار رابطًا رمزيًا (أو رابطًا سحريًا). .TP \fBELOOP\fP يحتوي \fIhow.resolve\fP على \fBRESOLVE_NO_MAGICLINKS\fP، وكان أحد مكونات المسار رابطًا سحريًا. .TP \fBEXDEV\fP يحتوي \fIhow.resolve\fP إما على \fBRESOLVE_IN_ROOT\fP أو \fBRESOLVE_BENEATH\fP، واُكتشف هروب من الجذر أثناء تحليل المسار. .TP \fBEXDEV\fP يحتوي \fIhow.resolve\fP على \fBRESOLVE_NO_XDEV\fP، ويعبر مكون مسار نقطة وصل. .SH المعايير لينكس. .SH التاريخ .\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179 لينكس 5.6. .P .\" https://reviews.freebsd.org/D25886 .\" https://reviews.freebsd.org/D28907 دلالات \fBRESOLVE_BENEATH\fP صُممت على غرار \fBO_BENEATH\fP في فري بي إس دي، لكنها تجنبت خطأ صحة معروفًا في تنفيذ فري بي إس دي جعله غير آمن فعليًا. لاحقًا، قدمت فري بي إس دي 13 \fBO_RESOLVE_BENEATH\fP لاستبدال \fBO_BENEATH\fP غير الآمن. دلالات \fBO_RESOLVE_BENEATH\fP في فري بي إس دي مبنية على \fBRESOLVE_BENEATH\fP في لينكس، والاثنان الآن متكافئان وظيفيًا. .SH ملاحظات .SS "القابلية للتوسع" للسماح بقابلية التوسع المستقبلية، تتطلب \fBopenat2\fP() من تطبيق مساحة المستخدم تحديد حجم بنية \fIopen_how\fP التي يمررها. بتوفير هذه المعلومات، يمكن لـ \fBopenat2\fP() توفير التوافق الأمامي والخلفي، مع عمل \fIsize\fP كرقم إصدار ضمني. (لأن حقول الامتداد الجديدة ستُضاف دائمًا في النهاية، سيزداد حجم البنية دائمًا.) تصميم قابلية التوسع هذا مشابه جدًا لاستدعاءات نظام أخرى مثل \fBsched_setattr\fP(2) و \fBperf_event_open\fP(2) و \fBclone3\fP(2). .P إذا جعلنا \fIusize\fP هو حجم البنية كما هو محدد من قبل تطبيق مساحة المستخدم، و \fIksize\fP هو حجم البنية التي يدعمها النواة، فهناك ثلاث حالات يجب مراعاتها: .IP \[bu] 3 إذا كان \fIksize\fP يساوي \fIusize\fP، فلا يوجد عدم تطابق في الإصدار ويمكن استخدام \fIhow\fP كما هو. .IP \[bu] إذا كان \fIksize\fP أكبر من \fIusize\fP، فهذا يعني وجود بعض حقول التوسعة التي تدعمها النواة ولكن تطبيق مساحة المستخدم لا يدركها. ولأن القيمة الصفرية في أي حقل توسعة مضاف تعني عدم التنفيذ (no\-op)، تعامل النواة جميع حقول التوسعة التي لم يوفرها تطبيق مساحة المستخدم على أنها ذات قيم صفرية. يوفر هذا توافقا مع الإصدارات السابقة. .IP \[bu] إذا كان \fIksize\fP أصغر من \fIusize\fP، فهناك بعض حقول الامتداد التي يعرفها تطبيق مساحة المستخدم ولكن النواة لا تدعمها. لأن أي حقل امتداد يجب أن تشير قيمه الصفرية إلى عدم إجراء عملية، يمكن للنواة تجاهل حقول الامتداد غير المدعومة بأمان إذا كانت كلها أصفار. إذا كانت أي حقول امتداد غير مدعومة غير صفرية، فسيُرجع \-1 ويُعين \fIerrno\fP إلى \fBE2BIG\fP. هذا يوفر التوافق الأمامي. .P لأن تعريف \fIstruct open_how\fP قد يتغير في المستقبل (مع إضافة حقول جديدة عند تحديث رؤوس النظام)، يجب على تطبيقات مساحة المستخدم ملء \fIstruct open_how\fP بالأصفار لضمان أن إعادة ترجمة البرنامج مع رؤوس جديدة لن تؤدي إلى أخطاء زائفة في وقت التشغيل. أبسط طريقة هي استخدام مهيئ معين: .P .in +4n .EX struct open_how how = { .flags = O_RDWR, .resolve = RESOLVE_IN_ROOT }; .EE .in .P أو باستخدام \fBmemset\fP(3) صراحةً أو ما شابه: .P .in +4n .EX struct open_how how; memset(&how, 0, sizeof(how)); how.flags = O_RDWR; how.resolve = RESOLVE_IN_ROOT; .EE .in .P يمكن لتطبيق في مساحة المستخدم يرغب في تحديد الامتدادات التي تدعمها النواة العاملة القيام بذلك عن طريق إجراء بحث ثنائي على \fIsize\fP مع هيكل يحتوي كل بايت فيه على قيمة غير صفرية (للعثور على أكبر قيمة لا تنتج خطأ \fBE2BIG\fP). .SH "انظر أيضًا" \fBopenat\fP(2), \fBopen_how\fP(2type), \fBpath_resolution\fP(7), \fBsymlink\fP(7) .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي و # . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .