عرض مصدر Node.js/child process

<noinclude>{{DISPLAYTITLE:العمليات الأبناء في Node.js}}</noinclude>
الاستقرار: 2-مستقر

توفِّر الوحدة <code>child_process</code> القدرة على توليد (spawn) عمليات أبناء بطريقةٍ مشابهةٍ  -وليست مماثلة- للدالة <code>popen(3)‎</code>، إذ يمكن للدالة <code>child_process.spawn()‎</code> أن توفِّر هذه الإمكانيَّة في المقام الأول:<syntaxhighlight lang="javascript">
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.log(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

</syntaxhighlight>تُنشَأ أنابيبٌ (pipes) لمجرى الدخل القياسي (stdin) ومجرى الخرج القياسي (stdout) ومجرى الخطأ القياسي (stderr) بين العمليَّة الأب في Node.js والعمليَّة الابن المولدة. إنّ لهذه الأنابيب قدرةٌ محدودةٌ (متعلقة بالمنصة المستعملة). إن حصل فائض عند كتابة العمليَّة الابن على مجرى الخرج القياسي يتجاوز القدرة الحديَّة تلك دون إظهار المخرجات، فستُوقف العمليَّة الابن عمليَّة انتظار مخزن الأنابيب (pipe buffer) لقبول المزيد من البيانات. هذا السلوك مماثل لسلوك الأنابيب في الصدفة (shell). استعمل الخيار <code>{ stdio: 'ignore'‎ }</code> إن كنت لا تود استعمال المخرجات والاستفادة منها.

يولِّد التابع <code>child_process.spawn()‎</code> العمليات الأبناء بشكل غير متزامن ودون منع حلقة أحداث Node.js. أمَّا التابع <code>child_process.spawnSync()‎</code> فيملك وظيفة مشابهة إذ يولِّد العمليات الأبناء ولكن بشكل متزامن، إذ يمنع حلقة الأحداث (event loop) حتى تنتهي علمية التوليد أو يتم مقاطعتها.

توفِّر الوحدة <code>child_process</code> بدائل متزامنة وغير متزامنة للتابعين <code>child_process.spawn()‎</code> و <code>child_process.spawnSync()</code>‎. انتبه إلى أنَّ هذه البدائل تُنفَّذ فوق <code>child_process.spawn()‎</code> أو <code>child_process.spawnSync()‎</code>.
* التابع <code>child_process.exec()‎</code>: يولِّد صدفةً (shell) ثمَّ يُنفِّذ أمرًا داخل هذه الصدفة مع تمرير مجرى الخرج والدخل القياسيين إلى دالة رد نداء عند الاكتمال.
* التابع <code>child_process.execFile()</code>‎: مشابهٌ للتابع السابق باستثناء أنَّه يولِّد الأمر مباشرةً دون توليد صدفةٍ أولًا.
* التابع <code>child_process.fork()</code>‎: يولِّد عمليَّة Node.js جديدة ويستدعي وحدة محددَّة مع وجود قناة اتصال IPC مُنشَأة تسمح بإرسال الرسائل بين العمليَّة الأب والابن.
* التابع <code>child_process.execSync()</code>‎: نسخةٌ متزامنة من التابع <code>child_process.exec()‎</code> الذي يمنع حلقة أحداث Node.js.
* التابع <code>child_process.execFileSync()</code>‎: نسخةٌ متزامنة من التابع <code>child_process.execFile()‎</code> الذي سيمنع حلقة أحداث Node.js.
قد تكون التوابع المتزامنة المقابلة في أغلب حالات الاستخدام، مثل أتمتة سكربتات الصدفة، ملائمةٌ أكثر. على أي حال، إنَّ لاستعمال التوايع المتزامنة أثرٌ كبيرٌ في أغلب الأوقات على الأداء وذلك عائد إلى توقف حلقة الأحداث (event loop) عند اكتمال العمليَّات المولدة.

== إنشاء عملية غير متزامنة ==
تتبع الدوال <code>hild_process.spawn()</code>‎، و <code>child_process.fork()</code>‎، و <code>child_process.exec()‎</code>، و <code>child_process.execFile()‎</code> جميعها نمط البرمجة غير المتزامنة الاعتيادي لواجهات Node.js البرمجيَّة الأخرى.

يعيد كلٌّ من تلك التوابع نسخةً من <code>ChildProcess</code>. تُنفِّذ (implement) هذه الكائنات الواجهة البرمجيَّة EventEmitter متيحةً بذلك للعملية الأب بتسجيل الدوال المستمعة التي تستدعى عند وقوع أحداث معيَّنة خلال دورة حياة العمليَّة الابن.

أضف إلى ذلك أنَّ التابعين <code>child_process.exec()‎</code> و <code>child_process.execFile()‎</code> يسمحان بتحديد دالة رد نداء <code>callback</code> اختياريَّة تُستدعَى عند انتهاء العمليَّة الابن.

=== توليد الملفان ‎.bat و ‎.cmd في ويندوز ===
جوهر الاختلاف بين التابع <code>child_process.exec()‎</code> والتابع <code>child_process.execFile()‎</code> يمكن أن يتفاوت من منصة لأخرى. في الأنظمة الشبيهة بيونكس (مثل يونكس، ولينكس، وماك)، يكون التابع <code>child_process.execFile()‎</code> أكثر كفاءةً لأنَّه لا يولد صدفةً بشكل افتراضي. أمَّا في نظام التشغيل ويندوز، لا يكون الملفان ‎.bat و ‎.cmd قابلين للتنفيذ من تلقاء نفسيهما بدون وجود طرفيَّة، لذا لا يمكن تشغيلهما باستعمال <code>child_process.execFile()‎</code>. على أي حال، يمكن استدعاء هذين الملفين باستعمال التابع <code>child_process.spawn()‎</code> مع الخيار shell، أو التابع <code>child_process.exec()‎</code>، أو عبر توليد العمليَّة cmd.exe ثمََّّ تمرير الملف ‎.bat أو الملف ‎.cmd كوسيط (هذا بالضبط ما يفعله الخيار <code>shell</code> والتابع <code>child_process.exec()‎</code>). إن احتوى اسم السكربت، عند استعمال أي طريقة، على أيَّة مسافات فارغة، فجب حينئذٍ أن يكون ذلك الاسم بين علامتي اقتباس.<syntaxhighlight lang="javascript">
// ... في ويندوز فقط
const { spawn } = require('child_process');
const bat = spawn('cmd.exe', ['/c', 'my.bat']);

bat.stdout.on('data', (data) => {
  console.log(data.toString());
});

bat.stderr.on('data', (data) => {
  console.log(data.toString());
});

bat.on('exit', (code) => {
  console.log(`Child exited with code ${code}`);
});
</syntaxhighlight>

=== <code>child_process.exec(command[, options][, callback])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v8.8.0
|إضافة المعامل <code>windowsHide</code>.
|-
|v0.1.90
|إضافة هذا التابع.
|}
* <code>command</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تُمثِّل الأمر المراد تنفيذه مع وسائط مفصولة بفراغ.
* <code>options</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ من النوع <code>Object</code> يمكن أن يحتوي على الخيارات التالية:
** <code>cwd</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثِّل مجلد العمل الحالي للعملية الابن. القيمة الافتراضيَّة هي: <code>[[JavaScript/null|null]]</code>.
** <code>env</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ يتكون من الأزواج مفتاح/قيمة يمثِّل البيئة.
** <code>encoding</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثِّل الترميز المستعمل. القيمة الافتراضيَّة هي: <code>'utf8'</code>.
** <code>shell</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تحدِّد الصدفة المراد تنفيذ الأمر ضمنها (ارجع إلى القسم «متطلبات الصدفة» والقسم «صدفة ويندوز الافتراضيَّة» في الأسفل للمزيد من التفاصيل). القيمة الافتراضيَّة هي: <code>'‎/bin/sh'</code> في يونكس والأنظمة الشبيهة به، أو <code>process.env.ComSpec</code> في ويندوز.
** <code>timeout</code>: ‏[[JavaScript/Number|<number>]] الفترة الزمنيَّة القصوى بالميلي ثانية التي يُسمَح فيها للعمليَّة بالعمل. القيمة الافتراضيَّة هي: 0.
** <code>maxBuffer</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثِّل أكبر حجم مسموحٍ به للبيانات بالبايت في مجريي الخرج والخطأ القياسيين. في حال تجاوز هذه القيمة، ستُنهَى العمليَّة الابن مباشرةً. ارجع إلى القسم «الخيار maxBuffer والترميز الموحَّد». القيمة الافتراضيَّة هي: 200 * 1024.
** <code>killSignal</code>: [[JavaScript/String|‏<string>]] | [[JavaScript/Number|‏<integer>]] قيمة الإشارة المراد استعمالها عندما يتم قتل (kill) العمليَّة المُولَّدة. القيمة الافتراضيَّة هي: <code>'SIGTERM'</code>.
** <code>uid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المستخدم المالك للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setuid.2.html setuid(2)]‎).
** <code>gid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المجموعة المالكة للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setgid.2.html setgid(2)]‎).
** <code>windowsHide</code>: ‏[[JavaScript/Boolean|<boolean>]] قيمةٌ منطقيةٌ تتحكم بإظهار وإخفاء نافذة الطرفيَّة للعمليَّة الفرعية التي ستُنشأ دومًا بشكل اعتيادي في أنظمة ويندوز. القيمة الافتراضيَّة هي: <code>false</code>.
* <code>callback</code>: ‏[[JavaScript/Function|<Function>]] دالةٌ تستدعى مع المخرجات عند انتهاء العمليَّة.
** <code>error</code>: ‏[[JavaScript/Error|<Error>]]
** <code>stdout</code>: ‏[[JavaScript/String|<string>]] | ‏<Buffer>
** <code>stderr</code>: ‏[[JavaScript/String|<string>]] | ‏<Buffer>
* نوع القيم المعادة: <ChildProcess>
يولدِّ هذا التابع صدفةً ثمََّّ ينفِّذ الأمر <code>command</code> المُعطى ضمنها مع تخزين أية مخرجات ناتجة. يعالج الأمر <code>command</code> المعطى المُمرَّر إلى الدالة <code>exec</code> مباشرةً من طرف الصدفة، ويجب الانتباه إلى المحارف الخاصَّة والتعامل معها (تهريبها مثلًا) بشكل صحيح وفقًا للصدفة المستعملة آنذاك:<syntaxhighlight lang="javascript">
exec('"/path/to/test file/test.sh" arg1 arg2');
// استعملت علامة الاقتباس المزدوجة، لذا لن تُفسَّر المسافة الموجودة في المسار على
// أنها وسائط متعددة

exec('echo "The \\$HOME variable is $HOME"');
// وإظهاره حرفيًّا أولًا ثمََّّ إظهار قيمته ثانيًّا $HOME استُعمل محرف التهريب لتهريب المتغير
</syntaxhighlight>'''تحذير''': لا تمرِّر مدخلات المستخدم إلى هذه الدالة مطلقًا ما لم تتحقَّق من صحتها وسلامتها، إذ يستطيع المستخدم التحايل وإدخال محارف خاصَّة بالصدفة (metacharacters) -مثل <code>:</code> أو <code>&</code>- مما يسمح له بتشغيل أوامر أخرى.

إن أعطيت دالة رد النداء <code>callback</code>، فستُستدعى مع الوسائط (error, stdout, stderr). عند النجاح، ستكون قيمة الوسيط <code>error</code> قيمةً عدميَّةً <code>[[JavaScript/null|null]]</code>. أمَّا في حالة وجود خطأ، فسيكون الوسيط <code>error</code> نسخةً من <code>Error</code>. ستكون الخاصِّيَّة <code>error.code</code> هي حالة الخروج من العمليَّة الابن بينما ستُعيَّن الخاصِّيَّة <code>error.signal</code> إلى الإشارة (signal) التي أَنهت العمليَّة. يشير أي حالة خروج مغاير للقيمة 0 إلى حصول خطأٍ ما.

سيحتوي الوسيطان <code>stdout</code> و <code>stderr</code> المُمرَّران إلى دالة رد النداء على مخرجات العمليَّة الابن التي ترسلها إلى مجريَي الخرج والخطأ القياسيين. ستفك Node.js ترميز تلك المخرجات باستعمال الترميز UTF-8 افتراضيًّا ثمَّ تضعها في سلسلة نصية وتمرِّرها إلى دالة رد النداء. إن أردت استعمال ترميز مختلف عن الترميز UTF-8، فحدِّد هذا الترميز البديل الذي تريد استعماله في الخيار <code>encoding</code>. في حال أعطيت القيمة <code>'buffer'</code> إلى الخيار <code>encoding</code> أو أعطي اسم ترميز لم يُتعرَّف عليه، فسيُمرَّر حينئذٍ الكائن <code>Buffer</code> إلى دالة رد النداء بدلًا من ذلك.<syntaxhighlight lang="javascript">
const { exec } = require('child_process');
exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {
  if (error) {
    console.error(`exec error: ${error}`);
    return;
  }
  console.log(`stdout: ${stdout}`);
  console.log(`stderr: ${stderr}`);
});
</syntaxhighlight>إن كانت قيمة المعامل <code>timeout</code> أكبر من الصفر، فستُرسِل العمليَّة الأب إشارةً محدَّدةً بالخيار <code>killSignal</code> (القيمة الافتراضيَّة له هي الإشارة <code>'SIGTERM'</code>) إن تجاوزت أثناء عملها المهلة الزمنية <code>timeout</code> المعطاة بالميلي ثانية.

لا يستبدل التابع <code>child_process.exec()‎</code> العمليَّة الموجودة آنذاك، وتُستعمَل صدفةٌ لتنفيذ الأمر خلافًا لاستدعاء النظام للدالة <code>exec(3)</code>‎ في معيار POSIX.

إن استدعيت نسخة <code>util.promisify()‎</code> من هذا التابع، فسيُعيد كائنًا من النوع <code>[[jQuery/promise|Promise]]</code> مع الخاصِّيَّتين <code>stdout</code> و <code>stderr</code>. عند حصول خطأٍ ما (يشمل ذلك أي خطأ ناتج عن إعادة حالة خروج مغايرة للصفر)، فسيُعاد كائن <code>[[jQuery/promise|Promise]]</code> مرفوض مع قيمة الكائن <code>[[JavaScript/Error|error]]</code> نفسه المُعطى في دالة رد النداء ولكن مع إضافة الخاصِّيَّتين <code>stdout</code> و <code>stderr</code>.<syntaxhighlight lang="javascript">
const util = require('util');
const exec = util.promisify(require('child_process').exec);

async function lsExample() {
  const { stdout, stderr } = await exec('ls');
  console.log('stdout:', stdout);
  console.log('stderr:', stderr);
}
lsExample();
</syntaxhighlight>

=== <code>child_process.execFile(file[, args][, options][, callback])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v8.8.0
|إضافة المعامل <code>windowsHide</code>.
|-
|v0.1.91
|إضافة هذا التابع.
|}
* <code>file</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تحوي اسم أو مسار الملف القابل للتنفيذ المراد تشغيله.
* <code>args</code>: ‏[[JavaScript/String|<string[]‎>]] قائمةٌ من سلاسل نصية تمثِّل الوسائط.
* <code>options</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ من النوع <code>Object</code> يمكن أن يحتوي على الخيارات التالية:
** <code>cwd</code>: [[JavaScript/String|‏<string>]] سلسلةٌ نصيةٌ تمثِّل مجلد العمل الحالي للعملية الابن. القيمة الافتراضيَّة هي: <code>[[JavaScript/null|null]]</code>.
** <code>env</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ يتكون من الأزواج مفتاح/قيمة يمثِّل البيئة.
** <code>encoding</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثل الترميز المراد استعماله. القيمة الافتراضيَّة هي: <code>'utf8'</code>.
** <code>timeout</code>: ‏[[JavaScript/Number|<number>]] الفترة الزمنية القصوى بالميلي ثاينة التي يُسمَح فيها للعملية بالعمل. القيمة الافتراضيَّة هي: 0.
** <code>maxBuffer</code>: [[JavaScript/Number|‏<number>]] عددٌ يمثِّل أكبر حجم مسموحٍ به للبيانات بالبايت في مجريي الخرج والخطأ القياسيين. في حال تجاوز هذه القيمة، ستُنهَى العمليَّة الابن مباشرةً. ارجع إلى القسم «الخيار <code>maxBuffer</code> والترميز الموحد». القيمة الافتراضيَّة هي: 200 * 1024.
** <code>killSignal</code>: [[JavaScript/String|‏<string>]] | ‏[[JavaScript/String|<integer>]] قيمة الإشارة المراد استعمالها عندما يتم قتل (kill) العمليَّة المولدة.  القيمة الافتراضيَّة هي: <code>'SIGTERM'</code>.
** <code>uid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المستخدم المالك للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setuid.2.html setuid(2)]‎).
** <code>gid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المجموعة المالكة للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setgid.2.html setgid(2)]‎).
** <code>windowsHide</code>: ‏[[JavaScript/Boolean|<boolean>]] قيمةٌ منطقيةٌ تتحكم بإظهار وإخفاء نافذة الطرفية للعملية الفرعية التي ستُنشأ دومًا بشكل اعتيادي في أنظمة ويندوز. القيمة الافتراضيَّة هي: <code>false</code>.
** <code>windowsVerbatimArguments</code>: ‏[[JavaScript/Boolean|<boolean>]] قيمة منطقية تحدِّد إن كان يراد اقتباس أو تهريب الوسائط في ويندوز أم لا. يتجاهل هذا الخيار في الأنظمة الشبيهة بيونكس. القيمة الافتراضيَّة في: false.
** <code>shell</code>: [[JavaScript/Boolean|‏<boolean>]] | ‏[[JavaScript/String|<string>]] إن كانت <code>true</code>، فسينفذ الأمر <code>command</code> داخل صدفةٍ. ستستعمل <code>'‎/bin/sh'</code> في يونكس والأنظمة الشبيهة به، و <code>process.env.ComSpec</code> في ويندوز، ويمكن تحديد صدفة أخرى بتمرير سلسلة نصية لهذا الخيار. ارجع إلى القسم «متطلبات الصدفة» والقسم «صدفة ويندوز الافتراضيَّة» في الأسفل للمزيد من التفاصيل. القيمة الافتراضيَّة هي: <code>false</code> (عدم استعمال صدفة).
* <code>callback</code>: ‏[[JavaScript/Function|<Function>]] دالةٌ تستدعى مع المخرجات عند انتهاء العمليَّة.
** <code>error</code>: [[JavaScript/Error|‏<Error>]]
** <code>stdout</code>: ‏[[JavaScript/String|<string>]] | ‏<Buffer>
** <code>stderr</code>: ‏[[JavaScript/String|<string>]] | ‏<Buffer>
* نوع القيم المعادة: <ChildProcess>
يشبه هذا التابعُ التابعَ <code>child_process.exec()‎</code> في جميع النواحي باستثناء أنَّه لا يولِّد صدفةً بشكل افتراضي. عوضًا عن ذلك، سيُنفَّذ الملف <code>file</code> المحدَّد مباشرةً كعملية جديدة مما يجعل هذا التابع أكثر كفاءةً من نظيره <code>child_process.exec()‎</code>.

يدعم هذا التابع المعاملات نفسها التي يدعمها التابع <code>child_process.exec()</code>‎. وبما أنَّه لا تولَّد صدفةٌ، فإنَّ بعض السلوكيات مثل إعادة توجيه المدخلات والمخرجات وتنفيذ الملف في النطاق العام (file globbing) غير مدعومة.<syntaxhighlight lang="javascript">
const { execFile } = require('child_process');
const child = execFile('node', ['--version'], (error, stdout, stderr) => {
  if (error) {
    throw error;
  }
  console.log(stdout);
});

</syntaxhighlight>سيحتوي الوسيطان <code>stdout</code> و <code>stderr</code> الممرَّران إلى دالة رد النداء على مخرجات العمليَّة الابن التي ترسلها إلى مجرى الخرج والخطأ القياسيين. ستفك Node.js ترميز تلك المخرجات باستعمال الترميز UTF-8 افتراضيًّا ثمَّ تضعها في سلسلة نصية وتمرِّرها إلى دالة رد النداء. إن أردت استعمال ترميز مختلف عن الترميز UTF-8، فحدِّد هذا الترميز البديل الذي تريد استعماله في الخيار <code>encoding</code>. في حال أُعطيت القيمة <code>'buffer'</code> إلى الخيار <code>encoding</code> أو أعطي اسم ترميز لم يُتعرَّف عليه، فسيمرَّر حينئذٍ الكائن <code>Buffer</code> إلى دالة رد النداء بدلًا من ذلك.

إن استدعيت نسخة <code>util.promisify()‎</code> من هذا التابع، فسيعيد كائنًا من النوع <code>[[jQuery/promise|Promise]]</code> مع الخاصِّيَّتين <code>stdout</code> و <code>stderr</code>. عند حصول خطأ ما (يشمل ذلك أي خطأ ناتج عن إعادة حالة خروج مغايرة للصفر)، فسيُعاد كائن <code>[[jQuery/promise|Promise]]</code> مرفوض مع قيمة الكائن <code>[[JavaScript/Error|error]]</code> نفسه المعطى في دالة رد النداء ولكن مع إضافة الخاصَّيِّتين <code>stdout</code> و <code>stderr</code>.<syntaxhighlight lang="javascript">
const util = require('util');
const execFile = util.promisify(require('child_process').execFile);
async function getVersion() {
  const { stdout } = await execFile('node', ['--version']);
  console.log(stdout);
}
getVersion();
</syntaxhighlight>'''تحذير''': إن مُرِّرت القيمة المنطقيَّة <code>true</code> للخيار <code>shell</code>، فلا تمرِّر مدخلات المستخدم إلى هذه الدالة مطلقًا ما لم تتحقَّق من صحتها وسلامتها، إذ يستطيع المستخدم التحايل وإدخال محارف خاصَّة بالصدفة (metacharacters) -مثل <code>:</code> أو <code>&</code>- مما يسمح له بتشغيل أوامر أخرى.

