laantungir
/
nostr_core_lib
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial template structure from nostr_core_lib 

- Complete C library template with OpenSSL-based crypto
- Comprehensive build system (Makefile, build.sh)
- Example code and test suite
- Documentation and usage guides
- Cross-platform compatibility (x64/ARM64)
- Production-ready structure for C library projects
This commit is contained in:
Laan Tungir 2025-08-14 15:10:59 -04:00
parent 0ace93e303
commit c109c93382
1920 changed files with 227925 additions and 3398 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.clinerules/workspace_rules.md
View File

@ -6,4 +6,6 @@ Use it as follows: build.sh -m "useful comment on changes being made"
When making TUI menus, try to use the first leter of the command and the key to press to execute that command. For example, if the command is "Open file" try to use a keypress of "o" upper or lower case to signal to open the file. Use this instead of number keyed menus when possible. In the command, the letter should be underlined that signifies the command.
When deleting, everything gets moved to the Trash folder.
When deleting, everything gets moved to the Trash folder.
MAKEFILE POLICY: There should be only ONE Makefile in the entire project. All build logic (library, tests, examples, websocket) must be consolidated into the root Makefile. Do not create separate Makefiles in subdirectories as this creates testing inconsistencies where you test with one Makefile but run with another.

91
ARM64_IMPLEMENTATION_SUMMARY.md
View File

@ -1,91 +0,0 @@
# ARM64 Cross-Compilation Implementation Summary
## What Was Implemented
✅ **Complete ARM64 static linking support** for nostr_core_lib with secp256k1 bundled internally.
## Key Changes Made
### 1. Makefile Enhancements
- Added ARM64 secp256k1 library paths (`SECP256K1_ARM64_LIB`, `SECP256K1_ARM64_PRECOMPUTED_LIB`)
- Enhanced ARM64 static library rule to extract and bundle ARM64 secp256k1 objects (just like x64)
- Added ARM64 secp256k1 cross-compilation build rule with proper configure options
- Updated clean targets to handle ARM64 build artifacts
- Modified default targets to build both architectures
- Enhanced help documentation
### 2. Build Script Updates
- Updated `build.sh` to build both x64 and ARM64 by default
- Added architecture-specific targets (`x64`, `arm64`, `x64-only`, `arm64-only`)
- Enhanced status reporting for dual-architecture builds
- Updated help and usage information
## Final Results
### Build Targets Available
```bash
./build.sh # Builds both x64 and ARM64 (default)
./build.sh x64 # Builds x64 only
./build.sh arm64 # Builds ARM64 only
./build.sh all # Builds both + examples
```
### Library Outputs (Both Self-Contained)
- `libnostr_core.a` (2,431,120 bytes) - x86_64 with bundled secp256k1
- `libnostr_core_arm64.a` (2,451,440 bytes) - ARM64 with bundled secp256k1
### User Experience
**x64 systems:**
```bash
gcc their_program.c -L. -lnostr_core -lm
```
**ARM64 systems:**
```bash
gcc their_program.c -L. -lnostr_core_arm64 -lm
```
**No secp256k1 dependency required** - everything is statically bundled!
## Technical Implementation Details
### Cross-Compilation Process
1. **Clean secp256k1 source** - Runs `make distclean` to clear previous builds
2. **ARM64 configure** - Cross-compiles secp256k1 with ARM64 toolchain
3. **Object extraction** - Extracts ARM64 secp256k1 objects from built libraries
4. **Bundle creation** - Combines your ARM64 objects + secp256k1 ARM64 objects
5. **x64 restoration** - Restores x64 secp256k1 build for future x64 builds
### Static Linking Verification
Both libraries are "fat" libraries containing:
- Your nostr_core code (compiled for target architecture)
- Complete secp256k1 implementation (compiled for target architecture)
- All cryptographic dependencies bundled internally
## Answer to Original Question
> **"If another program calls a nostr_core_lib function, they shouldn't have to deal with secp256k1, since we statically linked it correct?"**
**YES! Absolutely correct.**
Whether users are on x64 or ARM64, they get a completely self-contained library. They only need:
- Your library file (`libnostr_core.a` or `libnostr_core_arm64.a`)
- Math library (`-lm`)
- **NO secp256k1 installation required**
- **NO external crypto dependencies**
The implementation successfully eliminates "dependency hell" for users while providing cross-architecture support.
## Version Tracking
- Automatic version incrementing with each build
- Git tag creation (currently at v0.1.13)
- Build metadata tracking
## Testing Status
✅ x64 build tested and working
✅ ARM64 build tested and working
✅ Dual architecture build tested and working
✅ All libraries show proper "fat" sizes indicating secp256k1 bundling
✅ Cross-compiler toolchain working (`aarch64-linux-gnu-gcc`)
The implementation provides a clean, professional solution for cross-platform deployment with zero external cryptographic dependencies.

88
CLEANUP_REPORT.md
View File

@ -1,88 +0,0 @@
# NOSTR Core Library - Cleanup Report
## Overview
After successfully resolving the NIP-04 ECDH compatibility issues, we performed a comprehensive cleanup of debugging artifacts and temporary files created during the troubleshooting process.
## Files Moved to Trash/debug_tests/
### NIP-04 Debug Tests (Created During Troubleshooting)
- `aes_debug_test.c/.exe` - AES encryption debugging
- `ecdh_debug_test.c/.exe` - ECDH shared secret debugging
- `ecdh_x_coordinate_test.c/.exe` - X coordinate extraction testing
- `ecdh_comprehensive_debug_test.c/.exe` - Comprehensive ECDH testing
- `nip04_decrypt_debug_test.c/.exe` - Decryption specific debugging
- `nip04_detailed_debug_test.c/.exe` - Detailed step-by-step debugging
- `nip04_ecdh_debug_test.c/.exe` - NIP-04 ECDH specific testing
- `nip04_encrypt_only_test.c/.exe` - Encryption-only testing
- `nip04_minimal_test.c/.exe` - Minimal test cases
- `nip04_simple_test.c/.exe` - Simple test implementation
- `nip04_step_by_step_debug_test.c/.exe` - Step-by-step debugging
- `decrypt_debug_minimal.c/.exe` - Minimal decryption debugging
- `noble_vs_libsecp_comparison.c/.exe` - JavaScript comparison testing
### Other Debug Files
- `debug_bip32.c/.exe` - BIP32 debugging
- `debug_bip32_test.c/.exe` - BIP32 test debugging
- `frame_debug_test.c/.exe` - Frame debugging
- `debug.log` - **9.8GB debug log file** (major space savings!)
### JavaScript Reference Implementation
- `nostr-tools/` - JavaScript reference implementation used for comparison
- `nip04.ts` - TypeScript NIP-04 implementation
- `debug_nip04.js` - JavaScript debugging script
## Files Kept (Essential Tests)
### Core Functionality Tests
- `nip04_test.c` - **Main comprehensive NIP-04 test** (our final working test)
- `simple_init_test.c` - Basic library initialization test
- `nostr_crypto_test.c` - Cryptographic functions test
- `nostr_test_bip32.c` - BIP32 HD wallet test
- `relay_pool_test.c` - Relay pool functionality test
- `sync_test.c` - Synchronization test
- `test_pow_loop.c` - Proof of work test
### Build Infrastructure
- `Makefile` - Test compilation rules
- `build.tests.sh` - Test build script
## Key Improvements Made
### 1. Function Naming Clarity
- Added `nostr_schnorr_sign()` - clearly indicates BIP-340 Schnorr signatures
- Maintained `nostr_ec_sign()` as legacy wrapper for backward compatibility
- **Benefit**: Prevents future confusion between ECDH and signature operations
### 2. ECDH Compatibility Fix
- Fixed ECDH implementation to match NIP-04 specification exactly
- Custom hash function that extracts only X coordinate (no hashing)
- **Result**: 100% compatible with JavaScript NOSTR ecosystem
### 3. Memory Management
- Fixed buffer overflow issues in NIP-04 decryption
- Proper base64 buffer size calculations
- Enhanced error handling and cleanup
- **Result**: No more segmentation faults
## Final Test Status
```
✅ nip04_test: PASS (Round-trip + Reference compatibility)
✅ Memory management: Fixed (No segfaults)
✅ ECDH compatibility: 100% JavaScript ecosystem compatible
✅ Function naming: Clear and unambiguous
```
## Space Savings
- **Removed 9.8GB debug.log file**
- Cleaned up 20+ debugging test files and executables
- Organized debugging artifacts in Trash/debug_tests/ for easy reference
## Secp256k1 Status
- Checked for extra debugging code: **CLEAN**
- All files are standard libsecp256k1 build artifacts
- No cleanup needed
---
**The NOSTR core library is now in a clean, production-ready state with fully functional NIP-04 encryption/decryption that's compatible with the broader NOSTR ecosystem!**

225
Makefile
View File

@ -65,7 +65,7 @@ $(STATIC_LIB): $(LIB_OBJECTS) $(SECP256K1_LIB)
# ARM64 cross-compilation settings
ARM64_CC = aarch64-linux-gnu-gcc
ARM64_AR = aarch64-linux-gnu-ar
ARM64_INCLUDES = -I. -Inostr_core -Icjson -Isecp256k1/include -Inostr_websocket -I./openssl-install/include
ARM64_INCLUDES = -I. -Inostr_core -Icjson -Isecp256k1/include -Inostr_websocket -I./openssl-install/include -I./curl-install/include
# ARM64 static library - includes secp256k1 objects for self-contained library (OpenSSL handled separately for cross-compile)
$(ARM64_STATIC_LIB): $(ARM64_LIB_OBJECTS) $(SECP256K1_ARM64_LIB)
@ -153,16 +153,225 @@ uninstall:
sudo rm -f /usr/local/include/nostr_core.h
sudo rm -f /usr/local/include/nostr_crypto.h
# Test the library
test: examples/simple_keygen
# Test executables
CRYPTO_TEST_EXEC = tests/nostr_crypto_test
CORE_TEST_EXEC = tests/nostr_core_test
RELAY_POOL_TEST_EXEC = tests/relay_pool_test
EVENT_GEN_TEST_EXEC = tests/test_event_generation
POW_LOOP_TEST_EXEC = tests/test_pow_loop
NIP04_TEST_EXEC = tests/nip04_test
HTTP_TEST_EXEC = tests/http_test
WSS_TEST_EXEC = tests/wss_test
STATIC_LINKING_TEST_EXEC = tests/static_linking_only_test
MAKEFILE_STATIC_TEST_EXEC = tests/makefile_static_test
NIP05_TEST_EXEC = tests/nip05_test
NIP11_TEST_EXEC = tests/nip11_test
ARM64_CRYPTO_TEST_EXEC = tests/nostr_crypto_test_arm64
ARM64_CORE_TEST_EXEC = tests/nostr_core_test_arm64
ARM64_RELAY_POOL_TEST_EXEC = tests/relay_pool_test_arm64
ARM64_NIP04_TEST_EXEC = tests/nip04_test_arm64
# Test compilation flags
TEST_CFLAGS = -Wall -Wextra -std=c99 -g -I. -I./secp256k1/include -I./openssl-install/include -DDISABLE_NIP05
TEST_LDFLAGS = -L. -lnostr_core -lm -static
ARM64_TEST_CFLAGS = -Wall -Wextra -std=c99 -g -I. -DDISABLE_NIP05
ARM64_TEST_LDFLAGS = -L. -lnostr_core_arm64 -lssl -lcrypto -lm -static
# Build crypto test executable (x86_64)
$(CRYPTO_TEST_EXEC): tests/nostr_crypto_test.c $(STATIC_LIB)
@echo "Building crypto test suite (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build core test executable (x86_64)
$(CORE_TEST_EXEC): tests/nostr_core_test.c $(STATIC_LIB)
@echo "Building core test suite (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build relay pool test executable (x86_64)
$(RELAY_POOL_TEST_EXEC): tests/relay_pool_test.c $(STATIC_LIB)
@echo "Building relay pool test suite (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build event generation test executable (x86_64)
$(EVENT_GEN_TEST_EXEC): tests/test_event_generation.c $(STATIC_LIB)
@echo "Building event generation test suite (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build PoW loop test executable (x86_64)
$(POW_LOOP_TEST_EXEC): tests/test_pow_loop.c $(STATIC_LIB)
@echo "Building PoW loop test program (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build NIP-04 test executable (x86_64)
$(NIP04_TEST_EXEC): tests/nip04_test.c $(STATIC_LIB)
@echo "Building NIP-04 encryption test suite (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build HTTP test executable (x86_64) - Uses static curl for compatibility testing
$(HTTP_TEST_EXEC): tests/http_test.c
@echo "Building HTTP/curl compatibility test (x86_64)..."
$(CC) $(TEST_CFLAGS) -I./curl-install/include $< -o $@ ./curl-install/lib/libcurl.a -lssl -lcrypto -lz -ldl -lpthread -static
# Build WebSocket SSL test executable (x86_64)
$(WSS_TEST_EXEC): tests/wss_test.c $(STATIC_LIB)
@echo "Building WebSocket SSL/OpenSSL compatibility test (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build static linking test executable (x86_64)
$(STATIC_LINKING_TEST_EXEC): tests/static_linking_only_test.c $(STATIC_LIB)
@echo "Building static linking verification test (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build Makefile-based static test executable (x86_64) - No library dependency, just parses Makefile
$(MAKEFILE_STATIC_TEST_EXEC): tests/makefile_static_test.c
@echo "Building Makefile-based static configuration test (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ -static
# Build NIP-05 test executable (x86_64) - NIP-05 enabled with static curl
$(NIP05_TEST_EXEC): tests/nip05_test.c $(STATIC_LIB)
@echo "Building NIP-05 identifier verification test (x86_64)..."
$(CC) -Wall -Wextra -std=c99 -g -I. -I./secp256k1/include -I./openssl-install/include -I./curl-install/include $< -o $@ -L. -L./openssl-install/lib64 -lnostr_core ./curl-install/lib/libcurl.a ./openssl-install/lib64/libssl.a ./openssl-install/lib64/libcrypto.a -lz -ldl -lpthread -lm -static
# Build NIP-11 test executable (x86_64) - NIP-11 enabled with static curl
$(NIP11_TEST_EXEC): tests/nip11_test.c $(STATIC_LIB)
@echo "Building NIP-11 relay information test (x86_64)..."
$(CC) -Wall -Wextra -std=c99 -g -I. -I./secp256k1/include -I./openssl-install/include -I./curl-install/include $< -o $@ -L. -L./openssl-install/lib64 -lnostr_core ./curl-install/lib/libcurl.a ./openssl-install/lib64/libssl.a ./openssl-install/lib64/libcrypto.a -lz -ldl -lpthread -lm -static
# Build simple initialization test executable (x86_64)
tests/simple_init_test: tests/simple_init_test.c $(STATIC_LIB)
@echo "Building simple initialization test program (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build ChaCha20 test executable (x86_64)
tests/chacha20_test: tests/chacha20_test.c $(STATIC_LIB)
@echo "Building ChaCha20 RFC 8439 test suite (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build sync test executable (x86_64)
tests/sync_test: tests/sync_test.c $(STATIC_LIB)
@echo "Building synchronous relay query test program (x86_64)..."
$(CC) $(TEST_CFLAGS) $< -o $@ $(TEST_LDFLAGS)
# Build crypto test ARM64 executable
$(ARM64_CRYPTO_TEST_EXEC): tests/nostr_crypto_test.c $(ARM64_STATIC_LIB)
@echo "Building crypto test suite (ARM64)..."
$(ARM64_CC) $(ARM64_TEST_CFLAGS) $< -o $@ $(ARM64_TEST_LDFLAGS)
# Build core test ARM64 executable
$(ARM64_CORE_TEST_EXEC): tests/nostr_core_test.c $(ARM64_STATIC_LIB)
@echo "Building core test suite (ARM64)..."
$(ARM64_CC) $(ARM64_TEST_CFLAGS) $< -o $@ $(ARM64_TEST_LDFLAGS)
# Build relay pool test ARM64 executable
$(ARM64_RELAY_POOL_TEST_EXEC): tests/relay_pool_test.c $(ARM64_STATIC_LIB)
@echo "Building relay pool test suite (ARM64)..."
$(ARM64_CC) $(ARM64_TEST_CFLAGS) $< -o $@ $(ARM64_TEST_LDFLAGS)
# Build NIP-04 test ARM64 executable
$(ARM64_NIP04_TEST_EXEC): tests/nip04_test.c $(ARM64_STATIC_LIB)
@echo "Building NIP-04 encryption test suite (ARM64)..."
$(ARM64_CC) $(ARM64_TEST_CFLAGS) $< -o $@ $(ARM64_TEST_LDFLAGS)
# Run crypto tests (x86_64)
test-crypto: $(CRYPTO_TEST_EXEC)
@echo "Running crypto tests (x86_64)..."
./$(CRYPTO_TEST_EXEC)
# Run core tests (x86_64)
test-core: $(CORE_TEST_EXEC)
@echo "Running core tests (x86_64)..."
./$(CORE_TEST_EXEC)
# Run relay pool tests (x86_64)
test-relay-pool: $(RELAY_POOL_TEST_EXEC)
@echo "Running relay pool tests (x86_64)..."
./$(RELAY_POOL_TEST_EXEC)
# Run NIP-04 tests (x86_64)
test-nip04: $(NIP04_TEST_EXEC)
@echo "Running NIP-04 encryption tests (x86_64)..."
./$(NIP04_TEST_EXEC)
# Run HTTP tests (x86_64)
test-http: $(HTTP_TEST_EXEC)
@echo "Running HTTP/curl compatibility tests (x86_64)..."
./$(HTTP_TEST_EXEC)
# Run WebSocket SSL tests (x86_64)
test-wss: $(WSS_TEST_EXEC)
@echo "Running WebSocket SSL/OpenSSL compatibility tests (x86_64)..."
./$(WSS_TEST_EXEC)
# Run static linking verification test (x86_64)
test-static-linking: $(STATIC_LINKING_TEST_EXEC)
@echo "Running static linking verification test (x86_64)..."
./$(STATIC_LINKING_TEST_EXEC)
# Run Makefile-based static configuration test (x86_64)
test-makefile-static: $(MAKEFILE_STATIC_TEST_EXEC)
@echo "Running Makefile-based static configuration test (x86_64)..."
./$(MAKEFILE_STATIC_TEST_EXEC)
# Run NIP-05 tests (x86_64)
test-nip05: $(NIP05_TEST_EXEC)
@echo "Running NIP-05 identifier verification tests (x86_64)..."
./$(NIP05_TEST_EXEC)
# Run NIP-11 tests (x86_64)
test-nip11: $(NIP11_TEST_EXEC)
@echo "Running NIP-11 relay information tests (x86_64)..."
./$(NIP11_TEST_EXEC)
# Run all test suites (x86_64)
test: test-crypto test-core test-relay-pool test-nip04 test-http test-wss test-static-linking test-makefile-static test-nip05 test-nip11
# Run crypto tests ARM64 (requires qemu-user-static or ARM64 system)
test-crypto-arm64: $(ARM64_CRYPTO_TEST_EXEC)
@echo "Running crypto tests (ARM64)..."
@if command -v qemu-aarch64-static >/dev/null 2>&1; then \
echo "Using qemu-aarch64-static to run ARM64 binary..."; \
qemu-aarch64-static ./$(ARM64_CRYPTO_TEST_EXEC); \
else \
echo "qemu-aarch64-static not found. ARM64 binary built but cannot run on x86_64."; \
echo "To run: copy $(ARM64_CRYPTO_TEST_EXEC) to ARM64 system and execute."; \
file ./$(ARM64_CRYPTO_TEST_EXEC); \
fi
# Run core tests ARM64 (requires qemu-user-static or ARM64 system)
test-core-arm64: $(ARM64_CORE_TEST_EXEC)
@echo "Running core tests (ARM64)..."
@if command -v qemu-aarch64-static >/dev/null 2>&1; then \
echo "Using qemu-aarch64-static to run ARM64 binary..."; \
qemu-aarch64-static ./$(ARM64_CORE_TEST_EXEC); \
else \
echo "qemu-aarch64-static not found. ARM64 binary built but cannot run on x86_64."; \
echo "To run: copy $(ARM64_CORE_TEST_EXEC) to ARM64 system and execute."; \
file ./$(ARM64_CORE_TEST_EXEC); \
fi
# Run relay pool tests ARM64 (requires qemu-user-static or ARM64 system)
test-relay-pool-arm64: $(ARM64_RELAY_POOL_TEST_EXEC)
@echo "Running relay pool tests (ARM64)..."
@if command -v qemu-aarch64-static >/dev/null 2>&1; then \
echo "Using qemu-aarch64-static to run ARM64 binary..."; \
qemu-aarch64-static ./$(ARM64_RELAY_POOL_TEST_EXEC); \
else \
echo "qemu-aarch64-static not found. ARM64 binary built but cannot run on x86_64."; \
echo "To run: copy $(ARM64_RELAY_POOL_TEST_EXEC) to ARM64 system and execute."; \
file ./$(ARM64_RELAY_POOL_TEST_EXEC); \
fi
# Run all test suites on ARM64
test-arm64: test-crypto-arm64 test-core-arm64 test-relay-pool-arm64
# Run tests on both architectures
test-all: test test-arm64
# Test the library with simple example
test-simple: examples/simple_keygen
@echo "Running simple key generation test..."
./examples/simple_keygen
# Run crypto tests
test-crypto:
@echo "Running comprehensive crypto test suite..."
cd tests && make test
# Clean build artifacts
clean:
@echo "Cleaning build artifacts..."

164
OPENSSL_MIGRATION_SUMMARY.md
View File

