llm-wiki/raw/official-docs/sysexits-bsd-exit-code-convention.md

---
title: "BSD sysexits(3) — EX_CONFIG, EX_SOFTWARE, EX_OSERR, EX_OSFILE exit code convention"
source_type: official-doc
url: https://man.freebsd.org/cgi/man.cgi?sektion=3&query=sysexits
archive_url:
related_branches: [feature-migration-startup-contract]
related_projects: [ca-skeleton]
tags: [exit-code, sysexits, bsd, convention, EX_CONFIG, EX_SOFTWARE]
created: 2026-06-09
---

# BSD sysexits(3) — EX_CONFIG, EX_SOFTWARE, EX_OSERR, EX_OSFILE exit code convention

> Layer: `raw/official-docs/` — BSD sysexits(3) man page. FreeBSD + OpenBSD + Linux man7 세 소스 교차 확인.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-migration-startup-contract]] | D7: startup exit code 표준(env=78, migration=70, profile=71, adapter=72) 의 숫자 근거 — BSD sysexits(3) 컨벤션과의 정합성 확인 |

## 출처 / Source

- 원본 URL: https://man.freebsd.org/cgi/man.cgi?sektion=3&query=sysexits
- OpenBSD mirror: https://man.openbsd.org/sysexits.3
- Linux man7: https://www.man7.org/linux//man-pages/man3/sysexits.h.3head.html
- 저자 / 조직: Eric Allman (BSD 오리지널 작성, 1980), Joerg Wunsch (man page 작성)
- 마지막 확인일: 2026-06-09

## 왜 저장했는지 / Why archived

D7 결정의 숫자(78=env, 70=migration, 71=profile, 72=adapter)가 BSD sysexits(3) 컨벤션에 기반한다는 주장을 검증하기 위해 수집. OpenBSD의 "non-portable, do not use" 경고를 포함한 실제 텍스트 확인.

## 핵심 인용 / Key quotes (verbatim)

> [FreeBSD sysexits(3), EX_SOFTWARE] "An internal software error has been detected. This should be limited to non-operating system related errors if possible."

> [FreeBSD sysexits(3), EX_OSERR] "An operating system error has been detected. This is intended to be used for such things as 'cannot fork', 'cannot create pipe', or the like."

> [FreeBSD sysexits(3), EX_OSFILE] "Some system file (e.g., /etc/passwd, /etc/utmp, etc.) does not exist, cannot be opened, or has some sort of error (e.g., syntax error)."

> [FreeBSD sysexits(3), EX_CONFIG] "Something was found in an unconfigured or misconfigured state."

> [OpenBSD sysexits(3), portability note] "A few programs exit with the following non-portable error codes. Do not use them."

