Documentation
¶
Overview ¶
Package exit maps an error to the status the process should exit with.
influxd historically exited 0 or 1, which tells an init system nothing it can act on: a typo in a config file and a full disk are reported identically, so systemd's Restart=on-failure retries both forever. The codes here answer the one question a supervisor can actually use -- will retrying help? -- by naming the category of the failure.
The vocabulary is sysexits.h (see sysexits.h(3head)), whose 64-78 block is the conventional home for an application's own statuses: it sits inside the 1-125 "standard errors" range and clear of every reserved band (126-127 for the shell, 128-165 for signals, 255 for overflow).
Classify and Code are not the same function ¶
Code never guesses. It reports a status only for an error that was explicitly given one with WithCode, and returns CodeGeneric for everything else. That is what keeps this package's reach equal to its wiring: a command that has not opted in exits 1 exactly as it always has, rather than acquiring a sysexits status by accident.
Classify does guess, from the OS-level cause underneath the error. It is meant to run once, at the boundary where a failure leaves the subsystem that produced it, with the result pinned by WithCode. Pinning is what makes the answer stable: a caller that joins the startup error with a later teardown error would otherwise have a second, differently-caused chain for a late Classify to walk into, and could report the teardown's category as the startup's.
Which statuses influxd emits ¶
Every sysexits value is defined here, because a partial copy of a standard header invites a later collision. influxd emits a subset: CodeUsage, CodeDataErr, CodeNoInput, CodeUnavailable, CodeSoftware, CodeOSErr, CodeCantCreate, CodeIOErr, CodeTempFail, CodeNoPerm and CodeConfig. CodeNoUser, CodeNoHost, CodeOSFile and CodeProtocol are defined and unused -- influxd has no addressee, no remote host lookup, no /etc-style system file dependency and no protocol peer at startup.
See EXIT_CODES.md at the repository root for the operator-facing table.
Index ¶
Constants ¶
const ( // CodeOK is a successful run: startup completed and teardown completed. CodeOK = 0 // CodeGeneric is an error carrying no category. It is what Code reports // for an error nothing pinned a status to, and is the status influxd has // always exited with on failure. CodeGeneric = 1 CodeUsage = 64 // EX_USAGE: the command line was wrong. CodeDataErr = 65 // EX_DATAERR: input data was wrong. CodeNoInput = 66 // EX_NOINPUT: an input path is missing or unreadable. CodeNoUser = 67 // EX_NOUSER: the named user does not exist. CodeNoHost = 68 // EX_NOHOST: the named host does not exist. CodeSoftware = 70 // EX_SOFTWARE: an internal error with no OS-level cause. CodeOSErr = 71 // EX_OSERR: an operating system error, such as resource exhaustion. CodeOSFile = 72 // EX_OSFILE: a system file is missing or broken. CodeCantCreate = 73 // EX_CANTCREAT: an output file cannot be created or extended. CodeIOErr = 74 // EX_IOERR: an I/O error occurred. CodeTempFail = 75 // EX_TEMPFAIL: a temporary failure; retrying may succeed. CodeProtocol = 76 // EX_PROTOCOL: a remote peer violated a protocol. CodeNoPerm = 77 // EX_NOPERM: permission was denied. CodeConfig = 78 // EX_CONFIG: something is configured wrongly. )
Process exit statuses.
CodeOK and CodeGeneric are the two influxd has always used. The rest are the sysexits.h block, with the EX_ prefix dropped to read as Go identifiers; Name maps each back to its C macro name.
Variables ¶
This section is empty.
Functions ¶
func Classify ¶
Classify chooses an exit status for err from the cause underneath it.
The order is: a status already pinned anywhere in the chain wins, because a site that knew its own category outranks a guess made from a syscall; then the platform's errno table, consulted for every errno in the tree rather than only the first; then the portable io/fs and context sentinels; then CodeSoftware for a failure with no OS-level cause to point at.
The sentinel checks run after the errno table and are not redundant with it. On Windows the errno values are Win32 and Winsock numbers rather than the POSIX ones, so a file error that the table cannot place still resolves through fs.ErrPermission or fs.ErrNotExist, which the standard library maps per platform.
The categories, stated once so call sites need not re-derive them: a path-shaped problem is CodeNoInput, a permission problem is CodeNoPerm, a space problem is CodeCantCreate, and a value the operator declared being wrong is CodeConfig -- the last of which has no OS-level signature and so is always pinned at its site rather than found here.
func Code ¶
Code returns the exit status pinned to err, CodeOK if err is nil, and CodeGeneric if nothing in the chain pinned one.
It performs no classification of its own. An error that was never given a status exits 1, which is what influxd has always done, so wiring this into a process's exit path changes nothing for the paths that have not opted in.
errors.As walks a tree built by errors.Join depth-first and left to right, so when a joined error carries more than one pinned status the leftmost wins. Callers that join a primary failure with a secondary one should put the primary first, which is also the order that produces the right message.
func Name ¶
Name returns the sysexits macro name for a status, or "Unknown code: <n>", with n the status itself, if the status is not one this package defines.
func WithCode ¶
WithCode returns err with code pinned to it as the process exit status.
The result's message is err's message unchanged, and errors.Is and errors.As still reach err and everything it wraps. WithCode(code, nil) is nil, so it is safe to apply to a result that may not be an error.
Pin a status at a site that knows something Classify cannot infer -- a sentinel or a formatted message with no OS-level cause beneath it -- or at the boundary where a failure leaves the component that produced it, to fix the answer before the error is joined with any other.
Source Files