Exit status: Difference between revisions

Latest revision as of 15:06, 19 December 2025

Template:Short description Script error: No such module "redirect hatnote". Script error: No such module "Redirect hatnote". Template:Use dmy dates Template:Use list-defined references

In computing, the exit status (also exit code or exit value) of a terminated process is an integer number that is made available to its parent process (or caller). In DOS, this may be referred to as an errorlevel.

When computer programs are executed, the operating system creates an abstract entity called a process in which the book-keeping for that program is maintained. In multitasking operating systems such as Unix or Linux, new processes can be created by active processes. The process that spawns another is called a parent process, while those created are child processes. Child processes run concurrently with the parent process. The technique of spawning child processes is used to delegate some work to a child process when there is no reason to stop the execution of the parent. When the child finishes executing, it exits by calling the exit system call. This system call facilitates passing the exit status code back to the parent, which can retrieve this value using the wait system call.

Semantics

The parent and the child can have an understanding about the meaning of the exit statuses. For example, it is common programming practice for a child process to return (exit with) zero to the parent signifying success. Apart from this return value from the child, other information like how the process exited, either normally or by a signal may also be available to the parent process.

The specific set of codes returned is unique to the program that sets it. Typically it indicates success or failure. The value of the code returned by the function or program may indicate a specific cause of failure. On many systems, the higher the value, the more severe the cause of the error.^[1] Alternatively, each bit may indicate a different condition, with these being evaluated by the or operator together to give the final value; for example, fsck does this.

Sometimes, if the codes are designed with this purpose in mind, they can be used directly as a branch index upon return to the initiating program to avoid additional tests.

AmigaOS

In AmigaOS, MorphOS and AROS, four levels are defined:

Shell and scripts

Shell scripts typically execute commands and capture their exit statuses.

For the shell's purposes, a command which exits with a zero exit status has succeeded. A nonzero exit status indicates failure. This seemingly counter-intuitive scheme is used so there is one well-defined way to indicate success and a variety of ways to indicate various failure modes. When a command is terminated by a signal whose number is N, a shell sets the variable $? to a value greater than 128. Most shells use Template:Mono, while ksh93 uses Template:Mono.

If a command is not found, the shell should return a status of Template:Mono. If a command is found but is not executable, the return status should be Template:Mono.^[2] Note that this is not the case for all shells.

If a command fails because of an error during expansion or redirection, the exit status is greater than zero.

C language

The C programming language allows programs exiting or returning from the main function to signal success or failure by returning an integer, or returning the macros EXIT_SUCCESS and EXIT_FAILURE. On Unix-like systems these are equal to 0 and 1 respectively.^[3] A C program may also use the exit() function specifying the integer status or exit macro as the first parameter.

The return value from main is passed to the exit function, which for values zero, EXIT_SUCCESS or EXIT_FAILURE may translate it to "an implementation defined form" of successful termination or unsuccessful termination.Script error: No such module "Unsubst".

Apart from zero and the macros EXIT_SUCCESS and EXIT_FAILURE, the C standard does not define the meaning of return codes. Rules for the use of return codes vary on different platforms (see the platform-specific sections).

DOS

In DOS terminology, an errorlevel is an integer exit code returned by an executable program or subroutine. Errorlevels typically range from Template:Mono to Template:Mono.^[4]^[5]^[6]^[7] In DOS there are only 256 error codes available, but DR DOS 6.0 and higher support 16-bit error codes at least in Template:Mono.^[6] With 4DOS and DR-DOS Template:Mono, exit codes (in batchjobs) can be set by [[EXIT (DOS command)|Template:Mono]]^[6] and (in Template:Mono) through Template:Mono.^[6]

Exit statuses are often captured by batch programs through [[IF ERRORLEVEL (DOS command)|Template:Mono]] commands.^[4]^[6] Multiuser DOS supports a reserved environment variable %ERRORLVL% which gets automatically updated on return from applications. Template:Mono under DR-DOS 7.02 and higher supports a similar pseudo-environment variable Template:Mono as well as Template:Mono. In Template:Mono, DR DOS 6.0 and higher supports [[ONERROR (CONFIG.SYS directive)|Template:Mono]] to test the load status and return code of device drivers and the exit code of programs.^[6]

