التعامل مع نظام الملفات في Node.js

من موسوعة حسوب
< Node.js
مراجعة 11:14، 23 أكتوبر 2018 بواسطة عبد اللطيف ايمش (نقاش | مساهمات) (استبدال النص - '\[\[تصنيف:(.*)\]\]' ب'{{SUBPAGENAME}}')
(فرق) → مراجعة أقدم | المراجعة الحالية (فرق) | مراجعة أحدث ← (فرق)

الاستقرار: 2 - مستقر

توفِّر الوحدة fs‎ واجهةً برمجيةً للتعامل مع نظام الملفات بطريقة قريبة جدًا من دوال POSIX القياسية.

يمكن الوصول إلى هذه الوحدة باستعمال الأمر التالي:

const fs = require('fs');

جميع عمليات نظام الملفات لها أشكال متزامنة وغير متزامنة. تأخذ الأشكال المتزامنة دالة رد نداء مكملة دومًا وتُمرَّر إليها كآخر وسيط. تعتمد الوسائط المُمرَّرة إلى دالة رد النداء المكملة تلك على التابع نفسه، ولكن الوسيط الأول فيها محجوزٌ دومًا للاستثناء. إن اكتملت العملية بنجاح، فستكون قيمة هذا الوسيط null‎ أو undefined‎.

const fs = require('fs');

fs.unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

تُرمَى الاستثناءات التي تحدث باستعمال العمليات المتزامنة مباشرةً وقد تُعالَج باستعمال العبارة try...catch‎، أو ربما يُسمَح لها بالانتشار للأعلى (bubble up).

const fs = require('fs');

try {
  fs.unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // عالج الخطأ هنا
}

لا يوجد أي ترتيب مضمون عند استعمال توابع غير متزامنة. بناءً على ذلك، هنالك احتمالٌ كبير أن يحصل خطأ في المثال التالي لأنَّ العملية fs.stat()‎ قد تكتمل قبل العملية fs.rename()‎:

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  console.log('renamed complete');
});
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err;
  console.log(`stats: ${JSON.stringify(stats)}`);
});

لتنفيذ المثال بالشكل والترتيب الصحيح للعمليات، انقل الاستدعاء fs.stat()‎ إلى داخل رد النداء للعملية fs.rename()‎:

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  fs.stat('/tmp/world', (err, stats) => {
    if (err) throw err;
    console.log(`stats: ${JSON.stringify(stats)}`);
  });
});

في العمليات المشغولة، يُوصَى المبرمج بشدة باستخدام الاصدارات غير المتزامنة من هذه الاستدعاءات، إذ ستحجب الإصدارات المتزامنة كامل العملية حتى تكمل أو توقف جميع اتصالاتها.

لمَّا كانت أغلب دوال الوحدة fs‎ تسمح بحذف وسيط رد النداء، فإنَّ هذا السلوك غير مُستحسَن مطلقًا، إذ تُستخدَم دالة رد النداء الافتراضية، في أبسط الحالات، في معالجة الأخطاء المرمية وهنا تكمن فائدتها. للحصول على متعقِّب لموقع الاستدعاء الأصلي، اضبط متغير البيئة NODE_DEBUG‎.

أُهملَت عملية حذف دالة رد النداء في دوال الوحدة fs‎ الغير متزامنة، وقد يؤدي فعل ذلك إلى رمي خطأ في المستقبل.

$ cat script.js
function bad() {
  require('fs').readFile('/');
}
bad();

$ env NODE_DEBUG=fs node script.js
fs.js:88
        throw backtrace;
        ^
Error: EISDIR: illegal operation on a directory, read
    <stack trace.>

مسارات الملف (File paths)

تقبل أغلب عمليات fs‎ تمرير مسارات لملفات إليها في شكل سلسلة نصية، أو كائن من النوع Buffer‎، أو النوع URL‎ باستعمال البروتوكول file:‎.

تُفسَّر المسارات التي توضع في سلاسل نصية كسلاسل من المحارف بترميز UTF-8 ممثلةً اسم الملف المطلق أو النسبي. ستُستبيَن المسارات النسبية نسبةً إلى مجلد العمل الحالي المحدَّد باستعمال process.cwd()‎.

اطلع على المثال التالي الذي يشرح كيفية استعمال مسار مطلق على نظام متوافق مع معيار POSIX:

const fs = require('fs');

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

اطلع على المثال التالي الذي يشرح كيفية استعمال مسار نسي (نسبةً إلى process.cwd()‎) على نظام متوافق مع معيار POSIX:

fs.open('file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

تحديد المسارات باستعمال الكائنات Buffer‎ مفيدٌ جدًا خصوصًا على بعض أنظمة التشغيل المتوافقة مع POSIX التي تعامل مسارات الملفات كسلسلة مبهمة من البايتات. في بعض الأنظمة، يمكن لمسار ملف واحد أن يحوي سلاسل فرعية ترميز محارف كلِّ واحدة منها مختلفٌ عن الآخر. وكما هو الحال في مسارات السلاسل النصية، يمكن أن تكون المسارات المحتواة في الكائنات Buffer‎ نسبيةً أو مطلقةً. اطلع على المثال التالي الذي يشرح كيفية استعمال مسار مطلق على نظام متوافق مع معيار POSIX:

fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

في ويندوز، تتبنى Node.js مفهوم «مجلد العمل لكل قرص» (per-drive working directory). يمكن ملاحظة هذا السلوك عند استعمال مسار قرص دون محرف الخط المائل العكسي \‎. على سبيل المثال، يمكن أن يعيد الاستدعاء fs.readdirSync('c:\\')‎ نتيجةً مختلفةً عن الاستدعاء fs.readdirSync('c:')‎. للمزيد من المعلومات، اطلع على هذه الصفحة.

دعم الكائن URL‎

أضيف في الإصدار: v7.6.0.

في أغلب دوال الوحدة fs‎، قد يُمرَّر الوسيط path‎ والوسيط filename‎ ككائن من النوع URL‎ الذي يمثل عنوان URL متوافق مع المعيار WHATWG. الكائنات URL‎ التي تستعمل البروتوكول file:‎ مدعومةً فقط.

const fs = require('fs');
const fileUrl = new URL('file:///tmp/hello');

fs.readFileSync(fileUrl);

العناوين URL ذات البروتوكول file:‎ هي مسارات مطلقة دومًا.

قد يترافق استعمال الكائنات URL‎ -التي تمثل عناوين URL متوافقة مع المعيار WHATWG- سلوكيات محددة بحسب المنصة المستعملة.

في ويندوز، تحوَّل العناوين URL ذات البرتوكول file‎:‎ مع اسم المضيف (hosename) إلى مسارات UNC بينما تحول العناوين URL ذات البرتوكول file‎:‎ التي تحوي على محارف الأقراص إلى مسارات محلية مطلقة. أما العناوين URL ذات البروتوكول file‎:‎ التي لا تحوي اسم المضيف (hosename) ولا محرف قرص، فسيؤدي استعمالها إلى رمي خطأ. تفحَّص المثال التالي الذي يشرح ما سبق:

// :في ويندوز

// - UNC مع اسم المضيف إلى مسارات file‎: ذات البرتوكول URL تحوَّل العناوين 
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// - مع محارف الأقراص إلى مسارات محلية مطلقة file‎: ذات البرتوكول URL تحوَّل العناوين
// file:///C:/tmp/hello => C:\tmp\hello
fs.readFileSync(new URL('file:///C:/tmp/hello'));

// - التي بدون اسم مضيف على محرف قرص file‎: ذات البروتوكول URL يجب أن تحوي العناوين
fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'));
fs.readFileSync(new URL('file:///c/p/a/t/h/file'));
// إذ يجب أن يكون مسار TypeError [ERR_INVALID_FILE_URL_PATH] سيرمى الخطأ 
// مطلقًا URL الملف الذي يمثله عنوان 
يجب على العناوين URL ذات البروتوكول <code>file‎:</code> التي تحوي محارف أقراصٍ استعمال المحرف <code>:‎</code> كفاصل بعد محرف القرص مباشرةً. سيؤدي استعمال محرف فاصل آخر إلى رمي خطأ.
في جميع المنصات الأخرى، العناوين URL ذات البروتوكول <code>file‎:</code> مع اسم مضيف غيرَ مدعومةٍ وسيؤدي استعمالها بهذا الشكل إلى رمي خطأ:
<syntaxhighlight lang="javascript">// :في المنصات الأخرى

// - مع اسم المضيف غير مدعومة file‎: ذات البروتوكول URL العناوين 
// file://hostname/p/a/t/h/file => !رمي خطأ
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));
// إذ يجب أن يكون العنوان مطلقًا TypeError [ERR_INVALID_FILE_URL_PATH] سيرمى الخطأ

// - إلى مسارات مطلقة file‎: ذات البرتوكول URL تحوَّل العناوين 
// file:///tmp/hello => /tmp/hello
fs.readFileSync(new URL('file:///tmp/hello'));

يؤدي استعمال العناوين URL ذات البروتوكول file‎:‎ التي تحوي محارف الخط المائل المرمزة إلى رمي خطأ في جميع المنصات:

// في ويندوز
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f'));
// إذ لا يجب أن TypeError [ERR_INVALID_FILE_URL_PATH] سيرمى الخطأ
// الذي يمثل مسار ملف على المحارف \ أو / بعد ترميزها URL يحوي عنوان 

// POSIX في أنظمة
fs.readFileSync(new URL('file:///p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///p/a/t/h/%2f'));
// إذ لا يجب أن TypeError [ERR_INVALID_FILE_URL_PATH] سيرمى الخطأ
// الذي يمثل مسار ملف على المحارف / بعد ترميزها URL يحوي عنوان

في ويندوز، سيؤدي استعمال العناوين URL ذات البروتوكول file‎:‎ التي تحوي محارف الخط المائل العكسي المرمزة إلى رمي خطأ:

// في ويندوز
fs.readFileSync(new URL('file:///C:/path/%5C'));
fs.readFileSync(new URL('file:///C:/path/%5c'));
// إذ لا يجب أن TypeError [ERR_INVALID_FILE_URL_PATH] سيرمى الخطأ
// الذي يمثل مسار ملف على المحارف \ أو / بعد ترميزها URL يحوي عنوان

واصفات الملف (File Descriptors)

في الأنظمة المتوافقة مع POSIX، تحتفظ النواة بجدول للملفات والموارد المفتوحة حاليًا لكل عملية. يُسنَد كل ملف مفتوح إلى إلى معرِّف عددي بسيط يدعى «واصف الملف» (file descriptor). إن تحدثنا على مستوى النظام، نجد أنَّ جميع عمليات نظام الملفات تستعمل واصفات الملفات هذه لتحدِّد وتتتبَّع كل ملف بعينه. يستعمل نظام ويندوز طريقةً مختلفةً ولكنها شبيهة نظريًا بالآلية التي ذكرناها لتعقُّب الموارد. لتبسيط الأشياء للمستخدمين، عمدت Node.js إلى إزالة مثل هذه الاختلافات بين أنظمة التشغيل وإسناد جميع الملفات المفتوحة إلى واصفات ملف عددية.

يُستعمَل التابع fs.open()‎ لتخصيص واصف ملف جديد للملف المراد فتحه. متى ما خُصِّض واصف للملف، يمكن استعماله لقراءة بيانات من، أو كتابة بيانات على، أو طلب معلومات عن هذا الملف.

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.fstat(fd, (err, stat) => {
    if (err) throw err;
    // use stat

    // always close the file descriptor!
    fs.close(fd, (err) => {
      if (err) throw err;
    });
  });
});

تخصِّص أغلب أنظمة التشغيل مجالًا محدودًا من الأعداد لاستعمالها كواصفاتٍ للملفات التي قد تُفتَح في أي وقت، لذا فإنَّ إغلاق الواصف بعد اكتمال العملية أمرٌ بالغ الأهمية. سيؤدي إهمال أو فشل إغلاق واصفات الملفات إلى حدوث تسريب في الذاكرة (memory leak) ينتهي بانهيار التطبيق.

استعمال مجمع الخيوط (Threadpool Usage)

تستعمل جميع واجهات نظام الملفات البرمجية باستثناء fs.FSWatcher()‎ وتلك التي يظهر أنها تُستعمَل بشكل متزامن مجمع الخيوط الخاص بالمكتبة libuv والذي يمكن أن يكون يكون له تأثيرات مفاجئة وسلبية على بعض التطبيقات. اطلع إلى توثيق خيار سطر الأوامر UV_THREADPOOL_SIZE‎ للمزيد من التفاصيل.

الصنف fs.Dirent‎

أضيف في الإصدار: v10.10.0.

عندما يُستدعَى التابع fs.readdir()‎ أو التابع fs.readdirSync()‎ مع ضبط قيمة الخيار withFileTypes‎ فيه إلى القيمة true‎، ستُملَأ المصفوفة الناتجة بالكائنات fs.Dirent‎ بدلًا من السلاسل النصية أو الكائنات Buffer‎.

‎dirent.isBlockDevice()‎

أضيف في الإصدار: v10.10.0.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Dirent‎ يمثِّل جهازًا كتليًّا (block device)، أو القيمة false‎ خلا ذلك.

dirent.isCharacterDevice()‎

أضيف في الإصدار: v10.10.0.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Dirent‎ يمثِّل جهازًا محرفيًّا (character device)، أو القيمة false‎ خلا ذلك.

dirent.isDirectory()‎

أضيف في الإصدار: v10.10.0.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Dirent‎ يمثِّل مجلَّدًا في نظام الملفات (file system directory)، أو القيمة false‎ خلا ذلك.

dirent.isFIFO()‎

أضيف في الإصدار: v10.10.0.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Dirent‎ يمثِّل الأنبوب FIFO (اختصار للعبارة first-in-first-out أي «من دخل أولًا يخرج أولًا»، كما يدعى أحيانًا «أنبوبًا مسمًى») ، أو القيمة false‎ خلا ذلك.

dirent.isFile()‎

أضيف في الإصدار: v10.10.0.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Dirent‎ يمثِّل ملفًا طبيعيًّا، أو القيمة false‎ خلا ذلك.

dirent.isSocket()‎

أضيف في الإصدار: v10.10.0.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Dirent‎ يمثِّل مقبسًا (socket)، أو القيمة false‎ خلا ذلك.

dirent.isSymbolicLink()‎

أضيف في الإصدار: v10.10.0.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Dirent‎ يمثِّل وصلةً رمزيَّةً (symbolic link)، أو القيمة false‎ خلا ذلك.

dirent.name‎

أضيفت في الإصدار: v10.10.0.

تمثل هذه الخاصية اسم الملف الذي يشير إليه الكائن fs.Dirent‎. يُحدَّد نوع هذه القيمة عبر options.encoding‎ الممرَّر إلى fs.readdir()‎ أو fs.readdirSync()‎.

الصنف fs.FSWatcher‎

أضيف في الإصدار: v0.5.8.

سيعيد الاستدعاء الناجح للتابع fs.watch()‎ كائنًا جديدًا من النوع fs.FSWatcher‎.

الكائن fs.FSWatcher‎ هو مطلقٌُ للأحداث (EventEmitter)، إذ يُطلِق الحدث 'change' كلما عُدِّل ملفٌ مراقبٌ.

الحدث 'change'

أضيف في الإصدار: v0.5.8.

  • eventType‎: ‏<string> نوع حدث «التغيير» الذي حصل.
  • filename‎: ‏<string>‏ | <Buffer> اسم الملف الذي حصل تغيير فيه (إن كان متاحًا).

يُطلَق هذا الحدث عندما يتغير شيء في المجلَّد أو الملف المراقب. يوجد المزيد من التفاصيل في توثيق التابع fs.watch()‎ في الأسفل.

قد لا يكون الوسيط filename‎ متوافرًا وهذا يعتمد على دعم نظام التشغيل. إن أعطي الوسيط filename‎، فسيُعطَى بوصفه كائنًا من النوع Buffer‎ إن استُدعَي التابع fs.watch()‎ مع ضبط الخيار encoding‎ إلى القيمة 'buffer‎'؛ خلا ذلك، سيُعطَى الوسيط filename‎ في سلسلة نصية مرمزة بالترميز UTF-8.

// fs.watch() إضافة معالج حدث عبر مستمع
fs.watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename);
    // <Buffer ...> :سيُطبَع
  }
});

الحدث 'error'

أضيف في الإصدار: v10.10.0.

يُطلَق هذا الحدث متى ما توقف المراقب (watcher) عن مراقبة التغييرات. لن يكون الكائن fs.FSWatcher‎ قابلًا للاستعمال في معالج الحدث بعد إغلاقه.

الحدث 'close'

أضيف في الإصدار: v0.5.8.

يُطلَق هذا الحدث عندما يحدث خطأٌ أثناء عملية مراقبة الملف. لن يكون الكائن fs.FSWatcher‎ الذي حصل خطأٌ فيه قابلًا للاستعمال في معالج الحدث.

watcher.close()‎

أضيف في الإصدار: v0.5.8. يوقف هذا التابع عملية مراقبة التغييرات في الكائن fs.FSWatcher المعطى. متى ما استدعي هذا التابع، لن يعد الكائن fs.FSWatcher المُمرَّر إليه قابلًا للاستعمال بعد ذلك الحين.

الصنف fs.ReadStream‎

أضيف في الإصدار: v0.1.9.3.

سيعيد الاستدعاء الناجح للتابع fs.createReadStream()‎ كائنًا جديدًا من النوع fs.ReadStream‎. تُعدُّ جميع الكائنات fs.ReadStream مجارٍ قابلةٍ للقراءة (Readable Streams).

الحدث 'close'

أضيف في الإصدار: v0.1.93.

يُطلَق هذا الحدث عندما يُغلَق واصف الملف الموجود ضمنيًّا في الكائن fs.ReadStream‎.

الحدث 'open'

أضيف في الإصدار: v0.1.93.

  • fd‎:‏ <integer> عدد صحيح يمثل واصف الملف الذي استعمله الكائن ReadStream‎.

يُطلَق هذا الحدث عندما يُفتَح واصف الملف للكائن fs.ReadStream.

الحدث 'ready'

أضيف في الإصدار: v9.11.0. يُطلَق هذا الحدث عندما يكون الكائن fs.ReadStream‎ جاهزًا للاستعمال؛ أي يُطلَق بعد الحدث 'open' مباشرةً.

readStream.bytesRead‎

أضيفت في الإصدار: v6.4.0.

تمثِّل هذه الخاصية عدد البايتات التي قُرأَت حين استدعائها.

readStream.path‎

أضيفت في الإصدار: v0.1.93.

تمثِّل هذه الخاصية مسار الملف الذي يُقرَأ المجرى منه كما حُدِّد في الوسيط الأول المُمرَّر إلى fs.createReadStream()‎. إن كان المسار path‎ المُمرَّر سلسلةً نصيةً، فستعيد الخاصية readStream.path‎ سلسلةً نصيةً أيضًا. أمَّا إن كان المسار path‎ المُمرَّر كائنًا من النوع Buffer‎، فستعيد الخاصية readStream.path‎ كائنًا من النوع Buffer‎ أيضًا.

الصنف fs.Stats‎

