frama-c

[ai-review] / critic / posix.md

# POSIX Programming Critic Framework (Austin Group / IEEE Std 1003.1-2024)

This framework guides the Critic role when evaluating POSIX-compliant code, system interfaces, and standards conformance from the perspective of the Austin Common Standards Revision Group, the maintainers of the IEEE Std 1003.1-2024 (POSIX) standard. This critic focuses on specification adherence, portability, correct use of POSIX APIs, and the principles that ensure robust, interoperable, and maintainable POSIX systems and applications.

## POSIX Code Evaluation Areas

### 1. Standard Compliance and Conformance
**What to Look For:**
- Strict adherence to POSIX.1-2024 specifications
- Correct use of POSIX-defined interfaces, types, and constants
- Avoidance of undefined, unspecified, or implementation-defined behavior
- Proper feature test macros and conditional compilation for optional features

**Common Problems:**
- Use of non-standard or deprecated interfaces
- Reliance on unspecified or undefined behavior
- Incorrect or missing feature test macros
- Violation of interface contracts (e.g., buffer sizes, return values)

**Evaluation Questions:**
- Does the code use only POSIX-specified interfaces where required?
- Are all feature test macros used correctly to guard optional features?
- Is undefined or unspecified behavior avoided?
- Are all interface contracts (arguments, return values, side effects) respected?
- Does the code compile and run on multiple conforming POSIX systems?

### 2. Resource and File Descriptor Management
**What to Look For:**
- Proper acquisition and release of file descriptors and system resources
- Avoidance of resource leaks (file descriptors, memory, etc.)
- Correct use of close-on-exec and non-blocking flags
- Safe handling of signals and asynchronous events

**Common Problems:**
- File descriptor leaks (unclosed files, sockets, pipes)
- Double-closing or use-after-close errors
- Failure to set O_CLOEXEC or O_NONBLOCK when needed
- Unsafe resource handling in signal handlers

**Evaluation Questions:**
- Are all file descriptors and resources released on all code paths?
- Are close-on-exec and non-blocking flags used appropriately?
- Are resources handled safely in the presence of signals?
- Are resource limits (RLIMIT_*) respected and handled?

### 3. Error Handling and Robustness
**What to Look For:**
- Consistent checking of all system call and library function return values
- Proper use of errno and error reporting
- Graceful handling of partial operations (e.g., short reads/writes)
- Cleanup of resources on error paths

**Common Problems:**
- Ignoring or mishandling error returns from system calls
- Overwriting errno before it is checked
- Failing to handle partial I/O or interrupted system calls (EINTR)
- Resource leaks on error paths

**Evaluation Questions:**
- Are all system call and library function errors checked and handled?
- Is errno used and preserved correctly?
- Are partial and interrupted operations handled robustly?
- Are error messages clear and actionable?
- Are resources always cleaned up on error paths?

### 4. Portability and Implementation Independence
**What to Look For:**
- Code that works across all conforming POSIX systems
- Use of portable types (e.g., ssize_t, size_t, off_t)
- Avoidance of implementation-specific or undefined behavior
- Proper use of _POSIX_* and _XOPEN_* feature macros

**Common Problems:**
- Assumptions about file descriptor values, path lengths, or type sizes
- Use of non-portable extensions or platform-specific APIs
- Missing or incorrect feature detection
- Hardcoded limits or platform dependencies

**Evaluation Questions:**
- Does the code avoid assumptions about system-specific limits?
- Are feature macros used to detect and adapt to available features?
- Is all platform-specific code properly abstracted or guarded?
- Are all implementation dependencies documented?

### 5. Threading and Concurrency
**What to Look For:**
- Correct use of POSIX threads (pthreads) and synchronization primitives
- Avoidance of data races and deadlocks
- Proper initialization and destruction of thread resources
- Safe use of async-signal-safe functions in signal handlers

**Common Problems:**
- Data races due to unsynchronized access
- Deadlocks from improper lock ordering
- Leaks of thread resources (e.g., not joining threads)
- Unsafe function calls in signal handlers

**Evaluation Questions:**
- Are all shared resources properly synchronized?
- Are threads and synchronization objects correctly managed?
- Are only async-signal-safe functions called in signal handlers?
- Are thread and process resources always cleaned up?

### 6. Performance and Scalability
**What to Look For:**
- Efficient use of system calls and I/O
- Avoidance of unnecessary polling or busy-waiting
- Use of scalable APIs (e.g., poll, epoll, kqueue)
- Minimal resource contention and lock granularity

**Common Problems:**
- Inefficient polling or blocking
- Excessive system call overhead
- Poor scalability due to coarse-grained locking
- Resource starvation or contention

**Evaluation Questions:**
- Are system calls batched or minimized where possible?
- Are scalable I/O and event mechanisms used?
- Is lock contention minimized?
- Is the code designed for scalability across CPUs and workloads?

## POSIX Standards-Specific Criticism Process

### Step 1: Standard Conformance Analysis
1. **Check Interface Compliance**: Are only POSIX-specified interfaces used?
2. **Evaluate Feature Macros**: Are feature test macros used and correct?
3. **Assess Undefined/Unspecified Behavior**: Is it avoided or documented?
4. **Review Implementation Dependencies**: Are they documented and portable?

### Step 2: Resource and File Descriptor Management
1. **Audit Resource Handling**: Are all resources acquired and released properly?
2. **Check for Leaks**: Are there any resource leaks?
3. **Evaluate Signal Safety**: Are resources handled safely in signal handlers?

### Step 3: Error Handling and Robustness
1. **Check Error Propagation**: Are all errors detected and reported?
2. **Evaluate Partial Operations**: Are partial/interrupted operations handled?
3. **Assess Resource Cleanup**: Are resources cleaned up on error paths?

### Step 4: Portability and Implementation Independence
1. **Review Feature Usage**: Are feature macros and portable types used?
2. **Check for Platform Dependencies**: Are they abstracted or documented?
3. **Assess Limits and Assumptions**: Are hardcoded limits avoided?

### Step 5: Threading and Concurrency
1. **Check Synchronization**: Are all shared resources protected?
2. **Evaluate Thread Lifecycle**: Are threads and resources managed?
3. **Assess Signal Safety**: Are only async-signal-safe functions used in handlers?

## POSIX Standards-Specific Criticism Guidelines

### Focus on Specification Compliance
**Good Criticism:**
- "This code uses a non-standard extension without proper feature test macros."
- "The use of open() here omits O_CLOEXEC, risking file descriptor leaks across exec."
- "This function call is not async-signal-safe and is used in a signal handler."
- "The buffer size assumption here violates PATH_MAX portability requirements."

**Poor Criticism:**
- "This doesn't look right."
- "This seems unsafe."
- "I don't like this approach."

### Emphasize Portability and Correctness
**Good Criticism:**
- "This code assumes a fixed path length, which is not portable."
- "The use of non-portable system calls limits compatibility."
- "This code does not check for partial writes, risking data loss."
- "The use of errno is incorrect; it may be overwritten before being checked."

**Poor Criticism:**
- "This won't work everywhere."
- "This is not portable."
- "This might cause problems."

### Consider Implementation Quality
**Good Criticism:**
- "The error checking here is incomplete—read() can return less than requested."
- "This file descriptor is not closed on all error paths."
- "The use of pthread_mutex is not paired with proper destruction."
- "The signal handler calls a non-async-signal-safe function."

**Poor Criticism:**
- "This has bugs."
- "This is unreliable."
- "This code is bad."

## POSIX Standards-Specific Problem Categories

### Standard Compliance Problems
- **Non-Standard Extensions**: Use of non-POSIX or deprecated interfaces
- **Feature Macro Misuse**: Missing or incorrect feature test macros
- **Interface Contract Violations**: Incorrect arguments, buffer sizes, or return value handling
- **Undefined/Unspecified Behavior**: Code that invokes undefined or unspecified behavior

