man3head/sysexits.h.3head

   1 '\" t
   2 .\" Copyright (c) 1996 Joerg Wunsch
   3 .\" Copyright (c) 2022 Alejandro Colomar <alx@kernel.org>
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" SPDX-License-Identifier: BSD-2-Clause
   8 .\"
   9 .\" Rewritten for the Linux man-pages by Alejandro Colomar
  10 .\"
  11 .TH sysexits.h 3head (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 sysexits.h \- exit codes for programs
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <sysexits.h>
  20 .fi
  21 .TS
  22 lB2 lB2 l1 lX.
  23 #define EX_OK   0       /*      T{
  24 successful termination */
  25 T}
  26 .PP
  27 #define EX__BASE        64      /*      T{
  28 base value for error messages */
  29 T}
  30 .PP
  31 #define EX_USAGE        64      /*      T{
  32 command line usage error */
  33 T}
  34 #define EX_DATAERR      65      /*      T{
  35 data format error */
  36 T}
  37 #define EX_NOINPUT      66      /*      T{
  38 cannot open input */
  39 T}
  40 #define EX_NOUSER       67      /*      T{
  41 addressee unknown */
  42 T}
  43 #define EX_NOHOST       68      /*      T{
  44 host name unknown */
  45 T}
  46 #define EX_UNAVAILABLE  69      /*      T{
  47 service unavailable */
  48 T}
  49 #define EX_SOFTWARE     70      /*      T{
  50 internal software error */
  51 T}
  52 #define EX_OSERR        71      /*      T{
  53 system error (e.g., can't fork) */
  54 T}
  55 #define EX_OSFILE       72      /*      T{
  56 critical OS file missing */
  57 T}
  58 #define EX_CANTCREAT    73      /*      T{
  59 can't create (user) output file */
  60 T}
  61 #define EX_IOERR        74      /*      T{
  62 input/output error */
  63 T}
  64 #define EX_TEMPFAIL     75      /*      T{
  65 temp failure; user is invited to retry */
  66 T}
  67 #define EX_PROTOCOL     76      /*      T{
  68 remote error in protocol */
  69 T}
  70 #define EX_NOPERM       77      /*      T{
  71 permission denied */
  72 T}
  73 #define EX_CONFIG       78      /*      T{
  74 configuration error */
  75 T}
  76 .PP
  77 .T&
  78 lB2 l2 l1 lX.
  79 #define EX__MAX ...     /*      T{
  80 maximum listed value */
  81 T}
  82 .TE
  83 .SH DESCRIPTION
  84 A few programs exit with the following error codes.
  85 .PP
  86 The successful exit is always indicated by a status of
  87 .BR 0 ,
  88 or
  89 .B EX_OK
  90 (equivalent to
  91 .B EXIT_SUCCESS
  92 from
  93 .IR <stdlib.h> ).
  94 Error numbers begin at
  95 .B EX__BASE
  96 to reduce the possibility of clashing with other exit statuses
  97 that random programs may already return.
  98 The meaning of the code is approximately as follows:
  99 .TP
 100 .B EX_USAGE
 101 The command was used incorrectly,
 102 e.g.,
 103 with the wrong number of arguments,
 104 a bad flag,
 105 bad syntax in a parameter,
 106 or whatever.
 107 .TP
 108 .B EX_DATAERR
 109 The input data was incorrect in some way.
 110 This should only be used for user's data and not system files.
 111 .TP
 112 .B EX_NOINPUT
 113 An input file (not a system file) did not exist or was not readable.
 114 This could also include errors like "No message" to a mailer
 115 (if it cared to catch it).
 116 .TP
 117 .B EX_NOUSER
 118 The user specified did not exist.
 119 This might be used for mail addresses or remote logins.
 120 .TP
 121 .B EX_NOHOST
 122 The host specified did not exist.
 123 This is used in mail addresses or network requests.
 124 .TP
 125 .B EX_UNAVAILABLE
 126 A service is unavailable.
 127 This can occur if a support program or file does not exist.
 128 This can also be used as a catch-all message
 129 when something you wanted to do doesn't work, but you don't know why.
 130 .TP
 131 .B EX_SOFTWARE
 132 An internal software error has been detected.
 133 This should be limited to non-operating system related errors if possible.
 134 .TP
 135 .B EX_OSERR
 136 An operating system error has been detected.
 137 This is intended to be used for such things as
 138 "cannot fork",
 139 "cannot create pipe",
 140 or the like.
 141 It includes things like
 142 .BR getuid (2)
 143 returning a user that does not exist in the
 144 .BR passwd (5)
 145 file.
 146 .TP
 147 .B EX_OSFILE
 148 Some system file
 149 (e.g.,
 150 .IR /etc/passwd ,
 151 .IR /etc/utmp ,
 152 etc.)
 153 does not exist,
 154 cannot be opened,
 155 or has some sort of error (e.g., syntax error).
 156 .TP
 157 .B EX_CANTCREAT
 158 A (user specified) output file cannot be created.
 159 .TP
 160 .B EX_IOERR
 161 An error occurred while doing I/O on some file.
 162 .TP
 163 .B EX_TEMPFAIL
 164 Temporary failure,
 165 indicating something that is not really an error.
 166 For example that a mailer could not create a connection,
 167 and the request should be reattempted later.
 168 .TP
 169 .B EX_PROTOCOL
 170 The remote system returned something that
 171 was "not possible" during a protocol exchange.
 172 .TP
 173 .B EX_OSFILE
 174 You did not have sufficient permission to perform the operation.
 175 This is not intended for file system problems,
 176 which should use
 177 .B EX_NOINPUT
 178 or
 179 .BR EX_CANTCREAT ,
 180 but rather for higher level permissions.
 181 .TP
 182 .B EX_CONFIG
 183 Something was found in an unconfigured or misconfigured state.
 184 .PP
 185 The numerical values corresponding to the symbolical ones
 186 are given in parenthesis for easy reference.
 187 .SH STANDARDS
 188 Not in POSIX.1.
 189 Present on the BSDs.
 190 The
 191 .I <sysexits.h>
 192 file appeared in 4.0BSD for use by the deliverymail utility,
 193 later renamed to
 194 .BR sendmail (8).
 195 .SH BUGS
 196 The choice of an appropriate exit value is often ambiguous.
 197 .SH SEE ALSO
 198 .BR err (3),
 199 .BR error (3),
 200 .BR exit (3)