Java

In Java, any method can call System.exit(int status), unless a security manager does not permit it. This will terminate the currently running Java Virtual Machine. "The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination."^[8]

OpenVMS

In OpenVMS, success is indicated by odd values and failure by even values. The value is a 32-bit integer with sub-fields: control bits, facility number, message number and severity. Severity values are divided between success (Success, Informational) and failure (Warning, Error, Fatal).^[9]

Plan 9

In Plan 9's C, exit status is indicated by a string passed to the Template:Mono function, and [[Entry point#C and C++|function Template:Mono]] is [[Void type|type Template:Mono]].

POSIX

In Unix and other POSIX-compatible systems, the parent process can retrieve the exit status of a child process using the wait() family of system calls defined in POSIX header <wait.h>.^[10] Of these, the waitid()^[11] call retrieves the full exit status, but the older wait() and waitpid()^[12] calls retrieve only the least significant 8 bits of the exit status.

The wait() and waitpid() interfaces set a status value of type int packed as a bitfield with various types of child termination information. If the child terminated by exiting (as determined by the WIFEXITED() macro; the usual alternative being that it died from an uncaught signal), SUS specifies that the low-order 8 bits of the exit status can be retrieved from the status value using the WEXITSTATUS() macro.

In the waitid() system call (added with SUSv1), the child exit status and other information are no longer in a bitfield but in the structure of type siginfo_t.^[13]

POSIX-compatible systems typically use a convention of zero for success and nonzero for error.^[14] Some conventions have developed as to the relative meanings of various error codes; for example GNU recommend that codes with the high bit set be reserved for serious errors.^[3]

BSD-derived OS's have defined an extensive set of preferred interpretations: Meanings for 15 status codes 64 through 78 are defined in POSIX header <sysexits.h>.^[15] These historically derive from sendmail and other message transfer agents, but they have since found use in many other programs.^[16] It has been deprecated and its use is discouraged.^[15]

The Advanced Bash-Scripting Guide has some information on the meaning of non-0 exit status codes.^[17]

Windows

Microsoft Windows uses 32-bit unsigned integers as exit codes,^[18]^[19] although the command interpreter treats them as signed.^[20]

Exit codes are directly referenced, for example, by the command line interpreter CMD.exe in the errorlevel terminology inherited from DOS. The .NET Framework processes and the Windows PowerShell refer to it as the ExitCode property of the Process object.

References

↑ Script error: No such module "citation/CS1".
↑ Script error: No such module "citation/CS1".
↑ ^a ^b Script error: No such module "citation/CS1".
↑ ^a ^b Script error: No such module "citation/CS1". [1] [2] Template:Webarchive (NB. BATTIPS.TXT is part of MPDOSTIP.ZIP. The provided link points to a HTML-converted older version of the BATTIPS.TXT file.) [3]
↑ Script error: No such module "citation/CS1".
↑ ^a ^b ^c ^d ^e ^f Script error: No such module "citation/CS1". (NB. NWDOSTIP.TXT is a comprehensive work on Novell DOS 7 and OpenDOS 7.01, including the description of many undocumented features and internals. The provided link points to a HTML-converted version of the file, which is part of the MPDOSTIP.ZIP collection.) [4]
↑ Script error: No such module "citation/CS1".
↑ Script error: No such module "citation/CS1".
↑ Script error: No such module "citation/CS1".
↑ sys_wait.h – Base Definitions Reference, The Single UNIX Specification, Version 5 from The Open Group
↑ waitid – System Interfaces Reference, The Single UNIX Specification, Version 5 from The Open Group
↑ wait – System Interfaces Reference, The Single UNIX Specification, Version 5 from The Open Group
↑ Script error: No such module "citation/CS1".
↑ Script error: No such module "citation/CS1".
↑ ^a ^b sysexits(3): preferable exit codes for programs – FreeBSD Library Functions Manual
↑ Google search for «"sysexits.h" site:github.com» reports «About 3,540 results»; retrieved 2013-02-21.
↑ Script error: No such module "citation/CS1".
↑ Script error: No such module "citation/CS1".
↑ Script error: No such module "citation/CS1".
↑ Script error: No such module "citation/CS1".

