Exit status

Last updated

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.

Contents

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 128+N, while ksh93 uses 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. [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.[ citation needed ]

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 0 to 255. [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 CONFIG.SYS. [6] With 4DOS and DR-DOS COMMAND.COM, exit codes (in batchjobs) can be set by EXIT n [6] and (in CONFIG.SYS) through ERROR=n. [6]

Exit statuses are often captured by batch programs through IF ERRORLEVEL commands. [4] [6] Multiuser DOS supports a reserved 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%. In CONFIG.SYS, DR DOS 6.0 and higher supports ONERROR 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 exits function, and function main is type void.

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 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 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.

See also

Related Research Articles

On Unix and Unix-like computer operating systems, a zombie process or defunct process is a process that has completed execution but still has an entry in the process table: it is a process in the "terminated state". This occurs for the child processes, where the entry is still needed to allow the parent process to read its child's exit status: once the exit status is read via the wait system call, the zombie's entry is removed from the process table and it is said to be "reaped". A child process initially becomes a zombie, only then being removed from the resource table. Under normal system operation, zombies are immediately waited on by their parent and then reaped by the system. Processes that stay zombies for a long time are usually an error and can cause a resource leak. Generally, the only kernel resource they occupy is the process table entry, their process ID. However, zombies can also hold buffers open, consuming memory. Zombies can hold handles to file descriptors, which prevents the space for those files from being available to the filesystem. This effect can be seen by a difference between du and df. While du may show a large amount of free disk space, df will show a full partition. If the zombies are not cleaned, this can fill the root partition and crash the system.

A Berkeley (BSD) socket is an application programming interface (API) for Internet domain sockets and Unix domain sockets, used for inter-process communication (IPC). It is commonly implemented as a library of linkable modules. It originated with the 4.2BSD Unix operating system, which was released in 1983.

<span class="mw-page-title-main">C shell</span> Unix shell

The C shell is a Unix shell created by Bill Joy while he was a graduate student at University of California, Berkeley in the late 1970s. It has been widely distributed, beginning with the 2BSD release of the Berkeley Software Distribution (BSD) which Joy first distributed in 1978. Other early contributors to the ideas or the code were Michael Ubell, Eric Allman, Mike O'Brien and Jim Kulp.

In computer programming, standard streams are preconnected input and output communication channels between a computer program and its environment when it begins execution. The three input/output (I/O) connections are called standard input (stdin), standard output (stdout) and standard error (stderr). Originally I/O happened via a physically connected system console, but standard streams abstract this. When a command is executed via an interactive shell, the streams are typically connected to the text terminal on which the shell is running, but can be changed with redirection or a pipeline. More generally, a child process inherits the standard streams of its parent process.

In computing, particularly in the context of the Unix operating system and its workalikes, fork is an operation whereby a process creates a copy of itself. It is an interface which is required for compliance with the POSIX and Single UNIX Specification standards. It is usually implemented as a C standard library wrapper to the fork, clone, or other system calls of the kernel. Fork is the primary method of process creation on Unix-like operating systems.

In computing, end-of-file (EOF) is a condition in a computer operating system where no more data can be read from a data source. The data source is usually called a file or stream.

An environment variable is a user-definable value that can affect the way running processes will behave on a computer. Environment variables are part of the environment in which a process runs. For example, a running process can query the value of the TEMP environment variable to discover a suitable location to store temporary files, or the HOME or USERPROFILE variable to find the directory structure owned by the user running the process.

errno.h is a header file in the standard library of the C programming language. It defines macros for reporting and retrieving error conditions using the symbol errno.

<span class="mw-page-title-main">DIGITAL Command Language</span> Command language adopted by several operating systems (OSs)

DIGITAL Command Language (DCL) is the standard command language adopted by many of the operating systems created by Digital Equipment Corporation. DCL had its roots in IAS, TOPS-20, and RT-11 and was implemented as a standard across most of Digital's operating systems, notably RSX-11 and RSTS/E, but took its most powerful form in VAX/VMS. DCL continues to be developed by VSI as part of OpenVMS.

stat (system call) Unix system call

stat is a Unix system call that returns file attributes about an inode. The semantics of stat vary between operating systems. As an example, Unix command ls uses this system call to retrieve information on files that includes:

Signals are standardized messages sent to a running program to trigger specific behavior, such as quitting or error handling. They are a limited form of inter-process communication (IPC), typically used in Unix, Unix-like, and other POSIX-compliant operating systems.

In computer programming, an entry point is the place in a program where the execution of a program begins, and where the program has access to command line arguments.

exit (command) Termination command of many command-line interpreters and scripting languages

In computing, exit is a command used in many operating system command-line shells and scripting languages.

In computing, sigaction is a function API defined by POSIX to give the programmer access to what a program's behavior should be when receiving specific OS signals.

HRESULT is a computer programming data type that represents the completion status of a function.

In computing, exec is a functionality of an operating system that runs an executable file in the context of an already existing process, replacing the previous executable. This act is also referred to as an overlay. It is especially important in Unix-like systems, although it also exists elsewhere. As no new process is created, the process identifier (PID) does not change, but the machine code, data, heap, and stack of the process are replaced by those of the new program.

On many computer operating systems, a computer process terminates its execution by making an exit system call. More generally, an exit in a multithreading environment means that a thread of execution has stopped running. For resource management, the operating system reclaims resources that were used by the process. The process is said to be a dead process after it terminates.

Spawn in computing refers to a function that loads and executes a new child process. The current process may wait for the child to terminate or may continue to execute concurrent computing. Creating a new subprocess requires enough memory in which both the child process and the current program can execute.

In computer operating systems, a process may wait for another process to complete its execution. In most systems, a parent process can create an independently executing child process. The parent process may then issue a wait system call, which suspends the execution of the parent process while the child executes. When the child process terminates, it returns an exit status to the operating system, which is then returned to the waiting parent process. The parent process then resumes execution.

select is a system call and application programming interface (API) in Unix-like and POSIX-compliant operating systems for examining the status of file descriptors of open input/output channels. The select system call is similar to the poll facility introduced in UNIX System V and later operating systems. However, with the c10k problem, both select and poll have been superseded by the likes of kqueue, epoll, /dev/poll and I/O completion ports.

References

  1. ↑ "Errorlevels". Rob van der Woude's Scripting Pages. Retrieved 2007-08-26.
  2. ↑ "Shell command language - Exit Status for commands". The Open Group . Retrieved 2015-07-07.
  3. 1 2 "The GNU C Library Reference Manual 25.6.2: Exit Status". Gnu.org. Retrieved 2012-07-09.
  4. 1 2 Paul, Matthias R. (1997-05-01) [1993-10-01]. BATTIPs — Tips & Tricks zur Programmierung von Batchjobs (in German). 7: ERRORLEVEL abfragen. Archived from the original on 2017-08-23. Retrieved 2017-08-23.{{cite book}}: |work= ignored (help) Archived 2017-09-11 at archive.today (NB. BATTIPS.TXT is part of MPDOSTIP.ZIP. The provided link points to a HTML-converted older version of the BATTIPS.TXT file.)
  5. ↑ Auer, Eric; Paul, Matthias R.; Hall, Jim (2015-12-24) [2003-12-31]. "MS-DOS errorlevels". Archived from the original on 2015-12-24.
  6. 1 2 3 4 5 6 Paul, Matthias R. (1997-07-30) [1994-05-01]. NWDOS-TIPs — Tips & Tricks rund um Novell DOS 7, mit Blick auf undokumentierte Details, Bugs und Workarounds. Release 157 (in German) (3 ed.). Archived from the original on 2016-11-04. Retrieved 2014-08-06.{{cite book}}: |work= ignored (help) (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.)
  7. ↑ Allen, William; Allen, Linda. "Windows 95/98/ME ERRORLEVELs". Archived from the original on 2011-07-07.
  8. ↑ "Java 1.6.0 API". Sun Microsystems . Retrieved 2008-05-06.
  9. ↑ "OpenVMS Format of Return Status Values". H71000.www7.hp.com. Archived from the original on 2012-03-19. Retrieved 2012-07-09.
  10. ↑ sys_wait.h  – Base Definitions Reference, The Single UNIX Specification, Version 4 from The Open Group
  11. ↑ waitid  – System Interfaces Reference, The Single UNIX Specification, Version 4 from The Open Group
  12. ↑ wait  – System Interfaces Reference, The Single UNIX Specification, Version 4 from The Open Group
  13. ↑ "2.4.3 Signal Actions". The Open Group . Retrieved 2019-02-08.
  14. ↑ "Chapter 6. Exit and Exit Status". Faqs.org. Retrieved 2012-07-09.
  15. 1 2 sysexits(3) : preferable exit codes for programs –  FreeBSD Library Functions Manual
  16. ↑ Google search for «"sysexits.h" site:github.com» reports «About 3,540 results»; retrieved 2013-02-21.
  17. ↑ "Exit Codes with Special Meanings".
  18. ↑ "ExitProcess function" . Retrieved 2016-12-16.
  19. ↑ "GetExitCodeProcess function" . Retrieved 2022-04-22.
  20. ↑ "ExitCodes bigger than 255, possible?" . Retrieved 2009-09-28.
This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.