سجل التغييرات
الإصدار التغييرات
v8.1.0 أضيفت الأزمنة كأعداد.
v0.1.21 أضيف هذا الصنف.

يوفِّر الكائن fs.Stats‎ معلومات عن أي ملف. جميع الكائنات المعادة من التوابع fs.stat()‎، و fs.lstat()‎، و fs.fstat()‎، ونظيراتها المتزامنة هي من هذا الصنف. إن كانت قيمة الخيار bigint‎ في الوسيط options‎ المُمرَّر إلى هذه التوابع هي true‎، فستكون القيم العددية من النوع bigint‎ بدلًا من number‎.

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

سيُعاد المثال السابق ولكن مع ضبط الخيار bigint‎ في الوسيط options‎ إلى القيمة true‎:

Stats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()‎

أضيف في الإصدار: v0.1.10.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Stats‎ يمثِّل جهازًا كتليًّا (block device)، أو القيمة false‎ خلاف ذلك.

stats.isCharacterDevice()‎

أضيف في الإصدار: v0.1.10.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Stats‎ يمثِّل جهازًا محرفيًّا (character device)، أو القيمة false‎ خلاف ذلك.

stats.isDirectory()‎

أضيف في الإصدار: v0.1.10.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Stats‎ يمثِّل مجلَّدًا في نظام الملفات (file system directory)، أو القيمة false‎ خلاف ذلك.

stats.isFIFO()‎

أضيف في الإصدار: v0.1.10.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Stats‎ يمثِّل الأنبوب FIFO (اختصارٌ للعبارة first-in-first-out أي «من دخل أولًا يخرج أولًا»، كما يدعى أحيانًا «أنبوبًا مسمًى»)، أو القيمة false‎ خلاف ذلك.

stats.isFile()‎

أضيف في الإصدار: v0.1.10.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Stats‎ يمثِّل ملفًا طبيعيًّا، أو القيمة false‎ خلاف ذلك.

stats.isSocket()‎

أضيف في الإصدار: v0.1.10.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Stats‎ يمثِّل مقبسًا (socket)، أو القيمة false‎ خلاف ذلك.

stats.isSymbolicLink()‎

أضيف في الإصدار: v0.1.10.

يعيد هذا التابع القيمة true‎ إن كان الكائن fs.Stats‎ يمثِّل وصلةً رمزيَّةً (symbolic link)، أو القيمة false‎ خلاف ذلك.

stats.dev‎

تمثِّل هذه الخاصية المعرِّف العددي للجهاز الذي يحوي الملف.

stats.ino

تمثِّل هذه الخاصية رقم مؤشِّر الفهرسة (inode) لنظام الملفات المحدَّد.

stats.mode

تمثِّل هذه الخاصية حقلًا بتيًّا (bit-field) يصف نوع الملف ووضعه.

stats.nlink

تمثِّل هذه الخاصية عدد الوصلات الصلبة (hard-links) الموجود للملف.

stats.uid

تمثِّل هذه الخاصية معرِّف المستخدم العددي (UID) للمستخدم المالك للملف (في أنظمة POSIX).

stats.gid

تمثِّل هذه الخاصية معرِّف المجموعة العددي (GID) للمجموعة المالكة للملف (في أنظمة POSIX).

stats.rdev

تمثِّل هذه الخاصية معرِّف الجهاز العددي إن عُدَّ الملف «خاصًّا» (special).

stats.size

تمثِّل هذه الخاصية حجم الملف بالبايت.

stats.blksize

تمثِّل هذه الخاصية حجم الكتلة (block size) لنظام الملفات من أجل عمليات الإدخال والإخراج (i/o).

stats.blocks

تمثِّل هذه الخاصية عدد الكتل المحجوزة لهذا الملف.

stats.atimeMs

أضيفت في الإصدار: v8.1.0.

تمثِّل هذه الخاصية بصمة وقت (timestamp) تشير إلى آخر وقت تم الوصول فيه إلى هذا الملف معبَّرًا عنها بالميلي ثانية منذ عهد POSIX.

stats.mtimeMs

أضيفت في الإصدار: v8.1.0.

تمثِّل هذه الخاصية بصمة الوقت (timestamp) التي تشير إلى آخر وقت عُدِّل فيه هذا الملف معبَّرًا عنها بالميلي ثانية منذ عهد POSIX.

stats.ctimeMs

أضيفت في الإصدار: v8.1.0.

تمثِّل هذه الخاصية بصمة وقت (timestamp) تشير إلى آخر وقت عُدِّلَت فيه حالة هذا الملف معبَّرًا عنها بالميلي ثانية منذ عهد POSIX.

stats.birthtimeMs

أضيفت في الإصدار: v8.1.0.

تمثِّل هذه الخاصية بصمة وقت (timestamp) تشير إلى وقت إنشاء هذا الملف معبَّرًا عنها بالميلي ثانية منذ عهد POSIX.

stats.atime

أضيفت في الإصدار: v0.11.13.

تمثِّل هذه الخاصية بصمة وقت (timestamp) تشير إلى آخر وقت تم الوصول فيه إلى هذا الملف.

stats.mtime

أضيفت في الإصدار: v0.11.13.

تمثِّل هذه الخاصية بصمة وقت (timestamp) تشير إلى آخر وقت عُدِّل فيه هذا الملف.

stats.ctime

أضيفت في الإصدار: v0.11.13.

تمثِّل هذه الخاصية بصمة وقت (timestamp) تشير إلى آخر وقت عُدِّلَت فيه حالة هذا الملف.

stats.birthtime

أضيفت في الإصدار: v0.11.13.

تمثِّل هذه الخاصية بصمة وقت (timestamp) تشير إلى وقت إنشاء هذا الملف.

قيم الوقت في الكائن Stats‎

إن جميع الخاصيات atimeMs‎، و mtimeMs‎، و ctimeMs‎، و birthtimeMs‎ هي أعدادٌ تمثِّل أزمنةً بالميلي ثانية، وتعتمد دقتها على المنصة المستعملة. أمَّا الخاصيات atime‎، و mtime، و ctime، و birthtime، فهي كائنات من النوع Date‎ (أي تواريخ) تمثل أزمنةً وأوقاتًا مختلفةً. انتبه إلى أنَّ قيم الكائن Date (التاريخ) والكائن number‎ (الزمن) -لتلك الخاصيات- غير مترابطة مع بعضها بعضًا؛ أي إسناد قيمةٌ جديدةٌ لأحدهما لن ينعكس على القيمة المقابلة البديلة للآخر.

الأوقات في الكائن Stats‎ لها الدلالات التالية:

  • atime‎ (وقت الوصول): يمثِّل هذا الوقت آخر مرةٍ جرى فيها الوصول إلى البيانات. يتغيَّر باستعمال استدعاءات النظام mknod(2)‎، و utimes(2)‎، و read(2)‎.
  • atime‎ (وقت التعديل): يمثِّل هذا الوقت آخر عملية تعديل أجريَت على البيانات. يتغيَّر باستعمال استدعاء النظام mknod(2)‎، و utimes(2)‎، و write(2)‎.
  • atime‎ (وقت التغيير): يمثِّل هذا الوقت آخرة مرةٍ تغيَّرَت فيها حالة الملف (تعديل بيانات مؤشِّر الفهرسة [inode]). يتغيَّر عبر استدعاءات النظام chmod(2)‎، و chown(2)‎، و link(2)‎، و mknod(2)‎، و rename(2)‎، و unlink(2)‎ و utimes(2)‎، و read(2)‎، و write(2)‎.
  • atime‎ (وقت الإنشاء): يمثِّل وقت إنشاء الملف، إذ يُضبَط هذا الوقت عندما يُنشَأ الملف. في أنظمة الملفات التي لا يتوافر فيها وقت الإنشاء، قد يأخذ هذا الحقل قيمةً بديلةً هي إمَّا القيمة ctime‎ أو القيمة 1970-01-01T00:00Z‎ (أي بصمة الوقت 0‎ في توقيت يونكس). في هذه الحالة، قد تكون هذه القيمة أكبر من القيمة atime‎ أو mtime‎. في نظام التشغيل Darwin‎ وتوزيعات FreeBSD أخرى، تُضبَط هذه القيمة أيضًا إذا ضُبِطَت القيمة atime‎ بشكل واضح إلى قيمة سابقة للقيمة birthtime‎ الحالية باستعمال استدعاء النظام utimes(2)‎.

قبل الإصدار Node.js 0.12، تأخذ القيمة ctime‎ نفس القيمة birthtime‎ في أنظمة ويندوز. بدءًا من الإصدار 0.12، لم تعد القيمة ctime‎ تمثل «وقت الإنشاء»، ولم تكن كذلك مطلقًا في الأنظمة الشبيه بيونكس.

الصنف fs.WriteStream‎

أضيف في الإصدار: v0.1.93.

يمثل الكائن WriteStream‎ مجرًى قابلًا للكتابة.

الحدث 'close'

أضيف في الإصدار: v0.1.93.

يُطلَق هذا الحدث عندما يُغلَق واصف الملف الموجود ضمنيًّا في الكائن WriteStream.

الحدث 'open'

أضيف في الإصدار: v0.1.93.

  • fd‎:‏ <integer> عدد صحيح يمثل واصف الملف الذي استعمله الكائن WriteStream.

يُطلَق هذا الحدث عندما يُفتَح واصف الملف للكائن WriteStream.

الحدث 'ready'

أضيف في الإصدار: v9.11.0.

يُطلَق هذا الحدث عندما يكون الكائن WriteStream جاهزًا للاستعمال؛ أي يُطلَق بعد الحدث 'open' مباشرةً.

writeStream.bytesWritten

أضيفت في الإصدار: v0.4.7.

تمثِّل هذه الخاصية عدد البايتات التي كُتبَت حين استدعائها. لا تتضمن هذه القيمة حجم البيانات الموجودة في الطابور بانتظار كتابتها.

readStream.path‎

أضيفت في الإصدار: v0.1.93.

تمثِّل هذه الخاصية مسار الملف الذي يُكتَب المجرى فيه كما حُدِّد في الوسيط الأول المُمرَّر إلى fs.createWriteStream()‎. إن كان المسار path‎ المُمرَّر سلسلةً نصيةً، فستعيد الخاصية writeStream.path‎ سلسلةً نصيةً أيضًا. أمَّا إن كان المسار path‎ المُمرَّر كائنًا من النوع Buffer‎، فستعيد الخاصية writeStream.path‎ كائنًا من النوع Buffer‎ أيضًا.

fs.access(path[, mode], callback)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمل البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v6.3.0 نُقلَت الثوابت مثل fs.R_OK‎ وغيرها التي توجد مباشرةً في fs‎ إلى fs.constants‎ كإهمال مرن وسلسل. وبالتالي، استعمل fs‎ في الإصدارات التي قبل v6.3.0 للوصول إلى هذه الثوابت، أو افعل شيئًا آخر مثل (fs.constants || fs).R_OK‎ للعمل مع جميع الإصدارات بطريقة واحدة.
v0.11.15 أضيف هذا التابع.

يفحص هذا التابع أذونات المستخدم للملف أو المجلد المحدَّد في المسار path‎. الوسيط mode‎ الاختياري هو عددٌ صحيحٌ يحدِّد عمليات التحقق من قابلية الوصول المراد تنفيذها. اطلع على القسم «ثوابت الوصول للملف» لمعرفة القيمة المتاحة للوسيط mode‎. يمكن إنشاء قناع يتألف من ثابتين أو أكثر عبر عملية الدمج الثنائية (bitwise) باستعمال المعامل OR (مثل fs.constants.W_OK | fs.constants.R_OK‎).

الوسيط الأخير، callback‎، هو دالة رد نداءٍ تُستدعَى مع وسيط الخطأ المحتمل حدوثه. إن فشلت إحدى عمليات التحقق من قابلية الوصول، فسيكون وسيط الخطأ الكائن Error‎. يتحقق المثال التالي من وجود الملف package.json‎ وإن كان قابلًا للقراءة أو الكتابة:

const file = 'package.json';

// التحقق من وجود الملف في المجلد الحالي
fs.access(file, fs.constants.F_OK, (err) => {
  console.log(`${file} ${err ? 'does not exist' : 'exists'}`);
});

// التحقق من كون الملف قابلًا للقراءة
fs.access(file, fs.constants.R_OK, (err) => {
  console.log(`${file} ${err ? 'is not readable' : 'is readable'}`);
});

// التحقق من كون الملف قابلًا للكتابة
fs.access(file, fs.constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not writable' : 'is writable'}`);
});

// التحقق من وجود الملف في المجلد الحالي ومن كونه قابلًا للقراءة
fs.access(file, fs.constants.F_OK | fs.constants.W_OK, (err) => {
  if (err) {
    console.error(
      `${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}`);
  } else {
    console.log(`${file} exists, and it is writable`);
  }
});

لا يُنصَح باستدعاء fs.access()‎ للتحقُّق من قابلة الوصول للملف قبل استدعاء fs.open()‎، أو fs.readFile()‎، أو fs.writeFile()‎، إذ يؤدي فعل ذلك إلى خلق «حالة تسابق» (race condition) لأنَّه ربما قد تُغيِّر عمليات أخرى حالة الملف بين الاستدعائين. بدلًا من ذلك، يجب على شيفرة المستخدم أن تفتح وتقرأ وتكتب في الملف مباشرةً وأن تعالج أي خطأ يُطلَق إن لم يكن الملف قابلًا للوصول. يوضح المثال التالي كيفية الكتابة على ملف بطريقةٍ لا يوصى بها:

fs.access('myfile', (err) => {
  if (!err) {
    console.error('myfile already exists');
    return;
  }

  fs.open('myfile', 'wx', (err, fd) => {
    if (err) throw err;
    writeMyData(fd);
  });
});

أمَّا المثال التالي، فيُوضِّح كيفية القراءة من ملف بالطريقة المُثلَى:

fs.open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  writeMyData(fd);
});

يوضح المثال التالي كيفية القراءة من ملف بطريقة لا يوصى بها:

fs.access('myfile', (err) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  fs.open('myfile', 'r', (err, fd) => {
    if (err) throw err;
    readMyData(fd);
  });
});

أمَّا المثال التالي، فيُوضِّح كيفية القراءة من ملف بالطريقة المُثلَى:

fs.open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  readMyData(fd);
});

تتحقَّق الأمثلة التي «لا يوصى باتباعها» من قابلة الوصول ثمَّ تستعمل الملف؛ أمَّا الأمثلة التي «يوصى باتباعها»، فهي أفضل لأنَّها تستعمل الملف مباشرةً وتعالج الخطأ إن حصل.

عمومًا، يُتحقَّق من قابلة الوصول للملف في حال استعمال الملف بشكل غير مباشر مثل عندما تكون قابلية وصول ملف إشارةً من عملية أخرى.

fs.accessSync(path[, mode])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمل البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.11.15 أضيف هذا التابع.

يفحص هذا التابع بشكل متزامن أذونات المستخدم للملف أو المجلد المحدَّد في المسار path‎. الوسيط mode‎ الاختياري هو عدد صحيح يحدِّد عمليات التحقُّق من قابلية الوصول المراد تنفيذها. اطلع على القسم «ثوابت الوصول للملف» لمعرفة القيمة المتاحة للوسيط mode‎. يمكن إنشاء قناع يتألف من ثابتين أو أكثر عبر عملية الدمج الثنائية (bitwise) باستعمال المعامل OR (مثل fs.constants.W_OK | fs.constants.R_OK‎).

إن فشلت إحدى عمليات قابلية الوصول، فيُسرمَى الخطأ Error‎. خلا ذلك، سيعيد التابع القيمة undefined‎.

try {
  fs.accessSync('etc/passwd', fs.constants.R_OK | fs.constants.W_OK);
  console.log('can read/write');
} catch (err) {
  console.error('no access!');
}