=== <code>‎child_process.fork(modulePath[, args][, options])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v8.0.0
|أصبح بالإمكان أن يكون المعامل <code>stdio</code> سلسلةً نصيةً.
|-
|v6.4.0
|أضيف المعامل <code>stdio</code>.
|-
|v0.5.0
|أضيف هذا التابع.
|}
* <code>modulePath</code>: ‏[[JavaScript/String|<string>]] الوحدة المراد تشغيلها في العمليَّة الابن.
* <code>args</code>: ‏[[JavaScript/String|<string[]‎>]] قائمة سلاسل نصية تمثِّل الوسائط.
* <code>options</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ من النوع <code>Object</code> يمكن أن يحتوي على الخيارات التالية:
** <code>cwd</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثل مجلد العمل الحالي للعملية الابن. القيمة الافتراضيَّة هي: <code>[[JavaScript/null|null]]</code>.
** <code>env</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ يتكون من الأزواج مفتاح/قيمة يمثِّل البيئة.
** <code>execPath</code>: [[JavaScript/String|‏<string>]] أمرٌ قابلٌ للتنفيذ يستعمل لإنشاء العمليَّة الابن.
** <code>execArgv</code>: ‏[[JavaScript/String|<string[]‎]]> قائمة سلاسل نصية تمثِّل الوسائط المراد تمريرها إلى العمليَّة الابن المنشأة. القيمة الافتراضيَّة هي: <code>process.execArgv</code>.
** <code>silent</code>: ‏[[JavaScript/Boolean|<boolean>]] إن كان <code>true</code>، فستُحوَّل مجاري الدخل والخرج والخطأ القياسية إلى العمليَّة الأب. خلا ذلك، ستُورث تلك المجاري من العمليَّة الأب (ارجع إلى الخيار <code>'pipe'</code> والخيار <code>'inherit'</code> في مجاري الدخل والخرج القياسية (stdio) للتابع <code>child_process.spawn()‎</code> للمزيد من التفاصيل). القيمة الافتراضيَّة هي: <code>false</code>.
** <code>stdio</code>: ‏[[JavaScript/Array|<Array>]] | ‏[[JavaScript/String|<string>]] عندما يُعطى هذا الخيار، سيُتجاهَل الخيار <code>silent</code>. إن أعطيت مصفوفة من المتغيرات، فيجب أن تحتوي على عنصر واحد مع القيمة <code>'ipc'</code> مثل <code>[0, 1, 2, 'ipc']</code> وإلا سيرمى خطأٌ. ارجع إلى القسم «الخيار <code>options.stdio</code>» في التابع <code>child_process.spawn()‎</code> للمزيد من التفاصيل.
** <code>windowsVerbatimArguments</code>: ‏[[JavaScript/Boolean|<boolean>]] قيمةٌ منطقيَّةٌ تحدِّد إن كان يراد اقتباس أو تهريب الوسائط في ويندوز أم لا. يُتجاهل هذا الخيار في الأنظمة الشبيهة بيونكس. القيمة الافتراضيَّة في: <code>false</code>.
** <code>uid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المستخدم المالك للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setuid.2.html setuid(2)]‎).
** <code>gid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المجموعة المالكة للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setgid.2.html setgid(2)]‎).
* نوع القيمة المعادة: <ChildProcess>
التابع <code>child_process.fork()‎</code> هو حالةٌ خاَّصةٌ من التابع <code>child_process.spawn()‎</code> يُستعمَل خصيصًا لتوليد عمليات Node.js جديدة. يعيد هذا التابع الكائن <code>ChildProcess</code> مثل التابع <code>child_process.spawn()‎</code> تمامًا. يمتلك الكائن <code>ChildProcess</code> المعاد قناة اتصال إضافيَّة مضمَّنة فيه تسمح للرسائل بأن تمرَّر ذهابًأ وإيابًا بين العمليَّة الأب والعمليَّة الابن. للمزيد من التفاصيل، ارجع إلى التابع <code>subprocess.send()‎</code>.

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

سيولد التابع <code>child_process.fork()‎</code> نسخ جديدة من Node.js افتراضيًّا باستعمال الخاصِّيَّة <code>process.execPath</code> للعملية الأب. تسمح الخاصِّيَّة <code>execPath</code> ضمن الكائن <code>options</code> باستعمال مسار تنفيذ بديل.

عمليات Node.js التي بُدئت مع تحديد قيمة مخصَّصة للخاصِّيَّة <code>execPath</code> ستوصل مع العمليَّة الأب باستعمال واصف الملف (fd) المُعرَّف عبر متغير البيئة <code>NODE_CHANNEL_FD</code> في العمليَّة الابن.

لا ينسخ التابع <code>child_process.fork()‎</code> العمليَّة الحالية خلافًا للدالة <code>fork(2)</code>‎ في أنظمة POSIX.

الخيار <code>shell</code> الموجود في التابع <code>child_process.spawn()‎</code> غير مدعوم في التابع <code>child_process.fork()‎</code> وسيُتجاهل إن مرِّر إليه.

=== <code>child_process.spawn(command[, args][, options])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v8.8.0
|أضيف الخيار <code>windowsHide</code>.
|-
|v6.4.0
|أضيف الخيار <code>argv0</code>.
|-
|v5.7.0
|أضيف الخيار <code>shell</code>.
|-
|v0.1.90
|أضيف هذا التابع.
|}
* <code>command</code>: [[JavaScript/String|‏<string>]] الأمر المراد تنفيذه.
* <code>args</code>: [[JavaScript/String|‏<string[]‎>]] قائمة سلاسل نصية تمثِّل الوسائط المراد استعمالها مع الأمر <code>command</code>.
* <code>options</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ من النوع <code>Object</code> يمكن أن يحتوي على الخيارات التالية:
** <code>cwd</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثِّل مجلد العمل الحالي للعملية الابن. القيمة الافتراضيَّة هي: <code>null</code>.
** <code>env</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ يتكون من الأزواج مفتاح/قيمة يمثِّل البيئة.
** <code>argv0</code>: ‏[[JavaScript/String|<string>]] يضبط هذا الخيار قيمة <code>argv[0]‎</code> المراد إرسالها إلى العمليَّة الابن. إن لم يُعطَ هذا المعامل، فسيُعيَّن إلى <code>command</code>.
** <code>stdio</code>: [[JavaScript/Array|‏<Array>]] | [[JavaScript/String|‏<string>]] يمثِّل هذا الخيار ضبط مجاري الدخل والخرج القياسية (stdio) للعملية الابن. ارجع إلى القسم «الخيار <code>options.stdio</code>» في الأسفل للمزيد من التفاصيل.
** <code>deached</code>: ‏[[JavaScript/Boolean|<boolean>]] قيمةٌ منطقيةٌ تحدِّد إن كانت ستعمل العمليَّة الابن بشكل مستقل عن العمليَّة الأب لها. يعتمد هذا السلوك على المنصة المستعملة (ارجع إلى القسم «الخيار <code>options.detached</code>» في الأسفل للمزيد من التفاصيل).
** <code>uid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المستخدم المالك للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setuid.2.html setuid(2)]‎).
** <code>gid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المجموعة المالكة للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setgid.2.html setgid(2)]‎).
** <code>shell</code>: ‏[[JavaScript/Boolean|<boolean>]] | ‏[[JavaScript/String|<string>]] إن كان <code>true</code>، فسيُنفَّذ الأمر <code>command</code> داخل صدفةٍ. ستُستعمل <code>'‎/bin/sh'</code> في يونكس والأنظمة الشبيهة به، و <code>process.env.ComSpec</code> في ويندوز، ويمكن تحديد صدفة أخرى بتمرير سلسلة نصية لهذا الخيار. ارجع إلى القسم «متطلبات الصدفة» والقسم «صدفة ويندوز الافتراضيَّة» في الأسفل للمزيد من التفاصيل. القيمة الافتراضيَّة هي: <code>false</code> (عدم استعمال صدفة).
** <code>windowsVerbatimArguments</code>: [[JavaScript/Boolean|‏<boolean>]] قيمةٌ منطقيَّةٌ تحدِّد إن كان يراد اقتباس أو تهريب الوسائط في ويندوز أم لا. يُضبَط هذا الخيار إلى القيمة <code>true</code> تلقائيًّا عند ضبط الخيار <code>shell</code>. يتجاهل هذا الخيار في الأنظمة الشبيهة بيونكس. القيمة الافتراضيَّة في: <code>false</code>.
** <code>windowsHide</code>: [[JavaScript/Boolean|‏<boolean>]] قيمةٌ منطقيةٌ تتحكم بإظهار وإخفاء نافذة الطرفية للعملية الفرعية التي ستظهر دومًا بشكل اعتيادي في أنظمة ويندوز. القيمة الافتراضيَّة هي: <code>false</code>.
* نوع القيمة المعادة: <ChildProcess>
يولد التابع <code>child_process.spawn()‎</code> عملية جديدة باستعمال الأمر <code>command</code> المعطى مع وسائط سطر الأوامر المحدَّدة في المعامل <code>args</code>. إن لم يعطَ هذا المعامل، فسيعيَّن افتراضيًّا إلى مصفوفة فارغة.

'''تحذير''': إن مُرِّرت القيمة المنطقية <code>true</code> للخيار <code>shell</code>، فلا تمرِّر مدخلات المستخدم إلى هذه الدالة مطلقًا ما لم تتحقَّق من صحتها وسلامتها، إذ يستطيع المستخدم التحايل وإدخال محارف خاصَّة بالصدفة (metacharacters) -مثل <code>:</code> أو <code>&</code>- مما يسمح له بتشغيل أوامر أخرى.

يُستعمَل الوسيط الثالث <code>options</code> لتحديد خيارات إضافية مع تخصيص قيمة افتراضية لها:<syntaxhighlight lang="javascript">
const defaults = {
  cwd: undefined,
  env: process.env
};

</syntaxhighlight>يُستعمَل الخيار <code>cwd</code> لتحديد مجلد العمل الذي ستولد العمليَّة منه. إن لم يعطَ، فسيُورث مجلد العمل الحالي بشكل افتراضي.

يُستعمَل الخيار <code>env</code> لتحديد متغيرات البيئة التي ستكون متاحةً للعملية الجديدة. القيمة الافتراضيَّة لهذا الخيار هي <code>process.env</code>. انتبه إلى أنَّه سيتم تجاهل القيم <code>[[JavaScript/undefined|undefined]]</code> أينما وجدت في الخيار <code>env</code>.

