diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml index bc3c98cf0e7..5c789637c78 100644 --- a/.azure-pipelines.yml +++ b/.azure-pipelines.yml @@ -29,221 +29,221 @@ trigger: branches: include: - - 'master' - - '*/ci' + - 'master' + - '*/ci' paths: exclude: - - '.circleci/*' - - '.cirrus.yml' - - '.github/*' - - '.github/workflows/*' - - 'appveyor.yml' - - 'packages/*' - - 'plan9/*' + - '.circleci/*' + - '.cirrus.yml' + - '.github/*' + - '.github/workflows/*' + - 'appveyor.*' + - 'packages/*' + - 'plan9/*' pr: branches: include: - - 'master' + - 'master' paths: exclude: - - '.circleci/*' - - '.cirrus.yml' - - '.github/*' - - '.github/workflows/*' - - 'appveyor.yml' - - 'packages/*' - - 'plan9/*' + - '.circleci/*' + - '.cirrus.yml' + - '.github/*' + - '.github/workflows/*' + - 'appveyor.*' + - 'packages/*' + - 'plan9/*' variables: MAKEFLAGS: '-j 2' stages: -########################################## -### Linux jobs first -########################################## - -- stage: linux - dependsOn: [] - jobs: - - job: ubuntu - # define defaults to make sure variables are always expanded/replaced - variables: - install: '' - configure: '' - tests: '!433' - timeoutInMinutes: 60 - pool: - vmImage: 'ubuntu-latest' - strategy: - matrix: - default: - name: default - install: - configure: --enable-debug --with-openssl - disable_ipv6: - name: w/o IPv6 - configure: --disable-ipv6 --with-openssl - disable_http_smtp_imap: - name: w/o HTTP/SMTP/IMAP - configure: --disable-http --disable-smtp --disable-imap --without-ssl - disable_thredres: - name: sync resolver - configure: --disable-threaded-resolver --with-openssl - https_only: - name: HTTPS only - configure: --disable-dict --disable-file --disable-ftp --disable-gopher --disable-imap --disable-ldap --disable-pop3 --disable-rtmp --disable-rtsp --disable-scp --disable-sftp --disable-smb --disable-smtp --disable-telnet --disable-tftp --with-openssl - torture: - name: torture - install: libnghttp2-dev - configure: --enable-debug --disable-shared --disable-threaded-resolver --with-openssl - tests: -n -t --shallow=25 !FTP - steps: - - script: sudo apt-get update && sudo apt-get install -y stunnel4 python3-impacket libzstd-dev libbrotli-dev $(install) - displayName: 'apt install' - retryCountOnTaskFailure: 3 - - - script: autoreconf -fi && ./configure --enable-warnings --enable-werror $(configure) - displayName: 'configure $(name)' - - - script: make V=1 && make V=1 examples && cd tests && make V=1 - displayName: 'compile' - - - script: make V=1 test-ci - displayName: 'test' - env: - AZURE_ACCESS_TOKEN: "$(System.AccessToken)" - TFLAGS: "-ac /usr/bin/curl -r $(tests)" - -- stage: scanbuild - dependsOn: [] - jobs: - - job: ubuntu - timeoutInMinutes: 30 - pool: - vmImage: 'ubuntu-latest' - steps: - - script: sudo apt-get update && sudo apt-get install -y clang-tools clang libssl-dev libssh2-1-dev libpsl-dev libbrotli-dev libzstd-dev - displayName: 'apt install' - retryCountOnTaskFailure: 3 - - - script: autoreconf -fi - displayName: 'autoreconf' - - - script: scan-build ./configure --enable-debug --enable-werror --with-openssl --with-libssh2 - displayName: 'configure' - env: - CC: "clang" - CCX: "clang++" - - - script: scan-build --status-bugs make - displayName: 'make' - - - script: scan-build --status-bugs make examples - displayName: 'make examples' - -########################################## -### Windows jobs below -########################################## - -- stage: windows - dependsOn: [] - variables: - agent.preferPowerShellOnContainers: true - jobs: - - job: msys2 - # define defaults to make sure variables are always expanded/replaced + ########################################## + ### Linux jobs first + ########################################## + + - stage: linux + dependsOn: [] + jobs: + - job: ubuntu + # define defaults to make sure variables are always expanded/replaced + variables: + install: '' + configure: '' + tests: '!433' + timeoutInMinutes: 60 + pool: + vmImage: 'ubuntu-latest' + strategy: + matrix: + default: + name: default + install: + configure: --enable-debug --with-openssl + disable_ipv6: + name: w/o IPv6 + configure: --disable-ipv6 --with-openssl + disable_http_smtp_imap: + name: w/o HTTP/SMTP/IMAP + configure: --disable-http --disable-smtp --disable-imap --without-ssl + disable_thredres: + name: sync resolver + configure: --disable-threaded-resolver --with-openssl + https_only: + name: HTTPS only + configure: --disable-dict --disable-file --disable-ftp --disable-gopher --disable-imap --disable-ldap --disable-pop3 --disable-rtmp --disable-rtsp --disable-scp --disable-sftp --disable-smb --disable-smtp --disable-telnet --disable-tftp --with-openssl + torture: + name: torture + install: libnghttp2-dev + configure: --enable-debug --disable-shared --disable-threaded-resolver --with-openssl + tests: -n -t --shallow=25 !FTP + steps: + - script: sudo apt-get update && sudo apt-get install -y stunnel4 python3-impacket libzstd-dev libbrotli-dev libpsl-dev $(install) + displayName: 'apt install' + retryCountOnTaskFailure: 3 + + - script: autoreconf -fi && ./configure --enable-warnings --enable-werror $(configure) + displayName: 'configure $(name)' + + - script: make V=1 && make V=1 examples && cd tests && make V=1 + displayName: 'compile' + + - script: make V=1 test-ci + displayName: 'test' + env: + AZURE_ACCESS_TOKEN: "$(System.AccessToken)" + TFLAGS: "-ac /usr/bin/curl -r $(tests)" + + - stage: scanbuild + dependsOn: [] + jobs: + - job: ubuntu + timeoutInMinutes: 30 + pool: + vmImage: 'ubuntu-latest' + steps: + - script: sudo apt-get update && sudo apt-get install -y clang-tools clang libssl-dev libssh2-1-dev libpsl-dev libbrotli-dev libzstd-dev + displayName: 'apt install' + retryCountOnTaskFailure: 3 + + - script: autoreconf -fi + displayName: 'autoreconf' + + - script: scan-build ./configure --enable-debug --enable-werror --with-openssl --with-libssh2 + displayName: 'configure' + env: + CC: "clang" + CCX: "clang++" + + - script: scan-build --status-bugs make + displayName: 'make' + + - script: scan-build --status-bugs make examples + displayName: 'make examples' + + ########################################## + ### Windows jobs below + ########################################## + + - stage: windows + dependsOn: [] variables: - container_img: '' - container_cmd: '' - configure: '' - tests: '' - timeoutInMinutes: 120 - pool: - vmImage: 'windows-2019' - strategy: - matrix: - mingw32_openssl: - name: 32-bit OpenSSL/libssh2 - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw32:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - prepare: pacman -S --needed --noconfirm --noprogressbar libssh2-devel mingw-w64-i686-libssh2 - configure: --host=i686-w64-mingw32 --build=i686-w64-mingw32 --prefix=/mingw32 --enable-debug --enable-werror --with-libssh2 --with-openssl - tests: "~571" - mingw64_openssl: - name: 64-bit OpenSSL/libssh2 - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - prepare: pacman -S --needed --noconfirm --noprogressbar libssh2-devel mingw-w64-x86_64-libssh2 - configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --with-libssh2 --with-openssl - tests: "~571" - mingw64_libssh: - name: 64-bit OpenSSL/libssh - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - prepare: pacman -S --needed --noconfirm --noprogressbar libssh-devel mingw-w64-x86_64-libssh - configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --with-libssh --with-openssl - tests: "~571 ~614" - mingw32: - name: 32-bit w/o zlib - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw32:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - configure: --host=i686-w64-mingw32 --build=i686-w64-mingw32 --prefix=/mingw32 --enable-debug --enable-werror --without-zlib --without-ssl - tests: "!203 !1143" - mingw64: - name: 64-bit w/o zlib - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --without-zlib --without-ssl - tests: "!203 !1143" - mingw32_schannel: - name: 32-bit Schannel/SSPI/WinIDN/libssh2 - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw32:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - prepare: pacman -S --needed --noconfirm --noprogressbar libssh2-devel mingw-w64-i686-libssh2 - configure: --host=i686-w64-mingw32 --build=i686-w64-mingw32 --prefix=/mingw32 --enable-debug --enable-werror --enable-sspi --with-schannel --with-winidn --with-libssh2 - tests: "~571" - mingw64_schannel: - name: 64-bit Schannel/SSPI/WinIDN/libssh2 - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - prepare: pacman -S --needed --noconfirm --noprogressbar libssh2-devel mingw-w64-x86_64-libssh2 - configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --enable-sspi --with-schannel --with-winidn --with-libssh2 - tests: "~571" - mingw32_schannel_nozlib: - name: 32-bit Schannel/SSPI/WinIDN w/o zlib - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw32:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - configure: --host=i686-w64-mingw32 --build=i686-w64-mingw32 --prefix=/mingw32 --enable-debug --enable-werror --enable-sspi --with-schannel --with-winidn --without-zlib - tests: "!203 !1143" - mingw64_schannel_nozlib: - name: 64-bit Schannel/SSPI/WinIDN w/o zlib - container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 - container_cmd: C:\msys64\usr\bin\sh - configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --enable-sspi --with-schannel --with-winidn --without-zlib - tests: "!203 !1143" - container: - image: $(container_img) - env: - MSYS2_PATH_TYPE: inherit - steps: - - script: $(container_cmd) -l -c "cd $(echo '%cd%') && $(prepare)" - displayName: 'prepare' - condition: variables.prepare - retryCountOnTaskFailure: 3 - - - script: $(container_cmd) -l -c "cd $(echo '%cd%') && autoreconf -fi && ./configure $(configure)" - displayName: 'configure $(name)' - - - script: $(container_cmd) -l -c "cd $(echo '%cd%') && make V=1 && make V=1 examples && cd tests && make V=1" - displayName: 'compile' - - - script: $(container_cmd) -l -c "cd $(echo '%cd%') && make V=1 install && PATH=/usr/bin:/bin find . -type f -path '*/.libs/*.exe' -print -execdir mv -t .. {} \;" - displayName: 'install' - - - script: $(container_cmd) -l -c "cd $(echo '%cd%') && make V=1 test-ci" - displayName: 'test' - env: - AZURE_ACCESS_TOKEN: "$(System.AccessToken)" - TFLAGS: "-ac /usr/bin/curl.exe !IDN !SCP ~612 $(tests)" + agent.preferPowerShellOnContainers: true + jobs: + - job: msys2 + # define defaults to make sure variables are always expanded/replaced + variables: + container_img: '' + container_cmd: '' + configure: '' + tests: '' + timeoutInMinutes: 120 + pool: + vmImage: 'windows-2019' + strategy: + matrix: + mingw32_openssl: + name: 32-bit OpenSSL/libssh2 + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw32:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + prepare: pacman -S --needed --noconfirm --noprogressbar libssh2-devel mingw-w64-i686-libssh2 + configure: --host=i686-w64-mingw32 --build=i686-w64-mingw32 --prefix=/mingw32 --enable-debug --enable-werror --with-libssh2 --with-openssl --without-libpsl + tests: "~571" + mingw64_openssl: + name: 64-bit OpenSSL/libssh2 + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + prepare: pacman -S --needed --noconfirm --noprogressbar libssh2-devel mingw-w64-x86_64-libssh2 + configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --with-libssh2 --with-openssl --without-libpsl + tests: "~571" + mingw64_libssh: + name: 64-bit OpenSSL/libssh + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + prepare: pacman -S --needed --noconfirm --noprogressbar libssh-devel mingw-w64-x86_64-libssh + configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --with-libssh --with-openssl --without-libpsl + tests: "~571 ~614" + mingw32: + name: 32-bit w/o zlib + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw32:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + configure: --host=i686-w64-mingw32 --build=i686-w64-mingw32 --prefix=/mingw32 --enable-debug --enable-werror --without-zlib --without-ssl --without-libpsl + tests: "!203 !1143" + mingw64: + name: 64-bit w/o zlib + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --without-zlib --without-ssl --without-libpsl + tests: "!203 !1143" + mingw32_schannel: + name: 32-bit Schannel/SSPI/WinIDN/libssh2 + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw32:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + prepare: pacman -S --needed --noconfirm --noprogressbar libssh2-devel mingw-w64-i686-libssh2 + configure: --host=i686-w64-mingw32 --build=i686-w64-mingw32 --prefix=/mingw32 --enable-debug --enable-werror --enable-sspi --with-schannel --with-winidn --with-libssh2 --without-libpsl + tests: "~571" + mingw64_schannel: + name: 64-bit Schannel/SSPI/WinIDN/libssh2 + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + prepare: pacman -S --needed --noconfirm --noprogressbar libssh2-devel mingw-w64-x86_64-libssh2 + configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --enable-sspi --with-schannel --with-winidn --with-libssh2 --without-libpsl + tests: "~571" + mingw32_schannel_nozlib: + name: 32-bit Schannel/SSPI/WinIDN w/o zlib + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw32:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + configure: --host=i686-w64-mingw32 --build=i686-w64-mingw32 --prefix=/mingw32 --enable-debug --enable-werror --enable-sspi --with-schannel --with-winidn --without-zlib --without-libpsl + tests: "!203 !1143" + mingw64_schannel_nozlib: + name: 64-bit Schannel/SSPI/WinIDN w/o zlib + container_img: ghcr.io/mback2k/curl-docker-winbuildenv/msys2-mingw64:ltsc2019 + container_cmd: C:\msys64\usr\bin\sh + configure: --host=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --prefix=/mingw64 --enable-debug --enable-werror --enable-sspi --with-schannel --with-winidn --without-zlib --without-libpsl + tests: "!203 !1143" + container: + image: $(container_img) + env: + MSYS2_PATH_TYPE: inherit + steps: + - script: $(container_cmd) -l -c "cd $(echo '%cd%') && $(prepare)" + displayName: 'prepare' + condition: variables.prepare + retryCountOnTaskFailure: 3 + + - script: $(container_cmd) -l -c "cd $(echo '%cd%') && autoreconf -fi && ./configure $(configure)" + displayName: 'configure $(name)' + + - script: $(container_cmd) -l -c "cd $(echo '%cd%') && make V=1 && make V=1 examples && cd tests && make V=1" + displayName: 'compile' + + - script: $(container_cmd) -l -c "cd $(echo '%cd%') && make V=1 install && PATH=/usr/bin:/bin find . -type f -path '*/.libs/*.exe' -print -execdir mv -t .. {} \;" + displayName: 'install' + + - script: $(container_cmd) -l -c "cd $(echo '%cd%') && make V=1 test-ci" + displayName: 'test' + env: + AZURE_ACCESS_TOKEN: "$(System.AccessToken)" + TFLAGS: "-ac /usr/bin/curl.exe !IDN !SCP ~612 $(tests)" diff --git a/.circleci/config.yml b/.circleci/config.yml index 11bb0ef7b26..9fc6127a1d9 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -23,6 +23,9 @@ ########################################################################### # View these jobs in the browser: https://app.circleci.com/pipelines/github/curl/curl +# +# The macOS builds use M1 (ARM) machines for platform diversity. +# See https://circleci.com/docs/configuration-reference/#macos-execution-environment # Use the latest 2.1 version of CircleCI pipeline process engine. See: https://circleci.com/docs/2.0/configuration-reference version: 2.1 @@ -54,84 +57,84 @@ commands: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --without-ssl CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --without-ssl CFLAGS='-Wno-vla -mmacosx-version-min=10.9' CPPFLAGS="-I$(brew --prefix libpsl)/include" LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-debug: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --without-ssl --enable-debug CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --without-ssl --enable-debug CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-libssh2: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --without-ssl --with-libssh2=/opt/homebrew/opt/libssh2 --enable-debug CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --without-ssl --with-libssh2=/opt/homebrew/opt/libssh2 --enable-debug CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-libssh-c-ares: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --with-openssl --with-libssh --enable-ares --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --with-openssl --with-libssh --enable-ares --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-libssh: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --with-openssl --with-libssh --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --with-openssl --with-libssh --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" || tail -1000 config.log configure-macos-c-ares: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --without-ssl --enable-ares --enable-debug CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --without-ssl --enable-ares --enable-debug CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-http-only: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-maintainer-mode --disable-dict --disable-file --disable-ftp --disable-gopher --disable-imap --disable-ldap --disable-pop3 --disable-rtmp --disable-rtsp --disable-scp --disable-sftp --disable-smb --disable-smtp --disable-telnet --disable-tftp --disable-unix-sockets --disable-shared --without-brotli --without-gssapi --without-libidn2 --without-libpsl --without-librtmp --without-libssh2 --without-nghttp2 --without-ntlm-auth --without-ssl --without-zlib --enable-debug CFLAGS='-Wno-vla -mmacosx-version-min=10.15' + ./configure --enable-warnings --enable-maintainer-mode --disable-dict --disable-file --disable-ftp --disable-gopher --disable-imap --disable-ldap --disable-mqtt --disable-pop3 --disable-rtsp --disable-smb --disable-smtp --disable-telnet --disable-tftp --disable-unix-sockets --disable-shared --without-brotli --without-gssapi --without-libidn2 --without-libpsl --without-librtmp --without-libssh2 --without-nghttp2 --without-ssl --without-zlib --enable-debug CFLAGS='-Wno-vla -mmacosx-version-min=10.15' configure-macos-securetransport-http2: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --with-secure-transport CFLAGS='-Wno-vla -mmacosx-version-min=10.8' + ./configure --enable-warnings --enable-websockets --with-secure-transport CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.8' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-openssl-http2: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --with-openssl --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --with-openssl --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-libressl-http2: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --with-openssl --enable-debug PKG_CONFIG_PATH="$(brew --prefix libressl)/lib/pkgconfig" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --with-openssl --enable-debug PKG_CONFIG_PATH="$(brew --prefix libressl)/lib/pkgconfig" CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-torture: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --disable-shared --disable-threaded-resolver --with-openssl --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --disable-shared --disable-threaded-resolver --with-openssl --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" configure-macos-torture-ftp: steps: - run: command: | autoreconf -fi - ./configure --enable-warnings --enable-websockets --disable-shared --disable-threaded-resolver --with-openssl --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' + ./configure --enable-warnings --enable-websockets --disable-shared --disable-threaded-resolver --with-openssl --enable-debug PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig" CPPFLAGS="-I$(brew --prefix libpsl)/include" CFLAGS='-Wno-vla -mmacosx-version-min=10.9' LDFLAGS="-L$(brew --prefix libpsl)/lib -L$(brew --prefix icu4c)/lib" LIBS="-licuuc -licudata" install-cares: steps: @@ -149,7 +152,7 @@ commands: steps: - run: command: | - sudo apt-get update && sudo apt-get install -y libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev python3-pip + sudo apt-get update && sudo apt-get install -y libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev python3-pip libpsl-dev sudo python3 -m pip install impacket install-deps-brew: @@ -157,7 +160,7 @@ commands: - run: command: | # Drop libressl as long as we're not trying to build it - echo libtool autoconf automake pkg-config nghttp2 libssh2 openssl libssh c-ares | xargs -Ix -n1 echo brew '"x"' > /tmp/Brewfile + echo libtool autoconf automake pkg-config nghttp2 libssh2 openssl libssh c-ares libpsl icu4c | xargs -Ix -n1 echo brew '"x"' > /tmp/Brewfile while [ $? -eq 0 ]; do for i in 1 2 3; do brew update && brew bundle install --no-lock --file /tmp/Brewfile && break 2 || { echo Error: wait to try again; sleep 10; } done; false Too many retries; done sudo python3 -m pip install impacket @@ -220,8 +223,8 @@ commands: build-macos: steps: - - run: make -j7 V=1 - - run: make -j7 V=1 examples + - run: make -j5 V=1 + - run: make -j5 V=1 examples test: steps: @@ -229,7 +232,7 @@ commands: test-macos: steps: - - run: make -j7 V=1 test-ci + - run: make -j5 V=1 test-ci test-torture: steps: @@ -237,18 +240,20 @@ commands: test-torture-ftp: steps: - - run: make -j5 V=1 test-ci TFLAGS="-n -t --shallow=20 FTP" + # Test 250 takes too long, causing Circle CI to kill the job + - run: make -j5 V=1 test-ci TFLAGS="-n -t --shallow=20 FTP !250 !251" executors: ubuntu: machine: - image: ubuntu-2004:202010-01 + image: ubuntu-2004:2024.01.1 jobs: basic: executor: ubuntu steps: - checkout + - install-deps - configure - build - test @@ -284,6 +289,7 @@ jobs: executor: ubuntu steps: - checkout + - install-deps - install-cares - configure-cares - build @@ -293,6 +299,7 @@ jobs: executor: ubuntu steps: - checkout + - install-deps - install-libssh - configure-libssh - build @@ -300,34 +307,31 @@ jobs: arm: machine: - image: ubuntu-2004:202101-01 + image: ubuntu-2004:2024.01.1 resource_class: arm.medium steps: - checkout + - install-deps - configure - build - test arm-cares: machine: - image: ubuntu-2004:202101-01 + image: ubuntu-2004:2024.01.1 resource_class: arm.medium steps: - checkout + - install-deps - install-cares - configure-cares-debug - build - test - # TODO: All builds with "macos.x86.medium.gen2" must be changed to - # "macos.m1.medium.gen1" in January 2024 because the former will be removed - # (the names should also be changed from macos-x86-* to macos-arm-*). We - # want the M1 (ARM) machines anyway, for platform diversity. - # See https://circleci.com/docs/configuration-reference/#macos-execution-environment - macos-x86-normal: + macos-arm-normal: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -335,10 +339,10 @@ jobs: - build-macos - test-macos - macos-x86-debug: + macos-arm-debug: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -346,10 +350,10 @@ jobs: - build-macos - test-macos - macos-x86-libssh2: + macos-arm-libssh2: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -357,10 +361,10 @@ jobs: - build-macos - test-macos - macos-x86-libssh-c-ares: + macos-arm-libssh-c-ares: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -368,10 +372,10 @@ jobs: - build-macos - test-macos - macos-x86-libssh: + macos-arm-libssh: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -379,10 +383,10 @@ jobs: - build-macos - test-macos - macos-x86-c-ares: + macos-arm-c-ares: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -390,10 +394,10 @@ jobs: - build-macos - test-macos - macos-x86-http-only: + macos-arm-http-only: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -401,10 +405,10 @@ jobs: - build-macos - test-macos - macos-x86-http-securetransport-http2: + macos-arm-http-securetransport-http2: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -412,10 +416,10 @@ jobs: - build-macos - test-macos - macos-x86-http-openssl-http2: + macos-arm-http-openssl-http2: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -423,10 +427,10 @@ jobs: - build-macos - test-macos - macos-x86-http-libressl-http2: + macos-arm-http-libressl-http2: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -434,10 +438,10 @@ jobs: - build-macos - test-macos - macos-x86-http-torture: + macos-arm-http-torture: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -445,10 +449,10 @@ jobs: - build-macos - test-torture - macos-x86-http-torture-ftp: + macos-arm-http-torture-ftp: macos: xcode: 15.0.0 - resource_class: macos.x86.medium.gen2 + resource_class: macos.m1.medium.gen1 steps: - checkout - install-deps-brew @@ -489,52 +493,52 @@ workflows: jobs: - arm-cares - macos-x86-normal: + macos-arm-normal: jobs: - - macos-x86-normal + - macos-arm-normal - macos-x86-debug: + macos-arm-debug: jobs: - - macos-x86-debug + - macos-arm-debug - macos-x86-libssh2: + macos-arm-libssh2: jobs: - - macos-x86-libssh2 + - macos-arm-libssh2 - macos-x86-libssh-c-ares: + macos-arm-libssh-c-ares: jobs: - - macos-x86-libssh-c-ares + - macos-arm-libssh-c-ares - macos-x86-libssh: + macos-arm-libssh: jobs: - - macos-x86-libssh + - macos-arm-libssh - macos-x86-c-ares: + macos-arm-c-ares: jobs: - - macos-x86-c-ares + - macos-arm-c-ares - macos-x86-http-only: + macos-arm-http-only: jobs: - - macos-x86-http-only + - macos-arm-http-only - macos-x86-http-securetransport-http2: + macos-arm-http-securetransport-http2: jobs: - - macos-x86-http-securetransport-http2 + - macos-arm-http-securetransport-http2 - macos-x86-http-openssl-http2: + macos-arm-http-openssl-http2: jobs: - - macos-x86-http-openssl-http2 + - macos-arm-http-openssl-http2 # There are problem linking with LibreSSL on the CI boxes that prevent this # from working. - #macos-x86-http-libressl-http2: - # jobs: - # - macos-x86-http-libressl-http2 + # macos-arm-http-libressl-http2: + # jobs: + # - macos-arm-http-libressl-http2 - macos-x86-http-torture: + macos-arm-http-torture: jobs: - - macos-x86-http-torture + - macos-arm-http-torture - macos-x86-http-torture-ftp: + macos-arm-http-torture-ftp: jobs: - - macos-x86-http-torture-ftp + - macos-arm-http-torture-ftp diff --git a/.cirrus.yml b/.cirrus.yml index 27b4659b119..05c92756a47 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -32,7 +32,7 @@ freebsd_task: '.azure-pipelines.yml', '.circleci/**', '.github/**', - 'appveyor.yml', + 'appveyor.*', 'CMake/**', 'packages/**', 'plan9/**', @@ -54,18 +54,18 @@ freebsd_task: pkginstall_script: - pkg update -f - - pkg install -y autoconf automake libtool pkgconf brotli openldap26-client heimdal libpsl libssh2 libidn2 librtmp libnghttp2 nghttp2 stunnel py39-openssl py39-impacket py39-cryptography + - pkg install -y autoconf automake libtool pkgconf brotli openldap26-client heimdal libpsl libssh2 libidn2 librtmp libnghttp2 nghttp2 stunnel py39-openssl py39-impacket py39-cryptography libpsl - pkg delete -y curl configure_script: - autoreconf -fi # Building with the address sanitizer is causing unexplainable test issues due to timeouts - #- case `uname -r` in - # 12.2*) - # export CC=clang; - # export CFLAGS="-fsanitize=address,undefined,signed-integer-overflow -fno-sanitize-recover=undefined,integer -Wformat -Werror=format-security -Werror=array-bounds -g"; - # export CXXFLAGS="-fsanitize=address,undefined -fno-sanitize-recover=undefined,integer -Wformat -Werror=format-security -Werror=array-bounds -g"; - # export LDFLAGS="-fsanitize=address,undefined -fno-sanitize-recover=undefined,integer" ;; - # esac + # - case `uname -r` in + # 12.2*) + # export CC=clang; + # export CFLAGS="-fsanitize=address,undefined,signed-integer-overflow -fno-sanitize-recover=undefined,integer -Wformat -Werror=format-security -Werror=array-bounds -g"; + # export CXXFLAGS="-fsanitize=address,undefined -fno-sanitize-recover=undefined,integer -Wformat -Werror=format-security -Werror=array-bounds -g"; + # export LDFLAGS="-fsanitize=address,undefined -fno-sanitize-recover=undefined,integer" ;; + # esac - ./configure --prefix="${HOME}"/install --enable-debug --with-openssl --with-libssh2 --with-brotli --with-gssapi --with-libidn2 --enable-manual --enable-ldap --enable-ldaps --with-librtmp --with-libpsl --with-nghttp2 || { tail -300 config.log; false; } compile_script: - make V=1 && make V=1 examples && cd tests && make V=1 diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000000..5ace4600a1f --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/labeler.yml b/.github/labeler.yml index be585a69010..c22bd6e485f 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -13,481 +13,246 @@ # PR is all about that one topic, like HTTP/3), while the second ones are # "addendums" that give useful information about a PR that's really mostly # something else (e.g. CI if the PR also touches CI jobs). +# +# N.B. any-glob-to-all-files is misnamed; it acts like one-glob-to-all-files. +# Therefore, to get any-glob-to-all-files semantics, there must be a single glob +# with all matching patterns within braces. +# +# See https://github.com/actions/labeler/ for documentation on this file. appleOS: -- all: - - changed-files: - - any-glob-to-all-files: - - '.github/workflows/macos.yml' - - 'lib/config-mac.h' - - 'lib/macos*' - - 'lib/vtls/sectransp*' - - 'm4/curl-sectransp.m4' - - 'MacOSX-Framework' + - all: + - changed-files: + - any-glob-to-all-files: + - '{.github/workflows/macos.yml,lib/config-mac.h,lib/macos*,lib/vtls/sectransp*,m4/curl-sectransp.m4,MacOSX-Framework}' authentication: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/mk-ca-bundle.1' - - 'docs/libcurl/opts/CURLINFO_HTTPAUTH*' - - 'docs/libcurl/opts/CURLINFO_PROXYAUTH*' - - 'docs/libcurl/opts/CURLOPT_KRB*' - - 'docs/libcurl/opts/CURLOPT_SASL*' - - 'docs/libcurl/opts/CURLOPT_SERVICE_NAME*' - - 'docs/libcurl/opts/CURLOPT_USERNAME*' - - 'docs/libcurl/opts/CURLOPT_USERPWD*' - - 'docs/libcurl/opts/CURLOPT_XOAUTH*' - - 'lib/*gssapi*' - - 'lib/*krb5*' - - 'lib/*ntlm*' - - 'lib/curl_sasl.*' - - 'lib/http_aws*' - - 'lib/http_digest.*' - - 'lib/http_negotiate.*' - - 'lib/vauth/**' - - 'tests/server/fake_ntlm.c' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/mk-ca-bundle.1,docs/libcurl/opts/CURLINFO_HTTPAUTH*,docs/libcurl/opts/CURLINFO_PROXYAUTH*,docs/libcurl/opts/CURLOPT_KRB*,docs/libcurl/opts/CURLOPT_SASL*,docs/libcurl/opts/CURLOPT_SERVICE_NAME*,docs/libcurl/opts/CURLOPT_USERNAME*,docs/libcurl/opts/CURLOPT_USERPWD*,docs/libcurl/opts/CURLOPT_XOAUTH*,lib/*gssapi*,lib/*krb5*,lib/*ntlm*,lib/curl_sasl.*,lib/http_aws*,lib/http_digest.*,lib/http_negotiate.*,lib/vauth/**,tests/server/fake_ntlm.c}' build: -- all: - - changed-files: - - any-glob-to-all-files: - - '**/CMakeLists.txt' - - '**/Makefile.am' - - '**/Makefile.inc' - - '**/Makefile.mk' - - '**/*.m4' - - '**/*.mk' - - '*.m4' - - 'docs/INSTALL.cmake' - - 'lib/curl_config.h.cmake' - - 'lib/libcurl*.in' - - 'CMake/**' - - 'CMakeLists.txt' - - 'configure.ac' - - 'm4/**' - - 'MacOSX-Framework' - - 'Makefile.*' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' - - 'libcurl.def' + - all: + - changed-files: + - any-glob-to-all-files: + - '{**/CMakeLists.txt,**/Makefile.am,**/Makefile.inc,**/Makefile.mk,**/*.m4,**/*.mk,*.m4,docs/INSTALL.cmake,lib/curl_config.h.cmake,lib/libcurl*.in,CMake/**,CMakeLists.txt,configure.ac,m4/**,MacOSX-Framework,Makefile.*,packages/**,plan9/**,projects/**,winbuild/**,libcurl.def}' CI: -- all: - - changed-files: - - any-glob-to-any-file: - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - '.github/**' - - 'appveyor.yml' - - 'scripts/ci*' - - 'tests/azure.pm' - - 'tests/appveyor.pm' - - 'tests/CI.md' + - all: + - changed-files: + - any-glob-to-any-file: + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - '.github/**' + - 'appveyor.*' + - 'scripts/ci*' + - 'tests/azure.pm' + - 'tests/appveyor.pm' + - 'tests/CI.md' cmake: -- all: - - changed-files: - - any-glob-to-all-files: - - '**/CMakeLists.txt' - - 'CMake/**' - - 'docs/INSTALL.cmake' - - 'lib/curl_config.h.cmake' + - all: + - changed-files: + - any-glob-to-all-files: + - '{**/CMakeLists.txt,CMake/**,docs/INSTALL.cmake,lib/curl_config.h.cmake}' cmdline tool: -- all: - - changed-files: - - any-glob-to-any-file: - - 'docs/cmdline-opts/**' - - 'src/**' + - all: + - changed-files: + - any-glob-to-any-file: + - 'docs/cmdline-opts/**' + - 'src/**' connecting & proxies: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/CONNECTION-FILTERS.md' - - 'docs/examples/ipv6.c' - - 'docs/libcurl/opts/CURLINFO_CONNECT*' - - 'docs/libcurl/opts/CURLINFO_PROXY*' - - 'docs/libcurl/opts/CURLOPT_ADDRESS*' - - 'docs/libcurl/opts/CURLOPT_CONNECT*' - - 'docs/libcurl/opts/CURLOPT_HAPROXY*' - - 'docs/libcurl/opts/CURLOPT_OPENSOCKET*' - - 'docs/libcurl/opts/CURLOPT_PRE_PROXY*' - - 'docs/libcurl/opts/CURLOPT_PROXY*' - - 'docs/libcurl/opts/CURLOPT_SOCKOPT*' - - 'docs/libcurl/opts/CURLOPT_SOCKS*' - - 'docs/libcurl/opts/CURLOPT_TCP*' - - 'docs/libcurl/opts/CURLOPT_TIMEOUT*' - - 'lib/cf-*proxy.*' - - 'lib/cf-socket.*' - - 'lib/cfilters.*' - - 'lib/conncache.*' - - 'lib/connect.*' - - 'lib/http_proxy.*' - - 'lib/if2ip.*' - - 'lib/noproxy.*' - - 'lib/socks.*' - - 'tests/server/socksd.c' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/CONNECTION-FILTERS.md,docs/examples/ipv6.c,docs/libcurl/opts/CURLINFO_CONNECT*,docs/libcurl/opts/CURLINFO_PROXY*,docs/libcurl/opts/CURLOPT_ADDRESS*,docs/libcurl/opts/CURLOPT_CONNECT*,docs/libcurl/opts/CURLOPT_HAPROXY*,docs/libcurl/opts/CURLOPT_OPENSOCKET*,docs/libcurl/opts/CURLOPT_PRE_PROXY*,docs/libcurl/opts/CURLOPT_PROXY*,docs/libcurl/opts/CURLOPT_SOCKOPT*,docs/libcurl/opts/CURLOPT_SOCKS*,docs/libcurl/opts/CURLOPT_TCP*,docs/libcurl/opts/CURLOPT_TIMEOUT*,lib/cf-*proxy.*,lib/cf-socket.*,lib/cfilters.*,lib/conncache.*,lib/connect.*,lib/http_proxy.*,lib/if2ip.*,lib/noproxy.*,lib/socks.*,tests/server/socksd.c}' cookies: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/HTTP-COOKIES.md' - - 'docs/cmdline-opts/cookie*' - - 'docs/cmdline-opts/junk-session-cookies.d' - - 'docs/libcurl/opts/CURLINFO_COOKIE*' - - 'docs/libcurl/opts/CURLOPT_COOKIE*' - - 'docs/examples/cookie_interface.c' - - 'lib/cookie.*' - - 'lib/psl.*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/HTTP-COOKIES.md,docs/cmdline-opts/cookie*,docs/cmdline-opts/junk-session-cookies.md,docs/libcurl/opts/CURLINFO_COOKIE*,docs/libcurl/opts/CURLOPT_COOKIE*,docs/examples/cookie_interface.c,lib/cookie.*,lib/psl.*}' cryptography: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/CIPHERS.md' - - 'docs/RUSTLS.md' - - 'docs/libcurl/opts/CURLOPT_EGDSOCKET*' - - 'lib/*sha256*' - - 'lib/curl_des.*' - - 'lib/curl_hmac.*' - - 'lib/curl_md?.*' - - 'lib/md?.*' - - 'lib/rand.*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/CIPHERS.md,docs/RUSTLS.md,docs/libcurl/opts/CURLOPT_EGDSOCKET*,lib/*sha256*,lib/*sha512*,lib/curl_des.*,lib/curl_hmac.*,lib/curl_md?.*,lib/md?.*,lib/rand.*}' DICT: -- all: - - changed-files: - - any-glob-to-all-files: - - 'lib/dict.*' - - 'tests/dictserver.py' + - all: + - changed-files: + - any-glob-to-all-files: + - '{lib/dict.*,tests/dictserver.py}' documentation: -- all: - - changed-files: - - any-glob-to-all-files: - - '**/*.md' - - '**/*.txt' - - '**/*.1' - - '**/*.3' - - 'CHANGES' - - 'docs/**' - - 'GIT-INFO' - - 'LICENSES/**' - - 'README' - - 'RELEASE-NOTES' - - AllGlobsToAllFiles: - # negative matches - - '!**/CMakeLists.txt' - - '!**/Makefile.am' + - all: + - changed-files: + - any-glob-to-all-files: + - '{.github/workflows/badwords.yml,.github/workflows/man-examples.yml,.github/workflows/synopsis.yml,.github/scripts/badwords.*,.github/scripts/cd2cd,.github/scripts/cd2nroff,.github/scripts/cdall.pl,.github/scripts/nroff2cd,.github/scripts/verify-examples.pl,.github/scripts/verify-synopsis.pl,**/*.md,**/*.txt,**/*.1,CHANGES,docs/**,LICENSES/**,README,RELEASE-NOTES,scripts/cd*}' + - all-globs-to-all-files: + # negative matches + - '!**/CMakeLists.txt' + - '!**/Makefile.am' FTP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/libcurl/opts/CURLINFO_FTP*' - - 'docs/libcurl/opts/CURLOPT_FTP*' - - 'docs/libcurl/opts/CURLOPT_WILDCARDMATCH*' - - 'docs/examples/ftp*' - - 'lib/curl_fnmatch.*' - - 'lib/curl_range.*' - - 'lib/ftp*' - - 'tests/ftp*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/libcurl/opts/CURLINFO_FTP*,docs/libcurl/opts/CURLOPT_FTP*,docs/libcurl/opts/CURLOPT_WILDCARDMATCH*,docs/examples/ftp*,lib/curl_fnmatch.*,lib/curl_range.*,lib/ftp*,tests/ftp*' GOPHER: -- all: - - changed-files: - - any-glob-to-all-files: - - 'lib/gopher*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{lib/gopher*}' HTTP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/examples/hsts*' - - 'docs/examples/http-*' - - 'docs/examples/httpput*' - - 'docs/examples/https*' - - 'docs/examples/*post*' - - 'docs/HSTS.md' - - 'docs/HTTP-COOKIES.md' - - 'docs/libcurl/opts/CURLINFO_COOKIE*' - - 'docs/libcurl/opts/CURLOPT_COOKIE*' - - 'docs/libcurl/opts/CURLINFO_HTTP_**' - - 'docs/libcurl/opts/CURLINFO_REDIRECT*' - - 'docs/libcurl/opts/CURLINFO_REFER*' - - 'docs/libcurl/opts/CURLOPT_FOLLOWLOCATION*' - - 'docs/libcurl/opts/CURLOPT_HSTS*' - - 'docs/libcurl/opts/CURLOPT_HTTP*' - - 'docs/libcurl/opts/CURLOPT_POST.*' - - 'docs/libcurl/opts/CURLOPT_POSTFIELD*' - - 'docs/libcurl/opts/CURLOPT_POSTREDIR*' - - 'docs/libcurl/opts/CURLOPT_REDIR*' - - 'docs/libcurl/opts/CURLOPT_REFER*' - - 'docs/libcurl/opts/CURLOPT_TRAILER*' - - 'docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING*' - - 'lib/cf-https*' - - 'lib/cf-h1*' - - 'lib/cf-h2*' - - 'lib/cookie.*' - - 'lib/http*' - - 'tests/http*' - - 'tests/http-server.pl' - - 'tests/http/*' - - 'tests/nghttp*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/examples/hsts*,docs/examples/http-*,docs/examples/httpput*,docs/examples/https*,docs/examples/*post*,docs/HSTS.md,docs/HTTP-COOKIES.md,docs/libcurl/opts/CURLINFO_COOKIE*,docs/libcurl/opts/CURLOPT_COOKIE*,docs/libcurl/opts/CURLINFO_HTTP_**,docs/libcurl/opts/CURLINFO_REDIRECT*,docs/libcurl/opts/CURLINFO_REFER*,docs/libcurl/opts/CURLOPT_FOLLOWLOCATION*,docs/libcurl/opts/CURLOPT_HSTS*,docs/libcurl/opts/CURLOPT_HTTP*,docs/libcurl/opts/CURLOPT_POST.*,docs/libcurl/opts/CURLOPT_POSTFIELD*,docs/libcurl/opts/CURLOPT_POSTREDIR*,docs/libcurl/opts/CURLOPT_REDIR*,docs/libcurl/opts/CURLOPT_REFER*,docs/libcurl/opts/CURLOPT_TRAILER*,docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING*,lib/cf-https*,lib/cf-h1*,lib/cf-h2*,lib/cookie.*,lib/http*,tests/http*,tests/http-server.pl,tests/http/*,tests/nghttp*}' HTTP/2: -- all: - - changed-files: - - any-glob-to-all-files: - - 'CMake/FindNGHTTP2.cmake' - - 'CMake/FindQUICHE.cmake' - - 'docs/HTTP2.md' - - 'docs/libcurl/opts/CURLOPT_STREAM*' - - 'docs/examples/http2*' - - 'lib/http2*' - - 'tests/http2-server.pl' + - all: + - changed-files: + - any-glob-to-all-files: + - '{CMake/FindNGHTTP2.cmake,CMake/FindQUICHE.cmake,docs/HTTP2.md,docs/libcurl/opts/CURLOPT_STREAM*,docs/examples/http2*,lib/http2*,tests/http2-server.pl}' HTTP/3: -- all: - - changed-files: - - any-glob-to-all-files: - - '.github/workflows/ngtcp2*' - - '.github/workflows/quiche*' - - 'CMake/FindMSH3.cmake' - - 'CMake/FindNGHTTP3.cmake' - - 'CMake/FindNGTCP2.cmake' - - 'docs/HTTP3.md' - - 'docs/examples/http3*' - - 'lib/vquic/**' - - 'tests/http3-server.pl' - - 'tests/nghttpx.conf' + - all: + - changed-files: + - any-glob-to-all-files: + - '{.github/workflows/ngtcp2*,.github/workflows/quiche*,.github/workflows/osslq*,CMake/FindMSH3.cmake,CMake/FindNGHTTP3.cmake,CMake/FindNGTCP2.cmake,docs/HTTP3.md,docs/examples/http3*,lib/vquic/**,tests/http3-server.pl,tests/nghttpx.conf}' Hyper: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/HYPER.md' - - 'lib/c-hyper.*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/HYPER.md,lib/c-hyper.*}' IMAP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'lib/imap*' - - 'docs/examples/imap*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{lib/imap*,docs/examples/imap*}' LDAP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'lib/*ldap*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{lib/*ldap*}' libcurl API: -- all: - - changed-files: - - any-glob-to-any-file: - - 'docs/libcurl/ABI.md' - - 'docs/libcurl/curl_*.3' - - 'include/curl/**' + - all: + - changed-files: + - any-glob-to-any-file: + - 'docs/libcurl/ABI.md' + - 'docs/libcurl/curl_*.md' + - 'include/curl/**' logging: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/cmdline-opts/trace*' - - 'docs/libcurl/curl_global_trace*' - - 'lib/curl_trc*' - - 'tests/http/test_15_tracing.py' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/cmdline-opts/trace*,docs/libcurl/curl_global_trace*,lib/curl_trc*,tests/http/test_15_tracing.py}' MIME: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/libcurl/curl_form*' - - 'docs/libcurl/curl_mime_*' - - 'docs/libcurl/opts/CURLOPT_MIME*' - - 'docs/libcurl/opts/CURLOPT_HTTPPOST*' - - 'lib/formdata*' - - 'lib/mime*' - - 'src/tool_formparse.*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/libcurl/curl_form*,docs/libcurl/curl_mime_*,docs/libcurl/opts/CURLOPT_MIME*,docs/libcurl/opts/CURLOPT_HTTPPOST*,lib/formdata*,lib/mime*,src/tool_formparse.*}' MQTT: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/MQTT.md' - - 'lib/mqtt*' - - 'tests/server/mqttd.c' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/MQTT.md,lib/mqtt*,tests/server/mqttd.c}' name lookup: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/examples/resolve.c' - - 'docs/libcurl/opts/CURLINFO_NAMELOOKUP*' - - 'docs/libcurl/opts/CURLOPT_DNS*' - - 'docs/libcurl/opts/CURLOPT_DOH*' - - 'docs/libcurl/opts/CURLOPT_RESOLVE*' - - 'lib/asyn*' - - 'lib/curl_gethostname.*' - - 'lib/doh*' - - 'lib/host*' - - 'lib/idn*' - - 'lib/inet_pton.*' - - 'lib/socketpair*' - - 'tests/server/resolve.c' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/examples/resolve.c,docs/libcurl/opts/CURLINFO_NAMELOOKUP*,docs/libcurl/opts/CURLOPT_DNS*,docs/libcurl/opts/CURLOPT_DOH*,docs/libcurl/opts/CURLOPT_RESOLVE*,lib/asyn*,lib/curl_gethostname.*,lib/doh*,lib/host*,lib/idn*,lib/inet_pton.*,lib/socketpair*,tests/server/resolve.c}' POP3: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/examples/pop3*' - - 'lib/pop3.*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/examples/pop3*,lib/pop3.*}' RTMP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'lib/curl_rtmp.*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{lib/curl_rtmp.*}' RTSP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/libcurl/opts/CURLINFO_RTSP*' - - 'docs/libcurl/opts/CURLOPT_RTSP*' - - 'lib/rtsp.*' - - 'tests/rtspserver.pl' - - 'tests/server/rtspd.c' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/libcurl/opts/CURLINFO_RTSP*,docs/libcurl/opts/CURLOPT_RTSP*,lib/rtsp.*,tests/rtspserver.pl,tests/server/rtspd.c}' SCP/SFTP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'CMake/FindLibSSH2.cmake' - - 'docs/libcurl/opts/CURLOPT_SSH*' - - 'docs/examples/sftp*' - - 'lib/vssh/**' - - 'tests/sshhelp.pm' - - 'tests/sshserver.pl' + - all: + - changed-files: + - any-glob-to-all-files: + - '{CMake/FindLibSSH2.cmake,docs/libcurl/opts/CURLOPT_SSH*,docs/examples/sftp*,lib/vssh/**,tests/sshhelp.pm,tests/sshserver.pl}' script: -- all: - - changed-files: - - any-glob-to-all-files: - - '**/*.pl' - - '**/*.sh' - - 'curl-config.in' - - 'docs/curl-config.1' - - 'docs/mk-ca-bundle.1' - - 'docs/THANKS-filter' - - 'scripts/**' + - all: + - changed-files: + - any-glob-to-all-files: + - '{**/*.pl,**/*.sh,curl-config.in,docs/curl-config.1,docs/mk-ca-bundle.1,docs/THANKS-filter,scripts/**}' SMB: -- all: - - changed-files: - - any-glob-to-all-files: - - 'lib/smb.*' - - 'tests/smbserver.py' + - all: + - changed-files: + - any-glob-to-all-files: + - '{lib/smb.*,tests/smbserver.py}' SMTP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/examples/smtp-*' - - 'docs/libcurl/opts/CURLOPT_MAIL*' - - 'lib/smtp.*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/examples/smtp-*,docs/libcurl/opts/CURLOPT_MAIL*,lib/smtp.*}' tests: -- all: - - changed-files: - - any-glob-to-any-file: - - 'tests/**' + - all: + - changed-files: + - any-glob-to-any-file: + - 'tests/**' TFTP: -- all: - - changed-files: - - any-glob-to-all-files: - - 'lib/tftp.*' - - 'tests/tftpserver.pl' - - 'tests/server/tftp*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{lib/tftp.*,tests/tftpserver.pl,tests/server/tftp*}' TLS: -- all: - - changed-files: - - any-glob-to-all-files: - - 'CMake/FindBearSSL.cmake' - - 'CMake/FindMbedTLS.cmake' - - 'CMake/FindWolfSSL.cmake' - - 'docs/examples/ssl*' - - 'docs/examples/*ssl.*' - - 'docs/examples/*tls.*' - - 'docs/SSL*' - - 'docs/libcurl/curl_global_sslset*' - - 'docs/libcurl/opts/CURLINFO_CA*' - - 'docs/libcurl/opts/CURLINFO_CERT*' - - 'docs/libcurl/opts/CURLINFO_SSL*' - - 'docs/libcurl/opts/CURLINFO_TLS*' - - 'docs/libcurl/opts/CURLOPT_CA*' - - 'docs/libcurl/opts/CURLOPT_CERT*' - - 'docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY*' - - 'docs/libcurl/opts/CURLOPT_SSL*' - - 'docs/libcurl/opts/CURLOPT_TLS*' - - 'docs/libcurl/opts/CURLOPT_USE_SSL*' - - 'lib/vtls/**' - - 'm4/curl-bearssl.m4' - - 'm4/curl-gnutls.m4' - - 'm4/curl-mbedtls.m4' - - 'm4/curl-openssl.m4' - - 'm4/curl-rustls.m4' - - 'm4/curl-schannel.m4' - - 'm4/curl-sectransp.m4' - - 'm4/curl-wolfssl.m4' + - all: + - changed-files: + - any-glob-to-all-files: + - '{CMake/FindBearSSL.cmake,CMake/FindMbedTLS.cmake,CMake/FindWolfSSL.cmake,docs/examples/ssl*,docs/examples/*ssl.*,docs/examples/*tls.*,docs/SSL*,docs/libcurl/curl_global_sslset*,docs/libcurl/opts/CURLINFO_CA*,docs/libcurl/opts/CURLINFO_CERT*,docs/libcurl/opts/CURLINFO_SSL*,docs/libcurl/opts/CURLINFO_TLS*,docs/libcurl/opts/CURLOPT_CA*,docs/libcurl/opts/CURLOPT_CERT*,docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY*,docs/libcurl/opts/CURLOPT_SSL*,docs/libcurl/opts/CURLOPT_TLS*,docs/libcurl/opts/CURLOPT_USE_SSL*,lib/vtls/**,m4/curl-bearssl.m4,m4/curl-gnutls.m4,m4/curl-mbedtls.m4,m4/curl-openssl.m4,m4/curl-rustls.m4,m4/curl-schannel.m4,m4/curl-sectransp.m4,m4/curl-wolfssl.m4}' URL: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/libcurl/curl_url*' - - 'docs/URL-SYNTAX.md' - - 'docs/examples/parseurl*' - - 'include/curl/urlapi.h' - - 'lib/urlapi*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/libcurl/curl_url*,docs/URL-SYNTAX.md,docs/examples/parseurl*,include/curl/urlapi.h,lib/urlapi*}' WebSocket: -- all: - - changed-files: - - any-glob-to-all-files: - - 'docs/WEBSOCKET.md*' - - 'docs/examples/websocket*' - - 'docs/libcurl/curl_ws_*' - - 'docs/libcurl/libcurl-ws*' - - 'docs/libcurl/opts/CURLOPT_WS_*' - - 'include/curl/websockets.h' - - 'lib/ws.*' - - 'tests/http/clients/ws*' - - 'tests/http/test_20_websockets.py' - - 'tests/http/testenv/ws*' + - all: + - changed-files: + - any-glob-to-all-files: + - '{docs/WEBSOCKET.md*,docs/examples/websocket*,docs/libcurl/curl_ws_*,docs/libcurl/libcurl-ws*,docs/libcurl/opts/CURLOPT_WS_*,include/curl/websockets.h,lib/ws.*,tests/http/clients/ws*,tests/http/test_20_websockets.py,tests/http/testenv/ws*}' Windows: -- all: - - changed-files: - - any-glob-to-all-files: - - '**/Makefile.mk' - - 'appveyor.yml' - - 'CMake/Platforms/WindowsCache.cmake' - - 'lib/*win32*' - - 'lib/curl_multibyte.*' - - 'lib/rename.*' - - 'lib/vtls/schannel*' - - 'm4/curl-schannel.m4' - - 'projects/**' - - 'src/tool_doswin.c' - - 'winbuild/**' - - 'libcurl.def' + - all: + - changed-files: + - any-glob-to-all-files: + - '{appveyor.*,CMake/Platforms/WindowsCache.cmake,lib/*win32*,lib/curl_multibyte.*,lib/rename.*,lib/vtls/schannel*,m4/curl-schannel.m4,projects/**,src/tool_doswin.c,winbuild/**,libcurl.def}' diff --git a/.github/scripts/badwords.pl b/.github/scripts/badwords.pl new file mode 100755 index 00000000000..ffebad94e9d --- /dev/null +++ b/.github/scripts/badwords.pl @@ -0,0 +1,67 @@ +#!/usr/bin/perl +# Copyright (C) Daniel Stenberg, , et al. +# +# SPDX-License-Identifier: curl +# +# bad[:=]correct +# +# If separator is '=', the string will be compared case sensitively. +# If separator is ':', the check is done case insensitively. +# +my $w; +while() { + chomp; + if($_ =~ /^#/) { + next; + } + if($_ =~ /^([^:=]*)([:=])(.*)/) { + my ($bad, $sep, $better)=($1, $2, $3); + push @w, $bad; + $alt{$bad} = $better; + if($sep eq "=") { + $exactcase{$bad} = 1; + } + } +} + +my $errors; + +sub file { + my ($f) = @_; + my $l = 0; + open(F, "<$f"); + while() { + my $in = $_; + $l++; + chomp $in; + if($in =~ /^ /) { + next; + } + # remove the link part + $in =~ s/(\[.*\])\(.*\)/$1/g; + # remove backticked texts + $in =~ s/\`.*\`//g; + foreach my $w (@w) { + my $case = $exactcase{$w}; + if(($in =~ /^(.*)$w/i && !$case) || + ($in =~ /^(.*)$w/ && $case) ) { + my $p = $1; + my $c = length($p)+1; + print STDERR "$f:$l:$c: error: found bad word \"$w\"\n"; + printf STDERR " %4d | $in\n", $l; + printf STDERR " | %*s^%s\n", length($p), " ", + "~" x (length($w)-1); + printf STDERR " maybe use \"%s\" instead?\n", $alt{$w}; + $errors++; + } + } + } + close(F); +} + +my @files = @ARGV; + +foreach my $each (@files) { + file($each); +} +exit $errors; diff --git a/.github/scripts/badwords.txt b/.github/scripts/badwords.txt new file mode 100644 index 00000000000..2942ce8d8a6 --- /dev/null +++ b/.github/scripts/badwords.txt @@ -0,0 +1,50 @@ +# Copyright (C) Daniel Stenberg, , et al. +# +# SPDX-License-Identifier: curl +# +back-end:backend +e-mail:email +run-time:runtime +set-up:setup +tool chain:toolchain +tool-chain:toolchain +wild-card:wildcard +wild card:wildcard +i'm:I am +you've:You have +they've:They have +they're:They are +should've:should have +don't:do not +could've:could have +doesn't:does not +isn't:is not + a html: an html + a http: an http + a ftp: an ftp + url =URL +internet\b=Internet +isation:ization +it's:it is +there's:there is +[^.]\. And: Rewrite it somehow? +^(And|So|But) = Rewrite it somehow? +\. But: Rewrite it somehow? +\. So : Rewrite without "so" ? + dir :directory +you'd:you would +you'll:you will +can't:cannot +that's:that is +web page:webpage +host name\b:hostname +host names\b:hostnames +file name\b:filename +file names\b:filenames +\buser name\b:username +\buser names\b:usernames +didn't:did not +doesn't:does not +won't:will not +couldn't:could not +\bwill\b:rewrite to present tense diff --git a/.github/scripts/cleancmd.pl b/.github/scripts/cleancmd.pl new file mode 100755 index 00000000000..fabcce23b98 --- /dev/null +++ b/.github/scripts/cleancmd.pl @@ -0,0 +1,54 @@ +#!/usr/bin/perl +# Copyright (C) Daniel Stenberg, , et al. +# +# SPDX-License-Identifier: curl +# +# Input: a cmdline docs markdown, it gets modfied *in place* +# +# The main purpose is to strip off the leading meta-data part, but also to +# clean up whatever else the spell checker might have a problem with that we +# still deem is fine. + +my $header = 1; +while(1) { + # set this if the markdown has no meta-data header to skip + if($ARGV[0] eq "--no-header") { + shift @ARGV; + $header = 0; + } + else { + last; + } +} + +my $f = $ARGV[0]; + +open(F, "<$f") or die; + +my $ignore = $header; +my $sepcount = 0; +my @out; +while() { + if(/^---/ && $header) { + if(++$sepcount == 2) { + $ignore = 0; + } + next; + } + next if($ignore); + + # strip out all long command line options + $_ =~ s/--[a-z0-9-]+//g; + + # strip out https URLs, we don't want them spellchecked + $_ =~ s!https://[a-z0-9\#_/.-]+!!gi; + + push @out, $_; +} +close(F); + +if(!$ignore) { + open(O, ">$f") or die; + print O @out; + close(O); +} diff --git a/.github/scripts/cleanspell.pl b/.github/scripts/cleanspell.pl index 329a9724038..9a0d79f588d 100755 --- a/.github/scripts/cleanspell.pl +++ b/.github/scripts/cleanspell.pl @@ -3,38 +3,31 @@ # # SPDX-License-Identifier: curl # -# Input: a libcurl nroff man page -# Output: the same file, minus the SYNOPSIS and the EXAMPLE sections +# Given: a libcurl curldown man page +# Outputs: the same file, minus the SYNOPSIS and the EXAMPLE sections # my $f = $ARGV[0]; -my $o = $ARGV[1]; open(F, "<$f") or die; -open(O, ">$o") or die; +my @out; my $ignore = 0; while() { - if($_ =~ /^.SH (SYNOPSIS|EXAMPLE|\"SEE ALSO\"|SEE ALSO)/) { + if($_ =~ /^# (SYNOPSIS|EXAMPLE)/) { $ignore = 1; } - elsif($ignore && ($_ =~ /^.SH/)) { + elsif($ignore && ($_ =~ /^# [A-Z]/)) { $ignore = 0; } elsif(!$ignore) { - # filter out mentioned CURLE_ names + # **bold** + $_ =~ s/\*\*(\S.*?)\*\*//g; + # *italics* + $_ =~ s/\*(\S.*?)\*//g; + $_ =~ s/CURL(M|SH|U|H)code//g; - $_ =~ s/CURL_(READ|WRITE)FUNC_[A-Z0-9_]*//g; - $_ =~ s/CURL_CSELECT_[A-Z0-9_]*//g; - $_ =~ s/CURL_DISABLE_[A-Z0-9_]*//g; - $_ =~ s/CURL_FORMADD_[A-Z0-9_]*//g; - $_ =~ s/CURL_HET_DEFAULT//g; - $_ =~ s/CURL_IPRESOLVE_[A-Z0-9_]*//g; - $_ =~ s/CURL_PROGRESSFUNC_CONTINUE//g; - $_ =~ s/CURL_REDIR_[A-Z0-9_]*//g; - $_ =~ s/CURL_RTSPREQ_[A-Z0-9_]*//g; - $_ =~ s/CURL_TIMECOND_[A-Z0-9_]*//g; - $_ =~ s/CURL_VERSION_[A-Z0-9_]*//g; + $_ =~ s/CURL_[A-Z0-9_]*//g; $_ =~ s/CURLALTSVC_[A-Z0-9_]*//g; $_ =~ s/CURLAUTH_[A-Z0-9_]*//g; $_ =~ s/CURLE_[A-Z0-9_]*//g; @@ -56,24 +49,38 @@ $_ =~ s/CURLPX_[A-Z0-9_]*//g; $_ =~ s/CURLSHE_[A-Z0-9_]*//g; $_ =~ s/CURLSHOPT_[A-Z0-9_]*//g; + $_ =~ s/CURLSSLOPT_[A-Z0-9_]*//g; $_ =~ s/CURLSSH_[A-Z0-9_]*//g; $_ =~ s/CURLSSLBACKEND_[A-Z0-9_]*//g; $_ =~ s/CURLU_[A-Z0-9_]*//g; + $_ =~ s/CURLUPART_[A-Z0-9_]*//g; + #$_ =~ s/\bCURLU\b//g; # stand-alone CURLU $_ =~ s/CURLUE_[A-Z0-9_]*//g; + $_ =~ s/CURLHE_[A-Z0-9_]*//g; + $_ =~ s/CURLWS_[A-Z0-9_]*//g; + $_ =~ s/CURLKH[A-Z0-9_]*//g; $_ =~ s/CURLUPART_[A-Z0-9_]*//g; $_ =~ s/CURLUSESSL_[A-Z0-9_]*//g; - $_ =~ s/curl_global_(init_mem|sslset|cleanup)//g; + $_ =~ s/CURLPAUSE_[A-Z0-9_]*//g; + $_ =~ s/CURLHSTS_[A-Z0-9_]*//g; + $_ =~ s/curl_global_([a-z_]*)//g; $_ =~ s/curl_(strequal|strnequal|formadd|waitfd|formget|getdate|formfree)//g; - $_ =~ s/curl_easy_(nextheader|duphandle)//g; - $_ =~ s/curl_multi_fdset//g; + $_ =~ s/curl_easy_([a-z]*)//g; + $_ =~ s/curl_multi_([a-z_]*)//g; $_ =~ s/curl_mime_(subparts|addpart|filedata|data_cb)//g; $_ =~ s/curl_ws_(send|recv|meta)//g; $_ =~ s/curl_url_(dup)//g; $_ =~ s/curl_pushheader_by(name|num)//g; $_ =~ s/libcurl-(env|ws)//g; - $_ =~ s/(^|\W)((tftp|https|http|ftp):\/\/[a-z0-9\-._~%:\/?\#\[\]\@!\$&'()*+,;=]+)//gi; - print O $_; + $_ =~ s/libcurl\\-(env|ws)//g; + $_ =~ s/(^|\W)((tftp|https|http|ftp):\/\/[a-z0-9\-._~%:\/?\#\[\]\@!\$&'()*+,;=\\]+)//gi; + push @out, $_; } } close(F); + +open(O, ">$f") or die; +for my $l (@out) { + print O $l; +} close(O); diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index 4bee9bf6001..050513c76f2 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -39,7 +39,9 @@ auth autobuild autobuilds Autoconf +autoconf Automake +automake Autotools autotools AVR @@ -50,6 +52,7 @@ backend backends backoff backticks +balancers Baratov basename bashrc @@ -83,6 +86,7 @@ CCC CDN CentOS CFLAGS +cflags CGI's CHACHA chacha @@ -110,8 +114,10 @@ cliget closesocket CMake cmake +CMake's cmake's CMakeLists +CNA CodeQL codeql CODESET @@ -138,10 +144,11 @@ cshrc CTRL cURL CURLcode +curldown CURLE CURLH -CURLINFO curlimages +CURLINFO curlrc curltest customizable @@ -161,8 +168,8 @@ deepcode DELE DER deselectable -Deserialized deserialization +Deserialized destructor detections dev @@ -279,12 +286,14 @@ GPL GPLed Greear groff +gsasl GSKit gskit GSS GSSAPI GTFO Guenter +GUIs Gunderson Gustafsson gzip @@ -350,11 +359,10 @@ interoperable interoperates IoT ipadOS +IPCXN IPFS -IPNS ipld -trustless -IPCXN +IPNS IPv IPv4 IPv4/6 @@ -420,6 +428,7 @@ libssh libSSH libssh2 Libtool +libtool libuv libWebSocket libz @@ -444,6 +453,8 @@ Makefile makefiles malloc mallocs +manpage +manpages maprintf Marek Mavrogiannopoulos @@ -790,6 +801,7 @@ Tekniska testability TFTP tftp +threadsafe Tizen TLS tlsv @@ -804,6 +816,7 @@ TPF TrackMemory transcode Tru +trustless Tse Tsujikawa TTL @@ -826,6 +839,7 @@ unencoded unencrypted unescape Unglobbed +Unicode UNICOS unix UnixSockets @@ -880,6 +894,7 @@ WB web page WebDAV WebOS +webpage WebSocket WEBSOCKET WHATWG diff --git a/.github/scripts/spellcheck.yaml b/.github/scripts/spellcheck.yaml index 4e4e13d48c1..97d5d33053a 100644 --- a/.github/scripts/spellcheck.yaml +++ b/.github/scripts/spellcheck.yaml @@ -4,29 +4,29 @@ # # Docs: https://github.com/UnicornGlobal/spellcheck-github-actions matrix: -- name: Markdown - expect_match: false - apsell: - mode: en - dictionary: - wordlists: - - wordlist.txt - output: wordlist.dic - encoding: utf-8 - pipeline: - - pyspelling.filters.markdown: - markdown_extensions: - - markdown.extensions.extra: - - pyspelling.filters.html: - comments: true - attributes: - - title - - alt - ignores: - - ':matches(code, pre)' - - 'code' - - 'pre' - - 'strong' - - 'em' - sources: - - '**/*.md|!docs/BINDINGS.md' + - name: Markdown + expect_match: false + apsell: + mode: en + dictionary: + wordlists: + - wordlist.txt + output: wordlist.dic + encoding: utf-8 + pipeline: + - pyspelling.filters.markdown: + markdown_extensions: + - markdown.extensions.extra: + - pyspelling.filters.html: + comments: true + attributes: + - title + - alt + ignores: + - ':matches(code, pre)' + - 'code' + - 'pre' + - 'strong' + - 'em' + sources: + - '**/*.md|!docs/BINDINGS.md|!docs/DISTROS.md' diff --git a/.github/scripts/verify-examples.pl b/.github/scripts/verify-examples.pl index ff275569e15..28d24595fff 100755 --- a/.github/scripts/verify-examples.pl +++ b/.github/scripts/verify-examples.pl @@ -26,6 +26,7 @@ my @files = @ARGV; my $cfile = "test.c"; my $check = "./scripts/checksrc.pl"; +my $error; if($files[0] eq "-h") { print "Usage: verify-synopsis [man pages]\n"; @@ -47,8 +48,9 @@ sub extract { my $syn = 0; my $l = 0; my $iline = 0; - open(F, "<$f"); - open(O, ">$cfile"); + my $fail = 0; + open(F, "<$f") or die "failed opening input file $f : $!"; + open(O, ">$cfile") or die "failed opening output file $cfile : $!"; print O "#include \n"; while() { $iline++; @@ -68,6 +70,15 @@ sub extract { if(/^.fi/) { last; } + if(/(?, et al. +# +# SPDX-License-Identifier: curl + +name: badwords + +on: + # Trigger the workflow on push or pull requests, but only for the + # master branch + push: + branches: + - master + - '*/ci' + pull_request: + branches: + - master + +jobs: + check: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + + - name: check + run: ./.github/scripts/badwords.pl < .github/scripts/badwords.txt docs/*.md docs/libcurl/*.md docs/libcurl/opts/*.md docs/cmdline-opts/*.md diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index f5f969491aa..f98e4da4271 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -7,35 +7,35 @@ name: CodeQL on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'docs/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'tests/data/**' - - 'winbuild/**' + - '**/*.md' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'docs/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'tests/data/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'docs/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'tests/data/**' - - 'winbuild/**' + - '**/*.md' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'docs/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'tests/data/**' + - 'winbuild/**' schedule: - cron: '0 0 * * 4' @@ -50,31 +50,31 @@ jobs: permissions: security-events: write steps: - - name: Checkout repository - uses: actions/checkout@v4 + - name: Checkout repository + uses: actions/checkout@v4 - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: github/codeql-action/init@v2 - with: - languages: cpp - queries: security-extended + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: cpp + queries: security-extended - # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). - # If this step fails, then you should remove it and run the build manually (see below) - - name: Autobuild - uses: github/codeql-action/autobuild@v2 + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below) + - name: Autobuild + uses: github/codeql-action/autobuild@v3 - # ℹ️ Command-line programs to run using the OS shell. - # 📚 https://git.io/JvXDl + # ℹ️ Command-line programs to run using the OS shell. + # 📚 https://git.io/JvXDl - # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines - # and modify them (or add more) to build your code if your project - # uses a compiled language + # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines + # and modify them (or add more) to build your code if your project + # uses a compiled language - #- run: | - # make bootstrap - # make release + # - run: | + # make bootstrap + # make release - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v2 + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index 405d63915ad..2b095dae75a 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -7,25 +7,25 @@ name: Codespell on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths: - - 'lib/**' - - 'src/**' - - 'include/**' + - 'lib/**' + - 'src/**' + - 'include/**' pull_request: branches: - - master - - 'lib/**' - - 'src/**' - - 'include/**' + - master + - 'lib/**' + - 'src/**' + - 'include/**' jobs: codespell: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: install run: | diff --git a/.github/workflows/configure-vs-cmake.yml b/.github/workflows/configure-vs-cmake.yml index 3131bc128e5..dc2273f7375 100644 --- a/.github/workflows/configure-vs-cmake.yml +++ b/.github/workflows/configure-vs-cmake.yml @@ -6,23 +6,23 @@ name: configure-vs-cmake on: push: branches: - - master + - master paths: - - '*.ac' - - '**/*.m4' - - '**/CMakeLists.txt' - - 'lib/curl_config.h.cmake' - - 'scripts/cmp-config.pl' + - '*.ac' + - '**/*.m4' + - '**/CMakeLists.txt' + - 'lib/curl_config.h.cmake' + - 'scripts/cmp-config.pl' pull_request: branches: - - master + - master paths: - - '*.ac' - - '**/*.m4' - - '**/CMakeLists.txt' - - 'lib/curl_config.h.cmake' - - 'scripts/cmp-config.pl' + - '*.ac' + - '**/*.m4' + - '**/CMakeLists.txt' + - 'lib/curl_config.h.cmake' + - 'scripts/cmp-config.pl' permissions: {} @@ -30,16 +30,16 @@ jobs: check: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v4 - - name: run configure --with-openssl - run: | - autoreconf -fi - ./configure --with-openssl + - name: run configure --with-openssl + run: | + autoreconf -fi + ./configure --with-openssl --without-libpsl - - name: run cmake - run: | - mkdir build && cd build && cmake .. + - name: run cmake + run: | + mkdir build && cd build && cmake .. - - name: compare generated curl_config.h files - run: ./scripts/cmp-config.pl lib/curl_config.h build/lib/curl_config.h + - name: compare generated curl_config.h files + run: ./scripts/cmp-config.pl lib/curl_config.h build/lib/curl_config.h diff --git a/.github/workflows/distcheck.yml b/.github/workflows/distcheck.yml index 26c4da2b887..15068b640b4 100644 --- a/.github/workflows/distcheck.yml +++ b/.github/workflows/distcheck.yml @@ -7,11 +7,11 @@ name: dist on: push: branches: - - master - - '*/ci' + - master + - '*/ci' pull_request: branches: - - master + - master concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} @@ -22,101 +22,101 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 30 steps: - - uses: actions/checkout@v4 - - - run: sudo apt-get purge -y curl libcurl4 libcurl4-doc - name: 'remove preinstalled curl libcurl4{-doc}' - - - run: autoreconf -fi - name: 'autoreconf' - - - run: ./configure --without-ssl - name: 'configure' - - - run: make V=1 && make V=1 clean - name: 'make and clean' - - - run: ./maketgz 99.98.97 - name: 'maketgz' - - - uses: actions/upload-artifact@v3 - with: - name: 'release-tgz' - path: 'curl-99.98.97.tar.gz' - - - run: | - echo "::stop-commands::$(uuidgen)" - tar xvf curl-99.98.97.tar.gz - pushd curl-99.98.97 - ./configure --prefix=$HOME/temp --without-ssl - make - make TFLAGS=1 test - make install - popd - # basic check of the installed files - bash scripts/installcheck.sh $HOME/temp - rm -rf curl-99.98.97 - name: 'verify in-tree configure build including install' + - uses: actions/checkout@v4 + + - run: sudo apt-get purge -y curl libcurl4 libcurl4-doc + name: 'remove preinstalled curl libcurl4{-doc}' + + - run: autoreconf -fi + name: 'autoreconf' + + - run: ./configure --without-ssl --without-libpsl + name: 'configure' + + - run: make V=1 && make V=1 clean + name: 'make and clean' + + - run: ./maketgz 99.98.97 + name: 'maketgz' + + - uses: actions/upload-artifact@v4 + with: + name: 'release-tgz' + path: 'curl-99.98.97.tar.gz' + + - run: | + echo "::stop-commands::$(uuidgen)" + tar xvf curl-99.98.97.tar.gz + pushd curl-99.98.97 + ./configure --prefix=$HOME/temp --without-ssl --without-libpsl + make + make test-ci + make install + popd + # basic check of the installed files + bash scripts/installcheck.sh $HOME/temp + rm -rf curl-99.98.97 + name: 'verify in-tree configure build including install' verify-out-of-tree-docs: runs-on: ubuntu-latest timeout-minutes: 30 needs: maketgz-and-verify-in-tree steps: - - uses: actions/download-artifact@v3 - with: - name: 'release-tgz' - - - run: | - echo "::stop-commands::$(uuidgen)" - tar xvf curl-99.98.97.tar.gz - touch curl-99.98.97/docs/{cmdline-opts,libcurl}/Makefile.inc - mkdir build - pushd build - ../curl-99.98.97/configure --without-ssl - make - make TFLAGS='-p 1 1139' test - popd - rm -rf build - rm -rf curl-99.98.97 - name: 'verify out-of-tree configure build including docs' + - uses: actions/download-artifact@v4 + with: + name: 'release-tgz' + + - run: | + echo "::stop-commands::$(uuidgen)" + tar xvf curl-99.98.97.tar.gz + touch curl-99.98.97/docs/{cmdline-opts,libcurl}/Makefile.inc + mkdir build + pushd build + ../curl-99.98.97/configure --without-ssl --without-libpsl + make + make test-ci + popd + rm -rf build + rm -rf curl-99.98.97 + name: 'verify out-of-tree configure build including docs' verify-out-of-tree-autotools-debug: runs-on: ubuntu-latest timeout-minutes: 30 needs: maketgz-and-verify-in-tree steps: - - uses: actions/download-artifact@v3 - with: - name: 'release-tgz' - - - run: | - echo "::stop-commands::$(uuidgen)" - tar xvf curl-99.98.97.tar.gz - pushd curl-99.98.97 - mkdir build - pushd build - ../configure --without-ssl --enable-debug "--prefix=${PWD}/pkg" - make -j3 - make -j3 TFLAGS=1279 test - make -j3 install - name: 'verify out-of-tree autotools debug build' + - uses: actions/download-artifact@v4 + with: + name: 'release-tgz' + + - run: | + echo "::stop-commands::$(uuidgen)" + tar xvf curl-99.98.97.tar.gz + pushd curl-99.98.97 + mkdir build + pushd build + ../configure --without-ssl --enable-debug "--prefix=${PWD}/pkg" --without-libpsl + make -j3 + make -j3 test-ci + make -j3 install + name: 'verify out-of-tree autotools debug build' verify-out-of-tree-cmake: runs-on: ubuntu-latest timeout-minutes: 30 needs: maketgz-and-verify-in-tree steps: - - uses: actions/download-artifact@v3 - with: - name: 'release-tgz' - - - run: | - echo "::stop-commands::$(uuidgen)" - tar xvf curl-99.98.97.tar.gz - pushd curl-99.98.97 - mkdir build - pushd build - cmake .. - make - name: 'verify out-of-tree cmake build' + - uses: actions/download-artifact@v4 + with: + name: 'release-tgz' + + - run: | + echo "::stop-commands::$(uuidgen)" + tar xvf curl-99.98.97.tar.gz + pushd curl-99.98.97 + mkdir build + pushd build + cmake .. + make + name: 'verify out-of-tree cmake build' diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index 695e0def979..247a1c0abe4 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -7,37 +7,37 @@ name: Fuzzer on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'tests/data/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'tests/data/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'tests/data/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'tests/data/**' + - 'winbuild/**' concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} diff --git a/.github/workflows/hacktoberfest-accepted.yml b/.github/workflows/hacktoberfest-accepted.yml index 6363d1c5117..3c4ecd87c4d 100644 --- a/.github/workflows/hacktoberfest-accepted.yml +++ b/.github/workflows/hacktoberfest-accepted.yml @@ -8,7 +8,7 @@ on: # this must not ever run on any other branch than master push: branches: - - master + - master concurrency: # this should not run in parallel, so just run one at a time diff --git a/.github/workflows/label.yml b/.github/workflows/label.yml index df841cf88c3..b874c31b51a 100644 --- a/.github/workflows/label.yml +++ b/.github/workflows/label.yml @@ -21,6 +21,6 @@ jobs: pull-requests: write steps: - - uses: actions/labeler@v5 - with: - repo-token: "${{ secrets.GITHUB_TOKEN }}" + - uses: actions/labeler@v5 + with: + repo-token: "${{ secrets.GITHUB_TOKEN }}" diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml index 2301e301919..ba92efabb41 100644 --- a/.github/workflows/linkcheck.yml +++ b/.github/workflows/linkcheck.yml @@ -7,17 +7,17 @@ name: Markdown links on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths: - - '.github/workflows/linkcheck.yml' - - '**.md' + - '.github/workflows/linkcheck.yml' + - '**.md' pull_request: branches: - - master + - master paths: - - '.github/workflows/linkcheck.yml' - - '**.md' + - '.github/workflows/linkcheck.yml' + - '**.md' concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} @@ -30,7 +30,12 @@ jobs: check: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: gaurav-nelson/github-action-markdown-link-check@v1 - with: - use-quiet-mode: 'yes' + - uses: actions/checkout@v4 + name: checkout + + - name: trim the cmdline docs markdown files + run: find docs/cmdline-opts -name "*.md" ! -name "_*" ! -name MANPAGE.md | xargs -n1 ./.github/scripts/cleancmd.pl + + - uses: gaurav-nelson/github-action-markdown-link-check@v1 + with: + use-quiet-mode: 'yes' diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index aaa8abc0254..b033340842b 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -7,31 +7,31 @@ name: Linux on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} @@ -44,11 +44,11 @@ env: bearssl-version: 0.6 libressl-version: v3.7.3 mbedtls-version: v3.5.0 - mod_h2-version: v2.0.25 + mod_h2-version: v2.0.26 msh3-version: v0.6.0 openssl3-version: openssl-3.1.3 quictls-version: 3.1.4+quic - rustls-version: v0.10.0 + rustls-version: v0.12.0 jobs: autotools: @@ -60,375 +60,383 @@ jobs: fail-fast: false matrix: build: - - name: bearssl - install_packages: zlib1g-dev valgrind - install_steps: bearssl pytest - configure: LDFLAGS="-Wl,-rpath,$HOME/bearssl/lib" --with-bearssl=$HOME/bearssl --enable-debug - singleuse: --unit - - - name: bearssl-clang - install_packages: zlib1g-dev clang - install_steps: bearssl - configure: CC=clang LDFLAGS="-Wl,-rpath,$HOME/bearssl/lib" --with-bearssl=$HOME/bearssl --enable-debug - singleuse: --unit - - - name: libressl - install_packages: zlib1g-dev valgrind - install_steps: libressl pytest - configure: LDFLAGS="-Wl,-rpath,$HOME/libressl/lib" --with-openssl=$HOME/libressl --enable-debug - singleuse: --unit - - - name: libressl-clang - install_packages: zlib1g-dev clang - install_steps: libressl - configure: CC=clang LDFLAGS="-Wl,-rpath,$HOME/libressl/lib" --with-openssl=$HOME/libressl --enable-debug - singleuse: --unit - - - name: mbedtls - install_packages: libnghttp2-dev valgrind - install_steps: mbedtls pytest - configure: LDFLAGS="-Wl,-rpath,$HOME/mbedtls/lib" --with-mbedtls=$HOME/mbedtls --enable-debug - singleuse: --unit - - - name: mbedtls-clang - install_packages: libnghttp2-dev clang - install_steps: mbedtls - configure: CC=clang LDFLAGS="-Wl,-rpath,$HOME/mbedtls/lib" --with-mbedtls=$HOME/mbedtls --enable-debug - singleuse: --unit - - - name: msh3 - install_packages: zlib1g-dev valgrind - install_steps: quictls msh3 - configure: LDFLAGS="-Wl,-rpath,$HOME/msh3/lib -Wl,-rpath,$HOME/quictls/lib" --with-msh3=$HOME/msh3 --with-openssl=$HOME/quictls --enable-debug - singleuse: --unit - - - name: openssl3 - install_packages: zlib1g-dev valgrind - install_steps: gcc-11 openssl3 pytest - configure: CFLAGS=-std=gnu89 LDFLAGS="-Wl,-rpath,$HOME/openssl3/lib64" --with-openssl=$HOME/openssl3 --enable-debug --enable-websockets - singleuse: --unit - - - name: openssl3-O3 - install_packages: zlib1g-dev valgrind - install_steps: gcc-11 openssl3 - configure: CFLAGS=-O3 LDFLAGS="-Wl,-rpath,$HOME/openssl3/lib64" --with-openssl=$HOME/openssl3 --enable-debug --enable-websockets - singleuse: --unit - - - name: openssl3-clang - install_packages: zlib1g-dev clang - install_steps: openssl3 - configure: CC=clang LDFLAGS="-Wl,-rpath,$HOME/openssl3/lib64" --with-openssl=$HOME/openssl3 --enable-debug --enable-websockets - singleuse: --unit - - - name: address-sanitizer - install_packages: zlib1g-dev libssh2-1-dev clang libssl-dev libubsan1 libasan8 libtsan2 - install_steps: pytest - configure: > - CC=clang - CFLAGS="-fsanitize=address,undefined,signed-integer-overflow -fno-sanitize-recover=undefined,integer -Wformat -Werror=format-security -Werror=array-bounds -g" - LDFLAGS="-fsanitize=address,undefined -fno-sanitize-recover=undefined,integer" - LIBS="-ldl -lubsan" - --with-openssl --enable-debug --enable-websockets - singleuse: --unit - - - name: memory-sanitizer - install_packages: clang - install_steps: - configure: > - CC=clang - CFLAGS="-fsanitize=memory -Wformat -Werror=format-security -Werror=array-bounds -g" - LDFLAGS="-fsanitize=memory" - LIBS="-ldl" - --without-ssl --without-zlib --without-brotli --without-zstd --without-libpsl --without-nghttp2 --enable-debug --enable-websocketsx - singleuse: --unit - - - name: event-based - install_packages: libssh-dev valgrind - configure: --enable-debug --disable-shared --disable-threaded-resolver --with-libssh --with-openssl - tflags: -n -e '!TLS-SRP' - singleuse: --unit - - - name: hyper - install_steps: rust hyper valgrind - configure: LDFLAGS="-Wl,-rpath,$HOME/hyper/target/debug" --with-openssl --with-hyper=$HOME/hyper --enable-debug --enable-websockets - singleuse: --unit - - - name: rustls - install_steps: rust rustls pytest valgrind - configure: --with-rustls=$HOME/rustls --enable-debug - singleuse: --unit - - - name: Intel compiler - without SSL - install_packages: zlib1g-dev valgrind - install_steps: intel - configure: CC=icc --enable-debug --without-ssl - singleuse: --unit - - - name: Intel compiler - OpenSSL - install_packages: zlib1g-dev libssl-dev valgrind - install_steps: intel - configure: CC=icc --enable-debug --with-openssl - singleuse: --unit - - - name: Slackware-openssl-with-gssapi-gcc - # These are essentially the same flags used to build the curl Slackware package - # https://ftpmirror.infania.net/slackware/slackware64-current/source/n/curl/curl.SlackBuild - configure: --with-openssl --with-libssh2 --with-gssapi --enable-ares --enable-static=no --without-ca-bundle --with-ca-path=/etc/ssl/certs - # Docker Hub image that `container-job` executes in - container: 'andy5995/slackware-build-essential:15.0' - - - name: Alpine MUSL - configure: --enable-debug --enable-websockets --with-ssl --with-libssh2 --with-libidn2 --with-gssapi --enable-ldap --with-libpsl - container: 'alpine:3.18' - singleuse: --unit + - name: bearssl + install_packages: zlib1g-dev valgrind + install_steps: bearssl pytest + configure: LDFLAGS="-Wl,-rpath,$HOME/bearssl/lib" --with-bearssl=$HOME/bearssl --enable-debug + singleuse: --unit + + - name: bearssl-clang + install_packages: zlib1g-dev clang + install_steps: bearssl + configure: CC=clang LDFLAGS="-Wl,-rpath,$HOME/bearssl/lib" --with-bearssl=$HOME/bearssl --enable-debug + singleuse: --unit + + - name: libressl + install_packages: zlib1g-dev valgrind + install_steps: libressl pytest + configure: LDFLAGS="-Wl,-rpath,$HOME/libressl/lib" --with-openssl=$HOME/libressl --enable-debug + singleuse: --unit + + - name: libressl-clang + install_packages: zlib1g-dev clang + install_steps: libressl + configure: CC=clang LDFLAGS="-Wl,-rpath,$HOME/libressl/lib" --with-openssl=$HOME/libressl --enable-debug + singleuse: --unit + + - name: mbedtls + install_packages: libnghttp2-dev valgrind + install_steps: mbedtls pytest + configure: LDFLAGS="-Wl,-rpath,$HOME/mbedtls/lib" --with-mbedtls=$HOME/mbedtls --enable-debug + singleuse: --unit + + - name: mbedtls-clang + install_packages: libnghttp2-dev clang + install_steps: mbedtls + configure: CC=clang LDFLAGS="-Wl,-rpath,$HOME/mbedtls/lib" --with-mbedtls=$HOME/mbedtls --enable-debug + singleuse: --unit + + - name: msh3 + install_packages: zlib1g-dev valgrind + install_steps: quictls msh3 + configure: LDFLAGS="-Wl,-rpath,$HOME/msh3/lib -Wl,-rpath,$HOME/quictls/lib" --with-msh3=$HOME/msh3 --with-openssl=$HOME/quictls --enable-debug + singleuse: --unit + + - name: openssl3 + install_packages: zlib1g-dev valgrind + install_steps: gcc-11 openssl3 pytest + configure: CFLAGS=-std=gnu89 LDFLAGS="-Wl,-rpath,$HOME/openssl3/lib" --with-openssl=$HOME/openssl3 --enable-debug --enable-websockets + singleuse: --unit + + - name: openssl3-O3 + install_packages: zlib1g-dev valgrind + install_steps: gcc-11 openssl3 + configure: CPPFLAGS=-DCURL_WARN_SIGN_CONVERSION CFLAGS=-O3 LDFLAGS="-Wl,-rpath,$HOME/openssl3/lib" --with-openssl=$HOME/openssl3 --enable-debug --enable-websockets + singleuse: --unit + + - name: openssl3-clang + install_packages: zlib1g-dev clang + install_steps: openssl3 + configure: CC=clang LDFLAGS="-Wl,-rpath,$HOME/openssl3/lib" --with-openssl=$HOME/openssl3 --enable-debug --enable-websockets + singleuse: --unit + + - name: address-sanitizer + install_packages: zlib1g-dev libssh2-1-dev clang libssl-dev libubsan1 libasan8 libtsan2 + install_steps: pytest + configure: > + CC=clang + CFLAGS="-fsanitize=address,undefined,signed-integer-overflow -fno-sanitize-recover=undefined,integer -Wformat -Werror=format-security -Werror=array-bounds -g" + LDFLAGS="-fsanitize=address,undefined -fno-sanitize-recover=undefined,integer" + LIBS="-ldl -lubsan" + --with-openssl --enable-debug --enable-websockets + singleuse: --unit + + - name: memory-sanitizer + install_packages: clang + install_steps: + configure: > + CC=clang + CFLAGS="-fsanitize=memory -Wformat -Werror=format-security -Werror=array-bounds -g" + LDFLAGS="-fsanitize=memory" + LIBS="-ldl" + --without-ssl --without-zlib --without-brotli --without-zstd --without-libpsl --without-nghttp2 --enable-debug --enable-websockets + singleuse: --unit + + - name: event-based + install_packages: libssh-dev valgrind + configure: --enable-debug --disable-shared --disable-threaded-resolver --with-libssh --with-openssl + tflags: -n -e '!TLS-SRP' + singleuse: --unit + + - name: hyper + install_steps: rust hyper valgrind + configure: LDFLAGS="-Wl,-rpath,$HOME/hyper/target/debug" --with-openssl --with-hyper=$HOME/hyper --enable-debug --enable-websockets + singleuse: --unit + + - name: rustls + install_steps: rust rustls pytest valgrind libpsl-dev + configure: --with-rustls=$HOME/rustls --enable-debug + singleuse: --unit + + - name: Intel compiler - without SSL + install_packages: zlib1g-dev valgrind + install_steps: intel + configure: CC=icc --enable-debug --without-ssl + singleuse: --unit + + - name: Intel compiler - OpenSSL + install_packages: zlib1g-dev libssl-dev valgrind + install_steps: intel + configure: CC=icc --enable-debug --with-openssl + singleuse: --unit + + - name: Slackware-openssl-with-gssapi-gcc + # These are essentially the same flags used to build the curl Slackware package + # https://ftpmirror.infania.net/slackware/slackware64-current/source/n/curl/curl.SlackBuild + configure: --with-openssl --with-libssh2 --with-gssapi --enable-ares --enable-static=no --without-ca-bundle --with-ca-path=/etc/ssl/certs + # Docker Hub image that `container-job` executes in + container: 'andy5995/slackware-build-essential:15.0' + + - name: Alpine MUSL + configure: --enable-debug --enable-websockets --with-ssl --with-libssh2 --with-libidn2 --with-gssapi --enable-ldap --with-libpsl + container: 'alpine:3.18' + singleuse: --unit steps: - - if: matrix.build.container == null - run: | - sudo apt-get update - sudo apt-get install libtool autoconf automake pkg-config stunnel4 libpsl-dev libbrotli-dev libzstd-dev ${{ matrix.build.install_packages }} - sudo python3 -m pip install impacket - name: 'install prereqs and impacket' - - - if: startsWith(matrix.build.container, 'alpine') - run: | - apk add --no-cache build-base autoconf automake libtool perl openssl-dev libssh2-dev zlib-dev brotli-dev zstd-dev libidn2-dev openldap-dev heimdal-dev libpsl-dev py3-impacket py3-asn1 py3-six py3-pycryptodomex perl-time-hires openssh stunnel sudo git - name: 'install dependencies' - - - uses: actions/checkout@v4 - - - if: contains(matrix.build.install_steps, 'gcc-11') - run: | - sudo add-apt-repository ppa:ubuntu-toolchain-r/ppa - sudo apt-get update - sudo apt-get install gcc-11 - sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100 - sudo update-alternatives --set gcc /usr/bin/gcc-11 - gcc --version - name: 'install gcc-11' - - - name: cache bearssl - if: contains(matrix.build.install_steps, 'bearssl') - uses: actions/cache@v3 - id: cache-bearssl - env: - cache-name: cache-bearssl - with: - path: /home/runner/bearssl - key: ${{ runner.os }}-build-${{ env.cache-name }}-bearssl-${{ env.bearssl-version }} - - - name: 'build bearssl' - if: contains(matrix.build.install_steps, 'bearssl') && steps.cache-bearssl.outputs.cache-hit != 'true' - run: | - curl -LOsSf --retry 6 --retry-connrefused --max-time 999 https://bearssl.org/bearssl-${{ env.bearssl-version }}.tar.gz - tar -xzf bearssl-${{ env.bearssl-version }}.tar.gz - cd bearssl-${{ env.bearssl-version }} - make - mkdir -p $HOME/bearssl/lib $HOME/bearssl/include - cp inc/*.h $HOME/bearssl/include - cp build/libbearssl.* $HOME/bearssl/lib - - - name: cache libressl - if: contains(matrix.build.install_steps, 'libressl') - uses: actions/cache@v3 - id: cache-libressl - env: - cache-name: cache-libressl - with: - path: /home/runner/libressl - key: ${{ runner.os }}-build-${{ env.cache-name }}-libressl-${{ env.libressl-version }} - - - name: 'build libressl' - if: contains(matrix.build.install_steps, 'libressl') && steps.cache-libressl.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b ${{ env.libressl-version }} https://github.com/libressl-portable/portable.git libressl-git - cd libressl-git - ./autogen.sh - ./configure --prefix=$HOME/libressl - make install - - - name: cache mbedtls - if: contains(matrix.build.install_steps, 'mbedtls') - uses: actions/cache@v3 - id: cache-mbedtls - env: - cache-name: cache-mbedtls - with: - path: /home/runner/mbedtls - key: ${{ runner.os }}-build-${{ env.cache-name }}-mbedtls-${{ env.mbedtls-version }} - - - name: 'build mbedtls' - if: contains(matrix.build.install_steps, 'mbedtls') && steps.cache-mbedtls.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b ${{ env.mbedtls-version }} https://github.com/ARMmbed/mbedtls - cd mbedtls - make DESTDIR=$HOME/mbedtls install - - - name: cache openssl3 - if: contains(matrix.build.install_steps, 'openssl3') - uses: actions/cache@v3 - id: cache-openssl3 - env: - cache-name: cache-openssl3 - with: - path: /home/runner/openssl3 - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.openssl3-version }} - - - name: 'install openssl3' - if: contains(matrix.build.install_steps, 'openssl3') && steps.cache-openssl3.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b ${{ env.openssl3-version }} https://github.com/openssl/openssl - cd openssl - ./config enable-tls1_3 --prefix=$HOME/openssl3 - make -j1 install_sw - - - name: cache quictls - if: contains(matrix.build.install_steps, 'quictls') - uses: actions/cache@v3 - id: cache-quictls - env: - cache-name: cache-quictls - with: - path: /home/runner/quictls - key: ${{ runner.os }}-build-${{ env.cache-name }}-quictls-${{ env.quictls-version }} - - - name: 'build quictls' - if: contains(matrix.build.install_steps, 'quictls') && steps.cache-quictls.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b openssl-${{ env.quictls-version }} https://github.com/quictls/openssl - cd openssl - ./config enable-tls1_3 --prefix=$HOME/quictls --libdir=$HOME/quictls/lib - make -j1 install_sw - - - name: cache msh3 - if: contains(matrix.build.install_steps, 'msh3') - uses: actions/cache@v3 - id: cache-msh3 - env: - cache-name: cache-msh3 - with: - path: /home/runner/msh3 - key: ${{ runner.os }}-build-${{ env.cache-name }}-msh3-${{ env.msh3-version }} - - - name: 'build msh3' - if: contains(matrix.build.install_steps, 'msh3') && steps.cache-msh3.outputs.cache-hit != 'true' - run: | - git clone --quiet -b ${{ env.msh3-version }} --depth=1 --recursive https://github.com/nibanks/msh3 - cd msh3 && mkdir build && cd build - cmake -G 'Unix Makefiles' -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=$HOME/msh3 .. - cmake --build . - cmake --install . - - - if: contains(matrix.build.install_steps, 'rust') - run: | - cd $HOME - curl -sSf --compressed https://sh.rustup.rs/ | sh -s -- -y - source $HOME/.cargo/env - rustup toolchain install nightly - name: 'install rust' - - - name: cache rustls - if: contains(matrix.build.install_steps, 'rustls') - uses: actions/cache@v3 - id: cache-rustls - env: - cache-name: cache-rustls - with: - path: /home/runner/rustls - key: ${{ runner.os }}-build-${{ env.cache-name }}-rustls-${{ env.rustls-version }} - - - name: 'build rustls' - if: contains(matrix.build.install_steps, 'rustls') && steps.cache-rustls.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b ${{ env.rustls-version }} --recursive https://github.com/rustls/rustls-ffi.git - cd rustls-ffi - make DESTDIR=$HOME/rustls install - - - if: contains(matrix.build.install_steps, 'hyper') - run: | - cd $HOME - git clone --quiet --depth=1 https://github.com/hyperium/hyper.git - cd $HOME/hyper - RUSTFLAGS="--cfg hyper_unstable_ffi" cargo +nightly rustc --features client,http1,http2,ffi -Z unstable-options --crate-type cdylib - echo "LD_LIBRARY_PATH=$HOME/hyper/target/debug:/usr/local/lib" >> $GITHUB_ENV - name: 'install hyper' - - - if: contains(matrix.build.install_steps, 'intel') - run: | - cd /tmp - curl -sSf --compressed https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB | sudo apt-key add - - sudo add-apt-repository "deb https://apt.repos.intel.com/oneapi all main" - sudo apt install --no-install-recommends intel-oneapi-compiler-dpcpp-cpp-and-cpp-classic - source /opt/intel/oneapi/setvars.sh - printenv >> $GITHUB_ENV - name: 'install Intel compilers' - - - if: contains(matrix.build.install_steps, 'pytest') - run: | - sudo apt-get install apache2 apache2-dev libnghttp2-dev - sudo python3 -m pip install -r tests/http/requirements.txt - name: 'install pytest and apach2-dev' - - - name: cache mod_h2 - if: contains(matrix.build.install_steps, 'pytest') - uses: actions/cache@v3 - id: cache-mod_h2 - env: - cache-name: cache-mod_h2 - with: - path: /home/runner/mod_h2 - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.mod_h2-version }} - - - name: 'build mod_h2' - if: contains(matrix.build.install_steps, 'pytest') && steps.cache-mod_h2.outputs.cache-hit != 'true' - run: | - cd $HOME - git clone --quiet --depth=1 -b ${{ env.mod_h2-version }} https://github.com/icing/mod_h2 - cd mod_h2 - autoreconf -fi - ./configure - make - - - name: 'install mod_h2' - if: contains(matrix.build.install_steps, 'pytest') - run: | - cd $HOME/mod_h2 - sudo make install - - - run: autoreconf -fi - name: 'autoreconf' - - - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} - name: 'configure' - - - run: make V=1 - name: 'make' - - - run: | - git config --global --add safe.directory "*" - ./scripts/singleuse.pl ${{ matrix.build.singleuse }} lib/.libs/libcurl.a - name: single-use function check - - - run: ./src/curl -V - name: 'check curl -V output' - - - run: make V=1 examples - name: 'make examples' - - - run: make V=1 -C tests - name: 'make tests' - - - run: make V=1 test-ci - name: 'run tests' - env: - TFLAGS: "${{ matrix.build.tflags }}" - - - if: contains(matrix.build.install_steps, 'pytest') - # run for `tests` directory, so pytest does not pick up any other - # packages we might have built here - run: - pytest -v tests - name: 'run pytest' - env: - TFLAGS: "${{ matrix.build.tflags }}" - CURL_CI: github + - if: matrix.build.container == null + run: | + sudo apt-get update + sudo apt-get install libtool autoconf automake pkg-config stunnel4 libpsl-dev libbrotli-dev libzstd-dev ${{ matrix.build.install_packages }} + sudo python3 -m pip install impacket + name: 'install prereqs and impacket' + + - if: startsWith(matrix.build.container, 'alpine') + run: | + apk add --no-cache build-base autoconf automake libtool perl openssl-dev libssh2-dev zlib-dev brotli-dev zstd-dev libidn2-dev openldap-dev heimdal-dev libpsl-dev py3-impacket py3-asn1 py3-six py3-pycryptodomex perl-time-hires openssh stunnel sudo git + name: 'install dependencies' + + - uses: actions/checkout@v4 + + - name: Fix kernel mmap rnd bits + # Asan in llvm 14 provided in ubuntu 22.04 is incompatible with + # high-entropy ASLR in much newer kernels that GitHub runners are + # using leading to random crashes: https://reviews.llvm.org/D148280 + # See https://github.com/actions/runner-images/issues/9491 + continue-on-error: true + run: sudo sysctl vm.mmap_rnd_bits=28 + + - if: contains(matrix.build.install_steps, 'gcc-11') + run: | + sudo add-apt-repository ppa:ubuntu-toolchain-r/ppa + sudo apt-get update + sudo apt-get install gcc-11 + sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100 + sudo update-alternatives --set gcc /usr/bin/gcc-11 + gcc --version + name: 'install gcc-11' + + - name: cache bearssl + if: contains(matrix.build.install_steps, 'bearssl') + uses: actions/cache@v4 + id: cache-bearssl + env: + cache-name: cache-bearssl + with: + path: /home/runner/bearssl + key: ${{ runner.os }}-build-${{ env.cache-name }}-bearssl-${{ env.bearssl-version }} + + - name: 'build bearssl' + if: contains(matrix.build.install_steps, 'bearssl') && steps.cache-bearssl.outputs.cache-hit != 'true' + run: | + curl -LOsSf --retry 6 --retry-connrefused --max-time 999 https://bearssl.org/bearssl-${{ env.bearssl-version }}.tar.gz + tar -xzf bearssl-${{ env.bearssl-version }}.tar.gz + cd bearssl-${{ env.bearssl-version }} + make + mkdir -p $HOME/bearssl/lib $HOME/bearssl/include + cp inc/*.h $HOME/bearssl/include + cp build/libbearssl.* $HOME/bearssl/lib + + - name: cache libressl + if: contains(matrix.build.install_steps, 'libressl') + uses: actions/cache@v4 + id: cache-libressl + env: + cache-name: cache-libressl + with: + path: /home/runner/libressl + key: ${{ runner.os }}-build-${{ env.cache-name }}-libressl-${{ env.libressl-version }} + + - name: 'build libressl' + if: contains(matrix.build.install_steps, 'libressl') && steps.cache-libressl.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b ${{ env.libressl-version }} https://github.com/libressl-portable/portable.git libressl-git + cd libressl-git + ./autogen.sh + ./configure --prefix=$HOME/libressl + make install + + - name: cache mbedtls + if: contains(matrix.build.install_steps, 'mbedtls') + uses: actions/cache@v4 + id: cache-mbedtls + env: + cache-name: cache-mbedtls + with: + path: /home/runner/mbedtls + key: ${{ runner.os }}-build-${{ env.cache-name }}-mbedtls-${{ env.mbedtls-version }} + + - name: 'build mbedtls' + if: contains(matrix.build.install_steps, 'mbedtls') && steps.cache-mbedtls.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b ${{ env.mbedtls-version }} https://github.com/ARMmbed/mbedtls + cd mbedtls + make DESTDIR=$HOME/mbedtls install + + - name: cache openssl3 + if: contains(matrix.build.install_steps, 'openssl3') + uses: actions/cache@v4 + id: cache-openssl3 + env: + cache-name: cache-openssl3 + with: + path: /home/runner/openssl3 + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.openssl3-version }} + + - name: 'install openssl3' + if: contains(matrix.build.install_steps, 'openssl3') && steps.cache-openssl3.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b ${{ env.openssl3-version }} https://github.com/openssl/openssl + cd openssl + ./config --prefix=$HOME/openssl3 --libdir=$HOME/openssl3/lib + make -j1 install_sw + + - name: cache quictls + if: contains(matrix.build.install_steps, 'quictls') + uses: actions/cache@v4 + id: cache-quictls + env: + cache-name: cache-quictls + with: + path: /home/runner/quictls + key: ${{ runner.os }}-build-${{ env.cache-name }}-quictls-${{ env.quictls-version }} + + - name: 'build quictls' + if: contains(matrix.build.install_steps, 'quictls') && steps.cache-quictls.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b openssl-${{ env.quictls-version }} https://github.com/quictls/openssl + cd openssl + ./config --prefix=$HOME/quictls --libdir=$HOME/quictls/lib + make -j1 install_sw + + - name: cache msh3 + if: contains(matrix.build.install_steps, 'msh3') + uses: actions/cache@v4 + id: cache-msh3 + env: + cache-name: cache-msh3 + with: + path: /home/runner/msh3 + key: ${{ runner.os }}-build-${{ env.cache-name }}-msh3-${{ env.msh3-version }} + + - name: 'build msh3' + if: contains(matrix.build.install_steps, 'msh3') && steps.cache-msh3.outputs.cache-hit != 'true' + run: | + git clone --quiet -b ${{ env.msh3-version }} --depth=1 --recursive https://github.com/nibanks/msh3 + cd msh3 && mkdir build && cd build + cmake -G 'Unix Makefiles' -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=$HOME/msh3 .. + cmake --build . + cmake --install . + + - if: contains(matrix.build.install_steps, 'rust') + run: | + cd $HOME + curl -sSf --compressed https://sh.rustup.rs/ | sh -s -- -y + source $HOME/.cargo/env + rustup toolchain install nightly + name: 'install rust' + + - name: cache rustls + if: contains(matrix.build.install_steps, 'rustls') + uses: actions/cache@v4 + id: cache-rustls + env: + cache-name: cache-rustls + with: + path: /home/runner/rustls + key: ${{ runner.os }}-build-${{ env.cache-name }}-rustls-${{ env.rustls-version }} + + - name: 'build rustls' + if: contains(matrix.build.install_steps, 'rustls') && steps.cache-rustls.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b ${{ env.rustls-version }} --recursive https://github.com/rustls/rustls-ffi.git + cd rustls-ffi + make DESTDIR=$HOME/rustls install + + - if: contains(matrix.build.install_steps, 'hyper') + run: | + cd $HOME + git clone --quiet --depth=1 https://github.com/hyperium/hyper.git + cd $HOME/hyper + RUSTFLAGS="--cfg hyper_unstable_ffi" cargo +nightly rustc --features client,http1,http2,ffi -Z unstable-options --crate-type cdylib + echo "LD_LIBRARY_PATH=$HOME/hyper/target/debug:/usr/local/lib" >> $GITHUB_ENV + name: 'install hyper' + + - if: contains(matrix.build.install_steps, 'intel') + run: | + cd /tmp + curl -sSf --compressed https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB | sudo apt-key add - + sudo add-apt-repository "deb https://apt.repos.intel.com/oneapi all main" + sudo apt install --no-install-recommends intel-oneapi-compiler-dpcpp-cpp-and-cpp-classic + source /opt/intel/oneapi/setvars.sh + printenv >> $GITHUB_ENV + name: 'install Intel compilers' + + - if: contains(matrix.build.install_steps, 'pytest') + run: | + sudo apt-get install apache2 apache2-dev libnghttp2-dev + sudo python3 -m pip install -r tests/http/requirements.txt + name: 'install pytest and apach2-dev' + + - name: cache mod_h2 + if: contains(matrix.build.install_steps, 'pytest') + uses: actions/cache@v4 + id: cache-mod_h2 + env: + cache-name: cache-mod_h2 + with: + path: /home/runner/mod_h2 + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.mod_h2-version }} + + - name: 'build mod_h2' + if: contains(matrix.build.install_steps, 'pytest') && steps.cache-mod_h2.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b ${{ env.mod_h2-version }} https://github.com/icing/mod_h2 + cd mod_h2 + autoreconf -fi + ./configure + make + + - name: 'install mod_h2' + if: contains(matrix.build.install_steps, 'pytest') + run: | + cd $HOME/mod_h2 + sudo make install + + - run: autoreconf -fi + name: 'autoreconf' + + - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} + name: 'configure' + + - run: make V=1 + name: 'make' + + - run: | + git config --global --add safe.directory "*" + ./scripts/singleuse.pl ${{ matrix.build.singleuse }} lib/.libs/libcurl.a + name: single-use function check + + - run: ./src/curl -V + name: 'check curl -V output' + + - run: make V=1 examples + name: 'make examples' + + - run: make V=1 -C tests + name: 'make tests' + + - run: make V=1 test-ci + name: 'run tests' + env: + TFLAGS: "${{ matrix.build.tflags }}" + + - if: contains(matrix.build.install_steps, 'pytest') + # run for `tests` directory, so pytest does not pick up any other + # packages we might have built here + run: + pytest -v tests + name: 'run pytest' + env: + TFLAGS: "${{ matrix.build.tflags }}" + CURL_CI: github diff --git a/.github/workflows/linux32.yml b/.github/workflows/linux32.yml index 7c2d4cbf6ab..e3fca3d1d20 100644 --- a/.github/workflows/linux32.yml +++ b/.github/workflows/linux32.yml @@ -7,35 +7,35 @@ name: Linux 32-bit on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} @@ -55,39 +55,39 @@ jobs: fail-fast: false matrix: build: - - name: Linux i686 - install_packages: gcc-11-i686-linux-gnu libssl-dev:i386 zlib1g-dev:i386 libpsl-dev:i386 libbrotli-dev:i386 libzstd-dev:i386 - configure: --enable-debug --enable-websockets --with-openssl --host=i686-linux-gnu CC=i686-linux-gnu-gcc-11 PKG_CONFIG_PATH=/usr/lib/i386-linux-gnu/pkgconfig CPPFLAGS=-I/usr/include/i386-linux-gnu LDFLAGS=-L/usr/lib/i386-linux-gnu + - name: Linux i686 + install_packages: gcc-11-i686-linux-gnu libssl-dev:i386 zlib1g-dev:i386 libpsl-dev:i386 libbrotli-dev:i386 libzstd-dev:i386 + configure: --enable-debug --enable-websockets --with-openssl --host=i686-linux-gnu CC=i686-linux-gnu-gcc-11 PKG_CONFIG_PATH=/usr/lib/i386-linux-gnu/pkgconfig CPPFLAGS=-I/usr/include/i386-linux-gnu LDFLAGS=-L/usr/lib/i386-linux-gnu steps: - - run: | - sudo dpkg --add-architecture i386 - sudo apt-get update -y - sudo apt-get install -y --no-install-suggests --no-install-recommends libtool autoconf automake pkg-config stunnel4 ${{ matrix.build.install_packages }} - sudo python3 -m pip install impacket - name: 'install prereqs' + - run: | + sudo dpkg --add-architecture i386 + sudo apt-get update -y + sudo apt-get install -y --no-install-suggests --no-install-recommends libtool autoconf automake pkg-config stunnel4 ${{ matrix.build.install_packages }} + sudo python3 -m pip install impacket + name: 'install prereqs' - - uses: actions/checkout@v4 + - uses: actions/checkout@v4 - - run: autoreconf -fi - name: 'autoreconf' + - run: autoreconf -fi + name: 'autoreconf' - - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} - name: 'configure' + - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} + name: 'configure' - - run: make V=1 - name: 'make' + - run: make V=1 + name: 'make' - - run: ./src/curl -V - name: 'check curl -V output' + - run: ./src/curl -V + name: 'check curl -V output' - - run: make V=1 examples - name: 'make examples' + - run: make V=1 examples + name: 'make examples' - - run: make V=1 -C tests - name: 'make tests' + - run: make V=1 -C tests + name: 'make tests' - - run: make V=1 test-ci - name: 'run tests' - env: - TFLAGS: "${{ matrix.build.tflags }}" + - run: make V=1 test-ci + name: 'run tests' + env: + TFLAGS: "${{ matrix.build.tflags }}" diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml index e565f20e66c..2f2d75397aa 100644 --- a/.github/workflows/macos.yml +++ b/.github/workflows/macos.yml @@ -7,31 +7,31 @@ name: macOS on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} @@ -52,141 +52,142 @@ jobs: fail-fast: false matrix: build: - - name: normal - install: nghttp2 - configure: --without-ssl --enable-websockets - macosx-version-min: 10.9 - - name: debug - install: nghttp2 - configure: --enable-debug --without-ssl --enable-websockets - macosx-version-min: 10.9 - - name: libssh2 - install: nghttp2 libssh2 - configure: --enable-debug --with-libssh2 --without-ssl --enable-websockets - macosx-version-min: 10.9 - - name: libssh-c-ares - install: openssl nghttp2 libssh - configure: --enable-debug --with-libssh --with-openssl=/usr/local/opt/openssl --enable-ares --enable-websockets - macosx-version-min: 10.9 - - name: libssh - install: openssl nghttp2 libssh - configure: --enable-debug --with-libssh --with-openssl=/usr/local/opt/openssl --enable-websockets - macosx-version-min: 10.9 - - name: c-ares - install: nghttp2 - configure: --enable-debug --enable-ares --without-ssl --enable-websockets - macosx-version-min: 10.9 - - name: HTTP only - install: nghttp2 - configure: | - --enable-debug \ - --enable-maintainer-mode \ - --disable-alt-svc \ - --disable-dict \ - --disable-file \ - --disable-ftp \ - --disable-gopher \ - --disable-imap \ - --disable-ldap \ - --disable-pop3 \ - --disable-rtmp \ - --disable-rtsp \ - --disable-scp \ - --disable-sftp \ - --disable-shared \ - --disable-smb \ - --disable-smtp \ - --disable-telnet \ - --disable-tftp \ - --disable-unix-sockets \ - --without-brotli \ - --without-gssapi \ - --without-libidn2 \ - --without-libpsl \ - --without-librtmp \ - --without-libssh2 \ - --without-nghttp2 \ - --without-ntlm-auth \ - --without-ssl \ - --without-zlib \ - --without-zstd - macosx-version-min: 10.15 - - name: SecureTransport http2 - install: nghttp2 - configure: --enable-debug --with-secure-transport --enable-websockets - macosx-version-min: 10.8 - - name: gcc SecureTransport - configure: CC=gcc-12 --enable-debug --with-secure-transport --enable-websockets - macosx-version-min: 10.8 - - name: OpenSSL http2 - install: nghttp2 openssl - configure: --enable-debug --with-openssl=/usr/local/opt/openssl --enable-websockets - macosx-version-min: 10.9 - - name: LibreSSL http2 - install: nghttp2 libressl - configure: --enable-debug --with-openssl=/usr/local/opt/libressl --enable-websockets - macosx-version-min: 10.9 - - name: torture - install: nghttp2 openssl - configure: --enable-debug --disable-shared --disable-threaded-resolver --with-openssl=/usr/local/opt/openssl --enable-websockets - tflags: -n -t --shallow=25 !FTP - macosx-version-min: 10.9 - - name: torture-ftp - install: nghttp2 openssl - configure: --enable-debug --disable-shared --disable-threaded-resolver --with-openssl=/usr/local/opt/openssl --enable-websockets - tflags: -n -t --shallow=20 FTP - macosx-version-min: 10.9 - - name: macOS 10.15 - install: nghttp2 libssh2 openssl - configure: --enable-debug --disable-ldap --with-openssl=/usr/local/opt/openssl --enable-websockets - macosx-version-min: 10.15 + - name: normal + install: nghttp2 + configure: --without-ssl --enable-websockets + macosx-version-min: 10.9 + - name: debug + install: nghttp2 + configure: --enable-debug --without-ssl --enable-websockets + macosx-version-min: 10.9 + - name: libssh2 + install: nghttp2 libssh2 + configure: --enable-debug --with-libssh2 --without-ssl --enable-websockets + macosx-version-min: 10.9 + - name: libssh-c-ares + install: openssl nghttp2 libssh + configure: --enable-debug --with-libssh --with-openssl=/usr/local/opt/openssl --enable-ares --enable-websockets + macosx-version-min: 10.9 + - name: libssh + install: openssl nghttp2 libssh + configure: --enable-debug --with-libssh --with-openssl=/usr/local/opt/openssl --enable-websockets + macosx-version-min: 10.9 + - name: c-ares + install: nghttp2 + configure: --enable-debug --enable-ares --without-ssl --enable-websockets + macosx-version-min: 10.9 + - name: HTTP only + install: nghttp2 + configure: | + --enable-debug \ + --enable-maintainer-mode \ + --disable-alt-svc \ + --disable-dict \ + --disable-file \ + --disable-ftp \ + --disable-gopher \ + --disable-imap \ + --disable-ldap \ + --disable-pop3 \ + --disable-rtmp \ + --disable-rtsp \ + --disable-scp \ + --disable-sftp \ + --disable-shared \ + --disable-smb \ + --disable-smtp \ + --disable-telnet \ + --disable-tftp \ + --disable-unix-sockets \ + --without-brotli \ + --without-gssapi \ + --without-libidn2 \ + --without-libpsl \ + --without-librtmp \ + --without-libssh2 \ + --without-nghttp2 \ + --without-ntlm-auth \ + --without-ssl \ + --without-zlib \ + --without-zstd + + macosx-version-min: 10.15 + - name: SecureTransport http2 + install: nghttp2 + configure: --enable-debug --with-secure-transport --enable-websockets + macosx-version-min: 10.8 + - name: gcc SecureTransport + configure: CC=gcc-12 --enable-debug --with-secure-transport --enable-websockets --without-libpsl + macosx-version-min: 10.8 + - name: OpenSSL http2 + install: nghttp2 openssl + configure: --enable-debug --with-openssl=/usr/local/opt/openssl --enable-websockets + macosx-version-min: 10.9 + - name: LibreSSL http2 + install: nghttp2 libressl + configure: --enable-debug --with-openssl=/usr/local/opt/libressl --enable-websockets + macosx-version-min: 10.9 + - name: torture + install: nghttp2 openssl + configure: --enable-debug --disable-shared --disable-threaded-resolver --with-openssl=/usr/local/opt/openssl --enable-websockets + tflags: -n -t --shallow=25 !FTP + macosx-version-min: 10.9 + - name: torture-ftp + install: nghttp2 openssl + configure: --enable-debug --disable-shared --disable-threaded-resolver --with-openssl=/usr/local/opt/openssl --enable-websockets + tflags: -n -t --shallow=20 FTP + macosx-version-min: 10.9 + - name: macOS 10.15 + install: nghttp2 libssh2 openssl + configure: --enable-debug --disable-ldap --with-openssl=/usr/local/opt/openssl --enable-websockets + macosx-version-min: 10.15 steps: - - run: echo libtool autoconf automake pkg-config ${{ matrix.build.install }} | xargs -Ix -n1 echo brew '"x"' > /tmp/Brewfile - name: 'brew bundle' + - run: echo libtool autoconf automake pkg-config libpsl ${{ matrix.build.install }} | xargs -Ix -n1 echo brew '"x"' > /tmp/Brewfile + name: 'brew bundle' - # Run this command with retries because of spurious failures seen - # while running the tests, for example - # https://github.com/curl/curl/runs/4095721123?check_suite_focus=true - - run: "while [[ $? == 0 ]]; do for i in 1 2 3; do brew update && brew bundle install --no-lock --file /tmp/Brewfile && break 2 || { echo Error: wait to try again; sleep 10; } done; false Too many retries; done" - name: 'brew install' + # Run this command with retries because of spurious failures seen + # while running the tests, for example + # https://github.com/curl/curl/runs/4095721123?check_suite_focus=true + - run: "while [[ $? == 0 ]]; do for i in 1 2 3; do brew update && brew bundle install --no-lock --file /tmp/Brewfile && break 2 || { echo Error: wait to try again; sleep 10; } done; false Too many retries; done" + name: 'brew install' - - run: | - case "${{ matrix.build.install }}" in - *openssl*) - ;; - *) - if test -d /usr/local/include/openssl; then - brew unlink openssl - fi;; - esac - name: 'brew unlink openssl' + - run: | + case "${{ matrix.build.install }}" in + *openssl*) + ;; + *) + if test -d /usr/local/include/openssl; then + brew unlink openssl + fi;; + esac + name: 'brew unlink openssl' - - run: python3 -m pip install impacket - name: 'pip3 install' + - run: python3 -m pip install impacket + name: 'pip3 install' - - uses: actions/checkout@v4 + - uses: actions/checkout@v4 - - run: autoreconf -fi - name: 'autoreconf' + - run: autoreconf -fi + name: 'autoreconf' - - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} - name: 'configure' - env: - CFLAGS: "-mmacosx-version-min=${{ matrix.build.macosx-version-min }}" + - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} + name: 'configure' + env: + CFLAGS: "-mmacosx-version-min=${{ matrix.build.macosx-version-min }}" - - run: make V=1 - name: 'make' + - run: make V=1 + name: 'make' - - run: make V=1 examples - name: 'make examples' + - run: make V=1 examples + name: 'make examples' - - run: make V=1 -C tests - name: 'make tests' + - run: make V=1 -C tests + name: 'make tests' - - run: make V=1 test-ci - name: 'run tests' - env: - TFLAGS: "${{ matrix.build.tflags }} ~1452" + - run: make V=1 test-ci + name: 'run tests' + env: + TFLAGS: "${{ matrix.build.tflags }} ~1452" cmake: name: cmake ${{ matrix.compiler.CC }} ${{ matrix.build.name }} @@ -196,47 +197,47 @@ jobs: fail-fast: false matrix: compiler: - - CC: clang - CXX: clang++ - CFLAGS: "-mmacosx-version-min=10.15 -Wno-deprecated-declarations" - - CC: gcc-12 - CXX: g++-12 - CFLAGS: "-mmacosx-version-min=10.15 -Wno-error=undef -Wno-error=conversion" + - CC: clang + CXX: clang++ + CFLAGS: "-mmacosx-version-min=10.15 -Wno-deprecated-declarations" + - CC: gcc-12 + CXX: g++-12 + CFLAGS: "-mmacosx-version-min=10.15 -Wno-error=undef -Wno-error=conversion" build: - - name: OpenSSL - install: nghttp2 openssl - generate: -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl -DCMAKE_OSX_DEPLOYMENT_TARGET=10.9 - - name: LibreSSL - install: nghttp2 libressl - generate: -DOPENSSL_ROOT_DIR=/usr/local/opt/libressl -DCURL_DISABLE_LDAP=ON -DCURL_DISABLE_LDAPS=ON -DCMAKE_UNITY_BUILD=ON - - name: libssh2 - install: nghttp2 openssl libssh2 - generate: -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl -DCURL_USE_LIBSSH2=ON -DBUILD_SHARED_LIBS=ON -DBUILD_STATIC_LIBS=ON - - name: GnuTLS - install: gnutls - generate: -DCURL_USE_GNUTLS=ON -DCURL_USE_OPENSSL=OFF -DCURL_DISABLE_LDAP=ON -DCURL_DISABLE_LDAPS=ON -DCMAKE_SHARED_LINKER_FLAGS=-L/usr/local/lib -DCMAKE_EXE_LINKER_FLAGS=-L/usr/local/lib + - name: OpenSSL + install: nghttp2 openssl + generate: -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl -DCMAKE_OSX_DEPLOYMENT_TARGET=10.9 + - name: LibreSSL + install: nghttp2 libressl + generate: -DOPENSSL_ROOT_DIR=/usr/local/opt/libressl -DCURL_DISABLE_LDAP=ON -DCURL_DISABLE_LDAPS=ON -DCMAKE_UNITY_BUILD=ON + - name: libssh2 + install: nghttp2 openssl libssh2 + generate: -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl -DCURL_USE_LIBSSH2=ON -DBUILD_SHARED_LIBS=ON -DBUILD_STATIC_LIBS=ON + - name: GnuTLS + install: gnutls + generate: -DCURL_USE_GNUTLS=ON -DCURL_USE_OPENSSL=OFF -DCURL_DISABLE_LDAP=ON -DCURL_DISABLE_LDAPS=ON -DCMAKE_SHARED_LINKER_FLAGS=-L/usr/local/lib -DCMAKE_EXE_LINKER_FLAGS=-L/usr/local/lib steps: - - run: echo libtool autoconf automake pkg-config ${{ matrix.build.install }} | xargs -Ix -n1 echo brew '"x"' > /tmp/Brewfile - name: 'brew bundle' - - - run: "while [[ $? == 0 ]]; do for i in 1 2 3; do brew update && brew bundle install --no-lock --file /tmp/Brewfile && break 2 || { echo Error: wait to try again; sleep 10; } done; false Too many retries; done" - name: 'brew install' - - - run: | - case "${{ matrix.build.install }}" in - *openssl*) - ;; - *) - if test -d /usr/local/include/openssl; then - brew unlink openssl - fi;; - esac - name: 'brew unlink openssl' - - - uses: actions/checkout@v4 - - - run: cmake -S. -Bbuild -DCURL_WERROR=ON -DPICKY_COMPILER=ON ${{ matrix.build.generate }} - name: 'cmake generate' - - - run: cmake --build build - name: 'cmake build' + - run: echo libtool autoconf automake pkg-config ${{ matrix.build.install }} | xargs -Ix -n1 echo brew '"x"' > /tmp/Brewfile + name: 'brew bundle' + + - run: "while [[ $? == 0 ]]; do for i in 1 2 3; do brew update && brew bundle install --no-lock --file /tmp/Brewfile && break 2 || { echo Error: wait to try again; sleep 10; } done; false Too many retries; done" + name: 'brew install' + + - run: | + case "${{ matrix.build.install }}" in + *openssl*) + ;; + *) + if test -d /usr/local/include/openssl; then + brew unlink openssl + fi;; + esac + name: 'brew unlink openssl' + + - uses: actions/checkout@v4 + + - run: cmake -S. -Bbuild -DCURL_WERROR=ON -DPICKY_COMPILER=ON ${{ matrix.build.generate }} + name: 'cmake generate' + + - run: cmake --build build + name: 'cmake build' diff --git a/.github/workflows/man-examples.yml b/.github/workflows/man-examples.yml index 126e989dcfc..6f0d1e8ae42 100644 --- a/.github/workflows/man-examples.yml +++ b/.github/workflows/man-examples.yml @@ -7,24 +7,29 @@ name: manpage examples on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths: - - 'docs/libcurl/curl_*.3' - - 'docs/libcurl/opts/*.3' + - 'docs/libcurl/curl_*.3' + - 'docs/libcurl/opts/*.3' + - '.github/scripts/verify-examples.pl' pull_request: branches: - - master + - master paths: - - 'docs/libcurl/curl_*.3' - - 'docs/libcurl/opts/*.3' + - 'docs/libcurl/curl_*.3' + - 'docs/libcurl/opts/*.3' + - '.github/scripts/verify-examples.pl' jobs: verify: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 + + - name: render nroff versions + run: autoreconf -fi && ./configure --without-ssl --without-libpsl && make -C docs - name: verify examples run: ./.github/scripts/verify-examples.pl docs/libcurl/curl*.3 docs/libcurl/opts/*.3 diff --git a/.github/workflows/ngtcp2-linux.yml b/.github/workflows/ngtcp2-linux.yml index e73eba8c148..19172b48fd4 100644 --- a/.github/workflows/ngtcp2-linux.yml +++ b/.github/workflows/ngtcp2-linux.yml @@ -7,35 +7,35 @@ name: ngtcp2-linux on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: # Hardcoded workflow filename as workflow name above is just Linux again @@ -47,12 +47,12 @@ permissions: {} env: MAKEFLAGS: -j 3 quictls-version: 3.1.4+quic - gnutls-version: 3.8.0 + gnutls-version: 3.8.3 wolfssl-version: master nghttp3-version: v1.1.0 - ngtcp2-version: v1.1.0 - nghttp2-version: v1.58.0 - mod_h2-version: v2.0.25 + ngtcp2-version: v1.2.0 + nghttp2-version: v1.59.0 + mod_h2-version: v2.0.26 jobs: autotools: @@ -63,208 +63,208 @@ jobs: fail-fast: false matrix: build: - - name: quictls - configure: >- - PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/nghttpx/lib" - --with-ngtcp2=$HOME/nghttpx --enable-warnings --enable-werror --enable-debug --disable-ntlm - --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" - --with-openssl=$HOME/nghttpx - - name: gnutls - configure: >- - PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/nghttpx/lib" - --with-ngtcp2=$HOME/nghttpx --enable-warnings --enable-werror --enable-debug - --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" - --with-gnutls=$HOME/nghttpx - - name: wolfssl - configure: >- - PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/nghttpx/lib" - --with-ngtcp2=$HOME/nghttpx --enable-warnings --enable-werror --enable-debug - --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" - --with-wolfssl=$HOME/nghttpx + - name: quictls + configure: >- + PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/nghttpx/lib" + --with-ngtcp2=$HOME/nghttpx --enable-warnings --enable-werror --enable-debug --disable-ntlm + --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" + --with-openssl=$HOME/nghttpx + - name: gnutls + configure: >- + PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/nghttpx/lib" + --with-ngtcp2=$HOME/nghttpx --enable-warnings --enable-werror --enable-debug + --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" + --with-gnutls=$HOME/nghttpx + - name: wolfssl + configure: >- + PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/nghttpx/lib" + --with-ngtcp2=$HOME/nghttpx --enable-warnings --enable-werror --enable-debug + --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" + --with-wolfssl=$HOME/nghttpx steps: - - run: | - sudo apt-get update - sudo apt-get install libtool autoconf automake pkg-config stunnel4 \ - libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libev-dev libc-ares-dev \ - nettle-dev libp11-kit-dev libtspi-dev libunistring-dev guile-2.2-dev libtasn1-bin \ - libtasn1-6-dev libidn2-0-dev gawk gperf libtss2-dev dns-root-data bison gtk-doc-tools \ - texinfo texlive texlive-extra-utils autopoint libev-dev \ - apache2 apache2-dev libnghttp2-dev - name: 'install prereqs and impacket, pytest, crypto, apache2' - - - name: cache quictls - uses: actions/cache@v3 - id: cache-quictls-no-deprecated - env: - cache-name: cache-quictls-no-deprecated - with: - path: /home/runner/quictls - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.quictls-version }} - - - if: steps.cache-quictls-no-deprecated.outputs.cache-hit != 'true' - run: | - cd $HOME - git clone --quiet --depth=1 -b openssl-${{ env.quictls-version }} https://github.com/quictls/openssl quictls - cd quictls - ./config no-deprecated --prefix=$HOME/nghttpx --libdir=$HOME/nghttpx/lib - make - name: 'build quictls' - - - run: | - cd $HOME/quictls - make -j1 install_sw - name: 'install quictls' - - - - name: cache gnutls - uses: actions/cache@v3 - id: cache-gnutls - env: - cache-name: cache-gnutls - with: - path: /home/runner/gnutls - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.gnutls-version }} - - - if: steps.cache-gnutls.outputs.cache-hit != 'true' - run: | - cd $HOME - git clone --quiet --depth=1 -b ${{ env.gnutls-version }} https://github.com/gnutls/gnutls.git - cd gnutls - ./bootstrap - ./configure --prefix=$HOME/nghttpx \ - PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/nghttpx/lib -L$HOME/nghttpx/lib" \ - --with-included-libtasn1 --with-included-unistring \ - --disable-guile --disable-doc --disable-tests --disable-tools - make - name: 'build gnutls' - - - run: | - cd $HOME/gnutls - make install - name: 'install gnutls' - - - - name: cache wolfssl - uses: actions/cache@v3 - id: cache-wolfssl - env: - cache-name: cache-wolfssl - with: - path: /home/runner/wolfssl - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.wolfssl-version }} - - - if: steps.cache-wolfssl.outputs.cache-hit != 'true' || ${{ env.wolfssl-version }} == 'master' - run: | - cd $HOME - rm -rf wolfssl - git clone --quiet --depth=1 -b ${{ env.wolfssl-version }} https://github.com/wolfSSL/wolfssl.git - cd wolfssl - ./autogen.sh - ./configure --enable-all --enable-quic --prefix=$HOME/nghttpx - make - name: 'build wolfssl' - - - run: | - cd $HOME/wolfssl - make install - name: 'install wolfssl' - - - - name: cache nghttp3 - uses: actions/cache@v3 - id: cache-nghttp3 - env: - cache-name: cache-nghttp3 - with: - path: /home/runner/nghttp3 - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.nghttp3-version }} - - - if: steps.cache-nghttp3.outputs.cache-hit != 'true' - run: | - cd $HOME - git clone --quiet --depth=1 -b ${{ env.nghttp3-version }} https://github.com/ngtcp2/nghttp3 - cd nghttp3 - autoreconf -fi - ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only - make - name: 'build nghttp3' - - - run: | - cd $HOME/nghttp3 - make install - name: 'install nghttp3' - - # depends on all other cached libs built so far - - run: | - git clone --quiet --depth=1 -b ${{ env.ngtcp2-version }} https://github.com/ngtcp2/ngtcp2 - cd ngtcp2 - autoreconf -fi - ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only --with-openssl --with-gnutls --with-wolfssl - make install - name: 'install ngtcp2' - - # depends on all other cached libs built so far - - run: | - git clone --quiet --depth=1 -b ${{ env.nghttp2-version }} https://github.com/nghttp2/nghttp2 - cd nghttp2 - autoreconf -fi - ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-http3 - make install - name: 'install nghttp2' - - - name: cache mod_h2 - uses: actions/cache@v3 - id: cache-mod_h2 - env: - cache-name: cache-mod_h2 - with: - path: /home/runner/mod_h2 - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.mod_h2-version }} - - - if: steps.cache-mod_h2.outputs.cache-hit != 'true' - run: | - cd $HOME - git clone --quiet --depth=1 -b ${{ env.mod_h2-version }} https://github.com/icing/mod_h2 - cd mod_h2 - autoreconf -fi - ./configure - make - name: 'build mod_h2' - - - run: | - cd $HOME/mod_h2 - sudo make install - name: 'install mod_h2' - - - uses: actions/checkout@v4 - - - run: | - sudo python3 -m pip install -r tests/requirements.txt -r tests/http/requirements.txt - name: 'install python test prereqs' - - - run: autoreconf -fi - name: 'autoreconf' - - - run: ./configure ${{ matrix.build.configure }} - name: 'configure' - - - run: make V=1 - name: 'make' - - - run: make V=1 examples - name: 'make examples' - - - run: make V=1 -C tests - name: 'make tests' - - - run: make V=1 test-ci - name: 'run tests' - env: - TFLAGS: "${{ matrix.build.tflags }}" - - - run: pytest -v tests - name: 'run pytest' - env: - TFLAGS: "${{ matrix.build.tflags }}" - CURL_CI: github + - run: | + sudo apt-get update + sudo apt-get install libtool autoconf automake pkg-config stunnel4 \ + libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libev-dev libc-ares-dev \ + nettle-dev libp11-kit-dev libtspi-dev libunistring-dev guile-2.2-dev libtasn1-bin \ + libtasn1-6-dev libidn2-0-dev gawk gperf libtss2-dev dns-root-data bison gtk-doc-tools \ + texinfo texlive texlive-extra-utils autopoint libev-dev \ + apache2 apache2-dev libnghttp2-dev + name: 'install prereqs and impacket, pytest, crypto, apache2' + + - name: cache quictls + uses: actions/cache@v4 + id: cache-quictls-no-deprecated + env: + cache-name: cache-quictls-no-deprecated + with: + path: /home/runner/quictls + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.quictls-version }} + + - if: steps.cache-quictls-no-deprecated.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b openssl-${{ env.quictls-version }} https://github.com/quictls/openssl quictls + cd quictls + ./config no-deprecated --prefix=$HOME/nghttpx --libdir=$HOME/nghttpx/lib + make + name: 'build quictls' + + - run: | + cd $HOME/quictls + make -j1 install_sw + name: 'install quictls' + + + - name: cache gnutls + uses: actions/cache@v4 + id: cache-gnutls + env: + cache-name: cache-gnutls + with: + path: /home/runner/gnutls + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.gnutls-version }} + + - if: steps.cache-gnutls.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b ${{ env.gnutls-version }} https://github.com/gnutls/gnutls.git + cd gnutls + ./bootstrap + ./configure --prefix=$HOME/nghttpx \ + PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/nghttpx/lib -L$HOME/nghttpx/lib" \ + --with-included-libtasn1 --with-included-unistring \ + --disable-guile --disable-doc --disable-tests --disable-tools + make + name: 'build gnutls' + + - run: | + cd $HOME/gnutls + make install + name: 'install gnutls' + + + - name: cache wolfssl + uses: actions/cache@v4 + id: cache-wolfssl + env: + cache-name: cache-wolfssl + with: + path: /home/runner/wolfssl + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.wolfssl-version }} + + - if: steps.cache-wolfssl.outputs.cache-hit != 'true' || ${{ env.wolfssl-version }} == 'master' + run: | + cd $HOME + rm -rf wolfssl + git clone --quiet --depth=1 -b ${{ env.wolfssl-version }} https://github.com/wolfSSL/wolfssl.git + cd wolfssl + ./autogen.sh + ./configure --enable-all --enable-quic --prefix=$HOME/nghttpx + make + name: 'build wolfssl' + + - run: | + cd $HOME/wolfssl + make install + name: 'install wolfssl' + + + - name: cache nghttp3 + uses: actions/cache@v4 + id: cache-nghttp3 + env: + cache-name: cache-nghttp3 + with: + path: /home/runner/nghttp3 + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.nghttp3-version }} + + - if: steps.cache-nghttp3.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b ${{ env.nghttp3-version }} https://github.com/ngtcp2/nghttp3 + cd nghttp3 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only + make + name: 'build nghttp3' + + - run: | + cd $HOME/nghttp3 + make install + name: 'install nghttp3' + + # depends on all other cached libs built so far + - run: | + git clone --quiet --depth=1 -b ${{ env.ngtcp2-version }} https://github.com/ngtcp2/ngtcp2 + cd ngtcp2 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only --with-openssl --with-gnutls --with-wolfssl + make install + name: 'install ngtcp2' + + # depends on all other cached libs built so far + - run: | + git clone --quiet --depth=1 -b ${{ env.nghttp2-version }} https://github.com/nghttp2/nghttp2 + cd nghttp2 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-http3 + make install + name: 'install nghttp2' + + - name: cache mod_h2 + uses: actions/cache@v4 + id: cache-mod_h2 + env: + cache-name: cache-mod_h2 + with: + path: /home/runner/mod_h2 + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.mod_h2-version }} + + - if: steps.cache-mod_h2.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b ${{ env.mod_h2-version }} https://github.com/icing/mod_h2 + cd mod_h2 + autoreconf -fi + ./configure + make + name: 'build mod_h2' + + - run: | + cd $HOME/mod_h2 + sudo make install + name: 'install mod_h2' + + - uses: actions/checkout@v4 + + - run: | + sudo python3 -m pip install -r tests/requirements.txt -r tests/http/requirements.txt + name: 'install python test prereqs' + + - run: autoreconf -fi + name: 'autoreconf' + + - run: ./configure ${{ matrix.build.configure }} + name: 'configure' + + - run: make V=1 + name: 'make' + + - run: make V=1 examples + name: 'make examples' + + - run: make V=1 -C tests + name: 'make tests' + + - run: make V=1 test-ci + name: 'run tests' + env: + TFLAGS: "${{ matrix.build.tflags }}" + + - run: pytest -v tests + name: 'run pytest' + env: + TFLAGS: "${{ matrix.build.tflags }}" + CURL_CI: github diff --git a/.github/workflows/osslq-linux.yml b/.github/workflows/osslq-linux.yml new file mode 100644 index 00000000000..a15e28ccecf --- /dev/null +++ b/.github/workflows/osslq-linux.yml @@ -0,0 +1,233 @@ +# Copyright (C) Daniel Stenberg, , et al. +# +# SPDX-License-Identifier: curl + +name: osslq-linux + +on: + push: + branches: + - master + - '*/ci' + paths-ignore: + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' + pull_request: + branches: + - master + paths-ignore: + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' + +concurrency: + # Hardcoded workflow filename as workflow name above is just Linux again + group: osslq-${{ github.event.pull_request.number || github.sha }} + cancel-in-progress: true + +permissions: {} + +env: + MAKEFLAGS: -j 3 + openssl3-version: openssl-3.2.0 + quictls-version: 3.1.4+quic + nghttp3-version: v1.1.0 + ngtcp2-version: v1.2.0 + nghttp2-version: v1.59.0 + mod_h2-version: v2.0.26 + +jobs: + autotools: + name: ${{ matrix.build.name }} + runs-on: 'ubuntu-latest' + timeout-minutes: 60 + strategy: + fail-fast: false + matrix: + build: + - name: openssl-quic + configure: >- + PKG_CONFIG_PATH="$HOME/openssl3/lib/pkgconfig" LDFLAGS="-Wl,-rpath,$HOME/openssl3/lib" + --enable-warnings --enable-werror --enable-debug --disable-ntlm + --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" + --with-openssl=$HOME/openssl3 --with-openssl-quic + --with-nghttp3=$HOME/nghttpx + + steps: + - run: | + sudo apt-get update + sudo apt-get install libtool autoconf automake pkg-config stunnel4 \ + libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libev-dev libc-ares-dev \ + nettle-dev libp11-kit-dev libtspi-dev libunistring-dev guile-2.2-dev libtasn1-bin \ + libtasn1-6-dev libidn2-0-dev gawk gperf libtss2-dev dns-root-data bison gtk-doc-tools \ + texinfo texlive texlive-extra-utils autopoint libev-dev \ + apache2 apache2-dev libnghttp2-dev + name: 'install prereqs and impacket, pytest, crypto, apache2' + + - name: cache openssl3 + if: contains(matrix.build.install_steps, 'openssl3') + uses: actions/cache@v4 + id: cache-openssl3 + env: + cache-name: cache-openssl3 + with: + path: /home/runner/openssl3 + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.openssl3-version }} + + - name: 'install openssl3' + if: steps.cache-openssl3.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b ${{ env.openssl3-version }} https://github.com/openssl/openssl + cd openssl + ./config --prefix=$HOME/openssl3 --libdir=$HOME/openssl3/lib + make -j1 install_sw + + - name: cache quictls + if: contains(matrix.build.install_steps, 'quictls') + uses: actions/cache@v4 + id: cache-quictls + env: + cache-name: cache-quictls + with: + path: /home/runner/quictls + key: ${{ runner.os }}-build-${{ env.cache-name }}-quictls-${{ env.quictls-version }} + + - name: cache quictls + uses: actions/cache@v4 + id: cache-quictls-no-deprecated + env: + cache-name: cache-quictls-no-deprecated + with: + path: /home/runner/quictls + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.quictls-version }} + + - if: steps.cache-quictls-no-deprecated.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b openssl-${{ env.quictls-version }} https://github.com/quictls/openssl quictls + cd quictls + ./config no-deprecated --prefix=$HOME/nghttpx --libdir=$HOME/nghttpx/lib + make + name: 'build quictls' + + - run: | + cd $HOME/quictls + make -j1 install_sw + name: 'install quictls' + + + - name: cache nghttp3 + uses: actions/cache@v4 + id: cache-nghttp3 + env: + cache-name: cache-nghttp3 + with: + path: /home/runner/nghttp3 + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.nghttp3-version }} + + - if: steps.cache-nghttp3.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b ${{ env.nghttp3-version }} https://github.com/ngtcp2/nghttp3 + cd nghttp3 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only + make + name: 'build nghttp3' + + - run: | + cd $HOME/nghttp3 + make install + name: 'install nghttp3' + + # depends on all other cached libs built so far + - run: | + git clone --quiet --depth=1 -b ${{ env.ngtcp2-version }} https://github.com/ngtcp2/ngtcp2 + cd ngtcp2 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only --with-openssl + make install + name: 'install ngtcp2' + + # depends on all other cached libs built so far + - run: | + git clone --quiet --depth=1 -b ${{ env.nghttp2-version }} https://github.com/nghttp2/nghttp2 + cd nghttp2 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-http3 + make install + name: 'install nghttp2' + + - name: cache mod_h2 + uses: actions/cache@v4 + id: cache-mod_h2 + env: + cache-name: cache-mod_h2 + with: + path: /home/runner/mod_h2 + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.mod_h2-version }} + + - if: steps.cache-mod_h2.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b ${{ env.mod_h2-version }} https://github.com/icing/mod_h2 + cd mod_h2 + autoreconf -fi + ./configure + make + name: 'build mod_h2' + + - run: | + cd $HOME/mod_h2 + sudo make install + name: 'install mod_h2' + + - uses: actions/checkout@v4 + + - run: | + sudo python3 -m pip install -r tests/requirements.txt -r tests/http/requirements.txt + name: 'install python test prereqs' + + - run: autoreconf -fi + name: 'autoreconf' + + - run: ./configure ${{ matrix.build.configure }} + name: 'configure' + + - run: make V=1 + name: 'make' + + - run: make V=1 examples + name: 'make examples' + + - run: make V=1 -C tests + name: 'make tests' + + - run: make V=1 test-ci + name: 'run tests' + env: + # 2500 and 25002 fail atm due to fin handling + TFLAGS: "!http/3" + + - run: pytest -v tests + name: 'run pytest' + env: + TFLAGS: "${{ matrix.build.tflags }}" + CURL_CI: github diff --git a/.github/workflows/proselint.yml b/.github/workflows/proselint.yml index b01133c3b8c..4a0ae6f1f49 100644 --- a/.github/workflows/proselint.yml +++ b/.github/workflows/proselint.yml @@ -7,17 +7,17 @@ name: proselint on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths: - - '.github/workflows/proselint.yml' - - '**.md' + - '.github/workflows/proselint.yml' + - '**.md' pull_request: branches: - - master + - master paths: - - '.github/workflows/proselint.yml' - - '**.md' + - '.github/workflows/proselint.yml' + - '**.md' concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} @@ -29,40 +29,41 @@ jobs: check: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v4 - - name: install prereqs - run: sudo apt-get install python3-proselint + - name: install prereqs + run: sudo apt-get install python3-proselint - # config file help: https://github.com/amperser/proselint/ - - name: create proselint config - run: | - cat < $HOME/.proselintrc - { - "checks": { - "typography.diacritical_marks": false, - "typography.symbols": false, - "annotations.misc": false + # config file help: https://github.com/amperser/proselint/ + - name: create proselint config + run: | + cat < $HOME/.proselintrc + { + "checks": { + "typography.diacritical_marks": false, + "typography.symbols": false, + "annotations.misc": false, + "security.password": false + } } - } - JSON + JSON - - name: check prose - run: a=`git ls-files '*.md' | grep -v docs/CHECKSRC.md` && proselint $a README + - name: check prose + run: a=`git ls-files '*.md' | grep -Ev '(docs/CHECKSRC.md|docs/DISTROS.md)'` && proselint $a README - # This is for CHECKSRC and files with aggressive exclamation mark needs - - name: create second proselint config - run: | - cat < $HOME/.proselintrc - { - "checks": { - "typography.diacritical_marks": false, - "typography.symbols": false, - "typography.exclamation": false, - "annotations.misc": false + # This is for CHECKSRC and files with aggressive exclamation mark needs + - name: create second proselint config + run: | + cat < $HOME/.proselintrc + { + "checks": { + "typography.diacritical_marks": false, + "typography.symbols": false, + "typography.exclamation": false, + "annotations.misc": false + } } - } - JSON + JSON - - name: check special prose - run: a=docs/CHECKSRC.md && proselint $a + - name: check special prose + run: a=docs/CHECKSRC.md && proselint $a diff --git a/.github/workflows/quiche-linux.yml b/.github/workflows/quiche-linux.yml index 9d43d42df7c..40fc4d580d4 100644 --- a/.github/workflows/quiche-linux.yml +++ b/.github/workflows/quiche-linux.yml @@ -7,35 +7,35 @@ name: quiche on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: # Hardcoded workflow filename as workflow name above is just Linux again @@ -48,10 +48,10 @@ env: MAKEFLAGS: -j 3 openssl-version: 3.1.4+quic nghttp3-version: v1.1.0 - ngtcp2-version: v1.1.0 - nghttp2-version: v1.58.0 - quiche-version: 0.19.0 - mod_h2-version: v2.0.25 + ngtcp2-version: v1.2.0 + nghttp2-version: v1.59.0 + quiche-version: 0.20.0 + mod_h2-version: v2.0.26 jobs: autotools: @@ -62,149 +62,149 @@ jobs: fail-fast: false matrix: build: - - name: quiche - install: >- - libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libev-dev libc-ares-dev - install_steps: pytest - configure: >- - LDFLAGS="-Wl,-rpath,/home/runner/quiche/target/release" - --with-openssl=/home/runner/quiche/quiche/deps/boringssl/src - --enable-debug - --with-quiche=/home/runner/quiche/target/release - --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" - --with-ca-fallback + - name: quiche + install: >- + libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libev-dev libc-ares-dev + install_steps: pytest + configure: >- + LDFLAGS="-Wl,-rpath,/home/runner/quiche/target/release" + --with-openssl=/home/runner/quiche/quiche/deps/boringssl/src + --enable-debug + --with-quiche=/home/runner/quiche/target/release + --with-test-nghttpx="$HOME/nghttpx/bin/nghttpx" + --with-ca-fallback steps: - - run: | - sudo apt-get update - sudo apt-get install libtool autoconf automake pkg-config stunnel4 ${{ matrix.build.install }} - sudo apt-get install apache2 apache2-dev libnghttp2-dev - name: 'install prereqs and impacket, pytest, crypto' - - - name: cache nghttpx - uses: actions/cache@v3 - id: cache-nghttpx - env: - cache-name: cache-nghttpx - with: - path: /home/runner/nghttpx - key: ${{ runner.os }}-build-${{ env.cache-name }}-openssl-${{ env.openssl-version }}-nghttp3-${{ env.nghttp3-version }}-ngtcp2-${{ env.ngtcp2-version }}-nghttp2-${{ env.nghttp2-version }} - - - if: steps.cache-nghttpx.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b openssl-${{ env.openssl-version }} https://github.com/quictls/openssl - cd openssl - ./config --prefix=$HOME/nghttpx --libdir=$HOME/nghttpx/lib - make -j1 install_sw - name: 'install quictls' - - - if: steps.cache-nghttpx.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b ${{ env.nghttp3-version }} https://github.com/ngtcp2/nghttp3 - cd nghttp3 - autoreconf -fi - ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only - make install - name: 'install nghttp3' - - - if: steps.cache-nghttpx.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b ${{ env.ngtcp2-version }} https://github.com/ngtcp2/ngtcp2 - cd ngtcp2 - autoreconf -fi - ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only --with-openssl - make install - name: 'install ngtcp2' - - - if: steps.cache-nghttpx.outputs.cache-hit != 'true' - run: | - git clone --quiet --depth=1 -b ${{ env.nghttp2-version }} https://github.com/nghttp2/nghttp2 - cd nghttp2 - autoreconf -fi - ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-http3 - make install - name: 'install nghttp2' - - - name: cache quiche - uses: actions/cache@v3 - id: cache-quiche - env: - cache-name: cache-quiche - with: - path: /home/runner/quiche - key: ${{ runner.os }}-build-${{ env.cache-name }}-quiche-${{ env.quiche-version }} - - - if: steps.cache-quiche.outputs.cache-hit != 'true' - run: | - cd $HOME - git clone --quiet --depth=1 -b ${{ env.quiche-version }} --recursive https://github.com/cloudflare/quiche.git - cd quiche - #### Work-around https://github.com/curl/curl/issues/7927 ####### - #### See https://github.com/alexcrichton/cmake-rs/issues/131 #### - sed -i -e 's/cmake = "0.1"/cmake = "=0.1.45"/' quiche/Cargo.toml - - cargo build -v --package quiche --release --features ffi,pkg-config-meta,qlog --verbose - mkdir -v quiche/deps/boringssl/src/lib - ln -vnf $(find target/release -name libcrypto.a -o -name libssl.a) quiche/deps/boringssl/src/lib/ - - # include dir - # /home/runner/quiche/quiche/deps/boringssl/src/include - # lib dir - # /home/runner/quiche/quiche/deps/boringssl/src/lib - name: 'build quiche and boringssl' - - - name: cache mod_h2 - uses: actions/cache@v3 - id: cache-mod_h2 - env: - cache-name: cache-mod_h2 - with: - path: /home/runner/mod_h2 - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.mod_h2-version }} - - - if: steps.cache-mod_h2.outputs.cache-hit != 'true' - run: | - cd $HOME - git clone --quiet --depth=1 -b ${{ env.mod_h2-version }} https://github.com/icing/mod_h2 - cd mod_h2 - autoreconf -fi - ./configure - make - name: 'build mod_h2' - - - run: | - cd $HOME/mod_h2 - sudo make install - name: 'install mod_h2' - - - uses: actions/checkout@v4 - - - run: | - sudo python3 -m pip install -r tests/requirements.txt -r tests/http/requirements.txt - name: 'install python test prereqs' - - - run: autoreconf -fi - name: 'autoreconf' - - - run: ./configure ${{ matrix.build.configure }} - name: 'configure' - - - run: make V=1 - name: 'make' - - - run: make V=1 examples - name: 'make examples' - - - run: make V=1 -C tests - name: 'make tests' - - - run: make V=1 test-ci - name: 'run tests' - env: - TFLAGS: "${{ matrix.build.tflags }}" - - - run: pytest -v tests - name: 'run pytest' - env: - TFLAGS: "${{ matrix.build.tflags }}" - CURL_CI: github + - run: | + sudo apt-get update + sudo apt-get install libtool autoconf automake pkg-config stunnel4 ${{ matrix.build.install }} + sudo apt-get install apache2 apache2-dev libnghttp2-dev + name: 'install prereqs and impacket, pytest, crypto' + + - name: cache nghttpx + uses: actions/cache@v4 + id: cache-nghttpx + env: + cache-name: cache-nghttpx + with: + path: /home/runner/nghttpx + key: ${{ runner.os }}-build-${{ env.cache-name }}-openssl-${{ env.openssl-version }}-nghttp3-${{ env.nghttp3-version }}-ngtcp2-${{ env.ngtcp2-version }}-nghttp2-${{ env.nghttp2-version }} + + - if: steps.cache-nghttpx.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b openssl-${{ env.openssl-version }} https://github.com/quictls/openssl + cd openssl + ./config --prefix=$HOME/nghttpx --libdir=$HOME/nghttpx/lib + make -j1 install_sw + name: 'install quictls' + + - if: steps.cache-nghttpx.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b ${{ env.nghttp3-version }} https://github.com/ngtcp2/nghttp3 + cd nghttp3 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only + make install + name: 'install nghttp3' + + - if: steps.cache-nghttpx.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b ${{ env.ngtcp2-version }} https://github.com/ngtcp2/ngtcp2 + cd ngtcp2 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-lib-only --with-openssl + make install + name: 'install ngtcp2' + + - if: steps.cache-nghttpx.outputs.cache-hit != 'true' + run: | + git clone --quiet --depth=1 -b ${{ env.nghttp2-version }} https://github.com/nghttp2/nghttp2 + cd nghttp2 + autoreconf -fi + ./configure --prefix=$HOME/nghttpx PKG_CONFIG_PATH="$HOME/nghttpx/lib/pkgconfig" --enable-http3 + make install + name: 'install nghttp2' + + - name: cache quiche + uses: actions/cache@v4 + id: cache-quiche + env: + cache-name: cache-quiche + with: + path: /home/runner/quiche + key: ${{ runner.os }}-build-${{ env.cache-name }}-quiche-${{ env.quiche-version }} + + - if: steps.cache-quiche.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b ${{ env.quiche-version }} --recursive https://github.com/cloudflare/quiche.git + cd quiche + #### Work-around https://github.com/curl/curl/issues/7927 ####### + #### See https://github.com/alexcrichton/cmake-rs/issues/131 #### + sed -i -e 's/cmake = "0.1"/cmake = "=0.1.45"/' quiche/Cargo.toml + + cargo build -v --package quiche --release --features ffi,pkg-config-meta,qlog --verbose + mkdir -v quiche/deps/boringssl/src/lib + ln -vnf $(find target/release -name libcrypto.a -o -name libssl.a) quiche/deps/boringssl/src/lib/ + + # include dir + # /home/runner/quiche/quiche/deps/boringssl/src/include + # lib dir + # /home/runner/quiche/quiche/deps/boringssl/src/lib + name: 'build quiche and boringssl' + + - name: cache mod_h2 + uses: actions/cache@v4 + id: cache-mod_h2 + env: + cache-name: cache-mod_h2 + with: + path: /home/runner/mod_h2 + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.mod_h2-version }} + + - if: steps.cache-mod_h2.outputs.cache-hit != 'true' + run: | + cd $HOME + git clone --quiet --depth=1 -b ${{ env.mod_h2-version }} https://github.com/icing/mod_h2 + cd mod_h2 + autoreconf -fi + ./configure + make + name: 'build mod_h2' + + - run: | + cd $HOME/mod_h2 + sudo make install + name: 'install mod_h2' + + - uses: actions/checkout@v4 + + - run: | + sudo python3 -m pip install -r tests/requirements.txt -r tests/http/requirements.txt + name: 'install python test prereqs' + + - run: autoreconf -fi + name: 'autoreconf' + + - run: ./configure ${{ matrix.build.configure }} + name: 'configure' + + - run: make V=1 + name: 'make' + + - run: make V=1 examples + name: 'make examples' + + - run: make V=1 -C tests + name: 'make tests' + + - run: make V=1 test-ci + name: 'run tests' + env: + TFLAGS: "${{ matrix.build.tflags }}" + + - run: pytest -v tests + name: 'run pytest' + env: + TFLAGS: "${{ matrix.build.tflags }}" + CURL_CI: github diff --git a/.github/workflows/reuse.yml b/.github/workflows/reuse.yml index 0cb5295c7c0..0818bfaabf0 100644 --- a/.github/workflows/reuse.yml +++ b/.github/workflows/reuse.yml @@ -8,11 +8,11 @@ name: REUSE compliance on: push: branches: - - master - - '*/ci' + - master + - '*/ci' pull_request: branches: - - master + - master concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} @@ -24,6 +24,6 @@ jobs: check: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - name: REUSE Compliance Check - uses: fsfe/reuse-action@v2 + - uses: actions/checkout@v4 + - name: REUSE Compliance Check + uses: fsfe/reuse-action@v3 diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 4793cf19049..e78a36ca7ab 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -6,24 +6,20 @@ name: spell on: push: branches: - - master + - master paths: - - '**.md' - - '**.3' - - '**.1' - - '**/spellcheck.yml' - - '**/spellcheck.yaml' - - '**/wordlist.txt' + - '**.md' + - '**/spellcheck.yml' + - '**/spellcheck.yaml' + - '.github/scripts/*' pull_request: branches: - - master + - master paths: - - '**.md' - - '**.3' - - '**.1' - - '**/spellcheck.yml' - - '**/spellcheck.yaml' - - '**/wordlist.txt' + - '**.md' + - '**/spellcheck.yml' + - '**/spellcheck.yaml' + - '.github/scripts/*' permissions: {} @@ -31,36 +27,24 @@ jobs: check: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v4 - - name: install pandoc - run: sudo apt-get install pandoc + - name: trim all man page *.md files + run: find docs -name "*.md" ! -name "_*" | xargs -n1 ./.github/scripts/cleancmd.pl - - name: build curl.1 - run: | - autoreconf -fi - ./configure --without-ssl - make -C docs + - name: trim libcurl man page *.md files + run: find docs/libcurl -name "curl_*.md" -o -name "libcurl*.md" | xargs -n1 ./.github/scripts/cleanspell.pl - - name: strip "uncheckable" sections from .3 pages - run: find docs -name "*.3" -size +40c | sed 's/\.3//' | xargs -t -n1 -I OO ./.github/scripts/cleanspell.pl OO.3 OO.33 + - name: trim libcurl option man page *.md files + run: find docs/libcurl/opts -name "CURL*.md" | xargs -n1 ./.github/scripts/cleanspell.pl - - name: convert .3 man pages to markdown - run: find docs -name "*.33" -size +40c | sed 's/\.33//' | xargs -t -n1 -I OO pandoc -f man -t markdown OO.33 -o OO.md + - name: trim cmdline docs markdown _*.md files + run: find docs/cmdline-opts -name "_*.md" | xargs -n1 ./.github/scripts/cleancmd.pl --no-header - - name: convert .1 man pages to markdown - run: find docs -name "*.1" -size +40c | sed 's/\.1//' | xargs -t -n1 -I OO pandoc OO.1 -o OO.md + - name: setup the custom wordlist + run: grep -v '^#' .github/scripts/spellcheck.words > wordlist.txt - - name: trim the curl.1 markdown file - run: | - perl -pi -e 's/^ .*//' docs/curl.md - perl -pi -e 's/\-\-[\a-z0-9-]*//ig' docs/curl.md - perl -pi -e 's!https://[a-z0-9%/.-]*!!ig' docs/curl.md - - - name: setup the custom wordlist - run: grep -v '^#' .github/scripts/spellcheck.words > wordlist.txt - - - name: Check Spelling - uses: rojopolis/spellcheck-github-actions@v0 - with: - config_path: .github/scripts/spellcheck.yaml + - name: Check Spelling + uses: rojopolis/spellcheck-github-actions@v0 + with: + config_path: .github/scripts/spellcheck.yaml diff --git a/.github/workflows/synopsis.yml b/.github/workflows/synopsis.yml index 948a83acb29..0938f4bfc98 100644 --- a/.github/workflows/synopsis.yml +++ b/.github/workflows/synopsis.yml @@ -7,22 +7,22 @@ name: SYNOPSIS on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths: - - 'docs/libcurl/curl_*.3' + - 'docs/libcurl/curl_*.3' pull_request: branches: - - master + - master paths: - - 'docs/libcurl/curl_*.3' + - 'docs/libcurl/curl_*.3' jobs: verify: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: verify-synopsis run: ./.github/scripts/verify-synopsis.pl docs/libcurl/curl*.3 diff --git a/.github/workflows/torture.yml b/.github/workflows/torture.yml index fa70eecd4b0..a50b37f140c 100644 --- a/.github/workflows/torture.yml +++ b/.github/workflows/torture.yml @@ -7,35 +7,35 @@ name: Linux torture on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: # Hardcoded workflow filename as workflow name above is just Linux again @@ -56,37 +56,37 @@ jobs: fail-fast: false matrix: build: - - name: torture - install: libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libnghttp2-dev libssh2-1-dev libc-ares-dev - configure: --with-openssl --enable-debug --enable-ares --enable-websockets - tflags: -n -t --shallow=25 !FTP - - name: torture-ftp - install: libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libnghttp2-dev libssh2-1-dev libc-ares-dev - configure: --with-openssl --enable-debug --enable-ares - tflags: -n -t --shallow=20 FTP + - name: torture + install: libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libnghttp2-dev libssh2-1-dev libc-ares-dev + configure: --with-openssl --enable-debug --enable-ares --enable-websockets + tflags: -n -t --shallow=25 !FTP + - name: torture-ftp + install: libpsl-dev libbrotli-dev libzstd-dev zlib1g-dev libnghttp2-dev libssh2-1-dev libc-ares-dev + configure: --with-openssl --enable-debug --enable-ares + tflags: -n -t --shallow=20 FTP steps: - - run: | - sudo apt-get update - sudo apt-get install libtool autoconf automake pkg-config stunnel4 ${{ matrix.build.install }} - sudo python3 -m pip install impacket - name: 'install prereqs and impacket' + - run: | + sudo apt-get update + sudo apt-get install libtool autoconf automake pkg-config stunnel4 ${{ matrix.build.install }} + sudo python3 -m pip install impacket + name: 'install prereqs and impacket' - - uses: actions/checkout@v4 + - uses: actions/checkout@v4 - - run: autoreconf -fi - name: 'autoreconf' + - run: autoreconf -fi + name: 'autoreconf' - - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} - name: 'configure' + - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} + name: 'configure' - - run: make V=1 - name: 'make' + - run: make V=1 + name: 'make' - - run: make V=1 -C tests - name: 'make tests' + - run: make V=1 -C tests + name: 'make tests' - - run: make V=1 test-torture - name: 'run tests' - env: - TFLAGS: "${{ matrix.build.tflags }}" + - run: make V=1 test-torture + name: 'run tests' + env: + TFLAGS: "${{ matrix.build.tflags }}" diff --git a/.github/workflows/wolfssl.yml b/.github/workflows/wolfssl.yml index 48c831dd7eb..5aaf3d1bd56 100644 --- a/.github/workflows/wolfssl.yml +++ b/.github/workflows/wolfssl.yml @@ -7,35 +7,35 @@ name: Linux wolfSSL on: push: branches: - - master - - '*/ci' + - master + - '*/ci' paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' pull_request: branches: - - master + - master paths-ignore: - - '**/*.md' - - '**/CMakeLists.txt' - - '.azure-pipelines.yml' - - '.circleci/**' - - '.cirrus.yml' - - 'appveyor.yml' - - 'CMake/**' - - 'packages/**' - - 'plan9/**' - - 'projects/**' - - 'winbuild/**' + - '**/*.md' + - '**/CMakeLists.txt' + - '.azure-pipelines.yml' + - '.circleci/**' + - '.cirrus.yml' + - 'appveyor.*' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: # Hardcoded workflow filename as workflow name above is just Linux again @@ -56,50 +56,50 @@ jobs: fail-fast: false matrix: build: - - name: wolfssl (configured with --enable-all) - install: - configure: LDFLAGS="-Wl,-rpath,$HOME/wssl/lib" --with-wolfssl=$HOME/wssl --enable-debug - wolfssl-configure: --enable-all - - name: wolfssl (configured with --enable-opensslextra) - install: - configure: LDFLAGS="-Wl,-rpath,$HOME/wssl/lib" --with-wolfssl=$HOME/wssl --enable-debug - wolfssl-configure: --enable-opensslextra + - name: wolfssl (configured with --enable-all) + install: + configure: LDFLAGS="-Wl,-rpath,$HOME/wssl/lib" --with-wolfssl=$HOME/wssl --enable-debug + wolfssl-configure: --enable-all + - name: wolfssl (configured with --enable-opensslextra) + install: + configure: LDFLAGS="-Wl,-rpath,$HOME/wssl/lib" --with-wolfssl=$HOME/wssl --enable-debug + wolfssl-configure: --enable-opensslextra steps: - - run: | - sudo apt-get update - sudo apt-get install libtool autoconf automake pkg-config stunnel4 ${{ matrix.build.install }} - sudo python3 -m pip install impacket - name: 'install prereqs and impacket' + - run: | + sudo apt-get update + sudo apt-get install libtool autoconf automake pkg-config stunnel4 libpsl-dev ${{ matrix.build.install }} + sudo python3 -m pip install impacket + name: 'install prereqs and impacket' - - run: | - WOLFSSL_VER=5.6.3 - curl -LOsSf --retry 6 --retry-connrefused --max-time 999 https://github.com/wolfSSL/wolfssl/archive/v$WOLFSSL_VER-stable.tar.gz - tar -xzf v$WOLFSSL_VER-stable.tar.gz - cd wolfssl-$WOLFSSL_VER-stable - ./autogen.sh - ./configure --enable-tls13 ${{ matrix.build.wolfssl-configure }} --enable-harden --prefix=$HOME/wssl - make install - name: 'install wolfssl' + - run: | + WOLFSSL_VER=5.6.3 + curl -LOsSf --retry 6 --retry-connrefused --max-time 999 https://github.com/wolfSSL/wolfssl/archive/v$WOLFSSL_VER-stable.tar.gz + tar -xzf v$WOLFSSL_VER-stable.tar.gz + cd wolfssl-$WOLFSSL_VER-stable + ./autogen.sh + ./configure --enable-tls13 ${{ matrix.build.wolfssl-configure }} --enable-harden --prefix=$HOME/wssl + make install + name: 'install wolfssl' - - uses: actions/checkout@v4 + - uses: actions/checkout@v4 - - run: autoreconf -fi - name: 'autoreconf' + - run: autoreconf -fi + name: 'autoreconf' - - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} - name: 'configure' + - run: ./configure --enable-warnings --enable-werror ${{ matrix.build.configure }} + name: 'configure' - - run: make V=1 - name: 'make' + - run: make V=1 + name: 'make' - - run: make V=1 examples - name: 'make examples' + - run: make V=1 examples + name: 'make examples' - - run: make V=1 -C tests - name: 'make tests' + - run: make V=1 -C tests + name: 'make tests' - - run: make V=1 test-ci - name: 'run tests' - env: - TFLAGS: "${{ matrix.build.tflags }}" + - run: make V=1 test-ci + name: 'run tests' + env: + TFLAGS: "${{ matrix.build.tflags }}" diff --git a/.reuse/dep5 b/.reuse/dep5 index 3a7a672a2b6..d51e5b9ce10 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -32,7 +32,7 @@ Files: CHANGES Copyright: Daniel Stenberg, , et al. License: curl -Files: GIT-INFO +Files: GIT-INFO.md Copyright: Daniel Stenberg, , et al. License: curl @@ -96,3 +96,7 @@ License: curl Files: .mailmap Copyright: Daniel Stenberg, , et al. License: curl + +Files: .github/dependabot.yml +Copyright: Daniel Stenberg, , et al. +License: curl diff --git a/CMake/CurlTests.c b/CMake/CurlTests.c index e5462862649..83d743d34e4 100644 --- a/CMake/CurlTests.c +++ b/CMake/CurlTests.c @@ -164,14 +164,11 @@ int main(void) { ; return 0; } #ifdef HAVE_IOCTLSOCKET /* includes start */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # ifndef WIN32_LEAN_AND_MEAN # define WIN32_LEAN_AND_MEAN # endif -# ifdef HAVE_WINSOCK2_H -# include -# endif -# include +# include #endif int main(void) { @@ -186,14 +183,11 @@ int main(void) #ifdef HAVE_IOCTLSOCKET_CAMEL /* includes start */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # ifndef WIN32_LEAN_AND_MEAN # define WIN32_LEAN_AND_MEAN # endif -# ifdef HAVE_WINSOCK2_H -# include -# endif -# include +# include #endif int main(void) { @@ -207,14 +201,11 @@ int main(void) #ifdef HAVE_IOCTLSOCKET_CAMEL_FIONBIO /* includes start */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # ifndef WIN32_LEAN_AND_MEAN # define WIN32_LEAN_AND_MEAN # endif -# ifdef HAVE_WINSOCK2_H -# include -# endif -# include +# include #endif int main(void) { @@ -229,14 +220,11 @@ int main(void) #ifdef HAVE_IOCTLSOCKET_FIONBIO /* includes start */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # ifndef WIN32_LEAN_AND_MEAN # define WIN32_LEAN_AND_MEAN # endif -# ifdef HAVE_WINSOCK2_H -# include -# endif -# include +# include #endif int main(void) { @@ -307,14 +295,11 @@ int main(void) #ifdef HAVE_SETSOCKOPT_SO_NONBLOCK /* includes start */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # ifndef WIN32_LEAN_AND_MEAN # define WIN32_LEAN_AND_MEAN # endif -# ifdef HAVE_WINSOCK2_H -# include -# endif -# include +# include #endif /* includes start */ #ifdef HAVE_SYS_TYPES_H diff --git a/CMake/Macros.cmake b/CMake/Macros.cmake index 7ad2f5c40f0..d5439fcc04c 100644 --- a/CMake/Macros.cmake +++ b/CMake/Macros.cmake @@ -45,7 +45,7 @@ macro(curl_internal_test CURL_TEST) "-DLINK_LIBRARIES:STRING=${CMAKE_REQUIRED_LIBRARIES}") endif() - message(STATUS "Performing Curl Test ${CURL_TEST}") + message(STATUS "Performing Test ${CURL_TEST}") try_compile(${CURL_TEST} ${CMAKE_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/CMake/CurlTests.c @@ -54,49 +54,20 @@ macro(curl_internal_test CURL_TEST) OUTPUT_VARIABLE OUTPUT) if(${CURL_TEST}) set(${CURL_TEST} 1 CACHE INTERNAL "Curl test ${FUNCTION}") - message(STATUS "Performing Curl Test ${CURL_TEST} - Success") + message(STATUS "Performing Test ${CURL_TEST} - Success") file(APPEND ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeOutput.log - "Performing Curl Test ${CURL_TEST} passed with the following output:\n" + "Performing Test ${CURL_TEST} passed with the following output:\n" "${OUTPUT}\n") else() - message(STATUS "Performing Curl Test ${CURL_TEST} - Failed") + message(STATUS "Performing Test ${CURL_TEST} - Failed") set(${CURL_TEST} "" CACHE INTERNAL "Curl test ${FUNCTION}") file(APPEND ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeError.log - "Performing Curl Test ${CURL_TEST} failed with the following output:\n" + "Performing Test ${CURL_TEST} failed with the following output:\n" "${OUTPUT}\n") endif() endif() endmacro() -macro(curl_nroff_check) - find_program(NROFF NAMES gnroff nroff) - if(NROFF) - # Need a way to write to stdin, this will do - file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/nroff-input.txt" "test") - # Tests for a valid nroff option to generate a manpage - foreach(_MANOPT "-man" "-mandoc") - execute_process(COMMAND "${NROFF}" ${_MANOPT} - OUTPUT_VARIABLE NROFF_MANOPT_OUTPUT - INPUT_FILE "${CMAKE_CURRENT_BINARY_DIR}/nroff-input.txt" - ERROR_QUIET) - # Save the option if it was valid - if(NROFF_MANOPT_OUTPUT) - message("Found *nroff option: -- ${_MANOPT}") - set(NROFF_MANOPT ${_MANOPT}) - set(NROFF_USEFUL ON) - break() - endif() - endforeach() - # No need for the temporary file - file(REMOVE "${CMAKE_CURRENT_BINARY_DIR}/nroff-input.txt") - if(NOT NROFF_USEFUL) - message(WARNING "Found no *nroff option to get plaintext from man pages") - endif() - else() - message(WARNING "Found no *nroff program") - endif() -endmacro() - macro(optional_dependency DEPENDENCY) set(CURL_${DEPENDENCY} AUTO CACHE STRING "Build curl with ${DEPENDENCY} support (AUTO, ON or OFF)") set_property(CACHE CURL_${DEPENDENCY} PROPERTY STRINGS AUTO ON OFF) diff --git a/CMake/OtherTests.cmake b/CMake/OtherTests.cmake index a613f6ecdc1..7701c0ee93b 100644 --- a/CMake/OtherTests.cmake +++ b/CMake/OtherTests.cmake @@ -23,115 +23,89 @@ ########################################################################### include(CheckCSourceCompiles) include(CheckCSourceRuns) - -# The begin of the sources (macros and includes) -set(_source_epilogue "#undef inline") +include(CheckTypeSize) macro(add_header_include check header) if(${check}) - set(_source_epilogue "${_source_epilogue}\n#include <${header}>") + set(_source_epilogue "${_source_epilogue} + #include <${header}>") endif() endmacro() -set(signature_call_conv) -if(HAVE_WINDOWS_H) - set(_source_epilogue - "${_source_epilogue}\n#ifndef WIN32_LEAN_AND_MEAN\n#define WIN32_LEAN_AND_MEAN\n#endif") - add_header_include(HAVE_WINSOCK2_H "winsock2.h") - add_header_include(HAVE_WINDOWS_H "windows.h") - set(signature_call_conv "PASCAL") +set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) + +if(NOT DEFINED HAVE_STRUCT_SOCKADDR_STORAGE) + set(CMAKE_EXTRA_INCLUDE_FILES) if(WIN32) + set(CMAKE_EXTRA_INCLUDE_FILES "winsock2.h") + set(CMAKE_REQUIRED_DEFINITIONS "-DWIN32_LEAN_AND_MEAN") set(CMAKE_REQUIRED_LIBRARIES "ws2_32") + elseif(HAVE_SYS_SOCKET_H) + set(CMAKE_EXTRA_INCLUDE_FILES "sys/socket.h") endif() -else() + check_type_size("struct sockaddr_storage" SIZEOF_STRUCT_SOCKADDR_STORAGE) + set(HAVE_STRUCT_SOCKADDR_STORAGE ${HAVE_SIZEOF_STRUCT_SOCKADDR_STORAGE}) +endif() + +if(NOT WIN32) + set(_source_epilogue "#undef inline") add_header_include(HAVE_SYS_TYPES_H "sys/types.h") add_header_include(HAVE_SYS_SOCKET_H "sys/socket.h") + check_c_source_compiles("${_source_epilogue} + int main(void) + { + int flag = MSG_NOSIGNAL; + (void)flag; + return 0; + }" HAVE_MSG_NOSIGNAL) endif() -set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) - +set(_source_epilogue "#undef inline") +add_header_include(HAVE_SYS_TIME_H "sys/time.h") check_c_source_compiles("${_source_epilogue} - int main(void) { - int flag = MSG_NOSIGNAL; - (void)flag; + #include + int main(void) + { + struct timeval ts; + ts.tv_sec = 0; + ts.tv_usec = 0; + (void)ts; return 0; - }" HAVE_MSG_NOSIGNAL) - -if(NOT HAVE_WINDOWS_H) - add_header_include(HAVE_SYS_TIME_H "sys/time.h") -endif() -check_c_source_compiles("${_source_epilogue} -#include -int main(void) { - struct timeval ts; - ts.tv_sec = 0; - ts.tv_usec = 0; - (void)ts; - return 0; -}" HAVE_STRUCT_TIMEVAL) - -if(HAVE_WINDOWS_H) - set(CMAKE_EXTRA_INCLUDE_FILES "winsock2.h") -else() - set(CMAKE_EXTRA_INCLUDE_FILES) - if(HAVE_SYS_SOCKET_H) - set(CMAKE_EXTRA_INCLUDE_FILES "sys/socket.h") - endif() -endif() - -check_type_size("struct sockaddr_storage" SIZEOF_STRUCT_SOCKADDR_STORAGE) -if(HAVE_SIZEOF_STRUCT_SOCKADDR_STORAGE) - set(HAVE_STRUCT_SOCKADDR_STORAGE 1) -endif() + }" HAVE_STRUCT_TIMEVAL) unset(CMAKE_TRY_COMPILE_TARGET_TYPE) -if(NOT CMAKE_CROSSCOMPILING) - if(NOT ${CMAKE_SYSTEM_NAME} MATCHES "Darwin" AND NOT ${CMAKE_SYSTEM_NAME} MATCHES "iOS") - # only try this on non-apple platforms - - # if not cross-compilation... - set(CMAKE_REQUIRED_FLAGS "") - if(HAVE_SYS_POLL_H) - set(CMAKE_REQUIRED_FLAGS "-DHAVE_SYS_POLL_H") - elseif(HAVE_POLL_H) - set(CMAKE_REQUIRED_FLAGS "-DHAVE_POLL_H") - endif() - check_c_source_runs(" - #include - #include - - #ifdef HAVE_SYS_POLL_H - # include - #elif HAVE_POLL_H - # include - #endif - - int main(void) - { - if(0 != poll(0, 0, 10)) { - return 1; /* fail */ - } - else { - /* detect the 10.12 poll() breakage */ - struct timeval before, after; - int rc; - size_t us; - - gettimeofday(&before, NULL); - rc = poll(NULL, 0, 500); - gettimeofday(&after, NULL); - - us = (after.tv_sec - before.tv_sec) * 1000000 + - (after.tv_usec - before.tv_usec); - - if(us < 400000) { - return 1; - } - } - return 0; +if(NOT CMAKE_CROSSCOMPILING AND NOT APPLE) + set(_source_epilogue "#undef inline") + add_header_include(HAVE_SYS_POLL_H "sys/poll.h") + add_header_include(HAVE_POLL_H "poll.h") + check_c_source_runs("${_source_epilogue} + #include + #include + int main(void) + { + if(0 != poll(0, 0, 10)) { + return 1; /* fail */ + } + else { + /* detect the 10.12 poll() breakage */ + struct timeval before, after; + int rc; + size_t us; + + gettimeofday(&before, NULL); + rc = poll(NULL, 0, 500); + gettimeofday(&after, NULL); + + us = (after.tv_sec - before.tv_sec) * 1000000 + + (after.tv_usec - before.tv_usec); + + if(us < 400000) { + return 1; + } + } + return 0; }" HAVE_POLL_FINE) - endif() endif() # Detect HAVE_GETADDRINFO_THREADSAFE @@ -140,8 +114,8 @@ if(WIN32) set(HAVE_GETADDRINFO_THREADSAFE ${HAVE_GETADDRINFO}) elseif(NOT HAVE_GETADDRINFO) set(HAVE_GETADDRINFO_THREADSAFE FALSE) -elseif(CMAKE_SYSTEM_NAME STREQUAL "AIX" OR - CMAKE_SYSTEM_NAME STREQUAL "Darwin" OR +elseif(APPLE OR + CMAKE_SYSTEM_NAME STREQUAL "AIX" OR CMAKE_SYSTEM_NAME STREQUAL "FreeBSD" OR CMAKE_SYSTEM_NAME STREQUAL "HP-UX" OR CMAKE_SYSTEM_NAME STREQUAL "MidnightBSD" OR @@ -153,14 +127,10 @@ elseif(CMAKE_SYSTEM_NAME MATCHES "BSD") endif() if(NOT DEFINED HAVE_GETADDRINFO_THREADSAFE) - - set(_save_epilogue "${_source_epilogue}") set(_source_epilogue "#undef inline") - add_header_include(HAVE_SYS_SOCKET_H "sys/socket.h") add_header_include(HAVE_SYS_TIME_H "sys/time.h") add_header_include(HAVE_NETDB_H "netdb.h") - check_c_source_compiles("${_source_epilogue} int main(void) { @@ -197,17 +167,12 @@ if(NOT DEFINED HAVE_GETADDRINFO_THREADSAFE) if(HAVE_H_ERRNO OR HAVE_H_ERRNO_ASSIGNABLE OR HAVE_H_ERRNO_SBS_ISSUE_7) set(HAVE_GETADDRINFO_THREADSAFE TRUE) endif() - - set(_source_epilogue "${_save_epilogue}") endif() if(NOT WIN32 AND NOT DEFINED HAVE_CLOCK_GETTIME_MONOTONIC_RAW) - set(_save_epilogue "${_source_epilogue}") set(_source_epilogue "#undef inline") - add_header_include(HAVE_SYS_TYPES_H "sys/types.h") add_header_include(HAVE_SYS_TIME_H "sys/time.h") - check_c_source_compiles("${_source_epilogue} #include int main(void) @@ -216,6 +181,4 @@ if(NOT WIN32 AND NOT DEFINED HAVE_CLOCK_GETTIME_MONOTONIC_RAW) (void)clock_gettime(CLOCK_MONOTONIC_RAW, &ts); return 0; }" HAVE_CLOCK_GETTIME_MONOTONIC_RAW) - - set(_source_epilogue "${_save_epilogue}") endif() diff --git a/CMake/PickyWarnings.cmake b/CMake/PickyWarnings.cmake index 5a0d1560424..d82bbb1d6a6 100644 --- a/CMake/PickyWarnings.cmake +++ b/CMake/PickyWarnings.cmake @@ -23,6 +23,12 @@ ########################################################################### include(CheckCCompilerFlag) +unset(WPICKY) + +if(CURL_WERROR AND CMAKE_COMPILER_IS_GNUCC AND NOT CMAKE_C_COMPILER_VERSION VERSION_LESS 5.0) + set(WPICKY "${WPICKY} -pedantic-errors") +endif() + if(PICKY_COMPILER) if(CMAKE_COMPILER_IS_GNUCC OR CMAKE_C_COMPILER_ID MATCHES "Clang") @@ -83,11 +89,12 @@ if(PICKY_COMPILER) -Wmissing-field-initializers # clang 2.7 gcc 4.1 -Wmissing-noreturn # clang 2.7 gcc 4.1 -Wno-format-nonliteral # clang 1.0 gcc 2.96 (3.0) - -Wno-sign-conversion # clang 2.9 gcc 4.3 -Wno-system-headers # clang 1.0 gcc 3.0 # -Wpadded # clang 2.9 gcc 4.1 # Not used because we cannot change public structs - -Wredundant-decls # clang 2.7 gcc 4.1 -Wold-style-definition # clang 2.7 gcc 3.4 + -Wredundant-decls # clang 2.7 gcc 4.1 + -Wsign-conversion # clang 2.9 gcc 4.3 + -Wno-error=sign-conversion # FIXME -Wstrict-prototypes # clang 1.0 gcc 3.3 # -Wswitch-enum # clang 2.7 gcc 4.1 # Not used because this basically disallows default case -Wtype-limits # clang 2.7 gcc 4.3 @@ -110,6 +117,7 @@ if(PICKY_COMPILER) -Wshift-sign-overflow # clang 2.9 -Wshorten-64-to-32 # clang 1.0 -Wlanguage-extension-token # clang 3.0 + -Wformat=2 # clang 3.0 gcc 4.8 ) # Enable based on compiler version if((CMAKE_C_COMPILER_ID STREQUAL "Clang" AND NOT CMAKE_C_COMPILER_VERSION VERSION_LESS 3.6) OR @@ -135,6 +143,12 @@ if(PICKY_COMPILER) -Wextra-semi-stmt # clang 7.0 appleclang 10.3 ) endif() + if((CMAKE_C_COMPILER_ID STREQUAL "Clang" AND NOT CMAKE_C_COMPILER_VERSION VERSION_LESS 10.0) OR + (CMAKE_C_COMPILER_ID STREQUAL "AppleClang" AND NOT CMAKE_C_COMPILER_VERSION VERSION_LESS 12.4)) + list(APPEND WPICKY_ENABLE + -Wimplicit-fallthrough # clang 4.0 gcc 7.0 appleclang 12.4 # we have silencing markup for clang 10.0 and above only + ) + endif() else() # gcc list(APPEND WPICKY_DETECT ${WPICKY_COMMON} @@ -147,6 +161,7 @@ if(PICKY_COMPILER) -Wmissing-parameter-type # gcc 4.3 -Wold-style-declaration # gcc 4.3 -Wstrict-aliasing=3 # gcc 4.0 + -Wtrampolines # gcc 4.3 ) endif() if(NOT CMAKE_C_COMPILER_VERSION VERSION_LESS 4.5 AND MINGW) @@ -156,7 +171,7 @@ if(PICKY_COMPILER) endif() if(NOT CMAKE_C_COMPILER_VERSION VERSION_LESS 4.8) list(APPEND WPICKY_ENABLE - -Wformat=2 # clang 3.0 gcc 4.8 (clang part-default, enabling it fully causes -Wformat-nonliteral warnings) + -Wformat=2 # clang 3.0 gcc 4.8 ) endif() if(NOT CMAKE_C_COMPILER_VERSION VERSION_LESS 5.0) @@ -179,6 +194,7 @@ if(PICKY_COMPILER) -Wduplicated-branches # gcc 7.0 -Wformat-overflow=2 # gcc 7.0 -Wformat-truncation=2 # gcc 7.0 + -Wimplicit-fallthrough # clang 4.0 gcc 7.0 -Wrestrict # gcc 7.0 ) endif() @@ -191,8 +207,6 @@ if(PICKY_COMPILER) # - unset(WPICKY) - foreach(_CCOPT IN LISTS WPICKY_ENABLE) set(WPICKY "${WPICKY} ${_CCOPT}") endforeach() @@ -209,8 +223,10 @@ if(PICKY_COMPILER) set(WPICKY "${WPICKY} ${_CCOPT}") endif() endforeach() - - message(STATUS "Picky compiler options:${WPICKY}") - set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${WPICKY}") endif() endif() + +if(WPICKY) + set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${WPICKY}") + message(STATUS "Picky compiler options:${WPICKY}") +endif() diff --git a/CMake/Platforms/WindowsCache.cmake b/CMake/Platforms/WindowsCache.cmake index ec09fd4bd19..d3391d92f87 100644 --- a/CMake/Platforms/WindowsCache.cmake +++ b/CMake/Platforms/WindowsCache.cmake @@ -171,6 +171,7 @@ set(HAVE_POSIX_STRERROR_R 0) set(HAVE_BUILTIN_AVAILABLE 0) set(HAVE_MSG_NOSIGNAL 0) set(HAVE_STRUCT_TIMEVAL 1) +set(HAVE_STRUCT_SOCKADDR_STORAGE 1) set(HAVE_GETHOSTBYNAME_R_3 0) set(HAVE_GETHOSTBYNAME_R_3_REENTRANT 0) diff --git a/CMake/Utilities.cmake b/CMake/Utilities.cmake index 9ff38e3a0f1..84a40f4e3c5 100644 --- a/CMake/Utilities.cmake +++ b/CMake/Utilities.cmake @@ -23,7 +23,7 @@ ########################################################################### # File containing various utilities -# Returns a list of arguments that evaluate to true +# Returns number of arguments that evaluate to true function(count_true output_count_var) set(lst_len 0) foreach(option_var IN LISTS ARGN) diff --git a/CMakeLists.txt b/CMakeLists.txt index 7d22d4e966e..5702de3ec85 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -21,25 +21,8 @@ # SPDX-License-Identifier: curl # ########################################################################### -# curl/libcurl CMake script # by Tetetest and Sukender (Benoit Neil) -# TODO: -# The output .so file lacks the soname number which we currently have within the lib/Makefile.am file -# Add full (4 or 5 libs) SSL support -# Add INSTALL target (EXTRA_DIST variables in Makefile.am may be moved to Makefile.inc so that CMake/CPack is aware of what's to include). -# Check on all possible platforms -# Test with as many configurations possible (With or without any option) -# Create scripts that help keeping the CMake build system up to date (to reduce maintenance). According to Tetetest: -# - lists of headers that 'configure' checks for; -# - curl-specific tests (the ones that are in m4/curl-*.m4 files); -# - (most obvious thing:) curl version numbers. -# Add documentation subproject -# -# To check: -# (From Daniel Stenberg) The cmake build selected to run gcc with -fPIC on my box while the plain configure script did not. -# (From Daniel Stenberg) The gcc command line use neither -g nor any -O options. As a developer, I also treasure our configure scripts's --enable-debug option that sets a long range of "picky" compiler options. - # Note: By default this CMake build script detects the version of some # dependencies using `check_symbol_exists`. Those checks do not work # in the case that both CURL and its dependency are included as @@ -105,7 +88,7 @@ option(BUILD_SHARED_LIBS "Build shared libraries" ON) option(BUILD_STATIC_LIBS "Build static libraries" OFF) option(BUILD_STATIC_CURL "Build curl executable with static libcurl" OFF) option(ENABLE_ARES "Set to ON to enable c-ares support" OFF) -option(CURL_DISABLE_INSTALL "Set to ON to disable instalation targets" OFF) +option(CURL_DISABLE_INSTALL "Set to ON to disable installation targets" OFF) if(WIN32) option(CURL_STATIC_CRT "Set to ON to build libcurl with static CRT on Windows (/MT)." OFF) @@ -321,18 +304,18 @@ if(ENABLE_IPV6 AND NOT WIN32) endif() endif() -if(USE_MANUAL) - #nroff is currently only used when USE_MANUAL is set, so we can prevent the warning of no *NROFF if USE_MANUAL is OFF (or not defined), by not even looking for NROFF.. - curl_nroff_check() -endif() find_package(Perl) -cmake_dependent_option(ENABLE_MANUAL "to provide the built-in manual" - ON "NROFF_USEFUL;PERL_FOUND" - OFF) +option(BUILD_LIBCURL_DOCS "to build libcurl man pages" ON) +option(ENABLE_CURL_MANUAL "to build the man page for curl and enable its -M/--manual option" ON) -if(ENABLE_MANUAL) - set(USE_MANUAL ON) +if(ENABLE_CURL_MANUAL OR BUILD_LIBCURL_DOCS) + if(PERL_FOUND) + set(HAVE_MANUAL_TOOLS ON) + endif() + if(NOT HAVE_MANUAL_TOOLS) + message(WARNING "Perl not found. Will not build manuals.") + endif() endif() if(CURL_STATIC_CRT) @@ -368,9 +351,6 @@ include(CheckCSourceCompiles) # On windows preload settings if(WIN32) - set(HAVE_WINDOWS_H 1) - set(HAVE_WS2TCPIP_H 1) - set(HAVE_WINSOCK2_H 1) include(${CMAKE_CURRENT_SOURCE_DIR}/CMake/Platforms/WindowsCache.cmake) endif() @@ -412,8 +392,7 @@ if(APPLE) endif() if(WIN32) cmake_dependent_option(CURL_USE_SCHANNEL "Enable Windows native SSL/TLS" OFF CURL_ENABLE_SSL OFF) - cmake_dependent_option(CURL_WINDOWS_SSPI "Use windows libraries to allow NTLM authentication without OpenSSL" ON - CURL_USE_SCHANNEL OFF) + option(CURL_WINDOWS_SSPI "Enable SSPI on Windows" ${CURL_USE_SCHANNEL}) endif() cmake_dependent_option(CURL_USE_MBEDTLS "Enable mbedTLS for SSL/TLS" OFF CURL_ENABLE_SSL OFF) cmake_dependent_option(CURL_USE_BEARSSL "Enable BearSSL for SSL/TLS" OFF CURL_ENABLE_SSL OFF) @@ -759,6 +738,29 @@ if(USE_MSH3) list(APPEND CURL_LIBS ${MSH3_LIBRARIES}) endif() +option(USE_OPENSSL_QUIC "Use openssl and nghttp3 libraries for HTTP/3 support" OFF) +if(USE_OPENSSL_QUIC) + if(USE_NGTCP2 OR USE_QUICHE OR USE_MSH3) + message(FATAL_ERROR "Only one HTTP/3 backend can be selected!") + endif() + find_package(OpenSSL 3.2.0 REQUIRED) + + find_package(NGHTTP3 REQUIRED) + set(USE_NGHTTP3 ON) + include_directories(${NGHTTP3_INCLUDE_DIRS}) + list(APPEND CURL_LIBS ${NGHTTP3_LIBRARIES}) +endif() + +if(USE_MBEDTLS OR + USE_BEARSSL OR + USE_SECTRANSP) + message(WARNING "A selected TLS library does not support TLS 1.3.") +endif() + +if(CURL_WITH_MULTI_SSL AND (USE_NGTCP2 OR USE_QUICHE OR USE_MSH3 OR USE_OPENSSL_QUIC)) + message(FATAL_ERROR "MultiSSL cannot be enabled with HTTP/3 and vice versa.") +endif() + if(NOT CURL_DISABLE_SRP AND (HAVE_GNUTLS_SRP OR HAVE_OPENSSL_SRP)) set(USE_TLS_SRP 1) endif() @@ -810,7 +812,7 @@ if(NOT CURL_DISABLE_LDAP) endif() set(NEED_LBER_H ON) set(_HEADER_LIST) - if(HAVE_WINDOWS_H) + if(WIN32) list(APPEND _HEADER_LIST "windows.h") endif() if(HAVE_SYS_TYPES_H) @@ -950,10 +952,8 @@ if(CURL_USE_GSSAPI) check_include_file_concat("gssapi/gssapi_generic.h" HAVE_GSSAPI_GSSAPI_GENERIC_H) check_include_file_concat("gssapi/gssapi_krb5.h" HAVE_GSSAPI_GSSAPI_KRB5_H) - if(GSS_FLAVOUR STREQUAL "Heimdal") - set(HAVE_GSSHEIMDAL ON) - else() # MIT - set(HAVE_GSSMIT ON) + if(NOT GSS_FLAVOUR STREQUAL "Heimdal") + # MIT set(_INCLUDE_LIST "") if(HAVE_GSSAPI_GSSAPI_H) list(APPEND _INCLUDE_LIST "gssapi/gssapi.h") @@ -1093,9 +1093,9 @@ endif() # Check for header files if(WIN32) - check_include_file_concat("winsock2.h" HAVE_WINSOCK2_H) - check_include_file_concat("ws2tcpip.h" HAVE_WS2TCPIP_H) - check_include_file_concat("windows.h" HAVE_WINDOWS_H) + set(CURL_INCLUDES ${CURL_INCLUDES} "winsock2.h") + set(CURL_INCLUDES ${CURL_INCLUDES} "ws2tcpip.h") + set(CURL_INCLUDES ${CURL_INCLUDES} "windows.h") endif() if(WIN32) @@ -1289,7 +1289,7 @@ set(HAVE_SA_FAMILY_T ${HAVE_SIZEOF_SA_FAMILY_T}) set(CMAKE_EXTRA_INCLUDE_FILES "") if(WIN32) - set(CMAKE_EXTRA_INCLUDE_FILES "ws2def.h") + set(CMAKE_EXTRA_INCLUDE_FILES "winsock2.h") check_type_size("ADDRESS_FAMILY" SIZEOF_ADDRESS_FAMILY) set(HAVE_ADDRESS_FAMILY ${HAVE_SIZEOF_ADDRESS_FAMILY}) set(CMAKE_EXTRA_INCLUDE_FILES "") @@ -1429,15 +1429,6 @@ if(CMAKE_COMPILER_IS_GNUCC AND APPLE) endif() endif() -# TODO test which of these headers are required -if(WIN32) - set(CURL_PULL_WS2TCPIP_H ${HAVE_WS2TCPIP_H}) -else() - set(CURL_PULL_SYS_TYPES_H ${HAVE_SYS_TYPES_H}) - set(CURL_PULL_SYS_SOCKET_H ${HAVE_SYS_SOCKET_H}) - set(CURL_PULL_SYS_POLL_H ${HAVE_SYS_POLL_H}) -endif() - include(CMake/OtherTests.cmake) add_definitions(-DHAVE_CONFIG_H) @@ -1527,7 +1518,7 @@ set(generated_dir "${CMAKE_CURRENT_BINARY_DIR}/generated") set(project_config "${generated_dir}/${PROJECT_NAME}Config.cmake") set(version_config "${generated_dir}/${PROJECT_NAME}ConfigVersion.cmake") -if(USE_MANUAL) +if(HAVE_MANUAL_TOOLS) add_subdirectory(docs) endif() @@ -1556,7 +1547,6 @@ if(NOT CURL_DISABLE_INSTALL) endmacro() # NTLM support requires crypto function adaptions from various SSL libs - # TODO alternative SSL libs tests for SSP1, GnuTLS, NSS if(NOT (CURL_DISABLE_NTLM) AND (USE_OPENSSL OR USE_MBEDTLS OR USE_DARWINSSL OR USE_WIN32_CRYPTO OR USE_GNUTLS)) set(use_curl_ntlm_core ON) @@ -1574,28 +1564,22 @@ if(NOT CURL_DISABLE_INSTALL) _add_if("IDN" HAVE_LIBIDN2 OR USE_WIN32_IDN) _add_if("Largefile" (SIZEOF_CURL_OFF_T GREATER 4) AND ((SIZEOF_OFF_T GREATER 4) OR USE_WIN32_LARGE_FILES)) - # TODO SSP1 (Schannel) check is missing _add_if("SSPI" USE_WINDOWS_SSPI) _add_if("GSS-API" HAVE_GSSAPI) _add_if("alt-svc" NOT CURL_DISABLE_ALTSVC) _add_if("HSTS" NOT CURL_DISABLE_HSTS) - # TODO SSP1 missing for SPNEGO _add_if("SPNEGO" NOT CURL_DISABLE_NEGOTIATE_AUTH AND (HAVE_GSSAPI OR USE_WINDOWS_SSPI)) _add_if("Kerberos" NOT CURL_DISABLE_KERBEROS_AUTH AND (HAVE_GSSAPI OR USE_WINDOWS_SSPI)) - # NTLM support requires crypto function adaptions from various SSL libs - # TODO alternative SSL libs tests for SSP1, GnuTLS, NSS _add_if("NTLM" NOT (CURL_DISABLE_NTLM) AND (use_curl_ntlm_core OR USE_WINDOWS_SSPI)) - # TODO missing option (autoconf: --enable-ntlm-wb) _add_if("NTLM_WB" NOT (CURL_DISABLE_NTLM) AND (use_curl_ntlm_core OR USE_WINDOWS_SSPI) AND NOT CURL_DISABLE_HTTP AND NTLM_WB_ENABLED) _add_if("TLS-SRP" USE_TLS_SRP) - # TODO option --with-nghttp2 tests for nghttp2 lib and nghttp2/nghttp2.h header _add_if("HTTP2" USE_NGHTTP2) - _add_if("HTTP3" USE_NGTCP2 OR USE_QUICHE) + _add_if("HTTP3" USE_NGTCP2 OR USE_QUICHE OR USE_OPENSSL_QUIC) _add_if("MultiSSL" CURL_WITH_MULTI_SSL) # TODO wolfSSL only support this from v5.0.0 onwards _add_if("HTTPS-proxy" SSL_ENABLED AND (USE_OPENSSL OR USE_GNUTLS @@ -1612,6 +1596,8 @@ if(NOT CURL_DISABLE_INSTALL) # Clear list and try to detect available protocols set(_items) _add_if("HTTP" NOT CURL_DISABLE_HTTP) + _add_if("IPFS" NOT CURL_DISABLE_HTTP) + _add_if("IPNS" NOT CURL_DISABLE_HTTP) _add_if("HTTPS" NOT CURL_DISABLE_HTTP AND SSL_ENABLED) _add_if("FTP" NOT CURL_DISABLE_FTP) _add_if("FTPS" NOT CURL_DISABLE_FTP AND SSL_ENABLED) @@ -1678,6 +1664,30 @@ if(NOT CURL_DISABLE_INSTALL) set(LDFLAGS "${CMAKE_SHARED_LINKER_FLAGS}") set(LIBCURL_LIBS "") set(libdir "${CMAKE_INSTALL_PREFIX}/lib") + + # For processing full path libraries into -L and -l ld options, + # the directories that go with the -L option are cached, so they + # only get added once per such directory. + set(_libcurl_libs_dirs) + # To avoid getting unnecessary -L options for known system directories, + # _libcurl_libs_dirs is seeded with them. + foreach(_libdir ${CMAKE_SYSTEM_PREFIX_PATH}) + if(_libdir MATCHES "/$") + set(_libdir "${_libdir}lib") + else() + set(_libdir "${_libdir}/lib") + endif() + if(IS_DIRECTORY "${_libdir}") + list(APPEND _libcurl_libs_dirs "${_libdir}") + endif() + if(DEFINED CMAKE_LIBRARY_ARCHITECTURE) + set(_libdir "${_libdir}/${CMAKE_LIBRARY_ARCHITECTURE}") + if(IS_DIRECTORY "${_libdir}") + list(APPEND _libcurl_libs_dirs "${_libdir}") + endif() + endif() + endforeach() + foreach(_lib ${CMAKE_C_IMPLICIT_LINK_LIBRARIES} ${CURL_LIBS}) if(TARGET "${_lib}") set(_libname "${_lib}") @@ -1693,8 +1703,24 @@ if(NOT CURL_DISABLE_INSTALL) continue() endif() endif() - if(_lib MATCHES ".*/.*" OR _lib MATCHES "^-") + if(_lib MATCHES "^-") set(LIBCURL_LIBS "${LIBCURL_LIBS} ${_lib}") + elseif(_lib MATCHES ".*/.*") + # This gets a bit more complex, because we want to specify the + # directory separately, and only once per directory + string(REGEX REPLACE "^(.*)/[^/]*$" "\\1" _libdir "${_lib}") + string(REGEX REPLACE "^.*/([^/.]*).*$" "\\1" _libname "${_lib}") + if(_libname MATCHES "^lib") + list(FIND _libcurl_libs_dirs "${_libdir}" _libdir_index) + if(_libdir_index LESS 0) + list(APPEND _libcurl_libs_dirs "${_libdir}") + set(LIBCURL_LIBS "${LIBCURL_LIBS} -L${_libdir}") + endif() + string(REGEX REPLACE "^lib" "" _libname "${_libname}") + set(LIBCURL_LIBS "${LIBCURL_LIBS} -l${_libname}") + else() + set(LIBCURL_LIBS "${LIBCURL_LIBS} ${_lib}") + endif() else() set(LIBCURL_LIBS "${LIBCURL_LIBS} -l${_lib}") endif() diff --git a/COPYING b/COPYING index d1eab3eb932..d9e7e0bef3e 100644 --- a/COPYING +++ b/COPYING @@ -1,6 +1,6 @@ COPYRIGHT AND PERMISSION NOTICE -Copyright (c) 1996 - 2023, Daniel Stenberg, , and many +Copyright (c) 1996 - 2024, Daniel Stenberg, , and many contributors, see the THANKS file. All rights reserved. diff --git a/GIT-INFO b/GIT-INFO deleted file mode 100644 index 62efbd938c0..00000000000 --- a/GIT-INFO +++ /dev/null @@ -1,44 +0,0 @@ - _ _ ____ _ - ___| | | | _ \| | - / __| | | | |_) | | - | (__| |_| | _ <| |___ - \___|\___/|_| \_\_____| - -GIT-INFO - -This file is only present in git - never in release archives. It contains -information about other files and things that the git repository keeps in its -inner sanctum. - -To build in environments that support configure, after having extracted -everything from git, do this: - -autoreconf -fi -./configure --with-openssl -make - - Daniel uses a ./configure line similar to this for easier development: - - ./configure --disable-shared --enable-debug --enable-maintainer-mode - -In environments that don't support configure (i.e. Microsoft), do this: - -buildconf.bat - - -REQUIREMENTS - -For autoreconf and configure (not buildconf.bat) to work, you need the -following software installed: - - o autoconf 2.57 (or later) - o automake 1.7 (or later) - o libtool 1.4.2 (or later) - o GNU m4 (required by autoconf) - - o nroff + perl - - If you don't have nroff and perl and you for some reason don't want to - install them, you can rename the source file src/tool_hugehelp.c.cvs to - src/tool_hugehelp.c and avoid having to generate this file. This will - give you a stubbed version of the file that doesn't contain actual content. diff --git a/GIT-INFO.md b/GIT-INFO.md new file mode 100644 index 00000000000..825476c96ce --- /dev/null +++ b/GIT-INFO.md @@ -0,0 +1,42 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + +# GIT-INFO + +This file is only present in git - never in release archives. It contains +information about other files and things that the git repository keeps in its +inner sanctum. + +To build in environments that support configure, after having extracted +everything from git, do this: + + autoreconf -fi + ./configure --with-openssl + make + +Daniel uses a configure line similar to this for easier development: + + ./configure --disable-shared --enable-debug --enable-maintainer-mode + +In environments that don't support configure (i.e. Windows), do this: + + buildconf.bat + +## REQUIREMENTS + +For `autoreconf` and `configure` (not `buildconf.bat`) to work, you need the +following software installed: + + o autoconf 2.57 (or later) + o automake 1.7 (or later) + o libtool 1.4.2 (or later) + o GNU m4 (required by autoconf) + o perl + +If you don't have perl and don't want to install it, you can rename the source +file `src/tool_hugehelp.c.cvs` to `src/tool_hugehelp.c` and avoid having to +generate this file. This will give you a stubbed version of the file that +doesn't contain actual content. diff --git a/Makefile.am b/Makefile.am index 2341250833d..1ebc38b5a42 100644 --- a/Makefile.am +++ b/Makefile.am @@ -127,13 +127,14 @@ EXTRA_DIST = CHANGES COPYING maketgz Makefile.dist curl-config.in \ $(VC_DIST) $(WINBUILD_DIST) $(PLAN9_DIST) lib/libcurl.vers.in buildconf.bat \ libcurl.def -CLEANFILES = $(VC14_LIBVCXPROJ) \ - $(VC14_SRCVCXPROJ) $(VC14_10_LIBVCXPROJ) $(VC14_10_SRCVCXPROJ) \ +CLEANFILES = $(VC14_LIBVCXPROJ) $(VC14_SRCVCXPROJ) \ + $(VC14_10_LIBVCXPROJ) $(VC14_10_SRCVCXPROJ) \ + $(VC14_20_LIBVCXPROJ) $(VC14_20_SRCVCXPROJ) \ $(VC14_30_LIBVCXPROJ) $(VC14_30_SRCVCXPROJ) bin_SCRIPTS = curl-impersonate-chrome-config -SUBDIRS = lib src +SUBDIRS = lib docs src scripts DIST_SUBDIRS = $(SUBDIRS) tests packages scripts include docs pkgconfigdir = $(libdir)/pkgconfig @@ -152,12 +153,6 @@ dist-hook: cp -p $$file $(distdir)$$strip; \ done) -html: - cd docs && $(MAKE) html - -pdf: - cd docs && $(MAKE) pdf - check: test examples check-docs if CROSSCOMPILING @@ -246,10 +241,16 @@ cygwinbin: $(MAKE) -C packages/Win32/cygwin cygwinbin # We extend the standard install with a custom hook: +if BUILD_DOCS install-data-hook: (cd include && $(MAKE) install) (cd docs && $(MAKE) install) (cd docs/libcurl && $(MAKE) install) +else +install-data-hook: + (cd include && $(MAKE) install) + (cd docs && $(MAKE) install) +endif # We extend the standard uninstall with a custom hook: uninstall-hook: @@ -509,7 +510,8 @@ function gen_element(type, dir, file)\ -v src_rc="$$win32_src_rc" \ -v src_x_srcs="$$sorted_src_x_srcs" \ -v src_x_hdrs="$$sorted_src_x_hdrs" \ - "$$awk_code" $(srcdir)/$(VC14_20_SRCTMPL) > $(VC14_20_SRCVCXPROJ) || { exit 1; };) \ + "$$awk_code" $(srcdir)/$(VC14_20_SRCTMPL) > $(VC14_20_SRCVCXPROJ) || { exit 1; }; \ + \ echo "generating '$(VC14_30_LIBVCXPROJ)'"; \ awk -v proj_type=vcxproj \ -v lib_srcs="$$sorted_lib_srcs" \ diff --git a/Makefile.dist b/Makefile.dist index a5818e1da59..3db331a4817 100644 --- a/Makefile.dist +++ b/Makefile.dist @@ -30,27 +30,6 @@ ssl: ./configure --with-openssl make -mingw32: - $(MAKE) -C lib -f Makefile.mk - $(MAKE) -C src -f Makefile.mk - -mingw32-clean: - $(MAKE) -C lib -f Makefile.mk clean - $(MAKE) -C src -f Makefile.mk clean - $(MAKE) -C docs/examples -f Makefile.mk clean - -mingw32-vclean mingw32-distclean: - $(MAKE) -C lib -f Makefile.mk vclean - $(MAKE) -C src -f Makefile.mk vclean - $(MAKE) -C docs/examples -f Makefile.mk vclean - -mingw32-examples%: - $(MAKE) -C docs/examples -f Makefile.mk CFG=$@ - -mingw32%: - $(MAKE) -C lib -f Makefile.mk CFG=$@ - $(MAKE) -C src -f Makefile.mk CFG=$@ - vc: cd winbuild nmake /f Makefile.vc MACHINE=x86 diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 3f7dc99f682..620578ab34c 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -1,206 +1,183 @@ -curl and libcurl 8.5.0 +curl and libcurl 8.7.0 - Public curl releases: 253 + Public curl releases: 255 Command line options: 258 - curl_easy_setopt() options: 303 + curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3039 + Contributors: 3134 This release includes the following changes: - o gnutls: support CURLSSLOPT_NATIVE_CA [31] - o HTTP3: ngtcp2 builds are no longer experimental [77] + o configure: add --disable-docs flag [16] + o CURLINFO_USED_PROXY: return bool whether the proxy was used [24] + o digest: support SHA-512/256 [118] + o DoH: add trace configuration [61] + o write-out: add '%{proxy_used}' [24] This release includes the following bugfixes: - o appveyor: make VS2008-built curl tool runnable [93] - o asyn-thread: use pipe instead of socketpair for IPC when available [4] - o autotools: accept linker flags via `CURL_LDFLAGS_{LIB,BIN}` [128] - o autotools: avoid passing `LDFLAGS` twice to libcurl [127] - o autotools: delete LCC compiler support bits [137] - o autotools: fix/improve gcc and Apple clang version detection [136] - o autotools: stop setting `-std=gnu89` with `--enable-warnings` [135] - o autotools: update references to deleted `crypt-auth` option [46] - o BINDINGS: add V binding [54] - o build: add `src/.checksrc` to source tarball [1] - o build: add more picky warnings and fix them [172] - o build: always revert `#pragma GCC diagnostic` after use [143] - o build: delete `HAVE_STDINT_H` and `HAVE_INTTYPES_H` [107] - o build: delete support bits for obsolete Windows compilers [106] - o build: fix 'threadsafe' feature detection for older gcc [19] - o build: fix builds that disable protocols but not digest auth [174] - o build: fix compiler warning with auths disabled [85] - o build: fix libssh2 + `CURL_DISABLE_DIGEST_AUTH` + `CURL_DISABLE_AWS` [120] - o build: picky warning updates [125] - o build: require Windows XP or newer [86] - o cfilter: provide call to tell connection to forget a socket [65] - o checksrc.pl: support #line instructions - o CI: add autotools, out-of-tree, debug build to distro check job [14] - o CI: ignore test 286 on Appveyor gcc 9 build [6] - o cmake: add `CURL_DISABLE_BINDLOCAL` option [146] - o cmake: add test for `DISABLE` options, add `CURL_DISABLE_HEADERS_API` [138] - o cmake: dedupe Windows system libs [114] - o cmake: fix `HAVE_H_ERRNO_ASSIGNABLE` detection [2] - o cmake: fix CURL_DISABLE_GETOPTIONS [12] - o cmake: fix multiple include of CURL package [96] - o cmake: fix OpenSSL quic detection in quiche builds [56] - o cmake: option to disable install & drop `curlu` target when unused [72] - o cmake: pre-fill rest of detection values for Windows [50] - o cmake: replace `check_library_exists_concat()` [23] - o cmake: speed up threads setup for Windows [68] - o cmake: speed up zstd detection [69] - o config-win32: set `HAVE_SNPRINTF` for mingw-w64 [123] - o configure: better --disable-http [80] - o configure: check for the fseeko declaration too [55] - o conncache: use the closure handle when disconnecting surplus connections [173] - o content_encoding: make Curl_all_content_encodings allocless [101] - o cookie: lowercase the domain names before PSL checks [160] - o curl.h: delete Symbian OS references [162] - o curl.h: on FreeBSD include sys/param.h instead of osreldate.h [21] - o curl.rc: switch out the copyright symbol for plain ASCII [167] - o curl: improved IPFS and IPNS URL support [87] - o curl_easy_duphandle.3: clarify how HSTS and alt-svc are duped [99] - o Curl_http_body: cleanup properly when Curl_getformdata errors [152] - o curl_setup: disallow Windows IPv6 builds missing getaddrinfo [57] - o curl_sspi: support more revocation error names in error messages [95] - o CURLINFO_PRETRANSFER_TIME_T.3: fix time explanation [181] - o CURLMOPT_MAX_CONCURRENT_STREAMS: make sure the set value is within range [165] - o CURLOPT_CAINFO_BLOB.3: explain what CURL_BLOB_COPY does [113] - o CURLOPT_WRITEFUNCTION.3: clarify libcurl returns for CURL_WRITEFUNC_ERROR [45] - o CURPOST_POSTFIELDS.3: add CURLOPT_COPYPOSTFIELDS in SEE ALSO - o docs/example/keepalive.c: show TCP keep-alive options [73] - o docs/example/localport.c: show off CURLOPT_LOCALPORT [83] - o docs/examples/interface.c: show CURLOPT_INTERFACE use [84] - o docs/libcurl: fix three minor man page format mistakes [26] - o docs/libcurl: SYNSOPSIS cleanup [150] - o docs: add supported version for the json write-out [92] - o docs: clarify that curl passes on input unfiltered [47] - o docs: fix function typo in curl_easy_option_next.3 [36] - o docs: KNOWN_BUGS cleanup - o docs: make all examples in all libcurl man pages compile [175] - o docs: preserve the modification date when copying the prebuilt man page [89] - o docs: remove bold from some man page SYNOPSIS sections [90] - o docs: use SOURCE_DATE_EPOCH for generated manpages [16] - o doh: provide better return code for responses w/o addresses [133] - o doh: use PIPEWAIT when HTTP/2 is attempted [63] - o duphandle: also free 'outcurl->cookies' in error path [122] - o duphandle: make dupset() not return with pointers to old alloced data [109] - o duphandle: use strdup to clone *COPYPOSTFIELDS if size is not set [132] - o easy: in duphandle, init the cookies for the new handle [131] - o easy: remove duplicate wolfSSH init call [37] - o easy_lock: add a pthread_mutex_t fallback [13] - o examples/rtsp-options.c: add [157] - o fopen: create new file using old file's mode [153] - o fopen: create short(er) temporary file name [155] - o getenv: PlayStation doesn't have getenv() [41] - o GHA: move mod_h2 version in CI to v2.0.25 [43] - o hostip: show the list of IPs when resolving is done [35] - o hostip: silence compiler warning `-Wparentheses-equality` [62] - o hsts: skip single-dot hostname [67] - o HTTP/2, HTTP/3: handle detach of onoing transfers [134] - o http2: header conversion tightening [33] - o http2: provide an error callback and failf the message [53] - o http2: safer invocation of populate_binsettings [8] - o http: allow longer HTTP/2 request method names [112] - o http: avoid Expect: 100-continue if Upgrade: is used [15] - o http: consider resume with CURLOPT_FAILONERRROR and 416 to be fine [81] - o http: fix `-Wunused-parameter` with no auth and no proxy [149] - o http: fix `-Wunused-variable` compiler warning [115] - o http: fix empty-body warning [76] - o http_aws_sigv4: canonicalise valueless query params [88] - o hyper: temporarily remove HTTP/2 support [139] - o INSTALL: update list of ports and CPU archs - o IPFS: fix IPFS_PATH and file parsing [119] - o keylog: disable if unused [145] - o lib: add and use Curl_strndup() [97] - o lib: apache style infof and trace macros/functions [71] - o lib: fix gcc warning in printf call [7] - o libcurl-errors.3: sync with current public headers [156] - o libcurl-thread.3: simplify the TLS section [79] - o Makefile.am: drop vc10, vc11 and vc12 projects from dist [103] - o Makefile.mk: fix `-rtmp` option for non-Windows - o mime: store "form escape" as a single bit [170] - o misc: fix -Walloc-size warnings [118] - o msh3: error when built with CURL_DISABLE_SOCKETPAIR set [61] - o multi: during ratelimit multi_getsock should return no sockets [182] - o multi: use pipe instead of socketpair to *wakeup() [18] - o ngtcp2: fix races in stream handling [178] - o ngtcp2: ignore errors on unknown streams [158] - o ntlm_wb: use pipe instead of socketpair when possible [44] - o openldap: move the alloc of ldapconninfo to *connect() [29] - o openldap: set the callback argument in oldap_do [30] - o openssl: avoid BN_num_bits() NULL pointer derefs [9] - o openssl: fix building with v3 `no-deprecated` + add CI test [161] - o openssl: fix infof() to avoid compiler warning for %s with null [70] - o openssl: identify the "quictls" backend correctly [82] - o openssl: include SIG and KEM algorithms in verbose [52] - o openssl: make CURLSSLOPT_NATIVE_CA import Windows intermediate CAs [58] - o openssl: two multi pointer checks should probably rather be asserts [91] - o openssl: when a session-ID is reused, skip OCSP stapling [142] - o page-footer: clarify exit code 25 [51] - o projects: add VC14.20 project files [104] - o pytest: use lower count in repeat tests [98] - o quic: make eyeballers connect retries stop at weird replies [140] - o quic: manage connection idle timeouts [5] - o quiche: use quiche_conn_peer_transport_params() [116] - o rand: fix build error with autotools + LibreSSL [111] - o resolve.d: drop a multi use-sentence [100] - o RTSP: improved RTP parser [32] - o rustls: implement connect_blocking [154] - o sasl: fix `-Wunused-function` compiler warning [124] - o schannel: add CA cache support for files and memory blobs [121] - o setopt: check CURLOPT_TFTP_BLKSIZE range on set [171] - o setopt: remove outdated cookie comment [64] - o setopt: remove superfluous use of ternary expressions [169] - o socks: better buffer size checks for socks4a user and hostname [20] - o socks: make SOCKS5 use the CURLOPT_IPRESOLVE choice [38] - o symbols-in-versions: the CLOSEPOLICY options are deprecated - o test1683: remove commented-out check alternatives - o test3103: add missing quotes around a test tag attribute - o test613: stop showing an error on missing output file - o tests/README: SOCKS tests are not using OpenSSH, it has its own server [48] - o tests/server: add more SOCKS5 handshake error checking [27] - o tests: Fix Windows test helper tool search & use it for handle64 [17] - o tidy-up: casing typos, delete unused Windows version aliases [144] - o tool: fix --capath when proxy support is disabled [28] - o tool: support bold headers in Windows [117] - o tool_cb_hdr: add an additional parsing check [129] - o tool_cb_prg: make the carriage return fit for wide progress bars [159] - o tool_cb_wrt: fix write output for very old Windows versions [24] - o tool_getparam: limit --rate to be smaller than number of ms [3] - o tool_operate: do not mix memory models [108] - o tool_operate: fix links in ipfs errors [22] - o tool_parsecfg: make warning output propose double-quoting [164] - o tool_urlglob: fix build for old gcc versions [25] - o tool_urlglob: make multiply() bail out on negative values [11] - o tool_writeout_json: fix JSON encoding of non-ascii bytes [179] - o transfer: abort pause send when connection is marked for closing [183] - o transfer: avoid calling the read callback again after EOF [130] - o transfer: only reset the FTP wildcard engine in CLEAR state [42] - o url: don't touch the multi handle when closing internal handles [40] - o url: find scheme with a "perfect hash" [141] - o url: fix `-Wzero-length-array` with no protocols [147] - o url: fix builds with `CURL_DISABLE_HTTP` [148] - o url: protocol handler lookup tidy-up [66] - o url: proxy ssl connection reuse fix [94] - o urlapi: avoid null deref if setting blank host to url encode [75] - o urlapi: skip appending NULL pointer query [74] - o urlapi: when URL encoding the fragment, pass in the right length [59] - o urldata: make maxconnects a 32 bit value [166] - o urldata: move async resolver state from easy handle to connectdata [34] - o urldata: move cookielist from UserDefined to UrlState [126] - o urldata: move hstslist from 'set' to 'state' [105] - o urldata: move the 'internal' boolean to the state struct [39] - o vssh: remove the #ifdef for Curl_ssh_init, use empty macro - o vtls: cleanup SSL config management [78] - o vtls: consistently use typedef names for OpenSSL structs [176] - o vtls: late clone of connection ssl config [60] - o vtls: use ALPN "http/1.1" for HTTP/1.x, including HTTP/1.0 [102] - o VULN-DISCLOSURE-POLICY: escape sequences are not a security flaw [110] - o windows: use built-in `_WIN32` macro to detect Windows [163] - o wolfssh: remove redundant static prototypes [168] - o wolfssl: add default case for wolfssl_connect_step1 switch [49] - o wolfssl: require WOLFSSL_SYS_CA_CERTS for loading system CA [10] + o ALTSVC.md: correct a typo [14] + o asyn-ares: fix data race warning [88] + o asyn-thread: use wakeup_close to close the read descriptor [1] + o badwords: use hostname, not host name [46] + o BINDINGS: add mcurl, the python binding [67] + o bufq: writing into a softlimit queue cannot be partial [49] + o c-hyper: add header collection writer in hyper builds [70] + o cd2nroff: gen: make `\>` in input to render as plain '>' in output + o cd2nroff: remove backticks from titles + o checksrc.pl: fix handling .checksrc with CRLF [43] + o cmake: add USE_OPENSSL_QUIC support [21] + o cmake: add warning for using TLS libraries without 1.3 support [25] + o cmake: enable `ENABLE_CURL_MANUAL` by default [112] + o cmake: fix `CURL_WINDOWS_SSPI=ON` with Schannel disabled [117] + o cmake: fix function description in comment [47] + o cmake: fix install for older CMake versions [53] + o cmake: fix libcurl.pc and curl-config library specifications [115] + o cmdline-docs/Makefile: avoid using a fixed temp file name [5] + o cmdline-docs: quote and angle bracket cleanup [45] + o cmdline-opts/_EXITCODES: sync with libcurl-errors [80] + o cmdline-opts/_VARIABLES.md: improve the description [105] + o cmdline-opts/_VERSION: provide %VERSION correctly [87] + o cmdline-opts: shorter help texts [148] + o configure: add pkg-config support to rustls detection [151] + o configure: add warning for using TLS libraries without 1.3 support [26] + o configure: build & install shell completions when enabled [85] + o configure: do not link with nghttp3 unless necessary [7] + o configure: Don't build shell completions when disabled [68] + o configure: Don't make shell completions without perl [83] + o configure: find libpsl with pkg-config [79] + o connect.c: fix typo [17] + o CONTRIBUTE: update the section on documentation format [96] + o cookie.md: provide an example sending a fixed cookie [13] + o cookie: if psl fails, reject the cookie [107] + o curl: exit on config file parser errors [40] + o curl: make --libcurl output better CURLOPT_*SSLVERSION [127] + o curl: when allocating variables, add the name into the struct [37] + o curl_setup.h: add curl_uint64_t internal type + o curldown: fix email address in Copyright [89] + o CURLMOPT_MAX*: mention what happens if changed mid-transfer [154] + o CURLOPT_INTERFACE.md: remove spurious amp, add see-also [137] + o CURLOPT_POSTQUOTE.md: fix typo [36] + o CURLOPT_SSL_CTX_FUNCTION.md: no promises of lifetime after return [104] + o CURLOPT_WRITEFUNCTION.md: typo fix [41] + o digest: add check for hashing error [111] + o dist: make sure the http tests are in the tarball [29] + o DISTROS: add document with distro pointers [144] + o docs/libcurl: add TLS backend info for all TLS options [155] + o docs/libcurl: generate PROTOCOLS from meta-data [153] + o docs: add missing slashes to SChannel client certificate documentation [11] + o docs: add necessary setup for nghttp3 [51] + o docs: ascii version of manpage without nroff [121] + o docs: dist curl*.1 and install without perl [64] + o docs: make curldown do angle brackets like markdown [54] + o docs: make each libcurl man specify protocol(s) [157] + o docs: make sure curl.1 is included in dist tarballs [35] + o docs: update minimal binary size in INSTALL.md + o docs: use present tense [103] + o examples: use present tense in comments [97] + o file: use xfer buf for file:// transfers [23] + o fopen: fix narrowing conversion warning on 32-bit Android [100] + o form-string.md: correct the example [4] + o ftp: do lineend conversions in client writer [32] + o ftp: fix socket wait activity in ftp_domore_getsock [28] + o ftp: tracing improvements [33] + o ftp: treat a 226 arriving before data as a signal to read data [19] + o gen.pl: make the "manpageification" faster [95] + o gen: make `\>` in input to render as plain '>' in output [78] + o getparam: make --ftp-ssl work again [90] + o GHA/linux: add sysctl trick to work-around GitHub runner issue [129] + o GIT-INFO: convert to markdown [114] + o GOVERNANCE: document the core team [133] + o header.md: remove backslash, make nicer markdown [48] + o HTTP/2: write response directly [12] + o http2, http3: return CURLE_PARTIAL_FILE when bytes were received [160] + o http2: fix push discard [124] + o http2: memory errors in the push callbacks are fatal [132] + o http2: minor tweaks to optimize two struct sizes [130] + o http2: push headers better cleanup [113] + o http2: remove the third (unused) argument from http2_data_done() [159] + o HTTP3.md: adjust the OpenSSL QUIC install instructions [34] + o http: better error message for HTTP/1.x response without status line [86] + o http: improve response header handling, save cpu cycles [138] + o http: move headers collecting to writer [71] + o http: remove stale comment about rewindbeforesend [136] + o http: separate response parsing from response action [158] + o http_chunks: fix the accounting of consumed bytes [22] + o http_chunks: remove unused 'endptr' variable [58] + o https-proxy: use IP address and cert with ip in alt names [50] + o hyper: implement unpausing via client reader [98] + o ipv6.md: mention IPv4 mapped addresses [147] + o KNOWN_BUGS: POP3 issue when reading small chunks [134] + o lib1598: fix `CURLOPT_POSTFIELDSIZE` usage [128] + o lib582: remove code causing warning that is never run [38] + o lib: add `void *ctx` to reader/writer instances [122] + o lib: convert Curl_get_line to use dynbuf [42] + o lib: Curl_read/Curl_write clarifications [101] + o lib: enhance client reader resume + rewind [92] + o lib: initialize output pointers to NULL before calling strto[ff,l,ul] [63] + o lib: keep conn IP information together [109] + o lib: move 'done' parameter to SingleRequests [142] + o lib: remove curl_mimepart object when CURL_DISABLE_MIME [72] + o libcurl-docs: cleanups + o libcurl-security.md: Active FTP passes on the local IP address [6] + o libssh/libssh2: return error on too big range [75] + o MANUAL.md: fix typo [66] + o mbedtls: fix building when MBEDTLS_X509_REMOVE_INFO flag is defined [27] + o mbedtls: fix pytest for newer versions [146] + o mbedtls: properly cleanup the thread-shared entropy [140] + o mbedtls: use mbedtls_ssl_conf_{min|max}_tls_version [59] + o md4: include strdup.h for the memdup proto [10] + o mime: add client reader [126] + o misc: fix typos in docs and lib [84] + o mkhelp: simplify the generated hugehelp program [120] + o mprintf: fix format prefix I32/I64 for windows compilers [77] + o multi: add xfer_buf to multi handle [30] + o multi: fix multi_sock handling of select_bits [81] + o multi: make add_handle free any multi_easy [102] + o ngtcp2: no recvbuf for stream [108] + o ntml_wb: fix buffer type typo [2] + o OpenSSL QUIC: adapt to v3.3.x [65] + o openssl-quic: check on Windows that socket conv to int is possible [8] + o openssl-quic: fix BIO leak and Windows warning [93] + o openssl-quic: fix unity build, casing, indentation [94] + o OS400: avoid using awk in the build scripts [20] + o paramhlp: fix CRLF-stripping files with "-d @file" [116] + o proxy1.0.md: fix example [15] + o pytest: adapt to API change [106] + o request: clarify message when request has been sent off [143] + o rustls: make curl compile with 0.12.0 [73] + o schannel: fix hang on unexpected server close [57] + o scripts: fix cijobs.pl for Azure and GHA + o sendf: ignore response body to HEAD [18] + o setopt: fix check for CURLOPT_PROXY_TLSAUTH_TYPE value [76] + o setopt: fix disabling all protocols [99] + o sha512_256: add support for GnuTLS and OpenSSL [110] + o smtp: fix STARTTLS [91] + o SPONSORS: describe the basics [131] + o strtoofft: fix the overflow check [74] + o test 1541: verify getinfo values on first header callback [149] + o test1165: improve pattern matching [60] + o tests: support setting/using blank content env variables + o TIMER_STARTTRANSFER: set the same for everyone [82] + o TLS: start shutdown only when peer did not already close [150] + o TODO: update 13.11 with more information [152] + o tool_cb_hdr: only parse etag + content-disposition for 2xx [9] + o tool_getparam: accept a blank -w "" [139] + o tool_getparam: handle non-existing (out of range) short-options [141] + o tool_operate: change precedence of server Retry-After time [44] + o tool_operate: do not set CURLOPT_QUICK_EXIT in debug builds [3] + o trace-config.md: remove the mutexed options list [119] + o transfer.c: break receive loop in speed limited transfers [125] + o transfer: improve Windows SO_SNDBUF update limit [56] + o urldata: move authneg bit from conn to Curl_easy [69] + o version: allow building with ancient libpsl [52] + o vquic-tls: fix the error code returned for bad CA file [135] + o vtls: fix tls proxy peer verification [55] + o vtls: revert "receive max buffer" + add test case [39] + o VULN-DISCLOSURE-POLICY.md: update detail about CVE requests [123] + o websocket: fix curl_ws_recv() [62] + o wolfSSL: do not call the stub function wolfSSL_BIO_set_init() [145] + o write-out.md: clarify error handling details [31] This release includes the following known bugs: @@ -215,204 +192,188 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - 12932 on github, Alex Bozarth, Alexey Larikov, Alex Klyubin, Ammar Faizi, - Andrew Kurushin, Anubhav Rai, boilingoden, calvin2021y on github, - Carlos Henrique Lima Melara, Casey Bodley, Charlie C, Dan Fandrich, - Daniel Jeliński, Daniel Stenberg, David Benjamin, David Suter, Dmitry Karpov, - eeverettrbx on github, Emanuele Torre, Enno Boland, enWILLYado on github, - Faraz Fallahi, Gisle Vanem, Goro FUJI, Graham Campbell, Harry Mallon, - Harry Sintonen, iconoclasthero, icy17 on github, Jacob Hoffman-Andrews, - Jan Alexander Steffens, Jeroen Ooms, Jiehong on github, Jiri Hruska, - Junho Choi, Kai Pastor, Kareem, Kartatz on Github, kirbyn17 on hackerone, - Lau, lkordos on github, Loïc Yhuel, LoRd_MuldeR, lRoccoon on github, - Maksymilian Arciemowicz, Manfred Schwarb, Marcel Raad, Marcin Rataj, - Mark Gaiser, Martin Schmatz, Michael Kaufmann, Michał Antoniak, Nico Rieck, - Niracler Li, ohyeaah on github, Ophir Lojkine, Paweł Wegner, Philip Heiduck, - Ray Satiro, rilysh, Robert Southee, Romain Geissler, Sam James, - Samuel Henrique, sd0 on hackerone, Smackd0wn, Sohom Datta, Stefan Eissing, - Steven Allen, Tim Hill, Torben Dury, Turiiya, Viktor Szakats, - yushicheng7788 on github, z2_, zhengqwe on github, 積丹尼 Dan Jacobson - (78 contributors) + 5533asdg on github, Alan Coopersmith, Andreas Kiefer, Andrew Kaster, + Andy Fiddaman, Arjan van de Ven, av223119 on github, awesomekosm on github, + Boris Verkhovskiy, Brett Buddin, Brian Clemens, chensong1211 on github, + Chris Webb, chrysos349 on github, Dan Fandrich, Daniel Gustafsson, + Daniel Stenberg, Daniel Szmulewicz, Dan McDonald, DasKutti on github, + dependabot[bot], Dexter Gerig, dfdity on github, Dirk Hünniger, + Dmitry Karpov, Dmitry Tretyakov, edmcln on github, Erik Schnetter, + Evgeny Grin (Karlson2k), Fabian Keil, Fabian Vogt, Fabrice Fontaine, + Faraz Fallahi, Gaelan Steele, Geeknik Labs, Gisle Vanem, graywolf on github, + Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, Jiří Bok, + Joel Depooter, John Marshall, Jonathan Perkin, Jon Rumsey, Jordan Brown, + Josh Soref, Karthikdasari0423, Karthikdasari0423 on github, Kevin Daudt, + Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, + Lukáš Zaoral, Marcel Raad, Marcus Müller, Matt Jolly, Michael Forney, + Michael Kaufmann, Michał Antoniak, Michał Górny, Mohammadreza Hendiani, + Nikita Taranov, Outvi V, Patrick Monnerat, Paweł Witas, Pēteris Caune, + Peter Krefting, RainRat, Ramiro Garcia, Ray Satiro, Richard Levitte, + Robert Moreton, Ross Burton, Rudi Heitbaum, Ryan Carsten Schmidt, + Scott Mutter, Scott Talbert, Sean Molenaar, Sebastian Neubauer, + Sergey Bronnikov, Simon K, Stefan Eissing, Tal Regev, Thomas Pyle, + Till Wegmüller, Viktor Szakats, vulnerabilityspotter on hackerone, + Winni Neessen + (92 contributors) References to bug reports and discussions on issues: - [1] = https://curl.se/bug/?i=12084 - [2] = https://curl.se/bug/?i=12093 - [3] = https://curl.se/bug/?i=12116 - [4] = https://curl.se/bug/?i=12146 - [5] = https://curl.se/bug/?i=12064 - [6] = https://curl.se/bug/?i=12040 - [7] = https://curl.se/bug/?i=12082 - [8] = https://curl.se/bug/?i=12101 - [9] = https://curl.se/bug/?i=12099 - [10] = https://curl.se/bug/?i=12108 - [11] = https://curl.se/bug/?i=12102 - [12] = https://curl.se/bug/?i=12091 - [13] = https://curl.se/bug/?i=12090 - [14] = https://curl.se/bug/?i=12088 - [15] = https://curl.se/bug/?i=12022 - [16] = https://curl.se/bug/?i=12092 - [17] = https://curl.se/bug/?i=12115 - [18] = https://curl.se/bug/?i=12142 - [19] = https://curl.se/bug/?i=12125 - [20] = https://curl.se/bug/?i=12139 - [21] = https://curl.se/bug/?i=12107 - [22] = https://curl.se/bug/?i=12133 - [23] = https://curl.se/bug/?i=11285 - [24] = https://curl.se/bug/?i=12131 - [25] = https://curl.se/bug/?i=12124 - [26] = https://curl.se/bug/?i=12126 - [27] = https://curl.se/bug/?i=12117 - [28] = https://curl.se/bug/?i=12089 - [29] = https://curl.se/bug/?i=12166 - [30] = https://curl.se/bug/?i=12166 - [31] = https://curl.se/bug/?i=12137 - [32] = https://curl.se/bug/?i=12052 - [33] = https://curl.se/bug/?i=12097 - [34] = https://curl.se/bug/?i=12198 - [35] = https://curl.se/bug/?i=12145 - [36] = https://curl.se/bug/?i=12170 - [37] = https://curl.se/bug/?i=12168 - [38] = https://curl.se/bug/?i=11949 - [39] = https://curl.se/bug/?i=12165 - [40] = https://curl.se/bug/?i=12165 - [41] = https://curl.se/bug/?i=12140 - [42] = https://curl.se/bug/?i=11775 - [43] = https://curl.se/bug/?i=12157 - [44] = https://curl.se/bug/?i=12149 - [45] = https://curl.se/bug/?i=12201 - [46] = https://curl.se/bug/?i=12194 - [47] = https://curl.se/bug/?i=12249 - [48] = https://curl.se/bug/?i=12195 - [49] = https://curl.se/bug/?i=12218 - [50] = https://curl.se/bug/?i=12044 - [51] = https://curl.se/bug/?i=12189 - [52] = https://curl.se/bug/?i=12030 - [53] = https://curl.se/bug/?i=12179 - [54] = https://curl.se/bug/?i=12182 - [55] = https://curl.se/bug/?i=12086 - [56] = https://curl.se/bug/?i=12160 - [57] = https://curl.se/bug/?i=12221 - [58] = https://curl.se/bug/?i=12155 - [59] = https://curl.se/bug/?i=12250 - [60] = https://curl.se/bug/?i=12237 - [61] = https://curl.se/bug/?i=12213 - [62] = https://curl.se/bug/?i=12215 - [63] = https://curl.se/bug/?i=12214 - [64] = https://curl.se/bug/?i=12206 - [65] = https://curl.se/bug/?i=12207 - [66] = https://curl.se/bug/?i=12216 - [67] = https://curl.se/bug/?i=12247 - [68] = https://curl.se/bug/?i=12202 - [69] = https://curl.se/bug/?i=12200 - [70] = https://curl.se/bug/?i=12196 - [71] = https://curl.se/bug/?i=12083 - [72] = https://curl.se/bug/?i=12287 - [73] = https://curl.se/bug/?i=12242 - [74] = https://curl.se/bug/?i=12240 - [75] = https://curl.se/bug/?i=12240 - [76] = https://curl.se/bug/?i=12262 - [77] = https://curl.se/bug/?i=12235 - [78] = https://curl.se/bug/?i=12204 - [79] = https://curl.se/bug/?i=12233 - [80] = https://curl.se/bug/?i=12223 - [81] = https://curl.se/bug/?i=10521 - [82] = https://curl.se/bug/?i=12270 - [83] = https://curl.se/bug/?i=12230 - [84] = https://curl.se/bug/?i=12229 - [85] = https://curl.se/bug/?i=12227 - [86] = https://curl.se/bug/?i=12225 - [87] = https://curl.se/bug/?i=12148 - [88] = https://curl.se/bug/?i=8107 - [89] = https://curl.se/bug/?i=12199 - [90] = https://curl.se/bug/?i=12267 - [91] = https://curl.se/bug/?i=12264 - [92] = https://curl.se/bug/?i=12266 - [93] = https://curl.se/bug/?i=12263 - [94] = https://curl.se/bug/?i=12255 - [95] = https://curl.se/bug/?i=12239 - [96] = https://curl.se/bug/?i=11913 - [97] = https://curl.se/bug/?i=12251 - [98] = https://curl.se/bug/?i=12248 - [99] = https://curl.se/bug/?i=12315 - [100] = https://curl.se/bug/?i=12294 - [101] = https://curl.se/bug/?i=12289 - [102] = https://curl.se/bug/?i=12259 - [103] = https://curl.se/bug/?i=12288 - [104] = https://curl.se/bug/?i=12282 - [105] = https://curl.se/bug/?i=12315 - [106] = https://curl.se/bug/?i=12222 - [107] = https://curl.se/bug/?i=12275 - [108] = https://curl.se/bug/?i=12280 - [109] = https://curl.se/bug/?i=12337 - [110] = https://curl.se/bug/?i=12278 - [111] = https://curl.se/bug/?i=12257 - [112] = https://curl.se/bug/?i=12311 - [113] = https://curl.se/bug/?i=12277 - [114] = https://curl.se/bug/?i=12307 - [115] = https://curl.se/bug/?i=12228 - [116] = https://curl.se/bug/?i=12180 - [117] = https://curl.se/bug/?i=12321 - [118] = https://curl.se/bug/?i=12292 - [119] = https://curl.se/bug/?i=12152 - [120] = https://curl.se/bug/?i=12273 - [121] = https://curl.se/bug/?i=12261 - [122] = https://curl.se/bug/?i=12329 - [123] = https://curl.se/bug/?i=12325 - [124] = https://curl.se/bug/?i=12326 - [125] = https://curl.se/bug/?i=12324 - [126] = https://curl.se/bug/?i=12323 - [127] = https://curl.se/bug/?i=12310 - [128] = https://curl.se/bug/?i=12312 - [129] = https://curl.se/bug/?i=12320 - [130] = https://curl.se/mail/lib-2023-11/0017.html - [131] = https://curl.se/bug/?i=12318 - [132] = https://curl.se/bug/?i=12317 - [133] = https://curl.se/bug/?i=12365 - [134] = https://curl.se/bug/?i=12356 - [135] = https://curl.se/bug/?i=12346 - [136] = https://curl.se/bug/?i=12362 - [137] = https://curl.se/bug/?i=12357 - [138] = https://curl.se/bug/?i=12353 - [139] = https://curl.se/bug/?i=12191 - [140] = https://curl.se/bug/?i=12400 - [141] = https://curl.se/bug/?i=12347 - [142] = https://curl.se/bug/?i=12399 - [143] = https://curl.se/bug/?i=12352 - [144] = https://curl.se/bug/?i=12351 - [145] = https://curl.se/bug/?i=12350 - [146] = https://curl.se/bug/?i=12345 - [147] = https://curl.se/bug/?i=12344 - [148] = https://curl.se/bug/?i=12343 - [149] = https://curl.se/bug/?i=12338 - [150] = https://curl.se/bug/?i=12402 - [152] = https://curl.se/bug/?i=12410 - [153] = https://curl.se/bug/?i=12299 - [154] = https://curl.se/bug/?i=11647 - [155] = https://curl.se/bug/?i=12388 - [156] = https://curl.se/bug/?i=12424 - [157] = https://curl.se/bug/?i=12452 - [158] = https://curl.se/bug/?i=12449 - [159] = https://curl.se/bug/?i=12407 - [160] = https://curl.se/bug/?i=12387 - [161] = https://curl.se/bug/?i=12384 - [162] = https://curl.se/bug/?i=12378 - [163] = https://curl.se/bug/?i=12376 - [164] = https://curl.se/bug/?i=12409 - [165] = https://curl.se/bug/?i=12382 - [166] = https://curl.se/bug/?i=12375 - [167] = https://curl.se/bug/?i=12403 - [168] = https://curl.se/bug/?i=12381 - [169] = https://curl.se/bug/?i=12374 - [170] = https://curl.se/bug/?i=12374 - [171] = https://curl.se/bug/?i=12374 - [172] = https://curl.se/bug/?i=12331 - [173] = https://curl.se/bug/?i=12367 - [174] = https://curl.se/bug/?i=12440 - [175] = https://curl.se/bug/?i=12448 - [176] = https://curl.se/bug/?i=12439 - [178] = https://curl.se/bug/?i=12435 - [179] = https://curl.se/bug/?i=12434 - [181] = https://curl.se/bug/?i=12431 - [182] = https://curl.se/bug/?i=12430 - [183] = https://curl.se/bug/?i=12428 + [1] = https://curl.se/bug/?i=12836 + [2] = https://curl.se/bug/?i=12825 + [3] = https://curl.se/bug/?i=12834 + [4] = https://curl.se/bug/?i=12822 + [5] = https://curl.se/bug/?i=12829 + [6] = https://curl.se/bug/?i=12867 + [7] = https://curl.se/bug/?i=12833 + [8] = https://curl.se/bug/?i=12861 + [9] = https://curl.se/bug/?i=12866 + [10] = https://curl.se/bug/?i=12849 + [11] = https://curl.se/bug/?i=12854 + [12] = https://curl.se/bug/?i=12828 + [13] = https://curl.se/bug/?i=12868 + [14] = https://curl.se/bug/?i=12852 + [15] = https://curl.se/bug/?i=12856 + [16] = https://curl.se/bug/?i=12832 + [17] = https://curl.se/bug/?i=12858 + [18] = https://curl.se/mail/lib-2024-02/0000.html + [19] = https://curl.se/bug/?i=12823 + [20] = https://curl.se/bug/?i=12826 + [21] = https://curl.se/bug/?i=13034 + [22] = https://curl.se/bug/?i=12937 + [23] = https://curl.se/bug/?i=12750 + [24] = https://curl.se/bug/?i=12719 + [25] = https://curl.se/bug/?i=12900 + [26] = https://curl.se/bug/?i=12900 + [27] = https://curl.se/bug/?i=12904 + [28] = https://curl.se/bug/?i=12901 + [29] = https://curl.se/bug/?i=12914 + [30] = https://curl.se/bug/?i=12805 + [31] = https://curl.se/bug/?i=12909 + [32] = https://curl.se/bug/?i=12878 + [33] = https://curl.se/bug/?i=12902 + [34] = https://curl.se/bug/?i=12896 + [35] = https://curl.se/bug/?i=12892 + [36] = https://curl.se/bug/?i=12926 + [37] = https://curl.se/bug/?i=12891 + [38] = https://curl.se/bug/?i=12890 + [39] = https://curl.se/bug/?i=12885 + [40] = https://curl.se/mail/archive-2024-02/0008.html + [41] = https://curl.se/bug/?i=12889 + [42] = https://curl.se/bug/?i=12846 + [43] = https://curl.se/bug/?i=12924 + [44] = https://curl.se/mail/archive-2024-01/0022.html + [45] = https://curl.se/bug/?i=12884 + [46] = https://curl.se/bug/?i=12888 + [47] = https://curl.se/bug/?i=12879 + [48] = https://curl.se/bug/?i=12877 + [49] = https://curl.se/bug/?i=13020 + [50] = https://curl.se/bug/?i=12838 + [51] = https://curl.se/bug/?i=12859 + [52] = https://curl.se/mail/archive-2024-02/0004.html + [53] = https://curl.se/bug/?i=12920 + [54] = https://curl.se/bug/?i=12869 + [55] = https://curl.se/bug/?i=12831 + [56] = https://curl.se/bug/?i=12911 + [57] = https://curl.se/bug/?i=12894 + [58] = https://curl.se/bug/?i=12996 + [59] = https://curl.se/bug/?i=12905 + [60] = https://curl.se/bug/?i=12903 + [61] = https://curl.se/bug/?i=12411 + [62] = https://curl.se/bug/?i=12945 + [63] = https://curl.se/bug/?i=12995 + [64] = https://curl.se/bug/?i=12921 + [65] = https://curl.se/bug/?i=12933 + [66] = https://curl.se/bug/?i=12965 + [67] = https://curl.se/bug/?i=12962 + [68] = https://curl.se/bug/?i=13027 + [69] = https://curl.se/bug/?i=12949 + [70] = https://curl.se/bug/?i=12880 + [71] = https://curl.se/bug/?i=12880 + [72] = https://curl.se/bug/?i=12948 + [73] = https://curl.se/bug/?i=12989 + [74] = https://curl.se/bug/?i=12990 + [75] = https://curl.se/bug/?i=12983 + [76] = https://curl.se/bug/?i=12981 + [77] = https://curl.se/bug/?i=12944 + [78] = https://curl.se/bug/?i=12977 + [79] = https://curl.se/bug/?i=12947 + [80] = https://curl.se/bug/?i=13015 + [81] = https://curl.se/bug/?i=12971 + [82] = https://curl.se/bug/?i=13052 + [83] = https://curl.se/bug/?i=13022 + [84] = https://curl.se/bug/?i=13019 + [85] = https://curl.se/bug/?i=12906 + [86] = https://curl.se/bug/?i=13045 + [87] = https://curl.se/bug/?i=13008 + [88] = https://curl.se/bug/?i=13065 + [89] = https://curl.se/bug/?i=12997 + [90] = https://curl.se/bug/?i=13006 + [91] = https://curl.se/bug/?i=13048 + [92] = https://curl.se/bug/?i=13026 + [93] = https://curl.se/bug/?i=13043 + [94] = https://curl.se/bug/?i=13044 + [95] = https://curl.se/bug/?i=13041 + [96] = https://curl.se/bug/?i=13046 + [97] = https://curl.se/bug/?i=13003 + [98] = https://curl.se/bug/?i=13075 + [99] = https://curl.se/bug/?i=13004 + [100] = https://curl.se/bug/?i=12998 + [101] = https://curl.se/bug/?i=12964 + [102] = https://curl.se/bug/?i=12992 + [103] = https://curl.se/bug/?i=13001 + [104] = https://curl.se/bug/?i=12999 + [105] = https://curl.se/bug/?i=13040 + [106] = https://curl.se/bug/?i=13037 + [107] = https://curl.se/bug/?i=13033 + [108] = https://curl.se/bug/?i=13073 + [109] = https://curl.se/bug/?i=13084 + [110] = https://curl.se/bug/?i=13070 + [111] = https://curl.se/bug/?i=13072 + [112] = https://curl.se/bug/?i=13028 + [113] = https://curl.se/bug/?i=13054 + [114] = https://curl.se/bug/?i=13074 + [115] = https://curl.se/bug/?i=6169 + [116] = https://curl.se/bug/?i=13063 + [117] = https://curl.se/bug/?i=13061 + [118] = https://curl.se/bug/?i=12897 + [119] = https://curl.se/bug/?i=13031 + [120] = https://curl.se/bug/?i=13047 + [121] = https://curl.se/bug/?i=13047 + [122] = https://curl.se/bug/?i=13035 + [123] = https://curl.se/bug/?i=13088 + [124] = https://curl.se/bug/?i=13055 + [125] = https://curl.se/mail/lib-2024-03/0001.html + [126] = https://curl.se/bug/?i=13039 + [127] = https://curl.se/bug/?i=13127 + [128] = https://curl.se/bug/?i=13085 + [129] = https://curl.se/bug/?i=13124 + [130] = https://curl.se/bug/?i=13082 + [131] = https://curl.se/bug/?i=13119 + [132] = https://curl.se/bug/?i=13081 + [133] = https://curl.se/bug/?i=13118 + [134] = https://curl.se/bug/?i=12063 + [135] = https://curl.se/bug/?i=13115 + [136] = https://curl.se/bug/?i=13187 + [137] = https://curl.se/bug/?i=13149 + [138] = https://curl.se/bug/?i=13143 + [139] = https://curl.se/bug/?i=13144 + [140] = https://curl.se/bug/?i=11919 + [141] = https://curl.se/bug/?i=13101 + [142] = https://curl.se/bug/?i=13096 + [143] = https://curl.se/bug/?i=13093 + [144] = https://curl.se/bug/?i=13178 + [145] = https://curl.se/bug/?i=13164 + [146] = https://curl.se/bug/?i=13132 + [147] = https://curl.se/bug/?i=13112 + [148] = https://curl.se/bug/?i=13169 + [149] = https://curl.se/bug/?i=13128 + [150] = https://curl.se/bug/?i=10290 + [151] = https://curl.se/bug/?i=13179 + [152] = https://curl.se/bug/?i=13173 + [153] = https://curl.se/bug/?i=13175 + [154] = https://curl.se/bug/?i=13176 + [155] = https://curl.se/bug/?i=13168 + [157] = https://curl.se/bug/?i=13166 + [158] = https://curl.se/bug/?i=13134 + [159] = https://curl.se/bug/?i=13154 + [160] = https://curl.se/bug/?i=13151 diff --git a/acinclude.m4 b/acinclude.m4 index ac026e39d21..a44ae350e36 100644 --- a/acinclude.m4 +++ b/acinclude.m4 @@ -156,7 +156,6 @@ AC_DEFUN([CURL_CHECK_AIX_ALL_SOURCE], [ #endif]) AC_BEFORE([$0], [AC_SYS_LARGEFILE])dnl AC_BEFORE([$0], [CURL_CONFIGURE_REENTRANT])dnl - AC_BEFORE([$0], [CURL_CONFIGURE_PULL_SYS_POLL])dnl AC_MSG_CHECKING([if OS is AIX (to define _ALL_SOURCE)]) AC_EGREP_CPP([yes_this_is_aix],[ #ifdef _AIX @@ -171,144 +170,28 @@ AC_DEFUN([CURL_CHECK_AIX_ALL_SOURCE], [ ]) -dnl CURL_CHECK_HEADER_WINDOWS -dnl ------------------------------------------------- -dnl Check for compilable and valid windows.h header - -AC_DEFUN([CURL_CHECK_HEADER_WINDOWS], [ - AC_CACHE_CHECK([for windows.h], [curl_cv_header_windows_h], [ - AC_COMPILE_IFELSE([ - AC_LANG_PROGRAM([[ -#undef inline -#ifndef WIN32_LEAN_AND_MEAN -#define WIN32_LEAN_AND_MEAN -#endif -#include - ]],[[ -#if defined(__CYGWIN__) || defined(__CEGCC__) - HAVE_WINDOWS_H shall not be defined. -#else - int dummy=2*WINVER; -#endif - ]]) - ],[ - curl_cv_header_windows_h="yes" - ],[ - curl_cv_header_windows_h="no" - ]) - ]) - case "$curl_cv_header_windows_h" in - yes) - AC_DEFINE_UNQUOTED(HAVE_WINDOWS_H, 1, - [Define to 1 if you have the windows.h header file.]) - ;; - esac -]) - - dnl CURL_CHECK_NATIVE_WINDOWS dnl ------------------------------------------------- dnl Check if building a native Windows target AC_DEFUN([CURL_CHECK_NATIVE_WINDOWS], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINDOWS])dnl AC_CACHE_CHECK([whether build target is a native Windows one], [curl_cv_native_windows], [ - if test "$curl_cv_header_windows_h" = "no"; then - curl_cv_native_windows="no" - else - AC_COMPILE_IFELSE([ - AC_LANG_PROGRAM([[ - ]],[[ -#if defined(__MINGW32__) || defined(__MINGW32CE__) || \ - (defined(_MSC_VER) && (defined(_WIN32) || defined(_WIN64))) - int dummy=1; -#else - Not a native Windows build target. -#endif - ]]) - ],[ - curl_cv_native_windows="yes" - ],[ - curl_cv_native_windows="no" - ]) - fi - ]) - AM_CONDITIONAL(DOING_NATIVE_WINDOWS, test "x$curl_cv_native_windows" = xyes) -]) - - -dnl CURL_CHECK_HEADER_WINSOCK2 -dnl ------------------------------------------------- -dnl Check for compilable and valid winsock2.h header - -AC_DEFUN([CURL_CHECK_HEADER_WINSOCK2], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINDOWS])dnl - AC_CACHE_CHECK([for winsock2.h], [curl_cv_header_winsock2_h], [ AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ -#undef inline -#ifndef WIN32_LEAN_AND_MEAN -#define WIN32_LEAN_AND_MEAN -#endif -#include -#include ]],[[ -#if defined(__CYGWIN__) || defined(__CEGCC__) || defined(__MINGW32CE__) - HAVE_WINSOCK2_H shall not be defined. +#ifdef _WIN32 + int dummy=1; #else - int dummy=2*IPPROTO_ESP; + Not a native Windows build target. #endif ]]) ],[ - curl_cv_header_winsock2_h="yes" + curl_cv_native_windows="yes" ],[ - curl_cv_header_winsock2_h="no" - ]) - ]) - case "$curl_cv_header_winsock2_h" in - yes) - AC_DEFINE_UNQUOTED(HAVE_WINSOCK2_H, 1, - [Define to 1 if you have the winsock2.h header file.]) - ;; - esac -]) - - -dnl CURL_CHECK_HEADER_WS2TCPIP -dnl ------------------------------------------------- -dnl Check for compilable and valid ws2tcpip.h header - -AC_DEFUN([CURL_CHECK_HEADER_WS2TCPIP], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINSOCK2])dnl - AC_CACHE_CHECK([for ws2tcpip.h], [curl_cv_header_ws2tcpip_h], [ - AC_COMPILE_IFELSE([ - AC_LANG_PROGRAM([[ -#undef inline -#ifndef WIN32_LEAN_AND_MEAN -#define WIN32_LEAN_AND_MEAN -#endif -#include -#include -#include - ]],[[ -#if defined(__CYGWIN__) || defined(__CEGCC__) || defined(__MINGW32CE__) - HAVE_WS2TCPIP_H shall not be defined. -#else - int dummy=2*IP_PKTINFO; -#endif - ]]) - ],[ - curl_cv_header_ws2tcpip_h="yes" - ],[ - curl_cv_header_ws2tcpip_h="no" + curl_cv_native_windows="no" ]) ]) - case "$curl_cv_header_ws2tcpip_h" in - yes) - AC_DEFINE_UNQUOTED(HAVE_WS2TCPIP_H, 1, - [Define to 1 if you have the ws2tcpip.h header file.]) - ;; - esac + AM_CONDITIONAL(DOING_NATIVE_WINDOWS, test "x$curl_cv_native_windows" = xyes) ]) @@ -318,12 +201,12 @@ dnl Check for compilable and valid lber.h header, dnl and check if it is needed even with ldap.h AC_DEFUN([CURL_CHECK_HEADER_LBER], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINDOWS])dnl + AC_REQUIRE([CURL_CHECK_NATIVE_WINDOWS])dnl AC_CACHE_CHECK([for lber.h], [curl_cv_header_lber_h], [ AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif @@ -355,7 +238,7 @@ AC_DEFUN([CURL_CHECK_HEADER_LBER], [ AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif @@ -403,7 +286,7 @@ AC_DEFUN([CURL_CHECK_HEADER_LDAP], [ AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif @@ -449,7 +332,7 @@ AC_DEFUN([CURL_CHECK_HEADER_LDAP_SSL], [ AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif @@ -534,7 +417,7 @@ AC_DEFUN([CURL_CHECK_LIBS_WINLDAP], [ AC_LINK_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif @@ -632,7 +515,7 @@ AC_DEFUN([CURL_CHECK_LIBS_LDAP], [ AC_LINK_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif @@ -701,14 +584,11 @@ AC_DEFUN([TYPE_SOCKADDR_STORAGE], [if struct sockaddr_storage is defined]), , [ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include -#endif -#include #else #ifdef HAVE_SYS_TYPES_H #include @@ -731,7 +611,7 @@ dnl ------------------------------------------------- dnl Test if the socket recv() function is available, AC_DEFUN([CURL_CHECK_FUNC_RECV], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINSOCK2])dnl + AC_REQUIRE([CURL_CHECK_NATIVE_WINDOWS])dnl AC_REQUIRE([CURL_INCLUDES_BSDSOCKET])dnl AC_CHECK_HEADERS(sys/types.h sys/socket.h) # @@ -739,14 +619,11 @@ AC_DEFUN([CURL_CHECK_FUNC_RECV], [ AC_LINK_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include -#endif -#include #else $curl_includes_bsdsocket #ifdef HAVE_SYS_TYPES_H @@ -782,7 +659,7 @@ dnl ------------------------------------------------- dnl Test if the socket send() function is available, AC_DEFUN([CURL_CHECK_FUNC_SEND], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINSOCK2])dnl + AC_REQUIRE([CURL_CHECK_NATIVE_WINDOWS])dnl AC_REQUIRE([CURL_INCLUDES_BSDSOCKET])dnl AC_CHECK_HEADERS(sys/types.h sys/socket.h) # @@ -790,14 +667,11 @@ AC_DEFUN([CURL_CHECK_FUNC_SEND], [ AC_LINK_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include -#endif -#include #else $curl_includes_bsdsocket #ifdef HAVE_SYS_TYPES_H @@ -837,14 +711,11 @@ AC_DEFUN([CURL_CHECK_MSG_NOSIGNAL], [ AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include -#endif -#include #else #ifdef HAVE_SYS_TYPES_H #include @@ -876,21 +747,18 @@ dnl ------------------------------------------------- dnl Check for timeval struct AC_DEFUN([CURL_CHECK_STRUCT_TIMEVAL], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINSOCK2])dnl + AC_REQUIRE([CURL_CHECK_NATIVE_WINDOWS])dnl AC_CHECK_HEADERS(sys/types.h sys/time.h sys/socket.h) AC_CACHE_CHECK([for struct timeval], [curl_cv_struct_timeval], [ AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include #endif -#include -#endif #ifdef HAVE_SYS_TYPES_H #include #endif @@ -937,14 +805,11 @@ AC_DEFUN([TYPE_IN_ADDR_T], [ AC_LINK_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include -#endif -#include #else #ifdef HAVE_SYS_TYPES_H #include @@ -979,14 +844,11 @@ AC_DEFUN([TYPE_IN_ADDR_T], [ esac ],[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include -#endif -#include #else #ifdef HAVE_SYS_TYPES_H #include @@ -1197,7 +1059,7 @@ AC_DEFUN([CURL_CHECK_LIBS_CONNECT], [ AC_LANG_PROGRAM([[ $curl_includes_winsock2 $curl_includes_bsdsocket - #if !defined(HAVE_WINDOWS_H) && !defined(HAVE_PROTO_BSDSOCKET_H) + #if !defined(_WIN32) && !defined(HAVE_PROTO_BSDSOCKET_H) int connect(int, void*, int); #endif ]],[[ @@ -1246,40 +1108,6 @@ cat >>confdefs.h <<_EOF _EOF ]) -dnl CURL_CONFIGURE_PULL_SYS_POLL -dnl ------------------------------------------------- -dnl The need for the sys/poll.h inclusion arises mainly to properly -dnl interface AIX systems which define macros 'events' and 'revents'. - -AC_DEFUN([CURL_CONFIGURE_PULL_SYS_POLL], [ - AC_REQUIRE([CURL_INCLUDES_POLL])dnl - # - tst_poll_events_macro_defined="unknown" - # - AC_COMPILE_IFELSE([ - AC_LANG_PROGRAM([[ - $curl_includes_poll - ]],[[ -#if defined(events) || defined(revents) - return 0; -#else - force compilation error -#endif - ]]) - ],[ - tst_poll_events_macro_defined="yes" - ],[ - tst_poll_events_macro_defined="no" - ]) - # - if test "$tst_poll_events_macro_defined" = "yes"; then - if test "x$ac_cv_header_sys_poll_h" = "xyes"; then - CURL_DEFINE_UNQUOTED([CURL_PULL_SYS_POLL_H]) - fi - fi - # -]) - dnl CURL_CHECK_FUNC_SELECT dnl ------------------------------------------------- @@ -1294,15 +1122,12 @@ AC_DEFUN([CURL_CHECK_FUNC_SELECT], [ AC_LINK_IFELSE([ AC_LANG_PROGRAM([[ #undef inline -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include #endif -#include -#endif #ifdef HAVE_SYS_TYPES_H #include #endif @@ -1310,7 +1135,7 @@ AC_DEFUN([CURL_CHECK_FUNC_SELECT], [ #include #endif #include -#ifndef HAVE_WINDOWS_H +#ifndef _WIN32 #ifdef HAVE_SYS_SELECT_H #include #elif defined(HAVE_UNISTD_H) @@ -1547,17 +1372,15 @@ dnl ------------------------------------------------- dnl Check if curl's WIN32 large file will be used AC_DEFUN([CURL_CHECK_WIN32_LARGEFILE], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINDOWS])dnl + AC_REQUIRE([CURL_CHECK_NATIVE_WINDOWS])dnl AC_MSG_CHECKING([whether build target supports WIN32 file API]) curl_win32_file_api="no" - if test "$curl_cv_header_windows_h" = "yes"; then + if test "$curl_cv_native_windows" = "yes"; then if test x"$enable_largefile" != "xno"; then AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ ]],[[ -#if !defined(_WIN32_WCE) && \ - (defined(__MINGW32__) || \ - (defined(_MSC_VER) && (defined(_WIN32) || defined(_WIN64)))) +#if !defined(_WIN32_WCE) && (defined(__MINGW32__) || defined(_MSC_VER)) int dummy=1; #else WIN32 large file API not supported. @@ -1606,10 +1429,10 @@ dnl ------------------------------------------------- dnl Check if curl's WIN32 crypto lib can be used AC_DEFUN([CURL_CHECK_WIN32_CRYPTO], [ - AC_REQUIRE([CURL_CHECK_HEADER_WINDOWS])dnl + AC_REQUIRE([CURL_CHECK_NATIVE_WINDOWS])dnl AC_MSG_CHECKING([whether build target supports WIN32 crypto API]) curl_win32_crypto_api="no" - if test "$curl_cv_header_windows_h" = "yes"; then + if test "$curl_cv_native_windows" = "yes"; then AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ #undef inline diff --git a/appveyor.sh b/appveyor.sh new file mode 100644 index 00000000000..87c9d572a80 --- /dev/null +++ b/appveyor.sh @@ -0,0 +1,160 @@ +#!/usr/bin/env bash +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| +# +# Copyright (C) Daniel Stenberg, , et al. +# +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at https://curl.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +# SPDX-License-Identifier: curl +# +########################################################################### + +# shellcheck disable=SC3040,SC2039 +set -eux; [ -n "${BASH:-}${ZSH_NAME:-}" ] && set -o pipefail + +# build + +if [ "${APPVEYOR_BUILD_WORKER_IMAGE}" = 'Visual Studio 2022' ]; then + openssl_root_win='C:/OpenSSL-v30-Win64' +else + openssl_root_win='C:/OpenSSL-v111-Win64' +fi +openssl_root="$(cygpath -u "${openssl_root_win}")" + +if [ "${BUILD_SYSTEM}" = 'CMake' ]; then + options='' + [[ "${TARGET:-}" = *'ARM64'* ]] && SKIP_RUN='ARM64 architecture' + [ "${OPENSSL}" = 'ON' ] && options+=" -DOPENSSL_ROOT_DIR=${openssl_root_win}" + [ "${OPENSSL}" = 'ON' ] && options+=" -DOPENSSL_ROOT_DIR=${openssl_root_win}" + [ "${PRJ_CFG}" = 'Debug' ] && options+=' -DCMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG=' + [ "${PRJ_CFG}" = 'Release' ] && options+=' -DCMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE=' + [[ "${PRJ_GEN}" = *'Visual Studio'* ]] && options+=' -DCMAKE_VS_GLOBALS=TrackFileAccess=false' + # Fails to run without this run due to missing MSVCR90.dll + [ "${PRJ_GEN}" = 'Visual Studio 9 2008' ] && options+=' -DCURL_STATIC_CRT=ON' + # shellcheck disable=SC2086 + cmake -B _bld "-G${PRJ_GEN}" ${TARGET:-} ${options} \ + "-DCURL_USE_OPENSSL=${OPENSSL}" \ + "-DCURL_USE_SCHANNEL=${SCHANNEL}" \ + "-DHTTP_ONLY=${HTTP_ONLY}" \ + "-DBUILD_SHARED_LIBS=${SHARED}" \ + "-DBUILD_TESTING=${TESTING}" \ + "-DENABLE_WEBSOCKETS=${WEBSOCKETS:-}" \ + "-DCMAKE_UNITY_BUILD=${UNITY}" \ + '-DCURL_WERROR=ON' \ + "-DENABLE_DEBUG=${DEBUG}" \ + "-DENABLE_UNICODE=${ENABLE_UNICODE}" \ + '-DCMAKE_INSTALL_PREFIX=C:/CURL' \ + "-DCMAKE_BUILD_TYPE=${PRJ_CFG}" + # shellcheck disable=SC2086 + cmake --build _bld --config "${PRJ_CFG}" --parallel 2 --clean-first -- ${BUILD_OPT:-} + if [ "${SHARED}" = 'ON' ]; then + cp -f -p _bld/lib/*.dll _bld/src/ + fi + if [ "${OPENSSL}" = 'ON' ]; then + cp -f -p "${openssl_root}"/*.dll _bld/src/ + fi + curl='_bld/src/curl.exe' +elif [ "${BUILD_SYSTEM}" = 'VisualStudioSolution' ]; then + ( + cd projects + ./generate.bat "${VC_VERSION}" + msbuild.exe -maxcpucount "-property:Configuration=${PRJ_CFG}" "Windows/${VC_VERSION}/curl-all.sln" + ) + curl="build/Win32/${VC_VERSION}/${PRJ_CFG}/curld.exe" +elif [ "${BUILD_SYSTEM}" = 'winbuild_vs2015' ]; then + ./buildconf.bat + ( + cd winbuild + cat << EOF > _make.bat + call "C:/Program Files/Microsoft SDKs/Windows/v7.1/Bin/SetEnv.cmd" /x64 + call "C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/vcvarsall.bat" x86_amd64 + nmake -f Makefile.vc mode=dll VC=14 "SSL_PATH=${openssl_root_win}" WITH_SSL=dll MACHINE=x64 DEBUG=${DEBUG} ENABLE_UNICODE=${ENABLE_UNICODE} +EOF + ./_make.bat + rm _make.bat + ) + curl="builds/libcurl-vc14-x64-${PATHPART}-dll-ssl-dll-ipv6-sspi/bin/curl.exe" +elif [ "${BUILD_SYSTEM}" = 'winbuild_vs2017' ]; then + ./buildconf.bat + ( + cd winbuild + cat << EOF > _make.bat + call "C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Auxiliary/Build/vcvars64.bat" + nmake -f Makefile.vc mode=dll VC=14.10 "SSL_PATH=${openssl_root_win}" WITH_SSL=dll MACHINE=x64 DEBUG=${DEBUG} ENABLE_UNICODE=${ENABLE_UNICODE} +EOF + ./_make.bat + rm _make.bat + ) + curl="builds/libcurl-vc14.10-x64-${PATHPART}-dll-ssl-dll-ipv6-sspi/bin/curl.exe" +elif [ "${BUILD_SYSTEM}" = 'autotools' ]; then + autoreconf -fi + ( + mkdir _bld + cd _bld + # shellcheck disable=SC2086 + ../configure ${CONFIG_ARGS:-} + make -j2 V=1 + make -j2 V=1 examples + cd tests + make -j2 V=1 + ) + curl='_bld/src/curl.exe' +fi + +find . -name '*.exe' -o -name '*.dll' +if [ -z "${SKIP_RUN:-}" ]; then + "${curl}" --version +else + echo "Skip running curl.exe. Reason: ${SKIP_RUN}" +fi + +if false; then + for log in CMakeFiles/CMakeConfigureLog.yaml CMakeFiles/CMakeOutput.log CMakeFiles/CMakeError.log; do + [ -r "_bld/${log}" ] && cat "_bld/${log}" + done +fi + +if [ "${TESTING}" = 'ON' ] && [ "${BUILD_SYSTEM}" = 'CMake' ]; then + cmake --build _bld --config "${PRJ_CFG}" --parallel 2 --target testdeps +fi + +# test + +if [ "${TESTING}" = 'ON' ]; then + export TFLAGS='' + if [ -x "$(cygpath -u "${WINDIR}/System32/curl.exe")" ]; then + TFLAGS+=" -ac $(cygpath -u "${WINDIR}/System32/curl.exe")" + elif [ -x "$(cygpath -u "C:/msys64/usr/bin/curl.exe")" ]; then + TFLAGS+=" -ac $(cygpath -u "C:/msys64/usr/bin/curl.exe")" + fi + TFLAGS+=" ${DISABLED_TESTS:-}" + if [ "${BUILD_SYSTEM}" = 'CMake' ]; then + ls _bld/lib/*.dll >/dev/null 2>&1 && cp -f -p _bld/lib/*.dll _bld/tests/libtest/ + cmake --build _bld --config "${PRJ_CFG}" --target test-ci + elif [ "${BUILD_SYSTEM}" = 'autotools' ]; then + ( + cd _bld + make -j2 V=1 test-ci + ) + else + ( + TFLAGS="-a -p !flaky -r -rm ${TFLAGS}" + cd _bld/tests + ./runtests.pl + ) + fi +fi diff --git a/appveyor.yml b/appveyor.yml index 175f298d53a..7fd1a6629cb 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -84,8 +84,7 @@ environment: ENABLE_UNICODE: 'OFF' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1139 !1501' - ADD_PATH: 'C:\msys64\usr\bin' + DISABLED_TESTS: '!1139 !1501 !1140 !1173 !1177 !1477' - job_name: 'CMake, VS2022, Debug, x64, Schannel, Static, Unicode' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022' BUILD_SYSTEM: CMake @@ -96,8 +95,7 @@ environment: ENABLE_UNICODE: 'ON' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1139 !1501' - ADD_PATH: 'C:\msys64\usr\bin' + DISABLED_TESTS: '!1139 !1501 !1140 !1173 !1177 !1477' - job_name: 'CMake, VS2022, Debug, x64, no SSL, Static' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022' BUILD_SYSTEM: CMake @@ -108,8 +106,7 @@ environment: ENABLE_UNICODE: 'OFF' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1139 !1501' - ADD_PATH: 'C:\msys64\usr\bin' + DISABLED_TESTS: '!1139 !1501 !1140 !1173 !1177 !1477' - job_name: 'CMake, VS2022, Debug, x64, no SSL, Static, HTTP only' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022' BUILD_SYSTEM: CMake @@ -120,8 +117,7 @@ environment: ENABLE_UNICODE: 'OFF' HTTP_ONLY: 'ON' TESTING: 'ON' - DISABLED_TESTS: '!1139 !1501' - ADD_PATH: 'C:\msys64\usr\bin' + DISABLED_TESTS: '!1139 !1501 !1140 !1173 !1177 !1477' # generated CMake-based MSYS Makefiles builds (mingw cross-compiling) - job_name: 'CMake, mingw-w64, gcc 13, Debug, x64, Schannel, Static, Unicode, Unity' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022' @@ -132,8 +128,8 @@ environment: ENABLE_UNICODE: 'ON' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1086 !1139 !1451 !1501' - ADD_PATH: 'C:\msys64\mingw64\bin;C:\msys64\usr\bin' + DISABLED_TESTS: '!1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477' + ADD_PATH: 'C:/msys64/mingw64/bin' MSYS2_ARG_CONV_EXCL: '/*' BUILD_OPT: -k UNITY: 'ON' @@ -146,8 +142,8 @@ environment: ENABLE_UNICODE: 'ON' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1086 !1139 !1451 !1501' - ADD_PATH: 'C:\mingw-w64\x86_64-7.2.0-posix-seh-rt_v5-rev1\mingw64\bin;C:\msys64\usr\bin' + DISABLED_TESTS: '!1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477' + ADD_PATH: 'C:/mingw-w64/x86_64-7.2.0-posix-seh-rt_v5-rev1/mingw64/bin' MSYS2_ARG_CONV_EXCL: '/*' BUILD_OPT: -k - job_name: 'CMake, mingw-w64, gcc 9, Debug, x64, Schannel, Static, Unity' @@ -160,8 +156,8 @@ environment: HTTP_ONLY: 'OFF' TESTING: 'ON' # test 286 disabled due to https://github.com/curl/curl/issues/12040 - DISABLED_TESTS: '~286 !1086 !1139 !1451 !1501' - ADD_PATH: 'C:\msys64\mingw64\bin;C:\msys64\usr\bin' + DISABLED_TESTS: '~286 !1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477' + ADD_PATH: 'C:/msys64/mingw64/bin' MSYS2_ARG_CONV_EXCL: '/*' BUILD_OPT: -k UNITY: 'ON' @@ -174,8 +170,8 @@ environment: ENABLE_UNICODE: 'OFF' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1086 !1139 !1451 !1501' - ADD_PATH: 'C:\mingw-w64\i686-6.3.0-posix-dwarf-rt_v5-rev1\mingw32\bin;C:\msys64\usr\bin' + DISABLED_TESTS: '!1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477' + ADD_PATH: 'C:/mingw-w64/i686-6.3.0-posix-dwarf-rt_v5-rev1/mingw32/bin' MSYS2_ARG_CONV_EXCL: '/*' BUILD_OPT: -k # winbuild-based builds @@ -248,176 +244,42 @@ environment: BUILD_SYSTEM: autotools TESTING: 'ON' DISABLED_TESTS: '!19 !1233' - ADD_PATH: 'C:\msys64\usr\bin' - CONFIG_ARGS: '--enable-debug --enable-werror --disable-threaded-resolver --disable-proxy --without-ssl --enable-websockets' + CONFIG_ARGS: '--enable-debug --enable-werror --disable-threaded-resolver --disable-proxy --without-ssl --enable-websockets --without-libpsl' - job_name: 'autotools, msys2, Debug, x86_64, no SSL' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2017' BUILD_SYSTEM: autotools TESTING: 'ON' DISABLED_TESTS: '!19 !504 !704 !705 !1233' - ADD_PATH: 'C:\msys64\usr\bin' - CONFIG_ARGS: '--enable-debug --enable-werror --disable-threaded-resolver --without-ssl --enable-websockets' + CONFIG_ARGS: '--enable-debug --enable-werror --disable-threaded-resolver --without-ssl --enable-websockets --without-libpsl' - job_name: 'autotools, msys2, Release, x86_64, no SSL' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2017' BUILD_SYSTEM: autotools TESTING: 'ON' DISABLED_TESTS: '!19 !504 !704 !705 !1233' - ADD_PATH: 'C:\msys64\usr\bin' - CONFIG_ARGS: '--enable-warnings --enable-werror --without-ssl --enable-websockets' + CONFIG_ARGS: '--enable-warnings --enable-werror --without-ssl --enable-websockets --without-libpsl' # autotools-based Cygwin build - job_name: 'autotools, cygwin, Debug, x86_64, no SSL' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022' BUILD_SYSTEM: autotools TESTING: 'ON' DISABLED_TESTS: '' - ADD_PATH: 'C:\cygwin64\bin' - CONFIG_ARGS: '--enable-debug --enable-werror --disable-threaded-resolver --without-ssl --enable-websockets' - POSIX_PATH_PREFIX: '/cygdrive' + ADD_SHELL: 'C:/cygwin64/bin' + CONFIG_ARGS: '--enable-debug --enable-werror --disable-threaded-resolver --without-ssl --enable-websockets --without-libpsl' install: - ps: | - if($env:ADD_PATH -ne $null) { - $env:PATH = "$env:ADD_PATH;$env:PATH" - } - -build_script: - - ps: | - function Pull-BatchFile-Env { - param([string]$Path, [string]$Parameters) - $tempFile = [IO.Path]::GetTempFileName() - cmd.exe /c " `"$Path`" $Parameters && set " > $tempFile - Get-Content $tempFile | ForEach-Object { if($_ -match '^(.*?)=(.*)$') { Set-Content "env:\$($matches[1])" $matches[2] } } - Remove-Item $tempFile - } - - $ErrorActionPreference = 'Stop' - - if($env:APPVEYOR_BUILD_WORKER_IMAGE -eq 'Visual Studio 2022') { - $openssl_root = 'C:\OpenSSL-v30-Win64' + if($env:ADD_SHELL -ne $null) { + $env:PATH = "$env:ADD_SHELL;$env:PATH" } else { - $openssl_root = 'C:\OpenSSL-v111-Win64' - } - - if($env:BUILD_SYSTEM -eq 'CMake') { - - $options = @('-DCURL_WERROR=ON') - $options += "-G$env:PRJ_GEN" - if($env:TARGET -ne $null) { - $options += "$env:TARGET" - if($env:TARGET.Contains('ARM64')) { - $env:SKIP_RUN = 'ARM64 architecture' - } - } - $options += "-DCURL_USE_OPENSSL=$env:OPENSSL" - if($env:OPENSSL -eq 'ON') { - $options += "-DOPENSSL_ROOT_DIR=$openssl_root" - } - $options += "-DCURL_USE_SCHANNEL=$env:SCHANNEL" - $options += "-DHTTP_ONLY=$env:HTTP_ONLY" - $options += "-DBUILD_SHARED_LIBS=$env:SHARED" - $options += "-DBUILD_TESTING=$env:TESTING" - $options += "-DENABLE_WEBSOCKETS=$env:WEBSOCKETS" - $options += "-DCMAKE_UNITY_BUILD=$env:UNITY" - $options += "-DENABLE_DEBUG=$env:DEBUG" - $options += "-DENABLE_UNICODE=$env:ENABLE_UNICODE" - $options += '-DCMAKE_INSTALL_PREFIX=C:/CURL' - $options += "-DCMAKE_BUILD_TYPE=$env:PRJ_CFG" - if($env:PRJ_CFG -eq 'Debug') { - $options += '-DCMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG=' - } - elseif ($env:PRJ_CFG -eq 'Release') { - $options += '-DCMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE=' - } - if($env:PRJ_GEN.Contains('Visual Studio')) { - $options += '-DCMAKE_VS_GLOBALS=TrackFileAccess=false' - } - if($env:PRJ_GEN -eq 'Visual Studio 9 2008') { - # Without this it fails to run due to missing MSVCR90.dll - $options += '-DCURL_STATIC_CRT=ON' - } - - Write-Host 'CMake options:' $options - cmake . $options - cmake --build . --config $env:PRJ_CFG --parallel 2 --clean-first -- $env:BUILD_OPT - if($env:SHARED -eq 'ON') { - Copy-Item -Path 'C:\Projects\curl\lib\*.dll' -Destination 'C:\projects\curl\src' - Copy-Item -Path 'C:\Projects\curl\lib\*.dll' -Destination 'C:\projects\curl\tests\libtest' - } - if($env:OPENSSL -eq 'ON') { - Copy-Item -Path "$openssl_root\*.dll" -Destination 'C:\projects\curl\src' - } - $curl = '.\src\curl.exe' - } - elseif($env:BUILD_SYSTEM -eq 'VisualStudioSolution') { - cd projects - .\generate.bat $env:VC_VERSION - msbuild.exe -maxcpucount "-property:Configuration=$env:PRJ_CFG" "Windows\$env:VC_VERSION\curl-all.sln" - $curl = "..\build\Win32\$env:VC_VERSION\$env:PRJ_CFG\curld.exe" - } - elseif($env:BUILD_SYSTEM -eq 'winbuild_vs2015') { - .\buildconf.bat - cd winbuild - Pull-BatchFile-Env 'C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd' /x64 - Pull-BatchFile-Env 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat' x86_amd64 - nmake /nologo /f Makefile.vc mode=dll VC=14 "SSL_PATH=$openssl_root" WITH_SSL=dll MACHINE=x64 DEBUG=$env:DEBUG ENABLE_UNICODE=$env:ENABLE_UNICODE - $curl = "..\builds\libcurl-vc14-x64-$env:PATHPART-dll-ssl-dll-ipv6-sspi\bin\curl.exe" - } - elseif($env:BUILD_SYSTEM -eq 'winbuild_vs2017') { - .\buildconf.bat - cd winbuild - Pull-BatchFile-Env 'C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat' - nmake /nologo /f Makefile.vc mode=dll VC=14.10 "SSL_PATH=$openssl_root" WITH_SSL=dll MACHINE=x64 DEBUG=$env:DEBUG ENABLE_UNICODE=$env:ENABLE_UNICODE - $curl = "..\builds\libcurl-vc14.10-x64-$env:PATHPART-dll-ssl-dll-ipv6-sspi\bin\curl.exe" + $env:PATH = "C:/msys64/usr/bin;$env:PATH" } - elseif($env:BUILD_SYSTEM -eq 'autotools') { - & bash -e -c "cd $env:POSIX_PATH_PREFIX/c/projects/curl && autoreconf -fi 2>&1 && ./configure $env:CONFIG_ARGS 2>&1 && make V=1 && make V=1 examples && cd tests && make V=1" - $curl = '.\src\curl.exe' - } - - Get-ChildItem -Path C:\projects\curl -Include ('*.exe', '*.dll') -Recurse -Name - if($env:SKIP_RUN -eq $null) { - cmd.exe /c "`"$curl`" -V 2>&1" - if(-not $?) { - Write-Host "Error running curl: '$curl':" ("0x" + $LastExitCode.ToString("X")) - exit 1 - } - } - else { - Write-Host "Skip running curl.exe. Reason: $env:SKIP_RUN" - } - - if($false) { - if(Test-Path CMakeFiles/CMakeConfigureLog.yaml) { cat CMakeFiles/CMakeConfigureLog.yaml } - if(Test-Path CMakeFiles/CMakeOutput.log) { cat CMakeFiles/CMakeOutput.log } - if(Test-Path CMakeFiles/CMakeError.log) { cat CMakeFiles/CMakeError.log } - if(Test-Path config.log) { cat config.log } - } - - if($env:TESTING -eq 'ON' -and $env:BUILD_SYSTEM -eq 'CMake') { - cmake --build . --config $env:PRJ_CFG --parallel 2 --target testdeps + if($env:ADD_PATH -ne $null) { + $env:PATH = "$env:ADD_PATH;$env:PATH" } -test_script: - - ps: | - if(Test-Path 'C:/msys64/usr/bin/curl.exe') { - $acurl="-ac $env:POSIX_PATH_PREFIX/c/msys64/usr/bin/curl.exe" - } - if(Test-Path 'C:/Windows/System32/curl.exe') { - $acurl="-ac $env:POSIX_PATH_PREFIX/c/Windows/System32/curl.exe" - } - if($env:TESTING -eq 'ON') { - if($env:BUILD_SYSTEM -eq 'CMake') { - $env:TFLAGS="$acurl $env:DISABLED_TESTS" - cmake --build . --config $env:PRJ_CFG --target test-ci - } - elseif($env:BUILD_SYSTEM -eq 'autotools') { - & bash -e -c "cd $env:POSIX_PATH_PREFIX/c/projects/curl && make V=1 TFLAGS='$acurl $env:DISABLED_TESTS' test-ci" - } - else { - & bash -e -c "cd $env:POSIX_PATH_PREFIX/c/projects/curl/tests && ./runtests.pl -a -p !flaky -r -rm $acurl $env:DISABLED_TESTS" - } - } +build_script: + - cmd: sh -c ./appveyor.sh clone_depth: 10 @@ -430,7 +292,7 @@ branches: skip_commits: files: - '.azure-pipelines.yml' - - '.circleci/**/*' + - '.circleci/*' - '.cirrus.yml' - '.github/**/*' - 'packages/**/*' diff --git a/buildconf.bat b/buildconf.bat index 61536611858..532c9848d6b 100644 --- a/buildconf.bat +++ b/buildconf.bat @@ -38,19 +38,7 @@ rem cd /d "%~0\.." 1>NUL 2>&1 rem Check we are running from a curl git repository - if not exist GIT-INFO goto norepo - - rem Detect programs. HAVE_ - rem When not found the variable is set undefined. The undefined pattern - rem allows for statements like "if not defined HAVE_PERL (command)" - groff --version NUL 2>&1 - if errorlevel 1 (set HAVE_GROFF=) else (set HAVE_GROFF=Y) - nroff --version NUL 2>&1 - if errorlevel 1 (set HAVE_NROFF=) else (set HAVE_NROFF=Y) - perl --version NUL 2>&1 - if errorlevel 1 (set HAVE_PERL=) else (set HAVE_PERL=Y) - gzip --version NUL 2>&1 - if errorlevel 1 (set HAVE_GZIP=) else (set HAVE_GZIP=Y) + if not exist GIT-INFO.md goto norepo :parseArgs if "%~1" == "" goto start @@ -125,15 +113,6 @@ rem ) cmd /c exit 0 - rem Setup c-ares git tree - if exist ares\buildconf.bat ( - echo. - echo Configuring c-ares build environment - cd ares - call buildconf.bat - cd .. - ) - if "%BASIC_HUGEHELP%" == "1" ( if "%OS%" == "Windows_NT" endlocal exit /B 1 @@ -182,47 +161,20 @@ rem :genHugeHelp if "%OS%" == "Windows_NT" setlocal set LC_ALL=C - set ROFFCMD= set BASIC=1 - if defined HAVE_PERL ( - if defined HAVE_GROFF ( - set ROFFCMD=groff -mtty-char -Tascii -P-c -man - ) else if defined HAVE_NROFF ( - set ROFFCMD=nroff -c -Tascii -man - ) - ) - - if defined ROFFCMD ( + if exist src\tool_hugehelp.c.cvs ( + copy /Y src\tool_hugehelp.c.cvs src\tool_hugehelp.c 1>NUL 2>&1 + ) else ( echo #include "tool_setup.h"> src\tool_hugehelp.c echo #include "tool_hugehelp.h">> src\tool_hugehelp.c - - if defined HAVE_GZIP ( - echo #ifndef HAVE_LIBZ>> src\tool_hugehelp.c - ) - - %ROFFCMD% docs\curl.1 2>NUL | perl src\mkhelp.pl docs\MANUAL >> src\tool_hugehelp.c - if defined HAVE_GZIP ( - echo #else>> src\tool_hugehelp.c - %ROFFCMD% docs\curl.1 2>NUL | perl src\mkhelp.pl -c docs\MANUAL >> src\tool_hugehelp.c - echo #endif /^* HAVE_LIBZ ^*/>> src\tool_hugehelp.c - ) - - set BASIC=0 - ) else ( - if exist src\tool_hugehelp.c.cvs ( - copy /Y src\tool_hugehelp.c.cvs src\tool_hugehelp.c 1>NUL 2>&1 - ) else ( - echo #include "tool_setup.h"> src\tool_hugehelp.c - echo #include "tool_hugehelp.h">> src\tool_hugehelp.c - echo.>> src\tool_hugehelp.c - echo void hugehelp(void^)>> src\tool_hugehelp.c - echo {>> src\tool_hugehelp.c - echo #ifdef USE_MANUAL>> src\tool_hugehelp.c - echo fputs("Built-in manual not included\n", stdout^);>> src\tool_hugehelp.c - echo #endif>> src\tool_hugehelp.c - echo }>> src\tool_hugehelp.c - ) + echo.>> src\tool_hugehelp.c + echo void hugehelp(void^)>> src\tool_hugehelp.c + echo {>> src\tool_hugehelp.c + echo #ifdef USE_MANUAL>> src\tool_hugehelp.c + echo fputs("Built-in manual not included\n", stdout^);>> src\tool_hugehelp.c + echo #endif>> src\tool_hugehelp.c + echo }>> src\tool_hugehelp.c ) findstr "/C:void hugehelp(void)" src\tool_hugehelp.c 1>NUL 2>&1 @@ -244,13 +196,8 @@ rem Windows 9x as setlocal isn't available until Windows NT rem :dosCleanup set MODE= - set HAVE_GROFF= - set HAVE_NROFF= - set HAVE_PERL= - set HAVE_GZIP= set BASIC_HUGEHELP= set LC_ALL - set ROFFCMD= set BASIC= exit /B @@ -296,10 +243,9 @@ rem :warning echo. echo Warning: The curl manual could not be integrated in the source. This means when - echo you build curl the manual will not be available (curl --man^). Integration of + echo you build curl the manual will not be available (curl --manual^). Integration of echo the manual is not required and a summary of the options will still be available - echo (curl --help^). To integrate the manual your PATH is required to have - echo groff/nroff, perl and optionally gzip for compression. + echo (curl --help^). To integrate the manual build with configure or cmake. goto success :error diff --git a/configure.ac b/configure.ac index cd3b845f491..a19c12b95d2 100644 --- a/configure.ac +++ b/configure.ac @@ -159,6 +159,7 @@ curl_tls_srp_msg="no (--enable-tls-srp)" curl_ipv6_msg="no (--enable-ipv6)" curl_unix_sockets_msg="no (--enable-unix-sockets)" curl_idn_msg="no (--with-{libidn2,winidn})" + curl_docs_msg="enabled (--disable-docs)" curl_manual_msg="no (--enable-manual)" curl_libcurl_msg="enabled (--disable-libcurl-option)" curl_verbose_msg="enabled (--disable-verbose)" @@ -175,7 +176,7 @@ curl_headers_msg="enabled (--disable-headers-api)" ssl_backends= curl_h1_msg="enabled (internal)" curl_h2_msg="no (--with-nghttp2)" - curl_h3_msg="no (--with-ngtcp2 --with-nghttp3, --with-quiche, --with-msh3)" + curl_h3_msg="no (--with-ngtcp2 --with-nghttp3, --with-quiche, --with-openssl-quic, --with-msh3)" enable_altsvc="yes" hsts="yes" @@ -503,6 +504,7 @@ dnl platform/compiler/architecture specific checks/flags dnl ********************************************************************** CURL_CHECK_COMPILER +CURL_CHECK_NATIVE_WINDOWS CURL_SET_COMPILER_BASIC_OPTS CURL_SET_COMPILER_DEBUG_OPTS CURL_SET_COMPILER_OPTIMIZE_OPTS @@ -583,25 +585,6 @@ dnl ********************************************************************** dnl Compilation based checks should not be done before this point. dnl ********************************************************************** -dnl ********************************************************************** -dnl Make sure that our checks for headers windows.h winsock2.h -dnl and ws2tcpip.h take precedence over any other further checks which -dnl could be done later using AC_CHECK_HEADER or AC_CHECK_HEADERS for -dnl this specific header files. And do them before its results are used. -dnl ********************************************************************** - -CURL_CHECK_HEADER_WINDOWS -CURL_CHECK_NATIVE_WINDOWS -case X-"$curl_cv_native_windows" in - X-yes) - CURL_CHECK_HEADER_WINSOCK2 - CURL_CHECK_HEADER_WS2TCPIP - ;; - *) - curl_cv_header_winsock2_h="no" - curl_cv_header_ws2tcpip_h="no" - ;; -esac CURL_CHECK_WIN32_LARGEFILE CURL_CHECK_WIN32_CRYPTO @@ -1015,6 +998,28 @@ AS_HELP_STRING([--disable-mqtt],[Disable MQTT support]), AC_MSG_RESULT(no) ) +dnl ********************************************************************** +dnl Check whether to build documentation +dnl ********************************************************************** + +AC_MSG_CHECKING([whether to build documentation]) +AC_ARG_ENABLE(docs, +AS_HELP_STRING([--enable-docs],[Enable documentation]) +AS_HELP_STRING([--disable-docs],[Disable documentation]), +[ case "$enableval" in + no) + AC_MSG_RESULT(no) + BUILD_DOCS=0 + curl_docs_msg="no" + ;; + *) AC_MSG_RESULT(yes) + BUILD_DOCS=1 + ;; + esac ], + AC_MSG_RESULT(yes) + BUILD_DOCS=1 +) + dnl ********************************************************************** dnl Check for built-in manual dnl ********************************************************************** @@ -1130,24 +1135,19 @@ fi if test "$HAVE_GETHOSTBYNAME" != "1" then dnl This is for winsock systems - if test "$curl_cv_header_windows_h" = "yes"; then - if test "$curl_cv_header_winsock2_h" = "yes"; then - winsock_LIB="-lws2_32" - fi + if test "$curl_cv_native_windows" = "yes"; then + winsock_LIB="-lws2_32" if test ! -z "$winsock_LIB"; then my_ac_save_LIBS=$LIBS LIBS="$winsock_LIB $LIBS" AC_MSG_CHECKING([for gethostbyname in $winsock_LIB]) AC_LINK_IFELSE([ AC_LANG_PROGRAM([[ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include -#endif -#include #endif ]],[[ gethostbyname("localhost"); @@ -1422,8 +1422,8 @@ if test X"$OPT_BROTLI" != Xno; then dnl if given with a prefix, we set -L and -I based on that if test -n "$PREFIX_BROTLI"; then - # curl-impersonate: Use static libbrotli - LIB_BROTLI="-lbrotlidec-static -lbrotlicommon-static" + # curl-impersonate: Use static libbrotli, -static postfix dropped since brotli 1.1.0 + LIB_BROTLI="-lbrotlidec -lbrotlicommon" LD_BROTLI=-L${PREFIX_BROTLI}/lib$libsuff CPP_BROTLI=-I${PREFIX_BROTLI}/include DIR_BROTLI=${PREFIX_BROTLI}/lib$libsuff @@ -1673,7 +1673,7 @@ AS_HELP_STRING([--disable-ipv6],[Disable IPv6 support]), AC_RUN_IFELSE([AC_LANG_SOURCE([[ /* are AF_INET6 and sockaddr_in6 available? */ #include -#ifdef HAVE_WINSOCK2_H +#ifdef _WIN32 #include #include #else @@ -1683,15 +1683,12 @@ AS_HELP_STRING([--disable-ipv6],[Disable IPv6 support]), # include #endif #endif -#include /* for exit() */ -main() + +int main(void) { struct sockaddr_in6 s; (void)s; - if (socket(AF_INET6, SOCK_STREAM, 0) < 0) - exit(1); - else - exit(0); + return socket(AF_INET6, SOCK_STREAM, 0) < 0; } ]]) ], @@ -1712,7 +1709,7 @@ if test "$ipv6" = yes; then AC_MSG_CHECKING([if struct sockaddr_in6 has sin6_scope_id member]) AC_COMPILE_IFELSE([ AC_LANG_PROGRAM([[ #include -#ifdef HAVE_WINSOCK2_H +#ifdef _WIN32 #include #include #else @@ -1855,10 +1852,7 @@ AC_INCLUDES_DEFAULT if test "x$not_mit" = "x1"; then dnl MIT not found, check for Heimdal AC_CHECK_HEADER(gssapi.h, - [ - dnl found - AC_DEFINE(HAVE_GSSHEIMDAL, 1, [if you have Heimdal]) - ], + [], [ dnl no header found, disabling GSS want_gss=no @@ -1867,7 +1861,6 @@ AC_INCLUDES_DEFAULT ) else dnl MIT found - AC_DEFINE(HAVE_GSSMIT, 1, [if you have MIT Kerberos]) dnl check if we have a really old MIT Kerberos version (<= 1.2) AC_MSG_CHECKING([if GSS-API headers declare GSS_C_NT_HOSTBASED_SERVICE]) AC_COMPILE_IFELSE([ @@ -2087,20 +2080,74 @@ dnl ********************************************************************** dnl Check for libpsl dnl ********************************************************************** -AC_ARG_WITH(libpsl, - AS_HELP_STRING([--without-libpsl], - [disable support for libpsl cookie checking]), - with_libpsl=$withval, - with_libpsl=yes) -if test $with_libpsl != "no"; then - AC_SEARCH_LIBS(psl_builtin, psl, - [curl_psl_msg="enabled"; - AC_DEFINE([USE_LIBPSL], [1], [PSL support enabled]) - ], - [curl_psl_msg="no (libpsl not found)"; - AC_MSG_WARN([libpsl was not found]) - ] +dnl Default to compiler & linker defaults for LIBPSL files & libraries. +OPT_LIBPSL=off +AC_ARG_WITH(libpsl,dnl +AS_HELP_STRING([--with-libpsl=PATH],[Where to look for libpsl, PATH points to the LIBPSL installation; when possible, set the PKG_CONFIG_PATH environment variable instead of using this option]) +AS_HELP_STRING([--without-libpsl], [disable LIBPSL]), + OPT_LIBPSL=$withval) + +if test X"$OPT_LIBPSL" != Xno; then + dnl backup the pre-libpsl variables + CLEANLDFLAGS="$LDFLAGS" + CLEANCPPFLAGS="$CPPFLAGS" + CLEANLIBS="$LIBS" + + case "$OPT_LIBPSL" in + yes) + dnl --with-libpsl (without path) used + CURL_CHECK_PKGCONFIG(libpsl) + + if test "$PKGCONFIG" != "no" ; then + LIB_PSL=`$PKGCONFIG --libs-only-l libpsl` + LD_PSL=`$PKGCONFIG --libs-only-L libpsl` + CPP_PSL=`$PKGCONFIG --cflags-only-I libpsl` + else + dnl no libpsl pkg-config found + LIB_PSL="-lpsl" + fi + + ;; + off) + dnl no --with-libpsl option given, just check default places + LIB_PSL="-lpsl" + ;; + *) + dnl use the given --with-libpsl spot + LIB_PSL="-lpsl" + PREFIX_PSL=$OPT_LIBPSL + ;; + esac + + dnl if given with a prefix, we set -L and -I based on that + if test -n "$PREFIX_PSL"; then + LD_PSL=-L${PREFIX_PSL}/lib$libsuff + CPP_PSL=-I${PREFIX_PSL}/include + fi + + LDFLAGS="$LDFLAGS $LD_PSL" + CPPFLAGS="$CPPFLAGS $CPP_PSL" + LIBS="$LIB_PSL $LIBS" + + AC_CHECK_LIB(psl, psl_builtin, + [ + AC_CHECK_HEADERS(libpsl.h, + curl_psl_msg="enabled" + LIBPSL_ENABLED=1 + AC_DEFINE(USE_LIBPSL, 1, [if libpsl is in use]) + AC_SUBST(USE_LIBPSL, [1]) + ) + ], + dnl not found, revert back to clean variables + LDFLAGS=$CLEANLDFLAGS + CPPFLAGS=$CLEANCPPFLAGS + LIBS=$CLEANLIBS ) + + if test X"$OPT_LIBPSL" != Xoff && + test "$LIBPSL_ENABLED" != "1"; then + AC_MSG_ERROR([libpsl libs and/or directories were not found where specified!]) + fi fi AM_CONDITIONAL([USE_LIBPSL], [test "$curl_psl_msg" = "enabled"]) @@ -2812,6 +2859,11 @@ esac curl_tcp2_msg="no (--with-ngtcp2)" if test X"$want_tcp2" != Xno; then + + if test "$QUIC_ENABLED" != "yes"; then + AC_MSG_ERROR([the detected TLS library does not support QUIC, making --with-ngtcp2 a no-no]) + fi + dnl backup the pre-ngtcp2 variables CLEANLDFLAGS="$LDFLAGS" CLEANCPPFLAGS="$CPPFLAGS" @@ -2867,7 +2919,7 @@ if test X"$want_tcp2" != Xno; then fi -if test "x$NGTCP2_ENABLED" = "x1" -a "x$OPENSSL_ENABLED" = "x1"; then +if test "x$NGTCP2_ENABLED" = "x1" -a "x$OPENSSL_ENABLED" = "x1" -a "x$OPENSSL_IS_BORINGSSL" != "x1"; then dnl backup the pre-ngtcp2_crypto_quictls variables CLEANLDFLAGS="$LDFLAGS" CLEANCPPFLAGS="$CPPFLAGS" @@ -2922,6 +2974,61 @@ if test "x$NGTCP2_ENABLED" = "x1" -a "x$OPENSSL_ENABLED" = "x1"; then fi fi +if test "x$NGTCP2_ENABLED" = "x1" -a "x$OPENSSL_ENABLED" = "x1" -a "x$OPENSSL_IS_BORINGSSL" = "x1"; then + dnl backup the pre-ngtcp2_crypto_boringssl variables + CLEANLDFLAGS="$LDFLAGS" + CLEANCPPFLAGS="$CPPFLAGS" + CLEANLIBS="$LIBS" + + CURL_CHECK_PKGCONFIG(libngtcp2_crypto_boringssl, $want_tcp2_path) + + if test "$PKGCONFIG" != "no" ; then + LIB_NGTCP2_CRYPTO_BORINGSSL=`CURL_EXPORT_PCDIR([$want_tcp2_path]) + $PKGCONFIG --libs-only-l libngtcp2_crypto_boringssl` + AC_MSG_NOTICE([-l is $LIB_NGTCP2_CRYPTO_BORINGSSL]) + + CPP_NGTCP2_CRYPTO_BORINGSSL=`CURL_EXPORT_PCDIR([$want_tcp2_path]) dnl + $PKGCONFIG --cflags-only-I libngtcp2_crypto_boringssl` + AC_MSG_NOTICE([-I is $CPP_NGTCP2_CRYPTO_BORINGSSL]) + + LD_NGTCP2_CRYPTO_BORINGSSL=`CURL_EXPORT_PCDIR([$want_tcp2_path]) + $PKGCONFIG --libs-only-L libngtcp2_crypto_boringssl` + AC_MSG_NOTICE([-L is $LD_NGTCP2_CRYPTO_BORINGSSL]) + + LDFLAGS="$LDFLAGS $LD_NGTCP2_CRYPTO_BORINGSSL" + CPPFLAGS="$CPPFLAGS $CPP_NGTCP2_CRYPTO_BORINGSSL" + LIBS="$LIB_NGTCP2_CRYPTO_BORINGSSL $LIBS" + + if test "x$cross_compiling" != "xyes"; then + DIR_NGTCP2_CRYPTO_BORINGSSL=`echo $LD_NGTCP2_CRYPTO_BORINGSSL | $SED -e 's/^-L//'` + fi + AC_CHECK_LIB(ngtcp2_crypto_boringssl, ngtcp2_crypto_recv_client_initial_cb, + [ + AC_CHECK_HEADERS(ngtcp2/ngtcp2_crypto.h, + NGTCP2_ENABLED=1 + AC_DEFINE(USE_NGTCP2_CRYPTO_BORINGSSL, 1, [if ngtcp2_crypto_boringssl is in use]) + AC_SUBST(USE_NGTCP2_CRYPTO_BORINGSSL, [1]) + CURL_LIBRARY_PATH="$CURL_LIBRARY_PATH:$DIR_NGTCP2_CRYPTO_BORINGSSL" + export CURL_LIBRARY_PATH + AC_MSG_NOTICE([Added $DIR_NGTCP2_CRYPTO_BORINGSSL to CURL_LIBRARY_PATH]) + ) + ], + dnl not found, revert back to clean variables + LDFLAGS=$CLEANLDFLAGS + CPPFLAGS=$CLEANCPPFLAGS + LIBS=$CLEANLIBS + ) + + else + dnl no ngtcp2_crypto_boringssl pkg-config found, deal with it + if test X"$want_tcp2" != Xdefault; then + dnl To avoid link errors, we do not allow --with-ngtcp2 without + dnl a pkgconfig file + AC_MSG_ERROR([--with-ngtcp2 was specified but could not find ngtcp2_crypto_boringssl pkg-config file.]) + fi + fi +fi + if test "x$NGTCP2_ENABLED" = "x1" -a "x$GNUTLS_ENABLED" = "x1"; then dnl backup the pre-ngtcp2_crypto_gnutls variables CLEANLDFLAGS="$LDFLAGS" @@ -3032,15 +3139,55 @@ if test "x$NGTCP2_ENABLED" = "x1" -a "x$WOLFSSL_ENABLED" = "x1"; then fi fi +dnl ********************************************************************** +dnl Check for OpenSSL QUIC +dnl ********************************************************************** + +OPT_OPENSSL_QUIC="no" + +if test "x$disable_http" = "xyes" -o "x$OPENSSL_ENABLED" != "x1"; then + # without HTTP or without openssl, no use + OPT_OPENSSL_QUIC="no" +fi + +AC_ARG_WITH(openssl-quic, +AS_HELP_STRING([--with-openssl-quic],[Enable OpenSSL QUIC usage]) +AS_HELP_STRING([--without-openssl-quic],[Disable OpenSSL QUIC usage]), + [OPT_OPENSSL_QUIC=$withval]) +case "$OPT_OPENSSL_QUIC" in + no) + dnl --without-openssl-quic option used + want_openssl_quic="no" + ;; + yes) + dnl --with-openssl-quic option used + want_openssl_quic="yes" + ;; +esac + +curl_openssl_quic_msg="no (--with-openssl-quic)" +if test "x$want_openssl_quic" = "xyes"; then + + if test "$NGTCP2_ENABLED" = 1; then + AC_MSG_ERROR([--with-openssl-quic and --with-ngtcp2 are mutually exclusive]) + fi + if test "$HAVE_OPENSSL_QUIC" != 1; then + AC_MSG_ERROR([--with-openssl-quic requires quic support in OpenSSL]) + fi + AC_DEFINE(USE_OPENSSL_QUIC, 1, [if openssl QUIC is in use]) + AC_SUBST(USE_OPENSSL_QUIC, [1]) +fi + dnl ********************************************************************** dnl Check for nghttp3 (HTTP/3 with ngtcp2) dnl ********************************************************************** OPT_NGHTTP3="yes" -if test "x$NGTCP2_ENABLED" = "x"; then - # without ngtcp2, nghttp3 is of no use for us +if test "x$USE_NGTCP2" != "x1" -a "x$USE_OPENSSL_QUIC" != "x1"; then + # without ngtcp2 or openssl quic, nghttp3 is of no use for us OPT_NGHTTP3="no" + want_nghttp3="no" fi AC_ARG_WITH(nghttp3, @@ -3066,6 +3213,7 @@ esac curl_http3_msg="no (--with-nghttp3)" if test X"$want_nghttp3" != Xno; then + dnl backup the pre-nghttp3 variables CLEANLDFLAGS="$LDFLAGS" CLEANCPPFLAGS="$CPPFLAGS" @@ -3096,8 +3244,6 @@ if test X"$want_nghttp3" != Xno; then AC_CHECK_LIB(nghttp3, nghttp3_conn_client_new_versioned, [ AC_CHECK_HEADERS(nghttp3/nghttp3.h, - curl_h3_msg="enabled (ngtcp2 + nghttp3)" - NGHTTP3_ENABLED=1 AC_DEFINE(USE_NGHTTP3, 1, [if nghttp3 is in use]) AC_SUBST(USE_NGHTTP3, [1]) CURL_LIBRARY_PATH="$CURL_LIBRARY_PATH:$DIR_NGHTTP3" @@ -3122,6 +3268,29 @@ if test X"$want_nghttp3" != Xno; then fi +dnl ********************************************************************** +dnl Check for ngtcp2 and nghttp3 (HTTP/3 with ngtcp2 + nghttp3) +dnl ********************************************************************** + +if test "x$NGTCP2_ENABLED" = "x1" -a "x$USE_NGHTTP3" = "x1"; then + AC_DEFINE(USE_NGTCP2_H3, 1, [if ngtcp2 + nghttp3 is in use]) + AC_SUBST(USE_NGTCP2_H3, [1]) + AC_MSG_NOTICE([HTTP3 support is experimental]) + curl_h3_msg="enabled (ngtcp2 + nghttp3)" +fi + +dnl ********************************************************************** +dnl Check for OpenSSL and nghttp3 (HTTP/3 with nghttp3 using OpenSSL QUIC) +dnl ********************************************************************** + +if test "x$USE_OPENSSL_QUIC" = "x1" -a "x$USE_NGHTTP3" = "x1"; then + experimental="$experimental HTTP3" + AC_DEFINE(USE_OPENSSL_H3, 1, [if openssl quic + nghttp3 is in use]) + AC_SUBST(USE_OPENSSL_H3, [1]) + AC_MSG_NOTICE([HTTP3 support is experimental]) + curl_h3_msg="enabled (openssl + nghttp3)" +fi + dnl ********************************************************************** dnl Check for quiche (QUIC) dnl ********************************************************************** @@ -3156,6 +3325,10 @@ esac if test X"$want_quiche" != Xno; then + if test "$QUIC_ENABLED" != "yes"; then + AC_MSG_ERROR([the detected TLS library does not support QUIC, making --with-quiche a no-no]) + fi + if test "$NGHTTP3_ENABLED" = 1; then AC_MSG_ERROR([--with-quiche and --with-ngtcp2 are mutually exclusive]) fi @@ -3254,9 +3427,22 @@ esac if test X"$want_msh3" != Xno; then + dnl msh3 on non-Windows needs an OpenSSL with the QUIC API + if test "$curl_cv_native_windows" != "yes"; then + if test "$QUIC_ENABLED" != "yes"; then + AC_MSG_ERROR([the detected TLS library does not support QUIC, making --with-msh3 a no-no]) + fi + if test "$OPENSSL_ENABLED" != "1"; then + AC_MSG_ERROR([msh3 requires OpenSSL]) + fi + fi + if test "$NGHTTP3_ENABLED" = 1; then AC_MSG_ERROR([--with-msh3 and --with-ngtcp2 are mutually exclusive]) fi + if test "$QUICHE_ENABLED" = 1; then + AC_MSG_ERROR([--with-msh3 and --with-quiche are mutually exclusive]) + fi dnl backup the pre-msh3 variables CLEANLDFLAGS="$LDFLAGS" @@ -3302,10 +3488,10 @@ AS_HELP_STRING([--with-zsh-functions-dir=PATH],[Install zsh completions to PATH] AS_HELP_STRING([--without-zsh-functions-dir],[Do not install zsh completions]), [OPT_ZSH_FPATH=$withval]) case "$OPT_ZSH_FPATH" in - no) + default|no) dnl --without-zsh-functions-dir option used ;; - default|yes) + yes) dnl --with-zsh-functions-dir option used without path ZSH_FUNCTIONS_DIR="$datarootdir/zsh/site-functions" AC_SUBST(ZSH_FUNCTIONS_DIR) @@ -3316,6 +3502,7 @@ case "$OPT_ZSH_FPATH" in AC_SUBST(ZSH_FUNCTIONS_DIR) ;; esac +AM_CONDITIONAL(USE_ZSH_COMPLETION, test x"$ZSH_FUNCTIONS_DIR" != x) dnl ********************************************************************** dnl Check for fish completion path @@ -3327,10 +3514,10 @@ AS_HELP_STRING([--with-fish-functions-dir=PATH],[Install fish completions to PAT AS_HELP_STRING([--without-fish-functions-dir],[Do not install fish completions]), [OPT_FISH_FPATH=$withval]) case "$OPT_FISH_FPATH" in - no) + default|no) dnl --without-fish-functions-dir option used ;; - default|yes) + yes) dnl --with-fish-functions-dir option used without path CURL_CHECK_PKGCONFIG(fish) if test "$PKGCONFIG" != "no" ; then @@ -3346,6 +3533,7 @@ case "$OPT_FISH_FPATH" in AC_SUBST(FISH_FUNCTIONS_DIR) ;; esac +AM_CONDITIONAL(USE_FISH_COMPLETION, test x"$FISH_FUNCTIONS_DIR" != x) dnl Now check for the very most basic headers. Then we can use these dnl ones as default-headers when checking for the rest! @@ -3478,6 +3666,12 @@ AC_CHECK_TYPE(sa_family_t, AC_DEFINE(CURL_SA_FAMILY_T, ADDRESS_FAMILY, [IP address type in sockaddr]), AC_DEFINE(CURL_SA_FAMILY_T, unsigned short, [IP address type in sockaddr]), [ +#ifdef _WIN32 +#ifndef WIN32_LEAN_AND_MEAN +#define WIN32_LEAN_AND_MEAN +#endif +#include +#endif #ifdef HAVE_SYS_SOCKET_H #include #endif @@ -3521,8 +3715,6 @@ CURL_RUN_IFELSE( AC_MSG_RESULT([no]) ]) -CURL_CONFIGURE_PULL_SYS_POLL - TYPE_IN_ADDR_T TYPE_SOCKADDR_STORAGE @@ -3639,47 +3831,19 @@ AC_CHECK_DECL([fseeko], CURL_CHECK_NONBLOCKING_SOCKET -dnl ************************************************************ -dnl nroff tool stuff -dnl - AC_PATH_PROG( PERL, perl, , $PATH:/usr/local/bin/perl:/usr/bin/:/usr/local/bin ) AC_SUBST(PERL) -AC_PATH_PROGS( NROFF, gnroff nroff, , - $PATH:/usr/bin/:/usr/local/bin ) -AC_SUBST(NROFF) - -if test -n "$NROFF"; then - dnl only check for nroff options if an nroff command was found - - AC_MSG_CHECKING([how to use *nroff to get plain text from man pages]) - MANOPT="-man" - mancheck=`echo foo | $NROFF $MANOPT 2>/dev/null` - if test -z "$mancheck"; then - MANOPT="-mandoc" - mancheck=`echo foo | $NROFF $MANOPT 2>/dev/null` - if test -z "$mancheck"; then - MANOPT="" - AC_MSG_RESULT([failed]) - AC_MSG_WARN([found no *nroff option to get plaintext from man pages]) - else - AC_MSG_RESULT([$MANOPT]) - fi - else - AC_MSG_RESULT([$MANOPT]) - fi - AC_SUBST(MANOPT) +if test -z "$PERL"; then + dnl if perl was not found then disable building docs + AC_MSG_WARN([disabling documentation]) + BUILD_DOCS=0 + curl_docs_msg="no" fi -if test -z "$MANOPT" -then - dnl if no nroff tool was found, or no option that could convert man pages - dnl was found, then disable the built-in manual stuff - AC_MSG_WARN([disabling built-in manual]) - USE_MANUAL="no"; -fi +dnl set variable for use in automakefile(s) +AM_CONDITIONAL(BUILD_DOCS, test x"$BUILD_DOCS" = x1) dnl ************************************************************************* dnl If the manual variable still is set, then we go with providing a built-in @@ -4592,8 +4756,11 @@ if test "x$USE_NGHTTP2" = "x1"; then SUPPORT_FEATURES="$SUPPORT_FEATURES HTTP2" fi -if test "x$USE_NGTCP2" = "x1" -o "x$USE_QUICHE" = "x1" \ - -o "x$USE_MSH3" = "x1"; then +if test "x$USE_NGTCP2_H3" = "x1" -o "x$USE_QUICHE" = "x1" \ + -o "x$USE_OPENSSL_H3" = "x1" -o "x$USE_MSH3" = "x1"; then + if test "x$CURL_WITH_MULTI_SSL" = "x1"; then + AC_MSG_ERROR([MultiSSL cannot be enabled with HTTP/3 and vice versa]) + fi SUPPORT_FEATURES="$SUPPORT_FEATURES HTTP3" fi @@ -4667,7 +4834,7 @@ AC_SUBST(SUPPORT_FEATURES) dnl For supported protocols in pkg-config file if test "x$CURL_DISABLE_HTTP" != "x1"; then - SUPPORT_PROTOCOLS="$SUPPORT_PROTOCOLS HTTP" + SUPPORT_PROTOCOLS="$SUPPORT_PROTOCOLS HTTP IPFS IPNS" if test "x$SSL_ENABLED" = "x1"; then SUPPORT_PROTOCOLS="$SUPPORT_PROTOCOLS HTTPS" fi @@ -4839,6 +5006,7 @@ AC_MSG_NOTICE([Configured to build curl/libcurl: IPv6: ${curl_ipv6_msg} Unix sockets: ${curl_unix_sockets_msg} IDN: ${curl_idn_msg} + Build docs: ${curl_docs_msg} Build libcurl: Shared=${enable_shared}, Static=${enable_static} Built-in manual: ${curl_manual_msg} --libcurl option: ${curl_libcurl_msg} @@ -4864,6 +5032,14 @@ AC_MSG_NOTICE([Configured to build curl/libcurl: Protocols: ${SUPPORT_PROTOCOLS} Features: ${SUPPORT_FEATURES} ]) + +non13=`echo "$TLSCHOICE" | grep -Ei 'bearssl|secure-transport|mbedtls'`; +if test -n "$non13"; then + cat >&2 << _EOF + WARNING: A selected TLS library ($TLSCHOICE) does not support TLS 1.3! +_EOF +fi + if test -n "$experimental"; then cat >&2 << _EOF WARNING: $experimental enabled but marked EXPERIMENTAL. Use with caution! diff --git a/docs/.gitignore b/docs/.gitignore index 8d0bfb31bb1..a087be744bb 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,7 +2,5 @@ # # SPDX-License-Identifier: curl -*.html -*.pdf -curl.1 -*.1.dist +*.1 +*.3 diff --git a/docs/ALTSVC.md b/docs/ALTSVC.md index b9117e4d46c..92343aee4de 100644 --- a/docs/ALTSVC.md +++ b/docs/ALTSVC.md @@ -24,16 +24,16 @@ space separated fields. ## Fields 1. The ALPN id for the source origin -2. The host name for the source origin +2. The hostname for the source origin 3. The port number for the source origin 4. The ALPN id for the destination host -5. The host name for the destination host -6. The host number for the destination host +5. The hostname for the destination host +6. The port number for the destination host 7. The expiration date and time of this entry within double quotes. The date format is "YYYYMMDD HH:MM:SS" and the time zone is GMT. 8. Boolean (1 or 0) if "persist" was set for this entry 9. Integer priority value (not currently used) -If the host name is an IPv6 numerical address, it is stored with brackets such +If the hostname is an IPv6 numerical address, it is stored with brackets such as `[::1]`. # TODO diff --git a/docs/BINDINGS.md b/docs/BINDINGS.md index 7f5da4219c9..060586fde20 100644 --- a/docs/BINDINGS.md +++ b/docs/BINDINGS.md @@ -96,6 +96,8 @@ Bailiff and Bálint Szilakszi, [Python](http://pycurl.io/) PycURL by Kjetil Jacobsen +[Python](https://pypi.org/project/pymcurl/) mcurl by Ganesh Viswanathan + [Q](https://q-lang.sourceforge.net/) The libcurl module is part of the default install [R](https://cran.r-project.org/package=curl) diff --git a/docs/BUFQ.md b/docs/BUFQ.md index 5ff9e28b8cb..26cfccf491b 100644 --- a/docs/BUFQ.md +++ b/docs/BUFQ.md @@ -13,12 +13,12 @@ as many internal Curl read and write ones. ssize_t Curl_bufq_write(struct bufq *q, const unsigned char *buf, size_t len, CURLcode *err); - returns the length written into `q` or -1 on error. -- writing to a full `q` will return -1 and set *err to CURLE_AGAIN +- writing to a full `q` returns -1 and set *err to CURLE_AGAIN ssize_t Curl_bufq_read(struct bufq *q, unsigned char *buf, size_t len, CURLcode *err); - returns the length read from `q` or -1 on error. -- reading from an empty `q` will return -1 and set *err to CURLE_AGAIN +- reading from an empty `q` returns -1 and set *err to CURLE_AGAIN ``` @@ -32,10 +32,11 @@ ssize_t Curl_bufq_slurp(struct bufq *q, Curl_bufq_reader *reader, void *reader_c CURLcode *err); ``` -`Curl_bufq_slurp()` will invoke the given `reader` callback, passing it its own internal -buffer memory to write to. It may invoke the `reader` several times, as long as it has space -and while the `reader` always returns the length that was requested. There are variations of `slurp` that call the `reader` at most once or only read in a -maximum amount of bytes. +`Curl_bufq_slurp()` invokes the given `reader` callback, passing it its own +internal buffer memory to write to. It may invoke the `reader` several times, +as long as it has space and while the `reader` always returns the length that +was requested. There are variations of `slurp` that call the `reader` at most +once or only read in a maximum amount of bytes. The analog mechanism for write out buffer data is: @@ -47,8 +48,8 @@ ssize_t Curl_bufq_pass(struct bufq *q, Curl_bufq_writer *writer, void *writer_ct CURLcode *err); ``` -`Curl_bufq_pass()` will invoke the `writer`, passing its internal memory and remove the -amount that `writer` reports. +`Curl_bufq_pass()` invokes the `writer`, passing its internal memory and +remove the amount that `writer` reports. ## peek and skip @@ -58,8 +59,8 @@ It is possible to get access to the memory of data stored in a `bufq` with: bool Curl_bufq_peek(const struct bufq *q, const unsigned char **pbuf, size_t *plen); ``` -On returning TRUE, `pbuf` will point to internal memory with `plen` bytes that one may read. This will only -be valid until another operation on `bufq` is performed. +On returning TRUE, `pbuf` points to internal memory with `plen` bytes that one +may read. This is only valid until another operation on `bufq` is performed. Instead of reading `bufq` data, one may simply skip it: @@ -67,20 +68,22 @@ Instead of reading `bufq` data, one may simply skip it: void Curl_bufq_skip(struct bufq *q, size_t amount); ``` -This will remove `amount` number of bytes from the `bufq`. +This removes `amount` number of bytes from the `bufq`. ## lifetime -`bufq` is initialized and freed similar to the `dynbuf` module. Code using `bufq` will -hold a `struct bufq` somewhere. Before it uses it, it invokes: +`bufq` is initialized and freed similar to the `dynbuf` module. Code using +`bufq` holds a `struct bufq` somewhere. Before it uses it, it invokes: ``` void Curl_bufq_init(struct bufq *q, size_t chunk_size, size_t max_chunks); ``` -The `bufq` is told how many "chunks" of data it shall hold at maximum and how large those -"chunks" should be. There are some variants of this, allowing for more options. How "chunks" are handled in a `bufq` is presented in the section about memory management. +The `bufq` is told how many "chunks" of data it shall hold at maximum and how +large those "chunks" should be. There are some variants of this, allowing for +more options. How "chunks" are handled in a `bufq` is presented in the section +about memory management. The user of the `bufq` has the responsibility to call: @@ -95,37 +98,58 @@ void Curl_bufq_reset(struct bufq *q); ## memory management -Internally, a `bufq` uses allocation of fixed size, e.g. the "chunk_size", up to a maximum number, e.g. "max_chunks". These chunks are allocated on demand, therefore writing to a `bufq` may return `CURLE_OUT_OF_MEMORY`. Once the max number of chunks are used, the `bufq` will report that it is "full". +Internally, a `bufq` uses allocation of fixed size, e.g. the "chunk_size", up +to a maximum number, e.g. "max_chunks". These chunks are allocated on demand, +therefore writing to a `bufq` may return `CURLE_OUT_OF_MEMORY`. Once the max +number of chunks are used, the `bufq` reports that it is "full". -Each chunks has a `read` and `write` index. A `bufq` keeps its chunks in a list. Reading happens always at the head chunk, writing always goes to the tail chunk. When the head chunk becomes empty, it is removed. When the tail chunk becomes full, another chunk is added to the end of the list, becoming the new tail. +Each chunks has a `read` and `write` index. A `bufq` keeps its chunks in a +list. Reading happens always at the head chunk, writing always goes to the +tail chunk. When the head chunk becomes empty, it is removed. When the tail +chunk becomes full, another chunk is added to the end of the list, becoming +the new tail. -Chunks that are no longer used are returned to a `spare` list by default. If the `bufq` is created with option `BUFQ_OPT_NO_SPARES` those chunks will be freed right away. +Chunks that are no longer used are returned to a `spare` list by default. If +the `bufq` is created with option `BUFQ_OPT_NO_SPARES` those chunks are freed +right away. -If a `bufq` is created with a `bufc_pool`, the no longer used chunks are returned to the pool. Also `bufq` will ask the pool for a chunk when it needs one. More in section "pools". +If a `bufq` is created with a `bufc_pool`, the no longer used chunks are +returned to the pool. Also `bufq` asks the pool for a chunk when it needs one. +More in section "pools". ## empty, full and overflow -One can ask about the state of a `bufq` with methods such as `Curl_bufq_is_empty(q)`, -`Curl_bufq_is_full(q)`, etc. The amount of data held by a `bufq` is the sum of the data in all its chunks. This is what is reported by `Curl_bufq_len(q)`. +One can ask about the state of a `bufq` with methods such as +`Curl_bufq_is_empty(q)`, `Curl_bufq_is_full(q)`, etc. The amount of data held +by a `bufq` is the sum of the data in all its chunks. This is what is reported +by `Curl_bufq_len(q)`. -Note that a `bufq` length and it being "full" are only loosely related. A simple example: +Note that a `bufq` length and it being "full" are only loosely related. A +simple example: * create a `bufq` with chunk_size=1000 and max_chunks=4. -* write 4000 bytes to it, it will report "full" -* read 1 bytes from it, it will still report "full" -* read 999 more bytes from it, and it will no longer be "full" +* write 4000 bytes to it, it reports "full" +* read 1 bytes from it, it still reports "full" +* read 999 more bytes from it, and it is no longer "full" -The reason for this is that full really means: *bufq uses max_chunks and the last one cannot be written to*. +The reason for this is that full really means: *bufq uses max_chunks and the +last one cannot be written to*. -So when you read 1 byte from the head chunk in the example above, the head still hold 999 unread bytes. Only when those are also read, can the head chunk be removed and a new tail be added. +When you read 1 byte from the head chunk in the example above, the head still +hold 999 unread bytes. Only when those are also read, can the head chunk be +removed and a new tail be added. -There is another variation to this. If you initialized a `bufq` with option `BUFQ_OPT_SOFT_LIMIT`, it will allow writes **beyond** the `max_chunks`. It will report **full**, but one can **still** write. This option is necessary, if partial writes need to be avoided. But it means that you will need other checks to keep the `bufq` from growing ever larger and larger. +There is another variation to this. If you initialized a `bufq` with option +`BUFQ_OPT_SOFT_LIMIT`, it allows writes **beyond** the `max_chunks`. It +reports **full**, but one can **still** write. This option is necessary, if +partial writes need to be avoided. It means that you need other checks to keep +the `bufq` from growing ever larger and larger. ## pools -A `struct bufc_pool` may be used to create chunks for a `bufq` and keep spare ones around. It is initialized -and used via: +A `struct bufc_pool` may be used to create chunks for a `bufq` and keep spare +ones around. It is initialized and used via: ``` void Curl_bufcp_init(struct bufc_pool *pool, size_t chunk_size, size_t spare_max); @@ -133,9 +157,15 @@ void Curl_bufcp_init(struct bufc_pool *pool, size_t chunk_size, size_t spare_max void Curl_bufq_initp(struct bufq *q, struct bufc_pool *pool, size_t max_chunks, int opts); ``` -The pool gets the size and the mount of spares to keep. The `bufq` gets the pool and the `max_chunks`. It no longer needs to know the chunk sizes, as those are managed by the pool. +The pool gets the size and the mount of spares to keep. The `bufq` gets the +pool and the `max_chunks`. It no longer needs to know the chunk sizes, as +those are managed by the pool. -A pool can be shared between many `bufq`s, as long as all of them operate in the same thread. In curl that would be true for all transfers using the same multi handle. The advantages of a pool are: +A pool can be shared between many `bufq`s, as long as all of them operate in +the same thread. In curl that would be true for all transfers using the same +multi handle. The advantages of a pool are: -* when all `bufq`s are empty, only memory for `max_spare` chunks in the pool is used. Empty `bufq`s will hold no memory. -* the latest spare chunk is the first to be handed out again, no matter which `bufq` needs it. This keeps the footprint of "recently used" memory smaller. +* when all `bufq`s are empty, only memory for `max_spare` chunks in the pool + is used. Empty `bufq`s holds no memory. +* the latest spare chunk is the first to be handed out again, no matter which + `bufq` needs it. This keeps the footprint of "recently used" memory smaller. diff --git a/docs/BUFREF.md b/docs/BUFREF.md index 14f41b38bd9..9ee8fdbbee4 100644 --- a/docs/BUFREF.md +++ b/docs/BUFREF.md @@ -44,8 +44,7 @@ void Curl_bufref_set(struct bufref *br, const void *buffer, size_t length, Releases the previously referenced buffer, then assigns the new `buffer` to the structure, associated with its `destructor` function. The latter can be -specified as `NULL`: this will be the case when the referenced buffer is -static. +specified as `NULL`: this is the case when the referenced buffer is static. if `buffer` is NULL, `length` must be zero. diff --git a/docs/BUG-BOUNTY.md b/docs/BUG-BOUNTY.md index 3714efda524..3cb4024a31b 100644 --- a/docs/BUG-BOUNTY.md +++ b/docs/BUG-BOUNTY.md @@ -21,8 +21,8 @@ security vulnerabilities. The amount of money that is rewarded depends on how serious the flaw is determined to be. Since 2021, the Bug Bounty is managed in association with the Internet Bug -Bounty and they will set the reward amounts. If it would turn out that they -set amounts that are way lower than we can accept, the curl project intends to +Bounty and they set the reward amounts. If it would turn out that they set +amounts that are way lower than we can accept, the curl project intends to "top up" rewards. In 2022, typical "Medium" rated vulnerabilities have been rewarded 2,400 USD @@ -40,7 +40,7 @@ Vulnerabilities in features that are off by default and documented as experimental are not eligible for a reward. The vulnerability has to be fixed and publicly announced (by the curl project) -before a bug bounty will be considered. +before a bug bounty is considered. Once the vulnerability has been published by curl, the researcher can request their bounty from the [Internet Bug Bounty](https://hackerone.com/ibb). @@ -48,6 +48,9 @@ their bounty from the [Internet Bug Bounty](https://hackerone.com/ibb). Bounties need to be requested within twelve months from the publication of the vulnerability. +The curl security team reserves themselves the right to deny or allow bug +bounty payouts on its own discretion. There is no appeals process. + ## Product vulnerabilities only This bug bounty only concerns the curl and libcurl products and thus their @@ -60,9 +63,9 @@ bounty or not. ## How are vulnerabilities graded? -The grading of each reported vulnerability that makes a reward claim will be -performed by the curl security team. The grading will be based on the CVSS -(Common Vulnerability Scoring System) 3.0. +The grading of each reported vulnerability that makes a reward claim is +performed by the curl security team. The grading is based on the CVSS (Common +Vulnerability Scoring System) 3.0. ## How are reward amounts determined? diff --git a/docs/BUGS.md b/docs/BUGS.md index 2a8c56fe621..9a3a30add05 100644 --- a/docs/BUGS.md +++ b/docs/BUGS.md @@ -3,9 +3,9 @@ ## There are still bugs Curl and libcurl keep being developed. Adding features and changing code - means that bugs will sneak in, no matter how hard we try to keep them out. + means that bugs sneak in, no matter how hard we try to keep them out. - Of course there are lots of bugs left. And lots of misfeatures. + Of course there are lots of bugs left. Not to mention misfeatures. To help us make curl the stable and solid product we want it to be, we need bug reports and bug fixes. @@ -34,16 +34,16 @@ HackerOne](https://hackerone.com/curl). This ensures that the report reaches the curl security team so that they - first can deal with the report away from the public to minimize the harm - and impact it will have on existing users out there who might be using the - vulnerable versions. + first can deal with the report away from the public to minimize the harm and + impact it has on existing users out there who might be using the vulnerable + versions. The curl project's process for handling security related issues is [documented separately](https://curl.se/dev/secprocess.html). ## What to report - When reporting a bug, you should include all information that will help us + When reporting a bug, you should include all information to help us understand what is wrong, what you expected to happen and how to repeat the bad behavior. You therefore need to tell us: @@ -58,8 +58,8 @@ and anything and everything else you think matters. Tell us what you expected to happen, tell use what did happen, tell us how you could make it work another way. Dig around, try out, test. Then include all the tiny bits and - pieces in your report. You will benefit from this yourself, as it will enable - us to help you quicker and more accurately. + pieces in your report. You benefit from this yourself, as it enables us to + help you quicker and more accurately. Since curl deals with networks, it often helps us if you include a protocol debug dump with your bug report. The output you get by using the `-v` or @@ -84,15 +84,15 @@ SCP, the libssh2 version is relevant etc. Showing us a real source code example repeating your problem is the best way - to get our attention and it will greatly increase our chances to understand - your problem and to work on a fix (if we agree it truly is a problem). + to get our attention and it greatly increases our chances to understand your + problem and to work on a fix (if we agree it truly is a problem). Lots of problems that appear to be libcurl problems are actually just abuses of the libcurl API or other malfunctions in your applications. It is advised that you run your problematic program using a memory debug tool like valgrind or similar before you post memory-related or "crashing" problems to us. -## Who will fix the problems +## Who fixes the problems If the problems or bugs you describe are considered to be bugs, we want to have the problems fixed. @@ -102,11 +102,11 @@ it out of an ambition to keep curl and libcurl excellent products and out of pride. - Please do not assume that you can just lump over something to us and it will - then magically be fixed after some given time. Most often we need feedback - and help to understand what you have experienced and how to repeat a - problem. Then we may only be able to assist YOU to debug the problem and to - track down the proper fix. + Please do not assume that you can just lump over something to us and it then + magically gets fixed after some given time. Most often we need feedback and + help to understand what you have experienced and how to repeat a problem. + Then we may only be able to assist YOU to debug the problem and to track down + the proper fix. We get reports from many people every month and each report can take a considerable amount of time to really go to the bottom with. @@ -119,23 +119,23 @@ Run the program until it cores. - Run your debugger on the core file, like ` curl - core`. `` should be replaced with the name of your debugger, in - most cases that will be `gdb`, but `dbx` and others also occur. + Run your debugger on the core file, like ` curl core`. `` + should be replaced with the name of your debugger, in most cases that is + `gdb`, but `dbx` and others also occur. When the debugger has finished loading the core file and presents you a prompt, enter `where` (without quotes) and press return. The list that is presented is the stack trace. If everything worked, it is supposed to contain the chain of functions that were called when curl - crashed. Include the stack trace with your detailed bug report, it will help a + crashed. Include the stack trace with your detailed bug report, it helps a lot. ## Bugs in libcurl bindings - There will of course pop up bugs in libcurl bindings. You should then - primarily approach the team that works on that particular binding and see - what you can do to help them fix the problem. + There are of course bugs in libcurl bindings. You should then primarily + approach the team that works on that particular binding and see what you can + do to help them fix the problem. If you suspect that the problem exists in the underlying libcurl, then please convert your program over to plain C and follow the steps outlined above. @@ -181,13 +181,13 @@ maybe they are off in the woods hunting. Have patience. Allow at least a few days before expecting someone to have responded. - In the issue tracker, you can expect that some labels will be set on the issue - to help categorize it. + In the issue tracker, you can expect that some labels are set on the issue to + help categorize it. ## First response If your issue/bug report was not perfect at once (and few are), chances are - that someone will ask follow-up questions. Which version did you use? Which + that someone asks follow-up questions. Which version did you use? Which options did you use? How often does the problem occur? How can we reproduce this problem? Which protocols does it involve? Or perhaps much more specific and deep diving questions. It all depends on your specific issue. @@ -210,8 +210,8 @@ for discussing possible ways to move forward with the task, we take that as a strong suggestion that the bug is unimportant. - Unimportant issues will be closed as inactive sooner or later as they cannot - be fixed. The inactivity period (waiting for responses) should not be shorter + Unimportant issues are closed as inactive sooner or later as they cannot be + fixed. The inactivity period (waiting for responses) should not be shorter than two weeks but may extend months. ## Lack of time/interest @@ -240,9 +240,8 @@ Issues that are filed or reported that are not really bugs but more missing features or ideas for future improvements and so on are marked as - 'enhancement' or 'feature-request' and will be added to the `TODO` document - and the issues are closed. We do not keep TODO items open in the issue - tracker. + *enhancement* or *feature-request* and get added to the `TODO` document and + the issues are closed. We do not keep TODO items open in the issue tracker. The `TODO` document is full of ideas and suggestions of what we can add or fix one day. You are always encouraged and free to grab one of those items and @@ -255,11 +254,11 @@ ## Closing off stalled bugs - The [issue and pull request trackers](https://github.com/curl/curl) only - hold "active" entries open (using a non-precise definition of what active - actually is, but they are at least not completely dead). Those that are - abandoned or in other ways dormant will be closed and sometimes added to - `TODO` and `KNOWN_BUGS` instead. + The [issue and pull request trackers](https://github.com/curl/curl) only hold + "active" entries open (using a non-precise definition of what active actually + is, but they are at least not completely dead). Those that are abandoned or + in other ways dormant are closed and sometimes added to `TODO` and + `KNOWN_BUGS` instead. This way, we only have "active" issues open on GitHub. Irrelevant issues and - pull requests will not distract developers or casual visitors. + pull requests do not distract developers or casual visitors. diff --git a/docs/CHECKSRC.md b/docs/CHECKSRC.md index f73e7a8347a..fc500453591 100644 --- a/docs/CHECKSRC.md +++ b/docs/CHECKSRC.md @@ -12,7 +12,7 @@ check that it adheres to our [Source Code Style guide](CODE_STYLE.md). `-W[file]` skip that file and exclude it from being checked. Helpful when, for example, one of the files is generated. -`-D[dir]` directory name to prepend to file names when accessing them. +`-D[dir]` directory name to prepend to filenames when accessing them. `-h` shows the help output, that also lists all recognized warnings @@ -73,7 +73,7 @@ warnings are: - `FOPENMODE`: `fopen()` needs a macro for the mode string, use it - `INDENTATION`: detected a wrong start column for code. Note that this - warning only checks some specific places and will certainly miss many bad + warning only checks some specific places and can certainly miss many bad indentations. - `LONGLINE`: A line is longer than 79 columns. @@ -158,21 +158,21 @@ Example /* !checksrc! disable LONGLINE all */ -This will ignore the warning for overly long lines until it is re-enabled with: +This ignores the warning for overly long lines until it is re-enabled with: /* !checksrc! enable LONGLINE */ -If the enabling is not performed before the end of the file, it will be enabled -automatically for the next file. +If the enabling is not performed before the end of the file, it is enabled +again automatically for the next file. You can also opt to ignore just N violations so that if you have a single long line you just cannot shorten and is agreed to be fine anyway: /* !checksrc! disable LONGLINE 1 */ -... and the warning for long lines will be enabled again automatically after -it has ignored that single warning. The number `1` can of course be changed to -any other integer number. It can be used to make sure only the exact intended +... and the warning for long lines is enabled again automatically after it has +ignored that single warning. The number `1` can of course be changed to any +other integer number. It can be used to make sure only the exact intended instances are ignored and nothing extra. ### Directory wide ignore patterns diff --git a/docs/CIPHERS.md b/docs/CIPHERS.md index 27de9403632..1fb8540584d 100644 --- a/docs/CIPHERS.md +++ b/docs/CIPHERS.md @@ -290,9 +290,9 @@ next section. There is also the case that the selected algorithm is not supported by the protocol or does not match the ciphers offered by the server during the SSL -negotiation. In this case curl will return error +negotiation. In this case curl returns error `CURLE_SSL_CONNECT_ERROR (35) SEC_E_ALGORITHM_MISMATCH` -and the request will fail. +and the request fails. `CALG_MD2`, `CALG_MD4`, @@ -353,7 +353,7 @@ are running an outdated OS you might still be supporting weak ciphers. You can set TLS 1.3 ciphers for Schannel by using `CURLOPT_TLS13_CIPHERS` or `--tls13-ciphers` with the names below. -If TLS 1.3 cipher suites are set then libcurl will add or restrict Schannel TLS +If TLS 1.3 cipher suites are set then libcurl adds or restricts Schannel TLS 1.3 algorithms automatically. Essentially, libcurl is emulating support for individual TLS 1.3 cipher suites since Schannel does not support it directly. @@ -363,10 +363,10 @@ individual TLS 1.3 cipher suites since Schannel does not support it directly. `TLS_AES_128_CCM_8_SHA256` `TLS_AES_128_CCM_SHA256` -Note if you set TLS 1.3 ciphers without also setting the minimum TLS version to -1.3 then it's possible Schannel may negotiate an earlier TLS version and cipher -suite if your libcurl and OS settings allow it. You can set the minimum TLS -version by using `CURLOPT_SSLVERSION` or `--tlsv1.3`. +Note if you set TLS 1.3 ciphers without also setting the minimum TLS version +to 1.3 then it is possible Schannel may negotiate an earlier TLS version and +cipher suite if your libcurl and OS settings allow it. You can set the minimum +TLS version by using `CURLOPT_SSLVERSION` or `--tlsv1.3`. ## BearSSL diff --git a/docs/CLIENT-READERS.md b/docs/CLIENT-READERS.md new file mode 100644 index 00000000000..dec35b3282e --- /dev/null +++ b/docs/CLIENT-READERS.md @@ -0,0 +1,126 @@ +# curl client readers + +Client readers is a design in the internals of libcurl, not visible in its public API. They were started +in curl v8.7.0. This document describes the concepts, its high level implementation and the motivations. + +## Naming + +`libcurl` operates between clients and servers. A *client* is the application using libcurl, like the command line tool `curl` itself. Data to be uploaded to a server is **read** from the client and **sent** to the server, the servers response is **received** by `libcurl` and then **written** to the client. + +With this naming established, client readers are concerned with providing data from the application to the server. Applications register callbacks via `CURLOPT_READFUNCTION`, data via `CURLOPT_POSTFIELDS` and other options to be used by `libcurl` when the request is send. + +## Invoking + +The transfer loop that sends and receives, is using `Curl_client_read()` to get more data to send for a transfer. If no specific reader has been installed yet, the default one that uses `CURLOPT_READFUNCTION` is added. The prototype is + +``` +CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen, + size_t *nread, bool *eos); +``` +The arguments are the transfer to read for, a buffer to hold the read data, its length, the actual number of bytes placed into the buffer and the `eos` (*end of stream*) flag indicating that no more data is available. The `eos` flag may be set for a read amount, if that amount was the last. That way curl can avoid to read an additional time. + +The implementation of `Curl_client_read()` uses a chain of *client reader* instances to get the data. This is similar to the design of *client writers*. The chain of readers allows processing of the data to send. + +The definition of a reader is: + +``` +struct Curl_crtype { + const char *name; /* writer name. */ + CURLcode (*do_init)(struct Curl_easy *data, struct Curl_creader *writer); + CURLcode (*do_read)(struct Curl_easy *data, struct Curl_creader *reader, + char *buf, size_t blen, size_t *nread, bool *eos); + void (*do_close)(struct Curl_easy *data, struct Curl_creader *reader); + bool (*needs_rewind)(struct Curl_easy *data, struct Curl_creader *reader); + curl_off_t (*total_length)(struct Curl_easy *data, + struct Curl_creader *reader); + CURLcode (*resume_from)(struct Curl_easy *data, + struct Curl_creader *reader, curl_off_t offset); + CURLcode (*rewind)(struct Curl_easy *data, struct Curl_creader *reader); +}; + +struct Curl_creader { + const struct Curl_crtype *crt; /* type implementation */ + struct Curl_creader *next; /* Downstream reader. */ + Curl_creader_phase phase; /* phase at which it operates */ +}; +``` + +`Curl_creader` is a reader instance with a `next` pointer to form the chain. It as a type `crt` which provides the implementation. The main callback is `do_read()` which provides the data to the caller. The others are for setup and tear down. `needs_rewind()` is explained further below. + +## Phases and Ordering + +Since client readers may transform the data being read through the chain, the order in which they are called is relevant for the outcome. When a reader is created, it gets the `phase` property in which it operates. Reader phases are defined like: + +``` +typedef enum { + CURL_CR_NET, /* data send to the network (connection filters) */ + CURL_CR_TRANSFER_ENCODE, /* add transfer-encodings */ + CURL_CR_PROTOCOL, /* before transfer, but after content decoding */ + CURL_CR_CONTENT_ENCODE, /* add content-encodings */ + CURL_CR_CLIENT /* data read from client */ +} Curl_creader_phase; +``` + +If a reader for phase `PROTOCOL` is added to the chain, it is always added *after* any `NET` or `TRANSFER_ENCODE` readers and *before* and `CONTENT_ENCODE` and `CLIENT` readers. If there is already a reader for the same phase, the new reader is added before the existing one(s). + +### Example: `chunked` reader + +In `http_chunks.c` a client reader for chunked uploads is implemented. This one operates at phase `CURL_CR_TRANSFER_ENCODE`. Any data coming from the reader "below" has the HTTP/1.1 chunk handling applied and returned to the caller. + +When this reader sees an `eos` from below, it generates the terminal chunk, adding trailers if provided by the application. When that last chunk is fully returned, it also sets `eos` to the caller. + +### Example: `lineconv` reader + +In `sendf.c` a client reader that does line-end conversions is implemented. It operates at `CURL_CR_CONTENT_ENCODE` and converts any "\n" to "\r\n". This is used for FTP ASCII uploads or when the general `crlf` options has been set. + +### Example: `null` reader + +Implemented in `sendf.c` for phase `CURL_CR_CLIENT`, this reader has the simple job of providing transfer bytes of length 0 to the caller, immediately indicating an `eos`. This reader is installed by HTTP for all GET/HEAD requests and when authentication is being negotiated. + +### Example: `buf` reader + +Implemented in `sendf.c` for phase `CURL_CR_CLIENT`, this reader get a buffer pointer and a length and provides exactly these bytes. This one is used in HTTP for sending `postfields` provided by the application. + +## Request retries + +Sometimes it is necessary to send a request with client data again. Transfer handling can inquire via `Curl_client_read_needs_rewind()` if a rewind (e.g. a reset of the client data) is necessary. This asks all installed readers if they need it and give `FALSE` of none does. + +## Upload Size + +Many protocols need to know the amount of bytes delivered by the client readers in advance. They may invoke `Curl_creader_total_length(data)` to retrieve that. However, not all reader chains know the exact value beforehand. In that case, the call returns `-1` for "unknown". + +Even if the length of the "raw" data is known, the length that is send may not. Example: with option `--crlf` the uploaded content undergoes line-end conversion. The line converting reader does not know in advance how many newlines it may encounter. Therefore it must return `-1` for any positive raw content length. + +In HTTP, once the correct client readers are installed, the protocol asks the readers for the total length. If that is known, it can set `Content-Length:` accordingly. If not, it may choose to add an HTTP "chunked" reader. + +In addition, there is `Curl_creader_client_length(data)` which gives the total length as reported by the reader in phase `CURL_CR_CLIENT` without asking other readers that may transform the raw data. This is useful in estimating the size of an upload. The HTTP protocol uses this to determine if `Expect: 100-continue` shall be done. + +## Resuming + +Uploads can start at a specific offset, if so requested. The "resume from" that offset. This applies to the reader in phase `CURL_CR_CLIENT` that delivers the "raw" content. Resumption can fail if the installed reader does not support it or if the offset is too large. + +The total length reported by the reader changes when resuming. Example: resuming an upload of 100 bytes by 25 reports a total length of 75 afterwards. + +If `resume_from()` is invoked twice, it is additive. There is currently no way to undo a resume. + +## Rewinding + +When a request is retried, installed client readers are discarded and replaced by new ones. This works only if the new readers upload the same data. For many readers, this is not an issue. The "null" reader always does the same. Also the `buf` reader, initialized with the same buffer, does this. + +Readers operating on callbacks to the application need to "rewind" the underlying content. For example, when reading from a `FILE*`, the reader needs to `fseek()` to the beginning. The following methods are used: + +1. `Curl_creader_needs_rewind(data)`: tells if a rewind is necessary, given the current state of the reader chain. If nothing really has been read so far, this returns `FALSE`. +2. `Curl_creader_will_rewind(data)`: tells if the reader chain rewinds at the start of the next request. +3. `Curl_creader_set_rewind(data, TRUE)`: marks the reader chain for rewinding at the start of the next request. +4. `Curl_client_start(data)`: tells the readers that a new request starts and they need to rewind if requested. + + +## Summary and Outlook + +By adding the client reader interface, any protocol can control how/if it wants the curl transfer to send bytes for a request. The transfer loop becomes then blissfully ignorant of the specifics. + +The protocols on the other hand no longer have to care to package data most efficiently. At any time, should more data be needed, it can be read from the client. This is used when sending HTTP requests headers to add as much request body data to the initial sending as there is room for. + +Future enhancements based on the client readers: +* `expect-100` handling: place that into a HTTP specific reader at `CURL_CR_PROTOCOL` and eliminate the checks in the generic transfer parts. +* `eos forwarding`: transfer should forward an `eos` flag to the connection filters. Filters like HTTP/2 and HTTP/3 can make use of that, terminating streams early. This would also eliminate length checks in stream handling. diff --git a/docs/CLIENT-WRITERS.md b/docs/CLIENT-WRITERS.md new file mode 100644 index 00000000000..47e802f1215 --- /dev/null +++ b/docs/CLIENT-WRITERS.md @@ -0,0 +1,117 @@ +# curl client writers + +Client writers is a design in the internals of libcurl, not visible in its public API. They were started +in curl v8.5.0. This document describes the concepts, its high level implementation and the motivations. + +## Naming + +`libcurl` operates between clients and servers. A *client* is the application using libcurl, like the command line tool `curl` itself. Data to be uploaded to a server is **read** from the client and **send** to the server, the servers response is **received** by `libcurl` and then **written** to the client. + +With this naming established, client writers are concerned with writing responses from the server to the application. Applications register callbacks via `CURLOPT_WRITEFUNCTION` and `CURLOPT_HEADERFUNCTION` to be invoked by `libcurl` when the response is received. + +## Invoking + +All code in `libcurl` that handles response data is ultimately expected to forward this data via `Curl_client_write()` to the application. The exact prototype of this function is: + +``` +CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *buf, size_t blen); +``` +The `type` argument specifies what the bytes in `buf` actually are. The following bits are defined: + +``` +#define CLIENTWRITE_BODY (1<<0) /* non-meta information, BODY */ +#define CLIENTWRITE_INFO (1<<1) /* meta information, not a HEADER */ +#define CLIENTWRITE_HEADER (1<<2) /* meta information, HEADER */ +#define CLIENTWRITE_STATUS (1<<3) /* a special status HEADER */ +#define CLIENTWRITE_CONNECT (1<<4) /* a CONNECT related HEADER */ +#define CLIENTWRITE_1XX (1<<5) /* a 1xx response related HEADER */ +#define CLIENTWRITE_TRAILER (1<<6) /* a trailer HEADER */ +``` + +The main types here are `CLIENTWRITE_BODY` and `CLIENTWRITE_HEADER`. They are +mutually exclusive. The other bits are enhancements to `CLIENTWRITE_HEADER` to +specify what the header is about. They are only used in HTTP and related +protocols (RTSP and WebSocket). + +The implementation of `Curl_client_write()` uses a chain of *client writer* instances to process the call and make sure that the bytes reach the proper application callbacks. This is similar to the design of connection filters: client writers can be chained to process the bytes written through them. The definition is: + +``` +struct Curl_cwtype { + const char *name; + CURLcode (*do_init)(struct Curl_easy *data, + struct Curl_cwriter *writer); + CURLcode (*do_write)(struct Curl_easy *data, + struct Curl_cwriter *writer, int type, + const char *buf, size_t nbytes); + void (*do_close)(struct Curl_easy *data, + struct Curl_cwriter *writer); +}; + +struct Curl_cwriter { + const struct Curl_cwtype *cwt; /* type implementation */ + struct Curl_cwriter *next; /* Downstream writer. */ + Curl_cwriter_phase phase; /* phase at which it operates */ +}; +``` + +`Curl_cwriter` is a writer instance with a `next` pointer to form the chain. It has a type `cwt` which provides the implementation. The main callback is `do_write()` that processes the data and calls then the `next` writer. The others are for setup and tear down. + +## Phases and Ordering + +Since client writers may transform the bytes written through them, the order in which the are called is relevant for the outcome. When a writer is created, one property it gets is the `phase` in which it operates. Writer phases are defined like: + +``` +typedef enum { + CURL_CW_RAW, /* raw data written, before any decoding */ + CURL_CW_TRANSFER_DECODE, /* remove transfer-encodings */ + CURL_CW_PROTOCOL, /* after transfer, but before content decoding */ + CURL_CW_CONTENT_DECODE, /* remove content-encodings */ + CURL_CW_CLIENT /* data written to client */ +} Curl_cwriter_phase; +``` + +If a writer for phase `PROTOCOL` is added to the chain, it is always added *after* any `RAW` or `TRANSFER_DECODE` and *before* any `CONTENT_DECODE` and `CLIENT` phase writer. If there is already a writer for the same phase present, the new writer is inserted just before that one. + +All transfers have a chain of 3 writers by default. A specific protocol handler may alter that by adding additional writers. The 3 standard writers are (name, phase): + +1. `"raw", CURL_CW_RAW `: if the transfer is verbose, it forwards the body data to the debug function. +1. `"download", CURL_CW_PROTOCOL`: checks that protocol limits are kept and updates progress counters. When a download has a known length, it checks that it is not exceeded and errors otherwise. +1. `"client", CURL_CW_CLIENT`: the main work horse. It invokes the application callbacks or writes to the configured file handles. It chops large writes into smaller parts, as documented for `CURLOPT_WRITEFUNCTION`. If also handles *pausing* of transfers when the application callback returns `CURL_WRITEFUNC_PAUSE`. + +With these writers always in place, libcurl's protocol handlers automatically have these implemented. + +## Enhanced Use + +HTTP is the protocol in curl that makes use of the client writer chain by +adding writers to it. When the `libcurl` application set +`CURLOPT_ACCEPT_ENCODING` (as `curl` does with `--compressed`), the server is +offered an `Accept-Encoding` header with the algorithms supported. The server +then may choose to send the response body compressed. For example using `gzip` +or `brotli` or even both. + +In the server's response, if there is a `Content-Encoding` header listing the +encoding applied. If supported by `libcurl` it then decompresses the content +before writing it out to the client. How does it do that? + +The HTTP protocol adds client writers in phase `CURL_CW_CONTENT_DECODE` on +seeing such a header. For each encoding listed, it adds the corresponding +writer. The response from the server is then passed through +`Curl_client_write()` to the writers that decode it. If several encodings had +been applied the writer chain decodes them in the proper order. + +When the server provides a `Content-Length` header, that value applies to the +*compressed* content. Length checks on the response bytes must happen *before* +it gets decoded. That is why this check happens in phase `CURL_CW_PROTOCOL` +which always is ordered before writers in phase `CURL_CW_CONTENT_DECODE`. + +What else? + +Well, HTTP servers may also apply a `Transfer-Encoding` to the body of a response. The most well-known one is `chunked`, but algorithms like `gzip` and friends could also be applied. The difference to content encodings is that decoding needs to happen *before* protocol checks, for example on length, are done. + +That is why transfer decoding writers are added for phase `CURL_CW_TRANSFER_DECODE`. Which makes their operation happen *before* phase `CURL_CW_PROTOCOL` where length may be checked. + +## Summary + +By adding the common behavior of all protocols into `Curl_client_write()` we make sure that they do apply everywhere. Protocol handler have less to worry about. Changes to default behavior can be done without affecting handler implementations. + +Having a writer chain as implementation allows protocol handlers with extra needs, like HTTP, to add to this for special behavior. The common way of writing the actual response data stays the same. diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index dd2c6dc74ee..9c0b3769178 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -22,5 +22,9 @@ # ########################################################################### #add_subdirectory(examples) -add_subdirectory(libcurl) -add_subdirectory(cmdline-opts) +if(BUILD_LIBCURL_DOCS) + add_subdirectory(libcurl) +endif() +if(ENABLE_CURL_MANUAL AND BUILD_CURL_EXE) + add_subdirectory(cmdline-opts) +endif() diff --git a/docs/CODE_STYLE.md b/docs/CODE_STYLE.md index 9cdf0d17e47..970a3b0aec1 100644 --- a/docs/CODE_STYLE.md +++ b/docs/CODE_STYLE.md @@ -19,7 +19,7 @@ particularly unusual rules in our set of rules. We also work hard on writing code that are warning-free on all the major platforms and in general on as many platforms as possible. Code that obviously -will cause warnings will not be accepted as-is. +causes warnings is not accepted as-is. ## Naming @@ -218,10 +218,10 @@ int size = sizeof(int); Some statements cannot be completed on a single line because the line would be too long, the statement too hard to read, or due to other style guidelines -above. In such a case the statement will span multiple lines. +above. In such a case the statement spans multiple lines. If a continuation line is part of an expression or sub-expression then you -should align on the appropriate column so that it's easy to tell what part of +should align on the appropriate column so that it is easy to tell what part of the statement it is. Operators should not start continuation lines. In other cases follow the 2-space indent guideline. Here are some examples from libcurl: diff --git a/docs/CONNECTION-FILTERS.md b/docs/CONNECTION-FILTERS.md index c4b11dbb01d..95b6d50d7a7 100644 --- a/docs/CONNECTION-FILTERS.md +++ b/docs/CONNECTION-FILTERS.md @@ -1,16 +1,26 @@ # curl connection filters -Connection filters is a design in the internals of curl, not visible in its public API. They were added -in curl v7.xx.x. This document describes the concepts, its high level implementation and the motivations. +Connection filters is a design in the internals of curl, not visible in its +public API. They were added in curl v7.87.0. This document describes the +concepts, its high level implementation and the motivations. ## Filters -A "connection filter" is a piece of code that is responsible for handling a range of operations -of curl's connections: reading, writing, waiting on external events, connecting and closing down - to name the most important ones. +A "connection filter" is a piece of code that is responsible for handling a +range of operations of curl's connections: reading, writing, waiting on +external events, connecting and closing down - to name the most important +ones. -The most important feat of connection filters is that they can be stacked on top of each other (or "chained" if you prefer that metaphor). In the common scenario that you want to retrieve a `https:` url with curl, you need 2 basic things to send the request and get the response: a TCP connection, represented by a `socket` and a SSL instance en- and decrypt over that socket. You write your request to the SSL instance, which encrypts and writes that data to the socket, which then sends the bytes over the network. +The most important feat of connection filters is that they can be stacked on +top of each other (or "chained" if you prefer that metaphor). In the common +scenario that you want to retrieve a `https:` URL with curl, you need 2 basic +things to send the request and get the response: a TCP connection, represented +by a `socket` and a SSL instance en- and decrypt over that socket. You write +your request to the SSL instance, which encrypts and writes that data to the +socket, which then sends the bytes over the network. -With connection filters, curl's internal setup will look something like this (cf for connection filter): +With connection filters, curl's internal setup looks something like this (cf +for connection filter): ``` Curl_easy *data connectdata *conn cf-ssl cf-socket @@ -23,11 +33,17 @@ Curl_easy *data connectdata *conn cf-ssl cf-socket ---> conn->filter->write(conn->filter, data, buffer) ``` -While connection filters all do different things, they look the same from the "outside". The code in `data` and `conn` does not really know **which** filters are installed. `conn` just writes into the first filter, whatever that is. +While connection filters all do different things, they look the same from the +"outside". The code in `data` and `conn` does not really know **which** +filters are installed. `conn` just writes into the first filter, whatever that +is. -Same is true for filters. Each filter has a pointer to the `next` filter. When SSL has encrypted the data, it does not write to a socket, it writes to the next filter. If that is indeed a socket, or a file, or an HTTP/2 connection is of no concern to the SSL filter. +Same is true for filters. Each filter has a pointer to the `next` filter. When +SSL has encrypted the data, it does not write to a socket, it writes to the +next filter. If that is indeed a socket, or a file, or an HTTP/2 connection is +of no concern to the SSL filter. -And this allows the stacking, as in: +This allows stacking, as in: ``` Direct: @@ -45,7 +61,12 @@ Via http proxy tunnel via SOCKS proxy: ### Connecting/Closing -Before `Curl_easy` can send the request, the connection needs to be established. This means that all connection filters have done, whatever they need to do: waiting for the socket to be connected, doing the TLS handshake, performing the HTTP tunnel request, etc. This has to be done in reverse order: the last filter has to do its connect first, then the one above can start, etc. +Before `Curl_easy` can send the request, the connection needs to be +established. This means that all connection filters have done, whatever they +need to do: waiting for the socket to be connected, doing the TLS handshake, +performing the HTTP tunnel request, etc. This has to be done in reverse order: +the last filter has to do its connect first, then the one above can start, +etc. Each filter does in principle the following: @@ -72,12 +93,14 @@ myfilter_cf_connect(struct Curl_cfilter *cf, } ``` -Closing a connection then works similar. The `conn` tells the first filter to close. Contrary to connecting, -the filter does its own things first, before telling the next filter to close. +Closing a connection then works similar. The `conn` tells the first filter to +close. Contrary to connecting, the filter does its own things first, before +telling the next filter to close. ### Efficiency -There are two things curl is concerned about: efficient memory use and fast transfers. +There are two things curl is concerned about: efficient memory use and fast +transfers. The memory footprint of a filter is relatively small: @@ -91,13 +114,24 @@ struct Curl_cfilter { BIT(connected); /* != 0 iff this filter is connected */ }; ``` -The filter type `cft` is a singleton, one static struct for each type of filter. The `ctx` is where a filter will hold its specific data. That varies by filter type. An http-proxy filter will keep the ongoing state of the CONNECT here, but free it after its has been established. The SSL filter will keep the `SSL*` (if OpenSSL is used) here until the connection is closed. So, this varies. -`conn` is a reference to the connection this filter belongs to, so nothing extra besides the pointer itself. +The filter type `cft` is a singleton, one static struct for each type of +filter. The `ctx` is where a filter holds its specific data. That varies by +filter type. An http-proxy filter keeps the ongoing state of the CONNECT here, +free it after its has been established. The SSL filter keeps the `SSL*` (if +OpenSSL is used) here until the connection is closed. So, this varies. -Several things, that before were kept in `struct connectdata`, will now go into the `filter->ctx` *when needed*. So, the memory footprint for connections that do *not* use an http proxy, or socks, or https will be lower. +`conn` is a reference to the connection this filter belongs to, so nothing +extra besides the pointer itself. -As to transfer efficiency, writing and reading through a filter comes at near zero cost *if the filter does not transform the data*. An http proxy or socks filter, once it is connected, will just pass the calls through. Those filters implementations will look like this: +Several things, that before were kept in `struct connectdata`, now goes into +the `filter->ctx` *when needed*. So, the memory footprint for connections that +do *not* use an http proxy, or socks, or https is lower. + +As to transfer efficiency, writing and reading through a filter comes at near +zero cost *if the filter does not transform the data*. An http proxy or socks +filter, once it is connected, just passes the calls through. Those filters +implementations look like this: ``` ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data, @@ -110,18 +144,159 @@ The `recv` implementation is equivalent. ## Filter Types -The (currently) existing filter types are: SOCKET, SOCKET-ACCEPT, SSL, HTTP-PROXY and SOCKS-PROXY. Vital to establishing and read/writing a connection. But filters are also a good way to implement tasks for *managing* a connection: +The currently existing filter types (curl 8.5.0) are: + +* `TCP`, `UDP`, `UNIX`: filters that operate on a socket, providing raw I/O. +* `SOCKET-ACCEPT`: special TCP socket that has a socket that has been + `accept()`ed in a `listen()` +* `SSL`: filter that applies TLS en-/decryption and handshake. Manages the + underlying TLS backend implementation. +* `HTTP-PROXY`, `H1-PROXY`, `H2-PROXY`: the first manages the connection to an + HTTP proxy server and uses the other depending on which ALPN protocol has + been negotiated. +* `SOCKS-PROXY`: filter for the various SOCKS proxy protocol variations +* `HAPROXY`: filter for the protocol of the same name, providing client IP + information to a server. +* `HTTP/2`: filter for handling multiplexed transfers over an HTTP/2 + connection +* `HTTP/3`: filter for handling multiplexed transfers over an HTTP/3+QUIC + connection +* `HAPPY-EYEBALLS`: meta filter that implements IPv4/IPv6 "happy eyeballing". + It creates up to 2 sub-filters that race each other for a connection. +* `SETUP`: meta filter that manages the creation of sub-filter chains for a + specific transport (e.g. TCP or QUIC). +* `HTTPS-CONNECT`: meta filter that races a TCP+TLS and a QUIC connection + against each other to determine if HTTP/1.1, HTTP/2 or HTTP/3 shall be used + for a transfer. + +Meta filters are combining other filters for a specific purpose, mostly during +connection establishment. Other filters like `TCP`, `UDP` and `UNIX` are only +to be found at the end of filter chains. SSL filters provide encryption, of +course. Protocol filters change the bytes sent and received. + +## Filter Flags + +Filter types carry flags that inform what they do. These are (for now): + +* `CF_TYPE_IP_CONNECT`: this filter type talks directly to a server. This does + not have to be the server the transfer wants to talk to. For example when a + proxy server is used. +* `CF_TYPE_SSL`: this filter type provides encryption. +* `CF_TYPE_MULTIPLEX`: this filter type can manage multiple transfers in parallel. + +Filter types can combine these flags. For example, the HTTP/3 filter types +have `CF_TYPE_IP_CONNECT`, `CF_TYPE_SSL` and `CF_TYPE_MULTIPLEX` set. + +Flags are useful to extrapolate properties of a connection. To check if a +connection is encrypted, libcurl inspect the filter chain in place, top down, +for `CF_TYPE_SSL`. If it finds `CF_TYPE_IP_CONNECT` before any `CF_TYPE_SSL`, +the connection is not encrypted. + +For example, `conn1` is for a `http:` request using a tunnel through an HTTP/2 +`https:` proxy. `conn2` is a `https:` HTTP/2 connection to the same proxy. +`conn3` uses HTTP/3 without proxy. The filter chains would look like this +(simplified): + +``` +conn1 --> `HTTP-PROXY` --> `H2-PROXY` --> `SSL` --> `TCP` +flags: `IP_CONNECT` `SSL` `IP_CONNECT` + +conn2 --> `HTTP/2` --> `SSL` --> `HTTP-PROXY` --> `H2-PROXY` --> `SSL` --> `TCP` +flags: `SSL` `IP_CONNECT` `SSL` `IP_CONNECT` + +conn3 --> `HTTP/3` +flags: `SSL|IP_CONNECT` +``` + +Inspecting the filter chains, `conn1` is seen as unencrypted, since it +contains an `IP_CONNECT` filter before any `SSL`. `conn2` is clearly encrypted +as an `SSL` flagged filter is seen first. `conn3` is also encrypted as the +`SSL` flag is checked before the presence of `IP_CONNECT`. + +Similar checks can determine if a connection is multiplexed or not. + +## Filter Tracing + +Filters may make use of special trace macros like `CURL_TRC_CF(data, cf, msg, +...)`. With `data` being the transfer and `cf` being the filter instance. +These traces are normally not active and their execution is guarded so that +they are cheap to ignore. + +Users of `curl` may activate them by adding the name of the filter type to the +`--trace-config` argument. For example, in order to get more detailed tracing +of an HTTP/2 request, invoke curl with: + +``` +> curl -v --trace-config ids,time,http/2 https://curl.se +``` + +Which gives you trace output with time information, transfer+connection ids +and details from the `HTTP/2` filter. Filter type names in the trace config +are case insensitive. You may use `all` to enable tracing for all filter +types. When using `libcurl` you may call `curl_global_trace(config_string)` at +the start of your application to enable filter details. + +## Meta Filters + +Meta filters is a catch-all name for filter types that do not change the +transfer data in any way but provide other important services to curl. In +general, it is possible to do all sorts of silly things with them. One of the +commonly used, important things is "eyeballing". -* **Statistics**: a filter that counts the number of bytes sent/received. Place one in front of SOCKET and one higher up and get the number of raw and "easy" bytes transferred. They may track the speed as well, or number of partial writes, etc. -* **Timeout**: enforce timeouts, e.g. fail if a connection cannot be established in a certain amount of time. -* **Progress**: report progress on a connection. -* **Pacing**: limit read/write rates. -* **Testing**: simulate network condition or failures. +The `HAPPY-EYEBALLS` filter is involved in the connect phase. Its job is to +try the various IPv4 and IPv6 addresses that are known for a server. If only +one address family is known (or configured), it tries the addresses one after +the other with timeouts calculated from the amount of addresses and the +overall connect timeout. -As you see, filters are a good way to add functionality to curl's internal handling of transfers without impact on other code. +When more than one address family is to be tried, it splits the address list +into IPv4 and IPv6 and makes parallel attempts. The connection filter chain +looks like this: + +``` +* create connection for http://curl.se +conn[curl.se] --> SETUP[TCP] --> HAPPY-EYEBALLS --> NULL +* start connect +conn[curl.se] --> SETUP[TCP] --> HAPPY-EYEBALLS --> NULL + - ballerv4 --> TCP[151.101.1.91]:443 + - ballerv6 --> TCP[2a04:4e42:c00::347]:443 +* v6 answers, connected +conn[curl.se] --> SETUP[TCP] --> HAPPY-EYEBALLS --> TCP[2a04:4e42:c00::347]:443 +* transfer +``` -## Easy Filters? +The modular design of connection filters and that we can plug them into each other is used to control the parallel attempts. When a `TCP` filter does not connect (in time), it is torn down and another one is created for the next address. This keeps the `TCP` filter simple. -Some things that curl needs to manage are not directly tied to a specific connection but the property of the `Curl_easy` handle, e.g. a particular transfer. When using HTTP/2 or HTTP/3, many transfers can use the same connection. If one wants to monitor of the transfer itself or restricting its speed alone, a connection filter is not the right place to do this. +The `HAPPY-EYEBALLS` on the other hand stays focused on its side of the problem. We can use it also to make other type of connection by just giving it another filter type to try to have happy eyeballing for QUIC: -So we might add "easy filters" one day. Who knows? +``` +* create connection for --http3-only https://curl.se +conn[curl.se] --> SETUP[QUIC] --> HAPPY-EYEBALLS --> NULL +* start connect +conn[curl.se] --> SETUP[QUIC] --> HAPPY-EYEBALLS --> NULL + - ballerv4 --> HTTP/3[151.101.1.91]:443 + - ballerv6 --> HTTP/3[2a04:4e42:c00::347]:443 +* v6 answers, connected +conn[curl.se] --> SETUP[QUIC] --> HAPPY-EYEBALLS --> HTTP/3[2a04:4e42:c00::347]:443 +* transfer +``` + +When we plug these two variants together, we get the `HTTPS-CONNECT` filter +type that is used for `--http3` when **both** HTTP/3 and HTTP/2 or HTTP/1.1 +shall be attempted: + +``` +* create connection for --http3 https://curl.se +conn[curl.se] --> HTTPS-CONNECT --> NULL +* start connect +conn[curl.se] --> HTTPS-CONNECT --> NULL + - SETUP[QUIC] --> HAPPY-EYEBALLS --> NULL + - ballerv4 --> HTTP/3[151.101.1.91]:443 + - ballerv6 --> HTTP/3[2a04:4e42:c00::347]:443 + - SETUP[TCP] --> HAPPY-EYEBALLS --> NULL + - ballerv4 --> TCP[151.101.1.91]:443 + - ballerv6 --> TCP[2a04:4e42:c00::347]:443 +* v4 QUIC answers, connected +conn[curl.se] --> HTTPS-CONNECT --> SETUP[QUIC] --> HAPPY-EYEBALLS --> HTTP/3[151.101.1.91]:443 +* transfer +``` diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md index 72d31900195..6288dac90d2 100644 --- a/docs/CONTRIBUTE.md +++ b/docs/CONTRIBUTE.md @@ -35,14 +35,14 @@ must use "GPL compatible" licenses (as we want to allow users to use libcurl properly in GPL licensed environments). When changing existing source code, you do not alter the copyright of the -original file(s). The copyright will still be owned by the original creator(s) -or those who have been assigned copyright by the original author(s). +original file(s). The copyright is still owned by the original creator(s) or +those who have been assigned copyright by the original author(s). By submitting a patch to the curl project, you are assumed to have the right to the code and to be allowed by your employer or whatever to hand over that -patch/code to us. We will credit you for your changes as far as possible, to -give credit but also to keep a trace back to who made what changes. Please -always provide us with your full real name when contributing, +patch/code to us. We credit you for your changes as far as possible, to give +credit but also to keep a trace back to who made what changes. Please always +provide us with your full real name when contributing, ## What To Read @@ -50,10 +50,10 @@ Source code, the man pages, the [INTERNALS document](https://curl.se/dev/internals.html), [TODO](https://curl.se/docs/todo.html), [KNOWN_BUGS](https://curl.se/docs/knownbugs.html) and the [most recent -changes](https://curl.se/dev/sourceactivity.html) in git. Just lurking on -the [curl-library mailing -list](https://curl.se/mail/list.cgi?list=curl-library) will give you a -lot of insights on what's going on right now. Asking there is a good idea too. +changes](https://curl.se/dev/sourceactivity.html) in git. Just lurking on the +[curl-library mailing list](https://curl.se/mail/list.cgi?list=curl-library) +gives you a lot of insights on what's going on right now. Asking there is a +good idea too. ## Write a good patch @@ -101,22 +101,23 @@ archive is quite OK as well. ### Documentation Writing docs is dead boring and one of the big problems with many open source -projects. But someone's gotta do it. It makes things a lot easier if you -submit a small description of your fix or your new features with every -contribution so that it can be swiftly added to the package documentation. +projects but someone's gotta do it. It makes things a lot easier if you submit +a small description of your fix or your new features with every contribution +so that it can be swiftly added to the package documentation. -The documentation is always made in man pages (nroff formatted) or plain -ASCII files. All HTML files on the website and in the release archives are -generated from the nroff/ASCII versions. +Documentation is mostly provided as manpages or plain ASCII files. The +manpages are rendered from their source files that are usually written using +markdown. Most HTML files on the website and in the release archives are +generated from corresponding markdown and ASCII files. ### Test Cases Since the introduction of the test suite, we can quickly verify that the main features are working as they are supposed to. To maintain this situation and -improve it, all new features and functions that are added need to be tested -in the test suite. Every feature that is added should get at least one valid -test case that verifies that it works as documented. If every submitter also -posts a few test cases, it will not end up as a heavy burden on a single person! +improve it, all new features and functions that are added need to be tested in +the test suite. Every feature that is added should get at least one valid test +case that verifies that it works as documented. If every submitter also posts +a few test cases, it does not end up a heavy burden on a single person. If you do not have test cases or perhaps you have done something that is hard to write tests for, do explain exactly how you have otherwise tested and @@ -131,19 +132,19 @@ GitHub](https://github.com/curl/curl/pulls), but you can also send your plain patch to [the curl-library mailing list](https://curl.se/mail/list.cgi?list=curl-library). -If you opt to post a patch on the mailing list, chances are someone will -convert it into a pull request for you, to have the CI jobs verify it proper -before it can be merged. Be prepared that some feedback on the proposed change -might then come on GitHub. +If you opt to post a patch on the mailing list, chances are someone converts +it into a pull request for you, to have the CI jobs verify it proper before it +can be merged. Be prepared that some feedback on the proposed change might +then come on GitHub. -Your change will be reviewed and discussed and you will be expected to correct -flaws pointed out and update accordingly, or the change risks stalling and +Your changes be reviewed and discussed and you are expected to correct flaws +pointed out and update accordingly, or the change risks stalling and eventually just getting deleted without action. As a submitter of a change, you are the owner of that change until it has been merged. Respond on the list or on GitHub about the change and answer questions and/or -fix nits/flaws. This is important. We will take lack of replies as a sign that -you are not anxious to get your patch accepted and we tend to simply drop such +fix nits/flaws. This is important. We take lack of replies as a sign that you +are not anxious to get your patch accepted and we tend to simply drop such changes. ### About pull requests @@ -157,7 +158,7 @@ git commit that is easy to merge and they are easy to track and not that easy to lose in the flood of many emails, like they sometimes do on the mailing lists. -Every pull request submitted will automatically be tested in several different +Every pull request submitted is automatically tested in several different ways. [See the CI document for more information](https://github.com/curl/curl/blob/master/tests/CI.md). @@ -219,10 +220,10 @@ A short guide to how to write git commit messages in the curl project. has already been closed] [Ref: URL to more information about the commit; use Bug: instead for a reference to a bug on another bug tracker] - [Fixes #1234 - if this closes a GitHub issue; GitHub will actually - close the issue once this commit is merged] - [Closes #1234 - if this closes a GitHub PR; GitHub will actually - close the PR once this commit is merged] + [Fixes #1234 - if this closes a GitHub issue; GitHub closes the issue once + this commit is merged] + [Closes #1234 - if this closes a GitHub PR; GitHub closes the PR once this + commit is merged] ---- stop ---- The first line is a succinct description of the change: @@ -240,18 +241,18 @@ make sure that you have your own user and email setup correctly in git before you commit. Add whichever header lines as appropriate, with one line per person if more -than one person was involved. There is no need to credit yourself unless you are -using --author=... which hides your identity. Do not include people's e-mail -addresses in headers to avoid spam, unless they are already public from a -previous commit; saying `{userid} on github` is OK. +than one person was involved. There is no need to credit yourself unless you +are using --author=... which hides your identity. Do not include people's +email addresses in headers to avoid spam, unless they are already public from +a previous commit; saying `{userid} on github` is OK. ### Write Access to git Repository If you are a frequent contributor, you may be given push access to the git -repository and then you will be able to push your changes straight into the git +repository and then you are able to push your changes straight into the git repo instead of sending changes as pull requests or by mail as patches. -Just ask if this is what you would want. You will be required to have posted +Just ask if this is what you would want. You are required to have posted several high quality patches first, before you can be granted push access. ### How To Make a Patch with git @@ -302,9 +303,9 @@ all kinds of Unixes and Windows. ## Update copyright and license information -There is a CI job called **REUSE compliance / check** that will run on every -pull request and commit to verify that the *REUSE state* of all files are -still fine. +There is a CI job called **REUSE compliance / check** that runs on every pull +request and commit to verify that the *REUSE state* of all files are still +fine. This means that all files need to have their license and copyright information clearly stated. Ideally by having the standard curl source code header, with diff --git a/docs/CURLDOWN.md b/docs/CURLDOWN.md new file mode 100644 index 00000000000..8ee2f3ce4f4 --- /dev/null +++ b/docs/CURLDOWN.md @@ -0,0 +1,153 @@ +# curldown + +A markdown-like syntax for libcurl man pages. + +## Purpose + +A text format for writing libcurl documentation in the shape of man pages. + +Make it easier for users to contribute and write documentation. A format that +is easier on the eye in its source format. + +Make it harder to do syntactical mistakes. + +Use a format that allows creating man pages that end up looking exactly like +the man pages did when we wrote them in nroff format. + +Take advantage of the fact that people these days are accustomed to markdown +by using a markdown-like syntax. + +This allows us to fix issues in the nroff format easier since now we generate +them. For example: escaping minus to prevent them from being turned into +Unicode by man. + +Generate nroff output that looks (next to) *identical* to the previous files, +so that the look, existing test cases, HTML conversions, existing +infrastructure etc remain mostly intact. + +Contains meta-data in a structured way to allow better output (for example the +see also information) and general awareness of what the file is about. + +## File extension + +Since curldown looks similar to markdown, we use `.md` extensions on the +files. + +## Conversion + +Convert **from curldown to nroff** with `cd2nroff`. Generates nroff man pages. + +Convert **from nroff to curldown** with `nroff2cd`. This is only meant to be +used for the initial conversion to curldown and should ideally never be needed +again. + +Convert, check or clean up an existing curldown to nicer, better, cleaner +curldown with **cd2cd**. + +Mass-convert all curldown files to nroff in specified directories with +`cdall`: + + cdall [dir1] [dir2] [dir3] .. + +## Known issues + +The `cd2nroff` tool does not yet handle *italics* or **bold** where the start +and the end markers are used on separate lines. + +The `nroff2cd` tool generates code style quotes for all `.fi` sections since +the nroff format does not carry a distinction. + +# Format + +Each curldown starts with a header with meta-data: + + --- + c: Copyright (C) Daniel Stenberg, , et al. + SPDX-License-Identifier: curl + Title: CURLOPT_AWS_SIGV4 + Section: 3 + Source: libcurl + Protocol: + - HTTP + See-also: + - CURLOPT_HEADEROPT (3) + - CURLOPT_HTTPAUTH (3) + TLS-backend: + - [name] + --- + +All curldown files *must* have all the headers present and at least one +`See-also:` entry specified. + +If the man page is for section 3 (library related). The `Protocol` list must +contain at least one protocol, which can be `*` if the option is virtually for +everything. If `*` is used, it must be the only listed protocol. Recognized +protocols are either URL schemes (in uppercase), `TLS` or `TCP`. + +If the `Protocol` list contains `TLS`, then there must also be a `TLS-backend` +list, specifying `All` or a list of what TLS backends that work with this +option. The available TLS backends are: + +- `BearSSL` +- `GnuTLS` +- `mbedTLS` +- `OpenSSL` (also covers BoringSSL, libressl, quictls, AWS-LC and AmiSSL) +- `rustls` +- `Schannel` +- `Secure Transport` +- `wolfSSL` +- `All`: all TLS backends + +Following the header in the file, is the manual page using markdown-like +syntax: + +~~~ + # NAME + a page - this is a page descriving something + + # SYNOPSIS + ~~~c + #include + + CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); + ~~~ +~~~ + +Quoted source code should start with `~~~c` and end with `~~~` while regular +quotes can start with `~~~` or just be indented with 4 spaces. + +Headers at top-level `#` get converted to `.SH`. + +`nroff2cd` supports the `##` next level header which gets converted to `.IP`. + +Write bold words or phrases within `**` like: + + This is a **bold** word. + +Write italics like: + + This is *italics*. + +Due to how man pages do not support backticks especially formatted, such +occurrences in the source are instead just using italics in the generated +output: + + This `word` appears in italics. + +When generating the nroff output, the tooling removes superfluous newlines, +meaning they can be used freely in the source file to make the text more +readable. + +To make sure curldown documents render correctly as markdown, all literal +occurrences of `<` or `>` need to be escaped by a leading backslash. + +## symbols + +All mentioned curl symbols that have their own man pages, like +`curl_easy_perform(3)` are automatically rendered using italics in the output +without having to enclose it with asterisks. This helps ensuring that they get +converted to links properly later in the HTML version on the website, as +converted with `roffit`. This makes the curldown text easier to read even when +mentioning many curl symbols. + +This auto-linking works for patterns matching `(lib|)curl[^ ]*(3)`. diff --git a/docs/DEPRECATE.md b/docs/DEPRECATE.md index 4cd5a22ce2b..6b6b5b46b8c 100644 --- a/docs/DEPRECATE.md +++ b/docs/DEPRECATE.md @@ -10,12 +10,16 @@ how your use case cannot be satisfied properly using a workaround. This NTLM authentication method is powered by a separate tool, `ntlm_auth`. Barely anyone uses this method. It was always a quirky -implementation (including fork + exec), it has limited portability and we -don't test it in the test suite and CI. +implementation (including fork + exec), it has limited portability and we do +not test it in the test suite and CI. We keep the native NTLM implementation. -curl will remove the support for NTLM_WB auth in June 2024. +Due to a mistake, the `NTLM_WB` functionality is missing in builds since 8.4.0 +(October 2023). It needs to be manually patched to work. See [PR +12479](https://github.com/curl/curl/pull/12479). + +curl removes the support for NTLM_WB auth in April 2024. ## space-separated `NOPROXY` patterns @@ -34,7 +38,7 @@ variable but do not consider a space to be a valid separator. Using spaces for separator is probably less portable and might cause more friction than commas do. Users should use commas for this for greater portability. -curl will remove the support for space-separated names in July 2024. +curl removes the support for space-separated names in July 2024. ## past removals diff --git a/docs/DISTROS.md b/docs/DISTROS.md new file mode 100644 index 00000000000..09e588c4f1d --- /dev/null +++ b/docs/DISTROS.md @@ -0,0 +1,233 @@ +# curl distros + + + +Lots of organizations distribute curl packages to end users. This is a +collection of pointers to where to learn more about curl on and with each +distro. + +We discuss curl distro issues, patches and collaboration on the [curl-distros +mailing list](https://lists.haxx.se/listinfo/curl-distros). + +## AlmaLinux + +- curl package source and patches: curl package source and patches +- curl issues: https://bugs.almalinux.org/view_all_bug_page.php click Category and choose curl +- curl security: https://errata.almalinux.org/ search for curl + +## Alpine Linux + +- curl: https://pkgs.alpinelinux.org/package/edge/main/x86_64/curl +- curl issues: https://gitlab.alpinelinux.org/alpine/aports/-/issues +- curl security: https://security.alpinelinux.org/srcpkg/curl +- curl package source and patches: https://gitlab.alpinelinux.org/alpine/aports/-/tree/master/main/curl + +## Alt Linux + +- curl: http://www.sisyphus.ru/srpm/Sisyphus/curl +- curl patches: http://www.sisyphus.ru/ru/srpm/Sisyphus/curl/patches +- curl issues: http://www.sisyphus.ru/ru/srpm/Sisyphus/curl/bugs + +## Arch Linux + +- curl: https://archlinux.org/packages/core/x86_64/curl/ +- curl issues: https://gitlab.archlinux.org/archlinux/packaging/packages/curl/-/issues +- curl security: https://security.archlinux.org/package/curl +- curl wiki: https://wiki.archlinux.org/title/CURL + +## Buildroot + +- curl package source and patches: https://git.buildroot.net/buildroot/tree/package/libcurl +- curl issues: https://bugs.buildroot.org/buglist.cgi?quicksearch=curl + +## Chimera + +- curl package source and patches: https://github.com/chimera-linux/cports/tree/master/main/curl + +## Clear Linux + +- curl: https://github.com/clearlinux-pkgs/curl +- curl issues: https://github.com/clearlinux/distribution/issues + +## Conary + +- curl: https://github.com/conan-io/conan-center-index/tree/master/recipes/libcurl +- curl issues: https://github.com/conan-io/conan-center-index/issues +- curl patches: https://github.com/conan-io/conan-center-index/tree/master/recipes/libcurl (in `all/patches/*`, if any) + +## conda-forge + +- curl: https://github.com/conda-forge/curl-feedstock +- curl issues: https://github.com/conda-forge/curl-feedstock/issues + +## CRUX + +- curl: https://crux.nu/portdb/?a=search&q=curl +- curl issues: https://git.crux.nu/ports/core/issues/?type=all&state=open&q=curl + +## curl-for-win + +(this is the official curl binaries for Windows shipped by the curl project) + +- curl: https://curl.se/windows/ + +Issues and patches for this are managed in the main curl project. + +## Cygwin + +- curl: https://cygwin.com/cgit/cygwin-packages/curl/tree/curl.cygport +- curl patches: https://cygwin.com/cgit/cygwin-packages/curl/tree + +## Debian + +- curl: https://tracker.debian.org/pkg/curl +- curl issues: https://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=curl +- curl patches: https://udd.debian.org/patches.cgi?src=curl +- curl patches: https://salsa.debian.org/debian/curl (in debian/* branches, inside the folder debian/patches) + +## Fedora + +- curl: https://src.fedoraproject.org/rpms/curl +- curl issues: [bugzilla](https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&classification=Fedora&product=Fedora&product=Fedora%20EPEL&component=curl) +- curl patches: [list of patches in package git](https://src.fedoraproject.org/rpms/curl/tree/rawhide) + +## FreeBSD + +- curl: https://cgit.freebsd.org/ports/tree/ftp/curl +- curl patches: https://cgit.freebsd.org/ports/tree/ftp/curl +- curl issues: https://bugs.freebsd.org/bugzilla/buglist.cgi?bug_status=__open__&order=Importance&product=Ports%20%26%20Packages&query_format=advanced&short_desc=curl&short_desc_type=allwordssubstr + +## Gentoo Linux + +- curl: https://packages.gentoo.org/packages/net-misc/curl +- curl issues: https://bugs.gentoo.org/buglist.cgi?quicksearch=net-misc/curl +- curl package sources and patches: https://gitweb.gentoo.org/repo/gentoo.git/tree/net-misc/curl/ + +## GNU Guix + +- curl: https://git.savannah.gnu.org/gitweb/?p=guix.git;a=blob;f=gnu/packages/curl.scm;hb=HEAD +- curl issues: https://issues.guix.gnu.org/search?query=curl + +## Homebrew + +- curl: https://formulae.brew.sh/formula/curl + +Homebrew's policy is that all patches and issues should be submitted upstream +unless it is very specific to Homebrew's way of packaging software. + +## MacPorts + +- curl: https://github.com/macports/macports-ports/tree/master/net/curl +- curl issues: https://trac.macports.org/query?0_port=curl&0_port_mode=%7E&0_status=%21closed +- curl patches: https://github.com/macports/macports-ports/tree/master/net/curl/files + +## Mageia + +- curl: https://svnweb.mageia.org/packages/cauldron/curl/current/SPECS/curl.spec?view=markup +- curl issues: https://bugs.mageia.org/buglist.cgi?bug_status=NEW&bug_status=UNCONFIRMED&bug_status=NEEDINFO&bug_status=UPSTREAM&bug_status=ASSIGNED&component=RPM%20Packages&f1=cf_rpmpkg&list_id=176576&o1=casesubstring&product=Mageia&query_format=advanced&v1=curl +- curl patches: https://svnweb.mageia.org/packages/cauldron/curl/current/SOURCES/ +- curl patches in stable distro releases: https://svnweb.mageia.org/packages/updates//curl/current/SOURCES/ +- curl security: https://advisories.mageia.org/src_curl.html + +## MSYS2 + +- curl: https://github.com/msys2/MINGW-packages/tree/master/mingw-w64-curl +- curl issues: https://github.com/msys2/MINGW-packages/issues +- curl patches: https://github.com/msys2/MINGW-packages/tree/master/mingw-w64-curl (`*.patch`) + +## Muldersoft + +- curl: https://github.com/lordmulder/cURL-build-win32 +- curl issues: https://github.com/lordmulder/cURL-build-win32/issues +- curl patches: https://github.com/lordmulder/cURL-build-win32/tree/master/patch + +## NixOS + +- curl: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/networking/curl/default.nix +- curl issues: https://github.com/NixOS/nixpkgs + +nixpkgs is the package repository used by the NixOS Linux distribution, but +can also be used on other distributions + +## OmniOS + +- curl: https://github.com/omniosorg/omnios-build/tree/master/build/curl +- curl issues: https://github.com/omniosorg/omnios-build/issues +- curl patches: https://github.com/omniosorg/omnios-build/tree/master/build/curl/patches + +## OpenIndiana + +- curl: https://github.com/OpenIndiana/oi-userland/tree/oi/hipster/components/web/curl +- curl issues: https://www.illumos.org/projects/openindiana/issues +- curl patches: https://github.com/OpenIndiana/oi-userland/tree/oi/hipster/components/web/curl/patches + +## OpenSUSE + +- curl source and patches: https://build.opensuse.org/package/show/openSUSE%3AFactory/curl + +## Oracle Solaris + +- curl: https://github.com/oracle/solaris-userland/tree/master/components/curl +- curl issues: https://support.oracle.com/ (requires support contract) +- curl patches: https://github.com/oracle/solaris-userland/tree/master/components/curl/patches + +## OpenEmbedded / Yocto Project + +- curl: https://layers.openembedded.org/layerindex/recipe/5765/ +- curl issues: https://bugzilla.yoctoproject.org/ +- curl patches: https://git.openembedded.org/openembedded-core/tree/meta/recipes-support/curl + +## PLD Linux + +- curl package source and patches: https://github.com/pld-linux/curl +- curl issues: https://bugs.launchpad.net/pld-linux?field.searchtext=curl&search=Search&field.status%3Alist=NEW&field.status%3Alist=INCOMPLETE_WITH_RESPONSE&field.status%3Alist=INCOMPLETE_WITHOUT_RESPONSE&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&field.status%3Alist=INPROGRESS&field.status%3Alist=FIXCOMMITTED&field.assignee=&field.bug_reporter=&field.omit_dupes=on&field.has_patch=&field.has_no_package= + +## pkgsrc + +- curl: https://github.com/NetBSD/pkgsrc/tree/trunk/www/curl +- curl issues: https://github.com/NetBSD/pkgsrc/issues +- curl patches: https://github.com/NetBSD/pkgsrc/tree/trunk/www/curl/patches + +## Red Hat Enterprise Linux / CentOS Stream + +- curl: https://kojihub.stream.centos.org/koji/packageinfo?packageID=217 +- curl issues: https://issues.redhat.com/secure/CreateIssueDetails!init.jspa?pid=12332745&issuetype=1&components=12377466&priority=10300 +- curl patches: https://gitlab.com/redhat/centos-stream/rpms/curl + +## Rocky Linux + +- curl: https://git.rockylinux.org/staging/rpms/curl/-/blob/r9/SPECS/curl.spec +- curl issues: https://bugs.rockylinux.org +- curl patches: https://git.rockylinux.org/staging/rpms/curl/-/tree/r9/SOURCES + +## SerenityOS + +- curl: https://github.com/SerenityOS/serenity/tree/master/Ports/curl +- curl issues: https://github.com/SerenityOS/serenity/issues?q=label%3Aports +- curl patches: https://github.com/SerenityOS/serenity/tree/master/Ports/curl/patches + +## SmartOS + +- curl: https://github.com/TritonDataCenter/illumos-extra/tree/master/curl +- curl issues: https://github.com/TritonDataCenter/illumos-extra/issues +- curl patches: https://github.com/TritonDataCenter/illumos-extra/tree/master/curl/Patches + +## SPACK + +- curl package source and patches: https://github.com/spack/spack/tree/develop/var/spack/repos/builtin/packages/curl + +## vcpkg + +- curl: https://github.com/microsoft/vcpkg/tree/master/ports/curl +- curl issues: https://github.com/microsoft/vcpkg/issues +- curl patches: https://github.com/microsoft/vcpkg/tree/master/ports/curl (`*.patch`) + +## Void Linux + +- curl: https://github.com/void-linux/void-packages/tree/master/srcpkgs/curl +- curl issues: https://github.com/void-linux/void-packages/issues +- curl patches: https://github.com/void-linux/void-packages/tree/master/srcpkgs/curl/patches + +## Wolfi + +- curl: https://github.com/wolfi-dev/os/blob/main/curl.yaml diff --git a/docs/DYNBUF.md b/docs/DYNBUF.md index c3a4b766795..3f63ec7e47f 100644 --- a/docs/DYNBUF.md +++ b/docs/DYNBUF.md @@ -3,7 +3,7 @@ This is the internal module for creating and handling "dynamic buffers". This means buffers that can be appended to, dynamically and grow to adapt. -There will always be a terminating zero put at the end of the dynamic buffer. +There is always a terminating zero put at the end of the dynamic buffer. The `struct dynbuf` is used to hold data for each instance of a dynamic buffer. The members of that struct **MUST NOT** be accessed or modified @@ -17,8 +17,8 @@ void Curl_dyn_init(struct dynbuf *s, size_t toobig); This initializes a struct to use for dynbuf and it cannot fail. The `toobig` value **must** be set to the maximum size we allow this buffer instance to -grow to. The functions below will return `CURLE_OUT_OF_MEMORY` when hitting -this limit. +grow to. The functions below return `CURLE_OUT_OF_MEMORY` when hitting this +limit. ## `Curl_dyn_free` diff --git a/docs/EARLY-RELEASE.md b/docs/EARLY-RELEASE.md index 6d5a5e25b4c..3e9a679ac30 100644 --- a/docs/EARLY-RELEASE.md +++ b/docs/EARLY-RELEASE.md @@ -28,7 +28,7 @@ big and we never release just a patch. There is only "release". - Is there a security advisory rated high or critical? - Is there a data corruption bug? - Did the bug cause an API/ABI breakage? - - Will the problem annoy a significant share of the user population? + - Does the problem annoy a significant share of the user population? If the answer is yes to one or more of the above, an early release might be warranted. diff --git a/docs/EXPERIMENTAL.md b/docs/EXPERIMENTAL.md index de694013d1a..ee26ac11063 100644 --- a/docs/EXPERIMENTAL.md +++ b/docs/EXPERIMENTAL.md @@ -8,8 +8,8 @@ Experimental support in curl means: 1. Experimental features are provided to allow users to try them out and provide feedback on functionality and API etc before they ship and get "carved in stone". -2. You must enable the feature when invoking configure as otherwise curl will - not be built with the feature present. +2. You must enable the feature when invoking configure as otherwise curl is + not built with the feature present. 3. We strongly advise against using this feature in production. 4. **We reserve the right to change behavior** of the feature without sticking to our API/ABI rules as we do for regular features, as long as it is marked diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 05364aaf345..bae38fb851e 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -16,7 +16,7 @@ - custom maximum download time - custom least download speed acceptable - custom output result after completion - - guesses protocol from host name unless specified + - guesses protocol from hostname unless specified - uses .netrc - progress bar with time statistics while downloading - "standard" proxy environment variables support @@ -26,7 +26,7 @@ - happy eyeballs dual-stack connects - persistent connections - SOCKS 4 + 5 support, with or without local name resolving - - supports user name and password in proxy environment variables + - supports username and password in proxy environment variables - operations through HTTP proxy "tunnel" (using CONNECT) - replaceable memory functions (malloc, free, realloc, etc) - asynchronous name resolving (6) @@ -82,8 +82,8 @@ - active/passive using PORT, EPRT, PASV or EPSV - single file size information (compare to HTTP HEAD) - 'type=' URL support - - dir listing - - dir listing names-only + - directory listing + - directory listing names-only - upload - upload append - upload via http-proxy as HTTP PUT @@ -94,7 +94,7 @@ - via HTTP proxy, HTTPS proxy or SOCKS proxy - all operations can be tunneled through proxy - customizable to retrieve file modification date - - no dir depth limit + - no directory depth limit ## FTPS (1) diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index dd09de45636..09723c4d0bb 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -10,9 +10,8 @@ BDFL (Benevolent Dictator For Life) style project. This setup has been used due to convenience and the fact that it has worked fine this far. It is not because someone thinks of it as a superior project -leadership model. It will also only continue working as long as Daniel manages -to listen in to what the project and the general user population wants and -expects from us. +leadership model. It also only works as long as Daniel manages to listen in to +what the project and the general user population wants and expects from us. ## Legal entity @@ -29,13 +28,13 @@ that wrote those parts of the code. The curl project is not a democracy, but everyone is entitled to state their opinion and may argue for their sake within the community. -All and any changes that have been done or will be done are eligible to bring -up for discussion, to object to or to praise. Ideally, we find consensus for -the appropriate way forward in any given situation or challenge. +All and any changes that have been done or are done are eligible to bring up +for discussion, to object to or to praise. Ideally, we find consensus for the +appropriate way forward in any given situation or challenge. If there is no obvious consensus, a maintainer who's knowledgeable in the -specific area will take an "executive" decision that they think is the right -for the project. +specific area takes an "executive" decision that they think is the right for +the project. ## Donations @@ -81,17 +80,17 @@ curl source code repository. Committers are recorded as `Author` in git. A maintainer in the curl project is an individual who has been given permissions to push commits to one of the git repositories. -Maintainers are free to push commits to the repositories at their own will. +Maintainers are free to push commits to the repositories at they see fit. Maintainers are however expected to listen to feedback from users and any change that is non-trivial in size or nature *should* be brought to the project as a Pull-Request (PR) to allow others to comment/object before merge. ## Former maintainers -A maintainer who stops being active in the project will at some point get -their push permissions removed. We do this for security reasons but also to -make sure that we always have the list of maintainers as "the team that push -stuff to curl". +A maintainer who stops being active in the project gets their push permissions +removed at some point. We do this for security reasons but also to make sure +that we always have the list of maintainers as "the team that push stuff to +curl". Getting push permissions removed is not a punishment. Everyone who ever worked on maintaining curl is considered a hero, for all time hereafter. @@ -100,7 +99,7 @@ on maintaining curl is considered a hero, for all time hereafter. We have a security team. That is the team of people who are subscribed to the curl-security mailing list; the receivers of security reports from users and -developers. This list of people will vary over time but should be skilled +developers. This list of people varies over time but they are all skilled developers familiar with the curl project. The security team works best when it consists of a small set of active @@ -108,6 +107,22 @@ persons. We invite new members when the team seems to need it, and we also expect to retire security team members as they "drift off" from the project or just find themselves unable to perform their duties there. +## Core team + +There is a curl core team. It currently has the same set of members as the +security team. It can also be reached on the security email address. + +The core team nominates and invites new members to the team when it sees fit. +There is no open member voting or formal ways to be a candidate. Active +participants in the curl project who want to join the core team can ask to +join. + +The core team is a board of advisors. It deals with project management +subjects that need confidentiality or for other reasons cannot be dealt with +and discussed in the open (for example reports of code of conduct violations). +Project matters should always as far as possible be discussed on open mailing +lists. + ## Server admins We run a web server, a mailing list and more on the curl project's primary @@ -172,11 +187,10 @@ different individuals and over time. If you think you can help making the project better by shouldering some maintaining responsibilities, then please get in touch. -You will be expected to be familiar with the curl project and its ways of -working. You need to have gotten a few quality patches merged as a proof of -this. +You are expected to be familiar with the curl project and its ways of working. +You need to have gotten a few quality patches merged as a proof of this. ### Stop being a maintainer If you (appear to) not be active in the project anymore, you may be removed as -a maintainer. Thank you for your service! +a maintainer. Thank you for your service. diff --git a/docs/HELP-US.md b/docs/HELP-US.md index 90c9724b21d..15996d0462c 100644 --- a/docs/HELP-US.md +++ b/docs/HELP-US.md @@ -40,8 +40,8 @@ In the issue tracker we occasionally mark bugs with [help wanted](https://github.com/curl/curl/labels/help%20wanted), as a sign that the bug is acknowledged to exist and that there is nobody known to work on this issue for the moment. Those are bugs that are fine to "grab" and provide a -pull request for. The complexity level of these will of course vary, so pick -one that piques your interest. +pull request for. The complexity level of these of course varies, so pick one +that piques your interest. ## Work on known bugs @@ -77,13 +77,12 @@ brainstorming on specific ways to do the implementation etc. You can also come up with a completely new thing you think we should do. Or not do. Or fix. Or add to the project. You then either bring it to the mailing -list first to see if people will shoot down the idea at once, or you bring a -first draft of the idea as a pull request and take the discussion there around -the specific implementation. Either way is fine. +list first to see if people shoot down the idea at once, or you bring a first +draft of the idea as a pull request and take the discussion there around the +specific implementation. Either way is fine. ## CONTRIBUTE -We offer [guidelines](https://curl.se/dev/contribute.html) that are -suitable to be familiar with before you decide to contribute to curl. If -you are used to open source development, you will probably not find many -surprises there. +We offer [guidelines](https://curl.se/dev/contribute.html) that are suitable +to be familiar with before you decide to contribute to curl. If you are used +to open source development, you probably do not find many surprises there. diff --git a/docs/HISTORY.md b/docs/HISTORY.md index f39c45ea124..d28217ca6f8 100644 --- a/docs/HISTORY.md +++ b/docs/HISTORY.md @@ -327,7 +327,7 @@ April: added the cyassl backend (later renamed to WolfSSL) January: the curl tool defaults to HTTP/2 for HTTPS URLs - December: curl 7.52.0 introduced support for HTTPS-proxy! + December: curl 7.52.0 introduced support for HTTPS-proxy First TLS 1.3 support diff --git a/docs/HSTS.md b/docs/HSTS.md index e541024936e..c1f433b2814 100644 --- a/docs/HSTS.md +++ b/docs/HSTS.md @@ -10,19 +10,19 @@ HTTP Strict-Transport-Security. Added as experimental in curl ## Behavior libcurl features an in-memory cache for HSTS hosts, so that subsequent -HTTP-only requests to a host name present in the cache will get internally +HTTP-only requests to a hostname present in the cache gets internally "redirected" to the HTTPS version. ## `curl_easy_setopt()` options: - `CURLOPT_HSTS_CTRL` - enable HSTS for this easy handle - - `CURLOPT_HSTS` - specify file name where to store the HSTS cache on close + - `CURLOPT_HSTS` - specify filename where to store the HSTS cache on close (and possibly read from at startup) ## curl command line options - `--hsts [filename]` - enable HSTS, use the file as HSTS cache. If filename - is `""` (no length) then no file will be used, only in-memory cache. + is `""` (no length) then no file is used, only in-memory cache. ## HSTS cache file format @@ -38,5 +38,5 @@ The time stamp is when the entry expires. ## Possible future additions - - `CURLOPT_HSTS_PRELOAD` - provide a set of HSTS host names to load first + - `CURLOPT_HSTS_PRELOAD` - provide a set of HSTS hostnames to load first - ability to save to something else than a file diff --git a/docs/HTTP-COOKIES.md b/docs/HTTP-COOKIES.md index d6fd87d2051..174c4f536d1 100644 --- a/docs/HTTP-COOKIES.md +++ b/docs/HTTP-COOKIES.md @@ -9,7 +9,7 @@ Cookies are either "session cookies" which typically are forgotten when the session is over which is often translated to equal when browser quits, or the cookies are not session cookies they have expiration dates after which - the client will throw them away. + the client throws them away. Cookies are set to the client with the Set-Cookie: header and are sent to servers with the Cookie: header. @@ -30,9 +30,28 @@ implemented by curl. curl considers `http://localhost` to be a *secure context*, meaning that it - will allow and use cookies marked with the `secure` keyword even when done - over plain HTTP for this host. curl does this to match how popular browsers - work with secure cookies. + allows and uses cookies marked with the `secure` keyword even when done over + plain HTTP for this host. curl does this to match how popular browsers work + with secure cookies. + +## Super cookies + + A single cookie can be set for a domain that matches multiple hosts. Like if + set for `example.com` it gets sent to both `aa.example.com` as well as + `bb.example.com`. + + A challenge with this concept is that there are certain domains for which + cookies should not be allowed at all, because they are *Public + Suffixes*. Similarly, a client never accepts cookies set directly for the + top-level domain like for example `.com`. Cookies set for *too broad* + domains are generally referred to as *super cookies*. + + If curl is built with PSL (**Public Suffix List**) support, it detects and + discards cookies that are specified for such suffix domains that should not + be allowed to have cookies. + + if curl is *not* built with PSL support, it has no ability to stop super + cookies. ## Cookies saved to disk @@ -46,8 +65,7 @@ TAB. That file is called the cookie jar in curl terminology. When libcurl saves a cookie jar, it creates a file header of its own in - which there is a URL mention that will link to the web version of this - document. + which there is a URL mention that links to the web version of this document. ## Cookie file format @@ -82,13 +100,13 @@ `-b, --cookie` tell curl a file to read cookies from and start the cookie engine, or if it - is not a file it will pass on the given string. `-b name=var` works and so - does `-b cookiefile`. + is not a file it passes on the given string. `-b name=var` works and so does + `-b cookiefile`. `-j, --junk-session-cookies` - when used in combination with -b, it will skip all "session cookies" on load - so as to appear to start a new cookie session. + when used in combination with -b, it skips all "session cookies" on load so + as to appear to start a new cookie session. `-c, --cookie-jar` @@ -140,7 +158,7 @@ can also set and access cookies. Since curl and libcurl are plain HTTP clients without any knowledge of or - capability to handle JavaScript, such cookies will not be detected or used. + capability to handle JavaScript, such cookies are not detected or used. Often, if you want to mimic what a browser does on such websites, you can record web browser HTTP traffic when using such a site and then repeat the diff --git a/docs/HTTP2.md b/docs/HTTP2.md index 5b4028349cf..1d6575b54f0 100644 --- a/docs/HTTP2.md +++ b/docs/HTTP2.md @@ -23,20 +23,20 @@ We require at least version 1.12.0. Over an http:// URL ------------------- -If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will -include an upgrade header in the initial request to the host to allow -upgrading to HTTP/2. +If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl includes +an upgrade header in the initial request to the host to allow upgrading to +HTTP/2. -Possibly we can later introduce an option that will cause libcurl to fail if +Possibly we can later introduce an option that causes libcurl to fail if it is not possible to upgrade. Possibly we introduce an option that makes libcurl use HTTP/2 at once over http:// Over an https:// URL -------------------- -If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will use -ALPN to negotiate which protocol to continue with. Possibly introduce an -option that will cause libcurl to fail if not possible to use HTTP/2. +If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl uses ALPN +to negotiate which protocol to continue with. Possibly introduce an option +that causes libcurl to fail if not possible to use HTTP/2. `CURL_HTTP_VERSION_2TLS` was added in 7.47.0 as a way to ask libcurl to prefer HTTP/2 for HTTPS but stick to 1.1 by default for plain old HTTP connections. @@ -54,15 +54,15 @@ term for doing multiple independent transfers over the same physical TCP connection. To take advantage of multiplexing, you need to use the multi interface and set -`CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl will -attempt to reuse existing HTTP/2 connections and just add a new stream over +`CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl +attempts to reuse existing HTTP/2 connections and just add a new stream over that when doing subsequent parallel requests. While libcurl sets up a connection to an HTTP server there is a period during which it does not know if it can pipeline or do multiplexing and if you add -new transfers in that period, libcurl will default to start new connections -for those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), -you can ask that a transfer should rather wait and see in case there is a +new transfers in that period, libcurl defaults to starting new connections for +those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you +can ask that a transfer should rather wait and see in case there is a connection for the same host in progress that might end up being possible to multiplex on. It favors keeping the number of connections low to the cost of slightly longer time to first byte transferred. diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 7f2f08ada37..783ab101ffb 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -15,6 +15,8 @@ QUIC libraries we are using: [quiche](https://github.com/cloudflare/quiche) - **EXPERIMENTAL** +[OpenSSL 3.2+ QUIC](https://github.com/openssl/openssl) - **EXPERIMENTAL** + [msh3](https://github.com/nibanks/msh3) (with [msquic](https://github.com/microsoft/msquic)) - **EXPERIMENTAL** ## Experimental @@ -23,19 +25,19 @@ HTTP/3 support in curl is considered **EXPERIMENTAL** until further notice when built to use *quiche* or *msh3*. Only the *ngtcp2* backend is not experimental. -Further development and tweaking of the HTTP/3 support in curl will happen in -the master branch using pull-requests, just like ordinary changes. +Further development and tweaking of the HTTP/3 support in curl happens in the +master branch using pull-requests, just like ordinary changes. To fix before we remove the experimental label: - the used QUIC library needs to consider itself non-beta - - it's fine to "leave" individual backends as experimental if necessary + - it is fine to "leave" individual backends as experimental if necessary # ngtcp2 version Building curl with ngtcp2 involves 3 components: `ngtcp2` itself, `nghttp3` and a QUIC supporting TLS library. The supported TLS libraries are covered below. - * `ngtcp2`: v1.1.0 + * `ngtcp2`: v1.2.0 * `nghttp3`: v1.1.0 ## Build with quictls @@ -56,6 +58,7 @@ Build nghttp3 % cd .. % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 % cd nghttp3 + % git submodule update --init % autoreconf -fi % ./configure --prefix= --enable-lib-only % make @@ -64,7 +67,7 @@ Build nghttp3 Build ngtcp2 % cd .. - % git clone -b v1.1.0 https://github.com/ngtcp2/ngtcp2 + % git clone -b v1.2.0 https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi % ./configure PKG_CONFIG_PATH=/lib/pkgconfig:/lib/pkgconfig LDFLAGS="-Wl,-rpath,/lib" --prefix= --enable-lib-only @@ -99,6 +102,7 @@ Build nghttp3 % cd .. % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 % cd nghttp3 + % git submodule update --init % autoreconf -fi % ./configure --prefix= --enable-lib-only % make @@ -107,7 +111,7 @@ Build nghttp3 Build ngtcp2 % cd .. - % git clone -b v1.1.0 https://github.com/ngtcp2/ngtcp2 + % git clone -b v1.2.0 https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi % ./configure PKG_CONFIG_PATH=/lib/pkgconfig:/lib/pkgconfig LDFLAGS="-Wl,-rpath,/lib" --prefix= --enable-lib-only --with-gnutls @@ -140,6 +144,7 @@ Build nghttp3 % cd .. % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 % cd nghttp3 + % git submodule update --init % autoreconf -fi % ./configure --prefix= --enable-lib-only % make @@ -148,7 +153,7 @@ Build nghttp3 Build ngtcp2 % cd .. - % git clone -b v1.1.0 https://github.com/ngtcp2/ngtcp2 + % git clone -b v1.2.0 https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi % ./configure PKG_CONFIG_PATH=/lib/pkgconfig:/lib/pkgconfig LDFLAGS="-Wl,-rpath,/lib" --prefix= --enable-lib-only --with-wolfssl @@ -175,7 +180,7 @@ Since the quiche build manages its dependencies, curl can be built against the l Build quiche and BoringSSL: - % git clone --recursive https://github.com/cloudflare/quiche + % git clone --recursive -b 0.20.0 https://github.com/cloudflare/quiche % cd quiche % cargo build --package quiche --release --features ffi,pkg-config-meta,qlog % mkdir quiche/deps/boringssl/src/lib @@ -191,7 +196,54 @@ Build curl: % make % make install - If `make install` results in `Permission denied` error, you will need to prepend it with `sudo`. + If `make install` results in `Permission denied` error, you need to prepend + it with `sudo`. + +# OpenSSL version + +QUIC support is **EXPERIMENTAL** + +Build OpenSSL 3.2.0 + + % cd .. + % git clone -b openssl-3.2.0 https://github.com/openssl/openssl + % cd openssl + % ./config enable-tls1_3 --prefix= --libdir=/lib + % make + % make install + +Build nghttp3 + + % cd .. + % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 + % cd nghttp3 + % git submodule update --init + % autoreconf -fi + % ./configure --prefix= --enable-lib-only + % make + % make install + +Build curl: + + % cd .. + % git clone https://github.com/curl/curl + % cd curl + % autoreconf -fi + % LDFLAGS="-Wl,-rpath,/lib" ./configure --with-openssl= --with-openssl-quic --with-nghttp3= + % make + % make install + +You can build curl with cmake: + + % cd .. + % git clone https://github.com/curl/curl + % cd curl + % cmake . -B build -DCURL_USE_OPENSSL=ON -DUSE_OPENSSL_QUIC=ON + % cmake --build build + % cmake --install build + + If `make install` results in `Permission denied` error, you need to prepend + it with `sudo`. # msh3 (msquic) version @@ -232,11 +284,10 @@ Build msh3: % cmake --build . --config Release % cmake --install . --config Release -**Note** - On Windows, Schannel will be used for TLS support by default. If -you with to use (the quictls fork of) OpenSSL, specify the -`-DQUIC_TLS=openssl` option to the generate command above. Also note that -OpenSSL brings with it an additional set of build dependencies not specified -here. +**Note** - On Windows, Schannel is used for TLS support by default. If you +with to use (the quictls fork of) OpenSSL, specify the `-DQUIC_TLS=openssl` +option to the generate command above. Also note that OpenSSL brings with it an +additional set of build dependencies not specified here. Build curl (in [Visual Studio Command prompt](../winbuild/README.md#open-a-command-prompt)): @@ -273,10 +324,10 @@ See this [list of public HTTP/3 servers](https://bagder.github.io/HTTP3-test/) ### HTTPS eyeballing -With option `--http3` curl will attempt earlier HTTP versions as well should -the connect attempt via HTTP/3 not succeed "fast enough". This strategy is -similar to IPv4/6 happy eyeballing where the alternate address family is used -in parallel after a short delay. +With option `--http3` curl attempts earlier HTTP versions as well should the +connect attempt via HTTP/3 not succeed "fast enough". This strategy is similar +to IPv4/6 happy eyeballing where the alternate address family is used in +parallel after a short delay. The IPv4/6 eyeballing has a default of 200ms and you may override that via `--happy-eyeballs-timeout-ms value`. Since HTTP/3 is still relatively new, we @@ -295,8 +346,8 @@ So, without you specifying anything, the hard timeout is 200ms and the soft is 1 in less than 100ms. * When QUIC is not supported (or UDP does not work for this network path), no reply is seen and the HTTP/2 TLS+TCP connection starts 100ms later. - * In the worst case, UDP replies start before 100ms, but drag on. This will - start the TLS+TCP connection after 200ms. + * In the worst case, UDP replies start before 100ms, but drag on. This starts + the TLS+TCP connection after 200ms. * When the QUIC handshake fails, the TLS+TCP connection is attempted right away. For example, when the QUIC server presents the wrong certificate. @@ -304,10 +355,10 @@ The whole transfer only fails, when **both** QUIC and TLS+TCP fail to handshake or time out. Note that all this happens in addition to IP version happy eyeballing. If the -name resolution for the server gives more than one IP address, curl will try -all those until one succeeds - just as with all other protocols. And if those -IP addresses contain both IPv6 and IPv4, those attempts will happen, delayed, -in parallel (the actual eyeballing). +name resolution for the server gives more than one IP address, curl tries all +those until one succeeds - just as with all other protocols. If those IP +addresses contain both IPv6 and IPv4, those attempts happen, delayed, in +parallel (the actual eyeballing). ## Known Bugs diff --git a/docs/HYPER.md b/docs/HYPER.md index 9932c1bbf73..1e47c423728 100644 --- a/docs/HYPER.md +++ b/docs/HYPER.md @@ -8,9 +8,8 @@ library as a backend to deal with HTTP. Hyper support in curl is considered **EXPERIMENTAL** until further notice. It needs to be explicitly enabled at build-time. -Further development and tweaking of the Hyper backend support in curl will -happen in the master branch using pull-requests, just like ordinary -changes. +Further development and tweaking of the Hyper backend support in curl happens +in the master branch using pull-requests, just like ordinary changes. ## Hyper version diff --git a/docs/INSTALL-CMAKE.md b/docs/INSTALL-CMAKE.md new file mode 100644 index 00000000000..a606fcb21c2 --- /dev/null +++ b/docs/INSTALL-CMAKE.md @@ -0,0 +1,133 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + + How To Compile with CMake + +# Building with CMake + +This document describes how to configure, build and install curl and libcurl +from source code using the CMake build tool. To build with CMake, you of +course first have to install CMake. The minimum required version of CMake is +specified in the file `CMakeLists.txt` found in the top of the curl source +tree. Once the correct version of CMake is installed you can follow the +instructions below for the platform you are building on. + +CMake builds can be configured either from the command line, or from one of +CMake's GUIs. + +# Current flaws in the curl CMake build + +Missing features in the CMake build: + + - Builds libcurl without large file support + - Does not support all SSL libraries (only OpenSSL, Schannel, Secure + Transport, and mbedTLS, WolfSSL) + - Does not allow different resolver backends (no c-ares build support) + - No RTMP support built + - Does not allow build curl and libcurl debug enabled + - Does not allow a custom CA bundle path + - Does not allow you to disable specific protocols from the build + - Does not find or use krb4 or GSS + - Rebuilds test files too eagerly, but still cannot run the tests + - Does not detect the correct `strerror_r` flavor when cross-compiling + (issue #1123) + +# Configuring + +A CMake configuration of curl is similar to the autotools build of curl. +It consists of the following steps after you have unpacked the source. + +## Using `cmake` + +You can configure for in source tree builds or for a build tree +that is apart from the source tree. + + - Build in the source tree. + + $ cmake -B . + + - Build in a separate directory (parallel to the curl source tree in this + example). The build directory is created for you. + + $ cmake -B ../curl-build + +### Fallback for CMake before version 3.13 + +CMake before version 3.13 does not support the `-B` option. In that case, +you must create the build directory yourself, `cd` to it and run `cmake` +from there: + + $ mkdir ../curl-build + $ cd ../curl-build + $ cmake ../curl + +If you want to build in the source tree, it is enough to do this: + + $ cmake . + +## Using `ccmake` + +CMake comes with a curses based interface called `ccmake`. To run `ccmake` +on a curl use the instructions for the command line cmake, but substitute +`ccmake` for `cmake`. + +This brings up a curses interface with instructions on the bottom of the +screen. You can press the "c" key to configure the project, and the "g" key to +generate the project. After the project is generated, you can run make. + +## Using `cmake-gui` + +CMake also comes with a Qt based GUI called `cmake-gui`. To configure with +`cmake-gui`, you run `cmake-gui` and follow these steps: + + 1. Fill in the "Where is the source code" combo box with the path to + the curl source tree. + 2. Fill in the "Where to build the binaries" combo box with the path to + the directory for your build tree, ideally this should not be the same + as the source tree, but a parallel directory called curl-build or + something similar. + 3. Once the source and binary directories are specified, press the + "Configure" button. + 4. Select the native build tool that you want to use. + 5. At this point you can change any of the options presented in the GUI. + Once you have selected all the options you want, click the "Generate" + button. + +# Building + +Build (you have to specify the build directory). + + $ cmake --build ../curl-build + +### Fallback for CMake before version 3.13 + +CMake before version 3.13 does not support the `--build` option. In that +case, you have to `cd` to the build directory and use the building tool that +corresponds to the build files that CMake generated for you. This example +assumes that CMake generates `Makefile`: + + $ cd ../curl-build + $ make + +# Testing + +(The test suite does not yet work with the cmake build) + +# Installing + +Install to default location (you have to specify the build directory). + + $ cmake --install ../curl-build + +### Fallback for CMake before version 3.15 + +CMake before version 3.15 does not support the `--install` option. In that +case, you have to `cd` to the build directory and use the building tool that +corresponds to the build files that CMake generated for you. This example +assumes that CMake generates `Makefile`: + + $ cd ../curl-build + $ make install diff --git a/docs/INSTALL.cmake b/docs/INSTALL.cmake deleted file mode 100644 index 4e7f706a96e..00000000000 --- a/docs/INSTALL.cmake +++ /dev/null @@ -1,89 +0,0 @@ - _ _ ____ _ - ___| | | | _ \| | - / __| | | | |_) | | - | (__| |_| | _ <| |___ - \___|\___/|_| \_\_____| - - How To Compile with CMake - -Building with CMake -========================== - This document describes how to compile, build and install curl and libcurl - from source code using the CMake build tool. To build with CMake, you will - of course have to first install CMake. The minimum required version of - CMake is specified in the file CMakeLists.txt found in the top of the curl - source tree. Once the correct version of CMake is installed you can follow - the instructions below for the platform you are building on. - - CMake builds can be configured either from the command line, or from one - of CMake's GUI's. - -Current flaws in the curl CMake build -===================================== - - Missing features in the cmake build: - - - Builds libcurl without large file support - - Does not support all SSL libraries (only OpenSSL, Schannel, - Secure Transport, and mbedTLS, WolfSSL) - - Does not allow different resolver backends (no c-ares build support) - - No RTMP support built - - Does not allow build curl and libcurl debug enabled - - Does not allow a custom CA bundle path - - Does not allow you to disable specific protocols from the build - - Does not find or use krb4 or GSS - - Rebuilds test files too eagerly, but still cannot run the tests - - Does not detect the correct strerror_r flavor when cross-compiling (issue #1123) - - -Command Line CMake -================== - A CMake build of curl is similar to the autotools build of curl. It - consists of the following steps after you have unpacked the source. - - 1. Create an out of source build tree parallel to the curl source - tree and change into that directory - - $ mkdir curl-build - $ cd curl-build - - 2. Run CMake from the build tree, giving it the path to the top of - the curl source tree. CMake will pick a compiler for you. If you - want to specify the compile, you can set the CC environment - variable prior to running CMake. - - $ cmake ../curl - $ make - - 3. Install to default location: - - $ make install - - (The test suite does not work with the cmake build) - -ccmake -========= - CMake comes with a curses based interface called ccmake. To run ccmake on - a curl use the instructions for the command line cmake, but substitute - ccmake ../curl for cmake ../curl. This will bring up a curses interface - with instructions on the bottom of the screen. You can press the "c" key - to configure the project, and the "g" key to generate the project. After - the project is generated, you can run make. - -cmake-gui -========= - CMake also comes with a Qt based GUI called cmake-gui. To configure with - cmake-gui, you run cmake-gui and follow these steps: - 1. Fill in the "Where is the source code" combo box with the path to - the curl source tree. - 2. Fill in the "Where to build the binaries" combo box with the path - to the directory for your build tree, ideally this should not be the - same as the source tree, but a parallel directory called curl-build or - something similar. - 3. Once the source and binary directories are specified, press the - "Configure" button. - 4. Select the native build tool that you want to use. - 5. At this point you can change any of the options presented in the - GUI. Once you have selected all the options you want, click the - "Generate" button. - 6. Run the native build tool that you used CMake to generate. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index a6780b45ddc..7971b1abaaf 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -24,8 +24,8 @@ or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. ## Building from git If you get your code off a git repository instead of a release tarball, see -the `GIT-INFO` file in the root directory for specific instructions on how to -proceed. +the `GIT-INFO.md` file in the root directory for specific instructions on how +to proceed. # Unix @@ -110,10 +110,10 @@ Figuring out all the dependency libraries for a given library is hard, as it might involve figuring out the dependencies of the dependencies and they vary between platforms and change between versions. -When using static dependencies, the build scripts will mostly assume that you, -the user, will provide all the necessary additional dependency libraries as -additional arguments in the build. With configure, by setting `LIBS` or -`LDFLAGS` on the command line. +When using static dependencies, the build scripts mostly assume that you, the +user, provide all the necessary additional dependency libraries as additional +arguments in the build. With configure, by setting `LIBS` or `LDFLAGS` on the +command line. Building statically is not for the faint of heart. @@ -123,8 +123,8 @@ If you are a curl developer and use gcc, you might want to enable more debug options with the `--enable-debug` option. curl can be built to use a whole range of libraries to provide various useful -services, and configure will try to auto-detect a decent default. But if you -want to alter it, you can select how to deal with each individual library. +services, and configure tries to auto-detect a decent default. If you want to +alter it, you can select how to deal with each individual library. ## Select TLS backend @@ -146,7 +146,7 @@ you cannot add another OpenSSL fork (or wolfSSL) simply because they have conflicting identical symbol names. When you build with multiple TLS backends, you can select the active one at -run-time when curl starts up. +runtime when curl starts up. ## configure finding libs in wrong directory @@ -174,8 +174,8 @@ Building for Windows XP is required as a minimum. KB140584 is a must for any Windows developer. Especially important is full understanding if you are not going to follow the advice given above. - - [How To Use the C Run-Time](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time) - - [Run-Time Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library) + - [How To Use the C Runtime](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time) + - [Runtime Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library) - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://docs.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries) If your app is misbehaving in some strange way, or it is suffering from memory @@ -185,59 +185,11 @@ multi-threaded dynamic C runtime. If you get linkage errors read section 5.7 of the FAQ document. -## mingw-w64 - -Make sure that mingw-w64's bin directory is in the search path, for example: - -```cmd -set PATH=c:\mingw-w64\bin;%PATH% -``` - -then run `mingw32-make mingw32` in the root dir. There are other -make targets available to build libcurl with more features, use: - - - `mingw32-make mingw32-zlib` to build with Zlib support; - - `mingw32-make mingw32-ssl-zlib` to build with SSL and Zlib enabled; - - `mingw32-make mingw32-ssh2-ssl-zlib` to build with SSH2, SSL, Zlib; - - `mingw32-make mingw32-ssh2-ssl-sspi-zlib` to build with SSH2, SSL, Zlib - and SSPI support. - -If you have any problems linking libraries or finding header files, be sure -to verify that the provided `Makefile.mk` files use the proper paths, and -adjust as necessary. It is also possible to override these paths with -environment variables, for example: - -```cmd -set ZLIB_PATH=c:\zlib-1.2.12 -set OPENSSL_PATH=c:\openssl-3.0.5 -set LIBSSH2_PATH=c:\libssh2-1.10.0 -``` - -It is also possible to build with other LDAP installations than MS LDAP; -currently it is possible to build with native Win32 OpenLDAP, or with the -*Novell CLDAP* SDK. If you want to use these you need to set these vars: - -```cmd -set CPPFLAGS=-Ic:/openldap/include -DCURL_HAS_OPENLDAP_LDAPSDK -set LDFLAGS=-Lc:/openldap/lib -set LIBS=-lldap -llber -``` - -or for using the Novell SDK: - -```cmd -set CPPFLAGS=-Ic:/openldapsdk/inc -DCURL_HAS_NOVELL_LDAPSDK -set LDFLAGS=-Lc:/openldapsdk/lib/mscvc -set LIBS=-lldapsdk -lldapssl -lldapx -``` - -If you want to enable LDAPS support then append `-ldaps` to the make target. - ## Cygwin Almost identical to the Unix installation. Run the configure script in the curl source tree root with `sh configure`. Make sure you have the `sh` -executable in `/bin/` or you will see the configure fail toward the end. +executable in `/bin/` or you see the configure fail toward the end. Run `make` @@ -315,16 +267,16 @@ might yet need some additional adjustment. ## Important static libcurl usage note When building an application that uses the static libcurl library on Windows, -you must add `-DCURL_STATICLIB` to your `CFLAGS`. Otherwise the linker will -look for dynamic import symbols. +you must add `-DCURL_STATICLIB` to your `CFLAGS`. Otherwise the linker looks +for dynamic import symbols. ## Legacy Windows and SSL Schannel (from Windows SSPI), is the native SSL library in Windows. However, -Schannel in Windows <= XP is unable to connect to servers that -no longer support the legacy handshakes and algorithms used by those -versions. If you will be using curl in one of those earlier versions of -Windows you should choose another SSL backend such as OpenSSL. +Schannel in Windows <= XP is unable to connect to servers that no longer +support the legacy handshakes and algorithms used by those versions. If you +are using curl in one of those earlier versions of Windows you should choose +another SSL backend such as OpenSSL. # Apple Platforms (macOS, iOS, tvOS, watchOS, and their simulator counterparts) @@ -333,10 +285,10 @@ implementation, Secure Transport, instead of OpenSSL. To build with Secure Transport for SSL/TLS, use the configure option `--with-secure-transport`. When Secure Transport is in use, the curl options `--cacert` and `--capath` -and their libcurl equivalents, will be ignored, because Secure Transport uses -the certificates stored in the Keychain to evaluate whether or not to trust -the server. This, of course, includes the root certificates that ship with the -OS. The `--cert` and `--engine` options, and their libcurl equivalents, are +and their libcurl equivalents, are ignored, because Secure Transport uses the +certificates stored in the Keychain to evaluate whether or not to trust the +server. This, of course, includes the root certificates that ship with the OS. +The `--cert` and `--engine` options, and their libcurl equivalents, are currently unimplemented in curl with Secure Transport. In general, a curl build for an Apple `ARCH/SDK/DEPLOYMENT_TARGET` combination @@ -355,7 +307,8 @@ make -j8 make install ``` -Above will build curl for macOS platform with `x86_64` architecture and `10.8` as deployment target. +The above command lines build curl for macOS platform with `x86_64` +architecture and `10.8` as deployment target. Here is an example for iOS device: @@ -388,14 +341,14 @@ In all above, the built libraries and executables can be found in the # Android -When building curl for Android it's recommended to use a Linux/macOS environment -since using curl's `configure` script is the easiest way to build curl -for Android. Before you can build curl for Android, you need to install the -Android NDK first. This can be done using the SDK Manager that is part of -Android Studio. Once you have installed the Android NDK, you need to figure out -where it has been installed and then set up some environment variables before -launching `configure`. On macOS, those variables could look like this to compile -for `aarch64` and API level 29: +When building curl for Android it is recommended to use a Linux/macOS +environment since using curl's `configure` script is the easiest way to build +curl for Android. Before you can build curl for Android, you need to install +the Android NDK first. This can be done using the SDK Manager that is part of +Android Studio. Once you have installed the Android NDK, you need to figure +out where it has been installed and then set up some environment variables +before launching `configure`. On macOS, those variables could look like this +to compile for `aarch64` and API level 29: ```bash export ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/25.1.8937393 # Point into your NDK. @@ -415,16 +368,16 @@ to adjust those variables accordingly. After that you can build curl like this: ./configure --host aarch64-linux-android --with-pic --disable-shared -Note that this will not give you SSL/TLS support. If you need SSL/TLS, you have -to build curl against a SSL/TLS layer, e.g. OpenSSL, because it's impossible for -curl to access Android's native SSL/TLS layer. To build curl for Android using -OpenSSL, follow the OpenSSL build instructions and then install `libssl.a` and -`libcrypto.a` to `$TOOLCHAIN/sysroot/usr/lib` and copy `include/openssl` to -`$TOOLCHAIN/sysroot/usr/include`. Now you can build curl for Android using -OpenSSL like this: +Note that this does not give you SSL/TLS support. If you need SSL/TLS, you +have to build curl with a SSL/TLS library, e.g. OpenSSL, because it is +impossible for curl to access Android's native SSL/TLS layer. To build curl +for Android using OpenSSL, follow the OpenSSL build instructions and then +install `libssl.a` and `libcrypto.a` to `$TOOLCHAIN/sysroot/usr/lib` and copy +`include/openssl` to `$TOOLCHAIN/sysroot/usr/include`. Now you can build curl +for Android using OpenSSL like this: ```bash -LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you will need to the SSL/TLS layer's transitive dependencies if you are linking statically. +LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you need to the SSL/TLS layer's transitive dependencies if you are linking statically. ./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN/sysroot/usr" ``` @@ -434,22 +387,22 @@ For IBM i (formerly OS/400), you can use curl in two different ways: - Natively, running in the **ILE**. The obvious use is being able to call curl from ILE C or RPG applications. - - You will need to build this from source. See `packages/OS400/README` for - the ILE specific build instructions. -- In the **PASE** environment, which runs AIX programs. curl will be built as - it would be on AIX. - - IBM provides builds of curl in their Yum repository for PASE software. - - To build from source, follow the Unix instructions. +- You need to build this from source. See `packages/OS400/README` for the ILE + specific build instructions. +- In the **PASE** environment, which runs AIX programs. curl is built as it + would be on AIX. +- IBM provides builds of curl in their Yum repository for PASE software. +- To build from source, follow the Unix instructions. There are some additional limitations and quirks with curl on this platform; they affect both environments. ## Multi-threading notes -By default, jobs in IBM i will not start with threading enabled. (Exceptions +By default, jobs in IBM i does not start with threading enabled. (Exceptions include interactive PASE sessions started by `QP2TERM` or SSH.) If you use curl in an environment without threading when options like asynchronous DNS -were enabled, you will get messages like: +were enabled, you get messages like: ``` getaddrinfo() thread failed to start @@ -494,9 +447,9 @@ export NM=ppc_405-nm You may also need to provide a parameter like `--with-random=/dev/urandom` to configure as it cannot detect the presence of a random number generating -device for a target system. The `--prefix` parameter specifies where curl -will be installed. If `configure` completes successfully, do `make` and `make -install` as usual. +device for a target system. The `--prefix` parameter specifies where curl gets +installed. If `configure` completes successfully, do `make` and `make install` +as usual. In some cases, you may be able to simplify the above commands to as little as: @@ -508,10 +461,16 @@ There are a number of configure options that can be used to reduce the size of libcurl for embedded applications where binary size is an important factor. First, be sure to set the `CFLAGS` variable when configuring with any relevant compiler optimization flags to reduce the size of the binary. For gcc, this -would mean at minimum the -Os option, and potentially the `-march=X`, -`-mdynamic-no-pic` and `-flto` options as well, e.g. +would mean at minimum the `-Os` option, and others like the following that +may be relevant in some environments: `-march=X`, `-mthumb`, `-m32`, +`-mdynamic-no-pic`, `-flto`, `-fdata-sections`, `-ffunction-sections`, +`-fno-unwind-tables`, `-fno-asynchronous-unwind-tables`, +`-fno-record-gcc-switches`, `-fsection-anchors`, `-fno-plt`, +`-Wl,--gc-sections`, `-Wl,-Bsymbolic`, `-Wl,-s`, + +For example, this is how to combine a few of these options: - ./configure CFLAGS='-Os' LDFLAGS='-Wl,-Bsymbolic'... + ./configure CC=gcc CFLAGS='-Os -ffunction-sections' LDFLAGS='-Wl,--gc-sections'... Note that newer compilers often produce smaller code than older versions due to improved optimization. @@ -519,9 +478,9 @@ due to improved optimization. Be sure to specify as many `--disable-` and `--without-` flags on the configure command-line as you can to disable all the libcurl features that you know your application is not going to need. Besides specifying the -`--disable-PROTOCOL` flags for all the types of URLs your application will not +`--disable-PROTOCOL` flags for all the types of URLs your application do not use, here are some other flags that can reduce the size of the library by -disabling support for some feature: +disabling support for some feature (run `./configure --help` to see them all): - `--disable-alt-svc` (HTTP Alt-Svc) - `--disable-ares` (the C-ARES DNS library) @@ -535,13 +494,17 @@ disabling support for some feature: - `--disable-dateparse` (date parsing for time conditionals) - `--disable-dnsshuffle` (internal server load spreading) - `--disable-doh` (DNS-over-HTTP) + - `--disable-form-api` (POST form API) - `--disable-get-easy-options` (lookup easy options at runtime) + - `--disable-headers-api` (API to access headers) - `--disable-hsts` (HTTP Strict Transport Security) - `--disable-http-auth` (all HTTP authentication) - `--disable-ipv6` (IPv6) - `--disable-libcurl-option` (--libcurl C code generation support) - - `--disable-manual` (built-in documentation) + - `--disable-manual` (--manual built-in documentation) + - `--disable-mime` (MIME API) - `--disable-netrc` (.netrc file) + - `--disable-ntlm` (NTLM authentication) - `--disable-ntlm-wb` (NTLM WinBind) - `--disable-progress-meter` (graphical progress meter in library) - `--disable-proxy` (HTTP and SOCKS proxies) @@ -563,30 +526,21 @@ disabling support for some feature: - `--without-ssl` (SSL/TLS) - `--without-zlib` (on-the-fly decompression) -The GNU compiler and linker have a number of options that can reduce the -size of the libcurl dynamic libraries on some platforms even further. -Specify them by providing appropriate `CFLAGS` and `LDFLAGS` variables on -the configure command-line, e.g. - - CFLAGS="-Os -ffunction-sections -fdata-sections - -fno-unwind-tables -fno-asynchronous-unwind-tables -flto" - LDFLAGS="-Wl,-s -Wl,-Bsymbolic -Wl,--gc-sections" - Be sure also to strip debugging symbols from your binaries after compiling -using 'strip' (or the appropriate variant if cross-compiling). If space is -really tight, you may be able to remove some unneeded sections of the shared -library using the -R option to objcopy (e.g. the .comment section). +using 'strip' or an option like `-s`. If space is really tight, you may be able +to gain a few bytes by removing some unneeded sections of the shared library +using the -R option to objcopy (e.g. the .comment section). Using these techniques it is possible to create a basic HTTP-only libcurl -shared library for i386 Linux platforms that is only 133 KiB in size -(as of libcurl version 7.80.0, using gcc 11.2.0). +shared library for i386 Linux platforms that is only 130 KiB in size +(as of libcurl version 8.6.0, using gcc 13.2.0). -You may find that statically linking libcurl to your application will result -in a lower total size than dynamically linking. +You may find that statically linking libcurl to your application results in a +lower total size than dynamically linking. -Note that the curl test harness can detect the use of some, but not all, of -the `--disable` statements suggested above. Use will cause tests relying on -those features to fail. The test harness can be manually forced to skip the +The curl test harness can detect the use of some, but not all, of the +`--disable` statements suggested above. Use of these can cause tests relying +on those features to fail. The test harness can be manually forced to skip the relevant tests by specifying certain key words on the `runtests.pl` command line. Following is a list of appropriate key words for those configure options that are not automatically detected: diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md index d7513a8ff38..b1a095fe9ef 100644 --- a/docs/INTERNALS.md +++ b/docs/INTERNALS.md @@ -43,7 +43,6 @@ versions of libs and build tools. - GNU M4 1.4 - perl 5.6 - roffit 0.5 - - nroff any version that supports `-man [in] [out]` - cmake 3.7 Library Symbols diff --git a/docs/IPFS.md b/docs/IPFS.md index 24bba8b75a5..65c0f5daded 100644 --- a/docs/IPFS.md +++ b/docs/IPFS.md @@ -19,12 +19,29 @@ By explicitly requesting [application/vnd.ipld.raw](https://www.iana.org/assignm This enables users to use untrusted, public gateways without worrying they might return invalid/malicious bytes. ## IPFS and IPNS protocol handling -There are various ways to access data from the IPFS network. One such way is through the concept of public "[gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/#overview)". The short version is that entities can offer gateway services. An example here that is hosted by Protocol Labs (who also makes IPFS) is `dweb.link` and `ipfs.io`. Both sites expose gateway functionality. Getting a file through `ipfs.io` looks like this: `https://ipfs.io/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi` -If you were to be [running your own IPFS node](https://docs.ipfs.tech/how-to/command-line-quick-start/) then you, by default, also have a [local gateway](https://specs.ipfs.tech/http-gateways/) running. In it's default configuration the earlier example would then also work in this link: `http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi` +There are various ways to access data from the IPFS network. One such way is +through the concept of public +"[gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/#overview)". The +short version is that entities can offer gateway services. An example here +that is hosted by Protocol Labs (who also makes IPFS) is `dweb.link` and +`ipfs.io`. Both sites expose gateway functionality. Getting a file through +`ipfs.io` looks like this: +`https://ipfs.io/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi` + +If you were to be [running your own IPFS +node](https://docs.ipfs.tech/how-to/command-line-quick-start/) then you, by +default, also have a [local gateway](https://specs.ipfs.tech/http-gateways/) +running. In its default configuration the earlier example would then also work +in this link: + +`http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi` ## cURL handling of the IPFS protocols -The IPFS integration in cURL hides this gateway logic for you. So instead of providing a full URL to a file on IPFS like this: + +The IPFS integration in cURL hides this gateway logic for you. Instead of +providing a full URL to a file on IPFS like this: + ``` curl http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi ``` @@ -34,49 +51,77 @@ You can provide it with the IPFS protocol instead: curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi ``` -With the IPFS protocol way of asking a file, cURL still needs to know the gateway. curl essentially just rewrites the IPFS based URL to a gateway URL. +With the IPFS protocol way of asking a file, cURL still needs to know the +gateway. curl essentially just rewrites the IPFS based URL to a gateway URL. ### IPFS_GATEWAY environment variable -If the `IPFS_GATEWAY` environment variable is found, it's value is used as gateway. + +If the `IPFS_GATEWAY` environment variable is found, its value is used as +gateway. ### Automatic gateway detection -When you provide no additional details to cURL then cURL will: -1. First look for the `IPFS_GATEWAY` environment variable and use that if it's set. -2. Look for the file: `~/.ipfs/gateway`. If it can find that file then it means that you have a local gateway running and that file contains the URL to your local gateway. +When you provide no additional details to cURL then it: + +1. First looks for the `IPFS_GATEWAY` environment variable and use that if it + is set. +2. Looks for the file: `~/.ipfs/gateway`. If it can find that file then it + means that you have a local gateway running and that file contains the URL + to your local gateway. -If cURL fails you'll be presented with an error message and a link to this page to the option most applicable to solving the issue. +If cURL fails, you are presented with an error message and a link to this page +to the option most applicable to solving the issue. ### `--ipfs-gateway` argument -You can also provide a `--ipfs-gateway` argument to cURL. This overrules any other gateway setting. curl won't fallback to the other options if the provided gateway didn't work. + +You can also provide a `--ipfs-gateway` argument to cURL. This overrules any +other gateway setting. curl does not fallback to the other options if the +provided gateway did not work. ## Gateway redirects -A gateway could redirect to another place. For example, `dweb.link` redirects [path based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) requests to [subdomain based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) ones. So a request to: -``` -curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi --ipfs-gateway https://dweb.link -``` + +A gateway could redirect to another place. For example, `dweb.link` redirects +[path based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) +requests to [subdomain +based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) +ones. A request using: + + curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi --ipfs-gateway https://dweb.link + Which would be translated to: -``` -https://dweb.link/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi -``` -Will redirect to: -``` -https://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi.ipfs.dweb.link -``` -If you trust this behavior from your gateway of choice then passing the `-L` option will follow the redirect. + + https://dweb.link/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi + +redirects to: + + https://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi.ipfs.dweb.link + +If you trust this behavior from your gateway of choice then passing the `-L` +option follows the redirect. ## Error messages and hints + Depending on the arguments, cURL could present the user with an error. ### Gateway file and environment variable -cURL tried to look for the file: `~/.ipfs/gateway` but couldn't find it. It also tried to look for the `IPFS_GATEWAY` environment variable but couldn't find that either. This happens when no extra arguments are passed to cURL and letting it try to figure it out [automatically](#automatic-gateway-detection). -Any IPFS implementation that has gateway support should expose it's URL in `~/.ipfs/gateway`. If you are already running a gateway, make sure it exposes the file where cURL expects to find it. +cURL tried to look for the file: `~/.ipfs/gateway` but could not find it. It +also tried to look for the `IPFS_GATEWAY` environment variable but could not +find that either. This happens when no extra arguments are passed to cURL and +letting it try to figure it out [automatically](#automatic-gateway-detection). -Alternatively you could set the `IPFS_GATEWAY` environment variable or pass the `--ipfs-gateway` flag to the cURL command. +Any IPFS implementation that has gateway support should expose its URL in +`~/.ipfs/gateway`. If you are already running a gateway, make sure it exposes +the file where cURL expects to find it. + +Alternatively you could set the `IPFS_GATEWAY` environment variable or pass +the `--ipfs-gateway` flag to the cURL command. ### Malformed gateway URL -The command executed evaluates in an invalid URL. This could be anywhere in the URL, but a likely point is a wrong gateway URL. -Inspect the URL set via the `IPFS_GATEWAY` environment variable or passed with the `--ipfs-gateway` flag. -Alternatively opt to go for the [automatic](#automatic-gateway-detection) gateway detection. +The command executed evaluates in an invalid URL. This could be anywhere in +the URL, but a likely point is a wrong gateway URL. + +Inspect the URL set via the `IPFS_GATEWAY` environment variable or passed with +the `--ipfs-gateway` flag. Alternatively opt to go for the +[automatic](#automatic-gateway-detection) gateway detection. diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index e52774a15f5..f4ced4d84fd 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -16,12 +16,12 @@ problems may have been fixed or changed somewhat since this was written. 1.5 Expect-100 meets 417 2. TLS + 2.1 IMAPS connection fails with rustls error 2.3 Unable to use PKCS12 certificate with Secure Transport 2.4 Secure Transport will not import PKCS#12 client certificates without a password 2.5 Client cert handling with Issuer DN differs between backends 2.7 Client cert (MTLS) issues with Schannel 2.11 Schannel TLS 1.2 handshake bug in old Windows versions - 2.12 FTPS with Schannel times out file list operation 2.13 CURLOPT_CERTINFO results in CURLE_OUT_OF_MEMORY with Schannel 3. Email protocols @@ -30,6 +30,7 @@ problems may have been fixed or changed somewhat since this was written. 3.3 POP3 expects "CRLF.CRLF" eob for some single-line responses 3.4 AUTH PLAIN for SMTP is not working on all servers 3.5 APOP authentication fails on POP3 + 3.6 POP3 issue when reading small chunks 4. Command line @@ -44,6 +45,7 @@ problems may have been fixed or changed somewhat since this was written. 5.12 flaky CI builds 5.13 long paths are not fully supported on Windows 5.14 Windows Unicode builds use homedir in current locale + 5.15 Unicode on Windows 6. Authentication 6.1 NTLM authentication and unicode @@ -59,8 +61,11 @@ problems may have been fixed or changed somewhat since this was written. 6.13 Negotiate against Hadoop HDFS 7. FTP + 7.1 FTP upload fails if remembered dir is deleted + 7.2 Implicit FTPS upload timeout 7.3 FTP with NOBODY and FAILONERROR 7.4 FTP with ACCT + 7.5 FTPS upload, FileZilla, GnuTLS and close_notify 7.11 FTPS upload data loss with TLS 1.3 7.12 FTPS directory listing hangs on Windows with Schannel @@ -92,10 +97,8 @@ problems may have been fixed or changed somewhat since this was written. 15.1 cmake outputs: no version information available 15.2 support build with GnuTLS 15.3 unusable tool_hugehelp.c with MinGW - 15.4 build docs/curl.1 15.6 uses -lpthread instead of Threads::Threads 15.7 generated .pc file contains strange entries - 15.8 libcurl.pc uses absolute library paths 15.11 ExternalProject_Add does not set CURL_CA_PATH 15.13 CMake build with MIT Kerberos does not work @@ -104,12 +107,16 @@ problems may have been fixed or changed somewhat since this was written. 16.6 aws-sigv4 does not behave well with AWS VPC Lattice 17. HTTP/2 + 17.1 HTTP/2 prior knowledge over proxy 17.2 HTTP/2 frames while in the connection pool kill reuse 17.3 ENHANCE_YOUR_CALM causes infinite retries 18. HTTP/3 18.1 connection migration does not work + 19. RTSP + 19.1 Some methods do not support response bodies + ============================================================================== 1. HTTP @@ -129,6 +136,10 @@ problems may have been fixed or changed somewhat since this was written. 2. TLS +2.1 IMAPS connection fails with rustls error + + https://github.com/curl/curl/issues/10457 + 2.3 Unable to use PKCS12 certificate with Secure Transport See https://github.com/curl/curl/issues/5403 @@ -159,12 +170,6 @@ problems may have been fixed or changed somewhat since this was written. https://github.com/curl/curl/issues/5488 -2.12 FTPS with Schannel times out file list operation - - "Instead of the command completing, it just sits there until the timeout - expires." - the same command line seems to work with other TLS backends and - other operating systems. See https://github.com/curl/curl/issues/5284. - 2.13 CURLOPT_CERTINFO results in CURLE_OUT_OF_MEMORY with Schannel https://github.com/curl/curl/issues/8741 @@ -200,6 +205,12 @@ problems may have been fixed or changed somewhat since this was written. See https://github.com/curl/curl/issues/10073 +3.6 POP3 issue when reading small chunks + + CURL_DBG_SOCK_RMAX=4 ./runtests.pl -v 982 + + See https://github.com/curl/curl/issues/12063 + 4. Command line 5. Build and portability issues @@ -281,6 +292,16 @@ problems may have been fixed or changed somewhat since this was written. See https://github.com/curl/curl/pull/7252 and https://github.com/curl/curl/pull/7281 +5.15 Unicode on Windows + + Passing in a unicode filename with -o: + + https://github.com/curl/curl/issues/11461 + + Passing in unicode character with -d: + + https://github.com/curl/curl/issues/12231 + 6. Authentication 6.1 NTLM authentication and unicode @@ -360,6 +381,18 @@ problems may have been fixed or changed somewhat since this was written. 7. FTP +7.1 FTP upload fails if remembered dir is deleted + + curl's FTP code assumes that the directory it entered in a previous transfer + still exists when it comes back to do a second transfer, and does not respond + well if it was indeed deleted in the mean time. + + https://github.com/curl/curl/issues/12181 + +7.2 Implicit FTPS upload timeout + + https://github.com/curl/curl/issues/11720 + 7.3 FTP with NOBODY and FAILONERROR It seems sensible to be able to use CURLOPT_NOBODY and CURLOPT_FAILONERROR @@ -373,6 +406,13 @@ problems may have been fixed or changed somewhat since this was written. thus fails to issue the correct command: https://curl.se/bug/view.cgi?id=635 +7.5 FTPS upload, FileZilla, GnuTLS and close_notify + + An issue where curl does not send the TLS alert close_notify, which triggers + the wrath of GnuTLS in FileZilla server, and a FTP reply 426 ECONNABORTED. + + https://github.com/curl/curl/issues/11383 + 7.11 FTPS upload data loss with TLS 1.3 During FTPS upload curl does not attempt to read TLS handshake messages sent @@ -390,9 +430,16 @@ problems may have been fixed or changed somewhat since this was written. https://github.com/curl/curl/issues/6149 -7.12 FTPS directory listing hangs on Windows with Schannel +7.12 FTPS server compatibility on Windows with Schannel - https://github.com/curl/curl/issues/9161 + FTPS is not widely used with the Schannel TLS backend and so there may be more + bugs compared to other TLS backends such as OpenSSL. In the past users have + reported hanging and failed connections. It's very likely some changes to curl + since then fixed the issues. None of the reported issues can be reproduced any + longer. + + If you encounter an issue connecting to your server via FTPS with the latest + curl and Schannel then please search for open issues or file a new issue. 9. SFTP and SCP @@ -525,12 +572,6 @@ problems may have been fixed or changed somewhat since this was written. see https://github.com/curl/curl/issues/3125 -15.4 build docs/curl.1 - - The cmake build does not create the docs/curl.1 file and therefore must rely on - it being there already. This makes the --manual option not work and test - cases like 1139 cannot function. - 15.6 uses -lpthread instead of Threads::Threads See https://github.com/curl/curl/issues/6166 @@ -542,14 +583,6 @@ problems may have been fixed or changed somewhat since this was written. See https://github.com/curl/curl/issues/6167 -15.8 libcurl.pc uses absolute library paths - - The libcurl.pc file generated by cmake contains things like Libs.private: - /usr/lib64/libssl.so /usr/lib64/libcrypto.so /usr/lib64/libz.so. The - autotools equivalent would say Libs.private: -lssl -lcrypto -lz - - See https://github.com/curl/curl/issues/6169 - 15.11 ExternalProject_Add does not set CURL_CA_PATH CURL_CA_BUNDLE and CURL_CA_PATH are not set properly when cmake's @@ -580,6 +613,10 @@ problems may have been fixed or changed somewhat since this was written. 17. HTTP/2 +17.1 HTTP/2 prior knowledge over proxy + + https://github.com/curl/curl/issues/12641 + 17.2 HTTP/2 frames while in the connection pool kill reuse If the server sends HTTP/2 frames (like for example an HTTP/2 PING frame) to @@ -602,3 +639,13 @@ problems may have been fixed or changed somewhat since this was written. 18.1 connection migration does not work https://github.com/curl/curl/issues/7695 + +19. RTSP + +19.1 Some methods do not support response bodies + + The RTSP implementation is written to assume that a number of RTSP methods + will always get responses without bodies, even though there seems to be no + indication in the RFC that this is always the case. + + https://github.com/curl/curl/issues/12414 diff --git a/docs/MAIL-ETIQUETTE b/docs/MAIL-ETIQUETTE index 2dcf9cb8963..d42a6f0d629 100644 --- a/docs/MAIL-ETIQUETTE +++ b/docs/MAIL-ETIQUETTE @@ -40,13 +40,13 @@ MAIL ETIQUETTE please use the one or the ones that suit you the most. Each mailing list has hundreds up to thousands of readers, meaning that each - mail sent will be received and read by a large number of people. People - from various cultures, regions, religions and continents. + mail sent is received and read by a large number of people. People from + various cultures, regions, religions and continents. 1.2 Netiquette Netiquette is a common term for how to behave on the Internet. Of course, in - each particular group and subculture there will be differences in what is + each particular group and subculture there are differences in what is acceptable and what is considered good manners. This document outlines what we in the curl project consider to be good @@ -71,8 +71,8 @@ MAIL ETIQUETTE through to all the subscribers. If you post without being subscribed (or from a different mail address than - the one you are subscribed with), your mail will simply be silently - discarded. You have to subscribe first, then post. + the one you are subscribed with), your mail is simply silently discarded. + You have to subscribe first, then post. The reason for this unfortunate and strict subscription policy is of course to stop spam from pestering the lists. @@ -80,14 +80,13 @@ MAIL ETIQUETTE 1.5 Moderation of new posters Several of the curl mailing lists automatically make all posts from new - subscribers be moderated. This means that after you have subscribed and - sent your first mail to a list, that mail will not be let through to the - list until a mailing list administrator has verified that it is OK and - permits it to get posted. + subscribers be moderated. After you have subscribed and sent your first mail + to a list, that mail is not let through to the list until a mailing list + administrator has verified that it is OK and permits it to get posted. Once a first post has been made that proves the sender is actually talking - about curl-related subjects, the moderation "flag" will be switched off and - future posts will go through without being moderated. + about curl-related subjects, the moderation "flag" is switched off and + future posts go through without being moderated. The reason for this moderation policy is that we do suffer from spammers who actually subscribe and send spam to our lists. @@ -95,8 +94,8 @@ MAIL ETIQUETTE 1.6 Handling trolls and spam Despite our good intentions and hard work to keep spam off the lists and to - maintain a friendly and positive atmosphere, there will be times when spam - and or trolls get through. + maintain a friendly and positive atmosphere, there are times when spam and + or trolls get through. Troll - "someone who posts inflammatory, extraneous, or off-topic messages in an online community" @@ -106,10 +105,10 @@ MAIL ETIQUETTE No matter what, we NEVER EVER respond to trolls or spammers on the list. If you believe the list admin should do something in particular, contact them - off-list. The subject will be taken care of as much as possible to prevent - repeated offenses, but responding on the list to such messages never leads to - anything good and only puts the light even more on the offender: which was - the entire purpose of it getting sent to the list in the first place. + off-list. The subject is taken care of as much as possible to prevent + repeated offenses, but responding on the list to such messages never leads + to anything good and only puts the light even more on the offender: which + was the entire purpose of it getting sent to the list in the first place. Do not feed the trolls. @@ -130,7 +129,7 @@ MAIL ETIQUETTE 1.8 I posted, now what? If you are not subscribed with the same email address that you used to send - the email, your post will just be silently discarded. + the email, your post is silently discarded. If you posted for the first time to the mailing list, you first need to wait for an administrator to allow your email to go through (moderated). This @@ -151,28 +150,28 @@ MAIL ETIQUETTE what you did with details enough to allow others to help point out the problem or repeat the steps in their locations. - Failing to include details will only delay responses and make people respond - and ask for more details and you will have to send a follow-up email that - includes them. + Failing to include details only delays responses and make people respond and + ask for more details and you have to send follow-up emails that include + them. Expect the responses to primarily help YOU debug the issue, or ask YOU questions that can lead you or others towards a solution or explanation to whatever you experience. If you are a repeat offender to the guidelines outlined in this document, - chances are that people will ignore you at will and your chances to get - responses in the future will greatly diminish. + chances are that people ignore you and your chances to get responses in the + future greatly diminish. 1.9 Your emails are public Your email, its contents and all its headers and the details in those - headers will be received by every subscriber of the mailing list that you - send your email to. + headers are received by every subscriber of the mailing list that you send + your email to. - Your email as sent to a curl mailing list will end up in mail archives, on - the curl website and elsewhere, for others to see and read. Today and in - the future. In addition to the archives, the mail is sent out to thousands - of individuals. There is no way to undo a sent email. + Your email as sent to a curl mailing list ends up in mail archives, on the + curl website and elsewhere, for others to see and read. Today and in the + future. In addition to the archives, the mail is sent out to thousands of + individuals. There is no way to undo a sent email. When sending emails to a curl mailing list, do not include sensitive information such as user names and passwords; use fake ones, temporary ones diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 8de4bd7029c..3ce869413f5 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -10,7 +10,7 @@ Get a README file from an FTP server: curl ftp://ftp.example.com/README -Get a web page from a server using port 8000: +Get a webpage from a server using port 8000: curl http://www.example.com:8000/ @@ -63,13 +63,12 @@ Get a file from an SMB server: ## Download to a File -Get a web page and store in a local file with a specific name: +Get a webpage and store in a local file with a specific name: curl -o thatpage.html http://www.example.com/ -Get a web page and store in a local file, make the local file get the name of -the remote document (if no file name part is specified in the URL, this will -fail): +Get a webpage and store in a local file, make the local file get the name of +the remote document (if no filename part is specified in the URL, this fails): curl -O http://www.example.com/index.html @@ -104,7 +103,7 @@ This is similar to FTP, but you can use the `--key` option to specify a private key to use instead of a password. Note that the private key may itself be protected by a password that is unrelated to the login password of the remote system; this password is specified using the `--pass` option. -Typically, curl will automatically extract the public key from the private key +Typically, curl automatically extracts the public key from the private key file, but in cases where curl does not have the proper library support, a matching public key file must be specified using the `--pubkey` option. @@ -126,7 +125,7 @@ secure ones out of the ones that the server accepts for the given URL, by using `--anyauth`. **Note**! According to the URL specification, HTTP URLs can not contain a user -and password, so that style will not work when using curl via a proxy, even +and password, so that style does not work when using curl via a proxy, even though curl allows it at other times. When using a proxy, you _must_ use the `-u` style for user and password. @@ -161,7 +160,7 @@ specified as: curl --noproxy example.com -x my-proxy:888 http://www.example.com/ If the proxy is specified with `--proxy1.0` instead of `--proxy` or `-x`, then -curl will use HTTP/1.0 instead of HTTP/1.1 for any `CONNECT` attempts. +curl uses HTTP/1.0 instead of HTTP/1.1 for any `CONNECT` attempts. curl also supports SOCKS4 and SOCKS5 proxies with `--socks4` and `--socks5`. @@ -224,7 +223,7 @@ Upload data from a specified file, login with user and password: curl -T uploadfile -u user:passwd ftp://ftp.example.com/myfile -Upload a local file to the remote site, and use the local file name at the +Upload a local file to the remote site, and use the local filename at the remote site too: curl -T uploadfile -u user:passwd ftp://ftp.example.com/ @@ -257,16 +256,16 @@ For other ways to do HTTP data upload, see the POST section below. ## Verbose / Debug -If curl fails where it is not supposed to, if the servers do not let you in, if -you cannot understand the responses: use the `-v` flag to get verbose -fetching. Curl will output lots of info and what it sends and receives in -order to let the user see all client-server interaction (but it will not show you -the actual data). +If curl fails where it is not supposed to, if the servers do not let you in, +if you cannot understand the responses: use the `-v` flag to get verbose +fetching. Curl outputs lots of info and what it sends and receives in order to +let the user see all client-server interaction (but it does not show you the +actual data). curl -v ftp://ftp.example.com/ To get even more details and information on what curl does, try using the -`--trace` or `--trace-ascii` options with a given file name to log to, like +`--trace` or `--trace-ascii` options with a given filename to log to, like this: curl --trace trace.txt www.haxx.se @@ -283,7 +282,7 @@ extensive. For HTTP, you can get the header information (the same as `-I` would show) shown before the data by using `-i`/`--include`. Curl understands the `-D`/`--dump-header` option when getting files from both FTP and HTTP, and it -will then store the headers in the specified file. +then stores the headers in the specified file. Store the HTTP headers in a separate file (headers.txt in the example): @@ -347,20 +346,20 @@ multipart/form-data type. This latter type supports things like file upload. `-F` accepts parameters like `-F "name=contents"`. If you want the contents to be read from a file, use `@filename` as contents. When specifying a file, you can also specify the file content type by appending `;type=` to the -file name. You can also post the contents of several files in one field. For +filename. You can also post the contents of several files in one field. For example, the field name `coolfiles` is used to send three files, with different content types using the following syntax: curl -F "coolfiles=@fil1.gif;type=image/gif,fil2.txt,fil3.html" http://www.example.com/postit.cgi -If the content-type is not specified, curl will try to guess from the file +If the content-type is not specified, curl tries to guess from the file extension (it only knows a few), or use the previously specified type (from an -earlier file if several files are specified in a list) or else it will use the +earlier file if several files are specified in a list) or else it uses the default type `application/octet-stream`. Emulate a fill-in form with `-F`. Let's say you fill in three fields in a -form. One field is a file name which to post, one field is your name and one +form. One field is a filename which to post, one field is your name and one field is a file description. We want to post the file we have written named `cooltext.txt`. To let curl do the posting of this data instead of your favorite browser, you have to read the HTML source of the form page and find @@ -395,7 +394,7 @@ used on the command line. It is especially useful to fool or trick stupid servers or CGI scripts that rely on that information being available or contain certain data. - curl -e www.exomaple.org http://www.example.com/ + curl -e www.example.org http://www.example.com/ ## User Agent @@ -475,11 +474,11 @@ non-existing file to trigger the cookie awareness like: curl -L -b empty.txt www.example.com The file to read cookies from must be formatted using plain HTTP headers OR as -Netscape's cookie file. Curl will determine what kind it is based on the file -contents. In the above command, curl will parse the header and store the -cookies received from www.example.com. curl will send to the server the stored -cookies which match the request as it follows the location. The file -`empty.txt` may be a nonexistent file. +Netscape's cookie file. Curl determines what kind it is based on the file +contents. In the above command, curl parses the header and store the cookies +received from www.example.com. curl sends the stored cookies which match the +request to the server as it follows the location. The file `empty.txt` may be +a nonexistent file. To read and write cookies from a Netscape cookie file, you can set both `-b` and `-c` to use the same file: @@ -511,8 +510,8 @@ From left-to-right: - `Curr.Speed` - the average transfer speed the last 5 seconds (the first 5 seconds of a transfer is based on less time of course.) -The `-#` option will display a totally different progress bar that does not -need much explanation! +The `-#` option displays a totally different progress bar that does not need +much explanation! ## Speed Limit @@ -549,14 +548,14 @@ Or prevent curl from uploading data faster than 1 megabyte per second: curl -T upload --limit-rate 1M ftp://uploads.example.com When using the `--limit-rate` option, the transfer rate is regulated on a -per-second basis, which will cause the total transfer speed to become lower -than the given number. Sometimes of course substantially lower, if your -transfer stalls during periods. +per-second basis, which causes the total transfer speed to become lower than +the given number. Sometimes of course substantially lower, if your transfer +stalls during periods. ## Config File Curl automatically tries to read the `.curlrc` file (or `_curlrc` file on -Microsoft Windows systems) from the user's home dir on startup. +Microsoft Windows systems) from the user's home directory on startup. The config file could be made up with normal command line switches, but you can also specify the long options without the dashes to make it more @@ -592,16 +591,16 @@ URL by making a config file similar to: url = "http://help.with.curl.example.com/curlhelp.html" You can specify another config file to be read by using the `-K`/`--config` -flag. If you set config file name to `-` it will read the config from stdin, -which can be handy if you want to hide options from being visible in process -tables etc: +flag. If you set config filename to `-` it reads the config from stdin, which +can be handy if you want to hide options from being visible in process tables +etc: echo "user = user:passwd" | curl -K - http://that.secret.example.com ## Extra Headers When using curl in your own programs, you may end up needing to pass on your -own custom headers when getting a web page. You can do this by using the `-H` +own custom headers when getting a webpage. You can do this by using the `-H` flag. Example, send the header `X-you-and-me: yes` to the server when getting a @@ -626,11 +625,11 @@ directory at your ftp site, do: curl ftp://user:passwd@my.example.com/README If you want the README file from the root directory of that same site, you -need to specify the absolute file name: +need to specify the absolute filename: curl ftp://user:passwd@my.example.com//README -(I.e with an extra slash in front of the file name.) +(I.e with an extra slash in front of the filename.) ## SFTP and SCP and Path Names @@ -676,7 +675,7 @@ Download with `PORT` but use 192.168.0.10 as our IP address to use: ## Network Interface -Get a web page from a server using a specified port for the interface: +Get a webpage from a server using a specified port for the interface: curl --interface eth0:1 http://www.example.com/ @@ -707,8 +706,8 @@ personal password: curl -E /path/to/cert.pem:password https://secure.example.com/ -If you neglect to specify the password on the command line, you will be -prompted for the correct password before any data can be received. +If you neglect to specify the password on the command line, you are prompted +for the correct password before any data can be received. Many older HTTPS servers have problems with specific SSL or TLS versions, which newer versions of OpenSSL etc use, therefore it is sometimes useful to @@ -716,7 +715,7 @@ specify what TLS version curl should use.: curl --tlv1.0 https://secure.example.com/ -Otherwise, curl will attempt to use a sensible TLS default version. +Otherwise, curl attempts to use a sensible TLS default version. ## Resuming File Transfers @@ -783,11 +782,11 @@ Authentication support is still missing ## LDAP If you have installed the OpenLDAP library, curl can take advantage of it and -offer `ldap://` support. On Windows, curl will use WinLDAP from Platform SDK -by default. +offer `ldap://` support. On Windows, curl uses WinLDAP from Platform SDK by +default. -Default protocol version used by curl is LDAP version 3. Version 2 will be -used as a fallback mechanism in case version 3 fails to connect. +Default protocol version used by curl is LDAP version 3. Version 2 is used as +a fallback mechanism in case version 3 fails to connect. LDAP is a complex thing and writing an LDAP query is not an easy task. Familiarize yourself with the exact syntax description elsewhere. One @@ -804,14 +803,14 @@ You also can use authentication when accessing LDAP catalog: curl -u user:passwd "ldap://ldap.example.com/o=frontec??sub?mail=*" curl "ldap://user:passwd@ldap.example.com/o=frontec??sub?mail=*" -By default, if user and password are provided, OpenLDAP/WinLDAP will use basic +By default, if user and password are provided, OpenLDAP/WinLDAP uses basic authentication. On Windows you can control this behavior by providing one of `--basic`, `--ntlm` or `--digest` option in curl command line curl --ntlm "ldap://user:passwd@ldap.example.com/o=frontec??sub?mail=*" -On Windows, if no user/password specified, auto-negotiation mechanism will be -used with current logon credentials (SSPI/SPNEGO). +On Windows, if no user/password specified, auto-negotiation mechanism is used +with current logon credentials (SSPI/SPNEGO). ## Environment Variables @@ -824,17 +823,17 @@ with ALL_PROXY -A comma-separated list of host names that should not go through any proxy is +A comma-separated list of hostnames that should not go through any proxy is set in (only an asterisk, `*` matches all hosts) NO_PROXY -If the host name matches one of these strings, or the host is within the -domain of one of these strings, transactions with that node will not be done -over proxy. When a domain is used, it needs to start with a period. A user can +If the hostname matches one of these strings, or the host is within the domain +of one of these strings, transactions with that node is not done over the +proxy. When a domain is used, it needs to start with a period. A user can specify that both www.example.com and foo.example.com should not use a proxy by setting `NO_PROXY` to `.example.com`. By including the full name you can -exclude specific host names, so to make `www.example.com` not use a proxy but +exclude specific hostnames, so to make `www.example.com` not use a proxy but still have `foo.example.com` do it, set `NO_PROXY` to `www.example.com`. The usage of the `-x`/`--proxy` flag overrides the environment variables. @@ -845,7 +844,7 @@ Unix introduced the `.netrc` concept a long time ago. It is a way for a user to specify name and password for commonly visited FTP sites in a file so that you do not have to type them in each time you visit those sites. You realize this is a big security risk if someone else gets hold of your passwords, -therefore most Unix programs will not read this file unless it is only readable +therefore most Unix programs do not read this file unless it is only readable by yourself (curl does not care though). Curl supports `.netrc` files if told to (using the `-n`/`--netrc` and @@ -877,8 +876,8 @@ Then use curl in way similar to: curl --krb private ftp://krb4site.example.com -u username:fakepwd -There is no use for a password on the `-u` switch, but a blank one will make -curl ask for one and you already entered the real password to `kinit`/`kauth`. +There is no use for a password on the `-u` switch, but a blank one makes curl +ask for one and you already entered the real password to `kinit`/`kauth`. ## TELNET @@ -888,8 +887,8 @@ command line similar to: curl telnet://remote.example.com -And enter the data to pass to the server on stdin. The result will be sent to -stdout or to the file you specify with `-o`. +Enter the data to pass to the server on stdin. The result is sent to stdout or +to the file you specify with `-o`. You might want the `-N`/`--no-buffer` option to switch off the buffered output for slow connections or similar. @@ -911,20 +910,20 @@ accordingly. ## Persistent Connections -Specifying multiple files on a single command line will make curl transfer all -of them, one after the other in the specified order. +Specifying multiple files on a single command line makes curl transfer all of +them, one after the other in the specified order. -libcurl will attempt to use persistent connections for the transfers so that -the second transfer to the same host can use the same connection that was -already initiated and was left open in the previous transfer. This greatly -decreases connection time for all but the first transfer and it makes a far -better use of the network. +libcurl attempts to use persistent connections for the transfers so that the +second transfer to the same host can use the same connection that was already +initiated and was left open in the previous transfer. This greatly decreases +connection time for all but the first transfer and it makes a far better use +of the network. Note that curl cannot use persistent connections for transfers that are used in subsequent curl invokes. Try to stuff as many URLs as possible on the same -command line if they are using the same host, as that will make the transfers +command line if they are using the same host, as that makes the transfers faster. If you use an HTTP proxy for file transfers, practically all transfers -will be persistent. +are persistent. ## Multiple Transfers With A Single Command Line @@ -945,11 +944,10 @@ You can also upload multiple files in a similar fashion: ## IPv6 -curl will connect to a server with IPv6 when a host lookup returns an IPv6 -address and fall back to IPv4 if the connection fails. The `--ipv4` and -`--ipv6` options can specify which address to use when both are -available. IPv6 addresses can also be specified directly in URLs using the -syntax: +curl connects to a server with IPv6 when a host lookup returns an IPv6 address +and fall back to IPv4 if the connection fails. The `--ipv4` and `--ipv6` +options can specify which address to use when both are available. IPv6 +addresses can also be specified directly in URLs using the syntax: http://[2001:1890:1112:1::20]/overview.html diff --git a/docs/MQTT.md b/docs/MQTT.md index 660ff29a8ec..35c4e7699b8 100644 --- a/docs/MQTT.md +++ b/docs/MQTT.md @@ -24,4 +24,4 @@ Remaining limitations: - Only QoS level 0 is implemented for publish - No way to set retain flag for publish - No TLS (mqtts) support - - Naive EAGAIN handling will not handle split messages + - Naive EAGAIN handling does not handle split messages diff --git a/docs/Makefile.am b/docs/Makefile.am index 9190b441136..ca7b0833434 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -24,26 +24,25 @@ AUTOMAKE_OPTIONS = foreign no-dependencies -# EXTRA_DIST breaks with $(abs_builddir) so build it using this variable -# but distribute it (using the relative file name) in the next variable -man_MANS = $(abs_builddir)/curl.1 -noinst_man_MANS = curl.1 mk-ca-bundle.1 -dist_man_MANS = curl-config.1 -GENHTMLPAGES = curl.html curl-config.html mk-ca-bundle.html -PDFPAGES = curl.pdf curl-config.pdf mk-ca-bundle.pdf -MANDISTPAGES = curl.1.dist curl-config.1.dist +if BUILD_DOCS +# if we disable man page building, ignore these +MK_CA_DOCS = mk-ca-bundle.1 +CURLCONF_DOCS = curl-config.1 +endif -HTMLPAGES = $(GENHTMLPAGES) +man_MANS = curl-config.1 +CURLPAGES = curl-config.md mk-ca-bundle.md -# Build targets in this file (.) before cmdline-opts to ensure that -# the curl.1 rule below runs first -SUBDIRS = . cmdline-opts -DIST_SUBDIRS = $(SUBDIRS) examples libcurl +SUBDIRS = . cmdline-opts libcurl +DIST_SUBDIRS = $(SUBDIRS) examples -CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES) $(MANDISTPAGES) curl.1 +if BUILD_DOCS +CLEANFILES = mk-ca-bundle.1 curl-config.1 +endif EXTRA_DIST = \ - $(noinst_man_MANS) \ + $(CURLPAGES) \ + $(CURLCONF_DOCS) \ ALTSVC.md \ BINDINGS.md \ BUFREF.md \ @@ -55,10 +54,14 @@ EXTRA_DIST = \ CODE_OF_CONDUCT.md \ CODE_REVIEW.md \ CODE_STYLE.md \ + CLIENT-READERS.md \ + CLIENT-WRITERS.md \ CONNECTION-FILTERS.md \ CONTRIBUTE.md \ CURL-DISABLE.md \ + CURLDOWN.md \ DEPRECATE.md \ + DISTROS.md \ DYNBUF.md \ EARLY-RELEASE.md \ EXPERIMENTAL.md \ @@ -73,7 +76,7 @@ EXTRA_DIST = \ HTTP3.md \ HYPER.md \ INSTALL \ - INSTALL.cmake \ + INSTALL-CMAKE.md \ INSTALL.md \ INTERNALS.md \ KNOWN_BUGS \ @@ -87,6 +90,7 @@ EXTRA_DIST = \ RUSTLS.md \ ROADMAP.md \ SECURITY-ADVISORY.md \ + SPONSORS.md \ SSL-PROBLEMS.md \ SSLCERTS.md \ THANKS \ @@ -97,39 +101,23 @@ EXTRA_DIST = \ VULN-DISCLOSURE-POLICY.md \ WEBSOCKET.md -MAN2HTML= roffit $< >$@ +CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@ -SUFFIXES = .1 .html .pdf +CD2 = $(CD2_$(V)) +CD2_0 = @echo " RENDER " $@; +CD2_1 = +CD2_ = $(CD2_0) -# $(abs_builddir) is to disable VPATH when searching for this file, which -# would otherwise find the copy in $(srcdir) which breaks the $(HUGE) -# rule in src/Makefile.am in out-of-tree builds that references the file in the -# build directory. -# -# First, seed the used copy of curl.1 with the prebuilt copy (in an out-of-tree -# build), then run make recursively to rebuild it only if its dependencies -# have changed. -$(abs_builddir)/curl.1: - if test "$(top_builddir)x" != "$(top_srcdir)x" -a -e "$(srcdir)/curl.1"; then \ - $(INSTALL_DATA) "$(srcdir)/curl.1" $@ \ - && touch -r "$(srcdir)/curl.1" $@; fi - cd cmdline-opts && $(MAKE) +SUFFIXES = .1 .md -html: $(HTMLPAGES) - cd libcurl && $(MAKE) html +all: $(MK_CA_DOCS) -pdf: $(PDFPAGES) - cd libcurl && $(MAKE) pdf +.md.1: + $(CD2)$(CD2NROFF) -.1.html: - $(MAN2HTML) +curl-config.1: curl-config.md -.1.pdf: - @(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \ - groff -Tps -man $< >$$foo.ps; \ - ps2pdf $$foo.ps $@; \ - rm $$foo.ps; \ - echo "converted $< to $@") +mk-ca-bundle.1: mk-ca-bundle.md distclean: rm -f $(CLEANFILES) diff --git a/docs/NEW-PROTOCOL.md b/docs/NEW-PROTOCOL.md index a8b227d3c0b..b70caa9445f 100644 --- a/docs/NEW-PROTOCOL.md +++ b/docs/NEW-PROTOCOL.md @@ -7,16 +7,16 @@ protocols and it is the Internet transfer machine for the world. In the curl project we love protocols and we love supporting many protocols and doing it well. -So how do you proceed to add a new protocol and what are the requirements? +How do you proceed to add a new protocol and what are the requirements? ## No fixed set of requirements This document is an attempt to describe things to consider. There is no checklist of the twenty-seven things you need to cross off. We view the entire -effort as a whole and then judge if it seems to be the right thing - for -now. The more things that look right, fit our patterns and are done in ways -that align with our thinking, the better are the chances that we will agree -that supporting this protocol is a grand idea. +effort as a whole and then judge if it seems to be the right thing - for now. +The more things that look right, fit our patterns and are done in ways that +align with our thinking, the better are the chances that we agree that +supporting this protocol is a grand idea. ## Mutual benefit is preferred @@ -93,18 +93,18 @@ protocol - but it might require a bit of an effort to make it happen. We cannot assume that users are particularly familiar with details and peculiarities of the protocol. It needs documentation. -Maybe it even needs some internal documentation so that the developers who -will try to debug something five years from now can figure out functionality a -little easier! +Maybe it even needs some internal documentation so that the developers who try +to debug something five years from now can figure out functionality a little +easier! The protocol specification itself should be freely available without requiring a non-disclosure agreement or similar. ## Do not compare -We are constantly raising the bar and we are constantly improving the -project. A lot of things we did in the past would not be acceptable if done -today. Therefore, you might be tempted to use shortcuts or "hacks" you can -spot other - existing - protocol implementations have used, but there is -nothing to gain from that. The bar has been raised. Former "cheats" will not be -tolerated anymore. +We are constantly raising the bar and we are constantly improving the project. +A lot of things we did in the past would not be acceptable if done today. +Therefore, you might be tempted to use shortcuts or "hacks" you can spot +other - existing - protocol implementations have used, but there is nothing to +gain from that. The bar has been raised. Former "cheats" may not tolerated +anymore. diff --git a/docs/PARALLEL-TRANSFERS.md b/docs/PARALLEL-TRANSFERS.md index 337fab5faaa..c086f14abab 100644 --- a/docs/PARALLEL-TRANSFERS.md +++ b/docs/PARALLEL-TRANSFERS.md @@ -5,9 +5,9 @@ parallel. ## -Z, --parallel -When this command line option is used, curl will perform the transfers given -to it at the same time. It will do up to `--parallel-max` concurrent -transfers, with a default value of 50. +When this command line option is used, curl performs the transfers given to it +at the same time. It does up to `--parallel-max` concurrent transfers, with a +default value of 50. ## Progress meter @@ -38,9 +38,9 @@ Example: ## Behavior differences Connections are shared fine between different easy handles, but the -"authentication contexts" are not. So for example doing HTTP Digest auth with -one handle for a particular transfer and then continue on with another handle -that reuses the same connection, the second handle cannot send the necessary +"authentication contexts" are not. For example doing HTTP Digest auth with one +handle for a particular transfer and then continue on with another handle that +reuses the same connection, the second handle cannot send the necessary Authorization header at once since the context is only kept in the original easy handle. diff --git a/docs/README.md b/docs/README.md index b72d8bc4548..59f4bd147be 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,9 +2,9 @@ # Documentation -you will find a mix of various documentation in this directory and -subdirectories, using several different formats. Some of them are not ideal -for reading directly in your browser. +You find a mix of various documentation in this directory and subdirectories, +using several different formats. Some of them are not ideal for reading +directly in your browser. If you would rather see the rendered version of the documentation, check out the curl website's [documentation section](https://curl.se/docs/) for diff --git a/docs/RELEASE-PROCEDURE.md b/docs/RELEASE-PROCEDURE.md index 0ce02fbbc7a..e48a4d28a22 100644 --- a/docs/RELEASE-PROCEDURE.md +++ b/docs/RELEASE-PROCEDURE.md @@ -17,9 +17,8 @@ in the source code repo the tag is GPG signed (using -s). - run `./maketgz 7.34.0` to build the release tarballs. It is important that - you run this on a machine with the correct set of autotools etc installed - as this is what then will be shipped and used by most users on \*nix like - systems. + you run this on a machine with the correct set of autotools etc installed as + this is what is shipped and used by most users on \*nix like systems. - push the git commits and the new tag @@ -107,11 +106,11 @@ Coming dates Based on the description above, here are some planned release dates (at the time of this writing): -- October 11, 2023 -- December 6, 2023 -- January 31, 2024 -- March 27, 2024 - May 22, 2024 - July 17, 2024 - September 11, 2024 - November 6, 2024 +- January 8, 2025 +- March 5, 2025 +- April 30, 2025 +- June 25, 2025 diff --git a/docs/RUSTLS.md b/docs/RUSTLS.md index 7a0d806b627..3515e166625 100644 --- a/docs/RUSTLS.md +++ b/docs/RUSTLS.md @@ -3,7 +3,7 @@ [Rustls is a TLS backend written in Rust](https://docs.rs/rustls/). Curl can be built to use it as an alternative to OpenSSL or other TLS backends. We use the [rustls-ffi C bindings](https://github.com/rustls/rustls-ffi/). This -version of curl depends on version v0.10.0 of rustls-ffi. +version of curl depends on version v0.12.0 of rustls-ffi. # Building with rustls @@ -12,7 +12,7 @@ First, [install Rust](https://rustup.rs/). Next, check out, build, and install the appropriate version of rustls-ffi: % cargo install cbindgen - % git clone https://github.com/rustls/rustls-ffi -b v0.10.0 + % git clone https://github.com/rustls/rustls-ffi -b v0.12.0 % cd rustls-ffi % make % make DESTDIR=${HOME}/rustls-ffi-built/ install diff --git a/docs/SECURITY-ADVISORY.md b/docs/SECURITY-ADVISORY.md index 0ddc38b90db..8d908a8ca54 100644 --- a/docs/SECURITY-ADVISORY.md +++ b/docs/SECURITY-ADVISORY.md @@ -35,7 +35,7 @@ The eleven fields for each CVE in `vuln.pm` are, in order: ### `Makefile` -The new CVE web page file name needs to be added in the `Makefile`'s `CVELIST` +The new CVE webpage filename needs to be added in the `Makefile`'s `CVELIST` macro. When the markdown is in place and the `Makefile` and `vuln.pm` are updated, @@ -48,8 +48,8 @@ The easy way is to start with a recent previously published advisory and just blank out old texts and save it using a new name. Save the subtitles and general layout. -Some details and metadata will be extracted from this document so it is -important to stick to the existing format. +Some details and metadata are extracted from this document so it is important +to stick to the existing format. The first list must be the title of the issue. diff --git a/docs/SPONSORS.md b/docs/SPONSORS.md new file mode 100644 index 00000000000..bec96809c45 --- /dev/null +++ b/docs/SPONSORS.md @@ -0,0 +1,41 @@ +# curl sponsors + +A sponsor is someone who donates money or resources to the curl project for no +specific service in return. + +curl accepts donations via [GitHub sponsors](https://github.com/sponsors/curl) +and [Open Collective](https://opencollective.com/curl). + +An even better way to contribute to the project might be to pay an engineer or +two to spend work hours on curl related tasks. + +We promise to use donated funds for things and activities that we believe are +beneficial for the project and its development. That includes but is not +limited to bug-bounties, developer conferences, infrastructure, development, +services and hardware. + +Recurring donations above a certain amount of money puts the sponsor at a +named sponsor level: **Silver**, **Gold**, **Platinum** or **Top**. + +Sponsors on a named level can provide their logo image and preferred URL and +get recognition on the curl website's [sponsor +page](https://curl.se/sponsors.html). + +- **Silver Sponsor** at least 100 USD/month +- **Gold Sponsor** at least 500 USD/month +- **Platinum Sponsor** at least 1000 USD/month +- **Top Sponsor** outstanding extra valuable help + +## Sponsor requirements + +A named level sponsor is entitled a logo and link on the curl website assuming +the company, brand and link are not deemed unsuitable. The curl team reserves +the right to make that decision at its own discretion. + +Sponsors may be denied a website presence for example if involved with drugs, +gambling, pornography, social media manipulation etc. + +## Past Sponsors + +Sponsors that stop paying are considered *Past Sponsors* and are not displayed +on the sponsor page anymore. We thank you for your contributions! diff --git a/docs/SSL-PROBLEMS.md b/docs/SSL-PROBLEMS.md index afe42506c69..86262222fa6 100644 --- a/docs/SSL-PROBLEMS.md +++ b/docs/SSL-PROBLEMS.md @@ -22,14 +22,14 @@ ## CA bundle missing intermediate certificates - When using said CA bundle to verify a server cert, you will experience + When using said CA bundle to verify a server cert, you may experience problems if your CA store does not contain the certificates for the intermediates if the server does not provide them. The TLS protocol mandates that the intermediate certificates are sent in the handshake, but as browsers have ways to survive or work around such - omissions, missing intermediates in TLS handshakes still happen that - browser-users will not notice. + omissions, missing intermediates in TLS handshakes still happen that browser + users do not notice. Browsers work around this problem in two ways: they cache intermediate certificates from previous transfers and some implement the TLS "AIA" diff --git a/docs/SSLCERTS.md b/docs/SSLCERTS.md index 4094e2fec64..caac51c42fc 100644 --- a/docs/SSLCERTS.md +++ b/docs/SSLCERTS.md @@ -71,11 +71,11 @@ server, do one of the following: certificates need to be stored as individual PEM files in this directory. You may need to run c_rehash after adding files there. - If neither of the two options is specified, configure will try to - auto-detect a setting. It's also possible to explicitly not set any - default store but rely on the built in default the crypto library may - provide instead. You can achieve that by passing both - `--without-ca-bundle` and `--without-ca-path` to the configure script. + If neither of the two options is specified, configure tries to auto-detect + a setting. It's also possible to explicitly not set any default store but + rely on the built in default the crypto library may provide instead. You + can achieve that by passing both `--without-ca-bundle` and + `--without-ca-path` to the configure script. If you use Internet Explorer, this is one way to get extract the CA cert for a particular server: @@ -94,8 +94,7 @@ server, do one of the following: - `openssl s_client -showcerts -servername server -connect server:443 > cacert.pem` - type "quit", followed by the "ENTER" key - - The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE" - markers. + - The certificate has `BEGIN CERTIFICATE` and `END CERTIFICATE` markers. - If you want to see the data in the certificate, you can do: `openssl x509 -inform PEM -in certfile -text -out certdata` where `certfile` is the cert you extracted from logfile. Look in `certdata`. @@ -103,46 +102,46 @@ server, do one of the following: certificate store or use it stand-alone as described. Just remember that the security is no better than the way you obtained the certificate. - 4. If you are using the curl command line tool, you can specify your own CA - cert file by setting the environment variable `CURL_CA_BUNDLE` to the path - of your choice. + 4. If you are using the curl command line tool and the TLS backend is not + Schannel then you can specify your own CA cert file by setting the + environment variable `CURL_CA_BUNDLE` to the path of your choice. - If you are using the curl command line tool on Windows, curl will search - for a CA cert file named "curl-ca-bundle.crt" in these directories and in - this order: + If you are using the curl command line tool on Windows, curl searches for + a CA cert file named "curl-ca-bundle.crt" in these directories and in this + order: 1. application's directory 2. current working directory 3. Windows System directory (e.g. C:\windows\system32) 4. Windows Directory (e.g. C:\windows) 5. all directories along %PATH% - 5. Get a better/different/newer CA cert bundle! One option is to extract the - one a recent Firefox browser uses by running 'make ca-bundle' in the curl - build tree root, or possibly download a version that was generated this - way for you: [CA Extract](https://curl.se/docs/caextract.html) + 5. Get another CA cert bundle. One option is to extract the one a recent + Firefox browser uses by running 'make ca-bundle' in the curl build tree + root, or possibly download a version that was generated this way for you: + [CA Extract](https://curl.se/docs/caextract.html) Neglecting to use one of the above methods when dealing with a server using a certificate that is not signed by one of the certificates in the installed CA -certificate store, will cause SSL to report an error ("certificate verify -failed") during the handshake and SSL will then refuse further communication -with that server. +certificate store, causes SSL to report an error (`certificate verify failed`) +during the handshake and SSL then refuses further communication with that +server. Certificate Verification with Schannel and Secure Transport ----------------------------------------------------------- If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure -Transport (Apple's native TLS engine) support, then libcurl will still perform -peer certificate verification, but instead of using a CA cert bundle, it will -use the certificates that are built into the OS. These are the same -certificates that appear in the Internet Options control panel (under Windows) -or Keychain Access application (under OS X). Any custom security rules for -certificates will be honored. - -Schannel will run CRL checks on certificates unless peer verification is -disabled. Secure Transport on iOS will run OCSP checks on certificates unless -peer verification is disabled. Secure Transport on OS X will run either OCSP -or CRL checks on certificates if those features are enabled, and this behavior -can be adjusted in the preferences of Keychain Access. +Transport (Apple's native TLS engine) support, then libcurl still performs +peer certificate verification, but instead of using a CA cert bundle, it uses +the certificates that are built into the OS. These are the same certificates +that appear in the Internet Options control panel (under Windows) or Keychain +Access application (under OS X). Any custom security rules for certificates +are honored. + +Schannel runs CRL checks on certificates unless peer verification is disabled. +Secure Transport on iOS runs OCSP checks on certificates unless peer +verification is disabled. Secure Transport on OS X runs either OCSP or CRL +checks on certificates if those features are enabled, and this behavior can be +adjusted in the preferences of Keychain Access. HTTPS proxy ----------- diff --git a/docs/THANKS b/docs/THANKS index 88d924f63b3..8bd6b3d8630 100644 --- a/docs/THANKS +++ b/docs/THANKS @@ -11,6 +11,7 @@ 1ocalhost on github 3dyd on github 3eka on github +5533asdg on github 8U61ife on github a1346054 on github Aaro Koskinen @@ -47,11 +48,13 @@ ahodesuka on github ajak in #curl Ajit Dhumale Akhil Kedia +Akhilesh Nema Aki Koskinen Akos Pasztory Akshay Vernekar Alain Danteny Alain Miniussi +Alan Coopersmith Alan Jenkins Alan Pinstein Albert Chin-A-Young @@ -92,6 +95,7 @@ Alex Samorukov Alex Suykov Alex Vinnik Alex Xu +Alexander Bartel Alexander Beedie Alexander Chuykov Alexander Dyagilev @@ -154,6 +158,7 @@ Andreas Falkenhahn Andreas Farber Andreas Fischer Andreas Huebner +Andreas Kiefer Andreas Kostyrka Andreas Malzahn Andreas Ntaflos @@ -185,6 +190,7 @@ Andrew de los Reyes Andrew Francis Andrew Fuller Andrew Ishchuk +Andrew Kaster Andrew Krieger Andrew Kurushin Andrew Lambert @@ -206,6 +212,7 @@ Andy Stamp Andy Tsouladze Angus Mackay anio on github +annalee anon00000000 on github anshnd on github Anssi Kolehmainen @@ -236,6 +243,7 @@ apparentorder on github April King arainchik on github Archangel_SDY on github +Arjan van de Ven Arkadiusz Miskiewicz Armel Asselin Arnaud Compan @@ -260,7 +268,9 @@ Ates Goral atjg on github Augustus Saunders Austin Green +av223119 on github Avery Fay +awesomekosm on github awesomenode on github Axel Chong Axel Morawietz @@ -290,6 +300,7 @@ Basuke Suzuki baumanj on github bdry on github beckenc on github +Ben Ben Boeckel Ben Darnell Ben Fritz @@ -373,13 +384,16 @@ Brandon Dong Brandon Wang BratSinot on github Brendan Jurd +Brennan Kinney Brent Beardsley +Brett Buddin Brian Akins Brian Bergeron Brian Carpenter Brian Chaplin Brian Childs Brian Chrisman +Brian Clemens Brian Dessent Brian E. Gallew Brian Green @@ -404,11 +418,13 @@ Bryan Henderson Bryan Kemp bsammon on github bsergean on github +bubbleguuum on github Bubu on github buzo-ffm on github bxac on github Bylon2 on github Byrial Jensen +Cajus Pollmeier Caleb Raitto Calvin Buckley calvin2021y on github @@ -441,11 +457,13 @@ Cering on github Cesar Eduardo Barros Chad Monroe Chandrakant Bagul +Chara White Charles Cazabon Charles Kerr Charles Romestant Charlie C Chen Prog +chensong1211 on github Cherish98 on github Chester Liu Chih-Chung Chang @@ -465,8 +483,10 @@ Chris Maltby Chris Mumford Chris Paulson-Ellis Chris Roberts +Chris Sauer Chris Smowton Chris Talbot +Chris Webb Chris Young Christian Fillion Christian Grothoff @@ -494,6 +514,7 @@ Christopher R. Palmer Christopher Reid Christopher Sauer Christopher Stone +chrysos349 on github Chungtsun Li Ciprian Badescu civodul on github @@ -567,6 +588,7 @@ Dan Fandrich Dan Johnson Dan Kenigsberg Dan Locks +Dan McDonald Dan McNulty Dan Nelson Dan Petitt @@ -600,6 +622,7 @@ Daniel Shahaf Daniel Silverstone Daniel Steinberg Daniel Stenberg +Daniel Szmulewicz Daniel Theron Daniel Valenzuela Daniel Woelfel @@ -610,6 +633,7 @@ Darryl House Darshan Mody Darío Hereñú dasimx on github +DasKutti on github Dave Cottlehuber Dave Dribin Dave Halbakken @@ -686,6 +710,8 @@ Derzsi Dániel Desmond O. Chang destman on github Detlef Schmier +Dexter Gerig +dfdity on github Dheeraj Sangamkar Didier Brisebourg Diego Bes @@ -705,6 +731,7 @@ Diogo Teles Sant'Anna Dion Williams Dirk Eddelbuettel Dirk Feytons +Dirk Hünniger Dirk Manske Dirk Rosenkranz Dirk Wetter @@ -729,6 +756,7 @@ Dmitry Mikhirev Dmitry Popov Dmitry Rechkin Dmitry S. Baikov +Dmitry Tretyakov Dmitry Wagin dnivras on github Dolbneff A.V @@ -779,6 +807,7 @@ ed0d2b2ce19451f2 Eddie Lumpkin Edgaras Janušauskas Edin Kadribasic +edmcln on github Edmond Yu Edoardo Lolletti Eduard Bloch @@ -851,6 +880,7 @@ Erik Janssen Erik Johansson Erik Minekus Erik Olsson +Erik Schnetter Erik Stenlund Ernest Beinrohr Ernst Sjöstrand @@ -875,6 +905,7 @@ Fabian Frank Fabian Hiernaux Fabian Keil Fabian Ruff +Fabian Vogt Fabian Yamaguchi Fabrice Fontaine Fabrizio Ammollo @@ -943,10 +974,12 @@ FuccDucc on github Fujii Hironori fullincome on github fundawang on github +Gabe Gabriel Corona Gabriel Kuri Gabriel Simmer Gabriel Sjoberg +Gaelan Steele Gambit Communications Ganesh Kamath gaoxingwang on github @@ -1008,6 +1041,7 @@ Gou Lingfeng Graham Campbell Grant Erickson Grant Pannell +graywolf on github Greg Hewgill Greg Morse Greg Onufer @@ -1055,6 +1089,7 @@ Hannes Magnusson Hanno Böck Hanno Kranzhoff Hans Steegers +Hans-Christian Egtvedt Hans-Christian Noren Egtvedt Hans-Jurgen May Hao Wu @@ -1066,6 +1101,7 @@ Harry Sarson Harry Sintonen Harshal Pradhan Hauke Duden +Haydar Alaidrus Hayden Roche He Qin Heikki Korpela @@ -1084,6 +1120,7 @@ Henry Ludemann Henry Roeland Herve Amblard HexTheDragon +hgdagon on github Hide Ishikawa Hidemoto Nakada highmtworks on github @@ -1098,6 +1135,7 @@ Hongyi Zhao Howard Blaise Howard Chu hsiao yi +HsiehYuho on github htasta on github Hubert Kario Hugh Macdonald @@ -1117,6 +1155,7 @@ Ian Lynagh Ian Spence Ian Turner Ian Wilkes +iAroc on github iconoclasthero icy17 on github Ignacio Vazquez-Abrams @@ -1155,6 +1194,7 @@ Ishan SinghLevett Ithubg on github Ivan Avdeev Ivan Tsybulin +ivanfywang IvanoG on github Ivo Bellin Salarin iz8mbw on github @@ -1214,6 +1254,7 @@ Jan Venekamp Jan Verbeek Jan-Piet Mens JanB on github +janko-js on github Janne Blomqvist Janne Johansson Jared Jennings @@ -1235,6 +1276,7 @@ Javier Navarro Javier Sixto Jay Austin Jay Dommaschk +Jay Wu Jayesh A Shah Jaz Fresh JazJas on github @@ -1289,11 +1331,13 @@ Jerry Krinock Jerry Wu Jes Badwal Jesper Jensen +Jess Lowe Jesse Chisholm Jesse Noller Jesse Tan jethrogb on github jhoyla on github +Jiawen Geng Jie He Jiehong on github Jilayne Lovejoy @@ -1309,6 +1353,7 @@ Jiri Dvorak Jiri Hruska Jiri Jaburek Jishan Shaikh +Jiří Bok Jiří Malák jmdavitt on github jnbr on github @@ -1398,6 +1443,7 @@ Jonathan Cardoso Machado Jonathan Hseu Jonathan Moerman Jonathan Nieder +Jonathan Perkin Jonathan Watt Jonathan Wernberg Jongki Suwandi @@ -1518,6 +1564,7 @@ Kev Jackson Kevin Adler Kevin Baughman Kevin Burke +Kevin Daudt Kevin Fisk Kevin Ji Kevin Lussier @@ -1545,10 +1592,12 @@ Koichi Shiraishi kokke on github Konstantin Isakov Konstantin Kushnir +Konstantin Vlasov KotlinIsland on github kotoriのねこ kouzhudong on github Kovalkov Dmitrii +kpcyrd kreshano on github Kris Kennaway Krishnendu Majumdar @@ -1588,6 +1637,7 @@ Lars Francke Lars Gustafsson Lars J. Aas Lars Johannesen +Lars Kellogg-Stedman Lars Nilsson Lars Torben Wilson Lau @@ -1600,7 +1650,9 @@ Lawrence Gripper Lawrence Matthews Lawrence Wagerfield Leah Neukirchen +Lealem Amedie Leandro Coutinho +LeeRiva Legoff Vincent Lehel Bernadt Leif W @@ -1623,6 +1675,7 @@ LigH-de on github lijian996 on github Lijo Antony lilongyan-huawei on github +Lin Sun Linas Vepstas Lindley French Ling Thio @@ -1646,6 +1699,7 @@ Loic Dachary LoRd_MuldeR Loren Kirkby Lorenzo Miniero +Louis Solofrizzo Loïc Yhuel lRoccoon on github Luan Cestari @@ -1670,6 +1724,7 @@ Luke Amery Luke Call Luke Dashjr Luke Granger-Brown +Lukáš Zaoral luminixinc on github Luo Jinghua Luong Dinh Dung @@ -1726,6 +1781,7 @@ Marco Maggi Marcos Diazr Marcus Hoffmann Marcus Klein +Marcus Müller Marcus Sundberg Marcus T Marcus Webster @@ -1739,6 +1795,7 @@ Mark Davies Mark Dodgson Mark Gaiser Mark Hamilton +Mark Huang Mark Incley Mark Itzcovitz Mark Karpeles @@ -1747,6 +1804,7 @@ Mark Nottingham Mark Roszko Mark Salisbury Mark Seuffert +Mark Sinkovics Mark Snelling Mark Swaanenburg Mark Tully @@ -1835,6 +1893,7 @@ Matthias Naegler Mattias Fornander Matus Uzak Maurice Barnum +Mauricio Scheffer Mauro Iorio Mauro Rappa Maurício Meneghini Fauth @@ -1958,6 +2017,7 @@ Mohamed Lrhazi Mohamed Osama Mohammad AlSaleh Mohammad Hasbini +Mohammadreza Hendiani Mohammed Naser Mohun Biswas momala454 on github @@ -2036,6 +2096,7 @@ Nicolás Ojeda Bär Niels Martignène Niels van Tongeren Nikita Schmidt +Nikita Taranov Nikitinskit Dmitriy Niklas Angebrand Niklas Hambüchen @@ -2108,7 +2169,9 @@ Oscar Norlander Oskar Liljeblad Oskar Sigvardsson Oumph on github +Outvi V ovidiu-benea on github +Ozan Cansel P R Schaffner Pablo Busse Palo Markovic @@ -2173,6 +2236,7 @@ Pawel A. Gajda Pawel Kierski Paweł Kowalski Paweł Wegner +Paweł Witas PBudmark on github Pedro Henrique Pedro Larroy @@ -2194,6 +2258,7 @@ Peter Goodman Peter Heuchert Peter Hjalmarsson Peter Korsgaard +Peter Krefting Peter Körner Peter Lamare Peter Lamberg @@ -2261,12 +2326,14 @@ Prithvi MK privetryan on github Priyanka Shah ProceduralMan on github +promptfuzz_ on hackerone Pronyushkin Petr Przemysław Tomaszewski pszemus on github pszlazak on github puckipedia on github Puneet Pawaia +Pēteris Caune qiandu2006 on github Quagmire Quanah Gibson-Mount @@ -2289,6 +2356,7 @@ Rainer Canavan Rainer Jung Rainer Koenig Rainer Müller +RainRat Raito Bezarius Rajesh Naganathan Rajkumar Mandal @@ -2297,6 +2365,7 @@ Ralph Beckmann Ralph Langendam Ralph Mitchell Ram Krushna Mishra +Ramiro Garcia ramsay-jones on github Ran Mozes RanBarLavie on github @@ -2330,6 +2399,7 @@ Renaud Lehoux Rene Bernhardt Rene Rebe Reuven Wachtfogel +RevaliQaQ on github Reza Arbab Rianov Viacheslav Ricardo Cadime @@ -2355,6 +2425,7 @@ Richard Gorton Richard Gray Richard Hosking Richard Hsu +Richard Levitte Richard Marion Richard Michael Richard Moore @@ -2400,6 +2471,7 @@ Robert Foreman Robert Iakobashvili Robert Kolcun Robert Linden +Robert Moreton Robert Olson Robert Prag Robert Ronto @@ -2448,6 +2520,7 @@ roughtex on github Roy Bellingan Roy Li Roy Shan +Rudi Heitbaum Rui LIU Rui Pinheiro Rune Kleveland @@ -2460,6 +2533,7 @@ RuurdBeerstra on github rwmjones on github Ryan Beck-Buysse Ryan Braud +Ryan Carsten Schmidt Ryan Chan Ryan Mast Ryan Nelson @@ -2511,11 +2585,14 @@ Saul good Saurav Babu sayrer on github SBKarr on github +Scarlett McAllister Scott Bailey Scott Barrett Scott Cantor Scott Davis Scott McCreary +Scott Mutter +Scott Talbert sd0 on hackerone Sean Boudreau Sean Burford @@ -2526,6 +2603,7 @@ Sean Molenaar Sebastiaan van Erk Sebastian Haglund Sebastian Mundry +Sebastian Neubauer Sebastian Pohlschmidt Sebastian Rasmussen Sebastian Sterk @@ -2556,6 +2634,7 @@ SerusDev on github Seshubabu Pasam Seth Mos Sevan Janiyan +sfan5 on github Sgharat on github Sh Diao Shachaf Ben-Kiki @@ -2588,6 +2667,7 @@ Simon Chalifoux Simon Dick Simon H. Simon Josefsson +Simon K Simon Legner Simon Liu Simon Warta @@ -2701,10 +2781,12 @@ T200proX7 on github Tadej Vengust Tae Hyoung Ahn Taiyu Len +Tal Regev Taneli Vähäkangas Tanguy Fautre Taras Kushnir tarek112 on github +Tatsuhiko Miyagawa Tatsuhiro Tsujikawa tawmoto on github tbugfinder on github @@ -2717,6 +2799,7 @@ thanhchungbtc on github The Infinnovation team TheAssassin on github TheKnarf on github +Theo Theodore Dubois therealhirudo on github Thiago Suchorski @@ -2724,6 +2807,7 @@ tholin on github Thomas Bouzerar Thomas Braun Thomas Danielsson +Thomas Ferguson Thomas Gamper Thomas Glanzmann Thomas Guillem @@ -2733,6 +2817,7 @@ Thomas L. Shinnick Thomas Lopatic Thomas M. DuBuisson Thomas Petazzoni +Thomas Pyle Thomas Ruecker Thomas Schwinge Thomas Taylor @@ -2745,6 +2830,7 @@ Thorsten Klein Thorsten Schöning Tiit Pikma Till Maas +Till Wegmüller Tim Ansell Tim Baker Tim Bartley @@ -2915,6 +3001,7 @@ Vojtěch Král Volker Schmid Vsevolod Novikov vshmuk on hackerone +vulnerabilityspotter on hackerone vvb2060 vvb2060 on github Vyron Tsingaras @@ -2948,6 +3035,7 @@ William A. Rowe Jr William Ahern William Desportes William Tang +Winni Neessen wmsch on github wncboy on github Wojciech Zwiefka @@ -2961,6 +3049,7 @@ x2018 on github Xavier Bouchoux XhmikosR on github XhstormR on github +Xi Ruoyao Xiang Xiao Xiangbin Li xianghongai on github @@ -2972,6 +3061,7 @@ xtonik on github xwxbug on github Xì Gà Yaakov Selkowitz +Yadhu Krishna M Yair Lenga Yang Tse Yaobin Wen @@ -2979,10 +3069,12 @@ Yarram Sunil Yasuharu Yamada Yasuhiro Matsumoto Yechiel Kalmenson +Yedaya Katsman Yehezkel Horowitz Yehoshua Hershberg ygthien on github Yi Huang +Yifei Kong Yiming Jing Yingwei Liu yiyuaner on github @@ -3010,6 +3102,8 @@ Zachary Seguin Zdenek Pavlas Zekun Ni zelinchen on github +zengwei +zengwei2000 Zenju on github Zero King Zespre Schmidt diff --git a/docs/TODO b/docs/TODO index 06162c8bb64..159e2e87535 100644 --- a/docs/TODO +++ b/docs/TODO @@ -20,7 +20,7 @@ 1.1 TFO support on Windows 1.2 Consult %APPDATA% also for .netrc 1.3 struct lifreq - 1.4 alt-svc sharing + 1.4 Better and more sharing 1.5 get rid of PATH_MAX 1.6 native IDN support on macOS 1.8 CURLOPT_RESOLVE for any port number @@ -126,6 +126,7 @@ 13.12 Reduce CA certificate bundle reparsing 13.13 Make sure we forbid TLS 1.3 post-handshake authentication 13.14 Support the clienthello extension + 13.15 Select signature algorithms 14. GnuTLS 14.2 check connection @@ -176,7 +177,6 @@ 18.29 --retry and transfer timeouts 19. Build - 19.1 roffit 19.2 Enable PIE and RELRO by default 19.3 Do not use GNU libtool on OpenBSD 19.4 Package curl for Windows in a signed installer @@ -196,6 +196,9 @@ 21. MQTT 21.1 Support rate-limiting + 22. TFTP + 22.1 TFTP doesn't convert LF to CRLF for mode=netascii + ============================================================================== 1. libcurl @@ -889,7 +892,9 @@ Some TLS related options to the command line tool and libcurl are only provided for the server and not for HTTPS proxies. --proxy-tls-max, - --proxy-tlsv1.3, --proxy-curves and a few more.a + --proxy-tlsv1.3, --proxy-curves and a few more. + For more Documentation on this see: + https://curl.se/libcurl/c/tls-options.html https://github.com/curl/curl/issues/12286 @@ -919,6 +924,14 @@ https://datatracker.ietf.org/doc/html/rfc7685 https://github.com/curl/curl/issues/2299 +13.15 Select signature algorithms + + Consider adding an option or a way for users to select TLS signature + algorithm. The signature algorithms set by a client are used directly in the + supported signature algorithm in the client hello message. + + https://github.com/curl/curl/issues/12982 + 14. GnuTLS 14.2 check connection @@ -1113,7 +1126,7 @@ slow, potentially with a (random) wait between transfers. There is also a proposed set of standard HTTP headers to let servers let the client adapt to its rate limits: - https://www.ietf.org/id/draft-polli-ratelimit-headers-02.html + https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/ See https://github.com/curl/curl/issues/5406 @@ -1277,14 +1290,8 @@ https://qa.mandriva.com/show_bug.cgi?id=22565 - 19. Build -19.1 roffit - - Consider extending 'roffit' to produce decent ASCII output, and use that - instead of (g)nroff when building src/tool_hugehelp.c - 19.2 Enable PIE and RELRO by default Especially when having programs that execute curl via the command line, PIE @@ -1392,3 +1399,14 @@ The rate-limiting logic is done in the PERFORMING state in multi.c but MQTT is not (yet) implemented to use that. + +22. TFTP + +22.1 TFTP doesn't convert LF to CRLF for mode=netascii + + RFC 3617 defines that an TFTP transfer can be done using "netascii" + mode. curl does not support extracting that mode from the URL nor does it treat + such transfers specifically. It should probably do LF to CRLF translations + for them. + + See https://github.com/curl/curl/issues/12655 diff --git a/docs/TheArtOfHttpScripting.md b/docs/TheArtOfHttpScripting.md index 43f13e2afbd..4e111a3e3d0 100644 --- a/docs/TheArtOfHttpScripting.md +++ b/docs/TheArtOfHttpScripting.md @@ -10,10 +10,9 @@ web servers are all important tasks today. Curl is a command line tool for doing all sorts of URL manipulations and - transfers, but this particular document will focus on how to use it when - doing HTTP requests for fun and profit. This documents assumes that you know - how to invoke `curl --help` or `curl --manual` to get basic information about - it. + transfers, but this particular document focuses on how to use it when doing + HTTP requests for fun and profit. This documents assumes that you know how to + invoke `curl --help` or `curl --manual` to get basic information about it. Curl is not written to do everything for you. It makes the requests, it gets the data, it sends data and it retrieves the information. You probably need @@ -24,8 +23,8 @@ HTTP is the protocol used to fetch data from web servers. It is a simple protocol that is built upon TCP/IP. The protocol also allows information to - get sent to the server from the client using a few different methods, as will - be shown here. + get sent to the server from the client using a few different methods, as is + shown here. HTTP is plain ASCII text lines being sent by the client to a server to request a particular action, and then the server replies a few text lines @@ -39,9 +38,9 @@ ## See the Protocol - Using curl's option [`--verbose`](https://curl.se/docs/manpage.html#-v) - (`-v` as a short option) will display what kind of commands curl sends to the - server, as well as a few other informational texts. + Using curl's option [`--verbose`](https://curl.se/docs/manpage.html#-v) (`-v` + as a short option) displays what kind of commands curl sends to the server, + as well as a few other informational texts. `--verbose` is the single most useful option when it comes to debug or even understand the curl<->server interaction. @@ -59,19 +58,19 @@ Many times you may wonder what exactly is taking all the time, or you just want to know the amount of milliseconds between two points in a transfer. For those, and other similar situations, the - [`--trace-time`](https://curl.se/docs/manpage.html#--trace-time) option - is what you need. It will prepend the time to each trace output line: + [`--trace-time`](https://curl.se/docs/manpage.html#--trace-time) option is + what you need. It prepends the time to each trace output line: curl --trace-ascii d.txt --trace-time http://example.com/ ## See which Transfer - When doing parallel transfers, it is relevant to see which transfer is - doing what. When response headers are received (and logged) you need to - know which transfer these are for. - [`--trace-ids`](https://curl.se/docs/manpage.html#--trace-ids) option - is what you need. It will prepend the transfer and connection identifier - to each trace output line: + When doing parallel transfers, it is relevant to see which transfer is doing + what. When response headers are received (and logged) you need to know which + transfer these are for. + [`--trace-ids`](https://curl.se/docs/manpage.html#--trace-ids) option is what + you need. It prepends the transfer and connection identifier to each trace + output line: curl --trace-ascii d.txt --trace-ids http://example.com/ @@ -87,16 +86,16 @@ The Uniform Resource Locator format is how you specify the address of a particular resource on the Internet. You know these, you have seen URLs like https://curl.se or https://example.com a million times. RFC 3986 is the - canonical spec. And yeah, the formal name is not URL, it is URI. + canonical spec. The formal name is not URL, it is **URI**. ## Host - The host name is usually resolved using DNS or your /etc/hosts file to an IP - address and that is what curl will communicate with. Alternatively you specify + The hostname is usually resolved using DNS or your /etc/hosts file to an IP + address and that is what curl communicates with. Alternatively you specify the IP address directly in the URL instead of a name. For development and other trying out situations, you can point to a different - IP address for a host name than what would otherwise be used, by using curl's + IP address for a hostname than what would otherwise be used, by using curl's [`--resolve`](https://curl.se/docs/manpage.html#--resolve) option: curl --resolve www.example.org:80:127.0.0.1 http://www.example.org/ @@ -107,7 +106,7 @@ or in some cases UDP. Normally you do not have to take that into consideration, but at times you run test servers on other ports or similar. Then you can specify the port number in the URL with a colon and a - number immediately following the host name. Like when doing HTTP to port + number immediately following the hostname. Like when doing HTTP to port 1234: curl http://www.example.org:1234/ @@ -119,7 +118,7 @@ curl --proxy http://proxy.example.org:4321 http://remote.example.org/ -## User name and password +## Username and password Some services are setup to require HTTP authentication and then you need to provide name and password which is then transferred to the remote site in @@ -142,20 +141,20 @@ The path part is just sent off to the server to request that it sends back the associated response. The path is what is to the right side of the slash - that follows the host name and possibly port number. + that follows the hostname and possibly port number. # Fetch a page ## GET The simplest and most common request/operation made using HTTP is to GET a - URL. The URL could itself refer to a web page, an image or a file. The client + URL. The URL could itself refer to a webpage, an image or a file. The client issues a GET request to the server and receives the document it asked for. If you issue the command line curl https://curl.se - you get a web page returned in your terminal window. The entire HTML document + you get a webpage returned in your terminal window. The entire HTML document that that URL holds. All HTTP replies contain a set of response headers that are normally hidden, @@ -165,9 +164,9 @@ ## HEAD You can ask the remote server for ONLY the headers by using the - [`--head`](https://curl.se/docs/manpage.html#-I) (`-I`) option which - will make curl issue a HEAD request. In some special cases servers deny the - HEAD method while others still work, which is a particular kind of annoyance. + [`--head`](https://curl.se/docs/manpage.html#-I) (`-I`) option which makes + curl issue a HEAD request. In some special cases servers deny the HEAD method + while others still work, which is a particular kind of annoyance. The HEAD method is defined and made so that the server returns the headers exactly the way it would do for a GET, but without a body. It means that you @@ -177,9 +176,9 @@ ## Multiple URLs in a single command line A single curl command line may involve one or many URLs. The most common case - is probably to just use one, but you can specify any amount of URLs. Yes - any. No limits. You will then get requests repeated over and over for all the - given URLs. + is probably to just use one, but you can specify any amount of URLs. Yes any. + No limits. You then get requests repeated over and over for all the given + URLs. Example, send two GET requests: @@ -197,14 +196,14 @@ ## Multiple HTTP methods in a single command line Sometimes you need to operate on several URLs in a single command line and do - different HTTP methods on each. For this, you will enjoy the - [`--next`](https://curl.se/docs/manpage.html#-:) option. It is basically - a separator that separates a bunch of options from the next. All the URLs - before `--next` will get the same method and will get all the POST data - merged into one. + different HTTP methods on each. For this, you might enjoy the + [`--next`](https://curl.se/docs/manpage.html#-:) option. It is basically a + separator that separates a bunch of options from the next. All the URLs + before `--next` get the same method and get all the POST data merged into + one. - When curl reaches the `--next` on the command line, it will sort of reset the - method and the POST data and allow a new set. + When curl reaches the `--next` on the command line, it resets the method and + the POST data and allow a new set. Perhaps this is best shown with a few examples. To send first a HEAD and then a GET: @@ -241,14 +240,14 @@ ``` - In your favorite browser, this form will appear with a text box to fill in - and a press-button labeled "OK". If you fill in '1905' and press the OK - button, your browser will then create a new URL to get for you. The URL will - get `junk.cgi?birthyear=1905&press=OK` appended to the path part of the - previous URL. + In your favorite browser, this form appears with a text box to fill in and a + press-button labeled "OK". If you fill in '1905' and press the OK button, + your browser then creates a new URL to get for you. The URL gets + `junk.cgi?birthyear=1905&press=OK` appended to the path part of the previous + URL. If the original form was seen on the page `www.example.com/when/birth.html`, - the second page you will get will become + the second page you get becomes `www.example.com/when/junk.cgi?birthyear=1905&press=OK`. Most search engines work this way. @@ -267,7 +266,7 @@ amount of fields creating a long and unreadable URL. The HTTP protocol then offers the POST method. This way the client sends the - data separated from the URL and thus you will not see any of it in the URL + data separated from the URL and thus you do not see any of it in the URL address field. The form would look similar to the previous one: @@ -284,21 +283,20 @@ curl --data "birthyear=1905&press=%20OK%20" http://www.example.com/when/junk.cgi - This kind of POST will use the Content-Type - `application/x-www-form-urlencoded` and is the most widely used POST kind. + This kind of POST uses the Content-Type `application/x-www-form-urlencoded` + and is the most widely used POST kind. - The data you send to the server MUST already be properly encoded, curl will + The data you send to the server MUST already be properly encoded, curl does not do that for you. For example, if you want the data to contain a space, - you need to replace that space with `%20`, etc. Failing to comply with this will - most likely cause your data to be received wrongly and messed up. + you need to replace that space with `%20`, etc. Failing to comply with this + most likely causes your data to be received wrongly and messed up. Recent curl versions can in fact url-encode POST data for you, like this: curl --data-urlencode "name=I am Daniel" http://www.example.com - If you repeat `--data` several times on the command line, curl will - concatenate all the given data pieces - and put a `&` symbol between each - data segment. + If you repeat `--data` several times on the command line, curl concatenates + all the given data pieces - and put a `&` symbol between each data segment. ## File Upload POST @@ -309,12 +307,10 @@ This method is mainly designed to better support file uploads. A form that allows a user to upload a file could be written like this in HTML: -```html -
- - -
-``` +
+ + +
This clearly shows that the Content-Type about to be sent is `multipart/form-data`. @@ -341,7 +337,7 @@ ``` - To POST this with curl, you will not have to think about if the fields are + To POST this with curl, you do not have to think about if the fields are hidden or not. To curl they are all the same: curl --data "birthyear=1905&press=OK&person=daniel" [URL] @@ -356,7 +352,7 @@ your local disk, modify the 'method' to a GET, and press the submit button (you could also change the action URL if you want to). - You will then clearly see the data get appended to the URL, separated with a + You then clearly see the data get appended to the URL, separated with a `?`-letter as GET forms are supposed to. # HTTP upload @@ -411,7 +407,7 @@ [`--proxy-digest`](https://curl.se/docs/manpage.html#--proxy-digest). If you use any one of these user+password options but leave out the password - part, curl will prompt for the password interactively. + part, curl prompts for the password interactively. ## Hiding credentials @@ -421,7 +417,7 @@ options. There are ways to circumvent this. It is worth noting that while this is how HTTP Authentication works, many - websites will not use this concept when they provide logins etc. See the Web + websites do not use this concept when they provide logins etc. See the Web Login chapter further below for more details on that. # More HTTP Headers @@ -449,10 +445,10 @@ make them look the best possible for their particular browsers. They usually also do different kinds of JavaScript etc. - At times, you will see that getting a page with curl will not return the same - page that you see when getting the page with your browser. Then you know it - is time to set the User Agent field to fool the server into thinking you are - one of those browsers. + At times, you may learn that getting a page with curl does not return the + same page that you see when getting the page with your browser. Then you know + it is time to set the User Agent field to fool the server into thinking you + are one of those browsers. To make curl look like Internet Explorer 5 on a Windows 2000 box: @@ -471,20 +467,18 @@ new page keeping newly generated output. The header that tells the browser to redirect is `Location:`. - Curl does not follow `Location:` headers by default, but will simply display - such pages in the same manner it displays all HTTP replies. It does however - feature an option that will make it attempt to follow the `Location:` - pointers. + Curl does not follow `Location:` headers by default, but simply displays such + pages in the same manner it displays all HTTP replies. It does however + feature an option that makes it attempt to follow the `Location:` pointers. To tell curl to follow a Location: curl --location http://www.example.com If you use curl to POST to a site that immediately redirects you to another - page, you can safely use - [`--location`](https://curl.se/docs/manpage.html#-L) (`-L`) and - `--data`/`--form` together. Curl will only use POST in the first request, and - then revert to GET in the following operations. + page, you can safely use [`--location`](https://curl.se/docs/manpage.html#-L) + (`-L`) and `--data`/`--form` together. Curl only uses POST in the first + request, and then revert to GET in the following operations. ## Other redirects @@ -500,7 +494,7 @@ The way the web browsers do "client side state control" is by using cookies. Cookies are just names with associated contents. The cookies are sent to the client by the server. The server tells the client for what path - and host name it wants the cookie sent back, and it also sends an expiration + and hostname it wants the cookie sent back, and it also sends an expiration date and a few more properties. When a client communicates with a server with a name and path as previously @@ -551,7 +545,7 @@ format that Netscape and Mozilla once used. It is a convenient way to share cookies between scripts or invokes. The `--cookie` (`-b`) switch automatically detects if a given file is such a cookie file and parses it, - and by using the `--cookie-jar` (`-c`) option you will make curl write a new + and by using the `--cookie-jar` (`-c`) option you make curl write a new cookie file at the end of an operation: curl --cookie cookies.txt --cookie-jar newcookies.txt \ @@ -570,7 +564,7 @@ advanced features to do secure transfers over HTTP. Curl supports encrypted fetches when built to use a TLS library and it can be - built to use one out of a fairly large set of libraries - `curl -V` will show + built to use one out of a fairly large set of libraries - `curl -V` shows which one your curl was built to use (if any!). To get a page from an HTTPS server, simply run curl like: @@ -588,11 +582,10 @@ curl --cert mycert.pem https://secure.example.com curl also tries to verify that the server is who it claims to be, by - verifying the server's certificate against a locally stored CA cert - bundle. Failing the verification will cause curl to deny the connection. You - must then use [`--insecure`](https://curl.se/docs/manpage.html#-k) - (`-k`) in case you want to tell curl to ignore that the server cannot be - verified. + verifying the server's certificate against a locally stored CA cert bundle. + Failing the verification causes curl to deny the connection. You must then + use [`--insecure`](https://curl.se/docs/manpage.html#-k) (`-k`) in case you + want to tell curl to ignore that the server cannot be verified. More about server certificate verification and ca cert bundles can be read in the [`SSLCERTS` document](https://curl.se/docs/sslcerts.html). @@ -629,19 +622,18 @@ ## More on changed methods It should be noted that curl selects which methods to use on its own - depending on what action to ask for. `-d` will do POST, `-I` will do HEAD and - so on. If you use the - [`--request`](https://curl.se/docs/manpage.html#-X) / `-X` option you - can change the method keyword curl selects, but you will not modify curl's - behavior. This means that if you for example use -d "data" to do a POST, you - can modify the method to a `PROPFIND` with `-X` and curl will still think it - sends a POST . You can change the normal GET to a POST method by simply - adding `-X POST` in a command line like: + depending on what action to ask for. `-d` makes a POST, `-I` makes a HEAD and + so on. If you use the [`--request`](https://curl.se/docs/manpage.html#-X) / + `-X` option you can change the method keyword curl selects, but you do not + modify curl's behavior. This means that if you for example use -d "data" to + do a POST, you can modify the method to a `PROPFIND` with `-X` and curl still + thinks it sends a POST. You can change the normal GET to a POST method by + simply adding `-X POST` in a command line like: curl -X POST http://example.org/ - ... but curl will still think and act as if it sent a GET so it will not send - any request body etc. + curl however still acts as if it sent a GET so it does not send any request + body etc. # Web Login @@ -652,13 +644,13 @@ login forms work and how to login to them using curl. It can also be noted that to do this properly in an automated fashion, you - will most certainly need to script things and do multiple curl invokes etc. + most certainly need to script things and do multiple curl invokes etc. First, servers mostly use cookies to track the logged-in status of the - client, so you will need to capture the cookies you receive in the - responses. Then, many sites also set a special cookie on the login page (to - make sure you got there through their login page) so you should make a habit - of first getting the login-form page to capture the cookies set there. + client, so you need to capture the cookies you receive in the responses. + Then, many sites also set a special cookie on the login page (to make sure + you got there through their login page) so you should make a habit of first + getting the login-form page to capture the cookies set there. Some web-based login systems feature various amounts of JavaScript, and sometimes they use such code to set or modify cookie contents. Possibly they @@ -678,7 +670,7 @@ ## Some debug tricks - Many times when you run curl on a site, you will notice that the site does not + Many times when you run curl on a site, you notice that the site does not seem to respond the same way to your curl requests as it does to your browser's. diff --git a/docs/URL-SYNTAX.md b/docs/URL-SYNTAX.md index ddd99454fbe..67f9bdbc649 100644 --- a/docs/URL-SYNTAX.md +++ b/docs/URL-SYNTAX.md @@ -28,10 +28,10 @@ Due to the inherent differences between URL parser implementations, it is considered a security risk to mix different implementations and assume the same behavior! -For example, if you use one parser to check if a URL uses a good host name or +For example, if you use one parser to check if a URL uses a good hostname or the correct auth field, and then pass on that same URL to a *second* parser, -there will always be a risk it treats the same URL differently. There is no -right and wrong in URL land, only differences of opinions. +there is always a risk it treats the same URL differently. There is no right +and wrong in URL land, only differences of opinions. libcurl offers a separate API to its URL parser for this reason, among others. @@ -55,8 +55,8 @@ security concerns: ## "RFC 3986 plus" curl recognizes a URL syntax that we call "RFC 3986 plus". It is grounded on -the well established RFC 3986 to make sure previously written command lines and -curl using scripts will remain working. +the well established RFC 3986 to make sure previously written command lines +and curl using scripts remain working. curl's URL parser allows a few deviations from the spec in order to inter-operate better with URLs that appear in the wild. @@ -92,8 +92,7 @@ curl supports "URLs" that do not start with a scheme. This is not supported by any of the specifications. This is a shortcut to entering URLs that was supported by browsers early on and has been mimicked by curl. -Based on what the host name starts with, curl will "guess" what protocol to -use: +Based on what the hostname starts with, curl "guesses" what protocol to use: - `ftp.` means FTP - `dict.` means DICT @@ -147,7 +146,7 @@ schemes: ## Userinfo -The userinfo field can be used to set user name and password for +The userinfo field can be used to set username and password for authentication purposes in this transfer. The use of this field is discouraged since it often means passing around the password in plain text and is thus a security risk. @@ -184,7 +183,7 @@ machine. ### IDNA If curl was built with International Domain Name (IDN) support, it can also -handle host names using non-ASCII characters. +handle hostnames using non-ASCII characters. When built with libidn2, curl uses the IDNA 2008 standard. This is equivalent to the WHATWG URL spec, but differs from certain browsers that use IDNA 2003 @@ -201,8 +200,8 @@ If there is a colon after the hostname, that should be followed by the port number to use. 1 - 65535. curl also supports a blank port number field - but only if the URL starts with a scheme. -If the port number is not specified in the URL, curl will used a default port -based on the provide scheme: +If the port number is not specified in the URL, curl uses a default port +number based on the provide scheme: DICT 2628, FTP 21, FTPS 990, GOPHER 70, GOPHERS 70, HTTP 80, HTTPS 443, IMAP 132, IMAPS 993, LDAP 369, LDAPS 636, MQTT 1883, POP3 110, POP3S 995, @@ -216,7 +215,7 @@ SMTP 25, SMTPS 465, TELNET 23, TFTP 69 The path part of an FTP request specifies the file to retrieve and from which directory. If the file part is omitted then libcurl downloads the directory listing for the directory specified. If the directory is omitted then the -directory listing for the root / home directory will be returned. +directory listing for the root / home directory is returned. FTP servers typically put the user in its "home directory" after login, which then differs between users. To explicitly specify the root directory of an FTP @@ -231,14 +230,14 @@ to read or write such a path. curl only allows the hostname part of a FILE URL to be one out of these three alternatives: `localhost`, `127.0.0.1` or blank ("", zero characters). -Anything else will make curl fail to parse the URL. +Anything else makes curl fail to parse the URL. ### Windows-specific FILE details curl accepts that the FILE URL's path starts with a "drive letter". That is a single letter `a` to `z` followed by a colon or a pipe character (`|`). -The Windows operating system itself will convert some file accesses to perform +The Windows operating system itself converts some file accesses to perform network accesses over SMB/CIFS, through several different file path patterns. This way, a `file://` URL passed to curl *might* be converted into a network access inadvertently and unknowingly to curl. This is a Windows feature curl @@ -321,7 +320,7 @@ Search for the `DN` as `My Organization`: ldap://ldap.example.com/o=My%20Organization -the same search but will only return `postalAddress` attributes: +the same search but only return `postalAddress` attributes: ldap://ldap.example.com/o=My%20Organization?postalAddress @@ -352,12 +351,12 @@ To specify a path relative to the user's home directory on the server, prepend The path part of an SFTP URL specifies the file to retrieve or upload. If the path ends with a slash (`/`) then a directory listing is returned instead of a file. If the path is omitted entirely then the directory listing for the root -/ home directory will be returned. +/ home directory is returned. ## SMB The path part of a SMB request specifies the file to retrieve and from what share and directory or the share to upload to and as such, may not be omitted. -If the user name is embedded in the URL then it must contain the domain name +If the username is embedded in the URL then it must contain the domain name and as such, the backslash must be URL encoded as %2f. When uploading to SMB, the size of the file needs to be known ahead of time, @@ -367,9 +366,9 @@ curl supports SMB version 1 (only) ## SMTP -The path part of a SMTP request specifies the host name to present during -communication with the mail server. If the path is omitted, then libcurl will -attempt to resolve the local computer's host name. However, this may not +The path part of a SMTP request specifies the hostname to present during +communication with the mail server. If the path is omitted, then libcurl +attempts to resolve the local computer's hostname. However, this may not return the fully qualified domain name that is required by some mail servers and specifying this path allows you to set an alternative name, such as your machine's fully qualified domain name, which you might have obtained from an @@ -385,7 +384,6 @@ traditional URL, followed by a space and a series of space-separated `name=value` pairs. While space is not typically a "legal" letter, libcurl accepts them. When a -user wants to pass in a `#` (hash) character it will be treated as a fragment -and get cut off by libcurl if provided literally. You will instead have to -escape it by providing it as backslash and its ASCII value in hexadecimal: -`\23`. +user wants to pass in a `#` (hash) character it is treated as a fragment and +it gets cut off by libcurl if provided literally. You have to escape it by +providing it as backslash and its ASCII value in hexadecimal: `\23`. diff --git a/docs/VERSIONS.md b/docs/VERSIONS.md index 0ec9cd518ab..fc21749ee02 100644 --- a/docs/VERSIONS.md +++ b/docs/VERSIONS.md @@ -14,11 +14,11 @@ Version Numbers and Releases ## Bumping numbers - One of these numbers will get bumped in each new release. The numbers to the - right of a bumped number will be reset to zero. + One of these numbers get bumped in each new release. The numbers to the right + of a bumped number are reset to zero. - The main version number will get bumped when *really* big, world colliding - changes are made. The release number is bumped when changes are performed or + The main version number is bumped when *really* big, world colliding changes + are made. The release number is bumped when changes are performed or things/features are added. The patch number is bumped when the changes are mere bugfixes. diff --git a/docs/VULN-DISCLOSURE-POLICY.md b/docs/VULN-DISCLOSURE-POLICY.md index 65059934807..f18db6d52fa 100644 --- a/docs/VULN-DISCLOSURE-POLICY.md +++ b/docs/VULN-DISCLOSURE-POLICY.md @@ -17,8 +17,8 @@ The typical process for handling a new security vulnerability is as follows. No information should be made public about a vulnerability until it is formally announced at the end of this process. That means, for example, that a -bug tracker entry must NOT be created to track the issue since that will make -the issue public and it should not be discussed on any of the project's public +bug tracker entry must NOT be created to track the issue since that makes the +issue public and it should not be discussed on any of the project's public mailing lists. Messages associated with any commits should not make any reference to the security nature of the commit if done prior to the public announcement. @@ -59,7 +59,8 @@ announcement. [SECURITY-ADVISORY](https://curl.se/dev/advisory.html) for help on creating the advisory. -- Request a CVE number from HackerOne +- Request a CVE Id for the issue. curl is a CNA (CVE Numbering Authority) and + can request its own numbers. - Update the "security advisory" with the CVE number. @@ -92,7 +93,7 @@ announcement. the same manner we always announce releases. It gets sent to the curl-announce, curl-library and curl-users mailing lists. -- The security web page on the website should get the new vulnerability +- The security webpage on the website should get the new vulnerability mentioned. ## security (at curl dot se) @@ -108,7 +109,7 @@ its way of working. You must have been around for a good while and you should have no plans of vanishing in the near future. We do not make the list of participants public mostly because it tends to vary -somewhat over time and a list somewhere will only risk getting outdated. +somewhat over time and a list somewhere only risks getting outdated. ## Publishing Security Advisories @@ -255,8 +256,8 @@ data. We consider this functionality a best-effort and omissions are not security vulnerabilities. - not all systems allow the arguments to be blanked in the first place - - since curl blanks the argument itself they will be readable for a short - moment no matter what + - since curl blanks the argument itself they area readable for a short moment + no matter what - virtually every argument can contain sensitive data, depending on use - blanking all arguments would make it impractical for users to differentiate curl command lines in process listings diff --git a/docs/WEBSOCKET.md b/docs/WEBSOCKET.md index ba84c2284f3..14caec2405a 100644 --- a/docs/WEBSOCKET.md +++ b/docs/WEBSOCKET.md @@ -13,8 +13,7 @@ using the `ws://` or `wss://` URL schemes. The latter one being the secure version done over HTTPS. When using `wss://` to do WebSocket over HTTPS, the standard TLS and HTTPS -options will be acknowledged for the CA, verification of server certificate -etc. +options are acknowledged for the CA, verification of server certificate etc. WebSocket communication is done by upgrading a connection from either HTTP or HTTPS. When given a WebSocket URL to work with, libcurl considers it a @@ -64,7 +63,7 @@ directions. If the given WebSocket URL (using `ws://` or `wss://`) fails to get upgraded via a 101 response code and instead gets another response code back from the -HTTP server - the transfer will return `CURLE_HTTP_RETURNED_ERROR` for that +HTTP server - the transfer returns `CURLE_HTTP_RETURNED_ERROR` for that transfer. Note then that even 2xx response codes are then considered error since it failed to provide a WebSocket transfer. @@ -109,10 +108,9 @@ Ideas: ## Why not libWebSocket -[libWebSocket](https://libWebSockets.org/) is said to be a solid, fast and -efficient WebSocket library with a vast amount of users. My plan was -originally to build upon it to skip having to implement the low level parts of -WebSocket myself. +libWebSocket is said to be a solid, fast and efficient WebSocket library with +a vast amount of users. My plan was originally to build upon it to skip having +to implement the low level parts of WebSocket myself. Here are the reasons why I have decided to move forward with WebSocket in curl **without using libWebSocket**: diff --git a/docs/cmdline-opts/.gitignore b/docs/cmdline-opts/.gitignore new file mode 100644 index 00000000000..8d42e2c53d5 --- /dev/null +++ b/docs/cmdline-opts/.gitignore @@ -0,0 +1,5 @@ +# Copyright (C) Daniel Stenberg, , et al. +# +# SPDX-License-Identifier: curl + +curl.txt diff --git a/docs/cmdline-opts/CMakeLists.txt b/docs/cmdline-opts/CMakeLists.txt index 3dd8be49b19..99ec66c3188 100644 --- a/docs/cmdline-opts/CMakeLists.txt +++ b/docs/cmdline-opts/CMakeLists.txt @@ -21,15 +21,19 @@ # SPDX-License-Identifier: curl # ########################################################################### -set(MANPAGE "${CURL_BINARY_DIR}/docs/curl.1") +set(MANPAGE "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.1") +set(ASCIIPAGE "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.txt") # Load DPAGES and OTHERPAGES from shared file transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") add_custom_command(OUTPUT "${MANPAGE}" - COMMAND "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/gen.pl" mainpage "${CMAKE_CURRENT_SOURCE_DIR}" > "${MANPAGE}" - DEPENDS ${DPAGES} ${OTHERPAGES} + COMMAND cd ${CMAKE_CURRENT_SOURCE_DIR} && "${PERL_EXECUTABLE}" ${PROJECT_SOURCE_DIR}/scripts/managen mainpage ${DPAGES} > "${MANPAGE}" + COMMAND cd ${CMAKE_CURRENT_SOURCE_DIR} && "${PERL_EXECUTABLE}" ${PROJECT_SOURCE_DIR}/scripts/managen ascii ${DPAGES} > "${ASCIIPAGE}" VERBATIM ) -add_custom_target(generate-curl.1 DEPENDS "${MANPAGE}") +add_custom_target(generate-curl.1 ALL DEPENDS "${MANPAGE}") +if(NOT CURL_DISABLE_INSTALL) + install(FILES "${MANPAGE}" DESTINATION ${CMAKE_INSTALL_MANDIR}/man1) +endif() diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 6de32dab94d..1f9749bc51b 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -6,27 +6,41 @@ # curl man page generator -This is the curl man page generator. It generates a single nroff man page +`managen` is the curl man page generator. It generates a single nroff man page output from the set of sources files in this directory. -There is one source file for each supported command line option. The output -gets `page-header` prepended and `page-footer` appended. The format is -described below. +The `mainpage.idx` file lists all files that are rendered in that order to +produce the output. The magic `%options` keyword inserts all command line +options documented. + +The `%options` documentation is created with one source file for each +supported command line option. + +The documentation file format is described below. It is meant to look similar +to markdown which is why it uses `.md` file extensions. ## Option files Each command line option is described in a file named `.d`, where -option name is written without any prefixing dashes. Like the file name for -the -v, --verbose option is named `verbose.d`. +option name is written without any prefixing dashes. Like the filename for the +`-v, --verbose` option is named `verbose.d`. + +Each file has a set of meta-data in the top of the file, followed by a body of +text. + +The documentation files that do not document options have no meta-data part. -Each file has a set of meta-data and a body of text. +A line that starts with ``. ### Meta-data + --- (start of meta-data) Added: (version number in which this was added) Arg: (the argument the option takes) c: (copyright line) - Example: (example command line, without "curl" and can use `$URL`) + Example: + - (an example command line, without "curl" and can use `$URL`) + - (another example) Experimental: yes (if so) Help: (short text for the --help output for this option) Long: (long form name, without dashes) @@ -36,7 +50,9 @@ Each file has a set of meta-data and a body of text. Protocols: (space separated list for which protocols this option works) Requires: (space separated list of features this requires, no dashes) Scope: global (if the option is global) - See-also: (space separated list of related options, no dashes) + See-also: + - (a related option, no dashes) + - (another related option, no dashes) Short: (single letter, without dash) SPDX-License-Identifier: curl Tags: (space separated list) @@ -54,20 +70,49 @@ Text written within `*asterisks*` is shown using italics. Text within two Text that is prefixed with a space is treated like an "example" and gets output in monospace. -## Header and footer +Within the body, describe a list of items like this: + + ## item 1 + description + + ## item 2 + second description + +The list is automatically terminated at end of file, or you can do it +explicitly with an empty "header": -`page-header` is the file that is output before the generated options output -for the master man page. + ## -`page-footer` is appended after all the individual options. +Angle brackets (`<>`) need to be escaped when used in text like `\<` and +`\>`. This, to ensure that the text renders nicely as markdown. + +### Headers + +The `#` header can be used by non-option files and it produces a +`.SH` output. + +If the `#` header is used for a command line option file, that header is +simply ignored in the generated output. It can still serve a purpose in the +source file as it helps the user identify what option the file is for. + +### Variables + +There are three different "variables" that can be used when creating the +output. They need to be written within backticks in the source file (to escape +getting spellchecked by CI jobs): `%DATE`, `%VERSION` and `%GLOBALS`. ## Generate -`./gen.pl mainpage` +`managen mainpage [list of markdown option file names]` This command outputs a single huge nroff file, meant to become `curl.1`. The full curl man page. -`./gen.pl listhelp` +`managen ascii [list of markdown option file names]` + +This command outputs a single text file, meant to become `curl.txt`. The full +curl man page in text format, used to build `tool_hugehelp.c`. + +`managen listhelp` Generates a full `curl --help` output for all known command line options. diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index 5a8996bc227..81a4afe1bcf 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -24,18 +24,37 @@ AUTOMAKE_OPTIONS = foreign no-dependencies -MANPAGE = $(top_builddir)/docs/curl.1 +MANPAGE = curl.1 +ASCIIPAGE = curl.txt + +man_MANS = $(MANPAGE) include Makefile.inc -EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl $(OTHERPAGES) CMakeLists.txt +EXTRA_DIST = $(DPAGES) MANPAGE.md $(SUPPORT) CMakeLists.txt mainpage.idx GEN = $(GN_$(V)) GN_0 = @echo " GENERATE" $@; GN_1 = GN_ = $(GN_0) -all: $(MANPAGE) +MANAGEN=$(abs_top_srcdir)/scripts/managen + +if BUILD_DOCS +CLEANFILES = $(MANPAGE) $(ASCIIPAGE) + +all: $(MANPAGE) $(ASCIIPAGE) + +endif + +$(MANPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc $(MANAGEN) + $(GEN)(rm -f $(MANPAGE) && (cd $(srcdir) && @PERL@ $(MANAGEN) mainpage $(DPAGES)) > manpage.tmp.$$$$ && mv manpage.tmp.$$$$ $(MANPAGE)) + +$(ASCIIPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc $(MANAGEN) + $(GEN)(rm -f $(ASCIIPAGE) && (cd $(srcdir) && @PERL@ $(MANAGEN) ascii $(DPAGES)) > asciipage.tmp.$$$$ && mv asciipage.tmp.$$$$ $(ASCIIPAGE)) + +listhelp: + $(MANAGEN) listhelp $(DPAGES) > $(top_builddir)/src/tool_listhelp.c -$(MANPAGE): $(DPAGES) $(OTHERPAGES) Makefile.inc gen.pl - $(GEN)(rm -f $(MANPAGE) && cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES) > $(builddir)/manpage.tmp && mv $(builddir)/manpage.tmp $(MANPAGE)) +listcats: + @$(MANAGEN) listcats $(DPAGES) diff --git a/docs/cmdline-opts/Makefile.inc b/docs/cmdline-opts/Makefile.inc index a7c92f2646f..428cc3bab2a 100644 --- a/docs/cmdline-opts/Makefile.inc +++ b/docs/cmdline-opts/Makefile.inc @@ -23,264 +23,283 @@ ########################################################################### # Shared between Makefile.am and CMakeLists.txt -DPAGES = \ - abstract-unix-socket.d \ - alt-svc.d \ - anyauth.d \ - append.d \ - aws-sigv4.d \ - basic.d \ - ca-native.d \ - cacert.d \ - capath.d \ - cert-status.d \ - cert-type.d \ - cert.d \ - ciphers.d \ - compressed-ssh.d \ - compressed.d \ - config.d \ - connect-timeout.d \ - connect-to.d \ - continue-at.d \ - cookie-jar.d \ - cookie.d \ - create-dirs.d \ - create-file-mode.d \ - crlf.d \ - crlfile.d \ - curves.d \ - data-ascii.d \ - data-binary.d \ - data-raw.d \ - data-urlencode.d \ - data.d \ - delegation.d \ - digest.d \ - disable-eprt.d \ - disable-epsv.d \ - disable.d \ - disallow-username-in-url.d \ - dns-interface.d \ - dns-ipv4-addr.d \ - dns-ipv6-addr.d \ - dns-servers.d \ - doh-cert-status.d \ - doh-insecure.d \ - doh-url.d \ - dump-header.d \ - egd-file.d \ - engine.d \ - etag-compare.d \ - etag-save.d \ - expect100-timeout.d \ - fail-early.d \ - fail-with-body.d \ - fail.d \ - false-start.d \ - form-escape.d \ - form-string.d \ - form.d \ - ftp-account.d \ - ftp-alternative-to-user.d \ - ftp-create-dirs.d \ - ftp-method.d \ - ftp-pasv.d \ - ftp-port.d \ - ftp-pret.d \ - ftp-skip-pasv-ip.d \ - ftp-ssl-ccc-mode.d \ - ftp-ssl-ccc.d \ - ftp-ssl-control.d \ - get.d \ - globoff.d \ - happy-eyeballs-timeout-ms.d \ - haproxy-protocol.d \ - haproxy-clientip.d \ - head.d \ - header.d \ - help.d \ - hostpubmd5.d \ - hostpubsha256.d \ - hsts.d \ - http0.9.d \ - http1.0.d \ - http1.1.d \ - http2-prior-knowledge.d \ - http2.d \ - http3.d \ - http3-only.d \ - ignore-content-length.d \ - include.d \ - insecure.d \ - interface.d \ - ipfs-gateway.d \ - ipv4.d \ - ipv6.d \ - json.d \ - junk-session-cookies.d \ - keepalive-time.d \ - key-type.d \ - key.d \ - krb.d \ - libcurl.d \ - limit-rate.d \ - list-only.d \ - local-port.d \ - location-trusted.d \ - location.d \ - login-options.d \ - mail-auth.d \ - mail-from.d \ - mail-rcpt-allowfails.d \ - mail-rcpt.d \ - manual.d \ - max-filesize.d \ - max-redirs.d \ - max-time.d \ - metalink.d \ - negotiate.d \ - netrc-file.d \ - netrc-optional.d \ - netrc.d \ - next.d \ - no-alpn.d \ - no-buffer.d \ - no-clobber.d \ - no-keepalive.d \ - no-npn.d \ - no-progress-meter.d \ - no-sessionid.d \ - noproxy.d \ - ntlm-wb.d \ - ntlm.d \ - oauth2-bearer.d \ - output-dir.d \ - output.d \ - parallel-immediate.d \ - parallel-max.d \ - parallel.d \ - pass.d \ - path-as-is.d \ - pinnedpubkey.d \ - post301.d \ - post302.d \ - post303.d \ - preproxy.d \ - progress-bar.d \ - proto-default.d \ - proto-redir.d \ - proto.d \ - proxy-anyauth.d \ - proxy-basic.d \ - proxy-ca-native.d \ - proxy-cacert.d \ - proxy-capath.d \ - proxy-cert-type.d \ - proxy-cert.d \ - proxy-ciphers.d \ - proxy-crlfile.d \ - proxy-digest.d \ - proxy-header.d \ - proxy-http2.d \ - proxy-insecure.d \ - proxy-key-type.d \ - proxy-key.d \ - proxy-negotiate.d \ - proxy-ntlm.d \ - proxy-pass.d \ - proxy-pinnedpubkey.d \ - proxy-service-name.d \ - proxy-ssl-allow-beast.d \ - proxy-ssl-auto-client-cert.d \ - proxy-tls13-ciphers.d \ - proxy-tlsauthtype.d \ - proxy-tlspassword.d \ - proxy-tlsuser.d \ - proxy-tlsv1.d \ - proxy-user.d \ - proxy.d \ - proxy1.0.d \ - proxytunnel.d \ - pubkey.d \ - quote.d \ - random-file.d \ - range.d \ - rate.d \ - raw.d \ - referer.d \ - remote-header-name.d \ - remote-name-all.d \ - remote-name.d \ - remote-time.d \ - remove-on-error.d \ - request-target.d \ - request.d \ - resolve.d \ - retry-all-errors.d \ - retry-connrefused.d \ - retry-delay.d \ - retry-max-time.d \ - retry.d \ - sasl-authzid.d \ - sasl-ir.d \ - service-name.d \ - show-error.d \ - silent.d \ - socks4.d \ - socks4a.d \ - socks5-basic.d \ - socks5-gssapi-nec.d \ - socks5-gssapi-service.d \ - socks5-gssapi.d \ - socks5-hostname.d \ - socks5.d \ - speed-limit.d \ - speed-time.d \ - ssl-allow-beast.d \ - ssl-auto-client-cert.d \ - ssl-no-revoke.d \ - ssl-reqd.d \ - ssl-revoke-best-effort.d \ - ssl.d \ - sslv2.d \ - sslv3.d \ - stderr.d \ - styled-output.d \ - suppress-connect-headers.d \ - tcp-fastopen.d \ - tcp-nodelay.d \ - telnet-option.d \ - tftp-blksize.d \ - tftp-no-options.d \ - time-cond.d \ - tls-max.d \ - tls13-ciphers.d \ - tlsauthtype.d \ - tlspassword.d \ - tlsuser.d \ - tlsv1.0.d \ - tlsv1.1.d \ - tlsv1.2.d \ - tlsv1.3.d \ - tlsv1.d \ - tr-encoding.d \ - trace-ascii.d \ - trace-config.d \ - trace-ids.d \ - trace-time.d \ - trace.d \ - unix-socket.d \ - upload-file.d \ - url.d \ - url-query.d \ - use-ascii.d \ - user-agent.d \ - user.d \ - variable.d \ - verbose.d \ - version.d \ - write-out.d \ - xattr.d +SUPPORT = \ + _AUTHORS.md \ + _BUGS.md \ + _DESCRIPTION.md \ + _ENVIRONMENT.md \ + _EXITCODES.md \ + _FILES.md \ + _GLOBBING.md \ + _NAME.md \ + _OPTIONS.md \ + _OUTPUT.md \ + _PROGRESS.md \ + _PROTOCOLS.md \ + _PROXYPREFIX.md \ + _SEEALSO.md \ + _SYNOPSIS.md \ + _URL.md \ + _VARIABLES.md \ + _VERSION.md \ + _WWW.md -OTHERPAGES = page-footer page-header +DPAGES = \ + abstract-unix-socket.md \ + alt-svc.md \ + anyauth.md \ + append.md \ + aws-sigv4.md \ + basic.md \ + ca-native.md \ + cacert.md \ + capath.md \ + cert-status.md \ + cert-type.md \ + cert.md \ + ciphers.md \ + compressed-ssh.md \ + compressed.md \ + config.md \ + connect-timeout.md \ + connect-to.md \ + continue-at.md \ + cookie-jar.md \ + cookie.md \ + create-dirs.md \ + create-file-mode.md \ + crlf.md \ + crlfile.md \ + curves.md \ + data-ascii.md \ + data-binary.md \ + data-raw.md \ + data-urlencode.md \ + data.md \ + delegation.md \ + digest.md \ + disable-eprt.md \ + disable-epsv.md \ + disable.md \ + disallow-username-in-url.md \ + dns-interface.md \ + dns-ipv4-addr.md \ + dns-ipv6-addr.md \ + dns-servers.md \ + doh-cert-status.md \ + doh-insecure.md \ + doh-url.md \ + dump-header.md \ + egd-file.md \ + engine.md \ + etag-compare.md \ + etag-save.md \ + expect100-timeout.md \ + fail-early.md \ + fail-with-body.md \ + fail.md \ + false-start.md \ + form-escape.md \ + form-string.md \ + form.md \ + ftp-account.md \ + ftp-alternative-to-user.md \ + ftp-create-dirs.md \ + ftp-method.md \ + ftp-pasv.md \ + ftp-port.md \ + ftp-pret.md \ + ftp-skip-pasv-ip.md \ + ftp-ssl-ccc-mode.md \ + ftp-ssl-ccc.md \ + ftp-ssl-control.md \ + get.md \ + globoff.md \ + happy-eyeballs-timeout-ms.md \ + haproxy-protocol.md \ + haproxy-clientip.md \ + head.md \ + header.md \ + help.md \ + hostpubmd5.md \ + hostpubsha256.md \ + hsts.md \ + http0.9.md \ + http1.0.md \ + http1.1.md \ + http2-prior-knowledge.md \ + http2.md \ + http3.md \ + http3-only.md \ + ignore-content-length.md \ + include.md \ + insecure.md \ + interface.md \ + ipfs-gateway.md \ + ipv4.md \ + ipv6.md \ + json.md \ + junk-session-cookies.md \ + keepalive-time.md \ + key-type.md \ + key.md \ + krb.md \ + libcurl.md \ + limit-rate.md \ + list-only.md \ + local-port.md \ + location-trusted.md \ + location.md \ + login-options.md \ + mail-auth.md \ + mail-from.md \ + mail-rcpt-allowfails.md \ + mail-rcpt.md \ + manual.md \ + max-filesize.md \ + max-redirs.md \ + max-time.md \ + metalink.md \ + negotiate.md \ + netrc-file.md \ + netrc-optional.md \ + netrc.md \ + next.md \ + no-alpn.md \ + no-buffer.md \ + no-clobber.md \ + no-keepalive.md \ + no-npn.md \ + no-progress-meter.md \ + no-sessionid.md \ + noproxy.md \ + ntlm-wb.md \ + ntlm.md \ + oauth2-bearer.md \ + output-dir.md \ + output.md \ + parallel-immediate.md \ + parallel-max.md \ + parallel.md \ + pass.md \ + path-as-is.md \ + pinnedpubkey.md \ + post301.md \ + post302.md \ + post303.md \ + preproxy.md \ + progress-bar.md \ + proto-default.md \ + proto-redir.md \ + proto.md \ + proxy-anyauth.md \ + proxy-basic.md \ + proxy-ca-native.md \ + proxy-cacert.md \ + proxy-capath.md \ + proxy-cert-type.md \ + proxy-cert.md \ + proxy-ciphers.md \ + proxy-crlfile.md \ + proxy-digest.md \ + proxy-header.md \ + proxy-http2.md \ + proxy-insecure.md \ + proxy-key-type.md \ + proxy-key.md \ + proxy-negotiate.md \ + proxy-ntlm.md \ + proxy-pass.md \ + proxy-pinnedpubkey.md \ + proxy-service-name.md \ + proxy-ssl-allow-beast.md \ + proxy-ssl-auto-client-cert.md \ + proxy-tls13-ciphers.md \ + proxy-tlsauthtype.md \ + proxy-tlspassword.md \ + proxy-tlsuser.md \ + proxy-tlsv1.md \ + proxy-user.md \ + proxy.md \ + proxy1.0.md \ + proxytunnel.md \ + pubkey.md \ + quote.md \ + random-file.md \ + range.md \ + rate.md \ + raw.md \ + referer.md \ + remote-header-name.md \ + remote-name-all.md \ + remote-name.md \ + remote-time.md \ + remove-on-error.md \ + request-target.md \ + request.md \ + resolve.md \ + retry-all-errors.md \ + retry-connrefused.md \ + retry-delay.md \ + retry-max-time.md \ + retry.md \ + sasl-authzid.md \ + sasl-ir.md \ + service-name.md \ + show-error.md \ + silent.md \ + socks4.md \ + socks4a.md \ + socks5-basic.md \ + socks5-gssapi-nec.md \ + socks5-gssapi-service.md \ + socks5-gssapi.md \ + socks5-hostname.md \ + socks5.md \ + speed-limit.md \ + speed-time.md \ + ssl-allow-beast.md \ + ssl-auto-client-cert.md \ + ssl-no-revoke.md \ + ssl-reqd.md \ + ssl-revoke-best-effort.md \ + ssl.md \ + sslv2.md \ + sslv3.md \ + stderr.md \ + styled-output.md \ + suppress-connect-headers.md \ + tcp-fastopen.md \ + tcp-nodelay.md \ + telnet-option.md \ + tftp-blksize.md \ + tftp-no-options.md \ + time-cond.md \ + tls-max.md \ + tls13-ciphers.md \ + tlsauthtype.md \ + tlspassword.md \ + tlsuser.md \ + tlsv1.0.md \ + tlsv1.1.md \ + tlsv1.2.md \ + tlsv1.3.md \ + tlsv1.md \ + tr-encoding.md \ + trace-ascii.md \ + trace-config.md \ + trace-ids.md \ + trace-time.md \ + trace.md \ + unix-socket.md \ + upload-file.md \ + url.md \ + url-query.md \ + use-ascii.md \ + user-agent.md \ + user.md \ + variable.md \ + verbose.md \ + version.md \ + write-out.md \ + xattr.md diff --git a/docs/cmdline-opts/_AUTHORS.md b/docs/cmdline-opts/_AUTHORS.md new file mode 100644 index 00000000000..0c9bfb95388 --- /dev/null +++ b/docs/cmdline-opts/_AUTHORS.md @@ -0,0 +1,5 @@ + + +# AUTHORS +Daniel Stenberg is the main author, but the whole list of contributors is +found in the separate THANKS file. diff --git a/docs/cmdline-opts/_BUGS.md b/docs/cmdline-opts/_BUGS.md new file mode 100644 index 00000000000..45630d4352e --- /dev/null +++ b/docs/cmdline-opts/_BUGS.md @@ -0,0 +1,5 @@ + + +# BUGS +If you experience any problems with curl, submit an issue in the project's bug +tracker on GitHub: https://github.com/curl/curl/issues diff --git a/docs/cmdline-opts/_DESCRIPTION.md b/docs/cmdline-opts/_DESCRIPTION.md new file mode 100644 index 00000000000..3e06c1b38ff --- /dev/null +++ b/docs/cmdline-opts/_DESCRIPTION.md @@ -0,0 +1,11 @@ + + +# DESCRIPTION + +**curl** is a tool for transferring data from or to a server using URLs. It +supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, +IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, +SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. + +curl is powered by libcurl for all transfer-related features. See +*libcurl(3)* for details. diff --git a/docs/cmdline-opts/_ENVIRONMENT.md b/docs/cmdline-opts/_ENVIRONMENT.md new file mode 100644 index 00000000000..af60ac8d0b8 --- /dev/null +++ b/docs/cmdline-opts/_ENVIRONMENT.md @@ -0,0 +1,114 @@ + + +# ENVIRONMENT +The environment variables can be specified in lower case or upper case. The +lower case version has precedence. `http_proxy` is an exception as it is only +available in lower case. + +Using an environment variable to set the proxy has the same effect as using +the --proxy option. + +## `http_proxy` [protocol://][:port] +Sets the proxy server to use for HTTP. + +## `HTTPS_PROXY` [protocol://][:port] +Sets the proxy server to use for HTTPS. + +## `[url-protocol]_PROXY` [protocol://][:port] +Sets the proxy server to use for [url-protocol], where the protocol is a +protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP, +SMTP, LDAP, etc. + +## `ALL_PROXY` [protocol://][:port] +Sets the proxy server to use if no protocol-specific proxy is set. + +## `NO_PROXY` +list of hostnames that should not go through any proxy. If set to an asterisk +'*' only, it matches all hosts. Each name in this list is matched as either a +domain name which contains the hostname, or the hostname itself. + +This environment variable disables use of the proxy even when specified with +the --proxy option. That is + + NO_PROXY=direct.example.com curl -x http://proxy.example.com + http://direct.example.com + +accesses the target URL directly, and + + NO_PROXY=direct.example.com curl -x http://proxy.example.com + http://somewhere.example.com + +accesses the target URL through the proxy. + +The list of hostnames can also be include numerical IP addresses, and IPv6 +versions should then be given without enclosing brackets. + +IP addresses can be specified using CIDR notation: an appended slash and +number specifies the number of "network bits" out of the address to use in the +comparison (added in 7.86.0). For example "192.168.0.0/16" would match all +addresses starting with "192.168". + +## `APPDATA` +On Windows, this variable is used when trying to find the home directory. If +the primary home variable are all unset. + +## `COLUMNS` +If set, the specified number of characters is used as the terminal width when +the alternative progress-bar is shown. If not set, curl tries to figure it out +using other ways. + +## `CURL_CA_BUNDLE` +If set, it is used as the --cacert value. This environment variable is ignored +if Schannel is used as the TLS backend. + +## `CURL_HOME` +If set, is the first variable curl checks when trying to find its home +directory. If not set, it continues to check *XDG_CONFIG_HOME* + +## `CURL_SSL_BACKEND` +If curl was built with support for "MultiSSL", meaning that it has built-in +support for more than one TLS backend, this environment variable can be set to +the case insensitive name of the particular backend to use when curl is +invoked. Setting a name that is not a built-in alternative makes curl stay +with the default. + +SSL backend names (case-insensitive): **bearssl**, **gnutls**, **mbedtls**, +**openssl**, **rustls**, **schannel**, **secure-transport**, **wolfssl** + +## `HOME` +If set, this is used to find the home directory when that is needed. Like when +looking for the default .curlrc. *CURL_HOME* and *XDG_CONFIG_HOME* +have preference. + +## `QLOGDIR` +If curl was built with HTTP/3 support, setting this environment variable to a +local directory makes curl produce **qlogs** in that directory, using file +names named after the destination connection id (in hex). Do note that these +files can become rather large. Works with the ngtcp2 and quiche QUIC backends. + +## `SHELL` +Used on VMS when trying to detect if using a **DCL** or a **unix** shell. + +## `SSL_CERT_DIR` +If set, it is used as the --capath value. This environment variable is ignored +if Schannel is used as the TLS backend. + +## `SSL_CERT_FILE` +If set, it is used as the --cacert value. This environment variable is ignored +if Schannel is used as the TLS backend. + +## `SSLKEYLOGFILE` +If you set this environment variable to a filename, curl stores TLS secrets +from its connections in that file when invoked to enable you to analyze the +TLS traffic in real time using network analyzing tools such as Wireshark. This +works with the following TLS backends: OpenSSL, libressl, BoringSSL, GnuTLS +and wolfSSL. + +## `USERPROFILE` +On Windows, this variable is used when trying to find the home directory. If +the other, primary, variable are all unset. If set, curl uses the path +**"$USERPROFILE\Application Data"**. + +## `XDG_CONFIG_HOME` +If *CURL_HOME* is not set, this variable is checked when looking for a +default .curlrc file. diff --git a/docs/cmdline-opts/_EXITCODES.md b/docs/cmdline-opts/_EXITCODES.md new file mode 100644 index 00000000000..c5a928b5904 --- /dev/null +++ b/docs/cmdline-opts/_EXITCODES.md @@ -0,0 +1,203 @@ + + +# EXIT CODES +There are a bunch of different error codes and their corresponding error +messages that may appear under error conditions. At the time of this writing, +the exit codes are: +## 0 +Success. The operation completed successfully according to the instructions. +## 1 +Unsupported protocol. This build of curl has no support for this protocol. +## 2 +Failed to initialize. +## 3 +URL malformed. The syntax was not correct. +## 4 +A feature or option that was needed to perform the desired request was not +enabled or was explicitly disabled at build-time. To make curl able to do +this, you probably need another build of libcurl. +## 5 +Could not resolve proxy. The given proxy host could not be resolved. +## 6 +Could not resolve host. The given remote host could not be resolved. +## 7 +Failed to connect to host. +## 8 +Weird server reply. The server sent data curl could not parse. +## 9 +FTP access denied. The server denied login or denied access to the particular +resource or directory you wanted to reach. Most often you tried to change to a +directory that does not exist on the server. +## 10 +FTP accept failed. While waiting for the server to connect back when an active +FTP session is used, an error code was sent over the control connection or +similar. +## 11 +FTP weird PASS reply. Curl could not parse the reply sent to the PASS request. +## 12 +During an active FTP session while waiting for the server to connect back to +curl, the timeout expired. +## 13 +FTP weird PASV reply, Curl could not parse the reply sent to the PASV request. +## 14 +FTP weird 227 format. Curl could not parse the 227-line the server sent. +## 15 +FTP cannot use host. Could not resolve the host IP we got in the 227-line. +## 16 +HTTP/2 error. A problem was detected in the HTTP2 framing layer. This is +somewhat generic and can be one out of several problems, see the error message +for details. +## 17 +FTP could not set binary. Could not change transfer method to binary. +## 18 +Partial file. Only a part of the file was transferred. +## 19 +FTP could not download/access the given file, the RETR (or similar) command +failed. +## 21 +FTP quote error. A quote command returned error from the server. +## 22 +HTTP page not retrieved. The requested URL was not found or returned another +error with the HTTP error code being 400 or above. This return code only +appears if --fail is used. +## 23 +Write error. Curl could not write data to a local filesystem or similar. +## 25 +Failed starting the upload. For FTP, the server typically denied the STOR +command. +## 26 +Read error. Various reading problems. +## 27 +Out of memory. A memory allocation request failed. +## 28 +Operation timeout. The specified time-out period was reached according to the +conditions. +## 30 +FTP PORT failed. The PORT command failed. Not all FTP servers support the PORT +command, try doing a transfer using PASV instead. +## 31 +FTP could not use REST. The REST command failed. This command is used for +resumed FTP transfers. +## 33 +HTTP range error. The range "command" did not work. +## 34 +HTTP post error. Internal post-request generation error. +## 35 +SSL connect error. The SSL handshaking failed. +## 36 +Bad download resume. Could not continue an earlier aborted download. +## 37 +FILE could not read file. Failed to open the file. Permissions? +## 38 +LDAP cannot bind. LDAP bind operation failed. +## 39 +LDAP search failed. +## 41 +Function not found. A required LDAP function was not found. +## 42 +Aborted by callback. An application told curl to abort the operation. +## 43 +Internal error. A function was called with a bad parameter. +## 45 +Interface error. A specified outgoing interface could not be used. +## 47 +Too many redirects. When following redirects, curl hit the maximum amount. +## 48 +Unknown option specified to libcurl. This indicates that you passed a weird +option to curl that was passed on to libcurl and rejected. Read up in the +manual! +## 49 +Malformed telnet option. +## 52 +The server did not reply anything, which here is considered an error. +## 53 +SSL crypto engine not found. +## 54 +Cannot set SSL crypto engine as default. +## 55 +Failed sending network data. +## 56 +Failure in receiving network data. +## 58 +Problem with the local certificate. +## 59 +Could not use specified SSL cipher. +## 60 +Peer certificate cannot be authenticated with known CA certificates. +## 61 +Unrecognized transfer encoding. +## 63 +Maximum file size exceeded. +## 64 +Requested FTP SSL level failed. +## 65 +Sending the data requires a rewind that failed. +## 66 +Failed to initialize SSL Engine. +## 67 +The username, password, or similar was not accepted and curl failed to log in. +## 68 +File not found on TFTP server. +## 69 +Permission problem on TFTP server. +## 70 +Out of disk space on TFTP server. +## 71 +Illegal TFTP operation. +## 72 +Unknown TFTP transfer ID. +## 73 +File already exists (TFTP). +## 74 +No such user (TFTP). +## 77 +Problem reading the SSL CA cert (path? access rights?). +## 78 +The resource referenced in the URL does not exist. +## 79 +An unspecified error occurred during the SSH session. +## 80 +Failed to shut down the SSL connection. +## 82 +Could not load CRL file, missing or wrong format (added in 7.19.0). +## 83 +Issuer check failed (added in 7.19.0). +## 84 +The FTP PRET command failed. +## 85 +Mismatch of RTSP CSeq numbers. +## 86 +Mismatch of RTSP Session Identifiers. +## 87 +Unable to parse FTP file list. +## 88 +FTP chunk callback reported error. +## 89 +No connection available, the session is queued. +## 90 +SSL public key does not matched pinned public key. +## 91 +Invalid SSL certificate status. +## 92 +Stream error in HTTP/2 framing layer. +## 93 +An API function was called from inside a callback. +## 94 +An authentication function returned an error. +## 95 +A problem was detected in the HTTP/3 layer. This is somewhat generic and can +be one out of several problems, see the error message for details. +## 96 +QUIC connection error. This error may be caused by an SSL library error. QUIC +is the protocol used for HTTP/3 transfers. +## 97 +Proxy handshake error. +## 98 +A client-side certificate is required to complete the TLS handshake. +## 99 +Poll or select returned fatal error. +## 100 +A value or data field grew larger than allowed. +## XX +More error codes might appear here in future releases. The existing ones are +meant to never change. diff --git a/docs/cmdline-opts/_FILES.md b/docs/cmdline-opts/_FILES.md new file mode 100644 index 00000000000..8c5d3faa7bd --- /dev/null +++ b/docs/cmdline-opts/_FILES.md @@ -0,0 +1,6 @@ + + +# FILES +*~/.curlrc* + +Default config file, see --config for details. diff --git a/docs/cmdline-opts/_GLOBBING.md b/docs/cmdline-opts/_GLOBBING.md new file mode 100644 index 00000000000..282356c3efb --- /dev/null +++ b/docs/cmdline-opts/_GLOBBING.md @@ -0,0 +1,40 @@ + + +# GLOBBING +You can specify multiple URLs or parts of URLs by writing lists within braces +or ranges within brackets. We call this "globbing". + +Provide a list with three different names like this: + + "http://site.{one,two,three}.com" + +Do sequences of alphanumeric series by using [] as in: + + "ftp://ftp.example.com/file[1-100].txt" + +With leading zeroes: + + "ftp://ftp.example.com/file[001-100].txt" + +With letters through the alphabet: + + "ftp://ftp.example.com/file[a-z].txt" + +Nested sequences are not supported, but you can use several ones next to each +other: + + "http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html" + +You can specify a step counter for the ranges to get every Nth number or +letter: + + "http://example.com/file[1-100:10].txt" + + "http://example.com/file[a-z:2].txt" + +When using [] or {} sequences when invoked from a command line prompt, you +probably have to put the full URL within double quotes to avoid the shell from +interfering with it. This also goes for other characters treated special, like +for example '&', '?' and '*'. + +Switch off globbing with --globoff. diff --git a/docs/cmdline-opts/_NAME.md b/docs/cmdline-opts/_NAME.md new file mode 100644 index 00000000000..b0d89161441 --- /dev/null +++ b/docs/cmdline-opts/_NAME.md @@ -0,0 +1,4 @@ + + +# NAME +curl - transfer a URL diff --git a/docs/cmdline-opts/_OPTIONS.md b/docs/cmdline-opts/_OPTIONS.md new file mode 100644 index 00000000000..106298e7457 --- /dev/null +++ b/docs/cmdline-opts/_OPTIONS.md @@ -0,0 +1,26 @@ + + +# OPTIONS +Options start with one or two dashes. Many of the options require an +additional value next to them. If provided text does not start with a dash, it +is presumed to be and treated as a URL. + +The short "single-dash" form of the options, -d for example, may be used with +or without a space between it and its value, although a space is a recommended +separator. The long double-dash form, --data for example, requires a space +between it and its value. + +Short version options that do not need any additional values can be used +immediately next to each other, like for example you can specify all the +options *-O*, *-L* and *-v* at once as *-OLv*. + +In general, all boolean options are enabled with --**option** and yet again +disabled with --**no-**option. That is, you use the same option name but +prefix it with `no-`. However, in this list we mostly only list and show the +--**option** version of them. + +When --next is used, it resets the parser state and you start again with a +clean option state, except for the options that are global. Global options +retain their values and meaning even after --next. + +The following options are global: `%GLOBALS`. diff --git a/docs/cmdline-opts/_OUTPUT.md b/docs/cmdline-opts/_OUTPUT.md new file mode 100644 index 00000000000..32a5457afc4 --- /dev/null +++ b/docs/cmdline-opts/_OUTPUT.md @@ -0,0 +1,11 @@ + + +# OUTPUT +If not told otherwise, curl writes the received data to stdout. It can be +instructed to instead save that data into a local file, using the --output or +--remote-name options. If curl is given multiple URLs to transfer on the +command line, it similarly needs multiple options for where to save them. + +curl does not parse or otherwise "understand" the content it gets or writes as +output. It does no encoding or decoding, unless explicitly asked to with +dedicated command line options. diff --git a/docs/cmdline-opts/_PROGRESS.md b/docs/cmdline-opts/_PROGRESS.md new file mode 100644 index 00000000000..4cbbd8eb780 --- /dev/null +++ b/docs/cmdline-opts/_PROGRESS.md @@ -0,0 +1,25 @@ + + +# PROGRESS METER + +curl normally displays a progress meter during operations, indicating the +amount of transferred data, transfer speeds and estimated time left, etc. The +progress meter displays the transfer rate in bytes per second. The suffixes +(k, M, G, T, P) are 1024 based. For example 1k is 1024 bytes. 1M is 1048576 +bytes. + +curl displays this data to the terminal by default, so if you invoke curl to +do an operation and it is about to write data to the terminal, it *disables* +the progress meter as otherwise it would mess up the output mixing progress +meter and response data. + +If you want a progress meter for HTTP POST or PUT requests, you need to +redirect the response output to a file, using shell redirect (\>), --output +or similar. + +This does not apply to FTP upload as that operation does not spit out any +response data to the terminal. + +If you prefer a progress bar instead of the regular meter, --progress-bar is +your friend. You can also disable the progress meter completely with the +--silent option. diff --git a/docs/cmdline-opts/_PROTOCOLS.md b/docs/cmdline-opts/_PROTOCOLS.md new file mode 100644 index 00000000000..0d4c2374efa --- /dev/null +++ b/docs/cmdline-opts/_PROTOCOLS.md @@ -0,0 +1,51 @@ + + +# PROTOCOLS +curl supports numerous protocols, or put in URL terms: schemes. Your +particular build may not support them all. +## DICT +Lets you lookup words using online dictionaries. +## FILE +Read or write local files. curl does not support accessing file:// URL +remotely, but when running on Microsoft Windows using the native UNC approach +works. +## FTP(S) +curl supports the File Transfer Protocol with a lot of tweaks and levers. With +or without using TLS. +## GOPHER(S) +Retrieve files. +## HTTP(S) +curl supports HTTP with numerous options and variations. It can speak HTTP +version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct +command line options. +## IMAP(S) +Using the mail reading protocol, curl can download emails for you. With or +without using TLS. +## LDAP(S) +curl can do directory lookups for you, with or without TLS. +## MQTT +curl supports MQTT version 3. Downloading over MQTT equals subscribe to a +topic while uploading/posting equals publish on a topic. MQTT over TLS is not +supported (yet). +## POP3(S) +Downloading from a pop3 server means getting a mail. With or without using +TLS. +## RTMP(S) +The **Realtime Messaging Protocol** is primarily used to serve streaming media +and curl can download it. +## RTSP +curl supports RTSP 1.0 downloads. +## SCP +curl supports SSH version 2 scp transfers. +## SFTP +curl supports SFTP (draft 5) done over SSH version 2. +## SMB(S) +curl supports SMB version 1 for upload and download. +## SMTP(S) +Uploading contents to an SMTP server means sending an email. With or without +TLS. +## TELNET +Fetching a telnet URL starts an interactive session where it sends what it +reads on stdin and outputs what the server sends it. +## TFTP +curl can do TFTP downloads and uploads. diff --git a/docs/cmdline-opts/_PROXYPREFIX.md b/docs/cmdline-opts/_PROXYPREFIX.md new file mode 100644 index 00000000000..297b56c4b64 --- /dev/null +++ b/docs/cmdline-opts/_PROXYPREFIX.md @@ -0,0 +1,22 @@ + + +# PROXY PROTOCOL PREFIXES +The proxy string may be specified with a protocol:// prefix to specify +alternative proxy protocols. (Added in 7.21.7) + +If no protocol is specified in the proxy string or if the string does not +match a supported one, the proxy is treated as an HTTP proxy. + +The supported proxy protocol prefixes are as follows: +## http:// +Makes it use it as an HTTP proxy. The default if no scheme prefix is used. +## https:// +Makes it treated as an **HTTPS** proxy. +## socks4:// +Makes it the equivalent of --socks4 +## socks4a:// +Makes it the equivalent of --socks4a +## socks5:// +Makes it the equivalent of --socks5 +## socks5h:// +Makes it the equivalent of --socks5-hostname diff --git a/docs/cmdline-opts/_SEEALSO.md b/docs/cmdline-opts/_SEEALSO.md new file mode 100644 index 00000000000..f4d0b55cfcf --- /dev/null +++ b/docs/cmdline-opts/_SEEALSO.md @@ -0,0 +1,5 @@ + + +# SEE ALSO + +**ftp (1)**, **wget (1)** diff --git a/docs/cmdline-opts/_SYNOPSIS.md b/docs/cmdline-opts/_SYNOPSIS.md new file mode 100644 index 00000000000..38158774488 --- /dev/null +++ b/docs/cmdline-opts/_SYNOPSIS.md @@ -0,0 +1,5 @@ + + +# SYNOPSIS + +**curl [options / URLs]** diff --git a/docs/cmdline-opts/_URL.md b/docs/cmdline-opts/_URL.md new file mode 100644 index 00000000000..48ae02a556f --- /dev/null +++ b/docs/cmdline-opts/_URL.md @@ -0,0 +1,28 @@ + + +# URL +The URL syntax is protocol-dependent. You find a detailed description in +RFC 3986. + +If you provide a URL without a leading **protocol://** scheme, curl guesses +what protocol you want. It then defaults to HTTP but assumes others based on +often-used hostname prefixes. For example, for hostnames starting with `ftp.` +curl assumes you want FTP. + +You can specify any amount of URLs on the command line. They are fetched in a +sequential manner in the specified order unless you use --parallel. You can +specify command line options and URLs mixed and in any order on the command +line. + +curl attempts to reuse connections when doing multiple transfers, so that +getting many files from the same server do not use multiple connects and setup +handshakes. This improves speed. Connection reuse can only be done for URLs +specified for a single command line invocation and cannot be performed between +separate curl runs. + +Provide an IPv6 zone id in the URL with an escaped percentage sign. Like in + + "http://[fe80::3%25eth0]/" + +Everything provided on the command line that is not a command line option or +its argument, curl assumes is a URL and treats it as such. diff --git a/docs/cmdline-opts/_VARIABLES.md b/docs/cmdline-opts/_VARIABLES.md new file mode 100644 index 00000000000..aa6a8ae4f73 --- /dev/null +++ b/docs/cmdline-opts/_VARIABLES.md @@ -0,0 +1,44 @@ + + +# VARIABLES +curl supports command line variables (added in 8.3.0). Set variables with +--variable name=content or --variable name@file (where `file` can be stdin if +set to a single dash (-)). + +Variable contents can be expanded in option parameters using `{{name}}` if the +option name is prefixed with `--expand-`. This gets the contents of the +variable `name` inserted, or a blank if the name does not exist as a +variable. Insert `{{` verbatim in the string by prefixing it with a backslash, +like `\{{`. + +You an access and expand environment variables by first importing them. You +can select to either require the environment variable to be set or you can +provide a default value in case it is not already set. Plain --variable %name +imports the variable called 'name' but exits with an error if that environment +variable is not already set. To provide a default value if it is not set, use +--variable %name=content or --variable %name@content. + +Example. Get the USER environment variable into the URL, fail if USER is not +set: + + --variable '%USER' + --expand-url = "https://example.com/api/{{USER}}/method" + +When expanding variables, curl supports a set of functions that can make the +variable contents more convenient to use. It can trim leading and trailing +white space with `trim`, it can output the contents as a JSON quoted string +with `json`, URL encode the string with `url` or base64 encode it with `b64`. +To apply functions to a variable expansion, add them colon separated to the +right side of the variable. Variable content holding null bytes that are not +encoded when expanded cause error. + +Example: get the contents of a file called $HOME/.secret into a variable +called "fix". Make sure that the content is trimmed and percent-encoded when +sent as POST data: + + --variable %HOME + --expand-variable fix@{{HOME}}/.secret + --expand-data "{{fix:trim:url}}" + https://example.com/ + +Command line variables and expansions were added in 8.3.0. diff --git a/docs/cmdline-opts/_VERSION.md b/docs/cmdline-opts/_VERSION.md new file mode 100644 index 00000000000..e0228fe9cdb --- /dev/null +++ b/docs/cmdline-opts/_VERSION.md @@ -0,0 +1,15 @@ + + +# VERSION + +This man page describes curl `%VERSION`. If you use a later version, chances +are this man page does not fully document it. If you use an earlier version, +this document tries to include version information about which specific +version that introduced changes. + +You can always learn which the latest curl version is by running + + curl https://curl.se/info + +The online version of this man page is always showing the latest incarnation: +https://curl.se/docs/manpage.html diff --git a/docs/cmdline-opts/_WWW.md b/docs/cmdline-opts/_WWW.md new file mode 100644 index 00000000000..35d946697f9 --- /dev/null +++ b/docs/cmdline-opts/_WWW.md @@ -0,0 +1,4 @@ + + +# WWW +https://curl.se diff --git a/docs/cmdline-opts/abstract-unix-socket.d b/docs/cmdline-opts/abstract-unix-socket.d deleted file mode 100644 index 5c2fd4a4762..00000000000 --- a/docs/cmdline-opts/abstract-unix-socket.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: abstract-unix-socket -Arg: -Help: Connect via abstract Unix domain socket -Added: 7.53.0 -Protocols: HTTP -Category: connection -See-also: unix-socket -Example: --abstract-unix-socket socketpath $URL -Multi: single ---- -Connect through an abstract Unix domain socket, instead of using the network. -Note: netstat shows the path of an abstract socket prefixed with '@', however -the argument should not have this leading character. diff --git a/docs/cmdline-opts/abstract-unix-socket.md b/docs/cmdline-opts/abstract-unix-socket.md new file mode 100644 index 00000000000..7078e642fd8 --- /dev/null +++ b/docs/cmdline-opts/abstract-unix-socket.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: abstract-unix-socket +Arg: +Help: Connect via abstract Unix domain socket +Added: 7.53.0 +Protocols: HTTP +Category: connection +Multi: single +See-also: + - unix-socket +Example: + - --abstract-unix-socket socketpath $URL +--- + +# `--abstract-unix-socket` + +Connect through an abstract Unix domain socket, instead of using the network. +Note: netstat shows the path of an abstract socket prefixed with `@`, however +the \ argument should not have this leading character. diff --git a/docs/cmdline-opts/alt-svc.d b/docs/cmdline-opts/alt-svc.d deleted file mode 100644 index 276ac1b669d..00000000000 --- a/docs/cmdline-opts/alt-svc.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: alt-svc -Arg: -Protocols: HTTPS -Help: Enable alt-svc with this cache file -Added: 7.64.1 -Category: http -See-also: resolve connect-to -Example: --alt-svc svc.txt $URL -Multi: append ---- -This option enables the alt-svc parser in curl. If the file name points to an -existing alt-svc cache file, that gets used. After a completed transfer, the -cache is saved to the file name again if it has been modified. - -Specify a "" file name (zero length) to avoid loading/saving and make curl -just handle the cache in memory. - -If this option is used several times, curl loads contents from all the -files but the last one is used for saving. diff --git a/docs/cmdline-opts/alt-svc.md b/docs/cmdline-opts/alt-svc.md new file mode 100644 index 00000000000..257f4d5b9cb --- /dev/null +++ b/docs/cmdline-opts/alt-svc.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: alt-svc +Arg: +Protocols: HTTPS +Help: Enable alt-svc with this cache file +Added: 7.64.1 +Category: http +Multi: append +See-also: + - resolve + - connect-to +Example: + - --alt-svc svc.txt $URL +--- + +# `--alt-svc` + +Enable the alt-svc parser. If the filename points to an existing alt-svc cache +file, that gets used. After a completed transfer, the cache is saved to the +filename again if it has been modified. + +Specify a "" filename (zero length) to avoid loading/saving and make curl just +handle the cache in memory. + +If this option is used several times, curl loads contents from all the +files but the last one is used for saving. diff --git a/docs/cmdline-opts/anyauth.d b/docs/cmdline-opts/anyauth.d deleted file mode 100644 index 2498bdcd848..00000000000 --- a/docs/cmdline-opts/anyauth.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: anyauth -Help: Pick any authentication method -Protocols: HTTP -See-also: proxy-anyauth basic digest -Category: http proxy auth -Example: --anyauth --user me:pwd $URL -Added: 7.10.6 -Multi: mutex ---- -Tells curl to figure out authentication method by itself, and use the most -secure one the remote site claims to support. This is done by first doing a -request and checking the response-headers, thus possibly inducing an extra -network round-trip. This is used instead of setting a specific authentication -method, which you can do with --basic, --digest, --ntlm, and --negotiate. - -Using --anyauth is not recommended if you do uploads from stdin, since it may -require data to be sent twice and then the client must be able to rewind. If -the need should arise when uploading from stdin, the upload operation fails. - -Used together with --user. diff --git a/docs/cmdline-opts/anyauth.md b/docs/cmdline-opts/anyauth.md new file mode 100644 index 00000000000..31b27c4adea --- /dev/null +++ b/docs/cmdline-opts/anyauth.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: anyauth +Help: Pick any authentication method +Protocols: HTTP +Category: http proxy auth +Added: 7.10.6 +Multi: mutex +See-also: + - proxy-anyauth + - basic + - digest +Example: + - --anyauth --user me:pwd $URL +--- + +# `--anyauth` + +Figure out authentication method automatically, and use the most secure one +the remote site claims to support. This is done by first doing a request and +checking the response-headers, thus possibly inducing an extra network +round-trip. This option is used instead of setting a specific authentication +method, which you can do with --basic, --digest, --ntlm, and --negotiate. + +Using --anyauth is not recommended if you do uploads from stdin, since it may +require data to be sent twice and then the client must be able to rewind. If +the need should arise when uploading from stdin, the upload operation fails. + +Used together with --user. diff --git a/docs/cmdline-opts/append.d b/docs/cmdline-opts/append.d deleted file mode 100644 index 7561c951c58..00000000000 --- a/docs/cmdline-opts/append.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: a -Long: append -Help: Append to target file when uploading -Protocols: FTP SFTP -Category: ftp sftp -See-also: range continue-at -Example: --upload-file local --append ftp://example.com/ -Added: 4.8 -Multi: boolean ---- -When used in an upload, this option makes curl append to the target file -instead of overwriting it. If the remote file does not exist, it is -created. Note that this flag is ignored by some SFTP servers (including -OpenSSH). diff --git a/docs/cmdline-opts/append.md b/docs/cmdline-opts/append.md new file mode 100644 index 00000000000..3d0030d6a73 --- /dev/null +++ b/docs/cmdline-opts/append.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: a +Long: append +Help: Append to target file when uploading +Protocols: FTP SFTP +Category: ftp sftp +Added: 4.8 +Multi: boolean +See-also: + - range + - continue-at +Example: + - --upload-file local --append ftp://example.com/ +--- + +# `--append` + +When used in an upload, this option makes curl append to the target file +instead of overwriting it. If the remote file does not exist, it is +created. Note that this flag is ignored by some SFTP servers (including +OpenSSH). diff --git a/docs/cmdline-opts/aws-sigv4.d b/docs/cmdline-opts/aws-sigv4.d deleted file mode 100644 index b771eee6a94..00000000000 --- a/docs/cmdline-opts/aws-sigv4.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: aws-sigv4 -Arg: -Help: Use AWS V4 signature authentication -Category: auth http -Added: 7.75.0 -See-also: basic user -Example: --aws-sigv4 "aws:amz:us-east-2:es" --user "key:secret" $URL -Multi: single ---- -Use AWS V4 signature authentication in the transfer. - -The provider argument is a string that is used by the algorithm when creating -outgoing authentication headers. - -The region argument is a string that points to a geographic area of -a resources collection (region-code) when the region name is omitted from -the endpoint. - -The service argument is a string that points to a function provided by a cloud -(service-code) when the service name is omitted from the endpoint. diff --git a/docs/cmdline-opts/aws-sigv4.md b/docs/cmdline-opts/aws-sigv4.md new file mode 100644 index 00000000000..517cc1c5b08 --- /dev/null +++ b/docs/cmdline-opts/aws-sigv4.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: aws-sigv4 +Protocols: HTTP +Arg: +Help: AWS V4 signature auth +Category: auth http +Added: 7.75.0 +Multi: single +See-also: + - basic + - user +Example: + - --aws-sigv4 "aws:amz:us-east-2:es" --user "key:secret" $URL +--- + +# `--aws-sigv4` + +Use AWS V4 signature authentication in the transfer. + +The provider argument is a string that is used by the algorithm when creating +outgoing authentication headers. + +The region argument is a string that points to a geographic area of +a resources collection (region-code) when the region name is omitted from +the endpoint. + +The service argument is a string that points to a function provided by a cloud +(service-code) when the service name is omitted from the endpoint. diff --git a/docs/cmdline-opts/basic.d b/docs/cmdline-opts/basic.d deleted file mode 100644 index cb0642620e5..00000000000 --- a/docs/cmdline-opts/basic.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: basic -Help: Use HTTP Basic Authentication -See-also: proxy-basic -Protocols: HTTP -Category: auth -Example: -u name:password --basic $URL -Added: 7.10.6 -Multi: mutex ---- -Tells curl to use HTTP Basic authentication with the remote host. This is the -default and this option is usually pointless, unless you use it to override a -previously set option that sets a different authentication method (such as ---ntlm, --digest, or --negotiate). - -Used together with --user. diff --git a/docs/cmdline-opts/basic.md b/docs/cmdline-opts/basic.md new file mode 100644 index 00000000000..16acd4cb603 --- /dev/null +++ b/docs/cmdline-opts/basic.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: basic +Help: HTTP Basic Authentication +Protocols: HTTP +Category: auth +Added: 7.10.6 +Multi: mutex +See-also: + - proxy-basic +Example: + - -u name:password --basic $URL +--- + +# `--basic` + +Use HTTP Basic authentication with the remote host. This method is the default +and this option is usually pointless, unless you use it to override a +previously set option that sets a different authentication method (such as +--ntlm, --digest, or --negotiate). + +Used together with --user. diff --git a/docs/cmdline-opts/ca-native.d b/docs/cmdline-opts/ca-native.d deleted file mode 100644 index 51e36918aa6..00000000000 --- a/docs/cmdline-opts/ca-native.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ca-native -Help: Use CA certificates from the native OS -Protocols: TLS -Category: tls -See-also: cacert capath insecure -Example: --ca-native $URL -Added: 8.2.0 -Multi: boolean ---- -Tells curl to use the CA store from the native operating system to verify the -peer. By default, curl otherwise uses a CA store provided in a single file or -directory, but when using this option it interfaces the operating system's -own vault. - -This option only works for curl on Windows when built to use OpenSSL. When -curl on Windows is built to use Schannel, this feature is implied and curl -then only uses the native CA store. - -curl built with wolfSSL also supports this option (added in 8.3.0). diff --git a/docs/cmdline-opts/ca-native.md b/docs/cmdline-opts/ca-native.md new file mode 100644 index 00000000000..a771a7a8133 --- /dev/null +++ b/docs/cmdline-opts/ca-native.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ca-native +Help: Load CA certs from the OS +Protocols: TLS +Category: tls +Added: 8.2.0 +Multi: boolean +See-also: + - cacert + - capath + - insecure +Example: + - --ca-native $URL +--- + +# `--ca-native` + +Use the CA store from the native operating system to verify the peer. By +default, curl otherwise uses a CA store provided in a single file or +directory, but when using this option it interfaces the operating system's own +vault. + +This option works for curl on Windows when built to use OpenSSL, wolfSSL +(added in 8.3.0) or GnuTLS (added in 8.5.0). When curl on Windows is built to +use Schannel, this feature is implied and curl then only uses the native CA +store. diff --git a/docs/cmdline-opts/cacert.d b/docs/cmdline-opts/cacert.d deleted file mode 100644 index 5e4e74901e5..00000000000 --- a/docs/cmdline-opts/cacert.d +++ /dev/null @@ -1,35 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: cacert -Arg: -Help: CA certificate to verify peer against -Protocols: TLS -Category: tls -See-also: capath insecure -Example: --cacert CA-file.txt $URL -Added: 7.5 -Multi: single ---- -Tells curl to use the specified certificate file to verify the peer. The file -may contain multiple CA certificates. The certificate(s) must be in PEM -format. Normally curl is built to use a default file for this, so this option -is typically used to alter that default file. - -curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is -set, and uses the given path as a path to a CA cert bundle. This option -overrides that variable. - -The windows version of curl automatically looks for a CA certs file named -'curl-ca-bundle.crt', either in the same directory as curl.exe, or in the -Current Working Directory, or in any folder along your PATH. - -(iOS and macOS only) If curl is built against Secure Transport, then this -option is supported for backward compatibility with other SSL engines, but it -should not be set. If the option is not set, then curl uses the certificates -in the system and user Keychain to verify the peer, which is the preferred -method of verifying the peer's certificate chain. - -(Schannel only) This option is supported for Schannel in Windows 7 or later -(added in 7.60.0). This option is supported for backward compatibility with -other SSL engines; instead it is recommended to use Windows' store of root -certificates (the default for Schannel). diff --git a/docs/cmdline-opts/cacert.md b/docs/cmdline-opts/cacert.md new file mode 100644 index 00000000000..3268f966def --- /dev/null +++ b/docs/cmdline-opts/cacert.md @@ -0,0 +1,42 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: cacert +Arg: +Help: CA certificate to verify peer against +Protocols: TLS +Category: tls +Added: 7.5 +Multi: single +See-also: + - capath + - insecure +Example: + - --cacert CA-file.txt $URL +--- + +# `--cacert` + +Use the specified certificate file to verify the peer. The file may contain +multiple CA certificates. The certificate(s) must be in PEM format. Normally +curl is built to use a default file for this, so this option is typically used +to alter that default file. + +curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is set +and the TLS backend is not Schannel, and uses the given path as a path to a CA +cert bundle. This option overrides that variable. + +The windows version of curl automatically looks for a CA certs file named +'curl-ca-bundle.crt', either in the same directory as curl.exe, or in the +Current Working Directory, or in any folder along your PATH. + +(iOS and macOS only) If curl is built against Secure Transport, then this +option is supported for backward compatibility with other SSL engines, but it +should not be set. If the option is not set, then curl uses the certificates +in the system and user Keychain to verify the peer, which is the preferred +method of verifying the peer's certificate chain. + +(Schannel only) This option is supported for Schannel in Windows 7 or later +(added in 7.60.0). This option is supported for backward compatibility with +other SSL engines; instead it is recommended to use Windows' store of root +certificates (the default for Schannel). diff --git a/docs/cmdline-opts/capath.d b/docs/cmdline-opts/capath.d deleted file mode 100644 index 75e9f2e400a..00000000000 --- a/docs/cmdline-opts/capath.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: capath -Arg: -Help: CA directory to verify peer against -Protocols: TLS -Category: tls -See-also: cacert insecure -Example: --capath /local/directory $URL -Added: 7.9.8 -Multi: single ---- -Tells curl to use the specified certificate directory to verify the -peer. Multiple paths can be provided by separating them with ":" (e.g. -"path1:path2:path3"). The certificates must be in PEM format, and if curl is -built against OpenSSL, the directory must have been processed using the -c_rehash utility supplied with OpenSSL. Using --capath can allow -OpenSSL-powered curl to make SSL-connections much more efficiently than using ---cacert if the --cacert file contains many CA certificates. - -If this option is set, the default capath value is ignored. diff --git a/docs/cmdline-opts/capath.md b/docs/cmdline-opts/capath.md new file mode 100644 index 00000000000..58919dd4ab1 --- /dev/null +++ b/docs/cmdline-opts/capath.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: capath +Arg: +Help: CA directory to verify peer against +Protocols: TLS +Category: tls +Added: 7.9.8 +Multi: single +See-also: + - cacert + - insecure +Example: + - --capath /local/directory $URL +--- + +# `--capath` + +Use the specified certificate directory to verify the peer. Multiple paths can +be provided by separated with colon (`:`) (e.g. `path1:path2:path3`). The +certificates must be in PEM format, and if curl is built against OpenSSL, the +directory must have been processed using the c_rehash utility supplied with +OpenSSL. Using --capath can allow OpenSSL-powered curl to make SSL-connections +much more efficiently than using --cacert if the --cacert file contains many +CA certificates. + +If this option is set, the default capath value is ignored. diff --git a/docs/cmdline-opts/cert-status.d b/docs/cmdline-opts/cert-status.d deleted file mode 100644 index e2d1d7aa249..00000000000 --- a/docs/cmdline-opts/cert-status.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: cert-status -Protocols: TLS -Added: 7.41.0 -Help: Verify the status of the server cert via OCSP-staple -Category: tls -See-also: pinnedpubkey -Example: --cert-status $URL -Multi: boolean ---- -Tells curl to verify the status of the server certificate by using the -Certificate Status Request (aka. OCSP stapling) TLS extension. - -If this option is enabled and the server sends an invalid (e.g. expired) -response, if the response suggests that the server certificate has been -revoked, or no response at all is received, the verification fails. - -This is currently only implemented in the OpenSSL and GnuTLS backends. diff --git a/docs/cmdline-opts/cert-status.md b/docs/cmdline-opts/cert-status.md new file mode 100644 index 00000000000..8b6e57b9edf --- /dev/null +++ b/docs/cmdline-opts/cert-status.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: cert-status +Protocols: TLS +Added: 7.41.0 +Help: Verify server cert status OCSP-staple +Category: tls +Multi: boolean +See-also: + - pinnedpubkey +Example: + - --cert-status $URL +--- + +# `--cert-status` + +Verify the status of the server certificate by using the Certificate Status +Request (aka. OCSP stapling) TLS extension. + +If this option is enabled and the server sends an invalid (e.g. expired) +response, if the response suggests that the server certificate has been +revoked, or no response at all is received, the verification fails. + +This support is currently only implemented in the OpenSSL and GnuTLS backends. diff --git a/docs/cmdline-opts/cert-type.d b/docs/cmdline-opts/cert-type.d deleted file mode 100644 index cf9f17b7d5b..00000000000 --- a/docs/cmdline-opts/cert-type.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: cert-type -Protocols: TLS -Arg: -Help: Certificate type (DER/PEM/ENG/P12) -See-also: cert key key-type -Category: tls -Example: --cert-type PEM --cert file $URL -Added: 7.9.3 -Multi: single ---- -Tells curl what type the provided client certificate is using. PEM, DER, ENG -and P12 are recognized types. - -The default type depends on the TLS backend and is usually PEM, however for -Secure Transport and Schannel it is P12. If --cert is a pkcs11: URI then ENG is -the default type. diff --git a/docs/cmdline-opts/cert-type.md b/docs/cmdline-opts/cert-type.md new file mode 100644 index 00000000000..d78ab8fa441 --- /dev/null +++ b/docs/cmdline-opts/cert-type.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: cert-type +Protocols: TLS +Arg: +Help: Certificate type (DER/PEM/ENG/P12) +Category: tls +Added: 7.9.3 +Multi: single +See-also: + - cert + - key + - key-type +Example: + - --cert-type PEM --cert file $URL +--- + +# `--cert-type` + +Set type of the provided client certificate. PEM, DER, ENG and P12 are +recognized types. + +The default type depends on the TLS backend and is usually PEM, however for +Secure Transport and Schannel it is P12. If --cert is a pkcs11: URI then ENG is +the default type. diff --git a/docs/cmdline-opts/cert.d b/docs/cmdline-opts/cert.d deleted file mode 100644 index 56d0df7fdf8..00000000000 --- a/docs/cmdline-opts/cert.d +++ /dev/null @@ -1,49 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: E -Long: cert -Arg: -Help: Client certificate file and password -Protocols: TLS -See-also: cert-type key key-type -Category: tls -Example: --cert certfile --key keyfile $URL -Added: 5.0 -Multi: single ---- -Tells curl to use the specified client certificate file when getting a file -with HTTPS, FTPS or another SSL-based protocol. The certificate must be in -PKCS#12 format if using Secure Transport, or PEM format if using any other -engine. If the optional password is not specified, it is queried for on -the terminal. Note that this option assumes a certificate file that is the -private key and the client certificate concatenated. See --cert and --key to -specify them independently. - -In the portion of the argument, you must escape the character ":" -as "\\:" so that it is not recognized as the password delimiter. Similarly, you -must escape the character "\\" as "\\\\" so that it is not recognized as an -escape character. - -If curl is built against OpenSSL library, and the engine pkcs11 is available, -then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in -a PKCS#11 device. A string beginning with "pkcs11:" is interpreted as a -PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as -"pkcs11" if none was provided and the --cert-type option is set as "ENG" if -none was provided. - -(iOS and macOS only) If curl is built against Secure Transport, then the -certificate string can either be the name of a certificate/private key in the -system or user keychain, or the path to a PKCS#12-encoded certificate and -private key. If you want to use a file from the current directory, please -precede it with "./" prefix, in order to avoid confusion with a nickname. - -(Schannel only) Client certificates must be specified by a path -expression to a certificate store. (Loading *PFX* is not supported; you can -import it to a store first). You can use -"\\\\" to refer to a certificate -in the system certificates store, for example, -*"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a"*. Thumbprint is -usually a SHA-1 hex string which you can see in certificate details. Following -store locations are supported: *CurrentUser*, *LocalMachine*, *CurrentService*, -*Services*, *CurrentUserGroupPolicy*, *LocalMachineGroupPolicy* and -*LocalMachineEnterprise*. diff --git a/docs/cmdline-opts/cert.md b/docs/cmdline-opts/cert.md new file mode 100644 index 00000000000..715fcb831a4 --- /dev/null +++ b/docs/cmdline-opts/cert.md @@ -0,0 +1,56 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: E +Long: cert +Arg: +Help: Client certificate file and password +Protocols: TLS +Category: tls +Added: 5.0 +Multi: single +See-also: + - cert-type + - key + - key-type +Example: + - --cert certfile --key keyfile $URL +--- + +# `--cert` + +Use the specified client certificate file when getting a file with HTTPS, FTPS +or another SSL-based protocol. The certificate must be in PKCS#12 format if +using Secure Transport, or PEM format if using any other engine. If the +optional password is not specified, it is queried for on the terminal. Note +that this option assumes a certificate file that is the private key and the +client certificate concatenated. See --cert and --key to specify them +independently. + +In the \ portion of the argument, you must escape the character +`:` as `\:` so that it is not recognized as the password delimiter. Similarly, +you must escape the double quote character as \" so that it is not recognized +as an escape character. + +If curl is built against OpenSSL library, and the engine pkcs11 is available, +then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in +a PKCS#11 device. A string beginning with `pkcs11:` is interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as +`pkcs11` if none was provided and the --cert-type option is set as `ENG` if +none was provided. + +(iOS and macOS only) If curl is built against Secure Transport, then the +certificate string can either be the name of a certificate/private key in the +system or user keychain, or the path to a PKCS#12-encoded certificate and +private key. If you want to use a file from the current directory, please +precede it with `./` prefix, in order to avoid confusion with a nickname. + +(Schannel only) Client certificates must be specified by a path expression to +a certificate store. (Loading *PFX* is not supported; you can import it to a +store first). You can use "\\\\\" +to refer to a certificate in the system certificates store, for example, +*"CurrentUser\MY\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a"*. Thumbprint is +usually a SHA-1 hex string which you can see in certificate details. Following +store locations are supported: *CurrentUser*, *LocalMachine*, +*CurrentService*, *Services*, *CurrentUserGroupPolicy*, +*LocalMachineGroupPolicy* and *LocalMachineEnterprise*. diff --git a/docs/cmdline-opts/ciphers.d b/docs/cmdline-opts/ciphers.d deleted file mode 100644 index a30902bdb87..00000000000 --- a/docs/cmdline-opts/ciphers.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ciphers -Arg: -Help: SSL ciphers to use -Protocols: TLS -Category: tls -See-also: tlsv1.3 tls13-ciphers proxy-ciphers -Example: --ciphers ECDHE-ECDSA-AES256-CCM8 $URL -Added: 7.9 -Multi: single ---- -Specifies which ciphers to use in the connection. The list of ciphers must -specify valid ciphers. Read up on SSL cipher list details on this URL: - -https://curl.se/docs/ssl-ciphers.html diff --git a/docs/cmdline-opts/ciphers.md b/docs/cmdline-opts/ciphers.md new file mode 100644 index 00000000000..9d7e0c6fe03 --- /dev/null +++ b/docs/cmdline-opts/ciphers.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ciphers +Arg: +Help: SSL ciphers to use +Protocols: TLS +Category: tls +Added: 7.9 +Multi: single +See-also: + - tlsv1.3 + - tls13-ciphers + - proxy-ciphers +Example: + - --ciphers ECDHE-ECDSA-AES256-CCM8 $URL +--- + +# `--ciphers` + +Specifies which ciphers to use in the connection. The list of ciphers must +specify valid ciphers. Read up on SSL cipher list details on this URL: + +https://curl.se/docs/ssl-ciphers.html diff --git a/docs/cmdline-opts/compressed-ssh.d b/docs/cmdline-opts/compressed-ssh.d deleted file mode 100644 index 897395677bc..00000000000 --- a/docs/cmdline-opts/compressed-ssh.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: compressed-ssh -Help: Enable SSH compression -Protocols: SCP SFTP -Added: 7.56.0 -Category: scp ssh -See-also: compressed -Example: --compressed-ssh sftp://example.com/ -Multi: boolean ---- -Enables built-in SSH compression. -This is a request, not an order; the server may or may not do it. diff --git a/docs/cmdline-opts/compressed-ssh.md b/docs/cmdline-opts/compressed-ssh.md new file mode 100644 index 00000000000..b404f62d5d2 --- /dev/null +++ b/docs/cmdline-opts/compressed-ssh.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: compressed-ssh +Help: Enable SSH compression +Protocols: SCP SFTP +Added: 7.56.0 +Category: scp ssh +Multi: boolean +See-also: + - compressed +Example: + - --compressed-ssh sftp://example.com/ +--- + +# `--compressed-ssh` + +Enables built-in SSH compression. This is a request, not an order; the server +may or may not do it. diff --git a/docs/cmdline-opts/compressed.d b/docs/cmdline-opts/compressed.d deleted file mode 100644 index bb1d3baa744..00000000000 --- a/docs/cmdline-opts/compressed.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: compressed -Help: Request compressed response -Protocols: HTTP -Category: http -Example: --compressed $URL -See-also: compressed-ssh -Added: 7.10 -Multi: boolean ---- -Request a compressed response using one of the algorithms curl supports, and -automatically decompress the content. - -Response headers are not modified when saved, so if they are "interpreted" -separately again at a later point they might appear to be saying that the -content is (still) compressed; while in fact it has already been decompressed. - -If this option is used and the server sends an unsupported encoding, curl -reports an error. This is a request, not an order; the server may or may not -deliver data compressed. diff --git a/docs/cmdline-opts/compressed.md b/docs/cmdline-opts/compressed.md new file mode 100644 index 00000000000..35bbab81396 --- /dev/null +++ b/docs/cmdline-opts/compressed.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: compressed +Help: Request compressed response +Protocols: HTTP +Category: http +Added: 7.10 +Multi: boolean +See-also: + - compressed-ssh +Example: + - --compressed $URL +--- + +# `--compressed` + +Request a compressed response using one of the algorithms curl supports, and +automatically decompress the content. + +Response headers are not modified when saved, so if they are "interpreted" +separately again at a later point they might appear to be saying that the +content is (still) compressed; while in fact it has already been decompressed. + +If this option is used and the server sends an unsupported encoding, curl +reports an error. This is a request, not an order; the server may or may not +deliver data compressed. diff --git a/docs/cmdline-opts/config.d b/docs/cmdline-opts/config.d deleted file mode 100644 index c22a827f617..00000000000 --- a/docs/cmdline-opts/config.d +++ /dev/null @@ -1,77 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: config -Arg: -Help: Read config from a file -Short: K -Category: curl -Example: --config file.txt $URL -Added: 4.10 -See-also: disable -Multi: append ---- -Specify a text file to read curl arguments from. The command line arguments -found in the text file are used as if they were provided on the command -line. - -Options and their parameters must be specified on the same line in the file, -separated by whitespace, colon, or the equals sign. Long option names can -optionally be given in the config file without the initial double dashes and -if so, the colon or equals characters can be used as separators. If the option -is specified with one or two dashes, there can be no colon or equals character -between the option and its parameter. - -If the parameter contains whitespace or starts with a colon (:) or equals sign -(=), it must be specified enclosed within double quotes (\&"). Within double -quotes the following escape sequences are available: \\\\, \\", \\t, \\n, \\r -and \\v. A backslash preceding any other letter is ignored. - -If the first non-blank column of a config line is a '#' character, that line -is treated as a comment. - -Only write one option per physical line in the config file. A single line is -required to be no more than 10 megabytes (since 8.2.0). - -Specify the filename to --config as '-' to make curl read the file from stdin. - -Note that to be able to specify a URL in the config file, you need to specify -it using the --url option, and not by simply writing the URL on its own -line. So, it could look similar to this: - -url = "https://curl.se/docs/" - - # --- Example file --- - # this is a comment - url = "example.com" - output = "curlhere.html" - user-agent = "superagent/1.0" - - # and fetch another URL too - url = "example.com/docs/manpage.html" - -O - referer = "http://nowhereatall.example.com/" - # --- End of example file --- - -When curl is invoked, it (unless --disable is used) checks for a default -config file and uses it if found, even when --config is used. The default -config file is checked for in the following places in this order: - -1) **"$CURL_HOME/.curlrc"** - -2) **"$XDG_CONFIG_HOME/curlrc"** (Added in 7.73.0) - -3) **"$HOME/.curlrc"** - -4) Windows: **"%USERPROFILE%\\.curlrc"** - -5) Windows: **"%APPDATA%\\.curlrc"** - -6) Windows: **"%USERPROFILE%\\Application Data\\.curlrc"** - -7) Non-Windows: use getpwuid to find the home directory - -8) On Windows, if it finds no *.curlrc* file in the sequence described above, it -checks for one in the same dir the curl executable is placed. - -On Windows two filenames are checked per location: *.curlrc* and *_curlrc*, -preferring the former. Older versions on Windows checked for *_curlrc* only. diff --git a/docs/cmdline-opts/config.md b/docs/cmdline-opts/config.md new file mode 100644 index 00000000000..1281a3d9c9f --- /dev/null +++ b/docs/cmdline-opts/config.md @@ -0,0 +1,84 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: config +Arg: +Help: Read config from a file +Short: K +Category: curl +Added: 4.10 +Multi: append +See-also: + - disable +Example: + - --config file.txt $URL +--- + +# `--config` + +Specify a text file to read curl arguments from. The command line arguments +found in the text file are used as if they were provided on the command +line. + +Options and their parameters must be specified on the same line in the file, +separated by whitespace, colon, or the equals sign. Long option names can +optionally be given in the config file without the initial double dashes and +if so, the colon or equals characters can be used as separators. If the option +is specified with one or two dashes, there can be no colon or equals character +between the option and its parameter. + +If the parameter contains whitespace or starts with a colon (:) or equals sign +(=), it must be specified enclosed within double quotes ("like this"). Within +double quotes the following escape sequences are available: \\, \", \t, \n, \r +and \v. A backslash preceding any other letter is ignored. + +If the first non-blank column of a config line is a '#' character, that line +is treated as a comment. + +Only write one option per physical line in the config file. A single line is +required to be no more than 10 megabytes (since 8.2.0). + +Specify the filename to --config as minus "-" to make curl read the file from +stdin. + +Note that to be able to specify a URL in the config file, you need to specify +it using the --url option, and not by simply writing the URL on its own +line. So, it could look similar to this: + + url = "https://curl.se/docs/" + + # --- Example file --- + # this is a comment + url = "example.com" + output = "curlhere.html" + user-agent = "superagent/1.0" + + # and fetch another URL too + url = "example.com/docs/manpage.html" + -O + referer = "http://nowhereatall.example.com/" + # --- End of example file --- + +When curl is invoked, it (unless --disable is used) checks for a default +config file and uses it if found, even when --config is used. The default +config file is checked for in the following places in this order: + +1) **"$CURL_HOME/.curlrc"** + +2) **"$XDG_CONFIG_HOME/curlrc"** (Added in 7.73.0) + +3) **"$HOME/.curlrc"** + +4) Windows: **"%USERPROFILE%\.curlrc"** + +5) Windows: **"%APPDATA%\.curlrc"** + +6) Windows: **"%USERPROFILE%\Application Data\.curlrc"** + +7) Non-Windows: use getpwuid to find the home directory + +8) On Windows, if it finds no *.curlrc* file in the sequence described above, it +checks for one in the same directory the curl executable is placed. + +On Windows two filenames are checked per location: *.curlrc* and *_curlrc*, +preferring the former. Older versions on Windows checked for *_curlrc* only. diff --git a/docs/cmdline-opts/connect-timeout.d b/docs/cmdline-opts/connect-timeout.d deleted file mode 100644 index b3d19b3c332..00000000000 --- a/docs/cmdline-opts/connect-timeout.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: connect-timeout -Arg: -Help: Maximum time allowed for connection -See-also: max-time -Category: connection -Example: --connect-timeout 20 $URL -Example: --connect-timeout 3.14 $URL -Added: 7.7 -Multi: single ---- -Maximum time in seconds that you allow curl's connection to take. This only -limits the connection phase, so if curl connects within the given period it -continues - if not it exits. - -This option accepts decimal values (added in 7.32.0). The decimal value needs -to be provided using a dot (.) as decimal separator - not the local version -even if it might be using another separator. - -The connection phase is considered complete when the DNS lookup and requested -TCP, TLS or QUIC handshakes are done. diff --git a/docs/cmdline-opts/connect-timeout.md b/docs/cmdline-opts/connect-timeout.md new file mode 100644 index 00000000000..e1400811e9d --- /dev/null +++ b/docs/cmdline-opts/connect-timeout.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: connect-timeout +Arg: +Help: Maximum time allowed to connect +Category: connection +Added: 7.7 +Multi: single +See-also: + - max-time +Example: + - --connect-timeout 20 $URL + - --connect-timeout 3.14 $URL +--- + +# `--connect-timeout` + +Maximum time in seconds that you allow curl's connection to take. This only +limits the connection phase, so if curl connects within the given period it +continues - if not it exits. + +This option accepts decimal values (added in 7.32.0). The decimal value needs +to be provided using a dot (.) as decimal separator - not the local version +even if it might be using another separator. + +The connection phase is considered complete when the DNS lookup and requested +TCP, TLS or QUIC handshakes are done. diff --git a/docs/cmdline-opts/connect-to.d b/docs/cmdline-opts/connect-to.d deleted file mode 100644 index 95fab91121b..00000000000 --- a/docs/cmdline-opts/connect-to.d +++ /dev/null @@ -1,24 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: connect-to -Arg: -Help: Connect to host -Added: 7.49.0 -See-also: resolve header -Category: connection -Example: --connect-to example.com:443:example.net:8443 $URL -Multi: append ---- - -For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead. -This option is suitable to direct requests at a specific server, e.g. at a -specific cluster node in a cluster of servers. This option is only used to -establish the network connection. It does NOT affect the hostname/port that is -used for TLS/SSL (e.g. SNI, certificate verification) or for the application -protocols. "HOST1" and "PORT1" may be the empty string, meaning "any -host/port". "HOST2" and "PORT2" may also be the empty string, meaning "use the -request's original host/port". - -A "host" specified to this option is compared as a string, so it needs to -match the name used in request URL. It can be either numerical such as -"127.0.0.1" or the full host name such as "example.org". diff --git a/docs/cmdline-opts/connect-to.md b/docs/cmdline-opts/connect-to.md new file mode 100644 index 00000000000..360ef0da203 --- /dev/null +++ b/docs/cmdline-opts/connect-to.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: connect-to +Arg: +Help: Connect to host +Added: 7.49.0 +Category: connection +Multi: append +See-also: + - resolve + - header +Example: + - --connect-to example.com:443:example.net:8443 $URL +--- + +# `--connect-to` + +For a request intended for the `HOST1:PORT1` pair, connect to `HOST2:PORT2` +instead. This option is only used to establish the network connection. It does +NOT affect the hostname/port number that is used for TLS/SSL (e.g. SNI, +certificate verification) or for the application protocols. + +`HOST1` and `PORT1` may be empty strings, meaning any host or any port number. +`HOST2` and `PORT2` may also be empty strings, meaning use the request's +original hostname and port number. + +A hostname specified to this option is compared as a string, so it needs to +match the name used in request URL. It can be either numerical such as +`127.0.0.1` or the full host name such as `example.org`. diff --git a/docs/cmdline-opts/continue-at.d b/docs/cmdline-opts/continue-at.d deleted file mode 100644 index a4fc1a96950..00000000000 --- a/docs/cmdline-opts/continue-at.d +++ /dev/null @@ -1,20 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: C -Long: continue-at -Arg: -Help: Resumed transfer offset -See-also: range -Category: connection -Example: -C - $URL -Example: -C 400 $URL -Added: 4.8 -Multi: single ---- -Continue/Resume a previous file transfer at the given offset. The given offset -is the exact number of bytes that are skipped, counting from the beginning -of the source file before it is transferred to the destination. If used with -uploads, the FTP server command SIZE is not used by curl. - -Use "-C -" to tell curl to automatically find out where/how to resume the -transfer. It then uses the given output/input files to figure that out. diff --git a/docs/cmdline-opts/continue-at.md b/docs/cmdline-opts/continue-at.md new file mode 100644 index 00000000000..978cafc01f7 --- /dev/null +++ b/docs/cmdline-opts/continue-at.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: C +Long: continue-at +Arg: +Help: Resumed transfer offset +Category: connection +Added: 4.8 +Multi: single +See-also: + - range +Example: + - -C - $URL + - -C 400 $URL +--- + +# `--continue-at` + +Resume a previous transfer from the given byte offset. The given offset is the +exact number of bytes that are skipped, counting from the beginning of the +source file before it is transferred to the destination. If used with uploads, +the FTP server command SIZE is not used by curl. + +Use "-C -" to instruct curl to automatically find out where/how to resume the +transfer. It then uses the given output/input files to figure that out. diff --git a/docs/cmdline-opts/cookie-jar.d b/docs/cmdline-opts/cookie-jar.d deleted file mode 100644 index 28738cac946..00000000000 --- a/docs/cmdline-opts/cookie-jar.d +++ /dev/null @@ -1,31 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: c -Long: cookie-jar -Arg: -Protocols: HTTP -Help: Write cookies to after operation -Category: http -Example: -c store-here.txt $URL -Example: -c store-here.txt -b read-these $URL -Added: 7.9 -See-also: cookie -Multi: single ---- -Specify to which file you want curl to write all cookies after a completed -operation. Curl writes all cookies from its in-memory cookie storage to the -given file at the end of operations. If no cookies are known, no data is -written. The file is created using the Netscape cookie file format. If you set -the file name to a single dash, "-", the cookies are written to stdout. - -The file specified with --cookie-jar is only used for output. No cookies are -read from the file. To read cookies, use the --cookie option. Both options -can specify the same file. - -This command line option activates the cookie engine that makes curl record -and use cookies. The --cookie option also activates it. - -If the cookie jar cannot be created or written to, the whole curl operation -does not fail or even report an error clearly. Using --verbose gets a warning -displayed, but that is the only visible feedback you get about this possibly -lethal situation. diff --git a/docs/cmdline-opts/cookie-jar.md b/docs/cmdline-opts/cookie-jar.md new file mode 100644 index 00000000000..f993685916b --- /dev/null +++ b/docs/cmdline-opts/cookie-jar.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: c +Long: cookie-jar +Arg: +Protocols: HTTP +Help: Save cookies to after operation +Category: http +Added: 7.9 +Multi: single +See-also: + - cookie +Example: + - -c store-here.txt $URL + - -c store-here.txt -b read-these $URL +--- + +# `--cookie-jar` + +Specify to which file you want curl to write all cookies after a completed +operation. Curl writes all cookies from its in-memory cookie storage to the +given file at the end of operations. Even if no cookies are known, a file is +created so that it removes any formerly existing cookies from the file. The +file uses the Netscape cookie file format. If you set the filename to a single +minus, "-", the cookies are written to stdout. + +The file specified with --cookie-jar is only used for output. No cookies are +read from the file. To read cookies, use the --cookie option. Both options +can specify the same file. + +This command line option activates the cookie engine that makes curl record +and use cookies. The --cookie option also activates it. + +If the cookie jar cannot be created or written to, the whole curl operation +does not fail or even report an error clearly. Using --verbose gets a warning +displayed, but that is the only visible feedback you get about this possibly +lethal situation. diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d deleted file mode 100644 index 0f858d6613b..00000000000 --- a/docs/cmdline-opts/cookie.d +++ /dev/null @@ -1,42 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: b -Long: cookie -Arg: -Protocols: HTTP -Help: Send cookies from string/file -Category: http -Example: -b cookiefile $URL -Example: -b cookiefile -c cookiefile $URL -See-also: cookie-jar junk-session-cookies -Added: 4.9 -Multi: append ---- -Pass the data to the HTTP server in the Cookie header. It is supposedly the -data previously received from the server in a "Set-Cookie:" line. The data -should be in the format "NAME1=VALUE1; NAME2=VALUE2". This makes curl use the -cookie header with this content explicitly in all outgoing request(s). If -multiple requests are done due to authentication, followed redirects or -similar, they all get this cookie passed on. - -If no '=' symbol is used in the argument, it is instead treated as a filename -to read previously stored cookie from. This option also activates the cookie -engine which makes curl record incoming cookies, which may be handy if you are -using this in combination with the --location option or do multiple URL -transfers on the same invoke. If the file name is exactly a minus ("-"), curl -instead reads the contents from stdin. - -The file format of the file to read cookies from should be plain HTTP headers -(Set-Cookie style) or the Netscape/Mozilla cookie file format. - -The file specified with --cookie is only used as input. No cookies are written -to the file. To store cookies, use the --cookie-jar option. - -If you use the Set-Cookie file format and do not specify a domain then the -cookie is not sent since the domain never matches. To address this, set a -domain in Set-Cookie line (doing that includes subdomains) or preferably: use -the Netscape format. - -Users often want to both read cookies from a file and write updated cookies -back to a file, so using both --cookie and --cookie-jar in the same command -line is common. diff --git a/docs/cmdline-opts/cookie.md b/docs/cmdline-opts/cookie.md new file mode 100644 index 00000000000..cbc8b84572a --- /dev/null +++ b/docs/cmdline-opts/cookie.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: b +Long: cookie +Arg: +Protocols: HTTP +Help: Send cookies from string/load from file +Category: http +Added: 4.9 +Multi: append +See-also: + - cookie-jar + - junk-session-cookies +Example: + - -b "" $URL + - -b cookiefile $URL + - -b cookiefile -c cookiefile $URL + - -b name=Jane $URL +--- + +# `--cookie` + +Pass the data to the HTTP server in the Cookie header. It is supposedly the +data previously received from the server in a `Set-Cookie:` line. The data +should be in the format `NAME1=VALUE1; NAME2=VALUE2` or as a single filename. + +When given a set of specific cookies and not a filename, it makes curl use the +cookie header with this content explicitly in all outgoing request(s). If +multiple requests are done due to authentication, followed redirects or +similar, they all get this cookie header passed on. + +If no `=` symbol is used in the argument, it is instead treated as a filename +to read previously stored cookie from. This option also activates the cookie +engine which makes curl record incoming cookies, which may be handy if you are +using this in combination with the --location option or do multiple URL +transfers on the same invoke. + +If the filename is a single minus ("-"), curl reads the contents from stdin. +If the filename is an empty string ("") and is the only cookie input, curl +activates the cookie engine without any cookies. + +The file format of the file to read cookies from should be plain HTTP headers +(Set-Cookie style) or the Netscape/Mozilla cookie file format. + +The file specified with --cookie is only used as input. No cookies are written +to that file. To store cookies, use the --cookie-jar option. + +If you use the Set-Cookie file format and do not specify a domain then the +cookie is not sent since the domain never matches. To address this, set a +domain in Set-Cookie line (doing that includes subdomains) or preferably: use +the Netscape format. + +Users often want to both read cookies from a file and write updated cookies +back to a file, so using both --cookie and --cookie-jar in the same command +line is common. + +If curl is built with PSL (**Public Suffix List**) support, it detects and +discards cookies that are specified for such suffix domains that should not be +allowed to have cookies. If curl is *not* built with PSL support, it has no +ability to stop super cookies. diff --git a/docs/cmdline-opts/create-dirs.d b/docs/cmdline-opts/create-dirs.d deleted file mode 100644 index 966b70384ee..00000000000 --- a/docs/cmdline-opts/create-dirs.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: create-dirs -Help: Create necessary local directory hierarchy -Category: curl -Example: --create-dirs --output local/dir/file $URL -Added: 7.10.3 -See-also: ftp-create-dirs output-dir -Multi: boolean ---- -When used in conjunction with the --output option, curl creates the necessary -local directory hierarchy as needed. This option creates the directories -mentioned with the --output option combined with the path possibly set with ---output-dir. If the combined output file name uses no directory, or if the -directories it mentions already exist, no directories are created. - -Created directories are made with mode 0750 on unix style file systems. - -To create remote directories when using FTP or SFTP, try --ftp-create-dirs. diff --git a/docs/cmdline-opts/create-dirs.md b/docs/cmdline-opts/create-dirs.md new file mode 100644 index 00000000000..fcbeb3343b6 --- /dev/null +++ b/docs/cmdline-opts/create-dirs.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: create-dirs +Help: Create necessary local directory hierarchy +Category: curl +Added: 7.10.3 +Multi: boolean +See-also: + - ftp-create-dirs + - output-dir +Example: + - --create-dirs --output local/dir/file $URL +--- + +# `--create-dirs` + +When used in conjunction with the --output option, curl creates the necessary +local directory hierarchy as needed. This option creates the directories +mentioned with the --output option combined with the path possibly set with +--output-dir. If the combined output filename uses no directory, or if the +directories it mentions already exist, no directories are created. + +Created directories are made with mode 0750 on unix style file systems. + +To create remote directories when using FTP or SFTP, try --ftp-create-dirs. diff --git a/docs/cmdline-opts/create-file-mode.d b/docs/cmdline-opts/create-file-mode.d deleted file mode 100644 index c0ebc08d449..00000000000 --- a/docs/cmdline-opts/create-file-mode.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: create-file-mode -Arg: -Help: File mode for created files -Protocols: SFTP SCP FILE -Category: sftp scp file upload -See-also: ftp-create-dirs -Added: 7.75.0 -Example: --create-file-mode 0777 -T localfile sftp://example.com/new -Multi: single ---- -When curl is used to create files remotely using one of the supported -protocols, this option allows the user to set which 'mode' to set on the file -at creation time, instead of the default 0644. - -This option takes an octal number as argument. diff --git a/docs/cmdline-opts/create-file-mode.md b/docs/cmdline-opts/create-file-mode.md new file mode 100644 index 00000000000..c6467d15a4d --- /dev/null +++ b/docs/cmdline-opts/create-file-mode.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: create-file-mode +Arg: +Help: File mode for created files +Protocols: SFTP SCP FILE +Category: sftp scp file upload +Added: 7.75.0 +Multi: single +See-also: + - ftp-create-dirs +Example: + - --create-file-mode 0777 -T localfile sftp://example.com/new +--- + +# `--create-file-mode` + +When curl is used to create files remotely using one of the supported +protocols, this option allows the user to set which 'mode' to set on the file +at creation time, instead of the default 0644. + +This option takes an octal number as argument. diff --git a/docs/cmdline-opts/crlf.d b/docs/cmdline-opts/crlf.d deleted file mode 100644 index ea7fb1526ab..00000000000 --- a/docs/cmdline-opts/crlf.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: crlf -Help: Convert LF to CRLF in upload -Protocols: FTP SMTP -Category: ftp smtp -Example: --crlf -T file ftp://example.com/ -Added: 5.7 -See-also: use-ascii -Multi: boolean ---- -Convert line feeds to carriage return plus line feeds in upload. Useful for -**MVS (OS/390)**. - -(SMTP added in 7.40.0) diff --git a/docs/cmdline-opts/crlf.md b/docs/cmdline-opts/crlf.md new file mode 100644 index 00000000000..81a14ef6fd9 --- /dev/null +++ b/docs/cmdline-opts/crlf.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: crlf +Help: Convert LF to CRLF in upload +Protocols: FTP SMTP +Category: ftp smtp +Added: 5.7 +Multi: boolean +See-also: + - use-ascii +Example: + - --crlf -T file ftp://example.com/ +--- + +# `--crlf` + +Convert line feeds to carriage return plus line feeds in upload. Useful for +**MVS (OS/390)**. + +(SMTP added in 7.40.0) diff --git a/docs/cmdline-opts/crlfile.d b/docs/cmdline-opts/crlfile.d deleted file mode 100644 index da0d239bad7..00000000000 --- a/docs/cmdline-opts/crlfile.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: crlfile -Arg: -Protocols: TLS -Help: Use this CRL list -Added: 7.19.7 -Category: tls -Example: --crlfile rejects.txt $URL -See-also: cacert capath -Multi: single ---- -Provide a file using PEM format with a Certificate Revocation List that may -specify peer certificates that are to be considered revoked. diff --git a/docs/cmdline-opts/crlfile.md b/docs/cmdline-opts/crlfile.md new file mode 100644 index 00000000000..a762af09f11 --- /dev/null +++ b/docs/cmdline-opts/crlfile.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: crlfile +Arg: +Protocols: TLS +Help: Certificate Revocation list +Added: 7.19.7 +Category: tls +Multi: single +See-also: + - cacert + - capath +Example: + - --crlfile rejects.txt $URL +--- + +# `--crlfile` + +Provide a file using PEM format with a Certificate Revocation List that may +specify peer certificates that are to be considered revoked. diff --git a/docs/cmdline-opts/curves.d b/docs/cmdline-opts/curves.d deleted file mode 100644 index 58d472d20df..00000000000 --- a/docs/cmdline-opts/curves.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: curves -Arg: -Help: (EC) TLS key exchange algorithm(s) to request -Protocols: TLS -Added: 7.73.0 -Category: tls -Example: --curves X25519 $URL -See-also: ciphers -Multi: single ---- -Tells curl to request specific curves to use during SSL session establishment -according to RFC 8422, 5.1. Multiple algorithms can be provided by separating -them with ":" (e.g. "X25519:P-521"). The parameter is available identically -in the "openssl s_client/s_server" utilities. - ---curves allows a OpenSSL powered curl to make SSL-connections with exactly -the (EC) curve requested by the client, avoiding nontransparent client/server -negotiations. - -If this option is set, the default curves list built into OpenSSL are ignored. diff --git a/docs/cmdline-opts/curves.md b/docs/cmdline-opts/curves.md new file mode 100644 index 00000000000..9473aeaa7a8 --- /dev/null +++ b/docs/cmdline-opts/curves.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: curves +Arg: +Help: (EC) TLS key exchange algorithms to request +Protocols: TLS +Added: 7.73.0 +Category: tls +Multi: single +See-also: + - ciphers +Example: + - --curves X25519 $URL +--- + +# `--curves` + +Set specific curves to use during SSL session establishment according to RFC +8422, 5.1. Multiple algorithms can be provided by separating them with `:` +(e.g. `X25519:P-521`). The parameter is available identically in the OpenSSL +`s_client` and `s_server` utilities. + +--curves allows a OpenSSL powered curl to make SSL-connections with exactly +the (EC) curve requested by the client, avoiding nontransparent client/server +negotiations. + +If this option is set, the default curves list built into OpenSSL are ignored. diff --git a/docs/cmdline-opts/data-ascii.d b/docs/cmdline-opts/data-ascii.d deleted file mode 100644 index 5c7840bbc4f..00000000000 --- a/docs/cmdline-opts/data-ascii.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: data-ascii -Arg: -Help: HTTP POST ASCII data -Protocols: HTTP -Category: http post upload -Example: --data-ascii @file $URL -Added: 7.2 -See-also: data-binary data-raw data-urlencode -Multi: append ---- -This is just an alias for --data. diff --git a/docs/cmdline-opts/data-ascii.md b/docs/cmdline-opts/data-ascii.md new file mode 100644 index 00000000000..5763d81f193 --- /dev/null +++ b/docs/cmdline-opts/data-ascii.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: data-ascii +Arg: +Help: HTTP POST ASCII data +Protocols: HTTP +Category: http post upload +Added: 7.2 +Multi: append +See-also: + - data-binary + - data-raw + - data-urlencode +Example: + - --data-ascii @file $URL +--- + +# `--data-ascii` + +This option is just an alias for --data. diff --git a/docs/cmdline-opts/data-binary.d b/docs/cmdline-opts/data-binary.d deleted file mode 100644 index 2cedda97b04..00000000000 --- a/docs/cmdline-opts/data-binary.d +++ /dev/null @@ -1,25 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: data-binary -Arg: -Help: HTTP POST binary data -Protocols: HTTP -Category: http post upload -Example: --data-binary @filename $URL -Added: 7.2 -See-also: data-ascii -Multi: append ---- -This posts data exactly as specified with no extra processing whatsoever. - -If you start the data with the letter @, the rest should be a filename. Data -is posted in a similar manner as --data does, except that newlines and -carriage returns are preserved and conversions are never done. - -Like --data the default content-type sent to the server is -application/x-www-form-urlencoded. If you want the data to be treated as -arbitrary binary data by the server then set the content-type to octet-stream: --H "Content-Type: application/octet-stream". - -If this option is used several times, the ones following the first append -data as described in --data. diff --git a/docs/cmdline-opts/data-binary.md b/docs/cmdline-opts/data-binary.md new file mode 100644 index 00000000000..1ce53b32c67 --- /dev/null +++ b/docs/cmdline-opts/data-binary.md @@ -0,0 +1,31 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: data-binary +Arg: +Help: HTTP POST binary data +Protocols: HTTP +Category: http post upload +Added: 7.2 +Multi: append +See-also: + - data-ascii +Example: + - --data-binary @filename $URL +--- + +# `--data-binary` + +Post data exactly as specified with no extra processing whatsoever. + +If you start the data with the letter @, the rest should be a filename. Data +is posted in a similar manner as --data does, except that newlines and +carriage returns are preserved and conversions are never done. + +Like --data the default content-type sent to the server is +application/x-www-form-urlencoded. If you want the data to be treated as +arbitrary binary data by the server then set the content-type to octet-stream: +-H "Content-Type: application/octet-stream". + +If this option is used several times, the ones following the first append +data as described in --data. diff --git a/docs/cmdline-opts/data-raw.d b/docs/cmdline-opts/data-raw.d deleted file mode 100644 index e6a5a5b2b9e..00000000000 --- a/docs/cmdline-opts/data-raw.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: data-raw -Arg: -Protocols: HTTP -Help: HTTP POST data, '@' allowed -Added: 7.43.0 -See-also: data -Category: http post upload -Example: --data-raw "hello" $URL -Example: --data-raw "@at@at@" $URL -Multi: append ---- -This posts data similarly to --data but without the special -interpretation of the @ character. diff --git a/docs/cmdline-opts/data-raw.md b/docs/cmdline-opts/data-raw.md new file mode 100644 index 00000000000..1033678bdea --- /dev/null +++ b/docs/cmdline-opts/data-raw.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: data-raw +Arg: +Protocols: HTTP +Help: HTTP POST data, '@' allowed +Added: 7.43.0 +Category: http post upload +Multi: append +See-also: + - data +Example: + - --data-raw "hello" $URL + - --data-raw "@at@at@" $URL +--- + +# `--data-raw` + +Post data similarly to --data but without the special interpretation of the @ +character. diff --git a/docs/cmdline-opts/data-urlencode.d b/docs/cmdline-opts/data-urlencode.d deleted file mode 100644 index 3c436b26b15..00000000000 --- a/docs/cmdline-opts/data-urlencode.d +++ /dev/null @@ -1,42 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: data-urlencode -Arg: -Help: HTTP POST data URL encoded -Protocols: HTTP -See-also: data data-raw -Added: 7.18.0 -Category: http post upload -Example: --data-urlencode name=val $URL -Example: --data-urlencode =encodethis $URL -Example: --data-urlencode name@file $URL -Example: --data-urlencode @fileonly $URL -Multi: append ---- -This posts data, similar to the other --data options with the exception -that this performs URL-encoding. - -To be CGI-compliant, the part should begin with a *name* followed -by a separator and a content specification. The part can be passed to -curl using one of the following syntaxes: -.RS -.IP "content" -This makes curl URL-encode the content and pass that on. Just be careful -so that the content does not contain any = or @ symbols, as that makes -the syntax match one of the other cases below! -.IP "=content" -This makes curl URL-encode the content and pass that on. The preceding = -symbol is not included in the data. -.IP "name=content" -This makes curl URL-encode the content part and pass that on. Note that -the name part is expected to be URL-encoded already. -.IP "@filename" -This makes curl load data from the given file (including any newlines), -URL-encode that data and pass it on in the POST. -.IP "name@filename" -This makes curl load data from the given file (including any newlines), -URL-encode that data and pass it on in the POST. The name part gets an equal -sign appended, resulting in *name=urlencoded-file-content*. Note that the -name is expected to be URL-encoded already. -.RE -.IP diff --git a/docs/cmdline-opts/data-urlencode.md b/docs/cmdline-opts/data-urlencode.md new file mode 100644 index 00000000000..2bd84f3f160 --- /dev/null +++ b/docs/cmdline-opts/data-urlencode.md @@ -0,0 +1,51 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: data-urlencode +Arg: +Help: HTTP POST data URL encoded +Protocols: HTTP +Added: 7.18.0 +Category: http post upload +Multi: append +See-also: + - data + - data-raw +Example: + - --data-urlencode name=val $URL + - --data-urlencode =encodethis $URL + - --data-urlencode name@file $URL + - --data-urlencode @fileonly $URL +--- + +# `--data-urlencode` + +Post data, similar to the other --data options with the exception that this +performs URL-encoding. + +To be CGI-compliant, the \ part should begin with a *name* followed by +a separator and a content specification. The \ part can be passed to +curl using one of the following syntaxes: + +## content +URL-encode the content and pass that on. Just be careful so that the content +does not contain any `=` or `@` symbols, as that makes the syntax match one of +the other cases below! + +## =content +URL-encode the content and pass that on. The preceding `=` symbol is not +included in the data. + +## name=content +URL-encode the content part and pass that on. Note that the name part is +expected to be URL-encoded already. + +## @filename +load data from the given file (including any newlines), URL-encode that data +and pass it on in the POST. + +## name@filename +load data from the given file (including any newlines), URL-encode that data +and pass it on in the POST. The name part gets an equal sign appended, +resulting in *name=urlencoded-file-content*. Note that the name is expected to +be URL-encoded already. diff --git a/docs/cmdline-opts/data.d b/docs/cmdline-opts/data.d deleted file mode 100644 index f1d67b95069..00000000000 --- a/docs/cmdline-opts/data.d +++ /dev/null @@ -1,41 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: data -Short: d -Arg: -Help: HTTP POST data -Protocols: HTTP MQTT -See-also: data-binary data-urlencode data-raw -Mutexed: form head upload-file -Category: important http post upload -Example: -d "name=curl" $URL -Example: -d "name=curl" -d "tool=cmdline" $URL -Example: -d @filename $URL -Added: 4.0 -Multi: append ---- -Sends the specified data in a POST request to the HTTP server, in the same way -that a browser does when a user has filled in an HTML form and presses the -submit button. This makes curl pass the data to the server using the -content-type application/x-www-form-urlencoded. Compare to --form. - ---data-raw is almost the same but does not have a special interpretation of -the @ character. To post data purely binary, you should instead use the ---data-binary option. To URL-encode the value of a form field you may use ---data-urlencode. - -If any of these options is used more than once on the same command line, the -data pieces specified are merged with a separating &-symbol. Thus, using -'-d name=daniel -d skill=lousy' would generate a post chunk that looks like -'name=daniel&skill=lousy'. - -If you start the data with the letter @, the rest should be a file name to -read the data from, or - if you want curl to read the data from stdin. Posting -data from a file named 'foobar' would thus be done with --data @foobar. When ---data is told to read from a file like that, carriage returns and newlines -are stripped out. If you do not want the @ character to have a special -interpretation use --data-raw instead. - -The data for this option is passed on to the server exactly as provided on the -command line. curl does not convert, change or improve it. It is up to the -user to provide the data in the correct form. diff --git a/docs/cmdline-opts/data.md b/docs/cmdline-opts/data.md new file mode 100644 index 00000000000..6b6e70285e4 --- /dev/null +++ b/docs/cmdline-opts/data.md @@ -0,0 +1,49 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: data +Short: d +Arg: +Help: HTTP POST data +Protocols: HTTP MQTT +Mutexed: form head upload-file +Category: important http post upload +Added: 4.0 +Multi: append +See-also: + - data-binary + - data-urlencode + - data-raw +Example: + - -d "name=curl" $URL + - -d "name=curl" -d "tool=cmdline" $URL + - -d @filename $URL +--- + +# `--data` + +Sends the specified data in a POST request to the HTTP server, in the same way +that a browser does when a user has filled in an HTML form and presses the +submit button. This option makes curl pass the data to the server using the +content-type application/x-www-form-urlencoded. Compare to --form. + +--data-raw is almost the same but does not have a special interpretation of +the @ character. To post data purely binary, you should instead use the +--data-binary option. To URL-encode the value of a form field you may use +--data-urlencode. + +If any of these options is used more than once on the same command line, the +data pieces specified are merged with a separating &-symbol. Thus, using +'-d name=daniel -d skill=lousy' would generate a post chunk that looks like +'name=daniel&skill=lousy'. + +If you start the data with the letter @, the rest should be a filename to read +the data from, or - if you want curl to read the data from stdin. Posting data +from a file named 'foobar' would thus be done with --data @foobar. When --data +is told to read from a file like that, carriage returns, newlines and null +bytes are stripped out. If you do not want the @ character to have a special +interpretation use --data-raw instead. + +The data for this option is passed on to the server exactly as provided on the +command line. curl does not convert, change or improve it. It is up to the +user to provide the data in the correct form. diff --git a/docs/cmdline-opts/delegation.d b/docs/cmdline-opts/delegation.d deleted file mode 100644 index 7941849347f..00000000000 --- a/docs/cmdline-opts/delegation.d +++ /dev/null @@ -1,24 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: delegation -Arg: -Help: GSS-API delegation permission -Protocols: GSS/kerberos -Category: auth -Example: --delegation "none" $URL -Added: 7.22.0 -See-also: insecure ssl -Multi: single ---- -Set LEVEL to tell the server what it is allowed to delegate when it -comes to user credentials. -.RS -.IP "none" -Do not allow any delegation. -.IP "policy" -Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos -service ticket, which is a matter of realm policy. -.IP "always" -Unconditionally allow the server to delegate. -.RE -.IP diff --git a/docs/cmdline-opts/delegation.md b/docs/cmdline-opts/delegation.md new file mode 100644 index 00000000000..c874a2b59d4 --- /dev/null +++ b/docs/cmdline-opts/delegation.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: delegation +Arg: +Help: GSS-API delegation permission +Protocols: GSS/kerberos +Category: auth +Added: 7.22.0 +Multi: single +See-also: + - insecure + - ssl +Example: + - --delegation "none" $URL +--- + +# `--delegation` + +Set LEVEL what curl is allowed to delegate when it comes to user credentials. + +## none +Do not allow any delegation. + +## policy +Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos +service ticket, which is a matter of realm policy. + +## always +Unconditionally allow the server to delegate. diff --git a/docs/cmdline-opts/digest.d b/docs/cmdline-opts/digest.d deleted file mode 100644 index f2ee551c5e3..00000000000 --- a/docs/cmdline-opts/digest.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: digest -Help: Use HTTP Digest Authentication -Protocols: HTTP -Mutexed: basic ntlm negotiate -See-also: user proxy-digest anyauth -Category: proxy auth http -Example: -u name:password --digest $URL -Added: 7.10.6 -Multi: boolean ---- -Enables HTTP Digest authentication. This is an authentication scheme that -prevents the password from being sent over the wire in clear text. Use this in -combination with the normal --user option to set user name and password. diff --git a/docs/cmdline-opts/digest.md b/docs/cmdline-opts/digest.md new file mode 100644 index 00000000000..04c5a79a964 --- /dev/null +++ b/docs/cmdline-opts/digest.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: digest +Help: HTTP Digest Authentication +Protocols: HTTP +Mutexed: basic ntlm negotiate +Category: proxy auth http +Added: 7.10.6 +Multi: boolean +See-also: + - user + - proxy-digest + - anyauth +Example: + - -u name:password --digest $URL +--- + +# `--digest` + +Enables HTTP Digest authentication. This authentication scheme avoids sending +the password over the wire in clear text. Use this in combination with the +normal --user option to set username and password. diff --git a/docs/cmdline-opts/disable-eprt.d b/docs/cmdline-opts/disable-eprt.d deleted file mode 100644 index b6d382bafaa..00000000000 --- a/docs/cmdline-opts/disable-eprt.d +++ /dev/null @@ -1,25 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: disable-eprt -Help: Inhibit using EPRT or LPRT -Protocols: FTP -Category: ftp -Example: --disable-eprt ftp://example.com/ -Added: 7.10.5 -See-also: disable-epsv ftp-port -Multi: boolean ---- -Tell curl to disable the use of the EPRT and LPRT commands when doing active -FTP transfers. Curl normally first attempts to use EPRT before using PORT, but -with this option, it uses PORT right away. EPRT is an extension to the -original FTP protocol, and does not work on all servers, but enables more -functionality in a better way than the traditional PORT command. - ---eprt can be used to explicitly enable EPRT again and --no-eprt is an alias -for --disable-eprt. - -If the server is accessed using IPv6, this option has no effect as EPRT is -necessary then. - -Disabling EPRT only changes the active behavior. If you want to switch to -passive mode you need to not use --ftp-port or force it with --ftp-pasv. diff --git a/docs/cmdline-opts/disable-eprt.md b/docs/cmdline-opts/disable-eprt.md new file mode 100644 index 00000000000..b6e6c6da239 --- /dev/null +++ b/docs/cmdline-opts/disable-eprt.md @@ -0,0 +1,32 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: disable-eprt +Help: Inhibit using EPRT or LPRT +Protocols: FTP +Category: ftp +Added: 7.10.5 +Multi: boolean +See-also: + - disable-epsv + - ftp-port +Example: + - --disable-eprt ftp://example.com/ +--- + +# `--disable-eprt` + +Disable the use of the EPRT and LPRT commands when doing active FTP transfers. +Curl normally first attempts to use EPRT before using PORT, but with this +option, it uses PORT right away. EPRT is an extension to the original FTP +protocol, and does not work on all servers, but enables more functionality in +a better way than the traditional PORT command. + +--eprt can be used to explicitly enable EPRT again and --no-eprt is an alias +for --disable-eprt. + +If the server is accessed using IPv6, this option has no effect as EPRT is +necessary then. + +Disabling EPRT only changes the active behavior. If you want to switch to +passive mode you need to not use --ftp-port or force it with --ftp-pasv. diff --git a/docs/cmdline-opts/disable-epsv.d b/docs/cmdline-opts/disable-epsv.d deleted file mode 100644 index f02df763da7..00000000000 --- a/docs/cmdline-opts/disable-epsv.d +++ /dev/null @@ -1,23 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: disable-epsv -Help: Inhibit using EPSV -Protocols: FTP -Category: ftp -Example: --disable-epsv ftp://example.com/ -Added: 7.9.2 -See-also: disable-eprt ftp-port -Multi: boolean ---- -Tell curl to disable the use of the EPSV command when doing passive FTP -transfers. Curl normally first attempts to use EPSV before PASV, but with this -option, it does not try EPSV. - ---epsv can be used to explicitly enable EPSV again and --no-epsv is an alias -for --disable-epsv. - -If the server is an IPv6 host, this option has no effect as EPSV is necessary -then. - -Disabling EPSV only changes the passive behavior. If you want to switch to -active mode you need to use --ftp-port. diff --git a/docs/cmdline-opts/disable-epsv.md b/docs/cmdline-opts/disable-epsv.md new file mode 100644 index 00000000000..7667c795fbb --- /dev/null +++ b/docs/cmdline-opts/disable-epsv.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: disable-epsv +Help: Inhibit using EPSV +Protocols: FTP +Category: ftp +Added: 7.9.2 +Multi: boolean +See-also: + - disable-eprt + - ftp-port +Example: + - --disable-epsv ftp://example.com/ +--- + +# `--disable-epsv` + +Disable the use of the EPSV command when doing passive FTP transfers. Curl +normally first attempts to use EPSV before PASV, but with this option, it does +not try EPSV. + +--epsv can be used to explicitly enable EPSV again and --no-epsv is an alias +for --disable-epsv. + +If the server is an IPv6 host, this option has no effect as EPSV is necessary +then. + +Disabling EPSV only changes the passive behavior. If you want to switch to +active mode you need to use --ftp-port. diff --git a/docs/cmdline-opts/disable.d b/docs/cmdline-opts/disable.d deleted file mode 100644 index 979c039915a..00000000000 --- a/docs/cmdline-opts/disable.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: disable -Short: q -Help: Disable .curlrc -Category: curl -Example: -q $URL -Added: 5.0 -See-also: config -Multi: boolean ---- -If used as the **first** parameter on the command line, the *curlrc* config -file is not read or used. See the --config for details on the default config -file search path. - -Prior to 7.50.0 curl supported the short option name *q* but not the long -option name *disable*. diff --git a/docs/cmdline-opts/disable.md b/docs/cmdline-opts/disable.md new file mode 100644 index 00000000000..e22a2bb4a0a --- /dev/null +++ b/docs/cmdline-opts/disable.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: disable +Short: q +Help: Disable .curlrc +Category: curl +Added: 5.0 +Multi: boolean +See-also: + - config +Example: + - -q $URL +--- + +# `--disable` + +If used as the **first** parameter on the command line, the *curlrc* config +file is not read or used. See the --config for details on the default config +file search path. + +Prior to 7.50.0 curl supported the short option name *q* but not the long +option name *disable*. diff --git a/docs/cmdline-opts/disallow-username-in-url.d b/docs/cmdline-opts/disallow-username-in-url.d deleted file mode 100644 index d0537db97ac..00000000000 --- a/docs/cmdline-opts/disallow-username-in-url.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: disallow-username-in-url -Help: Disallow username in URL -Protocols: HTTP -Added: 7.61.0 -See-also: proto -Category: curl http -Example: --disallow-username-in-url $URL -Multi: boolean ---- -This tells curl to exit if passed a URL containing a username. This is probably -most useful when the URL is being provided at runtime or similar. diff --git a/docs/cmdline-opts/disallow-username-in-url.md b/docs/cmdline-opts/disallow-username-in-url.md new file mode 100644 index 00000000000..012f2d0dc80 --- /dev/null +++ b/docs/cmdline-opts/disallow-username-in-url.md @@ -0,0 +1,18 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: disallow-username-in-url +Help: Disallow username in URL +Added: 7.61.0 +Category: curl +Multi: boolean +See-also: + - proto +Example: + - --disallow-username-in-url $URL +--- + +# `--disallow-username-in-url` + +Exit with error if passed a URL containing a username. Probably most useful +when the URL is being provided at runtime or similar. diff --git a/docs/cmdline-opts/dns-interface.d b/docs/cmdline-opts/dns-interface.d deleted file mode 100644 index fd924b897ae..00000000000 --- a/docs/cmdline-opts/dns-interface.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: dns-interface -Arg: -Help: Interface to use for DNS requests -Protocols: DNS -See-also: dns-ipv4-addr dns-ipv6-addr -Added: 7.33.0 -Requires: c-ares -Category: dns -Example: --dns-interface eth0 $URL -Multi: single ---- -Tell curl to send outgoing DNS requests through . This option is a -counterpart to --interface (which does not affect DNS). The supplied string -must be an interface name (not an address). diff --git a/docs/cmdline-opts/dns-interface.md b/docs/cmdline-opts/dns-interface.md new file mode 100644 index 00000000000..aee7400bc5d --- /dev/null +++ b/docs/cmdline-opts/dns-interface.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: dns-interface +Arg: +Help: Interface to use for DNS requests +Protocols: DNS +Added: 7.33.0 +Requires: c-ares +Category: dns +Multi: single +See-also: + - dns-ipv4-addr + - dns-ipv6-addr +Example: + - --dns-interface eth0 $URL +--- + +# `--dns-interface` + +Send outgoing DNS requests through the given interface. This option is a +counterpart to --interface (which does not affect DNS). The supplied string +must be an interface name (not an address). diff --git a/docs/cmdline-opts/dns-ipv4-addr.d b/docs/cmdline-opts/dns-ipv4-addr.d deleted file mode 100644 index 5930557397c..00000000000 --- a/docs/cmdline-opts/dns-ipv4-addr.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: dns-ipv4-addr -Arg:
-Help: IPv4 address to use for DNS requests -Protocols: DNS -See-also: dns-interface dns-ipv6-addr -Added: 7.33.0 -Requires: c-ares -Category: dns -Example: --dns-ipv4-addr 10.1.2.3 $URL -Multi: single ---- -Tell curl to bind to a specific IP address when making IPv4 DNS requests, so -that the DNS requests originate from this address. The argument should be a -single IPv4 address. diff --git a/docs/cmdline-opts/dns-ipv4-addr.md b/docs/cmdline-opts/dns-ipv4-addr.md new file mode 100644 index 00000000000..4a43cb1d900 --- /dev/null +++ b/docs/cmdline-opts/dns-ipv4-addr.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: dns-ipv4-addr +Arg:
+Help: IPv4 address to use for DNS requests +Protocols: DNS +Added: 7.33.0 +Requires: c-ares +Category: dns +Multi: single +See-also: + - dns-interface + - dns-ipv6-addr +Example: + - --dns-ipv4-addr 10.1.2.3 $URL +--- + +# `--dns-ipv4-addr` + +Bind to a specific IP address when making IPv4 DNS requests, so that the DNS +requests originate from this address. The argument should be a single IPv4 +address. diff --git a/docs/cmdline-opts/dns-ipv6-addr.d b/docs/cmdline-opts/dns-ipv6-addr.d deleted file mode 100644 index a76120cdc12..00000000000 --- a/docs/cmdline-opts/dns-ipv6-addr.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: dns-ipv6-addr -Arg:
-Help: IPv6 address to use for DNS requests -Protocols: DNS -See-also: dns-interface dns-ipv4-addr -Added: 7.33.0 -Requires: c-ares -Category: dns -Example: --dns-ipv6-addr 2a04:4e42::561 $URL -Multi: single ---- -Tell curl to bind to a specific IP address when making IPv6 DNS requests, so -that the DNS requests originate from this address. The argument should be a -single IPv6 address. diff --git a/docs/cmdline-opts/dns-ipv6-addr.md b/docs/cmdline-opts/dns-ipv6-addr.md new file mode 100644 index 00000000000..71123117678 --- /dev/null +++ b/docs/cmdline-opts/dns-ipv6-addr.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: dns-ipv6-addr +Arg:
+Help: IPv6 address to use for DNS requests +Protocols: DNS +Added: 7.33.0 +Requires: c-ares +Category: dns +Multi: single +See-also: + - dns-interface + - dns-ipv4-addr +Example: + - --dns-ipv6-addr 2a04:4e42::561 $URL +--- + +# `--dns-ipv6-addr` + +Bind to a specific IP address when making IPv6 DNS requests, so that the DNS +requests originate from this address. The argument should be a single IPv6 +address. diff --git a/docs/cmdline-opts/dns-servers.d b/docs/cmdline-opts/dns-servers.d deleted file mode 100644 index bec23a3c352..00000000000 --- a/docs/cmdline-opts/dns-servers.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: dns-servers -Arg: -Help: DNS server addrs to use -Requires: c-ares -Added: 7.33.0 -Category: dns -Example: --dns-servers 192.168.0.1,192.168.0.2 $URL -See-also: dns-interface dns-ipv4-addr -Multi: single ---- -Set the list of DNS servers to be used instead of the system default. -The list of IP addresses should be separated with commas. Port numbers -may also optionally be given as *:* after each IP -address. diff --git a/docs/cmdline-opts/dns-servers.md b/docs/cmdline-opts/dns-servers.md new file mode 100644 index 00000000000..bf6ba3fe930 --- /dev/null +++ b/docs/cmdline-opts/dns-servers.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: dns-servers +Arg: +Help: DNS server addrs to use +Protocols: DNS +Requires: c-ares +Added: 7.33.0 +Category: dns +Multi: single +See-also: + - dns-interface + - dns-ipv4-addr +Example: + - --dns-servers 192.168.0.1,192.168.0.2 $URL + - --dns-servers 10.0.0.1:53 $URL +--- + +# `--dns-servers` + +Set the list of DNS servers to be used instead of the system default. The list +of IP addresses should be separated with commas. Port numbers may also +optionally be given, appended to the IP address separated with a colon. diff --git a/docs/cmdline-opts/doh-cert-status.d b/docs/cmdline-opts/doh-cert-status.d deleted file mode 100644 index 37ae0f8274a..00000000000 --- a/docs/cmdline-opts/doh-cert-status.d +++ /dev/null @@ -1,11 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: doh-cert-status -Help: Verify the status of the DoH server cert via OCSP-staple -Added: 7.76.0 -Category: dns tls -Example: --doh-cert-status --doh-url https://doh.example $URL -See-also: doh-insecure -Multi: boolean ---- -Same as --cert-status but used for DoH (DNS-over-HTTPS). diff --git a/docs/cmdline-opts/doh-cert-status.md b/docs/cmdline-opts/doh-cert-status.md new file mode 100644 index 00000000000..920c5b435d5 --- /dev/null +++ b/docs/cmdline-opts/doh-cert-status.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: doh-cert-status +Help: Verify DoH server cert status OCSP-staple +Added: 7.76.0 +Category: dns tls +Multi: boolean +See-also: + - doh-insecure +Example: + - --doh-cert-status --doh-url https://doh.example $URL +--- + +# `--doh-cert-status` + +Same as --cert-status but used for DoH (DNS-over-HTTPS). + +Verifies the status of the DoH servers' certificate by using the Certificate +Status Request (aka. OCSP stapling) TLS extension. + +If this option is enabled and the DoH server sends an invalid (e.g. expired) +response, if the response suggests that the server certificate has been +revoked, or no response at all is received, the verification fails. + +This support is currently only implemented in the OpenSSL and GnuTLS backends. diff --git a/docs/cmdline-opts/doh-insecure.d b/docs/cmdline-opts/doh-insecure.d deleted file mode 100644 index dcc65fb6c9f..00000000000 --- a/docs/cmdline-opts/doh-insecure.d +++ /dev/null @@ -1,11 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: doh-insecure -Help: Allow insecure DoH server connections -Added: 7.76.0 -Category: dns tls -Example: --doh-insecure --doh-url https://doh.example $URL -See-also: doh-url -Multi: boolean ---- -Same as --insecure but used for DoH (DNS-over-HTTPS). diff --git a/docs/cmdline-opts/doh-insecure.md b/docs/cmdline-opts/doh-insecure.md new file mode 100644 index 00000000000..684428ddf7e --- /dev/null +++ b/docs/cmdline-opts/doh-insecure.md @@ -0,0 +1,17 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: doh-insecure +Help: Allow insecure DoH server connections +Added: 7.76.0 +Category: dns tls +Multi: boolean +See-also: + - doh-url +Example: + - --doh-insecure --doh-url https://doh.example $URL +--- + +# `--doh-insecure` + +Same as --insecure but used for DoH (DNS-over-HTTPS). diff --git a/docs/cmdline-opts/doh-url.d b/docs/cmdline-opts/doh-url.d deleted file mode 100644 index 6d0dd1605ea..00000000000 --- a/docs/cmdline-opts/doh-url.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: doh-url -Arg: -Help: Resolve host names over DoH -Added: 7.62.0 -Category: dns -Example: --doh-url https://doh.example $URL -See-also: doh-insecure -Multi: single ---- -Specifies which DNS-over-HTTPS (DoH) server to use to resolve hostnames, -instead of using the default name resolver mechanism. The URL must be HTTPS. - -Some SSL options that you set for your transfer also applies to DoH since the -name lookups take place over SSL. However, the certificate verification -settings are not inherited but are controlled separately via --doh-insecure -and --doh-cert-status. - -This option is unset if an empty string "" is used as the URL. -(Added in 7.85.0) diff --git a/docs/cmdline-opts/doh-url.md b/docs/cmdline-opts/doh-url.md new file mode 100644 index 00000000000..23754cac19c --- /dev/null +++ b/docs/cmdline-opts/doh-url.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: doh-url +Arg: +Help: Resolve hostnames over DoH +Added: 7.62.0 +Category: dns +Multi: single +See-also: + - doh-insecure +Example: + - --doh-url https://doh.example $URL +--- + +# `--doh-url` + +Specifies which DNS-over-HTTPS (DoH) server to use to resolve hostnames, +instead of using the default name resolver mechanism. The URL must be HTTPS. + +Some SSL options that you set for your transfer also applies to DoH since the +name lookups take place over SSL. However, the certificate verification +settings are not inherited but are controlled separately via --doh-insecure +and --doh-cert-status. + +This option is unset if an empty string "" is used as the URL. +(Added in 7.85.0) diff --git a/docs/cmdline-opts/dump-header.d b/docs/cmdline-opts/dump-header.d deleted file mode 100644 index 42a79e7ddf6..00000000000 --- a/docs/cmdline-opts/dump-header.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: dump-header -Short: D -Arg: -Help: Write the received headers to -Protocols: HTTP FTP -See-also: output -Category: http ftp -Example: --dump-header store.txt $URL -Added: 5.7 -Multi: single ---- -Write the received protocol headers to the specified file. If no headers are -received, the use of this option creates an empty file. - -When used in FTP, the FTP server response lines are considered being "headers" -and thus are saved there. - -Having multiple transfers in one set of operations (i.e. the URLs in one ---next clause), appends them to the same file, separated by a blank line. diff --git a/docs/cmdline-opts/dump-header.md b/docs/cmdline-opts/dump-header.md new file mode 100644 index 00000000000..42d3e85ed60 --- /dev/null +++ b/docs/cmdline-opts/dump-header.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: dump-header +Short: D +Arg: +Help: Write the received headers to +Protocols: HTTP FTP +Category: http ftp +Added: 5.7 +Multi: single +See-also: + - output +Example: + - --dump-header store.txt $URL +--- + +# `--dump-header` + +Write the received protocol headers to the specified file. If no headers are +received, the use of this option creates an empty file. + +When used in FTP, the FTP server response lines are considered being "headers" +and thus are saved there. + +Having multiple transfers in one set of operations (i.e. the URLs in one +--next clause), appends them to the same file, separated by a blank line. diff --git a/docs/cmdline-opts/egd-file.d b/docs/cmdline-opts/egd-file.d deleted file mode 100644 index 4543ecf15eb..00000000000 --- a/docs/cmdline-opts/egd-file.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: egd-file -Arg: -Help: EGD socket path for random data -Protocols: TLS -See-also: random-file -Category: tls -Example: --egd-file /random/here $URL -Added: 7.7 -Multi: single ---- -Deprecated option (added in 7.84.0). Prior to that it only had an effect on -curl if built to use old versions of OpenSSL. - -Specify the path name to the Entropy Gathering Daemon socket. The socket is -used to seed the random engine for SSL connections. diff --git a/docs/cmdline-opts/egd-file.md b/docs/cmdline-opts/egd-file.md new file mode 100644 index 00000000000..b68b7d49670 --- /dev/null +++ b/docs/cmdline-opts/egd-file.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: egd-file +Arg: +Help: EGD socket path for random data +Protocols: TLS +Category: tls +Added: 7.7 +Multi: single +See-also: + - random-file +Example: + - --egd-file /random/here $URL +--- + +# `--egd-file` + +Deprecated option (added in 7.84.0). Prior to that it only had an effect on +curl if built to use old versions of OpenSSL. + +Specify the path name to the Entropy Gathering Daemon socket. The socket is +used to seed the random engine for SSL connections. diff --git a/docs/cmdline-opts/engine.d b/docs/cmdline-opts/engine.d deleted file mode 100644 index 1ebc779c0d8..00000000000 --- a/docs/cmdline-opts/engine.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: engine -Arg: -Help: Crypto engine to use -Protocols: TLS -Category: tls -Example: --engine flavor $URL -Added: 7.9.3 -See-also: ciphers curves -Multi: single ---- -Select the OpenSSL crypto engine to use for cipher operations. Use --engine -list to print a list of build-time supported engines. Note that not all (and -possibly none) of the engines may be available at runtime. diff --git a/docs/cmdline-opts/engine.md b/docs/cmdline-opts/engine.md new file mode 100644 index 00000000000..511190023ef --- /dev/null +++ b/docs/cmdline-opts/engine.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: engine +Arg: +Help: Crypto engine to use +Protocols: TLS +Category: tls +Added: 7.9.3 +Multi: single +See-also: + - ciphers + - curves +Example: + - --engine flavor $URL +--- + +# `--engine` + +Select the OpenSSL crypto engine to use for cipher operations. Use --engine +list to print a list of build-time supported engines. Note that not all (and +possibly none) of the engines may be available at runtime. diff --git a/docs/cmdline-opts/etag-compare.d b/docs/cmdline-opts/etag-compare.d deleted file mode 100644 index d3c48d17a65..00000000000 --- a/docs/cmdline-opts/etag-compare.d +++ /dev/null @@ -1,23 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: etag-compare -Arg: -Help: Pass an ETag from a file as a custom header -Protocols: HTTP -Added: 7.68.0 -Category: http -Example: --etag-compare etag.txt $URL -See-also: etag-save time-cond -Multi: single ---- -This option makes a conditional HTTP request for the specific ETag read -from the given file by sending a custom If-None-Match header using the -stored ETag. - -For correct results, make sure that the specified file contains only a -single line with the desired ETag. An empty file is parsed as an empty -ETag. - -Use the option --etag-save to first save the ETag from a response, and -then use this option to compare against the saved ETag in a subsequent -request. diff --git a/docs/cmdline-opts/etag-compare.md b/docs/cmdline-opts/etag-compare.md new file mode 100644 index 00000000000..d69cbdf34c4 --- /dev/null +++ b/docs/cmdline-opts/etag-compare.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: etag-compare +Arg: +Help: Load ETag from file +Protocols: HTTP +Added: 7.68.0 +Category: http +Multi: single +See-also: + - etag-save + - time-cond +Example: + - --etag-compare etag.txt $URL +--- + +# `--etag-compare` + +Make a conditional HTTP request for the specific ETag read from the given file +by sending a custom If-None-Match header using the stored ETag. + +For correct results, make sure that the specified file contains only a single +line with the desired ETag. An empty file is parsed as an empty ETag. + +Use the option --etag-save to first save the ETag from a response, and then +use this option to compare against the saved ETag in a subsequent request. diff --git a/docs/cmdline-opts/etag-save.d b/docs/cmdline-opts/etag-save.d deleted file mode 100644 index 6295a9e3116..00000000000 --- a/docs/cmdline-opts/etag-save.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: etag-save -Arg: -Help: Parse ETag from a request and save it to a file -Protocols: HTTP -Added: 7.68.0 -Category: http -Example: --etag-save storetag.txt $URL -See-also: etag-compare -Multi: single ---- -This option saves an HTTP ETag to the specified file. An ETag is a -caching related header, usually returned in a response. - -If no ETag is sent by the server, an empty file is created. diff --git a/docs/cmdline-opts/etag-save.md b/docs/cmdline-opts/etag-save.md new file mode 100644 index 00000000000..aa346adad3b --- /dev/null +++ b/docs/cmdline-opts/etag-save.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: etag-save +Arg: +Help: Parse incoming ETag and save to a file +Protocols: HTTP +Added: 7.68.0 +Category: http +Multi: single +See-also: + - etag-compare +Example: + - --etag-save storetag.txt $URL +--- + +# `--etag-save` + +Save an HTTP ETag to the specified file. An ETag is a caching related header, +usually returned in a response. + +If no ETag is sent by the server, an empty file is created. diff --git a/docs/cmdline-opts/expect100-timeout.d b/docs/cmdline-opts/expect100-timeout.d deleted file mode 100644 index f9a119bd979..00000000000 --- a/docs/cmdline-opts/expect100-timeout.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: expect100-timeout -Arg: -Help: How long to wait for 100-continue -Protocols: HTTP -Added: 7.47.0 -See-also: connect-timeout -Category: http -Example: --expect100-timeout 2.5 -T file $URL -Multi: single ---- -Maximum time in seconds that you allow curl to wait for a 100-continue -response when curl emits an Expects: 100-continue header in its request. By -default curl waits one second. This option accepts decimal values! When -curl stops waiting, it continues as if the response has been received. - -The decimal value needs to provided using a dot (.) as decimal separator - not -the local version even if it might be using another separator. diff --git a/docs/cmdline-opts/expect100-timeout.md b/docs/cmdline-opts/expect100-timeout.md new file mode 100644 index 00000000000..ce69227ad9c --- /dev/null +++ b/docs/cmdline-opts/expect100-timeout.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: expect100-timeout +Arg: +Help: How long to wait for 100-continue +Protocols: HTTP +Added: 7.47.0 +Category: http +Multi: single +See-also: + - connect-timeout +Example: + - --expect100-timeout 2.5 -T file $URL +--- + +# `--expect100-timeout` + +Maximum time in seconds that you allow curl to wait for a 100-continue +response when curl emits an Expects: 100-continue header in its request. By +default curl waits one second. This option accepts decimal values. When curl +stops waiting, it continues as if a response was received. + +The decimal value needs to provided using a dot (`.`) as decimal separator - +not the local version even if it might be using another separator. diff --git a/docs/cmdline-opts/fail-early.d b/docs/cmdline-opts/fail-early.d deleted file mode 100644 index 36b3309996b..00000000000 --- a/docs/cmdline-opts/fail-early.d +++ /dev/null @@ -1,25 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: fail-early -Help: Fail on first transfer error, do not continue -Added: 7.52.0 -Category: curl -Example: --fail-early $URL https://two.example -See-also: fail fail-with-body -Multi: boolean -Scope: global ---- -Fail and exit on the first detected transfer error. - -When curl is used to do multiple transfers on the command line, it attempts to -operate on each given URL, one by one. By default, it ignores errors if there -are more URLs given and the last URL's success determines the error code curl -returns. So early failures are "hidden" by subsequent successful transfers. - -Using this option, curl instead returns an error on the first transfer that -fails, independent of the amount of URLs that are given on the command -line. This way, no transfer failures go undetected by scripts and similar. - -This option does not imply --fail, which causes transfers to fail due to the -server's HTTP status code. You can combine the two options, however note --fail -is not global and is therefore contained by --next. diff --git a/docs/cmdline-opts/fail-early.md b/docs/cmdline-opts/fail-early.md new file mode 100644 index 00000000000..bb22e14707f --- /dev/null +++ b/docs/cmdline-opts/fail-early.md @@ -0,0 +1,32 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: fail-early +Help: Fail on first transfer error +Added: 7.52.0 +Category: curl +Multi: boolean +Scope: global +See-also: + - fail + - fail-with-body +Example: + - --fail-early $URL https://two.example +--- + +# `--fail-early` + +Fail and exit on the first detected transfer error. + +When curl is used to do multiple transfers on the command line, it attempts to +operate on each given URL, one by one. By default, it ignores errors if there +are more URLs given and the last URL's success determines the error code curl +returns. Early failures are "hidden" by subsequent successful transfers. + +Using this option, curl instead returns an error on the first transfer that +fails, independent of the amount of URLs that are given on the command +line. This way, no transfer failures go undetected by scripts and similar. + +This option does not imply --fail, which causes transfers to fail due to the +server's HTTP status code. You can combine the two options, however note --fail +is not global and is therefore contained by --next. diff --git a/docs/cmdline-opts/fail-with-body.d b/docs/cmdline-opts/fail-with-body.d deleted file mode 100644 index dddb86e2296..00000000000 --- a/docs/cmdline-opts/fail-with-body.d +++ /dev/null @@ -1,20 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: fail-with-body -Protocols: HTTP -Help: Fail on HTTP errors but save the body -Category: http output -Added: 7.76.0 -See-also: fail fail-early -Mutexed: fail -Example: --fail-with-body $URL -Multi: boolean ---- -Return an error on server errors where the HTTP response code is 400 or -greater). In normal cases when an HTTP server fails to deliver a document, it -returns an HTML document stating so (which often also describes why and -more). This flag allows curl to output and save that content but also to -return error 22. - -This is an alternative option to --fail which makes curl fail for the same -circumstances but without saving the content. diff --git a/docs/cmdline-opts/fail-with-body.md b/docs/cmdline-opts/fail-with-body.md new file mode 100644 index 00000000000..670959ba9bc --- /dev/null +++ b/docs/cmdline-opts/fail-with-body.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: fail-with-body +Protocols: HTTP +Help: Fail on HTTP errors but save the body +Category: http output +Added: 7.76.0 +Mutexed: fail +Multi: boolean +See-also: + - fail + - fail-early +Example: + - --fail-with-body $URL +--- + +# `--fail-with-body` + +Return an error on server errors where the HTTP response code is 400 or +greater). In normal cases when an HTTP server fails to deliver a document, it +returns an HTML document stating so (which often also describes why and more). +This option allows curl to output and save that content but also to return +error 22. + +This is an alternative option to --fail which makes curl fail for the same +circumstances but without saving the content. diff --git a/docs/cmdline-opts/fail.d b/docs/cmdline-opts/fail.d deleted file mode 100644 index 8196a908dec..00000000000 --- a/docs/cmdline-opts/fail.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: fail -Short: f -Protocols: HTTP -Help: Fail fast with no output on HTTP errors -See-also: fail-with-body fail-early -Category: important http -Example: --fail $URL -Mutexed: fail-with-body -Added: 4.0 -Multi: boolean ---- -Fail fast with no output at all on server errors. This is useful to enable -scripts and users to better deal with failed attempts. In normal cases when an -HTTP server fails to deliver a document, it returns an HTML document stating -so (which often also describes why and more). This flag prevents curl from -outputting that and return error 22. - -This method is not fail-safe and there are occasions where non-successful -response codes slip through, especially when authentication is involved -(response codes 401 and 407). diff --git a/docs/cmdline-opts/fail.md b/docs/cmdline-opts/fail.md new file mode 100644 index 00000000000..8591e330db4 --- /dev/null +++ b/docs/cmdline-opts/fail.md @@ -0,0 +1,29 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: fail +Short: f +Protocols: HTTP +Help: Fail fast with no output on HTTP errors +Category: important http +Mutexed: fail-with-body +Added: 4.0 +Multi: boolean +See-also: + - fail-with-body + - fail-early +Example: + - --fail $URL +--- + +# `--fail` + +Fail fast with no output at all on server errors. This is useful to enable +scripts and users to better deal with failed attempts. In normal cases when an +HTTP server fails to deliver a document, it returns an HTML document stating +so (which often also describes why and more). This command line option +prevents curl from outputting that and return error 22. + +This method is not fail-safe and there are occasions where non-successful +response codes slip through, especially when authentication is involved +(response codes 401 and 407). diff --git a/docs/cmdline-opts/false-start.d b/docs/cmdline-opts/false-start.d deleted file mode 100644 index 73240492b96..00000000000 --- a/docs/cmdline-opts/false-start.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: false-start -Help: Enable TLS False Start -Protocols: TLS -Added: 7.42.0 -Category: tls -Example: --false-start $URL -See-also: tcp-fastopen -Multi: boolean ---- -Tells curl to use false start during the TLS handshake. False start is a mode -where a TLS client starts sending application data before verifying the -server's Finished message, thus saving a round trip when performing a full -handshake. - -This is currently only implemented in the Secure Transport (on iOS 7.0 or -later, or OS X 10.9 or later) backend. diff --git a/docs/cmdline-opts/false-start.md b/docs/cmdline-opts/false-start.md new file mode 100644 index 00000000000..f25af2374de --- /dev/null +++ b/docs/cmdline-opts/false-start.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: false-start +Help: Enable TLS False Start +Protocols: TLS +Added: 7.42.0 +Category: tls +Multi: boolean +See-also: + - tcp-fastopen +Example: + - --false-start $URL +--- + +# `--false-start` + +Use false start during the TLS handshake. False start is a mode where a TLS +client starts sending application data before verifying the server's Finished +message, thus saving a round trip when performing a full handshake. + +This functionality is currently only implemented in the Secure Transport (on +iOS 7.0 or later, or OS X 10.9 or later) backend. diff --git a/docs/cmdline-opts/form-escape.d b/docs/cmdline-opts/form-escape.d deleted file mode 100644 index 304bfe81497..00000000000 --- a/docs/cmdline-opts/form-escape.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: form-escape -Help: Escape multipart form field/file names using backslash -Protocols: HTTP -See-also: form -Added: 7.81.0 -Category: http upload -Example: --form-escape -F 'field\\name=curl' -F 'file=@load"this' $URL -Multi: single ---- -Tells curl to pass on names of multipart form fields and files using -backslash-escaping instead of percent-encoding. diff --git a/docs/cmdline-opts/form-escape.md b/docs/cmdline-opts/form-escape.md new file mode 100644 index 00000000000..083c29e16ba --- /dev/null +++ b/docs/cmdline-opts/form-escape.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: form-escape +Help: Escape form fields using backslash +Protocols: HTTP +Added: 7.81.0 +Category: http upload +Multi: single +See-also: + - form +Example: + - --form-escape -F 'field\name=curl' -F 'file=@load"this' $URL +--- + +# `--form-escape` + +Pass on names of multipart form fields and files using backslash-escaping +instead of percent-encoding. diff --git a/docs/cmdline-opts/form-string.d b/docs/cmdline-opts/form-string.d deleted file mode 100644 index 6d7a500a447..00000000000 --- a/docs/cmdline-opts/form-string.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: form-string -Help: Specify multipart MIME data -Protocols: HTTP SMTP IMAP -Arg: -See-also: form -Category: http upload -Example: --form-string "data" $URL -Added: 7.13.2 -Multi: append ---- -Similar to --form except that the value string for the named parameter is used -literally. Leading '@' and '<' characters, and the ';type=' string in -the value have no special meaning. Use this in preference to --form if -there is any possibility that the string value may accidentally trigger the -'@' or '<' features of --form. diff --git a/docs/cmdline-opts/form-string.md b/docs/cmdline-opts/form-string.md new file mode 100644 index 00000000000..3c1f7b53275 --- /dev/null +++ b/docs/cmdline-opts/form-string.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: form-string +Help: Specify multipart MIME data +Protocols: HTTP SMTP IMAP +Arg: +Category: http upload +Added: 7.13.2 +Multi: append +See-also: + - form +Example: + - --form-string "name=data" $URL +--- + +# `--form-string` + +Similar to --form except that the value string for the named parameter is used +literally. Leading @ and \< characters, and the `;type=` string in the value +have no special meaning. Use this in preference to --form if there is any +possibility that the string value may accidentally trigger the @ or \< +features of --form. diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d deleted file mode 100644 index e53e93ae0dd..00000000000 --- a/docs/cmdline-opts/form.d +++ /dev/null @@ -1,134 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: form -Short: F -Arg: -Help: Specify multipart MIME data -Protocols: HTTP SMTP IMAP -Mutexed: data head upload-file -Category: http upload -Example: --form "name=curl" --form "file=@loadthis" $URL -Added: 5.0 -See-also: data form-string form-escape -Multi: append ---- -For HTTP protocol family, this lets curl emulate a filled-in form in which a -user has pressed the submit button. This causes curl to POST data using the -Content-Type multipart/form-data according to RFC 2388. - -For SMTP and IMAP protocols, this is the means to compose a multipart mail -message to transmit. - -This enables uploading of binary files etc. To force the 'content' part to be -a file, prefix the file name with an @ sign. To just get the content part from -a file, prefix the file name with the symbol <. The difference between @ and < -is then that @ makes a file get attached in the post as a file upload, while -the < makes a text field and just get the contents for that text field from a -file. - -Tell curl to read content from stdin instead of a file by using - as -filename. This goes for both @ and < constructs. When stdin is used, the -contents is buffered in memory first by curl to determine its size and allow a -possible resend. Defining a part's data from a named non-regular file (such as -a named pipe or similar) is not subject to buffering and is instead read at -transmission time; since the full size is unknown before the transfer starts, -such data is sent as chunks by HTTP and rejected by IMAP. - -Example: send an image to an HTTP server, where 'profile' is the name of the -form-field to which the file **portrait.jpg** is the input: - - curl -F profile=@portrait.jpg https://example.com/upload.cgi - -Example: send your name and shoe size in two text fields to the server: - - curl -F name=John -F shoesize=11 https://example.com/ - -Example: send your essay in a text field to the server. Send it as a plain -text field, but get the contents for it from a local file: - - curl -F "story=HTML message;type=text/html' \\ - -F '=)' -F '=@textfile.txt' ... smtp://example.com - -Data can be encoded for transfer using encoder=. Available encodings are -*binary* and *8bit* that do nothing else than adding the corresponding -Content-Transfer-Encoding header, *7bit* that only rejects 8-bit characters -with a transfer error, *quoted-printable* and *base64* that encodes data -according to the corresponding schemes, limiting lines length to 76 -characters. - -Example: send multipart mail with a quoted-printable text message and a -base64 attached file: - - curl -F '=text message;encoder=quoted-printable' \\ - -F '=@localfile;encoder=base64' ... smtp://example.com - -See further examples and details in the MANUAL. diff --git a/docs/cmdline-opts/form.md b/docs/cmdline-opts/form.md new file mode 100644 index 00000000000..8a4c91e5ae1 --- /dev/null +++ b/docs/cmdline-opts/form.md @@ -0,0 +1,142 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: form +Short: F +Arg: +Help: Specify multipart MIME data +Protocols: HTTP SMTP IMAP +Mutexed: data head upload-file +Category: http upload +Added: 5.0 +Multi: append +See-also: + - data + - form-string + - form-escape +Example: + - --form "name=curl" --form "file=@loadthis" $URL +--- + +# `--form` + +For the HTTP protocol family, emulate a filled-in form in which a user has +pressed the submit button. This makes curl POST data using the Content-Type +multipart/form-data according to RFC 2388. + +For SMTP and IMAP protocols, this composes a multipart mail message to +transmit. + +This enables uploading of binary files etc. To force the 'content' part to be +a file, prefix the filename with an @ sign. To just get the content part from +a file, prefix the filename with the symbol \<. The difference between @ and +\< is then that @ makes a file get attached in the post as a file upload, +while the \< makes a text field and just get the contents for that text field +from a file. + +Read content from stdin instead of a file by using a single "-" as filename. +This goes for both @ and \< constructs. When stdin is used, the contents is +buffered in memory first by curl to determine its size and allow a possible +resend. Defining a part's data from a named non-regular file (such as a named +pipe or similar) is not subject to buffering and is instead read at +transmission time; since the full size is unknown before the transfer starts, +such data is sent as chunks by HTTP and rejected by IMAP. + +Example: send an image to an HTTP server, where 'profile' is the name of the +form-field to which the file **portrait.jpg** is the input: + + curl -F profile=@portrait.jpg https://example.com/upload.cgi + +Example: send your name and shoe size in two text fields to the server: + + curl -F name=John -F shoesize=11 https://example.com/ + +Example: send your essay in a text field to the server. Send it as a plain +text field, but get the contents for it from a local file: + + curl -F "story=HTML message;type=text/html' \ + -F '=)' -F '=@textfile.txt' ... smtp://example.com + +Data can be encoded for transfer using encoder=. Available encodings are +*binary* and *8bit* that do nothing else than adding the corresponding +Content-Transfer-Encoding header, *7bit* that only rejects 8-bit characters +with a transfer error, *quoted-printable* and *base64* that encodes data +according to the corresponding schemes, limiting lines length to 76 +characters. + +Example: send multipart mail with a quoted-printable text message and a +base64 attached file: + + curl -F '=text message;encoder=quoted-printable' \ + -F '=@localfile;encoder=base64' ... smtp://example.com + +See further examples and details in the MANUAL. diff --git a/docs/cmdline-opts/ftp-account.d b/docs/cmdline-opts/ftp-account.d deleted file mode 100644 index eb669c56280..00000000000 --- a/docs/cmdline-opts/ftp-account.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-account -Arg: -Help: Account data string -Protocols: FTP -Added: 7.13.0 -Category: ftp auth -Example: --ftp-account "mr.robot" ftp://example.com/ -See-also: user -Multi: single ---- -When an FTP server asks for "account data" after user name and password has -been provided, this data is sent off using the ACCT command. diff --git a/docs/cmdline-opts/ftp-account.md b/docs/cmdline-opts/ftp-account.md new file mode 100644 index 00000000000..e275349dee0 --- /dev/null +++ b/docs/cmdline-opts/ftp-account.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-account +Arg: +Help: Account data string +Protocols: FTP +Added: 7.13.0 +Category: ftp auth +Multi: single +See-also: + - user +Example: + - --ftp-account "mr.robot" ftp://example.com/ +--- + +# `--ftp-account` + +When an FTP server asks for "account data" after username and password has +been provided, this data is sent off using the ACCT command. diff --git a/docs/cmdline-opts/ftp-alternative-to-user.d b/docs/cmdline-opts/ftp-alternative-to-user.d deleted file mode 100644 index f030bcf5985..00000000000 --- a/docs/cmdline-opts/ftp-alternative-to-user.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-alternative-to-user -Arg: -Help: String to replace USER [name] -Protocols: FTP -Added: 7.15.5 -Category: ftp -Example: --ftp-alternative-to-user "U53r" ftp://example.com -See-also: ftp-account user -Multi: single ---- -If authenticating with the USER and PASS commands fails, send this command. -When connecting to Tumbleweed's Secure Transport server over FTPS using a -client certificate, using "SITE AUTH" tells the server to retrieve the -username from the certificate. diff --git a/docs/cmdline-opts/ftp-alternative-to-user.md b/docs/cmdline-opts/ftp-alternative-to-user.md new file mode 100644 index 00000000000..9bd3686001c --- /dev/null +++ b/docs/cmdline-opts/ftp-alternative-to-user.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-alternative-to-user +Arg: +Help: String to replace USER [name] +Protocols: FTP +Added: 7.15.5 +Category: ftp +Multi: single +See-also: + - ftp-account + - user +Example: + - --ftp-alternative-to-user "U53r" ftp://example.com +--- + +# `--ftp-alternative-to-user` + +If authenticating with the USER and PASS commands fails, send this command. +When connecting to Tumbleweed's Secure Transport server over FTPS using a +client certificate, using "SITE AUTH" tells the server to retrieve the +username from the certificate. diff --git a/docs/cmdline-opts/ftp-create-dirs.d b/docs/cmdline-opts/ftp-create-dirs.d deleted file mode 100644 index 7c64f0e21c9..00000000000 --- a/docs/cmdline-opts/ftp-create-dirs.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-create-dirs -Protocols: FTP SFTP -Help: Create the remote dirs if not present -See-also: create-dirs -Category: ftp sftp curl -Example: --ftp-create-dirs -T file ftp://example.com/remote/path/file -Added: 7.10.7 -Multi: boolean ---- -When an FTP or SFTP URL/operation uses a path that does not currently exist on -the server, the standard behavior of curl is to fail. Using this option, curl -instead attempts to create missing directories. diff --git a/docs/cmdline-opts/ftp-create-dirs.md b/docs/cmdline-opts/ftp-create-dirs.md new file mode 100644 index 00000000000..5151e336c85 --- /dev/null +++ b/docs/cmdline-opts/ftp-create-dirs.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-create-dirs +Protocols: FTP SFTP +Help: Create the remote dirs if not present +Category: ftp sftp curl +Added: 7.10.7 +Multi: boolean +See-also: + - create-dirs +Example: + - --ftp-create-dirs -T file ftp://example.com/remote/path/file +--- + +# `--ftp-create-dirs` + +When an FTP or SFTP URL/operation uses a path that does not currently exist on +the server, the standard behavior of curl is to fail. Using this option, curl +instead attempts to create missing directories. diff --git a/docs/cmdline-opts/ftp-method.d b/docs/cmdline-opts/ftp-method.d deleted file mode 100644 index 8061d2b682b..00000000000 --- a/docs/cmdline-opts/ftp-method.d +++ /dev/null @@ -1,30 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-method -Arg: -Help: Control CWD usage -Protocols: FTP -Added: 7.15.1 -Category: ftp -Example: --ftp-method multicwd ftp://example.com/dir1/dir2/file -Example: --ftp-method nocwd ftp://example.com/dir1/dir2/file -Example: --ftp-method singlecwd ftp://example.com/dir1/dir2/file -See-also: list-only -Multi: single ---- -Control what method curl should use to reach a file on an FTP(S) -server. The method argument should be one of the following alternatives: -.RS -.IP multicwd -curl does a single CWD operation for each path part in the given URL. For deep -hierarchies this means many commands. This is how RFC 1738 says it should -be done. This is the default but the slowest behavior. -.IP nocwd -curl does no CWD at all. curl does SIZE, RETR, STOR etc and give a full -path to the server for all these commands. This is the fastest behavior. -.IP singlecwd -curl does one CWD with the full target directory and then operates on the file -"normally" (like in the multicwd case). This is somewhat more standards -compliant than 'nocwd' but without the full penalty of 'multicwd'. -.RE -.IP diff --git a/docs/cmdline-opts/ftp-method.md b/docs/cmdline-opts/ftp-method.md new file mode 100644 index 00000000000..d2bff21d59f --- /dev/null +++ b/docs/cmdline-opts/ftp-method.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-method +Arg: +Help: Control CWD usage +Protocols: FTP +Added: 7.15.1 +Category: ftp +Multi: single +See-also: + - list-only +Example: + - --ftp-method multicwd ftp://example.com/dir1/dir2/file + - --ftp-method nocwd ftp://example.com/dir1/dir2/file + - --ftp-method singlecwd ftp://example.com/dir1/dir2/file +--- + +# `--ftp-method` + +Control what method curl should use to reach a file on an FTP(S) +server. The method argument should be one of the following alternatives: + +## multicwd +Do a single CWD operation for each path part in the given URL. For deep +hierarchies this means many commands. This is how RFC 1738 says it should be +done. This is the default but the slowest behavior. + +## nocwd +Do no CWD at all. curl does SIZE, RETR, STOR etc and gives the full path to +the server for each of these commands. This is the fastest behavior. + +## singlecwd +Do one CWD with the full target directory and then operate on the file +"normally" (like in the multicwd case). This is somewhat more standards +compliant than `nocwd` but without the full penalty of `multicwd`. diff --git a/docs/cmdline-opts/ftp-pasv.d b/docs/cmdline-opts/ftp-pasv.d deleted file mode 100644 index c43bf2beeac..00000000000 --- a/docs/cmdline-opts/ftp-pasv.d +++ /dev/null @@ -1,20 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-pasv -Help: Use PASV/EPSV instead of PORT -Protocols: FTP -Added: 7.11.0 -See-also: disable-epsv -Category: ftp -Example: --ftp-pasv ftp://example.com/ -Multi: boolean ---- -Use passive mode for the data connection. Passive is the internal default -behavior, but using this option can be used to override a previous --ftp-port -option. - -Reversing an enforced passive really is not doable but you must then instead -enforce the correct --ftp-port again. - -Passive mode means that curl tries the EPSV command first and then PASV, -unless --disable-epsv is used. diff --git a/docs/cmdline-opts/ftp-pasv.md b/docs/cmdline-opts/ftp-pasv.md new file mode 100644 index 00000000000..964f9769ae5 --- /dev/null +++ b/docs/cmdline-opts/ftp-pasv.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-pasv +Help: Send PASV/EPSV instead of PORT +Protocols: FTP +Added: 7.11.0 +Category: ftp +Multi: boolean +See-also: + - disable-epsv +Example: + - --ftp-pasv ftp://example.com/ +--- + +# `--ftp-pasv` + +Use passive mode for the data connection. Passive is the internal default +behavior, but using this option can be used to override a previous --ftp-port +option. + +Reversing an enforced passive really is not doable but you must then instead +enforce the correct --ftp-port again. + +Passive mode means that curl tries the EPSV command first and then PASV, +unless --disable-epsv is used. diff --git a/docs/cmdline-opts/ftp-port.d b/docs/cmdline-opts/ftp-port.d deleted file mode 100644 index e1f4a1dba72..00000000000 --- a/docs/cmdline-opts/ftp-port.d +++ /dev/null @@ -1,41 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-port -Arg:
-Help: Use PORT instead of PASV -Short: P -Protocols: FTP -See-also: ftp-pasv disable-eprt -Category: ftp -Example: -P - ftp:/example.com -Example: -P eth0 ftp:/example.com -Example: -P 192.168.0.2 ftp:/example.com -Added: 4.0 -Multi: single ---- -Reverses the default initiator/listener roles when connecting with FTP. This -option makes curl use active mode. curl then tells the server to connect back -to the client's specified address and port, while passive mode asks the server -to setup an IP address and port for it to connect to.
should be one -of: -.RS -.IP interface -e.g. "eth0" to specify which interface's IP address you want to use (Unix only) -.IP "IP address" -e.g. "192.168.10.1" to specify the exact IP address -.IP "host name" -e.g. "my.host.domain" to specify the machine -.IP "-" -make curl pick the same IP address that is already used for the control -connection -.RE -.IP - -Disable the use of PORT with --ftp-pasv. Disable the attempt to use the EPRT -command instead of PORT by using --disable-eprt. EPRT is really PORT++. - -You can also append ":[start]-[end]\&" to the right of the address, to tell -curl what TCP port range to use. That means you specify a port range, from a -lower to a higher number. A single number works as well, but do note that it -increases the risk of failure since the port may not be available. -(Added in 7.19.5) diff --git a/docs/cmdline-opts/ftp-port.md b/docs/cmdline-opts/ftp-port.md new file mode 100644 index 00000000000..ff6d41c131f --- /dev/null +++ b/docs/cmdline-opts/ftp-port.md @@ -0,0 +1,51 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-port +Arg:
+Help: Send PORT instead of PASV +Short: P +Protocols: FTP +Category: ftp +Added: 4.0 +Multi: single +See-also: + - ftp-pasv + - disable-eprt +Example: + - -P - ftp:/example.com + - -P eth0 ftp:/example.com + - -P 192.168.0.2 ftp:/example.com +--- + +# `--ftp-port` + +Reverses the default initiator/listener roles when connecting with FTP. This +option makes curl use active mode. curl then commands the server to connect +back to the client's specified address and port, while passive mode asks the +server to setup an IP address and port for it to connect to. \ +should be one of: + +## interface +e.g. **eth0** to specify which interface's IP address you want to use (Unix only) + +## IP address +e.g. **192.168.10.1** to specify the exact IP address + +## hostname +e.g. **my.host.domain** to specify the machine + +## - +make curl pick the same IP address that is already used for the control +connection. This is the recommended choice. + +## + +Disable the use of PORT with --ftp-pasv. Disable the attempt to use the EPRT +command instead of PORT by using --disable-eprt. EPRT is really PORT++. + +You can also append ":[start]-[end]" to the right of the address, to tell +curl what TCP port range to use. That means you specify a port range, from a +lower to a higher number. A single number works as well, but do note that it +increases the risk of failure since the port may not be available. +(Added in 7.19.5) diff --git a/docs/cmdline-opts/ftp-pret.d b/docs/cmdline-opts/ftp-pret.d deleted file mode 100644 index 4bea99e6d84..00000000000 --- a/docs/cmdline-opts/ftp-pret.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-pret -Help: Send PRET before PASV -Protocols: FTP -Added: 7.20.0 -Category: ftp -Example: --ftp-pret ftp://example.com/ -See-also: ftp-port ftp-pasv -Multi: boolean ---- -Tell curl to send a PRET command before PASV (and EPSV). Certain FTP servers, -mainly drftpd, require this non-standard command for directory listings as -well as up and downloads in PASV mode. diff --git a/docs/cmdline-opts/ftp-pret.md b/docs/cmdline-opts/ftp-pret.md new file mode 100644 index 00000000000..48c48e3e77f --- /dev/null +++ b/docs/cmdline-opts/ftp-pret.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-pret +Help: Send PRET before PASV +Protocols: FTP +Added: 7.20.0 +Category: ftp +Multi: boolean +See-also: + - ftp-port + - ftp-pasv +Example: + - --ftp-pret ftp://example.com/ +--- + +# `--ftp-pret` + +Send a PRET command before PASV (and EPSV). Certain FTP servers, mainly +drftpd, require this non-standard command for directory listings as well as up +and downloads in PASV mode. diff --git a/docs/cmdline-opts/ftp-skip-pasv-ip.d b/docs/cmdline-opts/ftp-skip-pasv-ip.d deleted file mode 100644 index 3af9c6de4fe..00000000000 --- a/docs/cmdline-opts/ftp-skip-pasv-ip.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-skip-pasv-ip -Help: Skip the IP address for PASV -Protocols: FTP -Added: 7.14.2 -See-also: ftp-pasv -Category: ftp -Example: --ftp-skip-pasv-ip ftp://example.com/ -Multi: boolean ---- -Tell curl to not use the IP address the server suggests in its response to -curl's PASV command when curl connects the data connection. Instead curl -reuses the same IP address it already uses for the control connection. - -This option is enabled by default (added in 7.74.0). - -This option has no effect if PORT, EPRT or EPSV is used instead of PASV. diff --git a/docs/cmdline-opts/ftp-skip-pasv-ip.md b/docs/cmdline-opts/ftp-skip-pasv-ip.md new file mode 100644 index 00000000000..dfa546d1d27 --- /dev/null +++ b/docs/cmdline-opts/ftp-skip-pasv-ip.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-skip-pasv-ip +Help: Skip the IP address for PASV +Protocols: FTP +Added: 7.14.2 +Category: ftp +Multi: boolean +See-also: + - ftp-pasv +Example: + - --ftp-skip-pasv-ip ftp://example.com/ +--- + +# `--ftp-skip-pasv-ip` + +Do not use the IP address the server suggests in its response to curl's PASV +command when curl connects the data connection. Instead curl reuses the same +IP address it already uses for the control connection. + +This option is enabled by default (added in 7.74.0). + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. diff --git a/docs/cmdline-opts/ftp-ssl-ccc-mode.d b/docs/cmdline-opts/ftp-ssl-ccc-mode.d deleted file mode 100644 index ae9af9429d4..00000000000 --- a/docs/cmdline-opts/ftp-ssl-ccc-mode.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-ssl-ccc-mode -Arg: -Help: Set CCC mode -Protocols: FTP -Added: 7.16.2 -See-also: ftp-ssl-ccc -Category: ftp tls -Example: --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/ -Multi: boolean ---- -Sets the CCC mode. The passive mode does not initiate the shutdown, but -instead waits for the server to do it, and does not reply to the shutdown from -the server. The active mode initiates the shutdown and waits for a reply from -the server. diff --git a/docs/cmdline-opts/ftp-ssl-ccc-mode.md b/docs/cmdline-opts/ftp-ssl-ccc-mode.md new file mode 100644 index 00000000000..5f428dc0fa4 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-ccc-mode.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-ssl-ccc-mode +Arg: +Help: Set CCC mode +Protocols: FTP +Added: 7.16.2 +Category: ftp tls +Multi: boolean +See-also: + - ftp-ssl-ccc +Example: + - --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/ +--- + +# `--ftp-ssl-ccc-mode` + +Sets the CCC mode. The passive mode does not initiate the shutdown, but +instead waits for the server to do it, and does not reply to the shutdown from +the server. The active mode initiates the shutdown and waits for a reply from +the server. diff --git a/docs/cmdline-opts/ftp-ssl-ccc.d b/docs/cmdline-opts/ftp-ssl-ccc.d deleted file mode 100644 index 33ae83b1c95..00000000000 --- a/docs/cmdline-opts/ftp-ssl-ccc.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-ssl-ccc -Help: Send CCC after authenticating -Protocols: FTP -See-also: ssl ftp-ssl-ccc-mode -Added: 7.16.1 -Category: ftp tls -Example: --ftp-ssl-ccc ftps://example.com/ -Multi: boolean ---- -Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after -authenticating. The rest of the control channel communication is be -unencrypted. This allows NAT routers to follow the FTP transaction. The -default mode is passive. diff --git a/docs/cmdline-opts/ftp-ssl-ccc.md b/docs/cmdline-opts/ftp-ssl-ccc.md new file mode 100644 index 00000000000..d477606fe67 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-ccc.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-ssl-ccc +Help: Send CCC after authenticating +Protocols: FTP +Added: 7.16.1 +Category: ftp tls +Multi: boolean +See-also: + - ssl + - ftp-ssl-ccc-mode +Example: + - --ftp-ssl-ccc ftps://example.com/ +--- + +# `--ftp-ssl-ccc` + +Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after +authenticating. The rest of the control channel communication is be +unencrypted. This allows NAT routers to follow the FTP transaction. The +default mode is passive. diff --git a/docs/cmdline-opts/ftp-ssl-control.d b/docs/cmdline-opts/ftp-ssl-control.d deleted file mode 100644 index b895779271c..00000000000 --- a/docs/cmdline-opts/ftp-ssl-control.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ftp-ssl-control -Help: Require SSL/TLS for FTP login, clear for transfer -Protocols: FTP -Added: 7.16.0 -Category: ftp tls -Example: --ftp-ssl-control ftp://example.com -See-also: ssl -Multi: boolean ---- -Require SSL/TLS for the FTP login, clear for transfer. Allows secure -authentication, but non-encrypted data transfers for efficiency. Fails the -transfer if the server does not support SSL/TLS. diff --git a/docs/cmdline-opts/ftp-ssl-control.md b/docs/cmdline-opts/ftp-ssl-control.md new file mode 100644 index 00000000000..a68359a7b63 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-control.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ftp-ssl-control +Help: Require TLS for login, clear for transfer +Protocols: FTP +Added: 7.16.0 +Category: ftp tls +Multi: boolean +See-also: + - ssl +Example: + - --ftp-ssl-control ftp://example.com +--- + +# `--ftp-ssl-control` + +Require SSL/TLS for the FTP login, clear for transfer. Allows secure +authentication, but non-encrypted data transfers for efficiency. Fails the +transfer if the server does not support SSL/TLS. diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl deleted file mode 100755 index edf90622b2e..00000000000 --- a/docs/cmdline-opts/gen.pl +++ /dev/null @@ -1,750 +0,0 @@ -#!/usr/bin/env perl -#*************************************************************************** -# _ _ ____ _ -# Project ___| | | | _ \| | -# / __| | | | |_) | | -# | (__| |_| | _ <| |___ -# \___|\___/|_| \_\_____| -# -# Copyright (C) Daniel Stenberg, , et al. -# -# This software is licensed as described in the file COPYING, which -# you should have received as part of this distribution. The terms -# are also available at https://curl.se/docs/copyright.html. -# -# You may opt to use, copy, modify, merge, publish, distribute and/or sell -# copies of the Software, and permit persons to whom the Software is -# furnished to do so, under the terms of the COPYING file. -# -# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -# KIND, either express or implied. -# -# SPDX-License-Identifier: curl -# -########################################################################### - -=begin comment - -This script generates the manpage. - -Example: gen.pl [files] > curl.1 - -Dev notes: - -We open *input* files in :crlf translation (a no-op on many platforms) in -case we have CRLF line endings in Windows but a perl that defaults to LF. -Unfortunately it seems some perls like msysgit cannot handle a global input-only -:crlf so it has to be specified on each file open for text input. - -=end comment -=cut - -my %optshort; -my %optlong; -my %helplong; -my %arglong; -my %redirlong; -my %protolong; -my %catlong; - -use POSIX qw(strftime); -my @ts; -if (defined($ENV{SOURCE_DATE_EPOCH})) { - @ts = localtime($ENV{SOURCE_DATE_EPOCH}); -} else { - @ts = localtime; -} -my $date = strftime "%B %d %Y", @ts; -my $year = strftime "%Y", @ts; -my $version = "unknown"; -my $globals; - -open(INC, "<../../include/curl/curlver.h"); -while() { - if($_ =~ /^#define LIBCURL_VERSION \"([0-9.]*)/) { - $version = $1; - last; - } -} -close(INC); - -# get the long name version, return the man page string -sub manpageify { - my ($k)=@_; - my $l; - my $klong = $k; - # quote "bare" minuses in the long name - $klong =~ s/-/\\-/g; - if($optlong{$k} ne "") { - # both short + long - $l = "\\fI-".$optlong{$k}.", \\-\\-$klong\\fP"; - } - else { - # only long - $l = "\\fI\\-\\-$klong\\fP"; - } - return $l; -} - -sub printdesc { - my @desc = @_; - my $exam = 0; - for my $d (@desc) { - if($d =~ /\(Added in ([0-9.]+)\)/i) { - my $ver = $1; - if(too_old($ver)) { - $d =~ s/ *\(Added in $ver\)//gi; - } - } - if($d !~ /^.\\"/) { - # **bold** - $d =~ s/\*\*([^ ]*)\*\*/\\fB$1\\fP/g; - # *italics* - $d =~ s/\*([^ ]*)\*/\\fI$1\\fP/g; - } - if(!$exam && ($d =~ /^ /)) { - # start of example - $exam = 1; - print ".nf\n"; # no-fill - } - elsif($exam && ($d !~ /^ /)) { - # end of example - $exam = 0; - print ".fi\n"; # fill-in - } - # skip lines starting with space (examples) - if($d =~ /^[^ ]/ && $d =~ /--/) { - # scan for options in longest-names first order - for my $k (sort {length($b) <=> length($a)} keys %optlong) { - # --tlsv1 is complicated since --tlsv1.2 etc are also - # acceptable options! - if(($k eq "tlsv1") && ($d =~ /--tlsv1\.[0-9]\\f/)) { - next; - } - my $l = manpageify($k); - $d =~ s/\-\-$k([^a-z0-9-])/$l$1/g; - } - } - # quote minuses in the output - $d =~ s/([^\\])-/$1\\-/g; - # replace single quotes - $d =~ s/\'/\\(aq/g; - # handle double quotes first on the line - $d =~ s/^(\s*)\"/$1\\(dq/; - print $d; - } - if($exam) { - print ".fi\n"; # fill-in - } -} - -sub seealso { - my($standalone, $data)=@_; - if($standalone) { - return sprintf - ".SH \"SEE ALSO\"\n$data\n"; - } - else { - return "See also $data. "; - } -} - -sub overrides { - my ($standalone, $data)=@_; - if($standalone) { - return ".SH \"OVERRIDES\"\n$data\n"; - } - else { - return $data; - } -} - -sub protocols { - my ($standalone, $data)=@_; - if($standalone) { - return ".SH \"PROTOCOLS\"\n$data\n"; - } - else { - return "($data) "; - } -} - -sub too_old { - my ($version)=@_; - my $a = 999999; - if($version =~ /^(\d+)\.(\d+)\.(\d+)/) { - $a = $1 * 1000 + $2 * 10 + $3; - } - elsif($version =~ /^(\d+)\.(\d+)/) { - $a = $1 * 1000 + $2 * 10; - } - if($a < 7500) { - # we consider everything before 7.50.0 to be too old to mention - # specific changes for - return 1; - } - return 0; -} - -sub added { - my ($standalone, $data)=@_; - if(too_old($data)) { - # do not mention ancient additions - return ""; - } - if($standalone) { - return ".SH \"ADDED\"\nAdded in curl version $data\n"; - } - else { - return "Added in $data. "; - } -} - -sub single { - my ($f, $standalone)=@_; - open(F, "<:crlf", "$f") || - return 1; - my $short; - my $long; - my $tags; - my $added; - my $protocols; - my $arg; - my $mutexed; - my $requires; - my $category; - my $seealso; - my $copyright; - my $spdx; - my @examples; # there can be more than one - my $magic; # cmdline special option - my $line; - my $multi; - my $scope; - my $experimental; - while() { - $line++; - if(/^Short: *(.)/i) { - $short=$1; - } - elsif(/^Long: *(.*)/i) { - $long=$1; - } - elsif(/^Added: *(.*)/i) { - $added=$1; - } - elsif(/^Tags: *(.*)/i) { - $tags=$1; - } - elsif(/^Arg: *(.*)/i) { - $arg=$1; - } - elsif(/^Magic: *(.*)/i) { - $magic=$1; - } - elsif(/^Mutexed: *(.*)/i) { - $mutexed=$1; - } - elsif(/^Protocols: *(.*)/i) { - $protocols=$1; - } - elsif(/^See-also: *(.*)/i) { - if($seealso) { - print STDERR "ERROR: duplicated See-also in $f\n"; - return 1; - } - $seealso=$1; - } - elsif(/^Requires: *(.*)/i) { - $requires=$1; - } - elsif(/^Category: *(.*)/i) { - $category=$1; - } - elsif(/^Example: *(.*)/i) { - push @examples, $1; - } - elsif(/^Multi: *(.*)/i) { - $multi=$1; - } - elsif(/^Scope: *(.*)/i) { - $scope=$1; - } - elsif(/^Experimental: yes/i) { - $experimental=1; - } - elsif(/^C: (.*)/i) { - $copyright=$1; - } - elsif(/^SPDX-License-Identifier: (.*)/i) { - $spdx=$1; - } - elsif(/^Help: *(.*)/i) { - ; - } - elsif(/^---/) { - if(!$long) { - print STDERR "ERROR: no 'Long:' in $f\n"; - return 1; - } - if(!$category) { - print STDERR "ERROR: no 'Category:' in $f\n"; - return 2; - } - if(!$examples[0]) { - print STDERR "$f:$line:1:ERROR: no 'Example:' present\n"; - return 2; - } - if(!$added) { - print STDERR "$f:$line:1:ERROR: no 'Added:' version present\n"; - return 2; - } - if(!$seealso) { - print STDERR "$f:$line:1:ERROR: no 'See-also:' field present\n"; - return 2; - } - if(!$copyright) { - print STDERR "$f:$line:1:ERROR: no 'C:' field present\n"; - return 2; - } - if(!$spdx) { - print STDERR "$f:$line:1:ERROR: no 'SPDX-License-Identifier:' field present\n"; - return 2; - } - last; - } - else { - chomp; - print STDERR "WARN: unrecognized line in $f, ignoring:\n:'$_';" - } - } - my @desc; - while() { - push @desc, $_; - } - close(F); - my $opt; - - if(defined($short) && $long) { - $opt = "-$short, --$long"; - } - elsif($short && !$long) { - $opt = "-$short"; - } - elsif($long && !$short) { - $opt = "--$long"; - } - - if($arg) { - $opt .= " $arg"; - } - - # quote "bare" minuses in opt - $opt =~ s/-/\\-/g; - if($standalone) { - print ".TH curl 1 \"30 Nov 2016\" \"curl 7.52.0\" \"curl manual\"\n"; - print ".SH OPTION\n"; - print "curl $opt\n"; - } - else { - print ".IP \"$opt\"\n"; - } - if($protocols) { - print protocols($standalone, $protocols); - } - - if($standalone) { - print ".SH DESCRIPTION\n"; - } - - if($experimental) { - print "**WARNING**: this option is experimental. Do not use in production.\n\n"; - } - - printdesc(@desc); - undef @desc; - - if($scope) { - if($scope eq "global") { - print "\nThis option is global and does not need to be specified for each use of --next.\n"; - } - else { - print STDERR "$f:$line:1:ERROR: unrecognized scope: '$scope'\n"; - return 2; - } - } - - my @extra; - if($multi eq "single") { - push @extra, "\nIf --$long is provided several times, the last set ". - "value is used.\n"; - } - elsif($multi eq "append") { - push @extra, "\n--$long can be used several times in a command line\n"; - } - elsif($multi eq "boolean") { - my $rev = "no-$long"; - # for options that start with "no-" the reverse is then without - # the no- prefix - if($long =~ /^no-/) { - $rev = $long; - $rev =~ s/^no-//; - } - push @extra, - "\nProviding --$long multiple times has no extra effect.\n". - "Disable it again with \\-\\-$rev.\n"; - } - elsif($multi eq "mutex") { - push @extra, - "\nProviding --$long multiple times has no extra effect.\n"; - } - elsif($multi eq "custom") { - ; # left for the text to describe - } - else { - print STDERR "$f:$line:1:ERROR: unrecognized Multi: '$multi'\n"; - return 2; - } - - printdesc(@extra); - - my @foot; - if($seealso) { - my @m=split(/ /, $seealso); - my $mstr; - my $and = 0; - my $num = scalar(@m); - if($num > 2) { - # use commas up to this point - $and = $num - 1; - } - my $i = 0; - for my $k (@m) { - if(!$helplong{$k}) { - print STDERR "$f:$line:1:WARN: see-also a non-existing option: $k\n"; - } - my $l = manpageify($k); - my $sep = " and"; - if($and && ($i < $and)) { - $sep = ","; - } - $mstr .= sprintf "%s$l", $mstr?"$sep ":""; - $i++; - } - push @foot, seealso($standalone, $mstr); - } - - if($requires) { - my $l = manpageify($long); - push @foot, "$l requires that the underlying libcurl". - " was built to support $requires. "; - } - if($mutexed) { - my @m=split(/ /, $mutexed); - my $mstr; - for my $k (@m) { - if(!$helplong{$k}) { - print STDERR "WARN: $f mutexes a non-existing option: $k\n"; - } - my $l = manpageify($k); - $mstr .= sprintf "%s$l", $mstr?" and ":""; - } - push @foot, overrides($standalone, - "This option is mutually exclusive to $mstr. "); - } - if($examples[0]) { - my $s =""; - $s="s" if($examples[1]); - print "\nExample$s:\n.nf\n"; - foreach my $e (@examples) { - $e =~ s!\$URL!https://example.com!g; - $e =~ s/-/\\-/g; - $e =~ s/\'/\\(aq/g; - print " curl $e\n"; - } - print ".fi\n"; - } - if($added) { - push @foot, added($standalone, $added); - } - if($foot[0]) { - print "\n"; - my $f = join("", @foot); - $f =~ s/ +\z//; # remove trailing space - print "$f\n"; - } - return 0; -} - -sub getshortlong { - my ($f)=@_; - open(F, "<:crlf", "$f"); - my $short; - my $long; - my $help; - my $arg; - my $protocols; - my $category; - while() { - if(/^Short: (.)/i) { - $short=$1; - } - elsif(/^Long: (.*)/i) { - $long=$1; - } - elsif(/^Help: (.*)/i) { - $help=$1; - } - elsif(/^Arg: (.*)/i) { - $arg=$1; - } - elsif(/^Protocols: (.*)/i) { - $protocols=$1; - } - elsif(/^Category: (.*)/i) { - $category=$1; - } - elsif(/^---/) { - last; - } - } - close(F); - if($short) { - $optshort{$short}=$long; - } - if($long) { - $optlong{$long}=$short; - $helplong{$long}=$help; - $arglong{$long}=$arg; - $protolong{$long}=$protocols; - $catlong{$long}=$category; - } -} - -sub indexoptions { - my (@files) = @_; - foreach my $f (@files) { - getshortlong($f); - } -} - -sub header { - my ($f)=@_; - open(F, "<:crlf", "$f"); - my @d; - while() { - s/%DATE/$date/g; - s/%VERSION/$version/g; - s/%GLOBALS/$globals/g; - push @d, $_; - } - close(F); - printdesc(@d); -} - -sub listhelp { - print <, et al. - * - * This software is licensed as described in the file COPYING, which - * you should have received as part of this distribution. The terms - * are also available at https://curl.se/docs/copyright.html. - * - * You may opt to use, copy, modify, merge, publish, distribute and/or sell - * copies of the Software, and permit persons to whom the Software is - * furnished to do so, under the terms of the COPYING file. - * - * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY - * KIND, either express or implied. - * - * SPDX-License-Identifier: curl - * - ***************************************************************************/ -#include "tool_setup.h" -#include "tool_help.h" - -/* - * DO NOT edit tool_listhelp.c manually. - * This source file is generated with the following command: - - cd \$srcroot/docs/cmdline-opts - ./gen.pl listhelp *.d > \$srcroot/src/tool_listhelp.c - */ - -const struct helptxt helptext[] = { -HEAD - ; - foreach my $f (sort keys %helplong) { - my $long = $f; - my $short = $optlong{$long}; - my @categories = split ' ', $catlong{$long}; - my $bitmask = ' '; - my $opt; - - if(defined($short) && $long) { - $opt = "-$short, --$long"; - } - elsif($long && !$short) { - $opt = " --$long"; - } - for my $i (0 .. $#categories) { - $bitmask .= 'CURLHELP_' . uc $categories[$i]; - # If not last element, append | - if($i < $#categories) { - $bitmask .= ' | '; - } - } - $bitmask =~ s/(?=.{76}).{1,76}\|/$&\n /g; - my $arg = $arglong{$long}; - if($arg) { - $opt .= " $arg"; - } - my $desc = $helplong{$f}; - $desc =~ s/\"/\\\"/g; # escape double quotes - - my $line = sprintf " {\"%s\",\n \"%s\",\n %s},\n", $opt, $desc, $bitmask; - - if(length($opt) > 78) { - print STDERR "WARN: the --$long name is too long\n"; - } - elsif(length($desc) > 78) { - print STDERR "WARN: the --$long description is too long\n"; - } - print $line; - } - print <) { - if(/^Long: *(.*)/i) { - $long=$1; - } - elsif(/^Scope: global/i) { - push @globalopts, $long; - last; - } - elsif(/^---/) { - last; - } - } - close(F); - } - return $ret if($ret); - for my $e (0 .. $#globalopts) { - $globals .= sprintf "%s--%s", $e?($globalopts[$e+1] ? ", " : " and "):"", - $globalopts[$e],; - } -} - -sub mainpage { - my (@files) = @_; - my $ret; - # show the page header - header("page-header"); - - # output docs for all options - foreach my $f (sort @files) { - $ret += single($f, 0); - } - - if(!$ret) { - header("page-footer"); - } - exit $ret if($ret); -} - -sub showonly { - my ($f) = @_; - if(single($f, 1)) { - print STDERR "$f: failed\n"; - } -} - -sub showprotocols { - my %prots; - foreach my $f (keys %optlong) { - my @p = split(/ /, $protolong{$f}); - for my $p (@p) { - $prots{$p}++; - } - } - for(sort keys %prots) { - printf "$_ (%d options)\n", $prots{$_}; - } -} - -sub getargs { - my ($f, @s) = @_; - if($f eq "mainpage") { - listglobals(@s); - mainpage(@s); - return; - } - elsif($f eq "listhelp") { - listhelp(); - return; - } - elsif($f eq "single") { - showonly($s[0]); - return; - } - elsif($f eq "protos") { - showprotocols(); - return; - } - elsif($f eq "listcats") { - listcats(); - return; - } - - print "Usage: gen.pl [files]\n"; -} - -#------------------------------------------------------------------------ - -my $cmd = shift @ARGV; -my @files = @ARGV; # the rest are the files - -# learn all existing options -indexoptions(@files); - -getargs($cmd, @files); diff --git a/docs/cmdline-opts/get.d b/docs/cmdline-opts/get.d deleted file mode 100644 index 2e03a255bc8..00000000000 --- a/docs/cmdline-opts/get.d +++ /dev/null @@ -1,20 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: get -Short: G -Help: Put the post data in the URL and use GET -Category: http upload -Example: --get $URL -Example: --get -d "tool=curl" -d "age=old" $URL -Example: --get -I -d "tool=curl" $URL -Added: 7.8.1 -See-also: data request -Multi: boolean ---- -When used, this option makes all data specified with --data, --data-binary -or --data-urlencode to be used in an HTTP GET request instead of the POST -request that otherwise would be used. The data is appended to the URL -with a '?' separator. - -If used in combination with --head, the POST data is instead appended to the -URL with a HEAD request. diff --git a/docs/cmdline-opts/get.md b/docs/cmdline-opts/get.md new file mode 100644 index 00000000000..f8c8cf2f99b --- /dev/null +++ b/docs/cmdline-opts/get.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: get +Short: G +Help: Put the post data in the URL and use GET +Protocols: HTTP +Category: http upload +Added: 7.8.1 +Multi: boolean +See-also: + - data + - request +Example: + - --get $URL + - --get -d "tool=curl" -d "age=old" $URL + - --get -I -d "tool=curl" $URL +--- + +# `--get` + +When used, this option makes all data specified with --data, --data-binary +or --data-urlencode to be used in an HTTP GET request instead of the POST +request that otherwise would be used. The data is appended to the URL +with a '?' separator. + +If used in combination with --head, the POST data is instead appended to the +URL with a HEAD request. diff --git a/docs/cmdline-opts/globoff.d b/docs/cmdline-opts/globoff.d deleted file mode 100644 index 53bed6ec84e..00000000000 --- a/docs/cmdline-opts/globoff.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: globoff -Short: g -Help: Disable URL sequences and ranges using {} and [] -Category: curl -Example: -g "https://example.com/{[]}}}}" -Added: 7.6 -See-also: config disable -Multi: boolean ---- -This option switches off the "URL globbing parser". When you set this option, -you can specify URLs that contain the letters {}[] without having curl itself -interpret them. Note that these letters are not normal legal URL contents but -they should be encoded according to the URI standard. diff --git a/docs/cmdline-opts/globoff.md b/docs/cmdline-opts/globoff.md new file mode 100644 index 00000000000..3c8c341439d --- /dev/null +++ b/docs/cmdline-opts/globoff.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: globoff +Short: g +Help: Disable URL globbing with {} and [] +Category: curl +Added: 7.6 +Multi: boolean +See-also: + - config + - disable +Example: + - -g "https://example.com/{[]}}}}" +--- + +# `--globoff` + +Switch off the URL globbing function. When you set this option, you can +specify URLs that contain the letters {}[] without having curl itself +interpret them. Note that these letters are not normal legal URL contents but +they should be encoded according to the URI standard. diff --git a/docs/cmdline-opts/happy-eyeballs-timeout-ms.d b/docs/cmdline-opts/happy-eyeballs-timeout-ms.d deleted file mode 100644 index 29114e209a5..00000000000 --- a/docs/cmdline-opts/happy-eyeballs-timeout-ms.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: happy-eyeballs-timeout-ms -Arg: -Help: Time for IPv6 before trying IPv4 -Added: 7.59.0 -Category: connection -Example: --happy-eyeballs-timeout-ms 500 $URL -See-also: max-time connect-timeout -Multi: single ---- -Happy Eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6 -addresses for dual-stack hosts, giving IPv6 a head-start of the specified -number of milliseconds. If the IPv6 address cannot be connected to within that -time, then a connection attempt is made to the IPv4 address in parallel. The -first connection to be established is the one that is used. - -The range of suggested useful values is limited. Happy Eyeballs RFC 6555 says -"It is RECOMMENDED that connection attempts be paced 150-250 ms apart to -balance human factors against network load." libcurl currently defaults to -200 ms. Firefox and Chrome currently default to 300 ms. diff --git a/docs/cmdline-opts/happy-eyeballs-timeout-ms.md b/docs/cmdline-opts/happy-eyeballs-timeout-ms.md new file mode 100644 index 00000000000..8370ee92bbe --- /dev/null +++ b/docs/cmdline-opts/happy-eyeballs-timeout-ms.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: happy-eyeballs-timeout-ms +Arg: +Help: Time for IPv6 before IPv4 +Added: 7.59.0 +Category: connection +Multi: single +See-also: + - max-time + - connect-timeout +Example: + - --happy-eyeballs-timeout-ms 500 $URL +--- + +# `--happy-eyeballs-timeout-ms` + +Happy Eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6 +addresses for dual-stack hosts, giving IPv6 a head-start of the specified +number of milliseconds. If the IPv6 address cannot be connected to within that +time, then a connection attempt is made to the IPv4 address in parallel. The +first connection to be established is the one that is used. + +The range of suggested useful values is limited. Happy Eyeballs RFC 6555 says +"It is RECOMMENDED that connection attempts be paced 150-250 ms apart to +balance human factors against network load." libcurl currently defaults to +200 ms. Firefox and Chrome currently default to 300 ms. diff --git a/docs/cmdline-opts/haproxy-clientip.d b/docs/cmdline-opts/haproxy-clientip.d deleted file mode 100644 index 25cb7e62361..00000000000 --- a/docs/cmdline-opts/haproxy-clientip.d +++ /dev/null @@ -1,29 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: haproxy-clientip -Help: Sets client IP in HAProxy PROXY protocol v1 header -Protocols: HTTP -Added: 8.2.0 -Category: http proxy -Example: --haproxy-clientip $IP -See-also: proxy -Multi: single ---- -Sets a client IP in HAProxy PROXY protocol v1 header at the beginning of the -connection. - -For valid requests, IPv4 addresses must be indicated as a series of exactly -4 integers in the range [0..255] inclusive written in decimal representation -separated by exactly one dot between each other. Heading zeroes are not -permitted in front of numbers in order to avoid any possible confusion -with octal numbers. IPv6 addresses must be indicated as series of 4 hexadecimal -digits (upper or lower case) delimited by colons between each other, with the -acceptance of one double colon sequence to replace the largest acceptable range -of consecutive zeroes. The total number of decoded bits must exactly be 128. - -Otherwise, any string can be accepted for the client IP and get sent. - -It replaces --haproxy-protocol if used, it is not necessary to specify both flags. - -This option is primarily useful when sending test requests to -verify a service is working as intended. diff --git a/docs/cmdline-opts/haproxy-clientip.md b/docs/cmdline-opts/haproxy-clientip.md new file mode 100644 index 00000000000..fde085a9769 --- /dev/null +++ b/docs/cmdline-opts/haproxy-clientip.md @@ -0,0 +1,33 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: haproxy-clientip +Arg: +Help: Set address in HAProxy PROXY +Protocols: HTTP +Added: 8.2.0 +Category: http proxy +Multi: single +See-also: + - proxy +Example: + - --haproxy-clientip $IP +--- + +# `--haproxy-clientip` + +Sets a client IP in HAProxy PROXY protocol v1 header at the beginning of the +connection. + +For valid requests, IPv4 addresses must be indicated as a series of exactly +4 integers in the range [0..255] inclusive written in decimal representation +separated by exactly one dot between each other. Heading zeroes are not +permitted in front of numbers in order to avoid any possible confusion +with octal numbers. IPv6 addresses must be indicated as series of 4 hexadecimal +digits (upper or lower case) delimited by colons between each other, with the +acceptance of one double colon sequence to replace the largest acceptable range +of consecutive zeroes. The total number of decoded bits must exactly be 128. + +Otherwise, any string can be accepted for the client IP and get sent. + +It replaces --haproxy-protocol if used, it is not necessary to specify both flags. diff --git a/docs/cmdline-opts/haproxy-protocol.d b/docs/cmdline-opts/haproxy-protocol.d deleted file mode 100644 index 34119062e4b..00000000000 --- a/docs/cmdline-opts/haproxy-protocol.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: haproxy-protocol -Help: Send HAProxy PROXY protocol v1 header -Protocols: HTTP -Added: 7.60.0 -Category: http proxy -Example: --haproxy-protocol $URL -See-also: proxy -Multi: boolean ---- -Send a HAProxy PROXY protocol v1 header at the beginning of the -connection. This is used by some load balancers and reverse proxies to -indicate the client's true IP address and port. - -This option is primarily useful when sending test requests to a service that -expects this header. diff --git a/docs/cmdline-opts/haproxy-protocol.md b/docs/cmdline-opts/haproxy-protocol.md new file mode 100644 index 00000000000..26456c80bf4 --- /dev/null +++ b/docs/cmdline-opts/haproxy-protocol.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: haproxy-protocol +Help: Send HAProxy PROXY protocol v1 header +Protocols: HTTP +Added: 7.60.0 +Category: http proxy +Multi: boolean +See-also: + - proxy +Example: + - --haproxy-protocol $URL +--- + +# `--haproxy-protocol` + +Send a HAProxy PROXY protocol v1 header at the beginning of the connection. +This is used by some load balancers and reverse proxies to indicate the +client's true IP address and port. + +This option is primarily useful when sending test requests to a service that +expects this header. diff --git a/docs/cmdline-opts/head.d b/docs/cmdline-opts/head.d deleted file mode 100644 index bb748b72ef4..00000000000 --- a/docs/cmdline-opts/head.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: head -Short: I -Help: Show document info only -Protocols: HTTP FTP FILE -Category: http ftp file -Example: -I $URL -Added: 4.0 -See-also: get verbose trace-ascii -Multi: boolean ---- -Fetch the headers only! HTTP-servers feature the command HEAD which this uses -to get nothing but the header of a document. When used on an FTP or FILE file, -curl displays the file size and last modification time only. diff --git a/docs/cmdline-opts/head.md b/docs/cmdline-opts/head.md new file mode 100644 index 00000000000..be4dbb87fd6 --- /dev/null +++ b/docs/cmdline-opts/head.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: head +Short: I +Help: Show document info only +Protocols: HTTP FTP FILE +Category: http ftp file +Added: 4.0 +Multi: boolean +See-also: + - get + - verbose + - trace-ascii +Example: + - -I $URL +--- + +# `--head` + +Fetch the headers only! HTTP-servers feature the command HEAD which this uses +to get nothing but the header of a document. When used on an FTP or FILE file, +curl displays the file size and last modification time only. diff --git a/docs/cmdline-opts/header.d b/docs/cmdline-opts/header.d deleted file mode 100644 index 95c1565e8f2..00000000000 --- a/docs/cmdline-opts/header.d +++ /dev/null @@ -1,57 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: header -Short: H -Arg:
-Help: Pass custom header(s) to server -Protocols: HTTP IMAP SMTP -Category: http imap smtp -See-also: user-agent referer -Example: -H "X-First-Name: Joe" $URL -Example: -H "User-Agent: yes-please/2000" $URL -Example: -H "Host:" $URL -Example: -H @headers.txt $URL -Added: 5.0 -Multi: append ---- -Extra header to include in information sent. When used within an HTTP request, -it is added to the regular request headers. - -For an IMAP or SMTP MIME uploaded mail built with --form options, it is -prepended to the resulting MIME document, effectively including it at the mail -global level. It does not affect raw uploaded mails (Added in 7.56.0). - -You may specify any number of extra headers. Note that if you should add a -custom header that has the same name as one of the internal ones curl would -use, your externally set header is used instead of the internal one. This -allows you to make even trickier stuff than curl would normally do. You should -not replace internally set headers without knowing perfectly well what you are -doing. Remove an internal header by giving a replacement without content on -the right side of the colon, as in: -H "Host:". If you send the custom header -with no-value then its header must be terminated with a semicolon, such as \-H -"X-Custom-Header;" to send "X-Custom-Header:". - -curl makes sure that each header you add/replace is sent with the proper -end-of-line marker, you should thus **not** add that as a part of the header -content: do not add newlines or carriage returns, they only mess things up for -you. curl passes on the verbatim string you give it without any filter or -other safe guards. That includes white space and control characters. - -This option can take an argument in @filename style, which then adds a header -for each line in the input file. Using @- makes curl read the header file from -stdin. Added in 7.55.0. - -Please note that most anti-spam utilities check the presence and value of -several MIME mail headers: these are "From:", "To:", "Date:" and "Subject:" -among others and should be added with this option. - -You need --proxy-header to send custom headers intended for an HTTP -proxy. Added in 7.37.0. - -Passing on a "Transfer-Encoding: chunked" header when doing an HTTP request -with a request body, makes curl send the data using chunked encoding. - -**WARNING**: headers set with this option are set in all HTTP requests - even -after redirects are followed, like when told with --location. This can lead to -the header being sent to other hosts than the original host, so sensitive -headers should be used with caution combined with following redirects. diff --git a/docs/cmdline-opts/header.md b/docs/cmdline-opts/header.md new file mode 100644 index 00000000000..13ca4cb3221 --- /dev/null +++ b/docs/cmdline-opts/header.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: header +Short: H +Arg:
+Help: Pass custom header(s) to server +Protocols: HTTP IMAP SMTP +Category: http imap smtp +Added: 5.0 +Multi: append +See-also: + - user-agent + - referer +Example: + - -H "X-First-Name: Joe" $URL + - -H "User-Agent: yes-please/2000" $URL + - -H "Host:" $URL + - -H @headers.txt $URL +--- + +# `--header` + +Extra header to include in information sent. When used within an HTTP request, +it is added to the regular request headers. + +For an IMAP or SMTP MIME uploaded mail built with --form options, it is +prepended to the resulting MIME document, effectively including it at the mail +global level. It does not affect raw uploaded mails (Added in 7.56.0). + +You may specify any number of extra headers. Note that if you should add a +custom header that has the same name as one of the internal ones curl would +use, your externally set header is used instead of the internal one. This +allows you to make even trickier stuff than curl would normally do. You should +not replace internally set headers without knowing perfectly well what you are +doing. Remove an internal header by giving a replacement without content on +the right side of the colon, as in: -H `Host:`. If you send the custom header +with no-value then its header must be terminated with a semicolon, such as -H +`X-Custom-Header;` to send `X-Custom-Header:`. + +curl makes sure that each header you add/replace is sent with the proper +end-of-line marker, you should thus **not** add that as a part of the header +content: do not add newlines or carriage returns, they only mess things up for +you. curl passes on the verbatim string you give it without any filter or +other safe guards. That includes white space and control characters. + +This option can take an argument in @filename style, which then adds a header +for each line in the input file. Using @- makes curl read the header file from +stdin. Added in 7.55.0. + +Please note that most anti-spam utilities check the presence and value of +several MIME mail headers: these are `From:`, `To:`, `Date:` and `Subject:` +among others and should be added with this option. + +You need --proxy-header to send custom headers intended for an HTTP +proxy. Added in 7.37.0. + +Passing on a "Transfer-Encoding: chunked" header when doing an HTTP request +with a request body, makes curl send the data using chunked encoding. + +**WARNING**: headers set with this option are set in all HTTP requests - even +after redirects are followed, like when told with --location. This can lead to +the header being sent to other hosts than the original host, so sensitive +headers should be used with caution combined with following redirects. diff --git a/docs/cmdline-opts/help.d b/docs/cmdline-opts/help.d deleted file mode 100644 index f8675e48429..00000000000 --- a/docs/cmdline-opts/help.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: help -Arg: -Short: h -Help: Get help for commands -Category: important curl -Example: --help all -Added: 4.0 -See-also: verbose -Multi: custom ---- -Usage help. This lists all curl command line options within the given -**category**. - -If no argument is provided, curl displays only the most important command line -arguments. - -For category **all**, curl displays help for all options. - -If **category** is specified, curl displays all available help categories. diff --git a/docs/cmdline-opts/help.md b/docs/cmdline-opts/help.md new file mode 100644 index 00000000000..7477a1e4074 --- /dev/null +++ b/docs/cmdline-opts/help.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: help +Arg: +Short: h +Help: Get help for commands +Category: important curl +Added: 4.0 +Multi: custom +See-also: + - verbose +Example: + - --help all +--- + +# `--help` + +Usage help. List all curl command line options within the given **category**. + +If no argument is provided, curl displays the most important command line +arguments. + +For category **all**, curl displays help for all options. + +If **category** is specified, curl displays all available help categories. diff --git a/docs/cmdline-opts/hostpubmd5.d b/docs/cmdline-opts/hostpubmd5.d deleted file mode 100644 index e9db23db080..00000000000 --- a/docs/cmdline-opts/hostpubmd5.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: hostpubmd5 -Arg: -Help: Acceptable MD5 hash of the host public key -Protocols: SFTP SCP -Added: 7.17.1 -Category: sftp scp -Example: --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/ -See-also: hostpubsha256 -Multi: single ---- -Pass a string containing 32 hexadecimal digits. The string should -be the 128 bit MD5 checksum of the remote host's public key, curl refuses -the connection with the host unless the md5sums match. diff --git a/docs/cmdline-opts/hostpubmd5.md b/docs/cmdline-opts/hostpubmd5.md new file mode 100644 index 00000000000..7dc873254fc --- /dev/null +++ b/docs/cmdline-opts/hostpubmd5.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: hostpubmd5 +Arg: +Help: Acceptable MD5 hash of host public key +Protocols: SFTP SCP +Added: 7.17.1 +Category: sftp scp +Multi: single +See-also: + - hostpubsha256 +Example: + - --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/ +--- + +# `--hostpubmd5` + +Pass a string containing 32 hexadecimal digits. The string should be the 128 +bit **MD5** checksum of the remote host's public key, curl refuses the +connection with the host unless the checksums match. diff --git a/docs/cmdline-opts/hostpubsha256.d b/docs/cmdline-opts/hostpubsha256.d deleted file mode 100644 index b33f338bdd2..00000000000 --- a/docs/cmdline-opts/hostpubsha256.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: hostpubsha256 -Arg: -Help: Acceptable SHA256 hash of the host public key -Protocols: SFTP SCP -Added: 7.80.0 -Category: sftp scp -Example: --hostpubsha256 NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ= sftp://example.com/ -See-also: hostpubmd5 -Multi: single ---- -Pass a string containing a Base64-encoded SHA256 hash of the remote host's -public key. Curl refuses the connection with the host unless the hashes match. - -This feature requires libcurl to be built with libssh2 and does not work with -other SSH backends. diff --git a/docs/cmdline-opts/hostpubsha256.md b/docs/cmdline-opts/hostpubsha256.md new file mode 100644 index 00000000000..8ec080551d8 --- /dev/null +++ b/docs/cmdline-opts/hostpubsha256.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: hostpubsha256 +Arg: +Help: Acceptable SHA256 hash of host public key +Protocols: SFTP SCP +Added: 7.80.0 +Category: sftp scp +Multi: single +See-also: + - hostpubmd5 +Example: + - --hostpubsha256 NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ= sftp://example.com/ +--- + +# `--hostpubsha256` + +Pass a string containing a Base64-encoded SHA256 hash of the remote host's +public key. Curl refuses the connection with the host unless the hashes match. + +This feature requires libcurl to be built with libssh2 and does not work with +other SSH backends. diff --git a/docs/cmdline-opts/hsts.d b/docs/cmdline-opts/hsts.d deleted file mode 100644 index e30d3b419da..00000000000 --- a/docs/cmdline-opts/hsts.d +++ /dev/null @@ -1,26 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: hsts -Arg: -Protocols: HTTPS -Help: Enable HSTS with this cache file -Added: 7.74.0 -Category: http -Example: --hsts cache.txt $URL -See-also: proto -Multi: append ---- -This option enables HSTS for the transfer. If the file name points to an -existing HSTS cache file, that is used. After a completed transfer, the -cache is saved to the file name again if it has been modified. - -If curl is told to use HTTP:// for a transfer involving a host name that -exists in the HSTS cache, it upgrades the transfer to use HTTPS. Each HSTS -cache entry has an individual life time after which the upgrade is no longer -performed. - -Specify a "" file name (zero length) to avoid loading/saving and make curl -just handle HSTS in memory. - -If this option is used several times, curl loads contents from all the -files but the last one is used for saving. diff --git a/docs/cmdline-opts/hsts.md b/docs/cmdline-opts/hsts.md new file mode 100644 index 00000000000..9cae80c2f30 --- /dev/null +++ b/docs/cmdline-opts/hsts.md @@ -0,0 +1,32 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: hsts +Arg: +Protocols: HTTPS +Help: Enable HSTS with this cache file +Added: 7.74.0 +Category: http +Multi: append +See-also: + - proto +Example: + - --hsts cache.txt $URL +--- + +# `--hsts` + +Enable HSTS for the transfer. If the filename points to an existing HSTS cache +file, that is used. After a completed transfer, the cache is saved to the +filename again if it has been modified. + +If curl is told to use HTTP:// for a transfer involving a hostname that exists +in the HSTS cache, it upgrades the transfer to use HTTPS. Each HSTS cache +entry has an individual life time after which the upgrade is no longer +performed. + +Specify a "" filename (zero length) to avoid loading/saving and make curl just +handle HSTS in memory. + +If this option is used several times, curl loads contents from all the +files but the last one is used for saving. diff --git a/docs/cmdline-opts/http0.9.d b/docs/cmdline-opts/http0.9.d deleted file mode 100644 index 3dd14a05cee..00000000000 --- a/docs/cmdline-opts/http0.9.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: http0.9 -Tags: Versions -Protocols: HTTP -Help: Allow HTTP 0.9 responses -Category: http -Example: --http0.9 $URL -Added: 7.64.0 -See-also: http1.1 http2 http3 -Multi: boolean ---- -Tells curl to be fine with HTTP version 0.9 response. - -HTTP/0.9 is a response without headers and therefore you can also connect with -this to non-HTTP servers and still get a response since curl simply -transparently downgrades - if allowed. - -HTTP/0.9 is disabled by default (added in 7.66.0) diff --git a/docs/cmdline-opts/http0.9.md b/docs/cmdline-opts/http0.9.md new file mode 100644 index 00000000000..54ef3231564 --- /dev/null +++ b/docs/cmdline-opts/http0.9.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: http0.9 +Tags: Versions +Protocols: HTTP +Help: Allow HTTP 0.9 responses +Category: http +Added: 7.64.0 +Multi: boolean +See-also: + - http1.1 + - http2 + - http3 +Example: + - --http0.9 $URL +--- + +# `--http0.9` + +Accept an HTTP version 0.9 response. + +HTTP/0.9 is a response without headers and therefore you can also connect with +this to non-HTTP servers and still get a response since curl simply +transparently downgrades - if allowed. + +HTTP/0.9 is disabled by default (added in 7.66.0) diff --git a/docs/cmdline-opts/http1.0.d b/docs/cmdline-opts/http1.0.d deleted file mode 100644 index c5f4de872e4..00000000000 --- a/docs/cmdline-opts/http1.0.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: 0 -Long: http1.0 -Tags: Versions -Protocols: HTTP -Added: 7.9.1 -Mutexed: http1.1 http2 http2-prior-knowledge http3 -Help: Use HTTP 1.0 -Category: http -Example: --http1.0 $URL -See-also: http0.9 http1.1 -Multi: mutex ---- -Tells curl to use HTTP version 1.0 instead of using its internally preferred -HTTP version. diff --git a/docs/cmdline-opts/http1.0.md b/docs/cmdline-opts/http1.0.md new file mode 100644 index 00000000000..b810ccf3b70 --- /dev/null +++ b/docs/cmdline-opts/http1.0.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: 0 +Long: http1.0 +Tags: Versions +Protocols: HTTP +Added: 7.9.1 +Mutexed: http1.1 http2 http2-prior-knowledge http3 +Help: Use HTTP 1.0 +Category: http +Multi: mutex +See-also: + - http0.9 + - http1.1 +Example: + - --http1.0 $URL +--- + +# `--http1.0` + +Use HTTP version 1.0 instead of using its internally preferred HTTP version. diff --git a/docs/cmdline-opts/http1.1.d b/docs/cmdline-opts/http1.1.d deleted file mode 100644 index 3057aed36d3..00000000000 --- a/docs/cmdline-opts/http1.1.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: http1.1 -Tags: Versions -Protocols: HTTP -Added: 7.33.0 -Mutexed: http1.0 http2 http2-prior-knowledge http3 -Help: Use HTTP 1.1 -Category: http -Example: --http1.1 $URL -See-also: http1.0 http0.9 -Multi: mutex ---- -Tells curl to use HTTP version 1.1. diff --git a/docs/cmdline-opts/http1.1.md b/docs/cmdline-opts/http1.1.md new file mode 100644 index 00000000000..a223da1f9de --- /dev/null +++ b/docs/cmdline-opts/http1.1.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: http1.1 +Tags: Versions +Protocols: HTTP +Added: 7.33.0 +Mutexed: http1.0 http2 http2-prior-knowledge http3 +Help: Use HTTP 1.1 +Category: http +Multi: mutex +See-also: + - http1.0 + - http0.9 +Example: + - --http1.1 $URL +--- + +# `--http1.1` + +Use HTTP version 1.1. This is the default with HTTP:// URLs. diff --git a/docs/cmdline-opts/http2-prior-knowledge.d b/docs/cmdline-opts/http2-prior-knowledge.d deleted file mode 100644 index 7d7cabfd864..00000000000 --- a/docs/cmdline-opts/http2-prior-knowledge.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: http2-prior-knowledge -Tags: Versions -Protocols: HTTP -Added: 7.49.0 -Mutexed: http1.1 http1.0 http2 http3 -Requires: HTTP/2 -Help: Use HTTP 2 without HTTP/1.1 Upgrade -Category: http -Example: --http2-prior-knowledge $URL -See-also: http2 http3 -Multi: boolean ---- -Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1 -Upgrade. It requires prior knowledge that the server supports HTTP/2 straight -away. HTTPS requests still do HTTP/2 the standard way with negotiated protocol -version in the TLS handshake. diff --git a/docs/cmdline-opts/http2-prior-knowledge.md b/docs/cmdline-opts/http2-prior-knowledge.md new file mode 100644 index 00000000000..72701094172 --- /dev/null +++ b/docs/cmdline-opts/http2-prior-knowledge.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: http2-prior-knowledge +Tags: Versions +Protocols: HTTP +Added: 7.49.0 +Mutexed: http1.1 http1.0 http2 http3 +Requires: HTTP/2 +Help: Use HTTP 2 without HTTP/1.1 Upgrade +Category: http +Multi: boolean +See-also: + - http2 + - http3 +Example: + - --http2-prior-knowledge $URL +--- + +# `--http2-prior-knowledge` + +Issue a non-TLS HTTP requests using HTTP/2 directly without HTTP/1.1 Upgrade. +It requires prior knowledge that the server supports HTTP/2 straight away. +HTTPS requests still do HTTP/2 the standard way with negotiated protocol +version in the TLS handshake. diff --git a/docs/cmdline-opts/http2.d b/docs/cmdline-opts/http2.d deleted file mode 100644 index af5f3c4f5ae..00000000000 --- a/docs/cmdline-opts/http2.d +++ /dev/null @@ -1,25 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: http2 -Tags: Versions -Protocols: HTTP -Added: 7.33.0 -Mutexed: http1.1 http1.0 http2-prior-knowledge http3 -Requires: HTTP/2 -Help: Use HTTP/2 -See-also: http1.1 http3 no-alpn -Category: http -Example: --http2 $URL -Multi: mutex ---- -Tells curl to use HTTP version 2. - -For HTTPS, this means curl negotiates HTTP/2 in the TLS handshake. curl does -this by default. - -For HTTP, this means curl attempts to upgrade the request to HTTP/2 using the -Upgrade: request header. - -When curl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or -higher even though that is required by the specification. A user can add this -version requirement with --tlsv1.2. diff --git a/docs/cmdline-opts/http2.md b/docs/cmdline-opts/http2.md new file mode 100644 index 00000000000..ae4d26974c8 --- /dev/null +++ b/docs/cmdline-opts/http2.md @@ -0,0 +1,33 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: http2 +Tags: Versions +Protocols: HTTP +Added: 7.33.0 +Mutexed: http1.1 http1.0 http2-prior-knowledge http3 +Requires: HTTP/2 +Help: Use HTTP/2 +Category: http +Multi: mutex +See-also: + - http1.1 + - http3 + - no-alpn +Example: + - --http2 $URL +--- + +# `--http2` + +Use HTTP/2. + +For HTTPS, this means curl negotiates HTTP/2 in the TLS handshake. curl does +this by default. + +For HTTP, this means curl attempts to upgrade the request to HTTP/2 using the +Upgrade: request header. + +When curl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or +higher even though that is required by the specification. A user can add this +version requirement with --tlsv1.2. diff --git a/docs/cmdline-opts/http3-only.d b/docs/cmdline-opts/http3-only.d deleted file mode 100644 index c3f0f31aa1b..00000000000 --- a/docs/cmdline-opts/http3-only.d +++ /dev/null @@ -1,25 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: http3-only -Tags: Versions -Protocols: HTTP -Added: 7.88.0 -Mutexed: http1.1 http1.0 http2 http2-prior-knowledge http3 -Requires: HTTP/3 -Help: Use HTTP v3 only -See-also: http1.1 http2 http3 -Category: http -Example: --http3-only $URL -Multi: mutex -Experimental: yes ---- -Instructs curl to use HTTP/3 to the host in the URL, with no fallback to -earlier HTTP versions. HTTP/3 can only be used for HTTPS and not for HTTP -URLs. For HTTP, this option triggers an error. - -This option allows a user to avoid using the Alt-Svc method of upgrading to -HTTP/3 when you know that the target speaks HTTP/3 on the given host and port. - -This option makes curl fail if a QUIC connection cannot be established, it -does not attempt any other HTTP versions on its own. Use --http3 for similar -functionality *with* a fallback. diff --git a/docs/cmdline-opts/http3-only.md b/docs/cmdline-opts/http3-only.md new file mode 100644 index 00000000000..c565f8b95d3 --- /dev/null +++ b/docs/cmdline-opts/http3-only.md @@ -0,0 +1,32 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: http3-only +Tags: Versions +Protocols: HTTP +Added: 7.88.0 +Mutexed: http1.1 http1.0 http2 http2-prior-knowledge http3 +Requires: HTTP/3 +Help: Use HTTP v3 only +Category: http +Multi: mutex +See-also: + - http1.1 + - http2 + - http3 +Example: + - --http3-only $URL +--- + +# `--http3-only` + +Instructs curl to use HTTP/3 to the host in the URL, with no fallback to +earlier HTTP versions. HTTP/3 can only be used for HTTPS and not for HTTP +URLs. For HTTP, this option triggers an error. + +This option allows a user to avoid using the Alt-Svc method of upgrading to +HTTP/3 when you know that the target speaks HTTP/3 on the given host and port. + +This option makes curl fail if a QUIC connection cannot be established, it +does not attempt any other HTTP versions on its own. Use --http3 for similar +functionality *with* a fallback. diff --git a/docs/cmdline-opts/http3.d b/docs/cmdline-opts/http3.d deleted file mode 100644 index a8258c4d313..00000000000 --- a/docs/cmdline-opts/http3.d +++ /dev/null @@ -1,27 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: http3 -Tags: Versions -Protocols: HTTP -Added: 7.66.0 -Mutexed: http1.1 http1.0 http2 http2-prior-knowledge http3-only -Requires: HTTP/3 -Help: Use HTTP v3 -See-also: http1.1 http2 -Category: http -Example: --http3 $URL -Multi: mutex -Experimental: yes ---- -Tells curl to try HTTP/3 to the host in the URL, but fallback to earlier -HTTP versions if the HTTP/3 connection establishment fails. HTTP/3 is only -available for HTTPS and not for HTTP URLs. - -This option allows a user to avoid using the Alt-Svc method of upgrading to -HTTP/3 when you know that the target speaks HTTP/3 on the given host and port. - -When asked to use HTTP/3, curl issues a separate attempt to use older HTTP -versions with a slight delay, so if the HTTP/3 transfer fails or is slow, curl -still tries to proceed with an older HTTP version. - -Use --http3-only for similar functionality *without* a fallback. diff --git a/docs/cmdline-opts/http3.md b/docs/cmdline-opts/http3.md new file mode 100644 index 00000000000..a1900655a0b --- /dev/null +++ b/docs/cmdline-opts/http3.md @@ -0,0 +1,33 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: http3 +Tags: Versions +Protocols: HTTP +Added: 7.66.0 +Mutexed: http1.1 http1.0 http2 http2-prior-knowledge http3-only +Requires: HTTP/3 +Help: Use HTTP v3 +Category: http +Multi: mutex +See-also: + - http1.1 + - http2 +Example: + - --http3 $URL +--- + +# `--http3` + +Attempt HTTP/3 to the host in the URL, but fallback to earlier HTTP versions +if the HTTP/3 connection establishment fails. HTTP/3 is only available for +HTTPS and not for HTTP URLs. + +This option allows a user to avoid using the Alt-Svc method of upgrading to +HTTP/3 when you know that the target speaks HTTP/3 on the given host and port. + +When asked to use HTTP/3, curl issues a separate attempt to use older HTTP +versions with a slight delay, so if the HTTP/3 transfer fails or is slow, curl +still tries to proceed with an older HTTP version. + +Use --http3-only for similar functionality *without* a fallback. diff --git a/docs/cmdline-opts/ignore-content-length.d b/docs/cmdline-opts/ignore-content-length.d deleted file mode 100644 index 505c04c18bf..00000000000 --- a/docs/cmdline-opts/ignore-content-length.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ignore-content-length -Help: Ignore the size of the remote resource -Protocols: FTP HTTP -Category: http ftp -Example: --ignore-content-length $URL -Added: 7.14.1 -See-also: ftp-skip-pasv-ip -Multi: boolean ---- -For HTTP, Ignore the Content-Length header. This is particularly useful for -servers running Apache 1.x, which reports incorrect Content-Length for -files larger than 2 gigabytes. - -For FTP, this makes curl skip the SIZE command to figure out the size before -downloading a file (added in 7.46.0). - -This option does not work for HTTP if libcurl was built to use hyper. diff --git a/docs/cmdline-opts/ignore-content-length.md b/docs/cmdline-opts/ignore-content-length.md new file mode 100644 index 00000000000..b9f7522da53 --- /dev/null +++ b/docs/cmdline-opts/ignore-content-length.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ignore-content-length +Help: Ignore the size of the remote resource +Protocols: FTP HTTP +Category: http ftp +Added: 7.14.1 +Multi: boolean +See-also: + - ftp-skip-pasv-ip +Example: + - --ignore-content-length $URL +--- + +# `--ignore-content-length` + +For HTTP, Ignore the Content-Length header. This is particularly useful for +servers running Apache 1.x, which reports incorrect Content-Length for +files larger than 2 gigabytes. + +For FTP, this makes curl skip the SIZE command to figure out the size before +downloading a file (added in 7.46.0). + +This option does not work for HTTP if libcurl was built to use hyper. diff --git a/docs/cmdline-opts/include.d b/docs/cmdline-opts/include.d deleted file mode 100644 index ce7b9d87b47..00000000000 --- a/docs/cmdline-opts/include.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: include -Short: i -Help: Include protocol response headers in the output -See-also: verbose -Category: important verbose -Example: -i $URL -Added: 4.8 -Multi: boolean ---- -Include the HTTP response headers in the output. The HTTP response headers can -include things like server name, cookies, date of the document, HTTP version -and more... - -To view the request headers, consider the --verbose option. - -Prior to 7.75.0 curl did not print the headers if --fail was used in -combination with this option and there was error reported by server. diff --git a/docs/cmdline-opts/include.md b/docs/cmdline-opts/include.md new file mode 100644 index 00000000000..c4f6beb81cd --- /dev/null +++ b/docs/cmdline-opts/include.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: include +Short: i +Help: Include response headers in output +Protocols: HTTP FTP +Category: important verbose +Added: 4.8 +Multi: boolean +See-also: + - verbose +Example: + - -i $URL +--- + +# `--include` + +Include response headers in the output. HTTP response headers can include +things like server name, cookies, date of the document, HTTP version and +more... With non-HTTP protocols, the "headers" are other server communication. + +To view the request headers, consider the --verbose option. + +Prior to 7.75.0 curl did not print the headers if --fail was used in +combination with this option and there was error reported by server. diff --git a/docs/cmdline-opts/insecure.d b/docs/cmdline-opts/insecure.d deleted file mode 100644 index e48d5000298..00000000000 --- a/docs/cmdline-opts/insecure.d +++ /dev/null @@ -1,33 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: insecure -Short: k -Help: Allow insecure server connections -Protocols: TLS SFTP SCP -See-also: proxy-insecure cacert capath -Category: tls sftp scp -Example: --insecure $URL -Added: 7.10 -Multi: boolean ---- -By default, every secure connection curl makes is verified to be secure before -the transfer takes place. This option makes curl skip the verification step -and proceed without checking. - -When this option is not used for protocols using TLS, curl verifies the -server's TLS certificate before it continues: that the certificate contains -the right name which matches the host name used in the URL and that the -certificate has been signed by a CA certificate present in the cert store. -See this online resource for further details: - https://curl.se/docs/sslcerts.html - -For SFTP and SCP, this option makes curl skip the *known_hosts* verification. -*known_hosts* is a file normally stored in the user's home directory in the -".ssh" subdirectory, which contains host names and their public keys. - -**WARNING**: using this option makes the transfer insecure. - -When curl uses secure protocols it trusts responses and allows for example -HSTS and Alt-Svc information to be stored and used subsequently. Using ---insecure can make curl trust and use such information from malicious -servers. diff --git a/docs/cmdline-opts/insecure.md b/docs/cmdline-opts/insecure.md new file mode 100644 index 00000000000..b1c056b448b --- /dev/null +++ b/docs/cmdline-opts/insecure.md @@ -0,0 +1,41 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: insecure +Short: k +Help: Allow insecure server connections +Protocols: TLS SFTP SCP +Category: tls sftp scp +Added: 7.10 +Multi: boolean +See-also: + - proxy-insecure + - cacert + - capath +Example: + - --insecure $URL +--- + +# `--insecure` + +By default, every secure connection curl makes is verified to be secure before +the transfer takes place. This option makes curl skip the verification step +and proceed without checking. + +When this option is not used for protocols using TLS, curl verifies the +server's TLS certificate before it continues: that the certificate contains +the right name which matches the hostname used in the URL and that the +certificate has been signed by a CA certificate present in the cert store. See +this online resource for further details: +**https://curl.se/docs/sslcerts.html** + +For SFTP and SCP, this option makes curl skip the *known_hosts* verification. +*known_hosts* is a file normally stored in the user's home directory in the +".ssh" subdirectory, which contains hostnames and their public keys. + +**WARNING**: using this option makes the transfer insecure. + +When curl uses secure protocols it trusts responses and allows for example +HSTS and Alt-Svc information to be stored and used subsequently. Using +--insecure can make curl trust and use such information from malicious +servers. diff --git a/docs/cmdline-opts/interface.d b/docs/cmdline-opts/interface.d deleted file mode 100644 index 026ceaef5a6..00000000000 --- a/docs/cmdline-opts/interface.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: interface -Arg: -Help: Use network INTERFACE (or address) -See-also: dns-interface -Category: connection -Example: --interface eth0 $URL -Added: 7.3 -Multi: single ---- -Perform an operation using a specified interface. You can enter interface -name, IP address or host name. An example could look like: - - curl --interface eth0:1 https://www.example.com/ - -On Linux it can be used to specify a **VRF**, but the binary needs to either -have **CAP_NET_RAW** or to be run as root. More information about Linux -**VRF**: https://www.kernel.org/doc/Documentation/networking/vrf.txt diff --git a/docs/cmdline-opts/interface.md b/docs/cmdline-opts/interface.md new file mode 100644 index 00000000000..c938fd2717b --- /dev/null +++ b/docs/cmdline-opts/interface.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: interface +Arg: +Help: Use network INTERFACE (or address) +Category: connection +Added: 7.3 +Multi: single +See-also: + - dns-interface +Example: + - --interface eth0 $URL +--- + +# `--interface` + +Perform an operation using a specified interface. You can enter interface +name, IP address or hostname. An example could look like: + + curl --interface eth0:1 https://www.example.com/ + +On Linux it can be used to specify a **VRF**, but the binary needs to either +have **CAP_NET_RAW** or to be run as root. More information about Linux +**VRF**: https://www.kernel.org/doc/Documentation/networking/vrf.txt diff --git a/docs/cmdline-opts/ipfs-gateway.d b/docs/cmdline-opts/ipfs-gateway.d deleted file mode 100644 index e6845b327a6..00000000000 --- a/docs/cmdline-opts/ipfs-gateway.d +++ /dev/null @@ -1,32 +0,0 @@ -c: Copyright (C) 2023, Mark Gaiser, -SPDX-License-Identifier: curl -Long: ipfs-gateway -Arg: -Help: Gateway for IPFS -Added: 8.4.0 -See-also: help manual -Category: ipfs -Example: --ipfs-gateway $URL ipfs:// -Multi: single ---- -Specify which gateway to use for IPFS and IPNS URLs. Not specifying this will -instead make curl check if the IPFS_GATEWAY environment variable is set, or if -a ~/.ipfs/gateway file holding the gateway URL exists. - -If you run a local IPFS node, this gateway is by default available under -http://localhost:8080. A full example URL would look like: - - curl --ipfs-gateway http://localhost:8080 ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi - -There are many public IPFS gateways. See for example: - - https://ipfs.github.io/public-gateway-checker/ - -WARNING: If you opt to go for a remote gateway you should be aware that you -completely trust the gateway. This is fine in local gateways as you host it -yourself. With remote gateways there could potentially be a malicious actor -returning you data that does not match the request you made, inspect or even -interfere with the request. You will not notice this when using curl. A -mitigation could be to go for a "trustless" gateway. This means you locally -verify that the data. Consult the docs page on trusted vs trustless: -https://docs.ipfs.tech/reference/http/gateway/#trusted-vs-trustless diff --git a/docs/cmdline-opts/ipfs-gateway.md b/docs/cmdline-opts/ipfs-gateway.md new file mode 100644 index 00000000000..63429d83d12 --- /dev/null +++ b/docs/cmdline-opts/ipfs-gateway.md @@ -0,0 +1,39 @@ +--- +c: Copyright (C) Mark Gaiser, +SPDX-License-Identifier: curl +Long: ipfs-gateway +Arg: +Help: Gateway for IPFS +Protocols: IPFS +Added: 8.4.0 +Category: ipfs +Multi: single +See-also: + - help + - manual +Example: + - --ipfs-gateway $URL ipfs:// +--- + +# `--ipfs-gateway` + +Specify which gateway to use for IPFS and IPNS URLs. Not specifying this +instead makes curl check if the IPFS_GATEWAY environment variable is set, or +if a `~/.ipfs/gateway` file holding the gateway URL exists. + +If you run a local IPFS node, this gateway is by default available under +`http://localhost:8080`. A full example URL would look like: + + curl --ipfs-gateway http://localhost:8080 ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi + +There are many public IPFS gateways. See for example: +https://ipfs.github.io/public-gateway-checker/ + +If you opt to go for a remote gateway you need to be aware that you completely +trust the gateway. This might be fine in local gateways that you host +yourself. With remote gateways there could potentially be malicious actors +returning you data that does not match the request you made, inspect or even +interfere with the request. You may not notice this when using curl. A +mitigation could be to go for a "trustless" gateway. This means you locally +verify that the data. Consult the docs page on trusted vs trustless: +https://docs.ipfs.tech/reference/http/gateway/#trusted-vs-trustless diff --git a/docs/cmdline-opts/ipv4.d b/docs/cmdline-opts/ipv4.d deleted file mode 100644 index 60690bedcfc..00000000000 --- a/docs/cmdline-opts/ipv4.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: 4 -Long: ipv4 -Tags: Versions -Protocols: -Added: 7.10.8 -Mutexed: ipv6 -Requires: -See-also: http1.1 http2 -Help: Resolve names to IPv4 addresses -Category: connection dns -Example: --ipv4 $URL -Multi: mutex ---- -This option tells curl to use IPv4 addresses only when resolving host names, -and not for example try IPv6. diff --git a/docs/cmdline-opts/ipv4.md b/docs/cmdline-opts/ipv4.md new file mode 100644 index 00000000000..b790cc65aaa --- /dev/null +++ b/docs/cmdline-opts/ipv4.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: 4 +Long: ipv4 +Tags: Versions +Protocols: +Added: 7.10.8 +Mutexed: ipv6 +Requires: +Help: Resolve names to IPv4 addresses +Category: connection dns +Multi: mutex +See-also: + - http1.1 + - http2 +Example: + - --ipv4 $URL +--- + +# `--ipv4` + +Use IPv4 addresses only when resolving hostnames, and not for example try +IPv6. diff --git a/docs/cmdline-opts/ipv6.d b/docs/cmdline-opts/ipv6.d deleted file mode 100644 index 24ce201a2e2..00000000000 --- a/docs/cmdline-opts/ipv6.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: 6 -Long: ipv6 -Tags: Versions -Protocols: -Added: 7.10.8 -Mutexed: ipv4 -Requires: -See-also: http1.1 http2 -Help: Resolve names to IPv6 addresses -Category: connection dns -Example: --ipv6 $URL -Multi: mutex ---- -This option tells curl to use IPv6 addresses only when resolving host names, -and not for example try IPv4. diff --git a/docs/cmdline-opts/ipv6.md b/docs/cmdline-opts/ipv6.md new file mode 100644 index 00000000000..547f4917c2c --- /dev/null +++ b/docs/cmdline-opts/ipv6.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: 6 +Long: ipv6 +Tags: Versions +Protocols: +Added: 7.10.8 +Mutexed: ipv4 +Requires: +Help: Resolve names to IPv6 addresses +Category: connection dns +Multi: mutex +See-also: + - http1.1 + - http2 +Example: + - --ipv6 $URL +--- + +# `--ipv6` + +Use IPv6 addresses only when resolving hostnames, and not for example try +IPv4. + +Your resolver may respond to an IPv6-only resolve request by returning IPv6 +addresses that contain "mapped" IPv4 addresses for compatibility purposes. +macOS is known to do this. diff --git a/docs/cmdline-opts/json.d b/docs/cmdline-opts/json.d deleted file mode 100644 index aa3b49de2f9..00000000000 --- a/docs/cmdline-opts/json.d +++ /dev/null @@ -1,35 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: json -Arg: -Help: HTTP POST JSON -Protocols: HTTP -See-also: data-binary data-raw -Mutexed: form head upload-file -Category: http post upload -Example: --json '{ "drink": "coffe" }' $URL -Example: --json '{ "drink":' --json ' "coffe" }' $URL -Example: --json @prepared $URL -Example: --json @- $URL < json.txt -Added: 7.82.0 -Multi: append ---- -Sends the specified JSON data in a POST request to the HTTP server. --json -works as a shortcut for passing on these three options: - - --data [arg] - --header "Content-Type: application/json" - --header "Accept: application/json" - -There is **no verification** that the passed in data is actual JSON or that -the syntax is correct. - -If you start the data with the letter @, the rest should be a file name to -read the data from, or a single dash (-) if you want curl to read the data -from stdin. Posting data from a file named 'foobar' would thus be done with ---json @foobar and to instead read the data from stdin, use --json @-. - -If this option is used more than once on the same command line, the additional -data pieces are concatenated to the previous before sending. - -The headers this option sets can be overridden with --header as usual. diff --git a/docs/cmdline-opts/json.md b/docs/cmdline-opts/json.md new file mode 100644 index 00000000000..8056e62e7cf --- /dev/null +++ b/docs/cmdline-opts/json.md @@ -0,0 +1,42 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: json +Arg: +Help: HTTP POST JSON +Protocols: HTTP +Mutexed: form head upload-file +Category: http post upload +Added: 7.82.0 +Multi: append +See-also: + - data-binary + - data-raw +Example: + - --json '{ "drink": "coffe" }' $URL + - --json '{ "drink":' --json ' "coffe" }' $URL + - --json @prepared $URL + - --json @- $URL < json.txt +--- + +# `--json` + +Sends the specified JSON data in a POST request to the HTTP server. --json +works as a shortcut for passing on these three options: + + --data [arg] + --header "Content-Type: application/json" + --header "Accept: application/json" + +There is **no verification** that the passed in data is actual JSON or that +the syntax is correct. + +If you start the data with the letter @, the rest should be a filename to read +the data from, or a single dash (-) if you want curl to read the data from +stdin. Posting data from a file named 'foobar' would thus be done with --json +@foobar and to instead read the data from stdin, use --json @-. + +If this option is used more than once on the same command line, the additional +data pieces are concatenated to the previous before sending. + +The headers this option sets can be overridden with --header as usual. diff --git a/docs/cmdline-opts/junk-session-cookies.d b/docs/cmdline-opts/junk-session-cookies.d deleted file mode 100644 index daea7840add..00000000000 --- a/docs/cmdline-opts/junk-session-cookies.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: junk-session-cookies -Short: j -Help: Ignore session cookies read from file -Protocols: HTTP -See-also: cookie cookie-jar -Category: http -Example: --junk-session-cookies -b cookies.txt $URL -Added: 7.9.7 -Multi: boolean ---- -When curl is told to read cookies from a given file, this option makes it -discard all "session cookies". This has the same effect as if a new session is -started. Typical browsers discard session cookies when they are closed down. diff --git a/docs/cmdline-opts/junk-session-cookies.md b/docs/cmdline-opts/junk-session-cookies.md new file mode 100644 index 00000000000..63971050c03 --- /dev/null +++ b/docs/cmdline-opts/junk-session-cookies.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: junk-session-cookies +Short: j +Help: Ignore session cookies read from file +Protocols: HTTP +Category: http +Added: 7.9.7 +Multi: boolean +See-also: + - cookie + - cookie-jar +Example: + - --junk-session-cookies -b cookies.txt $URL +--- + +# `--junk-session-cookies` + +When curl is told to read cookies from a given file, this option makes it +discard all "session cookies". This has the same effect as if a new session is +started. Typical browsers discard session cookies when they are closed down. diff --git a/docs/cmdline-opts/keepalive-time.d b/docs/cmdline-opts/keepalive-time.d deleted file mode 100644 index 5e284774dff..00000000000 --- a/docs/cmdline-opts/keepalive-time.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: keepalive-time -Arg: -Help: Interval time for keepalive probes -Added: 7.18.0 -Category: connection -Example: --keepalive-time 20 $URL -See-also: no-keepalive max-time -Multi: single ---- -This option sets the time a connection needs to remain idle before sending -keepalive probes and the time between individual keepalive probes. It is -currently effective on operating systems offering the TCP_KEEPIDLE and -TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). -Keepalives are used by the TCP stack to detect broken networks on idle -connections. The number of missed keepalive probes before declaring the -connection down is OS dependent and is commonly 9 or 10. This option has no -effect if --no-keepalive is used. - -If unspecified, the option defaults to 60 seconds. diff --git a/docs/cmdline-opts/keepalive-time.md b/docs/cmdline-opts/keepalive-time.md new file mode 100644 index 00000000000..41c09031ec5 --- /dev/null +++ b/docs/cmdline-opts/keepalive-time.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: keepalive-time +Arg: +Help: Interval time for keepalive probes +Added: 7.18.0 +Category: connection +Multi: single +See-also: + - no-keepalive + - max-time +Example: + - --keepalive-time 20 $URL +--- + +# `--keepalive-time` + +Set the time a connection needs to remain idle before sending keepalive probes +and the time between individual keepalive probes. It is currently effective on +operating systems offering the `TCP_KEEPIDLE` and `TCP_KEEPINTVL` socket +options (meaning Linux, recent AIX, HP-UX and more). Keepalive is used by the +TCP stack to detect broken networks on idle connections. The number of missed +keepalive probes before declaring the connection down is OS dependent and is +commonly 9 or 10. This option has no effect if --no-keepalive is used. + +If unspecified, the option defaults to 60 seconds. diff --git a/docs/cmdline-opts/key-type.d b/docs/cmdline-opts/key-type.d deleted file mode 100644 index 22339b4c90e..00000000000 --- a/docs/cmdline-opts/key-type.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: key-type -Arg: -Help: Private key file type (DER/PEM/ENG) -Protocols: TLS -Category: tls -Example: --key-type DER --key here $URL -Added: 7.9.3 -See-also: key -Multi: single ---- -Private key file type. Specify which type your --key provided private key -is. DER, PEM, and ENG are supported. If not specified, PEM is assumed. diff --git a/docs/cmdline-opts/key-type.md b/docs/cmdline-opts/key-type.md new file mode 100644 index 00000000000..4128bfeafcd --- /dev/null +++ b/docs/cmdline-opts/key-type.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: key-type +Arg: +Help: Private key file type (DER/PEM/ENG) +Protocols: TLS +Category: tls +Added: 7.9.3 +Multi: single +See-also: + - key +Example: + - --key-type DER --key here $URL +--- + +# `--key-type` + +Private key file type. Specify which type your --key provided private key +is. DER, PEM, and ENG are supported. If not specified, PEM is assumed. diff --git a/docs/cmdline-opts/key.d b/docs/cmdline-opts/key.d deleted file mode 100644 index 4236218c9dd..00000000000 --- a/docs/cmdline-opts/key.d +++ /dev/null @@ -1,27 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: key -Arg: -Protocols: TLS SSH -Help: Private key file name -Category: tls ssh -Example: --cert certificate --key here $URL -Added: 7.9.3 -See-also: key-type cert -Multi: single ---- -Private key file name. Allows you to provide your private key in this separate -file. For SSH, if not specified, curl tries the following candidates in order: -'~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'. - -If curl is built against OpenSSL library, and the engine pkcs11 is available, -then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in -a PKCS#11 device. A string beginning with "pkcs11:" is interpreted as a -PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as -"pkcs11" if none was provided and the --key-type option is set as "ENG" if -none was provided. - -If curl is built against Secure Transport or Schannel then this option is -ignored for TLS protocols (HTTPS, etc). Those backends expect the private key -to be already present in the keychain or PKCS#12 file containing the -certificate. diff --git a/docs/cmdline-opts/key.md b/docs/cmdline-opts/key.md new file mode 100644 index 00000000000..80540ab9570 --- /dev/null +++ b/docs/cmdline-opts/key.md @@ -0,0 +1,34 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: key +Arg: +Protocols: TLS SSH +Help: Private key filename +Category: tls ssh +Added: 7.9.3 +Multi: single +See-also: + - key-type + - cert +Example: + - --cert certificate --key here $URL +--- + +# `--key` + +Private key filename. Allows you to provide your private key in this separate +file. For SSH, if not specified, curl tries the following candidates in order: +`~/.ssh/id_rsa`, `~/.ssh/id_dsa`, `./id_rsa`, `./id_dsa`. + +If curl is built against OpenSSL library, and the engine pkcs11 is available, +then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in +a PKCS#11 device. A string beginning with `pkcs11:` is interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as +`pkcs11` if none was provided and the --key-type option is set as `ENG` if +none was provided. + +If curl is built against Secure Transport or Schannel then this option is +ignored for TLS protocols (HTTPS, etc). Those backends expect the private key +to be already present in the keychain or PKCS#12 file containing the +certificate. diff --git a/docs/cmdline-opts/krb.d b/docs/cmdline-opts/krb.d deleted file mode 100644 index 42aa67ada40..00000000000 --- a/docs/cmdline-opts/krb.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: krb -Arg: -Help: Enable Kerberos with security -Protocols: FTP -Requires: Kerberos -Category: ftp -Example: --krb clear ftp://example.com/ -Added: 7.3 -See-also: delegation ssl -Multi: single ---- -Enable Kerberos authentication and use. The level must be entered and should -be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a -level that is not one of these, 'private' is used. diff --git a/docs/cmdline-opts/krb.md b/docs/cmdline-opts/krb.md new file mode 100644 index 00000000000..c353a0c7400 --- /dev/null +++ b/docs/cmdline-opts/krb.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: krb +Arg: +Help: Enable Kerberos with security +Protocols: FTP +Requires: Kerberos +Category: ftp +Added: 7.3 +Multi: single +See-also: + - delegation + - ssl +Example: + - --krb clear ftp://example.com/ +--- + +# `--krb` + +Enable Kerberos authentication and use. The level must be entered and should +be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a +level that is not one of these, 'private' is used. diff --git a/docs/cmdline-opts/libcurl.d b/docs/cmdline-opts/libcurl.d deleted file mode 100644 index 52e252f3b98..00000000000 --- a/docs/cmdline-opts/libcurl.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: libcurl -Arg: -Help: Dump libcurl equivalent code of this command line -Added: 7.16.1 -Category: curl -Example: --libcurl client.c $URL -See-also: verbose -Multi: single -Scope: global ---- -Append this option to any ordinary curl command line, and you get -libcurl-using C source code written to the file that does the equivalent of -what your command-line operation does! diff --git a/docs/cmdline-opts/libcurl.md b/docs/cmdline-opts/libcurl.md new file mode 100644 index 00000000000..eeae596d0a5 --- /dev/null +++ b/docs/cmdline-opts/libcurl.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: libcurl +Arg: +Help: Generate libcurl code for this command line +Added: 7.16.1 +Category: curl +Multi: single +Scope: global +See-also: + - verbose +Example: + - --libcurl client.c $URL +--- + +# `--libcurl` + +Append this option to any ordinary curl command line, and you get +libcurl-using C source code written to the file that does the equivalent of +what your command-line operation does! diff --git a/docs/cmdline-opts/limit-rate.d b/docs/cmdline-opts/limit-rate.d deleted file mode 100644 index 43ebf2c2336..00000000000 --- a/docs/cmdline-opts/limit-rate.d +++ /dev/null @@ -1,29 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: limit-rate -Arg: -Help: Limit transfer speed to RATE -Category: connection -Example: --limit-rate 100K $URL -Example: --limit-rate 1000 $URL -Example: --limit-rate 10M $URL -Added: 7.10 -See-also: rate speed-limit speed-time -Multi: single ---- -Specify the maximum transfer rate you want curl to use - for both downloads -and uploads. This feature is useful if you have a limited pipe and you would like -your transfer not to use your entire bandwidth. To make it slower than it -otherwise would be. - -The given speed is measured in bytes/second, unless a suffix is appended. -Appending 'k' or 'K' counts the number as kilobytes, 'm' or 'M' makes it -megabytes, while 'g' or 'G' makes it gigabytes. The suffixes (k, M, G, T, P) -are 1024 based. For example 1k is 1024. Examples: 200K, 3m and 1G. - -The rate limiting logic works on averaging the transfer speed to no more than -the set threshold over a period of multiple seconds. - -If you also use the --speed-limit option, that option takes precedence and -might cripple the rate-limiting slightly, to help keeping the speed-limit -logic working. diff --git a/docs/cmdline-opts/limit-rate.md b/docs/cmdline-opts/limit-rate.md new file mode 100644 index 00000000000..273a2ce5167 --- /dev/null +++ b/docs/cmdline-opts/limit-rate.md @@ -0,0 +1,37 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: limit-rate +Arg: +Help: Limit transfer speed to RATE +Category: connection +Added: 7.10 +Multi: single +See-also: + - rate + - speed-limit + - speed-time +Example: + - --limit-rate 100K $URL + - --limit-rate 1000 $URL + - --limit-rate 10M $URL +--- + +# `--limit-rate` + +Specify the maximum transfer rate you want curl to use - for both downloads +and uploads. This feature is useful if you have a limited pipe and you would +like your transfer not to use your entire bandwidth. To make it slower than it +otherwise would be. + +The given speed is measured in bytes/second, unless a suffix is appended. +Appending 'k' or 'K' counts the number as kilobytes, 'm' or 'M' makes it +megabytes, while 'g' or 'G' makes it gigabytes. The suffixes (k, M, G, T, P) +are 1024 based. For example 1k is 1024. Examples: 200K, 3m and 1G. + +The rate limiting logic works on averaging the transfer speed to no more than +the set threshold over a period of multiple seconds. + +If you also use the --speed-limit option, that option takes precedence and +might cripple the rate-limiting slightly, to help keeping the speed-limit +logic working. diff --git a/docs/cmdline-opts/list-only.d b/docs/cmdline-opts/list-only.d deleted file mode 100644 index dcfbf2ccc98..00000000000 --- a/docs/cmdline-opts/list-only.d +++ /dev/null @@ -1,36 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: list-only -Short: l -Protocols: FTP POP3 SFTP -Help: List only mode -Added: 4.0 -Category: ftp pop3 sftp -Example: --list-only ftp://example.com/dir/ -See-also: quote request -Multi: boolean ---- -(FTP) -When listing an FTP directory, this switch forces a name-only view. This is -especially useful if the user wants to machine-parse the contents of an FTP -directory since the normal directory view does not use a standard look or -format. When used like this, the option causes an NLST command to be sent to -the server instead of LIST. - -Note: Some FTP servers list only files in their response to NLST; they do not -include sub-directories and symbolic links. - -(SFTP) -When listing an SFTP directory, this switch forces a name-only view, one per line. -This is especially useful if the user wants to machine-parse the contents of an -SFTP directory since the normal directory view provides more information than just -file names. - -(POP3) -When retrieving a specific email from POP3, this switch forces a LIST command -to be performed instead of RETR. This is particularly useful if the user wants -to see if a specific message-id exists on the server and what size it is. - -Note: When combined with --request, this option can be used to send a UIDL -command instead, so the user may use the email's unique identifier rather than -its message-id to make the request. diff --git a/docs/cmdline-opts/list-only.md b/docs/cmdline-opts/list-only.md new file mode 100644 index 00000000000..5d8dde65c2d --- /dev/null +++ b/docs/cmdline-opts/list-only.md @@ -0,0 +1,40 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: list-only +Short: l +Protocols: FTP POP3 SFTP +Help: List only mode +Added: 4.0 +Category: ftp pop3 sftp +Multi: boolean +See-also: + - quote + - request +Example: + - --list-only ftp://example.com/dir/ +--- + +# `--list-only` + +When listing an FTP directory, force a name-only view. Maybe particularly +useful if the user wants to machine-parse the contents of an FTP directory +since the normal directory view does not use a standard look or format. When +used like this, the option causes an NLST command to be sent to the server +instead of LIST. + +Note: Some FTP servers list only files in their response to NLST; they do not +include sub-directories and symbolic links. + +When listing an SFTP directory, this switch forces a name-only view, one per +line. This is especially useful if the user wants to machine-parse the +contents of an SFTP directory since the normal directory view provides more +information than just filenames. + +When retrieving a specific email from POP3, this switch forces a LIST command +to be performed instead of RETR. This is particularly useful if the user wants +to see if a specific message-id exists on the server and what size it is. + +Note: When combined with --request, this option can be used to send a UIDL +command instead, so the user may use the email's unique identifier rather than +its message-id to make the request. diff --git a/docs/cmdline-opts/local-port.d b/docs/cmdline-opts/local-port.d deleted file mode 100644 index d6949b7ee3f..00000000000 --- a/docs/cmdline-opts/local-port.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: local-port -Arg: -Help: Force use of RANGE for local port numbers -Added: 7.15.2 -Category: connection -Example: --local-port 1000-3000 $URL -See-also: globoff -Multi: single ---- -Set a preferred single number or range (FROM-TO) of local port numbers to use -for the connection(s). Note that port numbers by nature are a scarce resource -so setting this range to something too narrow might cause unnecessary -connection setup failures. diff --git a/docs/cmdline-opts/local-port.md b/docs/cmdline-opts/local-port.md new file mode 100644 index 00000000000..b8c0d3fda1b --- /dev/null +++ b/docs/cmdline-opts/local-port.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: local-port +Arg: +Help: Use a local port number within RANGE +Added: 7.15.2 +Category: connection +Multi: single +See-also: + - globoff +Example: + - --local-port 1000-3000 $URL +--- + +# `--local-port` + +Set a preferred single number or range (FROM-TO) of local port numbers to use +for the connection(s). Note that port numbers by nature are a scarce resource +so setting this range to something too narrow might cause unnecessary +connection setup failures. diff --git a/docs/cmdline-opts/location-trusted.d b/docs/cmdline-opts/location-trusted.d deleted file mode 100644 index 9f83d0ef0ec..00000000000 --- a/docs/cmdline-opts/location-trusted.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: location-trusted -Help: Like --location, and send auth to other hosts -Protocols: HTTP -See-also: user -Category: http auth -Example: --location-trusted -u user:password $URL -Added: 7.10.4 -Multi: boolean ---- -Like --location, but allows sending the name + password to all hosts that the -site may redirect to. This may or may not introduce a security breach if the -site redirects you to a site to which you send your authentication info -(which is plaintext in the case of HTTP Basic authentication). diff --git a/docs/cmdline-opts/location-trusted.md b/docs/cmdline-opts/location-trusted.md new file mode 100644 index 00000000000..4f4e7def57a --- /dev/null +++ b/docs/cmdline-opts/location-trusted.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: location-trusted +Help: Like --location, but send auth to other hosts +Protocols: HTTP +Category: http auth +Added: 7.10.4 +Multi: boolean +See-also: + - user +Example: + - --location-trusted -u user:password $URL +--- + +# `--location-trusted` + +Like --location, but allows sending the name + password to all hosts that the +site may redirect to. This may or may not introduce a security breach if the +site redirects you to a site to which you send your authentication info (which +is clear-text in the case of HTTP Basic authentication). diff --git a/docs/cmdline-opts/location.d b/docs/cmdline-opts/location.d deleted file mode 100644 index 9a99a051336..00000000000 --- a/docs/cmdline-opts/location.d +++ /dev/null @@ -1,33 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: location -Short: L -Help: Follow redirects -Protocols: HTTP -Category: http -Example: -L $URL -Added: 4.9 -See-also: resolve alt-svc -Multi: boolean ---- -If the server reports that the requested page has moved to a different -location (indicated with a Location: header and a 3XX response code), this -option makes curl redo the request on the new place. If used together with ---include or --head, headers from all requested pages are shown. - -When authentication is used, curl only sends its credentials to the initial -host. If a redirect takes curl to a different host, it does not get the -user+password pass on. See also --location-trusted on how to change this. - -Limit the amount of redirects to follow by using the --max-redirs option. - -When curl follows a redirect and if the request is a POST, it sends the -following request with a GET if the HTTP response was 301, 302, or 303. If the -response code was any other 3xx code, curl resends the following request using -the same unmodified method. - -You can tell curl to not change POST requests to GET after a 30x response by -using the dedicated options for that: --post301, --post302 and --post303. - -The method set with --request overrides the method curl would otherwise select -to use. diff --git a/docs/cmdline-opts/location.md b/docs/cmdline-opts/location.md new file mode 100644 index 00000000000..62e3d470ae1 --- /dev/null +++ b/docs/cmdline-opts/location.md @@ -0,0 +1,40 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: location +Short: L +Help: Follow redirects +Protocols: HTTP +Category: http +Added: 4.9 +Multi: boolean +See-also: + - resolve + - alt-svc +Example: + - -L $URL +--- + +# `--location` + +If the server reports that the requested page has moved to a different +location (indicated with a Location: header and a 3XX response code), this +option makes curl redo the request on the new place. If used together with +--include or --head, headers from all requested pages are shown. + +When authentication is used, curl only sends its credentials to the initial +host. If a redirect takes curl to a different host, it does not get the +user+password pass on. See also --location-trusted on how to change this. + +Limit the amount of redirects to follow by using the --max-redirs option. + +When curl follows a redirect and if the request is a POST, it sends the +following request with a GET if the HTTP response was 301, 302, or 303. If the +response code was any other 3xx code, curl resends the following request using +the same unmodified method. + +You can tell curl to not change POST requests to GET after a 30x response by +using the dedicated options for that: --post301, --post302 and --post303. + +The method set with --request overrides the method curl would otherwise select +to use. diff --git a/docs/cmdline-opts/login-options.d b/docs/cmdline-opts/login-options.d deleted file mode 100644 index c67be90f872..00000000000 --- a/docs/cmdline-opts/login-options.d +++ /dev/null @@ -1,25 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: login-options -Arg: -Protocols: IMAP LDAP POP3 SMTP -Help: Server login options -Added: 7.34.0 -Category: imap pop3 smtp auth -Example: --login-options 'AUTH=*' imap://example.com -See-also: user -Multi: single ---- -Specify the login options to use during server authentication. - -You can use login options to specify protocol specific options that may be -used during authentication. At present only IMAP, POP3 and SMTP support login -options. For more information about login options please see RFC 2384, -RFC 5092 and the IETF draft -https://datatracker.ietf.org/doc/html/draft-earhart-url-smtp-00. - -Since 8.2.0, IMAP supports the login option "AUTH=+LOGIN". With this option, -curl uses the plain (not SASL) LOGIN IMAP command even if the server -advertises SASL authentication. Care should be taken in using this option, as -it sends your password over the network in plain text. This does not work if -the IMAP server disables the plain LOGIN (e.g. to prevent password snooping). diff --git a/docs/cmdline-opts/login-options.md b/docs/cmdline-opts/login-options.md new file mode 100644 index 00000000000..fdeeda52a3a --- /dev/null +++ b/docs/cmdline-opts/login-options.md @@ -0,0 +1,32 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: login-options +Arg: +Protocols: IMAP LDAP POP3 SMTP +Help: Server login options +Added: 7.34.0 +Category: imap pop3 smtp auth +Multi: single +See-also: + - user +Example: + - --login-options 'AUTH=*' imap://example.com +--- + +# `--login-options` + +Specify the login options to use during server authentication. + +You can use login options to specify protocol specific options that may be +used during authentication. At present only IMAP, POP3 and SMTP support login +options. For more information about login options please see RFC 2384, +RFC 5092 and the IETF draft +https://datatracker.ietf.org/doc/html/draft-earhart-url-smtp-00 + +Since 8.2.0, IMAP supports the login option `AUTH=+LOGIN`. With this option, +curl uses the plain (not SASL) `LOGIN IMAP` command even if the server +advertises SASL authentication. Care should be taken in using this option, as +it sends your password over the network in plain text. This does not work if +the IMAP server disables the plain `LOGIN` (e.g. to prevent password +snooping). diff --git a/docs/cmdline-opts/mail-auth.d b/docs/cmdline-opts/mail-auth.d deleted file mode 100644 index 45ceebd99ff..00000000000 --- a/docs/cmdline-opts/mail-auth.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: mail-auth -Arg:
-Protocols: SMTP -Help: Originator address of the original email -Added: 7.25.0 -See-also: mail-rcpt mail-from -Category: smtp -Example: --mail-auth user@example.come -T mail smtp://example.com/ -Multi: single ---- -Specify a single address. This is used to specify the authentication address -(identity) of a submitted message that is being relayed to another server. diff --git a/docs/cmdline-opts/mail-auth.md b/docs/cmdline-opts/mail-auth.md new file mode 100644 index 00000000000..3692c159661 --- /dev/null +++ b/docs/cmdline-opts/mail-auth.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: mail-auth +Arg:
+Protocols: SMTP +Help: Originator address of the original email +Added: 7.25.0 +Category: smtp +Multi: single +See-also: + - mail-rcpt + - mail-from +Example: + - --mail-auth user@example.come -T mail smtp://example.com/ +--- + +# `--mail-auth` + +Specify a single address. This is used to specify the authentication address +(identity) of a submitted message that is being relayed to another server. diff --git a/docs/cmdline-opts/mail-from.d b/docs/cmdline-opts/mail-from.d deleted file mode 100644 index 0729e841a96..00000000000 --- a/docs/cmdline-opts/mail-from.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: mail-from -Arg:
-Help: Mail from this address -Protocols: SMTP -Added: 7.20.0 -See-also: mail-rcpt mail-auth -Category: smtp -Example: --mail-from user@example.com -T mail smtp://example.com/ -Multi: single ---- -Specify a single address that the given mail should get sent from. diff --git a/docs/cmdline-opts/mail-from.md b/docs/cmdline-opts/mail-from.md new file mode 100644 index 00000000000..96b062501be --- /dev/null +++ b/docs/cmdline-opts/mail-from.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: mail-from +Arg:
+Help: Mail from this address +Protocols: SMTP +Added: 7.20.0 +Category: smtp +Multi: single +See-also: + - mail-rcpt + - mail-auth +Example: + - --mail-from user@example.com -T mail smtp://example.com/ +--- + +# `--mail-from` + +Specify a single address that the given mail should get sent from. diff --git a/docs/cmdline-opts/mail-rcpt-allowfails.d b/docs/cmdline-opts/mail-rcpt-allowfails.d deleted file mode 100644 index d2a5f39d3b3..00000000000 --- a/docs/cmdline-opts/mail-rcpt-allowfails.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: mail-rcpt-allowfails -Help: Allow RCPT TO command to fail for some recipients -Protocols: SMTP -Added: 7.69.0 -Category: smtp -Example: --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com -See-also: mail-rcpt -Multi: boolean ---- -When sending data to multiple recipients, by default curl aborts SMTP -conversation if at least one of the recipients causes RCPT TO command to -return an error. - -The default behavior can be changed by passing --mail-rcpt-allowfails -command-line option which makes curl ignore errors and proceed with the -remaining valid recipients. - -If all recipients trigger RCPT TO failures and this flag is specified, curl -still aborts the SMTP conversation and returns the error received from to the -last RCPT TO command. diff --git a/docs/cmdline-opts/mail-rcpt-allowfails.md b/docs/cmdline-opts/mail-rcpt-allowfails.md new file mode 100644 index 00000000000..a82948bbc4f --- /dev/null +++ b/docs/cmdline-opts/mail-rcpt-allowfails.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: mail-rcpt-allowfails +Help: Allow RCPT TO command to fail +Protocols: SMTP +Added: 7.69.0 +Category: smtp +Multi: boolean +See-also: + - mail-rcpt +Example: + - --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com +--- + +# `--mail-rcpt-allowfails` + +When sending data to multiple recipients, by default curl aborts SMTP +conversation if at least one of the recipients causes RCPT TO command to +return an error. + +The default behavior can be changed by passing --mail-rcpt-allowfails +command-line option which makes curl ignore errors and proceed with the +remaining valid recipients. + +If all recipients trigger RCPT TO failures and this flag is specified, curl +still aborts the SMTP conversation and returns the error received from to the +last RCPT TO command. diff --git a/docs/cmdline-opts/mail-rcpt.d b/docs/cmdline-opts/mail-rcpt.d deleted file mode 100644 index a4b16c4f7b0..00000000000 --- a/docs/cmdline-opts/mail-rcpt.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: mail-rcpt -Arg:
-Help: Mail to this address -Protocols: SMTP -Added: 7.20.0 -Category: smtp -Example: --mail-rcpt user@example.net smtp://example.com -See-also: mail-rcpt-allowfails -Multi: append ---- -Specify a single email address, user name or mailing list name. Repeat this -option several times to send to multiple recipients. - -When performing an address verification (**VRFY** command), the recipient should be -specified as the user name or user name and domain (as per Section 3.5 of -RFC 5321). (Added in 7.34.0) - -When performing a mailing list expand (EXPN command), the recipient should be -specified using the mailing list name, such as "Friends" or "London-Office". -(Added in 7.34.0) diff --git a/docs/cmdline-opts/mail-rcpt.md b/docs/cmdline-opts/mail-rcpt.md new file mode 100644 index 00000000000..bd787c2fa08 --- /dev/null +++ b/docs/cmdline-opts/mail-rcpt.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: mail-rcpt +Arg:
+Help: Mail to this address +Protocols: SMTP +Added: 7.20.0 +Category: smtp +Multi: append +See-also: + - mail-rcpt-allowfails +Example: + - --mail-rcpt user@example.net smtp://example.com +--- + +# `--mail-rcpt` + +Specify a single email address, username or mailing list name. Repeat this +option several times to send to multiple recipients. + +When performing an address verification (**VRFY** command), the recipient +should be specified as the username or username and domain (as per Section 3.5 +of RFC 5321). (Added in 7.34.0) + +When performing a mailing list expand (EXPN command), the recipient should be +specified using the mailing list name, such as "Friends" or "London-Office". +(Added in 7.34.0) diff --git a/docs/cmdline-opts/mainpage.idx b/docs/cmdline-opts/mainpage.idx new file mode 100644 index 00000000000..8496ee46dc5 --- /dev/null +++ b/docs/cmdline-opts/mainpage.idx @@ -0,0 +1,43 @@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| +# +# Copyright (C) Daniel Stenberg, , et al. +# +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at https://curl.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +# SPDX-License-Identifier: curl +# +########################################################################### +_NAME.md +_SYNOPSIS.md +_DESCRIPTION.md +_URL.md +_GLOBBING.md +_VARIABLES.md +_OUTPUT.md +_PROTOCOLS.md +_PROGRESS.md +_VERSION.md +_OPTIONS.md +%options +_FILES.md +_ENVIRONMENT.md +_PROXYPREFIX.md +_EXITCODES.md +_BUGS.md +_AUTHORS.md +_WWW.md +_SEEALSO.md diff --git a/docs/cmdline-opts/manual.d b/docs/cmdline-opts/manual.d deleted file mode 100644 index 9ee4d075ad5..00000000000 --- a/docs/cmdline-opts/manual.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: manual -Short: M -Help: Display the full manual -Category: curl -Example: --manual -Added: 5.2 -See-also: verbose libcurl trace -Multi: custom ---- -Manual. Display the huge help text. diff --git a/docs/cmdline-opts/manual.md b/docs/cmdline-opts/manual.md new file mode 100644 index 00000000000..bf44f3b8ad4 --- /dev/null +++ b/docs/cmdline-opts/manual.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: manual +Short: M +Help: Display the full manual +Category: curl +Added: 5.2 +Multi: custom +See-also: + - verbose + - libcurl + - trace +Example: + - --manual +--- + +# `--manual` + +Manual. Display the huge help text. diff --git a/docs/cmdline-opts/max-filesize.d b/docs/cmdline-opts/max-filesize.d deleted file mode 100644 index 7541a27127d..00000000000 --- a/docs/cmdline-opts/max-filesize.d +++ /dev/null @@ -1,26 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: max-filesize -Arg: -Help: Maximum file size to download -Protocols: FTP HTTP MQTT -See-also: limit-rate -Category: connection -Example: --max-filesize 100K $URL -Added: 7.10.8 -Multi: single ---- -Specify the maximum size (in bytes) of a file to download. If the file -requested is larger than this value, the transfer does not start and curl -returns with exit code 63. - -A size modifier may be used. For example, Appending 'k' or 'K' counts the -number as kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it -gigabytes. Examples: 200K, 3m and 1G. (Added in 7.58.0) - -**NOTE**: before curl 8.4.0, when the file size is not known prior to -download, for such files this option has no effect even if the file transfer -ends up being larger than this given limit. - -Starting with curl 8.4.0, this option aborts the transfer if it reaches the -threshold during transfer. diff --git a/docs/cmdline-opts/max-filesize.md b/docs/cmdline-opts/max-filesize.md new file mode 100644 index 00000000000..998359cf740 --- /dev/null +++ b/docs/cmdline-opts/max-filesize.md @@ -0,0 +1,32 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: max-filesize +Arg: +Help: Maximum file size to download +Protocols: FTP HTTP MQTT +Category: connection +Added: 7.10.8 +Multi: single +See-also: + - limit-rate +Example: + - --max-filesize 100K $URL +--- + +# `--max-filesize` + +Specify the maximum size (in bytes) of a file to download. If the file +requested is larger than this value, the transfer does not start and curl +returns with exit code 63. + +A size modifier may be used. For example, Appending 'k' or 'K' counts the +number as kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it +gigabytes. Examples: 200K, 3m and 1G. (Added in 7.58.0) + +**NOTE**: before curl 8.4.0, when the file size is not known prior to +download, for such files this option has no effect even if the file transfer +ends up being larger than this given limit. + +Starting with curl 8.4.0, this option aborts the transfer if it reaches the +threshold during transfer. diff --git a/docs/cmdline-opts/max-redirs.d b/docs/cmdline-opts/max-redirs.d deleted file mode 100644 index 31ce98ea5eb..00000000000 --- a/docs/cmdline-opts/max-redirs.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: max-redirs -Arg: -Help: Maximum number of redirects allowed -Protocols: HTTP -Category: http -Example: --max-redirs 3 --location $URL -Added: 7.5 -See-also: location -Multi: single ---- -Set maximum number of redirections to follow. When --location is used, to -prevent curl from following too many redirects, by default, the limit is -set to 50 redirects. Set this option to -1 to make it unlimited. diff --git a/docs/cmdline-opts/max-redirs.md b/docs/cmdline-opts/max-redirs.md new file mode 100644 index 00000000000..52b0c5721fb --- /dev/null +++ b/docs/cmdline-opts/max-redirs.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: max-redirs +Arg: +Help: Maximum number of redirects allowed +Protocols: HTTP +Category: http +Added: 7.5 +Multi: single +See-also: + - location +Example: + - --max-redirs 3 --location $URL +--- + +# `--max-redirs` + +Set maximum number of redirections to follow. When --location is used, to +prevent curl from following too many redirects, by default, the limit is +set to 50 redirects. Set this option to -1 to make it unlimited. diff --git a/docs/cmdline-opts/max-time.d b/docs/cmdline-opts/max-time.d deleted file mode 100644 index 0d5747b26ff..00000000000 --- a/docs/cmdline-opts/max-time.d +++ /dev/null @@ -1,23 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: max-time -Short: m -Arg: -Help: Maximum time allowed for transfer -See-also: connect-timeout retry-max-time -Category: connection -Example: --max-time 10 $URL -Example: --max-time 2.92 $URL -Added: 4.0 -Multi: single ---- -Maximum time in seconds that you allow each transfer to take. This is useful -for preventing your batch jobs from hanging for hours due to slow networks or -links going down. This option accepts decimal values (added in 7.32.0). - -If you enable retrying the transfer (--retry) then the maximum time counter is -reset each time the transfer is retried. You can use --retry-max-time to limit -the retry time. - -The decimal value needs to provided using a dot (.) as decimal separator - not -the local version even if it might be using another separator. diff --git a/docs/cmdline-opts/max-time.md b/docs/cmdline-opts/max-time.md new file mode 100644 index 00000000000..9102442aa9d --- /dev/null +++ b/docs/cmdline-opts/max-time.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: max-time +Short: m +Arg: +Help: Maximum time allowed for transfer +Category: connection +Added: 4.0 +Multi: single +See-also: + - connect-timeout + - retry-max-time +Example: + - --max-time 10 $URL + - --max-time 2.92 $URL +--- + +# `--max-time` + +Set maximum time in seconds that you allow each transfer to take. Prevents +your batch jobs from hanging for hours due to slow networks or links going +down. This option accepts decimal values (added in 7.32.0). + +If you enable retrying the transfer (--retry) then the maximum time counter is +reset each time the transfer is retried. You can use --retry-max-time to limit +the retry time. + +The decimal value needs to provided using a dot (.) as decimal separator - not +the local version even if it might be using another separator. diff --git a/docs/cmdline-opts/metalink.d b/docs/cmdline-opts/metalink.d deleted file mode 100644 index 88f012176e3..00000000000 --- a/docs/cmdline-opts/metalink.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: metalink -Help: Process given URLs as metalink XML file -Added: 7.27.0 -Category: misc -Example: --metalink file $URL -See-also: parallel -Multi: single ---- -This option was previously used to specify a Metalink resource. Metalink -support is disabled in curl for security reasons (added in 7.78.0). diff --git a/docs/cmdline-opts/metalink.md b/docs/cmdline-opts/metalink.md new file mode 100644 index 00000000000..0c39b46edac --- /dev/null +++ b/docs/cmdline-opts/metalink.md @@ -0,0 +1,18 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: metalink +Help: Process given URLs as metalink XML file +Added: 7.27.0 +Category: misc +Multi: single +See-also: + - parallel +Example: + - --metalink file $URL +--- + +# `--metalink` + +This option was previously used to specify a Metalink resource. Metalink +support is disabled in curl for security reasons (added in 7.78.0). diff --git a/docs/cmdline-opts/negotiate.d b/docs/cmdline-opts/negotiate.d deleted file mode 100644 index f1dd34dbafe..00000000000 --- a/docs/cmdline-opts/negotiate.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: negotiate -Help: Use HTTP Negotiate (SPNEGO) authentication -Protocols: HTTP -See-also: basic ntlm anyauth proxy-negotiate -Category: auth http -Example: --negotiate -u : $URL -Added: 7.10.6 -Multi: mutex ---- -Enables Negotiate (SPNEGO) authentication. - -This option requires a library built with GSS-API or SSPI support. Use ---version to see if your curl supports GSS-API/SSPI or SPNEGO. - -When using this option, you must also provide a fake --user option to activate -the authentication code properly. Sending a '-u :' is enough as the user name -and password from the --user option are not actually used. diff --git a/docs/cmdline-opts/negotiate.md b/docs/cmdline-opts/negotiate.md new file mode 100644 index 00000000000..bba3f6a08cb --- /dev/null +++ b/docs/cmdline-opts/negotiate.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: negotiate +Help: Use HTTP Negotiate (SPNEGO) authentication +Protocols: HTTP +Category: auth http +Added: 7.10.6 +Multi: mutex +See-also: + - basic + - ntlm + - anyauth + - proxy-negotiate +Example: + - --negotiate -u : $URL +--- + +# `--negotiate` + +Enable Negotiate (SPNEGO) authentication. + +This option requires a library built with GSS-API or SSPI support. Use +--version to see if your curl supports GSS-API/SSPI or SPNEGO. + +When using this option, you must also provide a fake --user option to activate +the authentication code properly. Sending a '-u :' is enough as the username +and password from the --user option are not actually used. diff --git a/docs/cmdline-opts/netrc-file.d b/docs/cmdline-opts/netrc-file.d deleted file mode 100644 index 7b1a214da28..00000000000 --- a/docs/cmdline-opts/netrc-file.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: netrc-file -Help: Specify FILE for netrc -Arg: -Added: 7.21.5 -Mutexed: netrc -Category: curl -Example: --netrc-file netrc $URL -See-also: netrc user config -Multi: single ---- -This option is similar to --netrc, except that you provide the path (absolute -or relative) to the netrc file that curl should use. You can only specify one -netrc file per invocation. - -It abides by --netrc-optional if specified. diff --git a/docs/cmdline-opts/netrc-file.md b/docs/cmdline-opts/netrc-file.md new file mode 100644 index 00000000000..841f23c48d9 --- /dev/null +++ b/docs/cmdline-opts/netrc-file.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: netrc-file +Help: Specify FILE for netrc +Arg: +Added: 7.21.5 +Mutexed: netrc +Category: curl +Multi: single +See-also: + - netrc + - user + - config +Example: + - --netrc-file netrc $URL +--- + +# `--netrc-file` + +Set the netrc file to use. Similar to --netrc, except that you also provide +the path (absolute or relative). + +It abides by --netrc-optional if specified. diff --git a/docs/cmdline-opts/netrc-optional.d b/docs/cmdline-opts/netrc-optional.d deleted file mode 100644 index a7759640f95..00000000000 --- a/docs/cmdline-opts/netrc-optional.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: netrc-optional -Help: Use either .netrc or URL -Mutexed: netrc -See-also: netrc-file -Category: curl -Example: --netrc-optional $URL -Added: 7.9.8 -Multi: boolean ---- -Similar to --netrc, but this option makes the .netrc usage **optional** -and not mandatory as the --netrc option does. diff --git a/docs/cmdline-opts/netrc-optional.md b/docs/cmdline-opts/netrc-optional.md new file mode 100644 index 00000000000..6aa76954ae4 --- /dev/null +++ b/docs/cmdline-opts/netrc-optional.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: netrc-optional +Help: Use either .netrc or URL +Mutexed: netrc +Category: curl +Added: 7.9.8 +Multi: boolean +See-also: + - netrc-file +Example: + - --netrc-optional $URL +--- + +# `--netrc-optional` + +Similar to --netrc, but this option makes the .netrc usage **optional** +and not mandatory as the --netrc option does. diff --git a/docs/cmdline-opts/netrc.d b/docs/cmdline-opts/netrc.d deleted file mode 100644 index f0ec75f3784..00000000000 --- a/docs/cmdline-opts/netrc.d +++ /dev/null @@ -1,30 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: netrc -Short: n -Help: Must read .netrc for user name and password -Category: curl -Example: --netrc $URL -Added: 4.6 -See-also: netrc-file config user -Mutexed: netrc-file netrc-optional -Multi: boolean ---- -Makes curl scan the *.netrc* file in the user's home directory for login name -and password. This is typically used for FTP on Unix. If used with HTTP, curl -enables user authentication. See *netrc(5)* and *ftp(1)* for details on the -file format. Curl does not complain if that file does not have the right -permissions (it should be neither world- nor group-readable). The environment -variable "HOME" is used to find the home directory. - -On Windows two filenames in the home directory are checked: *.netrc* and -*_netrc*, preferring the former. Older versions on Windows checked for *_netrc* -only. - -A quick and simple example of how to setup a *.netrc* to allow curl to FTP to -the machine host.domain.com with user name 'myself' and password 'secret' -could look similar to: - - machine host.domain.com - login myself - password secret diff --git a/docs/cmdline-opts/netrc.md b/docs/cmdline-opts/netrc.md new file mode 100644 index 00000000000..4c07f9b75ee --- /dev/null +++ b/docs/cmdline-opts/netrc.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: netrc +Short: n +Help: Must read .netrc for username and password +Category: curl +Added: 4.6 +Mutexed: netrc-file netrc-optional +Multi: boolean +See-also: + - netrc-file + - config + - user +Example: + - --netrc $URL +--- + +# `--netrc` + +Make curl scan the *.netrc* file in the user's home directory for login name +and password. This is typically used for FTP on Unix. If used with HTTP, curl +enables user authentication. See *netrc(5)* and *ftp(1)* for details on the +file format. Curl does not complain if that file does not have the right +permissions (it should be neither world- nor group-readable). The environment +variable "HOME" is used to find the home directory. + +On Windows two filenames in the home directory are checked: *.netrc* and +*_netrc*, preferring the former. Older versions on Windows checked for *_netrc* +only. + +A quick and simple example of how to setup a *.netrc* to allow curl to FTP to +the machine host.domain.com with username 'myself' and password 'secret' could +look similar to: + + machine host.domain.com + login myself + password secret diff --git a/docs/cmdline-opts/next.d b/docs/cmdline-opts/next.d deleted file mode 100644 index 93c9c45b38a..00000000000 --- a/docs/cmdline-opts/next.d +++ /dev/null @@ -1,27 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: : -Long: next -Tags: -Protocols: -Added: 7.36.0 -Magic: divider -Help: Make next URL use its separate set of options -Category: curl -Example: $URL --next -d postthis www2.example.com -Example: -I $URL --next https://example.net/ -See-also: parallel config -Multi: append ---- -Tells curl to use a separate operation for the following URL and associated -options. This allows you to send several URL requests, each with their own -specific options, for example, such as different user names or custom requests -for each. - ---next resets all local options and only global ones have their values survive -over to the operation following the --next instruction. Global options include ---verbose, --trace, --trace-ascii and --fail-early. - -For example, you can do both a GET and a POST in a single command line: - - curl www1.example.com --next -d postthis www2.example.com diff --git a/docs/cmdline-opts/next.md b/docs/cmdline-opts/next.md new file mode 100644 index 00000000000..2cf65c65a8f --- /dev/null +++ b/docs/cmdline-opts/next.md @@ -0,0 +1,33 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: : +Long: next +Tags: +Protocols: +Added: 7.36.0 +Magic: divider +Help: Make next URL use its separate set of options +Category: curl +Multi: append +See-also: + - parallel + - config +Example: + - $URL --next -d postthis www2.example.com + - -I $URL --next https://example.net/ +--- + +# `--next` + +Use a separate operation for the following URL and associated options. This +allows you to send several URL requests, each with their own specific options, +for example, such as different usernames or custom requests for each. + +--next resets all local options and only global ones have their values survive +over to the operation following the --next instruction. Global options include +--verbose, --trace, --trace-ascii and --fail-early. + +For example, you can do both a GET and a POST in a single command line: + + curl www1.example.com --next -d postthis www2.example.com diff --git a/docs/cmdline-opts/no-alpn.d b/docs/cmdline-opts/no-alpn.d deleted file mode 100644 index 102f2990e5f..00000000000 --- a/docs/cmdline-opts/no-alpn.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: no-alpn -Tags: HTTP/2 -Protocols: HTTPS -Added: 7.36.0 -See-also: no-npn http2 -Requires: TLS -Help: Disable the ALPN TLS extension -Category: tls http -Example: --no-alpn $URL -Multi: boolean ---- -Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built -with an SSL library that supports ALPN. ALPN is used by a libcurl that supports -HTTP/2 to negotiate HTTP/2 support with the server during https sessions. - -Note that this is the negated option name documented. You can use --alpn to -enable ALPN. diff --git a/docs/cmdline-opts/no-alpn.md b/docs/cmdline-opts/no-alpn.md new file mode 100644 index 00000000000..47529487872 --- /dev/null +++ b/docs/cmdline-opts/no-alpn.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: no-alpn +Tags: HTTP/2 +Protocols: HTTPS +Added: 7.36.0 +Requires: TLS +Help: Disable the ALPN TLS extension +Category: tls http +Multi: boolean +See-also: + - no-npn + - http2 +Example: + - --no-alpn $URL +--- + +# `--no-alpn` + +Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built +with an SSL library that supports ALPN. ALPN is used by a libcurl that supports +HTTP/2 to negotiate HTTP/2 support with the server during https sessions. + +Note that this is the negated option name documented. You can use --alpn to +enable ALPN. diff --git a/docs/cmdline-opts/no-buffer.d b/docs/cmdline-opts/no-buffer.d deleted file mode 100644 index 33f6fbc5bfd..00000000000 --- a/docs/cmdline-opts/no-buffer.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: no-buffer -Short: N -Help: Disable buffering of the output stream -Category: curl -Example: --no-buffer $URL -Added: 6.5 -See-also: progress-bar -Multi: boolean ---- -Disables the buffering of the output stream. In normal work situations, curl -uses a standard buffered output stream that has the effect that it outputs the -data in chunks, not necessarily exactly when the data arrives. Using this -option disables that buffering. - -Note that this is the negated option name documented. You can use --buffer to -enable buffering again. diff --git a/docs/cmdline-opts/no-buffer.md b/docs/cmdline-opts/no-buffer.md new file mode 100644 index 00000000000..41328b165ed --- /dev/null +++ b/docs/cmdline-opts/no-buffer.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: no-buffer +Short: N +Help: Disable buffering of the output stream +Category: curl +Added: 6.5 +Multi: boolean +See-also: + - progress-bar +Example: + - --no-buffer $URL +--- + +# `--no-buffer` + +Disables the buffering of the output stream. In normal work situations, curl +uses a standard buffered output stream that has the effect that it outputs the +data in chunks, not necessarily exactly when the data arrives. Using this +option disables that buffering. + +Note that this is the negated option name documented. You can use --buffer to +enable buffering again. diff --git a/docs/cmdline-opts/no-clobber.d b/docs/cmdline-opts/no-clobber.d deleted file mode 100644 index 9325558da6b..00000000000 --- a/docs/cmdline-opts/no-clobber.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: no-clobber -Help: Do not overwrite files that already exist -Category: curl output -Added: 7.83.0 -See-also: output remote-name -Example: --no-clobber --output local/dir/file $URL -Multi: boolean ---- -When used in conjunction with the --output, --remote-header-name, ---remote-name, or --remote-name-all options, curl avoids overwriting files -that already exist. Instead, a dot and a number gets appended to the name of -the file that would be created, up to filename.100 after which it does not -create any file. - -Note that this is the negated option name documented. You can thus use ---clobber to enforce the clobbering, even if --remote-header-name is -specified. diff --git a/docs/cmdline-opts/no-clobber.md b/docs/cmdline-opts/no-clobber.md new file mode 100644 index 00000000000..58646224c9f --- /dev/null +++ b/docs/cmdline-opts/no-clobber.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: no-clobber +Help: Do not overwrite files that already exist +Category: curl output +Added: 7.83.0 +Multi: boolean +See-also: + - output + - remote-name +Example: + - --no-clobber --output local/dir/file $URL +--- + +# `--no-clobber` + +When used in conjunction with the --output, --remote-header-name, +--remote-name, or --remote-name-all options, curl avoids overwriting files +that already exist. Instead, a dot and a number gets appended to the name of +the file that would be created, up to filename.100 after which it does not +create any file. + +Note that this is the negated option name documented. You can thus use +--clobber to enforce the clobbering, even if --remote-header-name is +specified. diff --git a/docs/cmdline-opts/no-keepalive.d b/docs/cmdline-opts/no-keepalive.d deleted file mode 100644 index 0aeaef8d535..00000000000 --- a/docs/cmdline-opts/no-keepalive.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: no-keepalive -Help: Disable TCP keepalive on the connection -Category: connection -Example: --no-keepalive $URL -Added: 7.18.0 -See-also: keepalive-time -Multi: boolean ---- -Disables the use of keepalive messages on the TCP connection. curl otherwise -enables them by default. - -Note that this is the negated option name documented. You can thus use ---keepalive to enforce keepalive. diff --git a/docs/cmdline-opts/no-keepalive.md b/docs/cmdline-opts/no-keepalive.md new file mode 100644 index 00000000000..1829e8c4e44 --- /dev/null +++ b/docs/cmdline-opts/no-keepalive.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: no-keepalive +Help: Disable TCP keepalive on the connection +Category: connection +Added: 7.18.0 +Multi: boolean +See-also: + - keepalive-time +Example: + - --no-keepalive $URL +--- + +# `--no-keepalive` + +Disables the use of keepalive messages on the TCP connection. curl otherwise +enables them by default. + +Note that this is the negated option name documented. You can thus use +--keepalive to enforce keepalive. diff --git a/docs/cmdline-opts/no-npn.d b/docs/cmdline-opts/no-npn.d deleted file mode 100644 index cd0e5e2af50..00000000000 --- a/docs/cmdline-opts/no-npn.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: no-npn -Tags: Versions HTTP/2 -Protocols: HTTPS -Added: 7.36.0 -Mutexed: -See-also: no-alpn http2 -Requires: TLS -Help: Disable the NPN TLS extension -Category: tls http -Example: --no-npn $URL -Multi: boolean ---- -curl never uses NPN, this option has no effect (added in 7.86.0). - -Disable the NPN TLS extension. NPN is enabled by default if libcurl was built -with an SSL library that supports NPN. NPN is used by a libcurl that supports -HTTP/2 to negotiate HTTP/2 support with the server during https sessions. diff --git a/docs/cmdline-opts/no-npn.md b/docs/cmdline-opts/no-npn.md new file mode 100644 index 00000000000..d8ad6a251f7 --- /dev/null +++ b/docs/cmdline-opts/no-npn.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: no-npn +Tags: Versions HTTP/2 +Protocols: HTTPS +Added: 7.36.0 +Mutexed: +Requires: TLS +Help: Disable the NPN TLS extension +Category: tls http +Multi: boolean +See-also: + - no-alpn + - http2 +Example: + - --no-npn $URL +--- + +# `--no-npn` + +curl never uses NPN, this option has no effect (added in 7.86.0). + +Disable the NPN TLS extension. NPN is enabled by default if libcurl was built +with an SSL library that supports NPN. NPN is used by a libcurl that supports +HTTP/2 to negotiate HTTP/2 support with the server during https sessions. diff --git a/docs/cmdline-opts/no-progress-meter.d b/docs/cmdline-opts/no-progress-meter.d deleted file mode 100644 index 820557d9d5e..00000000000 --- a/docs/cmdline-opts/no-progress-meter.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: no-progress-meter -Help: Do not show the progress meter -See-also: verbose silent -Added: 7.67.0 -Category: verbose -Example: --no-progress-meter -o store $URL -Multi: boolean ---- -Option to switch off the progress meter output without muting or otherwise -affecting warning and informational messages like --silent does. - -Note that this is the negated option name documented. You can thus use ---progress-meter to enable the progress meter again. diff --git a/docs/cmdline-opts/no-progress-meter.md b/docs/cmdline-opts/no-progress-meter.md new file mode 100644 index 00000000000..72ec993762c --- /dev/null +++ b/docs/cmdline-opts/no-progress-meter.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: no-progress-meter +Help: Do not show the progress meter +Added: 7.67.0 +Category: verbose +Multi: boolean +See-also: + - verbose + - silent +Example: + - --no-progress-meter -o store $URL +--- + +# `--no-progress-meter` + +Option to switch off the progress meter output without muting or otherwise +affecting warning and informational messages like --silent does. + +Note that this is the negated option name documented. You can thus use +--progress-meter to enable the progress meter again. diff --git a/docs/cmdline-opts/no-sessionid.d b/docs/cmdline-opts/no-sessionid.d deleted file mode 100644 index 9699f46bc97..00000000000 --- a/docs/cmdline-opts/no-sessionid.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: no-sessionid -Help: Disable SSL session-ID reusing -Protocols: TLS -Added: 7.16.0 -Category: tls -Example: --no-sessionid $URL -See-also: insecure -Multi: boolean ---- -Disable curl's use of SSL session-ID caching. By default all transfers are -done using the cache. Note that while nothing should ever get hurt by -attempting to reuse SSL session-IDs, there seem to be broken SSL -implementations in the wild that may require you to disable this in order for -you to succeed. - -Note that this is the negated option name documented. You can thus use ---sessionid to enforce session-ID caching. diff --git a/docs/cmdline-opts/no-sessionid.md b/docs/cmdline-opts/no-sessionid.md new file mode 100644 index 00000000000..08ba990beec --- /dev/null +++ b/docs/cmdline-opts/no-sessionid.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: no-sessionid +Help: Disable SSL session-ID reusing +Protocols: TLS +Added: 7.16.0 +Category: tls +Multi: boolean +See-also: + - insecure +Example: + - --no-sessionid $URL +--- + +# `--no-sessionid` + +Disable curl's use of SSL session-ID caching. By default all transfers are +done using the cache. Note that while nothing should ever get hurt by +attempting to reuse SSL session-IDs, there seem to be broken SSL +implementations in the wild that may require you to disable this in order for +you to succeed. + +Note that this is the negated option name documented. You can thus use +--sessionid to enforce session-ID caching. diff --git a/docs/cmdline-opts/noproxy.d b/docs/cmdline-opts/noproxy.d deleted file mode 100644 index 001c109b698..00000000000 --- a/docs/cmdline-opts/noproxy.d +++ /dev/null @@ -1,27 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: noproxy -Arg: -Help: List of hosts which do not use proxy -Added: 7.19.4 -Category: proxy -Example: --noproxy "www.example" $URL -See-also: proxy -Multi: single ---- -Comma-separated list of hosts for which not to use a proxy, if one is -specified. The only wildcard is a single * character, which matches all hosts, -and effectively disables the proxy. Each name in this list is matched as -either a domain which contains the hostname, or the hostname itself. For -example, local.com would match local.com, local.com:80, and www.local.com, but -not www.notlocal.com. - -This option overrides the environment variables that disable the proxy -('no_proxy' and 'NO_PROXY') (added in 7.53.0). If there is an environment -variable disabling a proxy, you can set the no proxy list to "" to override -it. - -IP addresses specified to this option can be provided using CIDR notation -(added in 7.86.0): an appended slash and number specifies the number of -"network bits" out of the address to use in the comparison. For example -"192.168.0.0/16" would match all addresses starting with "192.168". diff --git a/docs/cmdline-opts/noproxy.md b/docs/cmdline-opts/noproxy.md new file mode 100644 index 00000000000..698549e155d --- /dev/null +++ b/docs/cmdline-opts/noproxy.md @@ -0,0 +1,33 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: noproxy +Arg: +Help: List of hosts which do not use proxy +Added: 7.19.4 +Category: proxy +Multi: single +See-also: + - proxy +Example: + - --noproxy "www.example" $URL +--- + +# `--noproxy` + +Comma-separated list of hosts for which not to use a proxy, if one is +specified. The only wildcard is a single `*` character, which matches all +hosts, and effectively disables the proxy. Each name in this list is matched +as either a domain which contains the hostname, or the hostname itself. For +example, `local.com` would match `local.com`, `local.com:80`, and +`www.local.com`, but not `www.notlocal.com`. + +This option overrides the environment variables that disable the proxy +(`no_proxy` and `NO_PROXY`) (added in 7.53.0). If there is an environment +variable disabling a proxy, you can set the no proxy list to "" to override +it. + +IP addresses specified to this option can be provided using CIDR notation +(added in 7.86.0): an appended slash and number specifies the number of +network bits out of the address to use in the comparison. For example +`192.168.0.0/16` would match all addresses starting with `192.168`. diff --git a/docs/cmdline-opts/ntlm-wb.d b/docs/cmdline-opts/ntlm-wb.d deleted file mode 100644 index 4a322529365..00000000000 --- a/docs/cmdline-opts/ntlm-wb.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ntlm-wb -Help: Use HTTP NTLM authentication with winbind -Protocols: HTTP -See-also: ntlm proxy-ntlm -Category: auth http -Example: --ntlm-wb -u user:password $URL -Added: 7.22.0 -Multi: mutex ---- -Enables NTLM much in the style --ntlm does, but hand over the authentication -to the separate binary ntlmauth application that is executed when needed. diff --git a/docs/cmdline-opts/ntlm-wb.md b/docs/cmdline-opts/ntlm-wb.md new file mode 100644 index 00000000000..c5bcd4bfdc0 --- /dev/null +++ b/docs/cmdline-opts/ntlm-wb.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ntlm-wb +Help: HTTP NTLM authentication with winbind +Protocols: HTTP +Category: auth http +Added: 7.22.0 +Multi: mutex +See-also: + - ntlm + - proxy-ntlm +Example: + - --ntlm-wb -u user:password $URL +--- + +# `--ntlm-wb` + +Enables NTLM much in the style --ntlm does, but hand over the authentication +to the separate binary `ntlmauth` application that is executed when needed. diff --git a/docs/cmdline-opts/ntlm.d b/docs/cmdline-opts/ntlm.d deleted file mode 100644 index cc98c51e34c..00000000000 --- a/docs/cmdline-opts/ntlm.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ntlm -Help: Use HTTP NTLM authentication -Mutexed: basic negotiate digest anyauth -See-also: proxy-ntlm -Protocols: HTTP -Requires: TLS -Category: auth http -Example: --ntlm -u user:password $URL -Added: 7.10.6 -Multi: mutex ---- -Enables NTLM authentication. The NTLM authentication method was designed by -Microsoft and is used by IIS web servers. It is a proprietary protocol, -reverse-engineered by clever people and implemented in curl based on their -efforts. This kind of behavior should not be endorsed, you should encourage -everyone who uses NTLM to switch to a public and documented authentication -method instead, such as Digest. - -If you want to enable NTLM for your proxy authentication, then use ---proxy-ntlm. diff --git a/docs/cmdline-opts/ntlm.md b/docs/cmdline-opts/ntlm.md new file mode 100644 index 00000000000..b37716bcaa7 --- /dev/null +++ b/docs/cmdline-opts/ntlm.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ntlm +Help: HTTP NTLM authentication +Mutexed: basic negotiate digest anyauth +Protocols: HTTP +Requires: TLS +Category: auth http +Added: 7.10.6 +Multi: mutex +See-also: + - proxy-ntlm +Example: + - --ntlm -u user:password $URL +--- + +# `--ntlm` + +Use NTLM authentication. The NTLM authentication method was designed by +Microsoft and is used by IIS web servers. It is a proprietary protocol, +reverse-engineered by clever people and implemented in curl based on their +efforts. This kind of behavior should not be endorsed, you should encourage +everyone who uses NTLM to switch to a public and documented authentication +method instead, such as Digest. + +If you want to enable NTLM for your proxy authentication, then use +--proxy-ntlm. diff --git a/docs/cmdline-opts/oauth2-bearer.d b/docs/cmdline-opts/oauth2-bearer.d deleted file mode 100644 index 6f351478406..00000000000 --- a/docs/cmdline-opts/oauth2-bearer.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: oauth2-bearer -Help: OAuth 2 Bearer Token -Arg: -Protocols: IMAP LDAP POP3 SMTP HTTP -Category: auth -Example: --oauth2-bearer "mF_9.B5f-4.1JqM" $URL -Added: 7.33.0 -See-also: basic ntlm digest -Multi: single ---- -Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token -is used in conjunction with the user name which can be specified as part of -the --url or --user options. - -The Bearer Token and user name are formatted according to RFC 6750. diff --git a/docs/cmdline-opts/oauth2-bearer.md b/docs/cmdline-opts/oauth2-bearer.md new file mode 100644 index 00000000000..ee9ec5dccf1 --- /dev/null +++ b/docs/cmdline-opts/oauth2-bearer.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: oauth2-bearer +Help: OAuth 2 Bearer Token +Arg: +Protocols: IMAP LDAP POP3 SMTP HTTP +Category: auth +Added: 7.33.0 +Multi: single +See-also: + - basic + - ntlm + - digest +Example: + - --oauth2-bearer "mF_9.B5f-4.1JqM" $URL +--- + +# `--oauth2-bearer` + +Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token +is used in conjunction with the username which can be specified as part of the +--url or --user options. + +The Bearer Token and username are formatted according to RFC 6750. diff --git a/docs/cmdline-opts/output-dir.d b/docs/cmdline-opts/output-dir.d deleted file mode 100644 index 803b2948bbe..00000000000 --- a/docs/cmdline-opts/output-dir.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: output-dir -Arg: -Help: Directory to save files in -Added: 7.73.0 -See-also: remote-name remote-header-name -Category: curl -Example: --output-dir "tmp" -O $URL -Multi: single ---- -This option specifies the directory in which files should be stored, when ---remote-name or --output are used. - -The given output directory is used for all URLs and output options on the -command line, up until the first --next. - -If the specified target directory does not exist, the operation fails unless ---create-dirs is also used. diff --git a/docs/cmdline-opts/output-dir.md b/docs/cmdline-opts/output-dir.md new file mode 100644 index 00000000000..04d780f2986 --- /dev/null +++ b/docs/cmdline-opts/output-dir.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: output-dir +Arg: +Help: Directory to save files in +Added: 7.73.0 +Category: curl +Multi: single +See-also: + - remote-name + - remote-header-name +Example: + - --output-dir "tmp" -O $URL +--- + +# `--output-dir` + +Specify the directory in which files should be stored, when --remote-name or +--output are used. + +The given output directory is used for all URLs and output options on the +command line, up until the first --next. + +If the specified target directory does not exist, the operation fails unless +--create-dirs is also used. diff --git a/docs/cmdline-opts/output.d b/docs/cmdline-opts/output.d deleted file mode 100644 index 316f1099945..00000000000 --- a/docs/cmdline-opts/output.d +++ /dev/null @@ -1,49 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: output -Arg: -Short: o -Help: Write to file instead of stdout -See-also: remote-name remote-name-all remote-header-name -Category: important curl -Example: -o file $URL -Example: "http://{one,two}.example.com" -o "file_#1.txt" -Example: "http://{site,host}.host[1-5].example" -o "#1_#2" -Example: -o file $URL -o file2 https://example.net -Added: 4.0 -Multi: append ---- -Write output to instead of stdout. If you are using {} or [] to fetch -multiple documents, you should quote the URL and you can use '#' followed by a -number in the specifier. That variable is replaced with the current -string for the URL being fetched. Like in: - - curl "http://{one,two}.example.com" -o "file_#1.txt" - -or use several variables like: - - curl "http://{site,host}.host[1-5].example" -o "#1_#2" - -You may use this option as many times as the number of URLs you have. For -example, if you specify two URLs on the same command line, you can use it like -this: - - curl -o aa example.com -o bb example.net - -and the order of the -o options and the URLs does not matter, just that the -first -o is for the first URL and so on, so the above command line can also be -written as - - curl example.com example.net -o aa -o bb - -See also the --create-dirs option to create the local directories -dynamically. Specifying the output as '-' (a single dash) passes the output to -stdout. - -To suppress response bodies, you can redirect output to /dev/null: - - curl example.com -o /dev/null - -Or for Windows: - - curl example.com -o nul diff --git a/docs/cmdline-opts/output.md b/docs/cmdline-opts/output.md new file mode 100644 index 00000000000..53f65832723 --- /dev/null +++ b/docs/cmdline-opts/output.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: output +Arg: +Short: o +Help: Write to file instead of stdout +Category: important curl +Added: 4.0 +Multi: append +See-also: + - remote-name + - remote-name-all + - remote-header-name +Example: + - -o file $URL + - "http://{one,two}.example.com" -o "file_#1.txt" + - "http://{site,host}.host[1-5].example" -o "#1_#2" + - -o file $URL -o file2 https://example.net +--- + +# `--output` + +Write output to the given file instead of stdout. If you are using globbing to +fetch multiple documents, you should quote the URL and you can use `#` +followed by a number in the filename. That variable is then replaced with the +current string for the URL being fetched. Like in: + + curl "http://{one,two}.example.com" -o "file_#1.txt" + +or use several variables like: + + curl "http://{site,host}.host[1-5].example" -o "#1_#2" + +You may use this option as many times as the number of URLs you have. For +example, if you specify two URLs on the same command line, you can use it like +this: + + curl -o aa example.com -o bb example.net + +and the order of the -o options and the URLs does not matter, just that the +first -o is for the first URL and so on, so the above command line can also be +written as + + curl example.com example.net -o aa -o bb + +See also the --create-dirs option to create the local directories +dynamically. Specifying the output as '-' (a single dash) passes the output to +stdout. + +To suppress response bodies, you can redirect output to /dev/null: + + curl example.com -o /dev/null + +Or for Windows: + + curl example.com -o nul + +Specify the filename as single minus to force the output to stdout, to +override curl's internal binary output in terminal prevention: + + curl https://example.com/jpeg -o - diff --git a/docs/cmdline-opts/page-footer b/docs/cmdline-opts/page-footer deleted file mode 100644 index af41c94824a..00000000000 --- a/docs/cmdline-opts/page-footer +++ /dev/null @@ -1,322 +0,0 @@ -.SH FILES -.I ~/.curlrc -.RS -Default config file, see --config for details. -.SH ENVIRONMENT -The environment variables can be specified in lower case or upper case. The -lower case version has precedence. http_proxy is an exception as it is only -available in lower case. - -Using an environment variable to set the proxy has the same effect as using -the --proxy option. - -.IP "http_proxy [protocol://][:port]" -Sets the proxy server to use for HTTP. -.IP "HTTPS_PROXY [protocol://][:port]" -Sets the proxy server to use for HTTPS. -.IP "[url-protocol]_PROXY [protocol://][:port]" -Sets the proxy server to use for [url-protocol], where the protocol is a -protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP, -SMTP, LDAP, etc. -.IP "ALL_PROXY [protocol://][:port]" -Sets the proxy server to use if no protocol-specific proxy is set. -.IP "NO_PROXY " -list of host names that should not go through any proxy. If set to an asterisk -'*' only, it matches all hosts. Each name in this list is matched as either -a domain name which contains the hostname, or the hostname itself. - -This environment variable disables use of the proxy even when specified with -the --proxy option. That is -.B NO_PROXY=direct.example.com curl -x http://proxy.example.com -.B http://direct.example.com -accesses the target URL directly, and -.B NO_PROXY=direct.example.com curl -x http://proxy.example.com -.B http://somewhere.example.com -accesses the target URL through the proxy. - -The list of host names can also be include numerical IP addresses, and IPv6 -versions should then be given without enclosing brackets. - -IP addresses can be specified using CIDR notation: an appended slash and -number specifies the number of "network bits" out of the address to use in the -comparison (added in 7.86.0). For example "192.168.0.0/16" would match all -addresses starting with "192.168". -.IP "APPDATA " -On Windows, this variable is used when trying to find the home directory. If -the primary home variable are all unset. -.IP "COLUMNS " -If set, the specified number of characters is used as the terminal width when -the alternative progress-bar is shown. If not set, curl tries to figure it out -using other ways. -.IP "CURL_CA_BUNDLE " -If set, it is used as the --cacert value. -.IP "CURL_HOME " -If set, is the first variable curl checks when trying to find its home -directory. If not set, it continues to check *XDG_CONFIG_HOME* -.IP "CURL_SSL_BACKEND " -If curl was built with support for "MultiSSL", meaning that it has built-in -support for more than one TLS backend, this environment variable can be set to -the case insensitive name of the particular backend to use when curl is -invoked. Setting a name that is not a built-in alternative makes curl stay -with the default. - -SSL backend names (case-insensitive): **bearssl**, **gnutls**, **mbedtls**, -**openssl**, **rustls**, **schannel**, **secure-transport**, **wolfssl** -.IP "HOME " -If set, this is used to find the home directory when that is needed. Like when -looking for the default .curlrc. *CURL_HOME* and *XDG_CONFIG_HOME* -have preference. -.IP "QLOGDIR " -If curl was built with HTTP/3 support, setting this environment variable to a -local directory makes curl produce **qlogs** in that directory, using file -names named after the destination connection id (in hex). Do note that these -files can become rather large. Works with the ngtcp2 and quiche QUIC backends. -.IP SHELL -Used on VMS when trying to detect if using a **DCL** or a **unix** shell. -.IP "SSL_CERT_DIR " -If set, it is used as the --capath value. -.IP "SSL_CERT_FILE " -If set, it is used as the --cacert value. -.IP "SSLKEYLOGFILE " -If you set this environment variable to a file name, curl stores TLS secrets -from its connections in that file when invoked to enable you to analyze the -TLS traffic in real time using network analyzing tools such as Wireshark. This -works with the following TLS backends: OpenSSL, libressl, BoringSSL, GnuTLS -and wolfSSL. -.IP "USERPROFILE " -On Windows, this variable is used when trying to find the home directory. If -the other, primary, variable are all unset. If set, curl uses the path -**"$USERPROFILE\\Application Data"**. -.IP "XDG_CONFIG_HOME " -If *CURL_HOME* is not set, this variable is checked when looking for a -default .curlrc file. -.SH "PROXY PROTOCOL PREFIXES" -The proxy string may be specified with a protocol:// prefix to specify -alternative proxy protocols. (Added in 7.21.7) - -If no protocol is specified in the proxy string or if the string does not -match a supported one, the proxy is treated as an HTTP proxy. - -The supported proxy protocol prefixes are as follows: -.IP "http://" -Makes it use it as an HTTP proxy. The default if no scheme prefix is used. -.IP "https://" -Makes it treated as an **HTTPS** proxy. -.IP "socks4://" -Makes it the equivalent of --socks4 -.IP "socks4a://" -Makes it the equivalent of --socks4a -.IP "socks5://" -Makes it the equivalent of --socks5 -.IP "socks5h://" -Makes it the equivalent of --socks5-hostname -.SH EXIT CODES -There are a bunch of different error codes and their corresponding error -messages that may appear under error conditions. At the time of this writing, -the exit codes are: -.IP 0 -Success. The operation completed successfully according to the instructions. -.IP 1 -Unsupported protocol. This build of curl has no support for this protocol. -.IP 2 -Failed to initialize. -.IP 3 -URL malformed. The syntax was not correct. -.IP 4 -A feature or option that was needed to perform the desired request was not -enabled or was explicitly disabled at build-time. To make curl able to do -this, you probably need another build of libcurl. -.IP 5 -Could not resolve proxy. The given proxy host could not be resolved. -.IP 6 -Could not resolve host. The given remote host could not be resolved. -.IP 7 -Failed to connect to host. -.IP 8 -Weird server reply. The server sent data curl could not parse. -.IP 9 -FTP access denied. The server denied login or denied access to the particular -resource or directory you wanted to reach. Most often you tried to change to a -directory that does not exist on the server. -.IP 10 -FTP accept failed. While waiting for the server to connect back when an active -FTP session is used, an error code was sent over the control connection or -similar. -.IP 11 -FTP weird PASS reply. Curl could not parse the reply sent to the PASS request. -.IP 12 -During an active FTP session while waiting for the server to connect back to -curl, the timeout expired. -.IP 13 -FTP weird PASV reply, Curl could not parse the reply sent to the PASV request. -.IP 14 -FTP weird 227 format. Curl could not parse the 227-line the server sent. -.IP 15 -FTP cannot use host. Could not resolve the host IP we got in the 227-line. -.IP 16 -HTTP/2 error. A problem was detected in the HTTP2 framing layer. This is -somewhat generic and can be one out of several problems, see the error message -for details. -.IP 17 -FTP could not set binary. Could not change transfer method to binary. -.IP 18 -Partial file. Only a part of the file was transferred. -.IP 19 -FTP could not download/access the given file, the RETR (or similar) command -failed. -.IP 21 -FTP quote error. A quote command returned error from the server. -.IP 22 -HTTP page not retrieved. The requested URL was not found or returned another -error with the HTTP error code being 400 or above. This return code only -appears if --fail is used. -.IP 23 -Write error. Curl could not write data to a local filesystem or similar. -.IP 25 -Failed starting the upload. For FTP, the server typically denied the STOR -command. -.IP 26 -Read error. Various reading problems. -.IP 27 -Out of memory. A memory allocation request failed. -.IP 28 -Operation timeout. The specified time-out period was reached according to the -conditions. -.IP 30 -FTP PORT failed. The PORT command failed. Not all FTP servers support the PORT -command, try doing a transfer using PASV instead! -.IP 31 -FTP could not use REST. The REST command failed. This command is used for -resumed FTP transfers. -.IP 33 -HTTP range error. The range "command" did not work. -.IP 34 -HTTP post error. Internal post-request generation error. -.IP 35 -SSL connect error. The SSL handshaking failed. -.IP 36 -Bad download resume. Could not continue an earlier aborted download. -.IP 37 -FILE could not read file. Failed to open the file. Permissions? -.IP 38 -LDAP cannot bind. LDAP bind operation failed. -.IP 39 -LDAP search failed. -.IP 41 -Function not found. A required LDAP function was not found. -.IP 42 -Aborted by callback. An application told curl to abort the operation. -.IP 43 -Internal error. A function was called with a bad parameter. -.IP 45 -Interface error. A specified outgoing interface could not be used. -.IP 47 -Too many redirects. When following redirects, curl hit the maximum amount. -.IP 48 -Unknown option specified to libcurl. This indicates that you passed a weird -option to curl that was passed on to libcurl and rejected. Read up in the -manual! -.IP 49 -Malformed telnet option. -.IP 52 -The server did not reply anything, which here is considered an error. -.IP 53 -SSL crypto engine not found. -.IP 54 -Cannot set SSL crypto engine as default. -.IP 55 -Failed sending network data. -.IP 56 -Failure in receiving network data. -.IP 58 -Problem with the local certificate. -.IP 59 -Could not use specified SSL cipher. -.IP 60 -Peer certificate cannot be authenticated with known CA certificates. -.IP 61 -Unrecognized transfer encoding. -.IP 63 -Maximum file size exceeded. -.IP 64 -Requested FTP SSL level failed. -.IP 65 -Sending the data requires a rewind that failed. -.IP 66 -Failed to initialize SSL Engine. -.IP 67 -The user name, password, or similar was not accepted and curl failed to log in. -.IP 68 -File not found on TFTP server. -.IP 69 -Permission problem on TFTP server. -.IP 70 -Out of disk space on TFTP server. -.IP 71 -Illegal TFTP operation. -.IP 72 -Unknown TFTP transfer ID. -.IP 73 -File already exists (TFTP). -.IP 74 -No such user (TFTP). -.IP 77 -Problem reading the SSL CA cert (path? access rights?). -.IP 78 -The resource referenced in the URL does not exist. -.IP 79 -An unspecified error occurred during the SSH session. -.IP 80 -Failed to shut down the SSL connection. -.IP 82 -Could not load CRL file, missing or wrong format (added in 7.19.0). -.IP 83 -Issuer check failed (added in 7.19.0). -.IP 84 -The FTP PRET command failed. -.IP 85 -Mismatch of RTSP CSeq numbers. -.IP 86 -Mismatch of RTSP Session Identifiers. -.IP 87 -Unable to parse FTP file list. -.IP 88 -FTP chunk callback reported error. -.IP 89 -No connection available, the session is queued. -.IP 90 -SSL public key does not matched pinned public key. -.IP 91 -Invalid SSL certificate status. -.IP 92 -Stream error in HTTP/2 framing layer. -.IP 93 -An API function was called from inside a callback. -.IP 94 -An authentication function returned an error. -.IP 95 -A problem was detected in the HTTP/3 layer. This is somewhat generic and can -be one out of several problems, see the error message for details. -.IP 96 -QUIC connection error. This error may be caused by an SSL library error. QUIC -is the protocol used for HTTP/3 transfers. -.IP 97 -Proxy handshake error. -.IP 98 -A client-side certificate is required to complete the TLS handshake. -.IP 99 -Poll or select returned fatal error. -.IP XX -More error codes might appear here in future releases. The existing ones are -meant to never change. -.SH BUGS -If you experience any problems with curl, submit an issue in the project's bug -tracker on GitHub: https://github.com/curl/curl/issues -.SH AUTHORS / CONTRIBUTORS -Daniel Stenberg is the main author, but the whole list of contributors is -found in the separate THANKS file. -.SH WWW -https://curl.se -.SH "SEE ALSO" -.BR ftp (1), -.BR wget (1) diff --git a/docs/cmdline-opts/page-header b/docs/cmdline-opts/page-header deleted file mode 100644 index 7d14f4c4520..00000000000 --- a/docs/cmdline-opts/page-header +++ /dev/null @@ -1,258 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) Daniel Stenberg, , et al. -.\" * -.\" * This software is licensed as described in the file COPYING, which -.\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.se/docs/copyright.html. -.\" * -.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell -.\" * copies of the Software, and permit persons to whom the Software is -.\" * furnished to do so, under the terms of the COPYING file. -.\" * -.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -.\" * KIND, either express or implied. -.\" * -.\" * SPDX-License-Identifier: curl -.\" * -.\" ************************************************************************** -.\" -.\" DO NOT EDIT. Generated by the curl project gen.pl man page generator. -.\" -.TH curl 1 "%DATE" "curl %VERSION" "curl Manual" -.SH NAME -curl \- transfer a URL -.SH SYNOPSIS -.B curl [options / URLs] -.SH DESCRIPTION -**curl** is a tool for transferring data from or to a server using URLs. It -supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, -IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, -SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. - -curl is powered by libcurl for all transfer-related features. See -*libcurl(3)* for details. -.SH URL -The URL syntax is protocol-dependent. You find a detailed description in -RFC 3986. - -If you provide a URL without a leading **protocol://** scheme, curl guesses -what protocol you want. It then defaults to HTTP but assumes others based on -often-used host name prefixes. For example, for host names starting with -"ftp." curl assumes you want FTP. - -You can specify any amount of URLs on the command line. They are fetched in a -sequential manner in the specified order unless you use --parallel. You can -specify command line options and URLs mixed and in any order on the command -line. - -curl attempts to reuse connections when doing multiple transfers, so that -getting many files from the same server do not use multiple connects and setup -handshakes. This improves speed. Connection reuse can only be done for URLs -specified for a single command line invocation and cannot be performed between -separate curl runs. - -Provide an IPv6 zone id in the URL with an escaped percentage sign. Like in - - "http://[fe80::3%25eth0]/" - -Everything provided on the command line that is not a command line option or -its argument, curl assumes is a URL and treats it as such. -.SH GLOBBING -You can specify multiple URLs or parts of URLs by writing lists within braces -or ranges within brackets. We call this "globbing". - -Provide a list with three different names like this: - - "http://site.{one,two,three}.com" - -or you can get sequences of alphanumeric series by using [] as in: - - "ftp://ftp.example.com/file[1-100].txt" - - "ftp://ftp.example.com/file[001-100].txt" (with leading zeros) - - "ftp://ftp.example.com/file[a-z].txt" - -Nested sequences are not supported, but you can use several ones next to each -other: - - "http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html" - -You can specify a step counter for the ranges to get every Nth number or -letter: - - "http://example.com/file[1-100:10].txt" - - "http://example.com/file[a-z:2].txt" - -When using [] or {} sequences when invoked from a command line prompt, you -probably have to put the full URL within double quotes to avoid the shell from -interfering with it. This also goes for other characters treated special, like -for example '&', '?' and '*'. - -Switch off globbing with --globoff. -.SH VARIABLES -curl supports command line variables (added in 8.3.0). Set variables with ---variable name=content or --variable name@file (where "file" can be stdin if -set to a single dash (-)). - -Variable contents can expanded in option parameters using "{{name}}" (without -the quotes) if the option name is prefixed with "--expand-". This gets the -contents of the variable "name" inserted, or a blank if the name does not -exist as a variable. Insert "{{" verbatim in the string by prefixing it with a -backslash, like "\\{{". - -You an access and expand environment variables by first importing them. You -can select to either require the environment variable to be set or you can -provide a default value in case it is not already set. Plain --variable %name -imports the variable called 'name' but exits with an error if that environment -variable is not already set. To provide a default value if it is not set, use ---variable %name=content or --variable %name@content. - -Example. Get the USER environment variable into the URL, fail if USER is not -set: - - --variable '%USER' - --expand-url = "https://example.com/api/{{USER}}/method" - -When expanding variables, curl supports a set of functions that can make the -variable contents more convenient to use. It can trim leading and trailing -white space with *trim*, it can output the contents as a JSON quoted string -with *json*, URL encode the string with *url* or base64 encode it with -*b64*. You apply function to a variable expansion, add them colon separated to -the right side of the variable. Variable content holding null bytes that are -not encoded when expanded cause error. - -Example: get the contents of a file called $HOME/.secret into a variable -called "fix". Make sure that the content is trimmed and percent-encoded sent -as POST data: - - --variable %HOME - --expand-variable fix@{{HOME}}/.secret - --expand-data "{{fix:trim:url}}" - https://example.com/ - -Command line variables and expansions were added in in 8.3.0. -.SH OUTPUT -If not told otherwise, curl writes the received data to stdout. It can be -instructed to instead save that data into a local file, using the --output or ---remote-name options. If curl is given multiple URLs to transfer on the -command line, it similarly needs multiple options for where to save them. - -curl does not parse or otherwise "understand" the content it gets or writes as -output. It does no encoding or decoding, unless explicitly asked to with -dedicated command line options. -.SH PROTOCOLS -curl supports numerous protocols, or put in URL terms: schemes. Your -particular build may not support them all. -.IP DICT -Lets you lookup words using online dictionaries. -.IP FILE -Read or write local files. curl does not support accessing file:// URL -remotely, but when running on Microsoft Windows using the native UNC approach -works. -.IP FTP(S) -curl supports the File Transfer Protocol with a lot of tweaks and levers. With -or without using TLS. -.IP GOPHER(S) -Retrieve files. -.IP HTTP(S) -curl supports HTTP with numerous options and variations. It can speak HTTP -version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct -command line options. -.IP IMAP(S) -Using the mail reading protocol, curl can "download" emails for you. With or -without using TLS. -.IP LDAP(S) -curl can do directory lookups for you, with or without TLS. -.IP MQTT -curl supports MQTT version 3. Downloading over MQTT equals "subscribe" to a -topic while uploading/posting equals "publish" on a topic. MQTT over TLS is -not supported (yet). -.IP POP3(S) -Downloading from a pop3 server means getting a mail. With or without using -TLS. -.IP RTMP(S) -The **Realtime Messaging Protocol** is primarily used to serve streaming media -and curl can download it. -.IP RTSP -curl supports RTSP 1.0 downloads. -.IP SCP -curl supports SSH version 2 scp transfers. -.IP SFTP -curl supports SFTP (draft 5) done over SSH version 2. -.IP SMB(S) -curl supports SMB version 1 for upload and download. -.IP SMTP(S) -Uploading contents to an SMTP server means sending an email. With or without -TLS. -.IP TELNET -Telling curl to fetch a telnet URL starts an interactive session where it -sends what it reads on stdin and outputs what the server sends it. -.IP TFTP -curl can do TFTP downloads and uploads. -.SH "PROGRESS METER" -curl normally displays a progress meter during operations, indicating the -amount of transferred data, transfer speeds and estimated time left, etc. The -progress meter displays the transfer rate in bytes per second. The suffixes -(k, M, G, T, P) are 1024 based. For example 1k is 1024 bytes. 1M is 1048576 -bytes. - -curl displays this data to the terminal by default, so if you invoke curl to -do an operation and it is about to write data to the terminal, it -*disables* the progress meter as otherwise it would mess up the output -mixing progress meter and response data. - -If you want a progress meter for HTTP POST or PUT requests, you need to -redirect the response output to a file, using shell redirect (>), --output or -similar. - -This does not apply to FTP upload as that operation does not spit out any -response data to the terminal. - -If you prefer a progress "bar" instead of the regular meter, --progress-bar is -your friend. You can also disable the progress meter completely with the ---silent option. -.SH VERSION -This man page describes curl %VERSION. If you use a later version, chances are -this man page does not fully document it. If you use an earlier version, this -document tries to include version information about which specific version -that introduced changes. - -You can always learn which the latest curl version is by running - - curl https://curl.se/info - -The online version of this man page is always showing the latest incarnation: -https://curl.se/docs/manpage.html -.SH OPTIONS -Options start with one or two dashes. Many of the options require an -additional value next to them. If provided text does not start with a dash, it -is presumed to be and treated as a URL. - -The short "single-dash" form of the options, -d for example, may be used with -or without a space between it and its value, although a space is a recommended -separator. The long "double-dash" form, --data for example, requires a space -between it and its value. - -Short version options that do not need any additional values can be used -immediately next to each other, like for example you can specify all the -options *-O*, *-L* and *-v* at once as *-OLv*. - -In general, all boolean options are enabled with --**option** and yet again -disabled with --**no-**option. That is, you use the same option name but -prefix it with "no-". However, in this list we mostly only list and show the -*--option* version of them. - -When --next is used, it resets the parser state and you start again with a -clean option state, except for the options that are "global". Global options -retain their values and meaning even after --next. - -The following options are global: -%GLOBALS. diff --git a/docs/cmdline-opts/parallel-immediate.d b/docs/cmdline-opts/parallel-immediate.d deleted file mode 100644 index b534dd51228..00000000000 --- a/docs/cmdline-opts/parallel-immediate.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: parallel-immediate -Help: Do not wait for multiplexing (with --parallel) -Added: 7.68.0 -See-also: parallel parallel-max -Category: connection curl -Example: --parallel-immediate -Z $URL -o file1 $URL -o file2 -Multi: boolean -Scope: global ---- -When doing parallel transfers, this option instructs curl that it should -rather prefer opening up more connections in parallel at once rather than -waiting to see if new transfers can be added as multiplexed streams on another -connection. diff --git a/docs/cmdline-opts/parallel-immediate.md b/docs/cmdline-opts/parallel-immediate.md new file mode 100644 index 00000000000..f93a355f27c --- /dev/null +++ b/docs/cmdline-opts/parallel-immediate.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: parallel-immediate +Help: Do not wait for multiplexing (with --parallel) +Added: 7.68.0 +Category: connection curl +Multi: boolean +Scope: global +See-also: + - parallel + - parallel-max +Example: + - --parallel-immediate -Z $URL -o file1 $URL -o file2 +--- + +# `--parallel-immediate` + +When doing parallel transfers, this option instructs curl that it should +rather prefer opening up more connections in parallel at once rather than +waiting to see if new transfers can be added as multiplexed streams on another +connection. diff --git a/docs/cmdline-opts/parallel-max.d b/docs/cmdline-opts/parallel-max.d deleted file mode 100644 index cc6d32d1825..00000000000 --- a/docs/cmdline-opts/parallel-max.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: parallel-max -Arg: -Help: Maximum concurrency for parallel transfers -Added: 7.66.0 -See-also: parallel -Category: connection curl -Example: --parallel-max 100 -Z $URL ftp://example.com/ -Multi: single ---- -When asked to do parallel transfers, using --parallel, this option controls -the maximum amount of transfers to do simultaneously. - -This option is global and does not need to be specified for each use of ---next. - -The default is 50. diff --git a/docs/cmdline-opts/parallel-max.md b/docs/cmdline-opts/parallel-max.md new file mode 100644 index 00000000000..f3d2ad19813 --- /dev/null +++ b/docs/cmdline-opts/parallel-max.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: parallel-max +Arg: +Help: Maximum concurrency for parallel transfers +Added: 7.66.0 +Category: connection curl +Multi: single +See-also: + - parallel +Example: + - --parallel-max 100 -Z $URL ftp://example.com/ +--- + +# `--parallel-max` + +When asked to do parallel transfers, using --parallel, this option controls +the maximum amount of transfers to do simultaneously. + +This option is global and does not need to be specified for each use of +--next. + +The default is 50. diff --git a/docs/cmdline-opts/parallel.d b/docs/cmdline-opts/parallel.d deleted file mode 100644 index 4f698f8b3ab..00000000000 --- a/docs/cmdline-opts/parallel.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: Z -Long: parallel -Help: Perform transfers in parallel -Added: 7.66.0 -Category: connection curl -Example: --parallel $URL -o file1 $URL -o file2 -See-also: next verbose -Multi: boolean -Scope: global ---- -Makes curl perform its transfers in parallel as compared to the regular serial -manner. diff --git a/docs/cmdline-opts/parallel.md b/docs/cmdline-opts/parallel.md new file mode 100644 index 00000000000..f67598a0b8b --- /dev/null +++ b/docs/cmdline-opts/parallel.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: Z +Long: parallel +Help: Perform transfers in parallel +Added: 7.66.0 +Category: connection curl +Multi: boolean +Scope: global +See-also: + - next + - verbose +Example: + - --parallel $URL -o file1 $URL -o file2 +--- + +# `--parallel` + +Makes curl perform its transfers in parallel as compared to the regular serial +manner. diff --git a/docs/cmdline-opts/pass.d b/docs/cmdline-opts/pass.d deleted file mode 100644 index 2c0a2bef62f..00000000000 --- a/docs/cmdline-opts/pass.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: pass -Arg: -Help: Pass phrase for the private key -Protocols: SSH TLS -Category: ssh tls auth -Example: --pass secret --key file $URL -Added: 7.9.3 -See-also: key user -Multi: single ---- -Passphrase for the private key. diff --git a/docs/cmdline-opts/pass.md b/docs/cmdline-opts/pass.md new file mode 100644 index 00000000000..a0d94563ebd --- /dev/null +++ b/docs/cmdline-opts/pass.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: pass +Arg: +Help: Pass phrase for the private key +Protocols: SSH TLS +Category: ssh tls auth +Added: 7.9.3 +Multi: single +See-also: + - key + - user +Example: + - --pass secret --key file $URL +--- + +# `--pass` + +Passphrase for the private key. diff --git a/docs/cmdline-opts/path-as-is.d b/docs/cmdline-opts/path-as-is.d deleted file mode 100644 index 9897d882f61..00000000000 --- a/docs/cmdline-opts/path-as-is.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: path-as-is -Help: Do not squash .. sequences in URL path -Added: 7.42.0 -Category: curl -Example: --path-as-is https://example.com/../../etc/passwd -See-also: request-target -Multi: boolean ---- -Tell curl to not handle sequences of /../ or /./ in the given URL -path. Normally curl squashes or merges them according to standards but with -this option set you tell it not to do that. diff --git a/docs/cmdline-opts/path-as-is.md b/docs/cmdline-opts/path-as-is.md new file mode 100644 index 00000000000..f3a60cff245 --- /dev/null +++ b/docs/cmdline-opts/path-as-is.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: path-as-is +Help: Do not squash .. sequences in URL path +Added: 7.42.0 +Category: curl +Multi: boolean +See-also: + - request-target +Example: + - --path-as-is https://example.com/../../etc/passwd +--- + +# `--path-as-is` + +Do not handle sequences of /../ or /./ in the given URL path. Normally curl +squashes or merges them according to standards but with this option set you +tell it not to do that. diff --git a/docs/cmdline-opts/pinnedpubkey.d b/docs/cmdline-opts/pinnedpubkey.d deleted file mode 100644 index d799bfac8ce..00000000000 --- a/docs/cmdline-opts/pinnedpubkey.d +++ /dev/null @@ -1,38 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: pinnedpubkey -Arg: -Help: FILE/HASHES Public key to verify peer against -Protocols: TLS -Category: tls -Example: --pinnedpubkey keyfile $URL -Example: --pinnedpubkey 'sha256//ce118b51897f4452dc' $URL -Added: 7.39.0 -See-also: hostpubsha256 -Multi: single ---- -Tells curl to use the specified public key file (or hashes) to verify the -peer. This can be a path to a file which contains a single public key in PEM -or DER format, or any number of base64 encoded sha256 hashes preceded by -'sha256//' and separated by ';'. - -When negotiating a TLS or SSL connection, the server sends a certificate -indicating its identity. A public key is extracted from this certificate and -if it does not exactly match the public key provided to this option, curl -aborts the connection before sending or receiving any data. - -This option is independent of option --insecure. If you use both options -together then the peer is still verified by public key. - -PEM/DER support: - -OpenSSL and GnuTLS (added in 7.39.0), wolfSSL (added in 7.43.0), mbedTLS -(added in 7.47.0), Secure Transport macOS 10.7+/iOS 10+ (7.54.1), Schannel -(7.58.1) - -sha256 support: - -OpenSSL, GnuTLS and wolfSSL (added in 7.44.0), mbedTLS (added in 7.47.0), -Secure Transport macOS 10.7+/iOS 10+ (7.54.1), Schannel (7.58.1) - -Other SSL backends not supported. diff --git a/docs/cmdline-opts/pinnedpubkey.md b/docs/cmdline-opts/pinnedpubkey.md new file mode 100644 index 00000000000..53c79912af1 --- /dev/null +++ b/docs/cmdline-opts/pinnedpubkey.md @@ -0,0 +1,44 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: pinnedpubkey +Arg: +Help: FILE/HASHES Public key to verify peer against +Protocols: TLS +Category: tls +Added: 7.39.0 +Multi: single +See-also: + - hostpubsha256 +Example: + - --pinnedpubkey keyfile $URL + - --pinnedpubkey 'sha256//ce118b51897f4452dc' $URL +--- + +# `--pinnedpubkey` + +Use the specified public key file (or hashes) to verify the peer. This can be +a path to a file which contains a single public key in PEM or DER format, or +any number of base64 encoded sha256 hashes preceded by 'sha256//' and +separated by ';'. + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. A public key is extracted from this certificate and +if it does not exactly match the public key provided to this option, curl +aborts the connection before sending or receiving any data. + +This option is independent of option --insecure. If you use both options +together then the peer is still verified by public key. + +PEM/DER support: + +OpenSSL and GnuTLS (added in 7.39.0), wolfSSL (added in 7.43.0), mbedTLS +(added in 7.47.0), Secure Transport macOS 10.7+/iOS 10+ (7.54.1), Schannel +(7.58.1) + +sha256 support: + +OpenSSL, GnuTLS and wolfSSL (added in 7.44.0), mbedTLS (added in 7.47.0), +Secure Transport macOS 10.7+/iOS 10+ (7.54.1), Schannel (7.58.1) + +Other SSL backends not supported. diff --git a/docs/cmdline-opts/post301.d b/docs/cmdline-opts/post301.d deleted file mode 100644 index d067fc8cc0e..00000000000 --- a/docs/cmdline-opts/post301.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: post301 -Help: Do not switch to GET after following a 301 -Protocols: HTTP -See-also: post302 post303 location -Added: 7.17.1 -Category: http post -Example: --post301 --location -d "data" $URL -Multi: boolean ---- -Tells curl to respect RFC 7231/6.4.2 and not convert POST requests into GET -requests when following a 301 redirection. The non-RFC behavior is ubiquitous -in web browsers, so curl does the conversion by default to maintain -consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using --location. diff --git a/docs/cmdline-opts/post301.md b/docs/cmdline-opts/post301.md new file mode 100644 index 00000000000..d9506f7dfe3 --- /dev/null +++ b/docs/cmdline-opts/post301.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: post301 +Help: Do not switch to GET after a 301 redirect +Protocols: HTTP +Added: 7.17.1 +Category: http post +Multi: boolean +See-also: + - post302 + - post303 + - location +Example: + - --post301 --location -d "data" $URL +--- + +# `--post301` + +Respect RFC 7231/6.4.2 and do not convert POST requests into GET requests when +following a 301 redirect. The non-RFC behavior is ubiquitous in web browsers, +so curl does the conversion by default to maintain consistency. However, a +server may require a POST to remain a POST after such a redirection. This +option is meaningful only when using --location. diff --git a/docs/cmdline-opts/post302.d b/docs/cmdline-opts/post302.d deleted file mode 100644 index b7190ce0fb6..00000000000 --- a/docs/cmdline-opts/post302.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: post302 -Help: Do not switch to GET after following a 302 -Protocols: HTTP -See-also: post301 post303 location -Added: 7.19.1 -Category: http post -Example: --post302 --location -d "data" $URL -Multi: boolean ---- -Tells curl to respect RFC 7231/6.4.3 and not convert POST requests into GET -requests when following a 302 redirection. The non-RFC behavior is ubiquitous -in web browsers, so curl does the conversion by default to maintain -consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using --location. diff --git a/docs/cmdline-opts/post302.md b/docs/cmdline-opts/post302.md new file mode 100644 index 00000000000..9b2c2f658d7 --- /dev/null +++ b/docs/cmdline-opts/post302.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: post302 +Help: Do not switch to GET after a 302 redirect +Protocols: HTTP +Added: 7.19.1 +Category: http post +Multi: boolean +See-also: + - post301 + - post303 + - location +Example: + - --post302 --location -d "data" $URL +--- + +# `--post302` + +Respect RFC 7231/6.4.3 and do not convert POST requests into GET requests when +following a 302 redirect. The non-RFC behavior is ubiquitous in web browsers, +so curl does the conversion by default to maintain consistency. However, a +server may require a POST to remain a POST after such a redirection. This +option is meaningful only when using --location. diff --git a/docs/cmdline-opts/post303.d b/docs/cmdline-opts/post303.d deleted file mode 100644 index 52d440c4534..00000000000 --- a/docs/cmdline-opts/post303.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: post303 -Help: Do not switch to GET after following a 303 -Protocols: HTTP -See-also: post302 post301 location -Added: 7.26.0 -Category: http post -Example: --post303 --location -d "data" $URL -Multi: boolean ---- -Tells curl to violate RFC 7231/6.4.4 and not convert POST requests into GET -requests when following 303 redirections. A server may require a POST to -remain a POST after a 303 redirection. This option is meaningful only when -using --location. diff --git a/docs/cmdline-opts/post303.md b/docs/cmdline-opts/post303.md new file mode 100644 index 00000000000..63dc0d7956b --- /dev/null +++ b/docs/cmdline-opts/post303.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: post303 +Help: Do not switch to GET after a 303 redirect +Protocols: HTTP +Added: 7.26.0 +Category: http post +Multi: boolean +See-also: + - post302 + - post301 + - location +Example: + - --post303 --location -d "data" $URL +--- + +# `--post303` + +Violate RFC 7231/6.4.4 and do not convert POST requests into GET requests when +following 303 redirect. A server may require a POST to remain a POST after a +303 redirection. This option is meaningful only when using --location. diff --git a/docs/cmdline-opts/preproxy.d b/docs/cmdline-opts/preproxy.d deleted file mode 100644 index b55c1d47a29..00000000000 --- a/docs/cmdline-opts/preproxy.d +++ /dev/null @@ -1,26 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: preproxy -Arg: [protocol://]host[:port] -Help: Use this proxy first -Added: 7.52.0 -Category: proxy -Example: --preproxy socks5://proxy.example -x http://http.example $URL -See-also: proxy socks5 -Multi: single ---- -Use the specified SOCKS proxy before connecting to an HTTP or HTTPS --proxy. In -such a case curl first connects to the SOCKS proxy and then connects (through -SOCKS) to the HTTP or HTTPS proxy. Hence pre proxy. - -The pre proxy string should be specified with a protocol:// prefix to specify -alternative proxy protocols. Use socks4://, socks4a://, socks5:// or -socks5h:// to request the specific SOCKS version to be used. No protocol -specified makes curl default to SOCKS4. - -If the port number is not specified in the proxy string, it is assumed to be -1080. - -User and password that might be provided in the proxy string are URL decoded -by curl. This allows you to pass in special characters such as @ by using %40 -or pass in a colon with %3a. diff --git a/docs/cmdline-opts/preproxy.md b/docs/cmdline-opts/preproxy.md new file mode 100644 index 00000000000..dabccfc5efe --- /dev/null +++ b/docs/cmdline-opts/preproxy.md @@ -0,0 +1,33 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: preproxy +Arg: [protocol://]host[:port] +Help: Use this proxy first +Added: 7.52.0 +Category: proxy +Multi: single +See-also: + - proxy + - socks5 +Example: + - --preproxy socks5://proxy.example -x http://http.example $URL +--- + +# `--preproxy` + +Use the specified SOCKS proxy before connecting to an HTTP or HTTPS --proxy. In +such a case curl first connects to the SOCKS proxy and then connects (through +SOCKS) to the HTTP or HTTPS proxy. Hence pre proxy. + +The pre proxy string should be specified with a protocol:// prefix to specify +alternative proxy protocols. Use socks4://, socks4a://, socks5:// or +socks5h:// to request the specific SOCKS version to be used. No protocol +specified makes curl default to SOCKS4. + +If the port number is not specified in the proxy string, it is assumed to be +1080. + +User and password that might be provided in the proxy string are URL decoded +by curl. This allows you to pass in special characters such as @ by using %40 +or pass in a colon with %3a. diff --git a/docs/cmdline-opts/progress-bar.d b/docs/cmdline-opts/progress-bar.d deleted file mode 100644 index fee170979d1..00000000000 --- a/docs/cmdline-opts/progress-bar.d +++ /dev/null @@ -1,20 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: # -Long: progress-bar -Help: Display transfer progress as a bar -Category: verbose -Example: -# -O $URL -Added: 5.10 -See-also: styled-output -Multi: boolean -Scope: global ---- -Make curl display transfer progress as a simple progress bar instead of the -standard, more informational, meter. - -This progress bar draws a single line of '#' characters across the screen and -shows a percentage if the transfer size is known. For transfers without a -known size, there is a space ship (-=o=-) that moves back and forth but only -while data is being transferred, with a set of flying hash sign symbols on -top. diff --git a/docs/cmdline-opts/progress-bar.md b/docs/cmdline-opts/progress-bar.md new file mode 100644 index 00000000000..7b9c599b985 --- /dev/null +++ b/docs/cmdline-opts/progress-bar.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: # +Long: progress-bar +Help: Display transfer progress as a bar +Category: verbose +Added: 5.10 +Multi: boolean +Scope: global +See-also: + - styled-output +Example: + - -# -O $URL +--- + +# `--progress-bar` + +Make curl display transfer progress as a simple progress bar instead of the +standard, more informational, meter. + +This progress bar draws a single line of '#' characters across the screen and +shows a percentage if the transfer size is known. For transfers without a +known size, there is a space ship (-=o=-) that moves back and forth but only +while data is being transferred, with a set of flying hash sign symbols on +top. diff --git a/docs/cmdline-opts/proto-default.d b/docs/cmdline-opts/proto-default.d deleted file mode 100644 index d5b4bcd10d5..00000000000 --- a/docs/cmdline-opts/proto-default.d +++ /dev/null @@ -1,20 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proto-default -Help: Use PROTOCOL for any URL missing a scheme -Arg: -Added: 7.45.0 -Category: connection curl -Example: --proto-default https ftp.example.com -See-also: proto proto-redir -Multi: single ---- -Tells curl to use *protocol* for any URL missing a scheme name. - -An unknown or unsupported protocol causes error -*CURLE_UNSUPPORTED_PROTOCOL* (1). - -This option does not change the default proxy protocol (http). - -Without this option set, curl guesses protocol based on the host name, see ---url for details. diff --git a/docs/cmdline-opts/proto-default.md b/docs/cmdline-opts/proto-default.md new file mode 100644 index 00000000000..209e5cdc83d --- /dev/null +++ b/docs/cmdline-opts/proto-default.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proto-default +Help: Use PROTOCOL for any URL missing a scheme +Arg: +Added: 7.45.0 +Category: connection curl +Multi: single +See-also: + - proto + - proto-redir +Example: + - --proto-default https ftp.example.com +--- + +# `--proto-default` + +Use *protocol* for any provided URL missing a scheme. + +An unknown or unsupported protocol causes error *CURLE_UNSUPPORTED_PROTOCOL*. + +This option does not change the default proxy protocol (http). + +Without this option set, curl guesses protocol based on the hostname, see +--url for details. diff --git a/docs/cmdline-opts/proto-redir.d b/docs/cmdline-opts/proto-redir.d deleted file mode 100644 index dec87161443..00000000000 --- a/docs/cmdline-opts/proto-redir.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proto-redir -Arg: -Help: Enable/disable PROTOCOLS on redirect -Added: 7.20.2 -Category: connection curl -Example: --proto-redir =http,https $URL -See-also: proto -Multi: single ---- -Tells curl to limit what protocols it may use on redirect. Protocols denied by ---proto are not overridden by this option. See --proto for how protocols are -represented. - -Example, allow only HTTP and HTTPS on redirect: - - curl --proto-redir -all,http,https http://example.com - -By default curl only allows HTTP, HTTPS, FTP and FTPS on redirects (added in -7.65.2). Specifying *all* or *+all* enables all protocols on redirects, which -is not good for security. diff --git a/docs/cmdline-opts/proto-redir.md b/docs/cmdline-opts/proto-redir.md new file mode 100644 index 00000000000..51fb7bd3a14 --- /dev/null +++ b/docs/cmdline-opts/proto-redir.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proto-redir +Arg: +Help: Enable/disable PROTOCOLS on redirect +Added: 7.20.2 +Category: connection curl +Multi: single +See-also: + - proto +Example: + - --proto-redir =http,https $URL +--- + +# `--proto-redir` + +Limit what protocols to allow on redirects. Protocols denied by --proto are +not overridden by this option. See --proto for how protocols are represented. + +Example, allow only HTTP and HTTPS on redirect: + + curl --proto-redir -all,http,https http://example.com + +By default curl only allows HTTP, HTTPS, FTP and FTPS on redirects (added in +7.65.2). Specifying *all* or *+all* enables all protocols on redirects, which +is not good for security. diff --git a/docs/cmdline-opts/proto.d b/docs/cmdline-opts/proto.d deleted file mode 100644 index ac024bf4289..00000000000 --- a/docs/cmdline-opts/proto.d +++ /dev/null @@ -1,48 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proto -Arg: -Help: Enable/disable PROTOCOLS -See-also: proto-redir proto-default -Added: 7.20.2 -Category: connection curl -Example: --proto =http,https,sftp $URL -Multi: single ---- -Tells curl to limit what protocols it may use for transfers. Protocols are -evaluated left to right, are comma separated, and are each a protocol name or -'all', optionally prefixed by zero or more modifiers. Available modifiers are: -.RS -.TP 3 -.B + -Permit this protocol in addition to protocols already permitted (this is -the default if no modifier is used). -.TP -.B - -Deny this protocol, removing it from the list of protocols already permitted. -.TP -.B = -Permit only this protocol (ignoring the list already permitted), though -subject to later modification by subsequent entries in the comma separated -list. -.RE -.IP -For example: -.RS -.TP 15 -.B --proto -ftps -uses the default protocols, but disables ftps -.TP -.B --proto -all,https,+http -only enables http and https -.TP -.B --proto =http,https -also only enables http and https -.RE -.IP -Unknown and disabled protocols produce a warning. This allows scripts to -safely rely on being able to disable potentially dangerous protocols, without -relying upon support for that protocol being built into curl to avoid an error. - -This option can be used multiple times, in which case the effect is the same -as concatenating the protocols into one instance of the option. diff --git a/docs/cmdline-opts/proto.md b/docs/cmdline-opts/proto.md new file mode 100644 index 00000000000..704c6493cd5 --- /dev/null +++ b/docs/cmdline-opts/proto.md @@ -0,0 +1,48 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proto +Arg: +Help: Enable/disable PROTOCOLS +Added: 7.20.2 +Category: connection curl +Multi: single +See-also: + - proto-redir + - proto-default +Example: + - --proto =http,https,sftp $URL +--- + +# `--proto` + +Limit what protocols to allow for transfers. Protocols are evaluated left to +right, are comma separated, and are each a protocol name or 'all', optionally +prefixed by zero or more modifiers. Available modifiers are: + +## + +Permit this protocol in addition to protocols already permitted (this is +the default if no modifier is used). + +## - +Deny this protocol, removing it from the list of protocols already permitted. + +## = +Permit only this protocol (ignoring the list already permitted), though +subject to later modification by subsequent entries in the comma separated +list. + +## + +For example: --proto -ftps uses the default protocols, but disables ftps + +--proto -all,https,+http only enables http and https + +--proto =http,https also only enables http and https + +Unknown and disabled protocols produce a warning. This allows scripts to +safely rely on being able to disable potentially dangerous protocols, without +relying upon support for that protocol being built into curl to avoid an error. + +This option can be used multiple times, in which case the effect is the same +as concatenating the protocols into one instance of the option. diff --git a/docs/cmdline-opts/proxy-anyauth.d b/docs/cmdline-opts/proxy-anyauth.d deleted file mode 100644 index fa460876ef8..00000000000 --- a/docs/cmdline-opts/proxy-anyauth.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-anyauth -Help: Pick any proxy authentication method -Added: 7.13.2 -See-also: proxy proxy-basic proxy-digest -Category: proxy auth -Example: --proxy-anyauth --proxy-user user:passwd -x proxy $URL -Multi: mutex ---- -Tells curl to pick a suitable authentication method when communicating with -the given HTTP proxy. This might cause an extra request/response round-trip. diff --git a/docs/cmdline-opts/proxy-anyauth.md b/docs/cmdline-opts/proxy-anyauth.md new file mode 100644 index 00000000000..78e67ee7ce7 --- /dev/null +++ b/docs/cmdline-opts/proxy-anyauth.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-anyauth +Help: Pick any proxy authentication method +Added: 7.13.2 +Category: proxy auth +Multi: mutex +See-also: + - proxy + - proxy-basic + - proxy-digest +Example: + - --proxy-anyauth --proxy-user user:passwd -x proxy $URL +--- + +# `--proxy-anyauth` + +Automatically pick a suitable authentication method when communicating with +the given HTTP proxy. This might cause an extra request/response round-trip. diff --git a/docs/cmdline-opts/proxy-basic.d b/docs/cmdline-opts/proxy-basic.d deleted file mode 100644 index ff56631f779..00000000000 --- a/docs/cmdline-opts/proxy-basic.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-basic -Help: Use Basic authentication on the proxy -See-also: proxy proxy-anyauth proxy-digest -Category: proxy auth -Example: --proxy-basic --proxy-user user:passwd -x proxy $URL -Added: 7.12.0 -Multi: mutex ---- -Tells curl to use HTTP Basic authentication when communicating with the given -proxy. Use --basic for enabling HTTP Basic with a remote host. Basic is the -default authentication method curl uses with proxies. diff --git a/docs/cmdline-opts/proxy-basic.md b/docs/cmdline-opts/proxy-basic.md new file mode 100644 index 00000000000..2fae3d5b957 --- /dev/null +++ b/docs/cmdline-opts/proxy-basic.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-basic +Help: Use Basic authentication on the proxy +Category: proxy auth +Added: 7.12.0 +Multi: mutex +See-also: + - proxy + - proxy-anyauth + - proxy-digest +Example: + - --proxy-basic --proxy-user user:passwd -x proxy $URL +--- + +# `--proxy-basic` + +Use HTTP Basic authentication when communicating with the given proxy. Use +--basic for enabling HTTP Basic with a remote host. Basic is the default +authentication method curl uses with proxies. diff --git a/docs/cmdline-opts/proxy-ca-native.d b/docs/cmdline-opts/proxy-ca-native.d deleted file mode 100644 index aab4fcabc2a..00000000000 --- a/docs/cmdline-opts/proxy-ca-native.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-ca-native -Help: Use CA certificates from the native OS for proxy -Protocols: TLS -Category: tls -See-also: cacert capath insecure -Example: --ca-native $URL -Added: 8.2.0 -Multi: boolean ---- -Tells curl to use the CA store from the native operating system to verify the -HTTPS proxy. By default, curl uses a CA store provided in a single file or -directory, but when using this option it interfaces the operating system's own -vault. - -This option only works for curl on Windows when built to use OpenSSL. When -curl on Windows is built to use Schannel, this feature is implied and curl -then only uses the native CA store. - -curl built with wolfSSL also supports this option (added in 8.3.0). diff --git a/docs/cmdline-opts/proxy-ca-native.md b/docs/cmdline-opts/proxy-ca-native.md new file mode 100644 index 00000000000..6158b6cf6f4 --- /dev/null +++ b/docs/cmdline-opts/proxy-ca-native.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-ca-native +Help: Load CA certs from the OS to verify proxy +Protocols: TLS +Category: tls +Added: 8.2.0 +Multi: boolean +See-also: + - cacert + - capath + - insecure +Example: + - --ca-native $URL +--- + +# `--proxy-ca-native` + +Use the CA store from the native operating system to verify the HTTPS proxy. +By default, curl uses a CA store provided in a single file or directory, but +when using this option it interfaces the operating system's own vault. + +This option works for curl on Windows when built to use OpenSSL, wolfSSL +(added in 8.3.0) or GnuTLS (added in 8.5.0). When curl on Windows is built to +use Schannel, this feature is implied and curl then only uses the native CA +store. diff --git a/docs/cmdline-opts/proxy-cacert.d b/docs/cmdline-opts/proxy-cacert.d deleted file mode 100644 index 45dc3f301be..00000000000 --- a/docs/cmdline-opts/proxy-cacert.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-cacert -Help: CA certificate to verify peer against for proxy -Arg: -Added: 7.52.0 -See-also: proxy-capath cacert capath proxy -Category: proxy tls -Example: --proxy-cacert CA-file.txt -x https://proxy $URL -Multi: single ---- -Same as --cacert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cacert.md b/docs/cmdline-opts/proxy-cacert.md new file mode 100644 index 00000000000..ec0dd9f1432 --- /dev/null +++ b/docs/cmdline-opts/proxy-cacert.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-cacert +Help: CA certificates to verify proxy against +Arg: +Added: 7.52.0 +Category: proxy tls +Multi: single +See-also: + - proxy-capath + - cacert + - capath + - proxy +Example: + - --proxy-cacert CA-file.txt -x https://proxy $URL +--- + +# `--proxy-cacert` + +Same as --cacert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-capath.d b/docs/cmdline-opts/proxy-capath.d deleted file mode 100644 index 309f9408a86..00000000000 --- a/docs/cmdline-opts/proxy-capath.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-capath -Help: CA directory to verify peer against for proxy -Arg: -Added: 7.52.0 -See-also: proxy-cacert proxy capath -Category: proxy tls -Example: --proxy-capath /local/directory -x https://proxy $URL -Multi: single ---- -Same as --capath but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-capath.md b/docs/cmdline-opts/proxy-capath.md new file mode 100644 index 00000000000..bc2c7b56f59 --- /dev/null +++ b/docs/cmdline-opts/proxy-capath.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-capath +Help: CA directory to verify proxy against +Arg: +Added: 7.52.0 +Category: proxy tls +Multi: single +See-also: + - proxy-cacert + - proxy + - capath +Example: + - --proxy-capath /local/directory -x https://proxy $URL +--- + +# `--proxy-capath` + +Same as --capath but used in HTTPS proxy context. + +Use the specified certificate directory to verify the proxy. Multiple paths +can be provided by separated with colon (`:`) (e.g. `path1:path2:path3`). The +certificates must be in PEM format, and if curl is built against OpenSSL, the +directory must have been processed using the c_rehash utility supplied with +OpenSSL. Using --proxy-capath can allow OpenSSL-powered curl to make +SSL-connections much more efficiently than using --proxy-cacert if the +--proxy-cacert file contains many CA certificates. + +If this option is set, the default capath value is ignored. diff --git a/docs/cmdline-opts/proxy-cert-type.d b/docs/cmdline-opts/proxy-cert-type.d deleted file mode 100644 index 4ab38f5a80b..00000000000 --- a/docs/cmdline-opts/proxy-cert-type.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-cert-type -Arg: -Added: 7.52.0 -Help: Client certificate type for HTTPS proxy -Category: proxy tls -Example: --proxy-cert-type PEM --proxy-cert file -x https://proxy $URL -See-also: proxy-cert -Multi: single ---- -Same as --cert-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cert-type.md b/docs/cmdline-opts/proxy-cert-type.md new file mode 100644 index 00000000000..3f46bb6181e --- /dev/null +++ b/docs/cmdline-opts/proxy-cert-type.md @@ -0,0 +1,18 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-cert-type +Arg: +Added: 7.52.0 +Help: Client certificate type for HTTPS proxy +Category: proxy tls +Multi: single +See-also: + - proxy-cert +Example: + - --proxy-cert-type PEM --proxy-cert file -x https://proxy $URL +--- + +# `--proxy-cert-type` + +Same as --cert-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cert.d b/docs/cmdline-opts/proxy-cert.d deleted file mode 100644 index 2a869deb028..00000000000 --- a/docs/cmdline-opts/proxy-cert.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-cert -Arg: -Help: Set client certificate for proxy -Added: 7.52.0 -Category: proxy tls -Example: --proxy-cert file -x https://proxy $URL -See-also: proxy-cert-type -Multi: single ---- -Same as --cert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cert.md b/docs/cmdline-opts/proxy-cert.md new file mode 100644 index 00000000000..3068f3cd105 --- /dev/null +++ b/docs/cmdline-opts/proxy-cert.md @@ -0,0 +1,18 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-cert +Arg: +Help: Set client certificate for proxy +Added: 7.52.0 +Category: proxy tls +Multi: single +See-also: + - proxy-cert-type +Example: + - --proxy-cert file -x https://proxy $URL +--- + +# `--proxy-cert` + +Same as --cert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-ciphers.d b/docs/cmdline-opts/proxy-ciphers.d deleted file mode 100644 index 5879f397e18..00000000000 --- a/docs/cmdline-opts/proxy-ciphers.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-ciphers -Arg: -Help: SSL ciphers to use for proxy -Added: 7.52.0 -Category: proxy tls -Example: --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy $URL -See-also: ciphers curves proxy -Multi: single ---- -Same as --ciphers but used in HTTPS proxy context. - -Specifies which ciphers to use in the connection to the HTTPS proxy. The list -of ciphers must specify valid ciphers. Read up on SSL cipher list details on -this URL: - -https://curl.se/docs/ssl-ciphers.html diff --git a/docs/cmdline-opts/proxy-ciphers.md b/docs/cmdline-opts/proxy-ciphers.md new file mode 100644 index 00000000000..065d4495306 --- /dev/null +++ b/docs/cmdline-opts/proxy-ciphers.md @@ -0,0 +1,26 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-ciphers +Arg: +Help: SSL ciphers to use for proxy +Added: 7.52.0 +Category: proxy tls +Multi: single +See-also: + - ciphers + - curves + - proxy +Example: + - --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy $URL +--- + +# `--proxy-ciphers` + +Same as --ciphers but used in HTTPS proxy context. + +Specifies which ciphers to use in the connection to the HTTPS proxy. The list +of ciphers must specify valid ciphers. Read up on SSL cipher list details on +this URL: + +https://curl.se/docs/ssl-ciphers.html diff --git a/docs/cmdline-opts/proxy-crlfile.d b/docs/cmdline-opts/proxy-crlfile.d deleted file mode 100644 index 1a8fdf25dac..00000000000 --- a/docs/cmdline-opts/proxy-crlfile.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-crlfile -Arg: -Help: Set a CRL list for proxy -Added: 7.52.0 -Category: proxy tls -Example: --proxy-crlfile rejects.txt -x https://proxy $URL -See-also: crlfile proxy -Multi: single ---- -Same as --crlfile but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-crlfile.md b/docs/cmdline-opts/proxy-crlfile.md new file mode 100644 index 00000000000..ab47fb0a0d1 --- /dev/null +++ b/docs/cmdline-opts/proxy-crlfile.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-crlfile +Arg: +Help: Set a CRL list for proxy +Added: 7.52.0 +Category: proxy tls +Multi: single +See-also: + - crlfile + - proxy +Example: + - --proxy-crlfile rejects.txt -x https://proxy $URL +--- + +# `--proxy-crlfile` + +Same as --crlfile but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-digest.d b/docs/cmdline-opts/proxy-digest.d deleted file mode 100644 index c5cb19c48b8..00000000000 --- a/docs/cmdline-opts/proxy-digest.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-digest -Help: Use Digest authentication on the proxy -See-also: proxy proxy-anyauth proxy-basic -Category: proxy tls -Example: --proxy-digest --proxy-user user:passwd -x proxy $URL -Added: 7.12.0 -Multi: mutex ---- -Tells curl to use HTTP Digest authentication when communicating with the given -proxy. Use --digest for enabling HTTP Digest with a remote host. diff --git a/docs/cmdline-opts/proxy-digest.md b/docs/cmdline-opts/proxy-digest.md new file mode 100644 index 00000000000..77b88d7e4bd --- /dev/null +++ b/docs/cmdline-opts/proxy-digest.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-digest +Help: Digest auth with the proxy +Category: proxy tls +Added: 7.12.0 +Multi: mutex +See-also: + - proxy + - proxy-anyauth + - proxy-basic +Example: + - --proxy-digest --proxy-user user:passwd -x proxy $URL +--- + +# `--proxy-digest` + +Use HTTP Digest authentication when communicating with the given proxy. Use +--digest for enabling HTTP Digest with a remote host. diff --git a/docs/cmdline-opts/proxy-header.d b/docs/cmdline-opts/proxy-header.d deleted file mode 100644 index 06ae3bcbaa2..00000000000 --- a/docs/cmdline-opts/proxy-header.d +++ /dev/null @@ -1,32 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-header -Arg:
-Help: Pass custom header(s) to proxy -Protocols: HTTP -Added: 7.37.0 -Category: proxy -Example: --proxy-header "X-First-Name: Joe" -x http://proxy $URL -Example: --proxy-header "User-Agent: surprise" -x http://proxy $URL -Example: --proxy-header "Host:" -x http://proxy $URL -See-also: proxy -Multi: append ---- -Extra header to include in the request when sending HTTP to a proxy. You may -specify any number of extra headers. This is the equivalent option to --header -but is for proxy communication only like in CONNECT requests when you want a -separate header sent to the proxy to what is sent to the actual remote host. - -curl makes sure that each header you add/replace is sent with the proper -end-of-line marker, you should thus **not** add that as a part of the header -content: do not add newlines or carriage returns, they only mess things up for -you. - -Headers specified with this option are not included in requests that curl -knows are not be sent to a proxy. - -This option can take an argument in @filename style, which then adds a header -for each line in the input file (added in 7.55.0). Using @- makes curl read -the headers from stdin. - -This option can be used multiple times to add/replace/remove multiple headers. diff --git a/docs/cmdline-opts/proxy-header.md b/docs/cmdline-opts/proxy-header.md new file mode 100644 index 00000000000..0361fdff578 --- /dev/null +++ b/docs/cmdline-opts/proxy-header.md @@ -0,0 +1,38 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-header +Arg:
+Help: Pass custom header(s) to proxy +Protocols: HTTP +Added: 7.37.0 +Category: proxy +Multi: append +See-also: + - proxy +Example: + - --proxy-header "X-First-Name: Joe" -x http://proxy $URL + - --proxy-header "User-Agent: surprise" -x http://proxy $URL + - --proxy-header "Host:" -x http://proxy $URL +--- + +# `--proxy-header` + +Extra header to include in the request when sending HTTP to a proxy. You may +specify any number of extra headers. This is the equivalent option to --header +but is for proxy communication only like in CONNECT requests when you want a +separate header sent to the proxy to what is sent to the actual remote host. + +curl makes sure that each header you add/replace is sent with the proper +end-of-line marker, you should thus **not** add that as a part of the header +content: do not add newlines or carriage returns, they only mess things up for +you. + +Headers specified with this option are not included in requests that curl +knows are not be sent to a proxy. + +This option can take an argument in @filename style, which then adds a header +for each line in the input file (added in 7.55.0). Using @- makes curl read +the headers from stdin. + +This option can be used multiple times to add/replace/remove multiple headers. diff --git a/docs/cmdline-opts/proxy-http2.d b/docs/cmdline-opts/proxy-http2.d deleted file mode 100644 index 58f55e74ddd..00000000000 --- a/docs/cmdline-opts/proxy-http2.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-http2 -Tags: Versions HTTP/2 -Protocols: HTTP -Added: 8.1.0 -Mutexed: -Requires: HTTP/2 -See-also: proxy -Help: Use HTTP/2 with HTTPS proxy -Category: http proxy -Example: --proxy-http2 -x proxy $URL -Multi: boolean ---- -Tells curl to try negotiate HTTP version 2 with an HTTPS proxy. The proxy might -still only offer HTTP/1 and then curl sticks to using that version. - -This has no effect for any other kinds of proxies. diff --git a/docs/cmdline-opts/proxy-http2.md b/docs/cmdline-opts/proxy-http2.md new file mode 100644 index 00000000000..ca6a091f328 --- /dev/null +++ b/docs/cmdline-opts/proxy-http2.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-http2 +Tags: Versions HTTP/2 +Protocols: HTTP +Added: 8.1.0 +Mutexed: +Requires: HTTP/2 +Help: Use HTTP/2 with HTTPS proxy +Category: http proxy +Multi: boolean +See-also: + - proxy +Example: + - --proxy-http2 -x proxy $URL +--- + +# `--proxy-http2` + +Negotiate HTTP/2 with an HTTPS proxy. The proxy might still only offer HTTP/1 +and then curl sticks to using that version. + +This has no effect for any other kinds of proxies. diff --git a/docs/cmdline-opts/proxy-insecure.d b/docs/cmdline-opts/proxy-insecure.d deleted file mode 100644 index beb8c25317a..00000000000 --- a/docs/cmdline-opts/proxy-insecure.d +++ /dev/null @@ -1,11 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-insecure -Help: Do HTTPS proxy connections without verifying the proxy -Added: 7.52.0 -Category: proxy tls -Example: --proxy-insecure -x https://proxy $URL -See-also: proxy insecure -Multi: boolean ---- -Same as --insecure but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-insecure.md b/docs/cmdline-opts/proxy-insecure.md new file mode 100644 index 00000000000..5796c36237d --- /dev/null +++ b/docs/cmdline-opts/proxy-insecure.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-insecure +Help: Skip HTTPS proxy cert verification +Added: 7.52.0 +Category: proxy tls +Multi: boolean +See-also: + - proxy + - insecure +Example: + - --proxy-insecure -x https://proxy $URL +--- + +# `--proxy-insecure` + +Same as --insecure but used in HTTPS proxy context. + +Every secure connection curl makes is verified to be secure before the +transfer takes place. This option makes curl skip the verification step with a +proxy and proceed without checking. + +When this option is not used for a proxy using HTTPS, curl verifies the +proxy's TLS certificate before it continues: that the certificate contains the +right name which matches the hostname and that the certificate has been signed +by a CA certificate present in the cert store. See this online resource for +further details: **https://curl.se/docs/sslcerts.html** + +**WARNING**: using this option makes the transfer to the proxy insecure. diff --git a/docs/cmdline-opts/proxy-key-type.d b/docs/cmdline-opts/proxy-key-type.d deleted file mode 100644 index 3fd11f3a321..00000000000 --- a/docs/cmdline-opts/proxy-key-type.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-key-type -Arg: -Help: Private key file type for proxy -Added: 7.52.0 -Category: proxy tls -Example: --proxy-key-type DER --proxy-key here -x https://proxy $URL -See-also: proxy-key proxy -Multi: single ---- -Same as --key-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-key-type.md b/docs/cmdline-opts/proxy-key-type.md new file mode 100644 index 00000000000..8740935b56c --- /dev/null +++ b/docs/cmdline-opts/proxy-key-type.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-key-type +Arg: +Help: Private key file type for proxy +Added: 7.52.0 +Category: proxy tls +Multi: single +See-also: + - proxy-key + - proxy +Example: + - --proxy-key-type DER --proxy-key here -x https://proxy $URL +--- + +# `--proxy-key-type` + +Same as --key-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-key.d b/docs/cmdline-opts/proxy-key.d deleted file mode 100644 index 4bf2748a4e1..00000000000 --- a/docs/cmdline-opts/proxy-key.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-key -Help: Private key for HTTPS proxy -Arg: -Category: proxy tls -Example: --proxy-key here -x https://proxy $URL -Added: 7.52.0 -See-also: proxy-key-type proxy -Multi: single ---- -Same as --key but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-key.md b/docs/cmdline-opts/proxy-key.md new file mode 100644 index 00000000000..cfe507845ea --- /dev/null +++ b/docs/cmdline-opts/proxy-key.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-key +Help: Private key for HTTPS proxy +Arg: +Category: proxy tls +Added: 7.52.0 +Multi: single +See-also: + - proxy-key-type + - proxy +Example: + - --proxy-key here -x https://proxy $URL +--- + +# `--proxy-key` + +Same as --key but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-negotiate.d b/docs/cmdline-opts/proxy-negotiate.d deleted file mode 100644 index 89b5c1bde37..00000000000 --- a/docs/cmdline-opts/proxy-negotiate.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-negotiate -Help: Use HTTP Negotiate (SPNEGO) authentication on the proxy -Added: 7.17.1 -See-also: proxy-anyauth proxy-basic -Category: proxy auth -Example: --proxy-negotiate --proxy-user user:passwd -x proxy $URL -Multi: mutex ---- -Tells curl to use HTTP Negotiate (SPNEGO) authentication when communicating -with the given proxy. Use --negotiate for enabling HTTP Negotiate (SPNEGO) -with a remote host. diff --git a/docs/cmdline-opts/proxy-negotiate.md b/docs/cmdline-opts/proxy-negotiate.md new file mode 100644 index 00000000000..9bedf5dc4aa --- /dev/null +++ b/docs/cmdline-opts/proxy-negotiate.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-negotiate +Help: HTTP Negotiate (SPNEGO) auth with the proxy +Added: 7.17.1 +Category: proxy auth +Multi: mutex +See-also: + - proxy-anyauth + - proxy-basic +Example: + - --proxy-negotiate --proxy-user user:passwd -x proxy $URL +--- + +# `--proxy-negotiate` + +Use HTTP Negotiate (SPNEGO) authentication when communicating with the given +proxy. Use --negotiate for enabling HTTP Negotiate (SPNEGO) with a remote +host. diff --git a/docs/cmdline-opts/proxy-ntlm.d b/docs/cmdline-opts/proxy-ntlm.d deleted file mode 100644 index f8481e5d6dc..00000000000 --- a/docs/cmdline-opts/proxy-ntlm.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-ntlm -Help: Use NTLM authentication on the proxy -See-also: proxy-negotiate proxy-anyauth -Category: proxy auth -Example: --proxy-ntlm --proxy-user user:passwd -x http://proxy $URL -Added: 7.10.7 -Multi: mutex ---- -Tells curl to use HTTP NTLM authentication when communicating with the given -proxy. Use --ntlm for enabling NTLM with a remote host. diff --git a/docs/cmdline-opts/proxy-ntlm.md b/docs/cmdline-opts/proxy-ntlm.md new file mode 100644 index 00000000000..f8375a620e5 --- /dev/null +++ b/docs/cmdline-opts/proxy-ntlm.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-ntlm +Help: NTLM authentication with the proxy +Category: proxy auth +Added: 7.10.7 +Multi: mutex +See-also: + - proxy-negotiate + - proxy-anyauth +Example: + - --proxy-ntlm --proxy-user user:passwd -x http://proxy $URL +--- + +# `--proxy-ntlm` + +Use HTTP NTLM authentication when communicating with the given proxy. Use +--ntlm for enabling NTLM with a remote host. diff --git a/docs/cmdline-opts/proxy-pass.d b/docs/cmdline-opts/proxy-pass.d deleted file mode 100644 index 30713995191..00000000000 --- a/docs/cmdline-opts/proxy-pass.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-pass -Arg: -Help: Pass phrase for the private key for HTTPS proxy -Added: 7.52.0 -Category: proxy tls auth -Example: --proxy-pass secret --proxy-key here -x https://proxy $URL -See-also: proxy proxy-key -Multi: single ---- -Same as --pass but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-pass.md b/docs/cmdline-opts/proxy-pass.md new file mode 100644 index 00000000000..feba6e0838e --- /dev/null +++ b/docs/cmdline-opts/proxy-pass.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-pass +Arg: +Help: Pass phrase for the private key for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Multi: single +See-also: + - proxy + - proxy-key +Example: + - --proxy-pass secret --proxy-key here -x https://proxy $URL +--- + +# `--proxy-pass` + +Same as --pass but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-pinnedpubkey.d b/docs/cmdline-opts/proxy-pinnedpubkey.d deleted file mode 100644 index 7bf99d8c5b6..00000000000 --- a/docs/cmdline-opts/proxy-pinnedpubkey.d +++ /dev/null @@ -1,22 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-pinnedpubkey -Arg: -Help: FILE/HASHES public key to verify proxy with -Protocols: TLS -Category: proxy tls -Example: --proxy-pinnedpubkey keyfile $URL -Example: --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' $URL -Added: 7.59.0 -See-also: pinnedpubkey proxy -Multi: single ---- -Tells curl to use the specified public key file (or hashes) to verify the -proxy. This can be a path to a file which contains a single public key in PEM -or DER format, or any number of base64 encoded sha256 hashes preceded by -'sha256//' and separated by ';'. - -When negotiating a TLS or SSL connection, the server sends a certificate -indicating its identity. A public key is extracted from this certificate and -if it does not exactly match the public key provided to this option, curl -aborts the connection before sending or receiving any data. diff --git a/docs/cmdline-opts/proxy-pinnedpubkey.md b/docs/cmdline-opts/proxy-pinnedpubkey.md new file mode 100644 index 00000000000..6f0b52d3e6d --- /dev/null +++ b/docs/cmdline-opts/proxy-pinnedpubkey.md @@ -0,0 +1,29 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-pinnedpubkey +Arg: +Help: FILE/HASHES public key to verify proxy with +Protocols: TLS +Category: proxy tls +Added: 7.59.0 +Multi: single +See-also: + - pinnedpubkey + - proxy +Example: + - --proxy-pinnedpubkey keyfile $URL + - --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' $URL +--- + +# `--proxy-pinnedpubkey` + +Use the specified public key file (or hashes) to verify the proxy. This can be +a path to a file which contains a single public key in PEM or DER format, or +any number of base64 encoded sha256 hashes preceded by 'sha256//' and +separated by ';'. + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. A public key is extracted from this certificate and +if it does not exactly match the public key provided to this option, curl +aborts the connection before sending or receiving any data. diff --git a/docs/cmdline-opts/proxy-service-name.d b/docs/cmdline-opts/proxy-service-name.d deleted file mode 100644 index 200973fb523..00000000000 --- a/docs/cmdline-opts/proxy-service-name.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-service-name -Arg: -Help: SPNEGO proxy service name -Added: 7.43.0 -Category: proxy tls -Example: --proxy-service-name "shrubbery" -x proxy $URL -See-also: service-name proxy -Multi: single ---- -This option allows you to change the service name for proxy negotiation. diff --git a/docs/cmdline-opts/proxy-service-name.md b/docs/cmdline-opts/proxy-service-name.md new file mode 100644 index 00000000000..534222f449e --- /dev/null +++ b/docs/cmdline-opts/proxy-service-name.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-service-name +Arg: +Help: SPNEGO proxy service name +Added: 7.43.0 +Category: proxy tls +Multi: single +See-also: + - service-name + - proxy +Example: + - --proxy-service-name "shrubbery" -x proxy $URL +--- + +# `--proxy-service-name` + +Set the service name for proxy negotiation. diff --git a/docs/cmdline-opts/proxy-ssl-allow-beast.d b/docs/cmdline-opts/proxy-ssl-allow-beast.d deleted file mode 100644 index 55ff62b46ea..00000000000 --- a/docs/cmdline-opts/proxy-ssl-allow-beast.d +++ /dev/null @@ -1,11 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-ssl-allow-beast -Help: Allow security flaw for interop for HTTPS proxy -Added: 7.52.0 -Category: proxy tls -Example: --proxy-ssl-allow-beast -x https://proxy $URL -See-also: ssl-allow-beast proxy -Multi: boolean ---- -Same as --ssl-allow-beast but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-ssl-allow-beast.md b/docs/cmdline-opts/proxy-ssl-allow-beast.md new file mode 100644 index 00000000000..f2deedbb550 --- /dev/null +++ b/docs/cmdline-opts/proxy-ssl-allow-beast.md @@ -0,0 +1,18 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-ssl-allow-beast +Help: Allow security flaw for interop for HTTPS proxy +Added: 7.52.0 +Category: proxy tls +Multi: boolean +See-also: + - ssl-allow-beast + - proxy +Example: + - --proxy-ssl-allow-beast -x https://proxy $URL +--- + +# `--proxy-ssl-allow-beast` + +Same as --ssl-allow-beast but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-ssl-auto-client-cert.d b/docs/cmdline-opts/proxy-ssl-auto-client-cert.d deleted file mode 100644 index ea0f0c04dd7..00000000000 --- a/docs/cmdline-opts/proxy-ssl-auto-client-cert.d +++ /dev/null @@ -1,11 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-ssl-auto-client-cert -Help: Use auto client certificate for proxy (Schannel) -Added: 7.77.0 -Category: proxy tls -Example: --proxy-ssl-auto-client-cert -x https://proxy $URL -See-also: ssl-auto-client-cert proxy -Multi: boolean ---- -Same as --ssl-auto-client-cert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-ssl-auto-client-cert.md b/docs/cmdline-opts/proxy-ssl-auto-client-cert.md new file mode 100644 index 00000000000..578a7a6417c --- /dev/null +++ b/docs/cmdline-opts/proxy-ssl-auto-client-cert.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-ssl-auto-client-cert +Help: Auto client certificate for proxy +Added: 7.77.0 +Category: proxy tls +Multi: boolean +See-also: + - ssl-auto-client-cert + - proxy +Example: + - --proxy-ssl-auto-client-cert -x https://proxy $URL +--- + +# `--proxy-ssl-auto-client-cert` + +Same as --ssl-auto-client-cert but used in HTTPS proxy context. + +This is only supported by Schannel. diff --git a/docs/cmdline-opts/proxy-tls13-ciphers.d b/docs/cmdline-opts/proxy-tls13-ciphers.d deleted file mode 100644 index f18c3d5c0cb..00000000000 --- a/docs/cmdline-opts/proxy-tls13-ciphers.d +++ /dev/null @@ -1,21 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-tls13-ciphers -Arg: -help: TLS 1.3 proxy cipher suites -Protocols: TLS -Category: proxy tls -Example: --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy $URL -Added: 7.61.0 -See-also: tls13-ciphers curves proxy-ciphers -Multi: single ---- -Specifies which cipher suites to use in the connection to your HTTPS proxy -when it negotiates TLS 1.3. The list of ciphers suites must specify valid -ciphers. Read up on TLS 1.3 cipher suite details on this URL: - -https://curl.se/docs/ssl-ciphers.html - -This option is currently used only when curl is built to use OpenSSL 1.1.1 or -later. If you are using a different SSL backend you can try setting TLS 1.3 -cipher suites by using the --proxy-ciphers option. diff --git a/docs/cmdline-opts/proxy-tls13-ciphers.md b/docs/cmdline-opts/proxy-tls13-ciphers.md new file mode 100644 index 00000000000..002fd0b0f4c --- /dev/null +++ b/docs/cmdline-opts/proxy-tls13-ciphers.md @@ -0,0 +1,29 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-tls13-ciphers +Arg: +help: TLS 1.3 proxy cipher suites +Protocols: TLS +Category: proxy tls +Added: 7.61.0 +Multi: single +See-also: + - tls13-ciphers + - curves + - proxy-ciphers +Example: + - --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy $URL +--- + +# `--proxy-tls13-ciphers` + +Specify which cipher suites to use in the connection to your HTTPS proxy when +it negotiates TLS 1.3. The list of ciphers suites must specify valid ciphers. +Read up on TLS 1.3 cipher suite details on this URL: + +https://curl.se/docs/ssl-ciphers.html + +This option is currently used only when curl is built to use OpenSSL 1.1.1 or +later. If you are using a different SSL backend you can try setting TLS 1.3 +cipher suites by using the --proxy-ciphers option. diff --git a/docs/cmdline-opts/proxy-tlsauthtype.d b/docs/cmdline-opts/proxy-tlsauthtype.d deleted file mode 100644 index f83153e7bae..00000000000 --- a/docs/cmdline-opts/proxy-tlsauthtype.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-tlsauthtype -Arg: -Help: TLS authentication type for HTTPS proxy -Added: 7.52.0 -Category: proxy tls auth -Example: --proxy-tlsauthtype SRP -x https://proxy $URL -See-also: proxy proxy-tlsuser -Multi: single ---- -Same as --tlsauthtype but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsauthtype.md b/docs/cmdline-opts/proxy-tlsauthtype.md new file mode 100644 index 00000000000..067e4c59888 --- /dev/null +++ b/docs/cmdline-opts/proxy-tlsauthtype.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-tlsauthtype +Arg: +Help: TLS authentication type for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Multi: single +See-also: + - proxy + - proxy-tlsuser +Example: + - --proxy-tlsauthtype SRP -x https://proxy $URL +--- + +# `--proxy-tlsauthtype` + +Same as --tlsauthtype but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlspassword.d b/docs/cmdline-opts/proxy-tlspassword.d deleted file mode 100644 index 7ec01401be8..00000000000 --- a/docs/cmdline-opts/proxy-tlspassword.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-tlspassword -Arg: -Help: TLS password for HTTPS proxy -Added: 7.52.0 -Category: proxy tls auth -Example: --proxy-tlspassword passwd -x https://proxy $URL -See-also: proxy proxy-tlsuser -Multi: single ---- -Same as --tlspassword but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlspassword.md b/docs/cmdline-opts/proxy-tlspassword.md new file mode 100644 index 00000000000..3c6d06c6a5e --- /dev/null +++ b/docs/cmdline-opts/proxy-tlspassword.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-tlspassword +Arg: +Help: TLS password for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Multi: single +See-also: + - proxy + - proxy-tlsuser +Example: + - --proxy-tlspassword passwd -x https://proxy $URL +--- + +# `--proxy-tlspassword` + +Same as --tlspassword but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsuser.d b/docs/cmdline-opts/proxy-tlsuser.d deleted file mode 100644 index 17be7f7bae1..00000000000 --- a/docs/cmdline-opts/proxy-tlsuser.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-tlsuser -Arg: -Help: TLS username for HTTPS proxy -Added: 7.52.0 -Category: proxy tls auth -Example: --proxy-tlsuser smith -x https://proxy $URL -See-also: proxy proxy-tlspassword -Multi: single ---- -Same as --tlsuser but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsuser.md b/docs/cmdline-opts/proxy-tlsuser.md new file mode 100644 index 00000000000..1c626ee754a --- /dev/null +++ b/docs/cmdline-opts/proxy-tlsuser.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-tlsuser +Arg: +Help: TLS username for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Multi: single +See-also: + - proxy + - proxy-tlspassword +Example: + - --proxy-tlsuser smith -x https://proxy $URL +--- + +# `--proxy-tlsuser` + +Same as --tlsuser but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsv1.d b/docs/cmdline-opts/proxy-tlsv1.d deleted file mode 100644 index c4345023eff..00000000000 --- a/docs/cmdline-opts/proxy-tlsv1.d +++ /dev/null @@ -1,11 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-tlsv1 -Help: Use TLSv1 for HTTPS proxy -Added: 7.52.0 -Category: proxy tls auth -Example: --proxy-tlsv1 -x https://proxy $URL -See-also: proxy -Multi: mutex ---- -Same as --tlsv1 but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsv1.md b/docs/cmdline-opts/proxy-tlsv1.md new file mode 100644 index 00000000000..0dda72f4b69 --- /dev/null +++ b/docs/cmdline-opts/proxy-tlsv1.md @@ -0,0 +1,17 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-tlsv1 +Help: TLSv1 for HTTPS proxy +Added: 7.52.0 +Category: proxy tls auth +Multi: mutex +See-also: + - proxy +Example: + - --proxy-tlsv1 -x https://proxy $URL +--- + +# `--proxy-tlsv1` + +Same as --tlsv1 but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-user.d b/docs/cmdline-opts/proxy-user.d deleted file mode 100644 index df30de2d92a..00000000000 --- a/docs/cmdline-opts/proxy-user.d +++ /dev/null @@ -1,23 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy-user -Short: U -Arg: -Help: Proxy user and password -Category: proxy auth -Example: --proxy-user name:pwd -x proxy $URL -Added: 4.0 -See-also: proxy-pass -Multi: single ---- -Specify the user name and password to use for proxy authentication. - -If you use a Windows SSPI-enabled curl binary and do either Negotiate or NTLM -authentication then you can tell curl to select the user name and password -from your environment by specifying a single colon with this option: "-U :". - -On systems where it works, curl hides the given option argument from process -listings. This is not enough to protect credentials from possibly getting seen -by other users on the same system as they still are visible for a moment -before cleared. Such sensitive data should be retrieved from a file instead or -similar and never used in clear text in a command line. diff --git a/docs/cmdline-opts/proxy-user.md b/docs/cmdline-opts/proxy-user.md new file mode 100644 index 00000000000..8ba19322006 --- /dev/null +++ b/docs/cmdline-opts/proxy-user.md @@ -0,0 +1,29 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy-user +Short: U +Arg: +Help: Proxy user and password +Category: proxy auth +Added: 4.0 +Multi: single +See-also: + - proxy-pass +Example: + - --proxy-user smith:secret -x proxy $URL +--- + +# `--proxy-user` + +Specify the username and password to use for proxy authentication. + +If you use a Windows SSPI-enabled curl binary and do either Negotiate or NTLM +authentication then you can tell curl to select the username and password from +your environment by specifying a single colon with this option: "-U :". + +On systems where it works, curl hides the given option argument from process +listings. This is not enough to protect credentials from possibly getting seen +by other users on the same system as they still are visible for a moment +before cleared. Such sensitive data should be retrieved from a file instead or +similar and never used in clear text in a command line. diff --git a/docs/cmdline-opts/proxy.d b/docs/cmdline-opts/proxy.d deleted file mode 100644 index b7d550a1103..00000000000 --- a/docs/cmdline-opts/proxy.d +++ /dev/null @@ -1,51 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy -Short: x -Arg: [protocol://]host[:port] -Help: Use this proxy -Category: proxy -Example: --proxy http://proxy.example $URL -Added: 4.0 -See-also: socks5 proxy-basic -Multi: single ---- -Use the specified proxy. - -The proxy string can be specified with a protocol:// prefix. No protocol -specified or http:// it is treated as an HTTP proxy. Use socks4://, -socks4a://, socks5:// or socks5h:// to request a specific SOCKS version to be -used. (Added in 7.21.7) - -Unix domain sockets are supported for socks proxy. Set localhost for the host -part. e.g. socks5h://localhost/path/to/socket.sock - -HTTPS proxy support works set with the https:// protocol prefix for OpenSSL -and GnuTLS (added in 7.52.0). It also works for BearSSL, mbedTLS, rustls, -Schannel, Secure Transport and wolfSSL (added in 7.87.0). - -Unrecognized and unsupported proxy protocols cause an error (added in 7.52.0). -Ancient curl versions ignored unknown schemes and used http:// instead. - -If the port number is not specified in the proxy string, it is assumed to be -1080. - -This option overrides existing environment variables that set the proxy to -use. If there is an environment variable setting a proxy, you can set proxy to -"" to override it. - -All operations that are performed over an HTTP proxy are transparently -converted to HTTP. It means that certain protocol specific operations might -not be available. This is not the case if you can tunnel through the proxy, as -one with the --proxytunnel option. - -User and password that might be provided in the proxy string are URL decoded -by curl. This allows you to pass in special characters such as @ by using %40 -or pass in a colon with %3a. - -The proxy host can be specified the same way as the proxy environment -variables, including the protocol prefix (http://) and the embedded user + -password. - -When a proxy is used, the active FTP mode as set with --ftp-port, cannot be -used. diff --git a/docs/cmdline-opts/proxy.md b/docs/cmdline-opts/proxy.md new file mode 100644 index 00000000000..51f638c67bd --- /dev/null +++ b/docs/cmdline-opts/proxy.md @@ -0,0 +1,58 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy +Short: x +Arg: [protocol://]host[:port] +Help: Use this proxy +Category: proxy +Added: 4.0 +Multi: single +See-also: + - socks5 + - proxy-basic +Example: + - --proxy http://proxy.example $URL +--- + +# `--proxy` + +Use the specified proxy. + +The proxy string can be specified with a protocol:// prefix. No protocol +specified or http:// it is treated as an HTTP proxy. Use socks4://, +socks4a://, socks5:// or socks5h:// to request a specific SOCKS version to be +used. (Added in 7.21.7) + +Unix domain sockets are supported for socks proxy. Set localhost for the host +part. e.g. socks5h://localhost/path/to/socket.sock + +HTTPS proxy support works set with the https:// protocol prefix for OpenSSL +and GnuTLS (added in 7.52.0). It also works for BearSSL, mbedTLS, rustls, +Schannel, Secure Transport and wolfSSL (added in 7.87.0). + +Unrecognized and unsupported proxy protocols cause an error (added in 7.52.0). +Ancient curl versions ignored unknown schemes and used http:// instead. + +If the port number is not specified in the proxy string, it is assumed to be +1080. + +This option overrides existing environment variables that set the proxy to +use. If there is an environment variable setting a proxy, you can set proxy to +"" to override it. + +All operations that are performed over an HTTP proxy are transparently +converted to HTTP. It means that certain protocol specific operations might +not be available. This is not the case if you can tunnel through the proxy, as +one with the --proxytunnel option. + +User and password that might be provided in the proxy string are URL decoded +by curl. This allows you to pass in special characters such as @ by using %40 +or pass in a colon with %3a. + +The proxy host can be specified the same way as the proxy environment +variables, including the protocol prefix (http://) and the embedded user + +password. + +When a proxy is used, the active FTP mode as set with --ftp-port, cannot be +used. diff --git a/docs/cmdline-opts/proxy1.0.d b/docs/cmdline-opts/proxy1.0.d deleted file mode 100644 index 0657a9519dd..00000000000 --- a/docs/cmdline-opts/proxy1.0.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxy1.0 -Arg: -Help: Use HTTP/1.0 proxy on given port -Category: proxy -Example: --proxy1.0 -x http://proxy $URL -Added: 7.19.4 -See-also: proxy socks5 preproxy -Multi: mutex ---- -Use the specified HTTP 1.0 proxy. If the port number is not specified, it is -assumed at port 1080. - -The only difference between this and the HTTP proxy option --proxy, is that -attempts to use CONNECT through the proxy specifies an HTTP 1.0 protocol -instead of the default HTTP 1.1. diff --git a/docs/cmdline-opts/proxy1.0.md b/docs/cmdline-opts/proxy1.0.md new file mode 100644 index 00000000000..4d3203a0325 --- /dev/null +++ b/docs/cmdline-opts/proxy1.0.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxy1.0 +Arg: +Help: Use HTTP/1.0 proxy on given port +Category: proxy +Added: 7.19.4 +Multi: mutex +See-also: + - proxy + - socks5 + - preproxy +Example: + - --proxy1.0 http://proxy $URL +--- + +# `--proxy1.0` + +Use the specified HTTP 1.0 proxy. If the port number is not specified, it is +assumed at port 1080. + +The only difference between this and the HTTP proxy option --proxy, is that +attempts to use CONNECT through the proxy specifies an HTTP 1.0 protocol +instead of the default HTTP 1.1. diff --git a/docs/cmdline-opts/proxytunnel.d b/docs/cmdline-opts/proxytunnel.d deleted file mode 100644 index 51457870b26..00000000000 --- a/docs/cmdline-opts/proxytunnel.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: proxytunnel -Short: p -Help: Operate through an HTTP proxy tunnel (using CONNECT) -See-also: proxy -Category: proxy -Example: --proxytunnel -x http://proxy $URL -Added: 7.3 -Multi: boolean ---- -When an HTTP proxy is used --proxy, this option makes curl tunnel the traffic -through the proxy. The tunnel approach is made with the HTTP proxy CONNECT -request and requires that the proxy allows direct connect to the remote port -number curl wants to tunnel through to. - -To suppress proxy CONNECT response headers when curl is set to output headers -use --suppress-connect-headers. diff --git a/docs/cmdline-opts/proxytunnel.md b/docs/cmdline-opts/proxytunnel.md new file mode 100644 index 00000000000..169d2ad8bc4 --- /dev/null +++ b/docs/cmdline-opts/proxytunnel.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: proxytunnel +Short: p +Help: HTTP proxy tunnel (using CONNECT) +Category: proxy +Added: 7.3 +Multi: boolean +See-also: + - proxy +Example: + - --proxytunnel -x http://proxy $URL +--- + +# `--proxytunnel` + +When an HTTP proxy is used --proxy, this option makes curl tunnel the traffic +through the proxy. The tunnel approach is made with the HTTP proxy CONNECT +request and requires that the proxy allows direct connect to the remote port +number curl wants to tunnel through to. + +To suppress proxy CONNECT response headers when curl is set to output headers +use --suppress-connect-headers. diff --git a/docs/cmdline-opts/pubkey.d b/docs/cmdline-opts/pubkey.d deleted file mode 100644 index b2f4b727b6b..00000000000 --- a/docs/cmdline-opts/pubkey.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: pubkey -Arg: -Protocols: SFTP SCP -Help: SSH Public key file name -Category: sftp scp auth -Example: --pubkey file.pub sftp://example.com/ -Added: 7.16.2 -See-also: pass -Multi: single ---- -Public key file name. Allows you to provide your public key in this separate -file. - -curl attempts to automatically extract the public key from the private key -file, so passing this option is generally not required. Note that this public -key extraction requires libcurl to be linked against a copy of libssh2 1.2.8 -or higher that is itself linked against OpenSSL. (Added in 7.39.0.) diff --git a/docs/cmdline-opts/pubkey.md b/docs/cmdline-opts/pubkey.md new file mode 100644 index 00000000000..94e50e4e94c --- /dev/null +++ b/docs/cmdline-opts/pubkey.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: pubkey +Arg: +Protocols: SFTP SCP +Help: SSH Public key filename +Category: sftp scp auth +Added: 7.16.2 +Multi: single +See-also: + - pass +Example: + - --pubkey file.pub sftp://example.com/ +--- + +# `--pubkey` + +Public key filename. Allows you to provide your public key in this separate +file. + +curl attempts to automatically extract the public key from the private key +file, so passing this option is generally not required. Note that this public +key extraction requires libcurl to be linked against a copy of libssh2 1.2.8 +or higher that is itself linked against OpenSSL. (Added in 7.39.0.) diff --git a/docs/cmdline-opts/quote.d b/docs/cmdline-opts/quote.d deleted file mode 100644 index 5008d49321d..00000000000 --- a/docs/cmdline-opts/quote.d +++ /dev/null @@ -1,87 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: quote -Arg: -Short: Q -Help: Send command(s) to server before transfer -Protocols: FTP SFTP -Category: ftp sftp -Example: --quote "DELE file" ftp://example.com/foo -Added: 5.3 -See-also: request -Multi: append ---- -Send an arbitrary command to the remote FTP or SFTP server. Quote commands are -sent BEFORE the transfer takes place (just after the initial **PWD** command -in an FTP transfer, to be exact). To make commands take place after a -successful transfer, prefix them with a dash '-'. - -(FTP only) To make commands be sent after curl has changed the working -directory, just before the file transfer command(s), prefix the command with a -'+'. This is not performed when a directory listing is performed. - -You may specify any number of commands. - -By default curl stops at first failure. To make curl continue even if the -command fails, prefix the command with an asterisk (*). Otherwise, if the -server returns failure for one of the commands, the entire operation is -aborted. - -You must send syntactically correct FTP commands as RFC 959 defines to FTP -servers, or one of the commands listed below to SFTP servers. - -SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands -itself before sending them to the server. File names may be quoted -shell-style to embed spaces or special characters. Following is the list of -all supported SFTP quote commands: -.RS -.TP -**"atime date file"** -The atime command sets the last access time of the file named by the file -operand. The can be all sorts of date strings, see the -*curl_getdate(3)* man page for date expression details. (Added in 7.73.0) -.TP -**"chgrp group file"** -The chgrp command sets the group ID of the file named by the file operand to -the group ID specified by the group operand. The group operand is a decimal -integer group ID. -.TP -**"chmod mode file"** -The chmod command modifies the file mode bits of the specified file. The -mode operand is an octal integer mode number. -.TP -**"chown user file"** -The chown command sets the owner of the file named by the file operand to the -user ID specified by the user operand. The user operand is a decimal -integer user ID. -.TP -**"ln source_file target_file"** -The ln and symlink commands create a symbolic link at the target_file location -pointing to the source_file location. -.TP -**"mkdir directory_name"** -The mkdir command creates the directory named by the directory_name operand. -.TP -**"mtime date file"** -The mtime command sets the last modification time of the file named by the -file operand. The can be all sorts of date strings, see the -*curl_getdate(3)* man page for date expression details. (Added in 7.73.0) -.TP -**"pwd"** -The pwd command returns the absolute path name of the current working directory. -.TP -**"rename source target"** -The rename command renames the file or directory named by the source -operand to the destination path named by the target operand. -.TP -**"rm file"** -The rm command removes the file specified by the file operand. -.TP -**"rmdir directory"** -The rmdir command removes the directory entry specified by the directory -operand, provided it is empty. -.TP -**"symlink source_file target_file"** -See ln. -.RE -.IP diff --git a/docs/cmdline-opts/quote.md b/docs/cmdline-opts/quote.md new file mode 100644 index 00000000000..4972c96f549 --- /dev/null +++ b/docs/cmdline-opts/quote.md @@ -0,0 +1,90 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: quote +Arg: +Short: Q +Help: Send command(s) to server before transfer +Protocols: FTP SFTP +Category: ftp sftp +Added: 5.3 +Multi: append +See-also: + - request +Example: + - --quote "DELE file" ftp://example.com/foo +--- + +# `--quote` + +Send an arbitrary command to the remote FTP or SFTP server. Quote commands are +sent BEFORE the transfer takes place (just after the initial **PWD** command +in an FTP transfer, to be exact). To make commands take place after a +successful transfer, prefix them with a dash '-'. + +(FTP only) To make commands be sent after curl has changed the working +directory, just before the file transfer command(s), prefix the command with a +'+'. This is not performed when a directory listing is performed. + +You may specify any number of commands. + +By default curl stops at first failure. To make curl continue even if the +command fails, prefix the command with an asterisk (*). Otherwise, if the +server returns failure for one of the commands, the entire operation is +aborted. + +You must send syntactically correct FTP commands as RFC 959 defines to FTP +servers, or one of the commands listed below to SFTP servers. + +SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands +itself before sending them to the server. Filenames may be quoted shell-style +to embed spaces or special characters. Following is the list of all supported +SFTP quote commands: + +## atime date file +The atime command sets the last access time of the file named by the file +operand. The date expression can be all sorts of date strings, see the +*curl_getdate(3)* man page for date expression details. (Added in 7.73.0) + +## chgrp group file +The chgrp command sets the group ID of the file named by the file operand to +the group ID specified by the group operand. The group operand is a decimal +integer group ID. + +## chmod mode file +The chmod command modifies the file mode bits of the specified file. The +mode operand is an octal integer mode number. + +## chown user file +The chown command sets the owner of the file named by the file operand to the +user ID specified by the user operand. The user operand is a decimal +integer user ID. + +## ln source_file target_file +The ln and symlink commands create a symbolic link at the target_file location +pointing to the source_file location. + +## mkdir directory_name +The mkdir command creates the directory named by the directory_name operand. + +## mtime date file +The mtime command sets the last modification time of the file named by the +file operand. The date expression can be all sorts of date strings, see the +*curl_getdate(3)* man page for date expression details. (Added in 7.73.0) + +## pwd +The pwd command returns the absolute path name of the current working directory. + +## rename source target +The rename command renames the file or directory named by the source +operand to the destination path named by the target operand. + +## rm file +The rm command removes the file specified by the file operand. + +## rmdir directory +The rmdir command removes the directory entry specified by the directory +operand, provided it is empty. + +## symlink source_file target_file +See ln. diff --git a/docs/cmdline-opts/random-file.d b/docs/cmdline-opts/random-file.d deleted file mode 100644 index aa076de7fc4..00000000000 --- a/docs/cmdline-opts/random-file.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: random-file -Arg: -Help: File for reading random data from -Category: misc -Example: --random-file rubbish $URL -Added: 7.7 -See-also: egd-file -Multi: single ---- -Deprecated option. This option is ignored (added in 7.84.0). Prior to that it -only had an effect on curl if built to use old versions of OpenSSL. - -Specify the path name to file containing random data. The data may be used to -seed the random engine for SSL connections. diff --git a/docs/cmdline-opts/random-file.md b/docs/cmdline-opts/random-file.md new file mode 100644 index 00000000000..0f564d9d7e5 --- /dev/null +++ b/docs/cmdline-opts/random-file.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: random-file +Arg: +Help: File for reading random data from +Category: misc +Added: 7.7 +Multi: single +See-also: + - egd-file +Example: + - --random-file rubbish $URL +--- + +# `--random-file` + +Deprecated option. This option is ignored (added in 7.84.0). Prior to that it +only had an effect on curl if built to use old versions of OpenSSL. + +Specify the path name to file containing random data. The data may be used to +seed the random engine for SSL connections. diff --git a/docs/cmdline-opts/range.d b/docs/cmdline-opts/range.d deleted file mode 100644 index eba7220e1e9..00000000000 --- a/docs/cmdline-opts/range.d +++ /dev/null @@ -1,50 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: range -Short: r -Help: Retrieve only the bytes within RANGE -Arg: -Protocols: HTTP FTP SFTP FILE -Category: http ftp sftp file -Example: --range 22-44 $URL -Added: 4.0 -See-also: continue-at append -Multi: single ---- -Retrieve a byte range (i.e. a partial document) from an HTTP/1.1, FTP or SFTP -server or a local FILE. Ranges can be specified in a number of ways. -.RS -.TP 10 -.B 0-499 -specifies the first 500 bytes -.TP -.B 500-999 -specifies the second 500 bytes -.TP -.B -500 -specifies the last 500 bytes -.TP -.B 9500- -specifies the bytes from offset 9500 and forward -.TP -.B 0-0,-1 -specifies the first and last byte only(*)(HTTP) -.TP -.B 100-199,500-599 -specifies two separate 100-byte ranges(*) (HTTP) -.RE -.IP -(*) = NOTE that this causes the server to reply with a multipart response, -which is returned as-is by curl! Parsing or otherwise transforming this -response is the responsibility of the caller. - -Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the -'start-stop' range syntax. If a non-digit character is given in the range, the -server's response is unspecified, depending on the server's configuration. - -Many HTTP/1.1 servers do not have this feature enabled, so that when you -attempt to get a range, curl instead gets the whole document. - -FTP and SFTP range downloads only support the simple 'start-stop' syntax -(optionally with one of the numbers omitted). FTP use depends on the extended -FTP command SIZE. diff --git a/docs/cmdline-opts/range.md b/docs/cmdline-opts/range.md new file mode 100644 index 00000000000..abfdf216f8f --- /dev/null +++ b/docs/cmdline-opts/range.md @@ -0,0 +1,57 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: range +Short: r +Help: Retrieve only the bytes within RANGE +Arg: +Protocols: HTTP FTP SFTP FILE +Category: http ftp sftp file +Added: 4.0 +Multi: single +See-also: + - continue-at + - append +Example: + - --range 22-44 $URL +--- + +# `--range` + +Retrieve a byte range (i.e. a partial document) from an HTTP/1.1, FTP or SFTP +server or a local FILE. Ranges can be specified in a number of ways. + +## 0-499 +specifies the first 500 bytes + +## 500-999 +specifies the second 500 bytes + +## -500 +specifies the last 500 bytes + +## 9500- +specifies the bytes from offset 9500 and forward + +## 0-0,-1 +specifies the first and last byte only(*)(HTTP) + +## 100-199,500-599 +specifies two separate 100-byte ranges(*) (HTTP) + +## + +(*) = NOTE that these make the server reply with a multipart response, which +is returned as-is by curl! Parsing or otherwise transforming this response is +the responsibility of the caller. + +Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the +'start-stop' range syntax. If a non-digit character is given in the range, the +server's response is unspecified, depending on the server's configuration. + +Many HTTP/1.1 servers do not have this feature enabled, so that when you +attempt to get a range, curl instead gets the whole document. + +FTP and SFTP range downloads only support the simple 'start-stop' syntax +(optionally with one of the numbers omitted). FTP use depends on the extended +FTP command SIZE. diff --git a/docs/cmdline-opts/rate.d b/docs/cmdline-opts/rate.d deleted file mode 100644 index d3cbd2849db..00000000000 --- a/docs/cmdline-opts/rate.d +++ /dev/null @@ -1,35 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: rate -Arg: -Help: Request rate for serial transfers -Category: connection -Example: --rate 2/s $URL ... -Example: --rate 3/h $URL ... -Example: --rate 14/m $URL ... -Added: 7.84.0 -See-also: limit-rate retry-delay -Multi: single -Scope: global ---- -Specify the maximum transfer frequency you allow curl to use - in number of -transfer starts per time unit (sometimes called request rate). Without this -option, curl starts the next transfer as fast as possible. - -If given several URLs and a transfer completes faster than the allowed rate, -curl waits until the next transfer is started to maintain the requested -rate. This option has no effect when --parallel is used. - -The request rate is provided as "N/U" where N is an integer number and U is a -time unit. Supported units are 's' (second), 'm' (minute), 'h' (hour) and 'd' -/(day, as in a 24 hour unit). The default time unit, if no "/U" is provided, -is number of transfers per hour. - -If curl is told to allow 10 requests per minute, it does not start the next -request until 6 seconds have elapsed since the previous transfer was started. - -This function uses millisecond resolution. If the allowed frequency is set -more than 1000 per second, it instead runs unrestricted. - -When retrying transfers, enabled with --retry, the separate retry delay logic -is used and not this setting. diff --git a/docs/cmdline-opts/rate.md b/docs/cmdline-opts/rate.md new file mode 100644 index 00000000000..fb2901e7e59 --- /dev/null +++ b/docs/cmdline-opts/rate.md @@ -0,0 +1,42 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: rate +Arg: +Help: Request rate for serial transfers +Category: connection +Added: 7.84.0 +Multi: single +Scope: global +See-also: + - limit-rate + - retry-delay +Example: + - --rate 2/s $URL ... + - --rate 3/h $URL ... + - --rate 14/m $URL ... +--- + +# `--rate` + +Specify the maximum transfer frequency you allow curl to use - in number of +transfer starts per time unit (sometimes called request rate). Without this +option, curl starts the next transfer as fast as possible. + +If given several URLs and a transfer completes faster than the allowed rate, +curl waits until the next transfer is started to maintain the requested +rate. This option has no effect when --parallel is used. + +The request rate is provided as "N/U" where N is an integer number and U is a +time unit. Supported units are 's' (second), 'm' (minute), 'h' (hour) and 'd' +/(day, as in a 24 hour unit). The default time unit, if no "/U" is provided, +is number of transfers per hour. + +If curl is told to allow 10 requests per minute, it does not start the next +request until 6 seconds have elapsed since the previous transfer was started. + +This function uses millisecond resolution. If the allowed frequency is set +more than 1000 per second, it instead runs unrestricted. + +When retrying transfers, enabled with --retry, the separate retry delay logic +is used and not this setting. diff --git a/docs/cmdline-opts/raw.d b/docs/cmdline-opts/raw.d deleted file mode 100644 index 0523d62fab3..00000000000 --- a/docs/cmdline-opts/raw.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: raw -Help: Do HTTP "raw"; no transfer decoding -Added: 7.16.2 -Protocols: HTTP -Category: http -Example: --raw $URL -See-also: tr-encoding -Multi: boolean ---- -When used, it disables all internal HTTP decoding of content or transfer -encodings and instead makes them passed on unaltered, raw. diff --git a/docs/cmdline-opts/raw.md b/docs/cmdline-opts/raw.md new file mode 100644 index 00000000000..ca63dc318ce --- /dev/null +++ b/docs/cmdline-opts/raw.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: raw +Help: Do HTTP raw; no transfer decoding +Added: 7.16.2 +Protocols: HTTP +Category: http +Multi: boolean +See-also: + - tr-encoding +Example: + - --raw $URL +--- + +# `--raw` + +When used, it disables all internal HTTP decoding of content or transfer +encodings and instead makes them passed on unaltered, raw. diff --git a/docs/cmdline-opts/referer.d b/docs/cmdline-opts/referer.d deleted file mode 100644 index 0609e8c9977..00000000000 --- a/docs/cmdline-opts/referer.d +++ /dev/null @@ -1,20 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: referer -Short: e -Arg: -Protocols: HTTP -Help: Referrer URL -See-also: user-agent header -Category: http -Example: --referer "https://fake.example" $URL -Example: --referer "https://fake.example;auto" -L $URL -Example: --referer ";auto" -L $URL -Added: 4.0 -Multi: single ---- -Sends the "Referrer Page" information to the HTTP server. This can also be set -with the --header flag of course. When used with --location you can append -";auto" to the --referer URL to make curl automatically set the previous URL -when it follows a Location: header. The ";auto" string can be used alone, -even if you do not set an initial --referer. diff --git a/docs/cmdline-opts/referer.md b/docs/cmdline-opts/referer.md new file mode 100644 index 00000000000..1fec2485012 --- /dev/null +++ b/docs/cmdline-opts/referer.md @@ -0,0 +1,27 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: referer +Short: e +Arg: +Protocols: HTTP +Help: Referrer URL +Category: http +Added: 4.0 +Multi: single +See-also: + - user-agent + - header +Example: + - --referer "https://fake.example" $URL + - --referer "https://fake.example;auto" -L $URL + - --referer ";auto" -L $URL +--- + +# `--referer` + +Set the referrer URL in the HTTP request. This can also be set with the +--header flag of course. When used with --location you can append `;auto`" to +the --referer URL to make curl automatically set the previous URL when it +follows a Location: header. The `;auto` string can be used alone, even if you +do not set an initial --referer. diff --git a/docs/cmdline-opts/remote-header-name.d b/docs/cmdline-opts/remote-header-name.d deleted file mode 100644 index 917fe7abf26..00000000000 --- a/docs/cmdline-opts/remote-header-name.d +++ /dev/null @@ -1,34 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: remote-header-name -Short: J -Protocols: HTTP -Help: Use the header-provided filename -Category: output -Example: -OJ https://example.com/file -Added: 7.20.0 -See-also: remote-name -Multi: boolean ---- -This option tells the --remote-name option to use the server-specified -Content-Disposition filename instead of extracting a filename from the URL. If -the server-provided file name contains a path, that is stripped off before the -file name is used. - -The file is saved in the current directory, or in the directory specified with ---output-dir. - -If the server specifies a file name and a file with that name already exists -in the destination directory, it is not overwritten and an error occurs - -unless you allow it by using the --clobber option. If the server does not -specify a file name then this option has no effect. - -There is no attempt to decode %-sequences (yet) in the provided file name, so -this option may provide you with rather unexpected file names. - -This feature uses the name from the "filename" field, it does not yet support -the "filename*" field (filenames with explicit character sets). - -**WARNING**: Exercise judicious use of this option, especially on Windows. A -rogue server could send you the name of a DLL or other file that could be -loaded automatically by Windows or some third party software. diff --git a/docs/cmdline-opts/remote-header-name.md b/docs/cmdline-opts/remote-header-name.md new file mode 100644 index 00000000000..88c2808a3fe --- /dev/null +++ b/docs/cmdline-opts/remote-header-name.md @@ -0,0 +1,39 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: remote-header-name +Short: J +Protocols: HTTP +Help: Use the header-provided filename +Category: output +Added: 7.20.0 +Multi: boolean +See-also: + - remote-name +Example: + - -OJ https://example.com/file +--- + +# `--remote-header-name` + +Tell the --remote-name option to use the server-specified Content-Disposition +filename instead of extracting a filename from the URL. If the server-provided +filename contains a path, that is stripped off before the filename is used. + +The file is saved in the current directory, or in the directory specified with +--output-dir. + +If the server specifies a filename and a file with that name already exists in +the destination directory, it is not overwritten and an error occurs - unless +you allow it by using the --clobber option. If the server does not specify a +filename then this option has no effect. + +There is no attempt to decode %-sequences (yet) in the provided filename, so +this option may provide you with rather unexpected filenames. + +This feature uses the name from the `filename` field, it does not yet support +the `filename*` field (filenames with explicit character sets). + +**WARNING**: Exercise judicious use of this option, especially on Windows. A +rogue server could send you the name of a DLL or other file that could be +loaded automatically by Windows or some third party software. diff --git a/docs/cmdline-opts/remote-name-all.d b/docs/cmdline-opts/remote-name-all.d deleted file mode 100644 index 249c4e265f2..00000000000 --- a/docs/cmdline-opts/remote-name-all.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: remote-name-all -Help: Use the remote file name for all URLs -Added: 7.19.0 -Category: output -Example: --remote-name-all ftp://example.com/file1 ftp://example.com/file2 -See-also: remote-name -Multi: boolean ---- -This option changes the default action for all given URLs to be dealt with as -if --remote-name were used for each one. So if you want to disable that for a -specific URL after --remote-name-all has been used, you must use "-o -" or ---no-remote-name. diff --git a/docs/cmdline-opts/remote-name-all.md b/docs/cmdline-opts/remote-name-all.md new file mode 100644 index 00000000000..92d348e27c2 --- /dev/null +++ b/docs/cmdline-opts/remote-name-all.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: remote-name-all +Help: Use the remote filename for all URLs +Added: 7.19.0 +Category: output +Multi: boolean +See-also: + - remote-name +Example: + - --remote-name-all ftp://example.com/file1 ftp://example.com/file2 +--- + +# `--remote-name-all` + +Change the default action for all given URLs to be dealt with as if +--remote-name were used for each one. If you want to disable that for a +specific URL after --remote-name-all has been used, you must use "-o -" or +--no-remote-name. diff --git a/docs/cmdline-opts/remote-name.d b/docs/cmdline-opts/remote-name.d deleted file mode 100644 index 215cf72deb9..00000000000 --- a/docs/cmdline-opts/remote-name.d +++ /dev/null @@ -1,28 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: remote-name -Short: O -Help: Write output to a file named as the remote file -Category: important output -Example: -O https://example.com/filename -Added: 4.0 -See-also: remote-name-all output-dir remote-header-name -Multi: append ---- -Write output to a local file named like the remote file we get. (Only the file -part of the remote file is used, the path is cut off.) - -The file is saved in the current working directory. If you want the file saved -in a different directory, make sure you change the current working directory -before invoking curl with this option or use --output-dir. - -The remote file name to use for saving is extracted from the given URL, -nothing else, and if it already exists it is overwritten. If you want the -server to be able to choose the file name refer to --remote-header-name which -can be used in addition to this option. If the server chooses a file name and -that name already exists it is not overwritten. - -There is no URL decoding done on the file name. If it has %20 or other URL -encoded parts of the name, they end up as-is as file name. - -You may use this option as many times as the number of URLs you have. diff --git a/docs/cmdline-opts/remote-name.md b/docs/cmdline-opts/remote-name.md new file mode 100644 index 00000000000..5d2fcdcb2b6 --- /dev/null +++ b/docs/cmdline-opts/remote-name.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: remote-name +Short: O +Help: Write output to file named as remote file +Category: important output +Added: 4.0 +Multi: append +See-also: + - remote-name-all + - output-dir + - remote-header-name +Example: + - -O https://example.com/filename +--- + +# `--remote-name` + +Write output to a local file named like the remote file we get. (Only the file +part of the remote file is used, the path is cut off.) + +The file is saved in the current working directory. If you want the file saved +in a different directory, make sure you change the current working directory +before invoking curl with this option or use --output-dir. + +The remote filename to use for saving is extracted from the given URL, nothing +else, and if it already exists it is overwritten. If you want the server to be +able to choose the filename refer to --remote-header-name which can be used in +addition to this option. If the server chooses a filename and that name +already exists it is not overwritten. + +There is no URL decoding done on the filename. If it has %20 or other URL +encoded parts of the name, they end up as-is as filename. + +You may use this option as many times as the number of URLs you have. diff --git a/docs/cmdline-opts/remote-time.d b/docs/cmdline-opts/remote-time.d deleted file mode 100644 index 6dfb26c491b..00000000000 --- a/docs/cmdline-opts/remote-time.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: remote-time -Short: R -Help: Set the remote file's time on the local output -Category: output -Example: --remote-time -o foo $URL -Added: 7.9 -See-also: remote-name time-cond -Multi: boolean ---- -Makes curl attempt to figure out the timestamp of the remote file that is -getting downloaded, and if that is available make the local file get that same -timestamp. diff --git a/docs/cmdline-opts/remote-time.md b/docs/cmdline-opts/remote-time.md new file mode 100644 index 00000000000..7c5d21f0367 --- /dev/null +++ b/docs/cmdline-opts/remote-time.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: remote-time +Short: R +Help: Set remote file's time on local output +Category: output +Added: 7.9 +Multi: boolean +See-also: + - remote-name + - time-cond +Example: + - --remote-time -o foo $URL +--- + +# `--remote-time` + +Makes curl attempt to figure out the timestamp of the remote file that is +getting downloaded, and if that is available make the local file get that same +timestamp. diff --git a/docs/cmdline-opts/remove-on-error.d b/docs/cmdline-opts/remove-on-error.d deleted file mode 100644 index 50b7b1b65cf..00000000000 --- a/docs/cmdline-opts/remove-on-error.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: remove-on-error -Help: Remove output file on errors -See-also: fail -Category: curl -Example: --remove-on-error -o output $URL -Added: 7.83.0 -Multi: boolean ---- -When curl returns an error when told to save output in a local file, this -option removes that saved file before exiting. This prevents curl from -leaving a partial file in the case of an error during transfer. - -If the output is not a file, this option has no effect. diff --git a/docs/cmdline-opts/remove-on-error.md b/docs/cmdline-opts/remove-on-error.md new file mode 100644 index 00000000000..b0064ae3187 --- /dev/null +++ b/docs/cmdline-opts/remove-on-error.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: remove-on-error +Help: Remove output file on errors +Category: curl +Added: 7.83.0 +Multi: boolean +See-also: + - fail +Example: + - --remove-on-error -o output $URL +--- + +# `--remove-on-error` + +Remove output file if an error occurs. If curl returns an error when told to +save output in a local file. This prevents curl from leaving a partial file in +the case of an error during transfer. + +If the output is not a regular file, this option has no effect. diff --git a/docs/cmdline-opts/request-target.d b/docs/cmdline-opts/request-target.d deleted file mode 100644 index be53c658cb9..00000000000 --- a/docs/cmdline-opts/request-target.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: request-target -Arg: -Help: Specify the target for this request -Protocols: HTTP -Added: 7.55.0 -Category: http -Example: --request-target "*" -X OPTIONS $URL -See-also: request -Multi: single ---- -Tells curl to use an alternative "target" (path) instead of using the path as -provided in the URL. Particularly useful when wanting to issue HTTP requests -without leading slash or other data that does not follow the regular URL -pattern, like "OPTIONS *". - -curl passes on the verbatim string you give it its the request without any -filter or other safe guards. That includes white space and control characters. diff --git a/docs/cmdline-opts/request-target.md b/docs/cmdline-opts/request-target.md new file mode 100644 index 00000000000..442851148f9 --- /dev/null +++ b/docs/cmdline-opts/request-target.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: request-target +Arg: +Help: Specify the target for this request +Protocols: HTTP +Added: 7.55.0 +Category: http +Multi: single +See-also: + - request +Example: + - --request-target "*" -X OPTIONS $URL +--- + +# `--request-target` + +Use an alternative target (path) instead of using the path as provided in the +URL. Particularly useful when wanting to issue HTTP requests without leading +slash or other data that does not follow the regular URL pattern, like +"OPTIONS *". + +curl passes on the verbatim string you give it its the request without any +filter or other safe guards. That includes white space and control characters. diff --git a/docs/cmdline-opts/request.d b/docs/cmdline-opts/request.d deleted file mode 100644 index 6afd5356483..00000000000 --- a/docs/cmdline-opts/request.d +++ /dev/null @@ -1,54 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: request -Short: X -Arg: -Help: Specify request method to use -Category: connection -Example: -X "DELETE" $URL -Example: -X NLST ftp://example.com/ -Added: 6.0 -See-also: request-target -Multi: single ---- -Change the method to use when starting the transfer. - -curl passes on the verbatim string you give it its the request without any -filter or other safe guards. That includes white space and control characters. -.RS -.TP 15 -**HTTP** -Specifies a custom request method to use when communicating with the HTTP -server. The specified request method is used instead of the method otherwise -used (which defaults to *GET*). Read the HTTP 1.1 specification for details -and explanations. Common additional HTTP requests include *PUT* and *DELETE*, -but related technologies like WebDAV offers *PROPFIND*, *COPY*, *MOVE* and -more. - -Normally you do not need this option. All sorts of *GET*, *HEAD*, *POST* and -*PUT* requests are rather invoked by using dedicated command line options. - -This option only changes the actual word used in the HTTP request, it does not -alter the way curl behaves. So for example if you want to make a proper HEAD -request, using -X HEAD does not suffice. You need to use the --head option. - -The method string you set with --request is used for all requests, which -if you for example use --location may cause unintended side-effects when curl -does not change request method according to the HTTP 30x response codes - and -similar. -.TP -**FTP** -Specifies a custom FTP command to use instead of *LIST* when doing file lists -with FTP. -.TP -**POP3** -Specifies a custom POP3 command to use instead of *LIST* or *RETR*. -(Added in 7.26.0) -.TP -**IMAP** -Specifies a custom IMAP command to use instead of *LIST*. (Added in 7.30.0) -.TP -**SMTP** -Specifies a custom SMTP command to use instead of *HELP* or **VRFY**. (Added in 7.34.0) -.RE -.IP diff --git a/docs/cmdline-opts/request.md b/docs/cmdline-opts/request.md new file mode 100644 index 00000000000..4a6304c1be5 --- /dev/null +++ b/docs/cmdline-opts/request.md @@ -0,0 +1,57 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: request +Short: X +Arg: +Help: Specify request method to use +Category: connection +Added: 6.0 +Multi: single +See-also: + - request-target +Example: + - -X "DELETE" $URL + - -X NLST ftp://example.com/ +--- + +# `--request` + +Change the method to use when starting the transfer. + +curl passes on the verbatim string you give it its the request without any +filter or other safe guards. That includes white space and control characters. + +## HTTP +Specifies a custom request method to use when communicating with the HTTP +server. The specified request method is used instead of the method otherwise +used (which defaults to *GET*). Read the HTTP 1.1 specification for details +and explanations. Common additional HTTP requests include *PUT* and *DELETE*, +while related technologies like WebDAV offers *PROPFIND*, *COPY*, *MOVE* and +more. + +Normally you do not need this option. All sorts of *GET*, *HEAD*, *POST* and +*PUT* requests are rather invoked by using dedicated command line options. + +This option only changes the actual word used in the HTTP request, it does not +alter the way curl behaves. For example if you want to make a proper HEAD +request, using -X HEAD does not suffice. You need to use the --head option. + +The method string you set with --request is used for all requests, which +if you for example use --location may cause unintended side-effects when curl +does not change request method according to the HTTP 30x response codes - and +similar. + +## FTP +Specifies a custom FTP command to use instead of *LIST* when doing file lists +with FTP. + +## POP3 +Specifies a custom POP3 command to use instead of *LIST* or *RETR*. +(Added in 7.26.0) + +## IMAP +Specifies a custom IMAP command to use instead of *LIST*. (Added in 7.30.0) + +## SMTP +Specifies a custom SMTP command to use instead of *HELP* or **VRFY**. (Added in 7.34.0) diff --git a/docs/cmdline-opts/resolve.d b/docs/cmdline-opts/resolve.d deleted file mode 100644 index badb54e4566..00000000000 --- a/docs/cmdline-opts/resolve.d +++ /dev/null @@ -1,39 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: resolve -Arg: <[+]host:port:addr[,addr]...> -Help: Resolve the host+port to this address -Added: 7.21.3 -Category: connection dns -Example: --resolve example.com:443:127.0.0.1 $URL -See-also: connect-to alt-svc -Multi: append ---- -Provide a custom address for a specific host and port pair. Using this, you -can make the curl requests(s) use a specified address and prevent the -otherwise normally resolved address to be used. Consider it a sort of -/etc/hosts alternative provided on the command line. The port number should be -the number used for the specific protocol the host is used for. It means -you need several entries if you want to provide address for the same host but -different ports. - -By specifying '*' as host you can tell curl to resolve any host and specific -port pair to the specified address. Wildcard is resolved last so any --resolve -with a specific host and port is used first. - -The provided address set by this option is used even if --ipv4 or --ipv6 is -set to make curl use another IP version. - -By prefixing the host with a '+' you can make the entry time out after curl's -default timeout (1 minute). Note that this only makes sense for long running -parallel transfers with a lot of files. In such cases, if this option is used -curl tries to resolve the host as it normally would once the timeout has -expired. - -Support for providing the IP address within [brackets] was added in 7.57.0. - -Support for providing multiple IP addresses per entry was added in 7.59.0. - -Support for resolving with wildcard was added in 7.64.0. - -Support for the '+' prefix was was added in 7.75.0. diff --git a/docs/cmdline-opts/resolve.md b/docs/cmdline-opts/resolve.md new file mode 100644 index 00000000000..ca1f930fcd2 --- /dev/null +++ b/docs/cmdline-opts/resolve.md @@ -0,0 +1,46 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: resolve +Arg: <[+]host:port:addr[,addr]...> +Help: Resolve host+port to address +Added: 7.21.3 +Category: connection dns +Multi: append +See-also: + - connect-to + - alt-svc +Example: + - --resolve example.com:443:127.0.0.1 $URL +--- + +# `--resolve` + +Provide a custom address for a specific host and port pair. Using this, you +can make the curl requests(s) use a specified address and prevent the +otherwise normally resolved address to be used. Consider it a sort of +/etc/hosts alternative provided on the command line. The port number should be +the number used for the specific protocol the host is used for. It means +you need several entries if you want to provide address for the same host but +different ports. + +By specifying `*` as host you can tell curl to resolve any host and specific +port pair to the specified address. Wildcard is resolved last so any --resolve +with a specific host and port is used first. + +The provided address set by this option is used even if --ipv4 or --ipv6 is +set to make curl use another IP version. + +By prefixing the host with a '+' you can make the entry time out after curl's +default timeout (1 minute). Note that this only makes sense for long running +parallel transfers with a lot of files. In such cases, if this option is used +curl tries to resolve the host as it normally would once the timeout has +expired. + +Support for providing the IP address within [brackets] was added in 7.57.0. + +Support for providing multiple IP addresses per entry was added in 7.59.0. + +Support for resolving with wildcard was added in 7.64.0. + +Support for the '+' prefix was added in 7.75.0. diff --git a/docs/cmdline-opts/retry-all-errors.d b/docs/cmdline-opts/retry-all-errors.d deleted file mode 100644 index 1190d6a3ae4..00000000000 --- a/docs/cmdline-opts/retry-all-errors.d +++ /dev/null @@ -1,34 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: retry-all-errors -Help: Retry all errors (use with --retry) -Added: 7.71.0 -Category: curl -Example: --retry 5 --retry-all-errors $URL -See-also: retry -Multi: boolean ---- -Retry on any error. This option is used together with --retry. - -This option is the "sledgehammer" of retrying. Do not use this option by -default (for example in your **curlrc**), there may be unintended consequences -such as sending or receiving duplicate data. Do not use with redirected input -or output. You'd be much better off handling your unique problems in shell -script. Please read the example below. - -**WARNING**: For server compatibility curl attempts to retry failed flaky -transfers as close as possible to how they were started, but this is not -possible with redirected input or output. For example, before retrying it -removes output data from a failed partial transfer that was written to an -output file. However this is not true of data redirected to a | pipe or > -file, which are not reset. We strongly suggest you do not parse or record -output via redirect in combination with this option, since you may receive -duplicate data. - -By default curl does not return error for transfers with an HTTP response code -that indicates an HTTP error, if the transfer was successful. For example, if -a server replies 404 Not Found and the reply is fully received then that is -not an error. When --retry is used then curl retries on some HTTP response -codes that indicate transient HTTP errors, but that does not include most 4xx -response codes such as 404. If you want to retry on all response codes that -indicate HTTP errors (4xx and 5xx) then combine with --fail. diff --git a/docs/cmdline-opts/retry-all-errors.md b/docs/cmdline-opts/retry-all-errors.md new file mode 100644 index 00000000000..230e730678e --- /dev/null +++ b/docs/cmdline-opts/retry-all-errors.md @@ -0,0 +1,40 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: retry-all-errors +Help: Retry all errors (with --retry) +Added: 7.71.0 +Category: curl +Multi: boolean +See-also: + - retry +Example: + - --retry 5 --retry-all-errors $URL +--- + +# `--retry-all-errors` + +Retry on any error. This option is used together with --retry. + +This option is the "sledgehammer" of retrying. Do not use this option by +default (for example in your **curlrc**), there may be unintended consequences +such as sending or receiving duplicate data. Do not use with redirected input +or output. You might be better off handling your unique problems in a shell +script. Please read the example below. + +**WARNING**: For server compatibility curl attempts to retry failed flaky +transfers as close as possible to how they were started, but this is not +possible with redirected input or output. For example, before retrying it +removes output data from a failed partial transfer that was written to an +output file. However this is not true of data redirected to a | pipe or \> +file, which are not reset. We strongly suggest you do not parse or record +output via redirect in combination with this option, since you may receive +duplicate data. + +By default curl does not return error for transfers with an HTTP response code +that indicates an HTTP error, if the transfer was successful. For example, if +a server replies 404 Not Found and the reply is fully received then that is +not an error. When --retry is used then curl retries on some HTTP response +codes that indicate transient HTTP errors, but that does not include most 4xx +response codes such as 404. If you want to retry on all response codes that +indicate HTTP errors (4xx and 5xx) then combine with --fail. diff --git a/docs/cmdline-opts/retry-connrefused.d b/docs/cmdline-opts/retry-connrefused.d deleted file mode 100644 index a7b9643ce26..00000000000 --- a/docs/cmdline-opts/retry-connrefused.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: retry-connrefused -Help: Retry on connection refused (use with --retry) -Added: 7.52.0 -Category: curl -Example: --retry-connrefused --retry 7 $URL -See-also: retry retry-all-errors -Multi: boolean ---- -In addition to the other conditions, consider ECONNREFUSED as a transient -error too for --retry. This option is used together with --retry. diff --git a/docs/cmdline-opts/retry-connrefused.md b/docs/cmdline-opts/retry-connrefused.md new file mode 100644 index 00000000000..22345cd8818 --- /dev/null +++ b/docs/cmdline-opts/retry-connrefused.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: retry-connrefused +Help: Retry on connection refused (with --retry) +Added: 7.52.0 +Category: curl +Multi: boolean +See-also: + - retry + - retry-all-errors +Example: + - --retry-connrefused --retry 7 $URL +--- + +# `--retry-connrefused` + +In addition to the other conditions, consider ECONNREFUSED as a transient +error too for --retry. This option is used together with --retry. diff --git a/docs/cmdline-opts/retry-delay.d b/docs/cmdline-opts/retry-delay.d deleted file mode 100644 index 686a0d8ba48..00000000000 --- a/docs/cmdline-opts/retry-delay.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: retry-delay -Arg: -Help: Wait time between retries -Added: 7.12.3 -Category: curl -Example: --retry-delay 5 --retry 7 $URL -See-also: retry -Multi: single ---- -Make curl sleep this amount of time before each retry when a transfer has -failed with a transient error (it changes the default backoff time algorithm -between retries). This option is only interesting if --retry is also -used. Setting this delay to zero makes curl use the default backoff time. diff --git a/docs/cmdline-opts/retry-delay.md b/docs/cmdline-opts/retry-delay.md new file mode 100644 index 00000000000..b2a405b63fd --- /dev/null +++ b/docs/cmdline-opts/retry-delay.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: retry-delay +Arg: +Help: Wait time between retries +Added: 7.12.3 +Category: curl +Multi: single +See-also: + - retry +Example: + - --retry-delay 5 --retry 7 $URL +--- + +# `--retry-delay` + +Make curl sleep this amount of time before each retry when a transfer has +failed with a transient error (it changes the default backoff time algorithm +between retries). This option is only interesting if --retry is also +used. Setting this delay to zero makes curl use the default backoff time. diff --git a/docs/cmdline-opts/retry-max-time.d b/docs/cmdline-opts/retry-max-time.d deleted file mode 100644 index de2aff9a80c..00000000000 --- a/docs/cmdline-opts/retry-max-time.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: retry-max-time -Arg: -Help: Retry only within this period -Added: 7.12.3 -Category: curl -Example: --retry-max-time 30 --retry 10 $URL -See-also: retry -Multi: single ---- -The retry timer is reset before the first transfer attempt. Retries are done -as usual (see --retry) as long as the timer has not reached this given -limit. Notice that if the timer has not reached the limit, the request is -made and while performing, it may take longer than this given time period. To -limit a single request's maximum time, use --max-time. Set this option to zero -to not timeout retries. diff --git a/docs/cmdline-opts/retry-max-time.md b/docs/cmdline-opts/retry-max-time.md new file mode 100644 index 00000000000..f7346475b98 --- /dev/null +++ b/docs/cmdline-opts/retry-max-time.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: retry-max-time +Arg: +Help: Retry only within this period +Added: 7.12.3 +Category: curl +Multi: single +See-also: + - retry +Example: + - --retry-max-time 30 --retry 10 $URL +--- + +# `--retry-max-time` + +The retry timer is reset before the first transfer attempt. Retries are done +as usual (see --retry) as long as the timer has not reached this given +limit. Notice that if the timer has not reached the limit, the request is +made and while performing, it may take longer than this given time period. To +limit a single request's maximum time, use --max-time. Set this option to zero +to not timeout retries. diff --git a/docs/cmdline-opts/retry.d b/docs/cmdline-opts/retry.d deleted file mode 100644 index d49a0cdfb4e..00000000000 --- a/docs/cmdline-opts/retry.d +++ /dev/null @@ -1,25 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: retry -Arg: -Added: 7.12.3 -Help: Retry request if transient problems occur -Category: curl -Example: --retry 7 $URL -See-also: retry-max-time -Multi: single ---- -If a transient error is returned when curl tries to perform a transfer, it -retries this number of times before giving up. Setting the number to 0 -makes curl do no retries (which is the default). Transient error means either: -a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504 -response code. - -When curl is about to retry a transfer, it first waits one second and then for -all forthcoming retries it doubles the waiting time until it reaches 10 -minutes which then remains delay between the rest of the retries. By using ---retry-delay you disable this exponential backoff algorithm. See also ---retry-max-time to limit the total time allowed for retries. - -curl complies with the Retry-After: response header if one was present to know -when to issue the next retry (added in 7.66.0). diff --git a/docs/cmdline-opts/retry.md b/docs/cmdline-opts/retry.md new file mode 100644 index 00000000000..1cd595dd22b --- /dev/null +++ b/docs/cmdline-opts/retry.md @@ -0,0 +1,31 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: retry +Arg: +Added: 7.12.3 +Help: Retry request if transient problems occur +Category: curl +Multi: single +See-also: + - retry-max-time +Example: + - --retry 7 $URL +--- + +# `--retry` + +If a transient error is returned when curl tries to perform a transfer, it +retries this number of times before giving up. Setting the number to 0 +makes curl do no retries (which is the default). Transient error means either: +a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504 +response code. + +When curl is about to retry a transfer, it first waits one second and then for +all forthcoming retries it doubles the waiting time until it reaches 10 +minutes which then remains delay between the rest of the retries. By using +--retry-delay you disable this exponential backoff algorithm. See also +--retry-max-time to limit the total time allowed for retries. + +curl complies with the Retry-After: response header if one was present to know +when to issue the next retry (added in 7.66.0). diff --git a/docs/cmdline-opts/sasl-authzid.d b/docs/cmdline-opts/sasl-authzid.d deleted file mode 100644 index 872818df773..00000000000 --- a/docs/cmdline-opts/sasl-authzid.d +++ /dev/null @@ -1,19 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: sasl-authzid -Arg: -Help: Identity for SASL PLAIN authentication -Added: 7.66.0 -Category: auth -Example: --sasl-authzid zid imap://example.com/ -See-also: login-options -Multi: single ---- -Use this authorization identity (**authzid**), during SASL PLAIN -authentication, in addition to the authentication identity (**authcid**) as -specified by --user. - -If the option is not specified, the server derives the **authzid** from the -**authcid**, but if specified, and depending on the server implementation, it -may be used to access another user's inbox, that the user has been granted -access to, or a shared mailbox for example. diff --git a/docs/cmdline-opts/sasl-authzid.md b/docs/cmdline-opts/sasl-authzid.md new file mode 100644 index 00000000000..4c4282d14dd --- /dev/null +++ b/docs/cmdline-opts/sasl-authzid.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: sasl-authzid +Arg: +Help: Identity for SASL PLAIN authentication +Added: 7.66.0 +Category: auth +Multi: single +See-also: + - login-options +Example: + - --sasl-authzid zid imap://example.com/ +--- + +# `--sasl-authzid` + +Use this authorization identity (**authzid**), during SASL PLAIN +authentication, in addition to the authentication identity (**authcid**) as +specified by --user. + +If the option is not specified, the server derives the **authzid** from the +**authcid**, but if specified, and depending on the server implementation, it +may be used to access another user's inbox, that the user has been granted +access to, or a shared mailbox for example. diff --git a/docs/cmdline-opts/sasl-ir.d b/docs/cmdline-opts/sasl-ir.d deleted file mode 100644 index 56f1ae8ad71..00000000000 --- a/docs/cmdline-opts/sasl-ir.d +++ /dev/null @@ -1,11 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: sasl-ir -Help: Enable initial response in SASL authentication -Added: 7.31.0 -Category: auth -Example: --sasl-ir imap://example.com/ -See-also: sasl-authzid -Multi: boolean ---- -Enable initial response in SASL authentication. diff --git a/docs/cmdline-opts/sasl-ir.md b/docs/cmdline-opts/sasl-ir.md new file mode 100644 index 00000000000..b11137df0a6 --- /dev/null +++ b/docs/cmdline-opts/sasl-ir.md @@ -0,0 +1,17 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: sasl-ir +Help: Initial response in SASL authentication +Added: 7.31.0 +Category: auth +Multi: boolean +See-also: + - sasl-authzid +Example: + - --sasl-ir imap://example.com/ +--- + +# `--sasl-ir` + +Enable initial response in SASL authentication. diff --git a/docs/cmdline-opts/service-name.d b/docs/cmdline-opts/service-name.d deleted file mode 100644 index 54d7ebf7bcc..00000000000 --- a/docs/cmdline-opts/service-name.d +++ /dev/null @@ -1,12 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: service-name -Help: SPNEGO service name -Arg: -Added: 7.43.0 -Category: misc -Example: --service-name sockd/server $URL -See-also: negotiate proxy-service-name -Multi: single ---- -This option allows you to change the service name for SPNEGO. diff --git a/docs/cmdline-opts/service-name.md b/docs/cmdline-opts/service-name.md new file mode 100644 index 00000000000..b39bad4f18f --- /dev/null +++ b/docs/cmdline-opts/service-name.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: service-name +Help: SPNEGO service name +Arg: +Added: 7.43.0 +Category: misc +Multi: single +See-also: + - negotiate + - proxy-service-name +Example: + - --service-name sockd/server $URL +--- + +# `--service-name` + +Set the service name for SPNEGO. diff --git a/docs/cmdline-opts/show-error.d b/docs/cmdline-opts/show-error.d deleted file mode 100644 index f1502874589..00000000000 --- a/docs/cmdline-opts/show-error.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: show-error -Short: S -Help: Show error even when -s is used -See-also: no-progress-meter -Category: curl -Example: --show-error --silent $URL -Added: 5.9 -Multi: boolean -Scope: global ---- -When used with --silent, it makes curl show an error message if it fails. diff --git a/docs/cmdline-opts/show-error.md b/docs/cmdline-opts/show-error.md new file mode 100644 index 00000000000..0517c37bb41 --- /dev/null +++ b/docs/cmdline-opts/show-error.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: show-error +Short: S +Help: Show error even when -s is used +Category: curl +Added: 5.9 +Multi: boolean +Scope: global +See-also: + - no-progress-meter +Example: + - --show-error --silent $URL +--- + +# `--show-error` + +When used with --silent, it makes curl show an error message if it fails. diff --git a/docs/cmdline-opts/silent.d b/docs/cmdline-opts/silent.d deleted file mode 100644 index 74bb299cc2e..00000000000 --- a/docs/cmdline-opts/silent.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: silent -Short: s -Help: Silent mode -See-also: verbose stderr no-progress-meter -Category: important verbose -Example: -s $URL -Added: 4.0 -Multi: boolean ---- -Silent or quiet mode. Do not show progress meter or error messages. Makes Curl -mute. It still outputs the data you ask for, potentially even to the -terminal/stdout unless you redirect it. - -Use --show-error in addition to this option to disable progress meter but -still show error messages. diff --git a/docs/cmdline-opts/silent.md b/docs/cmdline-opts/silent.md new file mode 100644 index 00000000000..090af0cb149 --- /dev/null +++ b/docs/cmdline-opts/silent.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: silent +Short: s +Help: Silent mode +Category: important verbose +Added: 4.0 +Multi: boolean +See-also: + - verbose + - stderr + - no-progress-meter +Example: + - -s $URL +--- + +# `--silent` + +Silent or quiet mode. Do not show progress meter or error messages. Makes Curl +mute. It still outputs the data you ask for, potentially even to the +terminal/stdout unless you redirect it. + +Use --show-error in addition to this option to disable progress meter but +still show error messages. diff --git a/docs/cmdline-opts/socks4.d b/docs/cmdline-opts/socks4.d deleted file mode 100644 index d8cf719aad5..00000000000 --- a/docs/cmdline-opts/socks4.d +++ /dev/null @@ -1,28 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: socks4 -Arg: -Help: SOCKS4 proxy on given host + port -Added: 7.15.2 -Category: proxy -Example: --socks4 hostname:4096 $URL -See-also: socks4a socks5 socks5-hostname -Multi: single ---- -Use the specified SOCKS4 proxy. If the port number is not specified, it is -assumed at port 1080. Using this socket type make curl resolve the host name -and passing the address on to the proxy. - -To specify proxy on a unix domain socket, use localhost for host, e.g. -socks4://localhost/path/to/socket.sock - -This option overrides any previous use of --proxy, as they are mutually -exclusive. - -This option is superfluous since you can specify a socks4 proxy with --proxy -using a socks4:// protocol prefix. (Added in 7.21.7) - ---preproxy can be used to specify a SOCKS proxy at the same time proxy is used -with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first -connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or -HTTPS proxy. diff --git a/docs/cmdline-opts/socks4.md b/docs/cmdline-opts/socks4.md new file mode 100644 index 00000000000..e74fa787ce0 --- /dev/null +++ b/docs/cmdline-opts/socks4.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: socks4 +Arg: +Help: SOCKS4 proxy on given host + port +Added: 7.15.2 +Category: proxy +Multi: single +See-also: + - socks4a + - socks5 + - socks5-hostname +Example: + - --socks4 hostname:4096 $URL +--- + +# `--socks4` + +Use the specified SOCKS4 proxy. If the port number is not specified, it is +assumed at port 1080. Using this socket type make curl resolve the hostname +and passing the address on to the proxy. + +To specify proxy on a unix domain socket, use localhost for host, e.g. +`socks4://localhost/path/to/socket.sock` + +This option overrides any previous use of --proxy, as they are mutually +exclusive. + +This option is superfluous since you can specify a socks4 proxy with --proxy +using a socks4:// protocol prefix. (Added in 7.21.7) + +--preproxy can be used to specify a SOCKS proxy at the same time proxy is used +with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first +connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or +HTTPS proxy. diff --git a/docs/cmdline-opts/socks4a.d b/docs/cmdline-opts/socks4a.d deleted file mode 100644 index cbb62724cdf..00000000000 --- a/docs/cmdline-opts/socks4a.d +++ /dev/null @@ -1,27 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: socks4a -Arg: -Help: SOCKS4a proxy on given host + port -Added: 7.18.0 -Category: proxy -Example: --socks4a hostname:4096 $URL -See-also: socks4 socks5 socks5-hostname -Multi: single ---- -Use the specified SOCKS4a proxy. If the port number is not specified, it is -assumed at port 1080. This asks the proxy to resolve the host name. - -To specify proxy on a unix domain socket, use localhost for host, e.g. -socks4a://localhost/path/to/socket.sock - -This option overrides any previous use of --proxy, as they are mutually -exclusive. - -This option is superfluous since you can specify a socks4a proxy with --proxy -using a socks4a:// protocol prefix. (Added in 7.21.7) - ---preproxy can be used to specify a SOCKS proxy at the same time --proxy is -used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first -connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or -HTTPS proxy. diff --git a/docs/cmdline-opts/socks4a.md b/docs/cmdline-opts/socks4a.md new file mode 100644 index 00000000000..49fb9a275a8 --- /dev/null +++ b/docs/cmdline-opts/socks4a.md @@ -0,0 +1,35 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: socks4a +Arg: +Help: SOCKS4a proxy on given host + port +Added: 7.18.0 +Category: proxy +Multi: single +See-also: + - socks4 + - socks5 + - socks5-hostname +Example: + - --socks4a hostname:4096 $URL +--- + +# `--socks4a` + +Use the specified SOCKS4a proxy. If the port number is not specified, it is +assumed at port 1080. This asks the proxy to resolve the hostname. + +To specify proxy on a unix domain socket, use localhost for host, e.g. +`socks4a://localhost/path/to/socket.sock` + +This option overrides any previous use of --proxy, as they are mutually +exclusive. + +This option is superfluous since you can specify a socks4a proxy with --proxy +using a socks4a:// protocol prefix. (Added in 7.21.7) + +--preproxy can be used to specify a SOCKS proxy at the same time --proxy is +used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first +connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or +HTTPS proxy. diff --git a/docs/cmdline-opts/socks5-basic.d b/docs/cmdline-opts/socks5-basic.d deleted file mode 100644 index a16831be188..00000000000 --- a/docs/cmdline-opts/socks5-basic.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: socks5-basic -Help: Enable username/password auth for SOCKS5 proxies -Added: 7.55.0 -Category: proxy auth -Example: --socks5-basic --socks5 hostname:4096 $URL -See-also: socks5 -Multi: mutex ---- -Tells curl to use username/password authentication when connecting to a SOCKS5 -proxy. The username/password authentication is enabled by default. Use ---socks5-gssapi to force GSS-API authentication to SOCKS5 proxies. diff --git a/docs/cmdline-opts/socks5-basic.md b/docs/cmdline-opts/socks5-basic.md new file mode 100644 index 00000000000..dc2a5532f11 --- /dev/null +++ b/docs/cmdline-opts/socks5-basic.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: socks5-basic +Help: Username/password auth for SOCKS5 proxies +Added: 7.55.0 +Category: proxy auth +Multi: mutex +See-also: + - socks5 +Example: + - --socks5-basic --socks5 hostname:4096 $URL +--- + +# `--socks5-basic` + +Use username/password authentication when connecting to a SOCKS5 proxy. The +username/password authentication is enabled by default. Use --socks5-gssapi to +force GSS-API authentication to SOCKS5 proxies. diff --git a/docs/cmdline-opts/socks5-gssapi-nec.d b/docs/cmdline-opts/socks5-gssapi-nec.d deleted file mode 100644 index 957655a0912..00000000000 --- a/docs/cmdline-opts/socks5-gssapi-nec.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: socks5-gssapi-nec -Help: Compatibility with NEC SOCKS5 server -Added: 7.19.4 -Category: proxy auth -Example: --socks5-gssapi-nec --socks5 hostname:4096 $URL -See-also: socks5 -Multi: boolean ---- -As part of the GSS-API negotiation a protection mode is negotiated. RFC 1961 -says in section 4.3/4.4 it should be protected, but the NEC reference -implementation does not. The option --socks5-gssapi-nec allows the -unprotected exchange of the protection mode negotiation. diff --git a/docs/cmdline-opts/socks5-gssapi-nec.md b/docs/cmdline-opts/socks5-gssapi-nec.md new file mode 100644 index 00000000000..eef6b2de9df --- /dev/null +++ b/docs/cmdline-opts/socks5-gssapi-nec.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: socks5-gssapi-nec +Help: Compatibility with NEC SOCKS5 server +Added: 7.19.4 +Category: proxy auth +Multi: boolean +See-also: + - socks5 +Example: + - --socks5-gssapi-nec --socks5 hostname:4096 $URL +--- + +# `--socks5-gssapi-nec` + +As part of the GSS-API negotiation a protection mode is negotiated. RFC 1961 +says in section 4.3/4.4 it should be protected, but the NEC reference +implementation does not. The option --socks5-gssapi-nec allows the +unprotected exchange of the protection mode negotiation. diff --git a/docs/cmdline-opts/socks5-gssapi-service.d b/docs/cmdline-opts/socks5-gssapi-service.d deleted file mode 100644 index 66c2f33a59a..00000000000 --- a/docs/cmdline-opts/socks5-gssapi-service.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: socks5-gssapi-service -Arg: -Help: SOCKS5 proxy service name for GSS-API -Added: 7.19.4 -Category: proxy auth -Example: --socks5-gssapi-service sockd --socks5 hostname:4096 $URL -See-also: socks5 -Multi: single ---- -The default service name for a socks server is **rcmd/server-fqdn**. This option -allows you to change it. diff --git a/docs/cmdline-opts/socks5-gssapi-service.md b/docs/cmdline-opts/socks5-gssapi-service.md new file mode 100644 index 00000000000..d847e65e247 --- /dev/null +++ b/docs/cmdline-opts/socks5-gssapi-service.md @@ -0,0 +1,18 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: socks5-gssapi-service +Arg: +Help: SOCKS5 proxy service name for GSS-API +Added: 7.19.4 +Category: proxy auth +Multi: single +See-also: + - socks5 +Example: + - --socks5-gssapi-service sockd --socks5 hostname:4096 $URL +--- + +# `--socks5-gssapi-service` + +Set the service name for a socks server. Default is **rcmd/server-fqdn**. diff --git a/docs/cmdline-opts/socks5-gssapi.d b/docs/cmdline-opts/socks5-gssapi.d deleted file mode 100644 index cec684f422f..00000000000 --- a/docs/cmdline-opts/socks5-gssapi.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: socks5-gssapi -Help: Enable GSS-API auth for SOCKS5 proxies -Added: 7.55.0 -Category: proxy auth -Example: --socks5-gssapi --socks5 hostname:4096 $URL -See-also: socks5 -Multi: boolean ---- -Tells curl to use GSS-API authentication when connecting to a SOCKS5 proxy. -The GSS-API authentication is enabled by default (if curl is compiled with -GSS-API support). Use --socks5-basic to force username/password authentication -to SOCKS5 proxies. diff --git a/docs/cmdline-opts/socks5-gssapi.md b/docs/cmdline-opts/socks5-gssapi.md new file mode 100644 index 00000000000..e17425431b3 --- /dev/null +++ b/docs/cmdline-opts/socks5-gssapi.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: socks5-gssapi +Help: Enable GSS-API auth for SOCKS5 proxies +Added: 7.55.0 +Category: proxy auth +Multi: boolean +See-also: + - socks5 +Example: + - --socks5-gssapi --socks5 hostname:4096 $URL +--- + +# `--socks5-gssapi` + +Use GSS-API authentication when connecting to a SOCKS5 proxy. The GSS-API +authentication is enabled by default (if curl is compiled with GSS-API +support). Use --socks5-basic to force username/password authentication to +SOCKS5 proxies. diff --git a/docs/cmdline-opts/socks5-hostname.d b/docs/cmdline-opts/socks5-hostname.d deleted file mode 100644 index ee49ca64262..00000000000 --- a/docs/cmdline-opts/socks5-hostname.d +++ /dev/null @@ -1,27 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: socks5-hostname -Arg: -Help: SOCKS5 proxy, pass host name to proxy -Added: 7.18.0 -Category: proxy -Example: --socks5-hostname proxy.example:7000 $URL -See-also: socks5 socks4a -Multi: single ---- -Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If -the port number is not specified, it is assumed at port 1080. - -To specify proxy on a unix domain socket, use localhost for host, e.g. -socks5h://localhost/path/to/socket.sock - -This option overrides any previous use of --proxy, as they are mutually -exclusive. - -This option is superfluous since you can specify a socks5 hostname proxy with ---proxy using a socks5h:// protocol prefix. (Added in 7.21.7) - ---preproxy can be used to specify a SOCKS proxy at the same time --proxy is -used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first -connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or -HTTPS proxy. diff --git a/docs/cmdline-opts/socks5-hostname.md b/docs/cmdline-opts/socks5-hostname.md new file mode 100644 index 00000000000..1a5e4c1b5e3 --- /dev/null +++ b/docs/cmdline-opts/socks5-hostname.md @@ -0,0 +1,34 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: socks5-hostname +Arg: +Help: SOCKS5 proxy, pass hostname to proxy +Added: 7.18.0 +Category: proxy +Multi: single +See-also: + - socks5 + - socks4a +Example: + - --socks5-hostname proxy.example:7000 $URL +--- + +# `--socks5-hostname` + +Use the specified SOCKS5 proxy (and let the proxy resolve the hostname). If +the port number is not specified, it is assumed at port 1080. + +To specify proxy on a unix domain socket, use localhost for host, e.g. +`socks5h://localhost/path/to/socket.sock` + +This option overrides any previous use of --proxy, as they are mutually +exclusive. + +This option is superfluous since you can specify a socks5 hostname proxy with +--proxy using a socks5h:// protocol prefix. (Added in 7.21.7) + +--preproxy can be used to specify a SOCKS proxy at the same time --proxy is +used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first +connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or +HTTPS proxy. diff --git a/docs/cmdline-opts/socks5.d b/docs/cmdline-opts/socks5.d deleted file mode 100644 index 0e52166ea2f..00000000000 --- a/docs/cmdline-opts/socks5.d +++ /dev/null @@ -1,29 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: socks5 -Arg: -Help: SOCKS5 proxy on given host + port -Added: 7.18.0 -Category: proxy -Example: --socks5 proxy.example:7000 $URL -See-also: socks5-hostname socks4a -Multi: single ---- -Use the specified SOCKS5 proxy - but resolve the host name locally. If the -port number is not specified, it is assumed at port 1080. - -To specify proxy on a unix domain socket, use localhost for host, e.g. -socks5://localhost/path/to/socket.sock - -This option overrides any previous use of --proxy, as they are mutually -exclusive. - -This option is superfluous since you can specify a socks5 proxy with --proxy -using a socks5:// protocol prefix. (Added in 7.21.7) - ---preproxy can be used to specify a SOCKS proxy at the same time --proxy is -used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first -connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or -HTTPS proxy. - -This option (as well as --socks4) does not work with IPV6, FTPS or LDAP. diff --git a/docs/cmdline-opts/socks5.md b/docs/cmdline-opts/socks5.md new file mode 100644 index 00000000000..f17dfeb71fa --- /dev/null +++ b/docs/cmdline-opts/socks5.md @@ -0,0 +1,36 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: socks5 +Arg: +Help: SOCKS5 proxy on given host + port +Added: 7.18.0 +Category: proxy +Multi: single +See-also: + - socks5-hostname + - socks4a +Example: + - --socks5 proxy.example:7000 $URL +--- + +# `--socks5` + +Use the specified SOCKS5 proxy - but resolve the hostname locally. If the +port number is not specified, it is assumed at port 1080. + +To specify proxy on a unix domain socket, use localhost for host, e.g. +`socks5://localhost/path/to/socket.sock` + +This option overrides any previous use of --proxy, as they are mutually +exclusive. + +This option is superfluous since you can specify a socks5 proxy with --proxy +using a socks5:// protocol prefix. (Added in 7.21.7) + +--preproxy can be used to specify a SOCKS proxy at the same time --proxy is +used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first +connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or +HTTPS proxy. + +This option (as well as --socks4) does not work with IPV6, FTPS or LDAP. diff --git a/docs/cmdline-opts/speed-limit.d b/docs/cmdline-opts/speed-limit.d deleted file mode 100644 index dc9778db9b6..00000000000 --- a/docs/cmdline-opts/speed-limit.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: speed-limit -Short: Y -Arg: -Help: Stop transfers slower than this -Category: connection -Example: --speed-limit 300 --speed-time 10 $URL -Added: 4.7 -See-also: speed-time limit-rate max-time -Multi: single ---- -If a transfer is slower than this given speed (in bytes per second) for -speed-time seconds it gets aborted. speed-time is set with --speed-time and is -30 if not set. diff --git a/docs/cmdline-opts/speed-limit.md b/docs/cmdline-opts/speed-limit.md new file mode 100644 index 00000000000..b95d6e7d49d --- /dev/null +++ b/docs/cmdline-opts/speed-limit.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: speed-limit +Short: Y +Arg: +Help: Stop transfers slower than this +Category: connection +Added: 4.7 +Multi: single +See-also: + - speed-time + - limit-rate + - max-time +Example: + - --speed-limit 300 --speed-time 10 $URL +--- + +# `--speed-limit` + +If a transfer is slower than this set speed (in bytes per second) for a given +number of seconds, it gets aborted. The time period is set with --speed-time +and is 30 seconds by default. diff --git a/docs/cmdline-opts/speed-time.d b/docs/cmdline-opts/speed-time.d deleted file mode 100644 index 4a8860660a5..00000000000 --- a/docs/cmdline-opts/speed-time.d +++ /dev/null @@ -1,18 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: speed-time -Short: y -Arg: -Help: Trigger 'speed-limit' abort after this time -Category: connection -Example: --speed-limit 300 --speed-time 10 $URL -Added: 4.7 -See-also: speed-limit limit-rate -Multi: single ---- -If a transfer runs slower than speed-limit bytes per second during a -speed-time period, the transfer is aborted. If speed-time is used, the default -speed-limit is 1 unless set with --speed-limit. - -This option controls transfers (in both directions) but does not affect slow -connects etc. If this is a concern for you, try the --connect-timeout option. diff --git a/docs/cmdline-opts/speed-time.md b/docs/cmdline-opts/speed-time.md new file mode 100644 index 00000000000..ef8759ee54b --- /dev/null +++ b/docs/cmdline-opts/speed-time.md @@ -0,0 +1,25 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: speed-time +Short: y +Arg: +Help: Trigger 'speed-limit' abort after this time +Category: connection +Added: 4.7 +Multi: single +See-also: + - speed-limit + - limit-rate +Example: + - --speed-limit 300 --speed-time 10 $URL +--- + +# `--speed-time` + +If a transfer runs slower than speed-limit bytes per second during a +speed-time period, the transfer is aborted. If speed-time is used, the default +speed-limit is 1 unless set with --speed-limit. + +This option controls transfers (in both directions) but does not affect slow +connects etc. If this is a concern for you, try the --connect-timeout option. diff --git a/docs/cmdline-opts/ssl-allow-beast.d b/docs/cmdline-opts/ssl-allow-beast.d deleted file mode 100644 index 2547675d640..00000000000 --- a/docs/cmdline-opts/ssl-allow-beast.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ssl-allow-beast -Help: Allow security flaw to improve interop -Added: 7.25.0 -Category: tls -Example: --ssl-allow-beast $URL -See-also: proxy-ssl-allow-beast insecure -Multi: boolean ---- -This option tells curl to not work around a security flaw in the SSL3 and -TLS1.0 protocols known as BEAST. If this option is not used, the SSL layer -may use workarounds known to cause interoperability problems with some older -SSL implementations. - -**WARNING**: this option loosens the SSL security, and by using this flag you -ask for exactly that. diff --git a/docs/cmdline-opts/ssl-allow-beast.md b/docs/cmdline-opts/ssl-allow-beast.md new file mode 100644 index 00000000000..29f2b450c2d --- /dev/null +++ b/docs/cmdline-opts/ssl-allow-beast.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ssl-allow-beast +Help: Allow security flaw to improve interop +Protocols: TLS +Added: 7.25.0 +Category: tls +Multi: boolean +See-also: + - proxy-ssl-allow-beast + - insecure +Example: + - --ssl-allow-beast $URL +--- + +# `--ssl-allow-beast` + +Do not work around a security flaw in the SSL3 and TLS1.0 protocols known as +BEAST. If this option is not used, the SSL layer may use workarounds known to +cause interoperability problems with some older SSL implementations. + +**WARNING**: this option loosens the SSL security, and by using this flag you +ask for exactly that. diff --git a/docs/cmdline-opts/ssl-auto-client-cert.d b/docs/cmdline-opts/ssl-auto-client-cert.d deleted file mode 100644 index 5328adea710..00000000000 --- a/docs/cmdline-opts/ssl-auto-client-cert.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ssl-auto-client-cert -Help: Use auto client certificate (Schannel) -Added: 7.77.0 -See-also: proxy-ssl-auto-client-cert -Category: tls -Example: --ssl-auto-client-cert $URL -Multi: boolean ---- -(Schannel) Tell libcurl to automatically locate and use a client certificate -for authentication, when requested by the server. Since the server can request -any certificate that supports client authentication in the OS certificate -store it could be a privacy violation and unexpected. diff --git a/docs/cmdline-opts/ssl-auto-client-cert.md b/docs/cmdline-opts/ssl-auto-client-cert.md new file mode 100644 index 00000000000..4f0be5bd7e7 --- /dev/null +++ b/docs/cmdline-opts/ssl-auto-client-cert.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ssl-auto-client-cert +Help: Use auto client certificate (Schannel) +Added: 7.77.0 +Category: tls +Protocols: TLS +Multi: boolean +See-also: + - proxy-ssl-auto-client-cert +Example: + - --ssl-auto-client-cert $URL +--- + +# `--ssl-auto-client-cert` + +(Schannel) Automatically locate and use a client certificate for +authentication, when requested by the server. Since the server can request any +certificate that supports client authentication in the OS certificate store it +could be a privacy violation and unexpected. diff --git a/docs/cmdline-opts/ssl-no-revoke.d b/docs/cmdline-opts/ssl-no-revoke.d deleted file mode 100644 index 37e91d9c204..00000000000 --- a/docs/cmdline-opts/ssl-no-revoke.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ssl-no-revoke -Help: Disable cert revocation checks (Schannel) -Added: 7.44.0 -Category: tls -Example: --ssl-no-revoke $URL -See-also: crlfile -Multi: boolean ---- -(Schannel) This option tells curl to disable certificate revocation checks. -WARNING: this option loosens the SSL security, and by using this flag you ask -for exactly that. diff --git a/docs/cmdline-opts/ssl-no-revoke.md b/docs/cmdline-opts/ssl-no-revoke.md new file mode 100644 index 00000000000..16981f14d12 --- /dev/null +++ b/docs/cmdline-opts/ssl-no-revoke.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ssl-no-revoke +Help: Disable cert revocation checks (Schannel) +Added: 7.44.0 +Protocols: TLS +Category: tls +Multi: boolean +See-also: + - crlfile +Example: + - --ssl-no-revoke $URL +--- + +# `--ssl-no-revoke` + +(Schannel) Disable certificate revocation checks. WARNING: this option loosens +the SSL security, and by using this flag you ask for exactly that. diff --git a/docs/cmdline-opts/ssl-reqd.d b/docs/cmdline-opts/ssl-reqd.d deleted file mode 100644 index 8a5b8577e06..00000000000 --- a/docs/cmdline-opts/ssl-reqd.d +++ /dev/null @@ -1,23 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ssl-reqd -Help: Require SSL/TLS -Protocols: FTP IMAP POP3 SMTP LDAP -Added: 7.20.0 -Category: tls -Example: --ssl-reqd ftp://example.com -See-also: ssl insecure -Multi: boolean ---- -Require SSL/TLS for the connection. Terminates the connection if the transfer -cannot be upgraded to use SSL/TLS. - -This option is handled in LDAP (added in 7.81.0). It is fully supported by the -OpenLDAP backend and rejected by the generic ldap backend if explicit TLS is -required. - -This option is unnecessary if you use a URL scheme that in itself implies -immediate and implicit use of TLS, like for FTPS, IMAPS, POP3S, SMTPS and -LDAPS. Such a transfer always fails if the TLS handshake does not work. - -This option was formerly known as --ftp-ssl-reqd. diff --git a/docs/cmdline-opts/ssl-reqd.md b/docs/cmdline-opts/ssl-reqd.md new file mode 100644 index 00000000000..eeabc0645bb --- /dev/null +++ b/docs/cmdline-opts/ssl-reqd.md @@ -0,0 +1,30 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ssl-reqd +Help: Require SSL/TLS +Protocols: FTP IMAP POP3 SMTP LDAP +Added: 7.20.0 +Category: tls +Multi: boolean +See-also: + - ssl + - insecure +Example: + - --ssl-reqd ftp://example.com +--- + +# `--ssl-reqd` + +Require SSL/TLS for the connection. Terminates the connection if the transfer +cannot be upgraded to use SSL/TLS. + +This option is handled in LDAP (added in 7.81.0). It is fully supported by the +OpenLDAP backend and rejected by the generic ldap backend if explicit TLS is +required. + +This option is unnecessary if you use a URL scheme that in itself implies +immediate and implicit use of TLS, like for FTPS, IMAPS, POP3S, SMTPS and +LDAPS. Such a transfer always fails if the TLS handshake does not work. + +This option was formerly known as --ftp-ssl-reqd. diff --git a/docs/cmdline-opts/ssl-revoke-best-effort.d b/docs/cmdline-opts/ssl-revoke-best-effort.d deleted file mode 100644 index cb26d0b9a09..00000000000 --- a/docs/cmdline-opts/ssl-revoke-best-effort.d +++ /dev/null @@ -1,13 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ssl-revoke-best-effort -Help: Ignore missing/offline cert CRL dist points (Schannel) -Added: 7.70.0 -Category: tls -Example: --ssl-revoke-best-effort $URL -See-also: crlfile insecure -Multi: boolean ---- -(Schannel) This option tells curl to ignore certificate revocation checks when -they failed due to missing/offline distribution points for the revocation check -lists. diff --git a/docs/cmdline-opts/ssl-revoke-best-effort.md b/docs/cmdline-opts/ssl-revoke-best-effort.md new file mode 100644 index 00000000000..0257e05f47e --- /dev/null +++ b/docs/cmdline-opts/ssl-revoke-best-effort.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ssl-revoke-best-effort +Help: Ignore missing cert CRL dist points +Added: 7.70.0 +Protocols: TLS +Category: tls +Multi: boolean +See-also: + - crlfile + - insecure +Example: + - --ssl-revoke-best-effort $URL +--- + +# `--ssl-revoke-best-effort` + +(Schannel) Ignore certificate revocation checks when they failed due to +missing/offline distribution points for the revocation check lists. diff --git a/docs/cmdline-opts/ssl.d b/docs/cmdline-opts/ssl.d deleted file mode 100644 index b8fd22a9ca3..00000000000 --- a/docs/cmdline-opts/ssl.d +++ /dev/null @@ -1,26 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: ssl -Help: Try SSL/TLS -Protocols: FTP IMAP POP3 SMTP LDAP -Added: 7.20.0 -Category: tls -Example: --ssl pop3://example.com/ -See-also: ssl-reqd insecure ciphers -Multi: boolean ---- -Warning: this is considered an insecure option. Consider using --ssl-reqd -instead to be sure curl upgrades to a secure connection. - -Try to use SSL/TLS for the connection. Reverts to a non-secure connection if -the server does not support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd -for different levels of encryption required. - -This option is handled in LDAP (added in 7.81.0). It is fully supported by the -OpenLDAP backend and ignored by the generic ldap backend. - -Please note that a server may close the connection if the negotiation does -not succeed. - -This option was formerly known as --ftp-ssl (added in 7.11.0). That option -name can still be used but might be removed in a future version. diff --git a/docs/cmdline-opts/ssl.md b/docs/cmdline-opts/ssl.md new file mode 100644 index 00000000000..73fa96ad641 --- /dev/null +++ b/docs/cmdline-opts/ssl.md @@ -0,0 +1,34 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: ssl +Help: Try enabling TLS +Protocols: FTP IMAP POP3 SMTP LDAP +Added: 7.20.0 +Category: tls +Multi: boolean +See-also: + - ssl-reqd + - insecure + - ciphers +Example: + - --ssl pop3://example.com/ +--- + +# `--ssl` + +Warning: this is considered an insecure option. Consider using --ssl-reqd +instead to be sure curl upgrades to a secure connection. + +Try to use SSL/TLS for the connection. Reverts to a non-secure connection if +the server does not support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd +for different levels of encryption required. + +This option is handled in LDAP (added in 7.81.0). It is fully supported by the +OpenLDAP backend and ignored by the generic ldap backend. + +Please note that a server may close the connection if the negotiation does +not succeed. + +This option was formerly known as --ftp-ssl (added in 7.11.0). That option +name can still be used but might be removed in a future version. diff --git a/docs/cmdline-opts/sslv2.d b/docs/cmdline-opts/sslv2.d deleted file mode 100644 index 3ecf109a09d..00000000000 --- a/docs/cmdline-opts/sslv2.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: 2 -Long: sslv2 -Tags: Versions -Protocols: SSL -Added: 5.9 -Mutexed: sslv3 tlsv1 tlsv1.1 tlsv1.2 -Requires: TLS -See-also: http1.1 http2 -Help: Use SSLv2 -Category: tls -Example: --sslv2 $URL -Multi: mutex ---- -This option previously asked curl to use SSLv2, but is now ignored -(added in 7.77.0). SSLv2 is widely considered insecure (see RFC 6176). diff --git a/docs/cmdline-opts/sslv2.md b/docs/cmdline-opts/sslv2.md new file mode 100644 index 00000000000..3bd36f02cd4 --- /dev/null +++ b/docs/cmdline-opts/sslv2.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: 2 +Long: sslv2 +Tags: Versions +Protocols: SSL +Added: 5.9 +Mutexed: sslv3 tlsv1 tlsv1.1 tlsv1.2 +Requires: TLS +Help: SSLv2 +Category: tls +Multi: mutex +See-also: + - http1.1 + - http2 +Example: + - --sslv2 $URL +--- + +# `--sslv2` + +This option previously asked curl to use SSLv2, but is now ignored +(added in 7.77.0). SSLv2 is widely considered insecure (see RFC 6176). diff --git a/docs/cmdline-opts/sslv3.d b/docs/cmdline-opts/sslv3.d deleted file mode 100644 index 409afc610f4..00000000000 --- a/docs/cmdline-opts/sslv3.d +++ /dev/null @@ -1,17 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Short: 3 -Long: sslv3 -Tags: Versions -Protocols: SSL -Added: 5.9 -Mutexed: sslv2 tlsv1 tlsv1.1 tlsv1.2 -Requires: TLS -See-also: http1.1 http2 -Help: Use SSLv3 -Category: tls -Example: --sslv3 $URL -Multi: mutex ---- -This option previously asked curl to use SSLv3, but is now ignored -(added in 7.77.0). SSLv3 is widely considered insecure (see RFC 7568). diff --git a/docs/cmdline-opts/sslv3.md b/docs/cmdline-opts/sslv3.md new file mode 100644 index 00000000000..32d4c120669 --- /dev/null +++ b/docs/cmdline-opts/sslv3.md @@ -0,0 +1,24 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Short: 3 +Long: sslv3 +Tags: Versions +Protocols: SSL +Added: 5.9 +Mutexed: sslv2 tlsv1 tlsv1.1 tlsv1.2 +Requires: TLS +Help: SSLv3 +Category: tls +Multi: mutex +See-also: + - http1.1 + - http2 +Example: + - --sslv3 $URL +--- + +# `--sslv3` + +This option previously asked curl to use SSLv3, but is now ignored +(added in 7.77.0). SSLv3 is widely considered insecure (see RFC 7568). diff --git a/docs/cmdline-opts/stderr.d b/docs/cmdline-opts/stderr.d deleted file mode 100644 index a80bf43d1cd..00000000000 --- a/docs/cmdline-opts/stderr.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: stderr -Arg: -Help: Where to redirect stderr -See-also: verbose silent -Category: verbose -Example: --stderr output.txt $URL -Added: 6.2 -Multi: single -Scope: global ---- -Redirect all writes to stderr to the specified file instead. If the file name -is a plain '-', it is instead written to stdout. diff --git a/docs/cmdline-opts/stderr.md b/docs/cmdline-opts/stderr.md new file mode 100644 index 00000000000..bb42497de33 --- /dev/null +++ b/docs/cmdline-opts/stderr.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: stderr +Arg: +Help: Where to redirect stderr +Category: verbose +Added: 6.2 +Multi: single +Scope: global +See-also: + - verbose + - silent +Example: + - --stderr output.txt $URL +--- + +# `--stderr` + +Redirect all writes to stderr to the specified file instead. If the filename +is a plain '-', it is instead written to stdout. diff --git a/docs/cmdline-opts/styled-output.d b/docs/cmdline-opts/styled-output.d deleted file mode 100644 index 70e9da4e84c..00000000000 --- a/docs/cmdline-opts/styled-output.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: styled-output -Help: Enable styled output for HTTP headers -Added: 7.61.0 -Category: verbose -Example: --styled-output -I $URL -See-also: head verbose -Multi: boolean -Scope: global ---- -Enables the automatic use of bold font styles when writing HTTP headers to the -terminal. Use --no-styled-output to switch them off. - -Styled output requires a terminal that supports bold fonts. This feature is -not present on curl for Windows due to lack of this capability. diff --git a/docs/cmdline-opts/styled-output.md b/docs/cmdline-opts/styled-output.md new file mode 100644 index 00000000000..bb324532bda --- /dev/null +++ b/docs/cmdline-opts/styled-output.md @@ -0,0 +1,23 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: styled-output +Help: Enable styled output for HTTP headers +Added: 7.61.0 +Category: verbose +Multi: boolean +Scope: global +See-also: + - head + - verbose +Example: + - --styled-output -I $URL +--- + +# `--styled-output` + +Enable automatic use of bold font styles when writing HTTP headers to the +terminal. Use --no-styled-output to switch them off. + +Styled output requires a terminal that supports bold fonts. This feature is +not present on curl for Windows due to lack of this capability. diff --git a/docs/cmdline-opts/suppress-connect-headers.d b/docs/cmdline-opts/suppress-connect-headers.d deleted file mode 100644 index ed38f36de8d..00000000000 --- a/docs/cmdline-opts/suppress-connect-headers.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: suppress-connect-headers -Help: Suppress proxy CONNECT response headers -See-also: dump-header include proxytunnel -Category: proxy -Example: --suppress-connect-headers --include -x proxy $URL -Added: 7.54.0 -Multi: boolean ---- -When --proxytunnel is used and a CONNECT request is made do not output proxy -CONNECT response headers. This option is meant to be used with --dump-header or ---include which are used to show protocol headers in the output. It has no -effect on debug options such as --verbose or --trace, or any statistics. diff --git a/docs/cmdline-opts/suppress-connect-headers.md b/docs/cmdline-opts/suppress-connect-headers.md new file mode 100644 index 00000000000..9e2eefea4c2 --- /dev/null +++ b/docs/cmdline-opts/suppress-connect-headers.md @@ -0,0 +1,22 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: suppress-connect-headers +Help: Suppress proxy CONNECT response headers +Category: proxy +Added: 7.54.0 +Multi: boolean +See-also: + - dump-header + - include + - proxytunnel +Example: + - --suppress-connect-headers --include -x proxy $URL +--- + +# `--suppress-connect-headers` + +When --proxytunnel is used and a CONNECT request is made do not output proxy +CONNECT response headers. This option is meant to be used with --dump-header or +--include which are used to show protocol headers in the output. It has no +effect on debug options such as --verbose or --trace, or any statistics. diff --git a/docs/cmdline-opts/tcp-fastopen.d b/docs/cmdline-opts/tcp-fastopen.d deleted file mode 100644 index bcf1edbff50..00000000000 --- a/docs/cmdline-opts/tcp-fastopen.d +++ /dev/null @@ -1,14 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: tcp-fastopen -Added: 7.49.0 -Help: Use TCP Fast Open -Category: connection -Example: --tcp-fastopen $URL -See-also: false-start -Multi: boolean ---- - -Enable use of TCP Fast Open (RFC 7413). TCP Fast Open is a TCP extension that -allows data to get sent earlier over the connection (before the final -handshake ACK) if the client and server have been connected previously. diff --git a/docs/cmdline-opts/tcp-fastopen.md b/docs/cmdline-opts/tcp-fastopen.md new file mode 100644 index 00000000000..9a7c2b0a0cd --- /dev/null +++ b/docs/cmdline-opts/tcp-fastopen.md @@ -0,0 +1,19 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: tcp-fastopen +Added: 7.49.0 +Help: Use TCP Fast Open +Category: connection +Multi: boolean +See-also: + - false-start +Example: + - --tcp-fastopen $URL +--- + +# `--tcp-fastopen` + +Enable use of TCP Fast Open (RFC 7413). TCP Fast Open is a TCP extension that +allows data to get sent earlier over the connection (before the final +handshake ACK) if the client and server have been connected previously. diff --git a/docs/cmdline-opts/tcp-nodelay.d b/docs/cmdline-opts/tcp-nodelay.d deleted file mode 100644 index 2bf51cb5f44..00000000000 --- a/docs/cmdline-opts/tcp-nodelay.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: tcp-nodelay -Help: Use the TCP_NODELAY option -Added: 7.11.2 -Category: connection -Example: --tcp-nodelay $URL -See-also: no-buffer -Multi: boolean ---- -Turn on the TCP_NODELAY option. See the *curl_easy_setopt(3)* man page for -details about this option. - -curl sets this option by default and you need to explicitly switch it off if -you do not want it on (added in 7.50.2). diff --git a/docs/cmdline-opts/tcp-nodelay.md b/docs/cmdline-opts/tcp-nodelay.md new file mode 100644 index 00000000000..6944d70142b --- /dev/null +++ b/docs/cmdline-opts/tcp-nodelay.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: tcp-nodelay +Help: Set TCP_NODELAY +Added: 7.11.2 +Category: connection +Multi: boolean +See-also: + - no-buffer +Example: + - --tcp-nodelay $URL +--- + +# `--tcp-nodelay` + +Turn on the TCP_NODELAY option. See the *curl_easy_setopt(3)* man page for +details about this option. + +curl sets this option by default and you need to explicitly switch it off if +you do not want it on (added in 7.50.2). diff --git a/docs/cmdline-opts/telnet-option.d b/docs/cmdline-opts/telnet-option.d deleted file mode 100644 index 651ce4203e7..00000000000 --- a/docs/cmdline-opts/telnet-option.d +++ /dev/null @@ -1,23 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: telnet-option -Short: t -Arg: -Help: Set telnet option -Category: telnet -Example: -t TTYPE=vt100 telnet://example.com/ -Added: 7.7 -See-also: config -Multi: append ---- -Pass options to the telnet protocol. Supported options are: - -.RS -.TP 15 -**TTYPE**= Sets the terminal type. -.TP -**XDISPLOC**= Sets the X display location. -.TP -**NEW_ENV**= Sets an environment variable. -.RE -.IP diff --git a/docs/cmdline-opts/telnet-option.md b/docs/cmdline-opts/telnet-option.md new file mode 100644 index 00000000000..a332b1a5cdd --- /dev/null +++ b/docs/cmdline-opts/telnet-option.md @@ -0,0 +1,28 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: telnet-option +Short: t +Arg: +Help: Set telnet option +Category: telnet +Added: 7.7 +Multi: append +See-also: + - config +Example: + - -t TTYPE=vt100 telnet://example.com/ +--- + +# `--telnet-option` + +Pass options to the telnet protocol. Supported options are: + +## `TTYPE=` +Sets the terminal type. + +## `XDISPLOC=` +Sets the X display location. + +## `NEW_ENV=` +Sets an environment variable. diff --git a/docs/cmdline-opts/tftp-blksize.d b/docs/cmdline-opts/tftp-blksize.d deleted file mode 100644 index 76c7ee4b137..00000000000 --- a/docs/cmdline-opts/tftp-blksize.d +++ /dev/null @@ -1,15 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: tftp-blksize -Arg: -Help: Set TFTP BLKSIZE option -Protocols: TFTP -Added: 7.20.0 -Category: tftp -Example: --tftp-blksize 1024 tftp://example.com/file -See-also: tftp-no-options -Multi: single ---- -Set the TFTP **BLKSIZE** option (must be >512). This is the block size that -curl tries to use when transferring data to or from a TFTP server. By -default 512 bytes are used. diff --git a/docs/cmdline-opts/tftp-blksize.md b/docs/cmdline-opts/tftp-blksize.md new file mode 100644 index 00000000000..21d8476af06 --- /dev/null +++ b/docs/cmdline-opts/tftp-blksize.md @@ -0,0 +1,21 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: tftp-blksize +Arg: +Help: Set TFTP BLKSIZE option +Protocols: TFTP +Added: 7.20.0 +Category: tftp +Multi: single +See-also: + - tftp-no-options +Example: + - --tftp-blksize 1024 tftp://example.com/file +--- + +# `--tftp-blksize` + +Set the TFTP **BLKSIZE** option (must be 512 or larger). This is the block +size that curl tries to use when transferring data to or from a TFTP +server. By default 512 bytes are used. diff --git a/docs/cmdline-opts/tftp-no-options.d b/docs/cmdline-opts/tftp-no-options.d deleted file mode 100644 index 43b1c00c473..00000000000 --- a/docs/cmdline-opts/tftp-no-options.d +++ /dev/null @@ -1,16 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: tftp-no-options -Help: Do not send any TFTP options -Protocols: TFTP -Added: 7.48.0 -Category: tftp -Example: --tftp-no-options tftp://192.168.0.1/ -See-also: tftp-blksize -Multi: boolean ---- -Tells curl not to send TFTP options requests. - -This option improves interop with some legacy servers that do not acknowledge -or properly implement TFTP options. When this option is used --tftp-blksize is -ignored. diff --git a/docs/cmdline-opts/tftp-no-options.md b/docs/cmdline-opts/tftp-no-options.md new file mode 100644 index 00000000000..063da92edb4 --- /dev/null +++ b/docs/cmdline-opts/tftp-no-options.md @@ -0,0 +1,20 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Long: tftp-no-options +Help: Do not send any TFTP options +Protocols: TFTP +Added: 7.48.0 +Category: tftp +Multi: boolean +See-also: + - tftp-blksize +Example: + - --tftp-no-options tftp://192.168.0.1/ +--- + +# `--tftp-no-options` + +Do not to send TFTP options requests. This improves interop with some legacy +servers that do not acknowledge or properly implement TFTP options. When this +option is used --tftp-blksize is ignored. diff --git a/docs/cmdline-opts/time-cond.d b/docs/cmdline-opts/time-cond.d deleted file mode 100644 index c21ed2853b6..00000000000 --- a/docs/cmdline-opts/time-cond.d +++ /dev/null @@ -1,27 +0,0 @@ -c: Copyright (C) Daniel Stenberg, , et al. -SPDX-License-Identifier: curl -Long: time-cond -Short: z -Arg: