github.com/cockroachdb/cockroachdb-parser@v0.23.3-0.20240213214944-911057d40c9a/pkg/cli/exit/doc.go (about)

     1  // Copyright 2020 The Cockroach Authors.
     2  //
     3  // Use of this software is governed by the Business Source License
     4  // included in the file licenses/BSL.txt.
     5  //
     6  // As of the Change Date specified in that file, in accordance with
     7  // the Business Source License, use of this software will be governed
     8  // by the Apache License, Version 2.0, included in the file
     9  // licenses/APL.txt.
    10  
    11  // Package exit encapsulates calls to os.Exit to control the
    12  // production of process exit status codes.
    13  //
    14  // Its goal is to ensure that all possible exit codes produced
    15  // by the 'cockroach' process upon termination are documented.
    16  // It achieves this by providing a type exit.Code and requiring that
    17  // all possible values come from constructors in the package (see
    18  // codes.go). A linter ensures that no direct call to os.Exit() can be
    19  // present elsewhere.
    20  //
    21  // Note that due to the limited range of unix exit codes, it is not
    22  // possible to map all possible error situations inside a CockroachDB
    23  // server to a unique exit code.
    24  // This is why the main mechanism to explain the cause of a process
    25  // termination must remain the logging subsystem.
    26  //
    27  // The introduction of discrete exit codes here is thus meant to
    28  // merely complement logging, in those cases where logging is unable
    29  // to detail the reason why the process is terminating; for example:
    30  //
    31  // - before logging is initialized (e.g. during command-line parsing)
    32  // - when a logging operation fails.
    33  //
    34  // For client commands, the situation is different: there are much
    35  // fewer different exit situations, so we could envision discrete
    36  // error codes for them. Additionally, different client commands
    37  // can reuse the same numeric codes for different error situations,
    38  // when they do not overlap.
    39  //
    40  // This package accommodates this as follows:
    41  //
    42  //   - exit codes common to all commands should be allocated
    43  //     incrementally starting from the last defined common error
    44  //     in codes.go.
    45  //
    46  //   - exit codes specific to one command should be allocated downwards
    47  //     starting from 125.
    48  package exit