> [FreeBSD sysexits(3), history] "The <sysexits.h> file appeared in 4.0BSD for use by the deliverymail utility, later renamed to sendmail(8)."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SYSEXIT-C1 | EX_CONFIG = 78, 의미: "unconfigured or misconfigured state" | [FreeBSD sysexits(3)] "EX_CONFIG (78): Something was found in an unconfigured or misconfigured state." | `official-standard` (BSD UNIX 표준) | BSD 계열 UNIX 시스템 (FreeBSD, OpenBSD, macOS, Linux with sysexits.h 포함). 표준 헤더. | sysexits(3)가 Java/Spring Boot 애플리케이션 exit code에 적용되어야 한다는 뜻은 아님. 이 컨벤션의 채택은 구현자 결정. |
| SYSEXIT-C2 | EX_SOFTWARE = 70, 의미: "internal software error (non-OS)" | [FreeBSD sysexits(3)] "EX_SOFTWARE (70): An internal software error has been detected. This should be limited to non-operating system related errors if possible." | `official-standard` (BSD UNIX 표준) | BSD 계열 UNIX 시스템 | "migration failure = internal software error" 의 의미 정합성은 해석의 문제. 원문은 migration failure를 언급하지 않음. |
| SYSEXIT-C3 | EX_OSERR = 71, 의미: "OS error — cannot fork, cannot pipe 등" | [FreeBSD sysexits(3)] "EX_OSERR (71): An operating system error has been detected. This is intended to be used for such things as 'cannot fork', 'cannot create pipe', or the like." | `official-standard` (BSD UNIX 표준) | BSD 계열 UNIX 시스템 | **"profile mismatch"는 OS error가 아님.** EX_OSERR의 원래 의미(cannot fork/pipe)와 "profile mismatch" 사이에 의미론적 불일치 존재. |
| SYSEXIT-C4 | EX_OSFILE = 72, 의미: "system file missing/unreadable (/etc/passwd 등)" | [FreeBSD sysexits(3)] "EX_OSFILE (72): Some system file (e.g., /etc/passwd, /etc/utmp, etc.) does not exist, cannot be opened, or has some sort of error (e.g., syntax error)." | `official-standard` (BSD UNIX 표준) | BSD 계열 UNIX 시스템 | **"required adapter disabled"는 system file missing이 아님.** EX_OSFILE의 원래 의미(OS system file 문제)와 "required adapter disabled" 사이에 의미론적 불일치 존재. |
| SYSEXIT-C5 | OpenBSD는 이 exit code들을 "non-portable, do not use"로 표기한다 | [OpenBSD sysexits(3)] "A few programs exit with the following non-portable error codes. Do not use them." | `official-standard` (OpenBSD man page) | OpenBSD 공식 입장 — BSD 계열 내에서도 이견이 존재함 | Linux에서 이 코드들이 의미 없다는 뜻은 아님. POSIX 표준이 아닌 것은 사실. |
| SYSEXIT-C6 | sysexits는 sendmail(8)을 위해 1980년 만들어진 것으로, 현대 microservice context에서의 사용을 전제하지 않는다 | [FreeBSD sysexits(3), history] "The <sysexits.h> file appeared in 4.0BSD for use by the deliverymail utility, later renamed to sendmail(8)." | `official-standard` | sysexits의 역사적 기원 | 현대 애플리케이션에서의 적합성 판단은 이 문서의 범위 밖 |
| SYSEXIT-C7 | sysexits 표준에 EX_NOINPUT=66, EX_NOUSER=67, EX_NOHOST=68, EX_UNAVAILABLE=69, EX_TEMPFAIL=75, EX_PROTOCOL=76, EX_NOPERM=77 등도 존재한다 | [FreeBSD sysexits(3)] 전체 코드 목록 | `official-standard` | BSD 계열 UNIX 시스템 | D7이 선택한 4개(78/70/71/72) 외에도 더 적합한 코드가 있을 수 있음 — 예: EX_UNAVAILABLE(69)="service unavailable"이 "required adapter disabled"에 더 의미론적으로 적합할 수 있음 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `SYSEXIT-C1`: EX_CONFIG=78의 공식 의미 ("misconfigured state") — env 누락/malformed과 의미론적으로 정합
  - `SYSEXIT-C2`: EX_SOFTWARE=70의 공식 의미 ("internal software error") — migration 실패와 의미론적으로 수용 가능
  - `SYSEXIT-C3`: EX_OSERR=71의 공식 의미 ("cannot fork/pipe") — "profile mismatch"와 의미론적 불일치
  - `SYSEXIT-C4`: EX_OSFILE=72의 공식 의미 ("system file missing") — "required adapter disabled"와 의미론적 불일치
  - `SYSEXIT-C5`: OpenBSD는 이 코드들을 "do not use" (non-portable)로 경고
- 이 자료가 증명하지 않는 것:
  - Java/Spring Boot/Kubernetes 환경에서 sysexits 컨벤션을 따라야 한다는 것
  - 71을 "profile mismatch"에, 72를 "required adapter disabled"에 쓰는 것이 적절하다는 것 (원래 의미와 불일치)
  - Kubernetes가 이 코드들을 의미있게 처리한다는 것
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - D7에서 71/72 선택이 실제로 sysexits 의미론과 정합한지 — 본 raw 자료는 불일치를 보여줌
  - 대안: EX_UNAVAILABLE(69)="service unavailable"이 "required adapter disabled"에 더 적합하지 않은지 검토

## 의미론적 불일치 분석 (D7 vs sysexits 원래 의미)

D7 결정과 sysexits 원래 의미의 정합성:

| D7 코드 | D7 의미 | sysexits 원래 의미 | 정합성 |
|---|---|---|---|
| 78 (EX_CONFIG) | env 누락/malformed | "unconfigured or misconfigured state" | **정합** — env 누락은 misconfigured state |
| 70 (EX_SOFTWARE) | migration 실패 | "internal software error" | **부분 정합** — migration 실패는 SW error로 볼 수 있으나 원문은 DB migration을 언급하지 않음 |
| 71 (EX_OSERR) | profile mismatch | "cannot fork, cannot pipe" | **불일치** — profile mismatch는 OS error가 아님. EX_CONFIG(78)가 더 적합하거나 별도 커스텀 코드 필요 |
| 72 (EX_OSFILE) | required adapter disabled | "system file missing/unreadable" | **불일치** — adapter disabled는 system file 문제가 아님. EX_UNAVAILABLE(69)나 EX_CONFIG(78)이 더 적합할 수 있음 |

## 메모 / Notes

- sysexits(3)는 POSIX 표준이 아니라 BSD 컨벤션. Linux에서도 헤더가 존재하지만 OpenBSD가 "do not use"로 경고.
- 현대 microservice에서 process exit code보다 structured log가 실제 discriminator로 더 유용한 이유: k8s가 이 코드들을 자동으로 처리하지 않음.
- D7의 71/72는 sysexits 원래 의미와 의미론적 불일치가 존재함 — UNSUPPORTED_DECISION 라벨이 적합한 상태.

## Related / 관련

- [[raw/official-docs/spring-boot-exit-code-generator-startup-failure]] — Spring Boot의 exit code 메커니즘
- [[raw/branch-notes/feature-migration-startup-contract]] — D7 결정 (UNSUPPORTED_DECISION 해소 대상)