- Feature Name: exit
- Start Date: 2015-03-24
- RFC PR: [rust-lang/rfcs#1011](https://github.com/rust-lang/rfcs/pull/1011)
- Rust Issue: (leave this empty)

# Summary

Add a function to the `std::process` module to exit the process immediately with
a specified exit code.

# Motivation

Currently there is no stable method to exit a program in Rust with a nonzero
exit code without panicking. The current unstable method for doing so is by
using the `exit_status` feature with the `std::env::set_exit_status` function.

This function has not been stabilized as it diverges from the system APIs (there
is no equivalent) and it represents an odd piece of global state for a Rust
program to have. One example of odd behavior that may arise is that if a library
calls `env::set_exit_status`, then the process is not guaranteed to exit with
that status (e.g. Rust was called from C).

The purpose of this RFC is to provide at least one method on the path to
stabilization which will provide a method to exit a process with an arbitrary
exit code.

# Detailed design

The following function will be added to the `std::process` module:

```rust
/// Terminates the current process with the specified exit code.
///
/// This function will never return and will immediately terminate the current
/// process. The exit code is passed through to the underlying OS and will be
/// available for consumption by another process.
///
/// Note that because this function never returns, and that it terminates the
/// process, no destructors on the current stack or any other thread's stack
/// will be run. If a clean shutdown is needed it is recommended to only call
/// this function at a known point where there are no more destructors left
/// to run.
pub fn exit(code: i32) -> !;
```

Implementation-wise this will correspond to the [`exit` function][unix] on unix
and the [`ExitProcess` function][win] on windows.

[unix]: http://pubs.opengroup.org/onlinepubs/000095399/functions/exit.html
[win]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658%28v=vs.85%29.aspx

This function is also not marked `unsafe`, despite the risk of leaking
allocated resources (e.g. destructors may not be run). It is already possible
to safely create memory leaks in Rust, however, (with `Rc` + `RefCell`), so
this is not considered a strong enough threshold to mark the function as
`unsafe`.

# Drawbacks

* This API does not solve all use cases of exiting with a nonzero exit status.
  It is sometimes more convenient to simply return a code from the `main`
  function instead of having to call a separate function in the standard
  library.

# Alternatives

* One alternative would be to stabilize `set_exit_status` as-is today. The
  semantics of the function would be clearly documented to prevent against
  surprises, but it would arguably not prevent all surprises from arising. Some
  reasons for not pursuing this route, however, have been outlined in the
  motivation.

* The `main` function of binary programs could be altered to require an
  `i32` return value. This would greatly lessen the need to stabilize this
  function as-is today as it would be possible to exit with a nonzero code by
  returning a nonzero value from `main`. This is a backwards-incompatible
  change, however.

* The `main` function of binary programs could optionally be typed as `fn() ->
  i32` instead of just `fn()`. This would be a backwards-compatible change, but
  does somewhat add complexity. It may strike some as odd to be able to define
  the `main` function with two different signatures in Rust. Additionally, it's
  likely that the `exit` functionality proposed will be desired regardless of
  whether the main function can return a code or not.

# Unresolved questions

* To what degree should the documentation imply that `rt::at_exit` handlers are
  run? Implementation-wise their execution is guaranteed, but we may not wish
  for this to always be so.
