-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathprocess.html
More file actions
1964 lines (1928 loc) · 132 KB
/
process.html
File metadata and controls
1964 lines (1928 loc) · 132 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Process | Node.js v12.0.0 Documentation</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic">
<link rel="stylesheet" href="assets/style.css">
<link rel="stylesheet" href="assets/hljs.css">
<link rel="canonical" href="https://nodejs.org/api/process.html">
</head>
<body class="alt apidoc" id="api-section-process">
<div id="content" class="clearfix">
<div id="column2" class="interior">
<div id="intro" class="interior">
<a href="/" title="Go back to the home page">
Node.js
</a>
</div>
<ul>
<li><a href="documentation.html" class="nav-documentation">About these Docs</a></li>
<li><a href="synopsis.html" class="nav-synopsis">Usage & Example</a></li>
</ul>
<div class="line"></div>
<ul>
<li><a href="assert.html" class="nav-assert">Assertion Testing</a></li>
<li><a href="async_hooks.html" class="nav-async_hooks">Async Hooks</a></li>
<li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
<li><a href="addons.html" class="nav-addons">C++ Addons</a></li>
<li><a href="n-api.html" class="nav-n-api">C/C++ Addons - N-API</a></li>
<li><a href="child_process.html" class="nav-child_process">Child Processes</a></li>
<li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
<li><a href="cli.html" class="nav-cli">Command Line Options</a></li>
<li><a href="console.html" class="nav-console">Console</a></li>
<li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
<li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
<li><a href="dns.html" class="nav-dns">DNS</a></li>
<li><a href="domain.html" class="nav-domain">Domain</a></li>
<li><a href="esm.html" class="nav-esm">ECMAScript Modules</a></li>
<li><a href="errors.html" class="nav-errors">Errors</a></li>
<li><a href="events.html" class="nav-events">Events</a></li>
<li><a href="fs.html" class="nav-fs">File System</a></li>
<li><a href="globals.html" class="nav-globals">Globals</a></li>
<li><a href="http.html" class="nav-http">HTTP</a></li>
<li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
<li><a href="https.html" class="nav-https">HTTPS</a></li>
<li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
<li><a href="intl.html" class="nav-intl">Internationalization</a></li>
<li><a href="modules.html" class="nav-modules">Modules</a></li>
<li><a href="net.html" class="nav-net">Net</a></li>
<li><a href="os.html" class="nav-os">OS</a></li>
<li><a href="path.html" class="nav-path">Path</a></li>
<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance Hooks</a></li>
<li><a href="process.html" class="nav-process active">Process</a></li>
<li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
<li><a href="querystring.html" class="nav-querystring">Query Strings</a></li>
<li><a href="readline.html" class="nav-readline">Readline</a></li>
<li><a href="repl.html" class="nav-repl">REPL</a></li>
<li><a href="stream.html" class="nav-stream">Stream</a></li>
<li><a href="string_decoder.html" class="nav-string_decoder">String Decoder</a></li>
<li><a href="timers.html" class="nav-timers">Timers</a></li>
<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
<li><a href="tracing.html" class="nav-tracing">Trace Events</a></li>
<li><a href="tty.html" class="nav-tty">TTY</a></li>
<li><a href="dgram.html" class="nav-dgram">UDP/Datagram</a></li>
<li><a href="url.html" class="nav-url">URL</a></li>
<li><a href="util.html" class="nav-util">Utilities</a></li>
<li><a href="v8.html" class="nav-v8">V8</a></li>
<li><a href="vm.html" class="nav-vm">VM</a></li>
<li><a href="worker_threads.html" class="nav-worker_threads">Worker Threads</a></li>
<li><a href="zlib.html" class="nav-zlib">ZLIB</a></li>
</ul>
<div class="line"></div>
<ul>
<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">GitHub Repo & Issue Tracker</a></li>
</ul>
</div>
<div id="column1" data-id="process" class="interior">
<header>
<h1>Node.js v12.0.0 Documentation</h1>
<div id="gtoc">
<ul>
<li>
<a href="index.html" name="toc">Index</a>
</li>
<li>
<a href="all.html">View on single page</a>
</li>
<li>
<a href="process.json">View as JSON</a>
</li>
<li class="version-picker">
<a href="#">View another version <span>▼</span></a>
<ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v11.x/api/process.html">11.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v10.x/api/process.html">10.x <b>LTS</b></a></li>
<li><a href="https://nodejs.org/docs/latest-v9.x/api/process.html">9.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v8.x/api/process.html">8.x <b>LTS</b></a></li>
<li><a href="https://nodejs.org/docs/latest-v7.x/api/process.html">7.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v6.x/api/process.html">6.x <b>LTS</b></a></li>
<li><a href="https://nodejs.org/docs/latest-v5.x/api/process.html">5.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v4.x/api/process.html">4.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/process.html">0.12.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/process.html">0.10.x</a></li></ol>
</li>
<li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/process.md"><span class="github_icon"><svg height="16" width="16" viewBox="0 0 16.1 16.1" fill="currentColor"><path d="M8 0a8 8 0 0 0-2.5 15.6c.4 0 .5-.2.5-.4v-1.5c-2 .4-2.5-.5-2.7-1 0-.1-.5-.9-.8-1-.3-.2-.7-.6 0-.6.6 0 1 .6 1.2.8.7 1.2 1.9 1 2.4.7 0-.5.2-.9.5-1-1.8-.3-3.7-1-3.7-4 0-.9.3-1.6.8-2.2 0-.2-.3-1 .1-2 0 0 .7-.3 2.2.7a7.4 7.4 0 0 1 4 0c1.5-1 2.2-.8 2.2-.8.5 1.1.2 2 .1 2.1.5.6.8 1.3.8 2.2 0 3-1.9 3.7-3.6 4 .3.2.5.7.5 1.4v2.2c0 .2.1.5.5.4A8 8 0 0 0 16 8a8 8 0 0 0-8-8z"/></svg></span>Edit on GitHub</a></li>
</ul>
</div>
<hr>
</header>
<div id="toc">
<h2>Table of Contents</h2>
<ul>
<li>
<p><a href="#process_process">Process</a></p>
<ul>
<li>
<p><a href="#process_process_events">Process Events</a></p>
<ul>
<li><a href="#process_event_beforeexit">Event: 'beforeExit'</a></li>
<li><a href="#process_event_disconnect">Event: 'disconnect'</a></li>
<li><a href="#process_event_exit">Event: 'exit'</a></li>
<li><a href="#process_event_message">Event: 'message'</a></li>
<li><a href="#process_event_multipleresolves">Event: 'multipleResolves'</a></li>
<li><a href="#process_event_rejectionhandled">Event: 'rejectionHandled'</a></li>
<li>
<p><a href="#process_event_uncaughtexception">Event: 'uncaughtException'</a></p>
<ul>
<li><a href="#process_warning_using_uncaughtexception_correctly">Warning: Using <code>'uncaughtException'</code> correctly</a></li>
</ul>
</li>
<li><a href="#process_event_unhandledrejection">Event: 'unhandledRejection'</a></li>
<li>
<p><a href="#process_event_warning">Event: 'warning'</a></p>
<ul>
<li><a href="#process_emitting_custom_warnings">Emitting custom warnings</a></li>
</ul>
</li>
<li><a href="#process_signal_events">Signal Events</a></li>
</ul>
</li>
<li><a href="#process_process_abort">process.abort()</a></li>
<li><a href="#process_process_allowednodeenvironmentflags">process.allowedNodeEnvironmentFlags</a></li>
<li><a href="#process_process_arch">process.arch</a></li>
<li><a href="#process_process_argv">process.argv</a></li>
<li><a href="#process_process_argv0">process.argv0</a></li>
<li><a href="#process_process_channel">process.channel</a></li>
<li><a href="#process_process_chdir_directory">process.chdir(directory)</a></li>
<li><a href="#process_process_config">process.config</a></li>
<li><a href="#process_process_connected">process.connected</a></li>
<li><a href="#process_process_cpuusage_previousvalue">process.cpuUsage([previousValue])</a></li>
<li><a href="#process_process_cwd">process.cwd()</a></li>
<li><a href="#process_process_debugport">process.debugPort</a></li>
<li><a href="#process_process_disconnect">process.disconnect()</a></li>
<li><a href="#process_process_dlopen_module_filename_flags">process.dlopen(module, filename[, flags])</a></li>
<li><a href="#process_process_emitwarning_warning_options">process.emitWarning(warning[, options])</a></li>
<li>
<p><a href="#process_process_emitwarning_warning_type_code_ctor">process.emitWarning(warning[, type[, code]][, ctor])</a></p>
<ul>
<li><a href="#process_avoiding_duplicate_warnings">Avoiding duplicate warnings</a></li>
</ul>
</li>
<li><a href="#process_process_env">process.env</a></li>
<li><a href="#process_process_execargv">process.execArgv</a></li>
<li><a href="#process_process_execpath">process.execPath</a></li>
<li><a href="#process_process_exit_code">process.exit([code])</a></li>
<li><a href="#process_process_exitcode">process.exitCode</a></li>
<li><a href="#process_process_getegid">process.getegid()</a></li>
<li><a href="#process_process_geteuid">process.geteuid()</a></li>
<li><a href="#process_process_getgid">process.getgid()</a></li>
<li><a href="#process_process_getgroups">process.getgroups()</a></li>
<li><a href="#process_process_getuid">process.getuid()</a></li>
<li><a href="#process_process_hasuncaughtexceptioncapturecallback">process.hasUncaughtExceptionCaptureCallback()</a></li>
<li><a href="#process_process_hrtime_time">process.hrtime([time])</a></li>
<li><a href="#process_process_hrtime_bigint">process.hrtime.bigint()</a></li>
<li><a href="#process_process_initgroups_user_extragroup">process.initgroups(user, extraGroup)</a></li>
<li><a href="#process_process_kill_pid_signal">process.kill(pid[, signal])</a></li>
<li><a href="#process_process_mainmodule">process.mainModule</a></li>
<li><a href="#process_process_memoryusage">process.memoryUsage()</a></li>
<li><a href="#process_process_nexttick_callback_args">process.nextTick(callback[, ...args])</a></li>
<li><a href="#process_process_nodeprecation">process.noDeprecation</a></li>
<li><a href="#process_process_pid">process.pid</a></li>
<li><a href="#process_process_platform">process.platform</a></li>
<li><a href="#process_process_ppid">process.ppid</a></li>
<li><a href="#process_process_release">process.release</a></li>
<li><a href="#process_process_send_message_sendhandle_options_callback">process.send(message[, sendHandle[, options]][, callback])</a></li>
<li><a href="#process_process_setegid_id">process.setegid(id)</a></li>
<li><a href="#process_process_seteuid_id">process.seteuid(id)</a></li>
<li><a href="#process_process_setgid_id">process.setgid(id)</a></li>
<li><a href="#process_process_setgroups_groups">process.setgroups(groups)</a></li>
<li><a href="#process_process_setuid_id">process.setuid(id)</a></li>
<li><a href="#process_process_setuncaughtexceptioncapturecallback_fn">process.setUncaughtExceptionCaptureCallback(fn)</a></li>
<li><a href="#process_process_stderr">process.stderr</a></li>
<li><a href="#process_process_stdin">process.stdin</a></li>
<li>
<p><a href="#process_process_stdout">process.stdout</a></p>
<ul>
<li><a href="#process_a_note_on_process_i_o">A note on process I/O</a></li>
</ul>
</li>
<li><a href="#process_process_throwdeprecation">process.throwDeprecation</a></li>
<li><a href="#process_process_title">process.title</a></li>
<li><a href="#process_process_tracedeprecation">process.traceDeprecation</a></li>
<li><a href="#process_process_umask_mask">process.umask([mask])</a></li>
<li><a href="#process_process_uptime">process.uptime()</a></li>
<li><a href="#process_process_version">process.version</a></li>
<li><a href="#process_process_versions">process.versions</a></li>
<li><a href="#process_exit_codes">Exit Codes</a></li>
</ul>
</li>
</ul>
</div>
<div id="apicontent">
<h1>Process<span><a class="mark" href="#process_process" id="process_process">#</a></span></h1>
<p>The <code>process</code> object is a <code>global</code> that provides information about, and control
over, the current Node.js process. As a global, it is always available to
Node.js applications without using <code>require()</code>.</p>
<h2>Process Events<span><a class="mark" href="#process_process_events" id="process_process_events">#</a></span></h2>
<p>The <code>process</code> object is an instance of <a href="events.html#events_class_eventemitter"><code>EventEmitter</code></a>.</p>
<h3>Event: 'beforeExit'<span><a class="mark" href="#process_event_beforeexit" id="process_event_beforeexit">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.11.12</span>
</div>
<p>The <code>'beforeExit'</code> event is emitted when Node.js empties its event loop and has
no additional work to schedule. Normally, the Node.js process will exit when
there is no work scheduled, but a listener registered on the <code>'beforeExit'</code>
event can make asynchronous calls, and thereby cause the Node.js process to
continue.</p>
<p>The listener callback function is invoked with the value of
<a href="#process_process_exitcode"><code>process.exitCode</code></a> passed as the only argument.</p>
<p>The <code>'beforeExit'</code> event is <em>not</em> emitted for conditions causing explicit
termination, such as calling <a href="#process_process_exit_code"><code>process.exit()</code></a> or uncaught exceptions.</p>
<p>The <code>'beforeExit'</code> should <em>not</em> be used as an alternative to the <code>'exit'</code> event
unless the intention is to schedule additional work.</p>
<h3>Event: 'disconnect'<span><a class="mark" href="#process_event_disconnect" id="process_event_disconnect">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.7.7</span>
</div>
<p>If the Node.js process is spawned with an IPC channel (see the <a href="child_process.html">Child Process</a>
and <a href="cluster.html">Cluster</a> documentation), the <code>'disconnect'</code> event will be emitted when
the IPC channel is closed.</p>
<h3>Event: 'exit'<span><a class="mark" href="#process_event_exit" id="process_event_exit">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.1.7</span>
</div>
<ul>
<li><code>code</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
</ul>
<p>The <code>'exit'</code> event is emitted when the Node.js process is about to exit as a
result of either:</p>
<ul>
<li>The <code>process.exit()</code> method being called explicitly;</li>
<li>The Node.js event loop no longer having any additional work to perform.</li>
</ul>
<p>There is no way to prevent the exiting of the event loop at this point, and once
all <code>'exit'</code> listeners have finished running the Node.js process will terminate.</p>
<p>The listener callback function is invoked with the exit code specified either
by the <a href="#process_process_exitcode"><code>process.exitCode</code></a> property, or the <code>exitCode</code> argument passed to the
<a href="#process_process_exit_code"><code>process.exit()</code></a> method.</p>
<pre><code class="language-js">process.on(<span class="hljs-string">'exit'</span>, (code) => {
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`About to exit with code: <span class="hljs-subst">${code}</span>`</span>);
});</code></pre>
<p>Listener functions <strong>must</strong> only perform <strong>synchronous</strong> operations. The Node.js
process will exit immediately after calling the <code>'exit'</code> event listeners
causing any additional work still queued in the event loop to be abandoned.
In the following example, for instance, the timeout will never occur:</p>
<pre><code class="language-js">process.on(<span class="hljs-string">'exit'</span>, (code) => {
setTimeout(<span class="hljs-function"><span class="hljs-params">()</span> =></span> {
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'This will not run'</span>);
}, <span class="hljs-number">0</span>);
});</code></pre>
<h3>Event: 'message'<span><a class="mark" href="#process_event_message" id="process_event_message">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.5.10</span>
</div>
<ul>
<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> a parsed JSON object
or a serializable primitive value.</li>
<li><code>sendHandle</code> <a href="net.html#net_class_net_server" class="type"><net.Server></a> | <a href="net.html#net_class_net_socket" class="type"><net.Socket></a> a <a href="net.html#net_class_net_server"><code>net.Server</code></a> or <a href="net.html#net_class_net_socket"><code>net.Socket</code></a>
object, or undefined.</li>
</ul>
<p>If the Node.js process is spawned with an IPC channel (see the <a href="child_process.html">Child Process</a>
and <a href="cluster.html">Cluster</a> documentation), the <code>'message'</code> event is emitted whenever a
message sent by a parent process using <a href="child_process.html#child_process_subprocess_send_message_sendhandle_options_callback"><code>childprocess.send()</code></a> is received by
the child process.</p>
<p>The message goes through serialization and parsing. The resulting message might
not be the same as what is originally sent.</p>
<h3>Event: 'multipleResolves'<span><a class="mark" href="#process_event_multipleresolves" id="process_event_multipleresolves">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v10.12.0</span>
</div>
<ul>
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The error type. One of <code>'resolve'</code> or <code>'reject'</code>.</li>
<li><code>promise</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> The promise that resolved or rejected more than once.</li>
<li><code>value</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> The value with which the promise was either resolved or
rejected after the original resolve.</li>
</ul>
<p>The <code>'multipleResolves'</code> event is emitted whenever a <code>Promise</code> has been either:</p>
<ul>
<li>Resolved more than once.</li>
<li>Rejected more than once.</li>
<li>Rejected after resolve.</li>
<li>Resolved after reject.</li>
</ul>
<p>This is useful for tracking errors in an application while using the promise
constructor. Otherwise such mistakes are silently swallowed due to being in a
dead zone.</p>
<p>It is recommended to end the process on such errors, since the process could be
in an undefined state. While using the promise constructor make sure that it is
guaranteed to trigger the <code>resolve()</code> or <code>reject()</code> functions exactly once per
call and never call both functions in the same call.</p>
<pre><code class="language-js">process.on(<span class="hljs-string">'multipleResolves'</span>, (type, promise, reason) => {
<span class="hljs-built_in">console</span>.error(type, promise, reason);
setImmediate(<span class="hljs-function"><span class="hljs-params">()</span> =></span> process.exit(<span class="hljs-number">1</span>));
});
<span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">main</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">try</span> {
<span class="hljs-keyword">return</span> <span class="hljs-keyword">await</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span>(<span class="hljs-function">(<span class="hljs-params">resolve, reject</span>) =></span> {
resolve(<span class="hljs-string">'First call'</span>);
resolve(<span class="hljs-string">'Swallowed resolve'</span>);
reject(<span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">'Swallowed reject'</span>));
});
} <span class="hljs-keyword">catch</span> {
<span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">'Failed'</span>);
}
}
main().then(<span class="hljs-built_in">console</span>.log);
<span class="hljs-comment">// resolve: Promise { 'First call' } 'Swallowed resolve'</span>
<span class="hljs-comment">// reject: Promise { 'First call' } Error: Swallowed reject</span>
<span class="hljs-comment">// at Promise (*)</span>
<span class="hljs-comment">// at new Promise (<anonymous>)</span>
<span class="hljs-comment">// at main (*)</span>
<span class="hljs-comment">// First call</span></code></pre>
<h3>Event: 'rejectionHandled'<span><a class="mark" href="#process_event_rejectionhandled" id="process_event_rejectionhandled">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v1.4.1</span>
</div>
<ul>
<li><code>promise</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> The late handled promise.</li>
</ul>
<p>The <code>'rejectionHandled'</code> event is emitted whenever a <code>Promise</code> has been rejected
and an error handler was attached to it (using <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch"><code>promise.catch()</code></a>, for
example) later than one turn of the Node.js event loop.</p>
<p>The <code>Promise</code> object would have previously been emitted in an
<code>'unhandledRejection'</code> event, but during the course of processing gained a
rejection handler.</p>
<p>There is no notion of a top level for a <code>Promise</code> chain at which rejections can
always be handled. Being inherently asynchronous in nature, a <code>Promise</code>
rejection can be handled at a future point in time — possibly much later than
the event loop turn it takes for the <code>'unhandledRejection'</code> event to be emitted.</p>
<p>Another way of stating this is that, unlike in synchronous code where there is
an ever-growing list of unhandled exceptions, with Promises there can be a
growing-and-shrinking list of unhandled rejections.</p>
<p>In synchronous code, the <code>'uncaughtException'</code> event is emitted when the list of
unhandled exceptions grows.</p>
<p>In asynchronous code, the <code>'unhandledRejection'</code> event is emitted when the list
of unhandled rejections grows, and the <code>'rejectionHandled'</code> event is emitted
when the list of unhandled rejections shrinks.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> unhandledRejections = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Map</span>();
process.on(<span class="hljs-string">'unhandledRejection'</span>, (reason, promise) => {
unhandledRejections.set(promise, reason);
});
process.on(<span class="hljs-string">'rejectionHandled'</span>, (promise) => {
unhandledRejections.delete(promise);
});</code></pre>
<p>In this example, the <code>unhandledRejections</code> <code>Map</code> will grow and shrink over time,
reflecting rejections that start unhandled and then become handled. It is
possible to record such errors in an error log, either periodically (which is
likely best for long-running application) or upon process exit (which is likely
most convenient for scripts).</p>
<h3>Event: 'uncaughtException'<span><a class="mark" href="#process_event_uncaughtexception" id="process_event_uncaughtexception">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.1.18</span>
</div>
<p>The <code>'uncaughtException'</code> event is emitted when an uncaught JavaScript
exception bubbles all the way back to the event loop. By default, Node.js
handles such exceptions by printing the stack trace to <code>stderr</code> and exiting
with code 1, overriding any previously set <a href="#process_process_exitcode"><code>process.exitCode</code></a>.
Adding a handler for the <code>'uncaughtException'</code> event overrides this default
behavior. Alternatively, change the <a href="#process_process_exitcode"><code>process.exitCode</code></a> in the
<code>'uncaughtException'</code> handler which will result in the process exiting with the
provided exit code. Otherwise, in the presence of such handler the process will
exit with 0.</p>
<p>The listener function is called with the <code>Error</code> object passed as the only
argument.</p>
<pre><code class="language-js">process.on(<span class="hljs-string">'uncaughtException'</span>, (err) => {
fs.writeSync(<span class="hljs-number">1</span>, <span class="hljs-string">`Caught exception: <span class="hljs-subst">${err}</span>\n`</span>);
});
setTimeout(<span class="hljs-function"><span class="hljs-params">()</span> =></span> {
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'This will still run.'</span>);
}, <span class="hljs-number">500</span>);
<span class="hljs-comment">// Intentionally cause an exception, but don't catch it.</span>
nonexistentFunc();
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'This will not run.'</span>);</code></pre>
<h4>Warning: Using `'uncaughtException'` correctly<span><a class="mark" href="#process_warning_using_uncaughtexception_correctly" id="process_warning_using_uncaughtexception_correctly">#</a></span></h4>
<p>Note that <code>'uncaughtException'</code> is a crude mechanism for exception handling
intended to be used only as a last resort. The event <em>should not</em> be used as
an equivalent to <code>On Error Resume Next</code>. Unhandled exceptions inherently mean
that an application is in an undefined state. Attempting to resume application
code without properly recovering from the exception can cause additional
unforeseen and unpredictable issues.</p>
<p>Exceptions thrown from within the event handler will not be caught. Instead the
process will exit with a non-zero exit code and the stack trace will be printed.
This is to avoid infinite recursion.</p>
<p>Attempting to resume normally after an uncaught exception can be similar to
pulling out of the power cord when upgrading a computer — nine out of ten
times nothing happens - but the 10th time, the system becomes corrupted.</p>
<p>The correct use of <code>'uncaughtException'</code> is to perform synchronous cleanup
of allocated resources (e.g. file descriptors, handles, etc) before shutting
down the process. <strong>It is not safe to resume normal operation after
<code>'uncaughtException'</code>.</strong></p>
<p>To restart a crashed application in a more reliable way, whether
<code>'uncaughtException'</code> is emitted or not, an external monitor should be employed
in a separate process to detect application failures and recover or restart as
needed.</p>
<h3>Event: 'unhandledRejection'<span><a class="mark" href="#process_event_unhandledrejection" id="process_event_unhandledrejection">#</a></span></h3>
<div class="api_metadata">
<details class="changelog"><summary>History</summary>
<table>
<tbody><tr><th>Version</th><th>Changes</th></tr>
<tr><td>v7.0.0</td>
<td><p>Not handling <code>Promise</code> rejections is deprecated.</p></td></tr>
<tr><td>v6.6.0</td>
<td><p>Unhandled <code>Promise</code> rejections will now emit a process warning.</p></td></tr>
<tr><td>v1.4.1</td>
<td><p><span>Added in: v1.4.1</span></p></td></tr>
</tbody></table>
</details>
</div>
<p>The <code>'unhandledRejection'</code> event is emitted whenever a <code>Promise</code> is rejected and
no error handler is attached to the promise within a turn of the event loop.
When programming with Promises, exceptions are encapsulated as "rejected
promises". Rejections can be caught and handled using <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch"><code>promise.catch()</code></a> and
are propagated through a <code>Promise</code> chain. The <code>'unhandledRejection'</code> event is
useful for detecting and keeping track of promises that were rejected whose
rejections have not yet been handled.</p>
<p>The listener function is called with the following arguments:</p>
<ul>
<li><code>reason</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> The object with which the promise was rejected
(typically an <a href="errors.html#errors_class_error"><code>Error</code></a> object).</li>
<li><code>p</code> the <code>Promise</code> that was rejected.</li>
</ul>
<pre><code class="language-js">process.on(<span class="hljs-string">'unhandledRejection'</span>, (reason, p) => {
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'Unhandled Rejection at:'</span>, p, <span class="hljs-string">'reason:'</span>, reason);
<span class="hljs-comment">// application specific logging, throwing an error, or other logic here</span>
});
somePromise.then(<span class="hljs-function">(<span class="hljs-params">res</span>) =></span> {
<span class="hljs-keyword">return</span> reportToUser(<span class="hljs-built_in">JSON</span>.pasre(res)); <span class="hljs-comment">// note the typo (`pasre`)</span>
}); <span class="hljs-comment">// no `.catch()` or `.then()`</span></code></pre>
<p>The following will also trigger the <code>'unhandledRejection'</code> event to be
emitted:</p>
<pre><code class="language-js"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">SomeResource</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-comment">// Initially set the loaded status to a rejected promise</span>
<span class="hljs-keyword">this</span>.loaded = <span class="hljs-built_in">Promise</span>.reject(<span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">'Resource not yet loaded!'</span>));
}
<span class="hljs-keyword">const</span> resource = <span class="hljs-keyword">new</span> SomeResource();
<span class="hljs-comment">// no .catch or .then on resource.loaded for at least a turn</span></code></pre>
<p>In this example case, it is possible to track the rejection as a developer error
as would typically be the case for other <code>'unhandledRejection'</code> events. To
address such failures, a non-operational
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch"><code>.catch(() => { })</code></a> handler may be attached to
<code>resource.loaded</code>, which would prevent the <code>'unhandledRejection'</code> event from
being emitted. Alternatively, the <a href="#process_event_rejectionhandled"><code>'rejectionHandled'</code></a> event may be used.</p>
<h3>Event: 'warning'<span><a class="mark" href="#process_event_warning" id="process_event_warning">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v6.0.0</span>
</div>
<ul>
<li>
<p><code>warning</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> Key properties of the warning are:</p>
<ul>
<li><code>name</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The name of the warning. <strong>Default:</strong> <code>'Warning'</code>.</li>
<li><code>message</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> A system-provided description of the warning.</li>
<li><code>stack</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> A stack trace to the location in the code where the warning
was issued.</li>
</ul>
</li>
</ul>
<p>The <code>'warning'</code> event is emitted whenever Node.js emits a process warning.</p>
<p>A process warning is similar to an error in that it describes exceptional
conditions that are being brought to the user's attention. However, warnings
are not part of the normal Node.js and JavaScript error handling flow.
Node.js can emit warnings whenever it detects bad coding practices that could
lead to sub-optimal application performance, bugs, or security vulnerabilities.</p>
<pre><code class="language-js">process.on(<span class="hljs-string">'warning'</span>, (warning) => {
<span class="hljs-built_in">console</span>.warn(warning.name); <span class="hljs-comment">// Print the warning name</span>
<span class="hljs-built_in">console</span>.warn(warning.message); <span class="hljs-comment">// Print the warning message</span>
<span class="hljs-built_in">console</span>.warn(warning.stack); <span class="hljs-comment">// Print the stack trace</span>
});</code></pre>
<p>By default, Node.js will print process warnings to <code>stderr</code>. The <code>--no-warnings</code>
command-line option can be used to suppress the default console output but the
<code>'warning'</code> event will still be emitted by the <code>process</code> object.</p>
<p>The following example illustrates the warning that is printed to <code>stderr</code> when
too many listeners have been added to an event:</p>
<pre><code class="language-txt">$ node
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> (node:38638) MaxListenersExceededWarning: Possible EventEmitter memory leak
detected. 2 foo listeners added. Use emitter.setMaxListeners() to increase limit</code></pre>
<p>In contrast, the following example turns off the default warning output and
adds a custom handler to the <code>'warning'</code> event:</p>
<pre><code class="language-txt">$ node --no-warnings
> const p = process.on('warning', (warning) => console.warn('Do not do that!'));
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> Do not do that!</code></pre>
<p>The <code>--trace-warnings</code> command-line option can be used to have the default
console output for warnings include the full stack trace of the warning.</p>
<p>Launching Node.js using the <code>--throw-deprecation</code> command line flag will
cause custom deprecation warnings to be thrown as exceptions.</p>
<p>Using the <code>--trace-deprecation</code> command line flag will cause the custom
deprecation to be printed to <code>stderr</code> along with the stack trace.</p>
<p>Using the <code>--no-deprecation</code> command line flag will suppress all reporting
of the custom deprecation.</p>
<p>The <code>*-deprecation</code> command line flags only affect warnings that use the name
<code>'DeprecationWarning'</code>.</p>
<h4>Emitting custom warnings<span><a class="mark" href="#process_emitting_custom_warnings" id="process_emitting_custom_warnings">#</a></span></h4>
<p>See the <a href="#process_process_emitwarning_warning_type_code_ctor"><code>process.emitWarning()</code></a> method for issuing
custom or application-specific warnings.</p>
<h3>Signal Events<span><a class="mark" href="#process_signal_events" id="process_signal_events">#</a></span></h3>
<p>Signal events will be emitted when the Node.js process receives a signal. Please
refer to <a href="http://man7.org/linux/man-pages/man7/signal.7.html"><code>signal(7)</code></a> for a listing of standard POSIX signal names such as
<code>'SIGINT'</code>, <code>'SIGHUP'</code>, etc.</p>
<p>The signal handler will receive the signal's name (<code>'SIGINT'</code>,
<code>'SIGTERM'</code>, etc.) as the first argument.</p>
<p>The name of each event will be the uppercase common name for the signal (e.g.
<code>'SIGINT'</code> for <code>SIGINT</code> signals).</p>
<pre><code class="language-js"><span class="hljs-comment">// Begin reading from stdin so the process does not exit.</span>
process.stdin.resume();
process.on(<span class="hljs-string">'SIGINT'</span>, () => {
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">'Received SIGINT. Press Control-D to exit.'</span>);
});
<span class="hljs-comment">// Using a single function to handle multiple signals</span>
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">handle</span>(<span class="hljs-params">signal</span>) </span>{
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Received <span class="hljs-subst">${signal}</span>`</span>);
}
process.on(<span class="hljs-string">'SIGINT'</span>, handle);
process.on(<span class="hljs-string">'SIGTERM'</span>, handle);</code></pre>
<ul>
<li><code>'SIGUSR1'</code> is reserved by Node.js to start the <a href="debugger.html">debugger</a>. It's possible to
install a listener but doing so might interfere with the debugger.</li>
<li><code>'SIGTERM'</code> and <code>'SIGINT'</code> have default handlers on non-Windows platforms that
reset the terminal mode before exiting with code <code>128 + signal number</code>. If one
of these signals has a listener installed, its default behavior will be
removed (Node.js will no longer exit).</li>
<li><code>'SIGPIPE'</code> is ignored by default. It can have a listener installed.</li>
<li><code>'SIGHUP'</code> is generated on Windows when the console window is closed, and on
other platforms under various similar conditions. See <a href="http://man7.org/linux/man-pages/man7/signal.7.html"><code>signal(7)</code></a>. It can have a
listener installed, however Node.js will be unconditionally terminated by
Windows about 10 seconds later. On non-Windows platforms, the default
behavior of <code>SIGHUP</code> is to terminate Node.js, but once a listener has been
installed its default behavior will be removed.</li>
<li><code>'SIGTERM'</code> is not supported on Windows, it can be listened on.</li>
<li><code>'SIGINT'</code> from the terminal is supported on all platforms, and can usually be
generated with <code><Ctrl>+C</code> (though this may be configurable). It is not
generated when terminal raw mode is enabled.</li>
<li><code>'SIGBREAK'</code> is delivered on Windows when <code><Ctrl>+<Break></code> is pressed, on
non-Windows platforms it can be listened on, but there is no way to send or
generate it.</li>
<li><code>'SIGWINCH'</code> is delivered when the console has been resized. On Windows, this
will only happen on write to the console when the cursor is being moved, or
when a readable tty is used in raw mode.</li>
<li><code>'SIGKILL'</code> cannot have a listener installed, it will unconditionally
terminate Node.js on all platforms.</li>
<li><code>'SIGSTOP'</code> cannot have a listener installed.</li>
<li><code>'SIGBUS'</code>, <code>'SIGFPE'</code>, <code>'SIGSEGV'</code> and <code>'SIGILL'</code>, when not raised
artificially using <a href="http://man7.org/linux/man-pages/man2/kill.2.html"><code>kill(2)</code></a>, inherently leave the process in a state from
which it is not safe to attempt to call JS listeners. Doing so might lead to
the process hanging in an endless loop, since listeners attached using
<code>process.on()</code> are called asynchronously and therefore unable to correct the
underlying problem.</li>
</ul>
<p>Windows does not support sending signals, but Node.js offers some emulation
with <a href="#process_process_kill_pid_signal"><code>process.kill()</code></a>, and <a href="child_process.html#child_process_subprocess_kill_signal"><code>subprocess.kill()</code></a>. Sending signal <code>0</code> can
be used to test for the existence of a process. Sending <code>SIGINT</code>, <code>SIGTERM</code>,
and <code>SIGKILL</code> cause the unconditional termination of the target process.</p>
<h2>process.abort()<span><a class="mark" href="#process_process_abort" id="process_process_abort">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.7.0</span>
</div>
<p>The <code>process.abort()</code> method causes the Node.js process to exit immediately and
generate a core file.</p>
<p>This feature is not available in <a href="worker_threads.html#worker_threads_class_worker"><code>Worker</code></a> threads.</p>
<h2>process.allowedNodeEnvironmentFlags<span><a class="mark" href="#process_process_allowednodeenvironmentflags" id="process_process_allowednodeenvironmentflags">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v10.10.0</span>
</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set" class="type"><Set></a></li>
</ul>
<p>The <code>process.allowedNodeEnvironmentFlags</code> property is a special,
read-only <code>Set</code> of flags allowable within the <a href="cli.html#cli_node_options_options"><code>NODE_OPTIONS</code></a>
environment variable.</p>
<p><code>process.allowedNodeEnvironmentFlags</code> extends <code>Set</code>, but overrides
<code>Set.prototype.has</code> to recognize several different possible flag
representations. <code>process.allowedNodeEnvironmentFlags.has()</code> will
return <code>true</code> in the following cases:</p>
<ul>
<li>Flags may omit leading single (<code>-</code>) or double (<code>--</code>) dashes; e.g.,
<code>inspect-brk</code> for <code>--inspect-brk</code>, or <code>r</code> for <code>-r</code>.</li>
<li>Flags passed through to V8 (as listed in <code>--v8-options</code>) may replace
one or more <em>non-leading</em> dashes for an underscore, or vice-versa;
e.g., <code>--perf_basic_prof</code>, <code>--perf-basic-prof</code>, <code>--perf_basic-prof</code>,
etc.</li>
<li>Flags may contain one or more equals (<code>=</code>) characters; all
characters after and including the first equals will be ignored;
e.g., <code>--stack-trace-limit=100</code>.</li>
<li>Flags <em>must</em> be allowable within <a href="cli.html#cli_node_options_options"><code>NODE_OPTIONS</code></a>.</li>
</ul>
<p>When iterating over <code>process.allowedNodeEnvironmentFlags</code>, flags will
appear only <em>once</em>; each will begin with one or more dashes. Flags
passed through to V8 will contain underscores instead of non-leading
dashes:</p>
<pre><code class="language-js">process.allowedNodeEnvironmentFlags.forEach(<span class="hljs-function">(<span class="hljs-params">flag</span>) =></span> {
<span class="hljs-comment">// -r</span>
<span class="hljs-comment">// --inspect-brk</span>
<span class="hljs-comment">// --abort_on_uncaught_exception</span>
<span class="hljs-comment">// ...</span>
});</code></pre>
<p>The methods <code>add()</code>, <code>clear()</code>, and <code>delete()</code> of
<code>process.allowedNodeEnvironmentFlags</code> do nothing, and will fail
silently.</p>
<p>If Node.js was compiled <em>without</em> <a href="cli.html#cli_node_options_options"><code>NODE_OPTIONS</code></a> support (shown in
<a href="#process_process_config"><code>process.config</code></a>), <code>process.allowedNodeEnvironmentFlags</code> will
contain what <em>would have</em> been allowable.</p>
<h2>process.arch<span><a class="mark" href="#process_process_arch" id="process_process_arch">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.5.0</span>
</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
</ul>
<p>The <code>process.arch</code> property returns a string identifying the operating system
CPU architecture for which the Node.js binary was compiled.</p>
<p>The current possible values are: <code>'arm'</code>, <code>'arm64'</code>, <code>'ia32'</code>, <code>'mips'</code>,
<code>'mipsel'</code>, <code>'ppc'</code>, <code>'ppc64'</code>, <code>'s390'</code>, <code>'s390x'</code>, <code>'x32'</code>, and <code>'x64'</code>.</p>
<pre><code class="language-js"><span class="hljs-built_in">console</span>.log(<span class="hljs-string">`This processor architecture is <span class="hljs-subst">${process.arch}</span>`</span>);</code></pre>
<h2>process.argv<span><a class="mark" href="#process_process_argv" id="process_process_argv">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.1.27</span>
</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a></li>
</ul>
<p>The <code>process.argv</code> property returns an array containing the command line
arguments passed when the Node.js process was launched. The first element will
be <a href="#process_process_execpath"><code>process.execPath</code></a>. See <code>process.argv0</code> if access to the original value of
<code>argv[0]</code> is needed. The second element will be the path to the JavaScript
file being executed. The remaining elements will be any additional command line
arguments.</p>
<p>For example, assuming the following script for <code>process-args.js</code>:</p>
<pre><code class="language-js"><span class="hljs-comment">// print process.argv</span>
process.argv.forEach(<span class="hljs-function">(<span class="hljs-params">val, index</span>) =></span> {
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`<span class="hljs-subst">${index}</span>: <span class="hljs-subst">${val}</span>`</span>);
});</code></pre>
<p>Launching the Node.js process as:</p>
<pre><code class="language-console">$ node process-args.js one two=three four</code></pre>
<p>Would generate the output:</p>
<pre><code class="language-text">0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: four</code></pre>
<h2>process.argv0<span><a class="mark" href="#process_process_argv0" id="process_process_argv0">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v6.4.0</span>
</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
</ul>
<p>The <code>process.argv0</code> property stores a read-only copy of the original value of
<code>argv[0]</code> passed when Node.js starts.</p>
<pre><code class="language-console">$ bash -c 'exec -a customArgv0 ./node'
> process.argv[0]
'/Volumes/code/external/node/out/Release/node'
> process.argv0
'customArgv0'</code></pre>
<h2>process.channel<span><a class="mark" href="#process_process_channel" id="process_process_channel">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v7.1.0</span>
</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
</ul>
<p>If the Node.js process was spawned with an IPC channel (see the
<a href="child_process.html">Child Process</a> documentation), the <code>process.channel</code>
property is a reference to the IPC channel. If no IPC channel exists, this
property is <code>undefined</code>.</p>
<h2>process.chdir(directory)<span><a class="mark" href="#process_process_chdir_directory" id="process_process_chdir_directory">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.1.17</span>
</div>
<ul>
<li><code>directory</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
</ul>
<p>The <code>process.chdir()</code> method changes the current working directory of the
Node.js process or throws an exception if doing so fails (for instance, if
the specified <code>directory</code> does not exist).</p>
<pre><code class="language-js"><span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Starting directory: <span class="hljs-subst">${process.cwd()}</span>`</span>);
<span class="hljs-keyword">try</span> {
process.chdir(<span class="hljs-string">'/tmp'</span>);
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`New directory: <span class="hljs-subst">${process.cwd()}</span>`</span>);
} <span class="hljs-keyword">catch</span> (err) {
<span class="hljs-built_in">console</span>.error(<span class="hljs-string">`chdir: <span class="hljs-subst">${err}</span>`</span>);
}</code></pre>
<p>This feature is not available in <a href="worker_threads.html#worker_threads_class_worker"><code>Worker</code></a> threads.</p>
<h2>process.config<span><a class="mark" href="#process_process_config" id="process_process_config">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.7.7</span>
</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
</ul>
<p>The <code>process.config</code> property returns an <code>Object</code> containing the JavaScript
representation of the configure options used to compile the current Node.js
executable. This is the same as the <code>config.gypi</code> file that was produced when
running the <code>./configure</code> script.</p>
<p>An example of the possible output looks like:</p>
<!-- eslint-skip -->
<pre><code class="language-js">{
<span class="hljs-attr">target_defaults</span>:
{ <span class="hljs-attr">cflags</span>: [],
<span class="hljs-attr">default_configuration</span>: <span class="hljs-string">'Release'</span>,
<span class="hljs-attr">defines</span>: [],
<span class="hljs-attr">include_dirs</span>: [],
<span class="hljs-attr">libraries</span>: [] },
<span class="hljs-attr">variables</span>:
{
<span class="hljs-attr">host_arch</span>: <span class="hljs-string">'x64'</span>,
<span class="hljs-attr">node_install_npm</span>: <span class="hljs-string">'true'</span>,
<span class="hljs-attr">node_prefix</span>: <span class="hljs-string">''</span>,
<span class="hljs-attr">node_shared_cares</span>: <span class="hljs-string">'false'</span>,
<span class="hljs-attr">node_shared_http_parser</span>: <span class="hljs-string">'false'</span>,
<span class="hljs-attr">node_shared_libuv</span>: <span class="hljs-string">'false'</span>,
<span class="hljs-attr">node_shared_zlib</span>: <span class="hljs-string">'false'</span>,
<span class="hljs-attr">node_use_dtrace</span>: <span class="hljs-string">'false'</span>,
<span class="hljs-attr">node_use_openssl</span>: <span class="hljs-string">'true'</span>,
<span class="hljs-attr">node_shared_openssl</span>: <span class="hljs-string">'false'</span>,
<span class="hljs-attr">strict_aliasing</span>: <span class="hljs-string">'true'</span>,
<span class="hljs-attr">target_arch</span>: <span class="hljs-string">'x64'</span>,
<span class="hljs-attr">v8_use_snapshot</span>: <span class="hljs-string">'true'</span>
}
}</code></pre>
<p>The <code>process.config</code> property is <strong>not</strong> read-only and there are existing
modules in the ecosystem that are known to extend, modify, or entirely replace
the value of <code>process.config</code>.</p>
<h2>process.connected<span><a class="mark" href="#process_process_connected" id="process_process_connected">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.7.2</span>
</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li>
</ul>
<p>If the Node.js process is spawned with an IPC channel (see the <a href="child_process.html">Child Process</a>
and <a href="cluster.html">Cluster</a> documentation), the <code>process.connected</code> property will return
<code>true</code> so long as the IPC channel is connected and will return <code>false</code> after
<code>process.disconnect()</code> is called.</p>
<p>Once <code>process.connected</code> is <code>false</code>, it is no longer possible to send messages
over the IPC channel using <code>process.send()</code>.</p>
<h2>process.cpuUsage([previousValue])<span><a class="mark" href="#process_process_cpuusage_previousvalue" id="process_process_cpuusage_previousvalue">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v6.1.0</span>
</div>
<ul>
<li><code>previousValue</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> A previous return value from calling
<code>process.cpuUsage()</code></li>
<li>
<p>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></p>
<ul>
<li><code>user</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
<li><code>system</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li>
</ul>
</li>
</ul>
<p>The <code>process.cpuUsage()</code> method returns the user and system CPU time usage of
the current process, in an object with properties <code>user</code> and <code>system</code>, whose
values are microsecond values (millionth of a second). These values measure time
spent in user and system code respectively, and may end up being greater than
actual elapsed time if multiple CPU cores are performing work for this process.</p>
<p>The result of a previous call to <code>process.cpuUsage()</code> can be passed as the
argument to the function, to get a diff reading.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> startUsage = process.cpuUsage();
<span class="hljs-comment">// { user: 38579, system: 6986 }</span>
<span class="hljs-comment">// spin the CPU for 500 milliseconds</span>
<span class="hljs-keyword">const</span> now = <span class="hljs-built_in">Date</span>.now();
<span class="hljs-keyword">while</span> (<span class="hljs-built_in">Date</span>.now() - now < <span class="hljs-number">500</span>);
<span class="hljs-built_in">console</span>.log(process.cpuUsage(startUsage));
<span class="hljs-comment">// { user: 514883, system: 11226 }</span></code></pre>
<h2>process.cwd()<span><a class="mark" href="#process_process_cwd" id="process_process_cwd">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.1.8</span>
</div>
<ul>
<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
</ul>
<p>The <code>process.cwd()</code> method returns the current working directory of the Node.js
process.</p>
<pre><code class="language-js"><span class="hljs-built_in">console</span>.log(<span class="hljs-string">`Current directory: <span class="hljs-subst">${process.cwd()}</span>`</span>);</code></pre>
<h2>process.debugPort<span><a class="mark" href="#process_process_debugport" id="process_process_debugport">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.7.2</span>
</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li>
</ul>
<p>The port used by Node.js's debugger when enabled.</p>
<pre><code class="language-js">process.debugPort = <span class="hljs-number">5858</span>;</code></pre>
<h2>process.disconnect()<span><a class="mark" href="#process_process_disconnect" id="process_process_disconnect">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.7.2</span>
</div>
<p>If the Node.js process is spawned with an IPC channel (see the <a href="child_process.html">Child Process</a>
and <a href="cluster.html">Cluster</a> documentation), the <code>process.disconnect()</code> method will close the
IPC channel to the parent process, allowing the child process to exit gracefully
once there are no other connections keeping it alive.</p>
<p>The effect of calling <code>process.disconnect()</code> is that same as calling the parent
process's <a href="child_process.html#child_process_subprocess_disconnect"><code>ChildProcess.disconnect()</code></a>.</p>
<p>If the Node.js process was not spawned with an IPC channel,
<code>process.disconnect()</code> will be <code>undefined</code>.</p>
<h2>process.dlopen(module, filename[, flags])<span><a class="mark" href="#process_process_dlopen_module_filename_flags" id="process_process_dlopen_module_filename_flags">#</a></span></h2>
<div class="api_metadata">
<details class="changelog"><summary>History</summary>
<table>
<tbody><tr><th>Version</th><th>Changes</th></tr>
<tr><td>v9.0.0</td>
<td><p>Added support for the <code>flags</code> argument.</p></td></tr>
<tr><td>v0.1.16</td>
<td><p><span>Added in: v0.1.16</span></p></td></tr>
</tbody></table>
</details>
</div>
<ul>
<li><code>module</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li>
<li><code>filename</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li>
<li><code>flags</code> <a href="os.html#os_dlopen_constants" class="type"><os.constants.dlopen></a> <strong>Default:</strong> <code>os.constants.dlopen.RTLD_LAZY</code></li>
</ul>
<p>The <code>process.dlopen()</code> method allows to dynamically load shared
objects. It is primarily used by <code>require()</code> to load
C++ Addons, and should not be used directly, except in special
cases. In other words, <a href="globals.html#globals_require"><code>require()</code></a> should be preferred over
<code>process.dlopen()</code>, unless there are specific reasons.</p>
<p>The <code>flags</code> argument is an integer that allows to specify dlopen
behavior. See the <a href="os.html#os_dlopen_constants"><code>os.constants.dlopen</code></a> documentation for details.</p>
<p>If there are specific reasons to use <code>process.dlopen()</code> (for instance,
to specify dlopen flags), it's often useful to use <a href="modules.html#modules_require_resolve_request_options"><code>require.resolve()</code></a>
to look up the module's path.</p>
<p>An important drawback when calling <code>process.dlopen()</code> is that the <code>module</code>
instance must be passed. Functions exported by the C++ Addon will be accessible
via <code>module.exports</code>.</p>
<p>The example below shows how to load a C++ Addon, named as <code>binding</code>,
that exports a <code>foo</code> function. All the symbols will be loaded before
the call returns, by passing the <code>RTLD_NOW</code> constant. In this example
the constant is assumed to be available.</p>
<pre><code class="language-js"><span class="hljs-keyword">const</span> os = <span class="hljs-built_in">require</span>(<span class="hljs-string">'os'</span>);
process.dlopen(<span class="hljs-built_in">module</span>, <span class="hljs-built_in">require</span>.resolve(<span class="hljs-string">'binding'</span>),
os.constants.dlopen.RTLD_NOW);
<span class="hljs-built_in">module</span>.exports.foo();</code></pre>
<h2>process.emitWarning(warning[, options])<span><a class="mark" href="#process_process_emitwarning_warning_options" id="process_process_emitwarning_warning_options">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v8.0.0</span>
</div>
<ul>
<li><code>warning</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> The warning to emit.</li>
<li>
<p><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></p>
<ul>
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> When <code>warning</code> is a <code>String</code>, <code>type</code> is the name to use
for the <em>type</em> of warning being emitted. <strong>Default:</strong> <code>'Warning'</code>.</li>
<li><code>code</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> A unique identifier for the warning instance being emitted.</li>
<li><code>ctor</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> When <code>warning</code> is a <code>String</code>, <code>ctor</code> is an optional
function used to limit the generated stack trace. <strong>Default:</strong>
<code>process.emitWarning</code>.</li>
<li><code>detail</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Additional text to include with the error.</li>
</ul>
</li>
</ul>
<p>The <code>process.emitWarning()</code> method can be used to emit custom or application
specific process warnings. These can be listened for by adding a handler to the
<a href="#process_event_warning"><code>'warning'</code></a> event.</p>
<pre><code class="language-js"><span class="hljs-comment">// Emit a warning with a code and additional detail.</span>
process.emitWarning(<span class="hljs-string">'Something happened!'</span>, {
<span class="hljs-attr">code</span>: <span class="hljs-string">'MY_WARNING'</span>,
<span class="hljs-attr">detail</span>: <span class="hljs-string">'This is some additional information'</span>
});
<span class="hljs-comment">// Emits:</span>
<span class="hljs-comment">// (node:56338) [MY_WARNING] Warning: Something happened!</span>
<span class="hljs-comment">// This is some additional information</span></code></pre>
<p>In this example, an <code>Error</code> object is generated internally by
<code>process.emitWarning()</code> and passed through to the
<a href="#process_event_warning"><code>'warning'</code></a> handler.</p>
<pre><code class="language-js">process.on(<span class="hljs-string">'warning'</span>, (warning) => {
<span class="hljs-built_in">console</span>.warn(warning.name); <span class="hljs-comment">// 'Warning'</span>
<span class="hljs-built_in">console</span>.warn(warning.message); <span class="hljs-comment">// 'Something happened!'</span>
<span class="hljs-built_in">console</span>.warn(warning.code); <span class="hljs-comment">// 'MY_WARNING'</span>
<span class="hljs-built_in">console</span>.warn(warning.stack); <span class="hljs-comment">// Stack trace</span>
<span class="hljs-built_in">console</span>.warn(warning.detail); <span class="hljs-comment">// 'This is some additional information'</span>
});</code></pre>
<p>If <code>warning</code> is passed as an <code>Error</code> object, the <code>options</code> argument is ignored.</p>
<h2>process.emitWarning(warning[, type[, code]][, ctor])<span><a class="mark" href="#process_process_emitwarning_warning_type_code_ctor" id="process_process_emitwarning_warning_type_code_ctor">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v6.0.0</span>
</div>
<ul>
<li><code>warning</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> The warning to emit.</li>
<li><code>type</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> When <code>warning</code> is a <code>String</code>, <code>type</code> is the name to use
for the <em>type</em> of warning being emitted. <strong>Default:</strong> <code>'Warning'</code>.</li>
<li><code>code</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> A unique identifier for the warning instance being emitted.</li>
<li><code>ctor</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> When <code>warning</code> is a <code>String</code>, <code>ctor</code> is an optional
function used to limit the generated stack trace. <strong>Default:</strong>
<code>process.emitWarning</code>.</li>
</ul>
<p>The <code>process.emitWarning()</code> method can be used to emit custom or application
specific process warnings. These can be listened for by adding a handler to the
<a href="#process_event_warning"><code>'warning'</code></a> event.</p>
<pre><code class="language-js"><span class="hljs-comment">// Emit a warning using a string.</span>
process.emitWarning(<span class="hljs-string">'Something happened!'</span>);
<span class="hljs-comment">// Emits: (node: 56338) Warning: Something happened!</span></code></pre>
<pre><code class="language-js"><span class="hljs-comment">// Emit a warning using a string and a type.</span>
process.emitWarning(<span class="hljs-string">'Something Happened!'</span>, <span class="hljs-string">'CustomWarning'</span>);
<span class="hljs-comment">// Emits: (node:56338) CustomWarning: Something Happened!</span></code></pre>
<pre><code class="language-js">process.emitWarning(<span class="hljs-string">'Something happened!'</span>, <span class="hljs-string">'CustomWarning'</span>, <span class="hljs-string">'WARN001'</span>);
<span class="hljs-comment">// Emits: (node:56338) [WARN001] CustomWarning: Something happened!</span></code></pre>
<p>In each of the previous examples, an <code>Error</code> object is generated internally by
<code>process.emitWarning()</code> and passed through to the <a href="#process_event_warning"><code>'warning'</code></a>
handler.</p>
<pre><code class="language-js">process.on(<span class="hljs-string">'warning'</span>, (warning) => {
<span class="hljs-built_in">console</span>.warn(warning.name);
<span class="hljs-built_in">console</span>.warn(warning.message);
<span class="hljs-built_in">console</span>.warn(warning.code);
<span class="hljs-built_in">console</span>.warn(warning.stack);
});</code></pre>
<p>If <code>warning</code> is passed as an <code>Error</code> object, it will be passed through to the
<code>'warning'</code> event handler unmodified (and the optional <code>type</code>,
<code>code</code> and <code>ctor</code> arguments will be ignored):</p>
<pre><code class="language-js"><span class="hljs-comment">// Emit a warning using an Error object.</span>
<span class="hljs-keyword">const</span> myWarning = <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">'Something happened!'</span>);
<span class="hljs-comment">// Use the Error name property to specify the type name</span>
myWarning.name = <span class="hljs-string">'CustomWarning'</span>;
myWarning.code = <span class="hljs-string">'WARN001'</span>;
process.emitWarning(myWarning);
<span class="hljs-comment">// Emits: (node:56338) [WARN001] CustomWarning: Something happened!</span></code></pre>
<p>A <code>TypeError</code> is thrown if <code>warning</code> is anything other than a string or <code>Error</code>
object.</p>
<p>Note that while process warnings use <code>Error</code> objects, the process warning
mechanism is <strong>not</strong> a replacement for normal error handling mechanisms.</p>
<p>The following additional handling is implemented if the warning <code>type</code> is
<code>'DeprecationWarning'</code>:</p>
<ul>
<li>If the <code>--throw-deprecation</code> command-line flag is used, the deprecation
warning is thrown as an exception rather than being emitted as an event.</li>
<li>If the <code>--no-deprecation</code> command-line flag is used, the deprecation
warning is suppressed.</li>
<li>If the <code>--trace-deprecation</code> command-line flag is used, the deprecation
warning is printed to <code>stderr</code> along with the full stack trace.</li>
</ul>
<h3>Avoiding duplicate warnings<span><a class="mark" href="#process_avoiding_duplicate_warnings" id="process_avoiding_duplicate_warnings">#</a></span></h3>
<p>As a best practice, warnings should be emitted only once per process. To do
so, it is recommended to place the <code>emitWarning()</code> behind a simple boolean
flag as illustrated in the example below:</p>
<pre><code class="language-js"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">emitMyWarning</span>(<span class="hljs-params"></span>) </span>{
<span class="hljs-keyword">if</span> (!emitMyWarning.warned) {
emitMyWarning.warned = <span class="hljs-literal">true</span>;
process.emitWarning(<span class="hljs-string">'Only warn once!'</span>);
}
}
emitMyWarning();
<span class="hljs-comment">// Emits: (node: 56339) Warning: Only warn once!</span>
emitMyWarning();
<span class="hljs-comment">// Emits nothing</span></code></pre>
<h2>process.env<span><a class="mark" href="#process_process_env" id="process_process_env">#</a></span></h2>
<div class="api_metadata">
<details class="changelog"><summary>History</summary>
<table>
<tbody><tr><th>Version</th><th>Changes</th></tr>
<tr><td>v10.0.0</td>
<td><p>Implicit conversion of variable value to string is deprecated.</p></td></tr>
<tr><td>v0.1.27</td>