[Woude_2007-1] Script error: No such module "citation/CS1".

[OpenGroup_2015-2] Script error: No such module "citation/CS1".

[glibc-3] Script error: No such module "citation/CS1".

[Paul_1997_BATTIPS-4] Script error: No such module "citation/CS1". [1] [2] Template:Webarchive (NB. BATTIPS.TXT is part of MPDOSTIP.ZIP. The provided link points to a HTML-converted older version of the BATTIPS.TXT file.) [3]

[FD_2003_Errorlevel-5] Script error: No such module "citation/CS1".

[Paul_1997_NWDOSTIP-6] ↑ ^a ^b ^c ^d ^e ^f Script error: No such module "citation/CS1". (NB. NWDOSTIP.TXT is a comprehensive work on Novell DOS 7 and OpenDOS 7.01, including the description of many undocumented features and internals. The provided link points to a HTML-converted version of the file, which is part of the MPDOSTIP.ZIP collection.) [4]

[Allen_2005-7] Script error: No such module "citation/CS1".

[Java-8] Script error: No such module "citation/CS1".

[OpenVMS-9] Script error: No such module "citation/CS1".

[BD_syswait-10] sys_wait.h – Base Definitions Reference, The Single UNIX Specification, Version 5 from The Open Group

[SH_waitid-11] waitid – System Interfaces Reference, The Single UNIX Specification, Version 5 from The Open Group

[SH_wait-12] wait – System Interfaces Reference, The Single UNIX Specification, Version 5 from The Open Group

[OpenGroup-13] Script error: No such module "citation/CS1".

[ExitStatus-14] Script error: No such module "citation/CS1".

[FreeBSD-15] sysexits(3): preferable exit codes for programs – FreeBSD Library Functions Manual

[sysexits-16] Google search for «"sysexits.h" site:github.com» reports «About 3,540 results»; retrieved 2013-02-21.

[SpecialMeanings-17] Script error: No such module "citation/CS1".

[ExitProcess-18] Script error: No such module "citation/CS1".

[GetExitCodeProcess-19] Script error: No such module "citation/CS1".

[ExitCodesBig-20] Script error: No such module "citation/CS1".

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]

[15]

[16]

[17]

[18]

[19]

[20]

@@ Line 18: / Line 18: @@
 ===AmigaOS===
 In [[AmigaOS]], [[MorphOS]] and [[AROS]], four levels are defined:
-* OK 0
+# {{mono|OK 0}}
-* WARN 5
+# {{mono|WARN 5}}
-* ERROR 10
+# {{mono|ERROR 10}}
-* FAILURE 20
+# {{mono|FAILURE 20}}
 ===Shell and scripts===
 [[Shell script]]s typically execute commands and capture their exit statuses.
-For the shell's purposes, a command which exits with a zero exit status has succeeded. A nonzero exit status indicates failure. This seemingly counter-intuitive scheme is used so there is one well-defined way to indicate success and a variety of ways to indicate various failure modes. When a command is terminated by a signal whose number is N, a shell sets the variable $? to a value greater than 128. Most shells use 128+N, while ksh93 uses 256+N.
+For the shell's purposes, a command which exits with a zero exit status has succeeded. A nonzero exit status indicates failure. This seemingly counter-intuitive scheme is used so there is one well-defined way to indicate success and a variety of ways to indicate various failure modes. When a command is terminated by a signal whose number is {{code|N}}, a shell sets the variable {{code|$?}} to a value greater than 128. Most shells use {{mono|128+N}}, while ksh93 uses {{mono|256+N}}.
-If a command is not found, the shell should return a status of 127. If a command is found but is not executable, the return status should be 126.<ref name="OpenGroup_2015"/> Note that this is not the case for all shells.
+If a command is not found, the shell should return a status of {{mono|127}}. If a command is found but is not executable, the return status should be {{mono|126}}.<ref name="OpenGroup_2015"/> Note that this is not the case for all shells.
 If a command fails because of an error during expansion or redirection, the exit status is greater than zero.
