exit

README

Semantic Exit Codes

Usage

Go

os.Exit(exit.Forbidden) // The user isn't permitted to perform this action
os.Exit(exit.Unavailable) // An API this program consumes isn't available

Rust

use semantic_exit::{exit, Code};

exit(Code::Forbidden);
exit(Code::Unavailable);

Python

import exit

exit.Code.Forbidden.exit()
exit.Code.Unavailable.exit()

See the complete list of exit codes.

About

Conventionally, exiting a program with zero indicates success while nonzero indicates failure.

os.Exit(0) // success
os.Exit(1) // failure

But the system call exit accepts values between 0 and 255, leaving 254 different ways of expressing failure.

This library's goals are to define exit codes that are:

1. Broadly applicable to heterogenous Command Line tools
2. Easy to partition into user errors and system errors

It defines codes in two unreserved ranges: 80-99 for user errors and 100-119 for software or system errors.

The Codes

Exit Code	Name	Meaning
0	OK	The program exited successfully.
1	NotOK	The program exited unsuccessfully but gives no extra context as to what the failure was.
80	UsageError	The program exited unsuccessfully because it was was used incorrectly. (e.g. a required argument was omitted or an invalid value was supplied for a flag.)
81	UnknownSubcommand	The program exited unsuccessfully because an unrecognized subcommand was invoked. (Used by CLI multi-tools.)
82	RequirementNotMet	The program exited unsuccessfully because a prerequisite of it wasn't met.
83	Forbidden	The program exited unsuccessfully because the user isn't authorized to perform the requested action.
84	MovedPermanently	The program exited unsuccessfully because it has been migrated to a new location.
100	InternalError	The program exited unsuccessfully because of a problem in its own code. (Used instead of 1 when the problem is known to be with the program's code or dependencies.)
101	Unavailable	The program exited unsuccessfully because a service it depends on was not available. (e.g. A local daemon or remote service did not respond, a connection was closed unexpectedly, an HTTP service responded with 503.)

Reserved Codes and Prior Art

• Values above 128 are reserved for signals. (When a program is terminated with a signal, its exit code is 128 + the signal's numeric value. When you terminate a program with Ctrl C, for example, you send it the signal SIGINT — whose value is 2 — and the program exits with 130.)
• Bash reserves 2, 126, and 127.
• sysexits.h defines 64-78. The sysexits.h codes were originally defined for sendmail but have been used many places since. (Compare Semantic Exit Codes to sysexits.h codes)

Documentation

Overview

Package exit defines semantic exit codes which may be used by Command Line tools to aid in debugging and instrumentation.

This package defines exit codes in two ranges. Exit Codes 80-99 indicate a user error of some sort. Exit Codes 100-119 indicate software or system error of some sort.

Index

• Variables
• func IsSignal(code Code) bool
• func IsSoftwareError(code Code) bool
• func IsUserError(code Code) bool
• func Wrap(err error, code Code) error
• func WrapIf(err error, code Code) error
• type Code
  • func FromError(err error) Code
  • func FromSignal(signal syscall.Signal) Code
• type Error
  • func (e Error) Error() string
  • func (e Error) ExitCode() int
  • func (e Error) Unwrap() error

Variables

var (
	ErrNotOK             = Error{Code: NotOK}
	ErrUsageError        = Error{Code: UsageError}
	ErrUnknownSubcommand = Error{Code: UnknownSubcommand}
	ErrRequirementNotMet = Error{Code: RequirementNotMet}
	ErrForbidden         = Error{Code: Forbidden}
	ErrMovedPermanently  = Error{Code: MovedPermanently}
	ErrInternalError     = Error{Code: InternalError}
	ErrUnavailable       = Error{Code: Unavailable}
)

Functions

func IsSignal

func IsSignal(code Code) bool

IsSignal reports whether an exit code is derived from a signal. It returns true if the code is in the range 128-255 and false if not. It also returns true if the code is -1 because ProcessState.ExitCode() may return -1 if the process was terminated by a signal.

func IsSoftwareError

func IsSoftwareError(code Code) bool

IsSoftwareError reports whether an exit code is a software error. It returns true if the code is in the range 100-119 and false if not.

func IsUserError

func IsUserError(code Code) bool

IsUserError reports whether an exit code is a user error. It returns true if the code is in the range 80-99 and false if not.

func Wrap

func Wrap(err error, code Code) error

func WrapIf

func WrapIf(err error, code Code) error

Types

type Code

type Code = int

Code is the exit code that is passed to the system call `exit` when the program terminates. Conventionally, the value zero indicates success and all other values (1-255) indicate failure.

const (
	// OK indicates that the program exited successfully.
	OK Code = 0

	// NotOK indicates that the program exited unsuccessfully
	// but gives no extra context as to what the failure was.
	NotOK Code = 1
)

const (
	// UsageError indicates that the program exited unsuccessfully
	// because it was used incorrectly.
	//
	// Examples: a required argument was omitted or an invalid value
	// was supplied for a flag.
	UsageError Code = 80

	// UnknownSubcommand indicates that the program exited unsuccessfully
	// because an unrecognized subcommand was invoked.
	//
	// This is intended for CLI multi-tools. When you run a command that
	// doesn't exist from the shell, the shell exits 127. This is distinct
	// from that value in that the command itself exists but the subcommand
	// does not (e.g. `git nope` could exit 81).
	UnknownSubcommand Code = 81

	// RequirementNotMet indicates that the program exited unsuccessfully
	// because a precondition wasn't satisfied.
	//
	// Examples: the user must be on a VPN before using the program or have
	// a minimum version of some other software installed.
	RequirementNotMet Code = 82

	// Forbidden indicates that the program exited unsuccessfully
	// because the user isn't authorized to perform the requested action.
	Forbidden Code = 83

	// MovedPermanently indicates that the program exited unsuccessfully
	// because it has been migrated to a new location.
	MovedPermanently Code = 84
)

Exit Codes 80-99 are reserved for user errors.

const (
	// InternalError indicates that the program exited unsuccessfully
	// because of a problem in its own code.
	//
	// Used instead of 1 when the problem is known to be with the program's
	// code or dependencies.
	InternalError Code = 100

	// Unavailable indicates that the program exited unsuccessfully
	// because a service it depends on was not available.
	//
	// Examples: A local daemon or remote service did not respond, a connection
	// was closed unexpectedly, an HTTP service responded with 503.
	Unavailable Code = 101
)

Exit Codes 100-119 are reserved for software or system errors.

func FromError

func FromError(err error) Code

func FromSignal

func FromSignal(signal syscall.Signal) Code

FromSignal returns the exit code that corresponds to when a program exits in response to a signal.

type Error

type Error struct {
	Code  Code
	Cause error
}

func (Error) Error

func (e Error) Error() string

func (Error) ExitCode

func (e Error) ExitCode() int

func (Error) Unwrap

func (e Error) Unwrap() error