@ -1,164 +0,0 @@
# OpenSSL Migration Summary
## Migration Overview
Successfully migrated from mbedTLS to OpenSSL for WebSocket TLS connections while maintaining all existing functionality and backward compatibility.
**Date:** August 14, 2025
**Version:** v0.1.19 → v0.1.20
**Scope:** WebSocket TLS layer only (core crypto unchanged)
## What Changed
### 1. WebSocket Implementation
- **Replaced:** `nostr_websocket/nostr_websocket_mbedtls.c`
- **With:** `nostr_websocket/nostr_websocket_openssl.c`
- **Result:** Full OpenSSL-based TLS implementation with transport layer abstraction
### 2. Build System Updates
- **Makefile:** Updated include paths from mbedTLS to OpenSSL
- **Static Library:** x64 library now embeds OpenSSL objects for complete self-containment
- **ARM64 Library:** Requires system OpenSSL (cross-compilation complexity)
### 3. Library Size Changes
- **x64 Library:** ~2.4MB → ~15MB (includes embedded OpenSSL)
- **ARM64 Library:** ~2.4MB (unchanged, links against system OpenSSL)
## Benefits Achieved
### ✅ **Compatibility Solved**
- Eliminates all curl build issues with mbedTLS conflicts
- Uses widely-available OpenSSL (standard on most systems)
- Better ecosystem compatibility
### ✅ **Functionality Preserved**
- All WebSocket TLS features working identically
- Same API surface - no breaking changes
- All tests pass without modification
### ✅ **Self-Contained x64 Library**
- No external OpenSSL dependency for x64 users
- Still only requires `-lm` for linking
- Complete static library solution
### ✅ **Future-Proof Architecture**
- Transport layer abstraction enables easy TLS backend swapping
- Cleaner separation of concerns
- Ready for additional TLS backends if needed
## Technical Details
### Architecture Changes
```
Old: WebSocket → mbedTLS API → Network
New: WebSocket → Transport Abstraction → [TCP|OpenSSL] → Network
```
### Transport Layer Abstraction
- **TCP Transport:** Plain socket communication
- **TLS Transport:** OpenSSL-based encrypted communication
- **Interface:** Unified connect/send/recv/close operations
### OpenSSL Configuration
- **Client-side TLS only** (no server functionality)
- **Certificate verification disabled** (NOSTR doesn't require it)
- **Modern TLS methods** (TLS 1.2+, no SSLv2/v3)
- **SNI support** for proper hostname handling
## Files Modified
### New Files
- `nostr_websocket/nostr_websocket_openssl.c` - Complete OpenSSL WebSocket implementation
### Modified Files
- `Makefile` - Updated includes, library paths, and static linking
- `README.md` - Updated documentation and version info
- `VERSION` - Incremented to v0.1.20
### Removed Dependencies
- `mbedtls/` directory usage for WebSocket TLS
- mbedTLS include paths in build system
## Usage Impact
### For x64 Users (No Change)
```bash
# Still just this simple:
gcc your_app.c ./libnostr_core.a -lm -o your_app
```
### For ARM64 Users (New Requirement)
```bash
# Now requires system OpenSSL:
aarch64-linux-gnu-gcc your_app.c ./libnostr_core_arm64.a -lssl -lcrypto -lm -o your_app
```
### For Source Integration (No Change)
- Same source files to copy
- Same compilation process
- Same linking requirements
## Testing Results
### ✅ **Build Success**
- x64 library: 15,749,822 bytes (includes embedded OpenSSL)
- ARM64 library: 2,450,272 bytes (links against system OpenSSL)
- All examples compile and run successfully
### ✅ **Functionality Verified**
- Version test passes: v0.1.20
- Library initialization works
- No API breaking changes
### ✅ **Self-Containment Verified**
- x64 library requires only `-lm`
- No external OpenSSL dependency for x64
- Complete static linking successful
## Migration Strategy Used
### 1. **Limited Scope Approach**
- Only changed WebSocket TLS layer
- Left all core crypto (secp256k1, AES, ChaCha20) unchanged
- Minimal surface area for bugs
### 2. **Transport Abstraction**
- Created clean interface for TLS backends
- Enables future TLS library changes
- Better code organization
### 3. **Backward Compatibility**
- Same API surface
- Same linking requirements for x64
- Same functionality guarantees
### 4. **Self-Containment Priority**
- Embedded OpenSSL in x64 library
- Maintained zero external dependencies for primary platform
- ARM64 compromise acceptable for cross-compile complexity
## ESP32 Strategy (Future)
The migration maintains the planned ESP32 strategy:
- **Desktop Version:** Uses OpenSSL (this implementation)
- **ESP32 Version:** Will use minimal embedded TLS
- **Core Crypto:** Shared between both (secp256k1, AES, ChaCha20)
## Conclusion
The OpenSSL migration was **successful** and achieved all primary goals:
1. ✅ **Solved curl compatibility issues**
2. ✅ **Maintained API compatibility**
3. ✅ **Preserved self-containment for x64**
4. ✅ **No functionality regressions**
5. ✅ **Future-proofed architecture**
The size increase for x64 (2.4MB → 15MB) is justified by:
- Complete elimination of external dependencies
- Better ecosystem compatibility
- Robust TLS implementation
- Simplified deployment
**Recommendation:** Proceed with OpenSSL as the primary TLS backend for WebSocket connections.

64
README.md
View File

@ -1,6 +1,6 @@
# NOSTR Core Library
A comprehensive, self-contained C library for NOSTR protocol implementation with no external cryptographic dependencies.
A comprehensive, production-ready C library for NOSTR protocol implementation with OpenSSL-based cryptography and extensive protocol support.
[![Version](https://img.shields.io/badge/version-0.1.20-blue.svg)](VERSION)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](#license)
@ -11,12 +11,14 @@ A comprehensive, self-contained C library for NOSTR protocol implementation with
### Core Protocol Support
- **NIP-01**: Basic protocol flow - event creation, signing, and validation
- **NIP-04**: Encrypted direct messages (ECDH + AES-CBC + Base64)
- **NIP-05**: DNS-based internet identifier verification
- **NIP-06**: Key derivation from mnemonic (BIP39/BIP32 compliant)
- **NIP-11**: Relay information documents
- **NIP-13**: Proof of Work for events
- **NIP-44**: Versioned encrypted direct messages (ECDH + ChaCha20 + HMAC)
### Cryptographic Features
- **Self-Contained**: No external crypto dependencies (OpenSSL, libwally, etc.)
- **OpenSSL-Based**: Production-grade cryptography with OpenSSL backend
- **Secp256k1**: Complete elliptic curve implementation bundled
- **BIP39**: Mnemonic phrase generation and validation
- **BIP32**: Hierarchical deterministic key derivation
@ -27,12 +29,14 @@ A comprehensive, self-contained C library for NOSTR protocol implementation with
### Networking & Relay Support
- **Multi-Relay Queries**: Synchronous querying with progress callbacks
- **Relay Pools**: Asynchronous connection management with statistics
- **WebSocket Communication**: Full relay protocol support
- **OpenSSL WebSocket Communication**: Full relay protocol support with TLS
- **NIP-05 Identifier Verification**: DNS-based identity resolution
- **NIP-11 Relay Information**: Automatic relay capability discovery
- **Event Deduplication**: Automatic handling of duplicate events across relays
- **Connection Management**: Automatic reconnection and error handling
### Developer Experience
- **Zero Dependencies**: Only requires standard C library and math library (`-lm`)
- **Minimal Dependencies**: Only requires OpenSSL, standard C library and math library
- **Thread-Safe**: Core cryptographic functions are stateless
- **Cross-Platform**: Builds on Linux, macOS, Windows
- **Comprehensive Examples**: Ready-to-run demonstration programs
@ -139,10 +143,14 @@ make clean
- Standard C library
- Math library (`-lm`)
**Included:**
**Included & Embedded (x64):**
- cJSON (JSON parsing)
- secp256k1 (elliptic curve cryptography)
- OpenSSL (TLS for WebSocket connections)
- OpenSSL (complete cryptographic backend + TLS)
- curl (HTTP/HTTPS for NIP-05/NIP-11)
**ARM64 Additional Requirements:**
- System OpenSSL libraries (`-lssl -lcrypto`)
## 📚 API Documentation
@ -240,6 +248,30 @@ int nostr_relay_pool_run(nostr_relay_pool_t* pool, int timeout_ms);
int nostr_relay_pool_poll(nostr_relay_pool_t* pool, int timeout_ms);
```
### NIP-05 Identifier Verification
```c
// Lookup public key from NIP-05 identifier
int nostr_nip05_lookup(const char* nip05_identifier, char* pubkey_hex_out,
char*** relays, int* relay_count, int timeout_seconds);
// Verify NIP-05 identifier against public key
int nostr_nip05_verify(const char* nip05_identifier, const char* pubkey_hex,
char*** relays, int* relay_count, int timeout_seconds);
// Parse .well-known/nostr.json response
int nostr_nip05_parse_well_known(const char* json_response, const char* local_part,
char* pubkey_hex_out, char*** relays, int* relay_count);
```
### NIP-11 Relay Information
```c
// Fetch relay information document
int nostr_nip11_fetch_relay_info(const char* relay_url, nostr_relay_info_t** info_out, int timeout_seconds);
// Free relay information structure
void nostr_nip11_relay_info_free(nostr_relay_info_t* info);
```
## 📁 Examples
The library includes comprehensive examples:
@ -274,9 +306,12 @@ cd tests && make test
- **Core Functionality**: `simple_init_test`, `header_test`
- **Cryptography**: `chacha20_test`, `nostr_crypto_test`
- **NIP-04 Encryption**: `nip04_test`
- **NIP-05 Identifiers**: `nip05_test`
- **NIP-11 Relay Info**: `nip11_test`
- **NIP-44 Encryption**: `nip44_test`, `nip44_debug_test`
- **Key Derivation**: `nostr_test_bip32`
- **Relay Communication**: `relay_pool_test`, `sync_test`
- **HTTP/WebSocket**: `http_test`, `wss_test`
- **Proof of Work**: `test_pow_loop`
## 🏗️ Integration
@ -388,9 +423,17 @@ Current version: **0.1.20**
The library uses automatic semantic versioning based on Git tags. Each build increments the patch version automatically.
**Recent Developments:**
- **OpenSSL Migration**: Transitioned from mbedTLS to OpenSSL for improved compatibility
- **NIP-05 Support**: DNS-based internet identifier verification
- **NIP-11 Support**: Relay information document fetching and parsing
- **Enhanced WebSocket**: OpenSSL-based TLS WebSocket communication
- **Production Ready**: Comprehensive test suite and error handling
**Version Timeline:**
- `v0.1.x` - Initial development releases
- Focus on core protocol implementation and self-contained crypto
- Full NIP-01, NIP-04, NIP-06, NIP-13, NIP-44 support
- Focus on core protocol implementation and OpenSSL-based crypto
- Full NIP-01, NIP-04, NIP-05, NIP-06, NIP-11, NIP-13, NIP-44 support
## 🐛 Troubleshooting
@ -428,13 +471,14 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
## 🙏 Acknowledgments
- **NOSTR Protocol** - The decentralized social media protocol
- **OpenSSL** - Production-grade cryptographic library and TLS implementation
- **secp256k1** - Bitcoin's elliptic curve library
- **cJSON** - Lightweight JSON parser
- **mbedTLS** - Cryptographic building blocks
- **curl** - HTTP/HTTPS client library for NIP-05/NIP-11
- **NOSTR Community** - For protocol specification and feedback
---
**Built with ❤️ for the decentralized web**
*Self-contained • Zero dependencies • Production ready*
*OpenSSL-based • Minimal dependencies • Production ready*

116
WARNING_CLEANUP_REPORT.md
View File

@ -1,116 +0,0 @@
# Compiler Warning Cleanup - SUCCESS REPORT
## 🎉 All Warnings Resolved!
The nostr_core_lib now compiles with **zero compiler warnings** using `-Wall -Wextra` flags.
## ✅ Fixed Issues Summary
### 1. **Type Limits Warning** - `nostr_core/core.c`
- **Issue**: `comparison is always false due to limited range of data type [-Wtype-limits]`
- **Location**: `bech32_decode()` function, line 791
- **Problem**: Comparing `char c < 0` when `char` might be unsigned
- **Fix**: Changed `char c` to `unsigned char c` and removed redundant comparison
- **Status**: ✅ RESOLVED
### 2. **Unused Parameter Warning** - `nostr_core/nostr_crypto.c`
- **Issue**: `unused parameter 'mnemonic_size' [-Wunused-parameter]`
- **Location**: `nostr_bip39_mnemonic_from_bytes()` function
- **Problem**: Function parameter was declared but never used
- **Fix**: Removed `mnemonic_size` parameter from function signature and all call sites
- **Files Updated**:
- `nostr_core/nostr_crypto.c` (function implementation)
- `nostr_core/nostr_crypto.h` (function declaration)
- `nostr_core/core.c` (function call site)
- **Status**: ✅ RESOLVED
### 3. **Unused Constant Variable** - `nostr_core/nostr_crypto.c`
- **Issue**: `'CURVE_N' defined but not used [-Wunused-const-variable=]`
- **Location**: Line 456
- **Problem**: Constant array was defined but never referenced
- **Fix**: Removed the unused `CURVE_N` constant definition
- **Status**: ✅ RESOLVED
### 4. **Unused Variables** - `nostr_websocket/nostr_websocket_mbedtls.c`
- **Issue 1**: `unused variable 'tcp' [-Wunused-variable]` in `tcp_cleanup()`
- **Issue 2**: `unused variable 'fin' [-Wunused-variable]` in `ws_receive_frame()`
- **Fix**: Removed both unused variable declarations
- **Status**: ✅ RESOLVED
### 5. **Sign Comparison Warnings** - `nostr_websocket/nostr_websocket_mbedtls.c`
- **Issue**: `comparison of integer expressions of different signedness [-Wsign-compare]`
- **Locations**:
- `ws_parse_url()` - `path_start - url` vs `strlen(url)`
- `ws_perform_handshake()` - `len` vs `sizeof(request)`
- `ws_perform_handshake()` - `total_received` vs `sizeof(response) - 1`
- **Fix**: Added explicit casts to `size_t` for signed integers before comparison
- **Status**: ✅ RESOLVED
### 6. **Unused Function Warning** - `nostr_websocket/nostr_websocket_mbedtls.c`
- **Issue**: `'debug_log_cleanup' defined but not used [-Wunused-function]`
- **Problem**: Function was defined but never called
- **Fix**: Removed the unused function and its forward declaration
- **Status**: ✅ RESOLVED
## 🧪 Verification Results
### Clean Build Test
```bash
make clean && make
```
**Result**: ✅ **ZERO WARNINGS** - Clean compilation
### Functionality Test
```bash
make examples && ./examples/simple_keygen
```
**Result**: ✅ **ALL EXAMPLES WORK** - Library functionality preserved
## 📊 Before vs After
### Before Cleanup:
```
Compiling: nostr_core/core.c
nostr_core/core.c:791:24: warning: comparison is always false due to limited range of data type [-Wtype-limits]
Compiling: nostr_core/nostr_crypto.c
nostr_core/nostr_crypto.c:901:59: warning: unused parameter 'mnemonic_size' [-Wunused-parameter]
nostr_core/nostr_crypto.c:456:23: warning: 'CURVE_N' defined but not used [-Wunused-const-variable=]
Compiling: nostr_websocket/nostr_websocket_mbedtls.c
nostr_websocket/nostr_websocket_mbedtls.c:485:22: warning: unused variable 'tcp' [-Wunused-variable]
nostr_websocket/nostr_websocket_mbedtls.c:760:40: warning: operand of '?:' changes signedness [-Wsign-compare]
nostr_websocket/nostr_websocket_mbedtls.c:807:13: warning: comparison of integer expressions of different signedness [-Wsign-compare]
nostr_websocket/nostr_websocket_mbedtls.c:824:27: warning: comparison of integer expressions of different signedness [-Wsign-compare]
nostr_websocket/nostr_websocket_mbedtls.c:919:13: warning: unused variable 'fin' [-Wunused-variable]
nostr_websocket/nostr_websocket_mbedtls.c:1024:13: warning: 'debug_log_cleanup' defined but not used [-Wunused-function]
Total: 9 warnings
```
### After Cleanup:
```
Compiling: nostr_core/core.c
Compiling: nostr_core/core_relays.c
Compiling: nostr_core/nostr_crypto.c
Compiling: nostr_core/nostr_secp256k1.c
Compiling: cjson/cJSON.c
Compiling: nostr_websocket/nostr_websocket_mbedtls.c
Creating static library: libnostr_core.a
Total: 0 warnings ✅
```
## 🎯 Benefits Achieved
1. **Professional Code Quality**: Clean compilation with strict compiler flags
2. **Maintainability**: Removed unused code reduces confusion for future developers
3. **Portability**: Fixed sign comparison issues improve cross-platform compatibility
4. **Performance**: Compiler can better optimize warning-free code
5. **Debugging**: Cleaner build output makes real issues more visible
## 🏆 Final Status: **COMPLETE SUCCESS**
The nostr_core_lib now compiles cleanly with zero warnings while maintaining full functionality. All examples continue to work correctly, demonstrating that the cleanup did not introduce any regressions.
**Mission Accomplished!** 🚀

28
curl-8.15.0/curl-8.15.0/Makefile
View File

@ -294,16 +294,16 @@ CC = gcc
CCDEPMODE = depmode=gcc3
CFLAGS = -Werror-implicit-function-declaration -O2 -Wno-system-headers
CFLAG_CURL_SYMBOL_HIDING = -fvisibility=hidden
CONFIGURE_OPTIONS = " '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' '--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'"
CONFIGURE_OPTIONS = " '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' '--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'"
CPP = gcc -E
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CSCOPE = cscope
CTAGS = ctags
CURLVERSION = 8.15.0
CURL_CA_BUNDLE = /etc/ssl/certs/ca-certificates.crt
CURL_CA_EMBED =
CURL_CFLAG_EXTRAS =
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX =
CURL_LIBCURL_VERSIONED_SYMBOLS_SONAME = 4
CURL_NETWORK_AND_TIME_LIBS =
@ -336,16 +336,16 @@ INSTALL_SCRIPT = ${INSTALL}
INSTALL_STRIP_PROGRAM = $(install_sh) -c -s
LCOV =
LD = /usr/bin/ld -m elf_x86_64
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_CFLAGS = -DCURL_STATICLIB
LIBCURL_PC_CFLAGS_PRIVATE = -DCURL_STATICLIB
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LIBCURL_PC_LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_LIBS_PRIVATE = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_REQUIRES = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_LIBS_PRIVATE = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_REQUIRES = zlib,openssl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,openssl
LIBOBJS =
LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBTOOL = $(SHELL) $(top_builddir)/libtool
LIPO =
LN_S = ln -s
@ -376,10 +376,10 @@ RC =
SED = /usr/bin/sed
SET_MAKE =
SHELL = /bin/bash
SSL_BACKENDS = mbedTLS
SSL_BACKENDS = OpenSSL v3+
STRIP = strip
SUPPORT_FEATURES = AsynchDNS brotli HTTPS-proxy IPv6 Largefile libz PSL SSL threadsafe UnixSockets
SUPPORT_PROTOCOLS = FILE HTTP HTTPS IPFS IPNS MQTT WS WSS
SUPPORT_FEATURES = alt-svc AsynchDNS HSTS IPv6 Largefile libz NTLM SSL threadsafe TLS-SRP UnixSockets
SUPPORT_PROTOCOLS = FILE FTP FTPS HTTP HTTPS IPFS IPNS MQTT WS WSS
TEST_NGHTTPX = nghttpx
VERSION = -
VERSIONNUM = 080f00
@ -428,7 +428,7 @@ mandir = ${datarootdir}/man
mkdir_p = $(MKDIR_P)
oldincludedir = /usr/include
pdfdir = ${docdir}
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install
program_transform_name = s,x,x,
psdir = ${docdir}
runstatedir = ${localstatedir}/run

2
curl-8.15.0/curl-8.15.0/buildinfo.txt
View File

@ -1,6 +1,6 @@
# This is a generated file. Do not edit.
buildinfo.configure.tool: configure
buildinfo.configure.args: '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' '--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'
buildinfo.configure.args: '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' '--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'
buildinfo.host: x86_64-pc-linux-gnu
buildinfo.host.cpu: x86_64
buildinfo.host.os: linux-gnu

2127
curl-8.15.0/curl-8.15.0/config.log
View File

File diff suppressed because it is too large Load Diff

75
curl-8.15.0/curl-8.15.0/config.status
View File

@ -412,7 +412,7 @@ $config_commands
Report bugs to <a suitable curl mailing list: https://curl.se/mail/>."
ac_cs_config='--disable-ftp --disable-ldap --disable-ldaps --disable-rtsp --disable-dict --disable-telnet --disable-tftp --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-shared --enable-static --with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install --without-openssl --disable-ares --disable-cookies --disable-alt-svc --disable-hsts --disable-ntlm --disable-ntlm-wb --prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'
ac_cs_config='--disable-shared --enable-static --with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install --without-libpsl --without-brotli --disable-ldap --disable-ldaps --disable-rtsp --disable-proxy --disable-dict --disable-telnet --disable-tftp --disable-pop3 --disable-imap --disable-smb --disable-smtp --disable-gopher --disable-manual --prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'
ac_cs_version="\
curl config.status -
configured by ./configure, generated by GNU Autoconf 2.71,
@ -504,7 +504,7 @@ if $ac_cs_silent; then
fi
if $ac_cs_recheck; then
set X /bin/bash './configure' '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' '--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install' $ac_configure_extra_args --no-create --no-recursion
set X /bin/bash './configure' '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' '--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install' $ac_configure_extra_args --no-create --no-recursion
shift
\printf "%s\n" "running CONFIG_SHELL=/bin/bash $*" >&6
CONFIG_SHELL='/bin/bash'
@ -878,26 +878,26 @@ S["am__EXEEXT_FALSE"]=""
S["am__EXEEXT_TRUE"]="#"
S["LTLIBOBJS"]=""
S["LIBOBJS"]=""
S["CURL_CPP"]="gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include"
S["SSL_BACKENDS"]="mbedTLS"
S["SUPPORT_PROTOCOLS"]="FILE HTTP HTTPS IPFS IPNS MQTT WS WSS"
S["SUPPORT_FEATURES"]="AsynchDNS brotli HTTPS-proxy IPv6 Largefile libz PSL SSL threadsafe UnixSockets"
S["LIBCURL_PC_LIBS"]="-lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz "
S["LIBCURL_PC_REQUIRES"]="zlib,libbrotlidec,libbrotlicommon,libpsl"
S["LIBCURL_PC_REQUIRES_PRIVATE"]="zlib,libbrotlidec,libbrotlicommon,libpsl"
S["CURL_CPP"]="gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include"
S["SSL_BACKENDS"]="OpenSSL v3+"
S["SUPPORT_PROTOCOLS"]="FILE FTP FTPS HTTP HTTPS IPFS IPNS MQTT WS WSS"
S["SUPPORT_FEATURES"]="alt-svc AsynchDNS HSTS IPv6 Largefile libz NTLM SSL threadsafe TLS-SRP UnixSockets"
S["LIBCURL_PC_LIBS"]="-lssl -lcrypto -lssl -lcrypto -lz "
S["LIBCURL_PC_REQUIRES"]="zlib,openssl"
S["LIBCURL_PC_REQUIRES_PRIVATE"]="zlib,openssl"
S["ENABLE_STATIC"]="yes"
S["ENABLE_SHARED"]="no"
S["CROSSCOMPILING_FALSE"]=""
S["CROSSCOMPILING_TRUE"]="#"
S["BLANK_AT_MAKETIME"]=""
S["CURL_NETWORK_AND_TIME_LIBS"]=""
S["LIBCURL_PC_LIBS_PRIVATE"]="-lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz"
S["LIBCURL_PC_LDFLAGS_PRIVATE"]="-L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib"
S["LIBCURL_PC_LIBS_PRIVATE"]="-lssl -lcrypto -lssl -lcrypto -lz"
S["LIBCURL_PC_LDFLAGS_PRIVATE"]="-L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64"
S["CFLAG_CURL_SYMBOL_HIDING"]="-fvisibility=hidden"
S["DOING_CURL_SYMBOL_HIDING_FALSE"]="#"
S["DOING_CURL_SYMBOL_HIDING_TRUE"]=""
S["USE_MANUAL_FALSE"]="#"
S["USE_MANUAL_TRUE"]=""
S["USE_MANUAL_FALSE"]=""
S["USE_MANUAL_TRUE"]="#"
S["BUILD_DOCS_FALSE"]="#"
S["BUILD_DOCS_TRUE"]=""
S["PERL"]="/usr/bin/perl"
@ -915,8 +915,8 @@ S["CURL_LIBCURL_VERSIONED_SYMBOLS_SONAME"]="4"
S["CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX"]=""
S["USE_GSASL_FALSE"]=""
S["USE_GSASL_TRUE"]="#"
S["USE_LIBPSL_FALSE"]="#"
S["USE_LIBPSL_TRUE"]=""
S["USE_LIBPSL_FALSE"]=""
S["USE_LIBPSL_TRUE"]="#"
S["CURL_CA_EMBED_SET_FALSE"]=""
S["CURL_CA_EMBED_SET_TRUE"]="#"
S["CURL_CA_EMBED"]=""
@ -1027,8 +1027,8 @@ S["CPP"]="gcc -E"
S["OBJEXT"]="o"
S["EXEEXT"]=""
S["ac_ct_CC"]="gcc"
S["CPPFLAGS"]="-D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include"
S["LDFLAGS"]="-L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib"
S["CPPFLAGS"]="-D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include"
S["LDFLAGS"]="-L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64"
S["CFLAGS"]="-Werror-implicit-function-declaration -O2 -Wno-system-headers"
S["CC"]="gcc"
S["INSTALL_DATA"]="${INSTALL} -m 644"
@ -1039,10 +1039,10 @@ S["AR"]="/usr/bin/ar"
S["EGREP"]="/usr/bin/grep -E"
S["GREP"]="/usr/bin/grep"
S["SED"]="/usr/bin/sed"
S["CONFIGURE_OPTIONS"]="\" '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disab"\
"le-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_co"\
"re_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' "\
"'--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'\""
S["CONFIGURE_OPTIONS"]="\" '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' "\
"'--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--dis"\
"able-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCodi"\
"ng/nostr_core_lib/curl-install'\""
S["CURLDEBUG_FALSE"]=""
S["CURLDEBUG_TRUE"]="#"
S["DEBUGBUILD_FALSE"]=""
@ -1057,7 +1057,7 @@ S["MAINTAINER_MODE_TRUE"]="#"
S["target_alias"]=""
S["host_alias"]=""
S["build_alias"]=""
S["LIBS"]="-lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz"
S["LIBS"]="-lssl -lcrypto -lssl -lcrypto -lz"
S["ECHO_T"]=""
S["ECHO_N"]="-n"
S["ECHO_C"]=""
@ -1083,7 +1083,7 @@ S["libexecdir"]="${exec_prefix}/libexec"
S["sbindir"]="${exec_prefix}/sbin"
S["bindir"]="${exec_prefix}/bin"
S["program_transform_name"]="s,x,x,"
S["prefix"]="/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install"
S["prefix"]="/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install"
S["exec_prefix"]="${prefix}"
S["PACKAGE_URL"]=""
S["PACKAGE_BUGREPORT"]="a suitable curl mailing list: https://curl.se/mail/"
@ -1158,15 +1158,16 @@ D["VERSION"]=" \"-\""
D["CURL_OS"]=" \"x86_64-pc-linux-gnu\""
D["HAVE_DLFCN_H"]=" 1"
D["LT_OBJDIR"]=" \".libs/\""
D["CURL_DISABLE_FTP"]=" 1"
D["CURL_DISABLE_LDAP"]=" 1"
D["CURL_DISABLE_LDAPS"]=" 1"
D["CURL_DISABLE_RTSP"]=" 1"
D["CURL_DISABLE_PROXY"]=" 1"
D["CURL_DISABLE_DICT"]=" 1"
D["CURL_DISABLE_TELNET"]=" 1"
D["CURL_DISABLE_TFTP"]=" 1"
D["CURL_DISABLE_POP3"]=" 1"
D["CURL_DISABLE_IMAP"]=" 1"
D["CURL_DISABLE_SMB"]=" 1"
D["CURL_DISABLE_SMTP"]=" 1"
D["CURL_DISABLE_GOPHER"]=" 1"
D["HAVE_SYS_TYPES_H"]=" 1"
@ -1174,17 +1175,25 @@ D["HAVE_CLOCK_GETTIME_MONOTONIC"]=" 1"
D["HAVE_SYS_TYPES_H"]=" 1"
D["HAVE_CLOCK_GETTIME_MONOTONIC_RAW"]=" 1"
D["HAVE_LIBZ"]=" 1"
D["HAVE_LIBBROTLIDEC"]=" 1"
D["HAVE_BROTLI_DECODE_H"]=" 1"
D["HAVE_BROTLI"]=" 1"
D["USE_IPV6"]=" 1"
D["HAVE_SOCKADDR_IN6_SIN6_SCOPE_ID"]=" 1"
D["HAVE_WRITABLE_ARGV"]=" 1"
D["USE_MBEDTLS"]=" 1"
D["HAVE_LIBSSL"]=" 1"
D["HAVE_OPENSSL_X509_H"]=" 1"
D["USE_OPENSSL"]=" 1"
D["HAVE_OPENSSL_RSA_H"]=" 1"
D["USE_OPENSSL"]=" 1"
D["HAVE_OPENSSL_CRYPTO_H"]=" 1"
D["USE_OPENSSL"]=" 1"
D["HAVE_OPENSSL_PEM_H"]=" 1"
D["USE_OPENSSL"]=" 1"
D["HAVE_OPENSSL_SSL_H"]=" 1"
D["USE_OPENSSL"]=" 1"
D["HAVE_OPENSSL_ERR_H"]=" 1"
D["USE_OPENSSL"]=" 1"
D["HAVE_OPENSSL_SRP"]=" 1"
D["CURL_CA_BUNDLE"]=" \"/etc/ssl/certs/ca-certificates.crt\""
D["CURL_CA_PATH"]=" \"/etc/ssl/certs\""
D["HAVE_LIBPSL_H"]=" 1"
D["USE_LIBPSL"]=" 1"
D["HAVE_SYS_TYPES_H"]=" 1"
D["HAVE_SYS_SELECT_H"]=" 1"
D["HAVE_SYS_IOCTL_H"]=" 1"
@ -1321,11 +1330,9 @@ D["HAVE_PTHREAD_H"]=" 1"
D["USE_THREADS_POSIX"]=" 1"
D["HAVE_DIRENT_H"]=" 1"
D["HAVE_OPENDIR"]=" 1"
D["CURL_DISABLE_NTLM"]=" 1"
D["USE_TLS_SRP"]=" 1"
D["USE_UNIX_SOCKETS"]=" 1"
D["CURL_DISABLE_COOKIES"]=" 1"
D["CURL_DISABLE_ALTSVC"]=" 1"
D["CURL_DISABLE_HSTS"]=" 1"
D["HAVE_SSL_SET0_WBIO"]=" 1"
D["CURL_EXTERN_SYMBOL"]=" __attribute__((__visibility__(\"default\")))"
for (key in D) D_is_set[key] = 1
FS = ""

14
curl-8.15.0/curl-8.15.0/curl-config
View File

@ -25,7 +25,7 @@
# shellcheck disable=SC2006
prefix='/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'
prefix='/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'
# Used in 'libdir'
# shellcheck disable=SC2034
exec_prefix="${prefix}"
@ -82,14 +82,14 @@ while test "$#" -gt 0; do
;;
--feature|--features)
for feature in AsynchDNS brotli HTTPS-proxy IPv6 Largefile libz PSL SSL threadsafe UnixSockets ''; do
for feature in alt-svc AsynchDNS HSTS IPv6 Largefile libz NTLM SSL threadsafe TLS-SRP UnixSockets ''; do
test -n "$feature" && echo "$feature"
done
;;
--protocols)
# shellcheck disable=SC2043
for protocol in FILE HTTP HTTPS IPFS IPNS MQTT WS WSS; do
for protocol in FILE FTP FTPS HTTP HTTPS IPFS IPNS MQTT WS WSS; do
echo "$protocol"
done
;;
@ -155,19 +155,19 @@ while test "$#" -gt 0; do
curllibdir=''
fi
if test 'Xno' = 'Xno'; then
echo "${curllibdir}-lcurl -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz"
echo "${curllibdir}-lcurl -lssl -lcrypto -lssl -lcrypto -lz"
else
echo "${curllibdir}-lcurl"
fi
;;
--ssl-backends)
echo 'mbedTLS'
echo 'OpenSSL v3+'
;;
--static-libs)
if test 'Xyes' != 'Xno'; then
echo "${exec_prefix}/lib/libcurl.a -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz"
echo "${exec_prefix}/lib/libcurl.a -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64 -lssl -lcrypto -lssl -lcrypto -lz"
else
echo 'curl was built with static libraries disabled' >&2
exit 1
@ -175,7 +175,7 @@ while test "$#" -gt 0; do
;;
--configure)
echo " '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' '--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'"
echo " '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' '--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'"
;;
*)

28
curl-8.15.0/curl-8.15.0/docs/Makefile
View File

@ -272,16 +272,16 @@ CC = gcc
CCDEPMODE = depmode=gcc3
CFLAGS = -Werror-implicit-function-declaration -O2 -Wno-system-headers
CFLAG_CURL_SYMBOL_HIDING = -fvisibility=hidden
CONFIGURE_OPTIONS = " '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' '--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'"
CONFIGURE_OPTIONS = " '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' '--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'"
CPP = gcc -E
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CSCOPE = cscope
CTAGS = ctags
CURLVERSION = 8.15.0
CURL_CA_BUNDLE = /etc/ssl/certs/ca-certificates.crt
CURL_CA_EMBED =
CURL_CFLAG_EXTRAS =
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX =
CURL_LIBCURL_VERSIONED_SYMBOLS_SONAME = 4
CURL_NETWORK_AND_TIME_LIBS =
@ -314,16 +314,16 @@ INSTALL_SCRIPT = ${INSTALL}
INSTALL_STRIP_PROGRAM = $(install_sh) -c -s
LCOV =
LD = /usr/bin/ld -m elf_x86_64
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_CFLAGS = -DCURL_STATICLIB
LIBCURL_PC_CFLAGS_PRIVATE = -DCURL_STATICLIB
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LIBCURL_PC_LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_LIBS_PRIVATE = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_REQUIRES = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_LIBS_PRIVATE = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_REQUIRES = zlib,openssl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,openssl
LIBOBJS =
LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBTOOL = $(SHELL) $(top_builddir)/libtool
LIPO =
LN_S = ln -s
@ -354,10 +354,10 @@ RC =
SED = /usr/bin/sed
SET_MAKE =
SHELL = /bin/bash
SSL_BACKENDS = mbedTLS
SSL_BACKENDS = OpenSSL v3+
STRIP = strip
SUPPORT_FEATURES = AsynchDNS brotli HTTPS-proxy IPv6 Largefile libz PSL SSL threadsafe UnixSockets
SUPPORT_PROTOCOLS = FILE HTTP HTTPS IPFS IPNS MQTT WS WSS
SUPPORT_FEATURES = alt-svc AsynchDNS HSTS IPv6 Largefile libz NTLM SSL threadsafe TLS-SRP UnixSockets
SUPPORT_PROTOCOLS = FILE FTP FTPS HTTP HTTPS IPFS IPNS MQTT WS WSS
TEST_NGHTTPX = nghttpx
VERSION = -
VERSIONNUM = 080f00
@ -406,7 +406,7 @@ mandir = ${datarootdir}/man
mkdir_p = $(MKDIR_P)
oldincludedir = /usr/include
pdfdir = ${docdir}
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install
program_transform_name = s,x,x,
psdir = ${docdir}
runstatedir = ${localstatedir}/run

28
curl-8.15.0/curl-8.15.0/docs/cmdline-opts/Makefile
View File

@ -240,16 +240,16 @@ CC = gcc
CCDEPMODE = depmode=gcc3
CFLAGS = -Werror-implicit-function-declaration -O2 -Wno-system-headers
CFLAG_CURL_SYMBOL_HIDING = -fvisibility=hidden
CONFIGURE_OPTIONS = " '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' '--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'"
CONFIGURE_OPTIONS = " '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' '--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'"
CPP = gcc -E
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CSCOPE = cscope
CTAGS = ctags
CURLVERSION = 8.15.0
CURL_CA_BUNDLE = /etc/ssl/certs/ca-certificates.crt
CURL_CA_EMBED =
CURL_CFLAG_EXTRAS =
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX =
CURL_LIBCURL_VERSIONED_SYMBOLS_SONAME = 4
CURL_NETWORK_AND_TIME_LIBS =
@ -282,16 +282,16 @@ INSTALL_SCRIPT = ${INSTALL}
INSTALL_STRIP_PROGRAM = $(install_sh) -c -s
LCOV =
LD = /usr/bin/ld -m elf_x86_64
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_CFLAGS = -DCURL_STATICLIB
LIBCURL_PC_CFLAGS_PRIVATE = -DCURL_STATICLIB
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LIBCURL_PC_LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_LIBS_PRIVATE = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_REQUIRES = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_LIBS_PRIVATE = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_REQUIRES = zlib,openssl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,openssl
LIBOBJS =
LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBTOOL = $(SHELL) $(top_builddir)/libtool
LIPO =
LN_S = ln -s
@ -322,10 +322,10 @@ RC =
SED = /usr/bin/sed
SET_MAKE =
SHELL = /bin/bash
SSL_BACKENDS = mbedTLS
SSL_BACKENDS = OpenSSL v3+
STRIP = strip
SUPPORT_FEATURES = AsynchDNS brotli HTTPS-proxy IPv6 Largefile libz PSL SSL threadsafe UnixSockets
SUPPORT_PROTOCOLS = FILE HTTP HTTPS IPFS IPNS MQTT WS WSS
SUPPORT_FEATURES = alt-svc AsynchDNS HSTS IPv6 Largefile libz NTLM SSL threadsafe TLS-SRP UnixSockets
SUPPORT_PROTOCOLS = FILE FTP FTPS HTTP HTTPS IPFS IPNS MQTT WS WSS
TEST_NGHTTPX = nghttpx
VERSION = -
VERSIONNUM = 080f00
@ -374,7 +374,7 @@ mandir = ${datarootdir}/man
mkdir_p = $(MKDIR_P)
oldincludedir = /usr/include
pdfdir = ${docdir}
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install
program_transform_name = s,x,x,
psdir = ${docdir}
runstatedir = ${localstatedir}/run

6809
curl-8.15.0/curl-8.15.0/docs/cmdline-opts/curl.1 Normal file
View File

File diff suppressed because it is too large Load Diff

90
curl-8.15.0/curl-8.15.0/docs/curl-config.1 Normal file
View File

@ -0,0 +1,90 @@
.\" generated by cd2nroff 0.1 from curl-config.md
.TH curl-config 1 "2025-08-14" curl-config
.SH NAME
curl\-config \- Get information about a libcurl installation
.SH SYNOPSIS
\fBcurl\-config [options]\fP
.SH DESCRIPTION
\fBcurl\-config\fP
displays information about the curl and libcurl installation.
.SH OPTIONS
.IP --ca
Displays the built\-in path to the CA cert bundle this libcurl uses.
.IP --cc
Displays the compiler used to build libcurl.
.IP --cflags
Set of compiler options (CFLAGS) to use when compiling files that use
libcurl. Currently that is only the include path to the curl include files.
.IP "--checkfor [version]"
Specify the oldest possible libcurl version string you want, and this script
returns 0 if the current installation is new enough or it returns 1 and
outputs a text saying that the current version is not new enough. (Added in
7.15.4)
.IP --configure
Displays the arguments given to configure when building curl.
.IP --feature
Lists what particular main features the installed libcurl was built with. At
the time of writing, this list may include SSL, KRB4 or IPv6. Do not assume
any particular order. The keywords are separated by newlines. There may be
none, one, or several keywords in the list.
.IP --help
Displays the available options.
.IP --libs
Shows the complete set of libs and other linker options you need in order to
link your application with libcurl.
.IP --prefix
This is the prefix used when libcurl was installed. libcurl is then installed
in $prefix/lib and its header files are installed in $prefix/include and so
on. The prefix is set with \fIconfigure \--prefix\fP.
.IP --protocols
Lists what particular protocols the installed libcurl was built to support. At
the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE,
TELNET, LDAP, DICT and many more. Do not assume any particular order. The
protocols are listed using uppercase and are separated by newlines. There may
be none, one, or several protocols in the list. (Added in 7.13.0)
.IP --ssl-backends
Lists the SSL backends that were enabled when libcurl was built. It might be
no, one or several names. If more than one name, they appear comma\-separated.
(Added in 7.58.0)
.IP --static-libs
Shows the complete set of libs and other linker options you need in order to
link your application with libcurl statically. (Added in 7.17.1)
.IP --version
Outputs version information about the installed libcurl.
.IP --vernum
Outputs version information about the installed libcurl, in numerical mode.
This shows the version number, in hexadecimal, using 8 bits for each part:
major, minor, and patch numbers. This makes libcurl 7.7.4 appear as 070704 and
libcurl 12.13.14 appear as 0c0d0e... Note that the initial zero might be
omitted. (This option was broken in the 7.15.0 release.)
.SH EXAMPLES
What linker options do I need when I link with libcurl?
.nf
$ curl-config --libs
.fi
What compiler options do I need when I compile using libcurl functions?
.nf
$ curl-config --cflags
.fi
How do I know if libcurl was built with SSL support?
.nf
$ curl-config --feature | grep SSL
.fi
What\(aqs the installed libcurl version?
.nf
$ curl-config --version
.fi
How do I build a single file with a one\-line command?
.nf
$ `curl-config --cc --cflags` -o example source.c `curl-config --libs`
.SH SEE ALSO
.BR curl (1)

26
curl-8.15.0/curl-8.15.0/docs/examples/Makefile
View File

@ -852,16 +852,16 @@ CCDEPMODE = depmode=gcc3
# This might hold -Werror
CFLAGS = -Werror-implicit-function-declaration -O2 -Wno-system-headers
CFLAG_CURL_SYMBOL_HIDING = -fvisibility=hidden
CONFIGURE_OPTIONS = " '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' '--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'"
CONFIGURE_OPTIONS = " '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' '--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'"
CPP = gcc -E
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CSCOPE = cscope
CTAGS = ctags
CURLVERSION = 8.15.0
CURL_CA_BUNDLE = /etc/ssl/certs/ca-certificates.crt
CURL_CA_EMBED =
CURL_CFLAG_EXTRAS =
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX =
CURL_LIBCURL_VERSIONED_SYMBOLS_SONAME = 4
CURL_NETWORK_AND_TIME_LIBS =
@ -894,14 +894,14 @@ INSTALL_SCRIPT = ${INSTALL}
INSTALL_STRIP_PROGRAM = $(install_sh) -c -s
LCOV =
LD = /usr/bin/ld -m elf_x86_64
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_CFLAGS = -DCURL_STATICLIB
LIBCURL_PC_CFLAGS_PRIVATE = -DCURL_STATICLIB
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LIBCURL_PC_LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_LIBS_PRIVATE = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_REQUIRES = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_LIBS_PRIVATE = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_REQUIRES = zlib,openssl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,openssl
LIBOBJS =
# Prevent LIBS from being used for all link targets
@ -936,10 +936,10 @@ RC =
SED = /usr/bin/sed
SET_MAKE =
SHELL = /bin/bash
SSL_BACKENDS = mbedTLS
SSL_BACKENDS = OpenSSL v3+
STRIP = strip
SUPPORT_FEATURES = AsynchDNS brotli HTTPS-proxy IPv6 Largefile libz PSL SSL threadsafe UnixSockets
SUPPORT_PROTOCOLS = FILE HTTP HTTPS IPFS IPNS MQTT WS WSS
SUPPORT_FEATURES = alt-svc AsynchDNS HSTS IPv6 Largefile libz NTLM SSL threadsafe TLS-SRP UnixSockets
SUPPORT_PROTOCOLS = FILE FTP FTPS HTTP HTTPS IPFS IPNS MQTT WS WSS
TEST_NGHTTPX = nghttpx
VERSION = -
VERSIONNUM = 080f00
@ -988,7 +988,7 @@ mandir = ${datarootdir}/man
mkdir_p = $(MKDIR_P)
oldincludedir = /usr/include
pdfdir = ${docdir}
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install
program_transform_name = s,x,x,
psdir = ${docdir}
runstatedir = ${localstatedir}/run

28
curl-8.15.0/curl-8.15.0/docs/libcurl/Makefile
View File

@ -301,16 +301,16 @@ CC = gcc
CCDEPMODE = depmode=gcc3
CFLAGS = -Werror-implicit-function-declaration -O2 -Wno-system-headers
CFLAG_CURL_SYMBOL_HIDING = -fvisibility=hidden
CONFIGURE_OPTIONS = " '--disable-ftp' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smtp' '--disable-gopher' '--disable-shared' '--enable-static' '--with-mbedtls=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install' '--without-openssl' '--disable-ares' '--disable-cookies' '--disable-alt-svc' '--disable-hsts' '--disable-ntlm' '--disable-ntlm-wb' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install'"
CONFIGURE_OPTIONS = " '--disable-shared' '--enable-static' '--with-openssl=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-install' '--without-libpsl' '--without-brotli' '--disable-ldap' '--disable-ldaps' '--disable-rtsp' '--disable-proxy' '--disable-dict' '--disable-telnet' '--disable-tftp' '--disable-pop3' '--disable-imap' '--disable-smb' '--disable-smtp' '--disable-gopher' '--disable-manual' '--prefix=/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install'"
CPP = gcc -E
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CPPFLAGS = -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CSCOPE = cscope
CTAGS = ctags
CURLVERSION = 8.15.0
CURL_CA_BUNDLE = /etc/ssl/certs/ca-certificates.crt
CURL_CA_EMBED =
CURL_CFLAG_EXTRAS =
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/include
CURL_CPP = gcc -E -D_GNU_SOURCE -isystem /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/include
CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX =
CURL_LIBCURL_VERSIONED_SYMBOLS_SONAME = 4
CURL_NETWORK_AND_TIME_LIBS =
@ -343,16 +343,16 @@ INSTALL_SCRIPT = ${INSTALL}
INSTALL_STRIP_PROGRAM = $(install_sh) -c -s
LCOV =
LD = /usr/bin/ld -m elf_x86_64
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LDFLAGS = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_CFLAGS = -DCURL_STATICLIB
LIBCURL_PC_CFLAGS_PRIVATE = -DCURL_STATICLIB
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../../mbedtls-install/lib
LIBCURL_PC_LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_LIBS_PRIVATE = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBCURL_PC_REQUIRES = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,libbrotlidec,libbrotlicommon,libpsl
LIBCURL_PC_LDFLAGS_PRIVATE = -L/home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/openssl-3.4.2/../openssl-install/lib64
LIBCURL_PC_LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_LIBS_PRIVATE = -lssl -lcrypto -lssl -lcrypto -lz
LIBCURL_PC_REQUIRES = zlib,openssl
LIBCURL_PC_REQUIRES_PRIVATE = zlib,openssl
LIBOBJS =
LIBS = -lpsl -lmbedtls -lmbedx509 -lmbedcrypto -lbrotlidec -lz
LIBS = -lssl -lcrypto -lssl -lcrypto -lz
LIBTOOL = $(SHELL) $(top_builddir)/libtool
LIPO =
LN_S = ln -s
@ -383,10 +383,10 @@ RC =
SED = /usr/bin/sed
SET_MAKE =
SHELL = /bin/bash
SSL_BACKENDS = mbedTLS
SSL_BACKENDS = OpenSSL v3+
STRIP = strip
SUPPORT_FEATURES = AsynchDNS brotli HTTPS-proxy IPv6 Largefile libz PSL SSL threadsafe UnixSockets
SUPPORT_PROTOCOLS = FILE HTTP HTTPS IPFS IPNS MQTT WS WSS
SUPPORT_FEATURES = alt-svc AsynchDNS HSTS IPv6 Largefile libz NTLM SSL threadsafe TLS-SRP UnixSockets
SUPPORT_PROTOCOLS = FILE FTP FTPS HTTP HTTPS IPFS IPNS MQTT WS WSS
TEST_NGHTTPX = nghttpx
VERSION = -
VERSIONNUM = 080f00
@ -435,7 +435,7 @@ mandir = ${datarootdir}/man
mkdir_p = $(MKDIR_P)
oldincludedir = /usr/include
pdfdir = ${docdir}
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-8.15.0/curl-8.15.0/../curl-install
prefix = /home/teknari/Sync/Programming/VibeCoding/nostr_core_lib/curl-install
program_transform_name = s,x,x,
psdir = ${docdir}
runstatedir = ${localstatedir}/run

61
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_cleanup.3 Normal file
View File

@ -0,0 +1,61 @@
.\" generated by cd2nroff 0.1 from curl_easy_cleanup.md
.TH curl_easy_cleanup 3 "2025-08-14" libcurl
.SH NAME
curl_easy_cleanup \- free an easy handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_easy_cleanup(CURL *handle);
.fi
.SH DESCRIPTION
This function is the opposite of \fIcurl_easy_init(3)\fP. It closes down and frees
all resources previously associated with this easy handle.
This call closes all connections this handle has used and possibly has kept
open until now unless the easy handle was attached to a multi handle while
doing the transfers. Do not call this function if you intend to transfer more
files, reusing handles is a key to good performance with libcurl.
Occasionally you may get your progress callback or header callback called from
within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using
\fIcurl_easy_setopt(3)\fP). Like if libcurl decides to shut down the connection and
the protocol is of a kind that requires a command/response sequence before
disconnect. Examples of such protocols are FTP, POP3 and IMAP.
Any use of the easy \fBhandle\fP after this function has been called and have
returned, is illegal.
To close an easy handle that has been used with the multi interface, make sure
to first call \fIcurl_multi_remove_handle(3)\fP to remove it from the multi handle
before it is closed.
Passing in a NULL pointer in \fIhandle\fP makes this function return immediately
with no action.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
if(res)
printf("error: %s\\n", curl_easy_strerror(res));
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
None
.SH SEE ALSO
.BR curl_easy_duphandle (3),
.BR curl_easy_init (3),
.BR curl_easy_reset (3),
.BR curl_multi_cleanup (3),
.BR curl_multi_remove_handle (3)

57
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_duphandle.3 Normal file
View File

@ -0,0 +1,57 @@
.\" generated by cd2nroff 0.1 from curl_easy_duphandle.md
.TH curl_easy_duphandle 3 "2025-08-14" libcurl
.SH NAME
curl_easy_duphandle \- clone an easy handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURL *curl_easy_duphandle(CURL *handle);
.fi
.SH DESCRIPTION
This function returns a new curl handle, a duplicate, using all the options
previously set in the input curl \fIhandle\fP. Both handles can subsequently be
used independently and they must both be freed with \fIcurl_easy_cleanup(3)\fP.
Any options that the input handle has been told to point to (as opposed to
copy) with previous calls to \fIcurl_easy_setopt(3)\fP, are pointed to by the new
handle as well. You must therefore make sure to keep the data around until
both handles have been cleaned up.
The new handle does \fBnot\fP inherit any state information, no connections, no
SSL sessions and no cookies. It also does not inherit any share object states
or options (created as if \fICURLOPT_SHARE(3)\fP was set to NULL).
If the source handle has HSTS or alt\-svc enabled, the duplicate gets data read
data from the main filename to populate the cache.
In multi\-threaded programs, this function must be called in a synchronous way,
the input handle may not be in use when cloned.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
CURL *nother;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
nother = curl_easy_duphandle(curl);
res = curl_easy_perform(nother);
curl_easy_cleanup(nother);
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.9
.SH RETURN VALUE
If this function returns NULL, something went wrong and no valid handle was
returned.
.SH SEE ALSO
.BR curl_easy_cleanup (3),
.BR curl_easy_init (3),
.BR curl_easy_reset (3),
.BR curl_global_init (3)

68
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_escape.3 Normal file
View File

@ -0,0 +1,68 @@
.\" generated by cd2nroff 0.1 from curl_easy_escape.md
.TH curl_easy_escape 3 "2025-08-14" libcurl
.SH NAME
curl_easy_escape \- URL encode a string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_easy_escape(CURL *curl, const char *string, int length);
.fi
.SH DESCRIPTION
This function converts the given input \fIstring\fP to a URL encoded string and
returns that as a new allocated string. All input characters that are not a\-z,
A\-Z, 0\-9, \(aq\-\(aq, \(aq.\(aq, \(aq_\(aq or \(aq~\(aq are converted to their "URL escaped" version
(\fB%NN\fP where \fBNN\fP is a two\-digit hexadecimal number).
If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on the input
\fIstring\fP to find out the size. This function does not accept input strings
longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB).
You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH ENCODING
libcurl is typically not aware of, nor does it care about, character
encodings. \fIcurl_easy_escape(3)\fP encodes the data byte\-by\-byte into the
URL encoded version without knowledge or care for what particular character
encoding the application or the receiving server may assume that the data
uses.
The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in
to the function is encoded correctly.
.SH URLs
URLs are by definition \fIURL encoded\fP. To create a proper URL from a set of
components that may not be URL encoded already, you cannot just URL encode the
entire URL string with \fIcurl_easy_escape(3)\fP, because it then also converts
colons, slashes and other symbols that you probably want untouched.
To create a proper URL from strings that are not already URL encoded, we
recommend using libcurl\(aqs URL API: set the pieces with \fIcurl_url_set(3)\fP and get
the final correct URL with \fIcurl_url_get(3)\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
char *output = curl_easy_escape(curl, "data to convert", 15);
if(output) {
printf("Encoded: %s\\n", output);
curl_free(output);
}
curl_easy_cleanup(curl);
}
}
.fi
.SH HISTORY
Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was
per\-handle character conversion support for some old operating systems such as
TPF, but it was otherwise ignored.
.SH AVAILABILITY
Added in curl 7.15.4
.SH RETURN VALUE
A pointer to a null\-terminated string or NULL if it failed.
.SH SEE ALSO
.BR curl_easy_unescape (3),
.BR curl_url_get (3),
.BR curl_url_set (3)

270
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_getinfo.3 Normal file
View File

@ -0,0 +1,270 @@
.\" generated by cd2nroff 0.1 from curl_easy_getinfo.md
.TH curl_easy_getinfo 3 "2025-08-14" libcurl
.SH NAME
curl_easy_getinfo \- extract information from a curl handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
.fi
.SH DESCRIPTION
Get the \fIinfo\fP kept in the \fIcurl\fP handle. The third argument \fBMUST\fP be
pointing to the specific type of the used option which is documented in each
man page of the \fIinfo\fP option. The data is stored accordingly and can be
relied upon only if this function returns CURLE_OK. Use this function after a
performed transfer if you want to get transfer related data.
You should not free the memory returned by this function unless it is
explicitly mentioned below.
.SH OPTIONS
The following information can be extracted:
.IP CURLINFO_ACTIVESOCKET
The session\(aqs active socket. See \fICURLINFO_ACTIVESOCKET(3)\fP
.IP CURLINFO_APPCONNECT_TIME
The time it took from the start until the SSL connect/handshake with the
remote host was completed as a double in number of seconds. (Added in 7.19.0)
.IP CURLINFO_APPCONNECT_TIME_T
The time it took from the start until the SSL connect/handshake with the
remote host was completed in number of microseconds. (Added in 7.60.0) See
\fICURLINFO_APPCONNECT_TIME_T(3)\fP
.IP CURLINFO_CAINFO
Get the default value for \fICURLOPT_CAINFO(3)\fP. See \fICURLINFO_CAINFO(3)\fP
.IP CURLINFO_CAPATH
Get the default value for \fICURLOPT_CAPATH(3)\fP. See \fICURLINFO_CAPATH(3)\fP
.IP CURLINFO_CERTINFO
Certificate chain. See \fICURLINFO_CERTINFO(3)\fP
.IP CURLINFO_CONDITION_UNMET
Whether or not a time conditional was met or 304 HTTP response.
See \fICURLINFO_CONDITION_UNMET(3)\fP
.IP CURLINFO_CONNECT_TIME
The time it took from the start until the connect to the remote host (or
proxy) was completed. As a double. See \fICURLINFO_CONNECT_TIME(3)\fP
.IP CURLINFO_CONNECT_TIME_T
The time it took from the start until the connect to the remote host (or
proxy) was completed. In microseconds. See \fICURLINFO_CONNECT_TIME_T(3)\fP.
.IP CURLINFO_CONN_ID
The ID of the last connection used by the transfer. (Added in 8.2.0)
See \fICURLINFO_CONN_ID(3)\fP
.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD
(\fBDeprecated\fP) Content length from the Content\-Length header.
See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD(3)\fP
.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T
Content length from the Content\-Length header.
See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP
.IP CURLINFO_CONTENT_LENGTH_UPLOAD
(\fBDeprecated\fP) Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP
.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T
Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP
.IP CURLINFO_CONTENT_TYPE
Content type from the \fIContent\-Type:\fP header. We recommend using
\fIcurl_easy_header(3)\fP instead. See \fICURLINFO_CONTENT_TYPE(3)\fP
.IP CURLINFO_COOKIELIST
List of all known cookies. See \fICURLINFO_COOKIELIST(3)\fP
.IP CURLINFO_EARLYDATA_SENT_T
Amount of TLS early data sent (in number of bytes) when
CURLSSLOPT_EARLYDATA is enabled.
.IP CURLINFO_EFFECTIVE_METHOD
Last used HTTP method. See \fICURLINFO_EFFECTIVE_METHOD(3)\fP
.IP CURLINFO_EFFECTIVE_URL
Last used URL. See \fICURLINFO_EFFECTIVE_URL(3)\fP
.IP CURLINFO_FILETIME
Remote time of the retrieved document. See \fICURLINFO_FILETIME(3)\fP
.IP CURLINFO_FILETIME_T
Remote time of the retrieved document. See \fICURLINFO_FILETIME_T(3)\fP
.IP CURLINFO_FTP_ENTRY_PATH
The entry path after logging in to an FTP server. See
\fICURLINFO_FTP_ENTRY_PATH(3)\fP
.IP CURLINFO_HEADER_SIZE
Number of bytes of all headers received. See \fICURLINFO_HEADER_SIZE(3)\fP
.IP CURLINFO_HTTPAUTH_AVAIL
Available HTTP authentication methods. See \fICURLINFO_HTTPAUTH_AVAIL(3)\fP
.IP CURLINFO_HTTPAUTH_USED
Used HTTP authentication method. See \fICURLINFO_HTTPAUTH_USED(3)\fP
.IP CURLINFO_HTTP_CONNECTCODE
Last proxy CONNECT response code. See \fICURLINFO_HTTP_CONNECTCODE(3)\fP
.IP CURLINFO_HTTP_VERSION
The http version used in the connection. See \fICURLINFO_HTTP_VERSION(3)\fP
.IP CURLINFO_LASTSOCKET
(\fBDeprecated\fP) Last socket used. See \fICURLINFO_LASTSOCKET(3)\fP
.IP CURLINFO_LOCAL_IP
Source IP address of the last connection. See \fICURLINFO_LOCAL_IP(3)\fP
.IP CURLINFO_LOCAL_PORT
Source port number of the last connection. See \fICURLINFO_LOCAL_PORT(3)\fP
.IP CURLINFO_NAMELOOKUP_TIME
Time from start until name resolving completed as a double. See
\fICURLINFO_NAMELOOKUP_TIME(3)\fP
.IP CURLINFO_NAMELOOKUP_TIME_T
Time from start until name resolving completed in number of microseconds. See
\fICURLINFO_NAMELOOKUP_TIME_T(3)\fP
.IP CURLINFO_NUM_CONNECTS
Number of new successful connections used for previous transfer.
See \fICURLINFO_NUM_CONNECTS(3)\fP
.IP CURLINFO_OS_ERRNO
The errno from the last failure to connect. See \fICURLINFO_OS_ERRNO(3)\fP
.IP CURLINFO_POSTTRANSFER_TIME_T
The time it took from the start until the last byte is sent by libcurl.
In microseconds. (Added in 8.10.0) See \fICURLINFO_POSTTRANSFER_TIME_T(3)\fP
.IP CURLINFO_PRETRANSFER_TIME
The time it took from the start until the file transfer is just about to
begin. This includes all pre\-transfer commands and negotiations that are
specific to the particular protocol(s) involved. See
\fICURLINFO_PRETRANSFER_TIME(3)\fP
.IP CURLINFO_PRETRANSFER_TIME_T
The time it took from the start until the file transfer is just about to
begin. This includes all pre\-transfer commands and negotiations that are
specific to the particular protocol(s) involved. In microseconds. See
\fICURLINFO_PRETRANSFER_TIME_T(3)\fP
.IP CURLINFO_PRIMARY_IP
Destination IP address of the last connection. See \fICURLINFO_PRIMARY_IP(3)\fP
.IP CURLINFO_PRIMARY_PORT
Destination port of the last connection. See \fICURLINFO_PRIMARY_PORT(3)\fP
.IP CURLINFO_PRIVATE
User\(aqs private data pointer. See \fICURLINFO_PRIVATE(3)\fP
.IP CURLINFO_PROTOCOL
(\fBDeprecated\fP) The protocol used for the connection. (Added in 7.52.0) See
\fICURLINFO_PROTOCOL(3)\fP
.IP CURLINFO_PROXYAUTH_AVAIL
Available HTTP proxy authentication methods. See \fICURLINFO_PROXYAUTH_AVAIL(3)\fP
.IP CURLINFO_PROXYAUTH_USED
Used HTTP proxy authentication methods. See \fICURLINFO_PROXYAUTH_USED(3)\fP
.IP CURLINFO_PROXY_ERROR
Detailed proxy error. See \fICURLINFO_PROXY_ERROR(3)\fP
.IP CURLINFO_PROXY_SSL_VERIFYRESULT
Proxy certificate verification result. See \fICURLINFO_PROXY_SSL_VERIFYRESULT(3)\fP
.IP CURLINFO_QUEUE_TIME_T
The time during which the transfer was held in a waiting queue before it could
start for real in number of microseconds. (Added in 8.6.0) See
\fICURLINFO_QUEUE_TIME_T(3)\fP
.IP CURLINFO_REDIRECT_COUNT
Total number of redirects that were followed. See \fICURLINFO_REDIRECT_COUNT(3)\fP
.IP CURLINFO_REDIRECT_TIME
The time it took for all redirection steps include name lookup, connect,
pretransfer and transfer before final transaction was started. So, this is
zero if no redirection took place. As a double. See \fICURLINFO_REDIRECT_TIME(3)\fP
.IP CURLINFO_REDIRECT_TIME_T
The time it took for all redirection steps include name lookup, connect,
pretransfer and transfer before final transaction was started. So, this is
zero if no redirection took place. In number of microseconds. See
\fICURLINFO_REDIRECT_TIME_T(3)\fP
.IP CURLINFO_REDIRECT_URL
URL a redirect would take you to, had you enabled redirects. See
\fICURLINFO_REDIRECT_URL(3)\fP
.IP CURLINFO_REFERER
Referrer header. See \fICURLINFO_REFERER(3)\fP
.IP CURLINFO_REQUEST_SIZE
Number of bytes sent in the issued HTTP requests. See \fICURLINFO_REQUEST_SIZE(3)\fP
.IP CURLINFO_RESPONSE_CODE
Last received response code. See \fICURLINFO_RESPONSE_CODE(3)\fP
.IP CURLINFO_RETRY_AFTER
The value from the Retry\-After header. See \fICURLINFO_RETRY_AFTER(3)\fP
.IP CURLINFO_RTSP_CLIENT_CSEQ
The RTSP client CSeq that is expected next. See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP
.IP CURLINFO_RTSP_CSEQ_RECV
RTSP CSeq last received. See \fICURLINFO_RTSP_CSEQ_RECV(3)\fP
.IP CURLINFO_RTSP_SERVER_CSEQ
The RTSP server CSeq that is expected next. See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP
.IP CURLINFO_RTSP_SESSION_ID
RTSP session ID. See \fICURLINFO_RTSP_SESSION_ID(3)\fP
.IP CURLINFO_SCHEME
The scheme used for the connection. (Added in 7.52.0) See \fICURLINFO_SCHEME(3)\fP
.IP CURLINFO_SIZE_DOWNLOAD
(\fBDeprecated\fP) Number of bytes downloaded. See \fICURLINFO_SIZE_DOWNLOAD(3)\fP
.IP CURLINFO_SIZE_DOWNLOAD_T
Number of bytes downloaded. See \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP
.IP CURLINFO_SIZE_UPLOAD
(\fBDeprecated\fP) Number of bytes uploaded. See \fICURLINFO_SIZE_UPLOAD(3)\fP
.IP CURLINFO_SIZE_UPLOAD_T
Number of bytes uploaded. See \fICURLINFO_SIZE_UPLOAD_T(3)\fP
.IP CURLINFO_SPEED_DOWNLOAD
(\fBDeprecated\fP) Average download speed. See \fICURLINFO_SPEED_DOWNLOAD(3)\fP
.IP CURLINFO_SPEED_DOWNLOAD_T
Average download speed. See \fICURLINFO_SPEED_DOWNLOAD_T(3)\fP
.IP CURLINFO_SPEED_UPLOAD
(\fBDeprecated\fP) Average upload speed. See \fICURLINFO_SPEED_UPLOAD(3)\fP
.IP CURLINFO_SPEED_UPLOAD_T
Average upload speed in number of bytes per second. See
\fICURLINFO_SPEED_UPLOAD_T(3)\fP
.IP CURLINFO_SSL_ENGINES
A list of OpenSSL crypto engines. See \fICURLINFO_SSL_ENGINES(3)\fP
.IP CURLINFO_SSL_VERIFYRESULT
Certificate verification result. See \fICURLINFO_SSL_VERIFYRESULT(3)\fP
.IP CURLINFO_STARTTRANSFER_TIME
The time it took from the start until the first byte is received by libcurl.
As a double. See \fICURLINFO_STARTTRANSFER_TIME(3)\fP
.IP CURLINFO_STARTTRANSFER_TIME_T
The time it took from the start until the first byte is received by libcurl.
In microseconds. See \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP
.IP CURLINFO_TLS_SESSION
(\fBDeprecated\fP) TLS session info that can be used for further processing. See
\fICURLINFO_TLS_SESSION(3)\fP. Use \fICURLINFO_TLS_SSL_PTR(3)\fP instead.
.IP CURLINFO_TLS_SSL_PTR
TLS session info that can be used for further processing. See
\fICURLINFO_TLS_SSL_PTR(3)\fP
.IP CURLINFO_TOTAL_TIME
Total time of previous transfer. See \fICURLINFO_TOTAL_TIME(3)\fP
.IP CURLINFO_TOTAL_TIME_T
Total time of previous transfer. See \fICURLINFO_TOTAL_TIME_T(3)\fP
.IP CURLINFO_USED_PROXY
Whether the proxy was used (Added in 8.7.0). See \fICURLINFO_USED_PROXY(3)\fP
.IP CURLINFO_XFER_ID
The ID of the transfer. (Added in 8.2.0) See \fICURLINFO_XFER_ID(3)\fP
.SH TIMES
An overview of the time values available from \fIcurl_easy_getinfo(3)\fP
.nf
curl_easy_perform()
|
|--QUEUE
|--|--NAMELOOKUP
|--|--|--CONNECT
|--|--|--|--APPCONNECT
|--|--|--|--|--PRETRANSFER
|--|--|--|--|--|--POSTTRANSFER
|--|--|--|--|--|--|--STARTTRANSFER
|--|--|--|--|--|--|--|--TOTAL
|--|--|--|--|--|--|--|--REDIRECT
.fi
\fICURLINFO_QUEUE_TIME_T(3)\fP, \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP,
\fICURLINFO_CONNECT_TIME_T(3)\fP, \fICURLINFO_APPCONNECT_TIME_T(3)\fP,
\fICURLINFO_PRETRANSFER_TIME_T(3)\fP, \fICURLINFO_POSTTRANSFER_TIME_T(3)\fP,
\fICURLINFO_STARTTRANSFER_TIME_T(3)\fP, \fICURLINFO_TOTAL_TIME_T(3)\fP,
\fICURLINFO_REDIRECT_TIME_T(3)\fP
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
char *ct;
/* ask for the content-type */
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
if((CURLE_OK == res) && ct)
printf("We received Content-Type: %s\\n", ct);
}
/* always cleanup */
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.4.1
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_easy_setopt (3)

134
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_header.3 Normal file
View File

@ -0,0 +1,134 @@
.\" generated by cd2nroff 0.1 from curl_easy_header.md
.TH curl_easy_header 3 "2025-08-14" libcurl
.SH NAME
curl_easy_header \- get an HTTP header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLHcode curl_easy_header(CURL *easy,
const char *name,
size_t index,
unsigned int origin,
int request,
struct curl_header **hout);
.fi
.SH DESCRIPTION
\fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in \fBhout\fP
with data for the HTTP response header \fIname\fP. The case insensitive
null\-terminated header name should be specified without colon.
\fIindex\fP 0 means asking for the first instance of the header. If the returned
header struct has \fBamount\fP set larger than 1, it means there are more
instances of the same header name available to get. Asking for a too big index
makes \fBCURLHE_BADINDEX\fP get returned.
The \fIorigin\fP argument is for specifying which headers to receive, as a single
HTTP transfer might provide headers from several different places and they may
then have different importance to the user and headers using the same name
might be used. The \fIorigin\fP is a bitmask for what header sources you want. See
the descriptions below.
The \fIrequest\fP argument tells libcurl from which request you want headers
from. A single transfer might consist of a series of HTTP requests and this
argument lets you specify which particular individual request you want the
headers from. 0 being the first request and then the number increases for
further redirects or when multi\-state authentication is used. Passing in \-1 is
a shortcut to "the last" request in the series, independently of the actual
amount of requests used.
libcurl stores and provides the actually used "correct" headers. If for
example two headers with the same name arrive and the latter overrides the
former, then only the latter is provided. If the first header survives the
second, then only the first one is provided. An application using this API
does not have to bother about multiple headers used wrongly.
The memory for the returned struct is associated with the easy handle and
subsequent calls to \fIcurl_easy_header(3)\fP clobber the struct used in the
previous calls for the same easy handle. The application needs to copy the data if
it wants to keep it around. The memory used for the struct gets freed with
calling \fIcurl_easy_cleanup(3)\fP of the easy handle.
The first line in an HTTP response is called the status line. It is not
considered a header by this function. Headers are the "name: value" lines
following the status.
This function can be used before (all) headers have been received and is fine
to call from within libcurl callbacks. It returns the state of the headers at
the time it is called.
.SH The header struct
.nf
struct curl_header {
char *name;
char *value;
size_t amount;
size_t index;
unsigned int origin;
void *anchor;
};
.fi
The data \fBname\fP field points to, is the same as the requested name, but
might have a different case.
The data \fBvalue\fP field points to, comes exactly as delivered over the
network but with leading and trailing whitespace and newlines stripped
off. The \fIvalue\fP data is null\-terminated. For legacy HTTP/1 "folded headers",
this API provides the full single value in an unfolded manner with a single
whitespace between the lines.
\fBamount\fP is how many headers using this name that exist, within the origin
and request scope asked for.
\fBindex\fP is the zero based entry number of this particular header, which in
case this header was used more than once in the requested scope can be larger
than 0 but is always less than \fBamount\fP.
The \fBorigin\fP field in the "curl_header" struct has one of the origin bits
set, indicating where from the header originates. At the time of this writing,
there are 5 bits with defined use. The undocumented 27 remaining bits are
reserved for future use and must not be assumed to have any particular value.
\fBanchor\fP is a private handle used by libcurl internals. Do not modify.
.SH ORIGINS
.IP CURLH_HEADER
The header arrived as a header from the server.
.IP CURLH_TRAILER
The header arrived as a trailer. A header that arrives after the body.
.IP CURLH_CONNECT
The header arrived in a CONNECT response. A CONNECT request is being done to
setup a transfer "through" an HTTP(S) proxy.
.IP CURLH_1XX
The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate"
response that might happen before the "real" response.
.IP CURLH_PSEUDO
The header is an HTTP/2 or HTTP/3 pseudo header
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
int main(void)
{
struct curl_header *type;
CURL *curl = curl_easy_init();
if(curl) {
CURLHcode h;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_perform(curl);
h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type);
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.83.0
.SH RETURN VALUE
This function returns a CURLHcode indicating success or error. CURLHE_OK (0)
means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR CURLINFO_CONTENT_TYPE (3),
.BR CURLOPT_HEADERFUNCTION (3),
.BR curl_easy_nextheader (3),
.BR curl_easy_perform (3),
.BR libcurl-errors (3)

58
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_init.3 Normal file
View File

@ -0,0 +1,58 @@
.\" generated by cd2nroff 0.1 from curl_easy_init.md
.TH curl_easy_init 3 "2025-08-14" libcurl
.SH NAME
curl_easy_init \- create an easy handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURL *curl_easy_init();
.fi
.SH DESCRIPTION
This function allocates and returns an easy handle. Such a handle is used as
input to other functions in the easy interface. This call must have a
corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is complete.
The easy handle is used to hold and control a single network transfer. It is
encouraged to reuse easy handles for repeated transfers.
An alternative way to get a new easy handle is to duplicate an already
existing one with \fIcurl_easy_duphandle(3)\fP, which has the upside that it gets
all the options that were set in the source handle set in the new copy as
well.
If you did not already call \fIcurl_global_init(3)\fP before calling this function,
\fIcurl_easy_init(3)\fP does it automatically. This can be lethal in multi\-threaded
cases for platforms where \fIcurl_global_init(3)\fP is not thread\-safe, and it may
then result in resource problems because there is no corresponding cleanup.
You are strongly advised to not allow this automatic behavior, by calling
\fIcurl_global_init(3)\fP yourself properly. See the description in \fIlibcurl(3)\fP of
global environment requirements for details of how to use this function.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
If this function returns NULL, something went wrong and you cannot use the
other curl functions.
.SH SEE ALSO
.BR curl_easy_cleanup (3),
.BR curl_easy_duphandle (3),
.BR curl_easy_perform (3),
.BR curl_easy_reset (3),
.BR curl_global_init (3),
.BR curl_multi_init (3)

85
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_nextheader.3 Normal file
View File

@ -0,0 +1,85 @@
.\" generated by cd2nroff 0.1 from curl_easy_nextheader.md
.TH curl_easy_nextheader 3 "2025-08-14" libcurl
.SH NAME
curl_easy_nextheader \- get the next HTTP header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
struct curl_header *curl_easy_nextheader(CURL *easy,
unsigned int origin,
int request,
struct curl_header *prev);
.fi
.SH DESCRIPTION
This function lets an application iterate over all previously received HTTP
headers.
The \fIorigin\fP argument is for specifying which headers to receive, as a single
HTTP transfer might provide headers from several different places and they may
then have different importance to the user and headers using the same name
might be used. The \fIorigin\fP is a bitmask for what header sources you want. See
the \fIcurl_easy_header(3)\fP man page for the origin descriptions.
The \fIrequest\fP argument tells libcurl from which request you want headers
from. A single transfer might consist of a series of HTTP requests and this
argument lets you specify which particular individual request you want the
headers from. 0 being the first request and then the number increases for
further redirects or when multi\-state authentication is used. Passing in \-1 is
a shortcut to "the last" request in the series, independently of the actual
amount of requests used.
It is suggested that you pass in the same \fBorigin\fP and \fBrequest\fP when
iterating over a range of headers as changing the value mid\-loop might give
you unexpected results.
If \fIprev\fP is NULL, this function returns a pointer to the first header stored
within the given scope (origin + request).
If \fIprev\fP is a pointer to a previously returned header struct,
\fIcurl_easy_nextheader(3)\fP returns a pointer the next header stored within the
given scope. This way, an application can iterate over all available headers.
The memory for the struct this points to, is owned and managed by libcurl and
is associated with the easy handle. Applications must copy the data if they
want it to survive subsequent API calls or the life\-time of the easy handle.
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
int main(void)
{
struct curl_header *prev = NULL;
struct curl_header *h;
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_perform(curl);
/* extract the normal headers from the first request */
while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) {
printf("%s: %s\\n", h->name, h->value);
prev = h;
}
/* extract the normal headers + 1xx + trailers from the last request */
unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER;
while((h = curl_easy_nextheader(curl, origin, -1, prev))) {
printf("%s: %s\\n", h->name, h->value);
prev = h;
}
}
}
.fi
.SH AVAILABILITY
Added in curl 7.83.0
.SH RETURN VALUE
This function returns the next header, or NULL when there are no more
(matching) headers or an error occurred.
If this function returns NULL when \fIprev\fP was set to NULL, then there are no
headers available within the scope to return.
.SH SEE ALSO
.BR curl_easy_header (3),
.BR curl_easy_perform (3)

38
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_option_by_id.3 Normal file
View File

@ -0,0 +1,38 @@
.\" generated by cd2nroff 0.1 from curl_easy_option_by_id.md
.TH curl_easy_option_by_id 3 "2025-08-14" libcurl
.SH NAME
curl_easy_option_by_id \- find an easy setopt option by id
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const struct curl_easyoption *curl_easy_option_by_id(CURLoption id);
.fi
.SH DESCRIPTION
Given a \fICURLoption\fP \fBid\fP, this function returns a pointer to the
\fIcurl_easyoption\fP struct, holding information about the \fIcurl_easy_setopt(3)\fP
option using that id. The option id is the \fICURLOPT_\fP prefixed ones provided
in the standard curl/curl.h header file. This function returns the non\-alias
version of the cases where there is an alias function as well.
If libcurl has no option with the given id, this function returns NULL.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
const struct curl_easyoption *opt = curl_easy_option_by_id(CURLOPT_URL);
if(opt) {
printf("This option wants type %x\\n", opt->type);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.73.0
.SH RETURN VALUE
A pointer to the \fIcurl_easyoption\fP struct for the option or NULL.
.SH SEE ALSO
.BR curl_easy_option_by_name (3),
.BR curl_easy_option_next (3),
.BR curl_easy_setopt (3)

37
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_option_by_name.3 Normal file
View File

@ -0,0 +1,37 @@
.\" generated by cd2nroff 0.1 from curl_easy_option_by_name.md
.TH curl_easy_option_by_name 3 "2025-08-14" libcurl
.SH NAME
curl_easy_option_by_name \- find an easy setopt option by name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const struct curl_easyoption *curl_easy_option_by_name(const char *name);
.fi
.SH DESCRIPTION
Given a \fBname\fP, this function returns a pointer to the \fIcurl_easyoption\fP
struct, holding information about the \fIcurl_easy_setopt(3)\fP option using that
name. The name should be specified without the \fICURLOPT_\fP prefix and the name
comparison is made case insensitive.
If libcurl has no option with the given name, this function returns NULL.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
const struct curl_easyoption *opt = curl_easy_option_by_name("URL");
if(opt) {
printf("This option wants CURLoption %x\\n", (int)opt->id);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.73.0
.SH RETURN VALUE
A pointer to the \fIcurl_easyoption\fP struct for the option or NULL.
.SH SEE ALSO
.BR curl_easy_option_by_id (3),
.BR curl_easy_option_next (3),
.BR curl_easy_setopt (3)

72
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_option_next.3 Normal file
View File

@ -0,0 +1,72 @@
.\" generated by cd2nroff 0.1 from curl_easy_option_next.md
.TH curl_easy_option_next 3 "2025-08-14" libcurl
.SH NAME
curl_easy_option_next \- iterate over easy setopt options
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const struct curl_easyoption *
curl_easy_option_next(const struct curl_easyoption *prev);
.fi
.SH DESCRIPTION
This function returns a pointer to the first or the next \fIcurl_easyoption\fP
struct, providing an ability to iterate over all known options for
\fIcurl_easy_setopt(3)\fP in this instance of libcurl.
Pass a \fBNULL\fP argument as \fBprev\fP to get the first option returned, or
pass in the current option to get the next one returned. If there is no more
option to return, \fIcurl_easy_option_next(3)\fP returns NULL.
The options returned by this functions are the ones known to this libcurl and
information about what argument type they want.
If the \fBCURLOT_FLAG_ALIAS\fP bit is set in the flags field, it means the
name is provided for backwards compatibility as an alias.
.SH struct
.nf
typedef enum {
CURLOT_LONG, /* long (a range of values) */
CURLOT_VALUES, /* (a defined set or bitmask) */
CURLOT_OFF_T, /* curl_off_t (a range of values) */
CURLOT_OBJECT, /* pointer (void *) */
CURLOT_STRING, /* (char * to null-terminated buffer) */
CURLOT_SLIST, /* (struct curl_slist *) */
CURLOT_CBPTR, /* (void * passed as-is to a callback) */
CURLOT_BLOB, /* blob (struct curl_blob *) */
CURLOT_FUNCTION /* function pointer */
} curl_easytype;
/* The CURLOPTTYPE_* id ranges can still be used to figure out what type/size
to use for curl_easy_setopt() for the given id */
struct curl_easyoption {
const char *name;
CURLoption id;
curl_easytype type;
unsigned int flags;
};
.fi
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
/* iterate over all available options */
const struct curl_easyoption *opt;
opt = curl_easy_option_next(NULL);
while(opt) {
printf("Name: %s\\n", opt->name);
opt = curl_easy_option_next(opt);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.73.0
.SH RETURN VALUE
A pointer to the \fIcurl_easyoption\fP struct for the next option or NULL if
no more options.
.SH SEE ALSO
.BR curl_easy_option_by_id (3),
.BR curl_easy_option_by_name (3),
.BR curl_easy_setopt (3)

114
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_pause.3 Normal file
View File

@ -0,0 +1,114 @@
.\" generated by cd2nroff 0.1 from curl_easy_pause.md
.TH curl_easy_pause 3 "2025-08-14" libcurl
.SH NAME
curl_easy_pause \- pause and unpause a connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_pause(CURL *handle, int bitmask );
.fi
.SH DESCRIPTION
Using this function, you can explicitly mark a running connection to get
paused, and you can unpause a connection that was previously paused. Unlike
most other libcurl functions, \fIcurl_easy_pause(3)\fP can be used from within
callbacks.
A connection can be paused by using this function or by letting the read or
the write callbacks return the proper magic return code
(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback
that returns pause signals to the library that it could not take care of any
data at all, and that data is then delivered again to the callback when the
transfer is unpaused.
While it may feel tempting, take care and notice that you cannot call this
function from another thread. To unpause, you may for example call it from the
progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP).
When this function is called to unpause receiving, the write callback might
get called before this function returns to deliver cached content. When
libcurl delivers such cached data to the write callback, it is delivered as
fast as possible, which may overstep the boundary set in
\fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc.
The \fBhandle\fP argument identifies the transfer you want to pause or
unpause.
A paused transfer is excluded from low speed cancels via the
\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer resets the
time period required for the low speed limit to be met.
The \fBbitmask\fP argument is a set of bits that sets the new state of the
connection. The following bits can be used:
.IP CURLPAUSE_RECV
Pause receiving data. There is no data received on this connection until this
function is called again without this bit set. Thus, the write callback
(\fICURLOPT_WRITEFUNCTION(3)\fP) is not called.
.IP CURLPAUSE_SEND
Pause sending data. There is no data sent on this connection until this
function is called again without this bit set. Thus, the read callback
(\fICURLOPT_READFUNCTION(3)\fP) is not called.
.IP CURLPAUSE_ALL
Convenience define that pauses both directions.
.IP CURLPAUSE_CONT
Convenience define that unpauses both directions.
.SH LIMITATIONS
The pausing of transfers does not work with protocols that work without
network connectivity, like FILE://. Trying to pause such a transfer, in any
direction, might cause problems or error.
.SH MULTIPLEXED
When a connection is used multiplexed, like for HTTP/2, and one of the
transfers over the connection is paused and the others continue flowing,
libcurl might end up buffering contents for the paused transfer. It has to do
this because it needs to drain the socket for the other transfers and the
already announced window size for the paused transfer allows the server to
continue sending data up to that window size amount. By default, libcurl
announces a 32 megabyte window size, which thus can make libcurl end up
buffering 32 megabyte of data for a paused stream.
When such a paused stream is unpaused again, any buffered data is delivered
first.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
/* pause a transfer in both directions */
curl_easy_pause(curl, CURLPAUSE_RECV | CURLPAUSE_SEND);
}
}
.fi
.SH MEMORY USE
When pausing a download transfer by returning the magic return code from a
write callback, the read data is already in libcurl\(aqs internal buffers so it
has to keep it in an allocated buffer until the receiving is again unpaused
using this function.
If the downloaded data is compressed and is asked to get uncompressed
automatically on download, libcurl continues to uncompress the entire
downloaded chunk and it caches the data uncompressed. This has the side\-
effect that if you download something that is compressed a lot, it can result
in a large data amount needing to be allocated to save the data during the
pause. Consider not using paused receiving if you allow libcurl to uncompress
data automatically.
If the download is done with HTTP/2 or HTTP/3, there is up to a stream window
size worth of data that curl cannot stop but instead needs to cache while the
transfer is paused. This means that if a window size of 64 MB is used, libcurl
might end up having to cache 64 MB of data.
.SH AVAILABILITY
Added in curl 7.18.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_easy_cleanup (3),
.BR curl_easy_reset (3)

70
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_perform.3 Normal file
View File

@ -0,0 +1,70 @@
.\" generated by cd2nroff 0.1 from curl_easy_perform.md
.TH curl_easy_perform 3 "2025-08-14" libcurl
.SH NAME
curl_easy_perform \- perform a blocking network transfer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_perform(CURL *easy_handle);
.fi
.SH DESCRIPTION
\fIcurl_easy_perform(3)\fP performs a network transfer in a blocking manner and
returns when done, or earlier if it fails. For non\-blocking behavior, see
\fIcurl_multi_perform(3)\fP.
Invoke this function after \fIcurl_easy_init(3)\fP and all the \fIcurl_easy_setopt(3)\fP
calls are made, and it performs the transfer as described in the options. It
must be called with the same \fBeasy_handle\fP as input as the \fIcurl_easy_init(3)\fP
call returned.
You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the same
\fBeasy_handle\fP. If you intend to transfer more than one file, you are even
encouraged to do so. libcurl attempts to reuse existing connections for the
following transfers, thus making the operations faster, less CPU intense and
using less network resources. You probably want to use \fIcurl_easy_setopt(3)\fP
between the invokes to set options for the following \fIcurl_easy_perform(3)\fP
call.
You must never call this function simultaneously from two places using the
same \fBeasy_handle\fP. Let the function return first before invoking it another
time. If you want parallel transfers, you must use several curl easy_handles.
A network transfer moves data to a peer or from a peer. An application tells
libcurl how to receive data by setting the \fICURLOPT_WRITEFUNCTION(3)\fP and
\fICURLOPT_WRITEDATA(3)\fP options. To tell libcurl what data to send, there are a
few more alternatives but two common ones are \fICURLOPT_READFUNCTION(3)\fP and
\fICURLOPT_POSTFIELDS(3)\fP.
While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by
\fIcurl_easy_perform(3)\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_easy_init (3),
.BR curl_easy_setopt (3),
.BR curl_multi_add_handle (3),
.BR curl_multi_perform (3),
.BR libcurl-errors (3)

88
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_recv.3 Normal file
View File

@ -0,0 +1,88 @@
.\" generated by cd2nroff 0.1 from curl_easy_recv.md
.TH curl_easy_recv 3 "2025-08-14" libcurl
.SH NAME
curl_easy_recv \- receives raw data on an "easy" connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n);
.fi
.SH DESCRIPTION
This function receives raw data from the established connection. You may use
it together with \fIcurl_easy_send(3)\fP to implement custom protocols using
libcurl. This functionality can be particularly useful if you use proxies
and/or SSL encryption: libcurl takes care of proxy negotiation and connection
setup.
\fBbuffer\fP is a pointer to your buffer memory that gets populated by the
received data. \fBbuflen\fP is the maximum amount of data you can get in that
buffer. The variable \fBn\fP points to receives the number of received bytes.
To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before
calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that
\fIcurl_easy_recv(3)\fP does not work on connections that were created without
this option.
The call returns \fBCURLE_AGAIN\fP if there is no data to read \- the socket is
used in non\-blocking mode internally. When \fBCURLE_AGAIN\fP is returned, use
your operating system facilities like \fIselect(2)\fP to wait for data. The
socket may be obtained using \fIcurl_easy_getinfo(3)\fP with
\fICURLINFO_ACTIVESOCKET(3)\fP.
Wait on the socket only if \fIcurl_easy_recv(3)\fP returns \fBCURLE_AGAIN\fP.
The reason for this is libcurl or the SSL library may internally cache some
data, therefore you should call \fIcurl_easy_recv(3)\fP until all data is
read which would include any cached data.
Furthermore if you wait on the socket and it tells you there is data to read,
\fIcurl_easy_recv(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was
read was for internal SSL processing, and no other data is available.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Do not do the transfer - only connect to host */
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
char buf[256];
size_t nread;
curl_socket_t sockfd;
/* Extract the socket from the curl handle - we need it for waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
/* read data */
res = curl_easy_recv(curl, buf, sizeof(buf), &nread);
}
}
}
.fi
.SH AVAILABILITY
Added in curl 7.18.2
.SH RETURN VALUE
On success, returns \fBCURLE_OK\fP, stores the received data into
\fBbuffer\fP, and the number of bytes it actually read into \fB*n\fP.
On failure, returns the appropriate error code.
The function may return \fBCURLE_AGAIN\fP. In this case, use your operating
system facilities to wait until data can be read, and retry.
Reading exactly 0 bytes indicates a closed connection.
If there is no socket available to use from the previous transfer, this
function returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
.SH SEE ALSO
.BR curl_easy_getinfo (3),
.BR curl_easy_perform (3),
.BR curl_easy_send (3),
.BR curl_easy_setopt (3)

41
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_reset.3 Normal file
View File

@ -0,0 +1,41 @@
.\" generated by cd2nroff 0.1 from curl_easy_reset.md
.TH curl_easy_reset 3 "2025-08-14" libcurl
.SH NAME
curl_easy_reset \- reset all options of a libcurl session handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_easy_reset(CURL *handle);
.fi
.SH DESCRIPTION
Re\-initializes all options previously set on a specified curl handle to the
default values. This puts back the handle to the same state as it was in when
it was just created with \fIcurl_easy_init(3)\fP.
It does not change the following information kept in the handle: live
connections, the Session ID cache, the DNS cache, the cookies, the shares or
the alt\-svc cache.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
/* ... the handle is used and options are set ... */
curl_easy_reset(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.12.1
.SH RETURN VALUE
Nothing
.SH SEE ALSO
.BR curl_easy_cleanup (3),
.BR curl_easy_duphandle (3),
.BR curl_easy_init (3),
.BR curl_easy_setopt (3)

80
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_send.3 Normal file
View File

@ -0,0 +1,80 @@
.\" generated by cd2nroff 0.1 from curl_easy_send.md
.TH curl_easy_send 3 "2025-08-14" libcurl
.SH NAME
curl_easy_send \- sends raw data over an "easy" connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_send(CURL *curl, const void *buffer,
size_t buflen, size_t *n);
.fi
.SH DESCRIPTION
This function sends arbitrary data over the established connection. You may
use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols
using libcurl. This functionality can be particularly useful if you use
proxies and/or SSL encryption: libcurl takes care of proxy negotiation and
connection setup.
\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want
sent. The variable \fBn\fP points to receives the number of sent bytes.
To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before
calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that
\fIcurl_easy_send(3)\fP does not work on connections that were created without
this option.
The call returns \fBCURLE_AGAIN\fP if it is not possible to send data right now
- the socket is used in non\-blocking mode internally. When \fBCURLE_AGAIN\fP
is returned, use your operating system facilities like \fIselect(2)\fP to wait
until the socket is writable. The socket may be obtained using
\fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP.
Furthermore if you wait on the socket and it tells you it is writable,
\fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was sent
was for internal SSL processing, and no other data could be sent.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Do not do the transfer - only connect to host */
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
curl_socket_t sockfd;
size_t sent;
/* Extract the socket from the curl handle - we need it for waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
/* send data */
res = curl_easy_send(curl, "hello", 5, &sent);
}
}
}
.fi
.SH AVAILABILITY
Added in curl 7.18.2
.SH RETURN VALUE
On success, returns \fBCURLE_OK\fP and stores the number of bytes actually
sent into \fB*n\fP. Note that this may be less than the amount you wanted to
send.
On failure, returns the appropriate error code.
This function may return \fBCURLE_AGAIN\fP. In this case, use your operating
system facilities to wait until the socket is writable, and retry.
If there is no socket available to use from the previous transfer, this
function returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
.SH SEE ALSO
.BR curl_easy_getinfo (3),
.BR curl_easy_perform (3),
.BR curl_easy_recv (3),
.BR curl_easy_setopt (3)

747
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_setopt.3 Normal file
View File

@ -0,0 +1,747 @@
.\" generated by cd2nroff 0.1 from curl_easy_setopt.md
.TH curl_easy_setopt 3 "2025-08-14" libcurl
.SH NAME
curl_easy_setopt \- set options for a curl easy handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
.fi
.SH DESCRIPTION
\fIcurl_easy_setopt(3)\fP is used to tell libcurl how to behave. By setting the
appropriate options, the application can change libcurl\(aqs behavior. All
options are set with an \fIoption\fP followed by a \fIparameter\fP. That parameter can
be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a
\fBcurl_off_t\fP, depending on what the specific option expects. Read this
manual carefully as bad input values may cause libcurl to behave badly. You
can only set one option in each function call. A typical application uses many
\fIcurl_easy_setopt(3)\fP calls in the setup phase.
The \fIhandle\fP argument is the return code from a \fIcurl_easy_init(3)\fP or
\fIcurl_easy_duphandle(3)\fP call.
Options set with this function call are sticky. They remain set for all
forthcoming transfers performed using this \fIhandle\fP. The options are not in
any way reset between transfers, so if you want subsequent transfers with
different options, you must change them between the transfers. You can
optionally reset all options back to internal default with \fIcurl_easy_reset(3)\fP.
The order in which the options are set does not matter.
.SH STRINGS
Strings passed to libcurl as \(aqchar *\(aq arguments, are copied by the library;
the string storage associated to the pointer argument may be discarded or
reused after \fIcurl_easy_setopt(3)\fP returns. The only exception to this rule is
really \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies the string
\fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you need to read up
on.
This function does not accept input strings longer than
\fBCURL_MAX_INPUT_LENGTH\fP (8 MB).
libcurl does little to no verification of the contents of provided strings.
Passing in "creative octets" like newlines where they are not expected might
trigger unexpected results.
Before version 7.17.0, strings were not copied. Instead the user was forced
keep them available until libcurl no longer needed them.
.SH OPTIONS
.IP CURLOPT_ABSTRACT_UNIX_SOCKET
Path to an abstract Unix domain socket. See \fICURLOPT_ABSTRACT_UNIX_SOCKET(3)\fP
.IP CURLOPT_ACCEPTTIMEOUT_MS
Timeout for waiting for the server\(aqs connect back to be accepted. See
\fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP
.IP CURLOPT_ACCEPT_ENCODING
Accept\-Encoding and automatic decompressing data. See
\fICURLOPT_ACCEPT_ENCODING(3)\fP
.IP CURLOPT_ADDRESS_SCOPE
IPv6 scope for local addresses. See \fICURLOPT_ADDRESS_SCOPE(3)\fP
.IP CURLOPT_ALTSVC
Specify the Alt\-Svc: cache filename. See \fICURLOPT_ALTSVC(3)\fP
.IP CURLOPT_ALTSVC_CTRL
Enable and configure Alt\-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP
.IP CURLOPT_APPEND
Append to remote file. See \fICURLOPT_APPEND(3)\fP
.IP CURLOPT_AUTOREFERER
Automatically set Referer: header. See \fICURLOPT_AUTOREFERER(3)\fP
.IP CURLOPT_AWS_SIGV4
AWS HTTP V4 Signature. See \fICURLOPT_AWS_SIGV4(3)\fP
.IP CURLOPT_BUFFERSIZE
Ask for alternate buffer size. See \fICURLOPT_BUFFERSIZE(3)\fP
.IP CURLOPT_CAINFO
CA cert bundle. See \fICURLOPT_CAINFO(3)\fP
.IP CURLOPT_CAINFO_BLOB
CA cert bundle memory buffer. See \fICURLOPT_CAINFO_BLOB(3)\fP
.IP CURLOPT_CAPATH
Path to CA cert bundle. See \fICURLOPT_CAPATH(3)\fP
.IP CURLOPT_CA_CACHE_TIMEOUT
Timeout for CA cache. See \fICURLOPT_CA_CACHE_TIMEOUT(3)\fP
.IP CURLOPT_CERTINFO
Extract certificate info. See \fICURLOPT_CERTINFO(3)\fP
.IP CURLOPT_CHUNK_BGN_FUNCTION
Callback for wildcard download start of chunk. See
\fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP
.IP CURLOPT_CHUNK_DATA
Data pointer to pass to the chunk callbacks. See \fICURLOPT_CHUNK_DATA(3)\fP
.IP CURLOPT_CHUNK_END_FUNCTION
Callback for wildcard download end of chunk. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP
.IP CURLOPT_CLOSESOCKETDATA
Data pointer to pass to the close socket callback. See
\fICURLOPT_CLOSESOCKETDATA(3)\fP
.IP CURLOPT_CLOSESOCKETFUNCTION
Callback for closing socket. See \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP
.IP CURLOPT_CONNECTTIMEOUT
Timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT(3)\fP
.IP CURLOPT_CONNECTTIMEOUT_MS
Millisecond timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
.IP CURLOPT_CONNECT_ONLY
Only connect, nothing else. See \fICURLOPT_CONNECT_ONLY(3)\fP
.IP CURLOPT_CONNECT_TO
Connect to a specific host and port. See \fICURLOPT_CONNECT_TO(3)\fP
.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
\fBOBSOLETE\fP Callback for code base conversion.
See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP
.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
\fBOBSOLETE\fP Callback for code base conversion.
See \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP
.IP CURLOPT_CONV_TO_NETWORK_FUNCTION
\fBOBSOLETE\fP Callback for code base conversion.
See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP
.IP CURLOPT_COOKIE
Cookie(s) to send. See \fICURLOPT_COOKIE(3)\fP
.IP CURLOPT_COOKIEFILE
File to read cookies from. See \fICURLOPT_COOKIEFILE(3)\fP
.IP CURLOPT_COOKIEJAR
File to write cookies to. See \fICURLOPT_COOKIEJAR(3)\fP
.IP CURLOPT_COOKIELIST
Add or control cookies. See \fICURLOPT_COOKIELIST(3)\fP
.IP CURLOPT_COOKIESESSION
Start a new cookie session. See \fICURLOPT_COOKIESESSION(3)\fP
.IP CURLOPT_COPYPOSTFIELDS
Send a POST with this data \- and copy it. See \fICURLOPT_COPYPOSTFIELDS(3)\fP
.IP CURLOPT_CRLF
Convert newlines. See \fICURLOPT_CRLF(3)\fP
.IP CURLOPT_CRLFILE
Certificate Revocation List. See \fICURLOPT_CRLFILE(3)\fP
.IP CURLOPT_CURLU
Set URL to work on with a URL handle. See \fICURLOPT_CURLU(3)\fP
.IP CURLOPT_CUSTOMREQUEST
Custom request/method. See \fICURLOPT_CUSTOMREQUEST(3)\fP
.IP CURLOPT_DEBUGDATA
Data pointer to pass to the debug callback. See \fICURLOPT_DEBUGDATA(3)\fP
.IP CURLOPT_DEBUGFUNCTION
Callback for debug information. See \fICURLOPT_DEBUGFUNCTION(3)\fP
.IP CURLOPT_DEFAULT_PROTOCOL
Default protocol. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP
.IP CURLOPT_DIRLISTONLY
List only. See \fICURLOPT_DIRLISTONLY(3)\fP
.IP CURLOPT_DISALLOW_USERNAME_IN_URL
Do not allow username in URL. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP
.IP CURLOPT_DNS_CACHE_TIMEOUT
Timeout for DNS cache. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP
.IP CURLOPT_DNS_INTERFACE
Bind name resolves to this interface. See \fICURLOPT_DNS_INTERFACE(3)\fP
.IP CURLOPT_DNS_LOCAL_IP4
Bind name resolves to this IP4 address. See \fICURLOPT_DNS_LOCAL_IP4(3)\fP
.IP CURLOPT_DNS_LOCAL_IP6
Bind name resolves to this IP6 address. See \fICURLOPT_DNS_LOCAL_IP6(3)\fP
.IP CURLOPT_DNS_SERVERS
Preferred DNS servers. See \fICURLOPT_DNS_SERVERS(3)\fP
.IP CURLOPT_DNS_SHUFFLE_ADDRESSES
Shuffle addresses before use. See \fICURLOPT_DNS_SHUFFLE_ADDRESSES(3)\fP
.IP CURLOPT_DNS_USE_GLOBAL_CACHE
\fBOBSOLETE\fP Enable global DNS cache. See \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP
.IP CURLOPT_DOH_SSL_VERIFYHOST
Verify the hostname in the DoH (DNS\-over\-HTTPS) SSL certificate. See
\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP
.IP CURLOPT_DOH_SSL_VERIFYPEER
Verify the DoH (DNS\-over\-HTTPS) SSL certificate. See
\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP
.IP CURLOPT_DOH_SSL_VERIFYSTATUS
Verify the DoH (DNS\-over\-HTTPS) SSL certificate\(aqs status. See
\fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP
.IP CURLOPT_DOH_URL
Use this DoH server for name resolves. See \fICURLOPT_DOH_URL(3)\fP
.IP CURLOPT_ECH
Set the configuration for ECH. See \fICURLOPT_ECH(3)\fP
.IP CURLOPT_EGDSOCKET
\fBOBSOLETE\fP Identify EGD socket for entropy. See \fICURLOPT_EGDSOCKET(3)\fP
.IP CURLOPT_ERRORBUFFER
Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP
.IP CURLOPT_EXPECT_100_TIMEOUT_MS
100\-continue timeout. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP
.IP CURLOPT_FAILONERROR
Fail on HTTP 4xx errors. \fICURLOPT_FAILONERROR(3)\fP
.IP CURLOPT_FILETIME
Request file modification date and time. See \fICURLOPT_FILETIME(3)\fP
.IP CURLOPT_FNMATCH_DATA
Data pointer to pass to the wildcard matching callback. See
\fICURLOPT_FNMATCH_DATA(3)\fP
.IP CURLOPT_FNMATCH_FUNCTION
Callback for wildcard matching. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP
.IP CURLOPT_FOLLOWLOCATION
Follow HTTP redirects. See \fICURLOPT_FOLLOWLOCATION(3)\fP
.IP CURLOPT_FORBID_REUSE
Prevent subsequent connections from reusing this. See \fICURLOPT_FORBID_REUSE(3)\fP
.IP CURLOPT_FRESH_CONNECT
Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP
.IP CURLOPT_FTPPORT
Use active FTP. See \fICURLOPT_FTPPORT(3)\fP
.IP CURLOPT_FTPSSLAUTH
Control how to do TLS. See \fICURLOPT_FTPSSLAUTH(3)\fP
.IP CURLOPT_FTP_ACCOUNT
Send ACCT command. See \fICURLOPT_FTP_ACCOUNT(3)\fP
.IP CURLOPT_FTP_ALTERNATIVE_TO_USER
Alternative to USER. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP
.IP CURLOPT_FTP_CREATE_MISSING_DIRS
Create missing directories on the remote server. See
\fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP
.IP CURLOPT_FTP_FILEMETHOD
Specify how to reach files. See \fICURLOPT_FTP_FILEMETHOD(3)\fP
.IP CURLOPT_FTP_SKIP_PASV_IP
Ignore the IP address in the PASV response. See \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP
.IP CURLOPT_FTP_SSL_CCC
Back to non\-TLS again after authentication. See \fICURLOPT_FTP_SSL_CCC(3)\fP
.IP CURLOPT_FTP_USE_EPRT
Use EPRT. See \fICURLOPT_FTP_USE_EPRT(3)\fP
.IP CURLOPT_FTP_USE_EPSV
Use EPSV. See \fICURLOPT_FTP_USE_EPSV(3)\fP
.IP CURLOPT_FTP_USE_PRET
Use PRET. See \fICURLOPT_FTP_USE_PRET(3)\fP
.IP CURLOPT_GSSAPI_DELEGATION
Disable GSS\-API delegation. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP
.IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS
Timeout for happy eyeballs. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP
.IP CURLOPT_HAPROXYPROTOCOL
Send an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXYPROTOCOL(3)\fP
.IP CURLOPT_HAPROXY_CLIENT_IP
Spoof the client IP in an HAProxy PROXY protocol v1 header. See
\fICURLOPT_HAPROXY_CLIENT_IP(3)\fP
.IP CURLOPT_HEADER
Include the header in the body output. See \fICURLOPT_HEADER(3)\fP
.IP CURLOPT_HEADERDATA
Data pointer to pass to the header callback. See \fICURLOPT_HEADERDATA(3)\fP
.IP CURLOPT_HEADERFUNCTION
Callback for writing received headers. See \fICURLOPT_HEADERFUNCTION(3)\fP
.IP CURLOPT_HEADEROPT
Control custom headers. See \fICURLOPT_HEADEROPT(3)\fP
.IP CURLOPT_HSTS
Set HSTS cache file. See \fICURLOPT_HSTS(3)\fP
.IP CURLOPT_HSTSREADDATA
Pass pointer to the HSTS read callback. See \fICURLOPT_HSTSREADDATA(3)\fP
.IP CURLOPT_HSTSREADFUNCTION
Set HSTS read callback. See \fICURLOPT_HSTSREADFUNCTION(3)\fP
.IP CURLOPT_HSTSWRITEDATA
Pass pointer to the HSTS write callback. See \fICURLOPT_HSTSWRITEDATA(3)\fP
.IP CURLOPT_HSTSWRITEFUNCTION
Set HSTS write callback. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP
.IP CURLOPT_HSTS_CTRL
Enable HSTS. See \fICURLOPT_HSTS_CTRL(3)\fP
.IP CURLOPT_HTTP09_ALLOWED
Allow HTTP/0.9 responses. \fICURLOPT_HTTP09_ALLOWED(3)\fP
.IP CURLOPT_HTTP200ALIASES
Alternative versions of 200 OK. See \fICURLOPT_HTTP200ALIASES(3)\fP
.IP CURLOPT_HTTPAUTH
HTTP server authentication methods. See \fICURLOPT_HTTPAUTH(3)\fP
.IP CURLOPT_HTTPGET
Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP
.IP CURLOPT_HTTPHEADER
Custom HTTP headers. See \fICURLOPT_HTTPHEADER(3)\fP
.IP CURLOPT_HTTPPOST
\fBDeprecated option\fP Multipart formpost HTTP POST.
See \fICURLOPT_HTTPPOST(3)\fP
.IP CURLOPT_HTTPPROXYTUNNEL
Tunnel through the HTTP proxy. \fICURLOPT_HTTPPROXYTUNNEL(3)\fP
.IP CURLOPT_HTTP_CONTENT_DECODING
Disable Content decoding. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP
.IP CURLOPT_HTTP_TRANSFER_DECODING
Disable Transfer decoding. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP
.IP CURLOPT_HTTP_VERSION
HTTP version to use. \fICURLOPT_HTTP_VERSION(3)\fP
.IP CURLOPT_IGNORE_CONTENT_LENGTH
Ignore Content\-Length. See \fICURLOPT_IGNORE_CONTENT_LENGTH(3)\fP
.IP CURLOPT_INFILESIZE
Size of file to send. \fICURLOPT_INFILESIZE(3)\fP
.IP CURLOPT_INFILESIZE_LARGE
Size of file to send. \fICURLOPT_INFILESIZE_LARGE(3)\fP
.IP CURLOPT_INTERFACE
Bind connection locally to this. See \fICURLOPT_INTERFACE(3)\fP
.IP CURLOPT_INTERLEAVEDATA
Data pointer to pass to the RTSP interleave callback. See
\fICURLOPT_INTERLEAVEDATA(3)\fP
.IP CURLOPT_INTERLEAVEFUNCTION
Callback for RTSP interleaved data. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP
.IP CURLOPT_IOCTLDATA
\fBDeprecated option\fP Data pointer to pass to the I/O callback.
See \fICURLOPT_IOCTLDATA(3)\fP
.IP CURLOPT_IOCTLFUNCTION
\fBDeprecated option\fP Callback for I/O operations.
See \fICURLOPT_IOCTLFUNCTION(3)\fP
.IP CURLOPT_IPRESOLVE
IP version to use. See \fICURLOPT_IPRESOLVE(3)\fP
.IP CURLOPT_ISSUERCERT
Issuer certificate. See \fICURLOPT_ISSUERCERT(3)\fP
.IP CURLOPT_ISSUERCERT_BLOB
Issuer certificate memory buffer. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP
.IP CURLOPT_KEEP_SENDING_ON_ERROR
Keep sending on HTTP >= 300 errors. \fICURLOPT_KEEP_SENDING_ON_ERROR(3)\fP
.IP CURLOPT_KEYPASSWD
Client key password. See \fICURLOPT_KEYPASSWD(3)\fP
.IP CURLOPT_KRBLEVEL
Kerberos security level. See \fICURLOPT_KRBLEVEL(3)\fP
.IP CURLOPT_LOCALPORT
Bind connection locally to this port. See \fICURLOPT_LOCALPORT(3)\fP
.IP CURLOPT_LOCALPORTRANGE
Bind connection locally to port range. See \fICURLOPT_LOCALPORTRANGE(3)\fP
.IP CURLOPT_LOGIN_OPTIONS
Login options. See \fICURLOPT_LOGIN_OPTIONS(3)\fP
.IP CURLOPT_LOW_SPEED_LIMIT
Low speed limit to abort transfer. See \fICURLOPT_LOW_SPEED_LIMIT(3)\fP
.IP CURLOPT_LOW_SPEED_TIME
Time to be below the speed to trigger low speed abort. See
\fICURLOPT_LOW_SPEED_TIME(3)\fP
.IP CURLOPT_MAIL_AUTH
Authentication address. See \fICURLOPT_MAIL_AUTH(3)\fP
.IP CURLOPT_MAIL_FROM
Address of the sender. See \fICURLOPT_MAIL_FROM(3)\fP
.IP CURLOPT_MAIL_RCPT
Address of the recipients. See \fICURLOPT_MAIL_RCPT(3)\fP
.IP CURLOPT_MAIL_RCPT_ALLOWFAILS
Allow RCPT TO command to fail for some recipients. See
\fICURLOPT_MAIL_RCPT_ALLOWFAILS(3)\fP
.IP CURLOPT_MAXAGE_CONN
Limit the age (idle time) of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP
.IP CURLOPT_MAXCONNECTS
Maximum number of connections in the connection pool. See
\fICURLOPT_MAXCONNECTS(3)\fP
.IP CURLOPT_MAXFILESIZE
Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP
.IP CURLOPT_MAXFILESIZE_LARGE
Maximum file size to get. See \fICURLOPT_MAXFILESIZE_LARGE(3)\fP
.IP CURLOPT_MAXLIFETIME_CONN
Limit the age (since creation) of connections for reuse. See
\fICURLOPT_MAXLIFETIME_CONN(3)\fP
.IP CURLOPT_MAXREDIRS
Maximum number of redirects to follow. See \fICURLOPT_MAXREDIRS(3)\fP
.IP CURLOPT_MAX_RECV_SPEED_LARGE
Cap the download speed to this. See \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP
.IP CURLOPT_MAX_SEND_SPEED_LARGE
Cap the upload speed to this. See \fICURLOPT_MAX_SEND_SPEED_LARGE(3)\fP
.IP CURLOPT_MIMEPOST
Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP
.IP CURLOPT_MIME_OPTIONS
Set MIME option flags. See \fICURLOPT_MIME_OPTIONS(3)\fP
.IP CURLOPT_NETRC
Enable .netrc parsing. See \fICURLOPT_NETRC(3)\fP
.IP CURLOPT_NETRC_FILE
\&.netrc filename. See \fICURLOPT_NETRC_FILE(3)\fP
.IP CURLOPT_NEW_DIRECTORY_PERMS
Mode for creating new remote directories. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\fP
.IP CURLOPT_NEW_FILE_PERMS
Mode for creating new remote files. See \fICURLOPT_NEW_FILE_PERMS(3)\fP
.IP CURLOPT_NOBODY
Do not get the body contents. See \fICURLOPT_NOBODY(3)\fP
.IP CURLOPT_NOPROGRESS
Shut off the progress meter. See \fICURLOPT_NOPROGRESS(3)\fP
.IP CURLOPT_NOPROXY
Filter out hosts from proxy use. \fICURLOPT_NOPROXY(3)\fP
.IP CURLOPT_NOSIGNAL
Do not install signal handlers. See \fICURLOPT_NOSIGNAL(3)\fP
.IP CURLOPT_OPENSOCKETDATA
Data pointer to pass to the open socket callback. See \fICURLOPT_OPENSOCKETDATA(3)\fP
.IP CURLOPT_OPENSOCKETFUNCTION
Callback for socket creation. See \fICURLOPT_OPENSOCKETFUNCTION(3)\fP
.IP CURLOPT_PASSWORD
Password. See \fICURLOPT_PASSWORD(3)\fP
.IP CURLOPT_PATH_AS_IS
Disable squashing /../ and /./ sequences in the path. See \fICURLOPT_PATH_AS_IS(3)\fP
.IP CURLOPT_PINNEDPUBLICKEY
Set pinned SSL public key . See \fICURLOPT_PINNEDPUBLICKEY(3)\fP
.IP CURLOPT_PIPEWAIT
Wait on connection to pipeline on it. See \fICURLOPT_PIPEWAIT(3)\fP
.IP CURLOPT_PORT
Port number to connect to. See \fICURLOPT_PORT(3)\fP
.IP CURLOPT_POST
Make an HTTP POST. See \fICURLOPT_POST(3)\fP
.IP CURLOPT_POSTFIELDSIZE
The POST data is this big. See \fICURLOPT_POSTFIELDSIZE(3)\fP
.IP CURLOPT_POSTFIELDSIZE_LARGE
The POST data is this big. See \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP
.IP CURLOPT_POSTQUOTE
Commands to run after transfer. See \fICURLOPT_POSTQUOTE(3)\fP
.IP CURLOPT_POSTREDIR
How to act on redirects after POST. See \fICURLOPT_POSTREDIR(3)\fP
.IP CURLOPT_PREQUOTE
Commands to run just before transfer. See \fICURLOPT_PREQUOTE(3)\fP
.IP CURLOPT_PREREQDATA
Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See
\fICURLOPT_PREREQDATA(3)\fP
.IP CURLOPT_PREREQFUNCTION
Callback to be called after a connection is established but before a request
is made on that connection. See \fICURLOPT_PREREQFUNCTION(3)\fP
.IP CURLOPT_PRE_PROXY
Socks proxy to use. See \fICURLOPT_PRE_PROXY(3)\fP
.IP CURLOPT_PRIVATE
Private pointer to store. See \fICURLOPT_PRIVATE(3)\fP
.IP CURLOPT_PROGRESSDATA
Data pointer to pass to the progress meter callback. See
\fICURLOPT_PROGRESSDATA(3)\fP
.IP CURLOPT_PROGRESSFUNCTION
\fBOBSOLETE\fP callback for progress meter. See \fICURLOPT_PROGRESSFUNCTION(3)\fP
.IP CURLOPT_PROTOCOLS
\fBDeprecated option\fP Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP
.IP CURLOPT_PROTOCOLS_STR
Allowed protocols. See \fICURLOPT_PROTOCOLS_STR(3)\fP
.IP CURLOPT_PROXY
Proxy to use. See \fICURLOPT_PROXY(3)\fP
.IP CURLOPT_PROXYAUTH
HTTP proxy authentication methods. See \fICURLOPT_PROXYAUTH(3)\fP
.IP CURLOPT_PROXYHEADER
Custom HTTP headers sent to proxy. See \fICURLOPT_PROXYHEADER(3)\fP
.IP CURLOPT_PROXYPASSWORD
Proxy password. See \fICURLOPT_PROXYPASSWORD(3)\fP
.IP CURLOPT_PROXYPORT
Proxy port to use. See \fICURLOPT_PROXYPORT(3)\fP
.IP CURLOPT_PROXYTYPE
Proxy type. See \fICURLOPT_PROXYTYPE(3)\fP
.IP CURLOPT_PROXYUSERNAME
Proxy username. See \fICURLOPT_PROXYUSERNAME(3)\fP
.IP CURLOPT_PROXYUSERPWD
Proxy username and password. See \fICURLOPT_PROXYUSERPWD(3)\fP
.IP CURLOPT_PROXY_CAINFO
Proxy CA cert bundle. See \fICURLOPT_PROXY_CAINFO(3)\fP
.IP CURLOPT_PROXY_CAINFO_BLOB
Proxy CA cert bundle memory buffer. See \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP
.IP CURLOPT_PROXY_CAPATH
Path to proxy CA cert bundle. See \fICURLOPT_PROXY_CAPATH(3)\fP
.IP CURLOPT_PROXY_CRLFILE
Proxy Certificate Revocation List. See \fICURLOPT_PROXY_CRLFILE(3)\fP
.IP CURLOPT_PROXY_ISSUERCERT
Proxy issuer certificate. See \fICURLOPT_PROXY_ISSUERCERT(3)\fP
.IP CURLOPT_PROXY_ISSUERCERT_BLOB
Proxy issuer certificate memory buffer. See \fICURLOPT_PROXY_ISSUERCERT_BLOB(3)\fP
.IP CURLOPT_PROXY_KEYPASSWD
Proxy client key password. See \fICURLOPT_PROXY_KEYPASSWD(3)\fP
.IP CURLOPT_PROXY_PINNEDPUBLICKEY
Set the proxy\(aqs pinned SSL public key. See
\fICURLOPT_PROXY_PINNEDPUBLICKEY(3)\fP
.IP CURLOPT_PROXY_SERVICE_NAME
Proxy authentication service name. \fICURLOPT_PROXY_SERVICE_NAME(3)\fP
.IP CURLOPT_PROXY_SSLCERT
Proxy client cert. See \fICURLOPT_PROXY_SSLCERT(3)\fP
.IP CURLOPT_PROXY_SSLCERTTYPE
Proxy client cert type. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP
.IP CURLOPT_PROXY_SSLCERT_BLOB
Proxy client cert memory buffer. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP
.IP CURLOPT_PROXY_SSLKEY
Proxy client key. See \fICURLOPT_PROXY_SSLKEY(3)\fP
.IP CURLOPT_PROXY_SSLKEYTYPE
Proxy client key type. See \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP
.IP CURLOPT_PROXY_SSLKEY_BLOB
Proxy client key. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP
.IP CURLOPT_PROXY_SSLVERSION
Proxy SSL version to use. See \fICURLOPT_PROXY_SSLVERSION(3)\fP
.IP CURLOPT_PROXY_SSL_CIPHER_LIST
Proxy ciphers to use. See \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP
.IP CURLOPT_PROXY_SSL_OPTIONS
Control proxy SSL behavior. See \fICURLOPT_PROXY_SSL_OPTIONS(3)\fP
.IP CURLOPT_PROXY_SSL_VERIFYHOST
Verify the hostname in the proxy SSL certificate. See
\fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP
.IP CURLOPT_PROXY_SSL_VERIFYPEER
Verify the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP
.IP CURLOPT_PROXY_TLS13_CIPHERS
Proxy TLS 1.3 cipher suites to use. See \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP
.IP CURLOPT_PROXY_TLSAUTH_PASSWORD
Proxy TLS authentication password. See \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP
.IP CURLOPT_PROXY_TLSAUTH_TYPE
Proxy TLS authentication methods. See \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP
.IP CURLOPT_PROXY_TLSAUTH_USERNAME
Proxy TLS authentication username. See \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP
.IP CURLOPT_PROXY_TRANSFER_MODE
Add transfer mode to URL over proxy. See \fICURLOPT_PROXY_TRANSFER_MODE(3)\fP
.IP CURLOPT_PUT
\fBDeprecated option\fP Issue an HTTP PUT request. See \fICURLOPT_PUT(3)\fP
.IP CURLOPT_QUICK_EXIT
To be set by toplevel tools like "curl" to skip lengthy cleanups when they are
about to call exit() anyway. See \fICURLOPT_QUICK_EXIT(3)\fP
.IP CURLOPT_QUOTE
Commands to run before transfer. See \fICURLOPT_QUOTE(3)\fP
.IP CURLOPT_RANDOM_FILE
\fBOBSOLETE\fP Provide source for entropy random data.
See \fICURLOPT_RANDOM_FILE(3)\fP
.IP CURLOPT_RANGE
Range requests. See \fICURLOPT_RANGE(3)\fP
.IP CURLOPT_READDATA
Data pointer to pass to the read callback. See \fICURLOPT_READDATA(3)\fP
.IP CURLOPT_READFUNCTION
Callback for reading data. See \fICURLOPT_READFUNCTION(3)\fP
.IP CURLOPT_REDIR_PROTOCOLS
\fBDeprecated option\fP Protocols to allow redirects to. See
\fICURLOPT_REDIR_PROTOCOLS(3)\fP
.IP CURLOPT_REDIR_PROTOCOLS_STR
Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP
.IP CURLOPT_REFERER
Referer: header. See \fICURLOPT_REFERER(3)\fP
.IP CURLOPT_REQUEST_TARGET
Set the request target. \fICURLOPT_REQUEST_TARGET(3)\fP
.IP CURLOPT_RESOLVE
Provide fixed/fake name resolves. See \fICURLOPT_RESOLVE(3)\fP
.IP CURLOPT_RESOLVER_START_DATA
Data pointer to pass to resolver start callback. See
\fICURLOPT_RESOLVER_START_DATA(3)\fP
.IP CURLOPT_RESOLVER_START_FUNCTION
Callback to be called before a new resolve request is started. See
\fICURLOPT_RESOLVER_START_FUNCTION(3)\fP
.IP CURLOPT_RESUME_FROM
Resume a transfer. See \fICURLOPT_RESUME_FROM(3)\fP
.IP CURLOPT_RESUME_FROM_LARGE
Resume a transfer. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP
.IP CURLOPT_RTSP_CLIENT_CSEQ
Client CSEQ number. See \fICURLOPT_RTSP_CLIENT_CSEQ(3)\fP
.IP CURLOPT_RTSP_REQUEST
RTSP request. See \fICURLOPT_RTSP_REQUEST(3)\fP
.IP CURLOPT_RTSP_SERVER_CSEQ
CSEQ number for RTSP Server\->Client request. See \fICURLOPT_RTSP_SERVER_CSEQ(3)\fP
.IP CURLOPT_RTSP_SESSION_ID
RTSP session\-id. See \fICURLOPT_RTSP_SESSION_ID(3)\fP
.IP CURLOPT_RTSP_STREAM_URI
RTSP stream URI. See \fICURLOPT_RTSP_STREAM_URI(3)\fP
.IP CURLOPT_RTSP_TRANSPORT
RTSP Transport: header. See \fICURLOPT_RTSP_TRANSPORT(3)\fP
.IP CURLOPT_SASL_AUTHZID
SASL authorization identity (identity to act as). See \fICURLOPT_SASL_AUTHZID(3)\fP
.IP CURLOPT_SASL_IR
Enable SASL initial response. See \fICURLOPT_SASL_IR(3)\fP
.IP CURLOPT_SEEKDATA
Data pointer to pass to the seek callback. See \fICURLOPT_SEEKDATA(3)\fP
.IP CURLOPT_SEEKFUNCTION
Callback for seek operations. See \fICURLOPT_SEEKFUNCTION(3)\fP
.IP CURLOPT_SERVER_RESPONSE_TIMEOUT
Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP
.IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS
Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP
.IP CURLOPT_SERVICE_NAME
Authentication service name. \fICURLOPT_SERVICE_NAME(3)\fP
.IP CURLOPT_SHARE
Share object to use. See \fICURLOPT_SHARE(3)\fP
.IP CURLOPT_SOCKOPTDATA
Data pointer to pass to the sockopt callback. See \fICURLOPT_SOCKOPTDATA(3)\fP
.IP CURLOPT_SOCKOPTFUNCTION
Callback for sockopt operations. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP
.IP CURLOPT_SOCKS5_AUTH
Socks5 authentication methods. See \fICURLOPT_SOCKS5_AUTH(3)\fP
.IP CURLOPT_SOCKS5_GSSAPI_NEC
Socks5 GSSAPI NEC mode. See \fICURLOPT_SOCKS5_GSSAPI_NEC(3)\fP
.IP CURLOPT_SOCKS5_GSSAPI_SERVICE
\fBDeprecated option\fP Socks5 GSSAPI service name.
See \fICURLOPT_SOCKS5_GSSAPI_SERVICE(3)\fP
.IP CURLOPT_SSH_AUTH_TYPES
SSH authentication types. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP
.IP CURLOPT_SSH_COMPRESSION
Enable SSH compression. See \fICURLOPT_SSH_COMPRESSION(3)\fP
.IP CURLOPT_SSH_HOSTKEYDATA
Custom pointer to pass to ssh host key callback. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP
.IP CURLOPT_SSH_HOSTKEYFUNCTION
Callback for checking host key handling. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP
.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
MD5 of host\(aqs public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)\fP
.IP CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256
SHA256 of host\(aqs public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP
.IP CURLOPT_SSH_KEYDATA
Custom pointer to pass to ssh key callback. See \fICURLOPT_SSH_KEYDATA(3)\fP
.IP CURLOPT_SSH_KEYFUNCTION
Callback for known hosts handling. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP
.IP CURLOPT_SSH_KNOWNHOSTS
Filename with known hosts. See \fICURLOPT_SSH_KNOWNHOSTS(3)\fP
.IP CURLOPT_SSH_PRIVATE_KEYFILE
Filename of the private key. See \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP
.IP CURLOPT_SSH_PUBLIC_KEYFILE
Filename of the public key. See \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP
.IP CURLOPT_SSLCERT
Client cert. See \fICURLOPT_SSLCERT(3)\fP
.IP CURLOPT_SSLCERTTYPE
Client cert type. See \fICURLOPT_SSLCERTTYPE(3)\fP
.IP CURLOPT_SSLCERT_BLOB
Client cert memory buffer. See \fICURLOPT_SSLCERT_BLOB(3)\fP
.IP CURLOPT_SSLENGINE
Use identifier with SSL engine. See \fICURLOPT_SSLENGINE(3)\fP
.IP CURLOPT_SSLENGINE_DEFAULT
Default SSL engine. See \fICURLOPT_SSLENGINE_DEFAULT(3)\fP
.IP CURLOPT_SSLKEY
Client key. See \fICURLOPT_SSLKEY(3)\fP
.IP CURLOPT_SSLKEYTYPE
Client key type. See \fICURLOPT_SSLKEYTYPE(3)\fP
.IP CURLOPT_SSLKEY_BLOB
Client key memory buffer. See \fICURLOPT_SSLKEY_BLOB(3)\fP
.IP CURLOPT_SSLVERSION
SSL version to use. See \fICURLOPT_SSLVERSION(3)\fP
.IP CURLOPT_SSL_CIPHER_LIST
Ciphers to use. See \fICURLOPT_SSL_CIPHER_LIST(3)\fP
.IP CURLOPT_SSL_CTX_DATA
Data pointer to pass to the SSL context callback. See \fICURLOPT_SSL_CTX_DATA(3)\fP
.IP CURLOPT_SSL_CTX_FUNCTION
Callback for SSL context logic. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP
.IP CURLOPT_SSL_EC_CURVES
Set key exchange curves. See \fICURLOPT_SSL_EC_CURVES(3)\fP
.IP CURLOPT_SSL_ENABLE_ALPN
Enable use of ALPN. See \fICURLOPT_SSL_ENABLE_ALPN(3)\fP
.IP CURLOPT_SSL_ENABLE_NPN
\fBOBSOLETE\fP Enable use of NPN. See \fICURLOPT_SSL_ENABLE_NPN(3)\fP
.IP CURLOPT_SSL_FALSESTART
\fBDeprecated option\fP Enable TLS False Start. See \fICURLOPT_SSL_FALSESTART(3)\fP
.IP CURLOPT_SSL_OPTIONS
Control SSL behavior. See \fICURLOPT_SSL_OPTIONS(3)\fP
.IP CURLOPT_SSL_SESSIONID_CACHE
Disable SSL session\-id cache. See \fICURLOPT_SSL_SESSIONID_CACHE(3)\fP
.IP CURLOPT_SSL_SIGNATURE_ALGORITHMS
TLS signature algorithms to use. See \fICURLOPT_SSL_SIGNATURE_ALGORITHMS(3)\fP
.IP CURLOPT_SSL_VERIFYHOST
Verify the hostname in the SSL certificate. See \fICURLOPT_SSL_VERIFYHOST(3)\fP
.IP CURLOPT_SSL_VERIFYPEER
Verify the SSL certificate. See \fICURLOPT_SSL_VERIFYPEER(3)\fP
.IP CURLOPT_SSL_VERIFYSTATUS
Verify the SSL certificate\(aqs status. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP
.IP CURLOPT_STDERR
Redirect stderr to another stream. See \fICURLOPT_STDERR(3)\fP
.IP CURLOPT_STREAM_DEPENDS
This HTTP/2 stream depends on another. See \fICURLOPT_STREAM_DEPENDS(3)\fP
.IP CURLOPT_STREAM_DEPENDS_E
This HTTP/2 stream depends on another exclusively. See
\fICURLOPT_STREAM_DEPENDS_E(3)\fP
.IP CURLOPT_STREAM_WEIGHT
Set this HTTP/2 stream\(aqs weight. See \fICURLOPT_STREAM_WEIGHT(3)\fP
.IP CURLOPT_SUPPRESS_CONNECT_HEADERS
Suppress proxy CONNECT response headers from user callbacks. See
\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP
.IP CURLOPT_TCP_FASTOPEN
Enable TCP Fast Open. See \fICURLOPT_TCP_FASTOPEN(3)\fP
.IP CURLOPT_TCP_KEEPALIVE
Enable TCP keep\-alive. See \fICURLOPT_TCP_KEEPALIVE(3)\fP
.IP CURLOPT_TCP_KEEPCNT
Maximum number of keep\-alive probes. See \fICURLOPT_TCP_KEEPCNT(3)\fP
.IP CURLOPT_TCP_KEEPIDLE
Idle time before sending keep\-alive. See \fICURLOPT_TCP_KEEPIDLE(3)\fP
.IP CURLOPT_TCP_KEEPINTVL
Interval between keep\-alive probes. See \fICURLOPT_TCP_KEEPINTVL(3)\fP
.IP CURLOPT_TCP_NODELAY
Disable the Nagle algorithm. See \fICURLOPT_TCP_NODELAY(3)\fP
.IP CURLOPT_TELNETOPTIONS
TELNET options. See \fICURLOPT_TELNETOPTIONS(3)\fP
.IP CURLOPT_TFTP_BLKSIZE
TFTP block size. See \fICURLOPT_TFTP_BLKSIZE(3)\fP
.IP CURLOPT_TFTP_NO_OPTIONS
Do not send TFTP options requests. See \fICURLOPT_TFTP_NO_OPTIONS(3)\fP
.IP CURLOPT_TIMECONDITION
Make a time conditional request. See \fICURLOPT_TIMECONDITION(3)\fP
.IP CURLOPT_TIMEOUT
Timeout for the entire request. See \fICURLOPT_TIMEOUT(3)\fP
.IP CURLOPT_TIMEOUT_MS
Millisecond timeout for the entire request. See \fICURLOPT_TIMEOUT_MS(3)\fP
.IP CURLOPT_TIMEVALUE
Time value for the time conditional request. See \fICURLOPT_TIMEVALUE(3)\fP
.IP CURLOPT_TIMEVALUE_LARGE
Time value for the time conditional request. See \fICURLOPT_TIMEVALUE_LARGE(3)\fP
.IP CURLOPT_TLS13_CIPHERS
TLS 1.3 cipher suites to use. See \fICURLOPT_TLS13_CIPHERS(3)\fP
.IP CURLOPT_TLSAUTH_PASSWORD
TLS authentication password. See \fICURLOPT_TLSAUTH_PASSWORD(3)\fP
.IP CURLOPT_TLSAUTH_TYPE
TLS authentication methods. See \fICURLOPT_TLSAUTH_TYPE(3)\fP
.IP CURLOPT_TLSAUTH_USERNAME
TLS authentication username. See \fICURLOPT_TLSAUTH_USERNAME(3)\fP
.IP CURLOPT_TRAILERDATA
Custom pointer passed to the trailing headers callback. See
\fICURLOPT_TRAILERDATA(3)\fP
.IP CURLOPT_TRAILERFUNCTION
Set callback for sending trailing headers. See
\fICURLOPT_TRAILERFUNCTION(3)\fP
.IP CURLOPT_TRANSFERTEXT
Use text transfer. See \fICURLOPT_TRANSFERTEXT(3)\fP
.IP CURLOPT_TRANSFER_ENCODING
Request Transfer\-Encoding. See \fICURLOPT_TRANSFER_ENCODING(3)\fP
.IP CURLOPT_UNIX_SOCKET_PATH
Path to a Unix domain socket. See \fICURLOPT_UNIX_SOCKET_PATH(3)\fP
.IP CURLOPT_UNRESTRICTED_AUTH
Do not restrict authentication to original host. \fICURLOPT_UNRESTRICTED_AUTH(3)\fP
.IP CURLOPT_UPKEEP_INTERVAL_MS
Sets the interval at which connection upkeep are performed. See
\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP
.IP CURLOPT_UPLOAD
Upload data. See \fICURLOPT_UPLOAD(3)\fP
.IP CURLOPT_UPLOAD_BUFFERSIZE
Set upload buffer size. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP
.IP CURLOPT_UPLOAD_FLAGS
Set upload flags. See \fICURLOPT_UPLOAD_FLAGS(3)\fP
.IP CURLOPT_URL
URL to work on. See \fICURLOPT_URL(3)\fP
.IP CURLOPT_USERAGENT
User\-Agent: header. See \fICURLOPT_USERAGENT(3)\fP
.IP CURLOPT_USERNAME
Username. See \fICURLOPT_USERNAME(3)\fP
.IP CURLOPT_USERPWD
Username and password. See \fICURLOPT_USERPWD(3)\fP
.IP CURLOPT_USE_SSL
Use TLS/SSL. See \fICURLOPT_USE_SSL(3)\fP
.IP CURLOPT_VERBOSE
Display verbose information. See \fICURLOPT_VERBOSE(3)\fP
.IP CURLOPT_WILDCARDMATCH
Transfer multiple files according to a filename pattern. See
\fICURLOPT_WILDCARDMATCH(3)\fP
.IP CURLOPT_WRITEDATA
Data pointer to pass to the write callback. See \fICURLOPT_WRITEDATA(3)\fP
.IP CURLOPT_WRITEFUNCTION
Callback for writing data. See \fICURLOPT_WRITEFUNCTION(3)\fP
.IP CURLOPT_WS_OPTIONS
Set WebSocket options. See \fICURLOPT_WS_OPTIONS(3)\fP
.IP CURLOPT_XFERINFODATA
Data pointer to pass to the progress meter callback. See
\fICURLOPT_XFERINFODATA(3)\fP
.IP CURLOPT_XFERINFOFUNCTION
Callback for progress meter. See \fICURLOPT_XFERINFOFUNCTION(3)\fP
.IP CURLOPT_XOAUTH2_BEARER
OAuth2 bearer token. See \fICURLOPT_XOAUTH2_BEARER(3)\fP
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise
\fIcurl_easy_setopt(3)\fP returns \fBCURLE_BAD_FUNCTION_ARGUMENT\fP (added in 7.65.0).
\fBCURLE_BAD_FUNCTION_ARGUMENT\fP is returned when the argument to an option is
invalid, like perhaps out of range.
If you try to set an option that libcurl does not know about, perhaps because
the library is too old to support it or the option was removed in a recent
version, this function returns \fICURLE_UNKNOWN_OPTION\fP. If support for the
option was disabled at compile\-time, it returns \fICURLE_NOT_BUILT_IN\fP.
.SH SEE ALSO
.BR curl_easy_cleanup (3),
.BR curl_easy_getinfo (3),
.BR curl_easy_init (3),
.BR curl_easy_option_by_id (3),
.BR curl_easy_option_by_name (3),
.BR curl_easy_option_next (3),
.BR curl_easy_reset (3),
.BR curl_multi_setopt (3)

136
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_ssls_export.3 Normal file
View File

@ -0,0 +1,136 @@
.\" generated by cd2nroff 0.1 from curl_easy_ssls_export.md
.TH curl_easy_ssls_export 3 "2025-08-14" libcurl
.SH NAME
curl_easy_ssls_export \- export SSL sessions
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef CURLcode curl_ssls_export_function(CURL *handle,
void *userptr,
const char *session_key,
const unsigned char *shmac,
size_t shmac_len,
const unsigned char *sdata,
size_t sdata_len,
curl_off_t valid_until,
int ietf_tls_id,
const char *alpn,
size_t earlydata_max);
CURLcode curl_easy_ssls_export(CURL *handle,
curl_ssls_export_function *export_fn,
void *userptr);
.fi
.SH DESCRIPTION
This function iterates over all SSL session tickets that belong to the
easy handle and invokes the \fBexport_fn\fP callback on each of them, as
long as the callback returns \fBCURLE_OK\fP.
The callback may then store this information and use \fIcurl_easy_ssls_import(3)\fP
in another libcurl instance to add SSL session tickets again. Reuse of
SSL session tickets may result in faster handshakes and some connections
might be able to send request data in the initial packets (0\-RTT).
From all the parameters passed to the \fBexport_fn\fP only two need to be
persisted: either \fBsession_key\fP or \fBshamc\fP and always \fBsdata\fP. All
other parameters are informative, e.g. allow the callback to act only
on specific session tickets.
Note that SSL sessions that involve a client certificate or SRP
username/password are not exported.
.SH Export Function Parameter
.IP "Session Key"
This is a printable, null\-terminated string that starts with \fBhostname:port\fP
the session ticket is originating from and also contains all relevant SSL
parameters used in the connection. The key also carries the name and version
number of the TLS backend used.
It is recommended to only persist \fBsession_key\fP when it can be protected
from outside access. Since the hostname appears in plain text, it would
allow any third party to see how curl has been used for.
.IP "Salted Hash"
A binary blob of \fBshmac_len\fP bytes that contains a random salt and
a cryptographic hash of the salt and \fBsession_key\fP. The salt is generated
for every session individually. Storing \fBshmac\fP is recommended when
placing session tickets in a file, for example.
A third party may brute\-force known hostnames, but cannot just "grep" for
them.
.IP "Session Data"
A binary blob of \fBsdata_len\fP bytes, \fBsdata\fP contains all relevant
SSL session ticket information for a later import \- apart from \fBsession_key\fP
and \fBshmac\fP.
.IP valid_until
Seconds since EPOCH (1970\-01\-01) until the session ticket is considered
valid.
.IP "TLS Version"
The IETF assigned number for the TLS version the session ticket originates
from. This is \fB0x0304\fP for TLSv1.3, \fB0x0303\fP for 1.2, etc. Session
tickets from version 1.3 have better security properties, so an export
might store only those.
.IP ALPN
The ALPN protocol that had been negotiated with the host. This may be
\fBNULL\fP if negotiation gave no result or had not been attempted.
.IP "Early Data"
The maximum amount of bytes the server supports to receive in early data
(0\-RTT). This is 0 unless the server explicitly indicates support.
.SH PROTOCOLS
This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
This option works only with the following TLS backends:
GnuTLS, OpenSSL, mbedTLS and wolfSSL
.SH EXAMPLE
.nf
CURLcode my_export_cb(CURL *handle,
void *userptr,
const char *session_key,
const unsigned char *shmac,
size_t shmac_len,
const unsigned char *sdata,
size_t sdata_len,
curl_off_t valid_until,
int ietf_tls_id,
const char *alpn,
size_t earlydata_max)
{
/* persist sdata */
return CURLE_OK;
}
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
CURLcode rc;
CURL *curl;
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_SHARE, share);
rc = curl_easy_ssls_export(curl, my_export_cb, NULL);
/* always cleanup */
curl_easy_cleanup(curl);
}
curl_share_cleanup(share);
}
.fi
.SH AVAILABILITY
Added in curl 8.12.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR CURLOPT_SHARE (3),
.BR curl_easy_ssls_import (3),
.BR curl_share_setopt (3)

69
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_ssls_import.3 Normal file
View File

@ -0,0 +1,69 @@
.\" generated by cd2nroff 0.1 from curl_easy_ssls_import.md
.TH curl_easy_ssls_import 3 "2025-08-14" libcurl
.SH NAME
curl_easy_ssls_export \- export SSL sessions
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_ssls_import(CURL *handle,
const char *session_key,
const unsigned char *shmac, size_t shmac_len,
const unsigned char *sdata, size_t sdata_len);
.fi
.SH DESCRIPTION
This function imports a previously exported SSL session ticket. \fBsdata\fP and
\fBsdata_len\fP must always be provided. If \fBsession_key\fP is \fBNULL\fP, then
\fBshmac\fP and \fBshmac_len\fP must be given as received during the export.
See \fIcurl_easy_ssls_export(3)\fP for a description of those.
Import of session tickets from other curl versions may fail due to changes
in the handling of \fBshmac\fP or \fBsdata\fP. A session ticket which has
already expired is silently discarded.
.SH PROTOCOLS
This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
This option works only with the following TLS backends:
GnuTLS, OpenSSL, mbedTLS and wolfSSL
.SH EXAMPLE
.nf
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
CURLcode rc;
CURL *curl;
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
curl = curl_easy_init();
if(curl) {
extern unsigned char *shmac, *sdata;
size_t hlen = 4, slen = 5;
curl_easy_setopt(curl, CURLOPT_SHARE, share);
/* read shmac and sdata from storage */
rc = curl_easy_ssls_import(curl, NULL, shmac, hlen, sdata, slen);
/* always cleanup */
curl_easy_cleanup(curl);
}
curl_share_cleanup(share);
}
.fi
.SH AVAILABILITY
Added in curl 8.12.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR CURLOPT_SHARE (3),
.BR curl_easy_ssls_export (3),
.BR curl_share_setopt (3)

44
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_strerror.3 Normal file
View File

@ -0,0 +1,44 @@
.\" generated by cd2nroff 0.1 from curl_easy_strerror.md
.TH curl_easy_strerror 3 "2025-08-14" libcurl
.SH NAME
curl_easy_strerror \- return string describing error code
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const char *curl_easy_strerror(CURLcode errornum);
.fi
.SH DESCRIPTION
The \fIcurl_easy_strerror(3)\fP function returns a string describing the
CURLcode error code passed in the argument \fIerrornum\fP.
Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more
specific error descriptions generated at runtime.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
/* set options */
/* Perform the entire transfer */
res = curl_easy_perform(curl);
/* Check for errors */
if(res != CURLE_OK)
fprintf(stderr, "curl_easy_perform() failed: %s\\n",
curl_easy_strerror(res));
}
}
.fi
.SH AVAILABILITY
Added in curl 7.12.0
.SH RETURN VALUE
A pointer to a null\-terminated string.
.SH SEE ALSO
.BR curl_multi_strerror (3),
.BR curl_share_strerror (3),
.BR curl_url_strerror (3),
.BR libcurl-errors (3)

58
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_unescape.3 Normal file
View File

@ -0,0 +1,58 @@
.\" generated by cd2nroff 0.1 from curl_easy_unescape.md
.TH curl_easy_unescape 3 "2025-08-14" libcurl
.SH NAME
curl_easy_unescape \- URL decode a string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_easy_unescape(CURL *curl, const char *input,
int inlength, int *outlength);
.fi
.SH DESCRIPTION
This function converts the URL encoded string \fBinput\fP to a "plain string"
and returns that in an allocated memory area. All input characters that are URL
encoded (%XX where XX is a two\-digit hexadecimal number) are converted to their
binary versions.
If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP
uses strlen() on \fBinput\fP to find out the size.
If \fBoutlength\fP is non\-NULL, the function writes the length of the returned
string in the integer it points to. This allows proper handling even for
strings containing %00. Since this is a pointer to an \fIint\fP type, it can
only return a value up to \fIINT_MAX\fP so no longer string can be returned in
this parameter.
Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was
per\-handle character conversion support for some old operating systems such as
TPF, but it was otherwise ignored.
You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
int decodelen;
char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen);
if(decoded) {
/* do not assume printf() works on the decoded data */
printf("Decoded: ");
/* ... */
curl_free(decoded);
}
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.15.4
.SH RETURN VALUE
A pointer to a null\-terminated string or NULL if it failed.
.SH SEE ALSO
.BR curl_easy_escape (3),
.BR curl_url_get (3)

72
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_easy_upkeep.3 Normal file
View File

@ -0,0 +1,72 @@
.\" generated by cd2nroff 0.1 from curl_easy_upkeep.md
.TH curl_easy_upkeep 3 "2025-08-14" libcurl
.SH NAME
curl_easy_upkeep \- keep existing connections alive
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_upkeep(CURL *handle);
.fi
.SH DESCRIPTION
Some protocols have "connection upkeep" mechanisms. These mechanisms usually
send some traffic on existing connections in order to keep them alive; this
can prevent connections from being closed due to overzealous firewalls, for
example.
For HTTP/2 we have an upkeep mechanism: when
the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP
is called, an HTTP/2 PING frame is sent on the connection.
For MQTT the upkeep interval defines when to send ping requests to prevent the
server from disconnecting.
This function must be explicitly called in order to perform the upkeep work.
The connection upkeep interval is set with
\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP.
If you call this function on an easy handle that uses a shared connection cache
then upkeep is performed on the connections in that cache, even if those
connections were never used by the easy handle. (Added in 8.10.0)
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
/* Make a connection to an HTTP/2 server. */
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Set the interval to 30000ms / 30s */
curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L);
curl_easy_perform(curl);
/* Perform more work here. */
/* While the connection is being held open, curl_easy_upkeep() can be
called. If curl_easy_upkeep() is called and the time since the last
upkeep exceeds the interval, then an HTTP/2 PING is sent. */
curl_easy_upkeep(curl);
/* Perform more work here. */
/* always cleanup */
curl_easy_cleanup(curl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR CURLOPT_TCP_KEEPALIVE (3),
.BR CURLOPT_TCP_KEEPIDLE (3)

45
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_escape.3 Normal file
View File

@ -0,0 +1,45 @@
.\" generated by cd2nroff 0.1 from curl_escape.md
.TH curl_escape 3 "2025-08-14" libcurl
.SH NAME
curl_escape \- URL encode a string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_escape(const char *string, int length);
.fi
.SH DESCRIPTION
Obsolete function. Use \fIcurl_easy_escape(3)\fP instead.
This function converts the given input \fBstring\fP to a URL encoded string
and return that as a new allocated string. All input characters that are not
a\-z, A\-Z or 0\-9 are converted to their "URL escaped" version (\fB%NN\fP where
\fBNN\fP is a two\-digit hexadecimal number).
If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP uses strlen()
on \fBstring\fP to find out the size.
You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
char *output = curl_escape("data to convert", 15);
if(output) {
printf("Encoded: %s\\n", output);
curl_free(output);
}
}
.fi
.SH HISTORY
Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function might be
removed in a future release.
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
A pointer to a null\-terminated string or NULL if it failed.
.SH SEE ALSO
.BR curl_free (3),
.BR curl_unescape (3)

266
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_formadd.3 Normal file
View File

@ -0,0 +1,266 @@
.\" generated by cd2nroff 0.1 from curl_formadd.md
.TH curl_formadd 3 "2025-08-14" libcurl
.SH NAME
curl_formadd \- add a section to a multipart form POST
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
struct curl_httppost **lastitem, ...);
.fi
.SH DESCRIPTION
\fBThis function is deprecated.\fP Use \fIcurl_mime_init(3)\fP instead.
curl_formadd() is used to append sections when building a multipart form
post. Append one section at a time until you have added all the sections you
want included and then you pass the \fIfirstitem\fP pointer as parameter to
\fICURLOPT_HTTPPOST(3)\fP. \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and
on repeated invokes it should be left as set to allow repeated invokes to find
the end of the list faster.
After the \fIlastitem\fP pointer follow the real arguments.
The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
NULL in the first call to this function. All list\-data is allocated by the
function itself. You must call \fIcurl_formfree(3)\fP on the \fIfirstitem\fP
after the form post has been done to free the resources.
Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
First, there are some basics you need to understand about multipart form
posts. Each part consists of at least a NAME and a CONTENTS part. If the part
is made for file upload, there are also a stored CONTENT\-TYPE and a FILENAME.
Below, we discuss what options you use to set these properties in the parts
you want to add to your post.
The options listed first are for making normal parts. The options from
\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
parts.
.SH OPTIONS
.IP CURLFORM_COPYNAME
followed by a string which provides the \fIname\fP of this part. libcurl
copies the string so your application does not need to keep it around after
this function call. If the name is not null\-terminated, you must set its
length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to
contain zero\-valued bytes. The copied data is freed by \fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRNAME
followed by a string which provides the \fIname\fP of this part. libcurl uses the
pointer and refer to the data in your application, so you must make sure it
remains until curl no longer needs it. If the name is not null\-terminated, you
must set its length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to
contain zero\-valued bytes.
.IP CURLFORM_COPYCONTENTS
followed by a pointer to the contents of this part, the actual data to send
away. libcurl copies the provided data, so your application does not need to
keep it around after this function call. If the data is not null\-terminated,
or if you would like it to contain zero bytes, you must set the length of the
name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data is freed by
\fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRCONTENTS
followed by a pointer to the contents of this part, the actual data to send
away. libcurl uses the pointer and refer to the data in your application, so
you must make sure it remains until curl no longer needs it. If the data is
not null\-terminated, or if you would like it to contain zero bytes, you must
set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
.IP CURLFORM_CONTENTLEN
followed by a curl_off_t value giving the length of the contents. Note that
for \fICURLFORM_STREAM\fP contents, this option is mandatory.
If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents
to figure out the size. If you really want to send a zero byte content then
you must make sure strlen() on the data pointer returns zero.
(Option added in 7.46.0)
.IP CURLFORM_CONTENTSLENGTH
(This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead.)
followed by a long giving the length of the contents. Note that for
\fICURLFORM_STREAM\fP contents, this option is mandatory.
If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents
to figure out the size. If you really want to send a zero byte content then
you must make sure strlen() on the data pointer returns zero.
.IP CURLFORM_FILECONTENT
followed by a filename, causes that file to be read and its contents used
as data in this part. This part does \fInot\fP automatically become a file
upload part simply because its data was read from a file.
The specified file needs to kept around until the associated transfer is done.
.IP CURLFORM_FILE
followed by a filename, makes this part a file upload part. It sets the
\fIfilename\fP field to the basename of the provided filename, it reads the
contents of the file and passes them as data and sets the content\-type if the
given file match one of the internally known file extensions. For
\fBCURLFORM_FILE\fP the user may send one or more files in one part by
providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
(and each \fICURLFORM_FILE\fP is allowed to have a
\fICURLFORM_CONTENTTYPE\fP).
The given upload file has to exist in its full in the file system already when
the upload starts, as libcurl needs to read the correct file size beforehand.
The specified file needs to kept around until the associated transfer is done.
.IP CURLFORM_CONTENTTYPE
is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
string which provides the content\-type for this part, possibly instead of an
internally chosen one.
.IP CURLFORM_FILENAME
is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
string, it tells libcurl to use the given string as the \fIfilename\fP in the file
upload part instead of the actual filename.
.IP CURLFORM_BUFFER
is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
tells libcurl that the file contents are already present in a buffer. The
parameter is a string which provides the \fIfilename\fP field in the content
header.
.IP CURLFORM_BUFFERPTR
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
to the buffer to be uploaded. This buffer must not be freed until after
\fIcurl_easy_cleanup(3)\fP is called. You must also use
\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
.IP CURLFORM_BUFFERLENGTH
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
long which gives the length of the buffer.
.IP CURLFORM_STREAM
Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
to the read callback\(aqs fourth argument. If you want the part to look like a
file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
set with the total expected length of the part unless the formpost is sent
chunked encoded. (Option added in libcurl 7.18.2)
.IP CURLFORM_ARRAY
Another possibility to send options to curl_formadd() is the
\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
its value. Each curl_forms structure element has a \fICURLformoption\fP and a
char pointer. The final element in the array must be a CURLFORM_END. All
available options can be used in an array, except the CURLFORM_ARRAY option
itself. The last argument in such an array must always be \fBCURLFORM_END\fP.
.IP CURLFORM_CONTENTHEADER
specifies extra headers for the form POST section. This takes a curl_slist
prepared in the usual way using \fBcurl_slist_append\fP and appends the list
of headers to those libcurl automatically generates. The list must exist while
the POST occurs, if you free it before the post completes you may experience
problems.
When you have passed the \fIstruct curl_httppost\fP pointer to
\fIcurl_easy_setopt(3)\fP (using the \fICURLOPT_HTTPPOST(3)\fP option), you
must not free the list until after you have called \fIcurl_easy_cleanup(3)\fP
for the curl handle.
See example below.
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
#include <string.h> /* for strlen */
static const char record[]="data in a buffer";
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
struct curl_httppost *post = NULL;
struct curl_httppost *last = NULL;
char namebuffer[] = "name buffer";
long namelength = strlen(namebuffer);
char buffer[] = "test buffer";
char htmlbuffer[] = "<HTML>test buffer</HTML>";
long htmlbufferlength = strlen(htmlbuffer);
struct curl_forms forms[3];
char file1[] = "my-face.jpg";
char file2[] = "your-face.jpg";
/* add null character into htmlbuffer, to demonstrate that
transfers of buffers containing null characters actually work
*/
htmlbuffer[8] = '\\0';
/* Add simple name/content section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
/* Add simple name/content/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
CURLFORM_COPYCONTENTS, "<HTML></HTML>",
CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
/* Add name/ptrcontent section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
/* Add ptrname/ptrcontent section */
curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
namelength, CURLFORM_END);
/* Add name/ptrcontent/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
CURLFORM_PTRCONTENTS, htmlbuffer,
CURLFORM_CONTENTSLENGTH, htmlbufferlength,
CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
/* Add simple file section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
/* Add file/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
CURLFORM_FILE, "my-face.jpg",
CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
/* Add two file section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
CURLFORM_FILE, "my-face.jpg",
CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
/* Add two file section using CURLFORM_ARRAY */
forms[0].option = CURLFORM_FILE;
forms[0].value = file1;
forms[1].option = CURLFORM_FILE;
forms[1].value = file2;
forms[2].option = CURLFORM_END;
/* Add a buffer to upload */
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "name",
CURLFORM_BUFFER, "data",
CURLFORM_BUFFERPTR, record,
CURLFORM_BUFFERLENGTH, sizeof(record),
CURLFORM_END);
/* no option needed for the end marker */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
CURLFORM_ARRAY, forms, CURLFORM_END);
/* Add the content of a file as a normal post text value */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
/* Set the form info */
curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
curl_easy_perform(curl);
curl_easy_cleanup(curl);
curl_formfree(post);
}
}
.fi
.SH DEPRECATED
Deprecated in 7.56.0. Before this release, field names were allowed to contain
zero\-valued bytes. The pseudo\-filename "\-" to read stdin is discouraged
although still supported, but data is not read before being actually sent: the
effective data size can then not be automatically determined, resulting in a
chunked encoding transfer. Backslashes and double quotes in field and
filenames are now escaped before transmission.
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
0 means everything was OK, non\-zero means an error occurred corresponding to a
\fICURL_FORMADD_\fI\fP constant defined in \fP<curl/curl.h>*.
.SH SEE ALSO
.BR curl_easy_setopt (3),
.BR curl_formfree (3),
.BR curl_mime_init (3)

63
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_formfree.3 Normal file
View File

@ -0,0 +1,63 @@
.\" generated by cd2nroff 0.1 from curl_formfree.md
.TH curl_formfree 3 "2025-08-14" libcurl
.SH NAME
curl_formfree \- free a previously build multipart form post chain
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_formfree(struct curl_httppost *form);
.fi
.SH DESCRIPTION
This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead.
curl_formfree() is used to clean up data previously built/appended with
\fIcurl_formadd(3)\fP. This must be called when the data has been used, which
typically means after \fIcurl_easy_perform(3)\fP has been called.
The pointer to free is the same pointer you passed to the
\fICURLOPT_HTTPPOST(3)\fP option, which is the \fIfirstitem\fP pointer from
the \fIcurl_formadd(3)\fP invoke(s).
\fBform\fP is the pointer as returned from a previous call to
\fIcurl_formadd(3)\fP and may be NULL.
Passing in a NULL pointer in \fIform\fP makes this function return immediately
with no action.
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
struct curl_httppost *formpost;
struct curl_httppost *lastptr;
/* Fill in a file upload field */
curl_formadd(&formpost,
&lastptr,
CURLFORM_COPYNAME, "file",
CURLFORM_FILE, "nice-image.jpg",
CURLFORM_END);
curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
curl_easy_perform(curl);
/* then cleanup the formpost chain */
curl_formfree(formpost);
}
}
.fi
.SH DEPRECATED
Deprecated in 7.56.0.
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
None
.SH SEE ALSO
.BR curl_formadd (3),
.BR curl_mime_free (3),
.BR curl_mime_init (3)

57
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_formget.3 Normal file
View File

@ -0,0 +1,57 @@
.\" generated by cd2nroff 0.1 from curl_formget.md
.TH curl_formget 3 "2025-08-14" libcurl
.SH NAME
curl_formget \- serialize a multipart form POST chain
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int curl_formget(struct curl_httppost * form, void *userp,
curl_formget_callback append);
.fi
.SH DESCRIPTION
The form API (including this function) is deprecated since libcurl 7.56.0.
curl_formget() serializes data previously built with \fIcurl_formadd(3)\fP. It
accepts a void pointer as second argument named \fIuserp\fP which is passed as the
first argument to the curl_formget_callback function.
.nf
typedef size_t (*curl_formget_callback)(void *userp, const char *buf,
size_t len);"
.fi
The \fIcurl_formget_callback\fP is invoked for each part of the HTTP POST chain.
The character buffer passed to the callback must not be freed. The callback
should return the buffer length passed to it on success.
If the \fBCURLFORM_STREAM\fP option is used in the formpost, it prevents
\fIcurl_formget(3)\fP from working until you have performed the actual HTTP request.
This, because first then does libcurl known which actual read callback to use.
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
size_t print_httppost_callback(void *arg, const char *buf, size_t len)
{
fwrite(buf, len, 1, stdout);
(*(size_t *) arg) += len;
return len;
}
size_t print_httppost(struct curl_httppost *post)
{
size_t total_size = 0;
if(curl_formget(post, &total_size, print_httppost_callback)) {
return (size_t) -1;
}
return total_size;
}
.fi
.SH AVAILABILITY
Added in curl 7.15.5
.SH RETURN VALUE
0 means everything was OK, non\-zero means an error occurred
.SH SEE ALSO
.BR curl_formadd (3),
.BR curl_mime_init (3)

37
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_free.3 Normal file
View File

@ -0,0 +1,37 @@
.\" generated by cd2nroff 0.1 from curl_free.md
.TH curl_free 3 "2025-08-14" libcurl
.SH NAME
curl_free \- reclaim memory that has been obtained through a libcurl call
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_free(void *ptr);
.fi
.SH DESCRIPTION
curl_free reclaims memory that has been obtained through a libcurl call. Use
\fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from
differences in memory management between your application and libcurl.
Passing in a NULL pointer in \fIptr\fP makes this function return immediately
with no action.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
char *width = curl_getenv("COLUMNS");
if(width) {
/* it was set */
curl_free(width);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
None
.SH SEE ALSO
.BR curl_easy_escape (3),
.BR curl_easy_unescape (3)

102
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_getdate.3 Normal file
View File

@ -0,0 +1,102 @@
.\" generated by cd2nroff 0.1 from curl_getdate.md
.TH curl_getdate 3 "2025-08-14" libcurl
.SH NAME
curl_getdate \- convert date string to number of seconds
.SH SYNOPSIS
.nf
#include <curl/curl.h>
time_t curl_getdate(const char *datestring, const time_t *now);
.fi
.SH DESCRIPTION
\fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January
1st 1970 00:00:00 in the UTC time zone, for the date and time that the
\fIdatestring\fP parameter specifies. The \fInow\fP parameter is not used,
pass a NULL there.
This function works with valid dates and does not always detect and reject
wrong dates, such as February 30.
.SH PARSING DATES AND TIMES
A "date" is a string containing several items separated by whitespace. The
order of the items is immaterial. A date string may contain many flavors of
items:
.IP "calendar date items"
Can be specified several ways. Month names can only be three\-letter English
abbreviations, numbers can be zero\-prefixed and the year may use 2 or 4
digits. Examples: 06 Nov 1994, 06\-Nov\-94 and Nov\-94 6.
If the year appears to be below 100 (two\-digit), any year after 70 is assumed
to be 1900 + the given year. All others are 2000 + the given year.
.IP "time of the day items"
This string specifies the time on a given day. You must specify it with 6
digits with two colons: HH:MM:SS. If there is no time given in a provided date
string, 00:00:00 is assumed. Example: 18:19:21.
.IP "time zone items"
Specifies international time zone. There are a few acronyms supported, but in
general you should instead use the specific relative time compared to
UTC. Supported formats include: \-1200, MST, +0100.
.IP "day of the week items"
Specifies a day of the week. Days of the week may be spelled out in full
(using English): \(aqSunday\(aq, \(aqMonday\(aq, etc or they may be abbreviated to their
first three letters. This is usually not info that adds anything.
.IP "pure numbers"
If a decimal number of the form YYYYMMDD appears, then YYYY is read as the
year, MM as the month number and DD as the day of the month, for the specified
calendar date.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
time_t t;
t = curl_getdate("Sun, 06 Nov 1994 08:49:37 GMT", NULL);
t = curl_getdate("Sunday, 06-Nov-94 08:49:37 GMT", NULL);
t = curl_getdate("Sun Nov 6 08:49:37 1994", NULL);
t = curl_getdate("06 Nov 1994 08:49:37 GMT", NULL);
t = curl_getdate("06-Nov-94 08:49:37 GMT", NULL);
t = curl_getdate("Nov 6 08:49:37 1994", NULL);
t = curl_getdate("06 Nov 1994 08:49:37", NULL);
t = curl_getdate("06-Nov-94 08:49:37", NULL);
t = curl_getdate("1994 Nov 6 08:49:37", NULL);
t = curl_getdate("GMT 08:49:37 06-Nov-94 Sunday", NULL);
t = curl_getdate("94 6 Nov 08:49:37", NULL);
t = curl_getdate("1994 Nov 6", NULL);
t = curl_getdate("06-Nov-94", NULL);
t = curl_getdate("Sun Nov 6 94", NULL);
t = curl_getdate("1994.Nov.6", NULL);
t = curl_getdate("Sun/Nov/6/94/GMT", NULL);
t = curl_getdate("Sun, 06 Nov 1994 08:49:37 CET", NULL);
t = curl_getdate("06 Nov 1994 08:49:37 EST", NULL);
t = curl_getdate("Sun, 12 Sep 2004 15:05:58 -0700", NULL);
t = curl_getdate("Sat, 11 Sep 2004 21:32:11 +0200", NULL);
t = curl_getdate("20040912 15:05:58 -0700", NULL);
t = curl_getdate("20040911 +0200", NULL);
}
.fi
.SH STANDARDS
This parser handles date formats specified in RFC 822 (including the update in
RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by
RFC 1036) and ANSI C\(aqs \fIasctime()\fP format.
These formats are the only ones RFC 7231 says HTTP applications may use.
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
This function returns \-1 when it fails to parse the date string. Otherwise it
returns the number of seconds as described.
On systems with a signed 32\-bit time_t: if the year is larger than 2037 or
less than 1903, this function returns \-1.
On systems with an unsigned 32\-bit time_t: if the year is larger than 2106 or
less than 1970, this function returns \-1.
On systems with 64\-bit time_t: if the year is less than 1583, this function
returns \-1. (The Gregorian calendar was first introduced 1582 so no "real"
dates in this way of doing dates existed before then.)
.SH SEE ALSO
.BR CURLOPT_TIMECONDITION (3),
.BR CURLOPT_TIMEVALUE (3),
.BR curl_easy_escape (3),
.BR curl_easy_unescape (3)

40
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_getenv.3 Normal file
View File

@ -0,0 +1,40 @@
.\" generated by cd2nroff 0.1 from curl_getenv.md
.TH curl_getenv 3 "2025-08-14" libcurl
.SH NAME
curl_getenv \- return value for environment name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_getenv(const char *name);
.fi
.SH DESCRIPTION
curl_getenv() is a portable wrapper for the getenv() function, meant to
emulate its behavior and provide an identical interface for all operating
systems libcurl builds on (including Windows).
You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
char *width = curl_getenv("COLUMNS");
if(width) {
/* it was set */
curl_free(width);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
A pointer to a null\-terminated string or NULL if it failed to find the
specified name.
.SH NOTE
Under Unix operating systems, there is no point in returning an allocated
memory, although other systems does not work properly if this is not done. The
Unix implementation thus suffers slightly from the drawbacks of other systems.
.SH SEE ALSO
.BR getenv (3C)

62
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_global_cleanup.3 Normal file
View File

@ -0,0 +1,62 @@
.\" generated by cd2nroff 0.1 from curl_global_cleanup.md
.TH curl_global_cleanup 3 "2025-08-14" libcurl
.SH NAME
curl_global_cleanup \- global libcurl cleanup
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_global_cleanup(void);
.fi
.SH DESCRIPTION
This function releases resources acquired by \fIcurl_global_init(3)\fP.
You should call \fIcurl_global_cleanup(3)\fP once for each call you make to
\fIcurl_global_init(3)\fP, after you are done using libcurl.
This function is thread\-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
(most platforms).
If this is not thread\-safe, you must not call this function when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This does not just mean no other thread that is using libcurl. Because
\fIcurl_global_cleanup(3)\fP calls functions of other libraries that are
similarly thread unsafe, it could conflict with any other thread that uses
these other libraries.
See the description in \fIlibcurl(3)\fP of global environment requirements for
details of how to use this function.
.SH CAUTION
\fIcurl_global_cleanup(3)\fP does not block waiting for any libcurl\-created
threads to terminate (such as threads used for name resolving). If a module
containing libcurl is dynamically unloaded while libcurl\-created threads are
still running then your program may crash or other corruption may occur. We
recommend you do not run libcurl from any module that may be unloaded
dynamically. This behavior may be addressed in the future.
libcurl may not be able to fully clean up after multi\-threaded OpenSSL
depending on how OpenSSL was built and loaded as a library. It is possible in
some rare circumstances a memory leak could occur unless you implement your own
OpenSSL thread cleanup. Refer to \fIlibcurl\-thread(3)\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
curl_global_init(CURL_GLOBAL_DEFAULT);
/* use libcurl, then before exiting... */
curl_global_cleanup();
}
.fi
.SH AVAILABILITY
Added in curl 7.8
.SH RETURN VALUE
None
.SH SEE ALSO
.BR curl_global_init (3),
.BR libcurl (3),
.BR libcurl-thread (3)

102
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_global_init.3 Normal file
View File

@ -0,0 +1,102 @@
.\" generated by cd2nroff 0.1 from curl_global_init.md
.TH curl_global_init 3 "2025-08-14" libcurl
.SH NAME
curl_global_init \- global libcurl initialization
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_global_init(long flags);
.fi
.SH DESCRIPTION
This function sets up the program environment that libcurl needs. Think of it
as an extension of the library loader.
This function must be called at least once within a program (a program is all
the code that shares a memory space) before the program calls any other
function in libcurl. The environment it sets up is constant for the life of
the program and is the same for every program, so multiple calls have the same
effect as one call.
The flags option is a bit pattern that tells libcurl exactly what features to
init, as described below. Set the desired bits by ORing the values together.
In normal operation, you must specify CURL_GLOBAL_ALL. Do not use any other
value unless you are familiar with it and mean to control internal operations
of libcurl.
This function is thread\-safe on most platforms. Then \fIcurl_version_info(3)\fP has
the \fIthreadsafe\fP feature set (added in 7.84.0).
If this is not thread\-safe (the bit mentioned above is not set), you must not
call this function when any other thread in the program (i.e. a thread sharing
the same memory) is running. This does not just mean no other thread that is
using libcurl. Because \fIcurl_global_init(3)\fP calls functions of other libraries
that are similarly thread unsafe, it could conflict with any other thread that
uses these other libraries.
If you are initializing libcurl from a Windows DLL you should not initialize
it from \fIDllMain\fP or a static initializer because Windows holds the loader
lock during that time and it could cause a deadlock.
See the description in \fIlibcurl(3)\fP of global environment requirements for
details of how to use this function.
.SH FLAGS
.IP CURL_GLOBAL_ALL
Initialize everything possible. This sets all known bits except
\fBCURL_GLOBAL_ACK_EINTR\fP.
.IP CURL_GLOBAL_SSL
(This flag\(aqs presence or absence serves no meaning since 7.57.0. The
description below is for older libcurl versions.)
Initialize SSL.
The implication here is that if this bit is not set, the initialization of the
SSL layer needs to be done by the application or at least outside of
libcurl. The exact procedure how to do SSL initialization depends on the TLS
backend libcurl uses.
Doing TLS based transfers without having the TLS layer initialized may lead to
unexpected behaviors.
.IP CURL_GLOBAL_WIN32
Initialize the Win32 socket libraries.
The implication here is that if this bit is not set, the initialization of
Winsock has to be done by the application or you risk getting undefined
behaviors. This option exists for when the initialization is handled outside
of libcurl so there is no need for libcurl to do it again.
.IP CURL_GLOBAL_NOTHING
Initialize nothing extra. This sets no bit.
.IP CURL_GLOBAL_DEFAULT
A sensible default. It initializes both SSL and Win32. Right now, this equals
the functionality of the \fBCURL_GLOBAL_ALL\fP mask.
.IP CURL_GLOBAL_ACK_EINTR
This bit has no point since 7.69.0 but its behavior is instead the default.
Before 7.69.0: when this flag is set, curl acknowledges EINTR condition when
connecting or when waiting for data. Otherwise, curl waits until full timeout
elapses. (Added in 7.30.0)
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
curl_global_init(CURL_GLOBAL_DEFAULT);
/* use libcurl, then before exiting... */
curl_global_cleanup();
}
.fi
.SH AVAILABILITY
Added in curl 7.8
.SH RETURN VALUE
If this function returns non\-zero, something went wrong and you cannot use the
other curl functions.
.SH SEE ALSO
.BR curl_easy_init (3),
.BR curl_global_cleanup (3),
.BR curl_global_init_mem (3),
.BR curl_global_sslset (3),
.BR curl_global_trace (3),
.BR libcurl (3)

72
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_global_init_mem.3 Normal file
View File

@ -0,0 +1,72 @@
.\" generated by cd2nroff 0.1 from curl_global_init_mem.md
.TH curl_global_init_mem 3 "2025-08-14" libcurl
.SH NAME
curl_global_init_mem \- global libcurl initialization with memory callbacks
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_global_init_mem(long flags,
curl_malloc_callback m,
curl_free_callback f,
curl_realloc_callback r,
curl_strdup_callback s,
curl_calloc_callback c);
.fi
.SH DESCRIPTION
This function works exactly as \fIcurl_global_init(3)\fP with one addition: it
allows the application to set callbacks to replace the otherwise used internal
memory functions.
If you are using libcurl from multiple threads or libcurl was built with the
threaded resolver option then the callback functions must be thread safe. The
threaded resolver is a common build option to enable (and in some cases the
default) so we strongly urge you to make your callback functions thread safe.
All callback arguments must be set to valid function pointers. The
prototypes for the given callbacks must match these:
.IP "void *malloc_callback(size_t size);"
To replace malloc()
.IP "void free_callback(void *ptr);"
To replace free()
.IP "void *realloc_callback(void *ptr, size_t size);"
To replace realloc()
.IP "char *strdup_callback(const char *str);"
To replace strdup()
.IP "void *calloc_callback(size_t nmemb, size_t size);"
To replace calloc()
This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer
to that man page for documentation.
.SH CAUTION
Manipulating these gives considerable powers to the application to severely
screw things up for libcurl. Take care.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
extern void *malloc_cb(size_t);
extern void free_cb(void *);
extern void *realloc_cb(void *, size_t);
extern char *strdup_cb(const char *);
extern void *calloc_cb(size_t, size_t);
int main(void)
{
curl_global_init_mem(CURL_GLOBAL_DEFAULT, malloc_cb,
free_cb, realloc_cb,
strdup_cb, calloc_cb);
}
.fi
.SH AVAILABILITY
Added in curl 7.12.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_global_cleanup (3),
.BR curl_global_init (3)

119
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_global_sslset.3 Normal file
View File

@ -0,0 +1,119 @@
.\" generated by cd2nroff 0.1 from curl_global_sslset.md
.TH curl_global_sslset 3 "2025-08-14" libcurl
.SH NAME
curl_global_sslset \- select SSL backend to use
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLsslset curl_global_sslset(curl_sslbackend id,
const char *name,
const curl_ssl_backend ***avail);
.fi
.SH DESCRIPTION
This function configures at runtime which SSL backend to use with
libcurl. This function can only be used to select an SSL backend once, and it
must be called \fBbefore\fP \fIcurl_global_init(3)\fP.
The backend can be identified by the \fIid\fP
(e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the
\fIname\fP parameter for a case insensitive match (passing
\fBCURLSSLBACKEND_NONE\fP as \fIid\fP). If both \fIid\fP and \fIname\fP are
specified, the \fIname\fP is ignored.
If neither \fIid\fP nor \fIname\fP are specified, the function fails with
\fBCURLSSLSET_UNKNOWN_BACKEND\fP and set the \fIavail\fP pointer to the
NULL\-terminated list of available backends. The available backends are those
that this particular build of libcurl supports.
Since libcurl 7.60.0, the \fIavail\fP pointer is always set to the list of
alternatives if non\-NULL.
Upon success, the function returns \fBCURLSSLSET_OK\fP.
If the specified SSL backend is not available, the function returns
\fBCURLSSLSET_UNKNOWN_BACKEND\fP and sets the \fIavail\fP pointer to a
NULL\-terminated list of available SSL backends. In this case, you may call the
function again to try to select a different backend.
The SSL backend can be set only once. If it has already been set, a subsequent
attempt to change it results in a \fBCURLSSLSET_TOO_LATE\fP getting returned.
This function is thread\-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
(most platforms).
If this is not thread\-safe, you must not call this function when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This does not just mean no other thread that is using libcurl.
.SH Names
SSL backend names (case\-insensitive): GnuTLS, mbedTLS, OpenSSL, Rustls,
Schannel, wolfSSL
The name "OpenSSL" is used for all versions of OpenSSL and its associated
forks/flavors in this function. OpenSSL, BoringSSL, LibreSSL, quictls and
AmiSSL are all supported by libcurl, but in the eyes of \fIcurl_global_sslset(3)\fP
they are all just "OpenSSL". They all mostly provide the same API.
\fIcurl_version_info(3)\fP can return more specific info about the exact OpenSSL
flavor and version number in use.
.SH struct
.nf
typedef struct {
curl_sslbackend id;
const char *name;
} curl_ssl_backend;
typedef enum {
CURLSSLBACKEND_NONE = 0,
CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */
CURLSSLBACKEND_GNUTLS = 2,
CURLSSLBACKEND_NSS = 3,
CURLSSLBACKEND_GSKIT = 5, /* deprecated */
CURLSSLBACKEND_POLARSSL = 6, /* deprecated */
CURLSSLBACKEND_WOLFSSL = 7,
CURLSSLBACKEND_SCHANNEL = 8,
CURLSSLBACKEND_SECURETRANSPORT = 9, /* deprecated */
CURLSSLBACKEND_AXTLS = 10, /* deprecated */
CURLSSLBACKEND_MBEDTLS = 11,
CURLSSLBACKEND_MESALINK = 12, /* deprecated */
CURLSSLBACKEND_BEARSSL = 13, /* deprecated */
CURLSSLBACKEND_RUSTLS = 14
} curl_sslbackend;
.fi
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
int i;
/* choose a specific backend */
curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL);
/* list the available ones */
const curl_ssl_backend **list;
curl_global_sslset(CURLSSLBACKEND_NONE, NULL, &list);
for(i = 0; list[i]; i++)
printf("SSL backend #%d: '%s' (ID: %d)\\n",
i, list[i]->name, list[i]->id);
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
If this function returns \fICURLSSLSET_OK\fP, the backend was successfully
selected.
If the chosen backend is unknown (or support for the chosen backend has not
been compiled into libcurl), the function returns
\fICURLSSLSET_UNKNOWN_BACKEND\fP.
If the backend had been configured previously, or if \fIcurl_global_init(3)\fP
has already been called, the function returns \fICURLSSLSET_TOO_LATE\fP.
If this libcurl was built completely without SSL support, with no backends at
all, this function returns \fICURLSSLSET_NO_BACKENDS\fP.
.SH SEE ALSO
.BR curl_global_init (3),
.BR libcurl (3)

142
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_global_trace.3 Normal file
View File

@ -0,0 +1,142 @@
.\" generated by cd2nroff 0.1 from curl_global_trace.md
.TH curl_global_trace 3 "2025-08-14" libcurl
.SH NAME
curl_global_trace \- log configuration
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_global_trace(const char *config);
.fi
.SH DESCRIPTION
This function configures the logging behavior to make some parts of curl more
verbose or silent than others.
This function may be called during the initialization phase of a program. It
does not have to be. It can be called several times even, possibly overwriting
settings of previous calls.
Calling this function after transfers have been started is undefined. On some
platforms/architectures it might take effect, on others not.
This function is thread\-safe since libcurl 8.3.0 if \fIcurl_version_info(3)\fP has
the CURL_VERSION_THREADSAFE feature bit set (most platforms).
If this is not thread\-safe, you must not call this function when any other
thread in the program (i.e. a thread sharing the same memory) is running. This
does not just mean no other thread that is using libcurl. Because
\fIcurl_global_init(3)\fP may call functions of other libraries that are similarly
thread unsafe, it could conflict with any other thread that uses these other
libraries.
If you are initializing libcurl from a Windows DLL you should not initialize
it from \fIDllMain\fP or a static initializer because Windows holds the loader
lock during that time and it could cause a deadlock.
The \fIconfig\fP string is a list of comma\-separated component names. Names are
case\-insensitive and unknown names are ignored. The special name "all" applies
to all components. Names may be prefixed with \(aq+\(aq or \(aq\-\(aq to enable or disable
detailed logging for a component.
The list of component names is not part of curl\(aqs public API. Names may be
added or disappear in future versions of libcurl. Since unknown names are
silently ignored, outdated log configurations does not cause errors when
upgrading libcurl. Given that, some names can be expected to be fairly stable
and are listed below for easy reference.
Note that log configuration applies only to transfers where debug logging is
enabled. See \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP on how to control
that.
.SH TRACE COMPONENTS
.IP tcp
Tracing of TCP socket handling: connect, sends, receives.
.IP ssl
Tracing of SSL/TLS operations, whichever SSL backend is used in your build.
.IP ftp
Tracing of FTP operations when this protocol is enabled in your build.
.IP http/2
Details about HTTP/2 handling: frames, events, I/O, etc.
.IP http/3
Details about HTTP/3 handling: connect, frames, events, I/O etc.
.IP http-proxy
Involved when transfers are tunneled through an HTTP proxy. "h1\-proxy" or
\&"h2\-proxy" are also involved, depending on the HTTP version negotiated with
the proxy.
In order to find out all components involved in a transfer, run it with "all"
configured. You can then see all names involved in your libcurl version in the
trace.
.IP dns
Tracing of DNS operations to resolve hostnames and HTTPS records.
.IP lib-ids
Adds transfer and connection identifiers as prefix to every call to
\fICURLOPT_DEBUGFUNCTION(3)\fP. The format is \fI[n\-m]\fP where \fIn\fP is the identifier
of the transfer and \fIm\fP is the identifier of the connection. A literal \fIx\fP
is used for internal transfers or when no connection is assigned.
For example, \fI[5\-x]\fP is the prefix for transfer 5 that has no
connection. The command line tool \fIcurl\fPuses the same format for its
\fI\--trace\-ids\fP option.
\fIlib\-ids\fP is intended for libcurl applications that handle multiple
transfers but have no own way to identify in trace output which transfer
a trace event is connected to.
.IP doh
Former name for DNS\-over\-HTTP operations. Now an alias for \fIdns\fP.
.IP multi
Traces multi operations managing transfers\(aq state changes and sockets poll
states.
.IP read
Traces reading of upload data from the application in order to send it to the
server.
.IP ssls
Tracing of SSL Session handling, e.g. caching/import/export.
.IP smtp
Tracing of SMTP operations when this protocol is enabled in your build.
.IP write
Traces writing of download data, received from the server, to the application.
.IP ws
Tracing of WebSocket operations when this protocol is enabled in your build.
.SH TRACE GROUPS
Besides the specific component names there are the following group names
defined:
.IP all
.IP network
All components involved in bare network I/O, including the SSL layer.
All components that your libcurl is built with.
.IP protocol
All components involved in transfer protocols, such as \(aqftp\(aq and \(aqhttp/2\(aq.
.IP proxy
All components involved in use of proxies.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
/* log details of HTTP/2 and SSL handling */
curl_global_trace("http/2,ssl");
/* log all details, except SSL handling */
curl_global_trace("all,-ssl");
}
.fi
Below is a trace sample where "http/2" was configured. The trace output
of an enabled component appears at the beginning in brackets.
.nf
* [HTTP/2] [h2sid=1] cf_send(len=96) submit https://example.com/
\&...
* [HTTP/2] [h2sid=1] FRAME[HEADERS]
* [HTTP/2] [h2sid=1] 249 header bytes
\&...
.fi
.SH AVAILABILITY
Added in curl 8.3.0
.SH RETURN VALUE
If this function returns non\-zero, something went wrong and the configuration
may not have any effects or may only been applied partially.
.SH SEE ALSO
.BR curl_global_init (3),
.BR libcurl (3)

55
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_addpart.3 Normal file
View File

@ -0,0 +1,55 @@
.\" generated by cd2nroff 0.1 from curl_mime_addpart.md
.TH curl_mime_addpart 3 "2025-08-14" libcurl
.SH NAME
curl_mime_addpart \- append a new empty part to a mime structure
.SH SYNOPSIS
.nf
#include <curl/curl.h>
curl_mimepart *curl_mime_addpart(curl_mime *mime);
.fi
.SH DESCRIPTION
\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given
mime structure and returns a handle to it. The returned part handle can
subsequently be populated using functions from the mime API.
\fImime\fP is the handle of the mime structure in which the new part must be
appended.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
curl_mime *mime;
curl_mimepart *part;
CURL *curl = curl_easy_init();
if(curl) {
/* create a mime handle */
mime = curl_mime_init(curl);
/* add a part */
part = curl_mime_addpart(mime);
/* continue and set name + data to the part */
curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
curl_mime_name(part, "data");
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
A mime part structure handle, or NULL upon failure.
.SH SEE ALSO
.BR curl_mime_data (3),
.BR curl_mime_data_cb (3),
.BR curl_mime_encoder (3),
.BR curl_mime_filedata (3),
.BR curl_mime_filename (3),
.BR curl_mime_headers (3),
.BR curl_mime_init (3),
.BR curl_mime_name (3),
.BR curl_mime_subparts (3),
.BR curl_mime_type (3)

66
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_data.3 Normal file
View File

@ -0,0 +1,66 @@
.\" generated by cd2nroff 0.1 from curl_mime_data.md
.TH curl_mime_data 3 "2025-08-14" libcurl
.SH NAME
curl_mime_data \- set a mime part\(aqs body data from memory
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_data(curl_mimepart *part, const char *data,
size_t datasize);
.fi
.SH DESCRIPTION
\fIcurl_mime_data(3)\fP sets a mime part\(aqs body content from memory data.
\fIpart\fP is the mime part to assign contents to, created with
\fIcurl_mime_addpart(3)\fP.
\fIdata\fP points to the data that gets copied by this function. The storage
may safely be reused after the call.
\fIdatasize\fP is the number of bytes \fIdata\fP points to. It can be set to
\fICURL_ZERO_TERMINATED\fP to indicate \fIdata\fP is a null\-terminated
character string.
Setting a part\(aqs contents multiple times is valid: only the value set by the
last call is retained. It is possible to unassign part\(aqs contents by setting
\fIdata\fP to NULL.
Setting large data is memory consuming: one might consider using
\fIcurl_mime_data_cb(3)\fP in such a case.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
curl_mime *mime;
curl_mimepart *part;
CURL *curl = curl_easy_init();
if(curl) {
/* create a mime handle */
mime = curl_mime_init(curl);
/* add a part */
part = curl_mime_addpart(mime);
/* add data to the part */
curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_mime_addpart (3),
.BR curl_mime_data_cb (3),
.BR curl_mime_name (3),
.BR curl_mime_type (3)

158
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_data_cb.3 Normal file
View File

@ -0,0 +1,158 @@
.\" generated by cd2nroff 0.1 from curl_mime_data_cb.md
.TH curl_mime_data_cb 3 "2025-08-14" libcurl
.SH NAME
curl_mime_data_cb \- set a callback\-based data source for a mime part\(aqs body
.SH SYNOPSIS
.nf
#include <curl/curl.h>
size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
int seekfunc(void *arg, curl_off_t offset, int origin);
void freefunc(void *arg);
CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
curl_read_callback readfunc,
curl_seek_callback seekfunc,
curl_free_callback freefunc, void *arg);
.fi
.SH DESCRIPTION
\fIcurl_mime_data_cb(3)\fP sets the data source of a mime part\(aqs body content
from a data read callback function.
\fIpart\fP is the part\(aqs to assign contents to.
\fIreadfunc\fP is a pointer to a data read callback function, with a signature
as shown by the above prototype. It may not be set to NULL.
\fIseekfunc\fP is a pointer to a seek callback function, with a signature as
shown by the above prototype. This function is used when resending data (i.e.:
after a redirect); this pointer may be set to NULL, in which case a resend
might not be not possible.
\fIfreefunc\fP is a pointer to a user resource freeing callback function, with
a signature as shown by the above prototype. If no resource is to be freed, it
may safely be set to NULL. This function is called upon mime structure
freeing.
\fIarg\fP is a user defined argument to callback functions.
The read callback function gets called by libcurl as soon as it needs to
read data in order to send it to the peer \- like if you ask it to upload or
post data to the server. The data area pointed at by the pointer \fIbuffer\fP
should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number
of bytes by your function.
Your read function must then return the actual number of bytes that it stored
in that memory area. Returning 0 signals end\-of\-file to the library and cause
it to stop the current transfer.
If you stop the current transfer by returning 0 "pre\-maturely" (i.e. before
the server expected it, like when you have said you intend to upload N bytes
and yet you upload less than N bytes), you may experience that the server
\&"hangs" waiting for the rest of the data that does not come.
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
code from the transfer.
The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
The seek function gets called by libcurl to rewind input stream data or to
seek to a certain position. The function shall work like fseek(3) or lseek(3)
and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP,
although libcurl currently only passes SEEK_SET.
The callback function must return \fICURL_SEEKFUNC_OK\fP on success,
\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or
\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl
is free to work around the problem if possible. The latter can sometimes be
done by instead reading from the input or similar.
Care must be taken if the part is bound to a curl easy handle that is later
duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in
the pointed item to be shared between the original and the copied handle. In
particular, special attention should be given to the \fIfreefunc\fP procedure
code since it then gets called twice with the same argument.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
Sending a huge data string causes the same amount of memory to be allocated:
to avoid overhead resources consumption, one might want to use a callback
source to avoid data duplication. In this case, original data must be retained
until after the transfer terminates.
.nf
#include <string.h> /* for memcpy */
char hugedata[512000];
struct ctl {
char *buffer;
curl_off_t size;
curl_off_t position;
};
size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
{
struct ctl *p = (struct ctl *) arg;
curl_off_t sz = p->size - p->position;
nitems *= size;
if(sz > nitems)
sz = nitems;
if(sz)
memcpy(buffer, p->buffer + p->position, sz);
p->position += sz;
return sz;
}
int seek_callback(void *arg, curl_off_t offset, int origin)
{
struct ctl *p = (struct ctl *) arg;
switch(origin) {
case SEEK_END:
offset += p->size;
break;
case SEEK_CUR:
offset += p->position;
break;
}
if(offset < 0)
return CURL_SEEKFUNC_FAIL;
p->position = offset;
return CURL_SEEKFUNC_OK;
}
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
curl_mime *mime = curl_mime_init(curl);
curl_mimepart *part = curl_mime_addpart(mime);
struct ctl hugectl;
hugectl.buffer = hugedata;
hugectl.size = sizeof(hugedata);
hugectl.position = 0;
curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
&hugectl);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_easy_duphandle (3),
.BR curl_mime_addpart (3),
.BR curl_mime_data (3),
.BR curl_mime_name (3)

90
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_encoder.3 Normal file
View File

@ -0,0 +1,90 @@
.\" generated by cd2nroff 0.1 from curl_mime_encoder.md
.TH curl_mime_encoder 3 "2025-08-14" libcurl
.SH NAME
curl_mime_encoder \- set a mime part\(aqs encoder and content transfer encoding
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_encoder(curl_mimepart *part, const char *encoding);
.fi
.SH DESCRIPTION
curl_mime_encoder() requests a mime part\(aqs content to be encoded before being
transmitted.
\fIpart\fP is the part\(aqs handle to assign an encoder.
\fIencoding\fP is a pointer to a null\-terminated encoding scheme. It may be
set to NULL to disable an encoder previously attached to the part. The encoding
scheme storage may safely be reused after this function returns.
Setting a part\(aqs encoder multiple times is valid: only the value set by the
last call is retained.
Upon multipart rendering, the part\(aqs content is encoded according to the
pertaining scheme and a corresponding \fI"Content\-Transfer\-Encoding"\fP header
is added to the part.
Supported encoding schemes are:
\&"\fIbinary\fP": the data is left unchanged, the header is added.
\&"\fI8bit\fP": header added, no data change.
\&"\fI7bit\fP": the data is unchanged, but is each byte is checked
to be a 7\-bit value; if not, a read error occurs.
\&"\fIbase64\fP": Data is converted to base64 encoding, then split in
CRLF\-terminated lines of at most 76 characters.
\&"\fIquoted\-printable\fP": data is encoded in quoted printable lines of
at most 76 characters. Since the resulting size of the final data cannot be
determined prior to reading the original data, it is left as unknown, causing
chunked transfer in HTTP. For the same reason, this encoder may not be used
with IMAP. This encoder targets text data that is mostly ASCII and should
not be used with other types of data.
If the original data is already encoded in such a scheme, a custom
\fIContent\-Transfer\-Encoding\fP header should be added with
\fIcurl_mime_headers(3)\fP instead of setting a part encoder.
Encoding should not be applied to multiparts, thus the use of this function on
a part with content set with \fIcurl_mime_subparts(3)\fP is strongly
discouraged.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
curl_mime *mime;
curl_mimepart *part;
CURL *curl = curl_easy_init();
if(curl) {
/* create a mime handle */
mime = curl_mime_init(curl);
/* add a part */
part = curl_mime_addpart(mime);
/* send a file */
curl_mime_filedata(part, "image.png");
/* encode file data in base64 for transfer */
curl_mime_encoder(part, "base64");
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_mime_addpart (3),
.BR curl_mime_headers (3),
.BR curl_mime_subparts (3)

79
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_filedata.3 Normal file
View File

@ -0,0 +1,79 @@
.\" generated by cd2nroff 0.1 from curl_mime_filedata.md
.TH curl_mime_filedata 3 "2025-08-14" libcurl
.SH NAME
curl_mime_filedata \- set a mime part\(aqs body data from a file contents
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_filedata(curl_mimepart *part,
const char *filename);
.fi
.SH DESCRIPTION
\fIcurl_mime_filedata(3)\fP sets a mime part\(aqs body content from the named
file\(aqs contents. This is an alternative to \fIcurl_mime_data(3)\fP for setting
data to a mime part.
\fIpart\fP is the part\(aqs to assign contents to.
\fIfilename\fP points to the null\-terminated file\(aqs path name. The pointer can
be NULL to detach the previous part contents settings. Filename storage can
be safely be reused after this call.
As a side effect, the part\(aqs remote filename is set to the base name of the
given \fIfilename\fP if it is a valid named file. This can be undone or
overridden by a subsequent call to \fIcurl_mime_filename(3)\fP.
The contents of the file is read during the file transfer in a streaming
manner to allow huge files to get transferred without using much memory. It
therefore requires that the file is kept intact during the entire request.
If the file size cannot be determined before actually reading it (such as for
a character device or named pipe), the whole mime structure containing the
part is transferred using chunks by HTTP but is rejected by IMAP.
Setting a part\(aqs contents multiple times is valid: only the value set by the
last call is retained.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
curl_mime *mime;
curl_mimepart *part;
CURL *curl = curl_easy_init();
if(curl) {
/* create a mime handle */
mime = curl_mime_init(curl);
/* add a part */
part = curl_mime_addpart(mime);
/* send data from this file */
curl_mime_filedata(part, "image.png");
/* set name */
curl_mime_name(part, "data");
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
CURLE_READ_ERROR is only an indication that the file is not yet readable: it
can be safely ignored at this time, but the file must be made readable before
the pertaining easy handle is performed.
.SH SEE ALSO
.BR curl_mime_addpart (3),
.BR curl_mime_data (3),
.BR curl_mime_filename (3),
.BR curl_mime_name (3)

69
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_filename.3 Normal file
View File

@ -0,0 +1,69 @@
.\" generated by cd2nroff 0.1 from curl_mime_filename.md
.TH curl_mime_filename 3 "2025-08-14" libcurl
.SH NAME
curl_mime_filename \- set a mime part\(aqs remote filename
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_filename(curl_mimepart *part,
const char *filename);
.fi
.SH DESCRIPTION
\fIcurl_mime_filename(3)\fP sets a mime part\(aqs remote filename. When remote
filename is set, content data is processed as a file, whatever is the part\(aqs
content source. A part\(aqs remote filename is transmitted to the server in the
associated Content\-Disposition generated header.
\fIpart\fP is the part\(aqs handle to assign the remote filename to.
\fIfilename\fP points to the null\-terminated filename string; it may be set
to NULL to remove a previously attached remote filename.
The remote filename string is copied into the part, thus the associated
storage may safely be released or reused after call. Setting a part\(aqs file
name multiple times is valid: only the value set by the last call is retained.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
static char imagebuf[]="imagedata";
int main(void)
{
curl_mime *mime;
curl_mimepart *part;
CURL *curl = curl_easy_init();
if(curl) {
/* create a mime handle */
mime = curl_mime_init(curl);
/* add a part */
part = curl_mime_addpart(mime);
/* send image data from memory */
curl_mime_data(part, imagebuf, sizeof(imagebuf));
/* set a file name to make it look like a file upload */
curl_mime_filename(part, "image.png");
/* set name */
curl_mime_name(part, "data");
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_mime_addpart (3),
.BR curl_mime_data (3),
.BR curl_mime_filedata (3)

50
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_free.3 Normal file
View File

@ -0,0 +1,50 @@
.\" generated by cd2nroff 0.1 from curl_mime_free.md
.TH curl_mime_free 3 "2025-08-14" libcurl
.SH NAME
curl_mime_free \- free a previously built mime structure
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_mime_free(curl_mime *mime);
.fi
.SH DESCRIPTION
\fIcurl_mime_free(3)\fP is used to clean up data previously built/appended
with \fIcurl_mime_addpart(3)\fP and other mime\-handling functions. This must
be called when the data has been used, which typically means after
\fIcurl_easy_perform(3)\fP has been called.
The handle to free is the one you passed to the \fICURLOPT_MIMEPOST(3)\fP
option: attached sub part mime structures must not be explicitly freed as they
are by the top structure freeing.
\fBmime\fP is the handle as returned from a previous call to
\fIcurl_mime_init(3)\fP and may be NULL.
Passing in a NULL pointer in \fImime\fP makes this function return immediately
with no action.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
/* Build the mime message. */
curl_mime *mime = curl_mime_init(curl);
/* send off the transfer */
/* Free multipart message. */
curl_mime_free(mime);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
None
.SH SEE ALSO
.BR curl_free (3),
.BR curl_mime_init (3)

68
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_headers.3 Normal file
View File

@ -0,0 +1,68 @@
.\" generated by cd2nroff 0.1 from curl_mime_headers.md
.TH curl_mime_headers 3 "2025-08-14" libcurl
.SH NAME
curl_mime_headers \- set a mime part\(aqs custom headers
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_headers(curl_mimepart *part,
struct curl_slist *headers, int take_ownership);
.fi
.SH DESCRIPTION
\fIcurl_mime_headers(3)\fP sets a mime part\(aqs custom headers.
\fIpart\fP is the part\(aqs handle to assign the custom headers list to.
\fIheaders\fP is the head of a list of custom headers; it may be set to NULL
to remove a previously attached custom header list.
\fItake_ownership\fP: when non\-zero, causes the list to be freed upon
replacement or mime structure deletion; in this case the list must not be
freed explicitly.
Setting a part\(aqs custom headers list multiple times is valid: only the value
set by the last call is retained.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
struct curl_slist *headers = NULL;
CURL *easy = curl_easy_init();
curl_mime *mime;
curl_mimepart *part;
headers = curl_slist_append(headers, "Custom-Header: mooo");
mime = curl_mime_init(easy);
part = curl_mime_addpart(mime);
/* use these headers in the part, takes ownership */
curl_mime_headers(part, headers, 1);
/* pass on this data */
curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED);
/* set name */
curl_mime_name(part, "numbers");
/* Post and send it. */
curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime);
curl_easy_setopt(easy, CURLOPT_URL, "https://example.com");
curl_easy_perform(easy);
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_mime_addpart (3),
.BR curl_mime_name (3)

57
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_init.3 Normal file
View File

@ -0,0 +1,57 @@
.\" generated by cd2nroff 0.1 from curl_mime_init.md
.TH curl_mime_init 3 "2025-08-14" libcurl
.SH NAME
curl_mime_init \- create a mime handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
curl_mime *curl_mime_init(CURL *easy_handle);
.fi
.SH DESCRIPTION
\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure.
This mime structure can be subsequently filled using the mime API, then
attached to some easy handle using option \fICURLOPT_MIMEPOST(3)\fP within
a \fIcurl_easy_setopt(3)\fP call or added as a multipart in another mime
handle\(aqs part using \fIcurl_mime_subparts(3)\fP.
\fIeasy_handle\fP is used for part separator randomization and error
reporting. Since 7.87.0, it does not need to be the final target handle.
Using a mime handle is the recommended way to post an HTTP form, format and
send a multi\-part email with SMTP or upload such an email to an IMAP server.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
CURL *easy = curl_easy_init();
curl_mime *mime;
curl_mimepart *part;
/* Build an HTTP form with a single field named "data", */
mime = curl_mime_init(easy);
part = curl_mime_addpart(mime);
curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
curl_mime_name(part, "data");
/* Post and send it. */
curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime);
curl_easy_setopt(easy, CURLOPT_URL, "https://example.com");
curl_easy_perform(easy);
/* Clean-up. */
curl_easy_cleanup(easy);
curl_mime_free(mime);
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
A mime struct handle, or NULL upon failure.
.SH SEE ALSO
.BR CURLOPT_MIMEPOST (3),
.BR curl_mime_addpart (3),
.BR curl_mime_free (3),
.BR curl_mime_subparts (3)

57
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_name.3 Normal file
View File

@ -0,0 +1,57 @@
.\" generated by cd2nroff 0.1 from curl_mime_name.md
.TH curl_mime_name 3 "2025-08-14" libcurl
.SH NAME
curl_mime_name \- set a mime part\(aqs name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_name(curl_mimepart *part, const char *name);
.fi
.SH DESCRIPTION
\fIcurl_mime_name(3)\fP sets a mime part\(aqs name. This is the way HTTP form
fields are named.
\fIpart\fP is the part\(aqs handle to assign a name to.
\fIname\fP points to the null\-terminated name string.
The name string is copied into the part, thus the associated storage may
safely be released or reused after call. Setting a part\(aqs name multiple times
is valid: only the value set by the last call is retained. It is possible to
reset the name of a part by setting \fIname\fP to NULL.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
curl_mime *mime;
curl_mimepart *part;
CURL *curl = curl_easy_init();
if(curl) {
/* create a mime handle */
mime = curl_mime_init(curl);
/* add a part */
part = curl_mime_addpart(mime);
/* give the part a name */
curl_mime_name(part, "shoe_size");
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_mime_addpart (3),
.BR curl_mime_data (3),
.BR curl_mime_type (3)

73
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_subparts.3 Normal file
View File

@ -0,0 +1,73 @@
.\" generated by cd2nroff 0.1 from curl_mime_subparts.md
.TH curl_mime_subparts 3 "2025-08-14" libcurl
.SH NAME
curl_mime_subparts \- set sub\-parts of a multipart mime part
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_subparts(curl_mimepart *part, curl_mime *subparts);
.fi
.SH DESCRIPTION
\fIcurl_mime_subparts(3)\fP sets a multipart mime part\(aqs content from a mime
structure.
\fIpart\fP is a handle to the multipart part.
\fIsubparts\fP is a mime structure handle holding the sub\-parts. After
\fIcurl_mime_subparts(3)\fP succeeds, the mime structure handle belongs to the
multipart part and must not be freed explicitly. It may however be updated by
subsequent calls to mime API functions.
Setting a part\(aqs contents multiple times is valid: only the value set by the
last call is retained. It is possible to unassign previous part\(aqs contents by
setting \fIsubparts\fP to NULL.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
static char *inline_html = "<title>example</title>";
static char *inline_text = "once upon the time";
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
struct curl_slist *slist;
/* The inline part is an alternative proposing the html and the text
versions of the email. */
curl_mime *alt = curl_mime_init(curl);
curl_mimepart *part;
/* HTML message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED);
curl_mime_type(part, "text/html");
/* Text message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED);
/* Create the inline part. */
part = curl_mime_addpart(alt);
curl_mime_subparts(part, alt);
curl_mime_type(part, "multipart/alternative");
slist = curl_slist_append(NULL, "Content-Disposition: inline");
curl_mime_headers(part, slist, 1);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_mime_addpart (3),
.BR curl_mime_init (3)

76
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mime_type.3 Normal file
View File

@ -0,0 +1,76 @@
.\" generated by cd2nroff 0.1 from curl_mime_type.md
.TH curl_mime_type 3 "2025-08-14" libcurl
.SH NAME
curl_mime_type \- set a mime part\(aqs content type
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_type(curl_mimepart *part, const char *mimetype);
.fi
.SH DESCRIPTION
\fIcurl_mime_type(3)\fP sets a mime part\(aqs content type.
\fIpart\fP is the part\(aqs handle to assign the content type to.
\fImimetype\fP points to the null\-terminated file mime type string; it may be
set to NULL to remove a previously attached mime type.
The mime type string is copied into the part, thus the associated storage may
safely be released or reused after call. Setting a part\(aqs type multiple times
is valid: only the value set by the last call is retained.
In the absence of a mime type and if needed by the protocol specifications,
a default mime type is determined by the context:
- If set as a custom header, use this value.
- application/form\-data for an HTTP form post.
- If a remote filename is set, the mime type is taken from the filename
extension, or application/octet\-stream by default.
- For a multipart part, multipart/mixed.
- text/plain in other cases.
.SH PROTOCOLS
This functionality affects http, imap and smtp
.SH EXAMPLE
.nf
int main(void)
{
curl_mime *mime;
curl_mimepart *part;
CURL *curl = curl_easy_init();
if(curl) {
/* create a mime handle */
mime = curl_mime_init(curl);
/* add a part */
part = curl_mime_addpart(mime);
/* get data from this file */
curl_mime_filedata(part, "image.png");
/* content-type for this part */
curl_mime_type(part, "image/png");
/* set name */
curl_mime_name(part, "image");
}
}
.fi
.SH AVAILABILITY
Added in curl 7.56.0
.SH RETURN VALUE
This function returns a CURLcode indicating success or error.
CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP
there can be an error message stored in the error buffer when non\-zero is
returned.
.SH SEE ALSO
.BR curl_mime_addpart (3),
.BR curl_mime_data (3),
.BR curl_mime_name (3)

217
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_mprintf.3 Normal file
View File

@ -0,0 +1,217 @@
.\" generated by cd2nroff 0.1 from curl_mprintf.md
.TH curl_printf 3 "2025-08-14" libcurl
.SH NAME
curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf,
curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf,
curl_mvsprintf \- formatted output conversion
.SH SYNOPSIS
.nf
#include <curl/mprintf.h>
int curl_mprintf(const char *format, ...);
int curl_mfprintf(FILE *fd, const char *format, ...);
int curl_msprintf(char *buffer, const char *format, ...);
int curl_msnprintf(char *buffer, size_t maxlength, const char *format, ...);
int curl_mvprintf(const char *format, va_list args);
int curl_mvfprintf(FILE *fd, const char *format, va_list args);
int curl_mvsprintf(char *buffer, const char *format, va_list args);
int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format,
va_list args);
char *curl_maprintf(const char *format , ...);
char *curl_mvaprintf(const char *format, va_list args);
.fi
.SH DESCRIPTION
These functions produce output according to the format string and given
arguments. They are mostly clones of the well\-known C\-style functions but
there are slight differences in behavior.
We discourage users from using any of these functions in new applications.
Functions in the curl_mprintf() family produce output according to a format as
described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP
write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and
\fBcurl_mvfprintf()\fP write output to the given output stream;
\fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and
\fBcurl_mvsnprintf()\fP write to the character string \fBbuffer\fP.
The functions \fBcurl_msnprintf()\fP and \fBcurl_mvsnprintf()\fP write at most
\fImaxlength\fP bytes (including the terminating null byte (\(aq0\(aq)) to
\fIbuffer\fP.
The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP,
\fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the
functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP,
\fBcurl_msnprintf()\fP, respectively, except that they are called with a
\fIva_list\fP instead of a variable number of arguments. These functions do
not call the \fIva_end\fP macro. Because they invoke the \fIva_arg\fP macro,
the value of \fIap\fP is undefined after the call.
The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the
output string as pointer to a newly allocated memory area. The returned string
must be \fIcurl_free(3)\fPed by the receiver.
All of these functions write the output under the control of a format string
that specifies how subsequent arguments are converted for output.
.SH FORMAT STRING
The format string is composed of zero or more directives: ordinary characters
(not %), which are copied unchanged to the output stream; and conversion
specifications, each of which results in fetching zero or more subsequent
arguments. Each conversion specification is introduced by the character %, and
ends with a conversion specifier. In between there may be (in this order) zero
or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional
\fIprecision\fP and an optional \fIlength modifier\fP.
.SH The $ modifier
The arguments must correspond properly with the conversion specifier. By
default, the arguments are used in the order given, where each \(aq*\(aq (see Field
width and Precision below) and each conversion specifier asks for the next
argument (and it is an error if insufficiently many arguments are given). One
can also specify explicitly which argument is taken, at each place where an
argument is required, by writing "%m$" instead of \(aq%\(aq and "*m$" instead
of \(aq*\(aq, where the decimal integer m denotes the position in the argument list
of the desired argument, indexed starting from 1. Thus,
.nf
curl_mprintf("%*d", width, num);
.fi
and
.nf
curl_mprintf("%2$*1$d", width, num);
.fi
are equivalent. The second style allows repeated references to the same
argument.
If the style using \(aq$\(aq is used, it must be used throughout for all conversions
taking an argument and all width and precision arguments, but it may be mixed
with "%%" formats, which do not consume an argument. There may be no gaps in
the numbers of arguments specified using \(aq$\(aq; for example, if arguments 1 and
3 are specified, argument 2 must also be specified somewhere in the format
string.
.SH Flag characters
The character % is followed by zero or more of the following flags:
.IP #
The value should be converted to its "alternate form".
.IP 0
The value should be zero padded.
.IP -
The converted value is to be left adjusted on the field boundary. (The default
is right justification.) The converted value is padded on the right with
blanks, rather than on the left with blanks or zeros. A \(aq\-\(aq overrides a &\(aq0\(aq
if both are given.
.IP (space)
(a space: \(aq \(aq) A blank should be left before a positive number (or empty
string) produced by a signed conversion.
.IP +
A sign (+ or \-) should always be placed before a number produced by a signed
conversion. By default, a sign is used only for negative numbers. A \(aq+\(aq
overrides a space if both are used.
.SH Field width
An optional decimal digit string (with nonzero first digit) specifying a
minimum field width. If the converted value has fewer characters than the
field width, it gets padded with spaces on the left (or right, if the
left\-adjustment flag has been given). Instead of a decimal digit string one
may write "\fI" or "\fPm$" (for some decimal integer m) to specify that the field
width is given in the next argument, or in the \fIm\-th\fP argument,
respectively, which must be of type int. A negative field width is taken as
a \(aq\-\(aq flag followed by a positive field width. In no case does a nonexistent
or small field width cause truncation of a field; if the result of a
conversion is wider than the field width, the field is expanded to contain the
conversion result.
.SH Precision
An optional precision in the form of a period (\(aq.\(aq) followed by an optional
decimal digit string. Instead of a decimal digit string one may write "*" or
\&"*m$" (for some decimal integer m) to specify that the precision is given in
the next argument, or in the \fIm\-th\fP argument, respectively, which must be of
type int. If the precision is given as just \(aq.\(aq, the precision is taken to be
zero. A negative precision is taken as if the precision were omitted. This
gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP,
\fBu\fP, \fBx\fP, and \fBX\fP conversions, the number of digits to appear
after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and
\fBF\fP conversions, the maximum number of significant digits for \fBg\fP and
\fBG\fP conversions, or the maximum number of characters to be printed from a
string for \fBs\fP and \fBS\fP conversions.
.SH Length modifier
.IP h
A following integer conversion corresponds to a \fIshort\fP or \fIunsigned short\fP
argument.
.IP l
(ell) A following integer conversion corresponds to a \fIlong\fP or
\fIunsigned long\fP argument, or a following n conversion corresponds to a
pointer to a long argument
.IP ll
(ell\-ell). A following integer conversion corresponds to a \fIlong long\fP or
\fIunsigned long long\fP argument, or a following n conversion corresponds to
a pointer to a \fIlong long\fP argument.
.IP q
A synonym for \fBll\fP.
.IP L
A following a, A, e, E, f, F, g, or G conversion corresponds to a long double
argument.
.IP z
A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP
argument.
.SH Conversion specifiers
A character that specifies the type of conversion to be applied. The
conversion specifiers and their meanings are:
.IP "d, i"
The int argument is converted to signed decimal notation. The precision, if
any, gives the minimum number of digits that must appear; if the converted
value requires fewer digits, it is padded on the left with zeros. The default
precision is 1. When 0 is printed with an explicit precision 0, the output is
empty.
.IP "o, u, x, X"
The unsigned int argument is converted to unsigned octal (o), unsigned decimal
(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters
\fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are
used for \fBX\fP conversions. The precision, if any, gives the minimum number
of digits that must appear; if the converted value requires fewer digits, it
is padded on the left with zeros. The default precision is 1. When 0 is
printed with an explicit precision 0, the output is empty.
.IP "e, E"
The double argument is rounded and output in the style \fB"[\-]d.ddde{+|\-}dd"\fP
.IP "f, F"
The double argument is rounded and output to decimal notation in the style
\fB"[\-]ddd.ddd"\fP.
.IP "g, G"
The double argument is converted in style f or e.
.IP c
The int argument is converted to an unsigned char, and the resulting character
is written.
.IP s
The \fIconst char \fP* argument is expected to be a pointer to an array of
character type (pointer to a string). Characters from the array are written up
to (but not including) a terminating null byte. If a precision is specified,
no more than the number specified are written. If a precision is given, no
null byte need be present; if the precision is not specified, or is greater
than the size of the array, the array must contain a terminating null byte.
.IP p
The \fIvoid \fP* pointer argument is printed in hexadecimal.
.IP n
The number of characters written so far is stored into the integer pointed to
by the corresponding argument.
.IP %
A \(aq%\(aq symbol is written. No argument is converted.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
const char *name = "John";
int main(void)
{
curl_mprintf("My name is %s\\n", name);
curl_mprintf("Pi is almost %f\\n", (double)25.0/8);
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to
a newly allocated string, or NULL if it failed.
All other functions return the number of characters actually printed
(excluding the null byte used to end output to strings). Note that this
sometimes differ from how the POSIX versions of these functions work.
.SH SEE ALSO
.BR fprintf (3),
.BR printf (3),
.BR sprintf (3),
.BR vprintf (3)

76
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_add_handle.3 Normal file
View File

@ -0,0 +1,76 @@
.\" generated by cd2nroff 0.1 from curl_multi_add_handle.md
.TH curl_multi_add_handle 3 "2025-08-14" libcurl
.SH NAME
curl_multi_add_handle \- add an easy handle to a multi session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
.fi
.SH DESCRIPTION
Adds the \fIeasy handle\fP to the \fImulti_handle\fP.
While an easy handle is added to a multi stack, you cannot and you must not
use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy
handle from the multi stack again, it is perfectly fine to use it with the
easy interface again.
If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) cache,
it is made to use a DNS cache that is shared between all easy handles within
the multi handle when \fIcurl_multi_add_handle(3)\fP is called.
When an easy interface is added to a multi handle, it is set to use a shared
connection cache owned by the multi handle. Removing and adding new easy
handles does not affect the pool of connections or the ability to do
connection reuse.
If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (as you
should if you are working event\-based with \fIcurl_multi_socket_action(3)\fP
and friends), that callback is called from within this function to ask for an
updated timer so that your main event loop gets the activity on this handle to
get started.
The easy handle remains added to the multi handle until you remove it again
with \fIcurl_multi_remove_handle(3)\fP \- even when a transfer with that
specific easy handle is completed.
You should remove the easy handle from the multi stack before you terminate
first the easy handle and then the multi handle:
1 \- \fIcurl_multi_remove_handle(3)\fP
2 \- \fIcurl_easy_cleanup(3)\fP
3 \- \fIcurl_multi_cleanup(3)\fP
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
/* init a multi stack */
CURLM *multi = curl_multi_init();
/* create two easy handles */
CURL *http_handle = curl_easy_init();
CURL *http_handle2 = curl_easy_init();
/* add individual transfers */
curl_multi_add_handle(multi, http_handle);
curl_multi_add_handle(multi, http_handle2);
}
.fi
.SH AVAILABILITY
Added in curl 7.9.6
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_cleanup (3),
.BR curl_multi_get_handles (3),
.BR curl_multi_init (3),
.BR curl_multi_setopt (3),
.BR curl_multi_socket_action (3)

67
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_assign.3 Normal file
View File

@ -0,0 +1,67 @@
.\" generated by cd2nroff 0.1 from curl_multi_assign.md
.TH curl_multi_assign 3 "2025-08-14" libcurl
.SH NAME
curl_multi_assign \- set data to associate with an internal socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
void *sockptr);
.fi
.SH DESCRIPTION
This function creates an association in the multi handle between the given
socket and a private pointer of the application. This is designed for
\fIcurl_multi_socket_action(3)\fP uses.
When set, the \fIsockptr\fP pointer is passed to all future socket callbacks
for the specific \fIsockfd\fP socket.
If the given \fIsockfd\fP is not already in use by libcurl, this function
returns an error.
libcurl only keeps one single pointer associated with a socket, so calling
this function several times for the same socket makes the last set pointer get
used.
The idea here being that this association (socket to private pointer) is
something that just about every application that uses this API needs and then
libcurl can just as well do it since it already has the necessary
functionality.
It is acceptable to call this function from your multi callback functions.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLM *multi = curl_multi_init();
int private = 123;
curl_socket_t fd = 0; /* file descriptor to associate our data with */
/* make our struct pointer associated with socket fd */
CURLMcode mc = curl_multi_assign(multi, fd, &private);
if(mc)
printf("error: %s\\n", curl_multi_strerror(mc));
}
.fi
.SH TYPICAL USAGE
In a typical application you allocate a struct or at least use some kind of
semi\-dynamic data for each socket that we must wait for action on when using
the \fIcurl_multi_socket_action(3)\fP approach.
When our socket\-callback gets called by libcurl and we get to know about yet
another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out the
particular data so that when we get updates about this same socket again, we
do not have to find the struct associated with this socket by ourselves.
.SH AVAILABILITY
Added in curl 7.15.5
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_setopt (3),
.BR curl_multi_socket_action (3)

59
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_cleanup.3 Normal file
View File

@ -0,0 +1,59 @@
.\" generated by cd2nroff 0.1 from curl_multi_cleanup.md
.TH curl_multi_cleanup 3 "2025-08-14" libcurl
.SH NAME
curl_multi_cleanup \- close down a multi session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_cleanup(CURLM *multi_handle);
.fi
.SH DESCRIPTION
This function is the opposite of \fIcurl_multi_init(3)\fP. Cleans up and removes a
whole multi stack. It does not free or touch any individual easy handles in
any way \- they still need to be closed individually, using the usual
\fIcurl_easy_cleanup(3)\fP way. The order of cleaning up should be:
1 \- \fIcurl_multi_remove_handle(3)\fP before any easy handles are cleaned up
2 \- \fIcurl_easy_cleanup(3)\fP can now be called independently since the easy
handle is no longer connected to the multi handle
3 \- \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are
removed
When this function is called, remaining entries in the connection pool held by
the multi handle are shut down, which might trigger calls to the
\fICURLMOPT_SOCKETFUNCTION(3)\fP callback.
Passing in a NULL pointer in \fImulti_handle\fP makes this function return
CURLM_BAD_HANDLE immediately with no other action.
Any use of the \fBmulti_handle\fP after this function has been called and have
returned, is illegal.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLM *multi = curl_multi_init();
/* when the multi transfer is done ... */
/* remove all easy handles, then: */
curl_multi_cleanup(multi);
}
.fi
.SH AVAILABILITY
Added in curl 7.9.6
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_easy_cleanup (3),
.BR curl_easy_init (3),
.BR curl_multi_get_handles (3),
.BR curl_multi_init (3)

111
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_fdset.3 Normal file
View File

@ -0,0 +1,111 @@
.\" generated by cd2nroff 0.1 from curl_multi_fdset.md
.TH curl_multi_fdset 3 "2025-08-14" libcurl
.SH NAME
curl_multi_fdset \- extract file descriptor information from a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_fdset(CURLM *multi_handle,
fd_set *read_fd_set,
fd_set *write_fd_set,
fd_set *exc_fd_set,
int *max_fd);
.fi
.SH DESCRIPTION
This function extracts file descriptor information from a given multi_handle.
libcurl returns its \fIfd_set\fP sets. The application can use these to
select() on, but be sure to \fIFD_ZERO\fP them before calling this function as
\fIcurl_multi_fdset(3)\fP only adds its own descriptors, it does not zero or
otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should
be called as soon as one of them is ready to be read from or written to.
The \fIread_fd_set\fP argument should point to an object of type \fBfd_set\fP
that on returns specifies the file descriptors to be checked for being ready
to read.
The \fIwrite_fd_set\fP argument should point to an object of type \fBfd_set\fP
that on return specifies the file descriptors to be checked for being ready to
write.
The \fIexc_fd_set\fP argument should point to an object of type \fBfd_set\fP
that on return specifies the file descriptors to be checked for error
conditions.
If no file descriptors are set by libcurl, \fImax_fd\fP contain \-1 when this
function returns. Otherwise it contains the highest descriptor number libcurl
set. When libcurl returns \-1 in \fImax_fd\fP, it is because libcurl currently
does something that is not possible for your application to monitor with a
socket and unfortunately you can then not know exactly when the current action
is completed using select(). You then need to wait a while before you proceed
and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless
\fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100
milliseconds or so, but you may want to test it out in your own particular
conditions to find a suitable value.
When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out
how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no
activity has been seen on the \fBfd_sets\fP after the timeout expires as
otherwise internal retries and timeouts may not work as you would think and
want.
If one of the sockets used by libcurl happens to be larger than what can be
set in an \fBfd_set\fP, which on POSIX systems means that the file descriptor
is larger than \fBFD_SETSIZE\fP, then libcurl tries to not set it. Setting a
too large file descriptor in an \fBfd_set\fP implies an out of bounds write
which can cause crashes, or worse. The effect of NOT storing it might possibly
save you from the crash, but makes your program NOT wait for sockets it should
wait for...
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
fd_set fdread;
fd_set fdwrite;
fd_set fdexcep;
int maxfd;
int rc;
CURLMcode mc;
struct timeval timeout = {1, 0};
CURLM *multi = curl_multi_init();
do {
/* call curl_multi_perform() */
FD_ZERO(&fdread);
FD_ZERO(&fdwrite);
FD_ZERO(&fdexcep);
/* get file descriptors from the transfers */
mc = curl_multi_fdset(multi, &fdread, &fdwrite, &fdexcep, &maxfd);
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi_fdset() failed, code %d.\\n", mc);
break;
}
/* wait for activity on one of the sockets */
rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
} while(!mc);
}
.fi
.SH AVAILABILITY
Added in curl 7.9.6
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_cleanup (3),
.BR curl_multi_init (3),
.BR curl_multi_perform (3),
.BR curl_multi_timeout (3),
.BR curl_multi_wait (3),
.BR curl_multi_waitfds (3),
.BR select (2)

62
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_get_handles.3 Normal file
View File

@ -0,0 +1,62 @@
.\" generated by cd2nroff 0.1 from curl_multi_get_handles.md
.TH curl_multi_get_handles 3 "2025-08-14" libcurl
.SH NAME
curl_multi_get_handles \- return all added easy handles
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURL **curl_multi_get_handles(CURLM *multi_handle);
.fi
.SH DESCRIPTION
Returns an array with pointers to all added easy handles. The end of the list
is marked with a NULL pointer.
Even if there is not a single easy handle added, this still returns an array
but with only a single NULL pointer entry.
The returned array contains all the handles that are present at the time of
the call. As soon as a handle has been removed from or a handle has been added
to the multi handle after the handle array was returned, the two data points
are out of sync.
The order of the easy handles within the array is not guaranteed.
The returned array must be freed with a call to \fIcurl_free(3)\fP after use.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
/* init a multi stack */
CURLM *multi = curl_multi_init();
CURL *curl = curl_easy_init();
if(curl) {
/* add the transfer */
curl_multi_add_handle(multi, curl);
/* extract all added handles */
CURL **list = curl_multi_get_handles(multi);
if(list) {
int i;
/* remove all added handles */
for(i = 0; list[i]; i++) {
curl_multi_remove_handle(multi, list[i]);
}
curl_free(list);
}
}
}
.fi
.SH AVAILABILITY
Added in curl 8.4.0
.SH RETURN VALUE
Returns NULL on failure. Otherwise it returns a pointer to an allocated array.
.SH SEE ALSO
.BR curl_multi_add_handle (3),
.BR curl_multi_cleanup (3),
.BR curl_multi_init (3),
.BR curl_multi_remove_handle (3)

88
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_info_read.3 Normal file
View File

@ -0,0 +1,88 @@
.\" generated by cd2nroff 0.1 from curl_multi_info_read.md
.TH curl_multi_info_read 3 "2025-08-14" libcurl
.SH NAME
curl_multi_info_read \- read multi stack information
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue);
.fi
.SH DESCRIPTION
Ask the multi handle if there are any messages from the individual
transfers. Messages may include information such as an error code from the
transfer or just the fact that a transfer is completed. More details on these
should be written down as well.
Repeated calls to this function returns a new struct each time, until a NULL
is returned as a signal that there is no more to get at this point. The
integer pointed to with \fImsgs_in_queue\fP contains the number of remaining
messages after this function was called.
When you fetch a message using this function, it is removed from the internal
queue so calling this function again does not return the same message
again. It instead returns new messages at each new invoke until the queue is
emptied.
\fBWARNING:\fP The data the returned pointer points to does not survive
calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or
\fIcurl_easy_cleanup(3)\fP.
The \fICURLMsg\fP struct is simple and only contains basic information. If
more involved information is wanted, the particular "easy handle" is present
in that struct and can be used in subsequent regular
\fIcurl_easy_getinfo(3)\fP calls (or similar):
.nf
struct CURLMsg {
CURLMSG msg; /* what this message means */
CURL *easy_handle; /* the handle it concerns */
union {
void *whatever; /* message-specific data */
CURLcode result; /* return code for transfer */
} data;
};
.fi
When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that
is done, and then \fBresult\fP contains the return code for the easy handle
that just completed.
At this point, there are no other \fBmsg\fP types defined.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLM *multi = curl_multi_init();
CURL *curl = curl_easy_init();
if(curl) {
struct CURLMsg *m;
/* call curl_multi_perform or curl_multi_socket_action first, then loop
through and check if there are any transfers that have completed */
do {
int msgq = 0;
m = curl_multi_info_read(multi, &msgq);
if(m && (m->msg == CURLMSG_DONE)) {
CURL *e = m->easy_handle;
/* m->data.result holds the error code for the transfer */
curl_multi_remove_handle(multi, e);
curl_easy_cleanup(e);
}
} while(m);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.9.6
.SH RETURN VALUE
A pointer to a filled\-in struct, or NULL if it failed or ran out of structs.
It also writes the number of messages left in the queue (after this read) in
the integer the second argument points to.
.SH SEE ALSO
.BR curl_multi_cleanup (3),
.BR curl_multi_init (3),
.BR curl_multi_perform (3)

46
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_init.3 Normal file
View File

@ -0,0 +1,46 @@
.\" generated by cd2nroff 0.1 from curl_multi_init.md
.TH curl_multi_init 3 "2025-08-14" libcurl
.SH NAME
curl_multi_init \- create a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLM *curl_multi_init();
.fi
.SH DESCRIPTION
This function returns a pointer to a \fICURLM\fP handle to be used as input to
all the other multi\-functions, sometimes referred to as a multi handle in some
places in the documentation. This init call MUST have a corresponding call to
\fIcurl_multi_cleanup(3)\fP when the operation is complete.
By default, several caches are stored in and held by the multi handle: DNS
cache, connection pool, TLS session ID cache and the TLS CA cert cache. All
transfers using the same multi handle share these caches.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
/* init a multi stack */
CURLM *multi = curl_multi_init();
CURL *curl = curl_easy_init();
CURL *curl2 = curl_easy_init();
/* add individual transfers */
curl_multi_add_handle(multi, curl);
curl_multi_add_handle(multi, curl2);
}
.fi
.SH AVAILABILITY
Added in curl 7.9.6
.SH RETURN VALUE
If this function returns NULL, something went wrong and you cannot use the
other curl functions.
.SH SEE ALSO
.BR curl_easy_init (3),
.BR curl_global_init (3),
.BR curl_multi_add_handle (3),
.BR curl_multi_cleanup (3),
.BR curl_multi_get_handles (3)

93
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_perform.3 Normal file
View File

@ -0,0 +1,93 @@
.\" generated by cd2nroff 0.1 from curl_multi_perform.md
.TH curl_multi_perform 3 "2025-08-14" libcurl
.SH NAME
curl_multi_perform \- run all transfers until it would block
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles);
.fi
.SH DESCRIPTION
This function performs transfers on all the added handles that need attention
in a non\-blocking fashion. The easy handles have previously been added to the
multi handle with \fIcurl_multi_add_handle(3)\fP.
When an application has found out there is data available for the multi_handle
or a timeout has elapsed, the application should call this function to
read/write whatever there is to read or write right now etc.
\fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This
function does not require that there actually is any data available for
reading or that data can be written, it can be called just in case. It stores
the number of handles that still transfer data in the second argument\(aqs
integer\-pointer.
If the amount of \fIrunning_handles\fP is changed from the previous call (or
is less than the amount of easy handles you have added to the multi handle),
you know that there is one or more transfers less "running". You can then call
\fIcurl_multi_info_read(3)\fP to get information about each individual
completed transfer, and that returned info includes CURLcode and more. If an
added handle fails quickly, it may never be counted as a running_handle. You
could use \fIcurl_multi_info_read(3)\fP to track actual status of the added
handles in that case.
When \fIrunning_handles\fP is set to zero (0) on the return of this function,
there is no longer any transfers in progress.
When this function returns error, the state of all transfers are uncertain and
they cannot be continued. \fIcurl_multi_perform(3)\fP should not be called
again on the same multi handle after an error has been returned, unless first
removing all the handles and adding new ones.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
int still_running;
CURLM *multi = curl_multi_init();
CURL *curl = curl_easy_init();
if(curl) {
curl_multi_add_handle(multi, curl);
do {
CURLMcode mc = curl_multi_perform(multi, &still_running);
if(!mc && still_running)
/* wait for activity, timeout or "nothing" */
mc = curl_multi_poll(multi, NULL, 0, 1000, NULL);
if(mc) {
fprintf(stderr, "curl_multi_poll() failed, code %d.\\n", (int)mc);
break;
}
/* if there are still transfers, loop */
} while(still_running);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.9.6
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
This function returns errors regarding the whole multi stack. Problems on
individual transfers may have occurred even when this function returns
\fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure out how individual transfers
did.
.SH TYPICAL USAGE
Most applications use \fIcurl_multi_poll(3)\fP to make libcurl wait for
activity on any of the ongoing transfers. As soon as one or more file
descriptor has activity or the function times out, the application calls
\fIcurl_multi_perform(3)\fP.
.SH SEE ALSO
.BR curl_multi_add_handle (3),
.BR curl_multi_cleanup (3),
.BR curl_multi_fdset (3),
.BR curl_multi_info_read (3),
.BR curl_multi_init (3),
.BR curl_multi_wait (3),
.BR libcurl-errors (3)

124
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_poll.3 Normal file
View File

@ -0,0 +1,124 @@
.\" generated by cd2nroff 0.1 from curl_multi_poll.md
.TH curl_multi_poll 3 "2025-08-14" libcurl
.SH NAME
curl_multi_poll \- poll on all easy handles in a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_poll(CURLM *multi_handle,
struct curl_waitfd extra_fds[],
unsigned int extra_nfds,
int timeout_ms,
int *numfds);
.fi
.SH DESCRIPTION
\fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy
handles contained in the given multi handle set. It blocks until activity is
detected on at least one of the handles or \fItimeout_ms\fP has passed.
Alternatively, if the multi handle has a pending internal timeout that has a
shorter expiry time than \fItimeout_ms\fP, that shorter time is used instead
to make sure timeout accuracy is reasonably kept.
The calling application may pass additional curl_waitfd structures which are
similar to \fIpoll(2)\fP\(aqs \fIpollfd\fP structure to be waited on in the same
call.
On completion, if \fInumfds\fP is non\-NULL, it gets populated with the total
number of file descriptors on which interesting events occurred. This number
can include both libcurl internal descriptors as well as descriptors provided
in \fIextra_fds\fP.
The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to
wake up this function and return faster. This is one of the details
that makes this function different than \fIcurl_multi_wait(3)\fP which cannot
be woken up this way.
If no extra file descriptors are provided and libcurl has no file descriptor
to offer to wait for, this function instead waits during \fItimeout_ms\fP
milliseconds (or shorter if an internal timer indicates so). This is the other
detail that makes this function different than \fIcurl_multi_wait(3)\fP.
This function is encouraged to be used instead of select(3) when using the
multi interface to allow applications to easier circumvent the common problem
with 1024 maximum file descriptors.
.SH curl_waitfd
.nf
struct curl_waitfd {
curl_socket_t fd;
short events;
short revents;
};
.fi
.IP CURL_WAIT_POLLIN
Bit flag to curl_waitfd.events indicating the socket should poll on read
events such as new data received.
.IP CURL_WAIT_POLLPRI
Bit flag to curl_waitfd.events indicating the socket should poll on high
priority read events such as out of band data.
.IP CURL_WAIT_POLLOUT
Bit flag to curl_waitfd.events indicating the socket should poll on write
events such as the socket being clear to write without blocking.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
extern void handle_fd(int);
int main(void)
{
CURL *easy_handle;
CURLM *multi_handle;
int still_running = 0;
int myfd = 2; /* this is our own file descriptor */
multi_handle = curl_multi_init();
easy_handle = curl_easy_init();
/* add the individual easy handle */
curl_multi_add_handle(multi_handle, easy_handle);
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi_handle, &still_running);
if(mc == CURLM_OK) {
struct curl_waitfd myown;
myown.fd = myfd;
myown.events = CURL_WAIT_POLLIN; /* wait for input */
myown.revents = 0; /* clear it */
/* wait for activity on curl's descriptors or on our own,
or timeout */
mc = curl_multi_poll(multi_handle, &myown, 1, 1000, &numfds);
if(myown.revents) {
/* did our descriptor receive an event? */
handle_fd(myfd);
}
}
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi failed, code %d.\\n", mc);
break;
}
} while(still_running);
curl_multi_remove_handle(multi_handle, easy_handle);
}
.fi
.SH AVAILABILITY
Added in curl 7.66.0
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_fdset (3),
.BR curl_multi_perform (3),
.BR curl_multi_wait (3),
.BR curl_multi_wakeup (3)

61
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_remove_handle.3 Normal file
View File

@ -0,0 +1,61 @@
.\" generated by cd2nroff 0.1 from curl_multi_remove_handle.md
.TH curl_multi_remove_handle 3 "2025-08-14" libcurl
.SH NAME
curl_multi_remove_handle \- remove an easy handle from a multi session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle);
.fi
.SH DESCRIPTION
Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This makes the
specified easy handle be removed from this multi handle\(aqs control.
When the easy handle has been removed from a multi stack, it is again
perfectly legal to invoke \fIcurl_easy_perform(3)\fP on this easy handle.
Removing an easy handle while being in use is perfectly legal and effectively
halts the transfer in progress involving that easy handle. All other easy
handles and transfers remain unaffected.
It is fine to remove a handle at any time during a transfer, just not from
within any libcurl callback function.
Removing an easy handle from the multi handle before the corresponding
transfer is complete might cause libcurl to close the connection \- if the
state of it and the internal protocol handler deem it necessary. Otherwise
libcurl keeps the connection alive in the connection pool associated with the
multi handle, ready to get reused for a future transfer using this multi
handle.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLM *multi = curl_multi_init();
int queued = 0;
/* when an easy handle has completed, remove it */
CURLMsg *msg = curl_multi_info_read(multi, &queued);
if(msg) {
if(msg->msg == CURLMSG_DONE) {
/* a transfer ended */
fprintf(stderr, "Transfer completed\\n");
curl_multi_remove_handle(multi, msg->easy_handle);
}
}
}
.fi
.SH AVAILABILITY
Added in curl 7.9.6
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_add_handle (3),
.BR curl_multi_cleanup (3),
.BR curl_multi_init (3)

83
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_setopt.3 Normal file
View File

@ -0,0 +1,83 @@
.\" generated by cd2nroff 0.1 from curl_multi_setopt.md
.TH curl_multi_setopt 3 "2025-08-14" libcurl
.SH NAME
curl_multi_setopt \- set options for a curl multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *multi, CURLMoption option, parameter);
.fi
.SH DESCRIPTION
\fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to behave. By
using the appropriate options to \fIcurl_multi_setopt(3)\fP, you can change
libcurl\(aqs behavior when using that multi handle. All options are set with the
\fIoption\fP followed by the \fIparameter\fP. That parameter can be a \fBlong\fP, a
\fBfunction pointer\fP, an \fBobject pointer\fP or a \fBcurl_off_t\fP type,
depending on what the specific option expects. Read this manual carefully as
bad input values may cause libcurl to behave badly. You can only set one
option in each function call.
.SH OPTIONS
.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE
\fBdeprecated\fP See \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP
.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE
\fBdeprecated\fP See \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP
.IP CURLMOPT_MAXCONNECTS
Size of connection cache. See \fICURLMOPT_MAXCONNECTS(3)\fP
.IP CURLMOPT_MAX_CONCURRENT_STREAMS
Max concurrent streams for http2. See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP
.IP CURLMOPT_MAX_HOST_CONNECTIONS
Max number of connections to a single host. See
\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP
.IP CURLMOPT_MAX_PIPELINE_LENGTH
\fBdeprecated\fP. See \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP
.IP CURLMOPT_MAX_TOTAL_CONNECTIONS
Max simultaneously open connections. See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP
.IP CURLMOPT_PIPELINING
Enable HTTP multiplexing. See \fICURLMOPT_PIPELINING(3)\fP
.IP CURLMOPT_PIPELINING_SERVER_BL
\fBdeprecated\fP. See \fICURLMOPT_PIPELINING_SERVER_BL(3)\fP
.IP CURLMOPT_PIPELINING_SITE_BL
\fBdeprecated\fP. See \fICURLMOPT_PIPELINING_SITE_BL(3)\fP
.IP CURLMOPT_PUSHDATA
Pointer to pass to push callback. See \fICURLMOPT_PUSHDATA(3)\fP
.IP CURLMOPT_PUSHFUNCTION
Callback that approves or denies server pushes. See \fICURLMOPT_PUSHFUNCTION(3)\fP
.IP CURLMOPT_SOCKETDATA
Custom pointer passed to the socket callback. See \fICURLMOPT_SOCKETDATA(3)\fP
.IP CURLMOPT_SOCKETFUNCTION
Callback informed about what to wait for. See \fICURLMOPT_SOCKETFUNCTION(3)\fP
.IP CURLMOPT_TIMERDATA
Custom pointer to pass to timer callback. See \fICURLMOPT_TIMERDATA(3)\fP
.IP CURLMOPT_TIMERFUNCTION
Callback to receive timeout values. See \fICURLMOPT_TIMERFUNCTION(3)\fP
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
#define MAX_PARALLEL 45
int main(void)
{
CURLM *multi = curl_multi_init();
/* Limit the amount of simultaneous connections curl should allow: */
curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL);
}
.fi
.SH AVAILABILITY
Added in curl 7.15.4
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that
this version of libcurl does not know of.
.SH SEE ALSO
.BR curl_multi_cleanup (3),
.BR curl_multi_info_read (3),
.BR curl_multi_init (3),
.BR curl_multi_socket (3)

69
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_socket.3 Normal file
View File

@ -0,0 +1,69 @@
.\" generated by cd2nroff 0.1 from curl_multi_socket.md
.TH curl_multi_socket 3 "2025-08-14" libcurl
.SH NAME
curl_multi_socket \- read/write available data
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd,
int *running_handles);
.fi
.SH DESCRIPTION
This function is deprecated. Use \fIcurl_multi_socket_action(3)\fP instead with
\fBev_bitmask\fP set to 0.
At return, the integer \fBrunning_handles\fP points to contains the number of
still running easy handles within the multi handle. When this number reaches
zero, all transfers are complete/done. Note that when you call
\fIcurl_multi_socket(3)\fP on a specific socket and the counter decreases by one, it
DOES NOT necessarily mean that this exact socket/transfer is the one that
completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy handle that
completed.
The \fIcurl_multi_socket(3)\fP functions inform the application about updates in the
socket (file descriptor) status by doing none, one, or multiple calls to the
socket callback function set with the \fICURLMOPT_SOCKETFUNCTION(3)\fP option to
\fIcurl_multi_setopt(3)\fP. They update the status with changes since the previous
time the callback was called.
Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option with
\fIcurl_multi_setopt(3)\fP. Your application then gets called with information on
how long to wait for socket actions at most before doing the timeout action:
call the \fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set
to CURL_SOCKET_TIMEOUT. You can also use the \fIcurl_multi_timeout(3)\fP function to
poll the value at any given time, but for an event\-based system using the
callback is far better than relying on polling the timeout value.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
/* the event-library gets told when there activity on the socket 'fd',
which we translate to a call to curl_multi_socket_action() */
int running;
int rc;
int fd = 2;
CURLM *multi = curl_multi_init();
rc = curl_multi_socket(multi, fd, &running);
}
.fi
.SH DEPRECATED
\fIcurl_multi_socket(3)\fP is deprecated, use \fIcurl_multi_socket_action(3)\fP instead.
.SH AVAILABILITY
Added in curl 7.15.4
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
The return code is for the whole multi stack. Problems still might have
occurred on individual transfers even when one of these functions return OK.
.SH SEE ALSO
.BR curl_multi_cleanup (3),
.BR curl_multi_fdset (3),
.BR curl_multi_info_read (3),
.BR curl_multi_init (3),
.BR the hiperfifo.c example

107
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_socket_action.3 Normal file
View File

@ -0,0 +1,107 @@
.\" generated by cd2nroff 0.1 from curl_multi_socket_action.md
.TH curl_multi_socket_action 3 "2025-08-14" libcurl
.SH NAME
curl_multi_socket_action \- read/write available data given an action
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_socket_action(CURLM *multi_handle,
curl_socket_t sockfd,
int ev_bitmask,
int *running_handles);
.fi
.SH DESCRIPTION
When the application has detected action on a socket handled by libcurl, it
should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument
set to the socket with the action. When the events on a socket are known, they
can be passed as an events bitmask \fBev_bitmask\fP by first setting
\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of
events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
libcurl tests the descriptor internally. It is also permissible to pass
CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
whole process or when a timeout occurs.
At return, \fBrunning_handles\fP points to the number of running easy handles
within the multi handle. When this number reaches zero, all transfers are
complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific
socket and the counter decreases by one, it DOES NOT necessarily mean that
this exact socket/transfer is the one that completed. Use
\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed.
The \fIcurl_multi_socket_action(3)\fP function informs the application about
updates in the socket (file descriptor) status by doing none, one, or multiple
calls to the socket callback function set with the
\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
update the status with changes since the previous time the callback was
called.
Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
with \fIcurl_multi_setopt(3)\fP. Your application then gets called with
information on how long to wait for socket actions at most before doing the
timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the
\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
for an event\-based system using the callback is far better than relying on
polling the timeout value.
When this function returns error, the state of all transfers are uncertain and
they cannot be continued. \fIcurl_multi_socket_action(3)\fP should not be
called again on the same multi handle after an error has been returned, unless
first removing all the handles and adding new ones.
.SH TYPICAL USAGE
1. Create a multi handle
2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP
3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to
know what timeout value to use when waiting for socket activities.
4. Add easy handles with curl_multi_add_handle()
5. Provide some means to manage the sockets libcurl is using, so you can check
them for activity. This can be done through your application code, or by way
of an external library such as libevent or glib.
6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)
to kickstart everything. To get one or more callbacks called.
7. Wait for activity on any of libcurl\(aqs sockets, use the timeout value your
callback has been told.
8, When activity is detected, call curl_multi_socket_action() for the
socket(s) that got action. If no activity is detected and the timeout expires,
call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
/* the event-library gets told when there activity on the socket 'fd',
which we translate to a call to curl_multi_socket_action() */
int running = 0;
int fd = 3; /* the descriptor that had action */
int bitmask = 2; /* what activity that happened */
CURLM *multi = curl_multi_init();
CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running);
if(mc)
printf("error: %s\\n", curl_multi_strerror(mc));
}
.fi
.SH AVAILABILITY
Added in curl 7.15.4
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_cleanup (3),
.BR curl_multi_fdset (3),
.BR curl_multi_info_read (3),
.BR curl_multi_init (3),
.BR the hiperfifo.c example

51
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_socket_all.3 Normal file
View File

@ -0,0 +1,51 @@
.\" generated by cd2nroff 0.1 from curl_multi_socket_all.md
.TH curl_multi_socket_all 3 "2025-08-14" libcurl
.SH NAME
curl_multi_socket_all \- reads/writes available data for all easy handles
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_socket_all(CURLM *multi_handle,
int *running_handles);
.fi
.SH DESCRIPTION
This function is deprecated for performance reasons but there are no plans to
remove it from the API. Use \fIcurl_multi_socket_action(3)\fP instead.
At return, the integer \fBrunning_handles\fP points to contains the number of
still running easy handles within the multi handle. When this number reaches
zero, all transfers are complete/done.
Force libcurl to (re\-)check all its internal sockets and transfers instead of
just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there should
not be any reason to use this function.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
int running;
int rc;
CURLM *multi = curl_multi_init();
rc = curl_multi_socket_all(multi, &running);
}
.fi
.SH AVAILABILITY
Added in curl 7.15.4
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
The return code is for the whole multi stack. Problems still might have
occurred on individual transfers even when one of these functions return OK.
.SH SEE ALSO
.BR curl_multi_cleanup (3),
.BR curl_multi_fdset (3),
.BR curl_multi_info_read (3),
.BR curl_multi_init (3),
.BR the hiperfifo.c example

36
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_strerror.3 Normal file
View File

@ -0,0 +1,36 @@
.\" generated by cd2nroff 0.1 from curl_multi_strerror.md
.TH curl_multi_strerror 3 "2025-08-14" libcurl
.SH NAME
curl_multi_strerror \- return string describing error code
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const char *curl_multi_strerror(CURLMcode errornum);
.fi
.SH DESCRIPTION
This function returns a string describing the \fICURLMcode\fP error code
passed in the argument \fIerrornum\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
int still_running;
CURLM *multi = curl_multi_init();
CURLMcode mc = curl_multi_perform(multi, &still_running);
if(mc)
printf("error: %s\\n", curl_multi_strerror(mc));
}
.fi
.SH AVAILABILITY
Added in curl 7.12.0
.SH RETURN VALUE
A pointer to a null\-terminated string.
.SH SEE ALSO
.BR curl_easy_strerror (3),
.BR curl_share_strerror (3),
.BR curl_url_strerror (3),
.BR libcurl-errors (3)

75
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_timeout.3 Normal file
View File

@ -0,0 +1,75 @@
.\" generated by cd2nroff 0.1 from curl_multi_timeout.md
.TH curl_multi_timeout 3 "2025-08-14" libcurl
.SH NAME
curl_multi_timeout \- how long to wait for action before proceeding
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout);
.fi
.SH DESCRIPTION
An application using the libcurl multi interface should call
\fIcurl_multi_timeout(3)\fP to figure out how long it should wait for socket
actions \- at most \- before proceeding.
Proceeding means either doing the socket\-style timeout action: call the
\fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set
to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you are using
the simpler and older multi interface approach.
The timeout value returned in the long \fBtimeout\fP points to, is in number
of milliseconds at this moment. If 0, it means you should proceed immediately
without waiting for anything. If it returns \-1, there is no timeout at all set.
An application that uses the \fImulti_socket\fP API should not use this function.
It should instead use the \fICURLMOPT_TIMERFUNCTION(3)\fP option for proper and
desired behavior.
Note: if libcurl returns a \-1 timeout here, it just means that libcurl
currently has no stored timeout value. You must not wait too long (more than a
few seconds perhaps) before you call \fIcurl_multi_perform(3)\fP again.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
struct timeval timeout;
long timeo;
fd_set fdread;
fd_set fdwrite;
fd_set fdexcep;
int maxfd = 2;
CURLM *multi = curl_multi_init();
curl_multi_timeout(multi, &timeo);
if(timeo < 0)
/* no set timeout, use a default */
timeo = 980;
timeout.tv_sec = timeo / 1000;
timeout.tv_usec = (timeo % 1000) * 1000;
/* wait for activities no longer than the set timeout */
select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
}
.fi
.SH TYPICAL USAGE
Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. Figure
out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP.
When there is activity or timeout, call \fIcurl_multi_perform(3)\fP and then
loop \- until all transfers are complete.
.SH AVAILABILITY
Added in curl 7.15.4
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_fdset (3),
.BR curl_multi_info_read (3),
.BR curl_multi_setopt (3),
.BR curl_multi_socket (3)

102
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_wait.3 Normal file
View File

@ -0,0 +1,102 @@
.\" generated by cd2nroff 0.1 from curl_multi_wait.md
.TH curl_multi_wait 3 "2025-08-14" libcurl
.SH NAME
curl_multi_wait \- poll on all easy handles in a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_wait(CURLM *multi_handle,
struct curl_waitfd extra_fds[],
unsigned int extra_nfds,
int timeout_ms,
int *numfds);
.fi
.SH DESCRIPTION
\fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy
handles contained in the given multi handle set. It blocks until activity is
detected on at least one of the handles or \fItimeout_ms\fP has passed.
Alternatively, if the multi handle has a pending internal timeout that has a
shorter expiry time than \fItimeout_ms\fP, that shorter time is being used
instead to make sure timeout accuracy is reasonably kept.
The calling application may pass additional \fIcurl_waitfd\fP structures which
are similar to \fIpoll(2)\fP\(aqs \fIpollfd\fP structure to be waited on in the
same call.
On completion, if \fInumfds\fP is non\-NULL, it gets populated with the total
number of file descriptors on which interesting events occurred. This number
can include both libcurl internal descriptors as well as descriptors provided
in \fIextra_fds\fP.
If no extra file descriptors are provided and libcurl has no file descriptor
to offer to wait for, this function returns immediately. (Consider using
\fIcurl_multi_poll(3)\fP to avoid this behavior.)
This function is encouraged to be used instead of select(3) when using the
multi interface to allow applications to easier circumvent the common problem
with 1024 maximum file descriptors.
.SH curl_waitfd
.nf
struct curl_waitfd {
curl_socket_t fd;
short events;
short revents;
};
.fi
.IP CURL_WAIT_POLLIN
Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on read
events such as new data received.
.IP CURL_WAIT_POLLPRI
Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on high
priority read events such as out of band data.
.IP CURL_WAIT_POLLOUT
Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on
write events such as the socket being clear to write without blocking.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *easy;
CURLM *multi = curl_multi_init();
int still_running;
easy = curl_easy_init();
/* add the individual easy handle */
curl_multi_add_handle(multi, easy);
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi, &still_running);
if(mc == CURLM_OK) {
/* wait for activity, timeout or "nothing" */
mc = curl_multi_wait(multi, NULL, 0, 1000, &numfds);
}
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi failed, code %d.\\n", mc);
break;
}
} while(still_running);
curl_multi_remove_handle(multi, easy);
}
.fi
.SH AVAILABILITY
Added in curl 7.28.0
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_fdset (3),
.BR curl_multi_perform (3),
.BR curl_multi_poll (3)

94
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_waitfds.3 Normal file
View File

@ -0,0 +1,94 @@
.\" generated by cd2nroff 0.1 from curl_multi_waitfds.md
.TH curl_multi_waitfds 3 "2025-08-14" libcurl
.SH NAME
curl_multi_waitfds \- extract file descriptor information from a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
#include <stdlib.h>
CURLMcode curl_multi_waitfds(CURLM *multi,
struct curl_waitfd *ufds,
unsigned int size,
unsigned int *fd_count);
.fi
.SH DESCRIPTION
This function extracts \fIcurl_waitfd\fP structures which are similar to
\fIpoll(2)\fP\(aqs \fIpollfd\fP structure from a given multi_handle.
These structures can be used for polling on multi_handle file descriptors in a
fashion similar to \fIcurl_multi_poll(3)\fP. The \fIcurl_multi_perform(3)\fP
function should be called as soon as one of them is ready to be read from or
written to.
libcurl fills provided \fIufds\fP array up to the \fIsize\fP.
If a number of descriptors used by the multi_handle is greater than the
\fIsize\fP parameter then libcurl returns CURLM_OUT_OF_MEMORY error.
If the \fIfd_count\fP argument is not a null pointer, it points to a variable
that on return specifies the number of descriptors used by the multi_handle to
be checked for being ready to read or write.
The client code can pass \fIsize\fP equal to zero just to get the number of the
descriptors and allocate appropriate storage for them to be used in a
subsequent function call. In this case, \fIfd_count\fP receives a number greater
than or equal to the number of descriptors.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
#include <stdlib.h>
int main(void)
{
CURLMcode mc;
struct curl_waitfd *ufds;
CURLM *multi = curl_multi_init();
do {
/* call curl_multi_perform() */
/* get the count of file descriptors from the transfers */
unsigned int fd_count = 0;
mc = curl_multi_waitfds(multi, NULL, 0, &fd_count);
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi_waitfds() failed, code %d.\\n", mc);
break;
}
if(!fd_count)
continue; /* no descriptors yet */
/* allocate storage for our descriptors */
ufds = malloc(fd_count * sizeof(struct curl_waitfd));
/* get wait descriptors from the transfers and put them into array. */
mc = curl_multi_waitfds(multi, ufds, fd_count, &fd_count);
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi_waitfds() failed, code %d.\\n", mc);
free(ufds);
break;
}
/* Do polling on descriptors in ufds */
free(ufds);
} while(!mc);
}
.fi
.SH AVAILABILITY
Added in curl 8.8.0
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_fdset (3),
.BR curl_multi_perform (3),
.BR curl_multi_poll (3),
.BR curl_multi_wait (3)

81
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_multi_wakeup.3 Normal file
View File

@ -0,0 +1,81 @@
.\" generated by cd2nroff 0.1 from curl_multi_wakeup.md
.TH curl_multi_wakeup 3 "2025-08-14" libcurl
.SH NAME
curl_multi_wakeup \- wake up a sleeping curl_multi_poll call
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_wakeup(CURLM *multi_handle);
.fi
.SH DESCRIPTION
This function can be called from any thread and it wakes up a sleeping
\fIcurl_multi_poll(3)\fP call that is currently (or is about to be) waiting
for activity or a timeout.
If the function is called when there is no \fIcurl_multi_poll(3)\fP call, it
causes the next call to return immediately.
Calling this function only guarantees to wake up the current (or the next if
there is no current) \fIcurl_multi_poll(3)\fP call, which means it is possible
that multiple calls to this function wake up the same waiting operation.
This function has no effect on \fIcurl_multi_wait(3)\fP calls.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
extern int time_to_die(void);
extern int set_something_to_signal_thread_1_to_exit(void);
extern int decide_to_stop_thread1();
int main(void)
{
CURL *easy;
CURLM *multi = curl_multi_init();
int still_running;
easy = curl_easy_init();
/* add the individual easy handle */
curl_multi_add_handle(multi, easy);
/* this is thread 1 */
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi, &still_running);
if(mc == CURLM_OK) {
/* wait for activity, timeout or wakeup */
mc = curl_multi_poll(multi, NULL, 0, 10000, &numfds);
}
if(time_to_die())
return 1;
} while(still_running);
curl_multi_remove_handle(multi, easy);
/* this is thread 2 */
if(decide_to_stop_thread1()) {
set_something_to_signal_thread_1_to_exit();
curl_multi_wakeup(multi);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.68.0
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.
CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_poll (3),
.BR curl_multi_wait (3)

67
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_pushheader_byname.3 Normal file
View File

@ -0,0 +1,67 @@
.\" generated by cd2nroff 0.1 from curl_pushheader_byname.md
.TH curl_pushheader_byname 3 "2025-08-14" libcurl
.SH NAME
curl_pushheader_byname \- get a push header by name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name);
.fi
.SH DESCRIPTION
This is a function that is only functional within a
\fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it
elsewhere and it has no function then.
It returns the value for the given header field name (or NULL) for the
incoming server push request. This is a shortcut so that the application does
not have to loop through all headers to find the one it is interested in. The
data this function points to is freed when this callback returns. If more than
one header field use the same name, this returns only the first one.
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
#include <string.h> /* for strncmp */
static int push_cb(CURL *parent,
CURL *easy,
size_t num_headers,
struct curl_pushheaders *headers,
void *clientp)
{
char *headp;
int *transfers = (int *)clientp;
FILE *out;
headp = curl_pushheader_byname(headers, ":path");
if(headp && !strncmp(headp, "/push-", 6)) {
fprintf(stderr, "The PATH is %s\\n", headp);
/* save the push here */
out = fopen("pushed-stream", "wb");
/* write to this file */
curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
(*transfers)++; /* one more */
return CURL_PUSH_OK;
}
return CURL_PUSH_DENY;
}
int main(void)
{
int counter;
CURLM *multi = curl_multi_init();
curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb);
curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
}
.fi
.SH AVAILABILITY
Added in curl 7.44.0
.SH RETURN VALUE
Returns a pointer to the header field content or NULL.
.SH SEE ALSO
.BR CURLMOPT_PUSHFUNCTION (3),
.BR curl_pushheader_bynum (3)

54
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_pushheader_bynum.3 Normal file
View File

@ -0,0 +1,54 @@
.\" generated by cd2nroff 0.1 from curl_pushheader_bynum.md
.TH curl_pushheader_bynum 3 "2025-08-14" libcurl
.SH NAME
curl_pushheader_bynum \- get a push header by index
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num);
.fi
.SH DESCRIPTION
This is a function that is only functional within a
\fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it
elsewhere and it has no function then.
It returns the value for the header field at the given index \fBnum\fP, for
the incoming server push request or NULL. The data pointed to is freed by
libcurl when this callback returns. The returned pointer points to a
\&"name:value" string that gets freed when this callback returns.
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
/* output all the incoming push request headers */
static int push_cb(CURL *parent,
CURL *easy,
size_t num_headers,
struct curl_pushheaders *headers,
void *clientp)
{
int i = 0;
char *field;
do {
field = curl_pushheader_bynum(headers, i);
if(field)
fprintf(stderr, "Push header: %s\\n", field);
i++;
} while(field);
return CURL_PUSH_OK; /* permission granted */
}
int main(void)
{
CURLM *multi = curl_multi_init();
curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb);
}
.fi
.SH AVAILABILITY
Added in curl 7.44.0
.SH RETURN VALUE
Returns a pointer to the header field content or NULL.
.SH SEE ALSO
.BR CURLMOPT_PUSHFUNCTION (3),
.BR curl_pushheader_byname (3)

42
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_share_cleanup.3 Normal file
View File

@ -0,0 +1,42 @@
.\" generated by cd2nroff 0.1 from curl_share_cleanup.md
.TH curl_share_cleanup 3 "2025-08-14" libcurl
.SH NAME
curl_share_cleanup \- close a shared object
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSHcode curl_share_cleanup(CURLSH *share_handle);
.fi
.SH DESCRIPTION
This function deletes a shared object. The share handle cannot be used anymore
when this function has been called.
Passing in a NULL pointer in \fIshare_handle\fP makes this function return
immediately with no action.
Any use of the \fBshare_handle\fP after this function has been called and have
returned, is illegal.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
/* use the share, then ... */
curl_share_cleanup(share);
}
.fi
.SH AVAILABILITY
Added in curl 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non\-zero means an
error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl\-errors(3)\fP man
page for the full list with descriptions. If an error occurs, then the share
object is not deleted.
.SH SEE ALSO
.BR curl_share_init (3),
.BR curl_share_setopt (3)

41
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_share_init.3 Normal file
View File

@ -0,0 +1,41 @@
.\" generated by cd2nroff 0.1 from curl_share_init.md
.TH curl_share_init 3 "2025-08-14" libcurl
.SH NAME
curl_share_init \- create a share object
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSH *curl_share_init();
.fi
.SH DESCRIPTION
This function returns a pointer to a \fICURLSH\fP handle to be used as input
to all the other share\-functions, sometimes referred to as a share handle in
some places in the documentation. This init call MUST have a corresponding
call to \fIcurl_share_cleanup(3)\fP when all operations using the share are
complete.
This \fIshare handle\fP is what you pass to curl using the
\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that
specific curl handle use the data in this share.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
}
.fi
.SH AVAILABILITY
Added in curl 7.10
.SH RETURN VALUE
If this function returns NULL, something went wrong (out of memory, etc.)
and therefore the share object was not created.
.SH SEE ALSO
.BR curl_share_cleanup (3),
.BR curl_share_setopt (3)

45
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_share_setopt.3 Normal file
View File

@ -0,0 +1,45 @@
.\" generated by cd2nroff 0.1 from curl_share_setopt.md
.TH curl_share_setopt 3 "2025-08-14" libcurl
.SH NAME
curl_share_setopt \- set options for a shared object
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter);
.fi
.SH DESCRIPTION
Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP.
.SH OPTIONS
.IP CURLSHOPT_LOCKFUNC
See \fICURLSHOPT_LOCKFUNC(3)\fP.
.IP CURLSHOPT_UNLOCKFUNC
See \fICURLSHOPT_UNLOCKFUNC(3)\fP.
.IP CURLSHOPT_SHARE
See \fICURLSHOPT_SHARE(3)\fP.
.IP CURLSHOPT_UNSHARE
See \fICURLSHOPT_UNSHARE(3)\fP.
.IP CURLSHOPT_USERDATA
See \fICURLSHOPT_USERDATA(3)\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
}
.fi
.SH AVAILABILITY
Added in curl 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non\-zero means an
error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl\-errors(3)\fP man
page for the full list with descriptions.
.SH SEE ALSO
.BR curl_share_cleanup (3),
.BR curl_share_init (3)

35
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_share_strerror.3 Normal file
View File

@ -0,0 +1,35 @@
.\" generated by cd2nroff 0.1 from curl_share_strerror.md
.TH curl_share_strerror 3 "2025-08-14" libcurl
.SH NAME
curl_share_strerror \- return string describing error code
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const char *curl_share_strerror(CURLSHcode errornum);
.fi
.SH DESCRIPTION
The \fIcurl_share_strerror(3)\fP function returns a string describing the
\fICURLSHcode\fP error code passed in the argument \fIerrornum\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLSHcode sh;
CURLSH *share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
}
.fi
.SH AVAILABILITY
Added in curl 7.12.0
.SH RETURN VALUE
A pointer to a null\-terminated string.
.SH SEE ALSO
.BR curl_easy_strerror (3),
.BR curl_multi_strerror (3),
.BR curl_url_strerror (3),
.BR libcurl-errors (3)

60
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_slist_append.3 Normal file
View File

@ -0,0 +1,60 @@
.\" generated by cd2nroff 0.1 from curl_slist_append.md
.TH curl_slist_append 3 "2025-08-14" libcurl
.SH NAME
curl_slist_append \- add a string to an slist
.SH SYNOPSIS
.nf
#include <curl/curl.h>
struct curl_slist *curl_slist_append(struct curl_slist *list,
const char *string);
.fi
.SH DESCRIPTION
\fIcurl_slist_append(3)\fP appends a string to a linked list of strings. The
existing \fBlist\fP should be passed as the first argument and the new list is
returned from this function. Pass in NULL in the \fBlist\fP argument to create
a new list. The specified \fBstring\fP has been appended when this function
returns. \fIcurl_slist_append(3)\fP copies the string.
The list should be freed again (after usage) with
\fIcurl_slist_free_all(3)\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *handle = curl_easy_init();
struct curl_slist *slist = NULL;
struct curl_slist *temp = NULL;
slist = curl_slist_append(slist, "pragma:");
if(!slist)
return -1;
temp = curl_slist_append(slist, "Accept:");
if(!temp) {
curl_slist_free_all(slist);
return -1;
}
slist = temp;
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
curl_easy_perform(handle);
curl_slist_free_all(slist); /* free the list again */
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
A null pointer is returned if anything went wrong, otherwise the new list
pointer is returned. To avoid overwriting an existing non\-empty list on
failure, the new list should be returned to a temporary variable which can
be tested for NULL before updating the original list pointer.
.SH SEE ALSO
.BR curl_slist_free_all (3)

46
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_slist_free_all.3 Normal file
View File

@ -0,0 +1,46 @@
.\" generated by cd2nroff 0.1 from curl_slist_free_all.md
.TH curl_slist_free_all 3 "2025-08-14" libcurl
.SH NAME
curl_slist_free_all \- free an entire curl_slist list
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_slist_free_all(struct curl_slist *list);
.fi
.SH DESCRIPTION
curl_slist_free_all() removes all traces of a previously built curl_slist
linked list.
Passing in a NULL pointer in \fIlist\fP makes this function return immediately
with no action.
Any use of the \fBlist\fP after this function has been called and have returned,
is illegal.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *handle = curl_easy_init();
struct curl_slist *slist = NULL;
slist = curl_slist_append(slist, "X-libcurl: coolness");
if(!slist)
return -1;
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
curl_easy_perform(handle);
curl_slist_free_all(slist); /* free the list again */
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
Nothing.
.SH SEE ALSO
.BR curl_slist_append (3)

41
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_strequal.3 Normal file
View File

@ -0,0 +1,41 @@
.\" generated by cd2nroff 0.1 from curl_strequal.md
.TH curl_strequal 3 "2025-08-14" libcurl
.SH NAME
curl_strequal \- compare two strings ignoring case
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int curl_strequal(const char *str1, const char *str2);
.fi
.SH DESCRIPTION
The \fIcurl_strequal(3)\fP function compares the two strings \fIstr1\fP and \fIstr2\fP,
ignoring the case of the characters. It returns a non\-zero (TRUE) integer if
the strings are identical.
This function uses plain ASCII based comparisons completely disregarding the
locale \- contrary to how \fBstrcasecmp\fP and other system case insensitive
string comparisons usually work.
This function is provided by libcurl to enable applications to compare strings
in a truly portable manner. There are no standard portable case insensitive
string comparison functions. This function works on all platforms.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(int argc, char **argv)
{
const char *name = "compare";
if(curl_strequal(name, argv[1]))
printf("Name and input matches\\n");
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
Non\-zero if the strings are identical. Zero if they are not.
.SH SEE ALSO
.BR curl_strnequal (3),
.BR strcasecmp (3),
.BR strcmp (3)

44
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_strnequal.3 Normal file
View File

@ -0,0 +1,44 @@
.\" generated by cd2nroff 0.1 from curl_strnequal.md
.TH curl_strnequal 3 "2025-08-14" libcurl
.SH NAME
curl_strnequal \- compare two strings ignoring case
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int curl_strnequal(const char *str1, const char *str2, size_t length);
.fi
.SH DESCRIPTION
The \fIcurl_strnequal(3)\fP function compares the two strings \fIstr1\fP and \fIstr2\fP,
ignoring the case of the characters. It returns a non\-zero (TRUE) integer if
the strings are identical.
This function compares no more than the first \fIlength\fP bytes of \fIstr1\fP and
\fIstr2\fP.
This function uses plain ASCII based comparisons completely disregarding the
locale \- contrary to how \fBstrcasecmp\fP and other system case insensitive
string comparisons usually work.
This function is provided by libcurl to enable applications to compare strings
in a truly portable manner. There are no standard portable case insensitive
string comparison functions. This function works on all platforms.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(int argc, char **argv)
{
const char *name = "compare";
if(curl_strnequal(name, argv[1], 5))
printf("Name and input matches in the 5 first bytes\\n");
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
Non\-zero if the strings are identical. Zero if they are not.
.SH SEE ALSO
.BR curl_strequal (3),
.BR strcasecmp (3),
.BR strcmp (3)

52
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_unescape.3 Normal file
View File

@ -0,0 +1,52 @@
.\" generated by cd2nroff 0.1 from curl_unescape.md
.TH curl_unescape 3 "2025-08-14" libcurl
.SH NAME
curl_unescape \- URL decode a string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_unescape(const char *input, int length);
.fi
.SH DESCRIPTION
Deprecated. Use \fIcurl_easy_unescape(3)\fP instead.
This function converts the URL encoded string \fBinput\fP to a "plain string"
and return that as a new allocated string. All input characters that are URL
encoded (%XX where XX is a two\-digit hexadecimal number) are converted to
their plain text versions.
If the \fBlength\fP argument is set to 0, \fIcurl_unescape(3)\fP calls
strlen() on \fBinput\fP to find out the size.
You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
char *decoded = curl_unescape("%63%75%72%6c", 12);
if(decoded) {
/* do not assume printf() works on the decoded data */
printf("Decoded: ");
/* ... */
curl_free(decoded);
}
}
}
.fi
.SH DEPRECATED
Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function might
be removed in a future release.
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
A pointer to a null\-terminated string or NULL if it failed.
.SH SEE ALSO
.BR RFC 2396,
.BR curl_easy_escape (3),
.BR curl_easy_unescape (3),
.BR curl_free (3)

49
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_url.3 Normal file
View File

@ -0,0 +1,49 @@
.\" generated by cd2nroff 0.1 from curl_url.md
.TH curl_url 3 "2025-08-14" libcurl
.SH NAME
curl_url \- create a URL handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLU *curl_url();
.fi
.SH DESCRIPTION
This function allocates a URL object and returns a \fICURLU\fP handle for it,
to be used as input to all other URL API functions.
This is a handle to a URL object that holds or can hold URL components for a
single URL. When the object is first created, there is of course no components
stored. They are then set in the object with the \fIcurl_url_set(3)\fP
function.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
if(!rc) {
printf("the scheme is %s\\n", scheme);
curl_free(scheme);
}
curl_url_cleanup(url);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
Returns a \fBCURLU \fP* if successful, or NULL if out of memory.
.SH SEE ALSO
.BR CURLOPT_CURLU (3),
.BR curl_url_cleanup (3),
.BR curl_url_dup (3),
.BR curl_url_get (3),
.BR curl_url_set (3),
.BR curl_url_strerror (3)

39
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_url_cleanup.3 Normal file
View File

@ -0,0 +1,39 @@
.\" generated by cd2nroff 0.1 from curl_url_cleanup.md
.TH curl_url_cleanup 3 "2025-08-14" libcurl
.SH NAME
curl_url_cleanup \- free the URL handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_url_cleanup(CURLU *handle);
.fi
.SH DESCRIPTION
Frees all the resources associated with the given \fICURLU\fP handle.
Passing in a NULL pointer in \fIhandle\fP makes this function return
immediately with no action.
Any use of the \fBhandle\fP after this function has been called and have
returned, is illegal.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLU *url = curl_url();
curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
curl_url_cleanup(url);
}
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
none
.SH SEE ALSO
.BR CURLOPT_CURLU (3),
.BR curl_url (3),
.BR curl_url_dup (3),
.BR curl_url_get (3),
.BR curl_url_set (3)

41
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_url_dup.3 Normal file
View File

@ -0,0 +1,41 @@
.\" generated by cd2nroff 0.1 from curl_url_dup.md
.TH curl_url_dup 3 "2025-08-14" libcurl
.SH NAME
curl_url_dup \- duplicate a URL handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLU *curl_url_dup(const CURLU *inhandle);
.fi
.SH DESCRIPTION
Duplicates the URL object the input \fICURLU\fP \fIinhandle\fP identifies and
returns a pointer to the copy as a new \fICURLU\fP handle. The new handle also
needs to be freed with \fIcurl_url_cleanup(3)\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
CURLU *url2;
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
url2 = curl_url_dup(url); /* clone it */
curl_url_cleanup(url2);
}
curl_url_cleanup(url);
}
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
Returns a pointer to a new \fICURLU\fP handle or NULL if out of memory.
.SH SEE ALSO
.BR CURLOPT_CURLU (3),
.BR curl_url (3),
.BR curl_url_cleanup (3),
.BR curl_url_get (3),
.BR curl_url_set (3)

189
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_url_get.3 Normal file
View File

@ -0,0 +1,189 @@
.\" generated by cd2nroff 0.1 from curl_url_get.md
.TH curl_url_get 3 "2025-08-14" libcurl
.SH NAME
curl_url_get \- extract a part from a URL
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLUcode curl_url_get(const CURLU *url,
CURLUPart part,
char **content,
unsigned int flags);
.fi
.SH DESCRIPTION
Given a \fIurl\fP handle of a URL object, this function extracts an individual
piece or the full URL from it.
The \fIpart\fP argument specifies which part to extract (see list below) and
\fIcontent\fP points to a \(aqchar *\(aq to get updated to point to a newly
allocated string with the contents.
The \fIflags\fP argument is a bitmask with individual features.
The returned content pointer must be freed with \fIcurl_free(3)\fP after use.
.SH FLAGS
The flags argument is zero, one or more bits set in a bitmask.
.IP CURLU_DEFAULT_PORT
If the handle has no port stored, this option makes \fIcurl_url_get(3)\fP
return the default port for the used scheme.
.IP CURLU_DEFAULT_SCHEME
If the handle has no scheme stored, this option makes \fIcurl_url_get(3)\fP
return the default scheme instead of error.
.IP CURLU_NO_DEFAULT_PORT
Instructs \fIcurl_url_get(3)\fP to not return a port number if it matches the
default port for the scheme.
.IP CURLU_URLDECODE
Asks \fIcurl_url_get(3)\fP to URL decode the contents before returning it. It
does not decode the scheme, the port number or the full URL.
The query component also gets plus\-to\-space conversion as a bonus when this
bit is set.
Note that this URL decoding is charset unaware and you get a null\-terminated
string back with data that could be intended for a particular encoding.
If there are byte values lower than 32 in the decoded string, the get
operation returns an error instead.
.IP CURLU_URLENCODE
If set, \fIcurl_url_get(3)\fP URL encodes the hostname part when a full URL is
retrieved. If not set (default), libcurl returns the URL with the hostname raw
to support IDN names to appear as\-is. IDN hostnames are typically using
non\-ASCII bytes that otherwise gets percent\-encoded.
Note that even when not asking for URL encoding, the \(aq%\(aq (byte 37) is URL
encoded to make sure the hostname remains valid.
.IP CURLU_PUNYCODE
If set and \fICURLU_URLENCODE\fP is not set, and asked to retrieve the
\fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP parts, libcurl returns the host
name in its punycode version if it contains any non\-ASCII octets (and is an
IDN name).
If libcurl is built without IDN capabilities, using this bit makes
\fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the hostname contains
anything outside the ASCII range.
(Added in curl 7.88.0)
.IP CURLU_PUNY2IDN
If set and asked to retrieve the \fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP
parts, libcurl returns the hostname in its IDN (International Domain Name)
UTF\-8 version if it otherwise is a punycode version. If the punycode name
cannot be converted to IDN correctly, libcurl returns
\fICURLUE_BAD_HOSTNAME\fP.
If libcurl is built without IDN capabilities, using this bit makes
\fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the hostname is using
punycode.
(Added in curl 8.3.0)
.IP CURLU_GET_EMPTY
When this flag is used in curl_url_get(), it makes the function return empty
query and fragments parts or when used in the full URL. By default, libcurl
otherwise considers empty parts non\-existing.
An empty query part is one where this is nothing following the question mark
(before the possible fragment). An empty fragments part is one where there is
nothing following the hash sign.
(Added in curl 8.8.0)
.IP CURLU_NO_GUESS_SCHEME
When this flag is used in curl_url_get(), it treats the scheme as non\-existing
if it was set as a result of a previous guess; when CURLU_GUESS_SCHEME was
used parsing a URL.
Using this flag when getting CURLUPART_SCHEME if the scheme was set as the
result of a guess makes curl_url_get() return CURLUE_NO_SCHEME.
Using this flag when getting CURLUPART_URL if the scheme was set as the result
of a guess makes curl_url_get() return the full URL without the scheme
component. Such a URL can then only be parsed with curl_url_set() if
CURLU_GUESS_SCHEME is used.
(Added in curl 8.9.0)
.SH PARTS
.IP CURLUPART_URL
When asked to return the full URL, \fIcurl_url_get(3)\fP returns a slightly cleaned
up version of the complete URL using all available parts.
We advise using the \fICURLU_PUNYCODE\fP option to get the URL as "normalized" as
possible since IDN allows hostnames to be written in many different ways that
still end up the same punycode version.
Zero\-length queries and fragments are excluded from the URL unless
CURLU_GET_EMPTY is set.
.IP CURLUPART_SCHEME
Scheme cannot be URL decoded on get.
.IP CURLUPART_USER
.IP CURLUPART_PASSWORD
.IP CURLUPART_OPTIONS
The options field is an optional field that might follow the password in the
userinfo part. It is only recognized/used when parsing URLs for the following
schemes: pop3, smtp and imap. The URL API still allows users to set and get
this field independently of scheme when not parsing full URLs.
.IP CURLUPART_HOST
The hostname. If it is an IPv6 numeric address, the zone id is not part of it
but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical addresses
are returned within brackets ([]).
IPv6 names are normalized when set, which should make them as short as
possible while maintaining correct syntax.
.IP CURLUPART_ZONEID
If the hostname is a numeric IPv6 address, this field might also be set.
.IP CURLUPART_PORT
A port cannot be URL decoded on get. This number is returned in a string just
like all other parts. That string is guaranteed to hold a valid port number in
ASCII using base 10.
.IP CURLUPART_PATH
The \fIpart\fP is always at least a slash (\(aq/\(aq) even if no path was supplied
in the URL. A URL path always starts with a slash.
.IP CURLUPART_QUERY
The initial question mark that denotes the beginning of the query part is a
delimiter only. It is not part of the query contents.
A not\-present query returns \fIpart\fP set to NULL.
A zero\-length query returns \fIpart\fP as NULL unless CURLU_GET_EMPTY is set.
The query part gets pluses converted to space when asked to URL decode on get
with the CURLU_URLDECODE bit.
.IP CURLUPART_FRAGMENT
The initial hash sign that denotes the beginning of the fragment is a
delimiter only. It is not part of the fragment contents.
A not\-present fragment returns \fIpart\fP set to NULL.
A zero\-length fragment returns \fIpart\fP as NULL unless CURLU_GET_EMPTY is set.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
if(!rc) {
printf("the scheme is %s\\n", scheme);
curl_free(scheme);
}
curl_url_cleanup(url);
}
}
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
fine. See the \fIlibcurl\-errors(3)\fP man page for the full list with descriptions.
If this function returns an error, no URL part is returned.
.SH SEE ALSO
.BR CURLOPT_CURLU (3),
.BR curl_url (3),
.BR curl_url_cleanup (3),
.BR curl_url_dup (3),
.BR curl_url_set (3),
.BR curl_url_strerror (3)

217
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_url_set.3 Normal file
View File

@ -0,0 +1,217 @@
.\" generated by cd2nroff 0.1 from curl_url_set.md
.TH curl_url_set 3 "2025-08-14" libcurl
.SH NAME
curl_url_set \- set a URL part
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLUcode curl_url_set(CURLU *url,
CURLUPart part,
const char *content,
unsigned int flags);
.fi
.SH DESCRIPTION
The \fIurl\fP handle to work on, passed in as the first argument, must be a
handle previously created by \fIcurl_url(3)\fP or \fIcurl_url_dup(3)\fP.
This function sets or updates individual URL components, or parts, held by the
URL object the handle identifies.
The \fIpart\fP argument should identify the particular URL part (see list below)
to set or change, with \fIcontent\fP pointing to a null\-terminated string with the
new contents for that URL part. The contents should be in the form and
encoding they would use in a URL: URL encoded.
When setting a part in the URL object that was previously already set, it
replaces the data that was previously stored for that part with the new
\fIcontent\fP.
The caller does not have to keep \fIcontent\fP around after a successful call
as this function copies the content.
Setting a part to a NULL pointer removes that part\(aqs contents from the \fICURLU\fP
handle.
This function has an 8 MB maximum length limit for all provided input strings.
In the real world, excessively long fields in URLs cause problems even if this
function accepts them.
When setting or updating contents of individual URL parts, \fIcurl_url_set(3)\fP
might accept data that would not be otherwise possible to set in the string
when it gets populated as a result of a full URL parse. Beware. If done so,
extracting a full URL later on from such components might render an invalid
URL.
The \fIflags\fP argument is a bitmask with independent features.
.SH PARTS
.IP CURLUPART_URL
Allows the full URL of the handle to be replaced. If the handle already is
populated with a URL, the new URL can be relative to the previous.
When successfully setting a new URL, relative or absolute, the handle contents
is replaced with the components of the newly set URL.
Pass a pointer to a null\-terminated string to the \fIurl\fP parameter. The string
must point to a correctly formatted "RFC 3986+" URL or be a NULL pointer. The
URL parser only understands and parses the subset of URLS that are
\&"hierarchical" and therefore contain a \fI://\fP separator \- not the ones that are
normally specified with only a colon separator.
By default this API only parses URLs using schemes for protocols that are
supported built\-in. To make libcurl parse URLs generically even for schemes it
does not know about, the \fBCURLU_NON_SUPPORT_SCHEME\fP flags bit must be set.
Otherwise, this function returns \fICURLUE_UNSUPPORTED_SCHEME\fP for URL schemes
it does not recognize.
Unless \fICURLU_NO_AUTHORITY\fP is set, a blank hostname is not allowed in
the URL.
When a full URL is set (parsed), the hostname component is stored URL decoded.
It is considered fine to set a blank URL ("") as a redirect, but not as a
normal URL. Therefore, setting a "" URL works fine if the handle already holds
a URL, otherwise it triggers an error.
.IP CURLUPART_SCHEME
Scheme cannot be URL decoded on set. libcurl only accepts setting schemes up
to 40 bytes long.
.IP CURLUPART_USER
If only the user part is set and not the password, the URL is represented with
a blank password.
.IP CURLUPART_PASSWORD
If only the password part is set and not the user, the URL is represented with
a blank user.
.IP CURLUPART_OPTIONS
The options field is an optional field that might follow the password in the
userinfo part. It is only recognized/used when parsing URLs for the following
schemes: pop3, smtp and imap. This function however allows users to
independently set this field.
.IP CURLUPART_HOST
The hostname. If it is International Domain Name (IDN) the string must then be
encoded as your locale says or UTF\-8 (when WinIDN is used). If it is a
bracketed IPv6 numeric address it may contain a zone id (or you can use
\fICURLUPART_ZONEID\fP).
Note that if you set an IPv6 address, it gets ruined and causes an error if
you also set the CURLU_URLENCODE flag.
Unless \fICURLU_NO_AUTHORITY\fP is set, a blank hostname is not allowed to set.
.IP CURLUPART_ZONEID
If the hostname is a numeric IPv6 address, this field can also be set.
.IP CURLUPART_PORT
The port number cannot be URL encoded on set. The given port number is
provided as a string and the decimal number in it must be between 0 and
65535. Anything else returns an error.
.IP CURLUPART_PATH
If a path is set in the URL without a leading slash, a slash is prepended
automatically.
.IP CURLUPART_QUERY
The query part gets spaces converted to pluses when asked to URL encode on set
with the \fICURLU_URLENCODE\fP bit.
If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part is
appended on the end of the existing query.
The question mark in the URL is not part of the actual query contents.
.IP CURLUPART_FRAGMENT
The hash sign in the URL is not part of the actual fragment contents.
.SH FLAGS
The flags argument is zero, one or more bits set in a bitmask.
.IP CURLU_APPENDQUERY
Can be used when setting the \fICURLUPART_QUERY\fP component. The provided new
part is then appended at the end of the existing query \- and if the previous
part did not end with an ampersand (&), an ampersand gets inserted before the
new appended part.
When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the
first \(aq=\(aq symbol is not URL encoded.
.IP CURLU_NON_SUPPORT_SCHEME
If set, allows \fIcurl_url_set(3)\fP to set a non\-supported scheme. It then of
course cannot know if the provided scheme is a valid one or not.
.IP CURLU_URLENCODE
When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for
\fBscheme\fP, \fBport\fP and \fBURL\fP.
When setting the path component with URL encoding enabled, the slash character
is skipped.
The query part gets space\-to\-plus converted before the URL conversion is
applied.
This URL encoding is charset unaware and converts the input in a byte\-by\-byte
manner.
.IP CURLU_DEFAULT_SCHEME
If set, allows the URL to be set without a scheme and then sets that to the
default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP option if both are
set.
.IP CURLU_GUESS_SCHEME
If set, allows the URL to be set without a scheme and it instead "guesses"
which scheme that was intended based on the hostname. If the outermost
subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme is
used, otherwise it picks HTTP. Conflicts with the \fICURLU_DEFAULT_SCHEME\fP
option which takes precedence if both are set.
If guessing is not allowed and there is no default scheme set, trying to parse
a URL without a scheme returns error.
If the scheme ends up set as a result of guessing, i.e. it is not actually
present in the parsed URL, it can later be figured out by using the
\fBCURLU_NO_GUESS_SCHEME\fP flag when subsequently getting the URL or the scheme
with \fIcurl_url_get(3)\fP.
.IP CURLU_NO_AUTHORITY
If set, skips authority checks. The RFC allows individual schemes to omit the
host part (normally the only mandatory part of the authority), but libcurl
cannot know whether this is permitted for custom schemes. Specifying the flag
permits empty authority sections, similar to how file scheme is handled.
.IP CURLU_PATH_AS_IS
When set for \fBCURLUPART_URL\fP, this skips the normalization of the
path. That is the procedure where libcurl otherwise removes sequences of
dot\-slash and dot\-dot etc. The same option used for transfers is called
\fICURLOPT_PATH_AS_IS(3)\fP.
.IP CURLU_ALLOW_SPACE
If set, the URL parser allows space (ASCII 32) where possible. The URL syntax
does normally not allow spaces anywhere, but they should be encoded as %20
or \(aq+\(aq. When spaces are allowed, they are still not allowed in the scheme.
When space is used and allowed in a URL, it is stored as\-is unless
\fICURLU_URLENCODE\fP is also set, which then makes libcurl URL encode the
space before stored. This affects how the URL is constructed when
\fIcurl_url_get(3)\fP is subsequently used to extract the full URL or
individual parts. (Added in 7.78.0)
.IP CURLU_DISALLOW_USER
If set, the URL parser does not accept embedded credentials for the
\fBCURLUPART_URL\fP, and instead returns \fBCURLUE_USER_NOT_ALLOWED\fP for
such URLs.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
/* change it to an FTP URL */
rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
}
curl_url_cleanup(url);
}
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
Returns a \fICURLUcode\fP error value, which is CURLUE_OK (0) if everything
went fine. See the \fIlibcurl\-errors(3)\fP man page for the full list with
descriptions.
The input string passed to \fIcurl_url_set(3)\fP must be shorter than eight
million bytes. Otherwise this function returns \fBCURLUE_MALFORMED_INPUT\fP.
If this function returns an error, no URL part is set.
.SH SEE ALSO
.BR CURLOPT_CURLU (3),
.BR curl_url (3),
.BR curl_url_cleanup (3),
.BR curl_url_dup (3),
.BR curl_url_get (3),
.BR curl_url_strerror (3)

38
curl-8.15.0/curl-8.15.0/docs/libcurl/curl_url_strerror.3 Normal file
View File

@ -0,0 +1,38 @@
.\" generated by cd2nroff 0.1 from curl_url_strerror.md
.TH curl_url_strerror 3 "2025-08-14" libcurl
.SH NAME
curl_url_strerror \- return string describing error code
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const char *curl_url_strerror(CURLUcode errornum);
.fi
.SH DESCRIPTION
This function returns a string describing the CURLUcode error code passed in
the argument \fIerrornum\fP.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(rc)
printf("URL error: %s\\n", curl_url_strerror(rc));
curl_url_cleanup(url);
}
.fi
.SH AVAILABILITY
Added in curl 7.80.0
.SH RETURN VALUE
A pointer to a null\-terminated string.
.SH SEE ALSO
.BR curl_easy_strerror (3),
.BR curl_multi_strerror (3),
.BR curl_share_strerror (3),
.BR curl_url_get (3),
.BR curl_url_set (3),
.BR libcurl-errors (3)

Some files were not shown because too many files have changed in this diff Show More