@@ Line 40: / Line 40: @@
 ===DOS===
-In DOS terminology, an '''errorlevel''' is an [[integer]] exit [[code]] returned by an [[executable|executable program]] or [[subroutine]]. Errorlevels typically range from 0 to 255.<ref name="Paul_1997_BATTIPS"/><ref name="FD_2003_Errorlevel"/><ref name="Paul_1997_NWDOSTIP"/><ref name="Allen_2005"/> In [[DOS]] there are only 256 error codes available, but [[DR&nbsp;DOS 6.0]] and higher support 16-bit error codes at least in [[CONFIG.SYS]].<ref name="Paul_1997_NWDOSTIP"/> With [[4DOS]] and DR-DOS [[COMMAND.COM]], exit codes (in batchjobs) can be set by [[EXIT (DOS command)|EXIT ''n'']]<!-- MS-DOS/PC DOS COMMAND.COM does not support the optional parameter, just EXIT without any arguments --><ref name="Paul_1997_NWDOSTIP"/> and (in CONFIG.SYS) through [[ERROR (CONFIG.SYS directive)|ERROR=''n'']]<!-- and a number of other more specialized directives -->.<ref name="Paul_1997_NWDOSTIP"/>
+In DOS terminology, an '''errorlevel''' is an [[integer]] exit [[code]] returned by an [[executable|executable program]] or [[subroutine]]. Errorlevels typically range from {{mono|0}} to {{mono|255}}.<ref name="Paul_1997_BATTIPS"/><ref name="FD_2003_Errorlevel"/><ref name="Paul_1997_NWDOSTIP"/><ref name="Allen_2005"/> In [[DOS]] there are only 256 error codes available, but [[DR&nbsp;DOS 6.0]] and higher support 16-bit error codes at least in {{mono|[[CONFIG.SYS]]}}.<ref name="Paul_1997_NWDOSTIP"/> With [[4DOS]] and DR-DOS {{mono|[[COMMAND.COM]]}}, exit codes (in batchjobs) can be set by [[EXIT (DOS command)|{{mono|EXIT ''n''}}]]<!-- MS-DOS/PC DOS COMMAND.COM does not support the optional parameter, just EXIT without any arguments --><ref name="Paul_1997_NWDOSTIP"/> and (in {{mono|CONFIG.SYS}}) through {{mono|[[ERROR (CONFIG.SYS directive)|ERROR=''n'']]}}<!-- and a number of other more specialized directives -->.<ref name="Paul_1997_NWDOSTIP"/>
-Exit statuses are often captured by [[batch file|batch programs]] through [[IF ERRORLEVEL (DOS command)|IF ERRORLEVEL]] commands.<ref name="Paul_1997_BATTIPS"/><ref name="Paul_1997_NWDOSTIP"/> [[Multiuser DOS]] supports a reserved <!-- true -->[[environment variable]] [[%ERRORLVL%]] which gets automatically updated on return from applications. COMMAND.COM under [[DR-DOS 7.02]] and higher supports a similar [[pseudo-environment variable]] %ERRORLVL% as well as [[%ERRORLEVEL%]].<!-- MS-DOS and PC DOS do not, only Windows does! --> In CONFIG.SYS, DR&nbsp;DOS 6.0 and higher supports [[ONERROR (CONFIG.SYS directive)|ONERROR]] to test the load status and return code of device drivers and the exit code of programs.<ref name="Paul_1997_NWDOSTIP"/>
+Exit statuses are often captured by [[batch file|batch programs]] through [[IF ERRORLEVEL (DOS command)|{{mono|IF ERRORLEVEL}}]] commands.<ref name="Paul_1997_BATTIPS"/><ref name="Paul_1997_NWDOSTIP"/> [[Multiuser DOS]] supports a reserved <!-- true -->[[environment variable]] [[%ERRORLVL%]] which gets automatically updated on return from applications. {{mono|COMMAND.COM}} under [[DR-DOS 7.02]] and higher supports a similar [[pseudo-environment variable]] {{mono|%ERRORLVL%}} as well as {{mono|[[%ERRORLEVEL%]]}}.<!-- MS-DOS and PC DOS do not, only Windows does! --> In {{mono|CONFIG.SYS}}, DR&nbsp;DOS 6.0 and higher supports [[ONERROR (CONFIG.SYS directive)|{{mono|ONERROR}}]] to test the load status and return code of device drivers and the exit code of programs.<ref name="Paul_1997_NWDOSTIP"/>
 ===Java===