fs.appendFile(path, data[, options], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v7.0.0 لن يُغيَّر المعامل options المُمرَّر مطلقًا.
v5.0.0 يمكن للمعامل file‎ أن يكون واصف ملفٍ الآن.
v0.6.7 أضيف هذا التابع.

يضيف هذا التابع بشكل غير متزامن بياناتٍ إلى ملف، أو ينشئ ملفًا ويضع البيانات فيه إن لم يكن هذا الملف موجودًا. يمكن أن تكون البيانات data‎ المراد كتابتها سلسلةً نصيةً أو كائنًا من النوع Buffer‎.

fs.appendFile('message.txt', 'data to append', (err) => {
  if (err) throw err;
  console.log('The "data to append" was appended to file!');
});

إن كان الوسيط options‎ سلسلةً نصيةً، فسيُحدِّد حينئذٍ الترميز:

fs.appendFile('message.txt', 'data to append', 'utf8', callback);

يمكن أن يُعطَى المسار path‎ قيمةً عدديةً تمثِّل واصف الملف الذي فُتِح لإضافة البيانات فيه (باستعمال fs.open()‎ أو fs.openSync()‎). لن يُغلَق واصف الملف بشكل تلقائي.

fs.open('message.txt', 'a', (err, fd) => {
  if (err) throw err;
  fs.appendFile(fd, 'data to append', 'utf8', (err) => {
    fs.close(fd, (err) => {
      if (err) throw err;
    });
    if (err) throw err;
  });
});

fs.appendFileSync(path, data[, options])‎

سجل التغييرات
الإصدار التغييرات
v7.0.0 لن يُغيِّر المعامل options المُمرَّر مطلقًا.
v5.0.0 يمكن للمعامل file‎ أن يكون واصف ملفٍ الآن.
v0.6.7 أضيف هذا التابع.

يضيف هذا التابع بشكل متزامن بياناتٍ إلى ملف، أو ينشئ ملفًا ويضع البيانات فيه إن لم يكن هذا الملف موجودًا. يمكن أن تكون البيانات data‎ المراد كتابتها سلسلةً نصيةً أو كائنًا من النوع Buffer‎.

try {
  fs.appendFileSync('message.txt', 'data to append');
  console.log('The "data to append" was appended to file!');
} catch (err) {
  // عالج الخطأ (إن حصل) هنا
}

إن كان الوسيط options‎ سلسلةً نصيةً، فسيُحدِّد حينئذٍ الترميز:

fs.appendFileSync('message.txt', 'data to append', 'utf8');

يمكن أن يُعطَى المسار path‎ قيمةً عدديةً تمثُّل واصف الملف الذي فُتِح لإضافة البيانات فيه (باستعمال fs.open()‎ أو fs.openSync()‎). لن يُغلَق واصف الملف بشكل تلقائي.

let fd;

try {
  fd = fs.openSync('message.txt', 'a');
  fs.appendFileSync(fd, 'data to append', 'utf8');
} catch (err) {
  // عالج الخطأ (إن حصل) هنا
} finally {
  if (fd !== undefined)
    fs.closeSync(fd);
}

fs.chmod(path, mode, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path‎ كائنًا من النوع URL متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.30 أضيف هذا التابع.

يغيِّر هذا التابع بشكل غير متزامن أذونات ملفٍ. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه. انظر أيضًا الدالة chmod(2)‎.

نمط الملف (File Mode)

الوسيط mode‎ المستعمل في التابعين fs.chmod()‎ و fs.chmodSync()‎ كلاهما هو قناع بتِّي عددي (numeric bitmask) يُنشَأ باستعمال المعامل OR المنطقي للثوابت التالية:

الثابت القيمة الثمانية الإذن
fs.constants.S_IRUSR 0o400 يمكن للمالك قراءة الملف.
fs.constants.S_IWUSR 0o200 يمكن للمالك الكتابة على الملف.
fs.constants.S_IXUSR 0o100 يمكن للمالك تنفيذ الملف أو البحث ضمنه.
fs.constants.S_IRGRP 0o40 يمكن للمجموعة المالكة قراءة الملف.
fs.constants.S_IWGRP 0o20 يمكن للمجموعة المالكة الكتابة على الملف.
fs.constants.S_IXGRP 0o10 يمكن للمجموعة المالكة تنفيذ الملف أو البحث ضمنه.
fs.constants.S_IROTH 0o4 يمكن للآخرين قراءة الملف.
fs.constants.S_IWOTH 0o2 يمكن للآخرين الكتابة على الملف.
fs.constants.S_IXOTH 0o1 يمكن للآخرين تنفيذ الملف أو البحث ضمنه.

أسهل طريقة لضبط الوسيط mode‎ هي استعمال سلسلة من ثلاثة أعداد ثمانية (مثل العدد 765‎). يحدِّد العدد في أقصى اليسار (هو 7 في مثالنا) أذونات مالك الملف، والعدد الذي في المنتصف (هو 6 في مثالنا) أذونات المجموعة المالكة، والعدد في أقصى اليمين (هو 5 في مثالنا) أذونات الأشخاص الآخرين.

العدد الثماني الأذونات
7 القراءة والكتابة والتنفيذ.
6 القراءة والكتابة.
5 القراءة والتنفيذ.
4 القراءة فقط.
3 الكتابة والتنفيذ.
2 الكتابة فقط.
1 التنفيذ.
0 لا يوجد أذونات.

على سبيل المثال، القيمة الثمانية 0o765‎ تعني:

  • يُسمَح للمالك بقراءة وكتابة وتنفيذ الملف.
  • يُسمَح للمجموعة المالكة بالقراءة والكتابة على الملف.
  • يُسمَح للآخرين بقراءة وتنفيذ الملف.

عند استعمال الأعداد المجرَّدة في المكان الذي يُتوقَّع فيه استعمال أنماط الملف، يؤدي استعمال أية قيمة أكبر من 0o777‎ إلى حدوث سلوكيات غير مدعومة تختلف باختلاف المنصة المستعملة؛ وبالتالي، ثوابتٌ مثل S_ISVTX‎، و S_ISGID‎، و S_ISUID‎ غيرُ موجودةٍ في fs.constants‎. تحذير: في ويندوز، يمكن تغيير أذونات الكتابة فقط، ولا تؤخذ الاختلافات بين أذونات المجموعة المالكة، أو المالك، أو الآخرين بالحسبان.

fs.chmodSync(path, mode)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path‎ كائنًا من النوع URL متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.30 أضيف هذا التابع.

يغيِّر هذا التابع بشكل متزامن أذونات ملفٍ. لمزيد من التفاصيل، ارجع إلى توثيق الإصدار غير المتزامن من هذه الواجهة البرمجية وهي fs.chmod()‎.

انظر أيضًا الدالة chmod(2)‎.

fs.chown(path, uid, gid, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path‎ كائنًا من النوع URL متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.30 أضيف هذا التابع.

يغيِّر هذا التابع بشكل غير متزامن المالك والمجموعة المالكة لملف. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

انظر أيضًا: chown(2)‎.

fs.chownSync(path, uid, gid)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path‎ كائنًا من النوع URL متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.30 أضيف هذا التابع.

يغيِّر هذا التابع بشكل متزامن المالك والمجموعة المالكة لملف، أو يعيد القيمة undefined. هذا التابع هو النسخة المتزامنة من التابع fs.chown()‎.

انظر أيضًا: chown(2)‎.

‎fs.close(fd, callback)

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.30 أضيف هذا التابع.

يغلق هذا التابع بشكل غير متزامن ملفًا مفتوحًا، إذ يُنفِّذ دالة النظام close(2)‎. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

fs.closeSync(fd)‎

أضيف في الإصدار: v0.1.21.

يغلق هذا التابع بشكل متزامن ملفًا مفتوحًا، إذ يُنفِّذ دالة النظام close(2)‎. يعيد القيمة undefined‎.

fs.constants‎

يعيد هذا التابع كائنًا يحوي الثوابت الأكثر استعمالًا في عمليات نظام الملفات. الثوابت المعرَّفة حاليًا تجدها مع شرحٍ لها في القسم «الثوابت المستعملة في الوحدة fs‎» في الأسفل.

fs.copyFile(src, dest[, flags], callback)‎

أضيف في الإصدار:v8.5.0.

  • src:‏ <string>‏ | <Buffer>‏ | <URL> اسم الملف المراد نسخه.
  • dest:‏ <string>‏ | <Buffer>‏ | <URL> اسم الملف الوجهة الذي سيُنسَخ في الملف المحدَّد في المعامل src.
  • flags:‏ <number> مُعدِّلات (modifiers) عملية النسخ. القيمة الافتراضية هي: 0.
  • callback:‏ <Function>

ينسخ هذا التابع ملفًا من src‎ إلى dest‎ بشكل غير متزامن. تُستبدَل قيمة الوسيط dest‎ إن كانت موجودة مسبقًا بشكل افتراضي. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه. لا تعطِ Node.js أية ضمانات متعلقة بتجزئة عملية النسخ. إن حصل أي خطأ بعد فتح الملف الوجهة للكتابة، ستحاول Node.js إزالته.

الوسيط flags‎ اختياري وهو عددٌ صحيحٌ يحدِّد سلوك عملية النسخ. يمكن إنشاء قناع يتألف من ثابتين أو أكثر عبر عملية الدمج الثنائية (bitwise) باستعمال المعامل OR (مثل fs.constants.COPYFILE_FICLONE | fs.constants.COPYFILE_EXCL). الثوابت المدعومة هي:

  • fs.constants.COPYFILE_EXCL‎: ستفشل عملية النسخ إن كان الملف dest‎ موجودًا من قبل.

fs.constants.COPYFILE_FICLONE‎: ستحاول عملية النسخ إنشاء وصلة مرجعية (reflink) بنمط «النسخ عند الكتابة» (copy-on-write). إن لم تدعم المنصة نمط «النسخ عند الكتابة»، فستُستخدَم آلية النسخ التراجعي (fallback copy).

  • fs.constants.COPYFILE_FICLONE‎: ستحاول عملية النسخ إنشاء وصلة مرجعية (reflink) بنمط «النسخ عند الكتابة» (copy-on-write). إن لم تدعم المنصة نمط «النسخ عند الكتابة»، فستفشل عملية النسخ.
const fs = require('fs');

// أو سيُستبدَل بشكل افتراضي destination.txt سيُنشَأ الملف
fs.copyFileSync('source.txt', 'destination.txt');
console.log('source.txt was copied to destination.txt');

إن كان الوسيط الأخير عددًا، فهو يحدِّد الوسيط flags‎:

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

// موجودًا من قبل destination.txt ستفشل العملية إن كان الملف ،COPYFILE_EXCL باستخدام الثابت
fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL);

fs.createReadStream(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path‎ كائنًا من النوع URL متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لن يُغيِّر المعامل options المُمرَّر مطلقًا.
v2.3.0 يمكن أن يكون المعامل options المُمرَّر سلسلة نصية الآن.
v0.1.31 أضيف هذا التابع.
  • القيم المعادة: <fs.ReadStream> انظر القسم «المجاري القابلة للقراءة» في توثيق الوحدة stream‎.

المجرى المُعاد باستعمال هذا التابع يملك القيمة 64 كيلو بت الافتراضية للوسيط highWaterMark‎ خلافًا للمجرى القابل للقراءة الذي يملك القيمة 16 كيلو بت فقط لذلك الوسيط.

يمكن أن يتضمن الوسيط options‎ الخيارين start‎ و end‎ لقراءة مجالٍ محدَّدٍ من البايتات من الملف بدلًا من قراءته كاملًا. يدخل الوسيطين start‎ و end‎ كلاهما ضمن المجال، ويبدأ الوسيط من القيمة 0. إن حُدِّد الوسيط fd‎ ولم يُعطَ الوسيط start‎ أو كانت قيمته undefined‎، فسيقرأ التابع fs.createReadStream()‎ بالتسلسل بدءًا من موقع المؤشر الحالي للملف. يمكن أن يكون الوسيط encoding‎ أيًّا من الترميزات المقبولة في الصنف Buffer‎.

إن أعطي الوسيط fd‎، فسيتجاهل ReadStream‎ الوسيط path‎ ويستخدم واصف الملف المعطى. هذا يعني أنَّه لن يُطلَق الحدث 'open'. يجب أن يكون واصف الملف fd‎ المعطى محجوزًا. يجب أن يمرَّر واصف الملف غير المحجوز إلى net.Socket‎.

إن كان واصف الملف fd‎ يشير إلى جهاز محرفي (character device) يدعم وضع القراءة المحجوزة (blocking reads) فقط (مثل لوحة المفاتيح أو بطاقة الصوت)، فلن تنتهي عملية القراءة حتى تتوافر البيانات. هذا يساعد بمنع العملية من الخروج والمجرى من الإغلاق بشكل طبيعي.

const fs = require('fs');
// إنشاء مجرًى من بعض الأجهزة المحرفية
const stream = fs.createReadStream('/dev/input/event0');
setTimeout(() => {
  stream.close(); // قد لا يُغلق هذا المجرى
  // ؛ فإن أشار المورد(artificially marking) نهاية المجرى هي علامة اصطناعية 
  // .الضمني إلى نهاية الملف، فهذا سيسمح بإغلاق المجرى
  // هذا لا يلغي عمليات الكتابة قيد الانتظار، وإذا كان هنالك مثل 
  // هذه العمليات، فربما لن تستطيع العملية الخروج بنجاح
  // .حتى تنتهي
  stream.push(null);
  stream.read(0);
}, 100);

إن كانت قيمة الوسيط autoClose‎ هي false‎، فلن يُغلَق واصف الملف حينئذٍ حتى لو حصل خطأ. في هذه الحالة، تقع مسؤولية إغلاق الملف على عاتق التطبيق والتأكد من عدم حصول تسريب في واصفات الملفات. إن ضُبِط الوسيط autoClose‎ إلى القيمة true‎ (السلوك الافتراضي)، فسيُغلَق واصف الملف تلقائيًّا متى ما أطلق الحدث 'error' أو الحدث 'end'.

يضبط الوسيط mode‎ نمط الملف (الأذونات والبتات اللاصقة [sticky bits]) في حال أنشئ الملف آنذاك فقط.

إليك مثالٌ يوضِّح كيفية قراءة آخر 10 بايتات من ملفٍ بحجم 100 بايت:

fs.createReadStream('sample.txt', { start: 90, end: 99 });

إن كان options‎ سلسلةً نصيةً، فسيُحدِّد حينئذٍ الترميز.

fs.createWriteStream(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path‎ كائنًا من النوع URL متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لن يُغيِّر المعامل options المُمرَّر مطلقًا.
v2.3.0 يمكن أن يكون المعامل options المُمرَّر سلسلة نصية الآن.
v0.1.31 أضيف هذا التابع.
  • القيم المعادة: <fs.ReadStream> انظر القسم «المجاري القابلة للكتابة» في توثيق الوحدة stream‎.

يمكن أن يتضمن الوسيط options‎ الخيارstart‎ للسماح بكتابة البيانات في موضع محدِّد بعد تخطي عددٍ محدِّدٍ من البايتات الأولى. قد يتطلَّب تعديل الملف بدلًا من استبداله أن تكون قيمة الخيار flags‎ هي 'r+' بدلًا من القيمة 'w' الافتراضية. يمكن أن يكون الوسيط encoding‎ أيًّا من الترميزات المقبولة في الصنف Buffer‎.

إن كانت قيمة الوسيط autoClose‎ هي false‎، فلن يُغلَق واصف الملف حينئذٍ حتى لو حصل خطأ. في هذه الحالة، تقع مسؤولية إغلاق الملف على عاتق التطبيق والتأكد من عدم حصول تسريبٍ في واصفات الملفات. أمَّا إن ضُبِط الوسيط autoClose‎ إلى القيمة true‎ (السلوك الافتراضي)، فسيُغلَق واصف الملف تلقائيًّا متى ما أطلق الحدث 'error' أو الحدث 'end'.

إن أعطي الوسيط fd‎، فسيتجاهل WriteStream الوسيط path‎ ويستخدم واصف الملف المعطى. هذا يعني أنه لن يُطلَق الحدث 'open'. يجب أن يكون واصف الملف fd‎ المعطى محجوزًا. يجب أن يمرَّر واصف الملف غير المحجوز إلى net.Socket‎.

إن كان options‎ سلسلةً نصيةً، فسيُحدِّد حينئذٍ الترميز.

fs.exists(path, callback)‎

الاستقرار: 0 - مهمل. استعمل التابع fs.stat()‎ أو fs.access()‎ بدلًا منه.

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path‎ كائنًا من النوع URL متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v1.0.0 أهمل هذا التابع.
v0.0.2 أضيف هذا التابع.

يتحقق هذا التابع إن كان المسار المعطى موجودًا أم لا عبر التحقق من نظام الملفات ثم يستدعي الوسيط callback‎ إمَّا مع القيمة true‎ أو القيمة false‎.

fs.exists('/etc/passwd', (exists) => {
  console.log(exists ? 'it\'s there' : 'no passwd!');
});

ملاحظة: معاملات رد النداء هذا غير متناسقة مع معاملات ردود نداء Node.js الأخرى. الحالة السائدة هي أن يكون المعامل الأول لرد النداء في Node.js هو المعامل err‎ متبوعًا بمعاملات أخرى اختيارية. رد النداء في التابع fs.exists()‎ يملك معامل منطقي وحيد فقط. هذا هو أحد الأسباب التي يوصى من أجلها استعمال التابع fs.access()‎ عوضًا عن التابع fs.exists()‎. لا يُنصَح باستعمال التابع fs.exists()‎ للتحقق من وجود ملفٍ قبل استدعاء fs.open()‎، أو fs.readFile()‎، أو fs.writeFile()‎. يؤدي فعل ذلك إلى خلق «حالة سباق» (race condition) لأنه ربما قد تُغيِّر عمليات أخرى حالة الملف بين الاستدعائين. بدلًا من ذلك، يجب على شيفرة المستخدم أن تفتح وتقرأ وتكتب في الملف مباشرةً وأن تعالج أي خطأ يُطلَق إن لم يكن موجودًا. يوضح المثال التالي كيفية الكتابة على ملف بطريقة لا يوصى بها:

fs.exists('myfile', (exists) => {
  if (exists) {
    console.error('myfile already exists');
  } else {
    fs.open('myfile', 'wx', (err, fd) => {
      if (err) throw err;
      writeMyData(fd);
    });
  }
});

أمَّا المثال التالي، فيوضح كيفية الكتابة على ملف بالطريقة المُثلَى:

fs.open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  writeMyData(fd);
});

يوضح المثال التالي كيفية القراءة من ملف بطريقة لا يوصى بها:

fs.exists('myfile', (exists) => {
  if (exists) {
    fs.open('myfile', 'r', (err, fd) => {
      if (err) throw err;
      readMyData(fd);
    });
  } else {
    console.error('myfile does not exist');
  }
});

أمَّا المثال التالي، فيوضِّح كيفية القراءة من ملف بالطريقة المُثلَى:

fs.open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  readMyData(fd);
});

تتحقق الأمثلة التي «لا يوصى باتباعها» من وجود الملف ثم تستعمله؛ أمَّا الأمثلة التي «يوصى باتباعها»، فهي أفضل لأنَّها تستعمل الملف مباشرةً وتعالج الخطأ إن حصل.

عمومًا، يُتحقَّق من وجود الملف في حال استُعمِل الملف بشكل غير مباشر مثل عندما يكون وجود ملف إشارةً من عملية أخرى.

fs.existsSync(path)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path‎ كائنًا من النوع URL متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.21 أضيف هذا التابع.

يعيد التابع القيمة true‎ إن كان المسار موجودًا، أو القيمة false‎ خلا ذلك. لتفاصيل أوسع، انظر توثيق النسخة الغير متزامنة من هذا التابع وهي التابع fs.exists()‎.

انتبه إلى أنَّ التابع fs.exists()‎ مهمل، ولكن التابع fs.existsSync()‎ غير مهمل. المعامل callback‎ المُمرَّر إلى fs.exists()‎ يقبل معاملات تعد غير متناسقة مع معاملات ردود النداء الأخرى في Node.js.

لا يستعمل التابع fs.existsSync()‎ رد نداءٍ.