توضِّح الشيفرة التالية مثالًا عن تنفيذ الأمر <code>ls -lh /usr</code> مع التحكم بمجرى الدخل القياسي، ومجرى الخطأ القياسي، وحالة الخروج:<syntaxhighlight lang="javascript">
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.log(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
</syntaxhighlight>مثالٌ آخر يوضِّح بالتفصيل كيفيَّة تنفيذ الأمر <code>ps ax | grep ssh</code>:<syntaxhighlight lang="javascript">
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.log(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.log(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
</syntaxhighlight>المثال التالي يوضِّح كيفيَّة التحقُّق من فشل التابع <code>spawn</code>:<syntaxhighlight lang="javascript">
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.log('Failed to start subprocess.');
});
</syntaxhighlight>ستَستعمِل بعض المنصات (مثل لينكس وماك) قيمة <code>argv[0]‎</code> لاسم العمليَّة بينما ستستعمل منصات أخرى (مثل ويندوز ونظام SunOS) الأمر <code>command</code> فقط.

في الوقت الحالي، تستبدل Node.js بقيمة <code>argv[0]‎</code> القيمة <code>process.execPath</code> عند بدء التشغيل، لذا لن تتطابق <code>process.argv[0]‎</code> في العمليَّة الابن مع قيمة المعامل <code>argv0</code> المُمرَّرة إلى <code>spawn</code> من العمليَّة الأب بل ستعيدها مع الخاصِّيَّة <code>process.argv0</code> عوضًا عن ذلك.

==== الخيار <code>options.detached</code> ====
أضيف في الإصدار v0.7.10.

في منصة ويندوز، يؤدي ضبط الخيار <code>options.detached</code> إلى القيمة <code>true</code> إلى توفير إمكانيَّة استمرار عمل العمليَّة الابن بعد خروج العمليَّة الأب، إذ سيكون للعملية الابن آنذاك نافذة طرفيَّة خاصَّة بها. انتبه إلى أنهَّ متى ما فُعِّل هذا الخيار للعملية الابن، لن يعطَّل بعدئذٍ.

أمَّا في بقية المنصات، إن ضُبِطَ الخيار <code>options.detached</code> إلى القيمة <code>true</code>، فستُعيِّن العمليَّة الابن قائدًا للمجموعة والجلسة الخاصَّتين بالعمليَّة الجديدة. انتبه إلى أنَّه قد تستمر العمليَّة الابن بالعمل حتى بعد خروج العمليَّة الأب بغض النظر إن كانتا مستقلتين أم لا. ارجع إلى صفحة <code>[http://man7.org/linux/man-pages/man2/setsid.2.html setsid(2)‎]</code> للمزيد من التفاصيل.

ستنتظر العمليَّة الأب بشكل افتراضي انتهاء العمليَّة الابن المستقلة. إن أردت منعها من الانتظار، فاستعمل التابع <code>subprocess.unref()‎</code> الذي سيَمنع حلقة أحداث العمليَّة الأب من إضافة العمليَّة الابن مع مرجعٍ لها؛ نتيجةً لذلك، ستتمكن العمليَّة الأب التي أصبحت مستقلة عن العمليَّة الابن من الخروج متى ما أرادت ذلك ما لم يكن هنالك قناة اتصال IPC منشأةٌ بينهما.

عند استعمال الخيار <code>detached</code> لبدء عمليَّة تعمل لمدة طويلة، لن تستمر العمليَّة الابن بالعمل في الخلفية بعد خروج العمليَّة الأب إلا إذا توافر ضبطٌ للخيار <code>stdio</code> وكان هذا الضبط لا يسمح للمجرى بالاتصال بأي شكل من الأشكال مع العمليَّة الأب. إن ورثت العمليَّة الابن مجاري الدخل والخرج القياسية (stdio) من العمليَّة الأب، فستبقى العمليَّة الابن مستقلةً بالتحكم بالطرفية.

تحوي الشيفرة التالية مثالًا عن عملية ابن طويلة الأمد، إذ يُفصَل ويُتجاهَل واصف ملف مجاري الدخل والخرج القياسية (stdio) للعملية الأب لها من أجل تجاهل انتهاء وخروج العمليَّة الأب:<syntaxhighlight lang="javascript">
const { spawn } = require('child_process');

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore'
});

subprocess.unref();

</syntaxhighlight>بدلًا من ذلك، يمكن إعادة توجيه مخرجات العمليات الأبناء إلى ملفات خارجية:<syntaxhighlight lang="javascript">
const fs = require('fs');
const { spawn } = require('child_process');
const out = fs.openSync('./out.log', 'a');
const err = fs.openSync('./out.log', 'a');

const subprocess = spawn('prg', [], {
  detached: true,
  stdio: [ 'ignore', out, err ]
});

subprocess.unref();
</syntaxhighlight>

==== الخيار <code>options.stdio</code> ====
{| class="wikitable"
!الإصدار
!التغييرات
|-
|v3.3.1
|أصبحت القيمة 0 مقبولة باستعمالها كواصف ملفٍ.
|-
|0.7.10
|أضيف هذا الخيار.
|}
يستعمل الخيار <code>options.stdio</code> لضبط الأنابيب المنشأة بين العمليَّة الأب والعمليَّة الابن. يعاد توجيه مجاري الخرج والدخل والخطأ القياسية للعمليَّة الابن إلى المجاري <code>options.stdio</code>، و <code>options.stdout</code>، و <code>options.stderr</code> المقابلة في الكائن <code>ChildProcess</code>. يكافئ هذا ضبط الخيار <code>options.stdio</code> مثلًا إلى القيمة <code>['pipe', 'pipe', 'pipe']</code>.

لتحقيق التوافقية، يمكن أن يكون الخيار <code>options.stdio</code> إحدى السلاسل النصية التالية:
* <code>'pipe'</code>: وهذا يكافئ <code>['pipe', 'pipe', 'pipe']</code> وهي القيمة الافتراضيَّة، أو
* <code>'ignore'</code>: وهذا يكافئ <code>['ignore', 'ignore', 'ignore']</code>، أو
* <code>'inherit'</code>: وهذا يكافئ <code>[process.stdin, process.stdout, process.stderr]</code> أو <code>[0,1,2]</code>.
خلا ذلك، ستكون قيمة الخيار <code>options.stdio</code> مصفوفةً يقابل فهرس كل عنصر فيها واصف ملفٍ (file descriptor، أو fd اختصارًا) في العمليَّة الابن. فتقابل مثلًا واصفات الملفات 0، و 1، و 2 مجرى الخرج القياسي، ومجرى الدخل القياسي، ومجرى الخطأ القياسي على التوالي. يمكن تحديد واصفات ملفات إضافيَّة لإنشاء أنابيب إضافية بين العمليَّة الأب والعلمية الابن.

يمكن استعمال إحدى القيم التالية مع الخيار <code>options.stdio</code>:
# <code>'pipe'</code>: إنشاء أنبوب بين العمليَّة الابن والعمليَّة الأب. تكون نهاية الأنبوب من طرف العمليَّة الأب مرئيةً للعملية الأب كخاصِّيَّة في الكائن <code>child_process</code> مثل القيمة <code>subprocess.stdio[fd]‎</code>. الأنابيب المنشأة من أجل واصفات الملفات 0، و 1، و 2 متاحةً أيضًا بوصفها <code>subprocess.stdin</code>، و <code>subprocess.stdout</code>، و <code>subprocess.stderr</code> على التوالي.
# <code>'ipc'</code>: إنشاء قناة IPC لتمرير رسائل أو واصفات ملف بين العلمية الأب والعمليَّة الابن. قد يملك الكائن <code>ChildProcess</code> قناة IPC واحدة لواصف ملف مجاري الدخل والخرج القياسية (stdio) على الأكثر. يؤدي ضبط هذا الخيار إلى تفعيل التابع <code>subprocess.send()‎</code>. إن كانت العمليَّة الابن هي عملية Node.js، فسيُفعِّل وجود القناة IPC التابعين <code>process.send()‎</code> و <code>process.disconnect()‎</code> بالإضافة إلى الحدثين <code>'disconnect'</code> و <code>'message'</code> ضمن العمليَّة الابن.  لا يمكن الوصول إلى واصف ملف القناة IPC بأيِّ طريقة كانت غير <code>process.send()‎</code> أو استعمال القناة IPC مع عملية ابنٍ ليست نسخةً من Node.js.
# <code>'ignore'</code>: حثُّ Node.js على تجاهل واصف الملف في العمليَّة الابن. لمَّا كانت Node.js تفتح واصفات من 0 إلى 2 للعمليات التي تولدها، فسيؤدي ضبط واصف الملف إلى القيمة <code>'ignore</code>' إلى إجبار Node.js على فتح ‎<code>/dev/null</code> وربطه بواصف ملف العمليَّة الابن.
# كائن <code>stream</code>: ‏<Stream> مشاركة مجرى قابل للقراءة أو للكتابة يشير إلى وحدة tty أو ملفٍ، أو مقبسٍ، أو أنبوبٍ مع العمليَّة الابن. يضاعف واصف الملف المضمِّن للمجرى في العمليَّة الابن إلى الواصف المقابل لفهرس المصفوفة <code>stdio</code>. انتبه إلى أنَّه يجب أن يكون للمجرى واصف مُضمَّن (لا ينطبق هذا على مجاري الملفات حتى يقع الحدث 'open').
# عددٌ صحيح موجب: تفسير القيمة العددية على أنَّها واصف ملف مفتوح حاليًا في العمليَّة الأب وتمت مشاركته مع العمليَّة الابن، بطريقة مشابهة لمشاركة الكائنات stream.
# القيمة <code>[[JavaScript/null|null]]</code>، والقيمة <code>[[JavaScript/undefined|undefined]]</code>: استعمال القيم الافتراضيَّة. سيُنشأ أنبوبٌ من أجل واصفات ملف مجاري الدخل والخرج القياسية (stdio) وهي 0، و 1، و 2 (أي مجرى الدخل القياسي (stdio)، ومجرى الخرج القياسي (stdout)، ومجرى الخطأ القياسي (stderr)). أمَّا من أجل واصف الملف 3 وما بعده، فالقيمة الافتراضيَّة له هي <code>'ignore'</code>.
إليك المثال التالي الذي يشرح ما سبق:<syntaxhighlight lang="javascript">
const { spawn } = require('child_process');

// ستستعمل العمليَّة الابن مجاري الدخل والخرج القياسية الخاصة بالعمليَّة الأب
spawn('prg', [], { stdio: 'inherit' });

// ستشارك العمليَّة الابن المولدة مجرى الخطأ القياسي فقط
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] });

// startd-style للتفاعل مع برامج تعرض الواجهة fd=4 فتح مجرى إضافي عبر
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });
</syntaxhighlight>الجدير بالذكر أنَّه عند إنشاء قناة IPC بين العمليات الآباء والعمليات الأبناء وكانت العمليَّة الابن إحدى عمليات Node.js، فستبدأ العمليَّة الابن مع قناة IPC غير مرجعيَّة (باستعمال <code>unref()‎</code>) حتى تُعيِّن هذه العمليَّة الابن معالج حدثٍ من أجل الحدث 'disconnect' أو الحدث 'message'. يسمح ذلك للعملية الابن بالخروج بشكل طبيعي دون الإبقاء على هذه العمليَّة مفتوحةً من طرف القناة IPC المفتوحة.

