# Exit Codes Reference

## Standard Exit Codes (必须遵循)

| Code | Constant | Meaning | Use Case |
|------|----------|---------|----------|
| 0 | `E_SUCCESS` | Success | Normal completion |
| 1 | `E_GENERAL` | General error | Catch-all for unspecified errors |
| 2 | `E_ARGS` | Invalid arguments | Wrong number, invalid format, unknown option |
| 3 | `E_DEPS` | Missing dependency | Required command not found |
| 4 | `E_PERM` | Permission denied | Cannot read/write/execute required resource |
| 5 | `E_NOTFOUND` | Resource not found | File, directory, or resource doesn't exist |

## Extended Exit Codes (按需选用)

| Code | Constant | Meaning | Use Case |
|------|----------|---------|----------|
| 6 | `E_CONFIG` | Configuration error | Invalid or missing config file |
| 7 | `E_NETWORK` | Network error | Connection failed, timeout |
| 8 | `E_TIMEOUT` | Operation timeout | Command exceeded time limit |
| 9 | `E_LOCK` | Lock acquisition failed | Cannot acquire file/process lock |
| 10 | `E_STATE` | Invalid state | Precondition not met |

## Reserved Exit Codes (不要使用)

| Code | Reserved By | Meaning |
|------|-------------|---------|
| 126 | Shell | Command found but not executable |
| 127 | Shell | Command not found |
| 128 | Shell | Invalid exit code (exit only takes 0-255) |
| 128+N | Shell | Fatal signal N (e.g., 130 = SIGINT, 137 = SIGKILL, 143 = SIGTERM) |
| 255 | Shell | Exit code out of range |

## Declaration Pattern

```bash
# Exit codes (declare at top, after shebang)
readonly E_SUCCESS=0
readonly E_GENERAL=1
readonly E_ARGS=2
readonly E_DEPS=3
readonly E_PERM=4
readonly E_NOTFOUND=5
readonly E_CONFIG=6
readonly E_NETWORK=7
readonly E_TIMEOUT=8
readonly E_LOCK=9
readonly E_STATE=10
```

## Usage Examples

```bash
# Argument validation
[[ $# -ge 1 ]] || die "Missing required argument" "$E_ARGS"

# Dependency check
command -v jq &>/dev/null || die "jq is required" "$E_DEPS"

# Permission check
[[ -w "$output_dir" ]] || die "Cannot write to: $output_dir" "$E_PERM"

# File existence
[[ -f "$config_file" ]] || die "Config not found: $config_file" "$E_NOTFOUND"

# Network error (with retry)
curl -sf "$url" || die "Failed to fetch: $url" "$E_NETWORK"
```

## Exit Code Ranges by Category

| Range | Category | Description |
|-------|----------|-------------|
| 0 | Success | All operations completed |
| 1-10 | Application errors | Defined by script |
| 11-63 | Reserved | For future application use |
| 64-78 | BSD sysexits.h | Standard Unix exit codes |
| 79-125 | Reserved | For future use |
| 126-255 | Shell reserved | Do not use |

## sysexits.h Reference (可选，用于更严格的标准化)

| Code | Name | Meaning |
|------|------|---------|
| 64 | EX_USAGE | Command line usage error |
| 65 | EX_DATAERR | Data format error |
| 66 | EX_NOINPUT | Cannot open input |
| 67 | EX_NOUSER | Addressee unknown |
| 68 | EX_NOHOST | Host name unknown |
| 69 | EX_UNAVAILABLE | Service unavailable |
| 70 | EX_SOFTWARE | Internal software error |
| 71 | EX_OSERR | System error |
| 72 | EX_OSFILE | Critical OS file missing |
| 73 | EX_CANTCREAT | Can't create output file |
| 74 | EX_IOERR | I/O error |
| 75 | EX_TEMPFAIL | Temporary failure; retry |
| 76 | EX_PROTOCOL | Protocol error |
| 77 | EX_NOPERM | Permission denied |
| 78 | EX_CONFIG | Configuration error |