@@ Line 51: / Line 51: @@
 ===Plan 9===
-In Plan 9's C, exit status is indicated by a string passed to the ''exits'' function, and [[Entry point#C and C++|function main]] is [[Void type|type void]].
+In Plan 9's C, exit status is indicated by a string passed to the {{mono|exits()}} function, and [[Entry point#C and C++|function {{mono|main()}}]] is [[Void type|type {{mono|void}}]].
 ===POSIX===
-In [[Unix]] and other [[POSIX|POSIX-compatible systems]], the parent process can retrieve the exit status of a child process using the <code>[[Wait (system call)|wait()]]</code> family of system calls defined in [[wait.h]].<ref name="BD_syswait"/>  Of these, the <code>waitid()</code><ref name="SH_waitid"/> call retrieves the full exit status, but the older <code>wait()</code> and <code>waitpid()</code><ref name="SH_wait"/> calls retrieve only the least significant 8 bits of the exit status.
+In [[Unix]] and other [[POSIX|POSIX-compatible systems]], the parent process can retrieve the exit status of a child process using the <code>[[Wait (system call)|wait()]]</code> family of system calls defined in [[C POSIX library|POSIX header]] {{code|<wait.h>}}.<ref name="BD_syswait"/>  Of these, the <code>waitid()</code><ref name="SH_waitid"/> call retrieves the full exit status, but the older <code>wait()</code> and <code>waitpid()</code><ref name="SH_wait"/> calls retrieve only the least significant 8 bits of the exit status.
 The <code>wait()</code> and <code>waitpid()</code> interfaces set a ''status'' value of type <code>int</code> packed as a [[bitfield]] with various types of child termination information.  If the child terminated by exiting (as determined by the <code>WIFEXITED()</code> macro; the usual alternative being that it died from an uncaught [[signal (computing)|signal]]), [[Single UNIX Specification|SUS]] specifies that the low-order 8 bits of the exit status can be retrieved from the status value using the <code>WEXITSTATUS()</code> macro.
@@ Line 62: / Line 62: @@
 POSIX-compatible systems typically use a convention of zero for success and nonzero for error.<ref name="ExitStatus"/>  Some conventions have developed as to the relative meanings of various error codes; for example GNU recommend that codes with the high bit set be reserved for serious errors.<ref name="glibc"/>
-BSD-derived OS's have defined an extensive set of preferred interpretations: Meanings for 15 status codes 64 through 78 are defined in [[sysexits.h]].<ref name="FreeBSD"/> These historically derive from [[sendmail]] and other [[message transfer agent]]s, but they have since found use in many other programs.<ref name="sysexits"/>  It has been deprecated and its use	is discouraged.<ref name="FreeBSD"/>
+BSD-derived OS's have defined an extensive set of preferred interpretations: Meanings for 15 status codes 64 through 78 are defined in POSIX header {{code|<sysexits.h>}}.<ref name="FreeBSD"/> These historically derive from [[sendmail]] and other [[message transfer agent]]s, but they have since found use in many other programs.<ref name="sysexits"/>  It has been deprecated and its use is discouraged.<ref name="FreeBSD"/>
 The Advanced Bash-Scripting Guide has some information on the meaning of non-0 exit status codes.<ref name="SpecialMeanings"/>