في الأنظمة الشبيهة بيونكس، يُجرِي التابع <code>child_process.spawn()‎</code> بعض العمليات على الذاكرة بشكل متزامن قبل فصل حلقة الأحداث (event loop) من العمليَّة الابن. قد تجد التطبيقات التي تحجز جزءًا كبيرًأ من الذاكرة استدعاءات متكررة وعالقة للتابع <code>child_process.spawn()‎</code>. للمزيد من التفاصيل، راجع [https://bugs.chromium.org/p/v8/issues/detail?id=7381 المشكلة 7381].

انظر أيضًا التابع <code>child_process.exec()‎</code>، والتابع <code>child_process.fork()‎</code>.

== إنشاء عملية متزامنة ==
التوابع <code>child_process.spawnSync()‎</code>، و <code>child_process.execSync()‎</code>، و <code>child_process.execFileSync()‎</code> هي توابع متزامنة، وستَحجِب حلقة الأحداث (event loop) مانعةً بذلك من تنفيذ أي جزءٍ آخرٍ من الشيفرة ريثمَّا تنتهي العمليَّة المولدة.

حجب الاستدعاءات في مثل هذه الحالة له فائدة جمَّة في تبسيط مهام السكربتات ذات الغرض العام (general-purpose scripting tasks) و تبسيط تحميل أو معالجة إعدادات التطبيقات عند بدء تشغيلها.

=== <code>child_process.execFileSync(file[, args][, options])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v8.8.0
|إضافة المعامل <code>windowsHide</code>.
|-
|v8.0.0
|أصبح بالإمكان استعمال الكائن <code>Uint8Array</code> مع المعامل <code>input</code>.
|-
|v6.2.1 - v4.5.0
|أصبح بالإمكان ضبط قيمة الخيار <code>encoding</code> إلى <code>buffer</code>.
|-
|v0.11.12
|أضيف هذا التابع.
|}
* <code>file</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تحوي اسم أو مسار الملف القابل للتنفيذ المراد تشغيله.
* <code>args</code>: ‏[[JavaScript/String|<string[]‎>]] قائمةٌ من سلاسل نصية تمثل الوسائط المراد استعمالها مع الملف <code>file</code>.
* <code>options</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ من النوع Object يمكن أن يحتوي على الخيارات التالية:
** <code>cwd</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثِّل مجلد العمل الحالي للعملية الابن. القيمة الافتراضيَّة هي: <code>[[JavaScript/null|null]]</code>.
** <code>input</code>: ‏[[JavaScript/String|<string>]] | ‏<Buffer> | ‏<Uint8Array> القيم التي ستُمرَّر إلى العمليَّة المولدة كمجرى دخل وخرج قياسي. إعطاء قيمة لهذا المعامل سيؤدي إلى تجاهل <code>stdio[0]‎</code>.
** <code>stdio</code>: ‏[[JavaScript/Array|<Array>]] | ‏[[JavaScript/String|<string>]] يمثِّل هذا المعامل الضبط المخصَّص لمجاري الدخل والخرج القياسية للعملية الابن. سيُستعمَل مجرى الخطأ القياسي للعملية نفس مجرى الخطأ القياسي للعملية الأب ما لم يُعطَ هذا المعامل. القيمة الافتراضيَّة هي: <code>'pipe'</code>.
** <code>env</code>: [[JavaScript/Object|‏<Object>]] كائنٌ يتكون من الأزواج مفتاح/قيمة يمثِّل البيئة.
** <code>uid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المستخدم المالك للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setuid.2.html setuid(2)]‎).
** <code>gid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المجموعة المالكة للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setgid.2.html setgid(2)]‎).
** <code>timeout</code>: [[JavaScript/Number|‏<number>]] الفترة الزمنية القصوى بالميلي ثانية التي يسمح فيها للعملية بالعمل. القيمة الافتراضيَّة هي: <code>[[JavaScript/undefined|undefined]]</code>.
** <code>killSignal</code>: ‏[[JavaScript/String|<string>]] | [[JavaScript/Number|‏<integer>]] قيمة الإشارة المراد استعمالها عندما يتم قتل (kill) العمليَّة المولدة. القيمة الافتراضيَّة هي: <code>'SIGTERM'</code>.
** <code>maxBuffer</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثِّل أكبر حجم مسموحٍ به للبيانات بالبايت في مجرى الخرج والخطأ القياسيين. في حال تجاوز هذه القيمة، ستُنهَى العمليَّة الابن مباشرةً. ارجع إلى القسم «الخيار <code>maxBuffer</code> والترميز الموحد». القيمة الافتراضيَّة هي: 200 * 1024.
** <code>encoding</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصية تمثل الترميز المراد استعماله مع جميع مدخلات ومخرجات مجاري الدخل والخرج القياسية. القيمة الافتراضيَّة هي: <code>'buffer'</code>.
** <code>windowsHide</code>: ‏[[JavaScript/Boolean|<boolean>]] قيمةٌ منطقيةٌ تتحكم بإظهار وإخفاء نافذة الطرفية للعملية الفرعية التي ستُنشأ دومًا بشكل اعتيادي في أنظمة ويندوز. القيمة الافتراضيَّة هي: <code>false</code>.
** <code>shell‏</code> [[JavaScript/Boolean|<boolean>]]‏ | ‏[[JavaScript/String|<string>]] إن كانت <code>true</code>، فسيُنفَّذ الأمر <code>command</code> داخل صدفةٍ. ستستعمل <code>'‎/bin/sh'</code> في يونكس والأنظمة الشبيهة به، و <code>process.env.ComSpec</code> في ويندوز، ويمكن تحديد صدفة أخرى بتمرير سلسلة نصية لهذا الخيار. ارجع إلى القسم «متطلبات الصدفة» والقسم «صدفة ويندوز الافتراضيَّة» في الأسفل للمزيد من التفاصيل. القيمة الافتراضيَّة هي: <code>false</code> (عدم استعمال صدفة).
* القيم المعادة: <Buffer> |‏ [[JavaScript/String|<string>]] مجرى الخرج القياسي من الأمر.
يشبه هذا التابعُ التابعَ <code>child_process.execFile()‎</code> في جميع النواحي عمومًا باستثناء أنه لن يعيد أي شيء حتى تغلق العمليَّة الابن بشكل كامل. عندما تنتهي المهلة الزمنية (timeout) وترسل الإشارة <code>killSignal</code>، فلن تعيد هذه الدالة أي شيء حتى خروج العمليَّة كاملًا.

إن اعترضت العمليَّة الابن الإشارة <code>SIGTERM</code> وعالجتها ولم تخرج، فستبقى العمليَّة الأب منتظرةً حتى خروج تلك العمليَّة.

إن انتهت مهلة العمليَّة الابن أو خرجت بحالة خروج مغايرة للصفر، فسيَرمي هذا التابع خطأً يتضمن نتيجة استدعاء التابع <code>child_process.spawnSync()‎</code> ضمنيًا كاملةً.

'''تحذير''': إن مُرِّرت القيمة المنطقيَّة <code>true</code> للخيار <code>shell</code>، فلا تمرِّر مدخلات المستخدم إلى هذه الدالة مطلقًا ما لم تتحقَّق من صحتها وسلامتها، إذ يستطيع المستخدم التحايل وإدخال محارف خاصَّة بالصدفة (metacharacters) -مثل <code>:</code> أو <code>&</code>- مما يسمح له بتشغيل أوامر أخرى.

=== <code>child_process.execSync(command[, options])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v8.8.0
|إضافة المعامل <code>windowsHide</code>.
|-
|v8.0.0
|أصبح بالإمكان استعمال الكائن <code>Uint8Array</code> مع المعامل <code>input</code>.
|-
|v0.11.12
|أضيف هذا التابع.
|}
* <code>command</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تحوي الأمر المراد تنفيذه.
* <code>args</code>:‏ [[JavaScript/String|<string[]‎>]] قائمةٌ من سلاسل نصية تمثل الوسائط المراد استعمال مع الأمر <code>command</code>.
* <code>options</code>:‏ [[JavaScript/Object|<Object>]] كائنٌ من النوع <code>Object</code> يمكن أن يحتوي على الخيارات التالية:
** <code>cwd</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثِّل مجلد العمل الحالي للعملية الابن. القيمة الافتراضيَّة هي: <code>[[JavaScript/null|null]]</code>.
** <code>input</code>: [[JavaScript/String|‏<string>]] | ‏<Buffer> | ‏<Uint8Array> القيم التي ستُمرَّر إلى العمليَّة المولدة كمجرى دخل وخرج قياسي. إعطاء قيمة لهذا المعامل سيؤدي إلى تجاهل <code>stdio[0]</code>.
** <code>stdio</code>:‏ [[JavaScript/Array|<Array>]] | [[JavaScript/String|‏<string>]] يمثِّل هذا المعامل الضبط المخصَّص لمجاري الدخل والخرج القياسية للعملية الابن. سيستعمل مجرى الخطأ القياسي للعملية الابن نفس مجرى الخطأ القياسي للعملية الأب ما لم يعطَ هذا المعامل. القيمة الافتراضيَّة هي: <code>'pipe'</code>.
** <code>env</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ يتكون من الأزواج مفتاح/قيمة يمثِّل البيئة.
** <code>shell</code>: ‏[[JavaScript/String|<string>]] الصدفة المراد تنفيذ الأمر <code>command</code> داخلها. ارجع إلى القسم «متطلبات الصدفة» والقسم «صدفة ويندوز الافتراضيَّة» في الأسفل للمزيد من التفاصيل. القيمة الافتراضيَّة هي: <code>'‎/bin/sh'</code> في يونكس والأنظمة الشبيهة به، و <code>process.env.ComSpec</code> في ويندوز.
** <code>uid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المستخدم المالك للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setuid.2.html setuid(2)]‎).
** <code>gid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المجموعة المالكة للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setgid.2.html setgid(2)]‎).
** <code>timeout</code>:‏ [[JavaScript/Number|<number>]] الفترة الزمنية القصوى بالميلي ثاينة التي يُسمَح فيها للعملية بالعمل. القيمة الافتراضيَّة هي: <code>[[JavaScript/undefined|undefined]]</code>.
** <code>killSignal</code>: ‏[[JavaScript/String|<string>]] | [[JavaScript/Number|‏<integer>]] قيمة الإشارة المراد استعمالها عندما يتم قتل (kill) العمليَّة المولدة. القيمة الافتراضيَّة هي: <code>'SIGTERM'</code>.
** <code>maxBuffer</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثِّل أكبر حجم مسموحٍ به للبيانات بالبايت في مجرى الخرج والخطأ القياسيين. في حال تجاوز هذه القيمة، ستُنهَى العمليَّة الابن مباشرةً. ارجع إلى القسم «الخيار <code>maxBuffer</code> والترميز الموحد». القيمة الافتراضيَّة هي: 200 * 1024.
** <code>encoding</code>: [[JavaScript/String|‏<string>]] سلسلةٌ نصيةٌ تمثِّل الترميز المراد استعماله مع جميع مدخلات ومخرجات مجاري الدخل والخرج القياسية. القيمة الافتراضيَّة هي: <code>'buffer'</code>.
** <code>windowsHide</code>: ‏[[JavaScript/Boolean|<boolean>]] قيمةٌ منطقيةٌ تتحكم بإظهار وإخفاء نافذة الطرفية للعملية الفرعية التي ستُنشأ دومًا بشكل اعتيادي في أنظمة ويندوز. القيمة الافتراضيَّة هي: <code>false</code>.
* القيم المعادة: <Buffer> | ‏[[JavaScript/String|<string>]] مجرى الخرج القياسي من الأمر.
يشبه هذا التابعُ التابعَ <code>child_process.exec()‎</code> في جميع النواحي عمومًا باستثناء أنَّه لن يعيد أي شيء حتى تُغلق العمليَّة الابن بشكل كامل. فعندما تنتهي المهلة الزمنية (timeout) وتُرسَل الإشارة <code>killSignal</code>، لن تعيد هذه الدالة أي شيء حتى خروج العمليَّة كاملًا.

انتبه إلى أنه إذا اعترضت العمليَّة الابن الإشارة <code>SIGTERM</code> وعالجتها ولم تخرج، فستبقى العمليَّة الأب منتظرةً حتى خروج تلك العمليَّة.