fs.fchmod(fd, mode, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.4.7 أضيف هذا التابع.

يغيِّر هذا التابع نمط الملف (file mode) عبر استدعاء النظام fchmod(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

fs.fchmodSync(fd, mode)‎

أضيف في الإصدار: v0.4.7.

يغيِّر هذا التابع نمط الملف (file mode) عبر استدعاء النظام fchmod(2)‎ بشكل متزامن.

fs.fchown(fd, uid, gid, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.4.7 أضيف هذا التابع.

يغيِّر هذا التابع المستخدم المالك للملف عبر استدعاء النظام fchown(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

fs.fchownSync(fd, uid, gid)‎

أضيف في الإصدار: v0.4.7.

يغيِّر هذا التابع المستخدم المالك للملف عبر استدعاء النظام fchown(2)‎ بشكل متزامن. يعيد هذا التابع القيمة undefined‎.

fs.fdatasync(fd, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.96 أضيف هذا التابع.

ينفِّذ هذا التابع استدعاء النظام fdatasync(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

fs.fdatasyncSync(fd)‎

أضيف في الإصدار: v0.1.96.

ينفِّذ هذا التابع استدعاء النظام fdatasync(2)‎ بشكل متزامن. يعيد هذا التابع القيمة undefined‎.

fs.fstat(fd[, options], callback)‎

الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.95 أضيف هذا التابع.
  • fd:‏ <integer>
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • callback:‏ <Function>
  • stats:‏ <fs.Stats>

يجلب هذا التابع معلومات حول الملف عبر استدعاء دالة النظام fstat(2)‎ بشكل غير متزامن. يمرَّر إلى دالة رد النداء وسيطين هما: err‎، و stats‎، إذ stats‎ هو الكائن fs.Stats‎. التابع fstat()‎ ممائلٌ تمامًا للتابع stat()‎ باستثناء أنَّ الملف المراد جلب معلومات عنه يحدَّد عبر واصف الملف fd.

fs.fstatSync(fd[, options])‎

سجل التغييرات
الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v0.1.95 أضيف هذا التابع.
  • fd:‏ <integer>
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • القيم المعادة: <fs.Stats>

يجلب هذا التابع معلومات حول الملف عبر استدعاء دالة النظام fstat(2)‎ بشكل متزامن.

fs.fsync(fd, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.95 أضيف هذا التابع.

ينفِّذ هذا التابع دالة النظام fsync(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

fs.fsyncSync(fd)‎

أضيف في الإصدار: 0.1.96.

ينفِّذ هذا التابع دالة النظام fsync(2)‎ بشكل متزامن. يعيد هذا التابع القيمة undefined‎.

fs.ftruncate(fd[, len], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.8.6 أضيف هذا التابع.

يقطع هذا التابع الملف ذا الواصف fd‎ إلى الحجم len‎ عبر استدعاء دالة النظام ftruncate(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

إن كان حجم الملف أكبر من الحجم len‎ المعطى بالبايت، فستُعاد البايتات len‎ الأولى فقط من الملف. على سبيل المثال، يعيد البرنامج التالي البايتات الأربعة الأولى فقط من الملف:

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Node.js :سيُطبَع

// جلب واصف الملف للملف المراد اقتطاعه
const fd = fs.openSync('temp.txt', 'r+');

// اقتطاع أول أربعة بايتات من الملف
fs.ftruncate(fd, 4, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt', 'utf8'));
});
// Node :سيُطبَع
إن كان حجم الملف أقل من الحجم <code>len‎</code> المراد اقتطاعه، فسيُمدَّد حجم الملف إلى الحجم <code>len‎</code> بالبايت وستُملَأ البايتات المضافة ببايتات عدمية (أي بالقيمة <code>'\0'‎</code>):
<syntaxhighlight lang="javascript">console.log(fs.readFileSync('temp.txt', 'utf8'));
// Node.js :سيُطبَع

// جلب واصف الملف للملف المراد اقتطاعه
const fd = fs.openSync('temp.txt', 'r+');

// محاولة اقتطاع الملف إلى الحجم 10 بايت في حين أن حجمه الحقيقي هو 7 بايت
fs.ftruncate(fd, 10, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt'));
});
// <Buffer 4e 6f 64 65 2e 6a 73 00 00 00> :سيُطبَع
// (UTF8 في الترميز 'Node.js\0\0\0' أي تكون)

البايتات الأخيرة المضافة هي بايتات عدمية ('\0'‎) لتعويض البايتات الإضافية الناتجة عن عملية الإفراط في الاقتطاع (over-truncation).

fs.ftruncateSync(fd[, len])‎

أضيف في الإصدار: v0.8.6.

يقطع هذا التابع الملف ذا الواصف fd‎ إلى الحجم len‎ عبر استدعاء دالة النظام ftruncate(2)‎ بشكل متزامن. لمزيد من التفاصيل، اطلع رجاءً على توثيق الإصدار غير المتزامن من هذا التابع الذي هو fs.ftruncate()‎.

fs.futimes(fd, atime, mtime, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v4.1.0 يُسمَح الآن بأن تُستعمَل السلاسل النصية العددية، والقيمة NaN، والقيمة Infinity‎ لتكون محدِّدات للوقت (time specifiers).
v0.4.2 أضيف هذا التابع.

يغيِّر هذا التابع بصمات وقت نظام الملفات للكائن المشار إليه بواصف الملف المعطى. اطلع على التابع fs.utimes()‎.

لا يعمل هذا التابع على إصدارات AIX التي قبل 7.1، إذ ستعيد إن استعملت في تلك الإصدارات الخطأ UV_ENOSYS‎.

fs.futimesSync(fd, atime, mtime)‎

سجل التغييرات
الإصدار التغييرات
v4.1.0 يُسمَح الآن بأن تُستعمَل السلاسل النصية العددية، والقيمة NaN‎، والقيمة Infinity‎ لتكون محدِّدات للوقت (time specifiers).
v0.4.2 أضيف هذا التابع.

يمثِّل هذا التابع الإصدار المتزامن من التابع fs.futimes()‎. يعيد هذا التابع القيمة undefined‎.

fs.lchmod(path, mode, callback)‎

الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.4.7 أضيف هذا التابع.

يغيِّر هذا التابع أذونات ملفٍ عبر استدعاء lchmod(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه. هذا التابع متاحٌ في أنظمة macOS فقط.

‎fs.lchmodSync(path, mode)‎

أهملت بدءًا من الإصدار: v0.4.7.

يغيِّر هذا التابع أذونات ملفٍ عبر استدعاء lchmod(2)‎ بشكل متزامن. يعيد هذا التابع القيمة undefined‎.

fs.lchown(path, uid, gid, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.6.0 لم تعد هذه الواجهة البرمجية مهملةً بعد الآن.
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.

يغيِّر هذا التابع المالك والمجموعة المالكة لملف عبر استدعاء lchown(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

fs.chownSync(path, uid, gid)‎

سجل التغييرات
الإصدار التغييرات
v10.6.0 لم تعد هذه الواجهة البرمجية مهملةً بعد الآن.

يغيِّر هذا التابع المالك والمجموعة المالكة لملف عبر استدعاء lchown(2)‎ بشكل متزامن. يعيد هذا التابع القيمة undefined‎.

fs.link(existingPath, newPath, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط existingPath والوسيط newPath كائنات من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.31 أضيف هذا التابع.

ينشئ هذا التابع وصلةً جديدةً (وصلةً صلبةً) للملف الحالي عبر استدعاء link(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

fs.linkSync(existingPath, newPath)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط existingPath والوسيط newPath كائنات من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.31 أضيف هذا التابع.

ينشئ هذا التابع وصلةً جديدةً (وصلةً صلبةً) للملف الحالي عبر استدعاء link(2)‎‎ بشكل متزامن. يعيد هذا التابع القيمة undefined‎.

fs.lstat(path[, options], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.30 أضيف هذا التابع.
  • path:‏‏ <string>‏ | <Buffer>‏ | <URL>
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • callback:‏ <Function>
  • stats:‏ <fs.Stats>

يجلب هذا التابع معلومات حول الملف ذي المسار path‎ عبر استدعاء دالة النظام lstat(2)‎ بشكل غير متزامن. يمرَّر إلى دالة رد النداء وسيطين هما: err‎، و stats‎، إذ stats‎ هو الكائن fs.Stats‎. التابع lstat()‎ ممائلٌ تمامًا للتابع stat()‎ باستثناء أنَّه إذا كان المسار path‎ وصلةً رمزيةً، فستُعاد حينئذٍ معلومات عن الوصلة نفسها وليس عن الملف الذي تشير إليه هذه الوصلة.

fs.lstatSync(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.30 أضيف هذا التابع.
  • path:‏‏ <string>‏ | <Buffer>‏ | <URL>
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • القيم المعادة: <fs.Stats>

يجلب هذا التابع معلومات حول الملف ذي المسار path‎ عبر استدعاء دالة النظام lstat(2)‎ بشكل متزامن.

fs.mkdir(path[, mode], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.8 أضيف هذا التابع.

ينشئ هذا التابع مجلدًا جديدًا بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه. انظر أيضًا الدالة mkdir(2)‎.

fs.mkdirSync(path[, mode])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.21 أضيف هذا التابع.
  • path:‏‏ <string>‏ | <Buffer>‏ | <URL>
  • mode:‏ <integer> غير مدعوم على ويندوز. القيمة الافتراضية هي: 0o777‎.

ينشئ هذا التابع مجلدًا جديدًا بشكل متزامن. يعيد هذا التابع القيمة undefined‎. هذا التابع هو الإصدار المتزامن من التابع fs.mkdir()‎.

انظر أيضًا الدالة mkdir(2)‎.

fs.mkdtemp(prefix[, options], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v6.2.1 أصبح المعامل callback‎ الآن اختياريًّا.
v5.10.0 أضيف هذا التابع.

ينشئ هذا التابع مجلدًا فريدًا مؤقتًا بشكل غير متزامن.

يولِّد هذا التابع ستة محارف عشوائية لتضاف في نهاية البادئة prefix‎ المطلوبة لإنشاء مجلدٍ فريدٍ مؤقتٍ.

يمرَّر مسار المجلد المُنشَأ كسلسلة نصية إلى المعامل الثاني لدالة رد النداء.

يمكن أن يكون الوسيط options‎ سلسلةً نصيةً تحدِّد الترميز، أو كائنًا مع الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله.

fs.mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, folder) => {
  if (err) throw err;
  console.log(folder);
  // /tmp/foo-itXde2 أو C:\Users\...\AppData\Local\Temp\foo-itXde2 :سيُطبَع
});

سيضيف التابع fs.mkdtemp()‎ المحارف الستة العشوائية المختارة مباشرةً إلى السلسلة prefix‎ النصية. على سبيل المثال، إن كان لدينا المجلد ‎/tmp‎ وأردنا إنشاء مجلد مؤقت داخله، فيجب أن تنتهي البادئة prefix‎ بالفاصلة الزائدة المستعملة عادةً في فصل المسار في المنصة المستعملة آنذاك (require('path').sep‎).

// المجلد الأب للمجلد المؤقت الجديد
const tmpDir = os.tmpdir();

// :*استعمال التابع بهذه الطريقة *غير صحيح
fs.mkdtemp(tmpDir, (err, folder) => {
  if (err) throw err;
  console.log(folder);
  // `/tmpabc123` سيطبع شيء شبيه بالقيمة
  // ينشأ المجلد المؤقت الجديد في نظام الملفات الجذر
  // /tmp بدلًا من إنشائه *ضمن* المجلد
});

// :*استعمال التابع بهذه الطريقة هو *الصحيح
const { sep } = require('path');
fs.mkdtemp(`${tmpDir}${sep}`, (err, folder) => {
  if (err) throw err;
  console.log(folder);
  // `/tmp/abc123` سيطبع شيء شبيه بالقيمة
  // أنشئ المجلد المؤقت الجديد ضمن
  // كما هو مطلوب /tmp المجلد
});

fs.mkdtempSync(prefix[, options])‎

أضيف في الإصدار: v5.10.0.

ينشئ هذا التابع مجلدًا مؤقتًا فريدًا بشكل متزامن.

لمزيد من المعلومات، اطلع على توثيق الإصدار الغير متزامن من هذا التابع الذي هو fs.mkdtemp()‎.

يمكن أن يكون الوسيط options‎ سلسلةً نصيةً تحدِّد الترميز، أو كائنًا مع الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله.

fs.open(path, flags[, mode], callback)‎

سجل التغييرات
الإصدار التغييرات
v9.9.0 أصبح الوضعان <code>as‎</code> و <code>as+‎</code> مدعومين الآن.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.0.2 أضيف هذا التابع.

يفتح هذا التابع ملفًا بشكل غير متزامن. اطلع على دليل الدالة open(2)‎.

يضبط الوسيط mode‎ نمط الملف (الأذونات والبتات اللاصقة [sticky bits]) في حال لم يكن الملف موجودًا وأنشئ آنذاك. في ويندوز، يمكن التلاعب بإذن الكتابة فقط. اطلع على توثيق التابع fs.chmod()‎. تأخذ دالة رد النداء وسيطين هما: err‎ و fd‎. تعدُّ بعض المحارف (مثل < > : " / \ | ? *‎) محجوزةً في ويندوز كما أشير إلى ذلك التوثيق «تسمية الملفات، والمسارات، ومجالات الأسماء». في نظام الملفات NTFS، إن احتوى اسم الملف نقطتين رأسيتين، فستفتح Node.js مجرًى في نظام الملفات كما موضح في هذه الصفحة.

التوابع التي تعتمد على التابع fs.open()‎ تسلك السلوك نفسه أيضًا مثل التابع fs.writeFile()‎ و التابع fs.readFile()‎ ...إلخ.

‎fs.openSync(path, flags[, mode])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.21 أضيف هذا التابع.

يفتح هذا التابع ملفًا بشكل متزامن. اطلع على دليل الدالة open(2)‎.

لمزيدٍ من التفاصيل، اطلع على الإصدار غير المتزامن لهذا التابع الذي هو fs.open()‎.

fs.read(fd, buffer, offset, length, position, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 يمكن الآن أن يكون المعامل buffer‎ كائنًا من النوع TypedArray‎ أو DataView‎.
v7.4.0 يمكن الآن أن يكون المعامل buffer‎ كائنًا من النوع Uint8Array.
v6.0.0 يمكن أن يأخذ المعامل length‎  الآن القيمة 0.
v0.0.2 أضيف هذا التابع.
  • fd:‏‏ <string>‏
  • buffer:‏ <Buffer>‏ | <TypedArray>‏ | <DataView> يمثِّل ذاكرة التخزين المؤقتة التي ستُكتَب فيها البيانات المقروءة من الملف.
  • offset:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية كتابة البيانات في ذاكرة التخزين المؤقتة buffer‎ (أي مقدار الإزاحة من بدياتها).
  • length:‏ <integer> عددٌ صحيحٌ يحدِّد عدد البايتات المراد قراءتها من الملف.
  • position:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية قراءة البيانات من الملف. إن كانت قيمة هذا الوسيط null‎، فستُقرَأ البيانات بدءًا من موضع المؤشر الحالي في الملف ثم سيُحدَّث موضع مؤشِّر الملف بعد انتهاء عملية القراءة. إن كانت قيمة هذا الوسيط عددًا صحيحًا، فسيبقى موضع مؤشِّر الملف دون تغيير.
  • callback:‏ <Function>

يقرأ هذا التابع البيانات من الملف المحدَّد في واصف الملف fd‎ المعطى.

تأخذ دالة رد النداء ثلاثة وسائط هي: err‎ و bytesRead‎ و buffer‎.

إن استدعي هذا التابع مثل نظيره util.promisify()‎، فسيُعيد كائنًا من النوع Promise‎ لكائن Object‎ مع الخاصيتين bytesRead و buffer.

fs.readdir(path[, options], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 أضيف الخيار withFileTypes‎.
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v6.0.0 أضيف المعامل options.
v0.1.8 أضيف هذا التابع.

يقرأ هذا التابع محتوى المجلد المحدَّد في المسار عبر تنفيذ الدالة readdir(3)‎ بشكل غير متزامن. يمُرَّر إلى دالة رد النداء وسيطين هما: err‎ و files‎، إذ files‎ هو مصفوفةٌ من أسماء الملفات في المجلد باستثناء المجلد '.'‎ والمجلد '..'‎.

يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله لأسماء الملفات الممرَّرة إلى دالة رد النداء. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فستُمرَّر أسماء الملفات المعادة ككائنات من النوع Buffer‎.

إن ضُبِط الخيار options.withFileTypes‎ إلى القيمة true‎، فستحوي المصفوفة files‎ الكائنات fs.Diret‎.

fs.readdirSync(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 أضيف الخيار withFileTypes‎.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.21 أضيف هذا التابع.

يقرأ هذا التابع محتوى المجلد المحدَّد في المسار عبر تنفيذ الدالة readdir(3)‎ بشكل متزامن.

يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله لأسماء الملفات الممرَّرة إلى دالة رد النداء. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فستُمرَّر أسماء الملفات المعادة ككائنات من النوع Buffer‎.

إن ضُبِط الخيار options.withFileTypes‎ إلى القيمة true‎، فسيحوي الناتج الكائنات fs.Diret‎.

‎fs.readFile(path[, options], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v5.1.0 سيستدعى رد النداء callback‎ مع القيمة null‎ بوصفها قيمة للمعامل error‎ في حال نجاح العملية.
v5.0.0 يمكن أن يكون المعامل path‎ واصف ملفٍ الآن.
v0.1.29 أضيف هذا التابع.

يقرأ هذا التابع كامل محتوى الملف ذي المسار path‎ بشكل غير متزامن.

fs.readFile('/etc/passwd', (err, data) => {
  if (err) throw err;
  console.log(data);
});

يمُرَّر إلى دالة رد النداء وسيطين هما: err‎ أو data‎، إذ data‎ هو المحتوى المقروء من الملف. إن لم يُحدَّد أي ترميز، فسيكون نوع الوسيط data‎ هو كائنٌ من النوع Buffer‎. إن كان الوسيط options‎ سلسلة نصية، فسيُحدِّد حينئذٍ الترميز:

fs.readFile('/etc/passwd', 'utf8', callback);

عندما يكون المسار path‎ مجلدًا، سيختلف سلوك التابع fs.readFile()‎ والتابع fs.readFileSync()‎ اعتمادًا على المنصة المستعملة؛ في أنظمة التشغيل macOS، ولينكس، وويندوز، سيؤدي ذلك إلى رمي خطأ. أمَّا في FreeBSD، فسيعاد تمثيلٌ بمحتوى المجلد.

// macOS, Linux, and Windows
fs.readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: illegal operation on a directory, read <directory>]
});

//  FreeBSD
fs.readFile('<directory>', (err, data) => {
  // => null, [[JavaScript/Date|<Date>]]
});

يجب على واصف الملف المحدَّد أن يدعم عملية القراءة.

إن حُدِّد واصف ملفٍ كمسار path‎، فلن يُغلَق الملف تلقائيًّا بعد انتهاء العملية.

يُخزِّن التابع fs.readFile()‎ كامل محتوى الملف في الذاكرة مؤقتًا. لتقليل الحجم المستهلك من الذاكرة، يفضل استعمال المجرى عبر fs.createReadStream()‎ إن كان ذلك ممكنًا.

fs.readFileSync(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v5.0.0 يمكن أن يكون المعامل path‎ واصف ملفٍ الآن.
v0.1.29 أضيف هذا التابع.

يقرأ هذا التابع كامل محتوى الملف ذي المسار path‎ بشكل متزامن ثمَّ يعيده.

لمزيدٍ من التفاصيل، اطلع على الإصدار غير المتزامن من هذا التابع الذي هو fs.readFile()‎.

إن لم يُحدَّد أي ترميز، فسيُعاد كائنٌ من النوع Buffer‎. أمَّا إن حُدِّد الخيار encoding، فستُعاد سلسلةٌ نصيةٌ حينئذٍ.

بشكل مشابه للتابع fs.readFile()‎، عندما يكون المسار path‎ مجلدًا، فسيختلف سلوك التابع fs.readFile()‎ والتابع fs.readFileSync()‎ اعتمادًا على المنصة المستعملة؛ في أنظمة التشغيل macOS، ولينكس، وويندوز، سيؤدي ذلك إلى رمي خطأ. أما في FreeBSD، فسيعاد تمثيلٌ بمحتوى المجلد.

// macOS, Linux, and Windows
fs.readFileSync('<directory>');
// => [Error: EISDIR: illegal operation on a directory, read <directory>]

//  FreeBSD
fs.readFileSync('<directory>'); // => [[JavaScript/Date|<Date>]]

fs.readlink(path[, options], callback)‎

الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.1.31 أضيف هذا التابع.

يقرأ هذا التابع محتوى الوصلة الرمزية ذات المسار path‎ عبر استدعاء الدالة readlink(2)‎ بشكل غير متزامن.

يمرَّر دالة رد النداء وسيطين هما: err‎، و linkString‎.

يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله مع مسار الوصلة الممرَّر إلى دالة رد النداء. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فسيُمرَّر مسار الوصلة المعاد ككائن من النوع Buffer‎.

‎fs.readlinkSync(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.31 أضيف هذا التابع.

يقرأ هذا التابع محتوى الوصلة الرمزية ذات المسار path‎ عبر استدعاء الدالة readlink(2)‎ بشكل متزامن. يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله مع مسار الوصلة المعاد. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'‎، فسيُمرَّر مسار الوصلة المعاد ككائن من النوع Buffer‎.

fs.readSync(fd, buffer, offset, length, position)‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 يمكن الآن أن يكون المعامل buffer‎ كائنًا من النوع TypedArray‎ أو DataView‎.
v6.0.0 يمكن أن يأخذ المعامل length‎ الآن القيمة 0.
v0.1.21 أضيف هذا التابع.
  • fd:‏‏ <string>‏
  • buffer:‏ <Buffer>‏ | <TypedArray>‏ | <DataView> يمثِّل ذاكرة التخزين المؤقتة التي ستُكتَب فيها البيانات المقروءة من الملف.
  • offset:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية كتابة البيانات في ذاكرة التخزين المؤقتة buffer‎ (أي مقدار الإزاحة من بدياتها).
  • length:‏ <integer> عددٌ صحيحٌ يحدِّد عدد البايتات المراد قراءتها من الملف.
  • position:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية قراءة البيانات من الملف. إن كانت قيمة هذا الوسيط null‎، فستُقرَأ البيانات بدءًا من موضع المؤشر الحالي في الملف ثم سيُحدَّث موضع مؤشِّر الملف بعد انتهاء عملية القراءة. إن كانت قيمة هذا الوسيط عددًا صحيحًا، فسيبقى موضع مؤشِّر الملف دون تغيير.
  • القيم المعادة: <number>

يقرأ هذا التابع البيانات من الملف المحدَّد في واصف الملف fd‎ المعطى ويضعها في المخزن buffer‎ ثم يعيد عدد البايتات المقروءة.

لمزيد من التفاصيل، اطلع على توثيق الإصدار غير المتزامن من هذا التابع الذي هو fs.read()‎.

fs.realpath(path[, options], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v8.0.0 أضيف دعمٌ لاستبيان أنبوب أو مقبس.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v6.4.0 أصبح استدعاء هذا التابع يعمل مجدَّدًا لمختلف الحالات الحدية في ويندوز.
v6.0.0 حُذِف المعامل cache‎.
v0.1.31 أضيف هذا التابع.

يحسب هذا التابع اسم المسار الأساسي (canonical pathname) بشكل غير متزامن عبر استبيان .‎، و ..‎، والوصلات الرمزية. ليس بالضرورة أن يكون اسم المسار المتعارف عليه فريدًا. يمكن للوصلات الصلبة ونظام الملفات الموصول (عبر الأمر mount) أن يكشفا عن نظام ملفات عبر أسماء مسارات متعددة. يسلك هذا التابع نفس سلوك الدالة realpath(3)‎ باستثناء بعض الأمور منها:

  • لا تجرى أية عملية تحويل لحالة الأحرف على أنظمة الملفات الغير حساسة لحالة الأحرف.
  • يعتمد العدد الأقصى للوصلات الرمزية على المنصة المستعملة، ويكون غالبًا أكبر بكثير من العدد الذي يدعمه تنفيذ realpath(3)‎.

يمرَّر إلى دالة رد النداء وسيطين هما: err‎، و resolvedPath‎. قد يُستخدَم process.cwd‎ لاستبيان المسارات النسبية. المسارات المدعومة هي المسارات التي يمكن تحويلها إلى سلاسل نصية مرمزة بالترميز UTF8 فقط. يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله مع المسار الممرَّر إلى دالة رد النداء. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فسيُمرَّر المسار المعاد ككائن من النوع Buffer‎. إن استبين المسار إلى مقبسٍ أو أنبوبٍ، فسيعيد هذا التابع اسمًا يعتمد على النظام لذلك الكائن.

fs.realpath.native(path[, options], callback)‎

أضيف في الإصدار: v9.2.0.

يعيد هذا التابع المسار الأساسي المطلق للمسار path‎ عبر تنفيذ realpath(3)‎ بشكل غير متزامن. يمرَّر إلى دالة رد النداء وسيطين هما: err‎، و resolvedPath‎. المسارات المدعومة هي المسارات التي يمكن تحويلها إلى سلاسل نصية مرمزة بالترميز UTF8 فقط. يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله مع المسار الممرَّر إلى دالة رد النداء. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فسيُمرَّر المسار المعاد ككائن من النوع Buffer‎. في لينكس، عندما تُربَط Node.js مع المكتبة musl libc، يجب أن يوصل (mount) نظام الملفات procfs في ‎/proc‎ لكي يعمل هذا التابع بشكل صحيح. أما المكتبة glibc، فلا تشترط ذلك.

fs.realpathSync(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v8.0.0 أضيف دعمٌ لاستبيان أنبوب أو مقبس.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v6.4.0 أصبح استدعاء هذا التابع يعمل مجدَّدًا لمختلف الحالات الحدية في ويندوز.
v6.0.0 حُذِف المعامل cache‎.
v0.1.31 أضيف هذا التابع.

يعيد هذا التابع اسم المسار المستبين. لمزيدٍ من التفاصيل، اطلع على توثيق الإصدار غير المتزامن من هذا التابع الذي هو fs.realpath()‎.

fs.realpathSync.native(path[, options])‎

أضيف في الإصدار: v9.2.0.

يعيد هذا التابع المسار الأساسي المطلق للمسار path‎ عبر تنفيذ realpath(3)‎ بشكل متزامن. المسارات المدعومة هي المسارات التي يمكن تحويلها إلى سلاسل نصية مرمزةً بالترميز UTF8 فقط. يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله مع المسار المعاد. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فسيُمرَّر المسار المعاد ككائن من النوع Buffer‎. في لينكس، عندما تُربَط Node.js مع المكتبة musl libc، يجب أن يوصل (mount) نظام الملفات procfs في ‎/proc‎ لكي يعمل هذا التابع بشكل صحيح. أمَّا المكتبة glibc، فلا تشترط ذلك.

fs.rename(oldPath, newPath, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط oldPath والوسيط newPath كائنات من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.0.2 أضيف هذا التابع.

يغيِّر هذا التابع اسم الملف oldPath‎ إلى newPath‎ المعطى بشكل غير متزامن. إن كان الملف newPath‎ موجودًا من قبل، فسيُستبدَل آنذاك. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه. انظر أيضًا دالة النظام rename(2)‎.

fs.rename('oldFile.txt', 'newFile.txt', (err) => {
  if (err) throw err;
  console.log('Rename complete!');
});

‎fs.renameSync(oldPath, newPath)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط oldPath والوسيط newPath كائنات من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.21 أضيف هذا التابع.

يغيِّر هذا التابع اسم الملف oldPath‎ إلى newPath‎ المعطى بشكل متزامن. إن كان الملف newPath‎ موجودًا من قبل، فسيُستبدَل آنذاك. انظر أيضًا دالة النظام rename(2)‎.

‎fs.rmdir(path, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.0.2 أضيف هذا التابع.

يحذف هذا التابع المجلد ذا المسار path‎ عبر استدعاء rmdir(2)‎ بشكل غير متزامن. يؤدي استعمال التابع fs.rmdir()‎ مع ملف (وليس مجلد) إلى حصول الخطأ ENOENT‎ في ويندوز والخطأ ENOTDIR‎ في أنظمة POSIX.

‎fs.rmdirSync(path)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.21 أضيف هذا التابع.

يحذف هذا التابع المجلد ذا المسار path‎ عبر استدعاء rmdir(2)‎ بشكل متزامن. يؤدي استعمال التابع fs.rmdirSync()‎ مع ملف (وليس مجلد) إلى حصول الخطأ ENOENT‎ في ويندوز والخطأ ENOTDIR‎ في أنظمة POSIX.

‎fs.stat(path[, options], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.0.2 أضيف هذا التابع.
  • path:‏ <string>‏ | <Buffer>‏ | <URL>
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • callback:‏ <Function>
  • stats:‏ <fs.Stats>

يجلب هذا التابع معلومات حول الملف ذي المسار path‎ عبر استدعاء دالة النظام stat(2)‎ بشكل غير متزامن. يمرَّر إلى دالة رد النداء وسيطين هما: err‎، و stats‎، إذ stats‎ هو الكائن fs.Stats‎. إن حصل خطأ، سيكون err.code‎ أحد أخطاء النظام الشائعة. لا ينصح باستعمال التابع fs.stat()‎ للتحقق من وجود الملف قبل استدعاء fs.open()‎، أو fs.readFile()‎، أو fs.writeFile()‎. بدلًا من ذلك، يجب على شيفرة المستخدم فتح الملف والقراءة منه أو الكتابة عليه مباشرةً ومعالجة الخطأ المرمي إن لم يكن الملف موجودًا. للتحقق من وجود ملفٍ دون التعديل عليه بعد ذلك، ينصح باستعمال التابع fs.access()‎.

fs.statSync(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.21 أضيف هذا التابع.
  • path:‏ <string>‏ | <Buffer>‏ | <URL>
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • القيم المعادة: <fs.Stats>

يجلب هذا التابع معلومات حول الملف ذي المسار path‎ عبر استدعاء دالة النظام stat(2)‎ بشكل متزامن.

fs.symlink(target, path[, type], callback)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط target والوسيط path كائنات من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.31 أضيف هذا التابع.

ينشئ هذا التابع وصلة رمزيَّةً لملف المحدد بالمسار target‎ عبر استدعاء symlink(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه. يمكن ضبط الوسيط type‎ إلى القيمة 'dir'، أو 'file'، أو 'junction' وهو متاح في ويندوز فقط (يُتجاهل في المنصات الأخرى). تتطلب نقاط الوصل (junction points) في ويندوز أن يكون المسار الهدف مطلقًا. عند استعمال 'junction'، فسيحول الوسيط target‎ تلقائيًّا إلى مسار مطلق. إليك هذا المثال الذي سيُنشأ وصلة رمزية تدعى "new-port" تشير إلى الملف "foo":

fs.symlink('./foo', './new-port', callback);

fs.symlinkSync(target, path[, type])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط target والوسيط path كائنات من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.31 أضيف هذا التابع.

ينشئ هذا التابع وصلة رمزيَّةً لملف المحدد بالمسار target‎ عبر استدعاء symlink(2)‎ بشكل متزامن. لمزيد من التفاصيل، ارجع إلى الإصدار الغير متزامن من هذا التابع الذي هو fs.symlink()‎.

‎fs.truncate(path[, len], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.8.6 أضيف هذا التابع.

يقطع هذا التابع الملف ذا المسار path إلى الحجم len‎ عبر استدعاء دالة النظام truncate(2)‎ بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه. كان بالإمكان أن يُمرَّر واصف ملف كوسيط أول أيضًا، وسيستدعى في هذه الحالة التابع fs.ftruncate()‎، إلا أنه ذلك قد أُهمِل وقد يؤدي إلى رمي خطأ في المستقبل.

‎fs.truncateSync(path[, len])‎

أضيف في الإصدار: v0.8.6.

يقطع هذا التابع الملف ذا المسار path إلى الحجم len‎ عبر استدعاء دالة النظام truncate(2)‎ بشكل متزامن. كان بالإمكان أن يُمرَّر واصف ملف كوسيط أول أيضًا، وسيستدعى في هذه الحالة التابع fs.ftruncate()‎، إلا أنه ذلك قد أُهمِل وقد يؤدي إلى رمي خطأ في المستقبل.

fs.unlink(path, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.0.2 أضيف هذا التابع.

يزيل هذا التابع ملفًا أو وصلةً رمزيةً بشكل غير متزامن. لن تُعَط دالة رد النداء المُكمِّلة أية وسائط غير الاستثناء المحتمل وقوعه.

// هو ملف طبيعي 'path/file.txt' بفرض أن  الملف
fs.unlink('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was deleted');
});

لن يعمل التابع fs.unlink()‎ إن كان المسار فارغًا أو يشير إلى مجلد أو غير ذلك من الحالات. إن أردت حذف مجلد، فاستعمل التابع fs.rmdir()‎. انظر أيضًا دالة النظام unlink(2)‎.

fs.unlinkSync(path)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.21 أضيف هذا التابع.

يزيل هذا التابع ملفًا أو وصلةً رمزيةً بشكل غير متزامن. يعيد هذا التابع القيمة undefined‎. انظر أيضًا دالة النظام unlink(2)‎.

fs.unwatchFile(filename[, listener])‎

أضيف في الإصدار: v0.1.31.

  • filename:‏ <string>‏ | <Buffer>‏ | <URL>
  • path:‏ <Function>‏ وسيط اختياري يمثل المستمع السابق الذي ربط باستعمال fs.watchFile()‎.

يوقف هذا التابع عملية مراقبة التغييرات التي تحصل في الملف filename‎. إن أعطي الوسيط listener‎، فسيحذف التابع هذا المستمع المحدد فقط. خلا ذلك، سيزيل جميع المستمعين موقفًا عملية مراقبة الملف filename‎ بشكل فعَّال. يمثِّل استدعاء التابع fs.unwatchFile()‎ مع اسم ملف لا يراقب آنذاك عمليةً فارغةً ولا يعد ذلك خطأً. يعدُّ استعمال التابع fs.watch()‎ أكثر فاعليةً من استعمال fs.watchFile()‎، و fs.unwatchFile()‎. يجب أن يُستعمَل التابع fs.watch()‎ بدلًا من التابع fs.watchFile()‎، و fs.unwatchFile()‎ ما أمكن ذلك.

fs.utimes(path, atime, mtime, callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v8.0.0 لا يُسمَح بعد الآن بأن تُستعمَل القيمة NaN‎، والقيمة Infinity‎، والقيمة Infinity- لتكون محدِّدات للوقت (time specifiers).
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v4.1.0 يُسمَح الآن بأن تُستعمَل السلاسل النصية العددية، والقيمة NaN‎، والقيمة Infinity‎ لتكون محدِّدات للوقت (time specifiers).
v0.4.2 أضيف هذا التابع.

يغيِّر هذا التابع بصمات وقت نظام الملفات للكائن المشار إليه بالمسار المعطى بشكل غير متزامن. يخضع الوسيطان atime‎ و mtime‎ إلى القاعدتين التاليتين:

  • يمكن أن تكون القيم إما أعدادًا تمثل الوقت في توقيت يونكس (Unix epoch time)، أو التواريخ، أو سلاسل نصية عددية مثل '123456789.0'‎.
  • إن لم يكن بالإمكان تحويل القيمة إلى عددٍ، أو كانت NaN‎ أو Infinity‎ أو -Infinity‎، فسيُرمَى خطأٌ.

‎fs.utimesSync(path, atime, mtime)‎

سجل التغييرات
الإصدار التغييرات
v8.0.0 لا يُسمَح بعد الآن بأن تُستعمَل القيمة NaN‎، والقيمة Infinity‎، والقيمة Infinity- لتكون محدِّدات للوقت (time specifiers).
v7.6.0 يمكن الآن أن يكون الوسيط path كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v4.1.0 يُسمَح الآن بأن تُستعمَل السلاسل النصية العددية، والقيمة NaN‎، والقيمة Infinity‎ لتكون محدِّدات للوقت (time specifiers).
v0.4.2 أضيف هذا التابع.

يغيِّر هذا التابع بصمات وقت نظام الملفات للكائن المشار إليه بالمسار المعطى بشكل متزامن. لمزيدٍ من التفاصيل، اطلع على توثيق الإصدار غير المتزامن من هذا التابع الذي هو fs.utimes()‎.

fs.watch(filename[, options][, listener])‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط filename كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v7.0.0 لن يُعدَّل الكائن options‎ المُمرَّر مطلقًا.
v0.5.10 أضيف هذا التابع.
  • filename:‏ <string>‏ | <Buffer>‏ | <URL>
  • options:‏ <string>‏ | <Object>
    • persistent:‏ <boolean> يحدِّد إن كان يجب أن تستمر العملية بالعمل ما دامت عملية مراقبة الملف مستمرة. القيمة الافتراضية هي: true‎.
    • recursive:‏ <boolean> يحدِّد إن كان يجب مراقبة جميع المجلدات الفرعية أيضًا أم يجب مراقبة المجلد المحدد فقط. يُستعمَل هذا الخيار عندما يراد مراقبة مجلد، ولا يعمل إلا على المنصات المدعومة (اطلع على «تحذيرات يجب أخذها بالحسبان» في الأسفل). القيمة الافتراضية هي: false‎.
    • encoding:‏ <string> يحدد ترميز المحارف المراد استعماله من أجل اسم الملف الممرر إلى المستمع. القيمة الافتراضية هي: 'utf8'.
  • listener:‏ <Function>‏ | <undefined> القيمة الافتراضية هي: undefined‎.
  • القيم المعادة: <fs.FSWatcher>

ينشئ هذا التابع عملية مراقبة على filename‎ لمراقبة جميع التغييرات الحاصلة، إذ إما أن يكون filename‎ ملفًا أو مجلدًا. الوسيط options‎ الممرر إلى هذا التابع اختياري. إن أعطي وكان سلسلة نصية، فسيُحدِّد حينئذٍ الترميز encoding‎ المراد استعماله. خلا ذلك، يجب تمرير الوسيط options‎ ككائن. يمرَّر إلى دالة رد النداء التي تمثل المستمع (listener) وسيطان هما: eventType‎ و filename‎؛ يأخذ الوسيط eventType‎‎ إما القيمة 'rename' أو القيمة 'change'، بينما يمثل الوسيط filename‎ اسم الملف الذي أطلَق الحدث. في أغلب منصات التشغيل، يُطلَق الحدث 'rename' متى ما ظهر اسم الملف أو اختفى في المجلد. يُربَط رد النداء المستمع مع الحدث 'change' الذي يُطلَق عبر fs.FSWatcher‎، ولكن هذا الحدث لا يشبه القيمة 'change' الممررة إلى الوسيط eventType‎.

تحذيرات يجب أخذها بالحسبان

الواجهة البرمجية fs.watch‎ ليست ثابتة 100% عبر جميع المنصات، إذ تكون غير متوافرة في بعض الحالات. الخيار recursive‎ مدعومٌ فقط في macOS وويندوز.

التوافر

تعتمد هذه الميزة على نظام التشغيل بشكل أساسي الذي يوفر طريقةً للتنبيه بالتغيُّرات التي تحصل في نظام الملفات.

  • في أنظمة لينكس، يُستعمَل inotify(7)‎.
  • في أنظمة BSD، يُستعمَل kqueue(2)‎.
  • في أنظمة macOS، يُستعمَل kqueue(2)‎ للملفات و FSEvents‎ للمجلدات.
  • في أنظمة SunOS (بما فيها Solaris و SmartOS)، يُستعمَل منافذ الحدث (event ports).
  • في أنظمة ويندوز، تعتمد هذه الميزة على ReadDirectoryChangesW‎.
  • في أنظمة Aix، تعتمد هذه الميزة على AHAFS‎ التي يجب تفعليها.

الوظيفة الأساسية غير متوافرة لعدة أسباب، لذا لن يستطيع fs.watch‎ أن يؤدي وظيفته. على سبيل المثال، يمكن أن تكون عملية مراقبة ملفات أو مجلدات غير جديرة بالثقة، أو مستحيلة في بعض الحالات، في أنظمة ملفات الشكبة (مثل NFS، أو SMB، وغيرها) أو أنظمة ملفات المضيف عند استعمال تطبيقات افتراضية مثل Vagrant، أو Docker وغيرهما. لا يزال بالإمكان استعمال fs.watchFile()‎ الذي يستعمل «استطلاع الحالة» (stat polling) إلا أن هذه الطريقة أبطأ وذات وثوقية أقل.

مؤشرات الفهرسة (Inodes)

في أنظمة لينكس و macOS، يستبين التابع fs.watch()‎ المسار إلى قيمة مؤشر الفهرسة (inode) ويراقب هذا المؤشر. إن حذف المسار الذي يخضع للمراقبة، فسيُسنَد إلى مؤشر فهرسة جديد. سيُطلِق المراقب حدثًا يتعلق بأمر الحذف الذي حصل، ولكنه سيستمر بعملية مراقبة مؤشر الفهرسة الأصلي (original inode). لن تُطلَق أية أحداث لمؤشر الفهرسة الجديد، لذا يجب أن يكون هذا متوقعًا. تحتفظ ملفات AIX بمؤشر الفهرسة نفسه خلال دورة حياة الملف. حفظ وإغلاق ملف مراقب في AIX سيؤدي إلى إطلاق تنبيهين أحدهما من أجل إضافة محتوى جديد والآخر من أجل الاقتطاع (truncation).

الوسيط filename‎

تمرير الوسيط filename‎ إلى دالة رد النداء مدعومٌ فق لينكس، وويندوز، و macOS، و AIX فقط. حتى في الأنظمة المدعومة، لا يُضمَن أن يُعطَى الوسيط filename‎ دومًا؛ نتيجةً لذلك، لا تفترض أن الوسيط filename‎ معطًى دومًا في رد النداء، وليكن هنالك احتمالية التراجع المنطقي في الشيفرة إن كانت قيمته null‎.

fs.watch('somedir', (eventType, filename) => {
  console.log(`event type is: ${eventType}`);
  if (filename) {
    console.log(`filename provided: ${filename}`);
  } else {
    console.log('filename not provided');
  }
});

fs.watchFile(filename[, options], listener)‎

سجل التغييرات
الإصدار التغييرات
v7.6.0 يمكن الآن أن يكون الوسيط filename كائنًا من النوع URL‎ متوافق مع WHATWG باستعمال البروتوكول file:‎. ما زال هذا الدعم قيد التجريب.
v0.1.31 أضيف هذا التابع.
  • filename:‏ <string>‏ | <Buffer>‏ | <URL>
  • options:‏ <string>‏ | <Object>
    • persistent:‏ <boolean> يحدِّد إن كان يجب أن تستمر العملية بالعمل ما دامت عملية مراقبة الملف مستمرة. القيمة الافتراضية هي: true‎.
    • interval:‏ <string>
  • listener:‏ <Function>
    • current:‏ <fs.Stats>
    • previous:‏ <fs.Stats>

يراقب هذا التابع التغيرات التي تحصل على filename‎. سيُستدعى رد النداء listener‎ في كل مرة يتم فيها الوصول إلى الملف. يمكن عدم تمرير الوسيط options‎. إن أعطي، فيجب أن يكون كائنًا. قد يحوي الكائن options‎ قيمة منطقية تدعى persistent‎ تحدِّد إن كان يجب أن تستمر العملية بالعمل ما دامت عملية مراقبة الملف مستمرة. قد يحدِّد الكائن options‎ الخاصية interval‎ التي تشير إلى عدد المرات التي يجب فيها أن يُستطلَع الهدف بالميلي ثانية. يمرَّر إلى رد النداء listener‎ وسيطان هما الكائن fs.Stats‎ الذي يمثل الحالة الحالية، والكائن fs.Stats‎ الذي يمثل الحالة السابقة.

fs.watchFile('message.text', (curr, prev) => {
  console.log(`the current mtime is: ${curr.mtime}`);
  console.log(`the previous mtime was: ${prev.mtime}`);
});

إنَّ كلًا من كائني الحالة هذين هو نسخةٌ من fs.Stat‎. للحصول على تنبيهات عند تعديل الملف وليس عند الوصول إليه، إنَّه من الضروري الموازنة بين curr.mtime‎ و prev.mtime‎. عندما تصادف عملية مراقبة ملف باستعمال التابع fs.watchFile()‎ الخطأ ENOENT‎، سيستدعي التابع آنذاك رد النداء listener‎ مرة واحدة مع تصفير جميع الحقول للكائنين الممرَّرين إليه (أو ضبطها إلى تاريخ البداية في يونكس بالنسبة للتواريخ). في ويندوز، ستكون قيمة الحقلين blksize‎ و blocks‎ هي ‎undefined‎ بدلًا من الصفر. إن أنشئ الملف في وقت لاحق، فسيُستدعَى رد النداء listener‎ مجدَّدًا مع تمرير الكائنين الذين يحويان أحدث معلومات عن الحالة (stat). أصبح هذا التغير في سلوك التابع معتمدًا بدءًا من الإصدار v0.10. يعدُّ استعمال التابع fs.watch()‎ أكثر فاعليةً من استعمال fs.watchFile()‎، و fs.unwatchFile()‎. يجب أن يُستعمَل التابع fs.watch()‎ بدلًا من التابع fs.watchFile()‎، و fs.unwatchFile()‎ ما أمكن ذلك. عندما يختفي ملفٌ يخضع للمراقبة عبر fs.watchFile()‎ ويظهر مجدَّدًا، ستكون حينئذٍ الحالة السابقة (previousStat) المُبلَّغ عنها في الحدث الثاني لرد النداء (إعادة ظهور الملف) نفس الحالة السابقة للحدث الأول لرد النداء (اختفاء الملف). هذا يحدث عندما:

  • يُحذَف الملف ثم يُتبَع بتنفيذ عملية استعادة له، أو
  • يعاد تسمية الملف مرتين، إذ يعاد تسمية الملف في المرة الثانية إلى اسمه الأصلي.

fs.write(fd, buffer[, offset[, length[, position]]], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 يمكن أن يكون المعامل buffer الآن كائنًا من النوع TypeError‎ أو النوع DataView‎.
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.4.0 يمكن الآن أن يكون المعامل buffer‎ كائنًا من النوع Uint8Array.
v7.2.0 أصبح تمرير المعاملين offset‎ و length‎ اختياريًّا الآن.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.0.2 أضيف هذا التابع.
  • fd:‏‏ <integer>‏
  • buffer:‏ <Buffer>‏ | <TypedArray>‏ | <DataView> يمثِّل جزءًا من ذاكرة التخزين المؤقتة التي ستُقرَأ منها البيانات المراد كتابتها في الملف.
  • offset:‏ <integer> عددٌ صحيحٌ يحدِّد جزء البيانات من ذاكرة التخزين المؤقتة buffer‎ المراد كتابته.
  • length:‏ <integer> عددٌ صحيحٌ يحدِّد عدد البايتات المراد كتابتها في الملف.
  • position:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية كتابة البيانات في الملف بدءًا من بداية الملف (أي يحدِّد مقدار الإنزياح من بداية الملف). إن كان typeof position !=='number'‎، فستُكتَب البيانات بدءًا من موضع المؤشر الحالي في الملف. اطلع على الدالة pwrite(2)‎.
  • callback:‏ <Function>

يكتب هذا التابع البيانات المحددة في الذاكرة buffer‎ في الملف ذي الواصف fd‎ المعطى. تأخذ دالة رد النداء ثلاثة وسائط هي: err‎ و bytesWritten و buffer‎، إذ يحدد bytesWritten‎ عدد البايتات التي كُتبَت من buffer‎. إن استدعي هذا التابع مثل نظيره util.promisify()‎، فسيُعيد كائنًا من النوع Promise‎ لكائن Object‎ مع الخاصيتين bytesWritten و buffer. إنه من غير الآمن استدعاء التابع fs.write()‎ عدة مرات مع نفس الملف دون انتظار رد النداء. في مثل هذه الحالة، يُنصَح باستعمال التابع fs.createWriteStream()‎. في لينكس، لن يحرك مؤشر الكتابة إلى موضع معين عند فتح الملف في وضع الإضافة (append mode). ستتجاهل النواة الوسيط position‎ وستضيف البيانات إلى نهاية الملف دومًا.

fs.write(fd, string[, position[, encoding]], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.2.0 أصبح تمرير المعامل position اختياريًّا الآن.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v0.11.5 أضيف هذا التابع.
  • fd:‏‏ <integer>‏
  • string:‏ <string>‏ سلسلة نصية تحوي البيانات المراد كتابتها في الملف.
  • position:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية كتابة البيانات في الملف بدءًا من بداية الملف (أي يحدِّد مقدار الإنزياح من بداية الملف). إن كان typeof position !== 'number'‎، فستُكتَب البيانات بدءًا من موضع المؤشر الحالي في الملف. اطلع على الدالة pwrite(2)‎.
  • encoding:‏‏ <string>‏ يمثِّل الترميز المتوقع للسلسلة النصية. القيمة الافتراضية هي: 'utf8'.
  • callback:‏ <Function>

يكتب هذا التابع البيانات الموجودة في السلسلة النصية string في الملف ذي الواصف fd‎ المعطى بشكل غير متزامن. إن لم يكون الوسيط string‎ سلسلةً نصيةً، فستُحوَّل حينئذٍ القيمة رغمًا عنها إلى الواحد. تأخذ دالة رد النداء ثلاثة وسائط هي: err‎ و written و string، إذ يحدد written عدد بايتات السلسلة النصية المعطاة المطلوب كتابتها في الملف. لا يُشترَط أن تكون البايتات المكتوبة في الملف هي نفسها المحارف المعطاة في السلسلة النصية. اطلع على توثيق التابع Buffer.byteLength()‎. إنه من غير الآمن استدعاء التابع fs.write()‎ عدة مرات مع نفس الملف دون انتظار رد النداء. في مثل هذه الحالة، يُنصَح باستعمال التابع fs.createWriteStream()‎. في لينكس، لن يحرك مؤشر الكتابة إلى موضع معين عند فتح الملف في وضع الإضافة (append mode). ستتجاهل النواة الوسيط position‎ وستضيف البيانات إلى نهاية الملف دومًا.

fs.writeFile(file, data[, options], callback)‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 يمكن أن يكون المعامل data الآن كائنًا من النوع TypeError‎ أو النوع DataView.
v10.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُرمَى الخطأ TypeError‎ في وقت التشغيل إن لم يُمرَّر.
v7.4.0 يمكن أن يكون المعامل data كائنًا من النوع Uint8Array‎.
v7.0.0 لم يعد المعامل callback‎ اختياريًّا بعد الآن. سيُطلَق تحذير إهمال مع المعرِّف DEP0013 إن لم يُمرَّر.
v5.0.0 يمكن أن يكون المعامل file‎ واصف ملفٍ الآن.
v0.1.29 أضيف هذا التابع.

يكتب هذا التابع البيانات الموجودة في الوسيط data في الملف file المعطى بشكل غير متزامن، إذ يستبدل الملف إن كان موجودًا مسبقًا. يمكن أن يكون الوسيط data‎ سلسلةً نصيةً أو مخزنًا مؤقتًا في الذاكرة (buffer). سيُتجاهَل الخيار encoding‎ إن كان الوسيط data‎ مخزنًا مؤقتًا.

const data = new Uint8Array(Buffer.from('Hello Node.js'));
fs.writeFile('message.txt', data, (err) => {
  if (err) throw err;
  console.log('The file has been saved!');
});

إن كان الوسيط options‎ سلسلةً نصيةً، فسيُحدِّد حينئذٍ الترميز:

fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);

يجب على واصف الملف المعطى أن يدعم عملية الكتابة على الملف. إنه من غير الآمن استدعاء التابع fs.writeFile()‎ عدة مرات مع نفس الملف دون انتظار رد النداء. في مثل هذه الحالة، يُنصَح باستعمال التابع fs.createWriteStream()‎. إن أعطي واصف ملف للوسيط file‎، فلن يُغلَق الملف تلقائيًّا.

fs.writeFileSync(file, data[, options])‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 يمكن أن يكون المعامل data الآن كائنًا من النوع TypeError‎ أو النوع DataView‎.
v7.4.0 يمكن أن يكون المعامل data كائنًا من النوع Uint8Array‎.
v5.0.0 يمكن أن يكون المعامل file‎ واصف ملفٍ الآن.
v0.1.29 أضيف هذا التابع.

يكتب هذا التابع البيانات الموجودة في الوسيط data في الملف file المعطى بشكل متزامن، إذ يستبدل الملف إن كان موجودًا مسبقًا. يعيد هذا التابع القيمة undefined‎. لمزيدٍ من التفاصيل، اطلع على توثيق الإصدار المتزامن من هذا التابع الذي هو fs.writeFile()‎.

fs.writeSync(fd, buffer[, offset[, length[, position]]])‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 يمكن أن يكون المعامل buffer الآن كائنًا من النوع TypeError‎ أو النوع DataView‎.
v7.4.0 يمكن الآن أن يكون المعامل buffer‎ كائنًا من النوع Uint8Array.
v7.2.0 أصبح تمرير المعاملين offset‎ و length‎ اختياريًّا الآن.
v0.1.21 أضيف هذا التابع.
  • fd:‏‏ <integer>‏
  • buffer:‏ <Buffer>‏ | <TypedArray>‏ | <DataView> يمثِّل جزءًا من ذاكرة التخزين المؤقتة التي ستُقرَأ منها البيانات المراد كتابتها في الملف.
  • offset:‏ <integer> عددٌ صحيحٌ يحدِّد جزء البيانات من ذاكرة التخزين المؤقتة buffer‎ المراد كتابته.
  • length:‏ <integer> عددٌ صحيحٌ يحدِّد عدد البايتات المراد كتابتها في الملف.
  • position:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية كتابة البيانات في الملف بدءًا من بداية الملف (أي يحدِّد مقدار الإنزياح من بداية الملف). إن كان typeof position !== 'number'‎، فستُكتَب البيانات بدءًا من موضع المؤشر الحالي في الملف. اطلع على الدالة pwrite(2)‎.
  • القيم المعادة: <number> عدد البايتات التي كُتبَت.

يكتب هذا التابع البيانات المحددة في الذاكرة buffer‎ في الملف ذي الواصف fd‎ المعطى بشكل متزامن. لمزيدٍ من التفاصيل، اطلع على توثيق الإصدار المتزامن من هذا التابع الذي هو fs.write(fd, buffer...)‎.

fs.writeSync(fd, string[, position[, encoding]])‎

سجل التغييرات
الإصدار التغييرات
v7.2.0 أصبح تمرير المعامل position اختياريًّا الآن.
v0.11.5 أضيف هذا التابع.
  • fd:‏‏ <integer>‏
  • string:‏ <string>‏ سلسلة نصية تحوي البيانات المراد كتابتها في الملف.
  • position:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية كتابة البيانات في الملف بدءًا من بداية الملف (أي يحدِّد مقدار الإنزياح من بداية الملف). إن كان typeof position !== 'number'‎، فستُكتَب البيانات بدءًا من موضع المؤشر الحالي في الملف. اطلع على الدالة pwrite(2)‎.
  • encoding:‏‏ <string>‏ يمثِّل الترميز المتوقع للسلسلة النصية. القيمة الافتراضية هي: 'utf8'.

القيم المعادة: <number> عدد البايتات التي كُتبَت. يكتب هذا التابع البيانات الموجودة في السلسلة النصية string في الملف ذي الواصف fd‎ المعطى بشكل متزامن. لمزيدٍ من التفاصيل، اطلع على توثيق الإصدار المتزامن من هذا التابع الذي هو fs.write(fd, string...)‎.

واجهة الوعود (Promises) البرمجية في الوحدة fs‎

الاستقرار: 1 - قيد التجريب.

توفِّر الواجهة البرمجية fs.promises‎ مجموعةً بديلةً لتوابع نظام الملفات الغير متزامنة تعيد الكائن Promise‎ بدلًا من استعمال رد النداء. يمكن الوصول إلى هذه الواجهة البرمجية عبر require('fs').promises‎.

الصنف FileHandle‎

أضيف في الإصدار: v10.0.0.

الكائن FileHandle‎ هو مغلفٌ لواصف ملفٍ عدديٍّ. تختلف النسخ المنشأة من FileHandle‎ عن واصفات الملفات العددية، إذ إن لم يُغلَق الكائن FileHandle‎ مثلًا بشكل صريح عبر استعمال التابع filehandle.close()‎، فسيُغلَق واصف الملف تلقائيًّا وسيُصدَر تحذير بالعملية. هذا يساعد في منع حدوث تسريبٍ في الذاكرة. تُنشَأ نسخٌ من الصنف FileHandle‎ ضمنيًّا عبر التابع fsPromises.open()‎. لا يُستعمَل واصف ملف عددي عبر الواجهات البرمجية التي تعتمد على الوعود خلافًا للواجهات البرمجية التي تعتمد على ردود النداء (مثل fs.fstat()‎، و fs.fchown()‎، و fs.fchmod()‎، ...إلخ.). عوضًا عن ذلك، الواجهات البرمجية التي تعتمد على الوعود تستعمل الصنف FileHandle‎ لتجنب حدوث تسريب في واصفات الملفات غير المغلقة بشكل غير مقصود بعد أن يُقبَل الكائن Promise‎ أو يُرفَض.

‎filehandle.appendFile(data, options)‎

أضيف في الإصدار: v10.0.0.

يضيف هذا التابع بيانات إلى هذا الملف، أو يُنشئ ملفًا إن لم يكن الملف موجودًا بعد. يمكن أن يكون الوسيط data‎ سلسلة نصية أو مخزنًا مؤقتًا في الذاكرة (buffer). يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية. إن كان الوسيط options‎ سلسلة نصية، فسيُحدِّد حينئذٍ الترميز. يجب أن يكون مقبض الملف FileHandle‎ مفتوحًا في وضع الإضافة (appending mode).

filehandle.chmod(mode)‎

أضيف في الإصدار: v10.0.0.

يعدِّل هذا التابع أذونات الملف. يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

filehandle.chown(uid, gid)‎

أضيف في الإصدار: v10.0.0.

يغيِّر هذا التابع المستخدم المالك للملف ثم سيُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

‎filehandle.close()‎

أضيف في الإصدار: v10.0.0.

  • القيم المعادة:‏‏ <Promise> يعاد كائن من النوع Promise‎ الذي سيُقبَل متى ما أُغلِق واصف الملف الضمني، أو سيُرفَض إن حصل أي خطأ أثناء إغلاق الملف.

يوضح المثال التالي كيفية استعمال هذا التابع لإغلاق ملف:

const fsPromises = require('fs').promises;
async function openAndClose() {
  let filehandle;
  try {
    filehandle = await fsPromises.open('thefile.txt', 'r');
  } finally {
    if (filehandle !== undefined)
      await filehandle.close();
  }
}

filehandle.datasync()‎

أضيف في الإصدار: v10.0.0.

ينفِّذ هذا التابع استدعاء النظام fdatasync(2)‎ بشكل غير متزامن. يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

filehandle.fd‎

أضيفت في الإصدار: v10.0.0.

  • ‏‏ <Promise> عدد يمثل واصف الملف المُدار من قِبَل الكائن FileHandle‎.

filehandle.read(buffer, offset, length, position)‎

أضيف في الإصدار: v10.0.0.

  • buffer:‏ <Buffer>‏ | <Uint8Array> يمثِّل ذاكرة التخزين المؤقتة التي ستُكتَب فيها البيانات المقروءة من الملف.
  • offset:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية كتابة البيانات في ذاكرة التخزين المؤقتة buffer‎ (أي مقدار الإزاحة من بدياتها).
  • length:‏ <integer> عددٌ صحيحٌ يحدِّد عدد البايتات المراد قراءتها من الملف.
  • position:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية قراءة البيانات من الملف. إن كانت قيمة هذا الوسيط null‎، فستُقرَأ البيانات بدءًا من موضع المؤشر الحالي في الملف ثم سيُحدَّث موضع مؤشِّر الملف بعد انتهاء عملية القراءة. إن كانت قيمة هذا الوسيط عددًا صحيحًا، فسيبقى موضع مؤشِّر الملف دون تغيير.
  • القيم المعادة: <Promise>

يقرأ هذا التابع البيانات من الملف. عَقِب نجاح عملية القراءة، يُقبَل الكائن Promise‎ مع كائن يحوي الخاصية bytesRead‎ التي تحدد عدد البايتات التي قُرأَت، والخاصية buffer‎ التي تشير إلى محتوى الوسيط buffer‎ الذي يحوي البيانات التي قُرأَت من الملف.

filehandle.readFile(options)‎

أضيف في الإصدار: v10.0.0.

يقرأ هذا التابع كامل محتوى ملفٍ بشكل غير متزامن. يُقبَل الكائن Promise‎ مع محتوى الملف. إن لم يُحدَّد أي ترميز (باستعمال الخيار options.encoding‎)، فستُعاد البيانات ضمن كائن من النوع buffer‎. أمَّا إن أعطي الترميز، فستُعاد البيانات ضمن سلسلة نصية. إن كان الوسيط options‎ سلسلة نصية، فسيُحدِّد حينئذٍ الترميز. عندما يكون المسار path‎ مجلدًا، سيختلف سلوك التابع fsPromises.readFile()‎ اعتمادًا على المنصة المستعملة؛ في أنظمة التشغيل macOS، ولينكس، وويندوز، سيؤدي ذلك إلى رفض الكائن Promise‎ مع خطأ. أمَّا في FreeBSD، فسيعاد تمثيلٌ بمحتوى المجلد. يجب على مقبض الملف FileHandle‎ المحدَّد أن يدعم عملية القراءة.

filehandle.stat([options])‎

سجل التغييرات
الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v10.0.0 أضيف هذا التابع.
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • القيم المعادة:‏ <Promise>

يجلب هذا التابع معلومات حول الملف (أي يعيد الكائن fs.Stats‎ للملف).

filehandle.sync()‎

أضيف في الإصدار: v10.0.0.

ينفِّذ هذا التابع دالة النظام fsync(2)‎ بشكل غير متزامن. يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

filehandle.truncate(len)‎

أضيف في الإصدار: v10.0.0.

  • len:‏ <integer> القيمة الافتراضية هي: 0‎.
  • القيم المعادة:‏ <Promise>

يقطع هذا التابع الملف إلى الحجم len‎ ثم يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية. إن كان حجم الملف أكبر من الحجم len‎ المعطى بالبايت، فستُعاد البايتات len‎ الأولى فقط من الملف. على سبيل المثال، يعيد البرنامج التالي البايتات الأربعة الأولى فقط من الملف:

const fs = require('fs');
const fsPromises = fs.promises;

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Node.js سيُطبَع

async function doTruncate() {
  let filehandle = null;
  try {
    filehandle = await fsPromises.open('temp.txt', 'r+');
    await filehandle.truncate(4);
  } finally {
    if (filehandle) {
      // إغلاق الملف إن كان مفتوحًا.
      await filehandle.close();
    }
  }
  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Node :سيُطبَع
}

doTruncate().catch(console.error);

إن كان حجم الملف أقل من الحجم len‎ المراد اقتطاعه، فسيُمدَّد حجم الملف إلى الحجم len‎ بالبايت وستُملَأ البايتات المضافة ببايتات عدمية (أي بالقيمة '\0'‎):

const fs = require('fs');
const fsPromises = fs.promises;

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Node.js :سيُطبَع

async function doTruncate() {
  let filehandle = null;
  try {
    filehandle = await fsPromises.open('temp.txt', 'r+');
    await filehandle.truncate(10);
  } finally {
    if (filehandle) {
      // إغلاق الملف إن كان مفتوحًا
      await filehandle.close();
    }
  }
  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Node.js\0\0\0 :سيُطبَع
}

doTruncate().catch(console.error);

البايتات الأخيرة المضافة هي بايتات عدمية ('\0'‎) تستعمل لتعويض البايتات الإضافية الناتجة عن عملية الإفراط في الاقتطاع (over-truncation).

filehandle.utimes(atime, mtime)‎

أضيف في الإصدار: v10.0.0.

يغيِّر هذا التابع بصمات وقت نظام الملفات للكائن المشار إليه بالمقبض FileHandle‎ ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية. لا يعمل هذا التابع على إصدارات AIX التي قبل 7.1، إذ سيقبل الكائن Promise‎ مع خطأ رمزه UV_ENOSYS‎.

filehandle.write(buffer, offset, length, position)‎

أضيف في الإصدار: v10.0.0.

  • buffer:‏ <Buffer>‏ | <TypedArray>‏ | <DataView> يمثِّل جزءًا من ذاكرة التخزين المؤقتة التي ستُقرَأ منها البيانات المراد كتابتها في الملف.
  • offset:‏ <integer> عددٌ صحيحٌ يحدِّد جزء البيانات من ذاكرة التخزين المؤقتة buffer‎ المراد كتابته.
  • length:‏ <integer> عددٌ صحيحٌ يحدِّد عدد البايتات المراد كتابتها في الملف.
  • position:‏ <integer> عددٌ صحيحٌ يحدِّد موضع بداية كتابة البيانات في الملف بدءًا من بداية الملف (أي يحدِّد مقدار الإنزياح من بداية الملف). إن كان typeof position !== 'number'‎، فستُكتَب البيانات بدءًا من موضع المؤشر الحالي في الملف. اطلع على الدالة pwrite(2)‎.
  • القيم المعادة:‏ <Promise>

يكتب هذا التابع البيانات المحددة في الذاكرة buffer‎ في الملف. عَقِب نجاح عملية الكتابة، يُقبَل الكائن Promise‎ مع كائن يحوي الخاصية bytesWritten التي تحدد عدد البايتات التي كُتبَت، والخاصية buffer‎ التي تشير إلى محتوى الوسيط buffer‎ الذي يحوي البيانات التي كُتبَت في الملف. إنه من غير الآمن استدعاء التابع filehandle.write()‎ عدة مرات مع نفس الملف دون انتظار قبول الكائن Promise‎ (أو رفضه). في مثل هذه الحالة، يُنصَح باستعمال التابع fs.createWriteStream()‎. في لينكس، لن يحرك مؤشر الكتابة إلى موضع معين عند فتح الملف في وضع الإضافة (append mode). ستتجاهل النواة الوسيط position‎ وستضيف البيانات إلى نهاية الملف دومًا.

filehandle.writeFile(data, options)‎

أضيف في الإصدار: v10.0.0.

يكتب هذا التابع البيانات الموجودة في الوسيط data في الملف بشكل غير متزامن، إذ يستبدل الملف إن كان موجودًا مسبقًا. يمكن أن يكون الوسيط data‎ سلسلةً نصيةً أو مخزنًا مؤقتًا في الذاكرة (buffer). يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية. سيُتجاهَل الخيار encoding‎ إن كان الوسيط data‎ مخزنًا مؤقتًا (buffer). إن كان الوسيط options‎ سلسلةً نصيةً، فسيُحدِّد حينئذٍ الترميز. يجب على مقبض الملف FileHandle‎ المعطى أن يدعم عملية الكتابة على الملف. إنه من غير الآمن استدعاء التابع filehandle.writeFile()‎ عدة مرات مع نفس الملف دون قبول الكائن Promise‎ (أو رفضه).

fsPromises.access(path[, mode])‎

أضيف في الإصدار: v10.0.0.

يفحص هذا التابع أذونات المستخدم للملف أو المجلد المحدَّد في المسار path‎. الوسيط mode‎ الاختياري هو عددٌ صحيحٌ يحدِّد عمليات التحقق من قابلية الوصول المراد تنفيذها. اطلع على القسم «ثوابت الوصول للملف» لمعرفة القيمة المتاحة للوسيط mode‎. يمكن إنشاء قناع يتألف من ثابتين أو أكثر عبر عملية الدمج الثنائية (bitwise) باستعمال المعامل OR (مثل fs.constants.W_OK | fs.constants.R_OK‎). إن نجحت عملية التحقق من قابلية الوصول، فسيُقبَل الكائن Promise‎ دون أية قيمة. وإن فشلت عملية التحقق من أيِّ قابليةٍ للوصول، فسيُرفَض الكائن Promise‎ مع الكائن Error‎. يتحقق المثال التالي إن كان الملف ‎/etc/passwd قابلًا للقراءة أو الكتابة من قِبَل العملية الحالية:

const fs = require('fs');
const fsPromises = fs.promises;

fsPromises.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK)
  .then(() => console.log('can access'))
  .catch(() => console.error('cannot access'));

لا يُنصَح باستدعاء fsPromises.access()‎ للتحقُّق من قابلة الوصول للملف قبل استدعاء fsPromises.open()‎، إذ يؤدي فعل ذلك إلى خلق «حالة تسابق» (race condition) لأنَّه ربما قد تُغيِّر عمليات أخرى حالة الملف بين الاستدعائين. بدلًا من ذلك، يجب على شيفرة المستخدم أن تفتح وتقرأ وتكتب في الملف مباشرةً وأن تعالج أي خطأ يُطلَق إن لم يكن الملف قابلًا للوصول.

fsPromises.appendFile(path, data[, options])‎

أضيف في الإصدار: v10.0.0.

يضيف هذا التابع بياناتٍ إلى ملف بشكل غير متزامن، أو ينشئ ملفًا ويضع البيانات فيه إن لم يكن هذا الملف موجودًا. يمكن أن تكون البيانات data‎ المراد كتابتها سلسلةً نصيةً أو كائنًا من النوع Buffer‎. يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية. إن كان الوسيط options‎ سلسلةً نصيةً، فسيُحدِّد حينئذٍ الترميز. يمكن أن يُعطَى المسار path‎ كمقبض FileHandle‎ لملفٍ فُتِح لإضافة البيانات فيه (باستعمال fsPromises.open()‎). لن يُغلَق واصف الملف بشكل تلقائي.

fsPromises.chmod(path, mode)‎

أضيف في الإصدار: v10.0.0.

يغيِّر هذا التابع بشكل غير متزامن أذونات ملفٍ ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

fsPromises.chown(path, uid, gid)‎

أضيف في الإصدار: v10.0.0.

يغيِّر هذا التابع بشكل غير متزامن المالك والمجموعة المالكة لملف ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

fsPromises.copyFile(src, dest[, flags])‎

أضيف في الإصدار: v10.0.0.

  • src:‏ <string>‏ | <Buffer>‏ | <URL> اسم الملف المراد نسخه.
  • dest:‏ <string>‏ | <Buffer>‏ | <URL> اسم الملف الوجهة الذي سيُنسَخ في الملف المحدَّد في المعامل src.
  • flags:‏ <number> مُعدِّلات (modifiers) عملية النسخ. القيمة الافتراضية هي: 0.
  • القيم المعادة:‏ <Promise>

ينسخ هذا التابع ملفًا من src‎ إلى dest‎ بشكل غير متزامن. يُستبدَل ملف الوجهة المحدد بالوسيط dest‎ إن كان موجودًا مسبقًا بشكل افتراضي. يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية. لا تعطِ Node.js أية ضمانات متعلقة بتجزئة عملية النسخ. إن حصل أي خطأ بعد فتح الملف الوجهة للكتابة، ستحاول Node.js إزالته. الوسيط flags‎ اختياري وهو عددٌ صحيحٌ يحدِّد سلوك عملية النسخ. يمكن إنشاء قناع يتألف من ثابتين أو أكثر عبر عملية الدمج الثنائية (bitwise) باستعمال المعامل OR (مثل fs.constants.COPYFILE_FICLONE | fs.constants.COPYFILE_EXCL). الثوابت المدعومة هي:

  • fs.constants.COPYFILE_EXCL‎: ستفشل عملية النسخ إن كان الملف dest‎ موجودًا من قبل.

fs.constants.COPYFILE_FICLONE‎: ستحاول عملية النسخ إنشاء وصلة مرجعية (reflink) بنمط «النسخ عند الكتابة» (copy-on-write). إن لم تدعم المنصة نمط «النسخ عند الكتابة»، فستُستخدَم آلية النسخ التراجعي (fallback copy).

  • fs.constants.COPYFILE_FICLONE‎: ستحاول عملية النسخ إنشاء وصلة مرجعية (reflink) بنمط «النسخ عند الكتابة» (copy-on-write). إن لم تدعم المنصة نمط «النسخ عند الكتابة»، فستفشل عملية النسخ.
const fsPromises = require('fs').promises;

// أو سيُستبدَل بشكل افتراضي destination.txt سيُنشَأ الملف
fsPromises.copyFile('source.txt', 'destination.txt')
  .then(() => console.log('source.txt was copied to destination.txt'))
  .catch(() => console.log('The file could not be copied'));

إن كان الوسيط الأخير عددًا، فهو يحدِّد الوسيط flags‎:

const fs = require('fs');
const fsPromises = fs.promises;
const { COPYFILE_EXCL } = fs.constants;

// موجودًا من قبل destination.txt ستفشل العملية إن كان الملف ،COPYFILE_EXCL باستخدام الثابت
fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL)
  .then(() => console.log('source.txt was copied to destination.txt'))
  .catch(() => console.log('The file could not be copied'));

fsPromises.lchmod(path, mode)‎

أضيف في الإصدار: v10.0.0.

يغيِّر هذا التابع أذونات وصلةٍ رمزيةٍ بشكل غير متزامن ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية. هذا التابع متاحٌ في أنظمة macOS فقط.

fsPromises.lchown(path, uid, gid)‎

سجل التغييرات

الإصدار التغييرات v10.6.0 لم تعد هذه الواجهة البرمجية مهملةً بعد الآن. v10.0.0 أضيف هذا التابع.

يغيِّر هذا التابع بشكل غير متزامن المالك والمجموعة المالكة لوصلةٍ رمزيةٍ ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

fsPromises.link(existingPath, newPath)‎

أضيف في الإصدار: v10.0.0.

ينشئ هذا التابع وصلةً جديدةً (وصلةً صلبةً) للملف الحالي عبر استدعاء link(2)‎ بشكل غير متزامن. يُقبَل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

fsPromises.lstat(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v10.0.0 أضيف هذا التابع.
  • path:‏‏ <string>‏ | <Buffer>‏ | <URL>
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • القيم المعادة:‏ <Promise>

يجلب هذا التابع معلومات حول الوصلة الرمزية ذات المسار path‎ عبر استدعاء دالة النظام lstat(2)‎ بشكل غير متزامن. يُقبَل الكائن Promise‎ مع الكائن fs.Stats‎ للوصلة الرمزية المعطاة عند نجاح العملية.

fsPromises.mkdir(path[, mode])‎

أضيف في الإصدار: v10.0.0.

ينشئ هذا التابع مجلدًا جديدًا بشكل غير متزامن ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

fsPromises.mkdtemp(prefix[, options])‎

أضيف في الإصدار: v10.0.0.

ينشئ هذا التابع مجلدًا فريدًا مؤقتًا بشكل غير متزامن ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية. يولِّد هذا التابع ستة محارف عشوائية لتضاف إلى نهاية البادئة prefix‎ المعطاة لإنشاء مجلدٍ فريدٍ مؤقتٍ. يمكن أن يكون الوسيط options‎ سلسلةً نصيةً تحدِّد الترميز، أو كائنًا مع الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله.

fsPromises.mkdtemp(path.join(os.tmpdir(), 'foo-'))
  .catch(console.error);

سيضيف التابع fsPromises.mkdtemp()‎ المحارف الستة العشوائية المختارة مباشرةً إلى السلسلة prefix‎ النصية. على سبيل المثال، إن كان لدينا المجلد ‎/tmp‎ وأردنا إنشاء مجلد مؤقت داخله، فيجب أن تنتهي البادئة prefix‎ بالفاصلة الزائدة المستخدمة عادةً في فصل المسار في المنصة المستعملة آنذاك (require('path').sep‎).

fsPromises.open(path, flags[, mode])‎

أضيف في الإصدار: v10.0.0.

يفتح هذا التابع ملفًا بشكل غير متزامن ثم يعيد الكائن Promise‎ مع المقبض FileHandle‎ لذاك الملف عند نجاح العملية. اطلع على توثيق الدالة open(2)‎ لتفاصيل أوسع. يضبط الوسيط mode‎ نمط الملف (الأذونات والبتات اللاصقة [sticky bits]) في حال لم يكن الملف موجودًا وأنشئ آنذاك. تأخذ دالة رد النداء وسيطين هما: err‎ و fd‎. تعدُّ بعض المحارف (مثل < > : " / \ | ? *‎) محجوزةً في ويندوز كما أشير إلى ذلك التوثيق «تسمية الملفات، والمسارات، ومجالات الأسماء». في نظام الملفات NTFS، إن احتوى اسم الملف نقطتين رأسيتين، فستفتح Node.js مجرًى في نظام الملفات كما موضح في هذه الصفحة.

fsPromises.readdir(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v10.10.0 أضيف الخيار withFileTypes‎.
v10.0.0 أضيف هذا التابع.

يقرأ هذا التابع محتوى المجلد المعطى بشكل غير متزامن ثم يقبل الكائن Promise‎ مع مصفوفة تحوي أسماء الملفات في المجلد باستثناء المجلد '.'‎ والمجلد '..'‎. يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله لأسماء الملفات الممرَّرة إلى دالة رد النداء. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فستُمرَّر أسماء الملفات المعادة ككائنات من النوع Buffer‎. إن ضُبِط الخيار options.withFileTypes‎ إلى القيمة true‎، فستحوي المصفوفة files‎ الكائنات fs.Dirent‎.

fsPromises.readFile(path[, options])‎

أضيف في الإصدار: v10.0.0.

يقرأ هذا التابع كامل محتوى الملف ذي المسار path‎ بشكل غير متزامن. يُقبَل الكائن Promise‎ مع محتوى الملف. إن لم يُحدَّد أي ترميز (باستعمال options.encoding‎)، فسيكون نوع البيانات المعادة هو كائنٌ من النوع Buffer‎. أمَّا إن حُدِّد الترميز، فستوضع البيانات المعادة في سلسلة نصية. إن كان الوسيط options‎ سلسلة نصية، فسيُحدِّد حينئذٍ الترميز. عندما يكون المسار path‎ مجلدًا، سيختلف سلوك التابع fsPromises.readFile()‎ اعتمادًا على المنصة المستعملة؛ في أنظمة التشغيل macOS، ولينكس، وويندوز، سيؤدي ذلك إلى رفض الكائن Promise‎ مع خطأ. أمَّا في FreeBSD، فسيعاد تمثيلٌ بمحتوى المجلد. يجب على مقبض الملف FileHandle‎ المعطى أن يدعم عملية القراءة.

fsPromises.readlink(path[, options])‎

أضيف في الإصدار: v10.0.0.

يقرأ هذا التابع محتوى الوصلة الرمزية ذات المسار path‎ عبر استدعاء الدالة readlink(2)‎ بشكل غير متزامن. يُقبَل الكائن Promise‎ مع محتوى الوصلة linkString‎ عند نجاح العملية. يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله مع مسار الوصلة المعاد. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فسيُمرَّر مسار الوصلة المعاد ككائن من النوع Buffer‎.

fsPromises.realpath(path[, options])‎

أضيف في الإصدار: v10.0.0.

يحدِّد هذا التابع الموضع الحقيقي للمسار path‎ باستعمال نفس الدلالات التي يستعملها التابع fs.realpath.native()‎ ثم يقبل الكائن Promise‎ المسار المستبين. المسارات المدعومة هي المسارات التي يمكن تحويلها إلى سلاسل نصية مرمزة بالترميز UTF8 فقط. يمكن أن يكون الوسيط options‎ الاختياري سلسلة نصية تحدِّد الترميز المراد استعماله، أو كائنًا يملك الخاصية encoding‎ التي تحدِّد ترميز المحارف المراد استعماله مع المسار. إن ضُبطَت الخاصية encoding‎ إلى القيمة 'buffer'، فسيُمرَّر المسار المعاد ككائن من النوع Buffer‎. في لينكس، عندما تُربَط Node.js مع المكتبة musl libc، يجب أن يوصل (mount) نظام الملفات procfs في ‎/proc‎ لكي يعمل هذا التابع بشكل صحيح. أما المكتبة glibc، فلا تشترط ذلك.

fsPromises.rename(oldPath, newPath)‎

أضيف في الإصدار: v10.0.0.

يغيِّر هذا التابع اسم الملف oldPath‎ إلى newPath‎ المعطى بشكل غير متزامن ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية.

fsPromises.rmdir(path)‎

أضيف في الإصدار: v10.0.0.

يحذف هذا التابع المجلد ذا المسار path‎ ثم يقبل الكائن Promise‎ دون أية وسائط عند نجاح العملية. يؤدي استعمال التابع fsPromises.rmdir()‎ مع ملف (وليس مجلد) إلى رفض الكائن Promise‎ مع الخطأ ENOENT‎ في ويندوز والخطأ ENOTDIR‎ في أنظمة POSIX.

fsPromises.stat(path[, options])‎

سجل التغييرات
الإصدار التغييرات
v10.5.0 يقبل التابع كائن options‎ إضافي يحدِّد إذا كان يجب أن تكون القيم العددية المعادة من النوع bigint.
v10.0.0 أضيف هذا التابع.
  • path:‏ <string>‏ | <Buffer>‏ | <URL>
  • options:‏ <Object>
    • bigint:‏ <boolean> يحدِّد إذا كان يجب أن تكون القيم العددية في الكائن fs.Stats‎ المعاد من النوع bigint. القيمة الافتراضية هي: false‎.
  • القيم المعادة:‏ <Promise>

يجلب هذا التابع معلومات حول الملف ذي المسار path‎ بشكل غير متزامن ثم يقبل الكائن Promise‎ مع الكائن fs.Stats‎ لذاك الملف.

fsPromises.symlink(target, path[, type])‎

أضيف في الإصدار: v10.0.0.

ينشئ هذا التابع وصلة رمزيَّةً للملف المحدد بالمسار target‎ بشكل غير متزامن ثم يقبل الكائن Promise‎ دون أي وسائط عند نجاح العملية. يمكن ضبط الوسيط type‎ إلى القيمة 'dir'، أو 'file'، أو 'junction' وهو متاح في ويندوز فقط (يُتجاهل في المنصات الأخرى). تتطلب نقاط الوصل (junction points) في ويندوز أن يكون المسار الهدف مطلقًا. عند استعمال 'junction'، سيحول الوسيط target‎ تلقائيًّا إلى مسار مطلق.

fsPromises.truncate(path[, len])‎

أضيف في الإصدار: v10.0.0.

يقطع هذا التابع الملف ذا المسار path إلى الحجم len‎ ثم يقبل الكائن Promise‎ دون أي وسائط عند نجاح العملية. يجب أن يكون المسار path‎ سلسلة نصية أو كائنًا من النوع Buffer‎.

fsPromises.unlink(path)‎

أضيف في الإصدار: v10.0.0.

يزيل هذا التابع ملفًا أو وصلةً رمزيةً عبر تنفيذ الدالة unlink(2)‎ بشكل غير متزامن ثم يقبل الكائن Promise‎ دون أي وسائط عند نجاح العملية.

fsPromises.utimes(path, atime, mtime)‎

أضيف في الإصدار: v10.0.0.

يغيِّر هذا التابع بصمات وقت نظام الملفات للكائن المشار إليه بالمسار path‎ المعطى بشكل غير متزامن ثم يقبل الكائن Promise‎ دون أي وسائط عند نجاح العملية. يخضع الوسيطان atime‎ و mtime‎ إلى القاعدتين التاليتين:

  • يمكن أن تكون القيم إما أعدادًا تمثل الوقت في توقيت يونكس (Unix epoch time)، أو تواريخ، أو سلاسل نصية عددية مثل '123456789.0'‎.
  • إن لم يكن بالإمكان تحويل القيمة إلى عددٍ، أو كانت NaN‎ أو Infinity‎ أو Infinity‎-، فسيُرمَى خطأٌ.

fsPromises.writeFile(file, data[, options])‎

أضيف في الإصدار: v10.0.0.

يكتب هذا التابع البيانات الموجودة في الوسيط data في الملف file المعطى بشكل غير متزامن، إذ يستبدل الملف إن كان موجودًا مسبقًا. يمكن أن يكون الوسيط data‎ سلسلةً نصيةً أو مخزنًا مؤقتًا في الذاكرة (buffer). يُقبَل الكائن Promise‎ دون أي وسائط عند نجاح العملية. سيُتجاهَل الخيار encoding‎ إن كان الوسيط data‎ مخزنًا مؤقتًا. إن كان الوسيط options‎ سلسلةً نصيةً، فسيُحدِّد حينئذٍ الترميز. يجب على مقبض الملف FileHandle‎ المعطى أن يدعم عملية الكتابة على الملف. إنه من غير الآمن استدعاء التابع fsPromises.writeFile()‎ عدة مرات مع نفس الملف دون انتظار قبول الكائن Promise‎ (أو رفضه).

الثوابت المستعملة في الوحدة fs‎

يمكن تصدير الثوابت الموجودة في هذا القسم عبر استدعاء fs.constants‎. انتبه إلى أنه لن تكون جميع الثوابت متاحةً على جميع أنظمة التشغيل.

ثوابت الوصول للملف

تستخدم الثوابت التالية مع التابع fs.access()‎:

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

هذا الثابت هو القيمة الافتراضية المستعملة عند عدم تحديد أي ثابت.

R_OK رايةٌ تشير إلى أنَّ الملف قابل للقراءة من قبل العملية المستدعاة.
W_OK رايةٌ تشير إلى أنَّ الملف قابل للكتابة من قبل العملية المستدعاة.
X_OK رايةٌ تشير إلى أنَّ الملف قابل للتنفيذ من قبل العملية المستدعاة. ليس لهذه الراية أي تأثير في ويندوز (ستسلك نفس سلوك الراية fs.constants.F_OK).

ثوابت نسخ الملف

تستخدم الثوابت التالية مع التابع fs.copyFile()‎:

الثابت الوصف
COPYFILE_EXCL ستفشل عملية النسخ مع خطأ إن كان الملف موجودًا من قبل في المسار الوجهة المراد إنشاء نسخة فيه.
COPYFILE_FICLONE إن وُجِد، فستحاول عملية النسخ إنشاء وصلة مرجعية (reflink) بنمط «النسخ عند الكتابة» (copy-on-write). إن لم تدعم المنصة نمط «النسخ عند الكتابة»، فستُستخدَم آلية النسخ التراجعي (fallback copy).
COPYFILE_FICLONE_FORCE إن وُجِد، فستحاول عملية النسخ إنشاء وصلة مرجعية (reflink) بنمط «النسخ عند الكتابة» (copy-on-write). إن لم تدعم المنصة نمط «النسخ عند الكتابة»، فستفشل عملية النسخ مع خطأ.

ثوابت فتح الملف

تستخدم الثوابت التالية مع التابع fs.open()‎:

الثابت الوصف
O_RDONLY رايةٌ تشير إلى فتح الملف في نمط القراءة فقط.
O_WRONLY راية تشير إلى فتح الملف في نمط الكتابة فقط.
O_RDWR رايةٌ تشير إلى فتح الملف في نمط القراءة والكتابة فقط.
O_CREAT رايةٌ تشير إلى إنشاء الملف إن لم يكن موجودًا من قبل.
O_EXCL رايةٌ تشير إلى أن عملية فتح الملف يجب أن تفشل إن استعملت الراية وكان الملف موجودًا من قبل.
O_NOCTTY رايةٌ تشير إلى أنه إذا كان المسار يعرِّف جهازًا طرفيًّا (terminal device)، فيجب ألا يؤدي فتح المسار إلى جعل تلك الطرفية هي الطرفية المتحكمة بالعملية (إن لم تملك العملية واحدةً مسبقًا).
O_TRUNC رايةٌ تشير إلى أنه إذا كان الملف موجودًا وهو ملف طبيعي وفتح الملف بنجاح للكتابة فيه، فيجب أن يُقلَّص حجمه إلى الصفر.
O_APPEND رايةٌ تشير إلى أن البيانات ستضاف في نهاية الملف دومًا.
O_DIRECTORY رايةٌ تشير إلى أن العملية يجب أن تفشل إن كان المسار المعطى لا يمثِّل مجلدًا.
O_NOATIME رايةٌ تشير إلى أنه لن ينتج عن عملية الوصول إلى نظام الملفات من أجل القراءة تحديثَ معلومات الوقت atime‎ المرتبط بالملف.

هذه الراية متاحةٌ للاستعمال في أنظمة لينكس فقط.

O_NOFOLLOW رايةٌ تشير إلى أنه يجب ان تفشل العملية إن كان المسار يمثِّل وصلةً رمزيةً.
O_SYNC رايةٌ تشير إلى أنه يُفتَح الملف من أجل الدخل والخرج المتزامن (synchronized I/O) مع انتظار عمليات الكتابة للحفاظ على سلامة الملف.
O_DSYNC رايةٌ تشير إلى أنه يُفتَح الملف من أجل الدخل والخرج المتزامن (synchronized I/O) مع انتظار عمليات الكتابة للحفاظ على سلامة البيانات.
O_SYMLINK رايةٌ تشير إلى فتح الوصلة الرمزية نفسها بدلًا من فتح المورد الذي تشير إليه.
O_DIRECT عند استعمال هذه الراية، ستُجرَى محاولةٌ لتقليل تأثيرات التخزين المؤقت (caching) لدخل وخرج الملف (file I/O).
O_NONBLOCK رايةٌ تشير إلى فتح الملف في وضع عدم الحجز (nonblocking mode) إن أمكن ذلك.

ثوابت نوع الملف

تستعمل الثوابت التالية الخاصية mode‎ للكائن fs.Stats‎ لتحديد نوع الملف.

الثابت الوصف
S_IFMT قناع بتِّي (bit make) يُستعمَل لاستخراج رمز نوع الملف.
S_IFREG ثابت نوع الملف من أجل ملف طبيعي (regular file).
S_IFDIR ثابت نوع الملف من أجل مجلد.
S_IFCHR ثابت نوع الملف من أجل ملف جهاز محرفي  التوجه (character-oriented device file).
S_IFBLK ثابت نوع الملف من أجل ملف جهاز كتلي التوجه (block-oriented device file).
S_IFIFO ثابت نوع الملف من أجل الأنبوب FIFO (اختصار للعبارة first-in-first-out أي «من دخل أولًا يخرج أولًا»، كما يدعى أحيانًا «أنبوبًا مسمًى»)
S_IFLNK ثابت نوع ملف من أجل وصلة رمزية.
S_IFSOCK ثابت نوع ملف من أجل مقبس.

ثوابت نمط الملف

تستعمل الثوابت التالية الخاصية mode‎ للكائن fs.Stats‎ لتحديد أذونات الوصول للملف.

الثابت الوصف
S_IRWXU نمط ملف يشير إلى قابلية القراءة والكتابة والتنفيذ من قبل المالك.
S_IRUSR نمط ملف يشير إلى قابلة القراءة من قبل المالك.
S_IWUSR نمط ملف يشير إلى قابلية الكتابة من قبل المالك.
S_IXUSR نمط ملف يشير إلى قابلة التنفيذ من قبل المالك.
S_IRWXG نمط ملف يشير إلى قابلية القراءة والكتابة والتنفيذ من قبل المجموعة المالكة.
S_IRGRP نمط ملف يشير إلى قابلة القراءة من قبل المجموعة المالكة.
S_IWGRP نمط ملف يشير إلى قابلية الكتابة من قبل المجموعة المالكة.
S_IXGRP نمط ملف يشير إلى قابلة التنفيذ من قبل المجموعة المالكة.
S_IRWXO نمط ملف يشير إلى قابلية القراءة والكتابة والتنفيذ من قبل الآخرين.
S_IROTH نمط ملف يشير إلى قابلة القراءة من قبل الآخرين.
S_IWOTH نمط ملف يشير إلى قابلية الكتابة من قبل الآخرين.
S_IXOTH نمط ملف يشير إلى قابلة التنفيذ من قبل الآخرين.

رايات نظام الملفات

الرايات التالية متاحة متى ما قبل الخيار flag‎ أن يأخذ سلسلة نصية:

  • 'a': فتح الملف من أجل الإضافة (appending). سيُنشأ الملف إن لم يكون موجودًا.
  • 'ax': شبيهةٌ بالراية 'a' باستثناء أن العملية ستفشل إن كان الملف موجودًا.
  • 'a+‎': فتح الملف للقراءة والإضافة. سيُنشَا الملف إن لم يكن موجودًا.
  • 'ax+‎': شبيهةٌ بالراية 'a+‎' باستثناء أن العملية ستفشل إن كان الملف موجودًا.
  • '‎as': فتح الملف للإضافة في وضع التزامن (synchronous mode). سيُنشَأ الملف إن لم يكن موجودًا.
  • 'as+‎': فتح الملف للقراءة والإضافة في وضع التزامن. سيُنشَأ الملف إن لم يكن موجودًا.
  • 'r': فتح الملف للقراءة. سيُطلَق استثناء إن لم يكن الملف موجودًا.
  • 'r+‎': فتح الملف للقراءة والكتابة. سيُطلَق استثناء إن لم يكن الملف موجودًا.
  • 'rs+‎': فتح الملف للقراءة والكتابة في وضع التزامن. سيُوجَّه نظام التشغيل لتجاوز التخزين المؤقت في نظام الملفات.

الفائدة الأساسية في استعمال هذه الراية هي في فتح الملفات نظام الملفات NFS الموصول (mount)، إذ تسمح بتخطي ذاكرة التخزين المؤقتة المحلية (local cache) التي يحتمل أن تكون قديمة. إن لهذه الراية تأثير حقيقي كبير جدًا على أداء المدخلات والمخرجات (I/O)/ لذا لا يوصى باستعمال هذه الراية إلا عند الحاجة الماسَّة إليها. إن هذا لن يحول التابع fs.open()‎ أو fsPromises.open()‎ إلى الاستدعاء الكتلي المتزامن (synchronous blocking call). إن كان من المستحسن استعمال عملية متزامنة، فيجب استعمال شيء شبيه بالتابع fs.openSync()‎.

  • 'w': فتح الملف للكتابة. سيُنشَأ الملف إن لم يكن موجودًا أو سيُقتطَع إن كان موجودًا.
  • 'wx': شبيهةٌ بالراية 'w' باستثناء أن العملية ستفشل إن ان الملف موجودًا.
  • 'w+‎': فتح الملف للقراءة والكتابة. سيُنشَأ الملف إن لم يكن موجودًا أو سيُقتطَع إن كان موجودًا.
  • 'wx+‎': شبيهةٌ بالراية 'w+‎' باستثناء أن العملية ستفشل إن كان الملف موجودًا.

يمكن أن يكون الخيار flag‎ عددًا أيضًا كما هو مذكور في توثيق الدالة open(2)‎. الثوابت ذات الاستعمال الشائع متاحةٌ عبر استدعاء fs.constants‎. في ويندوز، تحول الرايات إلى ما يقابلها أينما أمكن ذلك مثل تحويل O_WRONLY‎ إلى FILE_GENERIC_WRITE‎ أو تحويل O_EXCL|O_CREAT‎ إلى CREATE_NEW‎ لتُقبَل عبر CreateFileW‎. تتأكد الراية 'x' (هي الراية O_EXCL‎ في open(2)‎) أن المسارات قد أُنشئَت حديثًا. في أنظمة POSIX، يعد مسارٌ موجودًا حتى إن كان وصلةً رمزيةً تشير إلى ملف غير موجود. الراية 'x' قد تعمل أو قد لا تعمل مع أنظمة ملفات الشبكة. في لينكس، لن يحرك مؤشر الكتابة إلى موضع معين عند فتح الملف في وضع الإضافة (append mode). ستتجاهل النواة الوسيط position‎ وستضيف البيانات إلى نهاية الملف دومًا. تعديل ملف بدلًا من استبداله قد يتطلَّب فتحه في الوضع 'r+‎' بدلًا من الوضع 'w' الافتراضي. يعتمد سلوك بعض الرايات على المنصة المستعملة آنذاك. بناءً على ذلك، سيعيد فتح مجلدٍ في نظام التشغيل maxOS أو لينكس مع الراية 'a+‎' خطأً (انظر المثال الآتي). في المقابل، سيعاد واصف ملف أو مقبص الملف FileHandle‎ في ويندوز و FreeBSD.

// macOS and Linux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: illegal operation on a directory, open <directory>]
});

// Windows and FreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
});

في ويندوز، ستفشل عملية فتح ملف موجود مخفي باستعمال الراية 'w' (سواءً عبر التابع fs.open()‎ أو التابع fs.writeFile()‎ أو التابع fsPromises.open()‎) مع الخطأ EPERM‎. يمكن فتح ملف موجود ولكنه مخفي من أجل الكتابة مع الراية 'r+‎'. يمكن استعمال التابع fs.ftruncate()‎ أو التابع filehandle.truncate()‎ لمسح جميع محتويات الملف.

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Node.js/fs&oldid=20893»