@@ Line 77: / Line 77: @@
 ==References==
-{{reflist|refs=
+<references>
 <ref name="Paul_1997_NWDOSTIP">{{cite book |title=NWDOS-TIPs&nbsp;— Tips & Tricks rund um Novell DOS 7, mit Blick auf undokumentierte Details, Bugs und Workarounds |work=MPDOSTIP |author-first=Matthias R. |author-last=Paul |date=1997-07-30 |orig-date=1994-05-01 |edition=3 |version=Release 157 |language=de |url=http://www.antonis.de/dos/dos-tuts/mpdostip/html/nwdostip.htm |access-date=2014-08-06 |url-status=live |archive-url=https://web.archive.org/web/20161104235829/http://www.antonis.de/dos/dos-tuts/mpdostip/html/nwdostip.htm |archive-date=2016-11-04}} (NB. NWDOSTIP.TXT is a comprehensive work on [[Novell DOS 7]] and [[OpenDOS 7.01]], including the description of many undocumented features and internals. The provided link points to a HTML-converted version of the file, which is part of the <code>MPDOSTIP.ZIP</code><!-- still named TIPS_MP.ZIP between 1991 and 1996-11 --> collection.) [https://web.archive.org/web/20190601152204/https://www.sac.sk/download/text/mpdostip.zip<!-- A yet older version 155 from 1997-05-13 of the 1997-07-15 distribution archive. -->]</ref>
 <ref name="Paul_1997_BATTIPS">{{cite book |title=BATTIPs&nbsp;— Tips & Tricks zur Programmierung von Batchjobs |at=7: ERRORLEVEL abfragen |work=MPDOSTIP |author-first=Matthias R. |author-last=Paul |date=1997-05-01 |orig-date=1993-10-01 |language=de |url=http://www.antonis.de/dos/batchtut/battips/index.htm#7 |access-date=2017-08-23 |url-status=live |archive-url=https://web.archive.org/web/20170823191411/http://www.antonis.de/dos/batchtut/battips/index.htm |archive-date=2017-08-23 }} [https://www.auersoft.eu/soft/by-others/dos-exitcodes-de.html] [https://www.auersoft.eu/soft/by-others/dos-exitcodes-en.html] {{Webarchive|url=https://archive.today/20170911103337/https://www.auersoft.eu/soft/by-others/dos-exitcodes-en.html |date=2017-09-11  }} (NB. BATTIPS.TXT is part of MPDOSTIP.ZIP. The provided link points to a HTML-converted older version of the BATTIPS.TXT file.) [https://web.archive.org/web/20190601152204/https://www.sac.sk/download/text/mpdostip.zip<!-- A yet older version 155 from 1997-05-13 of the 1997-07-15 distribution archive. -->]</ref>
@@ Line 98: / Line 99: @@
 <ref name="ExitCodesBig">{{cite web |url=https://stackoverflow.com/questions/179565/exitcodes-bigger-than-255-possible |title=ExitCodes bigger than 255, possible? |access-date=2009-09-28}}</ref>
 <ref name="Woude_2007">{{cite web |url=http://www.robvanderwoude.com/errorlevel.php |title=Errorlevels |publisher=Rob van der Woude's Scripting Pages |access-date=2007-08-26}}</ref>
-}}
+</references>
 {{DEFAULTSORT:Exit Status}}
 [[Category:Process (computing)]]

Exit status: Difference between revisions

Latest revision as of 15:06, 19 December 2025

Contents

Semantics

AmigaOS

Shell and scripts

C language

DOS

Java

OpenVMS

Plan 9

POSIX

Windows

See also

References

Navigation menu

Exit status: Difference between revisions

Latest revision as of 15:06, 19 December 2025

Semantics

AmigaOS

Shell and scripts

C language

DOS

Java

OpenVMS

Plan 9

POSIX

Windows

See also

References

Navigation menu

Search