إن انتهت مهلة العمليَّة الابن أو خرجت بحالة خروج مغايرة للصفر، فسيَرمي هذا التابع خطأً يتضمن نتيجة استدعاء التابع <code>child_process.spawnSync()‎</code> ضمنيًا كاملةً.

'''تحذير''': إن مُرِّرت القيمة المنطقيَّة <code>true</code> للخيار <code>shell</code>، فلا تمرِّر مدخلات المستخدم إلى هذه الدالة مطلقًا ما لم تتحقَّق من صحتها وسلامتها، إذ يستطيع المستخدم التحايل وإدخال محارف خاصَّة بالصدفة (metacharacters) -مثل <code>:</code> أو <code>&</code>- مما يسمح له بتشغيل أوامر أخرى.

=== <code>child_process.spawnSync(command[, args][, options])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v8.8.0
|أضيف المعامل <code>windowsHide</code>.
|-
|v8.0.0
|أصبح بالإمكان استعمال الكائن <code>Uint8Array</code> مع المعامل <code>input</code>.
|-
|v6.2.1 - v4.5.0
|أصبح بالإمكان ضبط قيمة الخيار <code>encoding</code> الآن إلى <code>buffer</code>.
|-
|v5.7.0
|أضيف المعامل <code>shell</code>.
|-
|v0.11.12
|أضيف هذا التابع.
|}
* <code>command</code>:‏ [[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تحوي الأمر المراد تنفيذه.
* <code>args</code>:‏ [[JavaScript/String|<string[]‎>]] قائمةٌ من سلاسل نصية تمثل الوسائط المراد استعمال مع الأمر command.
* <code>options</code>:‏ [[JavaScript/Object|<Object>]] كائنٌ من النوع Object يمكن أن يحتوي على الخيارات التالية:
** <code>cwd</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثِّل مجلد العمل الحالي للعملية الابن. القيمة الافتراضيَّة هي: null.
** <code>input</code>:‏ [[JavaScript/String|<string>]] | ‏<Buffer> | ‏<Uint8Array> القيم التي ستُمرَّر إلى العمليَّة المولدة كمجرى دخل وخرج قياسي. إعطاء قيمة لهذا المعامل سيؤدي إلى تجاهل stdio[0]‎.
** <code>stdio</code>: ‏[[JavaScript/Array|<Array>]] | [[JavaScript/String|‏<string>]] يمثِّل هذا المعامل الضبط المخصص لمجاري الدخل والخرج القياسية للعملية الابن.
** <code>env</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ يتكون من الأزواج مفتاح/قيمة يمثِّل البيئة.
** <code>uid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المستخدم المالك للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setuid.2.html setuid(2)]‎).
** <code>gid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المجموعة المالكة للعملية (ارجع إلى [http://man7.org/linux/man-pages/man2/setgid.2.html setgid(2)]‎).
** <code>timeout</code>:‏ [[JavaScript/Number|<number>]] الفترة الزمنية القصوى بالميلي ثاينة التي يُسمح فيها للعملية بالعمل. القيمة الافتراضيَّة هي: undefined.
** <code>killSignal</code>:‏ [[JavaScript/String|<string>]] | [[JavaScript/Number|‏<integer>]] قيمة الإشارة المراد استعمالها عندما يتم قتل (kill) العمليَّة المولدة. القيمة الافتراضيَّة هي: 'SIGTERM'.
** <code>maxBuffer</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثِّل أكبر حجم مسموحٍ به للبيانات بالبايت في مجرى الخرج والخطأ القياسيين. في حال تجاوز هذه القيمة، ستُنهَى العمليَّة الابن مباشرةً. ارجع إلى القسم «الخيار <code>maxBuffer</code> والترميز الموحد». القيمة الافتراضيَّة هي: 200 * 1024.
** <code>encoding</code>: ‏<string> سلسلةٌ نصيةٌ تمثِّل الترميز المراد استعماله مع جميع مدخلات ومخرجات مجاري الدخل والخرج القياسية. القيمة الافتراضيَّة هي: 'buffer'.
** <code>shell</code>:‏ [[JavaScript/Boolean|<boolean>]] | [[JavaScript/String|‏<string>]] إن كانت true، فسيُنفَّذ الأمر command داخل صدفةٍ. ستستعمل '‎/bin/sh' في يونكس والأنظمة الشبيهة به، و process.env.ComSpec في ويندوز، ويمكن تحديد صدفة أخرى بتمرير سلسلة نصية لهذا الخيار. ارجع إلى القسم «متطلبات الصدفة» والقسم «صدفة ويندوز الافتراضيَّة» في الأسفل للمزيد من التفاصيل. القيمة الافتراضيَّة هي: false (عدم استعمال صدفة).
** <code>windowsVerbatimArguments</code>:‏ [[JavaScript/Boolean|<boolean>]] قيمةٌ منطقيَّةٌ تحدِّد إن كان يراد اقتباس أو تهريب الوسائط في ويندوز أم لا. يُتجاهل هذا الخيار في الأنظمة الشبيهة بيونكس. القيمة الافتراضيَّة في: false.
** <code>windowsHide</code>: [[JavaScript/Boolean|‏<boolean>]] قيمةٌ منطقيَّةٌ تتحكم بإظهار وإخفاء نافذة الطرفية للعملية الفرعية التي ستُنشأ دومًا بشكل اعتيادي في أنظمة ويندوز. القيمة الافتراضيَّة هي: false.
* القيم المعادة: [[JavaScript/Boject|<Object>]]
** <code>pid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثِّل مُعرِِّف العمليَّة الابن.
** <code>output</code>: ‏[[JavaScript/Array|<Array>]] مصفوفةٌ تحوي نتائج مخرجات مجاري الدخل والخرج القياسية.
** <code>stdout</code>: ‏<Buffer> | ‏[[JavaScript/String|<string>]] محتوى المجرى <code>output[1]‎</code>.
** <code>stderr</code>: ‏<Buffer> | ‏[[JavaScript/String|<string>]] محتوى المجرى <code>output[2]‎</code>.
** <code>status</code>: ‏[[JavaScript/String|<number>]] حالة خروج العمليَّة الابن.
** <code>signal</code>: ‏[[JavaScript/String|<string>]] الإشارة المستعملة في قتل العمليَّة الابن.
** <code>error</code>: ‏[[JavaScript/Error|<Error>]] الكائن <code>errer</code> إن فشلت العمليَّة الابن أو انتهت مهلتها الزمنية.
يشبه هذا التابعُ التابعَ <code>child_process.spawn()‎</code> في جميع النواحي عمومًا باستثناء أنَّه لن يعيد أي شيء حتى تُغلَق العمليَّة الابن بشكل كامل. فعندما تنتهي المهلة الزمنية (timeout) وتُرسَل الإشارة <code>killSignal</code>، لن تعيد هذه الدالة أي شيء حتى خروج العمليَّة كاملًا.

انتبه إلى أنَّه إذا اعترضت العمليَّة الابن الإشارة <code>SIGTERM</code> وعالجتها ولم تخرج، فستبقى العمليَّة الأب منتظرةً حتى خروج تلك العمليَّة.

إن انتهت مهلة العمليَّة الابن أو خرجت بحالة خروج مغايرة للصفر، فسيَرمي هذا التابع خطأً يتضمن نتيجة استدعاء التابع <code>child_process.spawnSync()‎</code> ضمنيًا كاملةً.

'''تحذير''': إن مُرِّرت القيمة المنطقيَّة <code>true</code> للخيار <code>shell</code>، فلا تمرِّر مدخلات المستخدم إلى هذه الدالة مطلقًا ما لم تتحقَّق من صحتها وسلامتها، إذ يستطيع المستخدم التحايل وإدخال محارف خاصَّة بالصدفة (metacharacters) -مثل <code>:</code> أو <code>&</code>- مما يسمح له بتشغيل أوامر أخرى.

== الصنف <code>ChildProcess</code> ==
أضيف في الإصدار v2.2.0.

النُسَخ المنشأة من الصنف <code>ChildProcess</code> هي <code>EventEmitters</code> التي تمثل العمليات المُولَّدة.

لا تُنشَأ النسخ <code>ChildProcess</code> بشكل مباشر بل تستعمل التوابع <code>child_process.spawn()‎</code>، أو <code>child_process.exec()‎</code>، أو <code>child_process.execFile()‎</code>، أو <code>child_process.fork()‎</code> لإنشائها.

=== الحدث 'close' ===
أضيف في الإصدار v0.7.7.
* <code>code</code>: ‏[[JavaScript/Number|<number>]] حالة الخروج إن خرجت العمليَّة بمفردها.
* <code>signal</code>: ‏[[JavaScript/String|<string>]] الإشارة التي استُعملت لإنهاء العمليَّة الابن.
يُطلق الحدث 'close' عند إغلاق مجاري الدخل والخرج القياسية للعملية الابن. يختلف هذا الحدث عن الحدث 'exit'، إذ قد تتشارك عدَّة عمليات مجاري الخرج والدخل القياسية نفسها.

=== الحدث 'disconnect' ===
أضيف في الإصدار v0.7.2.

يُطلق الحدث 'disconnect' بعد استدعاء التابع <code>subprocess.disconnect()‎</code> في العمليَّة الأب أو التابع <code>process.disconnect()‎</code> في العمليَّة الابن. بعد قطع الاتصال بين العمليَّة الأب والابن، لن يعد بالإمكان إرسال أو استقبال أية رسائل بينهما، وستصبح قيمة الخاصِّيَّة <code>subprocess.connected</code> القيمة <code>false</code>.

=== الحدث 'error' ===
* err: ‏[[JavaScript/Error|<Error>]] الخطأ.
يُطلق الحدث 'error' في حال:
# لم يكن بالإمكان توليد العمليَّة، أو
# لم يكن بالإمكان قتل العمليَّة، أو
# فشلُ إرسال رسالةٍ إلى العمليَّة الابن.
قد يُطلق الحدث 'exit' أو لا بعد حدوث خطأٍ. عند الاستماع إلى الحدثين 'exit' و 'error' كلاهما، من المهم ضمان عدم استدعاء دوال معالجة الحدث عدة مرات من غير قصد.

انظر أيضًا التابع <code>subprocess.kill()‎</code> والتابع <code>subprocess.send()‎</code>.

=== الحدث 'exit' ===
أضيف في الإصدار v0.1.90.
* <code>code</code>: ‏[[JavaScript/Number|<number>]] حالة الخروج إن خرجت العمليَّة بمفردها.
* <code>signal</code>: ‏[[JavaScript/String|<string>]] الإشارة التي استُعملت لإنهاء العمليَّة الابن.
يُطلق الحدث بعد انتهاء العمليَّة الابن. إن خرجت العمليَّة، سيحوي <code>code</code> نسخةً من حالة الخروج النهائية لتلك العمليَّة. خلا ذلك، ستكون قيمته <code>[[JavaScript/null|null]]</code>. أمَّا إن أُنهيت العمليَّة نتيجة تلقيها إشارة معيَّنة، فسيحوي <code>signal</code> اسم تلك الإشارة. خلا ذلك، ستكون قيمته <code>[[JavaScript/null|null]]</code>.

انتبه إلى أنَّه عندما يُطلق الحدث 'exit'، ربما لا تزال مجاري الخرج والدخل للعمليَّة الابن مفتوحةً آنذاك.

انتبه أيضًا إلى أنَّ Node.js تنشئ معالجات إشارة (signal handlers) من أجل الإشارة <code>SIGINI</code> والإشارة <code>SIGTRM</code>، ولن تتوقف عمليات Node.js مباشرةً عندما تتلقى هاتين الإشارتين. عوضًا عن ذلك، ستُجري Node.js سلسلةً من أعمال التنظيف ثمَّ ستعيد عرض الإشارة المعالجة.

انظر أيضًا الدالة <code>waitpid(2)‎</code>.

=== الحدث 'message' ===
أضيف في الإصدار v0.5.9.
* <code>mesage</code>: ‏[[JavaScript/Object|<Object>]] كائن JSON مفسَّر أو قيمة أولية.
* <code>sendHandle</code>: ‏<Handle> كائن <code>net.Socket</code>، أو كائن <code>net.Server</code>، أو قيمة [[JavaScript/undefined|غير مُعرَّفة]].
يُطلق الحدث 'message' عندما تُستعمَل العمليَّة الابن التابع <code>process.send(0)‎</code> لإرسال رسائل.

تمرُّ الرسائل المرسلة عبر عمليات ترميز (serialization) وتفسير (parsing)، لذا لن تشبه الرسالة المستلمة في أغلب الأحيان الرسالة الأصلية المرسلة.

=== الخاصِّيَّة <code>subprocess.connected</code> ===
أضيفت في الإصدار v0.7.2.
* [[JavaScript/Boolean|<boolean>]] تضبط إلى القيمة false بعد استدعاء التابع <code>subprocess.disconnect()‎</code>.
تحدد الخاصِّيَّة <code>subprocess.connected</code> إن لا يزال بالإمكان إرسال واستقبال رسائل من وإلى العمليَّة الابن. عندما تصبح قيمة الخاصِّيَّة <code>false</code>، لن نتمكن بعدئذٍ من إرسال أو استلام أية رسالة.

=== التابع <code>subprocess.disconnect()‎</code> ===
أضيف في الإصدار V0.7.2.

يغلق هذا التابع القناة IPC بين العمليَّة الأب والعمليَّة الابن عند استدعائه، مما يسمح بخروج العمليَّة الابن بأمان متى ما انقطعت الاتصالات التي كانت تبقيها تعمل. بعد استدعاء هذا التابع، ستُضبط قيمة الخاصِّيَّة <code>subprocess.connected</code> والخاصِّيَّة <code>process.connected</code> في العمليَّة الأب والابن كلاهما (على التوالي) إلى القيمة false. نتئجةً لذلك، لن يعد بالإمكان تمرير أية رسالة بين هاتين العمليتين.

سيُطلق الحدث 'disconnect' عندما لا يكون هنالك أية رسائل في العمليَّة المستقبِلة. سيُطلق هذا الحدث في أغلب الأحيان بعد استدعاء <code>subprocess.disconnect()‎</code> مباشرةً.

انتبه إلى أنَّه عندما تكون العمليَّة نسخةً من Node.js (مثل توليد عملية باستعمال <code>child_process.fork()‎</code>)، فيمكن استدعاء التابع <code>process.disconnect()‎</code> ضمن العمليَّة الابن لإغلاق القناة IPC أيضًا.

=== <code>subprocess.kill([signal])‎</code> ===
أضيف في الإصدار v0.1.90.
* <code>signal</code>:‏ <string> الإشارة المراد إرسالها إلى العمليَّة الابن. القيمة الافتراضيَّة هي: <code>'SIGTERM'</code>.
يرسل هذا التابع إشارةً إلى العمليَّة الابن. إن لم يعطَ أي وسيط، فسيرسل التابع الإشارة <code>'SIGTERM'</code> إلى العمليَّة. ارجع إلى الدالة <code>signal(7)‎</code> للاطلاع على قائمة الإشارات المتاحة.<syntaxhighlight lang="javascript">
const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// إلى العمليَّة SIGHUP إرسال الإشارة
grep.kill('SIGHUP');

</syntaxhighlight>يمكن أن يطلِق الكائن <code>ChildProcess</code> الحدث 'error' إن لم تُسلَّم الإشارة المرسلة للعملية. فإرسال إشارة إلى عملية ابن قد أغلقت للتو ليس خطأً ولكن قد يترتَّب على ذلك عواقب غير متوقعة. على وجه التحديد، إن أعيد إسناد مُعرِّف العمليَّة (PID) إلى عملية أخرى، فستُسلَّم الإشارة إلى هذه العمليَّة بدلًا من العمليَّة المقصودة، وسنحصل بذلك على نتائج لا يحمد عقباها.

انتبه إلى أنَّه لما كان اسم الدالة «kill» يشير إلى «قتل» العمليَّة، فليس بالضرورة أن تكون الإشارة المرسلة إلى العمليَّة الابن إشارة إنهاءٍ لتلك العمليَّة.

انظر أيضًا الدالة <code>kill(2)‎</code>.

انتبه أيضًا أنه في لينكس، لن توقف العمليات الأبناء للعمليات الأبناء عند محاول قتل العمليَّة الأب لها. يرجَّح أن يحدث هذا عند تشغيل عملية جديدة في صدفةٍ أو مع استعمال الخيار <code>shell</code> للكائن <code>ChildProcess</code>. توضِّح الشيفرة التالية هذا الأمر:<syntaxhighlight lang="javascript">
'use strict';
const { spawn } = require('child_process');

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`
  ], {
    stdio: ['inherit', 'inherit', 'inherit']
  }
);

setTimeout(() => {
  subprocess.kill(); // التي تعمل في الصدفة node لا تُنهِي العمليَّة
}, 2000);
</syntaxhighlight>

=== الخاصِّيَّة <code>subprocess.killed</code> ===
أضيف في الإصدار v0.5.10.
* [[JavaScript/Boolean|<boolean>]] تُضبَط إلى القيمة بعد استعمال التابع <code>subprocess.kill()‎</code> من أجل إرسال إشارةٍ إلى العمليَّة الابن بنجاح.
تحدِّد الخاصِّيَّة <code>subprocess.killed</code> إن كانت العمليَّة الابن قد استَلمت بنجاح إشارةً من التابع <code>subprocess.kill()‎</code>، إذ لا تشير هذه الخاصِّيَّة إن كانت قد أُنهيت العمليَّة الابن أم لا.

=== الخاصِّيَّة <code>subprocess.pid</code> ===
أضيفت في الإصدار v0.1.90.
* [[JavaScript/Number|<integer>]]
تعيد هذه الخاصِّيَّة مُعرِّف العمليَّة (PID) للعملية الابن.<syntaxhighlight lang="javascript">
const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();
</syntaxhighlight>

=== <code>subprocess.send(message[, sendHandle[, options]][, callback])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v5.8.0
|أضيف المعامل <code>option</code> والخيار <code>keepOpen</code> تحديدًا.
|-
|v5.0.0
|أصبحت هذه الدالة تعيد قيمة منطقية للتحكم بالتدفق الآن.
|-
|v4.0.0
|أضيف المعامل <code>callback</code>.
|-
|v0.5.9
|أضيف هذا التابع.
|}
* <code>message</code>: ‏[[JavaScript/Object|<Object>]]
* <code>sendHandle</code>: ‏<Handle>
* <code>options</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ يُستعمل لضبط عمليَّة إرسال أنواع محدَّدة من المعالجات. يدعم هذا الكائن الخاصِّيَّات التالية:
** <code>keepOpen</code>: ‏[[JavaScript/Boolean|<boolean>]] يُستعمَل هذا الخيار عند تمرير نُسخٍ من <code>net.Socket</code>. عندما تكون <code>true</code>، سيُبقى على المقبس مفتوحًا خلال عمليَّة الإرسال. القيمة الافتراضيَّة هي: <code>false</code>.
* <code>callback</code>: ‏[[JavaScript/Function|<Function>]]
* نوع القيم المعادة: [[JavaScript/Boolean|<boolean>]]
عندما تُنشَأ قناة IPC بين العمليَّة الأب والعمليَّة الابن (مثل عند استعمال التابع <code>child_process.fork()‎</code>)، يمكن حينئذٍ استعمال التابع <code>subprocess.send()‎</code> لإرسال رسائل إلى العمليَّة الابن. وعندما تكون العمليَّة الابن هي نسخةٌ من Node.js، فيمكن استلام هذه الرسائل عبر الحدث 'message'.

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

تفحَّص مثلًا الشيفرة التالية التي تعود إلى عملية أب:<syntaxhighlight lang="javascript">
const cp = require('child_process');
const n = cp.fork(`${__dirname}/sub.js`);

n.on('message', (m) => {
  console.log(الأب استلم رسالة:', m);
});

// {يجب أن نجعل العمليَّة الابن تطبع الرسالة التالية: الابن استلم رسالة: {مرحبًا أيها العالم
n.send({ مرحبًا أيها العالم });
</syntaxhighlight>وستكون الشيفرة الخاصَّة بالعمليَّة الابن شبيهةً بالشيفرة التالية:<syntaxhighlight lang="javascript">
process.on('message', (m) => {
  console.log(الابن استلم رسالة:', m);
});

// {NaN :يجب أن نجعل العمليَّة الأب تطبع الرسالة التالية: الأب استلم رسالة: {{تفاح: 'موجود', موز
process.send({ تفاح: 'موجود'، موز: NaN});
</syntaxhighlight>لدى عمليات Node.js الابن تابعٌ خاص بها لإرسال رسائل إلى العمليَّة الأب ألا وهو التابع <code>process.send()‎</code>.

هنالك حالة خاصَّة تتعلق بإرسال رسالة تشبه <code>{cmd: 'NODE_foo'‎}</code>، إذ إن للبادئة <code>NODE_‎</code> معنًى خاص عند احتواء الخاصِّيَّة <code>cmd</code> عليها  واستعمالها ضمن نواة Node.js، ولن تظهر في الحدث 'message' للعملية الابن. عوضًا عن ذلك، نجد مثل هذه الرسائل في الحدث 'internalMessage'، إذ تحفظها Node.js داخليًا. يجب على التطبيقات تجنب استعمال مثل هذه الرسائل أو استعمال أحداث مثل 'internalMessage' التي تتغير دون أي تنبيه بذلك.

يُستعمَل الخيار <code>sendHandle</code> المُمرَّر إلى التابع <code>subprocess.send()‎</code> في تمرير الكائن <code>TCP server</code> أو الكائن <code>socket</code> إلى العمليَّة الابن. سيُستلم الابن الكائن كأنَّه وسيط ثانٍ مُرِّر إلى دالة رد النداء المسجلة في الحدث 'message'. أية بيانات تُستَلم وتُخزَّن في المقبس ستُرسل إلى العمليَّة الابن.

يمثِّل المعامل <code>callback</code> الاختياري دالةً تستدعى عد إتمام إرسال الرسالة وغالبًا قبل أن تستلم العمليَّة الابن هذا الرسالة.  تستدعى هذه الدالة مع وسيط وحيد؛ يكون هذا الوسيط القيمة <code>[[JavaScript/null|null]]</code> عند نجاح عملية الإرسال، أو الكائن <code>[[JavaScript/Error|Error]]</code> عند فشلها.

إن لم يعطَ المعامل <code>callback</code> ولم يُتمكن من إرسال الرسالة، فسيُطلِق الكائن <code>ChildProcess</code> الحدث 'error'. يحدث هذا مثلًا عندما تكون العمليَّة الابن قد أُغلقَت مسبقًا.

سيعيد التابع <code>subprocess.send()‎</code> القيمة المنطقية <code>false</code> إن أغلقت القناة أو عندما تتجاوز الرسائل غير المرسلة المتراكمة حدًا يصبح فيه من غير المعقول إرسال المزيد من الرسائل. خلا ذلك، سيعيد التابع القيمة <code>true</code>. يمكن أيضًا استعمال الدالة <code>callback</code> للتحكم بتدفق البيانات ضمن القناة.

==== مثالٌ عن إرسال الكائن <code>server</code> ====
يمكن استعمال المعامل <code>sendHandle</code> لتمرير معالج الكائن <code>TCP server</code> مثلًا إلى العمليَّة الابن كما هو موضح في المثال التالي:<syntaxhighlight lang="javascript">
const subprocess = require('child_process').fork('subprocess.js');

// وإرسال المعالج server فتح الكائن
const server = require('net').createServer();
server.on('connection', (socket) => {
  socket.end('handled by parent');
});
server.listen(1337, () => {
  subprocess.send('server', server);
});

</syntaxhighlight>ستستلم الآن العمليَّة الابن الكائن <code>server</code> بالشكل التالي:<syntaxhighlight lang="javascript">
process.on('message', (m, server) => {
  if (m === 'server') {
    server.on('connection', (socket) => {
      socket.end('handled by child');
    });
  }
});
</syntaxhighlight>حالما يصبح الخادم مشاركًا بين العمليَّة الأب والأبن، يمكن معالجة بعض الاتصالات عبر العمليَّة الأب وبعضها الآخر عبر العمليَّة الابن.

لمَّا كان هذا المثال يستعمل خادمًا أنشئ باستعمال الوحدة <code>net</code>، فإنَّ خوادم الوحدة <code>dgram</code> تستعمل نفس سير العمل تمامًا باستثناء الاستماع إلى الحدث 'message' بدلًأ من الحدث 'connection' واستعمال التابع <code>server.bind()‎</code> بدلًا من التابع <code>server.listen()‎</code>. على أي حال، هذا مدعوم حاليًا في المنصات الشبيهة بيونكس فقط.

==== مثالٌ عن إرسال الكائن <code>socket</code> ====
بطريقةٍ مشابهةٍ للمثال السابق، يمكن استعمال المعامل <code>sendHandle</code> لتمرير معالج الكائن <code>socket</code> إلى العمليَّة الابن. في الشيفرة التالية، سيتولد عمليتي ابن تعالج كلٌّ منهما الاتصالات ذات الأولوية «طبيعي» (normal) أو «استثنائي» (special):<syntaxhighlight lang="javascript">
const { fork } = require('child_process');
const normal = fork('subprocess.js', ['normal']);
const special = fork('subprocess.js', ['special']);

// لمنع pauseOnConnect فتح الخادم ثمَّ إرسال المقابس إلى العمليَّة الابن. سيُستعمل الخيار 
// قراءة المقابس قبل إرسالها إلى العمليَّة الابن
const server = require('net').createServer({ pauseOnConnect: true });
server.on('connection', (socket) => {

  // إن كان هذا الاتصال ذو أولوية طبيعية
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket);
    return;
  }
  // وإن كان هذا الاتصال ذو أولية استثنائية
  normal.send('socket', socket);
});
server.listen(1337);
</syntaxhighlight>ستستلم الخاصِّيَّة <code>subprocess.js</code> المعالج <code>socket</code> كوسيط ثانٍ مُرِّر إلى دالة رد نداء الحدث:<syntaxhighlight lang="javascript">
process.on('message', (m, socket) => {
  if (m === 'socket') {
    if (socket) {
      // .التحقق من خروج مقبس العميل
      // .يحتمل أن يكون المقبس مغلقًا في فترة الإرسال والاستقبال في العمليَّة الابن
      socket.end(`Request handled with ${process.argv[2]} priority`);
    }
  }
});
</syntaxhighlight>حالما يُمرَّر مقبسٌ إللى العمليَّة الابن، لن يعد بإمكان العمليَّة الأب تتبع متى يُدمَّر المقبس. لمعرفة ذلك، تصبح قيمة الخاصِّيَّة ‎.<code>connections</code> بعد تدميرالمقبس <code>[[JavaScript/null|null]]</code>. لا ينصح باستعمال الخاصِّيَّة ‎<code>.maxConnections</code> عندما يحدث ذلك.

ينصح أيضًا بالتأكد من أيَّة معالجات للحدث 'message' في العمليَّة الابن حيث يوجد الكائن <code>socket</code>، إذ قد يُغلق الاتصال في الوقت الذي تستغرقه العمليَّة في إرسال الاتصال إلى العمليَّة الابن.

=== الخاصية <code>subprocess.stderr</code> ===
أضيفت في الإصدار v0.1.90.
* <stream.Readable>
تعدُّ هذه الخاصِّيَّة مجرًى قابلًا للقراءة  يمثِّل مجرى الخطأ القياسي (stderr) للعملية الابن.

إن ولِّدت العمليَّة الابن مع ضبط قيمة الخيار <code>stdio[2]‎</code> إلى أية قيمة باستثناء <code>'pipe'</code>، فستكون حينئذٍ قيمة هذه الخاصِّيَّة <code>[[JavaScript/null|null]]</code>.

هذه الخاصِّيَّة هي اسمٌ بديل للخاصِّيَّة <code>subprocess.stdio[2]‎</code>، وستشير كلا الخاصِّيَّتين إلى القيمة نفسها.

=== الخاصية <code>subprocess.stdin</code> ===
أضيفت في الإصدار v0.1.90.
* <stream.Writable>
تعدُّ هذه الخاصِّيَّة مجرًى قابلًا للكتابة يمثِّل مجرى الدخل القياسي (stdin) للعملية الابن.

انتبه إلى أنَّه إن انتظرت العمليَّة الابن حتى تُقرأ جميع المدخلات الخاصَّة بها، فلن تَستأنف عملها حتى يُغلق هذا المجرى عبر استدعاء <code>end()‎</code>.

إن ولِّدت العمليَّة الابن مع ضبط قيمة الخيار <code>stdio[0]‎</code> إلى أيَّة قيمة باستثناء <code>'pipe'</code>، فستكون حينئذٍ قيمة هذه الخاصِّيَّة <code>[[JavaScript/null|null]]</code>.

هذه الخاصِّيَّة هي اسمٌ بديل للخاصِّيَّة <code>subprocess.stdio[0]‎</code>، وستشير كلا الخاصِّيَّتين إلى القيمة نفسها.

=== الخاصية <code>subprocess.stdio</code> ===
أضيفت في الإصدار v0.7.10.
* [[JavaScript/Array|<Array>]]
تمثِّل هذه الخاصِّيَّة مصفوفةً من الأنابيب المتفرقة المتصلة بالعمليَّة الابن، وتتطابق مع موقع القيمة <code>'pipe'</code> المعطاة في الخيار <code>stdio</code> المُمرَّر إلى التابع <code>child_process.spawn()‎</code>. انتبه إلى أنَّ التوابع <code>subprocess.stdio[0]‎</code>، و  <code>subprocess.stdio[1]‎</code>، و <code>subprocess.stdio[2]‎</code> متاحةً أيضًا بالشكل <code>subprocess.stdin</code>، و <code>subprocess.stdout</code>، و <code>subprocess.stderr</code> على التوالي.

في المثال التالي، يُضبَط واصف الملف 1 (stdout) للعملية الابن إلى القيمة <code>'pipe'</code>، لذا يتشكل لدينا المجرى <code>subprocess.stdio[1]‎</code> فقط في العمليَّة الأب، وستأخذ جميع قيم المصفوفة الأخرى القيمة <code>[[JavaScript/null|null]]</code>:<syntaxhighlight lang="javascript">
const assert = require('assert');
const fs = require('fs');
const child_process = require('child_process');

const subprocess = child_process.spawn('ls', {
  stdio: [
    0, // Use parent's stdin for child
    'pipe', // Pipe child's stdout to parent
    fs.openSync('err.out', 'w') // توجيه مجرى الخطأ القياسي للعملية الابن إلى ملف
  ]
});

assert.strictEqual(subprocess.stdio[0], null);
assert.strictEqual(subprocess.stdio[0], subprocess.stdin);

assert(subprocess.stdout);
assert.strictEqual(subprocess.stdio[1], subprocess.stdout);

assert.strictEqual(subprocess.stdio[2], null);
assert.strictEqual(subprocess.stdio[2], subprocess.stderr);
</syntaxhighlight>

=== الخاصية <code>subprocess.stdout</code> ===
أضيفت في الإصدار v0.1.90.
* <stream.Readable>
تعدُّ هذه الخاصِّيَّة مجرًى قابلًا للقراءة يمثِّل مجرى الخرج القياسي (stdout) للعملية الابن.

إن ولِّدت العمليَّة الابن مع ضبط قيمة الخيار <code>stdio[1]‎</code> إلى أيَّة قيمة باستثناء <code>'pipe'</code>، فستكون حينئذٍ قيمة هذه الخاصِّيَّة <code>[[JavaScript/null|null]]</code>.

هذه الخاصِّيَّة هي اسمٌ بديل للخاصِّيَّة <code>subprocess.stdio[1]‎</code>، وستشير كلا الخاصِّيَّتين إلى القيمة نفسها.

== الخيار maxBuffer والترميز الموحد (Unicode) ==
يحدِّد الخيار <code>maxBuffer</code> أكبر عددٍ من البايتات المسموح نقلها عبر مجريي الخرج والخطأ القياسيين. في تجاوزت عدد البايتات هذه القيمة، فستُنهى العمليَّة الابن. إنَّ لهذا تأثير على المخرجات التي تحوي ترميزًا لمحارف متعدِّدة البايتات مثل الترميز UTF-8 أو UTF-16. على سبيل المثال، سيُرسِل <code>console.log('中文测试')‎</code> ثلاثة عشر بايتًا مُرمَّزة بترميز UTF-8 إلى مجرى الخرج القياسي رغم أنَّ الرسالة تحوي أربعة محارف فقط.

== متطلبات الصدفة ==
يجب أن تتعرَّف الصدفة على المبدل ‎<code>-c</code> في الأنظمة الشبيهة بيونكس أو ‎<code>/d /s /c</code>  في أنظمة ويندوز. في ويندوز، يجب أن يكون مفسِّر سطر الأوامر متوافقًا مع 'cmd.exe'.

== صدفة ويندوز الافتراضية ==
رغم أنَّ مايكروسوفت قد خصَّصت <code>%COMSPEC%</code> ليحتوي على مسار 'cmd.exe' في البيئة الجذرية (root environment) إلا أنَّ العمليات الأبناء لا تخضع دومًا إلى المتطلبات نفسها. نتيجةً لذلك، تستخدم 'cmd.exe' في الدوال <code>child_process</code> حيث بالإمكان توليد صدفةٍ كحل بديل إن كانت <code>process.env.ComSpec</code> غير متاحة.

== مصادر ==
* [https://nodejs.org/dist/latest-v10.x/docs/api/child_process.html صفحة Child Process في توثيق Node.js الرسمي.]
[[تصنيف:Node.js]]