### Resource Management Problems
- **Resource Leaks**: Unreleased file descriptors, memory, or other resources
- **Use After Close**: Accessing resources after they are released
- **Improper Flags**: Missing O_CLOEXEC, O_NONBLOCK, or other required flags
- **Signal Safety Violations**: Unsafe resource handling in signal handlers

### Error Handling Problems
- **Unchecked Errors**: Ignoring return values from system/library calls
- **Partial Operation Handling**: Failing to handle short reads/writes or EINTR
- **Resource Leaks on Error**: Failing to clean up on error paths
- **Poor Error Reporting**: Unclear or missing error information

### Portability Problems
- **Hardcoded Limits**: Assumptions about PATH_MAX, NAME_MAX, etc.
- **Platform-Specific Code**: Unguarded use of platform-specific features
- **Missing Feature Detection**: No checks for optional POSIX features
- **Type Size Assumptions**: Assuming sizes of off_t, ssize_t, etc.

### Threading and Concurrency Problems
- **Data Races**: Unsynchronized access to shared data
- **Deadlocks**: Improper lock ordering or missing unlocks
- **Resource Leaks**: Not joining or cleaning up threads
- **Signal Safety Violations**: Unsafe calls in signal handlers

## POSIX Standards-Specific Criticism Templates

### For Standard Compliance Issues
```
Standard Compliance Issue: [Specific POSIX standard violation]
Standard Reference: [IEEE Std 1003.1-2024 section and paragraph]
Problem: [How this violates the POSIX specification]
Impact: [Undefined/unspecified behavior, non-conformance, or portability issue]
Evidence: [Specific code examples and standard citations]
Priority: [Critical/High/Medium/Low]
```

### For Resource Management Issues
```
Resource Management Issue: [Specific resource management problem]
Problem: [What makes this unsafe or incorrect]
Impact: [Potential leaks, crashes, or security vulnerabilities]
Evidence: [Specific code paths and failure scenarios]
Priority: [Critical/High/Medium/Low]
```

### For Portability Issues
```
Portability Issue: [Specific portability problem]
Problem: [What assumptions or dependencies limit portability]
Impact: [Platforms or implementations where this will fail]
Evidence: [Specific code examples and platform differences]
Priority: [High/Medium/Low]
```

## POSIX Standards-Specific Criticism Best Practices

### Do's
- **Cite Standard References**: Always reference specific sections of IEEE Std 1003.1-2024
- **Focus on Specification**: Evaluate against the formal POSIX specification
- **Consider All Implementations**: Think about all conforming POSIX systems, not just one
- **Emphasize Correctness**: Prioritize correct behavior and resource management
- **Document Dependencies**: Clearly identify any implementation-defined or system-specific behaviors

### Don'ts
- **Assume Specific Implementations**: Don't assume particular OS or libc behaviors
- **Ignore Feature Macros**: Don't overlook proper use of feature test macros
- **Accept Undefined/Unspecified Behavior**: Don't tolerate code that invokes undefined or unspecified behavior
- **Skip Error Checking**: Don't ignore error handling requirements
- **Overlook Portability**: Don't accept unnecessarily non-portable code

## POSIX Standards-Specific Criticism Checklist

### Standard Compliance Assessment
- [ ] Does the code use only POSIX-specified interfaces where required?
- [ ] Are all feature test macros used and correct?
- [ ] Is undefined/unspecified behavior avoided throughout?
- [ ] Are interface contracts respected (arguments, return values, side effects)?
- [ ] Does the code compile and run on multiple POSIX systems?

### Resource Management Assessment
- [ ] Are all file descriptors and resources released on all code paths?
- [ ] Are close-on-exec and non-blocking flags used appropriately?
- [ ] Are resources handled safely in the presence of signals?
- [ ] Are resource limits respected and handled?

### Error Handling Assessment
- [ ] Are all system/library call errors checked and handled?
- [ ] Is errno used and preserved correctly?
- [ ] Are partial and interrupted operations handled robustly?
- [ ] Are error messages clear and actionable?
- [ ] Are resources always cleaned up on error paths?

### Portability Assessment
- [ ] Does the code avoid assumptions about system-specific limits?
- [ ] Are feature macros used to detect and adapt to available features?
- [ ] Is all platform-specific code properly abstracted or guarded?
- [ ] Are all implementation dependencies documented?

### Threading and Concurrency Assessment
- [ ] Are all shared resources properly synchronized?
- [ ] Are threads and synchronization objects correctly managed?
- [ ] Are only async-signal-safe functions called in signal handlers?
- [ ] Are thread and process resources always cleaned up?

## POSIX Standards-Specific Evaluation Questions

### For Any POSIX Code
1. **Does this code use only POSIX-specified interfaces where required?**
2. **Are all feature test macros used and correct?**
3. **Is undefined or unspecified behavior avoided?**
4. **Are all resources (file descriptors, memory, etc.) managed correctly?**
5. **Are all error conditions properly handled and reported?**
6. **Is the code portable across conforming POSIX systems?**
7. **Are all types and constants used as specified by POSIX?**
8. **Are all implementation dependencies documented?**
9. **Do all code paths handle errors and cleanup resources?**
10. **Is the code efficient and scalable without sacrificing correctness?**

### For Library or System Code
1. **Are all public interfaces documented with preconditions and postconditions?**
2. **Is thread safety clearly specified and implemented correctly?**
3. **Are all parameters validated appropriately?**
4. **Is the API design consistent with POSIX conventions?**
5. **Are all resources properly managed by the library or system?**

### For Multi-Process or Multi-Threaded Code
1. **Are all synchronization primitives used correctly?**
2. **Are all shared resources protected from data races?**
3. **Are async-signal-safe functions used in signal handlers?**
4. **Are all process/thread resources cleaned up?**
5. **Are all concurrency and reentrancy issues considered and addressed?**

## POSIX Standard Principles Applied

### "Provide a Portable Operating System Interface"
- Write code that works across all conforming POSIX systems
- Avoid reliance on implementation-specific behaviors
- Use standard types, constants, and interfaces for maximum portability

### "Emphasize Correctness and Robustness"
- Use interfaces as specified, with correct arguments and error handling
- Avoid undefined or unspecified behavior
- Ensure all resources are managed and cleaned up

### "Support Efficient and Scalable Systems"
- Use efficient algorithms and scalable system interfaces
- Minimize resource contention and maximize concurrency
- Optimize appropriately without sacrificing correctness or clarity

### "Enable Secure and Reliable Systems"
- Avoid resource leaks and privilege escalation vulnerabilities
- Use async-signal-safe functions in signal handlers
- Validate all inputs and handle errors robustly

### "Document and Abstract Implementation Dependencies"
- Clearly document any system-specific or implementation-defined behavior
- Use feature macros and conditional compilation for optional features
- Abstract platform-specific code where possible

## POSIX Standard Library and System Interface Evaluation Criteria

### File and I/O Functions
- **open/close/read/write**: Proper error checking, resource cleanup, flags (O_CLOEXEC, O_NONBLOCK)
- **dup/dup2/dup3**: Correct duplication and management of file descriptors
- **poll/select/epoll/kqueue**: Scalable event handling, correct timeout and event mask usage
- **stat/fstat/lstat**: Correct handling of file metadata and symbolic links

### Process and Signal Functions
- **fork/exec/wait**: Proper error handling, resource management, and signal safety
- **signal/sigaction**: Use of async-signal-safe functions, correct signal mask handling
- **kill/raise**: Correct process and signal management

### Memory and Resource Functions
- **mmap/munmap**: Proper mapping/unmapping, error checking, alignment
- **malloc/free**: Correct pairing, error handling, and resource cleanup
- **getrlimit/setrlimit**: Respecting and handling resource limits

### Threading and Synchronization Functions
- **pthread_create/join/detach**: Proper thread lifecycle management
- **pthread_mutex/cond/rwlock**: Correct initialization, locking, unlocking, and destruction
- **pthread_once**: Safe one-time initialization

### Time and Locale Functions
- **clock_gettime/nanosleep**: Correct time handling, error checking
- **strftime/strptime**: Buffer sizes, locale awareness, error handling
- **setlocale**: Locale management and thread safety