From ee2e8bfa36323c8b549e7d826c1fe730c295df57 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Wed, 6 Dec 2023 00:58:59 -0800 Subject: [PATCH 001/509] github/labeler: update a missed key in the v5 upgrade Follow-up to ce03fe3ba --- .github/labeler.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/labeler.yml b/.github/labeler.yml index be585a69010..2c2de9b20a2 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -13,6 +13,8 @@ # 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). +# +# See https://github.com/actions/labeler/ for documentation on this file. appleOS: - all: @@ -181,7 +183,7 @@ documentation: - 'LICENSES/**' - 'README' - 'RELEASE-NOTES' - - AllGlobsToAllFiles: + - all-globs-to-all-files: # negative matches - '!**/CMakeLists.txt' - '!**/Makefile.am' From da8c1d15782c8161b455a7ee90197c16ae5edb90 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Dec 2023 09:40:30 +0100 Subject: [PATCH 002/509] dist: add tests/errorcodes.pl to the tarball Used by test 1477 Reported-by: Xi Ruoyao Follow-up to 0ca3a4ec9a7 Fixes #12462 Closes #12463 --- tests/Makefile.am | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/tests/Makefile.am b/tests/Makefile.am index 17e9ad04938..c6ae7a97afd 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -26,15 +26,17 @@ HTMLPAGES = testcurl.html runtests.html PDFPAGES = testcurl.pdf runtests.pdf MANDISTPAGES = runtests.1.dist testcurl.1.dist -EXTRA_DIST = appveyor.pm azure.pm badsymbols.pl check-deprecated.pl CMakeLists.txt \ - devtest.pl dictserver.py directories.pm disable-scan.pl error-codes.pl extern-scan.pl FILEFORMAT.md \ - processhelp.pm ftpserver.pl getpart.pm globalconfig.pm http-server.pl http2-server.pl \ - http3-server.pl manpage-scan.pl manpage-syntax.pl markdown-uppercase.pl mem-include-scan.pl \ - memanalyze.pl negtelnetserver.py nroff-scan.pl option-check.pl options-scan.pl \ - pathhelp.pm README.md rtspserver.pl runner.pm runtests.1 runtests.pl secureserver.pl \ - serverhelp.pm servers.pm smbserver.py sshhelp.pm sshserver.pl stunnel.pem symbol-scan.pl \ - testcurl.1 testcurl.pl testutil.pm tftpserver.pl util.py valgrind.pm \ - valgrind.supp version-scan.pl check-translatable-options.pl +EXTRA_DIST = appveyor.pm azure.pm badsymbols.pl check-deprecated.pl \ + CMakeLists.txt devtest.pl dictserver.py directories.pm disable-scan.pl \ + error-codes.pl extern-scan.pl FILEFORMAT.md processhelp.pm ftpserver.pl \ + getpart.pm globalconfig.pm http-server.pl http2-server.pl http3-server.pl \ + manpage-scan.pl manpage-syntax.pl markdown-uppercase.pl mem-include-scan.pl \ + memanalyze.pl negtelnetserver.py nroff-scan.pl option-check.pl \ + options-scan.pl pathhelp.pm README.md rtspserver.pl runner.pm runtests.1 \ + runtests.pl secureserver.pl serverhelp.pm servers.pm smbserver.py sshhelp.pm \ + sshserver.pl stunnel.pem symbol-scan.pl testcurl.1 testcurl.pl testutil.pm \ + tftpserver.pl util.py valgrind.pm valgrind.supp version-scan.pl \ + check-translatable-options.pl errorcodes.pl DISTCLEANFILES = configurehelp.pm From a2e75af3fb0074702a5d3fc7700e6f4f920cc610 Mon Sep 17 00:00:00 2001 From: Chris Sauer Date: Wed, 6 Dec 2023 01:16:36 -0800 Subject: [PATCH 003/509] cmake: fix typo Follow-up to aace27b Closes #12464 --- CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index a54c2fff921..4042f001baa 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -105,7 +105,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) From bda212911457c6fadfbba50be61afc4ca513fa56 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Wed, 6 Dec 2023 10:05:20 +0000 Subject: [PATCH 004/509] tidy-up: fix yamllint whitespace issues Closes #12466 --- .azure-pipelines.yml | 406 +++++----- .circleci/config.yml | 6 +- .cirrus.yml | 14 +- .github/scripts/spellcheck.yaml | 52 +- .github/workflows/awslc.yml | 226 +++--- .github/workflows/codeql-analysis.yml | 94 +-- .github/workflows/codespell.yml | 18 +- .github/workflows/configure-vs-cmake.yml | 44 +- .github/workflows/distcheck.yml | 166 ++-- .github/workflows/fuzz.yml | 54 +- .github/workflows/hacktoberfest-accepted.yml | 2 +- .github/workflows/label.yml | 6 +- .github/workflows/linkcheck.yml | 22 +- .github/workflows/linux.yml | 782 +++++++++---------- .github/workflows/linux32.yml | 102 +-- .github/workflows/macos.yml | 375 ++++----- .github/workflows/man-examples.yml | 14 +- .github/workflows/ngtcp2-linux.yml | 456 +++++------ .github/workflows/proselint.yml | 74 +- .github/workflows/quiche-linux.yml | 338 ++++---- .github/workflows/reuse.yml | 12 +- .github/workflows/spellcheck.yml | 78 +- .github/workflows/synopsis.yml | 10 +- .github/workflows/torture.yml | 102 +-- .github/workflows/wolfssl.yml | 124 +-- 25 files changed, 1789 insertions(+), 1788 deletions(-) diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml index bc3c98cf0e7..049e4673364 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.yml' + - '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.yml' + - '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 $(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 + 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)" diff --git a/.circleci/config.yml b/.circleci/config.yml index 11bb0ef7b26..fc4f5052502 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -527,9 +527,9 @@ workflows: # 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-x86-http-libressl-http2: + # jobs: + # - macos-x86-http-libressl-http2 macos-x86-http-torture: jobs: diff --git a/.cirrus.yml b/.cirrus.yml index 27b4659b119..8878205e5de 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -59,13 +59,13 @@ freebsd_task: 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/scripts/spellcheck.yaml b/.github/scripts/spellcheck.yaml index 4e4e13d48c1..5cf4f9a016a 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' diff --git a/.github/workflows/awslc.yml b/.github/workflows/awslc.yml index 2c38ca0a3b2..2505a46022f 100644 --- a/.github/workflows/awslc.yml +++ b/.github/workflows/awslc.yml @@ -7,31 +7,31 @@ name: Linux AWS-LC 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.yml' + - '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.yml' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: # Hardcoded workflow filename as workflow name above is just Linux again @@ -51,58 +51,58 @@ jobs: timeout-minutes: 30 steps: - - run: | - sudo apt-get update --yes - sudo apt-get install --yes libtool autoconf automake pkg-config stunnel4 - # ensure we don't pick up openssl in this build - sudo apt remove --yes libssl-dev - sudo python3 -m pip install impacket - name: 'install prereqs and impacket' - - - name: cache awslc - uses: actions/cache@v3 - id: cache-awslc - env: - cache-name: cache-awslc - with: - path: /home/runner/awslc - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.awslc-version }} - - - name: build awslc - if: steps.cache-awslc.outputs.cache-hit != 'true' - run: | - curl -LOsSf --retry 6 --retry-connrefused --max-time 999 \ - https://github.com/awslabs/aws-lc/archive/refs/tags/v${{ env.awslc-version }}.tar.gz - tar xzf v${{ env.awslc-version }}.tar.gz - mkdir aws-lc-${{ env.awslc-version }}-build - cd aws-lc-${{ env.awslc-version }}-build - cmake -DCMAKE_INSTALL_PREFIX=$HOME/awslc ../aws-lc-${{ env.awslc-version }} - cmake --build . --parallel - cmake --install . - - - uses: actions/checkout@v4 - - - run: autoreconf -fi - name: 'autoreconf' - - - run: | - mkdir build - cd build - ../configure --enable-warnings --enable-werror --with-openssl=$HOME/awslc - cd .. - name: 'configure out-of-tree' - - - run: make -C build V=1 - name: 'make' - - - run: make -C build V=1 examples - name: 'make examples' - - - run: make -C build V=1 -C tests - name: 'make tests' - - - run: make -C build V=1 test-ci - name: 'run tests' + - run: | + sudo apt-get update --yes + sudo apt-get install --yes libtool autoconf automake pkg-config stunnel4 + # ensure we don't pick up openssl in this build + sudo apt remove --yes libssl-dev + sudo python3 -m pip install impacket + name: 'install prereqs and impacket' + + - name: cache awslc + uses: actions/cache@v3 + id: cache-awslc + env: + cache-name: cache-awslc + with: + path: /home/runner/awslc + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.awslc-version }} + + - name: build awslc + if: steps.cache-awslc.outputs.cache-hit != 'true' + run: | + curl -LOsSf --retry 6 --retry-connrefused --max-time 999 \ + https://github.com/awslabs/aws-lc/archive/refs/tags/v${{ env.awslc-version }}.tar.gz + tar xzf v${{ env.awslc-version }}.tar.gz + mkdir aws-lc-${{ env.awslc-version }}-build + cd aws-lc-${{ env.awslc-version }}-build + cmake -DCMAKE_INSTALL_PREFIX=$HOME/awslc ../aws-lc-${{ env.awslc-version }} + cmake --build . --parallel + cmake --install . + + - uses: actions/checkout@v4 + + - run: autoreconf -fi + name: 'autoreconf' + + - run: | + mkdir build + cd build + ../configure --enable-warnings --enable-werror --with-openssl=$HOME/awslc + cd .. + name: 'configure out-of-tree' + + - run: make -C build V=1 + name: 'make' + + - run: make -C build V=1 examples + name: 'make examples' + + - run: make -C build V=1 -C tests + name: 'make tests' + + - run: make -C build V=1 test-ci + name: 'run tests' cmake: name: awslc (cmake) @@ -110,43 +110,43 @@ jobs: timeout-minutes: 15 steps: - - run: | - sudo apt-get update - sudo apt-get install cmake stunnel4 - # ensure we don't pick up openssl in this build - sudo apt remove --yes libssl-dev - sudo python3 -m pip install impacket - name: 'install prereqs and impacket' - - - name: cache awslc - uses: actions/cache@v3 - id: cache-awslc - env: - cache-name: cache-awslc - with: - path: /home/runner/awslc - key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.awslc-version }} - - - name: build awslc - if: steps.cache-awslc.outputs.cache-hit != 'true' - run: | - curl -LOsSf --retry 6 --retry-connrefused --max-time 999 \ - https://github.com/awslabs/aws-lc/archive/refs/tags/v${{ env.awslc-version }}.tar.gz - tar xzf v${{ env.awslc-version }}.tar.gz - mkdir aws-lc-${{ env.awslc-version }}-build - cd aws-lc-${{ env.awslc-version }}-build - cmake -DCMAKE_INSTALL_PREFIX=$HOME/awslc ../aws-lc-${{ env.awslc-version }} - cmake --build . --parallel - cmake --install . - - - uses: actions/checkout@v4 - - # CMAKE_COMPILE_WARNING_AS_ERROR is available in cmake 3.24 or later - - run: cmake -Bbuild -DOPENSSL_ROOT_DIR=$HOME/awslc -DBUILD_SHARED_LIBS=ON -DCMAKE_COMPILE_WARNING_AS_ERROR=ON . - name: 'cmake generate out-of-tree' - - - run: cmake --build build --parallel - name: 'cmake build' - - - run: cmake --install build --prefix $HOME/curl --strip - name: 'cmake install' + - run: | + sudo apt-get update + sudo apt-get install cmake stunnel4 + # ensure we don't pick up openssl in this build + sudo apt remove --yes libssl-dev + sudo python3 -m pip install impacket + name: 'install prereqs and impacket' + + - name: cache awslc + uses: actions/cache@v3 + id: cache-awslc + env: + cache-name: cache-awslc + with: + path: /home/runner/awslc + key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ env.awslc-version }} + + - name: build awslc + if: steps.cache-awslc.outputs.cache-hit != 'true' + run: | + curl -LOsSf --retry 6 --retry-connrefused --max-time 999 \ + https://github.com/awslabs/aws-lc/archive/refs/tags/v${{ env.awslc-version }}.tar.gz + tar xzf v${{ env.awslc-version }}.tar.gz + mkdir aws-lc-${{ env.awslc-version }}-build + cd aws-lc-${{ env.awslc-version }}-build + cmake -DCMAKE_INSTALL_PREFIX=$HOME/awslc ../aws-lc-${{ env.awslc-version }} + cmake --build . --parallel + cmake --install . + + - uses: actions/checkout@v4 + + # CMAKE_COMPILE_WARNING_AS_ERROR is available in cmake 3.24 or later + - run: cmake -Bbuild -DOPENSSL_ROOT_DIR=$HOME/awslc -DBUILD_SHARED_LIBS=ON -DCMAKE_COMPILE_WARNING_AS_ERROR=ON . + name: 'cmake generate out-of-tree' + + - run: cmake --build build --parallel + name: 'cmake build' + + - run: cmake --install build --prefix $HOME/curl --strip + name: 'cmake install' diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index f5f969491aa..800b01ac9d9 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.yml' + - '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.yml' + - '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@v2 + 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@v2 - # ℹ️ 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@v2 diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index 405d63915ad..f3cc4cd7280 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -7,18 +7,18 @@ 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: diff --git a/.github/workflows/configure-vs-cmake.yml b/.github/workflows/configure-vs-cmake.yml index 3131bc128e5..830c1460f3d 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 - - 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..8b908e0a5bc 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 + 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' 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@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' 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@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' 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@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' diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index 695e0def979..a382dcb6adb 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.yml' + - '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.yml' + - '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..ec2813c3ed2 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,7 @@ 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 + - 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..96f14561fbd 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.yml' + - '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.yml' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} @@ -60,375 +60,375 @@ 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/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 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 + + - 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 diff --git a/.github/workflows/linux32.yml b/.github/workflows/linux32.yml index 7c2d4cbf6ab..1afc9cac4f7 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.yml' + - '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.yml' + - '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..4a7d6917cca 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.yml' + - '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.yml' + - '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 + 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 ${{ 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..080cb4c2da2 100644 --- a/.github/workflows/man-examples.yml +++ b/.github/workflows/man-examples.yml @@ -7,17 +7,17 @@ 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' pull_request: branches: - - master + - master paths: - - 'docs/libcurl/curl_*.3' - - 'docs/libcurl/opts/*.3' + - 'docs/libcurl/curl_*.3' + - 'docs/libcurl/opts/*.3' jobs: verify: diff --git a/.github/workflows/ngtcp2-linux.yml b/.github/workflows/ngtcp2-linux.yml index e73eba8c148..3be5c108f23 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.yml' + - '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.yml' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: # Hardcoded workflow filename as workflow name above is just Linux again @@ -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@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 diff --git a/.github/workflows/proselint.yml b/.github/workflows/proselint.yml index b01133c3b8c..aead0b5b068 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,40 @@ 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 + } } - } - 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 -v docs/CHECKSRC.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..abc71a5725b 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.yml' + - '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.yml' + - 'CMake/**' + - 'packages/**' + - 'plan9/**' + - 'projects/**' + - 'winbuild/**' concurrency: # Hardcoded workflow filename as workflow name above is just Linux again @@ -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@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 diff --git a/.github/workflows/reuse.yml b/.github/workflows/reuse.yml index 0cb5295c7c0..27b33e2c8ab 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@v2 diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 4793cf19049..5eac83c7438 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -6,24 +6,24 @@ name: spell on: push: branches: - - master + - master paths: - - '**.md' - - '**.3' - - '**.1' - - '**/spellcheck.yml' - - '**/spellcheck.yaml' - - '**/wordlist.txt' + - '**.md' + - '**.3' + - '**.1' + - '**/spellcheck.yml' + - '**/spellcheck.yaml' + - '**/wordlist.txt' pull_request: branches: - - master + - master paths: - - '**.md' - - '**.3' - - '**.1' - - '**/spellcheck.yml' - - '**/spellcheck.yaml' - - '**/wordlist.txt' + - '**.md' + - '**.3' + - '**.1' + - '**/spellcheck.yml' + - '**/spellcheck.yaml' + - '**/wordlist.txt' permissions: {} @@ -31,36 +31,36 @@ 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: install pandoc + run: sudo apt-get install pandoc - - name: build curl.1 - run: | - autoreconf -fi - ./configure --without-ssl - make -C docs + - name: build curl.1 + run: | + autoreconf -fi + ./configure --without-ssl + make -C docs - - 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: 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: 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: 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: 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: 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: 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: 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: 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..98bdd476a19 100644 --- a/.github/workflows/synopsis.yml +++ b/.github/workflows/synopsis.yml @@ -7,15 +7,15 @@ 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: diff --git a/.github/workflows/torture.yml b/.github/workflows/torture.yml index fa70eecd4b0..b5f187d8c9e 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.yml' + - '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.yml' + - '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..f607c0bcc83 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.yml' + - '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.yml' + - '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 ${{ 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 }}" From 8b76591b6b09668c3f8029a11a163b039f3abc11 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Wed, 6 Dec 2023 17:54:08 +0000 Subject: [PATCH 005/509] tidy-up: fix yamllint whitespace issues in labeler.yml Follow-up to bda212911457c6fadfbba50be61afc4ca513fa56 #12466 Reviewed-by: Dan Fandrich Closes #12475 --- .github/labeler.yml | 808 ++++++++++++++++++++++---------------------- 1 file changed, 404 insertions(+), 404 deletions(-) diff --git a/.github/labeler.yml b/.github/labeler.yml index 2c2de9b20a2..2bd1fde8b73 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -17,479 +17,479 @@ # 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.yml' + - '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.d' + - '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/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' - - all-globs-to-all-files: - # negative matches - - '!**/CMakeLists.txt' - - '!**/Makefile.am' + - all: + - changed-files: + - any-glob-to-all-files: + - '**/*.md' + - '**/*.txt' + - '**/*.1' + - '**/*.3' + - 'CHANGES' + - 'docs/**' + - 'GIT-INFO' + - 'LICENSES/**' + - 'README' + - 'RELEASE-NOTES' + - 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*' + - '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_*.3' + - '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: + - '**/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' From a17f041bea199a67c45f756652a6d1aecda2573a Mon Sep 17 00:00:00 2001 From: YX Hao Date: Wed, 6 Dec 2023 22:42:00 +0800 Subject: [PATCH 006/509] lib: fix variable undeclared error caused by `infof` changes `--disable-verbose` yields `CURL_DISABLE_VERBOSE_STRINGS` defined. `infof` isn't `Curl_nop_stmt` anymore: dac293c. Follow-up to dac293c Closes #12470 --- lib/vauth/digest_sspi.c | 4 ++++ lib/vtls/schannel.c | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/lib/vauth/digest_sspi.c b/lib/vauth/digest_sspi.c index 02e36ea5ed8..4696f29adda 100644 --- a/lib/vauth/digest_sspi.c +++ b/lib/vauth/digest_sspi.c @@ -211,8 +211,10 @@ CURLcode Curl_auth_create_digest_md5_message(struct Curl_easy *data, if(status == SEC_E_INSUFFICIENT_MEMORY) return CURLE_OUT_OF_MEMORY; +#if !defined(CURL_DISABLE_VERBOSE_STRINGS) infof(data, "schannel: InitializeSecurityContext failed: %s", Curl_sspi_strerror(status, buffer, sizeof(buffer))); +#endif return CURLE_AUTH_ERROR; } @@ -603,8 +605,10 @@ CURLcode Curl_auth_create_digest_http_message(struct Curl_easy *data, if(status == SEC_E_INSUFFICIENT_MEMORY) return CURLE_OUT_OF_MEMORY; +#if !defined(CURL_DISABLE_VERBOSE_STRINGS) infof(data, "schannel: InitializeSecurityContext failed: %s", Curl_sspi_strerror(status, buffer, sizeof(buffer))); +#endif return CURLE_AUTH_ERROR; } diff --git a/lib/vtls/schannel.c b/lib/vtls/schannel.c index ae7f2956da6..8e1d5be8d80 100644 --- a/lib/vtls/schannel.c +++ b/lib/vtls/schannel.c @@ -2332,10 +2332,10 @@ schannel_recv(struct Curl_cfilter *cf, struct Curl_easy *data, else { #ifndef CURL_DISABLE_VERBOSE_STRINGS char buffer[STRERROR_LEN]; -#endif - *err = CURLE_RECV_ERROR; infof(data, "schannel: failed to read data from server: %s", Curl_sspi_strerror(sspi_status, buffer, sizeof(buffer))); +#endif + *err = CURLE_RECV_ERROR; goto cleanup; } } From 8b99e6f23ffbb29b7966efa15c28daa340a76025 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 6 Dec 2023 19:03:42 +0100 Subject: [PATCH 007/509] sectransp_ make TLSCipherNameForNumber() available in non-verbose config Reported-by: Cajus Pollmeier Closes #12476 Fixes #12474 --- lib/vtls/sectransp.c | 2 -- 1 file changed, 2 deletions(-) diff --git a/lib/vtls/sectransp.c b/lib/vtls/sectransp.c index 0a22ff60be5..e3205e3acdb 100644 --- a/lib/vtls/sectransp.c +++ b/lib/vtls/sectransp.c @@ -906,7 +906,6 @@ static OSStatus sectransp_bio_cf_out_write(SSLConnectionRef connection, return rtn; } -#ifndef CURL_DISABLE_VERBOSE_STRINGS CF_INLINE const char *TLSCipherNameForNumber(SSLCipherSuite cipher) { /* The first ciphers in the ciphertable are continuous. Here we do small @@ -925,7 +924,6 @@ CF_INLINE const char *TLSCipherNameForNumber(SSLCipherSuite cipher) } return ciphertable[SSL_NULL_WITH_NULL_NULL].name; } -#endif /* !CURL_DISABLE_VERBOSE_STRINGS */ #if CURL_BUILD_MAC CF_INLINE void GetDarwinVersionNumber(int *major, int *minor) From 45cf4755e71f920f1148e1309261bc50d576dd1a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Dec 2023 14:13:17 +0100 Subject: [PATCH 008/509] url: for disabled protocols, mention if found in redirect To help users better understand where the URL (and denied scheme) comes from. Also removed "in libcurl" from the message, since the disabling can be done by the application. The error message now says "not supported" or "disabled" depending on why it was denied: Protocol "hej" not supported Protocol "http" disabled And in redirects: Protocol "hej" not supported (in redirect) Protocol "http" disabled (in redirect) Reported-by: Mauricio Scheffer Fixes #12465 Closes #12469 --- lib/url.c | 5 +++-- tests/data/test1268 | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/lib/url.c b/lib/url.c index b81785fe2ec..7a270e51ed8 100644 --- a/lib/url.c +++ b/lib/url.c @@ -1680,8 +1680,9 @@ static CURLcode findprotocol(struct Curl_easy *data, /* The protocol was not found in the table, but we don't have to assign it to anything since it is already assigned to a dummy-struct in the create_conn() function when the connectdata struct is allocated. */ - failf(data, "Protocol \"%s\" not supported or disabled in " LIBCURL_NAME, - protostr); + failf(data, "Protocol \"%s\" %s%s", protostr, + p ? "disabled" : "not supported", + data->state.this_is_a_follow ? " (in redirect)":""); return CURLE_UNSUPPORTED_PROTOCOL; } diff --git a/tests/data/test1268 b/tests/data/test1268 index 806592fb895..05fe9d8e7fe 100644 --- a/tests/data/test1268 +++ b/tests/data/test1268 @@ -30,7 +30,7 @@ file name argument looks like a flag Warning: The file name argument '-k' looks like a flag. -curl: (1) Protocol "hej" not supported or disabled in libcurl +curl: (1) Protocol "hej" not supported # we expect an error since we provide a weird URL From f899e914315d220ecdc5fa976c0a569d0c25269f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Dec 2023 23:23:06 +0100 Subject: [PATCH 009/509] RELEASE-NOTES: synced Bumped to 8.5.1 --- RELEASE-NOTES | 405 ++--------------------------------------- include/curl/curlver.h | 6 +- 2 files changed, 18 insertions(+), 393 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 3f7dc99f682..a673f1106e6 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -1,206 +1,21 @@ -curl and libcurl 8.5.0 +curl and libcurl 8.5.1 Public curl releases: 253 Command line options: 258 curl_easy_setopt() options: 303 Public functions in libcurl: 93 - Contributors: 3039 + Contributors: 3042 This release includes the following changes: - o gnutls: support CURLSSLOPT_NATIVE_CA [31] - o HTTP3: ngtcp2 builds are no longer experimental [77] 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 cmake: fix typo [5] + o dist: add tests/errorcodes.pl to the tarball [6] + o lib: fix variable undeclared error caused by `infof` changes [2] + o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] + o url: for disabled protocols, mention if found in redirect [7] This release includes the following known bugs: @@ -215,204 +30,14 @@ 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) + Cajus Pollmeier, Chris Sauer, Dan Fandrich, Daniel Stenberg, + Mauricio Scheffer, Stefan Eissing, Viktor Szakats, Xi Ruoyao, YX Hao + (9 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=12474 + [2] = https://curl.se/bug/?i=12470 + [5] = https://curl.se/bug/?i=12464 + [6] = https://curl.se/bug/?i=12462 + [7] = https://curl.se/bug/?i=12466 diff --git a/include/curl/curlver.h b/include/curl/curlver.h index 1ff5de6147e..3d0c7279814 100644 --- a/include/curl/curlver.h +++ b/include/curl/curlver.h @@ -32,13 +32,13 @@ /* This is the version number of the libcurl package from which this header file origins: */ -#define LIBCURL_VERSION "8.5.0-DEV" +#define LIBCURL_VERSION "8.5.1-DEV" /* The numeric version number is also available "in parts" by using these defines: */ #define LIBCURL_VERSION_MAJOR 8 #define LIBCURL_VERSION_MINOR 5 -#define LIBCURL_VERSION_PATCH 0 +#define LIBCURL_VERSION_PATCH 1 /* This is the numeric version of the libcurl version number, meant for easier parsing and comparisons by programs. The LIBCURL_VERSION_NUM define will @@ -59,7 +59,7 @@ CURL_VERSION_BITS() macro since curl's own configure script greps for it and needs it to contain the full number. */ -#define LIBCURL_VERSION_NUM 0x080500 +#define LIBCURL_VERSION_NUM 0x080501 /* * This is the date and time when the full source package was created. The From c0dd06ecb39445958d327c67f79ca4cf2b21d2b6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Dec 2023 12:15:01 +0100 Subject: [PATCH 010/509] ftp: handle the PORT parsing without allocation Also reduces amount of *cpy() calls. Closes #12456 --- lib/ftp.c | 54 +++++++++++++++++++++++------------------------------- 1 file changed, 23 insertions(+), 31 deletions(-) diff --git a/lib/ftp.c b/lib/ftp.c index a8dcedf531e..c9ceaaac319 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -926,6 +926,8 @@ static CURLcode ftp_state_use_port(struct Curl_easy *data, bool possibly_non_local = TRUE; char buffer[STRERROR_LEN]; char *addr = NULL; + size_t addrlen = 0; + char ipstr[50]; /* Step 1, figure out what is requested, * accepted format : @@ -934,32 +936,17 @@ static CURLcode ftp_state_use_port(struct Curl_easy *data, if(data->set.str[STRING_FTPPORT] && (strlen(data->set.str[STRING_FTPPORT]) > 1)) { - -#ifdef ENABLE_IPV6 - size_t addrlen = INET6_ADDRSTRLEN > strlen(string_ftpport) ? - INET6_ADDRSTRLEN : strlen(string_ftpport); -#else - size_t addrlen = INET_ADDRSTRLEN > strlen(string_ftpport) ? - INET_ADDRSTRLEN : strlen(string_ftpport); -#endif - char *ip_start = string_ftpport; char *ip_end = NULL; - char *port_start = NULL; - char *port_sep = NULL; - - addr = calloc(1, addrlen + 1); - if(!addr) { - result = CURLE_OUT_OF_MEMORY; - goto out; - } #ifdef ENABLE_IPV6 if(*string_ftpport == '[') { /* [ipv6]:port(-range) */ - ip_start = string_ftpport + 1; - ip_end = strchr(string_ftpport, ']'); - if(ip_end) - strncpy(addr, ip_start, ip_end - ip_start); + char *ip_start = string_ftpport + 1; + ip_end = strchr(ip_start, ']'); + if(ip_end) { + addrlen = ip_end - ip_start; + addr = ip_start; + } } else #endif @@ -969,28 +956,27 @@ static CURLcode ftp_state_use_port(struct Curl_easy *data, } else { ip_end = strchr(string_ftpport, ':'); + addr = string_ftpport; if(ip_end) { /* either ipv6 or (ipv4|domain|interface):port(-range) */ + addrlen = ip_end - string_ftpport; #ifdef ENABLE_IPV6 if(Curl_inet_pton(AF_INET6, string_ftpport, &sa6->sin6_addr) == 1) { /* ipv6 */ port_min = port_max = 0; - strcpy(addr, string_ftpport); ip_end = NULL; /* this got no port ! */ } - else #endif - /* (ipv4|domain|interface):port(-range) */ - strncpy(addr, string_ftpport, ip_end - ip_start); } else /* ipv4|interface */ - strcpy(addr, string_ftpport); + addrlen = strlen(string_ftpport); } /* parse the port */ if(ip_end) { - port_start = strchr(ip_end, ':'); + char *port_sep = NULL; + char *port_start = strchr(ip_end, ':'); if(port_start) { port_min = curlx_ultous(strtoul(port_start + 1, NULL, 10)); port_sep = strchr(port_start, '-'); @@ -1011,22 +997,29 @@ static CURLcode ftp_state_use_port(struct Curl_easy *data, if(port_min > port_max) port_min = port_max = 0; - if(*addr != '\0') { + if(addrlen) { + DEBUGASSERT(addr); + if(addrlen >= sizeof(ipstr)) + goto out; + memcpy(ipstr, addr, addrlen); + ipstr[addrlen] = 0; + /* attempt to get the address of the given interface name */ switch(Curl_if2ip(conn->remote_addr->family, #ifdef ENABLE_IPV6 Curl_ipv6_scope(&conn->remote_addr->sa_addr), conn->scope_id, #endif - addr, hbuf, sizeof(hbuf))) { + ipstr, hbuf, sizeof(hbuf))) { case IF2IP_NOT_FOUND: /* not an interface, use the given string as host name instead */ - host = addr; + host = ipstr; break; case IF2IP_AF_NOT_SUPPORTED: goto out; case IF2IP_FOUND: host = hbuf; /* use the hbuf for host name */ + break; } } else @@ -1266,7 +1259,6 @@ static CURLcode ftp_state_use_port(struct Curl_easy *data, } if(portsock != CURL_SOCKET_BAD) Curl_socket_close(data, conn, portsock); - free(addr); return result; } From 63cdaefbc3a618f3d982ce239b3a9c1a7fd0e229 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Dec 2023 15:55:35 +0100 Subject: [PATCH 011/509] strdup: remove the memchr check from Curl_strndup It makes it possible to clone a binary chunk of data. Closes #12453 --- lib/strdup.c | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/lib/strdup.c b/lib/strdup.c index 2578441c317..50f0656b91b 100644 --- a/lib/strdup.c +++ b/lib/strdup.c @@ -104,18 +104,14 @@ void *Curl_memdup(const void *src, size_t length) * Curl_strndup(source, length) * * Copies the 'source' string to a newly allocated buffer (that is returned). - * Copies not more than 'length' bytes (up to a null terminator) then adds a - * null terminator. + * Copies 'length' bytes then adds a null terminator. * * Returns the new pointer or NULL on failure. * ***************************************************************************/ void *Curl_strndup(const char *src, size_t length) { - char *buf = memchr(src, '\0', length); - if(buf) - length = buf - src; - buf = malloc(length + 1); + char *buf = malloc(length + 1); if(!buf) return NULL; memcpy(buf, src, length); From 7309b9cbbf1dac71dc538e16082bbdb4642f023c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Dec 2023 15:55:35 +0100 Subject: [PATCH 012/509] lib: strndup/memdup instead of malloc, memcpy and null-terminate - bufref: use strndup - cookie: use strndup - formdata: use strndup - ftp: use strndup - gtls: use aprintf instead of malloc + strcpy * 2 - http: use strndup - mbedtls: use strndup - md4: use memdup - ntlm: use memdup - ntlm_sspi: use strndup - pingpong: use memdup - rtsp: use strndup instead of malloc, memcpy and null-terminate - sectransp: use strndup - socks_gssapi.c: use memdup - vtls: use dynbuf instead of malloc, snprintf and memcpy - vtls: use strdup instead of malloc + memcpy - wolfssh: use strndup Closes #12453 --- lib/bufref.c | 6 ++---- lib/cookie.c | 4 +--- lib/formdata.c | 4 +--- lib/ftp.c | 7 +++---- lib/http.c | 10 +--------- lib/md4.c | 6 ++---- lib/pingpong.c | 7 +++---- lib/rtsp.c | 6 ++---- lib/socks_gssapi.c | 7 +++---- lib/vauth/ntlm.c | 6 +++--- lib/vauth/ntlm_sspi.c | 6 +++--- lib/vssh/wolfssh.c | 11 +++-------- lib/vtls/gtls.c | 6 +----- lib/vtls/mbedtls.c | 11 +++++------ lib/vtls/sectransp.c | 11 ++++------- lib/vtls/vtls.c | 31 +++++++++++-------------------- 16 files changed, 48 insertions(+), 91 deletions(-) diff --git a/lib/bufref.c b/lib/bufref.c index ce686b6f377..013eba10b2e 100644 --- a/lib/bufref.c +++ b/lib/bufref.c @@ -25,6 +25,7 @@ #include "curl_setup.h" #include "urldata.h" #include "bufref.h" +#include "strdup.h" #include "curl_memory.h" #include "memdebug.h" @@ -116,12 +117,9 @@ CURLcode Curl_bufref_memdup(struct bufref *br, const void *ptr, size_t len) DEBUGASSERT(len <= CURL_MAX_INPUT_LENGTH); if(ptr) { - cpy = malloc(len + 1); + cpy = Curl_strndup(ptr, len); if(!cpy) return CURLE_OUT_OF_MEMORY; - if(len) - memcpy(cpy, ptr, len); - cpy[len] = '\0'; } Curl_bufref_set(br, cpy, len, curl_free); diff --git a/lib/cookie.c b/lib/cookie.c index 9095cea3e97..156322a9046 100644 --- a/lib/cookie.c +++ b/lib/cookie.c @@ -821,10 +821,8 @@ Curl_cookie_add(struct Curl_easy *data, endslash = memrchr(path, '/', (queryp - path)); if(endslash) { size_t pathlen = (endslash-path + 1); /* include end slash */ - co->path = malloc(pathlen + 1); /* one extra for the zero byte */ + co->path = Curl_strndup(path, pathlen); if(co->path) { - memcpy(co->path, path, pathlen); - co->path[pathlen] = 0; /* null-terminate */ co->spath = sanitize_cookie_path(co->path); if(!co->spath) badcookie = TRUE; /* out of memory bad */ diff --git a/lib/formdata.c b/lib/formdata.c index 05dc9b53d68..81ed5fe61d0 100644 --- a/lib/formdata.c +++ b/lib/formdata.c @@ -779,11 +779,9 @@ static CURLcode setname(curl_mimepart *part, const char *name, size_t len) if(!name || !len) return curl_mime_name(part, name); - zname = malloc(len + 1); + zname = Curl_strndup(name, len); if(!zname) return CURLE_OUT_OF_MEMORY; - memcpy(zname, name, len); - zname[len] = '\0'; res = curl_mime_name(part, zname); free(zname); return res; diff --git a/lib/ftp.c b/lib/ftp.c index c9ceaaac319..ae98530e922 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -72,6 +72,7 @@ #include "warnless.h" #include "http_proxy.h" #include "socks.h" +#include "strdup.h" /* The last 3 #include files should be in this order */ #include "curl_printf.h" #include "curl_memory.h" @@ -4169,13 +4170,12 @@ CURLcode ftp_parse_url_path(struct Curl_easy *data) return CURLE_OUT_OF_MEMORY; } - ftpc->dirs[0] = calloc(1, dirlen + 1); + ftpc->dirs[0] = Curl_strndup(rawPath, dirlen); if(!ftpc->dirs[0]) { free(rawPath); return CURLE_OUT_OF_MEMORY; } - strncpy(ftpc->dirs[0], rawPath, dirlen); ftpc->dirdepth = 1; /* we consider it to be a single dir */ fileName = slashPos + 1; /* rest is file name */ } @@ -4214,12 +4214,11 @@ CURLcode ftp_parse_url_path(struct Curl_easy *data) CWD requires a parameter and a non-existent parameter a) doesn't work on many servers and b) has no effect on the others. */ if(compLen > 0) { - char *comp = calloc(1, compLen + 1); + char *comp = Curl_strndup(curPos, compLen); if(!comp) { free(rawPath); return CURLE_OUT_OF_MEMORY; } - strncpy(comp, curPos, compLen); ftpc->dirs[ftpc->dirdepth++] = comp; } curPos = slashPos + 1; diff --git a/lib/http.c b/lib/http.c index be6d442e8b8..2597937623e 100644 --- a/lib/http.c +++ b/lib/http.c @@ -297,7 +297,6 @@ char *Curl_copy_header_value(const char *header) { const char *start; const char *end; - char *value; size_t len; /* Find the end of the header name */ @@ -330,14 +329,7 @@ char *Curl_copy_header_value(const char *header) /* get length of the type */ len = end - start + 1; - value = malloc(len + 1); - if(!value) - return NULL; - - memcpy(value, start, len); - value[len] = 0; /* null-terminate */ - - return value; + return Curl_strndup(start, len); } #ifndef CURL_DISABLE_HTTP_AUTH diff --git a/lib/md4.c b/lib/md4.c index 486e5fa6a03..067c211e420 100644 --- a/lib/md4.c +++ b/lib/md4.c @@ -194,11 +194,9 @@ static int MD4_Init(MD4_CTX *ctx) static void MD4_Update(MD4_CTX *ctx, const void *data, unsigned long size) { if(!ctx->data) { - ctx->data = malloc(size); - if(ctx->data) { - memcpy(ctx->data, data, size); + ctx->data = Curl_memdup(data, size); + if(ctx->data) ctx->size = size; - } } } diff --git a/lib/pingpong.c b/lib/pingpong.c index 0081c9ca623..2e062e2496d 100644 --- a/lib/pingpong.c +++ b/lib/pingpong.c @@ -36,6 +36,7 @@ #include "pingpong.h" #include "multiif.h" #include "vtls/vtls.h" +#include "strdup.h" /* The last 3 #include files should be in this order */ #include "curl_printf.h" @@ -424,10 +425,8 @@ CURLcode Curl_pp_readresp(struct Curl_easy *data, if(clipamount) { pp->cache_size = clipamount; - pp->cache = malloc(pp->cache_size); - if(pp->cache) - memcpy(pp->cache, pp->linestart_resp, pp->cache_size); - else + pp->cache = Curl_memdup(pp->linestart_resp, pp->cache_size); + if(!pp->cache) return CURLE_OUT_OF_MEMORY; } if(restart) { diff --git a/lib/rtsp.c b/lib/rtsp.c index e673bb8dc0f..f05ee727ebf 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -922,7 +922,7 @@ CURLcode Curl_rtsp_parseheader(struct Curl_easy *data, char *header) /* If the Session ID is set, then compare */ if(strlen(data->set.str[STRING_RTSP_SESSION_ID]) != idlen || - strncmp(start, data->set.str[STRING_RTSP_SESSION_ID], idlen) != 0) { + strncmp(start, data->set.str[STRING_RTSP_SESSION_ID], idlen)) { failf(data, "Got RTSP Session ID Line [%s], but wanted ID [%s]", start, data->set.str[STRING_RTSP_SESSION_ID]); return CURLE_RTSP_SESSION_ERROR; @@ -934,11 +934,9 @@ CURLcode Curl_rtsp_parseheader(struct Curl_easy *data, char *header) */ /* Copy the id substring into a new buffer */ - data->set.str[STRING_RTSP_SESSION_ID] = malloc(idlen + 1); + data->set.str[STRING_RTSP_SESSION_ID] = Curl_strndup(start, idlen); if(!data->set.str[STRING_RTSP_SESSION_ID]) return CURLE_OUT_OF_MEMORY; - memcpy(data->set.str[STRING_RTSP_SESSION_ID], start, idlen); - (data->set.str[STRING_RTSP_SESSION_ID])[idlen] = '\0'; } } else if(checkprefix("Transport:", header)) { diff --git a/lib/socks_gssapi.c b/lib/socks_gssapi.c index 2ede8c7c29a..243715055c2 100644 --- a/lib/socks_gssapi.c +++ b/lib/socks_gssapi.c @@ -35,6 +35,7 @@ #include "timeval.h" #include "socks.h" #include "warnless.h" +#include "strdup.h" /* The last 3 #include files should be in this order */ #include "curl_printf.h" @@ -139,10 +140,9 @@ CURLcode Curl_SOCKS5_gssapi_negotiate(struct Curl_cfilter *cf, /* prepare service name */ if(strchr(serviceptr, '/')) { service.length = serviceptr_length; - service.value = malloc(service.length); + service.value = Curl_memdup(serviceptr, service.length); if(!service.value) return CURLE_OUT_OF_MEMORY; - memcpy(service.value, serviceptr, service.length); gss_major_status = gss_import_name(&gss_minor_status, &service, (gss_OID) GSS_C_NULL_OID, &server); @@ -387,12 +387,11 @@ CURLcode Curl_SOCKS5_gssapi_negotiate(struct Curl_cfilter *cf, } else { gss_send_token.length = 1; - gss_send_token.value = malloc(1); + gss_send_token.value = Curl_memdup(&gss_enc, 1); if(!gss_send_token.value) { gss_delete_sec_context(&gss_status, &gss_context, NULL); return CURLE_OUT_OF_MEMORY; } - memcpy(gss_send_token.value, &gss_enc, 1); gss_major_status = gss_wrap(&gss_minor_status, gss_context, 0, GSS_C_QOP_DEFAULT, &gss_send_token, diff --git a/lib/vauth/ntlm.c b/lib/vauth/ntlm.c index ed7cee8deff..018e6a67ef0 100644 --- a/lib/vauth/ntlm.c +++ b/lib/vauth/ntlm.c @@ -44,6 +44,7 @@ #include "warnless.h" #include "rand.h" #include "vtls/vtls.h" +#include "strdup.h" #define BUILDING_CURL_NTLM_MSGS_C #include "vauth/vauth.h" @@ -184,11 +185,10 @@ static CURLcode ntlm_decode_type2_target(struct Curl_easy *data, } free(ntlm->target_info); /* replace any previous data */ - ntlm->target_info = malloc(target_info_len); + ntlm->target_info = Curl_memdup(&type2[target_info_offset], + target_info_len); if(!ntlm->target_info) return CURLE_OUT_OF_MEMORY; - - memcpy(ntlm->target_info, &type2[target_info_offset], target_info_len); } } diff --git a/lib/vauth/ntlm_sspi.c b/lib/vauth/ntlm_sspi.c index 5118963f4da..06079a6ffc6 100644 --- a/lib/vauth/ntlm_sspi.c +++ b/lib/vauth/ntlm_sspi.c @@ -34,6 +34,7 @@ #include "warnless.h" #include "curl_multibyte.h" #include "sendf.h" +#include "strdup.h" /* The last #include files should be: */ #include "curl_memory.h" @@ -213,11 +214,10 @@ CURLcode Curl_auth_decode_ntlm_type2_message(struct Curl_easy *data, } /* Store the challenge for later use */ - ntlm->input_token = malloc(Curl_bufref_len(type2) + 1); + ntlm->input_token = Curl_strndup((const char *)Curl_bufref_ptr(type2), + Curl_bufref_len(type2)); if(!ntlm->input_token) return CURLE_OUT_OF_MEMORY; - memcpy(ntlm->input_token, Curl_bufref_ptr(type2), Curl_bufref_len(type2)); - ntlm->input_token[Curl_bufref_len(type2)] = '\0'; ntlm->input_token_len = Curl_bufref_len(type2); return CURLE_OK; diff --git a/lib/vssh/wolfssh.c b/lib/vssh/wolfssh.c index 4da7e9dea6f..8d152d43c73 100644 --- a/lib/vssh/wolfssh.c +++ b/lib/vssh/wolfssh.c @@ -42,6 +42,7 @@ #include "select.h" #include "multiif.h" #include "warnless.h" +#include "strdup.h" /* The last 3 #include files should be in this order */ #include "curl_printf.h" @@ -512,15 +513,9 @@ static CURLcode wssh_statemach_act(struct Curl_easy *data, bool *block) return CURLE_OK; } else if(name && (rc == WS_SUCCESS)) { - sshc->homedir = malloc(name->fSz + 1); - if(!sshc->homedir) { + sshc->homedir = Curl_strndup(name->fName, name->fSz); + if(!sshc->homedir) sshc->actualcode = CURLE_OUT_OF_MEMORY; - } - else { - memcpy(sshc->homedir, name->fName, name->fSz); - sshc->homedir[name->fSz] = 0; - infof(data, "wolfssh SFTP realpath succeeded"); - } wolfSSH_SFTPNAME_list_free(name); state(data, SSH_STOP); return CURLE_OK; diff --git a/lib/vtls/gtls.c b/lib/vtls/gtls.c index 4e337f5dd3d..f42b6d6691d 100644 --- a/lib/vtls/gtls.c +++ b/lib/vtls/gtls.c @@ -584,13 +584,9 @@ CURLcode gtls_client_init(struct Curl_easy *data, /* Only add SRP to the cipher list if SRP is requested. Otherwise * GnuTLS will disable TLS 1.3 support. */ if(config->username) { - size_t len = strlen(prioritylist); - - char *prioritysrp = malloc(len + sizeof(GNUTLS_SRP) + 1); + char *prioritysrp = aprintf("%s:" GNUTLS_SRP, prioritylist); if(!prioritysrp) return CURLE_OUT_OF_MEMORY; - strcpy(prioritysrp, prioritylist); - strcpy(prioritysrp + len, ":" GNUTLS_SRP); rc = gnutls_priority_set_direct(gtls->session, prioritysrp, &err); free(prioritysrp); diff --git a/lib/vtls/mbedtls.c b/lib/vtls/mbedtls.c index 38f7de7f753..f0fb7f3e421 100644 --- a/lib/vtls/mbedtls.c +++ b/lib/vtls/mbedtls.c @@ -67,6 +67,7 @@ #include "select.h" #include "multiif.h" #include "mbedtls_threadlock.h" +#include "strdup.h" /* The last 3 #include files should be in this order */ #include "curl_printf.h" @@ -367,11 +368,10 @@ mbed_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) /* Unfortunately, mbedtls_x509_crt_parse() requires the data to be null terminated even when provided the exact length, forcing us to waste extra memory here. */ - unsigned char *newblob = malloc(ca_info_blob->len + 1); + unsigned char *newblob = Curl_strndup(ca_info_blob->data, + ca_info_blob->len); if(!newblob) return CURLE_OUT_OF_MEMORY; - memcpy(newblob, ca_info_blob->data, ca_info_blob->len); - newblob[ca_info_blob->len] = 0; /* null terminate */ ret = mbedtls_x509_crt_parse(&backend->cacert, newblob, ca_info_blob->len + 1); free(newblob); @@ -441,11 +441,10 @@ mbed_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) /* Unfortunately, mbedtls_x509_crt_parse() requires the data to be null terminated even when provided the exact length, forcing us to waste extra memory here. */ - unsigned char *newblob = malloc(ssl_cert_blob->len + 1); + unsigned char *newblob = Curl_strndup(ssl_cert_blob->data, + ssl_cert_blob->len); if(!newblob) return CURLE_OUT_OF_MEMORY; - memcpy(newblob, ssl_cert_blob->data, ssl_cert_blob->len); - newblob[ssl_cert_blob->len] = 0; /* null terminate */ ret = mbedtls_x509_crt_parse(&backend->clicert, newblob, ssl_cert_blob->len + 1); free(newblob); diff --git a/lib/vtls/sectransp.c b/lib/vtls/sectransp.c index e3205e3acdb..19c00e0350d 100644 --- a/lib/vtls/sectransp.c +++ b/lib/vtls/sectransp.c @@ -2367,19 +2367,16 @@ static CURLcode verify_cert(struct Curl_cfilter *cf, const struct curl_blob *ca_info_blob, SSLContextRef ctx) { - int result; + CURLcode result; unsigned char *certbuf; size_t buflen; if(ca_info_blob) { CURL_TRC_CF(data, cf, "verify_peer, CA from config blob"); - certbuf = (unsigned char *)malloc(ca_info_blob->len + 1); - if(!certbuf) { + certbuf = (unsigned char *)Curl_strndup(ca_info_blob->data, + buflen = ca_info_blob->len); + if(!certbuf) return CURLE_OUT_OF_MEMORY; - } - buflen = ca_info_blob->len; - memcpy(certbuf, ca_info_blob->data, ca_info_blob->len); - certbuf[ca_info_blob->len]='\0'; } else if(cafile) { CURL_TRC_CF(data, cf, "verify_peer, CA from file '%s'", cafile); diff --git a/lib/vtls/vtls.c b/lib/vtls/vtls.c index 34eda3e5a0d..9980d4405b1 100644 --- a/lib/vtls/vtls.c +++ b/lib/vtls/vtls.c @@ -883,28 +883,21 @@ CURLcode Curl_ssl_push_certinfo_len(struct Curl_easy *data, size_t valuelen) { struct curl_certinfo *ci = &data->info.certs; - char *output; struct curl_slist *nl; CURLcode result = CURLE_OK; - size_t labellen = strlen(label); - size_t outlen = labellen + 1 + valuelen + 1; /* label:value\0 */ + struct dynbuf build; - output = malloc(outlen); - if(!output) - return CURLE_OUT_OF_MEMORY; - - /* sprintf the label and colon */ - msnprintf(output, outlen, "%s:", label); + Curl_dyn_init(&build, 10000); - /* memcpy the value (it might not be null-terminated) */ - memcpy(&output[labellen + 1], value, valuelen); - - /* null-terminate the output */ - output[labellen + 1 + valuelen] = 0; + if(Curl_dyn_add(&build, label) || + Curl_dyn_addn(&build, ":", 1) || + Curl_dyn_addn(&build, value, valuelen)) + return CURLE_OUT_OF_MEMORY; - nl = Curl_slist_append_nodup(ci->certinfo[certnum], output); + nl = Curl_slist_append_nodup(ci->certinfo[certnum], + Curl_dyn_ptr(&build)); if(!nl) { - free(output); + Curl_dyn_free(&build); curl_slist_free_all(ci->certinfo[certnum]); result = CURLE_OUT_OF_MEMORY; } @@ -1002,7 +995,7 @@ CURLcode Curl_pin_peer_pubkey(struct Curl_easy *data, /* only do this if pinnedpubkey starts with "sha256//", length 8 */ if(strncmp(pinnedpubkey, "sha256//", 8) == 0) { CURLcode encode; - size_t encodedlen = 0, pinkeylen; + size_t encodedlen = 0; char *encoded = NULL, *pinkeycopy, *begin_pos, *end_pos; unsigned char *sha256sumdigest; @@ -1030,13 +1023,11 @@ CURLcode Curl_pin_peer_pubkey(struct Curl_easy *data, infof(data, " public key hash: sha256//%s", encoded); /* it starts with sha256//, copy so we can modify it */ - pinkeylen = strlen(pinnedpubkey) + 1; - pinkeycopy = malloc(pinkeylen); + pinkeycopy = strdup(pinnedpubkey); if(!pinkeycopy) { Curl_safefree(encoded); return CURLE_OUT_OF_MEMORY; } - memcpy(pinkeycopy, pinnedpubkey, pinkeylen); /* point begin_pos to the copy, and start extracting keys */ begin_pos = pinkeycopy; do { From 4dbc7acc19195d6b20347a4dd914090ff9bf1c89 Mon Sep 17 00:00:00 2001 From: MAntoniak <47522782+MAntoniak@users.noreply.github.com> Date: Tue, 5 Dec 2023 23:49:12 +0100 Subject: [PATCH 013/509] vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY Closes #12459 --- lib/curl_trc.c | 2 ++ lib/vtls/vtls.c | 15 ++++++++++++++- lib/vtls/vtls.h | 2 ++ 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/lib/curl_trc.c b/lib/curl_trc.c index 0ebe40b8f72..b8dccc41937 100644 --- a/lib/curl_trc.c +++ b/lib/curl_trc.c @@ -157,8 +157,10 @@ static struct Curl_cftype *cf_types[] = { #endif #ifdef USE_SSL &Curl_cft_ssl, +#ifndef CURL_DISABLE_PROXY &Curl_cft_ssl_proxy, #endif +#endif #if !defined(CURL_DISABLE_PROXY) #if !defined(CURL_DISABLE_HTTP) &Curl_cft_h1_proxy, diff --git a/lib/vtls/vtls.c b/lib/vtls/vtls.c index 9980d4405b1..dd68a066367 100644 --- a/lib/vtls/vtls.c +++ b/lib/vtls/vtls.c @@ -1846,6 +1846,8 @@ struct Curl_cftype Curl_cft_ssl = { ssl_cf_query, }; +#ifndef CURL_DISABLE_PROXY + struct Curl_cftype Curl_cft_ssl_proxy = { "SSL-PROXY", CF_TYPE_SSL, @@ -1864,6 +1866,8 @@ struct Curl_cftype Curl_cft_ssl_proxy = { Curl_cf_def_query, }; +#endif /* !CURL_DISABLE_PROXY */ + static CURLcode cf_ssl_create(struct Curl_cfilter **pcf, struct Curl_easy *data, struct connectdata *conn) @@ -1971,8 +1975,12 @@ bool Curl_ssl_supports(struct Curl_easy *data, int option) static struct Curl_cfilter *get_ssl_filter(struct Curl_cfilter *cf) { for(; cf; cf = cf->next) { - if(cf->cft == &Curl_cft_ssl || cf->cft == &Curl_cft_ssl_proxy) + if(cf->cft == &Curl_cft_ssl) + return cf; +#ifndef CURL_DISABLE_PROXY + if(cf->cft == &Curl_cft_ssl_proxy) return cf; +#endif } return NULL; } @@ -2018,7 +2026,12 @@ CURLcode Curl_ssl_cfilter_remove(struct Curl_easy *data, bool Curl_ssl_cf_is_proxy(struct Curl_cfilter *cf) { +#ifndef CURL_DISABLE_PROXY return (cf->cft == &Curl_cft_ssl_proxy); +#else + (void)cf; + return FALSE; +#endif } struct ssl_config_data * diff --git a/lib/vtls/vtls.h b/lib/vtls/vtls.h index f1856bd333b..744bbf8fd9e 100644 --- a/lib/vtls/vtls.h +++ b/lib/vtls/vtls.h @@ -228,7 +228,9 @@ struct ssl_primary_config * Curl_ssl_cf_get_primary_config(struct Curl_cfilter *cf); extern struct Curl_cftype Curl_cft_ssl; +#ifndef CURL_DISABLE_PROXY extern struct Curl_cftype Curl_cft_ssl_proxy; +#endif #else /* if not USE_SSL */ From ca6bafce95365fadd906a533bb16e47b638c5c2a Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 6 Dec 2023 12:08:20 +0100 Subject: [PATCH 014/509] test_02_download: fix paramters to test_02_27 - it is a special client that only ever uses http/2 Closes #12467 --- tests/http/test_02_download.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/tests/http/test_02_download.py b/tests/http/test_02_download.py index 391371c31c0..4db9c9d36e9 100644 --- a/tests/http/test_02_download.py +++ b/tests/http/test_02_download.py @@ -386,13 +386,10 @@ def test_02_26_session_shared_reuse(self, env: Env, httpd, repeat): r.check_exit_code(0) # test on paused transfers, based on issue #11982 - @pytest.mark.parametrize("proto", ['h2', 'h3']) - def test_02_27_paused_no_cl(self, env: Env, httpd, nghttpx, proto, repeat): - if proto == 'h3' and not env.have_h3(): - pytest.skip("h3 not supported") + def test_02_27_paused_no_cl(self, env: Env, httpd, nghttpx, repeat): + proto = 'h2' url = f'https://{env.authority_for(env.domain1, proto)}' \ - f'/tweak?'\ - '&chunks=2&chunk_size=16000' + '/tweak?&chunks=2&chunk_size=16000' client = LocalClient(env=env, name='h2-pausing') r = client.run(args=[url]) r.check_exit_code(0) From ede2e812c22fd42527acffdbafd98ee90eaa0dbe Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Thu, 7 Dec 2023 19:06:02 +0000 Subject: [PATCH 015/509] tidy-up: whitespace Closes #12484 --- .github/scripts/verify-examples.pl | 1 - .github/scripts/verify-synopsis.pl | 1 - docs/libcurl/curl_mime_headers.3 | 1 - docs/libcurl/curl_multi_cleanup.3 | 1 - docs/libcurl/curl_multi_init.3 | 1 - docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 | 1 - docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 | 1 - docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 | 1 - docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 | 1 - docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 | 2 -- docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 | 1 - docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 | 1 - docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 | 1 - docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 | 2 -- docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 | 1 - docs/libcurl/opts/CURLOPT_STDERR.3 | 1 - docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 | 1 - docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 | 1 - docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 | 1 - docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 | 1 - docs/libcurl/opts/CURLOPT_USERAGENT.3 | 1 - docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 | 1 - m4/curl-functions.m4 | 4 ++-- projects/generate.bat | 4 ++-- tests/ftpserver.pl | 2 +- tests/http/clients/.gitignore | 2 +- 26 files changed, 6 insertions(+), 30 deletions(-) diff --git a/.github/scripts/verify-examples.pl b/.github/scripts/verify-examples.pl index ff275569e15..0b750711ea1 100755 --- a/.github/scripts/verify-examples.pl +++ b/.github/scripts/verify-examples.pl @@ -90,4 +90,3 @@ sub extract { } } exit $error; - diff --git a/.github/scripts/verify-synopsis.pl b/.github/scripts/verify-synopsis.pl index 34f15a8e0cb..9d32185035e 100755 --- a/.github/scripts/verify-synopsis.pl +++ b/.github/scripts/verify-synopsis.pl @@ -78,4 +78,3 @@ sub extract { $error |= testcompile($m); } exit $error; - diff --git a/docs/libcurl/curl_mime_headers.3 b/docs/libcurl/curl_mime_headers.3 index dd6a4166944..109663c386a 100644 --- a/docs/libcurl/curl_mime_headers.3 +++ b/docs/libcurl/curl_mime_headers.3 @@ -81,4 +81,3 @@ CURLE_OK or a CURL error code upon failure. .SH "SEE ALSO" .BR curl_mime_addpart (3), .BR curl_mime_name (3) - diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 index 751bce9fd92..5b4aae26cef 100644 --- a/docs/libcurl/curl_multi_cleanup.3 +++ b/docs/libcurl/curl_multi_cleanup.3 @@ -68,4 +68,3 @@ CURLM_OK is returned. .BR curl_multi_get_handles (3), .BR curl_easy_init (3), .BR curl_multi_init (3) - diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index 9b589a11ec0..4501a003196 100644 --- a/docs/libcurl/curl_multi_init.3 +++ b/docs/libcurl/curl_multi_init.3 @@ -60,4 +60,3 @@ other curl functions. .BR curl_multi_get_handles (3), .BR curl_global_init (3), .BR curl_easy_init (3) - diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 index 24230c04687..5f5dd766ae8 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 @@ -68,4 +68,3 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .BR curl_easy_setopt (3), .BR CURLINFO_SIZE_DOWNLOAD_T (3), .BR CURLINFO_SIZE_UPLOAD (3) - diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 index b17d282815a..5bf2c285b58 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 @@ -68,4 +68,3 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .BR curl_easy_setopt (3), .BR CURLINFO_SIZE_UPLOAD_T (3), .BR CURLINFO_SPEED_UPLOAD_T (3) - diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 index f90c7729506..5ec1a450e7f 100644 --- a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 @@ -79,4 +79,3 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .BR CURLOPT_MAXFILESIZE (3), .BR CURLOPT_UPLOAD_BUFFERSIZE (3), .BR CURLOPT_WRITEFUNCTION (3) - diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 index f2f8628b461..9d1a9fd4ca2 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 @@ -131,4 +131,3 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .BR CURLOPT_CLOSESOCKETFUNCTION (3), .BR CURLOPT_OPENSOCKETFUNCTION (3), .BR CURLOPT_SOCKOPTFUNCTION (3) - diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 index 5bfa0ccdc2a..702d979197d 100644 --- a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 +++ b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 @@ -75,5 +75,3 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .BR CURLOPT_STDERR (3), .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_URL (3) - - diff --git a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 index 9a9ce119c32..631d42f8067 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 @@ -119,4 +119,3 @@ CURLE_OUT_OF_MEMORY if there was insufficient heap space. .BR CURLOPT_PROXY_CAPATH (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3) - diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 index 82a5bf9c29b..ce79f44a6fa 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 @@ -77,4 +77,3 @@ CURLE_OUT_OF_MEMORY if there was insufficient heap space. .BR CURLOPT_SSLCERT (3), .BR CURLOPT_SSLKEY (3), .BR CURLOPT_SSLKEYTYPE (3) - diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 index d64d17ccc70..fd187add897 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 @@ -78,4 +78,3 @@ Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. .BR CURLOPT_SSL_CIPHER_LIST (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_TLS13_CIPHERS (3) - diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 index bc9ea693d0e..2388a16860f 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 @@ -63,5 +63,3 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLOPT_SOCKS5_GSSAPI_SERVICE (3), .BR CURLOPT_PROXY (3) - - diff --git a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 index 65b5407d54d..ef123896b54 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 @@ -61,4 +61,3 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .BR CURLOPT_SSL_OPTIONS (3), .BR CURLOPT_SSL_CIPHER_LIST (3), .BR CURLOPT_TLS13_CIPHERS (3) - diff --git a/docs/libcurl/opts/CURLOPT_STDERR.3 b/docs/libcurl/opts/CURLOPT_STDERR.3 index 949841ddada..79a97d45c7e 100644 --- a/docs/libcurl/opts/CURLOPT_STDERR.3 +++ b/docs/libcurl/opts/CURLOPT_STDERR.3 @@ -65,4 +65,3 @@ Returns CURLE_OK .BR CURLOPT_VERBOSE (3), .BR CURLOPT_NOPROGRESS (3), .BR CURLOPT_DEBUGFUNCTION (3) - diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 index c84173d8542..c26ba812d3a 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 @@ -80,4 +80,3 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .BR CURLOPT_HTTP_VERSION (3), .BR CURLOPT_STREAM_DEPENDS (3), .BR CURLOPT_STREAM_WEIGHT (3) - diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 index dcd3ea79a6f..3b66a4ce3ae 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 @@ -63,4 +63,3 @@ Added in 7.19.4 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLOPT_MAXFILESIZE (3) - diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 index ed910a3d70f..0d61d129103 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 @@ -107,4 +107,3 @@ Returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_TRAILERDATA (3), .BR CURLOPT_WRITEFUNCTION (3) - diff --git a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 index 020bfec9ec5..dff01dc8678 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 +++ b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 @@ -65,4 +65,3 @@ Along with FTP Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLOPT_CRLF (3) - diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.3 b/docs/libcurl/opts/CURLOPT_USERAGENT.3 index bcb6a3c63a7..1ed5a7bc5f6 100644 --- a/docs/libcurl/opts/CURLOPT_USERAGENT.3 +++ b/docs/libcurl/opts/CURLOPT_USERAGENT.3 @@ -66,4 +66,3 @@ CURLE_OUT_OF_MEMORY if there was insufficient heap space. .BR CURLOPT_HTTPHEADER (3), .BR CURLOPT_REFERER (3), .BR CURLOPT_REQUEST_TARGET (3) - diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 index 0dc5242fdb8..98ac90f1eba 100644 --- a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 @@ -67,4 +67,3 @@ CURLE_OUT_OF_MEMORY if there was insufficient heap space. .SH "SEE ALSO" .BR CURLOPT_MAIL_AUTH (3), .BR CURLOPT_USERNAME (3) - diff --git a/m4/curl-functions.m4 b/m4/curl-functions.m4 index 28f4b8b9acb..a3275673a27 100644 --- a/m4/curl-functions.m4 +++ b/m4/curl-functions.m4 @@ -1796,8 +1796,8 @@ AC_DEFUN([CURL_CHECK_FUNC_GETADDRINFO], [ #ifdef HAVE_WINSOCK2_H WSADATA wsa; - if (WSAStartup(MAKEWORD(2,2), &wsa)) - exit(2); + if(WSAStartup(MAKEWORD(2, 2), &wsa)) + exit(2); #endif memset(&hints, 0, sizeof(hints)); diff --git a/projects/generate.bat b/projects/generate.bat index 7156a1731ae..a110adffc3d 100644 --- a/projects/generate.bat +++ b/projects/generate.bat @@ -58,7 +58,7 @@ rem *************************************************************************** set VERSION=VC14.10 ) else if /i "%~1" == "vc14.20" ( set VERSION=VC14.20 - )else if /i "%~1" == "vc14.30" ( + ) else if /i "%~1" == "vc14.30" ( set VERSION=VC14.30 ) else if /i "%~1" == "-clean" ( set MODE=CLEAN @@ -167,7 +167,7 @@ rem *************************************************************************** ) if not "%VERSION%" == "ALL" goto success - + :vc14.20 echo. diff --git a/tests/ftpserver.pl b/tests/ftpserver.pl index d0be36f1544..cd798f0b976 100755 --- a/tests/ftpserver.pl +++ b/tests/ftpserver.pl @@ -412,7 +412,7 @@ sub sysread_or_die { sub startsf { my @mainsockfcmd = ("./server/sockfilt".exe_ext('SRV'), "--ipv$ipvnum", - "--port", $port, + "--port", $port, "--pidfile", $mainsockf_pidfile, "--portfile", $portfile, "--logfile", $mainsockf_logfile); diff --git a/tests/http/clients/.gitignore b/tests/http/clients/.gitignore index 8d885e16e04..f461524b3ea 100644 --- a/tests/http/clients/.gitignore +++ b/tests/http/clients/.gitignore @@ -8,4 +8,4 @@ ws-data ws-pingpong h2-upgrade-extreme tls-session-reuse -h2-pausing \ No newline at end of file +h2-pausing From 13a1d1ace82bf5999bed8e2382c6ebaae40f5953 Mon Sep 17 00:00:00 2001 From: MAntoniak <47522782+MAntoniak@users.noreply.github.com> Date: Fri, 8 Dec 2023 01:07:38 +0100 Subject: [PATCH 016/509] sendf: fix compiler warning with CURL_DISABLE_HEADERS_API fix MSVC warning C4189: 'htype': local variable is initialized but not referenced - when CURL_DISABLE_HEADERS_API is defined. Closes #12485 --- lib/sendf.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/sendf.c b/lib/sendf.c index a2fac0c4e90..1bdab916532 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -345,7 +345,7 @@ static CURLcode chop_write(struct Curl_easy *data, len -= chunklen; } -#ifndef CURL_DISABLE_HTTP +#if !defined(CURL_DISABLE_HTTP) && !defined(CURL_DISABLE_HEADERS_API) /* HTTP header, but not status-line */ if((conn->handler->protocol & PROTO_FAMILY_HTTP) && (type & CLIENTWRITE_HEADER) && !(type & CLIENTWRITE_STATUS) ) { From c386065878eb1e0ecb7b7fa07138ece2f110a1fa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 8 Dec 2023 09:34:05 +0100 Subject: [PATCH 017/509] tests: rename tests scripts to the test number It is hard to name the scripts sensibly. Lots of them are similarly named and the name did not tell which test that used them. The new approach is rather to name them based on the test number that runs them. Also helps us see which scripts are for individual tests rather than for general test infra. - badsymbols.pl -> test1167.pl - check-deprecated.pl -> test1222.pl - check-translatable-options.pl -> test1544.pl - disable-scan.pl -> test1165.pl - error-codes.pl -> test1175.pl - errorcodes.pl -> test1477.pl - extern-scan.pl -> test1135.pl - manpage-scan.pl -> test1139.pl - manpage-syntax.pl -> test1173.pl - markdown-uppercase.pl -> test1275.pl - mem-include-scan.pl -> test1132.pl - nroff-scan.pl -> test1140.pl - option-check.pl -> test1276.pl - options-scan.pl -> test971.pl - symbol-scan.pl -> test1119.pl - version-scan.pl -> test1177.pl Closes #12487 --- tests/Makefile.am | 40 +++++++++++++------ tests/data/test1119 | 2 +- tests/data/test1132 | 2 +- tests/data/test1135 | 2 +- tests/data/test1139 | 2 +- tests/data/test1140 | 2 +- tests/data/test1165 | 2 +- tests/data/test1167 | 2 +- tests/data/test1173 | 2 +- tests/data/test1175 | 2 +- tests/data/test1177 | 2 +- tests/data/test1222 | 2 +- tests/data/test1275 | 2 +- tests/data/test1276 | 2 +- tests/data/test1279 | 2 +- tests/data/test1477 | 2 +- tests/data/test1544 | 2 +- tests/data/test971 | 2 +- tests/{symbol-scan.pl => test1119.pl} | 0 tests/{mem-include-scan.pl => test1132.pl} | 0 tests/{extern-scan.pl => test1135.pl} | 0 tests/{manpage-scan.pl => test1139.pl} | 0 tests/{nroff-scan.pl => test1140.pl} | 0 tests/{disable-scan.pl => test1165.pl} | 0 tests/{badsymbols.pl => test1167.pl} | 0 tests/{manpage-syntax.pl => test1173.pl} | 0 tests/{error-codes.pl => test1175.pl} | 0 tests/{version-scan.pl => test1177.pl} | 0 tests/{check-deprecated.pl => test1222.pl} | 0 tests/{markdown-uppercase.pl => test1275.pl} | 0 tests/{option-check.pl => test1276.pl} | 0 tests/{errorcodes.pl => test1477.pl} | 0 ...ck-translatable-options.pl => test1544.pl} | 0 tests/{options-scan.pl => test971.pl} | 0 34 files changed, 44 insertions(+), 30 deletions(-) rename tests/{symbol-scan.pl => test1119.pl} (100%) rename tests/{mem-include-scan.pl => test1132.pl} (100%) rename tests/{extern-scan.pl => test1135.pl} (100%) rename tests/{manpage-scan.pl => test1139.pl} (100%) rename tests/{nroff-scan.pl => test1140.pl} (100%) rename tests/{disable-scan.pl => test1165.pl} (100%) rename tests/{badsymbols.pl => test1167.pl} (100%) rename tests/{manpage-syntax.pl => test1173.pl} (100%) rename tests/{error-codes.pl => test1175.pl} (100%) rename tests/{version-scan.pl => test1177.pl} (100%) rename tests/{check-deprecated.pl => test1222.pl} (100%) rename tests/{markdown-uppercase.pl => test1275.pl} (100%) rename tests/{option-check.pl => test1276.pl} (100%) rename tests/{errorcodes.pl => test1477.pl} (100%) rename tests/{check-translatable-options.pl => test1544.pl} (100%) rename tests/{options-scan.pl => test971.pl} (100%) diff --git a/tests/Makefile.am b/tests/Makefile.am index c6ae7a97afd..b1fc25b0f8c 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -22,21 +22,35 @@ # ########################################################################### -HTMLPAGES = testcurl.html runtests.html -PDFPAGES = testcurl.pdf runtests.pdf MANDISTPAGES = runtests.1.dist testcurl.1.dist -EXTRA_DIST = appveyor.pm azure.pm badsymbols.pl check-deprecated.pl \ - CMakeLists.txt devtest.pl dictserver.py directories.pm disable-scan.pl \ - error-codes.pl extern-scan.pl FILEFORMAT.md processhelp.pm ftpserver.pl \ - getpart.pm globalconfig.pm http-server.pl http2-server.pl http3-server.pl \ - manpage-scan.pl manpage-syntax.pl markdown-uppercase.pl mem-include-scan.pl \ - memanalyze.pl negtelnetserver.py nroff-scan.pl option-check.pl \ - options-scan.pl pathhelp.pm README.md rtspserver.pl runner.pm runtests.1 \ - runtests.pl secureserver.pl serverhelp.pm servers.pm smbserver.py sshhelp.pm \ - sshserver.pl stunnel.pem symbol-scan.pl testcurl.1 testcurl.pl testutil.pm \ - tftpserver.pl util.py valgrind.pm valgrind.supp version-scan.pl \ - check-translatable-options.pl errorcodes.pl +# scripts used in test cases +TESTSCRIPTS = \ + test1119.pl \ + test1132.pl \ + test1135.pl \ + test1139.pl \ + test1140.pl \ + test1165.pl \ + test1167.pl \ + test1173.pl \ + test1175.pl \ + test1177.pl \ + test1222.pl \ + test1275.pl \ + test1276.pl \ + test1477.pl \ + test1544.pl \ + test971.pl + +EXTRA_DIST = appveyor.pm azure.pm CMakeLists.txt devtest.pl \ + dictserver.py directories.pm FILEFORMAT.md processhelp.pm ftpserver.pl \ + getpart.pm globalconfig.pm http-server.pl http2-server.pl \ + http3-server.pl memanalyze.pl negtelnetserver.py pathhelp.pm README.md \ + rtspserver.pl runner.pm runtests.1 runtests.pl secureserver.pl \ + serverhelp.pm servers.pm smbserver.py sshhelp.pm sshserver.pl \ + stunnel.pem testcurl.1 testcurl.pl testutil.pm tftpserver.pl util.py \ + valgrind.pm valgrind.supp $(TESTSCRIPTS) DISTCLEANFILES = configurehelp.pm diff --git a/tests/data/test1119 b/tests/data/test1119 index 41f6dba2c16..1a73439e605 100644 --- a/tests/data/test1119 +++ b/tests/data/test1119 @@ -18,7 +18,7 @@ Verify that symbols-in-versions and headers are in sync -%SRCDIR/symbol-scan.pl %SRCDIR/.. ../include/curl +%SRCDIR/test1119.pl %SRCDIR/.. ../include/curl diff --git a/tests/data/test1132 b/tests/data/test1132 index 613031bac83..e7a802a71a0 100644 --- a/tests/data/test1132 +++ b/tests/data/test1132 @@ -18,7 +18,7 @@ Verify memory #include files in libcurl's C source files -%SRCDIR/mem-include-scan.pl %SRCDIR/../lib +%SRCDIR/test1132.pl %SRCDIR/../lib diff --git a/tests/data/test1135 b/tests/data/test1135 index d188989ed6c..de028a0c9a9 100644 --- a/tests/data/test1135 +++ b/tests/data/test1135 @@ -22,7 +22,7 @@ Verify CURL_EXTERN order -%SRCDIR/extern-scan.pl %SRCDIR/.. +%SRCDIR/test1135.pl %SRCDIR/.. diff --git a/tests/data/test1139 b/tests/data/test1139 index b5267b012d7..2704e0a2173 100644 --- a/tests/data/test1139 +++ b/tests/data/test1139 @@ -20,7 +20,7 @@ Verify that all libcurl options have man pages -%SRCDIR/manpage-scan.pl %SRCDIR/.. %PWD/.. +%SRCDIR/test1139.pl %SRCDIR/.. %PWD/.. diff --git a/tests/data/test1140 b/tests/data/test1140 index 5aa997e7898..fc2a08d0141 100644 --- a/tests/data/test1140 +++ b/tests/data/test1140 @@ -19,7 +19,7 @@ Verify the nroff of man pages -%SRCDIR/nroff-scan.pl %SRCDIR/../docs/ %SRCDIR/../docs/libcurl/*.3 %SRCDIR/../docs/libcurl/opts/*.3 %SRCDIR/../docs/*.1 +%SRCDIR/test1140.pl %SRCDIR/../docs/ %SRCDIR/../docs/libcurl/*.3 %SRCDIR/../docs/libcurl/opts/*.3 %SRCDIR/../docs/*.1 diff --git a/tests/data/test1165 b/tests/data/test1165 index de4283af229..89f02d719c1 100644 --- a/tests/data/test1165 +++ b/tests/data/test1165 @@ -18,7 +18,7 @@ Verify configure.ac and source code CURL_DISABLE_-sync -%SRCDIR/disable-scan.pl %SRCDIR/.. +%SRCDIR/test1165.pl %SRCDIR/.. diff --git a/tests/data/test1167 b/tests/data/test1167 index 3c2fb1a5f14..76777f81b7f 100644 --- a/tests/data/test1167 +++ b/tests/data/test1167 @@ -17,7 +17,7 @@ Verify curl prefix of public symbols in header files -%SRCDIR/badsymbols.pl %SRCDIR/.. +%SRCDIR/test1167.pl %SRCDIR/.. diff --git a/tests/data/test1173 b/tests/data/test1173 index b5dafbb3b84..c1dc5c22a8d 100644 --- a/tests/data/test1173 +++ b/tests/data/test1173 @@ -19,7 +19,7 @@ Man page syntax checks -%SRCDIR/manpage-syntax.pl %SRCDIR/../docs/libcurl/symbols-in-versions %SRCDIR/../docs/*.1 %SRCDIR/../docs/libcurl/*.3 %SRCDIR/../docs/libcurl/opts/*.3 +%SRCDIR/test1173.pl %SRCDIR/../docs/libcurl/symbols-in-versions %SRCDIR/../docs/*.1 %SRCDIR/../docs/libcurl/*.3 %SRCDIR/../docs/libcurl/opts/*.3 diff --git a/tests/data/test1175 b/tests/data/test1175 index 5190dbe2acb..6e99a616eea 100644 --- a/tests/data/test1175 +++ b/tests/data/test1175 @@ -18,7 +18,7 @@ Verify that symbols-in-versions and libcurl-errors.3 are in sync -%SRCDIR/error-codes.pl %SRCDIR +%SRCDIR/test1175.pl %SRCDIR diff --git a/tests/data/test1177 b/tests/data/test1177 index 66fe49767bb..75af5b4c722 100644 --- a/tests/data/test1177 +++ b/tests/data/test1177 @@ -18,7 +18,7 @@ Verify that feature names and CURL_VERSION_* in lib and docs are in sync -%SRCDIR/version-scan.pl %SRCDIR/../docs/libcurl/curl_version_info.3 %SRCDIR/../include/curl/curl.h %SRCDIR/../lib/version.c +%SRCDIR/test1177.pl %SRCDIR/../docs/libcurl/curl_version_info.3 %SRCDIR/../include/curl/curl.h %SRCDIR/../lib/version.c diff --git a/tests/data/test1222 b/tests/data/test1222 index b56cf6879a7..b46fd115635 100644 --- a/tests/data/test1222 +++ b/tests/data/test1222 @@ -17,7 +17,7 @@ Verify deprecation statuses and versions -%SRCDIR/check-deprecated.pl %SRCDIR/.. +%SRCDIR/test1222.pl %SRCDIR/.. diff --git a/tests/data/test1275 b/tests/data/test1275 index d1cb223b8bb..31893f7ba79 100644 --- a/tests/data/test1275 +++ b/tests/data/test1275 @@ -18,7 +18,7 @@ Verify capital letters after period in markdown files -%SRCDIR/markdown-uppercase.pl %SRCDIR/.. +%SRCDIR/test1275.pl %SRCDIR/.. diff --git a/tests/data/test1276 b/tests/data/test1276 index 3961bf4cb10..b365f800af3 100644 --- a/tests/data/test1276 +++ b/tests/data/test1276 @@ -18,7 +18,7 @@ Verify lib/optiontable.pl -%SRCDIR/option-check.pl %SRCDIR/.. +%SRCDIR/test1276.pl %SRCDIR/.. diff --git a/tests/data/test1279 b/tests/data/test1279 index fd3b34bd309..041f5449b4a 100644 --- a/tests/data/test1279 +++ b/tests/data/test1279 @@ -19,7 +19,7 @@ Verify libcurl.def against CURL_EXTERN declarations -%SRCDIR/extern-scan.pl --heading=EXPORTS --sort %SRCDIR/.. +%SRCDIR/test1135.pl --heading=EXPORTS --sort %SRCDIR/.. diff --git a/tests/data/test1477 b/tests/data/test1477 index 2771d7f1d32..554ac141f1e 100644 --- a/tests/data/test1477 +++ b/tests/data/test1477 @@ -17,7 +17,7 @@ Verify that error codes in headers and libcurl-errors.3 are in sync -%SRCDIR/errorcodes.pl %SRCDIR/.. +%SRCDIR/test1477.pl %SRCDIR/.. diff --git a/tests/data/test1544 b/tests/data/test1544 index f658f5a7493..037caa0ac61 100644 --- a/tests/data/test1544 +++ b/tests/data/test1544 @@ -17,7 +17,7 @@ Verify all string options are translated by OS/400 wrapper -%SRCDIR/check-translatable-options.pl %SRCDIR/.. +%SRCDIR/test1544.pl %SRCDIR/.. diff --git a/tests/data/test971 b/tests/data/test971 index 19260dfdfe4..6c6b950589a 100644 --- a/tests/data/test971 +++ b/tests/data/test971 @@ -18,7 +18,7 @@ Verify that options-in-versions and docs/cmdline-opts are in sync -%SRCDIR/options-scan.pl %SRCDIR/../docs/options-in-versions %SRCDIR/../docs/cmdline-opts +%SRCDIR/test971.pl %SRCDIR/../docs/options-in-versions %SRCDIR/../docs/cmdline-opts diff --git a/tests/symbol-scan.pl b/tests/test1119.pl similarity index 100% rename from tests/symbol-scan.pl rename to tests/test1119.pl diff --git a/tests/mem-include-scan.pl b/tests/test1132.pl similarity index 100% rename from tests/mem-include-scan.pl rename to tests/test1132.pl diff --git a/tests/extern-scan.pl b/tests/test1135.pl similarity index 100% rename from tests/extern-scan.pl rename to tests/test1135.pl diff --git a/tests/manpage-scan.pl b/tests/test1139.pl similarity index 100% rename from tests/manpage-scan.pl rename to tests/test1139.pl diff --git a/tests/nroff-scan.pl b/tests/test1140.pl similarity index 100% rename from tests/nroff-scan.pl rename to tests/test1140.pl diff --git a/tests/disable-scan.pl b/tests/test1165.pl similarity index 100% rename from tests/disable-scan.pl rename to tests/test1165.pl diff --git a/tests/badsymbols.pl b/tests/test1167.pl similarity index 100% rename from tests/badsymbols.pl rename to tests/test1167.pl diff --git a/tests/manpage-syntax.pl b/tests/test1173.pl similarity index 100% rename from tests/manpage-syntax.pl rename to tests/test1173.pl diff --git a/tests/error-codes.pl b/tests/test1175.pl similarity index 100% rename from tests/error-codes.pl rename to tests/test1175.pl diff --git a/tests/version-scan.pl b/tests/test1177.pl similarity index 100% rename from tests/version-scan.pl rename to tests/test1177.pl diff --git a/tests/check-deprecated.pl b/tests/test1222.pl similarity index 100% rename from tests/check-deprecated.pl rename to tests/test1222.pl diff --git a/tests/markdown-uppercase.pl b/tests/test1275.pl similarity index 100% rename from tests/markdown-uppercase.pl rename to tests/test1275.pl diff --git a/tests/option-check.pl b/tests/test1276.pl similarity index 100% rename from tests/option-check.pl rename to tests/test1276.pl diff --git a/tests/errorcodes.pl b/tests/test1477.pl similarity index 100% rename from tests/errorcodes.pl rename to tests/test1477.pl diff --git a/tests/check-translatable-options.pl b/tests/test1544.pl similarity index 100% rename from tests/check-translatable-options.pl rename to tests/test1544.pl diff --git a/tests/options-scan.pl b/tests/test971.pl similarity index 100% rename from tests/options-scan.pl rename to tests/test971.pl From 6d8dc2f636cd873922f67ea77c1678698e911344 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 8 Dec 2023 10:28:46 +0100 Subject: [PATCH 018/509] convsrctest.pl: removed: not used, not shipped in tarballs --- tests/convsrctest.pl | 263 ------------------------------------------- 1 file changed, 263 deletions(-) delete mode 100755 tests/convsrctest.pl diff --git a/tests/convsrctest.pl b/tests/convsrctest.pl deleted file mode 100755 index cdb252aeb08..00000000000 --- a/tests/convsrctest.pl +++ /dev/null @@ -1,263 +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 -# -#*************************************************************************** - -#======================================================================= -# Read a test definition which exercises curl's --libcurl option. -# Generate either compilable source code for a new test tool, -# or a new test definition which runs the tool and expects the -# same output. -# This should verify that the --libcurl code really does perform -# the same actions as the original curl invocation. -#----------------------------------------------------------------------- -# The output of curl's --libcurl option differs in several ways from -# the code needed to integrate with the test tool environment: -# - #include "test.h" -# - no call of curl_global_init & curl_global_cleanup -# - main() function vs. test() function -# - no checking of curl_easy_setopt calls vs. test_setopt wrapper -# - handling of stdout -# - variable names ret & hnd vs. res & curl -# - URL as literal string vs. passed as argument -#======================================================================= -use strict; -use warnings; - -use getpart qw( - getpart - loadtest - fulltest - ); - -# Boilerplate code for test tool -my $head = -'#include "test.h" -#include "memdebug.h" - -int test(char *URL) -{ - CURLcode res; - CURL *curl; -'; -# Other declarations from --libcurl come here -# e.g. curl_slist -my $init = -' - if (curl_global_init(CURL_GLOBAL_ALL) != CURLE_OK) { - fprintf(stderr, "curl_global_init() failed\n"); - return TEST_ERR_MAJOR_BAD; - } - - if ((curl = curl_easy_init()) == NULL) { - fprintf(stderr, "curl_easy_init() failed\n"); - curl_global_cleanup(); - return TEST_ERR_MAJOR_BAD; - } -'; -# Option setting, perform and cleanup come here -my $exit = -' curl_global_cleanup(); - - return (int)res; -} -'; - -my $myname = leaf($0); -sub usage {die "Usage: $myname -c|-test=num testfile\n";} - -sub main { - @ARGV == 2 - or usage; - my($opt,$testfile) = @ARGV; - - if(loadtest($testfile)) { - die "$myname: $testfile doesn't look like a test case\n"; - } - - my $comment = sprintf("DO NOT EDIT - generated from %s by %s", - leaf($testfile), $myname); - if($opt eq '-c') { - generate_c($comment); - } - elsif(my($num) = $opt =~ /^-test=(\d+)$/) { - generate_test($comment, $num); - } - else { - usage; - } -} - -sub generate_c { - my($comment) = @_; - # Fetch the generated code, which is the output file checked by - # the old test. - my @libcurl = getpart("verify", "file") - or die "$myname: no section found\n"; - - # Mangle the code into a suitable form for a test tool. - # We want to extract the important parts (declarations, - # URL, setopt calls, cleanup code) from the --libcurl - # boilerplate and insert them into a new boilerplate. - my(@decl,@code); - # First URL passed in as argument, others as global - my @urlvars = ('URL', 'libtest_arg2', 'libtest_arg3'); - my($seen_main,$seen_setopt,$seen_return); - foreach (@libcurl) { - # Check state changes first (even though it - # duplicates some matches) so that the other tests - # are in a logical order). - if(/^int main/) { - $seen_main = 1; - } - if($seen_main and /curl_easy_setopt/) { - # Don't match 'curl_easy_setopt' in comment! - $seen_setopt = 1; - } - if(/^\s*return/) { - $seen_return = 1; - } - - # Now filter the code according to purpose - if(! $seen_main) { - next; - } - elsif(! $seen_setopt) { - if(/^\s*(int main|\{|CURLcode |CURL |hnd = curl_easy_init)/) { - # Initialization handled by boilerplate - next; - } - else { - push @decl, $_; - } - } - elsif(! $seen_return) { - if(/CURLOPT_URL/) { - # URL is passed in as argument or by global - my $var = shift @urlvars; - s/\"[^\"]*\"/$var/; - } - s/\bhnd\b/curl/; - # Convert to macro wrapper - s/curl_easy_setopt/test_setopt/; - if(/curl_easy_perform/) { - s/\bret\b/res/; - push @code, $_; - push @code, "test_cleanup:\n"; - } - else { - push @code, $_; - } - } - } - - print("/* $comment */\n", - $head, - @decl, - $init, - @code, - $exit); -} - -# Read the original test data file and transform it -# - add a "DO NOT EDIT comment" -# - replace CURLOPT_URL string with URL variable -# - remove section (was the --libcurl output) -# - insert a section with our new C program name -# - replace section with the URL -sub generate_test { - my($comment,$newnumber) = @_; - my @libcurl = getpart("verify", "file") - or die "$myname: no section found\n"; - # Scan the --libcurl code to find the URL used. - my $url; - foreach (@libcurl) { - if(my($u) = /CURLOPT_URL, \"([^\"]*)\"/) { - $url = $u; - } - } - die "$myname: CURLOPT_URL not found\n" - unless defined $url; - - # Traverse the pseudo-XML transforming as required - my @new; - my(@path,$path,$skip); - foreach (fulltest()) { - if(my($end) = /\s*<(\/?)testcase>/) { - push @new, $_; - push @new, "# $comment\n" - unless $end; - } - elsif(my($tag) = /^\s*<(\w+)/) { - push @path, $tag; - $path = join '/', @path; - if($path eq 'verify/file') { - $skip = 1; - } - push @new, $_ - unless $skip; - if($path eq 'client') { - push @new, ("\n", - "lib$newnumber\n", - "\n"); - } - elsif($path eq 'client/command') { - push @new, sh_quote($url)."\n"; - } - } - elsif(my($etag) = /^\s*<\/(\w+)/) { - my $tag = pop @path; - die "$myname: mismatched \n" - unless $tag eq $etag; - push @new, $_ - unless $skip; - $skip -- - if $path eq 'verify/file'; - $path = join '/', @path; - } - else { - if($path eq 'client/command') { - # Replaced above - } - else { - push @new, $_ - unless $skip; - } - } - } - print @new; -} - -sub leaf { - # Works for POSIX filenames - (my $path = shift) =~ s!.*/!!; - return $path; -} - -sub sh_quote { - my $word = shift; - $word =~ s/[\$\"\'\\]/\\$&/g; - return '"' . $word . '"'; -} - -main; From 7c992dd9f89ee219e7f3395211b8f7bdfebc35c3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 8 Dec 2023 14:27:29 +0100 Subject: [PATCH 019/509] lib: rename Curl_strndup to Curl_memdup0 to avoid misunderstanding Since the copy does not stop at a null byte, let's not call it anything that makes you think it works like the common strndup() function. Based on feedback from Jay Satiro, Stefan Eissing and Patrick Monnerat Closes #12490 --- lib/altsvc.c | 4 ++-- lib/bufref.c | 2 +- lib/cookie.c | 4 ++-- lib/formdata.c | 4 ++-- lib/ftp.c | 4 ++-- lib/hsts.c | 2 +- lib/http.c | 8 ++++---- lib/rtsp.c | 2 +- lib/strdup.c | 4 ++-- lib/strdup.h | 2 +- lib/urlapi.c | 8 ++++---- lib/vauth/ntlm_sspi.c | 2 +- lib/vssh/wolfssh.c | 2 +- lib/vtls/mbedtls.c | 4 ++-- lib/vtls/sectransp.c | 2 +- 15 files changed, 27 insertions(+), 27 deletions(-) diff --git a/lib/altsvc.c b/lib/altsvc.c index 35450d6b1c7..2d46b95c90b 100644 --- a/lib/altsvc.c +++ b/lib/altsvc.c @@ -123,11 +123,11 @@ static struct altsvc *altsvc_createid(const char *srchost, dlen -= 2; } - as->src.host = Curl_strndup(srchost, hlen); + as->src.host = Curl_memdup0(srchost, hlen); if(!as->src.host) goto error; - as->dst.host = Curl_strndup(dsthost, dlen); + as->dst.host = Curl_memdup0(dsthost, dlen); if(!as->dst.host) goto error; diff --git a/lib/bufref.c b/lib/bufref.c index 013eba10b2e..f0a0e2a7dea 100644 --- a/lib/bufref.c +++ b/lib/bufref.c @@ -117,7 +117,7 @@ CURLcode Curl_bufref_memdup(struct bufref *br, const void *ptr, size_t len) DEBUGASSERT(len <= CURL_MAX_INPUT_LENGTH); if(ptr) { - cpy = Curl_strndup(ptr, len); + cpy = Curl_memdup0(ptr, len); if(!cpy) return CURLE_OUT_OF_MEMORY; } diff --git a/lib/cookie.c b/lib/cookie.c index 156322a9046..1bd80ff5b3e 100644 --- a/lib/cookie.c +++ b/lib/cookie.c @@ -365,7 +365,7 @@ static void strstore(char **str, const char *newstr, size_t len) DEBUGASSERT(newstr); DEBUGASSERT(str); free(*str); - *str = Curl_strndup(newstr, len); + *str = Curl_memdup0(newstr, len); } /* @@ -821,7 +821,7 @@ Curl_cookie_add(struct Curl_easy *data, endslash = memrchr(path, '/', (queryp - path)); if(endslash) { size_t pathlen = (endslash-path + 1); /* include end slash */ - co->path = Curl_strndup(path, pathlen); + co->path = Curl_memdup0(path, pathlen); if(co->path) { co->spath = sanitize_cookie_path(co->path); if(!co->spath) diff --git a/lib/formdata.c b/lib/formdata.c index 81ed5fe61d0..8896b75e20d 100644 --- a/lib/formdata.c +++ b/lib/formdata.c @@ -603,7 +603,7 @@ CURLFORMcode FormAdd(struct curl_httppost **httppost, app passed in a bad combo, so we better check for that first. */ if(form->name) { /* copy name (without strdup; possibly not null-terminated) */ - form->name = Curl_strndup(form->name, form->namelength? + form->name = Curl_memdup0(form->name, form->namelength? form->namelength: strlen(form->name)); } @@ -779,7 +779,7 @@ static CURLcode setname(curl_mimepart *part, const char *name, size_t len) if(!name || !len) return curl_mime_name(part, name); - zname = Curl_strndup(name, len); + zname = Curl_memdup0(name, len); if(!zname) return CURLE_OUT_OF_MEMORY; res = curl_mime_name(part, zname); diff --git a/lib/ftp.c b/lib/ftp.c index ae98530e922..87666dbcb23 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -4170,7 +4170,7 @@ CURLcode ftp_parse_url_path(struct Curl_easy *data) return CURLE_OUT_OF_MEMORY; } - ftpc->dirs[0] = Curl_strndup(rawPath, dirlen); + ftpc->dirs[0] = Curl_memdup0(rawPath, dirlen); if(!ftpc->dirs[0]) { free(rawPath); return CURLE_OUT_OF_MEMORY; @@ -4214,7 +4214,7 @@ CURLcode ftp_parse_url_path(struct Curl_easy *data) CWD requires a parameter and a non-existent parameter a) doesn't work on many servers and b) has no effect on the others. */ if(compLen > 0) { - char *comp = Curl_strndup(curPos, compLen); + char *comp = Curl_memdup0(curPos, compLen); if(!comp) { free(rawPath); return CURLE_OUT_OF_MEMORY; diff --git a/lib/hsts.c b/lib/hsts.c index 9314be294be..99f5bd458fe 100644 --- a/lib/hsts.c +++ b/lib/hsts.c @@ -135,7 +135,7 @@ static CURLcode hsts_create(struct hsts *h, if(!sts) return CURLE_OUT_OF_MEMORY; - duphost = Curl_strndup(hostname, hlen); + duphost = Curl_memdup0(hostname, hlen); if(!duphost) { free(sts); return CURLE_OUT_OF_MEMORY; diff --git a/lib/http.c b/lib/http.c index 2597937623e..209780ed0a2 100644 --- a/lib/http.c +++ b/lib/http.c @@ -329,7 +329,7 @@ char *Curl_copy_header_value(const char *header) /* get length of the type */ len = end - start + 1; - return Curl_strndup(start, len); + return Curl_memdup0(start, len); } #ifndef CURL_DISABLE_HTTP_AUTH @@ -4617,17 +4617,17 @@ CURLcode Curl_http_req_make(struct httpreq **preq, goto out; memcpy(req->method, method, m_len); if(scheme) { - req->scheme = Curl_strndup(scheme, s_len); + req->scheme = Curl_memdup0(scheme, s_len); if(!req->scheme) goto out; } if(authority) { - req->authority = Curl_strndup(authority, a_len); + req->authority = Curl_memdup0(authority, a_len); if(!req->authority) goto out; } if(path) { - req->path = Curl_strndup(path, p_len); + req->path = Curl_memdup0(path, p_len); if(!req->path) goto out; } diff --git a/lib/rtsp.c b/lib/rtsp.c index f05ee727ebf..f83c0b5886a 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -934,7 +934,7 @@ CURLcode Curl_rtsp_parseheader(struct Curl_easy *data, char *header) */ /* Copy the id substring into a new buffer */ - data->set.str[STRING_RTSP_SESSION_ID] = Curl_strndup(start, idlen); + data->set.str[STRING_RTSP_SESSION_ID] = Curl_memdup0(start, idlen); if(!data->set.str[STRING_RTSP_SESSION_ID]) return CURLE_OUT_OF_MEMORY; } diff --git a/lib/strdup.c b/lib/strdup.c index 50f0656b91b..299c9cc36b7 100644 --- a/lib/strdup.c +++ b/lib/strdup.c @@ -101,7 +101,7 @@ void *Curl_memdup(const void *src, size_t length) /*************************************************************************** * - * Curl_strndup(source, length) + * Curl_memdup0(source, length) * * Copies the 'source' string to a newly allocated buffer (that is returned). * Copies 'length' bytes then adds a null terminator. @@ -109,7 +109,7 @@ void *Curl_memdup(const void *src, size_t length) * Returns the new pointer or NULL on failure. * ***************************************************************************/ -void *Curl_strndup(const char *src, size_t length) +void *Curl_memdup0(const char *src, size_t length) { char *buf = malloc(length + 1); if(!buf) diff --git a/lib/strdup.h b/lib/strdup.h index 9f12b25482a..238a2611f64 100644 --- a/lib/strdup.h +++ b/lib/strdup.h @@ -33,6 +33,6 @@ wchar_t* Curl_wcsdup(const wchar_t* src); #endif void *Curl_memdup(const void *src, size_t buffer_length); void *Curl_saferealloc(void *ptr, size_t size); -void *Curl_strndup(const char *src, size_t length); +void *Curl_memdup0(const char *src, size_t length); #endif /* HEADER_CURL_STRDUP_H */ diff --git a/lib/urlapi.c b/lib/urlapi.c index 0d11e48c92a..d8a6dab1abe 100644 --- a/lib/urlapi.c +++ b/lib/urlapi.c @@ -1231,7 +1231,7 @@ static CURLUcode parseurl(const char *url, CURLU *u, unsigned int flags) u->fragment = Curl_dyn_ptr(&enc); } else { - u->fragment = Curl_strndup(fragment + 1, fraglen - 1); + u->fragment = Curl_memdup0(fragment + 1, fraglen - 1); if(!u->fragment) { result = CURLUE_OUT_OF_MEMORY; goto fail; @@ -1260,7 +1260,7 @@ static CURLUcode parseurl(const char *url, CURLU *u, unsigned int flags) u->query = Curl_dyn_ptr(&enc); } else { - u->query = Curl_strndup(query + 1, qlen - 1); + u->query = Curl_memdup0(query + 1, qlen - 1); if(!u->query) { result = CURLUE_OUT_OF_MEMORY; goto fail; @@ -1294,7 +1294,7 @@ static CURLUcode parseurl(const char *url, CURLU *u, unsigned int flags) } else { if(!u->path) { - u->path = Curl_strndup(path, pathlen); + u->path = Curl_memdup0(path, pathlen); if(!u->path) { result = CURLUE_OUT_OF_MEMORY; goto fail; @@ -1592,7 +1592,7 @@ CURLUcode curl_url_get(const CURLU *u, CURLUPart what, if(ptr) { size_t partlen = strlen(ptr); size_t i = 0; - *part = Curl_strndup(ptr, partlen); + *part = Curl_memdup0(ptr, partlen); if(!*part) return CURLUE_OUT_OF_MEMORY; if(plusdecode) { diff --git a/lib/vauth/ntlm_sspi.c b/lib/vauth/ntlm_sspi.c index 06079a6ffc6..3d102eb4a4f 100644 --- a/lib/vauth/ntlm_sspi.c +++ b/lib/vauth/ntlm_sspi.c @@ -214,7 +214,7 @@ CURLcode Curl_auth_decode_ntlm_type2_message(struct Curl_easy *data, } /* Store the challenge for later use */ - ntlm->input_token = Curl_strndup((const char *)Curl_bufref_ptr(type2), + ntlm->input_token = Curl_memdup0((const char *)Curl_bufref_ptr(type2), Curl_bufref_len(type2)); if(!ntlm->input_token) return CURLE_OUT_OF_MEMORY; diff --git a/lib/vssh/wolfssh.c b/lib/vssh/wolfssh.c index 8d152d43c73..2fca3270777 100644 --- a/lib/vssh/wolfssh.c +++ b/lib/vssh/wolfssh.c @@ -513,7 +513,7 @@ static CURLcode wssh_statemach_act(struct Curl_easy *data, bool *block) return CURLE_OK; } else if(name && (rc == WS_SUCCESS)) { - sshc->homedir = Curl_strndup(name->fName, name->fSz); + sshc->homedir = Curl_memdup0(name->fName, name->fSz); if(!sshc->homedir) sshc->actualcode = CURLE_OUT_OF_MEMORY; wolfSSH_SFTPNAME_list_free(name); diff --git a/lib/vtls/mbedtls.c b/lib/vtls/mbedtls.c index f0fb7f3e421..4734ce026a2 100644 --- a/lib/vtls/mbedtls.c +++ b/lib/vtls/mbedtls.c @@ -368,7 +368,7 @@ mbed_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) /* Unfortunately, mbedtls_x509_crt_parse() requires the data to be null terminated even when provided the exact length, forcing us to waste extra memory here. */ - unsigned char *newblob = Curl_strndup(ca_info_blob->data, + unsigned char *newblob = Curl_memdup0(ca_info_blob->data, ca_info_blob->len); if(!newblob) return CURLE_OUT_OF_MEMORY; @@ -441,7 +441,7 @@ mbed_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) /* Unfortunately, mbedtls_x509_crt_parse() requires the data to be null terminated even when provided the exact length, forcing us to waste extra memory here. */ - unsigned char *newblob = Curl_strndup(ssl_cert_blob->data, + unsigned char *newblob = Curl_memdup0(ssl_cert_blob->data, ssl_cert_blob->len); if(!newblob) return CURLE_OUT_OF_MEMORY; diff --git a/lib/vtls/sectransp.c b/lib/vtls/sectransp.c index 19c00e0350d..075de0c88b8 100644 --- a/lib/vtls/sectransp.c +++ b/lib/vtls/sectransp.c @@ -2373,7 +2373,7 @@ static CURLcode verify_cert(struct Curl_cfilter *cf, if(ca_info_blob) { CURL_TRC_CF(data, cf, "verify_peer, CA from config blob"); - certbuf = (unsigned char *)Curl_strndup(ca_info_blob->data, + certbuf = (unsigned char *)Curl_memdup0(ca_info_blob->data, buflen = ca_info_blob->len); if(!certbuf) return CURLE_OUT_OF_MEMORY; From 0f3f3843436c3c924e1ea2fe949c9ec51c3a6d2f Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Fri, 1 Dec 2023 18:06:12 -0500 Subject: [PATCH 020/509] build: fix Windows ADDRESS_FAMILY detection - Include winsock2.h for Windows ADDRESS_FAMILY detection. Prior to this change cmake detection didn't work because it included ws2def.h by itself, which is missing needed types from winsock2.h. Prior to this change autotools detection didn't work because it did not include any Windows header. In both cases libcurl would fall back on unsigned short as the address family type, which is the same as ADDRESS_FAMILY. Co-authored-by: Viktor Szakats Closes https://github.com/curl/curl/pull/12441 --- CMakeLists.txt | 2 +- configure.ac | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 4042f001baa..c0abc284db2 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1266,7 +1266,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 "") diff --git a/configure.ac b/configure.ac index d9b396376d2..d26a183f569 100644 --- a/configure.ac +++ b/configure.ac @@ -3473,6 +3473,14 @@ 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 HAVE_WINDOWS_H +#ifndef WIN32_LEAN_AND_MEAN +#define WIN32_LEAN_AND_MEAN +#endif +#ifdef HAVE_WINSOCK2_H +#include +#endif +#endif #ifdef HAVE_SYS_SOCKET_H #include #endif From d65b8868c6d04d2d7fdedbc42bce3cf0fe60887a Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Fri, 8 Dec 2023 21:12:06 +0100 Subject: [PATCH 021/509] doh: remove unused local variable The nurl variable is no longer used during probing following a refactoring, so remove. Closes #12491 --- lib/doh.c | 3 --- 1 file changed, 3 deletions(-) diff --git a/lib/doh.c b/lib/doh.c index 1d928e92c73..fd89596284f 100644 --- a/lib/doh.c +++ b/lib/doh.c @@ -218,7 +218,6 @@ static CURLcode dohprobe(struct Curl_easy *data, struct curl_slist *headers) { struct Curl_easy *doh = NULL; - char *nurl = NULL; CURLcode result = CURLE_OK; timediff_t timeout_ms; DOHcode d = doh_encode(host, dnstype, p->dohbuffer, sizeof(p->dohbuffer), @@ -351,11 +350,9 @@ static CURLcode dohprobe(struct Curl_easy *data, } else goto error; - free(nurl); return CURLE_OK; error: - free(nurl); Curl_close(&doh); return result; } From 9fa8652fd573c3a1fa4b3c3df34d742952e3d3dc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 10 Dec 2023 00:05:04 +0100 Subject: [PATCH 022/509] cmdline/gen: fix the sorting of the man page options They were previously sorted based on the file names, which use a .d extension, making "data" get placed after "data-binary" etc. Making the sort ignore the extention fixes the ordering. Reported-by: Boris Verkhovskiy Bug: https://curl.se/mail/archive-2023-12/0014.html Closes #12494 --- docs/cmdline-opts/gen.pl | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index edf90622b2e..16324550888 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -675,6 +675,16 @@ sub listglobals { } } +sub noext { + my $in = $_[0]; + $in =~ s/\.d//; + return $in; +} + +sub sortnames { + return noext($a) cmp noext($b); +} + sub mainpage { my (@files) = @_; my $ret; @@ -682,7 +692,7 @@ sub mainpage { header("page-header"); # output docs for all options - foreach my $f (sort @files) { + foreach my $f (sort sortnames @files) { $ret += single($f, 0); } From e38a8e0cd0cdab91967ec5c0cb90803097ac0618 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Dec 2023 08:52:19 +0100 Subject: [PATCH 023/509] docs: clean up Protocols: for cmdline options ... and some other minor polish. Closes #12496 --- docs/cmdline-opts/aws-sigv4.d | 1 + docs/cmdline-opts/disallow-username-in-url.d | 3 +-- docs/cmdline-opts/dns-servers.d | 1 + docs/cmdline-opts/get.d | 1 + docs/cmdline-opts/http3-only.d | 1 - docs/cmdline-opts/http3.d | 1 - docs/cmdline-opts/include.d | 7 ++++--- docs/cmdline-opts/ipfs-gateway.d | 1 + docs/cmdline-opts/ssl-allow-beast.d | 1 + docs/cmdline-opts/ssl-auto-client-cert.d | 1 + docs/cmdline-opts/ssl-no-revoke.d | 1 + docs/cmdline-opts/ssl-revoke-best-effort.d | 1 + docs/cmdline-opts/tlsauthtype.d | 1 + docs/cmdline-opts/tlspassword.d | 1 + docs/cmdline-opts/tlsuser.d | 1 + 15 files changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/cmdline-opts/aws-sigv4.d b/docs/cmdline-opts/aws-sigv4.d index b771eee6a94..4b480f50cab 100644 --- a/docs/cmdline-opts/aws-sigv4.d +++ b/docs/cmdline-opts/aws-sigv4.d @@ -1,6 +1,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: aws-sigv4 +Protocols: HTTP Arg: Help: Use AWS V4 signature authentication Category: auth http diff --git a/docs/cmdline-opts/disallow-username-in-url.d b/docs/cmdline-opts/disallow-username-in-url.d index d0537db97ac..0e70ba91f64 100644 --- a/docs/cmdline-opts/disallow-username-in-url.d +++ b/docs/cmdline-opts/disallow-username-in-url.d @@ -2,10 +2,9 @@ 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 +Category: curl Example: --disallow-username-in-url $URL Multi: boolean --- diff --git a/docs/cmdline-opts/dns-servers.d b/docs/cmdline-opts/dns-servers.d index bec23a3c352..96be0814143 100644 --- a/docs/cmdline-opts/dns-servers.d +++ b/docs/cmdline-opts/dns-servers.d @@ -3,6 +3,7 @@ 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 diff --git a/docs/cmdline-opts/get.d b/docs/cmdline-opts/get.d index 2e03a255bc8..513ea00438d 100644 --- a/docs/cmdline-opts/get.d +++ b/docs/cmdline-opts/get.d @@ -3,6 +3,7 @@ SPDX-License-Identifier: curl Long: get Short: G Help: Put the post data in the URL and use GET +Protocols: HTTP Category: http upload Example: --get $URL Example: --get -d "tool=curl" -d "age=old" $URL diff --git a/docs/cmdline-opts/http3-only.d b/docs/cmdline-opts/http3-only.d index c3f0f31aa1b..384519b83c5 100644 --- a/docs/cmdline-opts/http3-only.d +++ b/docs/cmdline-opts/http3-only.d @@ -11,7 +11,6 @@ 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 diff --git a/docs/cmdline-opts/http3.d b/docs/cmdline-opts/http3.d index a8258c4d313..3b05d4a1dcb 100644 --- a/docs/cmdline-opts/http3.d +++ b/docs/cmdline-opts/http3.d @@ -11,7 +11,6 @@ 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 diff --git a/docs/cmdline-opts/include.d b/docs/cmdline-opts/include.d index ce7b9d87b47..85df6a55a0d 100644 --- a/docs/cmdline-opts/include.d +++ b/docs/cmdline-opts/include.d @@ -4,14 +4,15 @@ Long: include Short: i Help: Include protocol response headers in the output See-also: verbose +Protocols: HTTP FTP 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... +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. diff --git a/docs/cmdline-opts/ipfs-gateway.d b/docs/cmdline-opts/ipfs-gateway.d index e6845b327a6..2fd106e0170 100644 --- a/docs/cmdline-opts/ipfs-gateway.d +++ b/docs/cmdline-opts/ipfs-gateway.d @@ -3,6 +3,7 @@ SPDX-License-Identifier: curl Long: ipfs-gateway Arg: Help: Gateway for IPFS +Protocols: IPFS Added: 8.4.0 See-also: help manual Category: ipfs diff --git a/docs/cmdline-opts/ssl-allow-beast.d b/docs/cmdline-opts/ssl-allow-beast.d index 2547675d640..b2c5d9399c8 100644 --- a/docs/cmdline-opts/ssl-allow-beast.d +++ b/docs/cmdline-opts/ssl-allow-beast.d @@ -2,6 +2,7 @@ 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 Example: --ssl-allow-beast $URL diff --git a/docs/cmdline-opts/ssl-auto-client-cert.d b/docs/cmdline-opts/ssl-auto-client-cert.d index 5328adea710..549f0afd8b3 100644 --- a/docs/cmdline-opts/ssl-auto-client-cert.d +++ b/docs/cmdline-opts/ssl-auto-client-cert.d @@ -5,6 +5,7 @@ Help: Use auto client certificate (Schannel) Added: 7.77.0 See-also: proxy-ssl-auto-client-cert Category: tls +Protocols: TLS Example: --ssl-auto-client-cert $URL Multi: boolean --- diff --git a/docs/cmdline-opts/ssl-no-revoke.d b/docs/cmdline-opts/ssl-no-revoke.d index 37e91d9c204..3983938e6ef 100644 --- a/docs/cmdline-opts/ssl-no-revoke.d +++ b/docs/cmdline-opts/ssl-no-revoke.d @@ -3,6 +3,7 @@ SPDX-License-Identifier: curl Long: ssl-no-revoke Help: Disable cert revocation checks (Schannel) Added: 7.44.0 +Protocols: TLS Category: tls Example: --ssl-no-revoke $URL See-also: crlfile diff --git a/docs/cmdline-opts/ssl-revoke-best-effort.d b/docs/cmdline-opts/ssl-revoke-best-effort.d index cb26d0b9a09..33899848dce 100644 --- a/docs/cmdline-opts/ssl-revoke-best-effort.d +++ b/docs/cmdline-opts/ssl-revoke-best-effort.d @@ -3,6 +3,7 @@ SPDX-License-Identifier: curl Long: ssl-revoke-best-effort Help: Ignore missing/offline cert CRL dist points (Schannel) Added: 7.70.0 +Protocols: TLS Category: tls Example: --ssl-revoke-best-effort $URL See-also: crlfile insecure diff --git a/docs/cmdline-opts/tlsauthtype.d b/docs/cmdline-opts/tlsauthtype.d index 7d3f7e5aac4..e74385b8920 100644 --- a/docs/cmdline-opts/tlsauthtype.d +++ b/docs/cmdline-opts/tlsauthtype.d @@ -3,6 +3,7 @@ SPDX-License-Identifier: curl Long: tlsauthtype Arg: Help: TLS authentication type +Protocols: TLS Added: 7.21.4 Category: tls auth Example: --tlsauthtype SRP $URL diff --git a/docs/cmdline-opts/tlspassword.d b/docs/cmdline-opts/tlspassword.d index 0513191ae93..9335a07bbc3 100644 --- a/docs/cmdline-opts/tlspassword.d +++ b/docs/cmdline-opts/tlspassword.d @@ -4,6 +4,7 @@ Long: tlspassword Arg: Help: TLS password Added: 7.21.4 +Protocols: TLS Category: tls auth Example: --tlspassword pwd --tlsuser user $URL See-also: tlsuser diff --git a/docs/cmdline-opts/tlsuser.d b/docs/cmdline-opts/tlsuser.d index f87532a7c03..b884698b452 100644 --- a/docs/cmdline-opts/tlsuser.d +++ b/docs/cmdline-opts/tlsuser.d @@ -4,6 +4,7 @@ Long: tlsuser Arg: Help: TLS user name Added: 7.21.4 +Protocols: TLS Category: tls auth Example: --tlspassword pwd --tlsuser user $URL See-also: tlspassword From 9efdefe6b12a53789f2f8c4112dca94586b1387f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Dec 2023 18:57:48 +0100 Subject: [PATCH 024/509] CI/distcheck: run full tests To be able to detect missing files better, this now runs the full CI test suite. If done before, it would have detected #12462 before release. Closes #12503 --- .github/workflows/distcheck.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/distcheck.yml b/.github/workflows/distcheck.yml index 8b908e0a5bc..6c050f51740 100644 --- a/.github/workflows/distcheck.yml +++ b/.github/workflows/distcheck.yml @@ -50,7 +50,7 @@ jobs: pushd curl-99.98.97 ./configure --prefix=$HOME/temp --without-ssl make - make TFLAGS=1 test + make test-ci make install popd # basic check of the installed files @@ -75,7 +75,7 @@ jobs: pushd build ../curl-99.98.97/configure --without-ssl make - make TFLAGS='-p 1 1139' test + make test-ci popd rm -rf build rm -rf curl-99.98.97 @@ -98,7 +98,7 @@ jobs: pushd build ../configure --without-ssl --enable-debug "--prefix=${PWD}/pkg" make -j3 - make -j3 TFLAGS=1279 test + make -j3 test-ci make -j3 install name: 'verify out-of-tree autotools debug build' From ff74cef5d4a0cf60106517a1c7384ebec039e0a2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Dec 2023 16:15:57 +0100 Subject: [PATCH 025/509] lib: reduce use of strncpy - bearssl: select cipher without buffer copies - http_aws_sigv4: avoid strncpy, require exact timestamp length - http_aws_sigv4: use memcpy isntead of strncpy - openssl: avoid strncpy calls - schannel: check for 1.3 algos without buffer copies - strerror: avoid strncpy calls - telnet: avoid strncpy, return error on too long inputs - vtls: avoid strncpy in multissl_version() Closes #12499 --- lib/http_aws_sigv4.c | 19 ++++++++++++---- lib/strerror.c | 54 +++++++++++++++++++------------------------- lib/telnet.c | 24 ++++++++++++-------- lib/vtls/bearssl.c | 32 +++++++++++++++----------- lib/vtls/openssl.c | 20 ++++++++-------- lib/vtls/schannel.c | 34 +++++++++++++--------------- lib/vtls/vtls.c | 16 ++++--------- 7 files changed, 101 insertions(+), 98 deletions(-) diff --git a/lib/http_aws_sigv4.c b/lib/http_aws_sigv4.c index b673055f309..c9382918ed6 100644 --- a/lib/http_aws_sigv4.c +++ b/lib/http_aws_sigv4.c @@ -247,7 +247,7 @@ static CURLcode make_headers(struct Curl_easy *data, } else { char *value; - + char *endp; value = strchr(*date_header, ':'); if(!value) { *date_header = NULL; @@ -256,8 +256,17 @@ static CURLcode make_headers(struct Curl_easy *data, ++value; while(ISBLANK(*value)) ++value; - strncpy(timestamp, value, TIMESTAMP_SIZE - 1); - timestamp[TIMESTAMP_SIZE - 1] = 0; + endp = value; + while(*endp && ISALNUM(*endp)) + ++endp; + /* 16 bytes => "19700101T000000Z" */ + if((endp - value) == TIMESTAMP_SIZE - 1) { + memcpy(timestamp, value, TIMESTAMP_SIZE - 1); + timestamp[TIMESTAMP_SIZE - 1] = 0; + } + else + /* bad timestamp length */ + timestamp[0] = 0; *date_header = NULL; } @@ -605,7 +614,7 @@ CURLcode Curl_output_aws_sigv4(struct Curl_easy *data, bool proxy) result = CURLE_URL_MALFORMAT; goto fail; } - strncpy(service, hostname, len); + memcpy(service, hostname, len); service[len] = '\0'; infof(data, "aws_sigv4: picked service %s from host", service); @@ -624,7 +633,7 @@ CURLcode Curl_output_aws_sigv4(struct Curl_easy *data, bool proxy) result = CURLE_URL_MALFORMAT; goto fail; } - strncpy(region, reg, len); + memcpy(region, reg, len); region[len] = '\0'; infof(data, "aws_sigv4: picked region %s from host", region); } diff --git a/lib/strerror.c b/lib/strerror.c index 0d5f9276f03..51e1485408e 100644 --- a/lib/strerror.c +++ b/lib/strerror.c @@ -572,13 +572,15 @@ curl_url_strerror(CURLUcode error) * Returns NULL if no error message was found for error code. */ static const char * -get_winsock_error (int err, char *buf, size_t len) +get_winsock_error(int err, char *buf, size_t len) { #ifndef CURL_DISABLE_VERBOSE_STRINGS const char *p; #endif - if(!len) + /* 41 bytes is the longest error string */ + DEBUGASSERT(len > 41); + if(!len || len < 41) return NULL; *buf = '\0'; @@ -755,8 +757,8 @@ get_winsock_error (int err, char *buf, size_t len) default: return NULL; } - strncpy(buf, p, len); - buf [len-1] = '\0'; + memcpy(buf, p, len - 1); + buf[len - 1] = '\0'; return buf; #endif } @@ -832,7 +834,6 @@ const char *Curl_strerror(int err, char *buf, size_t buflen) #endif int old_errno = errno; char *p; - size_t max; if(!buflen) return NULL; @@ -841,23 +842,22 @@ const char *Curl_strerror(int err, char *buf, size_t buflen) DEBUGASSERT(err >= 0); #endif - max = buflen - 1; *buf = '\0'; #if defined(_WIN32) || defined(_WIN32_WCE) #if defined(_WIN32) /* 'sys_nerr' is the maximum errno number, it is not widely portable */ if(err >= 0 && err < sys_nerr) - strncpy(buf, sys_errlist[err], max); + msnprintf(buf, buflen, "%s", sys_errlist[err]); else #endif { if( #ifdef USE_WINSOCK - !get_winsock_error(err, buf, max) && + !get_winsock_error(err, buf, buflen) && #endif - !get_winapi_error((DWORD)err, buf, max)) - msnprintf(buf, max, "Unknown error %d (%#x)", err, err); + !get_winapi_error((DWORD)err, buf, buflen)) + msnprintf(buf, buflen, "Unknown error %d (%#x)", err, err); } #else /* not Windows coming up */ @@ -867,9 +867,9 @@ const char *Curl_strerror(int err, char *buf, size_t buflen) * storage is supplied via 'strerrbuf' and 'buflen' to hold the generated * message string, or EINVAL if 'errnum' is not a valid error number. */ - if(0 != strerror_r(err, buf, max)) { + if(0 != strerror_r(err, buf, buflen)) { if('\0' == buf[0]) - msnprintf(buf, max, "Unknown error %d", err); + msnprintf(buf, buflen, "Unknown error %d", err); } #elif defined(HAVE_STRERROR_R) && defined(HAVE_GLIBC_STRERROR_R) /* @@ -881,25 +881,23 @@ const char *Curl_strerror(int err, char *buf, size_t buflen) char buffer[256]; char *msg = strerror_r(err, buffer, sizeof(buffer)); if(msg) - strncpy(buf, msg, max); + msnprintf(buf, buflen, "%s", msg); else - msnprintf(buf, max, "Unknown error %d", err); + msnprintf(buf, buflen, "Unknown error %d", err); } #else { /* !checksrc! disable STRERROR 1 */ const char *msg = strerror(err); if(msg) - strncpy(buf, msg, max); + msnprintf(buf, buflen, "%s", msg); else - msnprintf(buf, max, "Unknown error %d", err); + msnprintf(buf, buflen, "Unknown error %d", err); } #endif #endif /* end of not Windows */ - buf[max] = '\0'; /* make sure the string is null-terminated */ - /* strip trailing '\r\n' or '\n'. */ p = strrchr(buf, '\n'); if(p && (p - buf) >= 2) @@ -943,8 +941,8 @@ const char *Curl_winapi_strerror(DWORD err, char *buf, size_t buflen) #else { const char *txt = (err == ERROR_SUCCESS) ? "No error" : "Error"; - strncpy(buf, txt, buflen); - buf[buflen - 1] = '\0'; + if(strlen(txt) < buflen) + strcpy(buf, txt); } #endif @@ -1081,17 +1079,11 @@ const char *Curl_sspi_strerror(int err, char *buf, size_t buflen) err); } else { - char txtbuf[80]; char msgbuf[256]; - - msnprintf(txtbuf, sizeof(txtbuf), "%s (0x%08X)", txt, err); - if(get_winapi_error(err, msgbuf, sizeof(msgbuf))) - msnprintf(buf, buflen, "%s - %s", txtbuf, msgbuf); - else { - strncpy(buf, txtbuf, buflen); - buf[buflen - 1] = '\0'; - } + msnprintf(buf, buflen, "%s (0x%08X) - %s", txt, err, msgbuf); + else + msnprintf(buf, buflen, "%s (0x%08X)", txt, err); } #else @@ -1099,8 +1091,8 @@ const char *Curl_sspi_strerror(int err, char *buf, size_t buflen) txt = "No error"; else txt = "Error"; - strncpy(buf, txt, buflen); - buf[buflen - 1] = '\0'; + if(buflen > strlen(txt)) + strcpy(buf, txt); #endif if(errno != old_errno) diff --git a/lib/telnet.c b/lib/telnet.c index 836e255c9d6..6c689c81662 100644 --- a/lib/telnet.c +++ b/lib/telnet.c @@ -826,23 +826,27 @@ static CURLcode check_telnet_options(struct Curl_easy *data) case 5: /* Terminal type */ if(strncasecompare(option, "TTYPE", 5)) { - strncpy(tn->subopt_ttype, arg, 31); - tn->subopt_ttype[31] = 0; /* String termination */ - tn->us_preferred[CURL_TELOPT_TTYPE] = CURL_YES; + size_t l = strlen(arg); + if(l < sizeof(tn->subopt_ttype)) { + strcpy(tn->subopt_ttype, arg); + tn->us_preferred[CURL_TELOPT_TTYPE] = CURL_YES; + break; + } } - else - result = CURLE_UNKNOWN_OPTION; + result = CURLE_UNKNOWN_OPTION; break; case 8: /* Display variable */ if(strncasecompare(option, "XDISPLOC", 8)) { - strncpy(tn->subopt_xdisploc, arg, 127); - tn->subopt_xdisploc[127] = 0; /* String termination */ - tn->us_preferred[CURL_TELOPT_XDISPLOC] = CURL_YES; + size_t l = strlen(arg); + if(l < sizeof(tn->subopt_xdisploc)) { + strcpy(tn->subopt_xdisploc, arg); + tn->us_preferred[CURL_TELOPT_XDISPLOC] = CURL_YES; + break; + } } - else - result = CURLE_UNKNOWN_OPTION; + result = CURLE_UNKNOWN_OPTION; break; case 7: diff --git a/lib/vtls/bearssl.c b/lib/vtls/bearssl.c index a6566f4d90c..58394bab9a6 100644 --- a/lib/vtls/bearssl.c +++ b/lib/vtls/bearssl.c @@ -509,7 +509,6 @@ static CURLcode bearssl_set_selected_ciphers(struct Curl_easy *data, { uint16_t selected_ciphers[NUM_OF_CIPHERS]; size_t selected_count = 0; - char cipher_name[CIPHER_NAME_BUF_LEN]; const char *cipher_start = ciphers; const char *cipher_end; size_t i, j; @@ -518,41 +517,48 @@ static CURLcode bearssl_set_selected_ciphers(struct Curl_easy *data, return CURLE_SSL_CIPHER; while(true) { + const char *cipher; + size_t clen; + /* Extract the next cipher name from the ciphers string */ while(is_separator(*cipher_start)) ++cipher_start; - if(*cipher_start == '\0') + if(!*cipher_start) break; cipher_end = cipher_start; - while(*cipher_end != '\0' && !is_separator(*cipher_end)) + while(*cipher_end && !is_separator(*cipher_end)) ++cipher_end; - j = cipher_end - cipher_start < CIPHER_NAME_BUF_LEN - 1 ? - cipher_end - cipher_start : CIPHER_NAME_BUF_LEN - 1; - strncpy(cipher_name, cipher_start, j); - cipher_name[j] = '\0'; + + clen = cipher_end - cipher_start; + cipher = cipher_start; + cipher_start = cipher_end; /* Lookup the cipher name in the table of available ciphers. If the cipher name starts with "TLS_" we do the lookup by IANA name. Otherwise, we try to match cipher name by an (OpenSSL) alias. */ - if(strncasecompare(cipher_name, "TLS_", 4)) { + if(strncasecompare(cipher, "TLS_", 4)) { for(i = 0; i < NUM_OF_CIPHERS && - !strcasecompare(cipher_name, ciphertable[i].name); ++i); + (strlen(ciphertable[i].name) == clen) && + !strncasecompare(cipher, ciphertable[i].name, clen); ++i); } else { for(i = 0; i < NUM_OF_CIPHERS && - !strcasecompare(cipher_name, ciphertable[i].alias_name); ++i); + (strlen(ciphertable[i].alias_name) == clen) && + !strncasecompare(cipher, ciphertable[i].alias_name, clen); ++i); } if(i == NUM_OF_CIPHERS) { - infof(data, "BearSSL: unknown cipher in list: %s", cipher_name); + infof(data, "BearSSL: unknown cipher in list: %.*s", + (int)clen, cipher); continue; } /* No duplicates allowed */ for(j = 0; j < selected_count && - selected_ciphers[j] != ciphertable[i].num; j++); + selected_ciphers[j] != ciphertable[i].num; j++); if(j < selected_count) { - infof(data, "BearSSL: duplicate cipher in list: %s", cipher_name); + infof(data, "BearSSL: duplicate cipher in list: %.*s", + (int)clen, cipher); continue; } diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c index 8c8f43e8360..1f735e00144 100644 --- a/lib/vtls/openssl.c +++ b/lib/vtls/openssl.c @@ -954,8 +954,9 @@ static char *ossl_strerror(unsigned long error, char *buf, size_t size) #endif if(!*buf) { - strncpy(buf, (error ? "Unknown error" : "No error"), size); - buf[size - 1] = '\0'; + const char *msg = error ? "Unknown error" : "No error"; + if(strlen(msg) < size) + strcpy(buf, msg); } return buf; @@ -4592,10 +4593,10 @@ static ssize_t ossl_send(struct Curl_cfilter *cf, ossl_strerror(sslerror, error_buffer, sizeof(error_buffer)); else if(sockerr) Curl_strerror(sockerr, error_buffer, sizeof(error_buffer)); - else { - strncpy(error_buffer, SSL_ERROR_to_str(err), sizeof(error_buffer)); - error_buffer[sizeof(error_buffer) - 1] = '\0'; - } + else + msnprintf(error_buffer, sizeof(error_buffer), "%s", + SSL_ERROR_to_str(err)); + failf(data, OSSL_PACKAGE " SSL_write: %s, errno %d", error_buffer, sockerr); *curlcode = CURLE_SEND_ERROR; @@ -4688,10 +4689,9 @@ static ssize_t ossl_recv(struct Curl_cfilter *cf, ossl_strerror(sslerror, error_buffer, sizeof(error_buffer)); else if(sockerr && err == SSL_ERROR_SYSCALL) Curl_strerror(sockerr, error_buffer, sizeof(error_buffer)); - else { - strncpy(error_buffer, SSL_ERROR_to_str(err), sizeof(error_buffer)); - error_buffer[sizeof(error_buffer) - 1] = '\0'; - } + else + msnprintf(error_buffer, sizeof(error_buffer), "%s", + SSL_ERROR_to_str(err)); failf(data, OSSL_PACKAGE " SSL_read: %s, errno %d", error_buffer, sockerr); *curlcode = CURLE_RECV_ERROR; diff --git a/lib/vtls/schannel.c b/lib/vtls/schannel.c index 8e1d5be8d80..b2a707950d5 100644 --- a/lib/vtls/schannel.c +++ b/lib/vtls/schannel.c @@ -439,6 +439,12 @@ get_cert_location(TCHAR *path, DWORD *store_name, TCHAR **store_path, return CURLE_OK; } #endif + +static bool algo(const char *check, char *namep, size_t nlen) +{ + return (strlen(check) == nlen) && !strncmp(check, namep, nlen); +} + static CURLcode schannel_acquire_credential_handle(struct Curl_cfilter *cf, struct Curl_easy *data) @@ -790,9 +796,7 @@ schannel_acquire_credential_handle(struct Curl_cfilter *cf, char *startCur = ciphers13; int algCount = 0; - char tmp[LONGEST_ALG_ID] = { 0 }; char *nameEnd; - size_t n; disable_aes_gcm_sha384 = TRUE; disable_aes_gcm_sha256 = TRUE; @@ -801,40 +805,34 @@ schannel_acquire_credential_handle(struct Curl_cfilter *cf, disable_aes_ccm_sha256 = TRUE; while(startCur && (0 != *startCur) && (algCount < remaining_ciphers)) { + size_t n; + char *namep; nameEnd = strchr(startCur, ':'); n = nameEnd ? (size_t)(nameEnd - startCur) : strlen(startCur); + namep = startCur; - /* reject too-long cipher names */ - if(n > (LONGEST_ALG_ID - 1)) { - failf(data, "schannel: Cipher name too long, not checked"); - return CURLE_SSL_CIPHER; - } - - strncpy(tmp, startCur, n); - tmp[n] = 0; - - if(disable_aes_gcm_sha384 - && !strcmp("TLS_AES_256_GCM_SHA384", tmp)) { + if(disable_aes_gcm_sha384 && + algo("TLS_AES_256_GCM_SHA384", namep, n)) { disable_aes_gcm_sha384 = FALSE; } else if(disable_aes_gcm_sha256 - && !strcmp("TLS_AES_128_GCM_SHA256", tmp)) { + && algo("TLS_AES_128_GCM_SHA256", namep, n)) { disable_aes_gcm_sha256 = FALSE; } else if(disable_chacha_poly - && !strcmp("TLS_CHACHA20_POLY1305_SHA256", tmp)) { + && algo("TLS_CHACHA20_POLY1305_SHA256", namep, n)) { disable_chacha_poly = FALSE; } else if(disable_aes_ccm_8_sha256 - && !strcmp("TLS_AES_128_CCM_8_SHA256", tmp)) { + && algo("TLS_AES_128_CCM_8_SHA256", namep, n)) { disable_aes_ccm_8_sha256 = FALSE; } else if(disable_aes_ccm_sha256 - && !strcmp("TLS_AES_128_CCM_SHA256", tmp)) { + && algo("TLS_AES_128_CCM_SHA256", namep, n)) { disable_aes_ccm_sha256 = FALSE; } else { - failf(data, "schannel: Unknown TLS 1.3 cipher: %s", tmp); + failf(data, "schannel: Unknown TLS 1.3 cipher: %.*s", (int)n, namep); return CURLE_SSL_CIPHER; } diff --git a/lib/vtls/vtls.c b/lib/vtls/vtls.c index dd68a066367..256b8faa804 100644 --- a/lib/vtls/vtls.c +++ b/lib/vtls/vtls.c @@ -1413,17 +1413,11 @@ static size_t multissl_version(char *buffer, size_t size) backends_len = p - backends; } - if(!size) - return 0; - - if(size <= backends_len) { - strncpy(buffer, backends, size - 1); - buffer[size - 1] = '\0'; - return size - 1; - } - - strcpy(buffer, backends); - return backends_len; + if(size && (size < backends_len)) + strcpy(buffer, backends); + else + *buffer = 0; /* did not fit */ + return 0; } static int multissl_setup(const struct Curl_ssl *backend) From 02d81c5a6808e189cd20418274abccbd9bb1385d Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 11 Dec 2023 11:52:26 +0100 Subject: [PATCH 026/509] CONNECTION-FILTERS: update documentation Closes #12497 --- docs/CONNECTION-FILTERS.md | 117 +++++++++++++++++++++++++++++++++---- 1 file changed, 106 insertions(+), 11 deletions(-) diff --git a/docs/CONNECTION-FILTERS.md b/docs/CONNECTION-FILTERS.md index c4b11dbb01d..d973bc79b15 100644 --- a/docs/CONNECTION-FILTERS.md +++ b/docs/CONNECTION-FILTERS.md @@ -1,7 +1,7 @@ # 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. +in curl v7.87.0. This document describes the concepts, its high level implementation and the motivations. ## Filters @@ -110,18 +110,113 @@ 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: -* **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. +* `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 a 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 a HTTP/2 connection +* `HTTP/3`: filter for handling multiplexed transfers over a 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. -As you see, filters are a good way to add functionality to curl's internal handling of transfers without impact on other code. +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. -## Easy Filters? +## Filter Flags -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. +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 a 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 a HTTP/2 request, invoke curl with: + +``` +> curl -v --trace-config ids,time,http/2 https://curl.se +``` +Which will give 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". + +The `HAPPY-EYEBALLS` filter is involved in the connect phase. It's 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. + +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 will look 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 +``` + +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. + +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 and have happy eyeballing for QUIC: + +``` +* 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 +``` + +And 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 +``` -So we might add "easy filters" one day. Who knows? From 5d5dfdbd1a6c40bd75e982b66f49e1fa3a7eeae7 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sun, 10 Dec 2023 03:33:17 +0000 Subject: [PATCH 027/509] cmake: delete obsolete TODO items [ci skip] There is always room for improvement, but CMake is up to par now with autotools, so there is no longer a good reason to keep around these inline TODO items. Answering one of questions: Q: "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." A: CMake offers the `CMAKE_BUILD_TYPE` variable to control debug info and optimization level. E.g.: - `Release` = `-O3` + no debug info - `MinSizeRel` = `-Os` + no debug info - `Debug` = `-O0` + debug info https://stackoverflow.com/questions/48754619/what-are-cmake-build-type-debug-release-relwithdebinfo-and-minsizerel/59314670#59314670 https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#default-and-custom-configurations For picky warnings we have the `PICKY_COMPILER` options, enabled by default. Closes #12500 --- CMakeLists.txt | 9 --------- 1 file changed, 9 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index c0abc284db2..bc53dbb2cd1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -26,19 +26,10 @@ # 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 From 3be759610f1e51e2daca68d49c4e93a1e34e3463 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 12 Dec 2023 12:36:07 +0100 Subject: [PATCH 028/509] CLIENT-WRITERS: design and use documentation Closes #12507 --- docs/CLIENT-WRITERS.md | 101 +++++++++++++++++++++++++++++++++++++++++ docs/Makefile.am | 1 + 2 files changed, 102 insertions(+) create mode 100644 docs/CLIENT-WRITERS.md diff --git a/docs/CLIENT-WRITERS.md b/docs/CLIENT-WRITERS.md new file mode 100644 index 00000000000..5f226487820 --- /dev/null +++ b/docs/CLIENT-WRITERS.md @@ -0,0 +1,101 @@ +# 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, 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. And 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, there then will be a `Content-Encoding` header listing the encoding applied. If supported by `libcurl` it will then decompress the content before writing it out to the client. How does it do that? + +The HTTP protocol will add client writers in phase `CURL_CW_CONTENT_DECODE` on seeing such a header. For each encoding listed, it will add 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. So 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/Makefile.am b/docs/Makefile.am index 9190b441136..e53cf305af2 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -55,6 +55,7 @@ EXTRA_DIST = \ CODE_OF_CONDUCT.md \ CODE_REVIEW.md \ CODE_STYLE.md \ + CLIENT-WRITERS.md \ CONNECTION-FILTERS.md \ CONTRIBUTE.md \ CURL-DISABLE.md \ From 043523a89be13a4d2d5c9228f4ecd52cd58ef10b Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 12 Dec 2023 16:37:28 +0000 Subject: [PATCH 029/509] cmake: delete obsolete TODOs more [ci skip] - manual completed: 898b012a9bf388590c4be7f526815b5ab74feca1 #1288 - soname completed: 5de6848f104d7cb0017080e31216265ac19d0dde #10023 - bunch of others that are completed - `NTLM_WB_ENABLED` is implemented in a basic form, and now also scheduled for removal, so a TODO at this point isn't useful. And this 'to-check' item: Q: "The cmake build selected to run gcc with -fPIC on my box while the plain configure script did not." A: With CMake, since 2ebc74c36a19a1700af394c16855ce144d9878e3 #11546 and fc9bfb14520712672b4784e8b48256fb29204011 #11627, we explicitly enable PIC for libcurl shared lib. Or when building libcurl for shared and static lib in a single pass. We do this by default for Windows or when enabled by the user via `SHARE_LIB_OBJECT`. Otherwise we don't touch this setting. Meaning the default set by CMake (if any) or the toolchain is used. On Debian Bookworm, this means that PIC is disabled for static libs by default. Some platforms (like macOS), has PIC enabled by default. autotools supports the double-pass mode only, and in that case CMake seems to match PIC behaviour now (as tested on Linux with gcc.) Follow-up to 5d5dfdbd1a6c40bd75e982b66f49e1fa3a7eeae7 #12500 Reviewed-by: Jay Satiro Closes #12509 --- CMakeLists.txt | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index bc53dbb2cd1..1ec8b5519ab 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -21,16 +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 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. - # 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 @@ -1524,7 +1516,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) @@ -1542,26 +1533,20 @@ 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("MultiSSL" CURL_WITH_MULTI_SSL) From 246e0d805ac11aa2a2e14aee485e5deb58653b8b Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 12 Dec 2023 20:38:08 +0000 Subject: [PATCH 030/509] tests/server: delete workaround for old-mingw mingw-w64 1.0 comes with w32api v3.12, thus doesn't need this. Follow-up to 38029101e2d78ba125732b3bab6ec267b80a0e72 #11625 Reviewed-by: Jay Satiro Closes #12510 --- tests/server/util.c | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/tests/server/util.c b/tests/server/util.c index 5cfdab269f7..34bca8659d4 100644 --- a/tests/server/util.c +++ b/tests/server/util.c @@ -39,9 +39,6 @@ #elif defined(HAVE_SYS_POLL_H) #include #endif -#ifdef __MINGW32__ -#include -#endif #define ENABLE_CURLX_PRINTF /* make the curlx header define all printf() functions to use the curlx_* @@ -58,15 +55,6 @@ #define EINVAL 22 /* errno.h value */ #endif -/* MinGW with w32api version < 3.6 declared in6addr_any as extern, - but lacked the definition */ -#if defined(ENABLE_IPV6) && defined(__MINGW32__) -#if (__W32API_MAJOR_VERSION < 3) || \ - ((__W32API_MAJOR_VERSION == 3) && (__W32API_MINOR_VERSION < 6)) -const struct in6_addr in6addr_any = {{ IN6ADDR_ANY_INIT }}; -#endif /* w32api < 3.6 */ -#endif /* ENABLE_IPV6 && __MINGW32__ */ - static struct timeval tvnow(void); /* This function returns a pointer to STATIC memory. It converts the given From 1e4cd519355b63b26a0a9ee1f125153bfcc4995e Mon Sep 17 00:00:00 2001 From: Dmitry Karpov Date: Wed, 13 Dec 2023 14:32:53 -0800 Subject: [PATCH 031/509] cookie: avoid fopen with empty file name Closes #12514 --- lib/cookie.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/cookie.c b/lib/cookie.c index 1bd80ff5b3e..5f158395b6f 100644 --- a/lib/cookie.c +++ b/lib/cookie.c @@ -1227,7 +1227,7 @@ struct CookieInfo *Curl_cookie_init(struct Curl_easy *data, if(data) { FILE *fp = NULL; - if(file) { + if(file && *file) { if(!strcmp(file, "-")) fp = stdin; else { From 0f052808b3a054bbbcdf31d16ad168e6fdd1252e Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 14 Dec 2023 12:59:19 +0100 Subject: [PATCH 032/509] connect: refactor `Curl_timeleft()` - less local vars, "better" readability - added documentation Closes #12518 --- lib/connect.c | 66 +++++++++++++++++++-------------------------------- 1 file changed, 25 insertions(+), 41 deletions(-) diff --git a/lib/connect.c b/lib/connect.c index ec5ab71d496..54cd27cbd86 100644 --- a/lib/connect.c +++ b/lib/connect.c @@ -93,25 +93,17 @@ * transfer/connection. If the value is 0, there's no timeout (ie there's * infinite time left). If the value is negative, the timeout time has already * elapsed. - * - * If 'nowp' is non-NULL, it points to the current time. - * 'duringconnect' is FALSE if not during a connect, as then of course the - * connect timeout is not taken into account! - * + * @param data the transfer to check on + * @param nowp timestamp to use for calculdation, NULL to use Curl_now() + * @param duringconnect TRUE iff connect timeout is also taken into account. * @unittest: 1303 */ - -#define TIMEOUT_CONNECT 1 -#define TIMEOUT_MAXTIME 2 - timediff_t Curl_timeleft(struct Curl_easy *data, struct curltime *nowp, bool duringconnect) { - unsigned int timeout_set = 0; - timediff_t connect_timeout_ms = 0; - timediff_t maxtime_timeout_ms = 0; - timediff_t timeout_ms = 0; + timediff_t timeleft_ms = 0; + timediff_t ctimeleft_ms = 0; struct curltime now; /* The duration of a connect and the total transfer are calculated from two @@ -119,43 +111,35 @@ timediff_t Curl_timeleft(struct Curl_easy *data, before the connect timeout expires and we must acknowledge whichever timeout that is reached first. The total timeout is set per entire operation, while the connect timeout is set per connect. */ - - if(data->set.timeout > 0) { - timeout_set = TIMEOUT_MAXTIME; - maxtime_timeout_ms = data->set.timeout; - } - if(duringconnect) { - timeout_set |= TIMEOUT_CONNECT; - connect_timeout_ms = (data->set.connecttimeout > 0) ? - data->set.connecttimeout : DEFAULT_CONNECT_TIMEOUT; - } - if(!timeout_set) - /* no timeout */ - return 0; + if(data->set.timeout <= 0 && !duringconnect) + return 0; /* no timeout in place or checked, return "no limit" */ if(!nowp) { now = Curl_now(); nowp = &now; } - if(timeout_set & TIMEOUT_MAXTIME) { - maxtime_timeout_ms -= Curl_timediff(*nowp, data->progress.t_startop); - timeout_ms = maxtime_timeout_ms; + if(data->set.timeout > 0) { + timeleft_ms = data->set.timeout - + Curl_timediff(*nowp, data->progress.t_startop); + if(!timeleft_ms) + timeleft_ms = -1; /* 0 is "no limit", fake 1 ms expiry */ + if(!duringconnect) + return timeleft_ms; /* no connect check, this is it */ } - if(timeout_set & TIMEOUT_CONNECT) { - connect_timeout_ms -= Curl_timediff(*nowp, data->progress.t_startsingle); - - if(!(timeout_set & TIMEOUT_MAXTIME) || - (connect_timeout_ms < maxtime_timeout_ms)) - timeout_ms = connect_timeout_ms; + if(duringconnect) { + timediff_t ctimeout_ms = (data->set.connecttimeout > 0) ? + data->set.connecttimeout : DEFAULT_CONNECT_TIMEOUT; + ctimeleft_ms = ctimeout_ms - + Curl_timediff(*nowp, data->progress.t_startsingle); + if(!ctimeleft_ms) + ctimeleft_ms = -1; /* 0 is "no limit", fake 1 ms expiry */ + if(!timeleft_ms) + return ctimeleft_ms; /* no general timeout, this is it */ } - - if(!timeout_ms) - /* avoid returning 0 as that means no timeout! */ - return -1; - - return timeout_ms; + /* return minimal time left or max amount already expired */ + return (ctimeleft_ms < timeleft_ms)? ctimeleft_ms : timeleft_ms; } /* Copies connection info into the transfer handle to make it available when From 8706b680108919d9cdca1acd3a17fff6a57e245c Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 13 Dec 2023 11:25:20 +0100 Subject: [PATCH 033/509] lib: eliminate `conn->cselect_bits` - use `data->state.dselect_bits` everywhere instead - remove `bool *comeback` parameter as non-zero `data->state.dselect_bits` will indicate that IO is incomplete. Closes #12512 --- lib/cf-h2-proxy.c | 6 +++--- lib/easy.c | 2 +- lib/http2.c | 6 +++--- lib/imap.c | 2 +- lib/multi.c | 7 +++---- lib/transfer.c | 34 +++++++++------------------------- lib/transfer.h | 3 +-- lib/urldata.h | 3 +-- lib/vquic/curl_msh3.c | 8 ++++---- lib/vquic/curl_ngtcp2.c | 4 ++-- lib/vquic/curl_quiche.c | 4 ++-- lib/vssh/libssh.c | 8 ++++---- lib/vssh/libssh2.c | 8 ++++---- lib/vssh/wolfssh.c | 4 ++-- 14 files changed, 40 insertions(+), 59 deletions(-) diff --git a/lib/cf-h2-proxy.c b/lib/cf-h2-proxy.c index 147acdc86f4..78902386ecd 100644 --- a/lib/cf-h2-proxy.c +++ b/lib/cf-h2-proxy.c @@ -221,10 +221,10 @@ static void drain_tunnel(struct Curl_cfilter *cf, bits = CURL_CSELECT_IN; if(!tunnel->closed && !tunnel->reset && tunnel->upload_blocked_len) bits |= CURL_CSELECT_OUT; - if(data->state.dselect_bits != bits) { - CURL_TRC_CF(data, cf, "[%d] DRAIN dselect_bits=%x", + if(data->state.select_bits != bits) { + CURL_TRC_CF(data, cf, "[%d] DRAIN select_bits=%x", tunnel->stream_id, bits); - data->state.dselect_bits = bits; + data->state.select_bits = bits; Curl_expire(data, 0, EXPIRE_RUN_NOW); } } diff --git a/lib/easy.c b/lib/easy.c index 322d1a41b8a..dae2afebf6d 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -1111,7 +1111,7 @@ CURLcode curl_easy_pause(struct Curl_easy *data, int action) if(!data->state.tempcount) /* if not pausing again, force a recv/send check of this connection as the data might've been read off the socket already */ - data->conn->cselect_bits = CURL_CSELECT_IN | CURL_CSELECT_OUT; + data->state.select_bits = CURL_CSELECT_IN | CURL_CSELECT_OUT; if(data->multi) { if(Curl_update_timer(data->multi)) return CURLE_ABORTED_BY_CALLBACK; diff --git a/lib/http2.c b/lib/http2.c index 973848484a4..59903cfa72d 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -219,10 +219,10 @@ static void drain_stream(struct Curl_cfilter *cf, if(!stream->send_closed && (stream->upload_left || stream->upload_blocked_len)) bits |= CURL_CSELECT_OUT; - if(data->state.dselect_bits != bits) { - CURL_TRC_CF(data, cf, "[%d] DRAIN dselect_bits=%x", + if(data->state.select_bits != bits) { + CURL_TRC_CF(data, cf, "[%d] DRAIN select_bits=%x", stream->id, bits); - data->state.dselect_bits = bits; + data->state.select_bits = bits; Curl_expire(data, 0, EXPIRE_RUN_NOW); } } diff --git a/lib/imap.c b/lib/imap.c index 47cff4897c7..1be89eccbd1 100644 --- a/lib/imap.c +++ b/lib/imap.c @@ -1220,7 +1220,7 @@ static CURLcode imap_state_fetch_resp(struct Curl_easy *data, data->req.maxdownload = size; /* force a recv/send check of this connection, as the data might've been read off the socket already */ - data->conn->cselect_bits = CURL_CSELECT_IN; + data->state.select_bits = CURL_CSELECT_IN; Curl_setup_transfer(data, FIRSTSOCKET, size, FALSE, -1); } } diff --git a/lib/multi.c b/lib/multi.c index 5456113be7a..53dee05e00a 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -2371,7 +2371,6 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, { char *newurl = NULL; bool retry = FALSE; - bool comeback = FALSE; DEBUGASSERT(data->state.buffer); /* check if over send speed */ send_timeout_ms = 0; @@ -2402,7 +2401,7 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, } /* read/write data if it is ready to do so */ - result = Curl_readwrite(data->conn, data, &done, &comeback); + result = Curl_readwrite(data->conn, data, &done); if(done || (result == CURLE_RECV_ERROR)) { /* If CURLE_RECV_ERROR happens early enough, we assume it was a race @@ -2512,7 +2511,7 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, } } } - else if(comeback) { + else if(data->state.select_bits) { /* This avoids CURLM_CALL_MULTI_PERFORM so that a very fast transfer won't get stuck on this transfer at the expense of other concurrent transfers */ @@ -3164,7 +3163,7 @@ static CURLMcode multi_socket(struct Curl_multi *multi, if(data->conn && !(data->conn->handler->flags & PROTOPT_DIRLOCK)) /* set socket event bitmask if they're not locked */ - data->conn->cselect_bits = (unsigned char)ev_bitmask; + data->state.select_bits = (unsigned char)ev_bitmask; Curl_expire(data, 0, EXPIRE_RUN_NOW); } diff --git a/lib/transfer.c b/lib/transfer.c index 96f1fde7559..d92b7edd41d 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -417,15 +417,11 @@ bool Curl_meets_timecondition(struct Curl_easy *data, time_t timeofdoc) * Go ahead and do a read if we have a readable socket or if * the stream was rewound (in which case we have data in a * buffer) - * - * return '*comeback' TRUE if we didn't properly drain the socket so this - * function should get called again without select() or similar in between! */ static CURLcode readwrite_data(struct Curl_easy *data, struct connectdata *conn, struct SingleRequest *k, - int *didwhat, bool *done, - bool *comeback) + int *didwhat, bool *done) { CURLcode result = CURLE_OK; char *buf; @@ -438,7 +434,6 @@ static CURLcode readwrite_data(struct Curl_easy *data, DEBUGASSERT(data->state.buffer); *done = FALSE; - *comeback = FALSE; /* This is where we loop until we have read everything there is to read or we get a CURLE_AGAIN */ @@ -722,8 +717,7 @@ static CURLcode readwrite_data(struct Curl_easy *data, if(maxloops <= 0 || max_recv <= 0) { /* we mark it as read-again-please */ - data->state.dselect_bits = CURL_CSELECT_IN; - *comeback = TRUE; + data->state.select_bits = CURL_CSELECT_IN; } if(((k->keepon & (KEEP_RECV|KEEP_SEND)) == KEEP_SEND) && @@ -1032,14 +1026,10 @@ static int select_bits_paused(struct Curl_easy *data, int select_bits) /* * Curl_readwrite() is the low-level function to be called when data is to * be read and written to/from the connection. - * - * return '*comeback' TRUE if we didn't properly drain the socket so this - * function should get called again without select() or similar in between! */ CURLcode Curl_readwrite(struct connectdata *conn, struct Curl_easy *data, - bool *done, - bool *comeback) + bool *done) { struct SingleRequest *k = &data->req; CURLcode result; @@ -1047,22 +1037,16 @@ CURLcode Curl_readwrite(struct connectdata *conn, int didwhat = 0; int select_bits; - if(data->state.dselect_bits) { - if(select_bits_paused(data, data->state.dselect_bits)) { + if(data->state.select_bits) { + if(select_bits_paused(data, data->state.select_bits)) { /* leave the bits unchanged, so they'll tell us what to do when * this transfer gets unpaused. */ - DEBUGF(infof(data, "readwrite, dselect_bits, early return on PAUSED")); + DEBUGF(infof(data, "readwrite, select_bits, early return on PAUSED")); result = CURLE_OK; goto out; } - select_bits = data->state.dselect_bits; - data->state.dselect_bits = 0; - } - else if(conn->cselect_bits) { - /* CAVEAT: adding `select_bits_paused()` check here makes test640 hang - * (among others). Which hints at strange state handling in FTP land... */ - select_bits = conn->cselect_bits; - conn->cselect_bits = 0; + select_bits = data->state.select_bits; + data->state.select_bits = 0; } else { curl_socket_t fd_read; @@ -1100,7 +1084,7 @@ CURLcode Curl_readwrite(struct connectdata *conn, the stream was rewound (in which case we have data in a buffer) */ if((k->keepon & KEEP_RECV) && (select_bits & CURL_CSELECT_IN)) { - result = readwrite_data(data, conn, k, &didwhat, done, comeback); + result = readwrite_data(data, conn, k, &didwhat, done); if(result || *done) goto out; } diff --git a/lib/transfer.h b/lib/transfer.h index 536ac249b7c..f1969a62a9e 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -46,8 +46,7 @@ typedef enum { CURLcode Curl_follow(struct Curl_easy *data, char *newurl, followtype type); CURLcode Curl_readwrite(struct connectdata *conn, - struct Curl_easy *data, bool *done, - bool *comeback); + struct Curl_easy *data, bool *done); int Curl_single_getsock(struct Curl_easy *data, struct connectdata *conn, curl_socket_t *socks); CURLcode Curl_fillreadbuffer(struct Curl_easy *data, size_t bytes, diff --git a/lib/urldata.h b/lib/urldata.h index ff661482eae..14ddee27708 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1103,7 +1103,6 @@ struct connectdata { unsigned short localport; unsigned short secondary_port; /* secondary socket remote port to connect to (ftp) */ - unsigned char cselect_bits; /* bitmask of socket events */ unsigned char alpn; /* APLN TLS negotiated protocol, a CURL_HTTP_VERSION* value */ #ifndef CURL_DISABLE_PROXY @@ -1479,7 +1478,7 @@ struct UrlState { server involved in this request */ unsigned char httpreq; /* Curl_HttpReq; what kind of HTTP request (if any) is this */ - unsigned char dselect_bits; /* != 0 -> bitmask of socket events for this + unsigned char select_bits; /* != 0 -> bitmask of socket events for this transfer overriding anything the socket may report */ #ifdef CURLDEBUG diff --git a/lib/vquic/curl_msh3.c b/lib/vquic/curl_msh3.c index 8ae36724008..7674bc1fcfe 100644 --- a/lib/vquic/curl_msh3.c +++ b/lib/vquic/curl_msh3.c @@ -204,8 +204,8 @@ static void drain_stream_from_other_thread(struct Curl_easy *data, bits = CURL_CSELECT_IN; if(stream && !stream->upload_done) bits |= CURL_CSELECT_OUT; - if(data->state.dselect_bits != bits) { - data->state.dselect_bits = bits; + if(data->state.select_bits != bits) { + data->state.select_bits = bits; /* cannot expire from other thread */ } } @@ -220,8 +220,8 @@ static void drain_stream(struct Curl_cfilter *cf, bits = CURL_CSELECT_IN; if(stream && !stream->upload_done) bits |= CURL_CSELECT_OUT; - if(data->state.dselect_bits != bits) { - data->state.dselect_bits = bits; + if(data->state.select_bits != bits) { + data->state.select_bits = bits; Curl_expire(data, 0, EXPIRE_RUN_NOW); } } diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index f09b10bef7a..0d0f2fab39b 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -292,8 +292,8 @@ static void h3_drain_stream(struct Curl_cfilter *cf, bits = CURL_CSELECT_IN; if(stream && stream->upload_left && !stream->send_closed) bits |= CURL_CSELECT_OUT; - if(data->state.dselect_bits != bits) { - data->state.dselect_bits = bits; + if(data->state.select_bits != bits) { + data->state.select_bits = bits; Curl_expire(data, 0, EXPIRE_RUN_NOW); } } diff --git a/lib/vquic/curl_quiche.c b/lib/vquic/curl_quiche.c index 7123d63ca4a..91395876b46 100644 --- a/lib/vquic/curl_quiche.c +++ b/lib/vquic/curl_quiche.c @@ -337,8 +337,8 @@ static void drain_stream(struct Curl_cfilter *cf, bits = CURL_CSELECT_IN; if(stream && !stream->send_closed && stream->upload_left) bits |= CURL_CSELECT_OUT; - if(data->state.dselect_bits != bits) { - data->state.dselect_bits = bits; + if(data->state.select_bits != bits) { + data->state.select_bits = bits; Curl_expire(data, 0, EXPIRE_RUN_NOW); } } diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index 97143c47764..fdb8d3e12ec 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -1370,7 +1370,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _sending_ function even when the socket turns out readable as the underlying libssh sftp send function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_OUT; + data->state.select_bits = CURL_CSELECT_OUT; /* since we don't really wait for anything at this point, we want the state machine to move on as soon as possible so we set a very short @@ -1740,7 +1740,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _receiving_ function even when the socket turns out writableable as the underlying libssh recv function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_IN; + data->state.select_bits = CURL_CSELECT_IN; if(result) { /* this should never occur; the close state should be entered @@ -1868,7 +1868,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _sending_ function even when the socket turns out readable as the underlying libssh scp send function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_OUT; + data->state.select_bits = CURL_CSELECT_OUT; state(data, SSH_STOP); @@ -1908,7 +1908,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _receiving_ function even when the socket turns out writableable as the underlying libssh recv function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_IN; + data->state.select_bits = CURL_CSELECT_IN; state(data, SSH_STOP); break; diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index 11f5f4fd5d7..2eaddb24408 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -2213,7 +2213,7 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _sending_ function even when the socket turns out readable as the underlying libssh2 sftp send function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_OUT; + data->state.select_bits = CURL_CSELECT_OUT; /* since we don't really wait for anything at this point, we want the state machine to move on as soon as possible so we set a very short @@ -2602,7 +2602,7 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _receiving_ function even when the socket turns out writableable as the underlying libssh2 recv function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_IN; + data->state.select_bits = CURL_CSELECT_IN; if(result) { /* this should never occur; the close state should be entered @@ -2757,7 +2757,7 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _sending_ function even when the socket turns out readable as the underlying libssh2 scp send function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_OUT; + data->state.select_bits = CURL_CSELECT_OUT; state(data, SSH_STOP); } @@ -2819,7 +2819,7 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _receiving_ function even when the socket turns out writableable as the underlying libssh2 recv function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_IN; + data->state.select_bits = CURL_CSELECT_IN; if(result) { state(data, SSH_SCP_CHANNEL_FREE); diff --git a/lib/vssh/wolfssh.c b/lib/vssh/wolfssh.c index 2fca3270777..368f163d1d7 100644 --- a/lib/vssh/wolfssh.c +++ b/lib/vssh/wolfssh.c @@ -694,7 +694,7 @@ static CURLcode wssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _sending_ function even when the socket turns out readable as the underlying libssh2 sftp send function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_OUT; + data->state.select_bits = CURL_CSELECT_OUT; /* since we don't really wait for anything at this point, we want the state machine to move on as soon as possible so we set a very short @@ -790,7 +790,7 @@ static CURLcode wssh_statemach_act(struct Curl_easy *data, bool *block) /* we want to use the _receiving_ function even when the socket turns out writableable as the underlying libssh2 recv function will deal with both accordingly */ - conn->cselect_bits = CURL_CSELECT_IN; + data->state.select_bits = CURL_CSELECT_IN; if(result) { /* this should never occur; the close state should be entered From 1da640abb6886aab822ff0c0da71b1df0ca89d0f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Dec 2023 19:36:27 +0100 Subject: [PATCH 034/509] readwrite_data: loop less This function is made to loop in order to drain incoming data faster. Completely removing the loop has a measerably negative impact on transfer speeds. Downsides with the looping include - it might call the progress callback much more seldom. Especially if the write callback is slow. - rate limiting becomes less exact - a single transfer might "starve out" other parallel transfers - QUIC timers for other connections can't be maintained correctly The long term fix should be to remove the loop and optimize coming back to avoid the transfer speed penalty. This fix lower the max loop count to reduce the starvation problem, and avoids the loop completely for when rate-limiting is in progress. Ref: #12488 Ref: https://curl.se/mail/lib-2023-12/0012.html Closes #12504 --- lib/transfer.c | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/transfer.c b/lib/transfer.c index d92b7edd41d..3afefd4dfc1 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -427,9 +427,8 @@ static CURLcode readwrite_data(struct Curl_easy *data, char *buf; size_t blen; size_t consumed; - int maxloops = 100; - curl_off_t max_recv = data->set.max_recv_speed? - data->set.max_recv_speed : CURL_OFF_T_MAX; + int maxloops = 10; + curl_off_t max_recv = data->set.max_recv_speed ? 0 : CURL_OFF_T_MAX; bool data_eof_handled = FALSE; DEBUGASSERT(data->state.buffer); From de0cd5e8e7c9a0cbf28c4a9dec998ad4b6dfa08c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Dec 2023 23:17:26 +0100 Subject: [PATCH 035/509] test1474: removed The test was already somewhat flaky and disabled on several platforms, and after 1da640abb688 even more unstable. --- tests/data/Makefile.inc | 2 +- tests/data/test1474 | 121 ---------------------------------------- 2 files changed, 1 insertion(+), 122 deletions(-) delete mode 100644 tests/data/test1474 diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index de13c525e8f..6d1a2ad13b6 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -186,7 +186,7 @@ test1439 test1440 test1441 test1442 test1443 test1444 test1445 test1446 \ test1447 test1448 test1449 test1450 test1451 test1452 test1453 test1454 \ test1455 test1456 test1457 test1458 test1459 test1460 test1461 test1462 \ test1463 test1464 test1465 test1466 test1467 test1468 test1469 test1470 \ -test1471 test1472 test1473 test1474 test1475 test1476 test1477 \ +test1471 test1472 test1473 test1475 test1476 test1477 \ \ test1500 test1501 test1502 test1503 test1504 test1505 test1506 test1507 \ test1508 test1509 test1510 test1511 test1512 test1513 test1514 test1515 \ diff --git a/tests/data/test1474 b/tests/data/test1474 deleted file mode 100644 index a87044d1a63..00000000000 --- a/tests/data/test1474 +++ /dev/null @@ -1,121 +0,0 @@ - -# This test is quite timing dependent and tricky to set up. The time line of -# test operations looks like this: -# -# 1. curl sends a PUT request with Expect: 100-continue and waits only 1 msec -# for a 100 response. -# 2. The HTTP server accepts the connection but waits 500 msec before acting -# on the request. -# 3. curl doesn't receive the expected 100 response before its timeout expires, -# so it starts sending the body. It is throttled by a --limit-rate, so it -# sends the first 64 KiB then stops for 1000 msec due to this -# throttling. -# 4. The server sends its 417 response while curl is throttled. -# 5. curl responds to this 417 response by closing the connection (because it -# has a half-completed response outstanding) and starting a new one. This -# new request does not have an Expect: header so it is sent without delay. -# It's still throttled, however, so it takes about 16 seconds to finish -# sending. -# 6. The server receives the response and this time acks it with 200. -# -# Because of the timing sensitivity (scheduling delays of 500 msec can cause -# the test to fail), this test is marked flaky to avoid it being run in the CI -# builds which are often run on overloaded servers. -# Increasing the --limit-rate would decrease the test time, but at the cost of -# becoming even more sensitive to delays (going from 500 msec to 250 msec or -# less of accepted delay before failure). Adding a --speed-time would increase -# the 1 second delay between writes to longer, but it would also increase the -# total time needed by the test, which is already quite high. -# -# The assumption in step 3 is also broken on NetBSD 9.3, OpenBSD 7.3 and -# Solaris 10 as they only usually send about half the requested amount of data -# (see https://curl.se/mail/lib-2023-09/0021.html). - - -HTTP -HTTP PUT -Expect -flaky -timing-dependent - - -# Server-side - -# 417 means the server didn't like the Expect header - -HTTP/1.1 417 BAD swsbounce -Date: Tue, 09 Nov 2010 14:49:00 GMT -Server: test-server/fake -Content-Length: 0 - - - -HTTP/1.1 200 OK -Date: Tue, 09 Nov 2010 14:49:00 GMT -Server: test-server/fake -Content-Length: 10 - -blablabla - - -HTTP/1.1 417 BAD swsbounce -Date: Tue, 09 Nov 2010 14:49:00 GMT -Server: test-server/fake -Content-Length: 0 - -HTTP/1.1 200 OK -Date: Tue, 09 Nov 2010 14:49:00 GMT -Server: test-server/fake -Content-Length: 10 - -blablabla - - -no-expect -delay: 500 -connection-monitor - - - -# Client-side - - -http - - -HTTP PUT with Expect: 100-continue and 417 response during upload - - -http://%HOSTIP:%HTTPPORT/we/want/%TESTNUMBER -T %LOGDIR/test%TESTNUMBER.txt --limit-rate 64K --expect100-timeout 0.001 - - -perl -e "print 'Test does not work on this BSD system' if ( $^O eq 'netbsd' || $^O eq 'openbsd' || ($^O eq 'solaris' && qx/uname -r/ * 100 <= 510));" - -# Must be large enough to trigger curl's automatic 100-continue behaviour - -%repeat[132 x S]%%repeat[16462 x xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx%0a]% - - - -# Verify data after the test has been "shot" - - -PUT /we/want/%TESTNUMBER HTTP/1.1 -Host: %HOSTIP:%HTTPPORT -User-Agent: curl/%VERSION -Accept: */* -Content-Length: 1053701 -Expect: 100-continue - -%repeat[132 x S]%%repeat[1021 x xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx%0a]%%repeat[60 x x]%[DISCONNECT] -PUT /we/want/%TESTNUMBER HTTP/1.1 -Host: %HOSTIP:%HTTPPORT -User-Agent: curl/%VERSION -Accept: */* -Content-Length: 1053701 - -%repeat[132 x S]%%repeat[16462 x xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx%0a]% -[DISCONNECT] - - - From d21bd2190c46ad7fa744cc65b6172fafb13ca0be Mon Sep 17 00:00:00 2001 From: Theo Date: Thu, 14 Dec 2023 13:53:23 +0100 Subject: [PATCH 036/509] libssh: improve the deprecation warning dismissal Previous code was compiler dependant, and dismissed all deprecation warnings indiscriminately. libssh provides a way to disable the deprecation warnings for libssh only, and naturally this is the preferred way. This commit uses that, to prevent the erroneous hiding of potential, unrelated deprecation warnings. Fixes #12519 Closes #12520 --- lib/vssh/libssh.c | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index fdb8d3e12ec..df4e07dfa4e 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -31,6 +31,11 @@ #include +/* in 0.10.0 or later, ignore deprecated warnings */ +#include +#if (LIBSSH_VERSION_MINOR >= 10) || (LIBSSH_VERSION_MAJOR > 0) +#define SSH_SUPPRESS_DEPRECATED +#endif #include #include @@ -89,14 +94,6 @@ #include "curl_memory.h" #include "memdebug.h" -/* in 0.10.0 or later, ignore deprecated warnings */ -#if defined(__GNUC__) && \ - (LIBSSH_VERSION_MINOR >= 10) || \ - (LIBSSH_VERSION_MAJOR > 0) -#pragma GCC diagnostic push -#pragma GCC diagnostic ignored "-Wdeprecated-declarations" -#endif - /* A recent macro provided by libssh. Or make our own. */ #ifndef SSH_STRING_FREE_CHAR #define SSH_STRING_FREE_CHAR(x) \ @@ -2957,10 +2954,4 @@ void Curl_ssh_version(char *buffer, size_t buflen) (void)msnprintf(buffer, buflen, "libssh/%s", ssh_version(0)); } -#if defined(__GNUC__) && \ - (LIBSSH_VERSION_MINOR >= 10) || \ - (LIBSSH_VERSION_MAJOR > 0) -#pragma GCC diagnostic pop -#endif - #endif /* USE_LIBSSH */ From 907dce2dc08ed2fec20b16b0f0ce5028e8042e01 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Dec 2023 16:34:25 +0100 Subject: [PATCH 037/509] hostip: return error immediately when Curl_ip2addr() fails Closes #12522 --- lib/hostip.c | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/lib/hostip.c b/lib/hostip.c index e7c318af77f..bcdc12270a6 100644 --- a/lib/hostip.c +++ b/lib/hostip.c @@ -754,16 +754,22 @@ enum resolve_t Curl_resolv(struct Curl_easy *data, #ifndef USE_RESOLVE_ON_IPS /* First check if this is an IPv4 address string */ - if(Curl_inet_pton(AF_INET, hostname, &in) > 0) + if(Curl_inet_pton(AF_INET, hostname, &in) > 0) { /* This is a dotted IP address 123.123.123.123-style */ addr = Curl_ip2addr(AF_INET, &in, hostname, port); + if(!addr) + return CURLRESOLV_ERROR; + } #ifdef ENABLE_IPV6 - if(!addr) { + else { struct in6_addr in6; /* check if this is an IPv6 address string */ - if(Curl_inet_pton(AF_INET6, hostname, &in6) > 0) + if(Curl_inet_pton(AF_INET6, hostname, &in6) > 0) { /* This is an IPv6 address literal */ addr = Curl_ip2addr(AF_INET6, &in6, hostname, port); + if(!addr) + return CURLRESOLV_ERROR; + } } #endif /* ENABLE_IPV6 */ From 78a1814b331c3535a785aa1c501203ad5a947838 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Dec 2023 23:07:24 +0100 Subject: [PATCH 038/509] libssh: supress warnings without version check Define unconditionally. Follow-up from d21bd2190c46ad7fa Closes #12523 --- lib/vssh/libssh.c | 3 --- 1 file changed, 3 deletions(-) diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index df4e07dfa4e..328aef5a0b0 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -32,10 +32,7 @@ #include /* in 0.10.0 or later, ignore deprecated warnings */ -#include -#if (LIBSSH_VERSION_MINOR >= 10) || (LIBSSH_VERSION_MAJOR > 0) #define SSH_SUPPRESS_DEPRECATED -#endif #include #include From 9f2d2290d13454fbb8ab365f05dbf28aafd101bf Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Fri, 15 Dec 2023 01:50:06 +0000 Subject: [PATCH 039/509] openssl: re-match LibreSSL deinit with init Earlier we switched to use modern initialization with LibreSSL v2.7.0 and up, but did not touch deinitialization [1]. Fix it in this patch. Regression from bec0c5bbf34369920598678161d2df8bea0e243b #11611 [1] https://github.com/curl/curl/pull/11611#issuecomment-1668654014 Reported-by: Mike Hommey Reviewed-by: Daniel Stenberg Fixes #12525 Closes #12526 --- lib/vtls/openssl.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c index 1f735e00144..737c2f7e144 100644 --- a/lib/vtls/openssl.c +++ b/lib/vtls/openssl.c @@ -1753,7 +1753,7 @@ static int ossl_init(void) static void ossl_cleanup(void) { #if (OPENSSL_VERSION_NUMBER >= 0x10100000L) && \ - !defined(LIBRESSL_VERSION_NUMBER) + (!defined(LIBRESSL_VERSION_NUMBER) || LIBRESSL_VERSION_NUMBER >= 0x2070000fL) /* OpenSSL 1.1 deprecates all these cleanup functions and turns them into no-ops in OpenSSL 1.0 compatibility mode */ #else From 907eea08041d7ab3f6441a0202ed4b47ea7fc52f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Dec 2023 23:25:09 +0100 Subject: [PATCH 040/509] Revert "urldata: move async resolver state from easy handle to connectdata" This reverts commit 56a4db2e4e2bcb9a0dcb75b83560a78ef231fcc8 (#12198) We want the c-ares channel to be held in the easy handle, not per connection - for performance. Closes #12524 --- lib/asyn-ares.c | 133 ++++++++++++++++++--------------------------- lib/asyn-thread.c | 40 +++++++------- lib/doh.c | 5 +- lib/easy.c | 30 ++++++++++ lib/hostasyn.c | 11 ++-- lib/hostip.c | 12 ++-- lib/multi.c | 4 +- lib/socks.c | 8 +-- lib/url.c | 42 ++++---------- lib/urldata.h | 6 +- lib/vtls/openssl.c | 2 + 11 files changed, 138 insertions(+), 155 deletions(-) diff --git a/lib/asyn-ares.c b/lib/asyn-ares.c index 437c9337fcd..c3030154b3e 100644 --- a/lib/asyn-ares.c +++ b/lib/asyn-ares.c @@ -228,9 +228,9 @@ static void destroy_async_data(struct Curl_async *async); void Curl_resolver_cancel(struct Curl_easy *data) { DEBUGASSERT(data); - if(data->conn->resolve_async.resolver) - ares_cancel((ares_channel)data->conn->resolve_async.resolver); - destroy_async_data(&data->conn->resolve_async); + if(data->state.async.resolver) + ares_cancel((ares_channel)data->state.async.resolver); + destroy_async_data(&data->state.async); } /* @@ -278,14 +278,14 @@ int Curl_resolver_getsock(struct Curl_easy *data, struct timeval timebuf; struct timeval *timeout; long milli; - int max = ares_getsock((ares_channel)data->conn->resolve_async.resolver, + int max = ares_getsock((ares_channel)data->state.async.resolver, (ares_socket_t *)socks, MAX_SOCKSPEREASYHANDLE); maxtime.tv_sec = CURL_TIMEOUT_RESOLVE; maxtime.tv_usec = 0; - timeout = ares_timeout((ares_channel)data->conn->resolve_async.resolver, - &maxtime, &timebuf); + timeout = ares_timeout((ares_channel)data->state.async.resolver, &maxtime, + &timebuf); milli = (long)curlx_tvtoms(timeout); if(milli == 0) milli += 10; @@ -313,8 +313,8 @@ static int waitperform(struct Curl_easy *data, timediff_t timeout_ms) int i; int num = 0; - bitmask = ares_getsock((ares_channel)data->conn->resolve_async.resolver, - socks, ARES_GETSOCK_MAXNUM); + bitmask = ares_getsock((ares_channel)data->state.async.resolver, socks, + ARES_GETSOCK_MAXNUM); for(i = 0; i < ARES_GETSOCK_MAXNUM; i++) { pfd[i].events = 0; @@ -344,12 +344,12 @@ static int waitperform(struct Curl_easy *data, timediff_t timeout_ms) if(!nfds) /* Call ares_process() unconditionally here, even if we simply timed out above, as otherwise the ares name resolve won't timeout! */ - ares_process_fd((ares_channel)data->conn->resolve_async.resolver, - ARES_SOCKET_BAD, ARES_SOCKET_BAD); + ares_process_fd((ares_channel)data->state.async.resolver, ARES_SOCKET_BAD, + ARES_SOCKET_BAD); else { /* move through the descriptors and ask for processing on them */ for(i = 0; i < num; i++) - ares_process_fd((ares_channel)data->conn->resolve_async.resolver, + ares_process_fd((ares_channel)data->state.async.resolver, (pfd[i].revents & (POLLRDNORM|POLLIN))? pfd[i].fd:ARES_SOCKET_BAD, (pfd[i].revents & (POLLWRNORM|POLLOUT))? @@ -368,7 +368,7 @@ static int waitperform(struct Curl_easy *data, timediff_t timeout_ms) CURLcode Curl_resolver_is_resolved(struct Curl_easy *data, struct Curl_dns_entry **dns) { - struct thread_data *res = data->conn->resolve_async.tdata; + struct thread_data *res = data->state.async.tdata; CURLcode result = CURLE_OK; DEBUGASSERT(dns); @@ -397,7 +397,7 @@ CURLcode Curl_resolver_is_resolved(struct Curl_easy *data, ARES_ECANCELLED synchronously for all pending responses. This will leave us with res->num_pending == 0, which is perfect for the next block. */ - ares_cancel((ares_channel)data->conn->resolve_async.resolver); + ares_cancel((ares_channel)data->state.async.resolver); DEBUGASSERT(res->num_pending == 0); } #endif @@ -408,12 +408,12 @@ CURLcode Curl_resolver_is_resolved(struct Curl_easy *data, them */ res->temp_ai = NULL; - if(!data->conn->resolve_async.dns) + if(!data->state.async.dns) result = Curl_resolver_error(data); else - *dns = data->conn->resolve_async.dns; + *dns = data->state.async.dns; - destroy_async_data(&data->conn->resolve_async); + destroy_async_data(&data->state.async); } return result; @@ -464,8 +464,7 @@ CURLcode Curl_resolver_wait_resolv(struct Curl_easy *data, store.tv_sec = itimeout/1000; store.tv_usec = (itimeout%1000)*1000; - tvp = ares_timeout((ares_channel)data->conn->resolve_async.resolver, - &store, &tv); + tvp = ares_timeout((ares_channel)data->state.async.resolver, &store, &tv); /* use the timeout period ares returned to us above if less than one second is left, otherwise just use 1000ms to make sure the progress @@ -479,7 +478,7 @@ CURLcode Curl_resolver_wait_resolv(struct Curl_easy *data, return CURLE_UNRECOVERABLE_POLL; result = Curl_resolver_is_resolved(data, entry); - if(result || data->conn->resolve_async.done) + if(result || data->state.async.done) break; if(Curl_pgrsUpdate(data)) @@ -500,12 +499,12 @@ CURLcode Curl_resolver_wait_resolv(struct Curl_easy *data, } if(result) /* failure, so we cancel the ares operation */ - ares_cancel((ares_channel)data->conn->resolve_async.resolver); + ares_cancel((ares_channel)data->state.async.resolver); /* Operation complete, if the lookup was successful we now have the entry in the cache. */ if(entry) - *entry = data->conn->resolve_async.dns; + *entry = data->state.async.dns; if(result) /* close the connection, since we can't return failure here without @@ -572,13 +571,12 @@ static void query_completed_cb(void *arg, /* (struct connectdata *) */ be valid so only defer it when we know the 'status' says its fine! */ return; - res = data->conn->resolve_async.tdata; + res = data->state.async.tdata; if(res) { res->num_pending--; if(CURL_ASYNC_SUCCESS == status) { - struct Curl_addrinfo *ai = Curl_he2ai(hostent, - data->conn->resolve_async.port); + struct Curl_addrinfo *ai = Curl_he2ai(hostent, data->state.async.port); if(ai) { compound_results(res, ai); } @@ -729,16 +727,14 @@ static void addrinfo_cb(void *arg, int status, int timeouts, struct ares_addrinfo *result) { struct Curl_easy *data = (struct Curl_easy *)arg; - if(data->conn) { - struct thread_data *res = data->conn->resolve_async.tdata; - (void)timeouts; - if(ARES_SUCCESS == status) { - res->temp_ai = ares2addr(result->nodes); - res->last_status = CURL_ASYNC_SUCCESS; - ares_freeaddrinfo(result); - } - res->num_pending--; + struct thread_data *res = data->state.async.tdata; + (void)timeouts; + if(ARES_SUCCESS == status) { + res->temp_ai = ares2addr(result->nodes); + res->last_status = CURL_ASYNC_SUCCESS; + ares_freeaddrinfo(result); } + res->num_pending--; } #endif @@ -762,12 +758,12 @@ struct Curl_addrinfo *Curl_resolver_getaddrinfo(struct Curl_easy *data, res = calloc(1, sizeof(struct thread_data) + namelen); if(res) { strcpy(res->hostname, hostname); - data->conn->resolve_async.hostname = res->hostname; - data->conn->resolve_async.port = port; - data->conn->resolve_async.done = FALSE; /* not done */ - data->conn->resolve_async.status = 0; /* clear */ - data->conn->resolve_async.dns = NULL; /* clear */ - data->conn->resolve_async.tdata = res; + data->state.async.hostname = res->hostname; + data->state.async.port = port; + data->state.async.done = FALSE; /* not done */ + data->state.async.status = 0; /* clear */ + data->state.async.dns = NULL; /* clear */ + data->state.async.tdata = res; /* initial status - failed */ res->last_status = ARES_ENOTFOUND; @@ -797,8 +793,8 @@ struct Curl_addrinfo *Curl_resolver_getaddrinfo(struct Curl_easy *data, hints.ai_flags = ARES_AI_NUMERICSERV; msnprintf(service, sizeof(service), "%d", port); res->num_pending = 1; - ares_getaddrinfo((ares_channel)data->conn->resolve_async.resolver, - hostname, service, &hints, addrinfo_cb, data); + ares_getaddrinfo((ares_channel)data->state.async.resolver, hostname, + service, &hints, addrinfo_cb, data); } #else @@ -808,10 +804,10 @@ struct Curl_addrinfo *Curl_resolver_getaddrinfo(struct Curl_easy *data, res->num_pending = 2; /* areschannel is already setup in the Curl_open() function */ - ares_gethostbyname((ares_channel)data->conn->resolve_async.resolver, - hostname, PF_INET, query_completed_cb, data); - ares_gethostbyname((ares_channel)data->conn->resolve_async.resolver, - hostname, PF_INET6, query_completed_cb, data); + ares_gethostbyname((ares_channel)data->state.async.resolver, hostname, + PF_INET, query_completed_cb, data); + ares_gethostbyname((ares_channel)data->state.async.resolver, hostname, + PF_INET6, query_completed_cb, data); } else #endif @@ -819,7 +815,7 @@ struct Curl_addrinfo *Curl_resolver_getaddrinfo(struct Curl_easy *data, res->num_pending = 1; /* areschannel is already setup in the Curl_open() function */ - ares_gethostbyname((ares_channel)data->conn->resolve_async.resolver, + ares_gethostbyname((ares_channel)data->state.async.resolver, hostname, PF_INET, query_completed_cb, data); } @@ -833,7 +829,6 @@ CURLcode Curl_set_dns_servers(struct Curl_easy *data, char *servers) { CURLcode result = CURLE_NOT_BUILT_IN; - ares_channel channel, lchannel = NULL; int ares_result; /* If server is NULL or empty, this would purge all DNS servers @@ -846,23 +841,11 @@ CURLcode Curl_set_dns_servers(struct Curl_easy *data, return CURLE_OK; #ifdef HAVE_CARES_SERVERS_CSV - if(data->conn) - channel = data->conn->resolve_async.resolver; - else { - /* we are called by setopt on a data without a connection (yet). In that - * case we set the value on a local instance for checking. - * The configured data options are set when the connection for this - * transfer is created. */ - result = Curl_resolver_init(data, (void **)&lchannel); - if(result) - goto out; - channel = lchannel; - } - #ifdef HAVE_CARES_PORTS_CSV - ares_result = ares_set_servers_ports_csv(channel, servers); + ares_result = ares_set_servers_ports_csv(data->state.async.resolver, + servers); #else - ares_result = ares_set_servers_csv(channel, servers); + ares_result = ares_set_servers_csv(data->state.async.resolver, servers); #endif switch(ares_result) { case ARES_SUCCESS: @@ -878,9 +861,6 @@ CURLcode Curl_set_dns_servers(struct Curl_easy *data, result = CURLE_BAD_FUNCTION_ARGUMENT; break; } -out: - if(lchannel) - Curl_resolver_cleanup(lchannel); #else /* too old c-ares version! */ (void)data; (void)(ares_result); @@ -892,14 +872,11 @@ CURLcode Curl_set_dns_interface(struct Curl_easy *data, const char *interf) { #ifdef HAVE_CARES_LOCAL_DEV - if(data->conn) { - /* not a setopt test run, set the value */ - if(!interf) - interf = ""; + if(!interf) + interf = ""; + + ares_set_local_dev((ares_channel)data->state.async.resolver, interf); - ares_set_local_dev((ares_channel)data->conn->resolve_async.resolver, - interf); - } return CURLE_OK; #else /* c-ares version too old! */ (void)data; @@ -923,11 +900,8 @@ CURLcode Curl_set_dns_local_ip4(struct Curl_easy *data, } } - if(data->conn) { - /* not a setopt test run, set the value */ - ares_set_local_ip4((ares_channel)data->conn->resolve_async.resolver, - ntohl(a4.s_addr)); - } + ares_set_local_ip4((ares_channel)data->state.async.resolver, + ntohl(a4.s_addr)); return CURLE_OK; #else /* c-ares version too old! */ @@ -953,10 +927,7 @@ CURLcode Curl_set_dns_local_ip6(struct Curl_easy *data, } } - if(data->conn) { - /* not a setopt test run, set the value */ - ares_set_local_ip6((ares_channel)data->conn->resolve_async.resolver, a6); - } + ares_set_local_ip6((ares_channel)data->state.async.resolver, a6); return CURLE_OK; #else /* c-ares version too old! */ diff --git a/lib/asyn-thread.c b/lib/asyn-thread.c index 63414b61746..a48f3f4ef0a 100644 --- a/lib/asyn-thread.c +++ b/lib/asyn-thread.c @@ -136,7 +136,7 @@ static void destroy_async_data(struct Curl_async *); */ void Curl_resolver_cancel(struct Curl_easy *data) { - destroy_async_data(&data->conn->resolve_async); + destroy_async_data(&data->state.async); } /* This function is used to init a threaded resolve */ @@ -173,7 +173,7 @@ struct thread_data { static struct thread_sync_data *conn_thread_sync_data(struct Curl_easy *data) { - return &(data->conn->resolve_async.tdata->tsd); + return &(data->state.async.tdata->tsd); } /* Destroy resolver thread synchronization data */ @@ -428,9 +428,9 @@ static bool init_resolve_thread(struct Curl_easy *data, { struct thread_data *td = calloc(1, sizeof(struct thread_data)); int err = ENOMEM; - struct Curl_async *asp = &data->conn->resolve_async; + struct Curl_async *asp = &data->state.async; - data->conn->resolve_async.tdata = td; + data->state.async.tdata = td; if(!td) goto errno_exit; @@ -488,7 +488,7 @@ static CURLcode thread_wait_resolv(struct Curl_easy *data, CURLcode result = CURLE_OK; DEBUGASSERT(data); - td = data->conn->resolve_async.tdata; + td = data->state.async.tdata; DEBUGASSERT(td); DEBUGASSERT(td->thread_hnd != curl_thread_t_null); @@ -500,18 +500,18 @@ static CURLcode thread_wait_resolv(struct Curl_easy *data, else DEBUGASSERT(0); - data->conn->resolve_async.done = TRUE; + data->state.async.done = TRUE; if(entry) - *entry = data->conn->resolve_async.dns; + *entry = data->state.async.dns; - if(!data->conn->resolve_async.dns && report) + if(!data->state.async.dns && report) /* a name was not resolved, report error */ result = Curl_resolver_error(data); - destroy_async_data(&data->conn->resolve_async); + destroy_async_data(&data->state.async); - if(!data->conn->resolve_async.dns && report) + if(!data->state.async.dns && report) connclose(data->conn, "asynch resolve failed"); return result; @@ -524,7 +524,7 @@ static CURLcode thread_wait_resolv(struct Curl_easy *data, */ void Curl_resolver_kill(struct Curl_easy *data) { - struct thread_data *td = data->conn->resolve_async.tdata; + struct thread_data *td = data->state.async.tdata; /* If we're still resolving, we must wait for the threads to fully clean up, unfortunately. Otherwise, we can simply cancel to clean up any resolver @@ -563,7 +563,7 @@ CURLcode Curl_resolver_wait_resolv(struct Curl_easy *data, CURLcode Curl_resolver_is_resolved(struct Curl_easy *data, struct Curl_dns_entry **entry) { - struct thread_data *td = data->conn->resolve_async.tdata; + struct thread_data *td = data->state.async.tdata; int done = 0; DEBUGASSERT(entry); @@ -581,13 +581,13 @@ CURLcode Curl_resolver_is_resolved(struct Curl_easy *data, if(done) { getaddrinfo_complete(data); - if(!data->conn->resolve_async.dns) { + if(!data->state.async.dns) { CURLcode result = Curl_resolver_error(data); - destroy_async_data(&data->conn->resolve_async); + destroy_async_data(&data->state.async); return result; } - destroy_async_data(&data->conn->resolve_async); - *entry = data->conn->resolve_async.dns; + destroy_async_data(&data->state.async); + *entry = data->state.async.dns; } else { /* poll for name lookup done with exponential backoff up to 250ms */ @@ -619,9 +619,9 @@ int Curl_resolver_getsock(struct Curl_easy *data, curl_socket_t *socks) int ret_val = 0; timediff_t milli; timediff_t ms; - struct resdata *reslv = (struct resdata *)data->conn->resolve_async.resolver; + struct resdata *reslv = (struct resdata *)data->state.async.resolver; #ifndef CURL_DISABLE_SOCKETPAIR - struct thread_data *td = data->conn->resolve_async.tdata; + struct thread_data *td = data->state.async.tdata; #else (void)socks; #endif @@ -662,7 +662,7 @@ struct Curl_addrinfo *Curl_resolver_getaddrinfo(struct Curl_easy *data, int port, int *waitp) { - struct resdata *reslv = (struct resdata *)data->conn->resolve_async.resolver; + struct resdata *reslv = (struct resdata *)data->state.async.resolver; *waitp = 0; /* default to synchronous response */ @@ -691,7 +691,7 @@ struct Curl_addrinfo *Curl_resolver_getaddrinfo(struct Curl_easy *data, { struct addrinfo hints; int pf = PF_INET; - struct resdata *reslv = (struct resdata *)data->conn->resolve_async.resolver; + struct resdata *reslv = (struct resdata *)data->state.async.resolver; *waitp = 0; /* default to synchronous response */ diff --git a/lib/doh.c b/lib/doh.c index fd89596284f..d550df299a1 100644 --- a/lib/doh.c +++ b/lib/doh.c @@ -901,7 +901,6 @@ UNITTEST void de_cleanup(struct dohentry *d) CURLcode Curl_doh_is_resolved(struct Curl_easy *data, struct Curl_dns_entry **dnsp) { - struct connectdata *conn = data->conn; CURLcode result; struct dohdata *dohp = data->req.doh; *dnsp = NULL; /* defaults to no response */ @@ -910,7 +909,7 @@ CURLcode Curl_doh_is_resolved(struct Curl_easy *data, if(!dohp->probe[DOH_PROBE_SLOT_IPADDR_V4].easy && !dohp->probe[DOH_PROBE_SLOT_IPADDR_V6].easy) { - failf(data, "Could not DoH-resolve: %s", conn->resolve_async.hostname); + failf(data, "Could not DoH-resolve: %s", data->state.async.hostname); return CONN_IS_PROXIED(data->conn)?CURLE_COULDNT_RESOLVE_PROXY: CURLE_COULDNT_RESOLVE_HOST; } @@ -973,7 +972,7 @@ CURLcode Curl_doh_is_resolved(struct Curl_easy *data, Curl_freeaddrinfo(ai); } else { - conn->resolve_async.dns = dns; + data->state.async.dns = dns; *dnsp = dns; result = CURLE_OK; /* address resolution OK */ } diff --git a/lib/easy.c b/lib/easy.c index dae2afebf6d..b4ad61f2e04 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -973,6 +973,36 @@ struct Curl_easy *curl_easy_duphandle(struct Curl_easy *data) } #endif +#ifdef CURLRES_ASYNCH + /* Clone the resolver handle, if present, for the new handle */ + if(Curl_resolver_duphandle(outcurl, + &outcurl->state.async.resolver, + data->state.async.resolver)) + goto fail; +#endif + +#ifdef USE_ARES + { + CURLcode rc; + + rc = Curl_set_dns_servers(outcurl, data->set.str[STRING_DNS_SERVERS]); + if(rc && rc != CURLE_NOT_BUILT_IN) + goto fail; + + rc = Curl_set_dns_interface(outcurl, data->set.str[STRING_DNS_INTERFACE]); + if(rc && rc != CURLE_NOT_BUILT_IN) + goto fail; + + rc = Curl_set_dns_local_ip4(outcurl, data->set.str[STRING_DNS_LOCAL_IP4]); + if(rc && rc != CURLE_NOT_BUILT_IN) + goto fail; + + rc = Curl_set_dns_local_ip6(outcurl, data->set.str[STRING_DNS_LOCAL_IP6]); + if(rc && rc != CURLE_NOT_BUILT_IN) + goto fail; + } +#endif /* USE_ARES */ + Curl_initinfo(outcurl); outcurl->magic = CURLEASY_MAGIC_NUMBER; diff --git a/lib/hostasyn.c b/lib/hostasyn.c index faf01c5f4c0..2f6762ca4e1 100644 --- a/lib/hostasyn.c +++ b/lib/hostasyn.c @@ -67,11 +67,10 @@ CURLcode Curl_addrinfo_callback(struct Curl_easy *data, int status, struct Curl_addrinfo *ai) { - struct connectdata *conn = data->conn; struct Curl_dns_entry *dns = NULL; CURLcode result = CURLE_OK; - conn->resolve_async.status = status; + data->state.async.status = status; if(CURL_ASYNC_SUCCESS == status) { if(ai) { @@ -79,8 +78,8 @@ CURLcode Curl_addrinfo_callback(struct Curl_easy *data, Curl_share_lock(data, CURL_LOCK_DATA_DNS, CURL_LOCK_ACCESS_SINGLE); dns = Curl_cache_addr(data, ai, - conn->resolve_async.hostname, 0, - conn->resolve_async.port); + data->state.async.hostname, 0, + data->state.async.port); if(data->share) Curl_share_unlock(data, CURL_LOCK_DATA_DNS); @@ -95,12 +94,12 @@ CURLcode Curl_addrinfo_callback(struct Curl_easy *data, } } - conn->resolve_async.dns = dns; + data->state.async.dns = dns; /* Set async.done TRUE last in this function since it may be used multi- threaded and once this is TRUE the other thread may read fields from the async struct */ - conn->resolve_async.done = TRUE; + data->state.async.done = TRUE; /* IPv4: The input hostent struct will be freed by ares when we return from this function */ diff --git a/lib/hostip.c b/lib/hostip.c index bcdc12270a6..4f44d348f6e 100644 --- a/lib/hostip.c +++ b/lib/hostip.c @@ -741,7 +741,7 @@ enum resolve_t Curl_resolv(struct Curl_easy *data, Curl_set_in_callback(data, true); st = data->set.resolver_start( #ifdef USE_CURL_ASYNC - conn->resolve_async.resolver, + data->state.async.resolver, #else NULL, #endif @@ -1421,9 +1421,9 @@ CURLcode Curl_once_resolved(struct Curl_easy *data, bool *protocol_done) struct connectdata *conn = data->conn; #ifdef USE_CURL_ASYNC - if(conn->resolve_async.dns) { - conn->dns_entry = conn->resolve_async.dns; - conn->resolve_async.dns = NULL; + if(data->state.async.dns) { + conn->dns_entry = data->state.async.dns; + data->state.async.dns = NULL; } #endif @@ -1445,11 +1445,11 @@ CURLcode Curl_once_resolved(struct Curl_easy *data, bool *protocol_done) #ifdef USE_CURL_ASYNC CURLcode Curl_resolver_error(struct Curl_easy *data) { - struct connectdata *conn = data->conn; const char *host_or_proxy; CURLcode result; #ifndef CURL_DISABLE_PROXY + struct connectdata *conn = data->conn; if(conn->bits.httpproxy) { host_or_proxy = "proxy"; result = CURLE_COULDNT_RESOLVE_PROXY; @@ -1462,7 +1462,7 @@ CURLcode Curl_resolver_error(struct Curl_easy *data) } failf(data, "Could not resolve %s: %s", host_or_proxy, - conn->resolve_async.hostname); + data->state.async.hostname); return result; } diff --git a/lib/multi.c b/lib/multi.c index 53dee05e00a..d064102150b 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -1983,8 +1983,8 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, if(dns) { #ifdef CURLRES_ASYNCH - conn->resolve_async.dns = dns; - conn->resolve_async.done = TRUE; + data->state.async.dns = dns; + data->state.async.done = TRUE; #endif result = CURLE_OK; infof(data, "Hostname '%s' was found in DNS cache", hostname); diff --git a/lib/socks.c b/lib/socks.c index 3a396de620e..437c2a4ef3d 100644 --- a/lib/socks.c +++ b/lib/socks.c @@ -339,8 +339,8 @@ static CURLproxycode do_SOCKS4(struct Curl_cfilter *cf, if(dns) { #ifdef CURLRES_ASYNCH - conn->resolve_async.dns = dns; - conn->resolve_async.done = TRUE; + data->state.async.dns = dns; + data->state.async.done = TRUE; #endif infof(data, "Hostname '%s' was found", sx->hostname); sxstate(sx, data, CONNECT_RESOLVED); @@ -806,8 +806,8 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, if(dns) { #ifdef CURLRES_ASYNCH - conn->resolve_async.dns = dns; - conn->resolve_async.done = TRUE; + data->state.async.dns = dns; + data->state.async.done = TRUE; #endif infof(data, "SOCKS5: hostname '%s' found", sx->hostname); } diff --git a/lib/url.c b/lib/url.c index 7a270e51ed8..7764668dc23 100644 --- a/lib/url.c +++ b/lib/url.c @@ -298,6 +298,10 @@ CURLcode Curl_close(struct Curl_easy **datap) Curl_safefree(data->info.contenttype); Curl_safefree(data->info.wouldredirect); + /* this destroys the channel and we cannot use it anymore after this */ + Curl_resolver_cancel(data); + Curl_resolver_cleanup(data->state.async.resolver); + data_priority_cleanup(data); /* No longer a dirty share, if it exists */ @@ -514,6 +518,13 @@ CURLcode Curl_open(struct Curl_easy **curl) data->magic = CURLEASY_MAGIC_NUMBER; + result = Curl_resolver_init(data, &data->state.async.resolver); + if(result) { + DEBUGF(fprintf(stderr, "Error: resolver_init failed\n")); + free(data); + return result; + } + result = Curl_init_userdefined(data); if(!result) { Curl_dyn_init(&data->state.headerb, CURL_MAX_HTTP_HEADER); @@ -530,6 +541,7 @@ CURLcode Curl_open(struct Curl_easy **curl) } if(result) { + Curl_resolver_cleanup(data->state.async.resolver); Curl_dyn_free(&data->state.headerb); Curl_freeset(data); free(data); @@ -563,7 +575,6 @@ static void conn_free(struct Curl_easy *data, struct connectdata *conn) Curl_conn_cf_discard_all(data, conn, (int)i); } - Curl_resolver_cleanup(conn->resolve_async.resolver); Curl_free_idnconverted_hostname(&conn->host); Curl_free_idnconverted_hostname(&conn->conn_to_host); #ifndef CURL_DISABLE_PROXY @@ -663,7 +674,6 @@ void Curl_disconnect(struct Curl_easy *data, conn->handler->disconnect(data, conn, dead_connection); conn_shutdown(data); - Curl_resolver_cancel(data); /* detach it again */ Curl_detach_connection(data); @@ -3740,35 +3750,7 @@ static CURLcode create_conn(struct Curl_easy *data, goto out; } - result = Curl_resolver_init(data, &conn->resolve_async.resolver); - if(result) { - DEBUGF(fprintf(stderr, "Error: resolver_init failed\n")); - goto out; - } - Curl_attach_connection(data, conn); - -#ifdef USE_ARES - result = Curl_set_dns_servers(data, data->set.str[STRING_DNS_SERVERS]); - if(result && result != CURLE_NOT_BUILT_IN) - goto out; - - result = Curl_set_dns_interface(data, - data->set.str[STRING_DNS_INTERFACE]); - if(result && result != CURLE_NOT_BUILT_IN) - goto out; - - result = Curl_set_dns_local_ip4(data, - data->set.str[STRING_DNS_LOCAL_IP4]); - if(result && result != CURLE_NOT_BUILT_IN) - goto out; - - result = Curl_set_dns_local_ip6(data, - data->set.str[STRING_DNS_LOCAL_IP6]); - if(result && result != CURLE_NOT_BUILT_IN) - goto out; -#endif /* USE_ARES */ - result = Curl_conncache_add_conn(data); if(result) goto out; diff --git a/lib/urldata.h b/lib/urldata.h index 14ddee27708..be9158325b8 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -921,9 +921,6 @@ struct connectdata { multi_done(). This entry will be NULL if the connection is reused as then there is no name resolve done. */ struct Curl_dns_entry *dns_entry; -#ifdef USE_CURL_ASYNC - struct Curl_async resolve_async; /* asynchronous name resolver data */ -#endif /* 'remote_addr' is the particular IP we connected to. it is owned, set * and NULLed by the connected socket filter (if there is one). */ @@ -1381,6 +1378,9 @@ struct UrlState { #endif struct auth authhost; /* auth details for host */ struct auth authproxy; /* auth details for proxy */ +#ifdef USE_CURL_ASYNC + struct Curl_async async; /* asynchronous name resolver data */ +#endif #if defined(USE_OPENSSL) /* void instead of ENGINE to avoid bleeding OpenSSL into this header */ diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c index 737c2f7e144..f93697c1632 100644 --- a/lib/vtls/openssl.c +++ b/lib/vtls/openssl.c @@ -3175,6 +3175,8 @@ static CURLcode populate_x509_store(struct Curl_cfilter *cf, bool imported_native_ca = false; bool imported_ca_info_blob = false; + CURL_TRC_CF(data, cf, "populate_x509_store, path=%s, blob=%d", + ssl_cafile? ssl_cafile : "none", !!ca_info_blob); if(!store) return CURLE_OUT_OF_MEMORY; From 102de7aa8d5bfc6ed5fe85e89c7b943d0c186f03 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Dec 2023 17:48:22 +0100 Subject: [PATCH 041/509] curl: show ipfs and ipns as supported "protocols" They are accepted schemes in URLs passed to curl (the tool, not the library). Also makes curl-config show the same list. Co-Authored-by: Jay Satiro Reported-by: Chara White Bug: https://curl.se/mail/archive-2023-12/0026.html Closes #12508 --- CMakeLists.txt | 2 ++ configure.ac | 2 +- src/tool_help.c | 18 ++++++++++++++++++ 3 files changed, 21 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 1ec8b5519ab..d5f250da011 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1565,6 +1565,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) diff --git a/configure.ac b/configure.ac index d26a183f569..c4e026068e6 100644 --- a/configure.ac +++ b/configure.ac @@ -4661,7 +4661,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 diff --git a/src/tool_help.c b/src/tool_help.c index c8aea295d55..04ac2453707 100644 --- a/src/tool_help.c +++ b/src/tool_help.c @@ -173,12 +173,30 @@ void tool_version_info(void) printf("Release-Date: %s\n", LIBCURL_TIMESTAMP); #endif if(built_in_protos[0]) { + const char *insert = NULL; + /* we have ipfs and ipns support if libcurl has http support */ + for(builtin = built_in_protos; *builtin; ++builtin) { + if(insert) { + /* update insertion so ipfs will be printed in alphabetical order */ + if(strcmp(*builtin, "ipfs") < 0) + insert = *builtin; + else + break; + } + else if(!strcmp(*builtin, "http")) { + insert = *builtin; + } + } printf("Protocols:"); for(builtin = built_in_protos; *builtin; ++builtin) { /* Special case: do not list rtmp?* protocols. They may only appear together with "rtmp" */ if(!curl_strnequal(*builtin, "rtmp", 4) || !builtin[0][4]) printf(" %s", *builtin); + if(insert && insert == *builtin) { + printf(" ipfs ipns"); + insert = NULL; + } } puts(""); /* newline */ } From 1e9db6997ac37db18e949b57360968fde07420e3 Mon Sep 17 00:00:00 2001 From: Tatsuhiko Miyagawa Date: Sat, 16 Dec 2023 01:28:55 -0800 Subject: [PATCH 042/509] http: fix off-by-one error in request method length check It should allow one more byte. Closes #12534 --- lib/http.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/http.c b/lib/http.c index 209780ed0a2..ba625b4def5 100644 --- a/lib/http.c +++ b/lib/http.c @@ -4609,7 +4609,7 @@ CURLcode Curl_http_req_make(struct httpreq **preq, CURLcode result = CURLE_OUT_OF_MEMORY; DEBUGASSERT(method); - if(m_len + 1 >= sizeof(req->method)) + if(m_len + 1 > sizeof(req->method)) return CURLE_BAD_FUNCTION_ARGUMENT; req = calloc(1, sizeof(*req)); @@ -4765,7 +4765,7 @@ CURLcode Curl_http_req_make2(struct httpreq **preq, CURLUcode uc; DEBUGASSERT(method); - if(m_len + 1 >= sizeof(req->method)) + if(m_len + 1 > sizeof(req->method)) return CURLE_BAD_FUNCTION_ARGUMENT; req = calloc(1, sizeof(*req)); From 67211e95402df28c8730e52b9803ba95bdadbb7f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 16 Dec 2023 11:46:31 +0100 Subject: [PATCH 043/509] cmdline-docs: use .IP consistently Remove use of .TP and some .B. The idea is to reduce nroff syntax as much as possible and to use it consistently. Ultimately, we should be able to introduce our own easier-to-use-and-read syntax/formatting and convert on generation time. Closes #12535 --- docs/cmdline-opts/form.d | 6 +- docs/cmdline-opts/proto.d | 28 ++--- docs/cmdline-opts/quote.d | 36 ++---- docs/cmdline-opts/range.d | 18 +-- docs/cmdline-opts/request.d | 15 +-- docs/cmdline-opts/telnet-option.d | 12 +- docs/cmdline-opts/variable.d | 12 +- docs/cmdline-opts/write-out.d | 195 ++++++++++-------------------- 8 files changed, 110 insertions(+), 212 deletions(-) diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d index e53e93ae0dd..ac0e4bfefb2 100644 --- a/docs/cmdline-opts/form.d +++ b/docs/cmdline-opts/form.d @@ -101,12 +101,12 @@ Here is an example of a header file contents: another header To support sending multipart mail messages, the syntax is extended as follows: -.br + - name can be omitted: the equal sign is the first character of the argument, -.br + - if data starts with '(', this signals to start a new multipart: it can be followed by a content type specification. -.br + - a multipart can be terminated with a '=)' argument. Example: the following command sends an SMTP mime email consisting in an diff --git a/docs/cmdline-opts/proto.d b/docs/cmdline-opts/proto.d index ac024bf4289..6788ee567db 100644 --- a/docs/cmdline-opts/proto.d +++ b/docs/cmdline-opts/proto.d @@ -13,33 +13,23 @@ 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 + +.IP + Permit this protocol in addition to protocols already permitted (this is the default if no modifier is used). -.TP -.B - +.IP - Deny this protocol, removing it from the list of protocols already permitted. -.TP -.B = +.IP = 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 +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. diff --git a/docs/cmdline-opts/quote.d b/docs/cmdline-opts/quote.d index 5008d49321d..51f7917fc37 100644 --- a/docs/cmdline-opts/quote.d +++ b/docs/cmdline-opts/quote.d @@ -35,53 +35,41 @@ 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"** +.IP "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"** +.IP "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"** +.IP "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"** +.IP "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"** +.IP "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"** +.IP "mkdir directory_name" The mkdir command creates the directory named by the directory_name operand. -.TP -**"mtime date file"** +.IP "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"** +.IP "pwd" The pwd command returns the absolute path name of the current working directory. -.TP -**"rename source target"** +.IP "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"** +.IP "rm file" The rm command removes the file specified by the file operand. -.TP -**"rmdir directory"** +.IP "rmdir directory" The rmdir command removes the directory entry specified by the directory operand, provided it is empty. -.TP -**"symlink source_file target_file"** +.IP "symlink source_file target_file" See ln. .RE .IP diff --git a/docs/cmdline-opts/range.d b/docs/cmdline-opts/range.d index eba7220e1e9..09ccf5f310a 100644 --- a/docs/cmdline-opts/range.d +++ b/docs/cmdline-opts/range.d @@ -14,23 +14,17 @@ 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 +.IP 0-499 specifies the first 500 bytes -.TP -.B 500-999 +.IP 500-999 specifies the second 500 bytes -.TP -.B -500 +.IP -500 specifies the last 500 bytes -.TP -.B 9500- +.IP 9500- specifies the bytes from offset 9500 and forward -.TP -.B 0-0,-1 +.IP 0-0,-1 specifies the first and last byte only(*)(HTTP) -.TP -.B 100-199,500-599 +.IP 100-199,500-599 specifies two separate 100-byte ranges(*) (HTTP) .RE .IP diff --git a/docs/cmdline-opts/request.d b/docs/cmdline-opts/request.d index 6afd5356483..41d81c55afd 100644 --- a/docs/cmdline-opts/request.d +++ b/docs/cmdline-opts/request.d @@ -16,8 +16,7 @@ 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** +.IP 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 @@ -36,19 +35,15 @@ 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** +.IP FTP Specifies a custom FTP command to use instead of *LIST* when doing file lists with FTP. -.TP -**POP3** +.IP POP3 Specifies a custom POP3 command to use instead of *LIST* or *RETR*. (Added in 7.26.0) -.TP -**IMAP** +.IP IMAP Specifies a custom IMAP command to use instead of *LIST*. (Added in 7.30.0) -.TP -**SMTP** +.IP 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/telnet-option.d b/docs/cmdline-opts/telnet-option.d index 651ce4203e7..56bf5be636d 100644 --- a/docs/cmdline-opts/telnet-option.d +++ b/docs/cmdline-opts/telnet-option.d @@ -13,11 +13,11 @@ 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. +.IP "TTYPE=" +Sets the terminal type. +.IP "XDISPLOC=" +Sets the X display location. +.IP "NEW_ENV=" +Sets an environment variable. .RE .IP diff --git a/docs/cmdline-opts/variable.d b/docs/cmdline-opts/variable.d index d7d773edab6..2029601976b 100644 --- a/docs/cmdline-opts/variable.d +++ b/docs/cmdline-opts/variable.d @@ -39,17 +39,13 @@ error. Available functions: .RS -.TP 15 -**trim** +.IP trim removes all leading and trailing white space. -.TP -**json** +.IP json outputs the content using JSON string quoting rules. -.TP -**url** +.IP url shows the content URL (percent) encoded. -.TP -**b64** +.IP b64 expands the variable base64 encoded .RE .IP diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d index e069afcf1ec..d21a747dc5f 100644 --- a/docs/cmdline-opts/write-out.d +++ b/docs/cmdline-opts/write-out.d @@ -46,31 +46,24 @@ the % cannot be escaped and unintended expansion is possible. The variables available are: .RS -.TP 15 -**certs** +.IP certs Output the certificate chain with details. Supported only by the OpenSSL, GnuTLS, Schannel and Secure Transport backends. (Added in 7.88.0) -.TP -**content_type** +.IP content_type The Content-Type of the requested document, if there was any. -.TP -**errormsg** +.IP errormsg The error message. (Added in 7.75.0) -.TP -**exitcode** +.IP exitcode The numerical exit code of the transfer. (Added in 7.75.0) -.TP -**filename_effective** +.IP filename_effective The ultimate filename that curl writes out to. This is only meaningful if curl is told to write to a file with the --remote-name or --output option. It's most useful in combination with the --remote-header-name option. (Added in 7.26.0) -.TP -**ftp_entry_path** +.IP ftp_entry_path The initial path curl ended up in when logging on to the remote FTP server. (Added in 7.15.4) -.TP -**header_json** +.IP header_json A JSON object with all HTTP response headers from the recent transfer. Values are provided as arrays, since in the case of multiple headers there can be multiple values. (Added in 7.83.0) @@ -78,214 +71,156 @@ multiple values. (Added in 7.83.0) The header names provided in lowercase, listed in order of appearance over the wire. Except for duplicated headers. They are grouped on the first occurrence of that header, each value is presented in the JSON array. -.TP -**http_code** +.IP http_code The numerical response code that was found in the last retrieved HTTP(S) or FTP(s) transfer. -.TP -**http_connect** +.IP http_connect The numerical code that was found in the last response (from a proxy) to a curl CONNECT request. (Added in 7.12.4) -.TP -**http_version** +.IP http_version The http version that was effectively used. (Added in 7.50.0) -.TP -**json** +.IP json A JSON object with all available keys. (Added in 7.70.0) -.TP -**local_ip** +.IP local_ip The IP address of the local end of the most recently done connection - can be either IPv4 or IPv6. (Added in 7.29.0) -.TP -**local_port** +.IP local_port The local port number of the most recently done connection. (Added in 7.29.0) -.TP -**method** +.IP method The http method used in the most recent HTTP request. (Added in 7.72.0) -.TP -**num_certs** +.IP num_certs Number of server certificates received in the TLS handshake. Supported only by the OpenSSL, GnuTLS, Schannel and Secure Transport backends. (Added in 7.88.0) -.TP -**num_connects** +.IP num_connects Number of new connects made in the recent transfer. (Added in 7.12.3) -.TP -**num_headers** +.IP num_headers The number of response headers in the most recent request (restarted at each redirect). Note that the status line IS NOT a header. (Added in 7.73.0) -.TP -**num_redirects** +.IP num_redirects Number of redirects that were followed in the request. (Added in 7.12.3) -.TP -**onerror** +.IP onerror The rest of the output is only shown if the transfer returned a non-zero error. (Added in 7.75.0) -.TP -**proxy_ssl_verify_result** +.IP "proxy_ssl_verify_result" The result of the HTTPS proxy's SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.52.0) -.TP -**redirect_url** +.IP redirect_url When an HTTP request was made without --location to follow redirects (or when --max-redirs is met), this variable shows the actual URL a redirect *would* have gone to. (Added in 7.18.2) -.TP -**referer** +.IP referer The Referer: header, if there was any. (Added in 7.76.0) -.TP -**remote_ip** +.IP remote_ip The remote IP address of the most recently done connection - can be either IPv4 or IPv6. (Added in 7.29.0) -.TP -**remote_port** +.IP remote_port The remote port number of the most recently done connection. (Added in 7.29.0) -.TP -**response_code** +.IP response_code The numerical response code that was found in the last transfer (formerly known as "http_code"). (Added in 7.18.2) -.TP -**scheme** +.IP scheme The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0) -.TP -**size_download** +.IP size_download The total amount of bytes that were downloaded. This is the size of the body/data that was transferred, excluding headers. -.TP -**size_header** +.IP size_header The total amount of bytes of the downloaded headers. -.TP -**size_request** +.IP size_request The total amount of bytes that were sent in the HTTP request. -.TP -**size_upload** +.IP size_upload The total amount of bytes that were uploaded. This is the size of the body/data that was transferred, excluding headers. -.TP -**speed_download** +.IP speed_download The average download speed that curl measured for the complete download. Bytes per second. -.TP -**speed_upload** +.IP speed_upload The average upload speed that curl measured for the complete upload. Bytes per second. -.TP -**ssl_verify_result** +.IP ssl_verify_result The result of the SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.19.0) -.TP -**stderr** +.IP stderr From this point on, the --write-out output is written to standard error. (Added in 7.63.0) -.TP -**stdout** +.IP stdout From this point on, the --write-out output is written to standard output. This is the default, but can be used to switch back after switching to stderr. (Added in 7.63.0) -.TP -**time_appconnect** +.IP time_appconnect The time, in seconds, it took from the start until the SSL/SSH/etc connect/handshake to the remote host was completed. (Added in 7.19.0) -.TP -**time_connect** +.IP time_connect The time, in seconds, it took from the start until the TCP connect to the remote host (or proxy) was completed. -.TP -**time_namelookup** +.IP time_namelookup The time, in seconds, it took from the start until the name resolving was completed. -.TP -**time_pretransfer** +.IP time_pretransfer The time, in seconds, it took from the start until the file transfer was just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. -.TP -**time_redirect** +.IP time_redirect The time, in seconds, it took for all redirection steps including name lookup, connect, pretransfer and transfer before the final transaction was started. time_redirect shows the complete execution time for multiple redirections. (Added in 7.12.3) -.TP -**time_starttransfer** +.IP time_starttransfer The time, in seconds, it took from the start until the first byte is received. This includes time_pretransfer and also the time the server needed to calculate the result. -.TP -**time_total** +.IP time_total The total time, in seconds, that the full operation lasted. -.TP -**url** +.IP url The URL that was fetched. (Added in 7.75.0) -.TP -**url.scheme** +.IP url.scheme The scheme part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.user** +.IP url.user The user part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.password** +.IP url.password The password part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.options** +.IP url.options The options part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.host** +.IP url.host The host part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.port** +.IP url.port The port number of the URL that was fetched. If no port number was specified, but the URL scheme is known, that scheme's default port number is shown. (Added in 8.1.0) -.TP -**url.path** +.IP url.path The path part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.query** +.IP url.query The query part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.fragment** +.IP url.fragment The fragment part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.zoneid** +.IP url.zoneid The zone id part of the URL that was fetched. (Added in 8.1.0) -.TP -**urle.scheme** +.IP urle.scheme The scheme part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.user** +.IP urle.user The user part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.password** +.IP urle.password The password part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.options** +.IP urle.options The options part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.host** +.IP urle.host The host part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.port** +.IP urle.port The port number of the effective (last) URL that was fetched. If no port number was specified, but the URL scheme is known, that scheme's default port number is shown. (Added in 8.1.0) -.TP -**urle.path** +.IP urle.path The path part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.query** +.IP urle.query The query part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.fragment** +.IP urle.fragment The fragment part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.zoneid** +.IP urle.zoneid The zone id part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urlnum** +.IP urlnum The URL index number of this transfer, 0-indexed. Unglobbed URLs share the same index number as the origin globbed URL. (Added in 7.75.0) -.TP -**url_effective** +.IP url_effective The URL that was fetched last. This is most meaningful if you have told curl to follow location: headers. .RE From ba8752e5566076acc8bdec7ae4ec78901f7050f4 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sat, 28 Oct 2023 09:48:19 +0000 Subject: [PATCH 044/509] Makefile.mk: drop Windows support And DLL-support with it. This leaves `Makefile.mk` for MS-DOS and Amiga. We recommend CMake instead. With unity mode it's much faster, and about the same without. Ref: https://github.com/curl/curl/pull/12221#issuecomment-1783761806 Reviewed-by: Daniel Stenberg Closes #12224 --- .github/labeler.yml | 1 - Makefile.dist | 21 ----- docs/INSTALL.md | 48 ---------- docs/examples/Makefile.mk | 26 +----- lib/Makefile.mk | 189 ++++++++++---------------------------- src/Makefile.mk | 29 +----- 6 files changed, 53 insertions(+), 261 deletions(-) diff --git a/.github/labeler.yml b/.github/labeler.yml index 2bd1fde8b73..4f87314d282 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -481,7 +481,6 @@ Windows: - all: - changed-files: - any-glob-to-all-files: - - '**/Makefile.mk' - 'appveyor.yml' - 'CMake/Platforms/WindowsCache.cmake' - 'lib/*win32*' 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/docs/INSTALL.md b/docs/INSTALL.md index a6780b45ddc..97ee408bb52 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -185,54 +185,6 @@ 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 diff --git a/docs/examples/Makefile.mk b/docs/examples/Makefile.mk index 599acee0bc3..5a5372dd3de 100644 --- a/docs/examples/Makefile.mk +++ b/docs/examples/Makefile.mk @@ -26,10 +26,6 @@ PROOT := ../.. -ifeq ($(findstring -static,$(CFG)),) - DYN := 1 -endif - ### Common include $(PROOT)/lib/Makefile.mk @@ -40,35 +36,17 @@ CPPFLAGS += -DCURL_NO_OLDIES LDFLAGS += -L$(PROOT)/lib LIBS := -lcurl $(LIBS) -ifdef DYN - curl_DEPENDENCIES += $(PROOT)/lib/libcurl.dll.a -else - curl_DEPENDENCIES := $(PROOT)/lib/libcurl.a - ifdef WIN32 - CPPFLAGS += -DCURL_STATICLIB - LDFLAGS += -static - endif -endif - -ifdef WIN32 - LIBS += -lws2_32 -endif - ### Sources and targets # Provides check_PROGRAMS include Makefile.inc -ifdef WIN32 -check_PROGRAMS += synctime -endif - TARGETS := $(patsubst %,%$(BIN_EXT),$(strip $(check_PROGRAMS))) TOCLEAN := $(TARGETS) ### Rules -%$(BIN_EXT): %.c $(curl_DEPENDENCIES) - $(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $(CURL_LDFLAGS_BIN) $< -o $@ $(LIBS) +%$(BIN_EXT): %.c $(PROOT)/lib/libcurl.a + $(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $< -o $@ $(LIBS) all: $(TARGETS) diff --git a/lib/Makefile.mk b/lib/Makefile.mk index 1513cafef90..95f281b7d87 100644 --- a/lib/Makefile.mk +++ b/lib/Makefile.mk @@ -24,8 +24,8 @@ # Makefile to build curl parts with GCC-like toolchains and optional features. # -# Usage: [mingw32-]make -f Makefile.mk CFG=-feat1[-feat2][-feat3][...] -# Example: [mingw32-]make -f Makefile.mk CFG=-zlib-ssl-libssh2-ipv6 +# Usage: make -f Makefile.mk CFG=-feat1[-feat2][-feat3][...] +# Example: make -f Makefile.mk CFG=-zlib-ssl-libssh2-ipv6 # # Look for ' ?=' to find all accepted customization variables. @@ -40,10 +40,7 @@ endif CFLAGS ?= CPPFLAGS ?= -RCFLAGS ?= LDFLAGS ?= -CURL_LDFLAGS_BIN ?= -CURL_LDFLAGS_LIB ?= LIBS ?= CROSSPREFIX ?= @@ -53,46 +50,21 @@ ifeq ($(CC),cc) endif CC := $(CROSSPREFIX)$(CC) AR := $(CROSSPREFIX)$(AR) -RC ?= $(CROSSPREFIX)windres - -# For compatibility -ARCH ?= -ifeq ($(ARCH),w64) - TRIPLET := x86_64-w64-mingw32 - CFLAGS += -m64 - LDFLAGS += -m64 - RCFLAGS += --target=pe-x86-64 -else ifdef ARCH - TRIPLET := i686-w64-mingw32 - CFLAGS += -m32 - LDFLAGS += -m32 - RCFLAGS += --target=pe-i386 -else - TRIPLET ?= $(shell $(CC) -dumpmachine) -endif -BIN_EXT := .exe +TRIPLET ?= $(shell $(CC) -dumpmachine) -ifneq ($(findstring -w,$(TRIPLET)),) - WIN32 := 1 -else ifneq ($(findstring msdos,$(TRIPLET)),) +BIN_EXT := + +ifneq ($(findstring msdos,$(TRIPLET)),) # Cross-tools: https://github.com/andrewwutw/build-djgpp MSDOS := 1 + BIN_EXT := .exe else ifneq ($(findstring amigaos,$(TRIPLET)),) # Cross-tools: https://github.com/bebbo/amiga-gcc AMIGA := 1 endif CPPFLAGS += -I. -I$(PROOT)/include -RCFLAGS += -I$(PROOT)/include - -ifndef WIN32 - DYN := -endif - -ifdef AMIGA - BIN_EXT := -endif ### Deprecated settings. For compatibility. @@ -115,40 +87,26 @@ ifneq ($(findstring -map,$(CFG)),) MAP := 1 endif -ifdef WIN32 - ifneq ($(findstring -unicode,$(CFG)),) - CPPFLAGS += -DUNICODE -D_UNICODE - CURL_LDFLAGS_BIN += -municode - endif -endif - # CPPFLAGS below are only necessary when building libcurl via 'lib' (see # comments below about exceptions). Always include them anyway to match # behavior of other build systems. -# Linker options to exclude for shared mode executables. -_LDFLAGS := -_LIBS := - ifneq ($(findstring -sync,$(CFG)),) CPPFLAGS += -DUSE_SYNC_DNS else ifneq ($(findstring -ares,$(CFG)),) LIBCARES_PATH ?= $(PROOT)/../c-ares CPPFLAGS += -DUSE_ARES CPPFLAGS += -I"$(LIBCARES_PATH)/include" - _LDFLAGS += -L"$(LIBCARES_PATH)/lib" - _LIBS += -lcares + LDFLAGS += -L"$(LIBCARES_PATH)/lib" + LIBS += -lcares endif ifneq ($(findstring -rtmp,$(CFG)),) LIBRTMP_PATH ?= $(PROOT)/../librtmp CPPFLAGS += -DUSE_LIBRTMP CPPFLAGS += -I"$(LIBRTMP_PATH)" - _LDFLAGS += -L"$(LIBRTMP_PATH)/librtmp" - _LIBS += -lrtmp - ifdef WIN32 - _LIBS += -lwinmm - endif + LDFLAGS += -L"$(LIBRTMP_PATH)/librtmp" + LIBS += -lrtmp ZLIB := 1 endif @@ -156,23 +114,20 @@ ifneq ($(findstring -ssh2,$(CFG)),) LIBSSH2_PATH ?= $(PROOT)/../libssh2 CPPFLAGS += -DUSE_LIBSSH2 CPPFLAGS += -I"$(LIBSSH2_PATH)/include" - _LDFLAGS += -L"$(LIBSSH2_PATH)/lib" - ifdef WIN32 - _LDFLAGS += -L"$(LIBSSH2_PATH)/win32" - endif - _LIBS += -lssh2 + LDFLAGS += -L"$(LIBSSH2_PATH)/lib" + LIBS += -lssh2 else ifneq ($(findstring -libssh,$(CFG)),) LIBSSH_PATH ?= $(PROOT)/../libssh CPPFLAGS += -DUSE_LIBSSH CPPFLAGS += -I"$(LIBSSH_PATH)/include" - _LDFLAGS += -L"$(LIBSSH_PATH)/lib" - _LIBS += -lssh + LDFLAGS += -L"$(LIBSSH_PATH)/lib" + LIBS += -lssh else ifneq ($(findstring -wolfssh,$(CFG)),) WOLFSSH_PATH ?= $(PROOT)/../wolfssh CPPFLAGS += -DUSE_WOLFSSH CPPFLAGS += -I"$(WOLFSSH_PATH)/include" - _LDFLAGS += -L"$(WOLFSSH_PATH)/lib" - _LIBS += -lwolfssh + LDFLAGS += -L"$(WOLFSSH_PATH)/lib" + LIBS += -lwolfssh endif ifneq ($(findstring -ssl,$(CFG)),) @@ -182,9 +137,9 @@ ifneq ($(findstring -ssl,$(CFG)),) OPENSSL_INCLUDE ?= $(OPENSSL_PATH)/include OPENSSL_LIBPATH ?= $(OPENSSL_PATH)/lib CPPFLAGS += -I"$(OPENSSL_INCLUDE)" - _LDFLAGS += -L"$(OPENSSL_LIBPATH)" + LDFLAGS += -L"$(OPENSSL_LIBPATH)" OPENSSL_LIBS ?= -lssl -lcrypto - _LIBS += $(OPENSSL_LIBS) + LIBS += $(OPENSSL_LIBS) ifneq ($(findstring -srp,$(CFG)),) ifneq ($(wildcard $(OPENSSL_INCLUDE)/openssl/srp.h),) @@ -199,20 +154,16 @@ ifneq ($(findstring -wolfssl,$(CFG)),) CPPFLAGS += -DUSE_WOLFSSL CPPFLAGS += -DSIZEOF_LONG_LONG=8 CPPFLAGS += -I"$(WOLFSSL_PATH)/include" - _LDFLAGS += -L"$(WOLFSSL_PATH)/lib" - _LIBS += -lwolfssl + LDFLAGS += -L"$(WOLFSSL_PATH)/lib" + LIBS += -lwolfssl SSLLIBS += 1 endif ifneq ($(findstring -mbedtls,$(CFG)),) MBEDTLS_PATH ?= $(PROOT)/../mbedtls CPPFLAGS += -DUSE_MBEDTLS CPPFLAGS += -I"$(MBEDTLS_PATH)/include" - _LDFLAGS += -L"$(MBEDTLS_PATH)/lib" - _LIBS += -lmbedtls -lmbedx509 -lmbedcrypto - SSLLIBS += 1 -endif -ifneq ($(findstring -schannel,$(CFG)),) - CPPFLAGS += -DUSE_SCHANNEL + LDFLAGS += -L"$(MBEDTLS_PATH)/lib" + LIBS += -lmbedtls -lmbedx509 -lmbedcrypto SSLLIBS += 1 endif @@ -220,21 +171,21 @@ ifneq ($(findstring -nghttp2,$(CFG)),) NGHTTP2_PATH ?= $(PROOT)/../nghttp2 CPPFLAGS += -DUSE_NGHTTP2 CPPFLAGS += -I"$(NGHTTP2_PATH)/include" - _LDFLAGS += -L"$(NGHTTP2_PATH)/lib" - _LIBS += -lnghttp2 + LDFLAGS += -L"$(NGHTTP2_PATH)/lib" + LIBS += -lnghttp2 endif ifeq ($(findstring -nghttp3,$(CFG))$(findstring -ngtcp2,$(CFG)),-nghttp3-ngtcp2) NGHTTP3_PATH ?= $(PROOT)/../nghttp3 CPPFLAGS += -DUSE_NGHTTP3 CPPFLAGS += -I"$(NGHTTP3_PATH)/include" - _LDFLAGS += -L"$(NGHTTP3_PATH)/lib" - _LIBS += -lnghttp3 + LDFLAGS += -L"$(NGHTTP3_PATH)/lib" + LIBS += -lnghttp3 NGTCP2_PATH ?= $(PROOT)/../ngtcp2 CPPFLAGS += -DUSE_NGTCP2 CPPFLAGS += -I"$(NGTCP2_PATH)/include" - _LDFLAGS += -L"$(NGTCP2_PATH)/lib" + LDFLAGS += -L"$(NGTCP2_PATH)/lib" NGTCP2_LIBS ?= ifeq ($(NGTCP2_LIBS),) @@ -249,7 +200,7 @@ ifeq ($(findstring -nghttp3,$(CFG))$(findstring -ngtcp2,$(CFG)),-nghttp3-ngtcp2) endif endif - _LIBS += -lngtcp2 $(NGTCP2_LIBS) + LIBS += -lngtcp2 $(NGTCP2_LIBS) endif ifneq ($(findstring -zlib,$(CFG))$(ZLIB),) @@ -257,59 +208,51 @@ ifneq ($(findstring -zlib,$(CFG))$(ZLIB),) # These CPPFLAGS are also required when compiling the curl tool via 'src'. CPPFLAGS += -DHAVE_LIBZ CPPFLAGS += -I"$(ZLIB_PATH)/include" - _LDFLAGS += -L"$(ZLIB_PATH)/lib" + LDFLAGS += -L"$(ZLIB_PATH)/lib" ZLIB_LIBS ?= -lz - _LIBS += $(ZLIB_LIBS) + LIBS += $(ZLIB_LIBS) ZLIB := 1 endif ifneq ($(findstring -zstd,$(CFG)),) ZSTD_PATH ?= $(PROOT)/../zstd CPPFLAGS += -DHAVE_ZSTD CPPFLAGS += -I"$(ZSTD_PATH)/include" - _LDFLAGS += -L"$(ZSTD_PATH)/lib" + LDFLAGS += -L"$(ZSTD_PATH)/lib" ZSTD_LIBS ?= -lzstd - _LIBS += $(ZSTD_LIBS) + LIBS += $(ZSTD_LIBS) endif ifneq ($(findstring -brotli,$(CFG)),) BROTLI_PATH ?= $(PROOT)/../brotli CPPFLAGS += -DHAVE_BROTLI CPPFLAGS += -I"$(BROTLI_PATH)/include" - _LDFLAGS += -L"$(BROTLI_PATH)/lib" + LDFLAGS += -L"$(BROTLI_PATH)/lib" BROTLI_LIBS ?= -lbrotlidec -lbrotlicommon - _LIBS += $(BROTLI_LIBS) + LIBS += $(BROTLI_LIBS) endif ifneq ($(findstring -gsasl,$(CFG)),) LIBGSASL_PATH ?= $(PROOT)/../gsasl CPPFLAGS += -DUSE_GSASL CPPFLAGS += -I"$(LIBGSASL_PATH)/include" - _LDFLAGS += -L"$(LIBGSASL_PATH)/lib" - _LIBS += -lgsasl + LDFLAGS += -L"$(LIBGSASL_PATH)/lib" + LIBS += -lgsasl endif ifneq ($(findstring -idn2,$(CFG)),) LIBIDN2_PATH ?= $(PROOT)/../libidn2 CPPFLAGS += -DUSE_LIBIDN2 CPPFLAGS += -I"$(LIBIDN2_PATH)/include" - _LDFLAGS += -L"$(LIBIDN2_PATH)/lib" - _LIBS += -lidn2 + LDFLAGS += -L"$(LIBIDN2_PATH)/lib" + LIBS += -lidn2 ifneq ($(findstring -psl,$(CFG)),) LIBPSL_PATH ?= $(PROOT)/../libpsl CPPFLAGS += -DUSE_LIBPSL CPPFLAGS += -I"$(LIBPSL_PATH)/include" - _LDFLAGS += -L"$(LIBPSL_PATH)/lib" - _LIBS += -lpsl + LDFLAGS += -L"$(LIBPSL_PATH)/lib" + LIBS += -lpsl endif -else ifneq ($(findstring -winidn,$(CFG)),) - CPPFLAGS += -DUSE_WIN32_IDN - _LIBS += -lnormaliz endif -ifneq ($(findstring -sspi,$(CFG)),) - ifdef WIN32 - CPPFLAGS += -DUSE_WINDOWS_SSPI - endif -endif ifneq ($(findstring -ipv6,$(CFG)),) CPPFLAGS += -DENABLE_IPV6 endif @@ -317,26 +260,14 @@ endif ifneq ($(findstring -watt,$(CFG))$(MSDOS),) WATT_PATH ?= $(PROOT)/../watt CPPFLAGS += -I"$(WATT_PATH)/inc" - _LDFLAGS += -L"$(WATT_PATH)/lib" - _LIBS += -lwatt -endif - -ifdef WIN32 - ifeq ($(findstring -lldap,$(LIBS)),) - _LIBS += -lwldap32 - endif - _LIBS += -lws2_32 -lcrypt32 -lbcrypt + LDFLAGS += -L"$(WATT_PATH)/lib" + LIBS += -lwatt endif ifneq ($(findstring 11,$(subst $(subst ,, ),,$(SSLLIBS))),) CPPFLAGS += -DCURL_WITH_MULTI_SSL endif -ifndef DYN - LDFLAGS += $(_LDFLAGS) - LIBS += $(_LIBS) -endif - ### Common rules OBJ_DIR := $(TRIPLET) @@ -363,9 +294,6 @@ $(OBJ_DIR): $(OBJ_DIR)/%.o: %.c $(CC) -W -Wall $(CFLAGS) $(CPPFLAGS) -c $< -o $@ -$(OBJ_DIR)/%.res: %.rc - $(RC) -O coff $(RCFLAGS) -i $< -o $@ - clean: @$(call DEL, $(TOCLEAN)) @$(RMDIR) $(OBJ_DIR) @@ -378,42 +306,23 @@ distclean vclean: clean ifdef LOCAL CPPFLAGS += -DBUILDING_LIBCURL -ifdef WIN32 -CPPFLAGS += -DCURL_STATICLIB -endif ### Sources and targets -# Provides CSOURCES, HHEADERS, LIB_RCFILES +# Provides CSOURCES, HHEADERS include Makefile.inc vpath %.c vauth vquic vssh vtls libcurl_a_LIBRARY := libcurl.a -ifdef WIN32 -CURL_DLL_SUFFIX ?= -libcurl_dll_LIBRARY := libcurl$(CURL_DLL_SUFFIX).dll -libcurl_dll_a_LIBRARY := libcurl.dll.a -ifeq ($(findstring -trackmem,$(CFG)),) -CURL_LDFLAGS_LIB += $(PROOT)/libcurl.def -endif -ifdef MAP -libcurl_map_LIBRARY := libcurl$(CURL_DLL_SUFFIX).map -CURL_LDFLAGS_LIB += -Wl,-Map,$(libcurl_map_LIBRARY) -endif -endif -TARGETS := $(libcurl_a_LIBRARY) $(libcurl_dll_LIBRARY) +TARGETS := $(libcurl_a_LIBRARY) libcurl_a_OBJECTS := $(patsubst %.c,$(OBJ_DIR)/%.o,$(notdir $(strip $(CSOURCES)))) libcurl_a_DEPENDENCIES := $(strip $(CSOURCES) $(HHEADERS)) -ifdef WIN32 -libcurl_dll_OBJECTS := $(libcurl_a_OBJECTS) -libcurl_dll_OBJECTS += $(patsubst %.rc,$(OBJ_DIR)/%.res,$(strip $(LIB_RCFILES))) -endif -TOCLEAN := $(libcurl_dll_OBJECTS) -TOVCLEAN := $(libcurl_dll_LIBRARY:.dll=.def) $(libcurl_dll_a_LIBRARY) $(libcurl_map_LIBRARY) +TOCLEAN := +TOVCLEAN := ### Rules @@ -421,9 +330,5 @@ $(libcurl_a_LIBRARY): $(libcurl_a_OBJECTS) $(libcurl_a_DEPENDENCIES) @$(call DEL, $@) $(AR) rcs $@ $(libcurl_a_OBJECTS) -$(libcurl_dll_LIBRARY): $(libcurl_dll_OBJECTS) - $(CC) $(LDFLAGS) -shared $(CURL_LDFLAGS_LIB) -o $@ $(libcurl_dll_OBJECTS) $(LIBS) \ - -Wl,--output-def,$(@:.dll=.def),--out-implib,$(libcurl_dll_a_LIBRARY) - all: $(OBJ_DIR) $(TARGETS) endif diff --git a/src/Makefile.mk b/src/Makefile.mk index 66882b3536a..83dd65d16fc 100644 --- a/src/Makefile.mk +++ b/src/Makefile.mk @@ -32,31 +32,13 @@ include $(PROOT)/lib/Makefile.mk ### Local -RCFLAGS += -DCURL_EMBED_MANIFEST CPPFLAGS += -I$(PROOT)/lib LDFLAGS += -L$(PROOT)/lib LIBS := -lcurl $(LIBS) -ifdef WIN32 - ifneq ($(findstring -dyn,$(CFG)),) - DYN := 1 - endif -endif - -ifdef DYN - curl_DEPENDENCIES := $(PROOT)/lib/libcurl$(CURL_DLL_SUFFIX).dll - curl_DEPENDENCIES += $(PROOT)/lib/libcurl.dll.a -else - curl_DEPENDENCIES := $(PROOT)/lib/libcurl.a - ifdef WIN32 - CPPFLAGS += -DCURL_STATICLIB - LDFLAGS += -static - endif -endif - ### Sources and targets -# Provides CURL_CFILES, CURLX_CFILES, CURL_RCFILES +# Provides CURL_CFILES, CURLX_CFILES include Makefile.inc TARGETS := curl$(BIN_EXT) @@ -64,12 +46,9 @@ TARGETS := curl$(BIN_EXT) CURL_CFILES += $(notdir $(CURLX_CFILES)) curl_OBJECTS := $(patsubst %.c,$(OBJ_DIR)/%.o,$(strip $(CURL_CFILES))) -ifdef WIN32 -curl_OBJECTS += $(patsubst %.rc,$(OBJ_DIR)/%.res,$(strip $(CURL_RCFILES))) -endif ifdef MAP CURL_MAP := curl.map -CURL_LDFLAGS_BIN += -Wl,-Map,$(CURL_MAP) +LDFLAGS += -Wl,-Map,$(CURL_MAP) TOVCLEAN := $(CURL_MAP) endif vpath %.c $(PROOT)/lib @@ -105,7 +84,7 @@ tool_hugehelp.c: endif endif -$(TARGETS): $(curl_OBJECTS) $(curl_DEPENDENCIES) - $(CC) $(LDFLAGS) $(CURL_LDFLAGS_BIN) -o $@ $(curl_OBJECTS) $(LIBS) +$(TARGETS): $(curl_OBJECTS) $(PROOT)/lib/libcurl.a + $(CC) $(LDFLAGS) -o $@ $(curl_OBJECTS) $(LIBS) all: $(OBJ_DIR) $(TARGETS) From 3829759bd042c03225ae862062560f568ba1a231 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Fri, 8 Dec 2023 13:05:09 +0000 Subject: [PATCH 045/509] build: enable missing OpenSSF-recommended warnings, with fixes https://best.openssf.org/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.html as of 2023-11-29 [1]. Enable new recommended warnings (except `-Wsign-conversion`): - enable `-Wformat=2` for clang (in both cmake and autotools). - add `CURL_PRINTF()` internal attribute and mark functions accepting printf arguments with it. This is a copy of existing `CURL_TEMP_PRINTF()` but using `__printf__` to make it compatible with redefinting the `printf` symbol: https://gcc.gnu.org/onlinedocs/gcc-3.0.4/gcc_5.html#SEC94 - fix `CURL_PRINTF()` and existing `CURL_TEMP_PRINTF()` for mingw-w64 and enable it on this platform. - enable `-Wimplicit-fallthrough`. - enable `-Wtrampolines`. - add `-Wsign-conversion` commented with a FIXME. - cmake: enable `-pedantic-errors` the way we do it with autotools. Follow-up to d5c0351055d5709da8f3e16c91348092fdb481aa #2747 - lib/curl_trc.h: use `CURL_FORMAT()`, this also fixes it to enable format checks. Previously it was always disabled due to the internal `printf` macro. Fix them: - fix bug where an `set_ipv6_v6only()` call was missed in builds with `--disable-verbose` / `CURL_DISABLE_VERBOSE_STRINGS=ON`. - add internal `FALLTHROUGH()` macro. - replace obsolete fall-through comments with `FALLTHROUGH()`. - fix fallthrough markups: Delete redundant ones (showing up as warnings in most cases). Add missing ones. Fix indentation. - silence `-Wformat-nonliteral` warnings with llvm/clang. - fix one `-Wformat-nonliteral` warning. - fix new `-Wformat` and `-Wformat-security` warnings. - fix `CURL_FORMAT_SOCKET_T` value for mingw-w64. Also move its definition to `lib/curl_setup.h` allowing use in `tests/server`. - lib: fix two wrongly passed string arguments in log outputs. Co-authored-by: Jay Satiro - fix new `-Wformat` warnings on mingw-w64. [1] https://github.com/ossf/wg-best-practices-os-developers/blob/56c0fde3895bfc55c8a973ef49a2572c507b2ae1/docs/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C%2B%2B.md Closes #12489 --- CMake/PickyWarnings.cmake | 31 ++++++++++++---- docs/examples/chkspeed.c | 8 +++-- docs/examples/debug.c | 5 ++- docs/examples/http2-download.c | 5 ++- docs/examples/http2-serverpush.c | 5 ++- docs/examples/http2-upload.c | 5 ++- docs/examples/multi-debugcallback.c | 5 ++- include/curl/mprintf.h | 12 +++++-- lib/cf-h1-proxy.c | 8 ++--- lib/cf-h2-proxy.c | 6 ++-- lib/cf-haproxy.c | 4 +-- lib/cf-https-connect.c | 2 +- lib/cf-socket.c | 35 +++++++++--------- lib/cf-socket.h | 17 --------- lib/connect.c | 2 +- lib/cookie.c | 2 +- lib/curl_ntlm_wb.c | 2 +- lib/curl_setup.h | 56 +++++++++++++++++++++++++++++ lib/curl_trc.c | 21 +++++++++++ lib/curl_trc.h | 25 ++----------- lib/dict.c | 10 ++++++ lib/dynbuf.c | 7 ++++ lib/dynbuf.h | 4 +-- lib/easy.c | 14 +++++--- lib/formdata.c | 4 +-- lib/ftp.c | 4 +-- lib/http.c | 2 +- lib/imap.c | 8 ++++- lib/krb5.c | 1 - lib/ldap.c | 2 +- lib/memdebug.c | 47 +++++++++++++++++++++--- lib/memdebug.h | 2 +- lib/mime.c | 13 +++++-- lib/mime.h | 3 +- lib/mprintf.c | 5 +-- lib/mqtt.c | 4 +-- lib/multi.c | 1 + lib/noproxy.c | 1 - lib/openldap.c | 6 ++-- lib/pingpong.h | 4 +-- lib/smtp.c | 1 - lib/socks.c | 42 +++++++++++----------- lib/socks_sspi.c | 12 +++++-- lib/telnet.c | 2 +- lib/urlapi.c | 23 ++++++++---- lib/vauth/ntlm_sspi.c | 2 +- lib/vquic/vquic.c | 2 +- lib/vssh/libssh.c | 27 ++++++-------- lib/vssh/libssh2.c | 11 +++--- lib/vtls/openssl.c | 14 ++++---- lib/vtls/rustls.c | 12 +++---- lib/vtls/schannel.c | 15 +++++--- lib/vtls/schannel_verify.c | 4 +-- lib/vtls/wolfssl.c | 2 -- lib/vtls/x509asn1.c | 11 +++--- lib/ws.c | 4 +-- m4/curl-compilers.m4 | 16 ++++++--- packages/OS400/ccsidcurl.c | 2 +- src/tool_cb_dbg.c | 2 +- src/tool_cb_prg.c | 7 ++++ src/tool_easysrc.c | 7 ++++ src/tool_easysrc.h | 2 +- src/tool_formparse.c | 2 +- src/tool_getparam.c | 4 +-- src/tool_ipfs.c | 9 ++--- src/tool_msgs.c | 14 ++++++++ src/tool_msgs.h | 12 ++++--- src/tool_paramhlp.c | 2 +- src/tool_setopt.c | 9 ++++- src/tool_urlglob.c | 4 +-- tests/http/clients/h2-download.c | 5 ++- tests/http/clients/h2-serverpush.c | 5 ++- tests/libtest/lib1560.c | 7 ++++ tests/libtest/lib3026.c | 2 +- tests/libtest/lib517.c | 2 +- tests/libtest/lib518.c | 9 +++++ tests/libtest/lib537.c | 9 +++++ tests/libtest/lib552.c | 5 ++- tests/libtest/lib557.c | 2 +- tests/libtest/testtrace.c | 5 ++- tests/server/mqttd.c | 38 ++++++++++---------- tests/server/sockfilt.c | 10 +++--- tests/server/socksd.c | 45 +++++++++++------------ tests/server/sws.c | 17 ++++----- tests/server/tftpd.c | 2 +- tests/server/util.c | 6 ++-- tests/server/util.h | 2 +- tests/unit/unit1652.c | 4 ++- 88 files changed, 531 insertions(+), 318 deletions(-) diff --git a/CMake/PickyWarnings.cmake b/CMake/PickyWarnings.cmake index 5a0d1560424..056e56c91bb 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") @@ -86,8 +92,10 @@ if(PICKY_COMPILER) -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 # FIXME + # -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 +118,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 +144,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 +162,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 +172,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 +195,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 +208,6 @@ if(PICKY_COMPILER) # - unset(WPICKY) - foreach(_CCOPT IN LISTS WPICKY_ENABLE) set(WPICKY "${WPICKY} ${_CCOPT}") endforeach() @@ -209,8 +224,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/docs/examples/chkspeed.c b/docs/examples/chkspeed.c index 45765b988f6..a8d95666c99 100644 --- a/docs/examples/chkspeed.c +++ b/docs/examples/chkspeed.c @@ -126,15 +126,17 @@ int main(int argc, char *argv[]) default: fprintf(stderr, "\r%s: invalid parameter %s\n", appname, *argv + 3); - exit(1); + return 1; } break; } - /* FALLTHROUGH */ + fprintf(stderr, "\r%s: invalid or unknown option %s\n", + appname, *argv); + return 1; default: fprintf(stderr, "\r%s: invalid or unknown option %s\n", appname, *argv); - exit(1); + return 1; } } else { diff --git a/docs/examples/debug.c b/docs/examples/debug.c index 684a1832727..68d93039e2d 100644 --- a/docs/examples/debug.c +++ b/docs/examples/debug.c @@ -95,10 +95,7 @@ int my_trace(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "== Info: %s", data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -117,6 +114,8 @@ int my_trace(CURL *handle, curl_infotype type, case CURLINFO_SSL_DATA_IN: text = "<= Recv SSL data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } dump(text, stderr, (unsigned char *)data, size, config->trace_ascii); diff --git a/docs/examples/http2-download.c b/docs/examples/http2-download.c index a2291a8c7f1..4c6d46a3d52 100644 --- a/docs/examples/http2-download.c +++ b/docs/examples/http2-download.c @@ -115,10 +115,7 @@ int my_trace(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "== %u Info: %s", num, data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -137,6 +134,8 @@ int my_trace(CURL *handle, curl_infotype type, case CURLINFO_SSL_DATA_IN: text = "<= Recv SSL data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } dump(text, num, (unsigned char *)data, size, 1); diff --git a/docs/examples/http2-serverpush.c b/docs/examples/http2-serverpush.c index b5ebe2eb9aa..e830aa95d4c 100644 --- a/docs/examples/http2-serverpush.c +++ b/docs/examples/http2-serverpush.c @@ -100,10 +100,7 @@ int my_trace(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "== Info: %s", data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -122,6 +119,8 @@ int my_trace(CURL *handle, curl_infotype type, case CURLINFO_SSL_DATA_IN: text = "<= Recv SSL data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } dump(text, (unsigned char *)data, size, 1); diff --git a/docs/examples/http2-upload.c b/docs/examples/http2-upload.c index 5889d0c361b..dd63b8cd50f 100644 --- a/docs/examples/http2-upload.c +++ b/docs/examples/http2-upload.c @@ -133,10 +133,7 @@ int my_trace(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "%s [%d] Info: %s", timebuf, num, data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -155,6 +152,8 @@ int my_trace(CURL *handle, curl_infotype type, case CURLINFO_SSL_DATA_IN: text = "<= Recv SSL data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } dump(text, num, (unsigned char *)data, size, 1); diff --git a/docs/examples/multi-debugcallback.c b/docs/examples/multi-debugcallback.c index 8bdb58800fb..10842e9509f 100644 --- a/docs/examples/multi-debugcallback.c +++ b/docs/examples/multi-debugcallback.c @@ -100,10 +100,7 @@ int my_trace(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "== Info: %s", data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -116,6 +113,8 @@ int my_trace(CURL *handle, curl_infotype type, case CURLINFO_DATA_IN: text = "<= Recv data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } dump(text, stderr, data, size, TRUE); diff --git a/include/curl/mprintf.h b/include/curl/mprintf.h index dc5664bc539..30e5ffe50db 100644 --- a/include/curl/mprintf.h +++ b/include/curl/mprintf.h @@ -34,10 +34,16 @@ extern "C" { #if (defined(__GNUC__) || defined(__clang__)) && \ defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) && \ - !defined(__MINGW32__) && !defined(CURL_NO_FMT_CHECKS) -#define CURL_TEMP_PRINTF(a,b) __attribute__ ((format(printf, a, b))) + !defined(CURL_NO_FMT_CHECKS) +#if defined(__MINGW32__) && !defined(__clang__) +#define CURL_TEMP_PRINTF(fmt, arg) \ + __attribute__((format(gnu_printf, fmt, arg))) #else -#define CURL_TEMP_PRINTF(a,b) +#define CURL_TEMP_PRINTF(fmt, arg) \ + __attribute__((format(printf, fmt, arg))) +#endif +#else +#define CURL_TEMP_PRINTF(fmt, arg) #endif CURL_EXTERN int curl_mprintf(const char *format, ...) CURL_TEMP_PRINTF(1, 2); diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index 2e23b0b9f57..f603ccf3772 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -183,7 +183,7 @@ static void h1_tunnel_go_state(struct Curl_cfilter *cf, infof(data, "CONNECT phase completed"); data->state.authproxy.done = TRUE; data->state.authproxy.multipass = FALSE; - /* FALLTHROUGH */ + FALLTHROUGH(); case H1_TUNNEL_FAILED: if(new_state == H1_TUNNEL_FAILED) CURL_TRC_CF(data, cf, "new tunnel state 'failed'"); @@ -912,7 +912,7 @@ static CURLcode H1_CONNECT(struct Curl_cfilter *cf, if(result) goto out; h1_tunnel_go_state(cf, ts, H1_TUNNEL_CONNECT, data); - /* FALLTHROUGH */ + FALLTHROUGH(); case H1_TUNNEL_CONNECT: /* see that the request is completely sent */ @@ -921,7 +921,7 @@ static CURLcode H1_CONNECT(struct Curl_cfilter *cf, if(result || !done) goto out; h1_tunnel_go_state(cf, ts, H1_TUNNEL_RECEIVE, data); - /* FALLTHROUGH */ + FALLTHROUGH(); case H1_TUNNEL_RECEIVE: /* read what is there */ @@ -936,7 +936,7 @@ static CURLcode H1_CONNECT(struct Curl_cfilter *cf, goto out; /* got it */ h1_tunnel_go_state(cf, ts, H1_TUNNEL_RESPONSE, data); - /* FALLTHROUGH */ + FALLTHROUGH(); case H1_TUNNEL_RESPONSE: CURL_TRC_CF(data, cf, "CONNECT response"); diff --git a/lib/cf-h2-proxy.c b/lib/cf-h2-proxy.c index 78902386ecd..f8f2f3c417d 100644 --- a/lib/cf-h2-proxy.c +++ b/lib/cf-h2-proxy.c @@ -155,7 +155,7 @@ static void h2_tunnel_go_state(struct Curl_cfilter *cf, infof(data, "CONNECT phase completed"); data->state.authproxy.done = TRUE; data->state.authproxy.multipass = FALSE; - /* FALLTHROUGH */ + FALLTHROUGH(); case H2_TUNNEL_FAILED: if(new_state == H2_TUNNEL_FAILED) CURL_TRC_CF(data, cf, "[%d] new tunnel state 'failed'", ts->stream_id); @@ -1033,7 +1033,7 @@ static CURLcode H2_CONNECT(struct Curl_cfilter *cf, if(result) goto out; h2_tunnel_go_state(cf, ts, H2_TUNNEL_CONNECT, data); - /* FALLTHROUGH */ + FALLTHROUGH(); case H2_TUNNEL_CONNECT: /* see that the request is completely sent */ @@ -1052,7 +1052,7 @@ static CURLcode H2_CONNECT(struct Curl_cfilter *cf, result = CURLE_OK; goto out; } - /* FALLTHROUGH */ + FALLTHROUGH(); case H2_TUNNEL_RESPONSE: DEBUGASSERT(ts->has_final_response); diff --git a/lib/cf-haproxy.c b/lib/cf-haproxy.c index 1ca43937bfa..c062887bf39 100644 --- a/lib/cf-haproxy.c +++ b/lib/cf-haproxy.c @@ -125,7 +125,7 @@ static CURLcode cf_haproxy_connect(struct Curl_cfilter *cf, if(result) goto out; ctx->state = HAPROXY_SEND; - /* FALLTHROUGH */ + FALLTHROUGH(); case HAPROXY_SEND: len = Curl_dyn_len(&ctx->data_out); if(len > 0) { @@ -141,7 +141,7 @@ static CURLcode cf_haproxy_connect(struct Curl_cfilter *cf, } } ctx->state = HAPROXY_DONE; - /* FALLTHROUGH */ + FALLTHROUGH(); default: Curl_dyn_free(&ctx->data_out); break; diff --git a/lib/cf-https-connect.c b/lib/cf-https-connect.c index b4f33c8e02b..b23fa056f8f 100644 --- a/lib/cf-https-connect.c +++ b/lib/cf-https-connect.c @@ -266,7 +266,7 @@ static CURLcode cf_hc_connect(struct Curl_cfilter *cf, cf_hc_baller_init(&ctx->h21_baller, cf, data, "h21", cf->conn->transport); ctx->state = CF_HC_CONNECT; - /* FALLTHROUGH */ + FALLTHROUGH(); case CF_HC_CONNECT: if(cf_hc_baller_is_active(&ctx->h3_baller)) { diff --git a/lib/cf-socket.c b/lib/cf-socket.c index e42b4a87b19..e868b6bbfab 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -163,7 +163,8 @@ tcpkeepalive(struct Curl_easy *data, /* only set IDLE and INTVL if setting KEEPALIVE is successful */ if(setsockopt(sockfd, SOL_SOCKET, SO_KEEPALIVE, (void *)&optval, sizeof(optval)) < 0) { - infof(data, "Failed to set SO_KEEPALIVE on fd %d", sockfd); + infof(data, "Failed to set SO_KEEPALIVE on fd %" CURL_FORMAT_SOCKET_T, + sockfd); } else { #if defined(SIO_KEEPALIVE_VALS) @@ -178,8 +179,9 @@ tcpkeepalive(struct Curl_easy *data, vals.keepaliveinterval = optval; if(WSAIoctl(sockfd, SIO_KEEPALIVE_VALS, (LPVOID) &vals, sizeof(vals), NULL, 0, &dummy, NULL, NULL) != 0) { - infof(data, "Failed to set SIO_KEEPALIVE_VALS on fd %d: %d", - (int)sockfd, WSAGetLastError()); + infof(data, "Failed to set SIO_KEEPALIVE_VALS on fd " + "%" CURL_FORMAT_SOCKET_T ": %d", + sockfd, WSAGetLastError()); } #else #ifdef TCP_KEEPIDLE @@ -187,7 +189,8 @@ tcpkeepalive(struct Curl_easy *data, KEEPALIVE_FACTOR(optval); if(setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPIDLE, (void *)&optval, sizeof(optval)) < 0) { - infof(data, "Failed to set TCP_KEEPIDLE on fd %d", sockfd); + infof(data, "Failed to set TCP_KEEPIDLE on fd %" CURL_FORMAT_SOCKET_T, + sockfd); } #elif defined(TCP_KEEPALIVE) /* Mac OS X style */ @@ -195,7 +198,8 @@ tcpkeepalive(struct Curl_easy *data, KEEPALIVE_FACTOR(optval); if(setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPALIVE, (void *)&optval, sizeof(optval)) < 0) { - infof(data, "Failed to set TCP_KEEPALIVE on fd %d", sockfd); + infof(data, "Failed to set TCP_KEEPALIVE on fd %" CURL_FORMAT_SOCKET_T, + sockfd); } #endif #ifdef TCP_KEEPINTVL @@ -203,7 +207,8 @@ tcpkeepalive(struct Curl_easy *data, KEEPALIVE_FACTOR(optval); if(setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPINTVL, (void *)&optval, sizeof(optval)) < 0) { - infof(data, "Failed to set TCP_KEEPINTVL on fd %d", sockfd); + infof(data, "Failed to set TCP_KEEPINTVL on fd %" CURL_FORMAT_SOCKET_T, + sockfd); } #endif #endif @@ -983,20 +988,14 @@ static CURLcode cf_socket_open(struct Curl_cfilter *cf, if(result) goto out; -#ifndef CURL_DISABLE_VERBOSE_STRINGS - { - const char *ipmsg; #ifdef ENABLE_IPV6 - if(ctx->addr.family == AF_INET6) { - set_ipv6_v6only(ctx->sock, 0); - ipmsg = " Trying [%s]:%d..."; - } - else -#endif - ipmsg = " Trying %s:%d..."; - infof(data, ipmsg, ctx->r_ip, ctx->r_port); + if(ctx->addr.family == AF_INET6) { + set_ipv6_v6only(ctx->sock, 0); + infof(data, " Trying [%s]:%d...", ctx->r_ip, ctx->r_port); } + else #endif + infof(data, " Trying %s:%d...", ctx->r_ip, ctx->r_port); #ifdef ENABLE_IPV6 is_tcp = (ctx->addr.family == AF_INET @@ -1574,7 +1573,7 @@ static CURLcode cf_socket_query(struct Curl_cfilter *cf, *when = ctx->first_byte_at; break; } - /* FALLTHROUGH */ + FALLTHROUGH(); default: *when = ctx->connected_at; break; diff --git a/lib/cf-socket.h b/lib/cf-socket.h index 1d40df737fc..87e0f30a251 100644 --- a/lib/cf-socket.h +++ b/lib/cf-socket.h @@ -34,23 +34,6 @@ struct Curl_easy; struct connectdata; struct Curl_sockaddr_ex; -#ifndef SIZEOF_CURL_SOCKET_T -/* configure and cmake check and set the define */ -# ifdef _WIN64 -# define SIZEOF_CURL_SOCKET_T 8 -# else -/* default guess */ -# define SIZEOF_CURL_SOCKET_T 4 -# endif -#endif - -#if SIZEOF_CURL_SOCKET_T < 8 -# define CURL_FORMAT_SOCKET_T "d" -#else -# define CURL_FORMAT_SOCKET_T "qd" -#endif - - /* * The Curl_sockaddr_ex structure is basically libcurl's external API * curl_sockaddr structure with enough space available to directly hold any diff --git a/lib/connect.c b/lib/connect.c index 54cd27cbd86..4cb6eda115c 100644 --- a/lib/connect.c +++ b/lib/connect.c @@ -892,7 +892,7 @@ static CURLcode cf_he_connect(struct Curl_cfilter *cf, if(result) return result; ctx->state = SCFST_WAITING; - /* FALLTHROUGH */ + FALLTHROUGH(); case SCFST_WAITING: result = is_connected(cf, data, done); if(!result && *done) { diff --git a/lib/cookie.c b/lib/cookie.c index 5f158395b6f..dc319b61111 100644 --- a/lib/cookie.c +++ b/lib/cookie.c @@ -925,7 +925,7 @@ Curl_cookie_add(struct Curl_easy *data, if(!co->spath) badcookie = TRUE; fields++; /* add a field and fall down to secure */ - /* FALLTHROUGH */ + FALLTHROUGH(); case 3: co->secure = FALSE; if(strcasecompare(ptr, "TRUE")) { diff --git a/lib/curl_ntlm_wb.c b/lib/curl_ntlm_wb.c index b087a37a3d3..426e845746d 100644 --- a/lib/curl_ntlm_wb.c +++ b/lib/curl_ntlm_wb.c @@ -481,7 +481,7 @@ CURLcode Curl_output_ntlm_wb(struct Curl_easy *data, struct connectdata *conn, /* connection is already authenticated, * don't send a header in future requests */ *state = NTLMSTATE_LAST; - /* FALLTHROUGH */ + FALLTHROUGH(); case NTLMSTATE_LAST: Curl_safefree(*allocuserpwd); authp->done = TRUE; diff --git a/lib/curl_setup.h b/lib/curl_setup.h index a08784140d9..f81cf610023 100644 --- a/lib/curl_setup.h +++ b/lib/curl_setup.h @@ -259,6 +259,33 @@ #include +/* curl uses its own printf() function internally. It understands the GNU + * format. Use this format, so that is matches the GNU format attribute we + * use with the mingw compiler, allowing it to verify them at compile-time. + */ +#ifdef __MINGW32__ +# undef CURL_FORMAT_CURL_OFF_T +# undef CURL_FORMAT_CURL_OFF_TU +# define CURL_FORMAT_CURL_OFF_T "lld" +# define CURL_FORMAT_CURL_OFF_TU "llu" +#endif + +/* based on logic in "curl/mprintf.h" */ + +#if (defined(__GNUC__) || defined(__clang__)) && \ + defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) && \ + !defined(CURL_NO_FMT_CHECKS) +#if defined(__MINGW32__) && !defined(__clang__) +#define CURL_PRINTF(fmt, arg) \ + __attribute__((format(gnu_printf, fmt, arg))) +#else +#define CURL_PRINTF(fmt, arg) \ + __attribute__((format(__printf__, fmt, arg))) +#endif +#else +#define CURL_PRINTF(fmt, arg) +#endif + /* * Use getaddrinfo to resolve the IPv4 address literal. If the current network * interface doesn't support IPv4, but supports IPv6, NAT64, and DNS64, @@ -408,6 +435,24 @@ #define SIZEOF_TIME_T 4 #endif +#ifndef SIZEOF_CURL_SOCKET_T +/* configure and cmake check and set the define */ +# ifdef _WIN64 +# define SIZEOF_CURL_SOCKET_T 8 +# else +/* default guess */ +# define SIZEOF_CURL_SOCKET_T 4 +# endif +#endif + +#if SIZEOF_CURL_SOCKET_T < 8 +# define CURL_FORMAT_SOCKET_T "d" +#elif defined(__MINGW32__) +# define CURL_FORMAT_SOCKET_T "zd" +#else +# define CURL_FORMAT_SOCKET_T "qd" +#endif + /* * Default sizeof(off_t) in case it hasn't been defined in config file. */ @@ -648,6 +693,17 @@ #endif #endif +/* fallthrough attribute */ + +#if !defined(FALLTHROUGH) +#if (defined(__GNUC__) && __GNUC__ >= 7) || \ + (defined(__clang__) && __clang_major__ >= 10) +# define FALLTHROUGH() __attribute__((fallthrough)) +#else +# define FALLTHROUGH() do {} while (0) +#endif +#endif + /* * Include macros and defines that should only be processed once. */ diff --git a/lib/curl_trc.c b/lib/curl_trc.c index b8dccc41937..1c49d553568 100644 --- a/lib/curl_trc.c +++ b/lib/curl_trc.c @@ -92,7 +92,14 @@ void Curl_failf(struct Curl_easy *data, const char *fmt, ...) int len; char error[CURL_ERROR_SIZE + 2]; va_start(ap, fmt); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif len = mvsnprintf(error, CURL_ERROR_SIZE, fmt, ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif if(data->set.errorbuffer && !data->state.errorbuf) { strcpy(data->set.errorbuffer, error); @@ -118,7 +125,14 @@ void Curl_infof(struct Curl_easy *data, const char *fmt, ...) int len; char buffer[MAXINFO + 2]; va_start(ap, fmt); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif len = mvsnprintf(buffer, MAXINFO, fmt, ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif va_end(ap); buffer[len++] = '\n'; buffer[len] = '\0'; @@ -136,7 +150,14 @@ void Curl_trc_cf_infof(struct Curl_easy *data, struct Curl_cfilter *cf, char buffer[MAXINFO + 2]; len = msnprintf(buffer, MAXINFO, "[%s] ", cf->cft->name); va_start(ap, fmt); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif len += mvsnprintf(buffer + len, MAXINFO - len, fmt, ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif va_end(ap); buffer[len++] = '\n'; buffer[len] = '\0'; diff --git a/lib/curl_trc.h b/lib/curl_trc.h index ade9108ac7d..3a5387a27a5 100644 --- a/lib/curl_trc.h +++ b/lib/curl_trc.h @@ -58,14 +58,7 @@ void Curl_debug(struct Curl_easy *data, curl_infotype type, * Output a failure message on registered callbacks for transfer. */ void Curl_failf(struct Curl_easy *data, -#if defined(__GNUC__) && !defined(printf) && \ - defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) && \ - !defined(__MINGW32__) - const char *fmt, ...) - __attribute__((format(printf, 2, 3))); -#else - const char *fmt, ...); -#endif + const char *fmt, ...) CURL_PRINTF(2, 3); #define failf Curl_failf @@ -102,26 +95,14 @@ void Curl_failf(struct Curl_easy *data, * Output an informational message when transfer's verbose logging is enabled. */ void Curl_infof(struct Curl_easy *data, -#if defined(__GNUC__) && !defined(printf) && defined(CURL_HAVE_C99) && \ - !defined(__MINGW32__) - const char *fmt, ...) - __attribute__((format(printf, 2, 3))); -#else - const char *fmt, ...); -#endif + const char *fmt, ...) CURL_PRINTF(2, 3); /** * Output an informational message when both transfer's verbose logging * and connection filters verbose logging are enabled. */ void Curl_trc_cf_infof(struct Curl_easy *data, struct Curl_cfilter *cf, -#if defined(__GNUC__) && !defined(printf) && defined(CURL_HAVE_C99) && \ - !defined(__MINGW32__) - const char *fmt, ...) - __attribute__((format(printf, 3, 4))); -#else - const char *fmt, ...); -#endif + const char *fmt, ...) CURL_PRINTF(3, 4); #else /* defined(CURL_DISABLE_VERBOSE_STRINGS) */ /* All informational messages are not compiled in for size savings */ diff --git a/lib/dict.c b/lib/dict.c index 3172b382909..5c9ce146120 100644 --- a/lib/dict.c +++ b/lib/dict.c @@ -122,6 +122,9 @@ static char *unescape_word(const char *input) } /* sendf() sends formatted data to the server */ +static CURLcode sendf(curl_socket_t sockfd, struct Curl_easy *data, + const char *fmt, ...) CURL_PRINTF(3, 4); + static CURLcode sendf(curl_socket_t sockfd, struct Curl_easy *data, const char *fmt, ...) { @@ -132,7 +135,14 @@ static CURLcode sendf(curl_socket_t sockfd, struct Curl_easy *data, char *sptr; va_list ap; va_start(ap, fmt); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif s = vaprintf(fmt, ap); /* returns an allocated string */ +#ifdef __clang__ +#pragma clang diagnostic pop +#endif va_end(ap); if(!s) return CURLE_OUT_OF_MEMORY; /* failure */ diff --git a/lib/dynbuf.c b/lib/dynbuf.c index 2973d8da29c..a20266a681b 100644 --- a/lib/dynbuf.c +++ b/lib/dynbuf.c @@ -201,7 +201,14 @@ CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap) return CURLE_OK; #else char *str; +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif str = vaprintf(fmt, ap); /* this allocs a new string to append */ +#ifdef __clang__ +#pragma clang diagnostic pop +#endif if(str) { CURLcode result = dyn_nappend(s, (unsigned char *)str, strlen(str)); diff --git a/lib/dynbuf.h b/lib/dynbuf.h index 31a91301979..7dbaab886e2 100644 --- a/lib/dynbuf.h +++ b/lib/dynbuf.h @@ -61,9 +61,9 @@ CURLcode Curl_dyn_addn(struct dynbuf *s, const void *mem, size_t len) CURLcode Curl_dyn_add(struct dynbuf *s, const char *str) WARN_UNUSED_RESULT; CURLcode Curl_dyn_addf(struct dynbuf *s, const char *fmt, ...) - WARN_UNUSED_RESULT; + WARN_UNUSED_RESULT CURL_PRINTF(2, 3); CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap) - WARN_UNUSED_RESULT; + WARN_UNUSED_RESULT CURL_PRINTF(2, 0); void Curl_dyn_reset(struct dynbuf *s); CURLcode Curl_dyn_tail(struct dynbuf *s, size_t trail); CURLcode Curl_dyn_setlen(struct dynbuf *s, size_t set); diff --git a/lib/easy.c b/lib/easy.c index b4ad61f2e04..085f368c9be 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -480,13 +480,15 @@ static int events_socket(struct Curl_easy *easy, /* easy handle */ ev->list = nxt; free(m); m = nxt; - infof(easy, "socket cb: socket %d REMOVED", s); + infof(easy, "socket cb: socket %" CURL_FORMAT_SOCKET_T + " REMOVED", s); } else { /* The socket 's' is already being monitored, update the activity mask. Convert from libcurl bitmask to the poll one. */ m->socket.events = socketcb2poll(what); - infof(easy, "socket cb: socket %d UPDATED as %s%s", s, + infof(easy, "socket cb: socket %" CURL_FORMAT_SOCKET_T + " UPDATED as %s%s", s, (what&CURL_POLL_IN)?"IN":"", (what&CURL_POLL_OUT)?"OUT":""); } @@ -510,7 +512,8 @@ static int events_socket(struct Curl_easy *easy, /* easy handle */ m->socket.events = socketcb2poll(what); m->socket.revents = 0; ev->list = m; - infof(easy, "socket cb: socket %d ADDED as %s%s", s, + infof(easy, "socket cb: socket %" CURL_FORMAT_SOCKET_T + " ADDED as %s%s", s, (what&CURL_POLL_IN)?"IN":"", (what&CURL_POLL_OUT)?"OUT":""); } @@ -599,8 +602,9 @@ static CURLcode wait_or_timeout(struct Curl_multi *multi, struct events *ev) if(fds[i].revents) { /* socket activity, tell libcurl */ int act = poll2cselect(fds[i].revents); /* convert */ - infof(multi->easyp, "call curl_multi_socket_action(socket %d)", - fds[i].fd); + infof(multi->easyp, + "call curl_multi_socket_action(socket " + "%" CURL_FORMAT_SOCKET_T ")", fds[i].fd); mcode = curl_multi_socket_action(multi, fds[i].fd, act, &ev->running_handles); } diff --git a/lib/formdata.c b/lib/formdata.c index 8896b75e20d..d6a1697aa73 100644 --- a/lib/formdata.c +++ b/lib/formdata.c @@ -277,7 +277,7 @@ CURLFORMcode FormAdd(struct curl_httppost **httppost, case CURLFORM_PTRNAME: current_form->flags |= HTTPPOST_PTRNAME; /* fall through */ - /* FALLTHROUGH */ + FALLTHROUGH(); case CURLFORM_COPYNAME: if(current_form->name) return_value = CURL_FORMADD_OPTION_TWICE; @@ -303,7 +303,7 @@ CURLFORMcode FormAdd(struct curl_httppost **httppost, */ case CURLFORM_PTRCONTENTS: current_form->flags |= HTTPPOST_PTRCONTENTS; - /* FALLTHROUGH */ + FALLTHROUGH(); case CURLFORM_COPYCONTENTS: if(current_form->value) return_value = CURL_FORMADD_OPTION_TWICE; diff --git a/lib/ftp.c b/lib/ftp.c index 87666dbcb23..ee3b403d3cd 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -3124,7 +3124,6 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, break; case FTP_QUIT: - /* fallthrough, just stop! */ default: /* internal error */ ftp_state(data, FTP_STOP); @@ -3251,14 +3250,13 @@ static CURLcode ftp_done(struct Curl_easy *data, CURLcode status, case CURLE_REMOTE_FILE_NOT_FOUND: case CURLE_WRITE_ERROR: /* the connection stays alive fine even though this happened */ - /* fall-through */ case CURLE_OK: /* doesn't affect the control connection's status */ if(!premature) break; /* until we cope better with prematurely ended requests, let them * fallback as if in complete failure */ - /* FALLTHROUGH */ + FALLTHROUGH(); default: /* by default, an error means the control connection is wedged and should not be used anymore */ ftpc->ctl_valid = FALSE; diff --git a/lib/http.c b/lib/http.c index ba625b4def5..582cb1cdbcf 100644 --- a/lib/http.c +++ b/lib/http.c @@ -3888,7 +3888,7 @@ CURLcode Curl_http_statusline(struct Curl_easy *data, * fields. */ if(data->set.timecondition) data->info.timecond = TRUE; - /* FALLTHROUGH */ + FALLTHROUGH(); case 204: /* (quote from RFC2616, section 10.2.5): The server has * fulfilled the request but does not need to return an diff --git a/lib/imap.c b/lib/imap.c index 1be89eccbd1..72ce5330686 100644 --- a/lib/imap.c +++ b/lib/imap.c @@ -1376,7 +1376,6 @@ static CURLcode imap_statemachine(struct Curl_easy *data, break; case IMAP_LOGOUT: - /* fallthrough, just stop! */ default: /* internal error */ imap_state(data, IMAP_STOP); @@ -1795,7 +1794,14 @@ static CURLcode imap_sendf(struct Curl_easy *data, const char *fmt, ...) if(!result) { va_list ap; va_start(ap, fmt); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif result = Curl_pp_vsendf(data, &imapc->pp, Curl_dyn_ptr(&imapc->dyn), ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif va_end(ap); } return result; diff --git a/lib/krb5.c b/lib/krb5.c index 18e73debbfe..91f8a1077f7 100644 --- a/lib/krb5.c +++ b/lib/krb5.c @@ -417,7 +417,6 @@ static char level_to_char(int level) case PROT_PRIVATE: return 'P'; case PROT_CMD: - /* Fall through */ default: /* Those 2 cases should not be reached! */ break; diff --git a/lib/ldap.c b/lib/ldap.c index eb5fe795e88..99ac317159e 100644 --- a/lib/ldap.c +++ b/lib/ldap.c @@ -137,7 +137,7 @@ static void _ldap_free_urldesc(LDAPURLDesc *ludp); _ldap_trace x; \ } while(0) - static void _ldap_trace(const char *fmt, ...); + static void _ldap_trace(const char *fmt, ...) CURL_PRINTF(1, 2); #else #define LDAP_TRACE(x) Curl_nop_stmt #endif diff --git a/lib/memdebug.c b/lib/memdebug.c index f6ced85cd94..fb2b5584607 100644 --- a/lib/memdebug.c +++ b/lib/memdebug.c @@ -317,8 +317,16 @@ curl_socket_t curl_dbg_socket(int domain, int type, int protocol, sockfd = socket(domain, type, protocol); - if(source && (sockfd != CURL_SOCKET_BAD)) + if(source && (sockfd != CURL_SOCKET_BAD)) { +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif curl_dbg_log(fmt, source, line, sockfd); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif + } return sockfd; } @@ -365,8 +373,16 @@ int curl_dbg_socketpair(int domain, int type, int protocol, int res = socketpair(domain, type, protocol, socket_vector); - if(source && (0 == res)) + if(source && (0 == res)) { +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif curl_dbg_log(fmt, source, line, socket_vector[0], socket_vector[1]); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif + } return res; } @@ -386,8 +402,16 @@ curl_socket_t curl_dbg_accept(curl_socket_t s, void *saddr, void *saddrlen, curl_socket_t sockfd = accept(s, addr, addrlen); - if(source && (sockfd != CURL_SOCKET_BAD)) + if(source && (sockfd != CURL_SOCKET_BAD)) { +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif curl_dbg_log(fmt, source, line, sockfd); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif + } return sockfd; } @@ -401,8 +425,16 @@ void curl_dbg_mark_sclose(curl_socket_t sockfd, int line, const char *source) "FD %s:%d sclose(%ld)\n": "FD %s:%d sclose(%zd)\n"; - if(source) + if(source) { +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif curl_dbg_log(fmt, source, line, sockfd); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif + } } /* this is our own defined way to close sockets on *ALL* platforms */ @@ -467,7 +499,14 @@ void curl_dbg_log(const char *format, ...) return; va_start(ap, format); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif nchars = mvsnprintf(buf, LOGLINE_BUFSIZE, format, ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif va_end(ap); if(nchars > LOGLINE_BUFSIZE - 1) diff --git a/lib/memdebug.h b/lib/memdebug.h index 78a012580cf..51147cdcba5 100644 --- a/lib/memdebug.h +++ b/lib/memdebug.h @@ -72,7 +72,7 @@ CURL_EXTERN ALLOC_FUNC wchar_t *curl_dbg_wcsdup(const wchar_t *str, CURL_EXTERN void curl_dbg_memdebug(const char *logname); CURL_EXTERN void curl_dbg_memlimit(long limit); -CURL_EXTERN void curl_dbg_log(const char *format, ...); +CURL_EXTERN void curl_dbg_log(const char *format, ...) CURL_PRINTF(1, 2); /* file descriptor manipulators */ CURL_EXTERN curl_socket_t curl_dbg_socket(int domain, int type, int protocol, diff --git a/lib/mime.c b/lib/mime.c index bb66130ad71..0966a0b5a17 100644 --- a/lib/mime.c +++ b/lib/mime.c @@ -817,7 +817,7 @@ static size_t read_part_content(curl_mimepart *part, case MIMEKIND_FILE: if(part->fp && feof(part->fp)) break; /* At EOF. */ - /* FALLTHROUGH */ + FALLTHROUGH(); default: if(part->readfunc) { if(!(part->flags & MIME_FAST_READ)) { @@ -936,7 +936,7 @@ static size_t readback_part(curl_mimepart *part, mimesetstate(&part->state, MIMESTATE_USERHEADERS, hdr->next); break; } - /* FALLTHROUGH */ + FALLTHROUGH(); case MIMESTATE_CURLHEADERS: if(!hdr) mimesetstate(&part->state, MIMESTATE_USERHEADERS, part->userheaders); @@ -970,7 +970,7 @@ static size_t readback_part(curl_mimepart *part, fclose(part->fp); part->fp = NULL; } - /* FALLTHROUGH */ + FALLTHROUGH(); case CURL_READFUNC_ABORT: case CURL_READFUNC_PAUSE: case READ_ERROR: @@ -1680,7 +1680,14 @@ CURLcode Curl_mime_add_header(struct curl_slist **slp, const char *fmt, ...) va_list ap; va_start(ap, fmt); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif s = curl_mvaprintf(fmt, ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif va_end(ap); if(s) { diff --git a/lib/mime.h b/lib/mime.h index 0a05c2a5aa8..a64f41d4b52 100644 --- a/lib/mime.h +++ b/lib/mime.h @@ -130,7 +130,8 @@ struct curl_mimepart { size_t lastreadstatus; /* Last read callback returned status. */ }; -CURLcode Curl_mime_add_header(struct curl_slist **slp, const char *fmt, ...); +CURLcode Curl_mime_add_header(struct curl_slist **slp, const char *fmt, ...) + CURL_PRINTF(2, 3); #if !defined(CURL_DISABLE_MIME) && (!defined(CURL_DISABLE_HTTP) || \ !defined(CURL_DISABLE_SMTP) || \ diff --git a/lib/mprintf.c b/lib/mprintf.c index 6b5df5bdde3..60cf531486a 100644 --- a/lib/mprintf.c +++ b/lib/mprintf.c @@ -365,7 +365,7 @@ static int dprintf_Pass1(const char *format, struct va_stack *vto, case '0': if(!(flags & FLAGS_LEFT)) flags |= FLAGS_PAD_NIL; - /* FALLTHROUGH */ + FALLTHROUGH(); case '1': case '2': case '3': case '4': case '5': case '6': case '7': case '8': case '9': flags |= FLAGS_WIDTH; @@ -385,6 +385,7 @@ static int dprintf_Pass1(const char *format, struct va_stack *vto, break; case '\0': fmt--; + FALLTHROUGH(); default: break; } @@ -401,7 +402,7 @@ static int dprintf_Pass1(const char *format, struct va_stack *vto, switch(*fmt) { case 'S': flags |= FLAGS_ALT; - /* FALLTHROUGH */ + FALLTHROUGH(); case 's': vto[i].type = FORMAT_STRING; break; diff --git a/lib/mqtt.c b/lib/mqtt.c index 366235c559c..b304bd62974 100644 --- a/lib/mqtt.c +++ b/lib/mqtt.c @@ -671,7 +671,7 @@ static CURLcode mqtt_read_publish(struct Curl_easy *data, bool *done) data->req.bytecount = 0; data->req.size = remlen; mq->npacket = remlen; /* get this many bytes */ - /* FALLTHROUGH */ + FALLTHROUGH(); case MQTT_PUB_REMAIN: { /* read rest of packet, but no more. Cap to buffer size */ size_t rest = mq->npacket; @@ -776,7 +776,7 @@ static CURLcode mqtt_doing(struct Curl_easy *data, bool *done) /* remember the first byte */ mq->npacket = 0; mqstate(data, MQTT_REMAINING_LENGTH, MQTT_NOSTATE); - /* FALLTHROUGH */ + FALLTHROUGH(); case MQTT_REMAINING_LENGTH: do { result = Curl_read(data, sockfd, (char *)&byte, 1, &nread); diff --git a/lib/multi.c b/lib/multi.c index d064102150b..89a02680a55 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -672,6 +672,7 @@ static CURLcode multi_done(struct Curl_easy *data, many callbacks and protocols work differently, we could potentially do this more fine-grained in the future. */ premature = TRUE; + FALLTHROUGH(); default: break; } diff --git a/lib/noproxy.c b/lib/noproxy.c index 2b9908d8941..5241640a363 100644 --- a/lib/noproxy.c +++ b/lib/noproxy.c @@ -216,7 +216,6 @@ bool Curl_check_noproxy(const char *name, const char *no_proxy, /* case C passes through, not a match */ break; case TYPE_IPV4: - /* FALLTHROUGH */ case TYPE_IPV6: { const char *check = token; char *slash; diff --git a/lib/openldap.c b/lib/openldap.c index 131f4741428..c9417fbe2a1 100644 --- a/lib/openldap.c +++ b/lib/openldap.c @@ -645,7 +645,7 @@ static CURLcode oldap_state_mechs_resp(struct Curl_easy *data, switch(code) { case LDAP_SIZELIMIT_EXCEEDED: infof(data, "Too many authentication mechanisms\n"); - /* FALLTHROUGH */ + FALLTHROUGH(); case LDAP_SUCCESS: case LDAP_NO_RESULTS_RETURNED: if(Curl_sasl_can_authenticate(&li->sasl, data)) @@ -793,7 +793,7 @@ static CURLcode oldap_connecting(struct Curl_easy *data, bool *done) result = oldap_perform_bind(data, OLDAP_BIND); break; } - /* FALLTHROUGH */ + FALLTHROUGH(); case OLDAP_TLS: result = oldap_ssl_connect(data, OLDAP_TLS); if(result && data->set.use_ssl != CURLUSESSL_TRY) @@ -1014,7 +1014,7 @@ static ssize_t oldap_recv(struct Curl_easy *data, int sockindex, char *buf, switch(code) { case LDAP_SIZELIMIT_EXCEEDED: infof(data, "There are more than %d entries", lr->nument); - /* FALLTHROUGH */ + FALLTHROUGH(); case LDAP_SUCCESS: data->req.size = data->req.bytecount; break; diff --git a/lib/pingpong.h b/lib/pingpong.h index 80d3f7718c7..24061d86aba 100644 --- a/lib/pingpong.h +++ b/lib/pingpong.h @@ -113,7 +113,7 @@ timediff_t Curl_pp_state_timeout(struct Curl_easy *data, */ CURLcode Curl_pp_sendf(struct Curl_easy *data, struct pingpong *pp, - const char *fmt, ...); + const char *fmt, ...) CURL_PRINTF(3, 4); /*********************************************************************** * @@ -128,7 +128,7 @@ CURLcode Curl_pp_sendf(struct Curl_easy *data, CURLcode Curl_pp_vsendf(struct Curl_easy *data, struct pingpong *pp, const char *fmt, - va_list args); + va_list args) CURL_PRINTF(3, 0); /* * Curl_pp_readresp() diff --git a/lib/smtp.c b/lib/smtp.c index 65fbc5b6c5a..8eddf8a9895 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -1268,7 +1268,6 @@ static CURLcode smtp_statemachine(struct Curl_easy *data, break; case SMTP_QUIT: - /* fallthrough, just stop! */ default: /* internal error */ smtp_state(data, SMTP_STOP); diff --git a/lib/socks.c b/lib/socks.c index 437c2a4ef3d..0031e0e42f4 100644 --- a/lib/socks.c +++ b/lib/socks.c @@ -353,9 +353,10 @@ static CURLproxycode do_SOCKS4(struct Curl_cfilter *cf, return CURLPX_OK; } } - /* FALLTHROUGH */ + FALLTHROUGH(); + case CONNECT_RESOLVED: CONNECT_RESOLVED: - case CONNECT_RESOLVED: { + { struct Curl_addrinfo *hp = NULL; /* * We cannot use 'hostent' as a struct that Curl_resolv() returns. It @@ -393,9 +394,9 @@ static CURLproxycode do_SOCKS4(struct Curl_cfilter *cf, if(!hp) return CURLPX_RESOLVE_HOST; } - /* FALLTHROUGH */ -CONNECT_REQ_INIT: + FALLTHROUGH(); case CONNECT_REQ_INIT: +CONNECT_REQ_INIT: /* * This is currently not supporting "Identification Protocol (RFC1413)". */ @@ -442,7 +443,7 @@ static CURLproxycode do_SOCKS4(struct Curl_cfilter *cf, sx->outstanding = packetsize; sxstate(sx, data, CONNECT_REQ_SENDING); } - /* FALLTHROUGH */ + FALLTHROUGH(); case CONNECT_REQ_SENDING: /* Send request */ presult = socks_state_send(cf, sx, data, CURLPX_SEND_CONNECT, @@ -458,7 +459,7 @@ static CURLproxycode do_SOCKS4(struct Curl_cfilter *cf, sx->outp = socksreq; sxstate(sx, data, CONNECT_SOCKS_READ); - /* FALLTHROUGH */ + FALLTHROUGH(); case CONNECT_SOCKS_READ: /* Receive response */ presult = socks_state_recv(cf, sx, data, CURLPX_RECV_CONNECT, @@ -640,12 +641,12 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, /* remain in sending state */ return CURLPX_OK; } - /* FALLTHROUGH */ -CONNECT_SOCKS_READ_INIT: + FALLTHROUGH(); case CONNECT_SOCKS_READ_INIT: +CONNECT_SOCKS_READ_INIT: sx->outstanding = 2; /* expect two bytes */ sx->outp = socksreq; /* store it here */ - /* FALLTHROUGH */ + FALLTHROUGH(); case CONNECT_SOCKS_READ: presult = socks_state_recv(cf, sx, data, CURLPX_RECV_CONNECT, "initial SOCKS5 response"); @@ -749,7 +750,7 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, sx->outstanding = len; sx->outp = socksreq; } - /* FALLTHROUGH */ + FALLTHROUGH(); case CONNECT_AUTH_SEND: presult = socks_state_send(cf, sx, data, CURLPX_SEND_AUTH, "SOCKS5 sub-negotiation request"); @@ -762,7 +763,7 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, sx->outp = socksreq; sx->outstanding = 2; sxstate(sx, data, CONNECT_AUTH_READ); - /* FALLTHROUGH */ + FALLTHROUGH(); case CONNECT_AUTH_READ: presult = socks_state_recv(cf, sx, data, CURLPX_RECV_AUTH, "SOCKS5 sub-negotiation response"); @@ -781,9 +782,9 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, /* Everything is good so far, user was authenticated! */ sxstate(sx, data, CONNECT_REQ_INIT); - /* FALLTHROUGH */ -CONNECT_REQ_INIT: + FALLTHROUGH(); case CONNECT_REQ_INIT: +CONNECT_REQ_INIT: if(socks5_resolve_local) { enum resolve_t rc = Curl_resolv(data, sx->hostname, sx->remote_port, TRUE, &dns); @@ -820,9 +821,10 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, return CURLPX_OK; } } - /* FALLTHROUGH */ + FALLTHROUGH(); + case CONNECT_RESOLVED: CONNECT_RESOLVED: - case CONNECT_RESOLVED: { + { char dest[MAX_IPADR_LEN]; /* printable address */ struct Curl_addrinfo *hp = NULL; if(dns) @@ -923,10 +925,10 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, infof(data, "SOCKS5 connect to %s:%d (remotely resolved)", sx->hostname, sx->remote_port); } - /* FALLTHROUGH */ + FALLTHROUGH(); -CONNECT_REQ_SEND: case CONNECT_REQ_SEND: +CONNECT_REQ_SEND: /* PORT MSB */ socksreq[len++] = (unsigned char)((sx->remote_port >> 8) & 0xff); /* PORT LSB */ @@ -941,7 +943,7 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, sx->outp = socksreq; sx->outstanding = len; sxstate(sx, data, CONNECT_REQ_SENDING); - /* FALLTHROUGH */ + FALLTHROUGH(); case CONNECT_REQ_SENDING: presult = socks_state_send(cf, sx, data, CURLPX_SEND_REQUEST, "SOCKS5 connect request"); @@ -960,7 +962,7 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, sx->outstanding = 10; /* minimum packet size is 10 */ sx->outp = socksreq; sxstate(sx, data, CONNECT_REQ_READ); - /* FALLTHROUGH */ + FALLTHROUGH(); case CONNECT_REQ_READ: presult = socks_state_recv(cf, sx, data, CURLPX_RECV_REQACK, "SOCKS5 connect request ack"); @@ -1049,7 +1051,7 @@ static CURLproxycode do_SOCKS5(struct Curl_cfilter *cf, #if defined(HAVE_GSSAPI) || defined(USE_WINDOWS_SSPI) } #endif - /* FALLTHROUGH */ + FALLTHROUGH(); case CONNECT_REQ_READ_MORE: presult = socks_state_recv(cf, sx, data, CURLPX_RECV_ADDRESS, "SOCKS5 connect request address"); diff --git a/lib/socks_sspi.c b/lib/socks_sspi.c index d1200ea037b..2baae2c2b21 100644 --- a/lib/socks_sspi.c +++ b/lib/socks_sspi.c @@ -331,9 +331,15 @@ CURLcode Curl_SOCKS5_gssapi_negotiate(struct Curl_cfilter *cf, failf(data, "Failed to determine user name."); return CURLE_COULDNT_CONNECT; } - infof(data, "SOCKS5 server authenticated user %s with GSS-API.", - names.sUserName); - s_pSecFn->FreeContextBuffer(names.sUserName); + else { +#ifndef CURL_DISABLE_VERBOSE_STRINGS + char *user_utf8 = curlx_convert_tchar_to_UTF8(names.sUserName); + infof(data, "SOCKS5 server authenticated user %s with GSS-API.", + (user_utf8 ? user_utf8 : "(unknown)")); + curlx_unicodefree(user_utf8); +#endif + s_pSecFn->FreeContextBuffer(names.sUserName); + } /* Do encryption */ socksreq[0] = 1; /* GSS-API subnegotiation version */ diff --git a/lib/telnet.c b/lib/telnet.c index 6c689c81662..1a1171ccb72 100644 --- a/lib/telnet.c +++ b/lib/telnet.c @@ -1546,7 +1546,7 @@ static CURLcode telnet_do(struct Curl_easy *data, bool *done) case 0: /* timeout */ pfd[0].revents = 0; pfd[1].revents = 0; - /* FALLTHROUGH */ + FALLTHROUGH(); default: /* read! */ if(pfd[0].revents & POLLIN) { /* read data from network */ diff --git a/lib/urlapi.c b/lib/urlapi.c index d8a6dab1abe..56ee16f055f 100644 --- a/lib/urlapi.c +++ b/lib/urlapi.c @@ -712,24 +712,30 @@ static int ipv4_normalize(struct dynbuf *host) Curl_dyn_reset(host); result = Curl_dyn_addf(host, "%u.%u.%u.%u", - parts[0] >> 24, (parts[0] >> 16) & 0xff, - (parts[0] >> 8) & 0xff, parts[0] & 0xff); + (unsigned int)(parts[0] >> 24), + (unsigned int)((parts[0] >> 16) & 0xff), + (unsigned int)((parts[0] >> 8) & 0xff), + (unsigned int)(parts[0] & 0xff)); break; case 1: /* a.b -- 8.24 bits */ if((parts[0] > 0xff) || (parts[1] > 0xffffff)) return HOST_NAME; Curl_dyn_reset(host); result = Curl_dyn_addf(host, "%u.%u.%u.%u", - parts[0], (parts[1] >> 16) & 0xff, - (parts[1] >> 8) & 0xff, parts[1] & 0xff); + (unsigned int)(parts[0]), + (unsigned int)((parts[1] >> 16) & 0xff), + (unsigned int)((parts[1] >> 8) & 0xff), + (unsigned int)(parts[1] & 0xff)); break; case 2: /* a.b.c -- 8.8.16 bits */ if((parts[0] > 0xff) || (parts[1] > 0xff) || (parts[2] > 0xffff)) return HOST_NAME; Curl_dyn_reset(host); result = Curl_dyn_addf(host, "%u.%u.%u.%u", - parts[0], parts[1], (parts[2] >> 8) & 0xff, - parts[2] & 0xff); + (unsigned int)(parts[0]), + (unsigned int)(parts[1]), + (unsigned int)((parts[2] >> 8) & 0xff), + (unsigned int)(parts[2] & 0xff)); break; case 3: /* a.b.c.d -- 8.8.8.8 bits */ if((parts[0] > 0xff) || (parts[1] > 0xff) || (parts[2] > 0xff) || @@ -737,7 +743,10 @@ static int ipv4_normalize(struct dynbuf *host) return HOST_NAME; Curl_dyn_reset(host); result = Curl_dyn_addf(host, "%u.%u.%u.%u", - parts[0], parts[1], parts[2], parts[3]); + (unsigned int)(parts[0]), + (unsigned int)(parts[1]), + (unsigned int)(parts[2]), + (unsigned int)(parts[3])); break; } if(result) diff --git a/lib/vauth/ntlm_sspi.c b/lib/vauth/ntlm_sspi.c index 3d102eb4a4f..92054316dc8 100644 --- a/lib/vauth/ntlm_sspi.c +++ b/lib/vauth/ntlm_sspi.c @@ -314,7 +314,7 @@ CURLcode Curl_auth_create_ntlm_type3_message(struct Curl_easy *data, &type_3_desc, &attrs, &expiry); if(status != SEC_E_OK) { - infof(data, "NTLM handshake failure (type-3 message): Status=%x", + infof(data, "NTLM handshake failure (type-3 message): Status=%lx", status); if(status == SEC_E_INSUFFICIENT_MEMORY) diff --git a/lib/vquic/vquic.c b/lib/vquic/vquic.c index 523b807bcc8..41fefceac31 100644 --- a/lib/vquic/vquic.c +++ b/lib/vquic/vquic.c @@ -179,7 +179,7 @@ static CURLcode do_sendmsg(struct Curl_cfilter *cf, qctx->no_gso = TRUE; return send_packet_no_gso(cf, data, qctx, pkt, pktlen, gsolen, psent); } - /* FALLTHROUGH */ + FALLTHROUGH(); default: failf(data, "sendmsg() returned %zd (errno %d)", sent, SOCKERRNO); return CURLE_SEND_ERROR; diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index 328aef5a0b0..cf9b1eb9059 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -439,11 +439,8 @@ static int myssh_is_known(struct Curl_easy *data) keymatch = CURLKHMATCH_OK; break; case SSH_KNOWN_HOSTS_OTHER: - /* fallthrough */ case SSH_KNOWN_HOSTS_NOT_FOUND: - /* fallthrough */ case SSH_KNOWN_HOSTS_UNKNOWN: - /* fallthrough */ case SSH_KNOWN_HOSTS_ERROR: keymatch = CURLKHMATCH_MISSING; break; @@ -459,7 +456,6 @@ static int myssh_is_known(struct Curl_easy *data) keymatch = CURLKHMATCH_OK; break; case SSH_SERVER_FILE_NOT_FOUND: - /* fallthrough */ case SSH_SERVER_NOT_KNOWN: keymatch = CURLKHMATCH_MISSING; break; @@ -623,7 +619,7 @@ int myssh_auth_interactive(struct connectdata *conn) if(rc < 0) return SSH_ERROR; - /* FALLTHROUGH */ + FALLTHROUGH(); case 1: sshc->kbd_state = 1; @@ -698,7 +694,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) ssh_set_blocking(sshc->ssh_session, 0); state(data, SSH_S_STARTUP); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_S_STARTUP: rc = ssh_connect(sshc->ssh_session); @@ -713,7 +709,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) state(data, SSH_HOSTKEY); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_HOSTKEY: rc = myssh_is_known(data); @@ -723,7 +719,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) } state(data, SSH_AUTHLIST); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_AUTHLIST:{ sshc->authed = FALSE; @@ -904,7 +900,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) break; } state(data, SSH_AUTH_PASS); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_AUTH_PASS: rc = ssh_userauth_password(sshc->ssh_session, NULL, conn->passwd); @@ -967,7 +963,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) break; } state(data, SSH_SFTP_REALPATH); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_SFTP_REALPATH: /* * Get the "home" directory @@ -1554,7 +1550,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) sshc->readdir_longentry = NULL; state(data, SSH_SFTP_READDIR_BOTTOM); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_SFTP_READDIR_BOTTOM: if(Curl_dyn_addn(&sshc->readdir_buf, "\n", 1)) result = CURLE_OUT_OF_MEMORY; @@ -1878,7 +1874,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) break; } state(data, SSH_SCP_DOWNLOAD); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_SCP_DOWNLOAD:{ curl_off_t bytecount; @@ -1942,7 +1938,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) ssh_set_blocking(sshc->ssh_session, 0); state(data, SSH_SESSION_DISCONNECT); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_SESSION_DISCONNECT: /* during weird times when we've been prematurely aborted, the channel @@ -1965,7 +1961,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) data->state.most_recent_ftp_entrypath = NULL; state(data, SSH_SESSION_FREE); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_SESSION_FREE: if(sshc->ssh_session) { ssh_free(sshc->ssh_session); @@ -2016,7 +2012,6 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) break; case SSH_QUIT: - /* fallthrough, just stop! */ default: /* internal error */ sshc->nextstate = SSH_NO_STATE; @@ -2607,7 +2602,7 @@ static ssize_t sftp_recv(struct Curl_easy *data, int sockindex, return -1; } - /* FALLTHROUGH */ + FALLTHROUGH(); case 1: conn->proto.sshc.sftp_recv_state = 1; diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index 2eaddb24408..83e09906a8f 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -589,10 +589,9 @@ static CURLcode ssh_knownhost(struct Curl_easy *data) switch(rc) { default: /* unknown return codes will equal reject */ - /* FALLTHROUGH */ case CURLKHSTAT_REJECT: state(data, SSH_SESSION_FREE); - /* FALLTHROUGH */ + FALLTHROUGH(); case CURLKHSTAT_DEFER: /* DEFER means bail out but keep the SSH_HOSTKEY state */ result = sshc->actualcode = CURLE_PEER_FAILED_VERIFICATION; @@ -601,9 +600,8 @@ static CURLcode ssh_knownhost(struct Curl_easy *data) /* remove old host+key that doesn't match */ if(host) libssh2_knownhost_del(sshc->kh, host); - /* FALLTHROUGH */ + FALLTHROUGH(); case CURLKHSTAT_FINE: - /* FALLTHROUGH */ case CURLKHSTAT_FINE_ADD_TO_FILE: /* proceed */ if(keycheck != LIBSSH2_KNOWNHOST_CHECK_MATCH) { @@ -997,7 +995,7 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) } state(data, SSH_S_STARTUP); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_S_STARTUP: rc = session_startup(sshc->ssh_session, sock); @@ -1016,7 +1014,7 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) state(data, SSH_HOSTKEY); - /* FALLTHROUGH */ + FALLTHROUGH(); case SSH_HOSTKEY: /* * Before we authenticate we should check the hostkey's fingerprint @@ -3024,7 +3022,6 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) break; case SSH_QUIT: - /* fallthrough, just stop! */ default: /* internal error */ sshc->nextstate = SSH_NO_STATE; diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c index f93697c1632..0e36dc6aa7e 100644 --- a/lib/vtls/openssl.c +++ b/lib/vtls/openssl.c @@ -1088,6 +1088,7 @@ static int ssl_ui_reader(UI *ui, UI_STRING *uis) UI_set_result(ui, uis, password); return 1; } + FALLTHROUGH(); default: break; } @@ -1106,6 +1107,7 @@ static int ssl_ui_writer(UI *ui, UI_STRING *uis) (UI_get_input_flags(uis) & UI_INPUT_FLAG_DEFAULT_PWD)) { return 1; } + FALLTHROUGH(); default: break; } @@ -1523,7 +1525,7 @@ int cert_stuff(struct Curl_easy *data, case SSL_FILETYPE_PEM: if(cert_done) break; - /* FALLTHROUGH */ + FALLTHROUGH(); case SSL_FILETYPE_ASN1: cert_use_result = key_blob ? SSL_CTX_use_PrivateKey_blob(ctx, key_blob, file_type, key_passwd) : @@ -2849,7 +2851,7 @@ ossl_set_ssl_version_min_max_legacy(ctx_option_t *ctx_options, failf(data, OSSL_PACKAGE " was built without TLS 1.3 support"); return CURLE_NOT_BUILT_IN; #endif - /* FALLTHROUGH */ + FALLTHROUGH(); case CURL_SSLVERSION_TLSv1_2: #if OPENSSL_VERSION_NUMBER >= 0x1000100FL *ctx_options |= SSL_OP_NO_TLSv1_1; @@ -2857,7 +2859,7 @@ ossl_set_ssl_version_min_max_legacy(ctx_option_t *ctx_options, failf(data, OSSL_PACKAGE " was built without TLS 1.2 support"); return CURLE_NOT_BUILT_IN; #endif - /* FALLTHROUGH */ + FALLTHROUGH(); case CURL_SSLVERSION_TLSv1_1: #if OPENSSL_VERSION_NUMBER >= 0x1000100FL *ctx_options |= SSL_OP_NO_TLSv1; @@ -2865,7 +2867,7 @@ ossl_set_ssl_version_min_max_legacy(ctx_option_t *ctx_options, failf(data, OSSL_PACKAGE " was built without TLS 1.1 support"); return CURLE_NOT_BUILT_IN; #endif - /* FALLTHROUGH */ + FALLTHROUGH(); case CURL_SSLVERSION_TLSv1_0: case CURL_SSLVERSION_TLSv1: break; @@ -2876,12 +2878,12 @@ ossl_set_ssl_version_min_max_legacy(ctx_option_t *ctx_options, #if OPENSSL_VERSION_NUMBER >= 0x1000100FL *ctx_options |= SSL_OP_NO_TLSv1_1; #endif - /* FALLTHROUGH */ + FALLTHROUGH(); case CURL_SSLVERSION_MAX_TLSv1_1: #if OPENSSL_VERSION_NUMBER >= 0x1000100FL *ctx_options |= SSL_OP_NO_TLSv1_2; #endif - /* FALLTHROUGH */ + FALLTHROUGH(); case CURL_SSLVERSION_MAX_TLSv1_2: #ifdef TLS1_3_VERSION *ctx_options |= SSL_OP_NO_TLSv1_3; diff --git a/lib/vtls/rustls.c b/lib/vtls/rustls.c index 8751fd98136..d58970910c5 100644 --- a/lib/vtls/rustls.c +++ b/lib/vtls/rustls.c @@ -156,7 +156,7 @@ static ssize_t tls_recv_more(struct Curl_cfilter *cf, size_t errorlen; rustls_error(rresult, errorbuf, sizeof(errorbuf), &errorlen); failf(data, "rustls_connection_process_new_packets: %.*s", - errorlen, errorbuf); + (int)errorlen, errorbuf); *err = map_error(rresult); return -1; } @@ -225,7 +225,7 @@ cr_recv(struct Curl_cfilter *cf, struct Curl_easy *data, char errorbuf[255]; size_t errorlen; rustls_error(rresult, errorbuf, sizeof(errorbuf), &errorlen); - failf(data, "rustls_connection_read: %.*s", errorlen, errorbuf); + failf(data, "rustls_connection_read: %.*s", (int)errorlen, errorbuf); *err = CURLE_READ_ERROR; nread = -1; goto out; @@ -301,7 +301,7 @@ cr_send(struct Curl_cfilter *cf, struct Curl_easy *data, &plainwritten); if(rresult != RUSTLS_RESULT_OK) { rustls_error(rresult, errorbuf, sizeof(errorbuf), &errorlen); - failf(data, "rustls_connection_write: %.*s", errorlen, errorbuf); + failf(data, "rustls_connection_write: %.*s", (int)errorlen, errorbuf); *err = CURLE_WRITE_ERROR; return -1; } @@ -459,7 +459,7 @@ cr_init_backend(struct Curl_cfilter *cf, struct Curl_easy *data, } if(result != RUSTLS_RESULT_OK) { rustls_error(result, errorbuf, sizeof(errorbuf), &errorlen); - failf(data, "rustls_client_connection_new: %.*s", errorlen, errorbuf); + failf(data, "rustls_client_connection_new: %.*s", (int)errorlen, errorbuf); return CURLE_COULDNT_CONNECT; } rustls_connection_set_userdata(rconn, backend); @@ -563,8 +563,8 @@ cr_connect_common(struct Curl_cfilter *cf, return CURLE_SSL_CONNECT_ERROR; } if(blocking && 0 == what) { - failf(data, "rustls connection timeout after %d ms", - socket_check_timeout); + failf(data, "rustls connection timeout after %" + CURL_FORMAT_TIMEDIFF_T " ms", socket_check_timeout); return CURLE_OPERATION_TIMEDOUT; } if(0 == what) { diff --git a/lib/vtls/schannel.c b/lib/vtls/schannel.c index b2a707950d5..455269a3c4a 100644 --- a/lib/vtls/schannel.c +++ b/lib/vtls/schannel.c @@ -666,7 +666,7 @@ schannel_acquire_credential_handle(struct Curl_cfilter *cf, cert_showfilename_error); else failf(data, "schannel: Failed to import cert file %s, " - "last error is 0x%x", + "last error is 0x%lx", cert_showfilename_error, errorcode); return CURLE_SSL_CERTPROBLEM; } @@ -677,7 +677,7 @@ schannel_acquire_credential_handle(struct Curl_cfilter *cf, if(!client_certs[0]) { failf(data, "schannel: Failed to get certificate from file %s" - ", last error is 0x%x", + ", last error is 0x%lx", cert_showfilename_error, GetLastError()); CertCloseStore(cert_store, 0); return CURLE_SSL_CERTPROBLEM; @@ -690,10 +690,15 @@ schannel_acquire_credential_handle(struct Curl_cfilter *cf, CERT_STORE_OPEN_EXISTING_FLAG | cert_store_name, cert_store_path); if(!cert_store) { - failf(data, "schannel: Failed to open cert store %x %s, " - "last error is 0x%x", - cert_store_name, cert_store_path, GetLastError()); + char *path_utf8 = + curlx_convert_tchar_to_UTF8(cert_store_path); + failf(data, "schannel: Failed to open cert store %lx %s, " + "last error is 0x%lx", + cert_store_name, + (path_utf8 ? path_utf8 : "(unknown)"), + GetLastError()); free(cert_store_path); + curlx_unicodefree(path_utf8); curlx_unicodefree(cert_path); return CURLE_SSL_CERTPROBLEM; } diff --git a/lib/vtls/schannel_verify.c b/lib/vtls/schannel_verify.c index e7c8bc66b9d..24146d0bd61 100644 --- a/lib/vtls/schannel_verify.c +++ b/lib/vtls/schannel_verify.c @@ -172,7 +172,7 @@ static CURLcode add_certs_data_to_store(HCERTSTORE trust_store, /* Sanity check that the cert_context object is the right type */ if(CERT_QUERY_CONTENT_CERT != actual_content_type) { failf(data, - "schannel: unexpected content type '%d' when extracting " + "schannel: unexpected content type '%lu' when extracting " "certificate from CA file '%s'", actual_content_type, ca_file_text); result = CURLE_SSL_CACERT_BADFILE; @@ -753,7 +753,7 @@ CURLcode Curl_verify_certificate(struct Curl_cfilter *cf, failf(data, "schannel: CertGetCertificateChain trust error" " CERT_TRUST_REVOCATION_STATUS_UNKNOWN"); else - failf(data, "schannel: CertGetCertificateChain error mask: 0x%08x", + failf(data, "schannel: CertGetCertificateChain error mask: 0x%08lx", dwTrustErrorMask); result = CURLE_PEER_FAILED_VERIFICATION; } diff --git a/lib/vtls/wolfssl.c b/lib/vtls/wolfssl.c index 5890bb6097e..998008ec7bf 100644 --- a/lib/vtls/wolfssl.c +++ b/lib/vtls/wolfssl.c @@ -1084,9 +1084,7 @@ static ssize_t wolfssl_recv(struct Curl_cfilter *cf, *curlcode = CURLE_OK; return 0; case SSL_ERROR_NONE: - /* FALLTHROUGH */ case SSL_ERROR_WANT_READ: - /* FALLTHROUGH */ case SSL_ERROR_WANT_WRITE: /* there's data pending, re-invoke wolfSSL_read() */ CURL_TRC_CF(data, cf, "wolfssl_recv(len=%zu) -> AGAIN", blen); diff --git a/lib/vtls/x509asn1.c b/lib/vtls/x509asn1.c index 8b1eed63f3d..4bfcba90545 100644 --- a/lib/vtls/x509asn1.c +++ b/lib/vtls/x509asn1.c @@ -379,10 +379,10 @@ utf8asn1str(char **to, int type, const char *from, const char *end) case 4: wc = (wc << 8) | *(const unsigned char *) from++; wc = (wc << 8) | *(const unsigned char *) from++; - /* FALLTHROUGH */ + FALLTHROUGH(); case 2: wc = (wc << 8) | *(const unsigned char *) from++; - /* FALLTHROUGH */ + FALLTHROUGH(); default: /* case 1: */ wc = (wc << 8) | *(const unsigned char *) from++; } @@ -548,7 +548,7 @@ static const char *GTime2str(const char *beg, const char *end) break; case 2: sec1 = fracp[-2]; - /* FALLTHROUGH */ + FALLTHROUGH(); case 1: sec2 = fracp[-1]; break; @@ -606,6 +606,7 @@ static const char *UTime2str(const char *beg, const char *end) switch(tzp - sec) { case 0: sec = "00"; + FALLTHROUGH(); case 2: break; default: @@ -964,7 +965,7 @@ static int do_pubkey(struct Curl_easy *data, int certnum, */ const size_t len = ((pubkey->end - pubkey->beg - 2) * 4); if(!certnum) - infof(data, " ECC Public Key (%lu bits)", len); + infof(data, " ECC Public Key (%zu bits)", len); if(data->set.ssl.certinfo) { char q[sizeof(len) * 8 / 3 + 1]; (void)msnprintf(q, sizeof(q), "%zu", len); @@ -998,7 +999,7 @@ static int do_pubkey(struct Curl_easy *data, int certnum, if(len > 32) elem.beg = q; /* Strip leading zero bytes. */ if(!certnum) - infof(data, " RSA Public Key (%lu bits)", len); + infof(data, " RSA Public Key (%zu bits)", len); if(data->set.ssl.certinfo) { char r[sizeof(len) * 8 / 3 + 1]; msnprintf(r, sizeof(r), "%zu", len); diff --git a/lib/ws.c b/lib/ws.c index adde531f5ed..f924362a865 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -296,7 +296,7 @@ static CURLcode ws_dec_pass(struct ws_decoder *dec, case WS_DEC_INIT: ws_dec_reset(dec); dec->state = WS_DEC_HEAD; - /* FALLTHROUGH */ + FALLTHROUGH(); case WS_DEC_HEAD: result = ws_dec_read_head(dec, data, inraw); if(result) { @@ -321,7 +321,7 @@ static CURLcode ws_dec_pass(struct ws_decoder *dec, dec->state = WS_DEC_INIT; break; } - /* FALLTHROUGH */ + FALLTHROUGH(); case WS_DEC_PAYLOAD: result = ws_dec_pass_payload(dec, data, inraw, write_payload, write_ctx); ws_dec_info(dec, data, "passing"); diff --git a/m4/curl-compilers.m4 b/m4/curl-compilers.m4 index 35ba19866fe..5346321641e 100644 --- a/m4/curl-compilers.m4 +++ b/m4/curl-compilers.m4 @@ -832,6 +832,8 @@ AC_DEFUN([CURL_SET_COMPILER_WARNING_OPTS], [ dnl Only clang 2.9 or later if test "$compiler_num" -ge "209"; then tmp_CFLAGS="$tmp_CFLAGS -Wno-sign-conversion" + # CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [sign-conversion]) # FIXME + # tmp_CFLAGS="$tmp_CFLAGS -Wno-error=sign-conversion" # FIXME CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [shift-sign-overflow]) # CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [padded]) # Not used because we cannot change public structs fi @@ -839,6 +841,7 @@ AC_DEFUN([CURL_SET_COMPILER_WARNING_OPTS], [ dnl Only clang 3.0 or later if test "$compiler_num" -ge "300"; then CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [language-extension-token]) + tmp_CFLAGS="$tmp_CFLAGS -Wformat=2" fi # dnl Only clang 3.2 or later @@ -887,6 +890,10 @@ AC_DEFUN([CURL_SET_COMPILER_WARNING_OPTS], [ CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [assign-enum]) CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [extra-semi-stmt]) fi + dnl clang 10 or later + if test "$compiler_num" -ge "1000"; then + tmp_CFLAGS="$tmp_CFLAGS -Wimplicit-fallthrough" # we have silencing markup for clang 10.0 and above only + fi fi dnl Disable pointer to bool conversion warnings since they cause dnl lib/securetransp.c cause several warnings for checks we want. @@ -1016,8 +1023,10 @@ AC_DEFUN([CURL_SET_COMPILER_WARNING_OPTS], [ CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [type-limits old-style-declaration]) CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [missing-parameter-type empty-body]) CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [clobbered ignored-qualifiers]) - CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [conversion]) + CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [conversion trampolines]) tmp_CFLAGS="$tmp_CFLAGS -Wno-sign-conversion" + # CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [sign-conversion]) # FIXME + # tmp_CFLAGS="$tmp_CFLAGS -Wno-error=sign-conversion" # FIXME CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [vla]) dnl required for -Warray-bounds, included in -Wall tmp_CFLAGS="$tmp_CFLAGS -ftree-vrp" @@ -1063,10 +1072,7 @@ AC_DEFUN([CURL_SET_COMPILER_WARNING_OPTS], [ CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [alloc-zero]) tmp_CFLAGS="$tmp_CFLAGS -Wformat-overflow=2" tmp_CFLAGS="$tmp_CFLAGS -Wformat-truncation=2" - if test "$compiler_num" -lt "1200"; then - dnl gcc 12 doesn't acknowledge our comment markups - tmp_CFLAGS="$tmp_CFLAGS -Wimplicit-fallthrough=4" - fi + tmp_CFLAGS="$tmp_CFLAGS -Wimplicit-fallthrough" fi # dnl Only gcc 10 or later diff --git a/packages/OS400/ccsidcurl.c b/packages/OS400/ccsidcurl.c index 48f1f5fbdc7..596c1f1e150 100644 --- a/packages/OS400/ccsidcurl.c +++ b/packages/OS400/ccsidcurl.c @@ -1282,7 +1282,7 @@ curl_easy_setopt_ccsid(CURL *easy, CURLoption tag, ...) result = curl_easy_setopt(easy, tag, &blob); break; } - /* FALLTHROUGH */ + FALLTHROUGH(); case CURLOPT_ERRORBUFFER: /* This is an output buffer. */ result = Curl_vsetopt(easy, tag, arg); break; diff --git a/src/tool_cb_dbg.c b/src/tool_cb_dbg.c index ce5e25e92c3..cbf57f05743 100644 --- a/src/tool_cb_dbg.c +++ b/src/tool_cb_dbg.c @@ -217,7 +217,7 @@ int tool_debug_cb(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(output, "%s%s== Info: %.*s", timebuf, idsbuf, (int)size, data); - /* FALLTHROUGH */ + FALLTHROUGH(); default: /* in case a new one is introduced to shock us */ return 0; diff --git a/src/tool_cb_prg.c b/src/tool_cb_prg.c index ef47b42da01..86b6fa60556 100644 --- a/src/tool_cb_prg.c +++ b/src/tool_cb_prg.c @@ -208,7 +208,14 @@ int tool_progress_cb(void *clientp, memset(line, '#', num); line[num] = '\0'; msnprintf(format, sizeof(format), "\r%%-%ds %%5.1f%%%%", barwidth); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif fprintf(bar->out, format, line, percent); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif } fflush(bar->out); bar->prev = point; diff --git a/src/tool_easysrc.c b/src/tool_easysrc.c index 6ef2be721cf..8b9c68c91fe 100644 --- a/src/tool_easysrc.c +++ b/src/tool_easysrc.c @@ -113,7 +113,14 @@ CURLcode easysrc_addf(struct slist_wc **plist, const char *fmt, ...) char *bufp; va_list ap; va_start(ap, fmt); +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif bufp = curlx_mvaprintf(fmt, ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif va_end(ap); if(!bufp) { ret = CURLE_OUT_OF_MEMORY; diff --git a/src/tool_easysrc.h b/src/tool_easysrc.h index 8c8d1315014..f698c8f5cc2 100644 --- a/src/tool_easysrc.h +++ b/src/tool_easysrc.h @@ -40,7 +40,7 @@ extern int easysrc_slist_count; /* Number of curl_slist variables */ extern CURLcode easysrc_init(void); extern CURLcode easysrc_add(struct slist_wc **plist, const char *bupf); extern CURLcode easysrc_addf(struct slist_wc **plist, - const char *fmt, ...); + const char *fmt, ...) CURL_PRINTF(2, 3); extern CURLcode easysrc_perform(void); extern CURLcode easysrc_cleanup(void); diff --git a/src/tool_formparse.c b/src/tool_formparse.c index fa38698d5e7..875ce78d632 100644 --- a/src/tool_formparse.c +++ b/src/tool_formparse.c @@ -278,7 +278,7 @@ static CURLcode tool2curlparts(CURL *curl, struct tool_mime *m, case TOOLMIME_STDIN: if(!filename) filename = "-"; - /* FALLTHROUGH */ + FALLTHROUGH(); case TOOLMIME_STDINDATA: ret = curl_mime_data_cb(part, m->size, (curl_read_callback) tool_mime_stdin_read, diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 5fa1ace10dd..6b256f8224e 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -2337,7 +2337,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->file_clobber_mode = toggle ? CLOBBER_ALWAYS : CLOBBER_NEVER; break; } - /* FALLTHROUGH */ + FALLTHROUGH(); case 'o': /* --output */ /* output file */ { @@ -2640,7 +2640,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ switch(*nextarg) { case '+': nextarg++; - /* FALLTHROUGH */ + FALLTHROUGH(); default: /* If-Modified-Since: (section 14.28 in RFC2068) */ config->timecond = CURL_TIMECOND_IFMODSINCE; diff --git a/src/tool_ipfs.c b/src/tool_ipfs.c index 435d1697ce4..f3a20aa9448 100644 --- a/src/tool_ipfs.c +++ b/src/tool_ipfs.c @@ -275,22 +275,19 @@ CURLcode ipfs_url_rewrite(CURLU *uh, const char *protocol, char **url, curl_free(pathbuffer); curl_url_cleanup(gatewayurl); { - const char *msg = NULL; switch(result) { case CURLE_URL_MALFORMAT: - msg = "malformed target URL"; + helpf(tool_stderr, "malformed target URL"); break; case CURLE_FILE_COULDNT_READ_FILE: - msg = "IPFS automatic gateway detection failed"; + helpf(tool_stderr, "IPFS automatic gateway detection failed"); break; case CURLE_BAD_FUNCTION_ARGUMENT: - msg = "--ipfs-gateway was given a malformed URL"; + helpf(tool_stderr, "--ipfs-gateway was given a malformed URL"); break; default: break; } - if(msg) - helpf(tool_stderr, msg); } return result; } diff --git a/src/tool_msgs.c b/src/tool_msgs.c index c914836db77..5e4f6ad1424 100644 --- a/src/tool_msgs.c +++ b/src/tool_msgs.c @@ -48,7 +48,14 @@ static void voutf(struct GlobalConfig *config, char *ptr; char *print_buffer; +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif print_buffer = curlx_mvaprintf(fmt, ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif if(!print_buffer) return; len = strlen(print_buffer); @@ -119,7 +126,14 @@ void helpf(FILE *errors, const char *fmt, ...) va_start(ap, fmt); DEBUGASSERT(!strchr(fmt, '\n')); fputs("curl: ", errors); /* prefix it */ +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif vfprintf(errors, fmt, ap); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif va_end(ap); fputs("\n", errors); /* newline it */ } diff --git a/src/tool_msgs.h b/src/tool_msgs.h index 9458991c01a..e963efaa0b1 100644 --- a/src/tool_msgs.h +++ b/src/tool_msgs.h @@ -26,9 +26,13 @@ #include "tool_setup.h" #include "tool_cfgable.h" -void warnf(struct GlobalConfig *config, const char *fmt, ...); -void notef(struct GlobalConfig *config, const char *fmt, ...); -void helpf(FILE *errors, const char *fmt, ...); -void errorf(struct GlobalConfig *config, const char *fmt, ...); +void warnf(struct GlobalConfig *config, const char *fmt, ...) + CURL_PRINTF(2, 3); +void notef(struct GlobalConfig *config, const char *fmt, ...) + CURL_PRINTF(2, 3); +void helpf(FILE *errors, const char *fmt, ...) + CURL_PRINTF(2, 3); +void errorf(struct GlobalConfig *config, const char *fmt, ...) + CURL_PRINTF(2, 3); #endif /* HEADER_CURL_TOOL_MSGS_H */ diff --git a/src/tool_paramhlp.c b/src/tool_paramhlp.c index d70e80db4bb..17018cf9fdd 100644 --- a/src/tool_paramhlp.c +++ b/src/tool_paramhlp.c @@ -408,7 +408,7 @@ ParameterError proto2num(struct OperationConfig *config, break; case set: protoset[0] = NULL; - /* FALLTHROUGH */ + FALLTHROUGH(); case allow: protoset_set(protoset, p); break; diff --git a/src/tool_setopt.c b/src/tool_setopt.c index de3b78fab5b..e95c68dcb29 100644 --- a/src/tool_setopt.c +++ b/src/tool_setopt.c @@ -247,8 +247,15 @@ static char *c_escape(const char *str, curl_off_t len) format = "\\%03o"; } +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif result = curlx_dyn_addf(&escaped, format, (unsigned int) *(unsigned char *) s); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif } } } @@ -431,7 +438,7 @@ static CURLcode libcurl_generate_mime_part(CURL *curl, case TOOLMIME_STDIN: if(!filename) filename = "-"; - /* FALLTHROUGH */ + FALLTHROUGH(); case TOOLMIME_STDINDATA: /* Can only be reading stdin in the current context. */ CODE1("curl_mime_data_cb(part%d, -1, (curl_read_callback) fread, \\", diff --git a/src/tool_urlglob.c b/src/tool_urlglob.c index e45c7d10b20..8ae28a3a670 100644 --- a/src/tool_urlglob.c +++ b/src/tool_urlglob.c @@ -127,7 +127,7 @@ static CURLcode glob_set(struct URLGlob *glob, char **patternp, if(multiply(amount, pat->content.Set.size + 1)) return GLOBERROR("range overflow", 0, CURLE_URL_MALFORMAT); - /* FALLTHROUGH */ + FALLTHROUGH(); case ',': *buf = '\0'; @@ -171,7 +171,7 @@ static CURLcode glob_set(struct URLGlob *glob, char **patternp, ++pattern; ++(*posp); } - /* FALLTHROUGH */ + FALLTHROUGH(); default: *buf++ = *pattern++; /* copy character to set element */ ++(*posp); diff --git a/tests/http/clients/h2-download.c b/tests/http/clients/h2-download.c index 53f3ac0d00c..12c9f8871e7 100644 --- a/tests/http/clients/h2-download.c +++ b/tests/http/clients/h2-download.c @@ -56,10 +56,7 @@ int my_trace(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "== Info: %s", data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -76,6 +73,8 @@ int my_trace(CURL *handle, curl_infotype type, return 0; text = "<= Recv data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } fprintf(stderr, "%s, %lu bytes (0x%lx)\n", diff --git a/tests/http/clients/h2-serverpush.c b/tests/http/clients/h2-serverpush.c index 742a67e5966..13f804aa264 100644 --- a/tests/http/clients/h2-serverpush.c +++ b/tests/http/clients/h2-serverpush.c @@ -102,10 +102,7 @@ int my_trace(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "== Info: %s", data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -124,6 +121,8 @@ int my_trace(CURL *handle, curl_infotype type, case CURLINFO_SSL_DATA_IN: text = "<= Recv SSL data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } dump(text, (unsigned char *)data, size, 1); diff --git a/tests/libtest/lib1560.c b/tests/libtest/lib1560.c index 87420a33012..97d02daeff1 100644 --- a/tests/libtest/lib1560.c +++ b/tests/libtest/lib1560.c @@ -1662,6 +1662,10 @@ static int huge(void) for(i = 0; i < 7; i++) { char *partp; +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif msnprintf(total, sizeof(total), url, (i == 0)? &bigpart[1] : smallpart, @@ -1671,6 +1675,9 @@ static int huge(void) (i == 4)? &bigpart[1] : smallpart, (i == 5)? &bigpart[1] : smallpart, (i == 6)? &bigpart[1] : smallpart); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif rc = curl_url_set(urlp, CURLUPART_URL, total, CURLU_NON_SUPPORT_SCHEME); if((!i && (rc != CURLUE_BAD_SCHEME)) || (i && rc)) { diff --git a/tests/libtest/lib3026.c b/tests/libtest/lib3026.c index 34dcafc502e..6f31dabdef2 100644 --- a/tests/libtest/lib3026.c +++ b/tests/libtest/lib3026.c @@ -84,7 +84,7 @@ int test(char *URL) th = _beginthreadex(NULL, 0, run_thread, &results[i], 0, NULL); #endif if(!th) { - fprintf(stderr, "%s:%d Couldn't create thread, errno %d\n", + fprintf(stderr, "%s:%d Couldn't create thread, errno %lu\n", __FILE__, __LINE__, GetLastError()); tid_count = i; test_failure = -1; diff --git a/tests/libtest/lib517.c b/tests/libtest/lib517.c index 7c65a659cf9..0d1ea2eb440 100644 --- a/tests/libtest/lib517.c +++ b/tests/libtest/lib517.c @@ -164,7 +164,7 @@ int test(char *URL) time_t out = curl_getdate(dates[i].input, NULL); if(out != dates[i].output) { printf("WRONGLY %s => %ld (instead of %ld)\n", - dates[i].input, out, dates[i].output); + dates[i].input, (long)out, (long)dates[i].output); error++; } } diff --git a/tests/libtest/lib518.c b/tests/libtest/lib518.c index e61d80a6f55..04e3b5b9993 100644 --- a/tests/libtest/lib518.c +++ b/tests/libtest/lib518.c @@ -99,6 +99,11 @@ static int fopen_works(void) return ret; } +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif + static int rlimit(int keep_open) { int nitems, i; @@ -459,6 +464,10 @@ static int rlimit(int keep_open) return 0; } +#ifdef __clang__ +#pragma clang diagnostic pop +#endif + int test(char *URL) { CURLcode res; diff --git a/tests/libtest/lib537.c b/tests/libtest/lib537.c index 8735947cf21..51d6d03456b 100644 --- a/tests/libtest/lib537.c +++ b/tests/libtest/lib537.c @@ -99,6 +99,11 @@ static int fopen_works(void) return ret; } +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif + static int rlimit(int keep_open) { int *tmpfd; @@ -460,6 +465,10 @@ static int rlimit(int keep_open) return 0; } +#ifdef __clang__ +#pragma clang diagnostic pop +#endif + int test(char *URL) { CURLcode res; diff --git a/tests/libtest/lib552.c b/tests/libtest/lib552.c index 13726c6b482..436b86ec020 100644 --- a/tests/libtest/lib552.c +++ b/tests/libtest/lib552.c @@ -96,10 +96,7 @@ int my_trace(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "== Info: %s", (char *)data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -118,6 +115,8 @@ int my_trace(CURL *handle, curl_infotype type, case CURLINFO_SSL_DATA_IN: text = "<= Recv SSL data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } dump(text, stderr, (unsigned char *)data, size, config->trace_ascii); diff --git a/tests/libtest/lib557.c b/tests/libtest/lib557.c index 6f96668da29..648992e5279 100644 --- a/tests/libtest/lib557.c +++ b/tests/libtest/lib557.c @@ -1281,7 +1281,7 @@ static int test_weird_arguments(void) rc = curl_msnprintf(buf, sizeof(buf), "%d, %.*1$d", 500, 1); if(rc != sizeof(buf) - 1) { - printf("curl_mprintf() returned %d and not %d!\n", rc, + printf("curl_mprintf() returned %d and not %zu!\n", rc, sizeof(buf) - 1); errors++; } diff --git a/tests/libtest/testtrace.c b/tests/libtest/testtrace.c index f78a9b9433f..49ff8ae20ef 100644 --- a/tests/libtest/testtrace.c +++ b/tests/libtest/testtrace.c @@ -117,10 +117,7 @@ int libtest_debug_cb(CURL *handle, curl_infotype type, switch(type) { case CURLINFO_TEXT: fprintf(stderr, "%s== Info: %s", timestr, (char *)data); - /* FALLTHROUGH */ - default: /* in case a new one is introduced to shock us */ return 0; - case CURLINFO_HEADER_OUT: text = "=> Send header"; break; @@ -139,6 +136,8 @@ int libtest_debug_cb(CURL *handle, curl_infotype type, case CURLINFO_SSL_DATA_IN: text = "<= Recv SSL data"; break; + default: /* in case a new one is introduced to shock us */ + return 0; } libtest_debug_dump(timebuf, text, stderr, data, size, trace_cfg->nohex); diff --git a/tests/server/mqttd.c b/tests/server/mqttd.c index 8a0da3ee687..0c31376c108 100644 --- a/tests/server/mqttd.c +++ b/tests/server/mqttd.c @@ -246,7 +246,7 @@ static int connack(FILE *dump, curl_socket_t fd) rc = swrite(fd, (char *)packet, sizeof(packet)); if(rc > 0) { - logmsg("WROTE %d bytes [CONNACK]", rc); + logmsg("WROTE %zd bytes [CONNACK]", rc); loghex(packet, rc); logprotocol(FROM_SERVER, "CONNACK", 2, dump, packet, sizeof(packet)); } @@ -270,7 +270,7 @@ static int suback(FILE *dump, curl_socket_t fd, unsigned short packetid) rc = swrite(fd, (char *)packet, sizeof(packet)); if(rc == sizeof(packet)) { - logmsg("WROTE %d bytes [SUBACK]", rc); + logmsg("WROTE %zd bytes [SUBACK]", rc); loghex(packet, rc); logprotocol(FROM_SERVER, "SUBACK", 3, dump, packet, rc); return 0; @@ -292,7 +292,7 @@ static int puback(FILE *dump, curl_socket_t fd, unsigned short packetid) rc = swrite(fd, (char *)packet, sizeof(packet)); if(rc == sizeof(packet)) { - logmsg("WROTE %d bytes [PUBACK]", rc); + logmsg("WROTE %zd bytes [PUBACK]", rc); loghex(packet, rc); logprotocol(FROM_SERVER, dump, packet, rc); return 0; @@ -310,7 +310,7 @@ static int disconnect(FILE *dump, curl_socket_t fd) }; ssize_t rc = swrite(fd, (char *)packet, sizeof(packet)); if(rc == sizeof(packet)) { - logmsg("WROTE %d bytes [DISCONNECT]", rc); + logmsg("WROTE %zd bytes [DISCONNECT]", rc); loghex(packet, rc); logprotocol(FROM_SERVER, "DISCONNECT", 0, dump, packet, rc); return 0; @@ -439,7 +439,7 @@ static int publish(FILE *dump, rc = swrite(fd, (char *)packet, sendamount); if(rc > 0) { - logmsg("WROTE %d bytes [PUBLISH]", rc); + logmsg("WROTE %zd bytes [PUBLISH]", rc); loghex(packet, rc); logprotocol(FROM_SERVER, "PUBLISH", remaininglength, dump, packet, rc); } @@ -465,10 +465,10 @@ static int fixedheader(curl_socket_t fd, ssize_t rc = sread(fd, (char *)buffer, 2); int i; if(rc < 2) { - logmsg("READ %d bytes [SHORT!]", rc); + logmsg("READ %zd bytes [SHORT!]", rc); return 1; /* fail */ } - logmsg("READ %d bytes", rc); + logmsg("READ %zd bytes", rc); loghex(buffer, rc); *bytep = buffer[0]; @@ -483,7 +483,7 @@ static int fixedheader(curl_socket_t fd, } } *remaining_lengthp = decode_length(&buffer[1], i, remaining_length_bytesp); - logmsg("Remaining Length: %ld [%d bytes]", (long) *remaining_lengthp, + logmsg("Remaining Length: %zu [%zu bytes]", *remaining_lengthp, *remaining_length_bytesp); return 0; } @@ -546,7 +546,7 @@ static curl_socket_t mqttit(curl_socket_t fd) buff_size = remaining_length; buffer = realloc(buffer, buff_size); if(!buffer) { - logmsg("Failed realloc of size %lu", buff_size); + logmsg("Failed realloc of size %zu", buff_size); goto end; } } @@ -555,7 +555,7 @@ static curl_socket_t mqttit(curl_socket_t fd) /* reading variable header and payload into buffer */ rc = sread(fd, (char *)buffer, remaining_length); if(rc > 0) { - logmsg("READ %d bytes", rc); + logmsg("READ %zd bytes", rc); loghex(buffer, rc); } } @@ -592,7 +592,7 @@ static curl_socket_t mqttit(curl_socket_t fd) /* check the length of the payload */ if((ssize_t)payload_len != (rc - 12)) { - logmsg("Payload length mismatch, expected %x got %x", + logmsg("Payload length mismatch, expected %zx got %zx", rc - 12, payload_len); goto end; } @@ -633,7 +633,7 @@ static curl_socket_t mqttit(curl_socket_t fd) /* two bytes topic length */ topic_len = (buffer[2] << 8) | buffer[3]; if(topic_len != (remaining_length - 5)) { - logmsg("Wrong topic length, got %d expected %d", + logmsg("Wrong topic length, got %u expected %zu", topic_len, remaining_length - 5); goto end; } @@ -677,7 +677,7 @@ static curl_socket_t mqttit(curl_socket_t fd) dump, buffer, rc); topiclen = (buffer[1 + bytes] << 8) | buffer[2 + bytes]; - logmsg("Got %d bytes topic", topiclen); + logmsg("Got %zu bytes topic", topiclen); /* TODO: verify topiclen */ #ifdef QOS @@ -688,7 +688,7 @@ static curl_socket_t mqttit(curl_socket_t fd) /* get the request */ rc = sread(fd, (char *)&buffer[0], 2); - logmsg("READ %d bytes [DISCONNECT]", rc); + logmsg("READ %zd bytes [DISCONNECT]", rc); loghex(buffer, rc); logprotocol(FROM_CLIENT, "DISCONNECT", 0, dump, buffer, rc); goto end; @@ -767,12 +767,12 @@ static bool incoming(curl_socket_t listenfd) curl_socket_t newfd = accept(sockfd, NULL, NULL); if(CURL_SOCKET_BAD == newfd) { error = SOCKERRNO; - logmsg("accept(%d, NULL, NULL) failed with error: (%d) %s", - sockfd, error, sstrerror(error)); + logmsg("accept(%" CURL_FORMAT_SOCKET_T ", NULL, NULL) " + "failed with error: (%d) %s", sockfd, error, sstrerror(error)); } else { - logmsg("====> Client connect, fd %d. Read config from %s", - newfd, configfile); + logmsg("====> Client connect, fd %" CURL_FORMAT_SOCKET_T ". " + "Read config from %s", newfd, configfile); set_advisor_read_lock(loglockfile); (void)mqttit(newfd); /* until done */ clear_advisor_read_lock(loglockfile); @@ -910,7 +910,7 @@ static curl_socket_t sockdaemon(curl_socket_t sock, rc = listen(sock, 5); if(0 != rc) { error = SOCKERRNO; - logmsg("listen(%d, 5) failed with error: (%d) %s", + logmsg("listen(%" CURL_FORMAT_SOCKET_T ", 5) failed with error: (%d) %s", sock, error, sstrerror(error)); sclose(sock); return CURL_SOCKET_BAD; diff --git a/tests/server/sockfilt.c b/tests/server/sockfilt.c index f87d1c8f9f3..0900f6564fb 100644 --- a/tests/server/sockfilt.c +++ b/tests/server/sockfilt.c @@ -551,14 +551,14 @@ static unsigned int WINAPI select_ws_wait_thread(void *lpParameter) continue; } else { - logmsg("[select_ws_wait_thread] PeekNamedPipe len: %d", length); + logmsg("[select_ws_wait_thread] PeekNamedPipe len: %lu", length); } } else { /* if the pipe has NOT been closed, sleep and continue waiting */ ret = GetLastError(); if(ret != ERROR_BROKEN_PIPE) { - logmsg("[select_ws_wait_thread] PeekNamedPipe error: %d", ret); + logmsg("[select_ws_wait_thread] PeekNamedPipe error: %lu", ret); SleepEx(0, FALSE); continue; } @@ -1159,8 +1159,8 @@ static bool juggle(curl_socket_t *sockfdp, curl_socket_t newfd = accept(sockfd, NULL, NULL); if(CURL_SOCKET_BAD == newfd) { error = SOCKERRNO; - logmsg("accept(%d, NULL, NULL) failed with error: (%d) %s", - sockfd, error, sstrerror(error)); + logmsg("accept(%" CURL_FORMAT_SOCKET_T ", NULL, NULL) " + "failed with error: (%d) %s", sockfd, error, sstrerror(error)); } else { logmsg("====> Client connect"); @@ -1335,7 +1335,7 @@ static curl_socket_t sockdaemon(curl_socket_t sock, rc = listen(sock, 5); if(0 != rc) { error = SOCKERRNO; - logmsg("listen(%d, 5) failed with error: (%d) %s", + logmsg("listen(%" CURL_FORMAT_SOCKET_T ", 5) failed with error: (%d) %s", sock, error, sstrerror(error)); sclose(sock); return CURL_SOCKET_BAD; diff --git a/tests/server/socksd.c b/tests/server/socksd.c index 490085d4920..179f1fdb251 100644 --- a/tests/server/socksd.c +++ b/tests/server/socksd.c @@ -323,7 +323,7 @@ static curl_socket_t socks4(curl_socket_t fd, return CURL_SOCKET_BAD; } if(rc < 9) { - logmsg("SOCKS4 connect message too short: %d", rc); + logmsg("SOCKS4 connect message too short: %zd", rc); return CURL_SOCKET_BAD; } if(!config.port) @@ -350,7 +350,7 @@ static curl_socket_t socks4(curl_socket_t fd, logmsg("Sending SOCKS4 response failed!"); return CURL_SOCKET_BAD; } - logmsg("Sent %d bytes", rc); + logmsg("Sent %zd bytes", rc); loghex(response, rc); if(cd == 90) @@ -380,18 +380,18 @@ static curl_socket_t sockit(curl_socket_t fd) rc = recv(fd, (char *)buffer, sizeof(buffer), 0); if(rc <= 0) { - logmsg("SOCKS identifier message missing, recv returned %d", rc); + logmsg("SOCKS identifier message missing, recv returned %zd", rc); return CURL_SOCKET_BAD; } - logmsg("READ %d bytes", rc); + logmsg("READ %zd bytes", rc); loghex(buffer, rc); if(buffer[SOCKS5_VERSION] == 4) return socks4(fd, buffer, rc); if(rc < 3) { - logmsg("SOCKS5 identifier message too short: %d", rc); + logmsg("SOCKS5 identifier message too short: %zd", rc); return CURL_SOCKET_BAD; } @@ -408,7 +408,7 @@ static curl_socket_t sockit(curl_socket_t fd) /* after NMETHODS follows that many bytes listing the methods the client says it supports */ if(rc != (buffer[SOCKS5_NMETHODS] + 2)) { - logmsg("Expected %d bytes, got %d", buffer[SOCKS5_NMETHODS] + 2, rc); + logmsg("Expected %d bytes, got %zd", buffer[SOCKS5_NMETHODS] + 2, rc); return CURL_SOCKET_BAD; } logmsg("Incoming request deemed fine!"); @@ -421,17 +421,17 @@ static curl_socket_t sockit(curl_socket_t fd) logmsg("Sending response failed!"); return CURL_SOCKET_BAD; } - logmsg("Sent %d bytes", rc); + logmsg("Sent %zd bytes", rc); loghex(response, rc); /* expect the request or auth */ rc = recv(fd, (char *)buffer, sizeof(buffer), 0); if(rc <= 0) { - logmsg("SOCKS5 request or auth message missing, recv returned %d", rc); + logmsg("SOCKS5 request or auth message missing, recv returned %zd", rc); return CURL_SOCKET_BAD; } - logmsg("READ %d bytes", rc); + logmsg("READ %zd bytes", rc); loghex(buffer, rc); if(config.responsemethod == 2) { @@ -446,7 +446,7 @@ static curl_socket_t sockit(curl_socket_t fd) unsigned char plen; bool login = TRUE; if(rc < 5) { - logmsg("Too short auth input: %d", rc); + logmsg("Too short auth input: %zd", rc); return CURL_SOCKET_BAD; } if(buffer[SOCKS5_VERSION] != 1) { @@ -455,12 +455,12 @@ static curl_socket_t sockit(curl_socket_t fd) } ulen = buffer[SOCKS5_ULEN]; if(rc < 4 + ulen) { - logmsg("Too short packet for username: %d", rc); + logmsg("Too short packet for username: %zd", rc); return CURL_SOCKET_BAD; } plen = buffer[SOCKS5_ULEN + ulen + 1]; if(rc < 3 + ulen + plen) { - logmsg("Too short packet for ulen %d plen %d: %d", ulen, plen, rc); + logmsg("Too short packet for ulen %d plen %d: %zd", ulen, plen, rc); return CURL_SOCKET_BAD; } if((ulen != strlen(config.user)) || @@ -478,7 +478,7 @@ static curl_socket_t sockit(curl_socket_t fd) logmsg("Sending auth response failed!"); return CURL_SOCKET_BAD; } - logmsg("Sent %d bytes", rc); + logmsg("Sent %zd bytes", rc); loghex(response, rc); if(!login) return CURL_SOCKET_BAD; @@ -486,15 +486,15 @@ static curl_socket_t sockit(curl_socket_t fd) /* expect the request */ rc = recv(fd, (char *)buffer, sizeof(buffer), 0); if(rc <= 0) { - logmsg("SOCKS5 request message missing, recv returned %d", rc); + logmsg("SOCKS5 request message missing, recv returned %zd", rc); return CURL_SOCKET_BAD; } - logmsg("READ %d bytes", rc); + logmsg("READ %zd bytes", rc); loghex(buffer, rc); } if(rc < 6) { - logmsg("Too short for request: %d", rc); + logmsg("Too short for request: %zd", rc); return CURL_SOCKET_BAD; } @@ -539,7 +539,7 @@ static curl_socket_t sockit(curl_socket_t fd) return CURL_SOCKET_BAD; } if(rc < (4 + len + 2)) { - logmsg("Request too short: %d, expected %d", rc, 4 + len + 2); + logmsg("Request too short: %zd, expected %d", rc, 4 + len + 2); return CURL_SOCKET_BAD; } logmsg("Received ATYP %d", type); @@ -625,7 +625,7 @@ static curl_socket_t sockit(curl_socket_t fd) logmsg("Sending connect response failed!"); return CURL_SOCKET_BAD; } - logmsg("Sent %d bytes", rc); + logmsg("Sent %zd bytes", rc); loghex(response, rc); if(!rep) @@ -754,13 +754,14 @@ static bool incoming(curl_socket_t listenfd) curl_socket_t newfd = accept(sockfd, NULL, NULL); if(CURL_SOCKET_BAD == newfd) { error = SOCKERRNO; - logmsg("accept(%d, NULL, NULL) failed with error: (%d) %s", + logmsg("accept(%" CURL_FORMAT_SOCKET_T ", NULL, NULL) " + "failed with error: (%d) %s", sockfd, error, sstrerror(error)); } else { curl_socket_t remotefd; - logmsg("====> Client connect, fd %d. Read config from %s", - newfd, configfile); + logmsg("====> Client connect, fd %" CURL_FORMAT_SOCKET_T ". " + "Read config from %s", newfd, configfile); remotefd = sockit(newfd); /* SOCKS until done */ if(remotefd == CURL_SOCKET_BAD) { logmsg("====> Client disconnect"); @@ -943,7 +944,7 @@ static curl_socket_t sockdaemon(curl_socket_t sock, rc = listen(sock, 5); if(0 != rc) { error = SOCKERRNO; - logmsg("listen(%d, 5) failed with error: (%d) %s", + logmsg("listen(%" CURL_FORMAT_SOCKET_T ", 5) failed with error: (%d) %s", sock, error, sstrerror(error)); sclose(sock); return CURL_SOCKET_BAD; diff --git a/tests/server/sws.c b/tests/server/sws.c index fa9b1ac809f..d9125859777 100644 --- a/tests/server/sws.c +++ b/tests/server/sws.c @@ -374,7 +374,7 @@ static int ProcessRequest(struct httprequest *req) req->callcount++; - logmsg("Process %d bytes request%s", req->offset, + logmsg("Process %zu bytes request%s", req->offset, req->callcount > 1?" [CONTINUED]":""); /* try to figure out the request characteristics as soon as possible, but @@ -557,14 +557,14 @@ static int ProcessRequest(struct httprequest *req) logmsg("request not complete yet"); return 0; /* not complete yet */ } - logmsg("- request found to be complete (%d)", req->testno); + logmsg("- request found to be complete (%ld)", req->testno); if(req->testno == DOCNUMBER_NOTHING) { /* check for a Testno: header with the test case number */ char *testno = strstr(line, "\nTestno: "); if(testno) { req->testno = strtol(&testno[9], NULL, 10); - logmsg("Found test number %d in Testno: header!", req->testno); + logmsg("Found test number %ld in Testno: header!", req->testno); } else { logmsg("No Testno: header"); @@ -702,8 +702,8 @@ static int ProcessRequest(struct httprequest *req) /* Negotiate iterations */ static long prev_testno = -1; static long prev_partno = -1; - logmsg("Negotiate: prev_testno: %d, prev_partno: %d", - prev_testno, prev_partno); + logmsg("Negotiate: prev_testno: %ld, prev_partno: %ld", + prev_testno, prev_partno); if(req->testno != prev_testno) { prev_testno = req->testno; prev_partno = req->partno; @@ -1198,8 +1198,8 @@ static int send_doc(curl_socket_t sock, struct httprequest *req) int intervals = msecs_left / MAX_SLEEP_TIME_MS; if(msecs_left%MAX_SLEEP_TIME_MS) intervals++; - logmsg("Pausing %d milliseconds after writing %d bytes", - msecs_left, written); + logmsg("Pausing %d milliseconds after writing %zd bytes", + msecs_left, written); while((intervals > 0) && !got_exit_signal) { int sleep_time = msecs_left > MAX_SLEEP_TIME_MS ? MAX_SLEEP_TIME_MS : msecs_left; @@ -2334,7 +2334,8 @@ int main(int argc, char *argv[]) curl_socket_t msgsock; do { msgsock = accept_connection(sock); - logmsg("accept_connection %d returned %d", sock, msgsock); + logmsg("accept_connection %" CURL_FORMAT_SOCKET_T + " returned %" CURL_FORMAT_SOCKET_T, sock, msgsock); if(CURL_SOCKET_BAD == msgsock) goto sws_cleanup; if(req->delay) diff --git a/tests/server/tftpd.c b/tests/server/tftpd.c index 9f93f4c6b48..9e839eafc4e 100644 --- a/tests/server/tftpd.c +++ b/tests/server/tftpd.c @@ -1129,7 +1129,7 @@ static int validate_access(struct testcase *test, if(!stream) { int error = errno; logmsg("fopen() failed with error: %d %s", error, strerror(error)); - logmsg("Couldn't open test file for test : %d", testno); + logmsg("Couldn't open test file for test: %ld", testno); return EACCESS; } else { diff --git a/tests/server/util.c b/tests/server/util.c index 34bca8659d4..d6698e5e363 100644 --- a/tests/server/util.c +++ b/tests/server/util.c @@ -139,7 +139,7 @@ static const char *win32_strerror(int err, char *buf, size_t buflen) if(!FormatMessageA((FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS), NULL, err, LANG_NEUTRAL, buf, (DWORD)buflen, NULL)) - msnprintf(buf, buflen, "Unknown error %lu (%#lx)", err, err); + msnprintf(buf, buflen, "Unknown error %d (%#x)", err, err); return buf; } @@ -555,7 +555,7 @@ static void exit_signal_handler(int signum) static BOOL WINAPI ctrl_event_handler(DWORD dwCtrlType) { int signum = 0; - logmsg("ctrl_event_handler: %d", dwCtrlType); + logmsg("ctrl_event_handler: %lu", dwCtrlType); switch(dwCtrlType) { #ifdef SIGINT case CTRL_C_EVENT: signum = SIGINT; break; @@ -569,7 +569,7 @@ static BOOL WINAPI ctrl_event_handler(DWORD dwCtrlType) default: return FALSE; } if(signum) { - logmsg("ctrl_event_handler: %d -> %d", dwCtrlType, signum); + logmsg("ctrl_event_handler: %lu -> %d", dwCtrlType, signum); raise(signum); } return TRUE; diff --git a/tests/server/util.h b/tests/server/util.h index 4dff40e814b..a91ecf47787 100644 --- a/tests/server/util.h +++ b/tests/server/util.h @@ -26,7 +26,7 @@ #include "server_setup.h" char *data_to_hex(char *data, size_t len); -void logmsg(const char *msg, ...); +void logmsg(const char *msg, ...) CURL_PRINTF(1, 2); long timediff(struct timeval newer, struct timeval older); #define TEST_DATA_PATH "%s/data/test%ld" diff --git a/tests/unit/unit1652.c b/tests/unit/unit1652.c index ef272621640..68ddec3ea10 100644 --- a/tests/unit/unit1652.c +++ b/tests/unit/unit1652.c @@ -21,6 +21,8 @@ * SPDX-License-Identifier: curl * ***************************************************************************/ +#define CURL_NO_FMT_CHECKS + #include "curlcheck.h" #include "urldata.h" @@ -105,7 +107,7 @@ fail_unless(verify(result, "Simple Test 42 testing 43\n") == 0, /* Variations of empty strings */ Curl_infof(data, ""); fail_unless(strlen(result) == 1, "Empty string"); -Curl_infof(data, "%s", NULL); +Curl_infof(data, "%s", (char *)NULL); fail_unless(verify(result, "(nil)") == 0, "Passing NULL as string"); /* A string just long enough to not be truncated */ From c1bc090d65b8d7d14e811dd36f5e8674be43dff3 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sat, 9 Dec 2023 20:37:11 +0000 Subject: [PATCH 046/509] windows: simplify detecting and using system headers - autotools, cmake: assume that if we detect Windows, `windows.h`, `winsock2.h` and `ws2tcpip.h` do exist. - lib: fix 3 outlier `#if` conditions to use `USE_WINSOCK` instead of looking for `winsock2.h`. - autotools: merge 3 Windows check methods into one. - move Watt-32 and lwIP socket support to `setup-win32.h` from `config-win32.h`. It opens up using these with all build tools. Also merge logic with Windows Sockets. - fix to assume Windows sockets with the mingw32ce toolchain. Follow-up to: 2748c64d605b19fb419ae56810ad8da36487a2d4 - cmake: delete unused variable `signature_call_conv` since eb33ccd5332435fa50f1758e5debb869c6942b7f. - autotools: simplify `CURL_CHECK_WIN32_LARGEFILE` detection. - examples/externalsocket: fix header order. - cmake/OtherTests.cmake: delete Windows-specific `_source_epilogue` that wasn't used anymore. - cmake/OtherTests.cmake: set `WIN32_LEAN_AND_MEAN` for test `SIZEOF_STRUCT_SOCKADDR_STORAGE`. After this patch curl universally uses `_WIN32` to guard Windows-specific logic. It guards Windows Sockets-specific logic with `USE_WINSOCK` (this might need further work). Reviewed-by: Jay Satiro Closes #12495 --- CMake/CurlTests.c | 30 ++--- CMake/OtherTests.cmake | 23 ++-- CMakeLists.txt | 13 +-- acinclude.m4 | 196 ++++++--------------------------- configure.ac | 38 ++----- docs/examples/externalsocket.c | 2 +- lib/cf-socket.c | 4 +- lib/config-win32.h | 55 --------- lib/config-win32ce.h | 9 -- lib/curl_config.h.cmake | 9 -- lib/curl_setup.h | 7 +- lib/inet_pton.h | 2 +- lib/setup-win32.h | 62 +++++++---- m4/curl-compilers.m4 | 3 +- m4/curl-functions.m4 | 29 ++--- 15 files changed, 119 insertions(+), 363 deletions(-) diff --git a/CMake/CurlTests.c b/CMake/CurlTests.c index e5462862649..e00acc542ec 100644 --- a/CMake/CurlTests.c +++ b/CMake/CurlTests.c @@ -164,13 +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,13 +184,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,13 +203,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,13 +223,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,13 +299,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 */ diff --git a/CMake/OtherTests.cmake b/CMake/OtherTests.cmake index a613f6ecdc1..f769b954777 100644 --- a/CMake/OtherTests.cmake +++ b/CMake/OtherTests.cmake @@ -29,20 +29,15 @@ set(_source_epilogue "#undef inline") 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") - if(WIN32) - set(CMAKE_REQUIRED_LIBRARIES "ws2_32") - endif() +if(WIN32) + set(CMAKE_EXTRA_INCLUDE_FILES "winsock2.h") + set(CMAKE_REQUIRED_DEFINITIONS "-DWIN32_LEAN_AND_MEAN") + set(CMAKE_REQUIRED_LIBRARIES "ws2_32") else() add_header_include(HAVE_SYS_TYPES_H "sys/types.h") add_header_include(HAVE_SYS_SOCKET_H "sys/socket.h") @@ -57,7 +52,7 @@ check_c_source_compiles("${_source_epilogue} return 0; }" HAVE_MSG_NOSIGNAL) -if(NOT HAVE_WINDOWS_H) +if(NOT WIN32) add_header_include(HAVE_SYS_TIME_H "sys/time.h") endif() check_c_source_compiles("${_source_epilogue} @@ -70,9 +65,7 @@ int main(void) { return 0; }" HAVE_STRUCT_TIMEVAL) -if(HAVE_WINDOWS_H) - set(CMAKE_EXTRA_INCLUDE_FILES "winsock2.h") -else() +if(NOT WIN32) set(CMAKE_EXTRA_INCLUDE_FILES) if(HAVE_SYS_SOCKET_H) set(CMAKE_EXTRA_INCLUDE_FILES "sys/socket.h") diff --git a/CMakeLists.txt b/CMakeLists.txt index d5f250da011..9f284bd9f1a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -351,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() @@ -770,7 +767,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) @@ -1053,9 +1050,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) @@ -1391,7 +1388,7 @@ endif() # TODO test which of these headers are required if(WIN32) - set(CURL_PULL_WS2TCPIP_H ${HAVE_WS2TCPIP_H}) + set(CURL_PULL_WS2TCPIP_H 1) else() set(CURL_PULL_SYS_TYPES_H ${HAVE_SYS_TYPES_H}) set(CURL_PULL_SYS_SOCKET_H ${HAVE_SYS_SOCKET_H}) diff --git a/acinclude.m4 b/acinclude.m4 index ac026e39d21..df80d693a52 100644 --- a/acinclude.m4 +++ b/acinclude.m4 @@ -171,144 +171,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 +202,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 +239,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 +287,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 +333,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 +418,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 +516,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,13 +585,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 @@ -731,7 +613,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,13 +621,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 @@ -782,7 +662,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,13 +670,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 @@ -837,13 +715,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 @@ -876,19 +752,17 @@ 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 @@ -937,13 +811,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 @@ -979,13 +851,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 @@ -1197,7 +1067,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 ]],[[ @@ -1294,13 +1164,11 @@ 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 @@ -1310,7 +1178,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 +1415,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 +1472,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/configure.ac b/configure.ac index c4e026068e6..810e3562bd8 100644 --- a/configure.ac +++ b/configure.ac @@ -503,6 +503,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 +584,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 @@ -1130,23 +1112,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 ]],[[ @@ -1668,7 +1646,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 @@ -1707,7 +1685,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 @@ -3473,14 +3451,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 HAVE_WINDOWS_H +#ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif -#ifdef HAVE_WINSOCK2_H #include #endif -#endif #ifdef HAVE_SYS_SOCKET_H #include #endif diff --git a/docs/examples/externalsocket.c b/docs/examples/externalsocket.c index 270a31996cc..6c9540a6dbe 100644 --- a/docs/examples/externalsocket.c +++ b/docs/examples/externalsocket.c @@ -31,9 +31,9 @@ #include #ifdef _WIN32 -#include #include #include +#include #define close closesocket #else #include /* socket types */ diff --git a/lib/cf-socket.c b/lib/cf-socket.c index e868b6bbfab..bd4f0d1e97e 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -137,14 +137,14 @@ static void nosigpipe(struct Curl_easy *data, #define nosigpipe(x,y) Curl_nop_stmt #endif -#if defined(__DragonFly__) || defined(HAVE_WINSOCK2_H) +#if defined(__DragonFly__) || defined(USE_WINSOCK) /* DragonFlyBSD and Windows use millisecond units */ #define KEEPALIVE_FACTOR(x) (x *= 1000) #else #define KEEPALIVE_FACTOR(x) #endif -#if defined(HAVE_WINSOCK2_H) && !defined(SIO_KEEPALIVE_VALS) +#if defined(USE_WINSOCK) && !defined(SIO_KEEPALIVE_VALS) #define SIO_KEEPALIVE_VALS _WSAIOW(IOC_VENDOR,4) struct tcp_keepalive { diff --git a/lib/config-win32.h b/lib/config-win32.h index 7b8a289bcdd..89ed1a0f16c 100644 --- a/lib/config-win32.h +++ b/lib/config-win32.h @@ -97,15 +97,6 @@ #define HAVE_UNISTD_H 1 #endif -/* Define if you have the header file. */ -#define HAVE_WINDOWS_H 1 - -/* Define if you have the header file. */ -#define HAVE_WINSOCK2_H 1 - -/* Define if you have the header file. */ -#define HAVE_WS2TCPIP_H 1 - /* Define to 1 if you have the header file. */ #if defined(__MINGW32__) #define HAVE_LIBGEN_H 1 @@ -292,52 +283,6 @@ /* Define to the size of `curl_off_t', as computed by sizeof. */ #define SIZEOF_CURL_OFF_T 8 -/* ---------------------------------------------------------------- */ -/* BSD-style lwIP TCP/IP stack SPECIFIC */ -/* ---------------------------------------------------------------- */ - -/* Define to use BSD-style lwIP TCP/IP stack. */ -/* #define USE_LWIPSOCK 1 */ - -#ifdef USE_LWIPSOCK -# undef USE_WINSOCK -# undef HAVE_WINSOCK2_H -# undef HAVE_WS2TCPIP_H -# undef HAVE_GETHOSTNAME -# undef LWIP_POSIX_SOCKETS_IO_NAMES -# undef RECV_TYPE_ARG1 -# undef RECV_TYPE_ARG3 -# undef SEND_TYPE_ARG1 -# undef SEND_TYPE_ARG3 -# define HAVE_GETHOSTBYNAME_R -# define HAVE_GETHOSTBYNAME_R_6 -# define LWIP_POSIX_SOCKETS_IO_NAMES 0 -# define RECV_TYPE_ARG1 int -# define RECV_TYPE_ARG3 size_t -# define SEND_TYPE_ARG1 int -# define SEND_TYPE_ARG3 size_t -#endif - -/* ---------------------------------------------------------------- */ -/* Watt-32 tcp/ip SPECIFIC */ -/* ---------------------------------------------------------------- */ - -#ifdef USE_WATT32 - #include - #undef byte - #undef word - #undef USE_WINSOCK - #undef HAVE_WINSOCK2_H - #undef HAVE_WS2TCPIP_H - #define HAVE_SYS_IOCTL_H - #define HAVE_SYS_SOCKET_H - #define HAVE_NETINET_IN_H - #define HAVE_NETDB_H - #define HAVE_ARPA_INET_H - #define SOCKET int -#endif - - /* ---------------------------------------------------------------- */ /* COMPILER SPECIFIC */ /* ---------------------------------------------------------------- */ diff --git a/lib/config-win32ce.h b/lib/config-win32ce.h index e0db57fd0fe..ae3ca290c3f 100644 --- a/lib/config-win32ce.h +++ b/lib/config-win32ce.h @@ -85,15 +85,6 @@ #define HAVE_UNISTD_H 1 #endif -/* Define if you have the header file. */ -#define HAVE_WINDOWS_H 1 - -/* Define if you have the header file. */ -#define HAVE_WINSOCK2_H 1 - -/* Define if you have the header file. */ -#define HAVE_WS2TCPIP_H 1 - /* ---------------------------------------------------------------- */ /* OTHER HEADER INFO */ /* ---------------------------------------------------------------- */ diff --git a/lib/curl_config.h.cmake b/lib/curl_config.h.cmake index 339358ea362..8c824721aab 100644 --- a/lib/curl_config.h.cmake +++ b/lib/curl_config.h.cmake @@ -599,18 +599,9 @@ /* Define to 1 if you have the header file. */ #cmakedefine HAVE_UTIME_H 1 -/* Define to 1 if you have the windows.h header file. */ -#cmakedefine HAVE_WINDOWS_H 1 - -/* Define to 1 if you have the winsock2.h header file. */ -#cmakedefine HAVE_WINSOCK2_H 1 - /* Define this symbol if your OS supports changing the contents of argv */ #cmakedefine HAVE_WRITABLE_ARGV 1 -/* Define to 1 if you have the ws2tcpip.h header file. */ -#cmakedefine HAVE_WS2TCPIP_H 1 - /* Define to 1 if you need the lber.h header file even with ldap.h */ #cmakedefine NEED_LBER_H 1 diff --git a/lib/curl_setup.h b/lib/curl_setup.h index f81cf610023..fd7358b4502 100644 --- a/lib/curl_setup.h +++ b/lib/curl_setup.h @@ -253,7 +253,7 @@ * Windows setup file includes some system headers. */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # include "setup-win32.h" #endif @@ -725,10 +725,7 @@ */ #if defined(__LWIP_OPT_H__) || defined(LWIP_HDR_OPT_H) -# if defined(SOCKET) || \ - defined(USE_WINSOCK) || \ - defined(HAVE_WINSOCK2_H) || \ - defined(HAVE_WS2TCPIP_H) +# if defined(SOCKET) || defined(USE_WINSOCK) # error "WinSock and lwIP TCP/IP stack definitions shall not coexist!" # endif #endif diff --git a/lib/inet_pton.h b/lib/inet_pton.h index 82fde7e2eb5..a6d161a9996 100644 --- a/lib/inet_pton.h +++ b/lib/inet_pton.h @@ -31,7 +31,7 @@ int Curl_inet_pton(int, const char *, void *); #ifdef HAVE_INET_PTON #ifdef HAVE_ARPA_INET_H #include -#elif defined(HAVE_WS2TCPIP_H) +#elif defined(USE_WINSOCK) /* inet_pton() exists in Vista or later */ #include #endif diff --git a/lib/setup-win32.h b/lib/setup-win32.h index 4e034d4bb21..d7e2e6be115 100644 --- a/lib/setup-win32.h +++ b/lib/setup-win32.h @@ -24,18 +24,53 @@ * ***************************************************************************/ +#undef USE_WINSOCK +/* ---------------------------------------------------------------- */ +/* Watt-32 TCP/IP SPECIFIC */ +/* ---------------------------------------------------------------- */ +#ifdef USE_WATT32 +# include +# undef byte +# undef word +# define HAVE_SYS_IOCTL_H +# define HAVE_SYS_SOCKET_H +# define HAVE_NETINET_IN_H +# define HAVE_NETDB_H +# define HAVE_ARPA_INET_H +# define SOCKET int +/* ---------------------------------------------------------------- */ +/* BSD-style lwIP TCP/IP stack SPECIFIC */ +/* ---------------------------------------------------------------- */ +#elif defined(USE_LWIPSOCK) + /* Define to use BSD-style lwIP TCP/IP stack. */ + /* #define USE_LWIPSOCK 1 */ +# undef HAVE_GETHOSTNAME +# undef LWIP_POSIX_SOCKETS_IO_NAMES +# undef RECV_TYPE_ARG1 +# undef RECV_TYPE_ARG3 +# undef SEND_TYPE_ARG1 +# undef SEND_TYPE_ARG3 +# define HAVE_GETHOSTBYNAME_R +# define HAVE_GETHOSTBYNAME_R_6 +# define LWIP_POSIX_SOCKETS_IO_NAMES 0 +# define RECV_TYPE_ARG1 int +# define RECV_TYPE_ARG3 size_t +# define SEND_TYPE_ARG1 int +# define SEND_TYPE_ARG3 size_t +#elif defined(_WIN32) +# define USE_WINSOCK 2 +#endif + /* * Include header files for windows builds before redefining anything. * Use this preprocessor block only to include or exclude windows.h, * winsock2.h or ws2tcpip.h. Any other windows thing belongs * to any other further and independent block. Under Cygwin things work * just as under linux (e.g. ) and the winsock headers should - * never be included when __CYGWIN__ is defined. configure script takes - * care of this, not defining HAVE_WINDOWS_H, HAVE_WINSOCK2_H, - * neither HAVE_WS2TCPIP_H when __CYGWIN__ is defined. + * never be included when __CYGWIN__ is defined. */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # if defined(UNICODE) && !defined(_UNICODE) # error "UNICODE is defined but _UNICODE is not defined" # endif @@ -53,12 +88,8 @@ # ifndef NOGDI # define NOGDI # endif -# ifdef HAVE_WINSOCK2_H -# include -# ifdef HAVE_WS2TCPIP_H -# include -# endif -# endif +# include +# include # include # include # include @@ -67,17 +98,6 @@ # endif #endif -/* - * Define USE_WINSOCK to 2 if we have and use WINSOCK2 API, else - * undefine USE_WINSOCK. - */ - -#undef USE_WINSOCK - -#ifdef HAVE_WINSOCK2_H -# define USE_WINSOCK 2 -#endif - /* * Define _WIN32_WINNT_[OS] symbols because not all Windows build systems have * those symbols to compare against, and even those that do may be missing diff --git a/m4/curl-compilers.m4 b/m4/curl-compilers.m4 index 5346321641e..7968a113a9a 100644 --- a/m4/curl-compilers.m4 +++ b/m4/curl-compilers.m4 @@ -194,7 +194,6 @@ AC_DEFUN([CURL_CHECK_COMPILER_GNU_C], [ flags_opt_all="-O -O0 -O1 -O2 -O3 -Os -Og -Ofast" flags_opt_yes="-O2" flags_opt_off="-O0" - CURL_CHECK_DEF([_WIN32], [], [silent]) else AC_MSG_RESULT([no]) fi @@ -1035,7 +1034,7 @@ AC_DEFUN([CURL_SET_COMPILER_WARNING_OPTS], [ dnl Only gcc 4.5 or later if test "$compiler_num" -ge "405"; then dnl Only windows targets - if test "$curl_cv_have_def__WIN32" = "yes"; then + if test "$curl_cv_native_windows" = "yes"; then tmp_CFLAGS="$tmp_CFLAGS -Wno-pedantic-ms-format" fi fi diff --git a/m4/curl-functions.m4 b/m4/curl-functions.m4 index a3275673a27..18147e4cac6 100644 --- a/m4/curl-functions.m4 +++ b/m4/curl-functions.m4 @@ -46,7 +46,7 @@ curl_includes_arpa_inet="\ #ifdef HAVE_ARPA_INET_H # include #endif -#ifdef HAVE_WINSOCK2_H +#ifdef _WIN32 #include #include #endif @@ -414,18 +414,15 @@ dnl included when winsock2.h is to be included. AC_DEFUN([CURL_INCLUDES_WINSOCK2], [ curl_includes_winsock2="\ /* 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 end */" - CURL_CHECK_HEADER_WINDOWS - CURL_CHECK_HEADER_WINSOCK2 + CURL_CHECK_NATIVE_WINDOWS ]) @@ -437,22 +434,16 @@ dnl included when ws2tcpip.h is to be included. AC_DEFUN([CURL_INCLUDES_WS2TCPIP], [ curl_includes_ws2tcpip="\ /* includes start */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # ifndef WIN32_LEAN_AND_MEAN # define WIN32_LEAN_AND_MEAN # endif -# ifdef HAVE_WINSOCK2_H -# include -# ifdef HAVE_WS2TCPIP_H -# include -# endif -# endif +# include +# include # include #endif /* includes end */" - CURL_CHECK_HEADER_WINDOWS - CURL_CHECK_HEADER_WINSOCK2 - CURL_CHECK_HEADER_WS2TCPIP + CURL_CHECK_NATIVE_WINDOWS ]) @@ -510,7 +501,7 @@ dnl defines function calling convention. AC_DEFUN([CURL_PREPROCESS_CALLCONV], [ curl_preprocess_callconv="\ /* preprocess start */ -#ifdef HAVE_WINDOWS_H +#ifdef _WIN32 # define FUNCALLCONV __stdcall #else # define FUNCALLCONV @@ -1794,7 +1785,7 @@ AC_DEFUN([CURL_CHECK_FUNC_GETADDRINFO], [ struct addrinfo *ai = 0; int error; - #ifdef HAVE_WINSOCK2_H + #ifdef _WIN32 WSADATA wsa; if(WSAStartup(MAKEWORD(2, 2), &wsa)) exit(2); From 6265718c77885d078a58a56d2174ecaab1cdbf23 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sun, 10 Dec 2023 02:19:32 +0000 Subject: [PATCH 047/509] system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers Align mingw with the other Windows compilers and use the `int` type for `CURL_TYPEOF_CURL_SOCKLEN_T` (and thus for `curl_socklent_t`). This makes it unnecessary to make a mingw-specific trick and pull all Windows headers early just for this type definition. This type is specific to Windows, not to the compiler. mingw-w64's Windows header maps it to `int` too. With this we also delete all remaining uses of `CURL_PULL_WS2TCPIP_H`. [ The official solution is to use `socklen_t` for all Windows compilers. In this case we may want to update `curl/curl.h` to pull in Windows headers before `system.h`. ] Reviewed-by: Daniel Stenberg Reviewed-by: Jay Satiro Closes #12501 --- CMakeLists.txt | 4 +--- include/curl/system.h | 12 +----------- 2 files changed, 2 insertions(+), 14 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 9f284bd9f1a..08c81451b9b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1387,9 +1387,7 @@ if(CMAKE_COMPILER_IS_GNUCC AND APPLE) endif() # TODO test which of these headers are required -if(WIN32) - set(CURL_PULL_WS2TCPIP_H 1) -else() +if(NOT WIN32) 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}) diff --git a/include/curl/system.h b/include/curl/system.h index f2554b4a90c..81a1b817df3 100644 --- a/include/curl/system.h +++ b/include/curl/system.h @@ -184,9 +184,8 @@ # define CURL_FORMAT_CURL_OFF_TU PRIu64 # define CURL_SUFFIX_CURL_OFF_T LL # define CURL_SUFFIX_CURL_OFF_TU ULL -# define CURL_TYPEOF_CURL_SOCKLEN_T socklen_t +# define CURL_TYPEOF_CURL_SOCKLEN_T int # define CURL_PULL_SYS_TYPES_H 1 -# define CURL_PULL_WS2TCPIP_H 1 #elif defined(__VMS) # if defined(__VAX) @@ -417,15 +416,6 @@ #define CURL_PULL_SYS_POLL_H #endif - -/* CURL_PULL_WS2TCPIP_H is defined above when inclusion of header file */ -/* ws2tcpip.h is required here to properly make type definitions below. */ -#ifdef CURL_PULL_WS2TCPIP_H -# include -# include -# include -#endif - /* CURL_PULL_SYS_TYPES_H is defined above when inclusion of header file */ /* sys/types.h is required here to properly make type definitions below. */ #ifdef CURL_PULL_SYS_TYPES_H From ee6992c66a3dd7a1a1e2fbf66ba8d446a28acc8c Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 11 Dec 2023 17:28:35 +0000 Subject: [PATCH 048/509] build: remove redundant `CURL_PULL_*` settings These macros were not propagated to the source code from CMake. autotools set only one of them (`CURL_PULL_SYS_POLL_H`), initially to address an AIX issue [1]. This later broke when introducing `system.h` [2] without the logic it enabled. A subsequent fix [3] re-added the logic, and also enabled it for AIX before its use, directly in `system.h`. [1] 2012-11-23: 665adcd4b7bcdb7deb638cdc499fbe71f8d777f2 [2] 2017-03-29: 9506d01ee50d5908138ebad0fd9fbd39b66bd64d #1373 [3] 2017-08-25: 8a84fcc4b59e8b78d2acc6febf44a43d6bc81b59 #1828 #1833 Reviewed-by: Daniel Stenberg Closes #12502 --- CMakeLists.txt | 7 ------- acinclude.m4 | 35 ----------------------------------- configure.ac | 2 -- 3 files changed, 44 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 08c81451b9b..b1f3e27d655 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1386,13 +1386,6 @@ if(CMAKE_COMPILER_IS_GNUCC AND APPLE) endif() endif() -# TODO test which of these headers are required -if(NOT WIN32) - 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) diff --git a/acinclude.m4 b/acinclude.m4 index df80d693a52..96187ade14e 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 @@ -1116,40 +1115,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 ------------------------------------------------- diff --git a/configure.ac b/configure.ac index 810e3562bd8..536198369ab 100644 --- a/configure.ac +++ b/configure.ac @@ -3500,8 +3500,6 @@ CURL_RUN_IFELSE( AC_MSG_RESULT([no]) ]) -CURL_CONFIGURE_PULL_SYS_POLL - TYPE_IN_ADDR_T TYPE_SOCKADDR_STORAGE From 423645a1ef34526d424e48d23f573e7a5137c88f Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 7 Nov 2023 00:25:18 +0000 Subject: [PATCH 049/509] build: delete unused `HAVE_{GSSHEIMDAL,GSSMIT,HEIMDAL}` Stop setting `HAVE_GSSHEIMDAL`, `HAVE_GSSMIT` and `HAVE_HEIMDAL`. There was no place in the build system or source code that used them. Reviewed-by: Daniel Stenberg Closes #12506 --- CMakeLists.txt | 6 ++---- configure.ac | 6 +----- lib/config-os400.h | 6 ------ lib/curl_config.h.cmake | 6 ------ packages/vms/config_h.com | 32 -------------------------------- 5 files changed, 3 insertions(+), 53 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index b1f3e27d655..3a6ae3d42a7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -907,10 +907,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") diff --git a/configure.ac b/configure.ac index 536198369ab..e809502dfa8 100644 --- a/configure.ac +++ b/configure.ac @@ -1828,10 +1828,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 @@ -1840,7 +1837,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([ diff --git a/lib/config-os400.h b/lib/config-os400.h index 357a36458b7..32852bb378b 100644 --- a/lib/config-os400.h +++ b/lib/config-os400.h @@ -116,12 +116,6 @@ /* Define if you have the GNU gssapi libraries */ #undef HAVE_GSSGNU -/* Define if you have the Heimdal gssapi libraries */ -#define HAVE_GSSHEIMDAL - -/* Define if you have the MIT gssapi libraries */ -#undef HAVE_GSSMIT - /* Define if you need the malloc.h header file even with stdlib.h */ /* #define NEED_MALLOC_H 1 */ diff --git a/lib/curl_config.h.cmake b/lib/curl_config.h.cmake index 8c824721aab..8b3015d6114 100644 --- a/lib/curl_config.h.cmake +++ b/lib/curl_config.h.cmake @@ -298,12 +298,6 @@ /* if you have the GNU gssapi libraries */ #cmakedefine HAVE_GSSGNU 1 -/* if you have the Heimdal gssapi libraries */ -#cmakedefine HAVE_GSSHEIMDAL 1 - -/* if you have the MIT gssapi libraries */ -#cmakedefine HAVE_GSSMIT 1 - /* Define to 1 if you have the `idna_strerror' function. */ #cmakedefine HAVE_IDNA_STRERROR 1 diff --git a/packages/vms/config_h.com b/packages/vms/config_h.com index 6e4e0396360..6378802ad84 100644 --- a/packages/vms/config_h.com +++ b/packages/vms/config_h.com @@ -1386,38 +1386,6 @@ $ write tf "#define ''key2' 1" $ write tf "#endif" $ goto cfgh_in_loop1 $ endif -$! -$! This is really do we have the newer MIT Kerberos -$!---------------------------------------------------------------------- -$ if (key2 .eqs. "HAVE_GSSMIT") -$ then -$ if f$search(test_mit) .nes. "" -$ then -$ write tf "#ifndef ''key2'" -$ write tf "#define ''key2' 1" -$ else -$ write tf "#ifdef ''key2'" -$ write tf "#undef ''key2'" -$ endif -$ write tf "#endif" -$ goto cfgh_in_loop1 -$ endif -$! -$! Older MIT looks like Heimdal -$!------------------------------------------------ -$ if (key2 .eqs. "HAVE_HEIMDAL") -$ then -$ if f$search(test_mit) .eqs. "" -$ then -$ write tf "#ifndef ''key2'" -$ write tf "#define ''key2' 1" -$ else -$ write tf "#ifdef ''key2'" -$ write tf "#undef ''key2'" -$ endif -$ write tf "#endif" -$ goto cfgh_in_loop1 -$ endif $ endif $! $ endif From af520ac9fec7d88e942f05fdcd90704adb9fa566 Mon Sep 17 00:00:00 2001 From: Baruch Siach Date: Mon, 11 Dec 2023 20:45:01 +0200 Subject: [PATCH 050/509] gnutls: fix build with --disable-verbose infof() parameters must be defined event with --disable-verbose since commit dac293cfb702 ("lib: apache style infof and trace macros/functions"). Move also 'ptr' definition under !CURL_DISABLE_VERBOSE_STRINGS. Fixes the following build failure: In file included from ../lib/sendf.h:29, from vtls/gtls.c:44: vtls/gtls.c: In function 'Curl_gtls_verifyserver': vtls/gtls.c:841:34: error: 'version' undeclared (first use in this function); did you mean 'session'? 841 | gnutls_protocol_get_name(version), ptr); | ^~~~~~~ Closes #12505 --- lib/vtls/gtls.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/vtls/gtls.c b/lib/vtls/gtls.c index f42b6d6691d..b95c5be3c5e 100644 --- a/lib/vtls/gtls.c +++ b/lib/vtls/gtls.c @@ -818,16 +818,17 @@ Curl_gtls_verifyserver(struct Curl_easy *data, char certname[65] = ""; /* limited to 64 chars by ASN.1 */ size_t size; time_t certclock; - const char *ptr; int rc; CURLcode result = CURLE_OK; #ifndef CURL_DISABLE_VERBOSE_STRINGS + const char *ptr; unsigned int algo; unsigned int bits; gnutls_protocol_t version = gnutls_protocol_get_version(session); #endif long * const certverifyresult = &ssl_config->certverifyresult; +#ifndef CURL_DISABLE_VERBOSE_STRINGS /* the name of the cipher suite used, e.g. ECDHE_RSA_AES_256_GCM_SHA384. */ ptr = gnutls_cipher_suite_get_name(gnutls_kx_get(session), gnutls_cipher_get(session), @@ -835,6 +836,7 @@ Curl_gtls_verifyserver(struct Curl_easy *data, infof(data, "SSL connection using %s / %s", gnutls_protocol_get_name(version), ptr); +#endif /* This function will return the peer's raw certificate (chain) as sent by the peer. These certificates are in raw format (DER encoded for From b29d1e887f25a830a8f69a15d20faa676b6ce07d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 16 Dec 2023 22:17:06 +0100 Subject: [PATCH 051/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 70 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 5 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index a673f1106e6..bafcfd15a00 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -1,21 +1,50 @@ curl and libcurl 8.5.1 - Public curl releases: 253 + Public curl releases: 254 Command line options: 258 curl_easy_setopt() options: 303 Public functions in libcurl: 93 - Contributors: 3042 + Contributors: 3046 This release includes the following changes: This release includes the following bugfixes: + o build: delete unused `HAVE_{GSSHEIMDAL,GSSMIT,HEIMDAL}` [4] + o build: enable missing OpenSSF-recommended warnings, with fixes [11] + o build: fix Windows ADDRESS_FAMILY detection [35] + o build: remove redundant `CURL_PULL_*` settings [8] + o CI/distcheck: run full tests [31] o cmake: fix typo [5] + o cmdline-docs: use .IP consistently [13] + o cmdline/gen: fix the sorting of the man page options [33] + o cookie: avoid fopen with empty file name [24] + o curl: show ipfs and ipns as supported "protocols" [15] o dist: add tests/errorcodes.pl to the tarball [6] + o docs: clean up Protocols: for cmdline options [32] + o doh: remove unused local variable [34] + o ftp: handle the PORT parsing without allocation [44] + o gnutls: fix build with --disable-verbose [3] + o hostip: return error immediately when Curl_ip2addr() fails [19] + o http: fix off-by-one error in request method length check [14] o lib: fix variable undeclared error caused by `infof` changes [2] + o lib: reduce use of strncpy [30] + o lib: rename Curl_strndup to Curl_memdup0 to avoid misunderstanding [36] + o lib: strndup/memdup instead of malloc, memcpy and null-terminate [42] + o libssh: improve the deprecation warning dismissal [20] + o libssh: supress warnings without version check [18] + o Makefile.mk: drop Windows support [12] + o openssl: re-match LibreSSL deinit with init [17] + o readwrite_data: loop less [21] + o Revert "urldata: move async resolver state from easy handle to connectdata" [16] o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] + o sendf: fix compiler warning with CURL_DISABLE_HEADERS_API [38] + o system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers [9] + o tests/server: delete workaround for old-mingw [25] o url: for disabled protocols, mention if found in redirect [7] + o vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY [41] + o windows: simplify detecting and using system headers [10] This release includes the following known bugs: @@ -30,14 +59,45 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - Cajus Pollmeier, Chris Sauer, Dan Fandrich, Daniel Stenberg, - Mauricio Scheffer, Stefan Eissing, Viktor Szakats, Xi Ruoyao, YX Hao - (9 contributors) + Baruch Siach, Ben, Boris Verkhovskiy, Cajus Pollmeier, Chara White, + Chris Sauer, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, Dmitry Karpov, + Mauricio Scheffer, Michał Antoniak, Mike Hommey, Ray Satiro, Stefan Eissing, + Tatsuhiko Miyagawa, Theo, Viktor Szakats, Xi Ruoyao, YX Hao + (20 contributors) References to bug reports and discussions on issues: [1] = https://curl.se/bug/?i=12474 [2] = https://curl.se/bug/?i=12470 + [3] = https://curl.se/bug/?i=12505 + [4] = https://curl.se/bug/?i=12506 [5] = https://curl.se/bug/?i=12464 [6] = https://curl.se/bug/?i=12462 [7] = https://curl.se/bug/?i=12466 + [8] = https://curl.se/bug/?i=12502 + [9] = https://curl.se/bug/?i=12501 + [10] = https://curl.se/bug/?i=12495 + [11] = https://curl.se/bug/?i=12489 + [12] = https://curl.se/bug/?i=12224 + [13] = https://curl.se/bug/?i=12535 + [14] = https://curl.se/bug/?i=12534 + [15] = https://curl.se/mail/archive-2023-12/0026.html + [16] = https://curl.se/bug/?i=12524 + [17] = https://curl.se/bug/?i=12525 + [18] = https://curl.se/bug/?i=12523 + [19] = https://curl.se/bug/?i=12522 + [20] = https://curl.se/bug/?i=12519 + [21] = https://curl.se/bug/?i=12504 + [24] = https://curl.se/bug/?i=12514 + [25] = https://curl.se/bug/?i=12510 + [30] = https://curl.se/bug/?i=12499 + [31] = https://curl.se/bug/?i=12503 + [32] = https://curl.se/bug/?i=12496 + [33] = https://curl.se/mail/archive-2023-12/0014.html + [34] = https://curl.se/bug/?i=12491 + [35] = https://curl.se/bug/?i=12441 + [36] = https://curl.se/bug/?i=12490 + [38] = https://curl.se/bug/?i=12485 + [41] = https://curl.se/bug/?i=12459 + [42] = https://curl.se/bug/?i=12453 + [44] = https://curl.se/bug/?i=12456 From a86254b39307af1a53735b065a382567805cd9b8 Mon Sep 17 00:00:00 2001 From: Mark Sinkovics Date: Wed, 13 Dec 2023 19:49:55 -0500 Subject: [PATCH 052/509] cmake: fix generation for system name iOS This PR fixes a problem that happens during CMake configuration when the `CMAKE_SYSTEM_NAME` set to `iOS` and not `Darwin`. This value is available (as far as I remember) version 3.14. The final solution (thanks to @vszakats) is to use `APPLE` which contains all the Apple platforms https://cmake.org/cmake/help/latest/variable/APPLE.html. This issue was found when during vcpkg installation. Running command `vcpkg install curl:arm64-ios` and `vcpkg install curl:x64-ios` failed with message: ``` CMake Error: try_run() invoked in cross-compiling mode, please set the following cache variables appropriately: HAVE_H_ERRNO_ASSIGNABLE_EXITCODE (advanced) ``` After this fix, I was able to compile the compile the binary without any issue. In addition to that fix, this PR also contains an simplification to check if the platform is not APPLE. Co-authored-by: Viktor Szakats Closes #12515 --- CMake/OtherTests.cmake | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CMake/OtherTests.cmake b/CMake/OtherTests.cmake index f769b954777..cf0bae6b980 100644 --- a/CMake/OtherTests.cmake +++ b/CMake/OtherTests.cmake @@ -80,7 +80,7 @@ endif() unset(CMAKE_TRY_COMPILE_TARGET_TYPE) if(NOT CMAKE_CROSSCOMPILING) - if(NOT ${CMAKE_SYSTEM_NAME} MATCHES "Darwin" AND NOT ${CMAKE_SYSTEM_NAME} MATCHES "iOS") + if(NOT APPLE) # only try this on non-apple platforms # if not cross-compilation... @@ -133,8 +133,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 From 17e61d4e3a50dfbfbcc9c2867f387d160205328b Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 12 Dec 2023 21:46:58 +0000 Subject: [PATCH 053/509] cmake: whitespace tidy-up in `OtherTests.cmake` Closes #12538 --- CMake/OtherTests.cmake | 62 ++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/CMake/OtherTests.cmake b/CMake/OtherTests.cmake index cf0bae6b980..a7599c44d7f 100644 --- a/CMake/OtherTests.cmake +++ b/CMake/OtherTests.cmake @@ -46,7 +46,8 @@ endif() set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) check_c_source_compiles("${_source_epilogue} - int main(void) { + int main(void) + { int flag = MSG_NOSIGNAL; (void)flag; return 0; @@ -56,14 +57,15 @@ if(NOT WIN32) 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) + #include + int main(void) + { + struct timeval ts; + ts.tv_sec = 0; + ts.tv_usec = 0; + (void)ts; + return 0; + }" HAVE_STRUCT_TIMEVAL) if(NOT WIN32) set(CMAKE_EXTRA_INCLUDE_FILES) @@ -102,28 +104,28 @@ if(NOT CMAKE_CROSSCOMPILING) 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; - } + 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) + } + return 0; + }" HAVE_POLL_FINE) endif() endif() From 15b09d93439525b5a4210620dba4e695a5ff3102 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sun, 17 Dec 2023 12:29:26 +0000 Subject: [PATCH 054/509] ssh: fix namespace of two local macros Avoid using the libssh and libssh2 macro namespaces by prefixing these local macro names with `CURL_`. Follow-up to 413a0fedd02c8c6df1d294534b8c6e306fcca7a2 #12346 Reviewed-by: Daniel Stenberg Closes #12544 --- lib/vssh/libssh.c | 26 +++++++++++++------------- lib/vssh/libssh2.c | 26 +++++++++++++------------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index cf9b1eb9059..18b3d67fb6a 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -1151,22 +1151,22 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) } else if(statvfs) { #ifdef _MSC_VER - #define LIBSSH_VFS_SIZE_MASK "I64u" + #define CURL_LIBSSH_VFS_SIZE_MASK "I64u" #else - #define LIBSSH_VFS_SIZE_MASK PRIu64 + #define CURL_LIBSSH_VFS_SIZE_MASK PRIu64 #endif char *tmp = aprintf("statvfs:\n" - "f_bsize: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_frsize: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_blocks: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_bfree: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_bavail: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_files: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_ffree: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_favail: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_fsid: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_flag: %" LIBSSH_VFS_SIZE_MASK "\n" - "f_namemax: %" LIBSSH_VFS_SIZE_MASK "\n", + "f_bsize: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_frsize: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_blocks: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_bfree: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_bavail: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_files: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_ffree: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_favail: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_fsid: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_flag: %" CURL_LIBSSH_VFS_SIZE_MASK "\n" + "f_namemax: %" CURL_LIBSSH_VFS_SIZE_MASK "\n", statvfs->f_bsize, statvfs->f_frsize, statvfs->f_blocks, statvfs->f_bfree, statvfs->f_bavail, statvfs->f_files, diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index 83e09906a8f..a751d7cd3a7 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -1959,22 +1959,22 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) } else if(rc == 0) { #ifdef _MSC_VER - #define LIBSSH2_VFS_SIZE_MASK "I64u" + #define CURL_LIBSSH2_VFS_SIZE_MASK "I64u" #else - #define LIBSSH2_VFS_SIZE_MASK "llu" + #define CURL_LIBSSH2_VFS_SIZE_MASK "llu" #endif char *tmp = aprintf("statvfs:\n" - "f_bsize: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_frsize: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_blocks: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_bfree: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_bavail: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_files: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_ffree: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_favail: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_fsid: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_flag: %" LIBSSH2_VFS_SIZE_MASK "\n" - "f_namemax: %" LIBSSH2_VFS_SIZE_MASK "\n", + "f_bsize: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_frsize: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_blocks: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_bfree: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_bavail: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_files: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_ffree: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_favail: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_fsid: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_flag: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n" + "f_namemax: %" CURL_LIBSSH2_VFS_SIZE_MASK "\n", statvfs.f_bsize, statvfs.f_frsize, statvfs.f_blocks, statvfs.f_bfree, statvfs.f_bavail, statvfs.f_files, From ad50d8104ca40f5fa9a950c2fe461ef937a7e7f0 Mon Sep 17 00:00:00 2001 From: Yedaya Katsman Date: Sun, 17 Dec 2023 22:04:25 +0200 Subject: [PATCH 055/509] tests: respect $TMPDIR when creating unix domain sockets When running on termux, where $TMPDIR isn't /tmp, running the tests failed, since the server config tried creating sockets in /tmp, without checking the temp dir config. Use the TMPDIR variable that makes it find the correct directory everywhere [0] [0] https://perldoc.perl.org/File::Temp#tempfile Closes #12545 --- tests/servers.pm | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/servers.pm b/tests/servers.pm index 9416ba75884..d4472d509bd 100644 --- a/tests/servers.pm +++ b/tests/servers.pm @@ -190,10 +190,10 @@ use File::Temp qw/ tempfile/; ####################################################################### # Initialize configuration variables sub initserverconfig { - my ($fh, $socks) = tempfile("/tmp/curl-socksd-XXXXXXXX"); + my ($fh, $socks) = tempfile("curl-socksd-XXXXXXXX", TMPDIR => 1); close($fh); unlink($socks); - my ($f2, $http) = tempfile("/tmp/curl-http-XXXXXXXX"); + my ($f2, $http) = tempfile("curl-http-XXXXXXXX", TMPDIR => 1); close($f2); unlink($http); $SOCKSUNIXPATH = $socks; # SOCKS Unix domain socket From b7258e49225750bb183acdc3e35fac3a66729eb7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 18 Dec 2023 09:34:39 +0100 Subject: [PATCH 056/509] CI/circleci: disable MQTT in the HTTP-only build And remove the use of configure options that don't actually exist Closes #12546 --- .circleci/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index fc4f5052502..7877d247a26 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -96,7 +96,7 @@ commands: - 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: From f58e493e44ad2f17bb574a4ccc5d47134e6f515f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 18 Dec 2023 10:34:17 +0100 Subject: [PATCH 057/509] curl.h: add CURLE_TOO_LARGE A new error code to be used when an internal field grows too large, like when a dynbuf reaches its maximum. Previously it would return CURLE_OUT_OF_MEMORY for this, which is highly misleading. Ref: #12268 Closes #12269 --- docs/libcurl/libcurl-errors.3 | 4 + docs/libcurl/symbols-in-versions | 2 + include/curl/curl.h | 1 + include/curl/urlapi.h | 1 + lib/c-hyper.c | 2 +- lib/curl_printf.h | 4 + lib/dynbuf.c | 7 +- lib/http.c | 27 +++--- lib/mprintf.c | 22 ++--- lib/strerror.c | 6 ++ lib/urlapi.c | 137 +++++++++++++++++-------------- tests/data/test1154 | 4 +- tests/data/test1538 | 6 +- 13 files changed, 132 insertions(+), 91 deletions(-) diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 03f18e6b538..cd7bd9a3df3 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -288,6 +288,8 @@ the specific problem. SSL Client Certificate required. .IP "CURLE_UNRECOVERABLE_POLL (99)" An internal call to poll() or select() returned error that is not recoverable. +.IP "CURLE_TOO_LARGE (100)" +A value or data field grew larger than allowed. .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. Also consider \fIcurl_multi_strerror(3)\fP. @@ -410,6 +412,8 @@ The URL contained an invalid number of slashes. The user part of the URL contained bad or invalid characters. .IP "CURLUE_LACKS_IDN (30)" libcurl lacks IDN support. +.IP "CURLUE_TOO_LARGE (31)" +A value or data field is larger than allowed. .SH "CURLHcode" The header interface returns a \fICURLHcode\fP to indicate when an error has occurred. diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index dc0e0629f09..179ba11025f 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -328,6 +328,7 @@ CURLE_TFTP_NOSUCHUSER 7.15.0 CURLE_TFTP_NOTFOUND 7.15.0 CURLE_TFTP_PERM 7.15.0 CURLE_TFTP_UNKNOWNID 7.15.0 +CURLE_TOO_LARGE 8.6.0 CURLE_TOO_MANY_REDIRECTS 7.5 CURLE_UNKNOWN_OPTION 7.21.5 CURLE_UNKNOWN_TELNET_OPTION 7.7 7.21.5 @@ -1094,6 +1095,7 @@ CURLUE_NO_USER 7.62.0 CURLUE_NO_ZONEID 7.81.0 CURLUE_OK 7.62.0 CURLUE_OUT_OF_MEMORY 7.62.0 +CURLUE_TOO_LARGE 8.6.0 CURLUE_UNKNOWN_PART 7.62.0 CURLUE_UNSUPPORTED_SCHEME 7.62.0 CURLUE_URLDECODE 7.62.0 diff --git a/include/curl/curl.h b/include/curl/curl.h index cc24c05065f..ab600b83c37 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -631,6 +631,7 @@ typedef enum { CURLE_PROXY, /* 97 - proxy handshake error */ CURLE_SSL_CLIENTCERT, /* 98 - client-side certificate required */ CURLE_UNRECOVERABLE_POLL, /* 99 - poll/select returned fatal error */ + CURLE_TOO_LARGE, /* 100 - a value/data met its maximum */ CURL_LAST /* never use! */ } CURLcode; diff --git a/include/curl/urlapi.h b/include/curl/urlapi.h index 88cdeb3bca6..91f8c4548aa 100644 --- a/include/curl/urlapi.h +++ b/include/curl/urlapi.h @@ -63,6 +63,7 @@ typedef enum { CURLUE_BAD_SLASHES, /* 28 */ CURLUE_BAD_USER, /* 29 */ CURLUE_LACKS_IDN, /* 30 */ + CURLUE_TOO_LARGE, /* 31 */ CURLUE_LAST } CURLUcode; diff --git a/lib/c-hyper.c b/lib/c-hyper.c index 787d6bbdbe0..c4a395f0e92 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -148,7 +148,7 @@ static int hyper_each_header(void *userdata, if(name_len + value_len + 2 > CURL_MAX_HTTP_HEADER) { failf(data, "Too long response header"); - data->state.hresult = CURLE_OUT_OF_MEMORY; + data->state.hresult = CURLE_TOO_LARGE; return HYPER_ITER_BREAK; } diff --git a/lib/curl_printf.h b/lib/curl_printf.h index 46ef344f76e..c2457d2a649 100644 --- a/lib/curl_printf.h +++ b/lib/curl_printf.h @@ -31,6 +31,10 @@ #include +#define MERR_OK 0 +#define MERR_MEM 1 +#define MERR_TOO_LARGE 2 + # undef printf # undef fprintf # undef msnprintf diff --git a/lib/dynbuf.c b/lib/dynbuf.c index a20266a681b..a6a71c5daa8 100644 --- a/lib/dynbuf.c +++ b/lib/dynbuf.c @@ -81,7 +81,7 @@ static CURLcode dyn_nappend(struct dynbuf *s, if(fit > s->toobig) { Curl_dyn_free(s); - return CURLE_OUT_OF_MEMORY; + return CURLE_TOO_LARGE; } else if(!a) { DEBUGASSERT(!indx); @@ -199,6 +199,9 @@ CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap) if(!rc) return CURLE_OK; + else if(rc == MERR_TOO_LARGE) + return CURLE_TOO_LARGE; + return CURLE_OUT_OF_MEMORY; #else char *str; #ifdef __clang__ @@ -217,8 +220,8 @@ CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap) } /* If we failed, we cleanup the whole buffer and return error */ Curl_dyn_free(s); + return CURLE_OK; #endif - return CURLE_OUT_OF_MEMORY; } /* diff --git a/lib/http.c b/lib/http.c index 582cb1cdbcf..5b8f3e54b01 100644 --- a/lib/http.c +++ b/lib/http.c @@ -3179,7 +3179,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) ) { result = Curl_http2_switch(data, conn, FIRSTSOCKET); if(result) - return result; + goto fail; } else #endif @@ -3194,7 +3194,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) DEBUGF(infof(data, "HTTP/2 over clean TCP")); result = Curl_http2_switch(data, conn, FIRSTSOCKET); if(result) - return result; + goto fail; } break; } @@ -3204,11 +3204,11 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) result = Curl_http_host(data, conn); if(result) - return result; + goto fail; result = Curl_http_useragent(data); if(result) - return result; + goto fail; Curl_http_method(data, conn, &request, &httpreq); @@ -3224,7 +3224,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) (pq ? pq : data->state.up.path), FALSE); free(pq); if(result) - return result; + goto fail; } Curl_safefree(data->state.aptr.ref); @@ -3249,23 +3249,23 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) /* we only consider transfer-encoding magic if libz support is built-in */ result = Curl_transferencode(data); if(result) - return result; + goto fail; #endif result = Curl_http_body(data, conn, httpreq, &te); if(result) - return result; + goto fail; p_accept = Curl_checkheaders(data, STRCONST("Accept"))?NULL:"Accept: */*\r\n"; result = Curl_http_resume(data, conn, httpreq); if(result) - return result; + goto fail; result = Curl_http_range(data, httpreq); if(result) - return result; + goto fail; httpstring = get_http_string(data, conn); @@ -3283,7 +3283,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) result = Curl_http_target(data, conn, &req); if(result) { Curl_dyn_free(&req); - return result; + goto fail; } #ifndef CURL_DISABLE_ALTSVC @@ -3354,7 +3354,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) if(result) { Curl_dyn_free(&req); - return result; + goto fail; } if(!(conn->handler->flags&PROTOPT_SSL) && @@ -3390,7 +3390,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) } if(result) { Curl_dyn_free(&req); - return result; + goto fail; } if((http->postsize > -1) && @@ -3426,6 +3426,9 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) but is disabled here again to avoid that the chunked encoded version is actually used when sending the request body over h2 */ data->req.upload_chunky = FALSE; +fail: + if(CURLE_TOO_LARGE == result) + failf(data, "HTTP request too large"); return result; } diff --git a/lib/mprintf.c b/lib/mprintf.c index 60cf531486a..514fdc87a86 100644 --- a/lib/mprintf.c +++ b/lib/mprintf.c @@ -39,6 +39,7 @@ #include "curl_setup.h" #include "dynbuf.h" +#include "curl_printf.h" #include #include "curl_memory.h" @@ -169,8 +170,7 @@ struct nsprintf { struct asprintf { struct dynbuf *b; - bool fail; /* if an alloc has failed and thus the output is not the complete - data */ + char merr; }; static long dprintf_DollarString(char *input, char **end) @@ -1062,25 +1062,27 @@ static int alloc_addbyter(int output, FILE *data) { struct asprintf *infop = (struct asprintf *)data; unsigned char outc = (unsigned char)output; + CURLcode result; - if(Curl_dyn_addn(infop->b, &outc, 1)) { - infop->fail = 1; + result = Curl_dyn_addn(infop->b, &outc, 1); + if(result) { + infop->merr = result == CURLE_TOO_LARGE ? MERR_TOO_LARGE : MERR_MEM; return -1; /* fail */ } return outc; /* fputc() returns like this on success */ } -/* appends the formatted string, returns 0 on success, 1 on error */ +/* appends the formatted string, returns MERR error code */ int Curl_dyn_vprintf(struct dynbuf *dyn, const char *format, va_list ap_save) { struct asprintf info; info.b = dyn; - info.fail = 0; + info.merr = MERR_OK; (void)dprintf_formatf(&info, alloc_addbyter, format, ap_save); - if(info.fail) { + if(info.merr) { Curl_dyn_free(info.b); - return 1; + return info.merr; } return 0; } @@ -1091,10 +1093,10 @@ char *curl_mvaprintf(const char *format, va_list ap_save) struct dynbuf dyn; info.b = &dyn; Curl_dyn_init(info.b, DYN_APRINTF); - info.fail = 0; + info.merr = MERR_OK; (void)dprintf_formatf(&info, alloc_addbyter, format, ap_save); - if(info.fail) { + if(info.merr) { Curl_dyn_free(info.b); return NULL; } diff --git a/lib/strerror.c b/lib/strerror.c index 51e1485408e..e35193a48c2 100644 --- a/lib/strerror.c +++ b/lib/strerror.c @@ -319,6 +319,9 @@ curl_easy_strerror(CURLcode error) case CURLE_UNRECOVERABLE_POLL: return "Unrecoverable error in select/poll"; + case CURLE_TOO_LARGE: + return "A value or data field grew larger than allowed"; + /* error codes not used by current libcurl */ case CURLE_OBSOLETE20: case CURLE_OBSOLETE24: @@ -553,6 +556,9 @@ curl_url_strerror(CURLUcode error) case CURLUE_LACKS_IDN: return "libcurl lacks IDN support"; + case CURLUE_TOO_LARGE: + return "A value or data field is larger than allowed"; + case CURLUE_LAST: break; } diff --git a/lib/urlapi.c b/lib/urlapi.c index 56ee16f055f..b9ea68eac54 100644 --- a/lib/urlapi.c +++ b/lib/urlapi.c @@ -126,6 +126,9 @@ static const char *find_host_sep(const char *url) return sep < query ? sep : query; } +/* convert CURLcode to CURLUcode */ +#define cc2cu(x) ((x) == CURLE_TOO_LARGE ? CURLUE_TOO_LARGE : \ + CURLUE_OUT_OF_MEMORY) /* * Decide whether a character in a URL must be escaped. */ @@ -146,6 +149,7 @@ static CURLUcode urlencode_str(struct dynbuf *o, const char *url, bool left = !query; const unsigned char *iptr; const unsigned char *host_sep = (const unsigned char *) url; + CURLcode result; if(!relative) host_sep = (const unsigned char *) find_host_sep(url); @@ -154,20 +158,19 @@ static CURLUcode urlencode_str(struct dynbuf *o, const char *url, len; iptr++, len--) { if(iptr < host_sep) { - if(Curl_dyn_addn(o, iptr, 1)) - return CURLUE_OUT_OF_MEMORY; + result = Curl_dyn_addn(o, iptr, 1); + if(result) + return cc2cu(result); continue; } if(*iptr == ' ') { - if(left) { - if(Curl_dyn_addn(o, "%20", 3)) - return CURLUE_OUT_OF_MEMORY; - } - else { - if(Curl_dyn_addn(o, "+", 1)) - return CURLUE_OUT_OF_MEMORY; - } + if(left) + result = Curl_dyn_addn(o, "%20", 3); + else + result = Curl_dyn_addn(o, "+", 1); + if(result) + return cc2cu(result); continue; } @@ -178,13 +181,12 @@ static CURLUcode urlencode_str(struct dynbuf *o, const char *url, char out[3]={'%'}; out[1] = hexdigits[*iptr>>4]; out[2] = hexdigits[*iptr & 0xf]; - if(Curl_dyn_addn(o, out, 3)) - return CURLUE_OUT_OF_MEMORY; - } - else { - if(Curl_dyn_addn(o, iptr, 1)) - return CURLUE_OUT_OF_MEMORY; + result = Curl_dyn_addn(o, out, 3); } + else + result = Curl_dyn_addn(o, iptr, 1); + if(result) + return cc2cu(result); } return CURLUE_OK; @@ -248,7 +250,7 @@ size_t Curl_is_absolute_url(const char *url, char *buf, size_t buflen, * * Note that this function destroys the 'base' string. */ -static char *concat_url(char *base, const char *relurl) +static CURLcode concat_url(char *base, const char *relurl, char **newurl) { /*** TRY to append this new path to the old URL @@ -260,6 +262,9 @@ static char *concat_url(char *base, const char *relurl) char *pathsep; bool host_changed = FALSE; const char *useurl = relurl; + CURLcode result = CURLE_OK; + CURLUcode uc; + *newurl = NULL; /* protsep points to the start of the host name */ protsep = strstr(base, "//"); @@ -360,21 +365,27 @@ static char *concat_url(char *base, const char *relurl) Curl_dyn_init(&newest, CURL_MAX_INPUT_LENGTH); /* copy over the root url part */ - if(Curl_dyn_add(&newest, base)) - return NULL; + result = Curl_dyn_add(&newest, base); + if(result) + return result; /* check if we need to append a slash */ if(('/' == useurl[0]) || (protsep && !*protsep) || ('?' == useurl[0])) ; else { - if(Curl_dyn_addn(&newest, "/", 1)) - return NULL; + result = Curl_dyn_addn(&newest, "/", 1); + if(result) + return result; } /* then append the new piece on the right side */ - urlencode_str(&newest, useurl, strlen(useurl), !host_changed, FALSE); + uc = urlencode_str(&newest, useurl, strlen(useurl), !host_changed, + FALSE); + if(uc) + return (uc == CURLUE_TOO_LARGE) ? CURLE_TOO_LARGE : CURLE_OUT_OF_MEMORY; - return Curl_dyn_ptr(&newest); + *newurl = Curl_dyn_ptr(&newest); + return CURLE_OK; } /* scan for byte values <= 31, 127 and sometimes space */ @@ -775,7 +786,7 @@ static CURLUcode urldecode_host(struct dynbuf *host) result = Curl_dyn_addn(host, decoded, dlen); free(decoded); if(result) - return CURLUE_OUT_OF_MEMORY; + return cc2cu(result); } return CURLUE_OK; @@ -788,22 +799,24 @@ static CURLUcode parse_authority(struct Curl_URL *u, bool has_scheme) { size_t offset; - CURLUcode result; + CURLUcode uc; + CURLcode result; /* * Parse the login details and strip them out of the host name. */ - result = parse_hostname_login(u, auth, authlen, flags, &offset); - if(result) + uc = parse_hostname_login(u, auth, authlen, flags, &offset); + if(uc) goto out; - if(Curl_dyn_addn(host, auth + offset, authlen - offset)) { - result = CURLUE_OUT_OF_MEMORY; + result = Curl_dyn_addn(host, auth + offset, authlen - offset); + if(result) { + uc = cc2cu(result); goto out; } - result = Curl_parse_port(u, host, has_scheme); - if(result) + uc = Curl_parse_port(u, host, has_scheme); + if(uc) goto out; if(!Curl_dyn_len(host)) @@ -813,24 +826,24 @@ static CURLUcode parse_authority(struct Curl_URL *u, case HOST_IPV4: break; case HOST_IPV6: - result = ipv6_parse(u, Curl_dyn_ptr(host), Curl_dyn_len(host)); + uc = ipv6_parse(u, Curl_dyn_ptr(host), Curl_dyn_len(host)); break; case HOST_NAME: - result = urldecode_host(host); - if(!result) - result = hostname_check(u, Curl_dyn_ptr(host), Curl_dyn_len(host)); + uc = urldecode_host(host); + if(!uc) + uc = hostname_check(u, Curl_dyn_ptr(host), Curl_dyn_len(host)); break; case HOST_ERROR: - result = CURLUE_OUT_OF_MEMORY; + uc = CURLUE_OUT_OF_MEMORY; break; case HOST_BAD: default: - result = CURLUE_BAD_HOSTNAME; /* Bad IPv4 address even */ + uc = CURLUE_BAD_HOSTNAME; /* Bad IPv4 address even */ break; } out: - return result; + return uc; } CURLUcode Curl_url_set_authority(CURLU *u, const char *authority, @@ -1079,8 +1092,9 @@ static CURLUcode parseurl(const char *url, CURLU *u, unsigned int flags) len = path - ptr; if(len) { - if(Curl_dyn_addn(&host, ptr, len)) { - result = CURLUE_OUT_OF_MEMORY; + CURLcode code = Curl_dyn_addn(&host, ptr, len); + if(code) { + result = cc2cu(code); goto fail; } uncpath = TRUE; @@ -1233,10 +1247,9 @@ static CURLUcode parseurl(const char *url, CURLU *u, unsigned int flags) if(flags & CURLU_URLENCODE) { struct dynbuf enc; Curl_dyn_init(&enc, CURL_MAX_INPUT_LENGTH); - if(urlencode_str(&enc, fragment + 1, fraglen - 1, TRUE, FALSE)) { - result = CURLUE_OUT_OF_MEMORY; + result = urlencode_str(&enc, fragment + 1, fraglen - 1, TRUE, FALSE); + if(result) goto fail; - } u->fragment = Curl_dyn_ptr(&enc); } else { @@ -1262,10 +1275,9 @@ static CURLUcode parseurl(const char *url, CURLU *u, unsigned int flags) struct dynbuf enc; Curl_dyn_init(&enc, CURL_MAX_INPUT_LENGTH); /* skip the leading question mark */ - if(urlencode_str(&enc, query + 1, qlen - 1, TRUE, TRUE)) { - result = CURLUE_OUT_OF_MEMORY; + result = urlencode_str(&enc, query + 1, qlen - 1, TRUE, TRUE); + if(result) goto fail; - } u->query = Curl_dyn_ptr(&enc); } else { @@ -1289,10 +1301,9 @@ static CURLUcode parseurl(const char *url, CURLU *u, unsigned int flags) if(pathlen && (flags & CURLU_URLENCODE)) { struct dynbuf enc; Curl_dyn_init(&enc, CURL_MAX_INPUT_LENGTH); - if(urlencode_str(&enc, path, pathlen, TRUE, FALSE)) { - result = CURLUE_OUT_OF_MEMORY; + result = urlencode_str(&enc, path, pathlen, TRUE, FALSE); + if(result) goto fail; - } pathlen = Curl_dyn_len(&enc); path = u->path = Curl_dyn_ptr(&enc); } @@ -1628,10 +1639,11 @@ CURLUcode curl_url_get(const CURLU *u, CURLUPart what, } if(urlencode) { struct dynbuf enc; + CURLUcode uc; Curl_dyn_init(&enc, CURL_MAX_INPUT_LENGTH); - if(urlencode_str(&enc, *part, partlen, TRUE, - what == CURLUPART_QUERY)) - return CURLUE_OUT_OF_MEMORY; + uc = urlencode_str(&enc, *part, partlen, TRUE, what == CURLUPART_QUERY); + if(uc) + return uc; free(*part); *part = Curl_dyn_ptr(&enc); } @@ -1816,7 +1828,8 @@ CURLUcode curl_url_set(CURLU *u, CURLUPart what, * If the existing contents is enough for a URL, allow a relative URL to * replace it. */ - CURLUcode result; + CURLcode result; + CURLUcode uc; char *oldurl; char *redired_url; @@ -1836,14 +1849,14 @@ CURLUcode curl_url_set(CURLU *u, CURLUPart what, /* apply the relative part to create a new URL * and replace the existing one with it. */ - redired_url = concat_url(oldurl, part); + result = concat_url(oldurl, part, &redired_url); free(oldurl); - if(!redired_url) - return CURLUE_OUT_OF_MEMORY; + if(result) + return cc2cu(result); - result = parseurl_and_replace(redired_url, u, flags); + uc = parseurl_and_replace(redired_url, u, flags); free(redired_url); - return result; + return uc; } default: return CURLUE_UNKNOWN_PART; @@ -1857,7 +1870,7 @@ CURLUcode curl_url_set(CURLU *u, CURLUPart what, if(leadingslash && (part[0] != '/')) { CURLcode result = Curl_dyn_addn(&enc, "/", 1); if(result) - return CURLUE_OUT_OF_MEMORY; + return cc2cu(result); } if(urlencode) { const unsigned char *i; @@ -1877,7 +1890,7 @@ CURLUcode curl_url_set(CURLU *u, CURLUPart what, equalsencode = FALSE; result = Curl_dyn_addn(&enc, i, 1); if(result) - return CURLUE_OUT_OF_MEMORY; + return cc2cu(result); } else { char out[3]={'%'}; @@ -1885,7 +1898,7 @@ CURLUcode curl_url_set(CURLU *u, CURLUPart what, out[2] = hexdigits[*i & 0xf]; result = Curl_dyn_addn(&enc, out, 3); if(result) - return CURLUE_OUT_OF_MEMORY; + return cc2cu(result); } } } @@ -1893,7 +1906,7 @@ CURLUcode curl_url_set(CURLU *u, CURLUPart what, char *p; CURLcode result = Curl_dyn_add(&enc, part); if(result) - return CURLUE_OUT_OF_MEMORY; + return cc2cu(result); p = Curl_dyn_ptr(&enc); while(*p) { /* make sure percent encoded are lower case */ diff --git a/tests/data/test1154 b/tests/data/test1154 index b7349e17d21..bd08ce26c10 100644 --- a/tests/data/test1154 +++ b/tests/data/test1154 @@ -47,9 +47,9 @@ User-Agent: curl/%VERSION Accept: */* -# 27 == CURLE_OUT_OF_MEMORY +# 100 == CURLE_TOO_LARGE -27 +100 diff --git a/tests/data/test1538 b/tests/data/test1538 index 59cd1628eae..c0f038be402 100644 --- a/tests/data/test1538 +++ b/tests/data/test1538 @@ -132,7 +132,8 @@ e96: QUIC connection error e97: proxy handshake error e98: SSL Client Certificate required e99: Unrecoverable error in select/poll -e100: Unknown error +e100: A value or data field grew larger than allowed +e101: Unknown error m-1: Please call curl_multi_perform() soon m0: No error m1: Invalid multi handle @@ -186,7 +187,8 @@ u27: Bad scheme u28: Unsupported number of slashes following scheme u29: Bad user u30: libcurl lacks IDN support -u31: CURLUcode unknown +u31: A value or data field is larger than allowed +u32: CURLUcode unknown From 3dcf301752a09d91961ebf4f17d08864ff3b05d4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 18 Dec 2023 10:11:30 +0100 Subject: [PATCH 058/509] runtests: support -gl. Like -g but for lldb. Follow-up to 63b5748 Invokes the test case via lldb instead of gdb. Since using gdb is such a pain on mac, using lldb is sometimes less quirky. Closes #12547 --- tests/runner.pm | 22 ++++++++++++++++++---- tests/runtests.1 | 5 +++++ tests/runtests.pl | 4 ++++ 3 files changed, 27 insertions(+), 4 deletions(-) diff --git a/tests/runner.pm b/tests/runner.pm index 8b61eb4b3be..1ee912fc7fc 100644 --- a/tests/runner.pm +++ b/tests/runner.pm @@ -945,9 +945,16 @@ sub singletest_run { if($gdbthis) { my $gdbinit = "$TESTDIR/gdbinit$testnum"; open(my $gdbcmd, ">", "$LOGDIR/gdbcmd") || die "Failure writing gdb file"; - print $gdbcmd "set args $cmdargs\n"; - print $gdbcmd "show args\n"; - print $gdbcmd "source $gdbinit\n" if -e $gdbinit; + if($gdbthis == 1) { + # gdb mode + print $gdbcmd "set args $cmdargs\n"; + print $gdbcmd "show args\n"; + print $gdbcmd "source $gdbinit\n" if -e $gdbinit; + } + else { + # lldb mode + print $gdbcmd "set args $cmdargs\n"; + } close($gdbcmd) || die "Failure writing gdb file"; } @@ -963,11 +970,18 @@ sub singletest_run { $testnum, "$gdb --directory $LIBDIR " . shell_quote($DBGCURL) . " -x $LOGDIR/gdbcmd"); } - elsif($gdbthis) { + elsif($gdbthis == 1) { + # gdb my $GDBW = ($gdbxwin) ? "-w" : ""; runclient("$gdb --directory $LIBDIR " . shell_quote($DBGCURL) . " $GDBW -x $LOGDIR/gdbcmd"); $cmdres=0; # makes it always continue after a debugged run } + elsif($gdbthis == 2) { + # $gdb is "lldb" + print "runs lldb -- $CURL $cmdargs\n"; + runclient("lldb -- $CURL $cmdargs"); + $cmdres=0; # makes it always continue after a debugged run + } else { # Convert the raw result code into a more useful one ($cmdres, $dumped_core) = normalize_cmdres(runclient("$CMDLINE")); diff --git a/tests/runtests.1 b/tests/runtests.1 index 6d895d2b9b3..01d490b2c7f 100644 --- a/tests/runtests.1 +++ b/tests/runtests.1 @@ -116,6 +116,11 @@ Run the given test(s) with gdb. This is best used on a single test case and curl built --disable-shared. This then fires up gdb with command line set to run the specified test case. Simply (set a break-point and) type 'run' to start. +.IP "-gl" +Run the given test(s) with lldb. This is best used on a single test case and +curl built --disable-shared. This then fires up lldb with command line set to +run the specified test case. Simply (set a break-point and) type 'run' to +start. .IP "-gw" Run the given test(s) with gdb as a windowed application. .IP "-h, --help" diff --git a/tests/runtests.pl b/tests/runtests.pl index e7b9f01f6a6..9dbe4e2d68b 100755 --- a/tests/runtests.pl +++ b/tests/runtests.pl @@ -2215,6 +2215,10 @@ sub pickrunner { # run this test with gdb $gdbthis=1; } + elsif ($ARGV[0] eq "-gl") { + # run this test with lldb + $gdbthis=2; + } elsif ($ARGV[0] eq "-gw") { # run this test with windowed gdb $gdbthis=1; From 6d8d59743179803ebc8a9c333ff0fe1c06a604e7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 18 Dec 2023 14:19:22 +0100 Subject: [PATCH 059/509] runner.pm: fix perl warning when running tests Use of uninitialized value $runner::gdbthis in numeric eq (==) at runner.pm Follow-up from 3dcf301752a09d9 Closes #12549 --- tests/runner.pm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/runner.pm b/tests/runner.pm index 1ee912fc7fc..c0fb40cb3db 100644 --- a/tests/runner.pm +++ b/tests/runner.pm @@ -115,7 +115,7 @@ our $DBGCURL=$CURL; #"../src/.libs/curl"; # alternative for debugging our $valgrind_logfile="--log-file"; # the option name for valgrind >=3 our $valgrind_tool="--tool=memcheck"; our $gdb = checktestcmd("gdb"); -our $gdbthis; # run test case with gdb debugger +our $gdbthis = 0; # run test case with debugger (gdb or lldb) our $gdbxwin; # use windowed gdb when using gdb # torture test variables From 7e8fdad2d51255330a87fd7e44b4b108836e232b Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 12 Dec 2023 22:00:59 +0000 Subject: [PATCH 060/509] cmake: prefill/cache `HAVE_STRUCT_SOCKADDR_STORAGE` Also add missing include to `OtherTests.cmake`. It didn't cause an issue because the parent already included this earlier by chance. Closes #12537 --- CMake/OtherTests.cmake | 7 ++++--- CMake/Platforms/WindowsCache.cmake | 1 + 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CMake/OtherTests.cmake b/CMake/OtherTests.cmake index a7599c44d7f..ae964f5bf15 100644 --- a/CMake/OtherTests.cmake +++ b/CMake/OtherTests.cmake @@ -23,6 +23,7 @@ ########################################################################### include(CheckCSourceCompiles) include(CheckCSourceRuns) +include(CheckTypeSize) # The begin of the sources (macros and includes) set(_source_epilogue "#undef inline") @@ -74,9 +75,9 @@ if(NOT WIN32) endif() endif() -check_type_size("struct sockaddr_storage" SIZEOF_STRUCT_SOCKADDR_STORAGE) -if(HAVE_SIZEOF_STRUCT_SOCKADDR_STORAGE) - set(HAVE_STRUCT_SOCKADDR_STORAGE 1) +if(NOT DEFINED HAVE_STRUCT_SOCKADDR_STORAGE) + check_type_size("struct sockaddr_storage" SIZEOF_STRUCT_SOCKADDR_STORAGE) + set(HAVE_STRUCT_SOCKADDR_STORAGE ${HAVE_SIZEOF_STRUCT_SOCKADDR_STORAGE}) endif() unset(CMAKE_TRY_COMPILE_TARGET_TYPE) 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) From 03e7dff8ff96ea5f87b393a9c11006683bef878e Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 12 Dec 2023 19:27:44 +0000 Subject: [PATCH 061/509] windows: delete redundant headers `winsock2.h` pulls in `windows.h`. `ws2tcpip.h` pulls in `winsock2.h`. `winsock2.h` and `ws2tcpip.h` are also pulled by `curl/curl.h`. Keep only those headers that are not already included, or the code under it uses something from that specific header. Closes #12539 --- CMake/CurlTests.c | 5 ----- acinclude.m4 | 8 -------- configure.ac | 1 - docs/examples/externalsocket.c | 2 -- docs/examples/synctime.c | 6 +++--- lib/inet_pton.h | 3 --- lib/socketpair.c | 3 --- m4/curl-functions.m4 | 2 -- tests/libtest/lib1960.c | 6 ------ 9 files changed, 3 insertions(+), 33 deletions(-) diff --git a/CMake/CurlTests.c b/CMake/CurlTests.c index e00acc542ec..83d743d34e4 100644 --- a/CMake/CurlTests.c +++ b/CMake/CurlTests.c @@ -169,7 +169,6 @@ int main(void) { ; return 0; } # define WIN32_LEAN_AND_MEAN # endif # include -# include #endif int main(void) { @@ -189,7 +188,6 @@ int main(void) # define WIN32_LEAN_AND_MEAN # endif # include -# include #endif int main(void) { @@ -208,7 +206,6 @@ int main(void) # define WIN32_LEAN_AND_MEAN # endif # include -# include #endif int main(void) { @@ -228,7 +225,6 @@ int main(void) # define WIN32_LEAN_AND_MEAN # endif # include -# include #endif int main(void) { @@ -304,7 +300,6 @@ int main(void) # define WIN32_LEAN_AND_MEAN # endif # include -# include #endif /* includes start */ #ifdef HAVE_SYS_TYPES_H diff --git a/acinclude.m4 b/acinclude.m4 index 96187ade14e..a44ae350e36 100644 --- a/acinclude.m4 +++ b/acinclude.m4 @@ -589,7 +589,6 @@ AC_DEFUN([TYPE_SOCKADDR_STORAGE], #define WIN32_LEAN_AND_MEAN #endif #include -#include #else #ifdef HAVE_SYS_TYPES_H #include @@ -625,7 +624,6 @@ AC_DEFUN([CURL_CHECK_FUNC_RECV], [ #define WIN32_LEAN_AND_MEAN #endif #include -#include #else $curl_includes_bsdsocket #ifdef HAVE_SYS_TYPES_H @@ -674,7 +672,6 @@ AC_DEFUN([CURL_CHECK_FUNC_SEND], [ #define WIN32_LEAN_AND_MEAN #endif #include -#include #else $curl_includes_bsdsocket #ifdef HAVE_SYS_TYPES_H @@ -719,7 +716,6 @@ AC_DEFUN([CURL_CHECK_MSG_NOSIGNAL], [ #define WIN32_LEAN_AND_MEAN #endif #include -#include #else #ifdef HAVE_SYS_TYPES_H #include @@ -762,7 +758,6 @@ AC_DEFUN([CURL_CHECK_STRUCT_TIMEVAL], [ #define WIN32_LEAN_AND_MEAN #endif #include -#include #endif #ifdef HAVE_SYS_TYPES_H #include @@ -815,7 +810,6 @@ AC_DEFUN([TYPE_IN_ADDR_T], [ #define WIN32_LEAN_AND_MEAN #endif #include -#include #else #ifdef HAVE_SYS_TYPES_H #include @@ -855,7 +849,6 @@ AC_DEFUN([TYPE_IN_ADDR_T], [ #define WIN32_LEAN_AND_MEAN #endif #include -#include #else #ifdef HAVE_SYS_TYPES_H #include @@ -1134,7 +1127,6 @@ AC_DEFUN([CURL_CHECK_FUNC_SELECT], [ #define WIN32_LEAN_AND_MEAN #endif #include -#include #endif #ifdef HAVE_SYS_TYPES_H #include diff --git a/configure.ac b/configure.ac index e809502dfa8..3e89da9f328 100644 --- a/configure.ac +++ b/configure.ac @@ -1125,7 +1125,6 @@ then #define WIN32_LEAN_AND_MEAN #endif #include -#include #endif ]],[[ gethostbyname("localhost"); diff --git a/docs/examples/externalsocket.c b/docs/examples/externalsocket.c index 6c9540a6dbe..9c343734436 100644 --- a/docs/examples/externalsocket.c +++ b/docs/examples/externalsocket.c @@ -32,8 +32,6 @@ #ifdef _WIN32 #include -#include -#include #define close closesocket #else #include /* socket types */ diff --git a/docs/examples/synctime.c b/docs/examples/synctime.c index fcf25d94111..2d7d523d50d 100644 --- a/docs/examples/synctime.c +++ b/docs/examples/synctime.c @@ -91,11 +91,11 @@ #include #include -#ifndef __CYGWIN__ -#include +#include + +#ifdef _WIN32 #include #endif -#include #define MAX_STRING 256 diff --git a/lib/inet_pton.h b/lib/inet_pton.h index a6d161a9996..f8562fa8a7a 100644 --- a/lib/inet_pton.h +++ b/lib/inet_pton.h @@ -31,9 +31,6 @@ int Curl_inet_pton(int, const char *, void *); #ifdef HAVE_INET_PTON #ifdef HAVE_ARPA_INET_H #include -#elif defined(USE_WINSOCK) -/* inet_pton() exists in Vista or later */ -#include #endif #define Curl_inet_pton(x,y,z) inet_pton(x,y,z) #endif diff --git a/lib/socketpair.c b/lib/socketpair.c index e3d40ff94eb..d01b255134a 100644 --- a/lib/socketpair.c +++ b/lib/socketpair.c @@ -33,9 +33,6 @@ * This is a socketpair() implementation for Windows. */ #include -#include -#include -#include #include #else #ifdef HAVE_NETDB_H diff --git a/m4/curl-functions.m4 b/m4/curl-functions.m4 index 18147e4cac6..425d9f96f8d 100644 --- a/m4/curl-functions.m4 +++ b/m4/curl-functions.m4 @@ -419,7 +419,6 @@ curl_includes_winsock2="\ # define WIN32_LEAN_AND_MEAN # endif # include -# include #endif /* includes end */" CURL_CHECK_NATIVE_WINDOWS @@ -440,7 +439,6 @@ curl_includes_ws2tcpip="\ # endif # include # include -# include #endif /* includes end */" CURL_CHECK_NATIVE_WINDOWS diff --git a/tests/libtest/lib1960.c b/tests/libtest/lib1960.c index b01370e6e70..9b82128e9be 100644 --- a/tests/libtest/lib1960.c +++ b/tests/libtest/lib1960.c @@ -25,12 +25,6 @@ #ifdef HAVE_INET_PTON -#ifdef _WIN32 -#include -#include -#include -#endif - #ifdef HAVE_NETINET_IN_H #include #endif From 09230127589eccc7e01c1a7217787ef8e64f3328 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sat, 16 Dec 2023 17:23:40 +0000 Subject: [PATCH 062/509] build: more `-Wformat` fixes - memdebug: update to not trigger `-Wformat-nonliteral` warnings. - imap: mark `imap_sendf()` with `CURL_PRINTF()`. - tool_msgs: mark static function with `CURL_PRINTF()`. Follow-up to 3829759bd042c03225ae862062560f568ba1a231 #12489 Closes #12540 --- lib/imap.c | 3 +- lib/memdebug.c | 77 +++++++++---------------------------------------- src/tool_msgs.c | 7 ++++- 3 files changed, 21 insertions(+), 66 deletions(-) diff --git a/lib/imap.c b/lib/imap.c index 72ce5330686..4e1f4d4bf0b 100644 --- a/lib/imap.c +++ b/lib/imap.c @@ -97,7 +97,8 @@ static CURLcode imap_doing(struct Curl_easy *data, bool *dophase_done); static CURLcode imap_setup_connection(struct Curl_easy *data, struct connectdata *conn); static char *imap_atom(const char *str, bool escape_only); -static CURLcode imap_sendf(struct Curl_easy *data, const char *fmt, ...); +static CURLcode imap_sendf(struct Curl_easy *data, const char *fmt, ...) + CURL_PRINTF(2, 3); static CURLcode imap_parse_url_options(struct connectdata *conn); static CURLcode imap_parse_url_path(struct Curl_easy *data); static CURLcode imap_parse_custom_request(struct Curl_easy *data); diff --git a/lib/memdebug.c b/lib/memdebug.c index fb2b5584607..f3d48172333 100644 --- a/lib/memdebug.c +++ b/lib/memdebug.c @@ -304,12 +304,6 @@ void curl_dbg_free(void *ptr, int line, const char *source) curl_socket_t curl_dbg_socket(int domain, int type, int protocol, int line, const char *source) { - const char *fmt = (sizeof(curl_socket_t) == sizeof(int)) ? - "FD %s:%d socket() = %d\n" : - (sizeof(curl_socket_t) == sizeof(long)) ? - "FD %s:%d socket() = %ld\n" : - "FD %s:%d socket() = %zd\n"; - curl_socket_t sockfd; if(countcheck("socket", line, source)) @@ -317,16 +311,9 @@ curl_socket_t curl_dbg_socket(int domain, int type, int protocol, sockfd = socket(domain, type, protocol); - if(source && (sockfd != CURL_SOCKET_BAD)) { -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif - curl_dbg_log(fmt, source, line, sockfd); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif - } + if(source && (sockfd != CURL_SOCKET_BAD)) + curl_dbg_log("FD %s:%d socket() = %" CURL_FORMAT_SOCKET_T "\n", + source, line, sockfd); return sockfd; } @@ -365,24 +352,12 @@ int curl_dbg_socketpair(int domain, int type, int protocol, curl_socket_t socket_vector[2], int line, const char *source) { - const char *fmt = (sizeof(curl_socket_t) == sizeof(int)) ? - "FD %s:%d socketpair() = %d %d\n" : - (sizeof(curl_socket_t) == sizeof(long)) ? - "FD %s:%d socketpair() = %ld %ld\n" : - "FD %s:%d socketpair() = %zd %zd\n"; - int res = socketpair(domain, type, protocol, socket_vector); - if(source && (0 == res)) { -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif - curl_dbg_log(fmt, source, line, socket_vector[0], socket_vector[1]); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif - } + if(source && (0 == res)) + curl_dbg_log("FD %s:%d socketpair() = " + "%" CURL_FORMAT_SOCKET_T " %" CURL_FORMAT_SOCKET_T "\n", + source, line, socket_vector[0], socket_vector[1]); return res; } @@ -391,27 +366,14 @@ int curl_dbg_socketpair(int domain, int type, int protocol, curl_socket_t curl_dbg_accept(curl_socket_t s, void *saddr, void *saddrlen, int line, const char *source) { - const char *fmt = (sizeof(curl_socket_t) == sizeof(int)) ? - "FD %s:%d accept() = %d\n" : - (sizeof(curl_socket_t) == sizeof(long)) ? - "FD %s:%d accept() = %ld\n" : - "FD %s:%d accept() = %zd\n"; - struct sockaddr *addr = (struct sockaddr *)saddr; curl_socklen_t *addrlen = (curl_socklen_t *)saddrlen; curl_socket_t sockfd = accept(s, addr, addrlen); - if(source && (sockfd != CURL_SOCKET_BAD)) { -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif - curl_dbg_log(fmt, source, line, sockfd); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif - } + if(source && (sockfd != CURL_SOCKET_BAD)) + curl_dbg_log("FD %s:%d accept() = %" CURL_FORMAT_SOCKET_T "\n", + source, line, sockfd); return sockfd; } @@ -419,22 +381,9 @@ curl_socket_t curl_dbg_accept(curl_socket_t s, void *saddr, void *saddrlen, /* separate function to allow libcurl to mark a "faked" close */ void curl_dbg_mark_sclose(curl_socket_t sockfd, int line, const char *source) { - const char *fmt = (sizeof(curl_socket_t) == sizeof(int)) ? - "FD %s:%d sclose(%d)\n": - (sizeof(curl_socket_t) == sizeof(long)) ? - "FD %s:%d sclose(%ld)\n": - "FD %s:%d sclose(%zd)\n"; - - if(source) { -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif - curl_dbg_log(fmt, source, line, sockfd); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif - } + if(source) + curl_dbg_log("FD %s:%d sclose(%" CURL_FORMAT_SOCKET_T ")\n", + source, line, sockfd); } /* this is our own defined way to close sockets on *ALL* platforms */ diff --git a/src/tool_msgs.c b/src/tool_msgs.c index 5e4f6ad1424..d11c5186bfe 100644 --- a/src/tool_msgs.c +++ b/src/tool_msgs.c @@ -36,6 +36,11 @@ #define NOTE_PREFIX "Note: " #define ERROR_PREFIX "curl: " +static void voutf(struct GlobalConfig *config, + const char *prefix, + const char *fmt, + va_list ap) CURL_PRINTF(3, 0); + static void voutf(struct GlobalConfig *config, const char *prefix, const char *fmt, @@ -107,7 +112,6 @@ void notef(struct GlobalConfig *config, const char *fmt, ...) * Emit warning formatted message on configured 'errors' stream unless * mute (--silent) was selected. */ - void warnf(struct GlobalConfig *config, const char *fmt, ...) { va_list ap; @@ -115,6 +119,7 @@ void warnf(struct GlobalConfig *config, const char *fmt, ...) voutf(config, WARN_PREFIX, fmt, ap); va_end(ap); } + /* * Emit help formatted message on given stream. This is for errors with or * related to command line arguments. From dd29622f323ca1148817eb7b257fe456bdf5d2a1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 20 Nov 2023 17:22:40 +0100 Subject: [PATCH 063/509] CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add Proposed-by: Yifei Kong Ref: https://curl.se/mail/lib-2023-11/0023.html Closes #12369 --- docs/libcurl/curl_easy_setopt.3 | 2 + .../opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 | 76 +++++++++++++++++++ docs/libcurl/opts/Makefile.inc | 1 + docs/libcurl/symbols-in-versions | 1 + include/curl/curl.h | 3 + lib/easyoptions.c | 4 +- lib/setopt.c | 11 +++ 7 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7e7819f643b..d4a5dcb5c00 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -423,6 +423,8 @@ Use PRET. See \fICURLOPT_FTP_USE_PRET(3)\fP Create missing directories on the remote server. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP .IP CURLOPT_SERVER_RESPONSE_TIMEOUT Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP +.IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS +Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP .IP CURLOPT_FTP_ALTERNATIVE_TO_USER Alternative to USER. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP .IP CURLOPT_FTP_SKIP_PASV_IP diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 new file mode 100644 index 00000000000..08239b74987 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 @@ -0,0 +1,76 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_SERVER_RESPONSE_TIMEOUT_MS 3 "19 Jun 2014" libcurl libcurl +.SH NAME +CURLOPT_SERVER_RESPONSE_TIMEOUT_MS \- time allowed to wait for server response +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, + long timeout); +.fi +.SH DESCRIPTION +Pass a long. Causes libcurl to set a \fItimeout\fP period (in milliseconds) +on the amount of time that the server is allowed to take in order to send a +response message for a command before the session is considered dead. While +libcurl is waiting for a response, this value overrides +\fICURLOPT_TIMEOUT(3)\fP. It is recommended that if used in conjunction with +\fICURLOPT_TIMEOUT(3)\fP, you set \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP +to a value smaller than \fICURLOPT_TIMEOUT(3)\fP. + +The maximum accepted value is 2147483648. + +This is the millisecond version of \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP. +.SH DEFAULT +None +.SH PROTOCOLS +FTP, IMAP, POP3, SMTP, and SSH +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); + /* wait no more than 237 milliseconds */ + curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, 237L); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in 8.6.0. +.SH RETURN VALUE +Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns +CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when +converted to milliseconds is too large. +.SH "SEE ALSO" +.BR CURLOPT_CONNECTTIMEOUT (3), +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc index 9fe780677fd..4b581c5be4e 100644 --- a/docs/libcurl/opts/Makefile.inc +++ b/docs/libcurl/opts/Makefile.inc @@ -332,6 +332,7 @@ man_MANS = \ CURLOPT_SEEKDATA.3 \ CURLOPT_SEEKFUNCTION.3 \ CURLOPT_SERVER_RESPONSE_TIMEOUT.3 \ + CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 \ CURLOPT_SERVICE_NAME.3 \ CURLOPT_SHARE.3 \ CURLOPT_SOCKOPTDATA.3 \ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 179ba11025f..a77a5255025 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -801,6 +801,7 @@ CURLOPT_SASL_IR 7.31.0 CURLOPT_SEEKDATA 7.18.0 CURLOPT_SEEKFUNCTION 7.18.0 CURLOPT_SERVER_RESPONSE_TIMEOUT 7.20.0 +CURLOPT_SERVER_RESPONSE_TIMEOUT_MS 8.6.0 CURLOPT_SERVICE_NAME 7.43.0 CURLOPT_SHARE 7.10 CURLOPT_SOCKOPTDATA 7.16.0 diff --git a/include/curl/curl.h b/include/curl/curl.h index ab600b83c37..a5b59e0268a 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -2202,6 +2202,9 @@ typedef enum { /* set a specific client IP for HAProxy PROXY protocol header? */ CURLOPT(CURLOPT_HAPROXY_CLIENT_IP, CURLOPTTYPE_STRINGPOINT, 323), + /* millisecond version */ + CURLOPT(CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, CURLOPTTYPE_LONG, 324), + CURLOPT_LASTENTRY /* the last unused */ } CURLoption; diff --git a/lib/easyoptions.c b/lib/easyoptions.c index e69c658b0c7..da4c6111a3b 100644 --- a/lib/easyoptions.c +++ b/lib/easyoptions.c @@ -274,6 +274,8 @@ struct curl_easyoption Curl_easyopts[] = { {"SEEKFUNCTION", CURLOPT_SEEKFUNCTION, CURLOT_FUNCTION, 0}, {"SERVER_RESPONSE_TIMEOUT", CURLOPT_SERVER_RESPONSE_TIMEOUT, CURLOT_LONG, 0}, + {"SERVER_RESPONSE_TIMEOUT_MS", CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, + CURLOT_LONG, 0}, {"SERVICE_NAME", CURLOPT_SERVICE_NAME, CURLOT_STRING, 0}, {"SHARE", CURLOPT_SHARE, CURLOT_OBJECT, 0}, {"SOCKOPTDATA", CURLOPT_SOCKOPTDATA, CURLOT_CBPTR, 0}, @@ -373,6 +375,6 @@ struct curl_easyoption Curl_easyopts[] = { */ int Curl_easyopts_check(void) { - return ((CURLOPT_LASTENTRY%10000) != (323 + 1)); + return ((CURLOPT_LASTENTRY%10000) != (324 + 1)); } #endif diff --git a/lib/setopt.c b/lib/setopt.c index a08140cce84..460cb32e74a 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -366,6 +366,17 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) else return CURLE_BAD_FUNCTION_ARGUMENT; break; + case CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: + /* + * Option that specifies how quickly a server response must be obtained + * before it is considered failure. For pingpong protocols. + */ + arg = va_arg(param, long); + if((arg >= 0) && (arg <= INT_MAX)) + data->set.server_response_timeout = (unsigned int)arg; + else + return CURLE_BAD_FUNCTION_ARGUMENT; + break; #ifndef CURL_DISABLE_TFTP case CURLOPT_TFTP_NO_OPTIONS: /* From d482444cc1e70dd78883d2995e6c2204b44cacdc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Dec 2023 08:21:48 +0100 Subject: [PATCH 064/509] DEPRECATE.md: mention that NTLM_WB no longer works Ref: #12479 Closes #12553 --- docs/DEPRECATE.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/DEPRECATE.md b/docs/DEPRECATE.md index 4cd5a22ce2b..598b77398da 100644 --- a/docs/DEPRECATE.md +++ b/docs/DEPRECATE.md @@ -15,7 +15,11 @@ don't 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 will remove the support for NTLM_WB auth in April 2024. ## space-separated `NOPROXY` patterns From a91746b4c73c9741e7b82fc6cae96e491b58e854 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 18 Dec 2023 15:21:21 +0000 Subject: [PATCH 065/509] appveyor: switch to out-of-tree builds With cmake and autotools. Closes #12550 --- appveyor.yml | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/appveyor.yml b/appveyor.yml index 175f298d53a..86a5f8b64d5 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -338,16 +338,15 @@ build_script: } Write-Host 'CMake options:' $options - cmake . $options - cmake --build . --config $env:PRJ_CFG --parallel 2 --clean-first -- $env:BUILD_OPT + cmake -B _bld $options + cmake --build _bld --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' + Copy-Item -Path 'C:\Projects\curl\_bld\lib\*.dll' -Destination 'C:\projects\curl\_bld\src' } if($env:OPENSSL -eq 'ON') { - Copy-Item -Path "$openssl_root\*.dll" -Destination 'C:\projects\curl\src' + Copy-Item -Path "$openssl_root\*.dll" -Destination 'C:\projects\curl\_bld\src' } - $curl = '.\src\curl.exe' + $curl = '.\_bld\src\curl.exe' } elseif($env:BUILD_SYSTEM -eq 'VisualStudioSolution') { cd projects @@ -371,8 +370,8 @@ build_script: $curl = "..\builds\libcurl-vc14.10-x64-$env:PATHPART-dll-ssl-dll-ipv6-sspi\bin\curl.exe" } 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' + & bash -e -c "cd $env:POSIX_PATH_PREFIX/c/projects/curl && autoreconf -fi 2>&1 && mkdir _bld && cd _bld && ../configure $env:CONFIG_ARGS 2>&1 && make V=1 && make V=1 examples && cd tests && make V=1" + $curl = '.\_bld\src\curl.exe' } Get-ChildItem -Path C:\projects\curl -Include ('*.exe', '*.dll') -Recurse -Name @@ -388,14 +387,14 @@ build_script: } 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(Test-Path _bld/CMakeFiles/CMakeConfigureLog.yaml) { cat _bld/CMakeFiles/CMakeConfigureLog.yaml } + if(Test-Path _bld/CMakeFiles/CMakeOutput.log) { cat _bld/CMakeFiles/CMakeOutput.log } + if(Test-Path _bld/CMakeFiles/CMakeError.log) { cat _bld/CMakeFiles/CMakeError.log } + if(Test-Path config.log) { cat _bld/config.log } } if($env:TESTING -eq 'ON' -and $env:BUILD_SYSTEM -eq 'CMake') { - cmake --build . --config $env:PRJ_CFG --parallel 2 --target testdeps + cmake --build _bld --config $env:PRJ_CFG --parallel 2 --target testdeps } test_script: @@ -408,14 +407,15 @@ test_script: } if($env:TESTING -eq 'ON') { if($env:BUILD_SYSTEM -eq 'CMake') { + Copy-Item -Path 'C:\Projects\curl\_bld\lib\*.dll' -Destination 'C:\projects\curl\_bld\tests\libtest' $env:TFLAGS="$acurl $env:DISABLED_TESTS" - cmake --build . --config $env:PRJ_CFG --target test-ci + cmake --build _bld --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" + & bash -e -c "cd $env:POSIX_PATH_PREFIX/c/projects/curl/_bld && 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" + & bash -e -c "cd $env:POSIX_PATH_PREFIX/c/projects/curl/_bld/tests && ./runtests.pl -a -p !flaky -r -rm $acurl $env:DISABLED_TESTS" } } From 68d80a8f9bf185f4aae1cfe0f5337f400afa6b6e Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 18 Dec 2023 15:40:33 +0000 Subject: [PATCH 066/509] cmake: tidy-up `OtherTests.cmake` - make more obvious which detection uses which prep steps. - merge and streamline conditions. - these should not alter detection results. Also align log output messages from `Macros.cmake` / `curl_internal_test` with rest of the build. Closes #12551 --- CMake/Macros.cmake | 10 +-- CMake/OtherTests.cmake | 143 ++++++++++++++++------------------------- 2 files changed, 60 insertions(+), 93 deletions(-) diff --git a/CMake/Macros.cmake b/CMake/Macros.cmake index 7ad2f5c40f0..9ff62ea7295 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,15 +54,15 @@ 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() diff --git a/CMake/OtherTests.cmake b/CMake/OtherTests.cmake index ae964f5bf15..7701c0ee93b 100644 --- a/CMake/OtherTests.cmake +++ b/CMake/OtherTests.cmake @@ -25,9 +25,6 @@ include(CheckCSourceCompiles) include(CheckCSourceRuns) include(CheckTypeSize) -# The begin of the sources (macros and includes) -set(_source_epilogue "#undef inline") - macro(add_header_include check header) if(${check}) set(_source_epilogue "${_source_epilogue} @@ -35,28 +32,36 @@ macro(add_header_include check header) endif() endmacro() -if(WIN32) - set(CMAKE_EXTRA_INCLUDE_FILES "winsock2.h") - set(CMAKE_REQUIRED_DEFINITIONS "-DWIN32_LEAN_AND_MEAN") - set(CMAKE_REQUIRED_LIBRARIES "ws2_32") -else() - add_header_include(HAVE_SYS_TYPES_H "sys/types.h") - add_header_include(HAVE_SYS_SOCKET_H "sys/socket.h") -endif() - set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) -check_c_source_compiles("${_source_epilogue} - int main(void) - { - int flag = MSG_NOSIGNAL; - (void)flag; - return 0; - }" HAVE_MSG_NOSIGNAL) +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() + check_type_size("struct sockaddr_storage" SIZEOF_STRUCT_SOCKADDR_STORAGE) + set(HAVE_STRUCT_SOCKADDR_STORAGE ${HAVE_SIZEOF_STRUCT_SOCKADDR_STORAGE}) +endif() if(NOT WIN32) - add_header_include(HAVE_SYS_TIME_H "sys/time.h") + 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(_source_epilogue "#undef inline") +add_header_include(HAVE_SYS_TIME_H "sys/time.h") check_c_source_compiles("${_source_epilogue} #include int main(void) @@ -68,66 +73,39 @@ check_c_source_compiles("${_source_epilogue} return 0; }" HAVE_STRUCT_TIMEVAL) -if(NOT WIN32) - set(CMAKE_EXTRA_INCLUDE_FILES) - if(HAVE_SYS_SOCKET_H) - set(CMAKE_EXTRA_INCLUDE_FILES "sys/socket.h") - endif() -endif() - -if(NOT DEFINED HAVE_STRUCT_SOCKADDR_STORAGE) - check_type_size("struct sockaddr_storage" SIZEOF_STRUCT_SOCKADDR_STORAGE) - set(HAVE_STRUCT_SOCKADDR_STORAGE ${HAVE_SIZEOF_STRUCT_SOCKADDR_STORAGE}) -endif() - unset(CMAKE_TRY_COMPILE_TARGET_TYPE) -if(NOT CMAKE_CROSSCOMPILING) - if(NOT APPLE) - # 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; - } +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() + } + return 0; + }" HAVE_POLL_FINE) endif() # Detect HAVE_GETADDRINFO_THREADSAFE @@ -149,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) { @@ -193,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) @@ -212,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() From 2dbe75bd7f3c36837aa06fd87a442bdf3fb7faef Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sat, 9 Dec 2023 02:45:19 +0000 Subject: [PATCH 067/509] build: fix some `-Wsign-conversion`/`-Warith-conversion` warnings - enable `-Wsign-conversion` warnings, but also setting them to not raise errors. - fix `-Warith-conversion` warnings seen in CI. These are triggered by `-Wsign-converion` and causing errors unless explicitly silenced. It makes more sense to fix them, there just a few of them. - fix some `-Wsign-conversion` warnings. - hide `-Wsign-conversion` warnings with a `#pragma`. - add macro `CURL_WARN_SIGN_CONVERSION` to unhide them on a per-build basis. - update a CI job to unhide them with the above macro: https://github.com/curl/curl/actions/workflows/linux.yml -> OpenSSL -O3 Closes #12492 --- .github/workflows/linux.yml | 2 +- CMake/PickyWarnings.cmake | 5 ++--- lib/curl_setup.h | 7 +++++++ lib/doh.c | 19 ++++++++++--------- lib/inet_pton.c | 3 ++- lib/mprintf.c | 2 +- lib/share.c | 8 ++++---- lib/vauth/krb5_gssapi.c | 3 ++- lib/vauth/krb5_sspi.c | 3 ++- m4/curl-compilers.m4 | 10 ++++------ tests/libtest/first.c | 12 ++++++++---- tests/libtest/lib1560.c | 2 +- tests/libtest/lib1947.c | 2 +- tests/libtest/testutil.c | 4 ++-- tests/server/mqttd.c | 12 +++++++----- tests/server/util.c | 4 ++-- tests/unit/unit1651.c | 2 +- 17 files changed, 57 insertions(+), 43 deletions(-) diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index 96f14561fbd..b4ad111f80e 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -111,7 +111,7 @@ jobs: - 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 + configure: CPPFLAGS=-DCURL_WARN_SIGN_CONVERSION CFLAGS=-O3 LDFLAGS="-Wl,-rpath,$HOME/openssl3/lib64" --with-openssl=$HOME/openssl3 --enable-debug --enable-websockets singleuse: --unit - name: openssl3-clang diff --git a/CMake/PickyWarnings.cmake b/CMake/PickyWarnings.cmake index 056e56c91bb..d82bbb1d6a6 100644 --- a/CMake/PickyWarnings.cmake +++ b/CMake/PickyWarnings.cmake @@ -89,13 +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 -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 # FIXME - # -Wno-error=sign-conversion # FIXME + -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 diff --git a/lib/curl_setup.h b/lib/curl_setup.h index fd7358b4502..551243e2700 100644 --- a/lib/curl_setup.h +++ b/lib/curl_setup.h @@ -28,6 +28,13 @@ #define CURL_NO_OLDIES #endif +/* FIXME: Delete this once the warnings have been fixed. */ +#if !defined(CURL_WARN_SIGN_CONVERSION) +#ifdef __GNUC__ +#pragma GCC diagnostic ignored "-Wsign-conversion" +#endif +#endif + /* Set default _WIN32_WINNT */ #ifdef __MINGW32__ #include <_mingw.h> diff --git a/lib/doh.c b/lib/doh.c index d550df299a1..ef32d507df2 100644 --- a/lib/doh.c +++ b/lib/doh.c @@ -444,7 +444,7 @@ static DOHcode skipqname(const unsigned char *doh, size_t dohlen, return DOH_DNS_BAD_LABEL; if(dohlen < (*indexp + 1 + length)) return DOH_DNS_OUT_OF_RANGE; - *indexp += 1 + length; + *indexp += (unsigned int)(1 + length); } while(length); return DOH_OK; } @@ -456,14 +456,15 @@ static unsigned short get16bit(const unsigned char *doh, int index) static unsigned int get32bit(const unsigned char *doh, int index) { - /* make clang and gcc optimize this to bswap by incrementing - the pointer first. */ - doh += index; - - /* avoid undefined behavior by casting to unsigned before shifting - 24 bits, possibly into the sign bit. codegen is same, but - ub sanitizer won't be upset */ - return ( (unsigned)doh[0] << 24) | (doh[1] << 16) |(doh[2] << 8) | doh[3]; + /* make clang and gcc optimize this to bswap by incrementing + the pointer first. */ + doh += index; + + /* avoid undefined behavior by casting to unsigned before shifting + 24 bits, possibly into the sign bit. codegen is same, but + ub sanitizer won't be upset */ + return ((unsigned)doh[0] << 24) | ((unsigned)doh[1] << 16) | + ((unsigned)doh[2] << 8) | doh[3]; } static DOHcode store_a(const unsigned char *doh, int index, struct dohentry *d) diff --git a/lib/inet_pton.c b/lib/inet_pton.c index 7d3c6987957..176cc956fec 100644 --- a/lib/inet_pton.c +++ b/lib/inet_pton.c @@ -112,7 +112,8 @@ inet_pton4(const char *src, unsigned char *dst) pch = strchr(digits, ch); if(pch) { - unsigned int val = *tp * 10 + (unsigned int)(pch - digits); + unsigned int val = (unsigned int)(*tp * 10) + + (unsigned int)(pch - digits); if(saw_digit && *tp == 0) return (0); diff --git a/lib/mprintf.c b/lib/mprintf.c index 514fdc87a86..3d194b24ed6 100644 --- a/lib/mprintf.c +++ b/lib/mprintf.c @@ -1010,7 +1010,7 @@ static int dprintf_formatf( static int addbyter(int output, FILE *data) { struct nsprintf *infop = (struct nsprintf *)data; - unsigned char outc = (unsigned char)output; + char outc = (char)output; if(infop->length < infop->max) { /* only do this if we haven't reached max length yet */ diff --git a/lib/share.c b/lib/share.c index c0a8d806f34..8fa5cda00f0 100644 --- a/lib/share.c +++ b/lib/share.c @@ -133,13 +133,13 @@ curl_share_setopt(struct Curl_share *share, CURLSHoption option, ...) res = CURLSHE_BAD_OPTION; } if(!res) - share->specifier |= (1<specifier |= (unsigned int)(1<specifier &= ~(1<specifier &= ~(unsigned int)(1<specifier & (1<specifier & (unsigned int)(1<lockfunc) /* only call this if set! */ share->lockfunc(data, type, accesstype, share->clientdata); } @@ -281,7 +281,7 @@ Curl_share_unlock(struct Curl_easy *data, curl_lock_data type) if(!share) return CURLSHE_INVALID; - if(share->specifier & (1<specifier & (unsigned int)(1<unlockfunc) /* only call this if set! */ share->unlockfunc (data, type, share->clientdata); } diff --git a/lib/vauth/krb5_gssapi.c b/lib/vauth/krb5_gssapi.c index 65eb3e1b508..16b6e4037f9 100644 --- a/lib/vauth/krb5_gssapi.c +++ b/lib/vauth/krb5_gssapi.c @@ -226,7 +226,8 @@ CURLcode Curl_auth_create_gssapi_security_message(struct Curl_easy *data, /* Extract the security layer and the maximum message size */ indata = output_token.value; sec_layer = indata[0]; - max_size = (indata[1] << 16) | (indata[2] << 8) | indata[3]; + max_size = ((unsigned int)indata[1] << 16) | + ((unsigned int)indata[2] << 8) | indata[3]; /* Free the challenge as it is not required anymore */ gss_release_buffer(&unused_status, &output_token); diff --git a/lib/vauth/krb5_sspi.c b/lib/vauth/krb5_sspi.c index c487149b9d7..17a517a9750 100644 --- a/lib/vauth/krb5_sspi.c +++ b/lib/vauth/krb5_sspi.c @@ -319,7 +319,8 @@ CURLcode Curl_auth_create_gssapi_security_message(struct Curl_easy *data, /* Extract the security layer and the maximum message size */ indata = input_buf[1].pvBuffer; sec_layer = indata[0]; - max_size = (indata[1] << 16) | (indata[2] << 8) | indata[3]; + max_size = ((unsigned long)indata[1] << 16) | + ((unsigned long)indata[2] << 8) | indata[3]; /* Free the challenge as it is not required anymore */ s_pSecFn->FreeContextBuffer(input_buf[1].pvBuffer); diff --git a/m4/curl-compilers.m4 b/m4/curl-compilers.m4 index 7968a113a9a..9a4547709eb 100644 --- a/m4/curl-compilers.m4 +++ b/m4/curl-compilers.m4 @@ -830,9 +830,8 @@ AC_DEFUN([CURL_SET_COMPILER_WARNING_OPTS], [ # dnl Only clang 2.9 or later if test "$compiler_num" -ge "209"; then - tmp_CFLAGS="$tmp_CFLAGS -Wno-sign-conversion" - # CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [sign-conversion]) # FIXME - # tmp_CFLAGS="$tmp_CFLAGS -Wno-error=sign-conversion" # FIXME + CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [sign-conversion]) + tmp_CFLAGS="$tmp_CFLAGS -Wno-error=sign-conversion" # FIXME CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [shift-sign-overflow]) # CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [padded]) # Not used because we cannot change public structs fi @@ -1023,9 +1022,8 @@ AC_DEFUN([CURL_SET_COMPILER_WARNING_OPTS], [ CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [missing-parameter-type empty-body]) CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [clobbered ignored-qualifiers]) CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [conversion trampolines]) - tmp_CFLAGS="$tmp_CFLAGS -Wno-sign-conversion" - # CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [sign-conversion]) # FIXME - # tmp_CFLAGS="$tmp_CFLAGS -Wno-error=sign-conversion" # FIXME + CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [sign-conversion]) + tmp_CFLAGS="$tmp_CFLAGS -Wno-error=sign-conversion" # FIXME CURL_ADD_COMPILER_WARNINGS([tmp_CFLAGS], [vla]) dnl required for -Warray-bounds, included in -Wall tmp_CFLAGS="$tmp_CFLAGS -ftree-vrp" diff --git a/tests/libtest/first.c b/tests/libtest/first.c index 6d13806887a..42c53c69410 100644 --- a/tests/libtest/first.c +++ b/tests/libtest/first.c @@ -65,12 +65,16 @@ int select_wrapper(int nfds, fd_set *rd, fd_set *wr, fd_set *exc, void wait_ms(int ms) { + if(ms < 0) + return; #ifdef USE_WINSOCK - Sleep(ms); + Sleep((DWORD)ms); #else - struct timeval t; - curlx_mstotv(&t, ms); - select_wrapper(0, NULL, NULL, NULL, &t); + { + struct timeval t; + curlx_mstotv(&t, ms); + select_wrapper(0, NULL, NULL, NULL, &t); + } #endif } diff --git a/tests/libtest/lib1560.c b/tests/libtest/lib1560.c index 97d02daeff1..6e734d2bf2d 100644 --- a/tests/libtest/lib1560.c +++ b/tests/libtest/lib1560.c @@ -1045,7 +1045,7 @@ static CURLUcode updateurl(CURLU *u, const char *cmd, unsigned int setflags) while(p) { char *e = strchr(p, ','); if(e) { - size_t n = e-p; + size_t n = (size_t)(e - p); char buf[80]; char part[80]; char value[80]; diff --git a/tests/libtest/lib1947.c b/tests/libtest/lib1947.c index b7a013127a1..c81345f9db2 100644 --- a/tests/libtest/lib1947.c +++ b/tests/libtest/lib1947.c @@ -39,7 +39,7 @@ int test(char *URL) CURLcode res = CURLE_OK; struct curl_header *h; int count = 0; - int origins; + unsigned int origins; global_init(CURL_GLOBAL_DEFAULT); diff --git a/tests/libtest/testutil.c b/tests/libtest/testutil.c index 4a3cd944af2..efbbf9019c4 100644 --- a/tests/libtest/testutil.c +++ b/tests/libtest/testutil.c @@ -37,8 +37,8 @@ struct timeval tutil_tvnow(void) */ struct timeval now; DWORD milliseconds = GetTickCount(); - now.tv_sec = milliseconds / 1000; - now.tv_usec = (milliseconds % 1000) * 1000; + now.tv_sec = (long)(milliseconds / 1000); + now.tv_usec = (long)((milliseconds % 1000) * 1000); return now; } diff --git a/tests/server/mqttd.c b/tests/server/mqttd.c index 0c31376c108..a85f9f80d9e 100644 --- a/tests/server/mqttd.c +++ b/tests/server/mqttd.c @@ -569,7 +569,7 @@ static curl_socket_t mqttit(curl_socket_t fd) goto end; } /* ignore the connect flag byte and two keepalive bytes */ - payload_len = (buffer[10] << 8) | buffer[11]; + payload_len = (size_t)(buffer[10] << 8) | buffer[11]; /* first part of the payload is the client ID */ client_id_length = payload_len; @@ -579,14 +579,16 @@ static curl_socket_t mqttit(curl_socket_t fd) start_usr = client_id_offset + payload_len; if(usr_flag == (unsigned char)(conn_flags & usr_flag)) { logmsg("User flag is present in CONN flag"); - payload_len += (buffer[start_usr] << 8) | buffer[start_usr + 1]; + payload_len += (size_t)(buffer[start_usr] << 8) | + buffer[start_usr + 1]; payload_len += 2; /* MSB and LSB for user length */ } start_passwd = client_id_offset + payload_len; if(passwd_flag == (char)(conn_flags & passwd_flag)) { logmsg("Password flag is present in CONN flags"); - payload_len += (buffer[start_passwd] << 8) | buffer[start_passwd + 1]; + payload_len += (size_t)(buffer[start_passwd] << 8) | + buffer[start_passwd + 1]; payload_len += 2; /* MSB and LSB for password length */ } @@ -631,7 +633,7 @@ static curl_socket_t mqttit(curl_socket_t fd) packet_id = (unsigned short)((buffer[0] << 8) | buffer[1]); /* two bytes topic length */ - topic_len = (buffer[2] << 8) | buffer[3]; + topic_len = (size_t)(buffer[2] << 8) | buffer[3]; if(topic_len != (remaining_length - 5)) { logmsg("Wrong topic length, got %u expected %zu", topic_len, remaining_length - 5); @@ -676,7 +678,7 @@ static curl_socket_t mqttit(curl_socket_t fd) logprotocol(FROM_CLIENT, "PUBLISH", remaining_length, dump, buffer, rc); - topiclen = (buffer[1 + bytes] << 8) | buffer[2 + bytes]; + topiclen = (size_t)(buffer[1 + bytes] << 8) | buffer[2 + bytes]; logmsg("Got %zu bytes topic", topiclen); /* TODO: verify topiclen */ diff --git a/tests/server/util.c b/tests/server/util.c index d6698e5e363..74d6d08072b 100644 --- a/tests/server/util.c +++ b/tests/server/util.c @@ -137,7 +137,7 @@ void logmsg(const char *msg, ...) static const char *win32_strerror(int err, char *buf, size_t buflen) { if(!FormatMessageA((FORMAT_MESSAGE_FROM_SYSTEM | - FORMAT_MESSAGE_IGNORE_INSERTS), NULL, err, + FORMAT_MESSAGE_IGNORE_INSERTS), NULL, (DWORD)err, LANG_NEUTRAL, buf, (DWORD)buflen, NULL)) msnprintf(buf, buflen, "Unknown error %d (%#x)", err, err); return buf; @@ -247,7 +247,7 @@ int wait_ms(int timeout_ms) #if defined(MSDOS) delay(timeout_ms); #elif defined(USE_WINSOCK) - Sleep(timeout_ms); + Sleep((DWORD)timeout_ms); #else pending_ms = timeout_ms; initial_tv = tvnow(); diff --git a/tests/unit/unit1651.c b/tests/unit/unit1651.c index 58d2f107627..63f3393947a 100644 --- a/tests/unit/unit1651.c +++ b/tests/unit/unit1651.c @@ -368,7 +368,7 @@ UNITTEST_START happens */ for(byte = 1 ; byte < 255; byte += 17) { for(i = 0; i < 45; i++) { - char backup = cert[i]; + unsigned char backup = cert[i]; cert[i] = (unsigned char) (byte & 0xff); (void) Curl_extract_certinfo(data, 0, beg, end); cert[i] = backup; From 95a882d26844745f1776fb6c7522b3df57dc9821 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 19 Dec 2023 19:16:03 +0000 Subject: [PATCH 068/509] build: fix `-Wconversion`/`-Wsign-conversion` warnings Fix remaining warnings in examples and tests which are not suppressed by the pragma in `lib/curl_setup.h`. Silence a toolchain issue causing warnings in `FD_SET()` calls with older Cygwin/MSYS2 builds. Likely fixed on 2020-08-03 by: https://cygwin.com/git/?p=newlib-cygwin.git;a=commitdiff;h=5717262b8ecfed0f7fab63e2c09c78991e36f9dd Follow-up to 2dbe75bd7f3c36837aa06fd87a442bdf3fb7faef #12492 Closes #12557 --- docs/examples/10-at-a-time.c | 2 +- docs/examples/anyauthput.c | 12 +++++------- docs/examples/ftpget.c | 2 +- docs/examples/ftpsget.c | 2 +- docs/examples/http2-download.c | 4 ++-- docs/examples/sendrecv.c | 10 ++++++++++ docs/examples/sftpget.c | 2 +- tests/http/clients/h2-download.c | 16 ++++++++-------- tests/server/mqttd.c | 4 ++-- tests/server/socksd.c | 2 +- 10 files changed, 32 insertions(+), 24 deletions(-) diff --git a/docs/examples/10-at-a-time.c b/docs/examples/10-at-a-time.c index 6077750583f..a622410fd32 100644 --- a/docs/examples/10-at-a-time.c +++ b/docs/examples/10-at-a-time.c @@ -95,7 +95,7 @@ static size_t write_cb(char *data, size_t n, size_t l, void *userp) return n*l; } -static void add_transfer(CURLM *cm, int i, int *left) +static void add_transfer(CURLM *cm, unsigned int i, int *left) { CURL *eh = curl_easy_init(); curl_easy_setopt(eh, CURLOPT_WRITEFUNCTION, write_cb); diff --git a/docs/examples/anyauthput.c b/docs/examples/anyauthput.c index 1f4340f4db5..156e8d15245 100644 --- a/docs/examples/anyauthput.c +++ b/docs/examples/anyauthput.c @@ -69,17 +69,15 @@ static int my_seek(void *userp, curl_off_t offset, int origin) /* read callback function, fread() look alike */ static size_t read_callback(char *ptr, size_t size, size_t nmemb, void *stream) { - ssize_t retcode; - unsigned long nread; + size_t nread; - retcode = fread(ptr, size, nmemb, stream); + nread = fread(ptr, size, nmemb, stream); - if(retcode > 0) { - nread = (unsigned long)retcode; - fprintf(stderr, "*** We read %lu bytes from file\n", nread); + if(nread > 0) { + fprintf(stderr, "*** We read %lu bytes from file\n", (unsigned long)nread); } - return retcode; + return nread; } int main(int argc, char **argv) diff --git a/docs/examples/ftpget.c b/docs/examples/ftpget.c index 94609fe0db5..95369c1c02b 100644 --- a/docs/examples/ftpget.c +++ b/docs/examples/ftpget.c @@ -42,7 +42,7 @@ static size_t my_fwrite(void *buffer, size_t size, size_t nmemb, void *stream) /* open file for writing */ out->stream = fopen(out->filename, "wb"); if(!out->stream) - return -1; /* failure, cannot open file to write */ + return 0; /* failure, cannot open file to write */ } return fwrite(buffer, size, nmemb, out->stream); } diff --git a/docs/examples/ftpsget.c b/docs/examples/ftpsget.c index dbe7d14bf7f..dfe80b9f8bc 100644 --- a/docs/examples/ftpsget.c +++ b/docs/examples/ftpsget.c @@ -44,7 +44,7 @@ static size_t my_fwrite(void *buffer, size_t size, size_t nmemb, /* open file for writing */ out->stream = fopen(out->filename, "wb"); if(!out->stream) - return -1; /* failure, cannot open file to write */ + return 0; /* failure, cannot open file to write */ } return fwrite(buffer, size, nmemb, out->stream); } diff --git a/docs/examples/http2-download.c b/docs/examples/http2-download.c index 4c6d46a3d52..5da7ed6035a 100644 --- a/docs/examples/http2-download.c +++ b/docs/examples/http2-download.c @@ -54,7 +54,7 @@ struct transfer { #define NUM_HANDLES 1000 static -void dump(const char *text, int num, unsigned char *ptr, size_t size, +void dump(const char *text, unsigned int num, unsigned char *ptr, size_t size, char nohex) { size_t i; @@ -66,7 +66,7 @@ void dump(const char *text, int num, unsigned char *ptr, size_t size, /* without the hex output, we can fit more on screen */ width = 0x40; - fprintf(stderr, "%d %s, %lu bytes (0x%lx)\n", + fprintf(stderr, "%u %s, %lu bytes (0x%lx)\n", num, text, (unsigned long)size, (unsigned long)size); for(i = 0; istream = fopen(out->filename, "wb"); if(!out->stream) - return -1; /* failure, cannot open file to write */ + return 0; /* failure, cannot open file to write */ } return fwrite(buffer, size, nmemb, out->stream); } diff --git a/tests/http/clients/h2-download.c b/tests/http/clients/h2-download.c index 12c9f8871e7..e6f001c7c1e 100644 --- a/tests/http/clients/h2-download.c +++ b/tests/http/clients/h2-download.c @@ -112,11 +112,11 @@ static size_t my_write_cb(char *buf, size_t nitems, size_t buflen, void *userdata) { struct transfer *t = userdata; - ssize_t nwritten; + size_t nwritten; if(!t->resumed && t->recv_size < t->pause_at && - ((curl_off_t)(t->recv_size + (nitems * buflen)) >= t->pause_at)) { + ((t->recv_size + (curl_off_t)(nitems * buflen)) >= t->pause_at)) { fprintf(stderr, "[t-%d] PAUSE\n", t->idx); t->paused = 1; return CURL_WRITEFUNC_PAUSE; @@ -131,11 +131,11 @@ static size_t my_write_cb(char *buf, size_t nitems, size_t buflen, } nwritten = fwrite(buf, nitems, buflen, t->out); - if(nwritten < 0) { + if(nwritten < buflen) { fprintf(stderr, "[t-%d] write failure\n", t->idx); return 0; } - t->recv_size += nwritten; + t->recv_size += (curl_off_t)nwritten; return (size_t)nwritten; } @@ -171,7 +171,7 @@ static void usage(const char *msg) " download a url with following options:\n" " -m number max parallel downloads\n" " -n number total downloads\n" - " -p number pause transfer after `number` response bytes\n" + " -P number pause transfer after `number` response bytes\n" ); } @@ -185,7 +185,7 @@ int main(int argc, char *argv[]) const char *url; size_t i, n, max_parallel = 1; size_t active_transfers; - long pause_offset = 0; + size_t pause_offset = 0; int abort_paused = 0; struct transfer *t; int ch; @@ -205,7 +205,7 @@ int main(int argc, char *argv[]) transfer_count = (size_t)strtol(optarg, NULL, 10); break; case 'P': - pause_offset = strtol(optarg, NULL, 10); + pause_offset = (size_t)strtol(optarg, NULL, 10); break; default: usage("invalid option"); @@ -234,7 +234,7 @@ int main(int argc, char *argv[]) for(i = 0; i < transfer_count; ++i) { t = &transfers[i]; t->idx = (int)i; - t->pause_at = (curl_off_t)pause_offset * i; + t->pause_at = (curl_off_t)(pause_offset * i); } n = (max_parallel < transfer_count)? max_parallel : transfer_count; diff --git a/tests/server/mqttd.c b/tests/server/mqttd.c index a85f9f80d9e..38918a065d8 100644 --- a/tests/server/mqttd.c +++ b/tests/server/mqttd.c @@ -497,7 +497,7 @@ static curl_socket_t mqttit(curl_socket_t fd) unsigned short packet_id; size_t payload_len; size_t client_id_length; - unsigned int topic_len; + size_t topic_len; size_t remaining_length = 0; size_t bytes = 0; /* remaining length field size in bytes */ char client_id[MAX_CLIENT_ID_LENGTH]; @@ -635,7 +635,7 @@ static curl_socket_t mqttit(curl_socket_t fd) /* two bytes topic length */ topic_len = (size_t)(buffer[2] << 8) | buffer[3]; if(topic_len != (remaining_length - 5)) { - logmsg("Wrong topic length, got %u expected %zu", + logmsg("Wrong topic length, got %zu expected %zu", topic_len, remaining_length - 5); goto end; } diff --git a/tests/server/socksd.c b/tests/server/socksd.c index 179f1fdb251..4ede2ecf2d7 100644 --- a/tests/server/socksd.c +++ b/tests/server/socksd.c @@ -620,7 +620,7 @@ static curl_socket_t sockit(curl_socket_t fd) memcpy(&response[SOCKS5_BNDADDR + len], &buffer[SOCKS5_DSTADDR + len], sizeof(socksport)); - rc = (send)(fd, (char *)response, len + 6, 0); + rc = (send)(fd, (char *)response, (size_t)(len + 6), 0); if(rc != (len + 6)) { logmsg("Sending connect response failed!"); return CURL_SOCKET_BAD; From 8d23a40ba6402f3f5a34102a28940d5d08847f3d Mon Sep 17 00:00:00 2001 From: zengwei2000 <102871671+zengwei2000@users.noreply.github.com> Date: Thu, 21 Dec 2023 02:09:21 +0000 Subject: [PATCH 069/509] altsvc: free 'as' when returning error Closes #12570 Signed-off-by: zengwei --- lib/altsvc.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/altsvc.c b/lib/altsvc.c index 2d46b95c90b..b5fb65fde1d 100644 --- a/lib/altsvc.c +++ b/lib/altsvc.c @@ -106,9 +106,11 @@ static struct altsvc *altsvc_createid(const char *srchost, dlen = strlen(dsthost); DEBUGASSERT(hlen); DEBUGASSERT(dlen); - if(!hlen || !dlen) + if(!hlen || !dlen) { /* bad input */ + free(as); return NULL; + } if((hlen > 2) && srchost[0] == '[') { /* IPv6 address, strip off brackets */ srchost++; From 3cd153d21ab1b5c4d02596469fd295c3186f9ebd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 20 Dec 2023 23:10:38 +0100 Subject: [PATCH 070/509] Makefile.am: fix the MSVC project generation It made the vcxproj files not get included in dist tarballs. Regression since 74423b5df4c8117891eb89 (8.5.0) Reported-by: iAroc on github Fixes #12564 Closes #12567 --- Makefile.am | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Makefile.am b/Makefile.am index c8afcb505ab..d0b1fef59af 100644 --- a/Makefile.am +++ b/Makefile.am @@ -127,8 +127,9 @@ 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-config @@ -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" \ From 000c7381402d03c8de8605d56f55c69bc6dc34ca Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Dec 2023 11:33:02 +0100 Subject: [PATCH 071/509] RELEASE-NOTES: synced Bumped version to 8.6.0 because of changes --- RELEASE-NOTES | 40 ++++++++++++++++++++++++++++++++++------ include/curl/curlver.h | 8 ++++---- 2 files changed, 38 insertions(+), 10 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index bafcfd15a00..7c4ae43a75c 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -1,22 +1,31 @@ -curl and libcurl 8.5.1 +curl and libcurl 8.6.0 Public curl releases: 254 Command line options: 258 - curl_easy_setopt() options: 303 + curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3046 + Contributors: 3052 This release includes the following changes: + o curl.h: add CURLE_TOO_LARGE [48] + o CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add [39] + o runtests: support -gl. Like -g but for lldb. [47] This release includes the following bugfixes: + o altsvc: free 'as' when returning error [23] + o appveyor: switch to out-of-tree builds [29] o build: delete unused `HAVE_{GSSHEIMDAL,GSSMIT,HEIMDAL}` [4] o build: enable missing OpenSSF-recommended warnings, with fixes [11] + o build: fix `-Wconversion`/`-Wsign-conversion` warnings [26] o build: fix Windows ADDRESS_FAMILY detection [35] + o build: more `-Wformat` fixes [40] o build: remove redundant `CURL_PULL_*` settings [8] o CI/distcheck: run full tests [31] + o cmake: fix generation for system name iOS [53] o cmake: fix typo [5] + o cmake: prefill/cache `HAVE_STRUCT_SOCKADDR_STORAGE` [45] o cmdline-docs: use .IP consistently [13] o cmdline/gen: fix the sorting of the man page options [33] o cookie: avoid fopen with empty file name [24] @@ -34,16 +43,20 @@ This release includes the following bugfixes: o lib: strndup/memdup instead of malloc, memcpy and null-terminate [42] o libssh: improve the deprecation warning dismissal [20] o libssh: supress warnings without version check [18] + o Makefile.am: fix the MSVC project generation [22] o Makefile.mk: drop Windows support [12] o openssl: re-match LibreSSL deinit with init [17] o readwrite_data: loop less [21] o Revert "urldata: move async resolver state from easy handle to connectdata" [16] o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] o sendf: fix compiler warning with CURL_DISABLE_HEADERS_API [38] + o ssh: fix namespace of two local macros [51] o system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers [9] o tests/server: delete workaround for old-mingw [25] + o tests: respect $TMPDIR when creating unix domain sockets [50] o url: for disabled protocols, mention if found in redirect [7] o vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY [41] + o windows: delete redundant headers [43] o windows: simplify detecting and using system headers [10] This release includes the following known bugs: @@ -61,9 +74,11 @@ advice from friends like these: Baruch Siach, Ben, Boris Verkhovskiy, Cajus Pollmeier, Chara White, Chris Sauer, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, Dmitry Karpov, - Mauricio Scheffer, Michał Antoniak, Mike Hommey, Ray Satiro, Stefan Eissing, - Tatsuhiko Miyagawa, Theo, Viktor Szakats, Xi Ruoyao, YX Hao - (20 contributors) + iAroc on github, Mark Sinkovics, Mauricio Scheffer, Michał Antoniak, + Mike Hommey, Ray Satiro, Stefan Eissing, Tatsuhiko Miyagawa, Theo, + Viktor Szakats, Xi Ruoyao, Yedaya Katsman, Yifei Kong, YX Hao, zengwei, + zengwei2000 + (26 contributors) References to bug reports and discussions on issues: @@ -88,8 +103,12 @@ References to bug reports and discussions on issues: [19] = https://curl.se/bug/?i=12522 [20] = https://curl.se/bug/?i=12519 [21] = https://curl.se/bug/?i=12504 + [22] = https://curl.se/bug/?i=12564 + [23] = https://curl.se/bug/?i=12570 [24] = https://curl.se/bug/?i=12514 [25] = https://curl.se/bug/?i=12510 + [26] = https://curl.se/bug/?i=12557 + [29] = https://curl.se/bug/?i=12550 [30] = https://curl.se/bug/?i=12499 [31] = https://curl.se/bug/?i=12503 [32] = https://curl.se/bug/?i=12496 @@ -98,6 +117,15 @@ References to bug reports and discussions on issues: [35] = https://curl.se/bug/?i=12441 [36] = https://curl.se/bug/?i=12490 [38] = https://curl.se/bug/?i=12485 + [39] = https://curl.se/bug/?i=12369 + [40] = https://curl.se/bug/?i=12540 [41] = https://curl.se/bug/?i=12459 [42] = https://curl.se/bug/?i=12453 + [43] = https://curl.se/bug/?i=12539 [44] = https://curl.se/bug/?i=12456 + [45] = https://curl.se/bug/?i=12537 + [47] = https://curl.se/bug/?i=12547 + [48] = https://curl.se/bug/?i=12269 + [50] = https://curl.se/bug/?i=12545 + [51] = https://curl.se/bug/?i=12544 + [53] = https://curl.se/bug/?i=12515 diff --git a/include/curl/curlver.h b/include/curl/curlver.h index 3d0c7279814..316f39c4ec6 100644 --- a/include/curl/curlver.h +++ b/include/curl/curlver.h @@ -32,13 +32,13 @@ /* This is the version number of the libcurl package from which this header file origins: */ -#define LIBCURL_VERSION "8.5.1-DEV" +#define LIBCURL_VERSION "8.6.0-DEV" /* The numeric version number is also available "in parts" by using these defines: */ #define LIBCURL_VERSION_MAJOR 8 -#define LIBCURL_VERSION_MINOR 5 -#define LIBCURL_VERSION_PATCH 1 +#define LIBCURL_VERSION_MINOR 6 +#define LIBCURL_VERSION_PATCH 0 /* This is the numeric version of the libcurl version number, meant for easier parsing and comparisons by programs. The LIBCURL_VERSION_NUM define will @@ -59,7 +59,7 @@ CURL_VERSION_BITS() macro since curl's own configure script greps for it and needs it to contain the full number. */ -#define LIBCURL_VERSION_NUM 0x080501 +#define LIBCURL_VERSION_NUM 0x080600 /* * This is the date and time when the full source package was created. The From d187f5194813463b0bae4d4d5a3368e0ffcdfe54 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Dec 2023 09:50:00 +0100 Subject: [PATCH 072/509] tool_getparam: do not try to expand without an argument This would lead to a segfault. Fixes #12565 Reported-by: Geeknik Labs Closes #12575 --- src/tool_getparam.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 6b256f8224e..79110eb7d2a 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -822,7 +822,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_NO_NOT_BOOLEAN; goto error; } - else if(expand) { + else if(expand && nextarg) { struct curlx_dynbuf nbuf; bool replaced; From ff41ac8ca2b0e2fb90a7665e94b880036b91e966 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Dec 2023 09:52:24 +0100 Subject: [PATCH 073/509] test460: verify a command line using --expand with no argument This verifies the fix for #12565 --- tests/data/Makefile.inc | 2 +- tests/data/test460 | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 tests/data/test460 diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 6d1a2ad13b6..485472271e1 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -72,7 +72,7 @@ test417 test418 test419 test420 test421 test422 test423 test424 test425 \ test426 test427 test428 test429 test430 test431 test432 test433 test434 \ test435 test436 test437 test438 test439 test440 test441 test442 test443 \ test444 test445 test446 test447 test448 test449 test450 test451 test452 \ -test453 test454 test455 test456 test457 test458 test459 \ +test453 test454 test455 test456 test457 test458 test459 test460 \ \ test490 test491 test492 test493 test494 test495 test496 test497 test498 \ \ diff --git a/tests/data/test460 b/tests/data/test460 new file mode 100644 index 00000000000..824166a81bb --- /dev/null +++ b/tests/data/test460 @@ -0,0 +1,28 @@ + + + +variables +expand + + + +# Client-side + + +none + + +try --expand without an argument + + +--expand-url + + + +# + + +2 + + + From 98794c56af0287879177a212bb414e2f9214ded9 Mon Sep 17 00:00:00 2001 From: ivanfywang Date: Thu, 21 Dec 2023 17:06:47 +0800 Subject: [PATCH 074/509] ngtcp2: put h3 at the front of alpn Closes #12576 --- lib/vquic/curl_ngtcp2.c | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index 0d0f2fab39b..fb1ef60a0a4 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -580,8 +580,8 @@ static CURLcode quic_init_ssl(struct Curl_cfilter *cf, SSL_set_connect_state(ctx->ssl); SSL_set_quic_use_legacy_codepoint(ctx->ssl, 0); - alpn = (const uint8_t *)H3_ALPN_H3_29 H3_ALPN_H3; - alpnlen = sizeof(H3_ALPN_H3_29) - 1 + sizeof(H3_ALPN_H3) - 1; + alpn = (const uint8_t *)H3_ALPN_H3 H3_ALPN_H3_29; + alpnlen = sizeof(H3_ALPN_H3) - 1 + sizeof(H3_ALPN_H3_29) - 1; if(alpn) SSL_set_alpn_protos(ctx->ssl, alpn, (int)alpnlen); @@ -644,10 +644,10 @@ static CURLcode quic_init_ssl(struct Curl_cfilter *cf, } /* strip the first byte (the length) from NGHTTP3_ALPN_H3 */ - alpn[0].data = (unsigned char *)H3_ALPN_H3_29 + 1; - alpn[0].size = sizeof(H3_ALPN_H3_29) - 2; - alpn[1].data = (unsigned char *)H3_ALPN_H3 + 1; - alpn[1].size = sizeof(H3_ALPN_H3) - 2; + alpn[0].data = (unsigned char *)H3_ALPN_H3 + 1; + alpn[0].size = sizeof(H3_ALPN_H3) - 2; + alpn[1].data = (unsigned char *)H3_ALPN_H3_29 + 1; + alpn[1].size = sizeof(H3_ALPN_H3_29) - 2; gnutls_alpn_set_protocols(ctx->gtls->session, alpn, 2, GNUTLS_ALPN_MANDATORY); @@ -782,8 +782,8 @@ static CURLcode quic_init_ssl(struct Curl_cfilter *cf, wolfSSL_set_connect_state(ctx->ssl); wolfSSL_set_quic_use_legacy_codepoint(ctx->ssl, 0); - alpn = (const uint8_t *)H3_ALPN_H3_29 H3_ALPN_H3; - alpnlen = sizeof(H3_ALPN_H3_29) - 1 + sizeof(H3_ALPN_H3) - 1; + alpn = (const uint8_t *)H3_ALPN_H3 H3_ALPN_H3_29; + alpnlen = sizeof(H3_ALPN_H3) - 1 + sizeof(H3_ALPN_H3_29) - 1; if(alpn) wolfSSL_set_alpn_protos(ctx->ssl, alpn, (int)alpnlen); From 5d2b0faec219db1cea07ef0ca6c804c4f172f93d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Dec 2023 08:48:21 +0100 Subject: [PATCH 075/509] CURLOPT_SSH_*_KEYFILE: clarify Closes #12554 --- docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 | 9 +++++++-- docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 | 7 ++++--- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 index 12cc5410da7..974a5b786da 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 @@ -34,12 +34,17 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PRIVATE_KEYFILE, .SH DESCRIPTION Pass a char * pointing to a \fIfilename\fP for your private key. If not used, libcurl defaults to \fB$HOME/.ssh/id_rsa\fP or \fB$HOME/.ssh/id_dsa\fP if the -HOME environment variable is set, and just \fB"id_rsa"\fP or \fB"id_dsa"\fP in -the current directory if HOME is not set. +HOME environment variable is set, and in the current directory if HOME is not +set. If the file is password-protected, set the password with \fICURLOPT_KEYPASSWD(3)\fP. +The SSH library derives the public key from this private key when possible. If +the SSH library cannot derive the public key from the private one and no +public one is provided with \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP, the transfer +fails. + The application does not have to keep the string around after setting this option. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 index 93d9241e08a..6a1d6991bfb 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 @@ -37,9 +37,10 @@ libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment variable is set, and just "id_dsa.pub" in the current directory if HOME is not set. -If NULL (or an empty string) is passed, libcurl passes no public key to -libssh2, which then computes it from the private key. This is known to work -with libssh2 1.4.0+ linked against OpenSSL. +If NULL (or an empty string) is passed to this option, libcurl passes no +public key to the SSH library, which then rather derives it from the private +key. If the SSH library cannot derive the public key from the private one and +no public one is provided, the transfer fails. The application does not have to keep the string around after setting this option. From a719be81e999bae2895306b7ef5b181f3a02cc10 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Dec 2023 17:50:29 +0100 Subject: [PATCH 076/509] strerror: repair get_winsock_error() It would try to read longer than the provided string and crash. Follow-up to ff74cef5d4a0cf60106517a1c7384 Reported-by: calvin2021y on github Fixes #12578 Closes #12579 --- lib/strerror.c | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/strerror.c b/lib/strerror.c index e35193a48c2..a900e78d151 100644 --- a/lib/strerror.c +++ b/lib/strerror.c @@ -582,11 +582,10 @@ get_winsock_error(int err, char *buf, size_t len) { #ifndef CURL_DISABLE_VERBOSE_STRINGS const char *p; + size_t alen; #endif - /* 41 bytes is the longest error string */ - DEBUGASSERT(len > 41); - if(!len || len < 41) + if(!len) return NULL; *buf = '\0'; @@ -763,8 +762,9 @@ get_winsock_error(int err, char *buf, size_t len) default: return NULL; } - memcpy(buf, p, len - 1); - buf[len - 1] = '\0'; + alen = strlen(p); + if(alen < len) + strcpy(buf, p); return buf; #endif } From a6bbc87f9e9ffb46a1801dfb983e7534825ed56b Mon Sep 17 00:00:00 2001 From: Pavel P Date: Fri, 17 Nov 2023 10:56:08 +0200 Subject: [PATCH 077/509] asyn-thread: use GetAddrInfoExW on >= Windows 8 For doing async DNS resolution instead of starting a thread for each request. Fixes #12481 Closes #12482 --- lib/asyn-thread.c | 218 +++++++++++++++++++++++++++++++++++++++++++++ lib/system_win32.c | 33 +++++++ lib/system_win32.h | 26 +++++- 3 files changed, 276 insertions(+), 1 deletion(-) diff --git a/lib/asyn-thread.c b/lib/asyn-thread.c index a48f3f4ef0a..8646d72e939 100644 --- a/lib/asyn-thread.c +++ b/lib/asyn-thread.c @@ -54,6 +54,7 @@ # define RESOLVER_ENOMEM ENOMEM #endif +#include "system_win32.h" #include "urldata.h" #include "sendf.h" #include "hostip.h" @@ -144,9 +145,22 @@ static bool init_resolve_thread(struct Curl_easy *data, const char *hostname, int port, const struct addrinfo *hints); +#ifdef _WIN32 +/* Thread sync data used by GetAddrInfoExW for win8+ */ +struct thread_sync_data_w8 +{ + OVERLAPPED overlapped; + ADDRINFOEXW_ *res; + HANDLE cancel_ev; + ADDRINFOEXW_ hints; +}; +#endif /* Data for synchronization between resolver thread and its parent */ struct thread_sync_data { +#ifdef _WIN32 + struct thread_sync_data_w8 w8; +#endif curl_mutex_t *mtx; int done; int port; @@ -165,6 +179,9 @@ struct thread_sync_data { }; struct thread_data { +#ifdef _WIN32 + HANDLE complete_ev; +#endif curl_thread_t thread_hnd; unsigned int poll_interval; timediff_t interval_end; @@ -276,6 +293,144 @@ static CURLcode getaddrinfo_complete(struct Curl_easy *data) return result; } +#ifdef _WIN32 +static VOID WINAPI +query_complete(DWORD err, DWORD bytes, LPWSAOVERLAPPED overlapped) +{ + size_t ss_size; + const ADDRINFOEXW_ *ai; + struct Curl_addrinfo *ca; + struct Curl_addrinfo *cafirst = NULL; + struct Curl_addrinfo *calast = NULL; + struct thread_sync_data *tsd = + CONTAINING_RECORD(overlapped, struct thread_sync_data, w8.overlapped); + struct thread_data *td = tsd->td; + const ADDRINFOEXW_ *res = tsd->w8.res; + int error = (int)err; + (void)bytes; + + if(error == ERROR_SUCCESS) { + /* traverse the addrinfo list */ + + for(ai = res; ai != NULL; ai = ai->ai_next) { + size_t namelen = ai->ai_canonname ? wcslen(ai->ai_canonname) + 1 : 0; + /* ignore elements with unsupported address family, */ + /* settle family-specific sockaddr structure size. */ + if(ai->ai_family == AF_INET) + ss_size = sizeof(struct sockaddr_in); +#ifdef ENABLE_IPV6 + else if(ai->ai_family == AF_INET6) + ss_size = sizeof(struct sockaddr_in6); +#endif + else + continue; + + /* ignore elements without required address info */ + if(!ai->ai_addr || !(ai->ai_addrlen > 0)) + continue; + + /* ignore elements with bogus address size */ + if((size_t)ai->ai_addrlen < ss_size) + continue; + + ca = malloc(sizeof(struct Curl_addrinfo) + ss_size + namelen); + if(!ca) { + error = EAI_MEMORY; + break; + } + + /* copy each structure member individually, member ordering, */ + /* size, or padding might be different for each platform. */ + ca->ai_flags = ai->ai_flags; + ca->ai_family = ai->ai_family; + ca->ai_socktype = ai->ai_socktype; + ca->ai_protocol = ai->ai_protocol; + ca->ai_addrlen = (curl_socklen_t)ss_size; + ca->ai_addr = NULL; + ca->ai_canonname = NULL; + ca->ai_next = NULL; + + ca->ai_addr = (void *)((char *)ca + sizeof(struct Curl_addrinfo)); + memcpy(ca->ai_addr, ai->ai_addr, ss_size); + + if(namelen) { + size_t i; + ca->ai_canonname = (void *)((char *)ca->ai_addr + ss_size); + for(i = 0; i < namelen; ++i) /* convert wide string to ascii */ + ca->ai_canonname[i] = (char)ai->ai_canonname[i]; + ca->ai_canonname[namelen] = '\0'; + } + + /* if the return list is empty, this becomes the first element */ + if(!cafirst) + cafirst = ca; + + /* add this element last in the return list */ + if(calast) + calast->ai_next = ca; + calast = ca; + } + + /* if we failed, also destroy the Curl_addrinfo list */ + if(error) { + Curl_freeaddrinfo(cafirst); + cafirst = NULL; + } + else if(!cafirst) { +#ifdef EAI_NONAME + /* rfc3493 conformant */ + error = EAI_NONAME; +#else + /* rfc3493 obsoleted */ + error = EAI_NODATA; +#endif +#ifdef USE_WINSOCK + SET_SOCKERRNO(error); +#endif + } + tsd->res = cafirst; + } + + if(tsd->w8.res) { + Curl_FreeAddrInfoExW(tsd->w8.res); + tsd->w8.res = NULL; + } + + if(error) { + tsd->sock_error = SOCKERRNO?SOCKERRNO:error; + if(tsd->sock_error == 0) + tsd->sock_error = RESOLVER_ENOMEM; + } + else { + Curl_addrinfo_set_port(tsd->res, tsd->port); + } + + Curl_mutex_acquire(tsd->mtx); + if(tsd->done) { + /* too late, gotta clean up the mess */ + Curl_mutex_release(tsd->mtx); + destroy_thread_sync_data(tsd); + free(td); + } + else { +#ifndef CURL_DISABLE_SOCKETPAIR + char buf[1]; + if(tsd->sock_pair[1] != CURL_SOCKET_BAD) { + /* DNS has been resolved, signal client task */ + buf[0] = 1; + if(swrite(tsd->sock_pair[1], buf, sizeof(buf)) < 0) { + /* update sock_erro to errno */ + tsd->sock_error = SOCKERRNO; + } + } +#endif + tsd->done = 1; + Curl_mutex_release(tsd->mtx); + if(td->complete_ev) + SetEvent(td->complete_ev); /* Notify caller that the query completed */ + } +} +#endif #ifdef HAVE_GETADDRINFO @@ -391,9 +546,21 @@ static void destroy_async_data(struct Curl_async *async) Curl_mutex_release(td->tsd.mtx); if(!done) { +#ifdef _WIN32 + if(td->complete_ev) + CloseHandle(td->complete_ev); + else +#endif Curl_thread_destroy(td->thread_hnd); } else { +#ifdef _WIN32 + if(td->complete_ev) { + Curl_GetAddrInfoExCancel(&td->tsd.w8.cancel_ev); + WaitForSingleObject(td->complete_ev, INFINITE); + CloseHandle(td->complete_ev); + } +#endif if(td->thread_hnd != curl_thread_t_null) Curl_thread_join(&td->thread_hnd); @@ -439,6 +606,9 @@ static bool init_resolve_thread(struct Curl_easy *data, asp->status = 0; asp->dns = NULL; td->thread_hnd = curl_thread_t_null; +#ifdef _WIN32 + td->complete_ev = NULL; +#endif if(!init_thread_sync_data(td, hostname, port, hints)) { asp->tdata = NULL; @@ -454,6 +624,41 @@ static bool init_resolve_thread(struct Curl_easy *data, /* The thread will set this to 1 when complete. */ td->tsd.done = 0; +#ifdef _WIN32 + if(Curl_isWindows8OrGreater && Curl_FreeAddrInfoExW && + Curl_GetAddrInfoExCancel && Curl_GetAddrInfoExW) { +#define MAX_NAME_LEN 256 /* max domain name is 253 chars */ +#define MAX_PORT_LEN 8 + WCHAR namebuf[MAX_NAME_LEN]; + WCHAR portbuf[MAX_PORT_LEN]; + /* calculate required length */ + int w_len = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, hostname, + -1, NULL, 0); + if((w_len > 0) && (w_len < MAX_NAME_LEN)) { + /* do utf8 conversion */ + w_len = MultiByteToWideChar(CP_UTF8, 0, hostname, -1, namebuf, w_len); + if((w_len > 0) && (w_len < MAX_NAME_LEN)) { + swprintf(portbuf, MAX_PORT_LEN, L"%d", port); + td->tsd.w8.hints.ai_family = hints->ai_family; + td->tsd.w8.hints.ai_socktype = hints->ai_socktype; + td->complete_ev = CreateEvent(NULL, TRUE, FALSE, NULL); + if(!td->complete_ev) { + /* failed to start, mark it as done here for proper cleanup. */ + td->tsd.done = 1; + goto err_exit; + } + err = Curl_GetAddrInfoExW(namebuf, portbuf, NS_DNS, + NULL, &td->tsd.w8.hints, &td->tsd.w8.res, + NULL, &td->tsd.w8.overlapped, + &query_complete, &td->tsd.w8.cancel_ev); + if(err != WSA_IO_PENDING) + query_complete(err, 0, &td->tsd.w8.overlapped); + return TRUE; + } + } + } +#endif + #ifdef HAVE_GETADDRINFO td->thread_hnd = Curl_thread_create(getaddrinfo_thread, &td->tsd); #else @@ -490,9 +695,22 @@ static CURLcode thread_wait_resolv(struct Curl_easy *data, DEBUGASSERT(data); td = data->state.async.tdata; DEBUGASSERT(td); +#ifdef _WIN32 + DEBUGASSERT(td->complete_ev || td->thread_hnd != curl_thread_t_null); +#else DEBUGASSERT(td->thread_hnd != curl_thread_t_null); +#endif /* wait for the thread to resolve the name */ +#ifdef _WIN32 + if(td->complete_ev) { + WaitForSingleObject(td->complete_ev, INFINITE); + CloseHandle(td->complete_ev); + if(entry) + result = getaddrinfo_complete(data); + } + else +#endif if(Curl_thread_join(&td->thread_hnd)) { if(entry) result = getaddrinfo_complete(data); diff --git a/lib/system_win32.c b/lib/system_win32.c index 9408d026b17..dd34140d726 100644 --- a/lib/system_win32.c +++ b/lib/system_win32.c @@ -38,6 +38,7 @@ LARGE_INTEGER Curl_freq; bool Curl_isVistaOrGreater; +bool Curl_isWindows8OrGreater; /* Handle of iphlpapp.dll */ static HMODULE s_hIpHlpApiDll = NULL; @@ -45,9 +46,19 @@ static HMODULE s_hIpHlpApiDll = NULL; /* Pointer to the if_nametoindex function */ IF_NAMETOINDEX_FN Curl_if_nametoindex = NULL; +void(WSAAPI *Curl_FreeAddrInfoExW)(ADDRINFOEXW_ *pAddrInfoEx) = NULL; +int(WSAAPI *Curl_GetAddrInfoExCancel)(LPHANDLE lpHandle) = NULL; +int(WSAAPI *Curl_GetAddrInfoExW)(PCWSTR pName, PCWSTR pServiceName, + DWORD dwNameSpace, LPGUID lpNspId, const ADDRINFOEXW_ *hints, + ADDRINFOEXW_ **ppResult, struct timeval *timeout, LPOVERLAPPED lpOverlapped, + LOOKUP_COMPLETION lpCompletionRoutine, LPHANDLE lpHandle) = NULL; + /* Curl_win32_init() performs win32 global initialization */ CURLcode Curl_win32_init(long flags) { +#ifdef USE_WINSOCK + HANDLE ws2_32Dll; +#endif /* CURL_GLOBAL_WIN32 controls the *optional* part of the initialization which is just for Winsock at the moment. Any required win32 initialization should take place after this block. */ @@ -104,6 +115,18 @@ CURLcode Curl_win32_init(long flags) Curl_if_nametoindex = pIfNameToIndex; } +#ifdef USE_WINSOCK + ws2_32Dll = GetModuleHandleA("ws2_32"); + if(ws2_32Dll) { + *(FARPROC*)&Curl_FreeAddrInfoExW = GetProcAddress(ws2_32Dll, + "FreeAddrInfoExW"); + *(FARPROC*)&Curl_GetAddrInfoExCancel = GetProcAddress(ws2_32Dll, + "GetAddrInfoExCancel"); + *(FARPROC*)&Curl_GetAddrInfoExW = GetProcAddress(ws2_32Dll, + "GetAddrInfoExW"); + } +#endif + /* curlx_verify_windows_version must be called during init at least once because it has its own initialization routine. */ if(curlx_verify_windows_version(6, 0, 0, PLATFORM_WINNT, @@ -113,6 +136,13 @@ CURLcode Curl_win32_init(long flags) else Curl_isVistaOrGreater = FALSE; + if(curlx_verify_windows_version(6, 2, 0, PLATFORM_WINNT, + VERSION_GREATER_THAN_EQUAL)) { + Curl_isWindows8OrGreater = TRUE; + } + else + Curl_isWindows8OrGreater = FALSE; + QueryPerformanceFrequency(&Curl_freq); return CURLE_OK; } @@ -120,6 +150,9 @@ CURLcode Curl_win32_init(long flags) /* Curl_win32_cleanup() is the opposite of Curl_win32_init() */ void Curl_win32_cleanup(long init_flags) { + Curl_FreeAddrInfoExW = NULL; + Curl_GetAddrInfoExCancel = NULL; + Curl_GetAddrInfoExW = NULL; if(s_hIpHlpApiDll) { FreeLibrary(s_hIpHlpApiDll); s_hIpHlpApiDll = NULL; diff --git a/lib/system_win32.h b/lib/system_win32.h index 2566766681f..42bbb143f31 100644 --- a/lib/system_win32.h +++ b/lib/system_win32.h @@ -26,10 +26,11 @@ #include "curl_setup.h" -#if defined(_WIN32) +#ifdef _WIN32 extern LARGE_INTEGER Curl_freq; extern bool Curl_isVistaOrGreater; +extern bool Curl_isWindows8OrGreater; CURLcode Curl_win32_init(long flags); void Curl_win32_cleanup(long init_flags); @@ -40,6 +41,29 @@ typedef unsigned int(WINAPI *IF_NAMETOINDEX_FN)(const char *); /* This is used instead of if_nametoindex if available on Windows */ extern IF_NAMETOINDEX_FN Curl_if_nametoindex; +/* Identical copy of addrinfoexW/ADDRINFOEXW */ +typedef struct addrinfoexW_ +{ + int ai_flags; + int ai_family; + int ai_socktype; + int ai_protocol; + size_t ai_addrlen; + PWSTR ai_canonname; + struct sockaddr *ai_addr; + void *ai_blob; + size_t ai_bloblen; + LPGUID ai_provider; + struct addrinfoexW_ *ai_next; +} ADDRINFOEXW_; + +typedef void(CALLBACK *LOOKUP_COMPLETION)(DWORD, DWORD, LPWSAOVERLAPPED); +extern void(WSAAPI *Curl_FreeAddrInfoExW)(ADDRINFOEXW_*); +extern int(WSAAPI *Curl_GetAddrInfoExCancel)(LPHANDLE); +extern int(WSAAPI *Curl_GetAddrInfoExW)(PCWSTR, PCWSTR, DWORD, LPGUID, + const ADDRINFOEXW_*, ADDRINFOEXW_**, struct timeval*, LPOVERLAPPED, + LOOKUP_COMPLETION, LPHANDLE); + /* This is used to dynamically load DLLs */ HMODULE Curl_load_library(LPCTSTR filename); #else /* _WIN32 */ From 2d4d0c1fd32f5cc3f946c407c8eccd5477b287df Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Thu, 21 Dec 2023 03:59:20 +0000 Subject: [PATCH 078/509] appveyor: replace PowerShell with bash + parallel autotools PowerShell works (after a steep development curve), but one property of it stuck and kept causing unresolvable usability issues: With `$ErrorActionPreference=Stop`, it does abort on failures, but shows only the first line of the error message. In `Continue` mode, it shows the full error message, but doesn't stop on all errors. Another issue is PowerShell considering any stderr output as if the command failed (this has been improved in 7.2 (2021-Nov), but fixed versions aren't running in CI and will not be for a long time in all test images.) Thus, we're going with bash. Also: - use `-j2` with autotools tests, making them finish 5-15 minutes per job faster. - omit `POSIX_PATH_PREFIX`. - use `WINDIR`. - prefer forward slashes. Follow-up to: 75078a415d9c769419aed4153d3d525a8eba95af #11999 Ref: #12444 Fixes #12560 Closes #12572 --- .azure-pipelines.yml | 4 +- .cirrus.yml | 2 +- .github/labeler.yml | 4 +- .github/workflows/awslc.yml | 4 +- .github/workflows/codeql-analysis.yml | 4 +- .github/workflows/fuzz.yml | 4 +- .github/workflows/linux.yml | 4 +- .github/workflows/linux32.yml | 4 +- .github/workflows/macos.yml | 4 +- .github/workflows/ngtcp2-linux.yml | 4 +- .github/workflows/quiche-linux.yml | 4 +- .github/workflows/torture.yml | 4 +- .github/workflows/wolfssl.yml | 4 +- appveyor.sh | 156 +++++++++++++++++++++++++ appveyor.yml | 162 ++------------------------ 15 files changed, 193 insertions(+), 175 deletions(-) create mode 100644 appveyor.sh diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml index 049e4673364..12ecad3f8aa 100644 --- a/.azure-pipelines.yml +++ b/.azure-pipelines.yml @@ -37,7 +37,7 @@ trigger: - '.cirrus.yml' - '.github/*' - '.github/workflows/*' - - 'appveyor.yml' + - 'appveyor.*' - 'packages/*' - 'plan9/*' @@ -51,7 +51,7 @@ pr: - '.cirrus.yml' - '.github/*' - '.github/workflows/*' - - 'appveyor.yml' + - 'appveyor.*' - 'packages/*' - 'plan9/*' diff --git a/.cirrus.yml b/.cirrus.yml index 8878205e5de..3d327259c33 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -32,7 +32,7 @@ freebsd_task: '.azure-pipelines.yml', '.circleci/**', '.github/**', - 'appveyor.yml', + 'appveyor.*', 'CMake/**', 'packages/**', 'plan9/**', diff --git a/.github/labeler.yml b/.github/labeler.yml index 4f87314d282..916219c0469 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -84,7 +84,7 @@ CI: - '.circleci/**' - '.cirrus.yml' - '.github/**' - - 'appveyor.yml' + - 'appveyor.*' - 'scripts/ci*' - 'tests/azure.pm' - 'tests/appveyor.pm' @@ -481,7 +481,7 @@ Windows: - all: - changed-files: - any-glob-to-all-files: - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/Platforms/WindowsCache.cmake' - 'lib/*win32*' - 'lib/curl_multibyte.*' diff --git a/.github/workflows/awslc.yml b/.github/workflows/awslc.yml index 2505a46022f..c600d72d50d 100644 --- a/.github/workflows/awslc.yml +++ b/.github/workflows/awslc.yml @@ -14,7 +14,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'packages/**' - 'plan9/**' - 'projects/**' @@ -27,7 +27,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'packages/**' - 'plan9/**' - 'projects/**' diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 800b01ac9d9..40d6545882d 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -14,7 +14,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'docs/**' - 'packages/**' - 'plan9/**' @@ -29,7 +29,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'docs/**' - 'packages/**' - 'plan9/**' diff --git a/.github/workflows/fuzz.yml b/.github/workflows/fuzz.yml index a382dcb6adb..247a1c0abe4 100644 --- a/.github/workflows/fuzz.yml +++ b/.github/workflows/fuzz.yml @@ -15,7 +15,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' @@ -31,7 +31,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index b4ad111f80e..81e489ff272 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -14,7 +14,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'packages/**' - 'plan9/**' - 'projects/**' @@ -27,7 +27,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'packages/**' - 'plan9/**' - 'projects/**' diff --git a/.github/workflows/linux32.yml b/.github/workflows/linux32.yml index 1afc9cac4f7..e3fca3d1d20 100644 --- a/.github/workflows/linux32.yml +++ b/.github/workflows/linux32.yml @@ -15,7 +15,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' @@ -30,7 +30,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml index 4a7d6917cca..49bb86cb486 100644 --- a/.github/workflows/macos.yml +++ b/.github/workflows/macos.yml @@ -14,7 +14,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'packages/**' - 'plan9/**' - 'projects/**' @@ -27,7 +27,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'packages/**' - 'plan9/**' - 'projects/**' diff --git a/.github/workflows/ngtcp2-linux.yml b/.github/workflows/ngtcp2-linux.yml index 3be5c108f23..84149f57c10 100644 --- a/.github/workflows/ngtcp2-linux.yml +++ b/.github/workflows/ngtcp2-linux.yml @@ -15,7 +15,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' @@ -30,7 +30,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' diff --git a/.github/workflows/quiche-linux.yml b/.github/workflows/quiche-linux.yml index abc71a5725b..fd1740295ee 100644 --- a/.github/workflows/quiche-linux.yml +++ b/.github/workflows/quiche-linux.yml @@ -15,7 +15,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' @@ -30,7 +30,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' diff --git a/.github/workflows/torture.yml b/.github/workflows/torture.yml index b5f187d8c9e..a50b37f140c 100644 --- a/.github/workflows/torture.yml +++ b/.github/workflows/torture.yml @@ -15,7 +15,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' @@ -30,7 +30,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' diff --git a/.github/workflows/wolfssl.yml b/.github/workflows/wolfssl.yml index f607c0bcc83..d8f0fd4271f 100644 --- a/.github/workflows/wolfssl.yml +++ b/.github/workflows/wolfssl.yml @@ -15,7 +15,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' @@ -30,7 +30,7 @@ on: - '.azure-pipelines.yml' - '.circleci/**' - '.cirrus.yml' - - 'appveyor.yml' + - 'appveyor.*' - 'CMake/**' - 'packages/**' - 'plan9/**' diff --git a/appveyor.sh b/appveyor.sh new file mode 100644 index 00000000000..4a345ff8899 --- /dev/null +++ b/appveyor.sh @@ -0,0 +1,156 @@ +#!/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 + acurl='' + [ -x "$(cygpath -u "C:/msys64/usr/bin/curl.exe")" ] && acurl="-ac $(cygpath -u "C:/msys64/usr/bin/curl.exe")" + [ -x "$(cygpath -u "${WINDIR}/System32/curl.exe")" ] && acurl="-ac $(cygpath -u "${WINDIR}/System32/curl.exe")" + if [ "${BUILD_SYSTEM}" = 'CMake' ]; then + ls _bld/lib/*.dll >/dev/null 2>&1 && cp -f -p _bld/lib/*.dll _bld/tests/libtest/ + TFLAGS="${acurl} ${DISABLED_TESTS:-}" cmake --build _bld --config "${PRJ_CFG}" --target test-ci + elif [ "${BUILD_SYSTEM}" = 'autotools' ]; then + ( + cd _bld + make -j2 V=1 TFLAGS="${acurl} ${DISABLED_TESTS:-}" test-ci + ) + else + ( + cd _bld/tests + # shellcheck disable=SC2086 + ./runtests.pl -a -p !flaky -r -rm ${acurl} ${DISABLED_TESTS:-} + ) + fi +fi diff --git a/appveyor.yml b/appveyor.yml index 86a5f8b64d5..f4911452ae5 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -85,7 +85,6 @@ environment: HTTP_ONLY: 'OFF' TESTING: 'ON' DISABLED_TESTS: '!1139 !1501' - ADD_PATH: 'C:\msys64\usr\bin' - job_name: 'CMake, VS2022, Debug, x64, Schannel, Static, Unicode' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022' BUILD_SYSTEM: CMake @@ -97,7 +96,6 @@ environment: HTTP_ONLY: 'OFF' TESTING: 'ON' DISABLED_TESTS: '!1139 !1501' - ADD_PATH: 'C:\msys64\usr\bin' - job_name: 'CMake, VS2022, Debug, x64, no SSL, Static' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022' BUILD_SYSTEM: CMake @@ -109,7 +107,6 @@ environment: HTTP_ONLY: 'OFF' TESTING: 'ON' DISABLED_TESTS: '!1139 !1501' - ADD_PATH: 'C:\msys64\usr\bin' - job_name: 'CMake, VS2022, Debug, x64, no SSL, Static, HTTP only' APPVEYOR_BUILD_WORKER_IMAGE: 'Visual Studio 2022' BUILD_SYSTEM: CMake @@ -121,7 +118,6 @@ environment: HTTP_ONLY: 'ON' TESTING: 'ON' DISABLED_TESTS: '!1139 !1501' - ADD_PATH: 'C:\msys64\usr\bin' # 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' @@ -133,7 +129,7 @@ environment: HTTP_ONLY: 'OFF' TESTING: 'ON' DISABLED_TESTS: '!1086 !1139 !1451 !1501' - ADD_PATH: 'C:\msys64\mingw64\bin;C:\msys64\usr\bin' + ADD_PATH: 'C:/msys64/mingw64/bin' MSYS2_ARG_CONV_EXCL: '/*' BUILD_OPT: -k UNITY: 'ON' @@ -147,7 +143,7 @@ environment: 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' + 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' @@ -161,7 +157,7 @@ environment: 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' + ADD_PATH: 'C:/msys64/mingw64/bin' MSYS2_ARG_CONV_EXCL: '/*' BUILD_OPT: -k UNITY: 'ON' @@ -175,7 +171,7 @@ environment: 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' + 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,21 +244,18 @@ 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' - 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' - 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' # autotools-based Cygwin build - job_name: 'autotools, cygwin, Debug, x86_64, no SSL' @@ -270,154 +263,23 @@ environment: BUILD_SYSTEM: autotools TESTING: 'ON' DISABLED_TESTS: '' - ADD_PATH: 'C:\cygwin64\bin' + ADD_SHELL: 'C:/cygwin64/bin' CONFIG_ARGS: '--enable-debug --enable-werror --disable-threaded-resolver --without-ssl --enable-websockets' - POSIX_PATH_PREFIX: '/cygdrive' 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 -B _bld $options - cmake --build _bld --config $env:PRJ_CFG --parallel 2 --clean-first -- $env:BUILD_OPT - if($env:SHARED -eq 'ON') { - Copy-Item -Path 'C:\Projects\curl\_bld\lib\*.dll' -Destination 'C:\projects\curl\_bld\src' - } - if($env:OPENSSL -eq 'ON') { - Copy-Item -Path "$openssl_root\*.dll" -Destination 'C:\projects\curl\_bld\src' - } - $curl = '.\_bld\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 && mkdir _bld && cd _bld && ../configure $env:CONFIG_ARGS 2>&1 && make V=1 && make V=1 examples && cd tests && make V=1" - $curl = '.\_bld\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 _bld/CMakeFiles/CMakeConfigureLog.yaml) { cat _bld/CMakeFiles/CMakeConfigureLog.yaml } - if(Test-Path _bld/CMakeFiles/CMakeOutput.log) { cat _bld/CMakeFiles/CMakeOutput.log } - if(Test-Path _bld/CMakeFiles/CMakeError.log) { cat _bld/CMakeFiles/CMakeError.log } - if(Test-Path config.log) { cat _bld/config.log } - } - - if($env:TESTING -eq 'ON' -and $env:BUILD_SYSTEM -eq 'CMake') { - cmake --build _bld --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') { - Copy-Item -Path 'C:\Projects\curl\_bld\lib\*.dll' -Destination 'C:\projects\curl\_bld\tests\libtest' - $env:TFLAGS="$acurl $env:DISABLED_TESTS" - cmake --build _bld --config $env:PRJ_CFG --target test-ci - } - elseif($env:BUILD_SYSTEM -eq 'autotools') { - & bash -e -c "cd $env:POSIX_PATH_PREFIX/c/projects/curl/_bld && make V=1 TFLAGS='$acurl $env:DISABLED_TESTS' test-ci" - } - else { - & bash -e -c "cd $env:POSIX_PATH_PREFIX/c/projects/curl/_bld/tests && ./runtests.pl -a -p !flaky -r -rm $acurl $env:DISABLED_TESTS" - } - } +build_script: + - cmd: sh -c ./appveyor.sh clone_depth: 10 From ef2cf58c77fc92960695d6669648f92ca4792e9c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 22 Dec 2023 09:51:20 +0100 Subject: [PATCH 079/509] mprintf: overhaul and bugfixes In a test case using lots of snprintf() calls using many commonly used %-codes per call, this version is around 30% faster than previous version. It also fixes the #12561 bug which made it not behave correctly when given unknown %-sequences. Fixing that flaw required a different take on the problem, which resulted in the new two-arrays model. lib557: extended - Verify the #12561 fix and test more printf features unit1398: fix test: It used a $ only for one argument, which is not supported. Fixes #12561 Closes #12563 --- lib/mprintf.c | 1182 +++++++++++++++++++++------------------- tests/libtest/lib557.c | 56 +- tests/unit/unit1398.c | 2 +- 3 files changed, 653 insertions(+), 587 deletions(-) diff --git a/lib/mprintf.c b/lib/mprintf.c index 3d194b24ed6..63f7f2409ec 100644 --- a/lib/mprintf.c +++ b/lib/mprintf.c @@ -20,21 +20,6 @@ * * SPDX-License-Identifier: curl * - * - * Purpose: - * A merge of Bjorn Reese's format() function and Daniel's dsprintf() - * 1.0. A full blooded printf() clone with full support for $ - * everywhere (parameters, widths and precisions) including variabled - * sized parameters (like doubles, long longs, long doubles and even - * void * in 64-bit architectures). - * - * Current restrictions: - * - Max 128 parameters - * - No 'long double' support. - * - * If you ever want truly portable and good *printf() clones, the project that - * took on from here is named 'Trio' and you find more details on the trio web - * page at https://daniel.haxx.se/projects/trio/ */ #include "curl_setup.h" @@ -87,7 +72,8 @@ #define BUFFSIZE 326 /* buffer for long-to-str and float-to-str calcs, should fit negative DBL_MAX (317 letters) */ -#define MAX_PARAMETERS 128 /* lame static limit */ +#define MAX_PARAMETERS 128 /* number of input arguments */ +#define MAX_SEGMENTS 128 /* number of output segments */ #ifdef __AMIGA__ # undef FORMAT_INT @@ -99,31 +85,33 @@ static const char lower_digits[] = "0123456789abcdefghijklmnopqrstuvwxyz"; /* Upper-case digits. */ static const char upper_digits[] = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"; -#define OUTCHAR(x) \ - do { \ - if(stream((unsigned char)(x), (FILE *)data) != -1) \ - done++; \ - else \ - return done; /* return immediately on failure */ \ +#define OUTCHAR(x) \ + do { \ + if(!stream(x, userp)) \ + done++; \ + else \ + return done; /* return on failure */ \ } while(0) /* Data type to read from the arglist */ typedef enum { - FORMAT_UNKNOWN = 0, FORMAT_STRING, FORMAT_PTR, - FORMAT_INT, FORMAT_INTPTR, + FORMAT_INT, FORMAT_LONG, FORMAT_LONGLONG, + FORMAT_INTU, + FORMAT_LONGU, + FORMAT_LONGLONGU, FORMAT_DOUBLE, FORMAT_LONGDOUBLE, - FORMAT_WIDTH /* For internal use */ + FORMAT_WIDTH, + FORMAT_PRECISION } FormatType; /* conversion and display flags */ enum { - FLAGS_NEW = 0, FLAGS_SPACE = 1<<0, FLAGS_SHOWSIGN = 1<<1, FLAGS_LEFT = 1<<2, @@ -143,23 +131,40 @@ enum { FLAGS_PRECPARAM = 1<<16, /* precision PARAMETER was specified */ FLAGS_CHAR = 1<<17, /* %c story */ FLAGS_FLOATE = 1<<18, /* %e or %E */ - FLAGS_FLOATG = 1<<19 /* %g or %G */ + FLAGS_FLOATG = 1<<19, /* %g or %G */ + FLAGS_SUBSTR = 1<<20 /* no input, only substring */ }; -struct va_stack { - FormatType type; - int flags; - long width; /* width OR width parameter number */ - long precision; /* precision OR precision parameter number */ +enum { + DOLLAR_UNKNOWN, + DOLLAR_NOPE, + DOLLAR_USE +}; + +/* + * Describes an input va_arg type and hold its value. + */ +struct va_input { + FormatType type; /* FormatType */ union { char *str; void *ptr; - union { - mp_intmax_t as_signed; - mp_uintmax_t as_unsigned; - } num; + mp_intmax_t nums; /* signed */ + mp_uintmax_t numu; /* unsigned */ double dnum; - } data; + } val; +}; + +/* + * Describes an output segment. + */ +struct outsegment { + int width; /* width OR width parameter number */ + int precision; /* precision OR precision parameter number */ + unsigned int flags; + unsigned int input; /* input argument array index */ + char *start; /* format string start to output */ + size_t outlen; /* number of bytes from the format string to output */ }; struct nsprintf { @@ -173,114 +178,120 @@ struct asprintf { char merr; }; -static long dprintf_DollarString(char *input, char **end) -{ - int number = 0; - while(ISDIGIT(*input)) { - if(number < MAX_PARAMETERS) { - number *= 10; - number += *input - '0'; - } - input++; - } - if(number <= MAX_PARAMETERS && ('$' == *input)) { - *end = ++input; - return number; - } - return 0; -} +/* the provided input number is 1-based but this returns the number 0-based. -static bool dprintf_IsQualifierNoDollar(const char *fmt) + returns -1 if no valid number was provided. +*/ +static int dollarstring(char *input, char **end) { -#if defined(MP_HAVE_INT_EXTENSIONS) - if(!strncmp(fmt, "I32", 3) || !strncmp(fmt, "I64", 3)) { - return TRUE; - } -#endif - - switch(*fmt) { - case '-': case '+': case ' ': case '#': case '.': - case '0': case '1': case '2': case '3': case '4': - case '5': case '6': case '7': case '8': case '9': - case 'h': case 'l': case 'L': case 'z': case 'q': - case '*': case 'O': -#if defined(MP_HAVE_INT_EXTENSIONS) - case 'I': -#endif - return TRUE; + if(ISDIGIT(*input)) { + int number = 0; + do { + if(number < MAX_PARAMETERS) { + number *= 10; + number += *input - '0'; + } + input++; + } while(ISDIGIT(*input)); - default: - return FALSE; + if(number && (number <= MAX_PARAMETERS) && ('$' == *input)) { + *end = ++input; + return number - 1; + } } + return -1; } -/****************************************************************** +/* + * Parse the format string. * - * Pass 1: - * Create an index with the type of each parameter entry and its - * value (may vary in size) + * Create two arrays. One describes the inputs, one describes the outputs. * * Returns zero on success. - * - ******************************************************************/ + */ -static int dprintf_Pass1(const char *format, struct va_stack *vto, - char **endpos, va_list arglist) +#define PFMT_OK 0 +#define PFMT_DOLLAR 1 /* bad dollar for main param */ +#define PFMT_DOLLARWIDTH 2 /* bad dollar use for width */ +#define PFMT_DOLLARPREC 3 /* bad dollar use for precision */ +#define PFMT_MANYARGS 4 /* too many input arguments used */ +#define PFMT_PREC 5 /* precision overflow */ +#define PFMT_PRECMIX 6 /* bad mix of precision specifiers */ +#define PFMT_WIDTH 7 /* width overflow */ +#define PFMT_INPUTGAP 8 /* gap in arguments */ +#define PFMT_WIDTHARG 9 /* attempted to use same arg twice, for width */ +#define PFMT_PRECARG 10 /* attempted to use same arg twice, for prec */ +#define PFMT_MANYSEGS 11 /* maxed out output segments */ + +static int parsefmt(const char *format, + struct outsegment *out, + struct va_input *in, + int *opieces, + int *ipieces, va_list arglist) { char *fmt = (char *)format; int param_num = 0; - long this_param; - long width; - long precision; - int flags; - long max_param = 0; - long i; + int param; + int width; + int precision; + unsigned int flags; + FormatType type; + int max_param = -1; + int i; + int ocount = 0; + unsigned char usedinput[MAX_PARAMETERS/8]; + size_t outlen = 0; + struct outsegment *optr; + int use_dollar = DOLLAR_UNKNOWN; + char *start = fmt; + + /* clear, set a bit for each used input */ + memset(usedinput, 0, sizeof(usedinput)); while(*fmt) { - if(*fmt++ == '%') { + if(*fmt == '%') { + struct va_input *iptr; + bool loopit = TRUE; + fmt++; + outlen = fmt - start - 1; if(*fmt == '%') { + /* this means a %% that should be output only as %. Create an output + segment. */ + if(outlen) { + optr = &out[ocount++]; + if(ocount > MAX_SEGMENTS) + return PFMT_MANYSEGS; + optr->input = 0; + optr->flags = FLAGS_SUBSTR; + optr->start = start; + optr->outlen = outlen; + } + start = fmt; fmt++; continue; /* while */ } - flags = FLAGS_NEW; - - /* Handle the positional case (N$) */ - - param_num++; - - this_param = dprintf_DollarString(fmt, &fmt); - if(0 == this_param) - /* we got no positional, get the next counter */ - this_param = param_num; - - if(this_param > max_param) - max_param = this_param; + flags = width = precision = 0; - /* - * The parameter with number 'i' should be used. Next, we need - * to get SIZE and TYPE of the parameter. Add the information - * to our array. - */ + if(use_dollar != DOLLAR_NOPE) { + param = dollarstring(fmt, &fmt); + if(param < 0) { + if(use_dollar == DOLLAR_USE) + /* illegal combo */ + return PFMT_DOLLAR; - width = 0; - precision = 0; - - /* Handle the flags */ - - while(dprintf_IsQualifierNoDollar(fmt)) { -#if defined(MP_HAVE_INT_EXTENSIONS) - if(!strncmp(fmt, "I32", 3)) { - flags |= FLAGS_LONG; - fmt += 3; - } - else if(!strncmp(fmt, "I64", 3)) { - flags |= FLAGS_LONGLONG; - fmt += 3; + /* we got no positional, just get the next arg */ + param = -1; + use_dollar = DOLLAR_NOPE; } else -#endif + use_dollar = DOLLAR_USE; + } + else + param = -1; + /* Handle the flags */ + while(loopit) { switch(*fmt++) { case ' ': flags |= FLAGS_SPACE; @@ -298,40 +309,63 @@ static int dprintf_Pass1(const char *format, struct va_stack *vto, case '.': if('*' == *fmt) { /* The precision is picked from a specified parameter */ - flags |= FLAGS_PRECPARAM; fmt++; - param_num++; - i = dprintf_DollarString(fmt, &fmt); - if(i) - precision = i; + if(use_dollar == DOLLAR_USE) { + precision = dollarstring(fmt, &fmt); + if(precision < 0) + /* illegal combo */ + return PFMT_DOLLARPREC; + } else - precision = param_num; - - if(precision > max_param) - max_param = precision; + /* get it from the next argument */ + precision = -1; } else { + bool is_neg = FALSE; flags |= FLAGS_PREC; - precision = strtol(fmt, &fmt, 10); + precision = 0; + if('-' == *fmt) { + is_neg = TRUE; + fmt++; + } + while(ISDIGIT(*fmt)) { + if(precision > INT_MAX/10) + return PFMT_PREC; + precision *= 10; + precision += *fmt - '0'; + fmt++; + } + if(is_neg) + precision = -precision; } if((flags & (FLAGS_PREC | FLAGS_PRECPARAM)) == (FLAGS_PREC | FLAGS_PRECPARAM)) /* it is not permitted to use both kinds of precision for the same argument */ - return 1; + return PFMT_PRECMIX; break; case 'h': flags |= FLAGS_SHORT; break; #if defined(MP_HAVE_INT_EXTENSIONS) case 'I': + if((fmt[0] == '3') && (fmt[1] == '2')) { + flags |= FLAGS_LONG; + fmt += 2; + } + else if((fmt[0] == '6') && (fmt[1] == '4')) { + flags |= FLAGS_LONGLONG; + fmt += 2; + } + else { #if (SIZEOF_CURL_OFF_T > SIZEOF_LONG) - flags |= FLAGS_LONGLONG; + flags |= FLAGS_LONGLONG; #else - flags |= FLAGS_LONG; + flags |= FLAGS_LONG; #endif + } break; #endif case 'l': @@ -369,398 +403,417 @@ static int dprintf_Pass1(const char *format, struct va_stack *vto, case '1': case '2': case '3': case '4': case '5': case '6': case '7': case '8': case '9': flags |= FLAGS_WIDTH; - width = strtol(fmt-1, &fmt, 10); + width = 0; + fmt--; + do { + if(width > INT_MAX/10) + return PFMT_WIDTH; + width *= 10; + width += *fmt - '0'; + fmt++; + } while(ISDIGIT(*fmt)); break; - case '*': /* Special case */ + case '*': /* read width from argument list */ flags |= FLAGS_WIDTHPARAM; - param_num++; - - i = dprintf_DollarString(fmt, &fmt); - if(i) - width = i; + if(use_dollar == DOLLAR_USE) { + width = dollarstring(fmt, &fmt); + if(width < 0) + /* illegal combo */ + return PFMT_DOLLARWIDTH; + } else - width = param_num; - if(width > max_param) - max_param = width; + /* pick from the next argument */ + width = -1; break; - case '\0': - fmt--; - FALLTHROUGH(); default: + loopit = FALSE; + fmt--; break; - } - } /* switch */ - - /* Handle the specifier */ - - i = this_param - 1; - - if((i < 0) || (i >= MAX_PARAMETERS)) - /* out of allowed range */ - return 1; + } /* switch */ + } /* while */ switch(*fmt) { case 'S': flags |= FLAGS_ALT; FALLTHROUGH(); case 's': - vto[i].type = FORMAT_STRING; + type = FORMAT_STRING; break; case 'n': - vto[i].type = FORMAT_INTPTR; + type = FORMAT_INTPTR; break; case 'p': - vto[i].type = FORMAT_PTR; + type = FORMAT_PTR; break; - case 'd': case 'i': - vto[i].type = FORMAT_INT; + case 'd': + case 'i': + if(flags & FLAGS_LONGLONG) + type = FORMAT_LONGLONG; + else if(flags & FLAGS_LONG) + type = FORMAT_LONG; + else + type = FORMAT_INT; break; case 'u': - vto[i].type = FORMAT_INT; + if(flags & FLAGS_LONGLONG) + type = FORMAT_LONGLONGU; + else if(flags & FLAGS_LONG) + type = FORMAT_LONGU; + else + type = FORMAT_INTU; flags |= FLAGS_UNSIGNED; break; case 'o': - vto[i].type = FORMAT_INT; + type = FORMAT_INT; flags |= FLAGS_OCTAL; break; case 'x': - vto[i].type = FORMAT_INT; + type = FORMAT_INTU; flags |= FLAGS_HEX|FLAGS_UNSIGNED; break; case 'X': - vto[i].type = FORMAT_INT; + type = FORMAT_INTU; flags |= FLAGS_HEX|FLAGS_UPPER|FLAGS_UNSIGNED; break; case 'c': - vto[i].type = FORMAT_INT; + type = FORMAT_INT; flags |= FLAGS_CHAR; break; case 'f': - vto[i].type = FORMAT_DOUBLE; + type = FORMAT_DOUBLE; break; case 'e': - vto[i].type = FORMAT_DOUBLE; + type = FORMAT_DOUBLE; flags |= FLAGS_FLOATE; break; case 'E': - vto[i].type = FORMAT_DOUBLE; + type = FORMAT_DOUBLE; flags |= FLAGS_FLOATE|FLAGS_UPPER; break; case 'g': - vto[i].type = FORMAT_DOUBLE; + type = FORMAT_DOUBLE; flags |= FLAGS_FLOATG; break; case 'G': - vto[i].type = FORMAT_DOUBLE; + type = FORMAT_DOUBLE; flags |= FLAGS_FLOATG|FLAGS_UPPER; break; default: - vto[i].type = FORMAT_UNKNOWN; - break; + /* invalid instruction, disregard and continue */ + continue; } /* switch */ - vto[i].flags = flags; - vto[i].width = width; - vto[i].precision = precision; - if(flags & FLAGS_WIDTHPARAM) { - /* we have the width specified from a parameter, so we make that - parameter's info setup properly */ - long k = width - 1; - if((k < 0) || (k >= MAX_PARAMETERS)) - /* out of allowed range */ - return 1; - vto[i].width = k; - vto[k].type = FORMAT_WIDTH; - vto[k].flags = FLAGS_NEW; - /* can't use width or precision of width! */ - vto[k].width = 0; - vto[k].precision = 0; + if(width < 0) + width = param_num++; + else { + /* if this identifies a parameter already used, this + is illegal */ + if(usedinput[width/8] & (1 << (width&7))) + return PFMT_WIDTHARG; + } + if(width >= MAX_PARAMETERS) + return PFMT_MANYARGS; + if(width >= max_param) + max_param = width; + + in[width].type = FORMAT_WIDTH; + /* mark as used */ + usedinput[width/8] |= (unsigned char)(1 << (width&7)); } + if(flags & FLAGS_PRECPARAM) { - /* we have the precision specified from a parameter, so we make that - parameter's info setup properly */ - long k = precision - 1; - if((k < 0) || (k >= MAX_PARAMETERS)) - /* out of allowed range */ - return 1; - vto[i].precision = k; - vto[k].type = FORMAT_WIDTH; - vto[k].flags = FLAGS_NEW; - /* can't use width or precision of width! */ - vto[k].width = 0; - vto[k].precision = 0; + if(precision < 0) + precision = param_num++; + else { + /* if this identifies a parameter already used, this + is illegal */ + if(usedinput[precision/8] & (1 << (precision&7))) + return PFMT_PRECARG; + } + if(precision >= MAX_PARAMETERS) + return PFMT_MANYARGS; + if(precision >= max_param) + max_param = precision; + + in[precision].type = FORMAT_PRECISION; + usedinput[precision/8] |= (unsigned char)(1 << (precision&7)); } - *endpos++ = fmt + ((*fmt == '\0') ? 0 : 1); /* end of this sequence */ + + /* Handle the specifier */ + if(param < 0) + param = param_num++; + if(param >= MAX_PARAMETERS) + return PFMT_MANYARGS; + if(param >= max_param) + max_param = param; + + iptr = &in[param]; + iptr->type = type; + + /* mark this input as used */ + usedinput[param/8] |= (unsigned char)(1 << (param&7)); + + fmt++; + optr = &out[ocount++]; + if(ocount > MAX_SEGMENTS) + return PFMT_MANYSEGS; + optr->input = param; + optr->flags = flags; + optr->width = width; + optr->precision = precision; + optr->start = start; + optr->outlen = outlen; + start = fmt; } + else + fmt++; } - /* Read the arg list parameters into our data list */ - for(i = 0; i MAX_SEGMENTS) + return PFMT_MANYSEGS; + optr->input = 0; + optr->flags = FLAGS_SUBSTR; + optr->start = start; + optr->outlen = outlen; + } - switch(vto[i].type) { + /* Read the arg list parameters into our data list */ + for(i = 0; i < max_param + 1; i++) { + struct va_input *iptr = &in[i]; + if(!(usedinput[i/8] & (1 << (i&7)))) + /* bad input */ + return PFMT_INPUTGAP; + + /* based on the type, read the correct argument */ + switch(iptr->type) { case FORMAT_STRING: - vto[i].data.str = va_arg(arglist, char *); + iptr->val.str = va_arg(arglist, char *); break; case FORMAT_INTPTR: - case FORMAT_UNKNOWN: case FORMAT_PTR: - vto[i].data.ptr = va_arg(arglist, void *); + iptr->val.ptr = va_arg(arglist, void *); break; - case FORMAT_INT: -#ifdef HAVE_LONG_LONG_TYPE - if((vto[i].flags & FLAGS_LONGLONG) && (vto[i].flags & FLAGS_UNSIGNED)) - vto[i].data.num.as_unsigned = - (mp_uintmax_t)va_arg(arglist, mp_uintmax_t); - else if(vto[i].flags & FLAGS_LONGLONG) - vto[i].data.num.as_signed = - (mp_intmax_t)va_arg(arglist, mp_intmax_t); - else -#endif - { - if((vto[i].flags & FLAGS_LONG) && (vto[i].flags & FLAGS_UNSIGNED)) - vto[i].data.num.as_unsigned = - (mp_uintmax_t)va_arg(arglist, unsigned long); - else if(vto[i].flags & FLAGS_LONG) - vto[i].data.num.as_signed = - (mp_intmax_t)va_arg(arglist, long); - else if(vto[i].flags & FLAGS_UNSIGNED) - vto[i].data.num.as_unsigned = - (mp_uintmax_t)va_arg(arglist, unsigned int); - else - vto[i].data.num.as_signed = - (mp_intmax_t)va_arg(arglist, int); - } + case FORMAT_LONGLONGU: + iptr->val.numu = (mp_uintmax_t)va_arg(arglist, mp_uintmax_t); break; - case FORMAT_DOUBLE: - vto[i].data.dnum = va_arg(arglist, double); + case FORMAT_LONGLONG: + iptr->val.nums = (mp_intmax_t)va_arg(arglist, mp_intmax_t); break; + case FORMAT_LONGU: + iptr->val.numu = (mp_uintmax_t)va_arg(arglist, unsigned long); + break; + + case FORMAT_LONG: + iptr->val.nums = (mp_intmax_t)va_arg(arglist, long); + break; + + case FORMAT_INTU: + iptr->val.numu = (mp_uintmax_t)va_arg(arglist, unsigned int); + break; + + case FORMAT_INT: case FORMAT_WIDTH: - /* Argument has been read. Silently convert it into an integer - * for later use - */ - vto[i].type = FORMAT_INT; + case FORMAT_PRECISION: + iptr->val.nums = (mp_intmax_t)va_arg(arglist, int); + break; + + case FORMAT_DOUBLE: + iptr->val.dnum = va_arg(arglist, double); break; default: + DEBUGASSERT(NULL); /* unexpected */ break; } } + *ipieces = max_param + 1; + *opieces = ocount; - return 0; - + return PFMT_OK; } -static int dprintf_formatf( - void *data, /* untouched by format(), just sent to the stream() function in - the second argument */ +/* + * formatf() - the general printf function. + * + * It calls parsefmt() to parse the format string. It populates two arrays; + * one that describes the input arguments and one that describes a number of + * output segments. + * + * On success, the input array describes the type of all arguments and their + * values. + * + * The function then iterates over the output sengments and outputs them one + * by one until done. Using the appropriate input arguments (if any). + * + * All output is sent to the 'stream()' callback, one byte at a time. + */ + +static int formatf( + void *userp, /* untouched by format(), just sent to the stream() function in + the second argument */ /* function pointer called for each output character */ - int (*stream)(int, FILE *), + int (*stream)(unsigned char, void *), const char *format, /* %-formatted string */ va_list ap_save) /* list of parameters */ { - /* Base-36 digits for numbers. */ - const char *digits = lower_digits; - - /* Pointer into the format string. */ - char *f; - - /* Number of characters written. */ - int done = 0; - - long param; /* current parameter to read */ - long param_num = 0; /* parameter counter */ - - struct va_stack vto[MAX_PARAMETERS]; - char *endpos[MAX_PARAMETERS]; - char **end; + static const char nilstr[] = "(nil)"; + const char *digits = lower_digits; /* Base-36 digits for numbers. */ + int done = 0; /* number of characters written */ + int i; + int ocount = 0; /* number of output segments */ + int icount = 0; /* number of input arguments */ + + struct outsegment output[MAX_SEGMENTS]; + struct va_input input[MAX_PARAMETERS]; char work[BUFFSIZE]; - struct va_stack *p; /* 'workend' points to the final buffer byte position, but with an extra byte as margin to avoid the (false?) warning Coverity gives us otherwise */ char *workend = &work[sizeof(work) - 2]; - /* Do the actual %-code parsing */ - if(dprintf_Pass1(format, vto, endpos, ap_save)) + /* Parse the format string */ + if(parsefmt(format, output, input, &ocount, &icount, ap_save)) return 0; - end = &endpos[0]; /* the initial end-position from the list dprintf_Pass1() - created for us */ - - f = (char *)format; - while(*f != '\0') { - /* Format spec modifiers. */ - int is_alt; - - /* Width of a field. */ - long width; - - /* Precision of a field. */ - long prec; - - /* Decimal integer is negative. */ - int is_neg; - - /* Base of a number to be written. */ - unsigned long base; - - /* Integral values to be written. */ - mp_uintmax_t num; - - /* Used to convert negative in positive. */ - mp_intmax_t signed_num; - + for(i = 0; i < ocount; i++) { + struct outsegment *optr = &output[i]; + struct va_input *iptr; + bool is_alt; /* Format spec modifiers. */ + int width; /* Width of a field. */ + int prec; /* Precision of a field. */ + bool is_neg; /* Decimal integer is negative. */ + unsigned long base; /* Base of a number to be written. */ + mp_uintmax_t num; /* Integral values to be written. */ + mp_intmax_t signed_num; /* Used to convert negative in positive. */ char *w; - - if(*f != '%') { - /* This isn't a format spec, so write everything out until the next one - OR end of string is reached. */ - do { - OUTCHAR(*f); - } while(*++f && ('%' != *f)); - continue; + size_t outlen = optr->outlen; + int flags = optr->flags; + + if(outlen) { + char *str = optr->start; + for(; outlen && *str; outlen--) + OUTCHAR(*str++); + if(optr->flags & FLAGS_SUBSTR) + /* this is just a substring */ + continue; } - ++f; - - /* Check for "%%". Note that although the ANSI standard lists - '%' as a conversion specifier, it says "The complete format - specification shall be `%%'," so we can avoid all the width - and precision processing. */ - if(*f == '%') { - ++f; - OUTCHAR('%'); - continue; - } - - /* If this is a positional parameter, the position must follow immediately - after the %, thus create a %$ sequence */ - param = dprintf_DollarString(f, &f); - - if(!param) - param = param_num; - else - --param; - - param_num++; /* increase this always to allow "%2$s %1$s %s" and then the - third %s will pick the 3rd argument */ - - p = &vto[param]; - /* pick up the specified width */ - if(p->flags & FLAGS_WIDTHPARAM) { - width = (long)vto[p->width].data.num.as_signed; - param_num++; /* since the width is extracted from a parameter, we - must skip that to get to the next one properly */ + if(flags & FLAGS_WIDTHPARAM) { + width = (int)input[optr->width].val.nums; if(width < 0) { /* "A negative field width is taken as a '-' flag followed by a positive field width." */ - width = -width; - p->flags |= FLAGS_LEFT; - p->flags &= ~FLAGS_PAD_NIL; + if(width == INT_MIN) + width = INT_MAX; + else + width = -width; + flags |= FLAGS_LEFT; + flags &= ~FLAGS_PAD_NIL; } } else - width = p->width; + width = optr->width; /* pick up the specified precision */ - if(p->flags & FLAGS_PRECPARAM) { - prec = (long)vto[p->precision].data.num.as_signed; - param_num++; /* since the precision is extracted from a parameter, we - must skip that to get to the next one properly */ + if(flags & FLAGS_PRECPARAM) { + prec = (int)input[optr->precision].val.nums; if(prec < 0) /* "A negative precision is taken as if the precision were omitted." */ prec = -1; } - else if(p->flags & FLAGS_PREC) - prec = p->precision; + else if(flags & FLAGS_PREC) + prec = optr->precision; else prec = -1; - is_alt = (p->flags & FLAGS_ALT) ? 1 : 0; + is_alt = (flags & FLAGS_ALT) ? 1 : 0; + iptr = &input[optr->input]; - switch(p->type) { + switch(iptr->type) { + case FORMAT_INTU: + case FORMAT_LONGU: + case FORMAT_LONGLONGU: + flags |= FLAGS_UNSIGNED; + FALLTHROUGH(); case FORMAT_INT: - num = p->data.num.as_unsigned; - if(p->flags & FLAGS_CHAR) { + case FORMAT_LONG: + case FORMAT_LONGLONG: + num = iptr->val.numu; + if(flags & FLAGS_CHAR) { /* Character. */ - if(!(p->flags & FLAGS_LEFT)) + if(!(flags & FLAGS_LEFT)) while(--width > 0) OUTCHAR(' '); OUTCHAR((char) num); - if(p->flags & FLAGS_LEFT) + if(flags & FLAGS_LEFT) while(--width > 0) OUTCHAR(' '); break; } - if(p->flags & FLAGS_OCTAL) { - /* Octal unsigned integer. */ + if(flags & FLAGS_OCTAL) { + /* Octal unsigned integer */ base = 8; - goto unsigned_number; + is_neg = FALSE; } - else if(p->flags & FLAGS_HEX) { - /* Hexadecimal unsigned integer. */ - - digits = (p->flags & FLAGS_UPPER)? upper_digits : lower_digits; + else if(flags & FLAGS_HEX) { + /* Hexadecimal unsigned integer */ + digits = (flags & FLAGS_UPPER)? upper_digits : lower_digits; base = 16; - goto unsigned_number; + is_neg = FALSE; } - else if(p->flags & FLAGS_UNSIGNED) { - /* Decimal unsigned integer. */ + else if(flags & FLAGS_UNSIGNED) { + /* Decimal unsigned integer */ base = 10; - goto unsigned_number; + is_neg = FALSE; } + else { + /* Decimal integer. */ + base = 10; - /* Decimal integer. */ - base = 10; - - is_neg = (p->data.num.as_signed < (mp_intmax_t)0) ? 1 : 0; - if(is_neg) { - /* signed_num might fail to hold absolute negative minimum by 1 */ - signed_num = p->data.num.as_signed + (mp_intmax_t)1; - signed_num = -signed_num; - num = (mp_uintmax_t)signed_num; - num += (mp_uintmax_t)1; + is_neg = (iptr->val.nums < (mp_intmax_t)0); + if(is_neg) { + /* signed_num might fail to hold absolute negative minimum by 1 */ + signed_num = iptr->val.nums + (mp_intmax_t)1; + signed_num = -signed_num; + num = (mp_uintmax_t)signed_num; + num += (mp_uintmax_t)1; + } } - - goto number; - -unsigned_number: - /* Unsigned number of base BASE. */ - is_neg = 0; - number: - /* Number of base BASE. */ - /* Supply a default precision if none was given. */ if(prec == -1) prec = 1; /* Put the number in WORK. */ w = workend; - while(num > 0) { - *w-- = digits[num % base]; - num /= base; + switch(base) { + case 10: + while(num > 0) { + *w-- = (char)('0' + (num % 10)); + num /= 10; + } + break; + default: + while(num > 0) { + *w-- = digits[num % base]; + num /= base; + } + break; } - width -= (long)(workend - w); - prec -= (long)(workend - w); + width -= (int)(workend - w); + prec -= (int)(workend - w); if(is_alt && base == 8 && prec <= 0) { *w-- = '0'; @@ -776,29 +829,29 @@ static int dprintf_formatf( if(is_alt && base == 16) width -= 2; - if(is_neg || (p->flags & FLAGS_SHOWSIGN) || (p->flags & FLAGS_SPACE)) + if(is_neg || (flags & FLAGS_SHOWSIGN) || (flags & FLAGS_SPACE)) --width; - if(!(p->flags & FLAGS_LEFT) && !(p->flags & FLAGS_PAD_NIL)) + if(!(flags & FLAGS_LEFT) && !(flags & FLAGS_PAD_NIL)) while(width-- > 0) OUTCHAR(' '); if(is_neg) OUTCHAR('-'); - else if(p->flags & FLAGS_SHOWSIGN) + else if(flags & FLAGS_SHOWSIGN) OUTCHAR('+'); - else if(p->flags & FLAGS_SPACE) + else if(flags & FLAGS_SPACE) OUTCHAR(' '); if(is_alt && base == 16) { OUTCHAR('0'); - if(p->flags & FLAGS_UPPER) + if(flags & FLAGS_UPPER) OUTCHAR('X'); else OUTCHAR('x'); } - if(!(p->flags & FLAGS_LEFT) && (p->flags & FLAGS_PAD_NIL)) + if(!(flags & FLAGS_LEFT) && (flags & FLAGS_PAD_NIL)) while(width-- > 0) OUTCHAR('0'); @@ -807,219 +860,199 @@ static int dprintf_formatf( OUTCHAR(*w); } - if(p->flags & FLAGS_LEFT) + if(flags & FLAGS_LEFT) while(width-- > 0) OUTCHAR(' '); break; - case FORMAT_STRING: - /* String. */ - { - static const char null[] = "(nil)"; - const char *str; - size_t len; - - str = (char *) p->data.str; - if(!str) { - /* Write null[] if there's space. */ - if(prec == -1 || prec >= (long) sizeof(null) - 1) { - str = null; - len = sizeof(null) - 1; - /* Disable quotes around (nil) */ - p->flags &= (~FLAGS_ALT); - } - else { - str = ""; - len = 0; - } + case FORMAT_STRING: { + const char *str; + size_t len; + + str = (char *)iptr->val.str; + if(!str) { + /* Write null string if there's space. */ + if(prec == -1 || prec >= (int) sizeof(nilstr) - 1) { + str = nilstr; + len = sizeof(nilstr) - 1; + /* Disable quotes around (nil) */ + flags &= (~FLAGS_ALT); } - else if(prec != -1) - len = (size_t)prec; - else if(*str == '\0') + else { + str = ""; len = 0; - else - len = strlen(str); + } + } + else if(prec != -1) + len = (size_t)prec; + else if(*str == '\0') + len = 0; + else + len = strlen(str); - width -= (len > LONG_MAX) ? LONG_MAX : (long)len; + width -= (len > INT_MAX) ? INT_MAX : (int)len; - if(p->flags & FLAGS_ALT) - OUTCHAR('"'); + if(flags & FLAGS_ALT) + OUTCHAR('"'); - if(!(p->flags&FLAGS_LEFT)) - while(width-- > 0) - OUTCHAR(' '); + if(!(flags&FLAGS_LEFT)) + while(width-- > 0) + OUTCHAR(' '); - for(; len && *str; len--) - OUTCHAR(*str++); - if(p->flags&FLAGS_LEFT) - while(width-- > 0) - OUTCHAR(' '); + for(; len && *str; len--) + OUTCHAR(*str++); + if(flags&FLAGS_LEFT) + while(width-- > 0) + OUTCHAR(' '); - if(p->flags & FLAGS_ALT) - OUTCHAR('"'); - } + if(flags & FLAGS_ALT) + OUTCHAR('"'); break; + } case FORMAT_PTR: /* Generic pointer. */ - { - void *ptr; - ptr = (void *) p->data.ptr; - if(ptr) { - /* If the pointer is not NULL, write it as a %#x spec. */ - base = 16; - digits = (p->flags & FLAGS_UPPER)? upper_digits : lower_digits; - is_alt = 1; - num = (size_t) ptr; - is_neg = 0; - goto number; - } - else { - /* Write "(nil)" for a nil pointer. */ - static const char strnil[] = "(nil)"; - const char *point; - - width -= (long)(sizeof(strnil) - 1); - if(p->flags & FLAGS_LEFT) - while(width-- > 0) - OUTCHAR(' '); - for(point = strnil; *point != '\0'; ++point) - OUTCHAR(*point); - if(!(p->flags & FLAGS_LEFT)) - while(width-- > 0) - OUTCHAR(' '); - } + if(iptr->val.ptr) { + /* If the pointer is not NULL, write it as a %#x spec. */ + base = 16; + digits = (flags & FLAGS_UPPER)? upper_digits : lower_digits; + is_alt = TRUE; + num = (size_t) iptr->val.ptr; + is_neg = FALSE; + goto number; } - break; + else { + /* Write "(nil)" for a nil pointer. */ + const char *point; - case FORMAT_DOUBLE: - { - char formatbuf[32]="%"; - char *fptr = &formatbuf[1]; - size_t left = sizeof(formatbuf)-strlen(formatbuf); - int len; - - width = -1; - if(p->flags & FLAGS_WIDTH) - width = p->width; - else if(p->flags & FLAGS_WIDTHPARAM) - width = (long)vto[p->width].data.num.as_signed; + width -= (int)(sizeof(nilstr) - 1); + if(flags & FLAGS_LEFT) + while(width-- > 0) + OUTCHAR(' '); + for(point = nilstr; *point != '\0'; ++point) + OUTCHAR(*point); + if(!(flags & FLAGS_LEFT)) + while(width-- > 0) + OUTCHAR(' '); + } + break; - prec = -1; - if(p->flags & FLAGS_PREC) - prec = p->precision; - else if(p->flags & FLAGS_PRECPARAM) - prec = (long)vto[p->precision].data.num.as_signed; - - if(p->flags & FLAGS_LEFT) - *fptr++ = '-'; - if(p->flags & FLAGS_SHOWSIGN) - *fptr++ = '+'; - if(p->flags & FLAGS_SPACE) - *fptr++ = ' '; - if(p->flags & FLAGS_ALT) - *fptr++ = '#'; - - *fptr = 0; - - if(width >= 0) { - if(width >= (long)sizeof(work)) - width = sizeof(work)-1; - /* RECURSIVE USAGE */ - len = curl_msnprintf(fptr, left, "%ld", width); - fptr += len; - left -= len; + case FORMAT_DOUBLE: { + char formatbuf[32]="%"; + char *fptr = &formatbuf[1]; + size_t left = sizeof(formatbuf)-strlen(formatbuf); + int len; + + if(flags & FLAGS_WIDTH) + width = optr->width; + + if(flags & FLAGS_PREC) + prec = optr->precision; + + if(flags & FLAGS_LEFT) + *fptr++ = '-'; + if(flags & FLAGS_SHOWSIGN) + *fptr++ = '+'; + if(flags & FLAGS_SPACE) + *fptr++ = ' '; + if(flags & FLAGS_ALT) + *fptr++ = '#'; + + *fptr = 0; + + if(width >= 0) { + if(width >= (int)sizeof(work)) + width = sizeof(work)-1; + /* RECURSIVE USAGE */ + len = curl_msnprintf(fptr, left, "%d", width); + fptr += len; + left -= len; + } + if(prec >= 0) { + /* for each digit in the integer part, we can have one less + precision */ + size_t maxprec = sizeof(work) - 2; + double val = iptr->val.dnum; + if(width > 0 && prec <= width) + maxprec -= width; + while(val >= 10.0) { + val /= 10; + maxprec--; } - if(prec >= 0) { - /* for each digit in the integer part, we can have one less - precision */ - size_t maxprec = sizeof(work) - 2; - double val = p->data.dnum; - if(width > 0 && prec <= width) - maxprec -= width; - while(val >= 10.0) { - val /= 10; - maxprec--; - } - if(prec > (long)maxprec) - prec = (long)maxprec-1; - if(prec < 0) - prec = 0; - /* RECURSIVE USAGE */ - len = curl_msnprintf(fptr, left, ".%ld", prec); - fptr += len; - } - if(p->flags & FLAGS_LONG) - *fptr++ = 'l'; + if(prec > (int)maxprec) + prec = (int)maxprec-1; + if(prec < 0) + prec = 0; + /* RECURSIVE USAGE */ + len = curl_msnprintf(fptr, left, ".%d", prec); + fptr += len; + } + if(flags & FLAGS_LONG) + *fptr++ = 'l'; - if(p->flags & FLAGS_FLOATE) - *fptr++ = (char)((p->flags & FLAGS_UPPER) ? 'E':'e'); - else if(p->flags & FLAGS_FLOATG) - *fptr++ = (char)((p->flags & FLAGS_UPPER) ? 'G' : 'g'); - else - *fptr++ = 'f'; + if(flags & FLAGS_FLOATE) + *fptr++ = (char)((flags & FLAGS_UPPER) ? 'E':'e'); + else if(flags & FLAGS_FLOATG) + *fptr++ = (char)((flags & FLAGS_UPPER) ? 'G' : 'g'); + else + *fptr++ = 'f'; - *fptr = 0; /* and a final null-termination */ + *fptr = 0; /* and a final null-termination */ #ifdef __clang__ #pragma clang diagnostic push #pragma clang diagnostic ignored "-Wformat-nonliteral" #endif - /* NOTE NOTE NOTE!! Not all sprintf implementations return number of - output characters */ + /* NOTE NOTE NOTE!! Not all sprintf implementations return number of + output characters */ #ifdef HAVE_SNPRINTF - (snprintf)(work, sizeof(work), formatbuf, p->data.dnum); + (snprintf)(work, sizeof(work), formatbuf, iptr->val.dnum); #else - (sprintf)(work, formatbuf, p->data.dnum); + (sprintf)(work, formatbuf, iptr->val.dnum); #endif #ifdef __clang__ #pragma clang diagnostic pop #endif - DEBUGASSERT(strlen(work) <= sizeof(work)); - for(fptr = work; *fptr; fptr++) - OUTCHAR(*fptr); - } + DEBUGASSERT(strlen(work) <= sizeof(work)); + for(fptr = work; *fptr; fptr++) + OUTCHAR(*fptr); break; + } case FORMAT_INTPTR: /* Answer the count of characters written. */ #ifdef HAVE_LONG_LONG_TYPE - if(p->flags & FLAGS_LONGLONG) - *(LONG_LONG_TYPE *) p->data.ptr = (LONG_LONG_TYPE)done; + if(flags & FLAGS_LONGLONG) + *(LONG_LONG_TYPE *) iptr->val.ptr = (LONG_LONG_TYPE)done; else #endif - if(p->flags & FLAGS_LONG) - *(long *) p->data.ptr = (long)done; - else if(!(p->flags & FLAGS_SHORT)) - *(int *) p->data.ptr = (int)done; + if(flags & FLAGS_LONG) + *(long *) iptr->val.ptr = (long)done; + else if(!(flags & FLAGS_SHORT)) + *(int *) iptr->val.ptr = (int)done; else - *(short *) p->data.ptr = (short)done; + *(short *) iptr->val.ptr = (short)done; break; default: break; } - f = *end++; /* goto end of %-code */ - } return done; } /* fputc() look-alike */ -static int addbyter(int output, FILE *data) +static int addbyter(unsigned char outc, void *f) { - struct nsprintf *infop = (struct nsprintf *)data; - char outc = (char)output; - + struct nsprintf *infop = f; if(infop->length < infop->max) { /* only do this if we haven't reached max length yet */ - infop->buffer[0] = outc; /* store */ - infop->buffer++; /* increase pointer */ + *infop->buffer++ = outc; /* store */ infop->length++; /* we are now one byte larger */ - return outc; /* fputc() returns like this on success */ + return 0; /* fputc() returns like this on success */ } - return -1; + return 1; } int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format, @@ -1032,7 +1065,7 @@ int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format, info.length = 0; info.max = maxlength; - retcode = dprintf_formatf(&info, addbyter, format, ap_save); + retcode = formatf(&info, addbyter, format, ap_save); if(info.max) { /* we terminate this with a zero byte */ if(info.max == info.length) { @@ -1058,18 +1091,15 @@ int curl_msnprintf(char *buffer, size_t maxlength, const char *format, ...) } /* fputc() look-alike */ -static int alloc_addbyter(int output, FILE *data) +static int alloc_addbyter(unsigned char outc, void *f) { - struct asprintf *infop = (struct asprintf *)data; - unsigned char outc = (unsigned char)output; - CURLcode result; - - result = Curl_dyn_addn(infop->b, &outc, 1); + struct asprintf *infop = f; + CURLcode result = Curl_dyn_addn(infop->b, &outc, 1); if(result) { infop->merr = result == CURLE_TOO_LARGE ? MERR_TOO_LARGE : MERR_MEM; - return -1; /* fail */ + return 1 ; /* fail */ } - return outc; /* fputc() returns like this on success */ + return 0; } /* appends the formatted string, returns MERR error code */ @@ -1079,7 +1109,7 @@ int Curl_dyn_vprintf(struct dynbuf *dyn, const char *format, va_list ap_save) info.b = dyn; info.merr = MERR_OK; - (void)dprintf_formatf(&info, alloc_addbyter, format, ap_save); + (void)formatf(&info, alloc_addbyter, format, ap_save); if(info.merr) { Curl_dyn_free(info.b); return info.merr; @@ -1095,7 +1125,7 @@ char *curl_mvaprintf(const char *format, va_list ap_save) Curl_dyn_init(info.b, DYN_APRINTF); info.merr = MERR_OK; - (void)dprintf_formatf(&info, alloc_addbyter, format, ap_save); + (void)formatf(&info, alloc_addbyter, format, ap_save); if(info.merr) { Curl_dyn_free(info.b); return NULL; @@ -1115,13 +1145,12 @@ char *curl_maprintf(const char *format, ...) return s; } -static int storebuffer(int output, FILE *data) +static int storebuffer(unsigned char outc, void *f) { - char **buffer = (char **)data; - unsigned char outc = (unsigned char)output; + char **buffer = f; **buffer = outc; (*buffer)++; - return outc; /* act like fputc() ! */ + return 0; } int curl_msprintf(char *buffer, const char *format, ...) @@ -1129,19 +1158,29 @@ int curl_msprintf(char *buffer, const char *format, ...) va_list ap_save; /* argument pointer */ int retcode; va_start(ap_save, format); - retcode = dprintf_formatf(&buffer, storebuffer, format, ap_save); + retcode = formatf(&buffer, storebuffer, format, ap_save); va_end(ap_save); *buffer = 0; /* we terminate this with a zero byte */ return retcode; } +static int fputc_wrapper(unsigned char outc, void *f) +{ + int out = outc; + FILE *s = f; + int rc = fputc(out, s); + if(rc == out) + return 0; + return 1; +} + int curl_mprintf(const char *format, ...) { int retcode; va_list ap_save; /* argument pointer */ va_start(ap_save, format); - retcode = dprintf_formatf(stdout, fputc, format, ap_save); + retcode = formatf(stdout, fputc_wrapper, format, ap_save); va_end(ap_save); return retcode; } @@ -1151,25 +1190,24 @@ int curl_mfprintf(FILE *whereto, const char *format, ...) int retcode; va_list ap_save; /* argument pointer */ va_start(ap_save, format); - retcode = dprintf_formatf(whereto, fputc, format, ap_save); + retcode = formatf(whereto, fputc_wrapper, format, ap_save); va_end(ap_save); return retcode; } int curl_mvsprintf(char *buffer, const char *format, va_list ap_save) { - int retcode; - retcode = dprintf_formatf(&buffer, storebuffer, format, ap_save); + int retcode = formatf(&buffer, storebuffer, format, ap_save); *buffer = 0; /* we terminate this with a zero byte */ return retcode; } int curl_mvprintf(const char *format, va_list ap_save) { - return dprintf_formatf(stdout, fputc, format, ap_save); + return formatf(stdout, fputc_wrapper, format, ap_save); } int curl_mvfprintf(FILE *whereto, const char *format, va_list ap_save) { - return dprintf_formatf(whereto, fputc, format, ap_save); + return formatf(whereto, fputc_wrapper, format, ap_save); } diff --git a/tests/libtest/lib557.c b/tests/libtest/lib557.c index 648992e5279..c157694745f 100644 --- a/tests/libtest/lib557.c +++ b/tests/libtest/lib557.c @@ -1181,12 +1181,49 @@ static int test_string_formatting(void) return errors; } +static int test_pos_arguments(void) +{ + int errors = 0; + char buf[256]; + + curl_msnprintf(buf, sizeof(buf), "%3$d %2$d %1$d", 500, 501, 502); + errors += string_check(buf, "502 501 500"); + + curl_msnprintf(buf, sizeof(buf), "%3$d %1$d %2$d", 500, 501, 502); + errors += string_check(buf, "502 500 501"); + + /* this is in invalid sequence but the output does not match + what glibc does */ + curl_msnprintf(buf, sizeof(buf), "%3$d %d %2$d", 500, 501, 502); + errors += string_check(buf, ""); + + return errors; +} + static int test_weird_arguments(void) { int errors = 0; char buf[256]; int rc; + /* verify %% */ + rc = curl_msnprintf(buf, sizeof(buf), "%-20d%% right? %%", 500); + errors += string_check(buf, "500 % right? %"); + + /* 100 x % */ + rc = curl_msnprintf(buf, sizeof(buf), "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" + "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" + "%%%%%%%%%%%%%%%%%%%%%%"); + /* 50 x % */ + errors += string_check(buf, "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" + "%%%%%%%%%%%%%%%"); + + rc = curl_msnprintf(buf, sizeof(buf), "%2 AA %d %K", 500, 501, 502); + errors += string_check(buf, "%2 AA 500 %K"); + + rc = curl_msnprintf(buf, sizeof(buf), "%2 %d %K", 500, 501, 502); + errors += string_check(buf, "%2 500 %K"); + /* MAX_PARAMETERS is 128, try exact 128! */ rc = curl_msnprintf(buf, sizeof(buf), "%d%d%d%d%d%d%d%d%d%d" /* 10 */ @@ -1276,18 +1313,6 @@ static int test_weird_arguments(void) errors += string_check(buf, ""); - /* Do not skip sanity checks with parameters! */ - buf[0] = 0; - rc = curl_msnprintf(buf, sizeof(buf), "%d, %.*1$d", 500, 1); - - if(rc != sizeof(buf) - 1) { - printf("curl_mprintf() returned %d and not %zu!\n", rc, - sizeof(buf) - 1); - errors++; - } - - errors += strlen_check(buf, 255); - if(errors) printf("Some curl_mprintf() weird arguments tests failed!\n"); @@ -1374,9 +1399,10 @@ static int test_float_formatting(void) 123456789123456789123456789.2987654); errors += strlen_check(buf, 325); - /* check negative when used signed */ + /* check negative width argument when used signed, is treated as positive + and maxes out the internal float width == 325 */ curl_msnprintf(buf, sizeof(buf), "%*f", INT_MIN, 9.1); - errors += string_check(buf, "9.100000"); + errors += string_check(buf, "9.100000 "); /* curl_msnprintf() limits a single float output to 325 bytes maximum width */ @@ -1451,6 +1477,8 @@ int test(char *URL) setlocale(LC_NUMERIC, "C"); #endif + errors += test_pos_arguments(); + errors += test_weird_arguments(); errors += test_unsigned_short_formatting(); diff --git a/tests/unit/unit1398.c b/tests/unit/unit1398.c index bf8af12d362..4283a8d1b98 100644 --- a/tests/unit/unit1398.c +++ b/tests/unit/unit1398.c @@ -92,7 +92,7 @@ fail_unless(rc == 15, "return code should be 15"); fail_unless(!strcmp(output, " 1234 567"), "wrong output"); /* double precision */ -rc = curl_msnprintf(output, 24, "%.*1$.99d", 3, 5678); +rc = curl_msnprintf(output, 24, "%2$.*1$.99d", 3, 5678); fail_unless(rc == 0, "return code should be 0"); UNITTEST_STOP From 35380273b9311cf0741e386284310fa7ca4d005e Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 19 Dec 2023 12:57:40 +0100 Subject: [PATCH 080/509] http2: improved on_stream_close/data_done handling - there seems to be a code path that cleans up easy handles without triggering DONE or DETACH events to the connection filters. This would explain wh nghttp2 still holds stream user data - add GOOD check to easy handle used in on_close_callback to prevent crashes, ASSERTs in debug builds. - NULL the stream user data early before submitting RST - add checks in on_stream_close() to identify UNGOOD easy handles Reported-by: Hans-Christian Egtvedt Fixes #10936 Closes #12562 --- lib/http2.c | 50 ++++++++++++++++++++++++------------ tests/http/test_07_upload.py | 17 ++++++++++++ tests/http/testenv/curl.py | 2 +- 3 files changed, 51 insertions(+), 18 deletions(-) diff --git a/lib/http2.c b/lib/http2.c index 59903cfa72d..dcc24ea1023 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -283,13 +283,20 @@ static void http2_data_done(struct Curl_cfilter *cf, return; if(ctx->h2) { + bool flush_egress = FALSE; + /* returns error if stream not known, which is fine here */ + (void)nghttp2_session_set_stream_user_data(ctx->h2, stream->id, NULL); + if(!stream->closed && stream->id > 0) { /* RST_STREAM */ CURL_TRC_CF(data, cf, "[%d] premature DATA_DONE, RST stream", stream->id); - if(!nghttp2_submit_rst_stream(ctx->h2, NGHTTP2_FLAG_NONE, - stream->id, NGHTTP2_STREAM_CLOSED)) - (void)nghttp2_session_send(ctx->h2); + stream->closed = TRUE; + stream->reset = TRUE; + stream->send_closed = TRUE; + nghttp2_submit_rst_stream(ctx->h2, NGHTTP2_FLAG_NONE, + stream->id, NGHTTP2_STREAM_CLOSED); + flush_egress = TRUE; } if(!Curl_bufq_is_empty(&stream->recvbuf)) { /* Anything in the recvbuf is still being counted @@ -299,19 +306,11 @@ static void http2_data_done(struct Curl_cfilter *cf, nghttp2_session_consume(ctx->h2, stream->id, Curl_bufq_len(&stream->recvbuf)); /* give WINDOW_UPATE a chance to be sent, but ignore any error */ - (void)h2_progress_egress(cf, data); + flush_egress = TRUE; } - /* -1 means unassigned and 0 means cleared */ - if(nghttp2_session_get_stream_user_data(ctx->h2, stream->id)) { - int rv = nghttp2_session_set_stream_user_data(ctx->h2, - stream->id, 0); - if(rv) { - infof(data, "http/2: failed to clear user_data for stream %u", - stream->id); - DEBUGASSERT(0); - } - } + if(flush_egress) + nghttp2_session_send(ctx->h2); } Curl_bufq_free(&stream->sendbuf); @@ -1316,26 +1315,43 @@ static int on_stream_close(nghttp2_session *session, int32_t stream_id, uint32_t error_code, void *userp) { struct Curl_cfilter *cf = userp; - struct Curl_easy *data_s; + struct Curl_easy *data_s, *call_data = CF_DATA_CURRENT(cf); struct stream_ctx *stream; int rv; (void)session; + DEBUGASSERT(call_data); /* get the stream from the hash based on Stream ID, stream ID zero is for connection-oriented stuff */ data_s = stream_id? nghttp2_session_get_stream_user_data(session, stream_id) : NULL; if(!data_s) { + CURL_TRC_CF(call_data, cf, + "[%d] on_stream_close, no easy set on stream", stream_id); return 0; } + if(!GOOD_EASY_HANDLE(data_s)) { + /* nghttp2 still has an easy registered for the stream which has + * been freed be libcurl. This points to a code path that does not + * trigger DONE or DETACH events as it must. */ + CURL_TRC_CF(call_data, cf, + "[%d] on_stream_close, not a GOOD easy on stream", stream_id); + (void)nghttp2_session_set_stream_user_data(session, stream_id, 0); + return NGHTTP2_ERR_CALLBACK_FAILURE; + } stream = H2_STREAM_CTX(data_s); - if(!stream) + if(!stream) { + CURL_TRC_CF(data_s, cf, + "[%d] on_stream_close, GOOD easy but no stream", stream_id); return NGHTTP2_ERR_CALLBACK_FAILURE; + } stream->closed = TRUE; stream->error = error_code; - if(stream->error) + if(stream->error) { stream->reset = TRUE; + stream->send_closed = TRUE; + } if(stream->error) CURL_TRC_CF(data_s, cf, "[%d] RESET: %s (err %d)", diff --git a/tests/http/test_07_upload.py b/tests/http/test_07_upload.py index 018a56c6e50..2115b577134 100644 --- a/tests/http/test_07_upload.py +++ b/tests/http/test_07_upload.py @@ -189,6 +189,23 @@ def test_07_21_upload_parallel_large(self, env: Env, httpd, nghttpx, repeat, pro r.check_response(count=count, http_status=200) self.check_download(count, fdata, curl) + # upload large data parallel to a URL that denies uploads + @pytest.mark.parametrize("proto", ['h2', 'h3']) + def test_07_22_upload_parallel_fail(self, env: Env, httpd, nghttpx, repeat, proto): + if proto == 'h3' and not env.have_h3(): + pytest.skip("h3 not supported") + if proto == 'h3' and env.curl_uses_lib('msh3'): + pytest.skip("msh3 stalls here") + fdata = os.path.join(env.gen_dir, 'data-10m') + count = 100 + curl = CurlClient(env=env) + url = f'https://{env.authority_for(env.domain1, proto)}'\ + f'/curltest/tweak?status=400&delay=5ms&chunks=1&body_error=reset&id=[0-{count-1}]' + r = curl.http_upload(urls=[url], data=f'@{fdata}', alpn_proto=proto, + extra_args=['--parallel']) + exp_exit = 92 if proto == 'h2' else 95 + r.check_stats(count=count, exitcode=exp_exit) + # PUT 100k @pytest.mark.parametrize("proto", ['http/1.1', 'h2', 'h3']) def test_07_30_put_100k(self, env: Env, httpd, nghttpx, repeat, proto): diff --git a/tests/http/testenv/curl.py b/tests/http/testenv/curl.py index bc5b4881c73..f8aaac46a55 100644 --- a/tests/http/testenv/curl.py +++ b/tests/http/testenv/curl.py @@ -247,7 +247,7 @@ def check_stats(self, count: int, http_status: Optional[int] = None, if exitcode is not None: for idx, x in enumerate(self.stats): if 'exitcode' in x: - assert x['exitcode'] == 0, \ + assert x['exitcode'] == exitcode, \ f'status #{idx} exitcode: expected {exitcode}, '\ f'got {x["exitcode"]}\n{self.dump_stat(x)}' From 8b1d2298358e83cd2a3403ab26b99b2646efe137 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 22 Dec 2023 10:16:14 +0100 Subject: [PATCH 081/509] mbedtls: free the entropy when threaded The entropy_free was never done for threaded builds, causing a small (fixed) memory leak. Reported-by: RevaliQaQ on github Fixes #12584 Closes #12585 --- lib/vtls/mbedtls.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/lib/vtls/mbedtls.c b/lib/vtls/mbedtls.c index 4734ce026a2..159fa6c6667 100644 --- a/lib/vtls/mbedtls.c +++ b/lib/vtls/mbedtls.c @@ -1206,6 +1206,9 @@ static int mbedtls_init(void) static void mbedtls_cleanup(void) { +#ifdef THREADING_SUPPORT + mbedtls_entropy_free(&ts_entropy); +#endif /* THREADING_SUPPORT */ (void)Curl_mbedtlsthreadlock_thread_cleanup(); } From e492c7c524263e47844ec9354102fcf200e686a8 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 22 Dec 2023 12:27:59 +0100 Subject: [PATCH 082/509] transfer: fix upload rate limiting, add test cases - add test cases for rate limiting uploads for all http versions - fix transfer loop handling of limits. Signal a re-receive attempt only on exhausting maxloops without an EAGAIN - fix `data->state.selectbits` forcing re-receive to also set re-sending when transfer is doing this. Reported-by: Karthikdasari0423 on github Fixes #12559 Closes #12586 --- lib/transfer.c | 22 ++++++++--- tests/http/test_07_upload.py | 39 +++++++++++++++++++ .../http/testenv/mod_curltest/mod_curltest.c | 5 ++- 3 files changed, 60 insertions(+), 6 deletions(-) diff --git a/lib/transfer.c b/lib/transfer.c index 3afefd4dfc1..59a3f05cb16 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -428,7 +428,7 @@ static CURLcode readwrite_data(struct Curl_easy *data, size_t blen; size_t consumed; int maxloops = 10; - curl_off_t max_recv = data->set.max_recv_speed ? 0 : CURL_OFF_T_MAX; + curl_off_t total_received = 0; bool data_eof_handled = FALSE; DEBUGASSERT(data->state.buffer); @@ -439,6 +439,7 @@ static CURLcode readwrite_data(struct Curl_easy *data, do { bool is_empty_data = FALSE; size_t bytestoread = data->set.buffer_size; + /* For HTTP/2 and HTTP/3, read data without caring about the content length. This is safe because body in HTTP/2 is always segmented thanks to its framing layer. Meanwhile, we have to call Curl_read @@ -447,6 +448,15 @@ static CURLcode readwrite_data(struct Curl_easy *data, bool is_http3 = Curl_conn_is_http3(data, conn, FIRSTSOCKET); data_eof_handled = is_http3 || Curl_conn_is_http2(data, conn, FIRSTSOCKET); + if(data->set.max_recv_speed) { + /* Limit the amount we read here, break on reaching it */ + curl_off_t net_limit = data->set.max_recv_speed - total_received; + if(net_limit <= 0) + break; + if((size_t)net_limit < bytestoread) + bytestoread = (size_t)net_limit; + } + /* Each loop iteration starts with a fresh buffer and handles * all data read into it. */ buf = data->state.buffer; @@ -654,7 +664,7 @@ static CURLcode readwrite_data(struct Curl_easy *data, } #endif /* CURL_DISABLE_HTTP */ - max_recv -= blen; + total_received += blen; if(!k->chunk && (blen || k->badheader || is_empty_data)) { /* If this is chunky transfer, it was already written */ @@ -712,11 +722,13 @@ static CURLcode readwrite_data(struct Curl_easy *data, break; } - } while((max_recv > 0) && data_pending(data) && maxloops--); + } while(maxloops-- && data_pending(data)); - if(maxloops <= 0 || max_recv <= 0) { - /* we mark it as read-again-please */ + if(maxloops <= 0) { + /* did not read until EAGAIN, mark read-again-please */ data->state.select_bits = CURL_CSELECT_IN; + if((k->keepon & KEEP_SENDBITS) == KEEP_SEND) + data->state.select_bits |= CURL_CSELECT_OUT; } if(((k->keepon & (KEEP_RECV|KEEP_SEND)) == KEEP_SEND) && diff --git a/tests/http/test_07_upload.py b/tests/http/test_07_upload.py index 2115b577134..463dbeaa776 100644 --- a/tests/http/test_07_upload.py +++ b/tests/http/test_07_upload.py @@ -461,3 +461,42 @@ def check_download(self, count, srcfile, curl): tofile=dfile, n=1)) assert False, f'download {dfile} differs:\n{diff}' + + # speed limited on put handler + @pytest.mark.parametrize("proto", ['http/1.1', 'h2', 'h3']) + def test_07_50_put_speed_limit(self, env: Env, httpd, nghttpx, proto, repeat): + if proto == 'h3' and not env.have_h3(): + pytest.skip("h3 not supported") + count = 1 + fdata = os.path.join(env.gen_dir, 'data-100k') + up_len = 100 * 1024 + speed_limit = 20 * 1024 + curl = CurlClient(env=env) + url = f'https://{env.authority_for(env.domain1, proto)}/curltest/put?id=[0-0]' + r = curl.http_put(urls=[url], fdata=fdata, alpn_proto=proto, + with_headers=True, extra_args=[ + '--limit-rate', f'{speed_limit}' + ]) + r.check_response(count=count, http_status=200) + assert r.responses[0]['header']['received-length'] == f'{up_len}', f'{r.responses[0]}' + up_speed = r.stats[0]['speed_upload'] + assert (speed_limit * 0.5) <= up_speed <= (speed_limit * 1.5), f'{r.stats[0]}' + + # speed limited on echo handler + @pytest.mark.parametrize("proto", ['http/1.1', 'h2', 'h3']) + def test_07_51_echo_speed_limit(self, env: Env, httpd, nghttpx, proto, repeat): + if proto == 'h3' and not env.have_h3(): + pytest.skip("h3 not supported") + count = 1 + fdata = os.path.join(env.gen_dir, 'data-100k') + speed_limit = 20 * 1024 + curl = CurlClient(env=env) + url = f'https://{env.authority_for(env.domain1, proto)}/curltest/echo?id=[0-0]' + r = curl.http_upload(urls=[url], data=f'@{fdata}', alpn_proto=proto, + with_headers=True, extra_args=[ + '--limit-rate', f'{speed_limit}' + ]) + r.check_response(count=count, http_status=200) + up_speed = r.stats[0]['speed_upload'] + assert (speed_limit * 0.5) <= up_speed <= (speed_limit * 1.5), f'{r.stats[0]}' + diff --git a/tests/http/testenv/mod_curltest/mod_curltest.c b/tests/http/testenv/mod_curltest/mod_curltest.c index 30fb765aea4..ff1983d17fd 100644 --- a/tests/http/testenv/mod_curltest/mod_curltest.c +++ b/tests/http/testenv/mod_curltest/mod_curltest.c @@ -423,6 +423,7 @@ static int curltest_put_handler(request_rec *r) char buffer[16*1024]; const char *ct; apr_off_t rbody_len = 0; + const char *s_rbody_len; const char *request_id = "none"; apr_time_t chunk_delay = 0; apr_array_header_t *args = NULL; @@ -491,7 +492,9 @@ static int curltest_put_handler(request_rec *r) } } /* we are done */ - rv = apr_brigade_printf(bb, NULL, NULL, "%"APR_OFF_T_FMT, rbody_len); + s_rbody_len = apr_psprintf(r->pool, "%"APR_OFF_T_FMT, rbody_len); + apr_table_setn(r->headers_out, "Received-Length", s_rbody_len); + rv = apr_brigade_puts(bb, NULL, NULL, s_rbody_len); if(APR_SUCCESS != rv) goto cleanup; b = apr_bucket_eos_create(c->bucket_alloc); APR_BRIGADE_INSERT_TAIL(bb, b); From 296cb805cfac11a09912b148b4f2d054af1e77d9 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Fri, 22 Dec 2023 00:26:59 +0000 Subject: [PATCH 083/509] appveyor: tidy-ups - replace two remaining backslashes with forward slashes. - tidy up the way we form and pass `TFLAGS`. Follow-up to 2d4d0c1fd32f5cc3f946c407c8eccd5477b287df #12572 Closes #12582 --- appveyor.sh | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/appveyor.sh b/appveyor.sh index 4a345ff8899..87c9d572a80 100644 --- a/appveyor.sh +++ b/appveyor.sh @@ -72,7 +72,7 @@ elif [ "${BUILD_SYSTEM}" = 'VisualStudioSolution' ]; then ( cd projects ./generate.bat "${VC_VERSION}" - msbuild.exe -maxcpucount "-property:Configuration=${PRJ_CFG}" "Windows\\${VC_VERSION}\\curl-all.sln" + 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 @@ -135,22 +135,26 @@ fi # test if [ "${TESTING}" = 'ON' ]; then - acurl='' - [ -x "$(cygpath -u "C:/msys64/usr/bin/curl.exe")" ] && acurl="-ac $(cygpath -u "C:/msys64/usr/bin/curl.exe")" - [ -x "$(cygpath -u "${WINDIR}/System32/curl.exe")" ] && acurl="-ac $(cygpath -u "${WINDIR}/System32/curl.exe")" + 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/ - TFLAGS="${acurl} ${DISABLED_TESTS:-}" cmake --build _bld --config "${PRJ_CFG}" --target test-ci + cmake --build _bld --config "${PRJ_CFG}" --target test-ci elif [ "${BUILD_SYSTEM}" = 'autotools' ]; then ( cd _bld - make -j2 V=1 TFLAGS="${acurl} ${DISABLED_TESTS:-}" test-ci + make -j2 V=1 test-ci ) else ( + TFLAGS="-a -p !flaky -r -rm ${TFLAGS}" cd _bld/tests - # shellcheck disable=SC2086 - ./runtests.pl -a -p !flaky -r -rm ${acurl} ${DISABLED_TESTS:-} + ./runtests.pl ) fi fi From 9faeebca883b3d8a57ca291e4f1b80382e236b5a Mon Sep 17 00:00:00 2001 From: Haydar Alaidrus Date: Sun, 24 Dec 2023 02:28:06 +0700 Subject: [PATCH 084/509] CURLOPT_POSTFIELDS.3: fix incorrect C string escape in example - Escape inner quotes with two backslashes. Two backslashes escapes the backslash for the man page and will show as a single backslash. eg: "{\\"name\\": \\"daniel\\"}" shows as "{\"name\": \"daniel\"}". Closes https://github.com/curl/curl/pull/12588 --- docs/libcurl/opts/CURLOPT_POSTFIELDS.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 index c42cd65fbf0..6efdb95316e 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 @@ -97,7 +97,7 @@ int main(void) /* send an application/json POST */ curl = curl_easy_init(); if(curl) { - const char *json = "{\"name\": \"daniel\"}"; + const char *json = "{\\"name\\": \\"daniel\\"}"; struct curl_slist *slist1 = NULL; slist1 = curl_slist_append(slist1, "Content-Type: application/json"); slist1 = curl_slist_append(slist1, "Accept: application/json"); From 82cbdd8396d8b70173757d06ac833c1f7c8f8f47 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Tue, 26 Dec 2023 03:28:46 -0500 Subject: [PATCH 085/509] examples/sendrecv: fix comment line length Caught by checksrc. --- docs/examples/sendrecv.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/examples/sendrecv.c b/docs/examples/sendrecv.c index f35b88d645e..eabe0c2269b 100644 --- a/docs/examples/sendrecv.c +++ b/docs/examples/sendrecv.c @@ -45,7 +45,8 @@ static int wait_on_socket(curl_socket_t sockfd, int for_recv, long timeout_ms) FD_ZERO(&errfd); /* Avoid this warning with pre-2020 Cygwin/MSYS releases: - * warning: conversion to 'long unsigned int' from 'curl_socket_t' {aka 'int'} may change the sign of the result [-Wsign-conversion] + * warning: conversion to 'long unsigned int' from 'curl_socket_t' {aka 'int'} + * may change the sign of the result [-Wsign-conversion] */ #if defined(__GNUC__) && defined(__CYGWIN__) #pragma GCC diagnostic push From 2b221d42142a896b173ae66c901c6a2834320252 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Dec 2023 09:24:42 +0100 Subject: [PATCH 086/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 7c4ae43a75c..379be612ae7 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,10 +4,11 @@ curl and libcurl 8.6.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3052 + Contributors: 3056 This release includes the following changes: + o asyn-thread: use GetAddrInfoExW on >= Windows 8 [55] o curl.h: add CURLE_TOO_LARGE [48] o CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add [39] o runtests: support -gl. Like -g but for lldb. [47] @@ -15,6 +16,7 @@ This release includes the following changes: This release includes the following bugfixes: o altsvc: free 'as' when returning error [23] + o appveyor: replace PowerShell with bash + parallel autotools [54] o appveyor: switch to out-of-tree builds [29] o build: delete unused `HAVE_{GSSHEIMDAL,GSSMIT,HEIMDAL}` [4] o build: enable missing OpenSSF-recommended warnings, with fixes [11] @@ -30,12 +32,15 @@ This release includes the following bugfixes: o cmdline/gen: fix the sorting of the man page options [33] o cookie: avoid fopen with empty file name [24] o curl: show ipfs and ipns as supported "protocols" [15] + o CURLOPT_POSTFIELDS.3: fix incorrect C string escape in example [27] + o CURLOPT_SSH_*_KEYFILE: clarify [57] o dist: add tests/errorcodes.pl to the tarball [6] o docs: clean up Protocols: for cmdline options [32] o doh: remove unused local variable [34] o ftp: handle the PORT parsing without allocation [44] o gnutls: fix build with --disable-verbose [3] o hostip: return error immediately when Curl_ip2addr() fails [19] + o http2: improved on_stream_close/data_done handling [49] o http: fix off-by-one error in request method length check [14] o lib: fix variable undeclared error caused by `infof` changes [2] o lib: reduce use of strncpy [30] @@ -45,15 +50,21 @@ This release includes the following bugfixes: o libssh: supress warnings without version check [18] o Makefile.am: fix the MSVC project generation [22] o Makefile.mk: drop Windows support [12] + o mbedtls: free the entropy when threaded [46] + o mprintf: overhaul and bugfixes [52] + o ngtcp2: put h3 at the front of alpn [58] o openssl: re-match LibreSSL deinit with init [17] o readwrite_data: loop less [21] o Revert "urldata: move async resolver state from easy handle to connectdata" [16] o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] o sendf: fix compiler warning with CURL_DISABLE_HEADERS_API [38] o ssh: fix namespace of two local macros [51] + o strerror: repair get_winsock_error() [56] o system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers [9] o tests/server: delete workaround for old-mingw [25] o tests: respect $TMPDIR when creating unix domain sockets [50] + o tool_getparam: do not try to expand without an argument [59] + o transfer: fix upload rate limiting, add test cases [37] o url: for disabled protocols, mention if found in redirect [7] o vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY [41] o windows: delete redundant headers [43] @@ -72,13 +83,15 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - Baruch Siach, Ben, Boris Verkhovskiy, Cajus Pollmeier, Chara White, - Chris Sauer, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, Dmitry Karpov, - iAroc on github, Mark Sinkovics, Mauricio Scheffer, Michał Antoniak, - Mike Hommey, Ray Satiro, Stefan Eissing, Tatsuhiko Miyagawa, Theo, + Baruch Siach, Ben, Boris Verkhovskiy, Cajus Pollmeier, calvin2021y on github, + Chara White, Chris Sauer, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, + Dmitry Karpov, Geeknik Labs, Hans-Christian Egtvedt, Haydar Alaidrus, + iAroc on github, ivanfywang, Karthikdasari0423 on github, Mark Sinkovics, + Mauricio Scheffer, Michał Antoniak, Mike Hommey, Pavel Pavlov, Ray Satiro, + RevaliQaQ on github, Stefan Eissing, Tatsuhiko Miyagawa, Theo, Viktor Szakats, Xi Ruoyao, Yedaya Katsman, Yifei Kong, YX Hao, zengwei, zengwei2000 - (26 contributors) + (34 contributors) References to bug reports and discussions on issues: @@ -108,6 +121,7 @@ References to bug reports and discussions on issues: [24] = https://curl.se/bug/?i=12514 [25] = https://curl.se/bug/?i=12510 [26] = https://curl.se/bug/?i=12557 + [27] = https://curl.se/bug/?i=12588 [29] = https://curl.se/bug/?i=12550 [30] = https://curl.se/bug/?i=12499 [31] = https://curl.se/bug/?i=12503 @@ -116,6 +130,7 @@ References to bug reports and discussions on issues: [34] = https://curl.se/bug/?i=12491 [35] = https://curl.se/bug/?i=12441 [36] = https://curl.se/bug/?i=12490 + [37] = https://curl.se/bug/?i=12559 [38] = https://curl.se/bug/?i=12485 [39] = https://curl.se/bug/?i=12369 [40] = https://curl.se/bug/?i=12540 @@ -124,8 +139,17 @@ References to bug reports and discussions on issues: [43] = https://curl.se/bug/?i=12539 [44] = https://curl.se/bug/?i=12456 [45] = https://curl.se/bug/?i=12537 + [46] = https://curl.se/bug/?i=12584 [47] = https://curl.se/bug/?i=12547 [48] = https://curl.se/bug/?i=12269 + [49] = https://curl.se/bug/?i=10936 [50] = https://curl.se/bug/?i=12545 [51] = https://curl.se/bug/?i=12544 + [52] = https://curl.se/bug/?i=12561 [53] = https://curl.se/bug/?i=12515 + [54] = https://curl.se/bug/?i=12560 + [55] = https://curl.se/bug/?i=12481 + [56] = https://curl.se/bug/?i=12578 + [57] = https://curl.se/bug/?i=12554 + [58] = https://curl.se/bug/?i=12576 + [59] = https://curl.se/bug/?i=12565 From 68f96fc9bfce90c264d4d95b91135f3ef945eea8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Dec 2023 09:28:48 +0100 Subject: [PATCH 087/509] getinfo: CURLINFO_QUEUE_TIME_T Returns the time, in microseconds, during which this transfer was held in a waiting queue before it started "for real". A transfer might be put in a queue if after getting started, it cannot create a new connection etc due to set conditions and limits imposed by the application. Ref: #12293 Closes #12368 --- docs/libcurl/curl_easy_getinfo.3 | 21 ++++--- docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 | 74 +++++++++++++++++++++++ docs/libcurl/opts/Makefile.inc | 1 + docs/libcurl/symbols-in-versions | 1 + include/curl/curl.h | 3 +- lib/getinfo.c | 5 +- lib/multi.c | 1 + lib/progress.c | 10 ++- lib/progress.h | 3 +- lib/urldata.h | 1 + 10 files changed, 109 insertions(+), 11 deletions(-) create mode 100644 docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index f3c9f946ce9..153551f10a8 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -95,6 +95,9 @@ See \fICURLINFO_PRETRANSFER_TIME(3)\fP .IP CURLINFO_PRETRANSFER_TIME_T Time from start until just before the transfer begins. See \fICURLINFO_PRETRANSFER_TIME_T(3)\fP +.IP CURLINFO_QUEUE_TIME_T +Time during which this transfer was held in a waiting queue. +See \fICURLINFO_QUEUE_TIME_T(3\fP .IP CURLINFO_STARTTRANSFER_TIME Time from start until just when the first byte is received. See \fICURLINFO_STARTTRANSFER_TIME(3)\fP @@ -259,14 +262,18 @@ An overview of the six time values available from \fIcurl_easy_getinfo(3)\fP curl_easy_perform() | - |--NAMELOOKUP - |--|--CONNECT - |--|--|--APPCONNECT - |--|--|--|--PRETRANSFER - |--|--|--|--|--STARTTRANSFER - |--|--|--|--|--|--TOTAL - |--|--|--|--|--|--REDIRECT + |--QUEUE_TIME + |--|--NAMELOOKUP + |--|--|--CONNECT + |--|--|--|--APPCONNECT + |--|--|--|--|--PRETRANSFER + |--|--|--|--|--|--STARTTRANSFER + |--|--|--|--|--|--|--TOTAL + |--|--|--|--|--|--|--REDIRECT .fi +.IP "QUEUE_TIME" +\fICURLINFO_QUEUE_TIME_T(3\fP. The time during which the transfer was held in +a waiting queue before it could start for real. (Added in 8.6.0) .IP NAMELOOKUP \fICURLINFO_NAMELOOKUP_TIME(3)\fP and \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP. The time it took from the start until the name resolving was completed. diff --git a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 new file mode 100644 index 00000000000..5ccd7c48a78 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 @@ -0,0 +1,74 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 +.\" * +.\" ************************************************************************** +.\" +.TH CURLINFO_QUEUE_TIME_T 3 "28 Apr 2018" libcurl libcurl +.SH NAME +CURLINFO_QUEUE_TIME_T \- time this transfer was queued +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_QUEUE_TIME_T, + curl_off_t *timep); +.fi +.SH DESCRIPTION +Pass a pointer to a curl_off_t to receive the time, in microseconds, this +transfer was held in a waiting queue before it started "for real". A transfer +might be put in a queue if after getting started, it cannot create a new +connection etc due to set conditions and limits imposed by the application. + +See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t queue; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_QUEUE_TIME_T, &queue); + if(CURLE_OK == res) { + printf("Queued: %" CURL_FORMAT_CURL_OFF_T ".%06ld us", queue / 1000000, + (long)(queue % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in 8.6.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR curl_easy_getinfo (3), +.BR curl_easy_setopt (3), +.BR CURLINFO_STARTTRANSFER_TIME_T (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc index 4b581c5be4e..be7035bf00d 100644 --- a/docs/libcurl/opts/Makefile.inc +++ b/docs/libcurl/opts/Makefile.inc @@ -65,6 +65,7 @@ man_MANS = \ CURLINFO_PROXY_ERROR.3 \ CURLINFO_PROXY_SSL_VERIFYRESULT.3 \ CURLINFO_PROXYAUTH_AVAIL.3 \ + CURLINFO_QUEUE_TIME_T.3 \ CURLINFO_REDIRECT_COUNT.3 \ CURLINFO_REDIRECT_TIME.3 \ CURLINFO_REDIRECT_TIME_T.3 \ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index a77a5255025..c20008a7313 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -469,6 +469,7 @@ CURLINFO_PROXY_ERROR 7.73.0 CURLINFO_PROXY_SSL_VERIFYRESULT 7.52.0 CURLINFO_PROXYAUTH_AVAIL 7.10.8 CURLINFO_PTR 7.54.1 +CURLINFO_QUEUE_TIME_T 8.6.0 CURLINFO_REDIRECT_COUNT 7.9.7 CURLINFO_REDIRECT_TIME 7.9.7 CURLINFO_REDIRECT_TIME_T 7.61.0 diff --git a/include/curl/curl.h b/include/curl/curl.h index a5b59e0268a..b35ac95553e 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -2936,7 +2936,8 @@ typedef enum { CURLINFO_CAPATH = CURLINFO_STRING + 62, CURLINFO_XFER_ID = CURLINFO_OFF_T + 63, CURLINFO_CONN_ID = CURLINFO_OFF_T + 64, - CURLINFO_LASTONE = 64 + CURLINFO_QUEUE_TIME_T = CURLINFO_OFF_T + 65, + CURLINFO_LASTONE = 65 } CURLINFO; /* CURLINFO_RESPONSE_CODE is the new name for the option previously known as diff --git a/lib/getinfo.c b/lib/getinfo.c index f1574e097b1..2f74629e1e7 100644 --- a/lib/getinfo.c +++ b/lib/getinfo.c @@ -409,6 +409,9 @@ static CURLcode getinfo_offt(struct Curl_easy *data, CURLINFO info, case CURLINFO_STARTTRANSFER_TIME_T: *param_offt = data->progress.t_starttransfer; break; + case CURLINFO_QUEUE_TIME_T: + *param_offt = data->progress.t_postqueue; + break; case CURLINFO_REDIRECT_TIME_T: *param_offt = data->progress.t_redirect; break; @@ -420,7 +423,7 @@ static CURLcode getinfo_offt(struct Curl_easy *data, CURLINFO info, break; case CURLINFO_CONN_ID: *param_offt = data->conn? - data->conn->connection_id : data->state.recent_conn_id; + data->conn->connection_id : data->state.recent_conn_id; break; default: return CURLE_UNKNOWN_OPTION; diff --git a/lib/multi.c b/lib/multi.c index 89a02680a55..9c7cde8f16c 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -1943,6 +1943,7 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, } if(!result) { + *nowp = Curl_pgrsTime(data, TIMER_POSTQUEUE); if(async) /* We're now waiting for an asynchronous name lookup */ multistate(data, MSTATE_RESOLVING); diff --git a/lib/progress.c b/lib/progress.c index e96cbf7af4c..d05fcc3ebd8 100644 --- a/lib/progress.c +++ b/lib/progress.c @@ -174,10 +174,18 @@ void Curl_pgrsTimeWas(struct Curl_easy *data, timerid timer, data->progress.t_startop = timestamp; break; case TIMER_STARTSINGLE: - /* This is set at the start of each single fetch */ + /* This is set at the start of each single transfer */ data->progress.t_startsingle = timestamp; data->progress.is_t_startransfer_set = false; break; + case TIMER_POSTQUEUE: + /* Set when the transfer starts (after potentially having been brought + back from the waiting queue). It needs to count from t_startop and not + t_startsingle since the latter is reset when a connection is brought + back from the pending queue. */ + data->progress.t_postqueue = + Curl_timediff_us(timestamp, data->progress.t_startop); + break; case TIMER_STARTACCEPT: data->progress.t_acceptdata = timestamp; break; diff --git a/lib/progress.h b/lib/progress.h index fc39e34d200..73749419add 100644 --- a/lib/progress.h +++ b/lib/progress.h @@ -30,7 +30,8 @@ typedef enum { TIMER_NONE, TIMER_STARTOP, - TIMER_STARTSINGLE, + TIMER_STARTSINGLE, /* start of transfer, might get queued */ + TIMER_POSTQUEUE, /* start, immediately after dequeue */ TIMER_NAMELOOKUP, TIMER_CONNECT, TIMER_APPCONNECT, diff --git a/lib/urldata.h b/lib/urldata.h index be9158325b8..210fca76c48 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1189,6 +1189,7 @@ struct Progress { curl_off_t dlspeed; curl_off_t ulspeed; + timediff_t t_postqueue; timediff_t t_nslookup; timediff_t t_connect; timediff_t t_appconnect; From fa6e123929de94064f1b1cb135f30b0a945ba399 Mon Sep 17 00:00:00 2001 From: Patrick Monnerat Date: Wed, 27 Dec 2023 11:19:17 +0100 Subject: [PATCH 088/509] openldap: fix an LDAP crash Reported-by: Ozan Cansel Fixes #12593 Closes #12600 --- lib/openldap.c | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/lib/openldap.c b/lib/openldap.c index c9417fbe2a1..fcc9f91f44c 100644 --- a/lib/openldap.c +++ b/lib/openldap.c @@ -887,10 +887,14 @@ static CURLcode oldap_do(struct Curl_easy *data, bool *done) result = oldap_url_parse(data, &lud); if(!result) { - Sockbuf *sb; - /* re-install the libcurl SSL handlers into the sockbuf. */ - ldap_get_option(li->ld, LDAP_OPT_SOCKBUF, &sb); - ber_sockbuf_add_io(sb, &ldapsb_tls, LBER_SBIOD_LEVEL_TRANSPORT, data); +#ifdef USE_SSL + if(ssl_installed(conn)) { + Sockbuf *sb; + /* re-install the libcurl SSL handlers into the sockbuf. */ + ldap_get_option(li->ld, LDAP_OPT_SOCKBUF, &sb); + ber_sockbuf_add_io(sb, &ldapsb_tls, LBER_SBIOD_LEVEL_TRANSPORT, data); + } +#endif rc = ldap_search_ext(li->ld, lud->lud_dn, lud->lud_scope, lud->lud_filter, lud->lud_attrs, 0, From f111603176edab8bfc01f9707c91d035b41e8bd2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Dec 2023 23:15:09 +0100 Subject: [PATCH 089/509] KNOWN_BUGS: [RTSP] Some methods do not support response bodies Closes #12414 --- docs/KNOWN_BUGS | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index e52774a15f5..254bc8479f5 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -110,6 +110,9 @@ problems may have been fixed or changed somewhat since this was written. 18. HTTP/3 18.1 connection migration does not work + 19. RTSP + 19.1 Some methods do not support response bodies + ============================================================================== 1. HTTP @@ -602,3 +605,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 From e251e858b941e29bb95a6c0d26bb45981a872585 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Tue, 26 Dec 2023 19:08:48 -0500 Subject: [PATCH 090/509] vtls: fix missing multissl version info - Fix erroneous buffer copy logic from ff74cef5. Prior to this change the MultiSSL version info returned to the user was empty. Closes https://github.com/curl/curl/pull/12599 --- lib/vtls/vtls.c | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/lib/vtls/vtls.c b/lib/vtls/vtls.c index 256b8faa804..7f6ce09d7cf 100644 --- a/lib/vtls/vtls.c +++ b/lib/vtls/vtls.c @@ -1413,10 +1413,12 @@ static size_t multissl_version(char *buffer, size_t size) backends_len = p - backends; } - if(size && (size < backends_len)) - strcpy(buffer, backends); - else - *buffer = 0; /* did not fit */ + if(size) { + if(backends_len < size) + strcpy(buffer, backends); + else + *buffer = 0; /* did not fit */ + } return 0; } From aa2c2ab837b18c3bcb4a6ce4542ce4ed89ab5093 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Sat, 23 Dec 2023 16:45:53 -0500 Subject: [PATCH 091/509] verify-examples.pl: fail verification on unescaped backslash - Check that all backslashes in EXAMPLE are properly escaped. eg manpage must always use `\\n` never `\n`. This is because the manpage requires we always double blackslash to show a single backslash. Prior to this change an erroneous single backslash would pass through and compile even though it would not show correctly in the manpage. Co-authored-by: Daniel Stenberg Ref: https://github.com/curl/curl/pull/12588 Closes https://github.com/curl/curl/pull/12589 --- .github/scripts/verify-examples.pl | 18 ++++++++++++++---- .github/workflows/man-examples.yml | 2 ++ 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/.github/scripts/verify-examples.pl b/.github/scripts/verify-examples.pl index 0b750711ea1..377fe8340c4 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(/(? Date: Wed, 27 Dec 2023 19:01:46 -0500 Subject: [PATCH 092/509] system_win32: fix a function pointer assignment warning - Use CURLX_FUNCTION_CAST to suppress a function pointer assignment warning. a6bbc87f added lookups of some Windows API functions and then cast them like `*(FARPROC*)&Curl_funcname = address`. Some versions of gcc warn about that as breaking strict-aliasing rules so this PR changes those assignments to use CURLX_FUNCTION_CAST. Bug: https://github.com/curl/curl/pull/12581#issuecomment-1869804317 Reported-by: Marcel Raad Closes https://github.com/curl/curl/pull/12602 --- lib/system_win32.c | 26 +++++++++++--------------- lib/system_win32.h | 14 +++++++++----- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/lib/system_win32.c b/lib/system_win32.c index dd34140d726..d2862de9231 100644 --- a/lib/system_win32.c +++ b/lib/system_win32.c @@ -43,21 +43,17 @@ bool Curl_isWindows8OrGreater; /* Handle of iphlpapp.dll */ static HMODULE s_hIpHlpApiDll = NULL; -/* Pointer to the if_nametoindex function */ +/* Function pointers */ IF_NAMETOINDEX_FN Curl_if_nametoindex = NULL; - -void(WSAAPI *Curl_FreeAddrInfoExW)(ADDRINFOEXW_ *pAddrInfoEx) = NULL; -int(WSAAPI *Curl_GetAddrInfoExCancel)(LPHANDLE lpHandle) = NULL; -int(WSAAPI *Curl_GetAddrInfoExW)(PCWSTR pName, PCWSTR pServiceName, - DWORD dwNameSpace, LPGUID lpNspId, const ADDRINFOEXW_ *hints, - ADDRINFOEXW_ **ppResult, struct timeval *timeout, LPOVERLAPPED lpOverlapped, - LOOKUP_COMPLETION lpCompletionRoutine, LPHANDLE lpHandle) = NULL; +FREEADDRINFOEXW_FN Curl_FreeAddrInfoExW = NULL; +GETADDRINFOEXCANCEL_FN Curl_GetAddrInfoExCancel = NULL; +GETADDRINFOEXW_FN Curl_GetAddrInfoExW = NULL; /* Curl_win32_init() performs win32 global initialization */ CURLcode Curl_win32_init(long flags) { #ifdef USE_WINSOCK - HANDLE ws2_32Dll; + HMODULE ws2_32Dll; #endif /* CURL_GLOBAL_WIN32 controls the *optional* part of the initialization which is just for Winsock at the moment. Any required win32 initialization @@ -118,12 +114,12 @@ CURLcode Curl_win32_init(long flags) #ifdef USE_WINSOCK ws2_32Dll = GetModuleHandleA("ws2_32"); if(ws2_32Dll) { - *(FARPROC*)&Curl_FreeAddrInfoExW = GetProcAddress(ws2_32Dll, - "FreeAddrInfoExW"); - *(FARPROC*)&Curl_GetAddrInfoExCancel = GetProcAddress(ws2_32Dll, - "GetAddrInfoExCancel"); - *(FARPROC*)&Curl_GetAddrInfoExW = GetProcAddress(ws2_32Dll, - "GetAddrInfoExW"); + Curl_FreeAddrInfoExW = CURLX_FUNCTION_CAST(FREEADDRINFOEXW_FN, + GetProcAddress(ws2_32Dll, "FreeAddrInfoExW")); + Curl_GetAddrInfoExCancel = CURLX_FUNCTION_CAST(GETADDRINFOEXCANCEL_FN, + GetProcAddress(ws2_32Dll, "GetAddrInfoExCancel")); + Curl_GetAddrInfoExW = CURLX_FUNCTION_CAST(GETADDRINFOEXW_FN, + GetProcAddress(ws2_32Dll, "GetAddrInfoExW")); } #endif diff --git a/lib/system_win32.h b/lib/system_win32.h index 42bbb143f31..bd490cabcc8 100644 --- a/lib/system_win32.h +++ b/lib/system_win32.h @@ -57,12 +57,16 @@ typedef struct addrinfoexW_ struct addrinfoexW_ *ai_next; } ADDRINFOEXW_; -typedef void(CALLBACK *LOOKUP_COMPLETION)(DWORD, DWORD, LPWSAOVERLAPPED); -extern void(WSAAPI *Curl_FreeAddrInfoExW)(ADDRINFOEXW_*); -extern int(WSAAPI *Curl_GetAddrInfoExCancel)(LPHANDLE); -extern int(WSAAPI *Curl_GetAddrInfoExW)(PCWSTR, PCWSTR, DWORD, LPGUID, +typedef void (CALLBACK *LOOKUP_COMPLETION_FN)(DWORD, DWORD, LPWSAOVERLAPPED); +typedef void (WSAAPI *FREEADDRINFOEXW_FN)(ADDRINFOEXW_*); +typedef int (WSAAPI *GETADDRINFOEXCANCEL_FN)(LPHANDLE); +typedef int (WSAAPI *GETADDRINFOEXW_FN)(PCWSTR, PCWSTR, DWORD, LPGUID, const ADDRINFOEXW_*, ADDRINFOEXW_**, struct timeval*, LPOVERLAPPED, - LOOKUP_COMPLETION, LPHANDLE); + LOOKUP_COMPLETION_FN, LPHANDLE); + +extern FREEADDRINFOEXW_FN Curl_FreeAddrInfoExW; +extern GETADDRINFOEXCANCEL_FN Curl_GetAddrInfoExCancel; +extern GETADDRINFOEXW_FN Curl_GetAddrInfoExW; /* This is used to dynamically load DLLs */ HMODULE Curl_load_library(LPCTSTR filename); From 6f17ead7b386769ab12ba2b90173f43e2cf29d92 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 28 Dec 2023 18:19:24 +0100 Subject: [PATCH 093/509] CURLINFO_REFERER.3: clarify that it is the *request* header That libcurl itself sent in the most recent request Closes #12605 --- docs/libcurl/opts/CURLINFO_REFERER.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/libcurl/opts/CURLINFO_REFERER.3 b/docs/libcurl/opts/CURLINFO_REFERER.3 index 550ccf9aee5..cc1a3c6673a 100644 --- a/docs/libcurl/opts/CURLINFO_REFERER.3 +++ b/docs/libcurl/opts/CURLINFO_REFERER.3 @@ -24,7 +24,7 @@ .\" .TH CURLINFO_REFERER 3 "11 Feb 2021" libcurl libcurl .SH NAME -CURLINFO_REFERER \- get the referrer header +CURLINFO_REFERER \- get the used referrer request header .SH SYNOPSIS .nf #include @@ -32,7 +32,8 @@ CURLINFO_REFERER \- get the referrer header CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REFERER, char **hdrp); .fi .SH DESCRIPTION -Pass in a pointer to a char pointer and get the referrer header. +Pass in a pointer to a char pointer and get the referrer header used in the +most recent request. The \fBhdrp\fP pointer is NULL or points to private memory you MUST NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding From 69b6953681d3e3172e27ef59c541d6b705ad6f9b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 28 Dec 2023 23:03:40 +0100 Subject: [PATCH 094/509] CURLOPT_AUTOREFERER.3: mention CURLINFO_REFERER --- docs/libcurl/opts/CURLOPT_AUTOREFERER.3 | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 index 5f94efc0090..e35f7041187 100644 --- a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 +++ b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 @@ -39,6 +39,9 @@ when it follows a Location: redirect to a new destination. The automatic referer is set to the full previous URL even when redirects are done cross-origin or following redirects to insecure protocols. This is considered a minor privacy leak by some. + +With \fICURLINFO_REFERER(3)\fP, applications can extract the actually used +referer header after the transfer. .SH DEFAULT 0, disabled .SH PROTOCOLS @@ -71,5 +74,6 @@ Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLINFO_EFFECTIVE_URL (3), .BR CURLINFO_REDIRECT_URL (3), +.BR CURLINFO_REFERER (3), .BR CURLOPT_FOLLOWLOCATION (3), .BR CURLOPT_REFERER (3) From 0af61bffb161c22ae751d84d9cfa401304e9344b Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 28 Dec 2023 22:26:02 -0800 Subject: [PATCH 095/509] CI: Fix use of any-glob-to-all-files in the labeler Despite its name, this atom acts like one-glob-to-all-files and a different syntax with braces must be used to get any-glob-to-all-files semantics. Unfortunately, this makes the file completely unreadable. Ref: https://github.com/actions/labeler/issues/731 --- .github/labeler.yml | 310 ++++++-------------------------------------- 1 file changed, 37 insertions(+), 273 deletions(-) diff --git a/.github/labeler.yml b/.github/labeler.yml index 916219c0469..cef2789d84e 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -14,67 +14,29 @@ # "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' + - '{.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' + - '{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' + - '{**/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: @@ -94,10 +56,7 @@ cmake: - all: - changed-files: - any-glob-to-all-files: - - '**/CMakeLists.txt' - - 'CMake/**' - - 'docs/INSTALL.cmake' - - 'lib/curl_config.h.cmake' + - '{**/CMakeLists.txt,CMake/**,docs/INSTALL.cmake,lib/curl_config.h.cmake}' cmdline tool: - all: @@ -110,79 +69,31 @@ 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' + - '{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.*' + - '{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.*}' 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.*' + - '{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.*}' DICT: - all: - changed-files: - any-glob-to-all-files: - - 'lib/dict.*' - - 'tests/dictserver.py' + - '{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' + - '{**/*.md,**/*.txt,**/*.1,**/*.3,CHANGES,docs/**,GIT-INFO,LICENSES/**,README,RELEASE-NOTES}' - all-globs-to-all-files: # negative matches - '!**/CMakeLists.txt' @@ -192,103 +103,49 @@ 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*' + - '{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*' + - '{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*' + - '{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' + - '{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' + - '{.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}' Hyper: - all: - changed-files: - any-glob-to-all-files: - - 'docs/HYPER.md' - - 'lib/c-hyper.*' + - '{docs/HYPER.md,lib/c-hyper.*}' IMAP: - all: - changed-files: - any-glob-to-all-files: - - 'lib/imap*' - - 'docs/examples/imap*' + - '{lib/imap*,docs/examples/imap*}' LDAP: - all: - changed-files: - any-glob-to-all-files: - - 'lib/*ldap*' + - '{lib/*ldap*}' libcurl API: - all: @@ -302,109 +159,67 @@ 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' + - '{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.*' + - '{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' + - '{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' + - '{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.*' + - '{docs/examples/pop3*,lib/pop3.*}' RTMP: - all: - changed-files: - any-glob-to-all-files: - - 'lib/curl_rtmp.*' + - '{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' + - '{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' + - '{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/**' + - '{**/*.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' + - '{lib/smb.*,tests/smbserver.py}' SMTP: - all: - changed-files: - any-glob-to-all-files: - - 'docs/examples/smtp-*' - - 'docs/libcurl/opts/CURLOPT_MAIL*' - - 'lib/smtp.*' + - '{docs/examples/smtp-*,docs/libcurl/opts/CURLOPT_MAIL*,lib/smtp.*}' tests: - all: @@ -416,79 +231,28 @@ TFTP: - all: - changed-files: - any-glob-to-all-files: - - 'lib/tftp.*' - - 'tests/tftpserver.pl' - - 'tests/server/tftp*' + - '{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' + - '{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*' + - '{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*' + - '{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: - - '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' + - '{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}' From ae75db3527461248b0a7b1686df52200d28d83b9 Mon Sep 17 00:00:00 2001 From: annalee <150648636+a-n-n-a-l-e-e@users.noreply.github.com> Date: Fri, 29 Dec 2023 05:43:33 +0000 Subject: [PATCH 096/509] configure: fix no default int compile error in ipv6 detection Closes #12607 --- configure.ac | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/configure.ac b/configure.ac index 3e89da9f328..79c98b3c4e9 100644 --- a/configure.ac +++ b/configure.ac @@ -1655,15 +1655,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; } ]]) ], From d16d18cf641d412f40269e1c8469f84201673204 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 30 Dec 2023 23:19:37 +0100 Subject: [PATCH 097/509] haproxy-clientip.d: document the arg The arg keyword was missing and therefore not present in the man page. Closes #12611 --- docs/cmdline-opts/haproxy-clientip.d | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/cmdline-opts/haproxy-clientip.d b/docs/cmdline-opts/haproxy-clientip.d index 25cb7e62361..9958849412b 100644 --- a/docs/cmdline-opts/haproxy-clientip.d +++ b/docs/cmdline-opts/haproxy-clientip.d @@ -1,6 +1,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: haproxy-clientip +Arg: Help: Sets client IP in HAProxy PROXY protocol v1 header Protocols: HTTP Added: 8.2.0 @@ -24,6 +25,3 @@ 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. From 4b6d44f6e9bd728b8568cc91ab02ba35e709104b Mon Sep 17 00:00:00 2001 From: Patrick Monnerat Date: Sat, 30 Dec 2023 17:31:04 +0100 Subject: [PATCH 098/509] openldap: fix STARTTLS It was not working anymore since introduction of connection filters. Also do not attempt to recover from a failing TLS negotiation with CURLUSESSL_TRY. Closes #12610 --- lib/openldap.c | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/lib/openldap.c b/lib/openldap.c index fcc9f91f44c..171a4c3ce8c 100644 --- a/lib/openldap.c +++ b/lib/openldap.c @@ -793,10 +793,13 @@ static CURLcode oldap_connecting(struct Curl_easy *data, bool *done) result = oldap_perform_bind(data, OLDAP_BIND); break; } + result = Curl_ssl_cfilter_add(data, conn, FIRSTSOCKET); + if(result) + break; FALLTHROUGH(); case OLDAP_TLS: result = oldap_ssl_connect(data, OLDAP_TLS); - if(result && data->set.use_ssl != CURLUSESSL_TRY) + if(result) result = oldap_map_error(code, CURLE_USE_SSL_FAILED); else if(ssl_installed(conn)) { conn->bits.tls_upgraded = TRUE; From 373d34494c7fc1fd0928e846d32c5d970a985d09 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 31 Dec 2023 16:49:54 +0100 Subject: [PATCH 099/509] cmdline-opts: update availability for the *-ca-native options Closes #12613 --- docs/cmdline-opts/ca-native.d | 9 ++++----- docs/cmdline-opts/proxy-ca-native.d | 9 ++++----- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/cmdline-opts/ca-native.d b/docs/cmdline-opts/ca-native.d index 51e36918aa6..9a8184c640f 100644 --- a/docs/cmdline-opts/ca-native.d +++ b/docs/cmdline-opts/ca-native.d @@ -14,8 +14,7 @@ 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). +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-ca-native.d b/docs/cmdline-opts/proxy-ca-native.d index aab4fcabc2a..63439b7f1ba 100644 --- a/docs/cmdline-opts/proxy-ca-native.d +++ b/docs/cmdline-opts/proxy-ca-native.d @@ -14,8 +14,7 @@ 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). +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. From b83729a339f5904832e4e524eb2e9499dbdb53e9 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Tue, 26 Dec 2023 01:55:54 -0500 Subject: [PATCH 100/509] quiche: return CURLE_HTTP3 on send to invalid stream Prior to this change if a send failed on a stream in an invalid state (according to quiche) and not marked as closed (according to libcurl) then the send function would return CURLE_SEND_ERROR. We already have similar code for ngtcp2 to return CURLE_HTTP3 in this case. Caught by test test_07_upload.py: test_07_22_upload_parallel_fail. Fixes https://github.com/curl/curl/issues/12590 Closes https://github.com/curl/curl/pull/12597 --- lib/vquic/curl_ngtcp2.c | 2 ++ lib/vquic/curl_quiche.c | 41 +++++++++++++++++++++++++++-------------- 2 files changed, 29 insertions(+), 14 deletions(-) diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index fb1ef60a0a4..f4edf2d636e 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -1894,6 +1894,8 @@ static ssize_t cf_ngtcp2_send(struct Curl_cfilter *cf, struct Curl_easy *data, sent = (ssize_t)len; goto out; } + CURL_TRC_CF(data, cf, "[%" PRId64 "] send_body(len=%zu) " + "-> stream closed", stream->id, len); *err = CURLE_HTTP3; sent = -1; goto out; diff --git a/lib/vquic/curl_quiche.c b/lib/vquic/curl_quiche.c index 91395876b46..227adbdd9a6 100644 --- a/lib/vquic/curl_quiche.c +++ b/lib/vquic/curl_quiche.c @@ -1078,6 +1078,28 @@ static ssize_t cf_quiche_send(struct Curl_cfilter *cf, struct Curl_easy *data, goto out; stream = H3_STREAM_CTX(data); } + else if(stream->closed) { + if(stream->resp_hds_complete) { + /* sending request body on a stream that has been closed by the + * server. If the server has send us a final response, we should + * silently discard the send data. + * This happens for example on redirects where the server, instead + * of reading the full request body just closed the stream after + * sending the 30x response. + * This is sort of a race: had the transfer loop called recv first, + * it would see the response and stop/discard sending on its own- */ + CURL_TRC_CF(data, cf, "[%" PRId64 "] discarding data" + "on closed stream with response", stream->id); + *err = CURLE_OK; + nwritten = (ssize_t)len; + goto out; + } + CURL_TRC_CF(data, cf, "[%" PRId64 "] send_body(len=%zu) " + "-> stream closed", stream->id, len); + *err = CURLE_HTTP3; + nwritten = -1; + goto out; + } else { bool eof = (stream->upload_left >= 0 && (curl_off_t)len >= stream->upload_left); @@ -1095,20 +1117,11 @@ static ssize_t cf_quiche_send(struct Curl_cfilter *cf, struct Curl_easy *data, nwritten = -1; goto out; } - else if(nwritten == QUICHE_H3_TRANSPORT_ERR_INVALID_STREAM_STATE && - stream->closed && stream->resp_hds_complete) { - /* sending request body on a stream that has been closed by the - * server. If the server has send us a final response, we should - * silently discard the send data. - * This happens for example on redirects where the server, instead - * of reading the full request body just closed the stream after - * sending the 30x response. - * This is sort of a race: had the transfer loop called recv first, - * it would see the response and stop/discard sending on its own- */ - CURL_TRC_CF(data, cf, "[%" PRId64 "] discarding data" - "on closed stream with response", stream->id); - *err = CURLE_OK; - nwritten = (ssize_t)len; + else if(nwritten == QUICHE_H3_TRANSPORT_ERR_INVALID_STREAM_STATE) { + CURL_TRC_CF(data, cf, "[%" PRId64 "] send_body(len=%zu) " + "-> invalid stream state", stream->id, len); + *err = CURLE_HTTP3; + nwritten = -1; goto out; } else if(nwritten == QUICHE_H3_TRANSPORT_ERR_FINAL_SIZE) { From 8620b11c3a6a38e18850fdfed3024fb8912d8bee Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 1 Jan 2024 22:48:09 +0100 Subject: [PATCH 101/509] runtests: for mode="text" on , fix newlines on both parts Closes #12612 --- tests/runtests.pl | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/runtests.pl b/tests/runtests.pl index 9dbe4e2d68b..17b0d3986c0 100755 --- a/tests/runtests.pl +++ b/tests/runtests.pl @@ -1235,6 +1235,8 @@ sub singletest_check { # text mode when running on windows: fix line endings s/\r\n/\n/g for @validstdout; s/\n/\r\n/g for @validstdout; + s/\r\n/\n/g for @actual; + s/\n/\r\n/g for @actual; } if($hash{'nonewline'}) { From 12f832d950c2cd91fbadf1118e2ceecb0849cf14 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 31 Dec 2023 16:27:46 +0100 Subject: [PATCH 102/509] testutil: make runtests support %include Using this instruction, a test case can include the contents of a file into the test during the preprocessing. Closes #12612 --- tests/FILEFORMAT.md | 11 +++++++++++ tests/testutil.pm | 13 +++++++++++++ 2 files changed, 24 insertions(+) diff --git a/tests/FILEFORMAT.md b/tests/FILEFORMAT.md index 665d93eb855..5a8e7832323 100644 --- a/tests/FILEFORMAT.md +++ b/tests/FILEFORMAT.md @@ -74,6 +74,17 @@ For example, to insert the word hello 100 times: %repeat[100 x hello]% +## Include file + +This instruction allows a test case to include another file. It is helpful to +remember that the ordinary variables are expanded before the include happens +so `%LOGDIR` and the others can be used in the include line. + +The file name cannot contain `%` as that letter is used to end the name for +the include instruction: + + %include filename% + ## Conditional lines Lines in the test file can be made to appear conditionally on a specific diff --git a/tests/testutil.pm b/tests/testutil.pm index ece0b6e0539..1a44083e1bf 100644 --- a/tests/testutil.pm +++ b/tests/testutil.pm @@ -94,6 +94,15 @@ sub clearlogs { ####################################################################### + +sub includefile { + my ($f) = @_; + open(F, "<$f"); + my @a = ; + close(F); + return join("", @a); +} + sub subbase64 { my ($thing) = @_; @@ -113,6 +122,7 @@ sub subbase64 { $d =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; $$thing =~ s/%%HEX%%/$d/; } + # repeat while($$thing =~ s/%repeat\[(\d+) x (.*?)\]%/%%REPEAT%%/i) { # decode %NN characters my ($d, $n) = ($2, $1); @@ -120,6 +130,9 @@ sub subbase64 { my $all = $d x $n; $$thing =~ s/%%REPEAT%%/$all/; } + + # include a file + $$thing =~ s/%include ([^%]*)%[\n\r]+/includefile($1)/ge; } my $prevupdate; # module scope so it remembers the last value From 0f1bb61e86314e82c97243fbc14d821fcf16b727 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 31 Dec 2023 16:28:48 +0100 Subject: [PATCH 103/509] test1478: verify src/tool_listhelp.c Verify that the source file on disk is identical to the output of gen.pl listhelp, as otherwise they are out of sync and need attention. Closes #12612 --- tests/data/Makefile.inc | 2 +- tests/data/test1478 | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 tests/data/test1478 diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 485472271e1..5008b86e011 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -186,7 +186,7 @@ test1439 test1440 test1441 test1442 test1443 test1444 test1445 test1446 \ test1447 test1448 test1449 test1450 test1451 test1452 test1453 test1454 \ test1455 test1456 test1457 test1458 test1459 test1460 test1461 test1462 \ test1463 test1464 test1465 test1466 test1467 test1468 test1469 test1470 \ -test1471 test1472 test1473 test1475 test1476 test1477 \ +test1471 test1472 test1473 test1475 test1476 test1477 test1478 \ \ test1500 test1501 test1502 test1503 test1504 test1505 test1506 test1507 \ test1508 test1509 test1510 test1511 test1512 test1513 test1514 test1515 \ diff --git a/tests/data/test1478 b/tests/data/test1478 new file mode 100644 index 00000000000..ae7732f3497 --- /dev/null +++ b/tests/data/test1478 @@ -0,0 +1,32 @@ + + + +source analysis +documentation +--help + + + +# +# Client-side + + +none + + + +src/tool_listhelp.c is in sync with docs/cmdline-opts + + + +%SRCDIR/../docs/cmdline-opts/gen.pl listhelp %SRCDIR/../docs/cmdline-opts/*.d + + + + + +%include %SRCDIR/../src/tool_listhelp.c% + + + + From b23255af99385ef2432ad138eb0bcbdd24d17089 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 31 Dec 2023 16:29:49 +0100 Subject: [PATCH 104/509] tool_listhelp: regenerate after recent .d updates Makes it survive test 1478 Closes #12612 --- src/tool_listhelp.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/tool_listhelp.c b/src/tool_listhelp.c index 4e7a6dd632c..59a5c95c99a 100644 --- a/src/tool_listhelp.c +++ b/src/tool_listhelp.c @@ -143,7 +143,7 @@ const struct helptxt helptext[] = { CURLHELP_FTP}, {" --disallow-username-in-url", "Disallow username in URL", - CURLHELP_CURL | CURLHELP_HTTP}, + CURLHELP_CURL}, {" --dns-interface ", "Interface to use for DNS requests", CURLHELP_DNS}, @@ -246,7 +246,7 @@ const struct helptxt helptext[] = { {" --happy-eyeballs-timeout-ms ", "Time for IPv6 before trying IPv4", CURLHELP_CONNECTION}, - {" --haproxy-clientip", + {" --haproxy-clientip ", "Sets client IP in HAProxy PROXY protocol v1 header", CURLHELP_HTTP | CURLHELP_PROXY}, {" --haproxy-protocol", From f0ea11b50b78c7ffe92c1c304beb4a66b9630b97 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 1 Jan 2024 15:29:33 +0000 Subject: [PATCH 105/509] asyn-thread: silence `-Wcast-align` warning for Windows Seen with llvm/clang 17: ``` lib/asyn-thread.c:310:5: warning: cast from 'PCHAR' (aka 'char *') to 'struct thread_sync_data *' increases required alignment from 1 to 8 [-Wcast-align] 310 | CONTAINING_RECORD(overlapped, struct thread_sync_data, w8.overlapped); | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .../llvm-mingw/aarch64-w64-mingw32/include/winnt.h:717:48: note: expanded from macro 'CONTAINING_RECORD' 717 | #define CONTAINING_RECORD(address,type,field) ((type *)((PCHAR)(address) - (ULONG_PTR)(&((type *)0)->field))) | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``` Follow-up to a6bbc87f9e9ffb46a1801dfb983e7534825ed56b #12482 Ref: https://github.com/curl/curl/pull/12482#issuecomment-1873017261 Closes #12615 --- lib/asyn-thread.c | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/lib/asyn-thread.c b/lib/asyn-thread.c index 8646d72e939..d4d382add9f 100644 --- a/lib/asyn-thread.c +++ b/lib/asyn-thread.c @@ -302,8 +302,15 @@ query_complete(DWORD err, DWORD bytes, LPWSAOVERLAPPED overlapped) struct Curl_addrinfo *ca; struct Curl_addrinfo *cafirst = NULL; struct Curl_addrinfo *calast = NULL; +#ifdef __clang__ +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wcast-align" +#endif struct thread_sync_data *tsd = CONTAINING_RECORD(overlapped, struct thread_sync_data, w8.overlapped); +#ifdef __clang__ +#pragma clang diagnostic pop +#endif struct thread_data *td = tsd->td; const ADDRINFOEXW_ *res = tsd->w8.res; int error = (int)err; From aff26089e837f0ed524cb7b29ad5faf732316776 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 1 Jan 2024 23:31:47 +0000 Subject: [PATCH 106/509] schannel: fix `-Warith-conversion` gcc 13 warning ``` lib/vtls/schannel.c:1201:22: warning: conversion to 'unsigned int' from 'int' may change the sign of the result [-Warith-conversion] 1201 | *extension_len = *list_len + | ^ ``` Closes #12616 --- lib/vtls/schannel.c | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/vtls/schannel.c b/lib/vtls/schannel.c index 455269a3c4a..45c3373713c 100644 --- a/lib/vtls/schannel.c +++ b/lib/vtls/schannel.c @@ -1198,9 +1198,8 @@ schannel_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) cur += proto.len; *list_len = curlx_uitous(cur - list_start_index); - *extension_len = *list_len + - (unsigned short)sizeof(unsigned int) + - (unsigned short)sizeof(unsigned short); + *extension_len = (unsigned int)(*list_len + + sizeof(unsigned int) + sizeof(unsigned short)); InitSecBuffer(&inbuf, SECBUFFER_APPLICATION_PROTOCOLS, alpn_buffer, cur); InitSecBufferDesc(&inbuf_desc, &inbuf, 1); From 7d103f00430dffedc86db49fdae3f6044f9eca2b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Jan 2024 09:05:19 +0100 Subject: [PATCH 107/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 50 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 10 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 379be612ae7..732b54e8279 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,13 +4,14 @@ curl and libcurl 8.6.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3056 + Contributors: 3058 This release includes the following changes: + o add CURLE_TOO_LARGE [48] + o add CURLINFO_QUEUE_TIME_T [76] + o add CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add [39] o asyn-thread: use GetAddrInfoExW on >= Windows 8 [55] - o curl.h: add CURLE_TOO_LARGE [48] - o CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add [39] o runtests: support -gl. Like -g but for lldb. [47] This release includes the following bugfixes: @@ -29,9 +30,13 @@ This release includes the following bugfixes: o cmake: fix typo [5] o cmake: prefill/cache `HAVE_STRUCT_SOCKADDR_STORAGE` [45] o cmdline-docs: use .IP consistently [13] + o cmdline-opts: update availability for the *-ca-native options [66] o cmdline/gen: fix the sorting of the man page options [33] + o configure: fix no default int compile error in ipv6 detection [69] o cookie: avoid fopen with empty file name [24] o curl: show ipfs and ipns as supported "protocols" [15] + o CURLINFO_REFERER.3: clarify that it is the *request* header [70] + o CURLOPT_AUTOREFERER.3: mention CURLINFO_REFERER o CURLOPT_POSTFIELDS.3: fix incorrect C string escape in example [27] o CURLOPT_SSH_*_KEYFILE: clarify [57] o dist: add tests/errorcodes.pl to the tarball [6] @@ -39,6 +44,7 @@ This release includes the following bugfixes: o doh: remove unused local variable [34] o ftp: handle the PORT parsing without allocation [44] o gnutls: fix build with --disable-verbose [3] + o haproxy-clientip.d: document the arg [68] o hostip: return error immediately when Curl_ip2addr() fails [19] o http2: improved on_stream_close/data_done handling [49] o http: fix off-by-one error in request method length check [14] @@ -53,19 +59,28 @@ This release includes the following bugfixes: o mbedtls: free the entropy when threaded [46] o mprintf: overhaul and bugfixes [52] o ngtcp2: put h3 at the front of alpn [58] + o openldap: fix an LDAP crash [75] + o openldap: fix STARTTLS [67] o openssl: re-match LibreSSL deinit with init [17] + o quiche: return CURLE_HTTP3 on send to invalid stream [65] o readwrite_data: loop less [21] o Revert "urldata: move async resolver state from easy handle to connectdata" [16] + o runtests: for mode="text" on , fix newlines on both parts [64] + o schannel: fix `-Warith-conversion` gcc 13 warning [28] o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] o sendf: fix compiler warning with CURL_DISABLE_HEADERS_API [38] o ssh: fix namespace of two local macros [51] o strerror: repair get_winsock_error() [56] o system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers [9] + o system_win32: fix a function pointer assignment warning [71] o tests/server: delete workaround for old-mingw [25] o tests: respect $TMPDIR when creating unix domain sockets [50] o tool_getparam: do not try to expand without an argument [59] + o tool_listhelp: regenerate after recent .d updates [61] o transfer: fix upload rate limiting, add test cases [37] o url: for disabled protocols, mention if found in redirect [7] + o verify-examples.pl: fail verification on unescaped backslash [72] + o vtls: fix missing multissl version info [73] o vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY [41] o windows: delete redundant headers [43] o windows: simplify detecting and using system headers [10] @@ -83,15 +98,16 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - Baruch Siach, Ben, Boris Verkhovskiy, Cajus Pollmeier, calvin2021y on github, - Chara White, Chris Sauer, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, - Dmitry Karpov, Geeknik Labs, Hans-Christian Egtvedt, Haydar Alaidrus, - iAroc on github, ivanfywang, Karthikdasari0423 on github, Mark Sinkovics, - Mauricio Scheffer, Michał Antoniak, Mike Hommey, Pavel Pavlov, Ray Satiro, - RevaliQaQ on github, Stefan Eissing, Tatsuhiko Miyagawa, Theo, + annalee, Baruch Siach, Ben, Boris Verkhovskiy, Cajus Pollmeier, + calvin2021y on github, Chara White, Chris Sauer, Dan Fandrich, + Daniel Gustafsson, Daniel Stenberg, Dmitry Karpov, Geeknik Labs, + Hans-Christian Egtvedt, Haydar Alaidrus, iAroc on github, ivanfywang, + Karthikdasari0423 on github, Marcel Raad, Mark Sinkovics, Mauricio Scheffer, + Michał Antoniak, Mike Hommey, Ozan Cansel, Patrick Monnerat, Pavel Pavlov, + Ray Satiro, RevaliQaQ on github, Stefan Eissing, Tatsuhiko Miyagawa, Theo, Viktor Szakats, Xi Ruoyao, Yedaya Katsman, Yifei Kong, YX Hao, zengwei, zengwei2000 - (34 contributors) + (38 contributors) References to bug reports and discussions on issues: @@ -122,6 +138,7 @@ References to bug reports and discussions on issues: [25] = https://curl.se/bug/?i=12510 [26] = https://curl.se/bug/?i=12557 [27] = https://curl.se/bug/?i=12588 + [28] = https://curl.se/bug/?i=12616 [29] = https://curl.se/bug/?i=12550 [30] = https://curl.se/bug/?i=12499 [31] = https://curl.se/bug/?i=12503 @@ -153,3 +170,16 @@ References to bug reports and discussions on issues: [57] = https://curl.se/bug/?i=12554 [58] = https://curl.se/bug/?i=12576 [59] = https://curl.se/bug/?i=12565 + [61] = https://curl.se/bug/?i=12612 + [64] = https://curl.se/bug/?i=12612 + [65] = https://curl.se/bug/?i=12590 + [66] = https://curl.se/bug/?i=12613 + [67] = https://curl.se/bug/?i=12610 + [68] = https://curl.se/bug/?i=12611 + [69] = https://curl.se/bug/?i=12607 + [70] = https://curl.se/bug/?i=12605 + [71] = https://curl.se/bug/?i=12581 + [72] = https://curl.se/bug/?i=12589 + [73] = https://curl.se/bug/?i=12599 + [75] = https://curl.se/bug/?i=12593 + [76] = https://curl.se/bug/?i=12368 From 1d8e8c9ad1ff3351386422535f4c066db6a9ea88 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Jan 2024 14:16:43 +0100 Subject: [PATCH 108/509] test1254: fix typo in name plus shorten it --- tests/data/test1254 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/data/test1254 b/tests/data/test1254 index a39cbd26e05..07e77ed2a2e 100644 --- a/tests/data/test1254 +++ b/tests/data/test1254 @@ -27,7 +27,7 @@ foo http -Under condition using --proxy, override NO_PROXY by --nproxy and access target URL through proxy +override NO_PROXY by --noproxy and access target URL through proxy NO_PROXY=example.com From 941b56d790dc8f056e1ae31c9a7d17e7b2af066a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Jan 2024 13:32:18 +0100 Subject: [PATCH 109/509] tool: prepend output_dir in header callback When Content-Disposition parsing is used and an output dir is prepended, make sure to store that new file name correctly so that it can be used for setting the file timestamp when --remote-time is used. Extended test 3012 to verify. Co-Authored-by: Jay Satiro Reported-by: hgdagon on github Fixes #12614 Closes #12617 --- src/tool_cb_hdr.c | 10 +++++++++- src/tool_cb_wrt.c | 14 -------------- tests/data/test3012 | 5 +++-- 3 files changed, 12 insertions(+), 17 deletions(-) diff --git a/src/tool_cb_hdr.c b/src/tool_cb_hdr.c index 198a8d050cd..30ee3b09c95 100644 --- a/src/tool_cb_hdr.c +++ b/src/tool_cb_hdr.c @@ -178,10 +178,18 @@ size_t tool_header_cb(char *ptr, size_t size, size_t nmemb, void *userdata) return CURL_WRITEFUNC_ERROR; } + if(per->config->output_dir) { + outs->filename = aprintf("%s/%s", per->config->output_dir, filename); + free(filename); + if(!outs->filename) + return CURL_WRITEFUNC_ERROR; + } + else + outs->filename = filename; + outs->is_cd_filename = TRUE; outs->s_isreg = TRUE; outs->fopened = FALSE; - outs->filename = filename; outs->alloc_filename = TRUE; hdrcbdata->honor_cd_filename = FALSE; /* done now! */ if(!tool_create_output_file(outs, per->config)) diff --git a/src/tool_cb_wrt.c b/src/tool_cb_wrt.c index 98063c39c2a..143cba255b9 100644 --- a/src/tool_cb_wrt.c +++ b/src/tool_cb_wrt.c @@ -57,7 +57,6 @@ bool tool_create_output_file(struct OutStruct *outs, struct GlobalConfig *global; FILE *file = NULL; char *fname = outs->filename; - char *aname = NULL; DEBUGASSERT(outs); DEBUGASSERT(config); global = config->global; @@ -66,15 +65,6 @@ bool tool_create_output_file(struct OutStruct *outs, return FALSE; } - if(config->output_dir && outs->is_cd_filename) { - aname = aprintf("%s/%s", config->output_dir, fname); - if(!aname) { - errorf(global, "out of memory"); - return FALSE; - } - fname = aname; - } - if(config->file_clobber_mode == CLOBBER_ALWAYS || (config->file_clobber_mode == CLOBBER_DEFAULT && !outs->is_cd_filename)) { @@ -94,14 +84,12 @@ bool tool_create_output_file(struct OutStruct *outs, char *newname; /* Guard against wraparound in new filename */ if(newlen < len) { - free(aname); errorf(global, "overflow in filename generation"); return FALSE; } newname = malloc(newlen); if(!newname) { errorf(global, "out of memory"); - free(aname); return FALSE; } memcpy(newname, fname, len); @@ -135,10 +123,8 @@ bool tool_create_output_file(struct OutStruct *outs, if(!file) { warnf(global, "Failed to open the file %s: %s", fname, strerror(errno)); - free(aname); return FALSE; } - free(aname); outs->s_isreg = TRUE; outs->fopened = TRUE; outs->stream = file; diff --git a/tests/data/test3012 b/tests/data/test3012 index 2bd329455c4..a9c95058743 100644 --- a/tests/data/test3012 +++ b/tests/data/test3012 @@ -4,6 +4,7 @@ -O -J --output-dir +--remote-time # @@ -36,10 +37,10 @@ http http ---output-dir with -J +--output-dir with -J and -R -http://%HOSTIP:%HTTPPORT/this/is/the/%TESTNUMBER -OJ --output-dir %PWD/%LOGDIR +http://%HOSTIP:%HTTPPORT/this/is/the/%TESTNUMBER -OJR --output-dir %PWD/%LOGDIR From 8558647613ab4d25cc77e52ebbd2454d2225b1cc Mon Sep 17 00:00:00 2001 From: Gisle Vanem Date: Tue, 2 Jan 2024 17:02:13 +0100 Subject: [PATCH 110/509] content_encoding: change return code to typedef'ed enum ... to work around a clang ubsan warning. Fixes #12618 Closes #12622 --- lib/content_encoding.c | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/lib/content_encoding.c b/lib/content_encoding.c index 4167d4d684d..de75dd68670 100644 --- a/lib/content_encoding.c +++ b/lib/content_encoding.c @@ -365,11 +365,14 @@ static CURLcode gzip_do_init(struct Curl_easy *data, #ifdef OLD_ZLIB_SUPPORT /* Skip over the gzip header */ -static enum { +typedef enum { GZIP_OK, GZIP_BAD, GZIP_UNDERFLOW -} check_gzip_header(unsigned char const *data, ssize_t len, ssize_t *headerlen) +} gzip_status; + +static gzip_status check_gzip_header(unsigned char const *data, ssize_t len, + ssize_t *headerlen) { int method, flags; const ssize_t totallen = len; From bf7cd837a68452bef11d9b1a783f43d4128c4ad4 Mon Sep 17 00:00:00 2001 From: andy5995 Date: Tue, 2 Jan 2024 12:41:58 -0600 Subject: [PATCH 111/509] CI: Add dependabot.yml This will cause dependabot to open a PR when various actions are updated, provided that the action maintainer has issued a release. Closes #12623 --- .github/dependabot.yml | 6 ++++++ .reuse/dep5 | 4 ++++ 2 files changed, 10 insertions(+) create mode 100644 .github/dependabot.yml 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/.reuse/dep5 b/.reuse/dep5 index 3a7a672a2b6..60c9a012dd2 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -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 From eeda18b1d2511cb9716066e5b29d81556a4f1355 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Jan 2024 16:35:50 +0100 Subject: [PATCH 112/509] setopt: clear mimepost when formp is freed A precaution to avoid a possibly dangling pointer left behind. Reported-by: Thomas Ferguson Fixes #12608 Closes #12621 --- lib/setopt.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/setopt.c b/lib/setopt.c index 460cb32e74a..e13432334d9 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -681,6 +681,7 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) data->set.opt_no_body = FALSE; /* this is implied */ Curl_mime_cleanpart(data->state.formp); Curl_safefree(data->state.formp); + data->state.mimepost = NULL; break; #endif @@ -988,6 +989,7 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) #ifndef CURL_DISABLE_FORM_API Curl_mime_cleanpart(data->state.formp); Curl_safefree(data->state.formp); + data->state.mimepost = NULL; #endif } break; From f712af2891210fa1b22acb9a5fef734a6b73511e Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 3 Jan 2024 09:37:55 +0100 Subject: [PATCH 113/509] http3/quiche: fix result code on a stream reset - fixes pytest failures in test 07_22 - aligns CURLcode values on stream reset with ngtcp2 Closes #12629 --- lib/vquic/curl_quiche.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/vquic/curl_quiche.c b/lib/vquic/curl_quiche.c index 227adbdd9a6..33c2621dc8b 100644 --- a/lib/vquic/curl_quiche.c +++ b/lib/vquic/curl_quiche.c @@ -836,7 +836,7 @@ static ssize_t recv_closed_stream(struct Curl_cfilter *cf, if(stream->reset) { failf(data, "HTTP/3 stream %" PRId64 " reset by server", stream->id); - *err = stream->resp_got_header? CURLE_PARTIAL_FILE : CURLE_RECV_ERROR; + *err = stream->resp_got_header? CURLE_PARTIAL_FILE : CURLE_HTTP3; CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_recv, was reset -> %d", stream->id, *err); } @@ -846,7 +846,7 @@ static ssize_t recv_closed_stream(struct Curl_cfilter *cf, " all response header fields, treated as error", stream->id); /* *err = CURLE_PARTIAL_FILE; */ - *err = CURLE_RECV_ERROR; + *err = CURLE_HTTP3; CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_recv, closed incomplete" " -> %d", stream->id, *err); } From 03fcddba2242a16206b17e8a8be5ad503c0f29a8 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 2 Jan 2024 22:32:38 +0000 Subject: [PATCH 114/509] build(deps): bump actions/download-artifact from 3 to 4 Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 3 to 4. - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](https://github.com/actions/download-artifact/compare/v3...v4) --- updated-dependencies: - dependency-name: actions/download-artifact dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Closes #12626 --- .github/workflows/distcheck.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/distcheck.yml b/.github/workflows/distcheck.yml index 6c050f51740..d63cd46846c 100644 --- a/.github/workflows/distcheck.yml +++ b/.github/workflows/distcheck.yml @@ -63,7 +63,7 @@ jobs: timeout-minutes: 30 needs: maketgz-and-verify-in-tree steps: - - uses: actions/download-artifact@v3 + - uses: actions/download-artifact@v4 with: name: 'release-tgz' @@ -86,7 +86,7 @@ jobs: timeout-minutes: 30 needs: maketgz-and-verify-in-tree steps: - - uses: actions/download-artifact@v3 + - uses: actions/download-artifact@v4 with: name: 'release-tgz' @@ -107,7 +107,7 @@ jobs: timeout-minutes: 30 needs: maketgz-and-verify-in-tree steps: - - uses: actions/download-artifact@v3 + - uses: actions/download-artifact@v4 with: name: 'release-tgz' From 1f138afcc2c4a062a2a17b48d8f5d9e97f2a5c2c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 2 Jan 2024 22:32:42 +0000 Subject: [PATCH 115/509] build(deps): bump actions/upload-artifact from 3 to 4 Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 3 to 4. - [Release notes](https://github.com/actions/upload-artifact/releases) - [Commits](https://github.com/actions/upload-artifact/compare/v3...v4) --- updated-dependencies: - dependency-name: actions/upload-artifact dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Closes #12627 --- .github/workflows/distcheck.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/distcheck.yml b/.github/workflows/distcheck.yml index d63cd46846c..6daa7a242ec 100644 --- a/.github/workflows/distcheck.yml +++ b/.github/workflows/distcheck.yml @@ -39,7 +39,7 @@ jobs: - run: ./maketgz 99.98.97 name: 'maketgz' - - uses: actions/upload-artifact@v3 + - uses: actions/upload-artifact@v4 with: name: 'release-tgz' path: 'curl-99.98.97.tar.gz' From 943ec10b6e96625fc5e45c8431a741593c3b2193 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 2 Jan 2024 22:32:31 +0000 Subject: [PATCH 116/509] build(deps): bump actions/checkout from 3 to 4 Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/v3...v4) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Closes #12624 --- .github/workflows/codespell.yml | 2 +- .github/workflows/man-examples.yml | 2 +- .github/workflows/synopsis.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index f3cc4cd7280..2b095dae75a 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -25,7 +25,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: install run: | diff --git a/.github/workflows/man-examples.yml b/.github/workflows/man-examples.yml index 640e3716cc2..249ebfe2f9d 100644 --- a/.github/workflows/man-examples.yml +++ b/.github/workflows/man-examples.yml @@ -26,7 +26,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: verify examples run: ./.github/scripts/verify-examples.pl docs/libcurl/curl*.3 docs/libcurl/opts/*.3 diff --git a/.github/workflows/synopsis.yml b/.github/workflows/synopsis.yml index 98bdd476a19..0938f4bfc98 100644 --- a/.github/workflows/synopsis.yml +++ b/.github/workflows/synopsis.yml @@ -22,7 +22,7 @@ jobs: 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 From f59223f500ebeee8ef6d882242fd4418f9e96c52 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 2 Jan 2024 22:32:35 +0000 Subject: [PATCH 117/509] build(deps): bump github/codeql-action from 2 to 3 Bumps [github/codeql-action](https://github.com/github/codeql-action) from 2 to 3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v2...v3) --- updated-dependencies: - dependency-name: github/codeql-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Closes #12625 --- .github/workflows/codeql-analysis.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 40d6545882d..f98e4da4271 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -55,7 +55,7 @@ jobs: # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL - uses: github/codeql-action/init@v2 + uses: github/codeql-action/init@v3 with: languages: cpp queries: security-extended @@ -63,7 +63,7 @@ jobs: # 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 + uses: github/codeql-action/autobuild@v3 # ℹ️ Command-line programs to run using the OS shell. # 📚 https://git.io/JvXDl @@ -77,4 +77,4 @@ jobs: # make release - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v2 + uses: github/codeql-action/analyze@v3 From 07bcae89d5d0090f1d11866d5f9c98c3720a2838 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Jan 2024 14:17:10 +0100 Subject: [PATCH 118/509] tool: make parser reject blank arguments if not supported Already in the getstr() function that clones the input argument. Closes #12620 --- src/tool_getparam.c | 308 ++++++++++++++++++++++---------------------- src/tool_getparam.h | 1 + src/tool_helpers.c | 2 + src/tool_paramhlp.c | 2 + 4 files changed, 157 insertions(+), 156 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 79110eb7d2a..7aa40bbe288 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -51,19 +51,25 @@ # define USE_WATT32 #endif -#define GetStr(str,val) do { \ - if(*(str)) { \ - free(*(str)); \ - *(str) = NULL; \ - } \ - if((val)) { \ - *(str) = strdup((val)); \ - if(!(*(str))) { \ - err = PARAM_NO_MEM; \ - goto error; \ - } \ - } \ - } while(0) +#define ALLOW_BLANK TRUE +#define DENY_BLANK FALSE + +static ParameterError getstr(char **str, const char *val, bool allowblank) +{ + if(*str) { + free(*str); + *str = NULL; + } + if(val) { + if(!allowblank && !val[0]) + return PARAM_BLANK_STRING; + + *str = strdup(val); + if(!*str) + return PARAM_NO_MEM; + } + return PARAM_OK; +} struct LongShort { const char *letter; /* short name option */ @@ -559,7 +565,7 @@ static ParameterError GetSizeParameter(struct GlobalConfig *global, #ifdef HAVE_WRITABLE_ARGV static void cleanarg(argv_item_t str) { - /* now that GetStr has copied the contents of nextarg, wipe the next + /* now that getstr has copied the contents of nextarg, wipe the next * argument out so that the username:password isn't displayed in the * system process list */ if(str) { @@ -624,7 +630,9 @@ static ParameterError data_urlencode(struct GlobalConfig *global, return err; } else { - GetStr(&postdata, p); + err = getstr(&postdata, p, ALLOW_BLANK); + if(err) + goto error; if(postdata) size = strlen(postdata); } @@ -759,6 +767,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ bool toggle = TRUE; /* how to switch boolean options, on or off. Controlled by using --OPTION or --no-OPTION */ bool nextalloc = FALSE; /* if nextarg is allocated */ + struct getout *url; static const char *redir_protos[] = { "http", "https", @@ -907,48 +916,48 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case '*': /* options without a short option */ switch(subletter) { case '4': /* --dns-ipv4-addr */ - if(!curlinfo->ares_num) { /* c-ares is needed for this */ + if(!curlinfo->ares_num) /* c-ares is needed for this */ err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - /* addr in dot notation */ - GetStr(&config->dns_ipv4_addr, nextarg); + else + /* addr in dot notation */ + err = getstr(&config->dns_ipv4_addr, nextarg, DENY_BLANK); break; case '6': /* --dns-ipv6-addr */ - if(!curlinfo->ares_num) { /* c-ares is needed for this */ + if(!curlinfo->ares_num) /* c-ares is needed for this */ err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - /* addr in dot notation */ - GetStr(&config->dns_ipv6_addr, nextarg); + else + /* addr in dot notation */ + err = getstr(&config->dns_ipv6_addr, nextarg, DENY_BLANK); break; case 'a': /* random-file */ break; case 'b': /* egd-file */ break; case 'B': /* OAuth 2.0 bearer token */ - GetStr(&config->oauth_bearer, nextarg); - cleanarg(clearthis); - config->authtype |= CURLAUTH_BEARER; + err = getstr(&config->oauth_bearer, nextarg, DENY_BLANK); + if(!err) { + cleanarg(clearthis); + config->authtype |= CURLAUTH_BEARER; + } break; case 'c': /* connect-timeout */ err = secs2ms(&config->connecttimeout_ms, nextarg); break; case 'C': /* doh-url */ - GetStr(&config->doh_url, nextarg); - if(config->doh_url && !config->doh_url[0]) - /* if given a blank string, we make it NULL again */ + err = getstr(&config->doh_url, nextarg, ALLOW_BLANK); + if(!err && config->doh_url && !config->doh_url[0]) + /* if given a blank string, make it NULL again */ Curl_safefree(config->doh_url); break; case 'd': /* ciphers */ - GetStr(&config->cipher_list, nextarg); + err = getstr(&config->cipher_list, nextarg, DENY_BLANK); break; case 'D': /* --dns-interface */ if(!curlinfo->ares_num) /* c-ares is needed for this */ err = PARAM_LIBCURL_DOESNT_SUPPORT; else /* interface name */ - GetStr(&config->dns_interface, nextarg); + err = getstr(&config->dns_interface, nextarg, DENY_BLANK); break; case 'e': /* --disable-epsv */ config->disable_epsv = toggle; @@ -964,23 +973,27 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; else /* IP addrs of DNS servers */ - GetStr(&config->dns_servers, nextarg); + err = getstr(&config->dns_servers, nextarg, DENY_BLANK); break; case 'g': /* --trace */ - GetStr(&global->trace_dump, nextarg); - if(global->tracetype && (global->tracetype != TRACE_BIN)) - warnf(global, "--trace overrides an earlier trace/verbose option"); - global->tracetype = TRACE_BIN; + err = getstr(&global->trace_dump, nextarg, DENY_BLANK); + if(!err) { + if(global->tracetype && (global->tracetype != TRACE_BIN)) + warnf(global, "--trace overrides an earlier trace/verbose option"); + global->tracetype = TRACE_BIN; + } break; case 'G': /* --npn */ warnf(global, "--npn is no longer supported"); break; case 'h': /* --trace-ascii */ - GetStr(&global->trace_dump, nextarg); - if(global->tracetype && (global->tracetype != TRACE_ASCII)) - warnf(global, - "--trace-ascii overrides an earlier trace/verbose option"); - global->tracetype = TRACE_ASCII; + err = getstr(&global->trace_dump, nextarg, DENY_BLANK); + if(!err) { + if(global->tracetype && (global->tracetype != TRACE_ASCII)) + warnf(global, + "--trace-ascii overrides an earlier trace/verbose option"); + global->tracetype = TRACE_ASCII; + } break; case 'H': /* --alpn */ config->noalpn = (!toggle)?TRUE:FALSE; @@ -1146,7 +1159,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'S': /* ipfs gateway url */ - GetStr(&config->ipfs_gateway, nextarg); + err = getstr(&config->ipfs_gateway, nextarg, DENY_BLANK); break; case 't': /* --proxy-ntlm */ @@ -1164,7 +1177,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case 'V': /* --aws-sigv4 */ config->authtype |= CURLAUTH_AWS_SIGV4; - GetStr(&config->aws_sigv4, nextarg); + err = getstr(&config->aws_sigv4, nextarg, DENY_BLANK); break; case 'v': /* --stderr */ @@ -1172,7 +1185,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'w': /* --interface */ /* interface */ - GetStr(&config->iface, nextarg); + err = getstr(&config->iface, nextarg, DENY_BLANK); break; case 'x': /* --krb */ /* kerberos level string */ @@ -1180,13 +1193,13 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } - GetStr(&config->krblevel, nextarg); + err = getstr(&config->krblevel, nextarg, DENY_BLANK); break; case 'X': /* --haproxy-protocol */ config->haproxy_protocol = toggle; break; case 'P': /* --haproxy-clientip */ - GetStr(&config->haproxy_clientip, nextarg); + err = getstr(&config->haproxy_clientip, nextarg, DENY_BLANK); break; case 'y': /* --max-filesize */ { @@ -1208,9 +1221,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->xattr = toggle; break; case '@': /* the URL! */ - { - struct getout *url; - if(!config->url_get) config->url_get = config->url_list; @@ -1236,10 +1246,9 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } /* fill in the URL */ - GetStr(&url->url, nextarg); + err = getstr(&url->url, nextarg, DENY_BLANK); url->flags |= GETOUT_URL; } - } break; case '$': /* more options without a short option */ switch(subletter) { @@ -1258,20 +1267,20 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'c': /* --socks5 specifies a socks5 proxy to use, and resolves the name locally and passes on the resolved address */ - GetStr(&config->proxy, nextarg); + err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_SOCKS5; break; case 't': /* --socks4 specifies a socks4 proxy to use */ - GetStr(&config->proxy, nextarg); + err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_SOCKS4; break; case 'T': /* --socks4a specifies a socks4a proxy to use */ - GetStr(&config->proxy, nextarg); + err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_SOCKS4A; break; case '2': /* --socks5-hostname specifies a socks5 proxy and enables name resolving with the proxy */ - GetStr(&config->proxy, nextarg); + err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_SOCKS5_HOSTNAME; break; case 'd': /* --tcp-nodelay option */ @@ -1314,7 +1323,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'm': /* --ftp-account */ - GetStr(&config->ftp_account, nextarg); + err = getstr(&config->ftp_account, nextarg, DENY_BLANK); break; case 'n': /* --proxy-anyauth */ config->proxyanyauth = toggle; @@ -1366,7 +1375,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; } case 'u': /* --ftp-alternative-to-user */ - GetStr(&config->ftp_alternative_to_user, nextarg); + err = getstr(&config->ftp_alternative_to_user, nextarg, DENY_BLANK); break; case 'v': /* --ssl-reqd */ if(toggle && !feature_ssl) { @@ -1399,11 +1408,10 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ warnf(global, "--libcurl option was disabled at build-time"); err = PARAM_OPTION_UNKNOWN; - break; #else - GetStr(&global->libcurl, nextarg); - break; + err = getstr(&global->libcurl, nextarg, DENY_BLANK); #endif + break; case '#': /* --raw */ config->raw = toggle; break; @@ -1424,21 +1432,21 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case '5': /* --noproxy */ /* This specifies the noproxy list */ - GetStr(&config->noproxy, nextarg); + err = getstr(&config->noproxy, nextarg, ALLOW_BLANK); break; case '7': /* --socks5-gssapi-nec */ config->socks5_gssapi_nec = toggle; break; case '8': /* --proxy1.0 */ /* http 1.0 proxy */ - GetStr(&config->proxy, nextarg); + err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_HTTP_1_0; break; case '9': /* --tftp-blksize */ err = str2unum(&config->tftp_blksize, nextarg); break; case 'A': /* --mail-from */ - GetStr(&config->mail_from, nextarg); + err = getstr(&config->mail_from, nextarg, DENY_BLANK); break; case 'B': /* --mail-rcpt */ /* append receiver to a list */ @@ -1466,14 +1474,14 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->gssapi_delegation = delegation(config, nextarg); break; case 'H': /* --mail-auth */ - GetStr(&config->mail_auth, nextarg); + err = getstr(&config->mail_auth, nextarg, DENY_BLANK); break; case 'J': /* --metalink */ errorf(global, "--metalink is disabled"); err = PARAM_BAD_USE; break; case '6': /* --sasl-authzid */ - GetStr(&config->sasl_authzid, nextarg); + err = getstr(&config->sasl_authzid, nextarg, DENY_BLANK); break; case 'K': /* --sasl-ir */ config->sasl_ir = toggle; @@ -1487,20 +1495,21 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'M': /* --unix-socket */ config->abstract_unix_socket = FALSE; - GetStr(&config->unix_socket_path, nextarg); + err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); break; case 'N': /* --path-as-is */ config->path_as_is = toggle; break; case 'O': /* --proxy-service-name */ - GetStr(&config->proxy_service_name, nextarg); + err = getstr(&config->proxy_service_name, nextarg, DENY_BLANK); break; case 'P': /* --service-name */ - GetStr(&config->service_name, nextarg); + err = getstr(&config->service_name, nextarg, DENY_BLANK); break; case 'Q': /* --proto-default */ - GetStr(&config->proto_default, nextarg); - err = check_protocol(config->proto_default); + err = getstr(&config->proto_default, nextarg, DENY_BLANK); + if(!err) + err = check_protocol(config->proto_default); break; case 'R': /* --expect100-timeout */ err = secs2ms(&config->expect100timeout_ms, nextarg); @@ -1513,7 +1522,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'W': /* --abstract-unix-socket */ config->abstract_unix_socket = TRUE; - GetStr(&config->unix_socket_path, nextarg); + err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); break; case 'X': /* --tls-max */ err = str2tls_max(&config->ssl_version_max, nextarg); @@ -1632,10 +1641,10 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->ssl_version = CURL_SSLVERSION_TLSv1_3; break; case 'A': /* --tls13-ciphers */ - GetStr(&config->cipher13_list, nextarg); + err = getstr(&config->cipher13_list, nextarg, DENY_BLANK); break; case 'B': /* --proxy-tls13-ciphers */ - GetStr(&config->proxy_cipher13_list, nextarg); + err = getstr(&config->proxy_cipher13_list, nextarg, DENY_BLANK); break; } break; @@ -1661,7 +1670,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'A': /* This specifies the User-Agent name */ - GetStr(&config->useragent, nextarg); + err = getstr(&config->useragent, nextarg, ALLOW_BLANK); break; case 'b': switch(subletter) { @@ -1669,13 +1678,13 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ if(!feature_altsvc) err = PARAM_LIBCURL_DOESNT_SUPPORT; else - GetStr(&config->altsvc, nextarg); + err = getstr(&config->altsvc, nextarg, ALLOW_BLANK); break; case 'b': /* --hsts */ if(!feature_hsts) err = PARAM_LIBCURL_DOESNT_SUPPORT; else - GetStr(&config->hsts, nextarg); + err = getstr(&config->hsts, nextarg, ALLOW_BLANK); break; default: /* --cookie string coming up: */ if(nextarg[0] == '@') { @@ -1696,7 +1705,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'c': /* get the file name to dump all cookies in */ - GetStr(&config->cookiejar, nextarg); + err = getstr(&config->cookiejar, nextarg, DENY_BLANK); break; case 'C': /* This makes us continue an ftp transfer at given position */ @@ -1806,7 +1815,9 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } } else { - GetStr(&postdata, nextarg); + err = getstr(&postdata, nextarg, ALLOW_BLANK); + if(err) + break; if(postdata) size = strlen(postdata); } @@ -1860,7 +1871,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'D': /* dump-header to given file name */ - GetStr(&config->headerfile, nextarg); + err = getstr(&config->headerfile, nextarg, DENY_BLANK); break; case 'e': { @@ -1874,7 +1885,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ else config->autoreferer = FALSE; ptr = *nextarg ? nextarg : NULL; - GetStr(&config->referer, ptr); + err = getstr(&config->referer, ptr, ALLOW_BLANK); } break; case 'E': @@ -1884,7 +1895,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ GetFileAndPassword(nextarg, &config->cert, &config->key_passwd); break; case 'a': /* --cacert CA info PEM file */ - GetStr(&config->cacert, nextarg); + err = getstr(&config->cacert, nextarg, DENY_BLANK); break; case 'G': /* --ca-native */ config->native_ca_store = toggle; @@ -1893,43 +1904,43 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->proxy_native_ca_store = toggle; break; case 'b': /* cert file type */ - GetStr(&config->cert_type, nextarg); + err = getstr(&config->cert_type, nextarg, DENY_BLANK); break; case 'c': /* private key file */ - GetStr(&config->key, nextarg); + err = getstr(&config->key, nextarg, DENY_BLANK); break; case 'd': /* private key file type */ - GetStr(&config->key_type, nextarg); + err = getstr(&config->key_type, nextarg, DENY_BLANK); break; case 'e': /* private key passphrase */ - GetStr(&config->key_passwd, nextarg); + err = getstr(&config->key_passwd, nextarg, DENY_BLANK); cleanarg(clearthis); break; case 'f': /* crypto engine */ - GetStr(&config->engine, nextarg); - if(config->engine && curl_strequal(config->engine, "list")) { + err = getstr(&config->engine, nextarg, DENY_BLANK); + if(!err && + config->engine && curl_strequal(config->engine, "list")) { err = PARAM_ENGINES_REQUESTED; - break; } break; case 'g': /* CA cert directory */ - GetStr(&config->capath, nextarg); + err = getstr(&config->capath, nextarg, DENY_BLANK); break; case 'h': /* --pubkey public key file */ - GetStr(&config->pubkey, nextarg); + err = getstr(&config->pubkey, nextarg, DENY_BLANK); break; case 'i': /* --hostpubmd5 md5 of the host public key */ - GetStr(&config->hostpubmd5, nextarg); - if(!config->hostpubmd5 || strlen(config->hostpubmd5) != 32) { - err = PARAM_BAD_USE; - break; + err = getstr(&config->hostpubmd5, nextarg, DENY_BLANK); + if(!err) { + if(!config->hostpubmd5 || strlen(config->hostpubmd5) != 32) + err = PARAM_BAD_USE; } break; case 'F': /* --hostpubsha256 sha256 of the host public key */ - GetStr(&config->hostpubsha256, nextarg); + err = getstr(&config->hostpubsha256, nextarg, DENY_BLANK); break; case 'j': /* CRL file */ - GetStr(&config->crlfile, nextarg); + err = getstr(&config->crlfile, nextarg, DENY_BLANK); break; case 'k': /* TLS username */ if(!feature_tls_srp) { @@ -1937,7 +1948,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } - GetStr(&config->tls_username, nextarg); + err = getstr(&config->tls_username, nextarg, DENY_BLANK); cleanarg(clearthis); break; case 'l': /* TLS password */ @@ -1946,7 +1957,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } - GetStr(&config->tls_password, nextarg); + err = getstr(&config->tls_password, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; case 'm': /* TLS authentication type */ @@ -1954,11 +1965,9 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } - GetStr(&config->tls_authtype, nextarg); - if(!curl_strequal(config->tls_authtype, "SRP")) { + err = getstr(&config->tls_authtype, nextarg, DENY_BLANK); + if(!err && !curl_strequal(config->tls_authtype, "SRP")) err = PARAM_LIBCURL_DOESNT_SUPPORT; /* only support TLS-SRP */ - break; - } break; case 'n': /* no empty SSL fragments, --ssl-allow-beast */ if(feature_ssl) @@ -1976,11 +1985,11 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'p': /* Pinned public key DER file */ - GetStr(&config->pinnedpubkey, nextarg); + err = getstr(&config->pinnedpubkey, nextarg, DENY_BLANK); break; case 'P': /* proxy pinned public key */ - GetStr(&config->proxy_pinnedpubkey, nextarg); + err = getstr(&config->proxy_pinnedpubkey, nextarg, DENY_BLANK); break; case 'q': /* --cert-status */ @@ -2015,7 +2024,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } - GetStr(&config->proxy_tls_username, nextarg); + err = getstr(&config->proxy_tls_username, nextarg, ALLOW_BLANK); break; case 'v': /* TLS password for proxy */ @@ -2024,7 +2033,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } - GetStr(&config->proxy_tls_password, nextarg); + err = getstr(&config->proxy_tls_password, nextarg, DENY_BLANK); break; case 'w': /* TLS authentication type for proxy */ @@ -2032,11 +2041,9 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } - GetStr(&config->proxy_tls_authtype, nextarg); - if(!curl_strequal(config->proxy_tls_authtype, "SRP")) { + err = getstr(&config->proxy_tls_authtype, nextarg, DENY_BLANK); + if(!err && !curl_strequal(config->proxy_tls_authtype, "SRP")) err = PARAM_LIBCURL_DOESNT_SUPPORT; /* only support TLS-SRP */ - break; - } break; case 'x': /* certificate file for proxy */ @@ -2046,28 +2053,28 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'y': /* cert file type for proxy */ - GetStr(&config->proxy_cert_type, nextarg); + err = getstr(&config->proxy_cert_type, nextarg, DENY_BLANK); break; case 'z': /* private key file for proxy */ - GetStr(&config->proxy_key, nextarg); + err = getstr(&config->proxy_key, nextarg, ALLOW_BLANK); break; case '0': /* private key file type for proxy */ - GetStr(&config->proxy_key_type, nextarg); + err = getstr(&config->proxy_key_type, nextarg, DENY_BLANK); break; case '1': /* private key passphrase for proxy */ - GetStr(&config->proxy_key_passwd, nextarg); + err = getstr(&config->proxy_key_passwd, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; case '2': /* ciphers for proxy */ - GetStr(&config->proxy_cipher_list, nextarg); + err = getstr(&config->proxy_cipher_list, nextarg, DENY_BLANK); break; case '3': /* CRL file for proxy */ - GetStr(&config->proxy_crlfile, nextarg); + err = getstr(&config->proxy_crlfile, nextarg, DENY_BLANK); break; case '4': /* no empty SSL fragments for proxy */ @@ -2076,15 +2083,15 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case '5': /* --login-options */ - GetStr(&config->login_options, nextarg); + err = getstr(&config->login_options, nextarg, ALLOW_BLANK); break; case '6': /* CA info PEM file for proxy */ - GetStr(&config->proxy_cacert, nextarg); + err = getstr(&config->proxy_cacert, nextarg, DENY_BLANK); break; case '7': /* CA cert directory for proxy */ - GetStr(&config->proxy_capath, nextarg); + err = getstr(&config->proxy_capath, nextarg, DENY_BLANK); break; case '8': /* allow insecure SSL connects for proxy */ @@ -2113,15 +2120,15 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'C': - GetStr(&config->etag_save_file, nextarg); + err = getstr(&config->etag_save_file, nextarg, DENY_BLANK); break; case 'D': - GetStr(&config->etag_compare_file, nextarg); + err = getstr(&config->etag_compare_file, nextarg, DENY_BLANK); break; case 'E': - GetStr(&config->ssl_ec_curves, nextarg); + err = getstr(&config->ssl_ec_curves, nextarg, DENY_BLANK); break; default: /* unknown flag */ @@ -2181,7 +2188,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case 'G': /* HTTP GET */ if(subletter == 'a') { /* --request-target */ - GetStr(&config->request_target, nextarg); + err = getstr(&config->request_target, nextarg, DENY_BLANK); } else config->use_httpget = toggle; @@ -2310,7 +2317,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->netrc_opt = toggle; break; case 'e': /* netrc-file */ - GetStr(&config->netrc_file, nextarg); + err = getstr(&config->netrc_file, nextarg, DENY_BLANK); break; default: /* pick info from .netrc, if this is used for http, curl will @@ -2330,7 +2337,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; } else if(subletter == 'b') { /* --output-dir */ - GetStr(&config->output_dir, nextarg); + err = getstr(&config->output_dir, nextarg, DENY_BLANK); break; } else if(subletter == 'c') { /* --clobber / --no-clobber */ @@ -2340,8 +2347,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ FALLTHROUGH(); case 'o': /* --output */ /* output file */ - { - struct getout *url; if(!config->url_out) config->url_out = config->url_list; if(config->url_out) { @@ -2370,12 +2375,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ /* fill in the outfile */ if('o' == letter) { - if(!*nextarg) { - warnf(global, "output file name has no length"); - err = PARAM_BAD_USE; - break; - } - GetStr(&url->outfile, nextarg); + err = getstr(&url->outfile, nextarg, DENY_BLANK); url->flags &= ~GETOUT_USEREMOTE; /* switch off */ } else { @@ -2386,15 +2386,14 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ url->flags &= ~GETOUT_USEREMOTE; /* switch off */ } url->flags |= GETOUT_OUTFILE; - } - break; + break; case 'P': /* This makes the FTP sessions use PORT instead of PASV */ /* use or <192.168.10.10> style addresses. Anything except this will make us try to get the "default" address. NOTE: this is a changed behavior since the released 4.1! */ - GetStr(&config->ftpport, nextarg); + err = getstr(&config->ftpport, nextarg, DENY_BLANK); break; case 'p': /* proxy tunnel for non-http protocols */ @@ -2459,7 +2458,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } tmp_range++; } - GetStr(&config->range, nextarg); + err = getstr(&config->range, nextarg, DENY_BLANK); } break; case 'R': @@ -2478,8 +2477,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'T': /* we are uploading */ - { - struct getout *url; if(!config->url_ul) config->url_ul = config->url_list; if(config->url_ul) { @@ -2508,18 +2505,17 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ url->flags |= GETOUT_NOUPLOAD; else { /* "-" equals stdin, but keep the string around for now */ - GetStr(&url->infile, nextarg); + err = getstr(&url->infile, nextarg, DENY_BLANK); } - } - break; + break; case 'u': /* user:password */ - GetStr(&config->userpwd, nextarg); + err = getstr(&config->userpwd, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; case 'U': /* Proxy user:password */ - GetStr(&config->proxyuserpwd, nextarg); + err = getstr(&config->proxyuserpwd, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; case 'v': @@ -2527,14 +2523,14 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ /* the '%' thing here will cause the trace get sent to stderr */ Curl_safefree(global->trace_dump); global->trace_dump = strdup("%"); - if(!global->trace_dump) { + if(!global->trace_dump) err = PARAM_NO_MEM; - break; + else { + if(global->tracetype && (global->tracetype != TRACE_PLAIN)) + warnf(global, + "-v, --verbose overrides an earlier trace/verbose option"); + global->tracetype = TRACE_PLAIN; } - if(global->tracetype && (global->tracetype != TRACE_PLAIN)) - warnf(global, - "-v, --verbose overrides an earlier trace/verbose option"); - global->tracetype = TRACE_PLAIN; } else /* verbose is disabled here */ @@ -2578,16 +2574,16 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ warnf(global, "Failed to read %s", fname); } else - GetStr(&config->writeout, nextarg); + err = getstr(&config->writeout, nextarg, DENY_BLANK); break; case 'x': switch(subletter) { case 'a': /* --preproxy */ - GetStr(&config->preproxy, nextarg); + err = getstr(&config->preproxy, nextarg, DENY_BLANK); break; default: /* --proxy */ - GetStr(&config->proxy, nextarg); + err = getstr(&config->proxy, nextarg, ALLOW_BLANK); if(config->proxyver != CURLPROXY_HTTPS2) config->proxyver = CURLPROXY_HTTP; break; @@ -2595,7 +2591,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; case 'X': /* set custom request */ - GetStr(&config->customrequest, nextarg); + err = getstr(&config->customrequest, nextarg, DENY_BLANK); break; case 'y': /* low speed time */ diff --git a/src/tool_getparam.h b/src/tool_getparam.h index a8a9d459750..12a971d0277 100644 --- a/src/tool_getparam.h +++ b/src/tool_getparam.h @@ -49,6 +49,7 @@ typedef enum { PARAM_CONTDISP_RESUME_FROM, /* --continue-at and --remote-header-name */ PARAM_READ_ERROR, PARAM_EXPAND_ERROR, /* --expand problem */ + PARAM_BLANK_STRING, PARAM_LAST } ParameterError; diff --git a/src/tool_helpers.c b/src/tool_helpers.c index 854bf777a04..67924a26e8c 100644 --- a/src/tool_helpers.c +++ b/src/tool_helpers.c @@ -78,6 +78,8 @@ const char *param2text(int res) return "error encountered when reading a file"; case PARAM_EXPAND_ERROR: return "variable expansion failure"; + case PARAM_BLANK_STRING: + return "blank argument where content is expected"; default: return "unknown error"; } diff --git a/src/tool_paramhlp.c b/src/tool_paramhlp.c index 17018cf9fdd..a6b946edd67 100644 --- a/src/tool_paramhlp.c +++ b/src/tool_paramhlp.c @@ -134,6 +134,8 @@ static ParameterError getnum(long *val, const char *str, int base) if(str) { char *endptr = NULL; long num; + if(!str[0]) + return PARAM_BLANK_STRING; errno = 0; num = strtol(str, &endptr, base); if(errno == ERANGE) From 8e2d7b9fa4264b94bd1d9838c84d16e4cd33fbea Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 4 Jan 2024 10:06:17 +0100 Subject: [PATCH 119/509] http: adjust_pollset fix do not add a socket for POLLIN when the transfer does not want to send (for example is paused). Follow-up to 47f5b1a Reported-by: bubbleguuum on github Fixes #12632 Closes #12633 --- lib/cf-socket.c | 2 +- lib/http2.c | 4 ++-- lib/vquic/curl_ngtcp2.c | 7 ++++--- lib/vquic/curl_quiche.c | 2 +- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/lib/cf-socket.c b/lib/cf-socket.c index bd4f0d1e97e..c86aa7e7c2a 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -1243,7 +1243,7 @@ static void cf_socket_adjust_pollset(struct Curl_cfilter *cf, if(ctx->sock != CURL_SOCKET_BAD) { if(!cf->connected) Curl_pollset_set_out_only(data, ps, ctx->sock); - else + else if(CURL_WANT_RECV(data)) Curl_pollset_add_in(data, ps, ctx->sock); CURL_TRC_CF(data, cf, "adjust_pollset -> %d socks", ps->num); } diff --git a/lib/http2.c b/lib/http2.c index dcc24ea1023..b7a08607945 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -2341,8 +2341,8 @@ static void cf_h2_adjust_pollset(struct Curl_cfilter *cf, bool c_exhaust, s_exhaust; CF_DATA_SAVE(save, cf, data); - c_exhaust = !nghttp2_session_get_remote_window_size(ctx->h2); - s_exhaust = stream && stream->id >= 0 && + c_exhaust = want_send && !nghttp2_session_get_remote_window_size(ctx->h2); + s_exhaust = want_send && stream && stream->id >= 0 && !nghttp2_session_get_stream_remote_window_size(ctx->h2, stream->id); want_recv = (want_recv || c_exhaust || s_exhaust); diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index f4edf2d636e..89f690462d6 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -1166,9 +1166,10 @@ static void cf_ngtcp2_adjust_pollset(struct Curl_cfilter *cf, bool c_exhaust, s_exhaust; CF_DATA_SAVE(save, cf, data); - c_exhaust = !ngtcp2_conn_get_cwnd_left(ctx->qconn) || - !ngtcp2_conn_get_max_data_left(ctx->qconn); - s_exhaust = stream && stream->id >= 0 && stream->quic_flow_blocked; + c_exhaust = want_send && (!ngtcp2_conn_get_cwnd_left(ctx->qconn) || + !ngtcp2_conn_get_max_data_left(ctx->qconn)); + s_exhaust = want_send && stream && stream->id >= 0 && + stream->quic_flow_blocked; want_recv = (want_recv || c_exhaust || s_exhaust); want_send = (!s_exhaust && want_send) || !Curl_bufq_is_empty(&ctx->q.sendbuf); diff --git a/lib/vquic/curl_quiche.c b/lib/vquic/curl_quiche.c index 33c2621dc8b..9c4df2df0f6 100644 --- a/lib/vquic/curl_quiche.c +++ b/lib/vquic/curl_quiche.c @@ -1189,7 +1189,7 @@ static void cf_quiche_adjust_pollset(struct Curl_cfilter *cf, c_exhaust = FALSE; /* Have not found any call in quiche that tells us if the connection itself is blocked */ - s_exhaust = stream && stream->id >= 0 && + s_exhaust = want_send && stream && stream->id >= 0 && (stream->quic_flow_blocked || !stream_is_writeable(cf, data)); want_recv = (want_recv || c_exhaust || s_exhaust); want_send = (!s_exhaust && want_send) || From afdb6c2d34c2e7f4e6e31acaa0df029023f96b05 Mon Sep 17 00:00:00 2001 From: Lealem Amedie Date: Fri, 5 Jan 2024 13:12:53 -0700 Subject: [PATCH 120/509] wolfssl: load certificate *chain* for PEM client certs Closes #12634 --- lib/vtls/wolfssl.c | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/lib/vtls/wolfssl.c b/lib/vtls/wolfssl.c index 998008ec7bf..a3c017ceaab 100644 --- a/lib/vtls/wolfssl.c +++ b/lib/vtls/wolfssl.c @@ -583,12 +583,25 @@ wolfssl_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) if(ssl_config->primary.clientcert && ssl_config->key) { int file_type = do_file_type(ssl_config->cert_type); - if(wolfSSL_CTX_use_certificate_file(backend->ctx, - ssl_config->primary.clientcert, - file_type) != 1) { - failf(data, "unable to use client certificate (no key or wrong pass" - " phrase?)"); - return CURLE_SSL_CONNECT_ERROR; + if(file_type == WOLFSSL_FILETYPE_PEM) { + if(wolfSSL_CTX_use_certificate_chain_file(backend->ctx, + ssl_config->primary.clientcert) + != 1) { + failf(data, "unable to use client certificate"); + return CURLE_SSL_CONNECT_ERROR; + } + } + else if(file_type == WOLFSSL_FILETYPE_ASN1) { + if(wolfSSL_CTX_use_certificate_file(backend->ctx, + ssl_config->primary.clientcert, + file_type) != 1) { + failf(data, "unable to use client certificate"); + return CURLE_SSL_CONNECT_ERROR; + } + } + else { + failf(data, "unknown cert type"); + return CURLE_BAD_FUNCTION_ARGUMENT; } file_type = do_file_type(ssl_config->key_type); From f4beef524a53e1951c102fdb2ab96dd7a5e01077 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 5 Jan 2024 11:52:08 +0100 Subject: [PATCH 121/509] ftp: use dynbuf to store entrypath avoid direct malloc Closes #12638 --- lib/ftp.c | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/lib/ftp.c b/lib/ftp.c index ee3b403d3cd..65b4db98154 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -2863,12 +2863,9 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, if(ftpcode == 257) { char *ptr = &data->state.buffer[4]; /* start on the first letter */ const size_t buf_size = data->set.buffer_size; - char *dir; bool entry_extracted = FALSE; - - dir = malloc(nread + 1); - if(!dir) - return CURLE_OUT_OF_MEMORY; + struct dynbuf out; + Curl_dyn_init(&out, 1000); /* Reply format is like 257[rubbish]"" and the @@ -2886,13 +2883,11 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, if('\"' == *ptr) { /* it started good */ - char *store; - ptr++; - for(store = dir; *ptr;) { + for(ptr++; *ptr; ptr++) { if('\"' == *ptr) { if('\"' == ptr[1]) { /* "quote-doubling" */ - *store = ptr[1]; + result = Curl_dyn_addn(&out, &ptr[1], 1); ptr++; } else { @@ -2902,11 +2897,10 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, } } else - *store = *ptr; - store++; - ptr++; + result = Curl_dyn_addn(&out, ptr, 1); + if(result) + return result; } - *store = '\0'; /* null-terminate */ } if(entry_extracted) { /* If the path name does not look like an absolute path (i.e.: it @@ -2920,6 +2914,7 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, The method used here is to check the server OS: we do it only if the path name looks strange to minimize overhead on other systems. */ + char *dir = Curl_dyn_ptr(&out); if(!ftpc->server_os && dir[0] != '/') { result = Curl_pp_sendf(data, &ftpc->pp, "%s", "SYST"); @@ -2944,7 +2939,7 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, } else { /* couldn't get the path */ - free(dir); + Curl_dyn_free(&out); infof(data, "Failed to figure out path"); } } From 8edcfedc1a144f438bd1cdf814a0016cbe678aaf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 5 Jan 2024 11:58:48 +0100 Subject: [PATCH 122/509] ftp: use memdup0 to store the OS from a SYST 215 response avoid malloc + direct buffer fiddle Closes #12639 --- lib/ftp.c | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/lib/ftp.c b/lib/ftp.c index 65b4db98154..bf8b57db267 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -2951,23 +2951,20 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, if(ftpcode == 215) { char *ptr = &data->state.buffer[4]; /* start on the first letter */ char *os; - char *store; - - os = malloc(nread + 1); - if(!os) - return CURLE_OUT_OF_MEMORY; + char *start; /* Reply format is like 215 */ while(*ptr == ' ') ptr++; - for(store = os; *ptr && *ptr != ' ';) - *store++ = *ptr++; - *store = '\0'; /* null-terminate */ + for(start = ptr; *ptr && *ptr != ' '; ptr++) + ; + os = Curl_memdup0(start, ptr - start); + if(!os) + return CURLE_OUT_OF_MEMORY; /* Check for special servers here. */ - if(strcasecompare(os, "OS/400")) { /* Force OS400 name format 1. */ result = Curl_pp_sendf(data, &ftpc->pp, "%s", "SITE NAMEFMT 1"); From a0f94800d507de580f04a447cf14edc9f52697dc Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 5 Jan 2024 12:28:09 +0100 Subject: [PATCH 123/509] transfer: adjust_pollset improvements - let `multi_getsock()` initialize the pollset in what the transfer state requires in regards to SEND/RECV - change connection filters `adjust_pollset()` implementation to react on the presence of POLLIN/-OUT in the pollset and no longer check CURL_WANT_SEND/CURL_WANT_RECV - cf-socket will no longer add POLLIN on its own - http2 and http/3 filters will only do adjustments if the passed pollset wants to POLLIN/OUT for the transfer on the socket. This is similar to the HTTP/2 proxy filter and works in stacked filters. Closes #12640 --- lib/cf-socket.c | 2 +- lib/cfilters.c | 14 ----- lib/cfilters.h | 5 -- lib/http2.c | 12 ++-- lib/multi.c | 131 +++++++++++++++++++++++++++++++--------- lib/transfer.c | 46 -------------- lib/transfer.h | 2 - lib/urldata.h | 2 +- lib/vquic/curl_ngtcp2.c | 9 ++- lib/vquic/curl_quiche.c | 9 ++- 10 files changed, 125 insertions(+), 107 deletions(-) diff --git a/lib/cf-socket.c b/lib/cf-socket.c index c86aa7e7c2a..2e985a77f30 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -1243,7 +1243,7 @@ static void cf_socket_adjust_pollset(struct Curl_cfilter *cf, if(ctx->sock != CURL_SOCKET_BAD) { if(!cf->connected) Curl_pollset_set_out_only(data, ps, ctx->sock); - else if(CURL_WANT_RECV(data)) + else if(!ctx->active) Curl_pollset_add_in(data, ps, ctx->sock); CURL_TRC_CF(data, cf, "adjust_pollset -> %d socks", ps->num); } diff --git a/lib/cfilters.c b/lib/cfilters.c index e78ecd71de2..823e90c3f2b 100644 --- a/lib/cfilters.c +++ b/lib/cfilters.c @@ -760,25 +760,11 @@ static void ps_add(struct Curl_easy *data, struct easy_pollset *ps, void Curl_pollset_add_socks(struct Curl_easy *data, struct easy_pollset *ps, int (*get_socks_cb)(struct Curl_easy *data, - struct connectdata *conn, curl_socket_t *socks)) { curl_socket_t socks[MAX_SOCKSPEREASYHANDLE]; int bitmap; - DEBUGASSERT(data->conn); - bitmap = get_socks_cb(data, data->conn, socks); - ps_add(data, ps, bitmap, socks); -} - -void Curl_pollset_add_socks2(struct Curl_easy *data, - struct easy_pollset *ps, - int (*get_socks_cb)(struct Curl_easy *data, - curl_socket_t *socks)) -{ - curl_socket_t socks[MAX_SOCKSPEREASYHANDLE]; - int bitmap; - bitmap = get_socks_cb(data, socks); ps_add(data, ps, bitmap, socks); } diff --git a/lib/cfilters.h b/lib/cfilters.h index 09a3f162acf..f83842920bc 100644 --- a/lib/cfilters.h +++ b/lib/cfilters.h @@ -530,12 +530,7 @@ void Curl_pollset_set(struct Curl_easy *data, void Curl_pollset_add_socks(struct Curl_easy *data, struct easy_pollset *ps, int (*get_socks_cb)(struct Curl_easy *data, - struct connectdata *conn, curl_socket_t *socks)); -void Curl_pollset_add_socks2(struct Curl_easy *data, - struct easy_pollset *ps, - int (*get_socks_cb)(struct Curl_easy *data, - curl_socket_t *socks)); /** * Check if the pollset, as is, wants to read and/or write regarding diff --git a/lib/http2.c b/lib/http2.c index b7a08607945..c3157d1ef28 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -2331,12 +2331,16 @@ static void cf_h2_adjust_pollset(struct Curl_cfilter *cf, struct easy_pollset *ps) { struct cf_h2_ctx *ctx = cf->ctx; - bool want_recv = CURL_WANT_RECV(data); - bool want_send = CURL_WANT_SEND(data); + curl_socket_t sock; + bool want_recv, want_send; - if(ctx->h2 && (want_recv || want_send)) { + if(!ctx->h2) + return; + + sock = Curl_conn_cf_get_socket(cf, data); + Curl_pollset_check(data, ps, sock, &want_recv, &want_send); + if(want_recv || want_send) { struct stream_ctx *stream = H2_STREAM_CTX(data); - curl_socket_t sock = Curl_conn_cf_get_socket(cf, data); struct cf_call_data save; bool c_exhaust, s_exhaust; diff --git a/lib/multi.c b/lib/multi.c index 9c7cde8f16c..e4491d912c9 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -994,31 +994,90 @@ void Curl_attach_connection(struct Curl_easy *data, Curl_conn_ev_data_attach(conn, data); } -static int domore_getsock(struct Curl_easy *data, - struct connectdata *conn, - curl_socket_t *socks) +static int connecting_getsock(struct Curl_easy *data, curl_socket_t *socks) { + struct connectdata *conn = data->conn; + (void)socks; + if(conn && conn->sockfd != CURL_SOCKET_BAD) { + /* Default is to wait to something from the server */ + socks[0] = conn->sockfd; + return GETSOCK_READSOCK(0); + } + return GETSOCK_BLANK; +} + +static int protocol_getsock(struct Curl_easy *data, curl_socket_t *socks) +{ + struct connectdata *conn = data->conn; + if(conn && conn->handler->proto_getsock) + return conn->handler->proto_getsock(data, conn, socks); + else if(conn && conn->sockfd != CURL_SOCKET_BAD) { + /* Default is to wait to something from the server */ + socks[0] = conn->sockfd; + return GETSOCK_READSOCK(0); + } + return GETSOCK_BLANK; +} + +static int domore_getsock(struct Curl_easy *data, curl_socket_t *socks) +{ + struct connectdata *conn = data->conn; if(conn && conn->handler->domore_getsock) return conn->handler->domore_getsock(data, conn, socks); + else if(conn && conn->sockfd != CURL_SOCKET_BAD) { + /* Default is that we want to send something to the server */ + socks[0] = conn->sockfd; + return GETSOCK_WRITESOCK(0); + } return GETSOCK_BLANK; } -static int doing_getsock(struct Curl_easy *data, - struct connectdata *conn, - curl_socket_t *socks) +static int doing_getsock(struct Curl_easy *data, curl_socket_t *socks) { + struct connectdata *conn = data->conn; if(conn && conn->handler->doing_getsock) return conn->handler->doing_getsock(data, conn, socks); + else if(conn && conn->sockfd != CURL_SOCKET_BAD) { + /* Default is that we want to send something to the server */ + socks[0] = conn->sockfd; + return GETSOCK_WRITESOCK(0); + } return GETSOCK_BLANK; } -static int protocol_getsock(struct Curl_easy *data, - struct connectdata *conn, - curl_socket_t *socks) +static int perform_getsock(struct Curl_easy *data, curl_socket_t *sock) { - if(conn->handler->proto_getsock) - return conn->handler->proto_getsock(data, conn, socks); - return GETSOCK_BLANK; + struct connectdata *conn = data->conn; + + if(!conn) + return GETSOCK_BLANK; + else if(conn->handler->perform_getsock) + return conn->handler->perform_getsock(data, conn, sock); + else { + /* Default is to obey the data->req.keepon flags for send/recv */ + int bitmap = GETSOCK_BLANK; + unsigned sockindex = 0; + if(CURL_WANT_RECV(data)) { + DEBUGASSERT(conn->sockfd != CURL_SOCKET_BAD); + bitmap |= GETSOCK_READSOCK(sockindex); + sock[sockindex] = conn->sockfd; + } + + if(CURL_WANT_SEND(data)) { + if((conn->sockfd != conn->writesockfd) || + bitmap == GETSOCK_BLANK) { + /* only if they are not the same socket and we have a readable + one, we increase index */ + if(bitmap != GETSOCK_BLANK) + sockindex++; /* increase index if we need two entries */ + + DEBUGASSERT(conn->writesockfd != CURL_SOCKET_BAD); + sock[sockindex] = conn->writesockfd; + } + bitmap |= GETSOCK_WRITESOCK(sockindex); + } + return bitmap; + } } /* Initializes `poll_set` with the current socket poll actions needed @@ -1034,45 +1093,61 @@ static void multi_getsock(struct Curl_easy *data, return; switch(data->mstate) { - default: + case MSTATE_INIT: + case MSTATE_PENDING: + case MSTATE_CONNECT: + /* nothing to poll for yet */ break; case MSTATE_RESOLVING: - Curl_pollset_add_socks2(data, ps, Curl_resolv_getsock); + Curl_pollset_add_socks(data, ps, Curl_resolv_getsock); /* connection filters are not involved in this phase */ - return; + break; + + case MSTATE_CONNECTING: + case MSTATE_TUNNELING: + Curl_pollset_add_socks(data, ps, connecting_getsock); + Curl_conn_adjust_pollset(data, ps); + break; - case MSTATE_PROTOCONNECTING: case MSTATE_PROTOCONNECT: + case MSTATE_PROTOCONNECTING: Curl_pollset_add_socks(data, ps, protocol_getsock); + Curl_conn_adjust_pollset(data, ps); break; case MSTATE_DO: case MSTATE_DOING: Curl_pollset_add_socks(data, ps, doing_getsock); - break; - - case MSTATE_TUNNELING: - case MSTATE_CONNECTING: + Curl_conn_adjust_pollset(data, ps); break; case MSTATE_DOING_MORE: Curl_pollset_add_socks(data, ps, domore_getsock); + Curl_conn_adjust_pollset(data, ps); break; - case MSTATE_DID: /* since is set after DO is completed, we switch to - waiting for the same as the PERFORMING state */ + case MSTATE_DID: /* same as PERFORMING in regard to polling */ case MSTATE_PERFORMING: - Curl_pollset_add_socks(data, ps, Curl_single_getsock); + Curl_pollset_add_socks(data, ps, perform_getsock); + Curl_conn_adjust_pollset(data, ps); break; case MSTATE_RATELIMITING: - /* nothing to wait for */ - return; - } + /* we need to let time pass, ignore socket(s) */ + break; + + case MSTATE_DONE: + case MSTATE_COMPLETED: + case MSTATE_MSGSENT: + /* nothing more to poll for */ + break; - /* Let connection filters add/remove as needed */ - Curl_conn_adjust_pollset(data, ps); + default: + failf(data, "multi_getsock: unexpected multi state %d", data->mstate); + DEBUGASSERT(0); + break; + } } CURLMcode curl_multi_fdset(struct Curl_multi *multi, diff --git a/lib/transfer.c b/lib/transfer.c index 59a3f05cb16..0d7226c8a5e 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -1220,52 +1220,6 @@ CURLcode Curl_readwrite(struct connectdata *conn, return result; } -/* - * Curl_single_getsock() gets called by the multi interface code when the app - * has requested to get the sockets for the current connection. This function - * will then be called once for every connection that the multi interface - * keeps track of. This function will only be called for connections that are - * in the proper state to have this information available. - */ -int Curl_single_getsock(struct Curl_easy *data, - struct connectdata *conn, - curl_socket_t *sock) -{ - int bitmap = GETSOCK_BLANK; - unsigned sockindex = 0; - - if(conn->handler->perform_getsock) - return conn->handler->perform_getsock(data, conn, sock); - - /* don't include HOLD and PAUSE connections */ - if((data->req.keepon & KEEP_RECVBITS) == KEEP_RECV) { - - DEBUGASSERT(conn->sockfd != CURL_SOCKET_BAD); - - bitmap |= GETSOCK_READSOCK(sockindex); - sock[sockindex] = conn->sockfd; - } - - /* don't include HOLD and PAUSE connections */ - if((data->req.keepon & KEEP_SENDBITS) == KEEP_SEND) { - if((conn->sockfd != conn->writesockfd) || - bitmap == GETSOCK_BLANK) { - /* only if they are not the same socket and we have a readable - one, we increase index */ - if(bitmap != GETSOCK_BLANK) - sockindex++; /* increase index if we need two entries */ - - DEBUGASSERT(conn->writesockfd != CURL_SOCKET_BAD); - - sock[sockindex] = conn->writesockfd; - } - - bitmap |= GETSOCK_WRITESOCK(sockindex); - } - - return bitmap; -} - /* Curl_init_CONNECT() gets called each time the handle switches to CONNECT which means this gets called once for each subsequent redirect etc */ void Curl_init_CONNECT(struct Curl_easy *data) diff --git a/lib/transfer.h b/lib/transfer.h index f1969a62a9e..b057c50d230 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -47,8 +47,6 @@ CURLcode Curl_follow(struct Curl_easy *data, char *newurl, followtype type); CURLcode Curl_readwrite(struct connectdata *conn, struct Curl_easy *data, bool *done); -int Curl_single_getsock(struct Curl_easy *data, - struct connectdata *conn, curl_socket_t *socks); CURLcode Curl_fillreadbuffer(struct Curl_easy *data, size_t bytes, size_t *nreadp); CURLcode Curl_retry_request(struct Curl_easy *data, char **url); diff --git a/lib/urldata.h b/lib/urldata.h index 210fca76c48..de192dadeaf 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -583,7 +583,7 @@ struct hostname { (((data)->req.keepon & KEEP_SENDBITS) == KEEP_SEND) /* transfer receive is not on PAUSE or HOLD */ #define CURL_WANT_RECV(data) \ - (!((data)->req.keepon & (KEEP_RECV_PAUSE|KEEP_RECV_HOLD))) + (((data)->req.keepon & KEEP_RECVBITS) == KEEP_RECV) #if defined(CURLRES_ASYNCH) || !defined(CURL_DISABLE_DOH) #define USE_CURL_ASYNC diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index 89f690462d6..e391e4f421f 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -1157,10 +1157,13 @@ static void cf_ngtcp2_adjust_pollset(struct Curl_cfilter *cf, struct easy_pollset *ps) { struct cf_ngtcp2_ctx *ctx = cf->ctx; - bool want_recv = CURL_WANT_RECV(data); - bool want_send = CURL_WANT_SEND(data); + bool want_recv, want_send; - if(ctx->qconn && (want_recv || want_send)) { + if(!ctx->qconn) + return; + + Curl_pollset_check(data, ps, ctx->q.sockfd, &want_recv, &want_send); + if(want_recv || want_send) { struct h3_stream_ctx *stream = H3_STREAM_CTX(data); struct cf_call_data save; bool c_exhaust, s_exhaust; diff --git a/lib/vquic/curl_quiche.c b/lib/vquic/curl_quiche.c index 9c4df2df0f6..ed0bde36709 100644 --- a/lib/vquic/curl_quiche.c +++ b/lib/vquic/curl_quiche.c @@ -1180,10 +1180,13 @@ static void cf_quiche_adjust_pollset(struct Curl_cfilter *cf, struct easy_pollset *ps) { struct cf_quiche_ctx *ctx = cf->ctx; - bool want_recv = CURL_WANT_RECV(data); - bool want_send = CURL_WANT_SEND(data); + bool want_recv, want_send; - if(ctx->qconn && (want_recv || want_send)) { + if(!ctx->qconn) + return; + + Curl_pollset_check(data, ps, ctx->q.sockfd, &want_recv, &want_send); + if(want_recv || want_send) { struct stream_ctx *stream = H3_STREAM_CTX(data); bool c_exhaust, s_exhaust; From 105848361558d47a10c285c82df5be5ed4f0667f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 7 Jan 2024 14:25:20 +0100 Subject: [PATCH 124/509] ftp: only consider entry path if it has a length Follow-up from 8edcfedc1a144f438bd1cdf814a0016cb Bug: https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65631 Avoids a NULL pointer deref. Closes #12648 --- lib/ftp.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/ftp.c b/lib/ftp.c index bf8b57db267..cea77d7ee5d 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -2892,7 +2892,8 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, } else { /* end of path */ - entry_extracted = TRUE; + if(Curl_dyn_len(&out)) + entry_extracted = TRUE; break; /* get out of this loop */ } } From e556470c23c6f375df93736f8488de3b658fc35f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 7 Jan 2024 12:06:12 +0100 Subject: [PATCH 125/509] connect: remove margin from eyeballer alloc Presumably leftovers from debugging Closes #12647 --- lib/connect.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/connect.c b/lib/connect.c index 4cb6eda115c..45743e98b52 100644 --- a/lib/connect.c +++ b/lib/connect.c @@ -389,7 +389,7 @@ static CURLcode eyeballer_new(struct eyeballer **pballer, struct eyeballer *baller; *pballer = NULL; - baller = calloc(1, sizeof(*baller) + 1000); + baller = calloc(1, sizeof(*baller)); if(!baller) return CURLE_OUT_OF_MEMORY; From d0cb2c7a1f09c17442987be8937cd2ac3708e524 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 8 Jan 2024 15:02:12 +0100 Subject: [PATCH 126/509] url: init conn->sockfd and writesockfd to CURL_SOCKET_BAD Also add more tracing to test 19 Follow-up to a0f9480 Fixes #12657 Closes #12659 --- lib/url.c | 2 ++ tests/data/test19 | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/url.c b/lib/url.c index 7764668dc23..e60020bc204 100644 --- a/lib/url.c +++ b/lib/url.c @@ -1356,6 +1356,8 @@ static struct connectdata *allocate_conn(struct Curl_easy *data) conn->sock[FIRSTSOCKET] = CURL_SOCKET_BAD; /* no file descriptor */ conn->sock[SECONDARYSOCKET] = CURL_SOCKET_BAD; /* no file descriptor */ + conn->sockfd = CURL_SOCKET_BAD; + conn->writesockfd = CURL_SOCKET_BAD; conn->connection_id = -1; /* no ID */ conn->port = -1; /* unknown at this point */ conn->remote_port = -1; /* unknown at this point */ diff --git a/tests/data/test19 b/tests/data/test19 index 265a74ad884..cf735a42f3f 100644 --- a/tests/data/test19 +++ b/tests/data/test19 @@ -24,7 +24,7 @@ http attempt connect to non-listening socket -%HOSTIP:%NOLISTENPORT +--trace-config all %HOSTIP:%NOLISTENPORT From 57cc70e559aa065426021e22e2af8166af6084f6 Mon Sep 17 00:00:00 2001 From: Gabe <66077254+MrBrain295@users.noreply.github.com> Date: Sun, 7 Jan 2024 21:27:05 -0600 Subject: [PATCH 127/509] COPYING: update copyright year Closes #12654 --- COPYING | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. From 07dd60c05b5f6b00ff7cc0d65c6b46cb1a6938a2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 128/509] tool_getparam: bsearch cmdline options - the option names are now alpha sorted and lookup is a lot faster - use case sensitive matching. It was previously case insensitive, but that was not documented nor tested. - remove "partial match" feature. It was not documented, not tested and was always fragile as existing use could break when we add a new option - lookup short options via a table Closes #12631 --- src/tool_getparam.c | 663 ++++++++++++++++++++++---------------------- tests/data/test285 | 2 +- tests/data/test498 | 2 +- tests/test1139.pl | 12 +- 4 files changed, 343 insertions(+), 336 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 7aa40bbe288..0b962aec447 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -72,7 +72,6 @@ static ParameterError getstr(char **str, const char *val, bool allowblank) } struct LongShort { - const char *letter; /* short name option */ const char *lname; /* long name option */ enum { ARG_NONE, /* stand-alone but not a boolean */ @@ -80,292 +79,279 @@ struct LongShort { ARG_STRING, /* requires an argument */ ARG_FILENAME /* requires an argument, usually a file name */ } desc; + const char *letter; /* short name option */ + /* 'letter' strings with more than one character have *no* short option. */ }; +/* this array MUST be alphasorted based on the 'lname' */ static const struct LongShort aliases[]= { - /* 'letter' strings with more than one character have *no* short option to - mention. */ - {"*@", "url", ARG_STRING}, - {"*4", "dns-ipv4-addr", ARG_STRING}, - {"*6", "dns-ipv6-addr", ARG_STRING}, - {"*a", "random-file", ARG_FILENAME}, - {"*b", "egd-file", ARG_STRING}, - {"*B", "oauth2-bearer", ARG_STRING}, - {"*c", "connect-timeout", ARG_STRING}, - {"*C", "doh-url" , ARG_STRING}, - {"*d", "ciphers", ARG_STRING}, - {"*D", "dns-interface", ARG_STRING}, - {"*e", "disable-epsv", ARG_BOOL}, - {"*f", "disallow-username-in-url", ARG_BOOL}, - {"*E", "epsv", ARG_BOOL}, - /* 'epsv' made like this to make --no-epsv and --epsv to work - although --disable-epsv is the documented option */ - {"*F", "dns-servers", ARG_STRING}, - {"*g", "trace", ARG_FILENAME}, - {"*G", "npn", ARG_BOOL}, - {"*h", "trace-ascii", ARG_FILENAME}, - {"*H", "alpn", ARG_BOOL}, - {"*i", "limit-rate", ARG_STRING}, - {"*I", "rate", ARG_STRING}, - {"*j", "compressed", ARG_BOOL}, - {"*J", "tr-encoding", ARG_BOOL}, - {"*k", "digest", ARG_BOOL}, - {"*l", "negotiate", ARG_BOOL}, - {"*m", "ntlm", ARG_BOOL}, - {"*M", "ntlm-wb", ARG_BOOL}, - {"*n", "basic", ARG_BOOL}, - {"*o", "anyauth", ARG_BOOL}, + {"abstract-unix-socket", ARG_FILENAME, "$W"}, + {"alpn", ARG_BOOL, "*H"}, + {"alt-svc", ARG_STRING, "ba"}, + {"anyauth", ARG_BOOL, "*o"}, + {"append", ARG_BOOL, "a",}, + {"aws-sigv4", ARG_STRING, "*V"}, + {"basic", ARG_BOOL, "*n"}, + {"buffer", ARG_BOOL, "N",}, + {"ca-native", ARG_BOOL, "EG"}, + {"cacert", ARG_FILENAME, "Ea"}, + {"capath", ARG_FILENAME, "Eg"}, + {"cert", ARG_FILENAME, "E",}, + {"cert-status", ARG_BOOL, "Eq"}, + {"cert-type", ARG_STRING, "Eb"}, + {"ciphers", ARG_STRING, "*d"}, + {"clobber", ARG_BOOL, "Oc"}, + {"compressed", ARG_BOOL, "*j"}, + {"compressed-ssh", ARG_BOOL, "$Z"}, + {"config", ARG_FILENAME, "K",}, + {"connect-timeout", ARG_STRING, "*c"}, + {"connect-to", ARG_STRING, "$U"}, + {"continue-at", ARG_STRING, "C",}, + {"cookie", ARG_STRING, "b",}, + {"cookie-jar", ARG_STRING, "c",}, + {"create-dirs", ARG_BOOL, "*r"}, + {"create-file-mode", ARG_STRING, "*R"}, + {"crlf", ARG_BOOL, "*u"}, + {"crlfile", ARG_FILENAME, "Ej"}, + {"curves", ARG_STRING, "EE"}, + {"data", ARG_STRING, "d",}, + {"data-ascii", ARG_STRING, "da"}, + {"data-binary", ARG_STRING, "db"}, + {"data-raw", ARG_STRING, "dr"}, + {"data-urlencode", ARG_STRING, "de"}, + {"delegation", ARG_STRING, "$G"}, + {"digest", ARG_BOOL, "*k"}, + {"disable", ARG_BOOL, "q",}, + {"disable-eprt", ARG_BOOL, "*z"}, + {"disable-epsv", ARG_BOOL, "*e"}, + {"disallow-username-in-url", ARG_BOOL, "*f"}, + {"dns-interface", ARG_STRING, "*D"}, + {"dns-ipv4-addr", ARG_STRING, "*4"}, + {"dns-ipv6-addr", ARG_STRING, "*6"}, + {"dns-servers", ARG_STRING, "*F"}, + {"doh-cert-status", ARG_BOOL, "EQ"}, + {"doh-insecure", ARG_BOOL, "kd"}, + {"doh-url" , ARG_STRING, "*C"}, + {"dump-header", ARG_FILENAME, "D",}, + {"egd-file", ARG_STRING, "*b"}, + {"engine", ARG_STRING, "Ef"}, + {"eprt", ARG_BOOL, "*Z"}, + {"epsv", ARG_BOOL, "*E"}, + {"etag-compare", ARG_FILENAME, "ED"}, + {"etag-save", ARG_FILENAME, "EC"}, + {"expect100-timeout", ARG_STRING, "$R"}, + {"fail", ARG_BOOL, "f",}, + {"fail-early", ARG_BOOL, "fa"}, + {"fail-with-body", ARG_BOOL, "fd"}, + {"false-start", ARG_BOOL, "Er"}, + {"form", ARG_STRING, "F",}, + {"form-escape", ARG_BOOL, "$l"}, + {"form-string", ARG_STRING, "Fs"}, + {"ftp-account", ARG_STRING, "$m"}, + {"ftp-alternative-to-user", ARG_STRING, "$u"}, + {"ftp-create-dirs", ARG_BOOL, "*q"}, + {"ftp-method", ARG_STRING, "$r"}, + {"ftp-pasv", ARG_BOOL, "$b"}, + {"ftp-port", ARG_STRING, "P",}, + {"ftp-pret", ARG_BOOL, "$C"}, + {"ftp-skip-pasv-ip", ARG_BOOL, "$q"}, + {"ftp-ssl", ARG_BOOL, "$a"}, + {"ftp-ssl-ccc", ARG_BOOL, "$y"}, + {"ftp-ssl-ccc-mode", ARG_STRING, "$j"}, + {"ftp-ssl-control", ARG_BOOL, "$x"}, + {"ftp-ssl-reqd", ARG_BOOL, "$v"}, + {"get", ARG_BOOL, "G",}, + {"globoff", ARG_BOOL, "g",}, + {"happy-eyeballs-timeout-ms", ARG_STRING, "$~"}, + {"haproxy-clientip", ARG_STRING, "*P"}, + {"haproxy-protocol", ARG_BOOL, "*X"}, + {"head", ARG_BOOL, "I",}, + {"header", ARG_STRING, "H",}, + {"help", ARG_BOOL, "h",}, + {"hostpubmd5", ARG_STRING, "Ei"}, + {"hostpubsha256", ARG_STRING, "EF"}, + {"hsts", ARG_STRING, "bb"}, + {"http0.9", ARG_BOOL, "09"}, + {"http1.0", ARG_NONE, "0",}, + {"http1.1", ARG_NONE, "01"}, + {"http2", ARG_NONE, "02"}, + {"http2-prior-knowledge", ARG_NONE, "03"}, + {"http3", ARG_NONE, "04"}, + {"http3-only", ARG_NONE, "05"}, + {"ignore-content-length", ARG_BOOL, "$p"}, + {"include", ARG_BOOL, "i",}, + {"insecure", ARG_BOOL, "k",}, + {"interface", ARG_STRING, "*w"}, + {"ipfs-gateway", ARG_STRING, "*S"}, + {"ipv4", ARG_NONE, "4",}, + {"ipv6", ARG_NONE, "6",}, + {"json", ARG_STRING, "df"}, + {"junk-session-cookies", ARG_BOOL, "j",}, + {"keepalive", ARG_BOOL, "$1"}, + {"keepalive-time", ARG_STRING, "$3"}, + {"key", ARG_FILENAME, "Ec"}, + {"key-type", ARG_STRING, "Ed"}, + {"krb", ARG_STRING, "*x"}, + {"krb4", ARG_STRING, "*x"}, + {"libcurl", ARG_STRING, "$z"}, + {"limit-rate", ARG_STRING, "*i"}, + {"list-only", ARG_BOOL, "l",}, + {"local-port", ARG_STRING, "$s"}, + {"location", ARG_BOOL, "L",}, + {"location-trusted", ARG_BOOL, "Lt"}, + {"login-options", ARG_STRING, "E5"}, + {"mail-auth", ARG_STRING, "$H"}, + {"mail-from", ARG_STRING, "$A"}, + {"mail-rcpt", ARG_STRING, "$B"}, + {"mail-rcpt-allowfails", ARG_BOOL, "fc"}, + {"manual", ARG_BOOL, "M",}, + {"max-filesize", ARG_STRING, "*y"}, + {"max-redirs", ARG_STRING, "*s"}, + {"max-time", ARG_STRING, "m",}, + {"metalink", ARG_BOOL, "$J"}, + {"negotiate", ARG_BOOL, "*l"}, + {"netrc", ARG_BOOL, "n",}, + {"netrc-file", ARG_FILENAME, "ne"}, + {"netrc-optional", ARG_BOOL, "no"}, + {"next", ARG_NONE, ":",}, + {"noproxy", ARG_STRING, "$5"}, + {"npn", ARG_BOOL, "*G"}, + {"ntlm", ARG_BOOL, "*m"}, + {"ntlm-wb", ARG_BOOL, "*M"}, + {"oauth2-bearer", ARG_STRING, "*B"}, + {"output", ARG_FILENAME, "o",}, + {"output-dir", ARG_STRING, "Ob"}, + {"parallel", ARG_BOOL, "Z",}, + {"parallel-immediate", ARG_BOOL, "Zc"}, + {"parallel-max", ARG_STRING, "Zb"}, + {"pass", ARG_STRING, "Ee"}, + {"path-as-is", ARG_BOOL, "$N"}, + {"pinnedpubkey", ARG_STRING, "Ep"}, + {"post301", ARG_BOOL, "$0"}, + {"post302", ARG_BOOL, "$4"}, + {"post303", ARG_BOOL, "$I"}, + {"preproxy", ARG_STRING, "xa"}, + {"progress-bar", ARG_BOOL, "#",}, + {"progress-meter", ARG_BOOL, "#m"}, + {"proto", ARG_STRING, "$D"}, + {"proto-default", ARG_STRING, "$Q"}, + {"proto-redir", ARG_STRING, "$E"}, + {"proxy", ARG_STRING, "x",}, + {"proxy-anyauth", ARG_BOOL, "$n"}, + {"proxy-basic", ARG_BOOL, "$f"}, + {"proxy-ca-native", ARG_BOOL, "EH"}, + {"proxy-cacert", ARG_FILENAME, "E6"}, + {"proxy-capath", ARG_FILENAME, "E7"}, + {"proxy-cert", ARG_FILENAME, "Ex"}, + {"proxy-cert-type", ARG_STRING, "Ey"}, + {"proxy-ciphers", ARG_STRING, "E2"}, + {"proxy-crlfile", ARG_FILENAME, "E3"}, + {"proxy-digest", ARG_BOOL, "$e"}, + {"proxy-header", ARG_STRING, "Hp"}, + {"proxy-http2", ARG_BOOL, "0a"}, + {"proxy-insecure", ARG_BOOL, "E8"}, + {"proxy-key", ARG_FILENAME, "Ez"}, + {"proxy-key-type", ARG_STRING, "E0"}, + {"proxy-negotiate", ARG_BOOL, "$k"}, + {"proxy-ntlm", ARG_BOOL, "*t"}, + {"proxy-pass", ARG_STRING, "E1"}, + {"proxy-pinnedpubkey", ARG_STRING, "EP"}, + {"proxy-service-name", ARG_STRING, "$O"}, + {"proxy-ssl-allow-beast", ARG_BOOL, "E4"}, + {"proxy-ssl-auto-client-cert", ARG_BOOL, "EO"}, + {"proxy-tls13-ciphers", ARG_STRING, "1B"}, + {"proxy-tlsauthtype", ARG_STRING, "Ew"}, + {"proxy-tlspassword", ARG_STRING, "Ev"}, + {"proxy-tlsuser", ARG_STRING, "Eu"}, + {"proxy-tlsv1", ARG_NONE, "E9"}, + {"proxy-user", ARG_STRING, "U",}, + {"proxy1.0", ARG_STRING, "$8"}, + {"proxytunnel", ARG_BOOL, "p",}, + {"pubkey", ARG_STRING, "Eh"}, + {"quote", ARG_STRING, "Q",}, + {"random-file", ARG_FILENAME, "*a"}, + {"range", ARG_STRING, "r",}, + {"rate", ARG_STRING, "*I"}, + {"raw", ARG_BOOL, "$#"}, + {"referer", ARG_STRING, "e",}, + {"remote-header-name", ARG_BOOL, "J",}, + {"remote-name", ARG_BOOL, "O",}, + {"remote-name-all", ARG_BOOL, "Oa"}, + {"remote-time", ARG_BOOL, "R",}, + {"remove-on-error", ARG_BOOL, "fe"}, + {"request", ARG_STRING, "X",}, + {"request-target", ARG_STRING, "Ga"}, + {"resolve", ARG_STRING, "$F"}, + {"retry", ARG_STRING, "$g"}, + {"retry-all-errors", ARG_BOOL, "$!"}, + {"retry-connrefused", ARG_BOOL, "$V"}, + {"retry-delay", ARG_STRING, "$h"}, + {"retry-max-time", ARG_STRING, "$i"}, + {"sasl-authzid", ARG_STRING, "$6"}, + {"sasl-ir", ARG_BOOL, "$K"}, + {"service-name", ARG_STRING, "$P"}, + {"sessionid", ARG_BOOL, "$w"}, + {"show-error", ARG_BOOL, "S",}, + {"silent", ARG_BOOL, "s",}, + {"socks4", ARG_STRING, "$t"}, + {"socks4a", ARG_STRING, "$T"}, + {"socks5", ARG_STRING, "$c"}, + {"socks5-basic", ARG_BOOL, "EA"}, + {"socks5-gssapi", ARG_BOOL, "EB"}, + {"socks5-gssapi-nec", ARG_BOOL, "$7"}, + {"socks5-gssapi-service", ARG_STRING, "$O"}, + {"socks5-hostname", ARG_STRING, "$2"}, + {"speed-limit", ARG_STRING, "Y",}, + {"speed-time", ARG_STRING, "y",}, + {"ssl", ARG_BOOL, "$a"}, + {"ssl-allow-beast", ARG_BOOL, "En"}, + {"ssl-auto-client-cert", ARG_BOOL, "Eo"}, + {"ssl-no-revoke", ARG_BOOL, "Es"}, + {"ssl-reqd", ARG_BOOL, "$v"}, + {"ssl-revoke-best-effort", ARG_BOOL, "ES"}, + {"sslv2", ARG_NONE, "2",}, + {"sslv3", ARG_NONE, "3",}, + {"stderr", ARG_FILENAME, "*v"}, + {"styled-output", ARG_BOOL, "fb"}, + {"suppress-connect-headers", ARG_BOOL, "$Y"}, + {"tcp-fastopen", ARG_BOOL, "Et"}, + {"tcp-nodelay", ARG_BOOL, "$d"}, + {"telnet-option", ARG_STRING, "t",}, + {"test-event", ARG_BOOL, "$L"}, + {"tftp-blksize", ARG_STRING, "$9"}, + {"tftp-no-options", ARG_BOOL, "$S"}, + {"time-cond", ARG_STRING, "z",}, + {"tls-max", ARG_STRING, "$X"}, + {"tls13-ciphers", ARG_STRING, "1A"}, + {"tlsauthtype", ARG_STRING, "Em"}, + {"tlspassword", ARG_STRING, "El"}, + {"tlsuser", ARG_STRING, "Ek"}, + {"tlsv1", ARG_NONE, "1",}, + {"tlsv1.0", ARG_NONE, "10"}, + {"tlsv1.1", ARG_NONE, "11"}, + {"tlsv1.2", ARG_NONE, "12"}, + {"tlsv1.3", ARG_NONE, "13"}, + {"tr-encoding", ARG_BOOL, "*J"}, + {"trace", ARG_FILENAME, "*g"}, + {"trace-ascii", ARG_FILENAME, "*h"}, + {"trace-config", ARG_STRING, "$&"}, + {"trace-ids", ARG_BOOL, "$%"}, + {"trace-time", ARG_BOOL, "$o"}, + {"unix-socket", ARG_FILENAME, "$M"}, + {"upload-file", ARG_FILENAME, "T",}, + {"url", ARG_STRING, "*@"}, + {"url-query", ARG_STRING, "dg"}, + {"use-ascii", ARG_BOOL, "B",}, + {"user", ARG_STRING, "u",}, + {"user-agent", ARG_STRING, "A",}, + {"variable", ARG_STRING, ":a"}, + {"verbose", ARG_BOOL, "v",}, + {"version", ARG_BOOL, "V",}, #ifdef USE_WATT32 - {"*p", "wdebug", ARG_BOOL}, + {"wdebug", ARG_BOOL, "*p"}, #endif - {"*q", "ftp-create-dirs", ARG_BOOL}, - {"*r", "create-dirs", ARG_BOOL}, - {"*R", "create-file-mode", ARG_STRING}, - {"*s", "max-redirs", ARG_STRING}, - {"*S", "ipfs-gateway", ARG_STRING}, - {"*t", "proxy-ntlm", ARG_BOOL}, - {"*u", "crlf", ARG_BOOL}, - {"*v", "stderr", ARG_FILENAME}, - {"*V", "aws-sigv4", ARG_STRING}, - {"*w", "interface", ARG_STRING}, - {"*x", "krb", ARG_STRING}, - {"*x", "krb4", ARG_STRING}, - /* 'krb4' is the previous name */ - {"*X", "haproxy-protocol", ARG_BOOL}, - {"*P", "haproxy-clientip", ARG_STRING}, - {"*y", "max-filesize", ARG_STRING}, - {"*z", "disable-eprt", ARG_BOOL}, - {"*Z", "eprt", ARG_BOOL}, - /* 'eprt' made like this to make --no-eprt and --eprt to work - although --disable-eprt is the documented option */ - {"*~", "xattr", ARG_BOOL}, - {"$a", "ftp-ssl", ARG_BOOL}, - /* 'ftp-ssl' deprecated name since 7.20.0 */ - {"$a", "ssl", ARG_BOOL}, - /* 'ssl' new option name in 7.20.0, previously this was ftp-ssl */ - {"$b", "ftp-pasv", ARG_BOOL}, - {"$c", "socks5", ARG_STRING}, - {"$d", "tcp-nodelay", ARG_BOOL}, - {"$e", "proxy-digest", ARG_BOOL}, - {"$f", "proxy-basic", ARG_BOOL}, - {"$g", "retry", ARG_STRING}, - {"$V", "retry-connrefused", ARG_BOOL}, - {"$h", "retry-delay", ARG_STRING}, - {"$i", "retry-max-time", ARG_STRING}, - {"$k", "proxy-negotiate", ARG_BOOL}, - {"$l", "form-escape", ARG_BOOL}, - {"$m", "ftp-account", ARG_STRING}, - {"$n", "proxy-anyauth", ARG_BOOL}, - {"$o", "trace-time", ARG_BOOL}, - {"$p", "ignore-content-length", ARG_BOOL}, - {"$q", "ftp-skip-pasv-ip", ARG_BOOL}, - {"$r", "ftp-method", ARG_STRING}, - {"$s", "local-port", ARG_STRING}, - {"$t", "socks4", ARG_STRING}, - {"$T", "socks4a", ARG_STRING}, - {"$u", "ftp-alternative-to-user", ARG_STRING}, - {"$v", "ftp-ssl-reqd", ARG_BOOL}, - /* 'ftp-ssl-reqd' deprecated name since 7.20.0 */ - {"$v", "ssl-reqd", ARG_BOOL}, - /* 'ssl-reqd' new in 7.20.0, previously this was ftp-ssl-reqd */ - {"$w", "sessionid", ARG_BOOL}, - /* 'sessionid' listed as --no-sessionid in the help */ - {"$x", "ftp-ssl-control", ARG_BOOL}, - {"$y", "ftp-ssl-ccc", ARG_BOOL}, - {"$j", "ftp-ssl-ccc-mode", ARG_STRING}, - {"$z", "libcurl", ARG_STRING}, - {"$#", "raw", ARG_BOOL}, - {"$0", "post301", ARG_BOOL}, - {"$1", "keepalive", ARG_BOOL}, - /* 'keepalive' listed as --no-keepalive in the help */ - {"$2", "socks5-hostname", ARG_STRING}, - {"$3", "keepalive-time", ARG_STRING}, - {"$4", "post302", ARG_BOOL}, - {"$5", "noproxy", ARG_STRING}, - {"$7", "socks5-gssapi-nec", ARG_BOOL}, - {"$8", "proxy1.0", ARG_STRING}, - {"$9", "tftp-blksize", ARG_STRING}, - {"$A", "mail-from", ARG_STRING}, - {"$B", "mail-rcpt", ARG_STRING}, - {"$C", "ftp-pret", ARG_BOOL}, - {"$D", "proto", ARG_STRING}, - {"$E", "proto-redir", ARG_STRING}, - {"$F", "resolve", ARG_STRING}, - {"$G", "delegation", ARG_STRING}, - {"$H", "mail-auth", ARG_STRING}, - {"$I", "post303", ARG_BOOL}, - {"$J", "metalink", ARG_BOOL}, - {"$6", "sasl-authzid", ARG_STRING}, - {"$K", "sasl-ir", ARG_BOOL }, - {"$L", "test-event", ARG_BOOL}, - {"$M", "unix-socket", ARG_FILENAME}, - {"$N", "path-as-is", ARG_BOOL}, - {"$O", "socks5-gssapi-service", ARG_STRING}, - /* 'socks5-gssapi-service' merged with'proxy-service-name' and - deprecated since 7.49.0 */ - {"$O", "proxy-service-name", ARG_STRING}, - {"$P", "service-name", ARG_STRING}, - {"$Q", "proto-default", ARG_STRING}, - {"$R", "expect100-timeout", ARG_STRING}, - {"$S", "tftp-no-options", ARG_BOOL}, - {"$U", "connect-to", ARG_STRING}, - {"$W", "abstract-unix-socket", ARG_FILENAME}, - {"$X", "tls-max", ARG_STRING}, - {"$Y", "suppress-connect-headers", ARG_BOOL}, - {"$Z", "compressed-ssh", ARG_BOOL}, - {"$~", "happy-eyeballs-timeout-ms", ARG_STRING}, - {"$!", "retry-all-errors", ARG_BOOL}, - {"$%", "trace-ids", ARG_BOOL}, - {"$&", "trace-config", ARG_STRING}, - {"0", "http1.0", ARG_NONE}, - {"01", "http1.1", ARG_NONE}, - {"02", "http2", ARG_NONE}, - {"03", "http2-prior-knowledge", ARG_NONE}, - {"04", "http3", ARG_NONE}, - {"05", "http3-only", ARG_NONE}, - {"09", "http0.9", ARG_BOOL}, - {"0a", "proxy-http2", ARG_BOOL}, - {"1", "tlsv1", ARG_NONE}, - {"10", "tlsv1.0", ARG_NONE}, - {"11", "tlsv1.1", ARG_NONE}, - {"12", "tlsv1.2", ARG_NONE}, - {"13", "tlsv1.3", ARG_NONE}, - {"1A", "tls13-ciphers", ARG_STRING}, - {"1B", "proxy-tls13-ciphers", ARG_STRING}, - {"2", "sslv2", ARG_NONE}, - {"3", "sslv3", ARG_NONE}, - {"4", "ipv4", ARG_NONE}, - {"6", "ipv6", ARG_NONE}, - {"a", "append", ARG_BOOL}, - {"A", "user-agent", ARG_STRING}, - {"b", "cookie", ARG_STRING}, - {"ba", "alt-svc", ARG_STRING}, - {"bb", "hsts", ARG_STRING}, - {"B", "use-ascii", ARG_BOOL}, - {"c", "cookie-jar", ARG_STRING}, - {"C", "continue-at", ARG_STRING}, - {"d", "data", ARG_STRING}, - {"dr", "data-raw", ARG_STRING}, - {"da", "data-ascii", ARG_STRING}, - {"db", "data-binary", ARG_STRING}, - {"de", "data-urlencode", ARG_STRING}, - {"df", "json", ARG_STRING}, - {"dg", "url-query", ARG_STRING}, - {"D", "dump-header", ARG_FILENAME}, - {"e", "referer", ARG_STRING}, - {"E", "cert", ARG_FILENAME}, - {"Ea", "cacert", ARG_FILENAME}, - {"Eb", "cert-type", ARG_STRING}, - {"Ec", "key", ARG_FILENAME}, - {"Ed", "key-type", ARG_STRING}, - {"Ee", "pass", ARG_STRING}, - {"Ef", "engine", ARG_STRING}, - {"EG", "ca-native", ARG_BOOL}, - {"EH", "proxy-ca-native", ARG_BOOL}, - {"Eg", "capath", ARG_FILENAME}, - {"Eh", "pubkey", ARG_STRING}, - {"Ei", "hostpubmd5", ARG_STRING}, - {"EF", "hostpubsha256", ARG_STRING}, - {"Ej", "crlfile", ARG_FILENAME}, - {"Ek", "tlsuser", ARG_STRING}, - {"El", "tlspassword", ARG_STRING}, - {"Em", "tlsauthtype", ARG_STRING}, - {"En", "ssl-allow-beast", ARG_BOOL}, - {"Eo", "ssl-auto-client-cert", ARG_BOOL}, - {"EO", "proxy-ssl-auto-client-cert", ARG_BOOL}, - {"Ep", "pinnedpubkey", ARG_STRING}, - {"EP", "proxy-pinnedpubkey", ARG_STRING}, - {"Eq", "cert-status", ARG_BOOL}, - {"EQ", "doh-cert-status", ARG_BOOL}, - {"Er", "false-start", ARG_BOOL}, - {"Es", "ssl-no-revoke", ARG_BOOL}, - {"ES", "ssl-revoke-best-effort", ARG_BOOL}, - {"Et", "tcp-fastopen", ARG_BOOL}, - {"Eu", "proxy-tlsuser", ARG_STRING}, - {"Ev", "proxy-tlspassword", ARG_STRING}, - {"Ew", "proxy-tlsauthtype", ARG_STRING}, - {"Ex", "proxy-cert", ARG_FILENAME}, - {"Ey", "proxy-cert-type", ARG_STRING}, - {"Ez", "proxy-key", ARG_FILENAME}, - {"E0", "proxy-key-type", ARG_STRING}, - {"E1", "proxy-pass", ARG_STRING}, - {"E2", "proxy-ciphers", ARG_STRING}, - {"E3", "proxy-crlfile", ARG_FILENAME}, - {"E4", "proxy-ssl-allow-beast", ARG_BOOL}, - {"E5", "login-options", ARG_STRING}, - {"E6", "proxy-cacert", ARG_FILENAME}, - {"E7", "proxy-capath", ARG_FILENAME}, - {"E8", "proxy-insecure", ARG_BOOL}, - {"E9", "proxy-tlsv1", ARG_NONE}, - {"EA", "socks5-basic", ARG_BOOL}, - {"EB", "socks5-gssapi", ARG_BOOL}, - {"EC", "etag-save", ARG_FILENAME}, - {"ED", "etag-compare", ARG_FILENAME}, - {"EE", "curves", ARG_STRING}, - {"f", "fail", ARG_BOOL}, - {"fa", "fail-early", ARG_BOOL}, - {"fb", "styled-output", ARG_BOOL}, - {"fc", "mail-rcpt-allowfails", ARG_BOOL}, - {"fd", "fail-with-body", ARG_BOOL}, - {"fe", "remove-on-error", ARG_BOOL}, - {"F", "form", ARG_STRING}, - {"Fs", "form-string", ARG_STRING}, - {"g", "globoff", ARG_BOOL}, - {"G", "get", ARG_BOOL}, - {"Ga", "request-target", ARG_STRING}, - {"h", "help", ARG_BOOL}, - {"H", "header", ARG_STRING}, - {"Hp", "proxy-header", ARG_STRING}, - {"i", "include", ARG_BOOL}, - {"I", "head", ARG_BOOL}, - {"j", "junk-session-cookies", ARG_BOOL}, - {"J", "remote-header-name", ARG_BOOL}, - {"k", "insecure", ARG_BOOL}, - {"kd", "doh-insecure", ARG_BOOL}, - {"K", "config", ARG_FILENAME}, - {"l", "list-only", ARG_BOOL}, - {"L", "location", ARG_BOOL}, - {"Lt", "location-trusted", ARG_BOOL}, - {"m", "max-time", ARG_STRING}, - {"M", "manual", ARG_BOOL}, - {"n", "netrc", ARG_BOOL}, - {"no", "netrc-optional", ARG_BOOL}, - {"ne", "netrc-file", ARG_FILENAME}, - {"N", "buffer", ARG_BOOL}, - /* 'buffer' listed as --no-buffer in the help */ - {"o", "output", ARG_FILENAME}, - {"O", "remote-name", ARG_BOOL}, - {"Oa", "remote-name-all", ARG_BOOL}, - {"Ob", "output-dir", ARG_STRING}, - {"Oc", "clobber", ARG_BOOL}, - {"p", "proxytunnel", ARG_BOOL}, - {"P", "ftp-port", ARG_STRING}, - {"q", "disable", ARG_BOOL}, - {"Q", "quote", ARG_STRING}, - {"r", "range", ARG_STRING}, - {"R", "remote-time", ARG_BOOL}, - {"s", "silent", ARG_BOOL}, - {"S", "show-error", ARG_BOOL}, - {"t", "telnet-option", ARG_STRING}, - {"T", "upload-file", ARG_FILENAME}, - {"u", "user", ARG_STRING}, - {"U", "proxy-user", ARG_STRING}, - {"v", "verbose", ARG_BOOL}, - {"V", "version", ARG_BOOL}, - {"w", "write-out", ARG_STRING}, - {"x", "proxy", ARG_STRING}, - {"xa", "preproxy", ARG_STRING}, - {"X", "request", ARG_STRING}, - {"Y", "speed-limit", ARG_STRING}, - {"y", "speed-time", ARG_STRING}, - {"z", "time-cond", ARG_STRING}, - {"Z", "parallel", ARG_BOOL}, - {"Zb", "parallel-max", ARG_STRING}, - {"Zc", "parallel-immediate", ARG_BOOL}, - {"#", "progress-bar", ARG_BOOL}, - {"#m", "progress-meter", ARG_BOOL}, - {":", "next", ARG_NONE}, - {":a", "variable", ARG_STRING}, + {"write-out", ARG_STRING, "w",}, + {"xattr", ARG_BOOL, "*~"}, }; /* Split the argument of -E to 'certname' and 'passphrase' separated by colon. @@ -501,12 +487,14 @@ static void GetFileAndPassword(char *nextarg, char **file, char **password) { char *certname, *passphrase; - parse_cert_parameter(nextarg, &certname, &passphrase); - Curl_safefree(*file); - *file = certname; - if(passphrase) { - Curl_safefree(*password); - *password = passphrase; + if(nextarg) { + parse_cert_parameter(nextarg, &certname, &passphrase); + Curl_safefree(*file); + *file = certname; + if(passphrase) { + Curl_safefree(*password); + *password = passphrase; + } } } @@ -746,6 +734,32 @@ static CURLcode set_trace_config(struct GlobalConfig *global, return result; } +static int findarg(const void *a, const void *b) +{ + const struct LongShort *aa = a; + const struct LongShort *bb = b; + return strcmp(aa->lname, bb->lname); +} + +static const struct LongShort *single(char letter) +{ + static const struct LongShort *singles[128 - ' ']; /* ASCII => pointer */ + static bool singles_done = FALSE; + DEBUGASSERT((letter < 127) && (letter > ' ')); + + if(!singles_done) { + unsigned int j; + for(j = 0; j < sizeof(aliases)/sizeof(aliases[0]); j++) { + if(!aliases[j].letter[1]) { + unsigned char l = aliases[j].letter[0]; + singles[l - ' '] = &aliases[j]; + } + } + singles_done = TRUE; + } + return singles[letter - ' ']; +} + ParameterError getparameter(const char *flag, /* f or -long-flag */ char *nextarg, /* NULL if unset */ argv_item_t cleararg, @@ -758,9 +772,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ char subletter = '\0'; /* subletters can only occur on long options */ int rc; const char *parse = NULL; - unsigned int j; time_t now; - int hit = -1; bool longopt = FALSE; bool singleopt = FALSE; /* when true means '-o foo' used '-ofoo' */ ParameterError err = PARAM_OK; @@ -775,6 +787,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ "ftps", NULL }; + const struct LongShort *a = NULL; #ifdef HAVE_WRITABLE_ARGV argv_item_t clearthis = NULL; #else @@ -786,10 +799,9 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ if(('-' != flag[0]) || ('-' == flag[1])) { /* this should be a long name */ const char *word = ('-' == flag[0]) ? flag + 2 : flag; - size_t fnam = strlen(word); - int numhits = 0; bool noflagged = FALSE; bool expand = FALSE; + struct LongShort key; if(!strncmp(word, "no-", 3)) { /* disable this option but ignore the "no-" part when looking for it */ @@ -802,31 +814,19 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ word += 7; expand = TRUE; } + key.lname = word; - for(j = 0; j < sizeof(aliases)/sizeof(aliases[0]); j++) { - if(curl_strnequal(aliases[j].lname, word, fnam)) { - longopt = TRUE; - numhits++; - if(curl_strequal(aliases[j].lname, word)) { - parse = aliases[j].letter; - hit = j; - numhits = 1; /* a single unique hit */ - break; - } - parse = aliases[j].letter; - hit = j; - } - } - if(numhits > 1) { - /* this is at least the second match! */ - err = PARAM_OPTION_AMBIGUOUS; - goto error; + a = bsearch(&key, aliases, sizeof(aliases)/sizeof(aliases[0]), + sizeof(aliases[0]), findarg); + if(a) { + longopt = TRUE; + parse = a->letter; } - else if(hit < 0) { + else { err = PARAM_OPTION_UNKNOWN; goto error; } - else if(noflagged && (aliases[hit].desc != ARG_BOOL)) { + if(noflagged && (a->desc != ARG_BOOL)) { /* --no- prefixed an option that isn't boolean! */ err = PARAM_NO_NOT_BOOLEAN; goto error; @@ -835,8 +835,8 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ struct curlx_dynbuf nbuf; bool replaced; - if((aliases[hit].desc != ARG_STRING) && - (aliases[hit].desc != ARG_FILENAME)) { + if((a->desc != ARG_STRING) && + (a->desc != ARG_FILENAME)) { /* --expand on an option that isn't a string or a filename */ err = PARAM_EXPAND_ERROR; goto error; @@ -854,7 +854,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } else { flag++; /* prefixed with one dash, pass it */ - hit = -1; parse = flag; } @@ -870,20 +869,15 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ subletter = parse[1]; } - if(hit < 0) { - for(j = 0; j < sizeof(aliases)/sizeof(aliases[0]); j++) { - if(letter == aliases[j].letter[0]) { - hit = j; - break; - } - } - if(hit < 0) { + if(!a) { + a = single(letter); + if(!a) { err = PARAM_OPTION_UNKNOWN; break; } } - if(aliases[hit].desc >= ARG_STRING) { + if(a->desc >= ARG_STRING) { /* this option requires an extra parameter */ if(!longopt && parse[1]) { nextarg = (char *)&parse[1]; /* this is the actual extra parameter */ @@ -900,18 +894,25 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ *usedarg = TRUE; /* mark it as used */ } - if((aliases[hit].desc == ARG_FILENAME) && + if((a->desc == ARG_FILENAME) && (nextarg[0] == '-') && nextarg[1]) { /* if the file name looks like a command line option */ warnf(global, "The file name argument '%s' looks like a flag.", nextarg); } } - else if((aliases[hit].desc == ARG_NONE) && !toggle) { + else if((a->desc == ARG_NONE) && !toggle) { err = PARAM_NO_PREFIX; break; } + if(!nextarg) + /* this is a precaution mostly to please scan-build, as all arguments + that use nextarg should be marked as such and they will check that + nextarg is set before continuing, but code analyzers are not always + that aware of that state */ + nextarg = (char *)""; + switch(letter) { case '*': /* options without a short option */ switch(subletter) { @@ -1919,7 +1920,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case 'f': /* crypto engine */ err = getstr(&config->engine, nextarg, DENY_BLANK); if(!err && - config->engine && curl_strequal(config->engine, "list")) { + config->engine && !strcmp(config->engine, "list")) { err = PARAM_ENGINES_REQUESTED; } break; @@ -1966,7 +1967,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; } err = getstr(&config->tls_authtype, nextarg, DENY_BLANK); - if(!err && !curl_strequal(config->tls_authtype, "SRP")) + if(!err && strcmp(config->tls_authtype, "SRP")) err = PARAM_LIBCURL_DOESNT_SUPPORT; /* only support TLS-SRP */ break; case 'n': /* no empty SSL fragments, --ssl-allow-beast */ @@ -2042,7 +2043,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; } err = getstr(&config->proxy_tls_authtype, nextarg, DENY_BLANK); - if(!err && !curl_strequal(config->proxy_tls_authtype, "SRP")) + if(!err && strcmp(config->proxy_tls_authtype, "SRP")) err = PARAM_LIBCURL_DOESNT_SUPPORT; /* only support TLS-SRP */ break; @@ -2196,7 +2197,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case 'h': /* h for help */ if(toggle) { - if(nextarg) { + if(*nextarg) { global->help_category = strdup(nextarg); if(!global->help_category) { err = PARAM_NO_MEM; @@ -2675,7 +2676,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_OPTION_UNKNOWN; break; } - hit = -1; + a = NULL; } while(!longopt && !singleopt && *++parse && !*usedarg && !err); diff --git a/tests/data/test285 b/tests/data/test285 index 7968e1a34c5..03dc96f6a08 100644 --- a/tests/data/test285 +++ b/tests/data/test285 @@ -16,7 +16,7 @@ tftp TFTP send --T %LOGDIR/test%TESTNUMBER.txt tftp://%HOSTIP:%TFTPPORT// --connect-time 549 +-T %LOGDIR/test%TESTNUMBER.txt tftp://%HOSTIP:%TFTPPORT// --connect-timeout 549 a chunk of diff --git a/tests/data/test498 b/tests/data/test498 index 457c28043b3..b1fc02380bd 100644 --- a/tests/data/test498 +++ b/tests/data/test498 @@ -35,7 +35,7 @@ http Reject too large HTTP response headers on endless redirects -http://%HOSTIP:%HTTPPORT/%TESTNUMBER --max-redir 400 --location +http://%HOSTIP:%HTTPPORT/%TESTNUMBER --max-redirs 400 --location diff --git a/tests/test1139.pl b/tests/test1139.pl index c09e979d0bd..1c3c017daf2 100755 --- a/tests/test1139.pl +++ b/tests/test1139.pl @@ -181,18 +181,23 @@ sub scanmanpage { my $list; my @getparam; # store all parsed parameters +my $prevlong = ""; +my $no = 0; while(<$r>) { + $no++; chomp; - my $l= $_; if(/struct LongShort aliases/) { $list=1; } elsif($list) { - if( /^ \{([^,]*), *([^ ]*)/) { - my ($s, $l)=($1, $2); + if( /^ \{(\"[^,]*\").*((\"[^ ]*)\")/) { + my ($l, $s)=($1, $2); my $sh; my $lo; my $title; + if(($l cmp $prevlong) < 0) { + print STDERR "tool_getparam.c:$no: '$l' is NOT placed in alpha-order\n"; + } if($l =~ /\"(.*)\"/) { # long option $lo = $1; @@ -205,6 +210,7 @@ sub scanmanpage { } push @getparam, $title; $opts{$title} |= 1; + $prevlong = $l; } } } From f6e97effb6d6b7b6cd5f30ba2525d9e20bd70cc1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 129/509] tool_getparam: unify the cmdline switch() into a single one - easier to follow, easier to modify, easier to extend, possibly slightly faster - each case now has the long option as a comment --- src/tool_getparam.c | 2066 +++++++++++++++++++++---------------------- 1 file changed, 990 insertions(+), 1076 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 0b962aec447..e23f020be12 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -760,6 +760,8 @@ static const struct LongShort *single(char letter) return singles[letter - ' ']; } +#define ONEOPT(x,y) (((int)x << 8) | y) + ParameterError getparameter(const char *flag, /* f or -long-flag */ char *nextarg, /* NULL if unset */ argv_item_t cleararg, @@ -788,6 +790,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ NULL }; const struct LongShort *a = NULL; + curl_off_t value; #ifdef HAVE_WRITABLE_ARGV argv_item_t clearthis = NULL; #else @@ -913,802 +916,745 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ that aware of that state */ nextarg = (char *)""; - switch(letter) { - case '*': /* options without a short option */ - switch(subletter) { - case '4': /* --dns-ipv4-addr */ - if(!curlinfo->ares_num) /* c-ares is needed for this */ - err = PARAM_LIBCURL_DOESNT_SUPPORT; - else - /* addr in dot notation */ - err = getstr(&config->dns_ipv4_addr, nextarg, DENY_BLANK); - break; - case '6': /* --dns-ipv6-addr */ - if(!curlinfo->ares_num) /* c-ares is needed for this */ - err = PARAM_LIBCURL_DOESNT_SUPPORT; - else - /* addr in dot notation */ - err = getstr(&config->dns_ipv6_addr, nextarg, DENY_BLANK); - break; - case 'a': /* random-file */ - break; - case 'b': /* egd-file */ - break; - case 'B': /* OAuth 2.0 bearer token */ - err = getstr(&config->oauth_bearer, nextarg, DENY_BLANK); - if(!err) { - cleanarg(clearthis); - config->authtype |= CURLAUTH_BEARER; - } - break; - case 'c': /* connect-timeout */ - err = secs2ms(&config->connecttimeout_ms, nextarg); - break; - case 'C': /* doh-url */ - err = getstr(&config->doh_url, nextarg, ALLOW_BLANK); - if(!err && config->doh_url && !config->doh_url[0]) - /* if given a blank string, make it NULL again */ - Curl_safefree(config->doh_url); - break; - case 'd': /* ciphers */ - err = getstr(&config->cipher_list, nextarg, DENY_BLANK); - break; - case 'D': /* --dns-interface */ - if(!curlinfo->ares_num) /* c-ares is needed for this */ - err = PARAM_LIBCURL_DOESNT_SUPPORT; - else - /* interface name */ - err = getstr(&config->dns_interface, nextarg, DENY_BLANK); - break; - case 'e': /* --disable-epsv */ - config->disable_epsv = toggle; - break; - case 'f': /* --disallow-username-in-url */ - config->disallow_username_in_url = toggle; - break; - case 'E': /* --epsv */ - config->disable_epsv = (!toggle)?TRUE:FALSE; - break; - case 'F': /* --dns-servers */ - if(!curlinfo->ares_num) /* c-ares is needed for this */ - err = PARAM_LIBCURL_DOESNT_SUPPORT; - else - /* IP addrs of DNS servers */ - err = getstr(&config->dns_servers, nextarg, DENY_BLANK); - break; - case 'g': /* --trace */ - err = getstr(&global->trace_dump, nextarg, DENY_BLANK); - if(!err) { - if(global->tracetype && (global->tracetype != TRACE_BIN)) - warnf(global, "--trace overrides an earlier trace/verbose option"); - global->tracetype = TRACE_BIN; - } - break; - case 'G': /* --npn */ - warnf(global, "--npn is no longer supported"); - break; - case 'h': /* --trace-ascii */ - err = getstr(&global->trace_dump, nextarg, DENY_BLANK); - if(!err) { - if(global->tracetype && (global->tracetype != TRACE_ASCII)) - warnf(global, - "--trace-ascii overrides an earlier trace/verbose option"); - global->tracetype = TRACE_ASCII; - } - break; - case 'H': /* --alpn */ - config->noalpn = (!toggle)?TRUE:FALSE; - break; - case 'i': /* --limit-rate */ - { - curl_off_t value; - err = GetSizeParameter(global, nextarg, "rate", &value); - if(err) - break; + switch(ONEOPT(letter, subletter)) { + case ONEOPT('*', '4'): /* --dns-ipv4-addr */ + if(!curlinfo->ares_num) /* c-ares is needed for this */ + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else + /* addr in dot notation */ + err = getstr(&config->dns_ipv4_addr, nextarg, DENY_BLANK); + break; + case ONEOPT('*', '6'): /* --dns-ipv6-addr */ + if(!curlinfo->ares_num) /* c-ares is needed for this */ + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else + /* addr in dot notation */ + err = getstr(&config->dns_ipv6_addr, nextarg, DENY_BLANK); + break; + case ONEOPT('*', 'a'): /* --random-file */ + break; + case ONEOPT('*', 'b'): /* --egd-file */ + break; + case ONEOPT('*', 'B'): /* --oauth2-bearer */ + err = getstr(&config->oauth_bearer, nextarg, DENY_BLANK); + if(!err) { + cleanarg(clearthis); + config->authtype |= CURLAUTH_BEARER; + } + break; + case ONEOPT('*', 'c'): /* --connect-timeout */ + err = secs2ms(&config->connecttimeout_ms, nextarg); + break; + case ONEOPT('*', 'C'): /* --doh-url */ + err = getstr(&config->doh_url, nextarg, ALLOW_BLANK); + if(!err && config->doh_url && !config->doh_url[0]) + /* if given a blank string, make it NULL again */ + Curl_safefree(config->doh_url); + break; + case ONEOPT('*', 'd'): /* -- ciphers */ + err = getstr(&config->cipher_list, nextarg, DENY_BLANK); + break; + case ONEOPT('*', 'D'): /* --dns-interface */ + if(!curlinfo->ares_num) /* c-ares is needed for this */ + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else + /* interface name */ + err = getstr(&config->dns_interface, nextarg, DENY_BLANK); + break; + case ONEOPT('*', 'e'): /* --disable-epsv */ + config->disable_epsv = toggle; + break; + case ONEOPT('*', 'f'): /* --disallow-username-in-url */ + config->disallow_username_in_url = toggle; + break; + case ONEOPT('*', 'E'): /* --epsv */ + config->disable_epsv = (!toggle)?TRUE:FALSE; + break; + case ONEOPT('*', 'F'): /* --dns-servers */ + if(!curlinfo->ares_num) /* c-ares is needed for this */ + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else + /* IP addrs of DNS servers */ + err = getstr(&config->dns_servers, nextarg, DENY_BLANK); + break; + case ONEOPT('*', 'g'): /* --trace */ + err = getstr(&global->trace_dump, nextarg, DENY_BLANK); + if(!err) { + if(global->tracetype && (global->tracetype != TRACE_BIN)) + warnf(global, "--trace overrides an earlier trace/verbose option"); + global->tracetype = TRACE_BIN; + } + break; + case ONEOPT('*', 'G'): /* --npn */ + warnf(global, "--npn is no longer supported"); + break; + case ONEOPT('*', 'h'): /* --trace-ascii */ + err = getstr(&global->trace_dump, nextarg, DENY_BLANK); + if(!err) { + if(global->tracetype && (global->tracetype != TRACE_ASCII)) + warnf(global, + "--trace-ascii overrides an earlier trace/verbose option"); + global->tracetype = TRACE_ASCII; + } + break; + case ONEOPT('*', 'H'): /* --alpn */ + config->noalpn = (!toggle)?TRUE:FALSE; + break; + case ONEOPT('*', 'i'): /* --limit-rate */ + err = GetSizeParameter(global, nextarg, "rate", &value); + if(!err) { config->recvpersecond = value; config->sendpersecond = value; } break; - case 'I': /* --rate (request rate) */ - { - /* support a few different suffixes, extract the suffix first, then - get the number and convert to per hour. - /s == per second - /m == per minute - /h == per hour (default) - /d == per day (24 hours) - */ - char *div = strchr(nextarg, '/'); - char number[26]; - long denominator; - long numerator = 60*60*1000; /* default per hour */ - size_t numlen = div ? (size_t)(div - nextarg) : strlen(nextarg); - if(numlen > sizeof(number)-1) { - err = PARAM_NUMBER_TOO_LARGE; + case ONEOPT('*', 'I'): { /* --rate */ + /* support a few different suffixes, extract the suffix first, then + get the number and convert to per hour. + /s == per second + /m == per minute + /h == per hour (default) + /d == per day (24 hours) + */ + char *div = strchr(nextarg, '/'); + char number[26]; + long denominator; + long numerator = 60*60*1000; /* default per hour */ + size_t numlen = div ? (size_t)(div - nextarg) : strlen(nextarg); + if(numlen > sizeof(number)-1) { + err = PARAM_NUMBER_TOO_LARGE; + break; + } + strncpy(number, nextarg, numlen); + number[numlen] = 0; + err = str2unum(&denominator, number); + if(err) + break; + + if(denominator < 1) { + err = PARAM_BAD_USE; + break; + } + if(div) { + char unit = div[1]; + switch(unit) { + case 's': /* per second */ + numerator = 1000; break; - } - strncpy(number, nextarg, numlen); - number[numlen] = 0; - err = str2unum(&denominator, number); - if(err) + case 'm': /* per minute */ + numerator = 60*1000; break; - - if(denominator < 1) { - err = PARAM_BAD_USE; + case 'h': /* per hour */ break; - } - if(div) { - char unit = div[1]; - switch(unit) { - case 's': /* per second */ - numerator = 1000; - break; - case 'm': /* per minute */ - numerator = 60*1000; - break; - case 'h': /* per hour */ - break; - case 'd': /* per day */ - numerator = 24*60*60*1000; - break; - default: - errorf(global, "unsupported --rate unit"); - err = PARAM_BAD_USE; - break; - } - } - - if(denominator > numerator) { - err = PARAM_NUMBER_TOO_LARGE; + case 'd': /* per day */ + numerator = 24*60*60*1000; + break; + default: + errorf(global, "unsupported --rate unit"); + err = PARAM_BAD_USE; break; } + } + if(err) + ; + else if(denominator > numerator) + err = PARAM_NUMBER_TOO_LARGE; + else global->ms_per_transfer = numerator/denominator; - } + } break; - case 'j': /* --compressed */ - if(toggle && !(feature_libz || feature_brotli || feature_zstd)) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + case ONEOPT('*', 'j'): /* --compressed */ + if(toggle && !(feature_libz || feature_brotli || feature_zstd)) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else config->encoding = toggle; - break; + break; - case 'J': /* --tr-encoding */ - config->tr_encoding = toggle; - break; + case ONEOPT('*', 'J'): /* --tr-encoding */ + config->tr_encoding = toggle; + break; - case 'k': /* --digest */ - if(toggle) - config->authtype |= CURLAUTH_DIGEST; - else - config->authtype &= ~CURLAUTH_DIGEST; - break; + case ONEOPT('*', 'k'): /* --digest */ + if(toggle) + config->authtype |= CURLAUTH_DIGEST; + else + config->authtype &= ~CURLAUTH_DIGEST; + break; - case 'l': /* --negotiate */ - if(!toggle) - config->authtype &= ~CURLAUTH_NEGOTIATE; - else if(feature_spnego) - config->authtype |= CURLAUTH_NEGOTIATE; - else { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - break; + case ONEOPT('*', 'l'): /* --negotiate */ + if(!toggle) + config->authtype &= ~CURLAUTH_NEGOTIATE; + else if(feature_spnego) + config->authtype |= CURLAUTH_NEGOTIATE; + else + err = PARAM_LIBCURL_DOESNT_SUPPORT; + break; - case 'm': /* --ntlm */ - if(!toggle) - config->authtype &= ~CURLAUTH_NTLM; - else if(feature_ntlm) - config->authtype |= CURLAUTH_NTLM; - else { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - break; + case ONEOPT('*', 'm'): /* --ntlm */ + if(!toggle) + config->authtype &= ~CURLAUTH_NTLM; + else if(feature_ntlm) + config->authtype |= CURLAUTH_NTLM; + else + err = PARAM_LIBCURL_DOESNT_SUPPORT; + break; - case 'M': /* --ntlm-wb */ - if(!toggle) - config->authtype &= ~CURLAUTH_NTLM_WB; - else if(feature_ntlm_wb) - config->authtype |= CURLAUTH_NTLM_WB; - else { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - break; + case ONEOPT('*', 'M'): /* --ntlm-wb */ + if(!toggle) + config->authtype &= ~CURLAUTH_NTLM_WB; + else if(feature_ntlm_wb) + config->authtype |= CURLAUTH_NTLM_WB; + else + err = PARAM_LIBCURL_DOESNT_SUPPORT; + break; - case 'n': /* --basic for completeness */ - if(toggle) - config->authtype |= CURLAUTH_BASIC; - else - config->authtype &= ~CURLAUTH_BASIC; - break; + case ONEOPT('*', 'n'): /* --basic */ + if(toggle) + config->authtype |= CURLAUTH_BASIC; + else + config->authtype &= ~CURLAUTH_BASIC; + break; - case 'o': /* --anyauth, let libcurl pick it */ - if(toggle) - config->authtype = CURLAUTH_ANY; - /* --no-anyauth simply doesn't touch it */ - break; + case ONEOPT('*', 'o'): /* --anyauth */ + if(toggle) + config->authtype = CURLAUTH_ANY; + /* --no-anyauth simply doesn't touch it */ + break; #ifdef USE_WATT32 - case 'p': /* --wdebug */ - dbug_init(); - break; + case ONEOPT('*', 'p'): /* --wdebug */ + dbug_init(); + break; #endif - case 'q': /* --ftp-create-dirs */ - config->ftp_create_dirs = toggle; - break; + case ONEOPT('*', 'q'): /* --ftp-create-dirs */ + config->ftp_create_dirs = toggle; + break; - case 'r': /* --create-dirs */ - config->create_dirs = toggle; - break; + case ONEOPT('*', 'r'): /* --create-dirs */ + config->create_dirs = toggle; + break; - case 'R': /* --create-file-mode */ - err = oct2nummax(&config->create_file_mode, nextarg, 0777); - break; + case ONEOPT('*', 'R'): /* --create-file-mode */ + err = oct2nummax(&config->create_file_mode, nextarg, 0777); + break; - case 's': /* --max-redirs */ - /* specified max no of redirects (http(s)), this accepts -1 as a - special condition */ - err = str2num(&config->maxredirs, nextarg); - if(err) - break; - if(config->maxredirs < -1) - err = PARAM_BAD_NUMERIC; - break; + case ONEOPT('*', 's'): /* --max-redirs */ + /* specified max no of redirects (http(s)), this accepts -1 as a + special condition */ + err = str2num(&config->maxredirs, nextarg); + if(!err && (config->maxredirs < -1)) + err = PARAM_BAD_NUMERIC; + break; - case 'S': /* ipfs gateway url */ - err = getstr(&config->ipfs_gateway, nextarg, DENY_BLANK); - break; + case ONEOPT('*', 'S'): /* --ipfs-gateway */ + err = getstr(&config->ipfs_gateway, nextarg, DENY_BLANK); + break; - case 't': /* --proxy-ntlm */ - if(!feature_ntlm) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + case ONEOPT('*', 't'): /* --proxy-ntlm */ + if(!feature_ntlm) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else config->proxyntlm = toggle; - break; + break; - case 'u': /* --crlf */ - /* LF -> CRLF conversion? */ - config->crlf = toggle; - break; + case ONEOPT('*', 'u'): /* --crlf */ + /* LF -> CRLF conversion? */ + config->crlf = toggle; + break; - case 'V': /* --aws-sigv4 */ - config->authtype |= CURLAUTH_AWS_SIGV4; - err = getstr(&config->aws_sigv4, nextarg, DENY_BLANK); - break; + case ONEOPT('*', 'V'): /* --aws-sigv4 */ + config->authtype |= CURLAUTH_AWS_SIGV4; + err = getstr(&config->aws_sigv4, nextarg, DENY_BLANK); + break; - case 'v': /* --stderr */ - tool_set_stderr_file(global, nextarg); - break; - case 'w': /* --interface */ - /* interface */ - err = getstr(&config->iface, nextarg, DENY_BLANK); - break; - case 'x': /* --krb */ - /* kerberos level string */ - if(!feature_spnego) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + case ONEOPT('*', 'v'): /* --stderr */ + tool_set_stderr_file(global, nextarg); + break; + case ONEOPT('*', 'w'): /* --interface */ + /* interface */ + err = getstr(&config->iface, nextarg, DENY_BLANK); + break; + case ONEOPT('*', 'x'): /* --krb */ + /* kerberos level string */ + if(!feature_spnego) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else err = getstr(&config->krblevel, nextarg, DENY_BLANK); - break; - case 'X': /* --haproxy-protocol */ - config->haproxy_protocol = toggle; - break; - case 'P': /* --haproxy-clientip */ - err = getstr(&config->haproxy_clientip, nextarg, DENY_BLANK); - break; - case 'y': /* --max-filesize */ - { - curl_off_t value; - err = - GetSizeParameter(global, nextarg, "max-filesize", &value); - if(err) - break; - config->max_filesize = value; - } - break; - case 'z': /* --disable-eprt */ - config->disable_eprt = toggle; - break; - case 'Z': /* --eprt */ - config->disable_eprt = (!toggle)?TRUE:FALSE; - break; - case '~': /* --xattr */ - config->xattr = toggle; - break; - case '@': /* the URL! */ - if(!config->url_get) - config->url_get = config->url_list; - - if(config->url_get) { - /* there's a node here, if it already is filled-in continue to find - an "empty" node */ - while(config->url_get && (config->url_get->flags & GETOUT_URL)) - config->url_get = config->url_get->next; - } + break; + case ONEOPT('*', 'X'): /* --haproxy-protocol */ + config->haproxy_protocol = toggle; + break; + case ONEOPT('*', 'P'): /* --haproxy-clientip */ + err = getstr(&config->haproxy_clientip, nextarg, DENY_BLANK); + break; + case ONEOPT('*', 'y'): /* --max-filesize */ + err = GetSizeParameter(global, nextarg, "max-filesize", &value); + if(!err) + config->max_filesize = value; + break; + case ONEOPT('*', 'z'): /* --disable-eprt */ + config->disable_eprt = toggle; + break; + case ONEOPT('*', 'Z'): /* --eprt */ + config->disable_eprt = (!toggle)?TRUE:FALSE; + break; + case ONEOPT('*', '~'): /* --xattr */ + config->xattr = toggle; + break; + case ONEOPT('*', '@'): /* --url */ + if(!config->url_get) + config->url_get = config->url_list; - /* now there might or might not be an available node to fill in! */ + if(config->url_get) { + /* there's a node here, if it already is filled-in continue to find + an "empty" node */ + while(config->url_get && (config->url_get->flags & GETOUT_URL)) + config->url_get = config->url_get->next; + } - if(config->url_get) - /* existing node */ - url = config->url_get; - else - /* there was no free node, create one! */ - config->url_get = url = new_getout(config); + /* now there might or might not be an available node to fill in! */ - if(!url) { - err = PARAM_NO_MEM; - break; - } + if(config->url_get) + /* existing node */ + url = config->url_get; + else + /* there was no free node, create one! */ + config->url_get = url = new_getout(config); - /* fill in the URL */ - err = getstr(&url->url, nextarg, DENY_BLANK); - url->flags |= GETOUT_URL; + if(!url) { + err = PARAM_NO_MEM; + break; } + + /* fill in the URL */ + err = getstr(&url->url, nextarg, DENY_BLANK); + url->flags |= GETOUT_URL; break; - case '$': /* more options without a short option */ - switch(subletter) { - case 'a': /* --ssl */ - if(toggle && !feature_ssl) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - config->ftp_ssl = toggle; - if(config->ftp_ssl) - warnf(global, - "--ssl is an insecure option, consider --ssl-reqd instead"); - break; - case 'b': /* --ftp-pasv */ - Curl_safefree(config->ftpport); - break; - case 'c': /* --socks5 specifies a socks5 proxy to use, and resolves - the name locally and passes on the resolved address */ - err = getstr(&config->proxy, nextarg, DENY_BLANK); - config->proxyver = CURLPROXY_SOCKS5; - break; - case 't': /* --socks4 specifies a socks4 proxy to use */ - err = getstr(&config->proxy, nextarg, DENY_BLANK); - config->proxyver = CURLPROXY_SOCKS4; - break; - case 'T': /* --socks4a specifies a socks4a proxy to use */ - err = getstr(&config->proxy, nextarg, DENY_BLANK); - config->proxyver = CURLPROXY_SOCKS4A; - break; - case '2': /* --socks5-hostname specifies a socks5 proxy and enables name - resolving with the proxy */ - err = getstr(&config->proxy, nextarg, DENY_BLANK); - config->proxyver = CURLPROXY_SOCKS5_HOSTNAME; - break; - case 'd': /* --tcp-nodelay option */ - config->tcp_nodelay = toggle; - break; - case 'e': /* --proxy-digest */ - config->proxydigest = toggle; - break; - case 'f': /* --proxy-basic */ - config->proxybasic = toggle; - break; - case 'g': /* --retry */ - err = str2unum(&config->req_retry, nextarg); - break; - case 'V': /* --retry-connrefused */ - config->retry_connrefused = toggle; - break; - case 'h': /* --retry-delay */ - err = str2unummax(&config->retry_delay, nextarg, LONG_MAX/1000); - break; - case 'i': /* --retry-max-time */ - err = str2unummax(&config->retry_maxtime, nextarg, LONG_MAX/1000); - break; - case '!': /* --retry-all-errors */ - config->retry_all_errors = toggle; - break; - case 'k': /* --proxy-negotiate */ - if(!feature_spnego) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - config->proxynegotiate = toggle; + case ONEOPT('$', 'a'): /* --ssl */ + if(toggle && !feature_ssl) { + err = PARAM_LIBCURL_DOESNT_SUPPORT; break; + } + config->ftp_ssl = toggle; + if(config->ftp_ssl) + warnf(global, + "--ssl is an insecure option, consider --ssl-reqd instead"); + break; + case ONEOPT('$', 'b'): /* --ftp-pasv */ + Curl_safefree(config->ftpport); + break; + case ONEOPT('$', 'c'): /* --socks5 */ + /* socks5 proxy to use, and resolves the name locally and passes on the + resolved address */ + err = getstr(&config->proxy, nextarg, DENY_BLANK); + config->proxyver = CURLPROXY_SOCKS5; + break; + case ONEOPT('$', 't'): /* --socks4 */ + err = getstr(&config->proxy, nextarg, DENY_BLANK); + config->proxyver = CURLPROXY_SOCKS4; + break; + case ONEOPT('$', 'T'): /* --socks4a */ + err = getstr(&config->proxy, nextarg, DENY_BLANK); + config->proxyver = CURLPROXY_SOCKS4A; + break; + case ONEOPT('$', '2'): /* --socks5-hostname */ + err = getstr(&config->proxy, nextarg, DENY_BLANK); + config->proxyver = CURLPROXY_SOCKS5_HOSTNAME; + break; + case ONEOPT('$', 'd'): /* --tcp-nodelay */ + config->tcp_nodelay = toggle; + break; + case ONEOPT('$', 'e'): /* --proxy-digest */ + config->proxydigest = toggle; + break; + case ONEOPT('$', 'f'): /* --proxy-basic */ + config->proxybasic = toggle; + break; + case ONEOPT('$', 'g'): /* --retry */ + err = str2unum(&config->req_retry, nextarg); + break; + case ONEOPT('$', 'V'): /* --retry-connrefused */ + config->retry_connrefused = toggle; + break; + case ONEOPT('$', 'h'): /* --retry-delay */ + err = str2unummax(&config->retry_delay, nextarg, LONG_MAX/1000); + break; + case ONEOPT('$', 'i'): /* --retry-max-time */ + err = str2unummax(&config->retry_maxtime, nextarg, LONG_MAX/1000); + break; + case ONEOPT('$', '!'): /* --retry-all-errors */ + config->retry_all_errors = toggle; + break; - case 'l': /* --form-escape */ - config->mime_options &= ~CURLMIMEOPT_FORMESCAPE; - if(toggle) - config->mime_options |= CURLMIMEOPT_FORMESCAPE; + case ONEOPT('$', 'k'): /* --proxy-negotiate */ + if(!feature_spnego) { + err = PARAM_LIBCURL_DOESNT_SUPPORT; break; + } + config->proxynegotiate = toggle; + break; - case 'm': /* --ftp-account */ - err = getstr(&config->ftp_account, nextarg, DENY_BLANK); - break; - case 'n': /* --proxy-anyauth */ - config->proxyanyauth = toggle; - break; - case 'o': /* --trace-time */ - global->tracetime = toggle; - break; - case 'p': /* --ignore-content-length */ - config->ignorecl = toggle; - break; - case 'q': /* --ftp-skip-pasv-ip */ - config->ftp_skip_ip = toggle; - break; - case 'r': /* --ftp-method (undocumented at this point) */ - config->ftp_filemethod = ftpfilemethod(config, nextarg); - break; - case 's': { /* --local-port */ - /* 16bit base 10 is 5 digits, but we allow 6 so that this catches - overflows, not just truncates */ - char lrange[7]=""; - char *p = nextarg; - while(ISDIGIT(*p)) - p++; - if(*p) { - /* if there's anything more than a plain decimal number */ - rc = sscanf(p, " - %6s", lrange); - *p = 0; /* null-terminate to make str2unum() work below */ - } - else - rc = 0; + case ONEOPT('$', 'l'): /* --form-escape */ + config->mime_options &= ~CURLMIMEOPT_FORMESCAPE; + if(toggle) + config->mime_options |= CURLMIMEOPT_FORMESCAPE; + break; + + case ONEOPT('$', 'm'): /* --ftp-account */ + err = getstr(&config->ftp_account, nextarg, DENY_BLANK); + break; + case ONEOPT('$', 'n'): /* --proxy-anyauth */ + config->proxyanyauth = toggle; + break; + case ONEOPT('$', 'o'): /* --trace-time */ + global->tracetime = toggle; + break; + case ONEOPT('$', 'p'): /* --ignore-content-length */ + config->ignorecl = toggle; + break; + case ONEOPT('$', 'q'): /* --ftp-skip-pasv-ip */ + config->ftp_skip_ip = toggle; + break; + case ONEOPT('$', 'r'): /* --ftp-method */ + config->ftp_filemethod = ftpfilemethod(config, nextarg); + break; + case ONEOPT('$', 's'): { /* --local-port */ + /* 16bit base 10 is 5 digits, but we allow 6 so that this catches + overflows, not just truncates */ + char lrange[7]=""; + char *p = nextarg; + while(ISDIGIT(*p)) + p++; + if(*p) { + /* if there's anything more than a plain decimal number */ + rc = sscanf(p, " - %6s", lrange); + *p = 0; /* null-terminate to make str2unum() work below */ + } + else + rc = 0; - err = str2unum(&config->localport, nextarg); - if(err || (config->localport > 65535)) { + err = str2unum(&config->localport, nextarg); + if(err || (config->localport > 65535)) { + err = PARAM_BAD_USE; + break; + } + if(!rc) + config->localportrange = 1; /* default number of ports to try */ + else { + err = str2unum(&config->localportrange, lrange); + if(err || (config->localportrange > 65535)) err = PARAM_BAD_USE; - break; - } - if(!rc) - config->localportrange = 1; /* default number of ports to try */ else { - err = str2unum(&config->localportrange, lrange); - if(err || (config->localportrange > 65535)) + config->localportrange -= (config->localport-1); + if(config->localportrange < 1) err = PARAM_BAD_USE; - else { - config->localportrange -= (config->localport-1); - if(config->localportrange < 1) - err = PARAM_BAD_USE; - } } - break; } - case 'u': /* --ftp-alternative-to-user */ - err = getstr(&config->ftp_alternative_to_user, nextarg, DENY_BLANK); - break; - case 'v': /* --ssl-reqd */ - if(toggle && !feature_ssl) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - config->ftp_ssl_reqd = toggle; - break; - case 'w': /* --no-sessionid */ - config->disable_sessionid = (!toggle)?TRUE:FALSE; - break; - case 'x': /* --ftp-ssl-control */ - if(toggle && !feature_ssl) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - config->ftp_ssl_control = toggle; - break; - case 'y': /* --ftp-ssl-ccc */ - config->ftp_ssl_ccc = toggle; - if(!config->ftp_ssl_ccc_mode) - config->ftp_ssl_ccc_mode = CURLFTPSSL_CCC_PASSIVE; + break; + } + case ONEOPT('$', 'u'): /* --ftp-alternative-to-user */ + err = getstr(&config->ftp_alternative_to_user, nextarg, DENY_BLANK); + break; + case ONEOPT('$', 'v'): /* --ssl-reqd */ + if(toggle && !feature_ssl) { + err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case 'j': /* --ftp-ssl-ccc-mode */ - config->ftp_ssl_ccc = TRUE; - config->ftp_ssl_ccc_mode = ftpcccmethod(config, nextarg); + } + config->ftp_ssl_reqd = toggle; + break; + case ONEOPT('$', 'w'): /* --no-sessionid */ + config->disable_sessionid = (!toggle)?TRUE:FALSE; + break; + case ONEOPT('$', 'x'): /* --ftp-ssl-control */ + if(toggle && !feature_ssl) { + err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case 'z': /* --libcurl */ + } + config->ftp_ssl_control = toggle; + break; + case ONEOPT('$', 'y'): /* --ftp-ssl-ccc */ + config->ftp_ssl_ccc = toggle; + if(!config->ftp_ssl_ccc_mode) + config->ftp_ssl_ccc_mode = CURLFTPSSL_CCC_PASSIVE; + break; + case ONEOPT('$', 'j'): /* --ftp-ssl-ccc-mode */ + config->ftp_ssl_ccc = TRUE; + config->ftp_ssl_ccc_mode = ftpcccmethod(config, nextarg); + break; + case ONEOPT('$', 'z'): /* --libcurl */ #ifdef CURL_DISABLE_LIBCURL_OPTION - warnf(global, - "--libcurl option was disabled at build-time"); - err = PARAM_OPTION_UNKNOWN; + warnf(global, + "--libcurl option was disabled at build-time"); + err = PARAM_OPTION_UNKNOWN; #else - err = getstr(&global->libcurl, nextarg, DENY_BLANK); + err = getstr(&global->libcurl, nextarg, DENY_BLANK); #endif - break; - case '#': /* --raw */ - config->raw = toggle; - break; - case '0': /* --post301 */ - config->post301 = toggle; - break; - case '1': /* --no-keepalive */ - config->nokeepalive = (!toggle)?TRUE:FALSE; - break; - case '3': /* --keepalive-time */ - err = str2unum(&config->alivetime, nextarg); - break; - case '4': /* --post302 */ - config->post302 = toggle; - break; - case 'I': /* --post303 */ - config->post303 = toggle; - break; - case '5': /* --noproxy */ - /* This specifies the noproxy list */ - err = getstr(&config->noproxy, nextarg, ALLOW_BLANK); - break; - case '7': /* --socks5-gssapi-nec */ - config->socks5_gssapi_nec = toggle; - break; - case '8': /* --proxy1.0 */ - /* http 1.0 proxy */ - err = getstr(&config->proxy, nextarg, DENY_BLANK); - config->proxyver = CURLPROXY_HTTP_1_0; - break; - case '9': /* --tftp-blksize */ - err = str2unum(&config->tftp_blksize, nextarg); - break; - case 'A': /* --mail-from */ - err = getstr(&config->mail_from, nextarg, DENY_BLANK); - break; - case 'B': /* --mail-rcpt */ - /* append receiver to a list */ - err = add2list(&config->mail_rcpt, nextarg); - break; - case 'C': /* --ftp-pret */ - config->ftp_pret = toggle; - break; - case 'D': /* --proto */ - config->proto_present = TRUE; - err = proto2num(config, built_in_protos, &config->proto_str, nextarg); - break; - case 'E': /* --proto-redir */ - config->proto_redir_present = TRUE; - if(proto2num(config, redir_protos, &config->proto_redir_str, - nextarg)) { - err = PARAM_BAD_USE; - break; - } - break; - case 'F': /* --resolve */ - err = add2list(&config->resolve, nextarg); - break; - case 'G': /* --delegation LEVEL */ - config->gssapi_delegation = delegation(config, nextarg); - break; - case 'H': /* --mail-auth */ - err = getstr(&config->mail_auth, nextarg, DENY_BLANK); - break; - case 'J': /* --metalink */ - errorf(global, "--metalink is disabled"); + break; + case ONEOPT('$', '#'): /* --raw */ + config->raw = toggle; + break; + case ONEOPT('$', '0'): /* --post301 */ + config->post301 = toggle; + break; + case ONEOPT('$', '1'): /* --no-keepalive */ + config->nokeepalive = (!toggle)?TRUE:FALSE; + break; + case ONEOPT('$', '3'): /* --keepalive-time */ + err = str2unum(&config->alivetime, nextarg); + break; + case ONEOPT('$', '4'): /* --post302 */ + config->post302 = toggle; + break; + case ONEOPT('$', 'I'): /* --post303 */ + config->post303 = toggle; + break; + case ONEOPT('$', '5'): /* --noproxy */ + /* This specifies the noproxy list */ + err = getstr(&config->noproxy, nextarg, ALLOW_BLANK); + break; + case ONEOPT('$', '7'): /* --socks5-gssapi-nec */ + config->socks5_gssapi_nec = toggle; + break; + case ONEOPT('$', '8'): /* --proxy1.0 */ + /* http 1.0 proxy */ + err = getstr(&config->proxy, nextarg, DENY_BLANK); + config->proxyver = CURLPROXY_HTTP_1_0; + break; + case ONEOPT('$', '9'): /* --tftp-blksize */ + err = str2unum(&config->tftp_blksize, nextarg); + break; + case ONEOPT('$', 'A'): /* --mail-from */ + err = getstr(&config->mail_from, nextarg, DENY_BLANK); + break; + case ONEOPT('$', 'B'): /* --mail-rcpt */ + /* append receiver to a list */ + err = add2list(&config->mail_rcpt, nextarg); + break; + case ONEOPT('$', 'C'): /* --ftp-pret */ + config->ftp_pret = toggle; + break; + case ONEOPT('$', 'D'): /* --proto */ + config->proto_present = TRUE; + err = proto2num(config, built_in_protos, &config->proto_str, nextarg); + break; + case ONEOPT('$', 'E'): /* --proto-redir */ + config->proto_redir_present = TRUE; + if(proto2num(config, redir_protos, &config->proto_redir_str, + nextarg)) { err = PARAM_BAD_USE; break; - case '6': /* --sasl-authzid */ - err = getstr(&config->sasl_authzid, nextarg, DENY_BLANK); - break; - case 'K': /* --sasl-ir */ - config->sasl_ir = toggle; - break; - case 'L': /* --test-event */ + } + break; + case ONEOPT('$', 'F'): /* --resolve */ + err = add2list(&config->resolve, nextarg); + break; + case ONEOPT('$', 'G'): /* --delegation */ + config->gssapi_delegation = delegation(config, nextarg); + break; + case ONEOPT('$', 'H'): /* --mail-auth */ + err = getstr(&config->mail_auth, nextarg, DENY_BLANK); + break; + case ONEOPT('$', 'J'): /* --metalink */ + errorf(global, "--metalink is disabled"); + err = PARAM_BAD_USE; + break; + case ONEOPT('$', '6'): /* --sasl-authzid */ + err = getstr(&config->sasl_authzid, nextarg, DENY_BLANK); + break; + case ONEOPT('$', 'K'): /* --sasl-ir */ + config->sasl_ir = toggle; + break; + case ONEOPT('$', 'L'): /* --test-event */ #ifdef CURLDEBUG - global->test_event_based = toggle; + global->test_event_based = toggle; #else - warnf(global, "--test-event is ignored unless a debug build"); + warnf(global, "--test-event is ignored unless a debug build"); #endif - break; - case 'M': /* --unix-socket */ - config->abstract_unix_socket = FALSE; - err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); - break; - case 'N': /* --path-as-is */ - config->path_as_is = toggle; - break; - case 'O': /* --proxy-service-name */ - err = getstr(&config->proxy_service_name, nextarg, DENY_BLANK); - break; - case 'P': /* --service-name */ - err = getstr(&config->service_name, nextarg, DENY_BLANK); - break; - case 'Q': /* --proto-default */ - err = getstr(&config->proto_default, nextarg, DENY_BLANK); - if(!err) - err = check_protocol(config->proto_default); - break; - case 'R': /* --expect100-timeout */ - err = secs2ms(&config->expect100timeout_ms, nextarg); - break; - case 'S': /* --tftp-no-options */ - config->tftp_no_options = toggle; - break; - case 'U': /* --connect-to */ - err = add2list(&config->connect_to, nextarg); - break; - case 'W': /* --abstract-unix-socket */ - config->abstract_unix_socket = TRUE; - err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); - break; - case 'X': /* --tls-max */ - err = str2tls_max(&config->ssl_version_max, nextarg); - break; - case 'Y': /* --suppress-connect-headers */ - config->suppress_connect_headers = toggle; - break; - case 'Z': /* --compressed-ssh */ - config->ssh_compression = toggle; - break; - case '~': /* --happy-eyeballs-timeout-ms */ - err = str2unum(&config->happy_eyeballs_timeout_ms, nextarg); - /* 0 is a valid value for this timeout */ - break; - case '%': /* --trace-ids */ - global->traceids = toggle; - break; - case '&': /* --trace-config */ - if(set_trace_config(global, nextarg)) { - err = PARAM_NO_MEM; - } - break; - } break; - case '#': - switch(subletter) { - case 'm': /* --progress-meter */ - global->noprogress = !toggle; - break; - default: /* --progress-bar */ - global->progressmode = - toggle ? CURL_PROGRESS_BAR : CURL_PROGRESS_STATS; - break; - } + case ONEOPT('$', 'M'): /* --unix-socket */ + config->abstract_unix_socket = FALSE; + err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); break; - case ':': - switch(subletter) { - case 'a': /* --variable */ - err = setvariable(global, nextarg); - break; - default: /* --next */ - err = PARAM_NEXT_OPERATION; - break; - } + case ONEOPT('$', 'N'): /* --path-as-is */ + config->path_as_is = toggle; break; - case '0': /* --http* options */ - switch(subletter) { - case '\0': - /* HTTP version 1.0 */ - sethttpver(global, config, CURL_HTTP_VERSION_1_0); - break; - case '1': - /* HTTP version 1.1 */ - sethttpver(global, config, CURL_HTTP_VERSION_1_1); - break; - case '2': - /* HTTP version 2.0 */ - if(!feature_http2) - return PARAM_LIBCURL_DOESNT_SUPPORT; - sethttpver(global, config, CURL_HTTP_VERSION_2_0); - break; - case '3': /* --http2-prior-knowledge */ - /* HTTP version 2.0 over clean TCP */ - if(!feature_http2) - return PARAM_LIBCURL_DOESNT_SUPPORT; - sethttpver(global, config, CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE); - break; - case '4': /* --http3 */ - /* Try HTTP/3, allow fallback */ - if(!feature_http3) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - sethttpver(global, config, CURL_HTTP_VERSION_3); - break; - case '5': /* --http3-only */ - /* Try HTTP/3 without fallback */ - if(!feature_http3) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - sethttpver(global, config, CURL_HTTP_VERSION_3ONLY); - break; - case '9': - /* Allow HTTP/0.9 responses! */ - config->http09_allowed = toggle; - break; - case 'a': - /* --proxy-http2 */ - if(!feature_httpsproxy || !feature_http2) - return PARAM_LIBCURL_DOESNT_SUPPORT; - config->proxyver = CURLPROXY_HTTPS2; - break; + case ONEOPT('$', 'O'): /* --proxy-service-name */ + err = getstr(&config->proxy_service_name, nextarg, DENY_BLANK); + break; + case ONEOPT('$', 'P'): /* --service-name */ + err = getstr(&config->service_name, nextarg, DENY_BLANK); + break; + case ONEOPT('$', 'Q'): /* --proto-default */ + err = getstr(&config->proto_default, nextarg, DENY_BLANK); + if(!err) + err = check_protocol(config->proto_default); + break; + case ONEOPT('$', 'R'): /* --expect100-timeout */ + err = secs2ms(&config->expect100timeout_ms, nextarg); + break; + case ONEOPT('$', 'S'): /* --tftp-no-options */ + config->tftp_no_options = toggle; + break; + case ONEOPT('$', 'U'): /* --connect-to */ + err = add2list(&config->connect_to, nextarg); + break; + case ONEOPT('$', 'W'): /* --abstract-unix-socket */ + config->abstract_unix_socket = TRUE; + err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); + break; + case ONEOPT('$', 'X'): /* --tls-max */ + err = str2tls_max(&config->ssl_version_max, nextarg); + break; + case ONEOPT('$', 'Y'): /* --suppress-connect-headers */ + config->suppress_connect_headers = toggle; + break; + case ONEOPT('$', 'Z'): /* --compressed-ssh */ + config->ssh_compression = toggle; + break; + case ONEOPT('$', '~'): /* --happy-eyeballs-timeout-ms */ + err = str2unum(&config->happy_eyeballs_timeout_ms, nextarg); + /* 0 is a valid value for this timeout */ + break; + case ONEOPT('$', '%'): /* --trace-ids */ + global->traceids = toggle; + break; + case ONEOPT('$', '&'): /* --trace-config */ + if(set_trace_config(global, nextarg)) { + err = PARAM_NO_MEM; } break; - case '1': /* --tlsv1* options */ - switch(subletter) { - case '\0': - /* TLS version 1.x */ - config->ssl_version = CURL_SSLVERSION_TLSv1; - break; - case '0': - /* TLS version 1.0 */ - config->ssl_version = CURL_SSLVERSION_TLSv1_0; - break; - case '1': - /* TLS version 1.1 */ - config->ssl_version = CURL_SSLVERSION_TLSv1_1; - break; - case '2': - /* TLS version 1.2 */ - config->ssl_version = CURL_SSLVERSION_TLSv1_2; - break; - case '3': - /* TLS version 1.3 */ - config->ssl_version = CURL_SSLVERSION_TLSv1_3; - break; - case 'A': /* --tls13-ciphers */ - err = getstr(&config->cipher13_list, nextarg, DENY_BLANK); + case ONEOPT('#', 'm'): /* --progress-meter */ + global->noprogress = !toggle; + break; + case ONEOPT('#', '\0'): /* --progress-bar */ + global->progressmode = toggle ? CURL_PROGRESS_BAR : CURL_PROGRESS_STATS; + break; + + case ONEOPT(':', 'a'): /* --variable */ + err = setvariable(global, nextarg); + break; + case ONEOPT(':', '\0'): /* --next */ + err = PARAM_NEXT_OPERATION; + break; + + case ONEOPT('0', '\0'): /* --http1.0 */ + /* HTTP version 1.0 */ + sethttpver(global, config, CURL_HTTP_VERSION_1_0); + break; + case ONEOPT('0', '1'): /* --http1.1 */ + /* HTTP version 1.1 */ + sethttpver(global, config, CURL_HTTP_VERSION_1_1); + break; + case ONEOPT('0', '2'): /* --http2 */ + /* HTTP version 2.0 */ + if(!feature_http2) + return PARAM_LIBCURL_DOESNT_SUPPORT; + sethttpver(global, config, CURL_HTTP_VERSION_2_0); + break; + case ONEOPT('0', '3'): /* --http2-prior-knowledge */ + /* HTTP version 2.0 over clean TCP */ + if(!feature_http2) + return PARAM_LIBCURL_DOESNT_SUPPORT; + sethttpver(global, config, CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE); + break; + case ONEOPT('0', '4'): /* --http3: */ + /* Try HTTP/3, allow fallback */ + if(!feature_http3) { + err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case 'B': /* --proxy-tls13-ciphers */ - err = getstr(&config->proxy_cipher13_list, nextarg, DENY_BLANK); + } + sethttpver(global, config, CURL_HTTP_VERSION_3); + break; + case ONEOPT('0', '5'): /* --http3-only */ + /* Try HTTP/3 without fallback */ + if(!feature_http3) { + err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } + sethttpver(global, config, CURL_HTTP_VERSION_3ONLY); + break; + case ONEOPT('0', '9'): /* --http0.9 */ + /* Allow HTTP/0.9 responses! */ + config->http09_allowed = toggle; + break; + case ONEOPT('0', 'a'): /* --proxy-http2 */ + if(!feature_httpsproxy || !feature_http2) + return PARAM_LIBCURL_DOESNT_SUPPORT; + config->proxyver = CURLPROXY_HTTPS2; + break; + case ONEOPT('1', '\0'): /* --tlsv1 */ + config->ssl_version = CURL_SSLVERSION_TLSv1; + break; + case ONEOPT('1', '0'): /* --tlsv1.0 */ + config->ssl_version = CURL_SSLVERSION_TLSv1_0; + break; + case ONEOPT('1', '1'): /* --tlsv1.1 */ + config->ssl_version = CURL_SSLVERSION_TLSv1_1; + break; + case ONEOPT('1', '2'): /* --tlsv1.2 */ + config->ssl_version = CURL_SSLVERSION_TLSv1_2; break; - case '2': - /* SSL version 2 */ + case ONEOPT('1', '3'): /* --tlsv1.3 */ + config->ssl_version = CURL_SSLVERSION_TLSv1_3; + break; + case ONEOPT('1', 'A'): /* --tls13-ciphers */ + err = getstr(&config->cipher13_list, nextarg, DENY_BLANK); + break; + case ONEOPT('1', 'B'): /* --proxy-tls13-ciphers */ + err = getstr(&config->proxy_cipher13_list, nextarg, DENY_BLANK); + break; + case ONEOPT('2', '\0'): /* --sslv2 */ warnf(global, "Ignores instruction to use SSLv2"); break; - case '3': - /* SSL version 3 */ + case ONEOPT('3', '\0'): /* --sslv3 */ warnf(global, "Ignores instruction to use SSLv3"); break; - case '4': - /* IPv4 */ + case ONEOPT('4', '\0'): /* --ipv4 */ config->ip_version = CURL_IPRESOLVE_V4; break; - case '6': - /* IPv6 */ + case ONEOPT('6', '\0'): /* --ipv6 */ config->ip_version = CURL_IPRESOLVE_V6; break; - case 'a': + case ONEOPT('a', '\0'): /* --append */ /* This makes the FTP sessions use APPE instead of STOR */ config->ftp_append = toggle; break; - case 'A': - /* This specifies the User-Agent name */ + case ONEOPT('A', '\0'): /* --user-agent */ err = getstr(&config->useragent, nextarg, ALLOW_BLANK); break; - case 'b': - switch(subletter) { - case 'a': /* --alt-svc */ - if(!feature_altsvc) - err = PARAM_LIBCURL_DOESNT_SUPPORT; - else - err = getstr(&config->altsvc, nextarg, ALLOW_BLANK); - break; - case 'b': /* --hsts */ - if(!feature_hsts) - err = PARAM_LIBCURL_DOESNT_SUPPORT; - else - err = getstr(&config->hsts, nextarg, ALLOW_BLANK); + case ONEOPT('b', 'a'): /* --alt-svc */ + if(!feature_altsvc) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else + err = getstr(&config->altsvc, nextarg, ALLOW_BLANK); + break; + case ONEOPT('b', 'b'): /* --hsts */ + if(!feature_hsts) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else + err = getstr(&config->hsts, nextarg, ALLOW_BLANK); + break; + case ONEOPT('b', '\0'): /* --cookie */ + if(nextarg[0] == '@') { + nextarg++; + } + else if(strchr(nextarg, '=')) { + /* A cookie string must have a =-letter */ + err = add2list(&config->cookies, nextarg); break; - default: /* --cookie string coming up: */ - if(nextarg[0] == '@') { - nextarg++; - } - else if(strchr(nextarg, '=')) { - /* A cookie string must have a =-letter */ - err = add2list(&config->cookies, nextarg); - break; - } - /* We have a cookie file to read from! */ - err = add2list(&config->cookiefiles, nextarg); } + /* We have a cookie file to read from! */ + err = add2list(&config->cookiefiles, nextarg); break; - case 'B': - /* use ASCII/text when transferring */ + case ONEOPT('B', '\0'): /* --use-ascii */ config->use_ascii = toggle; break; - case 'c': - /* get the file name to dump all cookies in */ + case ONEOPT('c', '\0'): /* --cookie-jar */ err = getstr(&config->cookiejar, nextarg, DENY_BLANK); break; - case 'C': + case ONEOPT('C', '\0'): /* --continue-at */ /* This makes us continue an ftp transfer at given position */ if(strcmp(nextarg, "-")) { err = str2offset(&config->resume_from, nextarg); @@ -1722,7 +1668,13 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } config->use_resume = TRUE; break; - case 'd': + case ONEOPT('d', '\0'): /* --data */ + case ONEOPT('d', 'a'): /* --data-ascii */ + case ONEOPT('d', 'b'): /* --data-binary */ + case ONEOPT('d', 'e'): /* --data-urlencode */ + case ONEOPT('d', 'f'): /* --json */ + case ONEOPT('d', 'g'): /* --url-query */ + case ONEOPT('d', 'r'): /* --data-raw */ /* postfield data */ { char *postdata = NULL; @@ -1865,17 +1817,15 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ a simple GET if -G is used. Already or soon. if(SetHTTPrequest(HTTPREQ_SIMPLEPOST, &config->httpreq)) { - Curl_safefree(postdata); - return PARAM_BAD_USE; + Curl_safefree(postdata); + return PARAM_BAD_USE; } */ break; - case 'D': - /* dump-header to given file name */ + case ONEOPT('D', '\0'): /* --dump-header */ err = getstr(&config->headerfile, nextarg, DENY_BLANK); break; - case 'e': - { + case ONEOPT('e', '\0'): { /* --referer */ char *ptr = strstr(nextarg, ";auto"); if(ptr) { /* Automatic referer requested, this may be combined with a @@ -1888,284 +1838,271 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ ptr = *nextarg ? nextarg : NULL; err = getstr(&config->referer, ptr, ALLOW_BLANK); } - break; - case 'E': - switch(subletter) { - case '\0': /* certificate file */ - cleanarg(clearthis); - GetFileAndPassword(nextarg, &config->cert, &config->key_passwd); - break; - case 'a': /* --cacert CA info PEM file */ - err = getstr(&config->cacert, nextarg, DENY_BLANK); - break; - case 'G': /* --ca-native */ - config->native_ca_store = toggle; - break; - case 'H': /* --proxy-ca-native */ - config->proxy_native_ca_store = toggle; - break; - case 'b': /* cert file type */ - err = getstr(&config->cert_type, nextarg, DENY_BLANK); - break; - case 'c': /* private key file */ - err = getstr(&config->key, nextarg, DENY_BLANK); - break; - case 'd': /* private key file type */ - err = getstr(&config->key_type, nextarg, DENY_BLANK); - break; - case 'e': /* private key passphrase */ - err = getstr(&config->key_passwd, nextarg, DENY_BLANK); - cleanarg(clearthis); - break; - case 'f': /* crypto engine */ - err = getstr(&config->engine, nextarg, DENY_BLANK); - if(!err && - config->engine && !strcmp(config->engine, "list")) { - err = PARAM_ENGINES_REQUESTED; - } - break; - case 'g': /* CA cert directory */ - err = getstr(&config->capath, nextarg, DENY_BLANK); - break; - case 'h': /* --pubkey public key file */ - err = getstr(&config->pubkey, nextarg, DENY_BLANK); - break; - case 'i': /* --hostpubmd5 md5 of the host public key */ - err = getstr(&config->hostpubmd5, nextarg, DENY_BLANK); - if(!err) { - if(!config->hostpubmd5 || strlen(config->hostpubmd5) != 32) - err = PARAM_BAD_USE; - } - break; - case 'F': /* --hostpubsha256 sha256 of the host public key */ - err = getstr(&config->hostpubsha256, nextarg, DENY_BLANK); - break; - case 'j': /* CRL file */ - err = getstr(&config->crlfile, nextarg, DENY_BLANK); - break; - case 'k': /* TLS username */ - if(!feature_tls_srp) { - cleanarg(clearthis); - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + break; + case ONEOPT('E', '\0'): /* --cert */ + cleanarg(clearthis); + GetFileAndPassword(nextarg, &config->cert, &config->key_passwd); + break; + case ONEOPT('E', 'a'): /* --cacert */ + err = getstr(&config->cacert, nextarg, DENY_BLANK); + break; + case ONEOPT('E', 'G'): /* --ca-native */ + config->native_ca_store = toggle; + break; + case ONEOPT('E', 'H'): /* --proxy-ca-native */ + config->proxy_native_ca_store = toggle; + break; + case ONEOPT('E', 'b'): /* --cert-type */ + err = getstr(&config->cert_type, nextarg, DENY_BLANK); + break; + case ONEOPT('E', 'c'): /* --key */ + err = getstr(&config->key, nextarg, DENY_BLANK); + break; + case ONEOPT('E', 'd'): /* --key-type */ + err = getstr(&config->key_type, nextarg, DENY_BLANK); + break; + case ONEOPT('E', 'e'): /* --pass */ + err = getstr(&config->key_passwd, nextarg, DENY_BLANK); + cleanarg(clearthis); + break; + case ONEOPT('E', 'f'): /* --engine */ + err = getstr(&config->engine, nextarg, DENY_BLANK); + if(!err && + config->engine && !strcmp(config->engine, "list")) { + err = PARAM_ENGINES_REQUESTED; + } + break; + case ONEOPT('E', 'g'): /* --capath */ + err = getstr(&config->capath, nextarg, DENY_BLANK); + break; + case ONEOPT('E', 'h'): /* --pubkey */ + err = getstr(&config->pubkey, nextarg, DENY_BLANK); + break; + case ONEOPT('E', 'i'): /* --hostpubmd5 */ + err = getstr(&config->hostpubmd5, nextarg, DENY_BLANK); + if(!err) { + if(!config->hostpubmd5 || strlen(config->hostpubmd5) != 32) + err = PARAM_BAD_USE; + } + break; + case ONEOPT('E', 'F'): /* --hostpubsha256 */ + err = getstr(&config->hostpubsha256, nextarg, DENY_BLANK); + break; + case ONEOPT('E', 'j'): /* --crlfile */ + err = getstr(&config->crlfile, nextarg, DENY_BLANK); + break; + case ONEOPT('E', 'k'): /* --tlsuser */ + if(!feature_tls_srp) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else err = getstr(&config->tls_username, nextarg, DENY_BLANK); - cleanarg(clearthis); - break; - case 'l': /* TLS password */ - if(!feature_tls_srp) { - cleanarg(clearthis); - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + cleanarg(clearthis); + break; + case ONEOPT('E', 'l'): /* --tlspassword */ + if(!feature_tls_srp) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else err = getstr(&config->tls_password, nextarg, ALLOW_BLANK); - cleanarg(clearthis); - break; - case 'm': /* TLS authentication type */ - if(!feature_tls_srp) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + cleanarg(clearthis); + break; + case ONEOPT('E', 'm'): /* --tlsauthtype */ + if(!feature_tls_srp) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else { err = getstr(&config->tls_authtype, nextarg, DENY_BLANK); if(!err && strcmp(config->tls_authtype, "SRP")) err = PARAM_LIBCURL_DOESNT_SUPPORT; /* only support TLS-SRP */ - break; - case 'n': /* no empty SSL fragments, --ssl-allow-beast */ - if(feature_ssl) - config->ssl_allow_beast = toggle; - break; + } + break; + case ONEOPT('E', 'n'): /* --ssl-allow-beast */ + if(feature_ssl) + config->ssl_allow_beast = toggle; + break; - case 'o': /* --ssl-auto-client-cert */ - if(feature_ssl) - config->ssl_auto_client_cert = toggle; - break; + case ONEOPT('E', 'o'): /* --ssl-auto-client-cert */ + if(feature_ssl) + config->ssl_auto_client_cert = toggle; + break; - case 'O': /* --proxy-ssl-auto-client-cert */ - if(feature_ssl) - config->proxy_ssl_auto_client_cert = toggle; - break; + case ONEOPT('E', 'O'): /* --proxy-ssl-auto-client-cert */ + if(feature_ssl) + config->proxy_ssl_auto_client_cert = toggle; + break; - case 'p': /* Pinned public key DER file */ - err = getstr(&config->pinnedpubkey, nextarg, DENY_BLANK); - break; + case ONEOPT('E', 'p'): /* --pinnedpubkey */ + err = getstr(&config->pinnedpubkey, nextarg, DENY_BLANK); + break; - case 'P': /* proxy pinned public key */ - err = getstr(&config->proxy_pinnedpubkey, nextarg, DENY_BLANK); - break; + case ONEOPT('E', 'P'): /* --proxy-pinnedpubkey */ + err = getstr(&config->proxy_pinnedpubkey, nextarg, DENY_BLANK); + break; - case 'q': /* --cert-status */ - config->verifystatus = TRUE; - break; + case ONEOPT('E', 'q'): /* --cert-status */ + config->verifystatus = TRUE; + break; - case 'Q': /* --doh-cert-status */ - config->doh_verifystatus = TRUE; - break; + case ONEOPT('E', 'Q'): /* --doh-cert-status */ + config->doh_verifystatus = TRUE; + break; - case 'r': /* --false-start */ - config->falsestart = TRUE; - break; + case ONEOPT('E', 'r'): /* --false-start */ + config->falsestart = TRUE; + break; - case 's': /* --ssl-no-revoke */ - if(feature_ssl) - config->ssl_no_revoke = TRUE; - break; + case ONEOPT('E', 's'): /* --ssl-no-revoke */ + if(feature_ssl) + config->ssl_no_revoke = TRUE; + break; - case 'S': /* --ssl-revoke-best-effort */ - if(feature_ssl) - config->ssl_revoke_best_effort = TRUE; - break; + case ONEOPT('E', 'S'): /* --ssl-revoke-best-effort */ + if(feature_ssl) + config->ssl_revoke_best_effort = TRUE; + break; - case 't': /* --tcp-fastopen */ - config->tcp_fastopen = TRUE; - break; + case ONEOPT('E', 't'): /* --tcp-fastopen */ + config->tcp_fastopen = TRUE; + break; - case 'u': /* TLS username for proxy */ - cleanarg(clearthis); - if(!feature_tls_srp) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + case ONEOPT('E', 'u'): /* --proxy-tlsuser */ + cleanarg(clearthis); + if(!feature_tls_srp) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else err = getstr(&config->proxy_tls_username, nextarg, ALLOW_BLANK); - break; + break; - case 'v': /* TLS password for proxy */ - cleanarg(clearthis); - if(!feature_tls_srp) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + case ONEOPT('E', 'v'): /* --proxy-tlspassword */ + cleanarg(clearthis); + if(!feature_tls_srp) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else err = getstr(&config->proxy_tls_password, nextarg, DENY_BLANK); - break; + break; - case 'w': /* TLS authentication type for proxy */ - if(!feature_tls_srp) { - err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } + case ONEOPT('E', 'w'): /* --proxy-tlsauthtype */ + if(!feature_tls_srp) + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else { err = getstr(&config->proxy_tls_authtype, nextarg, DENY_BLANK); if(!err && strcmp(config->proxy_tls_authtype, "SRP")) err = PARAM_LIBCURL_DOESNT_SUPPORT; /* only support TLS-SRP */ - break; + } + break; - case 'x': /* certificate file for proxy */ - cleanarg(clearthis); - GetFileAndPassword(nextarg, &config->proxy_cert, - &config->proxy_key_passwd); - break; + case ONEOPT('E', 'x'): /* --proxy-cert */ + cleanarg(clearthis); + GetFileAndPassword(nextarg, &config->proxy_cert, + &config->proxy_key_passwd); + break; - case 'y': /* cert file type for proxy */ - err = getstr(&config->proxy_cert_type, nextarg, DENY_BLANK); - break; + case ONEOPT('E', 'y'): /* --proxy-cert-type */ + err = getstr(&config->proxy_cert_type, nextarg, DENY_BLANK); + break; - case 'z': /* private key file for proxy */ - err = getstr(&config->proxy_key, nextarg, ALLOW_BLANK); - break; + case ONEOPT('E', 'z'): /* --proxy-key */ + err = getstr(&config->proxy_key, nextarg, ALLOW_BLANK); + break; - case '0': /* private key file type for proxy */ - err = getstr(&config->proxy_key_type, nextarg, DENY_BLANK); - break; + case ONEOPT('E', '0'): /* --proxy-key-type */ + err = getstr(&config->proxy_key_type, nextarg, DENY_BLANK); + break; - case '1': /* private key passphrase for proxy */ - err = getstr(&config->proxy_key_passwd, nextarg, ALLOW_BLANK); - cleanarg(clearthis); - break; + case ONEOPT('E', '1'): /* --proxy-pass */ + err = getstr(&config->proxy_key_passwd, nextarg, ALLOW_BLANK); + cleanarg(clearthis); + break; - case '2': /* ciphers for proxy */ - err = getstr(&config->proxy_cipher_list, nextarg, DENY_BLANK); - break; + case ONEOPT('E', '2'): /* --proxy-ciphers */ + err = getstr(&config->proxy_cipher_list, nextarg, DENY_BLANK); + break; - case '3': /* CRL file for proxy */ - err = getstr(&config->proxy_crlfile, nextarg, DENY_BLANK); - break; + case ONEOPT('E', '3'): /* --proxy-crlfile */ + err = getstr(&config->proxy_crlfile, nextarg, DENY_BLANK); + break; - case '4': /* no empty SSL fragments for proxy */ - if(feature_ssl) - config->proxy_ssl_allow_beast = toggle; - break; + case ONEOPT('E', '4'): /* --proxy-allow-beast */ + if(feature_ssl) + config->proxy_ssl_allow_beast = toggle; + break; - case '5': /* --login-options */ - err = getstr(&config->login_options, nextarg, ALLOW_BLANK); - break; + case ONEOPT('E', '5'): /* --login-options */ + err = getstr(&config->login_options, nextarg, ALLOW_BLANK); + break; - case '6': /* CA info PEM file for proxy */ - err = getstr(&config->proxy_cacert, nextarg, DENY_BLANK); - break; + case ONEOPT('E', '6'): /* --proxy-cacert */ + err = getstr(&config->proxy_cacert, nextarg, DENY_BLANK); + break; - case '7': /* CA cert directory for proxy */ - err = getstr(&config->proxy_capath, nextarg, DENY_BLANK); - break; + case ONEOPT('E', '7'): /* --proxy-cainfo */ + err = getstr(&config->proxy_capath, nextarg, DENY_BLANK); + break; - case '8': /* allow insecure SSL connects for proxy */ - config->proxy_insecure_ok = toggle; - break; + case ONEOPT('E', '8'): /* --proxy-insecure */ + config->proxy_insecure_ok = toggle; + break; - case '9': /* --proxy-tlsv1 */ - /* TLS version 1 for proxy */ - config->proxy_ssl_version = CURL_SSLVERSION_TLSv1; - break; + case ONEOPT('E', '9'): /* --proxy-tlsv1 */ + /* TLS version 1 for proxy */ + config->proxy_ssl_version = CURL_SSLVERSION_TLSv1; + break; - case 'A': - /* --socks5-basic */ - if(toggle) - config->socks5_auth |= CURLAUTH_BASIC; - else - config->socks5_auth &= ~CURLAUTH_BASIC; - break; + case ONEOPT('E', 'A'): /* --socks5-basic */ + if(toggle) + config->socks5_auth |= CURLAUTH_BASIC; + else + config->socks5_auth &= ~CURLAUTH_BASIC; + break; - case 'B': - /* --socks5-gssapi */ - if(toggle) - config->socks5_auth |= CURLAUTH_GSSAPI; - else - config->socks5_auth &= ~CURLAUTH_GSSAPI; - break; + case ONEOPT('E', 'B'): /* --socks5-gssapi */ + if(toggle) + config->socks5_auth |= CURLAUTH_GSSAPI; + else + config->socks5_auth &= ~CURLAUTH_GSSAPI; + break; - case 'C': - err = getstr(&config->etag_save_file, nextarg, DENY_BLANK); - break; + case ONEOPT('E', 'C'): /* --etag-save */ + err = getstr(&config->etag_save_file, nextarg, DENY_BLANK); + break; - case 'D': - err = getstr(&config->etag_compare_file, nextarg, DENY_BLANK); - break; + case ONEOPT('E', 'D'): /* --etag-compare */ + err = getstr(&config->etag_compare_file, nextarg, DENY_BLANK); + break; - case 'E': - err = getstr(&config->ssl_ec_curves, nextarg, DENY_BLANK); - break; + case ONEOPT('E', 'E'): /* --curves */ + err = getstr(&config->ssl_ec_curves, nextarg, DENY_BLANK); + break; - default: /* unknown flag */ - err = PARAM_OPTION_UNKNOWN; - break; - } + case ONEOPT('f', 'a'): /* --fail-early */ + global->fail_early = toggle; break; - case 'f': - switch(subletter) { - case 'a': /* --fail-early */ - global->fail_early = toggle; - break; - case 'b': /* --styled-output */ - global->styled_output = toggle; - break; - case 'c': /* --mail-rcpt-allowfails */ - config->mail_rcpt_allowfails = toggle; - break; - case 'd': /* --fail-with-body */ - config->failwithbody = toggle; - break; - case 'e': /* --remove-on-error */ - config->rm_partial = toggle; - break; - default: /* --fail (hard on errors) */ - config->failonerror = toggle; - break; + case ONEOPT('f', 'b'): /* --styled-output */ + global->styled_output = toggle; + break; + case ONEOPT('f', 'c'): /* --mail-rcpt-allowfails */ + config->mail_rcpt_allowfails = toggle; + break; + case ONEOPT('f', 'd'): /* --fail-with-body */ + config->failwithbody = toggle; + if(config->failonerror && config->failwithbody) { + errorf(config->global, "You must select either --fail or " + "--fail-with-body, not both."); + err = PARAM_BAD_USE; } + break; + case ONEOPT('f', 'e'): /* --remove-on-error */ + config->rm_partial = toggle; + break; + case ONEOPT('f', '\0'): /* --fail */ + config->failonerror = toggle; if(config->failonerror && config->failwithbody) { errorf(config->global, "You must select either --fail or " "--fail-with-body, not both."); err = PARAM_BAD_USE; - break; } break; - case 'F': + + case ONEOPT('F', '\0'): /* --form */ + case ONEOPT('F', 's'): /* --form-string */ /* "form data" simulation, this is a little advanced so lets do our best to sort this out slowly and carefully */ if(formparse(config, @@ -2175,27 +2112,24 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ (subletter == 's')?TRUE:FALSE)) { /* 's' is literal string */ err = PARAM_BAD_USE; - break; } - if(SetHTTPrequest(config, HTTPREQ_MIMEPOST, &config->httpreq)) { + else if(SetHTTPrequest(config, HTTPREQ_MIMEPOST, &config->httpreq)) err = PARAM_BAD_USE; - break; - } break; - case 'g': /* g disables URLglobbing */ + case ONEOPT('g', '\0'): /* --globoff */ config->globoff = toggle; break; - case 'G': /* HTTP GET */ - if(subletter == 'a') { /* --request-target */ - err = getstr(&config->request_target, nextarg, DENY_BLANK); - } - else - config->use_httpget = toggle; + case ONEOPT('G', '\0'): /* --get */ + config->use_httpget = toggle; + break; + + case ONEOPT('G', 'a'): /* --request-target */ + err = getstr(&config->request_target, nextarg, DENY_BLANK); break; - case 'h': /* h for help */ + case ONEOPT('h', '\0'): /* --help */ if(toggle) { if(*nextarg) { global->help_category = strdup(nextarg); @@ -2205,11 +2139,11 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } } err = PARAM_HELP_REQUESTED; - break; } /* we now actually support --no-help too! */ break; - case 'H': + case ONEOPT('H', '\0'): /* --header */ + case ONEOPT('H', 'p'): /* --proxy-header */ /* A custom header to append to a list */ if(nextarg[0] == '@') { /* read many headers from a file or stdin */ @@ -2252,101 +2186,93 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = add2list(&config->headers, nextarg); } break; - case 'i': + case ONEOPT('i', '\0'): /* --include */ config->show_headers = toggle; /* show the headers as well in the general output stream */ break; - case 'j': + case ONEOPT('j', '\0'): /* --junk-session-cookies */ config->cookiesession = toggle; break; - case 'I': /* --head */ + case ONEOPT('I', '\0'): /* --head */ config->no_body = toggle; config->show_headers = toggle; if(SetHTTPrequest(config, (config->no_body)?HTTPREQ_HEAD:HTTPREQ_GET, - &config->httpreq)) { + &config->httpreq)) err = PARAM_BAD_USE; - break; - } break; - case 'J': /* --remote-header-name */ + case ONEOPT('J', '\0'): /* --remote-header-name */ config->content_disposition = toggle; break; - case 'k': /* allow insecure SSL connects */ - if(subletter == 'd') /* --doh-insecure */ - config->doh_insecure_ok = toggle; - else - config->insecure_ok = toggle; + case ONEOPT('k', '\0'): /* --insecure */ + config->insecure_ok = toggle; break; - case 'K': /* parse config file */ + case ONEOPT('k', 'd'): /* --doh-insecure */ + config->doh_insecure_ok = toggle; + break; + case ONEOPT('K', '\0'): /* --config */ if(parseconfig(nextarg, global)) { errorf(global, "cannot read config from '%s'", nextarg); err = PARAM_READ_ERROR; - break; } break; - case 'l': + case ONEOPT('l', '\0'): /* --list-only */ config->dirlistonly = toggle; /* only list the names of the FTP dir */ break; - case 'L': + case ONEOPT('L', '\0'): /* --location */ + case ONEOPT('L', 't'): /* --location-trusted */ config->followlocation = toggle; /* Follow Location: HTTP headers */ - switch(subletter) { - case 't': + if(subletter == 't') /* Continue to send authentication (user+password) when following * locations, even when hostname changed */ config->unrestricted_auth = toggle; - break; - } break; - case 'm': + case ONEOPT('m', '\0'): /* --max-time */ /* specified max time */ err = secs2ms(&config->timeout_ms, nextarg); break; - case 'M': /* M for manual, huge help */ + case ONEOPT('M', '\0'): /* --manual */ if(toggle) { /* --no-manual shows no manual... */ #ifndef USE_MANUAL warnf(global, "built-in manual was disabled at build-time"); #endif err = PARAM_MANUAL_REQUESTED; - break; } break; - case 'n': - switch(subletter) { - case 'o': /* use .netrc or URL */ - config->netrc_opt = toggle; - break; - case 'e': /* netrc-file */ - err = getstr(&config->netrc_file, nextarg, DENY_BLANK); - break; - default: - /* pick info from .netrc, if this is used for http, curl will - automatically enforce user+password with the request */ - config->netrc = toggle; - break; - } + + case ONEOPT('n', 'o'): /* --netrc-optional */ + config->netrc_opt = toggle; + break; + case ONEOPT('n', 'e'): /* --netrc-file */ + err = getstr(&config->netrc_file, nextarg, DENY_BLANK); break; - case 'N': + case ONEOPT('n', '\0'): /* --netrc */ + /* pick info from .netrc, if this is used for http, curl will + automatically enforce user+password with the request */ + config->netrc = toggle; + break; + + case ONEOPT('N', '\0'): /* --buffer */ /* disable the output I/O buffering. note that the option is called --buffer but is mostly used in the negative form: --no-buffer */ config->nobuffer = longopt ? !toggle : TRUE; break; - case 'O': /* --remote-name */ - if(subletter == 'a') { /* --remote-name-all */ - config->default_node_flags = toggle?GETOUT_USEREMOTE:0; - break; - } - else if(subletter == 'b') { /* --output-dir */ - err = getstr(&config->output_dir, nextarg, DENY_BLANK); - break; - } - else if(subletter == 'c') { /* --clobber / --no-clobber */ - config->file_clobber_mode = toggle ? CLOBBER_ALWAYS : CLOBBER_NEVER; - break; - } - FALLTHROUGH(); - case 'o': /* --output */ + + case ONEOPT('O', 'a'): /* --remote-name-all */ + config->default_node_flags = toggle?GETOUT_USEREMOTE:0; + break; + + case ONEOPT('O', 'b'): /* --output-dir */ + err = getstr(&config->output_dir, nextarg, DENY_BLANK); + break; + + case ONEOPT('O', 'c'): /* --clobber */ + config->file_clobber_mode = toggle ? CLOBBER_ALWAYS : CLOBBER_NEVER; + break; + + case ONEOPT('o', '\0'): /* --output */ + case ONEOPT('O', '\0'): /* --remote-name */ /* output file */ if(!config->url_out) config->url_out = config->url_list; @@ -2388,7 +2314,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } url->flags |= GETOUT_OUTFILE; break; - case 'P': + case ONEOPT('P', '\0'): /* --ftp-port */ /* This makes the FTP sessions use PORT instead of PASV */ /* use or <192.168.10.10> style addresses. Anything except this will make us try to get the "default" address. @@ -2396,15 +2322,16 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ */ err = getstr(&config->ftpport, nextarg, DENY_BLANK); break; - case 'p': + case ONEOPT('p', '\0'): /* --proxytunnel */ /* proxy tunnel for non-http protocols */ config->proxytunnel = toggle; break; - case 'q': /* if used first, already taken care of, we do it like - this so we don't cause an error! */ + case ONEOPT('q', '\0'): /* --disable */ + /* if used first, already taken care of, we do it like this so we don't + cause an error! */ break; - case 'Q': + case ONEOPT('Q', '\0'): /* --quote */ /* QUOTE command to send to FTP server */ switch(nextarg[0]) { case '-': @@ -2422,15 +2349,14 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; } break; - case 'r': + case ONEOPT('r', '\0'): /* --range */ /* Specifying a range WITHOUT A DASH will create an illegal HTTP range (and won't actually be range by definition). The man page previously claimed that to be a good way, why this code is added to work-around it. */ if(ISDIGIT(*nextarg) && !strchr(nextarg, '-')) { char buffer[32]; - curl_off_t off; - if(curlx_strtoofft(nextarg, NULL, 10, &off)) { + if(curlx_strtoofft(nextarg, NULL, 10, &value)) { warnf(global, "unsupported range point"); err = PARAM_BAD_USE; break; @@ -2438,7 +2364,8 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ warnf(global, "A specified range MUST include at least one dash (-). " "Appending one for you"); - msnprintf(buffer, sizeof(buffer), "%" CURL_FORMAT_CURL_OFF_T "-", off); + msnprintf(buffer, sizeof(buffer), "%" CURL_FORMAT_CURL_OFF_T "-", + value); Curl_safefree(config->range); config->range = strdup(buffer); if(!config->range) { @@ -2462,21 +2389,21 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = getstr(&config->range, nextarg, DENY_BLANK); } break; - case 'R': + case ONEOPT('R', '\0'): /* --remote-time */ /* use remote file's time */ config->remote_time = toggle; break; - case 's': /* --silent */ + case ONEOPT('s', '\0'): /* --silent */ global->silent = toggle; break; - case 'S': /* --show-error */ + case ONEOPT('S', '\0'): /* --show-error */ global->showerror = toggle; break; - case 't': + case ONEOPT('t', '\0'): /* --telnet-option */ /* Telnet options */ err = add2list(&config->telnet_options, nextarg); break; - case 'T': + case ONEOPT('T', '\0'): /* --upload */ /* we are uploading */ if(!config->url_ul) config->url_ul = config->url_list; @@ -2509,17 +2436,17 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = getstr(&url->infile, nextarg, DENY_BLANK); } break; - case 'u': + case ONEOPT('u', '\0'): /* --user */ /* user:password */ err = getstr(&config->userpwd, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; - case 'U': + case ONEOPT('U', '\0'): /* --proxy-user */ /* Proxy user:password */ err = getstr(&config->proxyuserpwd, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; - case 'v': + case ONEOPT('v', '\0'): /* --verbose */ if(toggle) { /* the '%' thing here will cause the trace get sent to stderr */ Curl_safefree(global->trace_dump); @@ -2537,14 +2464,12 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ /* verbose is disabled here */ global->tracetype = TRACE_NONE; break; - case 'V': - if(toggle) { /* --no-version yields no output! */ + case ONEOPT('V', '\0'): /* --version */ + if(toggle) /* --no-version yields no output! */ err = PARAM_VERSION_INFO_REQUESTED; - break; - } break; - case 'w': + case ONEOPT('w', '\0'): /* --write-out */ /* get the output string */ if('@' == *nextarg) { /* the data begins with a '@' letter, it means that a file name @@ -2577,63 +2502,53 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ else err = getstr(&config->writeout, nextarg, DENY_BLANK); break; - case 'x': - switch(subletter) { - case 'a': /* --preproxy */ - err = getstr(&config->preproxy, nextarg, DENY_BLANK); - break; - default: - /* --proxy */ - err = getstr(&config->proxy, nextarg, ALLOW_BLANK); - if(config->proxyver != CURLPROXY_HTTPS2) - config->proxyver = CURLPROXY_HTTP; - break; - } + case ONEOPT('x', 'a'): /* --preproxy */ + err = getstr(&config->preproxy, nextarg, DENY_BLANK); + break; + case ONEOPT('x', '\0'): /* --proxy */ + /* --proxy */ + err = getstr(&config->proxy, nextarg, ALLOW_BLANK); + if(config->proxyver != CURLPROXY_HTTPS2) + config->proxyver = CURLPROXY_HTTP; break; - case 'X': + + case ONEOPT('X', '\0'): /* --request */ /* set custom request */ err = getstr(&config->customrequest, nextarg, DENY_BLANK); break; - case 'y': + case ONEOPT('y', '\0'): /* --speed-limit */ /* low speed time */ err = str2unum(&config->low_speed_time, nextarg); - if(err) - break; - if(!config->low_speed_limit) + if(!err && !config->low_speed_limit) config->low_speed_limit = 1; break; - case 'Y': + case ONEOPT('Y', '\0'): /* --speed-time */ /* low speed limit */ err = str2unum(&config->low_speed_limit, nextarg); - if(err) - break; - if(!config->low_speed_time) + if(!err && !config->low_speed_time) config->low_speed_time = 30; break; - case 'Z': - switch(subletter) { - case '\0': /* --parallel */ - global->parallel = toggle; - break; - case 'b': { /* --parallel-max */ - long val; - err = str2unum(&val, nextarg); - if(err) - break; - if(val > MAX_PARALLEL) - global->parallel_max = MAX_PARALLEL; - else if(val < 1) - global->parallel_max = PARALLEL_DEFAULT; - else - global->parallel_max = (unsigned short)val; - break; - } - case 'c': /* --parallel-immediate */ - global->parallel_connect = toggle; + case ONEOPT('Z', '\0'): /* --parallel */ + global->parallel = toggle; + break; + case ONEOPT('Z', 'b'): { /* --parallel-max */ + long val; + err = str2unum(&val, nextarg); + if(err) break; - } + if(val > MAX_PARALLEL) + global->parallel_max = MAX_PARALLEL; + else if(val < 1) + global->parallel_max = PARALLEL_DEFAULT; + else + global->parallel_max = (unsigned short)val; + break; + } + case ONEOPT('Z', 'c'): /* --parallel-immediate */ + global->parallel_connect = toggle; break; - case 'z': /* time condition coming up */ + + case ONEOPT('z', '\0'): /* --time-cond */ switch(*nextarg) { case '+': nextarg++; @@ -2657,11 +2572,10 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->condtime = (curl_off_t)curl_getdate(nextarg, &now); if(-1 == config->condtime) { /* now let's see if it is a file name to get the time from instead! */ - curl_off_t filetime; - rc = getfiletime(nextarg, global, &filetime); + rc = getfiletime(nextarg, global, &value); if(!rc) /* pull the time out from the file */ - config->condtime = filetime; + config->condtime = value; else { /* failed, remove time condition */ config->timecond = CURL_TIMECOND_NONE; From 8aecfad9e6c88447ca094dea1ac644f662f39d91 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 130/509] tool_getparam: move the --data logic into set_data() --- src/tool_getparam.c | 302 +++++++++++++++++++++++--------------------- 1 file changed, 156 insertions(+), 146 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index e23f020be12..0b58475c05d 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -760,6 +760,161 @@ static const struct LongShort *single(char letter) return singles[letter - ' ']; } +static ParameterError set_data(char subletter, + char *nextarg, + struct GlobalConfig *global, + struct OperationConfig *config) +{ + char *postdata = NULL; + FILE *file; + size_t size = 0; + ParameterError err = PARAM_OK; + + if(subletter == 'g') { /* --url-query */ +#define MAX_QUERY_LEN 100000 /* larger is not likely to ever work */ + char *query; + struct curlx_dynbuf dyn; + curlx_dyn_init(&dyn, MAX_QUERY_LEN); + + if(*nextarg == '+') { + /* use without encoding */ + query = strdup(&nextarg[1]); + if(!query) { + err = PARAM_NO_MEM; + goto done; + } + } + else { + err = data_urlencode(global, nextarg, &query, &size); + if(err) + goto done; + } + + if(config->query) { + CURLcode result = + curlx_dyn_addf(&dyn, "%s&%s", config->query, query); + free(query); + if(result) { + err = PARAM_NO_MEM; + goto done; + } + free(config->query); + config->query = curlx_dyn_ptr(&dyn); + } + else + config->query = query; + + goto done; /* this is not a POST argument at all */ + } + else if(subletter == 'e') { /* --data-urlencode */ + err = data_urlencode(global, nextarg, &postdata, &size); + if(err) + goto done; + } + else if('@' == *nextarg && (subletter != 'r')) { + /* the data begins with a '@' letter, it means that a file name + or - (stdin) follows */ + nextarg++; /* pass the @ */ + + if(!strcmp("-", nextarg)) { + file = stdin; + if(subletter == 'b') /* forced data-binary */ + set_binmode(stdin); + } + else { + file = fopen(nextarg, "rb"); + if(!file) { + errorf(global, "Failed to open %s", nextarg); + err = PARAM_READ_ERROR; + goto done; + } + } + + if((subletter == 'b') || /* --data-binary */ + (subletter == 'f') /* --json */) + /* forced binary */ + err = file2memory(&postdata, &size, file); + else { + err = file2string(&postdata, file); + if(postdata) + size = strlen(postdata); + } + + if(file && (file != stdin)) + fclose(file); + if(err) + goto done; + + if(!postdata) { + /* no data from the file, point to a zero byte string to make this + get sent as a POST anyway */ + postdata = strdup(""); + if(!postdata) { + err = PARAM_NO_MEM; + goto done; + } + } + } + else { + err = getstr(&postdata, nextarg, ALLOW_BLANK); + if(err) + goto done; + if(postdata) + size = strlen(postdata); + } + if(subletter == 'f') + config->jsoned = TRUE; + + if(config->postfields) { + /* we already have a string, we append this one with a separating + &-letter */ + char *oldpost = config->postfields; + curl_off_t oldlen = config->postfieldsize; + curl_off_t newlen = oldlen + curlx_uztoso(size) + 2; + config->postfields = malloc((size_t)newlen); + if(!config->postfields) { + Curl_safefree(oldpost); + Curl_safefree(postdata); + err = PARAM_NO_MEM; + goto done; + } + memcpy(config->postfields, oldpost, (size_t)oldlen); + if(subletter != 'f') { + /* skip this treatment for --json */ + /* use byte value 0x26 for '&' to accommodate non-ASCII platforms */ + config->postfields[oldlen] = '\x26'; + memcpy(&config->postfields[oldlen + 1], postdata, size); + config->postfields[oldlen + 1 + size] = '\0'; + config->postfieldsize += size + 1; + } + else { + memcpy(&config->postfields[oldlen], postdata, size); + config->postfields[oldlen + size] = '\0'; + config->postfieldsize += size; + } + Curl_safefree(oldpost); + Curl_safefree(postdata); + } + else { + config->postfields = postdata; + config->postfieldsize = curlx_uztoso(size); + } + + /* + We can't set the request type here, as this data might be used in + a simple GET if -G is used. Already or soon. + + if(SetHTTPrequest(HTTPREQ_SIMPLEPOST, &config->httpreq)) { + Curl_safefree(postdata); + return PARAM_BAD_USE; + } + */ + +done: + return err; +} + + #define ONEOPT(x,y) (((int)x << 8) | y) ParameterError getparameter(const char *flag, /* f or -long-flag */ @@ -1675,152 +1830,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case ONEOPT('d', 'f'): /* --json */ case ONEOPT('d', 'g'): /* --url-query */ case ONEOPT('d', 'r'): /* --data-raw */ - /* postfield data */ - { - char *postdata = NULL; - FILE *file; - size_t size = 0; - bool raw_mode = (subletter == 'r'); - - if(subletter == 'g') { /* --url-query */ -#define MAX_QUERY_LEN 100000 /* larger is not likely to ever work */ - char *query; - struct curlx_dynbuf dyn; - curlx_dyn_init(&dyn, MAX_QUERY_LEN); - - if(*nextarg == '+') { - /* use without encoding */ - query = strdup(&nextarg[1]); - if(!query) { - err = PARAM_NO_MEM; - break; - } - } - else { - err = data_urlencode(global, nextarg, &query, &size); - if(err) - break; - } - - if(config->query) { - CURLcode result = - curlx_dyn_addf(&dyn, "%s&%s", config->query, query); - free(query); - if(result) { - err = PARAM_NO_MEM; - break; - } - free(config->query); - config->query = curlx_dyn_ptr(&dyn); - } - else - config->query = query; - - break; /* this is not a POST argument at all */ - } - else if(subletter == 'e') { /* --data-urlencode */ - err = data_urlencode(global, nextarg, &postdata, &size); - if(err) - break; - } - else if('@' == *nextarg && !raw_mode) { - /* the data begins with a '@' letter, it means that a file name - or - (stdin) follows */ - nextarg++; /* pass the @ */ - - if(!strcmp("-", nextarg)) { - file = stdin; - if(subletter == 'b') /* forced data-binary */ - set_binmode(stdin); - } - else { - file = fopen(nextarg, "rb"); - if(!file) { - errorf(global, "Failed to open %s", nextarg); - err = PARAM_READ_ERROR; - break; - } - } - - if((subletter == 'b') || /* --data-binary */ - (subletter == 'f') /* --json */) - /* forced binary */ - err = file2memory(&postdata, &size, file); - else { - err = file2string(&postdata, file); - if(postdata) - size = strlen(postdata); - } - - if(file && (file != stdin)) - fclose(file); - if(err) - break; - - if(!postdata) { - /* no data from the file, point to a zero byte string to make this - get sent as a POST anyway */ - postdata = strdup(""); - if(!postdata) { - err = PARAM_NO_MEM; - break; - } - } - } - else { - err = getstr(&postdata, nextarg, ALLOW_BLANK); - if(err) - break; - if(postdata) - size = strlen(postdata); - } - if(subletter == 'f') - config->jsoned = TRUE; - - if(config->postfields) { - /* we already have a string, we append this one with a separating - &-letter */ - char *oldpost = config->postfields; - curl_off_t oldlen = config->postfieldsize; - curl_off_t newlen = oldlen + curlx_uztoso(size) + 2; - config->postfields = malloc((size_t)newlen); - if(!config->postfields) { - Curl_safefree(oldpost); - Curl_safefree(postdata); - err = PARAM_NO_MEM; - break; - } - memcpy(config->postfields, oldpost, (size_t)oldlen); - if(subletter != 'f') { - /* skip this treatment for --json */ - /* use byte value 0x26 for '&' to accommodate non-ASCII platforms */ - config->postfields[oldlen] = '\x26'; - memcpy(&config->postfields[oldlen + 1], postdata, size); - config->postfields[oldlen + 1 + size] = '\0'; - config->postfieldsize += size + 1; - } - else { - memcpy(&config->postfields[oldlen], postdata, size); - config->postfields[oldlen + size] = '\0'; - config->postfieldsize += size; - } - Curl_safefree(oldpost); - Curl_safefree(postdata); - } - else { - config->postfields = postdata; - config->postfieldsize = curlx_uztoso(size); - } - } - /* - We can't set the request type here, as this data might be used in - a simple GET if -G is used. Already or soon. - - if(SetHTTPrequest(HTTPREQ_SIMPLEPOST, &config->httpreq)) { - Curl_safefree(postdata); - return PARAM_BAD_USE; - } - */ + err = set_data(subletter, nextarg, global, config); break; case ONEOPT('D', '\0'): /* --dump-header */ err = getstr(&config->headerfile, nextarg, DENY_BLANK); From 3870d03b5d118766f63df3290946b2823c6396b0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 131/509] tool_getparam: move the --url-query logic into url_query() This function is not doing post at all so it was always weirdly placed. --- src/tool_getparam.c | 77 +++++++++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 0b58475c05d..baec05cf947 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -760,53 +760,54 @@ static const struct LongShort *single(char letter) return singles[letter - ' ']; } -static ParameterError set_data(char subletter, - char *nextarg, - struct GlobalConfig *global, - struct OperationConfig *config) +#define MAX_QUERY_LEN 100000 /* larger is not likely to ever work */ +static ParameterError url_query(char *nextarg, + struct GlobalConfig *global, + struct OperationConfig *config) { - char *postdata = NULL; - FILE *file; size_t size = 0; ParameterError err = PARAM_OK; + char *query; + struct curlx_dynbuf dyn; + curlx_dyn_init(&dyn, MAX_QUERY_LEN); + + if(*nextarg == '+') { + /* use without encoding */ + query = strdup(&nextarg[1]); + if(!query) + err = PARAM_NO_MEM; + } + else + err = data_urlencode(global, nextarg, &query, &size); - if(subletter == 'g') { /* --url-query */ -#define MAX_QUERY_LEN 100000 /* larger is not likely to ever work */ - char *query; - struct curlx_dynbuf dyn; - curlx_dyn_init(&dyn, MAX_QUERY_LEN); - - if(*nextarg == '+') { - /* use without encoding */ - query = strdup(&nextarg[1]); - if(!query) { - err = PARAM_NO_MEM; - goto done; - } - } - else { - err = data_urlencode(global, nextarg, &query, &size); - if(err) - goto done; - } - + if(!err) { if(config->query) { - CURLcode result = - curlx_dyn_addf(&dyn, "%s&%s", config->query, query); + CURLcode result = curlx_dyn_addf(&dyn, "%s&%s", config->query, query); free(query); - if(result) { + if(result) err = PARAM_NO_MEM; - goto done; + else { + free(config->query); + config->query = curlx_dyn_ptr(&dyn); } - free(config->query); - config->query = curlx_dyn_ptr(&dyn); } else config->query = query; - - goto done; /* this is not a POST argument at all */ } - else if(subletter == 'e') { /* --data-urlencode */ + return err; +} + +static ParameterError set_data(char subletter, + char *nextarg, + struct GlobalConfig *global, + struct OperationConfig *config) +{ + char *postdata = NULL; + FILE *file; + size_t size = 0; + ParameterError err = PARAM_OK; + + if(subletter == 'e') { /* --data-urlencode */ err = data_urlencode(global, nextarg, &postdata, &size); if(err) goto done; @@ -1828,10 +1829,12 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case ONEOPT('d', 'b'): /* --data-binary */ case ONEOPT('d', 'e'): /* --data-urlencode */ case ONEOPT('d', 'f'): /* --json */ - case ONEOPT('d', 'g'): /* --url-query */ case ONEOPT('d', 'r'): /* --data-raw */ err = set_data(subletter, nextarg, global, config); - break; + break; + case ONEOPT('d', 'g'): /* --url-query */ + err = url_query(nextarg, global, config); + break; case ONEOPT('D', '\0'): /* --dump-header */ err = getstr(&config->headerfile, nextarg, DENY_BLANK); break; From f37840a46e5eddaf109c16fa783c8dd8ef639271 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 132/509] tool_getparam: make data_urlencode avoid direct malloc use aprintf() instead --- src/tool_getparam.c | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index baec05cf947..ddc8ff7b337 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -637,25 +637,18 @@ static ParameterError data_urlencode(struct GlobalConfig *global, char *enc = curl_easy_escape(NULL, postdata, (int)size); Curl_safefree(postdata); /* no matter if it worked or not */ if(enc) { - /* replace (in-place) '%20' by '+' according to RFC1866 */ - size_t enclen = replace_url_encoded_space_by_plus(enc); - /* now make a string with the name from above and append the - encoded string */ - size_t outlen = nlen + enclen + 2; - char *n = malloc(outlen); - if(!n) { - curl_free(enc); - return PARAM_NO_MEM; - } + char *n; + replace_url_encoded_space_by_plus(enc); if(nlen > 0) { /* only append '=' if we have a name */ - msnprintf(n, outlen, "%.*s=%s", (int)nlen, nextarg, enc); - size = outlen-1; - } - else { - strcpy(n, enc); - size = outlen-2; /* since no '=' was inserted */ + n = aprintf("%.*s=%s", (int)nlen, nextarg, enc); + curl_free(enc); + if(!n) + return PARAM_NO_MEM; } - curl_free(enc); + else + n = enc; + + size = strlen(n); postdata = n; } else From 1dba44b2f1d8b813526610044aef5adbb9419dac Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 133/509] tool_getparam: replace malloc + copy by dynbuf for --data --- src/tool_getparam.c | 42 ++++++++++++++++-------------------------- src/tool_operate.c | 1 - src/tool_paramhlp.c | 2 -- src/tool_paramhlp.h | 2 ++ 4 files changed, 18 insertions(+), 29 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index ddc8ff7b337..6a7402b1689 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -860,34 +860,24 @@ static ParameterError set_data(char subletter, config->jsoned = TRUE; if(config->postfields) { - /* we already have a string, we append this one with a separating - &-letter */ - char *oldpost = config->postfields; - curl_off_t oldlen = config->postfieldsize; - curl_off_t newlen = oldlen + curlx_uztoso(size) + 2; - config->postfields = malloc((size_t)newlen); - if(!config->postfields) { - Curl_safefree(oldpost); - Curl_safefree(postdata); + /* we already have a string, append this one - perhaps with a separator */ + struct curlx_dynbuf out; + curlx_dyn_init(&out, MAX_FILE2MEMORY); + if(curlx_dyn_addn(&out, config->postfields, + (size_t)config->postfieldsize)) err = PARAM_NO_MEM; - goto done; - } - memcpy(config->postfields, oldpost, (size_t)oldlen); - if(subletter != 'f') { - /* skip this treatment for --json */ - /* use byte value 0x26 for '&' to accommodate non-ASCII platforms */ - config->postfields[oldlen] = '\x26'; - memcpy(&config->postfields[oldlen + 1], postdata, size); - config->postfields[oldlen + 1 + size] = '\0'; - config->postfieldsize += size + 1; - } - else { - memcpy(&config->postfields[oldlen], postdata, size); - config->postfields[oldlen + size] = '\0'; - config->postfieldsize += size; - } - Curl_safefree(oldpost); + + /* skip the separator append for --json */ + if(!err && (subletter != 'f') && curlx_dyn_addn(&out, "&", 1)) + err = PARAM_NO_MEM; + + if(!err && curlx_dyn_addn(&out, postdata, size)) + err = PARAM_NO_MEM; + + config->postfieldsize = curlx_dyn_len(&out); + free(config->postfields); Curl_safefree(postdata); + config->postfields = curlx_dyn_ptr(&out); } else { config->postfields = postdata; diff --git a/src/tool_operate.c b/src/tool_operate.c index c805b7732b2..2b0ed8620e2 100644 --- a/src/tool_operate.c +++ b/src/tool_operate.c @@ -372,7 +372,6 @@ void single_transfer_cleanup(struct OperationConfig *config) state->urls = NULL; } Curl_safefree(state->outfiles); - Curl_safefree(state->httpgetfields); Curl_safefree(state->uploadfile); if(state->inglob) { /* Free list of globbed upload files */ diff --git a/src/tool_paramhlp.c b/src/tool_paramhlp.c index a6b946edd67..2725815000d 100644 --- a/src/tool_paramhlp.c +++ b/src/tool_paramhlp.c @@ -88,8 +88,6 @@ ParameterError file2string(char **bufp, FILE *file) return PARAM_OK; } -#define MAX_FILE2MEMORY (1024*1024*1024) /* big enough ? */ - ParameterError file2memory(char **bufp, size_t *size, FILE *file) { if(file) { diff --git a/src/tool_paramhlp.h b/src/tool_paramhlp.h index edb87819502..96c49ac59e8 100644 --- a/src/tool_paramhlp.h +++ b/src/tool_paramhlp.h @@ -30,6 +30,8 @@ struct getout *new_getout(struct OperationConfig *config); ParameterError file2string(char **bufp, FILE *file); +#define MAX_FILE2MEMORY (1024*1024*1024) /* big enough ? */ + ParameterError file2memory(char **bufp, size_t *size, FILE *file); ParameterError str2num(long *val, const char *str); From 1f4433dad4cb6fbb5c6a85c95ee1fcd8891a4129 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 134/509] tool_getparam: build post data using dynbuf (more) --- src/tool_cfgable.c | 5 +++-- src/tool_cfgable.h | 2 +- src/tool_getparam.c | 54 ++++++++++++--------------------------------- src/tool_operate.c | 18 ++++++--------- src/tool_setopt.c | 2 +- 5 files changed, 26 insertions(+), 55 deletions(-) diff --git a/src/tool_cfgable.c b/src/tool_cfgable.c index 906e23e1411..3259bc7a5f0 100644 --- a/src/tool_cfgable.c +++ b/src/tool_cfgable.c @@ -25,6 +25,7 @@ #include "tool_cfgable.h" #include "tool_formparse.h" +#include "tool_paramhlp.h" #include "tool_main.h" #include "memdebug.h" /* keep this as LAST include */ @@ -33,7 +34,6 @@ void config_init(struct OperationConfig *config) { memset(config, 0, sizeof(struct OperationConfig)); - config->postfieldsize = -1; config->use_httpget = FALSE; config->create_dirs = FALSE; config->maxredirs = DEFAULT_MAXREDIRS; @@ -45,6 +45,7 @@ void config_init(struct OperationConfig *config) config->http09_allowed = FALSE; config->ftp_skip_ip = TRUE; config->file_clobber_mode = CLOBBER_DEFAULT; + curlx_dyn_init(&config->postdata, MAX_FILE2MEMORY); } static void free_config_fields(struct OperationConfig *config) @@ -59,7 +60,7 @@ static void free_config_fields(struct OperationConfig *config) Curl_safefree(config->cookiejar); curl_slist_free_all(config->cookiefiles); - Curl_safefree(config->postfields); + Curl_dyn_free(&config->postdata); Curl_safefree(config->query); Curl_safefree(config->referer); diff --git a/src/tool_cfgable.h b/src/tool_cfgable.h index 57e8fce527c..dfa74d81ff4 100644 --- a/src/tool_cfgable.h +++ b/src/tool_cfgable.h @@ -68,7 +68,7 @@ struct OperationConfig { char *proto_default; curl_off_t resume_from; char *postfields; - curl_off_t postfieldsize; + struct curlx_dynbuf postdata; char *referer; char *query; long timeout_ms; diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 6a7402b1689..e5c2b0f1574 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -803,7 +803,7 @@ static ParameterError set_data(char subletter, if(subletter == 'e') { /* --data-urlencode */ err = data_urlencode(global, nextarg, &postdata, &size); if(err) - goto done; + return err; } else if('@' == *nextarg && (subletter != 'r')) { /* the data begins with a '@' letter, it means that a file name @@ -819,8 +819,7 @@ static ParameterError set_data(char subletter, file = fopen(nextarg, "rb"); if(!file) { errorf(global, "Failed to open %s", nextarg); - err = PARAM_READ_ERROR; - goto done; + return PARAM_READ_ERROR; } } @@ -837,64 +836,39 @@ static ParameterError set_data(char subletter, if(file && (file != stdin)) fclose(file); if(err) - goto done; + return err; if(!postdata) { /* no data from the file, point to a zero byte string to make this get sent as a POST anyway */ postdata = strdup(""); - if(!postdata) { - err = PARAM_NO_MEM; - goto done; - } + if(!postdata) + return PARAM_NO_MEM; } } else { err = getstr(&postdata, nextarg, ALLOW_BLANK); if(err) - goto done; + return err; if(postdata) size = strlen(postdata); } if(subletter == 'f') config->jsoned = TRUE; - if(config->postfields) { - /* we already have a string, append this one - perhaps with a separator */ - struct curlx_dynbuf out; - curlx_dyn_init(&out, MAX_FILE2MEMORY); - if(curlx_dyn_addn(&out, config->postfields, - (size_t)config->postfieldsize)) + if(curlx_dyn_len(&config->postdata)) { + /* skip separator append for --json */ + if(!err && (subletter != 'f') && + curlx_dyn_addn(&config->postdata, "&", 1)) err = PARAM_NO_MEM; - - /* skip the separator append for --json */ - if(!err && (subletter != 'f') && curlx_dyn_addn(&out, "&", 1)) - err = PARAM_NO_MEM; - - if(!err && curlx_dyn_addn(&out, postdata, size)) - err = PARAM_NO_MEM; - - config->postfieldsize = curlx_dyn_len(&out); - free(config->postfields); - Curl_safefree(postdata); - config->postfields = curlx_dyn_ptr(&out); - } - else { - config->postfields = postdata; - config->postfieldsize = curlx_uztoso(size); } - /* - We can't set the request type here, as this data might be used in - a simple GET if -G is used. Already or soon. + if(!err && curlx_dyn_addn(&config->postdata, postdata, size)) + err = PARAM_NO_MEM; - if(SetHTTPrequest(HTTPREQ_SIMPLEPOST, &config->httpreq)) { - Curl_safefree(postdata); - return PARAM_BAD_USE; - } - */ + Curl_safefree(postdata); -done: + config->postfields = curlx_dyn_ptr(&config->postdata); return err; } diff --git a/src/tool_operate.c b/src/tool_operate.c index 2b0ed8620e2..3fe5b511654 100644 --- a/src/tool_operate.c +++ b/src/tool_operate.c @@ -761,15 +761,11 @@ static CURLcode single_transfer(struct GlobalConfig *global, if(config->use_httpget) { if(!httpgetfields) { /* Use the postfields data for an HTTP get */ - httpgetfields = state->httpgetfields = strdup(config->postfields); - Curl_safefree(config->postfields); - if(!httpgetfields) { - errorf(global, "out of memory"); - result = CURLE_OUT_OF_MEMORY; - } - else if(SetHTTPrequest(config, - (config->no_body?HTTPREQ_HEAD:HTTPREQ_GET), - &config->httpreq)) { + httpgetfields = state->httpgetfields = config->postfields; + config->postfields = NULL; + if(SetHTTPrequest(config, + (config->no_body?HTTPREQ_HEAD:HTTPREQ_GET), + &config->httpreq)) { result = CURLE_FAILED_INIT; } } @@ -1432,9 +1428,9 @@ static CURLcode single_transfer(struct GlobalConfig *global, } else { my_setopt_str(curl, CURLOPT_POSTFIELDS, - config->postfields); + curlx_dyn_ptr(&config->postdata)); my_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, - config->postfieldsize); + (curl_off_t)curlx_dyn_len(&config->postdata)); } break; case HTTPREQ_MIMEPOST: diff --git a/src/tool_setopt.c b/src/tool_setopt.c index e95c68dcb29..1c3096b8b46 100644 --- a/src/tool_setopt.c +++ b/src/tool_setopt.c @@ -660,7 +660,7 @@ CURLcode tool_setopt(CURL *curl, bool str, struct GlobalConfig *global, if(escape) { curl_off_t len = ZERO_TERMINATED; if(tag == CURLOPT_POSTFIELDS) - len = config->postfieldsize; + len = curlx_dyn_len(&config->postdata); escaped = c_escape(value, len); NULL_CHECK(escaped); CODE2("curl_easy_setopt(hnd, %s, \"%s\");", name, escaped); From 9e4e527735bfd92132d102b2e7d102b8cb4f5a61 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 135/509] tool_getparam: switch to an enum for every option To make the big switch much easier to read/understand and to make it easier to add new options. --- src/tool_getparam.c | 1550 ++++++++++++++++++++++++------------------- tests/test1139.pl | 8 +- 2 files changed, 878 insertions(+), 680 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index e5c2b0f1574..a0afeba93de 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -71,287 +71,558 @@ static ParameterError getstr(char **str, const char *val, bool allowblank) return PARAM_OK; } +/* one enum for every command line option. The name is the verbatim long + option name, but in uppercase with periods and minuses replaced with + underscores using a "C_" prefix. */ +typedef enum { + C_ABSTRACT_UNIX_SOCKET, + C_ALPN, + C_ALT_SVC, + C_ANYAUTH, + C_APPEND, + C_AWS_SIGV4, + C_BASIC, + C_BUFFER, + C_CA_NATIVE, + C_CACERT, + C_CAPATH, + C_CERT, + C_CERT_STATUS, + C_CERT_TYPE, + C_CIPHERS, + C_CLOBBER, + C_COMPRESSED, + C_COMPRESSED_SSH, + C_CONFIG, + C_CONNECT_TIMEOUT, + C_CONNECT_TO, + C_CONTINUE_AT, + C_COOKIE, + C_COOKIE_JAR, + C_CREATE_DIRS, + C_CREATE_FILE_MODE, + C_CRLF, + C_CRLFILE, + C_CURVES, + C_DATA, + C_DATA_ASCII, + C_DATA_BINARY, + C_DATA_RAW, + C_DATA_URLENCODE, + C_DELEGATION, + C_DIGEST, + C_DISABLE, + C_DISABLE_EPRT, + C_DISABLE_EPSV, + C_DISALLOW_USERNAME_IN_URL, + C_DNS_INTERFACE, + C_DNS_IPV4_ADDR, + C_DNS_IPV6_ADDR, + C_DNS_SERVERS, + C_DOH_CERT_STATUS, + C_DOH_INSECURE, + C_DOH_URL, + C_DUMP_HEADER, + C_EGD_FILE, + C_ENGINE, + C_EPRT, + C_EPSV, + C_ETAG_COMPARE, + C_ETAG_SAVE, + C_EXPECT100_TIMEOUT, + C_FAIL, + C_FAIL_EARLY, + C_FAIL_WITH_BODY, + C_FALSE_START, + C_FORM, + C_FORM_ESCAPE, + C_FORM_STRING, + C_FTP_ACCOUNT, + C_FTP_ALTERNATIVE_TO_USER, + C_FTP_CREATE_DIRS, + C_FTP_METHOD, + C_FTP_PASV, + C_FTP_PORT, + C_FTP_PRET, + C_FTP_SKIP_PASV_IP, + C_FTP_SSL, + C_FTP_SSL_CCC, + C_FTP_SSL_CCC_MODE, + C_FTP_SSL_CONTROL, + C_FTP_SSL_REQD, + C_GET, + C_GLOBOFF, + C_HAPPY_EYEBALLS_TIMEOUT_MS, + C_HAPROXY_CLIENTIP, + C_HAPROXY_PROTOCOL, + C_HEAD, + C_HEADER, + C_HELP, + C_HOSTPUBMD5, + C_HOSTPUBSHA256, + C_HSTS, + C_HTTP0_9, + C_HTTP1_0, + C_HTTP1_1, + C_HTTP2, + C_HTTP2_PRIOR_KNOWLEDGE, + C_HTTP3, + C_HTTP3_ONLY, + C_IGNORE_CONTENT_LENGTH, + C_INCLUDE, + C_INSECURE, + C_INTERFACE, + C_IPFS_GATEWAY, + C_IPV4, + C_IPV6, + C_JSON, + C_JUNK_SESSION_COOKIES, + C_KEEPALIVE, + C_KEEPALIVE_TIME, + C_KEY, + C_KEY_TYPE, + C_KRB, + C_KRB4, + C_LIBCURL, + C_LIMIT_RATE, + C_LIST_ONLY, + C_LOCAL_PORT, + C_LOCATION, + C_LOCATION_TRUSTED, + C_LOGIN_OPTIONS, + C_MAIL_AUTH, + C_MAIL_FROM, + C_MAIL_RCPT, + C_MAIL_RCPT_ALLOWFAILS, + C_MANUAL, + C_MAX_FILESIZE, + C_MAX_REDIRS, + C_MAX_TIME, + C_METALINK, + C_NEGOTIATE, + C_NETRC, + C_NETRC_FILE, + C_NETRC_OPTIONAL, + C_NEXT, + C_NOPROXY, + C_NPN, + C_NTLM, + C_NTLM_WB, + C_OAUTH2_BEARER, + C_OUTPUT, + C_OUTPUT_DIR, + C_PARALLEL, + C_PARALLEL_IMMEDIATE, + C_PARALLEL_MAX, + C_PASS, + C_PATH_AS_IS, + C_PINNEDPUBKEY, + C_POST301, + C_POST302, + C_POST303, + C_PREPROXY, + C_PROGRESS_BAR, + C_PROGRESS_METER, + C_PROTO, + C_PROTO_DEFAULT, + C_PROTO_REDIR, + C_PROXY, + C_PROXY_ANYAUTH, + C_PROXY_BASIC, + C_PROXY_CA_NATIVE, + C_PROXY_CACERT, + C_PROXY_CAPATH, + C_PROXY_CERT, + C_PROXY_CERT_TYPE, + C_PROXY_CIPHERS, + C_PROXY_CRLFILE, + C_PROXY_DIGEST, + C_PROXY_HEADER, + C_PROXY_HTTP2, + C_PROXY_INSECURE, + C_PROXY_KEY, + C_PROXY_KEY_TYPE, + C_PROXY_NEGOTIATE, + C_PROXY_NTLM, + C_PROXY_PASS, + C_PROXY_PINNEDPUBKEY, + C_PROXY_SERVICE_NAME, + C_PROXY_SSL_ALLOW_BEAST, + C_PROXY_SSL_AUTO_CLIENT_CERT, + C_PROXY_TLS13_CIPHERS, + C_PROXY_TLSAUTHTYPE, + C_PROXY_TLSPASSWORD, + C_PROXY_TLSUSER, + C_PROXY_TLSV1, + C_PROXY_USER, + C_PROXY1_0, + C_PROXYTUNNEL, + C_PUBKEY, + C_QUOTE, + C_RANDOM_FILE, + C_RANGE, + C_RATE, + C_RAW, + C_REFERER, + C_REMOTE_HEADER_NAME, + C_REMOTE_NAME, + C_REMOTE_NAME_ALL, + C_REMOTE_TIME, + C_REMOVE_ON_ERROR, + C_REQUEST, + C_REQUEST_TARGET, + C_RESOLVE, + C_RETRY, + C_RETRY_ALL_ERRORS, + C_RETRY_CONNREFUSED, + C_RETRY_DELAY, + C_RETRY_MAX_TIME, + C_SASL_AUTHZID, + C_SASL_IR, + C_SERVICE_NAME, + C_SESSIONID, + C_SHOW_ERROR, + C_SILENT, + C_SOCKS4, + C_SOCKS4A, + C_SOCKS5, + C_SOCKS5_BASIC, + C_SOCKS5_GSSAPI, + C_SOCKS5_GSSAPI_NEC, + C_SOCKS5_GSSAPI_SERVICE, + C_SOCKS5_HOSTNAME, + C_SPEED_LIMIT, + C_SPEED_TIME, + C_SSL, + C_SSL_ALLOW_BEAST, + C_SSL_AUTO_CLIENT_CERT, + C_SSL_NO_REVOKE, + C_SSL_REQD, + C_SSL_REVOKE_BEST_EFFORT, + C_SSLV2, + C_SSLV3, + C_STDERR, + C_STYLED_OUTPUT, + C_SUPPRESS_CONNECT_HEADERS, + C_TCP_FASTOPEN, + C_TCP_NODELAY, + C_TELNET_OPTION, + C_TEST_EVENT, + C_TFTP_BLKSIZE, + C_TFTP_NO_OPTIONS, + C_TIME_COND, + C_TLS_MAX, + C_TLS13_CIPHERS, + C_TLSAUTHTYPE, + C_TLSPASSWORD, + C_TLSUSER, + C_TLSV1, + C_TLSV1_0, + C_TLSV1_1, + C_TLSV1_2, + C_TLSV1_3, + C_TR_ENCODING, + C_TRACE, + C_TRACE_ASCII, + C_TRACE_CONFIG, + C_TRACE_IDS, + C_TRACE_TIME, + C_UNIX_SOCKET, + C_UPLOAD_FILE, + C_URL, + C_URL_QUERY, + C_USE_ASCII, + C_USER, + C_USER_AGENT, + C_VARIABLE, + C_VERBOSE, + C_VERSION, + C_WDEBUG, + C_WRITE_OUT, + C_XATTR +} cmdline_t; + struct LongShort { const char *lname; /* long name option */ enum { - ARG_NONE, /* stand-alone but not a boolean */ - ARG_BOOL, /* accepts a --no-[name] prefix */ - ARG_STRING, /* requires an argument */ - ARG_FILENAME /* requires an argument, usually a file name */ + ARG_NONE, /* stand-alone but not a boolean */ + ARG_BOOL, /* accepts a --no-[name] prefix */ + ARG_STRG, /* requires an argument */ + ARG_FILE /* requires an argument, usually a file name */ } desc; - const char *letter; /* short name option */ - /* 'letter' strings with more than one character have *no* short option. */ + char letter; /* short name option or ' ' */ + cmdline_t cmd; }; /* this array MUST be alphasorted based on the 'lname' */ static const struct LongShort aliases[]= { - {"abstract-unix-socket", ARG_FILENAME, "$W"}, - {"alpn", ARG_BOOL, "*H"}, - {"alt-svc", ARG_STRING, "ba"}, - {"anyauth", ARG_BOOL, "*o"}, - {"append", ARG_BOOL, "a",}, - {"aws-sigv4", ARG_STRING, "*V"}, - {"basic", ARG_BOOL, "*n"}, - {"buffer", ARG_BOOL, "N",}, - {"ca-native", ARG_BOOL, "EG"}, - {"cacert", ARG_FILENAME, "Ea"}, - {"capath", ARG_FILENAME, "Eg"}, - {"cert", ARG_FILENAME, "E",}, - {"cert-status", ARG_BOOL, "Eq"}, - {"cert-type", ARG_STRING, "Eb"}, - {"ciphers", ARG_STRING, "*d"}, - {"clobber", ARG_BOOL, "Oc"}, - {"compressed", ARG_BOOL, "*j"}, - {"compressed-ssh", ARG_BOOL, "$Z"}, - {"config", ARG_FILENAME, "K",}, - {"connect-timeout", ARG_STRING, "*c"}, - {"connect-to", ARG_STRING, "$U"}, - {"continue-at", ARG_STRING, "C",}, - {"cookie", ARG_STRING, "b",}, - {"cookie-jar", ARG_STRING, "c",}, - {"create-dirs", ARG_BOOL, "*r"}, - {"create-file-mode", ARG_STRING, "*R"}, - {"crlf", ARG_BOOL, "*u"}, - {"crlfile", ARG_FILENAME, "Ej"}, - {"curves", ARG_STRING, "EE"}, - {"data", ARG_STRING, "d",}, - {"data-ascii", ARG_STRING, "da"}, - {"data-binary", ARG_STRING, "db"}, - {"data-raw", ARG_STRING, "dr"}, - {"data-urlencode", ARG_STRING, "de"}, - {"delegation", ARG_STRING, "$G"}, - {"digest", ARG_BOOL, "*k"}, - {"disable", ARG_BOOL, "q",}, - {"disable-eprt", ARG_BOOL, "*z"}, - {"disable-epsv", ARG_BOOL, "*e"}, - {"disallow-username-in-url", ARG_BOOL, "*f"}, - {"dns-interface", ARG_STRING, "*D"}, - {"dns-ipv4-addr", ARG_STRING, "*4"}, - {"dns-ipv6-addr", ARG_STRING, "*6"}, - {"dns-servers", ARG_STRING, "*F"}, - {"doh-cert-status", ARG_BOOL, "EQ"}, - {"doh-insecure", ARG_BOOL, "kd"}, - {"doh-url" , ARG_STRING, "*C"}, - {"dump-header", ARG_FILENAME, "D",}, - {"egd-file", ARG_STRING, "*b"}, - {"engine", ARG_STRING, "Ef"}, - {"eprt", ARG_BOOL, "*Z"}, - {"epsv", ARG_BOOL, "*E"}, - {"etag-compare", ARG_FILENAME, "ED"}, - {"etag-save", ARG_FILENAME, "EC"}, - {"expect100-timeout", ARG_STRING, "$R"}, - {"fail", ARG_BOOL, "f",}, - {"fail-early", ARG_BOOL, "fa"}, - {"fail-with-body", ARG_BOOL, "fd"}, - {"false-start", ARG_BOOL, "Er"}, - {"form", ARG_STRING, "F",}, - {"form-escape", ARG_BOOL, "$l"}, - {"form-string", ARG_STRING, "Fs"}, - {"ftp-account", ARG_STRING, "$m"}, - {"ftp-alternative-to-user", ARG_STRING, "$u"}, - {"ftp-create-dirs", ARG_BOOL, "*q"}, - {"ftp-method", ARG_STRING, "$r"}, - {"ftp-pasv", ARG_BOOL, "$b"}, - {"ftp-port", ARG_STRING, "P",}, - {"ftp-pret", ARG_BOOL, "$C"}, - {"ftp-skip-pasv-ip", ARG_BOOL, "$q"}, - {"ftp-ssl", ARG_BOOL, "$a"}, - {"ftp-ssl-ccc", ARG_BOOL, "$y"}, - {"ftp-ssl-ccc-mode", ARG_STRING, "$j"}, - {"ftp-ssl-control", ARG_BOOL, "$x"}, - {"ftp-ssl-reqd", ARG_BOOL, "$v"}, - {"get", ARG_BOOL, "G",}, - {"globoff", ARG_BOOL, "g",}, - {"happy-eyeballs-timeout-ms", ARG_STRING, "$~"}, - {"haproxy-clientip", ARG_STRING, "*P"}, - {"haproxy-protocol", ARG_BOOL, "*X"}, - {"head", ARG_BOOL, "I",}, - {"header", ARG_STRING, "H",}, - {"help", ARG_BOOL, "h",}, - {"hostpubmd5", ARG_STRING, "Ei"}, - {"hostpubsha256", ARG_STRING, "EF"}, - {"hsts", ARG_STRING, "bb"}, - {"http0.9", ARG_BOOL, "09"}, - {"http1.0", ARG_NONE, "0",}, - {"http1.1", ARG_NONE, "01"}, - {"http2", ARG_NONE, "02"}, - {"http2-prior-knowledge", ARG_NONE, "03"}, - {"http3", ARG_NONE, "04"}, - {"http3-only", ARG_NONE, "05"}, - {"ignore-content-length", ARG_BOOL, "$p"}, - {"include", ARG_BOOL, "i",}, - {"insecure", ARG_BOOL, "k",}, - {"interface", ARG_STRING, "*w"}, - {"ipfs-gateway", ARG_STRING, "*S"}, - {"ipv4", ARG_NONE, "4",}, - {"ipv6", ARG_NONE, "6",}, - {"json", ARG_STRING, "df"}, - {"junk-session-cookies", ARG_BOOL, "j",}, - {"keepalive", ARG_BOOL, "$1"}, - {"keepalive-time", ARG_STRING, "$3"}, - {"key", ARG_FILENAME, "Ec"}, - {"key-type", ARG_STRING, "Ed"}, - {"krb", ARG_STRING, "*x"}, - {"krb4", ARG_STRING, "*x"}, - {"libcurl", ARG_STRING, "$z"}, - {"limit-rate", ARG_STRING, "*i"}, - {"list-only", ARG_BOOL, "l",}, - {"local-port", ARG_STRING, "$s"}, - {"location", ARG_BOOL, "L",}, - {"location-trusted", ARG_BOOL, "Lt"}, - {"login-options", ARG_STRING, "E5"}, - {"mail-auth", ARG_STRING, "$H"}, - {"mail-from", ARG_STRING, "$A"}, - {"mail-rcpt", ARG_STRING, "$B"}, - {"mail-rcpt-allowfails", ARG_BOOL, "fc"}, - {"manual", ARG_BOOL, "M",}, - {"max-filesize", ARG_STRING, "*y"}, - {"max-redirs", ARG_STRING, "*s"}, - {"max-time", ARG_STRING, "m",}, - {"metalink", ARG_BOOL, "$J"}, - {"negotiate", ARG_BOOL, "*l"}, - {"netrc", ARG_BOOL, "n",}, - {"netrc-file", ARG_FILENAME, "ne"}, - {"netrc-optional", ARG_BOOL, "no"}, - {"next", ARG_NONE, ":",}, - {"noproxy", ARG_STRING, "$5"}, - {"npn", ARG_BOOL, "*G"}, - {"ntlm", ARG_BOOL, "*m"}, - {"ntlm-wb", ARG_BOOL, "*M"}, - {"oauth2-bearer", ARG_STRING, "*B"}, - {"output", ARG_FILENAME, "o",}, - {"output-dir", ARG_STRING, "Ob"}, - {"parallel", ARG_BOOL, "Z",}, - {"parallel-immediate", ARG_BOOL, "Zc"}, - {"parallel-max", ARG_STRING, "Zb"}, - {"pass", ARG_STRING, "Ee"}, - {"path-as-is", ARG_BOOL, "$N"}, - {"pinnedpubkey", ARG_STRING, "Ep"}, - {"post301", ARG_BOOL, "$0"}, - {"post302", ARG_BOOL, "$4"}, - {"post303", ARG_BOOL, "$I"}, - {"preproxy", ARG_STRING, "xa"}, - {"progress-bar", ARG_BOOL, "#",}, - {"progress-meter", ARG_BOOL, "#m"}, - {"proto", ARG_STRING, "$D"}, - {"proto-default", ARG_STRING, "$Q"}, - {"proto-redir", ARG_STRING, "$E"}, - {"proxy", ARG_STRING, "x",}, - {"proxy-anyauth", ARG_BOOL, "$n"}, - {"proxy-basic", ARG_BOOL, "$f"}, - {"proxy-ca-native", ARG_BOOL, "EH"}, - {"proxy-cacert", ARG_FILENAME, "E6"}, - {"proxy-capath", ARG_FILENAME, "E7"}, - {"proxy-cert", ARG_FILENAME, "Ex"}, - {"proxy-cert-type", ARG_STRING, "Ey"}, - {"proxy-ciphers", ARG_STRING, "E2"}, - {"proxy-crlfile", ARG_FILENAME, "E3"}, - {"proxy-digest", ARG_BOOL, "$e"}, - {"proxy-header", ARG_STRING, "Hp"}, - {"proxy-http2", ARG_BOOL, "0a"}, - {"proxy-insecure", ARG_BOOL, "E8"}, - {"proxy-key", ARG_FILENAME, "Ez"}, - {"proxy-key-type", ARG_STRING, "E0"}, - {"proxy-negotiate", ARG_BOOL, "$k"}, - {"proxy-ntlm", ARG_BOOL, "*t"}, - {"proxy-pass", ARG_STRING, "E1"}, - {"proxy-pinnedpubkey", ARG_STRING, "EP"}, - {"proxy-service-name", ARG_STRING, "$O"}, - {"proxy-ssl-allow-beast", ARG_BOOL, "E4"}, - {"proxy-ssl-auto-client-cert", ARG_BOOL, "EO"}, - {"proxy-tls13-ciphers", ARG_STRING, "1B"}, - {"proxy-tlsauthtype", ARG_STRING, "Ew"}, - {"proxy-tlspassword", ARG_STRING, "Ev"}, - {"proxy-tlsuser", ARG_STRING, "Eu"}, - {"proxy-tlsv1", ARG_NONE, "E9"}, - {"proxy-user", ARG_STRING, "U",}, - {"proxy1.0", ARG_STRING, "$8"}, - {"proxytunnel", ARG_BOOL, "p",}, - {"pubkey", ARG_STRING, "Eh"}, - {"quote", ARG_STRING, "Q",}, - {"random-file", ARG_FILENAME, "*a"}, - {"range", ARG_STRING, "r",}, - {"rate", ARG_STRING, "*I"}, - {"raw", ARG_BOOL, "$#"}, - {"referer", ARG_STRING, "e",}, - {"remote-header-name", ARG_BOOL, "J",}, - {"remote-name", ARG_BOOL, "O",}, - {"remote-name-all", ARG_BOOL, "Oa"}, - {"remote-time", ARG_BOOL, "R",}, - {"remove-on-error", ARG_BOOL, "fe"}, - {"request", ARG_STRING, "X",}, - {"request-target", ARG_STRING, "Ga"}, - {"resolve", ARG_STRING, "$F"}, - {"retry", ARG_STRING, "$g"}, - {"retry-all-errors", ARG_BOOL, "$!"}, - {"retry-connrefused", ARG_BOOL, "$V"}, - {"retry-delay", ARG_STRING, "$h"}, - {"retry-max-time", ARG_STRING, "$i"}, - {"sasl-authzid", ARG_STRING, "$6"}, - {"sasl-ir", ARG_BOOL, "$K"}, - {"service-name", ARG_STRING, "$P"}, - {"sessionid", ARG_BOOL, "$w"}, - {"show-error", ARG_BOOL, "S",}, - {"silent", ARG_BOOL, "s",}, - {"socks4", ARG_STRING, "$t"}, - {"socks4a", ARG_STRING, "$T"}, - {"socks5", ARG_STRING, "$c"}, - {"socks5-basic", ARG_BOOL, "EA"}, - {"socks5-gssapi", ARG_BOOL, "EB"}, - {"socks5-gssapi-nec", ARG_BOOL, "$7"}, - {"socks5-gssapi-service", ARG_STRING, "$O"}, - {"socks5-hostname", ARG_STRING, "$2"}, - {"speed-limit", ARG_STRING, "Y",}, - {"speed-time", ARG_STRING, "y",}, - {"ssl", ARG_BOOL, "$a"}, - {"ssl-allow-beast", ARG_BOOL, "En"}, - {"ssl-auto-client-cert", ARG_BOOL, "Eo"}, - {"ssl-no-revoke", ARG_BOOL, "Es"}, - {"ssl-reqd", ARG_BOOL, "$v"}, - {"ssl-revoke-best-effort", ARG_BOOL, "ES"}, - {"sslv2", ARG_NONE, "2",}, - {"sslv3", ARG_NONE, "3",}, - {"stderr", ARG_FILENAME, "*v"}, - {"styled-output", ARG_BOOL, "fb"}, - {"suppress-connect-headers", ARG_BOOL, "$Y"}, - {"tcp-fastopen", ARG_BOOL, "Et"}, - {"tcp-nodelay", ARG_BOOL, "$d"}, - {"telnet-option", ARG_STRING, "t",}, - {"test-event", ARG_BOOL, "$L"}, - {"tftp-blksize", ARG_STRING, "$9"}, - {"tftp-no-options", ARG_BOOL, "$S"}, - {"time-cond", ARG_STRING, "z",}, - {"tls-max", ARG_STRING, "$X"}, - {"tls13-ciphers", ARG_STRING, "1A"}, - {"tlsauthtype", ARG_STRING, "Em"}, - {"tlspassword", ARG_STRING, "El"}, - {"tlsuser", ARG_STRING, "Ek"}, - {"tlsv1", ARG_NONE, "1",}, - {"tlsv1.0", ARG_NONE, "10"}, - {"tlsv1.1", ARG_NONE, "11"}, - {"tlsv1.2", ARG_NONE, "12"}, - {"tlsv1.3", ARG_NONE, "13"}, - {"tr-encoding", ARG_BOOL, "*J"}, - {"trace", ARG_FILENAME, "*g"}, - {"trace-ascii", ARG_FILENAME, "*h"}, - {"trace-config", ARG_STRING, "$&"}, - {"trace-ids", ARG_BOOL, "$%"}, - {"trace-time", ARG_BOOL, "$o"}, - {"unix-socket", ARG_FILENAME, "$M"}, - {"upload-file", ARG_FILENAME, "T",}, - {"url", ARG_STRING, "*@"}, - {"url-query", ARG_STRING, "dg"}, - {"use-ascii", ARG_BOOL, "B",}, - {"user", ARG_STRING, "u",}, - {"user-agent", ARG_STRING, "A",}, - {"variable", ARG_STRING, ":a"}, - {"verbose", ARG_BOOL, "v",}, - {"version", ARG_BOOL, "V",}, + {"abstract-unix-socket", ARG_FILE, ' ', C_ABSTRACT_UNIX_SOCKET}, + {"alpn", ARG_BOOL, ' ', C_ALPN}, + {"alt-svc", ARG_STRG, ' ', C_ALT_SVC}, + {"anyauth", ARG_BOOL, ' ', C_ANYAUTH}, + {"append", ARG_BOOL, 'a', C_APPEND}, + {"aws-sigv4", ARG_STRG, ' ', C_AWS_SIGV4}, + {"basic", ARG_BOOL, ' ', C_BASIC}, + {"buffer", ARG_BOOL, 'N', C_BUFFER}, + {"ca-native", ARG_BOOL, ' ', C_CA_NATIVE}, + {"cacert", ARG_FILE, ' ', C_CACERT}, + {"capath", ARG_FILE, ' ', C_CAPATH}, + {"cert", ARG_FILE, 'E', C_CERT}, + {"cert-status", ARG_BOOL, ' ', C_CERT_STATUS}, + {"cert-type", ARG_STRG, ' ', C_CERT_TYPE}, + {"ciphers", ARG_STRG, ' ', C_CIPHERS}, + {"clobber", ARG_BOOL, ' ', C_CLOBBER}, + {"compressed", ARG_BOOL, ' ', C_COMPRESSED}, + {"compressed-ssh", ARG_BOOL, ' ', C_COMPRESSED_SSH}, + {"config", ARG_FILE, 'K', C_CONFIG}, + {"connect-timeout", ARG_STRG, ' ', C_CONNECT_TIMEOUT}, + {"connect-to", ARG_STRG, ' ', C_CONNECT_TO}, + {"continue-at", ARG_STRG, 'C', C_CONTINUE_AT}, + {"cookie", ARG_STRG, 'b', C_COOKIE}, + {"cookie-jar", ARG_STRG, 'c', C_COOKIE_JAR}, + {"create-dirs", ARG_BOOL, ' ', C_CREATE_DIRS}, + {"create-file-mode", ARG_STRG, ' ', C_CREATE_FILE_MODE}, + {"crlf", ARG_BOOL, ' ', C_CRLF}, + {"crlfile", ARG_FILE, ' ', C_CRLFILE}, + {"curves", ARG_STRG, ' ', C_CURVES}, + {"data", ARG_STRG, 'd', C_DATA}, + {"data-ascii", ARG_STRG, ' ', C_DATA_ASCII}, + {"data-binary", ARG_STRG, ' ', C_DATA_BINARY}, + {"data-raw", ARG_STRG, ' ', C_DATA_RAW}, + {"data-urlencode", ARG_STRG, ' ', C_DATA_URLENCODE}, + {"delegation", ARG_STRG, ' ', C_DELEGATION}, + {"digest", ARG_BOOL, ' ', C_DIGEST}, + {"disable", ARG_BOOL, 'q', C_DISABLE}, + {"disable-eprt", ARG_BOOL, ' ', C_DISABLE_EPRT}, + {"disable-epsv", ARG_BOOL, ' ', C_DISABLE_EPSV}, + {"disallow-username-in-url", ARG_BOOL, ' ', C_DISALLOW_USERNAME_IN_URL}, + {"dns-interface", ARG_STRG, ' ', C_DNS_INTERFACE}, + {"dns-ipv4-addr", ARG_STRG, ' ', C_DNS_IPV4_ADDR}, + {"dns-ipv6-addr", ARG_STRG, ' ', C_DNS_IPV6_ADDR}, + {"dns-servers", ARG_STRG, ' ', C_DNS_SERVERS}, + {"doh-cert-status", ARG_BOOL, ' ', C_DOH_CERT_STATUS}, + {"doh-insecure", ARG_BOOL, ' ', C_DOH_INSECURE}, + {"doh-url" , ARG_STRG, ' ', C_DOH_URL}, + {"dump-header", ARG_FILE, 'D', C_DUMP_HEADER}, + {"egd-file", ARG_STRG, ' ', C_EGD_FILE}, + {"engine", ARG_STRG, ' ', C_ENGINE}, + {"eprt", ARG_BOOL, ' ', C_EPRT}, + {"epsv", ARG_BOOL, ' ', C_EPSV}, + {"etag-compare", ARG_FILE, ' ', C_ETAG_COMPARE}, + {"etag-save", ARG_FILE, ' ', C_ETAG_SAVE}, + {"expect100-timeout", ARG_STRG, ' ', C_EXPECT100_TIMEOUT}, + {"fail", ARG_BOOL, 'f', C_FAIL}, + {"fail-early", ARG_BOOL, ' ', C_FAIL_EARLY}, + {"fail-with-body", ARG_BOOL, ' ', C_FAIL_WITH_BODY}, + {"false-start", ARG_BOOL, ' ', C_FALSE_START}, + {"form", ARG_STRG, 'F', C_FORM}, + {"form-escape", ARG_BOOL, ' ', C_FORM_ESCAPE}, + {"form-string", ARG_STRG, ' ', C_FORM_STRING}, + {"ftp-account", ARG_STRG, ' ', C_FTP_ACCOUNT}, + {"ftp-alternative-to-user", ARG_STRG, ' ', C_FTP_ALTERNATIVE_TO_USER}, + {"ftp-create-dirs", ARG_BOOL, ' ', C_FTP_CREATE_DIRS}, + {"ftp-method", ARG_STRG, ' ', C_FTP_METHOD}, + {"ftp-pasv", ARG_BOOL, ' ', C_FTP_PASV}, + {"ftp-port", ARG_STRG, 'P', C_FTP_PORT}, + {"ftp-pret", ARG_BOOL, ' ', C_FTP_PRET}, + {"ftp-skip-pasv-ip", ARG_BOOL, ' ', C_FTP_SKIP_PASV_IP}, + {"ftp-ssl", ARG_BOOL, ' ', C_FTP_SSL}, + {"ftp-ssl-ccc", ARG_BOOL, ' ', C_FTP_SSL_CCC}, + {"ftp-ssl-ccc-mode", ARG_STRG, ' ', C_FTP_SSL_CCC_MODE}, + {"ftp-ssl-control", ARG_BOOL, ' ', C_FTP_SSL_CONTROL}, + {"ftp-ssl-reqd", ARG_BOOL, ' ', C_FTP_SSL_REQD}, + {"get", ARG_BOOL, 'G', C_GET}, + {"globoff", ARG_BOOL, 'g', C_GLOBOFF}, + {"happy-eyeballs-timeout-ms", ARG_STRG, ' ', C_HAPPY_EYEBALLS_TIMEOUT_MS}, + {"haproxy-clientip", ARG_STRG, ' ', C_HAPROXY_CLIENTIP}, + {"haproxy-protocol", ARG_BOOL, ' ', C_HAPROXY_PROTOCOL}, + {"head", ARG_BOOL, 'I', C_HEAD}, + {"header", ARG_STRG, 'H', C_HEADER}, + {"help", ARG_BOOL, 'h', C_HELP}, + {"hostpubmd5", ARG_STRG, ' ', C_HOSTPUBMD5}, + {"hostpubsha256", ARG_STRG, ' ', C_HOSTPUBSHA256}, + {"hsts", ARG_STRG, ' ', C_HSTS}, + {"http0.9", ARG_BOOL, ' ', C_HTTP0_9}, + {"http1.0", ARG_NONE, '0', C_HTTP1_0}, + {"http1.1", ARG_NONE, ' ', C_HTTP1_1}, + {"http2", ARG_NONE, ' ', C_HTTP2}, + {"http2-prior-knowledge", ARG_NONE, ' ', C_HTTP2_PRIOR_KNOWLEDGE}, + {"http3", ARG_NONE, ' ', C_HTTP3}, + {"http3-only", ARG_NONE, ' ', C_HTTP3_ONLY}, + {"ignore-content-length", ARG_BOOL, ' ', C_IGNORE_CONTENT_LENGTH}, + {"include", ARG_BOOL, 'i', C_INCLUDE}, + {"insecure", ARG_BOOL, 'k', C_INSECURE}, + {"interface", ARG_STRG, ' ', C_INTERFACE}, + {"ipfs-gateway", ARG_STRG, ' ', C_IPFS_GATEWAY}, + {"ipv4", ARG_NONE, '4', C_IPV4}, + {"ipv6", ARG_NONE, '6', C_IPV6}, + {"json", ARG_STRG, ' ', C_JSON}, + {"junk-session-cookies", ARG_BOOL, 'j', C_JUNK_SESSION_COOKIES}, + {"keepalive", ARG_BOOL, ' ', C_KEEPALIVE}, + {"keepalive-time", ARG_STRG, ' ', C_KEEPALIVE_TIME}, + {"key", ARG_FILE, ' ', C_KEY}, + {"key-type", ARG_STRG, ' ', C_KEY_TYPE}, + {"krb", ARG_STRG, ' ', C_KRB}, + {"krb4", ARG_STRG, ' ', C_KRB4}, + {"libcurl", ARG_STRG, ' ', C_LIBCURL}, + {"limit-rate", ARG_STRG, ' ', C_LIMIT_RATE}, + {"list-only", ARG_BOOL, 'l', C_LIST_ONLY}, + {"local-port", ARG_STRG, ' ', C_LOCAL_PORT}, + {"location", ARG_BOOL, 'L', C_LOCATION}, + {"location-trusted", ARG_BOOL, ' ', C_LOCATION_TRUSTED}, + {"login-options", ARG_STRG, ' ', C_LOGIN_OPTIONS}, + {"mail-auth", ARG_STRG, ' ', C_MAIL_AUTH}, + {"mail-from", ARG_STRG, ' ', C_MAIL_FROM}, + {"mail-rcpt", ARG_STRG, ' ', C_MAIL_RCPT}, + {"mail-rcpt-allowfails", ARG_BOOL, ' ', C_MAIL_RCPT_ALLOWFAILS}, + {"manual", ARG_BOOL, 'M', C_MANUAL}, + {"max-filesize", ARG_STRG, ' ', C_MAX_FILESIZE}, + {"max-redirs", ARG_STRG, ' ', C_MAX_REDIRS}, + {"max-time", ARG_STRG, 'm', C_MAX_TIME}, + {"metalink", ARG_BOOL, ' ', C_METALINK}, + {"negotiate", ARG_BOOL, ' ', C_NEGOTIATE}, + {"netrc", ARG_BOOL, 'n', C_NETRC}, + {"netrc-file", ARG_FILE, ' ', C_NETRC_FILE}, + {"netrc-optional", ARG_BOOL, ' ', C_NETRC_OPTIONAL}, + {"next", ARG_NONE, ':', C_NEXT}, + {"noproxy", ARG_STRG, ' ', C_NOPROXY}, + {"npn", ARG_BOOL, ' ', C_NPN}, + {"ntlm", ARG_BOOL, ' ', C_NTLM}, + {"ntlm-wb", ARG_BOOL, ' ', C_NTLM_WB}, + {"oauth2-bearer", ARG_STRG, ' ', C_OAUTH2_BEARER}, + {"output", ARG_FILE, 'o', C_OUTPUT}, + {"output-dir", ARG_STRG, ' ', C_OUTPUT_DIR}, + {"parallel", ARG_BOOL, 'Z', C_PARALLEL}, + {"parallel-immediate", ARG_BOOL, ' ', C_PARALLEL_IMMEDIATE}, + {"parallel-max", ARG_STRG, ' ', C_PARALLEL_MAX}, + {"pass", ARG_STRG, ' ', C_PASS}, + {"path-as-is", ARG_BOOL, ' ', C_PATH_AS_IS}, + {"pinnedpubkey", ARG_STRG, ' ', C_PINNEDPUBKEY}, + {"post301", ARG_BOOL, ' ', C_POST301}, + {"post302", ARG_BOOL, ' ', C_POST302}, + {"post303", ARG_BOOL, ' ', C_POST303}, + {"preproxy", ARG_STRG, ' ', C_PREPROXY}, + {"progress-bar", ARG_BOOL, '#', C_PROGRESS_BAR}, + {"progress-meter", ARG_BOOL, ' ', C_PROGRESS_METER}, + {"proto", ARG_STRG, ' ', C_PROTO}, + {"proto-default", ARG_STRG, ' ', C_PROTO_DEFAULT}, + {"proto-redir", ARG_STRG, ' ', C_PROTO_REDIR}, + {"proxy", ARG_STRG, 'x', C_PROXY}, + {"proxy-anyauth", ARG_BOOL, ' ', C_PROXY_ANYAUTH}, + {"proxy-basic", ARG_BOOL, ' ', C_PROXY_BASIC}, + {"proxy-ca-native", ARG_BOOL, ' ', C_PROXY_CA_NATIVE}, + {"proxy-cacert", ARG_FILE, ' ', C_PROXY_CACERT}, + {"proxy-capath", ARG_FILE, ' ', C_PROXY_CAPATH}, + {"proxy-cert", ARG_FILE, ' ', C_PROXY_CERT}, + {"proxy-cert-type", ARG_STRG, ' ', C_PROXY_CERT_TYPE}, + {"proxy-ciphers", ARG_STRG, ' ', C_PROXY_CIPHERS}, + {"proxy-crlfile", ARG_FILE, ' ', C_PROXY_CRLFILE}, + {"proxy-digest", ARG_BOOL, ' ', C_PROXY_DIGEST}, + {"proxy-header", ARG_STRG, ' ', C_PROXY_HEADER}, + {"proxy-http2", ARG_BOOL, ' ', C_PROXY_HTTP2}, + {"proxy-insecure", ARG_BOOL, ' ', C_PROXY_INSECURE}, + {"proxy-key", ARG_FILE, ' ', C_PROXY_KEY}, + {"proxy-key-type", ARG_STRG, ' ', C_PROXY_KEY_TYPE}, + {"proxy-negotiate", ARG_BOOL, ' ', C_PROXY_NEGOTIATE}, + {"proxy-ntlm", ARG_BOOL, ' ', C_PROXY_NTLM}, + {"proxy-pass", ARG_STRG, ' ', C_PROXY_PASS}, + {"proxy-pinnedpubkey", ARG_STRG, ' ', C_PROXY_PINNEDPUBKEY}, + {"proxy-service-name", ARG_STRG, ' ', C_PROXY_SERVICE_NAME}, + {"proxy-ssl-allow-beast", ARG_BOOL, ' ', C_PROXY_SSL_ALLOW_BEAST}, + {"proxy-ssl-auto-client-cert", ARG_BOOL, ' ', C_PROXY_SSL_AUTO_CLIENT_CERT}, + {"proxy-tls13-ciphers", ARG_STRG, ' ', C_PROXY_TLS13_CIPHERS}, + {"proxy-tlsauthtype", ARG_STRG, ' ', C_PROXY_TLSAUTHTYPE}, + {"proxy-tlspassword", ARG_STRG, ' ', C_PROXY_TLSPASSWORD}, + {"proxy-tlsuser", ARG_STRG, ' ', C_PROXY_TLSUSER}, + {"proxy-tlsv1", ARG_NONE, ' ', C_PROXY_TLSV1}, + {"proxy-user", ARG_STRG, 'U', C_PROXY_USER}, + {"proxy1.0", ARG_STRG, ' ', C_PROXY1_0}, + {"proxytunnel", ARG_BOOL, 'p', C_PROXYTUNNEL}, + {"pubkey", ARG_STRG, ' ', C_PUBKEY}, + {"quote", ARG_STRG, 'Q', C_QUOTE}, + {"random-file", ARG_FILE, ' ', C_RANDOM_FILE}, + {"range", ARG_STRG, 'r', C_RANGE}, + {"rate", ARG_STRG, ' ', C_RATE}, + {"raw", ARG_BOOL, ' ', C_RAW}, + {"referer", ARG_STRG, 'e', C_REFERER}, + {"remote-header-name", ARG_BOOL, 'J', C_REMOTE_HEADER_NAME}, + {"remote-name", ARG_BOOL, 'O', C_REMOTE_NAME}, + {"remote-name-all", ARG_BOOL, ' ', C_REMOTE_NAME_ALL}, + {"remote-time", ARG_BOOL, 'R', C_REMOTE_TIME}, + {"remove-on-error", ARG_BOOL, ' ', C_REMOVE_ON_ERROR}, + {"request", ARG_STRG, 'X', C_REQUEST}, + {"request-target", ARG_STRG, ' ', C_REQUEST_TARGET}, + {"resolve", ARG_STRG, ' ', C_RESOLVE}, + {"retry", ARG_STRG, ' ', C_RETRY}, + {"retry-all-errors", ARG_BOOL, ' ', C_RETRY_ALL_ERRORS}, + {"retry-connrefused", ARG_BOOL, ' ', C_RETRY_CONNREFUSED}, + {"retry-delay", ARG_STRG, ' ', C_RETRY_DELAY}, + {"retry-max-time", ARG_STRG, ' ', C_RETRY_MAX_TIME}, + {"sasl-authzid", ARG_STRG, ' ', C_SASL_AUTHZID}, + {"sasl-ir", ARG_BOOL, ' ', C_SASL_IR}, + {"service-name", ARG_STRG, ' ', C_SERVICE_NAME}, + {"sessionid", ARG_BOOL, ' ', C_SESSIONID}, + {"show-error", ARG_BOOL, 'S', C_SHOW_ERROR}, + {"silent", ARG_BOOL, 's', C_SILENT}, + {"socks4", ARG_STRG, ' ', C_SOCKS4}, + {"socks4a", ARG_STRG, ' ', C_SOCKS4A}, + {"socks5", ARG_STRG, ' ', C_SOCKS5}, + {"socks5-basic", ARG_BOOL, ' ', C_SOCKS5_BASIC}, + {"socks5-gssapi", ARG_BOOL, ' ', C_SOCKS5_GSSAPI}, + {"socks5-gssapi-nec", ARG_BOOL, ' ', C_SOCKS5_GSSAPI_NEC}, + {"socks5-gssapi-service", ARG_STRG, ' ', C_SOCKS5_GSSAPI_SERVICE}, + {"socks5-hostname", ARG_STRG, ' ', C_SOCKS5_HOSTNAME}, + {"speed-limit", ARG_STRG, 'Y', C_SPEED_LIMIT}, + {"speed-time", ARG_STRG, 'y', C_SPEED_TIME}, + {"ssl", ARG_BOOL, ' ', C_SSL}, + {"ssl-allow-beast", ARG_BOOL, ' ', C_SSL_ALLOW_BEAST}, + {"ssl-auto-client-cert", ARG_BOOL, ' ', C_SSL_AUTO_CLIENT_CERT}, + {"ssl-no-revoke", ARG_BOOL, ' ', C_SSL_NO_REVOKE}, + {"ssl-reqd", ARG_BOOL, ' ', C_SSL_REQD}, + {"ssl-revoke-best-effort", ARG_BOOL, ' ', C_SSL_REVOKE_BEST_EFFORT}, + {"sslv2", ARG_NONE, '2', C_SSLV2}, + {"sslv3", ARG_NONE, '3', C_SSLV3}, + {"stderr", ARG_FILE, ' ', C_STDERR}, + {"styled-output", ARG_BOOL, ' ', C_STYLED_OUTPUT}, + {"suppress-connect-headers", ARG_BOOL, ' ', C_SUPPRESS_CONNECT_HEADERS}, + {"tcp-fastopen", ARG_BOOL, ' ', C_TCP_FASTOPEN}, + {"tcp-nodelay", ARG_BOOL, ' ', C_TCP_NODELAY}, + {"telnet-option", ARG_STRG, 't', C_TELNET_OPTION}, + {"test-event", ARG_BOOL, ' ', C_TEST_EVENT}, + {"tftp-blksize", ARG_STRG, ' ', C_TFTP_BLKSIZE}, + {"tftp-no-options", ARG_BOOL, ' ', C_TFTP_NO_OPTIONS}, + {"time-cond", ARG_STRG, 'z', C_TIME_COND}, + {"tls-max", ARG_STRG, ' ', C_TLS_MAX}, + {"tls13-ciphers", ARG_STRG, ' ', C_TLS13_CIPHERS}, + {"tlsauthtype", ARG_STRG, ' ', C_TLSAUTHTYPE}, + {"tlspassword", ARG_STRG, ' ', C_TLSPASSWORD}, + {"tlsuser", ARG_STRG, ' ', C_TLSUSER}, + {"tlsv1", ARG_NONE, '1', C_TLSV1}, + {"tlsv1.0", ARG_NONE, ' ', C_TLSV1_0}, + {"tlsv1.1", ARG_NONE, ' ', C_TLSV1_1}, + {"tlsv1.2", ARG_NONE, ' ', C_TLSV1_2}, + {"tlsv1.3", ARG_NONE, ' ', C_TLSV1_3}, + {"tr-encoding", ARG_BOOL, ' ', C_TR_ENCODING}, + {"trace", ARG_FILE, ' ', C_TRACE}, + {"trace-ascii", ARG_FILE, ' ', C_TRACE_ASCII}, + {"trace-config", ARG_STRG, ' ', C_TRACE_CONFIG}, + {"trace-ids", ARG_BOOL, ' ', C_TRACE_IDS}, + {"trace-time", ARG_BOOL, ' ', C_TRACE_TIME}, + {"unix-socket", ARG_FILE, ' ', C_UNIX_SOCKET}, + {"upload-file", ARG_FILE, 'T', C_UPLOAD_FILE}, + {"url", ARG_STRG, ' ', C_URL}, + {"url-query", ARG_STRG, ' ', C_URL_QUERY}, + {"use-ascii", ARG_BOOL, 'B', C_USE_ASCII}, + {"user", ARG_STRG, 'u', C_USER}, + {"user-agent", ARG_STRG, 'A', C_USER_AGENT}, + {"variable", ARG_STRG, ' ', C_VARIABLE}, + {"verbose", ARG_BOOL, 'v', C_VERBOSE}, + {"version", ARG_BOOL, 'V', C_VERSION}, #ifdef USE_WATT32 - {"wdebug", ARG_BOOL, "*p"}, + {"wdebug", ARG_BOOL, ' ', C_WDEBUG}, #endif - {"write-out", ARG_STRING, "w",}, - {"xattr", ARG_BOOL, "*~"}, + {"write-out", ARG_STRG, 'w', C_WRITE_OUT}, + {"xattr", ARG_BOOL, ' ', C_XATTR}, }; /* Split the argument of -E to 'certname' and 'passphrase' separated by colon. @@ -743,8 +1014,8 @@ static const struct LongShort *single(char letter) if(!singles_done) { unsigned int j; for(j = 0; j < sizeof(aliases)/sizeof(aliases[0]); j++) { - if(!aliases[j].letter[1]) { - unsigned char l = aliases[j].letter[0]; + if(aliases[j].letter != ' ') { + unsigned char l = aliases[j].letter; singles[l - ' '] = &aliases[j]; } } @@ -790,7 +1061,7 @@ static ParameterError url_query(char *nextarg, return err; } -static ParameterError set_data(char subletter, +static ParameterError set_data(cmdline_t cmd, char *nextarg, struct GlobalConfig *global, struct OperationConfig *config) @@ -800,19 +1071,19 @@ static ParameterError set_data(char subletter, size_t size = 0; ParameterError err = PARAM_OK; - if(subletter == 'e') { /* --data-urlencode */ + if(cmd == C_DATA_URLENCODE) { /* --data-urlencode */ err = data_urlencode(global, nextarg, &postdata, &size); if(err) return err; } - else if('@' == *nextarg && (subletter != 'r')) { + else if('@' == *nextarg && (cmd != C_DATA_RAW)) { /* the data begins with a '@' letter, it means that a file name or - (stdin) follows */ nextarg++; /* pass the @ */ if(!strcmp("-", nextarg)) { file = stdin; - if(subletter == 'b') /* forced data-binary */ + if(cmd == C_DATA_BINARY) /* forced data-binary */ set_binmode(stdin); } else { @@ -823,8 +1094,8 @@ static ParameterError set_data(char subletter, } } - if((subletter == 'b') || /* --data-binary */ - (subletter == 'f') /* --json */) + if((cmd == C_DATA_BINARY) || /* --data-binary */ + (cmd == C_JSON) /* --json */) /* forced binary */ err = file2memory(&postdata, &size, file); else { @@ -853,12 +1124,12 @@ static ParameterError set_data(char subletter, if(postdata) size = strlen(postdata); } - if(subletter == 'f') + if(cmd == C_JSON) config->jsoned = TRUE; if(curlx_dyn_len(&config->postdata)) { /* skip separator append for --json */ - if(!err && (subletter != 'f') && + if(!err && (cmd != C_JSON) && curlx_dyn_addn(&config->postdata, "&", 1)) err = PARAM_NO_MEM; } @@ -873,8 +1144,6 @@ static ParameterError set_data(char subletter, } -#define ONEOPT(x,y) (((int)x << 8) | y) - ParameterError getparameter(const char *flag, /* f or -long-flag */ char *nextarg, /* NULL if unset */ argv_item_t cleararg, @@ -883,8 +1152,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ struct GlobalConfig *global, struct OperationConfig *config) { - char letter; - char subletter = '\0'; /* subletters can only occur on long options */ int rc; const char *parse = NULL; time_t now; @@ -936,7 +1203,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ sizeof(aliases[0]), findarg); if(a) { longopt = TRUE; - parse = a->letter; } else { err = PARAM_OPTION_UNKNOWN; @@ -951,8 +1217,8 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ struct curlx_dynbuf nbuf; bool replaced; - if((a->desc != ARG_STRING) && - (a->desc != ARG_FILENAME)) { + if((a->desc != ARG_STRG) && + (a->desc != ARG_FILE)) { /* --expand on an option that isn't a string or a filename */ err = PARAM_EXPAND_ERROR; goto error; @@ -975,25 +1241,19 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ do { /* we can loop here if we have multiple single-letters */ + char letter; + cmdline_t cmd; - if(!longopt) { - letter = (char)*parse; - subletter = '\0'; - } - else { - letter = parse[0]; - subletter = parse[1]; - } - - if(!a) { - a = single(letter); + if(!longopt && !a) { + a = single(*parse); if(!a) { err = PARAM_OPTION_UNKNOWN; break; } } - - if(a->desc >= ARG_STRING) { + letter = a->letter; + cmd = a->cmd; + if(a->desc >= ARG_STRG) { /* this option requires an extra parameter */ if(!longopt && parse[1]) { nextarg = (char *)&parse[1]; /* this is the actual extra parameter */ @@ -1010,7 +1270,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ *usedarg = TRUE; /* mark it as used */ } - if((a->desc == ARG_FILENAME) && + if((a->desc == ARG_FILE) && (nextarg[0] == '-') && nextarg[1]) { /* if the file name looks like a command line option */ warnf(global, "The file name argument '%s' looks like a flag.", @@ -1029,68 +1289,68 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ that aware of that state */ nextarg = (char *)""; - switch(ONEOPT(letter, subletter)) { - case ONEOPT('*', '4'): /* --dns-ipv4-addr */ + switch(cmd) { + case C_DNS_IPV4_ADDR: /* --dns-ipv4-addr */ if(!curlinfo->ares_num) /* c-ares is needed for this */ err = PARAM_LIBCURL_DOESNT_SUPPORT; else /* addr in dot notation */ err = getstr(&config->dns_ipv4_addr, nextarg, DENY_BLANK); break; - case ONEOPT('*', '6'): /* --dns-ipv6-addr */ + case C_DNS_IPV6_ADDR: /* --dns-ipv6-addr */ if(!curlinfo->ares_num) /* c-ares is needed for this */ err = PARAM_LIBCURL_DOESNT_SUPPORT; else /* addr in dot notation */ err = getstr(&config->dns_ipv6_addr, nextarg, DENY_BLANK); break; - case ONEOPT('*', 'a'): /* --random-file */ + case C_RANDOM_FILE: /* --random-file */ break; - case ONEOPT('*', 'b'): /* --egd-file */ + case C_EGD_FILE: /* --egd-file */ break; - case ONEOPT('*', 'B'): /* --oauth2-bearer */ + case C_OAUTH2_BEARER: /* --oauth2-bearer */ err = getstr(&config->oauth_bearer, nextarg, DENY_BLANK); if(!err) { cleanarg(clearthis); config->authtype |= CURLAUTH_BEARER; } break; - case ONEOPT('*', 'c'): /* --connect-timeout */ + case C_CONNECT_TIMEOUT: /* --connect-timeout */ err = secs2ms(&config->connecttimeout_ms, nextarg); break; - case ONEOPT('*', 'C'): /* --doh-url */ + case C_DOH_URL: /* --doh-url */ err = getstr(&config->doh_url, nextarg, ALLOW_BLANK); if(!err && config->doh_url && !config->doh_url[0]) /* if given a blank string, make it NULL again */ Curl_safefree(config->doh_url); break; - case ONEOPT('*', 'd'): /* -- ciphers */ + case C_CIPHERS: /* -- ciphers */ err = getstr(&config->cipher_list, nextarg, DENY_BLANK); break; - case ONEOPT('*', 'D'): /* --dns-interface */ + case C_DNS_INTERFACE: /* --dns-interface */ if(!curlinfo->ares_num) /* c-ares is needed for this */ err = PARAM_LIBCURL_DOESNT_SUPPORT; else /* interface name */ err = getstr(&config->dns_interface, nextarg, DENY_BLANK); break; - case ONEOPT('*', 'e'): /* --disable-epsv */ + case C_DISABLE_EPSV: /* --disable-epsv */ config->disable_epsv = toggle; break; - case ONEOPT('*', 'f'): /* --disallow-username-in-url */ + case C_DISALLOW_USERNAME_IN_URL: /* --disallow-username-in-url */ config->disallow_username_in_url = toggle; break; - case ONEOPT('*', 'E'): /* --epsv */ + case C_EPSV: /* --epsv */ config->disable_epsv = (!toggle)?TRUE:FALSE; break; - case ONEOPT('*', 'F'): /* --dns-servers */ + case C_DNS_SERVERS: /* --dns-servers */ if(!curlinfo->ares_num) /* c-ares is needed for this */ err = PARAM_LIBCURL_DOESNT_SUPPORT; else /* IP addrs of DNS servers */ err = getstr(&config->dns_servers, nextarg, DENY_BLANK); break; - case ONEOPT('*', 'g'): /* --trace */ + case C_TRACE: /* --trace */ err = getstr(&global->trace_dump, nextarg, DENY_BLANK); if(!err) { if(global->tracetype && (global->tracetype != TRACE_BIN)) @@ -1098,10 +1358,10 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ global->tracetype = TRACE_BIN; } break; - case ONEOPT('*', 'G'): /* --npn */ + case C_NPN: /* --npn */ warnf(global, "--npn is no longer supported"); break; - case ONEOPT('*', 'h'): /* --trace-ascii */ + case C_TRACE_ASCII: /* --trace-ascii */ err = getstr(&global->trace_dump, nextarg, DENY_BLANK); if(!err) { if(global->tracetype && (global->tracetype != TRACE_ASCII)) @@ -1110,17 +1370,17 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ global->tracetype = TRACE_ASCII; } break; - case ONEOPT('*', 'H'): /* --alpn */ + case C_ALPN: /* --alpn */ config->noalpn = (!toggle)?TRUE:FALSE; break; - case ONEOPT('*', 'i'): /* --limit-rate */ + case C_LIMIT_RATE: /* --limit-rate */ err = GetSizeParameter(global, nextarg, "rate", &value); if(!err) { config->recvpersecond = value; config->sendpersecond = value; } break; - case ONEOPT('*', 'I'): { /* --rate */ + case C_RATE: { /* --rate */ /* support a few different suffixes, extract the suffix first, then get the number and convert to per hour. /s == per second @@ -1177,25 +1437,25 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } break; - case ONEOPT('*', 'j'): /* --compressed */ + case C_COMPRESSED: /* --compressed */ if(toggle && !(feature_libz || feature_brotli || feature_zstd)) err = PARAM_LIBCURL_DOESNT_SUPPORT; else config->encoding = toggle; break; - case ONEOPT('*', 'J'): /* --tr-encoding */ + case C_TR_ENCODING: /* --tr-encoding */ config->tr_encoding = toggle; break; - case ONEOPT('*', 'k'): /* --digest */ + case C_DIGEST: /* --digest */ if(toggle) config->authtype |= CURLAUTH_DIGEST; else config->authtype &= ~CURLAUTH_DIGEST; break; - case ONEOPT('*', 'l'): /* --negotiate */ + case C_NEGOTIATE: /* --negotiate */ if(!toggle) config->authtype &= ~CURLAUTH_NEGOTIATE; else if(feature_spnego) @@ -1204,7 +1464,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case ONEOPT('*', 'm'): /* --ntlm */ + case C_NTLM: /* --ntlm */ if(!toggle) config->authtype &= ~CURLAUTH_NTLM; else if(feature_ntlm) @@ -1213,7 +1473,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case ONEOPT('*', 'M'): /* --ntlm-wb */ + case C_NTLM_WB: /* --ntlm-wb */ if(!toggle) config->authtype &= ~CURLAUTH_NTLM_WB; else if(feature_ntlm_wb) @@ -1222,37 +1482,37 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case ONEOPT('*', 'n'): /* --basic */ + case C_BASIC: /* --basic */ if(toggle) config->authtype |= CURLAUTH_BASIC; else config->authtype &= ~CURLAUTH_BASIC; break; - case ONEOPT('*', 'o'): /* --anyauth */ + case C_ANYAUTH: /* --anyauth */ if(toggle) config->authtype = CURLAUTH_ANY; /* --no-anyauth simply doesn't touch it */ break; #ifdef USE_WATT32 - case ONEOPT('*', 'p'): /* --wdebug */ + case C_WDEBUG: /* --wdebug */ dbug_init(); break; #endif - case ONEOPT('*', 'q'): /* --ftp-create-dirs */ + case C_FTP_CREATE_DIRS: /* --ftp-create-dirs */ config->ftp_create_dirs = toggle; break; - case ONEOPT('*', 'r'): /* --create-dirs */ + case C_CREATE_DIRS: /* --create-dirs */ config->create_dirs = toggle; break; - case ONEOPT('*', 'R'): /* --create-file-mode */ + case C_CREATE_FILE_MODE: /* --create-file-mode */ err = oct2nummax(&config->create_file_mode, nextarg, 0777); break; - case ONEOPT('*', 's'): /* --max-redirs */ + case C_MAX_REDIRS: /* --max-redirs */ /* specified max no of redirects (http(s)), this accepts -1 as a special condition */ err = str2num(&config->maxredirs, nextarg); @@ -1260,62 +1520,62 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_BAD_NUMERIC; break; - case ONEOPT('*', 'S'): /* --ipfs-gateway */ + case C_IPFS_GATEWAY: /* --ipfs-gateway */ err = getstr(&config->ipfs_gateway, nextarg, DENY_BLANK); break; - case ONEOPT('*', 't'): /* --proxy-ntlm */ + case C_PROXY_NTLM: /* --proxy-ntlm */ if(!feature_ntlm) err = PARAM_LIBCURL_DOESNT_SUPPORT; else config->proxyntlm = toggle; break; - case ONEOPT('*', 'u'): /* --crlf */ + case C_CRLF: /* --crlf */ /* LF -> CRLF conversion? */ config->crlf = toggle; break; - case ONEOPT('*', 'V'): /* --aws-sigv4 */ + case C_AWS_SIGV4: /* --aws-sigv4 */ config->authtype |= CURLAUTH_AWS_SIGV4; err = getstr(&config->aws_sigv4, nextarg, DENY_BLANK); break; - case ONEOPT('*', 'v'): /* --stderr */ + case C_STDERR: /* --stderr */ tool_set_stderr_file(global, nextarg); break; - case ONEOPT('*', 'w'): /* --interface */ + case C_INTERFACE: /* --interface */ /* interface */ err = getstr(&config->iface, nextarg, DENY_BLANK); break; - case ONEOPT('*', 'x'): /* --krb */ + case C_KRB: /* --krb */ /* kerberos level string */ if(!feature_spnego) err = PARAM_LIBCURL_DOESNT_SUPPORT; else err = getstr(&config->krblevel, nextarg, DENY_BLANK); break; - case ONEOPT('*', 'X'): /* --haproxy-protocol */ + case C_HAPROXY_PROTOCOL: /* --haproxy-protocol */ config->haproxy_protocol = toggle; break; - case ONEOPT('*', 'P'): /* --haproxy-clientip */ + case C_HAPROXY_CLIENTIP: /* --haproxy-clientip */ err = getstr(&config->haproxy_clientip, nextarg, DENY_BLANK); break; - case ONEOPT('*', 'y'): /* --max-filesize */ + case C_MAX_FILESIZE: /* --max-filesize */ err = GetSizeParameter(global, nextarg, "max-filesize", &value); if(!err) config->max_filesize = value; break; - case ONEOPT('*', 'z'): /* --disable-eprt */ + case C_DISABLE_EPRT: /* --disable-eprt */ config->disable_eprt = toggle; break; - case ONEOPT('*', 'Z'): /* --eprt */ + case C_EPRT: /* --eprt */ config->disable_eprt = (!toggle)?TRUE:FALSE; break; - case ONEOPT('*', '~'): /* --xattr */ + case C_XATTR: /* --xattr */ config->xattr = toggle; break; - case ONEOPT('*', '@'): /* --url */ + case C_URL: /* --url */ if(!config->url_get) config->url_get = config->url_list; @@ -1335,105 +1595,103 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ /* there was no free node, create one! */ config->url_get = url = new_getout(config); - if(!url) { + if(!url) err = PARAM_NO_MEM; - break; + else { + /* fill in the URL */ + err = getstr(&url->url, nextarg, DENY_BLANK); + url->flags |= GETOUT_URL; } - - /* fill in the URL */ - err = getstr(&url->url, nextarg, DENY_BLANK); - url->flags |= GETOUT_URL; break; - case ONEOPT('$', 'a'): /* --ssl */ - if(toggle && !feature_ssl) { + case C_SSL: /* --ssl */ + if(toggle && !feature_ssl) err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; + else { + config->ftp_ssl = toggle; + if(config->ftp_ssl) + warnf(global, + "--ssl is an insecure option, consider --ssl-reqd instead"); } - config->ftp_ssl = toggle; - if(config->ftp_ssl) - warnf(global, - "--ssl is an insecure option, consider --ssl-reqd instead"); break; - case ONEOPT('$', 'b'): /* --ftp-pasv */ + case C_FTP_PASV: /* --ftp-pasv */ Curl_safefree(config->ftpport); break; - case ONEOPT('$', 'c'): /* --socks5 */ + case C_SOCKS5: /* --socks5 */ /* socks5 proxy to use, and resolves the name locally and passes on the resolved address */ err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_SOCKS5; break; - case ONEOPT('$', 't'): /* --socks4 */ + case C_SOCKS4: /* --socks4 */ err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_SOCKS4; break; - case ONEOPT('$', 'T'): /* --socks4a */ + case C_SOCKS4A: /* --socks4a */ err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_SOCKS4A; break; - case ONEOPT('$', '2'): /* --socks5-hostname */ + case C_SOCKS5_HOSTNAME: /* --socks5-hostname */ err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_SOCKS5_HOSTNAME; break; - case ONEOPT('$', 'd'): /* --tcp-nodelay */ + case C_TCP_NODELAY: /* --tcp-nodelay */ config->tcp_nodelay = toggle; break; - case ONEOPT('$', 'e'): /* --proxy-digest */ + case C_PROXY_DIGEST: /* --proxy-digest */ config->proxydigest = toggle; break; - case ONEOPT('$', 'f'): /* --proxy-basic */ + case C_PROXY_BASIC: /* --proxy-basic */ config->proxybasic = toggle; break; - case ONEOPT('$', 'g'): /* --retry */ + case C_RETRY: /* --retry */ err = str2unum(&config->req_retry, nextarg); break; - case ONEOPT('$', 'V'): /* --retry-connrefused */ + case C_RETRY_CONNREFUSED: /* --retry-connrefused */ config->retry_connrefused = toggle; break; - case ONEOPT('$', 'h'): /* --retry-delay */ + case C_RETRY_DELAY: /* --retry-delay */ err = str2unummax(&config->retry_delay, nextarg, LONG_MAX/1000); break; - case ONEOPT('$', 'i'): /* --retry-max-time */ + case C_RETRY_MAX_TIME: /* --retry-max-time */ err = str2unummax(&config->retry_maxtime, nextarg, LONG_MAX/1000); break; - case ONEOPT('$', '!'): /* --retry-all-errors */ + case C_RETRY_ALL_ERRORS: /* --retry-all-errors */ config->retry_all_errors = toggle; break; - case ONEOPT('$', 'k'): /* --proxy-negotiate */ - if(!feature_spnego) { + case C_PROXY_NEGOTIATE: /* --proxy-negotiate */ + if(!feature_spnego) err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - config->proxynegotiate = toggle; + else + config->proxynegotiate = toggle; break; - case ONEOPT('$', 'l'): /* --form-escape */ + case C_FORM_ESCAPE: /* --form-escape */ config->mime_options &= ~CURLMIMEOPT_FORMESCAPE; if(toggle) config->mime_options |= CURLMIMEOPT_FORMESCAPE; break; - case ONEOPT('$', 'm'): /* --ftp-account */ + case C_FTP_ACCOUNT: /* --ftp-account */ err = getstr(&config->ftp_account, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'n'): /* --proxy-anyauth */ + case C_PROXY_ANYAUTH: /* --proxy-anyauth */ config->proxyanyauth = toggle; break; - case ONEOPT('$', 'o'): /* --trace-time */ + case C_TRACE_TIME: /* --trace-time */ global->tracetime = toggle; break; - case ONEOPT('$', 'p'): /* --ignore-content-length */ + case C_IGNORE_CONTENT_LENGTH: /* --ignore-content-length */ config->ignorecl = toggle; break; - case ONEOPT('$', 'q'): /* --ftp-skip-pasv-ip */ + case C_FTP_SKIP_PASV_IP: /* --ftp-skip-pasv-ip */ config->ftp_skip_ip = toggle; break; - case ONEOPT('$', 'r'): /* --ftp-method */ + case C_FTP_METHOD: /* --ftp-method */ config->ftp_filemethod = ftpfilemethod(config, nextarg); break; - case ONEOPT('$', 's'): { /* --local-port */ + case C_LOCAL_PORT: { /* --local-port */ /* 16bit base 10 is 5 digits, but we allow 6 so that this catches overflows, not just truncates */ char lrange[7]=""; @@ -1467,36 +1725,36 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } break; } - case ONEOPT('$', 'u'): /* --ftp-alternative-to-user */ + case C_FTP_ALTERNATIVE_TO_USER: /* --ftp-alternative-to-user */ err = getstr(&config->ftp_alternative_to_user, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'v'): /* --ssl-reqd */ + case C_FTP_SSL_REQD: /* --ftp-ssl-reqd */ + case C_SSL_REQD: /* --ssl-reqd */ if(toggle && !feature_ssl) { err = PARAM_LIBCURL_DOESNT_SUPPORT; break; } config->ftp_ssl_reqd = toggle; break; - case ONEOPT('$', 'w'): /* --no-sessionid */ + case C_SESSIONID: /* --sessionid */ config->disable_sessionid = (!toggle)?TRUE:FALSE; break; - case ONEOPT('$', 'x'): /* --ftp-ssl-control */ - if(toggle && !feature_ssl) { + case C_FTP_SSL_CONTROL: /* --ftp-ssl-control */ + if(toggle && !feature_ssl) err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - config->ftp_ssl_control = toggle; + else + config->ftp_ssl_control = toggle; break; - case ONEOPT('$', 'y'): /* --ftp-ssl-ccc */ + case C_FTP_SSL_CCC: /* --ftp-ssl-ccc */ config->ftp_ssl_ccc = toggle; if(!config->ftp_ssl_ccc_mode) config->ftp_ssl_ccc_mode = CURLFTPSSL_CCC_PASSIVE; break; - case ONEOPT('$', 'j'): /* --ftp-ssl-ccc-mode */ + case C_FTP_SSL_CCC_MODE: /* --ftp-ssl-ccc-mode */ config->ftp_ssl_ccc = TRUE; config->ftp_ssl_ccc_mode = ftpcccmethod(config, nextarg); break; - case ONEOPT('$', 'z'): /* --libcurl */ + case C_LIBCURL: /* --libcurl */ #ifdef CURL_DISABLE_LIBCURL_OPTION warnf(global, "--libcurl option was disabled at build-time"); @@ -1505,251 +1763,245 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = getstr(&global->libcurl, nextarg, DENY_BLANK); #endif break; - case ONEOPT('$', '#'): /* --raw */ + case C_RAW: /* --raw */ config->raw = toggle; break; - case ONEOPT('$', '0'): /* --post301 */ - config->post301 = toggle; - break; - case ONEOPT('$', '1'): /* --no-keepalive */ + case C_KEEPALIVE: /* --keepalive */ config->nokeepalive = (!toggle)?TRUE:FALSE; break; - case ONEOPT('$', '3'): /* --keepalive-time */ + case C_KEEPALIVE_TIME: /* --keepalive-time */ err = str2unum(&config->alivetime, nextarg); break; - case ONEOPT('$', '4'): /* --post302 */ + case C_POST301: /* --post301 */ + config->post301 = toggle; + break; + case C_POST302: /* --post302 */ config->post302 = toggle; break; - case ONEOPT('$', 'I'): /* --post303 */ + case C_POST303: /* --post303 */ config->post303 = toggle; break; - case ONEOPT('$', '5'): /* --noproxy */ + case C_NOPROXY: /* --noproxy */ /* This specifies the noproxy list */ err = getstr(&config->noproxy, nextarg, ALLOW_BLANK); break; - case ONEOPT('$', '7'): /* --socks5-gssapi-nec */ + case C_SOCKS5_GSSAPI_NEC: /* --socks5-gssapi-nec */ config->socks5_gssapi_nec = toggle; break; - case ONEOPT('$', '8'): /* --proxy1.0 */ + case C_PROXY1_0: /* --proxy1.0 */ /* http 1.0 proxy */ err = getstr(&config->proxy, nextarg, DENY_BLANK); config->proxyver = CURLPROXY_HTTP_1_0; break; - case ONEOPT('$', '9'): /* --tftp-blksize */ + case C_TFTP_BLKSIZE: /* --tftp-blksize */ err = str2unum(&config->tftp_blksize, nextarg); break; - case ONEOPT('$', 'A'): /* --mail-from */ + case C_MAIL_FROM: /* --mail-from */ err = getstr(&config->mail_from, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'B'): /* --mail-rcpt */ + case C_MAIL_RCPT: /* --mail-rcpt */ /* append receiver to a list */ err = add2list(&config->mail_rcpt, nextarg); break; - case ONEOPT('$', 'C'): /* --ftp-pret */ + case C_FTP_PRET: /* --ftp-pret */ config->ftp_pret = toggle; break; - case ONEOPT('$', 'D'): /* --proto */ + case C_PROTO: /* --proto */ config->proto_present = TRUE; err = proto2num(config, built_in_protos, &config->proto_str, nextarg); break; - case ONEOPT('$', 'E'): /* --proto-redir */ + case C_PROTO_REDIR: /* --proto-redir */ config->proto_redir_present = TRUE; if(proto2num(config, redir_protos, &config->proto_redir_str, - nextarg)) { + nextarg)) err = PARAM_BAD_USE; - break; - } break; - case ONEOPT('$', 'F'): /* --resolve */ + case C_RESOLVE: /* --resolve */ err = add2list(&config->resolve, nextarg); break; - case ONEOPT('$', 'G'): /* --delegation */ + case C_DELEGATION: /* --delegation */ config->gssapi_delegation = delegation(config, nextarg); break; - case ONEOPT('$', 'H'): /* --mail-auth */ + case C_MAIL_AUTH: /* --mail-auth */ err = getstr(&config->mail_auth, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'J'): /* --metalink */ + case C_METALINK: /* --metalink */ errorf(global, "--metalink is disabled"); err = PARAM_BAD_USE; break; - case ONEOPT('$', '6'): /* --sasl-authzid */ + case C_SASL_AUTHZID: /* --sasl-authzid */ err = getstr(&config->sasl_authzid, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'K'): /* --sasl-ir */ + case C_SASL_IR: /* --sasl-ir */ config->sasl_ir = toggle; break; - case ONEOPT('$', 'L'): /* --test-event */ + case C_TEST_EVENT: /* --test-event */ #ifdef CURLDEBUG global->test_event_based = toggle; #else warnf(global, "--test-event is ignored unless a debug build"); #endif break; - case ONEOPT('$', 'M'): /* --unix-socket */ + case C_UNIX_SOCKET: /* --unix-socket */ config->abstract_unix_socket = FALSE; err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'N'): /* --path-as-is */ + case C_PATH_AS_IS: /* --path-as-is */ config->path_as_is = toggle; break; - case ONEOPT('$', 'O'): /* --proxy-service-name */ + case C_PROXY_SERVICE_NAME: /* --proxy-service-name */ err = getstr(&config->proxy_service_name, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'P'): /* --service-name */ + case C_SERVICE_NAME: /* --service-name */ err = getstr(&config->service_name, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'Q'): /* --proto-default */ + case C_PROTO_DEFAULT: /* --proto-default */ err = getstr(&config->proto_default, nextarg, DENY_BLANK); if(!err) err = check_protocol(config->proto_default); break; - case ONEOPT('$', 'R'): /* --expect100-timeout */ + case C_EXPECT100_TIMEOUT: /* --expect100-timeout */ err = secs2ms(&config->expect100timeout_ms, nextarg); break; - case ONEOPT('$', 'S'): /* --tftp-no-options */ + case C_TFTP_NO_OPTIONS: /* --tftp-no-options */ config->tftp_no_options = toggle; break; - case ONEOPT('$', 'U'): /* --connect-to */ + case C_CONNECT_TO: /* --connect-to */ err = add2list(&config->connect_to, nextarg); break; - case ONEOPT('$', 'W'): /* --abstract-unix-socket */ + case C_ABSTRACT_UNIX_SOCKET: /* --abstract-unix-socket */ config->abstract_unix_socket = TRUE; err = getstr(&config->unix_socket_path, nextarg, DENY_BLANK); break; - case ONEOPT('$', 'X'): /* --tls-max */ + case C_TLS_MAX: /* --tls-max */ err = str2tls_max(&config->ssl_version_max, nextarg); break; - case ONEOPT('$', 'Y'): /* --suppress-connect-headers */ + case C_SUPPRESS_CONNECT_HEADERS: /* --suppress-connect-headers */ config->suppress_connect_headers = toggle; break; - case ONEOPT('$', 'Z'): /* --compressed-ssh */ + case C_COMPRESSED_SSH: /* --compressed-ssh */ config->ssh_compression = toggle; break; - case ONEOPT('$', '~'): /* --happy-eyeballs-timeout-ms */ + case C_HAPPY_EYEBALLS_TIMEOUT_MS: /* --happy-eyeballs-timeout-ms */ err = str2unum(&config->happy_eyeballs_timeout_ms, nextarg); /* 0 is a valid value for this timeout */ break; - case ONEOPT('$', '%'): /* --trace-ids */ + case C_TRACE_IDS: /* --trace-ids */ global->traceids = toggle; break; - case ONEOPT('$', '&'): /* --trace-config */ - if(set_trace_config(global, nextarg)) { + case C_TRACE_CONFIG: /* --trace-config */ + if(set_trace_config(global, nextarg)) err = PARAM_NO_MEM; - } break; - case ONEOPT('#', 'm'): /* --progress-meter */ + case C_PROGRESS_METER: /* --progress-meter */ global->noprogress = !toggle; break; - case ONEOPT('#', '\0'): /* --progress-bar */ + case C_PROGRESS_BAR: /* --progress-bar */ global->progressmode = toggle ? CURL_PROGRESS_BAR : CURL_PROGRESS_STATS; break; - - case ONEOPT(':', 'a'): /* --variable */ + case C_VARIABLE: /* --Variable */ err = setvariable(global, nextarg); break; - case ONEOPT(':', '\0'): /* --next */ + case C_NEXT: /* --next */ err = PARAM_NEXT_OPERATION; break; - - case ONEOPT('0', '\0'): /* --http1.0 */ + case C_HTTP1_0: /* --http1.0 */ /* HTTP version 1.0 */ sethttpver(global, config, CURL_HTTP_VERSION_1_0); break; - case ONEOPT('0', '1'): /* --http1.1 */ + case C_HTTP1_1: /* --http1.1 */ /* HTTP version 1.1 */ sethttpver(global, config, CURL_HTTP_VERSION_1_1); break; - case ONEOPT('0', '2'): /* --http2 */ + case C_HTTP2: /* --http2 */ /* HTTP version 2.0 */ if(!feature_http2) return PARAM_LIBCURL_DOESNT_SUPPORT; sethttpver(global, config, CURL_HTTP_VERSION_2_0); break; - case ONEOPT('0', '3'): /* --http2-prior-knowledge */ + case C_HTTP2_PRIOR_KNOWLEDGE: /* --http2-prior-knowledge */ /* HTTP version 2.0 over clean TCP */ if(!feature_http2) return PARAM_LIBCURL_DOESNT_SUPPORT; sethttpver(global, config, CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE); break; - case ONEOPT('0', '4'): /* --http3: */ + case C_HTTP3: /* --http3: */ /* Try HTTP/3, allow fallback */ - if(!feature_http3) { + if(!feature_http3) err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - sethttpver(global, config, CURL_HTTP_VERSION_3); + else + sethttpver(global, config, CURL_HTTP_VERSION_3); break; - case ONEOPT('0', '5'): /* --http3-only */ + case C_HTTP3_ONLY: /* --http3-only */ /* Try HTTP/3 without fallback */ - if(!feature_http3) { + if(!feature_http3) err = PARAM_LIBCURL_DOESNT_SUPPORT; - break; - } - sethttpver(global, config, CURL_HTTP_VERSION_3ONLY); + else + sethttpver(global, config, CURL_HTTP_VERSION_3ONLY); break; - case ONEOPT('0', '9'): /* --http0.9 */ + case C_HTTP0_9: /* --http0.9 */ /* Allow HTTP/0.9 responses! */ config->http09_allowed = toggle; break; - case ONEOPT('0', 'a'): /* --proxy-http2 */ + case C_PROXY_HTTP2: /* --proxy-http2 */ if(!feature_httpsproxy || !feature_http2) - return PARAM_LIBCURL_DOESNT_SUPPORT; - config->proxyver = CURLPROXY_HTTPS2; + err = PARAM_LIBCURL_DOESNT_SUPPORT; + else + config->proxyver = CURLPROXY_HTTPS2; break; - case ONEOPT('1', '\0'): /* --tlsv1 */ + case C_TLSV1: /* --tlsv1 */ config->ssl_version = CURL_SSLVERSION_TLSv1; break; - case ONEOPT('1', '0'): /* --tlsv1.0 */ + case C_TLSV1_0: /* --tlsv1.0 */ config->ssl_version = CURL_SSLVERSION_TLSv1_0; break; - case ONEOPT('1', '1'): /* --tlsv1.1 */ + case C_TLSV1_1: /* --tlsv1.1 */ config->ssl_version = CURL_SSLVERSION_TLSv1_1; break; - case ONEOPT('1', '2'): /* --tlsv1.2 */ + case C_TLSV1_2: /* --tlsv1.2 */ config->ssl_version = CURL_SSLVERSION_TLSv1_2; break; - case ONEOPT('1', '3'): /* --tlsv1.3 */ + case C_TLSV1_3: /* --tlsv1.3 */ config->ssl_version = CURL_SSLVERSION_TLSv1_3; break; - case ONEOPT('1', 'A'): /* --tls13-ciphers */ + case C_TLS13_CIPHERS: /* --tls13-ciphers */ err = getstr(&config->cipher13_list, nextarg, DENY_BLANK); break; - case ONEOPT('1', 'B'): /* --proxy-tls13-ciphers */ + case C_PROXY_TLS13_CIPHERS: /* --proxy-tls13-ciphers */ err = getstr(&config->proxy_cipher13_list, nextarg, DENY_BLANK); break; - case ONEOPT('2', '\0'): /* --sslv2 */ + case C_SSLV2: /* --sslv2 */ warnf(global, "Ignores instruction to use SSLv2"); break; - case ONEOPT('3', '\0'): /* --sslv3 */ + case C_SSLV3: /* --sslv3 */ warnf(global, "Ignores instruction to use SSLv3"); break; - case ONEOPT('4', '\0'): /* --ipv4 */ + case C_IPV4: /* --ipv4 */ config->ip_version = CURL_IPRESOLVE_V4; break; - case ONEOPT('6', '\0'): /* --ipv6 */ + case C_IPV6: /* --ipv6 */ config->ip_version = CURL_IPRESOLVE_V6; break; - case ONEOPT('a', '\0'): /* --append */ + case C_APPEND: /* --append */ /* This makes the FTP sessions use APPE instead of STOR */ config->ftp_append = toggle; break; - case ONEOPT('A', '\0'): /* --user-agent */ + case C_USER_AGENT: /* --user-agent */ err = getstr(&config->useragent, nextarg, ALLOW_BLANK); break; - case ONEOPT('b', 'a'): /* --alt-svc */ + case C_ALT_SVC: /* --alt-svc */ if(!feature_altsvc) err = PARAM_LIBCURL_DOESNT_SUPPORT; else err = getstr(&config->altsvc, nextarg, ALLOW_BLANK); break; - case ONEOPT('b', 'b'): /* --hsts */ + case C_HSTS: /* --hsts */ if(!feature_hsts) err = PARAM_LIBCURL_DOESNT_SUPPORT; else err = getstr(&config->hsts, nextarg, ALLOW_BLANK); break; - case ONEOPT('b', '\0'): /* --cookie */ + case C_COOKIE: /* --cookie */ if(nextarg[0] == '@') { nextarg++; } @@ -1761,18 +2013,16 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ /* We have a cookie file to read from! */ err = add2list(&config->cookiefiles, nextarg); break; - case ONEOPT('B', '\0'): /* --use-ascii */ + case C_USE_ASCII: /* --use-ascii */ config->use_ascii = toggle; break; - case ONEOPT('c', '\0'): /* --cookie-jar */ + case C_COOKIE_JAR: /* --cookie-jar */ err = getstr(&config->cookiejar, nextarg, DENY_BLANK); break; - case ONEOPT('C', '\0'): /* --continue-at */ + case C_CONTINUE_AT: /* --continue-at */ /* This makes us continue an ftp transfer at given position */ if(strcmp(nextarg, "-")) { err = str2offset(&config->resume_from, nextarg); - if(err) - break; config->resume_from_current = FALSE; } else { @@ -1781,21 +2031,21 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } config->use_resume = TRUE; break; - case ONEOPT('d', '\0'): /* --data */ - case ONEOPT('d', 'a'): /* --data-ascii */ - case ONEOPT('d', 'b'): /* --data-binary */ - case ONEOPT('d', 'e'): /* --data-urlencode */ - case ONEOPT('d', 'f'): /* --json */ - case ONEOPT('d', 'r'): /* --data-raw */ - err = set_data(subletter, nextarg, global, config); + case C_DATA: /* --data */ + case C_DATA_ASCII: /* --data-ascii */ + case C_DATA_BINARY: /* --data-binary */ + case C_DATA_URLENCODE: /* --data-urlencode */ + case C_JSON: /* --json */ + case C_DATA_RAW: /* --data-raw */ + err = set_data(cmd, nextarg, global, config); break; - case ONEOPT('d', 'g'): /* --url-query */ + case C_URL_QUERY: /* --url-query */ err = url_query(nextarg, global, config); break; - case ONEOPT('D', '\0'): /* --dump-header */ + case C_DUMP_HEADER: /* --dump-header */ err = getstr(&config->headerfile, nextarg, DENY_BLANK); break; - case ONEOPT('e', '\0'): { /* --referer */ + case C_REFERER: { /* --referer */ char *ptr = strstr(nextarg, ";auto"); if(ptr) { /* Automatic referer requested, this may be combined with a @@ -1809,73 +2059,73 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = getstr(&config->referer, ptr, ALLOW_BLANK); } break; - case ONEOPT('E', '\0'): /* --cert */ + case C_CERT: /* --cert */ cleanarg(clearthis); GetFileAndPassword(nextarg, &config->cert, &config->key_passwd); break; - case ONEOPT('E', 'a'): /* --cacert */ + case C_CACERT: /* --cacert */ err = getstr(&config->cacert, nextarg, DENY_BLANK); break; - case ONEOPT('E', 'G'): /* --ca-native */ + case C_CA_NATIVE: /* --ca-native */ config->native_ca_store = toggle; break; - case ONEOPT('E', 'H'): /* --proxy-ca-native */ + case C_PROXY_CA_NATIVE: /* --proxy-ca-native */ config->proxy_native_ca_store = toggle; break; - case ONEOPT('E', 'b'): /* --cert-type */ + case C_CERT_TYPE: /* --cert-type */ err = getstr(&config->cert_type, nextarg, DENY_BLANK); break; - case ONEOPT('E', 'c'): /* --key */ + case C_KEY: /* --key */ err = getstr(&config->key, nextarg, DENY_BLANK); break; - case ONEOPT('E', 'd'): /* --key-type */ + case C_KEY_TYPE: /* --key-type */ err = getstr(&config->key_type, nextarg, DENY_BLANK); break; - case ONEOPT('E', 'e'): /* --pass */ + case C_PASS: /* --pass */ err = getstr(&config->key_passwd, nextarg, DENY_BLANK); cleanarg(clearthis); break; - case ONEOPT('E', 'f'): /* --engine */ + case C_ENGINE: /* --engine */ err = getstr(&config->engine, nextarg, DENY_BLANK); if(!err && config->engine && !strcmp(config->engine, "list")) { err = PARAM_ENGINES_REQUESTED; } break; - case ONEOPT('E', 'g'): /* --capath */ + case C_CAPATH: /* --capath */ err = getstr(&config->capath, nextarg, DENY_BLANK); break; - case ONEOPT('E', 'h'): /* --pubkey */ + case C_PUBKEY: /* --pubkey */ err = getstr(&config->pubkey, nextarg, DENY_BLANK); break; - case ONEOPT('E', 'i'): /* --hostpubmd5 */ + case C_HOSTPUBMD5: /* --hostpubmd5 */ err = getstr(&config->hostpubmd5, nextarg, DENY_BLANK); if(!err) { if(!config->hostpubmd5 || strlen(config->hostpubmd5) != 32) err = PARAM_BAD_USE; } break; - case ONEOPT('E', 'F'): /* --hostpubsha256 */ + case C_HOSTPUBSHA256: /* --hostpubsha256 */ err = getstr(&config->hostpubsha256, nextarg, DENY_BLANK); break; - case ONEOPT('E', 'j'): /* --crlfile */ + case C_CRLFILE: /* --crlfile */ err = getstr(&config->crlfile, nextarg, DENY_BLANK); break; - case ONEOPT('E', 'k'): /* --tlsuser */ + case C_TLSUSER: /* --tlsuser */ if(!feature_tls_srp) err = PARAM_LIBCURL_DOESNT_SUPPORT; else err = getstr(&config->tls_username, nextarg, DENY_BLANK); cleanarg(clearthis); break; - case ONEOPT('E', 'l'): /* --tlspassword */ + case C_TLSPASSWORD: /* --tlspassword */ if(!feature_tls_srp) err = PARAM_LIBCURL_DOESNT_SUPPORT; else err = getstr(&config->tls_password, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; - case ONEOPT('E', 'm'): /* --tlsauthtype */ + case C_TLSAUTHTYPE: /* --tlsauthtype */ if(!feature_tls_srp) err = PARAM_LIBCURL_DOESNT_SUPPORT; else { @@ -1884,72 +2134,59 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; /* only support TLS-SRP */ } break; - case ONEOPT('E', 'n'): /* --ssl-allow-beast */ + case C_SSL_ALLOW_BEAST: /* --ssl-allow-beast */ if(feature_ssl) config->ssl_allow_beast = toggle; break; - - case ONEOPT('E', 'o'): /* --ssl-auto-client-cert */ + case C_SSL_AUTO_CLIENT_CERT: /* --ssl-auto-client-cert */ if(feature_ssl) config->ssl_auto_client_cert = toggle; break; - - case ONEOPT('E', 'O'): /* --proxy-ssl-auto-client-cert */ + case C_PROXY_SSL_AUTO_CLIENT_CERT: /* --proxy-ssl-auto-client-cert */ if(feature_ssl) config->proxy_ssl_auto_client_cert = toggle; break; - - case ONEOPT('E', 'p'): /* --pinnedpubkey */ + case C_PINNEDPUBKEY: /* --pinnedpubkey */ err = getstr(&config->pinnedpubkey, nextarg, DENY_BLANK); break; - - case ONEOPT('E', 'P'): /* --proxy-pinnedpubkey */ + case C_PROXY_PINNEDPUBKEY: /* --proxy-pinnedpubkey */ err = getstr(&config->proxy_pinnedpubkey, nextarg, DENY_BLANK); break; - - case ONEOPT('E', 'q'): /* --cert-status */ + case C_CERT_STATUS: /* --cert-status */ config->verifystatus = TRUE; break; - - case ONEOPT('E', 'Q'): /* --doh-cert-status */ + case C_DOH_CERT_STATUS: /* --doh-cert-status */ config->doh_verifystatus = TRUE; break; - - case ONEOPT('E', 'r'): /* --false-start */ + case C_FALSE_START: /* --false-start */ config->falsestart = TRUE; break; - - case ONEOPT('E', 's'): /* --ssl-no-revoke */ + case C_SSL_NO_REVOKE: /* --ssl-no-revoke */ if(feature_ssl) config->ssl_no_revoke = TRUE; break; - - case ONEOPT('E', 'S'): /* --ssl-revoke-best-effort */ + case C_SSL_REVOKE_BEST_EFFORT: /* --ssl-revoke-best-effort */ if(feature_ssl) config->ssl_revoke_best_effort = TRUE; break; - - case ONEOPT('E', 't'): /* --tcp-fastopen */ + case C_TCP_FASTOPEN: /* --tcp-fastopen */ config->tcp_fastopen = TRUE; break; - - case ONEOPT('E', 'u'): /* --proxy-tlsuser */ + case C_PROXY_TLSUSER: /* --proxy-tlsuser */ cleanarg(clearthis); if(!feature_tls_srp) err = PARAM_LIBCURL_DOESNT_SUPPORT; else err = getstr(&config->proxy_tls_username, nextarg, ALLOW_BLANK); break; - - case ONEOPT('E', 'v'): /* --proxy-tlspassword */ + case C_PROXY_TLSPASSWORD: /* --proxy-tlspassword */ cleanarg(clearthis); if(!feature_tls_srp) err = PARAM_LIBCURL_DOESNT_SUPPORT; else err = getstr(&config->proxy_tls_password, nextarg, DENY_BLANK); break; - - case ONEOPT('E', 'w'): /* --proxy-tlsauthtype */ + case C_PROXY_TLSAUTHTYPE: /* --proxy-tlsauthtype */ if(!feature_tls_srp) err = PARAM_LIBCURL_DOESNT_SUPPORT; else { @@ -1958,100 +2195,81 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_LIBCURL_DOESNT_SUPPORT; /* only support TLS-SRP */ } break; - - case ONEOPT('E', 'x'): /* --proxy-cert */ + case C_PROXY_CERT: /* --proxy-cert */ cleanarg(clearthis); GetFileAndPassword(nextarg, &config->proxy_cert, &config->proxy_key_passwd); break; - - case ONEOPT('E', 'y'): /* --proxy-cert-type */ + case C_PROXY_CERT_TYPE: /* --proxy-cert-type */ err = getstr(&config->proxy_cert_type, nextarg, DENY_BLANK); break; - - case ONEOPT('E', 'z'): /* --proxy-key */ + case C_PROXY_KEY: /* --proxy-key */ err = getstr(&config->proxy_key, nextarg, ALLOW_BLANK); break; - - case ONEOPT('E', '0'): /* --proxy-key-type */ + case C_PROXY_KEY_TYPE: /* --proxy-key-type */ err = getstr(&config->proxy_key_type, nextarg, DENY_BLANK); break; - - case ONEOPT('E', '1'): /* --proxy-pass */ + case C_PROXY_PASS: /* --proxy-pass */ err = getstr(&config->proxy_key_passwd, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; - - case ONEOPT('E', '2'): /* --proxy-ciphers */ + case C_PROXY_CIPHERS: /* --proxy-ciphers */ err = getstr(&config->proxy_cipher_list, nextarg, DENY_BLANK); break; - - case ONEOPT('E', '3'): /* --proxy-crlfile */ + case C_PROXY_CRLFILE: /* --proxy-crlfile */ err = getstr(&config->proxy_crlfile, nextarg, DENY_BLANK); break; - - case ONEOPT('E', '4'): /* --proxy-allow-beast */ + case C_PROXY_SSL_ALLOW_BEAST: /* --proxy-ssl-allow-beast */ if(feature_ssl) config->proxy_ssl_allow_beast = toggle; break; - - case ONEOPT('E', '5'): /* --login-options */ + case C_LOGIN_OPTIONS: /* --login-options */ err = getstr(&config->login_options, nextarg, ALLOW_BLANK); break; - - case ONEOPT('E', '6'): /* --proxy-cacert */ + case C_PROXY_CACERT: /* --proxy-cacert */ err = getstr(&config->proxy_cacert, nextarg, DENY_BLANK); break; - - case ONEOPT('E', '7'): /* --proxy-cainfo */ + case C_PROXY_CAPATH: /* --proxy-capath */ err = getstr(&config->proxy_capath, nextarg, DENY_BLANK); break; - - case ONEOPT('E', '8'): /* --proxy-insecure */ + case C_PROXY_INSECURE: /* --proxy-insecure */ config->proxy_insecure_ok = toggle; break; - - case ONEOPT('E', '9'): /* --proxy-tlsv1 */ + case C_PROXY_TLSV1: /* --proxy-tlsv1 */ /* TLS version 1 for proxy */ config->proxy_ssl_version = CURL_SSLVERSION_TLSv1; break; - - case ONEOPT('E', 'A'): /* --socks5-basic */ + case C_SOCKS5_BASIC: /* --socks5-basic */ if(toggle) config->socks5_auth |= CURLAUTH_BASIC; else config->socks5_auth &= ~CURLAUTH_BASIC; break; - - case ONEOPT('E', 'B'): /* --socks5-gssapi */ + case C_SOCKS5_GSSAPI: /* --socks5-gssapi */ if(toggle) config->socks5_auth |= CURLAUTH_GSSAPI; else config->socks5_auth &= ~CURLAUTH_GSSAPI; break; - - case ONEOPT('E', 'C'): /* --etag-save */ + case C_ETAG_SAVE: /* --etag-save */ err = getstr(&config->etag_save_file, nextarg, DENY_BLANK); break; - - case ONEOPT('E', 'D'): /* --etag-compare */ + case C_ETAG_COMPARE: /* --etag-compare */ err = getstr(&config->etag_compare_file, nextarg, DENY_BLANK); break; - - case ONEOPT('E', 'E'): /* --curves */ + case C_CURVES: /* --curves */ err = getstr(&config->ssl_ec_curves, nextarg, DENY_BLANK); break; - - case ONEOPT('f', 'a'): /* --fail-early */ + case C_FAIL_EARLY: /* --fail-early */ global->fail_early = toggle; break; - case ONEOPT('f', 'b'): /* --styled-output */ + case C_STYLED_OUTPUT: /* --styled-output */ global->styled_output = toggle; break; - case ONEOPT('f', 'c'): /* --mail-rcpt-allowfails */ + case C_MAIL_RCPT_ALLOWFAILS: /* --mail-rcpt-allowfails */ config->mail_rcpt_allowfails = toggle; break; - case ONEOPT('f', 'd'): /* --fail-with-body */ + case C_FAIL_WITH_BODY: /* --fail-with-body */ config->failwithbody = toggle; if(config->failonerror && config->failwithbody) { errorf(config->global, "You must select either --fail or " @@ -2059,10 +2277,10 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_BAD_USE; } break; - case ONEOPT('f', 'e'): /* --remove-on-error */ + case C_REMOVE_ON_ERROR: /* --remove-on-error */ config->rm_partial = toggle; break; - case ONEOPT('f', '\0'): /* --fail */ + case C_FAIL: /* --fail */ config->failonerror = toggle; if(config->failonerror && config->failwithbody) { errorf(config->global, "You must select either --fail or " @@ -2070,36 +2288,29 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_BAD_USE; } break; - - case ONEOPT('F', '\0'): /* --form */ - case ONEOPT('F', 's'): /* --form-string */ + case C_FORM: /* --form */ + case C_FORM_STRING: /* --form-string */ /* "form data" simulation, this is a little advanced so lets do our best to sort this out slowly and carefully */ if(formparse(config, nextarg, &config->mimeroot, &config->mimecurrent, - (subletter == 's')?TRUE:FALSE)) { /* 's' is literal - string */ + (cmd == C_FORM_STRING)?TRUE:FALSE)) /* literal string */ err = PARAM_BAD_USE; - } else if(SetHTTPrequest(config, HTTPREQ_MIMEPOST, &config->httpreq)) err = PARAM_BAD_USE; break; - - case ONEOPT('g', '\0'): /* --globoff */ + case C_GLOBOFF: /* --globoff */ config->globoff = toggle; break; - - case ONEOPT('G', '\0'): /* --get */ + case C_GET: /* --get */ config->use_httpget = toggle; break; - - case ONEOPT('G', 'a'): /* --request-target */ + case C_REQUEST_TARGET: /* --request-target */ err = getstr(&config->request_target, nextarg, DENY_BLANK); break; - - case ONEOPT('h', '\0'): /* --help */ + case C_HELP: /* --help */ if(toggle) { if(*nextarg) { global->help_category = strdup(nextarg); @@ -2112,8 +2323,8 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } /* we now actually support --no-help too! */ break; - case ONEOPT('H', '\0'): /* --header */ - case ONEOPT('H', 'p'): /* --proxy-header */ + case C_HEADER: /* --header */ + case C_PROXY_HEADER: /* --proxy-header */ /* A custom header to append to a list */ if(nextarg[0] == '@') { /* read many headers from a file or stdin */ @@ -2124,7 +2335,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ if(!file) { errorf(global, "Failed to open %s", &nextarg[1]); err = PARAM_READ_ERROR; - break; } else { err = file2memory(&string, &len, file); @@ -2133,7 +2343,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ /* !checksrc! disable BANNEDFUNC 2 */ char *h = strtok(string, "\r\n"); while(h) { - if(subletter == 'p') /* --proxy-header */ + if(cmd == C_PROXY_HEADER) /* --proxy-header */ err = add2list(&config->proxyheaders, h); else err = add2list(&config->headers, h); @@ -2145,25 +2355,23 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } if(!use_stdin) fclose(file); - if(err) - break; } } else { - if(subletter == 'p') /* --proxy-header */ + if(cmd == C_PROXY_HEADER) /* --proxy-header */ err = add2list(&config->proxyheaders, nextarg); else err = add2list(&config->headers, nextarg); } break; - case ONEOPT('i', '\0'): /* --include */ + case C_INCLUDE: /* --include */ config->show_headers = toggle; /* show the headers as well in the general output stream */ break; - case ONEOPT('j', '\0'): /* --junk-session-cookies */ + case C_JUNK_SESSION_COOKIES: /* --junk-session-cookies */ config->cookiesession = toggle; break; - case ONEOPT('I', '\0'): /* --head */ + case C_HEAD: /* --head */ config->no_body = toggle; config->show_headers = toggle; if(SetHTTPrequest(config, @@ -2171,37 +2379,37 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ &config->httpreq)) err = PARAM_BAD_USE; break; - case ONEOPT('J', '\0'): /* --remote-header-name */ + case C_REMOTE_HEADER_NAME: /* --remote-header-name */ config->content_disposition = toggle; break; - case ONEOPT('k', '\0'): /* --insecure */ + case C_INSECURE: /* --insecure */ config->insecure_ok = toggle; break; - case ONEOPT('k', 'd'): /* --doh-insecure */ + case C_DOH_INSECURE: /* --doh-insecure */ config->doh_insecure_ok = toggle; break; - case ONEOPT('K', '\0'): /* --config */ + case C_CONFIG: /* --config */ if(parseconfig(nextarg, global)) { errorf(global, "cannot read config from '%s'", nextarg); err = PARAM_READ_ERROR; } break; - case ONEOPT('l', '\0'): /* --list-only */ + case C_LIST_ONLY: /* --list-only */ config->dirlistonly = toggle; /* only list the names of the FTP dir */ break; - case ONEOPT('L', '\0'): /* --location */ - case ONEOPT('L', 't'): /* --location-trusted */ + case C_LOCATION_TRUSTED: /* --location-trusted */ + /* Continue to send authentication (user+password) when following + * locations, even when hostname changed */ + config->unrestricted_auth = toggle; + FALLTHROUGH(); + case C_LOCATION: /* --location */ config->followlocation = toggle; /* Follow Location: HTTP headers */ - if(subletter == 't') - /* Continue to send authentication (user+password) when following - * locations, even when hostname changed */ - config->unrestricted_auth = toggle; break; - case ONEOPT('m', '\0'): /* --max-time */ + case C_MAX_TIME: /* --max-time */ /* specified max time */ err = secs2ms(&config->timeout_ms, nextarg); break; - case ONEOPT('M', '\0'): /* --manual */ + case C_MANUAL: /* --manual */ if(toggle) { /* --no-manual shows no manual... */ #ifndef USE_MANUAL warnf(global, @@ -2210,39 +2418,33 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = PARAM_MANUAL_REQUESTED; } break; - - case ONEOPT('n', 'o'): /* --netrc-optional */ + case C_NETRC_OPTIONAL: /* --netrc-optional */ config->netrc_opt = toggle; break; - case ONEOPT('n', 'e'): /* --netrc-file */ + case C_NETRC_FILE: /* --netrc-file */ err = getstr(&config->netrc_file, nextarg, DENY_BLANK); break; - case ONEOPT('n', '\0'): /* --netrc */ + case C_NETRC: /* --netrc */ /* pick info from .netrc, if this is used for http, curl will automatically enforce user+password with the request */ config->netrc = toggle; break; - - case ONEOPT('N', '\0'): /* --buffer */ + case C_BUFFER: /* --buffer */ /* disable the output I/O buffering. note that the option is called --buffer but is mostly used in the negative form: --no-buffer */ config->nobuffer = longopt ? !toggle : TRUE; break; - - case ONEOPT('O', 'a'): /* --remote-name-all */ + case C_REMOTE_NAME_ALL: /* --remote-name-all */ config->default_node_flags = toggle?GETOUT_USEREMOTE:0; break; - - case ONEOPT('O', 'b'): /* --output-dir */ + case C_OUTPUT_DIR: /* --output-dir */ err = getstr(&config->output_dir, nextarg, DENY_BLANK); break; - - case ONEOPT('O', 'c'): /* --clobber */ + case C_CLOBBER: /* --clobber */ config->file_clobber_mode = toggle ? CLOBBER_ALWAYS : CLOBBER_NEVER; break; - - case ONEOPT('o', '\0'): /* --output */ - case ONEOPT('O', '\0'): /* --remote-name */ + case C_OUTPUT: /* --output */ + case C_REMOTE_NAME: /* --remote-name */ /* output file */ if(!config->url_out) config->url_out = config->url_list; @@ -2284,7 +2486,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } url->flags |= GETOUT_OUTFILE; break; - case ONEOPT('P', '\0'): /* --ftp-port */ + case C_FTP_PORT: /* --ftp-port */ /* This makes the FTP sessions use PORT instead of PASV */ /* use or <192.168.10.10> style addresses. Anything except this will make us try to get the "default" address. @@ -2292,16 +2494,16 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ */ err = getstr(&config->ftpport, nextarg, DENY_BLANK); break; - case ONEOPT('p', '\0'): /* --proxytunnel */ + case C_PROXYTUNNEL: /* --proxytunnel */ /* proxy tunnel for non-http protocols */ config->proxytunnel = toggle; break; - case ONEOPT('q', '\0'): /* --disable */ + case C_DISABLE: /* --disable */ /* if used first, already taken care of, we do it like this so we don't cause an error! */ break; - case ONEOPT('Q', '\0'): /* --quote */ + case C_QUOTE: /* --quote */ /* QUOTE command to send to FTP server */ switch(nextarg[0]) { case '-': @@ -2319,7 +2521,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ break; } break; - case ONEOPT('r', '\0'): /* --range */ + case C_RANGE: /* --range */ /* Specifying a range WITHOUT A DASH will create an illegal HTTP range (and won't actually be range by definition). The man page previously claimed that to be a good way, why this code is added to work-around @@ -2329,24 +2531,23 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ if(curlx_strtoofft(nextarg, NULL, 10, &value)) { warnf(global, "unsupported range point"); err = PARAM_BAD_USE; - break; } - warnf(global, - "A specified range MUST include at least one dash (-). " - "Appending one for you"); - msnprintf(buffer, sizeof(buffer), "%" CURL_FORMAT_CURL_OFF_T "-", - value); - Curl_safefree(config->range); - config->range = strdup(buffer); - if(!config->range) { - err = PARAM_NO_MEM; - break; + else { + warnf(global, + "A specified range MUST include at least one dash (-). " + "Appending one for you"); + msnprintf(buffer, sizeof(buffer), "%" CURL_FORMAT_CURL_OFF_T "-", + value); + Curl_safefree(config->range); + config->range = strdup(buffer); + if(!config->range) + err = PARAM_NO_MEM; } } else { /* byte range requested */ const char *tmp_range = nextarg; - while(*tmp_range != '\0') { + while(*tmp_range) { if(!ISDIGIT(*tmp_range) && *tmp_range != '-' && *tmp_range != ',') { warnf(global, "Invalid character is found in given range. " "A specified range MUST have only digits in " @@ -2359,21 +2560,21 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = getstr(&config->range, nextarg, DENY_BLANK); } break; - case ONEOPT('R', '\0'): /* --remote-time */ + case C_REMOTE_TIME: /* --remote-time */ /* use remote file's time */ config->remote_time = toggle; break; - case ONEOPT('s', '\0'): /* --silent */ + case C_SILENT: /* --silent */ global->silent = toggle; break; - case ONEOPT('S', '\0'): /* --show-error */ + case C_SHOW_ERROR: /* --show-error */ global->showerror = toggle; break; - case ONEOPT('t', '\0'): /* --telnet-option */ + case C_TELNET_OPTION: /* --telnet-option */ /* Telnet options */ err = add2list(&config->telnet_options, nextarg); break; - case ONEOPT('T', '\0'): /* --upload */ + case C_UPLOAD_FILE: /* --upload-file */ /* we are uploading */ if(!config->url_ul) config->url_ul = config->url_list; @@ -2406,17 +2607,17 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = getstr(&url->infile, nextarg, DENY_BLANK); } break; - case ONEOPT('u', '\0'): /* --user */ + case C_USER: /* --user */ /* user:password */ err = getstr(&config->userpwd, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; - case ONEOPT('U', '\0'): /* --proxy-user */ + case C_PROXY_USER: /* --proxy-user */ /* Proxy user:password */ err = getstr(&config->proxyuserpwd, nextarg, ALLOW_BLANK); cleanarg(clearthis); break; - case ONEOPT('v', '\0'): /* --verbose */ + case C_VERBOSE: /* --verbose */ if(toggle) { /* the '%' thing here will cause the trace get sent to stderr */ Curl_safefree(global->trace_dump); @@ -2434,12 +2635,11 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ /* verbose is disabled here */ global->tracetype = TRACE_NONE; break; - case ONEOPT('V', '\0'): /* --version */ + case C_VERSION: /* --version */ if(toggle) /* --no-version yields no output! */ err = PARAM_VERSION_INFO_REQUESTED; break; - - case ONEOPT('w', '\0'): /* --write-out */ + case C_WRITE_OUT: /* --write-out */ /* get the output string */ if('@' == *nextarg) { /* the data begins with a '@' letter, it means that a file name @@ -2472,36 +2672,35 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ else err = getstr(&config->writeout, nextarg, DENY_BLANK); break; - case ONEOPT('x', 'a'): /* --preproxy */ + case C_PREPROXY: /* --preproxy */ err = getstr(&config->preproxy, nextarg, DENY_BLANK); break; - case ONEOPT('x', '\0'): /* --proxy */ + case C_PROXY: /* --proxy */ /* --proxy */ err = getstr(&config->proxy, nextarg, ALLOW_BLANK); if(config->proxyver != CURLPROXY_HTTPS2) config->proxyver = CURLPROXY_HTTP; break; - - case ONEOPT('X', '\0'): /* --request */ + case C_REQUEST: /* --request */ /* set custom request */ err = getstr(&config->customrequest, nextarg, DENY_BLANK); break; - case ONEOPT('y', '\0'): /* --speed-limit */ + case C_SPEED_TIME: /* --speed-time */ /* low speed time */ err = str2unum(&config->low_speed_time, nextarg); if(!err && !config->low_speed_limit) config->low_speed_limit = 1; break; - case ONEOPT('Y', '\0'): /* --speed-time */ + case C_SPEED_LIMIT: /* --speed-limit */ /* low speed limit */ err = str2unum(&config->low_speed_limit, nextarg); if(!err && !config->low_speed_time) config->low_speed_time = 30; break; - case ONEOPT('Z', '\0'): /* --parallel */ + case C_PARALLEL: /* --parallel */ global->parallel = toggle; break; - case ONEOPT('Z', 'b'): { /* --parallel-max */ + case C_PARALLEL_MAX: { /* --parallel-max */ long val; err = str2unum(&val, nextarg); if(err) @@ -2514,11 +2713,10 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ global->parallel_max = (unsigned short)val; break; } - case ONEOPT('Z', 'c'): /* --parallel-immediate */ + case C_PARALLEL_IMMEDIATE: /* --parallel-immediate */ global->parallel_connect = toggle; break; - - case ONEOPT('z', '\0'): /* --time-cond */ + case C_TIME_COND: /* --time-cond */ switch(*nextarg) { case '+': nextarg++; diff --git a/tests/test1139.pl b/tests/test1139.pl index 1c3c017daf2..ce49a61ba8c 100755 --- a/tests/test1139.pl +++ b/tests/test1139.pl @@ -190,8 +190,8 @@ sub scanmanpage { $list=1; } elsif($list) { - if( /^ \{(\"[^,]*\").*((\"[^ ]*)\")/) { - my ($l, $s)=($1, $2); + if( /^ \{(\"[^,]*\").*\'(.)\', (.*)\}/) { + my ($l, $s, $rd)=($1, $2, $3); my $sh; my $lo; my $title; @@ -203,9 +203,9 @@ sub scanmanpage { $lo = $1; $title="--$lo"; } - if($s =~ /\"(.)\"/) { + if($s ne " ") { # a short option - $sh = $1; + $sh = $s; $title="-$sh, $title"; } push @getparam, $title; From fb414370acdc30297f8aea61dfe18a01274c62ec Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 17:00:05 +0100 Subject: [PATCH 136/509] tool_getparam: move the --rate logic into set_rate() --- src/tool_getparam.c | 138 ++++++++++++++++++++------------------------ 1 file changed, 62 insertions(+), 76 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index a0afeba93de..571918389d8 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -1143,6 +1143,66 @@ static ParameterError set_data(cmdline_t cmd, return err; } +static ParameterError set_rate(struct GlobalConfig *global, + char *nextarg) +{ + /* --rate */ + /* support a few different suffixes, extract the suffix first, then + get the number and convert to per hour. + /s == per second + /m == per minute + /h == per hour (default) + /d == per day (24 hours) + */ + ParameterError err = PARAM_OK; + char *div = strchr(nextarg, '/'); + char number[26]; + long denominator; + long numerator = 60*60*1000; /* default per hour */ + size_t numlen = div ? (size_t)(div - nextarg) : strlen(nextarg); + if(numlen > sizeof(number) -1) + return PARAM_NUMBER_TOO_LARGE; + + strncpy(number, nextarg, numlen); + number[numlen] = 0; + err = str2unum(&denominator, number); + if(err) + return err; + + if(denominator < 1) + return PARAM_BAD_USE; + + if(div) { + char unit = div[1]; + switch(unit) { + case 's': /* per second */ + numerator = 1000; + break; + case 'm': /* per minute */ + numerator = 60*1000; + break; + case 'h': /* per hour */ + break; + case 'd': /* per day */ + numerator = 24*60*60*1000; + break; + default: + errorf(global, "unsupported --rate unit"); + err = PARAM_BAD_USE; + break; + } + } + + if(err) + ; + else if(denominator > numerator) + err = PARAM_NUMBER_TOO_LARGE; + else + global->ms_per_transfer = numerator/denominator; + + return err; +} + ParameterError getparameter(const char *flag, /* f or -long-flag */ char *nextarg, /* NULL if unset */ @@ -1380,81 +1440,24 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->sendpersecond = value; } break; - case C_RATE: { /* --rate */ - /* support a few different suffixes, extract the suffix first, then - get the number and convert to per hour. - /s == per second - /m == per minute - /h == per hour (default) - /d == per day (24 hours) - */ - char *div = strchr(nextarg, '/'); - char number[26]; - long denominator; - long numerator = 60*60*1000; /* default per hour */ - size_t numlen = div ? (size_t)(div - nextarg) : strlen(nextarg); - if(numlen > sizeof(number)-1) { - err = PARAM_NUMBER_TOO_LARGE; - break; - } - strncpy(number, nextarg, numlen); - number[numlen] = 0; - err = str2unum(&denominator, number); - if(err) - break; - - if(denominator < 1) { - err = PARAM_BAD_USE; - break; - } - if(div) { - char unit = div[1]; - switch(unit) { - case 's': /* per second */ - numerator = 1000; - break; - case 'm': /* per minute */ - numerator = 60*1000; - break; - case 'h': /* per hour */ - break; - case 'd': /* per day */ - numerator = 24*60*60*1000; - break; - default: - errorf(global, "unsupported --rate unit"); - err = PARAM_BAD_USE; - break; - } - } - - if(err) - ; - else if(denominator > numerator) - err = PARAM_NUMBER_TOO_LARGE; - else - global->ms_per_transfer = numerator/denominator; - } + case C_RATE: + err = set_rate(global, nextarg); break; - case C_COMPRESSED: /* --compressed */ if(toggle && !(feature_libz || feature_brotli || feature_zstd)) err = PARAM_LIBCURL_DOESNT_SUPPORT; else config->encoding = toggle; break; - case C_TR_ENCODING: /* --tr-encoding */ config->tr_encoding = toggle; break; - case C_DIGEST: /* --digest */ if(toggle) config->authtype |= CURLAUTH_DIGEST; else config->authtype &= ~CURLAUTH_DIGEST; break; - case C_NEGOTIATE: /* --negotiate */ if(!toggle) config->authtype &= ~CURLAUTH_NEGOTIATE; @@ -1463,7 +1466,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ else err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case C_NTLM: /* --ntlm */ if(!toggle) config->authtype &= ~CURLAUTH_NTLM; @@ -1472,7 +1474,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ else err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case C_NTLM_WB: /* --ntlm-wb */ if(!toggle) config->authtype &= ~CURLAUTH_NTLM_WB; @@ -1481,20 +1482,17 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ else err = PARAM_LIBCURL_DOESNT_SUPPORT; break; - case C_BASIC: /* --basic */ if(toggle) config->authtype |= CURLAUTH_BASIC; else config->authtype &= ~CURLAUTH_BASIC; break; - case C_ANYAUTH: /* --anyauth */ if(toggle) config->authtype = CURLAUTH_ANY; /* --no-anyauth simply doesn't touch it */ break; - #ifdef USE_WATT32 case C_WDEBUG: /* --wdebug */ dbug_init(); @@ -1503,15 +1501,12 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case C_FTP_CREATE_DIRS: /* --ftp-create-dirs */ config->ftp_create_dirs = toggle; break; - case C_CREATE_DIRS: /* --create-dirs */ config->create_dirs = toggle; break; - case C_CREATE_FILE_MODE: /* --create-file-mode */ err = oct2nummax(&config->create_file_mode, nextarg, 0777); break; - case C_MAX_REDIRS: /* --max-redirs */ /* specified max no of redirects (http(s)), this accepts -1 as a special condition */ @@ -1519,28 +1514,23 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ if(!err && (config->maxredirs < -1)) err = PARAM_BAD_NUMERIC; break; - case C_IPFS_GATEWAY: /* --ipfs-gateway */ err = getstr(&config->ipfs_gateway, nextarg, DENY_BLANK); break; - case C_PROXY_NTLM: /* --proxy-ntlm */ if(!feature_ntlm) err = PARAM_LIBCURL_DOESNT_SUPPORT; else config->proxyntlm = toggle; break; - case C_CRLF: /* --crlf */ /* LF -> CRLF conversion? */ config->crlf = toggle; break; - case C_AWS_SIGV4: /* --aws-sigv4 */ config->authtype |= CURLAUTH_AWS_SIGV4; err = getstr(&config->aws_sigv4, nextarg, DENY_BLANK); break; - case C_STDERR: /* --stderr */ tool_set_stderr_file(global, nextarg); break; @@ -1603,7 +1593,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ url->flags |= GETOUT_URL; } break; - case C_SSL: /* --ssl */ if(toggle && !feature_ssl) err = PARAM_LIBCURL_DOESNT_SUPPORT; @@ -1659,20 +1648,17 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case C_RETRY_ALL_ERRORS: /* --retry-all-errors */ config->retry_all_errors = toggle; break; - case C_PROXY_NEGOTIATE: /* --proxy-negotiate */ if(!feature_spnego) err = PARAM_LIBCURL_DOESNT_SUPPORT; else config->proxynegotiate = toggle; break; - case C_FORM_ESCAPE: /* --form-escape */ config->mime_options &= ~CURLMIMEOPT_FORMESCAPE; if(toggle) config->mime_options |= CURLMIMEOPT_FORMESCAPE; break; - case C_FTP_ACCOUNT: /* --ftp-account */ err = getstr(&config->ftp_account, nextarg, DENY_BLANK); break; From 8e0323b4b534807e0fa8cc83e316950831a5afef Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 7 Jan 2024 16:01:00 +0100 Subject: [PATCH 137/509] mime: use memdup0 instead of malloc + memcpy Closes #12649 --- lib/mime.c | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/lib/mime.c b/lib/mime.c index 0966a0b5a17..d61cbeb8294 100644 --- a/lib/mime.c +++ b/lib/mime.c @@ -30,6 +30,7 @@ #include "warnless.h" #include "urldata.h" #include "sendf.h" +#include "strdup.h" #if !defined(CURL_DISABLE_MIME) && (!defined(CURL_DISABLE_HTTP) || \ !defined(CURL_DISABLE_SMTP) || \ @@ -1370,27 +1371,22 @@ CURLcode curl_mime_filename(curl_mimepart *part, const char *filename) /* Set mime part content from memory data. */ CURLcode curl_mime_data(curl_mimepart *part, - const char *data, size_t datasize) + const char *ptr, size_t datasize) { if(!part) return CURLE_BAD_FUNCTION_ARGUMENT; cleanup_part_content(part); - if(data) { + if(ptr) { if(datasize == CURL_ZERO_TERMINATED) - datasize = strlen(data); + datasize = strlen(ptr); - part->data = malloc(datasize + 1); + part->data = Curl_memdup0(ptr, datasize); if(!part->data) return CURLE_OUT_OF_MEMORY; part->datasize = datasize; - - if(datasize) - memcpy(part->data, data, datasize); - part->data[datasize] = '\0'; /* Set a null terminator as sentinel. */ - part->readfunc = mime_mem_read; part->seekfunc = mime_mem_seek; part->freefunc = mime_mem_free; From cfe7902111ae5478738c7ace8086db74963b87c6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 10:34:06 +0100 Subject: [PATCH 138/509] lib: add debug log outputs for CURLE_BAD_FUNCTION_ARGUMENT Closes #12658 --- lib/altsvc.c | 3 --- lib/asyn-ares.c | 3 +++ lib/easy.c | 6 +++--- lib/headers.c | 3 ++- lib/hsts.c | 2 ++ lib/http.c | 1 + lib/krb5.c | 3 +-- lib/mime.c | 1 + lib/mqtt.c | 4 +++- lib/rand.c | 6 ++++-- lib/setopt.c | 8 ++++++++ lib/telnet.c | 4 +++- lib/ws.c | 5 ++++- 13 files changed, 35 insertions(+), 14 deletions(-) diff --git a/lib/altsvc.c b/lib/altsvc.c index b5fb65fde1d..e9f62bf0e0a 100644 --- a/lib/altsvc.c +++ b/lib/altsvc.c @@ -335,9 +335,6 @@ CURLcode Curl_altsvc_load(struct altsvcinfo *asi, const char *file) CURLcode Curl_altsvc_ctrl(struct altsvcinfo *asi, const long ctrl) { DEBUGASSERT(asi); - if(!ctrl) - /* unexpected */ - return CURLE_BAD_FUNCTION_ARGUMENT; asi->flags = ctrl; return CURLE_OK; } diff --git a/lib/asyn-ares.c b/lib/asyn-ares.c index c3030154b3e..f1ff49277c4 100644 --- a/lib/asyn-ares.c +++ b/lib/asyn-ares.c @@ -858,6 +858,7 @@ CURLcode Curl_set_dns_servers(struct Curl_easy *data, case ARES_ENODATA: case ARES_EBADSTR: default: + DEBUGF(infof(data, "bad servers set")); result = CURLE_BAD_FUNCTION_ARGUMENT; break; } @@ -896,6 +897,7 @@ CURLcode Curl_set_dns_local_ip4(struct Curl_easy *data, } else { if(Curl_inet_pton(AF_INET, local_ip4, &a4) != 1) { + DEBUGF(infof(data, "bad DNS IPv4 address")); return CURLE_BAD_FUNCTION_ARGUMENT; } } @@ -923,6 +925,7 @@ CURLcode Curl_set_dns_local_ip6(struct Curl_easy *data, } else { if(Curl_inet_pton(AF_INET6, local_ip6, a6) != 1) { + DEBUGF(infof(data, "bad DNS IPv6 address")); return CURLE_BAD_FUNCTION_ARGUMENT; } } diff --git a/lib/easy.c b/lib/easy.c index 085f368c9be..067b6d7b69f 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -688,9 +688,9 @@ static CURLcode easy_transfer(struct Curl_multi *multi) /* Make sure to return some kind of error if there was a multi problem */ if(mcode) { result = (mcode == CURLM_OUT_OF_MEMORY) ? CURLE_OUT_OF_MEMORY : - /* The other multi errors should never happen, so return - something suitably generic */ - CURLE_BAD_FUNCTION_ARGUMENT; + /* The other multi errors should never happen, so return + something suitably generic */ + CURLE_BAD_FUNCTION_ARGUMENT; } return result; diff --git a/lib/headers.c b/lib/headers.c index 3ff4d5eb073..b6fcdda777c 100644 --- a/lib/headers.c +++ b/lib/headers.c @@ -185,7 +185,7 @@ struct curl_header *curl_easy_nextheader(CURL *easy, } static CURLcode namevalue(char *header, size_t hlen, unsigned int type, - char **name, char **value) + char **name, char **value) { char *end = header + hlen - 1; /* point to the last byte */ DEBUGASSERT(hlen); @@ -291,6 +291,7 @@ CURLcode Curl_headers_push(struct Curl_easy *data, const char *header, end = strchr(header, '\r'); if(!end) { end = strchr(header, '\n'); + DEBUGASSERT(end); if(!end) return CURLE_BAD_FUNCTION_ARGUMENT; } diff --git a/lib/hsts.c b/lib/hsts.c index 99f5bd458fe..5677e4f3d12 100644 --- a/lib/hsts.c +++ b/lib/hsts.c @@ -127,6 +127,7 @@ static CURLcode hsts_create(struct hsts *h, if(hlen && (hostname[hlen - 1] == '.')) /* strip off any trailing dot */ --hlen; + DEBUGASSERT(hlen); if(!hlen) /* no host name left */ return CURLE_BAD_FUNCTION_ARGUMENT; @@ -481,6 +482,7 @@ static CURLcode hsts_pull(struct Curl_easy *data, struct hsts *h) if(sc == CURLSTS_OK) { time_t expires; CURLcode result; + DEBUGASSERT(e.name[0]); if(!e.name[0]) /* bail out if no name was stored */ return CURLE_BAD_FUNCTION_ARGUMENT; diff --git a/lib/http.c b/lib/http.c index 5b8f3e54b01..1f33c143fae 100644 --- a/lib/http.c +++ b/lib/http.c @@ -2095,6 +2095,7 @@ CURLcode Curl_add_timecondition(struct Curl_easy *data, switch(data->set.timecondition) { default: + DEBUGF(infof(data, "invalid time condition")); return CURLE_BAD_FUNCTION_ARGUMENT; case CURL_TIMECOND_IFMODSINCE: diff --git a/lib/krb5.c b/lib/krb5.c index 91f8a1077f7..19f0f0cf106 100644 --- a/lib/krb5.c +++ b/lib/krb5.c @@ -75,8 +75,7 @@ static CURLcode ftpsend(struct Curl_easy *data, struct connectdata *conn, unsigned char data_sec = conn->data_prot; #endif - if(!cmd) - return CURLE_BAD_FUNCTION_ARGUMENT; + DEBUGASSERT(cmd); write_len = strlen(cmd); if(!write_len || write_len > (sizeof(s) -3)) diff --git a/lib/mime.c b/lib/mime.c index d61cbeb8294..e6553816fa3 100644 --- a/lib/mime.c +++ b/lib/mime.c @@ -1236,6 +1236,7 @@ CURLcode Curl_mime_duppart(struct Curl_easy *data, } break; default: /* Invalid kind: should not occur. */ + DEBUGF(infof(data, "invalid MIMEKIND* attempt")); res = CURLE_BAD_FUNCTION_ARGUMENT; /* Internal error? */ break; } diff --git a/lib/mqtt.c b/lib/mqtt.c index b304bd62974..e3a7aff9791 100644 --- a/lib/mqtt.c +++ b/lib/mqtt.c @@ -524,8 +524,10 @@ static CURLcode mqtt_publish(struct Curl_easy *data) char encodedbytes[4]; curl_off_t postfieldsize = data->set.postfieldsize; - if(!payload) + if(!payload) { + DEBUGF(infof(data, "mqtt_publish without payload, return bad arg")); return CURLE_BAD_FUNCTION_ARGUMENT; + } if(postfieldsize < 0) payloadlen = strlen(payload); else diff --git a/lib/rand.c b/lib/rand.c index 3383c490b67..c62b1a40323 100644 --- a/lib/rand.c +++ b/lib/rand.c @@ -201,7 +201,7 @@ CURLcode Curl_rand(struct Curl_easy *data, unsigned char *rnd, size_t num) { CURLcode result = CURLE_BAD_FUNCTION_ARGUMENT; - DEBUGASSERT(num > 0); + DEBUGASSERT(num); while(num) { unsigned int r; @@ -241,9 +241,11 @@ CURLcode Curl_rand_hex(struct Curl_easy *data, unsigned char *rnd, memset(buffer, 0, sizeof(buffer)); #endif - if((num/2 >= sizeof(buffer)) || !(num&1)) + if((num/2 >= sizeof(buffer)) || !(num&1)) { /* make sure it fits in the local buffer and that it is an odd number! */ + DEBUGF(infof(data, "invalid buffer size with Curl_rand_hex")); return CURLE_BAD_FUNCTION_ARGUMENT; + } num--; /* save one for null-termination */ diff --git a/lib/setopt.c b/lib/setopt.c index e13432334d9..72bd6cdf6f6 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -3122,6 +3122,10 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) return CURLE_OUT_OF_MEMORY; } arg = va_arg(param, long); + if(!arg) { + DEBUGF(infof(data, "bad CURLOPT_ALTSVC_CTRL input")); + return CURLE_BAD_FUNCTION_ARGUMENT; + } result = Curl_altsvc_ctrl(data->asi, arg); if(result) return result; @@ -3176,5 +3180,9 @@ CURLcode curl_easy_setopt(struct Curl_easy *data, CURLoption tag, ...) result = Curl_vsetopt(data, tag, arg); va_end(arg); +#ifdef DEBUGBUILD + if(result == CURLE_BAD_FUNCTION_ARGUMENT) + infof(data, "setopt arg 0x%x returned CURLE_BAD_FUNCTION_ARGUMENT", tag); +#endif return result; } diff --git a/lib/telnet.c b/lib/telnet.c index 1a1171ccb72..67667e347e5 100644 --- a/lib/telnet.c +++ b/lib/telnet.c @@ -799,8 +799,10 @@ static CURLcode check_telnet_options(struct Curl_easy *data) was given on the command line */ if(data->state.aptr.user) { char buffer[256]; - if(str_is_nonascii(data->conn->user)) + if(str_is_nonascii(data->conn->user)) { + DEBUGF(infof(data, "set a non ASCII user name in telnet")); return CURLE_BAD_FUNCTION_ARGUMENT; + } msnprintf(buffer, sizeof(buffer), "USER,%s", data->conn->user); beg = curl_slist_append(tn->telnet_vars, buffer); if(!beg) { diff --git a/lib/ws.c b/lib/ws.c index f924362a865..81b48180ccf 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -997,8 +997,11 @@ CURL_EXTERN CURLcode curl_ws_send(CURL *data, const void *buffer, ws = data->conn->proto.ws; if(data->set.ws_raw_mode) { - if(fragsize || flags) + if(fragsize || flags) { + DEBUGF(infof(data, "ws_send: " + "fragsize and flags cannot be non-zero in raw mode")); return CURLE_BAD_FUNCTION_ARGUMENT; + } if(!buflen) /* nothing to do */ return CURLE_OK; From a3abc81a482ae8a8d6db80fd38e14f53bdb7c6fc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 7 Jan 2024 16:06:32 +0100 Subject: [PATCH 139/509] pop3: replace calloc + memcpy with memdup0 ... and make sure to return error on out of memory. Closes #12650 --- lib/pop3.c | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/lib/pop3.c b/lib/pop3.c index 3e0f20a6900..648945ca8eb 100644 --- a/lib/pop3.c +++ b/lib/pop3.c @@ -77,6 +77,7 @@ #include "curl_sasl.h" #include "curl_md5.h" #include "warnless.h" +#include "strdup.h" /* The last 3 #include files should be in this order */ #include "curl_printf.h" #include "curl_memory.h" @@ -670,15 +671,12 @@ static CURLcode pop3_state_servergreet_resp(struct Curl_easy *data, if(!timestamplen) break; - /* Allocate some memory for the timestamp */ - pop3c->apoptimestamp = (char *)calloc(1, timestamplen + 1); - - if(!pop3c->apoptimestamp) + /* dupe the timestamp */ + pop3c->apoptimestamp = Curl_memdup0(&line[i], timestamplen); + if(!pop3c->apoptimestamp) { + result = CURLE_OUT_OF_MEMORY; break; - - /* Copy the timestamp */ - memcpy(pop3c->apoptimestamp, line + i, timestamplen); - pop3c->apoptimestamp[timestamplen] = '\0'; + } /* If the timestamp does not contain '@' it is not (as required by RFC-1939) conformant to the RFC-822 message id syntax, and we @@ -694,7 +692,8 @@ static CURLcode pop3_state_servergreet_resp(struct Curl_easy *data, } } - result = pop3_perform_capa(data, conn); + if(!result) + result = pop3_perform_capa(data, conn); } return result; From 912d80c68019d3d9a4ceb9993a596dff8009f4d0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 23:00:21 +0100 Subject: [PATCH 140/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 53 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 42 insertions(+), 11 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 732b54e8279..99504e702f9 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.6.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3058 + Contributors: 3064 This release includes the following changes: @@ -33,6 +33,8 @@ This release includes the following bugfixes: o cmdline-opts: update availability for the *-ca-native options [66] o cmdline/gen: fix the sorting of the man page options [33] o configure: fix no default int compile error in ipv6 detection [69] + o connect: remove margin from eyeballer alloc [79] + o content_encoding: change return code to typedef'ed enum [94] o cookie: avoid fopen with empty file name [24] o curl: show ipfs and ipns as supported "protocols" [15] o CURLINFO_REFERER.3: clarify that it is the *request* header [70] @@ -43,11 +45,16 @@ This release includes the following bugfixes: o docs: clean up Protocols: for cmdline options [32] o doh: remove unused local variable [34] o ftp: handle the PORT parsing without allocation [44] + o ftp: use dynbuf to store entrypath [83] + o ftp: use memdup0 to store the OS from a SYST 215 response [82] o gnutls: fix build with --disable-verbose [3] o haproxy-clientip.d: document the arg [68] o hostip: return error immediately when Curl_ip2addr() fails [19] o http2: improved on_stream_close/data_done handling [49] + o http3/quiche: fix result code on a stream reset [91] + o http: adjust_pollset fix [85] o http: fix off-by-one error in request method length check [14] + o lib: add debug log outputs for CURLE_BAD_FUNCTION_ARGUMENT [62] o lib: fix variable undeclared error caused by `infof` changes [2] o lib: reduce use of strncpy [30] o lib: rename Curl_strndup to Curl_memdup0 to avoid misunderstanding [36] @@ -57,11 +64,13 @@ This release includes the following bugfixes: o Makefile.am: fix the MSVC project generation [22] o Makefile.mk: drop Windows support [12] o mbedtls: free the entropy when threaded [46] + o mime: use memdup0 instead of malloc + memcpy [63] o mprintf: overhaul and bugfixes [52] o ngtcp2: put h3 at the front of alpn [58] o openldap: fix an LDAP crash [75] o openldap: fix STARTTLS [67] o openssl: re-match LibreSSL deinit with init [17] + o pop3: replace calloc + memcpy with memdup0 [60] o quiche: return CURLE_HTTP3 on send to invalid stream [65] o readwrite_data: loop less [21] o Revert "urldata: move async resolver state from easy handle to connectdata" [16] @@ -69,14 +78,19 @@ This release includes the following bugfixes: o schannel: fix `-Warith-conversion` gcc 13 warning [28] o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] o sendf: fix compiler warning with CURL_DISABLE_HEADERS_API [38] + o setopt: clear mimepost when formp is freed [92] o ssh: fix namespace of two local macros [51] o strerror: repair get_winsock_error() [56] o system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers [9] o system_win32: fix a function pointer assignment warning [71] o tests/server: delete workaround for old-mingw [25] o tests: respect $TMPDIR when creating unix domain sockets [50] + o tool: make parser reject blank arguments if not supported [86] + o tool: prepend output_dir in header callback [95] + o tool_getparam: bsearch cmdline options [74] o tool_getparam: do not try to expand without an argument [59] o tool_listhelp: regenerate after recent .d updates [61] + o transfer: adjust_pollset improvements [81] o transfer: fix upload rate limiting, add test cases [37] o url: for disabled protocols, mention if found in redirect [7] o verify-examples.pl: fail verification on unescaped backslash [72] @@ -84,6 +98,7 @@ This release includes the following bugfixes: o vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY [41] o windows: delete redundant headers [43] o windows: simplify detecting and using system headers [10] + o wolfssl: load certificate *chain* for PEM client certs [84] This release includes the following known bugs: @@ -98,16 +113,17 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - annalee, Baruch Siach, Ben, Boris Verkhovskiy, Cajus Pollmeier, - calvin2021y on github, Chara White, Chris Sauer, Dan Fandrich, - Daniel Gustafsson, Daniel Stenberg, Dmitry Karpov, Geeknik Labs, - Hans-Christian Egtvedt, Haydar Alaidrus, iAroc on github, ivanfywang, - Karthikdasari0423 on github, Marcel Raad, Mark Sinkovics, Mauricio Scheffer, - Michał Antoniak, Mike Hommey, Ozan Cansel, Patrick Monnerat, Pavel Pavlov, - Ray Satiro, RevaliQaQ on github, Stefan Eissing, Tatsuhiko Miyagawa, Theo, - Viktor Szakats, Xi Ruoyao, Yedaya Katsman, Yifei Kong, YX Hao, zengwei, - zengwei2000 - (38 contributors) + Andy Alt, annalee, Baruch Siach, Ben, Boris Verkhovskiy, + bubbleguuum on github, Cajus Pollmeier, calvin2021y on github, Chara White, + Chris Sauer, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, + dependabot[bot], Dmitry Karpov, Gabe, Geeknik Labs, Gisle Vanem, + Hans-Christian Egtvedt, Haydar Alaidrus, hgdagon on github, iAroc on github, + ivanfywang, Karthikdasari0423 on github, Lealem Amedie, Marcel Raad, + Mark Sinkovics, Mauricio Scheffer, Michał Antoniak, Mike Hommey, Ozan Cansel, + Patrick Monnerat, Pavel Pavlov, Ray Satiro, RevaliQaQ on github, + Stefan Eissing, Tatsuhiko Miyagawa, Theo, Thomas Ferguson, Viktor Szakats, + Xi Ruoyao, Yedaya Katsman, Yifei Kong, YX Hao, zengwei, zengwei2000 + (46 contributors) References to bug reports and discussions on issues: @@ -170,7 +186,10 @@ References to bug reports and discussions on issues: [57] = https://curl.se/bug/?i=12554 [58] = https://curl.se/bug/?i=12576 [59] = https://curl.se/bug/?i=12565 + [60] = https://curl.se/bug/?i=12650 [61] = https://curl.se/bug/?i=12612 + [62] = https://curl.se/bug/?i=12658 + [63] = https://curl.se/bug/?i=12649 [64] = https://curl.se/bug/?i=12612 [65] = https://curl.se/bug/?i=12590 [66] = https://curl.se/bug/?i=12613 @@ -181,5 +200,17 @@ References to bug reports and discussions on issues: [71] = https://curl.se/bug/?i=12581 [72] = https://curl.se/bug/?i=12589 [73] = https://curl.se/bug/?i=12599 + [74] = https://curl.se/bug/?i=12631 [75] = https://curl.se/bug/?i=12593 [76] = https://curl.se/bug/?i=12368 + [79] = https://curl.se/bug/?i=12647 + [81] = https://curl.se/bug/?i=12640 + [82] = https://curl.se/bug/?i=12639 + [83] = https://curl.se/bug/?i=12638 + [84] = https://curl.se/bug/?i=12634 + [85] = https://curl.se/bug/?i=12632 + [86] = https://curl.se/bug/?i=12620 + [91] = https://curl.se/bug/?i=12629 + [92] = https://curl.se/bug/?i=12608 + [94] = https://curl.se/bug/?i=12618 + [95] = https://curl.se/bug/?i=12614 From 2998874bb61ac6ef3b72d6a61467cd2aaf6e53ea Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 16:28:50 +0100 Subject: [PATCH 141/509] configure: make libpsl detection failure cause error To force users to explictily disable it if they really don't want it used and make it harder to accidentally miss it. --without-libpsl is the option to use if PSL is not wanted. Closes #12661 --- configure.ac | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/configure.ac b/configure.ac index 79c98b3c4e9..39dc0963f7e 100644 --- a/configure.ac +++ b/configure.ac @@ -2054,17 +2054,16 @@ dnl ********************************************************************** AC_ARG_WITH(libpsl, AS_HELP_STRING([--without-libpsl], - [disable support for libpsl cookie checking]), + [disable support for libpsl]), with_libpsl=$withval, with_libpsl=yes) +curl_psl_msg="no (libpsl disabled)" 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]) - ] + [AC_MSG_ERROR([libpsl was not found]) ] ) fi AM_CONDITIONAL([USE_LIBPSL], [test "$curl_psl_msg" = "enabled"]) From d18811b52bb4faf1ec7e55180cf6df8274e8b233 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Jan 2024 16:49:21 +0100 Subject: [PATCH 142/509] CI: install libpsl or configure --without-libpsl in builds As a follow-up to the stricted libpsl check in configure --- .azure-pipelines.yml | 20 ++++++++++---------- .circleci/config.yml | 9 +++++++-- .cirrus.yml | 2 +- .github/workflows/awslc.yml | 2 +- .github/workflows/configure-vs-cmake.yml | 2 +- .github/workflows/distcheck.yml | 8 ++++---- .github/workflows/linux.yml | 2 +- .github/workflows/macos.yml | 4 ++-- .github/workflows/wolfssl.yml | 2 +- 9 files changed, 28 insertions(+), 23 deletions(-) diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml index 12ecad3f8aa..5c789637c78 100644 --- a/.azure-pipelines.yml +++ b/.azure-pipelines.yml @@ -100,7 +100,7 @@ stages: 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) + - 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 @@ -169,59 +169,59 @@ stages: 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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) diff --git a/.circleci/config.yml b/.circleci/config.yml index 7877d247a26..e7ddc27d196 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -149,7 +149,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 +157,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 | 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 @@ -249,6 +249,7 @@ jobs: executor: ubuntu steps: - checkout + - install-deps - configure - build - test @@ -284,6 +285,7 @@ jobs: executor: ubuntu steps: - checkout + - install-deps - install-cares - configure-cares - build @@ -293,6 +295,7 @@ jobs: executor: ubuntu steps: - checkout + - install-deps - install-libssh - configure-libssh - build @@ -304,6 +307,7 @@ jobs: resource_class: arm.medium steps: - checkout + - install-deps - configure - build - test @@ -314,6 +318,7 @@ jobs: resource_class: arm.medium steps: - checkout + - install-deps - install-cares - configure-cares-debug - build diff --git a/.cirrus.yml b/.cirrus.yml index 3d327259c33..05c92756a47 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -54,7 +54,7 @@ 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 diff --git a/.github/workflows/awslc.yml b/.github/workflows/awslc.yml index c600d72d50d..b4011a42a71 100644 --- a/.github/workflows/awslc.yml +++ b/.github/workflows/awslc.yml @@ -53,7 +53,7 @@ jobs: steps: - run: | sudo apt-get update --yes - sudo apt-get install --yes libtool autoconf automake pkg-config stunnel4 + sudo apt-get install --yes libtool autoconf automake pkg-config stunnel4 libpsl-dev # ensure we don't pick up openssl in this build sudo apt remove --yes libssl-dev sudo python3 -m pip install impacket diff --git a/.github/workflows/configure-vs-cmake.yml b/.github/workflows/configure-vs-cmake.yml index 830c1460f3d..dc2273f7375 100644 --- a/.github/workflows/configure-vs-cmake.yml +++ b/.github/workflows/configure-vs-cmake.yml @@ -35,7 +35,7 @@ jobs: - name: run configure --with-openssl run: | autoreconf -fi - ./configure --with-openssl + ./configure --with-openssl --without-libpsl - name: run cmake run: | diff --git a/.github/workflows/distcheck.yml b/.github/workflows/distcheck.yml index 6daa7a242ec..15068b640b4 100644 --- a/.github/workflows/distcheck.yml +++ b/.github/workflows/distcheck.yml @@ -30,7 +30,7 @@ jobs: - run: autoreconf -fi name: 'autoreconf' - - run: ./configure --without-ssl + - run: ./configure --without-ssl --without-libpsl name: 'configure' - run: make V=1 && make V=1 clean @@ -48,7 +48,7 @@ jobs: echo "::stop-commands::$(uuidgen)" tar xvf curl-99.98.97.tar.gz pushd curl-99.98.97 - ./configure --prefix=$HOME/temp --without-ssl + ./configure --prefix=$HOME/temp --without-ssl --without-libpsl make make test-ci make install @@ -73,7 +73,7 @@ jobs: touch curl-99.98.97/docs/{cmdline-opts,libcurl}/Makefile.inc mkdir build pushd build - ../curl-99.98.97/configure --without-ssl + ../curl-99.98.97/configure --without-ssl --without-libpsl make make test-ci popd @@ -96,7 +96,7 @@ jobs: pushd curl-99.98.97 mkdir build pushd build - ../configure --without-ssl --enable-debug "--prefix=${PWD}/pkg" + ../configure --without-ssl --enable-debug "--prefix=${PWD}/pkg" --without-libpsl make -j3 make -j3 test-ci make -j3 install diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index 81e489ff272..ff0e310aa9d 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -154,7 +154,7 @@ jobs: singleuse: --unit - name: rustls - install_steps: rust rustls pytest valgrind + install_steps: rust rustls pytest valgrind libpsl-dev configure: --with-rustls=$HOME/rustls --enable-debug singleuse: --unit diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml index 49bb86cb486..2f2d75397aa 100644 --- a/.github/workflows/macos.yml +++ b/.github/workflows/macos.yml @@ -117,7 +117,7 @@ jobs: 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 + configure: CC=gcc-12 --enable-debug --with-secure-transport --enable-websockets --without-libpsl macosx-version-min: 10.8 - name: OpenSSL http2 install: nghttp2 openssl @@ -142,7 +142,7 @@ jobs: 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 + - 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 diff --git a/.github/workflows/wolfssl.yml b/.github/workflows/wolfssl.yml index d8f0fd4271f..5aaf3d1bd56 100644 --- a/.github/workflows/wolfssl.yml +++ b/.github/workflows/wolfssl.yml @@ -68,7 +68,7 @@ jobs: steps: - run: | sudo apt-get update - sudo apt-get install libtool autoconf automake pkg-config stunnel4 ${{ matrix.build.install }} + 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' From 2959f45b7d55dadd837f5bb2859780561f687ba1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 7 Jan 2024 16:28:15 +0100 Subject: [PATCH 143/509] telnet: use dynbuf instad of malloc for escape buffer Previously, send_telnet_data() would malloc + free a buffer every time for escaping IAC codes. Now, it reuses a dynbuf for this purpose. Closes #12652 --- lib/telnet.c | 57 +++++++++++++++++++++++----------------------------- 1 file changed, 25 insertions(+), 32 deletions(-) diff --git a/lib/telnet.c b/lib/telnet.c index 67667e347e5..b626bc56e53 100644 --- a/lib/telnet.c +++ b/lib/telnet.c @@ -160,6 +160,7 @@ struct TELNET { unsigned short subopt_wsy; /* Set with suboption NAWS */ TelnetReceive telrcv_state; struct curl_slist *telnet_vars; /* Environment variables */ + struct dynbuf out; /* output buffer */ /* suboptions */ unsigned char subbuffer[SUBBUFSIZE]; @@ -204,6 +205,7 @@ CURLcode init_telnet(struct Curl_easy *data) if(!tn) return CURLE_OUT_OF_MEMORY; + Curl_dyn_init(&tn->out, 0xffff); data->req.p.telnet = tn; /* make us known */ tn->telrcv_state = CURL_TS_DATA; @@ -1229,37 +1231,33 @@ CURLcode telrcv(struct Curl_easy *data, static CURLcode send_telnet_data(struct Curl_easy *data, char *buffer, ssize_t nread) { - ssize_t escapes, i, outlen; - unsigned char *outbuf = NULL; + ssize_t i, outlen; + unsigned char *outbuf; CURLcode result = CURLE_OK; - ssize_t bytes_written, total_written; + ssize_t bytes_written, total_written = 0; struct connectdata *conn = data->conn; + struct TELNET *tn = data->req.p.telnet; - /* Determine size of new buffer after escaping */ - escapes = 0; - for(i = 0; i < nread; i++) - if((unsigned char)buffer[i] == CURL_IAC) - escapes++; - outlen = nread + escapes; + DEBUGASSERT(tn); - if(outlen == nread) - outbuf = (unsigned char *)buffer; - else { - ssize_t j; - outbuf = malloc(nread + escapes + 1); - if(!outbuf) - return CURLE_OUT_OF_MEMORY; + if(memchr(buffer, CURL_IAC, nread)) { + /* only use the escape buffer when necessary */ + Curl_dyn_reset(&tn->out); - j = 0; - for(i = 0; i < nread; i++) { - outbuf[j++] = (unsigned char)buffer[i]; - if((unsigned char)buffer[i] == CURL_IAC) - outbuf[j++] = CURL_IAC; + for(i = 0; i < nread && !result; i++) { + result = Curl_dyn_addn(&tn->out, &buffer[i], 1); + if(!result && ((unsigned char)buffer[i] == CURL_IAC)) + /* IAC is FF in hex */ + result = Curl_dyn_addn(&tn->out, "\xff", 1); } - outbuf[j] = '\0'; - } - total_written = 0; + outlen = Curl_dyn_len(&tn->out); + outbuf = Curl_dyn_uptr(&tn->out); + } + else { + outlen = nread; + outbuf = (unsigned char *)buffer; + } while(!result && total_written < outlen) { /* Make sure socket is writable to avoid EWOULDBLOCK condition */ struct pollfd pfd[1]; @@ -1272,19 +1270,13 @@ static CURLcode send_telnet_data(struct Curl_easy *data, break; default: /* write! */ bytes_written = 0; - result = Curl_nwrite(data, FIRSTSOCKET, - outbuf + total_written, - outlen - total_written, - &bytes_written); + result = Curl_nwrite(data, FIRSTSOCKET, outbuf + total_written, + outlen - total_written, &bytes_written); total_written += bytes_written; break; } } - /* Free malloc copy if escaped */ - if(outbuf != (unsigned char *)buffer) - free(outbuf); - return result; } @@ -1300,6 +1292,7 @@ static CURLcode telnet_done(struct Curl_easy *data, curl_slist_free_all(tn->telnet_vars); tn->telnet_vars = NULL; + Curl_dyn_free(&tn->out); return CURLE_OK; } From ac4dbc9cb5407202ff9cc80bf90968a87603400c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 7 Jan 2024 16:11:01 +0100 Subject: [PATCH 144/509] setopt: use memdup0 when cloning COPYPOSTFIELDS Closes #12651 --- lib/setopt.c | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/lib/setopt.c b/lib/setopt.c index 72bd6cdf6f6..a5270773f39 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -51,7 +51,7 @@ #include "altsvc.h" #include "hsts.h" #include "tftp.h" - +#include "strdup.h" /* The last 3 #include files should be in this order */ #include "curl_printf.h" #include "curl_memory.h" @@ -508,26 +508,17 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) (data->set.postfieldsize > (curl_off_t)((size_t)-1)))) result = CURLE_OUT_OF_MEMORY; else { - char *p; - - (void) Curl_setstropt(&data->set.str[STRING_COPYPOSTFIELDS], NULL); - /* Allocate even when size == 0. This satisfies the need of possible - later address compare to detect the COPYPOSTFIELDS mode, and - to mark that postfields is used rather than read function or - form data. + later address compare to detect the COPYPOSTFIELDS mode, and to + mark that postfields is used rather than read function or form + data. */ - p = malloc((size_t)(data->set.postfieldsize? - data->set.postfieldsize:1)); - + char *p = Curl_memdup0(argptr, (size_t)data->set.postfieldsize); + (void) Curl_setstropt(&data->set.str[STRING_COPYPOSTFIELDS], NULL); if(!p) result = CURLE_OUT_OF_MEMORY; - else { - if(data->set.postfieldsize) - memcpy(p, argptr, (size_t)data->set.postfieldsize); - + else data->set.str[STRING_COPYPOSTFIELDS] = p; - } } } From 0ad13e061819e8fa9d1ea34dca4b66c08aa333f4 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Sun, 7 Jan 2024 00:25:13 -0500 Subject: [PATCH 145/509] cookie.d: Document use of empty string to enable cookie engine - Explain that --cookie "" can be used to enable the cookie engine without reading any initial cookies. As is documented in CURLOPT_COOKIEFILE. Ref: https://curl.se/libcurl/c/CURLOPT_COOKIEFILE.html Bug: https://github.com/curl/curl/issues/12643#issuecomment-1879844420 Reported-by: janko-js@users.noreply.github.com Closes https://github.com/curl/curl/pull/12646 --- docs/cmdline-opts/cookie.d | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d index 0f858d6613b..23f3f466a3e 100644 --- a/docs/cmdline-opts/cookie.d +++ b/docs/cmdline-opts/cookie.d @@ -6,6 +6,7 @@ Arg: Protocols: HTTP Help: Send cookies from string/file Category: http +Example: -b "" $URL Example: -b cookiefile $URL Example: -b cookiefile -c cookiefile $URL See-also: cookie-jar junk-session-cookies @@ -23,8 +24,11 @@ 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. +transfers on the same invoke. + +If the file name is exactly a minus ("-"), curl instead reads the contents from +stdin. If the file name is an empty string ("") and is the only cookie input, +curl will activate 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. From a859e29a60cf00129cc3484b1dd3423102958a5a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2024 10:20:48 +0100 Subject: [PATCH 146/509] gen.pl: support ## for doing .IP in table-like lists Warn on use of .RS/.IP/.RE Closes #12667 --- docs/cmdline-opts/MANPAGE.md | 13 +++++++++++++ docs/cmdline-opts/gen.pl | 26 ++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 6de32dab94d..4896f8513ef 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -54,6 +54,19 @@ 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. +Within the body, describe a lite 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": + + ## + ## Header and footer `page-header` is the file that is output before the generated options output diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index 16324550888..fbe0f546b88 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -319,10 +319,36 @@ sub single { } } my @desc; + my $tablemode = 0; while() { + $line++; + if(/^## (.*)/) { + if(!$tablemode) { + push @desc, ".RS\n"; + $tablemode = 1; + } + push @desc, ".IP \"\\fB$1\\fP\"\n"; + next; + } + elsif(/^##/) { + if($tablemode) { + # end of table + push @desc, ".RE\n.IP\n"; + $tablmode = 0; + } + next; + } + elsif(/^\.(IP|RS|RE)/) { + my ($cmd) = ($1); + print STDERR "$f:$line:1:ERROR: $cmd detected, use ##-style\n"; + } push @desc, $_; } close(F); + if($tablemode) { + # end of table + push @desc, ".RE\n.IP\n"; + } my $opt; if(defined($short) && $long) { From 89bb115e4a43020e5dc8dee89b559b13c73ee1e9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2024 10:36:14 +0100 Subject: [PATCH 147/509] cmdline/docs/*.d: switch to using ## instead of .IP To make the editing easier. To write and to read. Closes #12667 --- docs/cmdline-opts/data-urlencode.d | 18 +-- docs/cmdline-opts/delegation.d | 12 +- docs/cmdline-opts/ftp-method.d | 12 +- docs/cmdline-opts/ftp-port.d | 25 ++-- docs/cmdline-opts/proto.d | 15 ++- docs/cmdline-opts/quote.d | 39 +++--- docs/cmdline-opts/range.d | 30 +++-- docs/cmdline-opts/request.d | 18 +-- docs/cmdline-opts/telnet-option.d | 11 +- docs/cmdline-opts/tls-max.d | 17 +-- docs/cmdline-opts/variable.d | 15 ++- docs/cmdline-opts/version.d | 87 ++++++++----- docs/cmdline-opts/write-out.d | 198 +++++++++++++++++++---------- 13 files changed, 305 insertions(+), 192 deletions(-) diff --git a/docs/cmdline-opts/data-urlencode.d b/docs/cmdline-opts/data-urlencode.d index 3c436b26b15..51c0b4b7ce2 100644 --- a/docs/cmdline-opts/data-urlencode.d +++ b/docs/cmdline-opts/data-urlencode.d @@ -19,24 +19,26 @@ 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" + +## 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" + +## =content This makes curl URL-encode the content and pass that on. The preceding = symbol is not included in the data. -.IP "name=content" + +## 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" + +## @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" + +## 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/delegation.d b/docs/cmdline-opts/delegation.d index 7941849347f..004514f37b9 100644 --- a/docs/cmdline-opts/delegation.d +++ b/docs/cmdline-opts/delegation.d @@ -12,13 +12,13 @@ Multi: single --- Set LEVEL to tell the server what it is allowed to delegate when it comes to user credentials. -.RS -.IP "none" + +## none Do not allow any delegation. -.IP "policy" + +## 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" + +## always Unconditionally allow the server to delegate. -.RE -.IP diff --git a/docs/cmdline-opts/ftp-method.d b/docs/cmdline-opts/ftp-method.d index 8061d2b682b..e3a08782b33 100644 --- a/docs/cmdline-opts/ftp-method.d +++ b/docs/cmdline-opts/ftp-method.d @@ -14,17 +14,17 @@ 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 + +## 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 + +## 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 + +## 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-port.d b/docs/cmdline-opts/ftp-port.d index e1f4a1dba72..3026778d968 100644 --- a/docs/cmdline-opts/ftp-port.d +++ b/docs/cmdline-opts/ftp-port.d @@ -18,18 +18,21 @@ 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 "-" + +## 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 + +## host name +e.g. **my.host.domain** to specify the machine + +## - make curl pick the same IP address that is already used for the control -connection -.RE -.IP +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++. diff --git a/docs/cmdline-opts/proto.d b/docs/cmdline-opts/proto.d index 6788ee567db..68dd3a2078d 100644 --- a/docs/cmdline-opts/proto.d +++ b/docs/cmdline-opts/proto.d @@ -12,18 +12,21 @@ 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 -.IP + + +## + Permit this protocol in addition to protocols already permitted (this is the default if no modifier is used). -.IP - + +## - Deny this protocol, removing it from the list of protocols already permitted. -.IP = + +## = 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: --proto -ftps uses the default protocols, but disables ftps --proto -all,https,+http only enables http and https diff --git a/docs/cmdline-opts/quote.d b/docs/cmdline-opts/quote.d index 51f7917fc37..3210257476e 100644 --- a/docs/cmdline-opts/quote.d +++ b/docs/cmdline-opts/quote.d @@ -34,42 +34,51 @@ 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 -.IP "atime date file" + +## 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) -.IP "chgrp group file" + +## 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. -.IP "chmod mode file" + +## chmod mode file The chmod command modifies the file mode bits of the specified file. The mode operand is an octal integer mode number. -.IP "chown user file" + +## 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. -.IP "ln source_file target_file" + +## 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. -.IP "mkdir directory_name" + +## mkdir directory_name The mkdir command creates the directory named by the directory_name operand. -.IP "mtime date file" + +## 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) -.IP "pwd" + +## pwd The pwd command returns the absolute path name of the current working directory. -.IP "rename source target" + +## 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. -.IP "rm file" + +## rm file The rm command removes the file specified by the file operand. -.IP "rmdir directory" + +## rmdir directory The rmdir command removes the directory entry specified by the directory operand, provided it is empty. -.IP "symlink source_file target_file" + +## symlink source_file target_file See ln. -.RE -.IP diff --git a/docs/cmdline-opts/range.d b/docs/cmdline-opts/range.d index 09ccf5f310a..fc5267faac3 100644 --- a/docs/cmdline-opts/range.d +++ b/docs/cmdline-opts/range.d @@ -13,24 +13,30 @@ 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 -.IP 0-499 + +## 0-499 specifies the first 500 bytes -.IP 500-999 + +## 500-999 specifies the second 500 bytes -.IP -500 + +## -500 specifies the last 500 bytes -.IP 9500- + +## 9500- specifies the bytes from offset 9500 and forward -.IP 0-0,-1 + +## 0-0,-1 specifies the first and last byte only(*)(HTTP) -.IP 100-199,500-599 + +## 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. + +## + +(*) = 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 diff --git a/docs/cmdline-opts/request.d b/docs/cmdline-opts/request.d index 41d81c55afd..4e022c5eaa9 100644 --- a/docs/cmdline-opts/request.d +++ b/docs/cmdline-opts/request.d @@ -15,8 +15,8 @@ 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 -.IP HTTP + +## 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 @@ -35,15 +35,17 @@ 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. -.IP FTP + +## FTP Specifies a custom FTP command to use instead of *LIST* when doing file lists with FTP. -.IP POP3 + +## POP3 Specifies a custom POP3 command to use instead of *LIST* or *RETR*. (Added in 7.26.0) -.IP IMAP + +## IMAP Specifies a custom IMAP command to use instead of *LIST*. (Added in 7.30.0) -.IP SMTP + +## 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/telnet-option.d b/docs/cmdline-opts/telnet-option.d index 56bf5be636d..2c8a76180b6 100644 --- a/docs/cmdline-opts/telnet-option.d +++ b/docs/cmdline-opts/telnet-option.d @@ -12,12 +12,11 @@ Multi: append --- Pass options to the telnet protocol. Supported options are: -.RS -.IP "TTYPE=" +## TTYPE= Sets the terminal type. -.IP "XDISPLOC=" + +## XDISPLOC= Sets the X display location. -.IP "NEW_ENV=" + +## NEW_ENV= Sets an environment variable. -.RE -.IP diff --git a/docs/cmdline-opts/tls-max.d b/docs/cmdline-opts/tls-max.d index 2d52c1039f1..894cb76e9fc 100644 --- a/docs/cmdline-opts/tls-max.d +++ b/docs/cmdline-opts/tls-max.d @@ -19,16 +19,17 @@ is set by tlsv1.0, tlsv1.1, tlsv1.2 or tlsv1.3. If the connection is done without TLS, this option has no effect. This includes QUIC-using (HTTP/3) transfers. -.RS -.IP "default" +## default Use up to recommended TLS version. -.IP "1.0" + +## 1.0 Use up to TLSv1.0. -.IP "1.1" + +## 1.1 Use up to TLSv1.1. -.IP "1.2" + +## 1.2 Use up to TLSv1.2. -.IP "1.3" + +## 1.3 Use up to TLSv1.3. -.RE -.IP diff --git a/docs/cmdline-opts/variable.d b/docs/cmdline-opts/variable.d index 2029601976b..31b9d00cc38 100644 --- a/docs/cmdline-opts/variable.d +++ b/docs/cmdline-opts/variable.d @@ -38,14 +38,15 @@ content holding null bytes that are not encoded when expanded, causes an error. Available functions: -.RS -.IP trim + +## trim removes all leading and trailing white space. -.IP json + +## json outputs the content using JSON string quoting rules. -.IP url + +## url shows the content URL (percent) encoded. -.IP b64 + +## b64 expands the variable base64 encoded -.RE -.IP diff --git a/docs/cmdline-opts/version.d b/docs/cmdline-opts/version.d index 8d231ce0c35..9407736c554 100644 --- a/docs/cmdline-opts/version.d +++ b/docs/cmdline-opts/version.d @@ -21,68 +21,93 @@ reports to support. The fourth line (starts with "Features:") shows specific features libcurl reports to offer. Available features include: -.RS -.IP "alt-svc" + +## alt-svc Support for the Alt-Svc: header is provided. -.IP "AsynchDNS" + +## AsynchDNS This curl uses asynchronous name resolves. Asynchronous name resolves can be done using either the c-ares or the threaded resolver backends. -.IP "brotli" + +## brotli Support for automatic brotli compression over HTTP(S). -.IP "CharConv" + +## CharConv curl was built with support for character set conversions (like EBCDIC) -.IP "Debug" + +## Debug This curl uses a libcurl built with Debug. This enables more error-tracking and memory debugging etc. For curl-developers only! -.IP "gsasl" + +## gsasl The built-in SASL authentication includes extensions to support SCRAM because libcurl was built with libgsasl. -.IP "GSS-API" + +## GSS-API GSS-API is supported. -.IP "HSTS" + +## HSTS HSTS support is present. -.IP "HTTP2" + +## HTTP2 HTTP/2 support has been built-in. -.IP "HTTP3" + +## HTTP3 HTTP/3 support has been built-in. -.IP "HTTPS-proxy" + +## HTTPS-proxy This curl is built to support HTTPS proxy. -.IP "IDN" + +## IDN This curl supports IDN - international domain names. -.IP "IPv6" + +## IPv6 You can use IPv6 with this. -.IP "Kerberos" + +## Kerberos Kerberos V5 authentication is supported. -.IP "Largefile" + +## Largefile This curl supports transfers of large files, files larger than 2GB. -.IP "libz" + +## libz Automatic decompression (via gzip, deflate) of compressed files over HTTP is supported. -.IP "MultiSSL" + +## MultiSSL This curl supports multiple TLS backends. -.IP "NTLM" + +## NTLM NTLM authentication is supported. -.IP "NTLM_WB" + +## NTLM_WB NTLM delegation to winbind helper is supported. -.IP "PSL" + +## PSL PSL is short for Public Suffix List and means that this curl has been built with knowledge about "public suffixes". -.IP "SPNEGO" + +## SPNEGO SPNEGO authentication is supported. -.IP "SSL" + +## SSL SSL versions of various protocols are supported, such as HTTPS, FTPS, POP3S and so on. -.IP "SSPI" + +## SSPI SSPI is supported. -.IP "TLS-SRP" + +## TLS-SRP SRP (Secure Remote Password) authentication is supported for TLS. -.IP "TrackMemory" + +## TrackMemory Debug memory tracking is supported. -.IP "Unicode" + +## Unicode Unicode support on Windows. -.IP "UnixSockets" + +## UnixSockets Unix sockets support is provided. -.IP "zstd" + +## zstd Automatic decompression (via zstd) of compressed files over HTTP is supported. -.RE -.IP diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d index d21a747dc5f..5975c8e2d56 100644 --- a/docs/cmdline-opts/write-out.d +++ b/docs/cmdline-opts/write-out.d @@ -45,25 +45,31 @@ option to properly escape. If this option is used at the command prompt then the % cannot be escaped and unintended expansion is possible. The variables available are: -.RS -.IP certs + +## certs Output the certificate chain with details. Supported only by the OpenSSL, GnuTLS, Schannel and Secure Transport backends. (Added in 7.88.0) -.IP content_type + +## content_type The Content-Type of the requested document, if there was any. -.IP errormsg + +## errormsg The error message. (Added in 7.75.0) -.IP exitcode + +## exitcode The numerical exit code of the transfer. (Added in 7.75.0) -.IP filename_effective + +## filename_effective The ultimate filename that curl writes out to. This is only meaningful if curl is told to write to a file with the --remote-name or --output option. It's most useful in combination with the --remote-header-name option. (Added in 7.26.0) -.IP ftp_entry_path + +## ftp_entry_path The initial path curl ended up in when logging on to the remote FTP server. (Added in 7.15.4) -.IP header_json + +## header_json A JSON object with all HTTP response headers from the recent transfer. Values are provided as arrays, since in the case of multiple headers there can be multiple values. (Added in 7.83.0) @@ -71,157 +77,213 @@ multiple values. (Added in 7.83.0) The header names provided in lowercase, listed in order of appearance over the wire. Except for duplicated headers. They are grouped on the first occurrence of that header, each value is presented in the JSON array. -.IP http_code + +## http_code The numerical response code that was found in the last retrieved HTTP(S) or FTP(s) transfer. -.IP http_connect + +## http_connect The numerical code that was found in the last response (from a proxy) to a curl CONNECT request. (Added in 7.12.4) -.IP http_version + +## http_version The http version that was effectively used. (Added in 7.50.0) -.IP json + +## json A JSON object with all available keys. (Added in 7.70.0) -.IP local_ip + +## local_ip The IP address of the local end of the most recently done connection - can be either IPv4 or IPv6. (Added in 7.29.0) -.IP local_port + +## local_port The local port number of the most recently done connection. (Added in 7.29.0) -.IP method + +## method The http method used in the most recent HTTP request. (Added in 7.72.0) -.IP num_certs + +## num_certs Number of server certificates received in the TLS handshake. Supported only by the OpenSSL, GnuTLS, Schannel and Secure Transport backends. (Added in 7.88.0) -.IP num_connects + +## num_connects Number of new connects made in the recent transfer. (Added in 7.12.3) -.IP num_headers + +## num_headers The number of response headers in the most recent request (restarted at each redirect). Note that the status line IS NOT a header. (Added in 7.73.0) -.IP num_redirects + +## num_redirects Number of redirects that were followed in the request. (Added in 7.12.3) -.IP onerror + +## onerror The rest of the output is only shown if the transfer returned a non-zero error. (Added in 7.75.0) -.IP "proxy_ssl_verify_result" + +## "proxy_ssl_verify_result" The result of the HTTPS proxy's SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.52.0) -.IP redirect_url + +## redirect_url When an HTTP request was made without --location to follow redirects (or when --max-redirs is met), this variable shows the actual URL a redirect *would* have gone to. (Added in 7.18.2) -.IP referer + +## referer The Referer: header, if there was any. (Added in 7.76.0) -.IP remote_ip + +## remote_ip The remote IP address of the most recently done connection - can be either IPv4 or IPv6. (Added in 7.29.0) -.IP remote_port + +## remote_port The remote port number of the most recently done connection. (Added in 7.29.0) -.IP response_code + +## response_code The numerical response code that was found in the last transfer (formerly known as "http_code"). (Added in 7.18.2) -.IP scheme + +## scheme The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0) -.IP size_download + +## size_download The total amount of bytes that were downloaded. This is the size of the body/data that was transferred, excluding headers. -.IP size_header + +## size_header The total amount of bytes of the downloaded headers. -.IP size_request + +## size_request The total amount of bytes that were sent in the HTTP request. -.IP size_upload + +## size_upload The total amount of bytes that were uploaded. This is the size of the body/data that was transferred, excluding headers. -.IP speed_download + +## speed_download The average download speed that curl measured for the complete download. Bytes per second. -.IP speed_upload + +## speed_upload The average upload speed that curl measured for the complete upload. Bytes per second. -.IP ssl_verify_result + +## ssl_verify_result The result of the SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.19.0) -.IP stderr + +## stderr From this point on, the --write-out output is written to standard error. (Added in 7.63.0) -.IP stdout + +## stdout From this point on, the --write-out output is written to standard output. This is the default, but can be used to switch back after switching to stderr. (Added in 7.63.0) -.IP time_appconnect + +## time_appconnect The time, in seconds, it took from the start until the SSL/SSH/etc connect/handshake to the remote host was completed. (Added in 7.19.0) -.IP time_connect + +## time_connect The time, in seconds, it took from the start until the TCP connect to the remote host (or proxy) was completed. -.IP time_namelookup + +## time_namelookup The time, in seconds, it took from the start until the name resolving was completed. -.IP time_pretransfer + +## time_pretransfer The time, in seconds, it took from the start until the file transfer was just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. -.IP time_redirect + +## time_redirect The time, in seconds, it took for all redirection steps including name lookup, connect, pretransfer and transfer before the final transaction was started. time_redirect shows the complete execution time for multiple redirections. (Added in 7.12.3) -.IP time_starttransfer + +## time_starttransfer The time, in seconds, it took from the start until the first byte is received. This includes time_pretransfer and also the time the server needed to calculate the result. -.IP time_total + +## time_total The total time, in seconds, that the full operation lasted. -.IP url + +## url The URL that was fetched. (Added in 7.75.0) -.IP url.scheme + +## url.scheme The scheme part of the URL that was fetched. (Added in 8.1.0) -.IP url.user + +## url.user The user part of the URL that was fetched. (Added in 8.1.0) -.IP url.password + +## url.password The password part of the URL that was fetched. (Added in 8.1.0) -.IP url.options + +## url.options The options part of the URL that was fetched. (Added in 8.1.0) -.IP url.host + +## url.host The host part of the URL that was fetched. (Added in 8.1.0) -.IP url.port + +## url.port The port number of the URL that was fetched. If no port number was specified, but the URL scheme is known, that scheme's default port number is shown. (Added in 8.1.0) -.IP url.path + +## url.path The path part of the URL that was fetched. (Added in 8.1.0) -.IP url.query + +## url.query The query part of the URL that was fetched. (Added in 8.1.0) -.IP url.fragment + +## url.fragment The fragment part of the URL that was fetched. (Added in 8.1.0) -.IP url.zoneid + +## url.zoneid The zone id part of the URL that was fetched. (Added in 8.1.0) -.IP urle.scheme + +## urle.scheme The scheme part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urle.user + +## urle.user The user part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urle.password + +## urle.password The password part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urle.options + +## urle.options The options part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urle.host + +## urle.host The host part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urle.port + +## urle.port The port number of the effective (last) URL that was fetched. If no port number was specified, but the URL scheme is known, that scheme's default port number is shown. (Added in 8.1.0) -.IP urle.path + +## urle.path The path part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urle.query + +## urle.query The query part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urle.fragment + +## urle.fragment The fragment part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urle.zoneid + +## urle.zoneid The zone id part of the effective (last) URL that was fetched. (Added in 8.1.0) -.IP urlnum + +## urlnum The URL index number of this transfer, 0-indexed. Unglobbed URLs share the same index number as the origin globbed URL. (Added in 7.75.0) -.IP url_effective + +## url_effective The URL that was fetched last. This is most meaningful if you have told curl to follow location: headers. -.RE -.IP From e2fbe56610621261fc3032d43ed6d4bf7b52a20b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2024 11:09:30 +0100 Subject: [PATCH 148/509] CI: spellcheck/appveyor: invoke configure --without-libpsl Follow-up to 2998874bb61ac6 --- .github/workflows/spellcheck.yml | 2 +- appveyor.yml | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 5eac83c7438..f08538ad5e4 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -39,7 +39,7 @@ jobs: - name: build curl.1 run: | autoreconf -fi - ./configure --without-ssl + ./configure --without-ssl --without-libpsl make -C docs - name: strip "uncheckable" sections from .3 pages diff --git a/appveyor.yml b/appveyor.yml index f4911452ae5..534109e56c1 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -244,19 +244,19 @@ environment: BUILD_SYSTEM: autotools TESTING: 'ON' DISABLED_TESTS: '!19 !1233' - 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' - 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' - 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' @@ -264,7 +264,7 @@ environment: TESTING: 'ON' DISABLED_TESTS: '' ADD_SHELL: 'C:/cygwin64/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' install: - ps: | From 6d9bf0db7e3800fb787697086bba1b1cc2008b84 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2024 11:12:02 +0100 Subject: [PATCH 149/509] WEBSOCKET.md: remove dead link --- docs/WEBSOCKET.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/WEBSOCKET.md b/docs/WEBSOCKET.md index ba84c2284f3..c3967b8eab5 100644 --- a/docs/WEBSOCKET.md +++ b/docs/WEBSOCKET.md @@ -109,10 +109,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**: From 48d86999af12c8dee410296ae7a8f7072ea02042 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 9 Jan 2024 09:29:34 +0100 Subject: [PATCH 150/509] multi: pollset adjust, init with FIRSTSOCKET during connect - `conn->sockfd` is set by `Curl_setup_transfer()`, but that is called *after* the connection has been established - use `conn->sock[FIRSTSOCKET]` instead Follow-up to a0f94800d507de Closes #12664 --- lib/multi.c | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/multi.c b/lib/multi.c index e4491d912c9..63ab67691ed 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -998,9 +998,11 @@ static int connecting_getsock(struct Curl_easy *data, curl_socket_t *socks) { struct connectdata *conn = data->conn; (void)socks; - if(conn && conn->sockfd != CURL_SOCKET_BAD) { + /* Not using `conn->sockfd` as `Curl_setup_transfer()` initializes + * that *after* the connect. */ + if(conn && conn->sock[FIRSTSOCKET] != CURL_SOCKET_BAD) { /* Default is to wait to something from the server */ - socks[0] = conn->sockfd; + socks[0] = conn->sock[FIRSTSOCKET]; return GETSOCK_READSOCK(0); } return GETSOCK_BLANK; From ebbc6243d75c26f7cd296807d073c4079f4d1841 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2024 23:42:01 +0100 Subject: [PATCH 151/509] examples/address-scope.c: renamed from ipv6.c It shows address scope use really Closes #12671 --- docs/examples/address-scope.c | 62 +++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/examples/address-scope.c diff --git a/docs/examples/address-scope.c b/docs/examples/address-scope.c new file mode 100644 index 00000000000..dc305a072ec --- /dev/null +++ b/docs/examples/address-scope.c @@ -0,0 +1,62 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ +/* + * HTTP GET to an IPv6 address with specific scope + * + */ +#include +#include + +#ifndef _WIN32 +#include +#endif + +int main(void) +{ +#ifndef _WIN32 + /* Windows users need to find how to use if_nametoindex() */ + CURL *curl; + CURLcode res; + + curl = curl_easy_init(); + if(curl) { + long my_scope_id; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + my_scope_id = if_nametoindex("eth0"); + curl_easy_setopt(curl, CURLOPT_ADDRESS_SCOPE, my_scope_id); + + /* Perform the request, res will get the return code */ + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* always cleanup */ + curl_easy_cleanup(curl); + } +#endif + return 0; +} From dd09f88f13a3f7ff734be1b19fdf3f15fd662bf5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2024 23:42:17 +0100 Subject: [PATCH 152/509] examples/ipv6.c: new example showing IPv6-only internet transfer Closes #12671 --- docs/examples/ipv6.c | 26 ++++++-------------------- 1 file changed, 6 insertions(+), 20 deletions(-) diff --git a/docs/examples/ipv6.c b/docs/examples/ipv6.c index dc305a072ec..1b698705d0c 100644 --- a/docs/examples/ipv6.c +++ b/docs/examples/ipv6.c @@ -22,41 +22,27 @@ * ***************************************************************************/ /* - * HTTP GET to an IPv6 address with specific scope + * HTTPS GET using IPv6 only * */ #include #include -#ifndef _WIN32 -#include -#endif - int main(void) { -#ifndef _WIN32 - /* Windows users need to find how to use if_nametoindex() */ CURL *curl; - CURLcode res; + CURLcode res = CURLE_OK; curl = curl_easy_init(); if(curl) { - long my_scope_id; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V6); - my_scope_id = if_nametoindex("eth0"); - curl_easy_setopt(curl, CURLOPT_ADDRESS_SCOPE, my_scope_id); + curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/"); - /* Perform the request, res will get the return code */ res = curl_easy_perform(curl); - /* Check for errors */ - if(res != CURLE_OK) - fprintf(stderr, "curl_easy_perform() failed: %s\n", - curl_easy_strerror(res)); - /* always cleanup */ curl_easy_cleanup(curl); } -#endif - return 0; + + return (int)res; } From 1404bcdeaebe4608eb0d31a528f3bcde55f39f96 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2024 23:44:24 +0100 Subject: [PATCH 153/509] examples/netrc.c: add Closes #12671 --- docs/examples/Makefile.inc | 2 ++ docs/examples/netrc.c | 49 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100644 docs/examples/netrc.c diff --git a/docs/examples/Makefile.inc b/docs/examples/Makefile.inc index 1f1996c3700..baaedf9755a 100644 --- a/docs/examples/Makefile.inc +++ b/docs/examples/Makefile.inc @@ -25,6 +25,7 @@ # These are all libcurl example programs to be test compiled check_PROGRAMS = \ 10-at-a-time \ + address-scope \ altsvc \ anyauthput \ certinfo \ @@ -88,6 +89,7 @@ check_PROGRAMS = \ multi-legacy \ multi-post \ multi-single \ + netrc \ parseurl \ persistent \ pop3-authzid \ diff --git a/docs/examples/netrc.c b/docs/examples/netrc.c new file mode 100644 index 00000000000..42e1b6341e5 --- /dev/null +++ b/docs/examples/netrc.c @@ -0,0 +1,49 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ +/* + * Use credentials from .netrc + * + */ +#include +#include + +int main(void) +{ + CURL *curl; + CURLcode res = CURLE_OK; + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); + curl_easy_setopt(curl, CURLOPT_NETRC_FILE, + "/home/daniel/s3cr3ts.txt"); + curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } + + return (int)res; +} From 5d75bcd2eaa9b10b843dfe6d194a10524de79d46 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2024 23:47:01 +0100 Subject: [PATCH 154/509] examples/range.c: add Closes #12671 --- docs/examples/Makefile.inc | 1 + docs/examples/range.c | 45 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 docs/examples/range.c diff --git a/docs/examples/Makefile.inc b/docs/examples/Makefile.inc index baaedf9755a..71dac0bf436 100644 --- a/docs/examples/Makefile.inc +++ b/docs/examples/Makefile.inc @@ -109,6 +109,7 @@ check_PROGRAMS = \ postit2-formadd \ progressfunc \ protofeats \ + range \ resolve \ rtsp-options \ sendrecv \ diff --git a/docs/examples/range.c b/docs/examples/range.c new file mode 100644 index 00000000000..1a93f3676af --- /dev/null +++ b/docs/examples/range.c @@ -0,0 +1,45 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ +/* + * GET a range only of a HTTP resource + * + */ +#include + +int main(void) +{ + CURL *curl; + CURLcode res = CURLE_OK; + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/"); + curl_easy_setopt(curl, CURLOPT_RANGE, "200-999"); + + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } + + return (int)res; +} From 77c3c1a8fb051b9cbc95858d5c8139629d837e2a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Jan 2024 00:42:17 +0100 Subject: [PATCH 155/509] curl_easy_header.3: tiny language fix Closes #12672 --- docs/libcurl/curl_easy_header.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/libcurl/curl_easy_header.3 b/docs/libcurl/curl_easy_header.3 index a5f44db1ca7..8cbd3e272ac 100644 --- a/docs/libcurl/curl_easy_header.3 +++ b/docs/libcurl/curl_easy_header.3 @@ -66,7 +66,7 @@ second, then only the first one is provided. An application using this API does not have to bother about multiple headers used wrongly. The memory for the returned struct is associated with the easy handle and -subsequent calls to \fIcurl_easy_header(3)\fP clobbers the struct used in the +subsequent calls to \fIcurl_easy_header(3)\fP clobber the struct used in the previous calls for the same easy handle. Applications need to copy the data if it wants to keep it around. The memory used for the struct gets freed with calling \fIcurl_easy_cleanup(3)\fP of the easy handle. From a9e128d569f767bc6a1e0a4f60b49170e6b0d371 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Jan 2024 09:22:59 +0100 Subject: [PATCH 156/509] headers: make sure the trailing newline is not stored extended test1940 to verify blank header fields too Bug: https://curl.se/mail/lib-2024-01/0019.html Reported-by: Dmitry Karpov Closes #12675 --- lib/headers.c | 2 +- tests/data/test1940 | 4 ++++ tests/data/test421 | 2 +- tests/libtest/lib1940.c | 2 ++ 4 files changed, 8 insertions(+), 2 deletions(-) diff --git a/lib/headers.c b/lib/headers.c index b6fcdda777c..9c29238993a 100644 --- a/lib/headers.c +++ b/lib/headers.c @@ -295,7 +295,7 @@ CURLcode Curl_headers_push(struct Curl_easy *data, const char *header, if(!end) return CURLE_BAD_FUNCTION_ARGUMENT; } - hlen = end - header + 1; + hlen = end - header; if((header[0] == ' ') || (header[0] == '\t')) { if(data->state.prevhead) diff --git a/tests/data/test1940 b/tests/data/test1940 index 7f621b428df..f4c6dd1a1a6 100644 --- a/tests/data/test1940 +++ b/tests/data/test1940 @@ -19,6 +19,8 @@ Content-Length: 0 Set-Cookie: onecookie=data; Set-Cookie: secondcookie=2data; Set-Cookie: cookie3=data3; +Blank: +Blank2: Location: /%TESTNUMBER0002 @@ -57,6 +59,8 @@ http://%HOSTIP:%HTTPPORT/%TESTNUMBER - Set-Cookie == secondcookie=2data; (1/3) - Set-Cookie == cookie3=data3; (2/3) Fold == is folding a line + Blank == + Blank2 == diff --git a/tests/data/test421 b/tests/data/test421 index 0e4130b0645..2c79c1f8f16 100644 --- a/tests/data/test421 +++ b/tests/data/test421 @@ -71,7 +71,7 @@ Accept: */* "access-control-allow-methods":["GET, POST, PUT, DELETE, OPTIONS"], "access-control-max-age":["1728000"], "access-control-allow-headers":["Authorization, Content-Type, AuthorizationOauth, X-EARLY-ACCESS"], -"access-control-expose-headers":["\r"], +"access-control-expose-headers":[""], "etag":["W/\"2678f9ab2ba550d164e7cc014aefd31e\""], "cache-control":["max-age=0, private, must-revalidate"], "x-request-id":["375b343b3d2ecf9b442c0daf00fc4a9a"], diff --git a/tests/libtest/lib1940.c b/tests/libtest/lib1940.c index 8bc09436216..05da9de3009 100644 --- a/tests/libtest/lib1940.c +++ b/tests/libtest/lib1940.c @@ -35,6 +35,8 @@ static const char *show[]={ "set-cookie", "silly-thing", "fold", + "blank", + "Blank2", NULL }; From 24ae4a07f3496ddb1506a79e34b969cc2e026091 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Jan 2024 09:46:19 +0100 Subject: [PATCH 157/509] hsts: remove assert for zero length domain A zero length domain can happen if the HSTS parser is given invalid input data which is not unheard of and is done by the fuzzer. Follow-up from cfe7902111ae547873 Bug: https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65661 Closes #12676 --- lib/hsts.c | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/lib/hsts.c b/lib/hsts.c index 5677e4f3d12..8725a35c168 100644 --- a/lib/hsts.c +++ b/lib/hsts.c @@ -117,8 +117,6 @@ static CURLcode hsts_create(struct hsts *h, bool subdomains, curl_off_t expires) { - struct stsentry *sts; - char *duphost; size_t hlen; DEBUGASSERT(h); DEBUGASSERT(hostname); @@ -127,25 +125,23 @@ static CURLcode hsts_create(struct hsts *h, if(hlen && (hostname[hlen - 1] == '.')) /* strip off any trailing dot */ --hlen; - DEBUGASSERT(hlen); - if(!hlen) - /* no host name left */ - return CURLE_BAD_FUNCTION_ARGUMENT; - - sts = hsts_entry(); - if(!sts) - return CURLE_OUT_OF_MEMORY; + if(hlen) { + char *duphost; + struct stsentry *sts = hsts_entry(); + if(!sts) + return CURLE_OUT_OF_MEMORY; + + duphost = Curl_memdup0(hostname, hlen); + if(!duphost) { + free(sts); + return CURLE_OUT_OF_MEMORY; + } - duphost = Curl_memdup0(hostname, hlen); - if(!duphost) { - free(sts); - return CURLE_OUT_OF_MEMORY; + sts->host = duphost; + sts->expires = expires; + sts->includeSubDomains = subdomains; + Curl_llist_insert_next(&h->list, h->list.tail, sts, &sts->node); } - - sts->host = duphost; - sts->expires = expires; - sts->includeSubDomains = subdomains; - Curl_llist_insert_next(&h->list, h->list.tail, sts, &sts->node); return CURLE_OK; } From dd0f680fc0c891e44ea621262163ce11769724e7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Jan 2024 15:13:13 +0100 Subject: [PATCH 158/509] sectransp: do verify_cert without memdup for blobs Since the information is then already stored in memory, this can avoid an extra set of malloc + free calls. Closes #12679 --- lib/vtls/sectransp.c | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/lib/vtls/sectransp.c b/lib/vtls/sectransp.c index 075de0c88b8..1f37305ce8a 100644 --- a/lib/vtls/sectransp.c +++ b/lib/vtls/sectransp.c @@ -2370,13 +2370,12 @@ static CURLcode verify_cert(struct Curl_cfilter *cf, CURLcode result; unsigned char *certbuf; size_t buflen; + bool free_certbuf = FALSE; if(ca_info_blob) { CURL_TRC_CF(data, cf, "verify_peer, CA from config blob"); - certbuf = (unsigned char *)Curl_memdup0(ca_info_blob->data, - buflen = ca_info_blob->len); - if(!certbuf) - return CURLE_OUT_OF_MEMORY; + certbuf = ca_info_blob->data; + buflen = ca_info_blob->len; } else if(cafile) { CURL_TRC_CF(data, cf, "verify_peer, CA from file '%s'", cafile); @@ -2384,12 +2383,14 @@ static CURLcode verify_cert(struct Curl_cfilter *cf, failf(data, "SSL: failed to read or invalid CA certificate"); return CURLE_SSL_CACERT_BADFILE; } + free_certbuf = TRUE; } else return CURLE_SSL_CACERT_BADFILE; result = verify_cert_buf(cf, data, certbuf, buflen, ctx); - free(certbuf); + if(free_certbuf) + free(certbuf); return result; } From 693cd1679361828adb281ece01508cfdaec64e12 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Jan 2024 23:20:09 +0100 Subject: [PATCH 159/509] http_proxy: a blank CURLOPT_USERAGENT should not be used in CONNECT Extended test 80 to verify this. Reported-by: Stefan Eissing Fixes #12680 Closes #12681 --- lib/http_proxy.c | 4 ++-- tests/data/test80 | 4 +--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/lib/http_proxy.c b/lib/http_proxy.c index 8e1832581d5..113c43a4135 100644 --- a/lib/http_proxy.c +++ b/lib/http_proxy.c @@ -131,8 +131,8 @@ CURLcode Curl_http_proxy_create_CONNECT(struct httpreq **preq, goto out; } - if(!Curl_checkProxyheaders(data, cf->conn, STRCONST("User-Agent")) - && data->set.str[STRING_USERAGENT]) { + if(!Curl_checkProxyheaders(data, cf->conn, STRCONST("User-Agent")) && + data->set.str[STRING_USERAGENT] && *data->set.str[STRING_USERAGENT]) { result = Curl_dynhds_cadd(&req->headers, "User-Agent", data->set.str[STRING_USERAGENT]); if(result) diff --git a/tests/data/test80 b/tests/data/test80 index 21d9fd2ea5f..c6aa05b173d 100644 --- a/tests/data/test80 +++ b/tests/data/test80 @@ -53,7 +53,7 @@ http-proxy HTTP 1.0 CONNECT with proxytunnel and proxy+host Basic authentication -http://test.%TESTNUMBER:%HTTPPORT/we/want/that/page/%TESTNUMBER -p --proxy1.0 %HOSTIP:%PROXYPORT --user iam:myself --proxy-user youare:yourself +http://test.%TESTNUMBER:%HTTPPORT/we/want/that/page/%TESTNUMBER -p --proxy1.0 %HOSTIP:%PROXYPORT --user iam:myself --proxy-user youare:yourself -A "" proxy @@ -67,7 +67,6 @@ proxy CONNECT test.%TESTNUMBER:%HTTPPORT HTTP/1.0 Host: test.%TESTNUMBER:%HTTPPORT Proxy-Authorization: Basic eW91YXJlOnlvdXJzZWxm -User-Agent: curl/%VERSION Proxy-Connection: Keep-Alive @@ -75,7 +74,6 @@ Proxy-Connection: Keep-Alive GET /we/want/that/page/%TESTNUMBER HTTP/1.1 Host: test.%TESTNUMBER:%HTTPPORT Authorization: Basic aWFtOm15c2VsZg== -User-Agent: curl/%VERSION Accept: */* From 98543fc2cffd229340e9c50b12ef670d2383e438 Mon Sep 17 00:00:00 2001 From: Sergey Markelov Date: Wed, 10 Jan 2024 17:23:00 -0700 Subject: [PATCH 160/509] multi: remove total timer reset in file_do() while fetching file:// The total timer is properly reset in MSTATE_INIT. MSTATE_CONNECT starts with resetting the timer that is a start point for further multi states. If file://, MSTATE_DO calls file_do() that should not reset the total timer. Otherwise, the total time is always less than the pre-transfer and the start transfer times. Closes #12682 --- lib/file.c | 2 -- 1 file changed, 2 deletions(-) diff --git a/lib/file.c b/lib/file.c index c985071376b..1a9ef213753 100644 --- a/lib/file.c +++ b/lib/file.c @@ -419,8 +419,6 @@ static CURLcode file_do(struct Curl_easy *data, bool *done) *done = TRUE; /* unconditionally */ - Curl_pgrsStartNow(data); - if(data->state.upload) return file_upload(data); From 5d044ad9480a9f556f4b6a252d7533b1ba7fe57e Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 9 Jan 2024 13:21:02 +0100 Subject: [PATCH 161/509] vquic: extract TLS setup into own source - separate ngtcp2 specific parts out - provide callback during init to allow ngtcp2 to apply its defaults Closes #12678 --- lib/Makefile.inc | 6 +- lib/cf-socket.c | 42 +-- lib/vquic/curl_ngtcp2.c | 551 +++----------------------------- lib/vquic/curl_quiche.c | 237 +++----------- lib/vquic/vquic-tls.c | 603 ++++++++++++++++++++++++++++++++++++ lib/vquic/vquic-tls.h | 98 ++++++ lib/vquic/vquic.c | 7 +- lib/vquic/vquic_int.h | 4 +- tests/http/test_01_basic.py | 15 + 9 files changed, 839 insertions(+), 724 deletions(-) create mode 100644 lib/vquic/vquic-tls.c create mode 100644 lib/vquic/vquic-tls.h diff --git a/lib/Makefile.inc b/lib/Makefile.inc index e568ef95353..d937e1ed0c1 100644 --- a/lib/Makefile.inc +++ b/lib/Makefile.inc @@ -79,14 +79,16 @@ LIB_VQUIC_CFILES = \ vquic/curl_msh3.c \ vquic/curl_ngtcp2.c \ vquic/curl_quiche.c \ - vquic/vquic.c + vquic/vquic.c \ + vquic/vquic-tls.c LIB_VQUIC_HFILES = \ vquic/curl_msh3.h \ vquic/curl_ngtcp2.h \ vquic/curl_quiche.h \ vquic/vquic.h \ - vquic/vquic_int.h + vquic/vquic_int.h \ + vquic/vquic-tls.h LIB_VSSH_CFILES = \ vssh/libssh.c \ diff --git a/lib/cf-socket.c b/lib/cf-socket.c index 2e985a77f30..cfb98386d99 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -788,6 +788,7 @@ struct cf_socket_ctx { #endif BIT(got_first_byte); /* if first byte was received */ BIT(accepted); /* socket was accepted, not connected */ + BIT(sock_connected); /* socket is "connected", e.g. in UDP */ BIT(active); BIT(buffer_recv); }; @@ -1053,7 +1054,7 @@ static CURLcode cf_socket_open(struct Curl_cfilter *cf, /* set socket non-blocking */ (void)curlx_nonblock(ctx->sock, TRUE); - + ctx->sock_connected = (ctx->addr.socktype != SOCK_DGRAM); out: if(result) { if(ctx->sock != CURL_SOCKET_BAD) { @@ -1241,11 +1242,14 @@ static void cf_socket_adjust_pollset(struct Curl_cfilter *cf, struct cf_socket_ctx *ctx = cf->ctx; if(ctx->sock != CURL_SOCKET_BAD) { - if(!cf->connected) + if(!cf->connected) { Curl_pollset_set_out_only(data, ps, ctx->sock); - else if(!ctx->active) + CURL_TRC_CF(data, cf, "adjust_pollset(!connected) -> %d socks", ps->num); + } + else if(!ctx->active) { Curl_pollset_add_in(data, ps, ctx->sock); - CURL_TRC_CF(data, cf, "adjust_pollset -> %d socks", ps->num); + CURL_TRC_CF(data, cf, "adjust_pollset(!active) -> %d socks", ps->num); + } } } @@ -1428,36 +1432,11 @@ static ssize_t cf_socket_recv(struct Curl_cfilter *cf, struct Curl_easy *data, static void conn_set_primary_ip(struct Curl_cfilter *cf, struct Curl_easy *data) { -#ifdef HAVE_GETPEERNAME struct cf_socket_ctx *ctx = cf->ctx; - if(!(data->conn->handler->protocol & CURLPROTO_TFTP)) { - /* TFTP does not connect the endpoint: getpeername() failed with errno - 107: Transport endpoint is not connected */ - char buffer[STRERROR_LEN]; - struct Curl_sockaddr_storage ssrem; - curl_socklen_t plen; - int port; - - plen = sizeof(ssrem); - memset(&ssrem, 0, plen); - if(getpeername(ctx->sock, (struct sockaddr*) &ssrem, &plen)) { - int error = SOCKERRNO; - failf(data, "getpeername() failed with errno %d: %s", - error, Curl_strerror(error, buffer, sizeof(buffer))); - return; - } - if(!Curl_addr2string((struct sockaddr*)&ssrem, plen, - cf->conn->primary_ip, &port)) { - failf(data, "ssrem inet_ntop() failed with errno %d: %s", - errno, Curl_strerror(errno, buffer, sizeof(buffer))); - return; - } - } -#else - cf->conn->primary_ip[0] = 0; (void)data; -#endif + DEBUGASSERT(sizeof(ctx->r_ip) == sizeof(cf->conn->primary_ip)); + memcpy(cf->conn->primary_ip, ctx->r_ip, sizeof(cf->conn->primary_ip)); } static void cf_socket_active(struct Curl_cfilter *cf, struct Curl_easy *data) @@ -1651,6 +1630,7 @@ static CURLcode cf_udp_setup_quic(struct Curl_cfilter *cf, if(-1 == rc) { return socket_connect_result(data, ctx->r_ip, SOCKERRNO); } + ctx->sock_connected = TRUE; set_local_ip(cf, data); CURL_TRC_CF(data, cf, "%s socket %" CURL_FORMAT_SOCKET_T " connected: [%s:%d] -> [%s:%d]", diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index e391e4f421f..a26b3e429d2 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -41,7 +41,6 @@ #include "vtls/gtls.h" #elif defined(USE_WOLFSSL) #include -#include "vtls/wolfssl.h" #endif #include "urldata.h" @@ -61,6 +60,7 @@ #include "inet_pton.h" #include "vquic.h" #include "vquic_int.h" +#include "vquic-tls.h" #include "vtls/keylog.h" #include "vtls/vtls.h" #include "curl_ngtcp2.h" @@ -73,9 +73,6 @@ #include "memdebug.h" -#define H3_ALPN_H3_29 "\x5h3-29" -#define H3_ALPN_H3 "\x2h3" - #define QUIC_MAX_STREAMS (256*1024) #define QUIC_MAX_DATA (1*1024*1024) #define QUIC_HANDSHAKE_TIMEOUT (10*NGTCP2_SECONDS) @@ -101,25 +98,6 @@ (H3_STREAM_WINDOW_SIZE / H3_STREAM_CHUNK_SIZE) -#ifdef USE_OPENSSL -#define QUIC_CIPHERS \ - "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_" \ - "POLY1305_SHA256:TLS_AES_128_CCM_SHA256" -#define QUIC_GROUPS "P-256:X25519:P-384:P-521" -#elif defined(USE_GNUTLS) -#define QUIC_PRIORITY \ - "NORMAL:-VERS-ALL:+VERS-TLS1.3:-CIPHER-ALL:+AES-128-GCM:+AES-256-GCM:" \ - "+CHACHA20-POLY1305:+AES-128-CCM:-GROUP-ALL:+GROUP-SECP256R1:" \ - "+GROUP-X25519:+GROUP-SECP384R1:+GROUP-SECP521R1:" \ - "%DISABLE_TLS13_COMPAT_MODE" -#elif defined(USE_WOLFSSL) -#define QUIC_CIPHERS \ - "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_" \ - "POLY1305_SHA256:TLS_AES_128_CCM_SHA256" -#define QUIC_GROUPS "P-256:P-384:P-521" -#endif - - /* * Store ngtcp2 version info in this buffer. */ @@ -134,6 +112,7 @@ void Curl_ngtcp2_ver(char *p, size_t len) struct cf_ngtcp2_ctx { struct cf_quic_ctx q; struct ssl_peer peer; + struct quic_tls_ctx tls; ngtcp2_path connected_path; ngtcp2_conn *qconn; ngtcp2_cid dcid; @@ -143,30 +122,16 @@ struct cf_ngtcp2_ctx { ngtcp2_transport_params transport_params; ngtcp2_ccerr last_error; ngtcp2_crypto_conn_ref conn_ref; -#ifdef USE_OPENSSL - SSL_CTX *sslctx; - SSL *ssl; -#elif defined(USE_GNUTLS) - struct gtls_instance *gtls; -#elif defined(USE_WOLFSSL) - WOLFSSL_CTX *sslctx; - WOLFSSL *ssl; -#endif struct cf_call_data call_data; nghttp3_conn *h3conn; nghttp3_settings h3settings; struct curltime started_at; /* time the current attempt started */ struct curltime handshake_at; /* time connect handshake finished */ - struct curltime first_byte_at; /* when first byte was recvd */ struct curltime reconnect_at; /* time the next attempt should start */ struct bufc_pool stream_bufcp; /* chunk pool for streams */ size_t max_stream_window; /* max flow window for one stream */ uint64_t max_idle_ms; /* max idle time for QUIC connection */ int qlogfd; - BIT(got_first_byte); /* if first byte was received */ -#ifdef USE_OPENSSL - BIT(x509_store_setup); /* if x509 store has been set up */ -#endif }; /* How to access `call_data` from a cf_ngtcp2 filter */ @@ -413,388 +378,8 @@ static void quic_settings(struct cf_ngtcp2_ctx *ctx, } } -#ifdef USE_OPENSSL -static void keylog_callback(const SSL *ssl, const char *line) -{ - (void)ssl; - Curl_tls_keylog_write_line(line); -} -#elif defined(USE_GNUTLS) -static int keylog_callback(gnutls_session_t session, const char *label, - const gnutls_datum_t *secret) -{ - gnutls_datum_t crandom; - gnutls_datum_t srandom; - - gnutls_session_get_random(session, &crandom, &srandom); - if(crandom.size != 32) { - return -1; - } - - Curl_tls_keylog_write(label, crandom.data, secret->data, secret->size); - return 0; -} -#elif defined(USE_WOLFSSL) -#if defined(HAVE_SECRET_CALLBACK) -static void keylog_callback(const WOLFSSL *ssl, const char *line) -{ - (void)ssl; - Curl_tls_keylog_write_line(line); -} -#endif -#endif - static int init_ngh3_conn(struct Curl_cfilter *cf); -#ifdef USE_OPENSSL -static CURLcode quic_ssl_ctx(SSL_CTX **pssl_ctx, - struct Curl_cfilter *cf, struct Curl_easy *data) -{ - struct cf_ngtcp2_ctx *ctx = cf->ctx; - struct ssl_primary_config *conn_config; - CURLcode result = CURLE_FAILED_INIT; - - SSL_CTX *ssl_ctx = SSL_CTX_new(TLS_method()); - if(!ssl_ctx) { - result = CURLE_OUT_OF_MEMORY; - goto out; - } - conn_config = Curl_ssl_cf_get_primary_config(cf); - if(!conn_config) { - result = CURLE_FAILED_INIT; - goto out; - } - -#if defined(OPENSSL_IS_BORINGSSL) || defined(OPENSSL_IS_AWSLC) - if(ngtcp2_crypto_boringssl_configure_client_context(ssl_ctx) != 0) { - failf(data, "ngtcp2_crypto_boringssl_configure_client_context failed"); - goto out; - } -#else - if(ngtcp2_crypto_quictls_configure_client_context(ssl_ctx) != 0) { - failf(data, "ngtcp2_crypto_quictls_configure_client_context failed"); - goto out; - } -#endif - - SSL_CTX_set_default_verify_paths(ssl_ctx); - - { - const char *curves = conn_config->curves ? - conn_config->curves : QUIC_GROUPS; - if(!SSL_CTX_set1_curves_list(ssl_ctx, curves)) { - failf(data, "failed setting curves list for QUIC: '%s'", curves); - return CURLE_SSL_CIPHER; - } - } - -#ifndef OPENSSL_IS_BORINGSSL - { - const char *ciphers13 = conn_config->cipher_list13 ? - conn_config->cipher_list13 : QUIC_CIPHERS; - if(SSL_CTX_set_ciphersuites(ssl_ctx, ciphers13) != 1) { - failf(data, "failed setting QUIC cipher suite: %s", ciphers13); - return CURLE_SSL_CIPHER; - } - infof(data, "QUIC cipher selection: %s", ciphers13); - } -#endif - - /* Open the file if a TLS or QUIC backend has not done this before. */ - Curl_tls_keylog_open(); - if(Curl_tls_keylog_enabled()) { - SSL_CTX_set_keylog_callback(ssl_ctx, keylog_callback); - } - - /* OpenSSL always tries to verify the peer, this only says whether it should - * fail to connect if the verification fails, or if it should continue - * anyway. In the latter case the result of the verification is checked with - * SSL_get_verify_result() below. */ - SSL_CTX_set_verify(ssl_ctx, conn_config->verifypeer ? - SSL_VERIFY_PEER : SSL_VERIFY_NONE, NULL); - - /* give application a chance to interfere with SSL set up. */ - if(data->set.ssl.fsslctx) { - /* When a user callback is installed to modify the SSL_CTX, - * we need to do the full initialization before calling it. - * See: #11800 */ - if(!ctx->x509_store_setup) { - result = Curl_ssl_setup_x509_store(cf, data, ssl_ctx); - if(result) - goto out; - ctx->x509_store_setup = TRUE; - } - Curl_set_in_callback(data, true); - result = (*data->set.ssl.fsslctx)(data, ssl_ctx, - data->set.ssl.fsslctxp); - Curl_set_in_callback(data, false); - if(result) { - failf(data, "error signaled by ssl ctx callback"); - goto out; - } - } - result = CURLE_OK; - -out: - *pssl_ctx = result? NULL : ssl_ctx; - if(result && ssl_ctx) - SSL_CTX_free(ssl_ctx); - return result; -} - -static CURLcode quic_set_client_cert(struct Curl_cfilter *cf, - struct Curl_easy *data) -{ - struct cf_ngtcp2_ctx *ctx = cf->ctx; - SSL_CTX *ssl_ctx = ctx->sslctx; - const struct ssl_config_data *ssl_config; - - ssl_config = Curl_ssl_cf_get_config(cf, data); - DEBUGASSERT(ssl_config); - - if(ssl_config->primary.clientcert || ssl_config->primary.cert_blob - || ssl_config->cert_type) { - return Curl_ossl_set_client_cert( - data, ssl_ctx, ssl_config->primary.clientcert, - ssl_config->primary.cert_blob, ssl_config->cert_type, - ssl_config->key, ssl_config->key_blob, - ssl_config->key_type, ssl_config->key_passwd); - } - - return CURLE_OK; -} - -/** SSL callbacks ***/ - -static CURLcode quic_init_ssl(struct Curl_cfilter *cf, - struct Curl_easy *data) -{ - struct cf_ngtcp2_ctx *ctx = cf->ctx; - const uint8_t *alpn = NULL; - size_t alpnlen = 0; - - DEBUGASSERT(!ctx->ssl); - ctx->ssl = SSL_new(ctx->sslctx); - - SSL_set_app_data(ctx->ssl, &ctx->conn_ref); - SSL_set_connect_state(ctx->ssl); - SSL_set_quic_use_legacy_codepoint(ctx->ssl, 0); - - alpn = (const uint8_t *)H3_ALPN_H3 H3_ALPN_H3_29; - alpnlen = sizeof(H3_ALPN_H3) - 1 + sizeof(H3_ALPN_H3_29) - 1; - if(alpn) - SSL_set_alpn_protos(ctx->ssl, alpn, (int)alpnlen); - - /* set SNI */ - if(ctx->peer.sni) { - if(!SSL_set_tlsext_host_name(ctx->ssl, ctx->peer.sni)) { - failf(data, "Failed set SNI"); - SSL_free(ctx->ssl); - ctx->ssl = NULL; - return CURLE_QUIC_CONNECT_ERROR; - } - } - return CURLE_OK; -} -#elif defined(USE_GNUTLS) -static CURLcode quic_init_ssl(struct Curl_cfilter *cf, - struct Curl_easy *data) -{ - struct cf_ngtcp2_ctx *ctx = cf->ctx; - struct ssl_primary_config *conn_config; - CURLcode result; - gnutls_datum_t alpn[2]; - /* this will need some attention when HTTPS proxy over QUIC get fixed */ - long * const pverifyresult = &data->set.ssl.certverifyresult; - int rc; - - conn_config = Curl_ssl_cf_get_primary_config(cf); - if(!conn_config) - return CURLE_FAILED_INIT; - - DEBUGASSERT(ctx->gtls == NULL); - ctx->gtls = calloc(1, sizeof(*(ctx->gtls))); - if(!ctx->gtls) - return CURLE_OUT_OF_MEMORY; - - result = gtls_client_init(data, conn_config, &data->set.ssl, - &ctx->peer, ctx->gtls, pverifyresult); - if(result) - return result; - - gnutls_session_set_ptr(ctx->gtls->session, &ctx->conn_ref); - - if(ngtcp2_crypto_gnutls_configure_client_session(ctx->gtls->session) != 0) { - CURL_TRC_CF(data, cf, - "ngtcp2_crypto_gnutls_configure_client_session failed\n"); - return CURLE_QUIC_CONNECT_ERROR; - } - - rc = gnutls_priority_set_direct(ctx->gtls->session, QUIC_PRIORITY, NULL); - if(rc < 0) { - CURL_TRC_CF(data, cf, "gnutls_priority_set_direct failed: %s\n", - gnutls_strerror(rc)); - return CURLE_QUIC_CONNECT_ERROR; - } - - /* Open the file if a TLS or QUIC backend has not done this before. */ - Curl_tls_keylog_open(); - if(Curl_tls_keylog_enabled()) { - gnutls_session_set_keylog_function(ctx->gtls->session, keylog_callback); - } - - /* strip the first byte (the length) from NGHTTP3_ALPN_H3 */ - alpn[0].data = (unsigned char *)H3_ALPN_H3 + 1; - alpn[0].size = sizeof(H3_ALPN_H3) - 2; - alpn[1].data = (unsigned char *)H3_ALPN_H3_29 + 1; - alpn[1].size = sizeof(H3_ALPN_H3_29) - 2; - - gnutls_alpn_set_protocols(ctx->gtls->session, - alpn, 2, GNUTLS_ALPN_MANDATORY); - return CURLE_OK; -} -#elif defined(USE_WOLFSSL) - -static CURLcode quic_ssl_ctx(WOLFSSL_CTX **pssl_ctx, - struct Curl_cfilter *cf, struct Curl_easy *data) -{ - CURLcode result = CURLE_FAILED_INIT; - struct ssl_primary_config *conn_config; - WOLFSSL_CTX *ssl_ctx = NULL; - - conn_config = Curl_ssl_cf_get_primary_config(cf); - if(!conn_config) { - result = CURLE_FAILED_INIT; - goto out; - } - - ssl_ctx = wolfSSL_CTX_new(wolfTLSv1_3_client_method()); - if(!ssl_ctx) { - result = CURLE_OUT_OF_MEMORY; - goto out; - } - - if(ngtcp2_crypto_wolfssl_configure_client_context(ssl_ctx) != 0) { - failf(data, "ngtcp2_crypto_wolfssl_configure_client_context failed"); - result = CURLE_FAILED_INIT; - goto out; - } - - wolfSSL_CTX_set_default_verify_paths(ssl_ctx); - - if(wolfSSL_CTX_set_cipher_list(ssl_ctx, conn_config->cipher_list13 ? - conn_config->cipher_list13 : - QUIC_CIPHERS) != 1) { - char error_buffer[256]; - ERR_error_string_n(ERR_get_error(), error_buffer, sizeof(error_buffer)); - failf(data, "wolfSSL failed to set ciphers: %s", error_buffer); - goto out; - } - - if(wolfSSL_CTX_set1_groups_list(ssl_ctx, conn_config->curves ? - conn_config->curves : - (char *)QUIC_GROUPS) != 1) { - failf(data, "wolfSSL failed to set curves"); - goto out; - } - - /* Open the file if a TLS or QUIC backend has not done this before. */ - Curl_tls_keylog_open(); - if(Curl_tls_keylog_enabled()) { -#if defined(HAVE_SECRET_CALLBACK) - wolfSSL_CTX_set_keylog_callback(ssl_ctx, keylog_callback); -#else - failf(data, "wolfSSL was built without keylog callback"); - goto out; -#endif - } - - if(conn_config->verifypeer) { - const char * const ssl_cafile = conn_config->CAfile; - const char * const ssl_capath = conn_config->CApath; - - wolfSSL_CTX_set_verify(ssl_ctx, SSL_VERIFY_PEER, NULL); - if(ssl_cafile || ssl_capath) { - /* tell wolfSSL where to find CA certificates that are used to verify - the server's certificate. */ - int rc = - wolfSSL_CTX_load_verify_locations_ex(ssl_ctx, ssl_cafile, ssl_capath, - WOLFSSL_LOAD_FLAG_IGNORE_ERR); - if(SSL_SUCCESS != rc) { - /* Fail if we insist on successfully verifying the server. */ - failf(data, "error setting certificate verify locations:" - " CAfile: %s CApath: %s", - ssl_cafile ? ssl_cafile : "none", - ssl_capath ? ssl_capath : "none"); - goto out; - } - infof(data, " CAfile: %s", ssl_cafile ? ssl_cafile : "none"); - infof(data, " CApath: %s", ssl_capath ? ssl_capath : "none"); - } -#ifdef CURL_CA_FALLBACK - else { - /* verifying the peer without any CA certificates won't work so - use wolfssl's built-in default as fallback */ - wolfSSL_CTX_set_default_verify_paths(ssl_ctx); - } -#endif - } - else { - wolfSSL_CTX_set_verify(ssl_ctx, SSL_VERIFY_NONE, NULL); - } - - /* give application a chance to interfere with SSL set up. */ - if(data->set.ssl.fsslctx) { - Curl_set_in_callback(data, true); - result = (*data->set.ssl.fsslctx)(data, ssl_ctx, - data->set.ssl.fsslctxp); - Curl_set_in_callback(data, false); - if(result) { - failf(data, "error signaled by ssl ctx callback"); - goto out; - } - } - result = CURLE_OK; - -out: - *pssl_ctx = result? NULL : ssl_ctx; - if(result && ssl_ctx) - SSL_CTX_free(ssl_ctx); - return result; -} - -/** SSL callbacks ***/ - -static CURLcode quic_init_ssl(struct Curl_cfilter *cf, - struct Curl_easy *data) -{ - struct cf_ngtcp2_ctx *ctx = cf->ctx; - const uint8_t *alpn = NULL; - size_t alpnlen = 0; - /* this will need some attention when HTTPS proxy over QUIC get fixed */ - const char * const hostname = cf->conn->host.name; - - (void)data; - DEBUGASSERT(!ctx->ssl); - ctx->ssl = wolfSSL_new(ctx->sslctx); - - wolfSSL_set_app_data(ctx->ssl, &ctx->conn_ref); - wolfSSL_set_connect_state(ctx->ssl); - wolfSSL_set_quic_use_legacy_codepoint(ctx->ssl, 0); - - alpn = (const uint8_t *)H3_ALPN_H3 H3_ALPN_H3_29; - alpnlen = sizeof(H3_ALPN_H3) - 1 + sizeof(H3_ALPN_H3_29) - 1; - if(alpn) - wolfSSL_set_alpn_protos(ctx->ssl, alpn, (int)alpnlen); - - /* set SNI */ - wolfSSL_UseSNI(ctx->ssl, WOLFSSL_SNI_HOST_NAME, - hostname, (unsigned short)strlen(hostname)); - - return CURLE_OK; -} -#endif /* defined(USE_WOLFSSL) */ - static int cb_handshake_completed(ngtcp2_conn *tconn, void *user_data) { (void)user_data; @@ -1950,49 +1535,12 @@ static CURLcode qng_verify_peer(struct Curl_cfilter *cf, struct Curl_easy *data) { struct cf_ngtcp2_ctx *ctx = cf->ctx; - struct ssl_primary_config *conn_config; - CURLcode result = CURLE_OK; - - conn_config = Curl_ssl_cf_get_primary_config(cf); - if(!conn_config) - return CURLE_FAILED_INIT; cf->conn->bits.multiplex = TRUE; /* at least potentially multiplexed */ cf->conn->httpversion = 30; cf->conn->bundle->multiuse = BUNDLE_MULTIPLEX; - if(conn_config->verifyhost) { -#ifdef USE_OPENSSL - X509 *server_cert; - server_cert = SSL_get1_peer_certificate(ctx->ssl); - if(!server_cert) { - return CURLE_PEER_FAILED_VERIFICATION; - } - result = Curl_ossl_verifyhost(data, cf->conn, &ctx->peer, server_cert); - X509_free(server_cert); - if(result) - return result; -#elif defined(USE_GNUTLS) - result = Curl_gtls_verifyserver(data, ctx->gtls->session, - conn_config, &data->set.ssl, &ctx->peer, - data->set.str[STRING_SSL_PINNEDPUBLICKEY]); - if(result) - return result; -#elif defined(USE_WOLFSSL) - if(!ctx->peer.sni || - wolfSSL_check_domain_name(ctx->ssl, ctx->peer.sni) == SSL_FAILURE) - return CURLE_PEER_FAILED_VERIFICATION; -#endif - infof(data, "Verified certificate just fine"); - } - else - infof(data, "Skipped certificate verification"); -#ifdef USE_OPENSSL - if(data->set.ssl.certinfo) - /* asked to gather certificate info */ - (void)Curl_ossl_certchain(data, ctx->ssl); -#endif - return result; + return Curl_vquic_tls_verify_peer(&ctx->tls, cf, data, &ctx->peer); } static CURLcode recv_pkt(const unsigned char *pkt, size_t pktlen, @@ -2056,14 +1604,9 @@ static CURLcode cf_progress_ingress(struct Curl_cfilter *cf, pktx_update_time(pktx, cf); } -#ifdef USE_OPENSSL - if(!ctx->x509_store_setup) { - result = Curl_ssl_setup_x509_store(cf, data, ctx->sslctx); - if(result) - return result; - ctx->x509_store_setup = TRUE; - } -#endif + result = Curl_vquic_tls_before_recv(&ctx->tls, cf, data); + if(result) + return result; for(i = 0; i < pkts_max; i += pkts_chunk) { pktx->pkt_count = 0; @@ -2388,25 +1931,7 @@ static void cf_ngtcp2_ctx_clear(struct cf_ngtcp2_ctx *ctx) if(ctx->qlogfd != -1) { close(ctx->qlogfd); } -#ifdef USE_OPENSSL - if(ctx->ssl) - SSL_free(ctx->ssl); - if(ctx->sslctx) - SSL_CTX_free(ctx->sslctx); -#elif defined(USE_GNUTLS) - if(ctx->gtls) { - if(ctx->gtls->cred) - gnutls_certificate_free_credentials(ctx->gtls->cred); - if(ctx->gtls->session) - gnutls_deinit(ctx->gtls->session); - free(ctx->gtls); - } -#elif defined(USE_WOLFSSL) - if(ctx->ssl) - wolfSSL_free(ctx->ssl); - if(ctx->sslctx) - wolfSSL_CTX_free(ctx->sslctx); -#endif + Curl_vquic_tls_cleanup(&ctx->tls); vquic_ctx_free(&ctx->q); if(ctx->h3conn) nghttp3_conn_del(ctx->h3conn); @@ -2465,6 +1990,37 @@ static void cf_ngtcp2_destroy(struct Curl_cfilter *cf, struct Curl_easy *data) (void)save; } +static CURLcode tls_ctx_setup(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + (void)cf; +#ifdef USE_OPENSSL +#if defined(OPENSSL_IS_BORINGSSL) || defined(OPENSSL_IS_AWSLC) + if(ngtcp2_crypto_boringssl_configure_client_context(ctx->ssl_ctx) != 0) { + failf(data, "ngtcp2_crypto_boringssl_configure_client_context failed"); + return CURLE_FAILED_INIT; + } +#else + if(ngtcp2_crypto_quictls_configure_client_context(ctx->ssl_ctx) != 0) { + failf(data, "ngtcp2_crypto_quictls_configure_client_context failed"); + return CURLE_FAILED_INIT; + } +#endif /* !OPENSSL_IS_BORINGSSL && !OPENSSL_IS_AWSLC */ +#elif defined(USE_GNUTLS) + if(ngtcp2_crypto_gnutls_configure_client_session(ctx->gtls->session) != 0) { + failf(data, "ngtcp2_crypto_gnutls_configure_client_session failed"); + return CURLE_FAILED_INIT; + } +#elif defined(USE_WOLFSSL) + if(ngtcp2_crypto_wolfssl_configure_client_context(ctx->ssl_ctx) != 0) { + failf(data, "ngtcp2_crypto_wolfssl_configure_client_context failed"); + return CURLE_FAILED_INIT; + } +#endif + return CURLE_OK; +} + /* * Might be called twice for happy eyeballs. */ @@ -2489,21 +2045,10 @@ static CURLcode cf_connect_start(struct Curl_cfilter *cf, if(result) return result; -#ifdef USE_OPENSSL - result = quic_ssl_ctx(&ctx->sslctx, cf, data); - if(result) - return result; - - result = quic_set_client_cert(cf, data); - if(result) - return result; -#elif defined(USE_WOLFSSL) - result = quic_ssl_ctx(&ctx->sslctx, cf, data); - if(result) - return result; -#endif - - result = quic_init_ssl(cf, data); +#define H3_ALPN "\x2h3\x5h3-29" + result = Curl_vquic_tls_init(&ctx->tls, cf, data, &ctx->peer, + H3_ALPN, sizeof(H3_ALPN) - 1, + tls_ctx_setup, &ctx->conn_ref); if(result) return result; @@ -2550,9 +2095,9 @@ static CURLcode cf_connect_start(struct Curl_cfilter *cf, return CURLE_QUIC_CONNECT_ERROR; #ifdef USE_GNUTLS - ngtcp2_conn_set_tls_native_handle(ctx->qconn, ctx->gtls->session); + ngtcp2_conn_set_tls_native_handle(ctx->qconn, ctx->tls.gtls->session); #else - ngtcp2_conn_set_tls_native_handle(ctx->qconn, ctx->ssl); + ngtcp2_conn_set_tls_native_handle(ctx->qconn, ctx->tls.ssl); #endif ngtcp2_ccerr_default(&ctx->last_error); @@ -2683,8 +2228,8 @@ static CURLcode cf_ngtcp2_query(struct Curl_cfilter *cf, return CURLE_OK; } case CF_QUERY_CONNECT_REPLY_MS: - if(ctx->got_first_byte) { - timediff_t ms = Curl_timediff(ctx->first_byte_at, ctx->started_at); + if(ctx->q.got_first_byte) { + timediff_t ms = Curl_timediff(ctx->q.first_byte_at, ctx->started_at); *pres1 = (ms < INT_MAX)? (int)ms : INT_MAX; } else @@ -2692,8 +2237,8 @@ static CURLcode cf_ngtcp2_query(struct Curl_cfilter *cf, return CURLE_OK; case CF_QUERY_TIMER_CONNECT: { struct curltime *when = pres2; - if(ctx->got_first_byte) - *when = ctx->first_byte_at; + if(ctx->q.got_first_byte) + *when = ctx->q.first_byte_at; return CURLE_OK; } case CF_QUERY_TIMER_APPCONNECT: { diff --git a/lib/vquic/curl_quiche.c b/lib/vquic/curl_quiche.c index ed0bde36709..fcb0eb8f843 100644 --- a/lib/vquic/curl_quiche.c +++ b/lib/vquic/curl_quiche.c @@ -43,6 +43,7 @@ #include "http1.h" #include "vquic.h" #include "vquic_int.h" +#include "vquic-tls.h" #include "curl_quiche.h" #include "transfer.h" #include "inet_pton.h" @@ -84,31 +85,22 @@ void Curl_quiche_ver(char *p, size_t len) (void)msnprintf(p, len, "quiche/%s", quiche_version()); } -static void keylog_callback(const SSL *ssl, const char *line) -{ - (void)ssl; - Curl_tls_keylog_write_line(line); -} - struct cf_quiche_ctx { struct cf_quic_ctx q; struct ssl_peer peer; + struct quic_tls_ctx tls; quiche_conn *qconn; quiche_config *cfg; quiche_h3_conn *h3c; quiche_h3_config *h3config; uint8_t scid[QUICHE_MAX_CONN_ID_LEN]; - SSL_CTX *sslctx; - SSL *ssl; struct curltime started_at; /* time the current attempt started */ struct curltime handshake_at; /* time connect handshake finished */ - struct curltime first_byte_at; /* when first byte was recvd */ struct curltime reconnect_at; /* time the next attempt should start */ struct bufc_pool stream_bufcp; /* chunk pool for streams */ curl_off_t data_recvd; uint64_t max_idle_ms; /* max idle time for QUIC conn */ BIT(goaway); /* got GOAWAY from server */ - BIT(got_first_byte); /* if first byte was received */ BIT(x509_store_setup); /* if x509 store has been set up */ }; @@ -123,121 +115,25 @@ static void quiche_debug_log(const char *line, void *argp) static void cf_quiche_ctx_clear(struct cf_quiche_ctx *ctx) { if(ctx) { - vquic_ctx_free(&ctx->q); - if(ctx->qconn) - quiche_conn_free(ctx->qconn); - if(ctx->h3config) - quiche_h3_config_free(ctx->h3config); if(ctx->h3c) quiche_h3_conn_free(ctx->h3c); + if(ctx->h3config) + quiche_h3_config_free(ctx->h3config); + if(ctx->qconn) + quiche_conn_free(ctx->qconn); if(ctx->cfg) quiche_config_free(ctx->cfg); - Curl_bufcp_free(&ctx->stream_bufcp); + /* quiche just freed ctx->tls.ssl */ + ctx->tls.ssl = NULL; + Curl_vquic_tls_cleanup(&ctx->tls); Curl_ssl_peer_cleanup(&ctx->peer); + vquic_ctx_free(&ctx->q); + Curl_bufcp_free(&ctx->stream_bufcp); memset(ctx, 0, sizeof(*ctx)); } } -static CURLcode quic_x509_store_setup(struct Curl_cfilter *cf, - struct Curl_easy *data) -{ - struct cf_quiche_ctx *ctx = cf->ctx; - struct ssl_primary_config *conn_config; - - conn_config = Curl_ssl_cf_get_primary_config(cf); - if(!conn_config) - return CURLE_FAILED_INIT; - - if(!ctx->x509_store_setup) { - if(conn_config->verifypeer) { - const char * const ssl_cafile = conn_config->CAfile; - const char * const ssl_capath = conn_config->CApath; - if(ssl_cafile || ssl_capath) { - SSL_CTX_set_verify(ctx->sslctx, SSL_VERIFY_PEER, NULL); - /* tell OpenSSL where to find CA certificates that are used to verify - the server's certificate. */ - if(!SSL_CTX_load_verify_locations(ctx->sslctx, ssl_cafile, - ssl_capath)) { - /* Fail if we insist on successfully verifying the server. */ - failf(data, "error setting certificate verify locations:" - " CAfile: %s CApath: %s", - ssl_cafile ? ssl_cafile : "none", - ssl_capath ? ssl_capath : "none"); - return CURLE_SSL_CACERT_BADFILE; - } - infof(data, " CAfile: %s", ssl_cafile ? ssl_cafile : "none"); - infof(data, " CApath: %s", ssl_capath ? ssl_capath : "none"); - } -#ifdef CURL_CA_FALLBACK - else { - /* verifying the peer without any CA certificates won't work so - use openssl's built-in default as fallback */ - SSL_CTX_set_default_verify_paths(ctx->sslctx); - } -#endif - } - ctx->x509_store_setup = TRUE; - } - return CURLE_OK; -} - -static CURLcode quic_ssl_setup(struct Curl_cfilter *cf, struct Curl_easy *data) -{ - struct cf_quiche_ctx *ctx = cf->ctx; - struct ssl_primary_config *conn_config; - CURLcode result; - - conn_config = Curl_ssl_cf_get_primary_config(cf); - if(!conn_config) - return CURLE_FAILED_INIT; - - result = Curl_ssl_peer_init(&ctx->peer, cf); - if(result) - return result; - - DEBUGASSERT(!ctx->sslctx); - ctx->sslctx = SSL_CTX_new(TLS_method()); - if(!ctx->sslctx) - return CURLE_OUT_OF_MEMORY; - - SSL_CTX_set_alpn_protos(ctx->sslctx, - (const uint8_t *)QUICHE_H3_APPLICATION_PROTOCOL, - sizeof(QUICHE_H3_APPLICATION_PROTOCOL) - 1); - - SSL_CTX_set_default_verify_paths(ctx->sslctx); - - /* Open the file if a TLS or QUIC backend has not done this before. */ - Curl_tls_keylog_open(); - if(Curl_tls_keylog_enabled()) { - SSL_CTX_set_keylog_callback(ctx->sslctx, keylog_callback); - } - - if(conn_config->curves && - !SSL_CTX_set1_curves_list(ctx->sslctx, conn_config->curves)) { - failf(data, "failed setting curves list for QUIC: '%s'", - conn_config->curves); - return CURLE_SSL_CIPHER; - } - - ctx->ssl = SSL_new(ctx->sslctx); - if(!ctx->ssl) - return CURLE_QUIC_CONNECT_ERROR; - - SSL_set_app_data(ctx->ssl, cf); - - if(ctx->peer.sni) { - if(!SSL_set_tlsext_host_name(ctx->ssl, ctx->peer.sni)) { - failf(data, "Failed set SNI"); - SSL_free(ctx->ssl); - ctx->ssl = NULL; - return CURLE_QUIC_CONNECT_ERROR; - } - } - - return CURLE_OK; -} - /** * All about the H3 internals of a stream */ @@ -668,7 +564,7 @@ static CURLcode recv_pkt(const unsigned char *pkt, size_t pktlen, return CURLE_OK; } else if(QUICHE_ERR_TLS_FAIL == nread) { - long verify_ok = SSL_get_verify_result(ctx->ssl); + long verify_ok = SSL_get_verify_result(ctx->tls.ssl); if(verify_ok != X509_V_OK) { failf(r->data, "SSL certificate problem: %s", X509_verify_cert_error_string(verify_ok)); @@ -696,7 +592,7 @@ static CURLcode cf_process_ingress(struct Curl_cfilter *cf, CURLcode result; DEBUGASSERT(ctx->qconn); - result = quic_x509_store_setup(cf, data); + result = Curl_vquic_tls_before_recv(&ctx->tls, cf, data); if(result) return result; @@ -1277,66 +1173,6 @@ static CURLcode cf_quiche_data_event(struct Curl_cfilter *cf, return result; } -static CURLcode cf_verify_peer(struct Curl_cfilter *cf, - struct Curl_easy *data) -{ - struct cf_quiche_ctx *ctx = cf->ctx; - struct ssl_primary_config *conn_config; - CURLcode result = CURLE_OK; - - conn_config = Curl_ssl_cf_get_primary_config(cf); - if(!conn_config) - return CURLE_FAILED_INIT; - - cf->conn->bits.multiplex = TRUE; /* at least potentially multiplexed */ - cf->conn->httpversion = 30; - cf->conn->bundle->multiuse = BUNDLE_MULTIPLEX; - - if(conn_config->verifyhost) { - X509 *server_cert; - server_cert = SSL_get_peer_certificate(ctx->ssl); - if(!server_cert) { - result = CURLE_PEER_FAILED_VERIFICATION; - goto out; - } - result = Curl_ossl_verifyhost(data, cf->conn, &ctx->peer, server_cert); - X509_free(server_cert); - if(result) - goto out; - } - else - CURL_TRC_CF(data, cf, "Skipped certificate verification"); - - ctx->h3config = quiche_h3_config_new(); - if(!ctx->h3config) { - result = CURLE_OUT_OF_MEMORY; - goto out; - } - - /* Create a new HTTP/3 connection on the QUIC connection. */ - ctx->h3c = quiche_h3_conn_new_with_transport(ctx->qconn, ctx->h3config); - if(!ctx->h3c) { - result = CURLE_OUT_OF_MEMORY; - goto out; - } - if(data->set.ssl.certinfo) - /* asked to gather certificate info */ - (void)Curl_ossl_certchain(data, ctx->ssl); - -out: - if(result) { - if(ctx->h3config) { - quiche_h3_config_free(ctx->h3config); - ctx->h3config = NULL; - } - if(ctx->h3c) { - quiche_h3_conn_free(ctx->h3c); - ctx->h3c = NULL; - } - } - return result; -} - static CURLcode cf_connect_start(struct Curl_cfilter *cf, struct Curl_easy *data) { @@ -1364,6 +1200,10 @@ static CURLcode cf_connect_start(struct Curl_cfilter *cf, if(result) return result; + result = Curl_ssl_peer_init(&ctx->peer, cf); + if(result) + return result; + ctx->cfg = quiche_config_new(QUICHE_PROTOCOL_VERSION); if(!ctx->cfg) { failf(data, "can't create quiche config"); @@ -1392,9 +1232,10 @@ static CURLcode cf_connect_start(struct Curl_cfilter *cf, sizeof(QUICHE_H3_APPLICATION_PROTOCOL) - 1); - DEBUGASSERT(!ctx->ssl); - DEBUGASSERT(!ctx->sslctx); - result = quic_ssl_setup(cf, data); + result = Curl_vquic_tls_init(&ctx->tls, cf, data, &ctx->peer, + QUICHE_H3_APPLICATION_PROTOCOL, + sizeof(QUICHE_H3_APPLICATION_PROTOCOL) - 1, + NULL, cf); if(result) return result; @@ -1415,7 +1256,7 @@ static CURLcode cf_connect_start(struct Curl_cfilter *cf, (struct sockaddr *)&ctx->q.local_addr, ctx->q.local_addrlen, &sockaddr->sa_addr, sockaddr->addrlen, - ctx->cfg, ctx->ssl, false); + ctx->cfg, ctx->tls.ssl, false); if(!ctx->qconn) { failf(data, "can't create quiche connection"); return CURLE_OUT_OF_MEMORY; @@ -1454,6 +1295,18 @@ static CURLcode cf_connect_start(struct Curl_cfilter *cf, return CURLE_OK; } +static CURLcode cf_quiche_verify_peer(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_quiche_ctx *ctx = cf->ctx; + + cf->conn->bits.multiplex = TRUE; /* at least potentially multiplexed */ + cf->conn->httpversion = 30; + cf->conn->bundle->multiuse = BUNDLE_MULTIPLEX; + + return Curl_vquic_tls_verify_peer(&ctx->tls, cf, data, &ctx->peer); +} + static CURLcode cf_quiche_connect(struct Curl_cfilter *cf, struct Curl_easy *data, bool blocking, bool *done) @@ -1505,9 +1358,21 @@ static CURLcode cf_quiche_connect(struct Curl_cfilter *cf, ctx->handshake_at = ctx->q.last_op; CURL_TRC_CF(data, cf, "handshake complete after %dms", (int)Curl_timediff(ctx->handshake_at, ctx->started_at)); - result = cf_verify_peer(cf, data); + result = cf_quiche_verify_peer(cf, data); if(!result) { CURL_TRC_CF(data, cf, "peer verified"); + ctx->h3config = quiche_h3_config_new(); + if(!ctx->h3config) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } + + /* Create a new HTTP/3 connection on the QUIC connection. */ + ctx->h3c = quiche_h3_conn_new_with_transport(ctx->qconn, ctx->h3config); + if(!ctx->h3c) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } cf->connected = TRUE; cf->conn->alpn = CURL_HTTP_VERSION_3; *done = TRUE; @@ -1580,8 +1445,8 @@ static CURLcode cf_quiche_query(struct Curl_cfilter *cf, return CURLE_OK; } case CF_QUERY_CONNECT_REPLY_MS: - if(ctx->got_first_byte) { - timediff_t ms = Curl_timediff(ctx->first_byte_at, ctx->started_at); + if(ctx->q.got_first_byte) { + timediff_t ms = Curl_timediff(ctx->q.first_byte_at, ctx->started_at); *pres1 = (ms < INT_MAX)? (int)ms : INT_MAX; } else @@ -1589,8 +1454,8 @@ static CURLcode cf_quiche_query(struct Curl_cfilter *cf, return CURLE_OK; case CF_QUERY_TIMER_CONNECT: { struct curltime *when = pres2; - if(ctx->got_first_byte) - *when = ctx->first_byte_at; + if(ctx->q.got_first_byte) + *when = ctx->q.first_byte_at; return CURLE_OK; } case CF_QUERY_TIMER_APPCONNECT: { diff --git a/lib/vquic/vquic-tls.c b/lib/vquic/vquic-tls.c new file mode 100644 index 00000000000..e9f16773b97 --- /dev/null +++ b/lib/vquic/vquic-tls.c @@ -0,0 +1,603 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +#include "curl_setup.h" + +#if defined(ENABLE_QUIC) && \ + (defined(USE_OPENSSL) || defined(USE_GNUTLS) || defined(USE_WOLFSSL)) + +#ifdef USE_OPENSSL +#include +#include "vtls/openssl.h" +#elif defined(USE_GNUTLS) +#include +#include +#include +#include +#include +#include "vtls/gtls.h" +#elif defined(USE_WOLFSSL) +#include +#include +#include +#include "vtls/wolfssl.h" +#endif + +#include "urldata.h" +#include "curl_trc.h" +#include "cfilters.h" +#include "multiif.h" +#include "vtls/keylog.h" +#include "vtls/vtls.h" +#include "vquic-tls.h" + +/* The last 3 #include files should be in this order */ +#include "curl_printf.h" +#include "curl_memory.h" +#include "memdebug.h" + +#ifndef ARRAYSIZE +#define ARRAYSIZE(A) (sizeof(A)/sizeof((A)[0])) +#endif + +#ifdef USE_OPENSSL +#define QUIC_CIPHERS \ + "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_" \ + "POLY1305_SHA256:TLS_AES_128_CCM_SHA256" +#define QUIC_GROUPS "P-256:X25519:P-384:P-521" +#elif defined(USE_GNUTLS) +#define QUIC_PRIORITY \ + "NORMAL:-VERS-ALL:+VERS-TLS1.3:-CIPHER-ALL:+AES-128-GCM:+AES-256-GCM:" \ + "+CHACHA20-POLY1305:+AES-128-CCM:-GROUP-ALL:+GROUP-SECP256R1:" \ + "+GROUP-X25519:+GROUP-SECP384R1:+GROUP-SECP521R1:" \ + "%DISABLE_TLS13_COMPAT_MODE" +#elif defined(USE_WOLFSSL) +#define QUIC_CIPHERS \ + "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_" \ + "POLY1305_SHA256:TLS_AES_128_CCM_SHA256" +#define QUIC_GROUPS "P-256:P-384:P-521" +#endif + + +#ifdef USE_OPENSSL + +static void keylog_callback(const SSL *ssl, const char *line) +{ + (void)ssl; + Curl_tls_keylog_write_line(line); +} + +static CURLcode curl_ossl_init_ctx(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data, + Curl_vquic_tls_ctx_setup *ctx_setup) +{ + struct ssl_primary_config *conn_config; + CURLcode result = CURLE_FAILED_INIT; + + DEBUGASSERT(!ctx->ssl_ctx); + ctx->ssl_ctx = SSL_CTX_new(TLS_method()); + if(!ctx->ssl_ctx) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } + conn_config = Curl_ssl_cf_get_primary_config(cf); + if(!conn_config) { + result = CURLE_FAILED_INIT; + goto out; + } + + if(ctx_setup) { + result = ctx_setup(ctx, cf, data); + if(result) + goto out; + } + + SSL_CTX_set_default_verify_paths(ctx->ssl_ctx); + + { + const char *curves = conn_config->curves ? + conn_config->curves : QUIC_GROUPS; + if(!SSL_CTX_set1_curves_list(ctx->ssl_ctx, curves)) { + failf(data, "failed setting curves list for QUIC: '%s'", curves); + return CURLE_SSL_CIPHER; + } + } + +#ifndef OPENSSL_IS_BORINGSSL + { + const char *ciphers13 = conn_config->cipher_list13 ? + conn_config->cipher_list13 : QUIC_CIPHERS; + if(SSL_CTX_set_ciphersuites(ctx->ssl_ctx, ciphers13) != 1) { + failf(data, "failed setting QUIC cipher suite: %s", ciphers13); + return CURLE_SSL_CIPHER; + } + infof(data, "QUIC cipher selection: %s", ciphers13); + } +#endif + + /* Open the file if a TLS or QUIC backend has not done this before. */ + Curl_tls_keylog_open(); + if(Curl_tls_keylog_enabled()) { + SSL_CTX_set_keylog_callback(ctx->ssl_ctx, keylog_callback); + } + + /* OpenSSL always tries to verify the peer, this only says whether it should + * fail to connect if the verification fails, or if it should continue + * anyway. In the latter case the result of the verification is checked with + * SSL_get_verify_result() below. */ + SSL_CTX_set_verify(ctx->ssl_ctx, conn_config->verifypeer ? + SSL_VERIFY_PEER : SSL_VERIFY_NONE, NULL); + + /* give application a chance to interfere with SSL set up. */ + if(data->set.ssl.fsslctx) { + /* When a user callback is installed to modify the SSL_CTX, + * we need to do the full initialization before calling it. + * See: #11800 */ + if(!ctx->x509_store_setup) { + result = Curl_ssl_setup_x509_store(cf, data, ctx->ssl_ctx); + if(result) + goto out; + ctx->x509_store_setup = TRUE; + } + Curl_set_in_callback(data, true); + result = (*data->set.ssl.fsslctx)(data, ctx->ssl_ctx, + data->set.ssl.fsslctxp); + Curl_set_in_callback(data, false); + if(result) { + failf(data, "error signaled by ssl ctx callback"); + goto out; + } + } + result = CURLE_OK; + +out: + if(result && ctx->ssl_ctx) { + SSL_CTX_free(ctx->ssl_ctx); + ctx->ssl_ctx = NULL; + } + return result; +} + +static CURLcode curl_ossl_set_client_cert(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + SSL_CTX *ssl_ctx = ctx->ssl_ctx; + const struct ssl_config_data *ssl_config; + + ssl_config = Curl_ssl_cf_get_config(cf, data); + DEBUGASSERT(ssl_config); + + if(ssl_config->primary.clientcert || + ssl_config->primary.cert_blob || + ssl_config->cert_type) { + return Curl_ossl_set_client_cert( + data, ssl_ctx, ssl_config->primary.clientcert, + ssl_config->primary.cert_blob, ssl_config->cert_type, + ssl_config->key, ssl_config->key_blob, + ssl_config->key_type, ssl_config->key_passwd); + } + + return CURLE_OK; +} + +/** SSL callbacks ***/ + +static CURLcode curl_ossl_init_ssl(struct quic_tls_ctx *ctx, + struct Curl_easy *data, + struct ssl_peer *peer, + const char *alpn, size_t alpn_len, + void *user_data) +{ + DEBUGASSERT(!ctx->ssl); + ctx->ssl = SSL_new(ctx->ssl_ctx); + + SSL_set_app_data(ctx->ssl, user_data); + SSL_set_connect_state(ctx->ssl); + SSL_set_quic_use_legacy_codepoint(ctx->ssl, 0); + + if(alpn) + SSL_set_alpn_protos(ctx->ssl, (const uint8_t *)alpn, (int)alpn_len); + + if(peer->sni) { + if(!SSL_set_tlsext_host_name(ctx->ssl, peer->sni)) { + failf(data, "Failed set SNI"); + SSL_free(ctx->ssl); + ctx->ssl = NULL; + return CURLE_QUIC_CONNECT_ERROR; + } + } + return CURLE_OK; +} + +#elif defined(USE_GNUTLS) +static int keylog_callback(gnutls_session_t session, const char *label, + const gnutls_datum_t *secret) +{ + gnutls_datum_t crandom; + gnutls_datum_t srandom; + + gnutls_session_get_random(session, &crandom, &srandom); + if(crandom.size != 32) { + return -1; + } + + Curl_tls_keylog_write(label, crandom.data, secret->data, secret->size); + return 0; +} + +static CURLcode curl_gtls_init_ctx(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data, + struct ssl_peer *peer, + const char *alpn, size_t alpn_len, + Curl_vquic_tls_ctx_setup *ctx_setup, + void *user_data) +{ + struct ssl_primary_config *conn_config; + CURLcode result; + gnutls_datum_t alpns[5]; + /* this will need some attention when HTTPS proxy over QUIC get fixed */ + long * const pverifyresult = &data->set.ssl.certverifyresult; + int rc; + + conn_config = Curl_ssl_cf_get_primary_config(cf); + if(!conn_config) + return CURLE_FAILED_INIT; + + DEBUGASSERT(ctx->gtls == NULL); + ctx->gtls = calloc(1, sizeof(*(ctx->gtls))); + if(!ctx->gtls) + return CURLE_OUT_OF_MEMORY; + + result = gtls_client_init(data, conn_config, &data->set.ssl, + peer, ctx->gtls, pverifyresult); + if(result) + return result; + + gnutls_session_set_ptr(ctx->gtls->session, user_data); + + if(ctx_setup) { + result = ctx_setup(ctx, cf, data); + if(result) + return result; + } + + rc = gnutls_priority_set_direct(ctx->gtls->session, QUIC_PRIORITY, NULL); + if(rc < 0) { + CURL_TRC_CF(data, cf, "gnutls_priority_set_direct failed: %s\n", + gnutls_strerror(rc)); + return CURLE_QUIC_CONNECT_ERROR; + } + + /* Open the file if a TLS or QUIC backend has not done this before. */ + Curl_tls_keylog_open(); + if(Curl_tls_keylog_enabled()) { + gnutls_session_set_keylog_function(ctx->gtls->session, keylog_callback); + } + + /* convert the ALPN string from our arguments to a list of strings + * that gnutls wants and will convert internally back to this very + * string for sending to the server. nice. */ + if(alpn) { + size_t i, alen = alpn_len; + unsigned char *s = (unsigned char *)alpn; + unsigned char slen; + for(i = 0; (i < ARRAYSIZE(alpns)) && alen; ++i) { + slen = s[0]; + if(slen >= alen) + return CURLE_FAILED_INIT; + alpns[i].data = s + 1; + alpns[i].size = slen; + s += slen + 1; + alen -= (size_t)slen + 1; + } + if(alen) /* not all alpn chars used, wrong format or too many */ + return CURLE_FAILED_INIT; + if(i) { + gnutls_alpn_set_protocols(ctx->gtls->session, + alpns, (unsigned int)i, + GNUTLS_ALPN_MANDATORY); + } + } + + return CURLE_OK; +} +#elif defined(USE_WOLFSSL) + +#if defined(HAVE_SECRET_CALLBACK) +static void keylog_callback(const WOLFSSL *ssl, const char *line) +{ + (void)ssl; + Curl_tls_keylog_write_line(line); +} +#endif + +static CURLcode curl_wssl_init_ctx(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data, + Curl_vquic_tls_ctx_setup *ctx_setup) +{ + struct ssl_primary_config *conn_config; + CURLcode result = CURLE_FAILED_INIT; + + conn_config = Curl_ssl_cf_get_primary_config(cf); + if(!conn_config) { + result = CURLE_FAILED_INIT; + goto out; + } + + ctx->ssl_ctx = wolfSSL_CTX_new(wolfTLSv1_3_client_method()); + if(!ctx->ssl_ctx) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } + + if(ctx_setup) { + result = ctx_setup(ctx, cf, data); + if(result) + goto out; + } + + wolfSSL_CTX_set_default_verify_paths(ctx->ssl_ctx); + + if(wolfSSL_CTX_set_cipher_list(ctx->ssl_ctx, conn_config->cipher_list13 ? + conn_config->cipher_list13 : + QUIC_CIPHERS) != 1) { + char error_buffer[256]; + ERR_error_string_n(ERR_get_error(), error_buffer, sizeof(error_buffer)); + failf(data, "wolfSSL failed to set ciphers: %s", error_buffer); + goto out; + } + + if(wolfSSL_CTX_set1_groups_list(ctx->ssl_ctx, conn_config->curves ? + conn_config->curves : + (char *)QUIC_GROUPS) != 1) { + failf(data, "wolfSSL failed to set curves"); + goto out; + } + + /* Open the file if a TLS or QUIC backend has not done this before. */ + Curl_tls_keylog_open(); + if(Curl_tls_keylog_enabled()) { +#if defined(HAVE_SECRET_CALLBACK) + wolfSSL_CTX_set_keylog_callback(ctx->ssl_ctx, keylog_callback); +#else + failf(data, "wolfSSL was built without keylog callback"); + goto out; +#endif + } + + if(conn_config->verifypeer) { + const char * const ssl_cafile = conn_config->CAfile; + const char * const ssl_capath = conn_config->CApath; + + wolfSSL_CTX_set_verify(ctx->ssl_ctx, SSL_VERIFY_PEER, NULL); + if(ssl_cafile || ssl_capath) { + /* tell wolfSSL where to find CA certificates that are used to verify + the server's certificate. */ + int rc = + wolfSSL_CTX_load_verify_locations_ex(ctx->ssl_ctx, ssl_cafile, + ssl_capath, + WOLFSSL_LOAD_FLAG_IGNORE_ERR); + if(SSL_SUCCESS != rc) { + /* Fail if we insist on successfully verifying the server. */ + failf(data, "error setting certificate verify locations:" + " CAfile: %s CApath: %s", + ssl_cafile ? ssl_cafile : "none", + ssl_capath ? ssl_capath : "none"); + goto out; + } + infof(data, " CAfile: %s", ssl_cafile ? ssl_cafile : "none"); + infof(data, " CApath: %s", ssl_capath ? ssl_capath : "none"); + } +#ifdef CURL_CA_FALLBACK + else { + /* verifying the peer without any CA certificates won't work so + use wolfssl's built-in default as fallback */ + wolfSSL_CTX_set_default_verify_paths(ctx->ssl_ctx); + } +#endif + } + else { + wolfSSL_CTX_set_verify(ctx->ssl_ctx, SSL_VERIFY_NONE, NULL); + } + + /* give application a chance to interfere with SSL set up. */ + if(data->set.ssl.fsslctx) { + Curl_set_in_callback(data, true); + result = (*data->set.ssl.fsslctx)(data, ctx->ssl_ctx, + data->set.ssl.fsslctxp); + Curl_set_in_callback(data, false); + if(result) { + failf(data, "error signaled by ssl ctx callback"); + goto out; + } + } + result = CURLE_OK; + +out: + if(result && ctx->ssl_ctx) { + SSL_CTX_free(ctx->ssl_ctx); + ctx->ssl_ctx = NULL; + } + return result; +} + +/** SSL callbacks ***/ + +static CURLcode curl_wssl_init_ssl(struct quic_tls_ctx *ctx, + struct Curl_easy *data, + struct ssl_peer *peer, + const char *alpn, size_t alpn_len, + void *user_data) +{ + (void)data; + DEBUGASSERT(!ctx->ssl); + DEBUGASSERT(ctx->ssl_ctx); + ctx->ssl = wolfSSL_new(ctx->ssl_ctx); + + wolfSSL_set_app_data(ctx->ssl, user_data); + wolfSSL_set_connect_state(ctx->ssl); + wolfSSL_set_quic_use_legacy_codepoint(ctx->ssl, 0); + + if(alpn) + wolfSSL_set_alpn_protos(ctx->ssl, (const unsigned char *)alpn, + (int)alpn_len); + + if(peer->sni) { + wolfSSL_UseSNI(ctx->ssl, WOLFSSL_SNI_HOST_NAME, + peer->sni, (unsigned short)strlen(peer->sni)); + } + + return CURLE_OK; +} +#endif /* defined(USE_WOLFSSL) */ + +CURLcode Curl_vquic_tls_init(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data, + struct ssl_peer *peer, + const char *alpn, size_t alpn_len, + Curl_vquic_tls_ctx_setup *ctx_setup, + void *user_data) +{ + CURLcode result; + +#ifdef USE_OPENSSL + result = curl_ossl_init_ctx(ctx, cf, data, ctx_setup); + if(result) + return result; + + result = curl_ossl_set_client_cert(ctx, cf, data); + if(result) + return result; + + return curl_ossl_init_ssl(ctx, data, peer, alpn, alpn_len, user_data); +#elif defined(USE_GNUTLS) + (void)result; + return curl_gtls_init_ctx(ctx, cf, data, peer, alpn, alpn_len, + ctx_setup, user_data); +#elif defined(USE_WOLFSSL) + result = curl_wssl_init_ctx(ctx, cf, data, ctx_setup); + if(result) + return result; + + return curl_wssl_init_ssl(ctx, data, peer, alpn, alpn_len, user_data); +#else +#error "no TLS lib in used, should not happen" + return CURLE_FAILED_INIT; +#endif +} + +void Curl_vquic_tls_cleanup(struct quic_tls_ctx *ctx) +{ +#ifdef USE_OPENSSL + if(ctx->ssl) + SSL_free(ctx->ssl); + if(ctx->ssl_ctx) + SSL_CTX_free(ctx->ssl_ctx); +#elif defined(USE_GNUTLS) + if(ctx->gtls) { + if(ctx->gtls->cred) + gnutls_certificate_free_credentials(ctx->gtls->cred); + if(ctx->gtls->session) + gnutls_deinit(ctx->gtls->session); + free(ctx->gtls); + } +#elif defined(USE_WOLFSSL) + if(ctx->ssl) + wolfSSL_free(ctx->ssl); + if(ctx->ssl_ctx) + wolfSSL_CTX_free(ctx->ssl_ctx); +#endif + memset(ctx, 0, sizeof(*ctx)); +} + +CURLcode Curl_vquic_tls_before_recv(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data) +{ +#ifdef USE_OPENSSL + if(!ctx->x509_store_setup) { + CURLcode result = Curl_ssl_setup_x509_store(cf, data, ctx->ssl_ctx); + if(result) + return result; + ctx->x509_store_setup = TRUE; + } +#else + (void)ctx; (void)cf; (void)data; +#endif + return CURLE_OK; +} + +CURLcode Curl_vquic_tls_verify_peer(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data, + struct ssl_peer *peer) +{ + struct ssl_primary_config *conn_config; + CURLcode result = CURLE_OK; + + conn_config = Curl_ssl_cf_get_primary_config(cf); + if(!conn_config) + return CURLE_FAILED_INIT; + + if(conn_config->verifyhost) { +#ifdef USE_OPENSSL + X509 *server_cert; + server_cert = SSL_get1_peer_certificate(ctx->ssl); + if(!server_cert) { + return CURLE_PEER_FAILED_VERIFICATION; + } + result = Curl_ossl_verifyhost(data, cf->conn, peer, server_cert); + X509_free(server_cert); + if(result) + return result; +#elif defined(USE_GNUTLS) + result = Curl_gtls_verifyserver(data, ctx->gtls->session, + conn_config, &data->set.ssl, peer, + data->set.str[STRING_SSL_PINNEDPUBLICKEY]); + if(result) + return result; +#elif defined(USE_WOLFSSL) + if(!peer->sni || + wolfSSL_check_domain_name(ctx->ssl, peer->sni) == SSL_FAILURE) + return CURLE_PEER_FAILED_VERIFICATION; +#endif + infof(data, "Verified certificate just fine"); + } + else + infof(data, "Skipped certificate verification"); +#ifdef USE_OPENSSL + if(data->set.ssl.certinfo) + /* asked to gather certificate info */ + (void)Curl_ossl_certchain(data, ctx->ssl); +#endif + return result; +} + + +#endif /* !ENABLE_QUIC && (USE_OPENSSL || USE_GNUTLS || USE_WOLFSSL) */ diff --git a/lib/vquic/vquic-tls.h b/lib/vquic/vquic-tls.h new file mode 100644 index 00000000000..9c0dfd8d528 --- /dev/null +++ b/lib/vquic/vquic-tls.h @@ -0,0 +1,98 @@ +#ifndef HEADER_CURL_VQUIC_TLS_H +#define HEADER_CURL_VQUIC_TLS_H +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +#include "curl_setup.h" +#include "bufq.h" + +#if defined(ENABLE_QUIC) && \ + (defined(USE_OPENSSL) || defined(USE_GNUTLS) || defined(USE_WOLFSSL)) + +struct quic_tls_ctx { +#ifdef USE_OPENSSL + SSL_CTX *ssl_ctx; + SSL *ssl; +#elif defined(USE_GNUTLS) + struct gtls_instance *gtls; +#elif defined(USE_WOLFSSL) + WOLFSSL_CTX *ssl_ctx; + WOLFSSL *ssl; +#endif + BIT(x509_store_setup); /* if x509 store has been set up */ +}; + +/** + * Callback passed to `Curl_vquic_tls_init()` that can + * do early initializations on the not otherwise configured TLS + * instances created. This varies by TLS backend: + * - openssl/wolfssl: SSL_CTX* has just been created + * - gnutls: gtls_client_init() has run + */ +typedef CURLcode Curl_vquic_tls_ctx_setup(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data); + +/** + * Initialize the QUIC TLS instances based of the SSL configurations + * for the connection filter, transfer and peer. + * @param ctx the TLS context to initialize + * @param cf the connection filter involved + * @param data the transfer involved + * @param peer the peer that will be connected to + * @param alpn the ALPN string in protocol format ((len+bytes+)+), + * may be NULL + * @param alpn_len the overall number of bytes in `alpn` + * @param ctx_setup optional callback for very early TLS config + * @param user_data optional pointer to set in TLS application context + */ +CURLcode Curl_vquic_tls_init(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data, + struct ssl_peer *peer, + const char *alpn, size_t alpn_len, + Curl_vquic_tls_ctx_setup *ctx_setup, + void *user_data); + +/** + * Cleanup all data that has been initialized. + */ +void Curl_vquic_tls_cleanup(struct quic_tls_ctx *ctx); + +CURLcode Curl_vquic_tls_before_recv(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data); + +/** + * After the QUIC basic handshake has been, verify that the peer + * (and its certificate) fulfill our requirements. + */ +CURLcode Curl_vquic_tls_verify_peer(struct quic_tls_ctx *ctx, + struct Curl_cfilter *cf, + struct Curl_easy *data, + struct ssl_peer *peer); + +#endif /* !ENABLE_QUIC && (USE_OPENSSL || USE_GNUTLS || USE_WOLFSSL) */ + +#endif /* HEADER_CURL_VQUIC_TLS_H */ diff --git a/lib/vquic/vquic.c b/lib/vquic/vquic.c index 41fefceac31..7da4641468b 100644 --- a/lib/vquic/vquic.c +++ b/lib/vquic/vquic.c @@ -543,8 +543,13 @@ CURLcode vquic_recv_packets(struct Curl_cfilter *cf, #else result = recvfrom_packets(cf, data, qctx, max_pkts, recv_cb, userp); #endif - if(!result) + if(!result) { + if(!qctx->got_first_byte) { + qctx->got_first_byte = TRUE; + qctx->first_byte_at = qctx->last_op; + } qctx->last_io = qctx->last_op; + } return result; } diff --git a/lib/vquic/vquic_int.h b/lib/vquic/vquic_int.h index a820f39aec4..c218a949c72 100644 --- a/lib/vquic/vquic_int.h +++ b/lib/vquic/vquic_int.h @@ -40,6 +40,7 @@ struct cf_quic_ctx { socklen_t local_addrlen; /* length of local address */ struct bufq sendbuf; /* buffer for sending one or more packets */ + struct curltime first_byte_at; /* when first byte was recvd */ struct curltime last_op; /* last (attempted) send/recv operation */ struct curltime last_io; /* last successful socket IO */ size_t gsolen; /* length of individual packets in send buf */ @@ -48,7 +49,8 @@ struct cf_quic_ctx { #ifdef DEBUGBUILD int wblock_percent; /* percent of writes doing EAGAIN */ #endif - bool no_gso; /* do not use gso on sending */ + BIT(got_first_byte); /* if first byte was received */ + BIT(no_gso); /* do not use gso on sending */ }; CURLcode vquic_ctx_init(struct cf_quic_ctx *qctx); diff --git a/tests/http/test_01_basic.py b/tests/http/test_01_basic.py index 7c1792d3747..3902b75b7c9 100644 --- a/tests/http/test_01_basic.py +++ b/tests/http/test_01_basic.py @@ -84,3 +84,18 @@ def test_01_05_h3_get(self, env: Env, httpd, nghttpx): r = curl.http_get(url=url, extra_args=['--http3-only']) r.check_response(http_status=200, protocol='HTTP/3') assert r.json['server'] == env.domain1 + + # simple download, check connect/handshake timings + @pytest.mark.skipif(condition=not Env.have_ssl_curl(), reason=f"curl without SSL") + @pytest.mark.parametrize("proto", ['http/1.1', 'h2', 'h3']) + def test_01_06_timings(self, env: Env, httpd, nghttpx, repeat, proto): + if proto == 'h3' and not env.have_h3(): + pytest.skip("h3 not supported") + curl = CurlClient(env=env) + url = f'https://{env.authority_for(env.domain1, proto)}/data.json' + r = curl.http_download(urls=[url], alpn_proto=proto, with_stats=True) + r.check_stats(http_status=200, count=1) + assert r.stats[0]['time_connect'] > 0, f'{r.stats[0]}' + assert r.stats[0]['time_appconnect'] > 0, f'{r.stats[0]}' + + From b3f02e1d927f10b48bdaa573fe09e28bdc25d94d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 11 Jan 2024 14:11:19 +0100 Subject: [PATCH 162/509] configure: when enabling QUIC, check that TLS supports QUIC Most importantly perhaps is when using OpenSSL that the used build/flavor has the QUIC API: the vanilla OpenSSL does not, only BoringSSL, libressl, AWS-LC and quictls do. Ref: https://github.com/curl/curl/commit/5d044ad9480a9f556f4b6a252d7533b1ba7fe57e#r136780413 Closes #12683 --- configure.ac | 24 ++++++++++++++++++++++++ m4/curl-gnutls.m4 | 1 + m4/curl-openssl.m4 | 9 +++++++++ m4/curl-wolfssl.m4 | 1 + 4 files changed, 35 insertions(+) diff --git a/configure.ac b/configure.ac index 39dc0963f7e..092fcb6f98d 100644 --- a/configure.ac +++ b/configure.ac @@ -2776,6 +2776,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" @@ -3030,6 +3035,11 @@ esac curl_http3_msg="no (--with-nghttp3)" if test X"$want_nghttp3" != Xno; then + + if test "$NGTCP2_ENABLED" != "1"; then + AC_MSG_ERROR([--with-nghttp3 also requires --with-ntcp2]) + fi + dnl backup the pre-nghttp3 variables CLEANLDFLAGS="$LDFLAGS" CLEANCPPFLAGS="$CPPFLAGS" @@ -3120,6 +3130,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 @@ -3218,6 +3232,16 @@ 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 diff --git a/m4/curl-gnutls.m4 b/m4/curl-gnutls.m4 index 48813dfad47..d4f553d69da 100644 --- a/m4/curl-gnutls.m4 +++ b/m4/curl-gnutls.m4 @@ -104,6 +104,7 @@ if test "x$OPT_GNUTLS" != xno; then GNUTLS_ENABLED=1 USE_GNUTLS="yes" ssl_msg="GnuTLS" + QUIC_ENABLED=yes test gnutls != "$DEFAULT_SSL_BACKEND" || VALID_DEFAULT_SSL_BACKEND=yes ], [ diff --git a/m4/curl-openssl.m4 b/m4/curl-openssl.m4 index 608653c5c7f..3f3b3c238e5 100644 --- a/m4/curl-openssl.m4 +++ b/m4/curl-openssl.m4 @@ -328,6 +328,15 @@ if test "x$OPT_OPENSSL" != xno; then ]) fi + dnl is this OpenSSL (fork) providing the original QUIC API? + AC_CHECK_FUNCS([SSL_set_quic_use_legacy_codepoint], + [QUIC_ENABLED=yes]) + if test "$QUIC_ENABLED" = "yes"; then + AC_MSG_NOTICE([OpenSSL fork speaks QUIC API]) + else + AC_MSG_NOTICE([OpenSSL version does not speak QUIC API]) + fi + if test "$OPENSSL_ENABLED" = "1"; then if test -n "$LIB_OPENSSL"; then dnl when the ssl shared libs were found in a path that the run-time diff --git a/m4/curl-wolfssl.m4 b/m4/curl-wolfssl.m4 index f630685bc23..1da47a91ec9 100644 --- a/m4/curl-wolfssl.m4 +++ b/m4/curl-wolfssl.m4 @@ -107,6 +107,7 @@ if test "x$OPT_WOLFSSL" != xno; then WOLFSSL_ENABLED=1 USE_WOLFSSL="yes" ssl_msg="WolfSSL" + QUIC_ENABLED=yes test wolfssl != "$DEFAULT_SSL_BACKEND" || VALID_DEFAULT_SSL_BACKEND=yes ], [ From 5da57193b732687f430e75f82e16d71835f9dbf3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Jan 2024 16:50:44 +0100 Subject: [PATCH 163/509] docs: describe and highlight super cookies Reported-by: Yadhu Krishna M Closes #12687 --- docs/HTTP-COOKIES.md | 19 +++++++++++++++++++ docs/cmdline-opts/cookie.d | 5 +++++ docs/libcurl/libcurl-security.3 | 7 +++++++ docs/libcurl/opts/CURLOPT_COOKIE.3 | 6 ++++++ 4 files changed, 37 insertions(+) diff --git a/docs/HTTP-COOKIES.md b/docs/HTTP-COOKIES.md index d6fd87d2051..a91e824d543 100644 --- a/docs/HTTP-COOKIES.md +++ b/docs/HTTP-COOKIES.md @@ -34,6 +34,25 @@ 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 Netscape once created a file format for storing cookies on disk so that they diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d index 23f3f466a3e..601a1958c80 100644 --- a/docs/cmdline-opts/cookie.d +++ b/docs/cmdline-opts/cookie.d @@ -44,3 +44,8 @@ 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/libcurl/libcurl-security.3 b/docs/libcurl/libcurl-security.3 index 0d7bce06bb0..4a0d76d66a8 100644 --- a/docs/libcurl/libcurl-security.3 +++ b/docs/libcurl/libcurl-security.3 @@ -420,6 +420,13 @@ credentials may be left in freed data. .SH "Saving files" libcurl cannot protect against attacks where an attacker has write access to the same directory where libcurl is directed to save files. +.SH "Cookies" +If libcurl 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 libcurl is *not* built with PSL support, it has no ability to stop super +cookies. .SH "Report Security Problems" Should you detect or just suspect a security problem in libcurl or curl, contact the project curl security team immediately. See diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.3 b/docs/libcurl/opts/CURLOPT_COOKIE.3 index e21d54c5f67..4d24fc21e23 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIE.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIE.3 @@ -62,6 +62,12 @@ automatically. The application does not have to keep the string around after setting this option. + +If libcurl 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 libcurl is *not* built with PSL support, it has no +ability to stop super cookies. PSL support is identified by the +\fBCURL_VERSION_PSL\fP feature bit returned by \fIcurl_version_info(3)\fP. .SH DEFAULT NULL, no cookies .SH PROTOCOLS From 9729560a6ff1e4ae71915d972c88d2da37ba474e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 13 Jan 2024 10:49:20 +0100 Subject: [PATCH 164/509] gen: do italics/bold for a range of letters, not just single word Previously it would match only on a sequence of non-space, which made it miss to highlight for example "public suffix list". Updated the recent cookie.d edit from 5da57193b732 to use bold instead of italics. Closes #12689 --- docs/cmdline-opts/cookie.d | 2 +- docs/cmdline-opts/gen.pl | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d index 601a1958c80..108846c062b 100644 --- a/docs/cmdline-opts/cookie.d +++ b/docs/cmdline-opts/cookie.d @@ -45,7 +45,7 @@ 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 +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/gen.pl b/docs/cmdline-opts/gen.pl index fbe0f546b88..b31a42b580f 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -98,9 +98,9 @@ sub printdesc { } if($d !~ /^.\\"/) { # **bold** - $d =~ s/\*\*([^ ]*)\*\*/\\fB$1\\fP/g; + $d =~ s/\*\*(.*?)\*\*/\\fB$1\\fP/g; # *italics* - $d =~ s/\*([^ ]*)\*/\\fI$1\\fP/g; + $d =~ s/\*(.*?)\*/\\fI$1\\fP/g; } if(!$exam && ($d =~ /^ /)) { # start of example From 9582f20d8a593e56fb163021c88c4c1119e91668 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 13 Jan 2024 10:56:47 +0100 Subject: [PATCH 165/509] TODO: TFTP doesn't convert LF to CRLF for mode=netascii Closes #12655 Closes #12690 --- docs/TODO | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/TODO b/docs/TODO index 06162c8bb64..d89b080d0ca 100644 --- a/docs/TODO +++ b/docs/TODO @@ -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 @@ -1392,3 +1395,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 From d587ab422dafcda066c73149d8221fcce9a92bb9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 13 Jan 2024 17:02:45 +0100 Subject: [PATCH 166/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 99504e702f9..adbe72874ce 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -12,6 +12,7 @@ This release includes the following changes: o add CURLINFO_QUEUE_TIME_T [76] o add CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add [39] o asyn-thread: use GetAddrInfoExW on >= Windows 8 [55] + o configure: make libpsl detection failure cause error [109] o runtests: support -gl. Like -g but for lldb. [47] This release includes the following bugfixes: @@ -33,8 +34,10 @@ This release includes the following bugfixes: o cmdline-opts: update availability for the *-ca-native options [66] o cmdline/gen: fix the sorting of the man page options [33] o configure: fix no default int compile error in ipv6 detection [69] + o configure: when enabling QUIC, check that TLS supports QUIC [87] o connect: remove margin from eyeballer alloc [79] o content_encoding: change return code to typedef'ed enum [94] + o cookie.d: document use of empty string to enable cookie engine [106] o cookie: avoid fopen with empty file name [24] o curl: show ipfs and ipns as supported "protocols" [15] o CURLINFO_REFERER.3: clarify that it is the *request* header [70] @@ -43,17 +46,24 @@ This release includes the following bugfixes: o CURLOPT_SSH_*_KEYFILE: clarify [57] o dist: add tests/errorcodes.pl to the tarball [6] o docs: clean up Protocols: for cmdline options [32] + o docs: describe and highlight super cookies [80] o doh: remove unused local variable [34] + o examples: add four new examples [99] o ftp: handle the PORT parsing without allocation [44] o ftp: use dynbuf to store entrypath [83] o ftp: use memdup0 to store the OS from a SYST 215 response [82] + o gen.pl: support ## for doing .IP in table-like lists [105] + o gen: do italics/bold for a range of letters, not just single word [78] o gnutls: fix build with --disable-verbose [3] o haproxy-clientip.d: document the arg [68] + o headers: make sure the trailing newline is not stored [97] o hostip: return error immediately when Curl_ip2addr() fails [19] + o hsts: remove assert for zero length domain [96] o http2: improved on_stream_close/data_done handling [49] o http3/quiche: fix result code on a stream reset [91] o http: adjust_pollset fix [85] o http: fix off-by-one error in request method length check [14] + o http_proxy: a blank CURLOPT_USERAGENT should not be used in CONNECT [90] o lib: add debug log outputs for CURLE_BAD_FUNCTION_ARGUMENT [62] o lib: fix variable undeclared error caused by `infof` changes [2] o lib: reduce use of strncpy [30] @@ -66,6 +76,7 @@ This release includes the following bugfixes: o mbedtls: free the entropy when threaded [46] o mime: use memdup0 instead of malloc + memcpy [63] o mprintf: overhaul and bugfixes [52] + o multi: remove total timer reset in file_do() while fetching file:// [89] o ngtcp2: put h3 at the front of alpn [58] o openldap: fix an LDAP crash [75] o openldap: fix STARTTLS [67] @@ -76,13 +87,16 @@ This release includes the following bugfixes: o Revert "urldata: move async resolver state from easy handle to connectdata" [16] o runtests: for mode="text" on , fix newlines on both parts [64] o schannel: fix `-Warith-conversion` gcc 13 warning [28] + o sectransp: do verify_cert without memdup for blobs [93] o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] o sendf: fix compiler warning with CURL_DISABLE_HEADERS_API [38] o setopt: clear mimepost when formp is freed [92] + o setopt: use memdup0 when cloning COPYPOSTFIELDS [107] o ssh: fix namespace of two local macros [51] o strerror: repair get_winsock_error() [56] o system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers [9] o system_win32: fix a function pointer assignment warning [71] + o telnet: use dynbuf instad of malloc for escape buffer [108] o tests/server: delete workaround for old-mingw [25] o tests: respect $TMPDIR when creating unix domain sockets [50] o tool: make parser reject blank arguments if not supported [86] @@ -94,6 +108,7 @@ This release includes the following bugfixes: o transfer: fix upload rate limiting, add test cases [37] o url: for disabled protocols, mention if found in redirect [7] o verify-examples.pl: fail verification on unescaped backslash [72] + o vquic: extract TLS setup into own source [88] o vtls: fix missing multissl version info [73] o vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY [41] o windows: delete redundant headers [43] @@ -203,14 +218,29 @@ References to bug reports and discussions on issues: [74] = https://curl.se/bug/?i=12631 [75] = https://curl.se/bug/?i=12593 [76] = https://curl.se/bug/?i=12368 + [78] = https://curl.se/bug/?i=12689 [79] = https://curl.se/bug/?i=12647 + [80] = https://curl.se/bug/?i=12687 [81] = https://curl.se/bug/?i=12640 [82] = https://curl.se/bug/?i=12639 [83] = https://curl.se/bug/?i=12638 [84] = https://curl.se/bug/?i=12634 [85] = https://curl.se/bug/?i=12632 [86] = https://curl.se/bug/?i=12620 + [87] = https://curl.se/bug/?i=12683 + [88] = https://curl.se/bug/?i=12678 + [89] = https://curl.se/bug/?i=12682 + [90] = https://curl.se/bug/?i=12680 [91] = https://curl.se/bug/?i=12629 [92] = https://curl.se/bug/?i=12608 + [93] = https://curl.se/bug/?i=12679 [94] = https://curl.se/bug/?i=12618 [95] = https://curl.se/bug/?i=12614 + [96] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65661 + [97] = https://curl.se/mail/lib-2024-01/0019.html + [99] = https://curl.se/bug/?i=12671 + [105] = https://curl.se/bug/?i=12667 + [106] = https://curl.se/bug/?i=12643 + [107] = https://curl.se/bug/?i=12651 + [108] = https://curl.se/bug/?i=12652 + [109] = https://curl.se/bug/?i=12661 From d7b6ce64ce0ad787ad2ed3ee05c94938a6b4f551 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 1 Dec 2023 13:50:32 +0100 Subject: [PATCH 167/509] lib: replace readwrite with write_resp This clarifies the handling of server responses by folding the code for the complicated protocols into their protocol handlers. This concerns mainly HTTP and its bastard sibling RTSP. The terms "read" and "write" are often used without clear context if they refer to the connect or the client/application side of a transfer. This PR uses "read/write" for operations on the client side and "send/receive" for the connection, e.g. server side. If this is considered useful, we can revisit renaming of further methods in another PR. Curl's protocol handler `readwrite()` method been changed: ```diff - CURLcode (*readwrite)(struct Curl_easy *data, struct connectdata *conn, - const char *buf, size_t blen, - size_t *pconsumed, bool *readmore); + CURLcode (*write_resp)(struct Curl_easy *data, const char *buf, size_t blen, + bool is_eos, bool *done); ``` The name was changed to clarify that this writes reponse data to the client side. The parameter changes are: * `conn` removed as it always operates on `data->conn` * `pconsumed` removed as the method needs to handle all data on success * `readmore` removed as no longer necessary * `is_eos` as indicator that this is the last call for the transfer response (end-of-stream). * `done` TRUE on return iff the transfer response is to be treated as finished This change affects many files only because of updated comments in handlers that provide no implementation. The real change is that the HTTP protocol handlers now provide an implementation. The HTTP protocol handlers `write_resp()` implementation will get passed **all** raw data of a server response for the transfer. The HTTP/1.x formatted status and headers, as well as the undecoded response body. `Curl_http_write_resp_hds()` is used internally to parse the response headers and pass them on. This method is public as the RTSP protocol handler also uses it. HTTP/1.1 "chunked" transport encoding is now part of the general *content encoding* writer stack, just like other encodings. A new flag `CLIENTWRITE_EOS` was added for the last client write. This allows writers to verify that they are in a valid end state. The chunked decoder will check if it indeed has seen the last chunk. The general response handling in `transfer.c:466` happens in function `readwrite_data()`. This mainly operates now like: ``` static CURLcode readwrite_data(data, ...) { do { Curl_xfer_recv_resp(data, buf) ... Curl_xfer_write_resp(data, buf) ... } while(interested); ... } ``` All the response data handling is implemented in `Curl_xfer_write_resp()`. It calls the protocol handler's `write_resp()` implementation if available, or does the default behaviour. All raw response data needs to pass through this function. Which also means that anyone in possession of such data may call `Curl_xfer_write_resp()`. Closes #12480 --- lib/c-hyper.c | 3 + lib/cf-h1-proxy.c | 65 +++---- lib/content_encoding.c | 47 +++-- lib/curl_rtmp.c | 12 +- lib/dict.c | 2 +- lib/file.c | 2 +- lib/ftp.c | 4 +- lib/gopher.c | 4 +- lib/http.c | 138 ++++++++++---- lib/http.h | 8 +- lib/http_chunks.c | 294 ++++++++++++++++++++++-------- lib/http_chunks.h | 60 ++++-- lib/imap.c | 4 +- lib/ldap.c | 4 +- lib/mqtt.c | 2 +- lib/multi.c | 2 +- lib/openldap.c | 4 +- lib/pop3.c | 4 +- lib/rtsp.c | 167 ++++++++++------- lib/sendf.c | 76 +++++--- lib/sendf.h | 4 + lib/smb.c | 4 +- lib/smtp.c | 4 +- lib/telnet.c | 2 +- lib/tftp.c | 2 +- lib/transfer.c | 402 +++++++++++++---------------------------- lib/transfer.h | 22 ++- lib/url.c | 3 - lib/urldata.h | 24 +-- lib/vssh/libssh.c | 4 +- lib/vssh/libssh2.c | 4 +- lib/vssh/wolfssh.c | 4 +- scripts/singleuse.pl | 1 + tests/libtest/lib568.c | 1 + 34 files changed, 767 insertions(+), 616 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index c4a395f0e92..d02ecd73a7b 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -325,6 +325,9 @@ static CURLcode empty_header(struct Curl_easy *data) CURLE_WRITE_ERROR : CURLE_OK; if(result) failf(data, "hyperstream: couldn't pass blank header"); + /* Hyper does chunked decoding itself. If it was added during + * response header processing, remove it again. */ + Curl_cwriter_remove_by_name(data, "chunked"); } return result; } diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index f603ccf3772..2d2d8580921 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -70,6 +70,7 @@ struct h1_tunnel_state { struct dynbuf request_data; size_t nsent; size_t headerlines; + struct Curl_chunker ch; enum keeponval { KEEPON_DONE, KEEPON_CONNECT, @@ -133,6 +134,7 @@ static CURLcode tunnel_init(struct Curl_cfilter *cf, Curl_dyn_init(&ts->rcvbuf, DYN_PROXY_CONNECT_HEADERS); Curl_dyn_init(&ts->request_data, DYN_HTTP_REQUEST); + Curl_httpchunk_init(data, &ts->ch, TRUE); *pts = ts; connkeep(cf->conn, "HTTP proxy CONNECT"); @@ -146,14 +148,6 @@ static void h1_tunnel_go_state(struct Curl_cfilter *cf, { if(ts->tunnel_state == new_state) return; - /* leaving this one */ - switch(ts->tunnel_state) { - case H1_TUNNEL_CONNECT: - data->req.ignorebody = FALSE; - break; - default: - break; - } /* entering this one */ switch(new_state) { case H1_TUNNEL_INIT: @@ -212,6 +206,7 @@ static void tunnel_free(struct Curl_cfilter *cf, h1_tunnel_go_state(cf, ts, H1_TUNNEL_FAILED, data); Curl_dyn_free(&ts->rcvbuf); Curl_dyn_free(&ts->request_data); + Curl_httpchunk_free(data, &ts->ch); free(ts); cf->ctx = NULL; } @@ -344,8 +339,8 @@ static CURLcode on_resp_header(struct Curl_cfilter *cf, STRCONST("chunked"))) { infof(data, "CONNECT responded chunked"); ts->chunked_encoding = TRUE; - /* init our chunky engine */ - Curl_httpchunk_init(data); + /* reset our chunky engine */ + Curl_httpchunk_reset(data, &ts->ch, TRUE); } } else if(Curl_compareheader(header, @@ -373,7 +368,7 @@ static CURLcode recv_CONNECT_resp(struct Curl_cfilter *cf, struct SingleRequest *k = &data->req; curl_socket_t tunnelsocket = Curl_conn_cf_get_socket(cf, data); char *linep; - size_t perline; + size_t line_len; int error, writetype; #define SELECT_OK 0 @@ -432,17 +427,17 @@ static CURLcode recv_CONNECT_resp(struct Curl_cfilter *cf, break; } } - else { + else if(ts->chunked_encoding) { /* chunked-encoded body, so we need to do the chunked dance properly to know when the end of the body is reached */ - CHUNKcode r; - CURLcode extra; size_t consumed = 0; /* now parse the chunked piece of data so that we can properly tell when the stream ends */ - r = Curl_httpchunk_read(data, &byte, 1, &consumed, &extra); - if(r == CHUNKE_STOP) { + result = Curl_httpchunk_read(data, &ts->ch, &byte, 1, &consumed); + if(result) + return result; + if(Curl_httpchunk_is_done(data, &ts->ch)) { /* we're done reading chunks! */ infof(data, "chunk reading DONE"); ts->keepon = KEEPON_DONE; @@ -462,19 +457,19 @@ static CURLcode recv_CONNECT_resp(struct Curl_cfilter *cf, ts->headerlines++; linep = Curl_dyn_ptr(&ts->rcvbuf); - perline = Curl_dyn_len(&ts->rcvbuf); /* amount of bytes in this line */ + line_len = Curl_dyn_len(&ts->rcvbuf); /* amount of bytes in this line */ /* output debug if that is requested */ - Curl_debug(data, CURLINFO_HEADER_IN, linep, perline); + Curl_debug(data, CURLINFO_HEADER_IN, linep, line_len); /* send the header to the callback */ writetype = CLIENTWRITE_HEADER | CLIENTWRITE_CONNECT | (ts->headerlines == 1 ? CLIENTWRITE_STATUS : 0); - result = Curl_client_write(data, writetype, linep, perline); + result = Curl_client_write(data, writetype, linep, line_len); if(result) return result; - result = Curl_bump_headersize(data, perline, TRUE); + result = Curl_bump_headersize(data, line_len, TRUE); if(result) return result; @@ -497,29 +492,7 @@ static CURLcode recv_CONNECT_resp(struct Curl_cfilter *cf, " bytes of response-body", ts->cl); } else if(ts->chunked_encoding) { - CHUNKcode r; - CURLcode extra; - size_t consumed = 0; - infof(data, "Ignore chunked response-body"); - - /* We set ignorebody true here since the chunked decoder - function will acknowledge that. Pay attention so that this is - cleared again when this function returns! */ - k->ignorebody = TRUE; - - if(linep[1] == '\n') - /* this can only be a LF if the letter at index 0 was a CR */ - linep++; - - /* now parse the chunked piece of data so that we can properly - tell when the stream ends */ - r = Curl_httpchunk_read(data, linep + 1, 1, &consumed, &extra); - if(r == CHUNKE_STOP) { - /* we're done reading chunks! */ - infof(data, "chunk reading DONE"); - ts->keepon = KEEPON_DONE; - } } else { /* without content-length or chunked encoding, we @@ -1030,6 +1003,14 @@ static CURLcode cf_h1_proxy_connect(struct Curl_cfilter *cf, *done = (result == CURLE_OK) && tunnel_is_established(cf->ctx); if(*done) { cf->connected = TRUE; + /* Restore `data->req` fields that may habe been touched */ + data->req.header = TRUE; /* assume header */ + data->req.bytecount = 0; + data->req.ignorebody = FALSE; + Curl_client_cleanup(data); + Curl_pgrsSetUploadCounter(data, 0); + Curl_pgrsSetDownloadCounter(data, 0); + tunnel_free(cf, data); } return result; diff --git a/lib/content_encoding.c b/lib/content_encoding.c index de75dd68670..c1abf24e8c0 100644 --- a/lib/content_encoding.c +++ b/lib/content_encoding.c @@ -835,8 +835,8 @@ static const struct Curl_cwtype identity_encoding = { }; -/* supported content encodings table. */ -static const struct Curl_cwtype * const encodings[] = { +/* supported general content decoders. */ +static const struct Curl_cwtype * const general_unencoders[] = { &identity_encoding, #ifdef HAVE_LIBZ &deflate_encoding, @@ -851,6 +851,13 @@ static const struct Curl_cwtype * const encodings[] = { NULL }; +/* supported content decoders only for transfer encodings */ +static const struct Curl_cwtype * const transfer_unencoders[] = { +#ifndef CURL_DISABLE_HTTP + &Curl_httpchunk_unencoder, +#endif + NULL +}; /* Provide a list of comma-separated names of supported encodings. */ @@ -864,7 +871,7 @@ void Curl_all_content_encodings(char *buf, size_t blen) DEBUGASSERT(blen); buf[0] = 0; - for(cep = encodings; *cep; cep++) { + for(cep = general_unencoders; *cep; cep++) { ce = *cep; if(!strcasecompare(ce->name, CONTENT_ENCODING_DEFAULT)) len += strlen(ce->name) + 2; @@ -876,7 +883,7 @@ void Curl_all_content_encodings(char *buf, size_t blen) } else if(blen > len) { char *p = buf; - for(cep = encodings; *cep; cep++) { + for(cep = general_unencoders; *cep; cep++) { ce = *cep; if(!strcasecompare(ce->name, CONTENT_ENCODING_DEFAULT)) { strcpy(p, ce->name); @@ -934,12 +941,23 @@ static const struct Curl_cwtype error_writer = { }; /* Find the content encoding by name. */ -static const struct Curl_cwtype *find_encoding(const char *name, - size_t len) +static const struct Curl_cwtype *find_unencode_writer(const char *name, + size_t len, + Curl_cwriter_phase phase) { const struct Curl_cwtype * const *cep; - for(cep = encodings; *cep; cep++) { + if(phase == CURL_CW_TRANSFER_DECODE) { + for(cep = transfer_unencoders; *cep; cep++) { + const struct Curl_cwtype *ce = *cep; + if((strncasecompare(name, ce->name, len) && !ce->name[len]) || + (ce->alias && strncasecompare(name, ce->alias, len) + && !ce->alias[len])) + return ce; + } + } + /* look among the general decoders */ + for(cep = general_unencoders; *cep; cep++) { const struct Curl_cwtype *ce = *cep; if((strncasecompare(name, ce->name, len) && !ce->name[len]) || (ce->alias && strncasecompare(name, ce->alias, len) && !ce->alias[len])) @@ -953,7 +971,6 @@ static const struct Curl_cwtype *find_encoding(const char *name, CURLcode Curl_build_unencoding_stack(struct Curl_easy *data, const char *enclist, int is_transfer) { - struct SingleRequest *k = &data->req; Curl_cwriter_phase phase = is_transfer? CURL_CW_TRANSFER_DECODE:CURL_CW_CONTENT_DECODE; CURLcode result; @@ -972,16 +989,14 @@ CURLcode Curl_build_unencoding_stack(struct Curl_easy *data, if(!ISSPACE(*enclist)) namelen = enclist - name + 1; - /* Special case: chunked encoding is handled at the reader level. */ - if(is_transfer && namelen == 7 && strncasecompare(name, "chunked", 7)) { - k->chunk = TRUE; /* chunks coming our way. */ - Curl_httpchunk_init(data); /* init our chunky engine. */ - } - else if(namelen) { + if(namelen) { const struct Curl_cwtype *cwt; struct Curl_cwriter *writer; - if((is_transfer && !data->set.http_transfer_encoding) || + /* if we skip the decoding in this phase, do not look further. + * Exception is "chunked" transfer-encoding which always must happen */ + if((is_transfer && !data->set.http_transfer_encoding && + (namelen != 7 || !strncasecompare(name, "chunked", 7))) || (!is_transfer && data->set.http_ce_skip)) { /* not requested, ignore */ return CURLE_OK; @@ -993,7 +1008,7 @@ CURLcode Curl_build_unencoding_stack(struct Curl_easy *data, return CURLE_BAD_CONTENT_ENCODING; } - cwt = find_encoding(name, namelen); + cwt = find_unencode_writer(name, namelen, phase); if(!cwt) cwt = &error_writer; /* Defer error at use. */ diff --git a/lib/curl_rtmp.c b/lib/curl_rtmp.c index f7cf54e882f..147b12a3ff4 100644 --- a/lib/curl_rtmp.c +++ b/lib/curl_rtmp.c @@ -79,7 +79,7 @@ const struct Curl_handler Curl_handler_rtmp = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ rtmp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_RTMP, /* defport */ @@ -102,7 +102,7 @@ const struct Curl_handler Curl_handler_rtmpt = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ rtmp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_RTMPT, /* defport */ @@ -125,7 +125,7 @@ const struct Curl_handler Curl_handler_rtmpe = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ rtmp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_RTMP, /* defport */ @@ -148,7 +148,7 @@ const struct Curl_handler Curl_handler_rtmpte = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ rtmp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_RTMPT, /* defport */ @@ -171,7 +171,7 @@ const struct Curl_handler Curl_handler_rtmps = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ rtmp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_RTMPS, /* defport */ @@ -194,7 +194,7 @@ const struct Curl_handler Curl_handler_rtmpts = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ rtmp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_RTMPS, /* defport */ diff --git a/lib/dict.c b/lib/dict.c index 5c9ce146120..2d6e7e48c5c 100644 --- a/lib/dict.c +++ b/lib/dict.c @@ -89,7 +89,7 @@ const struct Curl_handler Curl_handler_dict = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_DICT, /* defport */ diff --git a/lib/file.c b/lib/file.c index 1a9ef213753..73cd73a6679 100644 --- a/lib/file.c +++ b/lib/file.c @@ -113,7 +113,7 @@ const struct Curl_handler Curl_handler_file = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ file_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ 0, /* defport */ diff --git a/lib/ftp.c b/lib/ftp.c index cea77d7ee5d..1cd0afe6c16 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -168,7 +168,7 @@ const struct Curl_handler Curl_handler_ftp = { ftp_domore_getsock, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ftp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_FTP, /* defport */ @@ -199,7 +199,7 @@ const struct Curl_handler Curl_handler_ftps = { ftp_domore_getsock, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ftp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_FTPS, /* defport */ diff --git a/lib/gopher.c b/lib/gopher.c index 61e41b7e477..9ca08289eb1 100644 --- a/lib/gopher.c +++ b/lib/gopher.c @@ -75,7 +75,7 @@ const struct Curl_handler Curl_handler_gopher = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_GOPHER, /* defport */ @@ -99,7 +99,7 @@ const struct Curl_handler Curl_handler_gophers = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_GOPHER, /* defport */ diff --git a/lib/http.c b/lib/http.c index 1f33c143fae..14963ca0e4a 100644 --- a/lib/http.c +++ b/lib/http.c @@ -107,6 +107,11 @@ static bool http_should_fail(struct Curl_easy *data); static CURLcode http_setup_conn(struct Curl_easy *data, struct connectdata *conn); +static CURLcode http_write_resp(struct Curl_easy *data, + const char *buf, size_t blen, + bool is_eos, + bool *done); + #ifdef USE_WEBSOCKETS static CURLcode ws_setup_conn(struct Curl_easy *data, struct connectdata *conn); @@ -129,7 +134,7 @@ const struct Curl_handler Curl_handler_http = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + http_write_resp, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_HTTP, /* defport */ @@ -154,7 +159,7 @@ const struct Curl_handler Curl_handler_ws = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ Curl_ws_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + http_write_resp, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_HTTP, /* defport */ @@ -183,7 +188,7 @@ const struct Curl_handler Curl_handler_https = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + http_write_resp, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_HTTPS, /* defport */ @@ -208,7 +213,7 @@ const struct Curl_handler Curl_handler_wss = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ Curl_ws_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + http_write_resp, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_HTTPS, /* defport */ @@ -3055,6 +3060,7 @@ CURLcode Curl_http_firstwrite(struct Curl_easy *data, { struct SingleRequest *k = &data->req; + *done = FALSE; if(data->req.newurl) { if(conn->bits.close) { /* Abort after the headers if "follow Location" is set @@ -3991,15 +3997,16 @@ CURLcode Curl_bump_headersize(struct Curl_easy *data, /* * Read any HTTP header lines from the server and pass them to the client app. */ -CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, - struct connectdata *conn, - const char *buf, size_t blen, - size_t *pconsumed) +static CURLcode http_rw_headers(struct Curl_easy *data, + const char *buf, size_t blen, + size_t *pconsumed) { - CURLcode result; + struct connectdata *conn = data->conn; + CURLcode result = CURLE_OK; struct SingleRequest *k = &data->req; char *headp; char *end_ptr; + bool leftover_body = FALSE; /* header line within buffer loop */ *pconsumed = 0; @@ -4028,12 +4035,12 @@ CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, if(st == STATUS_BAD) { /* this is not the beginning of a protocol first header line */ k->header = FALSE; - k->badheader = TRUE; streamclose(conn, "bad HTTP: No end-of-message indicator"); if(!data->set.http09_allowed) { failf(data, "Received HTTP/0.9 when not allowed"); return CURLE_UNSUPPORTED_PROTOCOL; } + leftover_body = TRUE; goto out; } } @@ -4067,15 +4074,8 @@ CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, return CURLE_UNSUPPORTED_PROTOCOL; } k->header = FALSE; - if(blen) - /* since there's more, this is a partial bad header */ - k->badheader = TRUE; - else { - /* this was all we read so it's all a bad header */ - k->badheader = TRUE; - return CURLE_OK; - } - break; + leftover_body = TRUE; + goto out; } } @@ -4084,6 +4084,7 @@ CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, headp = Curl_dyn_ptr(&data->state.headerb); if((0x0a == *headp) || (0x0d == *headp)) { size_t headerlen; + bool switch_to_h2 = FALSE; /* Zero-length header line means end of headers! */ if('\r' == *headp) @@ -4123,14 +4124,7 @@ CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, /* we'll get more headers (HTTP/2 response) */ k->header = TRUE; k->headerline = 0; /* restart the header line counter */ - - /* switch to http2 now. The bytes after response headers - are also processed here, otherwise they are lost. */ - result = Curl_http2_upgrade(data, conn, FIRSTSOCKET, buf, blen); - if(result) - return result; - *pconsumed += blen; - blen = 0; + switch_to_h2 = TRUE; } #ifdef USE_WEBSOCKETS else if(k->upgr101 == UPGR101_WS) { @@ -4355,16 +4349,6 @@ CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, */ if(data->req.no_body) k->download_done = TRUE; -#ifndef CURL_DISABLE_RTSP - else if((conn->handler->protocol & CURLPROTO_RTSP) && - (data->set.rtspreq == RTSPREQ_DESCRIBE) && - (k->size <= -1)) - /* Respect section 4.4 of rfc2326: If the Content-Length header is - absent, a length 0 must be assumed. It will prevent libcurl from - hanging on DESCRIBE request that got refused for whatever - reason */ - k->download_done = TRUE; -#endif /* If max download size is *zero* (nothing) we already have nothing and can safely return ok now! But for HTTP/2, we'd @@ -4384,6 +4368,17 @@ CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, /* We continue reading headers, reset the line-based header */ Curl_dyn_reset(&data->state.headerb); + if(switch_to_h2) { + /* Having handled the headers, we can do the HTTP/2 switch. + * Any remaining `buf` bytes are already HTTP/2 and passed to + * be processed. */ + result = Curl_http2_upgrade(data, conn, FIRSTSOCKET, buf, blen); + if(result) + return result; + *pconsumed += blen; + blen = 0; + } + continue; } @@ -4574,9 +4569,78 @@ CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, there might be a non-header part left in the end of the read buffer. */ out: + if(!k->header && !leftover_body) { + Curl_dyn_free(&data->state.headerb); + } return CURLE_OK; } +/* + * HTTP protocol `write_resp` implementation. Will parse headers + * when not done yet and otherwise return without consuming data. + */ +CURLcode Curl_http_write_resp_hds(struct Curl_easy *data, + const char *buf, size_t blen, + size_t *pconsumed, + bool *done) +{ + *done = FALSE; + if(!data->req.header) { + *pconsumed = 0; + return CURLE_OK; + } + else { + CURLcode result; + + result = http_rw_headers(data, buf, blen, pconsumed); + if(!result && !data->req.header) { + /* we have successfully finished parsing the HEADERs */ + result = Curl_http_firstwrite(data, data->conn, done); + + if(!data->req.no_body && Curl_dyn_len(&data->state.headerb)) { + /* leftover from parsing something that turned out not + * to be a header, only happens if we allow for + * HTTP/0.9 like responses */ + result = Curl_client_write(data, CLIENTWRITE_BODY, + Curl_dyn_ptr(&data->state.headerb), + Curl_dyn_len(&data->state.headerb)); + } + Curl_dyn_free(&data->state.headerb); + } + return result; + } +} + +static CURLcode http_write_resp(struct Curl_easy *data, + const char *buf, size_t blen, + bool is_eos, + bool *done) +{ + CURLcode result; + size_t consumed; + int flags; + + *done = FALSE; + result = Curl_http_write_resp_hds(data, buf, blen, &consumed, done); + if(result || *done) + goto out; + + DEBUGASSERT(consumed <= blen); + blen -= consumed; + buf += consumed; + /* either all was consumed in header parsing, or we have data left + * and are done with heders, e.g. it is BODY data */ + DEBUGASSERT(!blen || !data->req.header); + if(!data->req.header && (blen || is_eos)) { + /* BODY data after header been parsed, write and consume */ + flags = CLIENTWRITE_BODY; + if(is_eos) + flags |= CLIENTWRITE_EOS; + result = Curl_client_write(data, flags, (char *)buf, blen); + } +out: + return result; +} /* Decode HTTP status code string. */ CURLcode Curl_http_decode_status(int *pstatus, const char *s, size_t len) diff --git a/lib/http.h b/lib/http.h index 56b091301f8..8116ec1aacd 100644 --- a/lib/http.h +++ b/lib/http.h @@ -225,10 +225,10 @@ struct HTTP { CURLcode Curl_http_size(struct Curl_easy *data); -CURLcode Curl_http_readwrite_headers(struct Curl_easy *data, - struct connectdata *conn, - const char *buf, size_t blen, - size_t *pconsumed); +CURLcode Curl_http_write_resp_hds(struct Curl_easy *data, + const char *buf, size_t blen, + size_t *pconsumed, + bool *done); /** * Curl_http_output_auth() setups the authentication headers for the diff --git a/lib/http_chunks.c b/lib/http_chunks.c index acdb1086341..039c179c44c 100644 --- a/lib/http_chunks.c +++ b/lib/http_chunks.c @@ -75,47 +75,67 @@ */ -void Curl_httpchunk_init(struct Curl_easy *data) +void Curl_httpchunk_init(struct Curl_easy *data, struct Curl_chunker *ch, + bool ignore_body) { - struct connectdata *conn = data->conn; - struct Curl_chunker *chunk = &conn->chunk; - chunk->hexindex = 0; /* start at 0 */ - chunk->state = CHUNK_HEX; /* we get hex first! */ - Curl_dyn_init(&conn->trailer, DYN_H1_TRAILER); + (void)data; + ch->hexindex = 0; /* start at 0 */ + ch->state = CHUNK_HEX; /* we get hex first! */ + ch->last_code = CHUNKE_OK; + Curl_dyn_init(&ch->trailer, DYN_H1_TRAILER); + ch->ignore_body = ignore_body; } -/* - * chunk_read() returns a OK for normal operations, or a positive return code - * for errors. STOP means this sequence of chunks is complete. The 'wrote' - * argument is set to tell the caller how many bytes we actually passed to the - * client (for byte-counting and whatever). - * - * The states and the state-machine is further explained in the header file. - * - * This function always uses ASCII hex values to accommodate non-ASCII hosts. - * For example, 0x0d and 0x0a are used instead of '\r' and '\n'. - */ -CHUNKcode Curl_httpchunk_read(struct Curl_easy *data, - char *buf, - size_t blen, - size_t *pconsumed, - CURLcode *extrap) +void Curl_httpchunk_reset(struct Curl_easy *data, struct Curl_chunker *ch, + bool ignore_body) +{ + (void)data; + ch->hexindex = 0; /* start at 0 */ + ch->state = CHUNK_HEX; /* we get hex first! */ + ch->last_code = CHUNKE_OK; + Curl_dyn_reset(&ch->trailer); + ch->ignore_body = ignore_body; +} + +void Curl_httpchunk_free(struct Curl_easy *data, struct Curl_chunker *ch) +{ + (void)data; + Curl_dyn_free(&ch->trailer); +} + +bool Curl_httpchunk_is_done(struct Curl_easy *data, struct Curl_chunker *ch) +{ + (void)data; + return ch->state == CHUNK_DONE; +} + +static CURLcode httpchunk_readwrite(struct Curl_easy *data, + struct Curl_chunker *ch, + struct Curl_cwriter *cw_next, + const char *buf, size_t blen, + size_t *pconsumed) { CURLcode result = CURLE_OK; - struct connectdata *conn = data->conn; - struct Curl_chunker *ch = &conn->chunk; - struct SingleRequest *k = &data->req; size_t piece; *pconsumed = 0; /* nothing's written yet */ + /* first check terminal states that will not progress anywhere */ + if(ch->state == CHUNK_DONE) + return CURLE_OK; + if(ch->state == CHUNK_FAILED) + return CURLE_RECV_ERROR; /* the original data is written to the client, but we go on with the chunk read process, to properly calculate the content length */ - if(data->set.http_te_skip && !k->ignorebody) { - result = Curl_client_write(data, CLIENTWRITE_BODY, buf, blen); + if(data->set.http_te_skip && !ch->ignore_body) { + if(cw_next) + result = Curl_cwriter_write(data, cw_next, CLIENTWRITE_BODY, buf, blen); + else + result = Curl_client_write(data, CLIENTWRITE_BODY, (char *)buf, blen); if(result) { - *extrap = result; - return CHUNKE_PASSTHRU_ERROR; + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_PASSTHRU_ERROR; + return result; } } @@ -123,28 +143,35 @@ CHUNKcode Curl_httpchunk_read(struct Curl_easy *data, switch(ch->state) { case CHUNK_HEX: if(ISXDIGIT(*buf)) { - if(ch->hexindex < CHUNK_MAXNUM_LEN) { - ch->hexbuffer[ch->hexindex] = *buf; - buf++; - blen--; - ch->hexindex++; - } - else { - return CHUNKE_TOO_LONG_HEX; /* longer hex than we support */ + if(ch->hexindex >= CHUNK_MAXNUM_LEN) { + failf(data, "chunk hex-length longer than %d", CHUNK_MAXNUM_LEN); + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_TOO_LONG_HEX; /* longer than we support */ + return CURLE_RECV_ERROR; } + ch->hexbuffer[ch->hexindex++] = *buf; + buf++; + blen--; } else { char *endptr; - if(0 == ch->hexindex) + if(0 == ch->hexindex) { /* This is illegal data, we received junk where we expected a hexadecimal digit. */ - return CHUNKE_ILLEGAL_HEX; + failf(data, "chunk hex-length char not a hex digit: 0x%x", *buf); + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_ILLEGAL_HEX; + return CURLE_RECV_ERROR; + } /* blen and buf are unmodified */ ch->hexbuffer[ch->hexindex] = 0; - - if(curlx_strtoofft(ch->hexbuffer, &endptr, 16, &ch->datasize)) - return CHUNKE_ILLEGAL_HEX; + if(curlx_strtoofft(ch->hexbuffer, &endptr, 16, &ch->datasize)) { + failf(data, "chunk hex-length not valid: '%s'", ch->hexbuffer); + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_ILLEGAL_HEX; + return CURLE_RECV_ERROR; + } ch->state = CHUNK_LF; /* now wait for the CRLF */ } break; @@ -173,12 +200,17 @@ CHUNKcode Curl_httpchunk_read(struct Curl_easy *data, piece = curlx_sotouz(ch->datasize); /* Write the data portion available */ - if(!data->set.http_te_skip && !k->ignorebody) { - result = Curl_client_write(data, CLIENTWRITE_BODY, buf, piece); - + if(!data->set.http_te_skip && !ch->ignore_body) { + if(cw_next) + result = Curl_cwriter_write(data, cw_next, CLIENTWRITE_BODY, + buf, piece); + else + result = Curl_client_write(data, CLIENTWRITE_BODY, + (char *)buf, piece); if(result) { - *extrap = result; - return CHUNKE_PASSTHRU_ERROR; + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_PASSTHRU_ERROR; + return result; } } @@ -195,38 +227,51 @@ CHUNKcode Curl_httpchunk_read(struct Curl_easy *data, case CHUNK_POSTLF: if(*buf == 0x0a) { /* The last one before we go back to hex state and start all over. */ - Curl_httpchunk_init(data); /* sets state back to CHUNK_HEX */ + Curl_httpchunk_reset(data, ch, ch->ignore_body); + } + else if(*buf != 0x0d) { + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_BAD_CHUNK; + return CURLE_RECV_ERROR; } - else if(*buf != 0x0d) - return CHUNKE_BAD_CHUNK; buf++; blen--; break; case CHUNK_TRAILER: if((*buf == 0x0d) || (*buf == 0x0a)) { - char *tr = Curl_dyn_ptr(&conn->trailer); + char *tr = Curl_dyn_ptr(&ch->trailer); /* this is the end of a trailer, but if the trailer was zero bytes there was no trailer and we move on */ if(tr) { size_t trlen; - result = Curl_dyn_addn(&conn->trailer, (char *)STRCONST("\x0d\x0a")); - if(result) - return CHUNKE_OUT_OF_MEMORY; - - tr = Curl_dyn_ptr(&conn->trailer); - trlen = Curl_dyn_len(&conn->trailer); + result = Curl_dyn_addn(&ch->trailer, (char *)STRCONST("\x0d\x0a")); + if(result) { + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_OUT_OF_MEMORY; + return result; + } + tr = Curl_dyn_ptr(&ch->trailer); + trlen = Curl_dyn_len(&ch->trailer); if(!data->set.http_te_skip) { - result = Curl_client_write(data, - CLIENTWRITE_HEADER|CLIENTWRITE_TRAILER, - tr, trlen); + if(cw_next) + result = Curl_cwriter_write(data, cw_next, + CLIENTWRITE_HEADER| + CLIENTWRITE_TRAILER, + tr, trlen); + else + result = Curl_client_write(data, + CLIENTWRITE_HEADER| + CLIENTWRITE_TRAILER, + tr, trlen); if(result) { - *extrap = result; - return CHUNKE_PASSTHRU_ERROR; + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_PASSTHRU_ERROR; + return result; } } - Curl_dyn_reset(&conn->trailer); + Curl_dyn_reset(&ch->trailer); ch->state = CHUNK_TRAILER_CR; if(*buf == 0x0a) /* already on the LF */ @@ -239,9 +284,12 @@ CHUNKcode Curl_httpchunk_read(struct Curl_easy *data, } } else { - result = Curl_dyn_addn(&conn->trailer, buf, 1); - if(result) - return CHUNKE_OUT_OF_MEMORY; + result = Curl_dyn_addn(&ch->trailer, buf, 1); + if(result) { + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_OUT_OF_MEMORY; + return result; + } } buf++; blen--; @@ -253,8 +301,11 @@ CHUNKcode Curl_httpchunk_read(struct Curl_easy *data, buf++; blen--; } - else - return CHUNKE_BAD_CHUNK; + else { + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_BAD_CHUNK; + return CURLE_RECV_ERROR; + } break; case CHUNK_TRAILER_POSTCR: @@ -277,21 +328,29 @@ CHUNKcode Curl_httpchunk_read(struct Curl_easy *data, case CHUNK_STOP: if(*buf == 0x0a) { blen--; - /* Record the length of any data left in the end of the buffer even if there's no more chunks to read */ ch->datasize = blen; - - return CHUNKE_STOP; /* return stop */ + ch->state = CHUNK_DONE; + return CURLE_OK; } - else - return CHUNKE_BAD_CHUNK; + else { + ch->state = CHUNK_FAILED; + ch->last_code = CHUNKE_BAD_CHUNK; + return CURLE_RECV_ERROR; + } + case CHUNK_DONE: + return CURLE_OK; + + case CHUNK_FAILED: + return CURLE_RECV_ERROR; } + } - return CHUNKE_OK; + return CURLE_OK; } -const char *Curl_chunked_strerror(CHUNKcode code) +static const char *Curl_chunked_strerror(CHUNKcode code) { switch(code) { default: @@ -303,8 +362,7 @@ const char *Curl_chunked_strerror(CHUNKcode code) case CHUNKE_BAD_CHUNK: return "Malformed encoding found"; case CHUNKE_PASSTHRU_ERROR: - DEBUGASSERT(0); /* never used */ - return ""; + return "Error writing data to client"; case CHUNKE_BAD_ENCODING: return "Bad content-encoding found"; case CHUNKE_OUT_OF_MEMORY: @@ -312,4 +370,86 @@ const char *Curl_chunked_strerror(CHUNKcode code) } } +CURLcode Curl_httpchunk_read(struct Curl_easy *data, + struct Curl_chunker *ch, + char *buf, size_t blen, + size_t *pconsumed) +{ + return httpchunk_readwrite(data, ch, NULL, buf, blen, pconsumed); +} + +struct chunked_writer { + struct Curl_cwriter super; + struct Curl_chunker ch; +}; + +static CURLcode cw_chunked_init(struct Curl_easy *data, + struct Curl_cwriter *writer) +{ + struct chunked_writer *ctx = (struct chunked_writer *)writer; + + data->req.chunk = TRUE; /* chunks coming our way. */ + Curl_httpchunk_init(data, &ctx->ch, FALSE); + return CURLE_OK; +} + +static void cw_chunked_close(struct Curl_easy *data, + struct Curl_cwriter *writer) +{ + struct chunked_writer *ctx = (struct chunked_writer *)writer; + Curl_httpchunk_free(data, &ctx->ch); +} + +static CURLcode cw_chunked_write(struct Curl_easy *data, + struct Curl_cwriter *writer, int type, + const char *buf, size_t blen) +{ + struct chunked_writer *ctx = (struct chunked_writer *)writer; + CURLcode result; + size_t consumed; + + if(!(type & CLIENTWRITE_BODY)) + return Curl_cwriter_write(data, writer->next, type, buf, blen); + + consumed = 0; + result = httpchunk_readwrite(data, &ctx->ch, writer->next, buf, blen, + &consumed); + + if(result) { + if(CHUNKE_PASSTHRU_ERROR == ctx->ch.last_code) { + failf(data, "Failed reading the chunked-encoded stream"); + } + else { + failf(data, "%s in chunked-encoding", + Curl_chunked_strerror(ctx->ch.last_code)); + } + return result; + } + + blen -= consumed; + if(CHUNK_DONE == ctx->ch.state) { + /* chunks read successfully, download is complete */ + data->req.download_done = TRUE; + if(blen) { + infof(data, "Leftovers after chunking: %zu bytes", blen); + } + } + else if((type & CLIENTWRITE_EOS) && !data->req.no_body) { + failf(data, "transfer closed with outstanding read data remaining"); + return CURLE_PARTIAL_FILE; + } + + return CURLE_OK; +} + +/* HTTP chunked Transfer-Encoding decoder */ +const struct Curl_cwtype Curl_httpchunk_unencoder = { + "chunked", + NULL, + cw_chunked_init, + cw_chunked_write, + cw_chunked_close, + sizeof(struct chunked_writer) +}; + #endif /* CURL_DISABLE_HTTP */ diff --git a/lib/http_chunks.h b/lib/http_chunks.h index 0a36f379b17..07f2984c36e 100644 --- a/lib/http_chunks.h +++ b/lib/http_chunks.h @@ -24,6 +24,10 @@ * ***************************************************************************/ +#ifndef CURL_DISABLE_HTTP + +#include "dynbuf.h" + struct connectdata; /* @@ -67,34 +71,68 @@ typedef enum { signalled If this is an empty trailer CHUNKE_STOP will be signalled. Otherwise the trailer will be broadcasted via Curl_client_write() and the next state will be CHUNK_TRAILER */ - CHUNK_TRAILER_POSTCR + CHUNK_TRAILER_POSTCR, + + /* Successfully de-chunked everything */ + CHUNK_DONE, + + /* Failed on seeing a bad or not correctly terminated chunk */ + CHUNK_FAILED } ChunkyState; typedef enum { - CHUNKE_STOP = -1, CHUNKE_OK = 0, CHUNKE_TOO_LONG_HEX = 1, CHUNKE_ILLEGAL_HEX, CHUNKE_BAD_CHUNK, CHUNKE_BAD_ENCODING, CHUNKE_OUT_OF_MEMORY, - CHUNKE_PASSTHRU_ERROR, /* Curl_httpchunk_read() returns a CURLcode to use */ - CHUNKE_LAST + CHUNKE_PASSTHRU_ERROR /* Curl_httpchunk_read() returns a CURLcode to use */ } CHUNKcode; -const char *Curl_chunked_strerror(CHUNKcode code); - struct Curl_chunker { curl_off_t datasize; ChunkyState state; + CHUNKcode last_code; + struct dynbuf trailer; /* for chunked-encoded trailer */ unsigned char hexindex; - char hexbuffer[ CHUNK_MAXNUM_LEN + 1]; /* +1 for null-terminator */ + char hexbuffer[CHUNK_MAXNUM_LEN + 1]; /* +1 for null-terminator */ + BIT(ignore_body); /* never write response body data */ }; /* The following functions are defined in http_chunks.c */ -void Curl_httpchunk_init(struct Curl_easy *data); -CHUNKcode Curl_httpchunk_read(struct Curl_easy *data, char *buf, - size_t blen, size_t *pconsumed, - CURLcode *passthru); +void Curl_httpchunk_init(struct Curl_easy *data, struct Curl_chunker *ch, + bool ignore_body); +void Curl_httpchunk_free(struct Curl_easy *data, struct Curl_chunker *ch); +void Curl_httpchunk_reset(struct Curl_easy *data, struct Curl_chunker *ch, + bool ignore_body); + +/* + * Read BODY bytes in HTTP/1.1 chunked encoding from `buf` and return + * the amount of bytes consumed. The actual response bytes and trailer + * headers are written out to the client. + * On success, this will consume all bytes up to the end of the response, + * e.g. the last chunk, has been processed. + * @param data the transfer involved + * @param ch the chunker instance keeping state across calls + * @param buf the response data + * @param blen amount of bytes in `buf` + * @param pconsumed on successful return, the number of bytes in `buf` + * consumed + * + * This function always uses ASCII hex values to accommodate non-ASCII hosts. + * For example, 0x0d and 0x0a are used instead of '\r' and '\n'. + */ +CURLcode Curl_httpchunk_read(struct Curl_easy *data, struct Curl_chunker *ch, + char *buf, size_t blen, size_t *pconsumed); + +/** + * @return TRUE iff chunked decoded has finished successfully. + */ +bool Curl_httpchunk_is_done(struct Curl_easy *data, struct Curl_chunker *ch); + +extern const struct Curl_cwtype Curl_httpchunk_unencoder; + +#endif /* !CURL_DISABLE_HTTP */ #endif /* HEADER_CURL_HTTP_CHUNKS_H */ diff --git a/lib/imap.c b/lib/imap.c index 4e1f4d4bf0b..869ded85a39 100644 --- a/lib/imap.c +++ b/lib/imap.c @@ -130,7 +130,7 @@ const struct Curl_handler Curl_handler_imap = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ imap_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_IMAP, /* defport */ @@ -159,7 +159,7 @@ const struct Curl_handler Curl_handler_imaps = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ imap_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_IMAPS, /* defport */ diff --git a/lib/ldap.c b/lib/ldap.c index 99ac317159e..4c04647f4f5 100644 --- a/lib/ldap.c +++ b/lib/ldap.c @@ -177,7 +177,7 @@ const struct Curl_handler Curl_handler_ldap = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_LDAP, /* defport */ @@ -205,7 +205,7 @@ const struct Curl_handler Curl_handler_ldaps = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_LDAPS, /* defport */ diff --git a/lib/mqtt.c b/lib/mqtt.c index e3a7aff9791..3f7eb761c26 100644 --- a/lib/mqtt.c +++ b/lib/mqtt.c @@ -88,7 +88,7 @@ const struct Curl_handler Curl_handler_mqtt = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_MQTT, /* defport */ diff --git a/lib/multi.c b/lib/multi.c index 63ab67691ed..0926b0d85e9 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -2480,7 +2480,7 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, } /* read/write data if it is ready to do so */ - result = Curl_readwrite(data->conn, data, &done); + result = Curl_readwrite(data, &done); if(done || (result == CURLE_RECV_ERROR)) { /* If CURLE_RECV_ERROR happens early enough, we assume it was a race diff --git a/lib/openldap.c b/lib/openldap.c index 171a4c3ce8c..1e60ff7387d 100644 --- a/lib/openldap.c +++ b/lib/openldap.c @@ -130,7 +130,7 @@ const struct Curl_handler Curl_handler_ldap = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ oldap_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_LDAP, /* defport */ @@ -158,7 +158,7 @@ const struct Curl_handler Curl_handler_ldaps = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ oldap_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_LDAPS, /* defport */ diff --git a/lib/pop3.c b/lib/pop3.c index 648945ca8eb..64e786d7190 100644 --- a/lib/pop3.c +++ b/lib/pop3.c @@ -125,7 +125,7 @@ const struct Curl_handler Curl_handler_pop3 = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ pop3_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_POP3, /* defport */ @@ -154,7 +154,7 @@ const struct Curl_handler Curl_handler_pop3s = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ pop3_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_POP3S, /* defport */ diff --git a/lib/rtsp.c b/lib/rtsp.c index f83c0b5886a..c911bb6b22a 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -58,21 +58,20 @@ static int rtsp_getsock_do(struct Curl_easy *data, struct connectdata *conn, curl_socket_t *socks); /* - * Parse and write out any available RTP data. + * Parse and write out an RTSP response. * @param data the transfer * @param conn the connection * @param buf data read from connection * @param blen amount of data in buf - * @param consumed out, number of blen consumed + * @param is_eos TRUE iff this is the last write * @param readmore out, TRUE iff complete buf was consumed and more data * is needed */ -static CURLcode rtsp_rtp_readwrite(struct Curl_easy *data, - struct connectdata *conn, - const char *buf, - size_t blen, - size_t *pconsumed, - bool *readmore); +static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, + const char *buf, + size_t blen, + bool is_eos, + bool *done); static CURLcode rtsp_setup_connection(struct Curl_easy *data, struct connectdata *conn); @@ -115,7 +114,7 @@ const struct Curl_handler Curl_handler_rtsp = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ rtsp_disconnect, /* disconnect */ - rtsp_rtp_readwrite, /* readwrite */ + rtsp_rtp_write_resp, /* write_resp */ rtsp_conncheck, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_RTSP, /* defport */ @@ -590,26 +589,48 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) return result; } +/** + * write any BODY bytes missing to the client, ignore the rest. + */ +static CURLcode rtp_write_body_junk(struct Curl_easy *data, + const char *buf, + size_t blen) +{ + struct rtsp_conn *rtspc = &(data->conn->proto.rtspc); + curl_off_t body_remain; + bool in_body; + + in_body = (data->req.headerline && !rtspc->in_header) && + (data->req.size >= 0) && + (data->req.bytecount < data->req.size); + body_remain = in_body? (data->req.size - data->req.bytecount) : 0; + DEBUGASSERT(body_remain >= 0); + if(body_remain) { + if((curl_off_t)blen > body_remain) + blen = (size_t)body_remain; + return Curl_client_write(data, CLIENTWRITE_BODY, (char *)buf, blen); + } + return CURLE_OK; +} + static CURLcode rtsp_filter_rtp(struct Curl_easy *data, - struct connectdata *conn, const char *buf, size_t blen, - bool in_body, size_t *pconsumed) { - struct rtsp_conn *rtspc = &(conn->proto.rtspc); + struct rtsp_conn *rtspc = &(data->conn->proto.rtspc); CURLcode result = CURLE_OK; + size_t skip_len = 0; *pconsumed = 0; while(blen) { + bool in_body = (data->req.headerline && !rtspc->in_header) && + (data->req.size >= 0) && + (data->req.bytecount < data->req.size); switch(rtspc->state) { case RTP_PARSE_SKIP: { DEBUGASSERT(Curl_dyn_len(&rtspc->buf) == 0); - if(in_body && buf[0] != '$') { - /* in BODY and no valid start, do not consume and return */ - goto out; - } while(blen && buf[0] != '$') { if(!in_body && buf[0] == 'R' && data->set.rtspreq != RTSPREQ_RECEIVE) { @@ -624,13 +645,22 @@ static CURLcode rtsp_filter_rtp(struct Curl_easy *data, goto out; } } - /* junk, consume without buffering */ + /* junk/BODY, consume without buffering */ *pconsumed += 1; ++buf; --blen; + ++skip_len; } if(blen && buf[0] == '$') { /* possible start of an RTP message, buffer */ + if(skip_len) { + /* end of junk/BODY bytes, flush */ + result = rtp_write_body_junk(data, + (char *)(buf - skip_len), skip_len); + skip_len = 0; + if(result) + goto out; + } if(Curl_dyn_addn(&rtspc->buf, buf, 1)) { result = CURLE_OUT_OF_MEMORY; goto out; @@ -650,35 +680,22 @@ static CURLcode rtsp_filter_rtp(struct Curl_easy *data, if(!(data->state.rtp_channel_mask[idx] & (1 << off))) { /* invalid channel number, junk or BODY data */ rtspc->state = RTP_PARSE_SKIP; - if(in_body) { - /* we do not consume this byte, it is BODY data */ - DEBUGF(infof(data, "RTSP: invalid RTP channel %d in BODY, " - "treating as BODY data", idx)); - if(*pconsumed == 0) { - /* We did not consume the initial '$' in our buffer, but had - * it from an earlier call. We cannot un-consume it and have - * to write it directly as BODY data */ - result = Curl_client_write(data, CLIENTWRITE_BODY, - Curl_dyn_ptr(&rtspc->buf), 1); - Curl_dyn_free(&rtspc->buf); - if(result) - goto out; - } - else { - /* un-consume the '$' and leave */ - Curl_dyn_free(&rtspc->buf); - *pconsumed -= 1; - --buf; - ++blen; + DEBUGASSERT(skip_len == 0); + /* we do not consume this byte, it is BODY data */ + DEBUGF(infof(data, "RTSP: invalid RTP channel %d, skipping", idx)); + if(*pconsumed == 0) { + /* We did not consume the initial '$' in our buffer, but had + * it from an earlier call. We cannot un-consume it and have + * to write it directly as BODY data */ + result = rtp_write_body_junk(data, Curl_dyn_ptr(&rtspc->buf), 1); + if(result) goto out; - } } else { - /* not BODY, forget the junk '$'. Do not consume this byte, - * it might be a start */ - infof(data, "RTSP: invalid RTP channel %d, skipping", idx); - Curl_dyn_free(&rtspc->buf); + /* count the '$' as skip and continue */ + skip_len = 1; } + Curl_dyn_free(&rtspc->buf); break; } /* a valid channel, so we expect this to be a real RTP message */ @@ -754,52 +771,49 @@ static CURLcode rtsp_filter_rtp(struct Curl_easy *data, } } out: + if(!result && skip_len) + result = rtp_write_body_junk(data, (char *)(buf - skip_len), skip_len); return result; } -static CURLcode rtsp_rtp_readwrite(struct Curl_easy *data, - struct connectdata *conn, - const char *buf, - size_t blen, - size_t *pconsumed, - bool *readmore) +static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, + const char *buf, + size_t blen, + bool is_eos, + bool *done) { - struct rtsp_conn *rtspc = &(conn->proto.rtspc); + struct rtsp_conn *rtspc = &(data->conn->proto.rtspc); CURLcode result = CURLE_OK; size_t consumed = 0; - bool in_body; if(!data->req.header) rtspc->in_header = FALSE; - in_body = (data->req.headerline && !rtspc->in_header) && - (data->req.size >= 0) && - (data->req.bytecount < data->req.size); - - *readmore = FALSE; - *pconsumed = 0; + *done = FALSE; if(!blen) { goto out; } + DEBUGF(infof(data, "rtsp_rtp_write_resp(len=%zu, in_header=%d, eos=%d)", + blen, rtspc->in_header, is_eos)); + /* If header parsing is not onging, extract RTP messages */ if(!rtspc->in_header) { - result = rtsp_filter_rtp(data, conn, buf, blen, in_body, &consumed); + result = rtsp_filter_rtp(data, buf, blen, &consumed); if(result) goto out; - *pconsumed += consumed; buf += consumed; blen -= consumed; + /* either we consumed all or are at the start of header parsing */ + DEBUGASSERT(blen == 0 || data->req.header); } /* we want to parse headers, do so */ if(data->req.header && blen) { rtspc->in_header = TRUE; - result = Curl_http_readwrite_headers(data, conn, buf, blen, - &consumed); + result = Curl_http_write_resp_hds(data, buf, blen, &consumed, done); if(result) goto out; - *pconsumed += consumed; buf += consumed; blen -= consumed; @@ -807,26 +821,39 @@ static CURLcode rtsp_rtp_readwrite(struct Curl_easy *data, rtspc->in_header = FALSE; if(!rtspc->in_header) { - /* If header parsing is done and data left, extract RTP messages */ - in_body = (data->req.headerline && !rtspc->in_header) && - (data->req.size >= 0) && - (data->req.bytecount < data->req.size); - result = rtsp_filter_rtp(data, conn, buf, blen, in_body, &consumed); + /* If header parsing is done, extract interleaved RTP messages */ + if((data->set.rtspreq == RTSPREQ_DESCRIBE) && (data->req.size <= -1)) { + /* Respect section 4.4 of rfc2326: If the Content-Length header is + absent, a length 0 must be assumed. It will prevent libcurl from + hanging on DESCRIBE request that got refused for whatever + reason */ + data->req.download_done = TRUE; + } + result = rtsp_filter_rtp(data, buf, blen, &consumed); if(result) goto out; - *pconsumed += consumed; + blen -= consumed; } } if(rtspc->state != RTP_PARSE_SKIP) - *readmore = TRUE; + *done = FALSE; + /* we MUST have consumed all bytes */ + DEBUGF(infof(data, "rtsp_rtp_write_resp(len=%zu, in_header=%d, done=%d)", + blen, rtspc->in_header, *done)); + DEBUGASSERT(blen == 0); + if(!result && is_eos) { + result = Curl_client_write(data, CLIENTWRITE_BODY|CLIENTWRITE_EOS, + (char *)buf, 0); + } out: - if(!*readmore && data->set.rtspreq == RTSPREQ_RECEIVE) { + if((data->set.rtspreq == RTSPREQ_RECEIVE) && + (rtspc->state == RTP_PARSE_SKIP)) { /* In special mode RECEIVE, we just process one chunk of network * data, so we stop the transfer here, if we have no incomplete * RTP message pending. */ - data->req.keepon &= ~KEEP_RECV; + data->req.download_done = TRUE; } return result; } diff --git a/lib/sendf.c b/lib/sendf.c index 1bdab916532..2a2dfce8e8b 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -404,10 +404,12 @@ CURLcode Curl_client_write(struct Curl_easy *data, #endif /* it is one of those, at least */ DEBUGASSERT(type & (CLIENTWRITE_BODY|CLIENTWRITE_HEADER|CLIENTWRITE_INFO)); - /* BODY is only BODY */ - DEBUGASSERT(!(type & CLIENTWRITE_BODY) || (type == CLIENTWRITE_BODY)); - /* INFO is only INFO */ - DEBUGASSERT(!(type & CLIENTWRITE_INFO) || (type == CLIENTWRITE_INFO)); + /* BODY is only BODY (with optional EOS) */ + DEBUGASSERT(!(type & CLIENTWRITE_BODY) || + ((type & ~(CLIENTWRITE_BODY|CLIENTWRITE_EOS)) == 0)); + /* INFO is only INFO (with optional EOS) */ + DEBUGASSERT(!(type & CLIENTWRITE_INFO) || + ((type & ~(CLIENTWRITE_INFO|CLIENTWRITE_EOS)) == 0)); if(!data->req.writer_stack) { result = do_init_stack(data); @@ -477,8 +479,6 @@ CURLcode Curl_cwriter_write(struct Curl_easy *data, struct Curl_cwriter *writer, int type, const char *buf, size_t nbytes) { - if(!nbytes) - return CURLE_OK; if(!writer) return CURLE_WRITE_ERROR; return writer->cwt->do_write(data, writer, type, buf, nbytes); @@ -556,7 +556,6 @@ static CURLcode cw_download_write(struct Curl_easy *data, { CURLcode result; size_t nwrite, excess_len = 0; - const char *excess_data = NULL; if(!(type & CLIENTWRITE_BODY)) { if((type & CLIENTWRITE_CONNECT) && data->set.suppress_connect_headers) @@ -564,13 +563,38 @@ static CURLcode cw_download_write(struct Curl_easy *data, return Curl_cwriter_write(data, writer->next, type, buf, nbytes); } + if(!data->req.bytecount) { + Curl_pgrsTime(data, TIMER_STARTTRANSFER); + if(data->req.exp100 > EXP100_SEND_DATA) + /* set time stamp to compare with when waiting for the 100 */ + data->req.start100 = Curl_now(); + } + + /* Here, we deal with REAL BODY bytes. All filtering and transfer + * encodings have been applied and only the true content, e.g. BODY, + * bytes are passed here. + * This allows us to check sizes, update stats, etc. independent + * from the protocol in play. */ + + if(data->req.no_body && nbytes > 0) { + /* BODY arrives although we want none, bail out */ + streamclose(data->conn, "ignoring body"); + DEBUGF(infof(data, "did not want a BODY, but seeing %zu bytes", + nbytes)); + data->req.download_done = TRUE; + return CURLE_WEIRD_SERVER_REPLY; + } + + /* Determine if we see any bytes in excess to what is allowed. + * We write the allowed bytes and handle excess further below. + * This gives deterministic BODY writes on varying buffer receive + * lengths. */ nwrite = nbytes; if(-1 != data->req.maxdownload) { size_t wmax = get_max_body_write_len(data, data->req.maxdownload); if(nwrite > wmax) { excess_len = nbytes - wmax; nwrite = wmax; - excess_data = buf + nwrite; } if(nwrite == wmax) { @@ -578,6 +602,8 @@ static CURLcode cw_download_write(struct Curl_easy *data, } } + /* Error on too large filesize is handled below, after writing + * the permitted bytes */ if(data->set.max_filesize) { size_t wmax = get_max_body_write_len(data, data->set.max_filesize); if(nwrite > wmax) { @@ -585,6 +611,7 @@ static CURLcode cw_download_write(struct Curl_easy *data, } } + /* Update stats, write and report progress */ data->req.bytecount += nwrite; ++data->req.bodywrites; if(!data->req.ignorebody && nwrite) { @@ -597,23 +624,7 @@ static CURLcode cw_download_write(struct Curl_easy *data, return result; if(excess_len) { - if(data->conn->handler->readwrite) { - /* RTSP hack moved from transfer loop to here */ - bool readmore = FALSE; /* indicates data is incomplete, need more */ - size_t consumed = 0; - result = data->conn->handler->readwrite(data, data->conn, - excess_data, excess_len, - &consumed, &readmore); - if(result) - return result; - DEBUGASSERT(consumed <= excess_len); - excess_len -= consumed; - if(readmore) { - data->req.download_done = FALSE; - data->req.keepon |= KEEP_RECV; /* we're not done reading */ - } - } - if(excess_len && !data->req.ignorebody) { + if(!data->req.ignorebody) { infof(data, "Excess found writing body:" " excess = %zu" @@ -762,6 +773,21 @@ CURLcode Curl_cwriter_add(struct Curl_easy *data, return CURLE_OK; } +void Curl_cwriter_remove_by_name(struct Curl_easy *data, + const char *name) +{ + struct Curl_cwriter **anchor = &data->req.writer_stack; + + while(*anchor) { + if(!strcmp(name, (*anchor)->cwt->name)) { + struct Curl_cwriter *w = (*anchor); + *anchor = w->next; + Curl_cwriter_free(data, w); + continue; + } + anchor = &((*anchor)->next); + } +} /* * Internal read-from-socket function. This is meant to deal with plain diff --git a/lib/sendf.h b/lib/sendf.h index a70189f2f5e..7deae2ac3ca 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -49,6 +49,7 @@ #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 */ +#define CLIENTWRITE_EOS (1<<7) /* End Of transfer download Stream */ /** * Write `len` bytes at `prt` to the client. `type` indicates what @@ -147,6 +148,9 @@ size_t Curl_cwriter_count(struct Curl_easy *data, Curl_cwriter_phase phase); CURLcode Curl_cwriter_add(struct Curl_easy *data, struct Curl_cwriter *writer); +void Curl_cwriter_remove_by_name(struct Curl_easy *data, + const char *name); + /** * Convenience method for calling `writer->do_write()` that * checks for NULL writer. diff --git a/lib/smb.c b/lib/smb.c index 6c8a47c7fd9..1d1867cc270 100644 --- a/lib/smb.c +++ b/lib/smb.c @@ -272,7 +272,7 @@ const struct Curl_handler Curl_handler_smb = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ smb_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_SMB, /* defport */ @@ -299,7 +299,7 @@ const struct Curl_handler Curl_handler_smbs = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ smb_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_SMBS, /* defport */ diff --git a/lib/smtp.c b/lib/smtp.c index 8eddf8a9895..db1a96b31c9 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -130,7 +130,7 @@ const struct Curl_handler Curl_handler_smtp = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ smtp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_SMTP, /* defport */ @@ -159,7 +159,7 @@ const struct Curl_handler Curl_handler_smtps = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ smtp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_SMTPS, /* defport */ diff --git a/lib/telnet.c b/lib/telnet.c index b626bc56e53..040554107f7 100644 --- a/lib/telnet.c +++ b/lib/telnet.c @@ -186,7 +186,7 @@ const struct Curl_handler Curl_handler_telnet = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_TELNET, /* defport */ diff --git a/lib/tftp.c b/lib/tftp.c index 663015502d7..4288110da66 100644 --- a/lib/tftp.c +++ b/lib/tftp.c @@ -181,7 +181,7 @@ const struct Curl_handler Curl_handler_tftp = { ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ tftp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_TFTP, /* defport */ diff --git a/lib/transfer.c b/lib/transfer.c index 0d7226c8a5e..4040cc3eedd 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -413,23 +413,64 @@ bool Curl_meets_timecondition(struct Curl_easy *data, time_t timeofdoc) return TRUE; } +/** + * Receive raw response data for the transfer. + * @param data the transfer + * @param buf buffer to keep response data received + * @param blen length of `buf` + * @param eos_reliable if EOS detection in underlying connection is reliable + * @param err error code in case of -1 return + * @return number of bytes read or -1 for error + */ +static ssize_t Curl_xfer_recv_resp(struct Curl_easy *data, + char *buf, size_t blen, + bool eos_reliable, + CURLcode *err) +{ + ssize_t nread; + + DEBUGASSERT(blen > 0); + /* If we are reading BODY data and the connection does NOT handle EOF + * and we know the size of the BODY data, limit the read amount */ + if(!eos_reliable && !data->req.header && data->req.size != -1) { + curl_off_t totalleft = data->req.size - data->req.bytecount; + if(totalleft <= 0) + blen = 0; + else if(totalleft < (curl_off_t)blen) + blen = (size_t)totalleft; + } + + if(!blen) { + /* want nothing - continue as if read nothing. */ + DEBUGF(infof(data, "readwrite_data: we're done")); + *err = CURLE_OK; + return 0; + } + + *err = Curl_read(data, data->conn->sockfd, buf, blen, &nread); + if(*err) + return -1; + DEBUGASSERT(nread >= 0); + *err = CURLE_OK; + return nread; +} + /* * Go ahead and do a read if we have a readable socket or if * the stream was rewound (in which case we have data in a * buffer) */ static CURLcode readwrite_data(struct Curl_easy *data, - struct connectdata *conn, struct SingleRequest *k, int *didwhat, bool *done) { + struct connectdata *conn = data->conn; CURLcode result = CURLE_OK; char *buf; size_t blen; - size_t consumed; int maxloops = 10; curl_off_t total_received = 0; - bool data_eof_handled = FALSE; + bool is_multiplex = FALSE; DEBUGASSERT(data->state.buffer); *done = FALSE; @@ -437,290 +478,72 @@ static CURLcode readwrite_data(struct Curl_easy *data, /* This is where we loop until we have read everything there is to read or we get a CURLE_AGAIN */ do { - bool is_empty_data = FALSE; - size_t bytestoread = data->set.buffer_size; - - /* For HTTP/2 and HTTP/3, read data without caring about the content - length. This is safe because body in HTTP/2 is always segmented - thanks to its framing layer. Meanwhile, we have to call Curl_read - to ensure that http2_handle_stream_close is called when we read all - incoming bytes for a particular stream. */ - bool is_http3 = Curl_conn_is_http3(data, conn, FIRSTSOCKET); - data_eof_handled = is_http3 || Curl_conn_is_http2(data, conn, FIRSTSOCKET); - - if(data->set.max_recv_speed) { - /* Limit the amount we read here, break on reaching it */ - curl_off_t net_limit = data->set.max_recv_speed - total_received; - if(net_limit <= 0) - break; - if((size_t)net_limit < bytestoread) - bytestoread = (size_t)net_limit; + bool is_eos = FALSE; + size_t bytestoread; + ssize_t nread; + + if(!is_multiplex) { + /* Multiplexed connection have inherent handling of EOF and we do not + * have to carefully restrict the amount we try to read. + * Multiplexed changes only in one direction. */ + is_multiplex = Curl_conn_is_multiplex(conn, FIRSTSOCKET); } - /* Each loop iteration starts with a fresh buffer and handles - * all data read into it. */ buf = data->state.buffer; blen = 0; + bytestoread = data->set.buffer_size; - /* If we are reading BODY data and the connection does NOT handle EOF - * and we know the size of the BODY data, limit the read amount */ - if(!k->header && !data_eof_handled && k->size != -1) { - curl_off_t totalleft = k->size - k->bytecount; - if(totalleft <= 0) - bytestoread = 0; - else if(totalleft < (curl_off_t)bytestoread) - bytestoread = (size_t)totalleft; + /* Observe any imposed speed limit */ + if(bytestoread && data->set.max_recv_speed) { + curl_off_t net_limit = data->set.max_recv_speed - total_received; + if(net_limit <= 0) + break; + if((size_t)net_limit < bytestoread) + bytestoread = (size_t)net_limit; } - if(bytestoread) { - /* receive data from the network! */ - ssize_t nread; /* number of bytes read */ - result = Curl_read(data, conn->sockfd, buf, bytestoread, &nread); + nread = Curl_xfer_recv_resp(data, buf, bytestoread, + is_multiplex, &result); + if(nread < 0) { if(CURLE_AGAIN == result) { result = CURLE_OK; break; /* get out of loop */ } - else if(result) - goto out; - DEBUGASSERT(nread >= 0); - blen = (size_t)nread; - } - else { - /* read nothing but since we wanted nothing we consider this an OK - situation to proceed from */ - DEBUGF(infof(data, "readwrite_data: we're done")); - } - - if(!k->bytecount) { - Curl_pgrsTime(data, TIMER_STARTTRANSFER); - if(k->exp100 > EXP100_SEND_DATA) - /* set time stamp to compare with when waiting for the 100 */ - k->start100 = Curl_now(); + goto out; /* real error */ } + /* We only get a 0-length read on EndOfStream */ + blen = (size_t)nread; + is_eos = (blen == 0); *didwhat |= KEEP_RECV; - /* indicates data of zero size, i.e. empty file */ - is_empty_data = ((blen == 0) && (k->bodywrites == 0)) ? TRUE : FALSE; - - if(0 < blen || is_empty_data) { - /* data->state.buffer is allocated 1 byte larger than - * data->set.buffer_size admits. *wink* */ - /* TODO: we should really not rely on this being 0-terminated, since - * the actual data read might contain 0s. */ - buf[blen] = 0; - } if(!blen) { /* if we receive 0 or less here, either the data transfer is done or the server closed the connection and we bail out from this! */ - if(data_eof_handled) + if(is_multiplex) DEBUGF(infof(data, "nread == 0, stream closed, bailing")); else DEBUGF(infof(data, "nread <= 0, server closed connection, bailing")); - k->keepon = 0; /* stop sending as well */ - if(!is_empty_data) - break; - } - - if(conn->handler->readwrite) { - bool readmore = FALSE; /* indicates data is incomplete, need more */ - consumed = 0; - result = conn->handler->readwrite(data, conn, buf, blen, - &consumed, &readmore); - if(result) - goto out; - if(readmore) - break; - buf += consumed; - blen -= consumed; - if(k->download_done) { - /* We've stopped dealing with input, get out of the do-while loop */ - if(blen > 0) { - infof(data, - "Excess found:" - " excess = %zu" - " url = %s (zero-length body)", - blen, data->state.up.path); - } - - /* we make sure that this socket isn't read more now */ - k->keepon &= ~KEEP_RECV; + if(k->eos_written) { /* already did write this to client, leave */ + k->keepon = 0; /* stop sending as well */ break; } } + total_received += blen; -#ifndef CURL_DISABLE_HTTP - /* Since this is a two-state thing, we check if we are parsing - headers at the moment or not. */ - if(k->header) { - consumed = 0; - result = Curl_http_readwrite_headers(data, conn, buf, blen, &consumed); - if(result) - goto out; - buf += consumed; - blen -= consumed; - - if(conn->handler->readwrite && - (k->maxdownload <= 0 && blen > 0)) { - bool readmore = FALSE; /* indicates data is incomplete, need more */ - consumed = 0; - result = conn->handler->readwrite(data, conn, buf, blen, - &consumed, &readmore); - if(result) - goto out; - if(readmore) - break; - buf += consumed; - blen -= consumed; - } - - if(k->download_done) { - /* We've stopped dealing with input, get out of the do-while loop */ - if(blen > 0) { - infof(data, - "Excess found:" - " excess = %zu" - " url = %s (zero-length body)", - blen, data->state.up.path); - } - - /* we make sure that this socket isn't read more now */ - k->keepon &= ~KEEP_RECV; - break; - } - } -#endif /* CURL_DISABLE_HTTP */ - - - /* This is not an 'else if' since it may be a rest from the header - parsing, where the beginning of the buffer is headers and the end - is non-headers. */ - if(!k->header && (blen > 0 || is_empty_data)) { - - if(data->req.no_body && blen > 0) { - /* data arrives although we want none, bail out */ - streamclose(conn, "ignoring body"); - DEBUGF(infof(data, "did not want a BODY, but seeing %zu bytes", - blen)); - *done = TRUE; - result = CURLE_WEIRD_SERVER_REPLY; - goto out; - } - -#ifndef CURL_DISABLE_HTTP - if(0 == k->bodywrites && !is_empty_data) { - /* These checks are only made the first time we are about to - write a piece of the body */ - if(conn->handler->protocol&(PROTO_FAMILY_HTTP|CURLPROTO_RTSP)) { - /* HTTP-only checks */ - result = Curl_http_firstwrite(data, conn, done); - if(result || *done) - goto out; - } - } /* this is the first time we write a body part */ -#endif /* CURL_DISABLE_HTTP */ - -#ifndef CURL_DISABLE_HTTP - if(k->chunk) { - /* - * Here comes a chunked transfer flying and we need to decode this - * properly. While the name says read, this function both reads - * and writes away the data. - */ - CURLcode extra; - CHUNKcode res; - - consumed = 0; - res = Curl_httpchunk_read(data, buf, blen, &consumed, &extra); - - if(CHUNKE_OK < res) { - if(CHUNKE_PASSTHRU_ERROR == res) { - failf(data, "Failed reading the chunked-encoded stream"); - result = extra; - goto out; - } - failf(data, "%s in chunked-encoding", Curl_chunked_strerror(res)); - result = CURLE_RECV_ERROR; - goto out; - } - - buf += consumed; - blen -= consumed; - if(CHUNKE_STOP == res) { - /* we're done reading chunks! */ - k->keepon &= ~KEEP_RECV; /* read no more */ - /* chunks read successfully, download is complete */ - k->download_done = TRUE; - - /* N number of bytes at the end of the str buffer that weren't - written to the client. */ - if(conn->chunk.datasize) { - infof(data, "Leftovers after chunking: % " - CURL_FORMAT_CURL_OFF_T "u bytes", - conn->chunk.datasize); - } - } - /* If it returned OK, we just keep going */ - } -#endif /* CURL_DISABLE_HTTP */ - - total_received += blen; - - if(!k->chunk && (blen || k->badheader || is_empty_data)) { - /* If this is chunky transfer, it was already written */ - - if(k->badheader) { - /* we parsed a piece of data wrongly assuming it was a header - and now we output it as body instead */ - size_t headlen = Curl_dyn_len(&data->state.headerb); - - /* Don't let excess data pollute body writes */ - if(k->maxdownload != -1 && (curl_off_t)headlen > k->maxdownload) - headlen = (size_t)k->maxdownload; - - result = Curl_client_write(data, CLIENTWRITE_BODY, - Curl_dyn_ptr(&data->state.headerb), - headlen); - if(result) - goto out; - } - - if(blen) { -#ifndef CURL_DISABLE_POP3 - if(conn->handler->protocol & PROTO_FAMILY_POP3) { - result = k->ignorebody? CURLE_OK : - Curl_pop3_write(data, buf, blen); - } - else -#endif /* CURL_DISABLE_POP3 */ - result = Curl_client_write(data, CLIENTWRITE_BODY, buf, blen); - } - k->badheader = FALSE; /* taken care of now */ - - if(result) - goto out; - } - - if(k->download_done && !is_http3) { - /* HTTP/3 over QUIC should keep reading until QUIC connection - is closed. In contrast to HTTP/2 which can stop reading - from TCP connection, HTTP/3 over QUIC needs ACK from server - to ensure stream closure. It should keep reading. */ - k->keepon &= ~KEEP_RECV; /* we're done reading */ - } - } /* if(!header and data to read) */ + result = Curl_xfer_write_resp(data, buf, blen, is_eos, done); + if(result || *done) + goto out; - if(is_empty_data) { - /* if we received nothing, the server closed the connection and we - are done */ - k->keepon &= ~KEEP_RECV; - k->download_done = TRUE; + /* if we are done, we stop receiving. On multiplexed connections, + * we should read the EOS. Which may arrive as meta data after + * the bytes. Not taking it in might lead to RST of streams. */ + if((!is_multiplex && data->req.download_done) || is_eos) { + data->req.keepon &= ~KEEP_RECV; } - - if((k->keepon & KEEP_RECV_PAUSE) || !(k->keepon & KEEP_RECV)) { - /* this is a paused or stopped transfer */ + /* if we are PAUSEd or stopped receiving, leave the loop */ + if((k->keepon & KEEP_RECV_PAUSE) || !(k->keepon & KEEP_RECV)) break; - } } while(maxloops-- && data_pending(data)); @@ -732,7 +555,7 @@ static CURLcode readwrite_data(struct Curl_easy *data, } if(((k->keepon & (KEEP_RECV|KEEP_SEND)) == KEEP_SEND) && - (conn->bits.close || data_eof_handled)) { + (conn->bits.close || is_multiplex)) { /* When we've read the entire thing and the close bit is set, the server may now close the connection. If there's now any kind of sending going on from our side, we need to stop that immediately. */ @@ -1038,10 +861,10 @@ static int select_bits_paused(struct Curl_easy *data, int select_bits) * Curl_readwrite() is the low-level function to be called when data is to * be read and written to/from the connection. */ -CURLcode Curl_readwrite(struct connectdata *conn, - struct Curl_easy *data, +CURLcode Curl_readwrite(struct Curl_easy *data, bool *done) { + struct connectdata *conn = data->conn; struct SingleRequest *k = &data->req; CURLcode result; struct curltime now; @@ -1095,7 +918,7 @@ CURLcode Curl_readwrite(struct connectdata *conn, the stream was rewound (in which case we have data in a buffer) */ if((k->keepon & KEEP_RECV) && (select_bits & CURL_CSELECT_IN)) { - result = readwrite_data(data, conn, k, &didwhat, done); + result = readwrite_data(data, k, &didwhat, done); if(result || *done) goto out; } @@ -1191,21 +1014,6 @@ CURLcode Curl_readwrite(struct connectdata *conn, result = CURLE_PARTIAL_FILE; goto out; } - if(!(data->req.no_body) && k->chunk && - (conn->chunk.state != CHUNK_STOP)) { - /* - * In chunked mode, return an error if the connection is closed prior to - * the empty (terminating) chunk is read. - * - * The condition above used to check for - * conn->proto.http->chunk.datasize != 0 which is true after reading - * *any* chunk, not just the empty chunk. - * - */ - failf(data, "transfer closed with outstanding read data remaining"); - result = CURLE_PARTIAL_FILE; - goto out; - } if(Curl_pgrsUpdate(data)) { result = CURLE_ABORTED_BY_CALLBACK; goto out; @@ -1866,3 +1674,41 @@ Curl_setup_transfer( } /* if(k->getheader || !data->req.no_body) */ } + +CURLcode Curl_xfer_write_resp(struct Curl_easy *data, + char *buf, size_t blen, + bool is_eos, bool *done) +{ + CURLcode result = CURLE_OK; + + if(data->conn->handler->write_resp) { + /* protocol handlers offering this function take full responsibility + * for writing all received download data to the client. */ + result = data->conn->handler->write_resp(data, buf, blen, is_eos, done); + } + else { + /* No special handling by protocol handler, write all received data + * as BODY to the client. */ + if(blen || is_eos) { + int cwtype = CLIENTWRITE_BODY; + if(is_eos) + cwtype |= CLIENTWRITE_EOS; + +#ifndef CURL_DISABLE_POP3 + if(blen && data->conn->handler->protocol & PROTO_FAMILY_POP3) { + result = data->req.ignorebody? CURLE_OK : + Curl_pop3_write(data, buf, blen); + } + else +#endif /* CURL_DISABLE_POP3 */ + result = Curl_client_write(data, cwtype, buf, blen); + } + } + + if(!result && is_eos) { + /* If we wrote the EOS, we are definitely done */ + data->req.eos_written = TRUE; + data->req.download_done = TRUE; + } + return result; +} diff --git a/lib/transfer.h b/lib/transfer.h index b057c50d230..0507f1a45f7 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -45,8 +45,9 @@ typedef enum { CURLcode Curl_follow(struct Curl_easy *data, char *newurl, followtype type); -CURLcode Curl_readwrite(struct connectdata *conn, - struct Curl_easy *data, bool *done); +CURLcode Curl_readwrite(struct Curl_easy *data, bool *done); +int Curl_single_getsock(struct Curl_easy *data, + struct connectdata *conn, curl_socket_t *socks); CURLcode Curl_fillreadbuffer(struct Curl_easy *data, size_t bytes, size_t *nreadp); CURLcode Curl_retry_request(struct Curl_easy *data, char **url); @@ -56,6 +57,23 @@ CURLcode Curl_get_upload_buffer(struct Curl_easy *data); CURLcode Curl_done_sending(struct Curl_easy *data, struct SingleRequest *k); +/** + * Write the transfer raw response bytes, as received from the connection. + * Will handle all passed bytes or return an error. By default, this will + * write the bytes as BODY to the client. Protocols may provide a + * "write_resp" callback in their handler to add specific treatment. E.g. + * HTTP parses response headers and passes them differently to the client. + * @param data the transfer + * @param buf the raw response bytes + * @param blen the amount of bytes in `buf` + * @param is_eos TRUE iff the connection indicates this to be the last + * bytes of the response + * @param done on returnm, TRUE iff the response is complete + */ +CURLcode Curl_xfer_write_resp(struct Curl_easy *data, + char *buf, size_t blen, + bool is_eos, bool *done); + /* This sets up a forthcoming transfer */ void Curl_setup_transfer (struct Curl_easy *data, diff --git a/lib/url.c b/lib/url.c index e60020bc204..826f57caa66 100644 --- a/lib/url.c +++ b/lib/url.c @@ -592,9 +592,6 @@ static void conn_free(struct Curl_easy *data, struct connectdata *conn) Curl_safefree(conn->sasl_authzid); Curl_safefree(conn->options); Curl_safefree(conn->oauth_bearer); -#ifndef CURL_DISABLE_HTTP - Curl_dyn_free(&conn->trailer); -#endif Curl_safefree(conn->host.rawalloc); /* host name buffer */ Curl_safefree(conn->conn_to_host.rawalloc); /* host name buffer */ Curl_safefree(conn->hostname_resolve); diff --git a/lib/urldata.h b/lib/urldata.h index de192dadeaf..9dcccc7039b 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -683,7 +683,8 @@ struct SingleRequest { enum expect100 exp100; /* expect 100 continue state */ enum upgrade101 upgr101; /* 101 upgrade state */ - /* Content unencoding stack. See sec 3.5, RFC2616. */ + /* Client Writer stack, handles trasnfer- and content-encodings, protocol + * checks, pausing by client callbacks. */ struct Curl_cwriter *writer_stack; time_t timeofdoc; long bodywrites; @@ -730,11 +731,10 @@ struct SingleRequest { #ifndef CURL_DISABLE_COOKIES unsigned char setcookies; #endif - unsigned char writer_stack_depth; /* Unencoding stack depth. */ BIT(header); /* incoming data has HTTP header */ - BIT(badheader); /* header parsing found sth not a header */ BIT(content_range); /* set TRUE if Content-Range: was found */ BIT(download_done); /* set to TRUE when download is complete */ + BIT(eos_written); /* iff EOS has been written to client */ BIT(upload_done); /* set to TRUE when doing chunked transfer-encoding upload and we're uploading the last chunk */ BIT(ignorebody); /* we read a response-body but we ignore it! */ @@ -816,10 +816,10 @@ struct Curl_handler { bool dead_connection); /* If used, this function gets called from transfer.c:readwrite_data() to - allow the protocol to do extra reads/writes */ - CURLcode (*readwrite)(struct Curl_easy *data, struct connectdata *conn, - const char *buf, size_t blen, - size_t *pconsumed, bool *readmore); + allow the protocol to do extra handling in writing response to + the client. */ + CURLcode (*write_resp)(struct Curl_easy *data, const char *buf, size_t blen, + bool is_eos, bool *done); /* This function can perform various checks on the connection. See CONNCHECK_* for more information about the checks that can be performed, @@ -898,11 +898,6 @@ struct ldapconninfo; struct connectdata { struct Curl_llist_element bundle_node; /* conncache */ - /* chunk is for HTTP chunked encoding, but is in the general connectdata - struct only because we can do just about any protocol through an HTTP - proxy and an HTTP proxy may in fact respond using chunked encoding */ - struct Curl_chunker chunk; - curl_closesocket_callback fclosesocket; /* function closing the socket(s) */ void *closesocket_client; @@ -1025,11 +1020,6 @@ struct connectdata { struct negotiatedata proxyneg; /* state data for proxy Negotiate auth */ #endif -#ifndef CURL_DISABLE_HTTP - /* for chunked-encoded trailer */ - struct dynbuf trailer; -#endif - union { #ifndef CURL_DISABLE_FTP struct ftp_conn ftpc; diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index 18b3d67fb6a..4d77d6c7ab1 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -161,7 +161,7 @@ const struct Curl_handler Curl_handler_scp = { ZERO_NULL, /* domore_getsock */ myssh_getsock, /* perform_getsock */ scp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_SSH, /* defport */ @@ -188,7 +188,7 @@ const struct Curl_handler Curl_handler_sftp = { ZERO_NULL, /* domore_getsock */ myssh_getsock, /* perform_getsock */ sftp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_SSH, /* defport */ diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index a751d7cd3a7..fa24ac38c4d 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -138,7 +138,7 @@ const struct Curl_handler Curl_handler_scp = { ZERO_NULL, /* domore_getsock */ ssh_getsock, /* perform_getsock */ scp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ssh_attach, /* attach */ PORT_SSH, /* defport */ @@ -167,7 +167,7 @@ const struct Curl_handler Curl_handler_sftp = { ZERO_NULL, /* domore_getsock */ ssh_getsock, /* perform_getsock */ sftp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ssh_attach, /* attach */ PORT_SSH, /* defport */ diff --git a/lib/vssh/wolfssh.c b/lib/vssh/wolfssh.c index 368f163d1d7..b408d7d82fc 100644 --- a/lib/vssh/wolfssh.c +++ b/lib/vssh/wolfssh.c @@ -93,7 +93,7 @@ const struct Curl_handler Curl_handler_scp = { ZERO_NULL, /* domore_getsock */ wssh_getsock, /* perform_getsock */ wscp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_SSH, /* defport */ @@ -122,7 +122,7 @@ const struct Curl_handler Curl_handler_sftp = { ZERO_NULL, /* domore_getsock */ wssh_getsock, /* perform_getsock */ wsftp_disconnect, /* disconnect */ - ZERO_NULL, /* readwrite */ + ZERO_NULL, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_SSH, /* defport */ diff --git a/scripts/singleuse.pl b/scripts/singleuse.pl index b8a57f8d8d8..c4e1bed51ce 100755 --- a/scripts/singleuse.pl +++ b/scripts/singleuse.pl @@ -43,6 +43,7 @@ my %wl = ( 'curlx_uztoso' => 'cmdline tool use', + 'Curl_xfer_write_resp' => 'internal api', ); my %api = ( diff --git a/tests/libtest/lib568.c b/tests/libtest/lib568.c index 97304fa58aa..04452749959 100644 --- a/tests/libtest/lib568.c +++ b/tests/libtest/lib568.c @@ -93,6 +93,7 @@ int test(char *URL) test_setopt(curl, CURLOPT_READDATA, sdpf); test_setopt(curl, CURLOPT_UPLOAD, 1L); test_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t) file_info.st_size); + test_setopt(curl, CURLOPT_VERBOSE, 1L); /* Do the ANNOUNCE */ res = curl_easy_perform(curl); From adfffc39a3547c5619b8bca45f651745dc4343c8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 13 Jan 2024 23:42:19 +0100 Subject: [PATCH 168/509] transfer: remove warning: Value stored to 'blen' is never read Detected by scan-build Follow-up from 1cd2f0072f Closes #12693 --- lib/transfer.c | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/transfer.c b/lib/transfer.c index 4040cc3eedd..1d066fbf889 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -490,7 +490,6 @@ static CURLcode readwrite_data(struct Curl_easy *data, } buf = data->state.buffer; - blen = 0; bytestoread = data->set.buffer_size; /* Observe any imposed speed limit */ From 3167dab0d51d2596b14422f2a34d6b6cdea43ff3 Mon Sep 17 00:00:00 2001 From: Mark Huang Date: Sun, 14 Jan 2024 16:56:00 +0800 Subject: [PATCH 169/509] docs/cmdline: remove unnecessary line breaks Closes #12696 --- docs/cmdline-opts/connect-to.d | 1 - docs/cmdline-opts/tcp-fastopen.d | 1 - 2 files changed, 2 deletions(-) diff --git a/docs/cmdline-opts/connect-to.d b/docs/cmdline-opts/connect-to.d index 95fab91121b..f7da551592d 100644 --- a/docs/cmdline-opts/connect-to.d +++ b/docs/cmdline-opts/connect-to.d @@ -9,7 +9,6 @@ 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 diff --git a/docs/cmdline-opts/tcp-fastopen.d b/docs/cmdline-opts/tcp-fastopen.d index bcf1edbff50..d3aa8dca20b 100644 --- a/docs/cmdline-opts/tcp-fastopen.d +++ b/docs/cmdline-opts/tcp-fastopen.d @@ -8,7 +8,6 @@ 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. From beb2283746878a0a0bbed042abdd90bdd4d35e0f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 13 Jan 2024 23:18:20 +0100 Subject: [PATCH 170/509] curl_multi_fdset.3: remove mention of null pointer support ... since this funtion has not supported null pointer fd_set arguments since at least 2006. (That's when I stopped my git blame journey) Fixes #12691 Reported-by: sfan5 on github Closes #12692 --- docs/libcurl/curl_multi_fdset.3 | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 8a3ae965a65..0afbe9a3ccf 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -42,17 +42,17 @@ select() on, but be sure to \fIFD_ZERO\fP them before calling this function as otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should be called as soon as one of them is ready to be read from or written to. -If the \fIread_fd_set\fP argument is not a null pointer, it points to an -object of type \fBfd_set\fP that on returns specifies the file descriptors to -be checked for being ready to read. +The \fIread_fd_set\fP argument should point to an object of type \fBfd_set\fP +that on returns specifies the file descriptors to be checked for being ready +to read. -If the \fIwrite_fd_set\fP argument is not a null pointer, it points to an -object of type \fBfd_set\fP that on return specifies the file descriptors to -be checked for being ready to write. +The \fIwrite_fd_set\fP argument should point to an object of type \fBfd_set\fP +that on return specifies the file descriptors to be checked for being ready to +write. -If the \fIexc_fd_set\fP argument is not a null pointer, it points to an object -of type \fBfd_set\fP that on return specifies the file descriptors to be -checked for error conditions pending. +The \fIexc_fd_set\fP argument should point to an object of type \fBfd_set\fP +that on return specifies the file descriptors to be checked for error +conditions. If no file descriptors are set by libcurl, \fImax_fd\fP contain -1 when this function returns. Otherwise it contains the highest descriptor number libcurl From e186ca6534a21b391550a160b8b15f28d60fda37 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 14 Jan 2024 14:42:08 +0100 Subject: [PATCH 171/509] cf-h1-proxy: no CURLOPT_USERAGENT in CONNECT with hyper Follow-up to 693cd1679361828a which was incomplete Ref #12680 Closes #12697 --- lib/cf-h1-proxy.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index 2d2d8580921..167e5315a84 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -725,7 +725,7 @@ static CURLcode start_CONNECT(struct Curl_cfilter *cf, } if(!Curl_checkProxyheaders(data, conn, STRCONST("User-Agent")) && - data->set.str[STRING_USERAGENT]) { + data->set.str[STRING_USERAGENT] && *data->set.str[STRING_USERAGENT]) { struct dynbuf ua; Curl_dyn_init(&ua, DYN_HTTP_REQUEST); result = Curl_dyn_addf(&ua, "User-Agent: %s\r\n", From aaab6cb0c4a6795dac5d8a0d89c4be4fda11a926 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 14 Jan 2024 14:50:52 +0100 Subject: [PATCH 172/509] cmdline-opts/gen.pl: error on initital blank line After the "---" separator, there should be no blank line and this script now errors out if one is detected. Ref: #12696 Closes #12698 --- docs/cmdline-opts/gen.pl | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index b31a42b580f..2766ca265bd 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -219,6 +219,7 @@ sub single { my @examples; # there can be more than one my $magic; # cmdline special option my $line; + my $dline; my $multi; my $scope; my $experimental; @@ -322,6 +323,11 @@ sub single { my $tablemode = 0; while() { $line++; + $dline++; + if(($dline == 1) && ($_ =~ /^[\r\n]*\z/)) { + print STDERR "$f:$line:1:ERROR: unnecessary leading blank line\n"; + return 3; + } if(/^## (.*)/) { if(!$tablemode) { push @desc, ".RS\n"; @@ -341,6 +347,7 @@ sub single { elsif(/^\.(IP|RS|RE)/) { my ($cmd) = ($1); print STDERR "$f:$line:1:ERROR: $cmd detected, use ##-style\n"; + return 3; } push @desc, $_; } From e3b386f86f1b841aeb62d144dfbb0c8ad8a5c7d5 Mon Sep 17 00:00:00 2001 From: bch Date: Fri, 12 Jan 2024 13:54:40 -0800 Subject: [PATCH 173/509] curl.h: CURLOPT_DNS_SERVERS is only available with c-ares Closes #12695 --- include/curl/curl.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/curl/curl.h b/include/curl/curl.h index b35ac95553e..eb06022501c 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -1846,7 +1846,8 @@ typedef enum { /* allow GSSAPI credential delegation */ CURLOPT(CURLOPT_GSSAPI_DELEGATION, CURLOPTTYPE_VALUES, 210), - /* Set the name servers to use for DNS resolution */ + /* Set the name servers to use for DNS resolution. + * Only supported by the c-ares DNS backend */ CURLOPT(CURLOPT_DNS_SERVERS, CURLOPTTYPE_STRINGPOINT, 211), /* Time-out accept operations (currently for FTP only) after this amount From 72bd88adde0e8cf6e63644a7d6df1da01a399db4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 14 Jan 2024 17:54:51 +0100 Subject: [PATCH 174/509] version: show only the libpsl version, not its dependencies The libpsl version output otherwise also includes version number for its dependencies, like IDN lib, but since libcurl does not use libpsl's IDN functionality those components are not important. Ref: https://github.com/curl/curl-for-win/issues/63 Closes #12700 --- lib/version.c | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/lib/version.c b/lib/version.c index f957f085d8e..01c2a315e5c 100644 --- a/lib/version.c +++ b/lib/version.c @@ -211,8 +211,12 @@ char *curl_version(void) #endif #ifdef USE_LIBPSL - msnprintf(psl_version, sizeof(psl_version), "libpsl/%s", psl_get_version()); - src[i++] = psl_version; + { + int num = psl_check_version_number(0); + msnprintf(psl_version, sizeof(psl_version), "libpsl/%d.%d.%d", + num >> 16, (num >> 8) & 0xff, num & 0xff); + src[i++] = psl_version; + } #endif #ifdef USE_SSH From 036eb150d185be26ba644a47078e19967403cb19 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 15 Jan 2024 11:33:13 +0100 Subject: [PATCH 175/509] rtsp: deal with borked server responses - enforce a response body length of 0, if the response has no Content-lenght. This is according to the RTSP spec. - excess bytes in a response body are forwarded to the client writers which will report and fail the transfer Follow-up to d7b6ce6 Fixes #12701 Closes #12706 --- lib/rtsp.c | 24 ++++++++++--------- tests/data/Makefile.inc | 2 +- tests/data/test689 | 53 +++++++++++++++++++++++++++++++++++++++++ tests/libtest/lib567.c | 1 + 4 files changed, 68 insertions(+), 12 deletions(-) create mode 100644 tests/data/test689 diff --git a/lib/rtsp.c b/lib/rtsp.c index c911bb6b22a..dba8ae7a67b 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -822,11 +822,10 @@ static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, if(!rtspc->in_header) { /* If header parsing is done, extract interleaved RTP messages */ - if((data->set.rtspreq == RTSPREQ_DESCRIBE) && (data->req.size <= -1)) { + if(data->req.size <= -1) { /* Respect section 4.4 of rfc2326: If the Content-Length header is - absent, a length 0 must be assumed. It will prevent libcurl from - hanging on DESCRIBE request that got refused for whatever - reason */ + absent, a length 0 must be assumed. */ + data->req.size = 0; data->req.download_done = TRUE; } result = rtsp_filter_rtp(data, buf, blen, &consumed); @@ -838,13 +837,16 @@ static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, if(rtspc->state != RTP_PARSE_SKIP) *done = FALSE; - /* we MUST have consumed all bytes */ - DEBUGF(infof(data, "rtsp_rtp_write_resp(len=%zu, in_header=%d, done=%d)", - blen, rtspc->in_header, *done)); - DEBUGASSERT(blen == 0); - if(!result && is_eos) { - result = Curl_client_write(data, CLIENTWRITE_BODY|CLIENTWRITE_EOS, - (char *)buf, 0); + /* we SHOULD have consumed all bytes, unless the response is borked. + * In which case we write out the left over bytes, letting the client + * writer deal with it (it will report EXCESS and fail the transfer). */ + DEBUGF(infof(data, "rtsp_rtp_write_resp(len=%zu, in_header=%d, done=%d " + " rtspc->state=%d, req.size=%" CURL_FORMAT_CURL_OFF_T ")", + blen, rtspc->in_header, *done, rtspc->state, data->req.size)); + if(!result && (is_eos || blen)) { + result = Curl_client_write(data, CLIENTWRITE_BODY| + (is_eos? CLIENTWRITE_EOS:0), + (char *)buf, blen); } out: diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 5008b86e011..ab66fc4cc4c 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -96,7 +96,7 @@ test644 test645 test646 test647 test648 test649 test650 test651 test652 \ test653 test654 test655 test656 test658 test659 test660 test661 test662 \ test663 test664 test665 test666 test667 test668 test669 test670 test671 \ test672 test673 test674 test675 test676 test677 test678 test679 test680 \ -test681 test682 test683 test684 test685 test686 test687 test688 \ +test681 test682 test683 test684 test685 test686 test687 test688 test689 \ \ test700 test701 test702 test703 test704 test705 test706 test707 test708 \ test709 test710 test711 test712 test713 test714 test715 test716 test717 \ diff --git a/tests/data/test689 b/tests/data/test689 new file mode 100644 index 00000000000..821556decfa --- /dev/null +++ b/tests/data/test689 @@ -0,0 +1,53 @@ + + +#Informational + + +RTSP +OPTIONS + + + +# Server-side + + +RTSP/7.1 786 + +RTSP/ + + + + + +# Client-Side + + +rtsp + + +lib567 + + + +fuzzing crash issue #12701 + + +rtsp://%HOSTIP:%RTSPPORT/%TESTNUMBER + + + + + +OPTIONS rtsp://%HOSTIP:%RTSPPORT/%TESTNUMBER RTSP/1.0 +CSeq: 1 +User-Agent: test567 +Test-Number: 567 + + +# 8 == CURLE_WEIRD_SERVER_REPLY + +8 + + + + diff --git a/tests/libtest/lib567.c b/tests/libtest/lib567.c index 00937e71d67..a912b1663ac 100644 --- a/tests/libtest/lib567.c +++ b/tests/libtest/lib567.c @@ -49,6 +49,7 @@ int test(char *URL) /* Dump data to stdout for protocol verification */ test_setopt(curl, CURLOPT_HEADERDATA, stdout); test_setopt(curl, CURLOPT_WRITEDATA, stdout); + test_setopt(curl, CURLOPT_VERBOSE, 1L); test_setopt(curl, CURLOPT_URL, URL); test_setopt(curl, CURLOPT_RTSP_STREAM_URI, URL); From ba01cac39b47906802be22cd2230555f8f7cac79 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Jan 2024 16:28:04 +0100 Subject: [PATCH 176/509] tool_operate: stop setting the file comment on Amiga - the URL is capped at 80 cols, which ruins it if longer - it does not strip off URL credentials - it is done unconditonally, not on --xattr - we don't have Amiga in the CI which makes fixing it blindly fragile Someone who builds and tests on Amiga can add it back correctly in a future if there is a desire. Reported-by: Harry Sintonen Closes #12709 --- src/tool_operate.c | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/src/tool_operate.c b/src/tool_operate.c index 3fe5b511654..1ffd6730ec8 100644 --- a/src/tool_operate.c +++ b/src/tool_operate.c @@ -343,22 +343,6 @@ static CURLcode pre_transfer(struct GlobalConfig *global, return result; } -#ifdef __AMIGA__ -static void AmigaSetComment(struct per_transfer *per, - CURLcode result) -{ - struct OutStruct *outs = &per->outs; - if(!result && outs->s_isreg && outs->filename) { - /* Set the url (up to 80 chars) as comment for the file */ - if(strlen(per->this_url) > 78) - per->this_url[79] = '\0'; - SetComment(outs->filename, per->this_url); - } -} -#else -#define AmigaSetComment(x,y) Curl_nop_stmt -#endif - /* When doing serial transfers, we use a single fixed error area */ static char global_errorbuffer[CURL_ERROR_SIZE]; @@ -658,8 +642,6 @@ static CURLcode post_per_transfer(struct GlobalConfig *global, } } - AmigaSetComment(per, result); - /* File time can only be set _after_ the file has been closed */ if(!result && config->remote_time && outs->s_isreg && outs->filename) { /* Ask libcurl if we got a remote file time */ From 4224d6e0f3cc8ddf2e9e1aa82c356d9b88b53e43 Mon Sep 17 00:00:00 2001 From: Lin Sun Date: Mon, 15 Jan 2024 06:58:09 +0000 Subject: [PATCH 177/509] asyn-ares: with modern c-ares, use its default timeout Closes #12703 --- lib/asyn-ares.c | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/lib/asyn-ares.c b/lib/asyn-ares.c index f1ff49277c4..76efba78ad5 100644 --- a/lib/asyn-ares.c +++ b/lib/asyn-ares.c @@ -173,10 +173,26 @@ CURLcode Curl_resolver_init(struct Curl_easy *easy, void **resolver) int status; struct ares_options options; int optmask = ARES_OPT_SOCK_STATE_CB; + static int ares_ver = 0; options.sock_state_cb = sock_state_cb; options.sock_state_cb_data = easy; - options.timeout = CARES_TIMEOUT_PER_ATTEMPT; - optmask |= ARES_OPT_TIMEOUTMS; + if(ares_ver == 0) + ares_version(&ares_ver); + + if(ares_ver < 0x011400) { /* c-ares included similar change since 1.20.0 */ + options.timeout = CARES_TIMEOUT_PER_ATTEMPT; + optmask |= ARES_OPT_TIMEOUTMS; + } + + /* + if c ares < 1.20.0: curl set timeout to CARES_TIMEOUT_PER_ATTEMPT (2s) + + if c-ares >= 1.20.0 it already has the timeout to 2s, curl does not need + to set the timeout value; + + if c-ares >= 1.24.0, user can set the timeout via /etc/resolv.conf to + overwrite c-ares' timeout. + */ status = ares_init_options((ares_channel*)resolver, &options, optmask); if(status != ARES_SUCCESS) { From c5801a28c5592d8569339eb29b0a65bc2cc6d7b3 Mon Sep 17 00:00:00 2001 From: Jay Wu Date: Mon, 15 Jan 2024 12:24:45 +0800 Subject: [PATCH 178/509] url: don't set default CA paths for Secure Transport backend As the default for this backend is the native CA store. Closes #12704 --- lib/url.c | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/lib/url.c b/lib/url.c index 826f57caa66..36395a155fd 100644 --- a/lib/url.c +++ b/lib/url.c @@ -434,11 +434,13 @@ CURLcode Curl_init_userdefined(struct Curl_easy *data) /* Set the default CA cert bundle/path detected/specified at build time. * - * If Schannel is the selected SSL backend then these locations are - * ignored. We allow setting CA location for schannel only when explicitly - * specified by the user via CURLOPT_CAINFO / --cacert. + * If Schannel or SecureTransport is the selected SSL backend then these + * locations are ignored. We allow setting CA location for schannel and + * securetransport when explicitly specified by the user via + * CURLOPT_CAINFO / --cacert. */ - if(Curl_ssl_backend() != CURLSSLBACKEND_SCHANNEL) { + if(Curl_ssl_backend() != CURLSSLBACKEND_SCHANNEL && + Curl_ssl_backend() != CURLSSLBACKEND_SECURETRANSPORT) { #if defined(CURL_CA_BUNDLE) result = Curl_setstropt(&set->str[STRING_SSL_CAFILE], CURL_CA_BUNDLE); if(result) From ae9f01f336193047e4d370a18141ec7408f99c0b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Jan 2024 16:49:20 +0100 Subject: [PATCH 179/509] tool_operate: make --remove-on-error only remove "real" files Reported-by: Harry Sintonen Assisted-by: Dan Fandrich Closes #12710 --- docs/cmdline-opts/remove-on-error.d | 2 +- src/tool_operate.c | 13 +++++++++++-- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/cmdline-opts/remove-on-error.d b/docs/cmdline-opts/remove-on-error.d index 50b7b1b65cf..2b498bc9ec5 100644 --- a/docs/cmdline-opts/remove-on-error.d +++ b/docs/cmdline-opts/remove-on-error.d @@ -12,4 +12,4 @@ 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. +If the output is not a regular file, this option has no effect. diff --git a/src/tool_operate.c b/src/tool_operate.c index 1ffd6730ec8..ba811d77331 100644 --- a/src/tool_operate.c +++ b/src/tool_operate.c @@ -637,8 +637,17 @@ static CURLcode post_per_transfer(struct GlobalConfig *global, errorf(config->global, "curl: (%d) Failed writing body", result); } if(result && config->rm_partial) { - notef(global, "Removing output file: %s", outs->filename); - unlink(outs->filename); + struct_stat st; + if(!stat(outs->filename, &st) && + S_ISREG(st.st_mode)) { + if(!unlink(outs->filename)) + notef(global, "Removed output file: %s", outs->filename); + else + warnf(global, "Failed removing: %s", outs->filename); + } + else + warnf(global, "Skipping removal; not a regular file: %s", + outs->filename); } } From 9034a16d974a826e1ba8ef7262646a941bb79fb2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Jan 2024 23:39:55 +0100 Subject: [PATCH 180/509] docs: mention env vars not used by schannel Ref: #12704 Co-authored-by: Jay Satiro Closes #12711 --- docs/SSLCERTS.md | 6 +++--- docs/cmdline-opts/cacert.d | 6 +++--- docs/cmdline-opts/page-footer | 9 ++++++--- 3 files changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/SSLCERTS.md b/docs/SSLCERTS.md index 4094e2fec64..d10ce52916a 100644 --- a/docs/SSLCERTS.md +++ b/docs/SSLCERTS.md @@ -103,9 +103,9 @@ 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 diff --git a/docs/cmdline-opts/cacert.d b/docs/cmdline-opts/cacert.d index 5e4e74901e5..7b63f810bb0 100644 --- a/docs/cmdline-opts/cacert.d +++ b/docs/cmdline-opts/cacert.d @@ -15,9 +15,9 @@ 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. +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 diff --git a/docs/cmdline-opts/page-footer b/docs/cmdline-opts/page-footer index af41c94824a..ff56a5cdef8 100644 --- a/docs/cmdline-opts/page-footer +++ b/docs/cmdline-opts/page-footer @@ -49,7 +49,8 @@ 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. +If set, it is used as the --cacert value. This environment variable is ignored +if Schannel is used as the TLS backend. .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* @@ -74,9 +75,11 @@ 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. +If set, it is used as the --capath value. This environment variable is ignored +if Schannel is used as the TLS backend. .IP "SSL_CERT_FILE " -If set, it is used as the --cacert value. +If set, it is used as the --cacert value. This environment variable is ignored +if Schannel is used as the TLS backend. .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 From 49ca84144edf979007f50b2bb16e3c21319ccf3c Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 15 Jan 2024 13:02:34 +0100 Subject: [PATCH 181/509] websockets: check for negative payload lengths - in en- and decoding, check the websocket frame payload lengths for negative values (from curl_off_t) and error the operation in that case - add test 2307 to verify Closes #12707 --- lib/ws.c | 11 +++++++ tests/data/DISABLED | 2 ++ tests/data/Makefile.inc | 2 +- tests/data/test2307 | 71 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 tests/data/test2307 diff --git a/lib/ws.c b/lib/ws.c index 81b48180ccf..78c14046997 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -225,6 +225,10 @@ static CURLcode ws_dec_read_head(struct ws_decoder *dec, dec->payload_len = (dec->head[2] << 8) | dec->head[3]; break; case 10: + if(dec->head[2] > 127) { + failf(data, "WS: frame length longer than 64 signed not supported"); + return CURLE_RECV_ERROR; + } dec->payload_len = ((curl_off_t)dec->head[2] << 56) | (curl_off_t)dec->head[3] << 48 | (curl_off_t)dec->head[4] << 40 | @@ -410,6 +414,13 @@ static ssize_t ws_enc_write_head(struct Curl_easy *data, size_t hlen; ssize_t n; + if(payload_len < 0) { + failf(data, "WS: starting new frame with negative payload length %" + CURL_FORMAT_CURL_OFF_T, payload_len); + *err = CURLE_SEND_ERROR; + return -1; + } + if(enc->payload_remain > 0) { /* trying to write a new frame before the previous one is finished */ failf(data, "WS: starting new frame with %zd bytes from last one" diff --git a/tests/data/DISABLED b/tests/data/DISABLED index b077c67a0fc..a98dc856683 100644 --- a/tests/data/DISABLED +++ b/tests/data/DISABLED @@ -81,6 +81,8 @@ 2301 2302 2305 +# response body seem not to be handled by hyper +2307 %endif 2043 # The CRL test (313) doesn't work with rustls because rustls doesn't support diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index ab66fc4cc4c..64859632a11 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -244,7 +244,7 @@ test2100 \ \ test2200 test2201 test2202 test2203 test2204 test2205 \ \ -test2300 test2301 test2302 test2303 test2304 test2305 test2306 \ +test2300 test2301 test2302 test2303 test2304 test2305 test2306 test2307 \ \ test2400 test2401 test2402 test2403 test2404 \ \ diff --git a/tests/data/test2307 b/tests/data/test2307 new file mode 100644 index 00000000000..26b3309a8dc --- /dev/null +++ b/tests/data/test2307 @@ -0,0 +1,71 @@ + + + +WebSockets + + + +# +# Sends a PING with overlong payload + + +HTTP/1.1 101 Switching to WebSockets +Server: test-server/fake +Upgrade: websocket +Connection: Upgrade +Something: else +Sec-WebSocket-Accept: HkPsVga7+8LuxM4RGQ5p9tZHeYs= + +%hex[%19%7f%ff%30%30%30%30%30%30%30%30%30%30%30%30]hex% + +# allow upgrade + +upgrade + + + +# +# Client-side + +# require debug for the forced CURL_ENTROPY + +debug +ws +!hyper + + +http + + +WebSockets, overlong PING payload + + +lib2302 + + +ws://%HOSTIP:%HTTPPORT/%TESTNUMBER + + + +# +# PONG with no data and the 32 bit mask +# + + +GET /%TESTNUMBER HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +User-Agent: webbie-sox/3 +Accept: */* +Upgrade: websocket +Connection: Upgrade +Sec-WebSocket-Version: 13 +Sec-WebSocket-Key: NDMyMTUzMjE2MzIxNzMyMQ== + + + +# 23 == CURLE_WRITE_ERROR + +23 + + + From 3378d2bd0931433999ef4c0ca95040c394146484 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 16 Jan 2024 12:06:57 +0100 Subject: [PATCH 182/509] websockets: refactor decode chain - use client writer stack for decoding frames - move websocket protocol handler to ws.c Closes #12713 --- lib/http.c | 114 +++---------------- lib/http.h | 16 +-- lib/sendf.c | 7 -- lib/ws.c | 316 +++++++++++++++++++++++++++++++++++----------------- lib/ws.h | 13 ++- 5 files changed, 249 insertions(+), 217 deletions(-) diff --git a/lib/http.c b/lib/http.c index 14963ca0e4a..6cb0a10b80d 100644 --- a/lib/http.c +++ b/lib/http.c @@ -100,29 +100,14 @@ * Forward declarations. */ -static int http_getsock_do(struct Curl_easy *data, - struct connectdata *conn, - curl_socket_t *socks); static bool http_should_fail(struct Curl_easy *data); -static CURLcode http_setup_conn(struct Curl_easy *data, - struct connectdata *conn); -static CURLcode http_write_resp(struct Curl_easy *data, - const char *buf, size_t blen, - bool is_eos, - bool *done); - -#ifdef USE_WEBSOCKETS -static CURLcode ws_setup_conn(struct Curl_easy *data, - struct connectdata *conn); -#endif - /* * HTTP handler interface. */ const struct Curl_handler Curl_handler_http = { "HTTP", /* scheme */ - http_setup_conn, /* setup_connection */ + Curl_http_setup_conn, /* setup_connection */ Curl_http, /* do_it */ Curl_http_done, /* done */ ZERO_NULL, /* do_more */ @@ -130,11 +115,11 @@ const struct Curl_handler Curl_handler_http = { ZERO_NULL, /* connecting */ ZERO_NULL, /* doing */ ZERO_NULL, /* proto_getsock */ - http_getsock_do, /* doing_getsock */ + Curl_http_getsock_do, /* doing_getsock */ ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - http_write_resp, /* write_resp */ + Curl_http_write_resp, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_HTTP, /* defport */ @@ -144,39 +129,13 @@ const struct Curl_handler Curl_handler_http = { PROTOPT_USERPWDCTRL }; -#ifdef USE_WEBSOCKETS -const struct Curl_handler Curl_handler_ws = { - "WS", /* scheme */ - ws_setup_conn, /* setup_connection */ - Curl_http, /* do_it */ - Curl_http_done, /* done */ - ZERO_NULL, /* do_more */ - Curl_http_connect, /* connect_it */ - ZERO_NULL, /* connecting */ - ZERO_NULL, /* doing */ - ZERO_NULL, /* proto_getsock */ - http_getsock_do, /* doing_getsock */ - ZERO_NULL, /* domore_getsock */ - ZERO_NULL, /* perform_getsock */ - Curl_ws_disconnect, /* disconnect */ - http_write_resp, /* write_resp */ - ZERO_NULL, /* connection_check */ - ZERO_NULL, /* attach connection */ - PORT_HTTP, /* defport */ - CURLPROTO_WS, /* protocol */ - CURLPROTO_HTTP, /* family */ - PROTOPT_CREDSPERREQUEST | /* flags */ - PROTOPT_USERPWDCTRL -}; -#endif - #ifdef USE_SSL /* * HTTPS handler interface. */ const struct Curl_handler Curl_handler_https = { "HTTPS", /* scheme */ - http_setup_conn, /* setup_connection */ + Curl_http_setup_conn, /* setup_connection */ Curl_http, /* do_it */ Curl_http_done, /* done */ ZERO_NULL, /* do_more */ @@ -184,11 +143,11 @@ const struct Curl_handler Curl_handler_https = { NULL, /* connecting */ ZERO_NULL, /* doing */ NULL, /* proto_getsock */ - http_getsock_do, /* doing_getsock */ + Curl_http_getsock_do, /* doing_getsock */ ZERO_NULL, /* domore_getsock */ ZERO_NULL, /* perform_getsock */ ZERO_NULL, /* disconnect */ - http_write_resp, /* write_resp */ + Curl_http_write_resp, /* write_resp */ ZERO_NULL, /* connection_check */ ZERO_NULL, /* attach connection */ PORT_HTTPS, /* defport */ @@ -198,36 +157,10 @@ const struct Curl_handler Curl_handler_https = { PROTOPT_USERPWDCTRL }; -#ifdef USE_WEBSOCKETS -const struct Curl_handler Curl_handler_wss = { - "WSS", /* scheme */ - ws_setup_conn, /* setup_connection */ - Curl_http, /* do_it */ - Curl_http_done, /* done */ - ZERO_NULL, /* do_more */ - Curl_http_connect, /* connect_it */ - NULL, /* connecting */ - ZERO_NULL, /* doing */ - NULL, /* proto_getsock */ - http_getsock_do, /* doing_getsock */ - ZERO_NULL, /* domore_getsock */ - ZERO_NULL, /* perform_getsock */ - Curl_ws_disconnect, /* disconnect */ - http_write_resp, /* write_resp */ - ZERO_NULL, /* connection_check */ - ZERO_NULL, /* attach connection */ - PORT_HTTPS, /* defport */ - CURLPROTO_WSS, /* protocol */ - CURLPROTO_HTTP, /* family */ - PROTOPT_SSL | PROTOPT_CREDSPERREQUEST | /* flags */ - PROTOPT_USERPWDCTRL -}; -#endif - #endif -static CURLcode http_setup_conn(struct Curl_easy *data, - struct connectdata *conn) +CURLcode Curl_http_setup_conn(struct Curl_easy *data, + struct connectdata *conn) { /* allocate the HTTP-specific struct for the Curl_easy, only to survive during this request */ @@ -250,16 +183,6 @@ static CURLcode http_setup_conn(struct Curl_easy *data, return CURLE_OK; } -#ifdef USE_WEBSOCKETS -static CURLcode ws_setup_conn(struct Curl_easy *data, - struct connectdata *conn) -{ - /* websockets is 1.1 only (for now) */ - data->state.httpwant = CURL_HTTP_VERSION_1_1; - return http_setup_conn(data, conn); -} -#endif - #ifndef CURL_DISABLE_PROXY /* * checkProxyHeaders() checks the linked list of custom proxy headers @@ -1594,9 +1517,9 @@ CURLcode Curl_http_connect(struct Curl_easy *data, bool *done) /* this returns the socket to wait for in the DO and DOING state for the multi interface and then we're always _sending_ a request and thus we wait for the single socket to become writable only */ -static int http_getsock_do(struct Curl_easy *data, - struct connectdata *conn, - curl_socket_t *socks) +int Curl_http_getsock_do(struct Curl_easy *data, + struct connectdata *conn, + curl_socket_t *socks) { /* write mode */ (void)conn; @@ -4133,11 +4056,10 @@ static CURLcode http_rw_headers(struct Curl_easy *data, if(result) return result; k->header = FALSE; /* no more header to parse! */ - if(data->set.connect_only) { + *pconsumed += blen; /* ws accept handled the data */ + blen = 0; + if(data->set.connect_only) k->keepon &= ~KEEP_RECV; /* read no more content */ - *pconsumed += blen; - blen = 0; - } } #endif else { @@ -4611,10 +4533,10 @@ CURLcode Curl_http_write_resp_hds(struct Curl_easy *data, } } -static CURLcode http_write_resp(struct Curl_easy *data, - const char *buf, size_t blen, - bool is_eos, - bool *done) +CURLcode Curl_http_write_resp(struct Curl_easy *data, + const char *buf, size_t blen, + bool is_eos, + bool *done) { CURLcode result; size_t consumed; diff --git a/lib/http.h b/lib/http.h index 8116ec1aacd..ad2697c9e73 100644 --- a/lib/http.h +++ b/lib/http.h @@ -54,14 +54,6 @@ extern const struct Curl_handler Curl_handler_http; extern const struct Curl_handler Curl_handler_https; #endif -#ifdef USE_WEBSOCKETS -extern const struct Curl_handler Curl_handler_ws; - -#ifdef USE_SSL -extern const struct Curl_handler Curl_handler_wss; -#endif -#endif /* websockets */ - struct dynhds; CURLcode Curl_bump_headersize(struct Curl_easy *data, @@ -147,9 +139,17 @@ CURLcode Curl_http_firstwrite(struct Curl_easy *data, bool *done); /* protocol-specific functions set up to be called by the main engine */ +CURLcode Curl_http_setup_conn(struct Curl_easy *data, + struct connectdata *conn); CURLcode Curl_http(struct Curl_easy *data, bool *done); CURLcode Curl_http_done(struct Curl_easy *data, CURLcode, bool premature); CURLcode Curl_http_connect(struct Curl_easy *data, bool *done); +int Curl_http_getsock_do(struct Curl_easy *data, struct connectdata *conn, + curl_socket_t *socks); +CURLcode Curl_http_write_resp(struct Curl_easy *data, + const char *buf, size_t blen, + bool is_eos, + bool *done); /* These functions are in http.c */ CURLcode Curl_http_input_auth(struct Curl_easy *data, bool proxy, diff --git a/lib/sendf.c b/lib/sendf.c index 2a2dfce8e8b..db3189a2980 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -296,13 +296,6 @@ static CURLcode chop_write(struct Curl_easy *data, if(!skip_body_write && ((type & CLIENTWRITE_BODY) || ((type & CLIENTWRITE_HEADER) && data->set.include_header))) { -#ifdef USE_WEBSOCKETS - if(conn->handler->protocol & (CURLPROTO_WS|CURLPROTO_WSS)) { - writebody = Curl_ws_writecb; - writebody_ptr = data; - } - else -#endif writebody = data->set.fwrite_func; } if((type & (CLIENTWRITE_HEADER|CLIENTWRITE_INFO)) && diff --git a/lib/ws.c b/lib/ws.c index 78c14046997..d9765182d95 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -24,7 +24,7 @@ #include "curl_setup.h" #include -#ifdef USE_WEBSOCKETS +#if defined(USE_WEBSOCKETS) && !defined(CURL_DISABLE_HTTP) #include "urldata.h" #include "bufq.h" @@ -354,6 +354,136 @@ static void update_meta(struct websocket *ws, ws->frame.bytesleft = (payload_len - payload_offset - cur_len); } +/* WebSockets decoding client writer */ +struct ws_cw_ctx { + struct Curl_cwriter super; + struct bufq buf; +}; + +static CURLcode ws_cw_init(struct Curl_easy *data, + struct Curl_cwriter *writer) +{ + struct ws_cw_ctx *ctx = (struct ws_cw_ctx *)writer; + (void)data; + Curl_bufq_init2(&ctx->buf, WS_CHUNK_SIZE, 1, BUFQ_OPT_SOFT_LIMIT); + return CURLE_OK; +} + +static void ws_cw_close(struct Curl_easy *data, struct Curl_cwriter *writer) +{ + struct ws_cw_ctx *ctx = (struct ws_cw_ctx *)writer; + (void) data; + Curl_bufq_free(&ctx->buf); +} + +struct ws_cw_dec_ctx { + struct Curl_easy *data; + struct websocket *ws; + struct Curl_cwriter *next_writer; + int cw_type; +}; + +static ssize_t ws_cw_dec_next(const unsigned char *buf, size_t buflen, + int frame_age, int frame_flags, + curl_off_t payload_offset, + curl_off_t payload_len, + void *user_data, + CURLcode *err) +{ + struct ws_cw_dec_ctx *ctx = user_data; + struct Curl_easy *data = ctx->data; + struct websocket *ws = ctx->ws; + curl_off_t remain = (payload_len - (payload_offset + buflen)); + + (void)frame_age; + if((frame_flags & CURLWS_PING) && !remain) { + /* auto-respond to PINGs, only works for single-frame payloads atm */ + size_t bytes; + infof(data, "WS: auto-respond to PING with a PONG"); + /* send back the exact same content as a PONG */ + *err = curl_ws_send(data, buf, buflen, &bytes, 0, CURLWS_PONG); + if(*err) + return -1; + } + else if(buflen || !remain) { + /* forward the decoded frame to the next client writer. */ + update_meta(ws, frame_age, frame_flags, payload_offset, + payload_len, buflen); + + *err = Curl_cwriter_write(data, ctx->next_writer, ctx->cw_type, + (const char *)buf, buflen); + if(*err) + return -1; + } + *err = CURLE_OK; + return (ssize_t)buflen; +} + +static CURLcode ws_cw_write(struct Curl_easy *data, + struct Curl_cwriter *writer, int type, + const char *buf, size_t nbytes) +{ + struct ws_cw_ctx *ctx = (struct ws_cw_ctx *)writer; + struct websocket *ws; + CURLcode result; + + if(!(type & CLIENTWRITE_BODY) || data->set.ws_raw_mode) + return Curl_cwriter_write(data, writer->next, type, buf, nbytes); + + ws = data->conn->proto.ws; + if(!ws) { + failf(data, "WS: not a websocket transfer"); + return CURLE_FAILED_INIT; + } + + if(nbytes) { + ssize_t nwritten; + nwritten = Curl_bufq_write(&ctx->buf, (const unsigned char *)buf, + nbytes, &result); + if(nwritten < 0) { + infof(data, "WS: error adding data to buffer %d", result); + return result; + } + } + + while(!Curl_bufq_is_empty(&ctx->buf)) { + struct ws_cw_dec_ctx pass_ctx; + pass_ctx.data = data; + pass_ctx.ws = ws; + pass_ctx.next_writer = writer->next; + pass_ctx.cw_type = type; + result = ws_dec_pass(&ws->dec, data, &ctx->buf, + ws_cw_dec_next, &pass_ctx); + if(result == CURLE_AGAIN) + /* insufficient amount of data, keep it for later. + * we pretend to have written all since we have a copy */ + return CURLE_OK; + else if(result) { + infof(data, "WS: decode error %d", (int)result); + return result; + } + } + + if((type & CLIENTWRITE_EOS) && !Curl_bufq_is_empty(&ctx->buf)) { + infof(data, "WS: decode ending with %zd frame bytes remaining", + Curl_bufq_len(&ctx->buf)); + return CURLE_RECV_ERROR; + } + + return CURLE_OK; +} + +/* WebSocket payload decoding client writer. */ +static const struct Curl_cwtype ws_cw_decode = { + "ws-decode", + NULL, + ws_cw_init, + ws_cw_write, + ws_cw_close, + sizeof(struct ws_cw_ctx) +}; + + static void ws_enc_info(struct ws_encoder *enc, struct Curl_easy *data, const char *msg) { @@ -618,6 +748,7 @@ CURLcode Curl_ws_accept(struct Curl_easy *data, { struct SingleRequest *k = &data->req; struct websocket *ws; + struct Curl_cwriter *ws_dec_writer; CURLcode result; DEBUGASSERT(data->conn); @@ -627,7 +758,8 @@ CURLcode Curl_ws_accept(struct Curl_easy *data, if(!ws) return CURLE_OUT_OF_MEMORY; data->conn->proto.ws = ws; - Curl_bufq_init(&ws->recvbuf, WS_CHUNK_SIZE, WS_CHUNK_COUNT); + Curl_bufq_init2(&ws->recvbuf, WS_CHUNK_SIZE, WS_CHUNK_COUNT, + BUFQ_OPT_SOFT_LIMIT); Curl_bufq_init2(&ws->sendbuf, WS_CHUNK_SIZE, WS_CHUNK_COUNT, BUFQ_OPT_SOFT_LIMIT); ws_dec_init(&ws->dec); @@ -666,6 +798,18 @@ CURLcode Curl_ws_accept(struct Curl_easy *data, infof(data, "Received 101, switch to WebSocket; mask %02x%02x%02x%02x", ws->enc.mask[0], ws->enc.mask[1], ws->enc.mask[2], ws->enc.mask[3]); + /* Install our client writer that decodes WS frames payload */ + result = Curl_cwriter_create(&ws_dec_writer, data, &ws_cw_decode, + CURL_CW_CONTENT_DECODE); + if(result) + return result; + + result = Curl_cwriter_add(data, ws_dec_writer); + if(result) { + Curl_cwriter_free(data, ws_dec_writer); + return result; + } + if(data->set.connect_only) { ssize_t nwritten; /* In CONNECT_ONLY setup, the payloads from `mem` need to be received @@ -677,105 +821,15 @@ CURLcode Curl_ws_accept(struct Curl_easy *data, return result; infof(data, "%zu bytes websocket payload", nread); } - k->upgr101 = UPGR101_RECEIVED; - - return result; -} - -static ssize_t ws_client_write(const unsigned char *buf, size_t buflen, - int frame_age, int frame_flags, - curl_off_t payload_offset, - curl_off_t payload_len, - void *userp, - CURLcode *err) -{ - struct Curl_easy *data = userp; - struct websocket *ws; - size_t wrote; - curl_off_t remain = (payload_len - (payload_offset + buflen)); - - (void)frame_age; - if(!data->conn || !data->conn->proto.ws) { - *err = CURLE_FAILED_INIT; - return -1; - } - ws = data->conn->proto.ws; - - if((frame_flags & CURLWS_PING) && !remain) { - /* auto-respond to PINGs, only works for single-frame payloads atm */ - size_t bytes; - infof(data, "WS: auto-respond to PING with a PONG"); - /* send back the exact same content as a PONG */ - *err = curl_ws_send(data, buf, buflen, &bytes, 0, CURLWS_PONG); - if(*err) - return -1; - } - else if(buflen || !remain) { - /* deliver the decoded frame to the user callback. The application - * may invoke curl_ws_meta() to access frame information. */ - update_meta(ws, frame_age, frame_flags, payload_offset, - payload_len, buflen); - Curl_set_in_callback(data, true); - wrote = data->set.fwrite_func((char *)buf, 1, - buflen, data->set.out); - Curl_set_in_callback(data, false); - if(wrote != buflen) { - *err = CURLE_RECV_ERROR; - return -1; + else { /* !connect_only */ + /* And pass any additional data to the writers */ + if(nread) { + result = Curl_client_write(data, CLIENTWRITE_BODY, (char *)mem, nread); } } - *err = CURLE_OK; - return (ssize_t)buflen; -} - -/* Curl_ws_writecb() is the write callback for websocket traffic. The - websocket data is provided to this raw, in chunks. This function should - handle/decode the data and call the "real" underlying callback accordingly. -*/ -size_t Curl_ws_writecb(char *buffer, size_t size /* 1 */, - size_t nitems, void *userp) -{ - struct Curl_easy *data = userp; - - if(data->set.ws_raw_mode) - return data->set.fwrite_func(buffer, size, nitems, data->set.out); - else if(nitems) { - struct websocket *ws; - CURLcode result; - - if(!data->conn || !data->conn->proto.ws) { - failf(data, "WS: not a websocket transfer"); - return nitems - 1; - } - ws = data->conn->proto.ws; - - if(buffer) { - ssize_t nwritten; - - nwritten = Curl_bufq_write(&ws->recvbuf, (const unsigned char *)buffer, - nitems, &result); - if(nwritten < 0) { - infof(data, "WS: error adding data to buffer %d", (int)result); - return nitems - 1; - } - buffer = NULL; - } - - while(!Curl_bufq_is_empty(&ws->recvbuf)) { + k->upgr101 = UPGR101_RECEIVED; - result = ws_dec_pass(&ws->dec, data, &ws->recvbuf, - ws_client_write, data); - if(result == CURLE_AGAIN) - /* insufficient amount of data, keep it for later. - * we pretend to have written all since we have a copy */ - return nitems; - else if(result) { - infof(data, "WS: decode error %d", (int)result); - return nitems - 1; - } - } - } - return nitems; + return result; } struct ws_collect { @@ -1085,14 +1139,23 @@ static void ws_free(struct connectdata *conn) } } +static CURLcode ws_setup_conn(struct Curl_easy *data, + struct connectdata *conn) +{ + /* websockets is 1.1 only (for now) */ + data->state.httpwant = CURL_HTTP_VERSION_1_1; + return Curl_http_setup_conn(data, conn); +} + + void Curl_ws_done(struct Curl_easy *data) { (void)data; } -CURLcode Curl_ws_disconnect(struct Curl_easy *data, - struct connectdata *conn, - bool dead_connection) +static CURLcode ws_disconnect(struct Curl_easy *data, + struct connectdata *conn, + bool dead_connection) { (void)data; (void)dead_connection; @@ -1110,6 +1173,57 @@ CURL_EXTERN const struct curl_ws_frame *curl_ws_meta(struct Curl_easy *data) return NULL; } +const struct Curl_handler Curl_handler_ws = { + "WS", /* scheme */ + ws_setup_conn, /* setup_connection */ + Curl_http, /* do_it */ + Curl_http_done, /* done */ + ZERO_NULL, /* do_more */ + Curl_http_connect, /* connect_it */ + ZERO_NULL, /* connecting */ + ZERO_NULL, /* doing */ + ZERO_NULL, /* proto_getsock */ + Curl_http_getsock_do, /* doing_getsock */ + ZERO_NULL, /* domore_getsock */ + ZERO_NULL, /* perform_getsock */ + ws_disconnect, /* disconnect */ + Curl_http_write_resp, /* write_resp */ + ZERO_NULL, /* connection_check */ + ZERO_NULL, /* attach connection */ + PORT_HTTP, /* defport */ + CURLPROTO_WS, /* protocol */ + CURLPROTO_HTTP, /* family */ + PROTOPT_CREDSPERREQUEST | /* flags */ + PROTOPT_USERPWDCTRL +}; + +#ifdef USE_SSL +const struct Curl_handler Curl_handler_wss = { + "WSS", /* scheme */ + ws_setup_conn, /* setup_connection */ + Curl_http, /* do_it */ + Curl_http_done, /* done */ + ZERO_NULL, /* do_more */ + Curl_http_connect, /* connect_it */ + NULL, /* connecting */ + ZERO_NULL, /* doing */ + NULL, /* proto_getsock */ + Curl_http_getsock_do, /* doing_getsock */ + ZERO_NULL, /* domore_getsock */ + ZERO_NULL, /* perform_getsock */ + ws_disconnect, /* disconnect */ + Curl_http_write_resp, /* write_resp */ + ZERO_NULL, /* connection_check */ + ZERO_NULL, /* attach connection */ + PORT_HTTPS, /* defport */ + CURLPROTO_WSS, /* protocol */ + CURLPROTO_HTTP, /* family */ + PROTOPT_SSL | PROTOPT_CREDSPERREQUEST | /* flags */ + PROTOPT_USERPWDCTRL +}; +#endif + + #else CURL_EXTERN CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, diff --git a/lib/ws.h b/lib/ws.h index 0308a42545b..5f40d4528b5 100644 --- a/lib/ws.h +++ b/lib/ws.h @@ -25,7 +25,7 @@ ***************************************************************************/ #include "curl_setup.h" -#ifdef USE_WEBSOCKETS +#if defined(USE_WEBSOCKETS) && !defined(CURL_DISABLE_HTTP) #ifdef USE_HYPER #define REQTYPE void @@ -75,11 +75,14 @@ struct websocket { CURLcode Curl_ws_request(struct Curl_easy *data, REQTYPE *req); CURLcode Curl_ws_accept(struct Curl_easy *data, const char *mem, size_t len); -size_t Curl_ws_writecb(char *buffer, size_t size, size_t nitems, void *userp); void Curl_ws_done(struct Curl_easy *data); -CURLcode Curl_ws_disconnect(struct Curl_easy *data, - struct connectdata *conn, - bool dead_connection); + +extern const struct Curl_handler Curl_handler_ws; +#ifdef USE_SSL +extern const struct Curl_handler Curl_handler_wss; +#endif + + #else #define Curl_ws_request(x,y) CURLE_OK #define Curl_ws_done(x) Curl_nop_stmt From f4606a796ea1e2ef5c2301e93e4cf4f1dc6d901e Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Sun, 7 Jan 2024 00:07:55 -0500 Subject: [PATCH 183/509] tool_getparam: stop supporting `@filename` style for --cookie The `@filename` style was never documented for --cookie but prior to this change curl would accept it anyway and always treat a @ prefixed string as a filename. That's a problem if the string also contains a = sign because then it is documented to be interpreted as a cookie string and not a filename. Example: `--cookie @foo=bar` Before: Interpreted as load cookies from filename foo=bar. After: Interpreted as cookie `@foo=bar` (name `@foo` and value `bar`). Other curl options with a data/filename option-value use the `@filename` to distinguish filenames which is probably how this happened. The --cookie option has never been documented that way. Ref: https://curl.se/docs/manpage.html#-b Closes https://github.com/curl/curl/pull/12645 --- src/tool_getparam.c | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 571918389d8..4c910fd73c9 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -1988,16 +1988,15 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ err = getstr(&config->hsts, nextarg, ALLOW_BLANK); break; case C_COOKIE: /* --cookie */ - if(nextarg[0] == '@') { - nextarg++; - } - else if(strchr(nextarg, '=')) { + if(strchr(nextarg, '=')) { /* A cookie string must have a =-letter */ err = add2list(&config->cookies, nextarg); break; } - /* We have a cookie file to read from! */ - err = add2list(&config->cookiefiles, nextarg); + else { + /* We have a cookie file to read from! */ + err = add2list(&config->cookiefiles, nextarg); + } break; case C_USE_ASCII: /* --use-ascii */ config->use_ascii = toggle; From 7aa24f32dbbf14067ddb016c1fc43b72b04db06a Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Wed, 17 Jan 2024 00:10:40 -0500 Subject: [PATCH 184/509] cf-socket: show errno in tcpkeepalive error messages - If the socket keepalive options (TCP_KEEPIDLE, etc) cannot be set then show the errno in the verbose error messages. Ref: https://github.com/curl/curl/discussions/12715#discussioncomment-8151652 Closes https://github.com/curl/curl/pull/12726 --- lib/cf-socket.c | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/lib/cf-socket.c b/lib/cf-socket.c index cfb98386d99..64af604ad30 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -163,8 +163,9 @@ tcpkeepalive(struct Curl_easy *data, /* only set IDLE and INTVL if setting KEEPALIVE is successful */ if(setsockopt(sockfd, SOL_SOCKET, SO_KEEPALIVE, (void *)&optval, sizeof(optval)) < 0) { - infof(data, "Failed to set SO_KEEPALIVE on fd %" CURL_FORMAT_SOCKET_T, - sockfd); + infof(data, "Failed to set SO_KEEPALIVE on fd " + "%" CURL_FORMAT_SOCKET_T ": errno %d", + sockfd, SOCKERRNO); } else { #if defined(SIO_KEEPALIVE_VALS) @@ -180,8 +181,8 @@ tcpkeepalive(struct Curl_easy *data, if(WSAIoctl(sockfd, SIO_KEEPALIVE_VALS, (LPVOID) &vals, sizeof(vals), NULL, 0, &dummy, NULL, NULL) != 0) { infof(data, "Failed to set SIO_KEEPALIVE_VALS on fd " - "%" CURL_FORMAT_SOCKET_T ": %d", - sockfd, WSAGetLastError()); + "%" CURL_FORMAT_SOCKET_T ": errno %d", + sockfd, SOCKERRNO); } #else #ifdef TCP_KEEPIDLE @@ -189,8 +190,9 @@ tcpkeepalive(struct Curl_easy *data, KEEPALIVE_FACTOR(optval); if(setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPIDLE, (void *)&optval, sizeof(optval)) < 0) { - infof(data, "Failed to set TCP_KEEPIDLE on fd %" CURL_FORMAT_SOCKET_T, - sockfd); + infof(data, "Failed to set TCP_KEEPIDLE on fd " + "%" CURL_FORMAT_SOCKET_T ": errno %d", + sockfd, SOCKERRNO); } #elif defined(TCP_KEEPALIVE) /* Mac OS X style */ @@ -198,8 +200,9 @@ tcpkeepalive(struct Curl_easy *data, KEEPALIVE_FACTOR(optval); if(setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPALIVE, (void *)&optval, sizeof(optval)) < 0) { - infof(data, "Failed to set TCP_KEEPALIVE on fd %" CURL_FORMAT_SOCKET_T, - sockfd); + infof(data, "Failed to set TCP_KEEPALIVE on fd " + "%" CURL_FORMAT_SOCKET_T ": errno %d", + sockfd, SOCKERRNO); } #endif #ifdef TCP_KEEPINTVL @@ -207,8 +210,9 @@ tcpkeepalive(struct Curl_easy *data, KEEPALIVE_FACTOR(optval); if(setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPINTVL, (void *)&optval, sizeof(optval)) < 0) { - infof(data, "Failed to set TCP_KEEPINTVL on fd %" CURL_FORMAT_SOCKET_T, - sockfd); + infof(data, "Failed to set TCP_KEEPINTVL on fd " + "%" CURL_FORMAT_SOCKET_T ": errno %d", + sockfd, SOCKERRNO); } #endif #endif From 2462c9d594198901666735bcc807feb95510d440 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 17 Jan 2024 09:53:38 +0100 Subject: [PATCH 185/509] test2307: fix expected failure code after ws refactoring Fixes #12722 Closes #12728 --- tests/data/test2307 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/data/test2307 b/tests/data/test2307 index 26b3309a8dc..ce260ac1c23 100644 --- a/tests/data/test2307 +++ b/tests/data/test2307 @@ -63,9 +63,9 @@ Sec-WebSocket-Key: NDMyMTUzMjE2MzIxNzMyMQ== -# 23 == CURLE_WRITE_ERROR +# 56 == CURLE_RECV_ERROR -23 +56 From 6b930f1bfb31cad614d3f6f97f841d09daacdda8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 17 Jan 2024 14:27:16 +0100 Subject: [PATCH 186/509] docs: cleanup nroff format use - remove use of .BI for code snippet - stop using .br, just do a blank line - remove use of .PP - remove use for .sp - remove backslash in .IP - use .IP instead of .TP Closes #12731 --- docs/libcurl/curl_formget.3 | 13 +++--- docs/libcurl/curl_getdate.3 | 15 ++---- docs/libcurl/curl_global_init_mem.3 | 2 +- docs/libcurl/curl_mime_encoder.3 | 10 ++-- docs/libcurl/curl_mime_type.3 | 10 ++-- docs/libcurl/curl_mprintf.3 | 66 ++++++++++----------------- docs/libcurl/curl_strequal.3 | 12 ++--- docs/libcurl/curl_version_info.3 | 62 ++++++++++++------------- docs/libcurl/libcurl-tutorial.3 | 8 ++-- docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 | 14 +++--- 10 files changed, 93 insertions(+), 119 deletions(-) diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index 395ae7df69a..583092169f4 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -32,13 +32,14 @@ int curl_formget(struct curl_httppost * form, void *userp, curl_formget_callback append); .fi .SH DESCRIPTION -curl_formget() is used to serialize data previously built/appended with -\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named -\fIuserp\fP which is passed as the first argument to the curl_formget_callback -function. +curl_formget() serializes data previously built with \fIcurl_formadd(3)\fP. It +accepts a void pointer as second argument named \fIuserp\fP which is passed as +the first argument to the curl_formget_callback function. -.BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf, -.BI " size_t " len ");" +.nf + typedef size_t (*curl_formget_callback)(void *userp, const char *buf, + size_t len);" +.fi The curl_formget_callback is invoked for each part of the HTTP POST chain. The character buffer passed to the callback must not be freed. The callback should diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 42dc29997e0..91c55235fae 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -43,28 +43,23 @@ wrong dates, such as February 30. A "date" is a string containing several items separated by whitespace. The order of the items is immaterial. A date string may contain many flavors of items: -.TP 0.8i -.B calendar date items +.IP "calendar date items" Can be specified several ways. Month names can only be three-letter English abbreviations, numbers can be zero-prefixed and the year may use 2 or 4 digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. -.TP -.B time of the day items +.IP "time of the day items" This string specifies the time on a given day. You must specify it with 6 digits with two colons: HH:MM:SS. If there is no time given in a provided date string, 00:00:00 is assumed. Example: 18:19:21. -.TP -.B time zone items +.IP "time zone items" Specifies international time zone. There are a few acronyms supported, but in general you should instead use the specific relative time compared to UTC. Supported formats include: -1200, MST, +0100. -.TP -.B day of the week items +.IP "day of the week items" Specifies a day of the week. Days of the week may be spelled out in full (using English): `Sunday', `Monday', etc or they may be abbreviated to their first three letters. This is usually not info that adds anything. -.TP -.B pure numbers +.IP "pure numbers" If a decimal number of the form YYYYMMDD appears, then YYYY is read as the year, MM as the month number and DD as the day of the month, for the specified calendar date. diff --git a/docs/libcurl/curl_global_init_mem.3 b/docs/libcurl/curl_global_init_mem.3 index 3aa65ba934a..b41087531ef 100644 --- a/docs/libcurl/curl_global_init_mem.3 +++ b/docs/libcurl/curl_global_init_mem.3 @@ -57,7 +57,7 @@ To replace realloc() To replace strdup() .IP "void *calloc_callback(size_t nmemb, size_t size);" To replace calloc() -.PP + This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer to that man page for documentation. .SH CAUTION diff --git a/docs/libcurl/curl_mime_encoder.3 b/docs/libcurl/curl_mime_encoder.3 index 64c2636e318..f6eaa2ec6ee 100644 --- a/docs/libcurl/curl_mime_encoder.3 +++ b/docs/libcurl/curl_mime_encoder.3 @@ -47,17 +47,17 @@ pertaining scheme and a corresponding \fI"Content-Transfer-Encoding"\fP header is added to the part. Supported encoding schemes are: -.br + "\fIbinary\fP": the data is left unchanged, the header is added. -.br + "\fI8bit\fP": header added, no data change. -.br + "\fI7bit\fP": the data is unchanged, but is each byte is checked to be a 7-bit value; if not, a read error occurs. -.br + "\fIbase64\fP": Data is converted to base64 encoding, then split in CRLF-terminated lines of at most 76 characters. -.br + "\fIquoted-printable\fP": data is encoded in quoted printable lines of at most 76 characters. Since the resulting size of the final data cannot be determined prior to reading the original data, it is left as unknown, causing diff --git a/docs/libcurl/curl_mime_type.3 b/docs/libcurl/curl_mime_type.3 index 6d0c6a87299..3e4ac822bac 100644 --- a/docs/libcurl/curl_mime_type.3 +++ b/docs/libcurl/curl_mime_type.3 @@ -44,16 +44,16 @@ is valid: only the value set by the last call is retained. In the absence of a mime type and if needed by the protocol specifications, a default mime type is determined by the context: -.br + - If set as a custom header, use this value. -.br + - application/form-data for an HTTP form post. -.br + - If a remote file name is set, the mime type is taken from the file name extension, or application/octet-stream by default. -.br + - For a multipart part, multipart/mixed. -.br + - text/plain in other cases. .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index c60ef0a8129..ac746cbea3f 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -112,24 +112,20 @@ string. .SH "Flag characters" The character % is followed by zero or more of the following flags: -.TP -.B # + +.IP # The value should be converted to its "alternate form". -.TP -.B 0 +.IP 0 The value should be zero padded. -.TP -.B - +.IP - The converted value is to be left adjusted on the field boundary. (The default is right justification.) The converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A '-' overrides a \&'0' if both are given. -.TP -.B ' ' +.IP ' ' (a space) A blank should be left before a positive number (or empty string) produced by a signed conversion. -.TP -.B + +.IP + A sign (+ or -) should always be placed before a number produced by a signed conversion. By default, a sign is used only for negative numbers. A '+' overrides a space if both are used. @@ -159,43 +155,35 @@ after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and \fBG\fP conversions, or the maximum number of characters to be printed from a string for \fBs\fP and \fBS\fP conversions. .SH "Length modifier" -.TP -.B h +.IP h A following integer conversion corresponds to a \fIshort\fP or \fIunsigned short\fP argument. -.TP -.B l +.IP l (ell) A following integer conversion corresponds to a \fIlong\fP or \fIunsigned long\fP argument, or a following n conversion corresponds to a pointer to a long argument -.TP -.B ll +.IP ll (ell-ell). A following integer conversion corresponds to a \fIlong long\fP or \fIunsigned long long\fP argument, or a following n conversion corresponds to a pointer to a long long argument. -.TP -.B q +.IP q A synonym for \fBll\fP. -.TP -.B L +.IP L A following a, A, e, E, f, F, g, or G conversion corresponds to a long double argument. -.TP -.B z +.IP z A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP argument. .SH "Conversion specifiers" A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are: -.TP -.B d, i +.IP "d, i" The int argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. -.TP -.B o, u, x, X +.IP "o, u, x, X" The unsigned int argument is converted to unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters \fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are @@ -203,38 +191,30 @@ used for \fBX\fP conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. -.TP -.B e, E +.IP "e, E" The double argument is rounded and output in the style \fB"[-]d.ddde±dd"\fP -.TP -.B f, F +.IP "f, F" The double argument is rounded and output to decimal notation in the style \fB"[-]ddd.ddd"\fP. -.TP -.B g, G +.IP "g, G" The double argument is converted in style f or e. -.TP -.B c +.IP "c" The int argument is converted to an unsigned char, and the resulting character is written. -.TP -.B s +.IP "s" The \fIconst char *\fP argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating null byte. If a precision is specified, no more than the number specified are written. If a precision is given, no null byte need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating null byte. -.TP -.B p +.IP "p" The \fIvoid *\fP pointer argument is printed in hexadecimal. -.TP -.B n +.IP "n" The number of characters written so far is stored into the integer pointed to by the corresponding argument. -.TP -.B % -A '%' is written. No argument is converted. +.IP "%" +A '%' symbol is written. No argument is converted. .SH EXAMPLE .nf const char *name = "John"; diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index 89eec323f51..dc21c2e3ba3 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -32,15 +32,13 @@ int curl_strequal(const char *str1, const char *str2); int curl_strnequal(const char *str1, const char *str2, size_t length); .fi .SH DESCRIPTION -The -.B curl_strequal() -function compares the two strings \fIstr1\fP and \fIstr2\fP, ignoring the case -of the characters. It returns a non-zero (TRUE) integer if the strings are -identical. -.sp +The \fIcurl_strequal(3)\fP function compares the two strings \fIstr1\fP and +\fIstr2\fP, ignoring the case of the characters. It returns a non-zero (TRUE) +integer if the strings are identical. + The \fBcurl_strnequal()\fP function is similar, except it only compares the first \fIlength\fP characters of \fIstr1\fP. -.sp + These functions are provided by libcurl to enable applications to compare strings in a truly portable manner. There are no standard portable case insensitive string comparison functions. These two work on all platforms. diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index e7fb8af659c..32bea8272bc 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -141,153 +141,153 @@ entry. Currently defined names are: .RS .IP """alt-svc""" \fIfeatures\fP mask bit: CURL_VERSION_ALTSVC -.br + HTTP Alt-Svc parsing and the associated options (Added in 7.64.1) .IP """AsynchDNS""" \fIfeatures\fP mask bit: CURL_VERSION_ASYNCHDNS -.br + libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi interface. (added in 7.10.7) .IP """brotli""" \fIfeatures\fP mask bit: CURL_VERSION_BROTLI -.br + supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0) .IP """Debug""" \fIfeatures\fP mask bit: CURL_VERSION_DEBUG -.br + libcurl was built with debug capabilities (added in 7.10.6) .IP """gsasl""" \fIfeatures\fP mask bit: CURL_VERSION_GSASL -.br + libcurl was built with libgsasl and thus with some extra SCRAM-SHA authentication methods. (added in 7.76.0) .IP """GSS-API""" \fIfeatures\fP mask bit: CURL_VERSION_GSSAPI -.br + libcurl was built with support for GSS-API. This makes libcurl use provided functions for Kerberos and SPNEGO authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.38.0) .IP """HSTS""" \fIfeatures\fP mask bit: CURL_VERSION_HSTS -.br + libcurl was built with support for HSTS (HTTP Strict Transport Security) (Added in 7.74.0) .IP """HTTP2""" \fIfeatures\fP mask bit: CURL_VERSION_HTTP2 -.br + libcurl was built with support for HTTP2. (Added in 7.33.0) .IP """HTTP3""" \fIfeatures\fP mask bit: CURL_VERSION_HTTP3 -.br + HTTP/3 and QUIC support are built-in (Added in 7.66.0) .IP """HTTPS-proxy""" \fIfeatures\fP mask bit: CURL_VERSION_HTTPS_PROXY -.br + libcurl was built with support for HTTPS-proxy. (Added in 7.52.0) .IP """IDN""" \fIfeatures\fP mask bit: CURL_VERSION_IDN -.br + libcurl was built with support for IDNA, domain names with international letters. (Added in 7.12.0) .IP """IPv6""" \fIfeatures\fP mask bit: CURL_VERSION_IPV6 -.br + supports IPv6 .IP """Kerberos""" \fIfeatures\fP mask bit: CURL_VERSION_KERBEROS5 -.br + supports Kerberos V5 authentication for FTP, IMAP, LDAP, POP3, SMTP and SOCKSv5 proxy. (Added in 7.40.0) .IP """Largefile""" \fIfeatures\fP mask bit: CURL_VERSION_LARGEFILE -.br + libcurl was built with support for large files. (Added in 7.11.1) .IP """libz""" \fIfeatures\fP mask bit: CURL_VERSION_LIBZ -.br + supports HTTP deflate using libz (Added in 7.10) .IP """MultiSSL""" \fIfeatures\fP mask bit: CURL_VERSION_MULTI_SSL -.br + libcurl was built with multiple SSL backends. For details, see \fIcurl_global_sslset(3)\fP. (Added in 7.56.0) .IP """NTLM""" \fIfeatures\fP mask bit: CURL_VERSION_NTLM -.br + supports HTTP NTLM (added in 7.10.6) .IP """NTLM_WB""" \fIfeatures\fP mask bit: CURL_VERSION_NTLM_WB -.br + libcurl was built with support for NTLM delegation to a winbind helper. (Added in 7.22.0) .IP """PSL""" \fIfeatures\fP mask bit: CURL_VERSION_PSL -.br + libcurl was built with support for Mozilla's Public Suffix List. This makes libcurl ignore cookies with a domain that is on the list. (Added in 7.47.0) .IP """SPNEGO""" \fIfeatures\fP mask bit: CURL_VERSION_SPNEGO -.br + libcurl was built with support for SPNEGO authentication (Simple and Protected GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) .IP """SSL""" \fIfeatures\fP mask bit: CURL_VERSION_SSL -.br + supports SSL (HTTPS/FTPS) (Added in 7.10) .IP """SSPI""" \fIfeatures\fP mask bit: CURL_VERSION_SSPI -.br + libcurl was built with support for SSPI. This is only available on Windows and makes libcurl use Windows-provided functions for Kerberos, NTLM, SPNEGO and Digest authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.13.2) .IP """threadsafe""" \fIfeatures\fP mask bit: CURL_VERSION_THREADSAFE -.br + libcurl was built with thread-safety support (Atomic or SRWLOCK) to protect curl initialization. (Added in 7.84.0) See \fIlibcurl-thread(3)\fP .IP """TLS-SRP""" \fIfeatures\fP mask bit: CURL_VERSION_TLSAUTH_SRP -.br + libcurl was built with support for TLS-SRP (in one or more of the built-in TLS backends). (Added in 7.21.4) .IP """TrackMemory""" \fIfeatures\fP mask bit: CURL_VERSION_CURLDEBUG -.br + libcurl was built with memory tracking debug capabilities. This is mainly of interest for libcurl hackers. (added in 7.19.6) .IP """Unicode""" \fIfeatures\fP mask bit: CURL_VERSION_UNICODE -.br + libcurl was built with Unicode support on Windows. This makes non-ASCII characters work in filenames and options passed to libcurl. (Added in 7.72.0) .IP """UnixSockets""" \fIfeatures\fP mask bit: CURL_VERSION_UNIX_SOCKETS -.br + libcurl was built with support for Unix domain sockets. (Added in 7.40.0) .IP """zstd""" \fIfeatures\fP mask bit: CURL_VERSION_ZSTD -.br + supports HTTP zstd content encoding using zstd library (Added in 7.72.0) .IP none \fIfeatures\fP mask bit: CURL_VERSION_CONV -.br + libcurl was built with support for character conversions, as provided by the CURLOPT_CONV_* callbacks. Always 0 since 7.82.0. (Added in 7.15.4) .IP none \fIfeatures\fP mask bit: CURL_VERSION_GSSNEGOTIATE -.br + supports HTTP GSS-Negotiate (added in 7.10.6, deprecated in 7.38.0) .IP none \fIfeatures\fP mask bit: CURL_VERSION_KERBEROS4 -.br + supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0. .RE diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index d312bd5deb5..f8c9edf2289 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -597,13 +597,13 @@ from doing a POST. It just makes it POST without any data to send! .SH "Converting from deprecated form API to MIME API" Four rules have to be respected in building the multi-part: -.br + - The easy handle must be created before building the multi-part. -.br + - The multi-part is always created by a call to curl_mime_init(handle). -.br + - Each part is created by a call to curl_mime_addpart(multipart). -.br + - When complete, the multi-part must be bound to the easy handle using \fICURLOPT_MIMEPOST(3)\fP instead of \fICURLOPT_HTTPPOST(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 index 0cea12d02e8..edc2e6afd06 100644 --- a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 @@ -33,12 +33,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); .fi .SH DESCRIPTION Provides AWS V4 signature authentication on HTTP(S) header. -.PP + Pass a char * that is the collection of specific arguments are used for creating outgoing authentication headers. The format of the \fIparam\fP option is: .IP provider1[:provider2[:region[:service]]] -.IP provider1,\ provider2 +.IP "provider1, provider2" The providers arguments are used for generating some authentication parameters such as "Algorithm", "date", "request type" and "signed headers". .IP region @@ -47,16 +47,16 @@ It is extracted from the host name specified in the URL if omitted. .IP service The argument is a function provided by a cloud. It is extracted from the host name specified in the URL if omitted. -.PP + NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4. Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same as calling this with \fB"aws:amz"\fP in parameter. -.PP + Example with "Test:Try", when curl uses the algorithm, it generates \fB"TEST-HMAC-SHA256"\fP for "Algorithm", \fB"x-try-date"\fP and \fB"X-Try-Date"\fP for "date", \fB"test4_request"\fP for "request type", \fB"SignedHeaders=content-type;host;x-try-date"\fP for "signed headers" -.PP + If you use just "test", instead of "test:try", test is used for every generated string. .SH DEFAULT @@ -94,13 +94,13 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. This option overrides the other auth types you might have set in \fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth method special. This method cannot be combined with other auth types. -.PP + A sha256 checksum of the request payload is used as input to the signature calculation. For POST requests, this is a checksum of the provided \fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer. For requests like PUT, you can provide your own checksum in an HTTP header named \fBx-provider2-content-sha256\fP. -.PP + For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request if not already present. For s3 requests with unknown payload, this header takes the special value "UNSIGNED-PAYLOAD". From 434db995a7566a76f6a16391897816ddd1011adc Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 16 Jan 2024 16:30:07 +0000 Subject: [PATCH 187/509] mbedtls: fix `-Wnull-dereference` and `-Wredundant-decls` - Silence warning in mbedTLS v3.5.1 public headers: ``` ./mbedtls/_x64-linux-musl/usr/include/psa/crypto_extra.h:489:14: warning: redundant redeclaration of 'psa_set_key_domain_parameters' [-Wredundant-decls] ./mbedtls/_x64-linux-musl/usr/include/psa/crypto_struct.h:354:14: note: previous declaration of 'psa_set_key_domain_parameters' was here ``` Ref: https://github.com/libssh2/libssh2/commit/ecec68a2c13a9c63fe8c2dc457ae785a513e157c Ref: https://github.com/libssh2/libssh2/pull/1226 - Fix compiler warnings seen with gcc 9.2.0 + cmake unity: ``` ./curl/lib/vtls/mbedtls.c: In function 'mbedtls_bio_cf_read': ./curl/lib/vtls/mbedtls.c:189:11: warning: null pointer dereference [-Wnull-dereference] 189 | nread = Curl_conn_cf_recv(cf->next, data, (char *)buf, blen, &result); | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ./curl/lib/vtls/mbedtls.c: In function 'mbedtls_bio_cf_write': ./curl/lib/vtls/mbedtls.c:168:14: warning: null pointer dereference [-Wnull-dereference] 168 | nwritten = Curl_conn_cf_send(cf->next, data, (char *)buf, blen, &result); | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``` - delete stray `#else`. Closes #12720 --- lib/vtls/mbedtls.c | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/lib/vtls/mbedtls.c b/lib/vtls/mbedtls.c index 159fa6c6667..7d70de53bd2 100644 --- a/lib/vtls/mbedtls.c +++ b/lib/vtls/mbedtls.c @@ -36,6 +36,13 @@ /* Define this to enable lots of debugging for mbedTLS */ /* #define MBEDTLS_DEBUG */ +#ifdef __GNUC__ +#pragma GCC diagnostic push +/* mbedTLS (as of v3.5.1) has a duplicate function declaration + in its public headers. Disable the warning that detects it. */ +#pragma GCC diagnostic ignored "-Wredundant-decls" +#endif + #include #if MBEDTLS_VERSION_NUMBER >= 0x02040000 #include @@ -56,6 +63,10 @@ # endif #endif +#ifdef __GNUC__ +#pragma GCC diagnostic pop +#endif + #include "urldata.h" #include "sendf.h" #include "inet_pton.h" @@ -154,7 +165,6 @@ static void mbed_debug(void *context, int level, const char *f_name, infof(data, "%s", line); (void) level; } -#else #endif static int mbedtls_bio_cf_write(void *bio, @@ -166,6 +176,9 @@ static int mbedtls_bio_cf_write(void *bio, CURLcode result; DEBUGASSERT(data); + if(!data) + return 0; + nwritten = Curl_conn_cf_send(cf->next, data, (char *)buf, blen, &result); CURL_TRC_CF(data, cf, "mbedtls_bio_cf_out_write(len=%zu) -> %zd, err=%d", blen, nwritten, result); @@ -183,6 +196,8 @@ static int mbedtls_bio_cf_read(void *bio, unsigned char *buf, size_t blen) CURLcode result; DEBUGASSERT(data); + if(!data) + return 0; /* OpenSSL catches this case, so should we. */ if(!buf) return 0; From 48aaab55a58c100c8c289a55dbeda5e2099592e5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 17 Jan 2024 09:42:54 +0100 Subject: [PATCH 188/509] curl_easy_getinfo.3: remove the wrong time value count It said "six" time values but they are eight by now. Remove the mention of the amount. Closes #12727 --- docs/libcurl/curl_easy_getinfo.3 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 153551f10a8..1c12cf419e4 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -190,16 +190,16 @@ See \fICURLINFO_OS_ERRNO(3)\fP Number of new successful connections used for previous transfer. See \fICURLINFO_NUM_CONNECTS(3)\fP .IP CURLINFO_PRIMARY_IP -IP address of the last connection. +Destination IP address of the last connection. See \fICURLINFO_PRIMARY_IP(3)\fP .IP CURLINFO_PRIMARY_PORT -Port of the last connection. +Destination port of the last connection. See \fICURLINFO_PRIMARY_PORT(3)\fP .IP CURLINFO_LOCAL_IP -Local-end IP address of last connection. +Source IP address of the last connection. See \fICURLINFO_LOCAL_IP(3)\fP .IP CURLINFO_LOCAL_PORT -Local-end port of last connection. +Source port number of the last connection. See \fICURLINFO_LOCAL_PORT(3)\fP .IP CURLINFO_COOKIELIST List of all known cookies. @@ -257,7 +257,7 @@ See \fICURLINFO_CONN_ID(3)\fP The ID of the transfer. (Added in 8.2.0) See \fICURLINFO_XFER_ID(3)\fP .SH TIMES -An overview of the six time values available from \fIcurl_easy_getinfo(3)\fP +An overview of the time values available from \fIcurl_easy_getinfo(3)\fP .nf curl_easy_perform() From c8cffcb8d45449b3b9b7ce48d3e8ee24ceb3e6b2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 16 Jan 2024 23:50:02 +0100 Subject: [PATCH 189/509] headers: remove assert from Curl_headers_push The fuzzer managed to reach the function without a terminating CR or LF so let's handle it normally. While there, remove the goto. Bug: https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65839 Closes #12721 --- lib/headers.c | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/lib/headers.c b/lib/headers.c index 9c29238993a..8a3264ab566 100644 --- a/lib/headers.c +++ b/lib/headers.c @@ -291,9 +291,9 @@ CURLcode Curl_headers_push(struct Curl_easy *data, const char *header, end = strchr(header, '\r'); if(!end) { end = strchr(header, '\n'); - DEBUGASSERT(end); if(!end) - return CURLE_BAD_FUNCTION_ARGUMENT; + /* neither CR nor LF as terminator is not a valid header */ + return CURLE_WEIRD_SERVER_REPLY; } hlen = end - header; @@ -320,21 +320,19 @@ CURLcode Curl_headers_push(struct Curl_easy *data, const char *header, hs->buffer[hlen] = 0; /* nul terminate */ result = namevalue(hs->buffer, hlen, type, &name, &value); - if(result) - goto fail; - - hs->name = name; - hs->value = value; - hs->type = type; - hs->request = data->state.requests; - - /* insert this node into the list of headers */ - Curl_llist_insert_next(&data->state.httphdrs, data->state.httphdrs.tail, - hs, &hs->node); - data->state.prevhead = hs; - return CURLE_OK; -fail: - free(hs); + if(!result) { + hs->name = name; + hs->value = value; + hs->type = type; + hs->request = data->state.requests; + + /* insert this node into the list of headers */ + Curl_llist_insert_next(&data->state.httphdrs, data->state.httphdrs.tail, + hs, &hs->node); + data->state.prevhead = hs; + } + else + free(hs); return result; } From 524253dc9078e69300c5390eda496603067f325f Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 19 Jan 2024 10:15:03 +0100 Subject: [PATCH 190/509] rtsp: Convert assertion into debug log Bug: https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65934 - write excess bytes to the client where the standard excess bytes checks will report any wrongness and fail the transfer Fixes #12738 Closes #12739 --- lib/rtsp.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/rtsp.c b/lib/rtsp.c index dba8ae7a67b..26f47353447 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -804,7 +804,9 @@ static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, buf += consumed; blen -= consumed; /* either we consumed all or are at the start of header parsing */ - DEBUGASSERT(blen == 0 || data->req.header); + if(blen && !data->req.header) + DEBUGF(infof(data, "RTSP: %zu bytes, possibly excess in response body", + blen)); } /* we want to parse headers, do so */ From 42be71e3edbc721713fd8bfb8c0701fa4b544819 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 19 Jan 2024 16:37:14 +0100 Subject: [PATCH 191/509] cmdline-opts/write-out.d: remove spurious double quotes --- docs/cmdline-opts/write-out.d | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d index 5975c8e2d56..4b0d7c8ca9a 100644 --- a/docs/cmdline-opts/write-out.d +++ b/docs/cmdline-opts/write-out.d @@ -121,7 +121,7 @@ Number of redirects that were followed in the request. (Added in 7.12.3) The rest of the output is only shown if the transfer returned a non-zero error. (Added in 7.75.0) -## "proxy_ssl_verify_result" +## proxy_ssl_verify_result The result of the HTTPS proxy's SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.52.0) From ed420d9329f755fc33d6cbcb6139baf2812dec87 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 19 Jan 2024 15:03:50 +0100 Subject: [PATCH 192/509] cmake: when USE_MANUAL=YES, build the curl.1 man page Fixes KNOWN_BUG 15.4 Closes #12742 --- docs/KNOWN_BUGS | 7 ------- docs/cmdline-opts/CMakeLists.txt | 3 +-- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 254bc8479f5..f91ff63bb64 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -92,7 +92,6 @@ 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 @@ -528,12 +527,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 diff --git a/docs/cmdline-opts/CMakeLists.txt b/docs/cmdline-opts/CMakeLists.txt index 3dd8be49b19..e6221855f94 100644 --- a/docs/cmdline-opts/CMakeLists.txt +++ b/docs/cmdline-opts/CMakeLists.txt @@ -28,8 +28,7 @@ transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc. 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}" "./gen.pl" mainpage ${DPAGES} > "${MANPAGE}" VERBATIM ) add_custom_target(generate-curl.1 DEPENDS "${MANPAGE}") From ca01aca878e096f68482c8b7b4be5fca657eb026 Mon Sep 17 00:00:00 2001 From: Mohammadreza Hendiani Date: Fri, 19 Jan 2024 17:29:03 +0330 Subject: [PATCH 193/509] TODO: update broken link to ratelimit-headers draft Closes #12741 --- docs/TODO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TODO b/docs/TODO index d89b080d0ca..162944360d9 100644 --- a/docs/TODO +++ b/docs/TODO @@ -1116,7 +1116,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 From f81a335e85ba625c92da5738cb7b693cd71662ad Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sun, 21 Jan 2024 15:38:09 +0000 Subject: [PATCH 194/509] cmake: fix `ENABLE_MANUAL` option Fix the `ENABLE_MANUAL` option. Set it to default to `OFF`. Before this patch `ENABLE_MANUAL=ON` was a no-op, even though it was the option designed to enable building and using the built-in curl manual. (`USE_MANUAL=ON` option worked for this instead, by accident). Ref: https://github.com/curl/curl/pull/12730#issuecomment-1902572409 Closes #12749 --- CMakeLists.txt | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 3a6ae3d42a7..70ca457a969 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -304,18 +304,15 @@ 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(ENABLE_MANUAL "to provide the built-in manual" OFF) -if(ENABLE_MANUAL) - set(USE_MANUAL ON) +if(ENABLE_MANUAL AND PERL_FOUND) + curl_nroff_check() + if(NROFF_USEFUL) + set(USE_MANUAL ON) + endif() endif() if(CURL_STATIC_CRT) From 0535f6ec71cf950d7ad412b19ed706fcc7e4a7a9 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 18 Jan 2024 13:07:07 +0100 Subject: [PATCH 195/509] http3: initial support for OpenSSL 3.2 QUIC stack - HTTP/3 for curl using OpenSSL's own QUIC stack together with nghttp3 - configure with `--with-openssl-quic` to enable curl to build this. This requires the nghttp3 library - implementation with the following restrictions: * macOS has to use an unconnected UDP socket due to an issue in OpenSSL's datagram implementation See https://github.com/openssl/openssl/issues/23251 This makes connections to non-reponsive servers hang. * GET requests will send the indicator that they have no body in a separate QUIC packet. This may result in processing delays or Transfer-Encodings on proxied requests * uploads that encounter blocks will use 100% cpu as detection of these flow control issue is not working (we have not figured out to pry that from OpenSSL). Closes #12734 --- .github/workflows/osslq-linux.yml | 233 +++ configure.ac | 81 +- docs/HTTP3.md | 36 + lib/Makefile.inc | 2 + lib/cf-socket.c | 6 + lib/curl_setup.h | 1 + lib/vquic/curl_osslq.c | 2239 +++++++++++++++++++++++++++++ lib/vquic/curl_osslq.h | 51 + lib/vquic/vquic-tls.c | 6 + lib/vquic/vquic.c | 7 + m4/curl-openssl.m4 | 19 + tests/http/scorecard.py | 2 +- tests/http/test_08_caddy.py | 17 + tests/http/test_14_auth.py | 6 +- tests/http/testenv/nghttpx.py | 8 +- 15 files changed, 2698 insertions(+), 16 deletions(-) create mode 100644 .github/workflows/osslq-linux.yml create mode 100644 lib/vquic/curl_osslq.c create mode 100644 lib/vquic/curl_osslq.h diff --git a/.github/workflows/osslq-linux.yml b/.github/workflows/osslq-linux.yml new file mode 100644 index 00000000000..cda12616e21 --- /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.1.0 + nghttp2-version: master + mod_h2-version: v2.0.25 + +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@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: 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@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: 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 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 + 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: + # 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/configure.ac b/configure.ac index 092fcb6f98d..99e00514a1b 100644 --- a/configure.ac +++ b/configure.ac @@ -175,7 +175,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" @@ -3001,14 +3001,53 @@ 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" = "x" -a "$USE_OPENSSL_QUIC" = "x"; then + # without ngtcp2 or openssl quic, nghttp3 is of no use for us OPT_NGHTTP3="no" fi @@ -3036,10 +3075,6 @@ esac curl_http3_msg="no (--with-nghttp3)" if test X"$want_nghttp3" != Xno; then - if test "$NGTCP2_ENABLED" != "1"; then - AC_MSG_ERROR([--with-nghttp3 also requires --with-ntcp2]) - fi - dnl backup the pre-nghttp3 variables CLEANLDFLAGS="$LDFLAGS" CLEANCPPFLAGS="$CPPFLAGS" @@ -3070,8 +3105,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" @@ -3096,6 +3129,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 ********************************************************************** @@ -3245,6 +3301,9 @@ if test X"$want_msh3" != Xno; then 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" @@ -4575,8 +4634,8 @@ 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 SUPPORT_FEATURES="$SUPPORT_FEATURES HTTP3" fi diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 7f2f08ada37..6d84778c138 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 @@ -193,6 +195,40 @@ Build curl: If `make install` results in `Permission denied` error, you will need to prepend it with `sudo`. +# OpenSSL version + +quiche 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 install + +Build nghttp3 + + % cd .. + % git clone -b v1.1.0 https://github.com/ngtcp2/nghttp3 + % cd nghttp3 + % autoreconf -fi + % ./configure --prefix= --enable-lib-only + % make + % make install + +Build curl: + + % cd .. + % git clone https://github.com/curl/curl + % cd curl + % autoreconf -fi + % ./configure --with-openssl= --with-openssl-quic --with-nghttp3= + % make + % make install + + If `make install` results in `Permission denied` error, you will need to prepend it with `sudo`. + # msh3 (msquic) version **Note**: The msquic HTTP/3 backend is immature and is not properly functional diff --git a/lib/Makefile.inc b/lib/Makefile.inc index d937e1ed0c1..627148abeb4 100644 --- a/lib/Makefile.inc +++ b/lib/Makefile.inc @@ -78,6 +78,7 @@ LIB_VTLS_HFILES = \ LIB_VQUIC_CFILES = \ vquic/curl_msh3.c \ vquic/curl_ngtcp2.c \ + vquic/curl_osslq.c \ vquic/curl_quiche.c \ vquic/vquic.c \ vquic/vquic-tls.c @@ -85,6 +86,7 @@ LIB_VQUIC_CFILES = \ LIB_VQUIC_HFILES = \ vquic/curl_msh3.h \ vquic/curl_ngtcp2.h \ + vquic/curl_osslq.h \ vquic/curl_quiche.h \ vquic/vquic.h \ vquic/vquic_int.h \ diff --git a/lib/cf-socket.c b/lib/cf-socket.c index 64af604ad30..742902f1b9b 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -1630,11 +1630,17 @@ static CURLcode cf_udp_setup_quic(struct Curl_cfilter *cf, /* QUIC needs a connected socket, nonblocking */ DEBUGASSERT(ctx->sock != CURL_SOCKET_BAD); +#if defined(__APPLE__) && defined(USE_OPENSSL_QUIC) + (void)rc; + /* On macOS OpenSSL QUIC fails on connected sockets. + * see: */ +#else rc = connect(ctx->sock, &ctx->addr.sa_addr, ctx->addr.addrlen); if(-1 == rc) { return socket_connect_result(data, ctx->r_ip, SOCKERRNO); } ctx->sock_connected = TRUE; +#endif set_local_ip(cf, data); CURL_TRC_CF(data, cf, "%s socket %" CURL_FORMAT_SOCKET_T " connected: [%s:%d] -> [%s:%d]", diff --git a/lib/curl_setup.h b/lib/curl_setup.h index 551243e2700..91e35f58b4d 100644 --- a/lib/curl_setup.h +++ b/lib/curl_setup.h @@ -827,6 +827,7 @@ int getpwuid_r(uid_t uid, struct passwd *pwd, char *buf, #endif #if (defined(USE_NGTCP2) && defined(USE_NGHTTP3)) || \ + (defined(USE_OPENSSL_QUIC) && defined(USE_NGHTTP3)) || \ defined(USE_QUICHE) || defined(USE_MSH3) #define ENABLE_QUIC #define USE_HTTP3 diff --git a/lib/vquic/curl_osslq.c b/lib/vquic/curl_osslq.c new file mode 100644 index 00000000000..41f08924759 --- /dev/null +++ b/lib/vquic/curl_osslq.c @@ -0,0 +1,2239 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +#include "curl_setup.h" + +#if defined(USE_OPENSSL_QUIC) && defined(USE_NGHTTP3) + +#include +#include +#include +#include + +#include "urldata.h" +#include "sendf.h" +#include "strdup.h" +#include "rand.h" +#include "multiif.h" +#include "strcase.h" +#include "cfilters.h" +#include "cf-socket.h" +#include "connect.h" +#include "progress.h" +#include "strerror.h" +#include "dynbuf.h" +#include "http1.h" +#include "select.h" +#include "inet_pton.h" +#include "vquic.h" +#include "vquic_int.h" +#include "vquic-tls.h" +#include "vtls/keylog.h" +#include "vtls/vtls.h" +#include "vtls/openssl.h" +#include "curl_osslq.h" + +#include "warnless.h" + +/* The last 3 #include files should be in this order */ +#include "curl_printf.h" +#include "curl_memory.h" +#include "memdebug.h" + +/* A stream window is the maximum amount we need to buffer for + * each active transfer. We use HTTP/3 flow control and only ACK + * when we take things out of the buffer. + * Chunk size is large enough to take a full DATA frame */ +#define H3_STREAM_WINDOW_SIZE (128 * 1024) +#define H3_STREAM_CHUNK_SIZE (16 * 1024) +/* The pool keeps spares around and half of a full stream windows + * seems good. More does not seem to improve performance. + * The benefit of the pool is that stream buffer to not keep + * spares. So memory consumption goes down when streams run empty, + * have a large upload done, etc. */ +#define H3_STREAM_POOL_SPARES \ + (H3_STREAM_WINDOW_SIZE / H3_STREAM_CHUNK_SIZE ) / 2 +/* Receive and Send max number of chunks just follows from the + * chunk size and window size */ +#define H3_STREAM_RECV_CHUNKS \ + (H3_STREAM_WINDOW_SIZE / H3_STREAM_CHUNK_SIZE) +#define H3_STREAM_SEND_CHUNKS \ + (H3_STREAM_WINDOW_SIZE / H3_STREAM_CHUNK_SIZE) + +#ifndef ARRAYSIZE +#define ARRAYSIZE(A) (sizeof(A)/sizeof((A)[0])) +#endif + +#if defined(OPENSSL_IS_BORINGSSL) || defined(OPENSSL_IS_AWSLC) +typedef uint32_t sslerr_t; +#else +typedef unsigned long sslerr_t; +#endif + + +/* How to access `call_data` from a cf_osslq filter */ +#undef CF_CTX_CALL_DATA +#define CF_CTX_CALL_DATA(cf) \ + ((struct cf_osslq_ctx *)(cf)->ctx)->call_data + +static CURLcode cf_progress_ingress(struct Curl_cfilter *cf, + struct Curl_easy *data); + +static const char *SSL_ERROR_to_str(int err) +{ + switch(err) { + case SSL_ERROR_NONE: + return "SSL_ERROR_NONE"; + case SSL_ERROR_SSL: + return "SSL_ERROR_SSL"; + case SSL_ERROR_WANT_READ: + return "SSL_ERROR_WANT_READ"; + case SSL_ERROR_WANT_WRITE: + return "SSL_ERROR_WANT_WRITE"; + case SSL_ERROR_WANT_X509_LOOKUP: + return "SSL_ERROR_WANT_X509_LOOKUP"; + case SSL_ERROR_SYSCALL: + return "SSL_ERROR_SYSCALL"; + case SSL_ERROR_ZERO_RETURN: + return "SSL_ERROR_ZERO_RETURN"; + case SSL_ERROR_WANT_CONNECT: + return "SSL_ERROR_WANT_CONNECT"; + case SSL_ERROR_WANT_ACCEPT: + return "SSL_ERROR_WANT_ACCEPT"; +#if defined(SSL_ERROR_WANT_ASYNC) + case SSL_ERROR_WANT_ASYNC: + return "SSL_ERROR_WANT_ASYNC"; +#endif +#if defined(SSL_ERROR_WANT_ASYNC_JOB) + case SSL_ERROR_WANT_ASYNC_JOB: + return "SSL_ERROR_WANT_ASYNC_JOB"; +#endif +#if defined(SSL_ERROR_WANT_EARLY) + case SSL_ERROR_WANT_EARLY: + return "SSL_ERROR_WANT_EARLY"; +#endif + default: + return "SSL_ERROR unknown"; + } +} + +/* Return error string for last OpenSSL error */ +static char *ossl_strerror(unsigned long error, char *buf, size_t size) +{ + DEBUGASSERT(size); + *buf = '\0'; + +#if defined(OPENSSL_IS_BORINGSSL) || defined(OPENSSL_IS_AWSLC) + ERR_error_string_n((uint32_t)error, buf, size); +#else + ERR_error_string_n(error, buf, size); +#endif + + if(!*buf) { + const char *msg = error ? "Unknown error" : "No error"; + if(strlen(msg) < size) + strcpy(buf, msg); + } + + return buf; +} + +static CURLcode make_bio_addr(BIO_ADDR **pbio_addr, + const struct Curl_sockaddr_ex *addr) +{ + BIO_ADDR *ba; + CURLcode result = CURLE_FAILED_INIT; + + ba = BIO_ADDR_new(); + if(!ba) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } + + switch(addr->family) { + case AF_INET: { + struct sockaddr_in * const sin = + (struct sockaddr_in * const)(void *)&addr->sa_addr; + if(!BIO_ADDR_rawmake(ba, AF_INET, &sin->sin_addr, + sizeof(sin->sin_addr), sin->sin_port)) { + goto out; + } + result = CURLE_OK; + break; + } +#ifdef ENABLE_IPV6 + case AF_INET6: { + struct sockaddr_in6 * const sin = + (struct sockaddr_in6 * const)(void *)&addr->sa_addr; + if(!BIO_ADDR_rawmake(ba, AF_INET6, &sin->sin6_addr, + sizeof(sin->sin6_addr), sin->sin6_port)) { + } + result = CURLE_OK; + break; + } +#endif /* ENABLE_IPV6 */ + default: + /* sunsupported */ + DEBUGASSERT(0); + break; + } + +out: + if(result && ba) { + BIO_ADDR_free(ba); + ba = NULL; + } + *pbio_addr = ba; + return result; +} + +/* QUIC stream (not necessarily H3) */ +struct cf_osslq_stream { + int64_t id; + SSL *ssl; + struct bufq recvbuf; /* QUIC war data recv buffer */ + BIT(recvd_eos); + BIT(closed); + BIT(reset); + BIT(send_blocked); +}; + +static CURLcode cf_osslq_stream_open(struct cf_osslq_stream *s, + SSL *conn, + uint64_t flags, + struct bufc_pool *bufcp, + void *user_data) +{ + DEBUGASSERT(!s->ssl); + Curl_bufq_initp(&s->recvbuf, bufcp, 1, BUFQ_OPT_NONE); + s->ssl = SSL_new_stream(conn, flags); + if(!s->ssl) { + return CURLE_FAILED_INIT; + } + s->id = SSL_get_stream_id(s->ssl); + SSL_set_app_data(s->ssl, user_data); + return CURLE_OK; +} + +static void cf_osslq_stream_cleanup(struct cf_osslq_stream *s) +{ + if(s->ssl) { + SSL_set_app_data(s->ssl, NULL); + SSL_free(s->ssl); + } + Curl_bufq_free(&s->recvbuf); + memset(s, 0, sizeof(*s)); +} + +static void cf_osslq_stream_close(struct cf_osslq_stream *s) +{ + if(s->ssl) { + SSL_free(s->ssl); + s->ssl = NULL; + } +} + +struct cf_osslq_h3conn { + nghttp3_conn *conn; + nghttp3_settings settings; + struct cf_osslq_stream s_ctrl; + struct cf_osslq_stream s_qpack_enc; + struct cf_osslq_stream s_qpack_dec; + struct cf_osslq_stream remote_ctrl[3]; /* uni streams opened by the peer */ + size_t remote_ctrl_n; /* number of peer streams opened */ +}; + +static void cf_osslq_h3conn_cleanup(struct cf_osslq_h3conn *h3) +{ + size_t i; + + if(h3->conn) + nghttp3_conn_del(h3->conn); + cf_osslq_stream_cleanup(&h3->s_ctrl); + cf_osslq_stream_cleanup(&h3->s_qpack_enc); + cf_osslq_stream_cleanup(&h3->s_qpack_dec); + for(i = 0; i < h3->remote_ctrl_n; ++i) { + cf_osslq_stream_cleanup(&h3->remote_ctrl[i]); + } +} + +struct cf_osslq_ctx { + struct cf_quic_ctx q; + struct ssl_peer peer; + struct quic_tls_ctx tls; + struct cf_call_data call_data; + struct cf_osslq_h3conn h3; + struct curltime started_at; /* time the current attempt started */ + struct curltime handshake_at; /* time connect handshake finished */ + struct curltime first_byte_at; /* when first byte was recvd */ + struct curltime reconnect_at; /* time the next attempt should start */ + struct bufc_pool stream_bufcp; /* chunk pool for streams */ + size_t max_stream_window; /* max flow window for one stream */ + uint64_t max_idle_ms; /* max idle time for QUIC connection */ + BIT(got_first_byte); /* if first byte was received */ +#ifdef USE_OPENSSL + BIT(x509_store_setup); /* if x509 store has been set up */ + BIT(protocol_shutdown); /* QUIC connection is shut down */ +#endif +}; + +static void cf_osslq_ctx_clear(struct cf_osslq_ctx *ctx) +{ + struct cf_call_data save = ctx->call_data; + + cf_osslq_h3conn_cleanup(&ctx->h3); + Curl_vquic_tls_cleanup(&ctx->tls); + vquic_ctx_free(&ctx->q); + Curl_bufcp_free(&ctx->stream_bufcp); + Curl_ssl_peer_cleanup(&ctx->peer); + + memset(ctx, 0, sizeof(*ctx)); + ctx->call_data = save; +} + +static void cf_osslq_close(struct Curl_cfilter *cf, struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct cf_call_data save; + + CF_DATA_SAVE(save, cf, data); + if(ctx && ctx->tls.ssl) { + /* TODO: send connection close */ + CURL_TRC_CF(data, cf, "cf_osslq_close()"); + cf_osslq_ctx_clear(ctx); + } + + cf->connected = FALSE; + CF_DATA_RESTORE(cf, save); +} + +static void cf_osslq_destroy(struct Curl_cfilter *cf, struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct cf_call_data save; + + CF_DATA_SAVE(save, cf, data); + CURL_TRC_CF(data, cf, "destroy"); + if(ctx) { + CURL_TRC_CF(data, cf, "cf_osslq_destroy()"); + cf_osslq_ctx_clear(ctx); + free(ctx); + } + cf->ctx = NULL; + /* No CF_DATA_RESTORE(cf, save) possible */ + (void)save; +} + +static CURLcode cf_osslq_h3conn_add_stream(struct cf_osslq_h3conn *h3, + SSL *stream_ssl, + struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + int64_t stream_id = SSL_get_stream_id(stream_ssl); + + if(h3->remote_ctrl_n >= ARRAYSIZE(h3->remote_ctrl)) { + /* rejected, we are full */ + CURL_TRC_CF(data, cf, "[%" PRId64 "] rejecting additional remote stream", + stream_id); + SSL_free(stream_ssl); + return CURLE_FAILED_INIT; + } + switch(SSL_get_stream_type(stream_ssl)) { + case SSL_STREAM_TYPE_READ: { + struct cf_osslq_stream *nstream = &h3->remote_ctrl[h3->remote_ctrl_n++]; + nstream->id = stream_id; + nstream->ssl = stream_ssl; + Curl_bufq_initp(&nstream->recvbuf, &ctx->stream_bufcp, 1, BUFQ_OPT_NONE); + CURL_TRC_CF(data, cf, "[%" PRId64 "] accepted new remote uni stream", + stream_id); + break; + } + default: + CURL_TRC_CF(data, cf, "[%" PRId64 "] rejecting remote non-uni-read" + " stream", stream_id); + SSL_free(stream_ssl); + return CURLE_FAILED_INIT; + } + return CURLE_OK; + +} + +static CURLcode cf_osslq_ssl_err(struct Curl_cfilter *cf, + struct Curl_easy *data, + int detail, CURLcode def_result) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result = def_result; + sslerr_t errdetail; + char ebuf[256] = "unknown"; + const char *err_descr = ebuf; + long lerr; + int lib; + int reason; + struct ssl_config_data *ssl_config = Curl_ssl_cf_get_config(cf, data); + + errdetail = ERR_get_error(); + lib = ERR_GET_LIB(errdetail); + reason = ERR_GET_REASON(errdetail); + + if((lib == ERR_LIB_SSL) && + ((reason == SSL_R_CERTIFICATE_VERIFY_FAILED) || + (reason == SSL_R_SSLV3_ALERT_CERTIFICATE_EXPIRED))) { + result = CURLE_PEER_FAILED_VERIFICATION; + + lerr = SSL_get_verify_result(ctx->tls.ssl); + if(lerr != X509_V_OK) { + ssl_config->certverifyresult = lerr; + msnprintf(ebuf, sizeof(ebuf), + "SSL certificate problem: %s", + X509_verify_cert_error_string(lerr)); + } + else + err_descr = "SSL certificate verification failed"; + } +#if defined(SSL_R_TLSV13_ALERT_CERTIFICATE_REQUIRED) + /* SSL_R_TLSV13_ALERT_CERTIFICATE_REQUIRED is only available on + OpenSSL version above v1.1.1, not LibreSSL, BoringSSL, or AWS-LC */ + else if((lib == ERR_LIB_SSL) && + (reason == SSL_R_TLSV13_ALERT_CERTIFICATE_REQUIRED)) { + /* If client certificate is required, communicate the + error to client */ + result = CURLE_SSL_CLIENTCERT; + ossl_strerror(errdetail, ebuf, sizeof(ebuf)); + } +#endif + else if((lib == ERR_LIB_SSL) && (reason == SSL_R_PROTOCOL_IS_SHUTDOWN)) { + ctx->protocol_shutdown = TRUE; + err_descr = "QUIC connectin has been shut down"; + result = def_result; + } + else { + result = def_result; + ossl_strerror(errdetail, ebuf, sizeof(ebuf)); + } + + /* detail is already set to the SSL error above */ + + /* If we e.g. use SSLv2 request-method and the server doesn't like us + * (RST connection, etc.), OpenSSL gives no explanation whatsoever and + * the SO_ERROR is also lost. + */ + if(CURLE_SSL_CONNECT_ERROR == result && errdetail == 0) { + char extramsg[80]=""; + int sockerr = SOCKERRNO; + const char *r_ip = NULL; + int r_port = 0; + + Curl_cf_socket_peek(cf->next, data, NULL, NULL, + &r_ip, &r_port, NULL, NULL); + if(sockerr && detail == SSL_ERROR_SYSCALL) + Curl_strerror(sockerr, extramsg, sizeof(extramsg)); + failf(data, "QUIC connect: %s in connection to %s:%d (%s)", + extramsg[0] ? extramsg : SSL_ERROR_to_str(detail), + ctx->peer.dispname, r_port, r_ip); + } + else { + /* Could be a CERT problem */ + failf(data, "%s", err_descr); + } + return result; +} + +static CURLcode cf_osslq_verify_peer(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + + cf->conn->bits.multiplex = TRUE; /* at least potentially multiplexed */ + cf->conn->httpversion = 30; + cf->conn->bundle->multiuse = BUNDLE_MULTIPLEX; + + return Curl_vquic_tls_verify_peer(&ctx->tls, cf, data, &ctx->peer); +} + +/** + * All about the H3 internals of a stream + */ +struct h3_stream_ctx { + struct cf_osslq_stream s; + struct bufq sendbuf; /* h3 request body */ + struct bufq recvbuf; /* h3 response body */ + struct h1_req_parser h1; /* h1 request parsing */ + size_t sendbuf_len_in_flight; /* sendbuf amount "in flight" */ + size_t upload_blocked_len; /* the amount written last and EGAINed */ + size_t recv_buf_nonflow; /* buffered bytes, not counting for flow control */ + uint64_t error3; /* HTTP/3 stream error code */ + curl_off_t upload_left; /* number of request bytes left to upload */ + curl_off_t download_recvd; /* number of response DATA bytes received */ + int status_code; /* HTTP status code */ + bool resp_hds_complete; /* we have a complete, final response */ + bool closed; /* TRUE on stream close */ + bool reset; /* TRUE on stream reset */ + bool send_closed; /* stream is local closed */ + BIT(quic_flow_blocked); /* stream is blocked by QUIC flow control */ +}; + +#define H3_STREAM_CTX(d) ((struct h3_stream_ctx *)(((d) && (d)->req.p.http)? \ + ((struct HTTP *)(d)->req.p.http)->h3_ctx \ + : NULL)) +#define H3_STREAM_LCTX(d) ((struct HTTP *)(d)->req.p.http)->h3_ctx +#define H3_STREAM_ID(d) (H3_STREAM_CTX(d)? \ + H3_STREAM_CTX(d)->s.id : -2) + +static CURLcode h3_data_setup(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + + if(!data || !data->req.p.http) { + failf(data, "initialization failure, transfer not http initialized"); + return CURLE_FAILED_INIT; + } + + if(stream) + return CURLE_OK; + + stream = calloc(1, sizeof(*stream)); + if(!stream) + return CURLE_OUT_OF_MEMORY; + + stream->s.id = -1; + /* on send, we control how much we put into the buffer */ + Curl_bufq_initp(&stream->sendbuf, &ctx->stream_bufcp, + H3_STREAM_SEND_CHUNKS, BUFQ_OPT_NONE); + stream->sendbuf_len_in_flight = 0; + /* on recv, we need a flexible buffer limit since we also write + * headers to it that are not counted against the nghttp3 flow limits. */ + Curl_bufq_initp(&stream->recvbuf, &ctx->stream_bufcp, + H3_STREAM_RECV_CHUNKS, BUFQ_OPT_SOFT_LIMIT); + stream->recv_buf_nonflow = 0; + Curl_h1_req_parse_init(&stream->h1, H1_PARSE_DEFAULT_MAX_LINE_LEN); + + H3_STREAM_LCTX(data) = stream; + return CURLE_OK; +} + +static void h3_data_done(struct Curl_cfilter *cf, struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + + (void)cf; + if(stream) { + CURL_TRC_CF(data, cf, "[%"PRId64"] easy handle is done", stream->s.id); + if(ctx->h3.conn && !stream->closed) { + nghttp3_conn_shutdown_stream_read(ctx->h3.conn, stream->s.id); + nghttp3_conn_close_stream(ctx->h3.conn, stream->s.id, + NGHTTP3_H3_REQUEST_CANCELLED); + nghttp3_conn_set_stream_user_data(ctx->h3.conn, stream->s.id, NULL); + stream->closed = TRUE; + } + + cf_osslq_stream_cleanup(&stream->s); + Curl_bufq_free(&stream->sendbuf); + Curl_bufq_free(&stream->recvbuf); + Curl_h1_req_parse_free(&stream->h1); + free(stream); + H3_STREAM_LCTX(data) = NULL; + } +} + +static struct cf_osslq_stream *cf_osslq_get_qstream(struct Curl_cfilter *cf, + struct Curl_easy *data, + int64_t stream_id) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + struct Curl_easy *sdata; + + if(stream && stream->s.id == stream_id) { + return &stream->s; + } + else if(ctx->h3.s_ctrl.id == stream_id) { + return &ctx->h3.s_ctrl; + } + else if(ctx->h3.s_qpack_enc.id == stream_id) { + return &ctx->h3.s_qpack_enc; + } + else if(ctx->h3.s_qpack_dec.id == stream_id) { + return &ctx->h3.s_qpack_dec; + } + else { + DEBUGASSERT(data->multi); + for(sdata = data->multi->easyp; sdata; sdata = sdata->next) { + if((sdata->conn == data->conn) && H3_STREAM_ID(sdata) == stream_id) { + stream = H3_STREAM_CTX(sdata); + return stream? &stream->s : NULL; + } + } + } + return NULL; +} + +static void h3_drain_stream(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + unsigned char bits; + + (void)cf; + bits = CURL_CSELECT_IN; + if(stream && stream->upload_left && !stream->send_closed) + bits |= CURL_CSELECT_OUT; + if(data->state.select_bits != bits) { + data->state.select_bits = bits; + Curl_expire(data, 0, EXPIRE_RUN_NOW); + } +} + +static CURLcode h3_data_pause(struct Curl_cfilter *cf, + struct Curl_easy *data, + bool pause) +{ + if(!pause) { + /* unpaused. make it run again right away */ + h3_drain_stream(cf, data); + Curl_expire(data, 0, EXPIRE_RUN_NOW); + } + return CURLE_OK; +} + +static int cb_h3_stream_close(nghttp3_conn *conn, int64_t stream_id, + uint64_t app_error_code, void *user_data, + void *stream_user_data) +{ + struct Curl_cfilter *cf = user_data; + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + (void)conn; + (void)stream_id; + + /* we might be called by nghttp3 after we already cleaned up */ + if(!stream) + return 0; + + stream->closed = TRUE; + stream->error3 = app_error_code; + if(stream->error3 != NGHTTP3_H3_NO_ERROR) { + stream->reset = TRUE; + stream->send_closed = TRUE; + CURL_TRC_CF(data, cf, "[%" PRId64 "] RESET: error %" PRId64, + stream->s.id, stream->error3); + } + else { + CURL_TRC_CF(data, cf, "[%" PRId64 "] CLOSED", stream->s.id); + } + h3_drain_stream(cf, data); + return 0; +} + +/* + * write_resp_raw() copies response data in raw format to the `data`'s + * receive buffer. If not enough space is available, it appends to the + * `data`'s overflow buffer. + */ +static CURLcode write_resp_raw(struct Curl_cfilter *cf, + struct Curl_easy *data, + const void *mem, size_t memlen, + bool flow) +{ + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + CURLcode result = CURLE_OK; + ssize_t nwritten; + + (void)cf; + if(!stream) { + return CURLE_RECV_ERROR; + } + nwritten = Curl_bufq_write(&stream->recvbuf, mem, memlen, &result); + if(nwritten < 0) { + return result; + } + + if(!flow) + stream->recv_buf_nonflow += (size_t)nwritten; + + if((size_t)nwritten < memlen) { + /* This MUST not happen. Our recbuf is dimensioned to hold the + * full max_stream_window and then some for this very reason. */ + DEBUGASSERT(0); + return CURLE_RECV_ERROR; + } + return result; +} + +static int cb_h3_recv_data(nghttp3_conn *conn, int64_t stream3_id, + const uint8_t *buf, size_t buflen, + void *user_data, void *stream_user_data) +{ + struct Curl_cfilter *cf = user_data; + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + CURLcode result; + + (void)conn; + (void)stream3_id; + + if(!stream) + return NGHTTP3_ERR_CALLBACK_FAILURE; + + result = write_resp_raw(cf, data, buf, buflen, TRUE); + if(result) { + CURL_TRC_CF(data, cf, "[%" PRId64 "] DATA len=%zu, ERROR receiving %d", + stream->s.id, buflen, result); + return NGHTTP3_ERR_CALLBACK_FAILURE; + } + stream->download_recvd += (curl_off_t)buflen; + CURL_TRC_CF(data, cf, "[%" PRId64 "] DATA len=%zu, total=%zd", + stream->s.id, buflen, stream->download_recvd); + h3_drain_stream(cf, data); + return 0; +} + +static int cb_h3_deferred_consume(nghttp3_conn *conn, int64_t stream_id, + size_t consumed, void *user_data, + void *stream_user_data) +{ + struct Curl_cfilter *cf = user_data; + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + + (void)conn; + (void)stream_id; + if(stream) + CURL_TRC_CF(data, cf, "[%" PRId64 "] deferred consume %zu bytes", + stream->s.id, consumed); + return 0; +} + +static int cb_h3_recv_header(nghttp3_conn *conn, int64_t stream_id, + int32_t token, nghttp3_rcbuf *name, + nghttp3_rcbuf *value, uint8_t flags, + void *user_data, void *stream_user_data) +{ + struct Curl_cfilter *cf = user_data; + nghttp3_vec h3name = nghttp3_rcbuf_get_buf(name); + nghttp3_vec h3val = nghttp3_rcbuf_get_buf(value); + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + CURLcode result = CURLE_OK; + (void)conn; + (void)stream_id; + (void)token; + (void)flags; + (void)cf; + + /* we might have cleaned up this transfer already */ + if(!stream) + return 0; + + if(token == NGHTTP3_QPACK_TOKEN__STATUS) { + char line[14]; /* status line is always 13 characters long */ + size_t ncopy; + + result = Curl_http_decode_status(&stream->status_code, + (const char *)h3val.base, h3val.len); + if(result) + return -1; + ncopy = msnprintf(line, sizeof(line), "HTTP/3 %03d \r\n", + stream->status_code); + CURL_TRC_CF(data, cf, "[%" PRId64 "] status: %s", stream_id, line); + result = write_resp_raw(cf, data, line, ncopy, FALSE); + if(result) { + return -1; + } + } + else { + /* store as an HTTP1-style header */ + CURL_TRC_CF(data, cf, "[%" PRId64 "] header: %.*s: %.*s", + stream_id, (int)h3name.len, h3name.base, + (int)h3val.len, h3val.base); + result = write_resp_raw(cf, data, h3name.base, h3name.len, FALSE); + if(result) { + return -1; + } + result = write_resp_raw(cf, data, ": ", 2, FALSE); + if(result) { + return -1; + } + result = write_resp_raw(cf, data, h3val.base, h3val.len, FALSE); + if(result) { + return -1; + } + result = write_resp_raw(cf, data, "\r\n", 2, FALSE); + if(result) { + return -1; + } + } + return 0; +} + +static int cb_h3_end_headers(nghttp3_conn *conn, int64_t stream_id, + int fin, void *user_data, void *stream_user_data) +{ + struct Curl_cfilter *cf = user_data; + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + CURLcode result = CURLE_OK; + (void)conn; + (void)stream_id; + (void)fin; + (void)cf; + + if(!stream) + return 0; + /* add a CRLF only if we've received some headers */ + result = write_resp_raw(cf, data, "\r\n", 2, FALSE); + if(result) { + return -1; + } + + CURL_TRC_CF(data, cf, "[%" PRId64 "] end_headers, status=%d", + stream_id, stream->status_code); + if(stream->status_code / 100 != 1) { + stream->resp_hds_complete = TRUE; + } + h3_drain_stream(cf, data); + return 0; +} + +static int cb_h3_stop_sending(nghttp3_conn *conn, int64_t stream_id, + uint64_t app_error_code, void *user_data, + void *stream_user_data) +{ + struct Curl_cfilter *cf = user_data; + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + (void)conn; + (void)app_error_code; + + if(!stream || !stream->s.ssl) + return 0; + + CURL_TRC_CF(data, cf, "[%" PRId64 "] stop_sending", stream_id); + cf_osslq_stream_close(&stream->s); + return 0; +} + +static int cb_h3_reset_stream(nghttp3_conn *conn, int64_t stream_id, + uint64_t app_error_code, void *user_data, + void *stream_user_data) { + struct Curl_cfilter *cf = user_data; + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + int rv; + (void)conn; + + if(stream && stream->s.ssl) { + SSL_STREAM_RESET_ARGS args = {0}; + args.quic_error_code = app_error_code; + rv = !SSL_stream_reset(stream->s.ssl, &args, sizeof(args)); + CURL_TRC_CF(data, cf, "[%" PRId64 "] reset -> %d", stream_id, rv); + if(!rv) { + return NGHTTP3_ERR_CALLBACK_FAILURE; + } + } + return 0; +} + +static nghttp3_ssize +cb_h3_read_req_body(nghttp3_conn *conn, int64_t stream_id, + nghttp3_vec *vec, size_t veccnt, + uint32_t *pflags, void *user_data, + void *stream_user_data) +{ + struct Curl_cfilter *cf = user_data; + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + ssize_t nwritten = 0; + size_t nvecs = 0; + (void)cf; + (void)conn; + (void)stream_id; + (void)user_data; + (void)veccnt; + + if(!stream) + return NGHTTP3_ERR_CALLBACK_FAILURE; + /* nghttp3 keeps references to the sendbuf data until it is ACKed + * by the server (see `cb_h3_acked_req_body()` for updates). + * `sendbuf_len_in_flight` is the amount of bytes in `sendbuf` + * that we have already passed to nghttp3, but which have not been + * ACKed yet. + * Any amount beyond `sendbuf_len_in_flight` we need still to pass + * to nghttp3. Do that now, if we can. */ + if(stream->sendbuf_len_in_flight < Curl_bufq_len(&stream->sendbuf)) { + nvecs = 0; + while(nvecs < veccnt && + Curl_bufq_peek_at(&stream->sendbuf, + stream->sendbuf_len_in_flight, + (const unsigned char **)&vec[nvecs].base, + &vec[nvecs].len)) { + stream->sendbuf_len_in_flight += vec[nvecs].len; + nwritten += vec[nvecs].len; + ++nvecs; + } + DEBUGASSERT(nvecs > 0); /* we SHOULD have been be able to peek */ + } + + if(nwritten > 0 && stream->upload_left != -1) + stream->upload_left -= nwritten; + + /* When we stopped sending and everything in `sendbuf` is "in flight", + * we are at the end of the request body. */ + if(stream->upload_left == 0) { + *pflags = NGHTTP3_DATA_FLAG_EOF; + stream->send_closed = TRUE; + } + else if(!nwritten) { + /* Not EOF, and nothing to give, we signal WOULDBLOCK. */ + CURL_TRC_CF(data, cf, "[%" PRId64 "] read req body -> AGAIN", + stream->s.id); + return NGHTTP3_ERR_WOULDBLOCK; + } + + CURL_TRC_CF(data, cf, "[%" PRId64 "] read req body -> " + "%d vecs%s with %zu (buffered=%zu, left=%" + CURL_FORMAT_CURL_OFF_T ")", + stream->s.id, (int)nvecs, + *pflags == NGHTTP3_DATA_FLAG_EOF?" EOF":"", + nwritten, Curl_bufq_len(&stream->sendbuf), + stream->upload_left); + return (nghttp3_ssize)nvecs; +} + +static int cb_h3_acked_stream_data(nghttp3_conn *conn, int64_t stream_id, + uint64_t datalen, void *user_data, + void *stream_user_data) +{ + struct Curl_cfilter *cf = user_data; + struct Curl_easy *data = stream_user_data; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + size_t skiplen; + + (void)cf; + if(!stream) + return 0; + /* The server acknowledged `datalen` of bytes from our request body. + * This is a delta. We have kept this data in `sendbuf` for + * re-transmissions and can free it now. */ + if(datalen >= (uint64_t)stream->sendbuf_len_in_flight) + skiplen = stream->sendbuf_len_in_flight; + else + skiplen = (size_t)datalen; + Curl_bufq_skip(&stream->sendbuf, skiplen); + stream->sendbuf_len_in_flight -= skiplen; + + /* Everything ACKed, we resume upload processing */ + if(!stream->sendbuf_len_in_flight) { + int rv = nghttp3_conn_resume_stream(conn, stream_id); + if(rv && rv != NGHTTP3_ERR_STREAM_NOT_FOUND) { + return NGHTTP3_ERR_CALLBACK_FAILURE; + } + } + return 0; +} + +static nghttp3_callbacks ngh3_callbacks = { + cb_h3_acked_stream_data, + cb_h3_stream_close, + cb_h3_recv_data, + cb_h3_deferred_consume, + NULL, /* begin_headers */ + cb_h3_recv_header, + cb_h3_end_headers, + NULL, /* begin_trailers */ + cb_h3_recv_header, + NULL, /* end_trailers */ + cb_h3_stop_sending, + NULL, /* end_stream */ + cb_h3_reset_stream, + NULL, /* shutdown */ + NULL /* recv_settings */ +}; + +static CURLcode cf_osslq_h3conn_init(struct cf_osslq_ctx *ctx, SSL *conn, + void *user_data) +{ + struct cf_osslq_h3conn *h3 = &ctx->h3; + CURLcode result; + int rc; + + nghttp3_settings_default(&h3->settings); + rc = nghttp3_conn_client_new(&h3->conn, + &ngh3_callbacks, + &h3->settings, + nghttp3_mem_default(), + user_data); + if(rc) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } + + result = cf_osslq_stream_open(&h3->s_ctrl, conn, + SSL_STREAM_FLAG_ADVANCE|SSL_STREAM_FLAG_UNI, + &ctx->stream_bufcp, NULL); + if(result) { + result = CURLE_QUIC_CONNECT_ERROR; + goto out; + } + result = cf_osslq_stream_open(&h3->s_qpack_enc, conn, + SSL_STREAM_FLAG_ADVANCE|SSL_STREAM_FLAG_UNI, + &ctx->stream_bufcp, NULL); + if(result) { + result = CURLE_QUIC_CONNECT_ERROR; + goto out; + } + result = cf_osslq_stream_open(&h3->s_qpack_dec, conn, + SSL_STREAM_FLAG_ADVANCE|SSL_STREAM_FLAG_UNI, + &ctx->stream_bufcp, NULL); + if(result) { + result = CURLE_QUIC_CONNECT_ERROR; + goto out; + } + + rc = nghttp3_conn_bind_control_stream(h3->conn, h3->s_ctrl.id); + if(rc) { + result = CURLE_QUIC_CONNECT_ERROR; + goto out; + } + rc = nghttp3_conn_bind_qpack_streams(h3->conn, h3->s_qpack_enc.id, + h3->s_qpack_dec.id); + if(rc) { + result = CURLE_QUIC_CONNECT_ERROR; + goto out; + } + + result = CURLE_OK; +out: + return result; +} + +static CURLcode cf_osslq_ctx_start(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result; + int rv; + const struct Curl_sockaddr_ex *peer_addr = NULL; + int peer_port; + BIO *bio = NULL; + BIO_ADDR *baddr = NULL; + + Curl_bufcp_init(&ctx->stream_bufcp, H3_STREAM_CHUNK_SIZE, + H3_STREAM_POOL_SPARES); + result = Curl_ssl_peer_init(&ctx->peer, cf); + if(result) + goto out; + +#define H3_ALPN "\x2h3" + result = Curl_vquic_tls_init(&ctx->tls, cf, data, &ctx->peer, + H3_ALPN, sizeof(H3_ALPN) - 1, + NULL, NULL); + if(result) + goto out; + + result = vquic_ctx_init(&ctx->q); + if(result) + goto out; + + result = CURLE_QUIC_CONNECT_ERROR; + Curl_cf_socket_peek(cf->next, data, &ctx->q.sockfd, + &peer_addr, NULL, &peer_port, NULL, NULL); + if(!peer_addr) + goto out; + + ctx->q.local_addrlen = sizeof(ctx->q.local_addr); + rv = getsockname(ctx->q.sockfd, (struct sockaddr *)&ctx->q.local_addr, + &ctx->q.local_addrlen); + if(rv == -1) + goto out; + + result = make_bio_addr(&baddr, peer_addr); + if(result) { + failf(data, "error creating BIO_ADDR from sockaddr"); + goto out; + } + + bio = BIO_new_dgram(ctx->q.sockfd, BIO_NOCLOSE); + if(!bio) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } + + if(!SSL_set1_initial_peer_addr(ctx->tls.ssl, baddr)) { + failf(data, "failed to set the initial peer address"); + result = CURLE_FAILED_INIT; + goto out; + } + if(!SSL_set_blocking_mode(ctx->tls.ssl, 0)) { + failf(data, "failed to turn off blocking mode"); + result = CURLE_FAILED_INIT; + goto out; + } + + SSL_set_bio(ctx->tls.ssl, bio, bio); + bio = NULL; + SSL_set_connect_state(ctx->tls.ssl); + SSL_set_incoming_stream_policy(ctx->tls.ssl, + SSL_INCOMING_STREAM_POLICY_ACCEPT, 0); + /* setup the H3 things on top of the QUIC connection */ + result = cf_osslq_h3conn_init(ctx, ctx->tls.ssl, cf); + +out: + if(bio) + BIO_free(bio); + if(baddr) + BIO_ADDR_free(baddr); + CURL_TRC_CF(data, cf, "QUIC tls init -> %d", result); + return result; +} + +struct h3_quic_recv_ctx { + struct Curl_cfilter *cf; + struct Curl_easy *data; + struct cf_osslq_stream *s; +}; + +static ssize_t h3_quic_recv(void *reader_ctx, + unsigned char *buf, size_t len, + CURLcode *err) +{ + struct h3_quic_recv_ctx *x = reader_ctx; + size_t nread; + int rv; + + *err = CURLE_OK; + rv = SSL_read_ex(x->s->ssl, buf, len, &nread); + if(rv <= 0) { + int detail = SSL_get_error(x->s->ssl, rv); + if(detail == SSL_ERROR_WANT_READ || detail == SSL_ERROR_WANT_WRITE) { + *err = CURLE_AGAIN; + return -1; + } + else if(detail == SSL_ERROR_ZERO_RETURN) { + CURL_TRC_CF(x->data, x->cf, "[%" PRId64 "] h3_quic_recv -> EOS", + x->s->id); + x->s->recvd_eos = TRUE; + return 0; + } + else if(SSL_get_stream_read_state(x->s->ssl) == + SSL_STREAM_STATE_RESET_REMOTE) { + uint64_t app_error_code = NGHTTP3_H3_NO_ERROR; + SSL_get_stream_read_error_code(x->s->ssl, &app_error_code); + CURL_TRC_CF(x->data, x->cf, "[%" PRId64 "] h3_quic_recv -> RESET, " + "rv=%d, app_err=%" PRIu64, + x->s->id, rv, app_error_code); + if(app_error_code != NGHTTP3_H3_NO_ERROR) { + x->s->reset = TRUE; + } + x->s->recvd_eos = TRUE; + return 0; + } + else { + *err = cf_osslq_ssl_err(x->cf, x->data, detail, CURLE_RECV_ERROR); + return -1; + } + } + else { + /* CURL_TRC_CF(x->data, x->cf, "[%" PRId64 "] h3_quic_recv -> %zu bytes", + x->s->id, nread); */ + } + return (ssize_t)nread; +} + +static CURLcode cf_osslq_stream_recv(struct cf_osslq_stream *s, + struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result = CURLE_OK; + ssize_t nread; + struct h3_quic_recv_ctx x; + int rv, eagain = FALSE; + size_t total_recv_len = 0; + + DEBUGASSERT(s); + if(s->closed) + return CURLE_OK; + + x.cf = cf; + x.data = data; + x.s = s; + while(s->ssl && !s->closed && !eagain && + (total_recv_len < H3_STREAM_CHUNK_SIZE)) { + if(Curl_bufq_is_empty(&s->recvbuf) && !s->recvd_eos) { + while(!eagain && !s->recvd_eos && !Curl_bufq_is_full(&s->recvbuf)) { + nread = Curl_bufq_sipn(&s->recvbuf, 0, h3_quic_recv, &x, &result); + if(nread < 0) { + if(result != CURLE_AGAIN) + goto out; + result = CURLE_OK; + eagain = TRUE; + } + } + } + + /* Forward what we have to nghttp3 */ + if(!Curl_bufq_is_empty(&s->recvbuf)) { + const unsigned char *buf; + size_t blen; + + while(Curl_bufq_peek(&s->recvbuf, &buf, &blen)) { + nread = nghttp3_conn_read_stream(ctx->h3.conn, s->id, + buf, blen, 0); + CURL_TRC_CF(data, cf, "[%" PRId64 "] forward %zu bytes " + "to nghttp3 -> %zd", s->id, blen, nread); + if(nread < 0) { + failf(data, "nghttp3_conn_read_stream(len=%zu) error: %s", + blen, nghttp3_strerror((int)nread)); + result = CURLE_RECV_ERROR; + goto out; + } + /* success, `nread` is the flow for QUIC to count as "consumed", + * not sure how that will work with OpenSSL. Anyways, without error, + * all data that we passed is not owned by nghttp3. */ + Curl_bufq_skip(&s->recvbuf, blen); + total_recv_len += blen; + } + } + + /* When we forwarded everything, handle RESET/EOS */ + if(Curl_bufq_is_empty(&s->recvbuf) && !s->closed) { + result = CURLE_OK; + if(s->reset) { + uint64_t app_error; + if(!SSL_get_stream_read_error_code(s->ssl, &app_error)) { + failf(data, "SSL_get_stream_read_error_code returned error"); + result = CURLE_RECV_ERROR; + goto out; + } + rv = nghttp3_conn_close_stream(ctx->h3.conn, s->id, app_error); + s->closed = TRUE; + if(rv < 0 && rv != NGHTTP3_ERR_STREAM_NOT_FOUND) { + failf(data, "nghttp3_conn_close_stream returned error: %s", + nghttp3_strerror(rv)); + result = CURLE_RECV_ERROR; + goto out; + } + } + else if(s->recvd_eos) { + rv = nghttp3_conn_close_stream(ctx->h3.conn, s->id, + NGHTTP3_H3_NO_ERROR); + s->closed = TRUE; + CURL_TRC_CF(data, cf, "[%" PRId64 "] close nghttp3 stream -> %d", + s->id, rv); + if(rv < 0 && rv != NGHTTP3_ERR_STREAM_NOT_FOUND) { + failf(data, "nghttp3_conn_close_stream returned error: %s", + nghttp3_strerror(rv)); + result = CURLE_RECV_ERROR; + goto out; + } + } + } + } +out: + if(result) + CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_osslq_stream_recv -> %d", + s->id, result); + return result; +} + +static CURLcode cf_progress_ingress(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result = CURLE_OK; + + if(!ctx->tls.ssl) + goto out; + + ERR_clear_error(); + + /* 1. Check for new incoming streams */ + while(1) { + SSL *snew = SSL_accept_stream(ctx->tls.ssl, SSL_ACCEPT_STREAM_NO_BLOCK); + if(!snew) + break; + + (void)cf_osslq_h3conn_add_stream(&ctx->h3, snew, cf, data); + } + + if(!SSL_handle_events(ctx->tls.ssl)) { + int detail = SSL_get_error(ctx->tls.ssl, 0); + result = cf_osslq_ssl_err(cf, data, detail, CURLE_RECV_ERROR); + } + + if(ctx->h3.conn) { + size_t i; + for(i = 0; i < ctx->h3.remote_ctrl_n; ++i) { + result = cf_osslq_stream_recv(&ctx->h3.remote_ctrl[i], cf, data); + if(result) + goto out; + } + } + + if(ctx->h3.conn) { + struct Curl_easy *sdata; + struct h3_stream_ctx *stream; + /* PULL all open streams */ + DEBUGASSERT(data->multi); + for(sdata = data->multi->easyp; sdata; sdata = sdata->next) { + if(sdata->conn == data->conn && CURL_WANT_RECV(sdata)) { + stream = H3_STREAM_CTX(sdata); + if(stream && !stream->closed && + !Curl_bufq_is_full(&stream->recvbuf)) { + result = cf_osslq_stream_recv(&stream->s, cf, sdata); + if(result) + goto out; + } + } + } + } + +out: + CURL_TRC_CF(data, cf, "progress_ingress -> %d", result); + return result; +} + +/* Iterate over all streams and check if blocked can be unblocked */ +static CURLcode cf_osslq_check_and_unblock(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct Curl_easy *sdata; + struct h3_stream_ctx *stream; + + if(ctx->h3.conn) { + for(sdata = data->multi->easyp; sdata; sdata = sdata->next) { + if(sdata->conn == data->conn) { + stream = H3_STREAM_CTX(sdata); + if(stream && stream->s.ssl && stream->s.send_blocked && + !SSL_want_write(stream->s.ssl)) { + nghttp3_conn_unblock_stream(ctx->h3.conn, stream->s.id); + stream->s.send_blocked = FALSE; + h3_drain_stream(cf, sdata); + CURL_TRC_CF(sdata, cf, "unblocked"); + } + } + } + } + return CURLE_OK; +} + +static CURLcode h3_send_streams(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result = CURLE_OK; + + if(!ctx->tls.ssl || !ctx->h3.conn) + goto out; + + for(;;) { + struct cf_osslq_stream *s = NULL; + nghttp3_vec vec[16]; + nghttp3_ssize n, i; + int64_t stream_id; + size_t written; + int eos, ok, rv; + size_t total_len, acked_len = 0; + bool blocked = FALSE; + + n = nghttp3_conn_writev_stream(ctx->h3.conn, &stream_id, &eos, + vec, ARRAYSIZE(vec)); + if(n < 0) { + failf(data, "nghttp3_conn_writev_stream returned error: %s", + nghttp3_strerror((int)n)); + result = CURLE_SEND_ERROR; + goto out; + } + if(stream_id < 0) { + result = CURLE_OK; + goto out; + } + + /* Get the stream for this data */ + s = cf_osslq_get_qstream(cf, data, stream_id); + if(!s) { + failf(data, "nghttp3_conn_writev_stream gave unknown stream %" PRId64, + stream_id); + result = CURLE_SEND_ERROR; + goto out; + } + /* Now write the data to the stream's SSL*, it may not all fit! */ + DEBUGASSERT(s->id == stream_id); + for(i = 0, total_len = 0; i < n; ++i) { + total_len += vec[i].len; + } + for(i = 0; (i < n) && !blocked; ++i) { + /* Without stream->s.ssl, we closed that already, so + * pretend the write did succeed. */ + written = vec[i].len; + ok = !s->ssl || SSL_write_ex(s->ssl, vec[i].base, vec[i].len, + &written); + if(ok) { + /* As OpenSSL buffers the data, we count this as acknowledged + * from nghttp3's point of view */ + CURL_TRC_CF(data, cf, "[%"PRId64"] send %zu bytes to QUIC ok", + s->id, vec[i].len); + acked_len += vec[i].len; + } + else { + int detail = SSL_get_error(s->ssl, 0); + switch(detail) { + case SSL_ERROR_WANT_WRITE: + case SSL_ERROR_WANT_READ: + /* QUIC blocked us from writing more */ + CURL_TRC_CF(data, cf, "[%"PRId64"] send %zu bytes to QUIC blocked", + s->id, vec[i].len); + written = 0; + nghttp3_conn_block_stream(ctx->h3.conn, s->id); + s->send_blocked = blocked = TRUE; + break; + default: + failf(data, "[%"PRId64"] send %zu bytes to QUIC, SSL error %d", + s->id, vec[i].len, detail); + result = cf_osslq_ssl_err(cf, data, detail, CURLE_SEND_ERROR); + goto out; + } + } + } + + if(acked_len > 0 || (eos && !s->send_blocked)) { + /* Since QUIC buffers the data written internally, we can tell + * nghttp3 that it can move forward on it */ + rv = nghttp3_conn_add_write_offset(ctx->h3.conn, s->id, acked_len); + if(rv && rv != NGHTTP3_ERR_STREAM_NOT_FOUND) { + failf(data, "nghttp3_conn_add_write_offset returned error: %s\n", + nghttp3_strerror(rv)); + result = CURLE_SEND_ERROR; + goto out; + } + rv = nghttp3_conn_add_ack_offset(ctx->h3.conn, s->id, acked_len); + if(rv && rv != NGHTTP3_ERR_STREAM_NOT_FOUND) { + failf(data, "nghttp3_conn_add_ack_offset returned error: %s\n", + nghttp3_strerror(rv)); + result = CURLE_SEND_ERROR; + goto out; + } + CURL_TRC_CF(data, cf, "[%" PRId64 "] forwarded %zu/%zu h3 bytes " + "to QUIC, eos=%d", s->id, acked_len, total_len, eos); + } + + if(eos && !s->send_blocked) { + /* wrote everything and H3 indicates end of stream */ + CURL_TRC_CF(data, cf, "[%" PRId64 "] closing QUIC stream", s->id); + SSL_stream_conclude(s->ssl, 0); + } + } + +out: + CURL_TRC_CF(data, cf, "h3_send_streams -> %d", result); + return result; +} + +static CURLcode cf_progress_egress(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result = CURLE_OK; + + if(!ctx->tls.ssl) + goto out; + + ERR_clear_error(); + result = h3_send_streams(cf, data); + if(result) + goto out; + + if(!SSL_handle_events(ctx->tls.ssl)) { + int detail = SSL_get_error(ctx->tls.ssl, 0); + result = cf_osslq_ssl_err(cf, data, detail, CURLE_SEND_ERROR); + } + + result = cf_osslq_check_and_unblock(cf, data); + +out: + CURL_TRC_CF(data, cf, "progress_egress -> %d", result); + return result; +} + +static CURLcode check_and_set_expiry(struct Curl_cfilter *cf, + struct Curl_easy *data) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result = CURLE_OK; + struct timeval tv; + timediff_t timeoutms; + int is_infinite = TRUE; + + if(ctx->tls.ssl && + SSL_get_event_timeout(ctx->tls.ssl, &tv, &is_infinite) && + !is_infinite) { + timeoutms = curlx_tvtoms(&tv); + /* QUIC want to be called again latest at the returned timeout */ + if(timeoutms <= 0) { + result = cf_progress_ingress(cf, data); + if(result) + goto out; + result = cf_progress_egress(cf, data); + if(result) + goto out; + if(SSL_get_event_timeout(ctx->tls.ssl, &tv, &is_infinite)) { + timeoutms = curlx_tvtoms(&tv); + } + } + if(!is_infinite) { + Curl_expire(data, timeoutms, EXPIRE_QUIC); + CURL_TRC_CF(data, cf, "QUIC expiry in %ldms", (long)timeoutms); + } + } +out: + return result; +} + +static CURLcode cf_osslq_connect(struct Curl_cfilter *cf, + struct Curl_easy *data, + bool blocking, bool *done) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result = CURLE_OK; + struct cf_call_data save; + struct curltime now; + int err; + + if(cf->connected) { + *done = TRUE; + return CURLE_OK; + } + + /* Connect the UDP filter first */ + if(!cf->next->connected) { + result = Curl_conn_cf_connect(cf->next, data, blocking, done); + if(result || !*done) + return result; + } + + *done = FALSE; + now = Curl_now(); + CF_DATA_SAVE(save, cf, data); + + if(ctx->reconnect_at.tv_sec && Curl_timediff(now, ctx->reconnect_at) < 0) { + /* Not time yet to attempt the next connect */ + CURL_TRC_CF(data, cf, "waiting for reconnect time"); + goto out; + } + + if(!ctx->tls.ssl) { + ctx->started_at = now; + result = cf_osslq_ctx_start(cf, data); + if(result) + goto out; + } + + if(!ctx->got_first_byte) { + int readable = SOCKET_READABLE(ctx->q.sockfd, 0); + if(readable > 0 && (readable & CURL_CSELECT_IN)) { + ctx->got_first_byte = TRUE; + ctx->first_byte_at = Curl_now(); + } + } + + ERR_clear_error(); + err = SSL_do_handshake(ctx->tls.ssl); + + if(err == 1) { + /* connected */ + ctx->handshake_at = now; + CURL_TRC_CF(data, cf, "handshake complete after %dms", + (int)Curl_timediff(now, ctx->started_at)); + result = cf_osslq_verify_peer(cf, data); + if(!result) { + CURL_TRC_CF(data, cf, "peer verified"); + cf->connected = TRUE; + cf->conn->alpn = CURL_HTTP_VERSION_3; + *done = TRUE; + connkeep(cf->conn, "HTTP/3 default"); + } + } + else { + int detail = SSL_get_error(ctx->tls.ssl, err); + switch(detail) { + case SSL_ERROR_WANT_READ: + CURL_TRC_CF(data, cf, "QUIC SSL_connect() -> WANT_RECV"); + result = Curl_vquic_tls_before_recv(&ctx->tls, cf, data); + goto out; + case SSL_ERROR_WANT_WRITE: + CURL_TRC_CF(data, cf, "QUIC SSL_connect() -> WANT_SEND"); + result = CURLE_OK; + goto out; +#ifdef SSL_ERROR_WANT_ASYNC + case SSL_ERROR_WANT_ASYNC: + CURL_TRC_CF(data, cf, "QUIC SSL_connect() -> WANT_ASYNC"); + result = CURLE_OK; + goto out; +#endif +#ifdef SSL_ERROR_WANT_RETRY_VERIFY + case SSL_ERROR_WANT_RETRY_VERIFY: + result = CURLE_OK; + goto out; +#endif + default: + result = cf_osslq_ssl_err(cf, data, detail, CURLE_COULDNT_CONNECT); + goto out; + } + } + +out: + if(result == CURLE_RECV_ERROR && ctx->tls.ssl && ctx->protocol_shutdown) { + /* When a QUIC server instance is shutting down, it may send us a + * CONNECTION_CLOSE right away. Our connection then enters the DRAINING + * state. The CONNECT may work in the near future again. Indicate + * that as a "weird" reply. */ + result = CURLE_WEIRD_SERVER_REPLY; + } + +#ifndef CURL_DISABLE_VERBOSE_STRINGS + if(result) { + const char *r_ip = NULL; + int r_port = 0; + + Curl_cf_socket_peek(cf->next, data, NULL, NULL, + &r_ip, &r_port, NULL, NULL); + infof(data, "QUIC connect to %s port %u failed: %s", + r_ip, r_port, curl_easy_strerror(result)); + } +#endif + if(!result) + result = check_and_set_expiry(cf, data); + if(result || *done) + CURL_TRC_CF(data, cf, "connect -> %d, done=%d", result, *done); + CF_DATA_RESTORE(cf, save); + return result; +} + +static ssize_t h3_stream_open(struct Curl_cfilter *cf, + struct Curl_easy *data, + const void *buf, size_t len, + CURLcode *err) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct h3_stream_ctx *stream = NULL; + struct dynhds h2_headers; + size_t nheader; + nghttp3_nv *nva = NULL; + int rc = 0; + unsigned int i; + ssize_t nwritten = -1; + nghttp3_data_reader reader; + nghttp3_data_reader *preader = NULL; + + Curl_dynhds_init(&h2_headers, 0, DYN_HTTP_REQUEST); + + *err = h3_data_setup(cf, data); + if(*err) + goto out; + stream = H3_STREAM_CTX(data); + DEBUGASSERT(stream); + if(!stream) { + *err = CURLE_FAILED_INIT; + goto out; + } + + nwritten = Curl_h1_req_parse_read(&stream->h1, buf, len, NULL, 0, err); + if(nwritten < 0) + goto out; + if(!stream->h1.done) { + /* need more data */ + goto out; + } + DEBUGASSERT(stream->h1.req); + + *err = Curl_http_req_to_h2(&h2_headers, stream->h1.req, data); + if(*err) { + nwritten = -1; + goto out; + } + /* no longer needed */ + Curl_h1_req_parse_free(&stream->h1); + + nheader = Curl_dynhds_count(&h2_headers); + nva = malloc(sizeof(nghttp3_nv) * nheader); + if(!nva) { + *err = CURLE_OUT_OF_MEMORY; + nwritten = -1; + goto out; + } + + for(i = 0; i < nheader; ++i) { + struct dynhds_entry *e = Curl_dynhds_getn(&h2_headers, i); + nva[i].name = (unsigned char *)e->name; + nva[i].namelen = e->namelen; + nva[i].value = (unsigned char *)e->value; + nva[i].valuelen = e->valuelen; + nva[i].flags = NGHTTP3_NV_FLAG_NONE; + } + + DEBUGASSERT(stream->s.id == -1); + *err = cf_osslq_stream_open(&stream->s, ctx->tls.ssl, 0, + &ctx->stream_bufcp, data); + if(*err) { + failf(data, "can't get bidi streams"); + *err = CURLE_SEND_ERROR; + goto out; + } + + switch(data->state.httpreq) { + case HTTPREQ_POST: + case HTTPREQ_POST_FORM: + case HTTPREQ_POST_MIME: + case HTTPREQ_PUT: + /* known request body size or -1 */ + if(data->state.infilesize != -1) + stream->upload_left = data->state.infilesize; + else + /* data sending without specifying the data amount up front */ + stream->upload_left = -1; /* unknown */ + break; + default: + /* there is not request body */ + stream->upload_left = 0; /* no request body */ + break; + } + + stream->send_closed = (stream->upload_left == 0); + if(!stream->send_closed) { + reader.read_data = cb_h3_read_req_body; + preader = &reader; + } + + rc = nghttp3_conn_submit_request(ctx->h3.conn, stream->s.id, + nva, nheader, preader, data); + if(rc) { + switch(rc) { + case NGHTTP3_ERR_CONN_CLOSING: + CURL_TRC_CF(data, cf, "h3sid[%"PRId64"] failed to send, " + "connection is closing", stream->s.id); + break; + default: + CURL_TRC_CF(data, cf, "h3sid[%"PRId64"] failed to send -> %d (%s)", + stream->s.id, rc, nghttp3_strerror(rc)); + break; + } + *err = CURLE_SEND_ERROR; + nwritten = -1; + goto out; + } + + if(Curl_trc_is_verbose(data)) { + infof(data, "[HTTP/3] [%" PRId64 "] OPENED stream for %s", + stream->s.id, data->state.url); + for(i = 0; i < nheader; ++i) { + infof(data, "[HTTP/3] [%" PRId64 "] [%.*s: %.*s]", stream->s.id, + (int)nva[i].namelen, nva[i].name, + (int)nva[i].valuelen, nva[i].value); + } + } + +out: + free(nva); + Curl_dynhds_free(&h2_headers); + return nwritten; +} + +static ssize_t cf_osslq_send(struct Curl_cfilter *cf, struct Curl_easy *data, + const void *buf, size_t len, CURLcode *err) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + struct cf_call_data save; + ssize_t nwritten; + CURLcode result; + + CF_DATA_SAVE(save, cf, data); + DEBUGASSERT(cf->connected); + DEBUGASSERT(ctx->tls.ssl); + DEBUGASSERT(ctx->h3.conn); + *err = CURLE_OK; + + result = cf_progress_ingress(cf, data); + if(result) { + *err = result; + nwritten = -1; + goto out; + } + + result = cf_progress_egress(cf, data); + if(result) { + *err = result; + nwritten = -1; + goto out; + } + + if(!stream || stream->s.id < 0) { + nwritten = h3_stream_open(cf, data, buf, len, err); + if(nwritten < 0) { + CURL_TRC_CF(data, cf, "failed to open stream -> %d", *err); + goto out; + } + stream = H3_STREAM_CTX(data); + } + else if(stream->upload_blocked_len) { + /* the data in `buf` has already been submitted or added to the + * buffers, but have been EAGAINed on the last invocation. */ + DEBUGASSERT(len >= stream->upload_blocked_len); + if(len < stream->upload_blocked_len) { + /* Did we get called again with a smaller `len`? This should not + * happen. We are not prepared to handle that. */ + failf(data, "HTTP/3 send again with decreased length"); + *err = CURLE_HTTP3; + nwritten = -1; + goto out; + } + nwritten = (ssize_t)stream->upload_blocked_len; + stream->upload_blocked_len = 0; + } + else if(stream->closed) { + if(stream->resp_hds_complete) { + /* Server decided to close the stream after having sent us a final + * response. This is valid if it is not interested in the request + * body. This happens on 30x or 40x responses. + * We silently discard the data sent, since this is not a transport + * error situation. */ + CURL_TRC_CF(data, cf, "[%" PRId64 "] discarding data" + "on closed stream with response", stream->s.id); + *err = CURLE_OK; + nwritten = (ssize_t)len; + goto out; + } + CURL_TRC_CF(data, cf, "[%" PRId64 "] send_body(len=%zu) " + "-> stream closed", stream->s.id, len); + *err = CURLE_HTTP3; + nwritten = -1; + goto out; + } + else { + nwritten = Curl_bufq_write(&stream->sendbuf, buf, len, err); + CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_send, add to " + "sendbuf(len=%zu) -> %zd, %d", + stream->s.id, len, nwritten, *err); + if(nwritten < 0) { + goto out; + } + + (void)nghttp3_conn_resume_stream(ctx->h3.conn, stream->s.id); + } + + result = cf_progress_egress(cf, data); + if(result) { + *err = result; + nwritten = -1; + } + + if(stream && nwritten > 0 && stream->sendbuf_len_in_flight) { + /* We have unacknowledged DATA and cannot report success to our + * caller. Instead we EAGAIN and remember how much we have already + * "written" into our various internal connection buffers. */ + stream->upload_blocked_len = nwritten; + CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_send(len=%zu), " + "%zu bytes in flight -> EGAIN", stream->s.id, len, + stream->sendbuf_len_in_flight); + *err = CURLE_AGAIN; + nwritten = -1; + } + +out: + result = check_and_set_expiry(cf, data); + CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_send(len=%zu) -> %zd, %d", + stream? stream->s.id : -1, len, nwritten, *err); + CF_DATA_RESTORE(cf, save); + return nwritten; +} + +static ssize_t recv_closed_stream(struct Curl_cfilter *cf, + struct Curl_easy *data, + struct h3_stream_ctx *stream, + CURLcode *err) +{ + ssize_t nread = -1; + + (void)cf; + if(stream->reset) { + failf(data, + "HTTP/3 stream %" PRId64 " reset by server", stream->s.id); + *err = stream->resp_hds_complete? CURLE_PARTIAL_FILE : CURLE_HTTP3; + goto out; + } + else if(!stream->resp_hds_complete) { + failf(data, + "HTTP/3 stream %" PRId64 " was closed cleanly, but before getting" + " all response header fields, treated as error", + stream->s.id); + *err = CURLE_HTTP3; + goto out; + } + *err = CURLE_OK; + nread = 0; + +out: + return nread; +} + +static ssize_t cf_osslq_recv(struct Curl_cfilter *cf, struct Curl_easy *data, + char *buf, size_t len, CURLcode *err) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + ssize_t nread = -1; + struct cf_call_data save; + CURLcode result; + + (void)ctx; + CF_DATA_SAVE(save, cf, data); + DEBUGASSERT(cf->connected); + DEBUGASSERT(ctx); + DEBUGASSERT(ctx->tls.ssl); + DEBUGASSERT(ctx->h3.conn); + *err = CURLE_OK; + + if(!stream) { + *err = CURLE_RECV_ERROR; + goto out; + } + + if(!Curl_bufq_is_empty(&stream->recvbuf)) { + nread = Curl_bufq_read(&stream->recvbuf, + (unsigned char *)buf, len, err); + if(nread < 0) { + CURL_TRC_CF(data, cf, "[%" PRId64 "] read recvbuf(len=%zu) " + "-> %zd, %d", stream->s.id, len, nread, *err); + goto out; + } + } + + result = cf_progress_ingress(cf, data); + if(result) { + *err = result; + nread = -1; + goto out; + } + + /* recvbuf had nothing before, maybe after progressing ingress? */ + if(nread < 0 && !Curl_bufq_is_empty(&stream->recvbuf)) { + nread = Curl_bufq_read(&stream->recvbuf, + (unsigned char *)buf, len, err); + if(nread < 0) { + CURL_TRC_CF(data, cf, "[%" PRId64 "] read recvbuf(len=%zu) " + "-> %zd, %d", stream->s.id, len, nread, *err); + goto out; + } + } + + if(nread > 0) { + h3_drain_stream(cf, data); + } + else { + if(stream->closed) { + nread = recv_closed_stream(cf, data, stream, err); + goto out; + } + *err = CURLE_AGAIN; + nread = -1; + } + +out: + if(cf_progress_egress(cf, data)) { + *err = CURLE_SEND_ERROR; + nread = -1; + } + else { + CURLcode result2 = check_and_set_expiry(cf, data); + if(result2) { + *err = result2; + nread = -1; + } + } + CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_recv(len=%zu) -> %zd, %d", + stream? stream->s.id : -1, len, nread, *err); + CF_DATA_RESTORE(cf, save); + return nread; +} + +/* + * Called from transfer.c:data_pending to know if we should keep looping + * to receive more data from the connection. + */ +static bool cf_osslq_data_pending(struct Curl_cfilter *cf, + const struct Curl_easy *data) +{ + const struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + (void)cf; + return stream && !Curl_bufq_is_empty(&stream->recvbuf); +} + +static CURLcode cf_osslq_data_event(struct Curl_cfilter *cf, + struct Curl_easy *data, + int event, int arg1, void *arg2) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + CURLcode result = CURLE_OK; + struct cf_call_data save; + + CF_DATA_SAVE(save, cf, data); + (void)arg1; + (void)arg2; + switch(event) { + case CF_CTRL_DATA_SETUP: + break; + case CF_CTRL_DATA_PAUSE: + result = h3_data_pause(cf, data, (arg1 != 0)); + break; + case CF_CTRL_DATA_DETACH: + h3_data_done(cf, data); + break; + case CF_CTRL_DATA_DONE: + h3_data_done(cf, data); + break; + case CF_CTRL_DATA_DONE_SEND: { + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + if(stream && !stream->send_closed) { + stream->send_closed = TRUE; + stream->upload_left = Curl_bufq_len(&stream->sendbuf); + (void)nghttp3_conn_resume_stream(ctx->h3.conn, stream->s.id); + } + break; + } + case CF_CTRL_DATA_IDLE: { + struct h3_stream_ctx *stream = H3_STREAM_CTX(data); + CURL_TRC_CF(data, cf, "data idle"); + if(stream && !stream->closed) { + result = check_and_set_expiry(cf, data); + } + break; + } + default: + break; + } + CF_DATA_RESTORE(cf, save); + return result; +} + +static bool cf_osslq_conn_is_alive(struct Curl_cfilter *cf, + struct Curl_easy *data, + bool *input_pending) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + bool alive = FALSE; + struct cf_call_data save; + + CF_DATA_SAVE(save, cf, data); + *input_pending = FALSE; + if(!ctx->tls.ssl) + goto out; + + /* TODO: how to check negotiated connection idle time? */ + + if(!cf->next || !cf->next->cft->is_alive(cf->next, data, input_pending)) + goto out; + + alive = TRUE; + if(*input_pending) { + CURLcode result; + /* This happens before we've sent off a request and the connection is + not in use by any other transfer, there shouldn't be any data here, + only "protocol frames" */ + *input_pending = FALSE; + result = cf_progress_ingress(cf, data); + CURL_TRC_CF(data, cf, "is_alive, progress ingress -> %d", result); + alive = result? FALSE : TRUE; + } + +out: + CF_DATA_RESTORE(cf, save); + return alive; +} + +static void cf_osslq_adjust_pollset(struct Curl_cfilter *cf, + struct Curl_easy *data, + struct easy_pollset *ps) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + + if(!ctx->tls.ssl) { + /* NOP */ + } + else if(!cf->connected) { + /* during handshake, transfer has not started yet. we always + * add our socket for polling if SSL wants to send/recv */ + Curl_pollset_set(data, ps, ctx->q.sockfd, + SSL_net_read_desired(ctx->tls.ssl), + SSL_net_write_desired(ctx->tls.ssl)); + } + else { + /* once connected, we only modify the socket if it is present. + * this avoids adding it for paused transfers. */ + bool want_recv, want_send; + Curl_pollset_check(data, ps, ctx->q.sockfd, &want_recv, &want_send); + if(want_recv || want_send) { + Curl_pollset_set(data, ps, ctx->q.sockfd, + SSL_net_read_desired(ctx->tls.ssl), + SSL_net_write_desired(ctx->tls.ssl)); + } + } +} + +static CURLcode cf_osslq_query(struct Curl_cfilter *cf, + struct Curl_easy *data, + int query, int *pres1, void *pres2) +{ + struct cf_osslq_ctx *ctx = cf->ctx; + struct cf_call_data save; + + switch(query) { + case CF_QUERY_MAX_CONCURRENT: { + /* TODO: how to get this? */ + CF_DATA_SAVE(save, cf, data); + *pres1 = 100; + CURL_TRC_CF(data, cf, "query max_conncurrent -> %d", *pres1); + CF_DATA_RESTORE(cf, save); + return CURLE_OK; + } + case CF_QUERY_CONNECT_REPLY_MS: + if(ctx->got_first_byte) { + timediff_t ms = Curl_timediff(ctx->first_byte_at, ctx->started_at); + *pres1 = (ms < INT_MAX)? (int)ms : INT_MAX; + } + else + *pres1 = -1; + return CURLE_OK; + case CF_QUERY_TIMER_CONNECT: { + struct curltime *when = pres2; + if(ctx->got_first_byte) + *when = ctx->first_byte_at; + return CURLE_OK; + } + case CF_QUERY_TIMER_APPCONNECT: { + struct curltime *when = pres2; + if(cf->connected) + *when = ctx->handshake_at; + return CURLE_OK; + } + default: + break; + } + return cf->next? + cf->next->cft->query(cf->next, data, query, pres1, pres2) : + CURLE_UNKNOWN_OPTION; +} + +struct Curl_cftype Curl_cft_http3 = { + "HTTP/3", + CF_TYPE_IP_CONNECT | CF_TYPE_SSL | CF_TYPE_MULTIPLEX, + 0, + cf_osslq_destroy, + cf_osslq_connect, + cf_osslq_close, + Curl_cf_def_get_host, + cf_osslq_adjust_pollset, + cf_osslq_data_pending, + cf_osslq_send, + cf_osslq_recv, + cf_osslq_data_event, + cf_osslq_conn_is_alive, + Curl_cf_def_conn_keep_alive, + cf_osslq_query, +}; + +CURLcode Curl_cf_osslq_create(struct Curl_cfilter **pcf, + struct Curl_easy *data, + struct connectdata *conn, + const struct Curl_addrinfo *ai) +{ + struct cf_osslq_ctx *ctx = NULL; + struct Curl_cfilter *cf = NULL, *udp_cf = NULL; + CURLcode result; + + (void)data; + ctx = calloc(1, sizeof(*ctx)); + if(!ctx) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } + cf_osslq_ctx_clear(ctx); + + result = Curl_cf_create(&cf, &Curl_cft_http3, ctx); + if(result) + goto out; + + result = Curl_cf_udp_create(&udp_cf, data, conn, ai, TRNSPRT_QUIC); + if(result) + goto out; + + cf->conn = conn; + udp_cf->conn = cf->conn; + udp_cf->sockindex = cf->sockindex; + cf->next = udp_cf; + +out: + *pcf = (!result)? cf : NULL; + if(result) { + if(udp_cf) + Curl_conn_cf_discard_sub(cf, udp_cf, data, TRUE); + Curl_safefree(cf); + Curl_safefree(ctx); + } + return result; +} + +bool Curl_conn_is_osslq(const struct Curl_easy *data, + const struct connectdata *conn, + int sockindex) +{ + struct Curl_cfilter *cf = conn? conn->cfilter[sockindex] : NULL; + + (void)data; + for(; cf; cf = cf->next) { + if(cf->cft == &Curl_cft_http3) + return TRUE; + if(cf->cft->flags & CF_TYPE_IP_CONNECT) + return FALSE; + } + return FALSE; +} + +/* + * Store ngtcp2 version info in this buffer. + */ +void Curl_osslq_ver(char *p, size_t len) +{ + const nghttp3_info *ht3 = nghttp3_version(0); + char tmp[128]; + Curl_ssl_version(tmp, sizeof(tmp)-1); + (void)msnprintf(p, len, "%s nghttp3/%s", tmp, ht3->version_str); +} + +#endif /* USE_OPENSSL_QUIC && USE_NGHTTP3 */ diff --git a/lib/vquic/curl_osslq.h b/lib/vquic/curl_osslq.h new file mode 100644 index 00000000000..0e12d7023e0 --- /dev/null +++ b/lib/vquic/curl_osslq.h @@ -0,0 +1,51 @@ +#ifndef HEADER_CURL_VQUIC_CURL_OSSLQ_H +#define HEADER_CURL_VQUIC_CURL_OSSLQ_H +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +#include "curl_setup.h" + +#if defined(USE_OPENSSL_QUIC) && defined(USE_NGHTTP3) + +#ifdef HAVE_NETINET_UDP_H +#include +#endif + +struct Curl_cfilter; + +#include "urldata.h" + +void Curl_osslq_ver(char *p, size_t len); + +CURLcode Curl_cf_osslq_create(struct Curl_cfilter **pcf, + struct Curl_easy *data, + struct connectdata *conn, + const struct Curl_addrinfo *ai); + +bool Curl_conn_is_osslq(const struct Curl_easy *data, + const struct connectdata *conn, + int sockindex); +#endif + +#endif /* HEADER_CURL_VQUIC_CURL_OSSLQ_H */ diff --git a/lib/vquic/vquic-tls.c b/lib/vquic/vquic-tls.c index e9f16773b97..cc7794e405a 100644 --- a/lib/vquic/vquic-tls.c +++ b/lib/vquic/vquic-tls.c @@ -97,7 +97,11 @@ static CURLcode curl_ossl_init_ctx(struct quic_tls_ctx *ctx, CURLcode result = CURLE_FAILED_INIT; DEBUGASSERT(!ctx->ssl_ctx); +#ifdef USE_OPENSSL_QUIC + ctx->ssl_ctx = SSL_CTX_new(OSSL_QUIC_client_method()); +#else ctx->ssl_ctx = SSL_CTX_new(TLS_method()); +#endif if(!ctx->ssl_ctx) { result = CURLE_OUT_OF_MEMORY; goto out; @@ -216,7 +220,9 @@ static CURLcode curl_ossl_init_ssl(struct quic_tls_ctx *ctx, SSL_set_app_data(ctx->ssl, user_data); SSL_set_connect_state(ctx->ssl); +#ifndef USE_OPENSSL_QUIC SSL_set_quic_use_legacy_codepoint(ctx->ssl, 0); +#endif if(alpn) SSL_set_alpn_protos(ctx->ssl, (const uint8_t *)alpn, (int)alpn_len); diff --git a/lib/vquic/vquic.c b/lib/vquic/vquic.c index 7da4641468b..612d25bb0af 100644 --- a/lib/vquic/vquic.c +++ b/lib/vquic/vquic.c @@ -46,6 +46,7 @@ #include "curl_trc.h" #include "curl_msh3.h" #include "curl_ngtcp2.h" +#include "curl_osslq.h" #include "curl_quiche.h" #include "rand.h" #include "vquic.h" @@ -74,6 +75,8 @@ void Curl_quic_ver(char *p, size_t len) { #if defined(USE_NGTCP2) && defined(USE_NGHTTP3) Curl_ngtcp2_ver(p, len); +#elif defined(USE_OPENSSL_QUIC) && defined(USE_NGHTTP3) + Curl_osslq_ver(p, len); #elif defined(USE_QUICHE) Curl_quiche_ver(p, len); #elif defined(USE_MSH3) @@ -608,6 +611,8 @@ CURLcode Curl_cf_quic_create(struct Curl_cfilter **pcf, DEBUGASSERT(transport == TRNSPRT_QUIC); #if defined(USE_NGTCP2) && defined(USE_NGHTTP3) return Curl_cf_ngtcp2_create(pcf, data, conn, ai); +#elif defined(USE_OPENSSL_QUIC) && defined(USE_NGHTTP3) + return Curl_cf_osslq_create(pcf, data, conn, ai); #elif defined(USE_QUICHE) return Curl_cf_quiche_create(pcf, data, conn, ai); #elif defined(USE_MSH3) @@ -627,6 +632,8 @@ bool Curl_conn_is_http3(const struct Curl_easy *data, { #if defined(USE_NGTCP2) && defined(USE_NGHTTP3) return Curl_conn_is_ngtcp2(data, conn, sockindex); +#elif defined(USE_OPENSSL_QUIC) && defined(USE_NGHTTP3) + return Curl_conn_is_osslq(data, conn, sockindex); #elif defined(USE_QUICHE) return Curl_conn_is_quiche(data, conn, sockindex); #elif defined(USE_MSH3) diff --git a/m4/curl-openssl.m4 b/m4/curl-openssl.m4 index 3f3b3c238e5..c329b760faf 100644 --- a/m4/curl-openssl.m4 +++ b/m4/curl-openssl.m4 @@ -422,4 +422,23 @@ AS_HELP_STRING([--disable-openssl-auto-load-config],[Disable automatic loading o ]) fi +dnl --- +dnl We may use OpenSSL QUIC. +dnl --- +if test "$OPENSSL_ENABLED" = "1"; then + AC_MSG_CHECKING([for QUIC support in OpenSSL]) + AC_LINK_IFELSE([ + AC_LANG_PROGRAM([[ +#include + ]],[[ + OSSL_QUIC_client_method(); + ]]) + ],[ + AC_MSG_RESULT([yes]) + AC_DEFINE(HAVE_OPENSSL_QUIC, 1, [if you have the functions OSSL_QUIC_client_method]) + AC_SUBST(HAVE_OPENSSL_QUIC, [1]) + ],[ + AC_MSG_RESULT([no]) + ]) +fi ]) diff --git a/tests/http/scorecard.py b/tests/http/scorecard.py index ae466129c0a..1b539ffdc42 100644 --- a/tests/http/scorecard.py +++ b/tests/http/scorecard.py @@ -332,7 +332,7 @@ def score_proto(self, proto: str, p['name'] = 'h3' if not self.env.have_h3_curl(): raise ScoreCardException('curl does not support HTTP/3') - for lib in ['ngtcp2', 'quiche', 'msh3']: + for lib in ['ngtcp2', 'quiche', 'msh3', 'nghttp3']: if self.env.curl_uses_lib(lib): p['implementation'] = lib break diff --git a/tests/http/test_08_caddy.py b/tests/http/test_08_caddy.py index c95d8457a8e..c35bd27b76a 100644 --- a/tests/http/test_08_caddy.py +++ b/tests/http/test_08_caddy.py @@ -163,3 +163,20 @@ def test_08_05_download_1mb_parallel(self, env: Env, caddy: Caddy, assert r.total_connects > 1, r.dump_logs() else: assert r.total_connects == 1, r.dump_logs() + + # upload data parallel, check that they were echoed + @pytest.mark.skipif(condition=Env().ci_run, reason="not suitable for CI runs") + @pytest.mark.parametrize("proto", ['h2', 'h3']) + def test_08_06_upload_parallel(self, env: Env, caddy, repeat, proto): + if proto == 'h3' and not env.have_h3(): + pytest.skip("h3 not supported") + if proto == 'h3' and env.curl_uses_lib('msh3'): + pytest.skip("msh3 stalls here") + # limit since we use a separate connection in h1 + count = 20 + data = '0123456789' + curl = CurlClient(env=env) + url = f'https://{env.domain1}:{caddy.port}/data10.data?[0-{count-1}]' + r = curl.http_upload(urls=[url], data=data, alpn_proto=proto, + extra_args=['--parallel']) + r.check_stats(count=count, http_status=200, exitcode=0) diff --git a/tests/http/test_14_auth.py b/tests/http/test_14_auth.py index 0cc0f925f24..6d3db593129 100644 --- a/tests/http/test_14_auth.py +++ b/tests/http/test_14_auth.py @@ -133,5 +133,7 @@ def test_14_06_basic_very_large_pw(self, env: Env, httpd, nghttpx, repeat, proto r = curl.http_upload(urls=[url], data=f'@{fdata}', alpn_proto=proto, extra_args=[ '--basic', '--user', f'test:{password}' ]) - # request was never sent - r.check_response(exitcode=55, http_status=0) + # Depending on protocl, we might have an error sending or + # the server might shutdown the connection and we see the error + # on receiving + assert r.exit_code in [55, 56], f'{self.dump_logs()}' diff --git a/tests/http/testenv/nghttpx.py b/tests/http/testenv/nghttpx.py index 4be060b567a..9544ce05d9b 100644 --- a/tests/http/testenv/nghttpx.py +++ b/tests/http/testenv/nghttpx.py @@ -129,7 +129,9 @@ def wait_dead(self, timeout: timedelta): try_until = datetime.now() + timeout while datetime.now() < try_until: check_url = f'https://{self.env.domain1}:{self._port}/' - r = curl.http_get(url=check_url, extra_args=['--http3-only']) + r = curl.http_get(url=check_url, extra_args=[ + '--http3-only', '--connect-timeout', '1' + ]) if r.exit_code != 0: return True log.debug(f'waiting for nghttpx to stop responding: {r}') @@ -143,7 +145,8 @@ def wait_live(self, timeout: timedelta): while datetime.now() < try_until: check_url = f'https://{self.env.domain1}:{self._port}/' r = curl.http_get(url=check_url, extra_args=[ - '--http3-only', '--trace', 'curl.trace', '--trace-time' + '--http3-only', '--trace', 'curl.trace', '--trace-time', + '--connect-timeout', '1' ]) if r.exit_code == 0: return True @@ -193,6 +196,7 @@ def start(self, wait_live=True): f'--frontend-http3-max-window-size=10M', f'--frontend-http3-connection-window-size=10M', f'--frontend-http3-max-connection-window-size=100M', + # f'--frontend-quic-debug-log', ] ngerr = open(self._stderr, 'a') self._process = subprocess.Popen(args=args, stderr=ngerr) From cdd905a9854305657ebbe645095e1189dcda28c7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 22 Jan 2024 16:22:19 +0100 Subject: [PATCH 196/509] transfer: make the select_bits_paused condition check both directions If there is activity in a direction that is not paused, return false. Reported-by: Sergey Bronnikov Bug: https://curl.se/mail/lib-2024-01/0049.html Closes #12740 --- lib/transfer.c | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/lib/transfer.c b/lib/transfer.c index 1d066fbf889..3ae4b61c0ee 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -850,10 +850,15 @@ static int select_bits_paused(struct Curl_easy *data, int select_bits) * of our state machine are handling PAUSED transfers correctly. So, we * do not want to go there. * NOTE: we are only interested in PAUSE, not HOLD. */ - return (((select_bits & CURL_CSELECT_IN) && - (data->req.keepon & KEEP_RECV_PAUSE)) || - ((select_bits & CURL_CSELECT_OUT) && - (data->req.keepon & KEEP_SEND_PAUSE))); + + /* if there is data in a direction not paused, return false */ + if(((select_bits & CURL_CSELECT_IN) && + !(data->req.keepon & KEEP_RECV_PAUSE)) || + ((select_bits & CURL_CSELECT_OUT) && + !(data->req.keepon & KEEP_SEND_PAUSE))) + return FALSE; + + return (data->req.keepon & (KEEP_RECV_PAUSE|KEEP_SEND_PAUSE)); } /* From 02f91d5b6408b7972fdadb938fe9a95907a00a1b Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 22 Jan 2024 11:21:10 +0000 Subject: [PATCH 197/509] libssh2: use `libssh2_session_callback_set2()` with v1.11.1 To avoid a local hack to pass function pointers and to avoid deprecation warnings when building with libssh2 v1.11.1 or newer: ``` lib/vssh/libssh2.c:3324:5: warning: 'libssh2_session_callback_set' is deprecated: since libssh2 1.11.1. Use libssh2_session_callback_set2() [-Wdeprecated-declarations] lib/vssh/libssh2.c:3326:5: warning: 'libssh2_session_callback_set' is deprecated: since libssh2 1.11.1. Use libssh2_session_callback_set2() [-Wdeprecated-declarations] ``` Ref: https://github.com/curl/curl-for-win/actions/runs/7609484879/job/20720821100#step:3:4982 Ref: https://github.com/libssh2/libssh2/pull/1285 Ref: https://github.com/libssh2/libssh2/commit/c0f69548be902147ce014ffa40b8db3cf1d4b0b4 Reviewed-by: Daniel Stenberg Closes #12754 --- lib/vssh/libssh2.c | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index fa24ac38c4d..b2bedd8846b 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -3289,6 +3289,27 @@ static CURLcode ssh_connect(struct Curl_easy *data, bool *done) #ifndef CURL_DISABLE_PROXY if(conn->http_proxy.proxytype == CURLPROXY_HTTPS) { + /* + Setup libssh2 callbacks to make it read/write TLS from the socket. + + ssize_t + recvcb(libssh2_socket_t sock, void *buffer, size_t length, + int flags, void **abstract); + + ssize_t + sendcb(libssh2_socket_t sock, const void *buffer, size_t length, + int flags, void **abstract); + + */ +#if LIBSSH2_VERSION_NUM >= 0x010b01 + infof(data, "Uses HTTPS proxy"); + libssh2_session_callback_set2(sshc->ssh_session, + LIBSSH2_CALLBACK_RECV, + (libssh2_cb_generic *)ssh_tls_recv); + libssh2_session_callback_set2(sshc->ssh_session, + LIBSSH2_CALLBACK_SEND, + (libssh2_cb_generic *)ssh_tls_send); +#else /* * This crazy union dance is here to avoid assigning a void pointer a * function pointer as it is invalid C. The problem is of course that @@ -3309,22 +3330,11 @@ static CURLcode ssh_connect(struct Curl_easy *data, bool *done) sshsend.sendptr = ssh_tls_send; infof(data, "Uses HTTPS proxy"); - /* - Setup libssh2 callbacks to make it read/write TLS from the socket. - - ssize_t - recvcb(libssh2_socket_t sock, void *buffer, size_t length, - int flags, void **abstract); - - ssize_t - sendcb(libssh2_socket_t sock, const void *buffer, size_t length, - int flags, void **abstract); - - */ libssh2_session_callback_set(sshc->ssh_session, LIBSSH2_CALLBACK_RECV, sshrecv.recvp); libssh2_session_callback_set(sshc->ssh_session, LIBSSH2_CALLBACK_SEND, sshsend.sendp); +#endif /* Store the underlying TLS recv/send function pointers to be used when reading from the proxy */ From eefcc1bda4bccd800f5a56a0fe17a2f44a96e88b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 17 Jan 2024 11:32:44 +0100 Subject: [PATCH 198/509] docs: introduce "curldown" for libcurl man page format curldown is this new file format for libcurl man pages. It is markdown inspired with differences: - Each file has a set of leading headers with meta-data - Supports a small subset of markdown - Uses .md file extensions for editors/IDE/GitHub to treat them nicely - Generates man pages very similar to the previous ones - Generates man pages that still convert nicely to HTML on the website - Detects and highlights mentions of curl symbols automatically (when their man page section is specified) tools: - cd2nroff: converts from curldown to nroff man page - nroff2cd: convert an (old) nroff man page to curldown - cdall: convert many nroff pages to curldown versions - cd2cd: verifies and updates a curldown to latest curldown This setup generates .3 versions of all the curldown versions at build time. CI: Since the documentation is now technically markdown in the eyes of many things, the CI runs many more tests and checks on this documentation, including proselint, link checkers and tests that make sure we capitalize the first letter after a period... Closes #12730 --- .github/scripts/cleanspell.pl | 1 + .github/scripts/spellcheck.words | 13 +- .github/scripts/verify-examples.pl | 10 +- .github/workflows/man-examples.yml | 3 + .github/workflows/proselint.yml | 3 +- Makefile.am | 6 - appveyor.yml | 16 +- docs/.gitignore | 6 +- docs/CONTRIBUTE.md | 2 +- docs/CURLDOWN.md | 125 ++ docs/GOVERNANCE.md | 2 +- docs/HISTORY.md | 2 +- docs/Makefile.am | 44 +- docs/SSLCERTS.md | 8 +- docs/{curl-config.1 => curl-config.md} | 139 +- docs/libcurl/.gitignore | 8 - docs/libcurl/Makefile.am | 54 +- docs/libcurl/curl_easy_cleanup.3 | 82 - docs/libcurl/curl_easy_cleanup.md | 76 + docs/libcurl/curl_easy_duphandle.3 | 78 - docs/libcurl/curl_easy_duphandle.md | 72 + docs/libcurl/curl_easy_escape.3 | 79 - docs/libcurl/curl_easy_escape.md | 75 + docs/libcurl/curl_easy_getinfo.3 | 336 ---- docs/libcurl/curl_easy_getinfo.md | 483 ++++++ ...curl_easy_header.3 => curl_easy_header.md} | 156 +- docs/libcurl/curl_easy_init.3 | 82 - docs/libcurl/curl_easy_init.md | 73 + docs/libcurl/curl_easy_nextheader.3 | 106 -- docs/libcurl/curl_easy_nextheader.md | 100 ++ docs/libcurl/curl_easy_option_by_id.3 | 59 - docs/libcurl/curl_easy_option_by_id.md | 54 + docs/libcurl/curl_easy_option_by_name.3 | 58 - docs/libcurl/curl_easy_option_by_name.md | 53 + docs/libcurl/curl_easy_option_next.3 | 92 -- docs/libcurl/curl_easy_option_next.md | 89 ++ .../{curl_easy_pause.3 => curl_easy_pause.md} | 119 +- docs/libcurl/curl_easy_perform.3 | 90 -- docs/libcurl/curl_easy_perform.md | 83 + docs/libcurl/curl_easy_recv.3 | 109 -- docs/libcurl/curl_easy_recv.md | 103 ++ docs/libcurl/curl_easy_reset.3 | 61 - docs/libcurl/curl_easy_reset.md | 56 + docs/libcurl/curl_easy_send.3 | 101 -- docs/libcurl/curl_easy_send.md | 95 ++ docs/libcurl/curl_easy_setopt.3 | 751 --------- docs/libcurl/curl_easy_setopt.md | 1381 +++++++++++++++++ docs/libcurl/curl_easy_strerror.3 | 64 - docs/libcurl/curl_easy_strerror.md | 59 + docs/libcurl/curl_easy_unescape.3 | 79 - docs/libcurl/curl_easy_unescape.md | 73 + docs/libcurl/curl_easy_upkeep.3 | 84 - docs/libcurl/curl_easy_upkeep.md | 77 + docs/libcurl/curl_escape.3 | 63 - docs/libcurl/curl_escape.md | 58 + .../{curl_formadd.3 => curl_formadd.md} | 244 +-- docs/libcurl/curl_formfree.3 | 81 - docs/libcurl/curl_formfree.md | 76 + docs/libcurl/curl_formget.3 | 77 - docs/libcurl/curl_formget.md | 72 + docs/libcurl/curl_free.3 | 57 - docs/libcurl/curl_free.md | 52 + .../{curl_getdate.3 => curl_getdate.md} | 108 +- docs/libcurl/curl_getenv.3 | 60 - docs/libcurl/curl_getenv.md | 57 + docs/libcurl/curl_global_cleanup.3 | 77 - docs/libcurl/curl_global_cleanup.md | 74 + ...curl_global_init.3 => curl_global_init.md} | 115 +- docs/libcurl/curl_global_init_mem.3 | 88 -- docs/libcurl/curl_global_init_mem.md | 95 ++ docs/libcurl/curl_global_sslset.3 | 139 -- docs/libcurl/curl_global_sslset.md | 138 ++ ...rl_global_trace.3 => curl_global_trace.md} | 107 +- docs/libcurl/curl_mime_addpart.3 | 75 - docs/libcurl/curl_mime_addpart.md | 70 + docs/libcurl/curl_mime_data.3 | 81 - docs/libcurl/curl_mime_data.md | 76 + ...rl_mime_data_cb.3 => curl_mime_data_cb.md} | 109 +- docs/libcurl/curl_mime_encoder.3 | 105 -- docs/libcurl/curl_mime_encoder.md | 100 ++ docs/libcurl/curl_mime_filedata.3 | 93 -- docs/libcurl/curl_mime_filedata.md | 88 ++ docs/libcurl/curl_mime_filename.3 | 84 - docs/libcurl/curl_mime_filename.md | 79 + docs/libcurl/curl_mime_free.3 | 70 - docs/libcurl/curl_mime_free.md | 65 + docs/libcurl/curl_mime_headers.3 | 83 - docs/libcurl/curl_mime_headers.md | 78 + docs/libcurl/curl_mime_init.3 | 77 - docs/libcurl/curl_mime_init.md | 72 + docs/libcurl/curl_mime_name.3 | 72 - docs/libcurl/curl_mime_name.md | 67 + docs/libcurl/curl_mime_subparts.3 | 88 -- docs/libcurl/curl_mime_subparts.md | 83 + docs/libcurl/curl_mime_type.3 | 91 -- docs/libcurl/curl_mime_type.md | 86 + .../{curl_mprintf.3 => curl_mprintf.md} | 293 ++-- docs/libcurl/curl_multi_add_handle.3 | 93 -- docs/libcurl/curl_multi_add_handle.md | 88 ++ docs/libcurl/curl_multi_assign.3 | 84 - docs/libcurl/curl_multi_assign.md | 81 + docs/libcurl/curl_multi_cleanup.3 | 70 - docs/libcurl/curl_multi_cleanup.md | 65 + docs/libcurl/curl_multi_fdset.3 | 124 -- docs/libcurl/curl_multi_fdset.md | 119 ++ docs/libcurl/curl_multi_get_handles.3 | 82 - docs/libcurl/curl_multi_get_handles.md | 77 + ...ti_info_read.3 => curl_multi_info_read.md} | 93 +- docs/libcurl/curl_multi_init.3 | 62 - docs/libcurl/curl_multi_init.md | 57 + docs/libcurl/curl_multi_perform.3 | 110 -- docs/libcurl/curl_multi_perform.md | 107 ++ .../{curl_multi_poll.3 => curl_multi_poll.md} | 117 +- docs/libcurl/curl_multi_remove_handle.3 | 78 - docs/libcurl/curl_multi_remove_handle.md | 73 + docs/libcurl/curl_multi_setopt.3 | 98 -- docs/libcurl/curl_multi_setopt.md | 125 ++ docs/libcurl/curl_multi_socket.3 | 100 -- docs/libcurl/curl_multi_socket.md | 95 ++ docs/libcurl/curl_multi_socket_action.3 | 123 -- docs/libcurl/curl_multi_socket_action.md | 120 ++ docs/libcurl/curl_multi_socket_all.3 | 1 - docs/libcurl/curl_multi_socket_all.md | 95 ++ docs/libcurl/curl_multi_strerror.3 | 56 - docs/libcurl/curl_multi_strerror.md | 51 + docs/libcurl/curl_multi_timeout.3 | 93 -- docs/libcurl/curl_multi_timeout.md | 89 ++ docs/libcurl/curl_multi_wait.3 | 118 -- docs/libcurl/curl_multi_wait.md | 121 ++ docs/libcurl/curl_multi_wakeup.3 | 96 -- docs/libcurl/curl_multi_wakeup.md | 91 ++ ...der_byname.3 => curl_pushheader_byname.md} | 72 +- docs/libcurl/curl_pushheader_bynum.3 | 75 - docs/libcurl/curl_pushheader_bynum.md | 69 + docs/libcurl/curl_share_cleanup.3 | 59 - docs/libcurl/curl_share_cleanup.md | 54 + docs/libcurl/curl_share_init.3 | 61 - docs/libcurl/curl_share_init.md | 56 + docs/libcurl/curl_share_setopt.3 | 65 - docs/libcurl/curl_share_setopt.md | 71 + docs/libcurl/curl_share_strerror.3 | 55 - docs/libcurl/curl_share_strerror.md | 50 + docs/libcurl/curl_slist_append.3 | 80 - docs/libcurl/curl_slist_append.md | 75 + docs/libcurl/curl_slist_free_all.3 | 63 - docs/libcurl/curl_slist_free_all.md | 58 + docs/libcurl/curl_strequal.3 | 61 - docs/libcurl/curl_strequal.md | 57 + docs/libcurl/curl_strnequal.3 | 1 - docs/libcurl/curl_strnequal.md | 57 + docs/libcurl/curl_unescape.3 | 70 - docs/libcurl/curl_unescape.md | 65 + docs/libcurl/curl_url.3 | 69 - docs/libcurl/curl_url.md | 64 + docs/libcurl/curl_url_cleanup.3 | 56 - docs/libcurl/curl_url_cleanup.md | 51 + docs/libcurl/curl_url_dup.3 | 61 - docs/libcurl/curl_url_dup.md | 56 + .../{curl_url_get.3 => curl_url_get.md} | 204 ++- .../{curl_url_set.3 => curl_url_set.md} | 224 +-- docs/libcurl/curl_url_strerror.3 | 58 - docs/libcurl/curl_url_strerror.md | 53 + docs/libcurl/curl_version.3 | 52 - docs/libcurl/curl_version.md | 46 + ...rl_version_info.3 => curl_version_info.md} | 324 ++-- .../{curl_ws_meta.3 => curl_ws_meta.md} | 134 +- docs/libcurl/curl_ws_recv.3 | 79 - docs/libcurl/curl_ws_recv.md | 73 + docs/libcurl/curl_ws_send.3 | 111 -- docs/libcurl/curl_ws_send.md | 120 ++ docs/libcurl/libcurl-easy.3 | 65 - docs/libcurl/libcurl-easy.md | 52 + docs/libcurl/libcurl-env-dbg.3 | 97 -- docs/libcurl/libcurl-env-dbg.md | 118 ++ docs/libcurl/libcurl-env.3 | 92 -- docs/libcurl/libcurl-env.md | 99 ++ .../{libcurl-errors.3 => libcurl-errors.md} | 760 ++++++--- .../{libcurl-multi.3 => libcurl-multi.md} | 134 +- ...libcurl-security.3 => libcurl-security.md} | 285 ++-- docs/libcurl/libcurl-share.3 | 71 - docs/libcurl/libcurl-share.md | 63 + docs/libcurl/libcurl-thread.3 | 96 -- docs/libcurl/libcurl-thread.md | 99 ++ ...libcurl-tutorial.3 => libcurl-tutorial.md} | 730 ++++----- .../libcurl/{libcurl-url.3 => libcurl-url.md} | 165 +- docs/libcurl/{libcurl-ws.3 => libcurl-ws.md} | 109 +- docs/libcurl/{libcurl.3 => libcurl.md} | 195 +-- docs/libcurl/mksymbolsmanpage.pl | 52 +- docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 | 81 - docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md | 77 + docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 | 75 - docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md | 71 + .../libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 | 77 - .../opts/CURLINFO_APPCONNECT_TIME_T.md | 73 + docs/libcurl/opts/CURLINFO_CAINFO.3 | 70 - docs/libcurl/opts/CURLINFO_CAINFO.md | 66 + docs/libcurl/opts/CURLINFO_CAPATH.3 | 70 - docs/libcurl/opts/CURLINFO_CAPATH.md | 66 + docs/libcurl/opts/CURLINFO_CERTINFO.3 | 105 -- docs/libcurl/opts/CURLINFO_CERTINFO.md | 101 ++ docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 | 84 - docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md | 80 + docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 | 71 - docs/libcurl/opts/CURLINFO_CONNECT_TIME.md | 67 + docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 | 74 - docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md | 70 + docs/libcurl/opts/CURLINFO_CONN_ID.3 | 75 - docs/libcurl/opts/CURLINFO_CONN_ID.md | 70 + .../opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 | 74 - .../opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md | 70 + .../opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 | 71 - .../CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md | 67 + .../opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 | 73 - .../opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md | 69 + .../opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 | 70 - .../opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md | 66 + docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 | 79 - docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md | 75 + docs/libcurl/opts/CURLINFO_COOKIELIST.3 | 86 - docs/libcurl/opts/CURLINFO_COOKIELIST.md | 82 + docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 | 76 - .../libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md | 72 + docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 | 72 - docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md | 68 + docs/libcurl/opts/CURLINFO_FILETIME.3 | 80 - docs/libcurl/opts/CURLINFO_FILETIME.md | 76 + docs/libcurl/opts/CURLINFO_FILETIME_T.3 | 82 - docs/libcurl/opts/CURLINFO_FILETIME_T.md | 78 + docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 | 74 - docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md | 70 + docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 | 69 - docs/libcurl/opts/CURLINFO_HEADER_SIZE.md | 65 + docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 | 81 - docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md | 77 + docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 | 69 - .../libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md | 65 + docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 | 65 - docs/libcurl/opts/CURLINFO_HTTP_VERSION.md | 61 + docs/libcurl/opts/CURLINFO_LASTSOCKET.3 | 81 - docs/libcurl/opts/CURLINFO_LASTSOCKET.md | 77 + docs/libcurl/opts/CURLINFO_LOCAL_IP.3 | 76 - docs/libcurl/opts/CURLINFO_LOCAL_IP.md | 72 + docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 | 72 - docs/libcurl/opts/CURLINFO_LOCAL_PORT.md | 68 + docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 | 72 - docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md | 68 + .../libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 | 73 - .../opts/CURLINFO_NAMELOOKUP_TIME_T.md | 69 + docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 | 69 - docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md | 65 + docs/libcurl/opts/CURLINFO_OS_ERRNO.3 | 66 - docs/libcurl/opts/CURLINFO_OS_ERRNO.md | 62 + docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 | 77 - .../libcurl/opts/CURLINFO_PRETRANSFER_TIME.md | 73 + .../opts/CURLINFO_PRETRANSFER_TIME_T.3 | 79 - .../opts/CURLINFO_PRETRANSFER_TIME_T.md | 75 + docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 | 77 - docs/libcurl/opts/CURLINFO_PRIMARY_IP.md | 73 + docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 | 71 - docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md | 67 + docs/libcurl/opts/CURLINFO_PRIVATE.3 | 72 - docs/libcurl/opts/CURLINFO_PRIVATE.md | 68 + docs/libcurl/opts/CURLINFO_PROTOCOL.3 | 76 - docs/libcurl/opts/CURLINFO_PROTOCOL.md | 73 + docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 | 82 - docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md | 78 + docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 | 109 -- docs/libcurl/opts/CURLINFO_PROXY_ERROR.md | 105 ++ .../opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 | 68 - .../opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md | 64 + docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 | 74 - docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md | 70 + docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 | 66 - docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md | 62 + docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 | 74 - docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md | 70 + docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 | 76 - docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md | 72 + docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 | 73 - docs/libcurl/opts/CURLINFO_REDIRECT_URL.md | 69 + docs/libcurl/opts/CURLINFO_REFERER.3 | 71 - docs/libcurl/opts/CURLINFO_REFERER.md | 67 + docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 | 67 - docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md | 63 + docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 | 69 - docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md | 65 + docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 | 73 - docs/libcurl/opts/CURLINFO_RETRY_AFTER.md | 71 + docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 | 65 - .../libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md | 61 + docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 | 65 - docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md | 61 + docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 | 69 - .../libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md | 65 + docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 | 70 - docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md | 66 + docs/libcurl/opts/CURLINFO_SCHEME.3 | 72 - docs/libcurl/opts/CURLINFO_SCHEME.md | 68 + docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 | 77 - docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md | 73 + docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 | 74 - docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md | 70 + docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 | 73 - docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md | 69 + docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 | 70 - docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md | 66 + docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 | 72 - docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md | 67 + docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 | 70 - .../libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md | 65 + docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 | 70 - docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md | 65 + docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 | 68 - docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md | 63 + docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 | 69 - docs/libcurl/opts/CURLINFO_SSL_ENGINES.md | 65 + docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 | 69 - .../libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md | 65 + .../opts/CURLINFO_STARTTRANSFER_TIME.3 | 75 - .../opts/CURLINFO_STARTTRANSFER_TIME.md | 71 + .../opts/CURLINFO_STARTTRANSFER_TIME_T.3 | 77 - .../opts/CURLINFO_STARTTRANSFER_TIME_T.md | 73 + docs/libcurl/opts/CURLINFO_TLS_SESSION.3 | 78 - docs/libcurl/opts/CURLINFO_TLS_SESSION.md | 75 + ..._TLS_SSL_PTR.3 => CURLINFO_TLS_SSL_PTR.md} | 165 +- docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 | 73 - docs/libcurl/opts/CURLINFO_TOTAL_TIME.md | 69 + docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 | 75 - docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md | 71 + docs/libcurl/opts/CURLINFO_XFER_ID.3 | 75 - docs/libcurl/opts/CURLINFO_XFER_ID.md | 70 + .../opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 | 63 - .../CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md | 61 + .../CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 | 62 - .../CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md | 60 + docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 | 72 - docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md | 69 + .../opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 | 61 - .../opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md | 59 + .../opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 | 74 - .../opts/CURLMOPT_MAX_HOST_CONNECTIONS.md | 72 + .../opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 | 66 - .../opts/CURLMOPT_MAX_PIPELINE_LENGTH.md | 64 + .../opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 | 72 - .../opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md | 70 + docs/libcurl/opts/CURLMOPT_PIPELINING.3 | 74 - docs/libcurl/opts/CURLMOPT_PIPELINING.md | 77 + .../opts/CURLMOPT_PIPELINING_SERVER_BL.3 | 71 - .../opts/CURLMOPT_PIPELINING_SERVER_BL.md | 68 + .../opts/CURLMOPT_PIPELINING_SITE_BL.3 | 68 - .../opts/CURLMOPT_PIPELINING_SITE_BL.md | 66 + docs/libcurl/opts/CURLMOPT_PUSHDATA.3 | 89 -- docs/libcurl/opts/CURLMOPT_PUSHDATA.md | 87 ++ ...USHFUNCTION.3 => CURLMOPT_PUSHFUNCTION.md} | 125 +- docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 | 83 - docs/libcurl/opts/CURLMOPT_SOCKETDATA.md | 82 + docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 | 126 -- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 135 ++ docs/libcurl/opts/CURLMOPT_TIMERDATA.3 | 76 - docs/libcurl/opts/CURLMOPT_TIMERDATA.md | 75 + docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 | 104 -- docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md | 103 ++ .../opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 | 73 - .../opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md | 71 + docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 | 63 - docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md | 61 + ..._ENCODING.3 => CURLOPT_ACCEPT_ENCODING.md} | 104 +- docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 | 65 - docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md | 63 + docs/libcurl/opts/CURLOPT_ALTSVC.3 | 94 -- docs/libcurl/opts/CURLOPT_ALTSVC.md | 111 ++ docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 | 91 -- docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md | 97 ++ docs/libcurl/opts/CURLOPT_APPEND.3 | 63 - docs/libcurl/opts/CURLOPT_APPEND.md | 61 + docs/libcurl/opts/CURLOPT_AUTOREFERER.3 | 79 - docs/libcurl/opts/CURLOPT_AUTOREFERER.md | 77 + docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 | 111 -- docs/libcurl/opts/CURLOPT_AWS_SIGV4.md | 118 ++ docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 | 81 - docs/libcurl/opts/CURLOPT_BUFFERSIZE.md | 79 + docs/libcurl/opts/CURLOPT_CAINFO.3 | 89 -- docs/libcurl/opts/CURLOPT_CAINFO.md | 87 ++ docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 | 85 - docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md | 84 + docs/libcurl/opts/CURLOPT_CAPATH.3 | 81 - docs/libcurl/opts/CURLOPT_CAPATH.md | 79 + docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 | 84 - docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md | 82 + docs/libcurl/opts/CURLOPT_CERTINFO.3 | 92 -- docs/libcurl/opts/CURLOPT_CERTINFO.md | 90 ++ ...NCTION.3 => CURLOPT_CHUNK_BGN_FUNCTION.md} | 101 +- docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 | 104 -- docs/libcurl/opts/CURLOPT_CHUNK_DATA.md | 102 ++ .../libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 | 83 - .../opts/CURLOPT_CHUNK_END_FUNCTION.md | 82 + docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 | 77 - docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md | 75 + .../opts/CURLOPT_CLOSESOCKETFUNCTION.3 | 88 -- .../opts/CURLOPT_CLOSESOCKETFUNCTION.md | 86 + docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 | 91 -- docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md | 89 ++ docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 | 66 - .../libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md | 64 + docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 | 85 - docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md | 83 + ...OPT_CONNECT_TO.3 => CURLOPT_CONNECT_TO.md} | 103 +- .../opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 | 111 -- .../CURLOPT_CONV_FROM_NETWORK_FUNCTION.md | 114 ++ .../opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 | 106 -- .../opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md | 107 ++ .../opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 | 108 -- .../opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md | 110 ++ .../{CURLOPT_COOKIE.3 => CURLOPT_COOKIE.md} | 96 +- ...OPT_COOKIEFILE.3 => CURLOPT_COOKIEFILE.md} | 94 +- docs/libcurl/opts/CURLOPT_COOKIEJAR.3 | 88 -- docs/libcurl/opts/CURLOPT_COOKIEJAR.md | 86 + ...OPT_COOKIELIST.3 => CURLOPT_COOKIELIST.md} | 115 +- docs/libcurl/opts/CURLOPT_COOKIESESSION.3 | 77 - docs/libcurl/opts/CURLOPT_COOKIESESSION.md | 75 + docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 | 80 - docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md | 78 + docs/libcurl/opts/CURLOPT_CRLF.3 | 64 - docs/libcurl/opts/CURLOPT_CRLF.md | 62 + docs/libcurl/opts/CURLOPT_CRLFILE.3 | 84 - docs/libcurl/opts/CURLOPT_CRLFILE.md | 82 + docs/libcurl/opts/CURLOPT_CURLU.3 | 81 - docs/libcurl/opts/CURLOPT_CURLU.md | 79 + docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 | 124 -- docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md | 130 ++ docs/libcurl/opts/CURLOPT_DEBUGDATA.3 | 88 -- docs/libcurl/opts/CURLOPT_DEBUGDATA.md | 86 + ...BUGFUNCTION.3 => CURLOPT_DEBUGFUNCTION.md} | 145 +- docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 | 91 -- docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md | 89 ++ docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 | 82 - docs/libcurl/opts/CURLOPT_DIRLISTONLY.md | 80 + .../opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 | 70 - .../opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md | 68 + ...TIMEOUT.3 => CURLOPT_DNS_CACHE_TIMEOUT.md} | 88 +- docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 | 71 - docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md | 69 + docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 | 72 - docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md | 70 + docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 | 72 - docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md | 70 + docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 | 78 - docs/libcurl/opts/CURLOPT_DNS_SERVERS.md | 76 + .../opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 | 77 - .../opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md | 75 + .../opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 | 70 - .../opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md | 68 + .../libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 | 92 -- .../opts/CURLOPT_DOH_SSL_VERIFYHOST.md | 90 ++ .../libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 | 105 -- .../opts/CURLOPT_DOH_SSL_VERIFYPEER.md | 102 ++ .../opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 | 78 - .../opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md | 76 + docs/libcurl/opts/CURLOPT_DOH_URL.3 | 95 -- docs/libcurl/opts/CURLOPT_DOH_URL.md | 96 ++ docs/libcurl/opts/CURLOPT_EGDSOCKET.3 | 69 - docs/libcurl/opts/CURLOPT_EGDSOCKET.md | 67 + docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 | 103 -- docs/libcurl/opts/CURLOPT_ERRORBUFFER.md | 101 ++ .../opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 | 65 - .../opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md | 64 + docs/libcurl/opts/CURLOPT_FAILONERROR.3 | 76 - docs/libcurl/opts/CURLOPT_FAILONERROR.md | 74 + docs/libcurl/opts/CURLOPT_FILETIME.3 | 74 - docs/libcurl/opts/CURLOPT_FILETIME.md | 72 + docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 | 81 - docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md | 80 + docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 | 89 -- docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md | 88 ++ docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 | 93 -- docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md | 93 ++ docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 | 71 - docs/libcurl/opts/CURLOPT_FORBID_REUSE.md | 69 + docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 | 70 - docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md | 68 + .../{CURLOPT_FTPPORT.3 => CURLOPT_FTPPORT.md} | 88 +- docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 | 72 - docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md | 76 + docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 | 69 - docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md | 67 + .../opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 | 70 - .../opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md | 70 + .../opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 | 89 -- .../opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md | 88 ++ docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 | 81 - docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md | 86 + docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 | 74 - docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md | 72 + docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 | 74 - docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md | 78 + docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 | 78 - docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md | 73 + docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 | 76 - docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md | 73 + docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 | 68 - docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md | 66 + docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 | 68 - .../libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md | 65 + .../opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 | 72 - .../opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md | 71 + docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 | 66 - docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md | 64 + docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 | 65 - .../libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md | 63 + docs/libcurl/opts/CURLOPT_HEADER.3 | 78 - docs/libcurl/opts/CURLOPT_HEADER.md | 76 + docs/libcurl/opts/CURLOPT_HEADERDATA.3 | 91 -- docs/libcurl/opts/CURLOPT_HEADERDATA.md | 89 ++ ...ERFUNCTION.3 => CURLOPT_HEADERFUNCTION.md} | 104 +- docs/libcurl/opts/CURLOPT_HEADEROPT.3 | 83 - docs/libcurl/opts/CURLOPT_HEADEROPT.md | 81 + docs/libcurl/opts/CURLOPT_HSTS.3 | 83 - docs/libcurl/opts/CURLOPT_HSTS.md | 83 + docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 | 74 - docs/libcurl/opts/CURLOPT_HSTSREADDATA.md | 72 + docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 | 108 -- docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md | 106 ++ docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 | 74 - docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md | 72 + docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 | 112 -- .../libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md | 110 ++ docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 | 75 - docs/libcurl/opts/CURLOPT_HSTS_CTRL.md | 78 + docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 | 66 - docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md | 64 + docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 | 76 - docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md | 75 + ...CURLOPT_HTTPAUTH.3 => CURLOPT_HTTPAUTH.md} | 160 +- docs/libcurl/opts/CURLOPT_HTTPGET.3 | 73 - docs/libcurl/opts/CURLOPT_HTTPGET.md | 71 + ...OPT_HTTPHEADER.3 => CURLOPT_HTTPHEADER.md} | 149 +- docs/libcurl/opts/CURLOPT_HTTPPOST.3 | 101 -- docs/libcurl/opts/CURLOPT_HTTPPOST.md | 100 ++ docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 | 77 - docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md | 75 + .../opts/CURLOPT_HTTP_CONTENT_DECODING.3 | 63 - .../opts/CURLOPT_HTTP_CONTENT_DECODING.md | 62 + .../opts/CURLOPT_HTTP_TRANSFER_DECODING.3 | 62 - .../opts/CURLOPT_HTTP_TRANSFER_DECODING.md | 61 + ...HTTP_VERSION.3 => CURLOPT_HTTP_VERSION.md} | 121 +- .../opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 | 74 - .../opts/CURLOPT_IGNORE_CONTENT_LENGTH.md | 73 + docs/libcurl/opts/CURLOPT_INFILESIZE.3 | 87 -- docs/libcurl/opts/CURLOPT_INFILESIZE.md | 85 + docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 | 82 - docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md | 81 + docs/libcurl/opts/CURLOPT_INTERFACE.3 | 85 - docs/libcurl/opts/CURLOPT_INTERFACE.md | 83 + docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 | 74 - docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md | 72 + ...NCTION.3 => CURLOPT_INTERLEAVEFUNCTION.md} | 93 +- docs/libcurl/opts/CURLOPT_IOCTLDATA.3 | 74 - docs/libcurl/opts/CURLOPT_IOCTLDATA.md | 72 + ...CTLFUNCTION.3 => CURLOPT_IOCTLFUNCTION.md} | 91 +- docs/libcurl/opts/CURLOPT_IPRESOLVE.3 | 79 - docs/libcurl/opts/CURLOPT_IPRESOLVE.md | 83 + docs/libcurl/opts/CURLOPT_ISSUERCERT.3 | 79 - docs/libcurl/opts/CURLOPT_ISSUERCERT.md | 77 + ...CERT_BLOB.3 => CURLOPT_ISSUERCERT_BLOB.md} | 90 +- .../opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 | 70 - .../opts/CURLOPT_KEEP_SENDING_ON_ERROR.md | 68 + docs/libcurl/opts/CURLOPT_KEYPASSWD.3 | 70 - docs/libcurl/opts/CURLOPT_KEYPASSWD.md | 68 + docs/libcurl/opts/CURLOPT_KRBLEVEL.3 | 68 - docs/libcurl/opts/CURLOPT_KRBLEVEL.md | 66 + docs/libcurl/opts/CURLOPT_LOCALPORT.3 | 66 - docs/libcurl/opts/CURLOPT_LOCALPORT.md | 64 + docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 | 69 - docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md | 67 + docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 | 79 - docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md | 76 + docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 | 72 - docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md | 70 + docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 | 69 - docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md | 67 + docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 | 78 - docs/libcurl/opts/CURLOPT_MAIL_AUTH.md | 76 + docs/libcurl/opts/CURLOPT_MAIL_FROM.3 | 71 - docs/libcurl/opts/CURLOPT_MAIL_FROM.md | 69 + docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 | 81 - docs/libcurl/opts/CURLOPT_MAIL_RCPT.md | 80 + .../opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 | 82 - .../opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md | 81 + docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 | 73 - docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md | 71 + docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 | 77 - docs/libcurl/opts/CURLOPT_MAXCONNECTS.md | 75 + docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 | 71 - docs/libcurl/opts/CURLOPT_MAXFILESIZE.md | 69 + docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 | 71 - .../libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md | 70 + docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 | 75 - docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md | 73 + docs/libcurl/opts/CURLOPT_MAXREDIRS.3 | 74 - docs/libcurl/opts/CURLOPT_MAXREDIRS.md | 72 + .../opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 | 71 - .../opts/CURLOPT_MAX_RECV_SPEED_LARGE.md | 70 + .../opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 | 73 - .../opts/CURLOPT_MAX_SEND_SPEED_LARGE.md | 72 + docs/libcurl/opts/CURLOPT_MIMEPOST.3 | 84 - docs/libcurl/opts/CURLOPT_MIMEPOST.md | 81 + docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3 | 97 -- docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md | 97 ++ docs/libcurl/opts/CURLOPT_NETRC.3 | 126 -- docs/libcurl/opts/CURLOPT_NETRC.md | 141 ++ docs/libcurl/opts/CURLOPT_NETRC_FILE.3 | 68 - docs/libcurl/opts/CURLOPT_NETRC_FILE.md | 66 + .../opts/CURLOPT_NEW_DIRECTORY_PERMS.3 | 65 - .../opts/CURLOPT_NEW_DIRECTORY_PERMS.md | 64 + docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 | 62 - docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md | 60 + docs/libcurl/opts/CURLOPT_NOBODY.3 | 80 - docs/libcurl/opts/CURLOPT_NOBODY.md | 78 + docs/libcurl/opts/CURLOPT_NOPROGRESS.3 | 67 - docs/libcurl/opts/CURLOPT_NOPROGRESS.md | 65 + docs/libcurl/opts/CURLOPT_NOPROXY.3 | 91 -- docs/libcurl/opts/CURLOPT_NOPROXY.md | 91 ++ docs/libcurl/opts/CURLOPT_NOSIGNAL.3 | 80 - docs/libcurl/opts/CURLOPT_NOSIGNAL.md | 78 + ...SOCKETDATA.3 => CURLOPT_OPENSOCKETDATA.md} | 86 +- ...NCTION.3 => CURLOPT_OPENSOCKETFUNCTION.md} | 107 +- docs/libcurl/opts/CURLOPT_PASSWORD.3 | 73 - docs/libcurl/opts/CURLOPT_PASSWORD.md | 71 + docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 | 77 - docs/libcurl/opts/CURLOPT_PATH_AS_IS.md | 75 + ...PUBLICKEY.3 => CURLOPT_PINNEDPUBLICKEY.md} | 137 +- docs/libcurl/opts/CURLOPT_PIPEWAIT.3 | 80 - docs/libcurl/opts/CURLOPT_PIPEWAIT.md | 78 + docs/libcurl/opts/CURLOPT_PORT.3 | 74 - docs/libcurl/opts/CURLOPT_PORT.md | 72 + docs/libcurl/opts/CURLOPT_POST.3 | 104 -- docs/libcurl/opts/CURLOPT_POST.md | 102 ++ docs/libcurl/opts/CURLOPT_POSTFIELDS.3 | 126 -- docs/libcurl/opts/CURLOPT_POSTFIELDS.md | 124 ++ docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 | 73 - docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md | 71 + .../opts/CURLOPT_POSTFIELDSIZE_LARGE.3 | 73 - .../opts/CURLOPT_POSTFIELDSIZE_LARGE.md | 72 + docs/libcurl/opts/CURLOPT_POSTQUOTE.3 | 74 - docs/libcurl/opts/CURLOPT_POSTQUOTE.md | 72 + docs/libcurl/opts/CURLOPT_POSTREDIR.3 | 82 - docs/libcurl/opts/CURLOPT_POSTREDIR.md | 81 + docs/libcurl/opts/CURLOPT_PREQUOTE.3 | 78 - docs/libcurl/opts/CURLOPT_PREQUOTE.md | 76 + docs/libcurl/opts/CURLOPT_PREREQDATA.3 | 75 - docs/libcurl/opts/CURLOPT_PREREQDATA.md | 73 + ...EQFUNCTION.3 => CURLOPT_PREREQFUNCTION.md} | 111 +- ...RLOPT_PRE_PROXY.3 => CURLOPT_PRE_PROXY.md} | 88 +- docs/libcurl/opts/CURLOPT_PRIVATE.3 | 74 - docs/libcurl/opts/CURLOPT_PRIVATE.md | 72 + docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 | 82 - docs/libcurl/opts/CURLOPT_PROGRESSDATA.md | 80 + ...FUNCTION.3 => CURLOPT_PROGRESSFUNCTION.md} | 100 +- docs/libcurl/opts/CURLOPT_PROTOCOLS.3 | 106 -- docs/libcurl/opts/CURLOPT_PROTOCOLS.md | 104 ++ docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.3 | 90 -- docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md | 88 ++ docs/libcurl/opts/CURLOPT_PROXY.3 | 137 -- docs/libcurl/opts/CURLOPT_PROXY.md | 146 ++ docs/libcurl/opts/CURLOPT_PROXYAUTH.3 | 79 - docs/libcurl/opts/CURLOPT_PROXYAUTH.md | 77 + docs/libcurl/opts/CURLOPT_PROXYHEADER.3 | 81 - docs/libcurl/opts/CURLOPT_PROXYHEADER.md | 80 + docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 | 72 - docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md | 70 + docs/libcurl/opts/CURLOPT_PROXYPORT.3 | 70 - docs/libcurl/opts/CURLOPT_PROXYPORT.md | 68 + docs/libcurl/opts/CURLOPT_PROXYTYPE.3 | 88 -- docs/libcurl/opts/CURLOPT_PROXYTYPE.md | 99 ++ docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 | 74 - docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md | 73 + docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 | 73 - docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md | 71 + docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 | 95 -- docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md | 93 ++ docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 | 94 -- .../libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md | 92 ++ docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 | 83 - docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md | 81 + docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 | 85 - docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md | 83 + docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 | 84 - docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md | 82 + ...LOB.3 => CURLOPT_PROXY_ISSUERCERT_BLOB.md} | 95 +- docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 | 72 - docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md | 70 + ...KEY.3 => CURLOPT_PROXY_PINNEDPUBLICKEY.md} | 119 +- .../libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 | 67 - .../opts/CURLOPT_PROXY_SERVICE_NAME.md | 65 + docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 | 81 - docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md | 79 + docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 | 77 - .../libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md | 75 + .../libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 | 87 -- .../opts/CURLOPT_PROXY_SSLCERT_BLOB.md | 85 + docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 | 79 - docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md | 77 + docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 | 70 - docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md | 66 + ...EY_BLOB.3 => CURLOPT_PROXY_SSLKEY_BLOB.md} | 84 +- docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 | 110 -- docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md | 125 ++ .../opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 | 93 -- .../opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md | 91 ++ ...OPTIONS.3 => CURLOPT_PROXY_SSL_OPTIONS.md} | 116 +- .../opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 | 96 -- .../opts/CURLOPT_PROXY_SSL_VERIFYHOST.md | 94 ++ .../opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 | 97 -- .../opts/CURLOPT_PROXY_SSL_VERIFYPEER.md | 94 ++ .../opts/CURLOPT_PROXY_TLS13_CIPHERS.3 | 80 - .../opts/CURLOPT_PROXY_TLS13_CIPHERS.md | 78 + .../opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 | 73 - .../opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md | 71 + .../libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 | 81 - .../opts/CURLOPT_PROXY_TLSAUTH_TYPE.md | 80 + .../opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 | 73 - .../opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md | 71 + .../opts/CURLOPT_PROXY_TRANSFER_MODE.3 | 71 - .../opts/CURLOPT_PROXY_TRANSFER_MODE.md | 69 + docs/libcurl/opts/CURLOPT_PUT.3 | 92 -- docs/libcurl/opts/CURLOPT_PUT.md | 89 ++ docs/libcurl/opts/CURLOPT_QUICK_EXIT.3 | 63 - docs/libcurl/opts/CURLOPT_QUICK_EXIT.md | 62 + .../{CURLOPT_QUOTE.3 => CURLOPT_QUOTE.md} | 158 +- docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 | 69 - docs/libcurl/opts/CURLOPT_RANDOM_FILE.md | 67 + docs/libcurl/opts/CURLOPT_RANGE.3 | 86 - docs/libcurl/opts/CURLOPT_RANGE.md | 84 + docs/libcurl/opts/CURLOPT_READDATA.3 | 79 - docs/libcurl/opts/CURLOPT_READDATA.md | 77 + docs/libcurl/opts/CURLOPT_READFUNCTION.3 | 125 -- docs/libcurl/opts/CURLOPT_READFUNCTION.md | 123 ++ docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 | 117 -- docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md | 115 ++ ...S_STR.3 => CURLOPT_REDIR_PROTOCOLS_STR.md} | 90 +- docs/libcurl/opts/CURLOPT_REFERER.3 | 69 - docs/libcurl/opts/CURLOPT_REFERER.md | 67 + docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 | 69 - docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md | 67 + .../{CURLOPT_RESOLVE.3 => CURLOPT_RESOLVE.md} | 95 +- .../opts/CURLOPT_RESOLVER_START_DATA.3 | 72 - .../opts/CURLOPT_RESOLVER_START_DATA.md | 70 + .../opts/CURLOPT_RESOLVER_START_FUNCTION.3 | 89 -- .../opts/CURLOPT_RESOLVER_START_FUNCTION.md | 88 ++ docs/libcurl/opts/CURLOPT_RESUME_FROM.3 | 82 - docs/libcurl/opts/CURLOPT_RESUME_FROM.md | 80 + docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 | 80 - .../libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md | 79 + docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 | 64 - docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md | 62 + docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 | 122 -- docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md | 140 ++ docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 | 63 - docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md | 61 + docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 | 69 - docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md | 68 + docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 | 74 - docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md | 72 + docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 | 69 - docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md | 68 + docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 | 74 - docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md | 72 + docs/libcurl/opts/CURLOPT_SASL_IR.3 | 74 - docs/libcurl/opts/CURLOPT_SASL_IR.md | 72 + docs/libcurl/opts/CURLOPT_SEEKDATA.3 | 73 - docs/libcurl/opts/CURLOPT_SEEKDATA.md | 71 + ...SEEKFUNCTION.3 => CURLOPT_SEEKFUNCTION.md} | 95 +- .../opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 | 77 - .../opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md | 75 + .../opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 | 76 - .../CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md | 74 + docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 | 68 - docs/libcurl/opts/CURLOPT_SERVICE_NAME.md | 66 + docs/libcurl/opts/CURLOPT_SHARE.3 | 90 -- docs/libcurl/opts/CURLOPT_SHARE.md | 88 ++ docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 | 77 - docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md | 75 + ...TFUNCTION.3 => CURLOPT_SOCKOPTFUNCTION.md} | 105 +- docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 | 71 - docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md | 69 + docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 | 65 - .../libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md | 63 + .../opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 | 70 - .../opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md | 68 + docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 | 69 - docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md | 67 + docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 | 66 - docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md | 64 + docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 | 75 - docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md | 73 + .../opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 | 96 -- .../opts/CURLOPT_SSH_HOSTKEYFUNCTION.md | 98 ++ .../opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 | 72 - .../opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md | 71 + .../opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 | 67 - .../CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md | 65 + docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 | 77 - docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md | 75 + ...YFUNCTION.3 => CURLOPT_SSH_KEYFUNCTION.md} | 111 +- docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 | 70 - docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md | 68 + .../opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 | 77 - .../opts/CURLOPT_SSH_PRIVATE_KEYFILE.md | 76 + .../libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 | 73 - .../opts/CURLOPT_SSH_PUBLIC_KEYFILE.md | 71 + docs/libcurl/opts/CURLOPT_SSLCERT.3 | 90 -- docs/libcurl/opts/CURLOPT_SSLCERT.md | 87 ++ docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 | 73 - docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md | 71 + docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 | 85 - docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md | 83 + docs/libcurl/opts/CURLOPT_SSLENGINE.3 | 76 - docs/libcurl/opts/CURLOPT_SSLENGINE.md | 74 + docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 | 72 - .../libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md | 70 + docs/libcurl/opts/CURLOPT_SSLKEY.3 | 73 - docs/libcurl/opts/CURLOPT_SSLKEY.md | 71 + docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 | 74 - docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md | 72 + ...T_SSLKEY_BLOB.3 => CURLOPT_SSLKEY_BLOB.md} | 84 +- ...OPT_SSLVERSION.3 => CURLOPT_SSLVERSION.md} | 147 +- docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 | 94 -- docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md | 92 ++ ...SSL_CTX_DATA.3 => CURLOPT_SSL_CTX_DATA.md} | 110 +- ...FUNCTION.3 => CURLOPT_SSL_CTX_FUNCTION.md} | 131 +- docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 | 63 - docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md | 61 + docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 | 62 - docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md | 60 + docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 | 64 - docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md | 62 + docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 | 64 - docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md | 62 + ...T_SSL_OPTIONS.3 => CURLOPT_SSL_OPTIONS.md} | 114 +- .../opts/CURLOPT_SSL_SESSIONID_CACHE.3 | 67 - .../opts/CURLOPT_SSL_SESSIONID_CACHE.md | 66 + ...VERIFYHOST.3 => CURLOPT_SSL_VERIFYHOST.md} | 103 +- ...VERIFYPEER.3 => CURLOPT_SSL_VERIFYPEER.md} | 98 +- docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 | 70 - docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md | 68 + docs/libcurl/opts/CURLOPT_STDERR.3 | 67 - docs/libcurl/opts/CURLOPT_STDERR.md | 65 + docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 | 79 - docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md | 77 + docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 | 82 - docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md | 80 + docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 | 83 - docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md | 81 + .../opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 | 101 -- .../opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md | 103 ++ docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 | 66 - docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md | 64 + docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 | 73 - docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md | 71 + docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 | 72 - docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md | 70 + docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 | 71 - docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md | 69 + docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 | 73 - docs/libcurl/opts/CURLOPT_TCP_NODELAY.md | 71 + docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 | 68 - docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md | 66 + docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 | 65 - docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md | 63 + docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 | 80 - docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md | 78 + docs/libcurl/opts/CURLOPT_TIMECONDITION.3 | 74 - docs/libcurl/opts/CURLOPT_TIMECONDITION.md | 72 + docs/libcurl/opts/CURLOPT_TIMEOUT.3 | 92 -- docs/libcurl/opts/CURLOPT_TIMEOUT.md | 90 ++ docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 | 66 - docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md | 64 + docs/libcurl/opts/CURLOPT_TIMEVALUE.3 | 71 - docs/libcurl/opts/CURLOPT_TIMEVALUE.md | 69 + docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 | 73 - docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md | 71 + docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 | 81 - docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md | 80 + docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 | 72 - docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md | 70 + docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 | 76 - docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md | 75 + docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 | 71 - docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md | 69 + docs/libcurl/opts/CURLOPT_TRAILERDATA.3 | 63 - docs/libcurl/opts/CURLOPT_TRAILERDATA.md | 59 + docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 | 109 -- docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md | 110 ++ docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 | 67 - docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md | 65 + docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 | 70 - .../libcurl/opts/CURLOPT_TRANSFER_ENCODING.md | 68 + docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 | 89 -- docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md | 87 ++ docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 | 80 - .../libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md | 79 + .../libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 | 85 - .../opts/CURLOPT_UPKEEP_INTERVAL_MS.md | 82 + docs/libcurl/opts/CURLOPT_UPLOAD.3 | 99 -- docs/libcurl/opts/CURLOPT_UPLOAD.md | 97 ++ docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 | 82 - .../libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md | 80 + .../opts/{CURLOPT_URL.3 => CURLOPT_URL.md} | 137 +- docs/libcurl/opts/CURLOPT_USERAGENT.3 | 68 - docs/libcurl/opts/CURLOPT_USERAGENT.md | 66 + docs/libcurl/opts/CURLOPT_USERNAME.3 | 93 -- docs/libcurl/opts/CURLOPT_USERNAME.md | 92 ++ docs/libcurl/opts/CURLOPT_USERPWD.3 | 100 -- docs/libcurl/opts/CURLOPT_USERPWD.md | 98 ++ docs/libcurl/opts/CURLOPT_USE_SSL.3 | 80 - docs/libcurl/opts/CURLOPT_USE_SSL.md | 86 + docs/libcurl/opts/CURLOPT_VERBOSE.3 | 73 - docs/libcurl/opts/CURLOPT_VERBOSE.md | 71 + docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 | 118 -- docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md | 115 ++ docs/libcurl/opts/CURLOPT_WRITEDATA.3 | 65 - docs/libcurl/opts/CURLOPT_WRITEDATA.md | 63 + ...ITEFUNCTION.3 => CURLOPT_WRITEFUNCTION.md} | 112 +- docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 | 75 - docs/libcurl/opts/CURLOPT_WS_OPTIONS.md | 75 + docs/libcurl/opts/CURLOPT_XFERINFODATA.3 | 82 - docs/libcurl/opts/CURLOPT_XFERINFODATA.md | 80 + ...FUNCTION.3 => CURLOPT_XFERINFOFUNCTION.md} | 98 +- docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 | 69 - docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md | 67 + docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 | 80 - docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md | 77 + .../{CURLSHOPT_SHARE.3 => CURLSHOPT_SHARE.md} | 119 +- docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 | 75 - docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md | 72 + docs/libcurl/opts/CURLSHOPT_UNSHARE.3 | 77 - docs/libcurl/opts/CURLSHOPT_UNSHARE.md | 84 + docs/libcurl/opts/CURLSHOPT_USERDATA.3 | 65 - docs/libcurl/opts/CURLSHOPT_USERDATA.md | 62 + docs/libcurl/opts/Makefile.am | 43 +- docs/libcurl/opts/template.3 | 41 - docs/mk-ca-bundle.1 | 120 -- docs/mk-ca-bundle.md | 128 ++ maketgz | 7 +- scripts/Makefile.am | 4 +- scripts/cd2cd | 226 +++ scripts/cd2nroff | 331 ++++ scripts/cdall | 44 + scripts/nroff2cd | 193 +++ scripts/updatemanpages.pl | 357 ----- tests/Makefile.am | 12 - tests/data/test1140 | 2 +- tests/data/test1173 | 2 +- tests/data/test1177 | 2 +- tests/data/test1477 | 2 +- tests/test1139.pl | 11 +- tests/test1140.pl | 2 + tests/test1177.pl | 4 +- tests/test1275.pl | 11 +- tests/test1477.pl | 3 +- 960 files changed, 41071 insertions(+), 39712 deletions(-) create mode 100644 docs/CURLDOWN.md rename docs/{curl-config.1 => curl-config.md} (61%) delete mode 100644 docs/libcurl/.gitignore delete mode 100644 docs/libcurl/curl_easy_cleanup.3 create mode 100644 docs/libcurl/curl_easy_cleanup.md delete mode 100644 docs/libcurl/curl_easy_duphandle.3 create mode 100644 docs/libcurl/curl_easy_duphandle.md delete mode 100644 docs/libcurl/curl_easy_escape.3 create mode 100644 docs/libcurl/curl_easy_escape.md delete mode 100644 docs/libcurl/curl_easy_getinfo.3 create mode 100644 docs/libcurl/curl_easy_getinfo.md rename docs/libcurl/{curl_easy_header.3 => curl_easy_header.md} (51%) delete mode 100644 docs/libcurl/curl_easy_init.3 create mode 100644 docs/libcurl/curl_easy_init.md delete mode 100644 docs/libcurl/curl_easy_nextheader.3 create mode 100644 docs/libcurl/curl_easy_nextheader.md delete mode 100644 docs/libcurl/curl_easy_option_by_id.3 create mode 100644 docs/libcurl/curl_easy_option_by_id.md delete mode 100644 docs/libcurl/curl_easy_option_by_name.3 create mode 100644 docs/libcurl/curl_easy_option_by_name.md delete mode 100644 docs/libcurl/curl_easy_option_next.3 create mode 100644 docs/libcurl/curl_easy_option_next.md rename docs/libcurl/{curl_easy_pause.3 => curl_easy_pause.md} (63%) delete mode 100644 docs/libcurl/curl_easy_perform.3 create mode 100644 docs/libcurl/curl_easy_perform.md delete mode 100644 docs/libcurl/curl_easy_recv.3 create mode 100644 docs/libcurl/curl_easy_recv.md delete mode 100644 docs/libcurl/curl_easy_reset.3 create mode 100644 docs/libcurl/curl_easy_reset.md delete mode 100644 docs/libcurl/curl_easy_send.3 create mode 100644 docs/libcurl/curl_easy_send.md delete mode 100644 docs/libcurl/curl_easy_setopt.3 create mode 100644 docs/libcurl/curl_easy_setopt.md delete mode 100644 docs/libcurl/curl_easy_strerror.3 create mode 100644 docs/libcurl/curl_easy_strerror.md delete mode 100644 docs/libcurl/curl_easy_unescape.3 create mode 100644 docs/libcurl/curl_easy_unescape.md delete mode 100644 docs/libcurl/curl_easy_upkeep.3 create mode 100644 docs/libcurl/curl_easy_upkeep.md delete mode 100644 docs/libcurl/curl_escape.3 create mode 100644 docs/libcurl/curl_escape.md rename docs/libcurl/{curl_formadd.3 => curl_formadd.md} (59%) delete mode 100644 docs/libcurl/curl_formfree.3 create mode 100644 docs/libcurl/curl_formfree.md delete mode 100644 docs/libcurl/curl_formget.3 create mode 100644 docs/libcurl/curl_formget.md delete mode 100644 docs/libcurl/curl_free.3 create mode 100644 docs/libcurl/curl_free.md rename docs/libcurl/{curl_getdate.3 => curl_getdate.md} (65%) delete mode 100644 docs/libcurl/curl_getenv.3 create mode 100644 docs/libcurl/curl_getenv.md delete mode 100644 docs/libcurl/curl_global_cleanup.3 create mode 100644 docs/libcurl/curl_global_cleanup.md rename docs/libcurl/{curl_global_init.3 => curl_global_init.md} (59%) delete mode 100644 docs/libcurl/curl_global_init_mem.3 create mode 100644 docs/libcurl/curl_global_init_mem.md delete mode 100644 docs/libcurl/curl_global_sslset.3 create mode 100644 docs/libcurl/curl_global_sslset.md rename docs/libcurl/{curl_global_trace.3 => curl_global_trace.md} (61%) delete mode 100644 docs/libcurl/curl_mime_addpart.3 create mode 100644 docs/libcurl/curl_mime_addpart.md delete mode 100644 docs/libcurl/curl_mime_data.3 create mode 100644 docs/libcurl/curl_mime_data.md rename docs/libcurl/{curl_mime_data_cb.3 => curl_mime_data_cb.md} (58%) delete mode 100644 docs/libcurl/curl_mime_encoder.3 create mode 100644 docs/libcurl/curl_mime_encoder.md delete mode 100644 docs/libcurl/curl_mime_filedata.3 create mode 100644 docs/libcurl/curl_mime_filedata.md delete mode 100644 docs/libcurl/curl_mime_filename.3 create mode 100644 docs/libcurl/curl_mime_filename.md delete mode 100644 docs/libcurl/curl_mime_free.3 create mode 100644 docs/libcurl/curl_mime_free.md delete mode 100644 docs/libcurl/curl_mime_headers.3 create mode 100644 docs/libcurl/curl_mime_headers.md delete mode 100644 docs/libcurl/curl_mime_init.3 create mode 100644 docs/libcurl/curl_mime_init.md delete mode 100644 docs/libcurl/curl_mime_name.3 create mode 100644 docs/libcurl/curl_mime_name.md delete mode 100644 docs/libcurl/curl_mime_subparts.3 create mode 100644 docs/libcurl/curl_mime_subparts.md delete mode 100644 docs/libcurl/curl_mime_type.3 create mode 100644 docs/libcurl/curl_mime_type.md rename docs/libcurl/{curl_mprintf.3 => curl_mprintf.md} (56%) delete mode 100644 docs/libcurl/curl_multi_add_handle.3 create mode 100644 docs/libcurl/curl_multi_add_handle.md delete mode 100644 docs/libcurl/curl_multi_assign.3 create mode 100644 docs/libcurl/curl_multi_assign.md delete mode 100644 docs/libcurl/curl_multi_cleanup.3 create mode 100644 docs/libcurl/curl_multi_cleanup.md delete mode 100644 docs/libcurl/curl_multi_fdset.3 create mode 100644 docs/libcurl/curl_multi_fdset.md delete mode 100644 docs/libcurl/curl_multi_get_handles.3 create mode 100644 docs/libcurl/curl_multi_get_handles.md rename docs/libcurl/{curl_multi_info_read.3 => curl_multi_info_read.md} (51%) delete mode 100644 docs/libcurl/curl_multi_init.3 create mode 100644 docs/libcurl/curl_multi_init.md delete mode 100644 docs/libcurl/curl_multi_perform.3 create mode 100644 docs/libcurl/curl_multi_perform.md rename docs/libcurl/{curl_multi_poll.3 => curl_multi_poll.md} (50%) delete mode 100644 docs/libcurl/curl_multi_remove_handle.3 create mode 100644 docs/libcurl/curl_multi_remove_handle.md delete mode 100644 docs/libcurl/curl_multi_setopt.3 create mode 100644 docs/libcurl/curl_multi_setopt.md delete mode 100644 docs/libcurl/curl_multi_socket.3 create mode 100644 docs/libcurl/curl_multi_socket.md delete mode 100644 docs/libcurl/curl_multi_socket_action.3 create mode 100644 docs/libcurl/curl_multi_socket_action.md delete mode 100644 docs/libcurl/curl_multi_socket_all.3 create mode 100644 docs/libcurl/curl_multi_socket_all.md delete mode 100644 docs/libcurl/curl_multi_strerror.3 create mode 100644 docs/libcurl/curl_multi_strerror.md delete mode 100644 docs/libcurl/curl_multi_timeout.3 create mode 100644 docs/libcurl/curl_multi_timeout.md delete mode 100644 docs/libcurl/curl_multi_wait.3 create mode 100644 docs/libcurl/curl_multi_wait.md delete mode 100644 docs/libcurl/curl_multi_wakeup.3 create mode 100644 docs/libcurl/curl_multi_wakeup.md rename docs/libcurl/{curl_pushheader_byname.3 => curl_pushheader_byname.md} (50%) delete mode 100644 docs/libcurl/curl_pushheader_bynum.3 create mode 100644 docs/libcurl/curl_pushheader_bynum.md delete mode 100644 docs/libcurl/curl_share_cleanup.3 create mode 100644 docs/libcurl/curl_share_cleanup.md delete mode 100644 docs/libcurl/curl_share_init.3 create mode 100644 docs/libcurl/curl_share_init.md delete mode 100644 docs/libcurl/curl_share_setopt.3 create mode 100644 docs/libcurl/curl_share_setopt.md delete mode 100644 docs/libcurl/curl_share_strerror.3 create mode 100644 docs/libcurl/curl_share_strerror.md delete mode 100644 docs/libcurl/curl_slist_append.3 create mode 100644 docs/libcurl/curl_slist_append.md delete mode 100644 docs/libcurl/curl_slist_free_all.3 create mode 100644 docs/libcurl/curl_slist_free_all.md delete mode 100644 docs/libcurl/curl_strequal.3 create mode 100644 docs/libcurl/curl_strequal.md delete mode 100644 docs/libcurl/curl_strnequal.3 create mode 100644 docs/libcurl/curl_strnequal.md delete mode 100644 docs/libcurl/curl_unescape.3 create mode 100644 docs/libcurl/curl_unescape.md delete mode 100644 docs/libcurl/curl_url.3 create mode 100644 docs/libcurl/curl_url.md delete mode 100644 docs/libcurl/curl_url_cleanup.3 create mode 100644 docs/libcurl/curl_url_cleanup.md delete mode 100644 docs/libcurl/curl_url_dup.3 create mode 100644 docs/libcurl/curl_url_dup.md rename docs/libcurl/{curl_url_get.3 => curl_url_get.md} (50%) rename docs/libcurl/{curl_url_set.3 => curl_url_set.md} (56%) delete mode 100644 docs/libcurl/curl_url_strerror.3 create mode 100644 docs/libcurl/curl_url_strerror.md delete mode 100644 docs/libcurl/curl_version.3 create mode 100644 docs/libcurl/curl_version.md rename docs/libcurl/{curl_version_info.3 => curl_version_info.md} (63%) rename docs/libcurl/{curl_ws_meta.3 => curl_ws_meta.md} (53%) delete mode 100644 docs/libcurl/curl_ws_recv.3 create mode 100644 docs/libcurl/curl_ws_recv.md delete mode 100644 docs/libcurl/curl_ws_send.3 create mode 100644 docs/libcurl/curl_ws_send.md delete mode 100644 docs/libcurl/libcurl-easy.3 create mode 100644 docs/libcurl/libcurl-easy.md delete mode 100644 docs/libcurl/libcurl-env-dbg.3 create mode 100644 docs/libcurl/libcurl-env-dbg.md delete mode 100644 docs/libcurl/libcurl-env.3 create mode 100644 docs/libcurl/libcurl-env.md rename docs/libcurl/{libcurl-errors.3 => libcurl-errors.md} (58%) rename docs/libcurl/{libcurl-multi.3 => libcurl-multi.md} (60%) rename docs/libcurl/{libcurl-security.3 => libcurl-security.md} (75%) delete mode 100644 docs/libcurl/libcurl-share.3 create mode 100644 docs/libcurl/libcurl-share.md delete mode 100644 docs/libcurl/libcurl-thread.3 create mode 100644 docs/libcurl/libcurl-thread.md rename docs/libcurl/{libcurl-tutorial.3 => libcurl-tutorial.md} (79%) rename docs/libcurl/{libcurl-url.3 => libcurl-url.md} (59%) rename docs/libcurl/{libcurl-ws.3 => libcurl-ws.md} (60%) rename docs/libcurl/{libcurl.3 => libcurl.md} (63%) delete mode 100644 docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 create mode 100644 docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md delete mode 100644 docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 create mode 100644 docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md delete mode 100644 docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_CAINFO.3 create mode 100644 docs/libcurl/opts/CURLINFO_CAINFO.md delete mode 100644 docs/libcurl/opts/CURLINFO_CAPATH.3 create mode 100644 docs/libcurl/opts/CURLINFO_CAPATH.md delete mode 100644 docs/libcurl/opts/CURLINFO_CERTINFO.3 create mode 100644 docs/libcurl/opts/CURLINFO_CERTINFO.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONNECT_TIME.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONN_ID.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONN_ID.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 create mode 100644 docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md delete mode 100644 docs/libcurl/opts/CURLINFO_COOKIELIST.3 create mode 100644 docs/libcurl/opts/CURLINFO_COOKIELIST.md delete mode 100644 docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 create mode 100644 docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md delete mode 100644 docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 create mode 100644 docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md delete mode 100644 docs/libcurl/opts/CURLINFO_FILETIME.3 create mode 100644 docs/libcurl/opts/CURLINFO_FILETIME.md delete mode 100644 docs/libcurl/opts/CURLINFO_FILETIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_FILETIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 create mode 100644 docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md delete mode 100644 docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 create mode 100644 docs/libcurl/opts/CURLINFO_HEADER_SIZE.md delete mode 100644 docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 create mode 100644 docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md delete mode 100644 docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 create mode 100644 docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md delete mode 100644 docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 create mode 100644 docs/libcurl/opts/CURLINFO_HTTP_VERSION.md delete mode 100644 docs/libcurl/opts/CURLINFO_LASTSOCKET.3 create mode 100644 docs/libcurl/opts/CURLINFO_LASTSOCKET.md delete mode 100644 docs/libcurl/opts/CURLINFO_LOCAL_IP.3 create mode 100644 docs/libcurl/opts/CURLINFO_LOCAL_IP.md delete mode 100644 docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 create mode 100644 docs/libcurl/opts/CURLINFO_LOCAL_PORT.md delete mode 100644 docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 create mode 100644 docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md delete mode 100644 docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 create mode 100644 docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md delete mode 100644 docs/libcurl/opts/CURLINFO_OS_ERRNO.3 create mode 100644 docs/libcurl/opts/CURLINFO_OS_ERRNO.md delete mode 100644 docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 create mode 100644 docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md delete mode 100644 docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 create mode 100644 docs/libcurl/opts/CURLINFO_PRIMARY_IP.md delete mode 100644 docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 create mode 100644 docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md delete mode 100644 docs/libcurl/opts/CURLINFO_PRIVATE.3 create mode 100644 docs/libcurl/opts/CURLINFO_PRIVATE.md delete mode 100644 docs/libcurl/opts/CURLINFO_PROTOCOL.3 create mode 100644 docs/libcurl/opts/CURLINFO_PROTOCOL.md delete mode 100644 docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 create mode 100644 docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md delete mode 100644 docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 create mode 100644 docs/libcurl/opts/CURLINFO_PROXY_ERROR.md delete mode 100644 docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 create mode 100644 docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md delete mode 100644 docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 create mode 100644 docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md delete mode 100644 docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 create mode 100644 docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md delete mode 100644 docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 create mode 100644 docs/libcurl/opts/CURLINFO_REDIRECT_URL.md delete mode 100644 docs/libcurl/opts/CURLINFO_REFERER.3 create mode 100644 docs/libcurl/opts/CURLINFO_REFERER.md delete mode 100644 docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 create mode 100644 docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md delete mode 100644 docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 create mode 100644 docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md delete mode 100644 docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 create mode 100644 docs/libcurl/opts/CURLINFO_RETRY_AFTER.md delete mode 100644 docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 create mode 100644 docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md delete mode 100644 docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 create mode 100644 docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md delete mode 100644 docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 create mode 100644 docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md delete mode 100644 docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 create mode 100644 docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md delete mode 100644 docs/libcurl/opts/CURLINFO_SCHEME.3 create mode 100644 docs/libcurl/opts/CURLINFO_SCHEME.md delete mode 100644 docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 create mode 100644 docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md delete mode 100644 docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 create mode 100644 docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md delete mode 100644 docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 create mode 100644 docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md delete mode 100644 docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 create mode 100644 docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md delete mode 100644 docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 create mode 100644 docs/libcurl/opts/CURLINFO_SSL_ENGINES.md delete mode 100644 docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 create mode 100644 docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md delete mode 100644 docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.3 create mode 100644 docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md delete mode 100644 docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_TLS_SESSION.3 create mode 100644 docs/libcurl/opts/CURLINFO_TLS_SESSION.md rename docs/libcurl/opts/{CURLINFO_TLS_SSL_PTR.3 => CURLINFO_TLS_SSL_PTR.md} (54%) delete mode 100644 docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 create mode 100644 docs/libcurl/opts/CURLINFO_TOTAL_TIME.md delete mode 100644 docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 create mode 100644 docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md delete mode 100644 docs/libcurl/opts/CURLINFO_XFER_ID.3 create mode 100644 docs/libcurl/opts/CURLINFO_XFER_ID.md delete mode 100644 docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 create mode 100644 docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md delete mode 100644 docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 create mode 100644 docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md delete mode 100644 docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 create mode 100644 docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md delete mode 100644 docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 create mode 100644 docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md delete mode 100644 docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 create mode 100644 docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md delete mode 100644 docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 create mode 100644 docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md delete mode 100644 docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 create mode 100644 docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md delete mode 100644 docs/libcurl/opts/CURLMOPT_PIPELINING.3 create mode 100644 docs/libcurl/opts/CURLMOPT_PIPELINING.md delete mode 100644 docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 create mode 100644 docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md delete mode 100644 docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 create mode 100644 docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md delete mode 100644 docs/libcurl/opts/CURLMOPT_PUSHDATA.3 create mode 100644 docs/libcurl/opts/CURLMOPT_PUSHDATA.md rename docs/libcurl/opts/{CURLMOPT_PUSHFUNCTION.3 => CURLMOPT_PUSHFUNCTION.md} (55%) delete mode 100644 docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 create mode 100644 docs/libcurl/opts/CURLMOPT_SOCKETDATA.md delete mode 100644 docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 create mode 100644 docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md delete mode 100644 docs/libcurl/opts/CURLMOPT_TIMERDATA.3 create mode 100644 docs/libcurl/opts/CURLMOPT_TIMERDATA.md delete mode 100644 docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 create mode 100644 docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 create mode 100644 docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md delete mode 100644 docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 create mode 100644 docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md rename docs/libcurl/opts/{CURLOPT_ACCEPT_ENCODING.3 => CURLOPT_ACCEPT_ENCODING.md} (52%) delete mode 100644 docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 create mode 100644 docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md delete mode 100644 docs/libcurl/opts/CURLOPT_ALTSVC.3 create mode 100644 docs/libcurl/opts/CURLOPT_ALTSVC.md delete mode 100644 docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 create mode 100644 docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md delete mode 100644 docs/libcurl/opts/CURLOPT_APPEND.3 create mode 100644 docs/libcurl/opts/CURLOPT_APPEND.md delete mode 100644 docs/libcurl/opts/CURLOPT_AUTOREFERER.3 create mode 100644 docs/libcurl/opts/CURLOPT_AUTOREFERER.md delete mode 100644 docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 create mode 100644 docs/libcurl/opts/CURLOPT_AWS_SIGV4.md delete mode 100644 docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 create mode 100644 docs/libcurl/opts/CURLOPT_BUFFERSIZE.md delete mode 100644 docs/libcurl/opts/CURLOPT_CAINFO.3 create mode 100644 docs/libcurl/opts/CURLOPT_CAINFO.md delete mode 100644 docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 create mode 100644 docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md delete mode 100644 docs/libcurl/opts/CURLOPT_CAPATH.3 create mode 100644 docs/libcurl/opts/CURLOPT_CAPATH.md delete mode 100644 docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 create mode 100644 docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md delete mode 100644 docs/libcurl/opts/CURLOPT_CERTINFO.3 create mode 100644 docs/libcurl/opts/CURLOPT_CERTINFO.md rename docs/libcurl/opts/{CURLOPT_CHUNK_BGN_FUNCTION.3 => CURLOPT_CHUNK_BGN_FUNCTION.md} (53%) delete mode 100644 docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_CHUNK_DATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 create mode 100644 docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md delete mode 100644 docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 create mode 100644 docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md delete mode 100644 docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 create mode 100644 docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md rename docs/libcurl/opts/{CURLOPT_CONNECT_TO.3 => CURLOPT_CONNECT_TO.md} (53%) delete mode 100644 docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md rename docs/libcurl/opts/{CURLOPT_COOKIE.3 => CURLOPT_COOKIE.md} (52%) rename docs/libcurl/opts/{CURLOPT_COOKIEFILE.3 => CURLOPT_COOKIEFILE.md} (57%) delete mode 100644 docs/libcurl/opts/CURLOPT_COOKIEJAR.3 create mode 100644 docs/libcurl/opts/CURLOPT_COOKIEJAR.md rename docs/libcurl/opts/{CURLOPT_COOKIELIST.3 => CURLOPT_COOKIELIST.md} (60%) delete mode 100644 docs/libcurl/opts/CURLOPT_COOKIESESSION.3 create mode 100644 docs/libcurl/opts/CURLOPT_COOKIESESSION.md delete mode 100644 docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 create mode 100644 docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md delete mode 100644 docs/libcurl/opts/CURLOPT_CRLF.3 create mode 100644 docs/libcurl/opts/CURLOPT_CRLF.md delete mode 100644 docs/libcurl/opts/CURLOPT_CRLFILE.3 create mode 100644 docs/libcurl/opts/CURLOPT_CRLFILE.md delete mode 100644 docs/libcurl/opts/CURLOPT_CURLU.3 create mode 100644 docs/libcurl/opts/CURLOPT_CURLU.md delete mode 100644 docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 create mode 100644 docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md delete mode 100644 docs/libcurl/opts/CURLOPT_DEBUGDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_DEBUGDATA.md rename docs/libcurl/opts/{CURLOPT_DEBUGFUNCTION.3 => CURLOPT_DEBUGFUNCTION.md} (58%) delete mode 100644 docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 create mode 100644 docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md delete mode 100644 docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 create mode 100644 docs/libcurl/opts/CURLOPT_DIRLISTONLY.md delete mode 100644 docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 create mode 100644 docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md rename docs/libcurl/opts/{CURLOPT_DNS_CACHE_TIMEOUT.3 => CURLOPT_DNS_CACHE_TIMEOUT.md} (51%) delete mode 100644 docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 create mode 100644 docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md delete mode 100644 docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 create mode 100644 docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md delete mode 100644 docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 create mode 100644 docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md delete mode 100644 docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 create mode 100644 docs/libcurl/opts/CURLOPT_DNS_SERVERS.md delete mode 100644 docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 create mode 100644 docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md delete mode 100644 docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 create mode 100644 docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md delete mode 100644 docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 create mode 100644 docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md delete mode 100644 docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 create mode 100644 docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md delete mode 100644 docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 create mode 100644 docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md delete mode 100644 docs/libcurl/opts/CURLOPT_DOH_URL.3 create mode 100644 docs/libcurl/opts/CURLOPT_DOH_URL.md delete mode 100644 docs/libcurl/opts/CURLOPT_EGDSOCKET.3 create mode 100644 docs/libcurl/opts/CURLOPT_EGDSOCKET.md delete mode 100644 docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 create mode 100644 docs/libcurl/opts/CURLOPT_ERRORBUFFER.md delete mode 100644 docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 create mode 100644 docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md delete mode 100644 docs/libcurl/opts/CURLOPT_FAILONERROR.3 create mode 100644 docs/libcurl/opts/CURLOPT_FAILONERROR.md delete mode 100644 docs/libcurl/opts/CURLOPT_FILETIME.3 create mode 100644 docs/libcurl/opts/CURLOPT_FILETIME.md delete mode 100644 docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 create mode 100644 docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md delete mode 100644 docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 create mode 100644 docs/libcurl/opts/CURLOPT_FORBID_REUSE.md delete mode 100644 docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 create mode 100644 docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md rename docs/libcurl/opts/{CURLOPT_FTPPORT.3 => CURLOPT_FTPPORT.md} (58%) delete mode 100644 docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md delete mode 100644 docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 create mode 100644 docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md delete mode 100644 docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 create mode 100644 docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md delete mode 100644 docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 create mode 100644 docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md delete mode 100644 docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 create mode 100644 docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md delete mode 100644 docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 create mode 100644 docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md delete mode 100644 docs/libcurl/opts/CURLOPT_HEADER.3 create mode 100644 docs/libcurl/opts/CURLOPT_HEADER.md delete mode 100644 docs/libcurl/opts/CURLOPT_HEADERDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_HEADERDATA.md rename docs/libcurl/opts/{CURLOPT_HEADERFUNCTION.3 => CURLOPT_HEADERFUNCTION.md} (62%) delete mode 100644 docs/libcurl/opts/CURLOPT_HEADEROPT.3 create mode 100644 docs/libcurl/opts/CURLOPT_HEADEROPT.md delete mode 100644 docs/libcurl/opts/CURLOPT_HSTS.3 create mode 100644 docs/libcurl/opts/CURLOPT_HSTS.md delete mode 100644 docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_HSTSREADDATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 create mode 100644 docs/libcurl/opts/CURLOPT_HSTS_CTRL.md delete mode 100644 docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 create mode 100644 docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md delete mode 100644 docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 create mode 100644 docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md rename docs/libcurl/opts/{CURLOPT_HTTPAUTH.3 => CURLOPT_HTTPAUTH.md} (51%) delete mode 100644 docs/libcurl/opts/CURLOPT_HTTPGET.3 create mode 100644 docs/libcurl/opts/CURLOPT_HTTPGET.md rename docs/libcurl/opts/{CURLOPT_HTTPHEADER.3 => CURLOPT_HTTPHEADER.md} (62%) delete mode 100644 docs/libcurl/opts/CURLOPT_HTTPPOST.3 create mode 100644 docs/libcurl/opts/CURLOPT_HTTPPOST.md delete mode 100644 docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 create mode 100644 docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md delete mode 100644 docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 create mode 100644 docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md delete mode 100644 docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 create mode 100644 docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md rename docs/libcurl/opts/{CURLOPT_HTTP_VERSION.3 => CURLOPT_HTTP_VERSION.md} (52%) delete mode 100644 docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 create mode 100644 docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md delete mode 100644 docs/libcurl/opts/CURLOPT_INFILESIZE.3 create mode 100644 docs/libcurl/opts/CURLOPT_INFILESIZE.md delete mode 100644 docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_INTERFACE.3 create mode 100644 docs/libcurl/opts/CURLOPT_INTERFACE.md delete mode 100644 docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md rename docs/libcurl/opts/{CURLOPT_INTERLEAVEFUNCTION.3 => CURLOPT_INTERLEAVEFUNCTION.md} (54%) delete mode 100644 docs/libcurl/opts/CURLOPT_IOCTLDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_IOCTLDATA.md rename docs/libcurl/opts/{CURLOPT_IOCTLFUNCTION.3 => CURLOPT_IOCTLFUNCTION.md} (50%) delete mode 100644 docs/libcurl/opts/CURLOPT_IPRESOLVE.3 create mode 100644 docs/libcurl/opts/CURLOPT_IPRESOLVE.md delete mode 100644 docs/libcurl/opts/CURLOPT_ISSUERCERT.3 create mode 100644 docs/libcurl/opts/CURLOPT_ISSUERCERT.md rename docs/libcurl/opts/{CURLOPT_ISSUERCERT_BLOB.3 => CURLOPT_ISSUERCERT_BLOB.md} (50%) delete mode 100644 docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 create mode 100644 docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md delete mode 100644 docs/libcurl/opts/CURLOPT_KEYPASSWD.3 create mode 100644 docs/libcurl/opts/CURLOPT_KEYPASSWD.md delete mode 100644 docs/libcurl/opts/CURLOPT_KRBLEVEL.3 create mode 100644 docs/libcurl/opts/CURLOPT_KRBLEVEL.md delete mode 100644 docs/libcurl/opts/CURLOPT_LOCALPORT.3 create mode 100644 docs/libcurl/opts/CURLOPT_LOCALPORT.md delete mode 100644 docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 create mode 100644 docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md delete mode 100644 docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 create mode 100644 docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md delete mode 100644 docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 create mode 100644 docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAIL_AUTH.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAIL_FROM.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAIL_FROM.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAIL_RCPT.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAXCONNECTS.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAXFILESIZE.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAXREDIRS.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAXREDIRS.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_MIMEPOST.3 create mode 100644 docs/libcurl/opts/CURLOPT_MIMEPOST.md delete mode 100644 docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3 create mode 100644 docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md delete mode 100644 docs/libcurl/opts/CURLOPT_NETRC.3 create mode 100644 docs/libcurl/opts/CURLOPT_NETRC.md delete mode 100644 docs/libcurl/opts/CURLOPT_NETRC_FILE.3 create mode 100644 docs/libcurl/opts/CURLOPT_NETRC_FILE.md delete mode 100644 docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 create mode 100644 docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md delete mode 100644 docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 create mode 100644 docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md delete mode 100644 docs/libcurl/opts/CURLOPT_NOBODY.3 create mode 100644 docs/libcurl/opts/CURLOPT_NOBODY.md delete mode 100644 docs/libcurl/opts/CURLOPT_NOPROGRESS.3 create mode 100644 docs/libcurl/opts/CURLOPT_NOPROGRESS.md delete mode 100644 docs/libcurl/opts/CURLOPT_NOPROXY.3 create mode 100644 docs/libcurl/opts/CURLOPT_NOPROXY.md delete mode 100644 docs/libcurl/opts/CURLOPT_NOSIGNAL.3 create mode 100644 docs/libcurl/opts/CURLOPT_NOSIGNAL.md rename docs/libcurl/opts/{CURLOPT_OPENSOCKETDATA.3 => CURLOPT_OPENSOCKETDATA.md} (50%) rename docs/libcurl/opts/{CURLOPT_OPENSOCKETFUNCTION.3 => CURLOPT_OPENSOCKETFUNCTION.md} (53%) delete mode 100644 docs/libcurl/opts/CURLOPT_PASSWORD.3 create mode 100644 docs/libcurl/opts/CURLOPT_PASSWORD.md delete mode 100644 docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 create mode 100644 docs/libcurl/opts/CURLOPT_PATH_AS_IS.md rename docs/libcurl/opts/{CURLOPT_PINNEDPUBLICKEY.3 => CURLOPT_PINNEDPUBLICKEY.md} (52%) delete mode 100644 docs/libcurl/opts/CURLOPT_PIPEWAIT.3 create mode 100644 docs/libcurl/opts/CURLOPT_PIPEWAIT.md delete mode 100644 docs/libcurl/opts/CURLOPT_PORT.3 create mode 100644 docs/libcurl/opts/CURLOPT_PORT.md delete mode 100644 docs/libcurl/opts/CURLOPT_POST.3 create mode 100644 docs/libcurl/opts/CURLOPT_POST.md delete mode 100644 docs/libcurl/opts/CURLOPT_POSTFIELDS.3 create mode 100644 docs/libcurl/opts/CURLOPT_POSTFIELDS.md delete mode 100644 docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 create mode 100644 docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md delete mode 100644 docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_POSTQUOTE.3 create mode 100644 docs/libcurl/opts/CURLOPT_POSTQUOTE.md delete mode 100644 docs/libcurl/opts/CURLOPT_POSTREDIR.3 create mode 100644 docs/libcurl/opts/CURLOPT_POSTREDIR.md delete mode 100644 docs/libcurl/opts/CURLOPT_PREQUOTE.3 create mode 100644 docs/libcurl/opts/CURLOPT_PREQUOTE.md delete mode 100644 docs/libcurl/opts/CURLOPT_PREREQDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_PREREQDATA.md rename docs/libcurl/opts/{CURLOPT_PREREQFUNCTION.3 => CURLOPT_PREREQFUNCTION.md} (56%) rename docs/libcurl/opts/{CURLOPT_PRE_PROXY.3 => CURLOPT_PRE_PROXY.md} (50%) delete mode 100644 docs/libcurl/opts/CURLOPT_PRIVATE.3 create mode 100644 docs/libcurl/opts/CURLOPT_PRIVATE.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROGRESSDATA.md rename docs/libcurl/opts/{CURLOPT_PROGRESSFUNCTION.3 => CURLOPT_PROGRESSFUNCTION.md} (53%) delete mode 100644 docs/libcurl/opts/CURLOPT_PROTOCOLS.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROTOCOLS.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXYAUTH.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXYAUTH.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXYHEADER.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXYHEADER.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXYPORT.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXYPORT.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXYTYPE.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXYTYPE.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md rename docs/libcurl/opts/{CURLOPT_PROXY_ISSUERCERT_BLOB.3 => CURLOPT_PROXY_ISSUERCERT_BLOB.md} (50%) delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md rename docs/libcurl/opts/{CURLOPT_PROXY_PINNEDPUBLICKEY.3 => CURLOPT_PROXY_PINNEDPUBLICKEY.md} (54%) delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md rename docs/libcurl/opts/{CURLOPT_PROXY_SSLKEY_BLOB.3 => CURLOPT_PROXY_SSLKEY_BLOB.md} (52%) delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md rename docs/libcurl/opts/{CURLOPT_PROXY_SSL_OPTIONS.3 => CURLOPT_PROXY_SSL_OPTIONS.md} (60%) delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md delete mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 create mode 100644 docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md delete mode 100644 docs/libcurl/opts/CURLOPT_PUT.3 create mode 100644 docs/libcurl/opts/CURLOPT_PUT.md delete mode 100644 docs/libcurl/opts/CURLOPT_QUICK_EXIT.3 create mode 100644 docs/libcurl/opts/CURLOPT_QUICK_EXIT.md rename docs/libcurl/opts/{CURLOPT_QUOTE.3 => CURLOPT_QUOTE.md} (56%) delete mode 100644 docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 create mode 100644 docs/libcurl/opts/CURLOPT_RANDOM_FILE.md delete mode 100644 docs/libcurl/opts/CURLOPT_RANGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_RANGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_READDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_READDATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_READFUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_READFUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 create mode 100644 docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md rename docs/libcurl/opts/{CURLOPT_REDIR_PROTOCOLS_STR.3 => CURLOPT_REDIR_PROTOCOLS_STR.md} (51%) delete mode 100644 docs/libcurl/opts/CURLOPT_REFERER.3 create mode 100644 docs/libcurl/opts/CURLOPT_REFERER.md delete mode 100644 docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 create mode 100644 docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md rename docs/libcurl/opts/{CURLOPT_RESOLVE.3 => CURLOPT_RESOLVE.md} (59%) delete mode 100644 docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_RESUME_FROM.3 create mode 100644 docs/libcurl/opts/CURLOPT_RESUME_FROM.md delete mode 100644 docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 create mode 100644 docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md delete mode 100644 docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 create mode 100644 docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md delete mode 100644 docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 create mode 100644 docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md delete mode 100644 docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 create mode 100644 docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md delete mode 100644 docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 create mode 100644 docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md delete mode 100644 docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 create mode 100644 docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md delete mode 100644 docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 create mode 100644 docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md delete mode 100644 docs/libcurl/opts/CURLOPT_SASL_IR.3 create mode 100644 docs/libcurl/opts/CURLOPT_SASL_IR.md delete mode 100644 docs/libcurl/opts/CURLOPT_SEEKDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_SEEKDATA.md rename docs/libcurl/opts/{CURLOPT_SEEKFUNCTION.3 => CURLOPT_SEEKFUNCTION.md} (51%) delete mode 100644 docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 create mode 100644 docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md delete mode 100644 docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 create mode 100644 docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md delete mode 100644 docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 create mode 100644 docs/libcurl/opts/CURLOPT_SERVICE_NAME.md delete mode 100644 docs/libcurl/opts/CURLOPT_SHARE.3 create mode 100644 docs/libcurl/opts/CURLOPT_SHARE.md delete mode 100644 docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md rename docs/libcurl/opts/{CURLOPT_SOCKOPTFUNCTION.3 => CURLOPT_SOCKOPTFUNCTION.md} (54%) delete mode 100644 docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 create mode 100644 docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md delete mode 100644 docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 create mode 100644 docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md delete mode 100644 docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 create mode 100644 docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md rename docs/libcurl/opts/{CURLOPT_SSH_KEYFUNCTION.3 => CURLOPT_SSH_KEYFUNCTION.md} (64%) delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSLCERT.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSLCERT.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSLENGINE.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSLENGINE.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSLKEY.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSLKEY.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md rename docs/libcurl/opts/{CURLOPT_SSLKEY_BLOB.3 => CURLOPT_SSLKEY_BLOB.md} (50%) rename docs/libcurl/opts/{CURLOPT_SSLVERSION.3 => CURLOPT_SSLVERSION.md} (51%) delete mode 100644 docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md rename docs/libcurl/opts/{CURLOPT_SSL_CTX_DATA.3 => CURLOPT_SSL_CTX_DATA.md} (52%) rename docs/libcurl/opts/{CURLOPT_SSL_CTX_FUNCTION.3 => CURLOPT_SSL_CTX_FUNCTION.md} (58%) delete mode 100644 docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md delete mode 100644 docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md rename docs/libcurl/opts/{CURLOPT_SSL_OPTIONS.3 => CURLOPT_SSL_OPTIONS.md} (60%) delete mode 100644 docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md rename docs/libcurl/opts/{CURLOPT_SSL_VERIFYHOST.3 => CURLOPT_SSL_VERIFYHOST.md} (53%) rename docs/libcurl/opts/{CURLOPT_SSL_VERIFYPEER.3 => CURLOPT_SSL_VERIFYPEER.md} (53%) delete mode 100644 docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 create mode 100644 docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md delete mode 100644 docs/libcurl/opts/CURLOPT_STDERR.3 create mode 100644 docs/libcurl/opts/CURLOPT_STDERR.md delete mode 100644 docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 create mode 100644 docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md delete mode 100644 docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 create mode 100644 docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md delete mode 100644 docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 create mode 100644 docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md delete mode 100644 docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 create mode 100644 docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md delete mode 100644 docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 create mode 100644 docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md delete mode 100644 docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 create mode 100644 docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md delete mode 100644 docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 create mode 100644 docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md delete mode 100644 docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 create mode 100644 docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md delete mode 100644 docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 create mode 100644 docs/libcurl/opts/CURLOPT_TCP_NODELAY.md delete mode 100644 docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 create mode 100644 docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md delete mode 100644 docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 create mode 100644 docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md delete mode 100644 docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 create mode 100644 docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md delete mode 100644 docs/libcurl/opts/CURLOPT_TIMECONDITION.3 create mode 100644 docs/libcurl/opts/CURLOPT_TIMECONDITION.md delete mode 100644 docs/libcurl/opts/CURLOPT_TIMEOUT.3 create mode 100644 docs/libcurl/opts/CURLOPT_TIMEOUT.md delete mode 100644 docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 create mode 100644 docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md delete mode 100644 docs/libcurl/opts/CURLOPT_TIMEVALUE.3 create mode 100644 docs/libcurl/opts/CURLOPT_TIMEVALUE.md delete mode 100644 docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 create mode 100644 docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md delete mode 100644 docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 create mode 100644 docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md delete mode 100644 docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 create mode 100644 docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md delete mode 100644 docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 create mode 100644 docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md delete mode 100644 docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 create mode 100644 docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md delete mode 100644 docs/libcurl/opts/CURLOPT_TRAILERDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_TRAILERDATA.md delete mode 100644 docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 create mode 100644 docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md delete mode 100644 docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 create mode 100644 docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md delete mode 100644 docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 create mode 100644 docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md delete mode 100644 docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 create mode 100644 docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md delete mode 100644 docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 create mode 100644 docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md delete mode 100644 docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 create mode 100644 docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md delete mode 100644 docs/libcurl/opts/CURLOPT_UPLOAD.3 create mode 100644 docs/libcurl/opts/CURLOPT_UPLOAD.md delete mode 100644 docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 create mode 100644 docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md rename docs/libcurl/opts/{CURLOPT_URL.3 => CURLOPT_URL.md} (50%) delete mode 100644 docs/libcurl/opts/CURLOPT_USERAGENT.3 create mode 100644 docs/libcurl/opts/CURLOPT_USERAGENT.md delete mode 100644 docs/libcurl/opts/CURLOPT_USERNAME.3 create mode 100644 docs/libcurl/opts/CURLOPT_USERNAME.md delete mode 100644 docs/libcurl/opts/CURLOPT_USERPWD.3 create mode 100644 docs/libcurl/opts/CURLOPT_USERPWD.md delete mode 100644 docs/libcurl/opts/CURLOPT_USE_SSL.3 create mode 100644 docs/libcurl/opts/CURLOPT_USE_SSL.md delete mode 100644 docs/libcurl/opts/CURLOPT_VERBOSE.3 create mode 100644 docs/libcurl/opts/CURLOPT_VERBOSE.md delete mode 100644 docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 create mode 100644 docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md delete mode 100644 docs/libcurl/opts/CURLOPT_WRITEDATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_WRITEDATA.md rename docs/libcurl/opts/{CURLOPT_WRITEFUNCTION.3 => CURLOPT_WRITEFUNCTION.md} (51%) delete mode 100644 docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 create mode 100644 docs/libcurl/opts/CURLOPT_WS_OPTIONS.md delete mode 100644 docs/libcurl/opts/CURLOPT_XFERINFODATA.3 create mode 100644 docs/libcurl/opts/CURLOPT_XFERINFODATA.md rename docs/libcurl/opts/{CURLOPT_XFERINFOFUNCTION.3 => CURLOPT_XFERINFOFUNCTION.md} (52%) delete mode 100644 docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 create mode 100644 docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md delete mode 100644 docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 create mode 100644 docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md rename docs/libcurl/opts/{CURLSHOPT_SHARE.3 => CURLSHOPT_SHARE.md} (52%) delete mode 100644 docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 create mode 100644 docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md delete mode 100644 docs/libcurl/opts/CURLSHOPT_UNSHARE.3 create mode 100644 docs/libcurl/opts/CURLSHOPT_UNSHARE.md delete mode 100644 docs/libcurl/opts/CURLSHOPT_USERDATA.3 create mode 100644 docs/libcurl/opts/CURLSHOPT_USERDATA.md delete mode 100644 docs/libcurl/opts/template.3 delete mode 100644 docs/mk-ca-bundle.1 create mode 100644 docs/mk-ca-bundle.md create mode 100755 scripts/cd2cd create mode 100755 scripts/cd2nroff create mode 100755 scripts/cdall create mode 100755 scripts/nroff2cd delete mode 100755 scripts/updatemanpages.pl diff --git a/.github/scripts/cleanspell.pl b/.github/scripts/cleanspell.pl index 329a9724038..06648a3f99f 100755 --- a/.github/scripts/cleanspell.pl +++ b/.github/scripts/cleanspell.pl @@ -71,6 +71,7 @@ $_ =~ s/curl_url_(dup)//g; $_ =~ s/curl_pushheader_by(name|num)//g; $_ =~ s/libcurl-(env|ws)//g; + $_ =~ s/libcurl\\-(env|ws)//g; $_ =~ s/(^|\W)((tftp|https|http|ftp):\/\/[a-z0-9\-._~%:\/?\#\[\]\@!\$&'()*+,;=]+)//gi; print O $_; } diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index 4bee9bf6001..182a3bdb46c 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -83,6 +83,7 @@ CCC CDN CentOS CFLAGS +cflags CGI's CHACHA chacha @@ -138,10 +139,11 @@ cshrc CTRL cURL CURLcode +curldown CURLE CURLH -CURLINFO curlimages +CURLINFO curlrc curltest customizable @@ -161,8 +163,8 @@ deepcode DELE DER deselectable -Deserialized deserialization +Deserialized destructor detections dev @@ -350,11 +352,10 @@ interoperable interoperates IoT ipadOS +IPCXN IPFS -IPNS ipld -trustless -IPCXN +IPNS IPv IPv4 IPv4/6 @@ -804,6 +805,7 @@ TPF TrackMemory transcode Tru +trustless Tse Tsujikawa TTL @@ -826,6 +828,7 @@ unencoded unencrypted unescape Unglobbed +Unicode UNICOS unix UnixSockets diff --git a/.github/scripts/verify-examples.pl b/.github/scripts/verify-examples.pl index 377fe8340c4..28d24595fff 100755 --- a/.github/scripts/verify-examples.pl +++ b/.github/scripts/verify-examples.pl @@ -91,12 +91,20 @@ sub extract { return ($fail ? 0 : $l); } +my $count; for my $m (@files) { - print "Verify $m\n"; + #print "Verify $m\n"; my $out = extract($m); if($out) { $error |= testcompile($m); $error |= checksrc($m); } + $count++; +} +if(!$error) { + print "Verified $count man pages ok\n"; +} +else { + print "Detected problems\n"; } exit $error; diff --git a/.github/workflows/man-examples.yml b/.github/workflows/man-examples.yml index 249ebfe2f9d..6f0d1e8ae42 100644 --- a/.github/workflows/man-examples.yml +++ b/.github/workflows/man-examples.yml @@ -28,5 +28,8 @@ jobs: - name: Checkout 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/proselint.yml b/.github/workflows/proselint.yml index aead0b5b068..87126672224 100644 --- a/.github/workflows/proselint.yml +++ b/.github/workflows/proselint.yml @@ -42,7 +42,8 @@ jobs: "checks": { "typography.diacritical_marks": false, "typography.symbols": false, - "annotations.misc": false + "annotations.misc": false, + "security.password": false } } JSON diff --git a/Makefile.am b/Makefile.am index d0b1fef59af..b56ca1a1eb2 100644 --- a/Makefile.am +++ b/Makefile.am @@ -153,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 diff --git a/appveyor.yml b/appveyor.yml index 534109e56c1..039e040a15d 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -84,7 +84,7 @@ environment: ENABLE_UNICODE: 'OFF' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1139 !1501' + 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 @@ -95,7 +95,7 @@ environment: ENABLE_UNICODE: 'ON' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1139 !1501' + 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 @@ -106,7 +106,7 @@ environment: ENABLE_UNICODE: 'OFF' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1139 !1501' + 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 @@ -117,7 +117,7 @@ environment: ENABLE_UNICODE: 'OFF' HTTP_ONLY: 'ON' TESTING: 'ON' - DISABLED_TESTS: '!1139 !1501' + 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' @@ -128,7 +128,7 @@ environment: ENABLE_UNICODE: 'ON' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1086 !1139 !1451 !1501' + DISABLED_TESTS: '!1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477' ADD_PATH: 'C:/msys64/mingw64/bin' MSYS2_ARG_CONV_EXCL: '/*' BUILD_OPT: -k @@ -142,7 +142,7 @@ environment: ENABLE_UNICODE: 'ON' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1086 !1139 !1451 !1501' + 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 @@ -156,7 +156,7 @@ 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' + DISABLED_TESTS: '~286 !1086 !1139 !1451 !1501 !1140 !1173 !1177 !1477' ADD_PATH: 'C:/msys64/mingw64/bin' MSYS2_ARG_CONV_EXCL: '/*' BUILD_OPT: -k @@ -170,7 +170,7 @@ environment: ENABLE_UNICODE: 'OFF' HTTP_ONLY: 'OFF' TESTING: 'ON' - DISABLED_TESTS: '!1086 !1139 !1451 !1501' + 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 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/CONTRIBUTE.md b/docs/CONTRIBUTE.md index 72d31900195..11c9473b497 100644 --- a/docs/CONTRIBUTE.md +++ b/docs/CONTRIBUTE.md @@ -116,7 +116,7 @@ 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! +posts a few test cases, it will not end up as 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 diff --git a/docs/CURLDOWN.md b/docs/CURLDOWN.md new file mode 100644 index 00000000000..4a37fc2f6a2 --- /dev/null +++ b/docs/CURLDOWN.md @@ -0,0 +1,125 @@ +# 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 + See-also: + - CURLOPT_HEADEROPT (3) + - CURLOPT_HTTPAUTH (3) + --- + +All curldown files *must* have all the headers present and at least one +`See-also:` entry specified. + +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 don't support backticks especially formatted, such +occurrences in the source will instead just use italics in the generated +output: + + This `word` appears in italics. + +When generating the nroff output, the tooling will remove superfluous newlines, +meaning they can be used freely in the source file to make the text more +readable. + +All mentioned curl symbols that have their own man pages, like +`curl_easy_perform(3)` will automatically be 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/GOVERNANCE.md b/docs/GOVERNANCE.md index dd09de45636..0f7029e8276 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -179,4 +179,4 @@ 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/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/Makefile.am b/docs/Makefile.am index e53cf305af2..b3f2b07c8a2 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -26,24 +26,21 @@ 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 +man_MANS = $(abs_builddir)/curl.1 mk-ca-bundle.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 - -HTMLPAGES = $(GENHTMLPAGES) +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 +CLEANFILES = $(man_MANS) curl.1 curl-config.1 mk-ca-bundle.1 +nodist_MANS = $(CLEANFILES) EXTRA_DIST = \ - $(noinst_man_MANS) \ + $(CURLPAGES) \ ALTSVC.md \ BINDINGS.md \ BUFREF.md \ @@ -59,6 +56,7 @@ EXTRA_DIST = \ CONNECTION-FILTERS.md \ CONTRIBUTE.md \ CURL-DISABLE.md \ + CURLDOWN.md \ DEPRECATE.md \ DYNBUF.md \ EARLY-RELEASE.md \ @@ -98,9 +96,14 @@ EXTRA_DIST = \ VULN-DISCLOSURE-POLICY.md \ WEBSOCKET.md -MAN2HTML= roffit $< >$@ +CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@ + +CD2 = $(CD2_$(V)) +CD2_0 = @echo " RENDER " $@; +CD2_1 = +CD2_ = $(CD2_0) -SUFFIXES = .1 .html .pdf +SUFFIXES = .1 .md # $(abs_builddir) is to disable VPATH when searching for this file, which # would otherwise find the copy in $(srcdir) which breaks the $(HUGE) @@ -116,21 +119,10 @@ $(abs_builddir)/curl.1: && touch -r "$(srcdir)/curl.1" $@; fi cd cmdline-opts && $(MAKE) -html: $(HTMLPAGES) - cd libcurl && $(MAKE) html - -pdf: $(PDFPAGES) - cd libcurl && $(MAKE) pdf - -.1.html: - $(MAN2HTML) +.md.1: + $(CD2)$(CD2NROFF) -.1.pdf: - @(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \ - groff -Tps -man $< >$$foo.ps; \ - ps2pdf $$foo.ps $@; \ - rm $$foo.ps; \ - echo "converted $< to $@") +curl-config.1: curl-config.md distclean: rm -f $(CLEANFILES) diff --git a/docs/SSLCERTS.md b/docs/SSLCERTS.md index d10ce52916a..7087e1eaf14 100644 --- a/docs/SSLCERTS.md +++ b/docs/SSLCERTS.md @@ -116,10 +116,10 @@ server, do one of the following: 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 diff --git a/docs/curl-config.1 b/docs/curl-config.md similarity index 61% rename from docs/curl-config.1 rename to docs/curl-config.md index 65cd2c97123..5fe46879eea 100644 --- a/docs/curl-config.1 +++ b/docs/curl-config.md @@ -1,105 +1,124 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH curl-config 1 "25 Oct 2007" curl-config curl-config -.SH NAME -curl-config \- Get information about a libcurl installation -.SH SYNOPSIS -.B curl-config [options] -.SH DESCRIPTION -.B curl-config +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl-config +Section: 1 +Source: curl-config +See-also: + - curl (1) +--- + +# NAME + +curl-config - Get information about a libcurl installation + +# SYNOPSIS + +**curl-config [options]** + +# DESCRIPTION + +**curl-config** displays information about the curl and libcurl installation. -.SH OPTIONS -.IP "--ca" + +# OPTIONS + +## --ca + Displays the built-in path to the CA cert bundle this libcurl uses. -.IP "--cc" + +## --cc + Displays the compiler used to build libcurl. -.IP "--cflags" + +## --cflags + Set of compiler options (CFLAGS) to use when compiling files that use libcurl. Currently that is only the include path to the curl include files. -.IP "--checkfor [version]" + +## --checkfor [version] + Specify the oldest possible libcurl version string you want, and this script will return 0 if the current installation is new enough or it returns 1 and outputs a text saying that the current version is not new enough. (Added in 7.15.4) -.IP "--configure" + +## --configure + Displays the arguments given to configure when building curl. -.IP "--feature" + +## --feature + Lists what particular main features the installed libcurl was built with. At the time of writing, this list may include SSL, KRB4 or IPv6. Do not assume any particular order. The keywords will be separated by newlines. There may be none, one, or several keywords in the list. -.IP "--help" + +## --help + Displays the available options. -.IP "--libs" + +## --libs + Shows the complete set of libs and other linker options you will need in order to link your application with libcurl. -.IP "--prefix" + +## --prefix + This is the prefix used when libcurl was installed. Libcurl is then installed in $prefix/lib and its header files are installed in $prefix/include and so on. The prefix is set with "configure --prefix". -.IP "--protocols" + +## --protocols + Lists what particular protocols the installed libcurl was built to support. At the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE, TELNET, LDAP, DICT and many more. Do not assume any particular order. The protocols will be listed using uppercase and are separated by newlines. There may be none, one, or several protocols in the list. (Added in 7.13.0) -.IP "--ssl-backends" + +## --ssl-backends + Lists the SSL backends that were enabled when libcurl was built. It might be no, one or several names. If more than one name, they will appear comma-separated. (Added in 7.58.0) -.IP "--static-libs" + +## --static-libs + Shows the complete set of libs and other linker options you will need in order to link your application with libcurl statically. (Added in 7.17.1) -.IP "--version" + +## --version + Outputs version information about the installed libcurl. -.IP "--vernum" + +## --vernum + Outputs version information about the installed libcurl, in numerical mode. This outputs the version number, in hexadecimal, with 8 bits for each part: major, minor, and patch. So that libcurl 7.7.4 would appear as 070704 and libcurl 12.13.14 would appear as 0c0d0e... Note that the initial zero might be omitted. (This option was broken in the 7.15.0 release.) -.SH "EXAMPLES" + +# EXAMPLES + What linker options do I need when I link with libcurl? -.nf +~~~ $ curl-config --libs -.fi +~~~ What compiler options do I need when I compile using libcurl functions? -.nf +~~~ $ curl-config --cflags -.fi +~~~ How do I know if libcurl was built with SSL support? -.nf +~~~ $ curl-config --feature | grep SSL -.fi +~~~ What's the installed libcurl version? -.nf +~~~ $ curl-config --version -.fi +~~~ How do I build a single file with a one-line command? -.nf - $ `curl-config --cc --cflags` -o example example.c `curl-config --libs` -.fi -.SH "SEE ALSO" -.BR curl (1) +~~~ + $ `curl-config --cc --cflags` -o example source.c `curl-config --libs` +~~~ diff --git a/docs/libcurl/.gitignore b/docs/libcurl/.gitignore deleted file mode 100644 index fd35ad0fcef..00000000000 --- a/docs/libcurl/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Copyright (C) Daniel Stenberg, , et al. -# -# SPDX-License-Identifier: curl - -*.html -*.pdf -*.3.dist -libcurl-symbols.3 diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 8d512a6c260..17b2bc80d04 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -28,53 +28,27 @@ SUBDIRS = opts include Makefile.inc -man_DISTMANS = $(man_MANS:.3=.3.dist) - -HTMLPAGES = $(man_MANS:.3=.html) - -PDFPAGES = $(man_MANS:.3=.pdf) +CURLPAGES = $(man_MANS:.3=.md) m4macrodir = $(datadir)/aclocal dist_m4macro_DATA = libcurl.m4 -CLEANFILES = $(HTMLPAGES) $(PDFPAGES) $(TESTS) $(man_DISTMANS) \ - libcurl-symbols.3 +CLEANFILES = $(man_MANS) libcurl-symbols.md +nodist_MANS = $(man_MANS) -EXTRA_DIST = $(man_MANS) ABI.md symbols-in-versions symbols.pl \ +EXTRA_DIST = $(CURLPAGES) ABI.md symbols-in-versions symbols.pl \ mksymbolsmanpage.pl CMakeLists.txt -MAN2HTML= roffit --mandir=. $< >$@ - -SUFFIXES = .3 .html - -libcurl-symbols.3: $(srcdir)/symbols-in-versions $(srcdir)/mksymbolsmanpage.pl - perl $(srcdir)/mksymbolsmanpage.pl < $(srcdir)/symbols-in-versions > $@ - -html: $(HTMLPAGES) - cd opts && $(MAKE) html - -.3.html: - $(MAN2HTML) - -pdf: $(PDFPAGES) - cd opts && $(MAKE) pdf -.3.pdf: - @(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \ - groff -Tps -man $< >$$foo.ps; \ - ps2pdf $$foo.ps $@; \ - rm $$foo.ps; \ - echo "converted $< to $@") +CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@ +CD2 = $(CD2_$(V)) +CD2_0 = @echo " RENDER " $@; +CD2_1 = +CD2_ = $(CD2_0) -# Make sure each option man page is referenced in the main man page -TESTS = check-easy check-multi -LOG_COMPILER = $(PERL) -# The test fails if the log file contains any text -AM_LOG_FLAGS = -p -e 'die "$$_" if ($$_);' +SUFFIXES = .3 .md -check-easy: $(srcdir)/curl_easy_setopt.3 $(srcdir)/opts/CURLOPT*.3 - OPTS="$$(ls $(srcdir)/opts/CURLOPT*.3 | $(SED) -e 's,^.*/,,' -e 's,\.3$$,,')" && \ - for opt in $$OPTS; do grep "^\.IP $$opt$$" $(srcdir)/curl_easy_setopt.3 >/dev/null || echo Missing $$opt; done > $@ +libcurl-symbols.md: $(srcdir)/symbols-in-versions $(srcdir)/mksymbolsmanpage.pl + $(CD2)perl $(srcdir)/mksymbolsmanpage.pl < $(srcdir)/symbols-in-versions > $@ -check-multi: $(srcdir)/curl_multi_setopt.3 $(srcdir)/opts/CURLMOPT*.3 - OPTS="$$(ls $(srcdir)/opts/CURLMOPT*.3 | $(SED) -e 's,^.*/,,' -e 's,\.3$$,,')" && \ - for opt in $$OPTS; do grep "^\.IP $$opt$$" $(srcdir)/curl_multi_setopt.3 >/dev/null || echo Missing $$opt; done > $@ +.md.3: + $(CD2)$(CD2NROFF) diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 deleted file mode 100644 index 9d54d2e2554..00000000000 --- a/docs/libcurl/curl_easy_cleanup.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_easy_cleanup 3 "22 Aug 2007" "libcurl" "libcurl" -.SH NAME -curl_easy_cleanup - End a libcurl easy handle -.SH SYNOPSIS -.nf -#include - -void curl_easy_cleanup(CURL *handle); -.fi -.SH DESCRIPTION -This function is the opposite of \fIcurl_easy_init(3)\fP. It closes down and -frees all resources previously associated with this easy handle. - -This call closes all connections this handle has used and possibly has kept -open until now unless the easy handle was attached to a multi handle while -doing the transfers. Do not call this function if you intend to transfer more -files, reusing handles is a key to good performance with libcurl. - -Occasionally you may get your progress callback or header callback called from -within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using -\fIcurl_easy_setopt(3)\fP). Like if libcurl decides to shut down the -connection and the protocol is of a kind that requires a command/response -sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP. - -Any use of the easy \fBhandle\fP after this function has been called and have -returned, is illegal. - -To close an easy handle that has been used with the multi interface, make sure -to first call \fIcurl_multi_remove_handle(3)\fP to remove it from the multi -handle before it is closed. - -Passing in a NULL pointer in \fIhandle\fP makes this function return -immediately with no action. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res) - printf("error: %s\\n", curl_easy_strerror(res)); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.1 -.SH RETURN VALUE -None -.SH "SEE ALSO" -.BR curl_easy_duphandle (3), -.BR curl_easy_init (3), -.BR curl_easy_reset (3), -.BR curl_multi_cleanup (3), -.BR curl_multi_remove_handle (3) diff --git a/docs/libcurl/curl_easy_cleanup.md b/docs/libcurl/curl_easy_cleanup.md new file mode 100644 index 00000000000..bdbc058947f --- /dev/null +++ b/docs/libcurl/curl_easy_cleanup.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_cleanup +Section: 3 +Source: libcurl +See-also: + - curl_easy_duphandle (3) + - curl_easy_init (3) + - curl_easy_reset (3) + - curl_multi_cleanup (3) + - curl_multi_remove_handle (3) +--- + +# NAME + +curl_easy_cleanup - End a libcurl easy handle + +# SYNOPSIS + +~~~c +#include + +void curl_easy_cleanup(CURL *handle); +~~~ + +# DESCRIPTION + +This function is the opposite of curl_easy_init(3). It closes down and frees +all resources previously associated with this easy handle. + +This call closes all connections this handle has used and possibly has kept +open until now unless the easy handle was attached to a multi handle while +doing the transfers. Do not call this function if you intend to transfer more +files, reusing handles is a key to good performance with libcurl. + +Occasionally you may get your progress callback or header callback called from +within curl_easy_cleanup(3) (if previously set for the handle using +curl_easy_setopt(3)). Like if libcurl decides to shut down the connection and +the protocol is of a kind that requires a command/response sequence before +disconnect. Examples of such protocols are FTP, POP3 and IMAP. + +Any use of the easy **handle** after this function has been called and have +returned, is illegal. + +To close an easy handle that has been used with the multi interface, make sure +to first call curl_multi_remove_handle(3) to remove it from the multi handle +before it is closed. + +Passing in a NULL pointer in *handle* makes this function return immediately +with no action. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res) + printf("error: %s\n", curl_easy_strerror(res)); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.1 + +# RETURN VALUE + +None diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 deleted file mode 100644 index 5459386545a..00000000000 --- a/docs/libcurl/curl_easy_duphandle.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_duphandle 3 "19 Sep 2014" "libcurl" "libcurl" -.SH NAME -curl_easy_duphandle - Clone a libcurl session handle -.SH SYNOPSIS -.nf -#include - -CURL *curl_easy_duphandle(CURL *handle); -.fi -.SH DESCRIPTION -This function returns a new curl handle, a duplicate, using all the options -previously set in the input curl \fIhandle\fP. Both handles can subsequently -be used independently and they must both be freed with -\fIcurl_easy_cleanup(3)\fP. - -Any options that the input handle has been told to point to (as opposed to -copy) with previous calls to \fIcurl_easy_setopt(3)\fP, are pointed to by the -new handle as well. You must therefore make sure to keep the data around until -both handles have been cleaned up. - -The new handle does \fBnot\fP inherit any state information, no connections, -no SSL sessions and no cookies. It also does not inherit any share object -states or options (created as if \fICURLOPT_SHARE(3)\fP was set to NULL). - -If the source handle has HSTS or alt-svc enabled, the duplicate gets data read -data from the main file name to populate the cache. - -In multi-threaded programs, this function must be called in a synchronous way, -the input handle may not be in use when cloned. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - CURL *nother; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - nother = curl_easy_duphandle(curl); - res = curl_easy_perform(nother); - curl_easy_cleanup(nother); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.9 -.SH RETURN VALUE -If this function returns NULL, something went wrong and no valid handle was -returned. -.SH SEE ALSO -.BR curl_easy_cleanup (3), -.BR curl_easy_init (3), -.BR curl_easy_reset (3), -.BR curl_global_init (3) diff --git a/docs/libcurl/curl_easy_duphandle.md b/docs/libcurl/curl_easy_duphandle.md new file mode 100644 index 00000000000..359e8d2b062 --- /dev/null +++ b/docs/libcurl/curl_easy_duphandle.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_duphandle +Section: 3 +Source: libcurl +See-also: + - curl_easy_cleanup (3) + - curl_easy_init (3) + - curl_easy_reset (3) + - curl_global_init (3) +--- + +# NAME + +curl_easy_duphandle - Clone a libcurl session handle + +# SYNOPSIS + +~~~c +#include + +CURL *curl_easy_duphandle(CURL *handle); +~~~ + +# DESCRIPTION + +This function returns a new curl handle, a duplicate, using all the options +previously set in the input curl *handle*. Both handles can subsequently be +used independently and they must both be freed with curl_easy_cleanup(3). + +Any options that the input handle has been told to point to (as opposed to +copy) with previous calls to curl_easy_setopt(3), are pointed to by the new +handle as well. You must therefore make sure to keep the data around until +both handles have been cleaned up. + +The new handle does **not** inherit any state information, no connections, no +SSL sessions and no cookies. It also does not inherit any share object states +or options (created as if CURLOPT_SHARE(3) was set to NULL). + +If the source handle has HSTS or alt-svc enabled, the duplicate gets data read +data from the main file name to populate the cache. + +In multi-threaded programs, this function must be called in a synchronous way, +the input handle may not be in use when cloned. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + CURL *nother; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + nother = curl_easy_duphandle(curl); + res = curl_easy_perform(nother); + curl_easy_cleanup(nother); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.9 + +# RETURN VALUE + +If this function returns NULL, something went wrong and no valid handle was +returned. diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3 deleted file mode 100644 index 5aa01a964a0..00000000000 --- a/docs/libcurl/curl_easy_escape.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_easy_escape 3 "7 April 2006" "libcurl" "libcurl" -.SH NAME -curl_easy_escape - URL encodes the given string -.SH SYNOPSIS -.nf -#include - -char *curl_easy_escape(CURL *curl, const char *string, int length); -.fi -.SH DESCRIPTION -This function converts the given input \fIstring\fP to a URL encoded string -and returns that as a new allocated string. All input characters that are not -a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" -version (\fB%NN\fP where \fBNN\fP is a two-digit hexadecimal number). - -If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on -the input \fIstring\fP to find out the size. This function does not accept -input strings longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB). - -Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was -per-handle character conversion support for some old operating systems such as -TPF, but it was otherwise ignored. - -You must \fIcurl_free(3)\fP the returned string when you are done with it. -.SH ENCODING -libcurl is typically not aware of, nor does it care about, character -encodings. \fIcurl_easy_escape(3)\fP encodes the data byte-by-byte into the -URL encoded version without knowledge or care for what particular character -encoding the application or the receiving server may assume that the data -uses. - -The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in -to the function is encoded correctly. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - char *output = curl_easy_escape(curl, "data to convert", 15); - if(output) { - printf("Encoded: %s\\n", output); - curl_free(output); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function. -.SH RETURN VALUE -A pointer to a null-terminated string or NULL if it failed. -.SH "SEE ALSO" -.BR curl_easy_unescape (3), -.BR curl_free (3) diff --git a/docs/libcurl/curl_easy_escape.md b/docs/libcurl/curl_easy_escape.md new file mode 100644 index 00000000000..655dbb44666 --- /dev/null +++ b/docs/libcurl/curl_easy_escape.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_escape +Section: 3 +Source: libcurl +See-also: + - curl_easy_unescape (3) + - curl_free (3) +--- + +# NAME + +curl_easy_escape - URL encodes the given string + +# SYNOPSIS + +~~~c +#include + +char *curl_easy_escape(CURL *curl, const char *string, int length); +~~~ + +# DESCRIPTION + +This function converts the given input *string* to a URL encoded string +and returns that as a new allocated string. All input characters that are not +a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" +version (**%NN** where **NN** is a two-digit hexadecimal number). + +If *length* is set to 0 (zero), curl_easy_escape(3) uses strlen() on +the input *string* to find out the size. This function does not accept +input strings longer than **CURL_MAX_INPUT_LENGTH** (8 MB). + +Since 7.82.0, the **curl** parameter is ignored. Prior to that there was +per-handle character conversion support for some old operating systems such as +TPF, but it was otherwise ignored. + +You must curl_free(3) the returned string when you are done with it. + +# ENCODING + +libcurl is typically not aware of, nor does it care about, character +encodings. curl_easy_escape(3) encodes the data byte-by-byte into the +URL encoded version without knowledge or care for what particular character +encoding the application or the receiving server may assume that the data +uses. + +The caller of curl_easy_escape(3) must make sure that the data passed in +to the function is encoded correctly. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char *output = curl_easy_escape(curl, "data to convert", 15); + if(output) { + printf("Encoded: %s\n", output); + curl_free(output); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.4 and replaces the old curl_escape(3) function. + +# RETURN VALUE + +A pointer to a null-terminated string or NULL if it failed. diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 deleted file mode 100644 index 1c12cf419e4..00000000000 --- a/docs/libcurl/curl_easy_getinfo.3 +++ /dev/null @@ -1,336 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_easy_getinfo 3 "11 Feb 2009" "libcurl" "libcurl" -.SH NAME -curl_easy_getinfo - extract information from a curl handle -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... ); -.fi -.SH DESCRIPTION -Get the \fIinfo\fP kept in the \fIcurl\fP handle. The third argument -\fBMUST\fP be pointing to the specific type of the used option which is -documented in each man page of the \fIinfo\fP option. The data is stored -accordingly and can be relied upon only if this function returns CURLE_OK. Use -this function after a performed transfer if you want to get transfer related -data. - -You should not free the memory returned by this function unless it is -explicitly mentioned below. -.SH AVAILABLE INFORMATION -The following information can be extracted: -.IP CURLINFO_EFFECTIVE_METHOD -Last used HTTP method. -See \fICURLINFO_EFFECTIVE_METHOD(3)\fP -.IP CURLINFO_EFFECTIVE_URL -Last used URL. -See \fICURLINFO_EFFECTIVE_URL(3)\fP -.IP CURLINFO_RESPONSE_CODE -Last received response code. -See \fICURLINFO_RESPONSE_CODE(3)\fP -.IP CURLINFO_REFERER -Referrer header. -See \fICURLINFO_REFERER(3)\fP -.IP CURLINFO_HTTP_CONNECTCODE -Last proxy CONNECT response code. -See \fICURLINFO_HTTP_CONNECTCODE(3)\fP -.IP CURLINFO_HTTP_VERSION -The http version used in the connection. -See \fICURLINFO_HTTP_VERSION(3)\fP -.IP CURLINFO_FILETIME -Remote time of the retrieved document. See \fICURLINFO_FILETIME(3)\fP -.IP CURLINFO_FILETIME_T -Remote time of the retrieved document. See \fICURLINFO_FILETIME_T(3)\fP -.IP CURLINFO_TOTAL_TIME -Total time of previous transfer. -See \fICURLINFO_TOTAL_TIME(3)\fP -.IP CURLINFO_TOTAL_TIME_T -Total time of previous transfer. -See \fICURLINFO_TOTAL_TIME_T(3)\fP -.IP CURLINFO_NAMELOOKUP_TIME -Time from start until name resolving completed. -See \fICURLINFO_NAMELOOKUP_TIME(3)\fP -.IP CURLINFO_NAMELOOKUP_TIME_T -Time from start until name resolving completed. -See \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP -.IP CURLINFO_CONNECT_TIME -Time from start until remote host or proxy completed. -See \fICURLINFO_CONNECT_TIME(3)\fP -.IP CURLINFO_CONNECT_TIME_T -Time from start until remote host or proxy completed. -See \fICURLINFO_CONNECT_TIME_T(3)\fP -.IP CURLINFO_APPCONNECT_TIME -Time from start until SSL/SSH handshake completed. -See \fICURLINFO_APPCONNECT_TIME(3)\fP -.IP CURLINFO_APPCONNECT_TIME_T -Time from start until SSL/SSH handshake completed. -See \fICURLINFO_APPCONNECT_TIME_T(3)\fP -.IP CURLINFO_PRETRANSFER_TIME -Time from start until just before the transfer begins. -See \fICURLINFO_PRETRANSFER_TIME(3)\fP -.IP CURLINFO_PRETRANSFER_TIME_T -Time from start until just before the transfer begins. -See \fICURLINFO_PRETRANSFER_TIME_T(3)\fP -.IP CURLINFO_QUEUE_TIME_T -Time during which this transfer was held in a waiting queue. -See \fICURLINFO_QUEUE_TIME_T(3\fP -.IP CURLINFO_STARTTRANSFER_TIME -Time from start until just when the first byte is received. -See \fICURLINFO_STARTTRANSFER_TIME(3)\fP -.IP CURLINFO_STARTTRANSFER_TIME_T -Time from start until just when the first byte is received. -See \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP -.IP CURLINFO_REDIRECT_TIME -Time taken for all redirect steps before the final transfer. -See \fICURLINFO_REDIRECT_TIME(3)\fP -.IP CURLINFO_REDIRECT_TIME_T -Time taken for all redirect steps before the final transfer. -See \fICURLINFO_REDIRECT_TIME_T(3)\fP -.IP CURLINFO_REDIRECT_COUNT -Total number of redirects that were followed. -See \fICURLINFO_REDIRECT_COUNT(3)\fP -.IP CURLINFO_REDIRECT_URL -URL a redirect would take you to, had you enabled redirects. -See \fICURLINFO_REDIRECT_URL(3)\fP -.IP CURLINFO_SIZE_UPLOAD -(Deprecated) Number of bytes uploaded. -See \fICURLINFO_SIZE_UPLOAD(3)\fP -.IP CURLINFO_SIZE_UPLOAD_T -Number of bytes uploaded. -See \fICURLINFO_SIZE_UPLOAD_T(3)\fP -.IP CURLINFO_SIZE_DOWNLOAD -(Deprecated) Number of bytes downloaded. -See \fICURLINFO_SIZE_DOWNLOAD(3)\fP -.IP CURLINFO_SIZE_DOWNLOAD_T -Number of bytes downloaded. -See \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP -.IP CURLINFO_SPEED_DOWNLOAD -(Deprecated) Average download speed. -See \fICURLINFO_SPEED_DOWNLOAD(3)\fP -.IP CURLINFO_SPEED_DOWNLOAD_T -Average download speed. -See \fICURLINFO_SPEED_DOWNLOAD_T(3)\fP -.IP CURLINFO_SPEED_UPLOAD -(Deprecated) Average upload speed. -See \fICURLINFO_SPEED_UPLOAD(3)\fP -.IP CURLINFO_SPEED_UPLOAD_T -Average upload speed. -See \fICURLINFO_SPEED_UPLOAD_T(3)\fP -.IP CURLINFO_HEADER_SIZE -Number of bytes of all headers received. -See \fICURLINFO_HEADER_SIZE(3)\fP -.IP CURLINFO_REQUEST_SIZE -Number of bytes sent in the issued HTTP requests. -See \fICURLINFO_REQUEST_SIZE(3)\fP -.IP CURLINFO_SSL_VERIFYRESULT -Certificate verification result. -See \fICURLINFO_SSL_VERIFYRESULT(3)\fP -.IP CURLINFO_PROXY_ERROR -Detailed proxy error. -See \fICURLINFO_PROXY_ERROR(3)\fP -.IP CURLINFO_PROXY_SSL_VERIFYRESULT -Proxy certificate verification result. -See \fICURLINFO_PROXY_SSL_VERIFYRESULT(3)\fP -.IP CURLINFO_SSL_ENGINES -A list of OpenSSL crypto engines. -See \fICURLINFO_SSL_ENGINES(3)\fP -.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD -(Deprecated) Content length from the Content-Length header. -See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD(3)\fP -.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T -Content length from the Content-Length header. -See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP -.IP CURLINFO_CONTENT_LENGTH_UPLOAD -(Deprecated) Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP -.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T -Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP -.IP CURLINFO_CONTENT_TYPE -Content type from the Content-Type header. -See \fICURLINFO_CONTENT_TYPE(3)\fP -.IP CURLINFO_RETRY_AFTER -The value from the Retry-After header. -See \fICURLINFO_RETRY_AFTER(3)\fP -.IP CURLINFO_PRIVATE -User's private data pointer. -See \fICURLINFO_PRIVATE(3)\fP -.IP CURLINFO_HTTPAUTH_AVAIL -Available HTTP authentication methods. -See \fICURLINFO_HTTPAUTH_AVAIL(3)\fP -.IP CURLINFO_PROXYAUTH_AVAIL -Available HTTP proxy authentication methods. -See \fICURLINFO_PROXYAUTH_AVAIL(3)\fP -.IP CURLINFO_OS_ERRNO -The errno from the last failure to connect. -See \fICURLINFO_OS_ERRNO(3)\fP -.IP CURLINFO_NUM_CONNECTS -Number of new successful connections used for previous transfer. -See \fICURLINFO_NUM_CONNECTS(3)\fP -.IP CURLINFO_PRIMARY_IP -Destination IP address of the last connection. -See \fICURLINFO_PRIMARY_IP(3)\fP -.IP CURLINFO_PRIMARY_PORT -Destination port of the last connection. -See \fICURLINFO_PRIMARY_PORT(3)\fP -.IP CURLINFO_LOCAL_IP -Source IP address of the last connection. -See \fICURLINFO_LOCAL_IP(3)\fP -.IP CURLINFO_LOCAL_PORT -Source port number of the last connection. -See \fICURLINFO_LOCAL_PORT(3)\fP -.IP CURLINFO_COOKIELIST -List of all known cookies. -See \fICURLINFO_COOKIELIST(3)\fP -.IP CURLINFO_LASTSOCKET -(Deprecated) Last socket used. -See \fICURLINFO_LASTSOCKET(3)\fP -.IP CURLINFO_ACTIVESOCKET -The session's active socket. -See \fICURLINFO_ACTIVESOCKET(3)\fP -.IP CURLINFO_FTP_ENTRY_PATH -The entry path after logging in to an FTP server. -See \fICURLINFO_FTP_ENTRY_PATH(3)\fP -.IP CURLINFO_CAPATH -Get the default value for \fICURLOPT_CAPATH(3)\fP. -See \fICURLINFO_CAPATH(3)\fP -.IP CURLINFO_CAINFO -Get the default value for \fICURLOPT_CAINFO(3)\fP. -See \fICURLINFO_CAINFO(3)\fP -.IP CURLINFO_CERTINFO -Certificate chain. -See \fICURLINFO_CERTINFO(3)\fP -.IP CURLINFO_TLS_SSL_PTR -TLS session info that can be used for further processing. -See \fICURLINFO_TLS_SSL_PTR(3)\fP -.IP CURLINFO_TLS_SESSION -TLS session info that can be used for further processing. See -\fICURLINFO_TLS_SESSION(3)\fP. Deprecated option, use -\fICURLINFO_TLS_SSL_PTR(3)\fP instead! -.IP CURLINFO_CONDITION_UNMET -Whether or not a time conditional was met or 304 HTTP response. -See \fICURLINFO_CONDITION_UNMET(3)\fP -.IP CURLINFO_RTSP_SESSION_ID -RTSP session ID. -See \fICURLINFO_RTSP_SESSION_ID(3)\fP -.IP CURLINFO_RTSP_CLIENT_CSEQ -The RTSP client CSeq that is expected next. -See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP -.IP CURLINFO_RTSP_SERVER_CSEQ -The RTSP server CSeq that is expected next. -See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP -.IP CURLINFO_RTSP_CSEQ_RECV -RTSP CSeq last received. -See \fICURLINFO_RTSP_CSEQ_RECV(3)\fP -.IP CURLINFO_PROTOCOL -(Deprecated) The protocol used for the connection. (Added in 7.52.0) -See \fICURLINFO_PROTOCOL(3)\fP -.IP CURLINFO_SCHEME -The scheme used for the connection. (Added in 7.52.0) -See \fICURLINFO_SCHEME(3)\fP -.IP CURLINFO_CONN_ID -The ID of the last connection used by the transfer. (Added in 8.2.0) -See \fICURLINFO_CONN_ID(3)\fP -.IP CURLINFO_XFER_ID -The ID of the transfer. (Added in 8.2.0) -See \fICURLINFO_XFER_ID(3)\fP -.SH TIMES -An overview of the time values available from \fIcurl_easy_getinfo(3)\fP -.nf - -curl_easy_perform() - | - |--QUEUE_TIME - |--|--NAMELOOKUP - |--|--|--CONNECT - |--|--|--|--APPCONNECT - |--|--|--|--|--PRETRANSFER - |--|--|--|--|--|--STARTTRANSFER - |--|--|--|--|--|--|--TOTAL - |--|--|--|--|--|--|--REDIRECT -.fi -.IP "QUEUE_TIME" -\fICURLINFO_QUEUE_TIME_T(3\fP. The time during which the transfer was held in -a waiting queue before it could start for real. (Added in 8.6.0) -.IP NAMELOOKUP -\fICURLINFO_NAMELOOKUP_TIME(3)\fP and \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP. -The time it took from the start until the name resolving was completed. -.IP CONNECT -\fICURLINFO_CONNECT_TIME(3)\fP and \fICURLINFO_CONNECT_TIME_T(3)\fP. The time -it took from the start until the connect to the remote host (or proxy) was -completed. -.IP APPCONNECT -\fICURLINFO_APPCONNECT_TIME(3)\fP and \fICURLINFO_APPCONNECT_TIME_T(3)\fP. -The time it took from the start until the SSL connect/handshake with the -remote host was completed. (Added in 7.19.0) The latter is the integer version -(measuring microseconds). (Added in 7.60.0) -.IP PRETRANSFER -\fICURLINFO_PRETRANSFER_TIME(3)\fP and \fICURLINFO_PRETRANSFER_TIME_T(3)\fP. -The time it took from the start until the file transfer is just about to -begin. This includes all pre-transfer commands and negotiations that are -specific to the particular protocol(s) involved. -.IP STARTTRANSFER -\fICURLINFO_STARTTRANSFER_TIME(3)\fP and -\fICURLINFO_STARTTRANSFER_TIME_T(3)\fP. The time it took from the start until -the first byte is received by libcurl. -.IP TOTAL -\fICURLINFO_TOTAL_TIME(3)\fP and \fICURLINFO_TOTAL_TIME_T(3)\fP. Total time -of the previous request. -.IP REDIRECT -\fICURLINFO_REDIRECT_TIME(3)\fP and \fICURLINFO_REDIRECT_TIME_T(3)\fP. The -time it took for all redirection steps include name lookup, connect, -pretransfer and transfer before final transaction was started. So, this is -zero if no redirection took place. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); - res = curl_easy_perform(curl); - - if(CURLE_OK == res) { - char *ct; - /* ask for the content-type */ - res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); - - if((CURLE_OK == res) && ct) - printf("We received Content-Type: %s\\n", ct); - } - - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1 -.SH RETURN VALUE -If the operation was successful, CURLE_OK is returned. Otherwise an -appropriate error code is returned. -.SH "SEE ALSO" -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/curl_easy_getinfo.md b/docs/libcurl/curl_easy_getinfo.md new file mode 100644 index 00000000000..3b98ea4ebb0 --- /dev/null +++ b/docs/libcurl/curl_easy_getinfo.md @@ -0,0 +1,483 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_getinfo +Section: 3 +Source: libcurl +See-also: + - curl_easy_setopt (3) +--- + +# NAME + +curl_easy_getinfo - extract information from a curl handle + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... ); +~~~ + +# DESCRIPTION + +Get the *info* kept in the *curl* handle. The third argument **MUST** be +pointing to the specific type of the used option which is documented in each +man page of the *info* option. The data is stored accordingly and can be +relied upon only if this function returns CURLE_OK. Use this function after a +performed transfer if you want to get transfer related data. + +You should not free the memory returned by this function unless it is +explicitly mentioned below. + +# AVAILABLE INFORMATION + +The following information can be extracted: + +## CURLINFO_EFFECTIVE_METHOD + +Last used HTTP method. See CURLINFO_EFFECTIVE_METHOD(3) + +## CURLINFO_EFFECTIVE_URL + +Last used URL. See CURLINFO_EFFECTIVE_URL(3) + +## CURLINFO_RESPONSE_CODE + +Last received response code. See CURLINFO_RESPONSE_CODE(3) + +## CURLINFO_REFERER + +Referrer header. See CURLINFO_REFERER(3) + +## CURLINFO_HTTP_CONNECTCODE + +Last proxy CONNECT response code. See CURLINFO_HTTP_CONNECTCODE(3) + +## CURLINFO_HTTP_VERSION + +The http version used in the connection. See CURLINFO_HTTP_VERSION(3) + +## CURLINFO_FILETIME + +Remote time of the retrieved document. See CURLINFO_FILETIME(3) + +## CURLINFO_FILETIME_T + +Remote time of the retrieved document. See CURLINFO_FILETIME_T(3) + +## CURLINFO_TOTAL_TIME + +Total time of previous transfer. See CURLINFO_TOTAL_TIME(3) + +## CURLINFO_TOTAL_TIME_T + +Total time of previous transfer. See CURLINFO_TOTAL_TIME_T(3) + +## CURLINFO_NAMELOOKUP_TIME + +Time from start until name resolving completed. See +CURLINFO_NAMELOOKUP_TIME(3) + +## CURLINFO_NAMELOOKUP_TIME_T + +Time from start until name resolving completed. See +CURLINFO_NAMELOOKUP_TIME_T(3) + +## CURLINFO_CONNECT_TIME + +Time from start until remote host or proxy completed. +See CURLINFO_CONNECT_TIME(3) + +## CURLINFO_CONNECT_TIME_T + +Time from start until remote host or proxy completed. +See CURLINFO_CONNECT_TIME_T(3) + +## CURLINFO_APPCONNECT_TIME + +Time from start until SSL/SSH handshake completed. +See CURLINFO_APPCONNECT_TIME(3) + +## CURLINFO_APPCONNECT_TIME_T + +Time from start until SSL/SSH handshake completed. +See CURLINFO_APPCONNECT_TIME_T(3) + +## CURLINFO_PRETRANSFER_TIME + +Time from start until just before the transfer begins. +See CURLINFO_PRETRANSFER_TIME(3) + +## CURLINFO_PRETRANSFER_TIME_T + +Time from start until just before the transfer begins. +See CURLINFO_PRETRANSFER_TIME_T(3) + +## CURLINFO_QUEUE_TIME_T + +Time during which this transfer was held in a waiting queue. +See CURLINFO_QUEUE_TIME_T(3) + +## CURLINFO_STARTTRANSFER_TIME + +Time from start until just when the first byte is received. +See CURLINFO_STARTTRANSFER_TIME(3) + +## CURLINFO_STARTTRANSFER_TIME_T + +Time from start until just when the first byte is received. +See CURLINFO_STARTTRANSFER_TIME_T(3) + +## CURLINFO_REDIRECT_TIME + +Time taken for all redirect steps before the final transfer. +See CURLINFO_REDIRECT_TIME(3) + +## CURLINFO_REDIRECT_TIME_T + +Time taken for all redirect steps before the final transfer. +See CURLINFO_REDIRECT_TIME_T(3) + +## CURLINFO_REDIRECT_COUNT + +Total number of redirects that were followed. +See CURLINFO_REDIRECT_COUNT(3) + +## CURLINFO_REDIRECT_URL + +URL a redirect would take you to, had you enabled redirects. +See CURLINFO_REDIRECT_URL(3) + +## CURLINFO_SIZE_UPLOAD + +(Deprecated) Number of bytes uploaded. +See CURLINFO_SIZE_UPLOAD(3) + +## CURLINFO_SIZE_UPLOAD_T + +Number of bytes uploaded. +See CURLINFO_SIZE_UPLOAD_T(3) + +## CURLINFO_SIZE_DOWNLOAD + +(Deprecated) Number of bytes downloaded. +See CURLINFO_SIZE_DOWNLOAD(3) + +## CURLINFO_SIZE_DOWNLOAD_T + +Number of bytes downloaded. +See CURLINFO_SIZE_DOWNLOAD_T(3) + +## CURLINFO_SPEED_DOWNLOAD + +(Deprecated) Average download speed. +See CURLINFO_SPEED_DOWNLOAD(3) + +## CURLINFO_SPEED_DOWNLOAD_T + +Average download speed. +See CURLINFO_SPEED_DOWNLOAD_T(3) + +## CURLINFO_SPEED_UPLOAD + +(Deprecated) Average upload speed. +See CURLINFO_SPEED_UPLOAD(3) + +## CURLINFO_SPEED_UPLOAD_T + +Average upload speed. +See CURLINFO_SPEED_UPLOAD_T(3) + +## CURLINFO_HEADER_SIZE + +Number of bytes of all headers received. +See CURLINFO_HEADER_SIZE(3) + +## CURLINFO_REQUEST_SIZE + +Number of bytes sent in the issued HTTP requests. +See CURLINFO_REQUEST_SIZE(3) + +## CURLINFO_SSL_VERIFYRESULT + +Certificate verification result. +See CURLINFO_SSL_VERIFYRESULT(3) + +## CURLINFO_PROXY_ERROR + +Detailed proxy error. +See CURLINFO_PROXY_ERROR(3) + +## CURLINFO_PROXY_SSL_VERIFYRESULT + +Proxy certificate verification result. +See CURLINFO_PROXY_SSL_VERIFYRESULT(3) + +## CURLINFO_SSL_ENGINES + +A list of OpenSSL crypto engines. +See CURLINFO_SSL_ENGINES(3) + +## CURLINFO_CONTENT_LENGTH_DOWNLOAD + +(Deprecated) Content length from the Content-Length header. +See CURLINFO_CONTENT_LENGTH_DOWNLOAD(3) + +## CURLINFO_CONTENT_LENGTH_DOWNLOAD_T + +Content length from the Content-Length header. +See CURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3) + +## CURLINFO_CONTENT_LENGTH_UPLOAD + +(Deprecated) Upload size. See CURLINFO_CONTENT_LENGTH_UPLOAD(3) + +## CURLINFO_CONTENT_LENGTH_UPLOAD_T + +Upload size. See CURLINFO_CONTENT_LENGTH_UPLOAD_T(3) + +## CURLINFO_CONTENT_TYPE + +Content type from the Content-Type header. +See CURLINFO_CONTENT_TYPE(3) + +## CURLINFO_RETRY_AFTER + +The value from the Retry-After header. +See CURLINFO_RETRY_AFTER(3) + +## CURLINFO_PRIVATE + +User's private data pointer. +See CURLINFO_PRIVATE(3) + +## CURLINFO_HTTPAUTH_AVAIL + +Available HTTP authentication methods. +See CURLINFO_HTTPAUTH_AVAIL(3) + +## CURLINFO_PROXYAUTH_AVAIL + +Available HTTP proxy authentication methods. +See CURLINFO_PROXYAUTH_AVAIL(3) + +## CURLINFO_OS_ERRNO + +The errno from the last failure to connect. +See CURLINFO_OS_ERRNO(3) + +## CURLINFO_NUM_CONNECTS + +Number of new successful connections used for previous transfer. +See CURLINFO_NUM_CONNECTS(3) + +## CURLINFO_PRIMARY_IP + +Destination IP address of the last connection. +See CURLINFO_PRIMARY_IP(3) + +## CURLINFO_PRIMARY_PORT + +Destination port of the last connection. +See CURLINFO_PRIMARY_PORT(3) + +## CURLINFO_LOCAL_IP + +Source IP address of the last connection. +See CURLINFO_LOCAL_IP(3) + +## CURLINFO_LOCAL_PORT + +Source port number of the last connection. +See CURLINFO_LOCAL_PORT(3) + +## CURLINFO_COOKIELIST + +List of all known cookies. +See CURLINFO_COOKIELIST(3) + +## CURLINFO_LASTSOCKET + +(Deprecated) Last socket used. +See CURLINFO_LASTSOCKET(3) + +## CURLINFO_ACTIVESOCKET + +The session's active socket. +See CURLINFO_ACTIVESOCKET(3) + +## CURLINFO_FTP_ENTRY_PATH + +The entry path after logging in to an FTP server. +See CURLINFO_FTP_ENTRY_PATH(3) + +## CURLINFO_CAPATH + +Get the default value for CURLOPT_CAPATH(3). +See CURLINFO_CAPATH(3) + +## CURLINFO_CAINFO + +Get the default value for CURLOPT_CAINFO(3). +See CURLINFO_CAINFO(3) + +## CURLINFO_CERTINFO + +Certificate chain. +See CURLINFO_CERTINFO(3) + +## CURLINFO_TLS_SSL_PTR + +TLS session info that can be used for further processing. +See CURLINFO_TLS_SSL_PTR(3) + +## CURLINFO_TLS_SESSION + +TLS session info that can be used for further processing. See +CURLINFO_TLS_SESSION(3). Deprecated option, use +CURLINFO_TLS_SSL_PTR(3) instead! + +## CURLINFO_CONDITION_UNMET + +Whether or not a time conditional was met or 304 HTTP response. +See CURLINFO_CONDITION_UNMET(3) + +## CURLINFO_RTSP_SESSION_ID + +RTSP session ID. +See CURLINFO_RTSP_SESSION_ID(3) + +## CURLINFO_RTSP_CLIENT_CSEQ + +The RTSP client CSeq that is expected next. +See CURLINFO_RTSP_CLIENT_CSEQ(3) + +## CURLINFO_RTSP_SERVER_CSEQ + +The RTSP server CSeq that is expected next. +See CURLINFO_RTSP_SERVER_CSEQ(3) + +## CURLINFO_RTSP_CSEQ_RECV + +RTSP CSeq last received. +See CURLINFO_RTSP_CSEQ_RECV(3) + +## CURLINFO_PROTOCOL + +(Deprecated) The protocol used for the connection. (Added in 7.52.0) +See CURLINFO_PROTOCOL(3) + +## CURLINFO_SCHEME + +The scheme used for the connection. (Added in 7.52.0) +See CURLINFO_SCHEME(3) + +## CURLINFO_CONN_ID + +The ID of the last connection used by the transfer. (Added in 8.2.0) +See CURLINFO_CONN_ID(3) + +## CURLINFO_XFER_ID + +The ID of the transfer. (Added in 8.2.0) +See CURLINFO_XFER_ID(3) + +# TIMES + +An overview of the time values available from curl_easy_getinfo(3) + +~~~ +curl_easy_perform() + | + |--QUEUE_TIME + |--|--NAMELOOKUP + |--|--|--CONNECT + |--|--|--|--APPCONNECT + |--|--|--|--|--PRETRANSFER + |--|--|--|--|--|--STARTTRANSFER + |--|--|--|--|--|--|--TOTAL + |--|--|--|--|--|--|--REDIRECT +~~~ + +## QUEUE_TIME + +CURLINFO_QUEUE_TIME_T(3). The time during which the transfer was held in a +waiting queue before it could start for real. (Added in 8.6.0) + +## NAMELOOKUP + +CURLINFO_NAMELOOKUP_TIME(3) and CURLINFO_NAMELOOKUP_TIME_T(3). The time it +took from the start until the name resolving was completed. + +## CONNECT + +CURLINFO_CONNECT_TIME(3) and CURLINFO_CONNECT_TIME_T(3). The time it took from +the start until the connect to the remote host (or proxy) was completed. + +## APPCONNECT + +CURLINFO_APPCONNECT_TIME(3) and CURLINFO_APPCONNECT_TIME_T(3). The time it +took from the start until the SSL connect/handshake with the remote host was +completed. (Added in 7.19.0) The latter is the integer version (measuring +microseconds). (Added in 7.60.0) + +## PRETRANSFER + +CURLINFO_PRETRANSFER_TIME(3) and CURLINFO_PRETRANSFER_TIME_T(3). The time it +took from the start until the file transfer is just about to begin. This +includes all pre-transfer commands and negotiations that are specific to the +particular protocol(s) involved. + +## STARTTRANSFER + +CURLINFO_STARTTRANSFER_TIME(3) and CURLINFO_STARTTRANSFER_TIME_T(3). The time +it took from the start until the first byte is received by libcurl. + +## TOTAL + +CURLINFO_TOTAL_TIME(3) and CURLINFO_TOTAL_TIME_T(3). Total time +of the previous request. + +## REDIRECT + +CURLINFO_REDIRECT_TIME(3) and CURLINFO_REDIRECT_TIME_T(3). The time it took +for all redirection steps include name lookup, connect, pretransfer and +transfer before final transaction was started. So, this is zero if no +redirection took place. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); + res = curl_easy_perform(curl); + + if(CURLE_OK == res) { + char *ct; + /* ask for the content-type */ + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); + + if((CURLE_OK == res) && ct) + printf("We received Content-Type: %s\n", ct); + } + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1 + +# RETURN VALUE + +If the operation was successful, CURLE_OK is returned. Otherwise an +appropriate error code is returned. diff --git a/docs/libcurl/curl_easy_header.3 b/docs/libcurl/curl_easy_header.md similarity index 51% rename from docs/libcurl/curl_easy_header.3 rename to docs/libcurl/curl_easy_header.md index 8cbd3e272ac..9c2d76ceaf0 100644 --- a/docs/libcurl/curl_easy_header.3 +++ b/docs/libcurl/curl_easy_header.md @@ -1,31 +1,24 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_easy_header 3 "13 March 2022" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_header +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONTENT_TYPE (3) + - CURLOPT_HEADERFUNCTION (3) + - curl_easy_nextheader (3) + - curl_easy_perform (3) + - libcurl-errors (3) +--- + +# NAME + curl_easy_header - get an HTTP header -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLHcode curl_easy_header(CURL *easy, @@ -34,24 +27,26 @@ CURLHcode curl_easy_header(CURL *easy, unsigned int origin, int request, struct curl_header **hout); -.fi -.SH DESCRIPTION -\fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in -\fBhout\fP with data for the HTTP response header \fIname\fP. The case -insensitive null-terminated header name should be specified without colon. - -\fIindex\fP 0 means asking for the first instance of the header. If the -returned header struct has \fBamount\fP set larger than 1, it means there are -more instances of the same header name available to get. Asking for a too big -index makes \fBCURLHE_BADINDEX\fP get returned. - -The \fIorigin\fP argument is for specifying which headers to receive, as a -single HTTP transfer might provide headers from several different places and -they may then have different importance to the user and headers using the same -name might be used. The \fIorigin\fP is a bitmask for what header sources you -want. See the descriptions below. - -The \fIrequest\fP argument tells libcurl from which request you want headers +~~~ + +# DESCRIPTION + +curl_easy_header(3) returns a pointer to a "curl_header" struct in **hout** +with data for the HTTP response header *name*. The case insensitive +null-terminated header name should be specified without colon. + +*index* 0 means asking for the first instance of the header. If the returned +header struct has **amount** set larger than 1, it means there are more +instances of the same header name available to get. Asking for a too big index +makes **CURLHE_BADINDEX** get returned. + +The *origin* argument is for specifying which headers to receive, as a single +HTTP transfer might provide headers from several different places and they may +then have different importance to the user and headers using the same name +might be used. The *origin* is a bitmask for what header sources you want. See +the descriptions below. + +The *request* argument tells libcurl from which request you want headers from. A single transfer might consist of a series of HTTP requests and this argument lets you specify which particular individual request you want the headers from. 0 being the first request and then the number increases for @@ -66,10 +61,10 @@ second, then only the first one is provided. An application using this API does not have to bother about multiple headers used wrongly. The memory for the returned struct is associated with the easy handle and -subsequent calls to \fIcurl_easy_header(3)\fP clobber the struct used in the +subsequent calls to curl_easy_header(3) clobber the struct used in the previous calls for the same easy handle. Applications need to copy the data if it wants to keep it around. The memory used for the struct gets freed with -calling \fIcurl_easy_cleanup(3)\fP of the easy handle. +calling curl_easy_cleanup(3) of the easy handle. The first line in an HTTP response is called the status line. It is not considered a header by this function. Headers are the "name: value" lines @@ -78,8 +73,10 @@ following the status. This function can be used before (all) headers have been received and is fine to call from within libcurl callbacks. It returns the state of the headers at the time it is called. -.SH "The header struct" -.nf + +# The header struct + +~~~c struct curl_header { char *name; char *value; @@ -88,45 +85,58 @@ struct curl_header { unsigned int origin; void *anchor; }; -.fi +~~~ -The data \fBname\fP field points to, is the same as the requested name, but +The data **name** field points to, is the same as the requested name, but might have a different case. -The data \fBvalue\fP field points to, comes exactly as delivered over the +The data **value** field points to, comes exactly as delivered over the network but with leading and trailing whitespace and newlines stripped off. The `value` data is null-terminated. For legacy HTTP/1 "folded headers", this API provides the full single value in an unfolded manner with a single whitespace between the lines. -\fBamount\fP is how many headers using this name that exist, within the origin +**amount** is how many headers using this name that exist, within the origin and request scope asked for. -\fBindex\fP is the zero based entry number of this particular header, which in +**index** is the zero based entry number of this particular header, which in case this header was used more than once in the requested scope can be larger -than 0 but is always less than \fBamount\fP. +than 0 but is always less than **amount**. -The \fBorigin\fP field in the "curl_header" struct has one of the origin bits +The **origin** field in the "curl_header" struct has one of the origin bits set, indicating where from the header originates. At the time of this writing, there are 5 bits with defined use. The undocumented 27 remaining bits are reserved for future use and must not be assumed to have any particular value. -\fBanchor\fP is a private handle used by libcurl internals. Do not modify. -.SH ORIGINS -.IP CURLH_HEADER +**anchor** is a private handle used by libcurl internals. Do not modify. + +# ORIGINS + +## CURLH_HEADER + The header arrived as a header from the server. -.IP CURLH_TRAILER + +## CURLH_TRAILER + The header arrived as a trailer. A header that arrives after the body. -.IP CURLH_CONNECT + +## CURLH_CONNECT + The header arrived in a CONNECT response. A CONNECT request is being done to setup a transfer "through" an HTTP(S) proxy. -.IP CURLH_1XX + +## CURLH_1XX + The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate" response that might happen before the "real" response. -.IP CURLH_PSEUDO + +## CURLH_PSEUDO + The header is an HTTP/2 or HTTP/3 pseudo header -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { struct curl_header *type; @@ -139,14 +149,12 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.83.0. Officially supported since 7.84.0. -.SH RETURN VALUE + +# RETURN VALUE + This function returns a CURLHcode indicating success or error. -.SH "SEE ALSO" -.BR curl_easy_nextheader (3), -.BR curl_easy_perform (3), -.BR CURLINFO_CONTENT_TYPE (3), -.BR CURLOPT_HEADERFUNCTION (3), -.BR libcurl-errors (3) diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 deleted file mode 100644 index 23801698614..00000000000 --- a/docs/libcurl/curl_easy_init.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_init 3 "4 March 2002" "libcurl" "libcurl" -.SH NAME -curl_easy_init - Start a libcurl easy session -.SH SYNOPSIS -.nf -#include - -CURL *curl_easy_init(); -.fi -.SH DESCRIPTION -This function allocates and returns a CURL easy handle. Such a handle is used -as input to other functions in the easy interface. This call must have a -corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is -complete. - -The easy handle is used to hold and control a single network transfer. It is -encouraged to reuse easy handles for repeated transfers. - -An alternative way to get a new easy handle is to duplicate an already -existing one with \fIcurl_easy_duphandle(3)\fP, which has the upside that it -gets all the options that were set in the source handle set in the new copy as -well. - -If you did not already call \fIcurl_global_init(3)\fP before calling this -function, \fIcurl_easy_init(3)\fP does it automatically. This may be lethal in -multi-threaded cases, if \fIcurl_global_init(3)\fP is not thread-safe in your -system, and it may then result in resource problems because there is no -corresponding cleanup. - -You are strongly advised to not allow this automatic behavior, by calling -\fIcurl_global_init(3)\fP yourself properly. See the description in -\fBlibcurl\fP(3) of global environment requirements for details of how to use -this function. - -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -If this function returns NULL, something went wrong and you cannot use the -other curl functions. -.SH "SEE ALSO" -.BR curl_easy_cleanup (3), -.BR curl_easy_duphandle (3), -.BR curl_easy_perform (3), -.BR curl_easy_reset (3), -.BR curl_global_init (3), -.BR curl_multi_init (3) diff --git a/docs/libcurl/curl_easy_init.md b/docs/libcurl/curl_easy_init.md new file mode 100644 index 00000000000..a7465547fbe --- /dev/null +++ b/docs/libcurl/curl_easy_init.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_init +Section: 3 +Source: libcurl +See-also: + - curl_easy_cleanup (3) + - curl_easy_duphandle (3) + - curl_easy_perform (3) + - curl_easy_reset (3) + - curl_global_init (3) + - curl_multi_init (3) +--- + +# NAME + +curl_easy_init - Start a libcurl easy session + +# SYNOPSIS + +~~~c +#include + +CURL *curl_easy_init(); +~~~ + +# DESCRIPTION + +This function allocates and returns a CURL easy handle. Such a handle is used +as input to other functions in the easy interface. This call must have a +corresponding call to curl_easy_cleanup(3) when the operation is complete. + +The easy handle is used to hold and control a single network transfer. It is +encouraged to reuse easy handles for repeated transfers. + +An alternative way to get a new easy handle is to duplicate an already +existing one with curl_easy_duphandle(3), which has the upside that it gets +all the options that were set in the source handle set in the new copy as +well. + +If you did not already call curl_global_init(3) before calling this function, +curl_easy_init(3) does it automatically. This may be lethal in multi-threaded +cases, if curl_global_init(3) is not thread-safe in your system, and it may +then result in resource problems because there is no corresponding cleanup. + +You are strongly advised to not allow this automatic behavior, by calling +curl_global_init(3) yourself properly. See the description in libcurl(3) of +global environment requirements for details of how to use this function. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +If this function returns NULL, something went wrong and you cannot use the +other curl functions. diff --git a/docs/libcurl/curl_easy_nextheader.3 b/docs/libcurl/curl_easy_nextheader.3 deleted file mode 100644 index 44262463da1..00000000000 --- a/docs/libcurl/curl_easy_nextheader.3 +++ /dev/null @@ -1,106 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_nextheader 3 "13 March 2022" "libcurl" "libcurl" -.SH NAME -curl_easy_nextheader - get the next HTTP header -.SH SYNOPSIS -.nf -#include - -struct curl_header *curl_easy_nextheader(CURL *easy, - unsigned int origin, - int request, - struct curl_header *prev); -.fi -.SH DESCRIPTION -This function lets an application iterate over all previously received HTTP -headers. - -The \fIorigin\fP argument is for specifying which headers to receive, as a -single HTTP transfer might provide headers from several different places and -they may then have different importance to the user and headers using the same -name might be used. The \fIorigin\fP is a bitmask for what header sources you -want. See the \fIcurl_easy_header(3)\fP man page for the origin descriptions. - -The \fIrequest\fP argument tells libcurl from which request you want headers -from. A single transfer might consist of a series of HTTP requests and this -argument lets you specify which particular individual request you want the -headers from. 0 being the first request and then the number increases for -further redirects or when multi-state authentication is used. Passing in -1 is -a shortcut to "the last" request in the series, independently of the actual -amount of requests used. - -It is suggested that you pass in the same \fBorigin\fP and \fBrequest\fP when -iterating over a range of headers as changing the value mid-loop might give -you unexpected results. - -If \fIprev\fP is NULL, this function returns a pointer to the first header -stored within the given scope (origin + request). - -If \fIprev\fP is a pointer to a previously returned header struct, -\fIcurl_easy_nextheader(3)\fP returns a pointer the next header stored within -the given scope. This way, an application can iterate over all available -headers. - -The memory for the struct this points to, is owned and managed by libcurl and -is associated with the easy handle. Applications must copy the data if they -want it to survive subsequent API calls or the life-time of the easy handle. -.SH EXAMPLE -.nf -int main(void) -{ - struct curl_header *prev = NULL; - struct curl_header *h; - - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_perform(curl); - - /* extract the normal headers from the first request */ - while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) { - printf("%s: %s\\n", h->name, h->value); - prev = h; - } - - /* extract the normal headers + 1xx + trailers from the last request */ - unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER; - while((h = curl_easy_nextheader(curl, origin, -1, prev))) { - printf("%s: %s\\n", h->name, h->value); - prev = h; - } - } -} -.fi -.SH AVAILABILITY -Added in 7.83.0. Officially supported since 7.84.0. -.SH RETURN VALUE -This function returns the next header, or NULL when there are no more -(matching) headers or an error occurred. - -If this function returns NULL when \fIprev\fP was set to NULL, then there are -no headers available within the scope to return. -.SH "SEE ALSO" -.BR curl_easy_header (3), -.BR curl_easy_perform (3) diff --git a/docs/libcurl/curl_easy_nextheader.md b/docs/libcurl/curl_easy_nextheader.md new file mode 100644 index 00000000000..7c7e151c33d --- /dev/null +++ b/docs/libcurl/curl_easy_nextheader.md @@ -0,0 +1,100 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_nextheader +Section: 3 +Source: libcurl +See-also: + - curl_easy_header (3) + - curl_easy_perform (3) +--- + +# NAME + +curl_easy_nextheader - get the next HTTP header + +# SYNOPSIS + +~~~c +#include + +struct curl_header *curl_easy_nextheader(CURL *easy, + unsigned int origin, + int request, + struct curl_header *prev); +~~~ + +# DESCRIPTION + +This function lets an application iterate over all previously received HTTP +headers. + +The *origin* argument is for specifying which headers to receive, as a single +HTTP transfer might provide headers from several different places and they may +then have different importance to the user and headers using the same name +might be used. The *origin* is a bitmask for what header sources you want. See +the curl_easy_header(3) man page for the origin descriptions. + +The *request* argument tells libcurl from which request you want headers +from. A single transfer might consist of a series of HTTP requests and this +argument lets you specify which particular individual request you want the +headers from. 0 being the first request and then the number increases for +further redirects or when multi-state authentication is used. Passing in -1 is +a shortcut to "the last" request in the series, independently of the actual +amount of requests used. + +It is suggested that you pass in the same **origin** and **request** when +iterating over a range of headers as changing the value mid-loop might give +you unexpected results. + +If *prev* is NULL, this function returns a pointer to the first header stored +within the given scope (origin + request). + +If *prev* is a pointer to a previously returned header struct, +curl_easy_nextheader(3) returns a pointer the next header stored within the +given scope. This way, an application can iterate over all available headers. + +The memory for the struct this points to, is owned and managed by libcurl and +is associated with the easy handle. Applications must copy the data if they +want it to survive subsequent API calls or the life-time of the easy handle. + +# EXAMPLE + +~~~c +int main(void) +{ + struct curl_header *prev = NULL; + struct curl_header *h; + + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_perform(curl); + + /* extract the normal headers from the first request */ + while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) { + printf("%s: %s\n", h->name, h->value); + prev = h; + } + + /* extract the normal headers + 1xx + trailers from the last request */ + unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER; + while((h = curl_easy_nextheader(curl, origin, -1, prev))) { + printf("%s: %s\n", h->name, h->value); + prev = h; + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.83.0. Officially supported since 7.84.0. + +# RETURN VALUE + +This function returns the next header, or NULL when there are no more +(matching) headers or an error occurred. + +If this function returns NULL when *prev* was set to NULL, then there are no +headers available within the scope to return. diff --git a/docs/libcurl/curl_easy_option_by_id.3 b/docs/libcurl/curl_easy_option_by_id.3 deleted file mode 100644 index ded364bcabc..00000000000 --- a/docs/libcurl/curl_easy_option_by_id.3 +++ /dev/null @@ -1,59 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_option_by_id 3 "27 Aug 2020" "libcurl" "libcurl" -.SH NAME -curl_easy_option_by_id - find an easy setopt option by id -.SH SYNOPSIS -.nf -#include - -const struct curl_easyoption *curl_easy_option_by_id(CURLoption id); -.fi -.SH DESCRIPTION -Given a \fICURLoption\fP \fBid\fP, this function returns a pointer to the -\fIcurl_easyoption\fP struct, holding information about the -\fIcurl_easy_setopt(3)\fP option using that id. The option id is the CURLOPT_ -prefix ones provided in the standard curl/curl.h header file. This function -returns the non-alias version of the cases where there is an alias function as -well. - -If libcurl has no option with the given id, this function returns NULL. -.SH EXAMPLE -.nf -int main(void) -{ - const struct curl_easyoption *opt = curl_easy_option_by_id(CURLOPT_URL); - if(opt) { - printf("This option wants type %x\\n", opt->type); - } -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.73.0 -.SH RETURN VALUE -A pointer to the \fIcurl_easyoption\fP struct for the option or NULL. -.SH "SEE ALSO" -.BR curl_easy_option_by_name (3), -.BR curl_easy_option_next (3), -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/curl_easy_option_by_id.md b/docs/libcurl/curl_easy_option_by_id.md new file mode 100644 index 00000000000..b1d6d421b7d --- /dev/null +++ b/docs/libcurl/curl_easy_option_by_id.md @@ -0,0 +1,54 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_option_by_id +Section: 3 +Source: libcurl +See-also: + - curl_easy_option_by_name (3) + - curl_easy_option_next (3) + - curl_easy_setopt (3) +--- + +# NAME + +curl_easy_option_by_id - find an easy setopt option by id + +# SYNOPSIS + +~~~c +#include + +const struct curl_easyoption *curl_easy_option_by_id(CURLoption id); +~~~ + +# DESCRIPTION + +Given a *CURLoption* **id**, this function returns a pointer to the +*curl_easyoption* struct, holding information about the +curl_easy_setopt(3) option using that id. The option id is the CURLOPT_ +prefix ones provided in the standard curl/curl.h header file. This function +returns the non-alias version of the cases where there is an alias function as +well. + +If libcurl has no option with the given id, this function returns NULL. + +# EXAMPLE + +~~~c +int main(void) +{ + const struct curl_easyoption *opt = curl_easy_option_by_id(CURLOPT_URL); + if(opt) { + printf("This option wants type %x\n", opt->type); + } +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.73.0 + +# RETURN VALUE + +A pointer to the *curl_easyoption* struct for the option or NULL. diff --git a/docs/libcurl/curl_easy_option_by_name.3 b/docs/libcurl/curl_easy_option_by_name.3 deleted file mode 100644 index 87652e7238a..00000000000 --- a/docs/libcurl/curl_easy_option_by_name.3 +++ /dev/null @@ -1,58 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_option_by_name 3 "27 Aug 2020" "libcurl" "libcurl" -.SH NAME -curl_easy_option_by_name - find an easy setopt option by name -.SH SYNOPSIS -.nf -#include - -const struct curl_easyoption *curl_easy_option_by_name(const char *name); -.fi -.SH DESCRIPTION -Given a \fBname\fP, this function returns a pointer to the -\fIcurl_easyoption\fP struct, holding information about the -\fIcurl_easy_setopt(3)\fP option using that name. The name should be specified -without the "CURLOPT_" prefix and the name comparison is made case -insensitive. - -If libcurl has no option with the given name, this function returns NULL. -.SH EXAMPLE -.nf -int main(void) -{ - const struct curl_easyoption *opt = curl_easy_option_by_name("URL"); - if(opt) { - printf("This option wants CURLoption %x\\n", (int)opt->id); - } -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.73.0 -.SH RETURN VALUE -A pointer to the \fIcurl_easyoption\fP struct for the option or NULL. -.SH "SEE ALSO" -.BR curl_easy_option_by_id (3), -.BR curl_easy_option_next (3), -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/curl_easy_option_by_name.md b/docs/libcurl/curl_easy_option_by_name.md new file mode 100644 index 00000000000..86ccbd4da22 --- /dev/null +++ b/docs/libcurl/curl_easy_option_by_name.md @@ -0,0 +1,53 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_option_by_name +Section: 3 +Source: libcurl +See-also: + - curl_easy_option_by_id (3) + - curl_easy_option_next (3) + - curl_easy_setopt (3) +--- + +# NAME + +curl_easy_option_by_name - find an easy setopt option by name + +# SYNOPSIS + +~~~c +#include + +const struct curl_easyoption *curl_easy_option_by_name(const char *name); +~~~ + +# DESCRIPTION + +Given a **name**, this function returns a pointer to the +*curl_easyoption* struct, holding information about the +curl_easy_setopt(3) option using that name. The name should be specified +without the "CURLOPT_" prefix and the name comparison is made case +insensitive. + +If libcurl has no option with the given name, this function returns NULL. + +# EXAMPLE + +~~~c +int main(void) +{ + const struct curl_easyoption *opt = curl_easy_option_by_name("URL"); + if(opt) { + printf("This option wants CURLoption %x\n", (int)opt->id); + } +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.73.0 + +# RETURN VALUE + +A pointer to the *curl_easyoption* struct for the option or NULL. diff --git a/docs/libcurl/curl_easy_option_next.3 b/docs/libcurl/curl_easy_option_next.3 deleted file mode 100644 index e2b35c522c9..00000000000 --- a/docs/libcurl/curl_easy_option_next.3 +++ /dev/null @@ -1,92 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_option_next 3 "27 Aug 2020" "libcurl" "libcurl" -.SH NAME -curl_easy_option_next - iterate over easy setopt options -.SH SYNOPSIS -.nf -#include - -const struct curl_easyoption * -curl_easy_option_next(const struct curl_easyoption *prev); -.fi -.SH DESCRIPTION -This function returns a pointer to the first or the next \fIcurl_easyoption\fP -struct, providing an ability to iterate over all known options for -\fIcurl_easy_setopt(3)\fP in this instance of libcurl. - -Pass a \fBNULL\fP argument as \fBprev\fP to get the first option returned, or -pass in the current option to get the next one returned. If there is no more -option to return, \fIcurl_easy_option_next(3)\fP returns NULL. - -The options returned by this functions are the ones known to this libcurl and -information about what argument type they want. - -If the \fBCURLOT_FLAG_ALIAS\fP bit is set in the flags field, it means the -name is provided for backwards compatibility as an alias. -.SH struct -.nf -typedef enum { - CURLOT_LONG, /* long (a range of values) */ - CURLOT_VALUES, /* (a defined set or bitmask) */ - CURLOT_OFF_T, /* curl_off_t (a range of values) */ - CURLOT_OBJECT, /* pointer (void *) */ - CURLOT_STRING, /* (char * to null-terminated buffer) */ - CURLOT_SLIST, /* (struct curl_slist *) */ - CURLOT_CBPTR, /* (void * passed as-is to a callback) */ - CURLOT_BLOB, /* blob (struct curl_blob *) */ - CURLOT_FUNCTION /* function pointer */ -} curl_easytype; - -/* The CURLOPTTYPE_* id ranges can still be used to figure out what type/size - to use for curl_easy_setopt() for the given id */ -struct curl_easyoption { - const char *name; - CURLoption id; - curl_easytype type; - unsigned int flags; -}; -.fi -.SH EXAMPLE -.nf -int main(void) -{ - /* iterate over all available options */ - const struct curl_easyoption *opt; - opt = curl_easy_option_next(NULL); - while(opt) { - printf("Name: %s\\n", opt->name); - opt = curl_easy_option_next(opt); - } -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.73.0 -.SH RETURN VALUE -A pointer to the \fIcurl_easyoption\fP struct for the next option or NULL if -no more options. -.SH "SEE ALSO" -.BR curl_easy_option_by_id (3), -.BR curl_easy_option_by_name (3), -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/curl_easy_option_next.md b/docs/libcurl/curl_easy_option_next.md new file mode 100644 index 00000000000..f5da17cfcd2 --- /dev/null +++ b/docs/libcurl/curl_easy_option_next.md @@ -0,0 +1,89 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_option_next +Section: 3 +Source: libcurl +See-also: + - curl_easy_option_by_id (3) + - curl_easy_option_by_name (3) + - curl_easy_setopt (3) +--- + +# NAME + +curl_easy_option_next - iterate over easy setopt options + +# SYNOPSIS + +~~~c +#include + +const struct curl_easyoption * +curl_easy_option_next(const struct curl_easyoption *prev); +~~~ + +# DESCRIPTION + +This function returns a pointer to the first or the next *curl_easyoption* +struct, providing an ability to iterate over all known options for +curl_easy_setopt(3) in this instance of libcurl. + +Pass a **NULL** argument as **prev** to get the first option returned, or +pass in the current option to get the next one returned. If there is no more +option to return, curl_easy_option_next(3) returns NULL. + +The options returned by this functions are the ones known to this libcurl and +information about what argument type they want. + +If the **CURLOT_FLAG_ALIAS** bit is set in the flags field, it means the +name is provided for backwards compatibility as an alias. + +# struct + +~~~c +typedef enum { + CURLOT_LONG, /* long (a range of values) */ + CURLOT_VALUES, /* (a defined set or bitmask) */ + CURLOT_OFF_T, /* curl_off_t (a range of values) */ + CURLOT_OBJECT, /* pointer (void *) */ + CURLOT_STRING, /* (char * to null-terminated buffer) */ + CURLOT_SLIST, /* (struct curl_slist *) */ + CURLOT_CBPTR, /* (void * passed as-is to a callback) */ + CURLOT_BLOB, /* blob (struct curl_blob *) */ + CURLOT_FUNCTION /* function pointer */ +} curl_easytype; + +/* The CURLOPTTYPE_* id ranges can still be used to figure out what type/size + to use for curl_easy_setopt() for the given id */ +struct curl_easyoption { + const char *name; + CURLoption id; + curl_easytype type; + unsigned int flags; +}; +~~~ + +# EXAMPLE + +~~~c +int main(void) +{ + /* iterate over all available options */ + const struct curl_easyoption *opt; + opt = curl_easy_option_next(NULL); + while(opt) { + printf("Name: %s\n", opt->name); + opt = curl_easy_option_next(opt); + } +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.73.0 + +# RETURN VALUE + +A pointer to the *curl_easyoption* struct for the next option or NULL if +no more options. diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.md similarity index 63% rename from docs/libcurl/curl_easy_pause.3 rename to docs/libcurl/curl_easy_pause.md index e5ff8827d5e..03e6b917a67 100644 --- a/docs/libcurl/curl_easy_pause.3 +++ b/docs/libcurl/curl_easy_pause.md @@ -1,84 +1,88 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_easy_pause 3 "17 Dec 2007" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_pause +Section: 3 +Source: libcurl +See-also: + - curl_easy_cleanup (3) + - curl_easy_reset (3) +--- + +# NAME + curl_easy_pause - pause and unpause a connection -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_pause(CURL *handle, int bitmask ); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Using this function, you can explicitly mark a running connection to get paused, and you can unpause a connection that was previously paused. Unlike -most other libcurl functions, \fIcurl_easy_pause(3)\fP can be used from within +most other libcurl functions, curl_easy_pause(3) can be used from within callbacks. A connection can be paused by using this function or by letting the read or the write callbacks return the proper magic return code -(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback +(*CURL_READFUNC_PAUSE* and *CURL_WRITEFUNC_PAUSE*). A write callback that returns pause signals to the library that it could not take care of any data at all, and that data is then delivered again to the callback when the transfer is unpaused. While it may feel tempting, take care and notice that you cannot call this function from another thread. To unpause, you may for example call it from the -progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP). +progress callback (CURLOPT_PROGRESSFUNCTION(3)). When this function is called to unpause receiving, the write callback might get called before this function returns to deliver cached content. When libcurl delivers such cached data to the write callback, it is delivered as fast as possible, which may overstep the boundary set in -\fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc. +CURLOPT_MAX_RECV_SPEED_LARGE(3) etc. -The \fBhandle\fP argument identifies the transfer you want to pause or +The **handle** argument identifies the transfer you want to pause or unpause. A paused transfer is excluded from low speed cancels via the -\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer resets the +CURLOPT_LOW_SPEED_LIMIT(3) option and unpausing a transfer resets the time period required for the low speed limit to be met. -The \fBbitmask\fP argument is a set of bits that sets the new state of the +The **bitmask** argument is a set of bits that sets the new state of the connection. The following bits can be used: -.IP CURLPAUSE_RECV + +## CURLPAUSE_RECV + Pause receiving data. There is no data received on this connection until this function is called again without this bit set. Thus, the write callback -(\fICURLOPT_WRITEFUNCTION(3)\fP) is not called. -.IP CURLPAUSE_SEND +(CURLOPT_WRITEFUNCTION(3)) is not called. + +## CURLPAUSE_SEND + Pause sending data. There is no data sent on this connection until this function is called again without this bit set. Thus, the read callback -(\fICURLOPT_READFUNCTION(3)\fP) is not called. -.IP CURLPAUSE_ALL +(CURLOPT_READFUNCTION(3)) is not called. + +## CURLPAUSE_ALL + Convenience define that pauses both directions. -.IP CURLPAUSE_CONT + +## CURLPAUSE_CONT + Convenience define that unpauses both directions. -.SH LIMITATIONS + +# LIMITATIONS + The pausing of transfers does not work with protocols that work without network connectivity, like FILE://. Trying to pause such a transfer, in any direction, might cause problems or error. -.SH MULTIPLEXED + +# MULTIPLEXED + When a connection is used multiplexed, like for HTTP/2, and one of the transfers over the connection is paused and the others continue flowing, libcurl might end up buffering contents for the paused transfer. It has to do @@ -90,8 +94,10 @@ buffering 32 megabyte of data for a paused stream. When such a paused stream is unpaused again, any buffered data is delivered first. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -101,8 +107,10 @@ int main(void) } } -.fi -.SH "MEMORY USE" +~~~ + +# MEMORY USE + When pausing a download transfer by returning the magic return code from a write callback, the read data is already in libcurl's internal buffers so it has to keep it in an allocated buffer until the receiving is again unpaused @@ -113,19 +121,20 @@ automatically on download, libcurl continues to uncompress the entire downloaded chunk and it caches the data uncompressed. This has the side- effect that if you download something that is compressed a lot, it can result in a large data amount needing to be allocated to save the data during the -pause. consider not using paused receiving if you allow libcurl to uncompress +pause. Consider not using paused receiving if you allow libcurl to uncompress data automatically. If the download is done with HTTP/2 or HTTP/3, there is up to a stream window size worth of data that curl cannot stop but instead needs to cache while the transfer is paused. This means that if a window size of 64 MB is used, libcurl might end up having to cache 64 MB of data. -.SH AVAILABILITY + +# AVAILABILITY + Added in 7.18.0. -.SH RETURN VALUE + +# RETURN VALUE + CURLE_OK (zero) means that the option was set properly, and a non-zero return code means something wrong occurred after the new state was set. See the -\fIlibcurl-errors(3)\fP man page for the full list with descriptions. -.SH "SEE ALSO" -.BR curl_easy_cleanup (3), -.BR curl_easy_reset (3) +libcurl-errors(3) man page for the full list with descriptions. diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3 deleted file mode 100644 index 18430771a3d..00000000000 --- a/docs/libcurl/curl_easy_perform.3 +++ /dev/null @@ -1,90 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_perform 3 "5 Mar 2001" "libcurl" "libcurl" -.SH NAME -curl_easy_perform - perform a blocking file transfer -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_perform(CURL *easy_handle); -.fi -.SH DESCRIPTION -\fIcurl_easy_perform(3)\fP performs a network transfer in a blocking manner -and returns when done, or earlier if it fails. For non-blocking behavior, see -\fIcurl_multi_perform(3)\fP. - -Invoke this function after \fIcurl_easy_init(3)\fP and all the -\fIcurl_easy_setopt(3)\fP calls are made, and it performs the transfer as -described in the options. It must be called with the same \fBeasy_handle\fP as -input as the \fIcurl_easy_init(3)\fP call returned. - -You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the -same \fBeasy_handle\fP. If you intend to transfer more than one file, you are -even encouraged to do so. libcurl attempts to reuse existing connections for -the following transfers, thus making the operations faster, less CPU intense -and using less network resources. You probably want to use -\fIcurl_easy_setopt(3)\fP between the invokes to set options for the following -\fIcurl_easy_perform(3)\fP call. - -You must never call this function simultaneously from two places using the -same \fBeasy_handle\fP. Let the function return first before invoking it -another time. If you want parallel transfers, you must use several curl -easy_handles. - -A network transfer moves data to a peer or from a peer. An application tells -libcurl how to receive data by setting the \fICURLOPT_WRITEFUNCTION(3)\fP and -\fICURLOPT_WRITEDATA(3)\fP options. To tell libcurl what data to send, there -are a few more alternatives but two common ones are -\fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_POSTFIELDS(3)\fP. - -While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by -\fIcurl_easy_perform(3)\fP. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -CURLE_OK (0) means everything was OK, non-zero means an error occurred as -.I -defines - see \fIlibcurl-errors(3)\fP. If the \fICURLOPT_ERRORBUFFER(3)\fP was -set with \fIcurl_easy_setopt(3)\fP there is a readable error message stored in -the error buffer when non-zero is returned. -.SH "SEE ALSO" -.BR curl_easy_init (3), -.BR curl_easy_setopt (3), -.BR curl_multi_add_handle (3), -.BR curl_multi_perform (3), -.BR libcurl-errors (3) diff --git a/docs/libcurl/curl_easy_perform.md b/docs/libcurl/curl_easy_perform.md new file mode 100644 index 00000000000..ff65a82ee7b --- /dev/null +++ b/docs/libcurl/curl_easy_perform.md @@ -0,0 +1,83 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_perform +Section: 3 +Source: libcurl +See-also: + - curl_easy_init (3) + - curl_easy_setopt (3) + - curl_multi_add_handle (3) + - curl_multi_perform (3) + - libcurl-errors (3) +--- + +# NAME + +curl_easy_perform - perform a blocking file transfer + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_perform(CURL *easy_handle); +~~~ + +# DESCRIPTION + +curl_easy_perform(3) performs a network transfer in a blocking manner and +returns when done, or earlier if it fails. For non-blocking behavior, see +curl_multi_perform(3). + +Invoke this function after curl_easy_init(3) and all the curl_easy_setopt(3) +calls are made, and it performs the transfer as described in the options. It +must be called with the same **easy_handle** as input as the curl_easy_init(3) +call returned. + +You can do any amount of calls to curl_easy_perform(3) while using the same +**easy_handle**. If you intend to transfer more than one file, you are even +encouraged to do so. libcurl attempts to reuse existing connections for the +following transfers, thus making the operations faster, less CPU intense and +using less network resources. You probably want to use curl_easy_setopt(3) +between the invokes to set options for the following curl_easy_perform(3) +call. + +You must never call this function simultaneously from two places using the +same **easy_handle**. Let the function return first before invoking it another +time. If you want parallel transfers, you must use several curl easy_handles. + +A network transfer moves data to a peer or from a peer. An application tells +libcurl how to receive data by setting the CURLOPT_WRITEFUNCTION(3) and +CURLOPT_WRITEDATA(3) options. To tell libcurl what data to send, there are a +few more alternatives but two common ones are CURLOPT_READFUNCTION(3) and +CURLOPT_POSTFIELDS(3). + +While the **easy_handle** is added to a multi handle, it cannot be used by +curl_easy_perform(3). + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +CURLE_OK (0) means everything was OK, non-zero means an error occurred as +** defines - see libcurl-errors(3). If the CURLOPT_ERRORBUFFER(3) +was set with curl_easy_setopt(3) there is a readable error message stored in +the error buffer when non-zero is returned. diff --git a/docs/libcurl/curl_easy_recv.3 b/docs/libcurl/curl_easy_recv.3 deleted file mode 100644 index 5238f97b6b3..00000000000 --- a/docs/libcurl/curl_easy_recv.3 +++ /dev/null @@ -1,109 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_easy_recv 3 "29 April 2008" "libcurl" "libcurl" -.SH NAME -curl_easy_recv - receives raw data on an "easy" connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n); -.fi -.SH DESCRIPTION -This function receives raw data from the established connection. You may use -it together with \fIcurl_easy_send(3)\fP to implement custom protocols using -libcurl. This functionality can be particularly useful if you use proxies -and/or SSL encryption: libcurl takes care of proxy negotiation and connection -setup. - -\fBbuffer\fP is a pointer to your buffer memory that gets populated by the -received data. \fBbuflen\fP is the maximum amount of data you can get in that -buffer. The variable \fBn\fP points to receives the number of received bytes. - -To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before -calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that -\fIcurl_easy_recv(3)\fP does not work on connections that were created without -this option. - -The call returns \fBCURLE_AGAIN\fP if there is no data to read - the socket is -used in non-blocking mode internally. When \fBCURLE_AGAIN\fP is returned, use -your operating system facilities like \fIselect(2)\fP to wait for data. The -socket may be obtained using \fIcurl_easy_getinfo(3)\fP with -\fICURLINFO_ACTIVESOCKET(3)\fP. - -Wait on the socket only if \fIcurl_easy_recv(3)\fP returns \fBCURLE_AGAIN\fP. -The reason for this is libcurl or the SSL library may internally cache some -data, therefore you should call \fIcurl_easy_recv(3)\fP until all data is -read which would include any cached data. - -Furthermore if you wait on the socket and it tells you there is data to read, -\fIcurl_easy_recv(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was -read was for internal SSL processing, and no other data is available. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* Do not do the transfer - only connect to host */ - curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); - res = curl_easy_perform(curl); - - if(res == CURLE_OK) { - char buf[256]; - size_t nread; - long sockfd; - - /* Extract the socket from the curl handle - we need it for waiting. */ - res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); - - /* read data */ - res = curl_easy_recv(curl, buf, sizeof(buf), &nread); - } - } -} -.fi -.SH AVAILABILITY -Added in 7.18.2. -.SH RETURN VALUE -On success, returns \fBCURLE_OK\fP, stores the received data into -\fBbuffer\fP, and the number of bytes it actually read into \fB*n\fP. - -On failure, returns the appropriate error code. - -The function may return \fBCURLE_AGAIN\fP. In this case, use your operating -system facilities to wait until data can be read, and retry. - -Reading exactly 0 bytes indicates a closed connection. - -If there is no socket available to use from the previous transfer, this function -returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_perform (3), -.BR curl_easy_send (3), -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/curl_easy_recv.md b/docs/libcurl/curl_easy_recv.md new file mode 100644 index 00000000000..df210f71af2 --- /dev/null +++ b/docs/libcurl/curl_easy_recv.md @@ -0,0 +1,103 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_recv +Section: 3 +Source: libcurl +See-also: + - curl_easy_getinfo (3) + - curl_easy_perform (3) + - curl_easy_send (3) + - curl_easy_setopt (3) +--- + +# NAME + +curl_easy_recv - receives raw data on an "easy" connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n); +~~~ + +# DESCRIPTION + +This function receives raw data from the established connection. You may use +it together with curl_easy_send(3) to implement custom protocols using +libcurl. This functionality can be particularly useful if you use proxies +and/or SSL encryption: libcurl takes care of proxy negotiation and connection +setup. + +**buffer** is a pointer to your buffer memory that gets populated by the +received data. **buflen** is the maximum amount of data you can get in that +buffer. The variable **n** points to receives the number of received bytes. + +To establish the connection, set CURLOPT_CONNECT_ONLY(3) option before +calling curl_easy_perform(3) or curl_multi_perform(3). Note that +curl_easy_recv(3) does not work on connections that were created without +this option. + +The call returns **CURLE_AGAIN** if there is no data to read - the socket is +used in non-blocking mode internally. When **CURLE_AGAIN** is returned, use +your operating system facilities like *select(2)* to wait for data. The +socket may be obtained using curl_easy_getinfo(3) with +CURLINFO_ACTIVESOCKET(3). + +Wait on the socket only if curl_easy_recv(3) returns **CURLE_AGAIN**. +The reason for this is libcurl or the SSL library may internally cache some +data, therefore you should call curl_easy_recv(3) until all data is +read which would include any cached data. + +Furthermore if you wait on the socket and it tells you there is data to read, +curl_easy_recv(3) may return **CURLE_AGAIN** if the only data that was +read was for internal SSL processing, and no other data is available. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* Do not do the transfer - only connect to host */ + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + res = curl_easy_perform(curl); + + if(res == CURLE_OK) { + char buf[256]; + size_t nread; + long sockfd; + + /* Extract the socket from the curl handle - we need it for waiting. */ + res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); + + /* read data */ + res = curl_easy_recv(curl, buf, sizeof(buf), &nread); + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.18.2. + +# RETURN VALUE + +On success, returns **CURLE_OK**, stores the received data into +**buffer**, and the number of bytes it actually read into ***n**. + +On failure, returns the appropriate error code. + +The function may return **CURLE_AGAIN**. In this case, use your operating +system facilities to wait until data can be read, and retry. + +Reading exactly 0 bytes indicates a closed connection. + +If there is no socket available to use from the previous transfer, this function +returns **CURLE_UNSUPPORTED_PROTOCOL**. diff --git a/docs/libcurl/curl_easy_reset.3 b/docs/libcurl/curl_easy_reset.3 deleted file mode 100644 index 5fa9b13b354..00000000000 --- a/docs/libcurl/curl_easy_reset.3 +++ /dev/null @@ -1,61 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_reset 3 "31 July 2004" "libcurl" "libcurl" -.SH NAME -curl_easy_reset - reset all options of a libcurl session handle -.SH SYNOPSIS -.nf -#include - -void curl_easy_reset(CURL *handle); -.fi -.SH DESCRIPTION -Re-initializes all options previously set on a specified CURL handle to the -default values. This puts back the handle to the same state as it was in when -it was just created with \fIcurl_easy_init(3)\fP. - -It does not change the following information kept in the handle: live -connections, the Session ID cache, the DNS cache, the cookies, the shares or -the alt-svc cache. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - - /* ... the handle is used and options are set ... */ - curl_easy_reset(curl); - } -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.12.1 -.SH RETURN VALUE -Nothing -.SH "SEE ALSO" -.BR curl_easy_cleanup (3), -.BR curl_easy_duphandle (3), -.BR curl_easy_init (3), -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/curl_easy_reset.md b/docs/libcurl/curl_easy_reset.md new file mode 100644 index 00000000000..c2aea6e10b2 --- /dev/null +++ b/docs/libcurl/curl_easy_reset.md @@ -0,0 +1,56 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_reset +Section: 3 +Source: libcurl +See-also: + - curl_easy_cleanup (3) + - curl_easy_duphandle (3) + - curl_easy_init (3) + - curl_easy_setopt (3) +--- + +# NAME + +curl_easy_reset - reset all options of a libcurl session handle + +# SYNOPSIS + +~~~c +#include + +void curl_easy_reset(CURL *handle); +~~~ + +# DESCRIPTION + +Re-initializes all options previously set on a specified CURL handle to the +default values. This puts back the handle to the same state as it was in when +it was just created with curl_easy_init(3). + +It does not change the following information kept in the handle: live +connections, the Session ID cache, the DNS cache, the cookies, the shares or +the alt-svc cache. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + + /* ... the handle is used and options are set ... */ + curl_easy_reset(curl); + } +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.12.1 + +# RETURN VALUE + +Nothing diff --git a/docs/libcurl/curl_easy_send.3 b/docs/libcurl/curl_easy_send.3 deleted file mode 100644 index 820029ec055..00000000000 --- a/docs/libcurl/curl_easy_send.3 +++ /dev/null @@ -1,101 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_easy_send 3 "29 April 2008" "libcurl" "libcurl" -.SH NAME -curl_easy_send - sends raw data over an "easy" connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_send(CURL *curl, const void *buffer, - size_t buflen, size_t *n); -.fi -.SH DESCRIPTION -This function sends arbitrary data over the established connection. You may -use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols -using libcurl. This functionality can be particularly useful if you use -proxies and/or SSL encryption: libcurl takes care of proxy negotiation and -connection setup. - -\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want -sent. The variable \fBn\fP points to receives the number of sent bytes. - -To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before -calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that -\fIcurl_easy_send(3)\fP does not work on connections that were created without -this option. - -The call returns \fBCURLE_AGAIN\fP if it's not possible to send data right now -- the socket is used in non-blocking mode internally. When \fBCURLE_AGAIN\fP -is returned, use your operating system facilities like \fIselect(2)\fP to wait -until the socket is writable. The socket may be obtained using -\fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP. - -Furthermore if you wait on the socket and it tells you it's writable, -\fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was -sent was for internal SSL processing, and no other data could be sent. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* Do not do the transfer - only connect to host */ - curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); - res = curl_easy_perform(curl); - - if(res == CURLE_OK) { - long sockfd; - size_t sent; - /* Extract the socket from the curl handle - we need it for waiting. */ - res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); - - /* send data */ - res = curl_easy_send(curl, "hello", 5, &sent); - } - } -} -.fi -.SH AVAILABILITY -Added in 7.18.2. -.SH RETURN VALUE -On success, returns \fBCURLE_OK\fP and stores the number of bytes actually -sent into \fB*n\fP. Note that this may be less than the amount you wanted to -send. - -On failure, returns the appropriate error code. - -This function may return \fBCURLE_AGAIN\fP. In this case, use your operating -system facilities to wait until the socket is writable, and retry. - -If there is no socket available to use from the previous transfer, this function -returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP. -.SH "SEE ALSO" -.BR curl_easy_setopt (3), -.BR curl_easy_perform (3), -.BR curl_easy_getinfo (3), -.BR curl_easy_recv (3) diff --git a/docs/libcurl/curl_easy_send.md b/docs/libcurl/curl_easy_send.md new file mode 100644 index 00000000000..d9459284565 --- /dev/null +++ b/docs/libcurl/curl_easy_send.md @@ -0,0 +1,95 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_send +Section: 3 +Source: libcurl +See-also: + - curl_easy_getinfo (3) + - curl_easy_perform (3) + - curl_easy_recv (3) + - curl_easy_setopt (3) +--- + +# NAME + +curl_easy_send - sends raw data over an "easy" connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_send(CURL *curl, const void *buffer, + size_t buflen, size_t *n); +~~~ + +# DESCRIPTION + +This function sends arbitrary data over the established connection. You may +use it together with curl_easy_recv(3) to implement custom protocols +using libcurl. This functionality can be particularly useful if you use +proxies and/or SSL encryption: libcurl takes care of proxy negotiation and +connection setup. + +**buffer** is a pointer to the data of length **buflen** that you want +sent. The variable **n** points to receives the number of sent bytes. + +To establish the connection, set CURLOPT_CONNECT_ONLY(3) option before +calling curl_easy_perform(3) or curl_multi_perform(3). Note that +curl_easy_send(3) does not work on connections that were created without +this option. + +The call returns **CURLE_AGAIN** if it's not possible to send data right now +- the socket is used in non-blocking mode internally. When **CURLE_AGAIN** +is returned, use your operating system facilities like *select(2)* to wait +until the socket is writable. The socket may be obtained using +curl_easy_getinfo(3) with CURLINFO_ACTIVESOCKET(3). + +Furthermore if you wait on the socket and it tells you it's writable, +curl_easy_send(3) may return **CURLE_AGAIN** if the only data that was +sent was for internal SSL processing, and no other data could be sent. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* Do not do the transfer - only connect to host */ + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + res = curl_easy_perform(curl); + + if(res == CURLE_OK) { + long sockfd; + size_t sent; + /* Extract the socket from the curl handle - we need it for waiting. */ + res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); + + /* send data */ + res = curl_easy_send(curl, "hello", 5, &sent); + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.18.2. + +# RETURN VALUE + +On success, returns **CURLE_OK** and stores the number of bytes actually +sent into ***n**. Note that this may be less than the amount you wanted to +send. + +On failure, returns the appropriate error code. + +This function may return **CURLE_AGAIN**. In this case, use your operating +system facilities to wait until the socket is writable, and retry. + +If there is no socket available to use from the previous transfer, this function +returns **CURLE_UNSUPPORTED_PROTOCOL**. diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 deleted file mode 100644 index d4a5dcb5c00..00000000000 --- a/docs/libcurl/curl_easy_setopt.3 +++ /dev/null @@ -1,751 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_easy_setopt 3 "25 Jun 2014" "libcurl" "libcurl" -.SH NAME -curl_easy_setopt \- set options for a curl easy handle -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); -.fi -.SH DESCRIPTION -\fIcurl_easy_setopt(3)\fP is used to tell libcurl how to behave. By setting -the appropriate options, the application can change libcurl's behavior. All -options are set with an \fIoption\fP followed by a \fIparameter\fP. That -parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject -pointer\fP or a \fBcurl_off_t\fP, depending on what the specific option -expects. Read this manual carefully as bad input values may cause libcurl to -behave badly! You can only set one option in each function call. A typical -application uses many \fIcurl_easy_setopt(3)\fP calls in the setup phase. - -Options set with this function call are valid for all forthcoming transfers -performed using this \fIhandle\fP. The options are not in any way reset -between transfers, so if you want subsequent transfers with different options, -you must change them between the transfers. You can optionally reset all -options back to internal default with \fIcurl_easy_reset(3)\fP. - -Strings passed to libcurl as 'char *' arguments, are copied by the library; -the string storage associated to the pointer argument may be discarded or -reused after \fIcurl_easy_setopt(3)\fP returns. The only exception to this -rule is really \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies -the string \fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you -need to read up on. This function does not accept input strings longer than -\fBCURL_MAX_INPUT_LENGTH\fP (8 MB). - -The order in which the options are set does not matter. - -Before version 7.17.0, strings were not copied. Instead the user was forced -keep them available until libcurl no longer needed them. - -The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or -\fIcurl_easy_duphandle(3)\fP call. -.SH BEHAVIOR OPTIONS -.IP CURLOPT_VERBOSE -Display verbose information. See \fICURLOPT_VERBOSE(3)\fP -.IP CURLOPT_HEADER -Include the header in the body output. See \fICURLOPT_HEADER(3)\fP -.IP CURLOPT_NOPROGRESS -Shut off the progress meter. See \fICURLOPT_NOPROGRESS(3)\fP -.IP CURLOPT_NOSIGNAL -Do not install signal handlers. See \fICURLOPT_NOSIGNAL(3)\fP -.IP CURLOPT_WILDCARDMATCH -Transfer multiple files according to a file name pattern. See \fICURLOPT_WILDCARDMATCH(3)\fP -.SH CALLBACK OPTIONS -.IP CURLOPT_WRITEFUNCTION -Callback for writing data. See \fICURLOPT_WRITEFUNCTION(3)\fP -.IP CURLOPT_WRITEDATA -Data pointer to pass to the write callback. See \fICURLOPT_WRITEDATA(3)\fP -.IP CURLOPT_READFUNCTION -Callback for reading data. See \fICURLOPT_READFUNCTION(3)\fP -.IP CURLOPT_READDATA -Data pointer to pass to the read callback. See \fICURLOPT_READDATA(3)\fP -.IP CURLOPT_IOCTLFUNCTION -\fBDeprecated option\fP Callback for I/O operations. -See \fICURLOPT_IOCTLFUNCTION(3)\fP -.IP CURLOPT_IOCTLDATA -\fBDeprecated option\fP Data pointer to pass to the I/O callback. -See \fICURLOPT_IOCTLDATA(3)\fP -.IP CURLOPT_SEEKFUNCTION -Callback for seek operations. See \fICURLOPT_SEEKFUNCTION(3)\fP -.IP CURLOPT_SEEKDATA -Data pointer to pass to the seek callback. See \fICURLOPT_SEEKDATA(3)\fP -.IP CURLOPT_SOCKOPTFUNCTION -Callback for sockopt operations. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP -.IP CURLOPT_SOCKOPTDATA -Data pointer to pass to the sockopt callback. See \fICURLOPT_SOCKOPTDATA(3)\fP -.IP CURLOPT_OPENSOCKETFUNCTION -Callback for socket creation. See \fICURLOPT_OPENSOCKETFUNCTION(3)\fP -.IP CURLOPT_OPENSOCKETDATA -Data pointer to pass to the open socket callback. See \fICURLOPT_OPENSOCKETDATA(3)\fP -.IP CURLOPT_CLOSESOCKETFUNCTION -Callback for closing socket. See \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP -.IP CURLOPT_CLOSESOCKETDATA -Data pointer to pass to the close socket callback. See \fICURLOPT_CLOSESOCKETDATA(3)\fP -.IP CURLOPT_PROGRESSFUNCTION -\fBOBSOLETE\fP callback for progress meter. -See \fICURLOPT_PROGRESSFUNCTION(3)\fP -.IP CURLOPT_PROGRESSDATA -Data pointer to pass to the progress meter callback. See \fICURLOPT_PROGRESSDATA(3)\fP -.IP CURLOPT_XFERINFOFUNCTION -Callback for progress meter. See \fICURLOPT_XFERINFOFUNCTION(3)\fP -.IP CURLOPT_XFERINFODATA -Data pointer to pass to the progress meter callback. See \fICURLOPT_XFERINFODATA(3)\fP -.IP CURLOPT_HEADERFUNCTION -Callback for writing received headers. See \fICURLOPT_HEADERFUNCTION(3)\fP -.IP CURLOPT_HEADERDATA -Data pointer to pass to the header callback. See \fICURLOPT_HEADERDATA(3)\fP -.IP CURLOPT_DEBUGFUNCTION -Callback for debug information. See \fICURLOPT_DEBUGFUNCTION(3)\fP -.IP CURLOPT_DEBUGDATA -Data pointer to pass to the debug callback. See \fICURLOPT_DEBUGDATA(3)\fP -.IP CURLOPT_SSL_CTX_FUNCTION -Callback for SSL context logic. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP -.IP CURLOPT_SSL_CTX_DATA -Data pointer to pass to the SSL context callback. See \fICURLOPT_SSL_CTX_DATA(3)\fP -.IP CURLOPT_CONV_TO_NETWORK_FUNCTION -\fBOBSOLETE\fP Callback for code base conversion. -See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP -.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION -\fBOBSOLETE\fP Callback for code base conversion. -See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP -.IP CURLOPT_CONV_FROM_UTF8_FUNCTION -\fBOBSOLETE\fP Callback for code base conversion. -See \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP -.IP CURLOPT_INTERLEAVEFUNCTION -Callback for RTSP interleaved data. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP -.IP CURLOPT_INTERLEAVEDATA -Data pointer to pass to the RTSP interleave callback. See \fICURLOPT_INTERLEAVEDATA(3)\fP -.IP CURLOPT_CHUNK_BGN_FUNCTION -Callback for wildcard download start of chunk. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP -.IP CURLOPT_CHUNK_END_FUNCTION -Callback for wildcard download end of chunk. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP -.IP CURLOPT_CHUNK_DATA -Data pointer to pass to the chunk callbacks. See \fICURLOPT_CHUNK_DATA(3)\fP -.IP CURLOPT_FNMATCH_FUNCTION -Callback for wildcard matching. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP -.IP CURLOPT_FNMATCH_DATA -Data pointer to pass to the wildcard matching callback. See \fICURLOPT_FNMATCH_DATA(3)\fP -.IP CURLOPT_SUPPRESS_CONNECT_HEADERS -Suppress proxy CONNECT response headers from user callbacks. See \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP -.IP CURLOPT_RESOLVER_START_FUNCTION -Callback to be called before a new resolve request is started. See \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP -.IP CURLOPT_RESOLVER_START_DATA -Data pointer to pass to resolver start callback. See \fICURLOPT_RESOLVER_START_DATA(3)\fP -.IP CURLOPT_PREREQFUNCTION -Callback to be called after a connection is established but before a request is made on that connection. See \fICURLOPT_PREREQFUNCTION(3)\fP -.IP CURLOPT_PREREQDATA -Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See \fICURLOPT_PREREQDATA(3)\fP -.SH ERROR OPTIONS -.IP CURLOPT_ERRORBUFFER -Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP -.IP CURLOPT_STDERR -stderr replacement stream. See \fICURLOPT_STDERR(3)\fP -.IP CURLOPT_FAILONERROR -Fail on HTTP 4xx errors. \fICURLOPT_FAILONERROR(3)\fP -.IP CURLOPT_KEEP_SENDING_ON_ERROR -Keep sending on HTTP >= 300 errors. \fICURLOPT_KEEP_SENDING_ON_ERROR(3)\fP -.SH NETWORK OPTIONS -.IP CURLOPT_URL -URL to work on. See \fICURLOPT_URL(3)\fP -.IP CURLOPT_PATH_AS_IS -Disable squashing /../ and /./ sequences in the path. See \fICURLOPT_PATH_AS_IS(3)\fP -.IP CURLOPT_PROTOCOLS -\fBDeprecated option\fP Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP -.IP CURLOPT_PROTOCOLS_STR -Allowed protocols. See \fICURLOPT_PROTOCOLS_STR(3)\fP -.IP CURLOPT_REDIR_PROTOCOLS -\fBDeprecated option\fP Protocols to allow redirects to. See -\fICURLOPT_REDIR_PROTOCOLS(3)\fP -.IP CURLOPT_REDIR_PROTOCOLS_STR -Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP -.IP CURLOPT_DEFAULT_PROTOCOL -Default protocol. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP -.IP CURLOPT_PROXY -Proxy to use. See \fICURLOPT_PROXY(3)\fP -.IP CURLOPT_PRE_PROXY -Socks proxy to use. See \fICURLOPT_PRE_PROXY(3)\fP -.IP CURLOPT_PROXYPORT -Proxy port to use. See \fICURLOPT_PROXYPORT(3)\fP -.IP CURLOPT_PROXYTYPE -Proxy type. See \fICURLOPT_PROXYTYPE(3)\fP -.IP CURLOPT_NOPROXY -Filter out hosts from proxy use. \fICURLOPT_NOPROXY(3)\fP -.IP CURLOPT_HTTPPROXYTUNNEL -Tunnel through the HTTP proxy. \fICURLOPT_HTTPPROXYTUNNEL(3)\fP -.IP CURLOPT_CONNECT_TO -Connect to a specific host and port. See \fICURLOPT_CONNECT_TO(3)\fP -.IP CURLOPT_SOCKS5_AUTH -Socks5 authentication methods. See \fICURLOPT_SOCKS5_AUTH(3)\fP -.IP CURLOPT_SOCKS5_GSSAPI_SERVICE -\fBDeprecated option\fP Socks5 GSSAPI service name. -See \fICURLOPT_SOCKS5_GSSAPI_SERVICE(3)\fP -.IP CURLOPT_SOCKS5_GSSAPI_NEC -Socks5 GSSAPI NEC mode. See \fICURLOPT_SOCKS5_GSSAPI_NEC(3)\fP -.IP CURLOPT_PROXY_SERVICE_NAME -Proxy authentication service name. \fICURLOPT_PROXY_SERVICE_NAME(3)\fP -.IP CURLOPT_HAPROXYPROTOCOL -Send an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXYPROTOCOL(3)\fP -.IP CURLOPT_HAPROXY_CLIENT_IP -Spoof the client IP in an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXY_CLIENT_IP(3)\fP -.IP CURLOPT_SERVICE_NAME -Authentication service name. \fICURLOPT_SERVICE_NAME(3)\fP -.IP CURLOPT_INTERFACE -Bind connection locally to this. See \fICURLOPT_INTERFACE(3)\fP -.IP CURLOPT_LOCALPORT -Bind connection locally to this port. See \fICURLOPT_LOCALPORT(3)\fP -.IP CURLOPT_LOCALPORTRANGE -Bind connection locally to port range. See \fICURLOPT_LOCALPORTRANGE(3)\fP -.IP CURLOPT_DNS_CACHE_TIMEOUT -Timeout for DNS cache. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP -.IP CURLOPT_DNS_USE_GLOBAL_CACHE -\fBOBSOLETE\fP Enable global DNS cache. -See \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP -.IP CURLOPT_DOH_URL -Use this DoH server for name resolves. See \fICURLOPT_DOH_URL(3)\fP -.IP CURLOPT_BUFFERSIZE -Ask for alternate buffer size. See \fICURLOPT_BUFFERSIZE(3)\fP -.IP CURLOPT_PORT -Port number to connect to. See \fICURLOPT_PORT(3)\fP -.IP CURLOPT_TCP_FASTOPEN -Enable TCP Fast Open. See \fICURLOPT_TCP_FASTOPEN(3)\fP -.IP CURLOPT_TCP_NODELAY -Disable the Nagle algorithm. See \fICURLOPT_TCP_NODELAY(3)\fP -.IP CURLOPT_ADDRESS_SCOPE -IPv6 scope for local addresses. See \fICURLOPT_ADDRESS_SCOPE(3)\fP -.IP CURLOPT_TCP_KEEPALIVE -Enable TCP keep-alive. See \fICURLOPT_TCP_KEEPALIVE(3)\fP -.IP CURLOPT_TCP_KEEPIDLE -Idle time before sending keep-alive. See \fICURLOPT_TCP_KEEPIDLE(3)\fP -.IP CURLOPT_TCP_KEEPINTVL -Interval between keep-alive probes. See \fICURLOPT_TCP_KEEPINTVL(3)\fP -.IP CURLOPT_UNIX_SOCKET_PATH -Path to a Unix domain socket. See \fICURLOPT_UNIX_SOCKET_PATH(3)\fP -.IP CURLOPT_ABSTRACT_UNIX_SOCKET -Path to an abstract Unix domain socket. See \fICURLOPT_ABSTRACT_UNIX_SOCKET(3)\fP -.SH NAMES and PASSWORDS OPTIONS (Authentication) -.IP CURLOPT_NETRC -Enable .netrc parsing. See \fICURLOPT_NETRC(3)\fP -.IP CURLOPT_NETRC_FILE -\&.netrc file name. See \fICURLOPT_NETRC_FILE(3)\fP -.IP CURLOPT_USERPWD -User name and password. See \fICURLOPT_USERPWD(3)\fP -.IP CURLOPT_PROXYUSERPWD -Proxy user name and password. See \fICURLOPT_PROXYUSERPWD(3)\fP -.IP CURLOPT_USERNAME -User name. See \fICURLOPT_USERNAME(3)\fP -.IP CURLOPT_PASSWORD -Password. See \fICURLOPT_PASSWORD(3)\fP -.IP CURLOPT_LOGIN_OPTIONS -Login options. See \fICURLOPT_LOGIN_OPTIONS(3)\fP -.IP CURLOPT_PROXYUSERNAME -Proxy user name. See \fICURLOPT_PROXYUSERNAME(3)\fP -.IP CURLOPT_PROXYPASSWORD -Proxy password. See \fICURLOPT_PROXYPASSWORD(3)\fP -.IP CURLOPT_HTTPAUTH -HTTP server authentication methods. See \fICURLOPT_HTTPAUTH(3)\fP -.IP CURLOPT_TLSAUTH_USERNAME -TLS authentication user name. See \fICURLOPT_TLSAUTH_USERNAME(3)\fP -.IP CURLOPT_PROXY_TLSAUTH_USERNAME -Proxy TLS authentication user name. See \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP -.IP CURLOPT_TLSAUTH_PASSWORD -TLS authentication password. See \fICURLOPT_TLSAUTH_PASSWORD(3)\fP -.IP CURLOPT_PROXY_TLSAUTH_PASSWORD -Proxy TLS authentication password. See \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP -.IP CURLOPT_TLSAUTH_TYPE -TLS authentication methods. See \fICURLOPT_TLSAUTH_TYPE(3)\fP -.IP CURLOPT_PROXY_TLSAUTH_TYPE -Proxy TLS authentication methods. See \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP -.IP CURLOPT_PROXYAUTH -HTTP proxy authentication methods. See \fICURLOPT_PROXYAUTH(3)\fP -.IP CURLOPT_SASL_AUTHZID -SASL authorization identity (identity to act as). See \fICURLOPT_SASL_AUTHZID(3)\fP -.IP CURLOPT_SASL_IR -Enable SASL initial response. See \fICURLOPT_SASL_IR(3)\fP -.IP CURLOPT_XOAUTH2_BEARER -OAuth2 bearer token. See \fICURLOPT_XOAUTH2_BEARER(3)\fP -.IP CURLOPT_DISALLOW_USERNAME_IN_URL -Do not allow username in URL. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP -.SH HTTP OPTIONS -.IP CURLOPT_AUTOREFERER -Automatically set Referer: header. See \fICURLOPT_AUTOREFERER(3)\fP -.IP CURLOPT_ACCEPT_ENCODING -Accept-Encoding and automatic decompressing data. See \fICURLOPT_ACCEPT_ENCODING(3)\fP -.IP CURLOPT_TRANSFER_ENCODING -Request Transfer-Encoding. See \fICURLOPT_TRANSFER_ENCODING(3)\fP -.IP CURLOPT_FOLLOWLOCATION -Follow HTTP redirects. See \fICURLOPT_FOLLOWLOCATION(3)\fP -.IP CURLOPT_UNRESTRICTED_AUTH -Do not restrict authentication to original host. \fICURLOPT_UNRESTRICTED_AUTH(3)\fP -.IP CURLOPT_MAXREDIRS -Maximum number of redirects to follow. See \fICURLOPT_MAXREDIRS(3)\fP -.IP CURLOPT_POSTREDIR -How to act on redirects after POST. See \fICURLOPT_POSTREDIR(3)\fP -.IP CURLOPT_PUT -\fBDeprecated option\fP Issue an HTTP PUT request. See \fICURLOPT_PUT(3)\fP -.IP CURLOPT_POST -Issue an HTTP POST request. See \fICURLOPT_POST(3)\fP -.IP CURLOPT_POSTFIELDS -Send a POST with this data. See \fICURLOPT_POSTFIELDS(3)\fP -.IP CURLOPT_POSTFIELDSIZE -The POST data is this big. See \fICURLOPT_POSTFIELDSIZE(3)\fP -.IP CURLOPT_POSTFIELDSIZE_LARGE -The POST data is this big. See \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP -.IP CURLOPT_COPYPOSTFIELDS -Send a POST with this data - and copy it. See \fICURLOPT_COPYPOSTFIELDS(3)\fP -.IP CURLOPT_HTTPPOST -\fBDeprecated option\fP Multipart formpost HTTP POST. -See \fICURLOPT_HTTPPOST(3)\fP -.IP CURLOPT_REFERER -Referer: header. See \fICURLOPT_REFERER(3)\fP -.IP CURLOPT_USERAGENT -User-Agent: header. See \fICURLOPT_USERAGENT(3)\fP -.IP CURLOPT_HTTPHEADER -Custom HTTP headers. See \fICURLOPT_HTTPHEADER(3)\fP -.IP CURLOPT_HEADEROPT -Control custom headers. See \fICURLOPT_HEADEROPT(3)\fP -.IP CURLOPT_PROXYHEADER -Custom HTTP headers sent to proxy. See \fICURLOPT_PROXYHEADER(3)\fP -.IP CURLOPT_HTTP200ALIASES -Alternative versions of 200 OK. See \fICURLOPT_HTTP200ALIASES(3)\fP -.IP CURLOPT_COOKIE -Cookie(s) to send. See \fICURLOPT_COOKIE(3)\fP -.IP CURLOPT_COOKIEFILE -File to read cookies from. See \fICURLOPT_COOKIEFILE(3)\fP -.IP CURLOPT_COOKIEJAR -File to write cookies to. See \fICURLOPT_COOKIEJAR(3)\fP -.IP CURLOPT_COOKIESESSION -Start a new cookie session. See \fICURLOPT_COOKIESESSION(3)\fP -.IP CURLOPT_COOKIELIST -Add or control cookies. See \fICURLOPT_COOKIELIST(3)\fP -.IP CURLOPT_ALTSVC -Specify the Alt-Svc: cache file name. See \fICURLOPT_ALTSVC(3)\fP -.IP CURLOPT_ALTSVC_CTRL -Enable and configure Alt-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP -.IP CURLOPT_HSTS -Set HSTS cache file. See \fICURLOPT_HSTS(3)\fP -.IP CURLOPT_HSTS_CTRL -Enable HSTS. See \fICURLOPT_HSTS_CTRL(3)\fP -.IP CURLOPT_HSTSREADFUNCTION -Set HSTS read callback. See \fICURLOPT_HSTSREADFUNCTION(3)\fP -.IP CURLOPT_HSTSREADDATA -Pass pointer to the HSTS read callback. See \fICURLOPT_HSTSREADDATA(3)\fP -.IP CURLOPT_HSTSWRITEFUNCTION -Set HSTS write callback. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP -.IP CURLOPT_HSTSWRITEDATA -Pass pointer to the HSTS write callback. See \fICURLOPT_HSTSWRITEDATA(3)\fP -.IP CURLOPT_HTTPGET -Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP -.IP CURLOPT_REQUEST_TARGET -Set the request target. \fICURLOPT_REQUEST_TARGET(3)\fP -.IP CURLOPT_HTTP_VERSION -HTTP version to use. \fICURLOPT_HTTP_VERSION(3)\fP -.IP CURLOPT_HTTP09_ALLOWED -Allow HTTP/0.9 responses. \fICURLOPT_HTTP09_ALLOWED(3)\fP -.IP CURLOPT_IGNORE_CONTENT_LENGTH -Ignore Content-Length. See \fICURLOPT_IGNORE_CONTENT_LENGTH(3)\fP -.IP CURLOPT_HTTP_CONTENT_DECODING -Disable Content decoding. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP -.IP CURLOPT_HTTP_TRANSFER_DECODING -Disable Transfer decoding. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP -.IP CURLOPT_EXPECT_100_TIMEOUT_MS -100-continue timeout. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP -.IP CURLOPT_TRAILERFUNCTION -Set callback for sending trailing headers. See -\fICURLOPT_TRAILERFUNCTION(3)\fP -.IP CURLOPT_TRAILERDATA -Custom pointer passed to the trailing headers callback. See -\fICURLOPT_TRAILERDATA(3)\fP -.IP CURLOPT_PIPEWAIT -Wait on connection to pipeline on it. See \fICURLOPT_PIPEWAIT(3)\fP -.IP CURLOPT_STREAM_DEPENDS -This HTTP/2 stream depends on another. See \fICURLOPT_STREAM_DEPENDS(3)\fP -.IP CURLOPT_STREAM_DEPENDS_E -This HTTP/2 stream depends on another exclusively. See -\fICURLOPT_STREAM_DEPENDS_E(3)\fP -.IP CURLOPT_STREAM_WEIGHT -Set this HTTP/2 stream's weight. See \fICURLOPT_STREAM_WEIGHT(3)\fP -.SH SMTP OPTIONS -.IP CURLOPT_MAIL_FROM -Address of the sender. See \fICURLOPT_MAIL_FROM(3)\fP -.IP CURLOPT_MAIL_RCPT -Address of the recipients. See \fICURLOPT_MAIL_RCPT(3)\fP -.IP CURLOPT_MAIL_AUTH -Authentication address. See \fICURLOPT_MAIL_AUTH(3)\fP -.IP CURLOPT_MAIL_RCPT_ALLOWFAILS -Allow RCPT TO command to fail for some recipients. See -\fICURLOPT_MAIL_RCPT_ALLOWFAILS(3)\fP -.SH TFTP OPTIONS -.IP CURLOPT_TFTP_BLKSIZE -TFTP block size. See \fICURLOPT_TFTP_BLKSIZE(3)\fP -.IP CURLOPT_TFTP_NO_OPTIONS -Do not send TFTP options requests. See \fICURLOPT_TFTP_NO_OPTIONS(3)\fP -.SH FTP OPTIONS -.IP CURLOPT_FTPPORT -Use active FTP. See \fICURLOPT_FTPPORT(3)\fP -.IP CURLOPT_QUOTE -Commands to run before transfer. See \fICURLOPT_QUOTE(3)\fP -.IP CURLOPT_POSTQUOTE -Commands to run after transfer. See \fICURLOPT_POSTQUOTE(3)\fP -.IP CURLOPT_PREQUOTE -Commands to run just before transfer. See \fICURLOPT_PREQUOTE(3)\fP -.IP CURLOPT_APPEND -Append to remote file. See \fICURLOPT_APPEND(3)\fP -.IP CURLOPT_FTP_USE_EPRT -Use EPRT. See \fICURLOPT_FTP_USE_EPRT(3)\fP -.IP CURLOPT_FTP_USE_EPSV -Use EPSV. See \fICURLOPT_FTP_USE_EPSV(3)\fP -.IP CURLOPT_FTP_USE_PRET -Use PRET. See \fICURLOPT_FTP_USE_PRET(3)\fP -.IP CURLOPT_FTP_CREATE_MISSING_DIRS -Create missing directories on the remote server. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP -.IP CURLOPT_SERVER_RESPONSE_TIMEOUT -Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP -.IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS -Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP -.IP CURLOPT_FTP_ALTERNATIVE_TO_USER -Alternative to USER. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP -.IP CURLOPT_FTP_SKIP_PASV_IP -Ignore the IP address in the PASV response. See \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP -.IP CURLOPT_FTPSSLAUTH -Control how to do TLS. See \fICURLOPT_FTPSSLAUTH(3)\fP -.IP CURLOPT_FTP_SSL_CCC -Back to non-TLS again after authentication. See \fICURLOPT_FTP_SSL_CCC(3)\fP -.IP CURLOPT_FTP_ACCOUNT -Send ACCT command. See \fICURLOPT_FTP_ACCOUNT(3)\fP -.IP CURLOPT_FTP_FILEMETHOD -Specify how to reach files. See \fICURLOPT_FTP_FILEMETHOD(3)\fP -.SH RTSP OPTIONS -.IP CURLOPT_RTSP_REQUEST -RTSP request. See \fICURLOPT_RTSP_REQUEST(3)\fP -.IP CURLOPT_RTSP_SESSION_ID -RTSP session-id. See \fICURLOPT_RTSP_SESSION_ID(3)\fP -.IP CURLOPT_RTSP_STREAM_URI -RTSP stream URI. See \fICURLOPT_RTSP_STREAM_URI(3)\fP -.IP CURLOPT_RTSP_TRANSPORT -RTSP Transport: header. See \fICURLOPT_RTSP_TRANSPORT(3)\fP -.IP CURLOPT_RTSP_CLIENT_CSEQ -Client CSEQ number. See \fICURLOPT_RTSP_CLIENT_CSEQ(3)\fP -.IP CURLOPT_RTSP_SERVER_CSEQ -CSEQ number for RTSP Server->Client request. See \fICURLOPT_RTSP_SERVER_CSEQ(3)\fP -.IP CURLOPT_AWS_SIGV4 -AWS HTTP V4 Signature. See \fICURLOPT_AWS_SIGV4(3)\fP -.SH PROTOCOL OPTIONS -.IP CURLOPT_TRANSFERTEXT -Use text transfer. See \fICURLOPT_TRANSFERTEXT(3)\fP -.IP CURLOPT_PROXY_TRANSFER_MODE -Add transfer mode to URL over proxy. See \fICURLOPT_PROXY_TRANSFER_MODE(3)\fP -.IP CURLOPT_CRLF -Convert newlines. See \fICURLOPT_CRLF(3)\fP -.IP CURLOPT_RANGE -Range requests. See \fICURLOPT_RANGE(3)\fP -.IP CURLOPT_RESUME_FROM -Resume a transfer. See \fICURLOPT_RESUME_FROM(3)\fP -.IP CURLOPT_RESUME_FROM_LARGE -Resume a transfer. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP -.IP CURLOPT_CURLU -Set URL to work on with a URL handle. See \fICURLOPT_CURLU(3)\fP -.IP CURLOPT_CUSTOMREQUEST -Custom request/method. See \fICURLOPT_CUSTOMREQUEST(3)\fP -.IP CURLOPT_FILETIME -Request file modification date and time. See \fICURLOPT_FILETIME(3)\fP -.IP CURLOPT_DIRLISTONLY -List only. See \fICURLOPT_DIRLISTONLY(3)\fP -.IP CURLOPT_NOBODY -Do not get the body contents. See \fICURLOPT_NOBODY(3)\fP -.IP CURLOPT_INFILESIZE -Size of file to send. \fICURLOPT_INFILESIZE(3)\fP -.IP CURLOPT_INFILESIZE_LARGE -Size of file to send. \fICURLOPT_INFILESIZE_LARGE(3)\fP -.IP CURLOPT_UPLOAD -Upload data. See \fICURLOPT_UPLOAD(3)\fP -.IP CURLOPT_UPLOAD_BUFFERSIZE -Set upload buffer size. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP -.IP CURLOPT_MIMEPOST -Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP -.IP CURLOPT_MIME_OPTIONS -Set MIME option flags. See \fICURLOPT_MIME_OPTIONS(3)\fP -.IP CURLOPT_MAXFILESIZE -Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP -.IP CURLOPT_MAXFILESIZE_LARGE -Maximum file size to get. See \fICURLOPT_MAXFILESIZE_LARGE(3)\fP -.IP CURLOPT_TIMECONDITION -Make a time conditional request. See \fICURLOPT_TIMECONDITION(3)\fP -.IP CURLOPT_TIMEVALUE -Time value for the time conditional request. See \fICURLOPT_TIMEVALUE(3)\fP -.IP CURLOPT_TIMEVALUE_LARGE -Time value for the time conditional request. See \fICURLOPT_TIMEVALUE_LARGE(3)\fP -.SH CONNECTION OPTIONS -.IP CURLOPT_TIMEOUT -Timeout for the entire request. See \fICURLOPT_TIMEOUT(3)\fP -.IP CURLOPT_TIMEOUT_MS -Millisecond timeout for the entire request. See \fICURLOPT_TIMEOUT_MS(3)\fP -.IP CURLOPT_LOW_SPEED_LIMIT -Low speed limit to abort transfer. See \fICURLOPT_LOW_SPEED_LIMIT(3)\fP -.IP CURLOPT_LOW_SPEED_TIME -Time to be below the speed to trigger low speed abort. See \fICURLOPT_LOW_SPEED_TIME(3)\fP -.IP CURLOPT_MAX_SEND_SPEED_LARGE -Cap the upload speed to this. See \fICURLOPT_MAX_SEND_SPEED_LARGE(3)\fP -.IP CURLOPT_MAX_RECV_SPEED_LARGE -Cap the download speed to this. See \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP -.IP CURLOPT_MAXCONNECTS -Maximum number of connections in the connection pool. See \fICURLOPT_MAXCONNECTS(3)\fP -.IP CURLOPT_FRESH_CONNECT -Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP -.IP CURLOPT_FORBID_REUSE -Prevent subsequent connections from reusing this. See \fICURLOPT_FORBID_REUSE(3)\fP -.IP CURLOPT_MAXAGE_CONN -Limit the age (idle time) of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP -.IP CURLOPT_MAXLIFETIME_CONN -Limit the age (since creation) of connections for reuse. See \fICURLOPT_MAXLIFETIME_CONN(3)\fP -.IP CURLOPT_CONNECTTIMEOUT -Timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT(3)\fP -.IP CURLOPT_CONNECTTIMEOUT_MS -Millisecond timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP -.IP CURLOPT_IPRESOLVE -IP version to use. See \fICURLOPT_IPRESOLVE(3)\fP -.IP CURLOPT_CONNECT_ONLY -Only connect, nothing else. See \fICURLOPT_CONNECT_ONLY(3)\fP -.IP CURLOPT_USE_SSL -Use TLS/SSL. See \fICURLOPT_USE_SSL(3)\fP -.IP CURLOPT_RESOLVE -Provide fixed/fake name resolves. See \fICURLOPT_RESOLVE(3)\fP -.IP CURLOPT_DNS_INTERFACE -Bind name resolves to this interface. See \fICURLOPT_DNS_INTERFACE(3)\fP -.IP CURLOPT_DNS_LOCAL_IP4 -Bind name resolves to this IP4 address. See \fICURLOPT_DNS_LOCAL_IP4(3)\fP -.IP CURLOPT_DNS_LOCAL_IP6 -Bind name resolves to this IP6 address. See \fICURLOPT_DNS_LOCAL_IP6(3)\fP -.IP CURLOPT_DNS_SERVERS -Preferred DNS servers. See \fICURLOPT_DNS_SERVERS(3)\fP -.IP CURLOPT_DNS_SHUFFLE_ADDRESSES -Shuffle addresses before use. See \fICURLOPT_DNS_SHUFFLE_ADDRESSES(3)\fP -.IP CURLOPT_ACCEPTTIMEOUT_MS -Timeout for waiting for the server's connect back to be accepted. See \fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP -.IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS -Timeout for happy eyeballs. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP -.IP CURLOPT_UPKEEP_INTERVAL_MS -Sets the interval at which connection upkeep are performed. See -\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP -.SH SSL and SECURITY OPTIONS -.IP CURLOPT_SSLCERT -Client cert. See \fICURLOPT_SSLCERT(3)\fP -.IP CURLOPT_SSLCERT_BLOB -Client cert memory buffer. See \fICURLOPT_SSLCERT_BLOB(3)\fP -.IP CURLOPT_PROXY_SSLCERT -Proxy client cert. See \fICURLOPT_PROXY_SSLCERT(3)\fP -.IP CURLOPT_PROXY_SSLCERT_BLOB -Proxy client cert memory buffer. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP -.IP CURLOPT_SSLCERTTYPE -Client cert type. See \fICURLOPT_SSLCERTTYPE(3)\fP -.IP CURLOPT_PROXY_SSLCERTTYPE -Proxy client cert type. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP -.IP CURLOPT_SSLKEY -Client key. See \fICURLOPT_SSLKEY(3)\fP -.IP CURLOPT_SSLKEY_BLOB -Client key memory buffer. See \fICURLOPT_SSLKEY_BLOB(3)\fP -.IP CURLOPT_PROXY_SSLKEY -Proxy client key. See \fICURLOPT_PROXY_SSLKEY(3)\fP -.IP CURLOPT_PROXY_SSLKEY_BLOB -Proxy client key. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP -.IP CURLOPT_SSLKEYTYPE -Client key type. See \fICURLOPT_SSLKEYTYPE(3)\fP -.IP CURLOPT_PROXY_SSLKEYTYPE -Proxy client key type. See \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP -.IP CURLOPT_KEYPASSWD -Client key password. See \fICURLOPT_KEYPASSWD(3)\fP -.IP CURLOPT_PROXY_KEYPASSWD -Proxy client key password. See \fICURLOPT_PROXY_KEYPASSWD(3)\fP -.IP CURLOPT_SSL_EC_CURVES -Set key exchange curves. See \fICURLOPT_SSL_EC_CURVES(3)\fP -.IP CURLOPT_SSL_ENABLE_ALPN -Enable use of ALPN. See \fICURLOPT_SSL_ENABLE_ALPN(3)\fP -.IP CURLOPT_SSL_ENABLE_NPN -\fBOBSOLETE\fP Enable use of NPN. See \fICURLOPT_SSL_ENABLE_NPN(3)\fP -.IP CURLOPT_SSLENGINE -Use identifier with SSL engine. See \fICURLOPT_SSLENGINE(3)\fP -.IP CURLOPT_SSLENGINE_DEFAULT -Default SSL engine. See \fICURLOPT_SSLENGINE_DEFAULT(3)\fP -.IP CURLOPT_SSL_FALSESTART -Enable TLS False Start. See \fICURLOPT_SSL_FALSESTART(3)\fP -.IP CURLOPT_SSLVERSION -SSL version to use. See \fICURLOPT_SSLVERSION(3)\fP -.IP CURLOPT_PROXY_SSLVERSION -Proxy SSL version to use. See \fICURLOPT_PROXY_SSLVERSION(3)\fP -.IP CURLOPT_SSL_VERIFYHOST -Verify the host name in the SSL certificate. See \fICURLOPT_SSL_VERIFYHOST(3)\fP -.IP CURLOPT_DOH_SSL_VERIFYHOST -Verify the host name in the DoH (DNS-over-HTTPS) SSL certificate. See -\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP -.IP CURLOPT_PROXY_SSL_VERIFYHOST -Verify the host name in the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP -.IP CURLOPT_SSL_VERIFYPEER -Verify the SSL certificate. See \fICURLOPT_SSL_VERIFYPEER(3)\fP -.IP CURLOPT_DOH_SSL_VERIFYPEER -Verify the DoH (DNS-over-HTTPS) SSL certificate. See -\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP -.IP CURLOPT_PROXY_SSL_VERIFYPEER -Verify the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP -.IP CURLOPT_SSL_VERIFYSTATUS -Verify the SSL certificate's status. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP -.IP CURLOPT_DOH_SSL_VERIFYSTATUS -Verify the DoH (DNS-over-HTTPS) SSL certificate's status. See -\fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP -.IP CURLOPT_CAINFO -CA cert bundle. See \fICURLOPT_CAINFO(3)\fP -.IP CURLOPT_CAINFO_BLOB -CA cert bundle memory buffer. See \fICURLOPT_CAINFO_BLOB(3)\fP -.IP CURLOPT_PROXY_CAINFO -Proxy CA cert bundle. See \fICURLOPT_PROXY_CAINFO(3)\fP -.IP CURLOPT_PROXY_CAINFO_BLOB -Proxy CA cert bundle memory buffer. See \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP -.IP CURLOPT_ISSUERCERT -Issuer certificate. See \fICURLOPT_ISSUERCERT(3)\fP -.IP CURLOPT_ISSUERCERT_BLOB -Issuer certificate memory buffer. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP -.IP CURLOPT_PROXY_ISSUERCERT -Proxy issuer certificate. See \fICURLOPT_PROXY_ISSUERCERT(3)\fP -.IP CURLOPT_PROXY_ISSUERCERT_BLOB -Proxy issuer certificate memory buffer. See \fICURLOPT_PROXY_ISSUERCERT_BLOB(3)\fP -.IP CURLOPT_CAPATH -Path to CA cert bundle. See \fICURLOPT_CAPATH(3)\fP -.IP CURLOPT_PROXY_CAPATH -Path to proxy CA cert bundle. See \fICURLOPT_PROXY_CAPATH(3)\fP -.IP CURLOPT_CRLFILE -Certificate Revocation List. See \fICURLOPT_CRLFILE(3)\fP -.IP CURLOPT_PROXY_CRLFILE -Proxy Certificate Revocation List. See \fICURLOPT_PROXY_CRLFILE(3)\fP -.IP CURLOPT_CA_CACHE_TIMEOUT -Timeout for CA cache. See \fICURLOPT_CA_CACHE_TIMEOUT(3)\fP -.IP CURLOPT_CERTINFO -Extract certificate info. See \fICURLOPT_CERTINFO(3)\fP -.IP CURLOPT_PINNEDPUBLICKEY -Set pinned SSL public key . See \fICURLOPT_PINNEDPUBLICKEY(3)\fP -.IP CURLOPT_PROXY_PINNEDPUBLICKEY -Set the proxy's pinned SSL public key. See -\fICURLOPT_PROXY_PINNEDPUBLICKEY(3)\fP -.IP CURLOPT_RANDOM_FILE -\fBOBSOLETE\fP Provide source for entropy random data. -See \fICURLOPT_RANDOM_FILE(3)\fP -.IP CURLOPT_EGDSOCKET -\fBOBSOLETE\fP Identify EGD socket for entropy. See \fICURLOPT_EGDSOCKET(3)\fP -.IP CURLOPT_SSL_CIPHER_LIST -Ciphers to use. See \fICURLOPT_SSL_CIPHER_LIST(3)\fP -.IP CURLOPT_PROXY_SSL_CIPHER_LIST -Proxy ciphers to use. See \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP -.IP CURLOPT_TLS13_CIPHERS -TLS 1.3 cipher suites to use. See \fICURLOPT_TLS13_CIPHERS(3)\fP -.IP CURLOPT_PROXY_TLS13_CIPHERS -Proxy TLS 1.3 cipher suites to use. See \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP -.IP CURLOPT_SSL_SESSIONID_CACHE -Disable SSL session-id cache. See \fICURLOPT_SSL_SESSIONID_CACHE(3)\fP -.IP CURLOPT_SSL_OPTIONS -Control SSL behavior. See \fICURLOPT_SSL_OPTIONS(3)\fP -.IP CURLOPT_PROXY_SSL_OPTIONS -Control proxy SSL behavior. See \fICURLOPT_PROXY_SSL_OPTIONS(3)\fP -.IP CURLOPT_KRBLEVEL -Kerberos security level. See \fICURLOPT_KRBLEVEL(3)\fP -.IP CURLOPT_GSSAPI_DELEGATION -Disable GSS-API delegation. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP -.SH SSH OPTIONS -.IP CURLOPT_SSH_AUTH_TYPES -SSH authentication types. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP -.IP CURLOPT_SSH_COMPRESSION -Enable SSH compression. See \fICURLOPT_SSH_COMPRESSION(3)\fP -.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 -MD5 of host's public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)\fP -.IP CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 -SHA256 of host's public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP -.IP CURLOPT_SSH_PUBLIC_KEYFILE -File name of public key. See \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP -.IP CURLOPT_SSH_PRIVATE_KEYFILE -File name of private key. See \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP -.IP CURLOPT_SSH_KNOWNHOSTS -File name with known hosts. See \fICURLOPT_SSH_KNOWNHOSTS(3)\fP -.IP CURLOPT_SSH_KEYFUNCTION -Callback for known hosts handling. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP -.IP CURLOPT_SSH_KEYDATA -Custom pointer to pass to ssh key callback. See \fICURLOPT_SSH_KEYDATA(3)\fP -.IP CURLOPT_SSH_HOSTKEYFUNCTION -Callback for checking host key handling. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP -.IP CURLOPT_SSH_HOSTKEYDATA -Custom pointer to pass to ssh host key callback. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP -.SH WEBSOCKET -.IP CURLOPT_WS_OPTIONS -Set WebSocket options. See \fICURLOPT_WS_OPTIONS(3)\fP -.SH OTHER OPTIONS -.IP CURLOPT_PRIVATE -Private pointer to store. See \fICURLOPT_PRIVATE(3)\fP -.IP CURLOPT_SHARE -Share object to use. See \fICURLOPT_SHARE(3)\fP -.IP CURLOPT_NEW_FILE_PERMS -Mode for creating new remote files. See \fICURLOPT_NEW_FILE_PERMS(3)\fP -.IP CURLOPT_NEW_DIRECTORY_PERMS -Mode for creating new remote directories. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\fP -.IP CURLOPT_QUICK_EXIT -To be set by toplevel tools like "curl" to skip lengthy cleanups when they are about to call exit() anyway. See \fICURLOPT_QUICK_EXIT(3)\fP -.SH TELNET OPTIONS -.IP CURLOPT_TELNETOPTIONS -TELNET options. See \fICURLOPT_TELNETOPTIONS(3)\fP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -\fICURLE_OK\fP (zero) means that the option was set properly, non-zero means an -error occurred as \fI\fP defines. See the \fIlibcurl-errors(3)\fP -man page for the full list with descriptions. - -Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise -\fIcurl_easy_setopt(3)\fP returns \fBCURLE_BAD_FUNCTION_ARGUMENT\fP (added in -7.65.0). - -\fBCURLE_BAD_FUNCTION_ARGUMENT\fP is returned when the argument to an option -is invalid, like perhaps out of range. - -If you try to set an option that libcurl does not know about, perhaps because -the library is too old to support it or the option was removed in a recent -version, this function returns \fICURLE_UNKNOWN_OPTION\fP. If support for the -option was disabled at compile-time, it returns \fICURLE_NOT_BUILT_IN\fP. -.SH "SEE ALSO" -.BR curl_easy_cleanup (3), -.BR curl_easy_getinfo (3), -.BR curl_easy_init (3), -.BR curl_easy_option_by_id (3), -.BR curl_easy_option_by_name (3), -.BR curl_easy_option_next (3), -.BR curl_easy_reset (3), -.BR curl_multi_setopt (3) diff --git a/docs/libcurl/curl_easy_setopt.md b/docs/libcurl/curl_easy_setopt.md new file mode 100644 index 00000000000..a5779882934 --- /dev/null +++ b/docs/libcurl/curl_easy_setopt.md @@ -0,0 +1,1381 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_setopt +Section: 3 +Source: libcurl +See-also: + - curl_easy_cleanup (3) + - curl_easy_getinfo (3) + - curl_easy_init (3) + - curl_easy_option_by_id (3) + - curl_easy_option_by_name (3) + - curl_easy_option_next (3) + - curl_easy_reset (3) + - curl_multi_setopt (3) +--- + +# NAME + +curl_easy_setopt - set options for a curl easy handle + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); +~~~ + +# DESCRIPTION + +curl_easy_setopt(3) is used to tell libcurl how to behave. By setting the +appropriate options, the application can change libcurl's behavior. All +options are set with an *option* followed by a *parameter*. That parameter can +be a **long**, a **function pointer**, an **object pointer** or a +**curl_off_t**, depending on what the specific option expects. Read this +manual carefully as bad input values may cause libcurl to behave badly! You +can only set one option in each function call. A typical application uses many +curl_easy_setopt(3) calls in the setup phase. + +Options set with this function call are valid for all forthcoming transfers +performed using this *handle*. The options are not in any way reset between +transfers, so if you want subsequent transfers with different options, you +must change them between the transfers. You can optionally reset all options +back to internal default with curl_easy_reset(3). + +Strings passed to libcurl as 'char *' arguments, are copied by the library; +the string storage associated to the pointer argument may be discarded or +reused after curl_easy_setopt(3) returns. The only exception to this rule is +really CURLOPT_POSTFIELDS(3), but the alternative that copies the string +CURLOPT_COPYPOSTFIELDS(3) has some usage characteristics you need to read up +on. This function does not accept input strings longer than +**CURL_MAX_INPUT_LENGTH** (8 MB). + +The order in which the options are set does not matter. + +Before version 7.17.0, strings were not copied. Instead the user was forced +keep them available until libcurl no longer needed them. + +The *handle* is the return code from a curl_easy_init(3) or +curl_easy_duphandle(3) call. + +# BEHAVIOR OPTIONS + +## CURLOPT_VERBOSE + +Display verbose information. See CURLOPT_VERBOSE(3) + +## CURLOPT_HEADER + +Include the header in the body output. See CURLOPT_HEADER(3) + +## CURLOPT_NOPROGRESS + +Shut off the progress meter. See CURLOPT_NOPROGRESS(3) + +## CURLOPT_NOSIGNAL + +Do not install signal handlers. See CURLOPT_NOSIGNAL(3) + +## CURLOPT_WILDCARDMATCH + +Transfer multiple files according to a file name pattern. See +CURLOPT_WILDCARDMATCH(3) + +# CALLBACK OPTIONS + +## CURLOPT_WRITEFUNCTION + +Callback for writing data. See CURLOPT_WRITEFUNCTION(3) + +## CURLOPT_WRITEDATA + +Data pointer to pass to the write callback. See CURLOPT_WRITEDATA(3) + +## CURLOPT_READFUNCTION + +Callback for reading data. See CURLOPT_READFUNCTION(3) + +## CURLOPT_READDATA + +Data pointer to pass to the read callback. See CURLOPT_READDATA(3) + +## CURLOPT_IOCTLFUNCTION + +**Deprecated option** Callback for I/O operations. +See CURLOPT_IOCTLFUNCTION(3) + +## CURLOPT_IOCTLDATA + +**Deprecated option** Data pointer to pass to the I/O callback. +See CURLOPT_IOCTLDATA(3) + +## CURLOPT_SEEKFUNCTION + +Callback for seek operations. See CURLOPT_SEEKFUNCTION(3) + +## CURLOPT_SEEKDATA + +Data pointer to pass to the seek callback. See CURLOPT_SEEKDATA(3) + +## CURLOPT_SOCKOPTFUNCTION + +Callback for sockopt operations. See CURLOPT_SOCKOPTFUNCTION(3) + +## CURLOPT_SOCKOPTDATA + +Data pointer to pass to the sockopt callback. See CURLOPT_SOCKOPTDATA(3) + +## CURLOPT_OPENSOCKETFUNCTION + +Callback for socket creation. See CURLOPT_OPENSOCKETFUNCTION(3) + +## CURLOPT_OPENSOCKETDATA + +Data pointer to pass to the open socket callback. See CURLOPT_OPENSOCKETDATA(3) + +## CURLOPT_CLOSESOCKETFUNCTION + +Callback for closing socket. See CURLOPT_CLOSESOCKETFUNCTION(3) + +## CURLOPT_CLOSESOCKETDATA + +Data pointer to pass to the close socket callback. See CURLOPT_CLOSESOCKETDATA(3) + +## CURLOPT_PROGRESSFUNCTION + +**OBSOLETE** callback for progress meter. +See CURLOPT_PROGRESSFUNCTION(3) + +## CURLOPT_PROGRESSDATA + +Data pointer to pass to the progress meter callback. See CURLOPT_PROGRESSDATA(3) + +## CURLOPT_XFERINFOFUNCTION + +Callback for progress meter. See CURLOPT_XFERINFOFUNCTION(3) + +## CURLOPT_XFERINFODATA + +Data pointer to pass to the progress meter callback. See CURLOPT_XFERINFODATA(3) + +## CURLOPT_HEADERFUNCTION + +Callback for writing received headers. See CURLOPT_HEADERFUNCTION(3) + +## CURLOPT_HEADERDATA + +Data pointer to pass to the header callback. See CURLOPT_HEADERDATA(3) + +## CURLOPT_DEBUGFUNCTION + +Callback for debug information. See CURLOPT_DEBUGFUNCTION(3) + +## CURLOPT_DEBUGDATA + +Data pointer to pass to the debug callback. See CURLOPT_DEBUGDATA(3) + +## CURLOPT_SSL_CTX_FUNCTION + +Callback for SSL context logic. See CURLOPT_SSL_CTX_FUNCTION(3) + +## CURLOPT_SSL_CTX_DATA + +Data pointer to pass to the SSL context callback. See CURLOPT_SSL_CTX_DATA(3) + +## CURLOPT_CONV_TO_NETWORK_FUNCTION + +**OBSOLETE** Callback for code base conversion. +See CURLOPT_CONV_TO_NETWORK_FUNCTION(3) + +## CURLOPT_CONV_FROM_NETWORK_FUNCTION + +**OBSOLETE** Callback for code base conversion. +See CURLOPT_CONV_FROM_NETWORK_FUNCTION(3) + +## CURLOPT_CONV_FROM_UTF8_FUNCTION + +**OBSOLETE** Callback for code base conversion. +See CURLOPT_CONV_FROM_UTF8_FUNCTION(3) + +## CURLOPT_INTERLEAVEFUNCTION + +Callback for RTSP interleaved data. See CURLOPT_INTERLEAVEFUNCTION(3) + +## CURLOPT_INTERLEAVEDATA + +Data pointer to pass to the RTSP interleave callback. See CURLOPT_INTERLEAVEDATA(3) + +## CURLOPT_CHUNK_BGN_FUNCTION + +Callback for wildcard download start of chunk. See CURLOPT_CHUNK_BGN_FUNCTION(3) + +## CURLOPT_CHUNK_END_FUNCTION + +Callback for wildcard download end of chunk. See CURLOPT_CHUNK_END_FUNCTION(3) + +## CURLOPT_CHUNK_DATA + +Data pointer to pass to the chunk callbacks. See CURLOPT_CHUNK_DATA(3) + +## CURLOPT_FNMATCH_FUNCTION + +Callback for wildcard matching. See CURLOPT_FNMATCH_FUNCTION(3) + +## CURLOPT_FNMATCH_DATA + +Data pointer to pass to the wildcard matching callback. See CURLOPT_FNMATCH_DATA(3) + +## CURLOPT_SUPPRESS_CONNECT_HEADERS + +Suppress proxy CONNECT response headers from user callbacks. See +CURLOPT_SUPPRESS_CONNECT_HEADERS(3) + +## CURLOPT_RESOLVER_START_FUNCTION + +Callback to be called before a new resolve request is started. See +CURLOPT_RESOLVER_START_FUNCTION(3) + +## CURLOPT_RESOLVER_START_DATA + +Data pointer to pass to resolver start callback. See CURLOPT_RESOLVER_START_DATA(3) + +## CURLOPT_PREREQFUNCTION + +Callback to be called after a connection is established but before a request +is made on that connection. See CURLOPT_PREREQFUNCTION(3) + +## CURLOPT_PREREQDATA + +Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See +CURLOPT_PREREQDATA(3) + +# ERROR OPTIONS + +## CURLOPT_ERRORBUFFER + +Error message buffer. See CURLOPT_ERRORBUFFER(3) + +## CURLOPT_STDERR + +stderr replacement stream. See CURLOPT_STDERR(3) + +## CURLOPT_FAILONERROR + +Fail on HTTP 4xx errors. CURLOPT_FAILONERROR(3) + +## CURLOPT_KEEP_SENDING_ON_ERROR + +Keep sending on HTTP >= 300 errors. CURLOPT_KEEP_SENDING_ON_ERROR(3) + +# NETWORK OPTIONS + +## CURLOPT_URL + +URL to work on. See CURLOPT_URL(3) + +## CURLOPT_PATH_AS_IS + +Disable squashing /../ and /./ sequences in the path. See CURLOPT_PATH_AS_IS(3) + +## CURLOPT_PROTOCOLS + +**Deprecated option** Allowed protocols. See CURLOPT_PROTOCOLS(3) + +## CURLOPT_PROTOCOLS_STR + +Allowed protocols. See CURLOPT_PROTOCOLS_STR(3) + +## CURLOPT_REDIR_PROTOCOLS + +**Deprecated option** Protocols to allow redirects to. See +CURLOPT_REDIR_PROTOCOLS(3) + +## CURLOPT_REDIR_PROTOCOLS_STR + +Protocols to allow redirects to. See CURLOPT_REDIR_PROTOCOLS_STR(3) + +## CURLOPT_DEFAULT_PROTOCOL + +Default protocol. See CURLOPT_DEFAULT_PROTOCOL(3) + +## CURLOPT_PROXY + +Proxy to use. See CURLOPT_PROXY(3) + +## CURLOPT_PRE_PROXY + +Socks proxy to use. See CURLOPT_PRE_PROXY(3) + +## CURLOPT_PROXYPORT + +Proxy port to use. See CURLOPT_PROXYPORT(3) + +## CURLOPT_PROXYTYPE + +Proxy type. See CURLOPT_PROXYTYPE(3) + +## CURLOPT_NOPROXY + +Filter out hosts from proxy use. CURLOPT_NOPROXY(3) + +## CURLOPT_HTTPPROXYTUNNEL + +Tunnel through the HTTP proxy. CURLOPT_HTTPPROXYTUNNEL(3) + +## CURLOPT_CONNECT_TO + +Connect to a specific host and port. See CURLOPT_CONNECT_TO(3) + +## CURLOPT_SOCKS5_AUTH + +Socks5 authentication methods. See CURLOPT_SOCKS5_AUTH(3) + +## CURLOPT_SOCKS5_GSSAPI_SERVICE + +**Deprecated option** Socks5 GSSAPI service name. +See CURLOPT_SOCKS5_GSSAPI_SERVICE(3) + +## CURLOPT_SOCKS5_GSSAPI_NEC + +Socks5 GSSAPI NEC mode. See CURLOPT_SOCKS5_GSSAPI_NEC(3) + +## CURLOPT_PROXY_SERVICE_NAME + +Proxy authentication service name. CURLOPT_PROXY_SERVICE_NAME(3) + +## CURLOPT_HAPROXYPROTOCOL + +Send an HAProxy PROXY protocol v1 header. See CURLOPT_HAPROXYPROTOCOL(3) + +## CURLOPT_HAPROXY_CLIENT_IP + +Spoof the client IP in an HAProxy PROXY protocol v1 header. See +CURLOPT_HAPROXY_CLIENT_IP(3) + +## CURLOPT_SERVICE_NAME + +Authentication service name. CURLOPT_SERVICE_NAME(3) + +## CURLOPT_INTERFACE + +Bind connection locally to this. See CURLOPT_INTERFACE(3) + +## CURLOPT_LOCALPORT + +Bind connection locally to this port. See CURLOPT_LOCALPORT(3) + +## CURLOPT_LOCALPORTRANGE + +Bind connection locally to port range. See CURLOPT_LOCALPORTRANGE(3) + +## CURLOPT_DNS_CACHE_TIMEOUT + +Timeout for DNS cache. See CURLOPT_DNS_CACHE_TIMEOUT(3) + +## CURLOPT_DNS_USE_GLOBAL_CACHE + +**OBSOLETE** Enable global DNS cache. +See CURLOPT_DNS_USE_GLOBAL_CACHE(3) + +## CURLOPT_DOH_URL + +Use this DoH server for name resolves. See CURLOPT_DOH_URL(3) + +## CURLOPT_BUFFERSIZE + +Ask for alternate buffer size. See CURLOPT_BUFFERSIZE(3) + +## CURLOPT_PORT + +Port number to connect to. See CURLOPT_PORT(3) + +## CURLOPT_TCP_FASTOPEN + +Enable TCP Fast Open. See CURLOPT_TCP_FASTOPEN(3) + +## CURLOPT_TCP_NODELAY + +Disable the Nagle algorithm. See CURLOPT_TCP_NODELAY(3) + +## CURLOPT_ADDRESS_SCOPE + +IPv6 scope for local addresses. See CURLOPT_ADDRESS_SCOPE(3) + +## CURLOPT_TCP_KEEPALIVE + +Enable TCP keep-alive. See CURLOPT_TCP_KEEPALIVE(3) + +## CURLOPT_TCP_KEEPIDLE + +Idle time before sending keep-alive. See CURLOPT_TCP_KEEPIDLE(3) + +## CURLOPT_TCP_KEEPINTVL + +Interval between keep-alive probes. See CURLOPT_TCP_KEEPINTVL(3) + +## CURLOPT_UNIX_SOCKET_PATH + +Path to a Unix domain socket. See CURLOPT_UNIX_SOCKET_PATH(3) + +## CURLOPT_ABSTRACT_UNIX_SOCKET + +Path to an abstract Unix domain socket. See CURLOPT_ABSTRACT_UNIX_SOCKET(3) + +# NAMES and PASSWORDS OPTIONS (Authentication) + +## CURLOPT_NETRC + +Enable .netrc parsing. See CURLOPT_NETRC(3) + +## CURLOPT_NETRC_FILE + +&.netrc file name. See CURLOPT_NETRC_FILE(3) + +## CURLOPT_USERPWD + +User name and password. See CURLOPT_USERPWD(3) + +## CURLOPT_PROXYUSERPWD + +Proxy user name and password. See CURLOPT_PROXYUSERPWD(3) + +## CURLOPT_USERNAME + +User name. See CURLOPT_USERNAME(3) + +## CURLOPT_PASSWORD + +Password. See CURLOPT_PASSWORD(3) + +## CURLOPT_LOGIN_OPTIONS + +Login options. See CURLOPT_LOGIN_OPTIONS(3) + +## CURLOPT_PROXYUSERNAME + +Proxy user name. See CURLOPT_PROXYUSERNAME(3) + +## CURLOPT_PROXYPASSWORD + +Proxy password. See CURLOPT_PROXYPASSWORD(3) + +## CURLOPT_HTTPAUTH + +HTTP server authentication methods. See CURLOPT_HTTPAUTH(3) + +## CURLOPT_TLSAUTH_USERNAME + +TLS authentication user name. See CURLOPT_TLSAUTH_USERNAME(3) + +## CURLOPT_PROXY_TLSAUTH_USERNAME + +Proxy TLS authentication user name. See CURLOPT_PROXY_TLSAUTH_USERNAME(3) + +## CURLOPT_TLSAUTH_PASSWORD + +TLS authentication password. See CURLOPT_TLSAUTH_PASSWORD(3) + +## CURLOPT_PROXY_TLSAUTH_PASSWORD + +Proxy TLS authentication password. See CURLOPT_PROXY_TLSAUTH_PASSWORD(3) + +## CURLOPT_TLSAUTH_TYPE + +TLS authentication methods. See CURLOPT_TLSAUTH_TYPE(3) + +## CURLOPT_PROXY_TLSAUTH_TYPE + +Proxy TLS authentication methods. See CURLOPT_PROXY_TLSAUTH_TYPE(3) + +## CURLOPT_PROXYAUTH + +HTTP proxy authentication methods. See CURLOPT_PROXYAUTH(3) + +## CURLOPT_SASL_AUTHZID + +SASL authorization identity (identity to act as). See CURLOPT_SASL_AUTHZID(3) + +## CURLOPT_SASL_IR + +Enable SASL initial response. See CURLOPT_SASL_IR(3) + +## CURLOPT_XOAUTH2_BEARER + +OAuth2 bearer token. See CURLOPT_XOAUTH2_BEARER(3) + +## CURLOPT_DISALLOW_USERNAME_IN_URL + +Do not allow username in URL. See CURLOPT_DISALLOW_USERNAME_IN_URL(3) + +# HTTP OPTIONS + +## CURLOPT_AUTOREFERER + +Automatically set Referer: header. See CURLOPT_AUTOREFERER(3) + +## CURLOPT_ACCEPT_ENCODING + +Accept-Encoding and automatic decompressing data. See CURLOPT_ACCEPT_ENCODING(3) + +## CURLOPT_TRANSFER_ENCODING + +Request Transfer-Encoding. See CURLOPT_TRANSFER_ENCODING(3) + +## CURLOPT_FOLLOWLOCATION + +Follow HTTP redirects. See CURLOPT_FOLLOWLOCATION(3) + +## CURLOPT_UNRESTRICTED_AUTH + +Do not restrict authentication to original host. CURLOPT_UNRESTRICTED_AUTH(3) + +## CURLOPT_MAXREDIRS + +Maximum number of redirects to follow. See CURLOPT_MAXREDIRS(3) + +## CURLOPT_POSTREDIR + +How to act on redirects after POST. See CURLOPT_POSTREDIR(3) + +## CURLOPT_PUT + +**Deprecated option** Issue an HTTP PUT request. See CURLOPT_PUT(3) + +## CURLOPT_POST + +Issue an HTTP POST request. See CURLOPT_POST(3) + +## CURLOPT_POSTFIELDS + +Send a POST with this data. See CURLOPT_POSTFIELDS(3) + +## CURLOPT_POSTFIELDSIZE + +The POST data is this big. See CURLOPT_POSTFIELDSIZE(3) + +## CURLOPT_POSTFIELDSIZE_LARGE + +The POST data is this big. See CURLOPT_POSTFIELDSIZE_LARGE(3) + +## CURLOPT_COPYPOSTFIELDS + +Send a POST with this data - and copy it. See CURLOPT_COPYPOSTFIELDS(3) + +## CURLOPT_HTTPPOST + +**Deprecated option** Multipart formpost HTTP POST. +See CURLOPT_HTTPPOST(3) + +## CURLOPT_REFERER + +Referer: header. See CURLOPT_REFERER(3) + +## CURLOPT_USERAGENT + +User-Agent: header. See CURLOPT_USERAGENT(3) + +## CURLOPT_HTTPHEADER + +Custom HTTP headers. See CURLOPT_HTTPHEADER(3) + +## CURLOPT_HEADEROPT + +Control custom headers. See CURLOPT_HEADEROPT(3) + +## CURLOPT_PROXYHEADER + +Custom HTTP headers sent to proxy. See CURLOPT_PROXYHEADER(3) + +## CURLOPT_HTTP200ALIASES + +Alternative versions of 200 OK. See CURLOPT_HTTP200ALIASES(3) + +## CURLOPT_COOKIE + +Cookie(s) to send. See CURLOPT_COOKIE(3) + +## CURLOPT_COOKIEFILE + +File to read cookies from. See CURLOPT_COOKIEFILE(3) + +## CURLOPT_COOKIEJAR + +File to write cookies to. See CURLOPT_COOKIEJAR(3) + +## CURLOPT_COOKIESESSION + +Start a new cookie session. See CURLOPT_COOKIESESSION(3) + +## CURLOPT_COOKIELIST + +Add or control cookies. See CURLOPT_COOKIELIST(3) + +## CURLOPT_ALTSVC + +Specify the Alt-Svc: cache file name. See CURLOPT_ALTSVC(3) + +## CURLOPT_ALTSVC_CTRL + +Enable and configure Alt-Svc: treatment. See CURLOPT_ALTSVC_CTRL(3) + +## CURLOPT_HSTS + +Set HSTS cache file. See CURLOPT_HSTS(3) + +## CURLOPT_HSTS_CTRL + +Enable HSTS. See CURLOPT_HSTS_CTRL(3) + +## CURLOPT_HSTSREADFUNCTION + +Set HSTS read callback. See CURLOPT_HSTSREADFUNCTION(3) + +## CURLOPT_HSTSREADDATA + +Pass pointer to the HSTS read callback. See CURLOPT_HSTSREADDATA(3) + +## CURLOPT_HSTSWRITEFUNCTION + +Set HSTS write callback. See CURLOPT_HSTSWRITEFUNCTION(3) + +## CURLOPT_HSTSWRITEDATA + +Pass pointer to the HSTS write callback. See CURLOPT_HSTSWRITEDATA(3) + +## CURLOPT_HTTPGET + +Do an HTTP GET request. See CURLOPT_HTTPGET(3) + +## CURLOPT_REQUEST_TARGET + +Set the request target. CURLOPT_REQUEST_TARGET(3) + +## CURLOPT_HTTP_VERSION + +HTTP version to use. CURLOPT_HTTP_VERSION(3) + +## CURLOPT_HTTP09_ALLOWED + +Allow HTTP/0.9 responses. CURLOPT_HTTP09_ALLOWED(3) + +## CURLOPT_IGNORE_CONTENT_LENGTH + +Ignore Content-Length. See CURLOPT_IGNORE_CONTENT_LENGTH(3) + +## CURLOPT_HTTP_CONTENT_DECODING + +Disable Content decoding. See CURLOPT_HTTP_CONTENT_DECODING(3) + +## CURLOPT_HTTP_TRANSFER_DECODING + +Disable Transfer decoding. See CURLOPT_HTTP_TRANSFER_DECODING(3) + +## CURLOPT_EXPECT_100_TIMEOUT_MS + +100-continue timeout. See CURLOPT_EXPECT_100_TIMEOUT_MS(3) + +## CURLOPT_TRAILERFUNCTION + +Set callback for sending trailing headers. See +CURLOPT_TRAILERFUNCTION(3) + +## CURLOPT_TRAILERDATA + +Custom pointer passed to the trailing headers callback. See +CURLOPT_TRAILERDATA(3) + +## CURLOPT_PIPEWAIT + +Wait on connection to pipeline on it. See CURLOPT_PIPEWAIT(3) + +## CURLOPT_STREAM_DEPENDS + +This HTTP/2 stream depends on another. See CURLOPT_STREAM_DEPENDS(3) + +## CURLOPT_STREAM_DEPENDS_E + +This HTTP/2 stream depends on another exclusively. See +CURLOPT_STREAM_DEPENDS_E(3) + +## CURLOPT_STREAM_WEIGHT + +Set this HTTP/2 stream's weight. See CURLOPT_STREAM_WEIGHT(3) + +# SMTP OPTIONS + +## CURLOPT_MAIL_FROM + +Address of the sender. See CURLOPT_MAIL_FROM(3) + +## CURLOPT_MAIL_RCPT + +Address of the recipients. See CURLOPT_MAIL_RCPT(3) + +## CURLOPT_MAIL_AUTH + +Authentication address. See CURLOPT_MAIL_AUTH(3) + +## CURLOPT_MAIL_RCPT_ALLOWFAILS + +Allow RCPT TO command to fail for some recipients. See +CURLOPT_MAIL_RCPT_ALLOWFAILS(3) + +# TFTP OPTIONS + +## CURLOPT_TFTP_BLKSIZE + +TFTP block size. See CURLOPT_TFTP_BLKSIZE(3) + +## CURLOPT_TFTP_NO_OPTIONS + +Do not send TFTP options requests. See CURLOPT_TFTP_NO_OPTIONS(3) + +# FTP OPTIONS + +## CURLOPT_FTPPORT + +Use active FTP. See CURLOPT_FTPPORT(3) + +## CURLOPT_QUOTE + +Commands to run before transfer. See CURLOPT_QUOTE(3) + +## CURLOPT_POSTQUOTE + +Commands to run after transfer. See CURLOPT_POSTQUOTE(3) + +## CURLOPT_PREQUOTE + +Commands to run just before transfer. See CURLOPT_PREQUOTE(3) + +## CURLOPT_APPEND + +Append to remote file. See CURLOPT_APPEND(3) + +## CURLOPT_FTP_USE_EPRT + +Use EPRT. See CURLOPT_FTP_USE_EPRT(3) + +## CURLOPT_FTP_USE_EPSV + +Use EPSV. See CURLOPT_FTP_USE_EPSV(3) + +## CURLOPT_FTP_USE_PRET + +Use PRET. See CURLOPT_FTP_USE_PRET(3) + +## CURLOPT_FTP_CREATE_MISSING_DIRS + +Create missing directories on the remote server. See CURLOPT_FTP_CREATE_MISSING_DIRS(3) + +## CURLOPT_SERVER_RESPONSE_TIMEOUT + +Timeout for server responses. See CURLOPT_SERVER_RESPONSE_TIMEOUT(3) + +## CURLOPT_SERVER_RESPONSE_TIMEOUT_MS + +Timeout for server responses. See CURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3) + +## CURLOPT_FTP_ALTERNATIVE_TO_USER + +Alternative to USER. See CURLOPT_FTP_ALTERNATIVE_TO_USER(3) + +## CURLOPT_FTP_SKIP_PASV_IP + +Ignore the IP address in the PASV response. See CURLOPT_FTP_SKIP_PASV_IP(3) + +## CURLOPT_FTPSSLAUTH + +Control how to do TLS. See CURLOPT_FTPSSLAUTH(3) + +## CURLOPT_FTP_SSL_CCC + +Back to non-TLS again after authentication. See CURLOPT_FTP_SSL_CCC(3) + +## CURLOPT_FTP_ACCOUNT + +Send ACCT command. See CURLOPT_FTP_ACCOUNT(3) + +## CURLOPT_FTP_FILEMETHOD + +Specify how to reach files. See CURLOPT_FTP_FILEMETHOD(3) + +# RTSP OPTIONS + +## CURLOPT_RTSP_REQUEST + +RTSP request. See CURLOPT_RTSP_REQUEST(3) + +## CURLOPT_RTSP_SESSION_ID + +RTSP session-id. See CURLOPT_RTSP_SESSION_ID(3) + +## CURLOPT_RTSP_STREAM_URI + +RTSP stream URI. See CURLOPT_RTSP_STREAM_URI(3) + +## CURLOPT_RTSP_TRANSPORT + +RTSP Transport: header. See CURLOPT_RTSP_TRANSPORT(3) + +## CURLOPT_RTSP_CLIENT_CSEQ + +Client CSEQ number. See CURLOPT_RTSP_CLIENT_CSEQ(3) + +## CURLOPT_RTSP_SERVER_CSEQ + +CSEQ number for RTSP Server->Client request. See CURLOPT_RTSP_SERVER_CSEQ(3) + +## CURLOPT_AWS_SIGV4 + +AWS HTTP V4 Signature. See CURLOPT_AWS_SIGV4(3) + +# PROTOCOL OPTIONS + +## CURLOPT_TRANSFERTEXT + +Use text transfer. See CURLOPT_TRANSFERTEXT(3) + +## CURLOPT_PROXY_TRANSFER_MODE + +Add transfer mode to URL over proxy. See CURLOPT_PROXY_TRANSFER_MODE(3) + +## CURLOPT_CRLF + +Convert newlines. See CURLOPT_CRLF(3) + +## CURLOPT_RANGE + +Range requests. See CURLOPT_RANGE(3) + +## CURLOPT_RESUME_FROM + +Resume a transfer. See CURLOPT_RESUME_FROM(3) + +## CURLOPT_RESUME_FROM_LARGE + +Resume a transfer. See CURLOPT_RESUME_FROM_LARGE(3) + +## CURLOPT_CURLU + +Set URL to work on with a URL handle. See CURLOPT_CURLU(3) + +## CURLOPT_CUSTOMREQUEST + +Custom request/method. See CURLOPT_CUSTOMREQUEST(3) + +## CURLOPT_FILETIME + +Request file modification date and time. See CURLOPT_FILETIME(3) + +## CURLOPT_DIRLISTONLY + +List only. See CURLOPT_DIRLISTONLY(3) + +## CURLOPT_NOBODY + +Do not get the body contents. See CURLOPT_NOBODY(3) + +## CURLOPT_INFILESIZE + +Size of file to send. CURLOPT_INFILESIZE(3) + +## CURLOPT_INFILESIZE_LARGE + +Size of file to send. CURLOPT_INFILESIZE_LARGE(3) + +## CURLOPT_UPLOAD + +Upload data. See CURLOPT_UPLOAD(3) + +## CURLOPT_UPLOAD_BUFFERSIZE + +Set upload buffer size. See CURLOPT_UPLOAD_BUFFERSIZE(3) + +## CURLOPT_MIMEPOST + +Post/send MIME data. See CURLOPT_MIMEPOST(3) + +## CURLOPT_MIME_OPTIONS + +Set MIME option flags. See CURLOPT_MIME_OPTIONS(3) + +## CURLOPT_MAXFILESIZE + +Maximum file size to get. See CURLOPT_MAXFILESIZE(3) + +## CURLOPT_MAXFILESIZE_LARGE + +Maximum file size to get. See CURLOPT_MAXFILESIZE_LARGE(3) + +## CURLOPT_TIMECONDITION + +Make a time conditional request. See CURLOPT_TIMECONDITION(3) + +## CURLOPT_TIMEVALUE + +Time value for the time conditional request. See CURLOPT_TIMEVALUE(3) + +## CURLOPT_TIMEVALUE_LARGE + +Time value for the time conditional request. See CURLOPT_TIMEVALUE_LARGE(3) + +# CONNECTION OPTIONS + +## CURLOPT_TIMEOUT + +Timeout for the entire request. See CURLOPT_TIMEOUT(3) + +## CURLOPT_TIMEOUT_MS + +Millisecond timeout for the entire request. See CURLOPT_TIMEOUT_MS(3) + +## CURLOPT_LOW_SPEED_LIMIT + +Low speed limit to abort transfer. See CURLOPT_LOW_SPEED_LIMIT(3) + +## CURLOPT_LOW_SPEED_TIME + +Time to be below the speed to trigger low speed abort. See CURLOPT_LOW_SPEED_TIME(3) + +## CURLOPT_MAX_SEND_SPEED_LARGE + +Cap the upload speed to this. See CURLOPT_MAX_SEND_SPEED_LARGE(3) + +## CURLOPT_MAX_RECV_SPEED_LARGE + +Cap the download speed to this. See CURLOPT_MAX_RECV_SPEED_LARGE(3) + +## CURLOPT_MAXCONNECTS + +Maximum number of connections in the connection pool. See CURLOPT_MAXCONNECTS(3) + +## CURLOPT_FRESH_CONNECT + +Use a new connection. CURLOPT_FRESH_CONNECT(3) + +## CURLOPT_FORBID_REUSE + +Prevent subsequent connections from reusing this. See CURLOPT_FORBID_REUSE(3) + +## CURLOPT_MAXAGE_CONN + +Limit the age (idle time) of connections for reuse. See CURLOPT_MAXAGE_CONN(3) + +## CURLOPT_MAXLIFETIME_CONN + +Limit the age (since creation) of connections for reuse. See +CURLOPT_MAXLIFETIME_CONN(3) + +## CURLOPT_CONNECTTIMEOUT + +Timeout for the connection phase. See CURLOPT_CONNECTTIMEOUT(3) + +## CURLOPT_CONNECTTIMEOUT_MS + +Millisecond timeout for the connection phase. See CURLOPT_CONNECTTIMEOUT_MS(3) + +## CURLOPT_IPRESOLVE + +IP version to use. See CURLOPT_IPRESOLVE(3) + +## CURLOPT_CONNECT_ONLY + +Only connect, nothing else. See CURLOPT_CONNECT_ONLY(3) + +## CURLOPT_USE_SSL + +Use TLS/SSL. See CURLOPT_USE_SSL(3) + +## CURLOPT_RESOLVE + +Provide fixed/fake name resolves. See CURLOPT_RESOLVE(3) + +## CURLOPT_DNS_INTERFACE + +Bind name resolves to this interface. See CURLOPT_DNS_INTERFACE(3) + +## CURLOPT_DNS_LOCAL_IP4 + +Bind name resolves to this IP4 address. See CURLOPT_DNS_LOCAL_IP4(3) + +## CURLOPT_DNS_LOCAL_IP6 + +Bind name resolves to this IP6 address. See CURLOPT_DNS_LOCAL_IP6(3) + +## CURLOPT_DNS_SERVERS + +Preferred DNS servers. See CURLOPT_DNS_SERVERS(3) + +## CURLOPT_DNS_SHUFFLE_ADDRESSES + +Shuffle addresses before use. See CURLOPT_DNS_SHUFFLE_ADDRESSES(3) + +## CURLOPT_ACCEPTTIMEOUT_MS + +Timeout for waiting for the server's connect back to be accepted. See +CURLOPT_ACCEPTTIMEOUT_MS(3) + +## CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS + +Timeout for happy eyeballs. See CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3) + +## CURLOPT_UPKEEP_INTERVAL_MS + +Sets the interval at which connection upkeep are performed. See +CURLOPT_UPKEEP_INTERVAL_MS(3) + +# SSL and SECURITY OPTIONS + +## CURLOPT_SSLCERT + +Client cert. See CURLOPT_SSLCERT(3) + +## CURLOPT_SSLCERT_BLOB + +Client cert memory buffer. See CURLOPT_SSLCERT_BLOB(3) + +## CURLOPT_PROXY_SSLCERT + +Proxy client cert. See CURLOPT_PROXY_SSLCERT(3) + +## CURLOPT_PROXY_SSLCERT_BLOB + +Proxy client cert memory buffer. See CURLOPT_PROXY_SSLCERT_BLOB(3) + +## CURLOPT_SSLCERTTYPE + +Client cert type. See CURLOPT_SSLCERTTYPE(3) + +## CURLOPT_PROXY_SSLCERTTYPE + +Proxy client cert type. See CURLOPT_PROXY_SSLCERTTYPE(3) + +## CURLOPT_SSLKEY + +Client key. See CURLOPT_SSLKEY(3) + +## CURLOPT_SSLKEY_BLOB + +Client key memory buffer. See CURLOPT_SSLKEY_BLOB(3) + +## CURLOPT_PROXY_SSLKEY + +Proxy client key. See CURLOPT_PROXY_SSLKEY(3) + +## CURLOPT_PROXY_SSLKEY_BLOB + +Proxy client key. See CURLOPT_PROXY_SSLKEY_BLOB(3) + +## CURLOPT_SSLKEYTYPE + +Client key type. See CURLOPT_SSLKEYTYPE(3) + +## CURLOPT_PROXY_SSLKEYTYPE + +Proxy client key type. See CURLOPT_PROXY_SSLKEYTYPE(3) + +## CURLOPT_KEYPASSWD + +Client key password. See CURLOPT_KEYPASSWD(3) + +## CURLOPT_PROXY_KEYPASSWD + +Proxy client key password. See CURLOPT_PROXY_KEYPASSWD(3) + +## CURLOPT_SSL_EC_CURVES + +Set key exchange curves. See CURLOPT_SSL_EC_CURVES(3) + +## CURLOPT_SSL_ENABLE_ALPN + +Enable use of ALPN. See CURLOPT_SSL_ENABLE_ALPN(3) + +## CURLOPT_SSL_ENABLE_NPN + +**OBSOLETE** Enable use of NPN. See CURLOPT_SSL_ENABLE_NPN(3) + +## CURLOPT_SSLENGINE + +Use identifier with SSL engine. See CURLOPT_SSLENGINE(3) + +## CURLOPT_SSLENGINE_DEFAULT + +Default SSL engine. See CURLOPT_SSLENGINE_DEFAULT(3) + +## CURLOPT_SSL_FALSESTART + +Enable TLS False Start. See CURLOPT_SSL_FALSESTART(3) + +## CURLOPT_SSLVERSION + +SSL version to use. See CURLOPT_SSLVERSION(3) + +## CURLOPT_PROXY_SSLVERSION + +Proxy SSL version to use. See CURLOPT_PROXY_SSLVERSION(3) + +## CURLOPT_SSL_VERIFYHOST + +Verify the host name in the SSL certificate. See CURLOPT_SSL_VERIFYHOST(3) + +## CURLOPT_DOH_SSL_VERIFYHOST + +Verify the host name in the DoH (DNS-over-HTTPS) SSL certificate. See +CURLOPT_DOH_SSL_VERIFYHOST(3) + +## CURLOPT_PROXY_SSL_VERIFYHOST + +Verify the host name in the proxy SSL certificate. See +CURLOPT_PROXY_SSL_VERIFYHOST(3) + +## CURLOPT_SSL_VERIFYPEER + +Verify the SSL certificate. See CURLOPT_SSL_VERIFYPEER(3) + +## CURLOPT_DOH_SSL_VERIFYPEER + +Verify the DoH (DNS-over-HTTPS) SSL certificate. See +CURLOPT_DOH_SSL_VERIFYPEER(3) + +## CURLOPT_PROXY_SSL_VERIFYPEER + +Verify the proxy SSL certificate. See CURLOPT_PROXY_SSL_VERIFYPEER(3) + +## CURLOPT_SSL_VERIFYSTATUS + +Verify the SSL certificate's status. See CURLOPT_SSL_VERIFYSTATUS(3) + +## CURLOPT_DOH_SSL_VERIFYSTATUS + +Verify the DoH (DNS-over-HTTPS) SSL certificate's status. See +CURLOPT_DOH_SSL_VERIFYSTATUS(3) + +## CURLOPT_CAINFO + +CA cert bundle. See CURLOPT_CAINFO(3) + +## CURLOPT_CAINFO_BLOB + +CA cert bundle memory buffer. See CURLOPT_CAINFO_BLOB(3) + +## CURLOPT_PROXY_CAINFO + +Proxy CA cert bundle. See CURLOPT_PROXY_CAINFO(3) + +## CURLOPT_PROXY_CAINFO_BLOB + +Proxy CA cert bundle memory buffer. See CURLOPT_PROXY_CAINFO_BLOB(3) + +## CURLOPT_ISSUERCERT + +Issuer certificate. See CURLOPT_ISSUERCERT(3) + +## CURLOPT_ISSUERCERT_BLOB + +Issuer certificate memory buffer. See CURLOPT_ISSUERCERT_BLOB(3) + +## CURLOPT_PROXY_ISSUERCERT + +Proxy issuer certificate. See CURLOPT_PROXY_ISSUERCERT(3) + +## CURLOPT_PROXY_ISSUERCERT_BLOB + +Proxy issuer certificate memory buffer. See CURLOPT_PROXY_ISSUERCERT_BLOB(3) + +## CURLOPT_CAPATH + +Path to CA cert bundle. See CURLOPT_CAPATH(3) + +## CURLOPT_PROXY_CAPATH + +Path to proxy CA cert bundle. See CURLOPT_PROXY_CAPATH(3) + +## CURLOPT_CRLFILE + +Certificate Revocation List. See CURLOPT_CRLFILE(3) + +## CURLOPT_PROXY_CRLFILE + +Proxy Certificate Revocation List. See CURLOPT_PROXY_CRLFILE(3) + +## CURLOPT_CA_CACHE_TIMEOUT + +Timeout for CA cache. See CURLOPT_CA_CACHE_TIMEOUT(3) + +## CURLOPT_CERTINFO + +Extract certificate info. See CURLOPT_CERTINFO(3) + +## CURLOPT_PINNEDPUBLICKEY + +Set pinned SSL public key . See CURLOPT_PINNEDPUBLICKEY(3) + +## CURLOPT_PROXY_PINNEDPUBLICKEY + +Set the proxy's pinned SSL public key. See +CURLOPT_PROXY_PINNEDPUBLICKEY(3) + +## CURLOPT_RANDOM_FILE + +**OBSOLETE** Provide source for entropy random data. +See CURLOPT_RANDOM_FILE(3) + +## CURLOPT_EGDSOCKET + +**OBSOLETE** Identify EGD socket for entropy. See CURLOPT_EGDSOCKET(3) + +## CURLOPT_SSL_CIPHER_LIST + +Ciphers to use. See CURLOPT_SSL_CIPHER_LIST(3) + +## CURLOPT_PROXY_SSL_CIPHER_LIST + +Proxy ciphers to use. See CURLOPT_PROXY_SSL_CIPHER_LIST(3) + +## CURLOPT_TLS13_CIPHERS + +TLS 1.3 cipher suites to use. See CURLOPT_TLS13_CIPHERS(3) + +## CURLOPT_PROXY_TLS13_CIPHERS + +Proxy TLS 1.3 cipher suites to use. See CURLOPT_PROXY_TLS13_CIPHERS(3) + +## CURLOPT_SSL_SESSIONID_CACHE + +Disable SSL session-id cache. See CURLOPT_SSL_SESSIONID_CACHE(3) + +## CURLOPT_SSL_OPTIONS + +Control SSL behavior. See CURLOPT_SSL_OPTIONS(3) + +## CURLOPT_PROXY_SSL_OPTIONS + +Control proxy SSL behavior. See CURLOPT_PROXY_SSL_OPTIONS(3) + +## CURLOPT_KRBLEVEL + +Kerberos security level. See CURLOPT_KRBLEVEL(3) + +## CURLOPT_GSSAPI_DELEGATION + +Disable GSS-API delegation. See CURLOPT_GSSAPI_DELEGATION(3) + +# SSH OPTIONS + +## CURLOPT_SSH_AUTH_TYPES + +SSH authentication types. See CURLOPT_SSH_AUTH_TYPES(3) + +## CURLOPT_SSH_COMPRESSION + +Enable SSH compression. See CURLOPT_SSH_COMPRESSION(3) + +## CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 + +MD5 of host's public key. See CURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3) + +## CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 + +SHA256 of host's public key. See CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3) + +## CURLOPT_SSH_PUBLIC_KEYFILE + +File name of public key. See CURLOPT_SSH_PUBLIC_KEYFILE(3) + +## CURLOPT_SSH_PRIVATE_KEYFILE + +File name of private key. See CURLOPT_SSH_PRIVATE_KEYFILE(3) + +## CURLOPT_SSH_KNOWNHOSTS + +File name with known hosts. See CURLOPT_SSH_KNOWNHOSTS(3) + +## CURLOPT_SSH_KEYFUNCTION + +Callback for known hosts handling. See CURLOPT_SSH_KEYFUNCTION(3) + +## CURLOPT_SSH_KEYDATA + +Custom pointer to pass to ssh key callback. See CURLOPT_SSH_KEYDATA(3) + +## CURLOPT_SSH_HOSTKEYFUNCTION + +Callback for checking host key handling. See CURLOPT_SSH_HOSTKEYFUNCTION(3) + +## CURLOPT_SSH_HOSTKEYDATA + +Custom pointer to pass to ssh host key callback. See CURLOPT_SSH_HOSTKEYDATA(3) + +# WEBSOCKET + +## CURLOPT_WS_OPTIONS + +Set WebSocket options. See CURLOPT_WS_OPTIONS(3) + +# OTHER OPTIONS + +## CURLOPT_PRIVATE + +Private pointer to store. See CURLOPT_PRIVATE(3) + +## CURLOPT_SHARE + +Share object to use. See CURLOPT_SHARE(3) + +## CURLOPT_NEW_FILE_PERMS + +Mode for creating new remote files. See CURLOPT_NEW_FILE_PERMS(3) + +## CURLOPT_NEW_DIRECTORY_PERMS + +Mode for creating new remote directories. See CURLOPT_NEW_DIRECTORY_PERMS(3) + +## CURLOPT_QUICK_EXIT + +To be set by toplevel tools like "curl" to skip lengthy cleanups when they are +about to call exit() anyway. See CURLOPT_QUICK_EXIT(3) + +# TELNET OPTIONS + +## CURLOPT_TELNETOPTIONS + +TELNET options. See CURLOPT_TELNETOPTIONS(3) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +*CURLE_OK* (zero) means that the option was set properly, non-zero means an +error occurred as ** defines. See the libcurl-errors(3) man page +for the full list with descriptions. + +Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise +curl_easy_setopt(3) returns **CURLE_BAD_FUNCTION_ARGUMENT** (added in 7.65.0). + +**CURLE_BAD_FUNCTION_ARGUMENT** is returned when the argument to an option is +invalid, like perhaps out of range. + +If you try to set an option that libcurl does not know about, perhaps because +the library is too old to support it or the option was removed in a recent +version, this function returns *CURLE_UNKNOWN_OPTION*. If support for the +option was disabled at compile-time, it returns *CURLE_NOT_BUILT_IN*. diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 deleted file mode 100644 index 87a8f77b98c..00000000000 --- a/docs/libcurl/curl_easy_strerror.3 +++ /dev/null @@ -1,64 +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 -.\" * -.\" ************************************************************************** -.TH curl_easy_strerror 3 "26 Apr 2004" "libcurl" "libcurl" -.SH NAME -curl_easy_strerror - return string describing error code -.SH SYNOPSIS -.nf -#include - -const char *curl_easy_strerror(CURLcode errornum); -.fi -.SH DESCRIPTION -The \fIcurl_easy_strerror(3)\fP function returns a string describing the -CURLcode error code passed in the argument \fIerrornum\fP. - -Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more -specific error descriptions generated at runtime. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - /* set options */ - /* Perform the entire transfer */ - res = curl_easy_perform(curl); - /* Check for errors */ - if(res != CURLE_OK) - fprintf(stderr, "curl_easy_perform() failed: %s\\n", - curl_easy_strerror(res)); - } -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.12.0 -.SH RETURN VALUE -A pointer to a null-terminated string. -.SH "SEE ALSO" -.BR libcurl-errors (3), -.BR curl_multi_strerror (3), -.BR curl_share_strerror (3), -.BR curl_url_strerror (3) diff --git a/docs/libcurl/curl_easy_strerror.md b/docs/libcurl/curl_easy_strerror.md new file mode 100644 index 00000000000..218601a4446 --- /dev/null +++ b/docs/libcurl/curl_easy_strerror.md @@ -0,0 +1,59 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_strerror +Section: 3 +Source: libcurl +See-also: + - curl_multi_strerror (3) + - curl_share_strerror (3) + - curl_url_strerror (3) + - libcurl-errors (3) +--- + +# NAME + +curl_easy_strerror - return string describing error code + +# SYNOPSIS + +~~~c +#include + +const char *curl_easy_strerror(CURLcode errornum); +~~~ + +# DESCRIPTION + +The curl_easy_strerror(3) function returns a string describing the +CURLcode error code passed in the argument *errornum*. + +Typically applications also appreciate CURLOPT_ERRORBUFFER(3) for more +specific error descriptions generated at runtime. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + /* set options */ + /* Perform the entire transfer */ + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + } +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.12.0 + +# RETURN VALUE + +A pointer to a null-terminated string. diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3 deleted file mode 100644 index 9c52cbfa546..00000000000 --- a/docs/libcurl/curl_easy_unescape.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_easy_unescape 3 "7 April 2006" "libcurl" "libcurl" -.SH NAME -curl_easy_unescape - URL decodes the given string -.SH SYNOPSIS -.nf -#include - -char *curl_easy_unescape(CURL *curl, const char *input, - int inlength, int *outlength); -.fi -.SH DESCRIPTION -This function converts the URL encoded string \fBinput\fP to a "plain string" -and returns that in an allocated memory area. All input characters that are URL -encoded (%XX where XX is a two-digit hexadecimal number) are converted to their -binary versions. - -If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP -uses strlen() on \fBinput\fP to find out the size. - -If \fBoutlength\fP is non-NULL, the function writes the length of the returned -string in the integer it points to. This allows proper handling even for -strings containing %00. Since this is a pointer to an \fIint\fP type, it can -only return a value up to \fIINT_MAX\fP so no longer string can be returned in -this parameter. - -Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was -per-handle character conversion support for some old operating systems such as -TPF, but it was otherwise ignored. - -You must \fIcurl_free(3)\fP the returned string when you are done with it. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - int decodelen; - char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen); - if(decoded) { - /* do not assume printf() works on the decoded data! */ - printf("Decoded: "); - /* ... */ - curl_free(decoded); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.4 and replaces the old \fIcurl_unescape(3)\fP function. -.SH RETURN VALUE -A pointer to a null-terminated string or NULL if it failed. -.SH "SEE ALSO" -.BR curl_easy_escape (3), -.BR curl_free (3) diff --git a/docs/libcurl/curl_easy_unescape.md b/docs/libcurl/curl_easy_unescape.md new file mode 100644 index 00000000000..4f9262b34ac --- /dev/null +++ b/docs/libcurl/curl_easy_unescape.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_unescape +Section: 3 +Source: libcurl +See-also: + - curl_easy_escape (3) + - curl_free (3) +--- + +# NAME + +curl_easy_unescape - URL decodes the given string + +# SYNOPSIS + +~~~c +#include + +char *curl_easy_unescape(CURL *curl, const char *input, + int inlength, int *outlength); +~~~ + +# DESCRIPTION + +This function converts the URL encoded string **input** to a "plain string" +and returns that in an allocated memory area. All input characters that are URL +encoded (%XX where XX is a two-digit hexadecimal number) are converted to their +binary versions. + +If the **length** argument is set to 0 (zero), curl_easy_unescape(3) +uses strlen() on **input** to find out the size. + +If **outlength** is non-NULL, the function writes the length of the returned +string in the integer it points to. This allows proper handling even for +strings containing %00. Since this is a pointer to an *int* type, it can +only return a value up to *INT_MAX* so no longer string can be returned in +this parameter. + +Since 7.82.0, the **curl** parameter is ignored. Prior to that there was +per-handle character conversion support for some old operating systems such as +TPF, but it was otherwise ignored. + +You must curl_free(3) the returned string when you are done with it. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + int decodelen; + char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen); + if(decoded) { + /* do not assume printf() works on the decoded data! */ + printf("Decoded: "); + /* ... */ + curl_free(decoded); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.4 and replaces the old curl_unescape(3) function. + +# RETURN VALUE + +A pointer to a null-terminated string or NULL if it failed. diff --git a/docs/libcurl/curl_easy_upkeep.3 b/docs/libcurl/curl_easy_upkeep.3 deleted file mode 100644 index b4d35716f4e..00000000000 --- a/docs/libcurl/curl_easy_upkeep.3 +++ /dev/null @@ -1,84 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_easy_upkeep 3 "31 Oct 2018" "libcurl" "libcurl" -.SH NAME -curl_easy_upkeep - Perform any connection upkeep checks. -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_upkeep(CURL *handle); -.fi -.SH DESCRIPTION - -Some protocols have "connection upkeep" mechanisms. These mechanisms usually -send some traffic on existing connections in order to keep them alive; this -can prevent connections from being closed due to overzealous firewalls, for -example. - -Currently the only protocol with a connection upkeep mechanism is HTTP/2: when -the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP -is called, an HTTP/2 PING frame is sent on the connection. - -This function must be explicitly called in order to perform the upkeep work. -The connection upkeep interval is set with -\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* Make a connection to an HTTP/2 server. */ - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Set the interval to 30000ms / 30s */ - curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); - - curl_easy_perform(curl); - - /* Perform more work here. */ - - /* While the connection is being held open, curl_easy_upkeep() can be - called. If curl_easy_upkeep() is called and the time since the last - upkeep exceeds the interval, then an HTTP/2 PING is sent. */ - curl_easy_upkeep(curl); - - /* Perform more work here. */ - - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.62.0. -.SH RETURN VALUE -On success, returns \fBCURLE_OK\fP. - -On failure, returns the appropriate error code. -.SH SEE ALSO -.BR CURLOPT_TCP_KEEPALIVE "(3), " -.BR CURLOPT_TCP_KEEPIDLE "(3), " diff --git a/docs/libcurl/curl_easy_upkeep.md b/docs/libcurl/curl_easy_upkeep.md new file mode 100644 index 00000000000..2ad89d3bbc1 --- /dev/null +++ b/docs/libcurl/curl_easy_upkeep.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_easy_upkeep +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TCP_KEEPALIVE (3) + - CURLOPT_TCP_KEEPIDLE (3) +--- + +# NAME + +curl_easy_upkeep - Perform any connection upkeep checks. + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_upkeep(CURL *handle); +~~~ + +# DESCRIPTION + +Some protocols have "connection upkeep" mechanisms. These mechanisms usually +send some traffic on existing connections in order to keep them alive; this +can prevent connections from being closed due to overzealous firewalls, for +example. + +Currently the only protocol with a connection upkeep mechanism is HTTP/2: when +the connection upkeep interval is exceeded and curl_easy_upkeep(3) +is called, an HTTP/2 PING frame is sent on the connection. + +This function must be explicitly called in order to perform the upkeep work. +The connection upkeep interval is set with +CURLOPT_UPKEEP_INTERVAL_MS(3). + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* Make a connection to an HTTP/2 server. */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the interval to 30000ms / 30s */ + curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); + + curl_easy_perform(curl); + + /* Perform more work here. */ + + /* While the connection is being held open, curl_easy_upkeep() can be + called. If curl_easy_upkeep() is called and the time since the last + upkeep exceeds the interval, then an HTTP/2 PING is sent. */ + curl_easy_upkeep(curl); + + /* Perform more work here. */ + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.62.0. + +# RETURN VALUE + +On success, returns **CURLE_OK**. + +On failure, returns the appropriate error code. diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 deleted file mode 100644 index 1cd2625401c..00000000000 --- a/docs/libcurl/curl_escape.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.TH curl_escape 3 "6 March 2002" "libcurl" "libcurl" -.SH NAME -curl_escape - URL encodes the given string -.SH SYNOPSIS -.nf -#include - -char *curl_escape(const char *string, int length); -.fi -.SH DESCRIPTION -Obsolete function. Use \fIcurl_easy_escape(3)\fP instead! - -This function converts the given input \fBstring\fP to a URL encoded string -and return that as a new allocated string. All input characters that are not -a-z, A-Z or 0-9 are converted to their "URL escaped" version (\fB%NN\fP where -\fBNN\fP is a two-digit hexadecimal number). - -If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP uses strlen() -on \fBstring\fP to find out the size. - -You must \fIcurl_free(3)\fP the returned string when you are done with it. -.SH EXAMPLE -.nf -int main(void) -{ - char *output = curl_escape("data to convert", 15); - if(output) { - printf("Encoded: %s\\n", output); - curl_free(output); - } -} -.fi -.SH AVAILABILITY -Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function might be -removed in a future release. -.SH RETURN VALUE -A pointer to a null-terminated string or NULL if it failed. -.SH "SEE ALSO" -.BR curl_unescape (3), -.BR curl_free (3) diff --git a/docs/libcurl/curl_escape.md b/docs/libcurl/curl_escape.md new file mode 100644 index 00000000000..e5e7e92b745 --- /dev/null +++ b/docs/libcurl/curl_escape.md @@ -0,0 +1,58 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_escape +Section: 3 +Source: libcurl +See-also: + - curl_free (3) + - curl_unescape (3) +--- + +# NAME + +curl_escape - URL encodes the given string + +# SYNOPSIS + +~~~c +#include + +char *curl_escape(const char *string, int length); +~~~ + +# DESCRIPTION + +Obsolete function. Use curl_easy_escape(3) instead! + +This function converts the given input **string** to a URL encoded string +and return that as a new allocated string. All input characters that are not +a-z, A-Z or 0-9 are converted to their "URL escaped" version (**%NN** where +**NN** is a two-digit hexadecimal number). + +If the **length** argument is set to 0, curl_escape(3) uses strlen() +on **string** to find out the size. + +You must curl_free(3) the returned string when you are done with it. + +# EXAMPLE + +~~~c +int main(void) +{ + char *output = curl_escape("data to convert", 15); + if(output) { + printf("Encoded: %s\n", output); + curl_free(output); + } +} +~~~ + +# AVAILABILITY + +Since 7.15.4, curl_easy_escape(3) should be used. This function might be +removed in a future release. + +# RETURN VALUE + +A pointer to a null-terminated string or NULL if it failed. diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.md similarity index 59% rename from docs/libcurl/curl_formadd.3 rename to docs/libcurl/curl_formadd.md index 8d8e91d898c..901c24c3bb6 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.md @@ -1,55 +1,48 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_formadd 3 "24 June 2002" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_formadd +Section: 3 +Source: libcurl +See-also: + - curl_easy_setopt (3) + - curl_formfree (3) + - curl_mime_init (3) +--- + +# NAME + curl_formadd - add a section to a multipart form POST -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLFORMcode curl_formadd(struct curl_httppost **firstitem, struct curl_httppost **lastitem, ...); -.fi -.SH DESCRIPTION -\fBThis function is deprecated.\fP Use \fIcurl_mime_init(3)\fP instead. +~~~ + +# DESCRIPTION + +**This function is deprecated.** Use curl_mime_init(3) instead. curl_formadd() is used to append sections when building a multipart form post. Append one section at a time until you have added all the sections you -want included and then you pass the \fIfirstitem\fP pointer as parameter to -\fICURLOPT_HTTPPOST(3)\fP. \fIlastitem\fP is set after each -\fIcurl_formadd(3)\fP call and on repeated invokes it should be left as set to -allow repeated invokes to find the end of the list faster. +want included and then you pass the *firstitem* pointer as parameter to +CURLOPT_HTTPPOST(3). *lastitem* is set after each curl_formadd(3) call and +on repeated invokes it should be left as set to allow repeated invokes to find +the end of the list faster. -After the \fIlastitem\fP pointer follow the real arguments. +After the *lastitem* pointer follow the real arguments. -The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to +The pointers *firstitem* and *lastitem* should both be pointing to NULL in the first call to this function. All list-data is allocated by the -function itself. You must call \fIcurl_formfree(3)\fP on the \fIfirstitem\fP +function itself. You must call curl_formfree(3) on the *firstitem* after the form post has been done to free the resources. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. -You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. +You can disable this header with CURLOPT_HTTPHEADER(3) as usual. First, there are some basics you need to understand about multipart form posts. Each part consists of at least a NAME and a CONTENTS part. If the part @@ -58,123 +51,158 @@ Below, we discuss what options you use to set these properties in the parts you want to add to your post. The options listed first are for making normal parts. The options from -\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload +*CURLFORM_FILE* through *CURLFORM_BUFFERLENGTH* are for file upload parts. -.SH OPTIONS -.IP CURLFORM_COPYNAME -followed by a string which provides the \fIname\fP of this part. libcurl + +# OPTIONS + +## CURLFORM_COPYNAME + +followed by a string which provides the *name* of this part. libcurl copies the string so your application does not need to keep it around after this function call. If the name is not null-terminated, you must set its -length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to -contain zero-valued bytes. The copied data is freed by \fIcurl_formfree(3)\fP. -.IP CURLFORM_PTRNAME -followed by a string which provides the \fIname\fP of this part. libcurl uses -the pointer and refer to the data in your application, so you must make sure -it remains until curl no longer needs it. If the name is not null-terminated, -you must set its length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not -allowed to contain zero-valued bytes. -.IP CURLFORM_COPYCONTENTS +length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to +contain zero-valued bytes. The copied data is freed by curl_formfree(3). + +## CURLFORM_PTRNAME + +followed by a string which provides the *name* of this part. libcurl uses the +pointer and refer to the data in your application, so you must make sure it +remains until curl no longer needs it. If the name is not null-terminated, you +must set its length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to +contain zero-valued bytes. + +## CURLFORM_COPYCONTENTS + followed by a pointer to the contents of this part, the actual data to send away. libcurl copies the provided data, so your application does not need to keep it around after this function call. If the data is not null terminated, or if you would like it to contain zero bytes, you must set the length of the -name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data is freed by -\fIcurl_formfree(3)\fP. -.IP CURLFORM_PTRCONTENTS +name with **CURLFORM_CONTENTSLENGTH**. The copied data is freed by +curl_formfree(3). + +## CURLFORM_PTRCONTENTS + followed by a pointer to the contents of this part, the actual data to send away. libcurl uses the pointer and refer to the data in your application, so -you must make sure it remains until curl no longer needs it. If the data is +you must make sure it remains until curl no longer needs it. If the data is not null-terminated, or if you would like it to contain zero bytes, you must -set its length with \fBCURLFORM_CONTENTSLENGTH\fP. -.IP CURLFORM_CONTENTLEN +set its length with **CURLFORM_CONTENTSLENGTH**. + +## CURLFORM_CONTENTLEN + followed by a curl_off_t value giving the length of the contents. Note that -for \fICURLFORM_STREAM\fP contents, this option is mandatory. +for *CURLFORM_STREAM* contents, this option is mandatory. If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents to figure out the size. If you really want to send a zero byte content then you must make sure strlen() on the data pointer returns zero. (Option added in 7.46.0) -.IP CURLFORM_CONTENTSLENGTH -(This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!) + +## CURLFORM_CONTENTSLENGTH + +(This option is deprecated. Use *CURLFORM_CONTENTLEN* instead!) followed by a long giving the length of the contents. Note that for -\fICURLFORM_STREAM\fP contents, this option is mandatory. +*CURLFORM_STREAM* contents, this option is mandatory. If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents to figure out the size. If you really want to send a zero byte content then you must make sure strlen() on the data pointer returns zero. -.IP CURLFORM_FILECONTENT + +## CURLFORM_FILECONTENT + followed by a filename, causes that file to be read and its contents used -as data in this part. This part does \fInot\fP automatically become a file +as data in this part. This part does *not* automatically become a file upload part simply because its data was read from a file. The specified file needs to kept around until the associated transfer is done. -.IP CURLFORM_FILE + +## CURLFORM_FILE + followed by a filename, makes this part a file upload part. It sets the -\fIfilename\fP field to the basename of the provided filename, it reads the +*filename* field to the basename of the provided filename, it reads the contents of the file and passes them as data and sets the content-type if the given file match one of the internally known file extensions. For -\fBCURLFORM_FILE\fP the user may send one or more files in one part by -providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename -(and each \fICURLFORM_FILE\fP is allowed to have a -\fICURLFORM_CONTENTTYPE\fP). +**CURLFORM_FILE** the user may send one or more files in one part by +providing multiple **CURLFORM_FILE** arguments each followed by the filename +(and each *CURLFORM_FILE* is allowed to have a +*CURLFORM_CONTENTTYPE*). The given upload file has to exist in its full in the file system already when the upload starts, as libcurl needs to read the correct file size beforehand. The specified file needs to kept around until the associated transfer is done. -.IP CURLFORM_CONTENTTYPE -is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a + +## CURLFORM_CONTENTTYPE + +is used in combination with *CURLFORM_FILE*. Followed by a pointer to a string which provides the content-type for this part, possibly instead of an internally chosen one. -.IP CURLFORM_FILENAME -is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a -string, it tells libcurl to use the given string as the \fIfilename\fP in the + +## CURLFORM_FILENAME + +is used in combination with *CURLFORM_FILE*. Followed by a pointer to a +string, it tells libcurl to use the given string as the *filename* in the file upload part instead of the actual file name. -.IP CURLFORM_BUFFER -is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It + +## CURLFORM_BUFFER + +is used for custom file upload parts without use of *CURLFORM_FILE*. It tells libcurl that the file contents are already present in a buffer. The -parameter is a string which provides the \fIfilename\fP field in the content +parameter is a string which provides the *filename* field in the content header. -.IP CURLFORM_BUFFERPTR -is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer + +## CURLFORM_BUFFERPTR + +is used in combination with *CURLFORM_BUFFER*. The parameter is a pointer to the buffer to be uploaded. This buffer must not be freed until after -\fIcurl_easy_cleanup(3)\fP is called. You must also use -\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. -.IP CURLFORM_BUFFERLENGTH -is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a +curl_easy_cleanup(3) is called. You must also use +*CURLFORM_BUFFERLENGTH* to set the number of bytes in the buffer. + +## CURLFORM_BUFFERLENGTH + +is used in combination with *CURLFORM_BUFFER*. The parameter is a long which gives the length of the buffer. -.IP CURLFORM_STREAM -Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get -data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on + +## CURLFORM_STREAM + +Tells libcurl to use the CURLOPT_READFUNCTION(3) callback to get +data. The parameter you pass to *CURLFORM_STREAM* is the pointer passed on to the read callback's fourth argument. If you want the part to look like a -file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that -when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be +file upload one, set the *CURLFORM_FILENAME* parameter as well. Note that +when using *CURLFORM_STREAM*, *CURLFORM_CONTENTSLENGTH* must also be set with the total expected length of the part unless the formpost is sent chunked encoded. (Option added in libcurl 7.18.2) -.IP CURLFORM_ARRAY + +## CURLFORM_ARRAY + Another possibility to send options to curl_formadd() is the -\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as -its value. Each curl_forms structure element has a \fICURLformoption\fP and a +**CURLFORM_ARRAY** option, that passes a struct curl_forms array pointer as +its value. Each curl_forms structure element has a *CURLformoption* and a char pointer. The final element in the array must be a CURLFORM_END. All available options can be used in an array, except the CURLFORM_ARRAY option -itself. The last argument in such an array must always be \fBCURLFORM_END\fP. -.IP CURLFORM_CONTENTHEADER +itself. The last argument in such an array must always be **CURLFORM_END**. + +## CURLFORM_CONTENTHEADER + specifies extra headers for the form POST section. This takes a curl_slist -prepared in the usual way using \fBcurl_slist_append\fP and appends the list +prepared in the usual way using **curl_slist_append** and appends the list of headers to those libcurl automatically generates. The list must exist while the POST occurs, if you free it before the post completes you may experience problems. -When you have passed the \fIstruct curl_httppost\fP pointer to -\fIcurl_easy_setopt(3)\fP (using the \fICURLOPT_HTTPPOST(3)\fP option), you -must not free the list until after you have called \fIcurl_easy_cleanup(3)\fP +When you have passed the *struct curl_httppost* pointer to +curl_easy_setopt(3) (using the CURLOPT_HTTPPOST(3) option), you +must not free the list until after you have called curl_easy_cleanup(3) for the curl handle. See example below. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c #include /* for strlen */ static const char record[]="data in a buffer"; @@ -196,7 +224,7 @@ int main(void) /* add null character into htmlbuffer, to demonstrate that transfers of buffers containing null characters actually work */ - htmlbuffer[8] = '\\0'; + htmlbuffer[8] = '\0'; /* Add simple name/content section */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", @@ -267,19 +295,19 @@ int main(void) curl_formfree(post); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Deprecated in 7.56.0. Before this release, field names were allowed to contain zero-valued bytes. The pseudo-filename "-" to read stdin is discouraged although still supported, but data is not read before being actually sent: the effective data size can then not be automatically determined, resulting in a chunked encoding transfer. Backslashes and double quotes in field and file names are now escaped before transmission. -.SH RETURN VALUE + +# RETURN VALUE + 0 means everything was OK, non-zero means an error occurred corresponding to a CURL_FORMADD_* constant defined in -.I -.SH "SEE ALSO" -.BR curl_easy_setopt (3), -.BR curl_formfree (3), -.BR curl_mime_init (3) +** diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 deleted file mode 100644 index b3166745e15..00000000000 --- a/docs/libcurl/curl_formfree.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.TH curl_formfree 3 "6 April 2001" "libcurl" "libcurl" -.SH NAME -curl_formfree - free a previously build multipart form post chain -.SH SYNOPSIS -.nf -#include - -void curl_formfree(struct curl_httppost *form); -.fi -.SH DESCRIPTION -This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead! - -curl_formfree() is used to clean up data previously built/appended with -\fIcurl_formadd(3)\fP. This must be called when the data has been used, which -typically means after \fIcurl_easy_perform(3)\fP has been called. - -The pointer to free is the same pointer you passed to the -\fICURLOPT_HTTPPOST(3)\fP option, which is the \fIfirstitem\fP pointer from -the \fIcurl_formadd(3)\fP invoke(s). - -\fBform\fP is the pointer as returned from a previous call to -\fIcurl_formadd(3)\fP and may be NULL. - -Passing in a NULL pointer in \fIform\fP makes this function return immediately -with no action. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct curl_httppost *formpost; - struct curl_httppost *lastptr; - - /* Fill in a file upload field */ - curl_formadd(&formpost, - &lastptr, - CURLFORM_COPYNAME, "file", - CURLFORM_FILE, "nice-image.jpg", - CURLFORM_END); - - curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); - - curl_easy_perform(curl); - - /* then cleanup the formpost chain */ - curl_formfree(formpost); - } -} -.fi -.SH AVAILABILITY -Deprecated in 7.56.0. -.SH RETURN VALUE -None -.SH "SEE ALSO" -.BR curl_formadd (3), -.BR curl_mime_init (3), -.BR curl_mime_free (3) diff --git a/docs/libcurl/curl_formfree.md b/docs/libcurl/curl_formfree.md new file mode 100644 index 00000000000..d2f90c03fba --- /dev/null +++ b/docs/libcurl/curl_formfree.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_formfree +Section: 3 +Source: libcurl +See-also: + - curl_formadd (3) + - curl_mime_free (3) + - curl_mime_init (3) +--- + +# NAME + +curl_formfree - free a previously build multipart form post chain + +# SYNOPSIS + +~~~c +#include + +void curl_formfree(struct curl_httppost *form); +~~~ + +# DESCRIPTION + +This function is deprecated. Do not use. See curl_mime_init(3) instead! + +curl_formfree() is used to clean up data previously built/appended with +curl_formadd(3). This must be called when the data has been used, which +typically means after curl_easy_perform(3) has been called. + +The pointer to free is the same pointer you passed to the +CURLOPT_HTTPPOST(3) option, which is the *firstitem* pointer from +the curl_formadd(3) invoke(s). + +**form** is the pointer as returned from a previous call to +curl_formadd(3) and may be NULL. + +Passing in a NULL pointer in *form* makes this function return immediately +with no action. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_httppost *formpost; + struct curl_httppost *lastptr; + + /* Fill in a file upload field */ + curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "file", + CURLFORM_FILE, "nice-image.jpg", + CURLFORM_END); + + curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); + + curl_easy_perform(curl); + + /* then cleanup the formpost chain */ + curl_formfree(formpost); + } +} +~~~ + +# AVAILABILITY + +Deprecated in 7.56.0. + +# RETURN VALUE + +None diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 deleted file mode 100644 index 583092169f4..00000000000 --- a/docs/libcurl/curl_formget.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.TH curl_formget 3 "20 June 2006" "libcurl" "libcurl" -.SH NAME -curl_formget - serialize a previously built multipart form POST chain -.SH SYNOPSIS -.nf -#include - -int curl_formget(struct curl_httppost * form, void *userp, - curl_formget_callback append); -.fi -.SH DESCRIPTION -curl_formget() serializes data previously built with \fIcurl_formadd(3)\fP. It -accepts a void pointer as second argument named \fIuserp\fP which is passed as -the first argument to the curl_formget_callback function. - -.nf - typedef size_t (*curl_formget_callback)(void *userp, const char *buf, - size_t len);" -.fi - -The curl_formget_callback is invoked for each part of the HTTP POST chain. The -character buffer passed to the callback must not be freed. The callback should -return the buffer length passed to it on success. - -If the \fBCURLFORM_STREAM\fP option is used in the formpost, it prevents -\fIcurl_formget(3)\fP from working until you have performed the actual HTTP -request. This, because first then does libcurl known which actual read -callback to use! -.SH EXAMPLE -.nf -size_t print_httppost_callback(void *arg, const char *buf, size_t len) -{ - fwrite(buf, len, 1, stdout); - (*(size_t *) arg) += len; - return len; -} - -size_t print_httppost(struct curl_httppost *post) -{ - size_t total_size = 0; - if(curl_formget(post, &total_size, print_httppost_callback)) { - return (size_t) -1; - } - return total_size; -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.15.5. The form API is deprecated in -libcurl 7.56.0. -.SH RETURN VALUE -0 means everything was OK, non-zero means an error occurred -.SH "SEE ALSO" -.BR curl_formadd (3), -.BR curl_mime_init (3) diff --git a/docs/libcurl/curl_formget.md b/docs/libcurl/curl_formget.md new file mode 100644 index 00000000000..7130ee937ee --- /dev/null +++ b/docs/libcurl/curl_formget.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_formget +Section: 3 +Source: libcurl +See-also: + - curl_formadd (3) + - curl_mime_init (3) +--- + +# NAME + +curl_formget - serialize a previously built multipart form POST chain + +# SYNOPSIS + +~~~c +#include + +int curl_formget(struct curl_httppost * form, void *userp, + curl_formget_callback append); +~~~ + +# DESCRIPTION + +curl_formget() serializes data previously built with curl_formadd(3). It +accepts a void pointer as second argument named *userp* which is passed as +the first argument to the curl_formget_callback function. + +~~~c + typedef size_t (*curl_formget_callback)(void *userp, const char *buf, + size_t len);" +~~~ + +The curl_formget_callback is invoked for each part of the HTTP POST chain. The +character buffer passed to the callback must not be freed. The callback should +return the buffer length passed to it on success. + +If the **CURLFORM_STREAM** option is used in the formpost, it prevents +curl_formget(3) from working until you have performed the actual HTTP +request. This, because first then does libcurl known which actual read +callback to use! + +# EXAMPLE + +~~~c +size_t print_httppost_callback(void *arg, const char *buf, size_t len) +{ + fwrite(buf, len, 1, stdout); + (*(size_t *) arg) += len; + return len; +} + +size_t print_httppost(struct curl_httppost *post) +{ + size_t total_size = 0; + if(curl_formget(post, &total_size, print_httppost_callback)) { + return (size_t) -1; + } + return total_size; +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.15.5. The form API is deprecated in +libcurl 7.56.0. + +# RETURN VALUE + +0 means everything was OK, non-zero means an error occurred diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 deleted file mode 100644 index f29d8f1e1db..00000000000 --- a/docs/libcurl/curl_free.3 +++ /dev/null @@ -1,57 +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 -.\" * -.\" ************************************************************************** -.TH curl_free 3 "12 Aug 2003" "libcurl" "libcurl" -.SH NAME -curl_free - reclaim memory that has been obtained through a libcurl call -.SH SYNOPSIS -.nf -#include - -void curl_free(void *ptr); -.fi -.SH DESCRIPTION -curl_free reclaims memory that has been obtained through a libcurl call. Use -\fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from -differences in memory management between your application and libcurl. - -Passing in a NULL pointer in \fIptr\fP makes this function return immediately -with no action. -.SH EXAMPLE -.nf -int main(void) -{ - char *width = curl_getenv("COLUMNS"); - if(width) { - /* it was set! */ - curl_free(width); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -None -.SH "SEE ALSO" -.BR curl_easy_escape (3), -.BR curl_easy_unescape (3) diff --git a/docs/libcurl/curl_free.md b/docs/libcurl/curl_free.md new file mode 100644 index 00000000000..69639405560 --- /dev/null +++ b/docs/libcurl/curl_free.md @@ -0,0 +1,52 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_free +Section: 3 +Source: libcurl +See-also: + - curl_easy_escape (3) + - curl_easy_unescape (3) +--- + +# NAME + +curl_free - reclaim memory that has been obtained through a libcurl call + +# SYNOPSIS + +~~~c +#include + +void curl_free(void *ptr); +~~~ + +# DESCRIPTION + +curl_free reclaims memory that has been obtained through a libcurl call. Use +curl_free(3) instead of free() to avoid anomalies that can result from +differences in memory management between your application and libcurl. + +Passing in a NULL pointer in *ptr* makes this function return immediately +with no action. + +# EXAMPLE + +~~~c +int main(void) +{ + char *width = curl_getenv("COLUMNS"); + if(width) { + /* it was set! */ + curl_free(width); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +None diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.md similarity index 65% rename from docs/libcurl/curl_getdate.3 rename to docs/libcurl/curl_getdate.md index 91c55235fae..e4fbf039442 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.md @@ -1,70 +1,77 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_getdate 3 "12 Aug 2005" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_getdate +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TIMECONDITION (3) + - CURLOPT_TIMEVALUE (3) + - curl_easy_escape (3) + - curl_easy_unescape (3) +--- + +# NAME + curl_getdate - Convert a date string to number of seconds -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include time_t curl_getdate(const char *datestring, const time_t *now); -.fi -.SH DESCRIPTION -\fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January +~~~ + +# DESCRIPTION + +curl_getdate(3) returns the number of seconds since the Epoch, January 1st 1970 00:00:00 in the UTC time zone, for the date and time that the -\fIdatestring\fP parameter specifies. The \fInow\fP parameter is not used, +*datestring* parameter specifies. The *now* parameter is not used, pass a NULL there. This function works with valid dates and does not always detect and reject wrong dates, such as February 30. -.SH PARSING DATES AND TIMES +# PARSING DATES AND TIMES + A "date" is a string containing several items separated by whitespace. The order of the items is immaterial. A date string may contain many flavors of items: -.IP "calendar date items" + +## calendar date items + Can be specified several ways. Month names can only be three-letter English abbreviations, numbers can be zero-prefixed and the year may use 2 or 4 -digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. -.IP "time of the day items" +digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. + +## time of the day items + This string specifies the time on a given day. You must specify it with 6 digits with two colons: HH:MM:SS. If there is no time given in a provided date string, 00:00:00 is assumed. Example: 18:19:21. -.IP "time zone items" + +## time zone items + Specifies international time zone. There are a few acronyms supported, but in general you should instead use the specific relative time compared to UTC. Supported formats include: -1200, MST, +0100. -.IP "day of the week items" + +## day of the week items + Specifies a day of the week. Days of the week may be spelled out in full (using English): `Sunday', `Monday', etc or they may be abbreviated to their first three letters. This is usually not info that adds anything. -.IP "pure numbers" + +## pure numbers + If a decimal number of the form YYYYMMDD appears, then YYYY is read as the year, MM as the month number and DD as the day of the month, for the specified calendar date. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { time_t t; @@ -91,16 +98,22 @@ int main(void) t = curl_getdate("20040912 15:05:58 -0700", NULL); t = curl_getdate("20040911 +0200", NULL); } -.fi -.SH STANDARDS +~~~ + +# STANDARDS + This parser handles date formats specified in RFC 822 (including the update in RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by -RFC 1036) and ANSI C's \fIasctime()\fP format. +RFC 1036) and ANSI C's *asctime()* format. These formats are the only ones RFC 7231 says HTTP applications may use. -.SH AVAILABILITY + +# AVAILABILITY + Always -.SH RETURN VALUE + +# RETURN VALUE + This function returns -1 when it fails to parse the date string. Otherwise it returns the number of seconds as described. @@ -113,8 +126,3 @@ less than 1970, this function returns -1. On systems with 64 bit time_t: if the year is less than 1583, this function returns -1. (The Gregorian calendar was first introduced 1582 so no "real" dates in this way of doing dates existed before then.) -.SH "SEE ALSO" -.BR curl_easy_escape (3), -.BR curl_easy_unescape (3), -.BR CURLOPT_TIMECONDITION (3), -.BR CURLOPT_TIMEVALUE (3) diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 deleted file mode 100644 index a13d596710f..00000000000 --- a/docs/libcurl/curl_getenv.3 +++ /dev/null @@ -1,60 +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 -.\" * -.\" ************************************************************************** -.TH curl_getenv 3 "30 April 2004" "libcurl" "libcurl" -.SH NAME -curl_getenv - return value for environment name -.SH SYNOPSIS -.nf -#include - -char *curl_getenv(const char *name); -.fi -.SH DESCRIPTION -curl_getenv() is a portable wrapper for the getenv() function, meant to -emulate its behavior and provide an identical interface for all operating -systems libcurl builds on (including win32). - -You must \fIcurl_free(3)\fP the returned string when you are done with it. -.SH EXAMPLE -.nf -int main(void) -{ - char *width = curl_getenv("COLUMNS"); - if(width) { - /* it was set! */ - curl_free(width); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -A pointer to a null-terminated string or NULL if it failed to find the -specified name. -.SH NOTE -Under unix operating systems, there is no point in returning an allocated -memory, although other systems does not work properly if this is not done. The -unix implementation thus suffers slightly from the drawbacks of other systems. -.SH "SEE ALSO" -.BR getenv (3C) diff --git a/docs/libcurl/curl_getenv.md b/docs/libcurl/curl_getenv.md new file mode 100644 index 00000000000..dbf326d11be --- /dev/null +++ b/docs/libcurl/curl_getenv.md @@ -0,0 +1,57 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_getenv +Section: 3 +Source: libcurl +See-also: + - getenv (3C) +--- + +# NAME + +curl_getenv - return value for environment name + +# SYNOPSIS + +~~~c +#include + +char *curl_getenv(const char *name); +~~~ + +# DESCRIPTION + +curl_getenv() is a portable wrapper for the getenv() function, meant to +emulate its behavior and provide an identical interface for all operating +systems libcurl builds on (including win32). + +You must curl_free(3) the returned string when you are done with it. + +# EXAMPLE + +~~~c +int main(void) +{ + char *width = curl_getenv("COLUMNS"); + if(width) { + /* it was set! */ + curl_free(width); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +A pointer to a null-terminated string or NULL if it failed to find the +specified name. + +# NOTE + +Under unix operating systems, there is no point in returning an allocated +memory, although other systems does not work properly if this is not done. The +unix implementation thus suffers slightly from the drawbacks of other systems. diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3 deleted file mode 100644 index 75a0a01ac19..00000000000 --- a/docs/libcurl/curl_global_cleanup.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.TH curl_global_cleanup 3 "17 Feb 2006" "libcurl" "libcurl" -.SH NAME -curl_global_cleanup - global libcurl cleanup -.SH SYNOPSIS -.nf -#include - -void curl_global_cleanup(void); -.fi -.SH DESCRIPTION -This function releases resources acquired by \fIcurl_global_init(3)\fP. - -You should call \fIcurl_global_cleanup(3)\fP once for each call you make to -\fIcurl_global_init(3)\fP, after you are done using libcurl. - -This function is thread-safe since libcurl 7.84.0 if -\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set -(most platforms). - -If this is not thread-safe, you must not call this function when any other -thread in the program (i.e. a thread sharing the same memory) is running. -This does not just mean no other thread that is using libcurl. Because -\fIcurl_global_cleanup(3)\fP calls functions of other libraries that are -similarly thread unsafe, it could conflict with any other thread that uses -these other libraries. - -See the description in \fIlibcurl(3)\fP of global environment requirements for -details of how to use this function. -.SH CAUTION -\fIcurl_global_cleanup(3)\fP does not block waiting for any libcurl-created -threads to terminate (such as threads used for name resolving). If a module -containing libcurl is dynamically unloaded while libcurl-created threads are -still running then your program may crash or other corruption may occur. We -recommend you do not run libcurl from any module that may be unloaded -dynamically. This behavior may be addressed in the future. -.SH EXAMPLE -.nf -int main(void) -{ - curl_global_init(CURL_GLOBAL_DEFAULT); - - /* use libcurl, then before exiting... */ - - curl_global_cleanup(); -} -.fi -.SH AVAILABILITY -Added in 7.8 -.SH RETURN VALUE -None -.SH "SEE ALSO" -.BR curl_global_init (3), -.BR libcurl (3), -.BR libcurl-thread (3) diff --git a/docs/libcurl/curl_global_cleanup.md b/docs/libcurl/curl_global_cleanup.md new file mode 100644 index 00000000000..5502e718d09 --- /dev/null +++ b/docs/libcurl/curl_global_cleanup.md @@ -0,0 +1,74 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_global_cleanup +Section: 3 +Source: libcurl +See-also: + - curl_global_init (3) + - libcurl (3) + - libcurl-thread (3) +--- + +# NAME + +curl_global_cleanup - global libcurl cleanup + +# SYNOPSIS + +~~~c +#include + +void curl_global_cleanup(void); +~~~ + +# DESCRIPTION + +This function releases resources acquired by curl_global_init(3). + +You should call curl_global_cleanup(3) once for each call you make to +curl_global_init(3), after you are done using libcurl. + +This function is thread-safe since libcurl 7.84.0 if +curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set +(most platforms). + +If this is not thread-safe, you must not call this function when any other +thread in the program (i.e. a thread sharing the same memory) is running. +This does not just mean no other thread that is using libcurl. Because +curl_global_cleanup(3) calls functions of other libraries that are +similarly thread unsafe, it could conflict with any other thread that uses +these other libraries. + +See the description in libcurl(3) of global environment requirements for +details of how to use this function. + +# CAUTION + +curl_global_cleanup(3) does not block waiting for any libcurl-created +threads to terminate (such as threads used for name resolving). If a module +containing libcurl is dynamically unloaded while libcurl-created threads are +still running then your program may crash or other corruption may occur. We +recommend you do not run libcurl from any module that may be unloaded +dynamically. This behavior may be addressed in the future. + +# EXAMPLE + +~~~c +int main(void) +{ + curl_global_init(CURL_GLOBAL_DEFAULT); + + /* use libcurl, then before exiting... */ + + curl_global_cleanup(); +} +~~~ + +# AVAILABILITY + +Added in 7.8 + +# RETURN VALUE + +None diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.md similarity index 59% rename from docs/libcurl/curl_global_init.3 rename to docs/libcurl/curl_global_init.md index b7699910077..5c00e862d3a 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.md @@ -1,36 +1,32 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_global_init 3 "11 May 2004" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_global_init +Section: 3 +Source: libcurl +See-also: + - curl_easy_init (3) + - curl_global_cleanup (3) + - curl_global_init_mem (3) + - curl_global_sslset (3) + - curl_global_trace (3) + - libcurl (3) +--- + +# NAME + curl_global_init - Global libcurl initialization -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLcode curl_global_init(long flags); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This function sets up the program environment that libcurl needs. Think of it as an extension of the library loader. @@ -47,28 +43,32 @@ value unless you are familiar with it and mean to control internal operations of libcurl. This function is thread-safe since libcurl 7.84.0 if -\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set +curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set (most platforms). If this is not thread-safe, you must not call this function when any other thread in the program (i.e. a thread sharing the same memory) is running. This does not just mean no other thread that is using libcurl. Because -\fIcurl_global_init(3)\fP calls functions of other libraries that are +curl_global_init(3) calls functions of other libraries that are similarly thread unsafe, it could conflict with any other thread that uses these other libraries. If you are initializing libcurl from a Windows DLL you should not initialize -it from \fIDllMain\fP or a static initializer because Windows holds the loader +it from *DllMain* or a static initializer because Windows holds the loader lock during that time and it could cause a deadlock. -See the description in \fIlibcurl(3)\fP of global environment requirements for +See the description in libcurl(3) of global environment requirements for details of how to use this function. -.SH FLAGS -.IP CURL_GLOBAL_ALL + +# FLAGS + +## CURL_GLOBAL_ALL + Initialize everything possible. This sets all known bits except -\fBCURL_GLOBAL_ACK_EINTR\fP. +**CURL_GLOBAL_ACK_EINTR**. + +## CURL_GLOBAL_SSL -.IP CURL_GLOBAL_SSL (This flag's presence or absence serves no meaning since 7.57.0. The description below is for older libcurl versions.) @@ -81,26 +81,36 @@ backend libcurl uses. Doing TLS based transfers without having the TLS layer initialized may lead to unexpected behaviors. -.IP CURL_GLOBAL_WIN32 + +## CURL_GLOBAL_WIN32 + Initialize the Win32 socket libraries. The implication here is that if this bit is not set, the initialization of winsock has to be done by the application or you risk getting undefined behaviors. This option exists for when the initialization is handled outside of libcurl so there is no need for libcurl to do it again. -.IP CURL_GLOBAL_NOTHING + +## CURL_GLOBAL_NOTHING + Initialize nothing extra. This sets no bit. -.IP CURL_GLOBAL_DEFAULT + +## CURL_GLOBAL_DEFAULT + A sensible default. It initializes both SSL and Win32. Right now, this equals -the functionality of the \fBCURL_GLOBAL_ALL\fP mask. -.IP CURL_GLOBAL_ACK_EINTR +the functionality of the **CURL_GLOBAL_ALL** mask. + +## CURL_GLOBAL_ACK_EINTR + This bit has no point since 7.69.0 but its behavior is instead the default. Before 7.69.0: when this flag is set, curl acknowledges EINTR condition when connecting or when waiting for data. Otherwise, curl waits until full timeout elapses. (Added in 7.30.0) -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { curl_global_init(CURL_GLOBAL_DEFAULT); @@ -109,16 +119,13 @@ int main(void) curl_global_cleanup(); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.8 -.SH RETURN VALUE + +# RETURN VALUE + If this function returns non-zero, something went wrong and you cannot use the other curl functions. -.SH "SEE ALSO" -.BR curl_easy_init (3), -.BR curl_global_cleanup (3), -.BR curl_global_init_mem (3), -.BR curl_global_sslset (3), -.BR curl_global_trace (3), -.BR libcurl (3) diff --git a/docs/libcurl/curl_global_init_mem.3 b/docs/libcurl/curl_global_init_mem.3 deleted file mode 100644 index b41087531ef..00000000000 --- a/docs/libcurl/curl_global_init_mem.3 +++ /dev/null @@ -1,88 +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 -.\" * -.\" ************************************************************************** -.TH curl_global_init_mem 3 "10 May 2004" "libcurl" "libcurl" -.SH NAME -curl_global_init_mem - Global libcurl initialization with memory callbacks -.SH SYNOPSIS -.nf -#include - -CURLcode curl_global_init_mem(long flags, - curl_malloc_callback m, - curl_free_callback f, - curl_realloc_callback r, - curl_strdup_callback s, - curl_calloc_callback c); -.fi -.SH DESCRIPTION -This function works exactly as \fIcurl_global_init(3)\fP with one addition: it -allows the application to set callbacks to replace the otherwise used internal -memory functions. - -If you are using libcurl from multiple threads or libcurl was built with the -threaded resolver option then the callback functions must be thread safe. The -threaded resolver is a common build option to enable (and in some cases the -default) so we strongly urge you to make your callback functions thread safe. - -All callback arguments must be set to valid function pointers. The -prototypes for the given callbacks must match these: -.IP "void *malloc_callback(size_t size);" -To replace malloc() -.IP "void free_callback(void *ptr);" -To replace free() -.IP "void *realloc_callback(void *ptr, size_t size);" -To replace realloc() -.IP "char *strdup_callback(const char *str);" -To replace strdup() -.IP "void *calloc_callback(size_t nmemb, size_t size);" -To replace calloc() - -This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer -to that man page for documentation. -.SH CAUTION -Manipulating these gives considerable powers to the application to severely -screw things up for libcurl. Take care! -.SH EXAMPLE -.nf -extern void *malloc_cb(size_t); -extern void free_cb(void *); -extern void *realloc_cb(void *, size_t); -extern char *strdup_cb(const char *); -extern void *calloc_cb(size_t, size_t); - -int main(void) -{ - curl_global_init_mem(CURL_GLOBAL_DEFAULT, malloc_cb, - free_cb, realloc_cb, - strdup_cb, calloc_cb); -} -.fi -.SH AVAILABILITY -Added in 7.12.0 -.SH RETURN VALUE -CURLE_OK (0) means everything was OK, non-zero means an error occurred as -\fI\fP defines - see \fIlibcurl-errors(3)\fP. -.SH "SEE ALSO" -.BR curl_global_init (3), -.BR curl_global_cleanup (3) diff --git a/docs/libcurl/curl_global_init_mem.md b/docs/libcurl/curl_global_init_mem.md new file mode 100644 index 00000000000..3bf468f18d5 --- /dev/null +++ b/docs/libcurl/curl_global_init_mem.md @@ -0,0 +1,95 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_global_init_mem +Section: 3 +Source: libcurl +See-also: + - curl_global_cleanup (3) + - curl_global_init (3) +--- + +# NAME + +curl_global_init_mem - Global libcurl initialization with memory callbacks + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_global_init_mem(long flags, + curl_malloc_callback m, + curl_free_callback f, + curl_realloc_callback r, + curl_strdup_callback s, + curl_calloc_callback c); +~~~ + +# DESCRIPTION + +This function works exactly as curl_global_init(3) with one addition: it +allows the application to set callbacks to replace the otherwise used internal +memory functions. + +If you are using libcurl from multiple threads or libcurl was built with the +threaded resolver option then the callback functions must be thread safe. The +threaded resolver is a common build option to enable (and in some cases the +default) so we strongly urge you to make your callback functions thread safe. + +All callback arguments must be set to valid function pointers. The +prototypes for the given callbacks must match these: + +## void *malloc_callback(size_t size); + +To replace malloc() + +## void free_callback(void *ptr); + +To replace free() + +## void *realloc_callback(void *ptr, size_t size); + +To replace realloc() + +## char *strdup_callback(const char *str); + +To replace strdup() + +## void *calloc_callback(size_t nmemb, size_t size); + +To replace calloc() + +This function is otherwise the same as curl_global_init(3), please refer +to that man page for documentation. + +# CAUTION + +Manipulating these gives considerable powers to the application to severely +screw things up for libcurl. Take care! + +# EXAMPLE + +~~~c +extern void *malloc_cb(size_t); +extern void free_cb(void *); +extern void *realloc_cb(void *, size_t); +extern char *strdup_cb(const char *); +extern void *calloc_cb(size_t, size_t); + +int main(void) +{ + curl_global_init_mem(CURL_GLOBAL_DEFAULT, malloc_cb, + free_cb, realloc_cb, + strdup_cb, calloc_cb); +} +~~~ + +# AVAILABILITY + +Added in 7.12.0 + +# RETURN VALUE + +CURLE_OK (0) means everything was OK, non-zero means an error occurred as +** defines - see libcurl-errors(3). diff --git a/docs/libcurl/curl_global_sslset.3 b/docs/libcurl/curl_global_sslset.3 deleted file mode 100644 index 3384b551a27..00000000000 --- a/docs/libcurl/curl_global_sslset.3 +++ /dev/null @@ -1,139 +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 -.\" * -.\" ************************************************************************** -.TH curl_global_sslset 3 "15 July 2017" "libcurl" "libcurl" -.SH NAME -curl_global_sslset - Select SSL backend to use with libcurl -.SH SYNOPSIS -.nf -#include - -CURLsslset curl_global_sslset(curl_sslbackend id, - const char *name, - const curl_ssl_backend ***avail); -.fi -.SH DESCRIPTION -This function configures at runtime which SSL backend to use with -libcurl. This function can only be used to select an SSL backend once, and it -must be called \fBbefore\fP \fIcurl_global_init(3)\fP. - -The backend can be identified by the \fIid\fP -(e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the -\fIname\fP parameter for a case insensitive match (passing -\fBCURLSSLBACKEND_NONE\fP as \fIid\fP). If both \fIid\fP and \fIname\fP are -specified, the \fIname\fP is ignored. - -If neither \fIid\fP nor \fPname\fP are specified, the function fails with -\fBCURLSSLSET_UNKNOWN_BACKEND\fP and set the \fIavail\fP pointer to the -NULL-terminated list of available backends. The available backends are those -that this particular build of libcurl supports. - -Since libcurl 7.60.0, the \fIavail\fP pointer is always set to the list of -alternatives if non-NULL. - -Upon success, the function returns \fBCURLSSLSET_OK\fP. - -If the specified SSL backend is not available, the function returns -\fBCURLSSLSET_UNKNOWN_BACKEND\fP and sets the \fIavail\fP pointer to a -NULL-terminated list of available SSL backends. In this case, you may call the -function again to try to select a different backend. - -The SSL backend can be set only once. If it has already been set, a subsequent -attempt to change it results in a \fBCURLSSLSET_TOO_LATE\fP getting returned. - -This function is thread-safe since libcurl 7.84.0 if -\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set -(most platforms). - -If this is not thread-safe, you must not call this function when any other -thread in the program (i.e. a thread sharing the same memory) is running. -This does not just mean no other thread that is using libcurl. -.SH OpenSSL -The name "OpenSSL" is used for all versions of OpenSSL and its associated -forks/flavors in this function. OpenSSL, BoringSSL, libressl, quictls and -AmiSSL are all supported by libcurl, but in the eyes of -\fIcurl_global_sslset(3)\fP they are all just "OpenSSL". They all mostly -provide the same API. - -\fIcurl_version_info(3)\fP can return more specific info about the exact -OpenSSL flavor and version number is use. -.SH struct -.nf -typedef struct { - curl_sslbackend id; - const char *name; -} curl_ssl_backend; - -typedef enum { - CURLSSLBACKEND_NONE = 0, - CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */ - CURLSSLBACKEND_GNUTLS = 2, - CURLSSLBACKEND_NSS = 3, - CURLSSLBACKEND_GSKIT = 5, /* deprecated */ - CURLSSLBACKEND_POLARSSL = 6, /* deprecated */ - CURLSSLBACKEND_WOLFSSL = 7, - CURLSSLBACKEND_SCHANNEL = 8, - CURLSSLBACKEND_SECURETRANSPORT = 9, - CURLSSLBACKEND_AXTLS = 10, /* deprecated */ - CURLSSLBACKEND_MBEDTLS = 11, - CURLSSLBACKEND_MESALINK = 12, /* deprecated */ - CURLSSLBACKEND_BEARSSL = 13, - CURLSSLBACKEND_RUSTLS = 14 -} curl_sslbackend; -.fi -.SH EXAMPLE -.nf -int main(void) -{ - int i; - /* choose a specific backend */ - curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL); - - /* list the available ones */ - const curl_ssl_backend **list; - curl_global_sslset(CURLSSLBACKEND_NONE, NULL, &list); - - for(i = 0; list[i]; i++) - printf("SSL backend #%d: '%s' (ID: %d)\\n", - i, list[i]->name, list[i]->id); -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.56.0. Before this version, there was no -support for choosing SSL backends at runtime. -.SH RETURN VALUE -If this function returns \fICURLSSLSET_OK\fP, the backend was successfully -selected. - -If the chosen backend is unknown (or support for the chosen backend has not -been compiled into libcurl), the function returns -\fICURLSSLSET_UNKNOWN_BACKEND\fP. - -If the backend had been configured previously, or if \fIcurl_global_init(3)\fP -has already been called, the function returns \fICURLSSLSET_TOO_LATE\fP. - -If this libcurl was built completely without SSL support, with no backends at -all, this function returns \fICURLSSLSET_NO_BACKENDS\fP. -.SH "SEE ALSO" -.BR curl_global_init (3), -.BR libcurl (3) diff --git a/docs/libcurl/curl_global_sslset.md b/docs/libcurl/curl_global_sslset.md new file mode 100644 index 00000000000..6f50867a1a0 --- /dev/null +++ b/docs/libcurl/curl_global_sslset.md @@ -0,0 +1,138 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_global_sslset +Section: 3 +Source: libcurl +See-also: + - curl_global_init (3) + - libcurl (3) +--- + +# NAME + +curl_global_sslset - Select SSL backend to use with libcurl + +# SYNOPSIS + +~~~c +#include + +CURLsslset curl_global_sslset(curl_sslbackend id, + const char *name, + const curl_ssl_backend ***avail); +~~~ + +# DESCRIPTION + +This function configures at runtime which SSL backend to use with +libcurl. This function can only be used to select an SSL backend once, and it +must be called **before** curl_global_init(3). + +The backend can be identified by the *id* +(e.g. **CURLSSLBACKEND_OPENSSL**). The backend can also be specified via the +*name* parameter for a case insensitive match (passing +**CURLSSLBACKEND_NONE** as *id*). If both *id* and *name* are +specified, the *name* is ignored. + +If neither *id* nor *name* are specified, the function fails with +**CURLSSLSET_UNKNOWN_BACKEND** and set the *avail* pointer to the +NULL-terminated list of available backends. The available backends are those +that this particular build of libcurl supports. + +Since libcurl 7.60.0, the *avail* pointer is always set to the list of +alternatives if non-NULL. + +Upon success, the function returns **CURLSSLSET_OK**. + +If the specified SSL backend is not available, the function returns +**CURLSSLSET_UNKNOWN_BACKEND** and sets the *avail* pointer to a +NULL-terminated list of available SSL backends. In this case, you may call the +function again to try to select a different backend. + +The SSL backend can be set only once. If it has already been set, a subsequent +attempt to change it results in a **CURLSSLSET_TOO_LATE** getting returned. + +This function is thread-safe since libcurl 7.84.0 if +curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set +(most platforms). + +If this is not thread-safe, you must not call this function when any other +thread in the program (i.e. a thread sharing the same memory) is running. +This does not just mean no other thread that is using libcurl. + +# OpenSSL + +The name "OpenSSL" is used for all versions of OpenSSL and its associated +forks/flavors in this function. OpenSSL, BoringSSL, libressl, quictls and +AmiSSL are all supported by libcurl, but in the eyes of +curl_global_sslset(3) they are all just "OpenSSL". They all mostly +provide the same API. + +curl_version_info(3) can return more specific info about the exact +OpenSSL flavor and version number is use. + +# struct + +~~~c +typedef struct { + curl_sslbackend id; + const char *name; +} curl_ssl_backend; + +typedef enum { + CURLSSLBACKEND_NONE = 0, + CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */ + CURLSSLBACKEND_GNUTLS = 2, + CURLSSLBACKEND_NSS = 3, + CURLSSLBACKEND_GSKIT = 5, /* deprecated */ + CURLSSLBACKEND_POLARSSL = 6, /* deprecated */ + CURLSSLBACKEND_WOLFSSL = 7, + CURLSSLBACKEND_SCHANNEL = 8, + CURLSSLBACKEND_SECURETRANSPORT = 9, + CURLSSLBACKEND_AXTLS = 10, /* deprecated */ + CURLSSLBACKEND_MBEDTLS = 11, + CURLSSLBACKEND_MESALINK = 12, /* deprecated */ + CURLSSLBACKEND_BEARSSL = 13, + CURLSSLBACKEND_RUSTLS = 14 +} curl_sslbackend; +~~~ + +# EXAMPLE + +~~~c +int main(void) +{ + int i; + /* choose a specific backend */ + curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL); + + /* list the available ones */ + const curl_ssl_backend **list; + curl_global_sslset(CURLSSLBACKEND_NONE, NULL, &list); + + for(i = 0; list[i]; i++) + printf("SSL backend #%d: '%s' (ID: %d)\n", + i, list[i]->name, list[i]->id); +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.56.0. Before this version, there was no +support for choosing SSL backends at runtime. + +# RETURN VALUE + +If this function returns *CURLSSLSET_OK*, the backend was successfully +selected. + +If the chosen backend is unknown (or support for the chosen backend has not +been compiled into libcurl), the function returns +*CURLSSLSET_UNKNOWN_BACKEND*. + +If the backend had been configured previously, or if curl_global_init(3) +has already been called, the function returns *CURLSSLSET_TOO_LATE*. + +If this libcurl was built completely without SSL support, with no backends at +all, this function returns *CURLSSLSET_NO_BACKENDS*. diff --git a/docs/libcurl/curl_global_trace.3 b/docs/libcurl/curl_global_trace.md similarity index 61% rename from docs/libcurl/curl_global_trace.3 rename to docs/libcurl/curl_global_trace.md index 926a86b1dc0..fe9c12c1ba5 100644 --- a/docs/libcurl/curl_global_trace.3 +++ b/docs/libcurl/curl_global_trace.md @@ -1,36 +1,28 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_global_trace 3 "01 August 2023" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_global_trace +Section: 3 +Source: libcurl +See-also: + - curl_global_init (3) + - libcurl (3) +--- + +# NAME + curl_global_trace - Global libcurl logging configuration -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLcode curl_global_trace(const char *config); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This function configures the logging behavior, allowing to make some parts of curl more verbose or silent than others. @@ -42,21 +34,21 @@ Calling this function after transfers have been started is undefined. On some platforms/architectures it might take effect, on others not. This function is thread-safe since libcurl 8.3.0 if -\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set +curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set (most platforms). If this is not thread-safe, you must not call this function when any other thread in the program (i.e. a thread sharing the same memory) is running. This does not just mean no other thread that is using libcurl. Because -\fIcurl_global_init(3)\fP may call functions of other libraries that are +curl_global_init(3) may call functions of other libraries that are similarly thread unsafe, it could conflict with any other thread that uses these other libraries. If you are initializing libcurl from a Windows DLL you should not initialize -it from \fIDllMain\fP or a static initializer because Windows holds the loader +it from *DllMain* or a static initializer because Windows holds the loader lock during that time and it could cause a deadlock. -The \fIconfig\fP string is a list of comma-separated component names. Names +The *config* string is a list of comma-separated component names. Names are case-insensitive and unknown names are ignored. The special name "all" applies to all components. Names may be prefixed with '+' or '-' to enable or disable detailed logging for a component. @@ -68,19 +60,29 @@ upgrading libcurl. Given that, some names can be expected to be fairly stable and are listed below for easy reference. Note that log configuration applies only to transfers where debug logging -is enabled. See \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP +is enabled. See CURLOPT_VERBOSE(3) or CURLOPT_DEBUGFUNCTION(3) on how to control that. -.SH TRACE COMPONENTS -.IP tcp +# TRACE COMPONENTS + +## tcp + Tracing of TCP socket handling: connect, reads, writes. -.IP ssl + +## ssl + Tracing of SSL/TLS operations, whichever SSL backend is used in your build. -.IP http/2 + +## http/2 + Details about HTTP/2 handling: frames, events, I/O, etc. -.IP http/3 + +## http/3 + Details about HTTP/3 handling: connect, frames, events, I/O etc. -.IP http-proxy + +## http-proxy + Involved when transfers are tunneled through a HTTP proxy. "h1-proxy" or "h2-proxy" are also involved, depending on the HTTP version negotiated with the proxy. @@ -89,8 +91,9 @@ In order to find out all components involved in a transfer, run it with "all" configured. You can then see all names involved in your libcurl version in the trace. -.SH EXAMPLE -.nf +# EXAMPLE + +~~~c int main(void) { /* log details of HTTP/2 and SSL handling */ @@ -99,23 +102,23 @@ int main(void) /* log all details, except SSL handling */ curl_global_trace("all,-ssl"); } -.fi +~~~ Below is a trace sample where "http/2" was configured. The trace output of an enabled component appears at the beginning in brackets. -.nf +~~~ * [HTTP/2] [h2sid=1] cf_send(len=96) submit https://example.com/ -\&... +... * [HTTP/2] [h2sid=1] FRAME[HEADERS] * [HTTP/2] [h2sid=1] 249 header bytes -\&... -.fi +... +~~~ + +# AVAILABILITY -.SH AVAILABILITY Added in 8.3 -.SH RETURN VALUE + +# RETURN VALUE + If this function returns non-zero, something went wrong and the configuration may not have any effects or may only been applied partially. -.SH "SEE ALSO" -.BR curl_global_init (3), -.BR libcurl (3) diff --git a/docs/libcurl/curl_mime_addpart.3 b/docs/libcurl/curl_mime_addpart.3 deleted file mode 100644 index c9eccf55bf9..00000000000 --- a/docs/libcurl/curl_mime_addpart.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_addpart 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_addpart - append a new empty part to a mime structure -.SH SYNOPSIS -.nf -#include - -curl_mimepart *curl_mime_addpart(curl_mime *mime); -.fi -.SH DESCRIPTION -\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given -mime structure and returns a handle to it. The returned part handle can -subsequently be populated using functions from the mime API. - -\fImime\fP is the handle of the mime structure in which the new part must be -appended. -.SH EXAMPLE -.nf -int main(void) -{ - curl_mime *mime; - curl_mimepart *part; - - CURL *curl = curl_easy_init(); - if(curl) { - /* create a mime handle */ - mime = curl_mime_init(curl); - - /* add a part */ - part = curl_mime_addpart(mime); - - /* continue and set name + data to the part */ - curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED); - curl_mime_name(part, "data"); - } -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -A mime part structure handle, or NULL upon failure. -.SH "SEE ALSO" -.BR curl_mime_data (3), -.BR curl_mime_data_cb (3), -.BR curl_mime_encoder (3), -.BR curl_mime_filedata (3), -.BR curl_mime_filename (3), -.BR curl_mime_headers (3), -.BR curl_mime_init (3), -.BR curl_mime_name (3), -.BR curl_mime_subparts (3), -.BR curl_mime_type (3) diff --git a/docs/libcurl/curl_mime_addpart.md b/docs/libcurl/curl_mime_addpart.md new file mode 100644 index 00000000000..f641abbcfde --- /dev/null +++ b/docs/libcurl/curl_mime_addpart.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_addpart +Section: 3 +Source: libcurl +See-also: + - curl_mime_data (3) + - curl_mime_data_cb (3) + - curl_mime_encoder (3) + - curl_mime_filedata (3) + - curl_mime_filename (3) + - curl_mime_headers (3) + - curl_mime_init (3) + - curl_mime_name (3) + - curl_mime_subparts (3) + - curl_mime_type (3) +--- + +# NAME + +curl_mime_addpart - append a new empty part to a mime structure + +# SYNOPSIS + +~~~c +#include + +curl_mimepart *curl_mime_addpart(curl_mime *mime); +~~~ + +# DESCRIPTION + +curl_mime_addpart(3) creates and appends a new empty part to the given +mime structure and returns a handle to it. The returned part handle can +subsequently be populated using functions from the mime API. + +*mime* is the handle of the mime structure in which the new part must be +appended. + +# EXAMPLE + +~~~c +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* continue and set name + data to the part */ + curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED); + curl_mime_name(part, "data"); + } +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +A mime part structure handle, or NULL upon failure. diff --git a/docs/libcurl/curl_mime_data.3 b/docs/libcurl/curl_mime_data.3 deleted file mode 100644 index 71042daa1a3..00000000000 --- a/docs/libcurl/curl_mime_data.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_data 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_data - set a mime part's body data from memory -.SH SYNOPSIS -.nf -#include - -CURLcode curl_mime_data(curl_mimepart *part, const char *data, - size_t datasize); -.fi -.SH DESCRIPTION -\fIcurl_mime_data(3)\fP sets a mime part's body content from memory data. - -\fIpart\fP is the mime part to assign contents to, created with -\fIcurl_mime_addpart(3)\fP. - -\fIdata\fP points to the data that gets copied by this function. The storage -may safely be reused after the call. - -\fIdatasize\fP is the number of bytes \fIdata\fP points to. It can be set to -\fICURL_ZERO_TERMINATED\fP to indicate \fIdata\fP is a null-terminated -character string. - -Setting a part's contents multiple times is valid: only the value set by the -last call is retained. It is possible to unassign part's contents by setting -\fIdata\fP to NULL. - -Setting large data is memory consuming: one might consider using -\fIcurl_mime_data_cb(3)\fP in such a case. -.SH EXAMPLE -.nf -int main(void) -{ - curl_mime *mime; - curl_mimepart *part; - - CURL *curl = curl_easy_init(); - if(curl) { - /* create a mime handle */ - mime = curl_mime_init(curl); - - /* add a part */ - part = curl_mime_addpart(mime); - - /* add data to the part */ - curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED); - } -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -CURLE_OK or a CURL error code upon failure. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_data_cb (3), -.BR curl_mime_name (3), -.BR curl_mime_type (3) diff --git a/docs/libcurl/curl_mime_data.md b/docs/libcurl/curl_mime_data.md new file mode 100644 index 00000000000..15a1d2707cb --- /dev/null +++ b/docs/libcurl/curl_mime_data.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_data +Section: 3 +Source: libcurl +See-also: + - curl_mime_addpart (3) + - curl_mime_data_cb (3) + - curl_mime_name (3) + - curl_mime_type (3) +--- + +# NAME + +curl_mime_data - set a mime part's body data from memory + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_mime_data(curl_mimepart *part, const char *data, + size_t datasize); +~~~ + +# DESCRIPTION + +curl_mime_data(3) sets a mime part's body content from memory data. + +*part* is the mime part to assign contents to, created with +curl_mime_addpart(3). + +*data* points to the data that gets copied by this function. The storage +may safely be reused after the call. + +*datasize* is the number of bytes *data* points to. It can be set to +*CURL_ZERO_TERMINATED* to indicate *data* is a null-terminated +character string. + +Setting a part's contents multiple times is valid: only the value set by the +last call is retained. It is possible to unassign part's contents by setting +*data* to NULL. + +Setting large data is memory consuming: one might consider using +curl_mime_data_cb(3) in such a case. + +# EXAMPLE + +~~~c +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* add data to the part */ + curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED); + } +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +CURLE_OK or a CURL error code upon failure. diff --git a/docs/libcurl/curl_mime_data_cb.3 b/docs/libcurl/curl_mime_data_cb.md similarity index 58% rename from docs/libcurl/curl_mime_data_cb.3 rename to docs/libcurl/curl_mime_data_cb.md index 8ca3df3e3be..bd3c77ac504 100644 --- a/docs/libcurl/curl_mime_data_cb.3 +++ b/docs/libcurl/curl_mime_data_cb.md @@ -1,31 +1,23 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_mime_data_cb 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_data_cb +Section: 3 +Source: libcurl +See-also: + - curl_easy_duphandle (3) + - curl_mime_addpart (3) + - curl_mime_data (3) + - curl_mime_name (3) +--- + +# NAME + curl_mime_data_cb - set a callback-based data source for a mime part's body -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg); @@ -38,32 +30,34 @@ CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize, curl_read_callback readfunc, curl_seek_callback seekfunc, curl_free_callback freefunc, void *arg); -.fi -.SH DESCRIPTION -\fIcurl_mime_data_cb(3)\fP sets the data source of a mime part's body content +~~~ + +# DESCRIPTION + +curl_mime_data_cb(3) sets the data source of a mime part's body content from a data read callback function. -\fIpart\fP is the part's to assign contents to. +*part* is the part's to assign contents to. -\fIreadfunc\fP is a pointer to a data read callback function, with a signature +*readfunc* is a pointer to a data read callback function, with a signature as shown by the above prototype. It may not be set to NULL. -\fIseekfunc\fP is a pointer to a seek callback function, with a signature as +*seekfunc* is a pointer to a seek callback function, with a signature as shown by the above prototype. This function is used when resending data (i.e.: after a redirect); this pointer may be set to NULL, in which case a resend might not be not possible. -\fIfreefunc\fP is a pointer to a user resource freeing callback function, with +*freefunc* is a pointer to a user resource freeing callback function, with a signature as shown by the above prototype. If no resource is to be freed, it may safely be set to NULL. This function is called upon mime structure freeing. -\fIarg\fP is a user defined argument to callback functions. +*arg* is a user defined argument to callback functions. The read callback function gets called by libcurl as soon as it needs to read data in order to send it to the peer - like if you ask it to upload or -post data to the server. The data area pointed at by the pointer \fIbuffer\fP -should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number +post data to the server. The data area pointed at by the pointer *buffer* +should be filled up with at most *size* multiplied with *nitems* number of bytes by your function. Your read function must then return the actual number of bytes that it stored @@ -75,35 +69,37 @@ the server expected it, like when you have said you intend to upload N bytes and yet you upload less than N bytes), you may experience that the server "hangs" waiting for the rest of the data that does not come. -The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current -operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error +The read callback may return *CURL_READFUNC_ABORT* to stop the current +operation immediately, resulting in a *CURLE_ABORTED_BY_CALLBACK* error code from the transfer. -The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this -connection to pause. See \fIcurl_easy_pause(3)\fP for further details. +The callback can return *CURL_READFUNC_PAUSE* to cause reading from this +connection to pause. See curl_easy_pause(3) for further details. The seek function gets called by libcurl to rewind input stream data or to seek to a certain position. The function shall work like fseek(3) or lseek(3) -and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, +and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for *origin*, although libcurl currently only passes SEEK_SET. -The callback function must return \fICURL_SEEKFUNC_OK\fP on success, -\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or -\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl +The callback function must return *CURL_SEEKFUNC_OK* on success, +*CURL_SEEKFUNC_FAIL* to cause the upload operation to fail or +*CURL_SEEKFUNC_CANTSEEK* to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar. Care must be taken if the part is bound to a curl easy handle that is later -duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in +duplicated: the *arg* pointer argument is also duplicated, resulting in the pointed item to be shared between the original and the copied handle. In -particular, special attention should be given to the \fIfreefunc\fP procedure +particular, special attention should be given to the *freefunc* procedure code since it then gets called twice with the same argument. -.SH EXAMPLE + +# EXAMPLE + Sending a huge data string causes the same amount of memory to be allocated: to avoid overhead resources consumption, one might want to use a callback source to avoid data duplication. In this case, original data must be retained until after the transfer terminates. -.nf +~~~c #include /* for memcpy */ char hugedata[512000]; @@ -161,13 +157,12 @@ int main(void) &hugectl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE + +# RETURN VALUE + CURLE_OK or a CURL error code upon failure. -.SH "SEE ALSO" -.BR curl_easy_duphandle (3), -.BR curl_mime_addpart (3), -.BR curl_mime_data (3), -.BR curl_mime_name (3) diff --git a/docs/libcurl/curl_mime_encoder.3 b/docs/libcurl/curl_mime_encoder.3 deleted file mode 100644 index f6eaa2ec6ee..00000000000 --- a/docs/libcurl/curl_mime_encoder.3 +++ /dev/null @@ -1,105 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_encoder 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_encoder - set a mime part's encoder and content transfer encoding -.SH SYNOPSIS -.nf -#include - -CURLcode curl_mime_encoder(curl_mimepart *part, const char *encoding); -.fi -.SH DESCRIPTION -curl_mime_encoder() requests a mime part's content to be encoded before being -transmitted. - -\fIpart\fP is the part's handle to assign an encoder. -\fIencoding\fP is a pointer to a null-terminated encoding scheme. It may be -set to NULL to disable an encoder previously attached to the part. The encoding -scheme storage may safely be reused after this function returns. - -Setting a part's encoder multiple times is valid: only the value set by the -last call is retained. - -Upon multipart rendering, the part's content is encoded according to the -pertaining scheme and a corresponding \fI"Content-Transfer-Encoding"\fP header -is added to the part. - -Supported encoding schemes are: - -"\fIbinary\fP": the data is left unchanged, the header is added. - -"\fI8bit\fP": header added, no data change. - -"\fI7bit\fP": the data is unchanged, but is each byte is checked -to be a 7-bit value; if not, a read error occurs. - -"\fIbase64\fP": Data is converted to base64 encoding, then split in -CRLF-terminated lines of at most 76 characters. - -"\fIquoted-printable\fP": data is encoded in quoted printable lines of -at most 76 characters. Since the resulting size of the final data cannot be -determined prior to reading the original data, it is left as unknown, causing -chunked transfer in HTTP. For the same reason, this encoder may not be used -with IMAP. This encoder targets text data that is mostly ASCII and should -not be used with other types of data. - -If the original data is already encoded in such a scheme, a custom -\fIContent-Transfer-Encoding\fP header should be added with -\fIcurl_mime_headers(3)\fP instead of setting a part encoder. - -Encoding should not be applied to multiparts, thus the use of this function on -a part with content set with \fIcurl_mime_subparts(3)\fP is strongly -discouraged. -.SH EXAMPLE -.nf -int main(void) -{ - curl_mime *mime; - curl_mimepart *part; - - CURL *curl = curl_easy_init(); - if(curl) { - /* create a mime handle */ - mime = curl_mime_init(curl); - - /* add a part */ - part = curl_mime_addpart(mime); - - /* send a file */ - curl_mime_filedata(part, "image.png"); - - /* encode file data in base64 for transfer */ - curl_mime_encoder(part, "base64"); - } -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -CURLE_OK or a CURL error code upon failure. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_headers (3), -.BR curl_mime_subparts (3) diff --git a/docs/libcurl/curl_mime_encoder.md b/docs/libcurl/curl_mime_encoder.md new file mode 100644 index 00000000000..85dc3ac11e2 --- /dev/null +++ b/docs/libcurl/curl_mime_encoder.md @@ -0,0 +1,100 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_encoder +Section: 3 +Source: libcurl +See-also: + - curl_mime_addpart (3) + - curl_mime_headers (3) + - curl_mime_subparts (3) +--- + +# NAME + +curl_mime_encoder - set a mime part's encoder and content transfer encoding + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_mime_encoder(curl_mimepart *part, const char *encoding); +~~~ + +# DESCRIPTION + +curl_mime_encoder() requests a mime part's content to be encoded before being +transmitted. + +*part* is the part's handle to assign an encoder. +*encoding* is a pointer to a null-terminated encoding scheme. It may be +set to NULL to disable an encoder previously attached to the part. The encoding +scheme storage may safely be reused after this function returns. + +Setting a part's encoder multiple times is valid: only the value set by the +last call is retained. + +Upon multipart rendering, the part's content is encoded according to the +pertaining scheme and a corresponding *"Content-Transfer-Encoding"* header +is added to the part. + +Supported encoding schemes are: + +"*binary*": the data is left unchanged, the header is added. + +"*8bit*": header added, no data change. + +"*7bit*": the data is unchanged, but is each byte is checked +to be a 7-bit value; if not, a read error occurs. + +"*base64*": Data is converted to base64 encoding, then split in +CRLF-terminated lines of at most 76 characters. + +"*quoted-printable*": data is encoded in quoted printable lines of +at most 76 characters. Since the resulting size of the final data cannot be +determined prior to reading the original data, it is left as unknown, causing +chunked transfer in HTTP. For the same reason, this encoder may not be used +with IMAP. This encoder targets text data that is mostly ASCII and should +not be used with other types of data. + +If the original data is already encoded in such a scheme, a custom +*Content-Transfer-Encoding* header should be added with +curl_mime_headers(3) instead of setting a part encoder. + +Encoding should not be applied to multiparts, thus the use of this function on +a part with content set with curl_mime_subparts(3) is strongly +discouraged. + +# EXAMPLE + +~~~c +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* send a file */ + curl_mime_filedata(part, "image.png"); + + /* encode file data in base64 for transfer */ + curl_mime_encoder(part, "base64"); + } +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +CURLE_OK or a CURL error code upon failure. diff --git a/docs/libcurl/curl_mime_filedata.3 b/docs/libcurl/curl_mime_filedata.3 deleted file mode 100644 index cb20fea42a6..00000000000 --- a/docs/libcurl/curl_mime_filedata.3 +++ /dev/null @@ -1,93 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_filedata 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_filedata - set a mime part's body data from a file contents -.SH SYNOPSIS -.nf -#include - -CURLcode curl_mime_filedata(curl_mimepart *part, - const char *filename); -.fi -.SH DESCRIPTION -\fIcurl_mime_filedata(3)\fP sets a mime part's body content from the named -file's contents. This is an alternative to \fIcurl_mime_data(3)\fP for setting -data to a mime part. - -\fIpart\fP is the part's to assign contents to. - -\fIfilename\fP points to the null-terminated file's path name. The pointer can -be NULL to detach the previous part contents settings. Filename storage can -be safely be reused after this call. - -As a side effect, the part's remote file name is set to the base name of the -given \fIfilename\fP if it is a valid named file. This can be undone or -overridden by a subsequent call to \fIcurl_mime_filename(3)\fP. - -The contents of the file is read during the file transfer in a streaming -manner to allow huge files to get transferred without using much memory. It -therefore requires that the file is kept intact during the entire request. - -If the file size cannot be determined before actually reading it (such as for -a character device or named pipe), the whole mime structure containing the -part is transferred using chunks by HTTP but is rejected by IMAP. - -Setting a part's contents multiple times is valid: only the value set by the -last call is retained. -.SH EXAMPLE -.nf -int main(void) -{ - curl_mime *mime; - curl_mimepart *part; - - CURL *curl = curl_easy_init(); - if(curl) { - /* create a mime handle */ - mime = curl_mime_init(curl); - - /* add a part */ - part = curl_mime_addpart(mime); - - /* send data from this file */ - curl_mime_filedata(part, "image.png"); - - /* set name */ - curl_mime_name(part, "data"); - } -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an -indication that the file is not yet readable: it can be safely ignored at -this time, but the file must be made readable before the pertaining -easy handle is performed. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_data (3), -.BR curl_mime_filename (3), -.BR curl_mime_name (3) diff --git a/docs/libcurl/curl_mime_filedata.md b/docs/libcurl/curl_mime_filedata.md new file mode 100644 index 00000000000..2440e56b367 --- /dev/null +++ b/docs/libcurl/curl_mime_filedata.md @@ -0,0 +1,88 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_filedata +Section: 3 +Source: libcurl +See-also: + - curl_mime_addpart (3) + - curl_mime_data (3) + - curl_mime_filename (3) + - curl_mime_name (3) +--- + +# NAME + +curl_mime_filedata - set a mime part's body data from a file contents + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_mime_filedata(curl_mimepart *part, + const char *filename); +~~~ + +# DESCRIPTION + +curl_mime_filedata(3) sets a mime part's body content from the named +file's contents. This is an alternative to curl_mime_data(3) for setting +data to a mime part. + +*part* is the part's to assign contents to. + +*filename* points to the null-terminated file's path name. The pointer can +be NULL to detach the previous part contents settings. Filename storage can +be safely be reused after this call. + +As a side effect, the part's remote file name is set to the base name of the +given *filename* if it is a valid named file. This can be undone or +overridden by a subsequent call to curl_mime_filename(3). + +The contents of the file is read during the file transfer in a streaming +manner to allow huge files to get transferred without using much memory. It +therefore requires that the file is kept intact during the entire request. + +If the file size cannot be determined before actually reading it (such as for +a character device or named pipe), the whole mime structure containing the +part is transferred using chunks by HTTP but is rejected by IMAP. + +Setting a part's contents multiple times is valid: only the value set by the +last call is retained. + +# EXAMPLE + +~~~c +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* send data from this file */ + curl_mime_filedata(part, "image.png"); + + /* set name */ + curl_mime_name(part, "data"); + } +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an +indication that the file is not yet readable: it can be safely ignored at +this time, but the file must be made readable before the pertaining +easy handle is performed. diff --git a/docs/libcurl/curl_mime_filename.3 b/docs/libcurl/curl_mime_filename.3 deleted file mode 100644 index a10bf803ec0..00000000000 --- a/docs/libcurl/curl_mime_filename.3 +++ /dev/null @@ -1,84 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_filename 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_filename - set a mime part's remote file name -.SH SYNOPSIS -.nf -#include - -CURLcode curl_mime_filename(curl_mimepart *part, - const char *filename); -.fi -.SH DESCRIPTION -\fIcurl_mime_filename(3)\fP sets a mime part's remote file name. When remote -file name is set, content data is processed as a file, whatever is the part's -content source. A part's remote file name is transmitted to the server in the -associated Content-Disposition generated header. - -\fIpart\fP is the part's handle to assign the remote file name to. - -\fIfilename\fP points to the null-terminated file name string; it may be set -to NULL to remove a previously attached remote file name. - -The remote file name string is copied into the part, thus the associated -storage may safely be released or reused after call. Setting a part's file -name multiple times is valid: only the value set by the last call is retained. -.SH EXAMPLE -.nf - -static char imagebuf[]="imagedata"; - -int main(void) -{ - curl_mime *mime; - curl_mimepart *part; - - CURL *curl = curl_easy_init(); - if(curl) { - /* create a mime handle */ - mime = curl_mime_init(curl); - - /* add a part */ - part = curl_mime_addpart(mime); - - /* send image data from memory */ - curl_mime_data(part, imagebuf, sizeof(imagebuf)); - - /* set a file name to make it look like a file upload */ - curl_mime_filename(part, "image.png"); - - /* set name */ - curl_mime_name(part, "data"); - } -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -CURLE_OK or a CURL error code upon failure. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_data (3), -.BR curl_mime_filedata (3) diff --git a/docs/libcurl/curl_mime_filename.md b/docs/libcurl/curl_mime_filename.md new file mode 100644 index 00000000000..5f07114911f --- /dev/null +++ b/docs/libcurl/curl_mime_filename.md @@ -0,0 +1,79 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_filename +Section: 3 +Source: libcurl +See-also: + - curl_mime_addpart (3) + - curl_mime_data (3) + - curl_mime_filedata (3) +--- + +# NAME + +curl_mime_filename - set a mime part's remote file name + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_mime_filename(curl_mimepart *part, + const char *filename); +~~~ + +# DESCRIPTION + +curl_mime_filename(3) sets a mime part's remote file name. When remote +file name is set, content data is processed as a file, whatever is the part's +content source. A part's remote file name is transmitted to the server in the +associated Content-Disposition generated header. + +*part* is the part's handle to assign the remote file name to. + +*filename* points to the null-terminated file name string; it may be set +to NULL to remove a previously attached remote file name. + +The remote file name string is copied into the part, thus the associated +storage may safely be released or reused after call. Setting a part's file +name multiple times is valid: only the value set by the last call is retained. + +# EXAMPLE + +~~~c + +static char imagebuf[]="imagedata"; + +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* send image data from memory */ + curl_mime_data(part, imagebuf, sizeof(imagebuf)); + + /* set a file name to make it look like a file upload */ + curl_mime_filename(part, "image.png"); + + /* set name */ + curl_mime_name(part, "data"); + } +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +CURLE_OK or a CURL error code upon failure. diff --git a/docs/libcurl/curl_mime_free.3 b/docs/libcurl/curl_mime_free.3 deleted file mode 100644 index b37b1580307..00000000000 --- a/docs/libcurl/curl_mime_free.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_free 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_free - free a previously built mime structure -.SH SYNOPSIS -.nf -#include - -void curl_mime_free(curl_mime *mime); -.fi -.SH DESCRIPTION -\fIcurl_mime_free(3)\fP is used to clean up data previously built/appended -with \fIcurl_mime_addpart(3)\fP and other mime-handling functions. This must -be called when the data has been used, which typically means after -\fIcurl_easy_perform(3)\fP has been called. - -The handle to free is the one you passed to the \fICURLOPT_MIMEPOST(3)\fP -option: attached sub part mime structures must not be explicitly freed as they -are by the top structure freeing. - -\fBmime\fP is the handle as returned from a previous call to -\fIcurl_mime_init(3)\fP and may be NULL. - -Passing in a NULL pointer in \fImime\fP makes this function return immediately -with no action. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* Build the mime message. */ - curl_mime *mime = curl_mime_init(curl); - - /* send off the transfer */ - - /* Free multipart message. */ - curl_mime_free(mime); - } -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -None -.SH "SEE ALSO" -.BR curl_free (3), -.BR curl_mime_init (3) diff --git a/docs/libcurl/curl_mime_free.md b/docs/libcurl/curl_mime_free.md new file mode 100644 index 00000000000..5aa5b6aa15f --- /dev/null +++ b/docs/libcurl/curl_mime_free.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_free +Section: 3 +Source: libcurl +See-also: + - curl_free (3) + - curl_mime_init (3) +--- + +# NAME + +curl_mime_free - free a previously built mime structure + +# SYNOPSIS + +~~~c +#include + +void curl_mime_free(curl_mime *mime); +~~~ + +# DESCRIPTION + +curl_mime_free(3) is used to clean up data previously built/appended +with curl_mime_addpart(3) and other mime-handling functions. This must +be called when the data has been used, which typically means after +curl_easy_perform(3) has been called. + +The handle to free is the one you passed to the CURLOPT_MIMEPOST(3) +option: attached sub part mime structures must not be explicitly freed as they +are by the top structure freeing. + +**mime** is the handle as returned from a previous call to +curl_mime_init(3) and may be NULL. + +Passing in a NULL pointer in *mime* makes this function return immediately +with no action. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* Build the mime message. */ + curl_mime *mime = curl_mime_init(curl); + + /* send off the transfer */ + + /* Free multipart message. */ + curl_mime_free(mime); + } +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +None diff --git a/docs/libcurl/curl_mime_headers.3 b/docs/libcurl/curl_mime_headers.3 deleted file mode 100644 index 109663c386a..00000000000 --- a/docs/libcurl/curl_mime_headers.3 +++ /dev/null @@ -1,83 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_headers 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_headers - set a mime part's custom headers -.SH SYNOPSIS -.nf -#include - -CURLcode curl_mime_headers(curl_mimepart *part, - struct curl_slist *headers, int take_ownership); -.fi -.SH DESCRIPTION -\fIcurl_mime_headers(3)\fP sets a mime part's custom headers. - -\fIpart\fP is the part's handle to assign the custom headers list to. - -\fIheaders\fP is the head of a list of custom headers; it may be set to NULL -to remove a previously attached custom header list. - -\fItake_ownership\fP: when non-zero, causes the list to be freed upon -replacement or mime structure deletion; in this case the list must not be -freed explicitly. - -Setting a part's custom headers list multiple times is valid: only the value -set by the last call is retained. -.SH EXAMPLE -.nf -int main(void) -{ - struct curl_slist *headers = NULL; - CURL *easy = curl_easy_init(); - curl_mime *mime; - curl_mimepart *part; - - headers = curl_slist_append(headers, "Custom-Header: mooo"); - - mime = curl_mime_init(easy); - part = curl_mime_addpart(mime); - - /* use these headers in the part, takes ownership */ - curl_mime_headers(part, headers, 1); - - /* pass on this data */ - curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED); - - /* set name */ - curl_mime_name(part, "numbers"); - - /* Post and send it. */ - curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); - curl_easy_setopt(easy, CURLOPT_URL, "https://example.com"); - curl_easy_perform(easy); -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -CURLE_OK or a CURL error code upon failure. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_name (3) diff --git a/docs/libcurl/curl_mime_headers.md b/docs/libcurl/curl_mime_headers.md new file mode 100644 index 00000000000..4f6421abdd2 --- /dev/null +++ b/docs/libcurl/curl_mime_headers.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_headers +Section: 3 +Source: libcurl +See-also: + - curl_mime_addpart (3) + - curl_mime_name (3) +--- + +# NAME + +curl_mime_headers - set a mime part's custom headers + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_mime_headers(curl_mimepart *part, + struct curl_slist *headers, int take_ownership); +~~~ + +# DESCRIPTION + +curl_mime_headers(3) sets a mime part's custom headers. + +*part* is the part's handle to assign the custom headers list to. + +*headers* is the head of a list of custom headers; it may be set to NULL +to remove a previously attached custom header list. + +*take_ownership*: when non-zero, causes the list to be freed upon +replacement or mime structure deletion; in this case the list must not be +freed explicitly. + +Setting a part's custom headers list multiple times is valid: only the value +set by the last call is retained. + +# EXAMPLE + +~~~c +int main(void) +{ + struct curl_slist *headers = NULL; + CURL *easy = curl_easy_init(); + curl_mime *mime; + curl_mimepart *part; + + headers = curl_slist_append(headers, "Custom-Header: mooo"); + + mime = curl_mime_init(easy); + part = curl_mime_addpart(mime); + + /* use these headers in the part, takes ownership */ + curl_mime_headers(part, headers, 1); + + /* pass on this data */ + curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED); + + /* set name */ + curl_mime_name(part, "numbers"); + + /* Post and send it. */ + curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); + curl_easy_setopt(easy, CURLOPT_URL, "https://example.com"); + curl_easy_perform(easy); +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +CURLE_OK or a CURL error code upon failure. diff --git a/docs/libcurl/curl_mime_init.3 b/docs/libcurl/curl_mime_init.3 deleted file mode 100644 index dc93fd15fd6..00000000000 --- a/docs/libcurl/curl_mime_init.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_init 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_init - create a mime handle -.SH SYNOPSIS -.nf -#include - -curl_mime *curl_mime_init(CURL *easy_handle); -.fi -.SH DESCRIPTION -\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure. -This mime structure can be subsequently filled using the mime API, then -attached to some easy handle using option \fICURLOPT_MIMEPOST(3)\fP within -a \fIcurl_easy_setopt(3)\fP call or added as a multipart in another mime -handle's part using \fIcurl_mime_subparts(3)\fP. - -\fIeasy_handle\fP is used for part separator randomization and error -reporting. Since 7.87.0, it does not need to be the final target handle. - -Using a mime handle is the recommended way to post an HTTP form, format and -send a multi-part email with SMTP or upload such an email to an IMAP server. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *easy = curl_easy_init(); - curl_mime *mime; - curl_mimepart *part; - - /* Build an HTTP form with a single field named "data", */ - mime = curl_mime_init(easy); - part = curl_mime_addpart(mime); - curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED); - curl_mime_name(part, "data"); - - /* Post and send it. */ - curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); - curl_easy_setopt(easy, CURLOPT_URL, "https://example.com"); - curl_easy_perform(easy); - - /* Clean-up. */ - curl_easy_cleanup(easy); - curl_mime_free(mime); -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -A mime struct handle, or NULL upon failure. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_free (3), -.BR curl_mime_subparts (3), -.BR CURLOPT_MIMEPOST (3) diff --git a/docs/libcurl/curl_mime_init.md b/docs/libcurl/curl_mime_init.md new file mode 100644 index 00000000000..0811bb3d8c6 --- /dev/null +++ b/docs/libcurl/curl_mime_init.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_init +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MIMEPOST (3) + - curl_mime_addpart (3) + - curl_mime_free (3) + - curl_mime_subparts (3) +--- + +# NAME + +curl_mime_init - create a mime handle + +# SYNOPSIS + +~~~c +#include + +curl_mime *curl_mime_init(CURL *easy_handle); +~~~ + +# DESCRIPTION + +curl_mime_init(3) creates a handle to a new empty mime structure. +This mime structure can be subsequently filled using the mime API, then +attached to some easy handle using option CURLOPT_MIMEPOST(3) within +a curl_easy_setopt(3) call or added as a multipart in another mime +handle's part using curl_mime_subparts(3). + +*easy_handle* is used for part separator randomization and error +reporting. Since 7.87.0, it does not need to be the final target handle. + +Using a mime handle is the recommended way to post an HTTP form, format and +send a multi-part email with SMTP or upload such an email to an IMAP server. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *easy = curl_easy_init(); + curl_mime *mime; + curl_mimepart *part; + + /* Build an HTTP form with a single field named "data", */ + mime = curl_mime_init(easy); + part = curl_mime_addpart(mime); + curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED); + curl_mime_name(part, "data"); + + /* Post and send it. */ + curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); + curl_easy_setopt(easy, CURLOPT_URL, "https://example.com"); + curl_easy_perform(easy); + + /* Clean-up. */ + curl_easy_cleanup(easy); + curl_mime_free(mime); +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +A mime struct handle, or NULL upon failure. diff --git a/docs/libcurl/curl_mime_name.3 b/docs/libcurl/curl_mime_name.3 deleted file mode 100644 index 52953e5487f..00000000000 --- a/docs/libcurl/curl_mime_name.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_name 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_name - set a mime part's name -.SH SYNOPSIS -.nf -#include - -CURLcode curl_mime_name(curl_mimepart *part, const char *name); -.fi -.SH DESCRIPTION -\fIcurl_mime_name(3)\fP sets a mime part's name. This is the way HTTP form -fields are named. - -\fIpart\fP is the part's handle to assign a name to. - -\fIname\fP points to the null-terminated name string. - -The name string is copied into the part, thus the associated storage may -safely be released or reused after call. Setting a part's name multiple times -is valid: only the value set by the last call is retained. It is possible to -reset the name of a part by setting \fIname\fP to NULL. -.SH EXAMPLE -.nf -int main(void) -{ - curl_mime *mime; - curl_mimepart *part; - - CURL *curl = curl_easy_init(); - if(curl) { - /* create a mime handle */ - mime = curl_mime_init(curl); - - /* add a part */ - part = curl_mime_addpart(mime); - - /* give the part a name */ - curl_mime_name(part, "shoe_size"); - } -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -CURLE_OK or a CURL error code upon failure. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_data (3), -.BR curl_mime_type (3) diff --git a/docs/libcurl/curl_mime_name.md b/docs/libcurl/curl_mime_name.md new file mode 100644 index 00000000000..bd25033977d --- /dev/null +++ b/docs/libcurl/curl_mime_name.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_name +Section: 3 +Source: libcurl +See-also: + - curl_mime_addpart (3) + - curl_mime_data (3) + - curl_mime_type (3) +--- + +# NAME + +curl_mime_name - set a mime part's name + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_mime_name(curl_mimepart *part, const char *name); +~~~ + +# DESCRIPTION + +curl_mime_name(3) sets a mime part's name. This is the way HTTP form +fields are named. + +*part* is the part's handle to assign a name to. + +*name* points to the null-terminated name string. + +The name string is copied into the part, thus the associated storage may +safely be released or reused after call. Setting a part's name multiple times +is valid: only the value set by the last call is retained. It is possible to +reset the name of a part by setting *name* to NULL. + +# EXAMPLE + +~~~c +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* give the part a name */ + curl_mime_name(part, "shoe_size"); + } +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +CURLE_OK or a CURL error code upon failure. diff --git a/docs/libcurl/curl_mime_subparts.3 b/docs/libcurl/curl_mime_subparts.3 deleted file mode 100644 index 459f3cdcc7c..00000000000 --- a/docs/libcurl/curl_mime_subparts.3 +++ /dev/null @@ -1,88 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_subparts 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_subparts - set sub-parts of a multipart mime part -.SH SYNOPSIS -.nf -#include - -CURLcode curl_mime_subparts(curl_mimepart *part, curl_mime *subparts); -.fi -.SH DESCRIPTION -\fIcurl_mime_subparts(3)\fP sets a multipart mime part's content from a mime -structure. - -\fIpart\fP is a handle to the multipart part. - -\fIsubparts\fP is a mime structure handle holding the sub-parts. After -\fIcurl_mime_subparts(3)\fP succeeds, the mime structure handle belongs to the -multipart part and must not be freed explicitly. It may however be updated by -subsequent calls to mime API functions. - -Setting a part's contents multiple times is valid: only the value set by the -last call is retained. It is possible to unassign previous part's contents by -setting \fIsubparts\fP to NULL. -.SH EXAMPLE -.nf - -static char *inline_html = "example"; -static char *inline_text = "once upon the time"; - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct curl_slist *slist; - - /* The inline part is an alternative proposing the html and the text - versions of the email. */ - curl_mime *alt = curl_mime_init(curl); - curl_mimepart *part; - - /* HTML message. */ - part = curl_mime_addpart(alt); - curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED); - curl_mime_type(part, "text/html"); - - /* Text message. */ - part = curl_mime_addpart(alt); - curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED); - - /* Create the inline part. */ - part = curl_mime_addpart(alt); - curl_mime_subparts(part, alt); - curl_mime_type(part, "multipart/alternative"); - slist = curl_slist_append(NULL, "Content-Disposition: inline"); - curl_mime_headers(part, slist, 1); - } -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -CURLE_OK or a CURL error code upon failure. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_init (3) diff --git a/docs/libcurl/curl_mime_subparts.md b/docs/libcurl/curl_mime_subparts.md new file mode 100644 index 00000000000..4136a1b2a5d --- /dev/null +++ b/docs/libcurl/curl_mime_subparts.md @@ -0,0 +1,83 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_subparts +Section: 3 +Source: libcurl +See-also: + - curl_mime_addpart (3) + - curl_mime_init (3) +--- + +# NAME + +curl_mime_subparts - set sub-parts of a multipart mime part + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_mime_subparts(curl_mimepart *part, curl_mime *subparts); +~~~ + +# DESCRIPTION + +curl_mime_subparts(3) sets a multipart mime part's content from a mime +structure. + +*part* is a handle to the multipart part. + +*subparts* is a mime structure handle holding the sub-parts. After +curl_mime_subparts(3) succeeds, the mime structure handle belongs to the +multipart part and must not be freed explicitly. It may however be updated by +subsequent calls to mime API functions. + +Setting a part's contents multiple times is valid: only the value set by the +last call is retained. It is possible to unassign previous part's contents by +setting *subparts* to NULL. + +# EXAMPLE + +~~~c + +static char *inline_html = "example"; +static char *inline_text = "once upon the time"; + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_slist *slist; + + /* The inline part is an alternative proposing the html and the text + versions of the email. */ + curl_mime *alt = curl_mime_init(curl); + curl_mimepart *part; + + /* HTML message. */ + part = curl_mime_addpart(alt); + curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED); + curl_mime_type(part, "text/html"); + + /* Text message. */ + part = curl_mime_addpart(alt); + curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED); + + /* Create the inline part. */ + part = curl_mime_addpart(alt); + curl_mime_subparts(part, alt); + curl_mime_type(part, "multipart/alternative"); + slist = curl_slist_append(NULL, "Content-Disposition: inline"); + curl_mime_headers(part, slist, 1); + } +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +CURLE_OK or a CURL error code upon failure. diff --git a/docs/libcurl/curl_mime_type.3 b/docs/libcurl/curl_mime_type.3 deleted file mode 100644 index 3e4ac822bac..00000000000 --- a/docs/libcurl/curl_mime_type.3 +++ /dev/null @@ -1,91 +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 -.\" * -.\" ************************************************************************** -.TH curl_mime_type 3 "22 August 2017" "libcurl" "libcurl" -.SH NAME -curl_mime_type - set a mime part's content type -.SH SYNOPSIS -.nf -#include - -CURLcode curl_mime_type(curl_mimepart *part, const char *mimetype); -.fi -.SH DESCRIPTION -\fIcurl_mime_type(3)\fP sets a mime part's content type. - -\fIpart\fP is the part's handle to assign the content type to. - -\fImimetype\fP points to the null-terminated file mime type string; it may be -set to NULL to remove a previously attached mime type. - -The mime type string is copied into the part, thus the associated storage may -safely be released or reused after call. Setting a part's type multiple times -is valid: only the value set by the last call is retained. - -In the absence of a mime type and if needed by the protocol specifications, -a default mime type is determined by the context: - -- If set as a custom header, use this value. - -- application/form-data for an HTTP form post. - -- If a remote file name is set, the mime type is taken from the file name -extension, or application/octet-stream by default. - -- For a multipart part, multipart/mixed. - -- text/plain in other cases. -.SH EXAMPLE -.nf -int main(void) -{ - curl_mime *mime; - curl_mimepart *part; - - CURL *curl = curl_easy_init(); - if(curl) { - /* create a mime handle */ - mime = curl_mime_init(curl); - - /* add a part */ - part = curl_mime_addpart(mime); - - /* get data from this file */ - curl_mime_filedata(part, "image.png"); - - /* content-type for this part */ - curl_mime_type(part, "image/png"); - - /* set name */ - curl_mime_name(part, "image"); -} -} -.fi -.SH AVAILABILITY -As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. -.SH RETURN VALUE -CURLE_OK or a CURL error code upon failure. -.SH "SEE ALSO" -.BR curl_mime_addpart (3), -.BR curl_mime_data (3), -.BR curl_mime_name (3) diff --git a/docs/libcurl/curl_mime_type.md b/docs/libcurl/curl_mime_type.md new file mode 100644 index 00000000000..fcdb77f4cd2 --- /dev/null +++ b/docs/libcurl/curl_mime_type.md @@ -0,0 +1,86 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_mime_type +Section: 3 +Source: libcurl +See-also: + - curl_mime_addpart (3) + - curl_mime_data (3) + - curl_mime_name (3) +--- + +# NAME + +curl_mime_type - set a mime part's content type + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_mime_type(curl_mimepart *part, const char *mimetype); +~~~ + +# DESCRIPTION + +curl_mime_type(3) sets a mime part's content type. + +*part* is the part's handle to assign the content type to. + +*mimetype* points to the null-terminated file mime type string; it may be +set to NULL to remove a previously attached mime type. + +The mime type string is copied into the part, thus the associated storage may +safely be released or reused after call. Setting a part's type multiple times +is valid: only the value set by the last call is retained. + +In the absence of a mime type and if needed by the protocol specifications, +a default mime type is determined by the context: + +- If set as a custom header, use this value. + +- application/form-data for an HTTP form post. + +- If a remote file name is set, the mime type is taken from the file name +extension, or application/octet-stream by default. + +- For a multipart part, multipart/mixed. + +- text/plain in other cases. + +# EXAMPLE + +~~~c +int main(void) +{ + curl_mime *mime; + curl_mimepart *part; + + CURL *curl = curl_easy_init(); + if(curl) { + /* create a mime handle */ + mime = curl_mime_init(curl); + + /* add a part */ + part = curl_mime_addpart(mime); + + /* get data from this file */ + curl_mime_filedata(part, "image.png"); + + /* content-type for this part */ + curl_mime_type(part, "image/png"); + + /* set name */ + curl_mime_name(part, "image"); +} +} +~~~ + +# AVAILABILITY + +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. + +# RETURN VALUE + +CURLE_OK or a CURL error code upon failure. diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.md similarity index 56% rename from docs/libcurl/curl_mprintf.3 rename to docs/libcurl/curl_mprintf.md index ac746cbea3f..5aca9e3f6be 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.md @@ -1,33 +1,25 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_printf 3 "30 April 2004" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_printf +Section: 3 +Source: libcurl +See-also: + - fprintf (3) + - printf (3) + - sprintf (3) + - vprintf (3) +--- + +# NAME + curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf, curl_mvsprintf - formatted output conversion -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include int curl_mprintf(const char *format, ...); @@ -41,8 +33,10 @@ int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format, va_list args); char *curl_maprintf(const char *format , ...); char *curl_mvaprintf(const char *format, va_list args); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + These functions produce output according to the format string and given arguments. They are mostly clones of the well-known C-style functions but there are slight differences in behavior. @@ -50,41 +44,43 @@ there are slight differences in behavior. We discourage users from using any of these functions in new applications. Functions in the curl_mprintf() family produce output according to a format as -described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP -write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and -\fBcurl_mvfprintf()\fP write output to the given output stream; -\fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and -\fBcurl_mvsnprintf()\fP write to the character string \fBbuffer\fP. - -The functions \fBcurl_msnprintf()\fP and \fBcurl_mvsnprintf()\fP write at most -\fImaxlength\fP bytes (including the terminating null byte ('\\0')) to -\fIbuffer\fP. - -The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP, -\fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the -functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP, -\fBcurl_msnprintf()\fP, respectively, except that they are called with a -\fIva_list\fP instead of a variable number of arguments. These functions do -not call the \fIva_end\fP macro. Because they invoke the \fIva_arg\fP macro, -the value of \fIap\fP is undefined after the call. - -The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the +described below. The functions **curl_mprintf()** and **curl_mvprintf()** +write output to stdout, the standard output stream; **curl_mfprintf()** and +**curl_mvfprintf()** write output to the given output stream; +**curl_msprintf()**, **curl_msnprintf()**, **curl_mvsprintf()**, and +**curl_mvsnprintf()** write to the character string **buffer**. + +The functions **curl_msnprintf()** and **curl_mvsnprintf()** write at most +*maxlength* bytes (including the terminating null byte ('0')) to +*buffer*. + +The functions **curl_mvprintf()**, **curl_mvfprintf()**, +**curl_mvsprintf()**, **curl_mvsnprintf()** are equivalent to the +functions **curl_mprintf()**, **curl_mfprintf()**, **curl_msprintf()**, +**curl_msnprintf()**, respectively, except that they are called with a +*va_list* instead of a variable number of arguments. These functions do +not call the *va_end* macro. Because they invoke the *va_arg* macro, +the value of *ap* is undefined after the call. + +The functions **curl_maprintf()** and **curl_mvaprintf()** return the output string as pointer to a newly allocated memory area. The returned string -must be \fIcurl_free(3)\fPed by the receiver. +must be curl_free(3)ed by the receiver. All of these functions write the output under the control of a format string that specifies how subsequent arguments are converted for output. -.SH FORMAT STRING +# FORMAT STRING + The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order) zero -or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional -\fIprecision\fP and an optional \fIlength modifier\fP. +or more *flags*, an optional minimum *field width*, an optional +*precision* and an optional *length modifier*. + +# The $ modifier -.SH "The $ modifier" The arguments must correspond properly with the conversion specifier. By default, the arguments are used in the order given, where each '*' (see Field width and Precision below) and each conversion specifier asks for the next @@ -93,13 +89,13 @@ can also specify explicitly which argument is taken, at each place where an argument is required, by writing "%m$" instead of '%' and "*m$" instead of '*', where the decimal integer m denotes the position in the argument list of the desired argument, indexed starting from 1. Thus, -.nf +~~~c curl_mprintf("%*d", width, num); -.fi +~~~ and -.nf +~~~c curl_mprintf("%2$*1$d", width, num); -.fi +~~~ are equivalent. The second style allows repeated references to the same argument. @@ -110,130 +106,183 @@ the numbers of arguments specified using '$'; for example, if arguments 1 and 3 are specified, argument 2 must also be specified somewhere in the format string. -.SH "Flag characters" +# Flag characters + The character % is followed by zero or more of the following flags: -.IP # +## # + The value should be converted to its "alternate form". -.IP 0 + +## 0 + The value should be zero padded. -.IP - -The converted value is to be left adjusted on the field boundary. (The -default is right justification.) The converted value is padded on the right -with blanks, rather than on the left with blanks or zeros. A '-' overrides a -\&'0' if both are given. -.IP ' ' -(a space) A blank should be left before a positive number (or empty string) -produced by a signed conversion. -.IP + + +## - + +The converted value is to be left adjusted on the field boundary. (The default +is right justification.) The converted value is padded on the right with +blanks, rather than on the left with blanks or zeros. A '-' overrides a &'0' +if both are given. + +## (space) + +(a space: ' ') A blank should be left before a positive number (or empty +string) produced by a signed conversion. + +## + + A sign (+ or -) should always be placed before a number produced by a signed conversion. By default, a sign is used only for negative numbers. A '+' overrides a space if both are used. -.SH "Field width" + +# Field width + An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it gets padded with spaces on the left (or right, if the left-adjustment flag has been given). Instead of a decimal digit string one may write "*" or "*m$" (for some decimal integer m) to specify that the field -width is given in the next argument, or in the \fIm-th\fP argument, +width is given in the next argument, or in the *m-th* argument, respectively, which must be of type int. A negative field width is taken as a '-' flag followed by a positive field width. In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. -.SH "Precision" + +# Precision + An optional precision in the form of a period ('.') followed by an optional decimal digit string. Instead of a decimal digit string one may write "*" or "*m$" (for some decimal integer m) to specify that the precision is given in -the next argument, or in the \fIm-th\fP argument, respectively, which must be of +the next argument, or in the *m-th* argument, respectively, which must be of type int. If the precision is given as just '.', the precision is taken to be zero. A negative precision is taken as if the precision were omitted. This -gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP, -\fBu\fP, \fBx\fP, and \fBX\fP conversions, the number of digits to appear -after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and -\fBF\fP conversions, the maximum number of significant digits for \fBg\fP and -\fBG\fP conversions, or the maximum number of characters to be printed from a -string for \fBs\fP and \fBS\fP conversions. -.SH "Length modifier" -.IP h -A following integer conversion corresponds to a \fIshort\fP or \fIunsigned -short\fP argument. -.IP l -(ell) A following integer conversion corresponds to a \fIlong\fP or -\fIunsigned long\fP argument, or a following n conversion corresponds to a +gives the minimum number of digits to appear for **d**, **i**, **o**, +**u**, **x**, and **X** conversions, the number of digits to appear +after the radix character for **a**, **A**, **e**, **E**, **f**, and +**F** conversions, the maximum number of significant digits for **g** and +**G** conversions, or the maximum number of characters to be printed from a +string for **s** and **S** conversions. + +# Length modifier + +## h + +A following integer conversion corresponds to a *short* or *unsigned short* +argument. + +## l + +(ell) A following integer conversion corresponds to a *long* or +*unsigned long* argument, or a following n conversion corresponds to a pointer to a long argument -.IP ll -(ell-ell). A following integer conversion corresponds to a \fIlong long\fP or -\fIunsigned long long\fP argument, or a following n conversion corresponds to + +## ll + +(ell-ell). A following integer conversion corresponds to a *long long* or +*unsigned long long* argument, or a following n conversion corresponds to a pointer to a long long argument. -.IP q -A synonym for \fBll\fP. -.IP L + +## q + +A synonym for **ll**. + +## L + A following a, A, e, E, f, F, g, or G conversion corresponds to a long double argument. -.IP z -A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP + +## z + +A following integer conversion corresponds to a *size_t* or *ssize_t* argument. -.SH "Conversion specifiers" + +# Conversion specifiers + A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are: -.IP "d, i" + +## d, i + The int argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. -.IP "o, u, x, X" + +## o, u, x, X + The unsigned int argument is converted to unsigned octal (o), unsigned decimal -(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters -\fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are -used for \fBX\fP conversions. The precision, if any, gives the minimum number +(u), or unsigned hexadecimal (**x** and **X**) notation. The letters +*abcdef* are used for **x** conversions; the letters *ABCDEF* are +used for **X** conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. -.IP "e, E" -The double argument is rounded and output in the style \fB"[-]d.ddde±dd"\fP -.IP "f, F" + +## e, E + +The double argument is rounded and output in the style **"[-]d.ddde±dd"** + +## f, F + The double argument is rounded and output to decimal notation in the style -\fB"[-]ddd.ddd"\fP. -.IP "g, G" +**"[-]ddd.ddd"**. + +## g, G + The double argument is converted in style f or e. -.IP "c" + +## c + The int argument is converted to an unsigned char, and the resulting character is written. -.IP "s" -The \fIconst char *\fP argument is expected to be a pointer to an array of + +## s + +The *const char ** argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating null byte. If a precision is specified, no more than the number specified are written. If a precision is given, no null byte need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating null byte. -.IP "p" -The \fIvoid *\fP pointer argument is printed in hexadecimal. -.IP "n" + +## p + +The *void ** pointer argument is printed in hexadecimal. + +## n + The number of characters written so far is stored into the integer pointed to by the corresponding argument. -.IP "%" + +## % + A '%' symbol is written. No argument is converted. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c const char *name = "John"; int main(void) { - curl_mprintf("My name is %s\\n", name); - curl_mprintf("Pi is almost %f\\n", (double)25.0/8); + curl_mprintf("My name is %s\n", name); + curl_mprintf("Pi is almost %f\n", (double)25.0/8); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + These functions might be removed from the public libcurl API in the future. Do not use them in new programs or projects. -.SH RETURN VALUE -The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to + +# RETURN VALUE + +The **curl_maprintf** and **curl_mvaprintf** functions return a pointer to a newly allocated string, or NULL if it failed. All other functions return the number of characters actually printed (excluding the null byte used to end output to strings). Note that this sometimes differ from how the POSIX versions of these functions work. -.SH "SEE ALSO" -.BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) " diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 deleted file mode 100644 index 749b24e672e..00000000000 --- a/docs/libcurl/curl_multi_add_handle.3 +++ /dev/null @@ -1,93 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_add_handle 3 "4 March 2002" "libcurl" "libcurl" -.SH NAME -curl_multi_add_handle - add an easy handle to a multi session -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); -.fi -.SH DESCRIPTION -Adds the \fIeasy handle\fP to the \fImulti_handle\fP. - -While an easy handle is added to a multi stack, you cannot and you must not -use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy -handle from the multi stack again, it is perfectly fine to use it with the -easy interface again. - -If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) cache, -it is made to use a DNS cache that is shared between all easy handles within -the multi handle when \fIcurl_multi_add_handle(3)\fP is called. - -When an easy interface is added to a multi handle, it is set to use a shared -connection cache owned by the multi handle. Removing and adding new easy -handles does not affect the pool of connections or the ability to do -connection reuse. - -If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (as you -should if you are working event-based with \fIcurl_multi_socket_action(3)\fP -and friends), that callback is called from within this function to ask for an -updated timer so that your main event loop gets the activity on this handle to -get started. - -The easy handle remains added to the multi handle until you remove it again -with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that -specific easy handle is completed. - -You should remove the easy handle from the multi stack before you terminate -first the easy handle and then the multi handle: - -1 - \fIcurl_multi_remove_handle(3)\fP - -2 - \fIcurl_easy_cleanup(3)\fP - -3 - \fIcurl_multi_cleanup(3)\fP -.SH EXAMPLE -.nf -int main(void) -{ - /* init a multi stack */ - CURLM *multi = curl_multi_init(); - - /* create two easy handles */ - CURL *http_handle = curl_easy_init(); - CURL *http_handle2 = curl_easy_init(); - - /* add individual transfers */ - curl_multi_add_handle(multi, http_handle); - curl_multi_add_handle(multi, http_handle2); -} -.fi -.SH AVAILABILITY -Added in 7.9.6 -.SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. -.SH "SEE ALSO" -.BR curl_multi_cleanup (3), -.BR curl_multi_get_handles (3), -.BR curl_multi_init (3), -.BR curl_multi_setopt (3), -.BR curl_multi_socket_action (3) diff --git a/docs/libcurl/curl_multi_add_handle.md b/docs/libcurl/curl_multi_add_handle.md new file mode 100644 index 00000000000..3d6ba81fb1f --- /dev/null +++ b/docs/libcurl/curl_multi_add_handle.md @@ -0,0 +1,88 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_add_handle +Section: 3 +Source: libcurl +See-also: + - curl_multi_cleanup (3) + - curl_multi_get_handles (3) + - curl_multi_init (3) + - curl_multi_setopt (3) + - curl_multi_socket_action (3) +--- + +# NAME + +curl_multi_add_handle - add an easy handle to a multi session + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); +~~~ + +# DESCRIPTION + +Adds the *easy handle* to the *multi_handle*. + +While an easy handle is added to a multi stack, you cannot and you must not +use curl_easy_perform(3) on that handle. After having removed the easy +handle from the multi stack again, it is perfectly fine to use it with the +easy interface again. + +If the easy handle is not set to use a shared (CURLOPT_SHARE(3)) cache, +it is made to use a DNS cache that is shared between all easy handles within +the multi handle when curl_multi_add_handle(3) is called. + +When an easy interface is added to a multi handle, it is set to use a shared +connection cache owned by the multi handle. Removing and adding new easy +handles does not affect the pool of connections or the ability to do +connection reuse. + +If you have CURLMOPT_TIMERFUNCTION(3) set in the multi handle (as you +should if you are working event-based with curl_multi_socket_action(3) +and friends), that callback is called from within this function to ask for an +updated timer so that your main event loop gets the activity on this handle to +get started. + +The easy handle remains added to the multi handle until you remove it again +with curl_multi_remove_handle(3) - even when a transfer with that +specific easy handle is completed. + +You should remove the easy handle from the multi stack before you terminate +first the easy handle and then the multi handle: + +1 - curl_multi_remove_handle(3) + +2 - curl_easy_cleanup(3) + +3 - curl_multi_cleanup(3) + +# EXAMPLE + +~~~c +int main(void) +{ + /* init a multi stack */ + CURLM *multi = curl_multi_init(); + + /* create two easy handles */ + CURL *http_handle = curl_easy_init(); + CURL *http_handle2 = curl_easy_init(); + + /* add individual transfers */ + curl_multi_add_handle(multi, http_handle); + curl_multi_add_handle(multi, http_handle2); +} +~~~ + +# AVAILABILITY + +Added in 7.9.6 + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3 deleted file mode 100644 index 5b617053668..00000000000 --- a/docs/libcurl/curl_multi_assign.3 +++ /dev/null @@ -1,84 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_assign 3 "9 Jul 2006" "libcurl" "libcurl" -.SH NAME -curl_multi_assign \- set data to associate with an internal socket -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd, - void *sockptr); -.fi -.SH DESCRIPTION -This function creates an association in the multi handle between the given -socket and a private pointer of the application. This is designed for -\fIcurl_multi_socket_action(3)\fP uses. - -When set, the \fIsockptr\fP pointer is passed to all future socket callbacks -for the specific \fIsockfd\fP socket. - -If the given \fIsockfd\fP is not already in use by libcurl, this function -returns an error. - -libcurl only keeps one single pointer associated with a socket, so calling -this function several times for the same socket makes the last set pointer get -used. - -The idea here being that this association (socket to private pointer) is -something that just about every application that uses this API needs and then -libcurl can just as well do it since it already has the necessary -functionality. - -It is acceptable to call this function from your multi callback functions. -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *multi = curl_multi_init(); - void *ourstructp; /* pointer to our data */ - curl_socket_t fd; /* file descriptor to associate our data with */ - - /* make our struct pointer associated with socket fd */ - CURLMcode mc = curl_multi_assign(multi, fd, ourstructp); - if(mc) - printf("error: %s\\n", curl_multi_strerror(mc)); -} -.fi -.SH AVAILABILITY -Added in 7.15.5 -.SH RETURN VALUE -The standard CURLMcode for multi interface error codes. -.SH TYPICAL USAGE -In a typical application you allocate a struct or at least use some kind of -semi-dynamic data for each socket that we must wait for action on when using -the \fIcurl_multi_socket_action(3)\fP approach. - -When our socket-callback gets called by libcurl and we get to know about yet -another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out -the particular data so that when we get updates about this same socket again, -we do not have to find the struct associated with this socket by ourselves. -.SH "SEE ALSO" -.BR curl_multi_setopt (3), -.BR curl_multi_socket_action (3) diff --git a/docs/libcurl/curl_multi_assign.md b/docs/libcurl/curl_multi_assign.md new file mode 100644 index 00000000000..3f01349cd0f --- /dev/null +++ b/docs/libcurl/curl_multi_assign.md @@ -0,0 +1,81 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_assign +Section: 3 +Source: libcurl +See-also: + - curl_multi_setopt (3) + - curl_multi_socket_action (3) +--- + +# NAME + +curl_multi_assign - set data to associate with an internal socket + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd, + void *sockptr); +~~~ + +# DESCRIPTION + +This function creates an association in the multi handle between the given +socket and a private pointer of the application. This is designed for +curl_multi_socket_action(3) uses. + +When set, the *sockptr* pointer is passed to all future socket callbacks +for the specific *sockfd* socket. + +If the given *sockfd* is not already in use by libcurl, this function +returns an error. + +libcurl only keeps one single pointer associated with a socket, so calling +this function several times for the same socket makes the last set pointer get +used. + +The idea here being that this association (socket to private pointer) is +something that just about every application that uses this API needs and then +libcurl can just as well do it since it already has the necessary +functionality. + +It is acceptable to call this function from your multi callback functions. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *multi = curl_multi_init(); + void *ourstructp; /* pointer to our data */ + curl_socket_t fd; /* file descriptor to associate our data with */ + + /* make our struct pointer associated with socket fd */ + CURLMcode mc = curl_multi_assign(multi, fd, ourstructp); + if(mc) + printf("error: %s\n", curl_multi_strerror(mc)); +} +~~~ + +# AVAILABILITY + +Added in 7.15.5 + +# RETURN VALUE + +The standard CURLMcode for multi interface error codes. + +# TYPICAL USAGE + +In a typical application you allocate a struct or at least use some kind of +semi-dynamic data for each socket that we must wait for action on when using +the curl_multi_socket_action(3) approach. + +When our socket-callback gets called by libcurl and we get to know about yet +another socket to wait for, we can use curl_multi_assign(3) to point out +the particular data so that when we get updates about this same socket again, +we do not have to find the struct associated with this socket by ourselves. diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 deleted file mode 100644 index 5b4aae26cef..00000000000 --- a/docs/libcurl/curl_multi_cleanup.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_cleanup 3 "1 March 2002" "libcurl" "libcurl" -.SH NAME -curl_multi_cleanup - close down a multi session -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_cleanup(CURLM *multi_handle); -.fi -.SH DESCRIPTION -Cleans up and removes a whole multi stack. It does not free or touch any -individual easy handles in any way - they still need to be closed -individually, using the usual \fIcurl_easy_cleanup(3)\fP way. The order of -cleaning up should be: - -1 - \fIcurl_multi_remove_handle(3)\fP before any easy handles are cleaned up - -2 - \fIcurl_easy_cleanup(3)\fP can now be called independently since the easy -handle is no longer connected to the multi handle - -3 - \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are -removed - -Passing in a NULL pointer in \fImulti_handle\fP makes this function return -CURLM_BAD_HANDLE immediately with no other action. -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *multi = curl_multi_init(); - - /* when the multi transfer is done ... */ - - /* remove all easy handles, then: */ - curl_multi_cleanup(multi); -} -.fi -.SH AVAILABILITY -Added in 7.9.6 -.SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. On success, -CURLM_OK is returned. -.SH "SEE ALSO" -.BR curl_easy_cleanup (3), -.BR curl_multi_get_handles (3), -.BR curl_easy_init (3), -.BR curl_multi_init (3) diff --git a/docs/libcurl/curl_multi_cleanup.md b/docs/libcurl/curl_multi_cleanup.md new file mode 100644 index 00000000000..9aa64a85c92 --- /dev/null +++ b/docs/libcurl/curl_multi_cleanup.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_cleanup +Section: 3 +Source: libcurl +See-also: + - curl_easy_cleanup (3) + - curl_easy_init (3) + - curl_multi_get_handles (3) + - curl_multi_init (3) +--- + +# NAME + +curl_multi_cleanup - close down a multi session + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_cleanup(CURLM *multi_handle); +~~~ + +# DESCRIPTION + +Cleans up and removes a whole multi stack. It does not free or touch any +individual easy handles in any way - they still need to be closed +individually, using the usual curl_easy_cleanup(3) way. The order of +cleaning up should be: + +1 - curl_multi_remove_handle(3) before any easy handles are cleaned up + +2 - curl_easy_cleanup(3) can now be called independently since the easy +handle is no longer connected to the multi handle + +3 - curl_multi_cleanup(3) should be called when all easy handles are +removed + +Passing in a NULL pointer in *multi_handle* makes this function return +CURLM_BAD_HANDLE immediately with no other action. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *multi = curl_multi_init(); + + /* when the multi transfer is done ... */ + + /* remove all easy handles, then: */ + curl_multi_cleanup(multi); +} +~~~ + +# AVAILABILITY + +Added in 7.9.6 + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. On success, +CURLM_OK is returned. diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 deleted file mode 100644 index 0afbe9a3ccf..00000000000 --- a/docs/libcurl/curl_multi_fdset.3 +++ /dev/null @@ -1,124 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_fdset 3 "2 Jan 2006" "libcurl" "libcurl" -.SH NAME -curl_multi_fdset - extracts file descriptor information from a multi handle -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_fdset(CURLM *multi_handle, - fd_set *read_fd_set, - fd_set *write_fd_set, - fd_set *exc_fd_set, - int *max_fd); -.fi -.SH DESCRIPTION -This function extracts file descriptor information from a given multi_handle. -libcurl returns its \fIfd_set\fP sets. The application can use these to -select() on, but be sure to \fIFD_ZERO\fP them before calling this function as -\fIcurl_multi_fdset(3)\fP only adds its own descriptors, it does not zero or -otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should -be called as soon as one of them is ready to be read from or written to. - -The \fIread_fd_set\fP argument should point to an object of type \fBfd_set\fP -that on returns specifies the file descriptors to be checked for being ready -to read. - -The \fIwrite_fd_set\fP argument should point to an object of type \fBfd_set\fP -that on return specifies the file descriptors to be checked for being ready to -write. - -The \fIexc_fd_set\fP argument should point to an object of type \fBfd_set\fP -that on return specifies the file descriptors to be checked for error -conditions. - -If no file descriptors are set by libcurl, \fImax_fd\fP contain -1 when this -function returns. Otherwise it contains the highest descriptor number libcurl -set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl currently -does something that is not possible for your application to monitor with a -socket and unfortunately you can then not know exactly when the current action -is completed using select(). You then need to wait a while before you proceed -and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless -\fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100 -milliseconds or so, but you may want to test it out in your own particular -conditions to find a suitable value. - -When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out -how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no -activity has been seen on the \fBfd_sets\fP after the timeout expires as -otherwise internal retries and timeouts may not work as you would think and -want. - -If one of the sockets used by libcurl happens to be larger than what can be -set in an \fBfd_set\fP, which on POSIX systems means that the file descriptor -is larger than \fBFD_SETSIZE\fP, then libcurl tries to not set it. Setting a -too large file descriptor in an \fBfd_set\fP implies an out of bounds write -which can cause crashes, or worse. The effect of NOT storing it might possibly -save you from the crash, but makes your program NOT wait for sockets it should -wait for... -.SH EXAMPLE -.nf -int main(void) -{ - fd_set fdread; - fd_set fdwrite; - fd_set fdexcep; - int maxfd; - int rc; - CURLMcode mc; - struct timeval timeout = {1, 0}; - - CURLM *multi = curl_multi_init(); - - do { - - /* call curl_multi_perform() */ - - /* get file descriptors from the transfers */ - mc = curl_multi_fdset(multi, &fdread, &fdwrite, &fdexcep, &maxfd); - - if(mc != CURLM_OK) { - fprintf(stderr, "curl_multi_fdset() failed, code %d.\\n", mc); - break; - } - - /* wait for activity on one of the sockets */ - rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); - - } while(!mc); -} -.fi -.SH AVAILABILITY -Added in 7.9.6 -.SH RETURN VALUE -\fBCURLMcode\fP type, general libcurl multi interface error code. See -\fIlibcurl-errors(3)\fP -.SH "SEE ALSO" -.BR curl_multi_cleanup (3), -.BR curl_multi_init (3), -.BR curl_multi_perform (3), -.BR curl_multi_timeout (3), -.BR curl_multi_wait (3), -.BR select (2) diff --git a/docs/libcurl/curl_multi_fdset.md b/docs/libcurl/curl_multi_fdset.md new file mode 100644 index 00000000000..37d5959d18e --- /dev/null +++ b/docs/libcurl/curl_multi_fdset.md @@ -0,0 +1,119 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_fdset +Section: 3 +Source: libcurl +See-also: + - curl_multi_cleanup (3) + - curl_multi_init (3) + - curl_multi_perform (3) + - curl_multi_timeout (3) + - curl_multi_wait (3) + - select (2) +--- + +# NAME + +curl_multi_fdset - extracts file descriptor information from a multi handle + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_fdset(CURLM *multi_handle, + fd_set *read_fd_set, + fd_set *write_fd_set, + fd_set *exc_fd_set, + int *max_fd); +~~~ + +# DESCRIPTION + +This function extracts file descriptor information from a given multi_handle. +libcurl returns its *fd_set* sets. The application can use these to +select() on, but be sure to *FD_ZERO* them before calling this function as +curl_multi_fdset(3) only adds its own descriptors, it does not zero or +otherwise remove any others. The curl_multi_perform(3) function should +be called as soon as one of them is ready to be read from or written to. + +The *read_fd_set* argument should point to an object of type **fd_set** +that on returns specifies the file descriptors to be checked for being ready +to read. + +The *write_fd_set* argument should point to an object of type **fd_set** +that on return specifies the file descriptors to be checked for being ready to +write. + +The *exc_fd_set* argument should point to an object of type **fd_set** +that on return specifies the file descriptors to be checked for error +conditions. + +If no file descriptors are set by libcurl, *max_fd* contain -1 when this +function returns. Otherwise it contains the highest descriptor number libcurl +set. When libcurl returns -1 in *max_fd*, it is because libcurl currently +does something that is not possible for your application to monitor with a +socket and unfortunately you can then not know exactly when the current action +is completed using select(). You then need to wait a while before you proceed +and call curl_multi_perform(3) anyway. How long to wait? Unless +curl_multi_timeout(3) gives you a lower number, we suggest 100 +milliseconds or so, but you may want to test it out in your own particular +conditions to find a suitable value. + +When doing select(), you should use curl_multi_timeout(3) to figure out +how long to wait for action. Call curl_multi_perform(3) even if no +activity has been seen on the **fd_sets** after the timeout expires as +otherwise internal retries and timeouts may not work as you would think and +want. + +If one of the sockets used by libcurl happens to be larger than what can be +set in an **fd_set**, which on POSIX systems means that the file descriptor +is larger than **FD_SETSIZE**, then libcurl tries to not set it. Setting a +too large file descriptor in an **fd_set** implies an out of bounds write +which can cause crashes, or worse. The effect of NOT storing it might possibly +save you from the crash, but makes your program NOT wait for sockets it should +wait for... + +# EXAMPLE + +~~~c +int main(void) +{ + fd_set fdread; + fd_set fdwrite; + fd_set fdexcep; + int maxfd; + int rc; + CURLMcode mc; + struct timeval timeout = {1, 0}; + + CURLM *multi = curl_multi_init(); + + do { + + /* call curl_multi_perform() */ + + /* get file descriptors from the transfers */ + mc = curl_multi_fdset(multi, &fdread, &fdwrite, &fdexcep, &maxfd); + + if(mc != CURLM_OK) { + fprintf(stderr, "curl_multi_fdset() failed, code %d.\n", mc); + break; + } + + /* wait for activity on one of the sockets */ + rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); + + } while(!mc); +} +~~~ + +# AVAILABILITY + +Added in 7.9.6 + +# RETURN VALUE + +**CURLMcode** type, general libcurl multi interface error code. See +libcurl-errors(3) diff --git a/docs/libcurl/curl_multi_get_handles.3 b/docs/libcurl/curl_multi_get_handles.3 deleted file mode 100644 index 060c6e65143..00000000000 --- a/docs/libcurl/curl_multi_get_handles.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_get_handles 3 "28 August 2023" "libcurl" "libcurl" -.SH NAME -curl_multi_get_handles - returns all added easy handles -.SH SYNOPSIS -.nf -#include - -CURL **curl_multi_get_handles(CURLM *multi_handle); -.fi -.SH DESCRIPTION -Returns an array with pointers to all added easy handles. The end of the list -is marked with a NULL pointer. - -Even if there is not a single easy handle added, this still returns an array -but with only a single NULL pointer entry. - -The returned array contains all the handles that are present at the time of -the call. As soon as a handle has been removed from or a handle has been added -to the multi handle after the handle array was returned, the two data points -are out of sync. - -The order of the easy handles within the array is not guaranteed. - -The returned array must be freed with a call to \fIcurl_free(3)\fP after use. -.SH EXAMPLE -.nf -int main(void) -{ - /* init a multi stack */ - CURLM *multi = curl_multi_init(); - CURL *curl = curl_easy_init(); - - if(curl) { - /* add the transfer */ - curl_multi_add_handle(multi, curl); - - /* extract all added handles */ - CURL **list = curl_multi_get_handles(multi); - - if(list) { - int i; - /* remove all added handles */ - for(i = 0; list[i]; i++) { - curl_multi_remove_handle(multi, list[i]); - } - curl_free(list); - } - } -} -.fi -.SH AVAILABILITY -Added in 8.4.0 -.SH RETURN VALUE -Returns NULL on failure. Otherwise it returns a pointer to an allocated array. -.SH "SEE ALSO" -.BR curl_multi_add_handle (3), -.BR curl_multi_cleanup (3), -.BR curl_multi_init (3), -.BR curl_multi_remove_handle (3) diff --git a/docs/libcurl/curl_multi_get_handles.md b/docs/libcurl/curl_multi_get_handles.md new file mode 100644 index 00000000000..0a7ff67caf1 --- /dev/null +++ b/docs/libcurl/curl_multi_get_handles.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_get_handles +Section: 3 +Source: libcurl +See-also: + - curl_multi_add_handle (3) + - curl_multi_cleanup (3) + - curl_multi_init (3) + - curl_multi_remove_handle (3) +--- + +# NAME + +curl_multi_get_handles - returns all added easy handles + +# SYNOPSIS + +~~~c +#include + +CURL **curl_multi_get_handles(CURLM *multi_handle); +~~~ + +# DESCRIPTION + +Returns an array with pointers to all added easy handles. The end of the list +is marked with a NULL pointer. + +Even if there is not a single easy handle added, this still returns an array +but with only a single NULL pointer entry. + +The returned array contains all the handles that are present at the time of +the call. As soon as a handle has been removed from or a handle has been added +to the multi handle after the handle array was returned, the two data points +are out of sync. + +The order of the easy handles within the array is not guaranteed. + +The returned array must be freed with a call to curl_free(3) after use. + +# EXAMPLE + +~~~c +int main(void) +{ + /* init a multi stack */ + CURLM *multi = curl_multi_init(); + CURL *curl = curl_easy_init(); + + if(curl) { + /* add the transfer */ + curl_multi_add_handle(multi, curl); + + /* extract all added handles */ + CURL **list = curl_multi_get_handles(multi); + + if(list) { + int i; + /* remove all added handles */ + for(i = 0; list[i]; i++) { + curl_multi_remove_handle(multi, list[i]); + } + curl_free(list); + } + } +} +~~~ + +# AVAILABILITY + +Added in 8.4.0 + +# RETURN VALUE + +Returns NULL on failure. Otherwise it returns a pointer to an allocated array. diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.md similarity index 51% rename from docs/libcurl/curl_multi_info_read.3 rename to docs/libcurl/curl_multi_info_read.md index c833548c898..23d515d8f81 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.md @@ -1,36 +1,29 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_multi_info_read 3 "18 Dec 2004" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_info_read +Section: 3 +Source: libcurl +See-also: + - curl_multi_cleanup (3) + - curl_multi_init (3) + - curl_multi_perform (3) +--- + +# NAME + curl_multi_info_read - read multi stack information -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Ask the multi handle if there are any messages from the individual transfers. Messages may include information such as an error code from the transfer or just the fact that a transfer is completed. More details on these @@ -38,7 +31,7 @@ should be written down as well. Repeated calls to this function returns a new struct each time, until a NULL is returned as a signal that there is no more to get at this point. The -integer pointed to with \fImsgs_in_queue\fP contains the number of remaining +integer pointed to with *msgs_in_queue* contains the number of remaining messages after this function was called. When you fetch a message using this function, it is removed from the internal @@ -46,16 +39,16 @@ queue so calling this function again does not return the same message again. It instead returns new messages at each new invoke until the queue is emptied. -\fBWARNING:\fP The data the returned pointer points to does not survive -calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or -\fIcurl_easy_cleanup(3)\fP. +**WARNING:** The data the returned pointer points to does not survive +calling curl_multi_cleanup(3), curl_multi_remove_handle(3) or +curl_easy_cleanup(3). -The \fICURLMsg\fP struct is simple and only contains basic information. If +The *CURLMsg* struct is simple and only contains basic information. If more involved information is wanted, the particular "easy handle" is present in that struct and can be used in subsequent regular -\fIcurl_easy_getinfo(3)\fP calls (or similar): +curl_easy_getinfo(3) calls (or similar): -.nf +~~~c struct CURLMsg { CURLMSG msg; /* what this message means */ CURL *easy_handle; /* the handle it concerns */ @@ -64,14 +57,16 @@ in that struct and can be used in subsequent regular CURLcode result; /* return code for transfer */ } data; }; -.fi -When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that -is done, and then \fBresult\fP contains the return code for the easy handle +~~~ +When **msg** is *CURLMSG_DONE*, the message identifies a transfer that +is done, and then **result** contains the return code for the easy handle that just completed. -At this point, there are no other \fBmsg\fP types defined. -.SH EXAMPLE -.nf +At this point, there are no other **msg** types defined. + +# EXAMPLE + +~~~c int main(void) { CURLM *multi = curl_multi_init(); @@ -94,14 +89,14 @@ int main(void) } while(m); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.9.6 -.SH RETURN VALUE + +# RETURN VALUE + A pointer to a filled-in struct, or NULL if it failed or ran out of structs. It also writes the number of messages left in the queue (after this read) in the integer the second argument points to. -.SH "SEE ALSO" -.BR curl_multi_cleanup (3), -.BR curl_multi_init (3), -.BR curl_multi_perform (3) diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 deleted file mode 100644 index 4501a003196..00000000000 --- a/docs/libcurl/curl_multi_init.3 +++ /dev/null @@ -1,62 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_init 3 "1 March 2002" "libcurl" "libcurl" -.SH NAME -curl_multi_init - create a multi handle -.SH SYNOPSIS -.nf -#include - -CURLM *curl_multi_init(); -.fi -.SH DESCRIPTION -This function returns a pointer to a \fICURLM\fP handle to be used as input to -all the other multi-functions, sometimes referred to as a multi handle in some -places in the documentation. This init call MUST have a corresponding call to -\fIcurl_multi_cleanup(3)\fP when the operation is complete. -.SH EXAMPLE -.nf -int main(void) -{ - /* init a multi stack */ - CURLM *multi = curl_multi_init(); - CURL *curl = curl_easy_init(); - CURL *curl2 = curl_easy_init(); - - /* add individual transfers */ - curl_multi_add_handle(multi, curl); - curl_multi_add_handle(multi, curl2); -} -.fi -.SH AVAILABILITY -Added in 7.9.6 -.SH RETURN VALUE -If this function returns NULL, something went wrong and you cannot use the -other curl functions. -.SH "SEE ALSO" -.BR curl_multi_cleanup (3), -.BR curl_multi_add_handle (3), -.BR curl_multi_get_handles (3), -.BR curl_global_init (3), -.BR curl_easy_init (3) diff --git a/docs/libcurl/curl_multi_init.md b/docs/libcurl/curl_multi_init.md new file mode 100644 index 00000000000..0e91b57c178 --- /dev/null +++ b/docs/libcurl/curl_multi_init.md @@ -0,0 +1,57 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_init +Section: 3 +Source: libcurl +See-also: + - curl_easy_init (3) + - curl_global_init (3) + - curl_multi_add_handle (3) + - curl_multi_cleanup (3) + - curl_multi_get_handles (3) +--- + +# NAME + +curl_multi_init - create a multi handle + +# SYNOPSIS + +~~~c +#include + +CURLM *curl_multi_init(); +~~~ + +# DESCRIPTION + +This function returns a pointer to a *CURLM* handle to be used as input to +all the other multi-functions, sometimes referred to as a multi handle in some +places in the documentation. This init call MUST have a corresponding call to +curl_multi_cleanup(3) when the operation is complete. + +# EXAMPLE + +~~~c +int main(void) +{ + /* init a multi stack */ + CURLM *multi = curl_multi_init(); + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); + + /* add individual transfers */ + curl_multi_add_handle(multi, curl); + curl_multi_add_handle(multi, curl2); +} +~~~ + +# AVAILABILITY + +Added in 7.9.6 + +# RETURN VALUE + +If this function returns NULL, something went wrong and you cannot use the +other curl functions. diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 deleted file mode 100644 index 8088c433e3d..00000000000 --- a/docs/libcurl/curl_multi_perform.3 +++ /dev/null @@ -1,110 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_perform 3 "1 March 2002" "libcurl" "libcurl" -.SH NAME -curl_multi_perform - reads/writes available data from easy handles -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles); -.fi -.SH DESCRIPTION -This function performs transfers on all the added handles that need attention -in a non-blocking fashion. The easy handles have previously been added to the -multi handle with \fIcurl_multi_add_handle(3)\fP. - -When an application has found out there is data available for the multi_handle -or a timeout has elapsed, the application should call this function to -read/write whatever there is to read or write right now etc. -\fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This -function does not require that there actually is any data available for -reading or that data can be written, it can be called just in case. It stores -the number of handles that still transfer data in the second argument's -integer-pointer. - -If the amount of \fIrunning_handles\fP is changed from the previous call (or -is less than the amount of easy handles you have added to the multi handle), -you know that there is one or more transfers less "running". You can then call -\fIcurl_multi_info_read(3)\fP to get information about each individual -completed transfer, and that returned info includes CURLcode and more. If an -added handle fails quickly, it may never be counted as a running_handle. You -could use \fIcurl_multi_info_read(3)\fP to track actual status of the added -handles in that case. - -When \fIrunning_handles\fP is set to zero (0) on the return of this function, -there is no longer any transfers in progress. - -When this function returns error, the state of all transfers are uncertain and -they cannot be continued. \fIcurl_multi_perform(3)\fP should not be called -again on the same multi handle after an error has been returned, unless first -removing all the handles and adding new ones. -.SH EXAMPLE -.nf -int main(void) -{ - int still_running; - CURL *multi = curl_multi_init(); - CURL *curl = curl_easy_init(); - if(curl) { - curl_multi_add_handle(multi, curl); - do { - CURLMcode mc = curl_multi_perform(multi, &still_running); - - if(!mc && still_running) - /* wait for activity, timeout or "nothing" */ - mc = curl_multi_poll(multi, NULL, 0, 1000, NULL); - - if(mc) { - fprintf(stderr, "curl_multi_poll() failed, code %d.\\n", (int)mc); - break; - } - - /* if there are still transfers, loop! */ - } while(still_running); - } -} -.fi -.SH AVAILABILITY -Added in 7.9.6 -.SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. - -This function returns errors regarding the whole multi stack. Problems on -individual transfers may have occurred even when this function returns -\fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure out how individual -transfers did. -.SH "TYPICAL USAGE" -Most applications use \fIcurl_multi_poll(3)\fP to make libcurl wait for -activity on any of the ongoing transfers. As soon as one or more file -descriptor has activity or the function times out, the application calls -\fIcurl_multi_perform(3)\fP. -.SH "SEE ALSO" -.BR curl_multi_add_handle (3), -.BR curl_multi_cleanup (3), -.BR curl_multi_fdset (3), -.BR curl_multi_info_read (3), -.BR curl_multi_init (3), -.BR curl_multi_wait (3), -.BR libcurl-errors (3) diff --git a/docs/libcurl/curl_multi_perform.md b/docs/libcurl/curl_multi_perform.md new file mode 100644 index 00000000000..ecad22edf95 --- /dev/null +++ b/docs/libcurl/curl_multi_perform.md @@ -0,0 +1,107 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_perform +Section: 3 +Source: libcurl +See-also: + - curl_multi_add_handle (3) + - curl_multi_cleanup (3) + - curl_multi_fdset (3) + - curl_multi_info_read (3) + - curl_multi_init (3) + - curl_multi_wait (3) + - libcurl-errors (3) +--- + +# NAME + +curl_multi_perform - reads/writes available data from easy handles + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles); +~~~ + +# DESCRIPTION + +This function performs transfers on all the added handles that need attention +in a non-blocking fashion. The easy handles have previously been added to the +multi handle with curl_multi_add_handle(3). + +When an application has found out there is data available for the multi_handle +or a timeout has elapsed, the application should call this function to +read/write whatever there is to read or write right now etc. +curl_multi_perform(3) returns as soon as the reads/writes are done. This +function does not require that there actually is any data available for +reading or that data can be written, it can be called just in case. It stores +the number of handles that still transfer data in the second argument's +integer-pointer. + +If the amount of *running_handles* is changed from the previous call (or +is less than the amount of easy handles you have added to the multi handle), +you know that there is one or more transfers less "running". You can then call +curl_multi_info_read(3) to get information about each individual +completed transfer, and that returned info includes CURLcode and more. If an +added handle fails quickly, it may never be counted as a running_handle. You +could use curl_multi_info_read(3) to track actual status of the added +handles in that case. + +When *running_handles* is set to zero (0) on the return of this function, +there is no longer any transfers in progress. + +When this function returns error, the state of all transfers are uncertain and +they cannot be continued. curl_multi_perform(3) should not be called +again on the same multi handle after an error has been returned, unless first +removing all the handles and adding new ones. + +# EXAMPLE + +~~~c +int main(void) +{ + int still_running; + CURL *multi = curl_multi_init(); + CURL *curl = curl_easy_init(); + if(curl) { + curl_multi_add_handle(multi, curl); + do { + CURLMcode mc = curl_multi_perform(multi, &still_running); + + if(!mc && still_running) + /* wait for activity, timeout or "nothing" */ + mc = curl_multi_poll(multi, NULL, 0, 1000, NULL); + + if(mc) { + fprintf(stderr, "curl_multi_poll() failed, code %d.\n", (int)mc); + break; + } + + /* if there are still transfers, loop! */ + } while(still_running); + } +} +~~~ + +# AVAILABILITY + +Added in 7.9.6 + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. + +This function returns errors regarding the whole multi stack. Problems on +individual transfers may have occurred even when this function returns +*CURLM_OK*. Use curl_multi_info_read(3) to figure out how individual +transfers did. + +# TYPICAL USAGE + +Most applications use curl_multi_poll(3) to make libcurl wait for +activity on any of the ongoing transfers. As soon as one or more file +descriptor has activity or the function times out, the application calls +curl_multi_perform(3). diff --git a/docs/libcurl/curl_multi_poll.3 b/docs/libcurl/curl_multi_poll.md similarity index 50% rename from docs/libcurl/curl_multi_poll.3 rename to docs/libcurl/curl_multi_poll.md index dfc5bbd55f7..b239f2836dc 100644 --- a/docs/libcurl/curl_multi_poll.3 +++ b/docs/libcurl/curl_multi_poll.md @@ -1,31 +1,23 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_multi_poll 3 "29 Jul 2019" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_poll +Section: 3 +Source: libcurl +See-also: + - curl_multi_fdset (3) + - curl_multi_perform (3) + - curl_multi_wait (3) + - curl_multi_wakeup (3) +--- + +# NAME + curl_multi_poll - polls on all easy handles in a multi handle -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLMcode curl_multi_poll(CURLM *multi_handle, @@ -33,56 +25,68 @@ CURLMcode curl_multi_poll(CURLM *multi_handle, unsigned int extra_nfds, int timeout_ms, int *numfds); -.fi -.SH DESCRIPTION -\fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy +~~~ + +# DESCRIPTION + +curl_multi_poll(3) polls all file descriptors used by the curl easy handles contained in the given multi handle set. It blocks until activity is -detected on at least one of the handles or \fItimeout_ms\fP has passed. +detected on at least one of the handles or *timeout_ms* has passed. Alternatively, if the multi handle has a pending internal timeout that has a -shorter expiry time than \fItimeout_ms\fP, that shorter time is used instead +shorter expiry time than *timeout_ms*, that shorter time is used instead to make sure timeout accuracy is reasonably kept. The calling application may pass additional curl_waitfd structures which are -similar to \fIpoll(2)\fP's \fIpollfd\fP structure to be waited on in the same +similar to *poll(2)*'s *pollfd* structure to be waited on in the same call. -On completion, if \fInumfds\fP is non-NULL, it gets populated with the total +On completion, if *numfds* is non-NULL, it gets populated with the total number of file descriptors on which interesting events occurred. This number can include both libcurl internal descriptors as well as descriptors provided -in \fIextra_fds\fP. +in *extra_fds*. -The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to +The curl_multi_wakeup(3) function can be used from another thread to wake up this function and return faster. This is one of the details -that makes this function different than \fIcurl_multi_wait(3)\fP which cannot +that makes this function different than curl_multi_wait(3) which cannot be woken up this way. If no extra file descriptors are provided and libcurl has no file descriptor -to offer to wait for, this function instead waits during \fItimeout_ms\fP +to offer to wait for, this function instead waits during *timeout_ms* milliseconds (or shorter if an internal timer indicates so). This is the other -detail that makes this function different than \fIcurl_multi_wait(3)\fP. +detail that makes this function different than curl_multi_wait(3). This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem with 1024 maximum file descriptors. -.SH curl_waitfd -.nf + +# curl_waitfd + +~~~c struct curl_waitfd { curl_socket_t fd; short events; short revents; }; -.fi -.IP CURL_WAIT_POLLIN +~~~ + +## CURL_WAIT_POLLIN + Bit flag to curl_waitfd.events indicating the socket should poll on read events such as new data received. -.IP CURL_WAIT_POLLPRI + +## CURL_WAIT_POLLPRI + Bit flag to curl_waitfd.events indicating the socket should poll on high priority read events such as out of band data. -.IP CURL_WAIT_POLLOUT + +## CURL_WAIT_POLLOUT + Bit flag to curl_waitfd.events indicating the socket should poll on write events such as the socket being clear to write without blocking. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *easy_handle; @@ -104,7 +108,7 @@ int main(void) } if(mc != CURLM_OK) { - fprintf(stderr, "curl_multi failed, code %d.\\n", mc); + fprintf(stderr, "curl_multi failed, code %d.\n", mc); break; } @@ -112,14 +116,13 @@ int main(void) curl_multi_remove_handle(multi_handle, easy_handle); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.66.0. -.SH RETURN VALUE + +# RETURN VALUE + CURLMcode type, general libcurl multi interface error code. See -\fIlibcurl-errors(3)\fP -.SH "SEE ALSO" -.BR curl_multi_fdset (3), -.BR curl_multi_perform (3), -.BR curl_multi_wait (3), -.BR curl_multi_wakeup (3) +libcurl-errors(3) diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 deleted file mode 100644 index eb2aaf399b1..00000000000 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_remove_handle 3 "6 March 2002" "libcurl" "libcurl" -.SH NAME -curl_multi_remove_handle - remove an easy handle from a multi session -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle); -.fi -.SH DESCRIPTION -Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This makes the -specified easy handle be removed from this multi handle's control. - -When the easy handle has been removed from a multi stack, it is again -perfectly legal to invoke \fIcurl_easy_perform(3)\fP on this easy handle. - -Removing an easy handle while being in use is perfectly legal and effectively -halts the transfer in progress involving that easy handle. All other easy -handles and transfers remain unaffected. - -It is fine to remove a handle at any time during a transfer, just not from -within any libcurl callback function. - -Removing an easy handle from the multi handle before the corresponding -transfer is complete might cause libcurl to close the connection - if the -state of it and the internal protocol handler deem it necessary. Otherwise -libcurl keeps the connection alive in the connection pool associated with the -multi handle, ready to get reused for a future transfer using this multi -handle. -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *multi = curl_multi_init(); - int queued = 0; - - /* when an easy handle has completed, remove it */ - CURLMsg *msg = curl_multi_info_read(multi, &queued); - if(msg) { - if(msg->msg == CURLMSG_DONE) { - /* a transfer ended */ - fprintf(stderr, "Transfer completed\\n"); - curl_multi_remove_handle(multi, msg->easy_handle); - } - } -} -.fi -.SH AVAILABILITY -Added in 7.9.6 -.SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. -.SH "SEE ALSO" -.BR curl_multi_add_handle (3), -.BR curl_multi_cleanup (3), -.BR curl_multi_init (3) diff --git a/docs/libcurl/curl_multi_remove_handle.md b/docs/libcurl/curl_multi_remove_handle.md new file mode 100644 index 00000000000..bb8ee1c7d30 --- /dev/null +++ b/docs/libcurl/curl_multi_remove_handle.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_remove_handle +Section: 3 +Source: libcurl +See-also: + - curl_multi_add_handle (3) + - curl_multi_cleanup (3) + - curl_multi_init (3) +--- + +# NAME + +curl_multi_remove_handle - remove an easy handle from a multi session + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle); +~~~ + +# DESCRIPTION + +Removes a given *easy_handle* from the *multi_handle*. This makes the +specified easy handle be removed from this multi handle's control. + +When the easy handle has been removed from a multi stack, it is again +perfectly legal to invoke curl_easy_perform(3) on this easy handle. + +Removing an easy handle while being in use is perfectly legal and effectively +halts the transfer in progress involving that easy handle. All other easy +handles and transfers remain unaffected. + +It is fine to remove a handle at any time during a transfer, just not from +within any libcurl callback function. + +Removing an easy handle from the multi handle before the corresponding +transfer is complete might cause libcurl to close the connection - if the +state of it and the internal protocol handler deem it necessary. Otherwise +libcurl keeps the connection alive in the connection pool associated with the +multi handle, ready to get reused for a future transfer using this multi +handle. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *multi = curl_multi_init(); + int queued = 0; + + /* when an easy handle has completed, remove it */ + CURLMsg *msg = curl_multi_info_read(multi, &queued); + if(msg) { + if(msg->msg == CURLMSG_DONE) { + /* a transfer ended */ + fprintf(stderr, "Transfer completed\n"); + curl_multi_remove_handle(multi, msg->easy_handle); + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.9.6 + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 deleted file mode 100644 index 1752fe4fdbb..00000000000 --- a/docs/libcurl/curl_multi_setopt.3 +++ /dev/null @@ -1,98 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_setopt 3 "4 Nov 2014" "libcurl" "libcurl" -.SH NAME -curl_multi_setopt \- set options for a curl multi handle -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *multi_handle, CURLMoption option, parameter); -.fi -.SH DESCRIPTION -\fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to -behave. By using the appropriate options to \fIcurl_multi_setopt(3)\fP, you -can change libcurl's behavior when using that multi handle. All options are -set with the \fIoption\fP followed by the \fIparameter\fP. That parameter can -be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a -\fBcurl_off_t\fP type, depending on what the specific option expects. Read -this manual carefully as bad input values may cause libcurl to behave -badly. You can only set one option in each function call. - -.SH OPTIONS -.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE -See \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP -.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE -See \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP -.IP CURLMOPT_MAX_HOST_CONNECTIONS -See \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP -.IP CURLMOPT_MAX_PIPELINE_LENGTH -See \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP -.IP CURLMOPT_MAX_TOTAL_CONNECTIONS -See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP -.IP CURLMOPT_MAXCONNECTS -See \fICURLMOPT_MAXCONNECTS(3)\fP -.IP CURLMOPT_PIPELINING -See \fICURLMOPT_PIPELINING(3)\fP -.IP CURLMOPT_PIPELINING_SITE_BL -See \fICURLMOPT_PIPELINING_SITE_BL(3)\fP -.IP CURLMOPT_PIPELINING_SERVER_BL -See \fICURLMOPT_PIPELINING_SERVER_BL(3)\fP -.IP CURLMOPT_PUSHFUNCTION -See \fICURLMOPT_PUSHFUNCTION(3)\fP -.IP CURLMOPT_PUSHDATA -See \fICURLMOPT_PUSHDATA(3)\fP -.IP CURLMOPT_SOCKETFUNCTION -See \fICURLMOPT_SOCKETFUNCTION(3)\fP -.IP CURLMOPT_SOCKETDATA -See \fICURLMOPT_SOCKETDATA(3)\fP -.IP CURLMOPT_TIMERFUNCTION -See \fICURLMOPT_TIMERFUNCTION(3)\fP -.IP CURLMOPT_TIMERDATA -See \fICURLMOPT_TIMERDATA(3)\fP -.IP CURLMOPT_MAX_CONCURRENT_STREAMS -See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP -.SH EXAMPLE -.nf - -#define MAX_PARALLEL 45 - -int main(void) -{ - CURLM *multi; - /* Limit the amount of simultaneous connections curl should allow: */ - curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL); -} -.fi -.SH AVAILABILITY -Added in 7.15.4 -.SH RETURN VALUE -The standard CURLMcode for multi interface error codes. Note that it returns a -CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl -does not know of. -.SH "SEE ALSO" -.BR curl_multi_cleanup (3), -.BR curl_multi_info_read (3), -.BR curl_multi_init (3), -.BR curl_multi_socket (3) diff --git a/docs/libcurl/curl_multi_setopt.md b/docs/libcurl/curl_multi_setopt.md new file mode 100644 index 00000000000..c0c8a3e6eeb --- /dev/null +++ b/docs/libcurl/curl_multi_setopt.md @@ -0,0 +1,125 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_setopt +Section: 3 +Source: libcurl +See-also: + - curl_multi_cleanup (3) + - curl_multi_info_read (3) + - curl_multi_init (3) + - curl_multi_socket (3) +--- + +# NAME + +curl_multi_setopt - set options for a curl multi handle + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *multi_handle, CURLMoption option, parameter); +~~~ + +# DESCRIPTION + +curl_multi_setopt(3) is used to tell a libcurl multi handle how to +behave. By using the appropriate options to curl_multi_setopt(3), you +can change libcurl's behavior when using that multi handle. All options are +set with the *option* followed by the *parameter*. That parameter can +be a **long**, a **function pointer**, an **object pointer** or a +**curl_off_t** type, depending on what the specific option expects. Read +this manual carefully as bad input values may cause libcurl to behave +badly. You can only set one option in each function call. + +# OPTIONS + +## CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE + +See CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3) + +## CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE + +See CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3) + +## CURLMOPT_MAX_HOST_CONNECTIONS + +See CURLMOPT_MAX_HOST_CONNECTIONS(3) + +## CURLMOPT_MAX_PIPELINE_LENGTH + +See CURLMOPT_MAX_PIPELINE_LENGTH(3) + +## CURLMOPT_MAX_TOTAL_CONNECTIONS + +See CURLMOPT_MAX_TOTAL_CONNECTIONS(3) + +## CURLMOPT_MAXCONNECTS + +See CURLMOPT_MAXCONNECTS(3) + +## CURLMOPT_PIPELINING + +See CURLMOPT_PIPELINING(3) + +## CURLMOPT_PIPELINING_SITE_BL + +See CURLMOPT_PIPELINING_SITE_BL(3) + +## CURLMOPT_PIPELINING_SERVER_BL + +See CURLMOPT_PIPELINING_SERVER_BL(3) + +## CURLMOPT_PUSHFUNCTION + +See CURLMOPT_PUSHFUNCTION(3) + +## CURLMOPT_PUSHDATA + +See CURLMOPT_PUSHDATA(3) + +## CURLMOPT_SOCKETFUNCTION + +See CURLMOPT_SOCKETFUNCTION(3) + +## CURLMOPT_SOCKETDATA + +See CURLMOPT_SOCKETDATA(3) + +## CURLMOPT_TIMERFUNCTION + +See CURLMOPT_TIMERFUNCTION(3) + +## CURLMOPT_TIMERDATA + +See CURLMOPT_TIMERDATA(3) + +## CURLMOPT_MAX_CONCURRENT_STREAMS + +See CURLMOPT_MAX_CONCURRENT_STREAMS(3) + +# EXAMPLE + +~~~c + +#define MAX_PARALLEL 45 + +int main(void) +{ + CURLM *multi; + /* Limit the amount of simultaneous connections curl should allow: */ + curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL); +} +~~~ + +# AVAILABILITY + +Added in 7.15.4 + +# RETURN VALUE + +The standard CURLMcode for multi interface error codes. Note that it returns a +CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl +does not know of. diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 deleted file mode 100644 index e4759eb2d0d..00000000000 --- a/docs/libcurl/curl_multi_socket.3 +++ /dev/null @@ -1,100 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_socket 3 "9 Jul 2006" "libcurl" "libcurl" -.SH NAME -curl_multi_socket \- reads/writes available data -.SH SYNOPSIS -.nf -#include -CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd, - int *running_handles); - -CURLMcode curl_multi_socket_all(CURLM *multi_handle, - int *running_handles); -.fi -.SH DESCRIPTION -These functions are deprecated. Do not use. See -\fIcurl_multi_socket_action(3)\fP instead. - -At return, the integer \fBrunning_handles\fP points to contains the number of -still running easy handles within the multi handle. When this number reaches -zero, all transfers are complete/done. Note that when you call -\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter -decreases by one, it DOES NOT necessarily mean that this exact socket/transfer -is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out -which easy handle that completed. - -The \fIcurl_multi_socket_action(3)\fP functions inform the application about -updates in the socket (file descriptor) status by doing none, one, or multiple -calls to the socket callback function set with the -\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They -update the status with changes since the previous time the callback was -called. - -Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option -with \fIcurl_multi_setopt(3)\fP. Your application then gets called with -information on how long to wait for socket actions at most before doing the -timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the -\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the -\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but -for an event-based system using the callback is far better than relying on -polling the timeout value. - -Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is -equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to -0. - -Force libcurl to (re-)check all its internal sockets and transfers instead of -just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there -should not be any reason to use this function. -.SH EXAMPLE -.nf -int main(void) -{ - /* the event-library gets told when there activity on the socket 'fd', - which we translate to a call to curl_multi_socket_action() */ - int running; - int rc; - int fd; - CURLM *multi; - rc = curl_multi_socket(multi, fd, &running); -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.15.4, and is deemed stable since -7.16.0. - -\fIcurl_multi_socket(3)\fP is deprecated, use -\fIcurl_multi_socket_action(3)\fP instead! -.SH "RETURN VALUE" -CURLMcode type, general libcurl multi interface error code. - -The return code is for the whole multi stack. Problems still might have -occurred on individual transfers even when one of these functions return OK. -.SH "SEE ALSO" -.BR curl_multi_cleanup (3), -.BR curl_multi_init (3), -.BR curl_multi_fdset (3), -.BR curl_multi_info_read (3), -.BR the hiperfifo.c example diff --git a/docs/libcurl/curl_multi_socket.md b/docs/libcurl/curl_multi_socket.md new file mode 100644 index 00000000000..ff465c359c7 --- /dev/null +++ b/docs/libcurl/curl_multi_socket.md @@ -0,0 +1,95 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_socket +Section: 3 +Source: libcurl +See-also: + - curl_multi_cleanup (3) + - curl_multi_fdset (3) + - curl_multi_info_read (3) + - curl_multi_init (3) + - the hiperfifo.c example +--- + +# NAME + +curl_multi_socket - reads/writes available data + +# SYNOPSIS + +~~~c +#include +CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd, + int *running_handles); + +CURLMcode curl_multi_socket_all(CURLM *multi_handle, + int *running_handles); +~~~ + +# DESCRIPTION + +These functions are deprecated. Do not use. See +curl_multi_socket_action(3) instead. + +At return, the integer **running_handles** points to contains the number of +still running easy handles within the multi handle. When this number reaches +zero, all transfers are complete/done. Note that when you call +curl_multi_socket_action(3) on a specific socket and the counter +decreases by one, it DOES NOT necessarily mean that this exact socket/transfer +is the one that completed. Use curl_multi_info_read(3) to figure out +which easy handle that completed. + +The curl_multi_socket_action(3) functions inform the application about +updates in the socket (file descriptor) status by doing none, one, or multiple +calls to the socket callback function set with the +CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They +update the status with changes since the previous time the callback was +called. + +Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option +with curl_multi_setopt(3). Your application then gets called with +information on how long to wait for socket actions at most before doing the +timeout action: call the curl_multi_socket_action(3) function with the +**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the +curl_multi_timeout(3) function to poll the value at any given time, but +for an event-based system using the callback is far better than relying on +polling the timeout value. + +Usage of curl_multi_socket(3) is deprecated, whereas the function is +equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to +0. + +Force libcurl to (re-)check all its internal sockets and transfers instead of +just a single one by calling curl_multi_socket_all(3). Note that there +should not be any reason to use this function. + +# EXAMPLE + +~~~c +int main(void) +{ + /* the event-library gets told when there activity on the socket 'fd', + which we translate to a call to curl_multi_socket_action() */ + int running; + int rc; + int fd; + CURLM *multi; + rc = curl_multi_socket(multi, fd, &running); +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.15.4, and is deemed stable since +7.16.0. + +curl_multi_socket(3) is deprecated, use +curl_multi_socket_action(3) instead! + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. + +The return code is for the whole multi stack. Problems still might have +occurred on individual transfers even when one of these functions return OK. diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 deleted file mode 100644 index 445ac2c8d6a..00000000000 --- a/docs/libcurl/curl_multi_socket_action.3 +++ /dev/null @@ -1,123 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_socket_action 3 "9 Jul 2006" "libcurl" "libcurl" -.SH NAME -curl_multi_socket_action \- reads/writes available data given an action -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_socket_action(CURLM *multi_handle, - curl_socket_t sockfd, - int ev_bitmask, - int *running_handles); -.fi -.SH DESCRIPTION -When the application has detected action on a socket handled by libcurl, it -should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument -set to the socket with the action. When the events on a socket are known, they -can be passed as an events bitmask \fBev_bitmask\fP by first setting -\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of -events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or -CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and -libcurl tests the descriptor internally. It is also permissible to pass -CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the -whole process or when a timeout occurs. - -At return, \fBrunning_handles\fP points to the number of running easy handles -within the multi handle. When this number reaches zero, all transfers are -complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific -socket and the counter decreases by one, it DOES NOT necessarily mean that -this exact socket/transfer is the one that completed. Use -\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed. - -The \fIcurl_multi_socket_action(3)\fP function informs the application about -updates in the socket (file descriptor) status by doing none, one, or multiple -calls to the socket callback function set with the -\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They -update the status with changes since the previous time the callback was -called. - -Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option -with \fIcurl_multi_setopt(3)\fP. Your application then gets called with -information on how long to wait for socket actions at most before doing the -timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the -\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the -\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but -for an event-based system using the callback is far better than relying on -polling the timeout value. - -When this function returns error, the state of all transfers are uncertain and -they cannot be continued. \fIcurl_multi_socket_action(3)\fP should not be -called again on the same multi handle after an error has been returned, unless -first removing all the handles and adding new ones. -.SH "TYPICAL USAGE" -1. Create a multi handle - -2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP - -3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to -know what timeout value to use when waiting for socket activities. - -4. Add easy handles with curl_multi_add_handle() - -5. Provide some means to manage the sockets libcurl is using, so you can check -them for activity. This can be done through your application code, or by way -of an external library such as libevent or glib. - -6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...) -to kickstart everything. To get one or more callbacks called. - -7. Wait for activity on any of libcurl's sockets, use the timeout value your -callback has been told. - -8, When activity is detected, call curl_multi_socket_action() for the -socket(s) that got action. If no activity is detected and the timeout expires, -call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP. -.SH EXAMPLE -.nf -int main(void) -{ - /* the event-library gets told when there activity on the socket 'fd', - which we translate to a call to curl_multi_socket_action() */ - int running; - CURLM *multi; /* the stack we work with */ - int fd; /* the descriptor that had action */ - int bitmask; /* what activity that happened */ - CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running); - if(mc) - printf("error: %s\\n", curl_multi_strerror(mc)); -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0. -.SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. See -\fIlibcurl-errors(3)\fP -.SH "SEE ALSO" -.BR curl_multi_cleanup (3), -.BR curl_multi_fdset (3), -.BR curl_multi_info_read (3), -.BR curl_multi_init (3), -.BR the hiperfifo.c example diff --git a/docs/libcurl/curl_multi_socket_action.md b/docs/libcurl/curl_multi_socket_action.md new file mode 100644 index 00000000000..8af17c83fb2 --- /dev/null +++ b/docs/libcurl/curl_multi_socket_action.md @@ -0,0 +1,120 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_socket_action +Section: 3 +Source: libcurl +See-also: + - curl_multi_cleanup (3) + - curl_multi_fdset (3) + - curl_multi_info_read (3) + - curl_multi_init (3) + - the hiperfifo.c example +--- + +# NAME + +curl_multi_socket_action - reads/writes available data given an action + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_socket_action(CURLM *multi_handle, + curl_socket_t sockfd, + int ev_bitmask, + int *running_handles); +~~~ + +# DESCRIPTION + +When the application has detected action on a socket handled by libcurl, it +should call curl_multi_socket_action(3) with the **sockfd** argument +set to the socket with the action. When the events on a socket are known, they +can be passed as an events bitmask **ev_bitmask** by first setting +**ev_bitmask** to 0, and then adding using bitwise OR (|) any combination of +events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or +CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and +libcurl tests the descriptor internally. It is also permissible to pass +CURL_SOCKET_TIMEOUT to the **sockfd** parameter in order to initiate the +whole process or when a timeout occurs. + +At return, **running_handles** points to the number of running easy handles +within the multi handle. When this number reaches zero, all transfers are +complete/done. When you call curl_multi_socket_action(3) on a specific +socket and the counter decreases by one, it DOES NOT necessarily mean that +this exact socket/transfer is the one that completed. Use +curl_multi_info_read(3) to figure out which easy handle that completed. + +The curl_multi_socket_action(3) function informs the application about +updates in the socket (file descriptor) status by doing none, one, or multiple +calls to the socket callback function set with the +CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They +update the status with changes since the previous time the callback was +called. + +Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option +with curl_multi_setopt(3). Your application then gets called with +information on how long to wait for socket actions at most before doing the +timeout action: call the curl_multi_socket_action(3) function with the +**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the +curl_multi_timeout(3) function to poll the value at any given time, but +for an event-based system using the callback is far better than relying on +polling the timeout value. + +When this function returns error, the state of all transfers are uncertain and +they cannot be continued. curl_multi_socket_action(3) should not be +called again on the same multi handle after an error has been returned, unless +first removing all the handles and adding new ones. + +# TYPICAL USAGE + +1. Create a multi handle + +2. Set the socket callback with CURLMOPT_SOCKETFUNCTION(3) + +3. Set the timeout callback with CURLMOPT_TIMERFUNCTION(3), to get to +know what timeout value to use when waiting for socket activities. + +4. Add easy handles with curl_multi_add_handle() + +5. Provide some means to manage the sockets libcurl is using, so you can check +them for activity. This can be done through your application code, or by way +of an external library such as libevent or glib. + +6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...) +to kickstart everything. To get one or more callbacks called. + +7. Wait for activity on any of libcurl's sockets, use the timeout value your +callback has been told. + +8, When activity is detected, call curl_multi_socket_action() for the +socket(s) that got action. If no activity is detected and the timeout expires, +call curl_multi_socket_action(3) with *CURL_SOCKET_TIMEOUT*. + +# EXAMPLE + +~~~c +int main(void) +{ + /* the event-library gets told when there activity on the socket 'fd', + which we translate to a call to curl_multi_socket_action() */ + int running; + CURLM *multi; /* the stack we work with */ + int fd; /* the descriptor that had action */ + int bitmask; /* what activity that happened */ + CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running); + if(mc) + printf("error: %s\n", curl_multi_strerror(mc)); +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0. + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. See +libcurl-errors(3) diff --git a/docs/libcurl/curl_multi_socket_all.3 b/docs/libcurl/curl_multi_socket_all.3 deleted file mode 100644 index 428dd06f962..00000000000 --- a/docs/libcurl/curl_multi_socket_all.3 +++ /dev/null @@ -1 +0,0 @@ -.so man3/curl_multi_socket.3 diff --git a/docs/libcurl/curl_multi_socket_all.md b/docs/libcurl/curl_multi_socket_all.md new file mode 100644 index 00000000000..ff465c359c7 --- /dev/null +++ b/docs/libcurl/curl_multi_socket_all.md @@ -0,0 +1,95 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_socket +Section: 3 +Source: libcurl +See-also: + - curl_multi_cleanup (3) + - curl_multi_fdset (3) + - curl_multi_info_read (3) + - curl_multi_init (3) + - the hiperfifo.c example +--- + +# NAME + +curl_multi_socket - reads/writes available data + +# SYNOPSIS + +~~~c +#include +CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd, + int *running_handles); + +CURLMcode curl_multi_socket_all(CURLM *multi_handle, + int *running_handles); +~~~ + +# DESCRIPTION + +These functions are deprecated. Do not use. See +curl_multi_socket_action(3) instead. + +At return, the integer **running_handles** points to contains the number of +still running easy handles within the multi handle. When this number reaches +zero, all transfers are complete/done. Note that when you call +curl_multi_socket_action(3) on a specific socket and the counter +decreases by one, it DOES NOT necessarily mean that this exact socket/transfer +is the one that completed. Use curl_multi_info_read(3) to figure out +which easy handle that completed. + +The curl_multi_socket_action(3) functions inform the application about +updates in the socket (file descriptor) status by doing none, one, or multiple +calls to the socket callback function set with the +CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They +update the status with changes since the previous time the callback was +called. + +Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option +with curl_multi_setopt(3). Your application then gets called with +information on how long to wait for socket actions at most before doing the +timeout action: call the curl_multi_socket_action(3) function with the +**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the +curl_multi_timeout(3) function to poll the value at any given time, but +for an event-based system using the callback is far better than relying on +polling the timeout value. + +Usage of curl_multi_socket(3) is deprecated, whereas the function is +equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to +0. + +Force libcurl to (re-)check all its internal sockets and transfers instead of +just a single one by calling curl_multi_socket_all(3). Note that there +should not be any reason to use this function. + +# EXAMPLE + +~~~c +int main(void) +{ + /* the event-library gets told when there activity on the socket 'fd', + which we translate to a call to curl_multi_socket_action() */ + int running; + int rc; + int fd; + CURLM *multi; + rc = curl_multi_socket(multi, fd, &running); +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.15.4, and is deemed stable since +7.16.0. + +curl_multi_socket(3) is deprecated, use +curl_multi_socket_action(3) instead! + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. + +The return code is for the whole multi stack. Problems still might have +occurred on individual transfers even when one of these functions return OK. diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 deleted file mode 100644 index 5987679103f..00000000000 --- a/docs/libcurl/curl_multi_strerror.3 +++ /dev/null @@ -1,56 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_strerror 3 "26 Apr 2004" "libcurl" "libcurl" -.SH NAME -curl_multi_strerror - return string describing error code -.SH SYNOPSIS -.nf -#include - -const char *curl_multi_strerror(CURLMcode errornum); -.fi -.SH DESCRIPTION -This function returns a string describing the \fICURLMcode\fP error code -passed in the argument \fIerrornum\fP. -.SH EXAMPLE -.nf -int main(void) -{ - int still_running; - CURLM *multi = curl_multi_init(); - - CURLMcode mc = curl_multi_perform(multi, &still_running); - if(mc) - printf("error: %s\\n", curl_multi_strerror(mc)); -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.12.0 -.SH RETURN VALUE -A pointer to a null-terminated string. -.SH "SEE ALSO" -.BR curl_easy_strerror (3), -.BR curl_share_strerror (3), -.BR curl_url_strerror (3), -.BR libcurl-errors (3) diff --git a/docs/libcurl/curl_multi_strerror.md b/docs/libcurl/curl_multi_strerror.md new file mode 100644 index 00000000000..5429e0e3487 --- /dev/null +++ b/docs/libcurl/curl_multi_strerror.md @@ -0,0 +1,51 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_strerror +Section: 3 +Source: libcurl +See-also: + - curl_easy_strerror (3) + - curl_share_strerror (3) + - curl_url_strerror (3) + - libcurl-errors (3) +--- + +# NAME + +curl_multi_strerror - return string describing error code + +# SYNOPSIS + +~~~c +#include + +const char *curl_multi_strerror(CURLMcode errornum); +~~~ + +# DESCRIPTION + +This function returns a string describing the *CURLMcode* error code +passed in the argument *errornum*. + +# EXAMPLE + +~~~c +int main(void) +{ + int still_running; + CURLM *multi = curl_multi_init(); + + CURLMcode mc = curl_multi_perform(multi, &still_running); + if(mc) + printf("error: %s\n", curl_multi_strerror(mc)); +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.12.0 + +# RETURN VALUE + +A pointer to a null-terminated string. diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 deleted file mode 100644 index 1951282eef4..00000000000 --- a/docs/libcurl/curl_multi_timeout.3 +++ /dev/null @@ -1,93 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_timeout 3 "2 Jan 2006" "libcurl" "libcurl" -.SH NAME -curl_multi_timeout \- how long to wait for action before proceeding -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout); -.fi -.SH DESCRIPTION - -An application using the libcurl multi interface should call -\fIcurl_multi_timeout(3)\fP to figure out how long it should wait for socket -actions \- at most \- before proceeding. - -Proceeding means either doing the socket-style timeout action: call the -\fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set -to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you are using -the simpler and older multi interface approach. - -The timeout value returned in the long \fBtimeout\fP points to, is in number -of milliseconds at this moment. If 0, it means you should proceed immediately -without waiting for anything. If it returns -1, there is no timeout at all set. - -An application that uses the multi_socket API SHOULD NOT use this function, -but SHOULD instead use the \fICURLMOPT_TIMERFUNCTION(3)\fP option for proper -and desired behavior. - -Note: if libcurl returns a -1 timeout here, it just means that libcurl -currently has no stored timeout value. You must not wait too long (more than a -few seconds perhaps) before you call \fIcurl_multi_perform(3)\fP again. -.SH EXAMPLE -.nf -int main(void) -{ - struct timeval timeout; - long timeo; - fd_set fdread; - fd_set fdwrite; - fd_set fdexcep; - int maxfd; - CURLM *multi = curl_multi_init(); - - curl_multi_timeout(multi, &timeo); - if(timeo < 0) - /* no set timeout, use a default */ - timeo = 980; - - timeout.tv_sec = timeo / 1000; - timeout.tv_usec = (timeo % 1000) * 1000; - - /* wait for activities no longer than the set timeout */ - select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); -} -.fi -.SH TYPICAL USAGE -Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. Figure -out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP. - -When there is activity or timeout, call \fIcurl_multi_perform(3)\fP and then -loop - until all transfers are complete. -.SH AVAILABILITY -This function was added in libcurl 7.15.4. -.SH RETURN VALUE -The standard CURLMcode for multi interface error codes. -.SH "SEE ALSO" -.BR curl_multi_fdset (3), -.BR curl_multi_info_read (3), -.BR curl_multi_setopt (3), -.BR curl_multi_socket (3) diff --git a/docs/libcurl/curl_multi_timeout.md b/docs/libcurl/curl_multi_timeout.md new file mode 100644 index 00000000000..83bad38455e --- /dev/null +++ b/docs/libcurl/curl_multi_timeout.md @@ -0,0 +1,89 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_timeout +Section: 3 +Source: libcurl +See-also: + - curl_multi_fdset (3) + - curl_multi_info_read (3) + - curl_multi_setopt (3) + - curl_multi_socket (3) +--- + +# NAME + +curl_multi_timeout - how long to wait for action before proceeding + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout); +~~~ + +# DESCRIPTION + +An application using the libcurl multi interface should call +curl_multi_timeout(3) to figure out how long it should wait for socket +actions - at most - before proceeding. + +Proceeding means either doing the socket-style timeout action: call the +curl_multi_socket_action(3) function with the **sockfd** argument set +to CURL_SOCKET_TIMEOUT, or call curl_multi_perform(3) if you are using +the simpler and older multi interface approach. + +The timeout value returned in the long **timeout** points to, is in number +of milliseconds at this moment. If 0, it means you should proceed immediately +without waiting for anything. If it returns -1, there is no timeout at all set. + +An application that uses the *multi_socket* API should not use this function. +It should instead use the CURLMOPT_TIMERFUNCTION(3) option for proper and +desired behavior. + +Note: if libcurl returns a -1 timeout here, it just means that libcurl +currently has no stored timeout value. You must not wait too long (more than a +few seconds perhaps) before you call curl_multi_perform(3) again. + +# EXAMPLE + +~~~c +int main(void) +{ + struct timeval timeout; + long timeo; + fd_set fdread; + fd_set fdwrite; + fd_set fdexcep; + int maxfd; + CURLM *multi = curl_multi_init(); + + curl_multi_timeout(multi, &timeo); + if(timeo < 0) + /* no set timeout, use a default */ + timeo = 980; + + timeout.tv_sec = timeo / 1000; + timeout.tv_usec = (timeo % 1000) * 1000; + + /* wait for activities no longer than the set timeout */ + select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); +} +~~~ + +# TYPICAL USAGE + +Call curl_multi_timeout(3), then wait for action on the sockets. Figure +out which sockets to wait for by calling curl_multi_fdset(3). + +When there is activity or timeout, call curl_multi_perform(3) and then +loop - until all transfers are complete. + +# AVAILABILITY + +This function was added in libcurl 7.15.4. + +# RETURN VALUE + +The standard CURLMcode for multi interface error codes. diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 deleted file mode 100644 index 1f73dc3541f..00000000000 --- a/docs/libcurl/curl_multi_wait.3 +++ /dev/null @@ -1,118 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_wait 3 "12 Jul 2012" "libcurl" "libcurl" -.SH NAME -curl_multi_wait - polls on all easy handles in a multi handle -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_wait(CURLM *multi_handle, - struct curl_waitfd extra_fds[], - unsigned int extra_nfds, - int timeout_ms, - int *numfds); -.fi -.SH DESCRIPTION -\fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy -handles contained in the given multi handle set. It blocks until activity is -detected on at least one of the handles or \fItimeout_ms\fP has passed. -Alternatively, if the multi handle has a pending internal timeout that has a -shorter expiry time than \fItimeout_ms\fP, that shorter time is be used -instead to make sure timeout accuracy is reasonably kept. - -The calling application may pass additional \fIcurl_waitfd\fP structures which -are similar to \fIpoll(2)\fP's \fIpollfd\fP structure to be waited on in the -same call. - -On completion, if \fInumfds\fP is non-NULL, it gets populated with the total -number of file descriptors on which interesting events occurred. This number -can include both libcurl internal descriptors as well as descriptors provided -in \fIextra_fds\fP. - -If no extra file descriptors are provided and libcurl has no file descriptor -to offer to wait for, this function returns immediately. (Consider using -\fIcurl_multi_poll(3)\fP to avoid this behavior.) - -This function is encouraged to be used instead of select(3) when using the -multi interface to allow applications to easier circumvent the common problem -with 1024 maximum file descriptors. -.SH curl_waitfd -.nf -struct curl_waitfd { - curl_socket_t fd; - short events; - short revents; -}; -.fi -.IP CURL_WAIT_POLLIN -Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on read -events such as new data received. -.IP CURL_WAIT_POLLPRI -Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on high -priority read events such as out of band data. -.IP CURL_WAIT_POLLOUT -Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on -write events such as the socket being clear to write without blocking. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *easy; - CURLM *multi = curl_multi_init(); - int still_running; - - /* add the individual easy handle */ - curl_multi_add_handle(multi, easy); - - do { - CURLMcode mc; - int numfds; - - mc = curl_multi_perform(multi, &still_running); - - if(mc == CURLM_OK) { - /* wait for activity, timeout or "nothing" */ - mc = curl_multi_wait(multi, NULL, 0, 1000, &numfds); - } - - if(mc != CURLM_OK) { - fprintf(stderr, "curl_multi failed, code %d.\\n", mc); - break; - } - - } while(still_running); - - curl_multi_remove_handle(multi, easy); -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.28.0. -.SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. See -\fIlibcurl-errors(3)\fP -.SH "SEE ALSO" -.BR curl_multi_fdset (3), -.BR curl_multi_perform (3), -.BR curl_multi_poll (3) diff --git a/docs/libcurl/curl_multi_wait.md b/docs/libcurl/curl_multi_wait.md new file mode 100644 index 00000000000..094ace386dd --- /dev/null +++ b/docs/libcurl/curl_multi_wait.md @@ -0,0 +1,121 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_wait +Section: 3 +Source: libcurl +See-also: + - curl_multi_fdset (3) + - curl_multi_perform (3) + - curl_multi_poll (3) +--- + +# NAME + +curl_multi_wait - polls on all easy handles in a multi handle + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_wait(CURLM *multi_handle, + struct curl_waitfd extra_fds[], + unsigned int extra_nfds, + int timeout_ms, + int *numfds); +~~~ + +# DESCRIPTION + +curl_multi_wait(3) polls all file descriptors used by the curl easy +handles contained in the given multi handle set. It blocks until activity is +detected on at least one of the handles or *timeout_ms* has passed. +Alternatively, if the multi handle has a pending internal timeout that has a +shorter expiry time than *timeout_ms*, that shorter time is be used +instead to make sure timeout accuracy is reasonably kept. + +The calling application may pass additional *curl_waitfd* structures which +are similar to *poll(2)*'s *pollfd* structure to be waited on in the +same call. + +On completion, if *numfds* is non-NULL, it gets populated with the total +number of file descriptors on which interesting events occurred. This number +can include both libcurl internal descriptors as well as descriptors provided +in *extra_fds*. + +If no extra file descriptors are provided and libcurl has no file descriptor +to offer to wait for, this function returns immediately. (Consider using +curl_multi_poll(3) to avoid this behavior.) + +This function is encouraged to be used instead of select(3) when using the +multi interface to allow applications to easier circumvent the common problem +with 1024 maximum file descriptors. + +# curl_waitfd + +~~~c +struct curl_waitfd { + curl_socket_t fd; + short events; + short revents; +}; +~~~ + +## CURL_WAIT_POLLIN + +Bit flag to *curl_waitfd.events* indicating the socket should poll on read +events such as new data received. + +## CURL_WAIT_POLLPRI + +Bit flag to *curl_waitfd.events* indicating the socket should poll on high +priority read events such as out of band data. + +## CURL_WAIT_POLLOUT + +Bit flag to *curl_waitfd.events* indicating the socket should poll on +write events such as the socket being clear to write without blocking. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *easy; + CURLM *multi = curl_multi_init(); + int still_running; + + /* add the individual easy handle */ + curl_multi_add_handle(multi, easy); + + do { + CURLMcode mc; + int numfds; + + mc = curl_multi_perform(multi, &still_running); + + if(mc == CURLM_OK) { + /* wait for activity, timeout or "nothing" */ + mc = curl_multi_wait(multi, NULL, 0, 1000, &numfds); + } + + if(mc != CURLM_OK) { + fprintf(stderr, "curl_multi failed, code %d.\n", mc); + break; + } + + } while(still_running); + + curl_multi_remove_handle(multi, easy); +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.28.0. + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. See +libcurl-errors(3) diff --git a/docs/libcurl/curl_multi_wakeup.3 b/docs/libcurl/curl_multi_wakeup.3 deleted file mode 100644 index 9809232794b..00000000000 --- a/docs/libcurl/curl_multi_wakeup.3 +++ /dev/null @@ -1,96 +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 -.\" * -.\" ************************************************************************** -.TH curl_multi_wakeup 3 "17 Nov 2019" "libcurl" "libcurl" -.SH NAME -curl_multi_wakeup - wakes up a sleeping curl_multi_poll call -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_wakeup(CURLM *multi_handle); -.fi -.SH DESCRIPTION -This function can be called from any thread and it wakes up a sleeping -\fIcurl_multi_poll(3)\fP call that is currently (or is about to be) waiting -for activity or a timeout. - -If the function is called when there is no \fIcurl_multi_poll(3)\fP call, it -causes the next call to return immediately. - -Calling this function only guarantees to wake up the current (or the next if -there is no current) \fIcurl_multi_poll(3)\fP call, which means it is possible -that multiple calls to this function wake up the same waiting operation. - -This function has no effect on \fIcurl_multi_wait(3)\fP calls. -.SH EXAMPLE -.nf -extern int time_to_die(void); -extern int set_something_to_signal_thread_1_to_exit(void); -extern int decide_to_stop_thread1(); - -int main(void) -{ - CURL *easy; - CURLM *multi; - int still_running; - - /* add the individual easy handle */ - curl_multi_add_handle(multi, easy); - - /* this is thread 1 */ - do { - CURLMcode mc; - int numfds; - - mc = curl_multi_perform(multi, &still_running); - - if(mc == CURLM_OK) { - /* wait for activity, timeout or wakeup */ - mc = curl_multi_poll(multi, NULL, 0, 10000, &numfds); - } - - if(time_to_die()) - return 1; - - } while(still_running); - - curl_multi_remove_handle(multi, easy); - - /* this is thread 2 */ - - if(decide_to_stop_thread1()) { - - set_something_to_signal_thread_1_to_exit(); - - curl_multi_wakeup(multi); - } -} -.fi -.SH AVAILABILITY -Added in 7.68.0 -.SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. -.SH "SEE ALSO" -.BR curl_multi_poll (3), -.BR curl_multi_wait (3) diff --git a/docs/libcurl/curl_multi_wakeup.md b/docs/libcurl/curl_multi_wakeup.md new file mode 100644 index 00000000000..f6200c41e4d --- /dev/null +++ b/docs/libcurl/curl_multi_wakeup.md @@ -0,0 +1,91 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_multi_wakeup +Section: 3 +Source: libcurl +See-also: + - curl_multi_poll (3) + - curl_multi_wait (3) +--- + +# NAME + +curl_multi_wakeup - wakes up a sleeping curl_multi_poll call + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_wakeup(CURLM *multi_handle); +~~~ + +# DESCRIPTION + +This function can be called from any thread and it wakes up a sleeping +curl_multi_poll(3) call that is currently (or is about to be) waiting +for activity or a timeout. + +If the function is called when there is no curl_multi_poll(3) call, it +causes the next call to return immediately. + +Calling this function only guarantees to wake up the current (or the next if +there is no current) curl_multi_poll(3) call, which means it is possible +that multiple calls to this function wake up the same waiting operation. + +This function has no effect on curl_multi_wait(3) calls. + +# EXAMPLE + +~~~c +extern int time_to_die(void); +extern int set_something_to_signal_thread_1_to_exit(void); +extern int decide_to_stop_thread1(); + +int main(void) +{ + CURL *easy; + CURLM *multi; + int still_running; + + /* add the individual easy handle */ + curl_multi_add_handle(multi, easy); + + /* this is thread 1 */ + do { + CURLMcode mc; + int numfds; + + mc = curl_multi_perform(multi, &still_running); + + if(mc == CURLM_OK) { + /* wait for activity, timeout or wakeup */ + mc = curl_multi_poll(multi, NULL, 0, 10000, &numfds); + } + + if(time_to_die()) + return 1; + + } while(still_running); + + curl_multi_remove_handle(multi, easy); + + /* this is thread 2 */ + + if(decide_to_stop_thread1()) { + + set_something_to_signal_thread_1_to_exit(); + + curl_multi_wakeup(multi); + } +} +~~~ + +# AVAILABILITY + +Added in 7.68.0 + +# RETURN VALUE + +CURLMcode type, general libcurl multi interface error code. diff --git a/docs/libcurl/curl_pushheader_byname.3 b/docs/libcurl/curl_pushheader_byname.md similarity index 50% rename from docs/libcurl/curl_pushheader_byname.3 rename to docs/libcurl/curl_pushheader_byname.md index ad8459c36b5..ecb031f9e95 100644 --- a/docs/libcurl/curl_pushheader_byname.3 +++ b/docs/libcurl/curl_pushheader_byname.md @@ -1,38 +1,30 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_pushheader_byname 3 "9 Jun 2023" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_pushheader_byname +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PUSHFUNCTION (3) + - curl_pushheader_bynum (3) +--- + +# NAME + curl_pushheader_byname - get a push header by name -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This is a function that is only functional within a -\fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it +CURLMOPT_PUSHFUNCTION(3) callback. It makes no sense to try to use it elsewhere and it has no function then. It returns the value for the given header field name (or NULL) for the @@ -41,8 +33,9 @@ not have to loop through all headers to find the one it is interested in. The data this function points to is freed when this callback returns. If more than one header field use the same name, this returns only the first one. -.SH EXAMPLE -.nf +# EXAMPLE + +~~~c #include /* for strncmp */ static int push_cb(CURL *parent, @@ -56,7 +49,7 @@ static int push_cb(CURL *parent, FILE *out; headp = curl_pushheader_byname(headers, ":path"); if(headp && !strncmp(headp, "/push-", 6)) { - fprintf(stderr, "The PATH is %s\\n", headp); + fprintf(stderr, "The PATH is %s\n", headp); /* save the push here */ out = fopen("pushed-stream", "wb"); @@ -78,11 +71,12 @@ int main(void) curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb); curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.44.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns a pointer to the header field content or NULL. -.SH "SEE ALSO" -.BR CURLMOPT_PUSHFUNCTION (3), -.BR curl_pushheader_bynum (3) diff --git a/docs/libcurl/curl_pushheader_bynum.3 b/docs/libcurl/curl_pushheader_bynum.3 deleted file mode 100644 index da951bafb94..00000000000 --- a/docs/libcurl/curl_pushheader_bynum.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.TH curl_pushheader_bynum 3 "9 Jun 2023" "libcurl" "libcurl" -.SH NAME -curl_pushheader_bynum - get a push header by index -.SH SYNOPSIS -.nf -#include - -char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num); -.fi -.SH DESCRIPTION -This is a function that is only functional within a -\fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it -elsewhere and it has no function then. - -It returns the value for the header field at the given index \fBnum\fP, for -the incoming server push request or NULL. The data pointed to is freed by -libcurl when this callback returns. The returned pointer points to a -"name:value" string that gets freed when this callback returns. - -.SH EXAMPLE -.nf -/* output all the incoming push request headers */ -static int push_cb(CURL *parent, - CURL *easy, - size_t num_headers, - struct curl_pushheaders *headers, - void *clientp) -{ - int i = 0; - char *field; - do { - field = curl_pushheader_bynum(headers, i); - if(field) - fprintf(stderr, "Push header: %s\\n", field); - i++; - } while(field); - return CURL_PUSH_OK; /* permission granted */ -} - -int main(void) -{ - CURLM *multi = curl_multi_init(); - curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb); -} -.fi -.SH AVAILABILITY -Added in 7.44.0 -.SH RETURN VALUE -Returns a pointer to the header field content or NULL. -.SH "SEE ALSO" -.BR CURLMOPT_PUSHFUNCTION (3), -.BR curl_pushheader_byname (3) diff --git a/docs/libcurl/curl_pushheader_bynum.md b/docs/libcurl/curl_pushheader_bynum.md new file mode 100644 index 00000000000..537f06b1ce4 --- /dev/null +++ b/docs/libcurl/curl_pushheader_bynum.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_pushheader_bynum +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PUSHFUNCTION (3) + - curl_pushheader_byname (3) +--- + +# NAME + +curl_pushheader_bynum - get a push header by index + +# SYNOPSIS + +~~~c +#include + +char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num); +~~~ + +# DESCRIPTION + +This is a function that is only functional within a +CURLMOPT_PUSHFUNCTION(3) callback. It makes no sense to try to use it +elsewhere and it has no function then. + +It returns the value for the header field at the given index **num**, for +the incoming server push request or NULL. The data pointed to is freed by +libcurl when this callback returns. The returned pointer points to a +"name:value" string that gets freed when this callback returns. + +# EXAMPLE + +~~~c +/* output all the incoming push request headers */ +static int push_cb(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp) +{ + int i = 0; + char *field; + do { + field = curl_pushheader_bynum(headers, i); + if(field) + fprintf(stderr, "Push header: %s\n", field); + i++; + } while(field); + return CURL_PUSH_OK; /* permission granted */ +} + +int main(void) +{ + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb); +} +~~~ + +# AVAILABILITY + +Added in 7.44.0 + +# RETURN VALUE + +Returns a pointer to the header field content or NULL. diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 deleted file mode 100644 index ad49857f26b..00000000000 --- a/docs/libcurl/curl_share_cleanup.3 +++ /dev/null @@ -1,59 +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 -.\" * -.\" ************************************************************************** -.TH curl_share_cleanup 3 "8 Aug 2003" "libcurl" "libcurl" -.SH NAME -curl_share_cleanup - Clean up a shared object -.SH SYNOPSIS -.nf -#include - -CURLSHcode curl_share_cleanup(CURLSH *share_handle); -.fi -.SH DESCRIPTION -This function deletes a shared object. The share handle cannot be used anymore -when this function has been called. - -Passing in a NULL pointer in \fIshare_handle\fP makes this function return -immediately with no action. -.SH EXAMPLE -.nf -int main(void) -{ - CURLSHcode sh; - CURLSH *share = curl_share_init(); - sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); - /* use the share, then ... */ - curl_share_cleanup(share); -} -.fi -.SH AVAILABILITY -Added in 7.10 -.SH RETURN VALUE -CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred as \fI\fP defines. See the \fIlibcurl-errors(3)\fP -man page for the full list with descriptions. If an error occurs, then the -share object is not deleted. -.SH "SEE ALSO" -.BR curl_share_init (3), -.BR curl_share_setopt (3) diff --git a/docs/libcurl/curl_share_cleanup.md b/docs/libcurl/curl_share_cleanup.md new file mode 100644 index 00000000000..59126a145bc --- /dev/null +++ b/docs/libcurl/curl_share_cleanup.md @@ -0,0 +1,54 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_share_cleanup +Section: 3 +Source: libcurl +See-also: + - curl_share_init (3) + - curl_share_setopt (3) +--- + +# NAME + +curl_share_cleanup - Clean up a shared object + +# SYNOPSIS + +~~~c +#include + +CURLSHcode curl_share_cleanup(CURLSH *share_handle); +~~~ + +# DESCRIPTION + +This function deletes a shared object. The share handle cannot be used anymore +when this function has been called. + +Passing in a NULL pointer in *share_handle* makes this function return +immediately with no action. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); + /* use the share, then ... */ + curl_share_cleanup(share); +} +~~~ + +# AVAILABILITY + +Added in 7.10 + +# RETURN VALUE + +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred as ** defines. See the libcurl-errors(3) +man page for the full list with descriptions. If an error occurs, then the +share object is not deleted. diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 deleted file mode 100644 index b68c4bd8d98..00000000000 --- a/docs/libcurl/curl_share_init.3 +++ /dev/null @@ -1,61 +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 -.\" * -.\" ************************************************************************** -.TH curl_share_init 3 "Aug 3, 2003" "libcurl" "libcurl" -.SH NAME -curl_share_init - Create a shared object -.SH SYNOPSIS -.nf -#include - -CURLSH *curl_share_init(); -.fi -.SH DESCRIPTION -This function returns a pointer to a \fICURLSH\fP handle to be used as input -to all the other share-functions, sometimes referred to as a share handle in -some places in the documentation. This init call MUST have a corresponding -call to \fIcurl_share_cleanup(3)\fP when all operations using the share are -complete. - -This \fIshare handle\fP is what you pass to curl using the -\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that -specific curl handle use the data in this share. -.SH EXAMPLE -.nf -int main(void) -{ - CURLSHcode sh; - CURLSH *share = curl_share_init(); - sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); - if(sh) - printf("Error: %s\\n", curl_share_strerror(sh)); -} -.fi -.SH AVAILABILITY -Added in 7.10 -.SH RETURN VALUE -If this function returns NULL, something went wrong (out of memory, etc.) -and therefore the share object was not created. -.SH "SEE ALSO" -.BR curl_share_cleanup (3), -.BR curl_share_setopt (3) diff --git a/docs/libcurl/curl_share_init.md b/docs/libcurl/curl_share_init.md new file mode 100644 index 00000000000..553710727bd --- /dev/null +++ b/docs/libcurl/curl_share_init.md @@ -0,0 +1,56 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_share_init +Section: 3 +Source: libcurl +See-also: + - curl_share_cleanup (3) + - curl_share_setopt (3) +--- + +# NAME + +curl_share_init - Create a shared object + +# SYNOPSIS + +~~~c +#include + +CURLSH *curl_share_init(); +~~~ + +# DESCRIPTION + +This function returns a pointer to a *CURLSH* handle to be used as input +to all the other share-functions, sometimes referred to as a share handle in +some places in the documentation. This init call MUST have a corresponding +call to curl_share_cleanup(3) when all operations using the share are +complete. + +This *share handle* is what you pass to curl using the +CURLOPT_SHARE(3) option with curl_easy_setopt(3), to make that +specific curl handle use the data in this share. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); + if(sh) + printf("Error: %s\n", curl_share_strerror(sh)); +} +~~~ + +# AVAILABILITY + +Added in 7.10 + +# RETURN VALUE + +If this function returns NULL, something went wrong (out of memory, etc.) +and therefore the share object was not created. diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 deleted file mode 100644 index 96035499168..00000000000 --- a/docs/libcurl/curl_share_setopt.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.TH curl_share_setopt 3 "8 Aug 2003" "libcurl" "libcurl" -.SH NAME -curl_share_setopt - Set options for a shared object -.SH SYNOPSIS -.nf -#include - -CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter); -.fi -.SH DESCRIPTION -Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP. -.SH OPTIONS -.IP CURLSHOPT_LOCKFUNC -See \fICURLSHOPT_LOCKFUNC(3)\fP. -.IP CURLSHOPT_UNLOCKFUNC -See \fICURLSHOPT_UNLOCKFUNC(3)\fP. -.IP CURLSHOPT_SHARE -See \fICURLSHOPT_SHARE(3)\fP. -.IP CURLSHOPT_UNSHARE -See \fICURLSHOPT_UNSHARE(3)\fP. -.IP CURLSHOPT_USERDATA -See \fICURLSHOPT_USERDATA(3)\fP. -.SH EXAMPLE -.nf -int main(void) -{ - CURLSHcode sh; - CURLSH *share = curl_share_init(); - sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); - if(sh) - printf("Error: %s\\n", curl_share_strerror(sh)); -} -.fi -.SH AVAILABILITY -Added in 7.10 -.SH RETURN VALUE -CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred as \fI\fP defines. See the \fIlibcurl-errors(3)\fP -man page for the full list with descriptions. -.SH "SEE ALSO" -.BR curl_share_cleanup (3), -.BR curl_share_init (3) diff --git a/docs/libcurl/curl_share_setopt.md b/docs/libcurl/curl_share_setopt.md new file mode 100644 index 00000000000..5ab95503be0 --- /dev/null +++ b/docs/libcurl/curl_share_setopt.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_share_setopt +Section: 3 +Source: libcurl +See-also: + - curl_share_cleanup (3) + - curl_share_init (3) +--- + +# NAME + +curl_share_setopt - Set options for a shared object + +# SYNOPSIS + +~~~c +#include + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter); +~~~ + +# DESCRIPTION + +Set the *option* to *parameter* for the given *share*. + +# OPTIONS + +## CURLSHOPT_LOCKFUNC + +See CURLSHOPT_LOCKFUNC(3). + +## CURLSHOPT_UNLOCKFUNC + +See CURLSHOPT_UNLOCKFUNC(3). + +## CURLSHOPT_SHARE + +See CURLSHOPT_SHARE(3). + +## CURLSHOPT_UNSHARE + +See CURLSHOPT_UNSHARE(3). + +## CURLSHOPT_USERDATA + +See CURLSHOPT_USERDATA(3). + +# EXAMPLE + +~~~c +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); + if(sh) + printf("Error: %s\n", curl_share_strerror(sh)); +} +~~~ + +# AVAILABILITY + +Added in 7.10 + +# RETURN VALUE + +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred as ** defines. See the libcurl-errors(3) +man page for the full list with descriptions. diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 deleted file mode 100644 index b1f5e2f39c7..00000000000 --- a/docs/libcurl/curl_share_strerror.3 +++ /dev/null @@ -1,55 +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 -.\" * -.\" ************************************************************************** -.TH curl_share_strerror 3 "Apr 26, 2004" "libcurl" "libcurl" -.SH NAME -curl_share_strerror - return string describing error code -.SH SYNOPSIS -.nf -#include - -const char *curl_share_strerror(CURLSHcode errornum); -.fi -.SH DESCRIPTION -The \fIcurl_share_strerror(3)\fP function returns a string describing the -\fICURLSHcode\fP error code passed in the argument \fIerrornum\fP. -.SH EXAMPLE -.nf -int main(void) -{ - CURLSHcode sh; - CURLSH *share = curl_share_init(); - sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); - if(sh) - printf("Error: %s\\n", curl_share_strerror(sh)); -} -.fi -.SH AVAILABILITY -This function was added in libcurl 7.12.0 -.SH RETURN VALUE -A pointer to a null-terminated string. -.SH "SEE ALSO" -.BR curl_easy_strerror (3), -.BR curl_multi_strerror (3), -.BR curl_url_strerror (3), -.BR libcurl-errors (3) diff --git a/docs/libcurl/curl_share_strerror.md b/docs/libcurl/curl_share_strerror.md new file mode 100644 index 00000000000..130d43b3bba --- /dev/null +++ b/docs/libcurl/curl_share_strerror.md @@ -0,0 +1,50 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_share_strerror +Section: 3 +Source: libcurl +See-also: + - curl_easy_strerror (3) + - curl_multi_strerror (3) + - curl_url_strerror (3) + - libcurl-errors (3) +--- + +# NAME + +curl_share_strerror - return string describing error code + +# SYNOPSIS + +~~~c +#include + +const char *curl_share_strerror(CURLSHcode errornum); +~~~ + +# DESCRIPTION + +The curl_share_strerror(3) function returns a string describing the +*CURLSHcode* error code passed in the argument *errornum*. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); + if(sh) + printf("Error: %s\n", curl_share_strerror(sh)); +} +~~~ + +# AVAILABILITY + +This function was added in libcurl 7.12.0 + +# RETURN VALUE + +A pointer to a null-terminated string. diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 deleted file mode 100644 index 09dbc99a464..00000000000 --- a/docs/libcurl/curl_slist_append.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.TH curl_slist_append 3 "19 Jun 2003" "libcurl" "libcurl" -.SH NAME -curl_slist_append - add a string to an slist -.SH SYNOPSIS -.nf -#include - -struct curl_slist *curl_slist_append(struct curl_slist *list, - const char *string); -.fi -.SH DESCRIPTION -\fIcurl_slist_append(3)\fP appends a string to a linked list of strings. The -existing \fBlist\fP should be passed as the first argument and the new list is -returned from this function. Pass in NULL in the \fBlist\fP argument to create -a new list. The specified \fBstring\fP has been appended when this function -returns. \fIcurl_slist_append(3)\fP copies the string. - -The list should be freed again (after usage) with -\fIcurl_slist_free_all(3)\fP. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *handle; - struct curl_slist *slist = NULL; - struct curl_slist *temp = NULL; - - slist = curl_slist_append(slist, "pragma:"); - - if(!slist) - return -1; - - temp = curl_slist_append(slist, "Accept:"); - - if(!temp) { - curl_slist_free_all(slist); - return -1; - } - - slist = temp; - - curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); - - curl_easy_perform(handle); - - curl_slist_free_all(slist); /* free the list again */ -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -A null pointer is returned if anything went wrong, otherwise the new list -pointer is returned. To avoid overwriting an existing non-empty list on -failure, the new list should be returned to a temporary variable which can -be tested for NULL before updating the original list pointer. -.SH "SEE ALSO" -.BR curl_slist_free_all (3) diff --git a/docs/libcurl/curl_slist_append.md b/docs/libcurl/curl_slist_append.md new file mode 100644 index 00000000000..9773fd49416 --- /dev/null +++ b/docs/libcurl/curl_slist_append.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_slist_append +Section: 3 +Source: libcurl +See-also: + - curl_slist_free_all (3) +--- + +# NAME + +curl_slist_append - add a string to an slist + +# SYNOPSIS + +~~~c +#include + +struct curl_slist *curl_slist_append(struct curl_slist *list, + const char *string); +~~~ + +# DESCRIPTION + +curl_slist_append(3) appends a string to a linked list of strings. The +existing **list** should be passed as the first argument and the new list is +returned from this function. Pass in NULL in the **list** argument to create +a new list. The specified **string** has been appended when this function +returns. curl_slist_append(3) copies the string. + +The list should be freed again (after usage) with +curl_slist_free_all(3). + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *handle; + struct curl_slist *slist = NULL; + struct curl_slist *temp = NULL; + + slist = curl_slist_append(slist, "pragma:"); + + if(!slist) + return -1; + + temp = curl_slist_append(slist, "Accept:"); + + if(!temp) { + curl_slist_free_all(slist); + return -1; + } + + slist = temp; + + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); + + curl_easy_perform(handle); + + curl_slist_free_all(slist); /* free the list again */ +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +A null pointer is returned if anything went wrong, otherwise the new list +pointer is returned. To avoid overwriting an existing non-empty list on +failure, the new list should be returned to a temporary variable which can +be tested for NULL before updating the original list pointer. diff --git a/docs/libcurl/curl_slist_free_all.3 b/docs/libcurl/curl_slist_free_all.3 deleted file mode 100644 index 4eeb54132e6..00000000000 --- a/docs/libcurl/curl_slist_free_all.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.TH curl_slist_free_all 3 "5 March 2001" "libcurl" "libcurl" -.SH NAME -curl_slist_free_all - free an entire curl_slist list -.SH SYNOPSIS -.nf -#include - -void curl_slist_free_all(struct curl_slist *list); -.fi -.SH DESCRIPTION -curl_slist_free_all() removes all traces of a previously built curl_slist -linked list. - -Passing in a NULL pointer in \fIlist\fP makes this function return immediately -with no action. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *handle; - struct curl_slist *slist = NULL; - - slist = curl_slist_append(slist, "X-libcurl: coolness"); - - if(!slist) - return -1; - - curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); - - curl_easy_perform(handle); - - curl_slist_free_all(slist); /* free the list again */ -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Nothing. -.SH "SEE ALSO" -.BR curl_slist_append (3) diff --git a/docs/libcurl/curl_slist_free_all.md b/docs/libcurl/curl_slist_free_all.md new file mode 100644 index 00000000000..928f306016f --- /dev/null +++ b/docs/libcurl/curl_slist_free_all.md @@ -0,0 +1,58 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_slist_free_all +Section: 3 +Source: libcurl +See-also: + - curl_slist_append (3) +--- + +# NAME + +curl_slist_free_all - free an entire curl_slist list + +# SYNOPSIS + +~~~c +#include + +void curl_slist_free_all(struct curl_slist *list); +~~~ + +# DESCRIPTION + +curl_slist_free_all() removes all traces of a previously built curl_slist +linked list. + +Passing in a NULL pointer in *list* makes this function return immediately +with no action. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *handle; + struct curl_slist *slist = NULL; + + slist = curl_slist_append(slist, "X-libcurl: coolness"); + + if(!slist) + return -1; + + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); + + curl_easy_perform(handle); + + curl_slist_free_all(slist); /* free the list again */ +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Nothing. diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 deleted file mode 100644 index dc21c2e3ba3..00000000000 --- a/docs/libcurl/curl_strequal.3 +++ /dev/null @@ -1,61 +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 -.\" * -.\" ************************************************************************** -.TH curl_strequal 3 "30 April 2004" "libcurl" "libcurl" -.SH NAME -curl_strequal, curl_strnequal - case insensitive string comparisons -.SH SYNOPSIS -.nf -#include - -int curl_strequal(const char *str1, const char *str2); -int curl_strnequal(const char *str1, const char *str2, size_t length); -.fi -.SH DESCRIPTION -The \fIcurl_strequal(3)\fP function compares the two strings \fIstr1\fP and -\fIstr2\fP, ignoring the case of the characters. It returns a non-zero (TRUE) -integer if the strings are identical. - -The \fBcurl_strnequal()\fP function is similar, except it only compares the -first \fIlength\fP characters of \fIstr1\fP. - -These functions are provided by libcurl to enable applications to compare -strings in a truly portable manner. There are no standard portable case -insensitive string comparison functions. These two work on all platforms. -.SH EXAMPLE -.nf -int main(int argc, char **argv) -{ - const char *name = "compare"; - if(curl_strequal(name, argv[1])) - printf("Name and input matches\\n"); - if(curl_strnequal(name, argv[1], 5)) - printf("Name and input matches in the 5 first bytes\\n"); -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Non-zero if the strings are identical. Zero if they are not. -.SH "SEE ALSO" -.BR strcmp "(3), " strcasecmp "(3)" diff --git a/docs/libcurl/curl_strequal.md b/docs/libcurl/curl_strequal.md new file mode 100644 index 00000000000..518faee6a23 --- /dev/null +++ b/docs/libcurl/curl_strequal.md @@ -0,0 +1,57 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_strequal +Section: 3 +Source: libcurl +See-also: + - strcasecmp (3) + - strcmp (3) +--- + +# NAME + +curl_strequal, curl_strnequal - case insensitive string comparisons + +# SYNOPSIS + +~~~c +#include + +int curl_strequal(const char *str1, const char *str2); +int curl_strnequal(const char *str1, const char *str2, size_t length); +~~~ + +# DESCRIPTION + +The curl_strequal(3) function compares the two strings *str1* and +*str2*, ignoring the case of the characters. It returns a non-zero (TRUE) +integer if the strings are identical. + +The **curl_strnequal()** function is similar, except it only compares the +first *length* characters of *str1*. + +These functions are provided by libcurl to enable applications to compare +strings in a truly portable manner. There are no standard portable case +insensitive string comparison functions. These two work on all platforms. + +# EXAMPLE + +~~~c +int main(int argc, char **argv) +{ + const char *name = "compare"; + if(curl_strequal(name, argv[1])) + printf("Name and input matches\n"); + if(curl_strnequal(name, argv[1], 5)) + printf("Name and input matches in the 5 first bytes\n"); +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Non-zero if the strings are identical. Zero if they are not. diff --git a/docs/libcurl/curl_strnequal.3 b/docs/libcurl/curl_strnequal.3 deleted file mode 100644 index ce41d3e41d0..00000000000 --- a/docs/libcurl/curl_strnequal.3 +++ /dev/null @@ -1 +0,0 @@ -.so man3/curl_strequal.3 diff --git a/docs/libcurl/curl_strnequal.md b/docs/libcurl/curl_strnequal.md new file mode 100644 index 00000000000..518faee6a23 --- /dev/null +++ b/docs/libcurl/curl_strnequal.md @@ -0,0 +1,57 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_strequal +Section: 3 +Source: libcurl +See-also: + - strcasecmp (3) + - strcmp (3) +--- + +# NAME + +curl_strequal, curl_strnequal - case insensitive string comparisons + +# SYNOPSIS + +~~~c +#include + +int curl_strequal(const char *str1, const char *str2); +int curl_strnequal(const char *str1, const char *str2, size_t length); +~~~ + +# DESCRIPTION + +The curl_strequal(3) function compares the two strings *str1* and +*str2*, ignoring the case of the characters. It returns a non-zero (TRUE) +integer if the strings are identical. + +The **curl_strnequal()** function is similar, except it only compares the +first *length* characters of *str1*. + +These functions are provided by libcurl to enable applications to compare +strings in a truly portable manner. There are no standard portable case +insensitive string comparison functions. These two work on all platforms. + +# EXAMPLE + +~~~c +int main(int argc, char **argv) +{ + const char *name = "compare"; + if(curl_strequal(name, argv[1])) + printf("Name and input matches\n"); + if(curl_strnequal(name, argv[1], 5)) + printf("Name and input matches in the 5 first bytes\n"); +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Non-zero if the strings are identical. Zero if they are not. diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 deleted file mode 100644 index 5df8a8f82ff..00000000000 --- a/docs/libcurl/curl_unescape.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.TH curl_unescape 3 "22 March 2001" "libcurl" "libcurl" -.SH NAME -curl_unescape - URL decodes the given string -.SH SYNOPSIS -.nf -#include - -char *curl_unescape(const char *input, int length); -.fi -.SH DESCRIPTION -Obsolete function. Use \fIcurl_easy_unescape(3)\fP instead! - -This function converts the URL encoded string \fBinput\fP to a "plain string" -and return that as a new allocated string. All input characters that are URL -encoded (%XX where XX is a two-digit hexadecimal number) are converted to -their plain text versions. - -If the \fBlength\fP argument is set to 0, \fIcurl_unescape(3)\fP calls -strlen() on \fBinput\fP to find out the size. - -You must \fIcurl_free(3)\fP the returned string when you are done with it. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - char *decoded = curl_unescape("%63%75%72%6c", 12); - if(decoded) { - /* do not assume printf() works on the decoded data! */ - printf("Decoded: "); - /* ... */ - curl_free(decoded); - } - } -} -.fi -.SH AVAILABILITY -Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function might -be removed in a future release. -.SH RETURN VALUE -A pointer to a null-terminated string or NULL if it failed. -.SH "SEE ALSO" -.BR curl_easy_escape (3), -.BR curl_easy_unescape (3), -.BR curl_free (3), -.BR RFC 2396 diff --git a/docs/libcurl/curl_unescape.md b/docs/libcurl/curl_unescape.md new file mode 100644 index 00000000000..8ae9f508970 --- /dev/null +++ b/docs/libcurl/curl_unescape.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_unescape +Section: 3 +Source: libcurl +See-also: + - RFC 2396 + - curl_easy_escape (3) + - curl_easy_unescape (3) + - curl_free (3) +--- + +# NAME + +curl_unescape - URL decodes the given string + +# SYNOPSIS + +~~~c +#include + +char *curl_unescape(const char *input, int length); +~~~ + +# DESCRIPTION + +Obsolete function. Use curl_easy_unescape(3) instead. + +This function converts the URL encoded string **input** to a "plain string" +and return that as a new allocated string. All input characters that are URL +encoded (%XX where XX is a two-digit hexadecimal number) are converted to +their plain text versions. + +If the **length** argument is set to 0, curl_unescape(3) calls +strlen() on **input** to find out the size. + +You must curl_free(3) the returned string when you are done with it. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char *decoded = curl_unescape("%63%75%72%6c", 12); + if(decoded) { + /* do not assume printf() works on the decoded data */ + printf("Decoded: "); + /* ... */ + curl_free(decoded); + } + } +} +~~~ + +# AVAILABILITY + +Since 7.15.4, curl_easy_unescape(3) should be used. This function might +be removed in a future release. + +# RETURN VALUE + +A pointer to a null-terminated string or NULL if it failed. diff --git a/docs/libcurl/curl_url.3 b/docs/libcurl/curl_url.3 deleted file mode 100644 index 3f6eb0c0116..00000000000 --- a/docs/libcurl/curl_url.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.TH curl_url 3 "6 Aug 2018" "libcurl" "libcurl" -.SH NAME -curl_url - returns a new URL handle -.SH SYNOPSIS -.nf -#include - -CURLU *curl_url(); -.fi -.SH DESCRIPTION -This function allocates a URL object and returns a \fICURLU\fP handle for it, -to be used as input to all other URL API functions. - -This is a handle to a URL object that holds or can hold URL components for a -single URL. When the object is first created, there is of course no components -stored. They are then set in the object with the \fIcurl_url_set(3)\fP -function. -.SH EXAMPLE -.nf -int main(void) -{ - CURLUcode rc; - CURLU *url = curl_url(); - rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); - if(!rc) { - char *scheme; - rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); - if(!rc) { - printf("the scheme is %s\\n", scheme); - curl_free(scheme); - } - curl_url_cleanup(url); - } -} -.fi -.SH AVAILABILITY -Added in 7.62.0 -.SH RETURN VALUE -Returns a \fBCURLU *\fP if successful, or NULL if out of memory. -.SH "SEE ALSO" -.BR curl_url_cleanup (3), -.BR curl_url_dup (3), -.BR curl_url_get (3), -.BR curl_url_set (3), -.BR curl_url_strerror (3), -.BR CURLOPT_CURLU (3) diff --git a/docs/libcurl/curl_url.md b/docs/libcurl/curl_url.md new file mode 100644 index 00000000000..f71fb3580fe --- /dev/null +++ b/docs/libcurl/curl_url.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_url +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CURLU (3) + - curl_url_cleanup (3) + - curl_url_dup (3) + - curl_url_get (3) + - curl_url_set (3) + - curl_url_strerror (3) +--- + +# NAME + +curl_url - returns a new URL handle + +# SYNOPSIS + +~~~c +#include + +CURLU *curl_url(); +~~~ + +# DESCRIPTION + +This function allocates a URL object and returns a *CURLU* handle for it, +to be used as input to all other URL API functions. + +This is a handle to a URL object that holds or can hold URL components for a +single URL. When the object is first created, there is of course no components +stored. They are then set in the object with the curl_url_set(3) +function. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLUcode rc; + CURLU *url = curl_url(); + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(!rc) { + char *scheme; + rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); + if(!rc) { + printf("the scheme is %s\n", scheme); + curl_free(scheme); + } + curl_url_cleanup(url); + } +} +~~~ + +# AVAILABILITY + +Added in 7.62.0 + +# RETURN VALUE + +Returns a **CURLU *** if successful, or NULL if out of memory. diff --git a/docs/libcurl/curl_url_cleanup.3 b/docs/libcurl/curl_url_cleanup.3 deleted file mode 100644 index 94507efc37d..00000000000 --- a/docs/libcurl/curl_url_cleanup.3 +++ /dev/null @@ -1,56 +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 -.\" * -.\" ************************************************************************** -.TH curl_url_cleanup 3 "6 Aug 2018" "libcurl" "libcurl" -.SH NAME -curl_url_cleanup - free the URL handle -.SH SYNOPSIS -.nf -#include - -void curl_url_cleanup(CURLU *handle); -.fi -.SH DESCRIPTION -Frees all the resources associated with the given \fICURLU\fP handle! - -Passing in a NULL pointer in \fIhandle\fP makes this function return -immediately with no action. -.SH EXAMPLE -.nf -int main(void) -{ - CURLU *url = curl_url(); - curl_url_set(url, CURLUPART_URL, "https://example.com", 0); - curl_url_cleanup(url); -} -.fi -.SH AVAILABILITY -Added in 7.62.0 -.SH RETURN VALUE -none -.SH "SEE ALSO" -.BR curl_url_dup (3), -.BR curl_url (3), -.BR curl_url_set (3), -.BR curl_url_get (3), -.BR CURLOPT_CURLU (3) diff --git a/docs/libcurl/curl_url_cleanup.md b/docs/libcurl/curl_url_cleanup.md new file mode 100644 index 00000000000..d0f85b69ca0 --- /dev/null +++ b/docs/libcurl/curl_url_cleanup.md @@ -0,0 +1,51 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_url_cleanup +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CURLU (3) + - curl_url (3) + - curl_url_dup (3) + - curl_url_get (3) + - curl_url_set (3) +--- + +# NAME + +curl_url_cleanup - free the URL handle + +# SYNOPSIS + +~~~c +#include + +void curl_url_cleanup(CURLU *handle); +~~~ + +# DESCRIPTION + +Frees all the resources associated with the given *CURLU* handle! + +Passing in a NULL pointer in *handle* makes this function return +immediately with no action. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLU *url = curl_url(); + curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + curl_url_cleanup(url); +} +~~~ + +# AVAILABILITY + +Added in 7.62.0 + +# RETURN VALUE + +none diff --git a/docs/libcurl/curl_url_dup.3 b/docs/libcurl/curl_url_dup.3 deleted file mode 100644 index 2288347714c..00000000000 --- a/docs/libcurl/curl_url_dup.3 +++ /dev/null @@ -1,61 +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 -.\" * -.\" ************************************************************************** -.TH curl_url_dup 3 "6 Aug 2018" "libcurl" "libcurl" -.SH NAME -curl_url_dup - duplicate a URL handle -.SH SYNOPSIS -.nf -#include - -CURLU *curl_url_dup(const CURLU *inhandle); -.fi -.SH DESCRIPTION -Duplicates the URL object the input \fICURLU\fP \fIinhandle\fP identifies and -returns a pointer to the copy as a new \fICURLU\fP handle. The new handle also -needs to be freed with \fIcurl_url_cleanup(3)\fP. -.SH EXAMPLE -.nf -int main(void) -{ - CURLUcode rc; - CURLU *url = curl_url(); - CURLU *url2; - rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); - if(!rc) { - url2 = curl_url_dup(url); /* clone it! */ - curl_url_cleanup(url2); - } - curl_url_cleanup(url); -} -.fi -.SH AVAILABILITY -Added in 7.62.0 -.SH RETURN VALUE -Returns a new handle or NULL if out of memory. -.SH "SEE ALSO" -.BR curl_url (3), -.BR curl_url_cleanup (3), -.BR curl_url_get (3), -.BR curl_url_set (3), -.BR CURLOPT_CURLU (3) diff --git a/docs/libcurl/curl_url_dup.md b/docs/libcurl/curl_url_dup.md new file mode 100644 index 00000000000..ea590ce836d --- /dev/null +++ b/docs/libcurl/curl_url_dup.md @@ -0,0 +1,56 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_url_dup +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CURLU (3) + - curl_url (3) + - curl_url_cleanup (3) + - curl_url_get (3) + - curl_url_set (3) +--- + +# NAME + +curl_url_dup - duplicate a URL handle + +# SYNOPSIS + +~~~c +#include + +CURLU *curl_url_dup(const CURLU *inhandle); +~~~ + +# DESCRIPTION + +Duplicates the URL object the input *CURLU* *inhandle* identifies and +returns a pointer to the copy as a new *CURLU* handle. The new handle also +needs to be freed with curl_url_cleanup(3). + +# EXAMPLE + +~~~c +int main(void) +{ + CURLUcode rc; + CURLU *url = curl_url(); + CURLU *url2; + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(!rc) { + url2 = curl_url_dup(url); /* clone it! */ + curl_url_cleanup(url2); + } + curl_url_cleanup(url); +} +~~~ + +# AVAILABILITY + +Added in 7.62.0 + +# RETURN VALUE + +Returns a new handle or NULL if out of memory. diff --git a/docs/libcurl/curl_url_get.3 b/docs/libcurl/curl_url_get.md similarity index 50% rename from docs/libcurl/curl_url_get.3 rename to docs/libcurl/curl_url_get.md index 1940f4b6a4c..d373a3f4b27 100644 --- a/docs/libcurl/curl_url_get.3 +++ b/docs/libcurl/curl_url_get.md @@ -1,62 +1,68 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_url_get 3 "6 Aug 2018" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_url_get +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CURLU (3) + - curl_url (3) + - curl_url_cleanup (3) + - curl_url_dup (3) + - curl_url_set (3) + - curl_url_strerror (3) +--- + +# NAME + curl_url_get - extract a part from a URL -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLUcode curl_url_get(const CURLU *url, CURLUPart part, char **content, unsigned int flags); -.fi -.SH DESCRIPTION -Given a \fIurl\fP handle of a URL object, this function extracts an individual +~~~ + +# DESCRIPTION + +Given a *url* handle of a URL object, this function extracts an individual piece or the full URL from it. -The \fIpart\fP argument specifies which part to extract (see list below) and -\fIcontent\fP points to a 'char *' to get updated to point to a newly +The *part* argument specifies which part to extract (see list below) and +*content* points to a 'char *' to get updated to point to a newly allocated string with the contents. -The \fIflags\fP argument is a bitmask with individual features. +The *flags* argument is a bitmask with individual features. + +The returned content pointer must be freed with curl_free(3) after use. + +# FLAGS -The returned content pointer must be freed with \fIcurl_free(3)\fP after use. -.SH FLAGS The flags argument is zero, one or more bits set in a bitmask. -.IP CURLU_DEFAULT_PORT -If the handle has no port stored, this option makes \fIcurl_url_get(3)\fP + +## CURLU_DEFAULT_PORT + +If the handle has no port stored, this option makes curl_url_get(3) return the default port for the used scheme. -.IP CURLU_DEFAULT_SCHEME -If the handle has no scheme stored, this option makes \fIcurl_url_get(3)\fP + +## CURLU_DEFAULT_SCHEME + +If the handle has no scheme stored, this option makes curl_url_get(3) return the default scheme instead of error. -.IP CURLU_NO_DEFAULT_PORT -Instructs \fIcurl_url_get(3)\fP to not return a port number if it matches the + +## CURLU_NO_DEFAULT_PORT + +Instructs curl_url_get(3) to not return a port number if it matches the default port for the scheme. -.IP CURLU_URLDECODE -Asks \fIcurl_url_get(3)\fP to URL decode the contents before returning it. It + +## CURLU_URLDECODE + +Asks curl_url_get(3) to URL decode the contents before returning it. It does not decode the scheme, the port number or the full URL. The query component also gets plus-to-space conversion as a bonus when this @@ -67,84 +73,113 @@ string back with data that could be intended for a particular encoding. If there are byte values lower than 32 in the decoded string, the get operation returns an error instead. -.IP CURLU_URLENCODE -If set, \fIcurl_url_get(3)\fP URL encodes the host name part when a full URL + +## CURLU_URLENCODE + +If set, curl_url_get(3) URL encodes the host name part when a full URL is retrieved. If not set (default), libcurl returns the URL with the host name "raw" to support IDN names to appear as-is. IDN host names are typically using non-ASCII bytes that otherwise gets percent-encoded. Note that even when not asking for URL encoding, the '%' (byte 37) is URL encoded to make sure the host name remains valid. -.IP CURLU_PUNYCODE -If set and \fICURLU_URLENCODE\fP is not set, and asked to retrieve the -\fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP parts, libcurl returns the host + +## CURLU_PUNYCODE + +If set and *CURLU_URLENCODE* is not set, and asked to retrieve the +**CURLUPART_HOST** or **CURLUPART_URL** parts, libcurl returns the host name in its punycode version if it contains any non-ASCII octets (and is an IDN name). If libcurl is built without IDN capabilities, using this bit makes -\fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the host name contains +curl_url_get(3) return *CURLUE_LACKS_IDN* if the host name contains anything outside the ASCII range. (Added in curl 7.88.0) -.IP CURLU_PUNY2IDN -If set and asked to retrieve the \fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP + +## CURLU_PUNY2IDN + +If set and asked to retrieve the **CURLUPART_HOST** or **CURLUPART_URL** parts, libcurl returns the host name in its IDN (International Domain Name) UTF-8 version if it otherwise is a punycode version. If the punycode name cannot be converted to IDN correctly, libcurl returns -\fICURLUE_BAD_HOSTNAME\fP. +*CURLUE_BAD_HOSTNAME*. If libcurl is built without IDN capabilities, using this bit makes -\fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the host name is using +curl_url_get(3) return *CURLUE_LACKS_IDN* if the host name is using punycode. (Added in curl 8.3.0) -.SH PARTS -.IP CURLUPART_URL -When asked to return the full URL, \fIcurl_url_get(3)\fP returns a normalized + +# PARTS + +## CURLUPART_URL + +When asked to return the full URL, curl_url_get(3) returns a normalized and possibly cleaned up version using all available URL parts. -We advise using the \fICURLU_PUNYCODE\fP option to get the URL as "normalized" +We advise using the *CURLU_PUNYCODE* option to get the URL as "normalized" as possible since IDN allows host names to be written in many different ways that still end up the same punycode version. -.IP CURLUPART_SCHEME + +## CURLUPART_SCHEME + Scheme cannot be URL decoded on get. -.IP CURLUPART_USER -.IP CURLUPART_PASSWORD -.IP CURLUPART_OPTIONS + +## CURLUPART_USER + +## CURLUPART_PASSWORD + +## CURLUPART_OPTIONS + The options field is an optional field that might follow the password in the userinfo part. It is only recognized/used when parsing URLs for the following schemes: pop3, smtp and imap. The URL API still allows users to set and get this field independently of scheme when not parsing full URLs. -.IP CURLUPART_HOST + +## CURLUPART_HOST + The host name. If it is an IPv6 numeric address, the zone id is not part of it -but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical addresses +but is provided separately in *CURLUPART_ZONEID*. IPv6 numerical addresses are returned within brackets ([]). IPv6 names are normalized when set, which should make them as short as possible while maintaining correct syntax. -.IP CURLUPART_ZONEID + +## CURLUPART_ZONEID + If the host name is a numeric IPv6 address, this field might also be set. -.IP CURLUPART_PORT + +## CURLUPART_PORT + A port cannot be URL decoded on get. This number is returned in a string just like all other parts. That string is guaranteed to hold a valid port number in ASCII using base 10. -.IP CURLUPART_PATH -The \fIpart\fP is always at least a slash ('/') even if no path was supplied + +## CURLUPART_PATH + +The *part* is always at least a slash ('/') even if no path was supplied in the URL. A URL path always starts with a slash. -.IP CURLUPART_QUERY + +## CURLUPART_QUERY + The initial question mark that denotes the beginning of the query part is a -delimiter only. It is not part of the query contents. +delimiter only. It is not part of the query contents. -A not-present query returns \fIpart\fP set to NULL. -A zero-length query returns \fIpart\fP as a zero-length string. +A not-present query returns *part* set to NULL. +A zero-length query returns *part* as a zero-length string. The query part gets pluses converted to space when asked to URL decode on get with the CURLU_URLDECODE bit. -.IP CURLUPART_FRAGMENT + +## CURLUPART_FRAGMENT + The initial hash sign that denotes the beginning of the fragment is a delimiter only. It is not part of the fragment contents. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURLUcode rc; @@ -154,25 +189,22 @@ int main(void) char *scheme; rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); if(!rc) { - printf("the scheme is %s\\n", scheme); + printf("the scheme is %s\n", scheme); curl_free(scheme); } curl_url_cleanup(url); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0. -.SH RETURN VALUE + +# RETURN VALUE + Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went -fine. See the \fIlibcurl-errors(3)\fP man page for the full list with +fine. See the libcurl-errors(3) man page for the full list with descriptions. If this function returns an error, no URL part is returned. -.SH "SEE ALSO" -.BR curl_url (3), -.BR curl_url_cleanup (3), -.BR curl_url_dup (3), -.BR curl_url_set (3), -.BR curl_url_strerror (3), -.BR CURLOPT_CURLU (3) diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.md similarity index 56% rename from docs/libcurl/curl_url_set.3 rename to docs/libcurl/curl_url_set.md index e5b1790b8cc..6a7526f900b 100644 --- a/docs/libcurl/curl_url_set.3 +++ b/docs/libcurl/curl_url_set.md @@ -1,64 +1,60 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH curl_url_set 3 "6 Aug 2018" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_url_set +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CURLU (3) + - curl_url (3) + - curl_url_cleanup (3) + - curl_url_dup (3) + - curl_url_get (3) + - curl_url_strerror (3) +--- + +# NAME + curl_url_set - set a URL part -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLUcode curl_url_set(CURLU *url, CURLUPart part, const char *content, unsigned int flags); -.fi -.SH DESCRIPTION -The \fIurl\fP handle to work on, passed in as the first argument, must be a -handle previously created by \fIcurl_url(3)\fP or \fIcurl_url_dup(3)\fP. +~~~ + +# DESCRIPTION + +The *url* handle to work on, passed in as the first argument, must be a +handle previously created by curl_url(3) or curl_url_dup(3). This function sets or updates individual URL components, or parts, held by the URL object the handle identifies. -The \fIpart\fP argument should identify the particular URL part (see list -below) to set or change, with \fIcontent\fP pointing to a null-terminated +The *part* argument should identify the particular URL part (see list +below) to set or change, with *content* pointing to a null-terminated string with the new contents for that URL part. The contents should be in the form and encoding they would use in a URL: URL encoded. When setting part in the URL object that was previously already set, it replaces the data that was previously stored for that part with the new -\fIcontent\fP. +*content*. -The caller does not have to keep \fIcontent\fP around after a successful call +The caller does not have to keep *content* around after a successful call as this function copies the content. Setting a part to a NULL pointer removes that part's contents from the -\fICURLU\fP handle. +*CURLU* handle. By default, this API only accepts URLs using schemes for protocols that are supported built-in. To make libcurl parse URLs generically even for schemes it -does not know about, the \fBCURLU_NON_SUPPORT_SCHEME\fP flags bit must be -set. Otherwise, this function returns \fICURLUE_UNSUPPORTED_SCHEME\fP for URL +does not know about, the **CURLU_NON_SUPPORT_SCHEME** flags bit must be +set. Otherwise, this function returns *CURLUE_UNSUPPORTED_SCHEME* for URL schemes it does not recognize. This function has an 8 MB maximum length limit for all provided input strings. @@ -70,71 +66,100 @@ accept data that would not be otherwise possible to set in the string when it gets populated as a result of a full URL parse. Beware. If done so, extracting a full URL later on from such components might render an invalid URL. -The \fIflags\fP argument is a bitmask with independent features. -.SH PARTS -.IP CURLUPART_URL +The *flags* argument is a bitmask with independent features. + +# PARTS + +## CURLUPART_URL + Allows the full URL of the handle to be replaced. If the handle already is populated with a URL, the new URL can be relative to the previous. When successfully setting a new URL, relative or absolute, the handle contents is replaced with the components of the newly set URL. -Pass a pointer to a null-terminated string to the \fIurl\fP parameter. The +Pass a pointer to a null-terminated string to the *url* parameter. The string must point to a correctly formatted "RFC 3986+" URL or be a NULL pointer. -Unless \fICURLU_NO_AUTHORITY\fP is set, a blank host name is not allowed in +Unless *CURLU_NO_AUTHORITY* is set, a blank host name is not allowed in the URL. -.IP CURLUPART_SCHEME + +## CURLUPART_SCHEME + Scheme cannot be URL decoded on set. libcurl only accepts setting schemes up to 40 bytes long. -.IP CURLUPART_USER -.IP CURLUPART_PASSWORD -.IP CURLUPART_OPTIONS + +## CURLUPART_USER + +## CURLUPART_PASSWORD + +## CURLUPART_OPTIONS + The options field is an optional field that might follow the password in the userinfo part. It is only recognized/used when parsing URLs for the following schemes: pop3, smtp and imap. This function however allows users to independently set this field. -.IP CURLUPART_HOST + +## CURLUPART_HOST + The host name. If it is International Domain Name (IDN) the string must then be encoded as your locale says or UTF-8 (when WinIDN is used). If it is a bracketed IPv6 numeric address it may contain a zone id (or you can use -\fICURLUPART_ZONEID\fP). +*CURLUPART_ZONEID*). + +Unless *CURLU_NO_AUTHORITY* is set, a blank host name is not allowed to set. + +## CURLUPART_ZONEID -Unless \fICURLU_NO_AUTHORITY\fP is set, a blank host name is not allowed to set. -.IP CURLUPART_ZONEID If the host name is a numeric IPv6 address, this field can also be set. -.IP CURLUPART_PORT + +## CURLUPART_PORT + The port number cannot be URL encoded on set. The given port number is provided as a string and the decimal number in it must be between 0 and 65535. Anything else returns an error. -.IP CURLUPART_PATH + +## CURLUPART_PATH + If a path is set in the URL without a leading slash, a slash is prepended automatically. -.IP CURLUPART_QUERY + +## CURLUPART_QUERY + The query part gets spaces converted to pluses when asked to URL encode on set -with the \fICURLU_URLENCODE\fP bit. +with the *CURLU_URLENCODE* bit. -If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part is +If used together with the *CURLU_APPENDQUERY* bit, the provided part is appended on the end of the existing query. The question mark in the URL is not part of the actual query contents. -.IP CURLUPART_FRAGMENT + +## CURLUPART_FRAGMENT + The hash sign in the URL is not part of the actual fragment contents. -.SH FLAGS + +# FLAGS + The flags argument is zero, one or more bits set in a bitmask. -.IP CURLU_APPENDQUERY -Can be used when setting the \fICURLUPART_QUERY\fP component. The provided new + +## CURLU_APPENDQUERY + +Can be used when setting the *CURLUPART_QUERY* component. The provided new part is then appended at the end of the existing query - and if the previous part did not end with an ampersand (&), an ampersand gets inserted before the new appended part. -When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the +When *CURLU_APPENDQUERY* is used together with *CURLU_URLENCODE*, the first '=' symbol is not URL encoded. -.IP CURLU_NON_SUPPORT_SCHEME -If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme. -.IP CURLU_URLENCODE -When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for + +## CURLU_NON_SUPPORT_SCHEME + +If set, allows curl_url_set(3) to set a non-supported scheme. + +## CURLU_URLENCODE + +When set, curl_url_set(3) URL encodes the part on entry, except for scheme, port and URL. When setting the path component with URL encoding enabled, the slash character @@ -144,41 +169,55 @@ The query part gets space-to-plus conversion before the URL conversion. This URL encoding is charset unaware and converts the input in a byte-by-byte manner. -.IP CURLU_DEFAULT_SCHEME + +## CURLU_DEFAULT_SCHEME + If set, allows the URL to be set without a scheme and then sets that to the -default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP option if both +default scheme: HTTPS. Overrides the *CURLU_GUESS_SCHEME* option if both are set. -.IP CURLU_GUESS_SCHEME + +## CURLU_GUESS_SCHEME + If set, allows the URL to be set without a scheme and it instead "guesses" which scheme that was intended based on the host name. If the outermost subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme is used, otherwise it picks HTTP. Conflicts with the -\fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set. -.IP CURLU_NO_AUTHORITY +*CURLU_DEFAULT_SCHEME* option which takes precedence if both are set. + +## CURLU_NO_AUTHORITY + If set, skips authority checks. The RFC allows individual schemes to omit the host part (normally the only mandatory part of the authority), but libcurl cannot know whether this is permitted for custom schemes. Specifying the flag permits empty authority sections, similar to how file scheme is handled. -.IP CURLU_PATH_AS_IS -When set for \fBCURLUPART_URL\fP, this skips the normalization of the + +## CURLU_PATH_AS_IS + +When set for **CURLUPART_URL**, this skips the normalization of the path. That is the procedure where libcurl otherwise removes sequences of dot-slash and dot-dot etc. The same option used for transfers is called -\fICURLOPT_PATH_AS_IS(3)\fP. -.IP CURLU_ALLOW_SPACE +CURLOPT_PATH_AS_IS(3). + +## CURLU_ALLOW_SPACE + If set, the URL parser allows space (ASCII 32) where possible. The URL syntax does normally not allow spaces anywhere, but they should be encoded as %20 or '+'. When spaces are allowed, they are still not allowed in the scheme. When space is used and allowed in a URL, it is stored as-is unless -\fICURLU_URLENCODE\fP is also set, which then makes libcurl URL encode the +*CURLU_URLENCODE* is also set, which then makes libcurl URL encode the space before stored. This affects how the URL is constructed when -\fIcurl_url_get(3)\fP is subsequently used to extract the full URL or +curl_url_get(3) is subsequently used to extract the full URL or individual parts. (Added in 7.78.0) -.IP CURLU_DISALLOW_USER + +## CURLU_DISALLOW_USER + If set, the URL parser does not accept embedded credentials for the -\fBCURLUPART_URL\fP, and instead returns \fBCURLUE_USER_NOT_ALLOWED\fP for +**CURLUPART_URL**, and instead returns **CURLUE_USER_NOT_ALLOWED** for such URLs. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURLUcode rc; @@ -190,22 +229,19 @@ int main(void) } curl_url_cleanup(url); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0. -.SH RETURN VALUE -Returns a \fICURLUcode\fP error value, which is CURLUE_OK (0) if everything -went fine. See the \fIlibcurl-errors(3)\fP man page for the full list with + +# RETURN VALUE + +Returns a *CURLUcode* error value, which is CURLUE_OK (0) if everything +went fine. See the libcurl-errors(3) man page for the full list with descriptions. -The input string passed to \fIcurl_url_set(3)\fP must be shorter than eight -million bytes. Otherwise this function returns \fBCURLUE_MALFORMED_INPUT\fP. +The input string passed to curl_url_set(3) must be shorter than eight +million bytes. Otherwise this function returns **CURLUE_MALFORMED_INPUT**. If this function returns an error, no URL part is set. -.SH "SEE ALSO" -.BR curl_url (3), -.BR curl_url_cleanup (3), -.BR curl_url_dup (3), -.BR curl_url_get (3), -.BR curl_url_strerror (3), -.BR CURLOPT_CURLU (3) diff --git a/docs/libcurl/curl_url_strerror.3 b/docs/libcurl/curl_url_strerror.3 deleted file mode 100644 index 38af12e9c5c..00000000000 --- a/docs/libcurl/curl_url_strerror.3 +++ /dev/null @@ -1,58 +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 -.\" * -.\" ************************************************************************** -.TH curl_url_strerror 3 "21 Aug 2021" "libcurl" "libcurl" -.SH NAME -curl_url_strerror - return string describing error code -.SH SYNOPSIS -.nf -#include - -const char *curl_url_strerror(CURLUcode errornum); -.fi -.SH DESCRIPTION -This function returns a string describing the CURLUcode error code passed in -the argument \fIerrornum\fP. -.SH EXAMPLE -.nf -int main(void) -{ - CURLUcode rc; - CURLU *url = curl_url(); - rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); - if(rc) - printf("URL error: %s\\n", curl_url_strerror(rc)); - curl_url_cleanup(url); -} -.fi -.SH AVAILABILITY -Added in 7.80.0 -.SH RETURN VALUE -A pointer to a null-terminated string. -.SH "SEE ALSO" -.BR curl_easy_strerror (3), -.BR curl_multi_strerror (3), -.BR curl_share_strerror (3), -.BR curl_url_get (3), -.BR curl_url_set (3), -.BR libcurl-errors (3) diff --git a/docs/libcurl/curl_url_strerror.md b/docs/libcurl/curl_url_strerror.md new file mode 100644 index 00000000000..26562aa2101 --- /dev/null +++ b/docs/libcurl/curl_url_strerror.md @@ -0,0 +1,53 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_url_strerror +Section: 3 +Source: libcurl +See-also: + - curl_easy_strerror (3) + - curl_multi_strerror (3) + - curl_share_strerror (3) + - curl_url_get (3) + - curl_url_set (3) + - libcurl-errors (3) +--- + +# NAME + +curl_url_strerror - return string describing error code + +# SYNOPSIS + +~~~c +#include + +const char *curl_url_strerror(CURLUcode errornum); +~~~ + +# DESCRIPTION + +This function returns a string describing the CURLUcode error code passed in +the argument *errornum*. + +# EXAMPLE + +~~~c +int main(void) +{ + CURLUcode rc; + CURLU *url = curl_url(); + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(rc) + printf("URL error: %s\n", curl_url_strerror(rc)); + curl_url_cleanup(url); +} +~~~ + +# AVAILABILITY + +Added in 7.80.0 + +# RETURN VALUE + +A pointer to a null-terminated string. diff --git a/docs/libcurl/curl_version.3 b/docs/libcurl/curl_version.3 deleted file mode 100644 index fdf09d1ba3d..00000000000 --- a/docs/libcurl/curl_version.3 +++ /dev/null @@ -1,52 +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 -.\" * -.\" ************************************************************************** -.TH curl_version 3 "5 March 2001" "libcurl" "libcurl" -.SH NAME -curl_version - returns the libcurl version string -.SH SYNOPSIS -.nf -#include - -char *curl_version(); -.fi -.SH DESCRIPTION -Returns a human readable string with the version number of libcurl and some of -its important components (like OpenSSL version). - -We recommend using \fIcurl_version_info(3)\fP instead! -.SH EXAMPLE -.nf -int main(void) -{ - printf("libcurl version %s\\n", curl_version()); -} -.fi - -.SH AVAILABILITY -Always -.SH RETURN VALUE -A pointer to a null-terminated string. The string resides in a statically -allocated buffer and must not be freed by the caller. -.SH "SEE ALSO" -.BR curl_version_info (3) diff --git a/docs/libcurl/curl_version.md b/docs/libcurl/curl_version.md new file mode 100644 index 00000000000..3a3cb359bf3 --- /dev/null +++ b/docs/libcurl/curl_version.md @@ -0,0 +1,46 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_version +Section: 3 +Source: libcurl +See-also: + - curl_version_info (3) +--- + +# NAME + +curl_version - returns the libcurl version string + +# SYNOPSIS + +~~~c +#include + +char *curl_version(); +~~~ + +# DESCRIPTION + +Returns a human readable string with the version number of libcurl and some of +its important components (like OpenSSL version). + +We recommend using curl_version_info(3) instead! + +# EXAMPLE + +~~~c +int main(void) +{ + printf("libcurl version %s\n", curl_version()); +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +A pointer to a null-terminated string. The string resides in a statically +allocated buffer and must not be freed by the caller. diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.md similarity index 63% rename from docs/libcurl/curl_version_info.3 rename to docs/libcurl/curl_version_info.md index 32bea8272bc..be626b6ec8d 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.md @@ -1,57 +1,47 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_version_info 3 "2 Nov 2014" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_version_info +Section: 3 +Source: libcurl +See-also: + - curl_version (3) +--- + +# NAME + curl_version_info - returns runtime libcurl version info -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include curl_version_info_data *curl_version_info(CURLversion age); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Returns a pointer to a filled in static struct with information about various -features in the running version of libcurl. \fIage\fP should be set to the +features in the running version of libcurl. *age* should be set to the version of this functionality by the time you write your program. This way, libcurl always returns a proper struct that your program understands, while -programs in the future might get a different struct. \fBCURLVERSION_NOW\fP is +programs in the future might get a different struct. **CURLVERSION_NOW** is the most recent one for the library you have installed: -.nf +~~~c data = curl_version_info(CURLVERSION_NOW); -.fi +~~~ Applications should use this information to judge if things are possible to do or not, instead of using compile-time checks, as dynamic/DLL libraries can be changed independent of applications. This function can alter the returned static data as long as -\fIcurl_global_init(3)\fP has not been called. It is therefore not thread-safe +curl_global_init(3) has not been called. It is therefore not thread-safe before libcurl initialization occurs. The curl_version_info_data struct looks like this -.nf +~~~c typedef struct { CURLversion age; /* see description below */ @@ -113,211 +103,279 @@ typedef struct { below exist */ const char *const *feature_names; /* Feature names. */ } curl_version_info_data; -.fi +~~~ -\fIage\fP describes what the age of this struct is. The number depends on how +*age* describes what the age of this struct is. The number depends on how new the libcurl you are using is. You are however guaranteed to get a struct that you have a matching struct for in the header, as you tell libcurl your "age" with the input argument. -\fIversion\fP is just an ascii string for the libcurl version. +*version* is just an ascii string for the libcurl version. -\fIversion_num\fP is a 24 bit number created like this: <8 bits major number> +*version_num* is a 24 bit number created like this: <8 bits major number> | <8 bits minor number> | <8 bits patch number>. Version 7.9.8 is therefore returned as 0x070908. -\fIhost\fP is an ascii string showing what host information that this libcurl +*host* is an ascii string showing what host information that this libcurl was built for. As discovered by a configure script or set by the build environment. -\fIfeatures\fP is a bit mask representing available features. It can -have none, one or more bits set. -The use of this field is deprecated: use \fIfeature_names\fP instead. -The feature names description below lists the associated bits. +*features* is a bit mask representing available features. It can have none, +one or more bits set. The use of this field is deprecated: use +*feature_names* instead. The feature names description below lists the +associated bits. -\fIfeature_names\fP is a pointer to an array of string pointers, containing the +*feature_names* is a pointer to an array of string pointers, containing the names of the features that libcurl supports. The array is terminated by a NULL -entry. Currently defined names are: -.RS -.IP """alt-svc""" -\fIfeatures\fP mask bit: CURL_VERSION_ALTSVC +entry. See the list of features names below. + +*ssl_version* is an ASCII string for the TLS library name + version +used. If libcurl has no SSL support, this is NULL. For example "Schannel", +&"Secure Transport" or "OpenSSL/1.1.0g". + +*ssl_version_num* is always 0. + +*libz_version* is an ASCII string (there is no numerical version). If +libcurl has no libz support, this is NULL. + +*protocols* is a pointer to an array of char * pointers, containing the +names protocols that libcurl supports (using lowercase letters). The protocol +names are the same as would be used in URLs. The array is terminated by a NULL +entry. + +# FEATURES + +## alt-svc + +*features* mask bit: CURL_VERSION_ALTSVC HTTP Alt-Svc parsing and the associated options (Added in 7.64.1) -.IP """AsynchDNS""" -\fIfeatures\fP mask bit: CURL_VERSION_ASYNCHDNS + +## AsynchDNS + +*features* mask bit: CURL_VERSION_ASYNCHDNS libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi interface. (added in 7.10.7) -.IP """brotli""" -\fIfeatures\fP mask bit: CURL_VERSION_BROTLI + +## brotli + +*features* mask bit: CURL_VERSION_BROTLI supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0) -.IP """Debug""" -\fIfeatures\fP mask bit: CURL_VERSION_DEBUG + +## Debug + +*features* mask bit: CURL_VERSION_DEBUG libcurl was built with debug capabilities (added in 7.10.6) -.IP """gsasl""" -\fIfeatures\fP mask bit: CURL_VERSION_GSASL + +## gsasl + +*features* mask bit: CURL_VERSION_GSASL libcurl was built with libgsasl and thus with some extra SCRAM-SHA authentication methods. (added in 7.76.0) -.IP """GSS-API""" -\fIfeatures\fP mask bit: CURL_VERSION_GSSAPI + +## GSS-API + +*features* mask bit: CURL_VERSION_GSSAPI libcurl was built with support for GSS-API. This makes libcurl use provided functions for Kerberos and SPNEGO authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.38.0) -.IP """HSTS""" -\fIfeatures\fP mask bit: CURL_VERSION_HSTS + +## HSTS + +*features* mask bit: CURL_VERSION_HSTS libcurl was built with support for HSTS (HTTP Strict Transport Security) (Added in 7.74.0) -.IP """HTTP2""" -\fIfeatures\fP mask bit: CURL_VERSION_HTTP2 + +## HTTP2 + +*features* mask bit: CURL_VERSION_HTTP2 libcurl was built with support for HTTP2. (Added in 7.33.0) -.IP """HTTP3""" -\fIfeatures\fP mask bit: CURL_VERSION_HTTP3 + +## HTTP3 + +*features* mask bit: CURL_VERSION_HTTP3 HTTP/3 and QUIC support are built-in (Added in 7.66.0) -.IP """HTTPS-proxy""" -\fIfeatures\fP mask bit: CURL_VERSION_HTTPS_PROXY + +## HTTPS-proxy + +*features* mask bit: CURL_VERSION_HTTPS_PROXY libcurl was built with support for HTTPS-proxy. (Added in 7.52.0) -.IP """IDN""" -\fIfeatures\fP mask bit: CURL_VERSION_IDN + +## IDN + +*features* mask bit: CURL_VERSION_IDN libcurl was built with support for IDNA, domain names with international letters. (Added in 7.12.0) -.IP """IPv6""" -\fIfeatures\fP mask bit: CURL_VERSION_IPV6 + +## IPv6 + +*features* mask bit: CURL_VERSION_IPV6 supports IPv6 -.IP """Kerberos""" -\fIfeatures\fP mask bit: CURL_VERSION_KERBEROS5 + +## Kerberos + +*features* mask bit: CURL_VERSION_KERBEROS5 supports Kerberos V5 authentication for FTP, IMAP, LDAP, POP3, SMTP and SOCKSv5 proxy. (Added in 7.40.0) -.IP """Largefile""" -\fIfeatures\fP mask bit: CURL_VERSION_LARGEFILE + +## Largefile + +*features* mask bit: CURL_VERSION_LARGEFILE libcurl was built with support for large files. (Added in 7.11.1) -.IP """libz""" -\fIfeatures\fP mask bit: CURL_VERSION_LIBZ + +## libz + +*features* mask bit: CURL_VERSION_LIBZ supports HTTP deflate using libz (Added in 7.10) -.IP """MultiSSL""" -\fIfeatures\fP mask bit: CURL_VERSION_MULTI_SSL + +## MultiSSL + +*features* mask bit: CURL_VERSION_MULTI_SSL libcurl was built with multiple SSL backends. For details, see -\fIcurl_global_sslset(3)\fP. +curl_global_sslset(3). (Added in 7.56.0) -.IP """NTLM""" -\fIfeatures\fP mask bit: CURL_VERSION_NTLM + +## NTLM + +*features* mask bit: CURL_VERSION_NTLM supports HTTP NTLM (added in 7.10.6) -.IP """NTLM_WB""" -\fIfeatures\fP mask bit: CURL_VERSION_NTLM_WB + +## NTLM_WB + +*features* mask bit: CURL_VERSION_NTLM_WB libcurl was built with support for NTLM delegation to a winbind helper. (Added in 7.22.0) -.IP """PSL""" -\fIfeatures\fP mask bit: CURL_VERSION_PSL + +## PSL + +*features* mask bit: CURL_VERSION_PSL libcurl was built with support for Mozilla's Public Suffix List. This makes libcurl ignore cookies with a domain that is on the list. (Added in 7.47.0) -.IP """SPNEGO""" -\fIfeatures\fP mask bit: CURL_VERSION_SPNEGO + +## SPNEGO + +*features* mask bit: CURL_VERSION_SPNEGO libcurl was built with support for SPNEGO authentication (Simple and Protected GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) -.IP """SSL""" -\fIfeatures\fP mask bit: CURL_VERSION_SSL + +## SSL + +*features* mask bit: CURL_VERSION_SSL supports SSL (HTTPS/FTPS) (Added in 7.10) -.IP """SSPI""" -\fIfeatures\fP mask bit: CURL_VERSION_SSPI + +## SSPI + +*features* mask bit: CURL_VERSION_SSPI libcurl was built with support for SSPI. This is only available on Windows and makes libcurl use Windows-provided functions for Kerberos, NTLM, SPNEGO and Digest authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.13.2) -.IP """threadsafe""" -\fIfeatures\fP mask bit: CURL_VERSION_THREADSAFE + +## threadsafe + +*features* mask bit: CURL_VERSION_THREADSAFE libcurl was built with thread-safety support (Atomic or SRWLOCK) to protect -curl initialization. (Added in 7.84.0) See \fIlibcurl-thread(3)\fP -.IP """TLS-SRP""" -\fIfeatures\fP mask bit: CURL_VERSION_TLSAUTH_SRP +curl initialization. (Added in 7.84.0) See libcurl-thread(3) + +## TLS-SRP + +*features* mask bit: CURL_VERSION_TLSAUTH_SRP libcurl was built with support for TLS-SRP (in one or more of the built-in TLS backends). (Added in 7.21.4) -.IP """TrackMemory""" -\fIfeatures\fP mask bit: CURL_VERSION_CURLDEBUG + +## TrackMemory + +*features* mask bit: CURL_VERSION_CURLDEBUG libcurl was built with memory tracking debug capabilities. This is mainly of interest for libcurl hackers. (added in 7.19.6) -.IP """Unicode""" -\fIfeatures\fP mask bit: CURL_VERSION_UNICODE + +## Unicode + +*features* mask bit: CURL_VERSION_UNICODE libcurl was built with Unicode support on Windows. This makes non-ASCII characters work in filenames and options passed to libcurl. (Added in 7.72.0) -.IP """UnixSockets""" -\fIfeatures\fP mask bit: CURL_VERSION_UNIX_SOCKETS + +## UnixSockets + +*features* mask bit: CURL_VERSION_UNIX_SOCKETS libcurl was built with support for Unix domain sockets. (Added in 7.40.0) -.IP """zstd""" -\fIfeatures\fP mask bit: CURL_VERSION_ZSTD + +## zstd + +*features* mask bit: CURL_VERSION_ZSTD supports HTTP zstd content encoding using zstd library (Added in 7.72.0) -.IP none -\fIfeatures\fP mask bit: CURL_VERSION_CONV + +## no name + +*features* mask bit: CURL_VERSION_CONV libcurl was built with support for character conversions, as provided by the -CURLOPT_CONV_* callbacks. Always 0 since 7.82.0. (Added in 7.15.4) -.IP none -\fIfeatures\fP mask bit: CURL_VERSION_GSSNEGOTIATE +CURLOPT_CONV_* callbacks. Always 0 since 7.82.0. (Added in 7.15.4, +deprecated.) + +## no name + +*features* mask bit: CURL_VERSION_GSSNEGOTIATE supports HTTP GSS-Negotiate (added in 7.10.6, deprecated in 7.38.0) -.IP none -\fIfeatures\fP mask bit: CURL_VERSION_KERBEROS4 -supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0. -.RE +## no name -\fIssl_version\fP is an ASCII string for the TLS library name + version -used. If libcurl has no SSL support, this is NULL. For example "Schannel", -\&"Secure Transport" or "OpenSSL/1.1.0g". +*features* mask bit: CURL_VERSION_KERBEROS4 -\fIssl_version_num\fP is always 0. +supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0. -\fIlibz_version\fP is an ASCII string (there is no numerical version). If -libcurl has no libz support, this is NULL. +# EXAMPLE -\fIprotocols\fP is a pointer to an array of char * pointers, containing the -names protocols that libcurl supports (using lowercase letters). The protocol -names are the same as would be used in URLs. The array is terminated by a NULL -entry. -.SH EXAMPLE -.nf +~~~c int main(void) { curl_version_info_data *ver = curl_version_info(CURLVERSION_NOW); - printf("libcurl version %u.%u.%u\\n", + printf("libcurl version %u.%u.%u\n", (ver->version_num >> 16) & 0xff, (ver->version_num >> 8) & 0xff, ver->version_num & 0xff); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.10 -.SH RETURN VALUE + +# RETURN VALUE + A pointer to a curl_version_info_data struct. -.SH "SEE ALSO" -\fIcurl_version(3)\fP +curl_version(3) diff --git a/docs/libcurl/curl_ws_meta.3 b/docs/libcurl/curl_ws_meta.md similarity index 53% rename from docs/libcurl/curl_ws_meta.3 rename to docs/libcurl/curl_ws_meta.md index 8623ad08942..531791a519b 100644 --- a/docs/libcurl/curl_ws_meta.3 +++ b/docs/libcurl/curl_ws_meta.md @@ -1,41 +1,35 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_ws_meta 3 "12 Jun 2022" "libcurl" "libcurl" -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_ws_meta +Section: 3 +Source: libcurl +See-also: + - curl_easy_getinfo (3) + - curl_easy_setopt (3) + - curl_ws_recv (3) + - curl_ws_send (3) + - libcurl-ws (3) +--- + +# NAME + curl_ws_meta - meta data WebSocket information -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include const struct curl_ws_frame *curl_ws_meta(CURL *curl); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This function call is EXPERIMENTAL. -When the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP) is invoked on -received WebSocket traffic, \fIcurl_ws_meta(3)\fP can be called from within +When the write callback (CURLOPT_WRITEFUNCTION(3)) is invoked on +received WebSocket traffic, curl_ws_meta(3) can be called from within the callback to provide additional information about the current frame. This function only works from within the callback, and only when receiving @@ -44,45 +38,67 @@ WebSocket data. This function requires an easy handle as input argument for libcurl to know what transfer the question is about, but as there is no such pointer provided to the callback by libcurl itself, applications that want to use -\fIcurl_ws_meta(3)\fP need to pass it on to the callback on its own. +curl_ws_meta(3) need to pass it on to the callback on its own. -.SH "struct curl_ws_frame" -.nf +# struct curl_ws_frame + +~~~c struct curl_ws_frame { int age; int flags; curl_off_t offset; curl_off_t bytesleft; }; -.fi -.IP age +~~~ + +## age + This field specify the age of this struct. It is always zero for now. -.IP flags + +## flags + This is a bitmask with individual bits set that describes the WebSocket data. See the list below. -.IP offset + +## offset + When this frame is a continuation of fragment data already delivered, this is the offset into the final fragment where this piece belongs. -.IP bytesleft -If this is not a complete fragment, the \fIbytesleft\fP field informs about + +## bytesleft + +If this is not a complete fragment, the *bytesleft* field informs about how many additional bytes are expected to arrive before this fragment is complete. -.SH FLAGS -.IP CURLWS_TEXT + +# FLAGS + +## CURLWS_TEXT + The buffer contains text data. Note that this makes a difference to WebSocket but libcurl itself does not make any verification of the content or precautions that you actually receive valid UTF-8 content. -.IP CURLWS_BINARY + +## CURLWS_BINARY + This is binary data. -.IP CURLWS_CONT + +## CURLWS_CONT + This is not the final fragment of the message, it implies that there is another fragment coming as part of the same message. -.IP CURLWS_CLOSE + +## CURLWS_CLOSE + This transfer is now closed. -.IP CURLWS_PING + +## CURLWS_PING + This as an incoming ping message, that expects a pong response. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c /* we pass a pointer to this struct to the callback */ struct customdata { @@ -96,7 +112,7 @@ static size_t writecb(unsigned char *buffer, struct customdata *c = (struct customdata *)p; const struct curl_ws_frame *m = curl_ws_meta(c->easy); - printf("flags: %x\\n", m->flags); + printf("flags: %x\n", m->flags); } int main(void) @@ -113,17 +129,15 @@ int main(void) } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.86.0. -.SH RETURN VALUE -This function returns a pointer to a \fIcurl_ws_frame\fP struct with read-only + +# RETURN VALUE + +This function returns a pointer to a *curl_ws_frame* struct with read-only information that is valid for this specific callback invocation. If it cannot return this information, or if the function is called in the wrong context, it returns NULL. -.SH "SEE ALSO" -.BR curl_easy_setopt (3), -.BR curl_easy_getinfo (3), -.BR curl_ws_send (3), -.BR curl_ws_recv (3), -.BR libcurl-ws (3) diff --git a/docs/libcurl/curl_ws_recv.3 b/docs/libcurl/curl_ws_recv.3 deleted file mode 100644 index e35d9368853..00000000000 --- a/docs/libcurl/curl_ws_recv.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_ws_recv 3 "12 Jun 2022" "libcurl" "libcurl" -.SH NAME -curl_ws_recv - receive WebSocket data -.SH SYNOPSIS -.nf -#include - -CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, - size_t *recv, const struct curl_ws_frame **meta); -.fi -.SH DESCRIPTION -This function call is EXPERIMENTAL. - -Retrieves as much as possible of a received WebSocket data fragment into the -\fBbuffer\fP, but not more than \fBbuflen\fP bytes. \fIrecv\fP is set to the -number of bytes actually stored. - -If there is more fragment data to deliver than what fits in the provided -\fIbuffer\fP, libcurl returns a full buffer and the application needs to call -this function again to continue draining the buffer. - -The \fImeta\fP pointer gets set to point to a \fIconst struct curl_ws_frame\fP -that contains information about the received data. See the -\fIcurl_ws_meta(3)\fP for details on that struct. -.SH EXAMPLE -.nf -int main(void) -{ - size_t rlen; - const struct curl_ws_frame *meta; - char buffer[256]; - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res = curl_ws_recv(curl, buffer, sizeof(buffer), &rlen, &meta); - if(res) - printf("error: %s\\n", curl_easy_strerror(res)); - } -} -.fi -.SH AVAILABILITY -Added in 7.86.0. -.SH RETURN VALUE -Returns \fBCURLE_OK\fP if everything is okay, and a non-zero number for -errors. Returns \fBCURLE_GOT_NOTHING\fP if the associated connection is -closed. - -Instead of blocking, the function returns \fBCURLE_AGAIN\fP. The correct -behavior is then to wait for the socket to signal readability before calling -this function again. -.SH "SEE ALSO" -.BR curl_easy_setopt (3), -.BR curl_easy_perform (3), -.BR curl_easy_getinfo (3), -.BR curl_ws_send (3), -.BR libcurl-ws (3) diff --git a/docs/libcurl/curl_ws_recv.md b/docs/libcurl/curl_ws_recv.md new file mode 100644 index 00000000000..d801eddee20 --- /dev/null +++ b/docs/libcurl/curl_ws_recv.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_ws_recv +Section: 3 +Source: libcurl +See-also: + - curl_easy_getinfo (3) + - curl_easy_perform (3) + - curl_easy_setopt (3) + - curl_ws_send (3) + - libcurl-ws (3) +--- + +# NAME + +curl_ws_recv - receive WebSocket data + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, + size_t *recv, const struct curl_ws_frame **meta); +~~~ + +# DESCRIPTION + +This function call is EXPERIMENTAL. + +Retrieves as much as possible of a received WebSocket data fragment into the +**buffer**, but not more than **buflen** bytes. *recv* is set to the +number of bytes actually stored. + +If there is more fragment data to deliver than what fits in the provided +*buffer*, libcurl returns a full buffer and the application needs to call +this function again to continue draining the buffer. + +The *meta* pointer gets set to point to a *const struct curl_ws_frame* +that contains information about the received data. See the +curl_ws_meta(3) for details on that struct. + +# EXAMPLE + +~~~c +int main(void) +{ + size_t rlen; + const struct curl_ws_frame *meta; + char buffer[256]; + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res = curl_ws_recv(curl, buffer, sizeof(buffer), &rlen, &meta); + if(res) + printf("error: %s\n", curl_easy_strerror(res)); + } +} +~~~ + +# AVAILABILITY + +Added in 7.86.0. + +# RETURN VALUE + +Returns **CURLE_OK** if everything is okay, and a non-zero number for +errors. Returns **CURLE_GOT_NOTHING** if the associated connection is +closed. + +Instead of blocking, the function returns **CURLE_AGAIN**. The correct +behavior is then to wait for the socket to signal readability before calling +this function again. diff --git a/docs/libcurl/curl_ws_send.3 b/docs/libcurl/curl_ws_send.3 deleted file mode 100644 index 95873b78746..00000000000 --- a/docs/libcurl/curl_ws_send.3 +++ /dev/null @@ -1,111 +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 -.\" * -.\" ************************************************************************** -.\" -.TH curl_ws_send 3 "12 Jun 2022" "libcurl" "libcurl" -.SH NAME -curl_ws_send - send WebSocket data -.SH SYNOPSIS -.nf -#include - -CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen, - size_t *sent, curl_off_t fragsize, - unsigned int flags); -.fi -.SH DESCRIPTION -This function call is EXPERIMENTAL. - -Send the specific message fragment over an established WebSocket -connection. The \fIbuffer\fP holds the data to send and it is \fIbuflen\fP -number of payload bytes in that memory area. - -\fIsent\fP is returned as the number of payload bytes actually sent. - -To send a (huge) fragment using multiple calls with partial content per -invoke, set the \fICURLWS_OFFSET\fP bit and the \fIfragsize\fP argument as the -total expected size for the first part, then set the \fICURLWS_OFFSET\fP with -a zero \fIfragsize\fP for the following parts. - -If not sending a partial fragment or if this is raw mode, \fIfragsize\fP -should be set to zero. - -If \fBCURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the -\fBflags\fP argument should be set to 0. - -To send a message consisting of multiple frames, set the \fICURLWS_CONT\fP bit -in all frames except the final one. -.SH FLAGS -.IP CURLWS_TEXT -The buffer contains text data. Note that this makes a difference to WebSocket -but libcurl itself does not make any verification of the content or -precautions that you actually send valid UTF-8 content. -.IP CURLWS_BINARY -This is binary data. -.IP CURLWS_CONT -This is not the final fragment of the message, which implies that there is -another fragment coming as part of the same message where this bit is not set. -.IP CURLWS_CLOSE -Close this transfer. -.IP CURLWS_PING -This is a ping. -.IP CURLWS_PONG -This is a pong. -.IP CURLWS_OFFSET -The provided data is only a partial fragment and there is more coming in a -following call to \fIcurl_ws_send()\fP. When sending only a piece of the -fragment like this, the \fIfragsize\fP must be provided with the total -expected fragment size in the first call and it needs to be zero in subsequent -calls. -.SH EXAMPLE -.nf -#include /* for strlen */ - -const char *send_payload = "magic"; - -int main(void) -{ - size_t sent; - CURLcode res; - CURL *curl = curl_easy_init(); - curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/"); - curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L); - curl_easy_perform(curl); - res = curl_ws_send(curl, send_payload, strlen(send_payload), &sent, 0, - CURLWS_PING); - curl_easy_cleanup(curl); - return (int)res; -} -.fi -.SH AVAILABILITY -Added in 7.86.0. -.SH RETURN VALUE -\fICURLE_OK\fP (zero) means that the data was sent properly, non-zero means an -error occurred as \fI\fP defines. See the \fIlibcurl-errors(3)\fP -man page for the full list with descriptions. -.SH "SEE ALSO" -.BR curl_easy_setopt (3), -.BR curl_easy_perform (3), -.BR curl_easy_getinfo (3), -.BR curl_ws_recv (3), -.BR libcurl-ws (3) diff --git a/docs/libcurl/curl_ws_send.md b/docs/libcurl/curl_ws_send.md new file mode 100644 index 00000000000..a5a056c9da8 --- /dev/null +++ b/docs/libcurl/curl_ws_send.md @@ -0,0 +1,120 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: curl_ws_send +Section: 3 +Source: libcurl +See-also: + - curl_easy_getinfo (3) + - curl_easy_perform (3) + - curl_easy_setopt (3) + - curl_ws_recv (3) + - libcurl-ws (3) +--- + +# NAME + +curl_ws_send - send WebSocket data + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen, + size_t *sent, curl_off_t fragsize, + unsigned int flags); +~~~ + +# DESCRIPTION + +This function call is EXPERIMENTAL. + +Send the specific message fragment over an established WebSocket +connection. The *buffer* holds the data to send and it is *buflen* +number of payload bytes in that memory area. + +*sent* is returned as the number of payload bytes actually sent. + +To send a (huge) fragment using multiple calls with partial content per +invoke, set the *CURLWS_OFFSET* bit and the *fragsize* argument as the +total expected size for the first part, then set the *CURLWS_OFFSET* with +a zero *fragsize* for the following parts. + +If not sending a partial fragment or if this is raw mode, *fragsize* +should be set to zero. + +If **CURLWS_RAW_MODE** is enabled in CURLOPT_WS_OPTIONS(3), the +**flags** argument should be set to 0. + +To send a message consisting of multiple frames, set the *CURLWS_CONT* bit +in all frames except the final one. + +# FLAGS + +## CURLWS_TEXT + +The buffer contains text data. Note that this makes a difference to WebSocket +but libcurl itself does not make any verification of the content or +precautions that you actually send valid UTF-8 content. + +## CURLWS_BINARY + +This is binary data. + +## CURLWS_CONT + +This is not the final fragment of the message, which implies that there is +another fragment coming as part of the same message where this bit is not set. + +## CURLWS_CLOSE + +Close this transfer. + +## CURLWS_PING + +This is a ping. + +## CURLWS_PONG + +This is a pong. + +## CURLWS_OFFSET + +The provided data is only a partial fragment and there is more coming in a +following call to *curl_ws_send()*. When sending only a piece of the +fragment like this, the *fragsize* must be provided with the total +expected fragment size in the first call and it needs to be zero in subsequent +calls. + +# EXAMPLE + +~~~c +#include /* for strlen */ + +const char *send_payload = "magic"; + +int main(void) +{ + size_t sent; + CURLcode res; + CURL *curl = curl_easy_init(); + curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/"); + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L); + curl_easy_perform(curl); + res = curl_ws_send(curl, send_payload, strlen(send_payload), &sent, 0, + CURLWS_PING); + curl_easy_cleanup(curl); + return (int)res; +} +~~~ + +# AVAILABILITY + +Added in 7.86.0. + +# RETURN VALUE + +*CURLE_OK* (zero) means that the data was sent properly, non-zero means an +error occurred as ** defines. See the libcurl-errors(3) +man page for the full list with descriptions. diff --git a/docs/libcurl/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 deleted file mode 100644 index 1842c2116ae..00000000000 --- a/docs/libcurl/libcurl-easy.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.TH libcurl 3 "19 Sep 2014" "libcurl" "libcurl" -.SH NAME -libcurl-easy \- easy interface overview -.SH DESCRIPTION -When using libcurl's "easy" interface you init your session and get a handle -(often referred to as an "easy handle"), which you use as input to the easy -interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle. - -You continue by setting all the options you want in the upcoming transfer, the -most important among them is the URL itself (you cannot transfer anything -without a specified URL as you may have figured out yourself). You might want -to set some callbacks as well that are called from the library when data is -available etc. \fIcurl_easy_setopt(3)\fP is used for all this. - -\fICURLOPT_URL(3)\fP is the only option you really must set, as otherwise -there can be no transfer. Another commonly used option is -\fICURLOPT_VERBOSE(3)\fP that helps you see what libcurl is doing under the -hood, which is useful when debugging for example. The -\fIcurl_easy_setopt(3)\fP man page has a full index of the almost 300 -available options. - -If you at any point would like to blank all previously set options for a -single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also -make a clone of an easy handle (with all its set options) using -\fIcurl_easy_duphandle(3)\fP. - -When all is setup, you tell libcurl to perform the transfer using -\fIcurl_easy_perform(3)\fP. It performs the entire transfer operation and does -not return until it is done (successfully or not). - -After the transfer has been made, you can set new options and make another -transfer, or if you are done, cleanup the session by calling -\fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you do not -cleanup immediately, but instead run ahead and perform other transfers using -the same easy handle. -.SH "SEE ALSO" -.BR curl_easy_init (3), -.BR curl_easy_cleanup (3), -.BR curl_easy_setopt (3), -.BR libcurl-errors (3), -.BR libcurl-multi (3), -.BR libcurl (3) diff --git a/docs/libcurl/libcurl-easy.md b/docs/libcurl/libcurl-easy.md new file mode 100644 index 00000000000..f456c97bec8 --- /dev/null +++ b/docs/libcurl/libcurl-easy.md @@ -0,0 +1,52 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl +Section: 3 +Source: libcurl +See-also: + - curl_easy_cleanup (3) + - curl_easy_init (3) + - curl_easy_setopt (3) + - libcurl (3) + - libcurl-errors (3) + - libcurl-multi (3) +--- + +# NAME + +libcurl-easy - easy interface overview + +# DESCRIPTION + +When using libcurl's "easy" interface you init your session and get a handle +(often referred to as an "easy handle"), which you use as input to the easy +interface functions you use. Use curl_easy_init(3) to get the handle. + +You continue by setting all the options you want in the upcoming transfer, the +most important among them is the URL itself (you cannot transfer anything +without a specified URL as you may have figured out yourself). You might want +to set some callbacks as well that are called from the library when data is +available etc. curl_easy_setopt(3) is used for all this. + +CURLOPT_URL(3) is the only option you really must set, as otherwise +there can be no transfer. Another commonly used option is +CURLOPT_VERBOSE(3) that helps you see what libcurl is doing under the +hood, which is useful when debugging for example. The +curl_easy_setopt(3) man page has a full index of the almost 300 +available options. + +If you at any point would like to blank all previously set options for a +single easy handle, you can call curl_easy_reset(3) and you can also +make a clone of an easy handle (with all its set options) using +curl_easy_duphandle(3). + +When all is setup, you tell libcurl to perform the transfer using +curl_easy_perform(3). It performs the entire transfer operation and does +not return until it is done (successfully or not). + +After the transfer has been made, you can set new options and make another +transfer, or if you are done, cleanup the session by calling +curl_easy_cleanup(3). If you want persistent connections, you do not +cleanup immediately, but instead run ahead and perform other transfers using +the same easy handle. diff --git a/docs/libcurl/libcurl-env-dbg.3 b/docs/libcurl/libcurl-env-dbg.3 deleted file mode 100644 index 6995a8ede8f..00000000000 --- a/docs/libcurl/libcurl-env-dbg.3 +++ /dev/null @@ -1,97 +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 -.\" * -.\" ************************************************************************** -.TH libcurl-env-dbg 3 "18 September 2023" "libcurl" "libcurl" -.SH NAME -libcurl-env-dbg \- environment variables libcurl DEBUGBUILD understands -.SH DESCRIPTION -This is a set of variables only recognized and used if libcurl was built -"debug enabled", which should never be true for a library used in production. -These variables are intended for internal use only, subject to change and have -many effects on the behavior of libcurl. Refer to the source code to determine -how exactly they are being used. -.RS -.IP "CURL_ALTSVC_HTTP" -Bypass the AltSvc HTTPS protocol restriction if this variable exists. -.IP "CURL_DBG_SOCK_RBLOCK" -The percentage of recv() calls that should be answered with a EAGAIN at random. -For TCP/UNIX sockets. -.IP "CURL_DBG_SOCK_RMAX" -The maximum data that shall be received from the network in one recv() call. -For TCP/UNIX sockets. This is applied to every recv. - -Example: \fBCURL_DBG_SOCK_RMAX=400\fP means recv buffer size is limited to a -maximum of 400 bytes. -.IP "CURL_DBG_SOCK_WBLOCK" -The percentage of send() calls that should be answered with a EAGAIN at random. -For TCP/UNIX sockets. -.IP "CURL_DBG_SOCK_WPARTIAL" -The percentage of data that shall be written to the network. For TCP/UNIX -sockets. This is applied to every send. - -Example: \fBCURL_DBG_SOCK_WPARTIAL=80\fP means a send with 1000 bytes would -only send 800. -.IP "CURL_DBG_QUIC_WBLOCK" -The percentage of send() calls that should be answered with EAGAIN at random. -QUIC only. -.IP "CURL_DEBUG" -Trace logging behavior as an alternative to calling \fIcurl_global_trace(3)\fP. - -Example: \fBCURL_DEBUG=http/2\fP means trace details about HTTP/2 handling. -.IP "CURL_DEBUG_SIZE" -Fake the size returned by CURLINFO_HEADER_SIZE and CURLINFO_REQUEST_SIZE. -.IP "CURL_GETHOSTNAME" -Fake the local machine's unqualified hostname for NTLM and SMTP. -.IP "CURL_HSTS_HTTP" -Bypass the HSTS HTTPS protocol restriction if this variable exists. -.IP "CURL_FORCETIME" -A time of 0 is used for AWS signatures and NTLM if this variable exists. -.IP "CURL_ENTROPY" -A fixed faked value to use instead of a proper random number so that functions -in libcurl that are otherwise getting random outputs can be tested for what -they generate. -.IP "CURL_SMALLREQSEND" -An alternative size of HTTP data to be sent at a time only if smaller than the -current. -.IP "CURL_SMALLSENDS" -An alternative size of socket data to be sent at a time only if smaller than -the current. -.IP "CURL_TIME" -Fake unix timestamp to use for AltSvc, HSTS and CURLINFO variables that are -time related. - -This variable can also be used to fake the data returned by some CURLINFO -variables that are not time-related (such as CURLINFO_LOCAL_PORT), and in that -case the value is not a timestamp. -.IP "CURL_TRACE" -LDAP tracing is enabled if this variable exists and its value is 1 or greater. - -OpenLDAP tracing is separate. Refer to CURL_OPENLDAP_TRACE. -.IP "CURL_NTLM_WB_FILE" -Debug-version of the \fIntlm-wb\fP executable. -.IP "CURL_OPENLDAP_TRACE" -OpenLDAP tracing is enabled if this variable exists and its value is 1 or -greater. There's a number of debug levels, refer to \fIopenldap.c\fP comments. -.RE -.SH "SEE ALSO" -.BR libcurl-env (3) diff --git a/docs/libcurl/libcurl-env-dbg.md b/docs/libcurl/libcurl-env-dbg.md new file mode 100644 index 00000000000..d697a72fbe0 --- /dev/null +++ b/docs/libcurl/libcurl-env-dbg.md @@ -0,0 +1,118 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-env-dbg +Section: 3 +Source: libcurl +See-also: + - libcurl-env (3) +--- + +# NAME + +libcurl-env-dbg - environment variables libcurl DEBUGBUILD understands + +# DESCRIPTION + +This is a set of variables only recognized and used if libcurl was built +"debug enabled", which should never be true for a library used in production. +These variables are intended for internal use only, subject to change and have +many effects on the behavior of libcurl. Refer to the source code to determine +how exactly they are being used. + +## CURL_ALTSVC_HTTP + +Bypass the AltSvc HTTPS protocol restriction if this variable exists. + +## CURL_DBG_SOCK_RBLOCK + +The percentage of recv() calls that should be answered with a EAGAIN at random. +For TCP/UNIX sockets. + +## CURL_DBG_SOCK_RMAX + +The maximum data that shall be received from the network in one recv() call. +For TCP/UNIX sockets. This is applied to every recv. + +Example: **CURL_DBG_SOCK_RMAX=400** means recv buffer size is limited to a +maximum of 400 bytes. + +## CURL_DBG_SOCK_WBLOCK + +The percentage of send() calls that should be answered with a EAGAIN at random. +For TCP/UNIX sockets. + +## CURL_DBG_SOCK_WPARTIAL + +The percentage of data that shall be written to the network. For TCP/UNIX +sockets. This is applied to every send. + +Example: **CURL_DBG_SOCK_WPARTIAL=80** means a send with 1000 bytes would +only send 800. + +## CURL_DBG_QUIC_WBLOCK + +The percentage of send() calls that should be answered with EAGAIN at random. +QUIC only. + +## CURL_DEBUG + +Trace logging behavior as an alternative to calling curl_global_trace(3). + +Example: **CURL_DEBUG=http/2** means trace details about HTTP/2 handling. + +## CURL_DEBUG_SIZE + +Fake the size returned by CURLINFO_HEADER_SIZE and CURLINFO_REQUEST_SIZE. + +## CURL_GETHOSTNAME + +Fake the local machine's unqualified hostname for NTLM and SMTP. + +## CURL_HSTS_HTTP + +Bypass the HSTS HTTPS protocol restriction if this variable exists. + +## CURL_FORCETIME + +A time of 0 is used for AWS signatures and NTLM if this variable exists. + +## CURL_ENTROPY + +A fixed faked value to use instead of a proper random number so that functions +in libcurl that are otherwise getting random outputs can be tested for what +they generate. + +## CURL_SMALLREQSEND + +An alternative size of HTTP data to be sent at a time only if smaller than the +current. + +## CURL_SMALLSENDS + +An alternative size of socket data to be sent at a time only if smaller than +the current. + +## CURL_TIME + +Fake unix timestamp to use for AltSvc, HSTS and CURLINFO variables that are +time related. + +This variable can also be used to fake the data returned by some CURLINFO +variables that are not time-related (such as CURLINFO_LOCAL_PORT), and in that +case the value is not a timestamp. + +## CURL_TRACE + +LDAP tracing is enabled if this variable exists and its value is 1 or greater. + +OpenLDAP tracing is separate. Refer to CURL_OPENLDAP_TRACE. + +## CURL_NTLM_WB_FILE + +Debug-version of the *ntlm-wb* executable. + +## CURL_OPENLDAP_TRACE + +OpenLDAP tracing is enabled if this variable exists and its value is 1 or +greater. There's a number of debug levels, refer to *openldap.c* comments. diff --git a/docs/libcurl/libcurl-env.3 b/docs/libcurl/libcurl-env.3 deleted file mode 100644 index c2ba4321558..00000000000 --- a/docs/libcurl/libcurl-env.3 +++ /dev/null @@ -1,92 +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 -.\" * -.\" ************************************************************************** -.TH libcurl-env 3 "20 January 2018" "libcurl" "libcurl" -.SH NAME -libcurl-env \- environment variables libcurl understands -.SH DESCRIPTION -libcurl reads and understands a set of environment variables that if set -controls and changes behaviors. This is the full list of variables to set and -description of what they do. Also note that curl, the command line tool, -supports a set of additional environment variables independently of this. -.RS -.IP "[scheme]_proxy" -When libcurl is given a URL to use in a transfer, it first extracts the scheme -part from the URL and checks if there is a given proxy set for that in its -corresponding environment variable. A URL like https://example.com makes -libcurl use the \fBhttp_proxy\fP variable, while a URL like ftp://example.com -uses the \fBftp_proxy\fP variable. - -These proxy variables are also checked for in their uppercase versions, except -the \fBhttp_proxy\fP one which is only used lowercase. Note also that some -systems actually have a case insensitive handling of environment variables and -then of course \fBHTTP_PROXY\fP still works. - -An exception exists for the WebSocket \fBws\fP and \fBwss\fP URL schemes, -where libcurl first checks \fBws_proxy\fP or \fBwss_proxy\fP but if they are -not set, it will fall back and try the http and https versions instead if set. -.IP ALL_PROXY -This is a setting to set proxy for all URLs, independently of what scheme is -being used. Note that the scheme specific variables overrides this one if set. -.IP CURL_SSL_BACKEND -When libcurl is built to support multiple SSL backends, it selects a specific -backend at first use. If no selection is done by the program using libcurl, -this variable's selection is used. Setting a name that is not a built-in -alternative makes libcurl stay with the default. - -SSL backend names (case-insensitive): BearSSL, GnuTLS, mbedTLS, -nss, OpenSSL, rustls, Schannel, Secure-Transport, wolfSSL -.IP HOME -When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is -checked as the primary way to find the "current" home directory in which -the .netrc file is likely to exist. -.IP USERPROFILE -When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is -checked as the secondary way to find the "current" home directory (on Windows -only) in which the .netrc file is likely to exist. -.IP LOGNAME -User name to use when invoking the \fIntlm-wb\fP tool, if \fINTLMUSER\fP was -not set. -.IP NO_PROXY -This has the same functionality as the \fICURLOPT_NOPROXY(3)\fP option: it -gives libcurl a comma-separated list of host name patterns for which libcurl -should not use a proxy. -.IP NTLMUSER -User name to use when invoking the \fIntlm-wb\fP tool. -.IP SSLKEYLOGFILE -When set and libcurl runs with a SSL backend that supports this feature, -libcurl saves SSL secrets into the given file name. Using those SSL secrets, -other tools (such as Wireshark) can decrypt the SSL communication and -analyze/view the traffic. - -These secrets and this file might be sensitive. Users are advised to take -precautions so that they are not stolen or otherwise inadvertently revealed. -.IP USER -User name to use when invoking the \fIntlm-wb\fP tool, if \fINTLMUSER\fP and -\fILOGNAME\fP were not set. -.RE -.SH "Debug Variables" -Debug variables are intended for internal use and are documented in -\fIlibcurl-env-dbg(3)\fP. -.SH "SEE ALSO" -.BR libcurl-env-dbg (3) diff --git a/docs/libcurl/libcurl-env.md b/docs/libcurl/libcurl-env.md new file mode 100644 index 00000000000..410ed03f7bd --- /dev/null +++ b/docs/libcurl/libcurl-env.md @@ -0,0 +1,99 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-env +Section: 3 +Source: libcurl +See-also: + - libcurl-env-dbg (3) +--- + +# NAME + +libcurl-env - environment variables libcurl understands + +# DESCRIPTION + +libcurl reads and understands a set of environment variables that if set +controls and changes behaviors. This is the full list of variables to set and +description of what they do. Also note that curl, the command line tool, +supports a set of additional environment variables independently of this. + +## [scheme]_proxy + +When libcurl is given a URL to use in a transfer, it first extracts the scheme +part from the URL and checks if there is a given proxy set for that in its +corresponding environment variable. A URL like https://example.com makes +libcurl use the **http_proxy** variable, while a URL like ftp://example.com +uses the **ftp_proxy** variable. + +These proxy variables are also checked for in their uppercase versions, except +the **http_proxy** one which is only used lowercase. Note also that some +systems actually have a case insensitive handling of environment variables and +then of course **HTTP_PROXY** still works. + +An exception exists for the WebSocket **ws** and **wss** URL schemes, +where libcurl first checks **ws_proxy** or **wss_proxy** but if they are +not set, it will fall back and try the http and https versions instead if set. + +## ALL_PROXY + +This is a setting to set proxy for all URLs, independently of what scheme is +being used. Note that the scheme specific variables overrides this one if set. + +## CURL_SSL_BACKEND + +When libcurl is built to support multiple SSL backends, it selects a specific +backend at first use. If no selection is done by the program using libcurl, +this variable's selection is used. Setting a name that is not a built-in +alternative makes libcurl stay with the default. + +SSL backend names (case-insensitive): BearSSL, GnuTLS, mbedTLS, +nss, OpenSSL, rustls, Schannel, Secure-Transport, wolfSSL + +## HOME + +When the netrc feature is used (CURLOPT_NETRC(3)), this variable is +checked as the primary way to find the "current" home directory in which +the .netrc file is likely to exist. + +## USERPROFILE + +When the netrc feature is used (CURLOPT_NETRC(3)), this variable is +checked as the secondary way to find the "current" home directory (on Windows +only) in which the .netrc file is likely to exist. + +## LOGNAME + +User name to use when invoking the *ntlm-wb* tool, if *NTLMUSER* was +not set. + +## NO_PROXY + +This has the same functionality as the CURLOPT_NOPROXY(3) option: it +gives libcurl a comma-separated list of host name patterns for which libcurl +should not use a proxy. + +## NTLMUSER + +User name to use when invoking the *ntlm-wb* tool. + +## SSLKEYLOGFILE + +When set and libcurl runs with a SSL backend that supports this feature, +libcurl saves SSL secrets into the given file name. Using those SSL secrets, +other tools (such as Wireshark) can decrypt the SSL communication and +analyze/view the traffic. + +These secrets and this file might be sensitive. Users are advised to take +precautions so that they are not stolen or otherwise inadvertently revealed. + +## USER + +User name to use when invoking the *ntlm-wb* tool, if *NTLMUSER* and +*LOGNAME* were not set. + +# Debug Variables + +Debug variables are intended for internal use and are documented in +libcurl-env-dbg(3). diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.md similarity index 58% rename from docs/libcurl/libcurl-errors.3 rename to docs/libcurl/libcurl-errors.md index cd7bd9a3df3..a0466052659 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.md @@ -1,443 +1,757 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH libcurl-errors 3 "23 Nov 2021" "libcurl" "libcurl" -.SH NAME -libcurl-errors \- error codes in libcurl -.SH DESCRIPTION +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-errors +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_ERRORBUFFER (3) + - CURLOPT_VERBOSE (3) + - curl_easy_strerror (3) + - curl_multi_strerror (3) + - curl_share_strerror (3) + - curl_url_strerror (3) +--- + +# NAME + +libcurl-errors - error codes in libcurl + +# DESCRIPTION + This man page includes most, if not all, available error codes in libcurl. Why they occur and possibly what you can do to fix the problem are also included. -.SH "CURLcode" + +# CURLcode + Almost all "easy" interface functions return a CURLcode error code. No matter -what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER(3)\fP +what, using the curl_easy_setopt(3) option CURLOPT_ERRORBUFFER(3) is a good idea as it gives you a human readable error string that may offer more details about the cause of the error than just the error code. -\fIcurl_easy_strerror(3)\fP can be called to get an error string from a given +curl_easy_strerror(3) can be called to get an error string from a given CURLcode number. CURLcode is one of the following: -.IP "CURLE_OK (0)" + +## CURLE_OK (0) + All fine. Proceed as usual. -.IP "CURLE_UNSUPPORTED_PROTOCOL (1)" + +## CURLE_UNSUPPORTED_PROTOCOL (1) + The URL you passed to libcurl used a protocol that this libcurl does not support. The support might be a compile-time option that you did not use, it can be a misspelled protocol string or just a protocol libcurl has no code for. -.IP "CURLE_FAILED_INIT (2)" + +## CURLE_FAILED_INIT (2) + Early initialization code failed. This is likely to be an internal error or problem, or a resource problem where something fundamental could not get done at init time. -.IP "CURLE_URL_MALFORMAT (3)" + +## CURLE_URL_MALFORMAT (3) + The URL was not properly formatted. -.IP "CURLE_NOT_BUILT_IN (4)" + +## CURLE_NOT_BUILT_IN (4) + A requested feature, protocol or option was not found built-in in this libcurl due to a build-time decision. This means that a feature or option was not enabled or explicitly disabled when libcurl was built and in order to get it to function you have to get a rebuilt libcurl. -.IP "CURLE_COULDNT_RESOLVE_PROXY (5)" + +## CURLE_COULDNT_RESOLVE_PROXY (5) + Could not resolve proxy. The given proxy host could not be resolved. -.IP "CURLE_COULDNT_RESOLVE_HOST (6)" + +## CURLE_COULDNT_RESOLVE_HOST (6) + Could not resolve host. The given remote host was not resolved. -.IP "CURLE_COULDNT_CONNECT (7)" + +## CURLE_COULDNT_CONNECT (7) + Failed to connect() to host or proxy. -.IP "CURLE_WEIRD_SERVER_REPLY (8)" + +## CURLE_WEIRD_SERVER_REPLY (8) + The server sent data libcurl could not parse. This error code was known as -\fICURLE_FTP_WEIRD_SERVER_REPLY\fP before 7.51.0. -.IP "CURLE_REMOTE_ACCESS_DENIED (9)" +*CURLE_FTP_WEIRD_SERVER_REPLY* before 7.51.0. + +## CURLE_REMOTE_ACCESS_DENIED (9) + We were denied access to the resource given in the URL. For FTP, this occurs while trying to change to the remote directory. -.IP "CURLE_FTP_ACCEPT_FAILED (10)" + +## CURLE_FTP_ACCEPT_FAILED (10) + 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 "CURLE_FTP_WEIRD_PASS_REPLY (11)" + +## CURLE_FTP_WEIRD_PASS_REPLY (11) + After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. -.IP "CURLE_FTP_ACCEPT_TIMEOUT (12)" + +## CURLE_FTP_ACCEPT_TIMEOUT (12) + During an active FTP session while waiting for the server to connect, the -\fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP (or the internal default) timeout expired. -.IP "CURLE_FTP_WEIRD_PASV_REPLY (13)" +CURLOPT_ACCEPTTIMEOUT_MS(3) (or the internal default) timeout expired. + +## CURLE_FTP_WEIRD_PASV_REPLY (13) + libcurl failed to get a sensible result back from the server as a response to either a PASV or a EPSV command. The server is flawed. -.IP "CURLE_FTP_WEIRD_227_FORMAT (14)" + +## CURLE_FTP_WEIRD_227_FORMAT (14) + FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back. -.IP "CURLE_FTP_CANT_GET_HOST (15)" + +## CURLE_FTP_CANT_GET_HOST (15) + An internal failure to lookup the host used for the new connection. -.IP "CURLE_HTTP2 (16)" + +## CURLE_HTTP2 (16) + A problem was detected in the HTTP2 framing layer. This is somewhat generic and can be one out of several problems, see the error buffer for details. -.IP "CURLE_FTP_COULDNT_SET_TYPE (17)" + +## CURLE_FTP_COULDNT_SET_TYPE (17) + Received an error when trying to set the transfer mode to binary or ASCII. -.IP "CURLE_PARTIAL_FILE (18)" + +## CURLE_PARTIAL_FILE (18) + A file transfer was shorter or larger than expected. This happens when the server first reports an expected transfer size, and then delivers data that does not match the previously given size. -.IP "CURLE_FTP_COULDNT_RETR_FILE (19)" + +## CURLE_FTP_COULDNT_RETR_FILE (19) + This was either a weird reply to a 'RETR' command or a zero byte transfer complete. -.IP "Obsolete error (20)" + +## Obsolete error (20) + Not used in modern versions. -.IP "CURLE_QUOTE_ERROR (21)" + +## CURLE_QUOTE_ERROR (21) + When sending custom "QUOTE" commands to the remote server, one of the commands returned an error code that was 400 or higher (for FTP) or otherwise indicated unsuccessful completion of the command. -.IP "CURLE_HTTP_RETURNED_ERROR (22)" -This is returned if \fICURLOPT_FAILONERROR(3)\fP is set TRUE and the HTTP + +## CURLE_HTTP_RETURNED_ERROR (22) + +This is returned if CURLOPT_FAILONERROR(3) is set TRUE and the HTTP server returns an error code that is >= 400. -.IP "CURLE_WRITE_ERROR (23)" + +## CURLE_WRITE_ERROR (23) + An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback. -.IP "Obsolete error (24)" + +## Obsolete error (24) + Not used in modern versions. -.IP "CURLE_UPLOAD_FAILED (25)" + +## CURLE_UPLOAD_FAILED (25) + Failed starting the upload. For FTP, the server typically denied the STOR command. The error buffer usually contains the server's explanation for this. -.IP "CURLE_READ_ERROR (26)" + +## CURLE_READ_ERROR (26) + There was a problem reading a local file or an error returned by the read callback. -.IP "CURLE_OUT_OF_MEMORY (27)" + +## CURLE_OUT_OF_MEMORY (27) + A memory allocation request failed. This is serious badness and things are severely screwed up if this ever occurs. -.IP "CURLE_OPERATION_TIMEDOUT (28)" + +## CURLE_OPERATION_TIMEDOUT (28) + Operation timeout. The specified time-out period was reached according to the conditions. -.IP "Obsolete error (29)" + +## Obsolete error (29) + Not used in modern versions. -.IP "CURLE_FTP_PORT_FAILED (30)" + +## CURLE_FTP_PORT_FAILED (30) + The FTP PORT command returned error. This mostly happens when you have not specified a good enough address for libcurl to use. See -\fICURLOPT_FTPPORT(3)\fP. -.IP "CURLE_FTP_COULDNT_USE_REST (31)" +CURLOPT_FTPPORT(3). + +## CURLE_FTP_COULDNT_USE_REST (31) + The FTP REST command returned error. This should never happen if the server is sane. -.IP "Obsolete error (32)" + +## Obsolete error (32) + Not used in modern versions. -.IP "CURLE_RANGE_ERROR (33)" + +## CURLE_RANGE_ERROR (33) + The server does not support or accept range requests. -.IP "CURLE_HTTP_POST_ERROR (34)" + +## CURLE_HTTP_POST_ERROR (34) + This is an odd error that mainly occurs due to internal confusion. -.IP "CURLE_SSL_CONNECT_ERROR (35)" + +## CURLE_SSL_CONNECT_ERROR (35) + A problem occurred somewhere in the SSL/TLS handshake. You really want the error buffer and read the message there as it pinpoints the problem slightly more. Could be certificates (file formats, paths, permissions), passwords, and others. -.IP "CURLE_BAD_DOWNLOAD_RESUME (36)" + +## CURLE_BAD_DOWNLOAD_RESUME (36) + The download could not be resumed because the specified offset was out of the file boundary. -.IP "CURLE_FILE_COULDNT_READ_FILE (37)" + +## CURLE_FILE_COULDNT_READ_FILE (37) + A file given with FILE:// could not be opened. Most likely because the file path does not identify an existing file. Did you check file permissions? -.IP "CURLE_LDAP_CANNOT_BIND (38)" + +## CURLE_LDAP_CANNOT_BIND (38) + LDAP cannot bind. LDAP bind operation failed. -.IP "CURLE_LDAP_SEARCH_FAILED (39)" + +## CURLE_LDAP_SEARCH_FAILED (39) + LDAP search failed. -.IP "Obsolete error (40)" + +## Obsolete error (40) + Not used in modern versions. -.IP "CURLE_FUNCTION_NOT_FOUND (41)" + +## CURLE_FUNCTION_NOT_FOUND (41) + Function not found. A required zlib function was not found. -.IP "CURLE_ABORTED_BY_CALLBACK (42)" + +## CURLE_ABORTED_BY_CALLBACK (42) + Aborted by callback. A callback returned "abort" to libcurl. -.IP "CURLE_BAD_FUNCTION_ARGUMENT (43)" + +## CURLE_BAD_FUNCTION_ARGUMENT (43) + A function was called with a bad parameter. -.IP "Obsolete error (44)" + +## Obsolete error (44) + Not used in modern versions. -.IP "CURLE_INTERFACE_FAILED (45)" + +## CURLE_INTERFACE_FAILED (45) + Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections' source IP address with -\fICURLOPT_INTERFACE(3)\fP. -.IP "Obsolete error (46)" +CURLOPT_INTERFACE(3). + +## Obsolete error (46) + Not used in modern versions. -.IP "CURLE_TOO_MANY_REDIRECTS (47)" + +## CURLE_TOO_MANY_REDIRECTS (47) + Too many redirects. When following redirects, libcurl hit the maximum amount. -Set your limit with \fICURLOPT_MAXREDIRS(3)\fP. -.IP "CURLE_UNKNOWN_OPTION (48)" +Set your limit with CURLOPT_MAXREDIRS(3). + +## CURLE_UNKNOWN_OPTION (48) + An option passed to libcurl is not recognized/known. Refer to the appropriate documentation. This is most likely a problem in the program that uses libcurl. The error buffer might contain more specific information about which exact option it concerns. -.IP "CURLE_SETOPT_OPTION_SYNTAX (49)" + +## CURLE_SETOPT_OPTION_SYNTAX (49) + An option passed in to a setopt was wrongly formatted. See error message for details about what option. -.IP "Obsolete errors (50-51)" + +## Obsolete errors (50-51) + Not used in modern versions. -.IP "CURLE_GOT_NOTHING (52)" + +## CURLE_GOT_NOTHING (52) + Nothing was returned from the server, and under the circumstances, getting nothing is considered an error. -.IP "CURLE_SSL_ENGINE_NOTFOUND (53)" + +## CURLE_SSL_ENGINE_NOTFOUND (53) + The specified crypto engine was not found. -.IP "CURLE_SSL_ENGINE_SETFAILED (54)" + +## CURLE_SSL_ENGINE_SETFAILED (54) + Failed setting the selected SSL crypto engine as default. -.IP "CURLE_SEND_ERROR (55)" + +## CURLE_SEND_ERROR (55) + Failed sending network data. -.IP "CURLE_RECV_ERROR (56)" + +## CURLE_RECV_ERROR (56) + Failure with receiving network data. -.IP "Obsolete error (57)" + +## Obsolete error (57) + Not used in modern versions. -.IP "CURLE_SSL_CERTPROBLEM (58)" + +## CURLE_SSL_CERTPROBLEM (58) + problem with the local client certificate. -.IP "CURLE_SSL_CIPHER (59)" + +## CURLE_SSL_CIPHER (59) + Could not use specified cipher. -.IP "CURLE_PEER_FAILED_VERIFICATION (60)" + +## CURLE_PEER_FAILED_VERIFICATION (60) + The remote server's SSL certificate or SSH fingerprint was deemed not OK. This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its previous value was 51. -.IP "CURLE_BAD_CONTENT_ENCODING (61)" + +## CURLE_BAD_CONTENT_ENCODING (61) + Unrecognized transfer encoding. -.IP "Obsolete error (62)" + +## Obsolete error (62) + Not used in modern versions. -.IP "CURLE_FILESIZE_EXCEEDED (63)" + +## CURLE_FILESIZE_EXCEEDED (63) + Maximum file size exceeded. -.IP "CURLE_USE_SSL_FAILED (64)" + +## CURLE_USE_SSL_FAILED (64) + Requested FTP SSL level failed. -.IP "CURLE_SEND_FAIL_REWIND (65)" + +## CURLE_SEND_FAIL_REWIND (65) + When doing a send operation curl had to rewind the data to retransmit, but the rewinding operation failed. -.IP "CURLE_SSL_ENGINE_INITFAILED (66)" + +## CURLE_SSL_ENGINE_INITFAILED (66) + Initiating the SSL Engine failed. -.IP "CURLE_LOGIN_DENIED (67)" + +## CURLE_LOGIN_DENIED (67) + The remote server denied curl to login (Added in 7.13.1) -.IP "CURLE_TFTP_NOTFOUND (68)" + +## CURLE_TFTP_NOTFOUND (68) + File not found on TFTP server. -.IP "CURLE_TFTP_PERM (69)" + +## CURLE_TFTP_PERM (69) + Permission problem on TFTP server. -.IP "CURLE_REMOTE_DISK_FULL (70)" + +## CURLE_REMOTE_DISK_FULL (70) + Out of disk space on the server. -.IP "CURLE_TFTP_ILLEGAL (71)" + +## CURLE_TFTP_ILLEGAL (71) + Illegal TFTP operation. -.IP "CURLE_TFTP_UNKNOWNID (72)" + +## CURLE_TFTP_UNKNOWNID (72) + Unknown TFTP transfer ID. -.IP "CURLE_REMOTE_FILE_EXISTS (73)" + +## CURLE_REMOTE_FILE_EXISTS (73) + File already exists and is not overwritten. -.IP "CURLE_TFTP_NOSUCHUSER (74)" + +## CURLE_TFTP_NOSUCHUSER (74) + This error should never be returned by a properly functioning TFTP server. -.IP "Obsolete error (75-76)" + +## Obsolete error (75-76) + Not used in modern versions. -.IP "CURLE_SSL_CACERT_BADFILE (77)" + +## CURLE_SSL_CACERT_BADFILE (77) + Problem with reading the SSL CA cert (path? access rights?) -.IP "CURLE_REMOTE_FILE_NOT_FOUND (78)" + +## CURLE_REMOTE_FILE_NOT_FOUND (78) + The resource referenced in the URL does not exist. -.IP "CURLE_SSH (79)" + +## CURLE_SSH (79) + An unspecified error occurred during the SSH session. -.IP "CURLE_SSL_SHUTDOWN_FAILED (80)" + +## CURLE_SSL_SHUTDOWN_FAILED (80) + Failed to shut down the SSL connection. -.IP "CURLE_AGAIN (81)" + +## CURLE_AGAIN (81) + Socket is not ready for send/recv wait till it's ready and try again. This -return code is only returned from \fIcurl_easy_recv(3)\fP and -\fIcurl_easy_send(3)\fP (Added in 7.18.2) -.IP "CURLE_SSL_CRL_BADFILE (82)" +return code is only returned from curl_easy_recv(3) and +curl_easy_send(3) (Added in 7.18.2) + +## CURLE_SSL_CRL_BADFILE (82) + Failed to load CRL file (Added in 7.19.0) -.IP "CURLE_SSL_ISSUER_ERROR (83)" + +## CURLE_SSL_ISSUER_ERROR (83) + Issuer check failed (Added in 7.19.0) -.IP "CURLE_FTP_PRET_FAILED (84)" + +## CURLE_FTP_PRET_FAILED (84) + The FTP server does not understand the PRET command at all or does not support -the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST(3)\fP, a +the given argument. Be careful when using CURLOPT_CUSTOMREQUEST(3), a custom LIST command is sent with the PRET command before PASV as well. (Added in 7.20.0) -.IP "CURLE_RTSP_CSEQ_ERROR (85)" + +## CURLE_RTSP_CSEQ_ERROR (85) + Mismatch of RTSP CSeq numbers. -.IP "CURLE_RTSP_SESSION_ERROR (86)" + +## CURLE_RTSP_SESSION_ERROR (86) + Mismatch of RTSP Session Identifiers. -.IP "CURLE_FTP_BAD_FILE_LIST (87)" + +## CURLE_FTP_BAD_FILE_LIST (87) + Unable to parse FTP file list (during FTP wildcard downloading). -.IP "CURLE_CHUNK_FAILED (88)" + +## CURLE_CHUNK_FAILED (88) + Chunk callback reported error. -.IP "CURLE_NO_CONNECTION_AVAILABLE (89)" + +## CURLE_NO_CONNECTION_AVAILABLE (89) + (For internal use only, is never returned by libcurl) No connection available, the session is queued. (added in 7.30.0) -.IP "CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)" -Failed to match the pinned key specified with \fICURLOPT_PINNEDPUBLICKEY(3)\fP. -.IP "CURLE_SSL_INVALIDCERTSTATUS (91)" -Status returned failure when asked with \fICURLOPT_SSL_VERIFYSTATUS(3)\fP. -.IP "CURLE_HTTP2_STREAM (92)" + +## CURLE_SSL_PINNEDPUBKEYNOTMATCH (90) + +Failed to match the pinned key specified with CURLOPT_PINNEDPUBLICKEY(3). + +## CURLE_SSL_INVALIDCERTSTATUS (91) + +Status returned failure when asked with CURLOPT_SSL_VERIFYSTATUS(3). + +## CURLE_HTTP2_STREAM (92) + Stream error in the HTTP/2 framing layer. -.IP "CURLE_RECURSIVE_API_CALL (93)" + +## CURLE_RECURSIVE_API_CALL (93) + An API function was called from inside a callback. -.IP "CURLE_AUTH_ERROR (94)" + +## CURLE_AUTH_ERROR (94) + An authentication function returned an error. -.IP "CURLE_HTTP3 (95)" + +## CURLE_HTTP3 (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 buffer for details. -.IP "CURLE_QUIC_CONNECT_ERROR (96)" + +## CURLE_QUIC_CONNECT_ERROR (96) + QUIC connection error. This error may be caused by an SSL library error. QUIC is the protocol used for HTTP/3 transfers. -.IP "CURLE_PROXY (97)" -Proxy handshake error. \fICURLINFO_PROXY_ERROR(3)\fP provides extra details on + +## CURLE_PROXY (97) + +Proxy handshake error. CURLINFO_PROXY_ERROR(3) provides extra details on the specific problem. -.IP "CURLE_SSL_CLIENTCERT (98)" + +## CURLE_SSL_CLIENTCERT (98) + SSL Client Certificate required. -.IP "CURLE_UNRECOVERABLE_POLL (99)" + +## CURLE_UNRECOVERABLE_POLL (99) + An internal call to poll() or select() returned error that is not recoverable. -.IP "CURLE_TOO_LARGE (100)" + +## CURLE_TOO_LARGE (100) + A value or data field grew larger than allowed. -.SH "CURLMcode" + +# CURLMcode + This is the generic return code used by functions in the libcurl multi -interface. Also consider \fIcurl_multi_strerror(3)\fP. -.IP "CURLM_CALL_MULTI_PERFORM (-1)" +interface. Also consider curl_multi_strerror(3). + +## CURLM_CALL_MULTI_PERFORM (-1) + This is not really an error. It means you should call -\fIcurl_multi_perform(3)\fP again without doing select() or similar in +curl_multi_perform(3) again without doing select() or similar in between. Before version 7.20.0 (released on February 9 2010) this could be returned by -\fIcurl_multi_perform(3)\fP, but in later versions this return code is never +curl_multi_perform(3), but in later versions this return code is never used. -.IP "CURLM_OK (0)" + +## CURLM_OK (0) + Things are fine. -.IP "CURLM_BAD_HANDLE (1)" -The passed-in handle is not a valid \fICURLM\fP handle. -.IP "CURLM_BAD_EASY_HANDLE (2)" + +## CURLM_BAD_HANDLE (1) + +The passed-in handle is not a valid *CURLM* handle. + +## CURLM_BAD_EASY_HANDLE (2) + An easy handle was not good/valid. It could mean that it is not an easy handle at all, or possibly that the handle already is in use by this or another multi handle. -.IP "CURLM_OUT_OF_MEMORY (3)" + +## CURLM_OUT_OF_MEMORY (3) + You are doomed. -.IP "CURLM_INTERNAL_ERROR (4)" + +## CURLM_INTERNAL_ERROR (4) + This can only be returned if libcurl bugs. Please report it to us! -.IP "CURLM_BAD_SOCKET (5)" + +## CURLM_BAD_SOCKET (5) + The passed-in socket is not a valid one that libcurl already knows about. (Added in 7.15.4) -.IP "CURLM_UNKNOWN_OPTION (6)" + +## CURLM_UNKNOWN_OPTION (6) + curl_multi_setopt() with unsupported option (Added in 7.15.4) -.IP "CURLM_ADDED_ALREADY (7)" + +## CURLM_ADDED_ALREADY (7) + An easy handle already added to a multi handle was attempted to get added a second time. (Added in 7.32.1) -.IP "CURLM_RECURSIVE_API_CALL (8)" + +## CURLM_RECURSIVE_API_CALL (8) + An API function was called from inside a callback. -.IP "CURLM_WAKEUP_FAILURE (9)" + +## CURLM_WAKEUP_FAILURE (9) + Wake up is unavailable or failed. -.IP "CURLM_BAD_FUNCTION_ARGUMENT (10)" + +## CURLM_BAD_FUNCTION_ARGUMENT (10) + A function was called with a bad parameter. -.IP "CURLM_ABORTED_BY_CALLBACK (11)" + +## CURLM_ABORTED_BY_CALLBACK (11) + A multi handle callback returned error. -.IP "CURLM_UNRECOVERABLE_POLL (12)" + +## CURLM_UNRECOVERABLE_POLL (12) + An internal call to poll() or select() returned error that is not recoverable. -.SH "CURLSHcode" -The "share" interface returns a \fBCURLSHcode\fP to indicate when an error has -occurred. Also consider \fIcurl_share_strerror(3)\fP. -.IP "CURLSHE_OK (0)" + +# CURLSHcode + +The "share" interface returns a **CURLSHcode** to indicate when an error has +occurred. Also consider curl_share_strerror(3). + +## CURLSHE_OK (0) + All fine. Proceed as usual. -.IP "CURLSHE_BAD_OPTION (1)" + +## CURLSHE_BAD_OPTION (1) + An invalid option was passed to the function. -.IP "CURLSHE_IN_USE (2)" + +## CURLSHE_IN_USE (2) + The share object is currently in use. -.IP "CURLSHE_INVALID (3)" + +## CURLSHE_INVALID (3) + An invalid share object was passed to the function. -.IP "CURLSHE_NOMEM (4)" + +## CURLSHE_NOMEM (4) + Not enough memory was available. (Added in 7.12.0) -.IP "CURLSHE_NOT_BUILT_IN (5)" + +## CURLSHE_NOT_BUILT_IN (5) + The requested sharing could not be done because the library you use do not have that particular feature enabled. (Added in 7.23.0) -.SH "CURLUcode" -The URL interface returns a \fICURLUcode\fP to indicate when an error has -occurred. Also consider \fIcurl_url_strerror(3)\fP. -.IP "CURLUE_OK (0)" + +# CURLUcode + +The URL interface returns a *CURLUcode* to indicate when an error has +occurred. Also consider curl_url_strerror(3). + +## CURLUE_OK (0) + All fine. Proceed as usual. -.IP "CURLUE_BAD_HANDLE (1)" + +## CURLUE_BAD_HANDLE (1) + An invalid URL handle was passed as argument. -.IP "CURLUE_BAD_PARTPOINTER (2)" + +## CURLUE_BAD_PARTPOINTER (2) + An invalid 'part' argument was passed as argument. -.IP "CURLUE_MALFORMED_INPUT (3)" + +## CURLUE_MALFORMED_INPUT (3) + A malformed input was passed to a URL API function. -.IP "CURLUE_BAD_PORT_NUMBER (4)" + +## CURLUE_BAD_PORT_NUMBER (4) + The port number was not a decimal number between 0 and 65535. -.IP "CURLUE_UNSUPPORTED_SCHEME (5)" + +## CURLUE_UNSUPPORTED_SCHEME (5) + This libcurl build does not support the given URL scheme. -.IP "CURLUE_URLDECODE (6)" + +## CURLUE_URLDECODE (6) + URL decode error, most likely because of rubbish in the input. -.IP "CURLUE_OUT_OF_MEMORY (7)" + +## CURLUE_OUT_OF_MEMORY (7) + A memory function failed. -.IP "CURLUE_USER_NOT_ALLOWED (8)" + +## CURLUE_USER_NOT_ALLOWED (8) + Credentials was passed in the URL when prohibited. -.IP "CURLUE_UNKNOWN_PART (9)" + +## CURLUE_UNKNOWN_PART (9) + An unknown part ID was passed to a URL API function. -.IP "CURLUE_NO_SCHEME (10)" + +## CURLUE_NO_SCHEME (10) + There is no scheme part in the URL. -.IP "CURLUE_NO_USER (11)" + +## CURLUE_NO_USER (11) + There is no user part in the URL. -.IP "CURLUE_NO_PASSWORD (12)" + +## CURLUE_NO_PASSWORD (12) + There is no password part in the URL. -.IP "CURLUE_NO_OPTIONS (13)" + +## CURLUE_NO_OPTIONS (13) + There is no options part in the URL. -.IP "CURLUE_NO_HOST (14)" + +## CURLUE_NO_HOST (14) + There is no host part in the URL. -.IP "CURLUE_NO_PORT (15)" + +## CURLUE_NO_PORT (15) + There is no port part in the URL. -.IP "CURLUE_NO_QUERY (16)" + +## CURLUE_NO_QUERY (16) + There is no query part in the URL. -.IP "CURLUE_NO_FRAGMENT (17)" + +## CURLUE_NO_FRAGMENT (17) + There is no fragment part in the URL. -.IP "CURLUE_NO_ZONEID (18)" + +## CURLUE_NO_ZONEID (18) + There is no zone id set in the URL. -.IP "CURLUE_BAD_FILE_URL (19)" + +## CURLUE_BAD_FILE_URL (19) + The file:// URL is invalid. -.IP "CURLUE_BAD_FRAGMENT (20)" + +## CURLUE_BAD_FRAGMENT (20) + The fragment part of the URL contained bad or invalid characters. -.IP "CURLUE_BAD_HOSTNAME (21)" + +## CURLUE_BAD_HOSTNAME (21) + The hostname contained bad or invalid characters. -.IP "CURLUE_BAD_IPV6 (22)" + +## CURLUE_BAD_IPV6 (22) + The IPv6 address hostname contained bad or invalid characters. -.IP "CURLUE_BAD_LOGIN (23)" + +## CURLUE_BAD_LOGIN (23) + The login part of the URL contained bad or invalid characters. -.IP "CURLUE_BAD_PASSWORD (24)" + +## CURLUE_BAD_PASSWORD (24) + The password part of the URL contained bad or invalid characters. -.IP "CURLUE_BAD_PATH (25)" + +## CURLUE_BAD_PATH (25) + The path part of the URL contained bad or invalid characters. -.IP "CURLUE_BAD_QUERY (26)" + +## CURLUE_BAD_QUERY (26) + The query part of the URL contained bad or invalid characters. -.IP "CURLUE_BAD_SCHEME (27)" + +## CURLUE_BAD_SCHEME (27) + The scheme part of the URL contained bad or invalid characters. -.IP "CURLUE_BAD_SLASHES (28)" + +## CURLUE_BAD_SLASHES (28) + The URL contained an invalid number of slashes. -.IP "CURLUE_BAD_USER (29)" + +## CURLUE_BAD_USER (29) + The user part of the URL contained bad or invalid characters. -.IP "CURLUE_LACKS_IDN (30)" + +## CURLUE_LACKS_IDN (30) + libcurl lacks IDN support. -.IP "CURLUE_TOO_LARGE (31)" + +## CURLUE_TOO_LARGE (31) + A value or data field is larger than allowed. -.SH "CURLHcode" -The header interface returns a \fICURLHcode\fP to indicate when an error has + +# CURLHcode + +The header interface returns a *CURLHcode* to indicate when an error has occurred. -.IP "CURLHE_OK (0)" + +## CURLHE_OK (0) + All fine. Proceed as usual. -.IP "CURLHE_BADINDEX (1)" + +## CURLHE_BADINDEX (1) + There is no header with the requested index. -.IP "CURLHE_MISSING (2)" + +## CURLHE_MISSING (2) + No such header exists. -.IP "CURLHE_NOHEADERS (3)" + +## CURLHE_NOHEADERS (3) + No headers at all have been recorded. -.IP "CURLHE_NOREQUEST (4)" + +## CURLHE_NOREQUEST (4) + There was no such request number. -.IP "CURLHE_OUT_OF_MEMORY (5)" + +## CURLHE_OUT_OF_MEMORY (5) + Out of resources -.IP "CURLHE_BAD_ARGUMENT (6)" + +## CURLHE_BAD_ARGUMENT (6) + One or more of the given arguments are bad. -.IP "CURLHE_NOT_BUILT_IN (7)" + +## CURLHE_NOT_BUILT_IN (7) + HTTP support or the header API has been disabled in the build. -.SH "SEE ALSO" -.BR curl_easy_strerror (3), -.BR curl_multi_strerror (3), -.BR curl_share_strerror (3), -.BR curl_url_strerror (3), -.BR CURLOPT_ERRORBUFFER (3), -.BR CURLOPT_VERBOSE (3), -.BR CURLOPT_DEBUGFUNCTION (3) diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.md similarity index 60% rename from docs/libcurl/libcurl-multi.3 rename to docs/libcurl/libcurl-multi.md index 8bd89318521..3acd13ea638 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.md @@ -1,39 +1,31 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH libcurl-multi 3 "19 Sep 2014" "libcurl" "libcurl" -.SH NAME -libcurl-multi \- how to use the multi interface -.SH DESCRIPTION +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-multi +Section: 3 +Source: libcurl +See-also: + - libcurl (3) + - libcurl-easy (3) + - libcurl-errors (3) +--- + +# NAME + +libcurl-multi - how to use the multi interface + +# DESCRIPTION + This is an overview on how to use the libcurl multi interface in your C programs. There are specific man pages for each function mentioned in -here. There is also the \fIlibcurl-tutorial(3)\fP man page for a complete -tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page +here. There is also the libcurl-tutorial(3) man page for a complete +tutorial to programming with libcurl and the libcurl-easy(3) man page for an overview of the libcurl easy interface. All functions in the multi interface are prefixed with curl_multi. -.SH "OBJECTIVES" + +# OBJECTIVES + The multi interface offers several abilities that the easy interface does not. They are mainly: @@ -48,15 +40,17 @@ curl's file descriptors simultaneously. 4. Enable event-based handling and scaling transfers up to and beyond thousands of parallel connections. -.SH "ONE MULTI HANDLE MANY EASY HANDLES" + +# ONE MULTI HANDLE MANY EASY HANDLES + To use the multi interface, you must first create a 'multi handle' with -\fIcurl_multi_init(3)\fP. This handle is then used as input to all further +curl_multi_init(3). This handle is then used as input to all further curl_multi_* functions. With a multi handle and the multi interface you can do several simultaneous transfers in parallel. Each single transfer is built up around an easy handle. You create all the easy handles you need, and setup the appropriate -options for each easy handle using \fIcurl_easy_setopt(3)\fP. +options for each easy handle using curl_easy_setopt(3). There are two flavors of the multi interface, the select() oriented one and the event based one we call multi_socket. You benefit from reading through the @@ -64,21 +58,21 @@ description of both versions to fully understand how they work and differentiate. We start out with the select() oriented version. When an easy handle is setup and ready for transfer, then instead of using -\fIcurl_easy_perform(3)\fP like when using the easy interface for transfers, +curl_easy_perform(3) like when using the easy interface for transfers, you should add the easy handle to the multi handle with -\fIcurl_multi_add_handle(3)\fP. You can add more easy handles to a multi +curl_multi_add_handle(3). You can add more easy handles to a multi handle at any point, even if other transfers are already running. Should you change your mind, the easy handle is again removed from the multi -stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi +stack using curl_multi_remove_handle(3). Once removed from the multi handle, you can again use other easy interface functions like -\fIcurl_easy_perform(3)\fP on the handle or whatever you think is +curl_easy_perform(3) on the handle or whatever you think is necessary. You can remove handles at any point during transfers. Adding the easy handle to the multi handle does not start the transfer. Remember that one of the main ideas with this interface is to let your application drive. You drive the transfers by invoking -\fIcurl_multi_perform(3)\fP. libcurl then transfers data if there is anything +curl_multi_perform(3). libcurl then transfers data if there is anything available to transfer. It uses the callbacks and everything else you have setup in the individual easy handles. It transfers data on all current transfers in the multi stack that are ready to transfer anything. It may be @@ -87,22 +81,22 @@ to the calling application. Your application extracts info from libcurl about when it would like to get invoked to transfer data or do other work. The most convenient way is to use -\fIcurl_multi_poll(3)\fP that helps you wait until the application should call +curl_multi_poll(3) that helps you wait until the application should call libcurl again. The older API to accomplish the same thing is -\fIcurl_multi_fdset(3)\fP that extracts \fIfd_sets\fP from libcurl to use in +curl_multi_fdset(3) that extracts *fd_sets* from libcurl to use in select() or poll() calls in order to get to know when the transfers in the multi stack might need attention. Both these APIs allow for your program to wait for input on your own private file descriptors at the same time. -\fIcurl_multi_timeout(3)\fP also helps you with providing a suitable timeout +curl_multi_timeout(3) also helps you with providing a suitable timeout period for your select() calls. -\fIcurl_multi_perform(3)\fP stores the number of still running transfers in +curl_multi_perform(3) stores the number of still running transfers in one of its input arguments, and by reading that you can figure out when all the transfers in the multi handles are done. 'done' does not mean successful. One or more of the transfers may have failed. To get information about completed transfers, to figure out success or not and -similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a +similar, curl_multi_info_read(3) should be called. It can return a message about a current or previous transfer. Repeated invokes of the function get more messages until the message queue is empty. The information you receive there includes an easy handle pointer which you may use to identify @@ -110,31 +104,33 @@ which easy handle the information regards. When a single transfer is completed, the easy handle is still left added to the multi stack. You need to first remove the easy handle with -\fIcurl_multi_remove_handle(3)\fP and then close it with -\fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again -with \fIcurl_multi_add_handle(3)\fP to start another transfer. +curl_multi_remove_handle(3) and then close it with +curl_easy_cleanup(3), or possibly set new options to it and add it again +with curl_multi_add_handle(3) to start another transfer. When all transfers in the multi stack are done, close the multi handle with -\fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP -invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle +curl_multi_cleanup(3). Be careful and please note that you **MUST** +invoke separate curl_easy_cleanup(3) calls for every single easy handle to clean them up properly. If you want to reuse an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it again (possibly after having altered some options at your own choice). -.SH "MULTI_SOCKET" -\fIcurl_multi_socket_action(3)\fP function offers a way for applications to + +# MULTI_SOCKET + +curl_multi_socket_action(3) function offers a way for applications to not only avoid being forced to use select(), but it also offers a much more high-performance API that makes a significant difference for applications using large numbers of simultaneous connections. -\fIcurl_multi_socket_action(3)\fP is then used instead of -\fIcurl_multi_perform(3)\fP. +curl_multi_socket_action(3) is then used instead of +curl_multi_perform(3). When using this API, you add easy handles to the multi handle just as with the normal multi interface. Then you also set two callbacks with the -\fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options -to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl +CURLMOPT_SOCKETFUNCTION(3) and CURLMOPT_TIMERFUNCTION(3) options +to curl_multi_setopt(3). They are two callback functions that libcurl calls with information about what sockets to wait for, and for what activity, and what the current timeout time is - if that expires libcurl should be notified. @@ -144,14 +140,14 @@ sockets libcurl is currently using and for what activities (read and/or write) on those sockets your application is expected to wait for. Your application must make sure to receive all sockets informed about in the -\fICURLMOPT_SOCKETFUNCTION(3)\fP callback and make sure it reacts on the given +CURLMOPT_SOCKETFUNCTION(3) callback and make sure it reacts on the given activity on them. When a socket has the given activity, you call -\fIcurl_multi_socket_action(3)\fP specifying which socket and action there +curl_multi_socket_action(3) specifying which socket and action there are. -The \fICURLMOPT_TIMERFUNCTION(3)\fP callback is called to set a timeout. When +The CURLMOPT_TIMERFUNCTION(3) callback is called to set a timeout. When that timeout expires, your application should call the -\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout. +curl_multi_socket_action(3) function saying it was due to a timeout. This API is typically used with an event-driven underlying functionality (like libevent, libev, kqueue, epoll or similar) with which the application @@ -160,25 +156,23 @@ better scale upward and beyond thousands of simultaneous transfers without losing performance. When you have added your initial set of handles, you call -\fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the -\fIsockfd\fP argument, and you get callbacks invoked that set you up and you -then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when you +curl_multi_socket_action(3) with CURL_SOCKET_TIMEOUT set in the +*sockfd* argument, and you get callbacks invoked that set you up and you +then continue to call curl_multi_socket_action(3) accordingly when you get activity on the sockets you have been asked to wait on, or if the timeout timer expires. -You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has +You can poll curl_multi_info_read(3) to see if any transfer has completed, as it then has a message saying so. -.SH "BLOCKING" + +# BLOCKING + A few areas in the code are still using blocking code, even when used from the multi interface. While we certainly want and intend for these to get fixed in the future, you should be aware of the following current restrictions: -.nf +~~~c - Name resolves unless the c-ares or threaded-resolver backends are used - file:// transfers - TELNET transfers -.fi -.SH "SEE ALSO" -.BR libcurl-errors (3), -.BR libcurl-easy (3), -.BR libcurl (3) +~~~ diff --git a/docs/libcurl/libcurl-security.3 b/docs/libcurl/libcurl-security.md similarity index 75% rename from docs/libcurl/libcurl-security.3 rename to docs/libcurl/libcurl-security.md index 4a0d76d66a8..88c230f49ee 100644 --- a/docs/libcurl/libcurl-security.3 +++ b/docs/libcurl/libcurl-security.md @@ -1,31 +1,19 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH libcurl-security 3 "13 Feb 2018" "libcurl" "libcurl" -.SH NAME -libcurl-security \- security considerations when using libcurl -.SH "Security" +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-security +Section: 3 +Source: libcurl +See-also: + - libcurl-thread (3) +--- + +# NAME + +libcurl-security - security considerations when using libcurl + +# Security + The libcurl project takes security seriously. The library is written with caution and precautions are taken to mitigate many kinds of risks encountered while operating with potentially malicious servers on the Internet. It is a @@ -42,17 +30,21 @@ classes of attacks that robust applications should consider. The Common Weakness Enumeration project at https://cwe.mitre.org/ is a good reference for many of these and similar types of weaknesses of which application writers should be aware. -.SH "Command Lines" + +# Command Lines + If you use a command line tool (such as curl) that uses libcurl, and you give options to the tool on the command line those options can get read by other -users of your system when they use \fIps\fP or other tools to list currently +users of your system when they use *ps* or other tools to list currently running processes. To avoid these problems, never feed sensitive things to programs using command -line options. Write them to a protected file and use the \-K option to avoid +line options. Write them to a protected file and use the -K option to avoid this. -.SH ".netrc" -\&.netrc is a pretty handy file/feature that allows you to login quickly and + +# .netrc + +&.netrc is a pretty handy file/feature that allows you to login quickly and automatically to frequently visited sites. The file contains passwords in clear text and is a real security risk. In some cases, your .netrc is also stored in a home directory that is NFS mounted or used on another network @@ -64,7 +56,9 @@ URL might then be possible to pass on passwords. To avoid these problems, do not use .netrc files and never store passwords in plain text anywhere. -.SH "Clear Text Passwords" + +# Clear Text Passwords + Many of the protocols libcurl supports send name and password unencrypted as clear text (HTTP Basic authentication, FTP, TELNET etc). It is easy for anyone on your network or a network nearby yours to just fire up a network analyzer @@ -76,7 +70,9 @@ To avoid this problem, use an authentication mechanism or other protocol that does not let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or NTLM authentication. Or even better: use authenticated protocols that protect the entire connection and everything sent over it. -.SH "Unauthenticated Connections" + +# Unauthenticated Connections + Protocols that do not have any form of cryptographic authentication cannot with any certainty know that they communicate with the right remote server. @@ -90,12 +86,18 @@ before it reaches the intended server. If it even reaches the intended server at all. Remedies: -.IP "Restrict operations to authenticated transfers" + +## Restrict operations to authenticated transfers + Use authenticated protocols protected with HTTPS or SSH. -.IP "Make sure the server's certificate etc is verified" + +## Make sure the server's certificate etc is verified + Never ever switch off certificate verification. -.SH "Redirects" -The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP + +# Redirects + +The CURLOPT_FOLLOWLOCATION(3) option automatically follows HTTP redirects sent by a remote server. These redirects can refer to any kind of URL, not just HTTP. libcurl restricts the protocols allowed to be used in redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are @@ -105,64 +107,68 @@ A redirect to a file: URL would cause the libcurl to read (or write) arbitrary files from the local filesystem. If the application returns the data back to the user (as would happen in some kinds of CGI scripts), an attacker could leverage this to read otherwise forbidden data (e.g. -\fBfile://localhost/etc/passwd\fP). +**file://localhost/etc/passwd**). If authentication credentials are stored in the ~/.netrc file, or Kerberos is in use, any other URL type (not just file:) that requires authentication is -also at risk. A redirect such as ftp://some-internal-server/private-file would +also at risk. A redirect such as **ftp://some-internal-server/private-file** would then return data even when the server is password protected. In the same way, if an unencrypted SSH private key has been configured for the user running the libcurl application, SCP: or SFTP: URLs could access password or private-key protected resources, -e.g. \fBsftp://user@some-internal-server/etc/passwd\fP +e.g. **sftp://user@some-internal-server/etc/passwd** -The \fICURLOPT_REDIR_PROTOCOLS(3)\fP and \fICURLOPT_NETRC(3)\fP options can be +The CURLOPT_REDIR_PROTOCOLS(3) and CURLOPT_NETRC(3) options can be used to mitigate against this kind of attack. A redirect can also specify a location available only on the machine running libcurl, including servers hidden behind a firewall from the attacker. -e.g. http://127.0.0.1/ or http://intranet/delete-stuff.cgi?delete=all or -tftp://bootp-server/pc-config-data +E.g. **http://127.0.0.1/** or **http://intranet/delete-stuff.cgi?delete=all** or +**tftp://bootp-server/pc-config-data** Applications can mitigate against this by disabling -\fICURLOPT_FOLLOWLOCATION(3)\fP and handling redirects itself, sanitizing URLs -as necessary. Alternately, an app could leave \fICURLOPT_FOLLOWLOCATION(3)\fP -enabled but set \fICURLOPT_REDIR_PROTOCOLS(3)\fP and install a -\fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP callback +CURLOPT_FOLLOWLOCATION(3) and handling redirects itself, sanitizing URLs +as necessary. Alternately, an app could leave CURLOPT_FOLLOWLOCATION(3) +enabled but set CURLOPT_REDIR_PROTOCOLS(3) and install a +CURLOPT_OPENSOCKETFUNCTION(3) or CURLOPT_PREREQFUNCTION(3) callback function in which addresses are sanitized before use. -.SH "CRLF in Headers" + +# CRLF in Headers + For all options in libcurl which specify headers, including but not limited to -\fICURLOPT_HTTPHEADER(3)\fP, \fICURLOPT_PROXYHEADER(3)\fP, -\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_REFERER(3)\fP -and \fICURLOPT_RANGE(3)\fP, libcurl sends the headers as-is and does not apply +CURLOPT_HTTPHEADER(3), CURLOPT_PROXYHEADER(3), +CURLOPT_COOKIE(3), CURLOPT_USERAGENT(3), CURLOPT_REFERER(3) +and CURLOPT_RANGE(3), libcurl sends the headers as-is and does not apply any special sanitation or normalization to them. If you allow untrusted user input into these options without sanitizing CRLF sequences in them, someone malicious may be able to modify the request in a way you did not intend such as injecting new headers. -.SH "Local Resources" + +# Local Resources + A user who can control the DNS server of a domain being passed in within a URL can change the address of the host to a local, private address which a -server-side libcurl-using application could then use. e.g. the innocuous URL -\fBhttp://fuzzybunnies.example.com/\fP could actually resolve to the IP +server-side libcurl-using application could then use. E.g. the innocuous URL +**http://fuzzybunnies.example.com/** could actually resolve to the IP address of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Applications can mitigate against this by setting a -\fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP and +CURLOPT_OPENSOCKETFUNCTION(3) or CURLOPT_PREREQFUNCTION(3) and checking the address before a connection. All the malicious scenarios regarding redirected URLs apply just as well to non-redirected URLs, if the user is allowed to specify an arbitrary URL that could point to a private resource. For example, a web app providing a -translation service might happily translate \fBfile://localhost/etc/passwd\fP +translation service might happily translate **file://localhost/etc/passwd** and display the result. Applications can mitigate against this with the -\fICURLOPT_PROTOCOLS(3)\fP option as well as by similar mitigation techniques +CURLOPT_PROTOCOLS(3) option as well as by similar mitigation techniques for redirections. A malicious FTP server could in response to the PASV command return an IP address and port number for a server local to the app running libcurl but behind a firewall. Applications can mitigate against this by using the -\fICURLOPT_FTP_SKIP_PASV_IP(3)\fP option or \fICURLOPT_FTPPORT(3)\fP. +CURLOPT_FTP_SKIP_PASV_IP(3) option or CURLOPT_FTPPORT(3). Local servers sometimes assume local access comes from friends and trusted users. An application that expects https://example.com/file_to_read that and @@ -173,61 +179,75 @@ Allowing your application to connect to local hosts, be it the same machine that runs the application or a machine on the same local network, might be possible to exploit by an attacker who then perhaps can "port-scan" the particular hosts - depending on how the application and servers acts. -.SH "IPv4 Addresses" + +# IPv4 Addresses + Some users might be tempted to filter access to local resources or similar based on numerical IPv4 addresses used in URLs. This is a bad and error-prone idea because of the many different ways a numerical IPv4 address can be specified and libcurl accepts: one to four dot-separated fields using one of or a mix of decimal, octal or hexadecimal encoding. -.SH "IPv6 Addresses" + +# IPv6 Addresses + libcurl handles IPv6 addresses transparently and just as easily as IPv4 addresses. That means that a sanitizing function that filters out addresses -like 127.0.0.1 is not sufficient - the equivalent IPv6 addresses \fB::1\fP, -\fB::\fP, \fB0:00::0:1\fP, \fB::127.0.0.1\fP and \fB::ffff:7f00:1\fP supplied +like 127.0.0.1 is not sufficient - the equivalent IPv6 addresses **::1**, +**::**, **0:00::0:1**, **::127.0.0.1** and **::ffff:7f00:1** supplied somehow by an attacker would all bypass a naive filter and could allow access to undesired local resources. IPv6 also has special address blocks like link-local and site-local that generally should not be accessed by a server-side libcurl-using application. A poorly configured firewall installed in a data center, organization or server may also be configured to limit IPv4 connections but leave IPv6 connections wide open. In some cases, setting -\fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 can be used to limit resolved +CURLOPT_IPRESOLVE(3) to CURL_IPRESOLVE_V4 can be used to limit resolved addresses to IPv4 only and bypass these issues. -.SH Uploads + +# Uploads + When uploading, a redirect can cause a local (or remote) file to be overwritten. Applications must not allow any unsanitized URL to be passed in -for uploads. Also, \fICURLOPT_FOLLOWLOCATION(3)\fP should not be used on +for uploads. Also, CURLOPT_FOLLOWLOCATION(3) should not be used on uploads. Instead, the applications should consider handling redirects itself, sanitizing each URL first. -.SH Authentication -Use of \fICURLOPT_UNRESTRICTED_AUTH(3)\fP could cause authentication + +# Authentication + +Use of CURLOPT_UNRESTRICTED_AUTH(3) could cause authentication information to be sent to an unknown second server. Applications can mitigate -against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling +against this by disabling CURLOPT_FOLLOWLOCATION(3) and handling redirects itself, sanitizing where necessary. -Use of the CURLAUTH_ANY option to \fICURLOPT_HTTPAUTH(3)\fP could result in +Use of the CURLAUTH_ANY option to CURLOPT_HTTPAUTH(3) could result in user name and password being sent in clear text to an HTTP server. Instead, use CURLAUTH_ANYSAFE which ensures that the password is encrypted over the network, or else fail the request. -Use of the CURLUSESSL_TRY option to \fICURLOPT_USE_SSL(3)\fP could result in +Use of the CURLUSESSL_TRY option to CURLOPT_USE_SSL(3) could result in user name and password being sent in clear text to an FTP server. Instead, use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else fail the request. -.SH Cookies + +# Cookies + If cookies are enabled and cached, then a user could craft a URL which performs some malicious action to a site whose authentication is already -stored in a cookie. e.g. http://mail.example.com/delete-stuff.cgi?delete=all -Applications can mitigate against this by disabling cookies or clearing them -between requests. -.SH "Dangerous SCP URLs" +stored in a cookie. E.g. +**http://mail.example.com/delete-stuff.cgi?delete=all** Applications can +mitigate against this by disabling cookies or clearing them between requests. + +# Dangerous SCP URLs + SCP URLs can contain raw commands within the scp: URL, which is a side effect -of how the SCP protocol is designed. e.g. -.nf +of how the SCP protocol is designed. E.g. +~~~ scp://user:pass@host/a;date >/tmp/test; -.fi +~~~ Applications must not allow unsanitized SCP: URLs to be passed in for downloads. -.SH "file://" + +# file:// + By default curl and libcurl support file:// URLs. Such a URL is always an access, or attempted access, to a local resource. If your application wants to avoid that, keep control of what URLs to use and/or prevent curl/libcurl from @@ -235,7 +255,8 @@ using the protocol. By default, libcurl prohibits redirects to file:// URLs. -.SH "Warning: file:// on Windows" +# Warning: file:// on Windows + The Windows operating system tries automatically, and without any way for applications to disable it, to establish a connection to another host over the network and access it (over SMB or other protocols), if only the correct file @@ -260,7 +281,9 @@ If you use curl or libcurl on Windows (any version), disable the use of the FILE protocol in curl or be prepared that accesses to a range of "magic paths" potentially make your system access other hosts on your network. curl cannot protect you against this. -.SH "What if the user can set the URL" + +# What if the user can set the URL + Applications may find it tempting to let users set the URL that it can work on. That is probably fine, but opens up for mischief and trickery that you as an application author may want to address or take precautions against. @@ -278,14 +301,22 @@ particular scheme in the URL but point to a server doing a different protocol on a non-standard port. Remedies: -.IP "Use --proto" -curl command lines can use \fI--proto\fP to limit what URL schemes it accepts -.IP "Use CURLOPT_PROTOCOLS" -libcurl programs can use \fICURLOPT_PROTOCOLS(3)\fP to limit what URL schemes it accepts -.IP "consider not allowing the user to set the full URL" + +## Use --proto + +curl command lines can use *--proto* to limit what URL schemes it accepts + +## Use CURLOPT_PROTOCOLS + +libcurl programs can use CURLOPT_PROTOCOLS(3) to limit what URL schemes it accepts + +## consider not allowing the user to set the full URL + Maybe just let the user provide data for parts of it? Or maybe filter input to only allow specific choices? -.SH "RFC 3986 vs WHATWG URL" + +# RFC 3986 vs WHATWG URL + curl supports URLs mostly according to how they are defined in RFC 3986, and has done so since the beginning. @@ -298,9 +329,11 @@ assumptions about a link. This can mislead users into getting the wrong thing, connecting to the wrong host or otherwise not working identically. Within an application, this can be mitigated by always using the -\fIcurl_url(3)\fP API to parse URLs, ensuring that they are parsed the same way +curl_url(3) API to parse URLs, ensuring that they are parsed the same way as within libcurl itself. -.SH "FTP uses two connections" + +# FTP uses two connections + When performing an FTP transfer, two TCP connections are used: one for setting up the transfer and one for the actual data. @@ -329,46 +362,56 @@ instead of back to curl. The fact that FTP uses two connections makes it vulnerable in a way that is hard to avoid. -.SH "Denial of Service" + +# Denial of Service + A malicious server could cause libcurl to effectively hang by sending data slowly, or even no data at all but just keeping the TCP connection open. This could effectively result in a denial-of-service attack. The -\fICURLOPT_TIMEOUT(3)\fP and/or \fICURLOPT_LOW_SPEED_LIMIT(3)\fP options can +CURLOPT_TIMEOUT(3) and/or CURLOPT_LOW_SPEED_LIMIT(3) options can be used to mitigate against this. A malicious server could cause libcurl to download an infinite amount of data, potentially causing all of memory or disk to be filled. Setting the -\fICURLOPT_MAXFILESIZE_LARGE(3)\fP option is not sufficient to guard against +CURLOPT_MAXFILESIZE_LARGE(3) option is not sufficient to guard against this. Instead, applications should monitor the amount of data received within the write or progress callback and abort once the limit is reached. A malicious HTTP server could cause an infinite redirection loop, causing a denial-of-service. This can be mitigated by using the -\fICURLOPT_MAXREDIRS(3)\fP option. -.SH "Arbitrary Headers" +CURLOPT_MAXREDIRS(3) option. + +# Arbitrary Headers + User-supplied data must be sanitized when used in options like -\fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_HTTPHEADER(3)\fP, -\fICURLOPT_POSTFIELDS(3)\fP and others that are used to generate structured +CURLOPT_USERAGENT(3), CURLOPT_HTTPHEADER(3), +CURLOPT_POSTFIELDS(3) and others that are used to generate structured data. Characters like embedded carriage returns or ampersands could allow the user to create additional headers or fields that could cause malicious transactions. -.SH "Server-supplied Names" + +# Server-supplied Names + A server can supply data which the application may, in some cases, use as a file name. The curl command-line tool does this with -\fI--remote-header-name\fP, using the Content-disposition: header to generate -a file name. An application could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to +*--remote-header-name*, using the Content-disposition: header to generate +a file name. An application could also use CURLINFO_EFFECTIVE_URL(3) to generate a file name from a server-supplied redirect URL. Special care must be taken to sanitize such names to avoid the possibility of a malicious server -supplying one like \fB"/etc/passwd"\fP, \fB"\\autoexec.bat"\fP, \fB"prn:"\fP -or even \fB".bashrc"\fP. -.SH "Server Certificates" -A secure application should never use the \fICURLOPT_SSL_VERIFYPEER(3)\fP +supplying one like **"/etc/passwd"**, **"autoexec.bat"**, **"prn:"** +or even **".bashrc"**. + +# Server Certificates + +A secure application should never use the CURLOPT_SSL_VERIFYPEER(3) option to disable certificate validation. There are numerous attacks that are enabled by applications that fail to properly validate server TLS/SSL certificates, thus enabling a malicious server to spoof a legitimate one. HTTPS without validated certificates is potentially as insecure as a plain HTTP connection. -.SH "Showing What You Do" + +# Showing What You Do + Relatedly, be aware that in situations when you have problems with libcurl and ask someone for help, everything you reveal in order to get best possible help might also impose certain security related risks. Host names, user names, @@ -384,7 +427,9 @@ sensitive data. To avoid this problem, you must of course use your common sense. Often, you can just edit out the sensitive data or just search/replace your true information with faked data. -.SH "setuid applications using libcurl" + +# setuid applications using libcurl + libcurl-using applications that set the 'setuid' bit to run with elevated or modified rights also implicitly give that extra power to libcurl and this should only be done after careful considerations. @@ -396,16 +441,20 @@ that the user is otherwise not able to view (like credentials for a login etc), it should be noted that libcurl still might understand proxy environment variables that allow the user to redirect libcurl operations to use a proxy controlled by the user. -.SH "File descriptors, fork and NTLM" -An application that uses libcurl and invokes \fIfork()\fP gets all file + +# File descriptors, fork and NTLM + +An application that uses libcurl and invokes *fork()* gets all file descriptors duplicated in the child process, including the ones libcurl created. -libcurl itself uses \fIfork()\fP and \fIexecl()\fP if told to use the -\fBCURLAUTH_NTLM_WB\fP authentication method which then invokes the helper +libcurl itself uses *fork()* and *execl()* if told to use the +**CURLAUTH_NTLM_WB** authentication method which then invokes the helper command in a child process with file descriptors duplicated. Make sure that only the trusted and reliable helper program is invoked! -.SH "Secrets in memory" + +# Secrets in memory + When applications pass user names, passwords or other sensitive data to libcurl to be used for upcoming transfers, those secrets are kept around as-is in memory. In many cases they are stored in the heap for as long as the handle @@ -417,17 +466,23 @@ core dump file, such data might be accessible. Further, when eventually closing a handle and the secrets are no longer needed, libcurl does not explicitly clear memory before freeing it, so credentials may be left in freed data. -.SH "Saving files" + +# Saving files + libcurl cannot protect against attacks where an attacker has write access to the same directory where libcurl is directed to save files. -.SH "Cookies" + +# Cookies + If libcurl 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 libcurl is *not* built with PSL support, it has no ability to stop super cookies. -.SH "Report Security Problems" + +# Report Security Problems + Should you detect or just suspect a security problem in libcurl or curl, contact the project curl security team immediately. See https://curl.se/dev/secprocess.html for details. diff --git a/docs/libcurl/libcurl-share.3 b/docs/libcurl/libcurl-share.3 deleted file mode 100644 index 7e7ee2ae644..00000000000 --- a/docs/libcurl/libcurl-share.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.TH libcurl-share 3 "8 Aug 2003" "libcurl" "libcurl" -.SH NAME -libcurl-share \- how to use the share interface -.SH DESCRIPTION -This is an overview on how to use the libcurl share interface in your C -programs. There are specific man pages for each function mentioned in -here. - -All functions in the share interface are prefixed with curl_share. - -.SH "OBJECTIVES" -The share interface was added to enable sharing of data between curl -\&"handles". -.SH "ONE SET OF DATA - MANY TRANSFERS" -You can have multiple easy handles share data between them. Have them update -and use the \fBsame\fP cookie database, DNS cache, TLS session cache and/or -connection cache! This way, each single transfer takes advantage from data -updates made by the other transfer(s). -.SH "SHARE OBJECT" -You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle -for a newly created one. - -You tell the shared object what data you want it to share by using -\fIcurl_share_setopt(3)\fP. - -Since you can use this share from multiple threads, and libcurl has no -internal thread synchronization, you must provide mutex callbacks if you are -using this multi-threaded. You set lock and unlock functions with -\fIcurl_share_setopt(3)\fP too. - -Then, you make an easy handle to use this share, you set the -\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, and pass in -share handle. You can make any number of easy handles share the same share -handle. - -To make an easy handle stop using that particular share, you set -\fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop -sharing a particular data, you can \fICURLSHOPT_UNSHARE(3)\fP it. - -When you are done using the share, make sure that no easy handle is still using -it, and call \fIcurl_share_cleanup(3)\fP on the handle. -.SH "SEE ALSO" -.BR curl_share_init (3), -.BR curl_share_setopt (3), -.BR curl_share_cleanup (3), -.BR libcurl-errors (3), -.BR libcurl-easy (3), -.BR libcurl-multi (3) diff --git a/docs/libcurl/libcurl-share.md b/docs/libcurl/libcurl-share.md new file mode 100644 index 00000000000..0106eb592df --- /dev/null +++ b/docs/libcurl/libcurl-share.md @@ -0,0 +1,63 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-share +Section: 3 +Source: libcurl +See-also: + - curl_share_cleanup (3) + - curl_share_init (3) + - curl_share_setopt (3) + - libcurl-easy (3) + - libcurl-errors (3) + - libcurl-multi (3) +--- + +# NAME + +libcurl-share - how to use the share interface + +# DESCRIPTION + +This is an overview on how to use the libcurl share interface in your C +programs. There are specific man pages for each function mentioned in +here. + +All functions in the share interface are prefixed with curl_share. + +# OBJECTIVES + +The share interface was added to enable sharing of data between curl +&"handles". + +# ONE SET OF DATA - MANY TRANSFERS + +You can have multiple easy handles share data between them. Have them update +and use the **same** cookie database, DNS cache, TLS session cache and/or +connection cache! This way, each single transfer takes advantage from data +updates made by the other transfer(s). + +# SHARE OBJECT + +You create a shared object with curl_share_init(3). It returns a handle +for a newly created one. + +You tell the shared object what data you want it to share by using +curl_share_setopt(3). + +Since you can use this share from multiple threads, and libcurl has no +internal thread synchronization, you must provide mutex callbacks if you are +using this multi-threaded. You set lock and unlock functions with +curl_share_setopt(3) too. + +Then, you make an easy handle to use this share, you set the +CURLOPT_SHARE(3) option with curl_easy_setopt(3), and pass in +share handle. You can make any number of easy handles share the same share +handle. + +To make an easy handle stop using that particular share, you set +CURLOPT_SHARE(3) to NULL for that easy handle. To make a handle stop +sharing a particular data, you can CURLSHOPT_UNSHARE(3) it. + +When you are done using the share, make sure that no easy handle is still using +it, and call curl_share_cleanup(3) on the handle. diff --git a/docs/libcurl/libcurl-thread.3 b/docs/libcurl/libcurl-thread.3 deleted file mode 100644 index 397eeae6687..00000000000 --- a/docs/libcurl/libcurl-thread.3 +++ /dev/null @@ -1,96 +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 -.\" * -.\" ************************************************************************** -.\" -.TH libcurl-thread 3 "13 Jul 2015" "libcurl" "libcurl" -.SH NAME -libcurl-thread \- libcurl thread safety -.SH "Multi-threading with libcurl" -libcurl is thread safe but has no internal thread synchronization. You may have -to provide your own locking should you meet any of the thread safety exceptions -below. - -.SH "Handles" -You must \fBnever\fP share the same handle in multiple threads. You can pass -the handles around among threads, but you must never use a single handle from -more than one thread at any given time. -.SH "Shared objects" -You can share certain data between multiple handles by using the share -interface but you must provide your own locking and set -\fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC. - -Note that some items are specifically documented as not thread-safe in the -share API (the connection pool and HSTS cache for example). -.SH TLS -All current TLS libraries libcurl supports are thread-safe. OpenSSL 1.1.0+ can -be safely used in multi-threaded applications provided that support for the -underlying OS threading API is built-in. For older versions of OpenSSL, the -user must set mutex callbacks. -.SH "Signals" -Signals are used for timing out name resolves (during DNS lookup) - when built -without using either the c-ares or threaded resolver backends. On systems that -have a signal concept. - -When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP -option to 1L for all handles. Everything works fine except that timeouts -cannot be honored during DNS lookups - which you can work around by building -libcurl with c-ares or threaded-resolver support. c-ares is a library that -provides asynchronous name resolves. On some platforms, libcurl simply cannot -function properly multi-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option -is set. - -When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal -with the risk of a SIGPIPE (that at least the OpenSSL backend can -trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L does not work in a -threaded situation as there is a race condition where libcurl risks restoring -the former signal handler while another thread should still ignore it. -.SH "Name resolving" -The \fBgethostbyname\fP or \fBgetaddrinfo\fP and other name resolving system -calls used by libcurl are provided by your operating system and must be thread -safe. It is important that libcurl can find and use thread safe versions of -these and other system calls, as otherwise it cannot function fully thread -safe. Some operating systems are known to have faulty thread -implementations. We have previously received problem reports on *BSD (at least -in the past, they may be working fine these days). Some operating systems that -are known to have solid and working thread support are Linux, Solaris and -Windows. -.SH "curl_global_* functions" -These functions are thread-safe since libcurl 7.84.0 if -\fIcurl_version_info(3)\fP has the \fBCURL_VERSION_THREADSAFE\fP feature bit -set (most platforms). - -If these functions are not thread-safe and you are using libcurl with multiple -threads it is especially important that before use you call -\fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(3)\fP to explicitly -initialize the library and its dependents, rather than rely on the "lazy" -fail-safe initialization that takes place the first time -\fIcurl_easy_init(3)\fP is called. For an in-depth explanation refer to -\fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP. -.SH "Memory functions" -These functions, provided either by your operating system or your own -replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP -to set your own replacement memory functions. -.SH "Non-safe functions" -\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe. - -\fIcurl_version_info(3)\fP is not thread-safe before libcurl initialization. diff --git a/docs/libcurl/libcurl-thread.md b/docs/libcurl/libcurl-thread.md new file mode 100644 index 00000000000..b3e9ecf82a9 --- /dev/null +++ b/docs/libcurl/libcurl-thread.md @@ -0,0 +1,99 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-thread +Section: 3 +Source: libcurl +See-also: + - libcurl-security (3) +--- + +# NAME + +libcurl-thread - libcurl thread safety + +# Multi-threading with libcurl + +libcurl is thread safe but has no internal thread synchronization. You may have +to provide your own locking should you meet any of the thread safety exceptions +below. + +# Handles + +You must **never** share the same handle in multiple threads. You can pass the +handles around among threads, but you must never use a single handle from more +than one thread at any given time. + +# Shared objects + +You can share certain data between multiple handles by using the share +interface but you must provide your own locking and set +curl_share_setopt(3) CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC. + +Note that some items are specifically documented as not thread-safe in the +share API (the connection pool and HSTS cache for example). + +# TLS + +All current TLS libraries libcurl supports are thread-safe. OpenSSL 1.1.0+ can +be safely used in multi-threaded applications provided that support for the +underlying OS threading API is built-in. For older versions of OpenSSL, the +user must set mutex callbacks. + +# Signals + +Signals are used for timing out name resolves (during DNS lookup) - when built +without using either the c-ares or threaded resolver backends. On systems that +have a signal concept. + +When using multiple threads you should set the CURLOPT_NOSIGNAL(3) +option to 1L for all handles. Everything works fine except that timeouts +cannot be honored during DNS lookups - which you can work around by building +libcurl with c-ares or threaded-resolver support. c-ares is a library that +provides asynchronous name resolves. On some platforms, libcurl simply cannot +function properly multi-threaded unless the CURLOPT_NOSIGNAL(3) option +is set. + +When CURLOPT_NOSIGNAL(3) is set to 1L, your application needs to deal +with the risk of a SIGPIPE (that at least the OpenSSL backend can +trigger). Note that setting CURLOPT_NOSIGNAL(3) to 0L does not work in a +threaded situation as there is a race condition where libcurl risks restoring +the former signal handler while another thread should still ignore it. + +# Name resolving + +The **gethostbyname** or **getaddrinfo** and other name resolving system +calls used by libcurl are provided by your operating system and must be thread +safe. It is important that libcurl can find and use thread safe versions of +these and other system calls, as otherwise it cannot function fully thread +safe. Some operating systems are known to have faulty thread +implementations. We have previously received problem reports on *BSD (at least +in the past, they may be working fine these days). Some operating systems that +are known to have solid and working thread support are Linux, Solaris and +Windows. + +# curl_global_* functions + +These functions are thread-safe since libcurl 7.84.0 if +curl_version_info(3) has the **CURL_VERSION_THREADSAFE** feature bit +set (most platforms). + +If these functions are not thread-safe and you are using libcurl with multiple +threads it is especially important that before use you call +curl_global_init(3) or curl_global_init_mem(3) to explicitly +initialize the library and its dependents, rather than rely on the "lazy" +fail-safe initialization that takes place the first time +curl_easy_init(3) is called. For an in-depth explanation refer to +libcurl(3) section **GLOBAL CONSTANTS**. + +# Memory functions + +These functions, provided either by your operating system or your own +replacements, must be thread safe. You can use curl_global_init_mem(3) +to set your own replacement memory functions. + +# Non-safe functions + +CURLOPT_DNS_USE_GLOBAL_CACHE(3) is not thread-safe. + +curl_version_info(3) is not thread-safe before libcurl initialization. diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.md similarity index 79% rename from docs/libcurl/libcurl-tutorial.3 rename to docs/libcurl/libcurl-tutorial.md index f8c9edf2289..188a5e04211 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.md @@ -1,38 +1,29 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH libcurl-tutorial 3 "19 Sep 2014" "libcurl" "libcurl" -.SH NAME -libcurl-tutorial \- libcurl programming tutorial -.SH "Objective" +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-tutorial +Section: 3 +Source: libcurl +See-also: + - libcurl-easy (3) + - libcurl-errors (3) + - libcurl-multi (3) + - libcurl-url (3) +--- + +# NAME + +libcurl-tutorial - libcurl programming tutorial + +# Objective + This document attempts to describe the general principles and some basic approaches to consider when programming with libcurl. The text focuses on the C interface but should apply fairly well on other language bindings as well as they usually follow the C API pretty closely. This document refers to 'the user' as the person writing the source code that -uses libcurl. That would probably be you or someone in your position. What is +uses libcurl. That would probably be you or someone in your position. What is generally referred to as 'the program' is the collected source code that you write that is using libcurl for transfers. The program is outside libcurl and libcurl is outside of the program. @@ -40,48 +31,58 @@ libcurl is outside of the program. To get more details on all options and functions described herein, please refer to their respective man pages. -.SH "Building" +# Building + There are many different ways to build C programs. This chapter assumes a Unix style build process. If you use a different build system, you can still read this to get general information that may apply to your environment as well. -.IP "Compiling the Program" + +## Compiling the Program + Your compiler needs to know where the libcurl headers are located. Therefore you must set your compiler's include path to point to the directory where you installed them. The 'curl-config'[3] tool can be used to get this information: -.nf +~~~c $ curl-config --cflags -.fi -.IP "Linking the Program with libcurl" +~~~ + +## Linking the Program with libcurl + When having compiled the program, you need to link your object files to create a single executable. For that to succeed, you need to link with libcurl and possibly also with other libraries that libcurl itself depends on. Like the OpenSSL libraries, but even some standard OS libraries may be needed on the command line. To figure out which flags to use, once again the 'curl-config' tool comes to the rescue: -.nf +~~~c $ curl-config --libs -.fi -.IP "SSL or Not" +~~~ + +## SSL or Not + libcurl can be built and customized in many ways. One of the things that varies from different libraries and builds is the support for SSL-based transfers, like HTTPS and FTPS. If a supported SSL library was detected properly at build-time, libcurl is built with SSL support. To figure out if an -installed libcurl has been built with SSL support enabled, use \&'curl-config' +installed libcurl has been built with SSL support enabled, use &'curl-config' like this: -.nf +~~~c $ curl-config --feature -.fi -And if SSL is supported, the keyword \fISSL\fP is written to stdout, possibly +~~~ +And if SSL is supported, the keyword *SSL* is written to stdout, possibly together with a other features that could be either on or off on for different libcurls. See also the "Features libcurl Provides" further down. -.IP "autoconf macro" + +## autoconf macro + When you write your configure script to detect libcurl and setup variables accordingly, we offer a macro that probably does everything you need in this area. See docs/libcurl/libcurl.m4 file - it includes docs on how to use it. -.SH "Portable Code in a Portable World" +# Portable Code in a Portable World + The people behind libcurl have put a considerable effort to make libcurl work on a large amount of different operating systems and environments. @@ -90,54 +91,59 @@ are only a few minor details that differ. If you just make sure to write your code portable enough, you can create a portable program. libcurl should not stop you from that. -.SH "Global Preparation" +# Global Preparation + The program must initialize some of the libcurl functionality globally. That means it should be done exactly once, no matter how many times you intend to use the library. Once for your program's entire life time. This is done using -.nf +~~~c curl_global_init() -.fi +~~~ and it takes one parameter which is a bit pattern that tells libcurl what to -initialize. Using \fICURL_GLOBAL_ALL\fP makes it initialize all known internal +initialize. Using *CURL_GLOBAL_ALL* makes it initialize all known internal sub modules, and might be a good default option. The current two bits that are specified are: -.RS -.IP "CURL_GLOBAL_WIN32" + +## CURL_GLOBAL_WIN32 + which only does anything on Windows machines. When used on a Windows machine, it makes libcurl initialize the win32 socket stuff. Without having that initialized properly, your program cannot use sockets properly. You should only do this once for each application, so if your program already does this or of another library in use does it, you should not tell libcurl to do this as well. -.IP CURL_GLOBAL_SSL + +## CURL_GLOBAL_SSL + which only does anything on libcurls compiled and built SSL-enabled. On these systems, this makes libcurl initialize the SSL library properly for this application. This only needs to be done once for each application so if your program or another library already does this, this bit should not be needed. -.RE libcurl has a default protection mechanism that detects if -\fIcurl_global_init(3)\fP has not been called by the time -\fIcurl_easy_perform(3)\fP is called and if that is the case, libcurl runs the +curl_global_init(3) has not been called by the time +curl_easy_perform(3) is called and if that is the case, libcurl runs the function itself with a guessed bit pattern. Please note that depending solely on this is not considered nice nor good. When the program no longer uses libcurl, it should call -\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It +curl_global_cleanup(3), which is the opposite of the init call. It performs the reversed operations to cleanup the resources the -\fIcurl_global_init(3)\fP call initialized. +curl_global_init(3) call initialized. -Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP +Repeated calls to curl_global_init(3) and curl_global_cleanup(3) should be avoided. They should only be called once each. -.SH "Features libcurl Provides" +# Features libcurl Provides + It is considered best-practice to determine libcurl features at runtime rather than at build-time (if possible of course). By calling -\fIcurl_version_info(3)\fP and checking out the details of the returned +curl_version_info(3) and checking out the details of the returned struct, your program can figure out exactly what the currently running libcurl supports. -.SH "Two Interfaces" +# Two Interfaces + libcurl first introduced the so called easy interface. All operations in the easy interface are prefixed with 'curl_easy'. The easy interface lets you do single transfers with a synchronous and blocking function call. @@ -147,101 +153,103 @@ transfers in a single thread, the so called multi interface. More about that interface is detailed in a separate chapter further down. You still need to understand the easy interface first, so please continue reading for better understanding. -.SH "Handle the Easy libcurl" + +# Handle the Easy libcurl + To use the easy interface, you must first create yourself an easy handle. You need one handle for each easy session you want to perform. Basically, you should use one handle for every thread you plan to use for transferring. You must never share the same handle in multiple threads. Get an easy handle with -.nf +~~~c handle = curl_easy_init(); -.fi +~~~ It returns an easy handle. Using that you proceed to the next step: setting up your preferred actions. A handle is just a logic entity for the upcoming transfer or series of transfers. You set properties and options for this handle using -\fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or +curl_easy_setopt(3). They control how the subsequent transfer or transfers using this handle are made. Options remain set in the handle until set again to something different. They are sticky. Multiple requests using the same handle use the same options. If you at any point would like to blank all previously set options for a -single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also +single easy handle, you can call curl_easy_reset(3) and you can also make a clone of an easy handle (with all its set options) using -\fIcurl_easy_duphandle(3)\fP. +curl_easy_duphandle(3). Many of the options you set in libcurl are "strings", pointers to data terminated with a zero byte. When you set strings with -\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they do not need +curl_easy_setopt(3), libcurl makes its own copy so that they do not need to be kept around in your application after being set[4]. One of the most basic properties to set in the handle is the URL. You set your -preferred URL to transfer with \fICURLOPT_URL(3)\fP in a manner similar to: +preferred URL to transfer with CURLOPT_URL(3) in a manner similar to: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/"); -.fi +~~~ Let's assume for a while that you want to receive data as the URL identifies a remote resource you want to get here. Since you write a sort of application that needs this transfer, I assume that you would like to get the data passed to you directly instead of simply getting it passed to stdout. So, you write your own function that matches this prototype: -.nf +~~~c size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp); -.fi +~~~ You tell libcurl to pass all data to this function by issuing a function similar to this: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_data); -.fi +~~~ You can control what data your callback function gets in the fourth argument by setting another property: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_WRITEDATA, &internal_struct); -.fi +~~~ Using that property, you can easily pass local data between your application and the function that gets invoked by libcurl. libcurl itself does not touch -the data you pass with \fICURLOPT_WRITEDATA(3)\fP. +the data you pass with CURLOPT_WRITEDATA(3). libcurl offers its own default internal callback that takes care of the data -if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It simply +if you do not set the callback with CURLOPT_WRITEFUNCTION(3). It simply outputs the received data to stdout. You can have the default callback write the data to a different file handle by passing a 'FILE *' to a file opened for -writing with the \fICURLOPT_WRITEDATA(3)\fP option. +writing with the CURLOPT_WRITEDATA(3) option. Now, we need to take a step back and take a deep breath. Here is one of those rare platform-dependent nitpicks. Did you spot it? On some platforms[2], libcurl is not able to operate on file handles opened by the program. Therefore, if you use the default callback and pass in an open file -handle with \fICURLOPT_WRITEDATA(3)\fP, libcurl crashes. You should avoid this +handle with CURLOPT_WRITEDATA(3), libcurl crashes. You should avoid this to make your program run fine virtually everywhere. -(\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both +(CURLOPT_WRITEDATA(3) was formerly known as *CURLOPT_FILE*. Both names still work and do the same thing). If you are using libcurl as a win32 DLL, you MUST use the -\fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or +CURLOPT_WRITEFUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or experience crashes. There are of course many more options you can set, and we get back to a few of them later. Let's instead continue to the actual transfer: -.nf +~~~c success = curl_easy_perform(handle); -.fi -\fIcurl_easy_perform(3)\fP connects to the remote site, does the necessary +~~~ +curl_easy_perform(3) connects to the remote site, does the necessary commands and performs the transfer. Whenever it receives data, it calls the callback function we previously set. The function may get one byte at a time, or it may get many kilobytes at once. libcurl delivers as much as possible as often as possible. Your callback function should return the number of bytes it -\&"took care of". If that is not the same amount of bytes that was passed to +&"took care of". If that is not the same amount of bytes that was passed to it, libcurl aborts the operation and returns with an error code. When the transfer is complete, the function returns a return code that informs you if it succeeded in its mission or not. If a return code is not enough for -you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer +you, you can use the CURLOPT_ERRORBUFFER(3) to point libcurl to a buffer of yours where it stores a human readable error message as well. If you then want to transfer another file, the handle is ready to be used @@ -255,39 +263,42 @@ finally transferring the file data. libcurl takes care of all that complication for you. Given simply the URL to a file, libcurl takes care of all the details needed to get the file moved from one machine to another. -.SH "Multi-threading Issues" +# Multi-threading Issues + libcurl is thread safe but there are a few exceptions. Refer to -\fIlibcurl-thread(3)\fP for more information. +libcurl-thread(3) for more information. + +# When It does not Work -.SH "When It does not Work" There are times when the transfer fails for some reason. You might have set the wrong libcurl option or misunderstood what the libcurl option actually does, or the remote server might return non-standard replies that confuse the library which then confuses your program. There is one golden rule when these things occur: set the -\fICURLOPT_VERBOSE(3)\fP option to 1. it causes the library to spew out the +CURLOPT_VERBOSE(3) option to 1. it causes the library to spew out the entire protocol details it sends, some internal info and some received protocol data as well (especially when using FTP). If you are using HTTP, adding the headers in the received output to study is also a clever way to get a better understanding why the server behaves the way it does. Include headers -in the normal body output with \fICURLOPT_HEADER(3)\fP set 1. +in the normal body output with CURLOPT_HEADER(3) set 1. Of course, there are bugs left. We need to know about them to be able to fix them, so we are quite dependent on your bug reports. When you do report suspected bugs in libcurl, please include as many details as you possibly can: -a protocol dump that \fICURLOPT_VERBOSE(3)\fP produces, library version, as +a protocol dump that CURLOPT_VERBOSE(3) produces, library version, as much as possible of your code that uses libcurl, operating system name and version, compiler name and version etc. -If \fICURLOPT_VERBOSE(3)\fP is not enough, you increase the level of debug -data your application receive by using the \fICURLOPT_DEBUGFUNCTION(3)\fP. +If CURLOPT_VERBOSE(3) is not enough, you increase the level of debug +data your application receive by using the CURLOPT_DEBUGFUNCTION(3). Getting some in-depth knowledge about the protocols involved is never wrong, and if you are trying to do funny things, you might understand libcurl and how to use it better if you study the appropriate RFC documents at least briefly. -.SH "Upload Data to a Remote Site" +# Upload Data to a Remote Site + libcurl tries to keep a protocol independent approach to most transfers, thus uploading to a remote FTP site is similar to uploading data to an HTTP server with a PUT request. @@ -300,40 +311,41 @@ Since we write an application, we most likely want libcurl to get the upload data by asking us for it. To make it do that, we set the read callback and the custom pointer libcurl passes to our read callback. The read callback should have a prototype similar to: -.nf +~~~c size_t function(char *bufptr, size_t size, size_t nitems, void *userp); -.fi -Where \fIbufptr\fP is the pointer to a buffer we fill in with data to upload -and \fIsize*nitems\fP is the size of the buffer and therefore also the maximum -amount of data we can return to libcurl in this call. The \fIuserp\fP pointer +~~~ +Where *bufptr* is the pointer to a buffer we fill in with data to upload +and *size*nitems* is the size of the buffer and therefore also the maximum +amount of data we can return to libcurl in this call. The *userp* pointer is the custom pointer we set to point to a struct of ours to pass private data between the application and the callback. -.nf +~~~c curl_easy_setopt(handle, CURLOPT_READFUNCTION, read_function); curl_easy_setopt(handle, CURLOPT_READDATA, &filedata); -.fi +~~~ Tell libcurl that we want to upload: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L); -.fi +~~~ A few protocols do not behave properly when uploads are done without any prior knowledge of the expected file size. So, set the upload file size using the -\fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]: +CURLOPT_INFILESIZE_LARGE(3) for all known file sizes like this[1]: -.nf +~~~c /* in this example, file_size must be an curl_off_t variable */ curl_easy_setopt(handle, CURLOPT_INFILESIZE_LARGE, file_size); -.fi +~~~ -When you call \fIcurl_easy_perform(3)\fP this time, it performs all the +When you call curl_easy_perform(3) this time, it performs all the necessary operations and when it has invoked the upload it calls your supplied callback to get the data to upload. The program should return as much data as possible in every invoke, as that is likely to make the upload perform as fast as possible. The callback should return the number of bytes it wrote in the buffer. Returning 0 signals the end of the upload. -.SH "Passwords" +# Passwords + Many protocols use or even require that user name and password are provided to be able to download or upload the data of your choice. libcurl offers several ways to specify them. @@ -341,46 +353,46 @@ several ways to specify them. Most protocols support that you specify the name and password in the URL itself. libcurl detects this and use them accordingly. This is written like this: -.nf +~~~c protocol://user:password@example.com/path/ -.fi +~~~ If you need any odd letters in your user name or password, you should enter them URL encoded, as %XX where XX is a two-digit hexadecimal number. libcurl also provides options to set various passwords. The user name and password as shown embedded in the URL can instead get set with the -\fICURLOPT_USERPWD(3)\fP option. The argument passed to libcurl should be a +CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a char * to a string in the format "user:password". In a manner like this: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret"); -.fi +~~~ Another case where name and password might be needed at times, is for those users who need to authenticate themselves to a proxy they use. libcurl offers -another option for this, the \fICURLOPT_PROXYUSERPWD(3)\fP. It is used quite -similar to the \fICURLOPT_USERPWD(3)\fP option like this: -.nf +another option for this, the CURLOPT_PROXYUSERPWD(3). It is used quite +similar to the CURLOPT_USERPWD(3) option like this: +~~~c curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); -.fi +~~~ There is a long time Unix "standard" way of storing FTP user names and passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks -the \fI%USERPROFILE% environment\fP variable if \fI%HOME%\fP is unset, and +the *%USERPROFILE% environment* variable if *%HOME%* is unset, and tries "_netrc" as name). The file should be made private so that only the user may read it (see also the "Security Considerations" chapter), as it might contain the password in plain text. libcurl has the ability to use this file to figure out what set of user name and password to use for a particular host. As an extension to the normal functionality, libcurl also supports this file for non-FTP protocols such as HTTP. To make curl use this file, use the -\fICURLOPT_NETRC(3)\fP option: -.nf +CURLOPT_NETRC(3) option: +~~~c curl_easy_setopt(handle, CURLOPT_NETRC, 1L); -.fi +~~~ And a basic example of how such a .netrc file may look like: -.nf +~~~c machine myhost.mydomain.com login userlogin password secretword -.fi +~~~ All these examples have been cases where the password has been optional, or at least you could leave it out and have libcurl attempt to do its job @@ -388,10 +400,12 @@ without it. There are times when the password is not optional, like when you are using an SSL private key for secure transfers. To pass the known private key password to libcurl: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword"); -.fi -.SH "HTTP Authentication" +~~~ + +# HTTP Authentication + The previous chapter showed how to set user name and password for getting URLs that require authentication. When using the HTTP protocol, there are many different ways a client can provide those credentials to the server and you @@ -401,29 +415,30 @@ in the HTTP request, base64-encoded. This is insecure. At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, Negotiate (SPNEGO). You can tell libcurl which one to use -with \fICURLOPT_HTTPAUTH(3)\fP as in: -.nf +with CURLOPT_HTTPAUTH(3) as in: +~~~c curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); -.fi +~~~ And when you send authentication to a proxy, you can also set authentication -type the same way but instead with \fICURLOPT_PROXYAUTH(3)\fP: -.nf +type the same way but instead with CURLOPT_PROXYAUTH(3): +~~~c curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); -.fi +~~~ Both these options allow you to set multiple types (by ORing them together), to make libcurl pick the most secure one out of the types the server/proxy claims to support. This method does however add a round-trip since libcurl must first ask the server what it supports: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC); -.fi -For convenience, you can use the \fICURLAUTH_ANY\fP define (instead of a list +~~~ +For convenience, you can use the *CURLAUTH_ANY* define (instead of a list with specific types) which allows libcurl to use whatever method it wants. When asking for multiple types, libcurl picks the available one it considers "best" in its own internal order of preference. -.SH "HTTP POSTing" +# HTTP POSTing + We get many questions regarding how to issue HTTP POSTs with libcurl the proper way. This chapter thus includes examples using both different versions of HTTP POST that libcurl supports. @@ -432,16 +447,16 @@ The first version is the simple POST, the most common version, that most HTML pages using the
tag uses. We provide a pointer to the data and tell libcurl to post it all to the remote site: -.nf +~~~c char *data="name=daniel&project=curl"; curl_easy_setopt(handle, CURLOPT_POSTFIELDS, data); curl_easy_setopt(handle, CURLOPT_URL, "http://posthere.com/"); curl_easy_perform(handle); /* post away! */ -.fi +~~~ Simple enough, huh? Since you set the POST options with the -\fICURLOPT_POSTFIELDS(3)\fP, this automatically switches the handle to use +CURLOPT_POSTFIELDS(3), this automatically switches the handle to use POST in the upcoming request. What if you want to post binary data that also requires you to set the @@ -451,7 +466,7 @@ tell libcurl the size of the post data. Setting headers in libcurl requests are done in a generic way, by building a list of our own headers and then passing that list to libcurl. -.nf +~~~c struct curl_slist *headers=NULL; headers = curl_slist_append(headers, "Content-Type: text/xml"); @@ -467,34 +482,35 @@ that list to libcurl. curl_easy_perform(handle); /* post away! */ curl_slist_free_all(headers); /* free the header list */ -.fi +~~~ While the simple examples above cover the majority of all cases where HTTP POST operations are required, they do not do multi-part formposts. Multi-part formposts were introduced as a better way to post (possibly large) binary data -and were first documented in the RFC 1867 (updated in RFC 2388). they are +and were first documented in the RFC 1867 (updated in RFC 2388). They are called multi-part because they are built by a chain of parts, each part being a single unit of data. Each part has its own name and contents. You can in fact create and post a multi-part formpost with the regular libcurl POST support described above, but that would require that you build a formpost -yourself and provide to libcurl. To make that easier, libcurl provides a MIME -API consisting in several functions: using those, you can create and fill a -multi-part form. Function \fIcurl_mime_init(3)\fP creates a multi-part body; -you can then append new parts to a multi-part body using -\fIcurl_mime_addpart(3)\fP. There are three possible data sources for a part: -memory using \fIcurl_mime_data(3)\fP, file using \fIcurl_mime_filedata(3)\fP -and user-defined data read callback using \fIcurl_mime_data_cb(3)\fP. -\fIcurl_mime_name(3)\fP sets a part's (i.e.: form field) name, while -\fIcurl_mime_filename(3)\fP fills in the remote file name. With -\fIcurl_mime_type(3)\fP, you can tell the MIME type of a part, -\fIcurl_mime_headers(3)\fP allows defining the part's headers. When a -multi-part body is no longer needed, you can destroy it using -\fIcurl_mime_free(3)\fP. +yourself and provide to libcurl. + +To make that easier, libcurl provides a MIME API consisting in several +functions: using those, you can create and fill a multi-part form. Function +curl_mime_init(3) creates a multi-part body; you can then append new parts +to a multi-part body using curl_mime_addpart(3). + +There are three possible data sources for a part: memory using +curl_mime_data(3), file using curl_mime_filedata(3) and user-defined data +read callback using curl_mime_data_cb(3). curl_mime_name(3) sets a part's +(i.e.: form field) name, while curl_mime_filename(3) fills in the remote +file name. With curl_mime_type(3), you can tell the MIME type of a part, +curl_mime_headers(3) allows defining the part's headers. When a multi-part +body is no longer needed, you can destroy it using curl_mime_free(3). The following example sets two simple text parts with plain textual contents, and then a file with binary contents and uploads the whole thing. -.nf +~~~c curl_mime *multipart = curl_mime_init(handle); curl_mimepart *part = curl_mime_addpart(multipart); curl_mime_name(part, "name"); @@ -513,31 +529,31 @@ and then a file with binary contents and uploads the whole thing. /* free the post data again */ curl_mime_free(multipart); -.fi +~~~ To post multiple files for a single form field, you must supply each file in a separate part, all with the same field name. Although function -\fIcurl_mime_subparts(3)\fP implements nested multi-parts, this way of +curl_mime_subparts(3) implements nested multi-parts, this way of multiple files posting is deprecated by RFC 7578, chapter 4.3. To set the data source from an already opened FILE pointer, use: -.nf +~~~c curl_mime_data_cb(part, filesize, (curl_read_callback) fread, (curl_seek_callback) fseek, NULL, filepointer); -.fi +~~~ -A deprecated \fIcurl_formadd(3)\fP function is still supported in libcurl. +A deprecated curl_formadd(3) function is still supported in libcurl. It should however not be used anymore for new designs and programs using it ought to be converted to the MIME API. It is however described here as an aid to conversion. -Using \fIcurl_formadd\fP, you add parts to the form. When you are done adding +Using *curl_formadd*, you add parts to the form. When you are done adding parts, you post the whole form. The MIME API example above is expressed as follows using this function: -.nf +~~~c struct curl_httppost *post=NULL; struct curl_httppost *last=NULL; curl_formadd(&post, &last, @@ -557,7 +573,7 @@ The MIME API example above is expressed as follows using this function: /* free the post data again */ curl_formfree(post); -.fi +~~~ Multipart formposts are chains of parts using MIME-style separators and headers. It means that each one of these separate parts get a few headers set @@ -568,7 +584,7 @@ of course supply headers to as many parts as you like, but this little example shows how you set headers to one specific part when you add that to the post handle: -.nf +~~~c struct curl_slist *headers=NULL; headers = curl_slist_append(headers, "Content-Type: text/xml"); @@ -582,20 +598,21 @@ handle: curl_formfree(post); /* free post */ curl_slist_free_all(headers); /* free custom header list */ -.fi +~~~ Since all options on an easy handle are "sticky", they remain the same until -changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell +changed even if you do call curl_easy_perform(3), you may need to tell curl to go back to a plain GET request if you intend to do one as your next request. You force an easy handle to go back to GET by using the -\fICURLOPT_HTTPGET(3)\fP option: -.nf +CURLOPT_HTTPGET(3) option: +~~~c curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L); -.fi -Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL does *not* stop libcurl +~~~ +Just setting CURLOPT_POSTFIELDS(3) to "" or NULL does *not* stop libcurl from doing a POST. It just makes it POST without any data to send! -.SH "Converting from deprecated form API to MIME API" +# Converting from deprecated form API to MIME API + Four rules have to be respected in building the multi-part: - The easy handle must be created before building the multi-part. @@ -605,68 +622,68 @@ Four rules have to be respected in building the multi-part: - Each part is created by a call to curl_mime_addpart(multipart). - When complete, the multi-part must be bound to the easy handle using -\fICURLOPT_MIMEPOST(3)\fP instead of \fICURLOPT_HTTPPOST(3)\fP. +CURLOPT_MIMEPOST(3) instead of CURLOPT_HTTPPOST(3). -Here are some example of \fIcurl_formadd\fP calls to MIME API sequences: +Here are some example of *curl_formadd* calls to MIME API sequences: -.nf +~~~c curl_formadd(&post, &last, CURLFORM_COPYNAME, "id", CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END); CURLFORM_CONTENTHEADER, headers, CURLFORM_END); -.fi +~~~ becomes: -.nf +~~~c part = curl_mime_addpart(multipart); curl_mime_name(part, "id"); curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); curl_mime_headers(part, headers, FALSE); -.fi +~~~ -Setting the last \fIcurl_mime_headers(3)\fP argument to TRUE would have caused +Setting the last curl_mime_headers(3) argument to TRUE would have caused the headers to be automatically released upon destroyed the multi-part, thus -saving a clean-up call to \fIcurl_slist_free_all(3)\fP. +saving a clean-up call to curl_slist_free_all(3). -.nf +~~~c curl_formadd(&post, &last, CURLFORM_PTRNAME, "logotype-image", CURLFORM_FILECONTENT, "-", CURLFORM_END); -.fi +~~~ becomes: -.nf +~~~c part = curl_mime_addpart(multipart); curl_mime_name(part, "logotype-image"); curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin); -.fi +~~~ -\fIcurl_mime_name(3)\fP always copies the field name. The special file name -"-" is not supported by \fIcurl_mime_filename(3)\fP: to read an open file, use +curl_mime_name(3) always copies the field name. The special file name +"-" is not supported by curl_mime_filename(3): to read an open file, use a callback source using fread(). The transfer is be chunk-encoded since the data size is unknown. -.nf +~~~c curl_formadd(&post, &last, CURLFORM_COPYNAME, "datafile[]", CURLFORM_FILE, "file1", CURLFORM_FILE, "file2", CURLFORM_END); -.fi +~~~ becomes: -.nf +~~~c part = curl_mime_addpart(multipart); curl_mime_name(part, "datafile[]"); curl_mime_filedata(part, "file1"); part = curl_mime_addpart(multipart); curl_mime_name(part, "datafile[]"); curl_mime_filedata(part, "file2"); -.fi +~~~ The deprecated multipart/mixed implementation of multiple files field is translated to two distinct parts with the same name. -.nf +~~~c curl_easy_setopt(handle, CURLOPT_READFUNCTION, myreadfunc); curl_formadd(&post, &last, CURLFORM_COPYNAME, "stream", @@ -675,87 +692,87 @@ translated to two distinct parts with the same name. CURLFORM_FILENAME, "archive.zip", CURLFORM_CONTENTTYPE, "application/zip", CURLFORM_END); -.fi +~~~ becomes: -.nf +~~~c part = curl_mime_addpart(multipart); curl_mime_name(part, "stream"); curl_mime_data_cb(part, (curl_off_t) datasize, myreadfunc, NULL, NULL, arg); curl_mime_filename(part, "archive.zip"); curl_mime_type(part, "application/zip"); -.fi +~~~ -\fICURLOPT_READFUNCTION(3)\fP callback is not used: it is replace by directly +CURLOPT_READFUNCTION(3) callback is not used: it is replace by directly setting the part source data from the callback read function. -.nf +~~~c curl_formadd(&post, &last, CURLFORM_COPYNAME, "memfile", CURLFORM_BUFFER, "memfile.bin", CURLFORM_BUFFERPTR, databuffer, CURLFORM_BUFFERLENGTH, (long) sizeof databuffer, CURLFORM_END); -.fi +~~~ becomes: -.nf +~~~c part = curl_mime_addpart(multipart); curl_mime_name(part, "memfile"); curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer); curl_mime_filename(part, "memfile.bin"); -.fi +~~~ -\fIcurl_mime_data(3)\fP always copies the initial data: data buffer is thus +curl_mime_data(3) always copies the initial data: data buffer is thus free for immediate reuse. -.nf +~~~c curl_formadd(&post, &last, CURLFORM_COPYNAME, "message", CURLFORM_FILECONTENT, "msg.txt", CURLFORM_END); -.fi +~~~ becomes: -.nf +~~~c part = curl_mime_addpart(multipart); curl_mime_name(part, "message"); curl_mime_filedata(part, "msg.txt"); curl_mime_filename(part, NULL); -.fi +~~~ -Use of \fIcurl_mime_filedata(3)\fP sets the remote file name as a side effect: -it is therefore necessary to clear it for \fICURLFORM_FILECONTENT\fP +Use of curl_mime_filedata(3) sets the remote file name as a side effect: +it is therefore necessary to clear it for *CURLFORM_FILECONTENT* emulation. -.SH "Showing Progress" +# Showing Progress For historical and traditional reasons, libcurl has a built-in progress meter that can be switched on and then makes it present a progress meter in your terminal. Switch on the progress meter by, oddly enough, setting -\fICURLOPT_NOPROGRESS(3)\fP to zero. This option is set to 1 by default. +CURLOPT_NOPROGRESS(3) to zero. This option is set to 1 by default. For most applications however, the built-in progress meter is useless and what instead is interesting is the ability to specify a progress callback. The function pointer you pass to libcurl is then called on irregular intervals with information about the current transfer. -Set the progress callback by using \fICURLOPT_PROGRESSFUNCTION(3)\fP. And pass +Set the progress callback by using CURLOPT_PROGRESSFUNCTION(3). And pass a pointer to a function that matches this prototype: -.nf +~~~c int progress_callback(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow); -.fi +~~~ If any of the input arguments is unknown, a 0 is provided. The first argument, the 'clientp' is the pointer you pass to libcurl with -\fICURLOPT_PROGRESSDATA(3)\fP. libcurl does not touch it. +CURLOPT_PROGRESSDATA(3). libcurl does not touch it. -.SH "libcurl with C++" +# libcurl with C++ There is basically only one thing to keep in mind when using C++ instead of C when interfacing libcurl: @@ -764,7 +781,7 @@ The callbacks CANNOT be non-static class member functions Example C++ code: -.nf +~~~c class AClass { static size_t write_data(void *ptr, size_t size, size_t nmemb, void *ourpointer) @@ -772,9 +789,9 @@ class AClass { /* do what you want with the data */ } } -.fi +~~~ -.SH "Proxies" +# Proxies What "proxy" means according to Merriam-Webster: "a person authorized to act for another" but also "the agency, function, or office of a deputy who acts as @@ -800,53 +817,55 @@ at times it is important to understand that all operations over an HTTP proxy use the HTTP protocol. For example, you cannot invoke your own custom FTP commands or even proper FTP directory listings. -.IP "Proxy Options" +## Proxy Options To tell libcurl to use a proxy at a given port number: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_PROXY, "proxy-host.com:8080"); -.fi +~~~ Some proxies require user authentication before allowing a request, and you pass that information similar to this: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password"); -.fi +~~~ If you want to, you can specify the host name only in the -\fICURLOPT_PROXY(3)\fP option, and set the port number separately with -\fICURLOPT_PROXYPORT(3)\fP. +CURLOPT_PROXY(3) option, and set the port number separately with +CURLOPT_PROXYPORT(3). -Tell libcurl what kind of proxy it is with \fICURLOPT_PROXYTYPE(3)\fP (if not, +Tell libcurl what kind of proxy it is with CURLOPT_PROXYTYPE(3) (if not, it defaults to assuming an HTTP proxy): -.nf +~~~c curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); -.fi -.IP "Environment Variables" +~~~ + +## Environment Variables libcurl automatically checks and uses a set of environment variables to know what proxies to use for certain protocols. The names of the variables are following an old tradition and are built up as "[protocol]_proxy" (note the -lower casing). Which makes the variable \&'http_proxy' checked for a name of a +lower casing). Which makes the variable &'http_proxy' checked for a name of a proxy to use when the input URL is HTTP. Following the same rule, the variable named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are always HTTP proxies, the different names of the variables simply allows different HTTP proxies to be used. The proxy environment variable contents should be in the format -\&"[protocol://][user:password@]machine[:port]". Where the protocol:// part +"[protocol://][user:password@]machine[:port]". Where the protocol:// part specifies which type of proxy it is, and the optional port number specifies on which port the proxy operates. If not specified, the internal default port number is used and that is most likely not the one you would like it to be. There are two special environment variables. 'all_proxy' is what sets proxy for any URL in case the protocol specific variable was not set, and -\&'no_proxy' defines a list of hosts that should not use a proxy even though a +&'no_proxy' defines a list of hosts that should not use a proxy even though a variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all hosts. To explicitly disable libcurl's checking for and using the proxy environment variables, set the proxy name to "" - an empty string - with -\fICURLOPT_PROXY(3)\fP. -.IP "SSL and Proxies" +CURLOPT_PROXY(3). + +## SSL and Proxies SSL is for secure point-to-point connections. This involves strong encryption and similar things, which effectively makes it impossible for a proxy to @@ -866,7 +885,8 @@ few advantages that come from using a proxy, such as caching. Many organizations prevent this kind of tunneling to other destination port numbers than 443 (which is the default HTTPS port number). -.IP "Tunneling Through Proxy" +## Tunneling Through Proxy + As explained above, tunneling is required for SSL to work and often even restricted to the operation intended for SSL; HTTPS. @@ -882,18 +902,18 @@ Again, this is often prevented by the administrators of proxies and is rarely allowed. Tell libcurl to use proxy tunneling like this: -.nf +~~~c curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L); -.fi +~~~ In fact, there might even be times when you want to do plain HTTP operations using a tunnel like this, as it then enables you to operate on the remote server instead of asking the proxy to do so. libcurl does not stand in the way for such innovative actions either! -.IP "Proxy Auto-Config" +## Proxy Auto-Config Netscape first came up with this. It is basically a web page (usually using a -\&.pac extension) with a JavaScript that when executed by the browser with the +&.pac extension) with a JavaScript that when executed by the browser with the requested URL as input, returns information to the browser on how to connect to the URL. The returned information might be "DIRECT" (which means no proxy should be used), "PROXY host:port" (to tell the browser where the proxy for @@ -914,12 +934,12 @@ Mozilla JavaScript engine in the past. - Ask your admins to stop this, for a static proxy setup or similar. -.SH "Persistence Is The Way to Happiness" +# Persistence Is The Way to Happiness Re-cycling the same easy handle several times when doing multiple requests is the way to go. -After each single \fIcurl_easy_perform(3)\fP operation, libcurl keeps the +After each single curl_easy_perform(3) operation, libcurl keeps the connection alive and open. A subsequent request using the same easy handle to the same host might just be able to use the already open connection! This reduces network impact a lot. @@ -941,36 +961,41 @@ may also be added in the future. Each easy handle attempts to keep the last few connections alive for a while in case they are to be used again. You can set the size of this "cache" with -the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely any +the CURLOPT_MAXCONNECTS(3) option. Default is 5. There is rarely any point in changing this value, and if you think of changing this it is often just a matter of thinking again. To force your upcoming request to not use an already existing connection, you -can do that by setting \fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar +can do that by setting CURLOPT_FRESH_CONNECT(3) to 1. In a similar spirit, you can also forbid the upcoming request to be "lying" around and possibly get reused after the request by setting -\fICURLOPT_FORBID_REUSE(3)\fP to 1. +CURLOPT_FORBID_REUSE(3) to 1. + +# HTTP Headers Used by libcurl -.SH "HTTP Headers Used by libcurl" When you use libcurl to do HTTP requests, it passes along a series of headers automatically. It might be good for you to know and understand these. You can -replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option. +replace or remove them by using the CURLOPT_HTTPHEADER(3) option. + +## Host -.IP "Host" This header is required by HTTP 1.1 and even many 1.0 servers and should be the name of the server we want to talk to. This includes the port number if anything but default. -.IP "Accept" -\&"*/*". +## Accept + +&"*/*". -.IP "Expect" -When doing POST requests, libcurl sets this header to \&"100-continue" to ask +## Expect + +When doing POST requests, libcurl sets this header to &"100-continue" to ask the server for an "OK" message before it proceeds with sending the data part of the post. If the posted data amount is deemed "small", libcurl does not use this header. -.SH "Customizing Operations" +# Customizing Operations + There is an ongoing development today where more and more protocols are built upon HTTP for transport. This has obvious benefits as HTTP is a tested and reliable protocol that is widely deployed and has excellent proxy-support. @@ -981,50 +1006,53 @@ manners. You may need to change words, headers or various data. libcurl is your friend here too. -.IP CUSTOMREQUEST +## CUSTOMREQUEST + If just changing the actual HTTP request keyword is what you want, like when -GET, HEAD or POST is not good enough for you, \fICURLOPT_CUSTOMREQUEST(3)\fP +GET, HEAD or POST is not good enough for you, CURLOPT_CUSTOMREQUEST(3) is there for you. It is simple to use: -.nf - curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); -.fi +~~~c +curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); +~~~ When using the custom request, you change the request keyword of the actual -request you are performing. Thus, by default you make a GET request but you can -also make a POST operation (as described before) and then replace the POST -keyword if you want to. you are the boss. +request you are performing. Thus, by default you make a GET request but you +can also make a POST operation (as described before) and then replace the POST +keyword if you want to. You are the boss. + +## Modify Headers -.IP "Modify Headers" HTTP-like protocols pass a series of headers to the server when doing the request, and you are free to pass any amount of extra headers that you think fit. Adding headers is this easy: -.nf - struct curl_slist *headers=NULL; /* init to NULL is important */ +~~~c +struct curl_slist *headers=NULL; /* init to NULL is important */ - headers = curl_slist_append(headers, "Hey-server-hey: how are you?"); - headers = curl_slist_append(headers, "X-silly-content: yes"); +headers = curl_slist_append(headers, "Hey-server-hey: how are you?"); +headers = curl_slist_append(headers, "X-silly-content: yes"); - /* pass our list of custom made headers */ - curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); +/* pass our list of custom made headers */ +curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); - curl_easy_perform(handle); /* transfer http */ +curl_easy_perform(handle); /* transfer http */ - curl_slist_free_all(headers); /* free the header list */ -.fi +curl_slist_free_all(headers); /* free the header list */ +~~~ -\&... and if you think some of the internally generated headers, such as +&... and if you think some of the internally generated headers, such as Accept: or Host: do not contain the data you want them to contain, you can replace them by simply setting them too: -.nf - headers = curl_slist_append(headers, "Accept: Agent-007"); - headers = curl_slist_append(headers, "Host: munged.host.line"); -.fi +~~~c +headers = curl_slist_append(headers, "Accept: Agent-007"); +headers = curl_slist_append(headers, "Host: munged.host.line"); +~~~ + +## Delete Headers -.IP "Delete Headers" If you replace an existing header with one with no contents, you prevent the header from being sent. For instance, if you want to completely prevent the -\&"Accept:" header from being sent, you can disable it with code similar to +&"Accept:" header from being sent, you can disable it with code similar to this: headers = curl_slist_append(headers, "Accept:"); @@ -1033,7 +1061,7 @@ Both replacing and canceling internal headers should be done with careful consideration and you should be aware that you may violate the HTTP protocol when doing so. -.IP "Enforcing chunked transfer-encoding" +## Enforcing chunked transfer-encoding By making sure a request uses the custom header "Transfer-Encoding: chunked" when doing a non-GET HTTP operation, libcurl switches over to "chunked" @@ -1041,7 +1069,7 @@ upload, even though the size of the data to upload might be known. By default, libcurl usually switches over to chunked upload automatically if the upload data size is unknown. -.IP "HTTP Version" +## HTTP Version All HTTP requests includes the version number to tell the server which version we support. libcurl speaks HTTP 1.1 by default. Some old servers do not like @@ -1050,7 +1078,7 @@ can tell libcurl to use 1.0 instead by doing something like this: curl_easy_setopt(handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0); -.IP "FTP Custom Commands" +## FTP Custom Commands Not all protocols are HTTP-like, and thus the above may not help you when you want to make, for example, your FTP transfers to behave differently. @@ -1067,7 +1095,7 @@ correct remote directory. A little example that deletes a given file before an operation: -.nf +~~~c headers = curl_slist_append(headers, "DELE file-to-remove"); /* pass the list of custom commands to the handle */ @@ -1076,35 +1104,37 @@ A little example that deletes a given file before an operation: curl_easy_perform(handle); /* transfer ftp data! */ curl_slist_free_all(headers); /* free the header list */ -.fi +~~~ If you would instead want this operation (or chain of operations) to happen -_after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP -would instead be called \fICURLOPT_POSTQUOTE(3)\fP and used the exact same +_after_ the data transfer took place the option to curl_easy_setopt(3) +would instead be called CURLOPT_POSTQUOTE(3) and used the exact same way. The custom FTP commands are issued to the server in the same order they are added to the list, and if a command gets an error code returned back from the server, no more commands are issued and libcurl bails out with an error code -(CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to send +(CURLE_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE(3) to send commands before a transfer, no transfer actually takes place when a quote command has failed. -If you set the \fICURLOPT_HEADER(3)\fP to 1, you tell libcurl to get +If you set the CURLOPT_HEADER(3) to 1, you tell libcurl to get information about the target file and output "headers" about it. The headers are in "HTTP-style", looking like they do in HTTP. The option to enable headers or to run custom FTP commands may be useful to -combine with \fICURLOPT_NOBODY(3)\fP. If this option is set, no actual file +combine with CURLOPT_NOBODY(3). If this option is set, no actual file content transfer is performed. -.IP "FTP Custom CUSTOMREQUEST" +## FTP Custom CUSTOMREQUEST + If you do want to list the contents of an FTP directory using your own defined -FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP does just that. "NLST" is the +FTP command, CURLOPT_CUSTOMREQUEST(3) does just that. "NLST" is the default one for listing directories but you are free to pass in your idea of a good alternative. -.SH "Cookies Without Chocolate Chips" +# Cookies Without Chocolate Chips + In the HTTP sense, a cookie is a name with an associated value. A server sends the name and value to the client, and expects it to get sent back on every subsequent request to the server that matches the particular conditions @@ -1118,10 +1148,10 @@ Cookies are sent from server to clients with the header Set-Cookie: and they are sent from clients to servers with the Cookie: header. To just send whatever cookie you want to a server, you can use -\fICURLOPT_COOKIE(3)\fP to set a cookie string like this: -.nf +CURLOPT_COOKIE(3) to set a cookie string like this: +~~~c curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); -.fi +~~~ In many cases, that is not enough. You might want to dynamically save whatever cookies the remote server passes to you, and make sure those cookies are then used accordingly on later requests. @@ -1129,33 +1159,33 @@ are then used accordingly on later requests. One way to do this, is to save all headers you receive in a plain file and when you make a request, you tell libcurl to read the previous headers to figure out which cookies to use. Set the header file to read cookies from with -\fICURLOPT_COOKIEFILE(3)\fP. +CURLOPT_COOKIEFILE(3). -The \fICURLOPT_COOKIEFILE(3)\fP option also automatically enables the cookie +The CURLOPT_COOKIEFILE(3) option also automatically enables the cookie parser in libcurl. Until the cookie parser is enabled, libcurl does not parse or understand incoming cookies and they are just be ignored. However, when the parser is enabled the cookies are understood and the cookies are kept in memory and used properly in subsequent requests when the same handle is used. Many times this is enough, and you may not have to save the cookies to -disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP +disk at all. Note that the file you specify to CURLOPT_COOKIEFILE(3) does not have to exist to enable the parser, so a common way to just enable the parser and not read any cookies is to use the name of a file you know does not exist. If you would rather use existing cookies that you have previously received with your Netscape or Mozilla browsers, you can make libcurl use that cookie -file as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as +file as input. The CURLOPT_COOKIEFILE(3) is used for that too, as libcurl automatically finds out what kind of file it is and acts accordingly. Perhaps the most advanced cookie operation libcurl offers, is saving the entire internal cookie state back into a Netscape/Mozilla formatted cookie file. We call that the cookie-jar. When you set a file name with -\fICURLOPT_COOKIEJAR(3)\fP, that file name is created and all received cookies -get stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables +CURLOPT_COOKIEJAR(3), that file name is created and all received cookies +get stored in it when curl_easy_cleanup(3) is called. This enables cookies to get passed on properly between multiple handles without any information getting lost. -.SH "FTP Peculiarities We Need" +# FTP Peculiarities We Need FTP transfers use a second TCP/IP connection for the data transfer. This is usually a fact you can forget and ignore but at times this detail comes back @@ -1171,22 +1201,23 @@ work it tries PASV instead. (EPSV is an extension to the original FTP spec and does not exist nor work on all FTP servers.) You can prevent libcurl from first trying the EPSV command by setting -\fICURLOPT_FTP_USE_EPSV(3)\fP to zero. +CURLOPT_FTP_USE_EPSV(3) to zero. In some cases, you want to have the server connect back to you for the second connection. This might be when the server is perhaps behind a firewall or something and only allows connections on a single port. libcurl then informs -the remote server which IP address and port number to connect to. This is -made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "-", libcurl -uses your system's "default IP address". If you want to use a particular IP, -you can set the full IP address, a host name to resolve to an IP address or -even a local network interface name that libcurl gets the IP address from. +the remote server which IP address and port number to connect to. This is made +with the CURLOPT_FTPPORT(3) option. If you set it to "-", libcurl uses your +system's "default IP address". If you want to use a particular IP, you can set +the full IP address, a host name to resolve to an IP address or even a local +network interface name that libcurl gets the IP address from. When doing the "PORT" approach, libcurl attempts to use the EPRT and the LPRT before trying PORT, as they work with more protocols. You can disable this -behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero. +behavior by setting CURLOPT_FTP_USE_EPRT(3) to zero. + +# MIME API revisited for SMTP and IMAP -.SH "MIME API revisited for SMTP and IMAP" In addition to support HTTP multi-part form fields, the MIME API can be used to build structured email messages and send them via SMTP or append such messages to IMAP directories. @@ -1198,26 +1229,26 @@ text formats alternatives. This can be nested to any level. To build such a message, you prepare the nth-level multi-part and then include it as a source to the parent multi-part using function -\fIcurl_mime_subparts(3)\fP. Once it has been +curl_mime_subparts(3). Once it has been bound to its parent multi-part, a nth-level multi-part belongs to it and should not be freed explicitly. Email messages data is not supposed to be non-ascii and line length is limited: fortunately, some transfer encodings are defined by the standards to support the transmission of such incompatible data. Function -\fIcurl_mime_encoder(3)\fP tells a part that its source data must be encoded +curl_mime_encoder(3) tells a part that its source data must be encoded before being sent. It also generates the corresponding header for that part. If the part data you want to send is already encoded in such a scheme, do not use this function (this would over-encode it), but explicitly set the corresponding part header. Upon sending such a message, libcurl prepends it with the header list -set with \fICURLOPT_HTTPHEADER(3)\fP, as zero level mime part headers. +set with CURLOPT_HTTPHEADER(3), as zero level mime part headers. Here is an example building an email message with an inline plain/html text alternative and a file attachment encoded in base64: -.nf +~~~c curl_mime *message = curl_mime_init(handle); /* The inline part is an alternative proposing the html and the text @@ -1255,37 +1286,40 @@ alternative and a file attachment encoded in base64: /* Set these into the easy handle. */ curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); curl_easy_setopt(handle, CURLOPT_MIMEPOST, mime); -.fi +~~~ It should be noted that appending a message to an IMAP directory requires the message size to be known prior upload. It is therefore not possible to include parts with unknown data size in this context. -.SH "Headers Equal Fun" +# Headers Equal Fun Some protocols provide "headers", meta-data separated from the normal data. These headers are by default not included in the normal data stream, but -you can make them appear in the data stream by setting \fICURLOPT_HEADER(3)\fP +you can make them appear in the data stream by setting CURLOPT_HEADER(3) to 1. What might be even more useful, is libcurl's ability to separate the headers from the data and thus make the callbacks differ. You can for example set a different pointer to pass to the ordinary write callback by setting -\fICURLOPT_HEADERDATA(3)\fP. +CURLOPT_HEADERDATA(3). Or, you can set an entirely separate function to receive the headers, by using -\fICURLOPT_HEADERFUNCTION(3)\fP. +CURLOPT_HEADERFUNCTION(3). The headers are passed to the callback function one by one, and you can depend on that fact. It makes it easier for you to add custom header parsers etc. -\&"Headers" for FTP transfers equal all the FTP server responses. They are not +&"Headers" for FTP transfers equal all the FTP server responses. They are not actually true headers, but in this case we pretend they are! ;-) -.SH "Post Transfer Information" -See \fIcurl_easy_getinfo(3)\fP. -.SH "The multi Interface" +# Post Transfer Information + +See curl_easy_getinfo(3). + +# The multi Interface + The easy interface as described in detail in this document is a synchronous interface that transfers one file at a time and does not return until it is done. @@ -1312,14 +1346,14 @@ a "multi stack". You create the easy handles you want, one for each concurrent transfer, and you set all the options just like you learned above, and then you create a -multi handle with \fIcurl_multi_init(3)\fP and add all those easy handles to -that multi handle with \fIcurl_multi_add_handle(3)\fP. +multi handle with curl_multi_init(3) and add all those easy handles to +that multi handle with curl_multi_add_handle(3). When you have added the handles you have for the moment (you can still add new ones at any time), you start the transfers by calling -\fIcurl_multi_perform(3)\fP. +curl_multi_perform(3). -\fIcurl_multi_perform(3)\fP is asynchronous. It only performs what can be done +curl_multi_perform(3) is asynchronous. It only performs what can be done now and then return control to your program. It is designed to never block. You need to keep calling the function until all transfers are completed. @@ -1328,37 +1362,38 @@ The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also makes it easy for you to wait and respond to actions on your own application's sockets/handles. You figure out what to select() for by using -\fIcurl_multi_fdset(3)\fP, that fills in a set of \fIfd_set\fP variables for +curl_multi_fdset(3), that fills in a set of *fd_set* variables for you with the particular file descriptors libcurl uses for the moment. When you then call select(), it returns when one of the file handles signal -action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do +action and you then call curl_multi_perform(3) to allow libcurl to do what it wants to do. Take note that libcurl does also feature some time-out code so we advise you to never use long timeouts on select() before you call -\fIcurl_multi_perform(3)\fP again. \fIcurl_multi_timeout(3)\fP is provided to +curl_multi_perform(3) again. curl_multi_timeout(3) is provided to help you get a suitable timeout period. -Another precaution you should use: always call \fIcurl_multi_fdset(3)\fP +Another precaution you should use: always call curl_multi_fdset(3) immediately before the select() call since the current set of file descriptors may change in any curl function invoke. If you want to stop the transfer of one of the easy handles in the stack, you -can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy -handles. Remember that easy handles should be \fIcurl_easy_cleanup(3)\fPed. +can use curl_multi_remove_handle(3) to remove individual easy +handles. Remember that easy handles should be curl_easy_cleanup(3)ed. When a transfer within the multi stack has finished, the counter of running -transfers (as filled in by \fIcurl_multi_perform(3)\fP) decreases. When the +transfers (as filled in by curl_multi_perform(3)) decreases. When the number reaches zero, all transfers are done. -\fIcurl_multi_info_read(3)\fP can be used to get information about completed +curl_multi_info_read(3) can be used to get information about completed transfers. It then returns the CURLcode for each easy transfer, to allow you to figure out success on each individual transfer. -.SH "SSL, Certificates and Other Tricks" +# SSL, Certificates and Other Tricks [ seeding, passwords, keys, certificates, ENGINE, ca certs ] -.SH "Sharing Data Between Easy Handles" +# Sharing Data Between Easy Handles + You can share some data between easy handles when the easy interface is used, and some data is share automatically when you use the multi interface. @@ -1370,29 +1405,32 @@ The DNS cache is shared between handles within a multi handle, making subsequent name resolving faster, and the connection pool that is kept to better allow persistent connections and connection reuse is also shared. If you are using the easy interface, you can still share these between specific -easy handles by using the share interface, see \fIlibcurl-share(3)\fP. +easy handles by using the share interface, see libcurl-share(3). Some things are never shared automatically, not within multi handles, like for example cookies so the only way to share that is with the share interface. -.SH "Footnotes" -.IP "[1]" +# Footnotes + +## [1] + libcurl 7.10.3 and later have the ability to switch over to chunked Transfer-Encoding in cases where HTTP uploads are done with data of an unknown size. -.IP "[2]" + +## [2] + This happens on Windows machines when libcurl is built and used as a DLL. However, you can still do this on Windows if you link with a static library. -.IP "[3]" + +## [3] + The curl-config tool is generated at build-time (on Unix-like systems) and should be installed with the 'make install' or similar instruction that installs the library, header files, man pages etc. -.IP "[4]" + +## [4] + This behavior was different in versions before 7.17.0, where strings had to -remain valid past the end of the \fIcurl_easy_setopt(3)\fP call. -.SH "SEE ALSO" -.BR libcurl-easy (3), -.BR libcurl-errors (3), -.BR libcurl-multi (3), -.BR libcurl-url (3) +remain valid past the end of the curl_easy_setopt(3) call. diff --git a/docs/libcurl/libcurl-url.3 b/docs/libcurl/libcurl-url.md similarity index 59% rename from docs/libcurl/libcurl-url.3 rename to docs/libcurl/libcurl-url.md index fb96a1f03a1..e1469d08ff6 100644 --- a/docs/libcurl/libcurl-url.3 +++ b/docs/libcurl/libcurl-url.md @@ -1,80 +1,91 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH libcurl 3 "10 Sep 2018" "libcurl" "libcurl" -.SH NAME -libcurl-url \- URL interface overview -.SH DESCRIPTION +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl +Section: 3 +Source: libcurl +See-also: + - CURLOPT_URL (3) + - curl_url (3) + - curl_url_cleanup (3) + - curl_url_dup (3) + - curl_url_get (3) + - curl_url_set (3) + - curl_url_strerror (3) +--- + +# NAME + +libcurl-url - URL interface overview + +# DESCRIPTION + The URL interface provides functions for parsing and generating URLs. -.SH INCLUDE + +# INCLUDE + You still only include in your code. -.SH CREATE -Create a handle that holds URL info and resources with \fIcurl_url(3)\fP: -.nf + +# CREATE + +Create a handle that holds URL info and resources with curl_url(3): +~~~c CURLU *h = curl_url(); -.fi -.SH CLEANUP -When done with it, clean it up with \fIcurl_url_cleanup(3)\fP -.nf +~~~ + +# CLEANUP + +When done with it, clean it up with curl_url_cleanup(3) +~~~c curl_url_cleanup(h); -.fi -.SH DUPLICATE -When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP: -.nf +~~~ + +# DUPLICATE + +When you need a copy of a handle, just duplicate it with curl_url_dup(3): +~~~c CURLU *nh = curl_url_dup(h); -.fi -.SH PARSING -By setting a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed +~~~ + +# PARSING + +By setting a URL to the handle with curl_url_set(3), the URL is parsed and stored in the handle. If the URL is not syntactically correct it returns an error instead. -.nf +~~~c rc = curl_url_set(h, CURLUPART_URL, "https://example.com:449/foo/bar?name=moo", 0); -.fi +~~~ The zero in the fourth argument is a bitmask for changing specific features. If successful, this stores the URL in its individual parts within the handle. -.SH REDIRECT + +# REDIRECT + When a handle already contains info about a URL, setting a relative URL makes it "redirect" to that. -.nf +~~~c rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0); -.fi -.SH "GET URL" -The \fBCURLU\fP handle represents a URL and you can easily extract that with -\fIcurl_url_get(3)\fP: -.nf +~~~ + +# GET URL + +The **CURLU** handle represents a URL and you can easily extract that with +curl_url_get(3): +~~~c char *url; rc = curl_url_get(h, CURLUPART_URL, &url, 0); curl_free(url); -.fi +~~~ The zero in the fourth argument is a bitmask for changing specific features. -.SH "GET PARTS" + +# GET PARTS + When a URL has been parsed or parts have been set, you can extract those pieces from the handle at any time. -.nf +~~~c rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0); rc = curl_url_get(h, CURLUPART_HOST, &host, 0); rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0); @@ -84,18 +95,20 @@ pieces from the handle at any time. rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0); rc = curl_url_get(h, CURLUPART_USER, &user, 0); rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0); -.fi +~~~ Extracted parts are not URL decoded unless the user also asks for it with the -\fICURLU_URLDECODE\fP flag set in the fourth bitmask argument. +*CURLU_URLDECODE* flag set in the fourth bitmask argument. -Remember to free the returned string with \fIcurl_free(3)\fP when you are done +Remember to free the returned string with curl_free(3) when you are done with it! -.SH "SET PARTS" + +# SET PARTS + A user set individual URL parts, either after having parsed a full URL or instead of parsing such. -.nf +~~~c rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0); rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0); rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0); @@ -105,20 +118,22 @@ instead of parsing such. rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0); rc = curl_url_set(urlp, CURLUPART_USER, "john", 0); rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0); -.fi +~~~ Set parts are not URL encoded unless the user asks for it with the -\fICURLU_URLENCODE\fP flag. -.SH "CURLU_APPENDQUERY" +*CURLU_URLENCODE* flag. + +# CURLU_APPENDQUERY + An application can append a string to the right end of the query part with the -\fICURLU_APPENDQUERY\fP flag to \fIcurl_url_set(3)\fP. +*CURLU_APPENDQUERY* flag to curl_url_set(3). Imagine a handle that holds the URL "https://example.com/?shoes=2". An application can then add the string "hat=1" to the query part like this: -.nf +~~~c rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY); -.fi +~~~ It notices the lack of an ampersand (&) separator and injects one, and the handle's full URL then equals "https://example.com/?shoes=2&hat=1". @@ -127,25 +142,19 @@ The appended string can of course also get URL encoded on add, and if asked to URL encode, the encoding process skips the '=' character. For example, append "candy=N&N" to what we already have, and URL encode it to deal with the ampersand in the data: -.nf +~~~c rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N", CURLU_APPENDQUERY | CURLU_URLENCODE); -.fi +~~~ Now the URL looks like -.nf +~~~c https://example.com/?shoes=2&hat=1&candy=N%26N -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + The URL API was introduced in libcurl 7.62.0. A URL with a literal IPv6 address can be parsed even when IPv6 support is not enabled. -.SH "SEE ALSO" -.BR curl_url (3), -.BR curl_url_cleanup (3), -.BR curl_url_dup (3), -.BR curl_url_get (3), -.BR curl_url_set (3), -.BR curl_url_strerror (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/libcurl-ws.3 b/docs/libcurl/libcurl-ws.md similarity index 60% rename from docs/libcurl/libcurl-ws.3 rename to docs/libcurl/libcurl-ws.md index 2a96b8bc49c..40f7c039c60 100644 --- a/docs/libcurl/libcurl-ws.3 +++ b/docs/libcurl/libcurl-ws.md @@ -1,36 +1,35 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH libcurl 3 "10 Sep 2018" "libcurl" "libcurl" -.SH NAME -libcurl-ws \- WebSocket interface overview -.SH DESCRIPTION +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECT_ONLY (3) + - CURLOPT_WRITEFUNCTION (3) + - CURLOPT_WS_OPTIONS (3) + - curl_easy_init (3) + - curl_ws_meta (3) + - curl_ws_recv (3) + - curl_ws_send (3) +--- + +# NAME + +libcurl-ws - WebSocket interface overview + +# DESCRIPTION + The WebSocket interface provides functions for receiving and sending WebSocket data. -.SH INCLUDE + +# INCLUDE + You still only include in your code. -.SH SETUP -WebSocket is also often known as \fIWebSockets\fP, in plural. It is done by + +# SETUP + +WebSocket is also often known as *WebSockets*, in plural. It is done by upgrading a regular HTTP(S) GET request to a WebSocket connection. WebSocket is a TCP-like message-based communication protocol done over HTTP, @@ -44,7 +43,9 @@ A WebSocket request is done as an HTTP/1 GET request with an "Upgrade WebSocket" request header field. When the upgrade is accepted by the server, it responds with a 101 Switching and then the client can speak WebSocket with the server. The communication can happen in both directions at the same time. -.SH MESSAGES + +# MESSAGES + WebSocket communication is message based. That means that both ends send and receive entire messages, not streams like TCP. A WebSocket message is sent over the wire in one or more frames. Each frame in a message can have a size @@ -58,9 +59,11 @@ arrive for the same frame. A message has an unknown size until the last frame header for the message has been received since only frames have set sizes. -.SH "Raw mode" + +# Raw mode + libcurl can be told to speak WebSocket in "raw mode" by setting the -\fBCURLWS_RAW_MODE\fP bit to the \fICURLOPT_WS_OPTIONS(3)\fP option. +**CURLWS_RAW_MODE** bit to the CURLOPT_WS_OPTIONS(3) option. Raw WebSocket means that libcurl passes on the data from the network without parsing it leaving that entirely to the application. This mode assumes that @@ -69,50 +72,52 @@ itself. This mode is intended for applications that already have a WebSocket parser/engine that want to switch over to use libcurl for enabling WebSocket, -but keep parts of the existing software architecture. -.SH PING +and keep parts of the existing software architecture. + +# PING + WebSocket is designed to allow long-lived sessions and in order to keep the connections alive, both ends can send PING messages for the other end to respond with a PONG. libcurl automatically responds to server PING messages with a PONG. It does not send any PING messages automatically. -.SH MODELS + +# MODELS + Because of the many different ways WebSocket can be used, which is much more flexible than limited to plain downloads or uploads, libcurl offers two different API models to use it: -1. Using a write callback with \fICURLOPT_WRITEFUNCTION(3)\fP much like other +1. Using a write callback with CURLOPT_WRITEFUNCTION(3) much like other downloads for when the traffic is download oriented. -2. Using \fICURLOPT_CONNECT_ONLY(3)\fP and use the WebSocket recv/send +2. Using CURLOPT_CONNECT_ONLY(3) and use the WebSocket recv/send functions. -.SH "Callback model" + +# Callback model + When a write callback is set and a WebSocket transfer is performed, the callback is called to deliver all WebSocket data that arrives. -The callback can then call \fIcurl_ws_meta(3)\fP to learn about the details of +The callback can then call curl_ws_meta(3) to learn about the details of the incoming data fragment. -.SH "CONNECT_ONLY model" -By setting \fICURLOPT_CONNECT_ONLY(3)\fP to \fB2L\fP, the transfer only + +# CONNECT_ONLY model + +By setting CURLOPT_CONNECT_ONLY(3) to **2L**, the transfer only establishes and setups the WebSocket communication and then returns control back to the application. Once such a setup has been successfully performed, the application can proceed -and use \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP freely to exchange +and use curl_ws_recv(3) and curl_ws_send(3) freely to exchange WebSocket messages with the server. -.SH AVAILABILITY + +# AVAILABILITY + The WebSocket API was introduced as experimental in 7.86.0 and is still experimental today. It is only built-in if explicitly opted in at build time. We discourage use of the WebSocket API in production because of its experimental state. We might change API, ABI and behavior before this "goes live". -.SH "SEE ALSO" -.BR curl_easy_init (3), -.BR curl_ws_meta (3), -.BR curl_ws_recv (3), -.BR curl_ws_send (3), -.BR CURLOPT_CONNECT_ONLY (3), -.BR CURLOPT_WRITEFUNCTION (3), -.BR CURLOPT_WS_OPTIONS (3) diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.md similarity index 63% rename from docs/libcurl/libcurl.3 rename to docs/libcurl/libcurl.md index dd4163a7e3a..fd574a66645 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.md @@ -1,87 +1,97 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH libcurl 3 "March 19, 2002" "libcurl" "libcurl" -.SH NAME -libcurl \- client-side URL transfers -.SH DESCRIPTION +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl +Section: 3 +Source: libcurl +See-also: + - libcurl-easy (3) + - libcurl-multi (3) + - libcurl-security (3) + - libcurl-thread (3) +--- + +# NAME + +libcurl - client-side URL transfers + +# DESCRIPTION + This is a short overview on how to use libcurl in your C programs. There are specific man pages for each function mentioned in here. See -\fIlibcurl-easy(3)\fP, \fIlibcurl-multi(3)\fP, \fIlibcurl-share(3)\fP, -\fIlibcurl-url(3)\fP, \fIlibcurl-ws(3)\fP and \fIlibcurl-tutorial(3)\fP for +libcurl-easy(3), libcurl-multi(3), libcurl-share(3), +libcurl-url(3), libcurl-ws(3) and libcurl-tutorial(3) for in-depth understanding on how to program with libcurl. There are many bindings available that bring libcurl access to your favorite language. Look elsewhere for documentation on those. -.SH TRANSFERS -To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP + +# TRANSFERS + +To transfer files, you create an "easy handle" using curl_easy_init(3) for a single individual transfer (in either direction). You then set your -desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options -you set with \fIcurl_easy_setopt(3)\fP stick. They are then used for every +desired set of options in that handle with curl_easy_setopt(3). Options +you set with curl_easy_setopt(3) stick. They are then used for every repeated use of this handle until you either change the option, or you reset -them all with \fIcurl_easy_reset(3)\fP. +them all with curl_easy_reset(3). To actually transfer data you have the option of using the "easy" interface, or the "multi" interface. The easy interface is a synchronous interface with which you call -\fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is +curl_easy_perform(3) and let it perform the transfer. When it is completed, the function returns and you can continue. More details are found in -the \fIlibcurl-easy(3)\fP man page. +the libcurl-easy(3) man page. The multi interface on the other hand is an asynchronous interface, that you call and that performs only a little piece of the transfer on each invoke. It is perfect if you want to do things while the transfer is in progress, or similar. The multi interface allows you to select() on libcurl action, and even to easily download multiple files simultaneously using a single -thread. See further details in the \fIlibcurl-multi(3)\fP man page. +thread. See further details in the libcurl-multi(3) man page. + +# SUPPORT INTERFACES -.SH "SUPPORT INTERFACES" There is also a series of other helpful functions and interface families to use, including these: -.RS -.IP curl_version_info() + +## curl_version_info() + gets detailed libcurl (and other used libraries) version info. See -\fIcurl_version_info(3)\fP -.IP curl_getdate() -converts a date string to time_t. See \fIcurl_getdate(3)\fP -.IP curl_easy_getinfo() -get information about a performed transfer. See \fIcurl_easy_getinfo(3)\fP -.IP curl_mime_addpart() -helps building an HTTP form POST. See \fIcurl_mime_addpart(3)\fP -.IP curl_slist_append() -builds a linked list. See \fIcurl_slist_append(3)\fP -.IP "Sharing data between transfers" +curl_version_info(3) + +## curl_getdate() + +converts a date string to time_t. See curl_getdate(3) + +## curl_easy_getinfo() + +get information about a performed transfer. See curl_easy_getinfo(3) + +## curl_mime_addpart() + +helps building an HTTP form POST. See curl_mime_addpart(3) + +## curl_slist_append() + +builds a linked list. See curl_slist_append(3) + +## Sharing data between transfers + You can have multiple easy handles share certain data, even if they are used in different threads. This magic is setup using the share interface, as -described in the \fIlibcurl-share(3)\fP man page. -.IP "URL Parsing" -URL parsing and manipulations. See \fIlibcurl-url(3)\fP -.IP "WebSocket communication" -See \fIlibcurl-ws(3)\fP -.RE - -.SH "LINKING WITH LIBCURL" +described in the libcurl-share(3) man page. + +## URL Parsing + +URL parsing and manipulations. See libcurl-url(3) + +## WebSocket communication + +See libcurl-ws(3) + +# LINKING WITH LIBCURL + On unix-like machines, there is a tool named curl-config that gets installed with the rest of the curl stuff when 'make install' is performed. @@ -90,7 +100,7 @@ and developers to learn about libcurl and how to use it. Run 'curl-config --libs' to get the (additional) linker options you need to link with the particular version of libcurl you have installed. See the -\fIcurl-config(1)\fP man page for further details. +*curl-config(1)* man page for further details. Unix-like operating system that ship libcurl as part of their distributions often do not provide the curl-config tool, but simply install the library and @@ -98,42 +108,51 @@ headers in the common path for this purpose. Many Linux and similar systems use pkg-config to provide build and link options about libraries and libcurl supports that as well. -.SH "LIBCURL SYMBOL NAMES" + +# LIBCURL SYMBOL NAMES + All public functions in the libcurl interface are prefixed with 'curl_' (with a lowercase c). You can find other functions in the library source code, but other prefixes indicate that the functions are private and may change without further notice in the next release. Only use documented functions and functionality! -.SH "PORTABILITY" + +# PORTABILITY + libcurl works -.B exactly +**exactly** the same, on any of the platforms it compiles and builds on. -.SH "THREADS" + +# THREADS + libcurl is thread safe but there are a few exceptions. Refer to -\fIlibcurl-thread(3)\fP for more information. +libcurl-thread(3) for more information. + +# PERSISTENT CONNECTIONS -.SH "PERSISTENT CONNECTIONS" Persistent connections means that libcurl can reuse the same connection for several transfers, if the conditions are right. libcurl always attempts to use persistent connections. Whenever you use -\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl +curl_easy_perform(3) or curl_multi_perform(3) etc, libcurl attempts to use an existing connection to do the transfer, and if none exists it opens a new one that is subject for reuse on a possible following call to -\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. +curl_easy_perform(3) or curl_multi_perform(3). To allow libcurl to take full advantage of persistent connections, you should do as many of your file transfers as possible using the same handle. -If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all +If you use the easy interface, and you call curl_easy_cleanup(3), all the possibly open connections held by libcurl are closed and forgotten. When you have created a multi handle and are using the multi interface, the connection pool is instead kept in the multi handle so closing and creating new easy handles to do transfers do not affect them. Instead all added easy handles can take advantage of the single shared pool. -.SH "GLOBAL CONSTANTS" + +# GLOBAL CONSTANTS + There are a variety of constants that libcurl uses, mainly through its internal use of other libraries, which are too complicated for the library loader to set up. Therefore, a program must call a library @@ -142,19 +161,19 @@ the library code. For example, when libcurl is built for SSL capability via the GNU TLS library, there is an elaborate tree inside that library that describes the SSL protocol. -\fIcurl_global_init(3)\fP is the function that you must call. This may +curl_global_init(3) is the function that you must call. This may allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so -the companion function \fIcurl_global_cleanup(3)\fP releases them. +the companion function curl_global_cleanup(3) releases them. If libcurl was compiled with support for multiple SSL backends, the function -\fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP +curl_global_sslset(3) can be called before curl_global_init(3) to select the active SSL backend. The global constant functions are thread-safe since libcurl 7.84.0 if -\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set -(most platforms). Read \fIlibcurl-thread(3)\fP for thread safety guidelines. +curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set +(most platforms). Read libcurl-thread(3) for thread safety guidelines. -If the global constant functions are \fInot thread safe\fP, then you must +If the global constant functions are *not thread safe*, then you must not call them when any other thread in the program is running. It is not good enough that no other thread is using libcurl at the time, because these functions internally call similar functions of other @@ -162,11 +181,11 @@ libraries, and those functions are similarly thread-unsafe. You cannot generally know what these libraries are, or whether other threads are using them. -If the global constant functions are \fInot thread safe\fP, then the basic rule +If the global constant functions are *not thread safe*, then the basic rule for constructing a program that uses libcurl is this: Call -\fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately +curl_global_init(3), with a *CURL_GLOBAL_ALL* argument, immediately after the program starts, while it is still only one thread and before it uses -libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the +libcurl at all. Call curl_global_cleanup(3) immediately before the program exits, when the program is again only one thread and after its last use of libcurl. @@ -184,11 +203,11 @@ know whether they use libcurl or not. And its code does not necessarily run at the start and end of the whole program. A module like this must have global constant functions of its own, just like -\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus +curl_global_init(3) and curl_global_cleanup(3). The module thus has control at the beginning and end of the program and has a place to call the libcurl functions. If multiple modules in the program use libcurl, they all separately call the libcurl functions, and that is OK because only the -first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP in a +first curl_global_init(3) and the last curl_global_cleanup(3) in a program change anything. (libcurl uses a reference count in static memory). In a C++ module, it is common to deal with the global constant situation by @@ -197,28 +216,28 @@ the module. A program always has exactly one object of the class, in static storage. That way, the program automatically calls the constructor of the object as the program starts up and the destructor as it terminates. As the author of this libcurl-using module, you can make the constructor call -\fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP +curl_global_init(3) and the destructor call curl_global_cleanup(3) and satisfy libcurl's requirements without your user having to think about it. (Caveat: If you are initializing libcurl from a Windows DLL you should not -initialize it from \fIDllMain\fP or a static initializer because Windows holds +initialize it from *DllMain* or a static initializer because Windows holds the loader lock during that time and it could cause a deadlock.) -\fIcurl_global_init(3)\fP has an argument that tells what particular parts of +curl_global_init(3) has an argument that tells what particular parts of the global constant environment to set up. In order to successfully use any -value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you +value except *CURL_GLOBAL_ALL* (which says to set up the whole thing), you must have specific knowledge of internal workings of libcurl and all other parts of the program of which it is part. A special part of the global constant environment is the identity of the -memory allocator. \fIcurl_global_init(3)\fP selects the system default memory -allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your -own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a +memory allocator. curl_global_init(3) selects the system default memory +allocator, but you can use curl_global_init_mem(3) to supply one of your +own. However, there is no way to use curl_global_init_mem(3) in a modular program -- all modules in the program that might use libcurl would have to agree on one allocator. There is a failsafe in libcurl that makes it usable in simple situations without you having to worry about the global constant environment at all: -\fIcurl_easy_init(3)\fP sets up the environment itself if it has not been done +curl_easy_init(3) sets up the environment itself if it has not been done yet. The resources it acquires to do so get released by the operating system automatically when the program exits. diff --git a/docs/libcurl/mksymbolsmanpage.pl b/docs/libcurl/mksymbolsmanpage.pl index 3bc68694918..fb59eea7a89 100755 --- a/docs/libcurl/mksymbolsmanpage.pl +++ b/docs/libcurl/mksymbolsmanpage.pl @@ -23,8 +23,6 @@ # * # *************************************************************************** -my $version="7.41.0"; - use POSIX qw(strftime); my @ts; if (defined($ENV{SOURCE_DATE_EPOCH})) { @@ -36,33 +34,21 @@ my $year = strftime "%Y", @ts; 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 -.\\" * -.\\" ************************************************************************** -.TH libcurl-symbols 3 "$date" "libcurl" "libcurl" -.SH NAME -libcurl-symbols \\- libcurl symbol version information -.SH "libcurl symbols" +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: libcurl-symbols +Section: 3 +Source: libcurl +See-also: + - libcurl (3) + - libcurl-easy (3) + - libcurl-multi (3) + - libcurl-security (3) + - libcurl-thread (3) +--- +# libcurl symbols + This man page details version information for public symbols provided in the libcurl header files. This lists the first version in which the symbol was introduced and for some symbols two additional information pieces: @@ -91,13 +77,13 @@ if($rest =~ s/^([0-9.]*) *//) { $rem = $1; } - print ".IP $symbol\nIntroduced in $intro\n"; + print "\n## $symbol\nIntroduced in $intro."; if($dep) { - print "Deprecated since $dep\n"; + print " Deprecated since $dep."; } if($rem) { - print "Last used in $rem\n"; + print " Last used in $rem."; } + print "\n"; } - } diff --git a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 deleted file mode 100644 index b1f5b988351..00000000000 --- a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_ACTIVESOCKET 3 "12 Sep 2015" "libcurl" "libcurl" -.SH NAME -CURLINFO_ACTIVESOCKET \- get the active socket -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_ACTIVESOCKET, - curl_socket_t *socket); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_socket_t to receive the most recently active socket -used for the transfer connection by this curl session. If the socket is no -longer valid, \fICURL_SOCKET_BAD\fP is returned. When you are finished working -with the socket, you must call \fIcurl_easy_cleanup(3)\fP as usual on the easy -handle and let libcurl close the socket and cleanup other resources associated -with the handle. This option returns the active socket only after the transfer -is complete, and is typically used in combination with -\fICURLOPT_CONNECT_ONLY(3)\fP, which skips the transfer phase. - -\fICURLINFO_ACTIVESOCKET(3)\fP was added as a replacement for -\fICURLINFO_LASTSOCKET(3)\fP since that one is not working on all platforms. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_socket_t sockfd; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Do not do the transfer - only connect to host */ - curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); - res = curl_easy_perform(curl); - - /* Extract the socket from the curl handle */ - res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); - - if(res != CURLE_OK) { - printf("Error: %s\\n", curl_easy_strerror(res)); - return 1; - } - } -} -.fi -.SH AVAILABILITY -Added in 7.45.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_LASTSOCKET (3), -.BR CURLOPT_CONNECT_ONLY (3) diff --git a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md new file mode 100644 index 00000000000..7e106ed0bc8 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_ACTIVESOCKET +Section: 3 +Source: libcurl +See-also: + - CURLINFO_LASTSOCKET (3) + - CURLOPT_CONNECT_ONLY (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_ACTIVESOCKET - get the active socket + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_ACTIVESOCKET, + curl_socket_t *socket); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_socket_t to receive the most recently active socket +used for the transfer connection by this curl session. If the socket is no +longer valid, *CURL_SOCKET_BAD* is returned. When you are finished working +with the socket, you must call curl_easy_cleanup(3) as usual on the easy +handle and let libcurl close the socket and cleanup other resources associated +with the handle. This option returns the active socket only after the transfer +is complete, and is typically used in combination with +CURLOPT_CONNECT_ONLY(3), which skips the transfer phase. + +CURLINFO_ACTIVESOCKET(3) was added as a replacement for +CURLINFO_LASTSOCKET(3) since that one is not working on all platforms. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_socket_t sockfd; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Do not do the transfer - only connect to host */ + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + res = curl_easy_perform(curl); + + /* Extract the socket from the curl handle */ + res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); + + if(res != CURLE_OK) { + printf("Error: %s\n", curl_easy_strerror(res)); + return 1; + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.45.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 deleted file mode 100644 index 977ef5736bb..00000000000 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_APPCONNECT_TIME 3 "28 Aug 2015" "libcurl" "libcurl" -.SH NAME -CURLINFO_APPCONNECT_TIME \- get the time until the SSL/SSH handshake is completed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME, - double *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the time, in seconds, it took from the -start until the SSL/SSH connect/handshake to the remote host was completed. -This time is most often close to the \fICURLINFO_PRETRANSFER_TIME(3)\fP time, -except for cases such as HTTP pipelining where the pretransfer time can be -delayed due to waits in line for the pipeline and more. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - double connect; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME, &connect); - if(CURLE_OK == res) { - printf("Time: %.1f", connect); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_APPCONNECT_TIME_T (3) diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md new file mode 100644 index 00000000000..17fb465801a --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_APPCONNECT_TIME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_APPCONNECT_TIME_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_APPCONNECT_TIME - get the time until the SSL/SSH handshake is completed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME, + double *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the SSL/SSH connect/handshake to the remote host was completed. +This time is most often close to the CURLINFO_PRETRANSFER_TIME(3) time, +except for cases such as HTTP pipelining where the pretransfer time can be +delayed due to waits in line for the pipeline and more. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double connect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME, &connect); + if(CURLE_OK == res) { + printf("Time: %.1f", connect); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 deleted file mode 100644 index 7a2ecff23b4..00000000000 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_APPCONNECT_TIME_T 3 "28 Apr 2018" "libcurl" "libcurl" -.SH NAME -CURLINFO_APPCONNECT_TIME_T \- time until the SSL/SSH handshake completed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the time, in microseconds, it took -from the start until the SSL/SSH connect/handshake to the remote host was -completed. This time is most often close to the -\fICURLINFO_PRETRANSFER_TIME_T(3)\fP time, except for cases such as HTTP -pipelining where the pretransfer time can be delayed due to waits in line for -the pipeline and more. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_off_t connect; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME_T, &connect); - if(CURLE_OK == res) { - printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000, - (long)(connect % 1000000)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_APPCONNECT_TIME (3) diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md new file mode 100644 index 00000000000..cc4f2b8589f --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_APPCONNECT_TIME_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_APPCONNECT_TIME (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_APPCONNECT_TIME_T - time until the SSL/SSH handshake completed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the time, in microseconds, it took +from the start until the SSL/SSH connect/handshake to the remote host was +completed. This time is most often close to the +CURLINFO_PRETRANSFER_TIME_T(3) time, except for cases such as HTTP +pipelining where the pretransfer time can be delayed due to waits in line for +the pipeline and more. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t connect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME_T, &connect); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000, + (long)(connect % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CAINFO.3 b/docs/libcurl/opts/CURLINFO_CAINFO.3 deleted file mode 100644 index 61c3e14feaf..00000000000 --- a/docs/libcurl/opts/CURLINFO_CAINFO.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CAINFO 3 "20 May 2022" "libcurl" "libcurl" -.SH NAME -CURLINFO_CAINFO \- get the default built-in CA certificate path -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CAINFO, char **path); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive the pointer to a null-terminated -string holding the default built-in path used for the \fICURLOPT_CAINFO(3)\fP -option unless set by the user. - -Note that in a situation where libcurl has been built to support multiple TLS -libraries, this option might return a string even if the specific TLS library -currently set to be used does not support \fICURLOPT_CAINFO(3)\fP. - -This is a path identifying a single file containing CA certificates. - -The \fBpath\fP pointer is set to NULL if there is no default path. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - char *cainfo = NULL; - curl_easy_getinfo(curl, CURLINFO_CAINFO, &cainfo); - if(cainfo) { - printf("default ca info path: %s\\n", cainfo); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.84.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CAPATH (3) diff --git a/docs/libcurl/opts/CURLINFO_CAINFO.md b/docs/libcurl/opts/CURLINFO_CAINFO.md new file mode 100644 index 00000000000..44b253967da --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CAINFO.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CAINFO +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CAPATH (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CAINFO - get the default built-in CA certificate path + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CAINFO, char **path); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive the pointer to a null-terminated +string holding the default built-in path used for the CURLOPT_CAINFO(3) +option unless set by the user. + +Note that in a situation where libcurl has been built to support multiple TLS +libraries, this option might return a string even if the specific TLS library +currently set to be used does not support CURLOPT_CAINFO(3). + +This is a path identifying a single file containing CA certificates. + +The **path** pointer is set to NULL if there is no default path. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char *cainfo = NULL; + curl_easy_getinfo(curl, CURLINFO_CAINFO, &cainfo); + if(cainfo) { + printf("default ca info path: %s\n", cainfo); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.84.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CAPATH.3 b/docs/libcurl/opts/CURLINFO_CAPATH.3 deleted file mode 100644 index 56f05d1824d..00000000000 --- a/docs/libcurl/opts/CURLINFO_CAPATH.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CAPATH 3 "20 May 2022" "libcurl" "libcurl" -.SH NAME -CURLINFO_CAPATH \- get the default built-in CA path string -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CAPATH, char **path); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive the pointer to a null-terminated -string holding the default built-in path used for the \fICURLOPT_CAPATH(3)\fP -option unless set by the user. - -Note that in a situation where libcurl has been built to support multiple TLS -libraries, this option might return a string even if the specific TLS library -currently set to be used does not support \fICURLOPT_CAPATH(3)\fP. - -This is a path identifying a directory. - -The \fBpath\fP pointer is set to NULL if there is no default path. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - char *capath = NULL; - curl_easy_getinfo(curl, CURLINFO_CAPATH, &capath); - if(capath) { - printf("default ca path: %s\\n", capath); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.84.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CAINFO (3) diff --git a/docs/libcurl/opts/CURLINFO_CAPATH.md b/docs/libcurl/opts/CURLINFO_CAPATH.md new file mode 100644 index 00000000000..46499e7f675 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CAPATH.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CAPATH +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CAINFO (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CAPATH - get the default built-in CA path string + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CAPATH, char **path); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive the pointer to a null-terminated +string holding the default built-in path used for the CURLOPT_CAPATH(3) +option unless set by the user. + +Note that in a situation where libcurl has been built to support multiple TLS +libraries, this option might return a string even if the specific TLS library +currently set to be used does not support CURLOPT_CAPATH(3). + +This is a path identifying a directory. + +The **path** pointer is set to NULL if there is no default path. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char *capath = NULL; + curl_easy_getinfo(curl, CURLINFO_CAPATH, &capath); + if(capath) { + printf("default ca path: %s\n", capath); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.84.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.3 b/docs/libcurl/opts/CURLINFO_CERTINFO.3 deleted file mode 100644 index 46e93ccd3fe..00000000000 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.3 +++ /dev/null @@ -1,105 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CERTINFO 3 "12 Sep 2015" "libcurl" "libcurl" -.SH NAME -CURLINFO_CERTINFO \- get the TLS certificate chain -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO, - struct curl_certinfo **chainp); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIstruct curl_certinfo *\fP and it is set to point to a -struct that holds info about the server's certificate chain, assuming you had -\fICURLOPT_CERTINFO(3)\fP enabled when the request was made. - -.nf -struct curl_certinfo { - int num_of_certs; - struct curl_slist **certinfo; -}; -.fi - -The \fIcertinfo\fP struct member is an array of linked lists of certificate -information. The \fInum_of_certs\fP struct member is the number of -certificates which is the number of elements in the array. Each certificate's -list has items with textual information in the format "name:content" such as -\&"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on -the SSL backend and the certificate. -.SH PROTOCOLS -All TLS-based -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); - - /* connect to any HTTPS site, trusted or not */ - curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); - curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); - - curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L); - - res = curl_easy_perform(curl); - - if(!res) { - int i; - struct curl_certinfo *ci; - res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); - - if(!res) { - printf("%d certs!\\n", ci->num_of_certs); - - for(i = 0; i < ci->num_of_certs; i++) { - struct curl_slist *slist; - - for(slist = ci->certinfo[i]; slist; slist = slist->next) - printf("%s\\n", slist->data); - } - } - } - curl_easy_cleanup(curl); - } -} -.fi - -See also the \fIcertinfo.c\fP example. -.SH AVAILABILITY -This option is only working in libcurl built with OpenSSL, GnuTLS, Schannel or -Secure Transport. GnuTLS support added in 7.42.0. Schannel support added in -7.50.0. Secure Transport support added in 7.79.0. - -Added in 7.19.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CAPATH (3) diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.md b/docs/libcurl/opts/CURLINFO_CERTINFO.md new file mode 100644 index 00000000000..46f28375b98 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.md @@ -0,0 +1,101 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CERTINFO +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CAPATH (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CERTINFO - get the TLS certificate chain + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO, + struct curl_certinfo **chainp); +~~~ + +# DESCRIPTION + +Pass a pointer to a *struct curl_certinfo ** and it is set to point to a +struct that holds info about the server's certificate chain, assuming you had +CURLOPT_CERTINFO(3) enabled when the request was made. + +~~~c +struct curl_certinfo { + int num_of_certs; + struct curl_slist **certinfo; +}; +~~~ + +The *certinfo* struct member is an array of linked lists of certificate +information. The *num_of_certs* struct member is the number of +certificates which is the number of elements in the array. Each certificate's +list has items with textual information in the format "name:content" such as +&"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on +the SSL backend and the certificate. + +# PROTOCOLS + +All TLS-based + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); + + /* connect to any HTTPS site, trusted or not */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); + + curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L); + + res = curl_easy_perform(curl); + + if(!res) { + int i; + struct curl_certinfo *ci; + res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); + + if(!res) { + printf("%d certs!\n", ci->num_of_certs); + + for(i = 0; i < ci->num_of_certs; i++) { + struct curl_slist *slist; + + for(slist = ci->certinfo[i]; slist; slist = slist->next) + printf("%s\n", slist->data); + } + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +See also the *certinfo.c* example. + +# AVAILABILITY + +This option is only working in libcurl built with OpenSSL, GnuTLS, Schannel or +Secure Transport. GnuTLS support added in 7.42.0. Schannel support added in +7.50.0. Secure Transport support added in 7.79.0. + +Added in 7.19.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 deleted file mode 100644 index d59d16adbea..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 +++ /dev/null @@ -1,84 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONDITION_UNMET 3 "1 Sep 2015" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONDITION_UNMET \- get info on unmet time conditional or 304 HTTP response. -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONDITION_UNMET, - long *unmet); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the number 1 if the condition provided in -the previous request did not match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas, -if this returns a 1 you know that the reason you did not get data in return is -because it did not fulfill the condition. The long this argument points to -gets a zero stored if the condition instead was met. This can also return 1 if -the server responded with a 304 HTTP status code, for example after sending a -custom "If-Match-*" header. -.SH PROTOCOLS -HTTP and some -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* January 1, 2020 is 1577833200 */ - curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); - - /* If-Modified-Since the above time stamp */ - curl_easy_setopt(curl, CURLOPT_TIMECONDITION, - (long)CURL_TIMECOND_IFMODSINCE); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - /* check the time condition */ - long unmet; - res = curl_easy_getinfo(curl, CURLINFO_CONDITION_UNMET, &unmet); - if(!res) { - printf("The time condition was %sfulfilled\\n", unmet?"NOT":""); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.19.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_TIMECONDITION (3), -.BR CURLOPT_TIMEVALUE (3) diff --git a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md new file mode 100644 index 00000000000..aca04f1c9b9 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONDITION_UNMET +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TIMECONDITION (3) + - CURLOPT_TIMEVALUE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONDITION_UNMET - get info on unmet time conditional or 304 HTTP response. + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONDITION_UNMET, + long *unmet); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the number 1 if the condition provided in +the previous request did not match (see CURLOPT_TIMECONDITION(3)). Alas, +if this returns a 1 you know that the reason you did not get data in return is +because it did not fulfill the condition. The long this argument points to +gets a zero stored if the condition instead was met. This can also return 1 if +the server responded with a 304 HTTP status code, for example after sending a +custom "If-Match-*" header. + +# PROTOCOLS + +HTTP and some + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* January 1, 2020 is 1577833200 */ + curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); + + /* If-Modified-Since the above time stamp */ + curl_easy_setopt(curl, CURLOPT_TIMECONDITION, + (long)CURL_TIMECOND_IFMODSINCE); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the time condition */ + long unmet; + res = curl_easy_getinfo(curl, CURLINFO_CONDITION_UNMET, &unmet); + if(!res) { + printf("The time condition was %sfulfilled\n", unmet?"NOT":""); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 deleted file mode 100644 index 299e2d5200c..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONNECT_TIME 3 "28 Aug 2015" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONNECT_TIME \- get the time until connect -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME, double *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the total time in seconds from the start -until the connection to the remote host (or proxy) was completed. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - double connect; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME, &connect); - if(CURLE_OK == res) { - printf("Time: %.1f", connect); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONNECT_TIME_T (3) diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md new file mode 100644 index 00000000000..1fde7669993 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONNECT_TIME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONNECT_TIME_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONNECT_TIME - get the time until connect + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME, double *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the total time in seconds from the start +until the connection to the remote host (or proxy) was completed. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double connect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME, &connect); + if(CURLE_OK == res) { + printf("Time: %.1f", connect); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 deleted file mode 100644 index d215839c255..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONNECT_TIME_T 3 "28 Apr 2018" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONNECT_TIME_T \- get the time until connect -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the total time in microseconds from -the start until the connection to the remote host (or proxy) was completed. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_off_t connect; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME_T, &connect); - if(CURLE_OK == res) { - printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000, - (long)(connect % 1000000)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONNECT_TIME (3), -.BR CURLOPT_CONNECTTIMEOUT (3) diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md new file mode 100644 index 00000000000..cd72cdd077d --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONNECT_TIME_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONNECT_TIME (3) + - CURLOPT_CONNECTTIMEOUT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONNECT_TIME_T - get the time until connect + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the total time in microseconds from +the start until the connection to the remote host (or proxy) was completed. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t connect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME_T, &connect); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000, + (long)(connect % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONN_ID.3 b/docs/libcurl/opts/CURLINFO_CONN_ID.3 deleted file mode 100644 index 1b9da9338d5..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONN_ID.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONN_ID 3 "07 June 2023" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONN_ID \- get the ID of the last connection used by the handle -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONN_ID, - curl_off_t *conn_id); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIcurl_off_t\fP to receive the connection identifier last -used by the handle. Stores -1 if there was no connection used. - -The connection id is unique among all connections using the same -connection cache. This is implicitly the case for all connections in the -same multi handle. - -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - curl_off_t conn_id; - res = curl_easy_getinfo(curl, CURLINFO_CONN_ID, &conn_id); - if(!res) { - printf("Connection used: %" CURL_FORMAT_CURL_OFF_T "\\n", conn_id); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 8.2.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_XFER_ID (3) diff --git a/docs/libcurl/opts/CURLINFO_CONN_ID.md b/docs/libcurl/opts/CURLINFO_CONN_ID.md new file mode 100644 index 00000000000..d4791b42caf --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONN_ID.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONN_ID +Section: 3 +Source: libcurl +See-also: + - CURLINFO_XFER_ID (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONN_ID - get the ID of the last connection used by the handle + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONN_ID, + curl_off_t *conn_id); +~~~ + +# DESCRIPTION + +Pass a pointer to a *curl_off_t* to receive the connection identifier last +used by the handle. Stores -1 if there was no connection used. + +The connection id is unique among all connections using the same +connection cache. This is implicitly the case for all connections in the +same multi handle. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t conn_id; + res = curl_easy_getinfo(curl, CURLINFO_CONN_ID, &conn_id); + if(!res) { + printf("Connection used: %" CURL_FORMAT_CURL_OFF_T "\n", conn_id); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 8.2.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 deleted file mode 100644 index fbb89b223ea..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD 3 "1 Sep 2015" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONTENT_LENGTH_DOWNLOAD \- get content-length of download -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD, - double *content_length); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the content-length of the download. This -is the value read from the Content-Length: field. Since 7.19.4, this returns --1 if the size is not known. - -\fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP is a newer replacement that returns a more -sensible variable type. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - /* check the size */ - double cl; - res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD, &cl); - if(!res) { - printf("Size: %.0f\\n", cl); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.6.1. Deprecated since 7.55.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONTENT_LENGTH_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md new file mode 100644 index 00000000000..1e01419bdb1 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONTENT_LENGTH_DOWNLOAD +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONTENT_LENGTH_UPLOAD (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONTENT_LENGTH_DOWNLOAD - get content-length of download + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD, + double *content_length); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the content-length of the download. This +is the value read from the Content-Length: field. Since 7.19.4, this returns +-1 if the size is not known. + +CURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3) is a newer replacement that returns a more +sensible variable type. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + double cl; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD, &cl); + if(!res) { + printf("Size: %.0f\n", cl); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.6.1. Deprecated since 7.55.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 deleted file mode 100644 index f924df26d28..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD_T 3 "25 May 2017" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONTENT_LENGTH_DOWNLOAD_T \- get content-length of download -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, - curl_off_t *content_length); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIcurl_off_t\fP to receive the content-length of the -download. This is the value read from the Content-Length: field. Stores -1 if -the size is not known. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - /* check the size */ - curl_off_t cl; - res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, &cl); - if(!res) { - printf("Download size: %" CURL_FORMAT_CURL_OFF_T "\\n", cl); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.55.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3) diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md new file mode 100644 index 00000000000..15016c84c13 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONTENT_LENGTH_DOWNLOAD_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONTENT_LENGTH_UPLOAD_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONTENT_LENGTH_DOWNLOAD_T - get content-length of download + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, + curl_off_t *content_length); +~~~ + +# DESCRIPTION + +Pass a pointer to a *curl_off_t* to receive the content-length of the +download. This is the value read from the Content-Length: field. Stores -1 if +the size is not known. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + curl_off_t cl; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, &cl); + if(!res) { + printf("Download size: %" CURL_FORMAT_CURL_OFF_T "\n", cl); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.55.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 deleted file mode 100644 index 418e3c7208e..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONTENT_LENGTH_UPLOAD 3 "1 Sep 2015" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONTENT_LENGTH_UPLOAD \- get the specified size of the upload -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD, - double *content_length); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the specified size of the upload. Since -7.19.4, this returns -1 if the size is not known. - -\fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP is a newer replacement that returns a -more sensible variable type. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the upload */ - res = curl_easy_perform(curl); - - if(!res) { - /* check the size */ - double cl; - res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD, &cl); - if(!res) { - printf("Size: %.0f\\n", cl); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.6.1. Deprecated since 7.55.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3) diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md new file mode 100644 index 00000000000..c90e19e72cb --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONTENT_LENGTH_UPLOAD +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONTENT_LENGTH_UPLOAD - get the specified size of the upload + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD, + double *content_length); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the specified size of the upload. Since +7.19.4, this returns -1 if the size is not known. + +CURLINFO_CONTENT_LENGTH_UPLOAD_T(3) is a newer replacement that returns a +more sensible variable type. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the upload */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + double cl; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD, &cl); + if(!res) { + printf("Size: %.0f\n", cl); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.6.1. Deprecated since 7.55.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 deleted file mode 100644 index 170c1080a96..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONTENT_LENGTH_UPLOAD_T 3 "25 May 2017" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONTENT_LENGTH_UPLOAD_T \- get the specified size of the upload -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD_T, - curl_off_t *content_length); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIcurl_off_t\fP to receive the specified size of the -upload. Stores -1 if the size is not known. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the upload */ - res = curl_easy_perform(curl); - - if(!res) { - /* check the size */ - curl_off_t cl; - res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD_T, &cl); - if(!res) { - printf("Upload size: %" CURL_FORMAT_CURL_OFF_T "\\n", cl); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.55.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3) diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md new file mode 100644 index 00000000000..319a3345e86 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONTENT_LENGTH_UPLOAD_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONTENT_LENGTH_UPLOAD_T - get the specified size of the upload + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD_T, + curl_off_t *content_length); +~~~ + +# DESCRIPTION + +Pass a pointer to a *curl_off_t* to receive the specified size of the +upload. Stores -1 if the size is not known. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the upload */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + curl_off_t cl; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD_T, &cl); + if(!res) { + printf("Upload size: %" CURL_FORMAT_CURL_OFF_T "\n", cl); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.55.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 deleted file mode 100644 index 1045821b5b6..00000000000 --- a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_CONTENT_TYPE 3 "1 Sep 2015" "libcurl" "libcurl" -.SH NAME -CURLINFO_CONTENT_TYPE \- get Content-Type -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_TYPE, char **ct); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive the content-type of the downloaded -object. This is the value read from the Content-Type: field. If you get NULL, -it means that the server did not send a valid Content-Type header or that the -protocol used does not support this. - -The \fBct\fP pointer is set to NULL or pointing to private memory. You MUST -NOT free it - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. - -The modern way to get this header from a response is to instead use the -\fIcurl_easy_header(3)\fP function. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - res = curl_easy_perform(curl); - - if(!res) { - /* extract the content-type */ - char *ct = NULL; - res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); - if(!res && ct) { - printf("Content-Type: %s\\n", ct); - } - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.9.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_header (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_HEADERFUNCTION (3) diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md new file mode 100644 index 00000000000..b8745725109 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_CONTENT_TYPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADERFUNCTION (3) + - curl_easy_getinfo (3) + - curl_easy_header (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_CONTENT_TYPE - get Content-Type + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_TYPE, char **ct); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive the content-type of the downloaded +object. This is the value read from the Content-Type: field. If you get NULL, +it means that the server did not send a valid Content-Type header or that the +protocol used does not support this. + +The **ct** pointer is set to NULL or pointing to private memory. You MUST +NOT free it - it gets freed when you call curl_easy_cleanup(3) on the +corresponding CURL handle. + +The modern way to get this header from a response is to instead use the +curl_easy_header(3) function. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the content-type */ + char *ct = NULL; + res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); + if(!res && ct) { + printf("Content-Type: %s\n", ct); + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.9.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_COOKIELIST.3 b/docs/libcurl/opts/CURLINFO_COOKIELIST.3 deleted file mode 100644 index 02e2490eb02..00000000000 --- a/docs/libcurl/opts/CURLINFO_COOKIELIST.3 +++ /dev/null @@ -1,86 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_COOKIELIST 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_COOKIELIST \- get all known cookies -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_COOKIELIST, - struct curl_slist **cookies); -.fi -.SH DESCRIPTION -Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all -cookies curl knows (expired ones, too). do not forget to call -\fIcurl_slist_free_all(3)\fP on the list after it has been used. If there are -no cookies (cookies for the handle have not been enabled or simply none have -been received) the 'struct curl_slist *' is made a NULL pointer. - -Since 7.43.0 cookies that were imported in the Set-Cookie format without a -domain name are not exported by this option. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* enable the cookie engine */ - curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); - - res = curl_easy_perform(curl); - - if(!res) { - /* extract all known cookies */ - struct curl_slist *cookies = NULL; - res = curl_easy_getinfo(curl, CURLINFO_COOKIELIST, &cookies); - if(!res && cookies) { - /* a linked list of cookies in cookie file format */ - struct curl_slist *each = cookies; - while(each) { - printf("%s\\n", each->data); - each = each->next; - } - /* we must free these cookies when we are done */ - curl_slist_free_all(cookies); - } - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.14.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_COOKIELIST (3) diff --git a/docs/libcurl/opts/CURLINFO_COOKIELIST.md b/docs/libcurl/opts/CURLINFO_COOKIELIST.md new file mode 100644 index 00000000000..60ac0f036a6 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_COOKIELIST.md @@ -0,0 +1,82 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_COOKIELIST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_COOKIELIST (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_COOKIELIST - get all known cookies + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_COOKIELIST, + struct curl_slist **cookies); +~~~ + +# DESCRIPTION + +Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all +cookies curl knows (expired ones, too). Do not forget to call +curl_slist_free_all(3) on the list after it has been used. If there are no +cookies (cookies for the handle have not been enabled or simply none have been +received) the 'struct curl_slist *' is made a NULL pointer. + +Since 7.43.0 cookies that were imported in the Set-Cookie format without a +domain name are not exported by this option. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable the cookie engine */ + curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract all known cookies */ + struct curl_slist *cookies = NULL; + res = curl_easy_getinfo(curl, CURLINFO_COOKIELIST, &cookies); + if(!res && cookies) { + /* a linked list of cookies in cookie file format */ + struct curl_slist *each = cookies; + while(each) { + printf("%s\n", each->data); + each = each->next; + } + /* we must free these cookies when we are done */ + curl_slist_free_all(cookies); + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.14.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 deleted file mode 100644 index 50f028b57a4..00000000000 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_EFFECTIVE_METHOD 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_EFFECTIVE_METHOD \- get the last used HTTP method -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_METHOD, - char **methodp); -.fi -.SH DESCRIPTION -Pass in a pointer to a char pointer and get the last used effective HTTP -method. - -In cases when you have asked libcurl to follow redirects, the method may not be -the same method the first request would use. - -The \fBmethodp\fP pointer is NULL or points to private memory. You MUST NOT -free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data"); - curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - char *method = NULL; - curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_METHOD, &method); - if(method) - printf("Redirected to method: %s\\n", method); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.72.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_CUSTOMREQUEST (3), -.BR CURLOPT_FOLLOWLOCATION (3) diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md new file mode 100644 index 00000000000..da2e2a016fd --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_EFFECTIVE_METHOD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CUSTOMREQUEST (3) + - CURLOPT_FOLLOWLOCATION (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_EFFECTIVE_METHOD - get the last used HTTP method + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_METHOD, + char **methodp); +~~~ + +# DESCRIPTION + +Pass in a pointer to a char pointer and get the last used effective HTTP +method. + +In cases when you have asked libcurl to follow redirects, the method may not be +the same method the first request would use. + +The **methodp** pointer is NULL or points to private memory. You MUST NOT +free - it gets freed when you call curl_easy_cleanup(3) on the +corresponding CURL handle. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *method = NULL; + curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_METHOD, &method); + if(method) + printf("Redirected to method: %s\n", method); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.72.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 deleted file mode 100644 index 810e7873e3c..00000000000 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_EFFECTIVE_URL 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_EFFECTIVE_URL \- get the last used URL -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_URL, char **urlp); -.fi -.SH DESCRIPTION -Pass in a pointer to a char pointer and get the last used effective URL. - -In cases when you have asked libcurl to follow redirects, it may not be the same -value you set with \fICURLOPT_URL(3)\fP. - -The \fBurlp\fP pointer is NULL or points to private memory. You MUST NOT free -- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding -CURL handle. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - char *url = NULL; - curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_URL, &url); - if(url) - printf("Redirect to: %s\\n", url); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_FOLLOWLOCATION (3) diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md new file mode 100644 index 00000000000..268ff2c67e8 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_EFFECTIVE_URL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FOLLOWLOCATION (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_EFFECTIVE_URL - get the last used URL + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_URL, char **urlp); +~~~ + +# DESCRIPTION + +Pass in a pointer to a char pointer and get the last used effective URL. + +In cases when you have asked libcurl to follow redirects, it may not be the same +value you set with CURLOPT_URL(3). + +The **urlp** pointer is NULL or points to private memory. You MUST NOT free +- it gets freed when you call curl_easy_cleanup(3) on the corresponding +CURL handle. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *url = NULL; + curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_URL, &url); + if(url) + printf("Redirect to: %s\n", url); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.3 b/docs/libcurl/opts/CURLINFO_FILETIME.3 deleted file mode 100644 index ae08db367ae..00000000000 --- a/docs/libcurl/opts/CURLINFO_FILETIME.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_FILETIME 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_FILETIME \- get the remote time of the retrieved document -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME, long *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the remote time of the retrieved document -in number of seconds since January 1 1970 in the GMT/UTC time zone. If you get --1, it can be because of many reasons (it might be unknown, the server might -hide it or the server does not support the command that tells document time -etc) and the time of the document is unknown. - -You must tell libcurl to collect this information before the transfer is made, -by using the \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or -you this unconditionally gets a -1 back. - -Consider using \fICURLINFO_FILETIME_T(3)\fP to be able to extract dates beyond -the year 2038 on systems using 32 bit longs (Windows). -.SH PROTOCOLS -HTTP(S), FTP(S), SFTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* Ask for filetime */ - curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - long filetime = 0; - res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); - if((CURLE_OK == res) && (filetime >= 0)) { - time_t file_time = (time_t)filetime; - printf("filetime: %s", ctime(&file_time)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.5 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_FILETIME (3) diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.md b/docs/libcurl/opts/CURLINFO_FILETIME.md new file mode 100644 index 00000000000..77ef534b414 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_FILETIME.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_FILETIME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FILETIME (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_FILETIME - get the remote time of the retrieved document + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME, long *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the remote time of the retrieved document +in number of seconds since January 1 1970 in the GMT/UTC time zone. If you get +-1, it can be because of many reasons (it might be unknown, the server might +hide it or the server does not support the command that tells document time +etc) and the time of the document is unknown. + +You must tell libcurl to collect this information before the transfer is made, +by using the CURLOPT_FILETIME(3) option to curl_easy_setopt(3) or +you this unconditionally gets a -1 back. + +Consider using CURLINFO_FILETIME_T(3) to be able to extract dates beyond +the year 2038 on systems using 32 bit longs (Windows). + +# PROTOCOLS + +HTTP(S), FTP(S), SFTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* Ask for filetime */ + curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + long filetime = 0; + res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); + if((CURLE_OK == res) && (filetime >= 0)) { + time_t file_time = (time_t)filetime; + printf("filetime: %s", ctime(&file_time)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.5 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.3 b/docs/libcurl/opts/CURLINFO_FILETIME_T.3 deleted file mode 100644 index 48ddc41636f..00000000000 --- a/docs/libcurl/opts/CURLINFO_FILETIME_T.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_FILETIME 3 "25 Jan 2018" libcurl libcurl -.SH NAME -CURLINFO_FILETIME_T \- get the remote time of the retrieved document -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the remote time of the retrieved -document in number of seconds since January 1 1970 in the GMT/UTC time -zone. If you get -1, it can be because of many reasons (it might be unknown, -the server might hide it or the server does not support the command that tells -document time etc) and the time of the document is unknown. - -You must ask libcurl to collect this information before the transfer is made, -by using the \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or -you unconditionally get a -1 back. - -This option is an alternative to \fICURLINFO_FILETIME(3)\fP to allow systems -with 32 bit long variables to extract dates outside of the 32bit timestamp -range. -.SH PROTOCOLS -HTTP(S), FTP(S), SFTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* Ask for filetime */ - curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - curl_off_t filetime; - res = curl_easy_getinfo(curl, CURLINFO_FILETIME_T, &filetime); - if((CURLE_OK == res) && (filetime >= 0)) { - time_t file_time = (time_t)filetime; - printf("filetime: %s", ctime(&file_time)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.59.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_FILETIME (3) diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.md b/docs/libcurl/opts/CURLINFO_FILETIME_T.md new file mode 100644 index 00000000000..62c5f3cb040 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_FILETIME_T.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_FILETIME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FILETIME (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_FILETIME_T - get the remote time of the retrieved document + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the remote time of the retrieved +document in number of seconds since January 1 1970 in the GMT/UTC time +zone. If you get -1, it can be because of many reasons (it might be unknown, +the server might hide it or the server does not support the command that tells +document time etc) and the time of the document is unknown. + +You must ask libcurl to collect this information before the transfer is made, +by using the CURLOPT_FILETIME(3) option to curl_easy_setopt(3) or +you unconditionally get a -1 back. + +This option is an alternative to CURLINFO_FILETIME(3) to allow systems +with 32 bit long variables to extract dates outside of the 32bit timestamp +range. + +# PROTOCOLS + +HTTP(S), FTP(S), SFTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* Ask for filetime */ + curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + curl_off_t filetime; + res = curl_easy_getinfo(curl, CURLINFO_FILETIME_T, &filetime); + if((CURLE_OK == res) && (filetime >= 0)) { + time_t file_time = (time_t)filetime; + printf("filetime: %s", ctime(&file_time)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.59.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 deleted file mode 100644 index 8e0f1a23b17..00000000000 --- a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_FTP_ENTRY_PATH 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_FTP_ENTRY_PATH \- get entry path in FTP server -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FTP_ENTRY_PATH, char **path); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive a pointer to a string holding the -path of the entry path. That is the initial path libcurl ended up in when -logging on to the remote FTP server. This stores a NULL as pointer if -something is wrong. - -The \fBpath\fP pointer is NULL or points to private memory. You MUST NOT free -- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding -CURL handle. -.SH PROTOCOLS -FTP(S) and SFTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); - - res = curl_easy_perform(curl); - - if(!res) { - /* extract the entry path */ - char *ep = NULL; - res = curl_easy_getinfo(curl, CURLINFO_FTP_ENTRY_PATH, &ep); - if(!res && ep) { - printf("Entry path was: %s\\n", ep); - } - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.4. Works for SFTP since 7.21.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md new file mode 100644 index 00000000000..344e1f17432 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_FTP_ENTRY_PATH +Section: 3 +Source: libcurl +See-also: + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_FTP_ENTRY_PATH - get entry path in FTP server + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FTP_ENTRY_PATH, char **path); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive a pointer to a string holding the +path of the entry path. That is the initial path libcurl ended up in when +logging on to the remote FTP server. This stores a NULL as pointer if +something is wrong. + +The **path** pointer is NULL or points to private memory. You MUST NOT free +- it gets freed when you call curl_easy_cleanup(3) on the corresponding +CURL handle. + +# PROTOCOLS + +FTP(S) and SFTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the entry path */ + char *ep = NULL; + res = curl_easy_getinfo(curl, CURLINFO_FTP_ENTRY_PATH, &ep); + if(!res && ep) { + printf("Entry path was: %s\n", ep); + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.4. Works for SFTP since 7.21.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 deleted file mode 100644 index 2c9d8faede4..00000000000 --- a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_HEADER_SIZE 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_HEADER_SIZE \- get size of retrieved headers -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HEADER_SIZE, long *sizep); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the total size of all the headers -received. Measured in number of bytes. - -The total includes the size of any received headers suppressed by -\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long size; - res = curl_easy_getinfo(curl, CURLINFO_HEADER_SIZE, &size); - if(!res) - printf("Header size: %ld bytes\\n", size); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_REQUEST_SIZE (3), -.BR CURLINFO_SIZE_DOWNLOAD (3) diff --git a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md new file mode 100644 index 00000000000..67ccfc232d9 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_HEADER_SIZE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REQUEST_SIZE (3) + - CURLINFO_SIZE_DOWNLOAD (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_HEADER_SIZE - get size of retrieved headers + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HEADER_SIZE, long *sizep); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the total size of all the headers +received. Measured in number of bytes. + +The total includes the size of any received headers suppressed by +CURLOPT_SUPPRESS_CONNECT_HEADERS(3). + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long size; + res = curl_easy_getinfo(curl, CURLINFO_HEADER_SIZE, &size); + if(!res) + printf("Header size: %ld bytes\n", size); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 deleted file mode 100644 index 7ceb790b4eb..00000000000 --- a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_HTTPAUTH_AVAIL 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_HTTPAUTH_AVAIL \- get available HTTP authentication methods -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTPAUTH_AVAIL, long *authp); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive a bitmask indicating the authentication -method(s) available according to the previous response. The meaning of the -bits is explained in the \fICURLOPT_HTTPAUTH(3)\fP option for -\fIcurl_easy_setopt(3)\fP. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - res = curl_easy_perform(curl); - - if(!res) { - /* extract the available authentication types */ - long auth; - res = curl_easy_getinfo(curl, CURLINFO_HTTPAUTH_AVAIL, &auth); - if(!res) { - if(!auth) - printf("No auth available, perhaps no 401?\\n"); - else { - printf("%s%s%s%s\\n", - auth & CURLAUTH_BASIC ? "Basic ":"", - auth & CURLAUTH_DIGEST ? "Digest ":"", - auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"", - auth % CURLAUTH_NTLM ? "NTLM ":""); - } - } - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added RFC 2617 in 7.10.8 -Added RFC 7616 in 7.57.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_PROXYAUTH_AVAIL (3), -.BR CURLOPT_HTTPAUTH (3) diff --git a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md new file mode 100644 index 00000000000..574e0a52b3e --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_HTTPAUTH_AVAIL +Section: 3 +Source: libcurl +See-also: + - CURLINFO_PROXYAUTH_AVAIL (3) + - CURLOPT_HTTPAUTH (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_HTTPAUTH_AVAIL - get available HTTP authentication methods + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTPAUTH_AVAIL, long *authp); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive a bitmask indicating the authentication +method(s) available according to the previous response. The meaning of the +bits is explained in the CURLOPT_HTTPAUTH(3) option for +curl_easy_setopt(3). + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the available authentication types */ + long auth; + res = curl_easy_getinfo(curl, CURLINFO_HTTPAUTH_AVAIL, &auth); + if(!res) { + if(!auth) + printf("No auth available, perhaps no 401?\n"); + else { + printf("%s%s%s%s\n", + auth & CURLAUTH_BASIC ? "Basic ":"", + auth & CURLAUTH_DIGEST ? "Digest ":"", + auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"", + auth % CURLAUTH_NTLM ? "NTLM ":""); + } + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added RFC 2617 in 7.10.8 +Added RFC 7616 in 7.57.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 deleted file mode 100644 index b4b3ac3fe1a..00000000000 --- a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_HTTP_CONNECTCODE 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_HTTP_CONNECTCODE \- get the CONNECT response code -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_CONNECTCODE, long *p); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the last received HTTP proxy response code -to a CONNECT request. The returned value is zero if no such response code was -available. -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* typically CONNECT is used to do HTTPS over HTTP proxies */ - curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long code; - res = curl_easy_getinfo(curl, CURLINFO_HTTP_CONNECTCODE, &code); - if(!res && code) - printf("The CONNECT response code: %03ld\\n", code); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.7 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_RESPONSE_CODE (3) diff --git a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md new file mode 100644 index 00000000000..ee3f0f65c7d --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_HTTP_CONNECTCODE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RESPONSE_CODE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_HTTP_CONNECTCODE - get the CONNECT response code + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_CONNECTCODE, long *p); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the last received HTTP proxy response code +to a CONNECT request. The returned value is zero if no such response code was +available. + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* typically CONNECT is used to do HTTPS over HTTP proxies */ + curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long code; + res = curl_easy_getinfo(curl, CURLINFO_HTTP_CONNECTCODE, &code); + if(!res && code) + printf("The CONNECT response code: %03ld\n", code); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.7 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 deleted file mode 100644 index d4d4e89407e..00000000000 --- a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_HTTP_VERSION 3 "11 May 2016" libcurl libcurl -.SH NAME -CURLINFO_HTTP_VERSION \- get the http version used in the connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_VERSION, long *p); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the version used in the last http -connection done using this handle. The returned value is -CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, -CURL_HTTP_VERSION_3 or 0 if the version cannot be determined. -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long http_version; - curl_easy_getinfo(curl, CURLINFO_HTTP_VERSION, &http_version); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.50.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_RESPONSE_CODE (3) diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md new file mode 100644 index 00000000000..994d7712c1c --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_HTTP_VERSION +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RESPONSE_CODE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_HTTP_VERSION - get the http version used in the connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_VERSION, long *p); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the version used in the last http +connection done using this handle. The returned value is +CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, +CURL_HTTP_VERSION_3 or 0 if the version cannot be determined. + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long http_version; + curl_easy_getinfo(curl, CURLINFO_HTTP_VERSION, &http_version); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.50.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_LASTSOCKET.3 b/docs/libcurl/opts/CURLINFO_LASTSOCKET.3 deleted file mode 100644 index 88a7345a9f9..00000000000 --- a/docs/libcurl/opts/CURLINFO_LASTSOCKET.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_LASTSOCKET 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_LASTSOCKET \- get the last socket used -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LASTSOCKET, long *socket); -.fi -.SH DESCRIPTION -Deprecated since 7.45.0. Use \fICURLINFO_ACTIVESOCKET(3)\fP instead. - -Pass a pointer to a long to receive the last socket used by this curl -session. If the socket is no longer valid, -1 is returned. When you finish -working with the socket, you must call \fIcurl_easy_cleanup(3)\fP as usual and -let libcurl close the socket and cleanup other resources associated with the -handle. This is typically used in combination with -\fICURLOPT_CONNECT_ONLY(3)\fP. - -NOTE: this API is deprecated since it is not working on win64 where the SOCKET -type is 64 bits large while its 'long' is 32 bits. Use the -\fICURLINFO_ACTIVESOCKET(3)\fP instead, if possible. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - long sockfd; /* does not work on win64! */ - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Do not do the transfer - only connect to host */ - curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); - res = curl_easy_perform(curl); - - /* Extract the socket from the curl handle */ - res = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET, &sockfd); - - if(res != CURLE_OK) { - printf("Error: %s\\n", curl_easy_strerror(res)); - return 1; - } - } -} -.fi -.SH AVAILABILITY -Added in 7.15.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_ACTIVESOCKET (3), -.BR CURLOPT_CONNECT_ONLY (3) diff --git a/docs/libcurl/opts/CURLINFO_LASTSOCKET.md b/docs/libcurl/opts/CURLINFO_LASTSOCKET.md new file mode 100644 index 00000000000..b1619ebdbbd --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_LASTSOCKET.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_LASTSOCKET +Section: 3 +Source: libcurl +See-also: + - CURLINFO_ACTIVESOCKET (3) + - CURLOPT_CONNECT_ONLY (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_LASTSOCKET - get the last socket used + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LASTSOCKET, long *socket); +~~~ + +# DESCRIPTION + +Deprecated since 7.45.0. Use CURLINFO_ACTIVESOCKET(3) instead. + +Pass a pointer to a long to receive the last socket used by this curl +session. If the socket is no longer valid, -1 is returned. When you finish +working with the socket, you must call curl_easy_cleanup(3) as usual and +let libcurl close the socket and cleanup other resources associated with the +handle. This is typically used in combination with +CURLOPT_CONNECT_ONLY(3). + +NOTE: this API is deprecated since it is not working on win64 where the SOCKET +type is 64 bits large while its 'long' is 32 bits. Use the +CURLINFO_ACTIVESOCKET(3) instead, if possible. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + long sockfd; /* does not work on win64! */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Do not do the transfer - only connect to host */ + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + res = curl_easy_perform(curl); + + /* Extract the socket from the curl handle */ + res = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET, &sockfd); + + if(res != CURLE_OK) { + printf("Error: %s\n", curl_easy_strerror(res)); + return 1; + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 b/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 deleted file mode 100644 index 5501ba7f93f..00000000000 --- a/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_LOCAL_IP 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_LOCAL_IP \- get local IP address of last connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_IP, char **ip); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive the pointer to a null-terminated -string holding the IP address of the local end of most recent connection done -with this \fBcurl\fP handle. This string may be IPv6 when that is -enabled. Note that you get a pointer to a memory area that is reused at next -request so you need to copy the string if you want to keep the information. - -The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free - -it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding -CURL handle. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - char *ip; - CURLcode res; - CURL *curl = curl_easy_init(); - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the transfer */ - res = curl_easy_perform(curl); - /* Check for errors */ - if((res == CURLE_OK) && - !curl_easy_getinfo(curl, CURLINFO_LOCAL_IP, &ip) && ip) { - printf("Local IP: %s\\n", ip); - } - - /* always cleanup */ - curl_easy_cleanup(curl); -} -.fi -.SH AVAILABILITY -Added in 7.21.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_PRIMARY_IP (3), -.BR CURLINFO_LOCAL_PORT (3) diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md new file mode 100644 index 00000000000..e70d0cf0419 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_LOCAL_IP +Section: 3 +Source: libcurl +See-also: + - CURLINFO_LOCAL_PORT (3) + - CURLINFO_PRIMARY_IP (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_LOCAL_IP - get local IP address of last connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_IP, char **ip); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive the pointer to a null-terminated +string holding the IP address of the local end of most recent connection done +with this **curl** handle. This string may be IPv6 when that is +enabled. Note that you get a pointer to a memory area that is reused at next +request so you need to copy the string if you want to keep the information. + +The **ip** pointer is NULL or points to private memory. You MUST NOT free - +it gets freed when you call curl_easy_cleanup(3) on the corresponding +CURL handle. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + char *ip; + CURLcode res; + CURL *curl = curl_easy_init(); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the transfer */ + res = curl_easy_perform(curl); + /* Check for errors */ + if((res == CURLE_OK) && + !curl_easy_getinfo(curl, CURLINFO_LOCAL_IP, &ip) && ip) { + printf("Local IP: %s\n", ip); + } + + /* always cleanup */ + curl_easy_cleanup(curl); +} +~~~ + +# AVAILABILITY + +Added in 7.21.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 deleted file mode 100644 index 31617ac316b..00000000000 --- a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_LOCAL_PORT 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_LOCAL_PORT \- get the latest local port number -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_PORT, long *portp); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the local port number of the most recent -connection done with this \fBcurl\fP handle. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl; - CURLcode res; - - curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - res = curl_easy_perform(curl); - - if(CURLE_OK == res) { - long port; - res = curl_easy_getinfo(curl, CURLINFO_LOCAL_PORT, &port); - - if(CURLE_OK == res) { - printf("We used local port: %ld\\n", port); - } - } - curl_easy_cleanup(curl); - } - return 0; -} -.fi -.SH AVAILABILITY -Added in 7.21.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_LOCAL_IP (3), -.BR CURLINFO_PRIMARY_PORT (3) diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md new file mode 100644 index 00000000000..055fc2ee060 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_LOCAL_PORT +Section: 3 +Source: libcurl +See-also: + - CURLINFO_LOCAL_IP (3) + - CURLINFO_PRIMARY_PORT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_LOCAL_PORT - get the latest local port number + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_PORT, long *portp); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the local port number of the most recent +connection done with this **curl** handle. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl; + CURLcode res; + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + + if(CURLE_OK == res) { + long port; + res = curl_easy_getinfo(curl, CURLINFO_LOCAL_PORT, &port); + + if(CURLE_OK == res) { + printf("We used local port: %ld\n", port); + } + } + curl_easy_cleanup(curl); + } + return 0; +} +~~~ + +# AVAILABILITY + +Added in 7.21.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 deleted file mode 100644 index 4ad0e95229b..00000000000 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_NAMELOOKUP_TIME 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_NAMELOOKUP_TIME \- get the name lookup time -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NAMELOOKUP_TIME, - double *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the total time in seconds from the start -until the name resolving was completed. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - double namelookup; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME, &namelookup); - if(CURLE_OK == res) { - printf("Time: %.1f", namelookup); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_NAMELOOKUP_TIME_T (3) diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md new file mode 100644 index 00000000000..8cf425e0ffd --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_NAMELOOKUP_TIME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_NAMELOOKUP_TIME_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_NAMELOOKUP_TIME - get the name lookup time + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NAMELOOKUP_TIME, + double *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the total time in seconds from the start +until the name resolving was completed. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double namelookup; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME, &namelookup); + if(CURLE_OK == res) { + printf("Time: %.1f", namelookup); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 deleted file mode 100644 index 91be68a2923..00000000000 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_NAMELOOKUP_TIME_T 3 "28 Apr 2018" libcurl libcurl -.SH NAME -CURLINFO_NAMELOOKUP_TIME_T \- get the name lookup time in microseconds -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NAMELOOKUP_TIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the total time in microseconds -from the start until the name resolving was completed. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_off_t namelookup; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME_T, &namelookup); - if(CURLE_OK == res) { - printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", namelookup / 1000000, - (long)(namelookup % 1000000)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_NAMELOOKUP_TIME (3) diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md new file mode 100644 index 00000000000..a3fd4dd84f6 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_NAMELOOKUP_TIME_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_NAMELOOKUP_TIME (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_NAMELOOKUP_TIME_T - get the name lookup time in microseconds + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NAMELOOKUP_TIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the total time in microseconds +from the start until the name resolving was completed. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t namelookup; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME_T, &namelookup); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", namelookup / 1000000, + (long)(namelookup % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 deleted file mode 100644 index b151f1e268e..00000000000 --- a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_NUM_CONNECTS 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_NUM_CONNECTS \- get number of created connections -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NUM_CONNECTS, long *nump); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive how many new connections libcurl had to -create to achieve the previous transfer (only the successful connects are -counted). Combined with \fICURLINFO_REDIRECT_COUNT(3)\fP you are able to know -how many times libcurl successfully reused existing connection(s) or not. See -the connection options of \fIcurl_easy_setopt(3)\fP to see how libcurl tries -to make persistent connections to save time. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long connects; - res = curl_easy_getinfo(curl, CURLINFO_NUM_CONNECTS, &connects); - if(res) - printf("It needed %ld connects\\n", connects); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.12.3 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md new file mode 100644 index 00000000000..5127a0a32a7 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_NUM_CONNECTS +Section: 3 +Source: libcurl +See-also: + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_NUM_CONNECTS - get number of created connections + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NUM_CONNECTS, long *nump); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive how many new connections libcurl had to +create to achieve the previous transfer (only the successful connects are +counted). Combined with CURLINFO_REDIRECT_COUNT(3) you are able to know how +many times libcurl successfully reused existing connection(s) or not. See the +connection options of curl_easy_setopt(3) to see how libcurl tries to make +persistent connections to save time. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long connects; + res = curl_easy_getinfo(curl, CURLINFO_NUM_CONNECTS, &connects); + if(res) + printf("It needed %ld connects\n", connects); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.12.3 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_OS_ERRNO.3 b/docs/libcurl/opts/CURLINFO_OS_ERRNO.3 deleted file mode 100644 index cafeb68a137..00000000000 --- a/docs/libcurl/opts/CURLINFO_OS_ERRNO.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_OS_ERRNO 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_OS_ERRNO \- get errno number from last connect failure -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_OS_ERRNO, long *errnop); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the errno variable from a connect failure. -Note that the value is only set on failure, it is not reset upon a successful -operation. The number is OS and system specific. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res != CURLE_OK) { - long error; - res = curl_easy_getinfo(curl, CURLINFO_OS_ERRNO, &error); - if(res && error) { - printf("Errno: %ld\\n", error); - } - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.12.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3) diff --git a/docs/libcurl/opts/CURLINFO_OS_ERRNO.md b/docs/libcurl/opts/CURLINFO_OS_ERRNO.md new file mode 100644 index 00000000000..3fb69b43cfb --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_OS_ERRNO.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_OS_ERRNO +Section: 3 +Source: libcurl +See-also: + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_OS_ERRNO - get errno number from last connect failure + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_OS_ERRNO, long *errnop); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the errno variable from a connect failure. +Note that the value is only set on failure, it is not reset upon a successful +operation. The number is OS and system specific. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res != CURLE_OK) { + long error; + res = curl_easy_getinfo(curl, CURLINFO_OS_ERRNO, &error); + if(res && error) { + printf("Errno: %ld\n", error); + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.12.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 deleted file mode 100644 index 01f90f214ef..00000000000 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PRETRANSFER_TIME 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_PRETRANSFER_TIME \- get the time until the file transfer start -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME, - double *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the time, in seconds, it took from the -start until the file transfer is just about to begin. - -This time-stamp includes all pre-transfer commands and negotiations that are -specific to the particular protocol(s) involved. It includes the sending of -the protocol-specific instructions that trigger a transfer. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - double pretransfer; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME, &pretransfer); - if(CURLE_OK == res) { - printf("Time: %.1f", pretransfer); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONNECT_TIME_T (3), -.BR CURLINFO_PRETRANSFER_TIME_T (3) diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md new file mode 100644 index 00000000000..8eda23a3c67 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PRETRANSFER_TIME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONNECT_TIME_T (3) + - CURLINFO_PRETRANSFER_TIME_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_PRETRANSFER_TIME - get the time until the file transfer start + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME, + double *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the file transfer is just about to begin. + +This time-stamp includes all pre-transfer commands and negotiations that are +specific to the particular protocol(s) involved. It includes the sending of +the protocol-specific instructions that trigger a transfer. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double pretransfer; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME, &pretransfer); + if(CURLE_OK == res) { + printf("Time: %.1f", pretransfer); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.3 b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.3 deleted file mode 100644 index f0554344617..00000000000 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PRETRANSFER_TIME_T 3 "28 Apr 2018" libcurl libcurl -.SH NAME -CURLINFO_PRETRANSFER_TIME_T \- get the time until the file transfer start -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the time, in microseconds, it took -from the start until the file transfer is just about to begin. - -This time-stamp includes all pre-transfer commands and negotiations that are -specific to the particular protocol(s) involved. It includes the sending of -the protocol-specific instructions that trigger a transfer. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_off_t pretransfer; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME_T, &pretransfer); - if(CURLE_OK == res) { - printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld\\n", - pretransfer / 1000000, - (long)(pretransfer % 1000000)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONNECT_TIME (3), -.BR CURLINFO_PRETRANSFER_TIME_T (3) diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md new file mode 100644 index 00000000000..50c515f3aa4 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PRETRANSFER_TIME_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONNECT_TIME (3) + - CURLINFO_PRETRANSFER_TIME_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_PRETRANSFER_TIME_T - get the time until the file transfer start + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the time, in microseconds, it took +from the start until the file transfer is just about to begin. + +This time-stamp includes all pre-transfer commands and negotiations that are +specific to the particular protocol(s) involved. It includes the sending of +the protocol-specific instructions that trigger a transfer. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t pretransfer; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME_T, &pretransfer); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld\n", + pretransfer / 1000000, + (long)(pretransfer % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 deleted file mode 100644 index 597a797ec54..00000000000 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PRIMARY_IP 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_PRIMARY_IP \- get IP address of last connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_IP, char **ip); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive the pointer to a null-terminated -string holding the IP address of the most recent connection done with this -\fBcurl\fP handle. This string may be IPv6 when that is enabled. Note that you -get a pointer to a memory area that is reused at next request so you need to -copy the string if you want to keep the information. - -The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free - -it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding -CURL handle. -.SH PROTOCOLS -All network based ones -.SH EXAMPLE -.nf -int main(void) -{ - char *ip; - CURLcode res; - CURL *curl = curl_easy_init(); - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the transfer */ - res = curl_easy_perform(curl); - /* Check for errors */ - if((res == CURLE_OK) && - !curl_easy_getinfo(curl, CURLINFO_PRIMARY_IP, &ip) && ip) { - printf("IP: %s\\n", ip); - } - - /* always cleanup */ - curl_easy_cleanup(curl); -} -.fi -.SH AVAILABILITY -Added in 7.19.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_LOCAL_IP (3), -.BR CURLINFO_LOCAL_PORT (3), -.BR CURLINFO_PRIMARY_PORT (3) diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md new file mode 100644 index 00000000000..115113f3fd5 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PRIMARY_IP +Section: 3 +Source: libcurl +See-also: + - CURLINFO_LOCAL_IP (3) + - CURLINFO_LOCAL_PORT (3) + - CURLINFO_PRIMARY_PORT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_PRIMARY_IP - get IP address of last connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_IP, char **ip); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive the pointer to a null-terminated +string holding the IP address of the most recent connection done with this +**curl** handle. This string may be IPv6 when that is enabled. Note that you +get a pointer to a memory area that is reused at next request so you need to +copy the string if you want to keep the information. + +The **ip** pointer is NULL or points to private memory. You MUST NOT free - +it gets freed when you call curl_easy_cleanup(3) on the corresponding +CURL handle. + +# PROTOCOLS + +All network based ones + +# EXAMPLE + +~~~c +int main(void) +{ + char *ip; + CURLcode res; + CURL *curl = curl_easy_init(); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the transfer */ + res = curl_easy_perform(curl); + /* Check for errors */ + if((res == CURLE_OK) && + !curl_easy_getinfo(curl, CURLINFO_PRIMARY_IP, &ip) && ip) { + printf("IP: %s\n", ip); + } + + /* always cleanup */ + curl_easy_cleanup(curl); +} +~~~ + +# AVAILABILITY + +Added in 7.19.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 deleted file mode 100644 index 51d2b746f5f..00000000000 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PRIMARY_PORT 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_PRIMARY_PORT \- get the latest destination port number -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_PORT, long *portp); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the destination port of the most recent -connection done with this \fBcurl\fP handle. - -This is the destination port of the actual TCP or UDP connection libcurl used. -If a proxy was used for the most recent transfer, this is the port number of -the proxy, if no proxy was used it is the port number of the most recently -accessed URL. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long port; - res = curl_easy_getinfo(curl, CURLINFO_PRIMARY_PORT, &port); - if(!res) - printf("Connected to remote port: %ld\\n", port); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.21.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_LOCAL_PORT (3), -.BR CURLINFO_PRIMARY_IP (3) diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md new file mode 100644 index 00000000000..3d90b64ed9f --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PRIMARY_PORT +Section: 3 +Source: libcurl +See-also: + - CURLINFO_LOCAL_PORT (3) + - CURLINFO_PRIMARY_IP (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_PRIMARY_PORT - get the latest destination port number + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_PORT, long *portp); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the destination port of the most recent +connection done with this **curl** handle. + +This is the destination port of the actual TCP or UDP connection libcurl used. +If a proxy was used for the most recent transfer, this is the port number of +the proxy, if no proxy was used it is the port number of the most recently +accessed URL. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long port; + res = curl_easy_getinfo(curl, CURLINFO_PRIMARY_PORT, &port); + if(!res) + printf("Connected to remote port: %ld\n", port); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.21.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PRIVATE.3 b/docs/libcurl/opts/CURLINFO_PRIVATE.3 deleted file mode 100644 index 2c63e3e48c8..00000000000 --- a/docs/libcurl/opts/CURLINFO_PRIVATE.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PRIVATE 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_PRIVATE \- get the private pointer -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIVATE, char **private); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive the pointer to the private data -associated with the curl handle (set with the \fICURLOPT_PRIVATE(3)\fP). -Please note that for internal reasons, the value is returned as a char -pointer, although effectively being a 'void *'. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - void *pointer = (void *)0x2345454; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - /* set the private pointer */ - curl_easy_setopt(curl, CURLOPT_PRIVATE, pointer); - res = curl_easy_perform(curl); - - /* extract the private pointer again */ - res = curl_easy_getinfo(curl, CURLINFO_PRIVATE, &pointer); - - if(res) - printf("error: %s\\n", curl_easy_strerror(res)); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.3 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_PRIVATE (3) diff --git a/docs/libcurl/opts/CURLINFO_PRIVATE.md b/docs/libcurl/opts/CURLINFO_PRIVATE.md new file mode 100644 index 00000000000..127049f7ede --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PRIVATE.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PRIVATE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PRIVATE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_PRIVATE - get the private pointer + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIVATE, char **private); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive the pointer to the private data +associated with the curl handle (set with the CURLOPT_PRIVATE(3)). +Please note that for internal reasons, the value is returned as a char +pointer, although effectively being a 'void *'. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + void *pointer = (void *)0x2345454; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* set the private pointer */ + curl_easy_setopt(curl, CURLOPT_PRIVATE, pointer); + res = curl_easy_perform(curl); + + /* extract the private pointer again */ + res = curl_easy_getinfo(curl, CURLINFO_PRIVATE, &pointer); + + if(res) + printf("error: %s\n", curl_easy_strerror(res)); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.3 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PROTOCOL.3 b/docs/libcurl/opts/CURLINFO_PROTOCOL.3 deleted file mode 100644 index aac7e9f3f1b..00000000000 --- a/docs/libcurl/opts/CURLINFO_PROTOCOL.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PROTOCOL 3 "23 November 2016" libcurl libcurl -.SH NAME -CURLINFO_PROTOCOL \- get the protocol used in the connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROTOCOL, long *p); -.fi -.SH DESCRIPTION -This option is deprecated. We strongly recommend using -\fICURLINFO_SCHEME(3)\fP instead, because this option cannot return all -possible protocols! - -Pass a pointer to a long to receive the version used in the last http -connection. The returned value is set to one of the CURLPROTO_* values: - -.nf -CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_FTP, CURLPROTO_FTPS, -CURLPROTO_GOPHER, CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_IMAP, -CURLPROTO_IMAPS, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_POP3, -CURLPROTO_POP3S, CURLPROTO_RTMP, CURLPROTO_RTMPE, CURLPROTO_RTMPS, -CURLPROTO_RTMPT, CURLPROTO_RTMPTE, CURLPROTO_RTMPTS, CURLPROTO_RTSP, -CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROTO_SMTP, -CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP, CURLPROTO_MQTT -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long protocol; - curl_easy_getinfo(curl, CURLINFO_PROTOCOL, &protocol); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0. Deprecated since 7.85.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_RESPONSE_CODE (3) diff --git a/docs/libcurl/opts/CURLINFO_PROTOCOL.md b/docs/libcurl/opts/CURLINFO_PROTOCOL.md new file mode 100644 index 00000000000..9dfb2970fde --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PROTOCOL.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PROTOCOL +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RESPONSE_CODE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_PROTOCOL - get the protocol used in the connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROTOCOL, long *p); +~~~ + +# DESCRIPTION + +This option is deprecated. We strongly recommend using +CURLINFO_SCHEME(3) instead, because this option cannot return all +possible protocols! + +Pass a pointer to a long to receive the version used in the last http +connection. The returned value is set to one of the CURLPROTO_* values: + +~~~c +CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_FTP, CURLPROTO_FTPS, +CURLPROTO_GOPHER, CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_IMAP, +CURLPROTO_IMAPS, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_POP3, +CURLPROTO_POP3S, CURLPROTO_RTMP, CURLPROTO_RTMPE, CURLPROTO_RTMPS, +CURLPROTO_RTMPT, CURLPROTO_RTMPTE, CURLPROTO_RTMPTS, CURLPROTO_RTSP, +CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROTO_SMTP, +CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP, CURLPROTO_MQTT +~~~ + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long protocol; + curl_easy_getinfo(curl, CURLINFO_PROTOCOL, &protocol); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0. Deprecated since 7.85.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 deleted file mode 100644 index 3d6e5494829..00000000000 --- a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PROXYAUTH_AVAIL 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_PROXYAUTH_AVAIL \- get available HTTP proxy authentication methods -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXYAUTH_AVAIL, - long *authp); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive a bitmask indicating the authentication -method(s) available according to the previous response. The meaning of the -bits is explained in the \fICURLOPT_PROXYAUTH(3)\fP option for -\fIcurl_easy_setopt(3)\fP. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); - - res = curl_easy_perform(curl); - - if(!res) { - /* extract the available proxy authentication types */ - long auth; - res = curl_easy_getinfo(curl, CURLINFO_PROXYAUTH_AVAIL, &auth); - if(!res) { - if(!auth) - printf("No proxy auth available, perhaps no 407?\\n"); - else { - printf("%s%s%s%s\\n", - auth & CURLAUTH_BASIC ? "Basic ":"", - auth & CURLAUTH_DIGEST ? "Digest ":"", - auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"", - auth % CURLAUTH_NTLM ? "NTLM ":""); - } - } - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added RFC 2617 in 7.10.8 -Added RFC 7616 in 7.57.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_HTTPAUTH_AVAIL (3) diff --git a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md new file mode 100644 index 00000000000..0e9dbdcb505 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PROXYAUTH_AVAIL +Section: 3 +Source: libcurl +See-also: + - CURLINFO_HTTPAUTH_AVAIL (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_PROXYAUTH_AVAIL - get available HTTP proxy authentication methods + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXYAUTH_AVAIL, + long *authp); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive a bitmask indicating the authentication +method(s) available according to the previous response. The meaning of the +bits is explained in the CURLOPT_PROXYAUTH(3) option for +curl_easy_setopt(3). + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the available proxy authentication types */ + long auth; + res = curl_easy_getinfo(curl, CURLINFO_PROXYAUTH_AVAIL, &auth); + if(!res) { + if(!auth) + printf("No proxy auth available, perhaps no 407?\n"); + else { + printf("%s%s%s%s\n", + auth & CURLAUTH_BASIC ? "Basic ":"", + auth & CURLAUTH_DIGEST ? "Digest ":"", + auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"", + auth % CURLAUTH_NTLM ? "NTLM ":""); + } + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added RFC 2617 in 7.10.8 +Added RFC 7616 in 7.57.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 deleted file mode 100644 index f4ce84918b0..00000000000 --- a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 +++ /dev/null @@ -1,109 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PROXY_ERROR 3 "3 Aug 2020" libcurl libcurl -.SH NAME -CURLINFO_PROXY_ERROR \- get the detailed (SOCKS) proxy error -.SH SYNOPSIS -.nf -#include - -typedef enum { - CURLPX_OK, - CURLPX_BAD_ADDRESS_TYPE, - CURLPX_BAD_VERSION, - CURLPX_CLOSED, - CURLPX_GSSAPI, - CURLPX_GSSAPI_PERMSG, - CURLPX_GSSAPI_PROTECTION, - CURLPX_IDENTD, - CURLPX_IDENTD_DIFFER, - CURLPX_LONG_HOSTNAME, - CURLPX_LONG_PASSWD, - CURLPX_LONG_USER, - CURLPX_NO_AUTH, - CURLPX_RECV_ADDRESS, - CURLPX_RECV_AUTH, - CURLPX_RECV_CONNECT, - CURLPX_RECV_REQACK, - CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED, - CURLPX_REPLY_COMMAND_NOT_SUPPORTED, - CURLPX_REPLY_CONNECTION_REFUSED, - CURLPX_REPLY_GENERAL_SERVER_FAILURE, - CURLPX_REPLY_HOST_UNREACHABLE, - CURLPX_REPLY_NETWORK_UNREACHABLE, - CURLPX_REPLY_NOT_ALLOWED, - CURLPX_REPLY_TTL_EXPIRED, - CURLPX_REPLY_UNASSIGNED, - CURLPX_REQUEST_FAILED, - CURLPX_RESOLVE_HOST, - CURLPX_SEND_AUTH, - CURLPX_SEND_CONNECT, - CURLPX_SEND_REQUEST, - CURLPX_UNKNOWN_FAIL, - CURLPX_UNKNOWN_MODE, - CURLPX_USER_REJECTED, - CURLPX_LAST /* never use */ -} CURLproxycode; - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_ERROR, long *detail); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive a detailed error code when the most recent -transfer returned a \fBCURLE_PROXY\fP error. That error code matches the -\fBCURLproxycode\fP set. - -The error code is zero (\fBCURLPX_OK\fP) if no response code was available. -.SH PROTOCOLS -All that can be done over SOCKS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://127.0.0.1"); - res = curl_easy_perform(curl); - if(res == CURLE_PROXY) { - long proxycode; - res = curl_easy_getinfo(curl, CURLINFO_PROXY_ERROR, &proxycode); - if(!res && proxycode) - printf("The detailed proxy error: %ld\\n", proxycode); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.73.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_RESPONSE_CODE (3), -.BR libcurl-errors (3) diff --git a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md new file mode 100644 index 00000000000..01113c74075 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md @@ -0,0 +1,105 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PROXY_ERROR +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RESPONSE_CODE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) + - libcurl-errors (3) +--- + +# NAME + +CURLINFO_PROXY_ERROR - get the detailed (SOCKS) proxy error + +# SYNOPSIS + +~~~c +#include + +typedef enum { + CURLPX_OK, + CURLPX_BAD_ADDRESS_TYPE, + CURLPX_BAD_VERSION, + CURLPX_CLOSED, + CURLPX_GSSAPI, + CURLPX_GSSAPI_PERMSG, + CURLPX_GSSAPI_PROTECTION, + CURLPX_IDENTD, + CURLPX_IDENTD_DIFFER, + CURLPX_LONG_HOSTNAME, + CURLPX_LONG_PASSWD, + CURLPX_LONG_USER, + CURLPX_NO_AUTH, + CURLPX_RECV_ADDRESS, + CURLPX_RECV_AUTH, + CURLPX_RECV_CONNECT, + CURLPX_RECV_REQACK, + CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED, + CURLPX_REPLY_COMMAND_NOT_SUPPORTED, + CURLPX_REPLY_CONNECTION_REFUSED, + CURLPX_REPLY_GENERAL_SERVER_FAILURE, + CURLPX_REPLY_HOST_UNREACHABLE, + CURLPX_REPLY_NETWORK_UNREACHABLE, + CURLPX_REPLY_NOT_ALLOWED, + CURLPX_REPLY_TTL_EXPIRED, + CURLPX_REPLY_UNASSIGNED, + CURLPX_REQUEST_FAILED, + CURLPX_RESOLVE_HOST, + CURLPX_SEND_AUTH, + CURLPX_SEND_CONNECT, + CURLPX_SEND_REQUEST, + CURLPX_UNKNOWN_FAIL, + CURLPX_UNKNOWN_MODE, + CURLPX_USER_REJECTED, + CURLPX_LAST /* never use */ +} CURLproxycode; + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_ERROR, long *detail); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive a detailed error code when the most recent +transfer returned a **CURLE_PROXY** error. That error code matches the +**CURLproxycode** set. + +The error code is zero (**CURLPX_OK**) if no response code was available. + +# PROTOCOLS + +All that can be done over SOCKS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://127.0.0.1"); + res = curl_easy_perform(curl); + if(res == CURLE_PROXY) { + long proxycode; + res = curl_easy_getinfo(curl, CURLINFO_PROXY_ERROR, &proxycode); + if(!res && proxycode) + printf("The detailed proxy error: %ld\n", proxycode); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.73.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 deleted file mode 100644 index c2a311a2ac4..00000000000 --- a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_PROXY_SSL_VERIFYRESULT 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLINFO_PROXY_SSL_VERIFYRESULT \- get the result of the proxy certificate verification -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_SSL_VERIFYRESULT, - long *result); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the result of the certificate verification -that was requested (using the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP -option. This is only used for HTTPS proxies. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - long verifyresult; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); - res = curl_easy_perform(curl); - if(res) - printf("error: %s\\n", curl_easy_strerror(res)); - curl_easy_getinfo(curl, CURLINFO_PROXY_SSL_VERIFYRESULT, &verifyresult); - printf("The peer verification said %s\\n", verifyresult? - "fine" : "bad"); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SSL_VERIFYRESULT (3) diff --git a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md new file mode 100644 index 00000000000..d97f5e78e48 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_PROXY_SSL_VERIFYRESULT +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SSL_VERIFYRESULT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_PROXY_SSL_VERIFYRESULT - get the result of the proxy certificate verification + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_SSL_VERIFYRESULT, + long *result); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the result of the certificate verification +that was requested (using the CURLOPT_PROXY_SSL_VERIFYPEER(3) +option. This is only used for HTTPS proxies. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + long verifyresult; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); + res = curl_easy_perform(curl); + if(res) + printf("error: %s\n", curl_easy_strerror(res)); + curl_easy_getinfo(curl, CURLINFO_PROXY_SSL_VERIFYRESULT, &verifyresult); + printf("The peer verification said %s\n", verifyresult? + "fine" : "bad"); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 deleted file mode 100644 index 5ccd7c48a78..00000000000 --- a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_QUEUE_TIME_T 3 "28 Apr 2018" libcurl libcurl -.SH NAME -CURLINFO_QUEUE_TIME_T \- time this transfer was queued -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_QUEUE_TIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the time, in microseconds, this -transfer was held in a waiting queue before it started "for real". A transfer -might be put in a queue if after getting started, it cannot create a new -connection etc due to set conditions and limits imposed by the application. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_off_t queue; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_QUEUE_TIME_T, &queue); - if(CURLE_OK == res) { - printf("Queued: %" CURL_FORMAT_CURL_OFF_T ".%06ld us", queue / 1000000, - (long)(queue % 1000000)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 8.6.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_STARTTRANSFER_TIME_T (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md new file mode 100644 index 00000000000..00454e75255 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_QUEUE_TIME_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_STARTTRANSFER_TIME_T (3) + - CURLOPT_TIMEOUT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_QUEUE_TIME_T - time this transfer was queued + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_QUEUE_TIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the time, in microseconds, this +transfer was held in a waiting queue before it started "for real". A transfer +might be put in a queue if after getting started, it cannot create a new +connection etc due to set conditions and limits imposed by the application. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t queue; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_QUEUE_TIME_T, &queue); + if(CURLE_OK == res) { + printf("Queued: %" CURL_FORMAT_CURL_OFF_T ".%06ld us", queue / 1000000, + (long)(queue % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 8.6.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 deleted file mode 100644 index a0017d7067c..00000000000 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_REDIRECT_COUNT 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_REDIRECT_COUNT \- get the number of redirects -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_COUNT, - long *countp); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the total number of redirections that were -actually followed. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long redirects; - curl_easy_getinfo(curl, CURLINFO_REDIRECT_COUNT, &redirects); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.9.7 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_REDIRECT_URL (3), -.BR CURLOPT_FOLLOWLOCATION (3) diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md new file mode 100644 index 00000000000..aa75bdb2205 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_REDIRECT_COUNT +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_URL (3) + - CURLOPT_FOLLOWLOCATION (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_REDIRECT_COUNT - get the number of redirects + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_COUNT, + long *countp); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the total number of redirections that were +actually followed. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long redirects; + curl_easy_getinfo(curl, CURLINFO_REDIRECT_COUNT, &redirects); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.9.7 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 deleted file mode 100644 index ece2055c0fb..00000000000 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_REDIRECT_TIME 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_REDIRECT_TIME \- get the time for all redirection steps -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_TIME, - double *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the total time, in seconds, it took for -all redirection steps include name lookup, connect, pretransfer and transfer -before final transaction was started. \fICURLINFO_REDIRECT_TIME(3)\fP contains -the complete execution time for multiple redirections. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - double redirect; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME, &redirect); - if(CURLE_OK == res) { - printf("Time: %.1f", redirect); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.9.7 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_REDIRECT_COUNT (3), -.BR CURLINFO_REDIRECT_TIME_T (3), -.BR CURLINFO_REDIRECT_URL (3) diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md new file mode 100644 index 00000000000..26d9af2a0b0 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_REDIRECT_TIME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_COUNT (3) + - CURLINFO_REDIRECT_TIME_T (3) + - CURLINFO_REDIRECT_URL (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_REDIRECT_TIME - get the time for all redirection steps + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_TIME, + double *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the total time, in seconds, it took for +all redirection steps include name lookup, connect, pretransfer and transfer +before final transaction was started. CURLINFO_REDIRECT_TIME(3) contains +the complete execution time for multiple redirections. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double redirect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME, &redirect); + if(CURLE_OK == res) { + printf("Time: %.1f", redirect); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.9.7 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 deleted file mode 100644 index cbda4203540..00000000000 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_REDIRECT_TIME_T 3 "28 Apr 2018" libcurl libcurl -.SH NAME -CURLINFO_REDIRECT_TIME_T \- get the time for all redirection steps -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_TIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the total time, in microseconds, it -took for all redirection steps include name lookup, connect, pretransfer and -transfer before final transaction was started. -\fICURLINFO_REDIRECT_TIME_T(3)\fP holds the complete execution time for -multiple redirections. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_off_t redirect; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME_T, &redirect); - if(CURLE_OK == res) { - printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", redirect / 1000000, - (long)(redirect % 1000000)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_REDIRECT_COUNT (3), -.BR CURLINFO_REDIRECT_TIME (3), -.BR CURLINFO_REDIRECT_URL (3) diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md new file mode 100644 index 00000000000..f4ee710895b --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_REDIRECT_TIME_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_COUNT (3) + - CURLINFO_REDIRECT_TIME (3) + - CURLINFO_REDIRECT_URL (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_REDIRECT_TIME_T - get the time for all redirection steps + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_TIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the total time, in microseconds, it +took for all redirection steps include name lookup, connect, pretransfer and +transfer before final transaction was started. +CURLINFO_REDIRECT_TIME_T(3) holds the complete execution time for +multiple redirections. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t redirect; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME_T, &redirect); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", redirect / 1000000, + (long)(redirect % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 deleted file mode 100644 index 61422f6db67..00000000000 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_REDIRECT_URL 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_REDIRECT_URL \- get the URL a redirect would go to -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_URL, char **urlp); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP -take you to if you would enable \fICURLOPT_FOLLOWLOCATION(3)\fP. This can come -handy if you think using the built-in libcurl redirect logic is not good enough -for you but you would still prefer to avoid implementing all the magic of -figuring out the new URL. - -This URL is also set if the \fICURLOPT_MAXREDIRS(3)\fP limit prevented a -redirect to happen (since 7.54.1). -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - char *url = NULL; - curl_easy_getinfo(curl, CURLINFO_REDIRECT_URL, &url); - if(url) - printf("Redirect to: %s\\n", url); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.18.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_REDIRECT_COUNT (3), -.BR CURLINFO_REDIRECT_TIME_T (3), -.BR CURLOPT_FOLLOWLOCATION (3) diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md new file mode 100644 index 00000000000..8d7fc5c107d --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_REDIRECT_URL +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_COUNT (3) + - CURLINFO_REDIRECT_TIME_T (3) + - CURLOPT_FOLLOWLOCATION (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_REDIRECT_URL - get the URL a redirect would go to + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_URL, char **urlp); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive the URL a redirect *would* +take you to if you would enable CURLOPT_FOLLOWLOCATION(3). This can come +handy if you think using the built-in libcurl redirect logic is not good enough +for you but you would still prefer to avoid implementing all the magic of +figuring out the new URL. + +This URL is also set if the CURLOPT_MAXREDIRS(3) limit prevented a +redirect to happen (since 7.54.1). + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *url = NULL; + curl_easy_getinfo(curl, CURLINFO_REDIRECT_URL, &url); + if(url) + printf("Redirect to: %s\n", url); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.18.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_REFERER.3 b/docs/libcurl/opts/CURLINFO_REFERER.3 deleted file mode 100644 index cc1a3c6673a..00000000000 --- a/docs/libcurl/opts/CURLINFO_REFERER.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_REFERER 3 "11 Feb 2021" libcurl libcurl -.SH NAME -CURLINFO_REFERER \- get the used referrer request header -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REFERER, char **hdrp); -.fi -.SH DESCRIPTION -Pass in a pointer to a char pointer and get the referrer header used in the -most recent request. - -The \fBhdrp\fP pointer is NULL or points to private memory you MUST NOT free - -it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding -CURL handle. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/referrer"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - char *hdr = NULL; - curl_easy_getinfo(curl, CURLINFO_REFERER, &hdr); - if(hdr) - printf("Referrer header: %s\\n", hdr); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.76.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_header (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_REFERER (3) diff --git a/docs/libcurl/opts/CURLINFO_REFERER.md b/docs/libcurl/opts/CURLINFO_REFERER.md new file mode 100644 index 00000000000..fabc652a7fd --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_REFERER.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_REFERER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_REFERER (3) + - curl_easy_getinfo (3) + - curl_easy_header (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_REFERER - get the used referrer request header + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REFERER, char **hdrp); +~~~ + +# DESCRIPTION + +Pass in a pointer to a char pointer and get the referrer header used in the +most recent request. + +The **hdrp** pointer is NULL or points to private memory you MUST NOT free - +it gets freed when you call curl_easy_cleanup(3) on the corresponding +CURL handle. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/referrer"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *hdr = NULL; + curl_easy_getinfo(curl, CURLINFO_REFERER, &hdr); + if(hdr) + printf("Referrer header: %s\n", hdr); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.76.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 deleted file mode 100644 index 9f702910703..00000000000 --- a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 +++ /dev/null @@ -1,67 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_REQUEST_SIZE 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_REQUEST_SIZE \- get size of sent request -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REQUEST_SIZE, long *sizep); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the total size of the issued -requests. This is so far only for HTTP requests. Note that this may be more -than one request if \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long req; - res = curl_easy_getinfo(curl, CURLINFO_REQUEST_SIZE, &req); - if(!res) - printf("Request size: %ld bytes\\n", req); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_HEADER_SIZE (3), -.BR CURLINFO_SIZE_DOWNLOAD_T (3) diff --git a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md new file mode 100644 index 00000000000..444f4ec236d --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md @@ -0,0 +1,63 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_REQUEST_SIZE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_HEADER_SIZE (3) + - CURLINFO_SIZE_DOWNLOAD_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_REQUEST_SIZE - get size of sent request + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REQUEST_SIZE, long *sizep); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the total size of the issued +requests. This is so far only for HTTP requests. Note that this may be more +than one request if CURLOPT_FOLLOWLOCATION(3) is enabled. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long req; + res = curl_easy_getinfo(curl, CURLINFO_REQUEST_SIZE, &req); + if(!res) + printf("Request size: %ld bytes\n", req); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 deleted file mode 100644 index c006a158084..00000000000 --- a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_RESPONSE_CODE 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_RESPONSE_CODE \- get the last response code -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RESPONSE_CODE, long *codep); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or LDAP -(OpenLDAP only) response code. This option was previously known as -CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. The stored value is zero if -no server response code has been received. - -Note that a proxy's CONNECT response should be read with -\fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this. -.SH PROTOCOLS -HTTP, FTP, SMTP and LDAP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long response_code; - curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &response_code); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.8. CURLINFO_HTTP_CODE was added in 7.4.1. -Support for SMTP responses added in 7.25.0, for OpenLDAP in 7.81.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_HTTP_CONNECTCODE (3) diff --git a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md new file mode 100644 index 00000000000..43cf8378dad --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_RESPONSE_CODE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_HTTP_CONNECTCODE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_RESPONSE_CODE - get the last response code + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RESPONSE_CODE, long *codep); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or LDAP +(OpenLDAP only) response code. This option was previously known as +CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. The stored value is zero if +no server response code has been received. + +Note that a proxy's CONNECT response should be read with +CURLINFO_HTTP_CONNECTCODE(3) and not this. + +# PROTOCOLS + +HTTP, FTP, SMTP and LDAP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long response_code; + curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &response_code); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.8. CURLINFO_HTTP_CODE was added in 7.4.1. +Support for SMTP responses added in 7.25.0, for OpenLDAP in 7.81.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 deleted file mode 100644 index 5a7450ccba9..00000000000 --- a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_RETRY_AFTER 3 "6 Aug 2019" libcurl libcurl -.SH NAME -CURLINFO_RETRY_AFTER \- returns the Retry-After retry delay -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RETRY_AFTER, - curl_off_t *retry); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t variable to receive the number of seconds the -HTTP server suggests the client should wait until the next request is -issued. The information from the "Retry-After:" header. - -While the HTTP header might contain a fixed date string, the -\fICURLINFO_RETRY_AFTER(3)\fP always returns the number of seconds to wait - -or zero if there was no header or the header could not be parsed. -.SH DEFAULT -Returns zero delay if there was no header. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - curl_off_t wait = 0; - curl_easy_getinfo(curl, CURLINFO_RETRY_AFTER, &wait); - if(wait) - printf("Wait for %" CURL_FORMAT_CURL_OFF_T " seconds\\n", wait); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.66.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_header (3), -.BR CURLOPT_HEADERFUNCTION (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md new file mode 100644 index 00000000000..adc12007768 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_RETRY_AFTER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADERFUNCTION (3) + - CURLOPT_STDERR (3) + - curl_easy_header (3) +--- + +# NAME + +CURLINFO_RETRY_AFTER - returns the Retry-After retry delay + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RETRY_AFTER, + curl_off_t *retry); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t variable to receive the number of seconds the +HTTP server suggests the client should wait until the next request is +issued. The information from the "Retry-After:" header. + +While the HTTP header might contain a fixed date string, the +CURLINFO_RETRY_AFTER(3) always returns the number of seconds to wait - +or zero if there was no header or the header could not be parsed. + +# DEFAULT + +Returns zero delay if there was no header. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + curl_off_t wait = 0; + curl_easy_getinfo(curl, CURLINFO_RETRY_AFTER, &wait); + if(wait) + printf("Wait for %" CURL_FORMAT_CURL_OFF_T " seconds\n", wait); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.66.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 deleted file mode 100644 index bd8ec271ec6..00000000000 --- a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_RTSP_CLIENT_CSEQ 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_RTSP_CLIENT_CSEQ \- get the next RTSP client CSeq -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CLIENT_CSEQ, - long *cseq); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the next CSeq that is expected to be used -by the application. -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long cseq; - curl_easy_getinfo(curl, CURLINFO_RTSP_CLIENT_CSEQ, &cseq); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_RTSP_CSEQ_RECV (3), -.BR CURLINFO_RTSP_SERVER_CSEQ (3) diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md new file mode 100644 index 00000000000..8b515b42799 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_RTSP_CLIENT_CSEQ +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RTSP_CSEQ_RECV (3) + - CURLINFO_RTSP_SERVER_CSEQ (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_RTSP_CLIENT_CSEQ - get the next RTSP client CSeq + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CLIENT_CSEQ, + long *cseq); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the next CSeq that is expected to be used +by the application. + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long cseq; + curl_easy_getinfo(curl, CURLINFO_RTSP_CLIENT_CSEQ, &cseq); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 deleted file mode 100644 index dc840a8474e..00000000000 --- a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_RTSP_CSEQ_RECV 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_RTSP_CSEQ_RECV \- get the recently received CSeq -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CSEQ_RECV, long *cseq); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the most recently received CSeq from the -server. If your application encounters a \fICURLE_RTSP_CSEQ_ERROR\fP then you -may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this -value. -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long cseq; - curl_easy_getinfo(curl, CURLINFO_RTSP_CSEQ_RECV, &cseq); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_RTSP_SERVER_CSEQ (3) diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md new file mode 100644 index 00000000000..9eb813aa4d4 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_RTSP_CSEQ_RECV +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RTSP_SERVER_CSEQ (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_RTSP_CSEQ_RECV - get the recently received CSeq + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CSEQ_RECV, long *cseq); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the most recently received CSeq from the +server. If your application encounters a *CURLE_RTSP_CSEQ_ERROR* then you +may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this +value. + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long cseq; + curl_easy_getinfo(curl, CURLINFO_RTSP_CSEQ_RECV, &cseq); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 deleted file mode 100644 index 8cf05226115..00000000000 --- a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_RTSP_SERVER_CSEQ 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_RTSP_SERVER_CSEQ \- get the next RTSP server CSeq -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SERVER_CSEQ, - long *cseq); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the next CSeq that is expected to be used -by the application. - -Listening for server initiated requests is not implemented! - -Applications wishing to resume an RTSP session on another connection should -retrieve this info before closing the active connection. -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - long cseq; - curl_easy_getinfo(curl, CURLINFO_RTSP_SERVER_CSEQ, &cseq); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_RTSP_CSEQ_RECV (3) diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md new file mode 100644 index 00000000000..7826f8a3cfc --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_RTSP_SERVER_CSEQ +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RTSP_CSEQ_RECV (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_RTSP_SERVER_CSEQ - get the next RTSP server CSeq + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SERVER_CSEQ, + long *cseq); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the next CSeq that is expected to be used +by the application. + +Listening for server initiated requests is not implemented! + +Applications wishing to resume an RTSP session on another connection should +retrieve this info before closing the active connection. + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + long cseq; + curl_easy_getinfo(curl, CURLINFO_RTSP_SERVER_CSEQ, &cseq); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 deleted file mode 100644 index fe1e3fd0de1..00000000000 --- a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_RTSP_SESSION_ID 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_RTSP_SESSION_ID \- get RTSP session ID -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SESSION_ID, char **id); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive a pointer to a string holding the -most recent RTSP Session ID. - -Applications wishing to resume an RTSP session on another connection should -retrieve this info before closing the active connection. - -The \fBid\fP pointer is NULL or points to private memory. You MUST NOT free - -it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding -CURL handle. -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - char *id; - curl_easy_getinfo(curl, CURLINFO_RTSP_SESSION_ID, &id); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_RTSP_CSEQ_RECV (3) diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md new file mode 100644 index 00000000000..402a122f88c --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_RTSP_SESSION_ID +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RTSP_CSEQ_RECV (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_RTSP_SESSION_ID - get RTSP session ID + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SESSION_ID, char **id); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive a pointer to a string holding the +most recent RTSP Session ID. + +Applications wishing to resume an RTSP session on another connection should +retrieve this info before closing the active connection. + +The **id** pointer is NULL or points to private memory. You MUST NOT free - +it gets freed when you call curl_easy_cleanup(3) on the corresponding +CURL handle. + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *id; + curl_easy_getinfo(curl, CURLINFO_RTSP_SESSION_ID, &id); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SCHEME.3 b/docs/libcurl/opts/CURLINFO_SCHEME.3 deleted file mode 100644 index 018866a68e4..00000000000 --- a/docs/libcurl/opts/CURLINFO_SCHEME.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SCHEME 3 "23 November 2016" libcurl libcurl -.SH NAME -CURLINFO_SCHEME \- get the URL scheme (sometimes called protocol) used in the connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SCHEME, char **scheme); -.fi -.SH DESCRIPTION -Pass a pointer to a char pointer to receive the pointer to a null-terminated -string holding the URL scheme used for the most recent connection done with -this CURL \fBhandle\fP. - -The \fBscheme\fP pointer is NULL or points to private memory. You MUST NOT -free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res == CURLE_OK) { - char *scheme = NULL; - curl_easy_getinfo(curl, CURLINFO_SCHEME, &scheme); - if(scheme) - printf("scheme: %s\\n", scheme); /* scheme: HTTP */ - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_EFFECTIVE_URL (3), -.BR CURLINFO_PROTOCOL (3), -.BR CURLINFO_RESPONSE_CODE (3) diff --git a/docs/libcurl/opts/CURLINFO_SCHEME.md b/docs/libcurl/opts/CURLINFO_SCHEME.md new file mode 100644 index 00000000000..db567fc98a7 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SCHEME.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SCHEME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_EFFECTIVE_URL (3) + - CURLINFO_PROTOCOL (3) + - CURLINFO_RESPONSE_CODE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SCHEME - get the URL scheme (sometimes called protocol) used in the connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SCHEME, char **scheme); +~~~ + +# DESCRIPTION + +Pass a pointer to a char pointer to receive the pointer to a null-terminated +string holding the URL scheme used for the most recent connection done with +this CURL **handle**. + +The **scheme** pointer is NULL or points to private memory. You MUST NOT +free - it gets freed when you call curl_easy_cleanup(3) on the +corresponding CURL handle. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res == CURLE_OK) { + char *scheme = NULL; + curl_easy_getinfo(curl, CURLINFO_SCHEME, &scheme); + if(scheme) + printf("scheme: %s\n", scheme); /* scheme: HTTP */ + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 deleted file mode 100644 index 7ac1f9231ca..00000000000 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SIZE_DOWNLOAD 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_SIZE_DOWNLOAD \- get the number of downloaded bytes -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD, double *dlp); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the total amount of bytes that were -downloaded. The amount is only for the latest transfer and gets reset again -for each new transfer. This counts actual payload data, what's also commonly -called body. All meta and header data is excluded and not included in this -number. - -\fICURLINFO_SIZE_DOWNLOAD_T(3)\fP is a newer replacement that returns a more -sensible variable type. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - /* check the size */ - double dl; - res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD, &dl); - if(!res) { - printf("Downloaded %.0f bytes\\n", dl); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1. Deprecated since 7.55.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SIZE_DOWNLOAD_T (3), -.BR CURLINFO_SIZE_UPLOAD_T (3), -.BR CURLOPT_MAXFILESIZE (3) diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md new file mode 100644 index 00000000000..ff19908cfaf --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SIZE_DOWNLOAD +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SIZE_DOWNLOAD_T (3) + - CURLINFO_SIZE_UPLOAD_T (3) + - CURLOPT_MAXFILESIZE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SIZE_DOWNLOAD - get the number of downloaded bytes + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD, double *dlp); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the total amount of bytes that were +downloaded. The amount is only for the latest transfer and gets reset again +for each new transfer. This counts actual payload data, what's also commonly +called body. All meta and header data is excluded and not included in this +number. + +CURLINFO_SIZE_DOWNLOAD_T(3) is a newer replacement that returns a more +sensible variable type. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + double dl; + res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD, &dl); + if(!res) { + printf("Downloaded %.0f bytes\n", dl); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1. Deprecated since 7.55.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 deleted file mode 100644 index 5e424f2351b..00000000000 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SIZE_DOWNLOAD_T 3 "25 May 2017" libcurl libcurl -.SH NAME -CURLINFO_SIZE_DOWNLOAD_T \- get the number of downloaded bytes -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD_T, - curl_off_t *dlp); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that -were downloaded. The amount is only for the latest transfer and gets reset -again for each new transfer. This counts actual payload data, what's also -commonly called body. All meta and header data is excluded from this amount. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - /* check the size */ - curl_off_t dl; - res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD_T, &dl); - if(!res) { - printf("Downloaded %" CURL_FORMAT_CURL_OFF_T " bytes\\n", dl); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.55.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SIZE_DOWNLOAD (3), -.BR CURLINFO_SIZE_UPLOAD_T (3), -.BR CURLOPT_MAXFILESIZE (3) diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md new file mode 100644 index 00000000000..f5468db9d1f --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SIZE_DOWNLOAD_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SIZE_DOWNLOAD (3) + - CURLINFO_SIZE_UPLOAD_T (3) + - CURLOPT_MAXFILESIZE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SIZE_DOWNLOAD_T - get the number of downloaded bytes + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD_T, + curl_off_t *dlp); +~~~ + +# DESCRIPTION + +Pass a pointer to a *curl_off_t* to receive the total amount of bytes that +were downloaded. The amount is only for the latest transfer and gets reset +again for each new transfer. This counts actual payload data, what's also +commonly called body. All meta and header data is excluded from this amount. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + /* check the size */ + curl_off_t dl; + res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD_T, &dl); + if(!res) { + printf("Downloaded %" CURL_FORMAT_CURL_OFF_T " bytes\n", dl); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.55.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 deleted file mode 100644 index ba01b311923..00000000000 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SIZE_UPLOAD 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_SIZE_UPLOAD \- get the number of uploaded bytes -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD, - double *uploadp); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the total amount of bytes that were -uploaded. - -\fICURLINFO_SIZE_UPLOAD_T(3)\fP is a newer replacement that returns a more -sensible variable type. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - double ul; - res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD, &ul); - if(!res) { - printf("Uploaded %.0f bytes\\n", ul); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1. Deprecated since 7.55.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SIZE_DOWNLOAD_T (3), -.BR CURLINFO_SIZE_UPLOAD_T (3) diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md new file mode 100644 index 00000000000..175fe718d18 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SIZE_UPLOAD +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SIZE_DOWNLOAD_T (3) + - CURLINFO_SIZE_UPLOAD_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SIZE_UPLOAD - get the number of uploaded bytes + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD, + double *uploadp); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the total amount of bytes that were +uploaded. + +CURLINFO_SIZE_UPLOAD_T(3) is a newer replacement that returns a more +sensible variable type. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + double ul; + res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD, &ul); + if(!res) { + printf("Uploaded %.0f bytes\n", ul); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1. Deprecated since 7.55.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 deleted file mode 100644 index 5f5dd766ae8..00000000000 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SIZE_UPLOAD_T 3 "25 May 2017" libcurl libcurl -.SH NAME -CURLINFO_SIZE_UPLOAD_T \- get the number of uploaded bytes -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD_T, - curl_off_t *uploadp); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that -were uploaded. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - curl_off_t ul; - res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD_T, &ul); - if(!res) { - printf("Uploaded %" CURL_FORMAT_CURL_OFF_T " bytes\\n", ul); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.55.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SIZE_DOWNLOAD_T (3), -.BR CURLINFO_SIZE_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md new file mode 100644 index 00000000000..29874f9fdf1 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SIZE_UPLOAD_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SIZE_DOWNLOAD_T (3) + - CURLINFO_SIZE_UPLOAD (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SIZE_UPLOAD_T - get the number of uploaded bytes + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD_T, + curl_off_t *uploadp); +~~~ + +# DESCRIPTION + +Pass a pointer to a *curl_off_t* to receive the total amount of bytes that +were uploaded. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t ul; + res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD_T, &ul); + if(!res) { + printf("Uploaded %" CURL_FORMAT_CURL_OFF_T " bytes\n", ul); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.55.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 deleted file mode 100644 index 7c277d51dd4..00000000000 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SPEED_DOWNLOAD 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_SPEED_DOWNLOAD \- get download speed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD, - double *speed); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the average download speed that curl -measured for the complete download. Measured in bytes/second. - -\fICURLINFO_SPEED_DOWNLOAD_T(3)\fP is a newer replacement that returns a more -sensible variable type. -.SH PROTOCOLS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - double speed; - res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD, &speed); - if(!res) { - printf("Download speed %.0f bytes/sec\\n", speed); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1. Deprecated since 7.55.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SIZE_UPLOAD_T (3), -.BR CURLINFO_SPEED_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md new file mode 100644 index 00000000000..fe0766939c9 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SPEED_DOWNLOAD +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SIZE_UPLOAD_T (3) + - CURLINFO_SPEED_UPLOAD (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SPEED_DOWNLOAD - get download speed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD, + double *speed); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the average download speed that curl +measured for the complete download. Measured in bytes/second. + +CURLINFO_SPEED_DOWNLOAD_T(3) is a newer replacement that returns a more +sensible variable type. + +# PROTOCOLS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + double speed; + res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD, &speed); + if(!res) { + printf("Download speed %.0f bytes/sec\n", speed); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1. Deprecated since 7.55.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 deleted file mode 100644 index 5bf2c285b58..00000000000 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SPEED_DOWNLOAD_T 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_SPEED_DOWNLOAD_T \- get download speed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD_T, - curl_off_t *speed); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIcurl_off_t\fP to receive the average download speed -that curl measured for the complete download. Measured in bytes/second. -.SH PROTOCOLS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - curl_off_t speed; - res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD_T, &speed); - if(!res) { - printf("Download speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\\n", - speed); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.55.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SIZE_UPLOAD_T (3), -.BR CURLINFO_SPEED_UPLOAD_T (3) diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md new file mode 100644 index 00000000000..c8bc2f8671d --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SPEED_DOWNLOAD_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SIZE_UPLOAD_T (3) + - CURLINFO_SPEED_UPLOAD_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SPEED_DOWNLOAD_T - get download speed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD_T, + curl_off_t *speed); +~~~ + +# DESCRIPTION + +Pass a pointer to a *curl_off_t* to receive the average download speed +that curl measured for the complete download. Measured in bytes/second. + +# PROTOCOLS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t speed; + res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD_T, &speed); + if(!res) { + printf("Download speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\n", + speed); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.55.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 deleted file mode 100644 index c42f3b51708..00000000000 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SPEED_UPLOAD 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_SPEED_UPLOAD \- get upload speed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD, double *speed); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the average upload speed that curl -measured for the complete upload. Measured in bytes/second. - -\fICURLINFO_SPEED_UPLOAD_T(3)\fP is a newer replacement that returns a more -sensible variable type. -.SH PROTOCOLS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - double speed; - res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD, &speed); - if(!res) { - printf("Upload speed %.0f bytes/sec\\n", speed); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1. Deprecated since 7.55.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SPEED_DOWNLOAD_T (3) diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md new file mode 100644 index 00000000000..11ce92923e9 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SPEED_UPLOAD +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SPEED_DOWNLOAD_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SPEED_UPLOAD - get upload speed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD, double *speed); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the average upload speed that curl +measured for the complete upload. Measured in bytes/second. + +CURLINFO_SPEED_UPLOAD_T(3) is a newer replacement that returns a more +sensible variable type. + +# PROTOCOLS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + double speed; + res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD, &speed); + if(!res) { + printf("Upload speed %.0f bytes/sec\n", speed); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1. Deprecated since 7.55.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 deleted file mode 100644 index f2bf1d735b0..00000000000 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SPEED_UPLOAD_T 3 "25 May 2017" libcurl libcurl -.SH NAME -CURLINFO_SPEED_UPLOAD_T \- get upload speed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD_T, - curl_off_t *speed); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIcurl_off_t\fP to receive the average upload speed that -curl measured for the complete upload. Measured in bytes/second. -.SH PROTOCOLS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - curl_off_t speed; - res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD_T, &speed); - if(!res) { - printf("Upload speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\\n", speed); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 7.55.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_SPEED_DOWNLOAD_T (3) diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md new file mode 100644 index 00000000000..178e9a5269e --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md @@ -0,0 +1,63 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SPEED_UPLOAD_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SPEED_DOWNLOAD_T (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SPEED_UPLOAD_T - get upload speed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD_T, + curl_off_t *speed); +~~~ + +# DESCRIPTION + +Pass a pointer to a *curl_off_t* to receive the average upload speed that +curl measured for the complete upload. Measured in bytes/second. + +# PROTOCOLS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t speed; + res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD_T, &speed); + if(!res) { + printf("Upload speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\n", speed); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.55.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 deleted file mode 100644 index 03db5bbb445..00000000000 --- a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SSL_ENGINES 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_SSL_ENGINES \- get an slist of OpenSSL crypto-engines -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SSL_ENGINES, - struct curl_slist **engine_list); -.fi -.SH DESCRIPTION -Pass the address of a 'struct curl_slist *' to receive a linked-list of -OpenSSL crypto-engines supported. Note that engines are normally implemented -in separate dynamic libraries. Hence not all the returned engines may be -available at runtime. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP -on the list pointer once you are done with it, as libcurl does not free this -data for you. -.SH PROTOCOLS -All TLS based ones. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - struct curl_slist *engines; - res = curl_easy_getinfo(curl, CURLINFO_SSL_ENGINES, &engines); - if((res == CURLE_OK) && engines) { - /* we have a list, free it when done using it */ - curl_slist_free_all(engines); - } - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.12.3. Available in OpenSSL builds with "engine" support. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLOPT_SSLENGINE (3) diff --git a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md new file mode 100644 index 00000000000..9dbb0a1d157 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SSL_ENGINES +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSLENGINE (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SSL_ENGINES - get an slist of OpenSSL crypto-engines + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SSL_ENGINES, + struct curl_slist **engine_list); +~~~ + +# DESCRIPTION + +Pass the address of a 'struct curl_slist *' to receive a linked-list of +OpenSSL crypto-engines supported. Note that engines are normally implemented +in separate dynamic libraries. Hence not all the returned engines may be +available at runtime. **NOTE:** you must call curl_slist_free_all(3) +on the list pointer once you are done with it, as libcurl does not free this +data for you. + +# PROTOCOLS + +All TLS based ones. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_slist *engines; + res = curl_easy_getinfo(curl, CURLINFO_SSL_ENGINES, &engines); + if((res == CURLE_OK) && engines) { + /* we have a list, free it when done using it */ + curl_slist_free_all(engines); + } + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.12.3. Available in OpenSSL builds with "engine" support. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 deleted file mode 100644 index cf881ec8118..00000000000 --- a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_SSL_VERIFYRESULT 3 "1 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_SSL_VERIFYRESULT \- get the result of the certificate verification -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SSL_VERIFYRESULT, - long *result); -.fi -.SH DESCRIPTION -Pass a pointer to a long to receive the result of the server SSL certificate -verification that was requested (using the \fICURLOPT_SSL_VERIFYPEER(3)\fP -option). - -0 is a positive result. Non-zero is an error. -.SH PROTOCOLS -All using TLS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - long verifyresult; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res) - printf("error: %s\\n", curl_easy_strerror(res)); - curl_easy_getinfo(curl, CURLINFO_SSL_VERIFYRESULT, &verifyresult); - printf("The peer verification said %s\\n", verifyresult? - "BAAAD":"fine"); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.5. Only set by the OpenSSL/libressl/boringssl and GnuTLS backends. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_PROXY_SSL_VERIFYRESULT (3) diff --git a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md new file mode 100644 index 00000000000..fdc38f016ee --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_SSL_VERIFYRESULT +Section: 3 +Source: libcurl +See-also: + - CURLINFO_PROXY_SSL_VERIFYRESULT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_SSL_VERIFYRESULT - get the result of the certificate verification + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SSL_VERIFYRESULT, + long *result); +~~~ + +# DESCRIPTION + +Pass a pointer to a long to receive the result of the server SSL certificate +verification that was requested (using the CURLOPT_SSL_VERIFYPEER(3) +option). + +0 is a positive result. Non-zero is an error. + +# PROTOCOLS + +All using TLS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + long verifyresult; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res) + printf("error: %s\n", curl_easy_strerror(res)); + curl_easy_getinfo(curl, CURLINFO_SSL_VERIFYRESULT, &verifyresult); + printf("The peer verification said %s\n", verifyresult? + "BAAAD":"fine"); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.5. Only set by the OpenSSL/libressl/boringssl and GnuTLS backends. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.3 b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.3 deleted file mode 100644 index c9879d2e5e0..00000000000 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_STARTTRANSFER_TIME 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_STARTTRANSFER_TIME \- get the time until the first byte is received -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_STARTTRANSFER_TIME, - double *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the time, in seconds, it took from the -start until the first byte is received by libcurl. This includes -\fICURLINFO_PRETRANSFER_TIME(3)\fP and also the time the server needs to -calculate the result. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - double start; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME, &start); - if(CURLE_OK == res) { - printf("Time: %.1f", start); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.9.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_STARTTRANSFER_TIME_T (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md new file mode 100644 index 00000000000..d7c1f0884bb --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_STARTTRANSFER_TIME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_STARTTRANSFER_TIME_T (3) + - CURLOPT_TIMEOUT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_STARTTRANSFER_TIME - get the time until the first byte is received + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_STARTTRANSFER_TIME, + double *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the first byte is received by libcurl. This includes +CURLINFO_PRETRANSFER_TIME(3) and also the time the server needs to +calculate the result. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double start; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME, &start); + if(CURLE_OK == res) { + printf("Time: %.1f", start); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.9.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.3 b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.3 deleted file mode 100644 index 7638f115ee6..00000000000 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_STARTTRANSFER_TIME_T 3 "28 Apr 2018" libcurl libcurl -.SH NAME -CURLINFO_STARTTRANSFER_TIME_T \- get the time until the first byte is received -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_STARTTRANSFER_TIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the time, in microseconds, -it took from the -start until the first byte is received by libcurl. This includes -\fICURLINFO_PRETRANSFER_TIME_T(3)\fP and also the time the server needs to -calculate the result. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_off_t start; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME_T, &start); - if(CURLE_OK == res) { - printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", start / 1000000, - (long)(start % 1000000)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_STARTTRANSFER_TIME (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md new file mode 100644 index 00000000000..481c7f5bd62 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_STARTTRANSFER_TIME_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_STARTTRANSFER_TIME (3) + - CURLOPT_TIMEOUT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_STARTTRANSFER_TIME_T - get the time until the first byte is received + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_STARTTRANSFER_TIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the time, in microseconds, +it took from the +start until the first byte is received by libcurl. This includes +CURLINFO_PRETRANSFER_TIME_T(3) and also the time the server needs to +calculate the result. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t start; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME_T, &start); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", start / 1000000, + (long)(start % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 b/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 deleted file mode 100644 index 60d648552c1..00000000000 --- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_TLS_SESSION 3 "12 Sep 2015" libcurl libcurl -.SH NAME -CURLINFO_TLS_SESSION \- get TLS session info -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION, - struct curl_tlssessioninfo **session); -.SH DESCRIPTION -\fBThis option has been superseded\fP by \fICURLINFO_TLS_SSL_PTR(3)\fP which -was added in 7.48.0. The only reason you would use this option instead is if -you could be using a version of libcurl earlier than 7.48.0. - -This option is exactly the same as \fICURLINFO_TLS_SSL_PTR(3)\fP except in the -case of OpenSSL. If the session \fIbackend\fP is CURLSSLBACKEND_OPENSSL the -session \fIinternals\fP pointer varies depending on the option: - -\fICURLINFO_TLS_SESSION(3)\fP OpenSSL session \fIinternals\fP is \fBSSL_CTX *\fP. - -\fICURLINFO_TLS_SSL_PTR(3)\fP OpenSSL session \fIinternals\fP is \fBSSL *\fP. - -You can obtain an \fBSSL_CTX\fP pointer from an SSL pointer using OpenSSL -function \fISSL_get_SSL_CTX(3)\fP. Therefore unless you need compatibility -with older versions of libcurl use \fICURLINFO_TLS_SSL_PTR(3)\fP. Refer to -that document for more information. -.SH PROTOCOLS -All TLS-based -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - struct curl_tlssessioninfo *tls; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(res) - printf("error: %s\\n", curl_easy_strerror(res)); - curl_easy_getinfo(curl, CURLINFO_TLS_SESSION, &tls); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.34.0. Deprecated since 7.48.0 and supported OpenSSL, GnuTLS, and -NSS only up until this version was released. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_TLS_SSL_PTR (3) diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md new file mode 100644 index 00000000000..98cc2d67c55 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_TLS_SESSION +Section: 3 +Source: libcurl +See-also: + - CURLINFO_TLS_SSL_PTR (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_TLS_SESSION - get TLS session info + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION, + struct curl_tlssessioninfo **session); +~~~ + +# DESCRIPTION + +**This option has been superseded** by CURLINFO_TLS_SSL_PTR(3) which +was added in 7.48.0. The only reason you would use this option instead is if +you could be using a version of libcurl earlier than 7.48.0. + +This option is exactly the same as CURLINFO_TLS_SSL_PTR(3) except in the +case of OpenSSL. If the session *backend* is CURLSSLBACKEND_OPENSSL the +session *internals* pointer varies depending on the option: + +CURLINFO_TLS_SESSION(3) OpenSSL session *internals* is **SSL_CTX ***. + +CURLINFO_TLS_SSL_PTR(3) OpenSSL session *internals* is **SSL ***. + +You can obtain an **SSL_CTX** pointer from an SSL pointer using OpenSSL +function *SSL_get_SSL_CTX(3)*. Therefore unless you need compatibility +with older versions of libcurl use CURLINFO_TLS_SSL_PTR(3). Refer to +that document for more information. + +# PROTOCOLS + +All TLS-based + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_tlssessioninfo *tls; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(res) + printf("error: %s\n", curl_easy_strerror(res)); + curl_easy_getinfo(curl, CURLINFO_TLS_SESSION, &tls); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.34.0. Deprecated since 7.48.0 and supported OpenSSL, GnuTLS, and +NSS only up until this version was released. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md similarity index 54% rename from docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 rename to docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md index 8c5f2525e03..23b2a2c3f20 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md @@ -1,32 +1,22 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_TLS_SSL_PTR 3 "23 Feb 2016" libcurl libcurl -.SH NAME -CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR \- get TLS session info -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_TLS_SSL_PTR +Section: 3 +Source: libcurl +See-also: + - CURLINFO_TLS_SESSION (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR - get TLS session info + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR, @@ -37,60 +27,75 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR, CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION, struct curl_tlssessioninfo **session); -.SH DESCRIPTION -Pass a pointer to a \fIstruct curl_tlssessioninfo *\fP. The pointer is -initialized to refer to a \fIstruct curl_tlssessioninfo *\fP that contains an -enum indicating the SSL library used for the handshake and a pointer to the -respective internal TLS session structure of this underlying SSL library. +~~~ + +# DESCRIPTION + +Pass a pointer to a *struct curl_tlssessioninfo **. The pointer is initialized +to refer to a *struct curl_tlssessioninfo ** that contains an enum indicating +the SSL library used for the handshake and a pointer to the respective +internal TLS session structure of this underlying SSL library. This option may be useful for example to extract certificate information in a format convenient for further processing, such as manual validation. Refer to -the \fBLIMITATIONS\fP section. +the **LIMITATIONS** section. -.nf +~~~c struct curl_tlssessioninfo { curl_sslbackend backend; void *internals; }; -.fi +~~~ -The \fIbackend\fP struct member is one of the defines in the CURLSSLBACKEND_* +The *backend* struct member is one of the defines in the CURLSSLBACKEND_* series: CURLSSLBACKEND_NONE (when built without TLS support), CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_SCHANNEL or CURLSSLBACKEND_MESALINK. (Note that the OpenSSL forks are all reported as just OpenSSL here.) -The \fIinternals\fP struct member points to a TLS library specific pointer for +The *internals* struct member points to a TLS library specific pointer for the active ("in use") SSL connection, with the following underlying types: -.RS -.IP GnuTLS -\fBgnutls_session_t\fP -.IP NSS -\fBPRFileDesc *\fP -.IP OpenSSL -\fICURLINFO_TLS_SESSION(3)\fP: \fBSSL_CTX *\fP - -\fICURLINFO_TLS_SSL_PTR(3)\fP: \fBSSL *\fP -.RE -Since 7.48.0 the \fIinternals\fP member can point to these other SSL backends + +## GnuTLS + +**gnutls_session_t** + +## NSS + +**PRFileDesc *** + +## OpenSSL + +CURLINFO_TLS_SESSION(3): **SSL_CTX *** + +CURLINFO_TLS_SSL_PTR(3): **SSL *** +Since 7.48.0 the *internals* member can point to these other SSL backends as well: -.RS -.IP mbedTLS -\fBmbedTLS_ssl_context *\fP -.IP "Secure Channel" -\fBCtxtHandle *\fP -.IP "Secure Transport" -\fBSSLContext *\fP -.IP "wolfSSL" -\fBSSL *\fP -.RE - -If the \fIinternals\fP pointer is NULL then either the SSL backend is not + +## mbedTLS + +**mbedTLS_ssl_context *** + +## Secure Channel + +**CtxtHandle *** + +## Secure Transport + +**SSLContext *** + +## wolfSSL + +**SSL *** + +If the *internals* pointer is NULL then either the SSL backend is not supported, an SSL session has not yet been established or the connection is no -longer associated with the easy handle (e.g. \fIcurl_easy_perform(3)\fP has +longer associated with the easy handle (e.g. curl_easy_perform(3) has returned). -.SH LIMITATIONS + +# LIMITATIONS + This option has some limitations that could make it unsafe when it comes to the manual verification of certificates. @@ -102,7 +107,7 @@ retrieve a second in-use SSL session associated with an easy handle. This option has not been thoroughly tested with clear text protocols that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with -\fICURLOPT_USE_SSL(3)\fP. Though you can to retrieve the SSL pointer, it's +CURLOPT_USE_SSL(3). Though you can to retrieve the SSL pointer, it's possible that before you can do that, data (including auth) may have already been sent over a connection after it was upgraded. @@ -113,16 +118,20 @@ after renegotiation but before you are able to get the (possibly) changed SSL pointer, with the (possibly) changed certificate information. Instead of using this option to poll for certificate changes use -\fICURLOPT_SSL_CTX_FUNCTION(3)\fP to set a verification callback, if supported. +CURLOPT_SSL_CTX_FUNCTION(3) to set a verification callback, if supported. That is safer and does not suffer from any of the problems above. How are you using this option? Are you affected by any of these limitations? Please let us know by making a comment at https://github.com/curl/curl/issues/685 -.SH PROTOCOLS + +# PROTOCOLS + All TLS-based -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c #include #include @@ -133,7 +142,7 @@ static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream) CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info); if(info && !res) { if(CURLSSLBACKEND_OPENSSL == info->backend) { - printf("OpenSSL ver. %s\\n", SSL_get_version((SSL*)info->internals)); + printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals)); } } return size * nmemb; @@ -151,15 +160,15 @@ int main(int argc, char **argv) } return res; } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.48.0. -This option supersedes \fICURLINFO_TLS_SESSION(3)\fP which was added in 7.34.0. +This option supersedes CURLINFO_TLS_SESSION(3) which was added in 7.34.0. This option is exactly the same as that option except in the case of OpenSSL. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_TLS_SESSION (3) diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 deleted file mode 100644 index c5519fcb029..00000000000 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_TOTAL_TIME 3 "28 Aug 2015" libcurl libcurl -.SH NAME -CURLINFO_TOTAL_TIME \- get total time of previous transfer -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TOTAL_TIME, double *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a double to receive the total time in seconds for the -previous transfer, including name resolving, TCP connect etc. The double -represents the time in seconds, including fractions. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - double total; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME, &total); - if(CURLE_OK == res) { - printf("Time: %.1f", total); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.4.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_TOTAL_TIME_T (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md new file mode 100644 index 00000000000..c6af1694ed6 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_TOTAL_TIME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_TOTAL_TIME_T (3) + - CURLOPT_TIMEOUT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_TOTAL_TIME - get total time of previous transfer + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TOTAL_TIME, double *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a double to receive the total time in seconds for the +previous transfer, including name resolving, TCP connect etc. The double +represents the time in seconds, including fractions. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + double total; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME, &total); + if(CURLE_OK == res) { + printf("Time: %.1f", total); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.4.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 deleted file mode 100644 index 54a0d547c6c..00000000000 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_TOTAL_TIME_T 3 "28 Apr 2018" libcurl libcurl -.SH NAME -CURLINFO_TOTAL_TIME_T \- get total time of previous transfer in microseconds -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TOTAL_TIME_T, - curl_off_t *timep); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_off_t to receive the total time in microseconds -for the previous transfer, including name resolving, TCP connect etc. -The curl_off_t represents the time in microseconds. - -When a redirect is followed, the time from each request is added together. - -See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_off_t total; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME_T, &total); - if(CURLE_OK == res) { - printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", total / 1000000, - (long)(total % 1000000)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_TOTAL_TIME (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md new file mode 100644 index 00000000000..488d5d3aacb --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_TOTAL_TIME_T +Section: 3 +Source: libcurl +See-also: + - CURLINFO_TOTAL_TIME (3) + - CURLOPT_TIMEOUT (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_TOTAL_TIME_T - get total time of previous transfer in microseconds + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TOTAL_TIME_T, + curl_off_t *timep); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_off_t to receive the total time in microseconds +for the previous transfer, including name resolving, TCP connect etc. +The curl_off_t represents the time in microseconds. + +When a redirect is followed, the time from each request is added together. + +See also the TIMES overview in the curl_easy_getinfo(3) man page. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_off_t total; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME_T, &total); + if(CURLE_OK == res) { + printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", total / 1000000, + (long)(total % 1000000)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLINFO_XFER_ID.3 b/docs/libcurl/opts/CURLINFO_XFER_ID.3 deleted file mode 100644 index b166b20bff7..00000000000 --- a/docs/libcurl/opts/CURLINFO_XFER_ID.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLINFO_XFER_ID 3 "07 June 2023" "libcurl" "libcurl" -.SH NAME -CURLINFO_XFER_ID \- get the ID of a transfer -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_XFER_ID, - curl_off_t *xfer_id); -.fi -.SH DESCRIPTION -Pass a pointer to a \fIcurl_off_t\fP to receive the identifier of the -current/last transfer done with the handle. Stores -1 if no transfer -has been started yet for the handle. - -The transfer id is unique among all transfers performed using the same -connection cache. This is implicitly the case for all transfers in the -same multi handle. - -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Perform the request */ - res = curl_easy_perform(curl); - - if(!res) { - curl_off_t xfer_id; - res = curl_easy_getinfo(curl, CURLINFO_XFER_ID, &xfer_id); - if(!res) { - printf("Transfer ID: %" CURL_FORMAT_CURL_OFF_T "\\n", xfer_id); - } - } - } -} -.fi -.SH AVAILABILITY -Added in 8.2.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR curl_easy_setopt (3), -.BR CURLINFO_CONN_ID (3) diff --git a/docs/libcurl/opts/CURLINFO_XFER_ID.md b/docs/libcurl/opts/CURLINFO_XFER_ID.md new file mode 100644 index 00000000000..b32a46b1238 --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_XFER_ID.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_XFER_ID +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONN_ID (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_XFER_ID - get the ID of a transfer + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_XFER_ID, + curl_off_t *xfer_id); +~~~ + +# DESCRIPTION + +Pass a pointer to a *curl_off_t* to receive the identifier of the +current/last transfer done with the handle. Stores -1 if no transfer +has been started yet for the handle. + +The transfer id is unique among all transfers performed using the same +connection cache. This is implicitly the case for all transfers in the +same multi handle. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Perform the request */ + res = curl_easy_perform(curl); + + if(!res) { + curl_off_t xfer_id; + res = curl_easy_getinfo(curl, CURLINFO_XFER_ID, &xfer_id); + if(!res) { + printf("Transfer ID: %" CURL_FORMAT_CURL_OFF_T "\n", xfer_id); + } + } + } +} +~~~ + +# AVAILABILITY + +Added in 8.2.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 deleted file mode 100644 index 932e333976e..00000000000 --- a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 3 "4 Nov 2014" libcurl libcurl -.SH NAME -CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE \- chunk length threshold for pipelining -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, - long size); -.fi -.SH DESCRIPTION -No function since pipelining was removed in 7.62.0. - -Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is -currently processing a chunked (Transfer-encoding: chunked) request with a -current chunk length larger than \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP, -that pipeline is not considered for additional requests, even if it is shorter -than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. -.SH DEFAULT -The default value is 0, which means that the penalization is inactive. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *m = curl_multi_init(); - long maxchunk = 10000; - curl_multi_setopt(m, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, maxchunk); -} -.fi -.SH AVAILABILITY -Added in 7.30.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3), -.BR CURLMOPT_MAX_PIPELINE_LENGTH (3), -.BR CURLMOPT_PIPELINING (3) diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md new file mode 100644 index 00000000000..127f4dd062b --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3) + - CURLMOPT_MAX_PIPELINE_LENGTH (3) + - CURLMOPT_PIPELINING (3) +--- + +# NAME + +CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE - chunk length threshold for pipelining + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, + long size); +~~~ + +# DESCRIPTION + +No function since pipelining was removed in 7.62.0. + +Pass a long with a **size** in bytes. If a transfer in a pipeline is +currently processing a chunked (Transfer-encoding: chunked) request with a +current chunk length larger than CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3), +that pipeline is not considered for additional requests, even if it is shorter +than CURLMOPT_MAX_PIPELINE_LENGTH(3). + +# DEFAULT + +The default value is 0, which means that the penalization is inactive. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *m = curl_multi_init(); + long maxchunk = 10000; + curl_multi_setopt(m, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, maxchunk); +} +~~~ + +# AVAILABILITY + +Added in 7.30.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 deleted file mode 100644 index 30bbe99ec0c..00000000000 --- a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 +++ /dev/null @@ -1,62 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 3 "4 Nov 2014" libcurl libcurl -.SH NAME -CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE \- size threshold for pipelining penalty -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, - long size); -.fi -.SH DESCRIPTION -No function since pipelining was removed in 7.62.0. - -Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is -currently processing a request with a Content-Length larger than this -\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline is not considered -for additional requests, even if it is shorter than -\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. -.SH DEFAULT -The default value is 0, which means that the size penalization is inactive. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *m = curl_multi_init(); - long maxlength = 10000; - curl_multi_setopt(m, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, maxlength); -} -.fi -.SH AVAILABILITY -Added in 7.30.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PIPELINING (3), -.BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3) diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md new file mode 100644 index 00000000000..d3e7abaf00f --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md @@ -0,0 +1,60 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3) + - CURLMOPT_PIPELINING (3) +--- + +# NAME + +CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE - size threshold for pipelining penalty + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, + long size); +~~~ + +# DESCRIPTION + +No function since pipelining was removed in 7.62.0. + +Pass a long with a **size** in bytes. If a transfer in a pipeline is +currently processing a request with a Content-Length larger than this +CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3), that pipeline is not considered +for additional requests, even if it is shorter than +CURLMOPT_MAX_PIPELINE_LENGTH(3). + +# DEFAULT + +The default value is 0, which means that the size penalization is inactive. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *m = curl_multi_init(); + long maxlength = 10000; + curl_multi_setopt(m, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, maxlength); +} +~~~ + +# AVAILABILITY + +Added in 7.30.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 deleted file mode 100644 index e0d75f2d5d5..00000000000 --- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_MAXCONNECTS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLMOPT_MAXCONNECTS \- size of connection cache -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAXCONNECTS, long max); -.fi -.SH DESCRIPTION -Pass a long indicating the \fBmax\fP. The set number is used as the maximum -amount of simultaneously open connections that libcurl may keep in its -connection cache after completed use. By default libcurl enlarges the size for -each added easy handle to make it fit 4 times the number of added easy -handles. - -By setting this option, you can prevent the cache size from growing beyond the -limit set by you. - -When the cache is full, curl closes the oldest one in the cache to prevent the -number of open connections from increasing. - -This option is for the multi handle's use only, when using the easy interface -you should instead use the \fICURLOPT_MAXCONNECTS(3)\fP option. - -See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP for limiting the number of active -connections. - -.SH DEFAULT -See DESCRIPTION -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *m = curl_multi_init(); - /* only keep 10 connections in the cache */ - curl_multi_setopt(m, CURLMOPT_MAXCONNECTS, 10L); -} -.fi -.SH AVAILABILITY -Added in 7.16.3 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), -.BR CURLOPT_MAXCONNECTS (3) diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md new file mode 100644 index 00000000000..9a5457fa5ce --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_MAXCONNECTS +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_MAX_HOST_CONNECTIONS (3) + - CURLOPT_MAXCONNECTS (3) +--- + +# NAME + +CURLMOPT_MAXCONNECTS - size of connection cache + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAXCONNECTS, long max); +~~~ + +# DESCRIPTION + +Pass a long indicating the **max**. The set number is used as the maximum +amount of simultaneously open connections that libcurl may keep in its +connection cache after completed use. By default libcurl enlarges the size for +each added easy handle to make it fit 4 times the number of added easy +handles. + +By setting this option, you can prevent the cache size from growing beyond the +limit set by you. + +When the cache is full, curl closes the oldest one in the cache to prevent the +number of open connections from increasing. + +This option is for the multi handle's use only, when using the easy interface +you should instead use the CURLOPT_MAXCONNECTS(3) option. + +See CURLMOPT_MAX_TOTAL_CONNECTIONS(3) for limiting the number of active +connections. + +# DEFAULT + +See DESCRIPTION + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *m = curl_multi_init(); + /* only keep 10 connections in the cache */ + curl_multi_setopt(m, CURLMOPT_MAXCONNECTS, 10L); +} +~~~ + +# AVAILABILITY + +Added in 7.16.3 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 deleted file mode 100644 index 7b5741e58a8..00000000000 --- a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 +++ /dev/null @@ -1,61 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_MAX_CONCURRENT_STREAMS 3 "06 Nov 2019" libcurl libcurl -.SH NAME -CURLMOPT_MAX_CONCURRENT_STREAMS \- max concurrent streams for http2 -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_CONCURRENT_STREAMS, - long max); -.fi -.SH DESCRIPTION -Pass a long indicating the \fBmax\fP. The set number is used as the maximum -number of concurrent streams libcurl should support on connections done using -HTTP/2 or HTTP/3. - -Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 100. The -value passed here would be honored based on other system resources properties. -.SH DEFAULT -100 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *m = curl_multi_init(); - /* max concurrent streams 200 */ - curl_multi_setopt(m, CURLMOPT_MAX_CONCURRENT_STREAMS, 200L); -} -.fi -.SH AVAILABILITY -Added in 7.67.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_MAXCONNECTS (3), -.BR CURLOPT_MAXCONNECTS (3) diff --git a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md new file mode 100644 index 00000000000..2471994441a --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md @@ -0,0 +1,59 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_MAX_CONCURRENT_STREAMS +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_MAXCONNECTS (3) + - CURLOPT_MAXCONNECTS (3) +--- + +# NAME + +CURLMOPT_MAX_CONCURRENT_STREAMS - max concurrent streams for http2 + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_CONCURRENT_STREAMS, + long max); +~~~ + +# DESCRIPTION + +Pass a long indicating the **max**. The set number is used as the maximum +number of concurrent streams libcurl should support on connections done using +HTTP/2 or HTTP/3. + +Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 100. The +value passed here would be honored based on other system resources properties. + +# DEFAULT + +100 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *m = curl_multi_init(); + /* max concurrent streams 200 */ + curl_multi_setopt(m, CURLMOPT_MAX_CONCURRENT_STREAMS, 200L); +} +~~~ + +# AVAILABILITY + +Added in 7.67.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 deleted file mode 100644 index fb0f6787ce1..00000000000 --- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_MAX_HOST_CONNECTIONS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLMOPT_MAX_HOST_CONNECTIONS \- max number of connections to a single host -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS, - long max); -.fi -.SH DESCRIPTION -Pass a long to indicate \fBmax\fP. The set number is used as the maximum -amount of simultaneously open connections to a single host (a host being the -same as a host name + port number pair). For each new session to a host, -libcurl might open a new connection up to the limit set by -\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, new -sessions are kept pending until a connection becomes available. - -The default \fBmax\fP value is 0, unlimited. This set limit is also used for -proxy connections, and then the proxy is considered to be the host for which -this limit counts. - -When more transfers are added to the multi handle than what can be performed -due to the set limit, they are queued up waiting for their chance. When that -happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is inclusive of the waiting -time, meaning that if you set a too narrow timeout in such a case the transfer -might never even start before it times out. - -Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP -timeout is however treated as a per-connect timeout. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *m = curl_multi_init(); - /* do no more than 2 connections per host */ - curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L); -} -.fi -.SH AVAILABILITY -Added in 7.30.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_MAXCONNECTS (3), -.BR CURLMOPT_MAX_TOTAL_CONNECTIONS (3) diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md new file mode 100644 index 00000000000..f25778b7c11 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_MAX_HOST_CONNECTIONS +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_MAXCONNECTS (3) + - CURLMOPT_MAX_TOTAL_CONNECTIONS (3) +--- + +# NAME + +CURLMOPT_MAX_HOST_CONNECTIONS - max number of connections to a single host + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS, + long max); +~~~ + +# DESCRIPTION + +Pass a long to indicate **max**. The set number is used as the maximum +amount of simultaneously open connections to a single host (a host being the +same as a host name + port number pair). For each new session to a host, +libcurl might open a new connection up to the limit set by +CURLMOPT_MAX_HOST_CONNECTIONS(3). When the limit is reached, new +sessions are kept pending until a connection becomes available. + +The default **max** value is 0, unlimited. This set limit is also used for +proxy connections, and then the proxy is considered to be the host for which +this limit counts. + +When more transfers are added to the multi handle than what can be performed +due to the set limit, they are queued up waiting for their chance. When that +happens, the CURLOPT_TIMEOUT_MS(3) timeout is inclusive of the waiting +time, meaning that if you set a too narrow timeout in such a case the transfer +might never even start before it times out. + +Even in the queued up situation, the CURLOPT_CONNECTTIMEOUT_MS(3) +timeout is however treated as a per-connect timeout. + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *m = curl_multi_init(); + /* do no more than 2 connections per host */ + curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L); +} +~~~ + +# AVAILABILITY + +Added in 7.30.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 deleted file mode 100644 index 9f2c6ffbe80..00000000000 --- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_MAX_PIPELINE_LENGTH 3 "4 Nov 2014" libcurl libcurl -.SH NAME -CURLMOPT_MAX_PIPELINE_LENGTH \- maximum number of requests in a pipeline -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH, - long max); -.fi -.SH DESCRIPTION -No function since pipelining was removed in 7.62.0. - -Pass a long. The set \fBmax\fP number is used as the maximum amount of -outstanding requests in an HTTP/1.1 pipeline. This option is only used for -HTTP/1.1 pipelining, not for HTTP/2 multiplexing. - -When this limit is reached, libcurl creates another connection to the same -host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until -one of the pipelines to the host is ready to accept a request. Thus, the -total number of requests in-flight is \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP * -\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. -.SH DEFAULT -5 -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *m = curl_multi_init(); - /* set a more conservative pipe length */ - curl_multi_setopt(m, CURLMOPT_MAX_PIPELINE_LENGTH, 3L); -} -.fi -.SH AVAILABILITY -Added in 7.30.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PIPELINING (3), -.BR CURLMOPT_MAX_HOST_CONNECTIONS (3) diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md new file mode 100644 index 00000000000..bad638e5f1a --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_MAX_PIPELINE_LENGTH +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_MAX_HOST_CONNECTIONS (3) + - CURLMOPT_PIPELINING (3) +--- + +# NAME + +CURLMOPT_MAX_PIPELINE_LENGTH - maximum number of requests in a pipeline + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH, + long max); +~~~ + +# DESCRIPTION + +No function since pipelining was removed in 7.62.0. + +Pass a long. The set **max** number is used as the maximum amount of +outstanding requests in an HTTP/1.1 pipeline. This option is only used for +HTTP/1.1 pipelining, not for HTTP/2 multiplexing. + +When this limit is reached, libcurl creates another connection to the same +host (see CURLMOPT_MAX_HOST_CONNECTIONS(3)), or queue the request until one + of the pipelines to the host is ready to accept a request. Thus, the total +number of requests in-flight is CURLMOPT_MAX_HOST_CONNECTIONS(3) * +CURLMOPT_MAX_PIPELINE_LENGTH(3). + +# DEFAULT + +5 + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *m = curl_multi_init(); + /* set a more conservative pipe length */ + curl_multi_setopt(m, CURLMOPT_MAX_PIPELINE_LENGTH, 3L); +} +~~~ + +# AVAILABILITY + +Added in 7.30.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 deleted file mode 100644 index 130822f5692..00000000000 --- a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_MAX_TOTAL_CONNECTIONS 3 "4 Nov 2014" libcurl libcurl -.SH NAME -CURLMOPT_MAX_TOTAL_CONNECTIONS \- max simultaneously open connections -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_TOTAL_CONNECTIONS, - long amount); -.fi -.SH DESCRIPTION -Pass a long for the \fBamount\fP. The set number is used as the maximum number -of simultaneously open connections in total using this multi handle. For each -new session, libcurl might open a new connection up to the limit set by -\fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is reached, new -sessions are held pending until there are available connections. If -\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl can try multiplexing if the -host is capable of it. - -When more transfers are added to the multi handle than what can be performed -due to the set limit, they get queued up waiting for their chance. When that -happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is counted inclusive of the -waiting time, meaning that if you set a too narrow timeout in such a case the -transfer might never even start before it times out. - -Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP -timeout is however treated as a per-connect timeout. -.SH DEFAULT -The default value is 0, which means that there is no limit. It is then simply -controlled by the number of easy handles added. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *m = curl_multi_init(); - /* never do more than 15 connections */ - curl_multi_setopt(m, CURLMOPT_MAX_TOTAL_CONNECTIONS, 15L); -} -.fi -.SH AVAILABILITY -Added in 7.30.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_MAXCONNECTS (3), -.BR CURLMOPT_MAX_HOST_CONNECTIONS (3) diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md new file mode 100644 index 00000000000..859bb2ad564 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_MAX_TOTAL_CONNECTIONS +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_MAXCONNECTS (3) + - CURLMOPT_MAX_HOST_CONNECTIONS (3) +--- + +# NAME + +CURLMOPT_MAX_TOTAL_CONNECTIONS - max simultaneously open connections + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_TOTAL_CONNECTIONS, + long amount); +~~~ + +# DESCRIPTION + +Pass a long for the **amount**. The set number is used as the maximum number +of simultaneously open connections in total using this multi handle. For each +new session, libcurl might open a new connection up to the limit set by +CURLMOPT_MAX_TOTAL_CONNECTIONS(3). When the limit is reached, new +sessions are held pending until there are available connections. If +CURLMOPT_PIPELINING(3) is enabled, libcurl can try multiplexing if the +host is capable of it. + +When more transfers are added to the multi handle than what can be performed +due to the set limit, they get queued up waiting for their chance. When that +happens, the CURLOPT_TIMEOUT_MS(3) timeout is counted inclusive of the +waiting time, meaning that if you set a too narrow timeout in such a case the +transfer might never even start before it times out. + +Even in the queued up situation, the CURLOPT_CONNECTTIMEOUT_MS(3) +timeout is however treated as a per-connect timeout. + +# DEFAULT + +The default value is 0, which means that there is no limit. It is then simply +controlled by the number of easy handles added. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *m = curl_multi_init(); + /* never do more than 15 connections */ + curl_multi_setopt(m, CURLMOPT_MAX_TOTAL_CONNECTIONS, 15L); +} +~~~ + +# AVAILABILITY + +Added in 7.30.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING.3 deleted file mode 100644 index 88777320fab..00000000000 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_PIPELINING 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLMOPT_PIPELINING \- enable HTTP pipelining and multiplexing -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bitmask); -.fi -.SH DESCRIPTION -Pass in the correct value in the \fBbitmask\fP parameter to instruct libcurl -to enable multiplexing for this multi handle. - -With multiplexing enabled, libcurl attempts to do multiple transfers over the -same connection when doing parallel transfers to the same hosts. - -.IP CURLPIPE_NOTHING (0) -Default, which means doing no attempts at multiplexing. -.IP CURLPIPE_HTTP1 (1) -This bit is deprecated and has no effect since version 7.62.0. -.IP CURLPIPE_MULTIPLEX (2) -If this bit is set, libcurl tries to multiplex the new transfer over an -existing connection if possible. This requires HTTP/2 or HTTP/3. -.SH DEFAULT -Since 7.62.0, \fBCURLPIPE_MULTIPLEX\fP is enabled by default. - -Before that, default was \fBCURLPIPE_NOTHING\fP. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURLM *m = curl_multi_init(); - /* try HTTP/2 multiplexing */ - curl_multi_setopt(m, CURLMOPT_PIPELINING, CURLPIPE_MULTIPLEX); -} -.fi -.SH AVAILABILITY -Added in 7.16.0. Multiplex support bit added in 7.43.0. HTTP/1 Pipelining -support was disabled in 7.62.0. -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3), -.BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3), -.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), -.BR CURLMOPT_MAX_PIPELINE_LENGTH (3), -.BR CURLMOPT_MAXCONNECTS (3), -.BR CURLMOPT_PIPELINING_SITE_BL (3) diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.md b/docs/libcurl/opts/CURLMOPT_PIPELINING.md new file mode 100644 index 00000000000..3df71b54fa5 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_PIPELINING +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3) + - CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3) + - CURLMOPT_MAXCONNECTS (3) + - CURLMOPT_MAX_HOST_CONNECTIONS (3) + - CURLMOPT_MAX_PIPELINE_LENGTH (3) + - CURLMOPT_PIPELINING_SITE_BL (3) +--- + +# NAME + +CURLMOPT_PIPELINING - enable HTTP pipelining and multiplexing + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bitmask); +~~~ + +# DESCRIPTION + +Pass in the correct value in the **bitmask** parameter to instruct libcurl +to enable multiplexing for this multi handle. + +With multiplexing enabled, libcurl attempts to do multiple transfers over the +same connection when doing parallel transfers to the same hosts. + +## CURLPIPE_NOTHING (0) + +Default, which means doing no attempts at multiplexing. + +## CURLPIPE_HTTP1 (1) + +This bit is deprecated and has no effect since version 7.62.0. + +## CURLPIPE_MULTIPLEX (2) + +If this bit is set, libcurl tries to multiplex the new transfer over an +existing connection if possible. This requires HTTP/2 or HTTP/3. + +# DEFAULT + +Since 7.62.0, **CURLPIPE_MULTIPLEX** is enabled by default. + +Before that, default was **CURLPIPE_NOTHING**. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURLM *m = curl_multi_init(); + /* try HTTP/2 multiplexing */ + curl_multi_setopt(m, CURLMOPT_PIPELINING, CURLPIPE_MULTIPLEX); +} +~~~ + +# AVAILABILITY + +Added in 7.16.0. Multiplex support bit added in 7.43.0. HTTP/1 Pipelining +support was disabled in 7.62.0. + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 deleted file mode 100644 index b59232fb8c9..00000000000 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_PIPELINING_SERVER_BL 3 "4 Nov 2014" libcurl libcurl -.SH NAME -CURLMOPT_PIPELINING_SERVER_BL \- pipelining server block list -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SERVER_BL, - char **servers); -.fi -.SH DESCRIPTION -No function since pipelining was removed in 7.62.0. - -Pass a \fBservers\fP array of char *, ending with a NULL entry. This is a list -of server types prefixes (in the Server: HTTP header) that are blocked from -pipelining, i.e server types that are known to not support HTTP -pipelining. The array is copied by libcurl. - -Note that the comparison matches if the Server: header begins with the string -in the block list, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can -both be blocked by having "Ninja" in the list. - -Pass a NULL pointer to clear the block list. -.SH DEFAULT -The default value is NULL, which means that there is no block list. -.SH PROTOCOLS -.SH EXAMPLE -.nf -static char *server_block_list[] = -{ - "Microsoft-IIS/6.0", - "nginx/0.8.54", - NULL -}; -int main(void) -{ - CURLM *m = curl_multi_init(); - curl_multi_setopt(m, CURLMOPT_PIPELINING_SERVER_BL, server_block_list); -} -.fi -.SH AVAILABILITY -Added in 7.30.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PIPELINING (3), -.BR CURLMOPT_PIPELINING_SITE_BL (3) diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md new file mode 100644 index 00000000000..226700806f7 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_PIPELINING_SERVER_BL +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PIPELINING (3) + - CURLMOPT_PIPELINING_SITE_BL (3) +--- + +# NAME + +CURLMOPT_PIPELINING_SERVER_BL - pipelining server block list + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SERVER_BL, + char **servers); +~~~ + +# DESCRIPTION + +No function since pipelining was removed in 7.62.0. + +Pass a **servers** array of char *, ending with a NULL entry. This is a list +of server types prefixes (in the Server: HTTP header) that are blocked from +pipelining, i.e server types that are known to not support HTTP +pipelining. The array is copied by libcurl. + +Note that the comparison matches if the Server: header begins with the string +in the block list, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can +both be blocked by having "Ninja" in the list. + +Pass a NULL pointer to clear the block list. + +# DEFAULT + +The default value is NULL, which means that there is no block list. + +# PROTOCOLS + +# EXAMPLE + +~~~c +static char *server_block_list[] = +{ + "Microsoft-IIS/6.0", + "nginx/0.8.54", + NULL +}; +int main(void) +{ + CURLM *m = curl_multi_init(); + curl_multi_setopt(m, CURLMOPT_PIPELINING_SERVER_BL, server_block_list); +} +~~~ + +# AVAILABILITY + +Added in 7.30.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 deleted file mode 100644 index 2bbfbfe2672..00000000000 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_PIPELINING_SITE_BL 3 "4 Nov 2014" libcurl libcurl -.SH NAME -CURLMOPT_PIPELINING_SITE_BL \- pipelining host block list -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SITE_BL, - char **hosts); -.fi -.SH DESCRIPTION -No function since pipelining was removed in 7.62.0. - -Pass a \fBhosts\fP array of char *, ending with a NULL entry. This is a list -of sites that are blocked from pipelining, i.e sites that are known to not -support HTTP pipelining. The array is copied by libcurl. - -Pass a NULL pointer to clear the block list. -.SH DEFAULT -The default value is NULL, which means that there is no block list. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -static char *site_block_list[] = -{ - "www.haxx.se", - "www.example.com:1234", - NULL -}; - -int main(void) -{ - CURLM *m = curl_multi_init(); - curl_multi_setopt(m, CURLMOPT_PIPELINING_SITE_BL, site_block_list); -} -.fi -.SH AVAILABILITY -Added in 7.30.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PIPELINING (3), -.BR CURLMOPT_PIPELINING_SERVER_BL (3) diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md new file mode 100644 index 00000000000..a212c4f6341 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_PIPELINING_SITE_BL +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PIPELINING (3) + - CURLMOPT_PIPELINING_SERVER_BL (3) +--- + +# NAME + +CURLMOPT_PIPELINING_SITE_BL - pipelining host block list + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SITE_BL, + char **hosts); +~~~ + +# DESCRIPTION + +No function since pipelining was removed in 7.62.0. + +Pass a **hosts** array of char *, ending with a NULL entry. This is a list +of sites that are blocked from pipelining, i.e sites that are known to not +support HTTP pipelining. The array is copied by libcurl. + +Pass a NULL pointer to clear the block list. + +# DEFAULT + +The default value is NULL, which means that there is no block list. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +static char *site_block_list[] = +{ + "www.haxx.se", + "www.example.com:1234", + NULL +}; + +int main(void) +{ + CURLM *m = curl_multi_init(); + curl_multi_setopt(m, CURLMOPT_PIPELINING_SITE_BL, site_block_list); +} +~~~ + +# AVAILABILITY + +Added in 7.30.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 deleted file mode 100644 index 8ff04bbe0b9..00000000000 --- a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 +++ /dev/null @@ -1,89 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_PUSHDATA 3 "1 Jun 2015" libcurl libcurl -.SH NAME -CURLMOPT_PUSHDATA \- pointer to pass to push callback -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHDATA, void *pointer); -.fi -.SH DESCRIPTION -Set a \fIpointer\fP to pass as the last argument to the -\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer is not touched or used by -libcurl itself, only passed on to the callback function. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -#include - -/* only allow pushes for file names starting with "push-" */ -int push_callback(CURL *parent, - CURL *easy, - size_t num_headers, - struct curl_pushheaders *headers, - void *clientp) -{ - char *headp; - int *transfers = (int *)clientp; - FILE *out; - headp = curl_pushheader_byname(headers, ":path"); - if(headp && !strncmp(headp, "/push-", 6)) { - fprintf(stderr, "The PATH is %s\\n", headp); - - /* save the push here */ - out = fopen("pushed-stream", "wb"); - - /* write to this file */ - curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); - - (*transfers)++; /* one more */ - - return CURL_PUSH_OK; - } - return CURL_PUSH_DENY; -} - -int main(void) -{ - int counter; - CURLM *multi = curl_multi_init(); - curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback); - curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); -} -.fi -.SH AVAILABILITY -Added in 7.44.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PIPELINING (3), -.BR CURLMOPT_PUSHFUNCTION (3), -.BR CURLOPT_PIPEWAIT (3), -.BR RFC 7540 diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md new file mode 100644 index 00000000000..23e8785f20a --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md @@ -0,0 +1,87 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_PUSHDATA +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PIPELINING (3) + - CURLMOPT_PUSHFUNCTION (3) + - CURLOPT_PIPEWAIT (3) + - RFC 7540 +--- + +# NAME + +CURLMOPT_PUSHDATA - pointer to pass to push callback + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHDATA, void *pointer); +~~~ + +# DESCRIPTION + +Set a *pointer* to pass as the last argument to the +CURLMOPT_PUSHFUNCTION(3) callback. The pointer is not touched or used by +libcurl itself, only passed on to the callback function. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +#include + +/* only allow pushes for file names starting with "push-" */ +int push_callback(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp) +{ + char *headp; + int *transfers = (int *)clientp; + FILE *out; + headp = curl_pushheader_byname(headers, ":path"); + if(headp && !strncmp(headp, "/push-", 6)) { + fprintf(stderr, "The PATH is %s\n", headp); + + /* save the push here */ + out = fopen("pushed-stream", "wb"); + + /* write to this file */ + curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); + + (*transfers)++; /* one more */ + + return CURL_PUSH_OK; + } + return CURL_PUSH_DENY; +} + +int main(void) +{ + int counter; + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback); + curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); +} +~~~ + +# AVAILABILITY + +Added in 7.44.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md similarity index 55% rename from docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 rename to docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md index e1a96218f59..903ac06fb48 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md @@ -1,32 +1,23 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_PUSHFUNCTION 3 "1 Jun 2015" libcurl libcurl -.SH NAME -CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_PUSHFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PIPELINING (3) + - CURLMOPT_PUSHDATA (3) + - CURLOPT_PIPEWAIT (3) + - RFC 7540 +--- + +# NAME + +CURLMOPT_PUSHFUNCTION - callback that approves or denies server pushes + +# SYNOPSIS + +~~~c #include int curl_push_callback(CURL *parent, @@ -37,60 +28,79 @@ int curl_push_callback(CURL *parent, CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION, curl_push_callback func); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This callback gets called when a new HTTP/2 stream is being pushed by the server (using the PUSH_PROMISE frame). If no push callback is set, all offered pushes are denied automatically. -.SH CALLBACK DESCRIPTION + +# CALLBACK DESCRIPTION + The callback gets its arguments like this: -\fIparent\fP is the handle of the stream on which this push arrives. The new +*parent* is the handle of the stream on which this push arrives. The new handle has been duplicated from the parent, meaning that it has gotten all its options inherited. It is then up to the application to alter any options if desired. -\fIeasy\fP is a newly created handle that represents this upcoming transfer. +*easy* is a newly created handle that represents this upcoming transfer. -\fInum_headers\fP is the number of name+value pairs that was received and can +*num_headers* is the number of name+value pairs that was received and can be accessed -\fIheaders\fP is a handle used to access push headers using the accessor +*headers* is a handle used to access push headers using the accessor functions described below. This only accesses and provides the PUSH_PROMISE headers, the normal response headers are provided in the header callback as usual. -\fIclientp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP +*clientp* is the pointer set with CURLMOPT_PUSHDATA(3) If the callback returns CURL_PUSH_OK, the new easy handle is added to the multi handle, the callback must not do that by itself. The callback can access PUSH_PROMISE headers with two accessor functions. These functions can only be used from within this callback and they -can only access the PUSH_PROMISE headers: \fIcurl_pushheader_byname(3)\fP and -\fIcurl_pushheader_bynum(3)\fP. The normal response headers are passed to the +can only access the PUSH_PROMISE headers: curl_pushheader_byname(3) and +curl_pushheader_bynum(3). The normal response headers are passed to the header callback for pushed streams just as for normal streams. -The header fields can also be accessed with \fIcurl_easy_header(3)\fP, +The header fields can also be accessed with curl_easy_header(3), introduced in later libcurl versions. -.SH CALLBACK RETURN VALUE -.IP "CURL_PUSH_OK (0)" + +# CALLBACK RETURN VALUE + +## CURL_PUSH_OK (0) + The application has accepted the stream and it can now start receiving data, the ownership of the CURL handle has been taken over by the application. -.IP "CURL_PUSH_DENY (1)" + +## CURL_PUSH_DENY (1) + The callback denies the stream and no data reaches the application, the easy handle is destroyed by libcurl. -.IP "CURL_PUSH_ERROROUT (2)" + +## CURL_PUSH_ERROROUT (2) + Returning this code rejects the pushed stream and returns an error back on the parent stream making it get closed with an error. (Added in 7.72.0) -.IP * + +## * + All other return codes are reserved for future use. -.SH DEFAULT + +# DEFAULT + NULL, no callback -.SH PROTOCOLS + +# PROTOCOLS + HTTP(S) (HTTP/2 only) -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c #include /* only allow pushes for file names starting with "push-" */ @@ -105,7 +115,7 @@ int push_callback(CURL *parent, FILE *out; headp = curl_pushheader_byname(headers, ":path"); if(headp && !strncmp(headp, "/push-", 6)) { - fprintf(stderr, "The PATH is %s\\n", headp); + fprintf(stderr, "The PATH is %s\n", headp); /* save the push here */ out = fopen("pushed-stream", "wb"); @@ -127,13 +137,12 @@ int main(void) curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback); curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.44.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PUSHDATA (3), -.BR CURLMOPT_PIPELINING (3), -.BR CURLOPT_PIPEWAIT (3), -.BR RFC 7540 diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 deleted file mode 100644 index aeb04dabaf6..00000000000 --- a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 +++ /dev/null @@ -1,83 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_SOCKETDATA 3 "3 Nov 2014" libcurl libcurl -.SH NAME -CURLMOPT_SOCKETDATA \- custom pointer passed to the socket callback -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETDATA, void *pointer); -.SH DESCRIPTION -A data \fIpointer\fP to pass to the socket callback set with the -\fICURLMOPT_SOCKETFUNCTION(3)\fP option. - -This pointer is not touched by libcurl but is only passed in as the socket -callbacks's \fBclientp\fP argument. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct priv { - void *ours; -}; - -static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp) -{ - struct priv *p = sockp; - printf("my ptr: %p\\n", p->ours); - - if(what == CURL_POLL_REMOVE) { - /* remove the socket from our collection */ - } - if(what & CURL_POLL_IN) { - /* wait for read on this socket */ - } - if(what & CURL_POLL_OUT) { - /* wait for write on this socket */ - } - - return 0; -} - -int main(void) -{ - struct priv setup; - CURLM *multi = curl_multi_init(); - /* ... use socket callback and custom pointer */ - curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); - curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); -} -.fi -.SH AVAILABILITY -Added in 7.15.4 -.SH RETURN VALUE -Returns CURLM_OK. -.SH "SEE ALSO" -.BR curl_multi_socket_action (3), -.BR CURLMOPT_SOCKETFUNCTION (3), -.BR CURLMOPT_TIMERFUNCTION (3) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md new file mode 100644 index 00000000000..f4de8c331a1 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md @@ -0,0 +1,82 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_SOCKETDATA +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_SOCKETFUNCTION (3) + - CURLMOPT_TIMERFUNCTION (3) + - curl_multi_socket_action (3) +--- + +# NAME + +CURLMOPT_SOCKETDATA - custom pointer passed to the socket callback + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETDATA, void *pointer); +~~~ + +# DESCRIPTION + +A data *pointer* to pass to the socket callback set with the +CURLMOPT_SOCKETFUNCTION(3) option. + +This pointer is not touched by libcurl but is only passed in as the socket +callbacks's **clientp** argument. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct priv { + void *ours; +}; + +static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp) +{ + struct priv *p = sockp; + printf("my ptr: %p\n", p->ours); + + if(what == CURL_POLL_REMOVE) { + /* remove the socket from our collection */ + } + if(what & CURL_POLL_IN) { + /* wait for read on this socket */ + } + if(what & CURL_POLL_OUT) { + /* wait for write on this socket */ + } + + return 0; +} + +int main(void) +{ + struct priv setup; + CURLM *multi = curl_multi_init(); + /* ... use socket callback and custom pointer */ + curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); + curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); +} +~~~ + +# AVAILABILITY + +Added in 7.15.4 + +# RETURN VALUE + +Returns CURLM_OK. diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 deleted file mode 100644 index 701715dd25e..00000000000 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 +++ /dev/null @@ -1,126 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_SOCKETFUNCTION 3 "3 Nov 2016" libcurl libcurl -.SH NAME -CURLMOPT_SOCKETFUNCTION \- callback informed about what to wait for -.SH SYNOPSIS -.nf -#include - -int socket_callback(CURL *easy, /* easy handle */ - curl_socket_t s, /* socket */ - int what, /* describes the socket */ - void *clientp, /* private callback pointer */ - void *socketp); /* private socket pointer */ - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback); -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -When the \fIcurl_multi_socket_action(3)\fP function is called, it uses this -callback to inform the application about updates in the socket (file -descriptor) status by doing none, one, or multiple calls to the -\fBsocket_callback\fP. The callback function gets status updates with changes -since the previous time the callback was called. If the given callback pointer -is set to NULL, no callback is called. - -libcurl then expects the application to monitor the sockets for the specific -activities and tell libcurl again when something happens on one of them. Tell -libcurl by calling \fIcurl_multi_socket_action(3)\fP. -.SH "CALLBACK ARGUMENTS" -\fIeasy\fP identifies the specific transfer for which this update is related. - -\fIs\fP is the specific socket this function invocation concerns. If the -\fBwhat\fP argument is not CURL_POLL_REMOVE then it holds information about -what activity on this socket the application is supposed to -monitor. Subsequent calls to this callback might update the \fBwhat\fP bits -for a socket that is already monitored. - -The socket callback should return 0 on success, and -1 on error. If this -callback returns error, \fBall\fP transfers currently in progress in this -multi handle are aborted and made to fail. - -\fBclientp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP. - -\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or NULL. - -The \fBwhat\fP parameter informs the callback on the status of the given -socket. It can hold one of these values: -.IP CURL_POLL_IN -Wait for incoming data. For the socket to become readable. -.IP CURL_POLL_OUT -Wait for outgoing data. For the socket to become writable. -.IP CURL_POLL_INOUT -Wait for incoming and outgoing data. For the socket to become readable or -writable. -.IP CURL_POLL_REMOVE -The specified socket/file descriptor is no longer used by libcurl for any -active transfer. It might soon be added again. -.SH DEFAULT -NULL (no callback) -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct priv { - void *ours; -}; - -static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp) -{ - struct priv *p = sockp; - printf("our ptr: %p\\n", p->ours); - - if(what == CURL_POLL_REMOVE) { - /* remove the socket from our collection */ - } - if(what & CURL_POLL_IN) { - /* wait for read on this socket */ - } - if(what & CURL_POLL_OUT) { - /* wait for write on this socket */ - } - - return 0; -} - -int main(void) -{ - struct priv setup; - CURLM *multi = curl_multi_init(); - /* ... use socket callback and custom pointer */ - curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); - curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); -} -.fi -.SH AVAILABILITY -Added in 7.15.4 -.SH RETURN VALUE -Returns CURLM_OK. -.SH "SEE ALSO" -.BR curl_multi_socket_action (3), -.BR CURLMOPT_SOCKETDATA (3), -.BR CURLMOPT_TIMERFUNCTION (3) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md new file mode 100644 index 00000000000..5b34db5f374 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -0,0 +1,135 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_SOCKETFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_SOCKETDATA (3) + - CURLMOPT_TIMERFUNCTION (3) + - curl_multi_socket_action (3) +--- + +# NAME + +CURLMOPT_SOCKETFUNCTION - callback informed about what to wait for + +# SYNOPSIS + +~~~c +#include + +int socket_callback(CURL *easy, /* easy handle */ + curl_socket_t s, /* socket */ + int what, /* describes the socket */ + void *clientp, /* private callback pointer */ + void *socketp); /* private socket pointer */ + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +When the curl_multi_socket_action(3) function is called, it uses this +callback to inform the application about updates in the socket (file +descriptor) status by doing none, one, or multiple calls to the +**socket_callback**. The callback function gets status updates with changes +since the previous time the callback was called. If the given callback pointer +is set to NULL, no callback is called. + +libcurl then expects the application to monitor the sockets for the specific +activities and tell libcurl again when something happens on one of them. Tell +libcurl by calling curl_multi_socket_action(3). + +# CALLBACK ARGUMENTS + +*easy* identifies the specific transfer for which this update is related. + +*s* is the specific socket this function invocation concerns. If the +**what** argument is not CURL_POLL_REMOVE then it holds information about +what activity on this socket the application is supposed to +monitor. Subsequent calls to this callback might update the **what** bits +for a socket that is already monitored. + +The socket callback should return 0 on success, and -1 on error. If this +callback returns error, **all** transfers currently in progress in this +multi handle are aborted and made to fail. + +**clientp** is set with CURLMOPT_SOCKETDATA(3). + +**socketp** is set with curl_multi_assign(3) or NULL. + +The **what** parameter informs the callback on the status of the given +socket. It can hold one of these values: + +## CURL_POLL_IN + +Wait for incoming data. For the socket to become readable. + +## CURL_POLL_OUT + +Wait for outgoing data. For the socket to become writable. + +## CURL_POLL_INOUT + +Wait for incoming and outgoing data. For the socket to become readable or +writable. + +## CURL_POLL_REMOVE + +The specified socket/file descriptor is no longer used by libcurl for any +active transfer. It might soon be added again. + +# DEFAULT + +NULL (no callback) + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct priv { + void *ours; +}; + +static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp) +{ + struct priv *p = sockp; + printf("our ptr: %p\n", p->ours); + + if(what == CURL_POLL_REMOVE) { + /* remove the socket from our collection */ + } + if(what & CURL_POLL_IN) { + /* wait for read on this socket */ + } + if(what & CURL_POLL_OUT) { + /* wait for write on this socket */ + } + + return 0; +} + +int main(void) +{ + struct priv setup; + CURLM *multi = curl_multi_init(); + /* ... use socket callback and custom pointer */ + curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); + curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); +} +~~~ + +# AVAILABILITY + +Added in 7.15.4 + +# RETURN VALUE + +Returns CURLM_OK. diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 deleted file mode 100644 index b3f853d2317..00000000000 --- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_TIMERDATA 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLMOPT_TIMERDATA \- custom pointer to pass to timer callback -.SH SYNOPSIS -.nf -#include - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERDATA, void *pointer); -.SH DESCRIPTION -A data \fBpointer\fP to pass to the timer callback set with the -\fICURLMOPT_TIMERFUNCTION(3)\fP option. - -This pointer is not touched by libcurl but is only be passed in to the timer -callbacks's \fBclientp\fP argument. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct priv { - void *custom; -}; - -static int timerfunc(CURLM *multi, long timeout_ms, void *clientp) -{ - struct priv *mydata = clientp; - printf("our ptr: %p\\n", mydata->custom); - - if(timeout_ms) { - /* this is the new single timeout to wait for */ - } - else { - /* delete the timeout, nothing to wait for now */ - } -} - -int main(void) -{ - struct priv mydata; - CURLM *multi = curl_multi_init(); - curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); - curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata); -} -.fi -.SH AVAILABILITY -Added in 7.16.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_TIMERFUNCTION (3), -.BR CURLMOPT_SOCKETFUNCTION (3) diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md new file mode 100644 index 00000000000..13bbd925b35 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_TIMERDATA +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_SOCKETFUNCTION (3) + - CURLMOPT_TIMERFUNCTION (3) +--- + +# NAME + +CURLMOPT_TIMERDATA - custom pointer to pass to timer callback + +# SYNOPSIS + +~~~c +#include + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERDATA, void *pointer); +~~~ + +# DESCRIPTION + +A data **pointer** to pass to the timer callback set with the +CURLMOPT_TIMERFUNCTION(3) option. + +This pointer is not touched by libcurl but is only be passed in to the timer +callbacks's **clientp** argument. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct priv { + void *custom; +}; + +static int timerfunc(CURLM *multi, long timeout_ms, void *clientp) +{ + struct priv *mydata = clientp; + printf("our ptr: %p\n", mydata->custom); + + if(timeout_ms) { + /* this is the new single timeout to wait for */ + } + else { + /* delete the timeout, nothing to wait for now */ + } +} + +int main(void) +{ + struct priv mydata; + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); + curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata); +} +~~~ + +# AVAILABILITY + +Added in 7.16.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 deleted file mode 100644 index 69ad1516723..00000000000 --- a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 +++ /dev/null @@ -1,104 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLMOPT_TIMERFUNCTION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLMOPT_TIMERFUNCTION \- callback to receive timeout values -.SH SYNOPSIS -.nf -#include - -int timer_callback(CURLM *multi, /* multi handle */ - long timeout_ms, /* timeout in number of ms */ - void *clientp); /* private callback pointer */ - -CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback); -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -Certain features, such as timeouts and retries, require you to call libcurl -even when there is no activity on the file descriptors. - -Your callback function \fBtimer_callback\fP should install a non-repeating -timer with an expire time of \fBtimeout_ms\fP milliseconds. When that timer -fires, call either \fIcurl_multi_socket_action(3)\fP or -\fIcurl_multi_perform(3)\fP, depending on which interface you use. - -A \fBtimeout_ms\fP value of -1 passed to this callback means you should delete -the timer. All other values are valid expire times in number of milliseconds. - -The \fBtimer_callback\fP is called when the timeout expire time is changed. - -The \fBclientp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP. - -The timer callback should return 0 on success, and -1 on error. If this -callback returns error, \fBall\fP transfers currently in progress in this -multi handle are aborted and made to fail. - -This callback can be used instead of, or in addition to, -\fIcurl_multi_timeout(3)\fP. - -\fBWARNING:\fP do not call libcurl directly from within the callback itself -when the \fBtimeout_ms\fP value is zero, since it risks triggering an -unpleasant recursive behavior that immediately calls another call to the -callback with a zero timeout... -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct priv { - void *custom; -}; - -static int timerfunc(CURLM *multi, long timeout_ms, void *clientp) -{ - struct priv *mydata = clientp; - printf("our ptr: %p\\n", mydata->custom); - - if(timeout_ms) { - /* this is the new single timeout to wait for */ - } - else { - /* delete the timeout, nothing to wait for now */ - } -} - -int main(void) -{ - struct priv mydata; - CURLM *multi = curl_multi_init(); - curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); - curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata); -} -.fi -.SH AVAILABILITY -Added in 7.16.0 -.SH RETURN VALUE -Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_TIMERDATA (3), -.BR CURLMOPT_SOCKETFUNCTION (3) diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md new file mode 100644 index 00000000000..83a8fe7e08e --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md @@ -0,0 +1,103 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLMOPT_TIMERFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_SOCKETFUNCTION (3) + - CURLMOPT_TIMERDATA (3) +--- + +# NAME + +CURLMOPT_TIMERFUNCTION - callback to receive timeout values + +# SYNOPSIS + +~~~c +#include + +int timer_callback(CURLM *multi, /* multi handle */ + long timeout_ms, /* timeout in number of ms */ + void *clientp); /* private callback pointer */ + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +Certain features, such as timeouts and retries, require you to call libcurl +even when there is no activity on the file descriptors. + +Your callback function **timer_callback** should install a non-repeating +timer with an expire time of **timeout_ms** milliseconds. When that timer +fires, call either curl_multi_socket_action(3) or +curl_multi_perform(3), depending on which interface you use. + +A **timeout_ms** value of -1 passed to this callback means you should delete +the timer. All other values are valid expire times in number of milliseconds. + +The **timer_callback** is called when the timeout expire time is changed. + +The **clientp** pointer is set with CURLMOPT_TIMERDATA(3). + +The timer callback should return 0 on success, and -1 on error. If this +callback returns error, **all** transfers currently in progress in this +multi handle are aborted and made to fail. + +This callback can be used instead of, or in addition to, +curl_multi_timeout(3). + +**WARNING:** do not call libcurl directly from within the callback itself +when the **timeout_ms** value is zero, since it risks triggering an +unpleasant recursive behavior that immediately calls another call to the +callback with a zero timeout... + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct priv { + void *custom; +}; + +static int timerfunc(CURLM *multi, long timeout_ms, void *clientp) +{ + struct priv *mydata = clientp; + printf("our ptr: %p\n", mydata->custom); + + if(timeout_ms) { + /* this is the new single timeout to wait for */ + } + else { + /* delete the timeout, nothing to wait for now */ + } +} + +int main(void) +{ + struct priv mydata; + CURLM *multi = curl_multi_init(); + curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); + curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata); +} +~~~ + +# AVAILABILITY + +Added in 7.16.0 + +# RETURN VALUE + +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 deleted file mode 100644 index 0e89be55fd4..00000000000 --- a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ABSTRACT_UNIX_SOCKET 3 "08 Jan 2017" libcurl libcurl -.SH NAME -CURLOPT_ABSTRACT_UNIX_SOCKET \- abstract Unix domain socket -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ABSTRACT_UNIX_SOCKET, - char *path); -.fi -.SH DESCRIPTION -Enables the use of an abstract Unix domain socket instead of establishing a -TCP connection to a host. The parameter should be a char * to a -null-terminated string holding the path of the socket. The path is set to -\fIpath\fP prefixed by a NULL byte. This is the convention for abstract -sockets, however it should be stressed that the path passed to this function -should not contain a leading NULL byte. - -On non-supporting platforms, the abstract address is interpreted as an empty -string and fails gracefully, generating a runtime error. - -This option shares the same semantics as \fICURLOPT_UNIX_SOCKET_PATH(3)\fP in -which documentation more details can be found. Internally, these two options -share the same storage and therefore only one of them can be set per handle. -.SH DEFAULT -Default is NULL. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock"); - curl_easy_setopt(curl, CURLOPT_URL, "http://localhost/"); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.53.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_UNIX_SOCKET_PATH (3), -.BR unix (7) diff --git a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md new file mode 100644 index 00000000000..33d2b7bcc1d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ABSTRACT_UNIX_SOCKET +Section: 3 +Source: libcurl +See-also: + - CURLOPT_UNIX_SOCKET_PATH (3) + - unix (7) +--- + +# NAME + +CURLOPT_ABSTRACT_UNIX_SOCKET - abstract Unix domain socket + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ABSTRACT_UNIX_SOCKET, + char *path); +~~~ + +# DESCRIPTION + +Enables the use of an abstract Unix domain socket instead of establishing a +TCP connection to a host. The parameter should be a char * to a +null-terminated string holding the path of the socket. The path is set to +*path* prefixed by a NULL byte. This is the convention for abstract +sockets, however it should be stressed that the path passed to this function +should not contain a leading NULL byte. + +On non-supporting platforms, the abstract address is interpreted as an empty +string and fails gracefully, generating a runtime error. + +This option shares the same semantics as CURLOPT_UNIX_SOCKET_PATH(3) in +which documentation more details can be found. Internally, these two options +share the same storage and therefore only one of them can be set per handle. + +# DEFAULT + +Default is NULL. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock"); + curl_easy_setopt(curl, CURLOPT_URL, "http://localhost/"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.53.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 deleted file mode 100644 index b93142599fe..00000000000 --- a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ACCEPTTIMEOUT_MS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_ACCEPTTIMEOUT_MS \- timeout waiting for FTP server to connect back -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms); -.fi -.SH DESCRIPTION -Pass a long telling libcurl the maximum number of milliseconds to wait for a -server to connect back to libcurl when an active FTP connection is used. -.SH DEFAULT -60000 milliseconds -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/path/file"); - - /* wait no more than 5 seconds for FTP server responses */ - curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 5000L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.24.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CONNECTTIMEOUT_MS (3), -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md new file mode 100644 index 00000000000..77615d886df --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ACCEPTTIMEOUT_MS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT_MS (3) + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_STDERR (3) +--- + +# NAME + +CURLOPT_ACCEPTTIMEOUT_MS - timeout waiting for FTP server to connect back + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms); +~~~ + +# DESCRIPTION + +Pass a long telling libcurl the maximum number of milliseconds to wait for a +server to connect back to libcurl when an active FTP connection is used. + +# DEFAULT + +60000 milliseconds + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/path/file"); + + /* wait no more than 5 seconds for FTP server responses */ + curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 5000L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.24.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md similarity index 52% rename from docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 rename to docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md index 230b6b07f61..9bba40d9d02 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 +++ b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md @@ -1,38 +1,30 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ACCEPT_ENCODING 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_ACCEPT_ENCODING \- automatic decompression of HTTP downloads -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ACCEPT_ENCODING +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPHEADER (3) + - CURLOPT_HTTP_CONTENT_DECODING (3) + - CURLOPT_TRANSFER_ENCODING (3) +--- + +# NAME + +CURLOPT_ACCEPT_ENCODING - automatic decompression of HTTP downloads + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPT_ENCODING, char *enc); -.fi -.SH DESCRIPTION -Pass a char * argument specifying what encoding you would like. +~~~ + +# DESCRIPTION + +Pass a char pointer argument specifying what encoding you would like. Sets the contents of the Accept-Encoding: header sent in an HTTP request, and enables decoding of a response when a Content-Encoding: header is received. @@ -46,22 +38,22 @@ set ("") to ask for an Accept-Encoding: header to be used that contains all built-in supported encodings. Alternatively, you can specify exactly the encoding or list of encodings you -want in the response. The following encodings are supported: \fIidentity\fP, -meaning non-compressed, \fIdeflate\fP which requests the server to compress -its response using the zlib algorithm, \fIgzip\fP which requests the gzip -algorithm, (since curl 7.57.0) \fIbr\fP which is brotli and (since curl -7.72.0) \fIzstd\fP which is zstd. Provide them in the string as a -comma-separated list of accepted encodings, like: \fB"br, gzip, deflate"\fP. - -Set \fICURLOPT_ACCEPT_ENCODING(3)\fP to NULL to explicitly disable it, which +want in the response. The following encodings are supported: *identity*, +meaning non-compressed, *deflate* which requests the server to compress +its response using the zlib algorithm, *gzip* which requests the gzip +algorithm, (since curl 7.57.0) *br* which is brotli and (since curl +7.72.0) *zstd* which is zstd. Provide them in the string as a +comma-separated list of accepted encodings, like: **"br, gzip, deflate"**. + +Set CURLOPT_ACCEPT_ENCODING(3) to NULL to explicitly disable it, which makes libcurl not send an Accept-Encoding: header and not decompress received contents automatically. You can also opt to just include the Accept-Encoding: header in your request -with \fICURLOPT_HTTPHEADER(3)\fP but then there is no automatic decompressing +with CURLOPT_HTTPHEADER(3) but then there is no automatic decompressing when receiving data. -This is a request, not an order; the server may or may not do it. This option +This is a request, not an order; the server may or may not do it. This option must be set (to any non-NULL value) or else any unsolicited encoding done by the server is ignored. @@ -76,12 +68,18 @@ sending the length of the non-compressed content is a common server mistake). The application does not have to keep the string around after setting this option. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + HTTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -95,18 +93,18 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + This option was called CURLOPT_ENCODING before 7.21.6 The specific libcurl you are using must have been built with zlib to be able to decompress gzip and deflate responses, with the brotli library to decompress brotli responses and with the zstd library to decompress zstd responses. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_HTTP_CONTENT_DECODING (3), -.BR CURLOPT_HTTPHEADER (3), -.BR CURLOPT_TRANSFER_ENCODING (3) diff --git a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 deleted file mode 100644 index eea7f88477a..00000000000 --- a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ADDRESS_SCOPE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_ADDRESS_SCOPE \- scope id for IPv6 addresses -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ADDRESS_SCOPE, long scope); -.fi -.SH DESCRIPTION -Pass a long specifying the scope id value to use when connecting to IPv6 addresses. -.SH DEFAULT -0 -.SH PROTOCOLS -All, when using IPv6 -.SH EXAMPLE -.nf -#include /* for if_nametoindex() */ - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - long my_scope_id; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - my_scope_id = if_nametoindex("eth0"); - curl_easy_setopt(curl, CURLOPT_ADDRESS_SCOPE, my_scope_id); - ret = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value. -.SH "SEE ALSO" -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md new file mode 100644 index 00000000000..78526bd39f6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md @@ -0,0 +1,63 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ADDRESS_SCOPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_STDERR (3) +--- + +# NAME + +CURLOPT_ADDRESS_SCOPE - scope id for IPv6 addresses + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ADDRESS_SCOPE, long scope); +~~~ + +# DESCRIPTION + +Pass a long specifying the scope id value to use when connecting to IPv6 addresses. + +# DEFAULT + +0 + +# PROTOCOLS + +All, when using IPv6 + +# EXAMPLE + +~~~c +#include /* for if_nametoindex() */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + long my_scope_id; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + my_scope_id = if_nametoindex("eth0"); + curl_easy_setopt(curl, CURLOPT_ADDRESS_SCOPE, my_scope_id); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value. diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC.3 b/docs/libcurl/opts/CURLOPT_ALTSVC.3 deleted file mode 100644 index 5af38437d93..00000000000 --- a/docs/libcurl/opts/CURLOPT_ALTSVC.3 +++ /dev/null @@ -1,94 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ALTSVC 3 "5 Feb 2019" libcurl libcurl -.SH NAME -CURLOPT_ALTSVC \- alt-svc cache file name -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename); -.fi -.SH DESCRIPTION -Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as -the Alt-Svc cache to read existing cache contents from and possibly also write -it back to after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in -\fICURLOPT_ALTSVC_CTRL(3)\fP. - -Specify a blank file name ("") to make libcurl not load from a file at all. -.SH DEFAULT -NULL. The alt-svc cache is not read nor written to file. -.SH PROTOCOLS -HTTPS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, CURLALTSVC_H1); - curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt"); - curl_easy_perform(curl); - } -} -.fi -.SH "FILE FORMAT" -A text based file with one line per alt-svc entry and each line consists of -nine space-separated fields. - -An example line could look like - - h2 www.example 8443 h3 second.example 443 "20190808 06:18:37" 1 0 - -The fields of that line are: - -.IP h2 -ALPN id for the source origin -.IP www.example -Host name for the source origin -.IP 8443 -Port number for the source origin -.IP h3 -ALPN id for the destination host -.IP second.example -Host name for the destination host -.IP 443 -Port number for the destination host -.IP 2019* -Expiration date and time of this entry within double quotes. The date format -is "YYYYMMDD HH:MM:SS" and the time zone is GMT. -.IP 1 -Boolean (1 or 0) if "persist" was set for this entry -.IP 0 -Integer priority value (not currently used) -.SH AVAILABILITY -Added in 7.64.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_ALTSVC_CTRL (3), -.BR CURLOPT_CONNECT_TO (3), -.BR CURLOPT_COOKIEFILE (3), -.BR CURLOPT_RESOLVE (3) diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC.md b/docs/libcurl/opts/CURLOPT_ALTSVC.md new file mode 100644 index 00000000000..23a353c15ed --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ALTSVC.md @@ -0,0 +1,111 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ALTSVC +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ALTSVC_CTRL (3) + - CURLOPT_CONNECT_TO (3) + - CURLOPT_COOKIEFILE (3) + - CURLOPT_RESOLVE (3) +--- + +# NAME + +CURLOPT_ALTSVC - alt-svc cache file name + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename); +~~~ + +# DESCRIPTION + +Pass in a pointer to a *filename* to instruct libcurl to use that file as +the Alt-Svc cache to read existing cache contents from and possibly also write +it back to after a transfer, unless **CURLALTSVC_READONLYFILE** is set in +CURLOPT_ALTSVC_CTRL(3). + +Specify a blank file name ("") to make libcurl not load from a file at all. + +# DEFAULT + +NULL. The alt-svc cache is not read nor written to file. + +# PROTOCOLS + +HTTPS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, CURLALTSVC_H1); + curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt"); + curl_easy_perform(curl); + } +} +~~~ + +# FILE FORMAT + +A text based file with one line per alt-svc entry and each line consists of +nine space-separated fields. + +An example line could look like + + h2 www.example.com 8443 h3 second.example.com 443 "20190808 06:18:37" 1 0 + +The fields of that line are: + +## h2 + +ALPN id for the source origin + +## www.example.comp + +Host name for the source origin + +## 8443 + +Port number for the source origin + +## h3 + +ALPN id for the destination host + +## second.example.com + +Host name for the destination host + +## 443 + +Port number for the destination host + +## 2019* + +Expiration date and time of this entry within double quotes. The date format +is "YYYYMMDD HH:MM:SS" and the time zone is GMT. + +## 1 + +Boolean (1 or 0) if "persist" was set for this entry + +## 0 + +Integer priority value (not currently used) + +# AVAILABILITY + +Added in 7.64.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 deleted file mode 100644 index 5ba91c4408c..00000000000 --- a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 +++ /dev/null @@ -1,91 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ALTSVC_CTRL 3 "5 Feb 2019" libcurl libcurl -.SH NAME -CURLOPT_ALTSVC_CTRL \- control alt-svc behavior -.SH SYNOPSIS -.nf -#include - -#define CURLALTSVC_READONLYFILE (1<<2) -#define CURLALTSVC_H1 (1<<3) -#define CURLALTSVC_H2 (1<<4) -#define CURLALTSVC_H3 (1<<5) - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC_CTRL, long bitmask); -.fi -.SH DESCRIPTION -Populate the long \fIbitmask\fP with the correct set of features to instruct -libcurl how to handle Alt-Svc for the transfers using this handle. - -libcurl only accepts Alt-Svc headers over a secure transport, meaning -HTTPS. It also only completes a request to an alternative origin if that -origin is properly hosted over HTTPS. These requirements are there to make -sure both the source and the destination are legitimate. - -Alternative services are only used when setting up new connections. If there -exists an existing connection to the host in the connection pool, then that is -preferred. - -Setting any bit enables the alt-svc engine. -.IP "CURLALTSVC_READONLYFILE" -Do not write the alt-svc cache back to the file specified with -\fICURLOPT_ALTSVC(3)\fP even if it gets updated. By default a file specified -with that option is read and written to as deemed necessary. -.IP "CURLALTSVC_H1" -Accept alternative services offered over HTTP/1.1. -.IP "CURLALTSVC_H2" -Accept alternative services offered over HTTP/2. This is only used if libcurl -was also built to actually support HTTP/2, otherwise this bit is ignored. -.IP "CURLALTSVC_H3" -Accept alternative services offered over HTTP/3. This is only used if libcurl -was also built to actually support HTTP/3, otherwise this bit is ignored. -.SH DEFAULT -Alt-Svc handling is disabled by default. If \fICURLOPT_ALTSVC(3)\fP is set, -\fICURLOPT_ALTSVC_CTRL(3)\fP has a default value corresponding to -CURLALTSVC_H1 | CURLALTSVC_H2 | CURLALTSVC_H3 - the HTTP/2 and HTTP/3 bits are -only set if libcurl was built with support for those versions. -.SH PROTOCOLS -HTTPS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, (long)CURLALTSVC_H1); - curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt"); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.64.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_ALTSVC (3), -.BR CURLOPT_CONNECT_TO (3), -.BR CURLOPT_RESOLVE (3) diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md new file mode 100644 index 00000000000..538fc801aeb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md @@ -0,0 +1,97 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ALTSVC_CTRL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ALTSVC (3) + - CURLOPT_CONNECT_TO (3) + - CURLOPT_RESOLVE (3) +--- + +# NAME + +CURLOPT_ALTSVC_CTRL - control alt-svc behavior + +# SYNOPSIS + +~~~c +#include + +#define CURLALTSVC_READONLYFILE (1<<2) +#define CURLALTSVC_H1 (1<<3) +#define CURLALTSVC_H2 (1<<4) +#define CURLALTSVC_H3 (1<<5) + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC_CTRL, long bitmask); +~~~ + +# DESCRIPTION + +Populate the long *bitmask* with the correct set of features to instruct +libcurl how to handle Alt-Svc for the transfers using this handle. + +libcurl only accepts Alt-Svc headers over a secure transport, meaning +HTTPS. It also only completes a request to an alternative origin if that +origin is properly hosted over HTTPS. These requirements are there to make +sure both the source and the destination are legitimate. + +Alternative services are only used when setting up new connections. If there +exists an existing connection to the host in the connection pool, then that is +preferred. + +Setting any bit enables the alt-svc engine. + +## CURLALTSVC_READONLYFILE + +Do not write the alt-svc cache back to the file specified with +CURLOPT_ALTSVC(3) even if it gets updated. By default a file specified +with that option is read and written to as deemed necessary. + +## CURLALTSVC_H1 + +Accept alternative services offered over HTTP/1.1. + +## CURLALTSVC_H2 + +Accept alternative services offered over HTTP/2. This is only used if libcurl +was also built to actually support HTTP/2, otherwise this bit is ignored. + +## CURLALTSVC_H3 + +Accept alternative services offered over HTTP/3. This is only used if libcurl +was also built to actually support HTTP/3, otherwise this bit is ignored. + +# DEFAULT + +Alt-Svc handling is disabled by default. If CURLOPT_ALTSVC(3) is set, +CURLOPT_ALTSVC_CTRL(3) has a default value corresponding to +CURLALTSVC_H1 | CURLALTSVC_H2 | CURLALTSVC_H3 - the HTTP/2 and HTTP/3 bits are +only set if libcurl was built with support for those versions. + +# PROTOCOLS + +HTTPS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, (long)CURLALTSVC_H1); + curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt"); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.64.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_APPEND.3 b/docs/libcurl/opts/CURLOPT_APPEND.3 deleted file mode 100644 index 0830c1a50a7..00000000000 --- a/docs/libcurl/opts/CURLOPT_APPEND.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_APPEND 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_APPEND \- append to the remote file -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_APPEND, long append); -.fi -.SH DESCRIPTION -A long parameter set to 1 tells the library to append to the remote file -instead of overwrite it. This is only useful when uploading to an FTP site. -.SH DEFAULT -0 (disabled) -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); - curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); - curl_easy_setopt(curl, CURLOPT_APPEND, 1L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -This option was known as CURLOPT_FTPAPPEND up to 7.16.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_DIRLISTONLY (3), -.BR CURLOPT_RESUME_FROM (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_APPEND.md b/docs/libcurl/opts/CURLOPT_APPEND.md new file mode 100644 index 00000000000..d507c3812e8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_APPEND.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_APPEND +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DIRLISTONLY (3) + - CURLOPT_RESUME_FROM (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_APPEND - append to the remote file + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_APPEND, long append); +~~~ + +# DESCRIPTION + +A long parameter set to 1 tells the library to append to the remote file +instead of overwrite it. This is only useful when uploading to an FTP site. + +# DEFAULT + +0 (disabled) + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + curl_easy_setopt(curl, CURLOPT_APPEND, 1L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +This option was known as CURLOPT_FTPAPPEND up to 7.16.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 deleted file mode 100644 index e35f7041187..00000000000 --- a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_AUTOREFERER 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_AUTOREFERER \- automatically update the referer header -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AUTOREFERER, long autorefer); -.fi -.SH DESCRIPTION -Pass a long parameter set to 1 to enable this. When enabled, libcurl -automatically sets the Referer: header field in HTTP requests to the full URL -when it follows a Location: redirect to a new destination. - -The automatic referer is set to the full previous URL even when redirects are -done cross-origin or following redirects to insecure protocols. This is -considered a minor privacy leak by some. - -With \fICURLINFO_REFERER(3)\fP, applications can extract the actually used -referer header after the transfer. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - /* follow redirects */ - curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - - /* set Referer: automatically when following redirects */ - curl_easy_setopt(curl, CURLOPT_AUTOREFERER, 1L); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_EFFECTIVE_URL (3), -.BR CURLINFO_REDIRECT_URL (3), -.BR CURLINFO_REFERER (3), -.BR CURLOPT_FOLLOWLOCATION (3), -.BR CURLOPT_REFERER (3) diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.md b/docs/libcurl/opts/CURLOPT_AUTOREFERER.md new file mode 100644 index 00000000000..d201a71ad6e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_AUTOREFERER.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_AUTOREFERER +Section: 3 +Source: libcurl +See-also: + - CURLINFO_EFFECTIVE_URL (3) + - CURLINFO_REDIRECT_URL (3) + - CURLINFO_REFERER (3) + - CURLOPT_FOLLOWLOCATION (3) + - CURLOPT_REFERER (3) +--- + +# NAME + +CURLOPT_AUTOREFERER - automatically update the referer header + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AUTOREFERER, long autorefer); +~~~ + +# DESCRIPTION + +Pass a long parameter set to 1 to enable this. When enabled, libcurl +automatically sets the Referer: header field in HTTP requests to the full URL +when it follows a Location: redirect to a new destination. + +The automatic referer is set to the full previous URL even when redirects are +done cross-origin or following redirects to insecure protocols. This is +considered a minor privacy leak by some. + +With CURLINFO_REFERER(3), applications can extract the actually used +referer header after the transfer. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* follow redirects */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + /* set Referer: automatically when following redirects */ + curl_easy_setopt(curl, CURLOPT_AUTOREFERER, 1L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 deleted file mode 100644 index edc2e6afd06..00000000000 --- a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 +++ /dev/null @@ -1,111 +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.haxx.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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_AWS_SIGV4 3 "03 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_AWS_SIGV4 \- V4 signature -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); -.fi -.SH DESCRIPTION -Provides AWS V4 signature authentication on HTTP(S) header. - -Pass a char * that is the collection of specific arguments are used for -creating outgoing authentication headers. The format of the \fIparam\fP -option is: -.IP provider1[:provider2[:region[:service]]] -.IP "provider1, provider2" -The providers arguments are used for generating some authentication parameters -such as "Algorithm", "date", "request type" and "signed headers". -.IP region -The argument is a geographic area of a resources collection. -It is extracted from the host name specified in the URL if omitted. -.IP service -The argument is a function provided by a cloud. -It is extracted from the host name specified in the URL if omitted. - -NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4. -Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same -as calling this with \fB"aws:amz"\fP in parameter. - -Example with "Test:Try", when curl uses the algorithm, it generates -\fB"TEST-HMAC-SHA256"\fP for "Algorithm", \fB"x-try-date"\fP and -\fB"X-Try-Date"\fP for "date", \fB"test4_request"\fP for "request type", -\fB"SignedHeaders=content-type;host;x-try-date"\fP for "signed headers" - -If you use just "test", instead of "test:try", test is used for every -generated string. -.SH DEFAULT -By default, the value of this parameter is NULL. -Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same -as calling this with \fB"aws:amz"\fP in parameter. -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, - "https://service.region.example.com/uri"); - curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, "provider1:provider2"); - - /* service and region can also be set in CURLOPT_AWS_SIGV4 */ - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri"); - curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, - "provider1:provider2:region:service"); - - curl_easy_setopt(curl, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY"); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.75.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH NOTES -This option overrides the other auth types you might have set in -\fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth -method special. This method cannot be combined with other auth types. - -A sha256 checksum of the request payload is used as input to the signature -calculation. For POST requests, this is a checksum of the provided -\fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer. -For requests like PUT, you can provide your own checksum in an HTTP header named -\fBx-provider2-content-sha256\fP. - -For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request -if not already present. For s3 requests with unknown payload, this header takes -the special value "UNSIGNED-PAYLOAD". -.SH "SEE ALSO" -.BR CURLOPT_HEADEROPT (3), -.BR CURLOPT_HTTPAUTH (3), -.BR CURLOPT_HTTPHEADER (3), -.BR CURLOPT_PROXYAUTH (3) diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md new file mode 100644 index 00000000000..0a5cec9f0b2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md @@ -0,0 +1,118 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_AWS_SIGV4 +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADEROPT (3) + - CURLOPT_HTTPAUTH (3) + - CURLOPT_HTTPHEADER (3) + - CURLOPT_PROXYAUTH (3) +--- + +# NAME + +CURLOPT_AWS_SIGV4 - V4 signature + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); +~~~ + +# DESCRIPTION + +Provides AWS V4 signature authentication on HTTP(S) header. + +Pass a char pointer that is the collection of specific arguments are used for +creating outgoing authentication headers. The format of the *param* option +is: + +## provider1[:provider2[:region[:service]]] + +## provider1, provider2 + +The providers arguments are used for generating some authentication parameters +such as "Algorithm", "date", "request type" and "signed headers". + +## region + +The argument is a geographic area of a resources collection. +It is extracted from the host name specified in the URL if omitted. + +## service + +The argument is a function provided by a cloud. +It is extracted from the host name specified in the URL if omitted. + +NOTE: This call set CURLOPT_HTTPAUTH(3) to CURLAUTH_AWS_SIGV4. +Calling CURLOPT_HTTPAUTH(3) with CURLAUTH_AWS_SIGV4 is the same +as calling this with **"aws:amz"** in parameter. + +Example with "Test:Try", when curl uses the algorithm, it generates +**"TEST-HMAC-SHA256"** for "Algorithm", **"x-try-date"** and +**"X-Try-Date"** for "date", **"test4_request"** for "request type", +**"SignedHeaders=content-type;host;x-try-date"** for "signed headers" + +If you use just "test", instead of "test:try", test is used for every +generated string. + +# DEFAULT + +By default, the value of this parameter is NULL. +Calling CURLOPT_HTTPAUTH(3) with CURLAUTH_AWS_SIGV4 is the same +as calling this with **"aws:amz"** in parameter. + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, + "https://service.region.example.com/uri"); + curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, "provider1:provider2"); + + /* service and region can also be set in CURLOPT_AWS_SIGV4 */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri"); + curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, + "provider1:provider2:region:service"); + + curl_easy_setopt(curl, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY"); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.75.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. + +# NOTES + +This option overrides the other auth types you might have set in +CURLOPT_HTTPAUTH(3) which should be highlighted as this makes this auth +method special. This method cannot be combined with other auth types. + +A sha256 checksum of the request payload is used as input to the signature +calculation. For POST requests, this is a checksum of the provided +CURLOPT_POSTFIELDS(3). Otherwise, it's the checksum of an empty buffer. +For requests like PUT, you can provide your own checksum in an HTTP header named +**x-provider2-content-sha256**. + +For **aws:s3**, a **x-amz-content-sha256** header is added to every request +if not already present. For s3 requests with unknown payload, this header takes +the special value "UNSIGNED-PAYLOAD". diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 deleted file mode 100644 index 5ec1a450e7f..00000000000 --- a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_BUFFERSIZE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_BUFFERSIZE \- receive buffer size -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_BUFFERSIZE, long size); -.fi -.SH DESCRIPTION -Pass a long specifying your preferred \fIsize\fP (in bytes) for the receive -buffer in libcurl. The main point of this would be that the write callback -gets called more often and with smaller chunks. Secondly, for some protocols, -there is a benefit of having a larger buffer for performance. - -This is just treated as a request, not an order. You cannot be guaranteed to -actually get the given size. - -This buffer size is by default \fICURL_MAX_WRITE_SIZE\fP (16kB). The maximum -buffer size allowed to be set is \fICURL_MAX_READ_SIZE\fP (10MB). The minimum -buffer size allowed to be set is 1024. - -DO NOT set this option on a handle that is currently used for an active -transfer as that may lead to unintended consequences. - -The maximum size was 512kB until 7.88.0. -.SH DEFAULT -CURL_MAX_WRITE_SIZE (16kB) -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin"); - - /* ask libcurl to allocate a larger receive buffer */ - curl_easy_setopt(curl, CURLOPT_BUFFERSIZE, 120000L); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10. Growing the buffer was added in 7.53.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), -.BR CURLOPT_MAXFILESIZE (3), -.BR CURLOPT_UPLOAD_BUFFERSIZE (3), -.BR CURLOPT_WRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md new file mode 100644 index 00000000000..1faebeef54b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md @@ -0,0 +1,79 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_BUFFERSIZE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAXFILESIZE (3) + - CURLOPT_MAX_RECV_SPEED_LARGE (3) + - CURLOPT_UPLOAD_BUFFERSIZE (3) + - CURLOPT_WRITEFUNCTION (3) +--- + +# NAME + +CURLOPT_BUFFERSIZE - receive buffer size + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_BUFFERSIZE, long size); +~~~ + +# DESCRIPTION + +Pass a long specifying your preferred *size* (in bytes) for the receive buffer +in libcurl. The main point of this would be that the write callback gets +called more often and with smaller chunks. Secondly, for some protocols, there +is a benefit of having a larger buffer for performance. + +This is just treated as a request, not an order. You cannot be guaranteed to +actually get the given size. + +This buffer size is by default *CURL_MAX_WRITE_SIZE* (16kB). The maximum +buffer size allowed to be set is *CURL_MAX_READ_SIZE* (10MB). The minimum +buffer size allowed to be set is 1024. + +DO NOT set this option on a handle that is currently used for an active +transfer as that may lead to unintended consequences. + +The maximum size was 512kB until 7.88.0. + +# DEFAULT + +CURL_MAX_WRITE_SIZE (16kB) + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin"); + + /* ask libcurl to allocate a larger receive buffer */ + curl_easy_setopt(curl, CURLOPT_BUFFERSIZE, 120000L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10. Growing the buffer was added in 7.53.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.3 b/docs/libcurl/opts/CURLOPT_CAINFO.3 deleted file mode 100644 index f4e151eff18..00000000000 --- a/docs/libcurl/opts/CURLOPT_CAINFO.3 +++ /dev/null @@ -1,89 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CAINFO 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CAINFO \- path to Certificate Authority (CA) bundle -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO, char *path); -.fi -.SH DESCRIPTION -Pass a char * to a null-terminated string naming a file holding one or more -certificates to verify the peer with. - -If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the -server's certificate, \fICURLOPT_CAINFO(3)\fP need not even indicate an -accessible file. - -This option is by default set to the system path where libcurl's CA -certificate bundle is assumed to be stored, as established at build time. - -(iOS and macOS) When curl uses Secure Transport this option is supported. If -the option is not set, then curl uses the certificates in the system and user -Keychain to verify the peer. - -(Schannel) This option is supported for Schannel in Windows 7 or later but we -recommend not using it until Windows 8 since it works better starting then. -If the option is not set, then curl uses the certificates in the Windows' -store of root certificates (the default for Schannel). - -The application does not have to keep the string around after setting this -option. - -The default value for this can be figured out with \fICURLINFO_CAINFO(3)\fP. -.SH DEFAULT -Built-in system specific. When curl is built with Secure Transport or -Schannel, this option is not set by default. -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_CAINFO, "/etc/certs/cabundle.pem"); - curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -For the SSL engines that do not support certificate files the -\fICURLOPT_CAINFO(3)\fP option is ignored. Schannel support added in libcurl -7.60. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLINFO_CAINFO (3), -.BR CURLOPT_CA_CACHE_TIMEOUT (3), -.BR CURLOPT_CAINFO_BLOB (3), -.BR CURLOPT_CAPATH (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.md b/docs/libcurl/opts/CURLOPT_CAINFO.md new file mode 100644 index 00000000000..c46073ff850 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CAINFO.md @@ -0,0 +1,87 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CAINFO +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CAINFO (3) + - CURLOPT_CAINFO_BLOB (3) + - CURLOPT_CAPATH (3) + - CURLOPT_CA_CACHE_TIMEOUT (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_CAINFO - path to Certificate Authority (CA) bundle + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO, char *path); +~~~ + +# DESCRIPTION + +Pass a char pointer to a null-terminated string naming a file holding one or +more certificates to verify the peer with. + +If CURLOPT_SSL_VERIFYPEER(3) is zero and you avoid verifying the +server's certificate, CURLOPT_CAINFO(3) need not even indicate an +accessible file. + +This option is by default set to the system path where libcurl's CA +certificate bundle is assumed to be stored, as established at build time. + +(iOS and macOS) When curl uses Secure Transport this option is supported. If +the option is not set, then curl uses the certificates in the system and user +Keychain to verify the peer. + +(Schannel) This option is supported for Schannel in Windows 7 or later but we +recommend not using it until Windows 8 since it works better starting then. +If the option is not set, then curl uses the certificates in the Windows' +store of root certificates (the default for Schannel). + +The application does not have to keep the string around after setting this +option. + +The default value for this can be figured out with CURLINFO_CAINFO(3). + +# DEFAULT + +Built-in system specific. When curl is built with Secure Transport or +Schannel, this option is not set by default. + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_CAINFO, "/etc/certs/cabundle.pem"); + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +For the SSL engines that do not support certificate files the +CURLOPT_CAINFO(3) option is ignored. Schannel support added in libcurl +7.60. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 deleted file mode 100644 index db3bed9411f..00000000000 --- a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 +++ /dev/null @@ -1,85 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CAINFO_BLOB 3 "31 March 2021" libcurl libcurl -.SH NAME -CURLOPT_CAINFO_BLOB \- Certificate Authority (CA) bundle in PEM format -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO_BLOB, - struct curl_blob *stblob); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_blob structure, which contains information (pointer -and size) about a memory block with binary data of PEM encoded content holding -one or more certificates to verify the HTTPS server with. - -If the blob is initialized with the flags member of struct curl_blob set to -CURL_BLOB_COPY, the application does not have to keep the buffer around after -setting this. - -If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the -server's certificate, \fICURLOPT_CAINFO_BLOB(3)\fP is not needed. - -This option overrides \fICURLOPT_CAINFO(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -#include - -int main(void) -{ - char *strpem; /* strpem must point to a PEM string */ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - struct curl_blob blob; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - blob.data = strpem; - blob.len = strlen(strpem); - blob.flags = CURL_BLOB_COPY; - curl_easy_setopt(curl, CURLOPT_CAINFO_BLOB, &blob); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.77.0. - -This option is supported by the BearSSL (since 7.79.0), mbedTLS (since 7.81.0), -rustls (since 7.82.0), wolfSSL (since 8.2.0), OpenSSL, Secure Transport and Schannel backends. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_CAPATH (3), -.BR CURLOPT_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3) diff --git a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md new file mode 100644 index 00000000000..be30446ff23 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md @@ -0,0 +1,84 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CAINFO_BLOB +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_CAPATH (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_CAINFO_BLOB - Certificate Authority (CA) bundle in PEM format + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO_BLOB, + struct curl_blob *stblob); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_blob structure, which contains information (pointer +and size) about a memory block with binary data of PEM encoded content holding +one or more certificates to verify the HTTPS server with. + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +If CURLOPT_SSL_VERIFYPEER(3) is zero and you avoid verifying the +server's certificate, CURLOPT_CAINFO_BLOB(3) is not needed. + +This option overrides CURLOPT_CAINFO(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +#include + +int main(void) +{ + char *strpem; /* strpem must point to a PEM string */ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + blob.data = strpem; + blob.len = strlen(strpem); + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_CAINFO_BLOB, &blob); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.77.0. + +This option is supported by the BearSSL (since 7.79.0), mbedTLS (since +7.81.0), rustls (since 7.82.0), wolfSSL (since 8.2.0), OpenSSL, Secure +Transport and Schannel backends. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.3 b/docs/libcurl/opts/CURLOPT_CAPATH.3 deleted file mode 100644 index 8288ee334fa..00000000000 --- a/docs/libcurl/opts/CURLOPT_CAPATH.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CAPATH 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CAPATH \- directory holding CA certificates -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAPATH, char *capath); -.fi -.SH DESCRIPTION -Pass a char * to a null-terminated string naming a directory holding multiple -CA certificates to verify the peer with. If libcurl is built against OpenSSL, -the certificate directory must be prepared using the OpenSSL c_rehash utility. -This makes sense only when used in combination with the -\fICURLOPT_SSL_VERIFYPEER(3)\fP option. - -The \fICURLOPT_CAPATH(3)\fP function apparently does not work in Windows due -to some limitation in OpenSSL. - -The application does not have to keep the string around after setting this -option. - -The default value for this can be figured out with \fICURLINFO_CAPATH(3)\fP. -.SH DEFAULT -A default path detected at build time. -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_CAPATH, "/etc/cert-dir"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option is supported by the OpenSSL, GnuTLS and mbedTLS (since 7.56.0) -backends. -.SH RETURN VALUE -CURLE_OK if supported; or an error such as: - -CURLE_NOT_BUILT_IN - Not supported by the SSL backend - -CURLE_UNKNOWN_OPTION - -CURLE_OUT_OF_MEMORY -.SH "SEE ALSO" -.BR CURLINFO_CAPATH (3), -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.md b/docs/libcurl/opts/CURLOPT_CAPATH.md new file mode 100644 index 00000000000..ff1362f5232 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CAPATH.md @@ -0,0 +1,79 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CAPATH +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CAPATH (3) + - CURLOPT_CAINFO (3) + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_STDERR (3) +--- + +# NAME + +CURLOPT_CAPATH - directory holding CA certificates + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAPATH, char *capath); +~~~ + +# DESCRIPTION + +Pass a char pointer to a null-terminated string naming a directory holding +multiple CA certificates to verify the peer with. If libcurl is built against +OpenSSL, the certificate directory must be prepared using the OpenSSL c_rehash +utility. This makes sense only when used in combination with the +CURLOPT_SSL_VERIFYPEER(3) option. + +The CURLOPT_CAPATH(3) function apparently does not work in Windows due +to some limitation in OpenSSL. + +The application does not have to keep the string around after setting this +option. + +The default value for this can be figured out with CURLINFO_CAPATH(3). + +# DEFAULT + +A default path detected at build time. + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_CAPATH, "/etc/cert-dir"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option is supported by the OpenSSL, GnuTLS and mbedTLS (since 7.56.0) +backends. + +# RETURN VALUE + +CURLE_OK if supported; or an error such as: + +CURLE_NOT_BUILT_IN - Not supported by the SSL backend + +CURLE_UNKNOWN_OPTION + +CURLE_OUT_OF_MEMORY diff --git a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 deleted file mode 100644 index 8c2635120a1..00000000000 --- a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 +++ /dev/null @@ -1,84 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CA_CACHE_TIMEOUT 3 "21 Dec 2022" libcurl libcurl -.SH NAME -CURLOPT_CA_CACHE_TIMEOUT \- life-time for cached certificate stores -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CA_CACHE_TIMEOUT, long age); -.fi -.SH DESCRIPTION -Pass a long, this sets the timeout in seconds. This tells libcurl the maximum -time any cached certificate store it has in memory may be kept and reused for -new connections. Once the timeout has expired, a subsequent fetch requiring a -certificate has to reload it. - -Building a certificate store from a \fICURLOPT_CAINFO(3)\fP file is a slow -operation so curl may cache the generated certificate store internally to speed -up future connections. - -Set to zero to completely disable caching, or set to -1 to retain the cached -store remain forever. By default, libcurl caches this info for 24 hours. -.SH DEFAULT -86400 (24 hours) -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - /* only reuse certificate stores for a short time */ - curl_easy_setopt(curl, CURLOPT_CA_CACHE_TIMEOUT, 60L); - - res = curl_easy_perform(curl); - - /* in this second request, the cache is not used if more than - sixty seconds passed since the previous connection */ - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option was added in curl 7.87.0. - -This option is supported by OpenSSL and its forks (since 7.87.0) and Schannel -(since 8.5.0). -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_CAINFO_BLOB (3), -.BR CURLOPT_CAPATH (3), -.BR CURLOPT_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3) diff --git a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md new file mode 100644 index 00000000000..ef52f976dd7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md @@ -0,0 +1,82 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CA_CACHE_TIMEOUT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_CAINFO_BLOB (3) + - CURLOPT_CAPATH (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_CA_CACHE_TIMEOUT - life-time for cached certificate stores + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CA_CACHE_TIMEOUT, long age); +~~~ + +# DESCRIPTION + +Pass a long, this sets the timeout in seconds. This tells libcurl the maximum +time any cached certificate store it has in memory may be kept and reused for +new connections. Once the timeout has expired, a subsequent fetch requiring a +certificate has to reload it. + +Building a certificate store from a CURLOPT_CAINFO(3) file is a slow +operation so curl may cache the generated certificate store internally to speed +up future connections. + +Set to zero to completely disable caching, or set to -1 to retain the cached +store remain forever. By default, libcurl caches this info for 24 hours. + +# DEFAULT + +86400 (24 hours) + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* only reuse certificate stores for a short time */ + curl_easy_setopt(curl, CURLOPT_CA_CACHE_TIMEOUT, 60L); + + res = curl_easy_perform(curl); + + /* in this second request, the cache is not used if more than + sixty seconds passed since the previous connection */ + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option was added in curl 7.87.0. + +This option is supported by OpenSSL and its forks (since 7.87.0) and Schannel +(since 8.5.0). + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.3 b/docs/libcurl/opts/CURLOPT_CERTINFO.3 deleted file mode 100644 index 7b201340764..00000000000 --- a/docs/libcurl/opts/CURLOPT_CERTINFO.3 +++ /dev/null @@ -1,92 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CERTINFO 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CERTINFO \- request SSL certificate information -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CERTINFO, long certinfo); -.fi -.SH DESCRIPTION -Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With -this enabled, libcurl extracts lots of information and data about the -certificates in the certificate chain used in the SSL connection. This data -may then be retrieved after a transfer using \fIcurl_easy_getinfo(3)\fP and -its option \fICURLINFO_CERTINFO(3)\fP. -.SH DEFAULT -0 -.SH PROTOCOLS -All TLS-based -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); - - /* connect to any HTTPS site, trusted or not */ - curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); - curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); - - curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L); - - res = curl_easy_perform(curl); - - if(!res) { - struct curl_certinfo *ci; - res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); - - if(!res) { - int i; - printf("%d certs!\\n", ci->num_of_certs); - - for(i = 0; i < ci->num_of_certs; i++) { - struct curl_slist *slist; - - for(slist = ci->certinfo[i]; slist; slist = slist->next) - printf("%s\\n", slist->data); - } - } - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option is supported by the OpenSSL, GnuTLS, Schannel and Secure -Transport backends. Schannel support added in 7.50.0. Secure Transport support -added in 7.79.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_CAINFO (3), -.BR CURLINFO_CAPATH (3), -.BR CURLINFO_CERTINFO (3), -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.md b/docs/libcurl/opts/CURLOPT_CERTINFO.md new file mode 100644 index 00000000000..a69e1e9503c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CERTINFO.md @@ -0,0 +1,90 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CERTINFO +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CAINFO (3) + - CURLINFO_CAPATH (3) + - CURLINFO_CERTINFO (3) + - CURLOPT_CAINFO (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_CERTINFO - request SSL certificate information + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CERTINFO, long certinfo); +~~~ + +# DESCRIPTION + +Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With +this enabled, libcurl extracts lots of information and data about the +certificates in the certificate chain used in the SSL connection. This data +may then be retrieved after a transfer using curl_easy_getinfo(3) and +its option CURLINFO_CERTINFO(3). + +# DEFAULT + +0 + +# PROTOCOLS + +All TLS-based + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); + + /* connect to any HTTPS site, trusted or not */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); + + curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L); + + res = curl_easy_perform(curl); + + if(!res) { + struct curl_certinfo *ci; + res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); + + if(!res) { + int i; + printf("%d certs!\n", ci->num_of_certs); + + for(i = 0; i < ci->num_of_certs; i++) { + struct curl_slist *slist; + + for(slist = ci->certinfo[i]; slist; slist = slist->next) + printf("%s\n", slist->data); + } + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option is supported by the OpenSSL, GnuTLS, Schannel and Secure +Transport backends. Schannel support added in 7.50.0. Secure Transport support +added in 7.79.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md similarity index 53% rename from docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 rename to docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md index 88f3768c955..a208c9bbe57 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md @@ -1,32 +1,21 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CHUNK_BGN_FUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcard match -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CHUNK_BGN_FUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CHUNK_END_FUNCTION (3) + - CURLOPT_WILDCARDMATCH (3) +--- + +# NAME + +CURLOPT_CHUNK_BGN_FUNCTION - callback before a transfer with FTP wildcard match + +# SYNOPSIS + +~~~c #include struct curl_fileinfo { @@ -61,35 +50,44 @@ long chunk_bgn_callback(const void *transfer_info, void *ptr, CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_BGN_FUNCTION, chunk_bgn_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl before a part of the stream is going to be transferred (if the transfer supports chunks). -The \fItransfer_info\fP pointer points to a \fBcurl_fileinfo\fP struct with +The *transfer_info* pointer points to a **curl_fileinfo** struct with details about the file that is about to get transferred. -This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH(3)\fP +This callback makes sense only when using the CURLOPT_WILDCARDMATCH(3) option for now. The target of transfer_info parameter is a "feature depended" structure. For -the FTP wildcard download, the target is \fBcurl_fileinfo\fP structure (see -\fIcurl/curl.h\fP). The parameter \fIptr\fP is a pointer given by -\fICURLOPT_CHUNK_DATA(3)\fP. The parameter remains contains number of chunks +the FTP wildcard download, the target is **curl_fileinfo** structure (see +*curl/curl.h*). The parameter *ptr* is a pointer given by +CURLOPT_CHUNK_DATA(3). The parameter remains contains number of chunks remaining per the transfer. If the feature is not available, the parameter has zero value. -Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine, -\fICURL_CHUNK_BGN_FUNC_SKIP\fP if you want to skip the concrete chunk or -\fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred. -.SH DEFAULT +Return *CURL_CHUNK_BGN_FUNC_OK* if everything is fine, +*CURL_CHUNK_BGN_FUNC_SKIP* if you want to skip the concrete chunk or +*CURL_CHUNK_BGN_FUNC_FAIL* to tell libcurl to stop if some error occurred. + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + FTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c #include struct callback_data { @@ -106,20 +104,20 @@ static long file_is_coming(struct curl_fileinfo *finfo, switch(finfo->filetype) { case CURLFILETYPE_DIRECTORY: - printf(" DIR\\n"); + printf(" DIR\n"); break; case CURLFILETYPE_FILE: printf("FILE "); break; default: - printf("OTHER\\n"); + printf("OTHER\n"); break; } if(finfo->filetype == CURLFILETYPE_FILE) { /* do not transfer files >= 50B */ if(finfo->size > 50) { - printf("SKIPPED\\n"); + printf("SKIPPED\n"); return CURL_CHUNK_BGN_FUNC_SKIP; } @@ -143,11 +141,12 @@ int main() curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming); curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + This was added in 7.21.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CHUNK_END_FUNCTION (3), -.BR CURLOPT_WILDCARDMATCH (3) diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 deleted file mode 100644 index a4e35244da8..00000000000 --- a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 +++ /dev/null @@ -1,104 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CHUNK_DATA 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CHUNK_DATA \- pointer passed to the FTP chunk callbacks -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_DATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP that is untouched by libcurl and passed as the ptr -argument to the \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP and -\fICURLOPT_CHUNK_END_FUNCTION(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -#include - -struct callback_data { - FILE *output; -}; - -static long file_is_coming(struct curl_fileinfo *finfo, - void *ptr, - int remains) -{ - struct callback_data *data = ptr; - printf("%3d %40s %10luB ", remains, finfo->filename, - (unsigned long)finfo->size); - - switch(finfo->filetype) { - case CURLFILETYPE_DIRECTORY: - printf(" DIR\\n"); - break; - case CURLFILETYPE_FILE: - printf("FILE "); - break; - default: - printf("OTHER\\n"); - break; - } - - if(finfo->filetype == CURLFILETYPE_FILE) { - /* do not transfer files >= 50B */ - if(finfo->size > 50) { - printf("SKIPPED\\n"); - return CURL_CHUNK_BGN_FUNC_SKIP; - } - - data->output = fopen(finfo->filename, "wb"); - if(!data->output) { - return CURL_CHUNK_BGN_FUNC_FAIL; - } - } - - return CURL_CHUNK_BGN_FUNC_OK; -} - -int main() -{ - /* data for callback */ - struct callback_data callback_info; - - CURL *curl = curl_easy_init(); - - /* callback is called before download of concrete file started */ - curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming); - curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); -} -.fi -.SH AVAILABILITY -Added in 7.21.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CHUNK_BGN_FUNCTION (3), -.BR CURLOPT_WILDCARDMATCH (3) diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md new file mode 100644 index 00000000000..3640ec8df15 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md @@ -0,0 +1,102 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CHUNK_DATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CHUNK_BGN_FUNCTION (3) + - CURLOPT_WILDCARDMATCH (3) +--- + +# NAME + +CURLOPT_CHUNK_DATA - pointer passed to the FTP chunk callbacks + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_DATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* that is untouched by libcurl and passed as the ptr +argument to the CURLOPT_CHUNK_BGN_FUNCTION(3) and +CURLOPT_CHUNK_END_FUNCTION(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +#include + +struct callback_data { + FILE *output; +}; + +static long file_is_coming(struct curl_fileinfo *finfo, + void *ptr, + int remains) +{ + struct callback_data *data = ptr; + printf("%3d %40s %10luB ", remains, finfo->filename, + (unsigned long)finfo->size); + + switch(finfo->filetype) { + case CURLFILETYPE_DIRECTORY: + printf(" DIR\n"); + break; + case CURLFILETYPE_FILE: + printf("FILE "); + break; + default: + printf("OTHER\n"); + break; + } + + if(finfo->filetype == CURLFILETYPE_FILE) { + /* do not transfer files >= 50B */ + if(finfo->size > 50) { + printf("SKIPPED\n"); + return CURL_CHUNK_BGN_FUNC_SKIP; + } + + data->output = fopen(finfo->filename, "wb"); + if(!data->output) { + return CURL_CHUNK_BGN_FUNC_FAIL; + } + } + + return CURL_CHUNK_BGN_FUNC_OK; +} + +int main() +{ + /* data for callback */ + struct callback_data callback_info; + + CURL *curl = curl_easy_init(); + + /* callback is called before download of concrete file started */ + curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming); + curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); +} +~~~ + +# AVAILABILITY + +Added in 7.21.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 deleted file mode 100644 index c6bf88e4539..00000000000 --- a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 +++ /dev/null @@ -1,83 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CHUNK_END_FUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CHUNK_END_FUNCTION \- callback after a transfer with FTP wildcard match -.SH SYNOPSIS -.nf -#include - -long chunk_end_callback(void *ptr); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_END_FUNCTION, - chunk_end_callback); -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -This function gets called by libcurl as soon as a part of the stream has been -transferred (or skipped). - -Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or -\fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -#include - -struct callback_data { - FILE *output; -}; - -static long file_is_downloaded(struct callback_data *data) -{ - if(data->output) { - fclose(data->output); - data->output = 0x0; - } - return CURL_CHUNK_END_FUNC_OK; -} - -int main() -{ - /* data for callback */ - struct callback_data callback_info; - - CURL *curl = curl_easy_init(); - - curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded); - curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); -} -.fi -.SH AVAILABILITY -Added in 7.21.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CHUNK_BGN_FUNCTION (3), -.BR CURLOPT_WILDCARDMATCH (3) diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md new file mode 100644 index 00000000000..2d67afe20cf --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md @@ -0,0 +1,82 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CHUNK_END_FUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CHUNK_BGN_FUNCTION (3) + - CURLOPT_WILDCARDMATCH (3) +--- + +# NAME + +CURLOPT_CHUNK_END_FUNCTION - callback after a transfer with FTP wildcard match + +# SYNOPSIS + +~~~c +#include + +long chunk_end_callback(void *ptr); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_END_FUNCTION, + chunk_end_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +This function gets called by libcurl as soon as a part of the stream has been +transferred (or skipped). + +Return *CURL_CHUNK_END_FUNC_OK* if everything is fine or +**CURL_CHUNK_END_FUNC_FAIL** to tell the lib to stop if some error occurred. + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +#include + +struct callback_data { + FILE *output; +}; + +static long file_is_downloaded(struct callback_data *data) +{ + if(data->output) { + fclose(data->output); + data->output = 0x0; + } + return CURL_CHUNK_END_FUNC_OK; +} + +int main() +{ + /* data for callback */ + struct callback_data callback_info; + + CURL *curl = curl_easy_init(); + + curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded); + curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); +} +~~~ + +# AVAILABILITY + +Added in 7.21.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 deleted file mode 100644 index d1f870575ba..00000000000 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CLOSESOCKETDATA 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CLOSESOCKETDATA \- pointer passed to the socket close callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETDATA, - void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP that remains untouched by libcurl and passed as the first -argument in the closesocket callback set with -\fICURLOPT_CLOSESOCKETFUNCTION(3)\fP. -.SH DEFAULT -The default value of this parameter is NULL. -.SH PROTOCOLS -All except file: -.SH EXAMPLE -.nf -struct priv { - void *custom; -}; - -static int closesocket(void *clientp, curl_socket_t item) -{ - struct priv *my = clientp; - printf("our ptr: %p\\n", my->custom); - - printf("libcurl wants to close %d now\\n", (int)item); - return 0; -} - -int main(void) -{ - struct priv myown; - CURL *curl = curl_easy_init(); - - /* call this function to close sockets */ - curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket); - curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &myown); - - curl_easy_perform(curl); - curl_easy_cleanup(curl); -} -.fi -.SH AVAILABILITY -Added in 7.21.7 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CLOSESOCKETFUNCTION (3), -.BR CURLOPT_OPENSOCKETFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md new file mode 100644 index 00000000000..2dd74777b12 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CLOSESOCKETDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CLOSESOCKETFUNCTION (3) + - CURLOPT_OPENSOCKETFUNCTION (3) +--- + +# NAME + +CURLOPT_CLOSESOCKETDATA - pointer passed to the socket close callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETDATA, + void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* that remains untouched by libcurl and passed as the first +argument in the closesocket callback set with +CURLOPT_CLOSESOCKETFUNCTION(3). + +# DEFAULT + +The default value of this parameter is NULL. + +# PROTOCOLS + +All except file: + +# EXAMPLE + +~~~c +struct priv { + void *custom; +}; + +static int closesocket(void *clientp, curl_socket_t item) +{ + struct priv *my = clientp; + printf("our ptr: %p\n", my->custom); + + printf("libcurl wants to close %d now\n", (int)item); + return 0; +} + +int main(void) +{ + struct priv myown; + CURL *curl = curl_easy_init(); + + /* call this function to close sockets */ + curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket); + curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &myown); + + curl_easy_perform(curl); + curl_easy_cleanup(curl); +} +~~~ + +# AVAILABILITY + +Added in 7.21.7 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 deleted file mode 100644 index fb81f696f91..00000000000 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 +++ /dev/null @@ -1,88 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CLOSESOCKETFUNCTION 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CLOSESOCKETFUNCTION \- callback to socket close replacement -.SH SYNOPSIS -.nf -#include - -int closesocket_callback(void *clientp, curl_socket_t item); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETFUNCTION, - closesocket_callback); -.fi -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -This callback function gets called by libcurl instead of the \fIclose(3)\fP or -\fIclosesocket(3)\fP call when sockets are closed (not for any other file -descriptors). This is pretty much the reverse to the -\fICURLOPT_OPENSOCKETFUNCTION(3)\fP option. Return 0 to signal success and 1 -if there was an error. - -The \fIclientp\fP pointer is set with -\fICURLOPT_CLOSESOCKETDATA(3)\fP. \fIitem\fP is the socket libcurl wants to be -closed. -.SH DEFAULT -By default libcurl uses the standard socket close function. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct priv { - void *custom; -}; - -static int closesocket(void *clientp, curl_socket_t item) -{ - struct priv *my = clientp; - printf("our ptr: %p\\n", my->custom); - - printf("libcurl wants to close %d now\\n", (int)item); - return 0; -} - -int main(void) -{ - struct priv myown; - CURL *curl = curl_easy_init(); - - /* call this function to close sockets */ - curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket); - curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &myown); - - curl_easy_perform(curl); - curl_easy_cleanup(curl); -} -.fi -.SH AVAILABILITY -Added in 7.21.7 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CLOSESOCKETDATA (3), -.BR CURLOPT_OPENSOCKETFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md new file mode 100644 index 00000000000..e93e28c1efb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -0,0 +1,86 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CLOSESOCKETFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CLOSESOCKETDATA (3) + - CURLOPT_OPENSOCKETFUNCTION (3) +--- + +# NAME + +CURLOPT_CLOSESOCKETFUNCTION - callback to socket close replacement + +# SYNOPSIS + +~~~c +#include + +int closesocket_callback(void *clientp, curl_socket_t item); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETFUNCTION, + closesocket_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl instead of the *close(3)* or +*closesocket(3)* call when sockets are closed (not for any other file +descriptors). This is pretty much the reverse to the +CURLOPT_OPENSOCKETFUNCTION(3) option. Return 0 to signal success and 1 +if there was an error. + +The *clientp* pointer is set with +CURLOPT_CLOSESOCKETDATA(3). *item* is the socket libcurl wants to be +closed. + +# DEFAULT + +By default libcurl uses the standard socket close function. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct priv { + void *custom; +}; + +static int closesocket(void *clientp, curl_socket_t item) +{ + struct priv *my = clientp; + printf("our ptr: %p\n", my->custom); + + printf("libcurl wants to close %d now\n", (int)item); + return 0; +} + +int main(void) +{ + struct priv myown; + CURL *curl = curl_easy_init(); + + /* call this function to close sockets */ + curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket); + curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &myown); + + curl_easy_perform(curl); + curl_easy_cleanup(curl); +} +~~~ + +# AVAILABILITY + +Added in 7.21.7 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 deleted file mode 100644 index 1d4a2ed548b..00000000000 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 +++ /dev/null @@ -1,91 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CONNECTTIMEOUT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CONNECTTIMEOUT \- timeout for the connect phase -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout); -.fi -.SH DESCRIPTION -Pass a long. It should contain the maximum time in seconds that you allow the -connection phase to the server to take. This timeout only limits the -connection phase, it has no impact once it has connected. Set to zero to -switch to the default built-in connection timeout - 300 seconds. See also the -\fICURLOPT_TIMEOUT(3)\fP option. - -\fICURLOPT_CONNECTTIMEOUT_MS(3)\fP is the same function but set in milliseconds. - -If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP -are set, the value set last is used. - -The "connection phase" is considered complete when the requested TCP, TLS or -QUIC handshakes are done. - -The connection timeout set with \fICURLOPT_CONNECTTIMEOUT(3)\fP is included in -the general all-covering \fICURLOPT_TIMEOUT(3)\fP. - -With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 3 and \fICURLOPT_TIMEOUT(3)\fP set -to 5, the operation can never last longer than 5 seconds, and the connection -phase cannot last longer than 3 seconds. - -With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 4 and \fICURLOPT_TIMEOUT(3)\fP set -to 2, the operation can never last longer than 2 seconds. Including the -connection phase. - -This option may cause libcurl to use the SIGALRM signal to timeout system -calls on builds not using asynch DNS. In unix-like systems, this might cause -signals to be used unless \fICURLOPT_NOSIGNAL(3)\fP is set. -.SH DEFAULT -300 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* complete connection within 10 seconds */ - curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative -value or a value that when converted to milliseconds is too large. -.SH "SEE ALSO" -.BR CURLOPT_CONNECTTIMEOUT_MS (3), -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md new file mode 100644 index 00000000000..07513fdeea2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md @@ -0,0 +1,89 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CONNECTTIMEOUT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT_MS (3) + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_MAX_RECV_SPEED_LARGE (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_CONNECTTIMEOUT - timeout for the connect phase + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout); +~~~ + +# DESCRIPTION + +Pass a long. It should contain the maximum time in seconds that you allow the +connection phase to the server to take. This timeout only limits the +connection phase, it has no impact once it has connected. Set to zero to +switch to the default built-in connection timeout - 300 seconds. See also the +CURLOPT_TIMEOUT(3) option. + +CURLOPT_CONNECTTIMEOUT_MS(3) is the same function but set in milliseconds. + +If both CURLOPT_CONNECTTIMEOUT(3) and CURLOPT_CONNECTTIMEOUT_MS(3) +are set, the value set last is used. + +The "connection phase" is considered complete when the requested TCP, TLS or +QUIC handshakes are done. + +The connection timeout set with CURLOPT_CONNECTTIMEOUT(3) is included in +the general all-covering CURLOPT_TIMEOUT(3). + +With CURLOPT_CONNECTTIMEOUT(3) set to 3 and CURLOPT_TIMEOUT(3) set +to 5, the operation can never last longer than 5 seconds, and the connection +phase cannot last longer than 3 seconds. + +With CURLOPT_CONNECTTIMEOUT(3) set to 4 and CURLOPT_TIMEOUT(3) set +to 2, the operation can never last longer than 2 seconds. Including the +connection phase. + +This option may cause libcurl to use the SIGALRM signal to timeout system +calls on builds not using asynch DNS. In unix-like systems, this might cause +signals to be used unless CURLOPT_NOSIGNAL(3) is set. + +# DEFAULT + +300 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* complete connection within 10 seconds */ + curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative +value or a value that when converted to milliseconds is too large. diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 deleted file mode 100644 index 67c0097ef60..00000000000 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CONNECTTIMEOUT_MS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CONNECTTIMEOUT_MS \- timeout for the connect phase -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS, - long timeout); -.fi -.SH DESCRIPTION -Pass a long. It should contain the maximum time in milliseconds that you allow -the connection phase to the server to take. - -See \fICURLOPT_CONNECTTIMEOUT(3)\fP for details. -.SH DEFAULT -300000 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* complete connection within 10000 milliseconds */ - curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 10000L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_CONNECTTIMEOUT (3), -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md new file mode 100644 index 00000000000..b8508e7de52 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CONNECTTIMEOUT_MS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT (3) + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_CONNECTTIMEOUT_MS - timeout for the connect phase + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS, + long timeout); +~~~ + +# DESCRIPTION + +Pass a long. It should contain the maximum time in milliseconds that you allow +the connection phase to the server to take. + +See CURLOPT_CONNECTTIMEOUT(3) for details. + +# DEFAULT + +300000 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* complete connection within 10000 milliseconds */ + curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 10000L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 deleted file mode 100644 index 014c5f2cfa7..00000000000 --- a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 +++ /dev/null @@ -1,85 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CONNECT_ONLY 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CONNECT_ONLY \- stop when connected to target server -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_ONLY, long only); -.fi -.SH DESCRIPTION -Pass a long. If the parameter equals 1, it tells the library to perform all -the required proxy authentication and connection setup, but no data transfer, -and then return. - -The option can be used to simply test a connection to a server, but is more -useful when used with the \fICURLINFO_ACTIVESOCKET(3)\fP option to -\fIcurl_easy_getinfo(3)\fP as the library can set up the connection and then -the application can obtain the most recently used socket for special data -transfers. - -Since 7.86.0, this option can be set to '2' and if HTTP or WebSocket are used, -libcurl performs the request and reads all response headers before handing -over control to the application. - -Transfers marked connect only do not reuse any existing connections and -connections marked connect only are not allowed to get reused. - -If the connect only transfer is done using the multi interface, the particular -easy handle must remain added to the multi handle for as long as the -application wants to use it. Once it has been removed with -\fIcurl_multi_remove_handle(3)\fP, \fIcurl_easy_send(3)\fP and -\fIcurl_easy_recv(3)\fP do not function. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP, SMTP, POP3 and IMAP. For WS and WSS starting in 7.86.0. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); - ret = curl_easy_perform(curl); - if(ret == CURLE_OK) { - /* only connected! */ - } - } -} -.fi -.SH AVAILABILITY -Added in 7.15.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_recv (3), -.BR curl_easy_send (3), -.BR CURLOPT_HTTPPROXYTUNNEL (3), -.BR CURLOPT_VERBOSE (3) diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md new file mode 100644 index 00000000000..3312936afeb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md @@ -0,0 +1,83 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CONNECT_ONLY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPPROXYTUNNEL (3) + - CURLOPT_VERBOSE (3) + - curl_easy_recv (3) + - curl_easy_send (3) +--- + +# NAME + +CURLOPT_CONNECT_ONLY - stop when connected to target server + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_ONLY, long only); +~~~ + +# DESCRIPTION + +Pass a long. If the parameter equals 1, it tells the library to perform all +the required proxy authentication and connection setup, but no data transfer, +and then return. + +The option can be used to simply test a connection to a server, but is more +useful when used with the CURLINFO_ACTIVESOCKET(3) option to +curl_easy_getinfo(3) as the library can set up the connection and then +the application can obtain the most recently used socket for special data +transfers. + +Since 7.86.0, this option can be set to '2' and if HTTP or WebSocket are used, +libcurl performs the request and reads all response headers before handing +over control to the application. + +Transfers marked connect only do not reuse any existing connections and +connections marked connect only are not allowed to get reused. + +If the connect only transfer is done using the multi interface, the particular +easy handle must remain added to the multi handle for as long as the +application wants to use it. Once it has been removed with +curl_multi_remove_handle(3), curl_easy_send(3) and +curl_easy_recv(3) do not function. + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP, SMTP, POP3 and IMAP. For WS and WSS starting in 7.86.0. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); + ret = curl_easy_perform(curl); + if(ret == CURLE_OK) { + /* only connected! */ + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 b/docs/libcurl/opts/CURLOPT_CONNECT_TO.md similarity index 53% rename from docs/libcurl/opts/CURLOPT_CONNECT_TO.3 rename to docs/libcurl/opts/CURLOPT_CONNECT_TO.md index e0a45031bb7..98d7acc4a37 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 +++ b/docs/libcurl/opts/CURLOPT_CONNECT_TO.md @@ -1,43 +1,36 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CONNECT_TO 3 "10 April 2016" libcurl libcurl -.SH NAME -CURLOPT_CONNECT_TO \- connect to a specific host and port instead of the URL's host and port -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CONNECT_TO +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FOLLOWLOCATION (3) + - CURLOPT_HTTPPROXYTUNNEL (3) + - CURLOPT_RESOLVE (3) + - CURLOPT_URL (3) +--- + +# NAME + +CURLOPT_CONNECT_TO - connect to another host and port instead + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO, struct curl_slist *connect_to); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a linked list of strings with "connect to" information to use for establishing network connections with this handle. The linked list -should be a fully valid list of \fBstruct curl_slist\fP structs properly -filled in. Use \fIcurl_slist_append(3)\fP to create the list and -\fIcurl_slist_free_all(3)\fP to clean up an entire list. +should be a fully valid list of **struct curl_slist** structs properly filled +in. Use curl_slist_append(3) to create the list and curl_slist_free_all(3) to +clean up an entire list. Each single string should be written using the format HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where HOST is the host of the @@ -62,10 +55,9 @@ The "connect to" host and port are only used to establish the network connection. They do NOT affect the host and port that are used for TLS/SSL (e.g. SNI, certificate verification) or for the application protocols. -In contrast to \fICURLOPT_RESOLVE(3)\fP, the option -\fICURLOPT_CONNECT_TO(3)\fP does not pre-populate the DNS cache and therefore -it does not affect future transfers of other easy handles that have been added -to the same multi handle. +In contrast to CURLOPT_RESOLVE(3), the option CURLOPT_CONNECT_TO(3) does not +pre-populate the DNS cache and therefore it does not affect future transfers +of other easy handles that have been added to the same multi handle. The "connect to" host and port are ignored if they are equal to the host and the port in the request URL, because connecting to the host and the port in @@ -77,17 +69,21 @@ port, the HTTP proxy is automatically switched to tunnel mode for this specific request. This is necessary because it is not possible to connect to a specific host or port in normal (non-tunnel) mode. -When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy -the list so you \fBmust\fP keep it around until you no longer use this -\fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on -the list. +When this option is passed to curl_easy_setopt(3), libcurl does not copy the +list so you **must** keep it around until you no longer use this *handle* for +a transfer before you call curl_slist_free_all(3) on the list. + +# DEFAULT -.SH DEFAULT NULL -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl; @@ -107,13 +103,12 @@ int main(void) curl_slist_free_all(connect_to); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.49.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FOLLOWLOCATION (3), -.BR CURLOPT_HTTPPROXYTUNNEL (3), -.BR CURLOPT_RESOLVE (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 deleted file mode 100644 index 2baf5f46f72..00000000000 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 +++ /dev/null @@ -1,111 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CONV_FROM_NETWORK_FUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CONV_FROM_NETWORK_FUNCTION \- convert data from network to host encoding -.SH SYNOPSIS -.nf -#include - -CURLcode conv_callback(char *ptr, size_t length); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_NETWORK_FUNCTION, - conv_callback); -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the -\fBCURL_VERSION_CONV\fP feature bit set if this option is provided. - -The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. -The amount of data to convert is indicated by the \fIlength\fP parameter. The -converted data overlays the input data in the buffer pointed to by the ptr -parameter. \fICURLE_OK\fP must be returned upon successful conversion. A -CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, -should be returned if an error was encountered. - -\fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP converts to host encoding from the -network encoding. It is used when commands or ASCII data are received over -the network. - -If you set a callback pointer to NULL, or do not set it at all, the built-in -libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl -was built, and no callback has been established, the conversion returns the -\fBCURLE_CONV_REQD\fP error code. - -If \fBHAVE_ICONV\fP is defined, \fBCURL_ICONV_CODESET_OF_HOST\fP must also be -defined. For example: - - \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" - -The iconv code in libcurl defaults the network and UTF8 codeset names as -follows: - - \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" - - \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" - -You need to override these definitions if they are different on your system. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP, SMTP, IMAP, POP3 -.SH EXAMPLE -.nf -static CURLcode my_conv_from_ascii_to_ebcdic(char *buffer, size_t length) -{ - int rc = 0; - - /* in-place convert 'buffer' from ASCII to EBCDIC */ - - if(rc == 0) { - /* success */ - return CURLE_OK; - } - else { - return CURLE_CONV_FAILED; - } -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - - /* use platform-specific functions for codeset conversions */ - curl_easy_setopt(curl, CURLOPT_CONV_FROM_NETWORK_FUNCTION, - my_conv_from_ascii_to_ebcdic); -} -.fi -.SH AVAILABILITY -Not available and deprecated since 7.82.0. - -Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was -built. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CONV_FROM_UTF8_FUNCTION (3), -.BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md new file mode 100644 index 00000000000..7460a1e9050 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md @@ -0,0 +1,114 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CONV_FROM_NETWORK_FUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONV_FROM_UTF8_FUNCTION (3) + - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) +--- + +# NAME + +CURLOPT_CONV_FROM_NETWORK_FUNCTION - convert data from network to host encoding + +# SYNOPSIS + +~~~c +#include + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_NETWORK_FUNCTION, + conv_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non-ASCII platforms. curl_version_info(3) returns the +**CURL_VERSION_CONV** feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the *ptr* parameter. +The amount of data to convert is indicated by the *length* parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. *CURLE_OK* must be returned upon successful conversion. A +CURLcode return value defined by curl.h, such as *CURLE_CONV_FAILED*, +should be returned if an error was encountered. + +CURLOPT_CONV_FROM_NETWORK_FUNCTION(3) converts to host encoding from the +network encoding. It is used when commands or ASCII data are received over the +network. + +If you set a callback pointer to NULL, or do not set it at all, the built-in +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +**CURLE_CONV_REQD** error code. + +If **HAVE_ICONV** is defined, **CURL_ICONV_CODESET_OF_HOST** must also be +defined. For example: + +~~~c +#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" +~~~ + +The iconv code in libcurl defaults the network and UTF8 codeset names as +follows: + +~~~ +#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + +#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" +~~~ + +You need to override these definitions if they are different on your system. + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP, SMTP, IMAP, POP3 + +# EXAMPLE + +~~~c +static CURLcode my_conv_from_ascii_to_ebcdic(char *buffer, size_t length) +{ + int rc = 0; + + /* in-place convert 'buffer' from ASCII to EBCDIC */ + + if(rc == 0) { + /* success */ + return CURLE_OK; + } + else { + return CURLE_CONV_FAILED; + } +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + + /* use platform-specific functions for codeset conversions */ + curl_easy_setopt(curl, CURLOPT_CONV_FROM_NETWORK_FUNCTION, + my_conv_from_ascii_to_ebcdic); +} +~~~ + +# AVAILABILITY + +Not available and deprecated since 7.82.0. + +Available only if **CURL_DOES_CONVERSIONS** was defined when libcurl was +built. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 deleted file mode 100644 index e6ab8bf5b90..00000000000 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 +++ /dev/null @@ -1,106 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CONV_FROM_UTF8_FUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CONV_FROM_UTF8_FUNCTION \- convert data from UTF8 to host encoding -.SH SYNOPSIS -.nf -#include - -CURLcode conv_callback(char *ptr, size_t length); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION, - conv_callback); -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the -CURL_VERSION_CONV feature bit set if this option is provided. - -The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. -The amount of data to convert is indicated by the \fIlength\fP parameter. The -converted data overlays the input data in the buffer pointed to by the ptr -parameter. \fICURLE_OK\fP must be returned upon successful conversion. A -CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, -should be returned if an error was encountered. - -\fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP converts to host encoding from UTF8 -encoding. It is required only for SSL processing. - -If you set a callback pointer to NULL, or do not set it at all, the built-in -libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl -was built, and no callback has been established, the conversion returns the -CURLE_CONV_REQD error code. - -If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. -For example: - - \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" - -The iconv code in libcurl defaults the network and UTF8 codeset names as -follows: - - \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" - - \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" - -You need to override these definitions if they are different on your system. -.SH DEFAULT -NULL -.SH PROTOCOLS -TLS-based protocols. -.SH EXAMPLE -.nf -static CURLcode my_conv_from_utf8_to_ebcdic(char *buffer, size_t length) -{ - int rc = 0; - /* in-place convert 'buffer' from UTF-8 to EBCDIC */ - if(rc == 0) { - /* success */ - return CURLE_OK; - } - else { - return CURLE_CONV_FAILED; - } -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION, - my_conv_from_utf8_to_ebcdic); -} -.fi -.SH AVAILABILITY -Not available and deprecated since 7.82.0. - -Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was -built. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), -.BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md new file mode 100644 index 00000000000..1f7d704e9c4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md @@ -0,0 +1,107 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CONV_FROM_UTF8_FUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) + - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) +--- + +# NAME + +CURLOPT_CONV_FROM_UTF8_FUNCTION - convert data from UTF8 to host encoding + +# SYNOPSIS + +~~~c +#include + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION, + conv_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non-ASCII platforms. curl_version_info(3) returns the +CURL_VERSION_CONV feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the *ptr* parameter. +The amount of data to convert is indicated by the *length* parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. *CURLE_OK* must be returned upon successful conversion. A +CURLcode return value defined by curl.h, such as *CURLE_CONV_FAILED*, +should be returned if an error was encountered. + +CURLOPT_CONV_FROM_UTF8_FUNCTION(3) converts to host encoding from UTF8 +encoding. It is required only for SSL processing. + +If you set a callback pointer to NULL, or do not set it at all, the built-in +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +CURLE_CONV_REQD error code. + +If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. +For example: +~~~c + #define CURL_ICONV_CODESET_OF_HOST "IBM-1047" +~~~ + +The iconv code in libcurl defaults the network and UTF8 codeset names as +follows: +~~~c +#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + +#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" +~~~ + +You need to override these definitions if they are different on your system. + +# DEFAULT + +NULL + +# PROTOCOLS + +TLS-based protocols. + +# EXAMPLE + +~~~c +static CURLcode my_conv_from_utf8_to_ebcdic(char *buffer, size_t length) +{ + int rc = 0; + /* in-place convert 'buffer' from UTF-8 to EBCDIC */ + if(rc == 0) { + /* success */ + return CURLE_OK; + } + else { + return CURLE_CONV_FAILED; + } +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION, + my_conv_from_utf8_to_ebcdic); +} +~~~ + +# AVAILABILITY + +Not available and deprecated since 7.82.0. + +Available only if **CURL_DOES_CONVERSIONS** was defined when libcurl was +built. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 deleted file mode 100644 index e2dc7d6064a..00000000000 --- a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 +++ /dev/null @@ -1,108 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CONV_TO_NETWORK_FUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CONV_TO_NETWORK_FUNCTION \- convert data to network from host encoding -.SH SYNOPSIS -.nf -#include - -CURLcode conv_callback(char *ptr, size_t length); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_TO_NETWORK_FUNCTION, - conv_callback); -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the -CURL_VERSION_CONV feature bit set if this option is provided. - -The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. -The amount of data to convert is indicated by the \fIlength\fP parameter. The -converted data overlays the input data in the buffer pointed to by the ptr -parameter. \fICURLE_OK\fP must be returned upon successful conversion. A -CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, -should be returned if an error was encountered. - -\fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP converts from host encoding to the -network encoding. It is used when commands or ASCII data are sent over the -network. - -If you set a callback pointer to NULL, or do not set it at all, the built-in -libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl -was built, and no callback has been established, the conversion returns the -CURLE_CONV_REQD error code. - -If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. -For example: - - \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" - -The iconv code in libcurl defaults the network and UTF8 codeset names as -follows: - - \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" - - \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" - -You need to override these definitions if they are different on your system. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP, SMTP, IMAP, POP3 -.SH EXAMPLE -.nf -static CURLcode my_conv_from_ebcdic_to_ascii(char *buffer, size_t length) -{ - int rc = 0; - /* in-place convert 'buffer' from EBCDIC to ASCII */ - if(rc == 0) { - /* success */ - return CURLE_OK; - } - else { - return CURLE_CONV_FAILED; - } -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - - curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION, - my_conv_from_ebcdic_to_ascii); -} -.fi -.SH AVAILABILITY -Not available and deprecated since 7.82.0. - -Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was -built. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), -.BR CURLOPT_CONV_FROM_UTF8_FUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md new file mode 100644 index 00000000000..13d9da86755 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md @@ -0,0 +1,110 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CONV_TO_NETWORK_FUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) + - CURLOPT_CONV_FROM_UTF8_FUNCTION (3) +--- + +# NAME + +CURLOPT_CONV_TO_NETWORK_FUNCTION - convert data to network from host encoding + +# SYNOPSIS + +~~~c +#include + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_TO_NETWORK_FUNCTION, + conv_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non-ASCII platforms. curl_version_info(3) returns the +CURL_VERSION_CONV feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the *ptr* parameter. +The amount of data to convert is indicated by the *length* parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. *CURLE_OK* must be returned upon successful conversion. A CURLcode +return value defined by curl.h, such as *CURLE_CONV_FAILED*, should be +returned if an error was encountered. + +CURLOPT_CONV_TO_NETWORK_FUNCTION(3) converts from host encoding to the +network encoding. It is used when commands or ASCII data are sent over the +network. + +If you set a callback pointer to NULL, or do not set it at all, the built-in +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +CURLE_CONV_REQD error code. + +If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. +For example: +~~~c +define CURL_ICONV_CODESET_OF_HOST "IBM-1047" +~~~ + +The iconv code in libcurl defaults the network and UTF8 codeset names as +follows: + +~~~c +#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + +#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" +~~~ + +You need to override these definitions if they are different on your system. + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP, SMTP, IMAP, POP3 + +# EXAMPLE + +~~~c +static CURLcode my_conv_from_ebcdic_to_ascii(char *buffer, size_t length) +{ + int rc = 0; + /* in-place convert 'buffer' from EBCDIC to ASCII */ + if(rc == 0) { + /* success */ + return CURLE_OK; + } + else { + return CURLE_CONV_FAILED; + } +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + + curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION, + my_conv_from_ebcdic_to_ascii); +} +~~~ + +# AVAILABILITY + +Not available and deprecated since 7.82.0. + +Available only if **CURL_DOES_CONVERSIONS** was defined when libcurl was +built. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.3 b/docs/libcurl/opts/CURLOPT_COOKIE.md similarity index 52% rename from docs/libcurl/opts/CURLOPT_COOKIE.3 rename to docs/libcurl/opts/CURLOPT_COOKIE.md index 4d24fc21e23..4e2955d8aa4 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIE.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIE.md @@ -1,37 +1,31 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_COOKIE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_COOKIE \- HTTP Cookie header -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_COOKIE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_COOKIELIST (3) + - CURLOPT_COOKIEFILE (3) + - CURLOPT_COOKIEJAR (3) + - CURLOPT_COOKIELIST (3) + - CURLOPT_HTTPHEADER (3) +--- + +# NAME + +CURLOPT_COOKIE - HTTP Cookie header + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIE, char *cookie); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a null-terminated string as parameter. It is used to set one or more cookies in the HTTP request. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie @@ -48,16 +42,16 @@ The cookies set by this option are separate from the internal cookie storage held by the cookie engine and they are not be modified by it. If you enable the cookie engine and either you have imported a cookie of the same name (e.g. 'foo') or the server has set one, it has no effect on the cookies you -set here. A request to the server sends both the 'foo' held by the cookie +set here. A request to the server sends both the 'foo' held by the cookie engine and the 'foo' held by this option. To set a cookie that is instead held by the cookie engine and can be modified by the server use -\fICURLOPT_COOKIELIST(3)\fP. +CURLOPT_COOKIELIST(3). Using this option multiple times makes the last set string override the previous ones. -This option does not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP -or \fICURLOPT_COOKIEJAR(3)\fP to enable parsing and sending cookies +This option does not enable the cookie engine. Use CURLOPT_COOKIEFILE(3) +or CURLOPT_COOKIEJAR(3) to enable parsing and sending cookies automatically. The application does not have to keep the string around after setting this @@ -67,13 +61,19 @@ If libcurl 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 libcurl is *not* built with PSL support, it has no ability to stop super cookies. PSL support is identified by the -\fBCURL_VERSION_PSL\fP feature bit returned by \fIcurl_version_info(3)\fP. -.SH DEFAULT +**CURL_VERSION_PSL** feature bit returned by curl_version_info(3). + +# DEFAULT + NULL, no cookies -.SH PROTOCOLS + +# PROTOCOLS + HTTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -85,15 +85,13 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + If HTTP is enabled -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if HTTP is enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLINFO_COOKIELIST (3), -.BR CURLOPT_COOKIEFILE (3), -.BR CURLOPT_COOKIEJAR (3), -.BR CURLOPT_COOKIELIST (3), -.BR CURLOPT_HTTPHEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 b/docs/libcurl/opts/CURLOPT_COOKIEFILE.md similarity index 57% rename from docs/libcurl/opts/CURLOPT_COOKIEFILE.3 rename to docs/libcurl/opts/CURLOPT_COOKIEFILE.md index e1d5dbd9653..4af473b0912 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.md @@ -1,37 +1,29 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_COOKIEFILE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_COOKIEFILE \- file name to read cookies from -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_COOKIEFILE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_COOKIE (3) + - CURLOPT_COOKIEJAR (3) + - CURLOPT_COOKIESESSION (3) +--- + +# NAME + +CURLOPT_COOKIEFILE - file name to read cookies from + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEFILE, char *filename); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a null-terminated string as parameter. It should point to the file name of your file holding cookie data to read. The cookie data can be in either the old Netscape / Mozilla cookie data format or just regular HTTP @@ -44,8 +36,8 @@ By passing the empty string ("") to this option, you enable the cookie engine without reading any initial cookies. If you tell libcurl the file name is "-" (just a single minus sign), libcurl instead reads from stdin. -This option only \fBreads\fP cookies. To make libcurl write cookies to file, -see \fICURLOPT_COOKIEJAR(3)\fP. +This option only **reads** cookies. To make libcurl write cookies to file, +see CURLOPT_COOKIEJAR(3). If you read cookies from a plain HTTP headers file and it does not specify a domain in the Set-Cookie line, then the cookie is not sent since the cookie @@ -61,17 +53,25 @@ option. Setting this option to NULL (since 7.77.0) explicitly disables the cookie engine and clears the list of files to read cookies from. -.SH SECURITY + +# SECURITY + This document previously mentioned how specifying a non-existing file can also enable the cookie engine. While true, we strongly advise against using that method as it is too hard to be sure that files that stay that way in the long run. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + HTTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -87,15 +87,17 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH "Cookie file format" +~~~ + +# Cookie file format + The cookie file format and general cookie concepts in curl are described online here: https://curl.se/docs/http-cookies.html -.SH AVAILABILITY + +# AVAILABILITY + As long as HTTP is supported -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_COOKIE (3), -.BR CURLOPT_COOKIEJAR (3), -.BR CURLOPT_COOKIESESSION (3) diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 deleted file mode 100644 index f8d75bea435..00000000000 --- a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 +++ /dev/null @@ -1,88 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_COOKIEJAR 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_COOKIEJAR \- file name to store cookies to -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEJAR, char *filename); -.fi -.SH DESCRIPTION -Pass a \fIfilename\fP as a char *, null-terminated. This makes libcurl write -all internally known cookies to the specified file when -\fIcurl_easy_cleanup(3)\fP is called. If no cookies are kept in memory at that -time, no file is created. Specify "-" as filename to instead have the cookies -written to stdout. Using this option also enables cookies for this session, so -if you for example follow a redirect it makes matching cookies get sent -accordingly. - -Note that libcurl does not read any cookies from the cookie jar specified with -this option. To read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP. - -If the cookie jar file cannot be created or written to (when the -\fIcurl_easy_cleanup(3)\fP is called), libcurl does not and cannot report an -error for this. Using \fICURLOPT_VERBOSE(3)\fP or -\fICURLOPT_DEBUGFUNCTION(3)\fP displays a warning, but that is the only -visible feedback you get about this possibly lethal situation. - -Cookies are imported in the Set-Cookie format without a domain name are not -exported by this option. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - /* export cookies to this file when closing the handle */ - curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "/tmp/cookies.txt"); - - res = curl_easy_perform(curl); - - /* close the handle, write the cookies! */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_COOKIE (3), -.BR CURLOPT_COOKIEFILE (3), -.BR CURLOPT_COOKIELIST (3) diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.md b/docs/libcurl/opts/CURLOPT_COOKIEJAR.md new file mode 100644 index 00000000000..504633de91a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.md @@ -0,0 +1,86 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_COOKIEJAR +Section: 3 +Source: libcurl +See-also: + - CURLOPT_COOKIE (3) + - CURLOPT_COOKIEFILE (3) + - CURLOPT_COOKIELIST (3) +--- + +# NAME + +CURLOPT_COOKIEJAR - file name to store cookies to + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEJAR, char *filename); +~~~ + +# DESCRIPTION + +Pass a *filename* as a char *, null-terminated. This makes libcurl write +all internally known cookies to the specified file when +curl_easy_cleanup(3) is called. If no cookies are kept in memory at that +time, no file is created. Specify "-" as filename to instead have the cookies +written to stdout. Using this option also enables cookies for this session, so +if you for example follow a redirect it makes matching cookies get sent +accordingly. + +Note that libcurl does not read any cookies from the cookie jar specified with +this option. To read cookies from a file, use CURLOPT_COOKIEFILE(3). + +If the cookie jar file cannot be created or written to (when the +curl_easy_cleanup(3) is called), libcurl does not and cannot report an +error for this. Using CURLOPT_VERBOSE(3) or +CURLOPT_DEBUGFUNCTION(3) displays a warning, but that is the only +visible feedback you get about this possibly lethal situation. + +Cookies are imported in the Set-Cookie format without a domain name are not +exported by this option. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* export cookies to this file when closing the handle */ + curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "/tmp/cookies.txt"); + + res = curl_easy_perform(curl); + + /* close the handle, write the cookies! */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.md similarity index 60% rename from docs/libcurl/opts/CURLOPT_COOKIELIST.3 rename to docs/libcurl/opts/CURLOPT_COOKIELIST.md index 41862311a13..18a367ab18f 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.md @@ -1,38 +1,32 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_COOKIELIST 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_COOKIELIST \- add to or manipulate cookies held in memory -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_COOKIELIST +Section: 3 +Source: libcurl +See-also: + - CURLINFO_COOKIELIST (3) + - CURLOPT_COOKIE (3) + - CURLOPT_COOKIEFILE (3) + - CURLOPT_COOKIEJAR (3) +--- + +# NAME + +CURLOPT_COOKIELIST - add to or manipulate cookies held in memory + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST, char *cookie); -.SH DESCRIPTION -Pass a char * to a \fIcookie\fP string. +~~~ + +# DESCRIPTION + +Pass a char pointer to a *cookie* string. Such a cookie can be either a single line in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format. This option also enables @@ -52,27 +46,37 @@ much better: use the Netscape file format. Additionally, there are commands available that perform actions if you pass in these exact strings: -.IP ALL + +## ALL + erases all cookies held in memory -.IP SESS +## SESS + erases all session cookies held in memory -.IP FLUSH -writes all known cookies to the file specified by \fICURLOPT_COOKIEJAR(3)\fP +## FLUSH -.IP RELOAD -loads all cookies from the files specified by \fICURLOPT_COOKIEFILE(3)\fP +writes all known cookies to the file specified by CURLOPT_COOKIEJAR(3) + +## RELOAD + +loads all cookies from the files specified by CURLOPT_COOKIEFILE(3) + +# DEFAULT -.SH DEFAULT NULL -.SH PROTOCOLS + +# PROTOCOLS + HTTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c /* an inline import of a cookie in Netscape format. */ -#define SEP "\\t" /* Tab separates the fields */ +#define SEP "\t" /* Tab separates the fields */ int main(void) { @@ -109,23 +113,24 @@ int main(void) curl_easy_cleanup(curl); /* cookies exported to cookies.txt */ } } -.fi -.SH "Cookie file format" +~~~ + +# Cookie file format + The cookie file format and general cookie concepts in curl are described online here: https://curl.se/docs/http-cookies.html -.SH AVAILABILITY -\fBALL\fP was added in 7.14.1 -\fBSESS\fP was added in 7.15.4 +# AVAILABILITY + +**ALL** was added in 7.14.1 + +**SESS** was added in 7.15.4 + +**FLUSH** was added in 7.17.1 + +**RELOAD** was added in 7.39.0 -\fBFLUSH\fP was added in 7.17.1 +# RETURN VALUE -\fBRELOAD\fP was added in 7.39.0 -.SH RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLINFO_COOKIELIST (3), -.BR CURLOPT_COOKIE (3), -.BR CURLOPT_COOKIEFILE (3), -.BR CURLOPT_COOKIEJAR (3) diff --git a/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 b/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 deleted file mode 100644 index b8894d0fe8e..00000000000 --- a/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_COOKIESESSION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_COOKIESESSION \- start a new cookie session -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIESESSION, long init); -.fi -.SH DESCRIPTION -Pass a long set to 1 to mark this as a new cookie "session". It forces libcurl -to ignore all cookies it is about to load that are "session cookies" from the -previous session. By default, libcurl always loads all cookies, independent if -they are session cookies or not. Session cookies are cookies without expiry -date and they are meant to be alive and existing for this "session" only. - -A "session" is usually defined in browser land for as long as you have your -browser up, more or less. libcurl needs the application to use this option to -tell it when a new session starts, otherwise it assumes everything is still in -the same session. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - /* new "session", do not load session cookies */ - curl_easy_setopt(curl, CURLOPT_COOKIESESSION, 1L); - - /* get the (non session) cookies from this file */ - curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt"); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_COOKIE (3), -.BR CURLOPT_COOKIEFILE (3), -.BR CURLOPT_COOKIEJAR (3) diff --git a/docs/libcurl/opts/CURLOPT_COOKIESESSION.md b/docs/libcurl/opts/CURLOPT_COOKIESESSION.md new file mode 100644 index 00000000000..6f49f025c32 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COOKIESESSION.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_COOKIESESSION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_COOKIE (3) + - CURLOPT_COOKIEFILE (3) + - CURLOPT_COOKIEJAR (3) +--- + +# NAME + +CURLOPT_COOKIESESSION - start a new cookie session + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIESESSION, long init); +~~~ + +# DESCRIPTION + +Pass a long set to 1 to mark this as a new cookie "session". It forces libcurl +to ignore all cookies it is about to load that are "session cookies" from the +previous session. By default, libcurl always loads all cookies, independent if +they are session cookies or not. Session cookies are cookies without expiry +date and they are meant to be alive and existing for this "session" only. + +A "session" is usually defined in browser land for as long as you have your +browser up, more or less. libcurl needs the application to use this option to +tell it when a new session starts, otherwise it assumes everything is still in +the same session. + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* new "session", do not load session cookies */ + curl_easy_setopt(curl, CURLOPT_COOKIESESSION, 1L); + + /* get the (non session) cookies from this file */ + curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 deleted file mode 100644 index 447c66833ca..00000000000 --- a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_COPYPOSTFIELDS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_COPYPOSTFIELDS \- have libcurl copy data to POST -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COPYPOSTFIELDS, char *data); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should be the full \fIdata\fP to post in a -HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS(3)\fP option, but -the original data is instead copied by the library, allowing the application -to overwrite the original data after setting this option. - -Because data are copied, care must be taken when using this option in -conjunction with \fICURLOPT_POSTFIELDSIZE(3)\fP or -\fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP: If the size has not been set prior to -\fICURLOPT_COPYPOSTFIELDS(3)\fP, the data is assumed to be a null-terminated -string; else the stored size informs the library about the byte count to -copy. In any case, the size must not be changed after -\fICURLOPT_COPYPOSTFIELDS(3)\fP, unless another \fICURLOPT_POSTFIELDS(3)\fP or -\fICURLOPT_COPYPOSTFIELDS(3)\fP option is issued. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - char local_buffer[1024]="data to send"; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* size of the data to copy from the buffer and send in the request */ - curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); - - /* send data from the local stack */ - curl_easy_setopt(curl, CURLOPT_COPYPOSTFIELDS, local_buffer); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.17.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_MIMEPOST (3), -.BR CURLOPT_POSTFIELDS (3), -.BR CURLOPT_POSTFIELDSIZE (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md new file mode 100644 index 00000000000..911e081811a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_COPYPOSTFIELDS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MIMEPOST (3) + - CURLOPT_POSTFIELDS (3) + - CURLOPT_POSTFIELDSIZE (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_COPYPOSTFIELDS - have libcurl copy data to POST + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COPYPOSTFIELDS, char *data); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should be the full *data* to post in a +HTTP POST operation. It behaves as the CURLOPT_POSTFIELDS(3) option, but the +original data is instead copied by the library, allowing the application to +overwrite the original data after setting this option. + +Because data are copied, care must be taken when using this option in +conjunction with CURLOPT_POSTFIELDSIZE(3) or +CURLOPT_POSTFIELDSIZE_LARGE(3): If the size has not been set prior to +CURLOPT_COPYPOSTFIELDS(3), the data is assumed to be a null-terminated +string; else the stored size informs the library about the byte count to +copy. In any case, the size must not be changed after +CURLOPT_COPYPOSTFIELDS(3), unless another CURLOPT_POSTFIELDS(3) or +CURLOPT_COPYPOSTFIELDS(3) option is issued. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + char local_buffer[1024]="data to send"; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* size of the data to copy from the buffer and send in the request */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); + + /* send data from the local stack */ + curl_easy_setopt(curl, CURLOPT_COPYPOSTFIELDS, local_buffer); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.17.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_CRLF.3 b/docs/libcurl/opts/CURLOPT_CRLF.3 deleted file mode 100644 index b758f2985d4..00000000000 --- a/docs/libcurl/opts/CURLOPT_CRLF.3 +++ /dev/null @@ -1,64 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CRLF 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CRLF \- CRLF conversion -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLF, long conv); -.fi -.SH DESCRIPTION -Pass a long. If the value is set to 1 (one), libcurl converts Unix newlines to -CRLF newlines on transfers. Disable this option again by setting the value to -0 (zero). - -This is a legacy option of questionable use. -.SH DEFAULT -0 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); - curl_easy_setopt(curl, CURLOPT_CRLF, 1L); - ret = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -SMTP since 7.40.0, other protocols since they were introduced -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), -.BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_CRLF.md b/docs/libcurl/opts/CURLOPT_CRLF.md new file mode 100644 index 00000000000..1766c331281 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CRLF.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CRLF +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) + - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) +--- + +# NAME + +CURLOPT_CRLF - CRLF conversion + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLF, long conv); +~~~ + +# DESCRIPTION + +Pass a long. If the value is set to 1 (one), libcurl converts Unix newlines to +CRLF newlines on transfers. Disable this option again by setting the value to +0 (zero). + +This is a legacy option of questionable use. + +# DEFAULT + +0 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); + curl_easy_setopt(curl, CURLOPT_CRLF, 1L); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +SMTP since 7.40.0, other protocols since they were introduced + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.3 b/docs/libcurl/opts/CURLOPT_CRLFILE.3 deleted file mode 100644 index 30a6ad1ad84..00000000000 --- a/docs/libcurl/opts/CURLOPT_CRLFILE.3 +++ /dev/null @@ -1,84 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CRLFILE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CRLFILE \- Certificate Revocation List file -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLFILE, char *file); -.fi -.SH DESCRIPTION -Pass a char * to a null-terminated string naming a \fIfile\fP with the -concatenation of CRL (in PEM format) to use in the certificate validation that -occurs during the SSL exchange. - -When curl is built to use GnuTLS, there is no way to influence the use of CRL -passed to help in the verification process. - -When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and -X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the -elements of the certificate chain if a CRL file is passed. Also note that -\fICURLOPT_CRLFILE(3)\fP implies \fBCURLSSLOPT_NO_PARTIALCHAIN\fP (see -\fICURLOPT_SSL_OPTIONS(3)\fP) since curl 7.71.0 due to an OpenSSL bug. - -This option makes sense only when used in combination with the -\fICURLOPT_SSL_VERIFYPEER(3)\fP option. - -A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the -option. It is returned when the SSL exchange fails because the CRL file cannot -be loaded. A failure in certificate verification due to a revocation -information found in the CRL does not trigger this specific error. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS-based protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_CRLFILE, "/etc/certs/crl.pem"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_CRLFILE (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.md b/docs/libcurl/opts/CURLOPT_CRLFILE.md new file mode 100644 index 00000000000..b800f8ce337 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CRLFILE.md @@ -0,0 +1,82 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CRLFILE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_CRLFILE (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_CRLFILE - Certificate Revocation List file + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLFILE, char *file); +~~~ + +# DESCRIPTION + +Pass a char pointer to a null-terminated string naming a *file* with the +concatenation of CRL (in PEM format) to use in the certificate validation that +occurs during the SSL exchange. + +When curl is built to use GnuTLS, there is no way to influence the use of CRL +passed to help in the verification process. + +When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and +X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the +elements of the certificate chain if a CRL file is passed. Also note that +CURLOPT_CRLFILE(3) implies **CURLSSLOPT_NO_PARTIALCHAIN** (see +CURLOPT_SSL_OPTIONS(3)) since curl 7.71.0 due to an OpenSSL bug. + +This option makes sense only when used in combination with the +CURLOPT_SSL_VERIFYPEER(3) option. + +A specific error code (*CURLE_SSL_CRL_BADFILE*) is defined with the option. It +is returned when the SSL exchange fails because the CRL file cannot be +loaded. A failure in certificate verification due to a revocation information +found in the CRL does not trigger this specific error. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS-based protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_CRLFILE, "/etc/certs/crl.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_CURLU.3 b/docs/libcurl/opts/CURLOPT_CURLU.3 deleted file mode 100644 index 34e9c53b433..00000000000 --- a/docs/libcurl/opts/CURLOPT_CURLU.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CURLU 3 "28 Oct 2018" libcurl libcurl -.SH NAME -CURLOPT_CURLU \- URL in URL handle format -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, CURLU *pointer); -.fi -.SH DESCRIPTION -Pass in a pointer to the \fIURL\fP handle to work with. The parameter should -be a \fICURLU *\fP. Setting \fICURLOPT_CURLU(3)\fP explicitly overrides -\fICURLOPT_URL(3)\fP. - -\fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a -transfer is started. - -libcurl uses this handle and its contents read-only and does not change its -contents. An application can update the contents of the URL handle after a -transfer is done and if the same handle is used in a subsequent request the -updated contents is used. -.SH DEFAULT -The default value of this parameter is NULL. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - CURLU *urlp = curl_url(); - if(curl) { - CURLcode res; - CURLUcode ret; - ret = curl_url_set(urlp, CURLUPART_URL, "https://example.com", 0); - - curl_easy_setopt(curl, CURLOPT_CURLU, urlp); - - res = curl_easy_perform(curl); - - curl_url_cleanup(urlp); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.63.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_url (3), -.BR curl_url_cleanup (3), -.BR curl_url_dup (3), -.BR curl_url_get (3), -.BR curl_url_set (3), -.BR curl_url_strerror (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_CURLU.md b/docs/libcurl/opts/CURLOPT_CURLU.md new file mode 100644 index 00000000000..a3eeb5c9b7d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CURLU.md @@ -0,0 +1,79 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CURLU +Section: 3 +Source: libcurl +See-also: + - CURLOPT_URL (3) + - curl_url (3) + - curl_url_cleanup (3) + - curl_url_dup (3) + - curl_url_get (3) + - curl_url_set (3) + - curl_url_strerror (3) +--- + +# NAME + +CURLOPT_CURLU - URL in URL handle format + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, CURLU *pointer); +~~~ + +# DESCRIPTION + +Pass in a pointer to the *URL* handle to work with. The parameter should be a +*CURLU pointer*. Setting CURLOPT_CURLU(3) explicitly overrides +CURLOPT_URL(3). + +CURLOPT_URL(3) or CURLOPT_CURLU(3) **must** be set before a +transfer is started. + +libcurl uses this handle and its contents read-only and does not change its +contents. An application can update the contents of the URL handle after a +transfer is done and if the same handle is used in a subsequent request the +updated contents is used. + +# DEFAULT + +The default value of this parameter is NULL. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + CURLU *urlp = curl_url(); + if(curl) { + CURLcode res; + CURLUcode ret; + ret = curl_url_set(urlp, CURLUPART_URL, "https://example.com", 0); + + curl_easy_setopt(curl, CURLOPT_CURLU, urlp); + + res = curl_easy_perform(curl); + + curl_url_cleanup(urlp); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.63.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 deleted file mode 100644 index 6a1f0eeeb92..00000000000 --- a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 +++ /dev/null @@ -1,124 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_CUSTOMREQUEST 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_CUSTOMREQUEST \- custom request method -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *method); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. - -When you change the request \fImethod\fP by setting -\fICURLOPT_CUSTOMREQUEST(3)\fP to something, you do not actually change how -libcurl behaves or acts in regards to the particular request method, it only -changes the actual string sent in the request. - -libcurl passes on the verbatim string in its request without any filter or -other safe guards. That includes white space and control characters. - -Restore to the internal default by setting this to NULL. - -This option can be used to specify the request: -.IP HTTP -Instead of GET or HEAD when performing HTTP based requests. This is -particularly useful, for example, for performing an HTTP DELETE request. - -For example: - -When you tell libcurl to do a HEAD request, but then specify a GET though a -custom request libcurl still acts as if it sent a HEAD. To switch to a proper -HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use -\fICURLOPT_POST(3)\fP or \fICURLOPT_POSTFIELDS(3)\fP and to switch to a proper -GET use \fICURLOPT_HTTPGET(3)\fP. - -Many people have wrongly used this option to replace the entire request with -their own, including multiple headers and POST contents. While that might work -in many cases, it might cause libcurl to send invalid requests and it could -possibly confuse the remote server badly. Use \fICURLOPT_POST(3)\fP and -\fICURLOPT_POSTFIELDS(3)\fP to set POST data. Use \fICURLOPT_HTTPHEADER(3)\fP -to replace or extend the set of headers sent by libcurl. Use -\fICURLOPT_HTTP_VERSION(3)\fP to change HTTP version. - -.IP FTP -Instead of LIST and NLST when performing FTP directory listings. -.IP IMAP -Instead of LIST when issuing IMAP based requests. -.IP POP3 -Instead of LIST and RETR when issuing POP3 based requests. - -For example: - -When you tell libcurl to use a custom request it behaves like a LIST or RETR -command was sent where it expects data to be returned by the server. As such -\fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as -\fBDELE\fP and \fBNOOP\fP for example. -.IP SMTP -Instead of a \fBHELP\fP or \fBVRFY\fP when issuing SMTP based requests. - -For example: - -Normally a multi line response is returned which can be used, in conjunction -with \fICURLOPT_MAIL_RCPT(3)\fP, to specify an EXPN request. If the -\fICURLOPT_NOBODY(3)\fP option is specified then the request can be used to -issue \fBNOOP\fP and \fBRSET\fP commands. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP, FTP, IMAP, POP3 and SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - /* DELETE the given path */ - curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE"); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -IMAP is supported since 7.30.0, POP3 since 7.26.0 and SMTP since 7.34.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLINFO_EFFECTIVE_METHOD (3), -.BR CURLOPT_HTTPHEADER (3), -.BR CURLOPT_NOBODY (3), -.BR CURLOPT_REQUEST_TARGET (3) diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md new file mode 100644 index 00000000000..c4d4ec210e9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md @@ -0,0 +1,130 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_CUSTOMREQUEST +Section: 3 +Source: libcurl +See-also: + - CURLINFO_EFFECTIVE_METHOD (3) + - CURLOPT_HTTPHEADER (3) + - CURLOPT_NOBODY (3) + - CURLOPT_REQUEST_TARGET (3) +--- + +# NAME + +CURLOPT_CUSTOMREQUEST - custom request method + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *method); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. + +When changing the request *method* by setting CURLOPT_CUSTOMREQUEST(3), you +do not actually change how libcurl behaves or acts: you only change the actual +string sent in the request. + +libcurl passes on the verbatim string in its request without any filter or +other safe guards. That includes white space and control characters. + +Restore to the internal default by setting this to NULL. + +This option can be used to specify the request: + +## HTTP + +Instead of GET or HEAD when performing HTTP based requests. This is +particularly useful, for example, for performing an HTTP DELETE request. + +For example: + +When you tell libcurl to do a HEAD request, but then specify a GET though a +custom request libcurl still acts as if it sent a HEAD. To switch to a proper +HEAD use CURLOPT_NOBODY(3), to switch to a proper POST use +CURLOPT_POST(3) or CURLOPT_POSTFIELDS(3) and to switch to a proper +GET use CURLOPT_HTTPGET(3). + +Many people have wrongly used this option to replace the entire request with +their own, including multiple headers and POST contents. While that might work +in many cases, it might cause libcurl to send invalid requests and it could +possibly confuse the remote server badly. Use CURLOPT_POST(3) and +CURLOPT_POSTFIELDS(3) to set POST data. Use CURLOPT_HTTPHEADER(3) +to replace or extend the set of headers sent by libcurl. Use +CURLOPT_HTTP_VERSION(3) to change HTTP version. + +## FTP + +Instead of LIST and NLST when performing FTP directory listings. + +## IMAP + +Instead of LIST when issuing IMAP based requests. + +## POP3 + +Instead of LIST and RETR when issuing POP3 based requests. + +For example: + +When you tell libcurl to use a custom request it behaves like a LIST or RETR +command was sent where it expects data to be returned by the server. As such +CURLOPT_NOBODY(3) should be used when specifying commands such as +**DELE** and **NOOP** for example. + +## SMTP + +Instead of a **HELP** or **VRFY** when issuing SMTP based requests. + +For example: + +Normally a multi line response is returned which can be used, in conjunction +with CURLOPT_MAIL_RCPT(3), to specify an EXPN request. If the +CURLOPT_NOBODY(3) option is specified then the request can be used to +issue **NOOP** and **RSET** commands. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP, FTP, IMAP, POP3 and SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* DELETE the given path */ + curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +IMAP is supported since 7.30.0, POP3 since 7.26.0 and SMTP since 7.34.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 b/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 deleted file mode 100644 index 1b569e9831d..00000000000 --- a/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 +++ /dev/null @@ -1,88 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DEBUGDATA 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DEBUGDATA \- pointer passed to the debug callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP to whatever you want passed in to your -\fICURLOPT_DEBUGFUNCTION(3)\fP in the last void * argument. This pointer is -not used by libcurl, it is only passed to the callback. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct data { - void *custom; -}; - -static int my_trace(CURL *handle, curl_infotype type, - char *data, size_t size, - void *clientp) -{ - struct data *mine = clientp; - printf("our ptr: %p\\n", mine->custom); - - /* output debug info */ -} - -int main(void) -{ - CURL *curl; - CURLcode res; - struct data my_tracedata; - - curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace); - - curl_easy_setopt(curl, CURLOPT_DEBUGDATA, &my_tracedata); - - /* the DEBUGFUNCTION has no effect until we enable VERBOSE */ - curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - res = curl_easy_perform(curl); - - /* always cleanup */ - curl_easy_cleanup(curl); - } - return 0; -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.md b/docs/libcurl/opts/CURLOPT_DEBUGDATA.md new file mode 100644 index 00000000000..cac58d99dff --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DEBUGDATA.md @@ -0,0 +1,86 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DEBUGDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_STDERR (3) +--- + +# NAME + +CURLOPT_DEBUGDATA - pointer passed to the debug callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGDATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* to whatever you want passed in to your +CURLOPT_DEBUGFUNCTION(3) in the last void * argument. This pointer is +not used by libcurl, it is only passed to the callback. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct data { + void *custom; +}; + +static int my_trace(CURL *handle, curl_infotype type, + char *data, size_t size, + void *clientp) +{ + struct data *mine = clientp; + printf("our ptr: %p\n", mine->custom); + + /* output debug info */ +} + +int main(void) +{ + CURL *curl; + CURLcode res; + struct data my_tracedata; + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace); + + curl_easy_setopt(curl, CURLOPT_DEBUGDATA, &my_tracedata); + + /* the DEBUGFUNCTION has no effect until we enable VERBOSE */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + res = curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + return 0; +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md similarity index 58% rename from docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md index 78c9e76a337..1acf963ca49 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md @@ -1,32 +1,24 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DEBUGFUNCTION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DEBUGFUNCTION \- debug callback -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DEBUGFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONN_ID (3) + - CURLINFO_XFER_ID (3) + - CURLOPT_DEBUGDATA (3) + - CURLOPT_VERBOSE (3) + - curl_global_trace (3) +--- + +# NAME + +CURLOPT_DEBUGFUNCTION - debug callback + +# SYNOPSIS + +~~~c #include typedef enum { @@ -48,51 +40,72 @@ int debug_callback(CURL *handle, CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGFUNCTION, debug_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. -\fICURLOPT_DEBUGFUNCTION(3)\fP replaces the standard debug function used when -\fICURLOPT_VERBOSE(3)\fP is in effect. This callback receives debug -information, as specified in the \fItype\fP argument. This function must -return 0. The \fIdata\fP pointed to by the char * passed to this function is -not null-terminated, but is exactly of the \fIsize\fP as told by the -\fIsize\fP argument. +CURLOPT_DEBUGFUNCTION(3) replaces the standard debug function used when +CURLOPT_VERBOSE(3) is in effect. This callback receives debug +information, as specified in the *type* argument. This function must +return 0. The *data* pointed to by the char * passed to this function is +not null-terminated, but is exactly of the *size* as told by the +*size* argument. + +The *clientp* argument is the pointer set with CURLOPT_DEBUGDATA(3). + +Available **curl_infotype** values: -The \fIclientp\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP. +## CURLINFO_TEXT -Available \fBcurl_infotype\fP values: -.RS -.IP CURLINFO_TEXT The data is informational text. -.IP CURLINFO_HEADER_IN + +## CURLINFO_HEADER_IN + The data is header (or header-like) data received from the peer. -.IP CURLINFO_HEADER_OUT + +## CURLINFO_HEADER_OUT + The data is header (or header-like) data sent to the peer. -.IP CURLINFO_DATA_IN + +## CURLINFO_DATA_IN + The data is the unprocessed protocol data received from the peer. Even if the data is encoded or compressed, it is not not provided decoded nor decompressed to this callback. If you need the data in decoded and decompressed form, use -\fICURLOPT_WRITEFUNCTION(3)\fP. -.IP CURLINFO_DATA_OUT +CURLOPT_WRITEFUNCTION(3). + +## CURLINFO_DATA_OUT + The data is protocol data sent to the peer. -.IP CURLINFO_SSL_DATA_OUT + +## CURLINFO_SSL_DATA_OUT + The data is SSL/TLS (binary) data sent to the peer. -.IP CURLINFO_SSL_DATA_IN + +## CURLINFO_SSL_DATA_IN + The data is SSL/TLS (binary) data received from the peer. -.RE -WARNING: This callback may be called with the curl \fIhandle\fP set to an +WARNING: This callback may be called with the curl *handle* set to an internal handle. (Added in 8.4.0) -If you need to distinguish your curl \fIhandle\fP from internal handles then -set \fICURLOPT_PRIVATE(3)\fP on your handle. -.SH DEFAULT +If you need to distinguish your curl *handle* from internal handles then +set CURLOPT_PRIVATE(3) on your handle. + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c static void dump(const char *text, FILE *stream, unsigned char *ptr, size_t size) @@ -101,7 +114,7 @@ void dump(const char *text, size_t c; unsigned int width = 0x10; - fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\\n", + fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\n", text, (long)size, (long)size); for(i = 0; i < size; i += width) { @@ -121,7 +134,7 @@ void dump(const char *text, fputc(x, stream); } - fputc('\\n', stream); /* newline */ + fputc('\n', stream); /* newline */ } } @@ -184,7 +197,7 @@ int main(void) res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) - fprintf(stderr, "curl_easy_perform() failed: %s\\n", + fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res)); /* always cleanup */ @@ -192,14 +205,12 @@ int main(void) } return 0; } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Always -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK -.SH "SEE ALSO" -.BR curl_global_trace (3), -.BR CURLINFO_CONN_ID (3), -.BR CURLINFO_XFER_ID (3), -.BR CURLOPT_DEBUGDATA (3), -.BR CURLOPT_VERBOSE (3) diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 deleted file mode 100644 index ef7b24e9638..00000000000 --- a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 +++ /dev/null @@ -1,91 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DEFAULT_PROTOCOL 3 "18 Aug 2015" libcurl libcurl -.SH NAME -CURLOPT_DEFAULT_PROTOCOL \- default protocol to use if the URL is missing a -scheme name -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEFAULT_PROTOCOL, - char *protocol); -.fi -.SH DESCRIPTION -This option tells libcurl to use \fIprotocol\fP if the URL is missing a scheme -name. - -Use one of these protocol (scheme) names: - -dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3, -pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp - -An unknown or unsupported protocol causes error -\fICURLE_UNSUPPORTED_PROTOCOL\fP when libcurl parses a URL without a -scheme. Parsing happens when \fIcurl_easy_perform(3)\fP or -\fIcurl_multi_perform(3)\fP is called. The protocol set supported by libcurl -vary depending on how it was built. Use \fIcurl_version_info(3)\fP if you need -a list of protocol names supported by the build of libcurl that you are using. - -This option does not change the default proxy protocol (http). - -Without this option libcurl would make a guess based on the host, see -\fICURLOPT_URL(3)\fP for details. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL (make a guess based on the host) -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* set a URL without a scheme */ - curl_easy_setopt(curl, CURLOPT_URL, "example.com"); - - /* set the default protocol (scheme) for schemeless URLs */ - curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.45.0 -.SH RETURN VALUE -CURLE_OK if the option is supported. - -CURLE_OUT_OF_MEMORY if there was insufficient heap space. - -CURLE_UNKNOWN_OPTION if the option is not supported. -.SH "SEE ALSO" -.BR CURLINFO_PROTOCOL (3), -.BR CURLINFO_SCHEME (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md new file mode 100644 index 00000000000..88468f718f9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md @@ -0,0 +1,89 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DEFAULT_PROTOCOL +Section: 3 +Source: libcurl +See-also: + - CURLINFO_PROTOCOL (3) + - CURLINFO_SCHEME (3) + - CURLOPT_URL (3) +--- + +# NAME + +CURLOPT_DEFAULT_PROTOCOL - default protocol to use if the URL is missing a +scheme name + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEFAULT_PROTOCOL, + char *protocol); +~~~ + +# DESCRIPTION + +This option tells libcurl to use *protocol* if the URL is missing a scheme +name. + +Use one of these protocol (scheme) names: + +dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3, +pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp + +An unknown or unsupported protocol causes error +*CURLE_UNSUPPORTED_PROTOCOL* when libcurl parses a URL without a +scheme. Parsing happens when curl_easy_perform(3) or +curl_multi_perform(3) is called. The protocol set supported by libcurl +vary depending on how it was built. Use curl_version_info(3) if you need +a list of protocol names supported by the build of libcurl that you are using. + +This option does not change the default proxy protocol (http). + +Without this option libcurl would make a guess based on the host, see +CURLOPT_URL(3) for details. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL (make a guess based on the host) + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* set a URL without a scheme */ + curl_easy_setopt(curl, CURLOPT_URL, "example.com"); + + /* set the default protocol (scheme) for schemeless URLs */ + curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.45.0 + +# RETURN VALUE + +CURLE_OK if the option is supported. + +CURLE_OUT_OF_MEMORY if there was insufficient heap space. + +CURLE_UNKNOWN_OPTION if the option is not supported. diff --git a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 deleted file mode 100644 index 62dac240cef..00000000000 --- a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DIRLISTONLY 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DIRLISTONLY \- ask for names only in a directory listing -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DIRLISTONLY, long listonly); -.fi -.SH DESCRIPTION -For FTP and SFTP based URLs a parameter set to 1 tells the library to list the -names of files in a directory, rather than performing a full directory listing -that would normally include file sizes, dates etc. - -For POP3 a parameter of 1 tells the library to list the email message or -messages on the POP3 server. This can be used to change the default behavior -of libcurl, when combined with a URL that contains a message ID, to perform a -"scan listing" which can then be used to determine the size of an email. - -Note: For FTP this causes a NLST command to be sent to the FTP server. Beware -that some FTP servers list only files in their response to NLST; they might not -include subdirectories and symbolic links. - -Setting this option to 1 also implies a directory listing even if the URL -does not end with a slash, which otherwise is necessary. - -Do not use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it -effectively breaks that feature. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -FTP, SFTP and POP3 -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/"); - - /* list only */ - curl_easy_setopt(curl, CURLOPT_DIRLISTONLY, 1L); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option was known as CURLOPT_FTPLISTONLY up to 7.16.4. POP3 is supported -since 7.21.5. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CUSTOMREQUEST (3), -.BR CURLOPT_WILDCARDMATCH (3) diff --git a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md new file mode 100644 index 00000000000..29635622c8b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DIRLISTONLY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CUSTOMREQUEST (3) + - CURLOPT_WILDCARDMATCH (3) +--- + +# NAME + +CURLOPT_DIRLISTONLY - ask for names only in a directory listing + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DIRLISTONLY, long listonly); +~~~ + +# DESCRIPTION + +For FTP and SFTP based URLs a parameter set to 1 tells the library to list the +names of files in a directory, rather than performing a full directory listing +that would normally include file sizes, dates etc. + +For POP3 a parameter of 1 tells the library to list the email message or +messages on the POP3 server. This can be used to change the default behavior +of libcurl, when combined with a URL that contains a message ID, to perform a +"scan listing" which can then be used to determine the size of an email. + +Note: For FTP this causes a NLST command to be sent to the FTP server. Beware +that some FTP servers list only files in their response to NLST; they might +not include subdirectories and symbolic links. + +Setting this option to 1 also implies a directory listing even if the URL +does not end with a slash, which otherwise is necessary. + +Do not use this option if you also use CURLOPT_WILDCARDMATCH(3) as it +effectively breaks that feature. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +FTP, SFTP and POP3 + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/"); + + /* list only */ + curl_easy_setopt(curl, CURLOPT_DIRLISTONLY, 1L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option was known as CURLOPT_FTPLISTONLY up to 7.16.4. POP3 is supported +since 7.21.5. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 deleted file mode 100644 index 077fbd8db0d..00000000000 --- a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DISALLOW_USERNAME_IN_URL 3 "30 May 2018" libcurl libcurl -.SH NAME -CURLOPT_DISALLOW_USERNAME_IN_URL \- disallow specifying username in the URL -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DISALLOW_USERNAME_IN_URL, - long disallow); -.fi -.SH DESCRIPTION -A long parameter set to 1 tells the library to not allow URLs that include a -username. - -This is the equivalent to the \fICURLU_DISALLOW_USER\fP flag for the -\fIcurl_url_set(3)\fP function. -.SH DEFAULT -0 (disabled) - user names are allowed by default. -.SH PROTOCOLS -Several -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_DISALLOW_USERNAME_IN_URL, 1L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. - -\fIcurl_easy_perform(3)\fP returns CURLE_LOGIN_DENIED if this option is -enabled and a URL containing a username is specified. -.SH "SEE ALSO" -.BR curl_url_set (3), -.BR CURLOPT_PROTOCOLS (3), -.BR CURLOPT_URL (3), -.BR libcurl-security (3) diff --git a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md new file mode 100644 index 00000000000..ddaaace893f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DISALLOW_USERNAME_IN_URL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROTOCOLS (3) + - CURLOPT_URL (3) + - curl_url_set (3) + - libcurl-security (3) +--- + +# NAME + +CURLOPT_DISALLOW_USERNAME_IN_URL - disallow specifying username in the URL + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DISALLOW_USERNAME_IN_URL, + long disallow); +~~~ + +# DESCRIPTION + +A long parameter set to 1 tells the library to not allow URLs that include a +username. + +This is the equivalent to the *CURLU_DISALLOW_USER* flag for the +curl_url_set(3) function. + +# DEFAULT + +0 (disabled) - user names are allowed by default. + +# PROTOCOLS + +Several + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_DISALLOW_USERNAME_IN_URL, 1L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. + +curl_easy_perform(3) returns CURLE_LOGIN_DENIED if this option is +enabled and a URL containing a username is specified. diff --git a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md similarity index 51% rename from docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 rename to docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md index 2cdb3967ade..0199f525aae 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md @@ -1,37 +1,31 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DNS_CACHE_TIMEOUT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DNS_CACHE_TIMEOUT \- life-time for DNS cache entries -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DNS_CACHE_TIMEOUT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT_MS (3) + - CURLOPT_DNS_SERVERS (3) + - CURLOPT_DNS_USE_GLOBAL_CACHE (3) + - CURLOPT_MAXAGE_CONN (3) + - CURLOPT_RESOLVE (3) +--- + +# NAME + +CURLOPT_DNS_CACHE_TIMEOUT - life-time for DNS cache entries + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a long, this sets the timeout in seconds. Name resolve results are kept in memory and used for this number of seconds. Set to zero to completely disable caching, or set to -1 to make the cached entries remain forever. By @@ -44,7 +38,7 @@ period. The name resolve functions of various libc implementations do not re-read name server information unless explicitly told so (for example, by calling -\fIres_init(3)\fP). This may cause libcurl to keep using the older server even +*res_init(3)*). This may cause libcurl to keep using the older server even if DHCP has updated the server info, and this may look like a DNS cache issue to the casual libcurl-app user. @@ -54,12 +48,18 @@ for a small amount of time into the future. Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds 30,000 entries no matter which timeout value is used. -.SH DEFAULT + +# DEFAULT + 60 -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -79,14 +79,12 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Always -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_CONNECTTIMEOUT_MS (3), -.BR CURLOPT_DNS_SERVERS (3), -.BR CURLOPT_DNS_USE_GLOBAL_CACHE (3), -.BR CURLOPT_MAXAGE_CONN (3), -.BR CURLOPT_RESOLVE (3) diff --git a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 deleted file mode 100644 index dfeabb38644..00000000000 --- a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DNS_INTERFACE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DNS_INTERFACE \- interface to speak DNS over -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_INTERFACE, char *ifname); -.fi -.SH DESCRIPTION -Pass a char * as parameter. Set the name of the network interface that the DNS -resolver should bind to. This must be an interface name (not an address). Set -this option to NULL to use the default setting (do not bind to a specific -interface). - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All protocols except file:// - protocols that resolve host names. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_DNS_INTERFACE, "eth0"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.33.0. This option also requires that libcurl was built with a -resolver backend that supports this operation. The c-ares backend is the only -such one. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, -or CURLE_NOT_BUILT_IN if support was disabled at compile-time. -.SH "SEE ALSO" -.BR CURLOPT_DNS_LOCAL_IP4 (3), -.BR CURLOPT_DNS_LOCAL_IP6 (3), -.BR CURLOPT_DNS_SERVERS (3), -.BR CURLOPT_INTERFACE (3) diff --git a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md new file mode 100644 index 00000000000..070bdc5afc2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DNS_INTERFACE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DNS_LOCAL_IP4 (3) + - CURLOPT_DNS_LOCAL_IP6 (3) + - CURLOPT_DNS_SERVERS (3) + - CURLOPT_INTERFACE (3) +--- + +# NAME + +CURLOPT_DNS_INTERFACE - interface to speak DNS over + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_INTERFACE, char *ifname); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter. Set the name of the network interface that +the DNS resolver should bind to. This must be an interface name (not an +address). Set this option to NULL to use the default setting (do not bind to a +specific interface). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All protocols except file:// - protocols that resolve host names. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_DNS_INTERFACE, "eth0"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.33.0. This option also requires that libcurl was built with a +resolver backend that supports this operation. The c-ares backend is the only +such one. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +or CURLE_NOT_BUILT_IN if support was disabled at compile-time. diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 deleted file mode 100644 index 6f8ad2cf8b7..00000000000 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DNS_LOCAL_IP4 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DNS_LOCAL_IP4 \- IPv4 address to bind DNS resolves to -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP4, char *address); -.fi -.SH DESCRIPTION -Set the local IPv4 \fIaddress\fP that the resolver should bind to. The -argument should be of type char * and contain a single numerical IPv4 address -as a string. Set this option to NULL to use the default setting (do not bind -to a specific IP address). - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP4, "192.168.0.14"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option requires that libcurl was built with a resolver backend that -supports this operation. The c-ares backend is the only such one. - -Added in 7.33.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, -CURLE_NOT_BUILT_IN if support was disabled at compile-time, or -CURLE_BAD_FUNCTION_ARGUMENT when given a bad address. -.SH "SEE ALSO" -.BR CURLOPT_DNS_INTERFACE (3), -.BR CURLOPT_DNS_LOCAL_IP6 (3), -.BR CURLOPT_DNS_SERVERS (3) diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md new file mode 100644 index 00000000000..69af83b6b05 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DNS_LOCAL_IP4 +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DNS_INTERFACE (3) + - CURLOPT_DNS_LOCAL_IP6 (3) + - CURLOPT_DNS_SERVERS (3) +--- + +# NAME + +CURLOPT_DNS_LOCAL_IP4 - IPv4 address to bind DNS resolves to + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP4, char *address); +~~~ + +# DESCRIPTION + +Set the local IPv4 *address* that the resolver should bind to. The argument +should be of type char * and contain a single numerical IPv4 address as a +string. Set this option to NULL to use the default setting (do not bind to a +specific IP address). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP4, "192.168.0.14"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option requires that libcurl was built with a resolver backend that +supports this operation. The c-ares backend is the only such one. + +Added in 7.33.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile-time, or +CURLE_BAD_FUNCTION_ARGUMENT when given a bad address. diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 deleted file mode 100644 index 78ffbf95bc3..00000000000 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DNS_LOCAL_IP6 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DNS_LOCAL_IP6 \- IPv6 address to bind DNS resolves to -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP6, char *address); -.fi -.SH DESCRIPTION -Set the local IPv6 \fIaddress\fP that the resolver should bind to. The -argument should be of type char * and contain a single IPv6 address as a -string. Set this option to NULL to use the default setting (do not bind to a -specific IP address). - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP6, "fe80::a9ff:fe46:b619"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option requires that libcurl was built with a resolver backend that -supports this operation. The c-ares backend is the only such one. - -Added in 7.33.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, -CURLE_NOT_BUILT_IN if support was disabled at compile-time, or -CURLE_BAD_FUNCTION_ARGUMENT when given a bad address. -.SH "SEE ALSO" -.BR CURLOPT_DNS_INTERFACE (3), -.BR CURLOPT_DNS_LOCAL_IP4 (3), -.BR CURLOPT_DNS_SERVERS (3) diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md new file mode 100644 index 00000000000..fb04ee899f1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DNS_LOCAL_IP6 +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DNS_INTERFACE (3) + - CURLOPT_DNS_LOCAL_IP4 (3) + - CURLOPT_DNS_SERVERS (3) +--- + +# NAME + +CURLOPT_DNS_LOCAL_IP6 - IPv6 address to bind DNS resolves to + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP6, char *address); +~~~ + +# DESCRIPTION + +Set the local IPv6 *address* that the resolver should bind to. The argument +should be of type char * and contain a single IPv6 address as a string. Set +this option to NULL to use the default setting (do not bind to a specific IP +address). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP6, "fe80::a9ff:fe46:b619"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option requires that libcurl was built with a resolver backend that +supports this operation. The c-ares backend is the only such one. + +Added in 7.33.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile-time, or +CURLE_BAD_FUNCTION_ARGUMENT when given a bad address. diff --git a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 deleted file mode 100644 index c8e160a7d84..00000000000 --- a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DNS_SERVERS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DNS_SERVERS \- DNS servers to use -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SERVERS, char *servers); -.fi -.SH DESCRIPTION -Pass a char * that is the list of DNS servers to be used instead of the system -default. The format of the dns servers option is: - -host[:port][,host[:port]]... - -For example: - -192.168.1.100,192.168.1.101,3.4.5.6 - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL - use system default -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_DNS_SERVERS, - "192.168.1.100:53,192.168.1.101"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option requires that libcurl was built with a resolver backend that -supports this operation. The c-ares backend is the only such one. - -Added in 7.24.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, -CURLE_NOT_BUILT_IN if support was disabled at compile-time, -CURLE_BAD_FUNCTION_ARGUMENT when given an invalid server list, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_DNS_CACHE_TIMEOUT (3), -.BR CURLOPT_DNS_LOCAL_IP4 (3), -.BR CURLOPT_DNS_LOCAL_IP6 (3) diff --git a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md new file mode 100644 index 00000000000..998257c7989 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DNS_SERVERS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DNS_CACHE_TIMEOUT (3) + - CURLOPT_DNS_LOCAL_IP4 (3) + - CURLOPT_DNS_LOCAL_IP6 (3) +--- + +# NAME + +CURLOPT_DNS_SERVERS - DNS servers to use + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SERVERS, char *servers); +~~~ + +# DESCRIPTION + +Pass a char pointer that is the list of DNS servers to be used instead of the +system default. The format of the dns servers option is: + +host[:port][,host[:port]]... + +For example: + +192.168.1.100,192.168.1.101,3.4.5.6 + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL - use system default + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_DNS_SERVERS, + "192.168.1.100:53,192.168.1.101"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option requires that libcurl was built with a resolver backend that +supports this operation. The c-ares backend is the only such one. + +Added in 7.24.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile-time, +CURLE_BAD_FUNCTION_ARGUMENT when given an invalid server list, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 deleted file mode 100644 index cc6934d1d34..00000000000 --- a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DNS_SHUFFLE_ADDRESSES 3 "3 March 2018" libcurl libcurl -.SH NAME -CURLOPT_DNS_SHUFFLE_ADDRESSES \- shuffle IP addresses for hostname -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SHUFFLE_ADDRESSES, long onoff); -.fi -.SH DESCRIPTION -Pass a long set to 1 to enable this option. - -When a name is resolved and more than one IP address is returned, this -function shuffles the order of all returned addresses so that they are used in -a random order. This is similar to the ordering behavior of the legacy -gethostbyname function which is no longer used on most platforms. - -Addresses are not reshuffled if name resolution is completed using the DNS -cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this -option to reduce DNS cache timeout or disable caching entirely if frequent -reshuffling is needed. - -Since the addresses returned are randomly reordered, the order is not in -accordance with RFC 3484 or any other deterministic order that may be -generated by the system's name resolution implementation. This may have -performance impacts and may cause IPv4 to be used before IPv6 or vice versa. -.SH DEFAULT -0 (disabled) -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_DNS_SHUFFLE_ADDRESSES, 1L); - - curl_easy_perform(curl); - - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.60.0 -.SH RETURN VALUE -CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. -.SH "SEE ALSO" -.BR CURLOPT_DNS_CACHE_TIMEOUT (3), -.BR CURLOPT_IPRESOLVE (3) diff --git a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md new file mode 100644 index 00000000000..f15abc9c74b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DNS_SHUFFLE_ADDRESSES +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DNS_CACHE_TIMEOUT (3) + - CURLOPT_IPRESOLVE (3) +--- + +# NAME + +CURLOPT_DNS_SHUFFLE_ADDRESSES - shuffle IP addresses for hostname + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SHUFFLE_ADDRESSES, long onoff); +~~~ + +# DESCRIPTION + +Pass a long set to 1 to enable this option. + +When a name is resolved and more than one IP address is returned, this +function shuffles the order of all returned addresses so that they are used in +a random order. This is similar to the ordering behavior of the legacy +gethostbyname function which is no longer used on most platforms. + +Addresses are not reshuffled if name resolution is completed using the DNS +cache. CURLOPT_DNS_CACHE_TIMEOUT(3) can be used together with this +option to reduce DNS cache timeout or disable caching entirely if frequent +reshuffling is needed. + +Since the addresses returned are randomly reordered, the order is not in +accordance with RFC 3484 or any other deterministic order that may be +generated by the system's name resolution implementation. This may have +performance impacts and may cause IPv4 to be used before IPv6 or vice versa. + +# DEFAULT + +0 (disabled) + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_DNS_SHUFFLE_ADDRESSES, 1L); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.60.0 + +# RETURN VALUE + +CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. diff --git a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 deleted file mode 100644 index 184147b49a3..00000000000 --- a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DNS_USE_GLOBAL_CACHE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_DNS_USE_GLOBAL_CACHE \- global DNS cache -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_USE_GLOBAL_CACHE, - long enable); -.fi -.SH DESCRIPTION -Has no function since 7.62.0. Do not use! - -Pass a long. If the \fIenable\fP value is 1, it tells curl to use a global DNS -cache that survives between easy handle creations and deletions. This is not -thread-safe and this uses a global variable. - -See \fICURLOPT_SHARE(3)\fP and \fIcurl_share_init(3)\fP for the correct way to -share DNS cache between transfers. -.SH DEFAULT -0 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* switch off the use of a global, thread unsafe, cache */ - curl_easy_setopt(curl, CURLOPT_DNS_USE_GLOBAL_CACHE, 0L); - ret = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} - -.fi -.SH AVAILABILITY -Deprecated since 7.11.1. Function removed in 7.62.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_DNS_CACHE_TIMEOUT (3), -.BR CURLOPT_SHARE (3) diff --git a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md new file mode 100644 index 00000000000..dfbc2291686 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DNS_USE_GLOBAL_CACHE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DNS_CACHE_TIMEOUT (3) + - CURLOPT_SHARE (3) +--- + +# NAME + +CURLOPT_DNS_USE_GLOBAL_CACHE - global DNS cache + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_USE_GLOBAL_CACHE, + long enable); +~~~ + +# DESCRIPTION + +Has no function since 7.62.0. Do not use! + +Pass a long. If the *enable* value is 1, it tells curl to use a global DNS +cache that survives between easy handle creations and deletions. This is not +thread-safe and this uses a global variable. + +See CURLOPT_SHARE(3) and curl_share_init(3) for the correct way to +share DNS cache between transfers. + +# DEFAULT + +0 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* switch off the use of a global, thread unsafe, cache */ + curl_easy_setopt(curl, CURLOPT_DNS_USE_GLOBAL_CACHE, 0L); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} + +~~~ + +# AVAILABILITY + +Deprecated since 7.11.1. Function removed in 7.62.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 deleted file mode 100644 index 0bcd87b7164..00000000000 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 +++ /dev/null @@ -1,92 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DOH_SSL_VERIFYHOST 3 "11 Feb 2021" libcurl libcurl -.SH NAME -CURLOPT_DOH_SSL_VERIFYHOST \- verify the host name in the DoH SSL certificate -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYHOST, - long verify); -.fi -.SH DESCRIPTION -Pass a long set to 2L as asking curl to \fIverify\fP the DoH (DNS-over-HTTPS) -server's certificate name fields against the host name. - -This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYHOST(3)\fP and -only affects requests to the DoH server. - -When \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP is 2, the SSL certificate provided by -the DoH server must indicate that the server name is the same as the server -name to which you meant to connect to, or the connection fails. - -Curl considers the DoH server the intended one when the Common Name field or a -Subject Alternate Name field in the certificate matches the host name in the -DoH URL to which you told Curl to connect. - -When the \fIverify\fP value is set to 1L it is treated the same as 2L. However -for consistency with the other \fIVERIFYHOST\fP options we suggest use 2 and -not 1. - -When the \fIverify\fP value is set to 0L, the connection succeeds regardless of -the names used in the certificate. Use that ability with caution! - -See also \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP to verify the digital signature -of the DoH server certificate. -.SH DEFAULT -2 -.SH PROTOCOLS -DoH -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - curl_easy_setopt(curl, CURLOPT_DOH_URL, - "https://cloudflare-dns.com/dns-query"); - - /* Disable host name verification of the DoH server */ - curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYHOST, 0L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.76.0 - -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_DOH_SSL_VERIFYPEER (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md new file mode 100644 index 00000000000..a168b05a83b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md @@ -0,0 +1,90 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DOH_SSL_VERIFYHOST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DOH_SSL_VERIFYPEER (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_DOH_SSL_VERIFYHOST - verify the host name in the DoH SSL certificate + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYHOST, + long verify); +~~~ + +# DESCRIPTION + +Pass a long set to 2L as asking curl to *verify* the DoH (DNS-over-HTTPS) +server's certificate name fields against the host name. + +This option is the DoH equivalent of CURLOPT_SSL_VERIFYHOST(3) and +only affects requests to the DoH server. + +When CURLOPT_DOH_SSL_VERIFYHOST(3) is 2, the SSL certificate provided by +the DoH server must indicate that the server name is the same as the server +name to which you meant to connect to, or the connection fails. + +Curl considers the DoH server the intended one when the Common Name field or a +Subject Alternate Name field in the certificate matches the host name in the +DoH URL to which you told Curl to connect. + +When the *verify* value is set to 1L it is treated the same as 2L. However +for consistency with the other *VERIFYHOST* options we suggest use 2 and +not 1. + +When the *verify* value is set to 0L, the connection succeeds regardless of +the names used in the certificate. Use that ability with caution! + +See also CURLOPT_DOH_SSL_VERIFYPEER(3) to verify the digital signature +of the DoH server certificate. + +# DEFAULT + +2 + +# PROTOCOLS + +DoH + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_DOH_URL, + "https://cloudflare-dns.com/dns-query"); + + /* Disable host name verification of the DoH server */ + curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYHOST, 0L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.76.0 + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 deleted file mode 100644 index d894871d493..00000000000 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 +++ /dev/null @@ -1,105 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DOH_SSL_VERIFYPEER 3 "11 Feb 2021" libcurl libcurl -.SH NAME -CURLOPT_DOH_SSL_VERIFYPEER \- verify the DoH SSL certificate -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYPEER, - long verify); -.fi -.SH DESCRIPTION -Pass a long as parameter set to 1L to enable or 0L to disable. - -This option tells curl to verify the authenticity of the DoH (DNS-over-HTTPS) -server's certificate. A value of 1 means curl verifies; 0 (zero) means it -does not. - -This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYPEER(3)\fP and -only affects requests to the DoH server. - -When negotiating a TLS or SSL connection, the server sends a certificate -indicating its identity. Curl verifies whether the certificate is authentic, -i.e. that you can trust that the server is who the certificate says it is. -This trust is based on a chain of digital signatures, rooted in certification -authority (CA) certificates you supply. curl uses a default bundle of CA -certificates (the path for that is determined at build time) and you can -specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option -or the \fICURLOPT_CAPATH(3)\fP option. - -When \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP is enabled, and the verification -fails to prove that the certificate is authentic, the connection fails. When -the option is zero, the peer certificate verification succeeds regardless. - -Authenticating the certificate is not enough to be sure about the server. You -typically also want to ensure that the server is the server you mean to be -talking to. Use \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP for that. The check -that the host name in the certificate is valid for the host name you are -connecting to is done independently of the -\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP option. - -WARNING: disabling verification of the certificate allows bad guys to -man-in-the-middle the communication without you knowing it. Disabling -verification makes the communication insecure. Just having encryption on a -transfer is not enough as you cannot be sure that you are communicating with -the correct end-point. -.SH DEFAULT -1 -.SH PROTOCOLS -DoH -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - curl_easy_setopt(curl, CURLOPT_DOH_URL, - "https://cloudflare-dns.com/dns-query"); - - /* Disable certificate verification of the DoH server */ - curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYPEER, 0L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.76.0 - -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_CAPATH (3), -.BR CURLOPT_DOH_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md new file mode 100644 index 00000000000..c8935d1c8d8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md @@ -0,0 +1,102 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DOH_SSL_VERIFYPEER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_CAPATH (3) + - CURLOPT_DOH_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_DOH_SSL_VERIFYPEER - verify the DoH SSL certificate + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYPEER, + long verify); +~~~ + +# DESCRIPTION + +Pass a long as parameter set to 1L to enable or 0L to disable. + +This option tells curl to verify the authenticity of the DoH (DNS-over-HTTPS) +server's certificate. A value of 1 means curl verifies; 0 (zero) means it +does not. + +This option is the DoH equivalent of CURLOPT_SSL_VERIFYPEER(3) and +only affects requests to the DoH server. + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. Curl verifies whether the certificate is authentic, +i.e. that you can trust that the server is who the certificate says it is. +This trust is based on a chain of digital signatures, rooted in certification +authority (CA) certificates you supply. curl uses a default bundle of CA +certificates (the path for that is determined at build time) and you can +specify alternate certificates with the CURLOPT_CAINFO(3) option or the +CURLOPT_CAPATH(3) option. + +When CURLOPT_DOH_SSL_VERIFYPEER(3) is enabled, and the verification fails to +prove that the certificate is authentic, the connection fails. When the option +is zero, the peer certificate verification succeeds regardless. + +Authenticating the certificate is not enough to be sure about the server. You +typically also want to ensure that the server is the server you mean to be +talking to. Use CURLOPT_DOH_SSL_VERIFYHOST(3) for that. The check that the +host name in the certificate is valid for the host name you are connecting to +is done independently of the CURLOPT_DOH_SSL_VERIFYPEER(3) option. + +WARNING: disabling verification of the certificate allows bad guys to +man-in-the-middle the communication without you knowing it. Disabling +verification makes the communication insecure. Just having encryption on a +transfer is not enough as you cannot be sure that you are communicating with +the correct end-point. + +# DEFAULT + +1 + +# PROTOCOLS + +DoH + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_DOH_URL, + "https://cloudflare-dns.com/dns-query"); + + /* Disable certificate verification of the DoH server */ + curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYPEER, 0L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.76.0 + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 deleted file mode 100644 index cde868e3693..00000000000 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DOH_SSL_VERIFYSTATUS 3 "11 Feb 2021" libcurl libcurl -.SH NAME -CURLOPT_DOH_SSL_VERIFYSTATUS \- verify the DoH SSL certificate's status -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYSTATUS, - long verify); -.fi -.SH DESCRIPTION -Pass a long as parameter set to 1 to enable or 0 to disable. - -This option determines whether libcurl verifies the status of the DoH -(DNS-over-HTTPS) server cert using the "Certificate Status Request" TLS -extension (aka. OCSP stapling). - -This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYSTATUS(3)\fP and -only affects requests to the DoH server. - -If this option is enabled and the server does not support the TLS extension, -the verification fails. -.SH DEFAULT -0 -.SH PROTOCOLS -DoH -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - curl_easy_setopt(curl, CURLOPT_DOH_URL, - "https://cloudflare-dns.com/dns-query"); - - /* Ask for OCSP stapling when verifying the DoH server */ - curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYSTATUS, 1L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.76.0. This option is currently only supported by the OpenSSL, and -GnuTLS TLS backends. -.SH RETURN VALUE -Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise -returns CURLE_NOT_BUILT_IN. -.SH "SEE ALSO" -.BR CURLOPT_DOH_SSL_VERIFYHOST (3), -.BR CURLOPT_DOH_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYSTATUS (3) diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md new file mode 100644 index 00000000000..19489986ba8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DOH_SSL_VERIFYSTATUS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DOH_SSL_VERIFYHOST (3) + - CURLOPT_DOH_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYSTATUS (3) +--- + +# NAME + +CURLOPT_DOH_SSL_VERIFYSTATUS - verify the DoH SSL certificate's status + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYSTATUS, + long verify); +~~~ + +# DESCRIPTION + +Pass a long as parameter set to 1 to enable or 0 to disable. + +This option determines whether libcurl verifies the status of the DoH +(DNS-over-HTTPS) server cert using the "Certificate Status Request" TLS +extension (aka. OCSP stapling). + +This option is the DoH equivalent of CURLOPT_SSL_VERIFYSTATUS(3) and +only affects requests to the DoH server. + +If this option is enabled and the server does not support the TLS extension, +the verification fails. + +# DEFAULT + +0 + +# PROTOCOLS + +DoH + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_DOH_URL, + "https://cloudflare-dns.com/dns-query"); + + /* Ask for OCSP stapling when verifying the DoH server */ + curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYSTATUS, 1L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.76.0. This option is currently only supported by the OpenSSL, and +GnuTLS TLS backends. + +# RETURN VALUE + +Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. diff --git a/docs/libcurl/opts/CURLOPT_DOH_URL.3 b/docs/libcurl/opts/CURLOPT_DOH_URL.3 deleted file mode 100644 index 35dbed04ab5..00000000000 --- a/docs/libcurl/opts/CURLOPT_DOH_URL.3 +++ /dev/null @@ -1,95 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_DOH_URL 3 "18 Jun 2018" libcurl libcurl -.SH NAME -CURLOPT_DOH_URL \- provide the DNS-over-HTTPS URL -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_URL, char *URL); -.fi -.SH DESCRIPTION -Pass in a pointer to a \fIURL\fP for the DoH server to use for name -resolving. The parameter should be a char * to a null-terminated string which -must be URL-encoded in the following format: "https://host:port/path". It MUST -specify an HTTPS URL. - -libcurl does not validate the syntax or use this variable until the transfer -is issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP still -returns \fICURLE_OK\fP. - -curl sends POST requests to the given DNS-over-HTTPS URL. - -To find the DoH server itself, which might be specified using a name, libcurl -uses the default name lookup function. You can bootstrap that by providing the -address for the DoH server with \fICURLOPT_RESOLVE(3)\fP. - -Disable DoH use again by setting this option to NULL. -.SH "INHERIT OPTIONS" -DoH lookups use SSL and some SSL settings from your transfer are inherited, -like \fICURLOPT_SSL_CTX_FUNCTION(3)\fP. - -The hostname and peer certificate verification settings are not inherited but -can be controlled separately via \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP and -\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP. - -A set \fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback is not inherited. -.SH "KNOWN BUGS" -Even when DoH is set to be used with this option, there are still some name -resolves that are performed without it, using the default name resolver -mechanism. This includes name resolves done for \fICURLOPT_INTERFACE(3)\fP, -\fICURLOPT_FTPPORT(3)\fP, a proxy type set to \fBCURLPROXY_SOCKS4\fP or -\fBCURLPROXY_SOCKS5\fP and probably some more. -.SH DEFAULT -NULL - there is no default DoH URL. If this option is not set, libcurl uses -the default name resolver. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com"); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.62.0 -.SH RETURN VALUE -Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient -heap space. - -Note that \fIcurl_easy_setopt(3)\fP does immediately parse the given string so -when given a bad DoH URL, libcurl might not detect the problem until it later -tries to resolve a name with it. -.SH "SEE ALSO" -.BR CURLOPT_DNS_CACHE_TIMEOUT (3), -.BR CURLOPT_RESOLVE (3), -.BR CURLOPT_VERBOSE (3) diff --git a/docs/libcurl/opts/CURLOPT_DOH_URL.md b/docs/libcurl/opts/CURLOPT_DOH_URL.md new file mode 100644 index 00000000000..a2e46b4c0b6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DOH_URL.md @@ -0,0 +1,96 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_DOH_URL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DNS_CACHE_TIMEOUT (3) + - CURLOPT_RESOLVE (3) + - CURLOPT_VERBOSE (3) +--- + +# NAME + +CURLOPT_DOH_URL - provide the DNS-over-HTTPS URL + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_URL, char *URL); +~~~ + +# DESCRIPTION + +Pass in a pointer to a *URL* for the DoH server to use for name resolving. The +parameter should be a char pointer to a null-terminated string which must be a +valid and correct HTTPS URL. + +libcurl does not validate the syntax or use this variable until the transfer +is issued. Even if you set a crazy value here, curl_easy_setopt(3) still +returns *CURLE_OK*. + +curl sends POST requests to the given DNS-over-HTTPS URL. + +To find the DoH server itself, which might be specified using a name, libcurl +uses the default name lookup function. You can bootstrap that by providing the +address for the DoH server with CURLOPT_RESOLVE(3). + +Disable DoH use again by setting this option to NULL. + +# INHERIT OPTIONS + +DoH lookups use SSL and some SSL settings from your transfer are inherited, +like CURLOPT_SSL_CTX_FUNCTION(3). + +The hostname and peer certificate verification settings are not inherited but +can be controlled separately via CURLOPT_DOH_SSL_VERIFYHOST(3) and +CURLOPT_DOH_SSL_VERIFYPEER(3). + +A set CURLOPT_OPENSOCKETFUNCTION(3) callback is not inherited. + +# KNOWN BUGS + +Even when DoH is set to be used with this option, there are still some name +resolves that are performed without it, using the default name resolver +mechanism. This includes name resolves done for CURLOPT_INTERFACE(3), +CURLOPT_FTPPORT(3), a proxy type set to **CURLPROXY_SOCKS4** or +**CURLPROXY_SOCKS5** and probably some more. + +# DEFAULT + +NULL - there is no default DoH URL. If this option is not set, libcurl uses +the default name resolver. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com"); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.62.0 + +# RETURN VALUE + +Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient +heap space. + +Note that curl_easy_setopt(3) does immediately parse the given string so +when given a bad DoH URL, libcurl might not detect the problem until it later +tries to resolve a name with it. diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 b/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 deleted file mode 100644 index 099acd8c598..00000000000 --- a/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_EGDSOCKET 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_EGDSOCKET \- EGD socket path -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EGDSOCKET, char *path); -.fi -.SH DESCRIPTION -Deprecated option. It serves no purpose anymore. - -Pass a char * to the null-terminated path name to the Entropy Gathering Daemon -socket. It is used to seed the random engine for TLS. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_EGDSOCKET, "/var/egd.socket"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -If built with TLS enabled. Only the OpenSSL backend uses this, and only with -OpenSSL versions before 1.1.0. - -This option was deprecated in 7.84.0. -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_RANDOM_FILE (3) diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md new file mode 100644 index 00000000000..a472f5ea5a8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_EGDSOCKET +Section: 3 +Source: libcurl +See-also: + - CURLOPT_RANDOM_FILE (3) +--- + +# NAME + +CURLOPT_EGDSOCKET - EGD socket path + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EGDSOCKET, char *path); +~~~ + +# DESCRIPTION + +Deprecated option. It serves no purpose anymore. + +Pass a char pointer to the null-terminated path name to the Entropy Gathering +Daemon socket. It is used to seed the random engine for TLS. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_EGDSOCKET, "/var/egd.socket"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +If built with TLS enabled. Only the OpenSSL backend uses this, and only with +OpenSSL versions before 1.1.0. + +This option was deprecated in 7.84.0. + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 deleted file mode 100644 index 76180cba898..00000000000 --- a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 +++ /dev/null @@ -1,103 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ERRORBUFFER 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_ERRORBUFFER \- error buffer for error messages -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf); -.fi -.SH DESCRIPTION -Pass a char * to a buffer that libcurl may use to store human readable error -messages on failures or problems. This may be more helpful than just the -return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer -must be at least \fBCURL_ERROR_SIZE\fP bytes big. - -You must keep the associated buffer available until libcurl no longer needs -it. Failing to do so might cause odd behavior or even crashes. libcurl might -need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same option -again to use a different pointer. - -Do not rely on the contents of the buffer unless an error code was returned. -Since 7.60.0 libcurl initializes the contents of the error buffer to an empty -string before performing the transfer. For earlier versions if an error code -was returned but there was no error detail then the buffer was untouched. - -Consider \fICURLOPT_VERBOSE(3)\fP and \fICURLOPT_DEBUGFUNCTION(3)\fP to better -debug and trace why errors happen. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -#include /* for strlen() */ -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - char errbuf[CURL_ERROR_SIZE]; - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* provide a buffer to store errors in */ - curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, errbuf); - - /* set the error buffer as empty before performing a request */ - errbuf[0] = 0; - - /* perform the request */ - res = curl_easy_perform(curl); - - /* if the request did not complete correctly, show the error - information. if no detailed error information was written to errbuf - show the more generic information from curl_easy_strerror instead. - */ - if(res != CURLE_OK) { - size_t len = strlen(errbuf); - fprintf(stderr, "\\nlibcurl: (%d) ", res); - if(len) - fprintf(stderr, "%s%s", errbuf, - ((errbuf[len - 1] != '\\n') ? "\\n" : "")); - else - fprintf(stderr, "%s\\n", curl_easy_strerror(res)); - } - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR curl_easy_strerror (3), -.BR curl_multi_strerror (3), -.BR curl_share_strerror (3), -.BR curl_url_strerror (3), -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_VERBOSE (3) diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md new file mode 100644 index 00000000000..ed5d361ef88 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md @@ -0,0 +1,101 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ERRORBUFFER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_VERBOSE (3) + - curl_easy_strerror (3) + - curl_multi_strerror (3) + - curl_share_strerror (3) + - curl_url_strerror (3) +--- + +# NAME + +CURLOPT_ERRORBUFFER - error buffer for error messages + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf); +~~~ + +# DESCRIPTION + +Pass a char pointer to a buffer that libcurl may use to store human readable +error messages on failures or problems. This may be more helpful than just the +return code from curl_easy_perform(3) and related functions. The buffer must +be at least **CURL_ERROR_SIZE** bytes big. + +You must keep the associated buffer available until libcurl no longer needs +it. Failing to do so might cause odd behavior or even crashes. libcurl might +need it until you call curl_easy_cleanup(3) or you set the same option +again to use a different pointer. + +Do not rely on the contents of the buffer unless an error code was returned. +Since 7.60.0 libcurl initializes the contents of the error buffer to an empty +string before performing the transfer. For earlier versions if an error code +was returned but there was no error detail then the buffer was untouched. + +Consider CURLOPT_VERBOSE(3) and CURLOPT_DEBUGFUNCTION(3) to better +debug and trace why errors happen. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +#include /* for strlen() */ +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + char errbuf[CURL_ERROR_SIZE]; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* provide a buffer to store errors in */ + curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, errbuf); + + /* set the error buffer as empty before performing a request */ + errbuf[0] = 0; + + /* perform the request */ + res = curl_easy_perform(curl); + + /* if the request did not complete correctly, show the error + information. if no detailed error information was written to errbuf + show the more generic information from curl_easy_strerror instead. + */ + if(res != CURLE_OK) { + size_t len = strlen(errbuf); + fprintf(stderr, "\nlibcurl: (%d) ", res); + if(len) + fprintf(stderr, "%s%s", errbuf, + ((errbuf[len - 1] != '\n') ? "\n" : "")); + else + fprintf(stderr, "%s\n", curl_easy_strerror(res)); + } + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 deleted file mode 100644 index 98709223298..00000000000 --- a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_EXPECT_100_TIMEOUT_MS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_EXPECT_100_TIMEOUT_MS \- timeout for Expect: 100-continue response -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EXPECT_100_TIMEOUT_MS, - long milliseconds); -.SH DESCRIPTION -Pass a long to tell libcurl the number of \fImilliseconds\fP to wait for a -server response with the HTTP status 100 (Continue), 417 (Expectation Failed) -or similar after sending an HTTP request containing an Expect: 100-continue -header. If this times out before a response is received, the request body is -sent anyway. -.SH DEFAULT -1000 milliseconds -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* wait 3 seconds for 100-continue */ - curl_easy_setopt(curl, CURLOPT_EXPECT_100_TIMEOUT_MS, 3000L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.36.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTPPOST (3), -.BR CURLOPT_POST (3) diff --git a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md new file mode 100644 index 00000000000..9458cfc63d5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_EXPECT_100_TIMEOUT_MS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPPOST (3) + - CURLOPT_POST (3) +--- + +# NAME + +CURLOPT_EXPECT_100_TIMEOUT_MS - timeout for Expect: 100-continue response + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EXPECT_100_TIMEOUT_MS, + long milliseconds); +~~~ + +# DESCRIPTION + +Pass a long to tell libcurl the number of *milliseconds* to wait for a +server response with the HTTP status 100 (Continue), 417 (Expectation Failed) +or similar after sending an HTTP request containing an Expect: 100-continue +header. If this times out before a response is received, the request body is +sent anyway. + +# DEFAULT + +1000 milliseconds + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* wait 3 seconds for 100-continue */ + curl_easy_setopt(curl, CURLOPT_EXPECT_100_TIMEOUT_MS, 3000L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.36.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.3 b/docs/libcurl/opts/CURLOPT_FAILONERROR.3 deleted file mode 100644 index 53951712518..00000000000 --- a/docs/libcurl/opts/CURLOPT_FAILONERROR.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FAILONERROR 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FAILONERROR \- request failure on HTTP response >= 400 -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FAILONERROR, long fail); -.fi -.SH DESCRIPTION -A long parameter set to 1 tells the library to fail the request if the HTTP -code returned is equal to or larger than 400. The default action would be to -return the page normally, ignoring that code. - -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). - -You might get some amounts of headers transferred before this situation is -detected, like when a "100-continue" is received as a response to a POST/PUT -and a 401 or 407 is received immediately afterwards. - -When this option is used and an error is detected, it causes the connection to -get closed and \fICURLE_HTTP_RETURNED_ERROR\fP is returned. -.SH DEFAULT -0, do not fail on error -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L); - ret = curl_easy_perform(curl); - if(ret == CURLE_HTTP_RETURNED_ERROR) { - /* an HTTP response error problem */ - } - } -} -.fi -.SH AVAILABILITY -Along with HTTP. -.SH RETURN VALUE -Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_RESPONSE_CODE (3), -.BR CURLOPT_HTTP200ALIASES (3), -.BR CURLOPT_KEEP_SENDING_ON_ERROR (3) diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.md b/docs/libcurl/opts/CURLOPT_FAILONERROR.md new file mode 100644 index 00000000000..7ea5cedc689 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FAILONERROR.md @@ -0,0 +1,74 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FAILONERROR +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RESPONSE_CODE (3) + - CURLOPT_HTTP200ALIASES (3) + - CURLOPT_KEEP_SENDING_ON_ERROR (3) +--- + +# NAME + +CURLOPT_FAILONERROR - request failure on HTTP response >= 400 + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FAILONERROR, long fail); +~~~ + +# DESCRIPTION + +A long parameter set to 1 tells the library to fail the request if the HTTP +code returned is equal to or larger than 400. The default action would be to +return the page normally, ignoring that code. + +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). + +You might get some amounts of headers transferred before this situation is +detected, like when a "100-continue" is received as a response to a POST/PUT +and a 401 or 407 is received immediately afterwards. + +When this option is used and an error is detected, it causes the connection to +get closed and *CURLE_HTTP_RETURNED_ERROR* is returned. + +# DEFAULT + +0, do not fail on error + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L); + ret = curl_easy_perform(curl); + if(ret == CURLE_HTTP_RETURNED_ERROR) { + /* an HTTP response error problem */ + } + } +} +~~~ + +# AVAILABILITY + +Along with HTTP. + +# RETURN VALUE + +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FILETIME.3 b/docs/libcurl/opts/CURLOPT_FILETIME.3 deleted file mode 100644 index 39ce7a25b5e..00000000000 --- a/docs/libcurl/opts/CURLOPT_FILETIME.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FILETIME 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FILETIME \- get the modification time of the remote resource -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FILETIME, long gettime); -.fi -.SH DESCRIPTION -Pass a long. If it is 1, libcurl attempts to get the modification time of the -remote document in this operation. This requires that the remote server sends -the time or replies to a time querying command. The \fIcurl_easy_getinfo(3)\fP -function with the \fICURLINFO_FILETIME(3)\fP argument can be used after a -transfer to extract the received time (if any). -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP(S), FTP(S), SFTP, FILE, SMB(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/path.html"); - /* Ask for filetime */ - curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); - res = curl_easy_perform(curl); - if(CURLE_OK == res) { - long filetime; - res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); - if((CURLE_OK == res) && (filetime >= 0)) { - time_t file_time = (time_t)filetime; - printf("filetime: %s", ctime(&file_time)); - } - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always, for SFTP since 7.49.0 -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR curl_easy_getinfo (3), -.BR CURLINFO_FILETIME (3) diff --git a/docs/libcurl/opts/CURLOPT_FILETIME.md b/docs/libcurl/opts/CURLOPT_FILETIME.md new file mode 100644 index 00000000000..01344910598 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FILETIME.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FILETIME +Section: 3 +Source: libcurl +See-also: + - CURLINFO_FILETIME (3) + - curl_easy_getinfo (3) +--- + +# NAME + +CURLOPT_FILETIME - get the modification time of the remote resource + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FILETIME, long gettime); +~~~ + +# DESCRIPTION + +Pass a long. If it is 1, libcurl attempts to get the modification time of the +remote document in this operation. This requires that the remote server sends +the time or replies to a time querying command. The curl_easy_getinfo(3) +function with the CURLINFO_FILETIME(3) argument can be used after a +transfer to extract the received time (if any). + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP(S), FTP(S), SFTP, FILE, SMB(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/path.html"); + /* Ask for filetime */ + curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); + res = curl_easy_perform(curl); + if(CURLE_OK == res) { + long filetime; + res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); + if((CURLE_OK == res) && (filetime >= 0)) { + time_t file_time = (time_t)filetime; + printf("filetime: %s", ctime(&file_time)); + } + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always, for SFTP since 7.49.0 + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 deleted file mode 100644 index 89ca2d0397b..00000000000 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FNMATCH_DATA 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FNMATCH_DATA \- pointer passed to the fnmatch callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_DATA, - void *pointer); -.SH DESCRIPTION -Pass a pointer that is untouched by libcurl and passed as the ptr argument to -the \fICURLOPT_FNMATCH_FUNCTION(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -extern int string_match(const char *s1, const char *s2); - -struct local_stuff { - void *custom; -}; - -static int my_fnmatch(void *clientp, - const char *pattern, const char *string) -{ - struct local_stuff *my = clientp; - printf("my ptr: %p\\n", my->custom); - - if(string_match(pattern, string)) - return CURL_FNMATCHFUNC_MATCH; - else - return CURL_FNMATCHFUNC_NOMATCH; -} - -int main(void) -{ - struct local_stuff local_data; - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*"); - curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); - curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch); - curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.21.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FNMATCH_FUNCTION (3), -.BR CURLOPT_WILDCARDMATCH (3) diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md new file mode 100644 index 00000000000..48b60723ab6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FNMATCH_DATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FNMATCH_FUNCTION (3) + - CURLOPT_WILDCARDMATCH (3) +--- + +# NAME + +CURLOPT_FNMATCH_DATA - pointer passed to the fnmatch callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_DATA, + void *pointer); +~~~ + +# DESCRIPTION + +Pass a pointer that is untouched by libcurl and passed as the ptr argument to +the CURLOPT_FNMATCH_FUNCTION(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +extern int string_match(const char *s1, const char *s2); + +struct local_stuff { + void *custom; +}; + +static int my_fnmatch(void *clientp, + const char *pattern, const char *string) +{ + struct local_stuff *my = clientp; + printf("my ptr: %p\n", my->custom); + + if(string_match(pattern, string)) + return CURL_FNMATCHFUNC_MATCH; + else + return CURL_FNMATCHFUNC_NOMATCH; +} + +int main(void) +{ + struct local_stuff local_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*"); + curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); + curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch); + curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.21.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 deleted file mode 100644 index 7dc835766c4..00000000000 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 +++ /dev/null @@ -1,89 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FNMATCH_FUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FNMATCH_FUNCTION \- wildcard match callback -.SH SYNOPSIS -.nf -#include - -int fnmatch_callback(void *ptr, - const char *pattern, - const char *string); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_FUNCTION, - fnmatch_callback); -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -This callback is used for wildcard matching. - -Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, -\fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an -error occurred. -.SH DEFAULT -NULL == an internal function for wildcard matching. -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -extern int string_match(const char *s1, const char *s2); - -struct local_stuff { - void *custom; -}; -static int my_fnmatch(void *clientp, - const char *pattern, const char *string) -{ - struct local_stuff *data = clientp; - printf("my pointer: %p\\n", data->custom); - if(string_match(pattern, string)) - return CURL_FNMATCHFUNC_MATCH; - else - return CURL_FNMATCHFUNC_NOMATCH; -} - -int main(void) -{ - struct local_stuff local_data; - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*"); - curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); - curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch); - curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.21.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_FNMATCH_DATA (3), -.BR CURLOPT_WILDCARDMATCH (3) diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md new file mode 100644 index 00000000000..8ed13bfe6c8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md @@ -0,0 +1,88 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FNMATCH_FUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_FNMATCH_DATA (3) + - CURLOPT_WILDCARDMATCH (3) +--- + +# NAME + +CURLOPT_FNMATCH_FUNCTION - wildcard match callback + +# SYNOPSIS + +~~~c +#include + +int fnmatch_callback(void *ptr, + const char *pattern, + const char *string); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_FUNCTION, + fnmatch_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback is used for wildcard matching. + +Return *CURL_FNMATCHFUNC_MATCH* if pattern matches the string, +*CURL_FNMATCHFUNC_NOMATCH* if not or *CURL_FNMATCHFUNC_FAIL* if an +error occurred. + +# DEFAULT + +NULL == an internal function for wildcard matching. + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +extern int string_match(const char *s1, const char *s2); + +struct local_stuff { + void *custom; +}; +static int my_fnmatch(void *clientp, + const char *pattern, const char *string) +{ + struct local_stuff *data = clientp; + printf("my pointer: %p\n", data->custom); + if(string_match(pattern, string)) + return CURL_FNMATCHFUNC_MATCH; + else + return CURL_FNMATCHFUNC_NOMATCH; +} + +int main(void) +{ + struct local_stuff local_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*"); + curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); + curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch); + curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.21.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 deleted file mode 100644 index a78ea330597..00000000000 --- a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 +++ /dev/null @@ -1,93 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FOLLOWLOCATION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FOLLOWLOCATION \- follow HTTP 3xx redirects -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable); -.fi -.SH DESCRIPTION -A long parameter set to 1 tells the library to follow any Location: header -redirects that a HTTP server sends in a 30x response. The Location: header can -specify a relative or an absolute URL to follow. - -libcurl issues another request for the new URL and follows subsequent new -Location: redirects all the way until no more such headers are returned or the -maximum limit is reached. \fICURLOPT_MAXREDIRS(3)\fP is used to limit the -number of redirects libcurl follows. - -libcurl restricts what protocols it automatically follow redirects to. The -accepted target protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP. By -default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects. - -When following a redirect, the specific 30x response code also dictates which -request method libcurl uses in the subsequent request: For 301, 302 and 303 -responses libcurl switches method from POST to GET unless -\fICURLOPT_POSTREDIR(3)\fP instructs libcurl otherwise. All other redirect -response codes make libcurl use the same method again. - -For users who think the existing location following is too naive, too simple -or just lacks features, it is easy to instead implement your own redirect -follow logic with the use of \fIcurl_easy_getinfo(3)\fP's -\fICURLINFO_REDIRECT_URL(3)\fP option instead of using -\fICURLOPT_FOLLOWLOCATION(3)\fP. -.SH NOTE -Since libcurl changes method or not based on the specific HTTP response code, -setting \fICURLOPT_CUSTOMREQUEST(3)\fP while following redirects may change -what libcurl would otherwise do and if not that carefully may even make it -misbehave since \fICURLOPT_CUSTOMREQUEST(3)\fP overrides the method libcurl -would otherwise select internally. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* example.com is redirected, so we tell libcurl to follow redirection */ - curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_REDIRECT_COUNT (3), -.BR CURLINFO_REDIRECT_URL (3), -.BR CURLOPT_POSTREDIR (3), -.BR CURLOPT_PROTOCOLS (3), -.BR CURLOPT_REDIR_PROTOCOLS (3) diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md new file mode 100644 index 00000000000..814f3099622 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md @@ -0,0 +1,93 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FOLLOWLOCATION +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_COUNT (3) + - CURLINFO_REDIRECT_URL (3) + - CURLOPT_POSTREDIR (3) + - CURLOPT_PROTOCOLS (3) + - CURLOPT_REDIR_PROTOCOLS (3) +--- + +# NAME + +CURLOPT_FOLLOWLOCATION - follow HTTP 3xx redirects + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable); +~~~ + +# DESCRIPTION + +A long parameter set to 1 tells the library to follow any Location: header +redirects that a HTTP server sends in a 30x response. The Location: header can +specify a relative or an absolute URL to follow. + +libcurl issues another request for the new URL and follows subsequent new +Location: redirects all the way until no more such headers are returned or the +maximum limit is reached. CURLOPT_MAXREDIRS(3) is used to limit the +number of redirects libcurl follows. + +libcurl restricts what protocols it automatically follow redirects to. The +accepted target protocols are set with CURLOPT_REDIR_PROTOCOLS(3). By +default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects. + +When following a redirect, the specific 30x response code also dictates which +request method libcurl uses in the subsequent request: For 301, 302 and 303 +responses libcurl switches method from POST to GET unless +CURLOPT_POSTREDIR(3) instructs libcurl otherwise. All other redirect +response codes make libcurl use the same method again. + +For users who think the existing location following is too naive, too simple +or just lacks features, it is easy to instead implement your own redirect +follow logic with the use of curl_easy_getinfo(3)'s +CURLINFO_REDIRECT_URL(3) option instead of using +CURLOPT_FOLLOWLOCATION(3). + +# NOTE + +Since libcurl changes method or not based on the specific HTTP response code, +setting CURLOPT_CUSTOMREQUEST(3) while following redirects may change +what libcurl would otherwise do and if not that carefully may even make it +misbehave since CURLOPT_CUSTOMREQUEST(3) overrides the method libcurl +would otherwise select internally. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* example.com is redirected, so we tell libcurl to follow redirection */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 deleted file mode 100644 index 52d800d67b3..00000000000 --- a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FORBID_REUSE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FORBID_REUSE \- make connection get closed at once after use -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FORBID_REUSE, long close); -.fi -.SH DESCRIPTION -Pass a long. Set \fIclose\fP to 1 to make libcurl explicitly close the -connection when done with the transfer. Normally, libcurl keeps all -connections alive when done with one transfer in case a succeeding one follows -that can reuse them. This option should be used with caution and only if you -understand what it does as it can seriously impact performance. - -Set to 0 to have libcurl keep the connection open for possible later reuse -(default behavior). -.SH DEFAULT -0 -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_FORBID_REUSE, 1L); - curl_easy_perform(curl); - - /* this second transfer may not reuse the same connection */ - curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_FRESH_CONNECT (3), -.BR CURLOPT_MAXCONNECTS (3), -.BR CURLOPT_MAXLIFETIME_CONN (3) diff --git a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md new file mode 100644 index 00000000000..0e8a20607c6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FORBID_REUSE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FRESH_CONNECT (3) + - CURLOPT_MAXCONNECTS (3) + - CURLOPT_MAXLIFETIME_CONN (3) +--- + +# NAME + +CURLOPT_FORBID_REUSE - make connection get closed at once after use + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FORBID_REUSE, long close); +~~~ + +# DESCRIPTION + +Pass a long. Set *close* to 1 to make libcurl explicitly close the +connection when done with the transfer. Normally, libcurl keeps all +connections alive when done with one transfer in case a succeeding one follows +that can reuse them. This option should be used with caution and only if you +understand what it does as it can seriously impact performance. + +Set to 0 to have libcurl keep the connection open for possible later reuse +(default behavior). + +# DEFAULT + +0 + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_FORBID_REUSE, 1L); + curl_easy_perform(curl); + + /* this second transfer may not reuse the same connection */ + curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 deleted file mode 100644 index 00e4addf9a6..00000000000 --- a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FRESH_CONNECT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FRESH_CONNECT \- force a new connection to be used -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FRESH_CONNECT, long fresh); -.fi -.SH DESCRIPTION -Pass a long. Set to 1 to make the next transfer use a new (fresh) connection -by force instead of trying to reuse an existing one. This option should be -used with caution and only if you understand what it does as it may impact -performance negatively. - -Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the -connection is closed after use so that it cannot be reused. - -Set \fIfresh\fP to 0 to have libcurl attempt reusing an existing connection -(default behavior). -.SH DEFAULT -0 -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_FRESH_CONNECT, 1L); - /* this transfer must use a new connection, not reuse an existing */ - curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_FORBID_REUSE (3), -.BR CURLOPT_MAXAGE_CONN (3), -.BR CURLOPT_MAXLIFETIME_CONN (3) diff --git a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md new file mode 100644 index 00000000000..ccb85270d8f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FRESH_CONNECT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FORBID_REUSE (3) + - CURLOPT_MAXAGE_CONN (3) + - CURLOPT_MAXLIFETIME_CONN (3) +--- + +# NAME + +CURLOPT_FRESH_CONNECT - force a new connection to be used + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FRESH_CONNECT, long fresh); +~~~ + +# DESCRIPTION + +Pass a long. Set to 1 to make the next transfer use a new (fresh) connection +by force instead of trying to reuse an existing one. This option should be +used with caution and only if you understand what it does as it may impact +performance negatively. + +Related functionality is CURLOPT_FORBID_REUSE(3) which makes sure the +connection is closed after use so that it cannot be reused. + +Set *fresh* to 0 to have libcurl attempt reusing an existing connection +(default behavior). + +# DEFAULT + +0 + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_FRESH_CONNECT, 1L); + /* this transfer must use a new connection, not reuse an existing */ + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.3 b/docs/libcurl/opts/CURLOPT_FTPPORT.md similarity index 58% rename from docs/libcurl/opts/CURLOPT_FTPPORT.3 rename to docs/libcurl/opts/CURLOPT_FTPPORT.md index ad7f2be539b..93a2bfad477 100644 --- a/docs/libcurl/opts/CURLOPT_FTPPORT.3 +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.md @@ -1,37 +1,28 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTPPORT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTPPORT \- make FTP transfer active -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTPPORT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTP_USE_EPRT (3) + - CURLOPT_FTP_USE_EPSV (3) +--- + +# NAME + +CURLOPT_FTPPORT - make FTP transfer active + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPPORT, char *spec); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a null-terminated string as parameter. It specifies that the FTP transfer should be made actively and the given string is used to get the IP address to use for the FTP PORT instruction. @@ -52,17 +43,17 @@ specifier can be in brackets. Examples with specified ports: -.nf +~~~c eth0:0 192.168.1.2:32000-33000 curl.se:32123 [::1]:1234-4567 -.fi +~~~ We strongly advise against specifying the address with a name, as it causes libcurl to do a blocking name resolve call to retrieve the IP address. That -name resolve operation does \fBnot\fP use DNS-over-HTTPS even if -\fICURLOPT_DOH_URL(3)\fP is set. +name resolve operation does **not** use DNS-over-HTTPS even if +CURLOPT_DOH_URL(3) is set. Using anything else than "-" for this option should typically only be done if you have special knowledge and confirmation that it works. @@ -72,12 +63,18 @@ this option to NULL. The application does not have to keep the string around after setting this option. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + FTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -90,12 +87,13 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Port range support was added in 7.19.5 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_FTP_USE_EPRT (3), -.BR CURLOPT_FTP_USE_EPSV (3) diff --git a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 deleted file mode 100644 index 96b6e9d7f80..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTPSSLAUTH 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTPSSLAUTH \- order in which to attempt TLS vs SSL -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPSSLAUTH, long order); -.fi -.SH DESCRIPTION -Pass a long using one of the values from below, to alter how libcurl issues -\&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only -interesting if \fICURLOPT_USE_SSL(3)\fP is also set. - -Possible \fIorder\fP values: -.IP CURLFTPAUTH_DEFAULT -Allow libcurl to decide. -.IP CURLFTPAUTH_SSL -Try "AUTH SSL" first, and only if that fails try "AUTH TLS". -.IP CURLFTPAUTH_TLS -Try "AUTH TLS" first, and only if that fails try "AUTH SSL". -.SH DEFAULT -CURLFTPAUTH_DEFAULT -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); - curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_TRY); - /* funny server, ask for SSL before TLS */ - curl_easy_setopt(curl, CURLOPT_FTPSSLAUTH, (long)CURLFTPAUTH_SSL); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.12.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_USE_SSL (3), -.BR CURLOPT_FTP_SSL_CCC (3) diff --git a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md new file mode 100644 index 00000000000..922d23795b9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTPSSLAUTH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTP_SSL_CCC (3) + - CURLOPT_USE_SSL (3) +--- + +# NAME + +CURLOPT_FTPSSLAUTH - order in which to attempt TLS vs SSL + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPSSLAUTH, long order); +~~~ + +# DESCRIPTION + +Pass a long using one of the values from below, to alter how libcurl issues +&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only +interesting if CURLOPT_USE_SSL(3) is also set. + +Possible *order* values: + +## CURLFTPAUTH_DEFAULT + +Allow libcurl to decide. + +## CURLFTPAUTH_SSL + +Try "AUTH SSL" first, and only if that fails try "AUTH TLS". + +## CURLFTPAUTH_TLS + +Try "AUTH TLS" first, and only if that fails try "AUTH SSL". + +# DEFAULT + +CURLFTPAUTH_DEFAULT + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_TRY); + /* funny server, ask for SSL before TLS */ + curl_easy_setopt(curl, CURLOPT_FTPSSLAUTH, (long)CURLFTPAUTH_SSL); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.12.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 deleted file mode 100644 index 0b0513c5c3c..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_ACCOUNT 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_ACCOUNT \- account info for FTP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ACCOUNT, char *account); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string (or NULL to disable). 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. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); - - curl_easy_setopt(curl, CURLOPT_FTP_ACCOUNT, "human-resources"); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.13.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PASSWORD (3), -.BR CURLOPT_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md new file mode 100644 index 00000000000..f8941953bd9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_ACCOUNT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PASSWORD (3) + - CURLOPT_USERNAME (3) +--- + +# NAME + +CURLOPT_FTP_ACCOUNT - account info for FTP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ACCOUNT, char *account); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string (or NULL to disable). 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. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_FTP_ACCOUNT, "human-resources"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.13.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 deleted file mode 100644 index d89a13ac625..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_ALTERNATIVE_TO_USER 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_ALTERNATIVE_TO_USER \- command to use instead of USER with FTP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ALTERNATIVE_TO_USER, - char *cmd); -.SH DESCRIPTION -Pass a char * as parameter, pointing to a string which is used to authenticate -if the usual FTP "USER user" and "PASS password" negotiation fails. This is -currently only known to be required when connecting to Tumbleweed's Secure -Transport FTPS server using client certificates for authentication. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_FTP_ALTERNATIVE_TO_USER, "two users"); - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.5 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_FTP_ACCOUNT (3), -.BR CURLOPT_FTP_SKIP_PASV_IP (3), -.BR CURLOPT_SERVER_RESPONSE_TIMEOUT (3), -.BR CURLOPT_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md new file mode 100644 index 00000000000..70f451d8426 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_ALTERNATIVE_TO_USER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTP_ACCOUNT (3) + - CURLOPT_FTP_SKIP_PASV_IP (3) + - CURLOPT_SERVER_RESPONSE_TIMEOUT (3) + - CURLOPT_USERNAME (3) +--- + +# NAME + +CURLOPT_FTP_ALTERNATIVE_TO_USER - command to use instead of USER with FTP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ALTERNATIVE_TO_USER, + char *cmd); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, pointing to a string which is used to +authenticate if the usual FTP "USER user" and "PASS password" negotiation +fails. This is currently only known to be required when connecting to +Tumbleweed's Secure Transport FTPS server using client certificates for +authentication. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_FTP_ALTERNATIVE_TO_USER, "two users"); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.5 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 deleted file mode 100644 index 4d4142967ff..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 +++ /dev/null @@ -1,89 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing directories for FTP and SFTP -.SH SYNOPSIS -.nf -#include - -typedef enum { - CURLFTP_CREATE_DIR_NONE, - CURLFTP_CREATE_DIR, - CURLFTP_CREATE_DIR_RETRY -} curl_ftpcreatedir; - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS, - long create); -.SH DESCRIPTION -Pass a long telling libcurl to \fIcreate\fP the dir. If the value is -\fICURLFTP_CREATE_DIR\fP (1), libcurl may create any remote directory that it -fails to "move" into. - -For FTP requests, that means a CWD command fails. CWD being the command that -changes working directory. - -For SFTP requests, libcurl may create the remote directory if it cannot obtain -a handle to the target-location. The creation fails if a file of the same name -as the directory to create already exists or lack of permissions prevents -creation. - -Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to -retry the CWD command again if the subsequent \fBMKD\fP command fails. This is -especially useful if you are doing many simultaneous connections against the -same server and they all have this option enabled, as then CWD may first fail -but then another connection does \fBMKD\fP before this connection and thus -\fBMKD\fP fails but trying CWD works! -.SH DEFAULT -CURLFTP_CREATE_DIR_NONE (0) -.SH PROTOCOLS -FTP and SFTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, - "ftp://example.com/non-existing/new.txt"); - curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, - (long)CURLFTP_CREATE_DIR_RETRY); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.7. SFTP support added in 7.16.3. The retry option was added in -7.19.4. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the -create value is not. -.SH "SEE ALSO" -.BR CURLOPT_FTP_FILEMETHOD (3), -.BR CURLOPT_FTP_USE_EPSV (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md new file mode 100644 index 00000000000..07b6f68fd1e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md @@ -0,0 +1,88 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_CREATE_MISSING_DIRS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTP_FILEMETHOD (3) + - CURLOPT_FTP_USE_EPSV (3) +--- + +# NAME + +CURLOPT_FTP_CREATE_MISSING_DIRS - create missing directories for FTP and SFTP + +# SYNOPSIS + +~~~c +#include + +typedef enum { + CURLFTP_CREATE_DIR_NONE, + CURLFTP_CREATE_DIR, + CURLFTP_CREATE_DIR_RETRY +} curl_ftpcreatedir; + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS, + long create); +~~~ + +# DESCRIPTION + +Pass a long telling libcurl to *create* the dir. If the value is +*CURLFTP_CREATE_DIR* (1), libcurl may create any remote directory that it +fails to "move" into. + +For FTP requests, that means a CWD command fails. CWD being the command that +changes working directory. + +For SFTP requests, libcurl may create the remote directory if it cannot obtain +a handle to the target-location. The creation fails if a file of the same name +as the directory to create already exists or lack of permissions prevents +creation. + +Setting *create* to *CURLFTP_CREATE_DIR_RETRY* (2), tells libcurl to +retry the CWD command again if the subsequent **MKD** command fails. This is +especially useful if you are doing many simultaneous connections against the +same server and they all have this option enabled, as then CWD may first fail +but then another connection does **MKD** before this connection and thus +**MKD** fails but trying CWD works! + +# DEFAULT + +CURLFTP_CREATE_DIR_NONE (0) + +# PROTOCOLS + +FTP and SFTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/non-existing/new.txt"); + curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, + (long)CURLFTP_CREATE_DIR_RETRY); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.7. SFTP support added in 7.16.3. The retry option was added in +7.19.4. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the +create value is not. diff --git a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 deleted file mode 100644 index afd3a00dae0..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_FILEMETHOD 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_FILEMETHOD \- select directory traversing method for FTP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_FILEMETHOD, - long method); -.SH DESCRIPTION -Pass a long telling libcurl which \fImethod\fP to use to reach a file on a -FTP(S) server. - -This option exists because some server implementations are not compliant to -what the standards say should work. - -The argument should be one of the following alternatives: -.IP CURLFTPMETHOD_MULTICWD -libcurl 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 CURLFTPMETHOD_NOCWD -libcurl makes no CWD at all. libcurl does SIZE, RETR, STOR etc and gives a -full path to the server for all these commands. This is the fastest behavior -since it skips having to change directories. -.IP CURLFTPMETHOD_SINGLECWD -libcurl 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'. -.SH DEFAULT -CURLFTPMETHOD_MULTICWD -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/1/2/3/4/new.txt"); - curl_easy_setopt(curl, CURLOPT_FTP_FILEMETHOD, - (long)CURLFTPMETHOD_SINGLECWD); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_DIRLISTONLY (3), -.BR CURLOPT_FTP_SKIP_PASV_IP (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md new file mode 100644 index 00000000000..34b55d659c0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md @@ -0,0 +1,86 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_FILEMETHOD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DIRLISTONLY (3) + - CURLOPT_FTP_SKIP_PASV_IP (3) +--- + +# NAME + +CURLOPT_FTP_FILEMETHOD - select directory traversing method for FTP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_FILEMETHOD, + long method); +~~~ + +# DESCRIPTION + +Pass a long telling libcurl which *method* to use to reach a file on a +FTP(S) server. + +This option exists because some server implementations are not compliant to +what the standards say should work. + +The argument should be one of the following alternatives: + +## CURLFTPMETHOD_MULTICWD + +libcurl 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. + +## CURLFTPMETHOD_NOCWD + +libcurl makes no CWD at all. libcurl does SIZE, RETR, STOR etc and gives a +full path to the server for all these commands. This is the fastest behavior +since it skips having to change directories. + +## CURLFTPMETHOD_SINGLECWD + +libcurl 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'. + +# DEFAULT + +CURLFTPMETHOD_MULTICWD + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/1/2/3/4/new.txt"); + curl_easy_setopt(curl, CURLOPT_FTP_FILEMETHOD, + (long)CURLFTPMETHOD_SINGLECWD); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 deleted file mode 100644 index 9b6453bdce0..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_SKIP_PASV_IP 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_SKIP_PASV_IP \- ignore the IP address in the PASV response -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SKIP_PASV_IP, long skip); -.fi -.SH DESCRIPTION -Pass a long. If \fIskip\fP is set to 1, it instructs libcurl to not use the IP -address the server suggests in its 227-response to libcurl's PASV command when -libcurl connects the data connection. Instead libcurl reuses the same IP -address it already uses for the control connection. It still uses the port -number from the 227-response. - -This option allows libcurl to work around broken server installations or funny -network setups that due to NATs, firewalls or incompetence report the wrong IP -address. Setting this option also reduces the risk for various sorts of client -abuse by malicious servers. - -This option has no effect if PORT, EPRT or EPSV is used instead of PASV. -.SH DEFAULT -1 since 7.74.0, was 0 before then. -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); - - /* please ignore the IP in the PASV response */ - curl_easy_setopt(curl, CURLOPT_FTP_SKIP_PASV_IP, 1L); - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.14.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FTPPORT (3), -.BR CURLOPT_FTP_USE_EPRT (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md new file mode 100644 index 00000000000..bea622ac794 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_SKIP_PASV_IP +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTPPORT (3) + - CURLOPT_FTP_USE_EPRT (3) +--- + +# NAME + +CURLOPT_FTP_SKIP_PASV_IP - ignore the IP address in the PASV response + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SKIP_PASV_IP, long skip); +~~~ + +# DESCRIPTION + +Pass a long. If *skip* is set to 1, it instructs libcurl to not use the IP +address the server suggests in its 227-response to libcurl's PASV command when +libcurl connects the data connection. Instead libcurl reuses the same IP +address it already uses for the control connection. It still uses the port +number from the 227-response. + +This option allows libcurl to work around broken server installations or funny +network setups that due to NATs, firewalls or incompetence report the wrong IP +address. Setting this option also reduces the risk for various sorts of client +abuse by malicious servers. + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. + +# DEFAULT + +1 since 7.74.0, was 0 before then. + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + + /* please ignore the IP in the PASV response */ + curl_easy_setopt(curl, CURLOPT_FTP_SKIP_PASV_IP, 1L); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.14.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 deleted file mode 100644 index a8d39881ca2..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_SSL_CCC 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_SSL_CCC \- switch off SSL again with FTP after auth -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SSL_CCC, - long how); -.fi -.SH DESCRIPTION -If enabled, this option makes libcurl use CCC (Clear Command Channel). It -shuts down the SSL/TLS layer after authenticating. The rest of the control -channel communication remains unencrypted. This allows NAT routers to follow -the FTP transaction. Pass a long using one of the values below -.IP CURLFTPSSL_CCC_NONE -do not attempt to use CCC. -.IP CURLFTPSSL_CCC_PASSIVE -Do not initiate the shutdown, but wait for the server to do it. Do not send a -reply. -.IP CURLFTPSSL_CCC_ACTIVE -Initiate the shutdown and wait for a reply. -.SH DEFAULT -CURLFTPSSL_CCC_NONE -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); - curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_CONTROL); - /* go back to clear-text FTP after authenticating */ - curl_easy_setopt(curl, CURLOPT_FTP_SSL_CCC, (long)CURLFTPSSL_CCC_ACTIVE); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.16.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FTPSSLAUTH (3), -.BR CURLOPT_PROTOCOLS_STR (3), -.BR CURLOPT_USE_SSL (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md new file mode 100644 index 00000000000..71947c36ede --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_SSL_CCC +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTPSSLAUTH (3) + - CURLOPT_PROTOCOLS_STR (3) + - CURLOPT_USE_SSL (3) +--- + +# NAME + +CURLOPT_FTP_SSL_CCC - switch off SSL again with FTP after auth + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SSL_CCC, + long how); +~~~ + +# DESCRIPTION + +If enabled, this option makes libcurl use CCC (Clear Command Channel). It +shuts down the SSL/TLS layer after authenticating. The rest of the control +channel communication remains unencrypted. This allows NAT routers to follow +the FTP transaction. Pass a long using one of the values below + +## CURLFTPSSL_CCC_NONE + +do not attempt to use CCC. + +## CURLFTPSSL_CCC_PASSIVE + +Do not initiate the shutdown, but wait for the server to do it. Do not send a +reply. + +## CURLFTPSSL_CCC_ACTIVE + +Initiate the shutdown and wait for a reply. + +# DEFAULT + +CURLFTPSSL_CCC_NONE + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_CONTROL); + /* go back to clear-text FTP after authenticating */ + curl_easy_setopt(curl, CURLOPT_FTP_SSL_CCC, (long)CURLFTPSSL_CCC_ACTIVE); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.16.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 deleted file mode 100644 index 8731bd6c5bd..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_USE_EPRT 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_USE_EPRT \- use EPRT for FTP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPRT, long enabled); -.fi -.SH DESCRIPTION -Pass a long. If the value is 1, it tells curl to use the EPRT command when -doing active FTP downloads (which is enabled by -\fICURLOPT_FTPPORT(3)\fP). Using EPRT means that libcurl first attempts to use -EPRT before using PORT, but if you pass zero to this option, it avoids using -EPRT, only plain PORT. - -The EPRT command is a slightly newer addition to the FTP protocol than PORT -and is the preferred command to use since it enables IPv6 to be used. Very old -FTP servers might not support it, which is why libcurl has a fallback -mechanism. Sometimes that fallback is not enough and then this option might -come handy. - -If the server is an IPv6 host, this option has no effect as EPRT is necessary -then. -.SH DEFAULT -.SH PROTOCOLS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); - - /* contact us back, aka "active" FTP */ - curl_easy_setopt(curl, CURLOPT_FTPPORT, "-"); - - /* FTP the way the neanderthals did it */ - curl_easy_setopt(curl, CURLOPT_FTP_USE_EPRT, 0L); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.5 -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_FTP_USE_EPSV (3), -.BR CURLOPT_FTPPORT (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md new file mode 100644 index 00000000000..644f51aa9bf --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_USE_EPRT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTPPORT (3) + - CURLOPT_FTP_USE_EPSV (3) +--- + +# NAME + +CURLOPT_FTP_USE_EPRT - use EPRT for FTP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPRT, long enabled); +~~~ + +# DESCRIPTION + +Pass a long. If the value is 1, it tells curl to use the EPRT command when +doing active FTP downloads (which is enabled by +CURLOPT_FTPPORT(3)). Using EPRT means that libcurl first attempts to use +EPRT before using PORT, but if you pass zero to this option, it avoids using +EPRT, only plain PORT. + +The EPRT command is a slightly newer addition to the FTP protocol than PORT +and is the preferred command to use since it enables IPv6 to be used. Old FTP +servers might not support it, which is why libcurl has a fallback mechanism. +Sometimes that fallback is not enough and then this option might come handy. + +If the server is an IPv6 host, this option has no effect as EPRT is necessary +then. + +# DEFAULT + +# PROTOCOLS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + + /* contact us back, aka "active" FTP */ + curl_easy_setopt(curl, CURLOPT_FTPPORT, "-"); + + /* FTP the way the neanderthals did it */ + curl_easy_setopt(curl, CURLOPT_FTP_USE_EPRT, 0L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.5 + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 deleted file mode 100644 index af5d4ace988..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_USE_EPSV 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_USE_EPSV \- use EPSV for FTP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPSV, long epsv); -.fi -.SH DESCRIPTION -Pass \fIepsv\fP as a long. If the value is 1, it tells curl to use the EPSV -command when doing passive FTP downloads (which it does by default). Using -EPSV means that libcurl first attempts to use the EPSV command before using -PASV. If you pass zero to this option, it does not use EPSV, only plain PASV. - -The EPSV command is a slightly newer addition to the FTP protocol than PASV -and is the preferred command to use since it enables IPv6 to be used. Very old -FTP servers might not support it, which is why libcurl has a fallback -mechanism. Sometimes that fallback is not enough and then this option might -come handy. - -If the server is an IPv6 host, this option has no effect. -.SH DEFAULT -1 -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, - "ftp://example.com/old-server/file.txt"); - - /* let's shut off this modern feature */ - curl_easy_setopt(curl, CURLOPT_FTP_USE_EPSV, 0L); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Along with FTP -.SH RETURN VALUE -Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FTP_USE_EPRT (3), -.BR CURLOPT_FTPPORT (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md new file mode 100644 index 00000000000..985ca8ba3c1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_USE_EPSV +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTPPORT (3) + - CURLOPT_FTP_USE_EPRT (3) +--- + +# NAME + +CURLOPT_FTP_USE_EPSV - use EPSV for FTP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPSV, long epsv); +~~~ + +# DESCRIPTION + +Pass *epsv* as a long. If the value is 1, it tells curl to use the EPSV +command when doing passive FTP downloads (which it does by default). Using +EPSV means that libcurl first attempts to use the EPSV command before using +PASV. If you pass zero to this option, it does not use EPSV, only plain PASV. + +The EPSV command is a slightly newer addition to the FTP protocol than PASV +and is the preferred command to use since it enables IPv6 to be used. Old FTP +servers might not support it, which is why libcurl has a fallback mechanism. +Sometimes that fallback is not enough and then this option might come handy. + +If the server is an IPv6 host, this option has no effect. + +# DEFAULT + +1 + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/old-server/file.txt"); + + /* let's shut off this modern feature */ + curl_easy_setopt(curl, CURLOPT_FTP_USE_EPSV, 0L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Along with FTP + +# RETURN VALUE + +Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 deleted file mode 100644 index c4538bda843..00000000000 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_FTP_USE_PRET 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_FTP_USE_PRET \- use PRET for FTP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_PRET, long enable); -.fi -.SH DESCRIPTION -Pass a long. If the value is 1, it tells 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. Has -no effect when using the active FTP transfers mode. -.SH DEFAULT -0 -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, - "ftp://example.com/old-server/file.txt"); - - /* a drftpd server, do it! */ - curl_easy_setopt(curl, CURLOPT_FTP_USE_PRET, 1L); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FTP_USE_EPRT (3), -.BR CURLOPT_FTP_USE_EPSV (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md new file mode 100644 index 00000000000..f81ca4cf08b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_FTP_USE_PRET +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTP_USE_EPRT (3) + - CURLOPT_FTP_USE_EPSV (3) +--- + +# NAME + +CURLOPT_FTP_USE_PRET - use PRET for FTP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_PRET, long enable); +~~~ + +# DESCRIPTION + +Pass a long. If the value is 1, it tells 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. Has +no effect when using the active FTP transfers mode. + +# DEFAULT + +0 + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/old-server/file.txt"); + + /* a drftpd server, do it! */ + curl_easy_setopt(curl, CURLOPT_FTP_USE_PRET, 1L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 deleted file mode 100644 index 2a711b8fac9..00000000000 --- a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_GSSAPI_DELEGATION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_GSSAPI_DELEGATION \- allowed GSS-API delegation -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_GSSAPI_DELEGATION, long level); -.fi -.SH DESCRIPTION -Set the long parameter \fIlevel\fP to \fBCURLGSSAPI_DELEGATION_FLAG\fP to -allow unconditional GSSAPI credential delegation. The delegation is disabled -by default since 7.21.7. Set the parameter to -\fBCURLGSSAPI_DELEGATION_POLICY_FLAG\fP to delegate only if the OK-AS-DELEGATE -flag is set in the service ticket in case this feature is supported by the -GSS-API implementation and the definition of \fIGSS_C_DELEG_POLICY_FLAG\fP was -available at compile-time. -.SH DEFAULT -CURLGSSAPI_DELEGATION_NONE -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* delegate if okayed by policy */ - curl_easy_setopt(curl, CURLOPT_GSSAPI_DELEGATION, - (long)CURLGSSAPI_DELEGATION_POLICY_FLAG); - ret = curl_easy_perform(curl); - } -} -.fi - -.SH AVAILABILITY -Added in 7.22.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTPAUTH (3), -.BR CURLOPT_PROXYAUTH (3) diff --git a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md new file mode 100644 index 00000000000..01c1d50622a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_GSSAPI_DELEGATION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPAUTH (3) + - CURLOPT_PROXYAUTH (3) +--- + +# NAME + +CURLOPT_GSSAPI_DELEGATION - allowed GSS-API delegation + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_GSSAPI_DELEGATION, long level); +~~~ + +# DESCRIPTION + +Set the long parameter *level* to **CURLGSSAPI_DELEGATION_FLAG** to allow +unconditional GSSAPI credential delegation. The delegation is disabled by +default since 7.21.7. Set the parameter to +**CURLGSSAPI_DELEGATION_POLICY_FLAG** to delegate only if the OK-AS-DELEGATE +flag is set in the service ticket in case this feature is supported by the +GSS-API implementation and the definition of *GSS_C_DELEG_POLICY_FLAG* was +available at compile-time. + +# DEFAULT + +CURLGSSAPI_DELEGATION_NONE + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* delegate if okayed by policy */ + curl_easy_setopt(curl, CURLOPT_GSSAPI_DELEGATION, + (long)CURLGSSAPI_DELEGATION_POLICY_FLAG); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.22.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 deleted file mode 100644 index 5e3865f1259..00000000000 --- a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS 3 "1 Feb 2018" libcurl libcurl -.SH NAME -CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS \- head start for IPv6 for happy eyeballs -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, - long timeout); -.fi -.SH DESCRIPTION -Happy eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6 -addresses for dual-stack hosts, preferring IPv6 first for \fItimeout\fP -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 for \fItimeout\fP 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. -.SH DEFAULT -CURL_HET_DEFAULT (currently defined as 200L) -.SH PROTOCOLS -All except FILE -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, 300L); - - curl_easy_perform(curl); - - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.59.0 -.SH RETURN VALUE -Returns CURLE_OK -.SH SEE ALSO -.BR CURLOPT_CONNECTTIMEOUT_MS "(3), " -.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md new file mode 100644 index 00000000000..23299c736d9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT_MS (3) + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS - head start for IPv6 for happy eyeballs + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, + long timeout); +~~~ + +# DESCRIPTION + +Happy eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6 +addresses for dual-stack hosts, preferring IPv6 first for *timeout* +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 for *timeout* 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. + +# DEFAULT + +CURL_HET_DEFAULT (currently defined as 200L) + +# PROTOCOLS + +All except FILE + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, 300L); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.59.0 + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 deleted file mode 100644 index 5c3b079d8ba..00000000000 --- a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HAPROXYPROTOCOL 3 "5 Feb 2018" libcurl libcurl -.SH NAME -CURLOPT_HAPROXYPROTOCOL \- send HAProxy PROXY protocol v1 header -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPROXYPROTOCOL, - long haproxy_protocol); -.fi -.SH DESCRIPTION -A long parameter set to 1 tells the library to send an HAProxy PROXY -protocol v1 header at beginning of the connection. The default action is not to -send this header. - -This option is primarily useful when sending test requests to a service that -expects this header. - -Most applications do not need this option. -.SH DEFAULT -0, do not send any HAProxy PROXY protocol header -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_HAPROXYPROTOCOL, 1L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP. Added in 7.60.0. -.SH RETURN VALUE -Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. -.SH SEE ALSO -.BR CURLOPT_PROXY "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md new file mode 100644 index 00000000000..51eb2656c5f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HAPROXYPROTOCOL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) +--- + +# NAME + +CURLOPT_HAPROXYPROTOCOL - send HAProxy PROXY protocol v1 header + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPROXYPROTOCOL, + long haproxy_protocol); +~~~ + +# DESCRIPTION + +A long parameter set to 1 tells the library to send an HAProxy PROXY +protocol v1 header at beginning of the connection. The default action is not to +send this header. + +This option is primarily useful when sending test requests to a service that +expects this header. + +Most applications do not need this option. + +# DEFAULT + +0, do not send any HAProxy PROXY protocol header + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HAPROXYPROTOCOL, 1L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP. Added in 7.60.0. + +# RETURN VALUE + +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 deleted file mode 100644 index a2c9b2ff4aa..00000000000 --- a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HAPROXY_CLIENT_IP 3 "8 May 2023" libcurl libcurl -.SH NAME -CURLOPT_HAPROXY_CLIENT_IP \- set HAProxy PROXY protocol client IP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPROXY_CLIENT_IP, - char *client_ip); -.fi -.SH DESCRIPTION -When this parameter is set to a valid IPv4 or IPv6 numerical address, the -library sends this address as client address in the HAProxy PROXY protocol v1 -header at beginning of the connection. - -This option is an alternative to \fICURLOPT_HAPROXYPROTOCOL(3)\fP as that one -cannot use a specified address. -.SH DEFAULT -NULL, no HAProxy header is sent -.SH PROTOCOLS -HTTP, HAProxy PROTOCOL -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_HAPROXY_CLIENT_IP, "1.1.1.1"); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP. Added in 8.2.0. -.SH RETURN VALUE -Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. -.SH SEE ALSO -.BR CURLOPT_PROXY "(3), " -.BR CURLOPT_HAPROXYPROTOCOL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md new file mode 100644 index 00000000000..ac0da3a1ccc --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md @@ -0,0 +1,63 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HAPROXY_CLIENT_IP +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HAPROXYPROTOCOL (3) + - CURLOPT_PROXY (3) +--- + +# NAME + +CURLOPT_HAPROXY_CLIENT_IP - set HAProxy PROXY protocol client IP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPROXY_CLIENT_IP, + char *client_ip); +~~~ + +# DESCRIPTION + +When this parameter is set to a valid IPv4 or IPv6 numerical address, the +library sends this address as client address in the HAProxy PROXY protocol v1 +header at beginning of the connection. + +This option is an alternative to CURLOPT_HAPROXYPROTOCOL(3) as that one +cannot use a specified address. + +# DEFAULT + +NULL, no HAProxy header is sent + +# PROTOCOLS + +HTTP, HAProxy PROTOCOL + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HAPROXY_CLIENT_IP, "1.1.1.1"); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP. Added in 8.2.0. + +# RETURN VALUE + +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HEADER.3 b/docs/libcurl/opts/CURLOPT_HEADER.3 deleted file mode 100644 index 193cdf1a530..00000000000 --- a/docs/libcurl/opts/CURLOPT_HEADER.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HEADER 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HEADER \- pass headers to the data stream -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADER, long onoff); -.fi -.SH DESCRIPTION -Pass the long value \fIonoff\fP set to 1 to ask libcurl to include the headers -in the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP). This option is -relevant for protocols that actually have headers or other meta-data (like -HTTP and FTP). - -When asking to get the headers passed to the same callback as the body, it is -not possible to accurately separate them again without detailed knowledge -about the protocol in use. - -Further: the \fICURLOPT_WRITEFUNCTION(3)\fP callback is limited to only ever -get a maximum of \fICURL_MAX_WRITE_SIZE\fP bytes passed to it (16KB), while a -header can be longer and the \fICURLOPT_HEADERFUNCTION(3)\fP supports getting -called with headers up to \fICURL_MAX_HTTP_HEADER\fP bytes big (100KB). - -It is often better to use \fICURLOPT_HEADERFUNCTION(3)\fP to get the header -data separately. - -While named confusingly similar, \fICURLOPT_HTTPHEADER(3)\fP is used to set -custom HTTP headers! -.SH DEFAULT -0 -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - curl_easy_setopt(curl, CURLOPT_HEADER, 1L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Provided in all libcurl versions. -.SH RETURN VALUE -Returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_HEADERFUNCTION (3), -.BR CURLOPT_HTTPHEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_HEADER.md b/docs/libcurl/opts/CURLOPT_HEADER.md new file mode 100644 index 00000000000..d5e272ac548 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HEADER.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HEADER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADERFUNCTION (3) + - CURLOPT_HTTPHEADER (3) +--- + +# NAME + +CURLOPT_HEADER - pass headers to the data stream + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADER, long onoff); +~~~ + +# DESCRIPTION + +Pass the long value *onoff* set to 1 to ask libcurl to include the headers +in the write callback (CURLOPT_WRITEFUNCTION(3)). This option is +relevant for protocols that actually have headers or other meta-data (like +HTTP and FTP). + +When asking to get the headers passed to the same callback as the body, it is +not possible to accurately separate them again without detailed knowledge +about the protocol in use. + +Further: the CURLOPT_WRITEFUNCTION(3) callback is limited to only ever +get a maximum of *CURL_MAX_WRITE_SIZE* bytes passed to it (16KB), while a +header can be longer and the CURLOPT_HEADERFUNCTION(3) supports getting +called with headers up to *CURL_MAX_HTTP_HEADER* bytes big (100KB). + +It is often better to use CURLOPT_HEADERFUNCTION(3) to get the header +data separately. + +While named confusingly similar, CURLOPT_HTTPHEADER(3) is used to set +custom HTTP headers! + +# DEFAULT + +0 + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_HEADER, 1L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Provided in all libcurl versions. + +# RETURN VALUE + +Returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_HEADERDATA.3 b/docs/libcurl/opts/CURLOPT_HEADERDATA.3 deleted file mode 100644 index 20e696e4915..00000000000 --- a/docs/libcurl/opts/CURLOPT_HEADERDATA.3 +++ /dev/null @@ -1,91 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HEADERDATA 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HEADERDATA \- pointer to pass to header callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP to be used to write the header part of the received data -to. - -If \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP is used, -\fIpointer\fP is passed in to the respective callback. - -If neither of those options are set, \fIpointer\fP must be a valid FILE * and -it is used by a plain fwrite() to write headers to. - -If you are using libcurl as a win32 DLL, you \fBMUST\fP use a -\fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP if you set -this option or you might experience crashes. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct my_info { - int shoesize; - char *secret; -}; - -static size_t header_callback(char *buffer, size_t size, - size_t nitems, void *userdata) -{ - struct my_info *i = userdata; - printf("shoe size: %d\\n", i->shoesize); - /* now this callback can access the my_info struct */ - - return nitems * size; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct my_info my = { 10, "the cookies are in the cupboard" }; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback); - - /* pass in custom data to the callback */ - curl_easy_setopt(curl, CURLOPT_HEADERDATA, &my); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR curl_easy_header (3), -.BR CURLOPT_HEADERFUNCTION (3), -.BR CURLOPT_WRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_HEADERDATA.md b/docs/libcurl/opts/CURLOPT_HEADERDATA.md new file mode 100644 index 00000000000..7f056361f19 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HEADERDATA.md @@ -0,0 +1,89 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HEADERDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADERFUNCTION (3) + - CURLOPT_WRITEFUNCTION (3) + - curl_easy_header (3) +--- + +# NAME + +CURLOPT_HEADERDATA - pointer to pass to header callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERDATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* to be used to write the header part of the received data +to. + +If CURLOPT_WRITEFUNCTION(3) or CURLOPT_HEADERFUNCTION(3) is used, +*pointer* is passed in to the respective callback. + +If neither of those options are set, *pointer* must be a valid FILE * and +it is used by a plain fwrite() to write headers to. + +If you are using libcurl as a win32 DLL, you **MUST** use a +CURLOPT_WRITEFUNCTION(3) or CURLOPT_HEADERFUNCTION(3) if you set +this option or you might experience crashes. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct my_info { + int shoesize; + char *secret; +}; + +static size_t header_callback(char *buffer, size_t size, + size_t nitems, void *userdata) +{ + struct my_info *i = userdata; + printf("shoe size: %d\n", i->shoesize); + /* now this callback can access the my_info struct */ + + return nitems * size; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct my_info my = { 10, "the cookies are in the cupboard" }; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback); + + /* pass in custom data to the callback */ + curl_easy_setopt(curl, CURLOPT_HEADERDATA, &my); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md similarity index 62% rename from docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md index 03051b19383..40530c5a6fa 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md @@ -1,32 +1,22 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HEADERFUNCTION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HEADERFUNCTION \- callback that receives header data -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HEADERFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADERDATA (3) + - CURLOPT_WRITEFUNCTION (3) + - curl_easy_header (3) +--- + +# NAME + +CURLOPT_HEADERFUNCTION - callback that receives header data + +# SYNOPSIS + +~~~c #include size_t header_callback(char *buffer, @@ -36,35 +26,37 @@ size_t header_callback(char *buffer, CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, header_callback); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets invoked by libcurl as soon as it has received header data. The header callback is called once for each header and only complete header lines are passed on to the callback. Parsing headers is easy -to do using this callback. \fIbuffer\fP points to the delivered data, and the -size of that data is \fInitems\fP; \fIsize\fP is always 1. The provide header +to do using this callback. *buffer* points to the delivered data, and the +size of that data is *nitems*; *size* is always 1. The provide header line is not null-terminated! -The pointer named \fIuserdata\fP is the one you set with the -\fICURLOPT_HEADERDATA(3)\fP option. +The pointer named *userdata* is the one you set with the +CURLOPT_HEADERDATA(3) option. Your callback should return the number of bytes actually taken care of. If that amount differs from the amount passed to your callback function, it signals an error condition to the library. This causes the transfer to get -aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. +aborted and the libcurl function used returns *CURLE_WRITE_ERROR*. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) A complete HTTP header that is passed to this function can be up to -\fICURL_MAX_HTTP_HEADER\fP (100K) bytes and includes the final line terminator. +*CURL_MAX_HTTP_HEADER* (100K) bytes and includes the final line terminator. If this option is not set, or if it is set to NULL, but -\fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to +CURLOPT_HEADERDATA(3) is set to anything but NULL, the function used to accept response data is used instead. That is the function specified with -\fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or NULL - the +CURLOPT_WRITEFUNCTION(3), or if it is not specified or NULL - the default, stream-writing function. It's important to note that the callback is invoked for the headers of all @@ -89,19 +81,27 @@ For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function gets called with the server responses to the commands that libcurl sends. A more convenient way to get HTTP headers might be to use -\fIcurl_easy_header(3)\fP. -.SH LIMITATIONS +curl_easy_header(3). + +# LIMITATIONS + libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A folded header is a header that continues on a subsequent line and starts with a whitespace. Such folds are passed to the header callback as separate ones, although strictly they are just continuations of the previous lines. -.SH DEFAULT + +# DEFAULT + Nothing. -.SH PROTOCOLS + +# PROTOCOLS + Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3, IMAP, SMTP and more. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c static size_t header_callback(char *buffer, size_t size, size_t nitems, void *userdata) { @@ -121,12 +121,12 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Always -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK -.SH "SEE ALSO" -.BR curl_easy_header (3), -.BR CURLOPT_HEADERDATA (3), -.BR CURLOPT_WRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_HEADEROPT.3 b/docs/libcurl/opts/CURLOPT_HEADEROPT.3 deleted file mode 100644 index 000f2035ff1..00000000000 --- a/docs/libcurl/opts/CURLOPT_HEADEROPT.3 +++ /dev/null @@ -1,83 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HEADEROPT 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HEADEROPT \- send HTTP headers to both proxy and host or separately -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADEROPT, long bitmask); -.fi -.SH DESCRIPTION -Pass a long that is a bitmask of options of how to deal with headers. The two -mutually exclusive options are: - -\fBCURLHEADER_UNIFIED\fP - the headers specified in -\fICURLOPT_HTTPHEADER(3)\fP are used in requests both to servers and -proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP does not have -any effect. - -\fBCURLHEADER_SEPARATE\fP - makes \fICURLOPT_HTTPHEADER(3)\fP headers only get -sent to a server and not to a proxy. Proxy headers must be set with -\fICURLOPT_PROXYHEADER(3)\fP to get used. Note that if a non-CONNECT request -is sent to a proxy, libcurl sends both server headers and proxy headers. When -doing CONNECT, libcurl sends \fICURLOPT_PROXYHEADER(3)\fP headers only to the -proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to the server. -.SH DEFAULT -CURLHEADER_SEPARATE (changed in 7.42.1, used CURLHEADER_UNIFIED before then) -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - struct curl_slist *list; - list = curl_slist_append(NULL, "Shoesize: 10"); - list = curl_slist_append(list, "Accept:"); - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); - curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); - - /* HTTPS over a proxy makes a separate CONNECT to the proxy, so tell - libcurl to not send the custom headers to the proxy. Keep them - separate! */ - curl_easy_setopt(curl, CURLOPT_HEADEROPT, CURLHEADER_SEPARATE); - ret = curl_easy_perform(curl); - curl_slist_free_all(list); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.37.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTPHEADER (3), -.BR CURLOPT_PROXYHEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_HEADEROPT.md b/docs/libcurl/opts/CURLOPT_HEADEROPT.md new file mode 100644 index 00000000000..bb3bcf41ccf --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HEADEROPT.md @@ -0,0 +1,81 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HEADEROPT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPHEADER (3) + - CURLOPT_PROXYHEADER (3) +--- + +# NAME + +CURLOPT_HEADEROPT - send HTTP headers to both proxy and host or separately + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADEROPT, long bitmask); +~~~ + +# DESCRIPTION + +Pass a long that is a bitmask of options of how to deal with headers. The two +mutually exclusive options are: + +**CURLHEADER_UNIFIED** - the headers specified in +CURLOPT_HTTPHEADER(3) are used in requests both to servers and +proxies. With this option enabled, CURLOPT_PROXYHEADER(3) does not have +any effect. + +**CURLHEADER_SEPARATE** - makes CURLOPT_HTTPHEADER(3) headers only get +sent to a server and not to a proxy. Proxy headers must be set with +CURLOPT_PROXYHEADER(3) to get used. Note that if a non-CONNECT request +is sent to a proxy, libcurl sends both server headers and proxy headers. When +doing CONNECT, libcurl sends CURLOPT_PROXYHEADER(3) headers only to the +proxy and then CURLOPT_HTTPHEADER(3) headers only to the server. + +# DEFAULT + +CURLHEADER_SEPARATE (changed in 7.42.1, used CURLHEADER_UNIFIED before then) + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + struct curl_slist *list; + list = curl_slist_append(NULL, "Shoesize: 10"); + list = curl_slist_append(list, "Accept:"); + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); + + /* HTTPS over a proxy makes a separate CONNECT to the proxy, so tell + libcurl to not send the custom headers to the proxy. Keep them + separate! */ + curl_easy_setopt(curl, CURLOPT_HEADEROPT, CURLHEADER_SEPARATE); + ret = curl_easy_perform(curl); + curl_slist_free_all(list); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.37.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HSTS.3 b/docs/libcurl/opts/CURLOPT_HSTS.3 deleted file mode 100644 index 30d3f375300..00000000000 --- a/docs/libcurl/opts/CURLOPT_HSTS.3 +++ /dev/null @@ -1,83 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HSTS 3 "5 Feb 2019" libcurl libcurl -.SH NAME -CURLOPT_HSTS \- HSTS cache file name -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename); -.fi -.SH DESCRIPTION -Make the \fIfilename\fP point to a file name to load an existing HSTS cache -from, and to store the cache in when the easy handle is closed. Setting a file -name with this option also enables HSTS for this handle (the equivalent of -setting \fICURLHSTS_ENABLE\fP with \fICURLOPT_HSTS_CTRL(3)\fP). - -If the given file does not exist or contains no HSTS entries at startup, the -HSTS cache simply starts empty. Setting the file name to NULL or "" only -enables HSTS without reading from or writing to any file. - -If this option is set multiple times, libcurl loads cache entries from each -given file but only stores the last used name for later writing. -.SH "FILE FORMAT" -The HSTS cache is saved to and loaded from a text file with one entry per -physical line. Each line in the file has the following format: - -[host] [stamp] - -[host] is the domain name for the entry and the name is dot-prefixed if it is -an entry valid for all subdomains to the name as well or only for the exact -name. - -[stamp] is the time (in UTC) when the entry expires and it uses the format -\&"YYYYMMDD HH:MM:SS". - -Lines starting with "#" are treated as comments and are ignored. There is -currently no length or size limit. -.SH DEFAULT -NULL, no file name -.SH PROTOCOLS -HTTPS and HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache"); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.74.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_ALTSVC (3), -.BR CURLOPT_HSTS_CTRL (3), -.BR CURLOPT_RESOLVE (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTS.md b/docs/libcurl/opts/CURLOPT_HSTS.md new file mode 100644 index 00000000000..5d972066960 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTS.md @@ -0,0 +1,83 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HSTS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ALTSVC (3) + - CURLOPT_HSTS_CTRL (3) + - CURLOPT_RESOLVE (3) +--- + +# NAME + +CURLOPT_HSTS - HSTS cache file name + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename); +~~~ + +# DESCRIPTION + +Make the *filename* point to a file name to load an existing HSTS cache +from, and to store the cache in when the easy handle is closed. Setting a file +name with this option also enables HSTS for this handle (the equivalent of +setting *CURLHSTS_ENABLE* with CURLOPT_HSTS_CTRL(3)). + +If the given file does not exist or contains no HSTS entries at startup, the +HSTS cache simply starts empty. Setting the file name to NULL or "" only +enables HSTS without reading from or writing to any file. + +If this option is set multiple times, libcurl loads cache entries from each +given file but only stores the last used name for later writing. + +# FILE FORMAT + +The HSTS cache is saved to and loaded from a text file with one entry per +physical line. Each line in the file has the following format: + +[host] [stamp] + +[host] is the domain name for the entry and the name is dot-prefixed if it is +an entry valid for all subdomains to the name as well or only for the exact +name. + +[stamp] is the time (in UTC) when the entry expires and it uses the format +&"YYYYMMDD HH:MM:SS". + +Lines starting with "#" are treated as comments and are ignored. There is +currently no length or size limit. + +# DEFAULT + +NULL, no file name + +# PROTOCOLS + +HTTPS and HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache"); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.74.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 deleted file mode 100644 index 3097fbda8cd..00000000000 --- a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HSTSREADDATA 3 "14 Sep 2020" libcurl libcurl -.SH NAME -CURLOPT_HSTSREADDATA \- pointer passed to the HSTS read callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADDATA, void *pointer); -.fi -.SH DESCRIPTION -Data \fIpointer\fP to pass to the HSTS read function. If you use the -\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you get as input -in the 3rd argument to the callback. - -This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to -do that. -.SH DEFAULT -NULL -.SH PROTOCOLS -This feature is only used for HTTP(S) transfer. -.SH EXAMPLE -.nf -struct MyData { - void *custom; -}; - -int main(void) -{ - CURL *curl = curl_easy_init(); - struct MyData this; - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); - - /* pass pointer that gets passed in to the - CURLOPT_HSTSREADFUNCTION callback */ - curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &this); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.74.0 -.SH RETURN VALUE -This returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_HSTS (3), -.BR CURLOPT_HSTSREADFUNCTION (3), -.BR CURLOPT_HSTSWRITEDATA (3), -.BR CURLOPT_HSTSWRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md new file mode 100644 index 00000000000..8fbb888d357 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HSTSREADDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HSTS (3) + - CURLOPT_HSTSREADFUNCTION (3) + - CURLOPT_HSTSWRITEDATA (3) + - CURLOPT_HSTSWRITEFUNCTION (3) +--- + +# NAME + +CURLOPT_HSTSREADDATA - pointer passed to the HSTS read callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADDATA, void *pointer); +~~~ + +# DESCRIPTION + +Data *pointer* to pass to the HSTS read function. If you use the +CURLOPT_HSTSREADFUNCTION(3) option, this is the pointer you get as input +in the 3rd argument to the callback. + +This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to +do that. + +# DEFAULT + +NULL + +# PROTOCOLS + +This feature is only used for HTTP(S) transfer. + +# EXAMPLE + +~~~c +struct MyData { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + struct MyData this; + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* pass pointer that gets passed in to the + CURLOPT_HSTSREADFUNCTION callback */ + curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &this); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.74.0 + +# RETURN VALUE + +This returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 deleted file mode 100644 index 9fcd0464504..00000000000 --- a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 +++ /dev/null @@ -1,108 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HSTSREADFUNCTION 3 "14 Sep 2020" libcurl libcurl -.SH NAME -CURLOPT_HSTSREADFUNCTION \- read callback for HSTS hosts -.SH SYNOPSIS -.nf -#include - -struct curl_hstsentry { - char *name; - size_t namelen; - unsigned int includeSubDomains:1; - char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */ -}; - -CURLSTScode hstsread(CURL *easy, struct curl_hstsentry *sts, void *clientp); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADFUNCTION, hstsread); -.fi -.SH DESCRIPTION -Pass a pointer to your callback function, as the prototype shows above. - -This callback function gets called by libcurl repeatedly when it populates the -in-memory HSTS cache. - -Set the \fIclientp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option -or it is NULL. - -When this callback is invoked, the \fIsts\fP pointer points to a populated -struct: Copy the host name to \fIname\fP (no longer than \fInamelen\fP -bytes). Make it null-terminated. Set \fIincludeSubDomains\fP to TRUE or -FALSE. Set \fIexpire\fP to a date stamp or a zero length string for *forever* -(wrong date stamp format might cause the name to not get accepted) - -The callback should return \fICURLSTS_OK\fP if it returns a name and is -prepared to be called again (for another host) or \fICURLSTS_DONE\fP if it has -no entry to return. It can also return \fICURLSTS_FAIL\fP to signal -error. Returning \fICURLSTS_FAIL\fP stops the transfer from being performed -and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned. - -This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to -do that. -.SH DEFAULT -NULL - no callback. -.SH PROTOCOLS -This feature is only used for HTTP(S) transfer. -.SH EXAMPLE -.nf -struct priv { - void *custom; -}; - -static CURLSTScode hsts_cb(CURL *easy, struct curl_hstsentry *sts, - void *clientp) -{ - /* populate the struct as documented */ - return CURLSTS_OK; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct priv my_stuff; - CURLcode res; - - /* set HSTS read callback */ - curl_easy_setopt(curl, CURLOPT_HSTSREADFUNCTION, hsts_cb); - - /* pass in suitable argument to the callback */ - curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &my_stuff); - - res = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.74.0 -.SH RETURN VALUE -This returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_HSTS (3), -.BR CURLOPT_HSTS_CTRL (3), -.BR CURLOPT_HSTSREADDATA (3), -.BR CURLOPT_HSTSWRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md new file mode 100644 index 00000000000..5e60feb9edb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md @@ -0,0 +1,106 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HSTSREADFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HSTS (3) + - CURLOPT_HSTSREADDATA (3) + - CURLOPT_HSTSWRITEFUNCTION (3) + - CURLOPT_HSTS_CTRL (3) +--- + +# NAME + +CURLOPT_HSTSREADFUNCTION - read callback for HSTS hosts + +# SYNOPSIS + +~~~c +#include + +struct curl_hstsentry { + char *name; + size_t namelen; + unsigned int includeSubDomains:1; + char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */ +}; + +CURLSTScode hstsread(CURL *easy, struct curl_hstsentry *sts, void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADFUNCTION, hstsread); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, as the prototype shows above. + +This callback function gets called by libcurl repeatedly when it populates the +in-memory HSTS cache. + +Set the *clientp* argument with the CURLOPT_HSTSREADDATA(3) option +or it is NULL. + +When this callback is invoked, the *sts* pointer points to a populated +struct: Copy the host name to *name* (no longer than *namelen* +bytes). Make it null-terminated. Set *includeSubDomains* to TRUE or +FALSE. Set *expire* to a date stamp or a zero length string for *forever* +(wrong date stamp format might cause the name to not get accepted) + +The callback should return *CURLSTS_OK* if it returns a name and is +prepared to be called again (for another host) or *CURLSTS_DONE* if it has +no entry to return. It can also return *CURLSTS_FAIL* to signal +error. Returning *CURLSTS_FAIL* stops the transfer from being performed +and make *CURLE_ABORTED_BY_CALLBACK* get returned. + +This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to +do that. + +# DEFAULT + +NULL - no callback. + +# PROTOCOLS + +This feature is only used for HTTP(S) transfer. + +# EXAMPLE + +~~~c +struct priv { + void *custom; +}; + +static CURLSTScode hsts_cb(CURL *easy, struct curl_hstsentry *sts, + void *clientp) +{ + /* populate the struct as documented */ + return CURLSTS_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct priv my_stuff; + CURLcode res; + + /* set HSTS read callback */ + curl_easy_setopt(curl, CURLOPT_HSTSREADFUNCTION, hsts_cb); + + /* pass in suitable argument to the callback */ + curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &my_stuff); + + res = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.74.0 + +# RETURN VALUE + +This returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 deleted file mode 100644 index 04b7d383ea5..00000000000 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HSTSWRITEDATA 3 "14 Sep 2020" libcurl libcurl -.SH NAME -CURLOPT_HSTSWRITEDATA \- pointer passed to the HSTS write callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEDATA, void *pointer); -.fi -.SH DESCRIPTION -Data \fIpointer\fP to pass to the HSTS write function. If you use the -\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you get as -input in the fourth argument to the callback. - -This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to -do that. -.SH DEFAULT -NULL -.SH PROTOCOLS -This feature is only used for HTTP(S) transfer. -.SH EXAMPLE -.nf -struct MyData { - void *custom; -}; - -int main(void) -{ - CURL *curl = curl_easy_init(); - struct MyData this; - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); - - /* pass pointer that gets passed in to the - CURLOPT_HSTSWRITEFUNCTION callback */ - curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &this); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.74.0 -.SH RETURN VALUE -This returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_HSTS (3), -.BR CURLOPT_HSTSREADDATA (3), -.BR CURLOPT_HSTSREADFUNCTION (3), -.BR CURLOPT_HSTSWRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md new file mode 100644 index 00000000000..b4486d7a3be --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HSTSWRITEDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HSTS (3) + - CURLOPT_HSTSREADDATA (3) + - CURLOPT_HSTSREADFUNCTION (3) + - CURLOPT_HSTSWRITEFUNCTION (3) +--- + +# NAME + +CURLOPT_HSTSWRITEDATA - pointer passed to the HSTS write callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEDATA, void *pointer); +~~~ + +# DESCRIPTION + +Data *pointer* to pass to the HSTS write function. If you use the +CURLOPT_HSTSWRITEFUNCTION(3) option, this is the pointer you get as +input in the fourth argument to the callback. + +This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to +do that. + +# DEFAULT + +NULL + +# PROTOCOLS + +This feature is only used for HTTP(S) transfer. + +# EXAMPLE + +~~~c +struct MyData { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + struct MyData this; + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* pass pointer that gets passed in to the + CURLOPT_HSTSWRITEFUNCTION callback */ + curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &this); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.74.0 + +# RETURN VALUE + +This returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 deleted file mode 100644 index e5b3a950bd5..00000000000 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 +++ /dev/null @@ -1,112 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HSTSWRITEFUNCTION 3 "14 Sep 2020" libcurl libcurl -.SH NAME -CURLOPT_HSTSWRITEFUNCTION \- write callback for HSTS hosts -.SH SYNOPSIS -.nf -#include - -struct curl_hstsentry { - char *name; - size_t namelen; - unsigned int includeSubDomains:1; - char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */ -}; - -struct curl_index { - size_t index; /* the provided entry's "index" or count */ - size_t total; /* total number of entries to save */ -}; - -CURLSTScode hstswrite(CURL *easy, struct curl_hstsentry *sts, - struct curl_index *count, void *clientp); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEFUNCTION, hstswrite); -.fi -.SH DESCRIPTION -Pass a pointer to your callback function, as the prototype shows above. - -This callback function gets called by libcurl repeatedly to allow the -application to store the in-memory HSTS cache when libcurl is about to discard -it. - -Set the \fIclientp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option -or it is NULL. -When the callback is invoked, the \fIsts\fP pointer points to a populated -struct: Read the host name to 'name' (it is \fInamelen\fP bytes long and null -terminated. The \fIincludeSubDomains\fP field is non-zero if the entry matches -subdomains. The \fIexpire\fP string is a date stamp null-terminated string -using the syntax YYYYMMDD HH:MM:SS. - -The callback should return \fICURLSTS_OK\fP if it succeeded and is prepared to -be called again (for another host) or \fICURLSTS_DONE\fP if there is nothing -more to do. It can also return \fICURLSTS_FAIL\fP to signal error. - -This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to -do that. -.SH DEFAULT -NULL - no callback. -.SH PROTOCOLS -This feature is only used for HTTP(S) transfer. -.SH EXAMPLE -.nf -struct priv { - void *custom; -}; - -static CURLSTScode hswr_cb(CURL *easy, struct curl_hstsentry *sts, - struct curl_index *count, void *clientp) -{ - /* save the passed in HSTS data somewhere */ - return CURLSTS_OK; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct priv my_stuff; - CURLcode res; - - /* set HSTS read callback */ - curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hswr_cb); - - /* pass in suitable argument to the callback */ - curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &my_stuff); - - res = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.74.0 -.SH RETURN VALUE -This returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_HSTS (3), -.BR CURLOPT_HSTS_CTRL (3), -.BR CURLOPT_HSTSWRITEDATA (3), -.BR CURLOPT_HSTSWRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md new file mode 100644 index 00000000000..229b12e310d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md @@ -0,0 +1,110 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HSTSWRITEFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HSTS (3) + - CURLOPT_HSTSWRITEDATA (3) + - CURLOPT_HSTSWRITEFUNCTION (3) + - CURLOPT_HSTS_CTRL (3) +--- + +# NAME + +CURLOPT_HSTSWRITEFUNCTION - write callback for HSTS hosts + +# SYNOPSIS + +~~~c +#include + +struct curl_hstsentry { + char *name; + size_t namelen; + unsigned int includeSubDomains:1; + char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */ +}; + +struct curl_index { + size_t index; /* the provided entry's "index" or count */ + size_t total; /* total number of entries to save */ +}; + +CURLSTScode hstswrite(CURL *easy, struct curl_hstsentry *sts, + struct curl_index *count, void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEFUNCTION, hstswrite); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, as the prototype shows above. + +This callback function gets called by libcurl repeatedly to allow the +application to store the in-memory HSTS cache when libcurl is about to discard +it. + +Set the *clientp* argument with the CURLOPT_HSTSWRITEDATA(3) option +or it is NULL. +When the callback is invoked, the *sts* pointer points to a populated +struct: Read the host name to 'name' (it is *namelen* bytes long and null +terminated. The *includeSubDomains* field is non-zero if the entry matches +subdomains. The *expire* string is a date stamp null-terminated string +using the syntax YYYYMMDD HH:MM:SS. + +The callback should return *CURLSTS_OK* if it succeeded and is prepared to +be called again (for another host) or *CURLSTS_DONE* if there is nothing +more to do. It can also return *CURLSTS_FAIL* to signal error. + +This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to +do that. + +# DEFAULT + +NULL - no callback. + +# PROTOCOLS + +This feature is only used for HTTP(S) transfer. + +# EXAMPLE + +~~~c +struct priv { + void *custom; +}; + +static CURLSTScode hswr_cb(CURL *easy, struct curl_hstsentry *sts, + struct curl_index *count, void *clientp) +{ + /* save the passed in HSTS data somewhere */ + return CURLSTS_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct priv my_stuff; + CURLcode res; + + /* set HSTS read callback */ + curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hswr_cb); + + /* pass in suitable argument to the callback */ + curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &my_stuff); + + res = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.74.0 + +# RETURN VALUE + +This returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 deleted file mode 100644 index 2747ccdd7c5..00000000000 --- a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HSTS_CTRL 3 "4 Sep 2020" libcurl libcurl -.SH NAME -CURLOPT_HSTS_CTRL \- control HSTS behavior -.SH SYNOPSIS -.nf -#include - -#define CURLHSTS_ENABLE (1<<0) -#define CURLHSTS_READONLYFILE (1<<1) - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS_CTRL, long bitmask); -.fi -.SH DESCRIPTION -HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct -the client to not contact it again over clear-text HTTP for a certain period -into the future. libcurl then automatically redirects HTTP attempts to such -hosts to instead use HTTPS. This is done by libcurl retaining this knowledge -in an in-memory cache. - -Populate the long \fIbitmask\fP with the correct set of features to instruct -libcurl how to handle HSTS for the transfers using this handle. -.SH BITS -.IP "CURLHSTS_ENABLE" -Enable the in-memory HSTS cache for this handle. -.IP "CURLHSTS_READONLYFILE" -Make the HSTS file (if specified) read-only - makes libcurl not save the cache -to the file when closing the handle. -.SH DEFAULT -0. HSTS is disabled by default. -.SH PROTOCOLS -HTTPS and HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, (long)CURLHSTS_ENABLE); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.74.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_ALTSVC (3), -.BR CURLOPT_CONNECT_TO (3), -.BR CURLOPT_HSTS (3), -.BR CURLOPT_RESOLVE (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md new file mode 100644 index 00000000000..d60e58f0f12 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HSTS_CTRL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ALTSVC (3) + - CURLOPT_CONNECT_TO (3) + - CURLOPT_HSTS (3) + - CURLOPT_RESOLVE (3) +--- + +# NAME + +CURLOPT_HSTS_CTRL - control HSTS behavior + +# SYNOPSIS + +~~~c +#include + +#define CURLHSTS_ENABLE (1<<0) +#define CURLHSTS_READONLYFILE (1<<1) + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS_CTRL, long bitmask); +~~~ + +# DESCRIPTION + +HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct +the client to not contact it again over clear-text HTTP for a certain period +into the future. libcurl then automatically redirects HTTP attempts to such +hosts to instead use HTTPS. This is done by libcurl retaining this knowledge +in an in-memory cache. + +Populate the long *bitmask* with the correct set of features to instruct +libcurl how to handle HSTS for the transfers using this handle. + +# BITS + +## CURLHSTS_ENABLE + +Enable the in-memory HSTS cache for this handle. + +## CURLHSTS_READONLYFILE + +Make the HSTS file (if specified) read-only - makes libcurl not save the cache +to the file when closing the handle. + +# DEFAULT + +0. HSTS is disabled by default. + +# PROTOCOLS + +HTTPS and HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, (long)CURLHSTS_ENABLE); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.74.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 deleted file mode 100644 index af8f26bae1a..00000000000 --- a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTP09_ALLOWED 3 "17 Dec 2018" libcurl libcurl -.SH NAME -CURLOPT_HTTP09_ALLOWED \- allow HTTP/0.9 response -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP09_ALLOWED, long allowed); -.fi -.SH DESCRIPTION -Pass the long argument \fIallowed\fP set to 1L to allow HTTP/0.9 responses. - -An HTTP/0.9 response is a server response entirely without headers and only a -body. You can connect to lots of random TCP services and still get a response -that curl might consider to be HTTP/0.9! -.SH DEFAULT -curl allowed HTTP/0.9 responses by default before 7.66.0 - -Since 7.66.0, libcurl requires this option set to 1L to allow HTTP/0.9 -responses. -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_HTTP09_ALLOWED, 1L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Option added in 7.64.0, present along with HTTP. -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTP_VERSION (3), -.BR CURLOPT_SSLVERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md new file mode 100644 index 00000000000..d3594926f5c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTP09_ALLOWED +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTP_VERSION (3) + - CURLOPT_SSLVERSION (3) +--- + +# NAME + +CURLOPT_HTTP09_ALLOWED - allow HTTP/0.9 response + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP09_ALLOWED, long allowed); +~~~ + +# DESCRIPTION + +Pass the long argument *allowed* set to 1L to allow HTTP/0.9 responses. + +An HTTP/0.9 response is a server response entirely without headers and only a +body. You can connect to lots of random TCP services and still get a response +that curl might consider to be HTTP/0.9! + +# DEFAULT + +curl allowed HTTP/0.9 responses by default before 7.66.0 + +Since 7.66.0, libcurl requires this option set to 1L to allow HTTP/0.9 +responses. + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HTTP09_ALLOWED, 1L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Option added in 7.64.0, present along with HTTP. + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 deleted file mode 100644 index 05a0e3ac3a8..00000000000 --- a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTP200ALIASES 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTP200ALIASES \- alternative matches for HTTP 200 OK -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP200ALIASES, - struct curl_slist *aliases); -.SH DESCRIPTION -Pass a pointer to a linked list of \fIaliases\fP to be treated as valid HTTP -200 responses. Some servers respond with a custom header response line. For -example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast -1.3.x servers respond like that for certain user agent headers or in absence -of such. By including this string in your list of aliases, the response gets -treated as a valid HTTP header line such as "HTTP/1.0 200 OK". - -The linked list should be a fully valid list of struct curl_slist structs, and -be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and -\fIcurl_slist_free_all(3)\fP to clean up an entire list. - -The alias itself is not parsed for any version strings. The protocol is -assumed to match HTTP 1.0 when an alias match. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct curl_slist *list; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - list = curl_slist_append(NULL, "ICY 200 OK"); - list = curl_slist_append(list, "WEIRDO 99 FINE"); - - curl_easy_setopt(curl, CURLOPT_HTTP200ALIASES, list); - curl_easy_perform(curl); - curl_slist_free_all(list); /* free the list again */ - } -} -.fi -.SH AVAILABILITY -Added in 7.10.3 -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTP09_ALLOWED (3), -.BR CURLOPT_HTTP_VERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md new file mode 100644 index 00000000000..b48faf6038e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTP200ALIASES +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTP09_ALLOWED (3) + - CURLOPT_HTTP_VERSION (3) +--- + +# NAME + +CURLOPT_HTTP200ALIASES - alternative matches for HTTP 200 OK + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP200ALIASES, + struct curl_slist *aliases); +~~~ + +# DESCRIPTION + +Pass a pointer to a linked list of *aliases* to be treated as valid HTTP 200 +responses. Some servers respond with a custom header response line. For +example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast +1.3.x servers respond like that for certain user agent headers or in absence +of such. By including this string in your list of aliases, the response gets +treated as a valid HTTP header line such as "HTTP/1.0 200 OK". + +The linked list should be a fully valid list of struct curl_slist structs, and +be properly filled in. Use curl_slist_append(3) to create the list and +curl_slist_free_all(3) to clean up an entire list. + +The alias itself is not parsed for any version strings. The protocol is +assumed to match HTTP 1.0 when an alias match. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_slist *list; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + list = curl_slist_append(NULL, "ICY 200 OK"); + list = curl_slist_append(list, "WEIRDO 99 FINE"); + + curl_easy_setopt(curl, CURLOPT_HTTP200ALIASES, list); + curl_easy_perform(curl); + curl_slist_free_all(list); /* free the list again */ + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.3 + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md similarity index 51% rename from docs/libcurl/opts/CURLOPT_HTTPAUTH.3 rename to docs/libcurl/opts/CURLOPT_HTTPAUTH.md index 661f52942a5..ca92f5eb098 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md @@ -1,36 +1,29 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTPAUTH 3 "2 Aug 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTPAUTH \- HTTP server authentication methods to try -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTPAUTH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PASSWORD (3) + - CURLOPT_PROXYAUTH (3) + - CURLOPT_USERNAME (3) +--- + +# NAME + +CURLOPT_HTTPAUTH - HTTP server authentication methods to try + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use speaking to the remote server. @@ -38,76 +31,103 @@ The available bits are listed below. If more than one bit is set, libcurl first queries the host to see which authentication methods it supports and then picks the best one you allow it to use. For some methods, this induces an extra network round-trip. Set the actual name and password with the -\fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the -\fICURLOPT_PASSWORD(3)\fP options. +CURLOPT_USERPWD(3) option or with the CURLOPT_USERNAME(3) and the +CURLOPT_PASSWORD(3) options. + +For authentication with a proxy, see CURLOPT_PROXYAUTH(3). -For authentication with a proxy, see \fICURLOPT_PROXYAUTH(3)\fP. +## CURLAUTH_BASIC -.IP CURLAUTH_BASIC HTTP Basic authentication. This is the default choice, and the only method that is in wide-spread use and supported virtually everywhere. This sends the user name and password over the network in plain text, easily captured by others. -.IP CURLAUTH_DIGEST -HTTP Digest authentication. Digest authentication is defined in RFC 2617 and + +## CURLAUTH_DIGEST + +HTTP Digest authentication. Digest authentication is defined in RFC 2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. -.IP CURLAUTH_DIGEST_IE -HTTP Digest authentication with an IE flavor. Digest authentication is -defined in RFC 2617 and is a more secure way to do authentication over public -networks than the regular old-fashioned Basic method. The IE flavor is simply -that libcurl uses a special "quirk" that IE is known to have used before -version 7 and that some servers require the client to use. -.IP CURLAUTH_BEARER + +## CURLAUTH_DIGEST_IE + +HTTP Digest authentication with an IE flavor. Digest authentication is defined +in RFC 2617 and is a more secure way to do authentication over public networks +than the regular old-fashioned Basic method. The IE flavor is simply that +libcurl uses a special "quirk" that IE is known to have used before version 7 +and that some servers require the client to use. + +## CURLAUTH_BEARER + HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol. -You can set the Bearer token to use with \fICURLOPT_XOAUTH2_BEARER(3)\fP. -.IP CURLAUTH_NEGOTIATE +You can set the Bearer token to use with CURLOPT_XOAUTH2_BEARER(3). + +## CURLAUTH_NEGOTIATE + HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined in RFC 4559 and is the most secure way to perform authentication over HTTP. You need to build libcurl with a suitable GSS-API library or SSPI on Windows for this to work. -.IP CURLAUTH_NTLM + +## CURLAUTH_NTLM + HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being eavesdropped. You need to build libcurl with either OpenSSL or GnuTLS support for this option to work, or build libcurl on Windows with SSPI support. -.IP CURLAUTH_NTLM_WB + +## CURLAUTH_NTLM_WB + NTLM delegating to winbind helper. Authentication is performed by a separate binary application that is executed when needed. The name of the application -is specified at compile time but is typically \fB/usr/bin/ntlm_auth\fP. +is specified at compile time but is typically **/usr/bin/ntlm_auth**. Note that libcurl forks when necessary to run the winbind application and kill -it when complete, calling \fBwaitpid()\fP to await its exit when done. On -POSIX operating systems, killing the process causes a SIGCHLD signal to be -raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be -handled intelligently by the application. In particular, the application must -not unconditionally call wait() in its SIGCHLD signal handler to avoid being -subject to a race condition. This behavior is subject to change in future +it when complete, calling **waitpid()** to await its exit when done. On POSIX +operating systems, killing the process causes a SIGCHLD signal to be raised +(regardless of whether CURLOPT_NOSIGNAL(3) is set), which must be handled +intelligently by the application. In particular, the application must not +unconditionally call wait() in its SIGCHLD signal handler to avoid being +subject to a race condition. This behavior is subject to change in future versions of libcurl. -.IP CURLAUTH_ANY + +## CURLAUTH_ANY + This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl automatically selects the one it finds most secure. -.IP CURLAUTH_ANYSAFE + +## CURLAUTH_ANYSAFE + This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl automatically selects the one it finds most secure. -.IP CURLAUTH_ONLY + +## CURLAUTH_ONLY + This is a meta symbol. OR this value together with a single specific auth value to force libcurl to probe for unrestricted auth and if not, only that single auth algorithm is acceptable. -.IP CURLAUTH_AWS_SIGV4 + +## CURLAUTH_AWS_SIGV4 + provides AWS V4 signature authentication on HTTPS header -see \fICURLOPT_AWS_SIGV4(3)\fP. -.SH DEFAULT +see CURLOPT_AWS_SIGV4(3). + +# DEFAULT + CURLAUTH_BASIC -.SH PROTOCOLS + +# PROTOCOLS + HTTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -120,8 +140,10 @@ int main(void) ret = curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Option Added in 7.10.6. CURLAUTH_DIGEST_IE was added in 7.19.3 @@ -133,11 +155,9 @@ CURLAUTH_NTLM_WB was added in 7.22.0 CURLAUTH_BEARER was added in 7.61.0 CURLAUTH_AWS_SIGV4 was added in 7.74.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication methods. -.SH "SEE ALSO" -.BR CURLOPT_PASSWORD (3), -.BR CURLOPT_PROXYAUTH (3), -.BR CURLOPT_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.3 b/docs/libcurl/opts/CURLOPT_HTTPGET.3 deleted file mode 100644 index 9a3af4d7ca9..00000000000 --- a/docs/libcurl/opts/CURLOPT_HTTPGET.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTPGET 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTPGET \- ask for an HTTP GET request -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPGET, long useget); -.fi -.SH DESCRIPTION -Pass a long. If \fIuseget\fP is 1, this forces the HTTP request to get back to -using GET. Usable if a POST, HEAD, PUT, etc has been used previously using the -same curl \fIhandle\fP. - -When setting \fICURLOPT_HTTPGET(3)\fP to 1, libcurl automatically sets -\fICURLOPT_NOBODY(3)\fP to 0 and \fICURLOPT_UPLOAD(3)\fP to 0. - -Setting this option to zero has no effect. Applications need to explicitly -select which HTTP request method to use, they cannot deselect a method. To -reset a handle to default method, consider \fIcurl_easy_reset(3)\fP. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* use a GET to fetch this */ - curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_easy_reset (3), -.BR CURLOPT_NOBODY (3), -.BR CURLOPT_POST (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.md b/docs/libcurl/opts/CURLOPT_HTTPGET.md new file mode 100644 index 00000000000..d8b024d8eb4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTPGET.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTPGET +Section: 3 +Source: libcurl +See-also: + - CURLOPT_NOBODY (3) + - CURLOPT_POST (3) + - CURLOPT_UPLOAD (3) + - curl_easy_reset (3) +--- + +# NAME + +CURLOPT_HTTPGET - ask for an HTTP GET request + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPGET, long useget); +~~~ + +# DESCRIPTION + +Pass a long. If *useget* is 1, this forces the HTTP request to get back to +using GET. Usable if a POST, HEAD, PUT, etc has been used previously using the +same curl *handle*. + +When setting CURLOPT_HTTPGET(3) to 1, libcurl automatically sets +CURLOPT_NOBODY(3) to 0 and CURLOPT_UPLOAD(3) to 0. + +Setting this option to zero has no effect. Applications need to explicitly +select which HTTP request method to use, they cannot deselect a method. To +reset a handle to default method, consider curl_easy_reset(3). + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* use a GET to fetch this */ + curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 b/docs/libcurl/opts/CURLOPT_HTTPHEADER.md similarity index 62% rename from docs/libcurl/opts/CURLOPT_HTTPHEADER.3 rename to docs/libcurl/opts/CURLOPT_HTTPHEADER.md index a750b98105e..0170336acc8 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.md @@ -1,50 +1,45 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTPHEADER 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTPHEADER \- set of HTTP headers -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTPHEADER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CUSTOMREQUEST (3) + - CURLOPT_HEADER (3) + - CURLOPT_HEADEROPT (3) + - CURLOPT_MIMEPOST (3) + - CURLOPT_PROXYHEADER (3) + - curl_mime_init (3) +--- + +# NAME + +CURLOPT_HTTPHEADER - set of HTTP headers + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPHEADER, struct curl_slist *headers); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a linked list of HTTP headers to pass to the server and/or proxy in your HTTP request. The same list can be used for both host and proxy requests! When used within an IMAP or SMTP request to upload a MIME mail, the given header list establishes the document-level MIME headers to prepend to the -uploaded document described by \fICURLOPT_MIMEPOST(3)\fP. This does not affect +uploaded document described by CURLOPT_MIMEPOST(3). This does not affect raw mail uploads. -The linked list should be a fully valid list of \fBstruct curl_slist\fP -structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list -and \fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a +The linked list should be a fully valid list of **struct curl_slist** +structs properly filled in. Use curl_slist_append(3) to create the list +and curl_slist_free_all(3) to clean up an entire list. If you add a header that is otherwise generated and used by libcurl internally, your added header is used instead. If you add a header with no content as in 'Accept:' (no data on the right side of the colon), the internally used header is @@ -53,7 +48,7 @@ headers and remove internal headers. To add a header with no content (nothing to the right side of the colon), use the form 'name;' (note the ending semicolon). -The headers included in the linked list \fBmust not\fP be CRLF-terminated, +The headers included in the linked list **must not** be CRLF-terminated, because libcurl adds CRLF after each header item itself. Failure to comply with this might result in strange behavior. libcurl passes on the verbatim strings you give it, without any filter or other safe guards. That includes @@ -63,39 +58,51 @@ The first line in an HTTP request (containing the method, usually a GET or POST) is not a header and cannot be replaced using this option. Only the lines following the request-line are headers. Adding this method line in this list of headers only causes your request to send an invalid header. Use -\fICURLOPT_CUSTOMREQUEST(3)\fP to change the method. +CURLOPT_CUSTOMREQUEST(3) to change the method. -When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy -the entire list so you \fBmust\fP keep it around until you no longer use this -\fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on +When this option is passed to curl_easy_setopt(3), libcurl does not copy +the entire list so you **must** keep it around until you no longer use this +*handle* for a transfer before you call curl_slist_free_all(3) on the list. Pass a NULL to this option to reset back to no custom headers. The most commonly replaced HTTP headers have "shortcuts" in the options -\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and -\fICURLOPT_REFERER(3)\fP. We recommend using those. +CURLOPT_COOKIE(3), CURLOPT_USERAGENT(3) and +CURLOPT_REFERER(3). We recommend using those. There is an alternative option that sets or replaces headers only for requests -that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use -\fICURLOPT_HEADEROPT(3)\fP to control the behavior. -.SH SPECIFIC HTTP HEADERS +that are sent with CONNECT to a proxy: CURLOPT_PROXYHEADER(3). Use +CURLOPT_HEADEROPT(3) to control the behavior. + +# SPECIFIC HTTP HEADERS + Setting some specific headers causes libcurl to act differently. -.IP "Host:" + +## Host: + The specified host name is used for cookie matching if the cookie engine is also enabled for this transfer. If the request is done over HTTP/2 or HTTP/3, the custom host name is instead used in the ":authority" header field and Host: is not sent at all over the wire. -.IP "Transfer-Encoding: chunked" + +## Transfer-Encoding: chunked + Tells libcurl the upload is to be done using this chunked encoding instead of providing the Content-Length: field in the request. -.SH SPECIFIC MIME HEADERS + +# SPECIFIC MIME HEADERS + When used to build a MIME e-mail for IMAP or SMTP, the following document-level headers can be set to override libcurl-generated values: -.IP "Mime-Version:" + +## Mime-Version: + Tells the parser at the receiving site how to interpret the MIME framing. It defaults to "1.0" and should normally not be altered. -.IP "Content-Type:" + +## Content-Type: + Indicates the document's global structure type. By default, libcurl sets it to "multipart/mixed", describing a document made of independent parts. When a MIME mail is only composed of alternative representations of the same data @@ -107,35 +114,43 @@ Other specific headers that do not have a libcurl default value but are strongly desired by mail delivery and user agents should also be included. These are "From:", "To:", "Date:" and "Subject:" among others and their presence and value is generally checked by anti-spam utilities. -.SH SECURITY CONCERNS + +# SECURITY CONCERNS + By default, this option makes libcurl send the given headers in all HTTP requests done by this handle. You should therefore use this option with caution if you for example connect to the remote site using a proxy and a CONNECT request, you should to consider if that proxy is supposed to also get the headers. They may be private or otherwise sensitive to leak. -Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you +Use CURLOPT_HEADEROPT(3) to make the headers only get sent to where you intend them to get sent. Custom headers are sent in all requests done by the easy handle, which implies that if you tell libcurl to follow redirects -(\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers is sent in +(CURLOPT_FOLLOWLOCATION(3)), the same set of custom headers is sent in the subsequent request. Redirects can of course go to other hosts and thus those servers get all the contents of your custom headers too. Starting in 7.58.0, libcurl specifically prevents "Authorization:" headers from being sent to other hosts than the first used one, unless specifically -permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. +permitted with the CURLOPT_UNRESTRICTED_AUTH(3) option. Starting in 7.64.0, libcurl specifically prevents "Cookie:" headers from being sent to other hosts than the first used one, unless specifically permitted -with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. -.SH DEFAULT +with the CURLOPT_UNRESTRICTED_AUTH(3) option. + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + HTTP, IMAP and SMTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -155,16 +170,12 @@ int main(void) curl_slist_free_all(list); /* free the list */ } } -.fi +~~~ + +# AVAILABILITY -.SH AVAILABILITY As long as HTTP is enabled. Use in MIME mail added in 7.56.0. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_mime_init (3), -.BR CURLOPT_CUSTOMREQUEST (3), -.BR CURLOPT_HEADER (3), -.BR CURLOPT_HEADEROPT (3), -.BR CURLOPT_MIMEPOST (3), -.BR CURLOPT_PROXYHEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 deleted file mode 100644 index f86db4ee7ec..00000000000 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 +++ /dev/null @@ -1,101 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTPPOST 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTPPOST \- multipart formpost content -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPOST, - struct curl_httppost *formpost); -.SH DESCRIPTION -\fBThis option is deprecated.\fP Use \fICURLOPT_MIMEPOST(3)\fP instead. - -Tells libcurl you want a \fBmultipart/formdata\fP HTTP POST to be made and you -instruct what data to pass on to the server in the \fIformpost\fP argument. -Pass a pointer to a linked list of \fIcurl_httppost\fP structs as parameter. -The easiest way to create such a list, is to use \fIcurl_formadd(3)\fP as -documented. The data in this list must remain intact as long as the curl -transfer is alive and is using it. - -Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. -You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP. - -When setting \fICURLOPT_HTTPPOST(3)\fP, libcurl automatically sets -\fICURLOPT_NOBODY(3)\fP to 0. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - struct curl_httppost *formpost; - struct curl_httppost *lastptr; - - /* Fill in the file upload field. This makes libcurl load data from - the given file name when curl_easy_perform() is called. */ - curl_formadd(&formpost, - &lastptr, - CURLFORM_COPYNAME, "sendfile", - CURLFORM_FILE, "postit2.c", - CURLFORM_END); - - /* Fill in the filename field */ - curl_formadd(&formpost, - &lastptr, - CURLFORM_COPYNAME, "filename", - CURLFORM_COPYCONTENTS, "postit2.c", - CURLFORM_END); - - /* Fill in the submit field too, even if this is rarely needed */ - curl_formadd(&formpost, - &lastptr, - CURLFORM_COPYNAME, "submit", - CURLFORM_COPYCONTENTS, "send", - CURLFORM_END); - - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); - curl_easy_perform(curl); - curl_easy_cleanup(curl); - } - curl_formfree(formpost); -} -.fi -.SH AVAILABILITY -As long as HTTP is enabled. Deprecated in 7.56.0. -.SH RETURN VALUE -Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_formadd (3), -.BR curl_formfree (3), -.BR curl_mime_init (3), -.BR CURLOPT_MIMEPOST (3), -.BR CURLOPT_POST (3), -.BR CURLOPT_POSTFIELDS (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.md b/docs/libcurl/opts/CURLOPT_HTTPPOST.md new file mode 100644 index 00000000000..6fdfc170701 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.md @@ -0,0 +1,100 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTPPOST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MIMEPOST (3) + - CURLOPT_POST (3) + - CURLOPT_POSTFIELDS (3) + - curl_formadd (3) + - curl_formfree (3) + - curl_mime_init (3) +--- + +# NAME + +CURLOPT_HTTPPOST - multipart formpost content + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPOST, + struct curl_httppost *formpost); +~~~ + +# DESCRIPTION + +**This option is deprecated.** Use CURLOPT_MIMEPOST(3) instead. + +Tells libcurl you want a **multipart/formdata** HTTP POST to be made and you +instruct what data to pass on to the server in the *formpost* argument. +Pass a pointer to a linked list of *curl_httppost* structs as parameter. +The easiest way to create such a list, is to use curl_formadd(3) as +documented. The data in this list must remain intact as long as the curl +transfer is alive and is using it. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with CURLOPT_HTTPHEADER(3). + +When setting CURLOPT_HTTPPOST(3), libcurl automatically sets +CURLOPT_NOBODY(3) to 0. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + struct curl_httppost *formpost; + struct curl_httppost *lastptr; + + /* Fill in the file upload field. This makes libcurl load data from + the given file name when curl_easy_perform() is called. */ + curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "sendfile", + CURLFORM_FILE, "postit2.c", + CURLFORM_END); + + /* Fill in the filename field */ + curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "filename", + CURLFORM_COPYCONTENTS, "postit2.c", + CURLFORM_END); + + /* Fill in the submit field too, even if this is rarely needed */ + curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "submit", + CURLFORM_COPYCONTENTS, "send", + CURLFORM_END); + + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } + curl_formfree(formpost); +} +~~~ + +# AVAILABILITY + +As long as HTTP is enabled. Deprecated in 7.56.0. + +# RETURN VALUE + +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 deleted file mode 100644 index 542eefe6c0c..00000000000 --- a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTPPROXYTUNNEL 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTPPROXYTUNNEL \- tunnel through HTTP proxy -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPROXYTUNNEL, long tunnel); -.fi -.SH DESCRIPTION -Set the \fBtunnel\fP parameter to 1L to make libcurl tunnel all operations -through the HTTP proxy (set with \fICURLOPT_PROXY(3)\fP). There is a big -difference between using a proxy and to tunnel through it. - -Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it -to connect to a remote host on a specific port number and then the traffic is -just passed through the proxy. Proxies tend to white-list specific port numbers -it allows CONNECT requests to and often only port 80 and 443 are allowed. - -To suppress proxy CONNECT response headers from user callbacks use -\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. - -HTTP proxies can generally only speak HTTP (for obvious reasons), which makes -libcurl convert non-HTTP requests to HTTP when using an HTTP proxy without -this tunnel option set. For example, asking for an FTP URL and specifying an -HTTP proxy makes libcurl send an FTP URL in an HTTP GET request to the -proxy. By instead tunneling through the proxy, you avoid that conversion (that -rarely works through the proxy anyway). -.SH DEFAULT -0 -.SH PROTOCOLS -All network protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); - curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYTYPE (3), -.BR CURLOPT_PROXYPORT (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md new file mode 100644 index 00000000000..bd67640b491 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTPPROXYTUNNEL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_PROXYPORT (3) + - CURLOPT_PROXYTYPE (3) +--- + +# NAME + +CURLOPT_HTTPPROXYTUNNEL - tunnel through HTTP proxy + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPROXYTUNNEL, long tunnel); +~~~ + +# DESCRIPTION + +Set the **tunnel** parameter to 1L to make libcurl tunnel all operations +through the HTTP proxy (set with CURLOPT_PROXY(3)). There is a big +difference between using a proxy and to tunnel through it. + +Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it +to connect to a remote host on a specific port number and then the traffic is +just passed through the proxy. Proxies tend to white-list specific port numbers +it allows CONNECT requests to and often only port 80 and 443 are allowed. + +To suppress proxy CONNECT response headers from user callbacks use +CURLOPT_SUPPRESS_CONNECT_HEADERS(3). + +HTTP proxies can generally only speak HTTP (for obvious reasons), which makes +libcurl convert non-HTTP requests to HTTP when using an HTTP proxy without +this tunnel option set. For example, asking for an FTP URL and specifying an +HTTP proxy makes libcurl send an FTP URL in an HTTP GET request to the +proxy. By instead tunneling through the proxy, you avoid that conversion (that +rarely works through the proxy anyway). + +# DEFAULT + +0 + +# PROTOCOLS + +All network protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); + curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 deleted file mode 100644 index 7d6dabee375..00000000000 --- a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTP_CONTENT_DECODING 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTP_CONTENT_DECODING \- HTTP content decoding control -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_CONTENT_DECODING, - long enabled); -.SH DESCRIPTION -Pass a long to tell libcurl how to act on content decoding. If set to zero, -content decoding is disabled. If set to 1 it is enabled. Libcurl has no -default content decoding but requires you to use -\fICURLOPT_ACCEPT_ENCODING(3)\fP for that. -.SH DEFAULT -1 -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_HTTP_CONTENT_DECODING, 0L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.16.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_ACCEPT_ENCODING (3), -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md new file mode 100644 index 00000000000..b48c0f9fbdf --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTP_CONTENT_DECODING +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ACCEPT_ENCODING (3) + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_STDERR (3) +--- + +# NAME + +CURLOPT_HTTP_CONTENT_DECODING - HTTP content decoding control + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_CONTENT_DECODING, + long enabled); +~~~ + +# DESCRIPTION + +Pass a long to tell libcurl how to act on content decoding. If set to zero, +content decoding is disabled. If set to 1 it is enabled. Libcurl has no +default content decoding but requires you to use +CURLOPT_ACCEPT_ENCODING(3) for that. + +# DEFAULT + +1 + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HTTP_CONTENT_DECODING, 0L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.16.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 deleted file mode 100644 index a00fb1a1ded..00000000000 --- a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 +++ /dev/null @@ -1,62 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTP_TRANSFER_DECODING 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTP_TRANSFER_DECODING \- HTTP transfer decoding control -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_TRANSFER_DECODING, - long enabled); -.SH DESCRIPTION -Pass a long to tell libcurl how to act on transfer decoding. If set to zero, -transfer decoding is disabled, if set to 1 it is enabled (default). libcurl -does chunked transfer decoding by default unless this option is set to zero. -.SH DEFAULT -1 -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_HTTP_TRANSFER_DECODING, 0L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.16.2 Does not work with the hyper backend (it always has transfer -decoding enabled). -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTP_CONTENT_DECODING (3), -.BR CURLOPT_ACCEPT_ENCODING (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md new file mode 100644 index 00000000000..ba83acaae1a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTP_TRANSFER_DECODING +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ACCEPT_ENCODING (3) + - CURLOPT_HTTP_CONTENT_DECODING (3) +--- + +# NAME + +CURLOPT_HTTP_TRANSFER_DECODING - HTTP transfer decoding control + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_TRANSFER_DECODING, + long enabled); +~~~ + +# DESCRIPTION + +Pass a long to tell libcurl how to act on transfer decoding. If set to zero, +transfer decoding is disabled, if set to 1 it is enabled (default). libcurl +does chunked transfer decoding by default unless this option is set to zero. + +# DEFAULT + +1 + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_HTTP_TRANSFER_DECODING, 0L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.16.2 Does not work with the hyper backend (it always has transfer +decoding enabled). + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md similarity index 52% rename from docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 rename to docs/libcurl/opts/CURLOPT_HTTP_VERSION.md index 87b133b88a4..a41e1a27702 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md @@ -1,85 +1,99 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_HTTP_VERSION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_HTTP_VERSION \- HTTP protocol version to use -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_HTTP_VERSION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ALTSVC (3) + - CURLOPT_HTTP09_ALLOWED (3) + - CURLOPT_HTTP200ALIASES (3) + - CURLOPT_SSLVERSION (3) +--- + +# NAME + +CURLOPT_HTTP_VERSION - HTTP protocol version to use + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version); -.fi -.SH DESCRIPTION -Pass \fIversion\fP a long, set to one of the values described below. They ask +~~~ + +# DESCRIPTION + +Pass *version* a long, set to one of the values described below. They ask libcurl to use the specific HTTP versions. Note that the HTTP version is just a request. libcurl still prioritizes to reuse existing connections so it might then reuse a connection using a HTTP version you have not asked for. -.IP CURL_HTTP_VERSION_NONE +## CURL_HTTP_VERSION_NONE + We do not care about what version the library uses. libcurl uses whatever it thinks fit. -.IP CURL_HTTP_VERSION_1_0 + +## CURL_HTTP_VERSION_1_0 + Enforce HTTP 1.0 requests. -.IP CURL_HTTP_VERSION_1_1 + +## CURL_HTTP_VERSION_1_1 + Enforce HTTP 1.1 requests. -.IP CURL_HTTP_VERSION_2_0 + +## CURL_HTTP_VERSION_2_0 + Attempt HTTP 2 requests. libcurl falls back to HTTP 1.1 if HTTP 2 cannot be negotiated with the server. (Added in 7.33.0) When libcurl 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 \fICURLOPT_SSLVERSION(3)\fP. +version requirement with CURLOPT_SSLVERSION(3). -The alias \fICURL_HTTP_VERSION_2\fP was added in 7.43.0 to better reflect the +The alias *CURL_HTTP_VERSION_2* was added in 7.43.0 to better reflect the actual protocol name. -.IP CURL_HTTP_VERSION_2TLS + +## CURL_HTTP_VERSION_2TLS + Attempt HTTP 2 over TLS (HTTPS) only. libcurl falls back to HTTP 1.1 if HTTP 2 cannot be negotiated with the HTTPS server. For clear text HTTP servers, libcurl uses 1.1. (Added in 7.47.0) -.IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE + +## CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE + Issue 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. (Added in 7.49.0) -.IP CURL_HTTP_VERSION_3 + +## CURL_HTTP_VERSION_3 + (Added in 7.66.0) This option makes libcurl attempt to use HTTP/3 to the host given in the URL, with fallback to earlier HTTP versions if needed. -.IP CURL_HTTP_VERSION_3ONLY + +## CURL_HTTP_VERSION_3ONLY + (Added in 7.88.0) Setting this makes libcurl attempt to use HTTP/3 directly to server given in the URL and does not downgrade to earlier HTTP version if the server does not support HTTP/3. -.SH DEFAULT + +# DEFAULT + Since curl 7.62.0: CURL_HTTP_VERSION_2TLS Before that: CURL_HTTP_VERSION_1_1 -.SH PROTOCOLS + +# PROTOCOLS + HTTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -94,13 +108,12 @@ int main(void) } } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Along with HTTP -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_ALTSVC (3), -.BR CURLOPT_HTTP09_ALLOWED (3), -.BR CURLOPT_HTTP200ALIASES (3), -.BR CURLOPT_SSLVERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 deleted file mode 100644 index 2512b665fc4..00000000000 --- a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_IGNORE_CONTENT_LENGTH 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_IGNORE_CONTENT_LENGTH \- ignore content length -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IGNORE_CONTENT_LENGTH, - long ignore); -.SH DESCRIPTION -If \fIignore\fP is set to 1L, ignore the Content-Length header in the HTTP -response and ignore asking for or relying on it for FTP transfers. - -This is useful for doing HTTP transfers with ancient web servers which report -incorrect content length for files over 2 gigabytes. If this option is used, -curl cannot accurately report progress, and it instead stops the download when -the server ends the connection. - -It is also useful with FTP when for example the file is growing while the -transfer is in progress which otherwise unconditionally causes libcurl to -report error. - -Only use this option if strictly necessary. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* we know the server is silly, ignore content-length */ - curl_easy_setopt(curl, CURLOPT_IGNORE_CONTENT_LENGTH, 1L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.14.1. Support for FTP added in 7.46.0. This option is not working -for HTTP when libcurl is built to use the hyper backend. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTP_VERSION (3), -.BR CURLOPT_MAXFILESIZE_LARGE (3) diff --git a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md new file mode 100644 index 00000000000..d12b4912017 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_IGNORE_CONTENT_LENGTH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTP_VERSION (3) + - CURLOPT_MAXFILESIZE_LARGE (3) +--- + +# NAME + +CURLOPT_IGNORE_CONTENT_LENGTH - ignore content length + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IGNORE_CONTENT_LENGTH, + long ignore); +~~~ + +# DESCRIPTION + +If *ignore* is set to 1L, ignore the Content-Length header in the HTTP +response and ignore asking for or relying on it for FTP transfers. + +This is useful for doing HTTP transfers with ancient web servers which report +incorrect content length for files over 2 gigabytes. If this option is used, +curl cannot accurately report progress, and it instead stops the download when +the server ends the connection. + +It is also useful with FTP when for example the file is growing while the +transfer is in progress which otherwise unconditionally causes libcurl to +report error. + +Only use this option if strictly necessary. + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* we know the server is silly, ignore content-length */ + curl_easy_setopt(curl, CURLOPT_IGNORE_CONTENT_LENGTH, 1L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.14.1. Support for FTP added in 7.46.0. This option is not working +for HTTP when libcurl is built to use the hyper backend. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 deleted file mode 100644 index a26e46302d9..00000000000 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE.3 +++ /dev/null @@ -1,87 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_INFILESIZE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_INFILESIZE \- size of the input file to send off -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE, long filesize); -.fi -.SH DESCRIPTION -When uploading a file to a remote site, \fIfilesize\fP should be used to tell -libcurl what the expected size of the input file is. This value must be passed -as a long. See also \fICURLOPT_INFILESIZE_LARGE(3)\fP for sending files larger -than 2GB. - -For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE(3)\fP is -mandatory. - -To unset this value again, set it to -1. - -Using \fICURLOPT_UPLOAD(3)\fP to a HTTP/1.1 server and this value set to -1, -makes libcurl do a chunked transfer-encoded upload. - -When sending emails using SMTP, this command can be used to specify the -optional SIZE parameter for the MAIL FROM command. - -This option does not limit how much data libcurl actually sends, as that is -controlled entirely by what the read callback returns, but telling one value -and sending a different amount may lead to errors. -.SH DEFAULT -Unset -.SH PROTOCOLS -Many -.SH EXAMPLE -.nf - -#define FILE_SIZE 12345L - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - long uploadsize = FILE_SIZE; - - curl_easy_setopt(curl, CURLOPT_URL, - "ftp://example.com/destination.tar.gz"); - - curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); - - curl_easy_setopt(curl, CURLOPT_INFILESIZE, uploadsize); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -SMTP support added in 7.23.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3), -.BR CURLOPT_INFILESIZE_LARGE (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.md b/docs/libcurl/opts/CURLOPT_INFILESIZE.md new file mode 100644 index 00000000000..8098f6d908a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE.md @@ -0,0 +1,85 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_INFILESIZE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONTENT_LENGTH_UPLOAD_T (3) + - CURLOPT_INFILESIZE_LARGE (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_INFILESIZE - size of the input file to send off + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE, long filesize); +~~~ + +# DESCRIPTION + +When uploading a file to a remote site, *filesize* should be used to tell +libcurl what the expected size of the input file is. This value must be passed +as a long. See also CURLOPT_INFILESIZE_LARGE(3) for sending files larger +than 2GB. + +For uploading using SCP, this option or CURLOPT_INFILESIZE_LARGE(3) is +mandatory. + +To unset this value again, set it to -1. + +Using CURLOPT_UPLOAD(3) to a HTTP/1.1 server and this value set to -1, +makes libcurl do a chunked transfer-encoded upload. + +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. + +This option does not limit how much data libcurl actually sends, as that is +controlled entirely by what the read callback returns, but telling one value +and sending a different amount may lead to errors. + +# DEFAULT + +Unset + +# PROTOCOLS + +Many + +# EXAMPLE + +~~~c + +#define FILE_SIZE 12345L + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + long uploadsize = FILE_SIZE; + + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/destination.tar.gz"); + + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + curl_easy_setopt(curl, CURLOPT_INFILESIZE, uploadsize); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +SMTP support added in 7.23.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 deleted file mode 100644 index 5cac9108936..00000000000 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_INFILESIZE_LARGE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_INFILESIZE_LARGE \- size of the input file to send off -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE_LARGE, - curl_off_t filesize); -.SH DESCRIPTION -When uploading a file to a remote site, \fIfilesize\fP should be used to tell -libcurl what the expected size of the input file is. This value must be passed -as a \fBcurl_off_t\fP. - -For uploading using SCP, this option or \fICURLOPT_INFILESIZE(3)\fP is -mandatory. - -To unset this value again, set it to -1. - -When sending emails using SMTP, this command can be used to specify the -optional SIZE parameter for the MAIL FROM command. - -This option does not limit how much data libcurl actually sends, as that is -controlled entirely by what the read callback returns, but telling one value -and sending a different amount may lead to errors. -.SH DEFAULT -Unset -.SH PROTOCOLS -Many -.SH EXAMPLE -.nf -#define FILE_SIZE 123456 - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_off_t uploadsize = FILE_SIZE; - - curl_easy_setopt(curl, CURLOPT_URL, - "ftp://example.com/destination.tar.gz"); - - curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); - - curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, uploadsize); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -SMTP support added in 7.23.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3), -.BR CURLOPT_INFILESIZE (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md new file mode 100644 index 00000000000..5f8a3386ff8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md @@ -0,0 +1,81 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_INFILESIZE_LARGE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CONTENT_LENGTH_UPLOAD_T (3) + - CURLOPT_INFILESIZE (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_INFILESIZE_LARGE - size of the input file to send off + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE_LARGE, + curl_off_t filesize); +~~~ + +# DESCRIPTION + +When uploading a file to a remote site, *filesize* should be used to tell +libcurl what the expected size of the input file is. This value must be passed +as a **curl_off_t**. + +For uploading using SCP, this option or CURLOPT_INFILESIZE(3) is +mandatory. + +To unset this value again, set it to -1. + +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. + +This option does not limit how much data libcurl actually sends, as that is +controlled entirely by what the read callback returns, but telling one value +and sending a different amount may lead to errors. + +# DEFAULT + +Unset + +# PROTOCOLS + +Many + +# EXAMPLE + +~~~c +#define FILE_SIZE 123456 + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_off_t uploadsize = FILE_SIZE; + + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/destination.tar.gz"); + + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, uploadsize); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +SMTP support added in 7.23.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.3 b/docs/libcurl/opts/CURLOPT_INTERFACE.3 deleted file mode 100644 index 676f8ba7c93..00000000000 --- a/docs/libcurl/opts/CURLOPT_INTERFACE.3 +++ /dev/null @@ -1,85 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_INTERFACE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_INTERFACE \- source interface for outgoing traffic -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERFACE, char *interface); -.fi -.SH DESCRIPTION -Pass a char * as parameter. This sets the \fIinterface\fP name to use as -outgoing network interface. The name can be an interface name, an IP address, -or a host name. - -If the parameter starts with "if!" then it is treated only as an interface -name. If the parameter starts with \&"host!" it is treated as either an IP -address or a hostname. - -If "if!" is specified but the parameter does not match an existing interface, -\fICURLE_INTERFACE_FAILED\fP is returned from the libcurl function used to -perform the transfer. - -libcurl does not support using network interface names for this option on -Windows. - -We strongly advise against specifying the interface with a hostname, as it -causes libcurl to do a blocking name resolve call to retrieve the IP -address. That name resolve operation does \fBnot\fP use DNS-over-HTTPS even if -\fICURLOPT_DOH_URL(3)\fP is set. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL, use whatever the TCP stack finds suitable -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - curl_easy_setopt(curl, CURLOPT_INTERFACE, "eth0"); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -The "if!" and "host!" syntax was added in 7.24.0. -.SH RETURN VALUE -Returns CURLE_OK on success or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SOCKOPTFUNCTION (3), -.BR CURLOPT_TCP_NODELAY (3) diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.md b/docs/libcurl/opts/CURLOPT_INTERFACE.md new file mode 100644 index 00000000000..39d5c241c49 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INTERFACE.md @@ -0,0 +1,83 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_INTERFACE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SOCKOPTFUNCTION (3) + - CURLOPT_TCP_NODELAY (3) +--- + +# NAME + +CURLOPT_INTERFACE - source interface for outgoing traffic + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERFACE, char *interface); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter. This sets the *interface* name to use as +outgoing network interface. The name can be an interface name, an IP address, +or a host name. + +If the parameter starts with "if!" then it is treated only as an interface +name. If the parameter starts with &"host!" it is treated as either an IP +address or a hostname. + +If "if!" is specified but the parameter does not match an existing interface, +*CURLE_INTERFACE_FAILED* is returned from the libcurl function used to +perform the transfer. + +libcurl does not support using network interface names for this option on +Windows. + +We strongly advise against specifying the interface with a hostname, as it +causes libcurl to do a blocking name resolve call to retrieve the IP +address. That name resolve operation does **not** use DNS-over-HTTPS even if +CURLOPT_DOH_URL(3) is set. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL, use whatever the TCP stack finds suitable + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_INTERFACE, "eth0"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +The "if!" and "host!" syntax was added in 7.24.0. + +# RETURN VALUE + +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 deleted file mode 100644 index adc54f69484..00000000000 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_INTERLEAVEDATA 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_INTERLEAVEDATA \- pointer passed to RTSP interleave callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEDATA, void *pointer); -.fi -.SH DESCRIPTION -This is the userdata \fIpointer\fP that is passed to -\fICURLOPT_INTERLEAVEFUNCTION(3)\fP when interleaved RTP data is received. If -the interleave function callback is not set, this pointer is not used -anywhere. -.SH DEFAULT -NULL -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -struct local { - void *custom; -}; -static size_t rtp_write(void *ptr, size_t size, size_t nmemb, void *userp) -{ - struct local *l = userp; - printf("my pointer: %p\\n", l->custom); - /* take care of the packet in 'ptr', then return... */ - return size * nmemb; -} - -int main(void) -{ - struct local rtp_data; - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write); - curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_INTERLEAVEFUNCTION (3), -.BR CURLOPT_RTSP_REQUEST (3) diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md new file mode 100644 index 00000000000..64311f83cc2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_INTERLEAVEDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_INTERLEAVEFUNCTION (3) + - CURLOPT_RTSP_REQUEST (3) +--- + +# NAME + +CURLOPT_INTERLEAVEDATA - pointer passed to RTSP interleave callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEDATA, void *pointer); +~~~ + +# DESCRIPTION + +This is the userdata *pointer* that is passed to +CURLOPT_INTERLEAVEFUNCTION(3) when interleaved RTP data is received. If +the interleave function callback is not set, this pointer is not used +anywhere. + +# DEFAULT + +NULL + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +struct local { + void *custom; +}; +static size_t rtp_write(void *ptr, size_t size, size_t nmemb, void *userp) +{ + struct local *l = userp; + printf("my pointer: %p\n", l->custom); + /* take care of the packet in 'ptr', then return... */ + return size * nmemb; +} + +int main(void) +{ + struct local rtp_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write); + curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md similarity index 54% rename from docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md index b2fa947dd1d..5f8e999df94 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md @@ -1,32 +1,21 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_INTERLEAVEFUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_INTERLEAVEFUNCTION \- callback for RTSP interleaved data -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_INTERLEAVEFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_INTERLEAVEDATA (3) + - CURLOPT_RTSP_REQUEST (3) +--- + +# NAME + +CURLOPT_INTERLEAVEFUNCTION - callback for RTSP interleaved data + +# SYNOPSIS + +~~~c #include size_t interleave_callback(void *ptr, size_t size, size_t nmemb, @@ -34,13 +23,16 @@ size_t interleave_callback(void *ptr, size_t size, size_t nmemb, CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEFUNCTION, interleave_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl as soon as it has received interleaved RTP data. This function gets called for each $ block and therefore -contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl +contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the interleaved header as well as the included data for each call. The first byte is always an ASCII dollar sign. The dollar sign is followed by a one byte channel identifier and then a 2 byte integer length in network byte @@ -51,27 +43,33 @@ Interleaved RTP poses some challenges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service the RTP in a timely fashion. If the RTP data is not handled quickly, subsequent response processing may become unreasonably delayed and the -connection may close. The application may use \fICURL_RTSPREQ_RECEIVE\fP to +connection may close. The application may use *CURL_RTSPREQ_RECEIVE* to service RTP data when no requests are desired. If the application makes a -request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler processes +request, (e.g. *CURL_RTSPREQ_PAUSE*) then the response handler processes any pending RTP data before marking the request as finished. -The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in +The CURLOPT_INTERLEAVEDATA(3) is passed in the *userdata* argument in the callback. Your callback should return the number of bytes actually taken care of. If that amount differs from the amount passed to your callback function, it signals an error condition to the library. This causes the transfer to abort -and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. +and the libcurl function used returns *CURLE_WRITE_ERROR*. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) -.SH DEFAULT + +# DEFAULT + NULL, the interleave data is then passed to the regular write function: -\fICURLOPT_WRITEFUNCTION(3)\fP. -.SH PROTOCOLS +CURLOPT_WRITEFUNCTION(3). + +# PROTOCOLS + RTSP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c struct local { void *custom; }; @@ -79,7 +77,7 @@ struct local { static size_t rtp_write(void *ptr, size_t size, size_t nmemb, void *userp) { struct local *l = userp; - printf("our ptr: %p\\n", l->custom); + printf("our ptr: %p\n", l->custom); /* take care of the packet in 'ptr', then return... */ return size * nmemb; } @@ -93,11 +91,12 @@ int main(void) curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.20.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_INTERLEAVEDATA (3), -.BR CURLOPT_RTSP_REQUEST (3) diff --git a/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 b/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 deleted file mode 100644 index 93742c75ee0..00000000000 --- a/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_IOCTLDATA 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_IOCTLDATA \- pointer passed to I/O callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass the \fIpointer\fP that is untouched by libcurl and passed as the 3rd -argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION(3)\fP. -.SH DEFAULT -By default, the value of this parameter is NULL. -.SH PROTOCOLS -Used with HTTP -.SH EXAMPLE -.nf -#include /* for lseek */ - -struct data { - int fd; /* our file descriptor */ -}; - -static curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp) -{ - struct data *io = (struct data *)clientp; - if(cmd == CURLIOCMD_RESTARTREAD) { - lseek(io->fd, 0, SEEK_SET); - return CURLIOE_OK; - } - return CURLIOE_UNKNOWNCMD; -} -int main(void) -{ - struct data ioctl_data; - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback); - curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data); - } -} -.fi -.SH AVAILABILITY -Added in 7.12.3. Deprecated since 7.18.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_IOCTLFUNCTION (3), -.BR CURLOPT_SEEKFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_IOCTLDATA.md b/docs/libcurl/opts/CURLOPT_IOCTLDATA.md new file mode 100644 index 00000000000..2490fbc7fcb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_IOCTLDATA.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_IOCTLDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_IOCTLFUNCTION (3) + - CURLOPT_SEEKFUNCTION (3) +--- + +# NAME + +CURLOPT_IOCTLDATA - pointer passed to I/O callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLDATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass the *pointer* that is untouched by libcurl and passed as the 3rd +argument in the ioctl callback set with CURLOPT_IOCTLFUNCTION(3). + +# DEFAULT + +By default, the value of this parameter is NULL. + +# PROTOCOLS + +Used with HTTP + +# EXAMPLE + +~~~c +#include /* for lseek */ + +struct data { + int fd; /* our file descriptor */ +}; + +static curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp) +{ + struct data *io = (struct data *)clientp; + if(cmd == CURLIOCMD_RESTARTREAD) { + lseek(io->fd, 0, SEEK_SET); + return CURLIOE_OK; + } + return CURLIOE_UNKNOWNCMD; +} +int main(void) +{ + struct data ioctl_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback); + curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data); + } +} +~~~ + +# AVAILABILITY + +Added in 7.12.3. Deprecated since 7.18.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md similarity index 50% rename from docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md index 98105147257..8804ae57845 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md @@ -1,32 +1,21 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_IOCTLFUNCTION 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_IOCTLFUNCTION \- callback for I/O operations -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_IOCTLFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_IOCTLDATA (3) + - CURLOPT_SEEKFUNCTION (3) +--- + +# NAME + +CURLOPT_IOCTLFUNCTION - callback for I/O operations + +# SYNOPSIS + +~~~c #include typedef enum { @@ -45,7 +34,10 @@ typedef enum { curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLFUNCTION, ioctl_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. @@ -55,21 +47,27 @@ rewinding the read data stream is the only action it can request. The rewinding of the read data stream may be necessary when doing an HTTP PUT or POST with a multi-pass authentication method. -The callback MUST return \fICURLIOE_UNKNOWNCMD\fP if the input \fIcmd\fP is -not \fICURLIOCMD_RESTARTREAD\fP. +The callback MUST return *CURLIOE_UNKNOWNCMD* if the input *cmd* is +not *CURLIOCMD_RESTARTREAD*. -The \fIclientp\fP argument to the callback is set with the -\fICURLOPT_IOCTLDATA(3)\fP option. +The *clientp* argument to the callback is set with the +CURLOPT_IOCTLDATA(3) option. -This option is deprecated! Do not use it. Use \fICURLOPT_SEEKFUNCTION(3)\fP -instead to provide seeking! If \fICURLOPT_SEEKFUNCTION(3)\fP is set, this +**This option is deprecated**. Do not use it. Use CURLOPT_SEEKFUNCTION(3) +instead to provide seeking! If CURLOPT_SEEKFUNCTION(3) is set, this parameter is ignored when seeking. -.SH DEFAULT + +# DEFAULT + By default, this parameter is set to NULL. Not used. -.SH PROTOCOLS + +# PROTOCOLS + Used with HTTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c #include /* for lseek */ struct data { @@ -94,11 +92,12 @@ int main(void) curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.12.3. Deprecated since 7.18.0. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_IOCTLDATA (3), -.BR CURLOPT_SEEKFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 deleted file mode 100644 index 499aed5138b..00000000000 --- a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_IPRESOLVE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_IPRESOLVE \- IP protocol version to use -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IPRESOLVE, long resolve); -.fi -.SH DESCRIPTION -Allows an application to select what kind of IP addresses to use when -establishing a connection or choosing one from the connection pool. This is -interesting when using host names that resolve to more than one IP family. - -If the URL provided for a transfer contains a numerical IP version as a host -name, this option does not override or prohibit libcurl from using that IP -version. - -Available values for this option are: -.IP CURL_IPRESOLVE_WHATEVER -Default, can use addresses of all IP versions that your system allows. -.IP CURL_IPRESOLVE_V4 -Uses only IPv4 addresses. -.IP CURL_IPRESOLVE_V6 -Uses only IPv6 addresses. -.SH DEFAULT -CURL_IPRESOLVE_WHATEVER -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - /* of all addresses example.com resolves to, only IPv6 ones are used */ - curl_easy_setopt(curl, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V6); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_HTTP_VERSION (3), -.BR CURLOPT_RESOLVE (3), -.BR CURLOPT_SSLVERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md new file mode 100644 index 00000000000..7d06405ecdd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md @@ -0,0 +1,83 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_IPRESOLVE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTP_VERSION (3) + - CURLOPT_RESOLVE (3) + - CURLOPT_SSLVERSION (3) +--- + +# NAME + +CURLOPT_IPRESOLVE - IP protocol version to use + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IPRESOLVE, long resolve); +~~~ + +# DESCRIPTION + +Allows an application to select what kind of IP addresses to use when +establishing a connection or choosing one from the connection pool. This is +interesting when using host names that resolve to more than one IP family. + +If the URL provided for a transfer contains a numerical IP version as a host +name, this option does not override or prohibit libcurl from using that IP +version. + +Available values for this option are: + +## CURL_IPRESOLVE_WHATEVER + +Default, can use addresses of all IP versions that your system allows. + +## CURL_IPRESOLVE_V4 + +Uses only IPv4 addresses. + +## CURL_IPRESOLVE_V6 + +Uses only IPv6 addresses. + +# DEFAULT + +CURL_IPRESOLVE_WHATEVER + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + /* of all addresses example.com resolves to, only IPv6 ones are used */ + curl_easy_setopt(curl, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V6); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 b/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 deleted file mode 100644 index a0c2f5f7965..00000000000 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ISSUERCERT 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_ISSUERCERT \- issuer SSL certificate filename -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT, char *file); -.fi -.SH DESCRIPTION -Pass a char * to a null-terminated string naming a \fIfile\fP holding a CA -certificate in PEM format. If the option is set, an additional check against -the peer certificate is performed to verify the issuer is indeed the one -associated with the certificate provided by the option. This additional check -is useful in multi-level PKI where one needs to enforce that the peer -certificate is from a specific branch of the tree. - -This option makes sense only when used in combination with the -\fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is -not considered as failure. - -A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, -which is returned if the setup of the SSL/TLS session has failed due to a -mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP -has to be set too for the check to fail). (Added in 7.19.0) - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS-based protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_ISSUERCERT, "/etc/certs/cacert.pem"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -If built TLS enabled -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_CRLFILE (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md new file mode 100644 index 00000000000..9b35d5d79c6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ISSUERCERT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CRLFILE (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_ISSUERCERT - issuer SSL certificate filename + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT, char *file); +~~~ + +# DESCRIPTION + +Pass a char pointer to a null-terminated string naming a *file* holding a CA +certificate in PEM format. If the option is set, an additional check against +the peer certificate is performed to verify the issuer is indeed the one +associated with the certificate provided by the option. This additional check +is useful in multi-level PKI where one needs to enforce that the peer +certificate is from a specific branch of the tree. + +This option makes sense only when used in combination with the +CURLOPT_SSL_VERIFYPEER(3) option. Otherwise, the result of the check is +not considered as failure. + +A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, +which is returned if the setup of the SSL/TLS session has failed due to a +mismatch with the issuer of peer certificate (CURLOPT_SSL_VERIFYPEER(3) +has to be set too for the check to fail). (Added in 7.19.0) + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS-based protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_ISSUERCERT, "/etc/certs/cacert.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +If built TLS enabled + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.3 b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md similarity index 50% rename from docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.3 rename to docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md index 858987e9b2b..8f68aedbc4c 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md @@ -1,38 +1,31 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_ISSUERCERT_BLOB 3 "24 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_ISSUERCERT_BLOB \- issuer SSL certificate from memory blob -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_ISSUERCERT_BLOB +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CRLFILE (3) + - CURLOPT_ISSUERCERT (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_ISSUERCERT_BLOB - issuer SSL certificate from memory blob + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT_BLOB, struct curl_blob *stblob); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a curl_blob structure, which contains information (pointer and size) about a memory block with binary data of a CA certificate in PEM format. If the option is set, an additional check against the peer certificate @@ -42,26 +35,32 @@ multi-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree. This option should be used in combination with the -\fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is +CURLOPT_SSL_VERIFYPEER(3) option. Otherwise, the result of the check is not considered as failure. A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, which is returned if the setup of the SSL/TLS session has failed due to a -mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP +mismatch with the issuer of peer certificate (CURLOPT_SSL_VERIFYPEER(3) has to be set too for the check to fail). If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. -This option is an alternative to \fICURLOPT_ISSUERCERT(3)\fP which instead +This option is an alternative to CURLOPT_ISSUERCERT(3) which instead expects a file name as input. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All TLS-based protocols -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c extern char *certificateData; extern size_t filesize; @@ -81,14 +80,13 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.71.0. This option is supported by the OpenSSL backends. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_ISSUERCERT (3), -.BR CURLOPT_CRLFILE (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 deleted file mode 100644 index 4664360953c..00000000000 --- a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_KEEP_SENDING_ON_ERROR 3 "22 Sep 2016" libcurl libcurl -.SH NAME -CURLOPT_KEEP_SENDING_ON_ERROR \- keep sending on early HTTP response >= 300 -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEEP_SENDING_ON_ERROR, - long keep_sending); -.fi -.SH DESCRIPTION -A long parameter set to 1 tells the library to keep sending the request body -if the HTTP code returned is equal to or larger than 300. The default action -would be to stop sending and close the stream or connection. - -This option is suitable for manual NTLM authentication, i.e. if an application -does not use \fICURLOPT_HTTPAUTH(3)\fP, but instead sets "Authorization: NTLM ..." -headers manually using \fICURLOPT_HTTPHEADER(3)\fP. - -Most applications do not need this option. -.SH DEFAULT -0, stop sending on error -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "sending data"); - curl_easy_setopt(curl, CURLOPT_KEEP_SENDING_ON_ERROR, 1L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP. Added in 7.51.0. -.SH RETURN VALUE -Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_RESPONSE_CODE (3), -.BR CURLOPT_FAILONERROR (3), -.BR CURLOPT_HTTPHEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md new file mode 100644 index 00000000000..090a8fc2d20 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_KEEP_SENDING_ON_ERROR +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RESPONSE_CODE (3) + - CURLOPT_FAILONERROR (3) + - CURLOPT_HTTPHEADER (3) +--- + +# NAME + +CURLOPT_KEEP_SENDING_ON_ERROR - keep sending on early HTTP response >= 300 + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEEP_SENDING_ON_ERROR, + long keep_sending); +~~~ + +# DESCRIPTION + +A long parameter set to 1 tells the library to keep sending the request body +if the HTTP code returned is equal to or larger than 300. The default action +would be to stop sending and close the stream or connection. + +This option is suitable for manual NTLM authentication, i.e. if an application +does not use CURLOPT_HTTPAUTH(3), but instead sets "Authorization: NTLM ..." +headers manually using CURLOPT_HTTPHEADER(3). + +Most applications do not need this option. + +# DEFAULT + +0, stop sending on error + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "sending data"); + curl_easy_setopt(curl, CURLOPT_KEEP_SENDING_ON_ERROR, 1L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP. Added in 7.51.0. + +# RETURN VALUE + +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 b/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 deleted file mode 100644 index 119f26cd163..00000000000 --- a/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_KEYPASSWD 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_KEYPASSWD \- passphrase to private key -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEYPASSWD, char *pwd); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It is used as the -password required to use the \fICURLOPT_SSLKEY(3)\fP or -\fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP private key. You never need a pass -phrase to load a certificate but you need one to load your private key. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "superman"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and -CURLOPT_SSLCERTPASSWD up to 7.9.2. -.SH RETURN VALUE -Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSH_PRIVATE_KEYFILE (3), -.BR CURLOPT_SSLKEY (3) diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md new file mode 100644 index 00000000000..7407f093934 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_KEYPASSWD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_PRIVATE_KEYFILE (3) + - CURLOPT_SSLKEY (3) +--- + +# NAME + +CURLOPT_KEYPASSWD - passphrase to private key + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEYPASSWD, char *pwd); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. It is used as the +password required to use the CURLOPT_SSLKEY(3) or +CURLOPT_SSH_PRIVATE_KEYFILE(3) private key. You never need a pass phrase to +load a certificate but you need one to load your private key. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "superman"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and +CURLOPT_SSLCERTPASSWD up to 7.9.2. + +# RETURN VALUE + +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 b/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 deleted file mode 100644 index 7be711e1d00..00000000000 --- a/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_KRBLEVEL 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_KRBLEVEL \- FTP kerberos security level -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KRBLEVEL, char *level); -.fi -.SH DESCRIPTION -Pass a char * as parameter. Set the kerberos security level for FTP; this also -enables kerberos awareness. This is a string that should match one of the -following: \&'clear', \&'safe', \&'confidential' or \&'private'. If the string -is set but does not match one of these, 'private' is used. Set the string to -NULL to disable kerberos support for FTP. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_KRBLEVEL, "private"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option was known as CURLOPT_KRB4LEVEL up to 7.16.3 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_KRBLEVEL (3), -.BR CURLOPT_USE_SSL (3) diff --git a/docs/libcurl/opts/CURLOPT_KRBLEVEL.md b/docs/libcurl/opts/CURLOPT_KRBLEVEL.md new file mode 100644 index 00000000000..cb8e276891d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_KRBLEVEL.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_KRBLEVEL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_KRBLEVEL (3) + - CURLOPT_USE_SSL (3) +--- + +# NAME + +CURLOPT_KRBLEVEL - FTP kerberos security level + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KRBLEVEL, char *level); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter. Set the kerberos security level for FTP; +this also enables kerberos awareness. This is a string that should match one +of the following: &'clear', &'safe', &'confidential' or &'private'. If the +string is set but does not match one of these, 'private' is used. Set the +string to NULL to disable kerberos support for FTP. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_KRBLEVEL, "private"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option was known as CURLOPT_KRB4LEVEL up to 7.16.3 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORT.3 b/docs/libcurl/opts/CURLOPT_LOCALPORT.3 deleted file mode 100644 index e5bddf1c13a..00000000000 --- a/docs/libcurl/opts/CURLOPT_LOCALPORT.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_LOCALPORT 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_LOCALPORT \- local port number to use for socket -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORT, long port); -.fi -.SH DESCRIPTION -Pass a long. This sets the local port number of the socket used for the -connection. This can be used in combination with \fICURLOPT_INTERFACE(3)\fP -and you are recommended to use \fICURLOPT_LOCALPORTRANGE(3)\fP as well when -this option is set. Valid port numbers are 1 - 65535. -.SH DEFAULT -0, disabled - use whatever the system thinks is fine -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L); - /* and try 20 more ports following that */ - curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.2 -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLINFO_LOCAL_PORT (3), -.BR CURLOPT_INTERFACE (3), -.BR CURLOPT_LOCALPORTRANGE (3) diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORT.md b/docs/libcurl/opts/CURLOPT_LOCALPORT.md new file mode 100644 index 00000000000..25a21c15e5e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOCALPORT.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_LOCALPORT +Section: 3 +Source: libcurl +See-also: + - CURLINFO_LOCAL_PORT (3) + - CURLOPT_INTERFACE (3) + - CURLOPT_LOCALPORTRANGE (3) +--- + +# NAME + +CURLOPT_LOCALPORT - local port number to use for socket + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORT, long port); +~~~ + +# DESCRIPTION + +Pass a long. This sets the local port number of the socket used for the +connection. This can be used in combination with CURLOPT_INTERFACE(3) +and you are recommended to use CURLOPT_LOCALPORTRANGE(3) as well when +this option is set. Valid port numbers are 1 - 65535. + +# DEFAULT + +0, disabled - use whatever the system thinks is fine + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L); + /* and try 20 more ports following that */ + curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.2 + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 deleted file mode 100644 index 71934e32358..00000000000 --- a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_LOCALPORTRANGE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_LOCALPORTRANGE \- number of additional local ports to try -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORTRANGE, - long range); -.fi -.SH DESCRIPTION -Pass a long. The \fIrange\fP argument is the number of attempts libcurl makes -to find a working local port number. It starts with the given -\fICURLOPT_LOCALPORT(3)\fP and adds one to the number for each retry. Setting -this option to 1 or below makes libcurl only do one try for the exact port -number. Port numbers by nature are scarce resources that are busy at times so -setting this value to something too low might cause unnecessary connection -setup failures. -.SH DEFAULT -1 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L); - /* and try 20 more ports following that */ - curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.2 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_INTERFACE (3), -.BR CURLOPT_LOCALPORT (3) diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md new file mode 100644 index 00000000000..52002079089 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_LOCALPORTRANGE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_INTERFACE (3) + - CURLOPT_LOCALPORT (3) +--- + +# NAME + +CURLOPT_LOCALPORTRANGE - number of additional local ports to try + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORTRANGE, + long range); +~~~ + +# DESCRIPTION + +Pass a long. The *range* argument is the number of attempts libcurl makes +to find a working local port number. It starts with the given +CURLOPT_LOCALPORT(3) and adds one to the number for each retry. Setting +this option to 1 or below makes libcurl only do one try for the exact port +number. Port numbers by nature are scarce resources that are busy at times so +setting this value to something too low might cause unnecessary connection +setup failures. + +# DEFAULT + +1 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L); + /* and try 20 more ports following that */ + curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.2 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 deleted file mode 100644 index 5410bbdce99..00000000000 --- a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_LOGIN_OPTIONS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_LOGIN_OPTIONS \- login options -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOGIN_OPTIONS, char *options); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should be pointing to the null-terminated -\fIoptions\fP string to use for the transfer. - -For more information about the login options please see RFC 2384, RFC 5092 and -the IETF draft \fBdraft-earhart-url-smtp-00.txt\fP. - -\fICURLOPT_LOGIN_OPTIONS(3)\fP can be used to set protocol specific login -options, such as the preferred authentication mechanism via "AUTH=NTLM" or -"AUTH=*", and should be used in conjunction with the \fICURLOPT_USERNAME(3)\fP -option. - -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 in plain text. This does not work if the IMAP server -disables the plain LOGIN (e.g. to prevent password snooping). - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -Only IMAP, LDAP, POP3 and SMTP support login options. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); - curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=*"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.34.0. Support for OpenLDAP added in 7.82.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PASSWORD (3), -.BR CURLOPT_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md new file mode 100644 index 00000000000..a57b446902b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_LOGIN_OPTIONS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PASSWORD (3) + - CURLOPT_USERNAME (3) +--- + +# NAME + +CURLOPT_LOGIN_OPTIONS - login options + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOGIN_OPTIONS, char *options); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should be pointing to the +null-terminated *options* string to use for the transfer. + +For more information about the login options please see RFC 2384, RFC 5092 and +the IETF draft **draft-earhart-url-smtp-00.txt**. + +CURLOPT_LOGIN_OPTIONS(3) can be used to set protocol specific login options, +such as the preferred authentication mechanism via "AUTH=NTLM" or "AUTH=*", +and should be used in conjunction with the CURLOPT_USERNAME(3) option. + +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 in plain text. This does not work if the IMAP server +disables the plain LOGIN (e.g. to prevent password snooping). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +Only IMAP, LDAP, POP3 and SMTP support login options. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=*"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.34.0. Support for OpenLDAP added in 7.82.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 deleted file mode 100644 index d491e655b71..00000000000 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_LOW_SPEED_LIMIT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_LOW_SPEED_LIMIT \- low speed limit in bytes per second -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_LIMIT, - long speedlimit); -.fi -.SH DESCRIPTION -Pass a long as parameter. It contains the average transfer speed in bytes per -second that the transfer should be below during -\fICURLOPT_LOW_SPEED_TIME(3)\fP seconds for libcurl to consider it to be too -slow and abort. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* abort if slower than 30 bytes/sec during 60 seconds */ - curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L); - curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L); - res = curl_easy_perform(curl); - if(CURLE_OPERATION_TIMEDOUT == res) { - printf("Timeout!\\n"); - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_LOW_SPEED_TIME (3), -.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), -.BR CURLOPT_MAX_SEND_SPEED_LARGE (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md new file mode 100644 index 00000000000..99df9faed10 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_LOW_SPEED_LIMIT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_LOW_SPEED_TIME (3) + - CURLOPT_MAX_RECV_SPEED_LARGE (3) + - CURLOPT_MAX_SEND_SPEED_LARGE (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_LOW_SPEED_LIMIT - low speed limit in bytes per second + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_LIMIT, + long speedlimit); +~~~ + +# DESCRIPTION + +Pass a long as parameter. It contains the average transfer speed in bytes per +second that the transfer should be below during +CURLOPT_LOW_SPEED_TIME(3) seconds for libcurl to consider it to be too +slow and abort. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* abort if slower than 30 bytes/sec during 60 seconds */ + curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L); + curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L); + res = curl_easy_perform(curl); + if(CURLE_OPERATION_TIMEDOUT == res) { + printf("Timeout!\n"); + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 deleted file mode 100644 index 507ac452862..00000000000 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_LOW_SPEED_TIME 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_LOW_SPEED_TIME \- low speed limit time period -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_TIME, - long speedtime); -.fi -.SH DESCRIPTION -Pass a long as parameter. It contains the time in number seconds that the -transfer speed should be below the \fICURLOPT_LOW_SPEED_LIMIT(3)\fP for the -library to consider it too slow and abort. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* abort if slower than 30 bytes/sec during 60 seconds */ - curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L); - curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L); - res = curl_easy_perform(curl); - if(CURLE_OPERATION_TIMEDOUT == res) { - printf("Timeout!\\n"); - } - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md new file mode 100644 index 00000000000..a3a9ef1ffef --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_LOW_SPEED_TIME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_LOW_SPEED_TIME - low speed limit time period + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_TIME, + long speedtime); +~~~ + +# DESCRIPTION + +Pass a long as parameter. It contains the time in number seconds that the +transfer speed should be below the CURLOPT_LOW_SPEED_LIMIT(3) for the +library to consider it too slow and abort. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* abort if slower than 30 bytes/sec during 60 seconds */ + curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L); + curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L); + res = curl_easy_perform(curl); + if(CURLE_OPERATION_TIMEDOUT == res) { + printf("Timeout!\n"); + } + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 deleted file mode 100644 index 340d801d848..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAIL_AUTH 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAIL_AUTH \- SMTP authentication address -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_AUTH, char *auth); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. This is used to -specify the authentication address (identity) of a submitted message that is -being relayed to another server. - -This optional parameter allows co-operating agents in a trusted environment to -communicate the authentication of individual messages and should only be used -by the application program, using libcurl, if the application is itself a mail -server acting in such an environment. If the application is operating as such -and the AUTH address is not known or is invalid, then an empty string should -be used for this parameter. - -Unlike \fICURLOPT_MAIL_FROM(3)\fP and \fICURLOPT_MAIL_RCPT(3)\fP, the address -should not be specified within a pair of angled brackets (<>). However, if an -empty string is used then a pair of brackets are sent by libcurl as required -by RFC 2554. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); - curl_easy_setopt(curl, CURLOPT_MAIL_AUTH, ""); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.25.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_MAIL_FROM (3), -.BR CURLOPT_MAIL_RCPT (3) diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md new file mode 100644 index 00000000000..a5dbc7d79f6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAIL_AUTH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAIL_FROM (3) + - CURLOPT_MAIL_RCPT (3) +--- + +# NAME + +CURLOPT_MAIL_AUTH - SMTP authentication address + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_AUTH, char *auth); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. This is used to +specify the authentication address (identity) of a submitted message that is +being relayed to another server. + +This optional parameter allows co-operating agents in a trusted environment to +communicate the authentication of individual messages and should only be used +by the application program, using libcurl, if the application is itself a mail +server acting in such an environment. If the application is operating as such +and the AUTH address is not known or is invalid, then an empty string should +be used for this parameter. + +Unlike CURLOPT_MAIL_FROM(3) and CURLOPT_MAIL_RCPT(3), the address +should not be specified within a pair of angled brackets (<>). However, if an +empty string is used then a pair of brackets are sent by libcurl as required +by RFC 2554. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_MAIL_AUTH, ""); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.25.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 b/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 deleted file mode 100644 index b76455c61ed..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAIL_FROM 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAIL_FROM \- SMTP sender address -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_FROM, char *from); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. This should be used -to specify the sender's email address when sending SMTP mail with libcurl. - -An originator email address should be specified with angled brackets (<>) -around it, which if not specified are added automatically. - -If this parameter is not specified then an empty address is sent to the SMTP -server which might cause the email to be rejected. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -blank -.SH PROTOCOLS -SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); - curl_easy_setopt(curl, CURLOPT_MAIL_FROM, "president@example.com"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_MAIL_AUTH (3), -.BR CURLOPT_MAIL_RCPT (3) diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md new file mode 100644 index 00000000000..c4984b056a2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAIL_FROM +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAIL_AUTH (3) + - CURLOPT_MAIL_RCPT (3) +--- + +# NAME + +CURLOPT_MAIL_FROM - SMTP sender address + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_FROM, char *from); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. This should be used +to specify the sender's email address when sending SMTP mail with libcurl. + +An originator email address should be specified with angled brackets (<>) +around it, which if not specified are added automatically. + +If this parameter is not specified then an empty address is sent to the SMTP +server which might cause the email to be rejected. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +blank + +# PROTOCOLS + +SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_MAIL_FROM, "president@example.com"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 deleted file mode 100644 index 5a47e3d9a6b..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAIL_RCPT 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAIL_RCPT \- list of SMTP mail recipients -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT, - struct curl_slist *rcpts); -.SH DESCRIPTION -Pass a pointer to a linked list of recipients to pass to the server in your -SMTP mail request. The linked list should be a fully valid list of -\fBstruct curl_slist\fP structs properly filled in. Use -\fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP -to clean up an entire list. - -When performing a mail transfer, each recipient should be specified within a -pair of angled brackets (<>), however, should you not use an angled bracket as -the first character libcurl assumes you provided a single email address and -encloses that address within brackets for you. - -When performing an address verification (\fBVRFY\fP command), each recipient -should be specified as the user name or user name and domain (as per Section -3.5 of RFC 5321). - -When performing a mailing list expand (\fBEXPN\fP command), each recipient -should be specified using the mailing list name, such as "Friends" or -"London-Office". -.SH DEFAULT -NULL -.SH PROTOCOLS -SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - struct curl_slist *list; - list = curl_slist_append(NULL, "root@localhost"); - list = curl_slist_append(list, "person@example.com"); - curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); - curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, list); - res = curl_easy_perform(curl); - curl_slist_free_all(list); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0. The \fBVRFY\fP and \fBEXPN\fP logic was added in 7.34.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_MAIL_AUTH (3), -.BR CURLOPT_MAIL_FROM (3) diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md new file mode 100644 index 00000000000..ce57074f01d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAIL_RCPT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAIL_AUTH (3) + - CURLOPT_MAIL_FROM (3) +--- + +# NAME + +CURLOPT_MAIL_RCPT - list of SMTP mail recipients + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT, + struct curl_slist *rcpts); +~~~ + +# DESCRIPTION + +Pass a pointer to a linked list of recipients to pass to the server in your +SMTP mail request. The linked list should be a fully valid list of +**struct curl_slist** structs properly filled in. Use +curl_slist_append(3) to create the list and curl_slist_free_all(3) +to clean up an entire list. + +When performing a mail transfer, each recipient should be specified within a +pair of angled brackets (<>), however, should you not use an angled bracket as +the first character libcurl assumes you provided a single email address and +encloses that address within brackets for you. + +When performing an address verification (**VRFY** command), each recipient +should be specified as the user name or user name and domain (as per Section +3.5 of RFC 5321). + +When performing a mailing list expand (**EXPN** command), each recipient +should be specified using the mailing list name, such as "Friends" or +"London-Office". + +# DEFAULT + +NULL + +# PROTOCOLS + +SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_slist *list; + list = curl_slist_append(NULL, "root@localhost"); + list = curl_slist_append(list, "person@example.com"); + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, list); + res = curl_easy_perform(curl); + curl_slist_free_all(list); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0. The **VRFY** and **EXPN** logic was added in 7.34.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 deleted file mode 100644 index bef15148541..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAIL_RCPT_ALLOWFAILS 3 "16 Jan 2020" libcurl libcurl -.SH NAME -CURLOPT_MAIL_RCPT_ALLOWFAILS \- allow RCPT TO command to fail for some recipients -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT_ALLOWFAILS, - long allow); -.SH DESCRIPTION -If \fIallow\fP is set to 1L, allow RCPT TO command to fail for some recipients. - -When sending data to multiple recipients, by default curl aborts the SMTP -conversation if either one of the recipients causes the RCPT TO command to -return an error. - -The default behavior can be changed by setting \fIallow\fP to 1L which makes -libcurl ignore errors for individual recipients and proceed with the remaining -accepted recipients. - -If all recipients trigger RCPT TO failures and this flag is specified, curl -aborts the SMTP conversation and returns the error received from to the last -RCPT TO command. -.SH DEFAULT -0 -.SH PROTOCOLS -SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct curl_slist *list; - CURLcode res; - - /* Adding one valid and one invalid email address */ - list = curl_slist_append(NULL, "person@example.com"); - list = curl_slist_append(list, "invalidemailaddress"); - - curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); - curl_easy_setopt(curl, CURLOPT_MAIL_RCPT_ALLOWFAILS, 1L); - - res = curl_easy_perform(curl); - curl_slist_free_all(list); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -This option was called CURLOPT_MAIL_RCPT_ALLLOWFAILS before 8.2.0 - -Added in 7.69.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_MAIL_FROM (3), -.BR CURLOPT_MAIL_RCPT (3) diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md new file mode 100644 index 00000000000..cf595e26b4b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md @@ -0,0 +1,81 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAIL_RCPT_ALLOWFAILS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAIL_FROM (3) + - CURLOPT_MAIL_RCPT (3) +--- + +# NAME + +CURLOPT_MAIL_RCPT_ALLOWFAILS - allow RCPT TO command to fail for some recipients + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT_ALLOWFAILS, + long allow); +~~~ + +# DESCRIPTION + +If *allow* is set to 1L, allow RCPT TO command to fail for some recipients. + +When sending data to multiple recipients, by default curl aborts the SMTP +conversation if either one of the recipients causes the RCPT TO command to +return an error. + +The default behavior can be changed by setting *allow* to 1L which makes +libcurl ignore errors for individual recipients and proceed with the remaining +accepted recipients. + +If all recipients trigger RCPT TO failures and this flag is specified, curl +aborts the SMTP conversation and returns the error received from to the last +RCPT TO command. + +# DEFAULT + +0 + +# PROTOCOLS + +SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct curl_slist *list; + CURLcode res; + + /* Adding one valid and one invalid email address */ + list = curl_slist_append(NULL, "person@example.com"); + list = curl_slist_append(list, "invalidemailaddress"); + + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_MAIL_RCPT_ALLOWFAILS, 1L); + + res = curl_easy_perform(curl); + curl_slist_free_all(list); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +This option was called CURLOPT_MAIL_RCPT_ALLLOWFAILS before 8.2.0 + +Added in 7.69.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 deleted file mode 100644 index 652792857a5..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAXAGE_CONN 3 "18 Apr 2019" libcurl libcurl -.SH NAME -CURLOPT_MAXAGE_CONN \- max idle time allowed for reusing a connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long age); -.fi -.SH DESCRIPTION -Pass a long as parameter containing \fIage\fP - the maximum time in seconds -allowed for an existing connection to have been idle to be considered for -reuse for this request. - -The "connection cache" holds previously used connections. When a new request -is to be done, libcurl considers any connection that matches for reuse. The -\fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too old -connections for reuse, since old connections have a higher risk of not working -and thus trying them is a performance loss and sometimes service loss due to -the difficulties to figure out the situation. If a connection is found in the -cache that is older than this set \fIage\fP, it is closed instead. -.SH DEFAULT -Default maximum age is set to 118 seconds. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* only allow 30 seconds idle time */ - curl_easy_setopt(curl, CURLOPT_MAXAGE_CONN, 30L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.65.0 -.SH RETURN VALUE -Returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_FORBID_REUSE (3), -.BR CURLOPT_FRESH_CONNECT (3), -.BR CURLOPT_MAXLIFETIME_CONN (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md new file mode 100644 index 00000000000..3d0a9cb2a46 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAXAGE_CONN +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FORBID_REUSE (3) + - CURLOPT_FRESH_CONNECT (3) + - CURLOPT_MAXLIFETIME_CONN (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_MAXAGE_CONN - max idle time allowed for reusing a connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long age); +~~~ + +# DESCRIPTION + +Pass a long as parameter containing *age* - the maximum time in seconds +allowed for an existing connection to have been idle to be considered for +reuse for this request. + +The "connection cache" holds previously used connections. When a new request +is to be done, libcurl considers any connection that matches for reuse. The +CURLOPT_MAXAGE_CONN(3) limit prevents libcurl from trying too old +connections for reuse, since old connections have a higher risk of not working +and thus trying them is a performance loss and sometimes service loss due to +the difficulties to figure out the situation. If a connection is found in the +cache that is older than this set *age*, it is closed instead. + +# DEFAULT + +Default maximum age is set to 118 seconds. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* only allow 30 seconds idle time */ + curl_easy_setopt(curl, CURLOPT_MAXAGE_CONN, 30L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.65.0 + +# RETURN VALUE + +Returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 deleted file mode 100644 index bb1c40398ba..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAXCONNECTS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAXCONNECTS \- maximum connection cache size -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXCONNECTS, long amount); -.fi -.SH DESCRIPTION -Pass a long. The set \fIamount\fP is the maximum number of simultaneously open -persistent connections that libcurl may cache in the pool associated with this -handle. The default is 5, and there is not much point in changing this value -unless you are perfectly aware of how this works. This concerns connections -using any of the protocols that support persistent connections. - -When reaching the maximum limit, curl closes the oldest one in the cache to -prevent increasing the number of open connections. - -If you already have performed transfers with this curl handle, setting a -smaller \fICURLOPT_MAXCONNECTS(3)\fP than before may cause open connections to -get closed unnecessarily. - -If you add this easy handle to a multi handle, this setting is not -acknowledged, and you must instead use \fIcurl_multi_setopt(3)\fP and the -\fICURLMOPT_MAXCONNECTS(3)\fP option. -.SH DEFAULT -5 -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* limit the connection cache for this handle to no more than 3 */ - curl_easy_setopt(curl, CURLOPT_MAXCONNECTS, 3L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), -.BR CURLMOPT_MAX_TOTAL_CONNECTIONS (3), -.BR CURLMOPT_MAXCONNECTS (3), -.BR CURLOPT_MAXREDIRS (3) diff --git a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md new file mode 100644 index 00000000000..807df4da1fd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAXCONNECTS +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_MAXCONNECTS (3) + - CURLMOPT_MAX_HOST_CONNECTIONS (3) + - CURLMOPT_MAX_TOTAL_CONNECTIONS (3) + - CURLOPT_MAXREDIRS (3) +--- + +# NAME + +CURLOPT_MAXCONNECTS - maximum connection cache size + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXCONNECTS, long amount); +~~~ + +# DESCRIPTION + +Pass a long. The set *amount* is the maximum number of simultaneously open +persistent connections that libcurl may cache in the pool associated with this +handle. The default is 5, and there is not much point in changing this value +unless you are perfectly aware of how this works. This concerns connections +using any of the protocols that support persistent connections. + +When reaching the maximum limit, curl closes the oldest one in the cache to +prevent increasing the number of open connections. + +If you already have performed transfers with this curl handle, setting a +smaller CURLOPT_MAXCONNECTS(3) than before may cause open connections to +get closed unnecessarily. + +If you add this easy handle to a multi handle, this setting is not +acknowledged, and you must instead use curl_multi_setopt(3) and the +CURLMOPT_MAXCONNECTS(3) option. + +# DEFAULT + +5 + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* limit the connection cache for this handle to no more than 3 */ + curl_easy_setopt(curl, CURLOPT_MAXCONNECTS, 3L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 deleted file mode 100644 index ed970b29ea6..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAXFILESIZE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAXFILESIZE \- maximum file size allowed to download -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE, long size); -.fi -.SH DESCRIPTION -Pass a long as parameter. This specifies the maximum accepted \fIsize\fP (in -bytes) of a file to download. If the file requested is found larger than this -value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is returned. - -The file size is not always known prior to the download start, and for such -transfers this option has no effect - even if the file transfer eventually -ends up being larger than this given limit. - -If you want a limit above 2GB, use \fICURLOPT_MAXFILESIZE_LARGE(3)\fP. - -Since 8.4.0, this option also stops ongoing transfers if they reach this -threshold. -.SH DEFAULT -None -.SH PROTOCOLS -FTP, HTTP and MQTT -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* refuse to download if larger than 1000 bytes! */ - curl_easy_setopt(curl, CURLOPT_MAXFILESIZE, 1000L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), -.BR CURLOPT_MAXFILESIZE_LARGE (3) diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md new file mode 100644 index 00000000000..a90c94b7dc3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAXFILESIZE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAXFILESIZE_LARGE (3) + - CURLOPT_MAX_RECV_SPEED_LARGE (3) +--- + +# NAME + +CURLOPT_MAXFILESIZE - maximum file size allowed to download + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE, long size); +~~~ + +# DESCRIPTION + +Pass a long as parameter. This specifies the maximum accepted *size* (in +bytes) of a file to download. If the file requested is found larger than this +value, the transfer is aborted and *CURLE_FILESIZE_EXCEEDED* is returned. + +The file size is not always known prior to the download start, and for such +transfers this option has no effect - even if the file transfer eventually +ends up being larger than this given limit. + +If you want a limit above 2GB, use CURLOPT_MAXFILESIZE_LARGE(3). + +Since 8.4.0, this option also stops ongoing transfers if they reach this +threshold. + +# DEFAULT + +None + +# PROTOCOLS + +FTP, HTTP and MQTT + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* refuse to download if larger than 1000 bytes! */ + curl_easy_setopt(curl, CURLOPT_MAXFILESIZE, 1000L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 deleted file mode 100644 index 209701c4ed9..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAXFILESIZE_LARGE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAXFILESIZE_LARGE \- maximum file size allowed to download -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE_LARGE, - curl_off_t size); -.SH DESCRIPTION -Pass a curl_off_t as parameter. This specifies the maximum accepted \fIsize\fP -(in bytes) of a file to download. If the file requested is found larger than -this value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is -returned. - -The file size is not always known prior to the download start, and for such -transfers this option has no effect - even if the file transfer eventually -ends up being larger than this given limit. - -Since 8.4.0, this option also stops ongoing transfers if they reach this -threshold. -.SH DEFAULT -None -.SH PROTOCOLS -FTP, HTTP and MQTT -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_off_t ridiculous = (curl_off_t)1 << 48; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* refuse to download if larger than ridiculous */ - curl_easy_setopt(curl, CURLOPT_MAXFILESIZE_LARGE, ridiculous); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.11.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), -.BR CURLOPT_MAXFILESIZE (3) diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md new file mode 100644 index 00000000000..041282f4190 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAXFILESIZE_LARGE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAXFILESIZE (3) + - CURLOPT_MAX_RECV_SPEED_LARGE (3) +--- + +# NAME + +CURLOPT_MAXFILESIZE_LARGE - maximum file size allowed to download + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE_LARGE, + curl_off_t size); +~~~ + +# DESCRIPTION + +Pass a curl_off_t as parameter. This specifies the maximum accepted *size* +(in bytes) of a file to download. If the file requested is found larger than +this value, the transfer is aborted and *CURLE_FILESIZE_EXCEEDED* is +returned. + +The file size is not always known prior to the download start, and for such +transfers this option has no effect - even if the file transfer eventually +ends up being larger than this given limit. + +Since 8.4.0, this option also stops ongoing transfers if they reach this +threshold. + +# DEFAULT + +None + +# PROTOCOLS + +FTP, HTTP and MQTT + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_off_t ridiculous = (curl_off_t)1 << 48; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* refuse to download if larger than ridiculous */ + curl_easy_setopt(curl, CURLOPT_MAXFILESIZE_LARGE, ridiculous); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.11.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 deleted file mode 100644 index c3ec8aab9ea..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAXLIFETIME_CONN 3 "10 Nov 2021" libcurl libcurl -.SH NAME -CURLOPT_MAXLIFETIME_CONN \- max lifetime (since creation) allowed for reusing a connection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXLIFETIME_CONN, - long maxlifetime); -.fi -.SH DESCRIPTION -Pass a long as parameter containing \fImaxlifetime\fP - the maximum time in -seconds, since the creation of the connection, that you allow an existing -connection to have to be considered for reuse for this request. - -libcurl features a connection cache that holds previously used connections. -When a new request is to be done, libcurl considers any connection that -matches for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents -libcurl from trying too old connections for reuse. This can be used for -client-side load balancing. If a connection is found in the cache that is -older than this set \fImaxlifetime\fP, it is instead marked for closure. - -If set to 0, this behavior is disabled: all connections are eligible for reuse. -.SH DEFAULT -Default \fImaxlifetime\fP is 0 seconds (i.e., disabled). -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* only allow each connection to be reused for 30 seconds */ - curl_easy_setopt(curl, CURLOPT_MAXLIFETIME_CONN, 30L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.80.0 -.SH RETURN VALUE -Returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_FORBID_REUSE (3), -.BR CURLOPT_FRESH_CONNECT (3), -.BR CURLOPT_MAXAGE_CONN (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md new file mode 100644 index 00000000000..f731ad9990e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAXLIFETIME_CONN +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FORBID_REUSE (3) + - CURLOPT_FRESH_CONNECT (3) + - CURLOPT_MAXAGE_CONN (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_MAXLIFETIME_CONN - max lifetime (since creation) allowed for reusing a connection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXLIFETIME_CONN, + long maxlifetime); +~~~ + +# DESCRIPTION + +Pass a long as parameter containing *maxlifetime* - the maximum time in +seconds, since the creation of the connection, that you allow an existing +connection to have to be considered for reuse for this request. + +libcurl features a connection cache that holds previously used connections. +When a new request is to be done, libcurl considers any connection that +matches for reuse. The CURLOPT_MAXLIFETIME_CONN(3) limit prevents +libcurl from trying too old connections for reuse. This can be used for +client-side load balancing. If a connection is found in the cache that is +older than this set *maxlifetime*, it is instead marked for closure. + +If set to 0, this behavior is disabled: all connections are eligible for reuse. + +# DEFAULT + +Default *maxlifetime* is 0 seconds (i.e., disabled). + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* only allow each connection to be reused for 30 seconds */ + curl_easy_setopt(curl, CURLOPT_MAXLIFETIME_CONN, 30L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.80.0 + +# RETURN VALUE + +Returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 deleted file mode 100644 index 763425a07f6..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAXREDIRS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAXREDIRS \- maximum number of redirects allowed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXREDIRS, long amount); -.fi -.SH DESCRIPTION -Pass a long. The set number is the redirection limit \fIamount\fP. If that -many redirections have been followed, the next redirect triggers the error -(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the -\fICURLOPT_FOLLOWLOCATION(3)\fP is used at the same time. - -Setting the limit to 0 makes libcurl refuse any redirect. - -Set it to -1 for an infinite number of redirects. This allows your application -to get stuck in never-ending redirect loops. -.SH DEFAULT -30 (since 8.3.0), it was previously unlimited. -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - - /* enable redirect following */ - curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - - /* allow three redirects */ - curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 3L); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_REDIRECT_COUNT (3), -.BR CURLINFO_REDIRECT_URL (3), -.BR CURLOPT_FOLLOWLOCATION (3) diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.md b/docs/libcurl/opts/CURLOPT_MAXREDIRS.md new file mode 100644 index 00000000000..5ace67e42e7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXREDIRS.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAXREDIRS +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_COUNT (3) + - CURLINFO_REDIRECT_URL (3) + - CURLOPT_FOLLOWLOCATION (3) +--- + +# NAME + +CURLOPT_MAXREDIRS - maximum number of redirects allowed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXREDIRS, long amount); +~~~ + +# DESCRIPTION + +Pass a long. The set number is the redirection limit *amount*. If that +many redirections have been followed, the next redirect triggers the error +(*CURLE_TOO_MANY_REDIRECTS*). This option only makes sense if the +CURLOPT_FOLLOWLOCATION(3) is used at the same time. + +Setting the limit to 0 makes libcurl refuse any redirect. + +Set it to -1 for an infinite number of redirects. This allows your application +to get stuck in never-ending redirect loops. + +# DEFAULT + +30 (since 8.3.0), it was previously unlimited. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + + /* enable redirect following */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + /* allow three redirects */ + curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 3L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 deleted file mode 100644 index 9f0a5ac92d7..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAX_RECV_SPEED_LARGE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAX_RECV_SPEED_LARGE \- rate limit data download speed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_RECV_SPEED_LARGE, - curl_off_t maxspeed); -.SH DESCRIPTION -Pass a curl_off_t as parameter. If a download exceeds this \fImaxspeed\fP -(counted in bytes per second) the transfer pauses to keep the average speed -less than or equal to the parameter value. Defaults to unlimited speed. - -This is not an exact science. libcurl attempts to keep the average speed below -the given threshold over a period time. - -If you set \fImaxspeed\fP to a value lower than \fICURLOPT_BUFFERSIZE(3)\fP, -libcurl might download faster than the set limit initially. - -This option does not affect transfer speeds done with FILE:// URLs. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -All but file:// -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* cap the download speed to 31415 bytes/sec */ - curl_easy_setopt(curl, CURLOPT_MAX_RECV_SPEED_LARGE, (curl_off_t)31415); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.5 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_MAX_SEND_SPEED_LARGE (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md new file mode 100644 index 00000000000..646f301e44f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAX_RECV_SPEED_LARGE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_MAX_SEND_SPEED_LARGE (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_MAX_RECV_SPEED_LARGE - rate limit data download speed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_RECV_SPEED_LARGE, + curl_off_t maxspeed); +~~~ + +# DESCRIPTION + +Pass a curl_off_t as parameter. If a download exceeds this *maxspeed* +(counted in bytes per second) the transfer pauses to keep the average speed +less than or equal to the parameter value. Defaults to unlimited speed. + +This is not an exact science. libcurl attempts to keep the average speed below +the given threshold over a period time. + +If you set *maxspeed* to a value lower than CURLOPT_BUFFERSIZE(3), +libcurl might download faster than the set limit initially. + +This option does not affect transfer speeds done with FILE:// URLs. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +All but file:// + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* cap the download speed to 31415 bytes/sec */ + curl_easy_setopt(curl, CURLOPT_MAX_RECV_SPEED_LARGE, (curl_off_t)31415); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.5 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 deleted file mode 100644 index 364baed310b..00000000000 --- a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MAX_SEND_SPEED_LARGE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_MAX_SEND_SPEED_LARGE \- rate limit data upload speed -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_SEND_SPEED_LARGE, - curl_off_t maxspeed); -.SH DESCRIPTION -Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds -this speed (counted in bytes per second) the transfer pauses to keep the -average speed less than or equal to the parameter value. Defaults to unlimited -speed. - -This is not an exact science. libcurl attempts to keep the average speed below -the given threshold over a period time. - -If you set \fImaxspeed\fP to a value lower than -\fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP, libcurl might "shoot over" the limit on -its first send and still send off a full buffer. - -This option does not affect transfer speeds done with FILE:// URLs. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -All except file:// -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* cap the upload speed to 1000 bytes/sec */ - curl_easy_setopt(curl, CURLOPT_MAX_SEND_SPEED_LARGE, (curl_off_t)1000); - /* (set some upload options as well!) */ - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.15.5 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_MAX_RECV_SPEED_LARGE (3) diff --git a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md new file mode 100644 index 00000000000..8b709ccb726 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MAX_SEND_SPEED_LARGE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_MAX_RECV_SPEED_LARGE (3) +--- + +# NAME + +CURLOPT_MAX_SEND_SPEED_LARGE - rate limit data upload speed + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_SEND_SPEED_LARGE, + curl_off_t maxspeed); +~~~ + +# DESCRIPTION + +Pass a curl_off_t as parameter with the *maxspeed*. If an upload exceeds +this speed (counted in bytes per second) the transfer pauses to keep the +average speed less than or equal to the parameter value. Defaults to unlimited +speed. + +This is not an exact science. libcurl attempts to keep the average speed below +the given threshold over a period time. + +If you set *maxspeed* to a value lower than +CURLOPT_UPLOAD_BUFFERSIZE(3), libcurl might "shoot over" the limit on +its first send and still send off a full buffer. + +This option does not affect transfer speeds done with FILE:// URLs. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +All except file:// + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* cap the upload speed to 1000 bytes/sec */ + curl_easy_setopt(curl, CURLOPT_MAX_SEND_SPEED_LARGE, (curl_off_t)1000); + /* (set some upload options as well!) */ + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.15.5 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 deleted file mode 100644 index 02a5a0a7f2b..00000000000 --- a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 +++ /dev/null @@ -1,84 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MIMEPOST 3 "22 Aug 2017" libcurl libcurl -.SH NAME -CURLOPT_MIMEPOST \- send data from mime structure -.SH SYNOPSIS -.nf -#include - -curl_mime *mime; - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIMEPOST, mime); -.SH DESCRIPTION -Pass a mime handle previously obtained from \fIcurl_mime_init(3)\fP. - -This setting is supported by the HTTP protocol to post forms and by the -SMTP and IMAP protocols to provide the email data to send/upload. - -This option is the preferred way of posting an HTTP form, replacing and -extending the \fICURLOPT_HTTPPOST(3)\fP option. - -When setting \fICURLOPT_MIMEPOST(3)\fP to NULL, libcurl resets the request -type for HTTP to the default to disable the POST. Typically that would mean it -is reset to GET. Instead you should set a desired request method explicitly. -.SH PROTOCOLS -HTTP, SMTP, IMAP. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_mime *multipart = curl_mime_init(curl); - if(multipart) { - curl_mimepart *part = curl_mime_addpart(multipart); - curl_mime_name(part, "name"); - curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); - part = curl_mime_addpart(multipart); - curl_mime_name(part, "project"); - curl_mime_data(part, "curl", CURL_ZERO_TERMINATED); - part = curl_mime_addpart(multipart); - curl_mime_name(part, "logotype-image"); - curl_mime_filedata(part, "curl.png"); - - /* Set the form info */ - curl_easy_setopt(curl, CURLOPT_MIMEPOST, multipart); - - curl_easy_perform(curl); /* post away! */ - curl_mime_free(multipart); /* free the post data */ - } - } -} -.fi -.SH AVAILABILITY -Added in 7.56.0 -.SH RETURN VALUE -This returns CURLE_OK. -.SH "SEE ALSO" -.BR curl_mime_init (3), -.BR CURLOPT_HTTPPOST (3), -.BR CURLOPT_POSTFIELDS (3), -.BR CURLOPT_PUT (3) diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.md b/docs/libcurl/opts/CURLOPT_MIMEPOST.md new file mode 100644 index 00000000000..588b7e80328 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.md @@ -0,0 +1,81 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MIMEPOST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPPOST (3) + - CURLOPT_POSTFIELDS (3) + - CURLOPT_PUT (3) + - curl_mime_init (3) +--- + +# NAME + +CURLOPT_MIMEPOST - send data from mime structure + +# SYNOPSIS + +~~~c +#include + +curl_mime *mime; + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIMEPOST, mime); +~~~ + +# DESCRIPTION + +Pass a mime handle previously obtained from curl_mime_init(3). + +This setting is supported by the HTTP protocol to post forms and by the +SMTP and IMAP protocols to provide the email data to send/upload. + +This option is the preferred way of posting an HTTP form, replacing and +extending the CURLOPT_HTTPPOST(3) option. + +When setting CURLOPT_MIMEPOST(3) to NULL, libcurl resets the request +type for HTTP to the default to disable the POST. Typically that would mean it +is reset to GET. Instead you should set a desired request method explicitly. + +# PROTOCOLS + +HTTP, SMTP, IMAP. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_mime *multipart = curl_mime_init(curl); + if(multipart) { + curl_mimepart *part = curl_mime_addpart(multipart); + curl_mime_name(part, "name"); + curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); + part = curl_mime_addpart(multipart); + curl_mime_name(part, "project"); + curl_mime_data(part, "curl", CURL_ZERO_TERMINATED); + part = curl_mime_addpart(multipart); + curl_mime_name(part, "logotype-image"); + curl_mime_filedata(part, "curl.png"); + + /* Set the form info */ + curl_easy_setopt(curl, CURLOPT_MIMEPOST, multipart); + + curl_easy_perform(curl); /* post away! */ + curl_mime_free(multipart); /* free the post data */ + } + } +} +~~~ + +# AVAILABILITY + +Added in 7.56.0 + +# RETURN VALUE + +This returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3 deleted file mode 100644 index 3f72823513c..00000000000 --- a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3 +++ /dev/null @@ -1,97 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_MIME_OPTIONS 3 "2 Oct 2021" libcurl libcurl -.SH NAME -CURLOPT_MIME_OPTIONS \- set MIME option flags -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIME_OPTIONS, long options); -.fi -.SH DESCRIPTION -Pass a long that holds a bitmask of CURLMIMEOPT_* defines. Each bit is a -Boolean flag used while encoding a MIME tree or multipart form data. - -Available bits are: -.IP CURLMIMEOPT_FORMESCAPE -Tells libcurl to escape multipart form field and file names using the -backslash-escaping algorithm rather than percent-encoding (HTTP only). - -Backslash-escaping consists in preceding backslashes and double quotes with -a backslash. Percent encoding maps all occurrences of double quote, -carriage return and line feed to %22, %0D and %0A respectively. - -Before version 7.81.0, percent-encoding was never applied. - -HTTP browsers used to do backslash-escaping in the past but have over time -transitioned to use percent-encoding. This option allows one to address -server-side applications that have not yet have been converted. - -As an example, consider field or file name \fIstrange\\name"kind\fP. -When the containing multipart form is sent, this is normally transmitted as -\fIstrange\\name%22kind\fP. When this option is set, it is sent as -\fIstrange\\\\name\\"kind\fP. -.SH DEFAULT -0, meaning disabled. -.SH PROTOCOLS -HTTP, IMAP, SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - curl_mime *form = NULL; - - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_MIME_OPTIONS, CURLMIMEOPT_FORMESCAPE); - - form = curl_mime_init(curl); - if(form) { - curl_mimepart *part = curl_mime_addpart(form); - - if(part) { - curl_mime_filedata(part, "strange\\\\file\\\\name"); - curl_mime_name(part, "strange\\"field\\"name"); - curl_easy_setopt(curl, CURLOPT_MIMEPOST, form); - - /* Perform the request */ - curl_easy_perform(curl); - } - } - - curl_easy_cleanup(curl); - curl_mime_free(form); - } -} -.fi -.SH AVAILABILITY -Option added in 7.81.0. -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_HTTPPOST (3), -.BR CURLOPT_MIMEPOST (3) diff --git a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md new file mode 100644 index 00000000000..6ba9abb5f1a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md @@ -0,0 +1,97 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_MIME_OPTIONS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPPOST (3) + - CURLOPT_MIMEPOST (3) +--- + +# NAME + +CURLOPT_MIME_OPTIONS - set MIME option flags + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIME_OPTIONS, long options); +~~~ + +# DESCRIPTION + +Pass a long that holds a bitmask of CURLMIMEOPT_* defines. Each bit is a +Boolean flag used while encoding a MIME tree or multipart form data. + +Available bits are: + +## CURLMIMEOPT_FORMESCAPE + +Tells libcurl to escape multipart form field and file names using the +backslash-escaping algorithm rather than percent-encoding (HTTP only). + +Backslash-escaping consists in preceding backslashes and double quotes with +a backslash. Percent encoding maps all occurrences of double quote, +carriage return and line feed to %22, %0D and %0A respectively. + +Before version 7.81.0, percent-encoding was never applied. + +HTTP browsers used to do backslash-escaping in the past but have over time +transitioned to use percent-encoding. This option allows one to address +server-side applications that have not yet have been converted. + +As an example, consider field or file name *strangename"kind*. +When the containing multipart form is sent, this is normally transmitted as +*strangename%22kind*. When this option is set, it is sent as +*strangename"kind*. + +# DEFAULT + +0, meaning disabled. + +# PROTOCOLS + +HTTP, IMAP, SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + curl_mime *form = NULL; + + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_MIME_OPTIONS, CURLMIMEOPT_FORMESCAPE); + + form = curl_mime_init(curl); + if(form) { + curl_mimepart *part = curl_mime_addpart(form); + + if(part) { + curl_mime_filedata(part, "strange\\file\\name"); + curl_mime_name(part, "strange\"field\"name"); + curl_easy_setopt(curl, CURLOPT_MIMEPOST, form); + + /* Perform the request */ + curl_easy_perform(curl); + } + } + + curl_easy_cleanup(curl); + curl_mime_free(form); + } +} +~~~ + +# AVAILABILITY + +Option added in 7.81.0. + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_NETRC.3 b/docs/libcurl/opts/CURLOPT_NETRC.3 deleted file mode 100644 index 3f04fccf704..00000000000 --- a/docs/libcurl/opts/CURLOPT_NETRC.3 +++ /dev/null @@ -1,126 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_NETRC 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_NETRC \- enable use of .netrc -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level); -.fi -.SH DESCRIPTION -This parameter controls the preference \fIlevel\fP of libcurl between using -user names and passwords from your \fI~/.netrc\fP file, relative to user names -and passwords in the URL supplied with \fICURLOPT_URL(3)\fP. - -On Windows, libcurl uses the file as \fI%HOME%/_netrc\fP. If \fI%HOME%\fP is -not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP. - -You can also tell libcurl a different file name to use with -\fICURLOPT_NETRC_FILE(3)\fP. - -libcurl uses a user name (and supplied or prompted password) supplied with -\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP in preference to any of -the options controlled by this parameter. - -Only machine name, user name and password are taken into account (init macros -and similar things are not supported). - -libcurl does not verify that the file has the correct properties set (as the -standard Unix ftp client does). It should only be readable by user. - -\fIlevel\fP is a long that should be set to one of the values described below. -.IP "CURL_NETRC_IGNORED (0)" -libcurl ignores the \fI.netrc\fP file. This is the default. -.IP "CURL_NETRC_OPTIONAL (1)" -The use of the \fI.netrc\fP file is optional, and information in the URL is to -be preferred. The file is scanned for the host and user name (to find the -password only) or for the host only, to find the first user name and password -after that \fImachine\fP, which ever information is not specified. -.IP "CURL_NETRC_REQUIRED (2)" -The use of the \fI.netrc\fP file is required, and any credential information -present in the URL is ignored. The file is scanned for the host and user name -(to find the password only) or for the host only, to find the first user name -and password after that \fImachine\fP, which ever information is not -specified. -.SH FILE FORMAT -The \fB.netrc\fP file format is simple: you specify lines with a machine name -and follow the login and password that are associated with that machine. - -Each field is provided as a sequence of letters that ends with a space or -newline. Starting in 7.84.0, libcurl also supports quoted strings. They start -and end with double quotes and support the escaped special letters \\\", \\n, -\\r, and \\t. Quoted strings are the only way a space character can be used in -a user name or password. - -.IP "machine " -Provides credentials for a host called \fBname\fP. libcurl searches the .netrc -file for a machine token that matches the host name specified in the URL. Once -a match is made, the subsequent tokens are processed, stopping when the end of -file is reached or another "machine" is encountered. -.IP default -This is the same as "machine" name except that default matches any name. There -can be only one default token, and it must be after all machine tokens. To -provide a default anonymous login for hosts that are not otherwise matched, -add a line similar to this in the end: - - default login anonymous password user@domain -.IP "login " -The user name string for the remote machine. -.IP "password " -Supply a password. If this token is present, curl supplies the specified -string if the remote server requires a password as part of the login process. -Note that if this token is present in the .netrc file you really should make -sure the file is not readable by anyone besides the user. -.IP "macdef " -Define a macro. This feature is not supported by libcurl. In order for the -rest of the .netrc to still work fine, libcurl properly skips every definition -done with "macdef" that it finds. -.SH DEFAULT -CURL_NETRC_IGNORED -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); - curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_USERPWD (3), -.BR CURLOPT_USERNAME (3), -.BR CURLOPT_NETRC_FILE (3) diff --git a/docs/libcurl/opts/CURLOPT_NETRC.md b/docs/libcurl/opts/CURLOPT_NETRC.md new file mode 100644 index 00000000000..4ec83133570 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NETRC.md @@ -0,0 +1,141 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_NETRC +Section: 3 +Source: libcurl +See-also: + - CURLOPT_NETRC_FILE (3) + - CURLOPT_USERNAME (3) + - CURLOPT_USERPWD (3) +--- + +# NAME + +CURLOPT_NETRC - enable use of .netrc + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level); +~~~ + +# DESCRIPTION + +This parameter controls the preference *level* of libcurl between using +user names and passwords from your *~/.netrc* file, relative to user names +and passwords in the URL supplied with CURLOPT_URL(3). + +On Windows, libcurl uses the file as *%HOME%/_netrc*. If *%HOME%* is +not set on Windows, libcurl falls back to *%USERPROFILE%*. + +You can also tell libcurl a different file name to use with +CURLOPT_NETRC_FILE(3). + +libcurl uses a user name (and supplied or prompted password) supplied with +CURLOPT_USERPWD(3) or CURLOPT_USERNAME(3) in preference to any of +the options controlled by this parameter. + +Only machine name, user name and password are taken into account (init macros +and similar things are not supported). + +libcurl does not verify that the file has the correct properties set (as the +standard Unix ftp client does). It should only be readable by user. + +*level* is a long that should be set to one of the values described below. + +## CURL_NETRC_IGNORED (0) + +libcurl ignores the *.netrc* file. This is the default. + +## CURL_NETRC_OPTIONAL (1) + +The use of the *.netrc* file is optional, and information in the URL is to +be preferred. The file is scanned for the host and user name (to find the +password only) or for the host only, to find the first user name and password +after that *machine*, which ever information is not specified. + +## CURL_NETRC_REQUIRED (2) + +The use of the *.netrc* file is required, and any credential information +present in the URL is ignored. The file is scanned for the host and user name +(to find the password only) or for the host only, to find the first user name +and password after that *machine*, which ever information is not +specified. + +# FILE FORMAT + +The **.netrc** file format is simple: you specify lines with a machine name +and follow the login and password that are associated with that machine. + +Each field is provided as a sequence of letters that ends with a space or +newline. Starting in 7.84.0, libcurl also supports quoted strings. They start +and end with double quotes and support the escaped special letters ", n, +r, and t. Quoted strings are the only way a space character can be used in +a user name or password. + +## machine + +Provides credentials for a host called **name**. libcurl searches the .netrc +file for a machine token that matches the host name specified in the URL. Once +a match is made, the subsequent tokens are processed, stopping when the end of +file is reached or another "machine" is encountered. + +## default + +This is the same as "machine" name except that default matches any name. There +can be only one default token, and it must be after all machine tokens. To +provide a default anonymous login for hosts that are not otherwise matched, +add a line similar to this in the end: + + default login anonymous password user@domain + +## login + +The user name string for the remote machine. + +## password + +Supply a password. If this token is present, curl supplies the specified +string if the remote server requires a password as part of the login process. +Note that if this token is present in the .netrc file you really should make +sure the file is not readable by anyone besides the user. + +## macdef + +Define a macro. This feature is not supported by libcurl. In order for the +rest of the .netrc to still work fine, libcurl properly skips every definition +done with "macdef" that it finds. + +# DEFAULT + +CURL_NETRC_IGNORED + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); + curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 b/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 deleted file mode 100644 index ff0bb505064..00000000000 --- a/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_NETRC_FILE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_NETRC_FILE \- file name to read .netrc info from -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC_FILE, char *file); -.fi -.SH DESCRIPTION -Pass a char * as parameter, pointing to a null-terminated string containing -the full path name to the \fIfile\fP you want libcurl to use as .netrc -file. If this option is omitted, and \fICURLOPT_NETRC(3)\fP is set, libcurl -checks for a .netrc file in the current user's home directory. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); - curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); - curl_easy_setopt(curl, CURLOPT_NETRC_FILE, "/tmp/magic-netrc"); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.9 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_NETRC (3), -.BR CURLOPT_PASSWORD (3), -.BR CURLOPT_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_NETRC_FILE.md b/docs/libcurl/opts/CURLOPT_NETRC_FILE.md new file mode 100644 index 00000000000..95a3e877d6d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NETRC_FILE.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_NETRC_FILE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_NETRC (3) + - CURLOPT_PASSWORD (3) + - CURLOPT_USERNAME (3) +--- + +# NAME + +CURLOPT_NETRC_FILE - file name to read .netrc info from + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC_FILE, char *file); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, pointing to a null-terminated string +containing the full path name to the *file* you want libcurl to use as .netrc +file. If this option is omitted, and CURLOPT_NETRC(3) is set, libcurl checks +for a .netrc file in the current user's home directory. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); + curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); + curl_easy_setopt(curl, CURLOPT_NETRC_FILE, "/tmp/magic-netrc"); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.9 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 deleted file mode 100644 index 97282225a1d..00000000000 --- a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_NEW_DIRECTORY_PERMS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_NEW_DIRECTORY_PERMS \- permissions for remotely created directories -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_DIRECTORY_PERMS, - long mode); -.SH DESCRIPTION -Pass a long as a parameter, containing the value of the permissions that is -set on newly created directories on the remote server. The default value is -\fI0755\fP, but any valid value can be used. The only protocols that can use -this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. -.SH DEFAULT -0755 -.SH PROTOCOLS -SFTP, SCP and FILE -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, - "sftp://upload.example.com/newdir/file.zip"); - curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, 1L); - curl_easy_setopt(curl, CURLOPT_NEW_DIRECTORY_PERMS, 0644L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.16.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FTP_CREATE_MISSING_DIRS (3), -.BR CURLOPT_NEW_FILE_PERMS (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md new file mode 100644 index 00000000000..bb302d42bd0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_NEW_DIRECTORY_PERMS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FTP_CREATE_MISSING_DIRS (3) + - CURLOPT_NEW_FILE_PERMS (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_NEW_DIRECTORY_PERMS - permissions for remotely created directories + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_DIRECTORY_PERMS, + long mode); +~~~ + +# DESCRIPTION + +Pass a long as a parameter, containing the value of the permissions that is +set on newly created directories on the remote server. The default value is +*0755*, but any valid value can be used. The only protocols that can use +this are *sftp://*, *scp://*, and *file://*. + +# DEFAULT + +0755 + +# PROTOCOLS + +SFTP, SCP and FILE + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, + "sftp://upload.example.com/newdir/file.zip"); + curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, 1L); + curl_easy_setopt(curl, CURLOPT_NEW_DIRECTORY_PERMS, 0644L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.16.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 deleted file mode 100644 index b81041d160d..00000000000 --- a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 +++ /dev/null @@ -1,62 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_NEW_FILE_PERMS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_NEW_FILE_PERMS \- permissions for remotely created files -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_FILE_PERMS, - long mode); -.SH DESCRIPTION -Pass a long as a parameter, containing the value of the permissions that are -set on newly created files on the remote server. The default value is -\fI0644\fP, but any valid value can be used. The only protocols that can use -this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. -.SH DEFAULT -0644 -.SH PROTOCOLS -SFTP, SCP and FILE -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://upload.example.com/file.txt"); - curl_easy_setopt(curl, CURLOPT_NEW_FILE_PERMS, 0664L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.16.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_NEW_DIRECTORY_PERMS (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md new file mode 100644 index 00000000000..dd12c0bbdf1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md @@ -0,0 +1,60 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_NEW_FILE_PERMS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_NEW_DIRECTORY_PERMS (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_NEW_FILE_PERMS - permissions for remotely created files + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_FILE_PERMS, + long mode); +~~~ + +# DESCRIPTION + +Pass a long as a parameter, containing the value of the permissions that are +set on newly created files on the remote server. The default value is *0644*. +The only protocols that can use this are *sftp://*, *scp://*, and *file://*. + +# DEFAULT + +0644 + +# PROTOCOLS + +SFTP, SCP and FILE + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://upload.example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_NEW_FILE_PERMS, 0664L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.16.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.3 b/docs/libcurl/opts/CURLOPT_NOBODY.3 deleted file mode 100644 index a21a825a3e8..00000000000 --- a/docs/libcurl/opts/CURLOPT_NOBODY.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_NOBODY 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_NOBODY \- do the download request without getting the body -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOBODY, long opt); -.fi -.SH DESCRIPTION -A long parameter set to 1 tells libcurl to not include the body-part in the -output when doing what would otherwise be a download. For HTTP(S), this makes -libcurl do a HEAD request. For most other protocols it means just not asking -to transfer the body data. - -For HTTP operations when \fICURLOPT_NOBODY(3)\fP has been set, disabling this -option (with 0) makes it a GET again - only if the method is still set to be -HEAD. The proper way to get back to a GET request is to set -\fICURLOPT_HTTPGET(3)\fP and for other methods, use the POST or UPLOAD -options. - -Enabling \fICURLOPT_NOBODY(3)\fP means asking for a download without a body. - -If you do a transfer with HTTP that involves a method other than HEAD, you get -a body (unless the resource and server sends a zero byte body for the specific -URL you request). -.SH DEFAULT -0, the body is transferred -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* get us the resource without a body - use HEAD! */ - curl_easy_setopt(curl, CURLOPT_NOBODY, 1L); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_HTTPGET (3), -.BR CURLOPT_MIMEPOST (3), -.BR CURLOPT_POSTFIELDS (3), -.BR CURLOPT_REQUEST_TARGET (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.md b/docs/libcurl/opts/CURLOPT_NOBODY.md new file mode 100644 index 00000000000..9d63154c9d3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NOBODY.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_NOBODY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPGET (3) + - CURLOPT_MIMEPOST (3) + - CURLOPT_POSTFIELDS (3) + - CURLOPT_REQUEST_TARGET (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_NOBODY - do the download request without getting the body + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOBODY, long opt); +~~~ + +# DESCRIPTION + +A long parameter set to 1 tells libcurl to not include the body-part in the +output when doing what would otherwise be a download. For HTTP(S), this makes +libcurl do a HEAD request. For most other protocols it means just not asking +to transfer the body data. + +For HTTP operations when CURLOPT_NOBODY(3) has been set, disabling this +option (with 0) makes it a GET again - only if the method is still set to be +HEAD. The proper way to get back to a GET request is to set +CURLOPT_HTTPGET(3) and for other methods, use the POST or UPLOAD +options. + +Enabling CURLOPT_NOBODY(3) means asking for a download without a body. + +If you do a transfer with HTTP that involves a method other than HEAD, you get +a body (unless the resource and server sends a zero byte body for the specific +URL you request). + +# DEFAULT + +0, the body is transferred + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* get us the resource without a body - use HEAD! */ + curl_easy_setopt(curl, CURLOPT_NOBODY, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 b/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 deleted file mode 100644 index fd4e07f3276..00000000000 --- a/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 +++ /dev/null @@ -1,67 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_NOPROGRESS 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_NOPROGRESS \- switch off the progress meter -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROGRESS, long onoff); -.fi -.SH DESCRIPTION -If \fIonoff\fP is to 1, it tells the library to shut off the progress meter -completely for requests done with this \fIhandle\fP. It also prevents the -\fICURLOPT_XFERINFOFUNCTION(3)\fP or \fICURLOPT_PROGRESSFUNCTION(3)\fP from -getting called. -.SH DEFAULT -1, meaning it normally runs without a progress meter. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* enable progress meter */ - curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_PROGRESSFUNCTION (3), -.BR CURLOPT_VERBOSE (3), -.BR CURLOPT_XFERINFOFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_NOPROGRESS.md b/docs/libcurl/opts/CURLOPT_NOPROGRESS.md new file mode 100644 index 00000000000..e2845a96fcd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NOPROGRESS.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_NOPROGRESS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_PROGRESSFUNCTION (3) + - CURLOPT_VERBOSE (3) + - CURLOPT_XFERINFOFUNCTION (3) +--- + +# NAME + +CURLOPT_NOPROGRESS - switch off the progress meter + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROGRESS, long onoff); +~~~ + +# DESCRIPTION + +If *onoff* is to 1, it tells the library to shut off the progress meter +completely for requests done with this *handle*. It also prevents the +CURLOPT_XFERINFOFUNCTION(3) or CURLOPT_PROGRESSFUNCTION(3) from +getting called. + +# DEFAULT + +1, meaning it normally runs without a progress meter. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable progress meter */ + curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.3 b/docs/libcurl/opts/CURLOPT_NOPROXY.3 deleted file mode 100644 index 1a5b075700e..00000000000 --- a/docs/libcurl/opts/CURLOPT_NOPROXY.3 +++ /dev/null @@ -1,91 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_NOPROXY 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_NOPROXY \- disable proxy use for specific hosts -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROXY, char *noproxy); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string. The string consists of a comma -separated list of host names that do not require a proxy to get reached, even -if one is specified. The only wildcard available 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, "ample.com" would match ample.com, ample.com:80, -and www.ample.com, but not www.example.com or ample.com.org. - -Setting the \fInoproxy\fP string to "" (an empty string) explicitly enables -the proxy for all host names, even if there is an environment variable set for -it. - -Enter IPv6 numerical addresses in the list of host names without enclosing -brackets: - - "example.com,::1,localhost" - -Since 7.86.0, IP addresses specified to this option can be provided using CIDR -notation: 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". - -The application does not have to keep the string around after setting this -option. -.SH "Environment variables" -If there is an environment variable called \fBno_proxy\fP (or \fBNO_PROXY\fP), -it is used if the \fICURLOPT_NOPROXY(3)\fP option is not set. It works exactly -the same way. -.SH DEFAULT -NULL -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* accept various URLs */ - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* use this proxy */ - curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); - /* ... but make sure this host name is not proxied */ - curl_easy_setopt(curl, CURLOPT_NOPROXY, "www.example.com"); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYAUTH (3), -.BR CURLOPT_PROXYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.md b/docs/libcurl/opts/CURLOPT_NOPROXY.md new file mode 100644 index 00000000000..91292e22ea2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.md @@ -0,0 +1,91 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_NOPROXY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_PROXYAUTH (3) + - CURLOPT_PROXYTYPE (3) +--- + +# NAME + +CURLOPT_NOPROXY - disable proxy use for specific hosts + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROXY, char *noproxy); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string. The string consists of a comma +separated list of host names that do not require a proxy to get reached, even +if one is specified. The only wildcard available 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, "ample.com" would match ample.com, ample.com:80, +and www.ample.com, but not www.example.com or ample.com.org. + +Setting the *noproxy* string to "" (an empty string) explicitly enables +the proxy for all host names, even if there is an environment variable set for +it. + +Enter IPv6 numerical addresses in the list of host names without enclosing +brackets: + + "example.com,::1,localhost" + +Since 7.86.0, IP addresses specified to this option can be provided using CIDR +notation: 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". + +The application does not have to keep the string around after setting this +option. + +# Environment variables + +If there is an environment variable called **no_proxy** (or **NO_PROXY**), +it is used if the CURLOPT_NOPROXY(3) option is not set. It works exactly +the same way. + +# DEFAULT + +NULL + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* accept various URLs */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* use this proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); + /* ... but make sure this host name is not proxied */ + curl_easy_setopt(curl, CURLOPT_NOPROXY, "www.example.com"); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 deleted file mode 100644 index 290f44e42df..00000000000 --- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_NOSIGNAL 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_NOSIGNAL \- skip all signal handling -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOSIGNAL, long onoff); -.fi -.SH DESCRIPTION -If \fIonoff\fP is 1, libcurl uses no functions that install signal handlers or -any functions that cause signals to be sent to the process. This option is -here to allow multi-threaded unix applications to still set/use all timeout -options etc, without risking getting signals. - -If this option is set and libcurl has been built with the standard name -resolver, timeouts cannot occur while the name resolve takes place. Consider -building libcurl with the c-ares or threaded resolver backends to enable -asynchronous DNS lookups, to enable timeouts for name resolves without the use -of signals. - -Setting \fICURLOPT_NOSIGNAL(3)\fP to 1 makes libcurl NOT ask the system to -ignore SIGPIPE signals, which otherwise are sent by the system when trying to -send data to a socket which is closed in the other end. libcurl makes an -effort to never cause such SIGPIPE signals to trigger, but some operating -systems have no way to avoid them and even on those that have there are some -corner cases when they may still happen, contrary to our desire. In addition, -using \fICURLAUTH_NTLM_WB\fP authentication could cause a SIGCHLD signal to be -raised. -.SH DEFAULT -0 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - - curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH SEE ALSO -.BR CURLOPT_TIMEOUT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.md b/docs/libcurl/opts/CURLOPT_NOSIGNAL.md new file mode 100644 index 00000000000..50ae65ccade --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_NOSIGNAL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_NOSIGNAL - skip all signal handling + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOSIGNAL, long onoff); +~~~ + +# DESCRIPTION + +If *onoff* is 1, libcurl uses no functions that install signal handlers or +any functions that cause signals to be sent to the process. This option is +here to allow multi-threaded unix applications to still set/use all timeout +options etc, without risking getting signals. + +If this option is set and libcurl has been built with the standard name +resolver, timeouts cannot occur while the name resolve takes place. Consider +building libcurl with the c-ares or threaded resolver backends to enable +asynchronous DNS lookups, to enable timeouts for name resolves without the use +of signals. + +Setting CURLOPT_NOSIGNAL(3) to 1 makes libcurl NOT ask the system to +ignore SIGPIPE signals, which otherwise are sent by the system when trying to +send data to a socket which is closed in the other end. libcurl makes an +effort to never cause such SIGPIPE signals to trigger, but some operating +systems have no way to avoid them and even on those that have there are some +corner cases when they may still happen, contrary to our desire. In addition, +using *CURLAUTH_NTLM_WB* authentication could cause a SIGCHLD signal to be +raised. + +# DEFAULT + +0 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + + curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md similarity index 50% rename from docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 rename to docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md index e4c227a8977..f3e7ef85503 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md @@ -1,46 +1,44 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_OPENSOCKETDATA 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_OPENSOCKETDATA \- pointer passed to open socket callback -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_OPENSOCKETDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CLOSESOCKETFUNCTION (3) + - CURLOPT_OPENSOCKETFUNCTION (3) + - CURLOPT_SOCKOPTFUNCTION (3) +--- + +# NAME + +CURLOPT_OPENSOCKETDATA - pointer passed to open socket callback + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP that is untouched by libcurl and passed as the first +~~~ + +# DESCRIPTION + +Pass a *pointer* that is untouched by libcurl and passed as the first argument in the open socket callback set with -\fICURLOPT_OPENSOCKETFUNCTION(3)\fP. -.SH DEFAULT +CURLOPT_OPENSOCKETFUNCTION(3). + +# DEFAULT + The default value of this parameter is NULL. -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c /* make libcurl use the already established socket 'sockfd' */ static curl_socket_t opensocket(void *clientp, @@ -83,12 +81,12 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.17.1 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CLOSESOCKETFUNCTION (3), -.BR CURLOPT_OPENSOCKETFUNCTION (3), -.BR CURLOPT_SOCKOPTFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md similarity index 53% rename from docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md index 9d1a9fd4ca2..125ccff6887 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md @@ -1,32 +1,22 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_OPENSOCKETFUNCTION 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_OPENSOCKETFUNCTION \- callback for opening socket -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_OPENSOCKETFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CLOSESOCKETFUNCTION (3) + - CURLOPT_OPENSOCKETFUNCTION (3) + - CURLOPT_SOCKOPTFUNCTION (3) +--- + +# NAME + +CURLOPT_OPENSOCKETFUNCTION - callback for opening socket + +# SYNOPSIS + +~~~c #include typedef enum { @@ -46,41 +36,50 @@ curl_socket_t opensocket_callback(void *clientp, struct curl_sockaddr *address); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. -This callback function gets called by libcurl instead of the \fIsocket(2)\fP -call. The callback's \fIpurpose\fP argument identifies the exact purpose for -this particular socket. \fICURLSOCKTYPE_IPCXN\fP is for IP based connections +This callback function gets called by libcurl instead of the *socket(2)* +call. The callback's *purpose* argument identifies the exact purpose for +this particular socket. *CURLSOCKTYPE_IPCXN* is for IP based connections and is the only purpose currently used in libcurl. Future versions of libcurl may support more purposes. -The \fIclientp\fP pointer contains whatever user-defined value set using the -\fICURLOPT_OPENSOCKETDATA(3)\fP function. +The *clientp* pointer contains whatever user-defined value set using the +CURLOPT_OPENSOCKETDATA(3) function. -The callback gets the resolved peer address as the \fIaddress\fP argument and +The callback gets the resolved peer address as the *address* argument and is allowed to modify the address or refuse to connect completely. The callback -function should return the newly created socket or \fICURL_SOCKET_BAD\fP in +function should return the newly created socket or *CURL_SOCKET_BAD* in case no connection could be established or another error was detected. Any -additional \fIsetsockopt(2)\fP calls can of course be done on the socket at -the user's discretion. A \fICURL_SOCKET_BAD\fP return value from the callback +additional *setsockopt(2)* calls can of course be done on the socket at +the user's discretion. A *CURL_SOCKET_BAD* return value from the callback function signals an unrecoverable error to libcurl and it returns -\fICURLE_COULDNT_CONNECT\fP from the function that triggered this callback. +*CURLE_COULDNT_CONNECT* from the function that triggered this callback. This return code can be used for IP address block listing. If you want to pass in a socket with an already established connection, pass the socket back with this callback and then use -\fICURLOPT_SOCKOPTFUNCTION(3)\fP to signal that it already is connected. -.SH DEFAULT +CURLOPT_SOCKOPTFUNCTION(3) to signal that it already is connected. + +# DEFAULT + The default behavior is the equivalent of this: -.nf +~~~c return socket(addr->family, addr->socktype, addr->protocol); -.fi -.SH PROTOCOLS +~~~ + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c /* make libcurl use the already established socket 'sockfd' */ static curl_socket_t opensocket(void *clientp, @@ -122,12 +121,12 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.17.1. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CLOSESOCKETFUNCTION (3), -.BR CURLOPT_OPENSOCKETFUNCTION (3), -.BR CURLOPT_SOCKOPTFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_PASSWORD.3 b/docs/libcurl/opts/CURLOPT_PASSWORD.3 deleted file mode 100644 index 73d8627c0b2..00000000000 --- a/docs/libcurl/opts/CURLOPT_PASSWORD.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PASSWORD 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PASSWORD \- password to use in authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PASSWORD, char *pwd); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should be pointing to the null-terminated -password to use for the transfer. - -The \fICURLOPT_PASSWORD(3)\fP option should be used in conjunction with the -\fICURLOPT_USERNAME(3)\fP option. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -blank -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - curl_easy_setopt(curl, CURLOPT_PASSWORD, "qwerty"); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_HTTPAUTH (3), -.BR CURLOPT_PROXYAUTH (3), -.BR CURLOPT_USERNAME (3), -.BR CURLOPT_USERPWD (3) diff --git a/docs/libcurl/opts/CURLOPT_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PASSWORD.md new file mode 100644 index 00000000000..9849802d12b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PASSWORD.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PASSWORD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPAUTH (3) + - CURLOPT_PROXYAUTH (3) + - CURLOPT_USERNAME (3) + - CURLOPT_USERPWD (3) +--- + +# NAME + +CURLOPT_PASSWORD - password to use in authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PASSWORD, char *pwd); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should be pointing to the +null-terminated password to use for the transfer. + +The CURLOPT_PASSWORD(3) option should be used in conjunction with the +CURLOPT_USERNAME(3) option. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +blank + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_PASSWORD, "qwerty"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 deleted file mode 100644 index 702d979197d..00000000000 --- a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PATH_AS_IS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PATH_AS_IS \- do not handle dot dot sequences -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PATH_AS_IS, long leaveit); -.fi -.SH DESCRIPTION -Set the long \fIleaveit\fP to 1, to explicitly tell libcurl to not alter the -given path before passing it on to the server. - -This instructs libcurl to NOT squash sequences of "/../" or "/./" that may -exist in the URL's path part and that is supposed to be removed according to -RFC 3986 section 5.2.4. - -Some server implementations are known to (erroneously) require the dot dot -sequences to remain in the path and some clients want to pass these on in -order to try out server implementations. - -By default libcurl normalizes such sequences before using the path. - -The corresponding flag for the \fIcurl_url_set(3)\fP function is called -\fBCURLU_PATH_AS_IS\fP. -.SH DEFAULT -0 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, - "https://example.com/../../etc/password"); - - curl_easy_setopt(curl, CURLOPT_PATH_AS_IS, 1L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.42.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_url_set (3), -.BR CURLOPT_STDERR (3), -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md new file mode 100644 index 00000000000..49946917243 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PATH_AS_IS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_STDERR (3) + - CURLOPT_URL (3) + - curl_url_set (3) +--- + +# NAME + +CURLOPT_PATH_AS_IS - do not handle dot dot sequences + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PATH_AS_IS, long leaveit); +~~~ + +# DESCRIPTION + +Set the long *leaveit* to 1, to explicitly tell libcurl to not alter the +given path before passing it on to the server. + +This instructs libcurl to NOT squash sequences of "/../" or "/./" that may +exist in the URL's path part and that is supposed to be removed according to +RFC 3986 section 5.2.4. + +Some server implementations are known to (erroneously) require the dot dot +sequences to remain in the path and some clients want to pass these on in +order to try out server implementations. + +By default libcurl normalizes such sequences before using the path. + +The corresponding flag for the curl_url_set(3) function is called +**CURLU_PATH_AS_IS**. + +# DEFAULT + +0 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, + "https://example.com/../../etc/password"); + + curl_easy_setopt(curl, CURLOPT_PATH_AS_IS, 1L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.42.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md similarity index 52% rename from docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 rename to docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md index 9a72fa85f41..af3ed12ba2d 100644 --- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md @@ -1,61 +1,60 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PINNEDPUBLICKEY 3 "27 Aug 2014" libcurl libcurl -.SH NAME -CURLOPT_PINNEDPUBLICKEY \- pinned public key -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PINNEDPUBLICKEY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_CAPATH (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PINNEDPUBLICKEY - pinned public key + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PINNEDPUBLICKEY, char *pinnedpubkey); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a null-terminated string as parameter. The string can be the -file name of your pinned public key. The file format expected is "PEM" or "DER". -The string can also be any number of base64 encoded sha256 hashes preceded by -"sha256//" and separated by ";" +file name of your pinned public key. The file format expected is "PEM" or +"DER". The string can also be 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 \fICURLOPT_SSL_VERIFYPEER(3)\fP. If you -turn off that option then the peer is still verified by public key. +This option is independent of option CURLOPT_SSL_VERIFYPEER(3). If you turn +off that option then the peer is still verified by public key. -On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. +On mismatch, *CURLE_SSL_PINNEDPUBKEYNOTMATCH* is returned. The application does not have to keep the string around after setting this option. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -73,11 +72,13 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH PUBLIC KEY EXTRACTION +~~~ + +# PUBLIC KEY EXTRACTION + If you do not have the server's public key file you can extract it from the server's certificate. -.nf +~~~ # retrieve the server's certificate if you do not already have it # # be sure to examine the certificate to see if it is what you expected @@ -88,53 +89,55 @@ server's certificate. # - If you do not have sed, then just copy the certificate into a file: # Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----. # -openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem +openssl s_client -servername www.example.com -connect www.example.com:443 \ + < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem # extract public key in pem format from certificate openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem # convert public key from pem to der -openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem -out www.example.com.pubkey.der +openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem \ + -out www.example.com.pubkey.der # sha256 hash and base64 encode der to string for use openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64 -.fi +~~~ + The public key in PEM format contains a header, base64 data and a footer: -.nf +~~~ -----BEGIN PUBLIC KEY----- [BASE 64 DATA] -----END PUBLIC KEY----- -.fi -.SH AVAILABILITY -PEM/DER support: +~~~ + +# AVAILABILITY - 7.39.0: OpenSSL, GnuTLS +## PEM/DER support - 7.43.0: wolfSSL +7.39.0: OpenSSL, GnuTLS - 7.47.0: mbedTLS +7.43.0: wolfSSL - 7.54.1: Secure Transport on macOS 10.7+/iOS 10+ +7.47.0: mbedTLS - 7.58.1: Schannel +7.54.1: Secure Transport on macOS 10.7+/iOS 10+ -sha256 support: +7.58.1: Schannel - 7.44.0: OpenSSL, GnuTLS and wolfSSL +## sha256 support - 7.47.0: mbedTLS +7.44.0: OpenSSL, GnuTLS and wolfSSL - 7.54.1: Secure Transport on macOS 10.7+/iOS 10+ +7.47.0: mbedTLS - 7.58.1: Schannel +7.54.1: Secure Transport on macOS 10.7+/iOS 10+ + +7.58.1: Schannel Other SSL backends not supported. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_CAPATH (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 b/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 deleted file mode 100644 index 645f788f98c..00000000000 --- a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PIPEWAIT 3 "12 May 2015" libcurl libcurl -.SH NAME -CURLOPT_PIPEWAIT \- wait for multiplexing -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PIPEWAIT, long wait); -.fi -.SH DESCRIPTION -Set \fIwait\fP to 1L to tell libcurl to prefer to wait for a connection to -confirm or deny that it can do multiplexing before continuing. - -When about to perform a new transfer that allows multiplexing, libcurl checks -for existing connections to use. If no such connection exists it immediately -continues and creates a fresh new connection to use. - -By setting this option to 1 - and having \fICURLMOPT_PIPELINING(3)\fP enabled -for the multi handle this transfer is associated with - libcurl instead waits -for the connection to reveal if it is possible to multiplex on before it -continues. This enables libcurl to much better keep the number of connections -to a minimum when using multiplexing protocols. - -With this option set, libcurl prefers to wait and reuse an existing connection -for multiplexing rather than the opposite: prefer to open a new connection -rather than waiting. - -The waiting time is as long as it takes for the connection to get up and for -libcurl to get the necessary response back that informs it about its protocol -and support level. -.SH DEFAULT -0 (off) -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PIPEWAIT, 1L); - - /* now add this easy handle to the multi handle */ - } -} -.fi -.SH AVAILABILITY -Added in 7.43.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_MAX_HOST_CONNECTIONS (3), -.BR CURLMOPT_PIPELINING (3), -.BR CURLOPT_FORBID_REUSE (3), -.BR CURLOPT_FRESH_CONNECT (3) diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.md b/docs/libcurl/opts/CURLOPT_PIPEWAIT.md new file mode 100644 index 00000000000..1be844dd042 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PIPEWAIT.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PIPEWAIT +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_MAX_HOST_CONNECTIONS (3) + - CURLMOPT_PIPELINING (3) + - CURLOPT_FORBID_REUSE (3) + - CURLOPT_FRESH_CONNECT (3) +--- + +# NAME + +CURLOPT_PIPEWAIT - wait for multiplexing + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PIPEWAIT, long wait); +~~~ + +# DESCRIPTION + +Set *wait* to 1L to tell libcurl to prefer to wait for a connection to +confirm or deny that it can do multiplexing before continuing. + +When about to perform a new transfer that allows multiplexing, libcurl checks +for existing connections to use. If no such connection exists it immediately +continues and creates a fresh new connection to use. + +By setting this option to 1 - and having CURLMOPT_PIPELINING(3) enabled +for the multi handle this transfer is associated with - libcurl instead waits +for the connection to reveal if it is possible to multiplex on before it +continues. This enables libcurl to much better keep the number of connections +to a minimum when using multiplexing protocols. + +With this option set, libcurl prefers to wait and reuse an existing connection +for multiplexing rather than the opposite: prefer to open a new connection +rather than waiting. + +The waiting time is as long as it takes for the connection to get up and for +libcurl to get the necessary response back that informs it about its protocol +and support level. + +# DEFAULT + +0 (off) + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PIPEWAIT, 1L); + + /* now add this easy handle to the multi handle */ + } +} +~~~ + +# AVAILABILITY + +Added in 7.43.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PORT.3 b/docs/libcurl/opts/CURLOPT_PORT.3 deleted file mode 100644 index 4b6667ba890..00000000000 --- a/docs/libcurl/opts/CURLOPT_PORT.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PORT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PORT \- remote port number to connect to -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PORT, long number); -.fi -.SH DESCRIPTION -We discourage using this option since its scope is not obvious and hard to -predict. Set the preferred port number in the URL instead. - -This option sets \fInumber\fP to be the remote port number to connect to, -instead of the one specified in the URL or the default port for the used -protocol. - -Usually, you just let the URL decide which port to use but this allows the -application to override that. - -While this option accepts a 'long', a port number is an unsigned 16 bit number -and therefore using a port number lower than zero or over 65535 causes a -\fBCURLE_BAD_FUNCTION_ARGUMENT\fP error. -.SH DEFAULT -By default this is 0 which makes it not used. This also makes port number zero -impossible to set with this API. -.SH PROTOCOLS -Used for all protocols that speak to a port number. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_PORT, 8080L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLINFO_PRIMARY_PORT (3), -.BR CURLOPT_STDERR (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_PORT.md b/docs/libcurl/opts/CURLOPT_PORT.md new file mode 100644 index 00000000000..42dc80133b2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PORT.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PORT +Section: 3 +Source: libcurl +See-also: + - CURLINFO_PRIMARY_PORT (3) + - CURLOPT_STDERR (3) + - CURLOPT_URL (3) +--- + +# NAME + +CURLOPT_PORT - remote port number to connect to + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PORT, long number); +~~~ + +# DESCRIPTION + +We discourage using this option since its scope is not obvious and hard to +predict. Set the preferred port number in the URL instead. + +This option sets *number* to be the remote port number to connect to, +instead of the one specified in the URL or the default port for the used +protocol. + +Usually, you just let the URL decide which port to use but this allows the +application to override that. + +While this option accepts a 'long', a port number is an unsigned 16 bit number +and therefore using a port number lower than zero or over 65535 causes a +**CURLE_BAD_FUNCTION_ARGUMENT** error. + +# DEFAULT + +By default this is 0 which makes it not used. This also makes port number zero +impossible to set with this API. + +# PROTOCOLS + +Used for all protocols that speak to a port number. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PORT, 8080L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_POST.3 b/docs/libcurl/opts/CURLOPT_POST.3 deleted file mode 100644 index 182b59cb83d..00000000000 --- a/docs/libcurl/opts/CURLOPT_POST.3 +++ /dev/null @@ -1,104 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_POST 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_POST \- make an HTTP POST -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post); -.fi -.SH DESCRIPTION -A parameter set to 1 tells libcurl to do a regular HTTP post. This also makes -libcurl use a "Content-Type: application/x-www-form-urlencoded" header. This -is the most commonly used POST method. - -Use one of \fICURLOPT_POSTFIELDS(3)\fP or \fICURLOPT_COPYPOSTFIELDS(3)\fP -options to specify what data to post and \fICURLOPT_POSTFIELDSIZE(3)\fP or -\fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP to set the data size. - -Optionally, you can provide data to POST using the -\fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_READDATA(3)\fP options but then -you must make sure to not set \fICURLOPT_POSTFIELDS(3)\fP to anything but -NULL. When providing data with a callback, you must transmit it using chunked -transfer-encoding or you must set the size of the data with the -\fICURLOPT_POSTFIELDSIZE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP -options. To enable chunked encoding, you simply pass in the appropriate -Transfer-Encoding header, see the post-callback.c example. - -You can override the default POST Content-Type: header by setting your own -with \fICURLOPT_HTTPHEADER(3)\fP. - -Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. -You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. - -If you use POST to an HTTP 1.1 server, you can send data without knowing the -size before starting the POST if you use chunked encoding. You enable this by -adding a header like "Transfer-Encoding: chunked" with -\fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you -must specify the size in the request. (Since 7.66.0, libcurl automatically -uses chunked encoding for POSTs if the size is unknown.) - -When setting \fICURLOPT_POST(3)\fP to 1, libcurl automatically sets -\fICURLOPT_NOBODY(3)\fP and \fICURLOPT_HTTPGET(3)\fP to 0. - -If you issue a POST request and then want to make a HEAD or GET using the same -reused handle, you must explicitly set the new request type using -\fICURLOPT_NOBODY(3)\fP or \fICURLOPT_HTTPGET(3)\fP or similar. - -When setting \fICURLOPT_POST(3)\fP to 0, libcurl resets the request type to -the default to disable the POST. Typically that would mean it's reset to GET. -Instead you should set a new request type explicitly as described above. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_POST, 1L); - - /* set up the read callback with CURLOPT_READFUNCTION */ - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTPPOST (3), -.BR CURLOPT_POSTFIELDS (3), -.BR CURLOPT_PUT (3) diff --git a/docs/libcurl/opts/CURLOPT_POST.md b/docs/libcurl/opts/CURLOPT_POST.md new file mode 100644 index 00000000000..fd3c0b2c908 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POST.md @@ -0,0 +1,102 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_POST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPPOST (3) + - CURLOPT_POSTFIELDS (3) + - CURLOPT_PUT (3) +--- + +# NAME + +CURLOPT_POST - make an HTTP POST + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post); +~~~ + +# DESCRIPTION + +A parameter set to 1 tells libcurl to do a regular HTTP post. This also makes +libcurl use a "Content-Type: application/x-www-form-urlencoded" header. This +is the most commonly used POST method. + +Use one of CURLOPT_POSTFIELDS(3) or CURLOPT_COPYPOSTFIELDS(3) +options to specify what data to post and CURLOPT_POSTFIELDSIZE(3) or +CURLOPT_POSTFIELDSIZE_LARGE(3) to set the data size. + +Optionally, you can provide data to POST using the +CURLOPT_READFUNCTION(3) and CURLOPT_READDATA(3) options but then +you must make sure to not set CURLOPT_POSTFIELDS(3) to anything but +NULL. When providing data with a callback, you must transmit it using chunked +transfer-encoding or you must set the size of the data with the +CURLOPT_POSTFIELDSIZE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3) +options. To enable chunked encoding, you simply pass in the appropriate +Transfer-Encoding header, see the post-callback.c example. + +You can override the default POST Content-Type: header by setting your own +with CURLOPT_HTTPHEADER(3). + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with CURLOPT_HTTPHEADER(3) as usual. + +If you use POST to an HTTP 1.1 server, you can send data without knowing the +size before starting the POST if you use chunked encoding. You enable this by +adding a header like "Transfer-Encoding: chunked" with +CURLOPT_HTTPHEADER(3). With HTTP 1.0 or without chunked transfer, you +must specify the size in the request. (Since 7.66.0, libcurl automatically +uses chunked encoding for POSTs if the size is unknown.) + +When setting CURLOPT_POST(3) to 1, libcurl automatically sets +CURLOPT_NOBODY(3) and CURLOPT_HTTPGET(3) to 0. + +If you issue a POST request and then want to make a HEAD or GET using the same +reused handle, you must explicitly set the new request type using +CURLOPT_NOBODY(3) or CURLOPT_HTTPGET(3) or similar. + +When setting CURLOPT_POST(3) to 0, libcurl resets the request type to +the default to disable the POST. Typically that would mean it's reset to GET. +Instead you should set a new request type explicitly as described above. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_POST, 1L); + + /* set up the read callback with CURLOPT_READFUNCTION */ + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 deleted file mode 100644 index 6efdb95316e..00000000000 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 +++ /dev/null @@ -1,126 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_POSTFIELDS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_POSTFIELDS \- data to POST to server -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata); -.fi -.SH DESCRIPTION -Pass a char * as parameter, pointing to the data buffer to use in an HTTP POST -operation. The data must be formatted and encoded the way you want the server -to receive it. libcurl does not convert or encode it in any way. For example, -the web server may assume that this data is URL encoded. - -The data pointed to is NOT copied by the library: as a consequence, it must be -preserved by the calling application until the associated transfer finishes. -This behavior can be changed (so libcurl does copy the data) by instead using -the \fICURLOPT_COPYPOSTFIELDS(3)\fP option. - -This POST is a normal \fBapplication/x-www-form-urlencoded\fP kind (and -libcurl sets that Content-Type by default when this option is used), which is -commonly used by HTML forms. Change Content-Type with -\fICURLOPT_HTTPHEADER(3)\fP. - -You can use \fIcurl_easy_escape(3)\fP to URL encode your data, if -necessary. It returns a pointer to an encoded string that can be passed as -\fIpostdata\fP. - -Using \fICURLOPT_POSTFIELDS(3)\fP implies setting \fICURLOPT_POST(3)\fP to 1. - -If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl gets the -POST data from the read callback. If you want to send a zero-byte POST set -\fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP -to 1 and \fICURLOPT_POSTFIELDSIZE(3)\fP to 0. - -libcurl assumes this option points to a null-terminated string unless you also -set \fICURLOPT_POSTFIELDSIZE(3)\fP to specify the length of the provided data, -which then is strictly required if you want to send off null bytes included in -the data. - -Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header, -and libcurl adds that header automatically if the POST is either known to be -larger than 1MB or if the expected size is unknown. You can disable this -header with \fICURLOPT_HTTPHEADER(3)\fP as usual. - -To make \fBmultipart/formdata\fP posts, check out the -\fICURLOPT_MIMEPOST(3)\fP option combined with \fIcurl_mime_init(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -/* send an application/x-www-form-urlencoded POST */ -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - const char *data = "data to send"; - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* size of the POST data if strlen() is not good enough */ - curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); - - /* pass in a pointer to the data - libcurl does not copy */ - curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); - - curl_easy_perform(curl); - } - - /* send an application/json POST */ - curl = curl_easy_init(); - if(curl) { - const char *json = "{\\"name\\": \\"daniel\\"}"; - struct curl_slist *slist1 = NULL; - slist1 = curl_slist_append(slist1, "Content-Type: application/json"); - slist1 = curl_slist_append(slist1, "Accept: application/json"); - - /* set custom headers */ - curl_easy_setopt(curl, CURLOPT_HTTPHEADER, slist1); - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* pass in a pointer to the data - libcurl does not copy */ - curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_COPYPOSTFIELDS (3), -.BR CURLOPT_MIMEPOST (3), -.BR CURLOPT_POSTFIELDSIZE (3), -.BR CURLOPT_READFUNCTION (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md new file mode 100644 index 00000000000..409e4100afe --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md @@ -0,0 +1,124 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_POSTFIELDS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_COPYPOSTFIELDS (3) + - CURLOPT_MIMEPOST (3) + - CURLOPT_POSTFIELDSIZE (3) + - CURLOPT_READFUNCTION (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_POSTFIELDS - data to POST to server + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, pointing to the data buffer to use in an +HTTP POST operation. The data must be formatted and encoded the way you want +the server to receive it. libcurl does not convert or encode it in any +way. For example, the web server may assume that this data is URL encoded. + +The data pointed to is NOT copied by the library: as a consequence, it must be +preserved by the calling application until the associated transfer finishes. +This behavior can be changed (so libcurl does copy the data) by instead using +the CURLOPT_COPYPOSTFIELDS(3) option. + +This POST is a normal **application/x-www-form-urlencoded** kind (and +libcurl sets that Content-Type by default when this option is used), which is +commonly used by HTML forms. Change Content-Type with +CURLOPT_HTTPHEADER(3). + +You can use curl_easy_escape(3) to URL encode your data, if +necessary. It returns a pointer to an encoded string that can be passed as +*postdata*. + +Using CURLOPT_POSTFIELDS(3) implies setting CURLOPT_POST(3) to 1. + +If CURLOPT_POSTFIELDS(3) is explicitly set to NULL then libcurl gets the +POST data from the read callback. If you want to send a zero-byte POST set +CURLOPT_POSTFIELDS(3) to an empty string, or set CURLOPT_POST(3) +to 1 and CURLOPT_POSTFIELDSIZE(3) to 0. + +libcurl assumes this option points to a null-terminated string unless you also +set CURLOPT_POSTFIELDSIZE(3) to specify the length of the provided data, +which then is strictly required if you want to send off null bytes included in +the data. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header, +and libcurl adds that header automatically if the POST is either known to be +larger than 1MB or if the expected size is unknown. You can disable this +header with CURLOPT_HTTPHEADER(3) as usual. + +To make **multipart/formdata** posts, check out the +CURLOPT_MIMEPOST(3) option combined with curl_mime_init(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +/* send an application/x-www-form-urlencoded POST */ +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + const char *data = "data to send"; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* size of the POST data if strlen() is not good enough */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); + + /* pass in a pointer to the data - libcurl does not copy */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); + } + + /* send an application/json POST */ + curl = curl_easy_init(); + if(curl) { + const char *json = "{\"name\": \"daniel\"}"; + struct curl_slist *slist1 = NULL; + slist1 = curl_slist_append(slist1, "Content-Type: application/json"); + slist1 = curl_slist_append(slist1, "Accept: application/json"); + + /* set custom headers */ + curl_easy_setopt(curl, CURLOPT_HTTPHEADER, slist1); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* pass in a pointer to the data - libcurl does not copy */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 deleted file mode 100644 index 75ec0529152..00000000000 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_POSTFIELDSIZE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_POSTFIELDSIZE \- size of POST data pointed to -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE, long size); -.fi -.SH DESCRIPTION -If you want to post static data to the server without having libcurl do a -strlen() to measure the data size, this option must be used. When this option -is used you can post fully binary data, which otherwise is likely to fail. If -this size is set to -1, libcurl uses strlen() to get the size or relies on the -\fICURLOPT_READFUNCTION(3)\fP (if used) to signal the end of data. - -If you post more than 2GB, use \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. -.SH DEFAULT --1 -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -#include /* for strlen */ - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - const char *data = "data to send"; - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* size of the POST data */ - curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long) strlen(data)); - - curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_POSTFIELDS (3), -.BR CURLOPT_POSTFIELDSIZE_LARGE (3) diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md new file mode 100644 index 00000000000..d086809cba3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_POSTFIELDSIZE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_POSTFIELDS (3) + - CURLOPT_POSTFIELDSIZE_LARGE (3) +--- + +# NAME + +CURLOPT_POSTFIELDSIZE - size of POST data pointed to + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE, long size); +~~~ + +# DESCRIPTION + +If you want to post static data to the server without having libcurl do a +strlen() to measure the data size, this option must be used. When this option +is used you can post fully binary data, which otherwise is likely to fail. If +this size is set to -1, libcurl uses strlen() to get the size or relies on the +CURLOPT_READFUNCTION(3) (if used) to signal the end of data. + +If you post more than 2GB, use CURLOPT_POSTFIELDSIZE_LARGE(3). + +# DEFAULT + +-1 + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +#include /* for strlen */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + const char *data = "data to send"; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long) strlen(data)); + + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 deleted file mode 100644 index c09feea9a32..00000000000 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_POSTFIELDSIZE_LARGE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_POSTFIELDSIZE_LARGE \- size of POST data pointed to -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE_LARGE, - curl_off_t size); -.SH DESCRIPTION -If you want to post static data to the server without having libcurl do a -strlen() to measure the data size, this option must be used. When this option -is used you can post fully binary data, which otherwise is likely to fail. If -this size is set to -1, libcurl uses strlen() to get the size or relies on the -\fICURLOPT_READFUNCTION(3)\fP (if used) to signal the end of data. -.SH DEFAULT --1 -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -extern char *large_chunk; /* pointer to somewhere */ - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - const char *data = large_chunk; - curl_off_t length_of_data; /* set somehow */ - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* size of the POST data */ - curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, length_of_data); - - curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_COPYPOSTFIELDS (3), -.BR CURLOPT_POSTFIELDS (3), -.BR CURLOPT_POSTFIELDSIZE (3) diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md new file mode 100644 index 00000000000..36fc0ff959a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_POSTFIELDSIZE_LARGE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_COPYPOSTFIELDS (3) + - CURLOPT_POSTFIELDS (3) + - CURLOPT_POSTFIELDSIZE (3) +--- + +# NAME + +CURLOPT_POSTFIELDSIZE_LARGE - size of POST data pointed to + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE_LARGE, + curl_off_t size); +~~~ + +# DESCRIPTION + +If you want to post static data to the server without having libcurl do a +strlen() to measure the data size, this option must be used. When this option +is used you can post fully binary data, which otherwise is likely to fail. If +this size is set to -1, libcurl uses strlen() to get the size or relies on the +CURLOPT_READFUNCTION(3) (if used) to signal the end of data. + +# DEFAULT + +-1 + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +extern char *large_chunk; /* pointer to somewhere */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + const char *data = large_chunk; + curl_off_t length_of_data; /* set somehow */ + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, length_of_data); + + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 b/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 deleted file mode 100644 index 33c46c7a51e..00000000000 --- a/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_POSTQUOTE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_POSTQUOTE \- (S)FTP commands to run after the transfer -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTQUOTE, - struct curl_slist *cmds); -.fi -.SH DESCRIPTION -Pass a pointer to a linked list of FTP or SFTP commands to pass to the server -after your FTP transfer request. The commands are only issues if no error -occur. The linked list should be a fully valid list of struct curl_slist -structs properly filled in as described for \fICURLOPT_QUOTE(3)\fP. - -Disable this operation again by setting a NULL to this option. -.SH DEFAULT -NULL -.SH PROTOCOLS -SFTP and FTP -.SH EXAMPLE -.nf -int main(void) -{ - struct curl_slist *cmdlist = NULL; - cmdlist = curl_slist_append(cmdlist, "RNFR source-name"); - cmdlist = curl_slist_append(cmdlist, "RNTO new-name"); - - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); - - /* pass in the FTP commands to run after the transfer */ - curl_easy_setopt(curl, CURLOPT_POSTQUOTE, cmdlist); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -If support for the protocols are built-in. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_PREQUOTE (3), -.BR CURLOPT_QUOTE (3) diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md new file mode 100644 index 00000000000..300a1f2c596 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_POSTQUOTE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PREQUOTE (3) + - CURLOPT_QUOTE (3) +--- + +# NAME + +CURLOPT_POSTQUOTE - (S)FTP commands to run after the transfer + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTQUOTE, + struct curl_slist *cmds); +~~~ + +# DESCRIPTION + +Pass a pointer to a linked list of FTP or SFTP commands to pass to the server +after your FTP transfer request. The commands are only issues if no error +occur. The linked list should be a fully valid list of struct curl_slist +structs properly filled in as described for CURLOPT_QUOTE(3). + +Disable this operation again by setting a NULL to this option. + +# DEFAULT + +NULL + +# PROTOCOLS + +SFTP and FTP + +# EXAMPLE + +~~~c +int main(void) +{ + struct curl_slist *cmdlist = NULL; + cmdlist = curl_slist_append(cmdlist, "RNFR source-name"); + cmdlist = curl_slist_append(cmdlist, "RNTO new-name"); + + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + + /* pass in the FTP commands to run after the transfer */ + curl_easy_setopt(curl, CURLOPT_POSTQUOTE, cmdlist); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +If support for the protocols are built-in. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_POSTREDIR.3 b/docs/libcurl/opts/CURLOPT_POSTREDIR.3 deleted file mode 100644 index da7d826d7ab..00000000000 --- a/docs/libcurl/opts/CURLOPT_POSTREDIR.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_POSTREDIR 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_POSTREDIR \- how to act on an HTTP POST redirect -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTREDIR, - long bitmask); -.SH DESCRIPTION -Pass a bitmask to control how libcurl acts on redirects after POSTs that get a -301, 302 or 303 response back. A parameter with bit 0 set (value -\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 7231 (section -6.4.2 to 6.4.4) and not convert POST requests into GET requests when following -a 301 redirection. Setting bit 1 (value \fBCURL_REDIR_POST_302\fP) makes -libcurl maintain the request method after a 302 redirect whilst setting bit 2 -(value \fBCURL_REDIR_POST_303\fP) makes libcurl maintain the request method -after a 303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience -define that sets all three bits. - -The non-RFC behavior is ubiquitous in web browsers, so the library 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 setting \fICURLOPT_FOLLOWLOCATION(3)\fP. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP(S) -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* a silly POST example */ - curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data=true"); - - /* example.com is redirected, so we tell libcurl to send POST on 301, - 302 and 303 HTTP response codes */ - curl_easy_setopt(curl, CURLOPT_POSTREDIR, CURL_REDIR_POST_ALL); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.17.1. This option was known as CURLOPT_POST301 up to 7.19.0 as it -only supported the 301 then. CURL_REDIR_POST_303 was added in 7.26.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_EFFECTIVE_METHOD (3), -.BR CURLINFO_REDIRECT_COUNT (3), -.BR CURLOPT_FOLLOWLOCATION (3), -.BR CURLOPT_MAXREDIRS (3), -.BR CURLOPT_POSTFIELDS (3) diff --git a/docs/libcurl/opts/CURLOPT_POSTREDIR.md b/docs/libcurl/opts/CURLOPT_POSTREDIR.md new file mode 100644 index 00000000000..0ca04a98cb3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTREDIR.md @@ -0,0 +1,81 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_POSTREDIR +Section: 3 +Source: libcurl +See-also: + - CURLINFO_EFFECTIVE_METHOD (3) + - CURLINFO_REDIRECT_COUNT (3) + - CURLOPT_FOLLOWLOCATION (3) + - CURLOPT_MAXREDIRS (3) + - CURLOPT_POSTFIELDS (3) +--- + +# NAME + +CURLOPT_POSTREDIR - how to act on an HTTP POST redirect + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTREDIR, + long bitmask); +~~~ + +# DESCRIPTION + +Pass a bitmask to control how libcurl acts on redirects after POSTs that get a +301, 302 or 303 response back. A parameter with bit 0 set (value +**CURL_REDIR_POST_301**) tells the library to respect RFC 7231 (section +6.4.2 to 6.4.4) and not convert POST requests into GET requests when following +a 301 redirection. Setting bit 1 (value **CURL_REDIR_POST_302**) makes +libcurl maintain the request method after a 302 redirect whilst setting bit 2 +(value **CURL_REDIR_POST_303**) makes libcurl maintain the request method +after a 303 redirect. The value **CURL_REDIR_POST_ALL** is a convenience +define that sets all three bits. + +The non-RFC behavior is ubiquitous in web browsers, so the library 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 setting CURLOPT_FOLLOWLOCATION(3). + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* a silly POST example */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data=true"); + + /* example.com is redirected, so we tell libcurl to send POST on 301, + 302 and 303 HTTP response codes */ + curl_easy_setopt(curl, CURLOPT_POSTREDIR, CURL_REDIR_POST_ALL); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.17.1. This option was known as CURLOPT_POST301 up to 7.19.0 as it +only supported the 301 then. CURL_REDIR_POST_303 was added in 7.26.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PREQUOTE.3 b/docs/libcurl/opts/CURLOPT_PREQUOTE.3 deleted file mode 100644 index fd5ba04676d..00000000000 --- a/docs/libcurl/opts/CURLOPT_PREQUOTE.3 +++ /dev/null @@ -1,78 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PREQUOTE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PREQUOTE \- commands to run before an FTP transfer -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREQUOTE, - struct curl_slist *cmds); -.fi -.SH DESCRIPTION -Pass a pointer to a linked list of FTP commands to pass to the server after -the transfer type is set. The linked list should be a fully valid list of -struct curl_slist structs properly filled in as described for -\fICURLOPT_QUOTE(3)\fP. Disable this operation again by setting a NULL to this -option. - -These commands are not performed when a directory listing is performed, only -for file transfers. - -While \fICURLOPT_QUOTE(3)\fP and \fICURLOPT_POSTQUOTE(3)\fP work for SFTP, -this option does not. -.SH DEFAULT -NULL -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - struct curl_slist *cmdlist = NULL; - cmdlist = curl_slist_append(cmdlist, "SYST"); - - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); - - /* pass in the FTP commands to run */ - curl_easy_setopt(curl, CURLOPT_PREQUOTE, cmdlist); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Along with the protocol support -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_POSTQUOTE (3), -.BR CURLOPT_QUOTE (3) diff --git a/docs/libcurl/opts/CURLOPT_PREQUOTE.md b/docs/libcurl/opts/CURLOPT_PREQUOTE.md new file mode 100644 index 00000000000..e5192039dc7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PREQUOTE.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PREQUOTE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_POSTQUOTE (3) + - CURLOPT_QUOTE (3) +--- + +# NAME + +CURLOPT_PREQUOTE - commands to run before an FTP transfer + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREQUOTE, + struct curl_slist *cmds); +~~~ + +# DESCRIPTION + +Pass a pointer to a linked list of FTP commands to pass to the server after +the transfer type is set. The linked list should be a fully valid list of +struct curl_slist structs properly filled in as described for +CURLOPT_QUOTE(3). Disable this operation again by setting a NULL to this +option. + +These commands are not performed when a directory listing is performed, only +for file transfers. + +While CURLOPT_QUOTE(3) and CURLOPT_POSTQUOTE(3) work for SFTP, +this option does not. + +# DEFAULT + +NULL + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + struct curl_slist *cmdlist = NULL; + cmdlist = curl_slist_append(cmdlist, "SYST"); + + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); + + /* pass in the FTP commands to run */ + curl_easy_setopt(curl, CURLOPT_PREQUOTE, cmdlist); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Along with the protocol support + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PREREQDATA.3 b/docs/libcurl/opts/CURLOPT_PREREQDATA.3 deleted file mode 100644 index 2d9c4e12c20..00000000000 --- a/docs/libcurl/opts/CURLOPT_PREREQDATA.3 +++ /dev/null @@ -1,75 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) Max Dymond, , 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PREREQDATA 3 "2 Aug 2021" libcurl libcurl -.SH NAME -CURLOPT_PREREQDATA \- pointer passed to the pre-request callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP that is untouched by libcurl and passed as the first -argument in the pre-request callback set with \fICURLOPT_PREREQFUNCTION(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct priv { - void *custom; -}; - -static int prereq_callback(void *clientp, - char *conn_primary_ip, - char *conn_local_ip, - int conn_primary_port, - int conn_local_port) -{ - printf("Connection made to %s:%d\\n", conn_primary_ip, conn_primary_port); - return CURL_PREREQFUNC_OK; -} - -int main(void) -{ - struct priv prereq_data; - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback); - curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.80.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_PRIMARY_IP (3), -.BR CURLINFO_PRIMARY_PORT (3), -.BR CURLOPT_PREREQFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_PREREQDATA.md b/docs/libcurl/opts/CURLOPT_PREREQDATA.md new file mode 100644 index 00000000000..14ba8e302fe --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PREREQDATA.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PREREQDATA +Section: 3 +Source: libcurl +See-also: + - CURLINFO_PRIMARY_IP (3) + - CURLINFO_PRIMARY_PORT (3) + - CURLOPT_PREREQFUNCTION (3) +--- + +# NAME + +CURLOPT_PREREQDATA - pointer passed to the pre-request callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* that is untouched by libcurl and passed as the first +argument in the pre-request callback set with CURLOPT_PREREQFUNCTION(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct priv { + void *custom; +}; + +static int prereq_callback(void *clientp, + char *conn_primary_ip, + char *conn_local_ip, + int conn_primary_port, + int conn_local_port) +{ + printf("Connection made to %s:%d\n", conn_primary_ip, conn_primary_port); + return CURL_PREREQFUNC_OK; +} + +int main(void) +{ + struct priv prereq_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback); + curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.80.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md similarity index 56% rename from docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md index a2e3dd38f71..c8140849475 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md @@ -1,33 +1,23 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) Max Dymond, , 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PREREQFUNCTION 3 "2 Aug 2021" libcurl libcurl -.SH NAME -CURLOPT_PREREQFUNCTION \- user callback called when a connection has been +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PREREQFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLINFO_PRIMARY_IP (3) + - CURLINFO_PRIMARY_PORT (3) + - CURLOPT_PREREQDATA (3) +--- + +# NAME + +CURLOPT_PREREQFUNCTION - user callback called when a connection has been established, but before a request has been made. -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include /* These are the return codes for the pre-request callback. */ @@ -41,7 +31,10 @@ int prereq_callback(void *clientp, int conn_local_port); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. @@ -52,35 +45,51 @@ callback is called once a connection has been established to the server, but before a GET/HEAD/POST/etc request has been sent. This function may be called multiple times if redirections are enabled and are -being followed (see \fICURLOPT_FOLLOWLOCATION(3)\fP). +being followed (see CURLOPT_FOLLOWLOCATION(3)). -The callback function must return \fICURL_PREREQFUNC_OK\fP on success, or -\fICURL_PREREQFUNC_ABORT\fP to cause the transfer to fail. +The callback function must return *CURL_PREREQFUNC_OK* on success, or +*CURL_PREREQFUNC_ABORT* to cause the transfer to fail. This function is passed the following arguments: -.IP conn_primary_ip + +## conn_primary_ip + A null-terminated pointer to a C string containing the primary IP of the remote server established with this connection. For FTP, this is the IP for the control connection. IPv6 addresses are represented without surrounding brackets. -.IP conn_local_ip + +## conn_local_ip + A null-terminated pointer to a C string containing the originating IP for this connection. IPv6 addresses are represented without surrounding brackets. -.IP conn_primary_port + +## conn_primary_port + The primary port number on the remote server established with this connection. For FTP, this is the port for the control connection. This can be a TCP or a UDP port number depending on the protocol. -.IP conn_local_port + +## conn_local_port + The originating port number for this connection. This can be a TCP or a UDP port number depending on the protocol. -.IP clientp -The pointer you set with \fICURLOPT_PREREQDATA(3)\fP. -.SH DEFAULT + +## clientp + +The pointer you set with CURLOPT_PREREQDATA(3). + +# DEFAULT + By default, this is NULL and unused. -.SH PROTOCOLS + +# PROTOCOLS + ALL -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c struct priv { void *custom; }; @@ -91,7 +100,7 @@ static int prereq_callback(void *clientp, int conn_primary_port, int conn_local_port) { - printf("Connection made to %s:%d\\n", conn_primary_ip, conn_primary_port); + printf("Connection made to %s:%d\n", conn_primary_ip, conn_primary_port); return CURL_PREREQFUNC_OK; } @@ -105,12 +114,12 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.80.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_PRIMARY_IP (3), -.BR CURLINFO_PRIMARY_PORT (3), -.BR CURLOPT_PREREQDATA (3) diff --git a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 b/docs/libcurl/opts/CURLOPT_PRE_PROXY.md similarity index 50% rename from docs/libcurl/opts/CURLOPT_PRE_PROXY.3 rename to docs/libcurl/opts/CURLOPT_PRE_PROXY.md index 044d60c0cd6..78a4af032d0 100644 --- a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 +++ b/docs/libcurl/opts/CURLOPT_PRE_PROXY.md @@ -1,55 +1,46 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PRE_PROXY 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PRE_PROXY \- pre-proxy host to use -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PRE_PROXY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPPROXYTUNNEL (3) + - CURLOPT_PROXY (3) +--- + +# NAME + +CURLOPT_PRE_PROXY - pre-proxy host to use + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRE_PROXY, char *preproxy); -.fi -.SH DESCRIPTION -Set the \fIpreproxy\fP to use for the upcoming request. The parameter +~~~ + +# DESCRIPTION + +Set the *preproxy* to use for the upcoming request. The parameter should be a char * to a null-terminated string holding the host name or dotted numerical IP address. A numerical IPv6 address must be written within [brackets]. To specify port number in this string, append :[port] to the end of the host name. The proxy's port number may optionally be specified with the separate -option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl defaults to using +option CURLOPT_PROXYPORT(3). If not specified, libcurl defaults to using port 1080 for proxies. A pre proxy is a SOCKS proxy that curl connects to before it connects to the -HTTP(S) proxy specified in the \fICURLOPT_PROXY(3)\fP option. The pre proxy +HTTP(S) proxy specified in the CURLOPT_PROXY(3) option. The pre proxy can only be a SOCKS proxy. The pre proxy string should be prefixed with [scheme]:// to specify which kind of socks is used. Use socks4://, socks4a://, socks5:// or socks5h:// (the last one to enable socks5 and asking the proxy to do the resolving, also known as -\fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to +*CURLPROXY_SOCKS5_HOSTNAME* type) to request the specific SOCKS version to be used. Otherwise SOCKS4 is used as default. Setting the pre proxy string to "" (an empty string) explicitly disables the @@ -57,15 +48,21 @@ use of a pre proxy. The application does not have to keep the string around after setting this option. -.SH DEFAULT + +# DEFAULT + Default is NULL, meaning no pre proxy is used. When you set a host name to use, do not assume that there is any particular single port number used widely for proxies. Specify it! -.SH PROTOCOLS + +# PROTOCOLS + All except file://. Note that some protocols do not work well over proxy. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -76,12 +73,13 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.52.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_HTTPPROXYTUNNEL (3) diff --git a/docs/libcurl/opts/CURLOPT_PRIVATE.3 b/docs/libcurl/opts/CURLOPT_PRIVATE.3 deleted file mode 100644 index 273ba1df6f3..00000000000 --- a/docs/libcurl/opts/CURLOPT_PRIVATE.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PRIVATE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PRIVATE \- store a private pointer -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRIVATE, void *pointer); -.fi -.SH DESCRIPTION -Pass a void * as parameter, pointing to data that should be associated with -this curl handle. The pointer can subsequently be retrieved using -\fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_PRIVATE(3)\fP option. libcurl -itself never does anything with this data. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct private { - void *custom; -}; - -int main(void) -{ - CURL *curl = curl_easy_init(); - struct private secrets; - if(curl) { - struct private *extracted; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* store a pointer to our private struct */ - curl_easy_setopt(curl, CURLOPT_PRIVATE, &secrets); - - curl_easy_perform(curl); - - /* we can extract the private pointer again too */ - curl_easy_getinfo(curl, CURLINFO_PRIVATE, &extracted); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.3 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_PRIVATE (3), -.BR CURLOPT_STDERR (3), -.BR CURLOPT_VERBOSE (3) diff --git a/docs/libcurl/opts/CURLOPT_PRIVATE.md b/docs/libcurl/opts/CURLOPT_PRIVATE.md new file mode 100644 index 00000000000..571a681b9d9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PRIVATE.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PRIVATE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_PRIVATE (3) + - CURLOPT_STDERR (3) + - CURLOPT_VERBOSE (3) +--- + +# NAME + +CURLOPT_PRIVATE - store a private pointer + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRIVATE, void *pointer); +~~~ + +# DESCRIPTION + +Pass a void * as parameter, pointing to data that should be associated with +this curl handle. The pointer can subsequently be retrieved using +curl_easy_getinfo(3) with the CURLINFO_PRIVATE(3) option. libcurl itself +never does anything with this data. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct private { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + struct private secrets; + if(curl) { + struct private *extracted; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* store a pointer to our private struct */ + curl_easy_setopt(curl, CURLOPT_PRIVATE, &secrets); + + curl_easy_perform(curl); + + /* we can extract the private pointer again too */ + curl_easy_getinfo(curl, CURLINFO_PRIVATE, &extracted); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.3 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 deleted file mode 100644 index 8d1fef100fa..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROGRESSDATA 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROGRESSDATA \- pointer passed to the progress callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP that is untouched by libcurl and passed as the first -argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION(3)\fP. -.SH DEFAULT -The default value of this parameter is NULL. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct progress { - char *private; - size_t size; -}; - -static size_t progress_callback(void *clientp, - double dltotal, - double dlnow, - double ultotal, - double ulnow) -{ - struct progress *memory = clientp; - printf("private: %p\\n", memory->private); - - /* use the values */ - - return 0; /* all is good */ -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct progress data; - - /* pass struct to callback */ - curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &data); - curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress_callback); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_PROGRESSFUNCTION (3), -.BR CURLOPT_XFERINFOFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md new file mode 100644 index 00000000000..276bee82743 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROGRESSDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROGRESSFUNCTION (3) + - CURLOPT_XFERINFOFUNCTION (3) +--- + +# NAME + +CURLOPT_PROGRESSDATA - pointer passed to the progress callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* that is untouched by libcurl and passed as the first +argument in the progress callback set with CURLOPT_PROGRESSFUNCTION(3). + +# DEFAULT + +The default value of this parameter is NULL. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct progress { + char *private; + size_t size; +}; + +static size_t progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow) +{ + struct progress *memory = clientp; + printf("private: %p\n", memory->private); + + /* use the values */ + + return 0; /* all is good */ +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &data); + curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress_callback); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md similarity index 53% rename from docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md index 5682900d5fb..19d84c88900 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md @@ -1,32 +1,22 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROGRESSFUNCTION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROGRESSFUNCTION \- progress meter callback -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROGRESSFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_NOPROGRESS (3) + - CURLOPT_VERBOSE (3) + - CURLOPT_XFERINFOFUNCTION (3) +--- + +# NAME + +CURLOPT_PROGRESSFUNCTION - progress meter callback + +# SYNOPSIS + +~~~c #include int progress_callback(void *clientp, @@ -37,27 +27,29 @@ int progress_callback(void *clientp, CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION, progress_callback); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. This option is deprecated and we encourage users to use the -newer \fICURLOPT_XFERINFOFUNCTION(3)\fP instead, if you can. +newer CURLOPT_XFERINFOFUNCTION(3) instead, if you can. This function gets called by libcurl instead of its internal equivalent with a frequent interval. While data is being transferred it is invoked frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second. -\fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA(3)\fP, it is not +*clientp* is the pointer set with CURLOPT_PROGRESSDATA(3), it is not used by libcurl but is only passed along from the application to the callback. The callback gets told how much data libcurl is about to transfer and has -transferred, in number of bytes. \fIdltotal\fP is the total number of bytes -libcurl expects to download in this transfer. \fIdlnow\fP is the number of -bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl -expects to upload in this transfer. \fIulnow\fP is the number of bytes +transferred, in number of bytes. *dltotal* is the total number of bytes +libcurl expects to download in this transfer. *dlnow* is the number of +bytes downloaded so far. *ultotal* is the total number of bytes libcurl +expects to upload in this transfer. *ulnow* is the number of bytes uploaded so far. Unknown/unused argument values passed to the callback are be set to zero (like @@ -69,21 +61,27 @@ If your callback function returns CURL_PROGRESSFUNC_CONTINUE it causes libcurl to continue executing the default progress function. Returning any other non-zero value from this callback makes libcurl abort the -transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. +transfer and return *CURLE_ABORTED_BY_CALLBACK*. If you transfer data with the multi interface, this function is not called during periods of idleness unless you call the appropriate libcurl function that performs transfers. -\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually +CURLOPT_NOPROGRESS(3) must be set to 0 to make this function actually get called. -.SH DEFAULT + +# DEFAULT + By default, libcurl has an internal progress meter. That is rarely wanted by users. -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c struct progress { char *private; size_t size; @@ -96,7 +94,7 @@ static size_t progress_callback(void *clientp, double ulnow) { struct progress *memory = clientp; - printf("private: %p\\n", memory->private); + printf("private: %p\n", memory->private); /* use the values */ @@ -116,12 +114,12 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Deprecated since 7.32.0. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_VERBOSE (3), -.BR CURLOPT_NOPROGRESS (3), -.BR CURLOPT_XFERINFOFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 deleted file mode 100644 index 29538d6602e..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 +++ /dev/null @@ -1,106 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROTOCOLS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROTOCOLS \- allowed protocols -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS, long bitmask); -.fi -.SH DESCRIPTION -This option is deprecated. We strongly recommend using -\fICURLOPT_PROTOCOLS_STR(3)\fP instead because this option cannot control all -available protocols! - -Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask -limits what protocols libcurl may use in the transfer. This allows you to have -a libcurl built to support a wide range of protocols but still limit specific -transfers to only be allowed to use a subset of them. By default libcurl -accepts all protocols it supports (\fICURLPROTO_ALL\fP). See also -\fICURLOPT_REDIR_PROTOCOLS(3)\fP. - -These are the available protocol defines: -.nf -CURLPROTO_DICT -CURLPROTO_FILE -CURLPROTO_FTP -CURLPROTO_FTPS -CURLPROTO_GOPHER -CURLPROTO_HTTP -CURLPROTO_HTTPS -CURLPROTO_IMAP -CURLPROTO_IMAPS -CURLPROTO_LDAP -CURLPROTO_LDAPS -CURLPROTO_POP3 -CURLPROTO_POP3S -CURLPROTO_RTMP -CURLPROTO_RTMPE -CURLPROTO_RTMPS -CURLPROTO_RTMPT -CURLPROTO_RTMPTE -CURLPROTO_RTMPTS -CURLPROTO_RTSP -CURLPROTO_SCP -CURLPROTO_SFTP -CURLPROTO_SMB -CURLPROTO_SMBS -CURLPROTO_SMTP -CURLPROTO_SMTPS -CURLPROTO_TELNET -CURLPROTO_TFTP -.fi -.SH DEFAULT -All protocols built-in. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(int argc, char **argv) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* pass in the URL from an external source */ - curl_easy_setopt(curl, CURLOPT_URL, argv[1]); - - /* only allow HTTP, TFTP and SFTP */ - curl_easy_setopt(curl, CURLOPT_PROTOCOLS, - CURLPROTO_HTTP | CURLPROTO_TFTP | CURLPROTO_SFTP); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.4. Deprecated since 7.85.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_DEFAULT_PROTOCOL (3), -.BR CURLOPT_REDIR_PROTOCOLS (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.md b/docs/libcurl/opts/CURLOPT_PROTOCOLS.md new file mode 100644 index 00000000000..a4d1a5a7cd3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS.md @@ -0,0 +1,104 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROTOCOLS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEFAULT_PROTOCOL (3) + - CURLOPT_REDIR_PROTOCOLS (3) + - CURLOPT_URL (3) +--- + +# NAME + +CURLOPT_PROTOCOLS - allowed protocols + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS, long bitmask); +~~~ + +# DESCRIPTION + +This option is deprecated. We strongly recommend using +CURLOPT_PROTOCOLS_STR(3) instead because this option cannot control all +available protocols! + +Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask +limits what protocols libcurl may use in the transfer. This allows you to have +a libcurl built to support a wide range of protocols but still limit specific +transfers to only be allowed to use a subset of them. By default libcurl +accepts all protocols it supports (*CURLPROTO_ALL*). See also +CURLOPT_REDIR_PROTOCOLS(3). + +These are the available protocol defines: +~~~c +CURLPROTO_DICT +CURLPROTO_FILE +CURLPROTO_FTP +CURLPROTO_FTPS +CURLPROTO_GOPHER +CURLPROTO_HTTP +CURLPROTO_HTTPS +CURLPROTO_IMAP +CURLPROTO_IMAPS +CURLPROTO_LDAP +CURLPROTO_LDAPS +CURLPROTO_POP3 +CURLPROTO_POP3S +CURLPROTO_RTMP +CURLPROTO_RTMPE +CURLPROTO_RTMPS +CURLPROTO_RTMPT +CURLPROTO_RTMPTE +CURLPROTO_RTMPTS +CURLPROTO_RTSP +CURLPROTO_SCP +CURLPROTO_SFTP +CURLPROTO_SMB +CURLPROTO_SMBS +CURLPROTO_SMTP +CURLPROTO_SMTPS +CURLPROTO_TELNET +CURLPROTO_TFTP +~~~ + +# DEFAULT + +All protocols built-in. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(int argc, char **argv) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow HTTP, TFTP and SFTP */ + curl_easy_setopt(curl, CURLOPT_PROTOCOLS, + CURLPROTO_HTTP | CURLPROTO_TFTP | CURLPROTO_SFTP); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.4. Deprecated since 7.85.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.3 b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.3 deleted file mode 100644 index 8af32244d1c..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.3 +++ /dev/null @@ -1,90 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROTOCOLS_STR 3 "11 Jun 2022" libcurl libcurl -.SH NAME -CURLOPT_PROTOCOLS_STR \- allowed protocols -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS_STR, char *spec); -.fi -.SH DESCRIPTION -Pass a pointer to a string that holds a comma-separated list of case -insensitive protocol names (URL schemes) to allow in the transfer. This -option allows applications to use libcurl built to support a wide range of -protocols but still limit specific transfers to only be allowed to use a -subset of them. By default, libcurl accepts all protocols it was built with -support for. See also \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP. - -If trying to set a non-existing protocol or if no matching protocol at all is -set, it returns error. - -These are the available protocols: - -DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, -MQTT, POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP, -SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS - -You can set "ALL" as a short-cut to enable all protocols. Note that by setting -all, you may enable protocols that were not supported the day you write this -but are introduced in a future libcurl version. - -\fIcurl_version_info(3)\fP can be used to get a list of all supported -protocols in the current libcurl. \fICURLINFO_SCHEME(3)\fP is the recommended -way to figure out the protocol used in a previous transfer. -.SH DEFAULT -All protocols built-in -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(int argc, char **argv) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* pass in the URL from an external source */ - curl_easy_setopt(curl, CURLOPT_URL, argv[1]); - - /* only allow HTTP, TFTP and SFTP */ - curl_easy_setopt(curl, CURLOPT_PROTOCOLS_STR, "http,tftp,sftp"); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.85.0 -.SH RETURN VALUE -Returns CURLE_UNKNOWN_OPTION if the option is not implemented, -CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled, -CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK. -.SH "SEE ALSO" -.BR curl_version_info (3), -.BR CURLINFO_SCHEME (3), -.BR CURLOPT_DEFAULT_PROTOCOL (3), -.BR CURLOPT_REDIR_PROTOCOLS_STR (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md new file mode 100644 index 00000000000..9da056d2394 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md @@ -0,0 +1,88 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROTOCOLS_STR +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SCHEME (3) + - CURLOPT_DEFAULT_PROTOCOL (3) + - CURLOPT_REDIR_PROTOCOLS_STR (3) + - CURLOPT_URL (3) + - curl_version_info (3) +--- + +# NAME + +CURLOPT_PROTOCOLS_STR - allowed protocols + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS_STR, char *spec); +~~~ + +# DESCRIPTION + +Pass a pointer to a string that holds a comma-separated list of case +insensitive protocol names (URL schemes) to allow in the transfer. This +option allows applications to use libcurl built to support a wide range of +protocols but still limit specific transfers to only be allowed to use a +subset of them. By default, libcurl accepts all protocols it was built with +support for. See also CURLOPT_REDIR_PROTOCOLS_STR(3). + +If trying to set a non-existing protocol or if no matching protocol at all is +set, it returns error. + +These are the available protocols: + +DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, +MQTT, POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP, +SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS + +You can set "ALL" as a short-cut to enable all protocols. Note that by setting +all, you may enable protocols that were not supported the day you write this +but are introduced in a future libcurl version. + +curl_version_info(3) can be used to get a list of all supported +protocols in the current libcurl. CURLINFO_SCHEME(3) is the recommended +way to figure out the protocol used in a previous transfer. + +# DEFAULT + +All protocols built-in + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(int argc, char **argv) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow HTTP, TFTP and SFTP */ + curl_easy_setopt(curl, CURLOPT_PROTOCOLS_STR, "http,tftp,sftp"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.85.0 + +# RETURN VALUE + +Returns CURLE_UNKNOWN_OPTION if the option is not implemented, +CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled, +CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_PROXY.3 b/docs/libcurl/opts/CURLOPT_PROXY.3 deleted file mode 100644 index a3a36152ab6..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY.3 +++ /dev/null @@ -1,137 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXY \- proxy to use -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy); -.fi -.SH DESCRIPTION -Set the \fIproxy\fP to use for transfers with this easy handle. The parameter -should be a char * to a null-terminated string holding the host name or dotted -numerical IP address. A numerical IPv6 address must be written within -[brackets]. - -To specify port number in this string, append :[port] to the end of the host -name. The proxy's port number may optionally (but discouraged) be specified -with the separate option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl -defaults to using port 1080 for proxies. - -The proxy string may be prefixed with [scheme]:// to specify which kind of -proxy is used. - -.RS -.IP http:// -HTTP Proxy. Default when no scheme or proxy type is specified. -.IP https:// -HTTPS Proxy. (Added in 7.52.0 for OpenSSL and GnuTLS Since 7.87.0, it -also works for BearSSL, mbedTLS, rustls, Schannel, Secure Transport and -wolfSSL.) - -This uses HTTP/1 by default. Setting \fICURLOPT_PROXYTYPE(3)\fP to -\fBCURLPROXY_HTTPS2\fP allows libcurl to negotiate using HTTP/2 with proxy. -.IP socks4:// -SOCKS4 Proxy. -.IP socks4a:// -SOCKS4a Proxy. Proxy resolves URL hostname. -.IP socks5:// -SOCKS5 Proxy. -.IP socks5h:// -SOCKS5 Proxy. Proxy resolves URL hostname. -.RE - -Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify -which kind of proxy the string identifies. - -When you tell the library to use an HTTP proxy, libcurl transparently converts -operations to HTTP even if you specify an FTP URL etc. This may have an impact -on what other features of the library you can use, such as -\fICURLOPT_QUOTE(3)\fP and similar FTP specifics that do not work unless you -tunnel through the HTTP proxy. Such tunneling is activated with -\fICURLOPT_HTTPPROXYTUNNEL(3)\fP. - -Setting the proxy string to "" (an empty string) explicitly disables the use -of a proxy, even if there is an environment variable set for it. - -A proxy host string can also include protocol scheme (http://) and embedded -user + password. - -Unix domain sockets are supported for socks proxies since 7.84.0. Set -localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock - -The application does not have to keep the string around after setting this -option. - -When a proxy is used, the active FTP mode as set with \fICUROPT_FTPPORT(3)\fP, -cannot be used. -.SH "Environment variables" -libcurl respects the proxy environment variables named \fBhttp_proxy\fP, -\fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl uses the specified -proxy for that URL scheme. So for a "FTP://" URL, the \fBftp_proxy\fP is -considered. \fBall_proxy\fP is used if no protocol specific proxy was set. - -If \fBno_proxy\fP (or \fBNO_PROXY\fP) is set, it is the exact equivalent of -setting the \fICURLOPT_NOPROXY(3)\fP option. - -The \fICURLOPT_PROXY(3)\fP and \fICURLOPT_NOPROXY(3)\fP options override -environment variables. -.SH DEFAULT -Default is NULL, meaning no proxy is used. - -When you set a host name to use, do not assume that there is any particular -single port number used widely for proxies. Specify it! -.SH PROTOCOLS -All except file://. Note that some protocols do not work well over proxy. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Since 7.14.1 the proxy environment variable names can include the protocol -scheme. - -Since 7.21.7 the proxy string supports the socks protocols as "schemes". - -Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return -error. -.SH RETURN VALUE -Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_HTTPPROXYTUNNEL (3), -.BR CURLOPT_PRE_PROXY (3), -.BR CURLOPT_PROXYPORT (3), -.BR CURLOPT_PROXYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY.md b/docs/libcurl/opts/CURLOPT_PROXY.md new file mode 100644 index 00000000000..6bdda4ab5ef --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY.md @@ -0,0 +1,146 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPPROXYTUNNEL (3) + - CURLOPT_PRE_PROXY (3) + - CURLOPT_PROXYPORT (3) + - CURLOPT_PROXYTYPE (3) +--- + +# NAME + +CURLOPT_PROXY - proxy to use + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy); +~~~ + +# DESCRIPTION + +Set the *proxy* to use for transfers with this easy handle. The parameter +should be a char * to a null-terminated string holding the host name or dotted +numerical IP address. A numerical IPv6 address must be written within +[brackets]. + +To specify port number in this string, append :[port] to the end of the host +name. The proxy's port number may optionally (but discouraged) be specified +with the separate option CURLOPT_PROXYPORT(3). If not specified, libcurl +defaults to using port 1080 for proxies. + +The proxy string may be prefixed with [scheme]:// to specify which kind of +proxy is used. + +## http:// + +HTTP Proxy. Default when no scheme or proxy type is specified. + +## https:// + +HTTPS Proxy. (Added in 7.52.0 for OpenSSL and GnuTLS Since 7.87.0, it +also works for BearSSL, mbedTLS, rustls, Schannel, Secure Transport and +wolfSSL.) + +This uses HTTP/1 by default. Setting CURLOPT_PROXYTYPE(3) to +**CURLPROXY_HTTPS2** allows libcurl to negotiate using HTTP/2 with proxy. + +## socks4:// + +SOCKS4 Proxy. + +## socks4a:// + +SOCKS4a Proxy. Proxy resolves URL hostname. + +## socks5:// + +SOCKS5 Proxy. + +## socks5h:// + +SOCKS5 Proxy. Proxy resolves URL hostname. + +Without a scheme prefix, CURLOPT_PROXYTYPE(3) can be used to specify +which kind of proxy the string identifies. + +When you tell the library to use an HTTP proxy, libcurl transparently converts +operations to HTTP even if you specify an FTP URL etc. This may have an impact +on what other features of the library you can use, such as +CURLOPT_QUOTE(3) and similar FTP specifics that do not work unless you +tunnel through the HTTP proxy. Such tunneling is activated with +CURLOPT_HTTPPROXYTUNNEL(3). + +Setting the proxy string to "" (an empty string) explicitly disables the use +of a proxy, even if there is an environment variable set for it. + +A proxy host string can also include protocol scheme (http://) and embedded +user + password. + +Unix domain sockets are supported for socks proxies since 7.84.0. Set +localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock + +The application does not have to keep the string around after setting this +option. + +When a proxy is used, the active FTP mode as set with *CUROPT_FTPPORT(3)*, +cannot be used. + +# Environment variables + +libcurl respects the proxy environment variables named **http_proxy**, +**ftp_proxy**, **sftp_proxy** etc. If set, libcurl uses the specified +proxy for that URL scheme. So for a "FTP://" URL, the **ftp_proxy** is +considered. **all_proxy** is used if no protocol specific proxy was set. + +If **no_proxy** (or **NO_PROXY**) is set, it is the exact equivalent of +setting the CURLOPT_NOPROXY(3) option. + +The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override +environment variables. + +# DEFAULT + +Default is NULL, meaning no proxy is used. + +When you set a host name to use, do not assume that there is any particular +single port number used widely for proxies. Specify it! + +# PROTOCOLS + +All except file://. Note that some protocols do not work well over proxy. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Since 7.14.1 the proxy environment variable names can include the protocol +scheme. + +Since 7.21.7 the proxy string supports the socks protocols as "schemes". + +Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return +error. + +# RETURN VALUE + +Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 deleted file mode 100644 index db48dd1fb9f..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXYAUTH 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXYAUTH \- HTTP proxy authentication methods -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYAUTH, long bitmask); -.fi -.SH DESCRIPTION -Pass a long as parameter, which is set to a bitmask, to tell libcurl which -HTTP authentication method(s) you want it to use for your proxy -authentication. If more than one bit is set, libcurl first queries the site to -see what authentication methods it supports and then it picks the best one you -allow it to use. For some methods, this induces an extra network round-trip. -Set the actual name and password with the \fICURLOPT_PROXYUSERPWD(3)\fP -option. - -The bitmask can be constructed by the bits listed and described in the -\fICURLOPT_HTTPAUTH(3)\fP man page. -.SH DEFAULT -CURLAUTH_BASIC -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* use this proxy */ - curl_easy_setopt(curl, CURLOPT_PROXY, "http://local.example.com:1080"); - /* allow whatever auth the proxy speaks */ - curl_easy_setopt(curl, CURLOPT_PROXYAUTH, CURLAUTH_ANY); - /* set the proxy credentials */ - curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "james:007"); - ret = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.7 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication -methods. -.SH "SEE ALSO" -.BR CURLOPT_HTTPAUTH (3), -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYPORT (3), -.BR CURLOPT_PROXYTYPE (3), -.BR CURLOPT_PROXYUSERPWD (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.md b/docs/libcurl/opts/CURLOPT_PROXYAUTH.md new file mode 100644 index 00000000000..8e6dc093b5e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYAUTH.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXYAUTH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPAUTH (3) + - CURLOPT_PROXY (3) + - CURLOPT_PROXYPORT (3) + - CURLOPT_PROXYTYPE (3) + - CURLOPT_PROXYUSERPWD (3) +--- + +# NAME + +CURLOPT_PROXYAUTH - HTTP proxy authentication methods + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYAUTH, long bitmask); +~~~ + +# DESCRIPTION + +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +HTTP authentication method(s) you want it to use for your proxy +authentication. If more than one bit is set, libcurl first queries the site to +see what authentication methods it supports and then it picks the best one you +allow it to use. For some methods, this induces an extra network round-trip. +Set the actual name and password with the CURLOPT_PROXYUSERPWD(3) +option. + +The bitmask can be constructed by the bits listed and described in the +CURLOPT_HTTPAUTH(3) man page. + +# DEFAULT + +CURLAUTH_BASIC + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* use this proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "http://local.example.com:1080"); + /* allow whatever auth the proxy speaks */ + curl_easy_setopt(curl, CURLOPT_PROXYAUTH, CURLAUTH_ANY); + /* set the proxy credentials */ + curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "james:007"); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.7 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication +methods. diff --git a/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 b/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 deleted file mode 100644 index 1bc17e9e8bc..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXYHEADER 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXYHEADER \- set of HTTP headers to pass to proxy -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYHEADER, - struct curl_slist *headers); -.SH DESCRIPTION -Pass a pointer to a linked list of HTTP headers to pass in your HTTP request -sent to a proxy. The rules for this list is identical to the -\fICURLOPT_HTTPHEADER(3)\fP option's. - -The headers set with this option is only ever used in requests sent to a proxy -- when there is also a request sent to a host. - -The first line in a request (containing the method, usually a GET or POST) is -NOT a header and cannot be replaced using this option. Only the lines -following the request-line are headers. Adding this method line in this list -of headers causes your request to send an invalid header. - -Pass a NULL to this to reset back to no custom headers. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - - struct curl_slist *list; - - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example.com:80"); - - list = curl_slist_append(NULL, "Shoesize: 10"); - list = curl_slist_append(list, "Accept:"); - - curl_easy_setopt(curl, CURLOPT_PROXYHEADER, list); - - curl_easy_perform(curl); - - curl_slist_free_all(list); /* free the list again */ - } -} -.fi -.SH AVAILABILITY -Added in 7.37.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HEADEROPT (3), -.BR CURLOPT_HTTPHEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXYHEADER.md b/docs/libcurl/opts/CURLOPT_PROXYHEADER.md new file mode 100644 index 00000000000..e44afdd1871 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYHEADER.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXYHEADER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADEROPT (3) + - CURLOPT_HTTPHEADER (3) +--- + +# NAME + +CURLOPT_PROXYHEADER - set of HTTP headers to pass to proxy + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYHEADER, + struct curl_slist *headers); +~~~ + +# DESCRIPTION + +Pass a pointer to a linked list of HTTP headers to pass in your HTTP request +sent to a proxy. The rules for this list is identical to the +CURLOPT_HTTPHEADER(3) option's. + +The headers set with this option is only ever used in requests sent to a proxy +- when there is also a request sent to a host. + +The first line in a request (containing the method, usually a GET or POST) is +NOT a header and cannot be replaced using this option. Only the lines +following the request-line are headers. Adding this method line in this list +of headers causes your request to send an invalid header. + +Pass a NULL to this to reset back to no custom headers. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + + struct curl_slist *list; + + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example.com:80"); + + list = curl_slist_append(NULL, "Shoesize: 10"); + list = curl_slist_append(list, "Accept:"); + + curl_easy_setopt(curl, CURLOPT_PROXYHEADER, list); + + curl_easy_perform(curl); + + curl_slist_free_all(list); /* free the list again */ + } +} +~~~ + +# AVAILABILITY + +Added in 7.37.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 deleted file mode 100644 index 921caf329de..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXYPASSWORD 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXYPASSWORD \- password to use with proxy authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPASSWORD, char *pwd); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should be pointing to the null-terminated -password to use for authentication with the proxy. - -The \fICURLOPT_PROXYPASSWORD(3)\fP option should be used in conjunction with -the \fICURLOPT_PROXYUSERNAME(3)\fP option. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -blank -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); - curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith"); - curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_HTTPAUTH (3), -.BR CURLOPT_PASSWORD (3), -.BR CURLOPT_PROXYAUTH (3), -.BR CURLOPT_PROXYUSERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md new file mode 100644 index 00000000000..22520ea1161 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXYPASSWORD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPAUTH (3) + - CURLOPT_PASSWORD (3) + - CURLOPT_PROXYAUTH (3) + - CURLOPT_PROXYUSERNAME (3) +--- + +# NAME + +CURLOPT_PROXYPASSWORD - password to use with proxy authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPASSWORD, char *pwd); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should be pointing to the null-terminated +password to use for authentication with the proxy. + +The CURLOPT_PROXYPASSWORD(3) option should be used in conjunction with +the CURLOPT_PROXYUSERNAME(3) option. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +blank + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith"); + curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXYPORT.3 b/docs/libcurl/opts/CURLOPT_PROXYPORT.3 deleted file mode 100644 index 04a20a7bbc3..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXYPORT.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXYPORT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXYPORT \- port number the proxy listens on -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPORT, long port); -.fi -.SH DESCRIPTION -We discourage use of this option. - -Pass a long with this option to set the proxy port to connect to unless it is -specified in the proxy string \fICURLOPT_PROXY(3)\fP or uses 443 for https -proxies and 1080 for all others as default. - -While this accepts a 'long', the port number is 16 bit so it cannot be larger -than 65535. -.SH DEFAULT -0, not specified which makes it use the default port -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_PROXY, "localhost"); - curl_easy_setopt(curl, CURLOPT_PROXYPORT, 8080L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLINFO_PRIMARY_PORT (3), -.BR CURLOPT_PORT (3), -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXYPORT.md b/docs/libcurl/opts/CURLOPT_PROXYPORT.md new file mode 100644 index 00000000000..0cda8bb8fc0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYPORT.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXYPORT +Section: 3 +Source: libcurl +See-also: + - CURLINFO_PRIMARY_PORT (3) + - CURLOPT_PORT (3) + - CURLOPT_PROXY (3) + - CURLOPT_PROXYTYPE (3) +--- + +# NAME + +CURLOPT_PROXYPORT - port number the proxy listens on + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPORT, long port); +~~~ + +# DESCRIPTION + +We discourage use of this option. + +Pass a long with this option to set the proxy port to connect to unless it is +specified in the proxy string CURLOPT_PROXY(3) or uses 443 for https +proxies and 1080 for all others as default. + +While this accepts a 'long', the port number is 16 bit so it cannot be larger +than 65535. + +# DEFAULT + +0, not specified which makes it use the default port + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "localhost"); + curl_easy_setopt(curl, CURLOPT_PROXYPORT, 8080L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 deleted file mode 100644 index 91f3b5a9a3f..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 +++ /dev/null @@ -1,88 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXYTYPE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXYTYPE \- proxy protocol type -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYTYPE, long type); -.fi -.SH DESCRIPTION -Pass one of the values below to set the type of the proxy. - -.RS -.IP CURLPROXY_HTTP -HTTP Proxy. Default. -.IP CURLPROXY_HTTPS -HTTPS Proxy using HTTP/1. (Added in 7.52.0 for OpenSSL and GnuTLS. Since -7.87.0, it also works for BearSSL, mbedTLS, rustls, Schannel, Secure Transport -and wolfSSL.) -.IP CURLPROXY_HTTPS2 -HTTPS Proxy and attempt to speak HTTP/2 over it. (Added in 8.1.0) -.IP CURLPROXY_HTTP_1_0 -HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for -any CONNECT tunneling. It does not change the HTTP version of the actual HTTP -requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP. -.IP CURLPROXY_SOCKS4 -SOCKS4 Proxy. -.IP CURLPROXY_SOCKS4A -SOCKS4a Proxy. Proxy resolves URL hostname. -.IP CURLPROXY_SOCKS5 -SOCKS5 Proxy. -.IP CURLPROXY_SOCKS5_HOSTNAME -SOCKS5 Proxy. Proxy resolves URL hostname. -.RE - -Often it is more convenient to specify the proxy type with the scheme part of -the \fICURLOPT_PROXY(3)\fP string. -.SH DEFAULT -CURLPROXY_HTTP -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "local.example.com:1080"); - /* set the proxy type */ - curl_easy_setopt(curl, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5); - ret = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYPORT (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXYTYPE.md new file mode 100644 index 00000000000..4f06fe5508f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYTYPE.md @@ -0,0 +1,99 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXYTYPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_PROXYPORT (3) +--- + +# NAME + +CURLOPT_PROXYTYPE - proxy protocol type + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYTYPE, long type); +~~~ + +# DESCRIPTION + +Pass one of the values below to set the type of the proxy. + +## CURLPROXY_HTTP + +HTTP Proxy. Default. + +## CURLPROXY_HTTPS + +HTTPS Proxy using HTTP/1. (Added in 7.52.0 for OpenSSL and GnuTLS. Since +7.87.0, it also works for BearSSL, mbedTLS, rustls, Schannel, Secure Transport +and wolfSSL.) + +## CURLPROXY_HTTPS2 + +HTTPS Proxy and attempt to speak HTTP/2 over it. (Added in 8.1.0) + +## CURLPROXY_HTTP_1_0 + +HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for +any CONNECT tunneling. It does not change the HTTP version of the actual HTTP +requests, controlled by CURLOPT_HTTP_VERSION(3). + +## CURLPROXY_SOCKS4 + +SOCKS4 Proxy. + +## CURLPROXY_SOCKS4A + +SOCKS4a Proxy. Proxy resolves URL hostname. + +## CURLPROXY_SOCKS5 + +SOCKS5 Proxy. + +## CURLPROXY_SOCKS5_HOSTNAME + +SOCKS5 Proxy. Proxy resolves URL hostname. + +Often it is more convenient to specify the proxy type with the scheme part of +the CURLOPT_PROXY(3) string. + +# DEFAULT + +CURLPROXY_HTTP + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "local.example.com:1080"); + /* set the proxy type */ + curl_easy_setopt(curl, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 deleted file mode 100644 index 7a0e54ee23d..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXYUSERNAME 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXYUSERNAME \- user name to use for proxy authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERNAME, - char *username); -.SH DESCRIPTION -Pass a char * as parameter, which should be pointing to the null-terminated -user name to use for the transfer. - -\fICURLOPT_PROXYUSERNAME(3)\fP sets the user name to be used in protocol -authentication with the proxy. - -To specify the proxy password use the \fICURLOPT_PROXYPASSWORD(3)\fP. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -blank -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); - curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith"); - curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXYPASSWORD (3), -.BR CURLOPT_USERNAME (3), -.BR CURLOPT_HTTPAUTH (3), -.BR CURLOPT_PROXYAUTH (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md new file mode 100644 index 00000000000..f0d1dfc4d51 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXYUSERNAME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPAUTH (3) + - CURLOPT_PROXYAUTH (3) + - CURLOPT_PROXYPASSWORD (3) + - CURLOPT_USERNAME (3) +--- + +# NAME + +CURLOPT_PROXYUSERNAME - user name to use for proxy authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERNAME, + char *username); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should be pointing to the +null-terminated user name to use for the transfer. + +CURLOPT_PROXYUSERNAME(3) sets the user name to be used in protocol +authentication with the proxy. + +To specify the proxy password use the CURLOPT_PROXYPASSWORD(3). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +blank + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith"); + curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 deleted file mode 100644 index e6bdcf956a2..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXYUSERPWD 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXYUSERPWD \- user name and password to use for proxy authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERPWD, char *userpwd); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should be [user name]:[password] to use for -the connection to the HTTP proxy. Both the name and the password are URL -decoded before used, so to include for example a colon in the user name you -should encode it as %3A. (This is different to how \fICURLOPT_USERPWD(3)\fP is -used - beware.) - -Use \fICURLOPT_PROXYAUTH(3)\fP to specify the authentication method. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -This is NULL by default. -.SH PROTOCOLS -Used with all protocols that can use a proxy -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); - curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "clark%20kent:superman"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYPASSWORD (3), -.BR CURLOPT_PROXYTYPE (3), -.BR CURLOPT_PROXYUSERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md new file mode 100644 index 00000000000..196d587e28c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXYUSERPWD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_PROXYPASSWORD (3) + - CURLOPT_PROXYTYPE (3) + - CURLOPT_PROXYUSERNAME (3) +--- + +# NAME + +CURLOPT_PROXYUSERPWD - user name and password to use for proxy authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERPWD, char *userpwd); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should be [user name]:[password] to +use for the connection to the HTTP proxy. Both the name and the password are +URL decoded before used, so to include for example a colon in the user name +you should encode it as %3A. (This is different to how CURLOPT_USERPWD(3) is +used - beware.) + +Use CURLOPT_PROXYAUTH(3) to specify the authentication method. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +This is NULL by default. + +# PROTOCOLS + +Used with all protocols that can use a proxy + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "clark%20kent:superman"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 deleted file mode 100644 index 4b64353e6f2..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 +++ /dev/null @@ -1,95 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_CAINFO 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_CAINFO \- path to proxy Certificate Authority (CA) bundle -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO, char *path); -.fi -.SH DESCRIPTION -This option is for connecting to an HTTPS proxy, not an HTTPS server. - -Pass a char * to a null-terminated string naming a file holding one or more -certificates to verify the HTTPS proxy with. - -If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the -server's certificate, \fICURLOPT_PROXY_CAINFO(3)\fP need not even indicate an -accessible file. - -This option is by default set to the system path where libcurl's CA -certificate bundle is assumed to be stored, as established at build time. - -(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. - -The application does not have to keep the string around after setting this -option. - -The default value for this can be figured out with \fICURLINFO_CAINFO(3)\fP. -.SH DEFAULT -Built-in system specific -.SH PROTOCOLS -Used with HTTPS proxy -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* using an HTTPS proxy */ - curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); - curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO, "/etc/certs/cabundle.pem"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 - -For TLS backends that do not support certificate files, the -\fICURLOPT_PROXY_CAINFO(3)\fP option is ignored. Refer to -https://curl.se/docs/ssl-compared.html -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_CAINFO_BLOB (3), -.BR CURLOPT_CAPATH (3), -.BR CURLOPT_PROXY_CAINFO_BLOB (3), -.BR CURLOPT_PROXY_CAPATH (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md new file mode 100644 index 00000000000..473083f35b4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md @@ -0,0 +1,93 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_CAINFO +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_CAINFO_BLOB (3) + - CURLOPT_CAPATH (3) + - CURLOPT_PROXY_CAINFO_BLOB (3) + - CURLOPT_PROXY_CAPATH (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PROXY_CAINFO - path to proxy Certificate Authority (CA) bundle + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO, char *path); +~~~ + +# DESCRIPTION + +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a char pointer to a null-terminated string naming a file holding one or +more certificates to verify the HTTPS proxy with. + +If CURLOPT_PROXY_SSL_VERIFYPEER(3) is zero and you avoid verifying the +server's certificate, CURLOPT_PROXY_CAINFO(3) need not even indicate an +accessible file. + +This option is by default set to the system path where libcurl's CA +certificate bundle is assumed to be stored, as established at build time. + +(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. + +The application does not have to keep the string around after setting this +option. + +The default value for this can be figured out with CURLINFO_CAINFO(3). + +# DEFAULT + +Built-in system specific + +# PROTOCOLS + +Used with HTTPS proxy + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO, "/etc/certs/cabundle.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +For TLS backends that do not support certificate files, the +CURLOPT_PROXY_CAINFO(3) option is ignored. Refer to +https://curl.se/docs/ssl-compared.html + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 deleted file mode 100644 index 80c03f35499..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 +++ /dev/null @@ -1,94 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_CAINFO_BLOB 3 "31 March 2021" libcurl libcurl -.SH NAME -CURLOPT_PROXY_CAINFO_BLOB \- proxy Certificate Authority (CA) bundle in PEM format -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO_BLOB, - struct curl_blob *stblob); -.fi -.SH DESCRIPTION -This option is for connecting to an HTTPS proxy, not an HTTPS server. - -Pass a pointer to a curl_blob structure, which contains information (pointer -and size) about a memory block with binary data of PEM encoded content holding -one or more certificates to verify the HTTPS proxy with. - -If the blob is initialized with the flags member of struct curl_blob set to -CURL_BLOB_COPY, the application does not have to keep the buffer around after -setting this. - -If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the -server's certificate, \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP is not needed. - -This option overrides \fICURLOPT_PROXY_CAINFO(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -Used with HTTPS proxy -.SH EXAMPLE -.nf -#include /* for strlen */ - -extern char *strpem; /* strpem must point to a PEM string */ -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - struct curl_blob blob; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* using an HTTPS proxy */ - curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); - blob.data = strpem; - blob.len = strlen(strpem); - blob.flags = CURL_BLOB_COPY; - curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO_BLOB, &blob); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.77.0. - -This option is supported by the rustls (since 7.82.0), OpenSSL, Secure -Transport and Schannel backends. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_CAINFO_BLOB (3), -.BR CURLOPT_CAPATH (3), -.BR CURLOPT_PROXY_CAINFO (3), -.BR CURLOPT_PROXY_CAPATH (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md new file mode 100644 index 00000000000..bbf30cba3e6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md @@ -0,0 +1,92 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_CAINFO_BLOB +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_CAINFO_BLOB (3) + - CURLOPT_CAPATH (3) + - CURLOPT_PROXY_CAINFO (3) + - CURLOPT_PROXY_CAPATH (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PROXY_CAINFO_BLOB - proxy Certificate Authority (CA) bundle in PEM format + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO_BLOB, + struct curl_blob *stblob); +~~~ + +# DESCRIPTION + +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a pointer to a curl_blob structure, which contains information (pointer +and size) about a memory block with binary data of PEM encoded content holding +one or more certificates to verify the HTTPS proxy with. + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +If CURLOPT_PROXY_SSL_VERIFYPEER(3) is zero and you avoid verifying the +server's certificate, CURLOPT_PROXY_CAINFO_BLOB(3) is not needed. + +This option overrides CURLOPT_PROXY_CAINFO(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +Used with HTTPS proxy + +# EXAMPLE + +~~~c +#include /* for strlen */ + +extern char *strpem; /* strpem must point to a PEM string */ +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + blob.data = strpem; + blob.len = strlen(strpem); + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO_BLOB, &blob); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.77.0. + +This option is supported by the rustls (since 7.82.0), OpenSSL, Secure +Transport and Schannel backends. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 deleted file mode 100644 index fd55b0918bc..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 +++ /dev/null @@ -1,83 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_CAPATH 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_CAPATH \- directory holding HTTPS proxy CA certificates -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAPATH, char *capath); -.fi -.SH DESCRIPTION -Pass a char * to a null-terminated string naming a directory holding multiple -CA certificates to verify the HTTPS proxy with. If libcurl is built against -OpenSSL, the certificate directory must be prepared using the OpenSSL -\fBc_rehash\fP utility. This makes sense only when -\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled (which it is by default). - -The application does not have to keep the string around after setting this -option. - -The default value for this can be figured out with \fICURLINFO_CAPATH(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -Everything used over an HTTPS proxy -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* using an HTTPS proxy */ - curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); - curl_easy_setopt(curl, CURLOPT_PROXY_CAPATH, "/etc/cert-dir"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 - -This option is supported by the OpenSSL, GnuTLS, and mbedTLS (since 7.56.0) -backends. -.SH RETURN VALUE -CURLE_OK if supported; or an error such as: - -CURLE_NOT_BUILT_IN - Not supported by the SSL backend - -CURLE_UNKNOWN_OPTION - -CURLE_OUT_OF_MEMORY -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_PROXY_CAINFO (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md new file mode 100644 index 00000000000..2253c9f26a5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md @@ -0,0 +1,81 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_CAPATH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_PROXY_CAINFO (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_STDERR (3) +--- + +# NAME + +CURLOPT_PROXY_CAPATH - directory holding HTTPS proxy CA certificates + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAPATH, char *capath); +~~~ + +# DESCRIPTION + +Pass a char pointer to a null-terminated string naming a directory holding +multiple CA certificates to verify the HTTPS proxy with. If libcurl is built +against OpenSSL, the certificate directory must be prepared using the OpenSSL +**c_rehash** utility. This makes sense only when +CURLOPT_PROXY_SSL_VERIFYPEER(3) is enabled (which it is by default). + +The application does not have to keep the string around after setting this +option. + +The default value for this can be figured out with CURLINFO_CAPATH(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +Everything used over an HTTPS proxy + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_CAPATH, "/etc/cert-dir"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +This option is supported by the OpenSSL, GnuTLS, and mbedTLS (since 7.56.0) +backends. + +# RETURN VALUE + +CURLE_OK if supported; or an error such as: + +CURLE_NOT_BUILT_IN - Not supported by the SSL backend + +CURLE_UNKNOWN_OPTION + +CURLE_OUT_OF_MEMORY diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 deleted file mode 100644 index 80891666ab0..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 +++ /dev/null @@ -1,85 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_CRLFILE 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_CRLFILE \- HTTPS proxy Certificate Revocation List file -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CRLFILE, char *file); -.fi -.SH DESCRIPTION -This option is for connecting to an HTTPS proxy, not an HTTPS server. - -Pass a char * to a null-terminated string naming a \fIfile\fP with the -concatenation of CRL (in PEM format) to use in the certificate validation that -occurs during the SSL exchange. - -When curl is built to use GnuTLS, there is no way to influence the use of CRL -passed to help in the verification process. When libcurl is built with OpenSSL -support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, -requiring CRL check against all the elements of the certificate chain if a CRL -file is passed. - -This option makes sense only when used in combination with the -\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. - -A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the -option. It is returned when the SSL exchange fails because the CRL file cannot -be loaded. A failure in certificate verification due to a revocation -information found in the CRL does not trigger this specific error. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -Used with HTTPS proxy. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:80"); - curl_easy_setopt(curl, CURLOPT_PROXY_CRLFILE, "/etc/certs/crl.pem"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md new file mode 100644 index 00000000000..d12c298009d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md @@ -0,0 +1,83 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_CRLFILE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PROXY_CRLFILE - HTTPS proxy Certificate Revocation List file + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CRLFILE, char *file); +~~~ + +# DESCRIPTION + +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a char pointer to a null-terminated string naming a *file* with the +concatenation of CRL (in PEM format) to use in the certificate validation that +occurs during the SSL exchange. + +When curl is built to use GnuTLS, there is no way to influence the use of CRL +passed to help in the verification process. When libcurl is built with OpenSSL +support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, +requiring CRL check against all the elements of the certificate chain if a CRL +file is passed. + +This option makes sense only when used in combination with the +CURLOPT_PROXY_SSL_VERIFYPEER(3) option. + +A specific error code (*CURLE_SSL_CRL_BADFILE*) is defined with the option. It +is returned when the SSL exchange fails because the CRL file cannot be loaded. +A failure in certificate verification due to a revocation information found in +the CRL does not trigger this specific error. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +Used with HTTPS proxy. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:80"); + curl_easy_setopt(curl, CURLOPT_PROXY_CRLFILE, "/etc/certs/crl.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 deleted file mode 100644 index 5ddbc712c69..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 +++ /dev/null @@ -1,84 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_ISSUERCERT 3 "24 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_PROXY_ISSUERCERT \- proxy issuer SSL certificate filename -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_ISSUERCERT, char *file); -.fi -.SH DESCRIPTION -Pass a char * to a null-terminated string naming a \fIfile\fP holding a CA -certificate in PEM format. If the option is set, an additional check against -the peer certificate is performed to verify the issuer of the the HTTPS proxy -is indeed the one associated with the certificate provided by the option. -This additional check is useful in multi-level PKI where one needs to enforce -that the peer certificate is from a specific branch of the tree. - -This option makes sense only when used in combination with the -\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the -check is not considered as failure. - -A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, -which is returned if the setup of the SSL/TLS session has failed due to a -mismatch with the issuer of peer certificate -(\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP has to be set too for the check to -fail). - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS-based protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* using an HTTPS proxy */ - curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); - curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT, "/etc/certs/cacert.pem"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.71.0. This option is supported by the OpenSSL backends. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_ISSUERCERT (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md new file mode 100644 index 00000000000..3b289d2d4d9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md @@ -0,0 +1,82 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_ISSUERCERT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ISSUERCERT (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PROXY_ISSUERCERT - proxy issuer SSL certificate filename + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_ISSUERCERT, char *file); +~~~ + +# DESCRIPTION + +Pass a char pointer to a null-terminated string naming a *file* holding a CA +certificate in PEM format. If the option is set, an additional check against +the peer certificate is performed to verify the issuer of the HTTPS proxy is +indeed the one associated with the certificate provided by the option. This +additional check is useful in multi-level PKI where one needs to enforce that +the peer certificate is from a specific branch of the tree. + +This option makes sense only when used in combination with the +CURLOPT_PROXY_SSL_VERIFYPEER(3) option. Otherwise, the result of the +check is not considered as failure. + +A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, +which is returned if the setup of the SSL/TLS session has failed due to a +mismatch with the issuer of peer certificate +(CURLOPT_PROXY_SSL_VERIFYPEER(3) has to be set too for the check to +fail). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS-based protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* using an HTTPS proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT, "/etc/certs/cacert.pem"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.71.0. This option is supported by the OpenSSL backends. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md similarity index 50% rename from docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.3 rename to docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md index 4f94d2eb053..41a2a18964d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md @@ -1,68 +1,67 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_ISSUERCERT_BLOB 3 "24 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_PROXY_ISSUERCERT_BLOB \- proxy issuer SSL certificate from memory blob -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_ISSUERCERT_BLOB +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ISSUERCERT_BLOB (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PROXY_ISSUERCERT_BLOB - proxy issuer SSL certificate from memory blob + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_ISSUERCERT_BLOB, struct curl_blob *blob); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a curl_blob struct, which contains information (pointer and size) about a memory block with binary data of a CA certificate in PEM format. If the option is set, an additional check against the peer certificate -is performed to verify the issuer of the the HTTPS proxy is indeed the one +is performed to verify the issuer of the HTTPS proxy is indeed the one associated with the certificate provided by the option. This additional check is useful in multi-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree. This option should be used in combination with the -\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the +CURLOPT_PROXY_SSL_VERIFYPEER(3) option. Otherwise, the result of the check is not considered as failure. A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, which is returned if the setup of the SSL/TLS session has failed due to a mismatch with the issuer of peer certificate -(\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP has to be set too for the check to -fail). +(CURLOPT_PROXY_SSL_VERIFYPEER(3) has to be set too for the check to fail). If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. -This option is an alternative to \fICURLOPT_PROXY_ISSUERCERT(3)\fP which +This option is an alternative to CURLOPT_PROXY_ISSUERCERT(3) which instead expects a file name as input. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All TLS-based protocols -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c extern char *certificateData; /* point to the data */ size_t filesize; /* size of the data */ @@ -84,15 +83,13 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.71.0. This option is supported by the OpenSSL backends. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_ISSUERCERT_BLOB (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 deleted file mode 100644 index 8d0ba91a01b..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_KEYPASSWD 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_KEYPASSWD \- passphrase for the proxy private key -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_KEYPASSWD, char *pwd); -.fi -.SH DESCRIPTION -This option is for connecting to an HTTPS proxy, not an HTTPS server. - -Pass a pointer to a null-terminated string as parameter. It is used as the -password required to use the \fICURLOPT_PROXY_SSLKEY(3)\fP private key. You -never need a pass phrase to load a certificate but you need one to load your -private key. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -Used with HTTPS proxy -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); - curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "superman"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 -.SH RETURN VALUE -Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_KEYPASSWD (3), -.BR CURLOPT_PROXY_SSLKEY (3), -.BR CURLOPT_SSH_PRIVATE_KEYFILE (3), -.BR CURLOPT_SSLKEY (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md new file mode 100644 index 00000000000..b29d95f07d3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_KEYPASSWD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_KEYPASSWD (3) + - CURLOPT_PROXY_SSLKEY (3) + - CURLOPT_SSH_PRIVATE_KEYFILE (3) + - CURLOPT_SSLKEY (3) +--- + +# NAME + +CURLOPT_PROXY_KEYPASSWD - passphrase for the proxy private key + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_KEYPASSWD, char *pwd); +~~~ + +# DESCRIPTION + +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a pointer to a null-terminated string as parameter. It is used as the +password required to use the CURLOPT_PROXY_SSLKEY(3) private key. You +never need a pass phrase to load a certificate but you need one to load your +private key. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +Used with HTTPS proxy + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "superman"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +# RETURN VALUE + +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md similarity index 54% rename from docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 rename to docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md index 631d42f8067..37110bba645 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md @@ -1,57 +1,58 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_PINNEDPUBLICKEY 3 "24 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_PINNEDPUBLICKEY \- pinned public key for https proxy -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_PINNEDPUBLICKEY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PINNEDPUBLICKEY (3) + - CURLOPT_PROXY_CAINFO (3) + - CURLOPT_PROXY_CAPATH (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PROXY_PINNEDPUBLICKEY - pinned public key for https proxy + +# SYNOPSIS + +~~~c #include -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_PINNEDPUBLICKEY, char *pinnedpubkey); -.fi -.SH DESCRIPTION +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_PINNEDPUBLICKEY, + char *pinnedpubkey); +~~~ + +# DESCRIPTION + Pass a pointer to a null-terminated string as parameter. The string can be the -file name of your pinned public key. The file format expected is "PEM" or "DER". -The string can also be any number of base64 encoded sha256 hashes preceded by -"sha256//" and separated by ";" +file name of your pinned public key. The file format expected is "PEM" or +"DER". The string can also be any number of base64 encoded sha256 hashes +preceded by "sha256//" and separated by ";" When negotiating a TLS or SSL connection, the https proxy 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, libcurl aborts the connection before sending or receiving any data. -On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. +On mismatch, *CURLE_SSL_PINNEDPUBKEYNOTMATCH* is returned. The application does not have to keep the string around after setting this option. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -67,11 +68,13 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH PUBLIC KEY EXTRACTION +~~~ + +# PUBLIC KEY EXTRACTION + If you do not have the https proxy server's public key file you can extract it from the https proxy server's certificate. -.nf +~~~c # retrieve the server's certificate if you do not already have it # # be sure to examine the certificate to see if it is what you expected @@ -82,40 +85,40 @@ from the https proxy server's certificate. # - If you do not have sed, then just copy the certificate into a file: # Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----. # -openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem +openssl s_client -servername www.example.com -connect www.example.com:443 \ + < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem # extract public key in pem format from certificate openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem # convert public key from pem to der -openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem -out www.example.com.pubkey.der +openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem \ + -out www.example.com.pubkey.der # sha256 hash and base64 encode der to string for use openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64 -.fi +~~~ The public key in PEM format contains a header, base64 data and a footer: -.nf +~~~c -----BEGIN PUBLIC KEY----- [BASE 64 DATA] -----END PUBLIC KEY----- -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + PEM/DER support: - 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL + 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL sha256 support: - 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL + 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL Other SSL backends not supported. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PINNEDPUBLICKEY (3), -.BR CURLOPT_PROXY_CAINFO (3), -.BR CURLOPT_PROXY_CAPATH (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 deleted file mode 100644 index 712836f6025..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 +++ /dev/null @@ -1,67 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SERVICE_NAME 3 "17 Jun 2015" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SERVICE_NAME \- proxy authentication service name -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SERVICE_NAME, - char *name); -.fi -.SH DESCRIPTION -Pass a char * as parameter to a string holding the \fIname\fP of the -service. The default service name is \fB"HTTP"\fP for HTTP based proxies and -\fB"rcmd"\fP for SOCKS5. This option allows you to change it. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -See above -.SH PROTOCOLS -All network protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY_SERVICE_NAME, "custom"); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.43.0 for HTTP proxies, 7.49.0 for SOCKS5 proxies. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYTYPE (3), -.BR CURLOPT_SERVICE_NAME (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md new file mode 100644 index 00000000000..73e5cb72ad9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SERVICE_NAME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_PROXYTYPE (3) + - CURLOPT_SERVICE_NAME (3) +--- + +# NAME + +CURLOPT_PROXY_SERVICE_NAME - proxy authentication service name + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SERVICE_NAME, + char *name); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter to a string holding the *name* of the +service. The default service name is **"HTTP"** for HTTP based proxies and +**"rcmd"** for SOCKS5. This option allows you to change it. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +See above + +# PROTOCOLS + +All network protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY_SERVICE_NAME, "custom"); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.43.0 for HTTP proxies, 7.49.0 for SOCKS5 proxies. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 deleted file mode 100644 index 54e6f545ba9..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSLCERT 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSLCERT \- HTTPS proxy client certificate -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT, char *cert); -.fi -.SH DESCRIPTION -This option is for connecting to an HTTPS proxy, not an HTTPS server. - -Pass a pointer to a null-terminated string as parameter. The string should be -the file name of your client certificate used to connect to the HTTPS proxy. -The default format is "P12" on Secure Transport and "PEM" on other engines, -and can be changed with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP. - -With Secure Transport, this can also be the nickname of the certificate you -wish to authenticate with as it is named in the security database. If you want -to use a file from the current directory, please precede it with "./" prefix, -in order to avoid confusion with a nickname. - -When using a client certificate, you most likely also need to provide a -private key with \fICURLOPT_PROXY_SSLKEY(3)\fP. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -Used with HTTPS proxy -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 -.SH RETURN VALUE -Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSLCERTTYPE (3), -.BR CURLOPT_PROXY_SSLKEY (3), -.BR CURLOPT_SSLCERT (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md new file mode 100644 index 00000000000..0a1539f8b4b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md @@ -0,0 +1,79 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSLCERT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLCERTTYPE (3) + - CURLOPT_PROXY_SSLKEY (3) + - CURLOPT_SSLCERT (3) +--- + +# NAME + +CURLOPT_PROXY_SSLCERT - HTTPS proxy client certificate + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT, char *cert); +~~~ + +# DESCRIPTION + +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a pointer to a null-terminated string as parameter. The string should be +the file name of your client certificate used to connect to the HTTPS proxy. +The default format is "P12" on Secure Transport and "PEM" on other engines, +and can be changed with CURLOPT_PROXY_SSLCERTTYPE(3). + +With Secure Transport, this can also be the nickname of the certificate you +wish to authenticate with as it is named in the security database. If you want +to use a file from the current directory, please precede it with "./" prefix, +in order to avoid confusion with a nickname. + +When using a client certificate, you most likely also need to provide a +private key with CURLOPT_PROXY_SSLKEY(3). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +Used with HTTPS proxy + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +# RETURN VALUE + +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 deleted file mode 100644 index 380595c7e26..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSLCERTTYPE 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSLCERTTYPE \- type of the proxy client SSL certificate -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERTTYPE, char *type); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. The string should be -the format of your client certificate used when connecting to an HTTPS proxy. - -Supported formats are "PEM" and "DER", except with Secure Transport or -Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or -later, or OS X 10.7 or later) and Schannel support "P12" for PKCS#12-encoded -files. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -"PEM" -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 - -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSLCERT (3), -.BR CURLOPT_PROXY_SSLKEY (3), -.BR CURLOPT_SSLCERTTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md new file mode 100644 index 00000000000..ce6c50887c8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSLCERTTYPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLCERT (3) + - CURLOPT_PROXY_SSLKEY (3) + - CURLOPT_SSLCERTTYPE (3) +--- + +# NAME + +CURLOPT_PROXY_SSLCERTTYPE - type of the proxy client SSL certificate + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERTTYPE, char *type); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. The string should be +the format of your client certificate used when connecting to an HTTPS proxy. + +Supported formats are "PEM" and "DER", except with Secure Transport or +Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or +later, or OS X 10.7 or later) and Schannel support "P12" for PKCS#12-encoded +files. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +"PEM" + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 deleted file mode 100644 index a033193d1bf..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 +++ /dev/null @@ -1,87 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSLCERT_BLOB 3 "24 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSLCERT_BLOB \- SSL proxy client certificate from memory blob -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT_BLOB, - struct curl_blob *blob); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_blob structure, which contains information (pointer -and size) about a memory block with binary data of the certificate used to -connect to the HTTPS proxy. The format must be "P12" on Secure Transport or -Schannel. The format must be "P12" or "PEM" on OpenSSL. The string "P12" or -"PEM" must be specified with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP. - -If the blob is initialized with the flags member of struct curl_blob set to -CURL_BLOB_COPY, the application does not have to keep the buffer around after -setting this. - -This option is an alternative to \fICURLOPT_PROXY_SSLCERT(3)\fP which instead -expects a file name as input. -.SH DEFAULT -NULL -.SH PROTOCOLS -Used with HTTPS proxy -.SH EXAMPLE -.nf - -extern char *certificateData; /* point to data */ -extern size_t filesize; /* size of the data */ - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - struct curl_blob blob; - blob.data = certificateData; - blob.len = filesize; - blob.flags = CURL_BLOB_COPY; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &blob); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport and -Schannel backends. -.SH RETURN VALUE -Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSLCERT (3), -.BR CURLOPT_PROXY_SSLCERTTYPE (3), -.BR CURLOPT_PROXY_SSLKEY (3), -.BR CURLOPT_SSLCERT_BLOB (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md new file mode 100644 index 00000000000..d0b1407c32e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md @@ -0,0 +1,85 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSLCERT_BLOB +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLCERT (3) + - CURLOPT_PROXY_SSLCERTTYPE (3) + - CURLOPT_PROXY_SSLKEY (3) + - CURLOPT_SSLCERT_BLOB (3) +--- + +# NAME + +CURLOPT_PROXY_SSLCERT_BLOB - SSL proxy client certificate from memory blob + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT_BLOB, + struct curl_blob *blob); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_blob structure, which contains information (pointer +and size) about a memory block with binary data of the certificate used to +connect to the HTTPS proxy. The format must be "P12" on Secure Transport or +Schannel. The format must be "P12" or "PEM" on OpenSSL. The string "P12" or +"PEM" must be specified with CURLOPT_PROXY_SSLCERTTYPE(3). + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +This option is an alternative to CURLOPT_PROXY_SSLCERT(3) which instead +expects a file name as input. + +# DEFAULT + +NULL + +# PROTOCOLS + +Used with HTTPS proxy + +# EXAMPLE + +~~~c + +extern char *certificateData; /* point to data */ +extern size_t filesize; /* size of the data */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob blob; + blob.data = certificateData; + blob.len = filesize; + blob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &blob); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport and +Schannel backends. + +# RETURN VALUE + +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 deleted file mode 100644 index ce79f44a6fa..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSLKEY 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSLKEY \- private key file for HTTPS proxy client cert -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEY, char *keyfile); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. The string should be -the file name of your private key used for connecting to the HTTPS proxy. The -default format is "PEM" and can be changed with -\fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. - -(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and -Schannel SSL backends because they expect the private key to be already -present in the key chain or PKCS#12 file containing the certificate. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 - -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSLCERT (3), -.BR CURLOPT_PROXY_SSLKEYTYPE (3), -.BR CURLOPT_SSLCERT (3), -.BR CURLOPT_SSLKEY (3), -.BR CURLOPT_SSLKEYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md new file mode 100644 index 00000000000..59385980627 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSLKEY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLCERT (3) + - CURLOPT_PROXY_SSLKEYTYPE (3) + - CURLOPT_SSLCERT (3) + - CURLOPT_SSLKEY (3) + - CURLOPT_SSLKEYTYPE (3) +--- + +# NAME + +CURLOPT_PROXY_SSLKEY - private key file for HTTPS proxy client cert + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEY, char *keyfile); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. The string should be +the file name of your private key used for connecting to the HTTPS proxy. The +default format is "PEM" and can be changed with +CURLOPT_PROXY_SSLKEYTYPE(3). + +(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and +Schannel SSL backends because they expect the private key to be already +present in the key chain or PKCS#12 file containing the certificate. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 deleted file mode 100644 index dfa6ce6d481..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSLKEYTYPE 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSLKEYTYPE \- type of the proxy private key file -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEYTYPE, char *type); -.fi -.SH DESCRIPTION -This option is for connecting to an HTTPS proxy, not an HTTPS server. - -Pass a pointer to a null-terminated string as parameter. The string should be -the format of your private key. Supported formats are "PEM", "DER" and "ENG". - -The application does not have to keep the string around after setting this -option. -.SH PROTOCOLS -Used with HTTPS proxy -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEYTYPE, "PEM"); - curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSLCERT (3), -.BR CURLOPT_PROXY_SSLKEY (3), -.BR CURLOPT_SSLKEYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md new file mode 100644 index 00000000000..97960f43702 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSLKEYTYPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLCERT (3) + - CURLOPT_PROXY_SSLKEY (3) + - CURLOPT_SSLKEYTYPE (3) +--- + +# NAME + +CURLOPT_PROXY_SSLKEYTYPE - type of the proxy private key file + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEYTYPE, char *type); +~~~ + +# DESCRIPTION + +This option is for connecting to an HTTPS proxy, not an HTTPS server. + +Pass a pointer to a null-terminated string as parameter. The string should be +the format of your private key. Supported formats are "PEM", "DER" and "ENG". + +The application does not have to keep the string around after setting this +option. + +# PROTOCOLS + +Used with HTTPS proxy + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEYTYPE, "PEM"); + curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md similarity index 52% rename from docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.3 rename to docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md index 034e1fe0ec4..48bb2e88aad 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md @@ -1,52 +1,50 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSLKEY_BLOB 3 "24 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSLKEY_BLOB \- private key for proxy cert from memory blob -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSLKEY_BLOB +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSLKEY (3) + - CURLOPT_SSLKEYTYPE (3) + - CURLOPT_SSLKEY_BLOB (3) +--- + +# NAME + +CURLOPT_PROXY_SSLKEY_BLOB - private key for proxy cert from memory blob + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEY_BLOB, struct curl_blob *blob); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a curl_blob structure that contains information (pointer and size) about the private key for connecting to the HTTPS proxy. Compatible with OpenSSL. The format (like "PEM") must be specified with -\fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. +CURLOPT_PROXY_SSLKEYTYPE(3). If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c extern char *certificateData; /* point to data */ extern size_t filesize; /* size of data */ @@ -76,13 +74,13 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.71.0. This option is supported by the OpenSSL backends. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSLKEY (3), -.BR CURLOPT_SSLKEY_BLOB (3), -.BR CURLOPT_SSLKEYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 deleted file mode 100644 index 3c3fe028962..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 +++ /dev/null @@ -1,110 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSLVERSION 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSLVERSION \- preferred HTTPS proxy TLS version -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLVERSION, - long version); -.fi -.SH DESCRIPTION -Pass a long as parameter to control which version of SSL/TLS to attempt to use -when connecting to an HTTPS proxy. - -Use one of the available defines for this purpose. The available options are: -.RS -.IP CURL_SSLVERSION_DEFAULT -The default action. This attempts to figure out the remote SSL protocol -version. -.IP CURL_SSLVERSION_TLSv1 -TLSv1.x -.IP CURL_SSLVERSION_TLSv1_0 -TLSv1.0 -.IP CURL_SSLVERSION_TLSv1_1 -TLSv1.1 -.IP CURL_SSLVERSION_TLSv1_2 -TLSv1.2 -.IP CURL_SSLVERSION_TLSv1_3 -TLSv1.3 -.RE -The maximum TLS version can be set by using \fIone\fP of the -CURL_SSLVERSION_MAX_ macros below. It is also possible to OR \fIone\fP of the -CURL_SSLVERSION_ macros with \fIone\fP of the CURL_SSLVERSION_MAX_ macros. -The MAX macros are not supported for WolfSSL. -.RS -.IP CURL_SSLVERSION_MAX_DEFAULT -The flag defines the maximum supported TLS version as TLSv1.2, or the default -value from the SSL library. -(Added in 7.54.0) -.IP CURL_SSLVERSION_MAX_TLSv1_0 -The flag defines maximum supported TLS version as TLSv1.0. -(Added in 7.54.0) -.IP CURL_SSLVERSION_MAX_TLSv1_1 -The flag defines maximum supported TLS version as TLSv1.1. -(Added in 7.54.0) -.IP CURL_SSLVERSION_MAX_TLSv1_2 -The flag defines maximum supported TLS version as TLSv1.2. -(Added in 7.54.0) -.IP CURL_SSLVERSION_MAX_TLSv1_3 -The flag defines maximum supported TLS version as TLSv1.3. -(Added in 7.54.0) -.RE - -In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were -documented to allow \fIonly\fP the specified TLS version, but behavior was -inconsistent depending on the TLS library. - -.SH DEFAULT -CURL_SSLVERSION_DEFAULT -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* ask libcurl to use TLS version 1.0 or later */ - curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTP_VERSION (3), -.BR CURLOPT_IPRESOLVE (3), -.BR CURLOPT_SSLVERSION (3), -.BR CURLOPT_USE_SSL (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md new file mode 100644 index 00000000000..6f159e87d02 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md @@ -0,0 +1,125 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSLVERSION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTP_VERSION (3) + - CURLOPT_IPRESOLVE (3) + - CURLOPT_SSLVERSION (3) + - CURLOPT_USE_SSL (3) +--- + +# NAME + +CURLOPT_PROXY_SSLVERSION - preferred HTTPS proxy TLS version + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLVERSION, + long version); +~~~ + +# DESCRIPTION + +Pass a long as parameter to control which version of SSL/TLS to attempt to use +when connecting to an HTTPS proxy. + +Use one of the available defines for this purpose. The available options are: + +## CURL_SSLVERSION_DEFAULT + +The default action. This attempts to figure out the remote SSL protocol +version. + +## CURL_SSLVERSION_TLSv1 + +TLSv1.x + +## CURL_SSLVERSION_TLSv1_0 + +TLSv1.0 + +## CURL_SSLVERSION_TLSv1_1 + +TLSv1.1 + +## CURL_SSLVERSION_TLSv1_2 + +TLSv1.2 + +## CURL_SSLVERSION_TLSv1_3 + +TLSv1.3 +The maximum TLS version can be set by using *one* of the +CURL_SSLVERSION_MAX_ macros below. It is also possible to OR *one* of the +CURL_SSLVERSION_ macros with *one* of the CURL_SSLVERSION_MAX_ macros. +The MAX macros are not supported for WolfSSL. + +## CURL_SSLVERSION_MAX_DEFAULT + +The flag defines the maximum supported TLS version as TLSv1.2, or the default +value from the SSL library. +(Added in 7.54.0) + +## CURL_SSLVERSION_MAX_TLSv1_0 + +The flag defines maximum supported TLS version as TLSv1.0. +(Added in 7.54.0) + +## CURL_SSLVERSION_MAX_TLSv1_1 + +The flag defines maximum supported TLS version as TLSv1.1. +(Added in 7.54.0) + +## CURL_SSLVERSION_MAX_TLSv1_2 + +The flag defines maximum supported TLS version as TLSv1.2. +(Added in 7.54.0) + +## CURL_SSLVERSION_MAX_TLSv1_3 + +The flag defines maximum supported TLS version as TLSv1.3. +(Added in 7.54.0) + +In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were +documented to allow *only* the specified TLS version, but behavior was +inconsistent depending on the TLS library. + +# DEFAULT + +CURL_SSLVERSION_DEFAULT + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* ask libcurl to use TLS version 1.0 or later */ + curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 deleted file mode 100644 index 5677c655aff..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 +++ /dev/null @@ -1,93 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSL_CIPHER_LIST 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSL_CIPHER_LIST \- ciphers to use for HTTPS proxy -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_CIPHER_LIST, - char *list); -.fi -.SH DESCRIPTION -Pass a char *, pointing to a null-terminated string holding the list of -ciphers to use for the connection to the HTTPS proxy. The list must be -syntactically correct, it consists of one or more cipher strings separated by -colons. Commas or spaces are also acceptable separators but colons are -normally used, \&!, \&- and \&+ can be used as operators. - -For OpenSSL and GnuTLS valid examples of cipher lists include \fBRC4-SHA\fP, -\fBSHA1+DES\fP, \fBTLSv1\fP and \fBDEFAULT\fP. The default list is normally -set when you compile OpenSSL. - -For WolfSSL, valid examples of cipher lists include \fBECDHE-RSA-RC4-SHA\fP, -\fBAES256-SHA:AES256-SHA256\fP, etc. - -For BearSSL, valid examples of cipher lists include -\fBECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256\fP, or when using IANA names -\fBTLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256\fP, -etc. -With BearSSL you do not add/remove ciphers. If one uses this option then all -known ciphers are disabled and only those passed in are enabled. - -Find more details about cipher lists on this URL: - - https://curl.se/docs/ssl-ciphers.html - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL, use internal default -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost"); - curl_easy_setopt(curl, CURLOPT_PROXY_SSL_CIPHER_LIST, "TLSv1"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0, in 7.83.0 for BearSSL - -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSLVERSION (3), -.BR CURLOPT_PROXY_TLS13_CIPHERS (3), -.BR CURLOPT_SSL_CIPHER_LIST (3), -.BR CURLOPT_SSLVERSION (3), -.BR CURLOPT_TLS13_CIPHERS (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md new file mode 100644 index 00000000000..d7626c3768e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md @@ -0,0 +1,91 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSL_CIPHER_LIST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLVERSION (3) + - CURLOPT_PROXY_TLS13_CIPHERS (3) + - CURLOPT_SSLVERSION (3) + - CURLOPT_SSL_CIPHER_LIST (3) + - CURLOPT_TLS13_CIPHERS (3) +--- + +# NAME + +CURLOPT_PROXY_SSL_CIPHER_LIST - ciphers to use for HTTPS proxy + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_CIPHER_LIST, + char *list); +~~~ + +# DESCRIPTION + +Pass a char pointer, pointing to a null-terminated string holding the list of +ciphers to use for the connection to the HTTPS proxy. The list must be +syntactically correct, it consists of one or more cipher strings separated by +colons. Commas or spaces are also acceptable separators but colons are +normally used, &!, &- and &+ can be used as operators. + +For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**, +**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally +set when you compile OpenSSL. + +For WolfSSL, valid examples of cipher lists include **ECDHE-RSA-RC4-SHA**, +**AES256-SHA:AES256-SHA256**, etc. + +For BearSSL, valid examples of cipher lists include +**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using IANA names +**TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256**, +etc. +With BearSSL you do not add/remove ciphers. If one uses this option then all +known ciphers are disabled and only those passed in are enabled. + +Find more details about cipher lists on this URL: + + https://curl.se/docs/ssl-ciphers.html + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL, use internal default + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost"); + curl_easy_setopt(curl, CURLOPT_PROXY_SSL_CIPHER_LIST, "TLSv1"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0, in 7.83.0 for BearSSL + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md similarity index 60% rename from docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 rename to docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md index b64285afc18..30d6935a10c 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md @@ -1,66 +1,69 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSL_OPTIONS 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSL_OPTIONS \- HTTPS proxy SSL behavior options -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSL_OPTIONS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLVERSION (3) + - CURLOPT_PROXY_SSL_CIPHER_LIST (3) + - CURLOPT_SSLVERSION (3) + - CURLOPT_SSL_CIPHER_LIST (3) +--- + +# NAME + +CURLOPT_PROXY_SSL_OPTIONS - HTTPS proxy SSL behavior options + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_OPTIONS, long bitmask); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a long with a bitmask to tell libcurl about specific SSL behaviors. Available bits: -.IP CURLSSLOPT_ALLOW_BEAST + +## CURLSSLOPT_ALLOW_BEAST + Tells libcurl to not attempt to use any workarounds for a security flaw in the -SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, +SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, the SSL layer libcurl uses may use a work-around for this flaw although it might cause interoperability problems with some (older) SSL implementations. WARNING: avoiding this work-around lessens the security, and by setting this -option to 1 you ask for exactly that. This option is only supported for -Secure Transport and OpenSSL. -.IP CURLSSLOPT_NO_REVOKE +option to 1 you ask for exactly that. This option is only supported for Secure +Transport and OpenSSL. + +## CURLSSLOPT_NO_REVOKE + Tells libcurl to disable certificate revocation checks for those SSL backends where such behavior is present. This option is only supported for Schannel (the native Windows SSL library), with an exception in the case of Windows' Untrusted Publishers block list which it seems cannot be bypassed. (Added in 7.44.0) -.IP CURLSSLOPT_NO_PARTIALCHAIN + +## CURLSSLOPT_NO_PARTIALCHAIN + Tells libcurl to not accept "partial" certificate chains, which it otherwise does by default. This option is only supported for OpenSSL and fails the certificate verification if the chain ends with an intermediate certificate and not with a root cert. (Added in 7.68.0) -.IP CURLSSLOPT_REVOKE_BEST_EFFORT + +## CURLSSLOPT_REVOKE_BEST_EFFORT + Tells libcurl to ignore certificate revocation checks in case of missing or offline distribution points for those SSL backends where such behavior is present. This option is only supported for Schannel (the native Windows SSL -library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes +library). If combined with *CURLSSLOPT_NO_REVOKE*, the latter takes precedence. (Added in 7.70.0) -.IP CURLSSLOPT_NATIVE_CA + +## CURLSSLOPT_NATIVE_CA + Tell libcurl to use the operating system's native CA store for certificate verification. If you set this option and also set a CA certificate file or directory then during verification those certificates are searched in addition @@ -69,7 +72,9 @@ to the native CA store. Works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), macOS, Android and iOS (added in 8.3.0), with GnuTLS (added in 8.5.0) or on Windows when built to use OpenSSL (Added in 7.71.0). -.IP CURLSSLOPT_AUTO_CLIENT_CERT + +## CURLSSLOPT_AUTO_CLIENT_CERT + Tell libcurl to automatically locate and use a client certificate for authentication, when requested by the server. This option is only supported for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the @@ -77,12 +82,18 @@ default behavior in libcurl with Schannel. Since the server can request any certificate that supports client authentication in the OS certificate store it could be a privacy violation and unexpected. (Added in 7.77.0) -.SH DEFAULT + +# DEFAULT + 0 -.SH PROTOCOLS + +# PROTOCOLS + All TLS-based protocols -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -97,13 +108,12 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.52.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), -.BR CURLOPT_PROXY_SSLVERSION (3), -.BR CURLOPT_SSL_CIPHER_LIST (3), -.BR CURLOPT_SSLVERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 deleted file mode 100644 index 42a96b6c2ff..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 +++ /dev/null @@ -1,96 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSL_VERIFYHOST 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSL_VERIFYHOST \- verify the proxy certificate's name against host -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYHOST, - long verify); -.fi -.SH DESCRIPTION -Pass a long set to 2L as asking curl to \fIverify\fP in the HTTPS proxy's -certificate name fields against the proxy name. - -This option determines whether libcurl verifies that the proxy cert contains -the correct name for the name it is known as. - -When \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP is 2, the proxy certificate must -indicate that the server is the proxy to which you meant to connect to, or the -connection fails. - -Curl considers the proxy the intended one when the Common Name field or a -Subject Alternate Name field in the certificate matches the host name in the -proxy string which you told curl to use. - -If \fIverify\fP value is set to 1: - -In 7.28.0 and earlier: treated as a debug option of some sorts, not supported -anymore due to frequently leading to programmer mistakes. - -From 7.28.1 to 7.65.3: setting it to 1 made \fIcurl_easy_setopt(3)\fP return -an error and leaving the flag untouched. - -From 7.66.0: treats 1 and 2 the same. - -When the \fIverify\fP value is 0L, the connection succeeds regardless of the -names used in the certificate. Use that ability with caution! - -See also \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP to verify the digital signature -of the proxy certificate. -.SH DEFAULT -2 -.SH PROTOCOLS -All protocols when used over an HTTPS proxy. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Set the default value: strict name check please */ - curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYHOST, 2L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0. - -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not. - -If 1 is set as argument, \fICURLE_BAD_FUNCTION_ARGUMENT\fP is returned. -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_PROXY_CAINFO (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md new file mode 100644 index 00000000000..ff52383a174 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md @@ -0,0 +1,94 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSL_VERIFYHOST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_PROXY_CAINFO (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PROXY_SSL_VERIFYHOST - verify the proxy certificate's name against host + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYHOST, + long verify); +~~~ + +# DESCRIPTION + +Pass a long set to 2L as asking curl to *verify* in the HTTPS proxy's +certificate name fields against the proxy name. + +This option determines whether libcurl verifies that the proxy cert contains +the correct name for the name it is known as. + +When CURLOPT_PROXY_SSL_VERIFYHOST(3) is 2, the proxy certificate must +indicate that the server is the proxy to which you meant to connect to, or the +connection fails. + +Curl considers the proxy the intended one when the Common Name field or a +Subject Alternate Name field in the certificate matches the host name in the +proxy string which you told curl to use. + +If *verify* value is set to 1: + +In 7.28.0 and earlier: treated as a debug option of some sorts, not supported +anymore due to frequently leading to programmer mistakes. + +From 7.28.1 to 7.65.3: setting it to 1 made curl_easy_setopt(3) return +an error and leaving the flag untouched. + +From 7.66.0: treats 1 and 2 the same. + +When the *verify* value is 0L, the connection succeeds regardless of the +names used in the certificate. Use that ability with caution! + +See also CURLOPT_PROXY_SSL_VERIFYPEER(3) to verify the digital signature +of the proxy certificate. + +# DEFAULT + +2 + +# PROTOCOLS + +All protocols when used over an HTTPS proxy. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the default value: strict name check please */ + curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYHOST, 2L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0. + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not. + +If 1 is set as argument, *CURLE_BAD_FUNCTION_ARGUMENT* is returned. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 deleted file mode 100644 index 866f07c9f24..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 +++ /dev/null @@ -1,97 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_SSL_VERIFYPEER 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_SSL_VERIFYPEER \- verify the proxy's SSL certificate -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYPEER, - long verify); -.fi -.SH DESCRIPTION -Pass a long as parameter set to 1L to enable or 0L to disable. - -This option tells curl to verify the authenticity of the HTTPS proxy's -certificate. A value of 1 means curl verifies; 0 (zero) means it does not. - -This is the proxy version of \fICURLOPT_SSL_VERIFYPEER(3)\fP that is used for -ordinary HTTPS servers. - -When negotiating a TLS or SSL connection, the server sends a certificate -indicating its identity. Curl verifies whether the certificate is authentic, -i.e. that you can trust that the server is who the certificate says it is. -This trust is based on a chain of digital signatures, rooted in certification -authority (CA) certificates you supply. curl uses a default bundle of CA -certificates (the path for that is determined at build time) and you can -specify alternate certificates with the \fICURLOPT_PROXY_CAINFO(3)\fP option -or the \fICURLOPT_PROXY_CAPATH(3)\fP option. - -When \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled, and the verification -fails to prove that the certificate is authentic, the connection fails. When -the option is zero, the peer certificate verification succeeds regardless. - -Authenticating the certificate is not enough to be sure about the server. You -typically also want to ensure that the server is the server you mean to be -talking to. Use \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP for that. The check -that the host name in the certificate is valid for the host name you are -connecting to is done independently of the -\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. - -WARNING: disabling verification of the certificate allows bad guys to -man-in-the-middle the communication without you knowing it. Disabling -verification makes the communication insecure. Just having encryption on a -transfer is not enough as you cannot be sure that you are communicating with -the correct end-point. -.SH DEFAULT -1 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Set the default value: strict certificate check please */ - curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYPEER, 1L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 - -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3), -.BR CURLOPT_SSL_VERIFYHOST (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md new file mode 100644 index 00000000000..e4504068a71 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md @@ -0,0 +1,94 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_SSL_VERIFYPEER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_PROXY_SSL_VERIFYPEER - verify the proxy's SSL certificate + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYPEER, + long verify); +~~~ + +# DESCRIPTION + +Pass a long as parameter set to 1L to enable or 0L to disable. + +This option tells curl to verify the authenticity of the HTTPS proxy's +certificate. A value of 1 means curl verifies; 0 (zero) means it does not. + +This is the proxy version of CURLOPT_SSL_VERIFYPEER(3) that is used for +ordinary HTTPS servers. + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. Curl verifies whether the certificate is authentic, +i.e. that you can trust that the server is who the certificate says it is. +This trust is based on a chain of digital signatures, rooted in certification +authority (CA) certificates you supply. curl uses a default bundle of CA +certificates (the path for that is determined at build time) and you can +specify alternate certificates with the CURLOPT_PROXY_CAINFO(3) option or +the CURLOPT_PROXY_CAPATH(3) option. + +When CURLOPT_PROXY_SSL_VERIFYPEER(3) is enabled, and the verification +fails to prove that the certificate is authentic, the connection fails. When +the option is zero, the peer certificate verification succeeds regardless. + +Authenticating the certificate is not enough to be sure about the server. You +typically also want to ensure that the server is the server you mean to be +talking to. Use CURLOPT_PROXY_SSL_VERIFYHOST(3) for that. The check that the +host name in the certificate is valid for the host name you are connecting to +is done independently of the CURLOPT_PROXY_SSL_VERIFYPEER(3) option. + +WARNING: disabling verification of the certificate allows bad guys to +man-in-the-middle the communication without you knowing it. Disabling +verification makes the communication insecure. Just having encryption on a +transfer is not enough as you cannot be sure that you are communicating with +the correct end-point. + +# DEFAULT + +1 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the default value: strict certificate check please */ + curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYPEER, 1L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 deleted file mode 100644 index fd187add897..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_TLS13_CIPHERS 3 "25 May 2018" libcurl libcurl -.SH NAME -CURLOPT_PROXY_TLS13_CIPHERS \- ciphers suites for proxy TLS 1.3 -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLS13_CIPHERS, - char *list); -.fi -.SH DESCRIPTION -Pass a char *, pointing to a null-terminated string holding the list of cipher -suites to use for the TLS 1.3 connection to a proxy. The list must be -syntactically correct, it consists of one or more cipher suite strings -separated by colons. - -Find more details about cipher lists 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 \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP option. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL, use internal default -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLS13_CIPHERS, - "TLS_CHACHA20_POLY1305_SHA256"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0. -Available when built with OpenSSL >= 1.1.1. -.SH RETURN VALUE -Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), -.BR CURLOPT_PROXY_SSLVERSION (3), -.BR CURLOPT_SSL_CIPHER_LIST (3), -.BR CURLOPT_SSLVERSION (3), -.BR CURLOPT_TLS13_CIPHERS (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md new file mode 100644 index 00000000000..f3c5448f0a5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_TLS13_CIPHERS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLVERSION (3) + - CURLOPT_PROXY_SSL_CIPHER_LIST (3) + - CURLOPT_SSLVERSION (3) + - CURLOPT_SSL_CIPHER_LIST (3) + - CURLOPT_TLS13_CIPHERS (3) +--- + +# NAME + +CURLOPT_PROXY_TLS13_CIPHERS - ciphers suites for proxy TLS 1.3 + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLS13_CIPHERS, + char *list); +~~~ + +# DESCRIPTION + +Pass a char pointer, pointing to a null-terminated string holding the list of +cipher suites to use for the TLS 1.3 connection to a proxy. The list must be +syntactically correct, it consists of one or more cipher suite strings +separated by colons. + +Find more details about cipher lists 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 CURLOPT_PROXY_SSL_CIPHER_LIST(3) option. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL, use internal default + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLS13_CIPHERS, + "TLS_CHACHA20_POLY1305_SHA256"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0. +Available when built with OpenSSL >= 1.1.1. + +# RETURN VALUE + +Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 deleted file mode 100644 index 327b92a81d4..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_TLSAUTH_PASSWORD 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_TLSAUTH_PASSWORD \- password to use for proxy TLS authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_PASSWORD, - char *pwd); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should point to the null-terminated password -to use for the TLS authentication method specified with the -\fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP option. Requires that the -\fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP option also be set. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0, with the OpenSSL and GnuTLS backends only -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_TLSAUTH_TYPE (3), -.BR CURLOPT_PROXY_TLSAUTH_USERNAME (3), -.BR CURLOPT_TLSAUTH_TYPE (3), -.BR CURLOPT_TLSAUTH_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md new file mode 100644 index 00000000000..778d1b79ce3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_TLSAUTH_PASSWORD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_TLSAUTH_TYPE (3) + - CURLOPT_PROXY_TLSAUTH_USERNAME (3) + - CURLOPT_TLSAUTH_TYPE (3) + - CURLOPT_TLSAUTH_USERNAME (3) +--- + +# NAME + +CURLOPT_PROXY_TLSAUTH_PASSWORD - password to use for proxy TLS authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_PASSWORD, + char *pwd); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should point to the null-terminated +password to use for the TLS authentication method specified with the +CURLOPT_PROXY_TLSAUTH_TYPE(3) option. Requires that the +CURLOPT_PROXY_TLSAUTH_USERNAME(3) option also be set. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0, with the OpenSSL and GnuTLS backends only + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 deleted file mode 100644 index c4fe02c8584..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_TLSAUTH_TYPE 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_TLSAUTH_TYPE \- HTTPS proxy TLS authentication methods -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_TYPE, - char *type); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. The string should be -the method of the TLS authentication used for the HTTPS connection. Supported -method is "SRP". - -.IP SRP -TLS-SRP authentication. Secure Remote Password authentication for TLS is -defined in RFC 5054 and provides mutual authentication if both sides have a -shared secret. To use TLS-SRP, you must also set the -\fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP and -\fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP options. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -blank -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0 - -You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this -to work. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), -.BR CURLOPT_PROXY_TLSAUTH_USERNAME (3), -.BR CURLOPT_TLSAUTH_PASSWORD (3), -.BR CURLOPT_TLSAUTH_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md new file mode 100644 index 00000000000..d4389188b06 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_TLSAUTH_TYPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_TLSAUTH_PASSWORD (3) + - CURLOPT_PROXY_TLSAUTH_USERNAME (3) + - CURLOPT_TLSAUTH_PASSWORD (3) + - CURLOPT_TLSAUTH_USERNAME (3) +--- + +# NAME + +CURLOPT_PROXY_TLSAUTH_TYPE - HTTPS proxy TLS authentication methods + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_TYPE, + char *type); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. The string should be +the method of the TLS authentication used for the HTTPS connection. Supported +method is "SRP". + +## SRP + +TLS-SRP authentication. Secure Remote Password authentication for TLS is +defined in RFC 5054 and provides mutual authentication if both sides have a +shared secret. To use TLS-SRP, you must also set the +CURLOPT_PROXY_TLSAUTH_USERNAME(3) and +CURLOPT_PROXY_TLSAUTH_PASSWORD(3) options. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +blank + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0 + +You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this +to work. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 deleted file mode 100644 index e8362fa2f03..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_TLSAUTH_USERNAME 3 "16 Nov 2016" libcurl libcurl -.SH NAME -CURLOPT_PROXY_TLSAUTH_USERNAME \- user name to use for proxy TLS authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_USERNAME, - char *user); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should point to the null-terminated username -to use for the HTTPS proxy TLS authentication method specified with the -\fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP option. Requires that the -\fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP option also be set. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); - curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.52.0, with the OpenSSL and GnuTLS backends only. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), -.BR CURLOPT_PROXY_TLSAUTH_TYPE (3), -.BR CURLOPT_TLSAUTH_PASSWORD (3), -.BR CURLOPT_TLSAUTH_TYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md new file mode 100644 index 00000000000..612ff4f9293 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_TLSAUTH_USERNAME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_TLSAUTH_PASSWORD (3) + - CURLOPT_PROXY_TLSAUTH_TYPE (3) + - CURLOPT_TLSAUTH_PASSWORD (3) + - CURLOPT_TLSAUTH_TYPE (3) +--- + +# NAME + +CURLOPT_PROXY_TLSAUTH_USERNAME - user name to use for proxy TLS authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_USERNAME, + char *user); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should point to the null-terminated +username to use for the HTTPS proxy TLS authentication method specified with +the CURLOPT_PROXY_TLSAUTH_TYPE(3) option. Requires that the +CURLOPT_PROXY_TLSAUTH_PASSWORD(3) option also be set. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.52.0, with the OpenSSL and GnuTLS backends only. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 deleted file mode 100644 index f948613a8c3..00000000000 --- a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PROXY_TRANSFER_MODE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PROXY_TRANSFER_MODE \- append FTP transfer mode to URL for proxy -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TRANSFER_MODE, - long enabled); -.fi -.SH DESCRIPTION -Pass a long. If the value is set to 1 (one), it tells libcurl to set the -transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by -appending ;type=a or ;type=i to the URL. Without this setting, or it being set -to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT(3)\fP has no effect when -doing FTP via a proxy. Beware that not all proxies support this feature. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -FTP over proxy -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, - "ftp://example.com/old-server/file.txt"); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:80"); - curl_easy_setopt(curl, CURLOPT_PROXY_TRANSFER_MODE, 1L); - curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.18.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the -enabled value is not supported. -.SH "SEE ALSO" -.BR CURLOPT_CRLF (3), -.BR CURLOPT_TRANSFERTEXT (3), -.BR CURLOPT_HTTPPROXYTUNNEL (3), -.BR CURLOPT_PROXY (3) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md new file mode 100644 index 00000000000..c0fed8b21e1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PROXY_TRANSFER_MODE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CRLF (3) + - CURLOPT_HTTPPROXYTUNNEL (3) + - CURLOPT_PROXY (3) + - CURLOPT_TRANSFERTEXT (3) +--- + +# NAME + +CURLOPT_PROXY_TRANSFER_MODE - append FTP transfer mode to URL for proxy + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TRANSFER_MODE, + long enabled); +~~~ + +# DESCRIPTION + +Pass a long. If the value is set to 1 (one), it tells libcurl to set the +transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by +appending ;type=a or ;type=i to the URL. Without this setting, or it being set +to 0 (zero, the default), CURLOPT_TRANSFERTEXT(3) has no effect when +doing FTP via a proxy. Beware that not all proxies support this feature. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +FTP over proxy + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, + "ftp://example.com/old-server/file.txt"); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:80"); + curl_easy_setopt(curl, CURLOPT_PROXY_TRANSFER_MODE, 1L); + curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.18.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the +enabled value is not supported. diff --git a/docs/libcurl/opts/CURLOPT_PUT.3 b/docs/libcurl/opts/CURLOPT_PUT.3 deleted file mode 100644 index fb4e4c9bef0..00000000000 --- a/docs/libcurl/opts/CURLOPT_PUT.3 +++ /dev/null @@ -1,92 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_PUT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_PUT \- make an HTTP PUT request -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PUT, long put); -.fi -.SH DESCRIPTION -A parameter set to 1 tells the library to use HTTP PUT to transfer data. The -data should be set with \fICURLOPT_READDATA(3)\fP and -\fICURLOPT_INFILESIZE(3)\fP. - -This option is \fBdeprecated\fP since version 7.12.1. Use -\fICURLOPT_UPLOAD(3)\fP! -.SH DEFAULT -0, disabled -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -static size_t read_cb(char *ptr, size_t size, size_t nmemb, void *userdata) -{ - FILE *src = userdata; - /* copy as much data as possible into the 'ptr' buffer, but no more than - 'size' * 'nmemb' bytes! */ - size_t retcode = fread(ptr, size, nmemb, src); - - return retcode; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - FILE *src = fopen("local-file", "r"); - curl_off_t fsize; /* set this to the size of the input file */ - - /* we want to use our own read function */ - curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); - - /* enable PUT */ - curl_easy_setopt(curl, CURLOPT_PUT, 1L); - - /* specify target */ - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); - - /* now specify which pointer to pass to our callback */ - curl_easy_setopt(curl, CURLOPT_READDATA, src); - - /* Set the size of the file to upload */ - curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); - - /* Now run off and do what you have been told! */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Deprecated since 7.12.1. Do not use. -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTPGET (3), -.BR CURLOPT_MIMEPOST (3), -.BR CURLOPT_POSTFIELDS (3), -.BR CURLOPT_UPLOAD (3) diff --git a/docs/libcurl/opts/CURLOPT_PUT.md b/docs/libcurl/opts/CURLOPT_PUT.md new file mode 100644 index 00000000000..117eaedd7d4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PUT.md @@ -0,0 +1,89 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_PUT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPGET (3) + - CURLOPT_MIMEPOST (3) + - CURLOPT_POSTFIELDS (3) + - CURLOPT_UPLOAD (3) +--- + +# NAME + +CURLOPT_PUT - make an HTTP PUT request + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PUT, long put); +~~~ + +# DESCRIPTION + +A parameter set to 1 tells the library to use HTTP PUT to transfer data. The +data should be set with CURLOPT_READDATA(3) and +CURLOPT_INFILESIZE(3). + +This option is **deprecated** since version 7.12.1. Use CURLOPT_UPLOAD(3). + +# DEFAULT + +0, disabled + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +static size_t read_cb(char *ptr, size_t size, size_t nmemb, void *userdata) +{ + FILE *src = userdata; + /* copy as much data as possible into the 'ptr' buffer, but no more than + 'size' * 'nmemb' bytes */ + size_t retcode = fread(ptr, size, nmemb, src); + + return retcode; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + FILE *src = fopen("local-file", "r"); + curl_off_t fsize; /* set this to the size of the input file */ + + /* we want to use our own read function */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); + + /* enable PUT */ + curl_easy_setopt(curl, CURLOPT_PUT, 1L); + + /* specify target */ + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); + + /* now specify which pointer to pass to our callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, src); + + /* Set the size of the file to upload */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); + + /* Now run off and do what you have been told */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Deprecated since 7.12.1. Do not use. + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.3 b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.3 deleted file mode 100644 index f34e771ac8d..00000000000 --- a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_QUICK_EXIT 3 "30 Sep 2022" libcurl libcurl -.SH NAME -CURLOPT_QUICK_EXIT \- allow to exit quickly -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_QUICK_EXIT, - long value); -.SH DESCRIPTION -Pass a long as a parameter, 1L meaning that when recovering from a timeout, -libcurl should skip lengthy cleanups that are intended to avoid all kinds of -leaks (threads etc.), as the caller program is about to call exit() anyway. -This allows for a swift termination after a DNS timeout for example, by -canceling and/or forgetting about a resolver thread, at the expense of a -possible (though short-lived) leak of associated resources. -.SH DEFAULT -0 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_QUICK_EXIT, 1L); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.87.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FAILONERROR (3), -.BR CURLOPT_RESOLVE (3) diff --git a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md new file mode 100644 index 00000000000..4159c02fb6f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_QUICK_EXIT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_FAILONERROR (3) + - CURLOPT_RESOLVE (3) +--- + +# NAME + +CURLOPT_QUICK_EXIT - allow to exit quickly + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_QUICK_EXIT, + long value); +~~~ + +# DESCRIPTION + +Pass a long as a parameter, 1L meaning that when recovering from a timeout, +libcurl should skip lengthy cleanups that are intended to avoid all kinds of +leaks (threads etc.), as the caller program is about to call exit() anyway. +This allows for a swift termination after a DNS timeout for example, by +canceling and/or forgetting about a resolver thread, at the expense of a +possible (though short-lived) leak of associated resources. + +# DEFAULT + +0 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_QUICK_EXIT, 1L); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.87.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.3 b/docs/libcurl/opts/CURLOPT_QUOTE.md similarity index 56% rename from docs/libcurl/opts/CURLOPT_QUOTE.3 rename to docs/libcurl/opts/CURLOPT_QUOTE.md index 29e0154cd0c..f57b45eec11 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.3 +++ b/docs/libcurl/opts/CURLOPT_QUOTE.md @@ -1,44 +1,37 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_QUOTE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_QUOTE \- (S)FTP commands to run before transfer -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_QUOTE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CUSTOMREQUEST (3) + - CURLOPT_DIRLISTONLY (3) + - CURLOPT_POSTQUOTE (3) + - CURLOPT_PREQUOTE (3) +--- + +# NAME + +CURLOPT_QUOTE - (S)FTP commands to run before transfer + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_QUOTE, struct curl_slist *cmds); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a linked list of FTP or SFTP commands to pass to the server prior to your request. This is done before any other commands are issued (even before the CWD command for FTP). The linked list should be a fully valid list of 'struct curl_slist' structs properly filled in with text strings. Use -\fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear -the entire list afterwards with \fIcurl_slist_free_all(3)\fP. +curl_slist_append(3) to append strings (commands) to the list, and clear +the entire list afterwards with curl_slist_free_all(3). Disable this operation again by setting a NULL to this option. @@ -53,55 +46,91 @@ libcurl does not inspect, parse or "understand" the commands passed to the server using this option. If you change connection state, working directory or similar using quote commands, libcurl does not know about it. -The valid SFTP commands are: -.RS -.IP "atime date file" +The path arguments for FTP or SFTP can use single or double quotes to +distinguish a space from being the parameter separator or being a part of the +path. e.g. rename with sftp using a quote command like this: + + "rename 'test/_upload.txt' 'test/Hello World.txt'" + +# SFTP commands + +## 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 -\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) -.IP "chgrp group file" +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. -.IP "chmod mode file" + +## chmod mode file + The chmod command modifies the file mode bits of the specified file. The mode operand is an octal integer mode number. -.IP "chown user file" + +## 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. -.IP "ln source_file target_file" -The \fBln\fP and \fBsymlink\fP commands create a symbolic link at the + +## 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. -.IP "mkdir directory_name" + +## mkdir directory_name + The mkdir command creates the directory named by the directory_name operand. -.IP "mtime date file" + +## 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 -\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) -.IP "pwd" -The \fBpwd\fP command returns the absolute path of the current working +curl_getdate(3) man page for date expression details. (Added in 7.73.0) + +## pwd + +The **pwd** command returns the absolute path of the current working directory. -.IP "rename source target" + +## 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. -.IP "rm file" + +## rm file + The rm command removes the file specified by the file operand. -.IP "rmdir directory" + +## rmdir directory + The rmdir command removes the directory entry specified by the directory operand, provided it is empty. -.IP "statvfs file" + +## statvfs file + The statvfs command returns statistics on the file system in which specified file resides. (Added in 7.49.0) -.IP "symlink source_file target_file" + +## symlink source_file target_file + See ln. -.RE -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + SFTP and FTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { struct curl_slist *cmdlist = NULL; @@ -121,13 +150,12 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + SFTP support added in 7.16.3. *-prefix for SFTP added in 7.24.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_CUSTOMREQUEST (3), -.BR CURLOPT_DIRLISTONLY (3), -.BR CURLOPT_POSTQUOTE (3), -.BR CURLOPT_PREQUOTE (3) diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 deleted file mode 100644 index b226d15a0e7..00000000000 --- a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RANDOM_FILE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RANDOM_FILE \- file to read random data from -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANDOM_FILE, char *path); -.fi -.SH DESCRIPTION -Deprecated option. It serves no purpose anymore. - -Pass a char * to a null-terminated file name. The file might be used to read -from to seed the random engine for SSL and more. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL, not used -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_RANDOM_FILE, "junk.txt"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -If built with TLS enabled. Only the OpenSSL backend uses this, and only with -OpenSSL versions before 1.1.0. - -This option was deprecated in 7.84.0. -.SH RETURN VALUE -Returns CURLE_OK on success or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_EGDSOCKET (3) diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md new file mode 100644 index 00000000000..5331a68c907 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RANDOM_FILE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_EGDSOCKET (3) +--- + +# NAME + +CURLOPT_RANDOM_FILE - file to read random data from + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANDOM_FILE, char *path); +~~~ + +# DESCRIPTION + +Deprecated option. It serves no purpose anymore. + +Pass a char pointer to a null-terminated file name. The file might be used to +read from to seed the random engine for SSL and more. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL, not used + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_RANDOM_FILE, "junk.txt"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +If built with TLS enabled. Only the OpenSSL backend uses this, and only with +OpenSSL versions before 1.1.0. + +This option was deprecated in 7.84.0. + +# RETURN VALUE + +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_RANGE.3 b/docs/libcurl/opts/CURLOPT_RANGE.3 deleted file mode 100644 index 90ad666967a..00000000000 --- a/docs/libcurl/opts/CURLOPT_RANGE.3 +++ /dev/null @@ -1,86 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RANGE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RANGE \- byte range to request -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANGE, char *range); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should contain the specified range you want -to retrieve. It should be in the format "X-Y", where either X or Y may be left -out and X and Y are byte indexes. - -HTTP transfers also support several intervals, separated with commas as in -\fI"X-Y,N-M"\fP. Using this kind of multiple intervals causes the HTTP server -to send the response document in pieces (using standard MIME separation -techniques). Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows -servers to ignore range requests so even when you set \fICURLOPT_RANGE(3)\fP -for a request, you may end up getting the full response sent back. - -For RTSP, the formatting of a range should follow RFC 2326 Section 12.29. For -RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in -\fBnpt\fP, \fButc\fP, or \fBsmpte\fP formats. - -For HTTP PUT uploads this option should not be used, since it may conflict with -other options. - -Pass a NULL to this option to disable the use of ranges. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP, FTP, FILE, RTSP and SFTP. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* get the first 200 bytes */ - curl_easy_setopt(curl, CURLOPT_RANGE, "0-199"); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -FILE since 7.18.0, RTSP since 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK on success or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_MAX_RECV_SPEED_LARGE (3), -.BR CURLOPT_MAXFILESIZE_LARGE (3), -.BR CURLOPT_RESUME_FROM (3) diff --git a/docs/libcurl/opts/CURLOPT_RANGE.md b/docs/libcurl/opts/CURLOPT_RANGE.md new file mode 100644 index 00000000000..3f765bc61fa --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RANGE.md @@ -0,0 +1,84 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RANGE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_MAXFILESIZE_LARGE (3) + - CURLOPT_MAX_RECV_SPEED_LARGE (3) + - CURLOPT_RESUME_FROM (3) +--- + +# NAME + +CURLOPT_RANGE - byte range to request + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANGE, char *range); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should contain the specified range you +want to retrieve. It should be in the format "X-Y", where either X or Y may be +left out and X and Y are byte indexes. + +HTTP transfers also support several intervals, separated with commas as in +*"X-Y,N-M"*. Using this kind of multiple intervals causes the HTTP server +to send the response document in pieces (using standard MIME separation +techniques). Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows +servers to ignore range requests so even when you set CURLOPT_RANGE(3) +for a request, you may end up getting the full response sent back. + +For RTSP, the formatting of a range should follow RFC 2326 Section 12.29. For +RTSP, byte ranges are **not** permitted. Instead, ranges should be given in +**npt**, **utc**, or **smpte** formats. + +For HTTP PUT uploads this option should not be used, since it may conflict with +other options. + +Pass a NULL to this option to disable the use of ranges. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP, FTP, FILE, RTSP and SFTP. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* get the first 200 bytes */ + curl_easy_setopt(curl, CURLOPT_RANGE, "0-199"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +FILE since 7.18.0, RTSP since 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_READDATA.3 b/docs/libcurl/opts/CURLOPT_READDATA.3 deleted file mode 100644 index db0dcfc6095..00000000000 --- a/docs/libcurl/opts/CURLOPT_READDATA.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_READDATA 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_READDATA \- pointer passed to the read callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer); -.fi -.SH DESCRIPTION -Data \fIpointer\fP to pass to the file read function. If you use the -\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you get as input in -the fourth argument to the callback. - -If you do not specify a read callback but instead rely on the default internal -read function, this data must be a valid readable FILE * (cast to 'void *'). - -If you are using libcurl as a DLL on Windows, you must use the -\fICURLOPT_READFUNCTION(3)\fP callback if you set this option, otherwise you -might experience crashes. -.SH DEFAULT -By default, this is a FILE * to stdin. -.SH PROTOCOLS -This is used for all protocols when sending data. -.SH EXAMPLE -.nf -struct MyData { - void *custom; -}; - -int main(void) -{ - CURL *curl = curl_easy_init(); - struct MyData this; - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* pass pointer that gets passed in to the - CURLOPT_READFUNCTION callback */ - curl_easy_setopt(curl, CURLOPT_READDATA, &this); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -This option was once known by the older name CURLOPT_INFILE, the name -\fICURLOPT_READDATA(3)\fP was introduced in 7.9.7. -.SH RETURN VALUE -This returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_HEADERDATA (3), -.BR CURLOPT_READFUNCTION (3), -.BR CURLOPT_WRITEDATA (3), -.BR CURLOPT_WRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_READDATA.md b/docs/libcurl/opts/CURLOPT_READDATA.md new file mode 100644 index 00000000000..d7aa4ff9aca --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_READDATA.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_READDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADERDATA (3) + - CURLOPT_READFUNCTION (3) + - CURLOPT_WRITEDATA (3) + - CURLOPT_WRITEFUNCTION (3) +--- + +# NAME + +CURLOPT_READDATA - pointer passed to the read callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer); +~~~ + +# DESCRIPTION + +Data *pointer* to pass to the file read function. If you use the +CURLOPT_READFUNCTION(3) option, this is the pointer you get as input in +the fourth argument to the callback. + +If you do not specify a read callback but instead rely on the default internal +read function, this data must be a valid readable FILE * (cast to 'void *'). + +If you are using libcurl as a DLL on Windows, you must use the +CURLOPT_READFUNCTION(3) callback if you set this option, otherwise you +might experience crashes. + +# DEFAULT + +By default, this is a FILE * to stdin. + +# PROTOCOLS + +This is used for all protocols when sending data. + +# EXAMPLE + +~~~c +struct MyData { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + struct MyData this; + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* pass pointer that gets passed in to the + CURLOPT_READFUNCTION callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, &this); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +This option was once known by the older name CURLOPT_INFILE, the name +CURLOPT_READDATA(3) was introduced in 7.9.7. + +# RETURN VALUE + +This returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 deleted file mode 100644 index de689fbdcd9..00000000000 --- a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 +++ /dev/null @@ -1,125 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_READFUNCTION 3 "25 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_READFUNCTION \- read callback for data uploads -.SH SYNOPSIS -.nf -#include - -size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback); -.fi -.SH DESCRIPTION -Pass a pointer to your callback function, as the prototype shows above. - -This callback function gets called by libcurl as soon as it needs to read data -in order to send it to the peer - like if you ask it to upload or post data to -the server. The data area pointed at by the pointer \fIbuffer\fP should be -filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes -by your function. \fIsize\fP is always 1. - -Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option. - -Your function must return the actual number of bytes that it stored in the -data area pointed at by the pointer \fIbuffer\fP. Returning 0 signals -end-of-file to the library and causes it to stop the current transfer. - -If you stop the current transfer by returning 0 "pre-maturely" (i.e before the -server expected it, like when you have said you would upload N bytes and you -upload less than N bytes), you may experience that the server "hangs" waiting -for the rest of the data that is not sent. - -The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current -operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error -code from the transfer. - -The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this -connection to pause. See \fIcurl_easy_pause(3)\fP for further details. - -\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data -that the callback wants, or it is considered the final packet by the server -end and the transfer ends there. - -If you set this callback pointer to NULL, or do not set it at all, the default -internal read function is used. It is doing an fread() on the FILE * userdata -set with \fICURLOPT_READDATA(3)\fP. - -You can set the total size of the data you are sending by using -\fICURLOPT_INFILESIZE_LARGE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP, -depending on the type of transfer. For some transfer types it may be required -and it allows for better error checking. -.SH DEFAULT -The default internal read callback is fread(). -.SH PROTOCOLS -This is used for all protocols when doing uploads. -.SH EXAMPLE -.nf -size_t read_callback(char *ptr, size_t size, size_t nmemb, void *userdata) -{ - FILE *readhere = (FILE *)userdata; - curl_off_t nread; - - /* copy as much data as possible into the 'ptr' buffer, but no more than - 'size' * 'nmemb' bytes! */ - size_t retcode = fread(ptr, size, nmemb, readhere); - - nread = (curl_off_t)retcode; - - fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T - " bytes from file\\n", nread); - return retcode; -} - -int main(int argc, char **argv) -{ - FILE *file = fopen(argv[1], "rb"); - CURLcode result; - - CURL *curl = curl_easy_init(); - if(curl) { - /* set callback to use */ - curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback); - - /* pass in suitable argument to callback */ - curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file); - - result = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT -was added in 7.12.1. -.SH RETURN VALUE -This returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_POST (3), -.BR CURLOPT_READDATA (3), -.BR CURLOPT_SEEKFUNCTION (3), -.BR CURLOPT_UPLOAD (3), -.BR CURLOPT_UPLOAD_BUFFERSIZE (3), -.BR CURLOPT_WRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.md b/docs/libcurl/opts/CURLOPT_READFUNCTION.md new file mode 100644 index 00000000000..978440d138e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.md @@ -0,0 +1,123 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_READFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_POST (3) + - CURLOPT_READDATA (3) + - CURLOPT_SEEKFUNCTION (3) + - CURLOPT_UPLOAD (3) + - CURLOPT_UPLOAD_BUFFERSIZE (3) + - CURLOPT_WRITEFUNCTION (3) +--- + +# NAME + +CURLOPT_READFUNCTION - read callback for data uploads + +# SYNOPSIS + +~~~c +#include + +size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, as the prototype shows above. + +This callback function gets called by libcurl as soon as it needs to read data +in order to send it to the peer - like if you ask it to upload or post data to +the server. The data area pointed at by the pointer *buffer* should be +filled up with at most *size* multiplied with *nitems* number of bytes +by your function. *size* is always 1. + +Set the *userdata* argument with the CURLOPT_READDATA(3) option. + +Your function must return the actual number of bytes that it stored in the +data area pointed at by the pointer *buffer*. Returning 0 signals +end-of-file to the library and causes it to stop the current transfer. + +If you stop the current transfer by returning 0 "pre-maturely" (i.e before the +server expected it, like when you have said you would upload N bytes and you +upload less than N bytes), you may experience that the server "hangs" waiting +for the rest of the data that is not sent. + +The read callback may return *CURL_READFUNC_ABORT* to stop the current +operation immediately, resulting in a *CURLE_ABORTED_BY_CALLBACK* error +code from the transfer. + +The callback can return *CURL_READFUNC_PAUSE* to cause reading from this +connection to pause. See curl_easy_pause(3) for further details. + +**Bugs**: when doing TFTP uploads, you must return the exact amount of data +that the callback wants, or it is considered the final packet by the server +end and the transfer ends there. + +If you set this callback pointer to NULL, or do not set it at all, the default +internal read function is used. It is doing an fread() on the FILE * userdata +set with CURLOPT_READDATA(3). + +You can set the total size of the data you are sending by using +CURLOPT_INFILESIZE_LARGE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3), +depending on the type of transfer. For some transfer types it may be required +and it allows for better error checking. + +# DEFAULT + +The default internal read callback is fread(). + +# PROTOCOLS + +This is used for all protocols when doing uploads. + +# EXAMPLE + +~~~c +size_t read_callback(char *ptr, size_t size, size_t nmemb, void *userdata) +{ + FILE *readhere = (FILE *)userdata; + curl_off_t nread; + + /* copy as much data as possible into the 'ptr' buffer, but no more than + 'size' * 'nmemb' bytes! */ + size_t retcode = fread(ptr, size, nmemb, readhere); + + nread = (curl_off_t)retcode; + + fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T + " bytes from file\n", nread); + return retcode; +} + +int main(int argc, char **argv) +{ + FILE *file = fopen(argv[1], "rb"); + CURLcode result; + + CURL *curl = curl_easy_init(); + if(curl) { + /* set callback to use */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback); + + /* pass in suitable argument to callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file); + + result = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT +was added in 7.12.1. + +# RETURN VALUE + +This returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 deleted file mode 100644 index c45583d792c..00000000000 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 +++ /dev/null @@ -1,117 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_REDIR_PROTOCOLS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_REDIR_PROTOCOLS \- protocols allowed to redirect to -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS, long bitmask); -.fi -.SH DESCRIPTION -This option is deprecated. We strongly recommend using -\fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP instead because this option cannot -control all available protocols! - -Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask -limits what protocols libcurl may use in a transfer that it follows to in a -redirect when \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This allows you to -limit specific transfers to only be allowed to use a subset of protocols in -redirections. - -Protocols denied by \fICURLOPT_PROTOCOLS(3)\fP are not overridden by this -option. - -By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). -\fICURLPROTO_ALL\fP enables all protocols on redirect, including those -otherwise disabled for security. - -These are the available protocol defines: -.nf -CURLPROTO_DICT -CURLPROTO_FILE -CURLPROTO_FTP -CURLPROTO_FTPS -CURLPROTO_GOPHER -CURLPROTO_HTTP -CURLPROTO_HTTPS -CURLPROTO_IMAP -CURLPROTO_IMAPS -CURLPROTO_LDAP -CURLPROTO_LDAPS -CURLPROTO_POP3 -CURLPROTO_POP3S -CURLPROTO_RTMP -CURLPROTO_RTMPE -CURLPROTO_RTMPS -CURLPROTO_RTMPT -CURLPROTO_RTMPTE -CURLPROTO_RTMPTS -CURLPROTO_RTSP -CURLPROTO_SCP -CURLPROTO_SFTP -CURLPROTO_SMB -CURLPROTO_SMBS -CURLPROTO_SMTP -CURLPROTO_SMTPS -CURLPROTO_TELNET -CURLPROTO_TFTP -.fi -.SH DEFAULT -HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). - -Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 -SMB and SMBS. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(int argc, char **argv) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* pass in the URL from an external source */ - curl_easy_setopt(curl, CURLOPT_URL, argv[1]); - - /* only allow redirects to HTTP and HTTPS URLs */ - curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS, - CURLPROTO_HTTP | CURLPROTO_HTTPS); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.4, before then it would follow all protocols. Deprecated -since 7.85.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_SCHEME (3), -.BR CURLOPT_DEFAULT_PROTOCOL (3), -.BR CURLOPT_PROTOCOLS (3), -.BR CURLOPT_REDIR_PROTOCOLS_STR (3) diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md new file mode 100644 index 00000000000..4d06d465844 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md @@ -0,0 +1,115 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_REDIR_PROTOCOLS +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SCHEME (3) + - CURLOPT_DEFAULT_PROTOCOL (3) + - CURLOPT_PROTOCOLS (3) + - CURLOPT_REDIR_PROTOCOLS_STR (3) +--- + +# NAME + +CURLOPT_REDIR_PROTOCOLS - protocols allowed to redirect to + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS, long bitmask); +~~~ + +# DESCRIPTION + +This option is deprecated. We strongly recommend using +CURLOPT_REDIR_PROTOCOLS_STR(3) instead because this option cannot +control all available protocols! + +Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask +limits what protocols libcurl may use in a transfer that it follows to in a +redirect when CURLOPT_FOLLOWLOCATION(3) is enabled. This allows you to +limit specific transfers to only be allowed to use a subset of protocols in +redirections. + +Protocols denied by CURLOPT_PROTOCOLS(3) are not overridden by this +option. + +By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). +*CURLPROTO_ALL* enables all protocols on redirect, including those +otherwise disabled for security. + +These are the available protocol defines: +~~~c +CURLPROTO_DICT +CURLPROTO_FILE +CURLPROTO_FTP +CURLPROTO_FTPS +CURLPROTO_GOPHER +CURLPROTO_HTTP +CURLPROTO_HTTPS +CURLPROTO_IMAP +CURLPROTO_IMAPS +CURLPROTO_LDAP +CURLPROTO_LDAPS +CURLPROTO_POP3 +CURLPROTO_POP3S +CURLPROTO_RTMP +CURLPROTO_RTMPE +CURLPROTO_RTMPS +CURLPROTO_RTMPT +CURLPROTO_RTMPTE +CURLPROTO_RTMPTS +CURLPROTO_RTSP +CURLPROTO_SCP +CURLPROTO_SFTP +CURLPROTO_SMB +CURLPROTO_SMBS +CURLPROTO_SMTP +CURLPROTO_SMTPS +CURLPROTO_TELNET +CURLPROTO_TFTP +~~~ + +# DEFAULT + +HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). + +Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 +SMB and SMBS. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(int argc, char **argv) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow redirects to HTTP and HTTPS URLs */ + curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS, + CURLPROTO_HTTP | CURLPROTO_HTTPS); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.4, before then it would follow all protocols. Deprecated +since 7.85.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3 b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md similarity index 51% rename from docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3 rename to docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md index db243ad1dbe..9201a4b41f3 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3 +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md @@ -1,46 +1,40 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_REDIR_PROTOCOLS_STR 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_REDIR_PROTOCOLS_STR \- protocols allowed to redirect to -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_REDIR_PROTOCOLS_STR +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SCHEME (3) + - CURLOPT_DEFAULT_PROTOCOL (3) + - CURLOPT_PROTOCOLS (3) + - CURLOPT_PROTOCOLS_STR (3) + - CURLOPT_REDIR_PROTOCOLS (3) +--- + +# NAME + +CURLOPT_REDIR_PROTOCOLS_STR - protocols allowed to redirect to + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS_STR, char *spec); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a string that holds a comma-separated list of case insensitive protocol names (URL schemes). That list limits what protocols libcurl may use in a transfer that it follows to in a redirect when -\fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This option allows applications to +CURLOPT_FOLLOWLOCATION(3) is enabled. This option allows applications to limit specific transfers to only be allowed to use a subset of protocols in redirections. -Protocols denied by \fICURLOPT_PROTOCOLS_STR(3)\fP are not overridden by this +Protocols denied by CURLOPT_PROTOCOLS_STR(3) are not overridden by this option. By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects (since @@ -58,15 +52,21 @@ but are introduced in a future libcurl version. If trying to set a non-existing protocol or if no matching protocol at all is set, it returns error. -.SH DEFAULT + +# DEFAULT + HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 SMB and SMBS. -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(int argc, char **argv) { CURL *curl = curl_easy_init(); @@ -81,16 +81,14 @@ int main(int argc, char **argv) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.85.0. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_UNKNOWN_OPTION if the option is not implemented, CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled, CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_PROTOCOLS_STR (3), -.BR CURLINFO_SCHEME (3), -.BR CURLOPT_DEFAULT_PROTOCOL (3), -.BR CURLOPT_PROTOCOLS (3), -.BR CURLOPT_REDIR_PROTOCOLS (3) diff --git a/docs/libcurl/opts/CURLOPT_REFERER.3 b/docs/libcurl/opts/CURLOPT_REFERER.3 deleted file mode 100644 index 38d931b9f7c..00000000000 --- a/docs/libcurl/opts/CURLOPT_REFERER.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_REFERER 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_REFERER \- the HTTP referer header -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REFERER, char *where); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It is used to set the -Referer: header field in the HTTP request sent to the remote server. You can -set any custom header with \fICURLOPT_HTTPHEADER(3)\fP. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* tell it where we found the link to this place */ - curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/me.html"); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -If built with HTTP support -.SH RETURN VALUE -Returns CURLE_OK if HTTP support is enabled, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLINFO_REDIRECT_URL (3), -.BR CURLINFO_REFERER (3), -.BR CURLOPT_HTTPHEADER (3), -.BR CURLOPT_USERAGENT (3) diff --git a/docs/libcurl/opts/CURLOPT_REFERER.md b/docs/libcurl/opts/CURLOPT_REFERER.md new file mode 100644 index 00000000000..6af19cb01b7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_REFERER.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_REFERER +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_URL (3) + - CURLINFO_REFERER (3) + - CURLOPT_HTTPHEADER (3) + - CURLOPT_USERAGENT (3) +--- + +# NAME + +CURLOPT_REFERER - the HTTP referer header + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REFERER, char *where); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. It is used to set the +Referer: header field in the HTTP request sent to the remote server. You can +set any custom header with CURLOPT_HTTPHEADER(3). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* tell it where we found the link to this place */ + curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/me.html"); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +If built with HTTP support + +# RETURN VALUE + +Returns CURLE_OK if HTTP support is enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 deleted file mode 100644 index f7a21fedaca..00000000000 --- a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_REQUEST_TARGET 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_REQUEST_TARGET \- alternative target for this request -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REQUEST_TARGET, string); -.fi -.SH DESCRIPTION -Pass a char * to string which libcurl uses in the upcoming request instead of -the path as extracted from the URL. - -libcurl passes on the verbatim string in its request without any filter or -other safe guards. That includes white space and control characters. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/*"); - curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "OPTIONS"); - - /* issue an OPTIONS * request (no leading slash) */ - curl_easy_setopt(curl, CURLOPT_REQUEST_TARGET, "*"); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.55.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CUSTOMREQUEST (3), -.BR CURLOPT_HTTPGET (3), -.BR CURLOPT_PATH_AS_IS (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md new file mode 100644 index 00000000000..cfc15d7b47e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_REQUEST_TARGET +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CUSTOMREQUEST (3) + - CURLOPT_HTTPGET (3) + - CURLOPT_PATH_AS_IS (3) + - CURLOPT_URL (3) +--- + +# NAME + +CURLOPT_REQUEST_TARGET - alternative target for this request + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REQUEST_TARGET, string); +~~~ + +# DESCRIPTION + +Pass a char pointer to string which libcurl uses in the upcoming request +instead of the path as extracted from the URL. + +libcurl passes on the verbatim string in its request without any filter or +other safe guards. That includes white space and control characters. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/*"); + curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "OPTIONS"); + + /* issue an OPTIONS * request (no leading slash) */ + curl_easy_setopt(curl, CURLOPT_REQUEST_TARGET, "*"); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.55.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.3 b/docs/libcurl/opts/CURLOPT_RESOLVE.md similarity index 59% rename from docs/libcurl/opts/CURLOPT_RESOLVE.3 rename to docs/libcurl/opts/CURLOPT_RESOLVE.md index b0aa0e77812..8ae8f05569b 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVE.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.md @@ -1,48 +1,41 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RESOLVE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RESOLVE \- provide custom host name to IP address resolves -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RESOLVE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECT_TO (3) + - CURLOPT_DNS_CACHE_TIMEOUT (3) + - CURLOPT_IPRESOLVE (3) +--- + +# NAME + +CURLOPT_RESOLVE - provide custom host name to IP address resolves + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE, struct curl_slist *hosts); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a linked list of strings with host name resolve information to use for requests with this handle. The linked list should be a fully valid -list of \fBstruct curl_slist\fP structs properly filled in. Use -\fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP +list of **struct curl_slist** structs properly filled in. Use +curl_slist_append(3) to create the list and curl_slist_free_all(3) to clean up an entire list. Each resolve rule to add should be written using the format -.nf +~~~c [+]HOST:PORT:ADDRESS[,ADDRESS] -.fi +~~~ HOST is the name libcurl wants to resolve, PORT is the port number of the service where libcurl wants to connect to the HOST and ADDRESS is one or more @@ -62,23 +55,29 @@ If the DNS cache already has an entry for the given host+port pair, the new entry overrides the former one. An ADDRESS provided by this option is only used if not restricted by the -setting of \fICURLOPT_IPRESOLVE(3)\fP to a different IP version. +setting of CURLOPT_IPRESOLVE(3) to a different IP version. To remove names from the DNS cache again, to stop providing these fake resolves, include a string in the linked list that uses the format -.nf +~~~c -HOST:PORT -.fi +~~~ The entry to remove must be prefixed with a dash, and the host name and port number must exactly match what was added previously. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl; @@ -98,8 +97,10 @@ int main(void) curl_slist_free_all(host); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.21.3. Removal support added in 7.42.0. Support for providing the ADDRESS within [brackets] was added in 7.57.0. @@ -108,9 +109,7 @@ Support for providing multiple IP addresses per entry was added in 7.59.0. Support for adding non-permanent entries by using the "+" prefix was added in 7.75.0. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CONNECT_TO (3), -.BR CURLOPT_DNS_CACHE_TIMEOUT (3), -.BR CURLOPT_IPRESOLVE (3) diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 deleted file mode 100644 index 84bc081a67b..00000000000 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RESOLVER_START_DATA 3 "14 Feb 2018" libcurl libcurl -.SH NAME -CURLOPT_RESOLVER_START_DATA \- pointer passed to the resolver start callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVER_START_DATA, - void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP is be untouched by libcurl and passed as the third -argument in the resolver start callback set with -\fICURLOPT_RESOLVER_START_FUNCTION(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -static int resolver_start_cb(void *resolver_state, void *reserved, - void *userdata) -{ - (void)reserved; - printf("Received resolver_state=%p userdata=%p\\n", - resolver_state, userdata); - return 0; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb); - curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl); - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.59.0 -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_PREREQFUNCTION (3), -.BR CURLOPT_RESOLVER_START_FUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md new file mode 100644 index 00000000000..f34cf8bd68f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RESOLVER_START_DATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PREREQFUNCTION (3) + - CURLOPT_RESOLVER_START_FUNCTION (3) +--- + +# NAME + +CURLOPT_RESOLVER_START_DATA - pointer passed to the resolver start callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVER_START_DATA, + void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* is be untouched by libcurl and passed as the third +argument in the resolver start callback set with +CURLOPT_RESOLVER_START_FUNCTION(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +static int resolver_start_cb(void *resolver_state, void *reserved, + void *userdata) +{ + (void)reserved; + printf("Received resolver_state=%p userdata=%p\n", + resolver_state, userdata); + return 0; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb); + curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl); + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.59.0 + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 deleted file mode 100644 index bd2c1189f7f..00000000000 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 +++ /dev/null @@ -1,89 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RESOLVER_START_FUNCTION 3 "14 Feb 2018" libcurl libcurl -.SH NAME -CURLOPT_RESOLVER_START_FUNCTION \- callback called before a new name resolve is started -.SH SYNOPSIS -.nf -#include - -int resolver_start_cb(void *resolver_state, void *reserved, void *userdata); - -CURLcode curl_easy_setopt(CURL *handle, - CURLOPT_RESOLVER_START_FUNCTION, - resolver_start_cb); -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. - -This callback function gets called by libcurl every time before a new resolve -request is started. - -\fIresolver_state\fP points to a backend-specific resolver state. Currently -only the ares resolver backend has a resolver state. It can be used to set up -any desired option on the ares channel before it's used, for example setting up -socket callback options. - -\fIreserved\fP is reserved. - -\fIuserdata\fP is the user pointer set with the -\fICURLOPT_RESOLVER_START_DATA(3)\fP option. - -The callback must return 0 on success. Returning a non-zero value causes the -resolve to fail. -.SH DEFAULT -NULL (No callback) -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -static int start_cb(void *resolver_state, void *reserved, - void *userdata) -{ - (void)reserved; - printf("Received resolver_state=%p userdata=%p\\n", - resolver_state, userdata); - return 0; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, start_cb); - curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl); - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.59.0 -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_PREREQFUNCTION (3), -.BR CURLOPT_RESOLVER_START_DATA (3) diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md new file mode 100644 index 00000000000..3b5d500cd79 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md @@ -0,0 +1,88 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RESOLVER_START_FUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PREREQFUNCTION (3) + - CURLOPT_RESOLVER_START_DATA (3) +--- + +# NAME + +CURLOPT_RESOLVER_START_FUNCTION - callback called before a new name resolve is started + +# SYNOPSIS + +~~~c +#include + +int resolver_start_cb(void *resolver_state, void *reserved, void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, + CURLOPT_RESOLVER_START_FUNCTION, + resolver_start_cb); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl every time before a new resolve +request is started. + +*resolver_state* points to a backend-specific resolver state. Currently +only the ares resolver backend has a resolver state. It can be used to set up +any desired option on the ares channel before it's used, for example setting up +socket callback options. + +*reserved* is reserved. + +*userdata* is the user pointer set with the +CURLOPT_RESOLVER_START_DATA(3) option. + +The callback must return 0 on success. Returning a non-zero value causes the +resolve to fail. + +# DEFAULT + +NULL (No callback) + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +static int start_cb(void *resolver_state, void *reserved, + void *userdata) +{ + (void)reserved; + printf("Received resolver_state=%p userdata=%p\n", + resolver_state, userdata); + return 0; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, start_cb); + curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl); + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.59.0 + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 b/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 deleted file mode 100644 index 30c7fea9eed..00000000000 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RESUME_FROM 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RESUME_FROM \- offset to resume transfer from -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM, long from); -.fi -.SH DESCRIPTION -Pass a long as parameter. It contains the offset in number of bytes that you -want the transfer to start from. Set this option to 0 to make the transfer -start from the beginning (effectively disabling resume). For FTP, set this -option to -1 to make the transfer start from the end of the target file -(useful to continue an interrupted upload). - -When doing uploads with FTP, the resume position is where in the local/source -file libcurl should try to resume the upload from and it then appends the -source file to the remote target file. - -If you need to resume a transfer beyond the 2GB limit, use -\fICURLOPT_RESUME_FROM_LARGE(3)\fP instead. -.SH DEFAULT -0, not used -.SH PROTOCOLS -HTTP, FTP, SFTP, FILE -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - long size_of_file; - - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); - - /* resume upload at byte index 200 */ - curl_easy_setopt(curl, CURLOPT_RESUME_FROM, 200L); - - /* ask for upload */ - curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); - - /* set total data amount to expect */ - curl_easy_setopt(curl, CURLOPT_INFILESIZE, size_of_file); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_RESUME_FROM_LARGE (3), -.BR CURLOPT_RANGE (3), -.BR CURLOPT_INFILESIZE (3) diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM.md b/docs/libcurl/opts/CURLOPT_RESUME_FROM.md new file mode 100644 index 00000000000..c8de1ee6bd5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RESUME_FROM +Section: 3 +Source: libcurl +See-also: + - CURLOPT_INFILESIZE (3) + - CURLOPT_RANGE (3) + - CURLOPT_RESUME_FROM_LARGE (3) +--- + +# NAME + +CURLOPT_RESUME_FROM - offset to resume transfer from + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM, long from); +~~~ + +# DESCRIPTION + +Pass a long as parameter. It contains the offset in number of bytes that you +want the transfer to start from. Set this option to 0 to make the transfer +start from the beginning (effectively disabling resume). For FTP, set this +option to -1 to make the transfer start from the end of the target file +(useful to continue an interrupted upload). + +When doing uploads with FTP, the resume position is where in the local/source +file libcurl should try to resume the upload from and it then appends the +source file to the remote target file. + +If you need to resume a transfer beyond the 2GB limit, use +CURLOPT_RESUME_FROM_LARGE(3) instead. + +# DEFAULT + +0, not used + +# PROTOCOLS + +HTTP, FTP, SFTP, FILE + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + long size_of_file; + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); + + /* resume upload at byte index 200 */ + curl_easy_setopt(curl, CURLOPT_RESUME_FROM, 200L); + + /* ask for upload */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* set total data amount to expect */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE, size_of_file); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 deleted file mode 100644 index e5d91bb8973..00000000000 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RESUME_FROM_LARGE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RESUME_FROM_LARGE \- offset to resume transfer from -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM_LARGE, - curl_off_t from); -.SH DESCRIPTION -Pass a curl_off_t as parameter. It contains the offset in number of bytes that -you want the transfer to start from. Set this option to 0 to make the transfer -start from the beginning (effectively disabling resume). For FTP, set this -option to -1 to make the transfer start from the end of the target file -(useful to continue an interrupted upload). - -When doing uploads with FTP, the resume position is where in the local/source -file libcurl should try to resume the upload from and it appends the source -file to the remote target file. -.SH DEFAULT -0, not used -.SH PROTOCOLS -HTTP, FTP, SFTP, FILE -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_off_t resume_position; /* get it somehow */ - curl_off_t file_size; /* get it somehow as well */ - - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); - - /* resuming upload at this position, possibly beyond 2GB */ - curl_easy_setopt(curl, CURLOPT_RESUME_FROM_LARGE, resume_position); - - /* ask for upload */ - curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); - - /* set total data amount to expect */ - curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, file_size); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.11.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_INFILESIZE_LARGE (3), -.BR CURLOPT_RANGE (3), -.BR CURLOPT_RESUME_FROM (3) diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md new file mode 100644 index 00000000000..950a4f496d1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md @@ -0,0 +1,79 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RESUME_FROM_LARGE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_INFILESIZE_LARGE (3) + - CURLOPT_RANGE (3) + - CURLOPT_RESUME_FROM (3) +--- + +# NAME + +CURLOPT_RESUME_FROM_LARGE - offset to resume transfer from + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM_LARGE, + curl_off_t from); +~~~ + +# DESCRIPTION + +Pass a curl_off_t as parameter. It contains the offset in number of bytes that +you want the transfer to start from. Set this option to 0 to make the transfer +start from the beginning (effectively disabling resume). For FTP, set this +option to -1 to make the transfer start from the end of the target file +(useful to continue an interrupted upload). + +When doing uploads with FTP, the resume position is where in the local/source +file libcurl should try to resume the upload from and it appends the source +file to the remote target file. + +# DEFAULT + +0, not used + +# PROTOCOLS + +HTTP, FTP, SFTP, FILE + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_off_t resume_position; /* get it somehow */ + curl_off_t file_size; /* get it somehow as well */ + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); + + /* resuming upload at this position, possibly beyond 2GB */ + curl_easy_setopt(curl, CURLOPT_RESUME_FROM_LARGE, resume_position); + + /* ask for upload */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* set total data amount to expect */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, file_size); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.11.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 deleted file mode 100644 index 4faf8020aad..00000000000 --- a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 +++ /dev/null @@ -1,64 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RTSP_CLIENT_CSEQ 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RTSP_CLIENT_CSEQ \- RTSP client CSEQ number -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_CLIENT_CSEQ, long cseq); -.fi -.SH DESCRIPTION -Pass a long to set the CSEQ number to issue for the next RTSP request. Useful -if the application is resuming a previously broken connection. The CSEQ -increments from this new number henceforth. -.SH DEFAULT -0 -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); - curl_easy_setopt(curl, CURLOPT_RTSP_CLIENT_CSEQ, 1234L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_RTSP_CLIENT_CSEQ (3), -.BR CURLINFO_RTSP_SERVER_CSEQ (3), -.BR CURLOPT_RTSP_REQUEST (3), -.BR CURLOPT_RTSP_SERVER_CSEQ (3) diff --git a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md new file mode 100644 index 00000000000..6c83663dc67 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RTSP_CLIENT_CSEQ +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RTSP_CLIENT_CSEQ (3) + - CURLINFO_RTSP_SERVER_CSEQ (3) + - CURLOPT_RTSP_REQUEST (3) + - CURLOPT_RTSP_SERVER_CSEQ (3) +--- + +# NAME + +CURLOPT_RTSP_CLIENT_CSEQ - RTSP client CSEQ number + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_CLIENT_CSEQ, long cseq); +~~~ + +# DESCRIPTION + +Pass a long to set the CSEQ number to issue for the next RTSP request. Useful +if the application is resuming a previously broken connection. The CSEQ +increments from this new number henceforth. + +# DEFAULT + +0 + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_CLIENT_CSEQ, 1234L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 deleted file mode 100644 index d62cf1d18da..00000000000 --- a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 +++ /dev/null @@ -1,122 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RTSP_REQUEST 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RTSP_REQUEST \- RTSP request -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_REQUEST, long request); -.fi -.SH DESCRIPTION -Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP -enum values as a long in the \fIrequest\fP argument. Unless noted otherwise, -commands require the Session ID to be initialized. -.IP CURL_RTSPREQ_OPTIONS -Used to retrieve the available methods of the server. The application is -responsible for parsing and obeying the response. The session ID is not needed -for this method. -.IP CURL_RTSPREQ_DESCRIBE -Used to get the low level description of a stream. The application should note -what formats it understands in the \fI'Accept:'\fP header. Unless set -manually, libcurl automatically adds in \fI'Accept: application/sdp'\fP. -Time-condition headers are added to Describe requests if the -\fICURLOPT_TIMECONDITION(3)\fP option is used. \fB(The session ID is not -needed for this method)\fP -.IP CURL_RTSPREQ_ANNOUNCE -When sent by a client, this method changes the description of the session. For -example, if a client is using the server to record a meeting, the client can -use Announce to inform the server of all the meta-information about the -session. ANNOUNCE acts like an HTTP PUT or POST just like -\fICURL_RTSPREQ_SET_PARAMETER\fP -.IP CURL_RTSPREQ_SETUP -Setup is used to initialize the transport layer for the session. The -application must set the desired Transport options for a session by using the -\fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session -ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl extracts -and uses the session ID in the response to this request. The session ID is not -needed for this method. -.IP CURL_RTSPREQ_PLAY -Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to -modify the playback time (e.g. \fInpt=10-15\fP). -.IP CURL_RTSPREQ_PAUSE -Send a Pause command to the server. Use the \fICURLOPT_RANGE(3)\fP option with -a single value to indicate when the stream should be -halted. (e.g. \fInpt=25\fP) -.IP CURL_RTSPREQ_TEARDOWN -This command terminates an RTSP session. Simply closing a connection does not -terminate the RTSP session since it is valid to control an RTSP session over -different connections. -.IP CURL_RTSPREQ_GET_PARAMETER -Retrieve a parameter from the server. By default, libcurl adds a -\fIContent-Type: text/parameters\fP header on all non-empty requests unless a -custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see -\fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat -message (e.g. in the presence of a server-specified timeout) should send use -an empty GET_PARAMETER request. -.IP CURL_RTSPREQ_SET_PARAMETER -Set a parameter on the server. By default, libcurl uses a -\fIContent-Type: text/parameters\fP header unless a custom one is set. -The interaction with SET_PARAMETER is much like an HTTP PUT or POST. An -application may either use \fICURLOPT_UPLOAD(3)\fP with -\fICURLOPT_READDATA(3)\fP like a HTTP PUT, or it may use -\fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No chunked transfers are -allowed, so the application must set the \fICURLOPT_INFILESIZE(3)\fP in the -former and \fICURLOPT_POSTFIELDSIZE(3)\fP in the latter. Also, there is no use -of multi-part POSTs within RTSP. -.IP CURL_RTSPREQ_RECORD -Used to tell the server to record a session. Use the \fICURLOPT_RANGE(3)\fP -option to modify the record time. -.IP CURL_RTSPREQ_RECEIVE -This is a special request because it does not send any data to the server. The -application may call this function in order to receive interleaved RTP -data. It returns after processing one read buffer of data in order to give the -application a chance to run. -.SH DEFAULT -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); - /* ask for options! */ - curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_OPTIONS); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_RTSP_SESSION_ID (3), -.BR CURLOPT_RTSP_STREAM_URI (3) diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md new file mode 100644 index 00000000000..925a31782b9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md @@ -0,0 +1,140 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RTSP_REQUEST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_RTSP_SESSION_ID (3) + - CURLOPT_RTSP_STREAM_URI (3) +--- + +# NAME + +CURLOPT_RTSP_REQUEST - RTSP request + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_REQUEST, long request); +~~~ + +# DESCRIPTION + +Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP +enum values as a long in the *request* argument. Unless noted otherwise, +commands require the Session ID to be initialized. + +## CURL_RTSPREQ_OPTIONS + +Used to retrieve the available methods of the server. The application is +responsible for parsing and obeying the response. The session ID is not needed +for this method. + +## CURL_RTSPREQ_DESCRIBE + +Used to get the low level description of a stream. The application should note +what formats it understands in the *'Accept:'* header. Unless set manually, +libcurl automatically adds in *'Accept: application/sdp'*. Time-condition +headers are added to Describe requests if the CURLOPT_TIMECONDITION(3) +option is used. (The session ID is not needed for this method) + +## CURL_RTSPREQ_ANNOUNCE + +When sent by a client, this method changes the description of the session. For +example, if a client is using the server to record a meeting, the client can +use Announce to inform the server of all the meta-information about the +session. ANNOUNCE acts like an HTTP PUT or POST just like +*CURL_RTSPREQ_SET_PARAMETER* + +## CURL_RTSPREQ_SETUP + +Setup is used to initialize the transport layer for the session. The +application must set the desired Transport options for a session by using the +CURLOPT_RTSP_TRANSPORT(3) option prior to calling setup. If no session +ID is currently set with CURLOPT_RTSP_SESSION_ID(3), libcurl extracts +and uses the session ID in the response to this request. The session ID is not +needed for this method. + +## CURL_RTSPREQ_PLAY + +Send a Play command to the server. Use the CURLOPT_RANGE(3) option to +modify the playback time (e.g. *npt=10-15*). + +## CURL_RTSPREQ_PAUSE + +Send a Pause command to the server. Use the CURLOPT_RANGE(3) option with +a single value to indicate when the stream should be +halted. (e.g. *npt=25*) + +## CURL_RTSPREQ_TEARDOWN + +This command terminates an RTSP session. Simply closing a connection does not +terminate the RTSP session since it is valid to control an RTSP session over +different connections. + +## CURL_RTSPREQ_GET_PARAMETER + +Retrieve a parameter from the server. By default, libcurl adds a +*Content-Type: text/parameters* header on all non-empty requests unless a +custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see +*CURL_RTSPREQ_SET_PARAMETER*). Applications wishing to send a heartbeat +message (e.g. in the presence of a server-specified timeout) should send use +an empty GET_PARAMETER request. + +## CURL_RTSPREQ_SET_PARAMETER + +Set a parameter on the server. By default, libcurl uses a +*Content-Type: text/parameters* header unless a custom one is set. +The interaction with SET_PARAMETER is much like an HTTP PUT or POST. An +application may either use CURLOPT_UPLOAD(3) with +CURLOPT_READDATA(3) like a HTTP PUT, or it may use +CURLOPT_POSTFIELDS(3) like an HTTP POST. No chunked transfers are +allowed, so the application must set the CURLOPT_INFILESIZE(3) in the +former and CURLOPT_POSTFIELDSIZE(3) in the latter. Also, there is no use +of multi-part POSTs within RTSP. + +## CURL_RTSPREQ_RECORD + +Used to tell the server to record a session. Use the CURLOPT_RANGE(3) +option to modify the record time. + +## CURL_RTSPREQ_RECEIVE + +This is a special request because it does not send any data to the server. The +application may call this function in order to receive interleaved RTP +data. It returns after processing one read buffer of data in order to give the +application a chance to run. + +# DEFAULT + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + /* ask for options! */ + curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_OPTIONS); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 deleted file mode 100644 index 5c75bd1499a..00000000000 --- a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RTSP_SERVER_CSEQ 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RTSP_SERVER_CSEQ \- RTSP server CSEQ number -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SERVER_CSEQ, long cseq); -.fi -.SH DESCRIPTION -Pass a long to set the CSEQ number to expect for the next RTSP Server->Client -request. \fBNOTE\fP: this feature (listening for Server requests) is -unimplemented. -.SH DEFAULT -0 -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); - curl_easy_setopt(curl, CURLOPT_RTSP_SERVER_CSEQ, 1234L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLINFO_RTSP_SERVER_CSEQ (3), -.BR CURLOPT_RTSP_CLIENT_CSEQ (3), -.BR CURLOPT_RTSP_STREAM_URI (3) diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md new file mode 100644 index 00000000000..521084388aa --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RTSP_SERVER_CSEQ +Section: 3 +Source: libcurl +See-also: + - CURLINFO_RTSP_SERVER_CSEQ (3) + - CURLOPT_RTSP_CLIENT_CSEQ (3) + - CURLOPT_RTSP_STREAM_URI (3) +--- + +# NAME + +CURLOPT_RTSP_SERVER_CSEQ - RTSP server CSEQ number + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SERVER_CSEQ, long cseq); +~~~ + +# DESCRIPTION + +Pass a long to set the CSEQ number to expect for the next RTSP Server->Client +request. **NOTE**: this feature (listening for Server requests) is +unimplemented. + +# DEFAULT + +0 + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_SERVER_CSEQ, 1234L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 deleted file mode 100644 index acb8e36114e..00000000000 --- a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RTSP_SESSION_ID 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RTSP_SESSION_ID \- RTSP session ID -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SESSION_ID, char *id); -.fi -.SH DESCRIPTION -Pass a char * as a parameter to set the value of the current RTSP Session ID -for the handle. Useful for resuming an in-progress session. Once this value is -set to any non-NULL value, libcurl returns \fICURLE_RTSP_SESSION_ERROR\fP if -ID received from the server does not match. If unset (or set to NULL), libcurl -automatically sets the ID the first time the server sets it in a response. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - char *prev_id; /* saved from before somehow */ - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); - curl_easy_setopt(curl, CURLOPT_RTSP_SESSION_ID, prev_id); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_RTSP_REQUEST (3), -.BR CURLOPT_RTSP_STREAM_URI (3) diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md new file mode 100644 index 00000000000..8af7f7c5963 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RTSP_SESSION_ID +Section: 3 +Source: libcurl +See-also: + - CURLOPT_RTSP_REQUEST (3) + - CURLOPT_RTSP_STREAM_URI (3) +--- + +# NAME + +CURLOPT_RTSP_SESSION_ID - RTSP session ID + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SESSION_ID, char *id); +~~~ + +# DESCRIPTION + +Pass a char pointer as a parameter to set the value of the current RTSP +Session ID for the handle. Useful for resuming an in-progress session. Once +this value is set to any non-NULL value, libcurl returns +*CURLE_RTSP_SESSION_ERROR* if ID received from the server does not match. If +unset (or set to NULL), libcurl automatically sets the ID the first time the +server sets it in a response. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + char *prev_id; /* saved from before somehow */ + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_SESSION_ID, prev_id); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 deleted file mode 100644 index d2c7a49da64..00000000000 --- a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RTSP_STREAM_URI 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RTSP_STREAM_URI \- RTSP stream URI -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_STREAM_URI, char *URI); -.fi -.SH DESCRIPTION -Set the stream \fIURI\fP to operate on by passing a char * . For example, a -single session may be controlling \fIrtsp://foo/twister/audio\fP and -\fIrtsp://foo/twister/video\fP and the application can switch to the -appropriate stream using this option. If unset, libcurl defaults to operating -on generic server options by passing '*' in the place of the RTSP Stream -URI. This option is distinct from \fICURLOPT_URL(3)\fP. When working with -RTSP, the \fICURLOPT_RTSP_STREAM_URI(3)\fP indicates what URL to send to the -server in the request header while the \fICURLOPT_URL(3)\fP indicates where to -make the connection to. (e.g. the \fICURLOPT_URL(3)\fP for the above examples -might be set to \fIrtsp://foo/twister\fP - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -\&'*' -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); - curl_easy_setopt(curl, CURLOPT_RTSP_STREAM_URI, - "rtsp://foo.example.com/twister/video"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_RTSP_REQUEST (3), -.BR CURLOPT_RTSP_TRANSPORT (3) diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md new file mode 100644 index 00000000000..c1d50ad13c6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RTSP_STREAM_URI +Section: 3 +Source: libcurl +See-also: + - CURLOPT_RTSP_REQUEST (3) + - CURLOPT_RTSP_TRANSPORT (3) +--- + +# NAME + +CURLOPT_RTSP_STREAM_URI - RTSP stream URI + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_STREAM_URI, char *URI); +~~~ + +# DESCRIPTION + +Set the stream *URI* to operate on by passing a char * . For example, a single +session may be controlling *rtsp://foo/twister/audio* and +*rtsp://foo/twister/video* and the application can switch to the appropriate +stream using this option. If unset, libcurl defaults to operating on generic +server options by passing '*' in the place of the RTSP Stream URI. This option +is distinct from CURLOPT_URL(3). When working with RTSP, the +CURLOPT_RTSP_STREAM_URI(3) indicates what URL to send to the server in the +request header while the CURLOPT_URL(3) indicates where to make the +connection to. (e.g. the CURLOPT_URL(3) for the above examples might be set +to *rtsp://foo/twister* + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +&'*' + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_STREAM_URI, + "rtsp://foo.example.com/twister/video"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 deleted file mode 100644 index 9017f915482..00000000000 --- a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_RTSP_TRANSPORT 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_RTSP_TRANSPORT \- RTSP Transport: header -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_TRANSPORT, - char *transport); -.SH DESCRIPTION -Pass a char * to tell libcurl what to pass for the Transport: header for this -RTSP session. This is mainly a convenience method to avoid needing to set a -custom Transport: header for every SETUP request. The application must set a -Transport: header before issuing a SETUP request. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -RTSP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); - curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_SETUP); - curl_easy_setopt(curl, CURLOPT_RTSP_TRANSPORT, - "RTP/AVP;unicast;client_port=4588-4589"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.20.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_RTSP_REQUEST (3), -.BR CURLOPT_RTSP_SESSION_ID (3) diff --git a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md new file mode 100644 index 00000000000..b8083967dc0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_RTSP_TRANSPORT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_RTSP_REQUEST (3) + - CURLOPT_RTSP_SESSION_ID (3) +--- + +# NAME + +CURLOPT_RTSP_TRANSPORT - RTSP Transport: header + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_TRANSPORT, + char *transport); +~~~ + +# DESCRIPTION + +Pass a char pointer to tell libcurl what to pass for the Transport: header for +this RTSP session. This is mainly a convenience method to avoid needing to set +a custom Transport: header for every SETUP request. The application must set a +Transport: header before issuing a SETUP request. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +RTSP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); + curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_SETUP); + curl_easy_setopt(curl, CURLOPT_RTSP_TRANSPORT, + "RTP/AVP;unicast;client_port=4588-4589"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.20.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 deleted file mode 100644 index c06a665e2cb..00000000000 --- a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SASL_AUTHZID 3 "11 Sep 2019" libcurl libcurl -.SH NAME -CURLOPT_SASL_AUTHZID \- authorization identity (identity to act as) -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_AUTHZID, char *authzid); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should be pointing to the null-terminated -authorization identity (\fIauthzid\fP) for the transfer. Only applicable to -the PLAIN SASL authentication mechanism where it is optional. - -When not specified only the authentication identity (\fIauthcid\fP) as -specified by the username is sent to the server, along with the password. The -server derives a \fIauthzid\fP from the \fIauthcid\fP when not provided, which -it then uses internally. - -When the \fIauthzid\fP is specified, the use of which is server dependent, it -can be used to access another user's inbox, that the user has been granted -access to, or a shared mailbox for example. -.SH DEFAULT -blank -.SH PROTOCOLS -IMAP, LDAP, POP3 and SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "imap://example.com/"); - curl_easy_setopt(curl, CURLOPT_USERNAME, "Kurt"); - curl_easy_setopt(curl, CURLOPT_PASSWORD, "xipj3plmq"); - curl_easy_setopt(curl, CURLOPT_SASL_AUTHZID, "Ursel"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.66.0. Support for OpenLDAP added in 7.82.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_PASSWORD (3), -.BR CURLOPT_USERNAME (3), -.BR CURLOPT_USERPWD (3) diff --git a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md new file mode 100644 index 00000000000..5ff67c6ab45 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SASL_AUTHZID +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PASSWORD (3) + - CURLOPT_USERNAME (3) + - CURLOPT_USERPWD (3) +--- + +# NAME + +CURLOPT_SASL_AUTHZID - authorization identity (identity to act as) + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_AUTHZID, char *authzid); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should be pointing to the +null-terminated authorization identity (*authzid*) for the transfer. Only +applicable to the PLAIN SASL authentication mechanism where it is optional. + +When not specified only the authentication identity (*authcid*) as +specified by the username is sent to the server, along with the password. The +server derives a *authzid* from the *authcid* when not provided, which +it then uses internally. + +When the *authzid* is specified, the use of which is server dependent, it +can be used to access another user's inbox, that the user has been granted +access to, or a shared mailbox for example. + +# DEFAULT + +blank + +# PROTOCOLS + +IMAP, LDAP, POP3 and SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "imap://example.com/"); + curl_easy_setopt(curl, CURLOPT_USERNAME, "Kurt"); + curl_easy_setopt(curl, CURLOPT_PASSWORD, "xipj3plmq"); + curl_easy_setopt(curl, CURLOPT_SASL_AUTHZID, "Ursel"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.66.0. Support for OpenLDAP added in 7.82.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SASL_IR.3 b/docs/libcurl/opts/CURLOPT_SASL_IR.3 deleted file mode 100644 index 50ec074a055..00000000000 --- a/docs/libcurl/opts/CURLOPT_SASL_IR.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SASL_IR 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SASL_IR \- send initial response in first packet -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_IR, long enable); -.fi -.SH DESCRIPTION -Pass a long. If the value is 1, curl sends the initial response to the server -in the first authentication packet in order to reduce the number of ping pong -requests. Only applicable to the following supporting SASL authentication -mechanisms: - -* Login -* Plain -* GSSAPI -* NTLM -* OAuth 2.0 - -Note: Whilst IMAP supports this option there is no need to explicitly set it, -as libcurl can determine the feature itself when the server supports the -SASL-IR CAPABILITY. -.SH DEFAULT -0 -.SH PROTOCOLS -IMAP, POP3 and SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); - curl_easy_setopt(curl, CURLOPT_SASL_IR, 1L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.31.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_MAIL_AUTH (3), -.BR CURLOPT_MAIL_FROM (3), -.BR CURLOPT_SASL_AUTHZID (3) diff --git a/docs/libcurl/opts/CURLOPT_SASL_IR.md b/docs/libcurl/opts/CURLOPT_SASL_IR.md new file mode 100644 index 00000000000..204734d01e4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SASL_IR.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SASL_IR +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAIL_AUTH (3) + - CURLOPT_MAIL_FROM (3) + - CURLOPT_SASL_AUTHZID (3) +--- + +# NAME + +CURLOPT_SASL_IR - send initial response in first packet + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_IR, long enable); +~~~ + +# DESCRIPTION + +Pass a long. If the value is 1, curl sends the initial response to the server +in the first authentication packet in order to reduce the number of ping pong +requests. Only applicable to the following supporting SASL authentication +mechanisms: + +* Login +* Plain +* GSSAPI +* NTLM +* OAuth 2.0 + +Note: Whilst IMAP supports this option there is no need to explicitly set it, +as libcurl can determine the feature itself when the server supports the +SASL-IR CAPABILITY. + +# DEFAULT + +0 + +# PROTOCOLS + +IMAP, POP3 and SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); + curl_easy_setopt(curl, CURLOPT_SASL_IR, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.31.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.3 b/docs/libcurl/opts/CURLOPT_SEEKDATA.3 deleted file mode 100644 index eed02af1960..00000000000 --- a/docs/libcurl/opts/CURLOPT_SEEKDATA.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SEEKDATA 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SEEKDATA \- pointer passed to the seek callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, void *pointer); -.fi -.SH DESCRIPTION -Data \fIpointer\fP to pass to the seek callback function. If you use the -\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you get as input. -.SH DEFAULT -If you do not set this, NULL is passed to the callback. -.SH PROTOCOLS -HTTP, FTP, SFTP -.SH EXAMPLE -.nf -#include /* for lseek() */ - -struct data { - int our_fd; -}; - -static int seek_cb(void *clientp, curl_off_t offset, int origin) -{ - struct data *d = (struct data *)clientp; - lseek(d->our_fd, offset, origin); - return CURL_SEEKFUNC_OK; -} - -int main(void) -{ - struct data seek_data; - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, seek_cb); - curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data); - } -} -.fi -.SH AVAILABILITY -Added in 7.18.0 -.SH RETURN VALUE -.SH "SEE ALSO" -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_IOCTLFUNCTION (3), -.BR CURLOPT_SEEKFUNCTION (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.md b/docs/libcurl/opts/CURLOPT_SEEKDATA.md new file mode 100644 index 00000000000..9392c2366b6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SEEKDATA.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SEEKDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_IOCTLFUNCTION (3) + - CURLOPT_SEEKFUNCTION (3) + - CURLOPT_STDERR (3) +--- + +# NAME + +CURLOPT_SEEKDATA - pointer passed to the seek callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, void *pointer); +~~~ + +# DESCRIPTION + +Data *pointer* to pass to the seek callback function. If you use the +CURLOPT_SEEKFUNCTION(3) option, this is the pointer you get as input. + +# DEFAULT + +If you do not set this, NULL is passed to the callback. + +# PROTOCOLS + +HTTP, FTP, SFTP + +# EXAMPLE + +~~~c +#include /* for lseek() */ + +struct data { + int our_fd; +}; + +static int seek_cb(void *clientp, curl_off_t offset, int origin) +{ + struct data *d = (struct data *)clientp; + lseek(d->our_fd, offset, origin); + return CURL_SEEKFUNC_OK; +} + +int main(void) +{ + struct data seek_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, seek_cb); + curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data); + } +} +~~~ + +# AVAILABILITY + +Added in 7.18.0 + +# RETURN VALUE + diff --git a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md similarity index 51% rename from docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md index 649eb2ae291..102bdcfc721 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md @@ -1,32 +1,23 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SEEKFUNCTION 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SEEKFUNCTION \- user callback for seeking in input stream -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SEEKFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_IOCTLFUNCTION (3) + - CURLOPT_SEEKDATA (3) + - CURLOPT_STDERR (3) +--- + +# NAME + +CURLOPT_SEEKFUNCTION - user callback for seeking in input stream + +# SYNOPSIS + +~~~c #include /* These are the return codes for the seek callbacks */ @@ -38,7 +29,10 @@ CURLOPT_SEEKFUNCTION \- user callback for seeking in input stream int seek_callback(void *clientp, curl_off_t offset, int origin); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. @@ -50,26 +44,32 @@ been sent to the server and needs to be sent again. This may happen when doing an HTTP PUT or POST with a multi-pass authentication method, or when an existing HTTP connection is reused too late and the server closes the connection. The function shall work like fseek(3) or lseek(3) and it gets -SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, although libcurl +SEEK_SET, SEEK_CUR or SEEK_END as argument for *origin*, although libcurl currently only passes SEEK_SET. -\fIclientp\fP is the pointer you set with \fICURLOPT_SEEKDATA(3)\fP. +*clientp* is the pointer you set with CURLOPT_SEEKDATA(3). -The callback function must return \fICURL_SEEKFUNC_OK\fP on success, -\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or -\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl +The callback function must return *CURL_SEEKFUNC_OK* on success, +*CURL_SEEKFUNC_FAIL* to cause the upload operation to fail or +*CURL_SEEKFUNC_CANTSEEK* to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar. If you forward the input arguments directly to fseek(3) or lseek(3), note that -the data type for \fIoffset\fP is not the same as defined for curl_off_t on +the data type for *offset* is not the same as defined for curl_off_t on many systems! -.SH DEFAULT + +# DEFAULT + By default, this is NULL and unused. -.SH PROTOCOLS + +# PROTOCOLS + HTTP, FTP, SFTP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c #include /* for lseek */ struct data { @@ -91,13 +91,12 @@ int main(void) curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.18.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_IOCTLFUNCTION (3), -.BR CURLOPT_SEEKDATA (3), -.BR CURLOPT_STDERR (3) diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 deleted file mode 100644 index 72b2a6264a6..00000000000 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SERVER_RESPONSE_TIMEOUT 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SERVER_RESPONSE_TIMEOUT \- time allowed to wait for server response -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT, - long timeout); -.fi -.SH DESCRIPTION -Pass a long. Causes libcurl to set a \fItimeout\fP period (in seconds) on the -amount of time that the server is allowed to take in order to send a response -message for a command before the session is considered dead. While libcurl is -waiting for a response, this value overrides \fICURLOPT_TIMEOUT(3)\fP. It is -recommended that if used in conjunction with \fICURLOPT_TIMEOUT(3)\fP, you set -\fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP to a value smaller than -\fICURLOPT_TIMEOUT(3)\fP. - -This option was formerly known as CURLOPT_FTP_RESPONSE_TIMEOUT. -.SH DEFAULT -None -.SH PROTOCOLS -FTP, IMAP, POP3, SMTP, and SSH -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); - /* wait no more than 23 seconds */ - curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT, 23L); - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.10.8. Used under this name since 7.20.0 - -Support for SSH is predicated on a new enough (1.11.0) version of libssh2 -being available when compiling libcurl. -.SH RETURN VALUE -Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns -CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when -converted to milliseconds is too large. -.SH "SEE ALSO" -.BR CURLOPT_CONNECTTIMEOUT (3), -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md new file mode 100644 index 00000000000..5385d521ef4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SERVER_RESPONSE_TIMEOUT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT (3) + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_SERVER_RESPONSE_TIMEOUT - time allowed to wait for server response + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT, + long timeout); +~~~ + +# DESCRIPTION + +Pass a long. Causes libcurl to set a *timeout* period (in seconds) on the +amount of time that the server is allowed to take in order to send a response +message for a command before the session is considered dead. While libcurl is +waiting for a response, this value overrides CURLOPT_TIMEOUT(3). It is +recommended that if used in conjunction with CURLOPT_TIMEOUT(3), you set +CURLOPT_SERVER_RESPONSE_TIMEOUT(3) to a value smaller than +CURLOPT_TIMEOUT(3). + +This option was formerly known as CURLOPT_FTP_RESPONSE_TIMEOUT. + +# DEFAULT + +None + +# PROTOCOLS + +FTP, IMAP, POP3, SMTP, and SSH + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); + /* wait no more than 23 seconds */ + curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT, 23L); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.10.8. Used under this name since 7.20.0 + +Support for SSH is predicated on a new enough (1.11.0) version of libssh2 +being available when compiling libcurl. + +# RETURN VALUE + +Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns +CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when +converted to milliseconds is too large. diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 deleted file mode 100644 index 08239b74987..00000000000 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SERVER_RESPONSE_TIMEOUT_MS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SERVER_RESPONSE_TIMEOUT_MS \- time allowed to wait for server response -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, - long timeout); -.fi -.SH DESCRIPTION -Pass a long. Causes libcurl to set a \fItimeout\fP period (in milliseconds) -on the amount of time that the server is allowed to take in order to send a -response message for a command before the session is considered dead. While -libcurl is waiting for a response, this value overrides -\fICURLOPT_TIMEOUT(3)\fP. It is recommended that if used in conjunction with -\fICURLOPT_TIMEOUT(3)\fP, you set \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP -to a value smaller than \fICURLOPT_TIMEOUT(3)\fP. - -The maximum accepted value is 2147483648. - -This is the millisecond version of \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP. -.SH DEFAULT -None -.SH PROTOCOLS -FTP, IMAP, POP3, SMTP, and SSH -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); - /* wait no more than 237 milliseconds */ - curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, 237L); - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 8.6.0. -.SH RETURN VALUE -Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns -CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when -converted to milliseconds is too large. -.SH "SEE ALSO" -.BR CURLOPT_CONNECTTIMEOUT (3), -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md new file mode 100644 index 00000000000..a7d9c913785 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md @@ -0,0 +1,74 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SERVER_RESPONSE_TIMEOUT_MS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT (3) + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_SERVER_RESPONSE_TIMEOUT_MS - time allowed to wait for server response + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, + long timeout); +~~~ + +# DESCRIPTION + +Pass a long. Causes libcurl to set a *timeout* period (in milliseconds) on the +amount of time that the server is allowed to take in order to send a response +message for a command before the session is considered dead. While libcurl is +waiting for a response, this value overrides CURLOPT_TIMEOUT(3). It is +recommended that if used in conjunction with CURLOPT_TIMEOUT(3), you set +CURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3) to a value smaller than +CURLOPT_TIMEOUT(3). + +The maximum accepted value is 2147483648. + +This is the millisecond version of CURLOPT_SERVER_RESPONSE_TIMEOUT(3). + +# DEFAULT + +None + +# PROTOCOLS + +FTP, IMAP, POP3, SMTP, and SSH + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); + /* wait no more than 237 milliseconds */ + curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, 237L); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 8.6.0. + +# RETURN VALUE + +Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns +CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when +converted to milliseconds is too large. diff --git a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 deleted file mode 100644 index 02d18494d95..00000000000 --- a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SERVICE_NAME 3 "17 Jun 2015" libcurl libcurl -.SH NAME -CURLOPT_SERVICE_NAME \- authentication service name -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVICE_NAME, char *name); -.fi -.SH DESCRIPTION -Pass a char * as parameter to a string holding the \fIname\fP of the service -for DIGEST-MD5, SPNEGO and Kerberos 5 authentication mechanisms. The default -service names are "ftp", "HTTP", "imap", "ldap", "pop" and "smtp". This option -allows you to change them. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -See above -.SH PROTOCOLS -HTTP, FTP, IMAP, LDAP, POP3 and SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode ret; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SERVICE_NAME, "custom"); - ret = curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.43.0 for HTTP, 7.49.0 for FTP, IMAP, POP3 and SMTP, -7.82.0 for OpenLDAP. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXY_SERVICE_NAME (3), -.BR CURLOPT_PROXYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md new file mode 100644 index 00000000000..0e13ca712ad --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SERVICE_NAME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_PROXYTYPE (3) + - CURLOPT_PROXY_SERVICE_NAME (3) +--- + +# NAME + +CURLOPT_SERVICE_NAME - authentication service name + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVICE_NAME, char *name); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter to a string holding the *name* of the service +for DIGEST-MD5, SPNEGO and Kerberos 5 authentication mechanisms. The default +service names are "ftp", "HTTP", "imap", "ldap", "pop" and "smtp". This option +allows you to change them. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +See above + +# PROTOCOLS + +HTTP, FTP, IMAP, LDAP, POP3 and SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode ret; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SERVICE_NAME, "custom"); + ret = curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.43.0 for HTTP, 7.49.0 for FTP, IMAP, POP3 and SMTP, +7.82.0 for OpenLDAP. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SHARE.3 b/docs/libcurl/opts/CURLOPT_SHARE.3 deleted file mode 100644 index 22a662ac607..00000000000 --- a/docs/libcurl/opts/CURLOPT_SHARE.3 +++ /dev/null @@ -1,90 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SHARE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SHARE \- share handle to use -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SHARE, CURLSH *share); -.fi -.SH DESCRIPTION -Pass a \fIshare\fP handle as a parameter. The share handle must have been -created by a previous call to \fIcurl_share_init(3)\fP. Setting this option, -makes this curl handle use the data from the shared handle instead of keeping -the data to itself. This enables several curl handles to share data. If the -curl handles are used simultaneously in multiple threads, you \fBMUST\fP use -the locking methods in the share handle. See \fIcurl_share_setopt(3)\fP for -details. - -If you add a share that is set to share cookies, your easy handle uses that -cookie cache and get the cookie engine enabled. If you stop sharing an object -that was using cookies (or change to another object that does not share -cookies), the easy handle gets its cookie engine disabled. - -Data that the share object is not set to share is dealt with the usual way, as -if no share was used. - -Set this option to NULL again to stop using that share object. -.SH DEFAULT -NULL -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - CURL *curl2 = curl_easy_init(); /* a second handle */ - if(curl) { - CURLcode res; - CURLSH *shobject = curl_share_init(); - curl_share_setopt(shobject, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE); - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); - curl_easy_setopt(curl, CURLOPT_SHARE, shobject); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - - /* the second handle shares cookies from the first */ - curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/second"); - curl_easy_setopt(curl2, CURLOPT_COOKIEFILE, ""); - curl_easy_setopt(curl2, CURLOPT_SHARE, shobject); - res = curl_easy_perform(curl2); - curl_easy_cleanup(curl2); - - curl_share_cleanup(shobject); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_COOKIE (3), -.BR CURLSHOPT_SHARE (3) diff --git a/docs/libcurl/opts/CURLOPT_SHARE.md b/docs/libcurl/opts/CURLOPT_SHARE.md new file mode 100644 index 00000000000..3c0e7d2595b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SHARE.md @@ -0,0 +1,88 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SHARE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_COOKIE (3) + - CURLSHOPT_SHARE (3) +--- + +# NAME + +CURLOPT_SHARE - share handle to use + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SHARE, CURLSH *share); +~~~ + +# DESCRIPTION + +Pass a *share* handle as a parameter. The share handle must have been +created by a previous call to curl_share_init(3). Setting this option, +makes this curl handle use the data from the shared handle instead of keeping +the data to itself. This enables several curl handles to share data. If the +curl handles are used simultaneously in multiple threads, you **MUST** use +the locking methods in the share handle. See curl_share_setopt(3) for +details. + +If you add a share that is set to share cookies, your easy handle uses that +cookie cache and get the cookie engine enabled. If you stop sharing an object +that was using cookies (or change to another object that does not share +cookies), the easy handle gets its cookie engine disabled. + +Data that the share object is not set to share is dealt with the usual way, as +if no share was used. + +Set this option to NULL again to stop using that share object. + +# DEFAULT + +NULL + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); /* a second handle */ + if(curl) { + CURLcode res; + CURLSH *shobject = curl_share_init(); + curl_share_setopt(shobject, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); + curl_easy_setopt(curl, CURLOPT_SHARE, shobject); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + + /* the second handle shares cookies from the first */ + curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/second"); + curl_easy_setopt(curl2, CURLOPT_COOKIEFILE, ""); + curl_easy_setopt(curl2, CURLOPT_SHARE, shobject); + res = curl_easy_perform(curl2); + curl_easy_cleanup(curl2); + + curl_share_cleanup(shobject); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 deleted file mode 100644 index f671aa9895a..00000000000 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SOCKOPTDATA 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SOCKOPTDATA \- pointer to pass to sockopt callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP that is untouched by libcurl and passed as the first -argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP. -.SH DEFAULT -The default value of this parameter is NULL. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -static int sockopt_callback(void *clientp, curl_socket_t curlfd, - curlsocktype purpose) -{ - int val = *(int *)clientp; - setsockopt((int)curlfd, SOL_SOCKET, SO_RCVBUF, - (const char *)&val, sizeof(val)); - return CURL_SOCKOPT_OK; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - int recvbuffersize = 256 * 1024; - - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - - /* call this function to set options for the socket */ - curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); - curl_easy_setopt(curl, CURLOPT_SOCKOPTDATA, &recvbuffersize); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.16.0 -.SH RETURN VALUE -Returns \fICURLE_OK\fP if the option is supported, and \fICURLE_UNKNOWN_OPTION\fP if not. -.SH "SEE ALSO" -.BR CURLOPT_OPENSOCKETFUNCTION (3), -.BR CURLOPT_SOCKOPTFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md new file mode 100644 index 00000000000..f44bf532d9a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SOCKOPTDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_OPENSOCKETFUNCTION (3) + - CURLOPT_SOCKOPTFUNCTION (3) +--- + +# NAME + +CURLOPT_SOCKOPTDATA - pointer to pass to sockopt callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTDATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* that is untouched by libcurl and passed as the first +argument in the sockopt callback set with CURLOPT_SOCKOPTFUNCTION(3). + +# DEFAULT + +The default value of this parameter is NULL. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +static int sockopt_callback(void *clientp, curl_socket_t curlfd, + curlsocktype purpose) +{ + int val = *(int *)clientp; + setsockopt((int)curlfd, SOL_SOCKET, SO_RCVBUF, + (const char *)&val, sizeof(val)); + return CURL_SOCKOPT_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + int recvbuffersize = 256 * 1024; + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + + /* call this function to set options for the socket */ + curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); + curl_easy_setopt(curl, CURLOPT_SOCKOPTDATA, &recvbuffersize); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.16.0 + +# RETURN VALUE + +Returns *CURLE_OK* if the option is supported, and *CURLE_UNKNOWN_OPTION* if not. diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md similarity index 54% rename from docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md index 269490f85e3..f5de3168585 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md @@ -1,32 +1,22 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SOCKOPTFUNCTION 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SOCKOPTFUNCTION \- callback for setting socket options -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SOCKOPTFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_OPENSOCKETFUNCTION (3) + - CURLOPT_SEEKFUNCTION (3) + - CURLOPT_SOCKOPTDATA (3) +--- + +# NAME + +CURLOPT_SOCKOPTFUNCTION - callback for setting socket options + +# SYNOPSIS + +~~~c #include typedef enum { @@ -45,41 +35,50 @@ int sockopt_callback(void *clientp, curlsocktype purpose); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. When set, this callback function gets called by libcurl when the socket has been created, but before the connect call to allow applications to change -specific socket options. The callback's \fIpurpose\fP argument identifies the +specific socket options. The callback's *purpose* argument identifies the exact purpose for this particular socket: -\fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0 -\fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV +*CURLSOCKTYPE_IPCXN* for actively created connections or since 7.28.0 +*CURLSOCKTYPE_ACCEPT* for FTP when the connection was setup with PORT/EPSV (in earlier versions these sockets were not passed to this callback). Future versions of libcurl may support more purposes. libcurl passes the newly -created socket descriptor to the callback in the \fIcurlfd\fP parameter so +created socket descriptor to the callback in the *curlfd* parameter so additional setsockopt() calls can be done at the user's discretion. -The \fIclientp\fP pointer contains whatever user-defined value set using the -\fICURLOPT_SOCKOPTDATA(3)\fP function. +The *clientp* pointer contains whatever user-defined value set using the +CURLOPT_SOCKOPTDATA(3) function. -Return \fICURL_SOCKOPT_OK\fP from the callback on success. Return -\fICURL_SOCKOPT_ERROR\fP from the callback function to signal an unrecoverable +Return *CURL_SOCKOPT_OK* from the callback on success. Return +*CURL_SOCKOPT_ERROR* from the callback function to signal an unrecoverable error to the library and it closes the socket and returns -\fICURLE_COULDNT_CONNECT\fP. Alternatively, the callback function can return -\fICURL_SOCKOPT_ALREADY_CONNECTED\fP, to tell libcurl that the socket is +*CURLE_COULDNT_CONNECT*. Alternatively, the callback function can return +*CURL_SOCKOPT_ALREADY_CONNECTED*, to tell libcurl that the socket is already connected and then libcurl does no attempt to connect. This allows an application to pass in an already connected socket with -\fICURLOPT_OPENSOCKETFUNCTION(3)\fP and then have this function make libcurl +CURLOPT_OPENSOCKETFUNCTION(3) and then have this function make libcurl not attempt to connect (again). -.SH DEFAULT + +# DEFAULT + By default, this callback is NULL and unused. -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c /* make libcurl use the already established socket 'sockfd' */ static curl_socket_t opensocket(void *clientp, @@ -121,13 +120,13 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY -Added in 7.16.0. The \fICURL_SOCKOPT_ALREADY_CONNECTED\fP return code was +~~~ + +# AVAILABILITY + +Added in 7.16.0. The *CURL_SOCKOPT_ALREADY_CONNECTED* return code was added in 7.21.5. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_OPENSOCKETFUNCTION (3), -.BR CURLOPT_SEEKFUNCTION (3), -.BR CURLOPT_SOCKOPTDATA (3) diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 deleted file mode 100644 index d2276cffcfd..00000000000 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SOCKS5_AUTH 3 "27 April 2017" libcurl libcurl -.SH NAME -CURLOPT_SOCKS5_AUTH \- methods for SOCKS5 proxy authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_AUTH, long bitmask); -.fi -.SH DESCRIPTION -Pass a long as parameter, which is set to a bitmask, to tell libcurl which -authentication method(s) are allowed for SOCKS5 proxy authentication. The only -supported flags are \fICURLAUTH_BASIC\fP, which allows username/password -authentication, \fICURLAUTH_GSSAPI\fP, which allows GSS-API authentication, and -\fICURLAUTH_NONE\fP, which allows no authentication. Set the actual user name -and password with the \fICURLOPT_PROXYUSERPWD(3)\fP option. -.SH DEFAULT -CURLAUTH_BASIC|CURLAUTH_GSSAPI -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* request to use a SOCKS5 proxy */ - curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://user:pass@myproxy.com"); - - /* enable username/password authentication only */ - curl_easy_setopt(curl, CURLOPT_SOCKS5_AUTH, (long)CURLAUTH_BASIC); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.55.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_NOT_BUILT_IN if the bitmask contains unsupported flags. -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md new file mode 100644 index 00000000000..457ef99401a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SOCKS5_AUTH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_PROXYTYPE (3) +--- + +# NAME + +CURLOPT_SOCKS5_AUTH - methods for SOCKS5 proxy authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_AUTH, long bitmask); +~~~ + +# DESCRIPTION + +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +authentication method(s) are allowed for SOCKS5 proxy authentication. The only +supported flags are *CURLAUTH_BASIC*, which allows username/password +authentication, *CURLAUTH_GSSAPI*, which allows GSS-API authentication, and +*CURLAUTH_NONE*, which allows no authentication. Set the actual user name and +password with the CURLOPT_PROXYUSERPWD(3) option. + +# DEFAULT + +CURLAUTH_BASIC|CURLAUTH_GSSAPI + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* request to use a SOCKS5 proxy */ + curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://user:pass@myproxy.com"); + + /* enable username/password authentication only */ + curl_easy_setopt(curl, CURLOPT_SOCKS5_AUTH, (long)CURLAUTH_BASIC); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.55.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_NOT_BUILT_IN if the bitmask contains unsupported flags. diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 deleted file mode 100644 index 2388a16860f..00000000000 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SOCKS5_GSSAPI_NEC 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SOCKS5_GSSAPI_NEC \- SOCKS proxy GSSAPI negotiation protection -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_NEC, long nec); -.fi -.SH DESCRIPTION -Pass a long set to 1 to enable or 0 to disable. As part of the GSSAPI -negotiation a protection mode is negotiated. The RFC 1961 says in section -4.3/4.4 it should be protected, but the NEC reference implementation does not. -If enabled, this option allows the unprotected exchange of the protection mode -negotiation. -.SH DEFAULT -? -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy"); - curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_NEC, 1L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SOCKS5_GSSAPI_SERVICE (3), -.BR CURLOPT_PROXY (3) diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md new file mode 100644 index 00000000000..08a1ced6a42 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md @@ -0,0 +1,63 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SOCKS5_GSSAPI_NEC +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_SOCKS5_GSSAPI_SERVICE (3) +--- + +# NAME + +CURLOPT_SOCKS5_GSSAPI_NEC - SOCKS proxy GSSAPI negotiation protection + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_NEC, long nec); +~~~ + +# DESCRIPTION + +Pass a long set to 1 to enable or 0 to disable. As part of the GSSAPI +negotiation a protection mode is negotiated. The RFC 1961 says in section +4.3/4.4 it should be protected, but the NEC reference implementation does not. +If enabled, this option allows the unprotected exchange of the protection mode +negotiation. + +# DEFAULT + +? + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy"); + curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_NEC, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 deleted file mode 100644 index c5b32ec2ab8..00000000000 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SOCKS5_GSSAPI_SERVICE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SOCKS5_GSSAPI_SERVICE \- SOCKS5 proxy authentication service name -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_SERVICE, - char *name); -.fi -.SH DESCRIPTION -Deprecated since 7.49.0. Use \fICURLOPT_PROXY_SERVICE_NAME(3)\fP instead. - -Pass a \fBchar *\fP as parameter to a string holding the \fIname\fP of the -service. The default service name for a SOCKS5 server is \fI"rcmd"\fP. This -option allows you to change it. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -See above -.SH PROTOCOLS -All network protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy"); - curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_SERVICE, "rcmd-special"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.4, deprecated in 7.49.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY (3), -.BR CURLOPT_PROXYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md new file mode 100644 index 00000000000..47f6e28db88 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SOCKS5_GSSAPI_SERVICE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY (3) + - CURLOPT_PROXYTYPE (3) +--- + +# NAME + +CURLOPT_SOCKS5_GSSAPI_SERVICE - SOCKS5 proxy authentication service name + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_SERVICE, + char *name); +~~~ + +# DESCRIPTION + +Deprecated since 7.49.0. Use CURLOPT_PROXY_SERVICE_NAME(3) instead. + +Pass a char pointer as parameter to a string holding the *name* of the +service. The default service name for a SOCKS5 server is *rcmd*. This option +allows you to change it. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +See above + +# PROTOCOLS + +All network protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy"); + curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_SERVICE, "rcmd-special"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.4, deprecated in 7.49.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 deleted file mode 100644 index a6c16c84615..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_AUTH_TYPES 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSH_AUTH_TYPES \- auth types for SFTP and SCP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_AUTH_TYPES, long bitmask); -.fi -.SH DESCRIPTION -Pass a long set to a bitmask consisting of one or more of -CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, -CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT. - -Set \fICURLSSH_AUTH_ANY\fP to let libcurl pick a suitable one. Currently -CURLSSH_AUTH_HOST has no effect. If CURLSSH_AUTH_AGENT is used, libcurl -attempts to connect to ssh-agent or pageant and let the agent attempt the -authentication. -.SH DEFAULT -CURLSSH_AUTH_ANY (all available) -.SH PROTOCOLS -SFTP and SCP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); - curl_easy_setopt(curl, CURLOPT_SSH_AUTH_TYPES, - CURLSSH_AUTH_PUBLICKEY | CURLSSH_AUTH_KEYBOARD); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -CURLSSH_AUTH_HOST was added in 7.16.1, CURLSSH_AUTH_AGENT was added in 7.28.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3), -.BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3), -.BR CURLOPT_SSH_PUBLIC_KEYFILE (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md new file mode 100644 index 00000000000..205e94d1935 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_AUTH_TYPES +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3) + - CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3) + - CURLOPT_SSH_PUBLIC_KEYFILE (3) +--- + +# NAME + +CURLOPT_SSH_AUTH_TYPES - auth types for SFTP and SCP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_AUTH_TYPES, long bitmask); +~~~ + +# DESCRIPTION + +Pass a long set to a bitmask consisting of one or more of +CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, +CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT. + +Set *CURLSSH_AUTH_ANY* to let libcurl pick a suitable one. Currently +CURLSSH_AUTH_HOST has no effect. If CURLSSH_AUTH_AGENT is used, libcurl +attempts to connect to ssh-agent or pageant and let the agent attempt the +authentication. + +# DEFAULT + +CURLSSH_AUTH_ANY (all available) + +# PROTOCOLS + +SFTP and SCP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_AUTH_TYPES, + CURLSSH_AUTH_PUBLICKEY | CURLSSH_AUTH_KEYBOARD); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +CURLSSH_AUTH_HOST was added in 7.16.1, CURLSSH_AUTH_AGENT was added in 7.28.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 deleted file mode 100644 index 9a1fab01d57..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_COMPRESSION 3 "05 Aug 2017" libcurl libcurl -.SH NAME -CURLOPT_SSH_COMPRESSION \- enable SSH compression -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_COMPRESSION, long enable); -.fi -.SH DESCRIPTION -Pass a long as parameter set to 1L to enable or 0L to disable. - -Enables built-in SSH compression. This is a request, not an order; the server -may or may not do it. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -All SSH based protocols: SCP, SFTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com"); - - /* enable built-in compression */ - curl_easy_setopt(curl, CURLOPT_SSH_COMPRESSION, 1L); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.56.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_ACCEPT_ENCODING (3), -.BR CURLOPT_TRANSFER_ENCODING (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md new file mode 100644 index 00000000000..5e2b2785d66 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_COMPRESSION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ACCEPT_ENCODING (3) + - CURLOPT_TRANSFER_ENCODING (3) +--- + +# NAME + +CURLOPT_SSH_COMPRESSION - enable SSH compression + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_COMPRESSION, long enable); +~~~ + +# DESCRIPTION + +Pass a long as parameter set to 1L to enable or 0L to disable. + +Enables built-in SSH compression. This is a request, not an order; the server +may or may not do it. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +All SSH based protocols: SCP, SFTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com"); + + /* enable built-in compression */ + curl_easy_setopt(curl, CURLOPT_SSH_COMPRESSION, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.56.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 deleted file mode 100644 index c0a5720c500..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_KEYDATA 3 "4 Nov 2021" libcurl libcurl -.SH NAME -CURLOPT_SSH_HOSTKEYDATA \- pointer to pass to the SSH host key callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a void * as parameter. This \fIpointer\fP is passed along untouched to -the callback set with \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -SCP and SFTP -.SH EXAMPLE -.nf -struct mine { - void *custom; -}; - -static int hostkeycb(void *clientp, /* CURLOPT_SSH_HOSTKEYDATA */ - int keytype, /* CURLKHTYPE */ - const char *key, /* host key to check */ - size_t keylen) /* length of the key */ -{ - /* 'clientp' points to the callback_data struct */ - /* investigate the situation and return the correct value */ - return CURLKHMATCH_OK; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct mine callback_data; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); - curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb); - curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.84.0, works only with libssh2 backend. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSH_HOSTKEYFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md new file mode 100644 index 00000000000..39cbd0ddd27 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md @@ -0,0 +1,73 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_KEYDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_HOSTKEYFUNCTION (3) +--- + +# NAME + +CURLOPT_SSH_HOSTKEYDATA - pointer to pass to the SSH host key callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYDATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a void * as parameter. This *pointer* is passed along untouched to +the callback set with CURLOPT_SSH_HOSTKEYFUNCTION(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +SCP and SFTP + +# EXAMPLE + +~~~c +struct mine { + void *custom; +}; + +static int hostkeycb(void *clientp, /* CURLOPT_SSH_HOSTKEYDATA */ + int keytype, /* CURLKHTYPE */ + const char *key, /* host key to check */ + size_t keylen) /* length of the key */ +{ + /* 'clientp' points to the callback_data struct */ + /* investigate the situation and return the correct value */ + return CURLKHMATCH_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct mine callback_data; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); + curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb); + curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.84.0, works only with libssh2 backend. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 deleted file mode 100644 index 132e9e94dec..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 +++ /dev/null @@ -1,96 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_HOSTKEYFUNCTION 3 "4 Nov 2021" libcurl libcurl -.SH NAME -CURLOPT_SSH_HOSTKEYFUNCTION \- callback to check host key -.SH SYNOPSIS -.nf -#include - -int keycallback(void *clientp, - int keytype, - const char *key, - size_t keylen); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYFUNCTION, - keycallback); -.fi -.SH DESCRIPTION -Pass a pointer to your callback function, which should match the prototype -shown above. It overrides \fICURLOPT_SSH_KNOWNHOSTS(3)\fP. - -This callback gets called when the verification of the SSH host key is needed. - -\fBkey\fP is \fBkeylen\fP bytes long and is the key to check. \fBkeytype\fP -says what type it is, from the \fBCURLKHTYPE_*\fP series in the -\fBcurl_khtype\fP enum. - -\fBclientp\fP is a custom pointer set with \fICURLOPT_SSH_HOSTKEYDATA(3)\fP. - -The callback MUST return one of the following return codes to tell libcurl how -to act: -.IP CURLKHMATCH_OK -The host key is accepted, the connection should continue. -.IP CURLKHMATCH_MISMATCH -the host key is rejected, the connection is canceled. -.SH DEFAULT -NULL -.SH PROTOCOLS -SCP and SFTP -.SH EXAMPLE -.nf -struct mine { - void *custom; -}; - -int hostkeycb(void *clientp, /* passed with CURLOPT_SSH_HOSTKEYDATA */ - int keytype, /* CURLKHTYPE */ - const char *key, /* host key to check */ - size_t keylen) /* length of the key */ -{ - /* 'clientp' points to the callback_data struct */ - /* investigate the situation and return the correct value */ - return CURLKHMATCH_OK; -} -int main(void) -{ - struct mine callback_data; - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); - curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb); - curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.84.0 , work only with libssh2 backend. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSH_HOSTKEYDATA (3), -.BR CURLOPT_SSH_KNOWNHOSTS (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md new file mode 100644 index 00000000000..ed57975209f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md @@ -0,0 +1,98 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_HOSTKEYFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_HOSTKEYDATA (3) + - CURLOPT_SSH_KNOWNHOSTS (3) +--- + +# NAME + +CURLOPT_SSH_HOSTKEYFUNCTION - callback to check host key + +# SYNOPSIS + +~~~c +#include + +int keycallback(void *clientp, + int keytype, + const char *key, + size_t keylen); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYFUNCTION, + keycallback); +~~~ + +# DESCRIPTION + +Pass a pointer to your callback function, which should match the prototype +shown above. It overrides CURLOPT_SSH_KNOWNHOSTS(3). + +This callback gets called when the verification of the SSH host key is needed. + +**key** is **keylen** bytes long and is the key to check. **keytype** +says what type it is, from the **CURLKHTYPE_*** series in the +**curl_khtype** enum. + +**clientp** is a custom pointer set with CURLOPT_SSH_HOSTKEYDATA(3). + +The callback MUST return one of the following return codes to tell libcurl how +to act: + +## CURLKHMATCH_OK + +The host key is accepted, the connection should continue. + +## CURLKHMATCH_MISMATCH + +the host key is rejected, the connection is canceled. + +# DEFAULT + +NULL + +# PROTOCOLS + +SCP and SFTP + +# EXAMPLE + +~~~c +struct mine { + void *custom; +}; + +int hostkeycb(void *clientp, /* passed with CURLOPT_SSH_HOSTKEYDATA */ + int keytype, /* CURLKHTYPE */ + const char *key, /* host key to check */ + size_t keylen) /* length of the key */ +{ + /* 'clientp' points to the callback_data struct */ + /* investigate the situation and return the correct value */ + return CURLKHMATCH_OK; +} +int main(void) +{ + struct mine callback_data; + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); + curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb); + curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.84.0 , work only with libssh2 backend. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 deleted file mode 100644 index e0b2586edbd..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 \- MD5 checksum of SSH server public key -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, - char *md5); -.SH DESCRIPTION -Pass a char * pointing to a string containing 32 hexadecimal digits. The -string should be the 128 bit MD5 checksum of the remote host's public key, and -libcurl aborts the connection to the host unless the MD5 checksum match. - -MD5 is a weak algorithm. We strongly recommend using -\fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP instead. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -SCP and SFTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); - curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, - "afe17cd62a0f3b61f1ab9cb22ba269a7"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.17.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSH_AUTH_TYPES (3), -.BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3), -.BR CURLOPT_SSH_PUBLIC_KEYFILE (3), -.BR CURLOPT_SSH_KNOWNHOSTS (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md new file mode 100644 index 00000000000..4b78765016f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_AUTH_TYPES (3) + - CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3) + - CURLOPT_SSH_KNOWNHOSTS (3) + - CURLOPT_SSH_PUBLIC_KEYFILE (3) +--- + +# NAME + +CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 - MD5 checksum of SSH server public key + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, + char *md5); +~~~ + +# DESCRIPTION + +Pass a char pointer pointing to a string containing 32 hexadecimal digits. The +string should be the 128 bit MD5 checksum of the remote host's public key, and +libcurl aborts the connection to the host unless the MD5 checksum match. + +MD5 is a weak algorithm. We strongly recommend using +CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3) instead. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +SCP and SFTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, + "afe17cd62a0f3b61f1ab9cb22ba269a7"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.17.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 deleted file mode 100644 index 266b7b0ac53..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 +++ /dev/null @@ -1,67 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 3 "27 Aug 2021" libcurl libcurl -.SH NAME -CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 \- SHA256 hash of SSH server public key -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, - char *sha256); -.SH DESCRIPTION -Pass a char * pointing to a string containing a Base64-encoded SHA256 hash of -the remote host's public key. The transfer fails if the given hash does not -match the hash the remote host provides. - -.SH DEFAULT -NULL -.SH PROTOCOLS -SCP and SFTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); - curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, - "NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ="); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.80.0 -Requires the libssh2 backend. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSH_AUTH_TYPES (3), -.BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3), -.BR CURLOPT_SSH_PUBLIC_KEYFILE (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md new file mode 100644 index 00000000000..41562db6311 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_AUTH_TYPES (3) + - CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3) + - CURLOPT_SSH_PUBLIC_KEYFILE (3) +--- + +# NAME + +CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 - SHA256 hash of SSH server public key + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, + char *sha256); +~~~ + +# DESCRIPTION + +Pass a char pointer pointing to a string containing a Base64-encoded SHA256 +hash of the remote host's public key. The transfer fails if the given hash +does not match the hash the remote host provides. + +# DEFAULT + +NULL + +# PROTOCOLS + +SCP and SFTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, + "NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ="); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.80.0 +Requires the libssh2 backend. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 deleted file mode 100644 index 04ae0a55788..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_KEYDATA 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSH_KEYDATA \- pointer passed to the SSH key callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYDATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a void * as parameter. This \fIpointer\fP is passed along verbatim to the -callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP. -.SH DEFAULT -NULL -.SH PROTOCOLS -SFTP and SCP -.SH EXAMPLE -.nf -struct mine { - void *custom; -}; -static int keycb(CURL *easy, - const struct curl_khkey *knownkey, - const struct curl_khkey *foundkey, - enum curl_khmatch match, - void *clientp) -{ - /* 'clientp' points to the callback_data struct */ - /* investigate the situation and return the correct value */ - return CURLKHSTAT_FINE_ADD_TO_FILE; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct mine callback_data; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); - curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb); - curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data); - curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts"); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.6 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSH_KEYDATA (3), -.BR CURLOPT_SSH_KNOWNHOSTS (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md new file mode 100644 index 00000000000..e90cace34f4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_KEYDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_KEYDATA (3) + - CURLOPT_SSH_KNOWNHOSTS (3) +--- + +# NAME + +CURLOPT_SSH_KEYDATA - pointer passed to the SSH key callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYDATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a void * as parameter. This *pointer* is passed along verbatim to the +callback set with CURLOPT_SSH_KEYFUNCTION(3). + +# DEFAULT + +NULL + +# PROTOCOLS + +SFTP and SCP + +# EXAMPLE + +~~~c +struct mine { + void *custom; +}; +static int keycb(CURL *easy, + const struct curl_khkey *knownkey, + const struct curl_khkey *foundkey, + enum curl_khmatch match, + void *clientp) +{ + /* 'clientp' points to the callback_data struct */ + /* investigate the situation and return the correct value */ + return CURLKHSTAT_FINE_ADD_TO_FILE; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct mine callback_data; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); + curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb); + curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data); + curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts"); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.6 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md similarity index 64% rename from docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md index 1abe37d63d8..5fc40060efa 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md @@ -1,32 +1,21 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_KEYFUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSH_KEYFUNCTION \- callback for known host matching logic -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_KEYFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_KEYDATA (3) + - CURLOPT_SSH_KNOWNHOSTS (3) +--- + +# NAME + +CURLOPT_SSH_KEYFUNCTION - callback for known host matching logic + +# SYNOPSIS + +~~~c #include enum curl_khstat { @@ -61,50 +50,69 @@ int ssh_keycallback(CURL *easy, CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYFUNCTION, ssh_keycallback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. It gets called when the known_host matching has been done, to allow the application to act and decide for libcurl how to proceed. The callback is only -called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set. +called if CURLOPT_SSH_KNOWNHOSTS(3) is also set. This callback function gets passed the CURL handle, the key from the -known_hosts file \fIknownkey\fP, the key from the remote site \fIfoundkey\fP, +known_hosts file *knownkey*, the key from the remote site *foundkey*, info from libcurl on the matching status and a custom pointer (set with -\fICURLOPT_SSH_KEYDATA(3)\fP). It MUST return one of the following return +CURLOPT_SSH_KEYDATA(3)). It MUST return one of the following return codes to tell libcurl how to act: -.IP CURLKHSTAT_FINE_REPLACE + +## CURLKHSTAT_FINE_REPLACE + The new host+key is accepted and libcurl replaces the old host+key into the known_hosts file before continuing with the connection. This also adds the new host+key combo to the known_host pool kept in memory if it was not already present there. The adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this. (Added in 7.73.0) -.IP CURLKHSTAT_FINE_ADD_TO_FILE + +## CURLKHSTAT_FINE_ADD_TO_FILE + The host+key is accepted and libcurl appends it to the known_hosts file before continuing with the connection. This also adds the host+key combo to the known_host pool kept in memory if it was not already present there. The adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this. -.IP CURLKHSTAT_FINE + +## CURLKHSTAT_FINE + The host+key is accepted libcurl continues with the connection. This also adds the host+key combo to the known_host pool kept in memory if it was not already present there. -.IP CURLKHSTAT_REJECT + +## CURLKHSTAT_REJECT + The host+key is rejected. libcurl denies the connection to continue and it is closed. -.IP CURLKHSTAT_DEFER + +## CURLKHSTAT_DEFER + The host+key is rejected, but the SSH connection is asked to be kept alive. -This feature could be used when the app wants to somehow return back and act -on the host+key situation and then retry without needing the overhead of -setting it up from scratch again. -.SH DEFAULT +This feature could be used when the app wants to return and act on the +host+key situation and then retry without needing the overhead of setting it +up from scratch again. + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + SFTP and SCP -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c struct mine { void *custom; }; @@ -133,11 +141,12 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.19.6 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSH_KEYDATA (3), -.BR CURLOPT_SSH_KNOWNHOSTS (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 deleted file mode 100644 index 8984fedb70a..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_KNOWNHOSTS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSH_KNOWNHOSTS \- file name holding the SSH known hosts -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KNOWNHOSTS, char *fname); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string holding the file name of the -known_host file to use. The known_hosts file should use the OpenSSH file -format as supported by libssh2. If this file is specified, libcurl only -accepts connections with hosts that are known and present in that file, with a -matching public key. Use \fICURLOPT_SSH_KEYFUNCTION(3)\fP to alter the default -behavior on host and key matches and mismatches. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -SFTP and SCP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); - curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, - "/home/clarkkent/.ssh/known_hosts"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.6 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSH_AUTH_TYPES (3), -.BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md new file mode 100644 index 00000000000..cc5304fc106 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_KNOWNHOSTS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_AUTH_TYPES (3) + - CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3) +--- + +# NAME + +CURLOPT_SSH_KNOWNHOSTS - file name holding the SSH known hosts + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KNOWNHOSTS, char *fname); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string holding the file name of the +known_host file to use. The known_hosts file should use the OpenSSH file +format as supported by libssh2. If this file is specified, libcurl only +accepts connections with hosts that are known and present in that file, with a +matching public key. Use CURLOPT_SSH_KEYFUNCTION(3) to alter the default +behavior on host and key matches and mismatches. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +SFTP and SCP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, + "/home/clarkkent/.ssh/known_hosts"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.6 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 deleted file mode 100644 index 974a5b786da..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_PRIVATE_KEYFILE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSH_PRIVATE_KEYFILE \- private key file for SSH auth -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PRIVATE_KEYFILE, - char *filename); -.SH DESCRIPTION -Pass a char * pointing to a \fIfilename\fP for your private key. If not used, -libcurl defaults to \fB$HOME/.ssh/id_rsa\fP or \fB$HOME/.ssh/id_dsa\fP if the -HOME environment variable is set, and in the current directory if HOME is not -set. - -If the file is password-protected, set the password with -\fICURLOPT_KEYPASSWD(3)\fP. - -The SSH library derives the public key from this private key when possible. If -the SSH library cannot derive the public key from the private one and no -public one is provided with \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP, the transfer -fails. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -As explained above -.SH PROTOCOLS -SFTP and SCP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); - curl_easy_setopt(curl, CURLOPT_SSH_PRIVATE_KEYFILE, - "/home/clarkkent/.ssh/id_rsa"); - curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "password"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.16.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSH_PUBLIC_KEYFILE (3), -.BR CURLOPT_SSH_AUTH_TYPES (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md new file mode 100644 index 00000000000..e8a40079b56 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md @@ -0,0 +1,76 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_PRIVATE_KEYFILE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_AUTH_TYPES (3) + - CURLOPT_SSH_PUBLIC_KEYFILE (3) +--- + +# NAME + +CURLOPT_SSH_PRIVATE_KEYFILE - private key file for SSH auth + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PRIVATE_KEYFILE, + char *filename); +~~~ + +# DESCRIPTION + +Pass a char pointer pointing to a *filename* for your private key. If not +used, libcurl defaults to **$HOME/.ssh/id_rsa** or **$HOME/.ssh/id_dsa** if +the HOME environment variable is set, and in the current directory if HOME is +not set. + +If the file is password-protected, set the password with +CURLOPT_KEYPASSWD(3). + +The SSH library derives the public key from this private key when possible. If +the SSH library cannot derive the public key from the private one and no +public one is provided with CURLOPT_SSH_PUBLIC_KEYFILE(3), the transfer +fails. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +As explained above + +# PROTOCOLS + +SFTP and SCP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_PRIVATE_KEYFILE, + "/home/clarkkent/.ssh/id_rsa"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "password"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.16.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 deleted file mode 100644 index 6a1d6991bfb..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSH_PUBLIC_KEYFILE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSH_PUBLIC_KEYFILE \- public key file for SSH auth -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PUBLIC_KEYFILE, - char *filename); -.SH DESCRIPTION -Pass a char * pointing to a \fIfilename\fP for your public key. If not used, -libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment -variable is set, and just "id_dsa.pub" in the current directory if HOME is not -set. - -If NULL (or an empty string) is passed to this option, libcurl passes no -public key to the SSH library, which then rather derives it from the private -key. If the SSH library cannot derive the public key from the private one and -no public one is provided, the transfer fails. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -SFTP and SCP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); - curl_easy_setopt(curl, CURLOPT_SSH_PUBLIC_KEYFILE, - "/home/clarkkent/.ssh/id_rsa.pub"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -The "" trick was added in 7.26.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSH_PRIVATE_KEYFILE (3), -.BR CURLOPT_SSH_AUTH_TYPES (3) diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md new file mode 100644 index 00000000000..35d65ad93ed --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSH_PUBLIC_KEYFILE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSH_AUTH_TYPES (3) + - CURLOPT_SSH_PRIVATE_KEYFILE (3) +--- + +# NAME + +CURLOPT_SSH_PUBLIC_KEYFILE - public key file for SSH auth + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PUBLIC_KEYFILE, + char *filename); +~~~ + +# DESCRIPTION + +Pass a char pointer pointing to a *filename* for your public key. If not used, +libcurl defaults to **$HOME/.ssh/id_dsa.pub** if the HOME environment variable +is set, and just "id_dsa.pub" in the current directory if HOME is not set. + +If NULL (or an empty string) is passed to this option, libcurl passes no +public key to the SSH library, which then rather derives it from the private +key. If the SSH library cannot derive the public key from the private one and +no public one is provided, the transfer fails. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +SFTP and SCP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_PUBLIC_KEYFILE, + "/home/clarkkent/.ssh/id_rsa.pub"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +The "" trick was added in 7.26.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.3 b/docs/libcurl/opts/CURLOPT_SSLCERT.3 deleted file mode 100644 index d3ded42fa50..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.3 +++ /dev/null @@ -1,90 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLCERT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSLCERT \- SSL client certificate -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT, char *cert); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. The string should be -the file name of your client certificate. The default format is "P12" on -Secure Transport and "PEM" on other engines, and can be changed with -\fICURLOPT_SSLCERTTYPE(3)\fP. - -With Secure Transport, this can also be the nickname of the certificate you -wish to authenticate with as it is named in the security database. 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 can be specified by a path expression to a -certificate store. (You can import \fIPFX\fP to a store first). You can use -"\\\\" to refer to a certificate in -the system certificates store, for example, -\fB"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"\fP. The thumbprint is usually a -SHA-1 hex string which you can see in certificate details. Following store -locations are supported: \fBCurrentUser\fP, \fBLocalMachine\fP, -\fBCurrentService\fP, \fBServices\fP, \fBCurrentUserGroupPolicy\fP, -\fBLocalMachineGroupPolicy\fP, \fBLocalMachineEnterprise\fP. Schannel also -support P12 certificate file, with the string "P12" specified with -\fICURLOPT_SSLCERTTYPE(3)\fP. - -When using a client certificate, you most likely also need to provide a -private key with \fICURLOPT_SSLKEY(3)\fP. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSLCERTTYPE (3), -.BR CURLOPT_SSLKEY (3), -.BR CURLOPT_KEYPASSWD (3) diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.md b/docs/libcurl/opts/CURLOPT_SSLCERT.md new file mode 100644 index 00000000000..3029832db26 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.md @@ -0,0 +1,87 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLCERT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_KEYPASSWD (3) + - CURLOPT_SSLCERTTYPE (3) + - CURLOPT_SSLKEY (3) +--- + +# NAME + +CURLOPT_SSLCERT - SSL client certificate + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT, char *cert); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. The string should be +the file name of your client certificate. The default format is "P12" on +Secure Transport and "PEM" on other engines, and can be changed with +CURLOPT_SSLCERTTYPE(3). + +With Secure Transport, this can also be the nickname of the certificate you +wish to authenticate with as it is named in the security database. 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 can be specified by a path expression to a +certificate store. (You can import *PFX* to a store first). You can use +"" to refer to a certificate in the +system certificates store, for example, +**"CurrentUserMY934a7ac6f8a5d579285a74fa"**. The 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**, +**LocalMachineEnterprise**. Schannel also support P12 certificate file, with +the string "P12" specified with CURLOPT_SSLCERTTYPE(3). + +When using a client certificate, you most likely also need to provide a +private key with CURLOPT_SSLKEY(3). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 deleted file mode 100644 index e800c5cbd84..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLCERTTYPE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSLCERTTYPE \- type of client SSL certificate -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERTTYPE, char *type); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. The string should be -the format of your certificate. - -Supported formats are "PEM" and "DER", except with Secure Transport or -Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or -later, or OS X 10.7 or later) and Schannel support "P12" for PKCS#12-encoded -files. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -"PEM" -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM"); - curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -If built TLS enabled. Added in 7.9.3 -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSLCERT (3), -.BR CURLOPT_SSLKEY (3) diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md new file mode 100644 index 00000000000..420ca4f86b8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLCERTTYPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSLCERT (3) + - CURLOPT_SSLKEY (3) +--- + +# NAME + +CURLOPT_SSLCERTTYPE - type of client SSL certificate + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERTTYPE, char *type); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. The string should be +the format of your certificate. + +Supported formats are "PEM" and "DER", except with Secure Transport or +Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or +later, or OS X 10.7 or later) and Schannel support "P12" for PKCS#12-encoded +files. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +"PEM" + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +If built TLS enabled. Added in 7.9.3 + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 deleted file mode 100644 index 37a53362e75..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 +++ /dev/null @@ -1,85 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLCERT_BLOB 3 "24 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_SSLCERT_BLOB \- SSL client certificate from memory blob -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT_BLOB, - struct curl_blob *stblob); -.fi -.SH DESCRIPTION -Pass a pointer to a curl_blob structure, which contains (pointer and size) a -client certificate. The format must be "P12" on Secure Transport or -Schannel. The format must be "P12" or "PEM" on OpenSSL. The format must be -"DER" or "PEM" on mbedTLS. The format must be specified with -\fICURLOPT_SSLCERTTYPE(3)\fP. - -If the blob is initialized with the flags member of struct curl_blob set to -CURL_BLOB_COPY, the application does not have to keep the buffer around after -setting this. - -This option is an alternative to \fICURLOPT_SSLCERT(3)\fP which instead -expects a file name as input. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf - -extern char *certificateData; /* point to data */ -extern size_t filesize; /* size of data */ - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - struct curl_blob stblob; - stblob.data = certificateData; - stblob.len = filesize; - stblob.flags = CURL_BLOB_COPY; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &stblob); - curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "P12"); - curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport, -Schannel and mbedTLS (since 7.78.0) backends. -.SH RETURN VALUE -Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSLCERTTYPE (3), -.BR CURLOPT_SSLKEY (3), -.BR CURLOPT_KEYPASSWD (3) diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md new file mode 100644 index 00000000000..5f7d7389654 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md @@ -0,0 +1,83 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLCERT_BLOB +Section: 3 +Source: libcurl +See-also: + - CURLOPT_KEYPASSWD (3) + - CURLOPT_SSLCERTTYPE (3) + - CURLOPT_SSLKEY (3) +--- + +# NAME + +CURLOPT_SSLCERT_BLOB - SSL client certificate from memory blob + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT_BLOB, + struct curl_blob *stblob); +~~~ + +# DESCRIPTION + +Pass a pointer to a curl_blob structure, which contains (pointer and size) a +client certificate. The format must be "P12" on Secure Transport or +Schannel. The format must be "P12" or "PEM" on OpenSSL. The format must be +"DER" or "PEM" on mbedTLS. The format must be specified with +CURLOPT_SSLCERTTYPE(3). + +If the blob is initialized with the flags member of struct curl_blob set to +CURL_BLOB_COPY, the application does not have to keep the buffer around after +setting this. + +This option is an alternative to CURLOPT_SSLCERT(3) which instead +expects a file name as input. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c + +extern char *certificateData; /* point to data */ +extern size_t filesize; /* size of data */ + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_blob stblob; + stblob.data = certificateData; + stblob.len = filesize; + stblob.flags = CURL_BLOB_COPY; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &stblob); + curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "P12"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport, +Schannel and mbedTLS (since 7.78.0) backends. + +# RETURN VALUE + +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.3 b/docs/libcurl/opts/CURLOPT_SSLENGINE.3 deleted file mode 100644 index 495841da9ec..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLENGINE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSLENGINE \- SSL engine identifier -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE, char *id); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It is used as the -identifier for the crypto engine you want to use for your private key. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Only if the SSL backend is OpenSSL built with engine support. -.SH RETURN VALUE -CURLE_OK - Engine found. - -CURLE_SSL_ENGINE_NOTFOUND - Engine not found, or OpenSSL was not built with -engine support. - -CURLE_SSL_ENGINE_INITFAILED - Engine found but initialization failed. - -CURLE_NOT_BUILT_IN - Option not built in, OpenSSL is not the SSL backend. - -CURLE_UNKNOWN_OPTION - Option not recognized. - -CURLE_OUT_OF_MEMORY - Insufficient heap space. -.SH "SEE ALSO" -.BR CURLINFO_SSL_ENGINES (3), -.BR CURLOPT_SSLENGINE_DEFAULT (3), -.BR CURLOPT_SSLKEY (3) diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.md b/docs/libcurl/opts/CURLOPT_SSLENGINE.md new file mode 100644 index 00000000000..45ccc42c5a1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE.md @@ -0,0 +1,74 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLENGINE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_SSL_ENGINES (3) + - CURLOPT_SSLENGINE_DEFAULT (3) + - CURLOPT_SSLKEY (3) +--- + +# NAME + +CURLOPT_SSLENGINE - SSL engine identifier + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE, char *id); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. It is used as the +identifier for the crypto engine you want to use for your private key. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Only if the SSL backend is OpenSSL built with engine support. + +# RETURN VALUE + +CURLE_OK - Engine found. + +CURLE_SSL_ENGINE_NOTFOUND - Engine not found, or OpenSSL was not built with +engine support. + +CURLE_SSL_ENGINE_INITFAILED - Engine found but initialization failed. + +CURLE_NOT_BUILT_IN - Option not built in, OpenSSL is not the SSL backend. + +CURLE_UNKNOWN_OPTION - Option not recognized. + +CURLE_OUT_OF_MEMORY - Insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 deleted file mode 100644 index 0e904c67fc9..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLENGINE_DEFAULT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSLENGINE_DEFAULT \- make SSL engine default -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE_DEFAULT, long val); -.fi -.SH DESCRIPTION -Pass a long set to 1 to make the already specified crypto engine the default -for (asymmetric) crypto operations. - -This option has no effect unless set after \fICURLOPT_SSLENGINE(3)\fP. -.SH DEFAULT -None -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic"); - curl_easy_setopt(curl, CURLOPT_SSLENGINE_DEFAULT, 1L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Only if the SSL backend is OpenSSL built with engine support. -.SH RETURN VALUE -CURLE_OK - Engine set as default. - -CURLE_SSL_ENGINE_SETFAILED - Engine could not be set as default. - -CURLE_NOT_BUILT_IN - Option not built in, OpenSSL is not the SSL backend. - -CURLE_UNKNOWN_OPTION - Option not recognized. - -CURLE_OUT_OF_MEMORY - Insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSLENGINE (3), -.BR CURLOPT_SSLCERT (3) diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md new file mode 100644 index 00000000000..d082f7b54ae --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLENGINE_DEFAULT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSLCERT (3) + - CURLOPT_SSLENGINE (3) +--- + +# NAME + +CURLOPT_SSLENGINE_DEFAULT - make SSL engine default + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE_DEFAULT, long val); +~~~ + +# DESCRIPTION + +Pass a long set to 1 to make the already specified crypto engine the default +for (asymmetric) crypto operations. + +This option has no effect unless set after CURLOPT_SSLENGINE(3). + +# DEFAULT + +None + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic"); + curl_easy_setopt(curl, CURLOPT_SSLENGINE_DEFAULT, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Only if the SSL backend is OpenSSL built with engine support. + +# RETURN VALUE + +CURLE_OK - Engine set as default. + +CURLE_SSL_ENGINE_SETFAILED - Engine could not be set as default. + +CURLE_NOT_BUILT_IN - Option not built in, OpenSSL is not the SSL backend. + +CURLE_UNKNOWN_OPTION - Option not recognized. + +CURLE_OUT_OF_MEMORY - Insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_SSLKEY.3 deleted file mode 100644 index 7f54c4eafba..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSLKEY.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLKEY 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSLKEY \- private key file for TLS and SSL client cert -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEY, char *keyfile); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. The string should be -the file name of your private key. The default format is "PEM" and can be -changed with \fICURLOPT_SSLKEYTYPE(3)\fP. - -(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and -Schannel SSL backends because they expect the private key to be already present -in the key-chain or PKCS#12 file containing the certificate. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSLCERT (3), -.BR CURLOPT_SSLKEY_BLOB (3), -.BR CURLOPT_SSLKEYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.md b/docs/libcurl/opts/CURLOPT_SSLKEY.md new file mode 100644 index 00000000000..94c65b2f681 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLKEY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSLCERT (3) + - CURLOPT_SSLKEYTYPE (3) + - CURLOPT_SSLKEY_BLOB (3) +--- + +# NAME + +CURLOPT_SSLKEY - private key file for TLS and SSL client cert + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEY, char *keyfile); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. The string should be +the file name of your private key. The default format is "PEM" and can be +changed with CURLOPT_SSLKEYTYPE(3). + +(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and +Schannel SSL backends because they expect the private key to be already present +in the key-chain or PKCS#12 file containing the certificate. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 deleted file mode 100644 index 957d175eaa3..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLKEYTYPE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSLKEYTYPE \- type of the private key file -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEYTYPE, char *type); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. The string should be -the format of your private key. Supported formats are "PEM", "DER" and "ENG". - -The format "ENG" enables you to load the private key from a crypto engine. In -this case \fICURLOPT_SSLKEY(3)\fP is used as an identifier passed to the -engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE(3)\fP. -\&"DER" format key file currently does not work because of a bug in OpenSSL. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -"PEM" -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); - curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); - curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM"); - curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSLCERT (3), -.BR CURLOPT_SSLKEY (3), -.BR CURLOPT_PROXY_SSLKEYTYPE (3) diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md new file mode 100644 index 00000000000..8a2023ea461 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLKEYTYPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLKEYTYPE (3) + - CURLOPT_SSLCERT (3) + - CURLOPT_SSLKEY (3) +--- + +# NAME + +CURLOPT_SSLKEYTYPE - type of the private key file + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEYTYPE, char *type); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. The string should be +the format of your private key. Supported formats are "PEM", "DER" and "ENG". + +The format "ENG" enables you to load the private key from a crypto engine. In +this case CURLOPT_SSLKEY(3) is used as an identifier passed to the +engine. You have to set the crypto engine with CURLOPT_SSLENGINE(3). +&"DER" format key file currently does not work because of a bug in OpenSSL. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +"PEM" + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); + curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM"); + curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.3 b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md similarity index 50% rename from docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.3 rename to docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md index 8d3f21da3f3..4adf8032836 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md @@ -1,54 +1,51 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLKEY_BLOB 3 "24 Jun 2020" libcurl libcurl -.SH NAME -CURLOPT_SSLKEY_BLOB \- private key for client cert from memory blob -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLKEY_BLOB +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSLKEY (3) + - CURLOPT_SSLKEYTYPE (3) +--- + +# NAME + +CURLOPT_SSLKEY_BLOB - private key for client cert from memory blob + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEY_BLOB, struct curl_blob *blob); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to a curl_blob structure, which contains information (pointer and size) for a private key. Compatible with OpenSSL. The format (like "PEM") -must be specified with \fICURLOPT_SSLKEYTYPE(3)\fP. +must be specified with CURLOPT_SSLKEYTYPE(3). If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. -This option is an alternative to \fICURLOPT_SSLKEY(3)\fP which instead expects +This option is an alternative to CURLOPT_SSLKEY(3) which instead expects a file name as input. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c extern char *certificateData; /* point to cert */ extern size_t filesize; /* size of cert */ @@ -78,12 +75,13 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.71.0. This option is supported by the OpenSSL backends. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_SSLKEYTYPE (3), -.BR CURLOPT_SSLKEY (3) diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_SSLVERSION.md similarity index 51% rename from docs/libcurl/opts/CURLOPT_SSLVERSION.3 rename to docs/libcurl/opts/CURLOPT_SSLVERSION.md index 2031b68032f..f64a13b5fe0 100644 --- a/docs/libcurl/opts/CURLOPT_SSLVERSION.3 +++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.md @@ -1,37 +1,30 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSLVERSION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSLVERSION \- preferred TLS/SSL version -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSLVERSION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTP_VERSION (3) + - CURLOPT_IPRESOLVE (3) + - CURLOPT_PROXY_SSLVERSION (3) + - CURLOPT_USE_SSL (3) +--- + +# NAME + +CURLOPT_SSLVERSION - preferred TLS/SSL version + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLVERSION, long version); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a long as parameter to control which version range of SSL/TLS versions to use. @@ -40,60 +33,87 @@ version to be more and more secure in this order through history: SSL v2, SSLv3, TLS v1.0, TLS v1.1, TLS v1.2 and the most recent TLS v1.3. Use one of the available defines for this purpose. The available options are: -.RS -.IP CURL_SSLVERSION_DEFAULT + +## CURL_SSLVERSION_DEFAULT + The default acceptable version range. The minimum acceptable version is by default TLS v1.0 since 7.39.0 (unless the TLS library has a stricter rule). -.IP CURL_SSLVERSION_TLSv1 + +## CURL_SSLVERSION_TLSv1 + TLS v1.0 or later -.IP CURL_SSLVERSION_SSLv2 + +## CURL_SSLVERSION_SSLv2 + SSL v2 - refused -.IP CURL_SSLVERSION_SSLv3 + +## CURL_SSLVERSION_SSLv3 + SSL v3 - refused -.IP CURL_SSLVERSION_TLSv1_0 + +## CURL_SSLVERSION_TLSv1_0 + TLS v1.0 or later (Added in 7.34.0) -.IP CURL_SSLVERSION_TLSv1_1 + +## CURL_SSLVERSION_TLSv1_1 + TLS v1.1 or later (Added in 7.34.0) -.IP CURL_SSLVERSION_TLSv1_2 + +## CURL_SSLVERSION_TLSv1_2 + TLS v1.2 or later (Added in 7.34.0) -.IP CURL_SSLVERSION_TLSv1_3 + +## CURL_SSLVERSION_TLSv1_3 + TLS v1.3 or later (Added in 7.52.0) -.RE -The maximum TLS version can be set by using \fIone\fP of the -CURL_SSLVERSION_MAX_ macros below. It is also possible to OR \fIone\fP of the -CURL_SSLVERSION_ macros with \fIone\fP of the CURL_SSLVERSION_MAX_ macros. +The maximum TLS version can be set by using *one* of the +CURL_SSLVERSION_MAX_ macros below. It is also possible to OR *one* of the +CURL_SSLVERSION_ macros with *one* of the CURL_SSLVERSION_MAX_ macros. The MAX macros are not supported for WolfSSL. -.RS -.IP CURL_SSLVERSION_MAX_DEFAULT + +## CURL_SSLVERSION_MAX_DEFAULT + The flag defines the maximum supported TLS version by libcurl, or the default value from the SSL library is used. libcurl uses a sensible default maximum, which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then - assuming the TLS library support it. (Added in 7.54.0) -.IP CURL_SSLVERSION_MAX_TLSv1_0 + +## CURL_SSLVERSION_MAX_TLSv1_0 + The flag defines maximum supported TLS version as TLS v1.0. (Added in 7.54.0) -.IP CURL_SSLVERSION_MAX_TLSv1_1 + +## CURL_SSLVERSION_MAX_TLSv1_1 + The flag defines maximum supported TLS version as TLS v1.1. (Added in 7.54.0) -.IP CURL_SSLVERSION_MAX_TLSv1_2 + +## CURL_SSLVERSION_MAX_TLSv1_2 + The flag defines maximum supported TLS version as TLS v1.2. (Added in 7.54.0) -.IP CURL_SSLVERSION_MAX_TLSv1_3 + +## CURL_SSLVERSION_MAX_TLSv1_3 + The flag defines maximum supported TLS version as TLS v1.3. (Added in 7.54.0) -.RE In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were -documented to allow \fIonly\fP the specified TLS version, but behavior was +documented to allow *only* the specified TLS version, but behavior was inconsistent depending on the TLS library. -.SH DEFAULT +# DEFAULT + CURL_SSLVERSION_DEFAULT -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -107,18 +127,17 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + SSLv2 and SSLv3 are refused completely since curl 7.77.0 SSLv2 is disabled by default since 7.18.1. Other SSL versions availability may vary depending on which backend libcurl has been built to use. SSLv3 is disabled by default since 7.39.0. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTP_VERSION (3), -.BR CURLOPT_IPRESOLVE (3), -.BR CURLOPT_PROXY_SSLVERSION (3), -.BR CURLOPT_USE_SSL (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 deleted file mode 100644 index 8196b55298c..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 +++ /dev/null @@ -1,94 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_CIPHER_LIST 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_CIPHER_LIST \- ciphers to use for TLS -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list); -.fi -.SH DESCRIPTION -Pass a char *, pointing to a null-terminated string holding the list of -ciphers to use for the SSL connection. The list must be syntactically correct, -it consists of one or more cipher strings separated by colons. Commas or -spaces are also acceptable separators but colons are normally used, \&!, \&- -and \&+ can be used as operators. - -For OpenSSL and GnuTLS valid examples of cipher lists include \fBRC4-SHA\fP, -\fBSHA1+DES\fP, \fBTLSv1\fP and \fBDEFAULT\fP. The default list is normally -set when you compile OpenSSL. - -For WolfSSL, valid examples of cipher lists include \fBECDHE-RSA-RC4-SHA\fP, -\fBAES256-SHA:AES256-SHA256\fP, etc. - -For BearSSL, valid examples of cipher lists include -\fBECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256\fP, or when using IANA names -\fBTLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256\fP, -etc. -With BearSSL you do not add/remove ciphers. If one uses this option then all -known ciphers are disabled and only those passed in are enabled. - -For Schannel, you can use this option to set algorithms but not specific cipher -suites. Refer to the ciphers lists document for algorithms. - -Find more details about cipher lists on this URL: - - https://curl.se/docs/ssl-ciphers.html - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL, use internal default -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST, "TLSv1"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.9, in 7.83.0 for BearSSL - -If built TLS enabled. -.SH RETURN VALUE -Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_TLS13_CIPHERS (3), -.BR CURLOPT_SSLVERSION (3), -.BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), -.BR CURLOPT_PROXY_TLS13_CIPHERS (3), -.BR CURLOPT_USE_SSL (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md new file mode 100644 index 00000000000..2d7c32da220 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md @@ -0,0 +1,92 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_CIPHER_LIST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSL_CIPHER_LIST (3) + - CURLOPT_PROXY_TLS13_CIPHERS (3) + - CURLOPT_SSLVERSION (3) + - CURLOPT_TLS13_CIPHERS (3) + - CURLOPT_USE_SSL (3) +--- + +# NAME + +CURLOPT_SSL_CIPHER_LIST - ciphers to use for TLS + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list); +~~~ + +# DESCRIPTION + +Pass a char pointer, pointing to a null-terminated string holding the list of +ciphers to use for the SSL connection. The list must be syntactically correct, +it consists of one or more cipher strings separated by colons. Commas or +spaces are also acceptable separators but colons are normally used, &!, &- and +&+ can be used as operators. + +For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**, +**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally +set when you compile OpenSSL. + +For WolfSSL, valid examples of cipher lists include **ECDHE-RSA-RC4-SHA**, +**AES256-SHA:AES256-SHA256**, etc. + +For BearSSL, valid examples of cipher lists include +**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using IANA names +**TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256**, +etc. +With BearSSL you do not add/remove ciphers. If one uses this option then all +known ciphers are disabled and only those passed in are enabled. + +For Schannel, you can use this option to set algorithms but not specific cipher +suites. Refer to the ciphers lists document for algorithms. + +Find more details about cipher lists on this URL: + + https://curl.se/docs/ssl-ciphers.html + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL, use internal default + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST, "TLSv1"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.9, in 7.83.0 for BearSSL + +If built TLS enabled. + +# RETURN VALUE + +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md similarity index 52% rename from docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 rename to docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md index 6abe2a9bf40..6e328a5bd40 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md @@ -1,46 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_CTX_DATA 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_CTX_DATA \- pointer passed to SSL context callback -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_CTX_DATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSLVERSION (3) + - CURLOPT_SSL_CTX_FUNCTION (3) +--- + +# NAME + +CURLOPT_SSL_CTX_DATA - pointer passed to SSL context callback + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_DATA, void *pointer); -.fi -.SH DESCRIPTION -Data \fIpointer\fP to pass to the ssl context callback set by the option -\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you get as third +~~~ + +# DESCRIPTION + +Data *pointer* to pass to the ssl context callback set by the option +CURLOPT_SSL_CTX_FUNCTION(3), this is the pointer you get as third parameter. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c /* OpenSSL specific */ #include @@ -60,14 +57,14 @@ static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm) */ PEM_read_bio_X509(bio, &cert, 0, NULL); if(!cert) - printf("PEM_read_bio_X509 failed...\\n"); + printf("PEM_read_bio_X509 failed...\n"); /* get a pointer to the X509 certificate store (which may be empty) */ store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx); /* add our certificate to this store */ if(X509_STORE_add_cert(store, cert) == 0) - printf("error adding certificate\\n"); + printf("error adding certificate\n"); /* decrease reference counts */ X509_free(cert); @@ -82,15 +79,15 @@ int main(void) CURL *ch; CURLcode rv; char *mypem = /* example CA cert PEM - shortened */ - "-----BEGIN CERTIFICATE-----\\n" - "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\\n" - "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\\n" - "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\\n" - "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\\n" - "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\\n" - "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\\n" - "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n" - "-----END CERTIFICATE-----\\n"; + "-----BEGIN CERTIFICATE-----\n" + "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\n" + "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\n" + "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\n" + "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\n" + "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\n" + "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\n" + "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\n" + "-----END CERTIFICATE-----\n"; curl_global_init(CURL_GLOBAL_ALL); ch = curl_easy_init(); @@ -103,24 +100,25 @@ int main(void) curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); rv = curl_easy_perform(ch); if(!rv) - printf("*** transfer succeeded ***\\n"); + printf("*** transfer succeeded ***\n"); else - printf("*** transfer failed ***\\n"); + printf("*** transfer failed ***\n"); curl_easy_cleanup(ch); curl_global_cleanup(); return rv; } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL, in 7.54.0 for mbedTLS, in 7.83.0 in BearSSL. Other SSL backends are not supported. -.SH RETURN VALUE + +# RETURN VALUE + CURLE_OK if supported; or an error such as: CURLE_NOT_BUILT_IN - Not supported by the SSL backend CURLE_UNKNOWN_OPTION -.SH "SEE ALSO" -.BR CURLOPT_SSL_CTX_FUNCTION (3), -.BR CURLOPT_SSLVERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md similarity index 58% rename from docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 rename to docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md index 3ec1c95e5d3..ae8b8bbadd3 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md @@ -1,39 +1,31 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_CTX_FUNCTION 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_CTX_FUNCTION \- SSL context callback for OpenSSL, wolfSSL or mbedTLS -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_CTX_FUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSL_CTX_DATA (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_SSL_CTX_FUNCTION - SSL context callback for OpenSSL, wolfSSL or mbedTLS + +# SYNOPSIS + +~~~c #include CURLcode ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *clientp); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION, ssl_ctx_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + This option only works for libcurl powered by OpenSSL, wolfSSL, mbedTLS or BearSSL. If libcurl was built against another SSL library this functionality is absent. @@ -44,16 +36,16 @@ shown above. This callback function gets called by libcurl just before the initialization of an SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behavior of the SSL -initialization. The \fIssl_ctx\fP parameter is actually a pointer to the SSL -library's \fISSL_CTX\fP for OpenSSL or wolfSSL, a pointer to -\fImbedtls_ssl_config\fP for mbedTLS or a pointer to -\fIbr_ssl_client_context\fP for BearSSL. If an error is returned from the +initialization. The *ssl_ctx* parameter is actually a pointer to the SSL +library's *SSL_CTX* for OpenSSL or wolfSSL, a pointer to +*mbedtls_ssl_config* for mbedTLS or a pointer to +*br_ssl_client_context* for BearSSL. If an error is returned from the callback no attempt to establish a connection is made and the perform -operation returns the callback's error code. Set the \fIclientp\fP argument -with the \fICURLOPT_SSL_CTX_DATA(3)\fP option. +operation returns the callback's error code. Set the *clientp* argument +with the CURLOPT_SSL_CTX_DATA(3) option. This function gets called on all new connections made to a server, during the -SSL negotiation. The \fIssl_ctx\fP points to a newly initialized object each +SSL negotiation. The *ssl_ctx* points to a newly initialized object each time, but note the pointer may be the same as from a prior call. To use this properly, a non-trivial amount of knowledge of your SSL library is @@ -62,27 +54,33 @@ callbacks to add additional validation code for certificates, and even to change the actual URI of an HTTPS request. For OpenSSL, asynchronous certificate verification via -\fISSL_set_retry_verify\fP is supported. (Added in 8.3.0) +*SSL_set_retry_verify* is supported. (Added in 8.3.0) -WARNING: The \fICURLOPT_SSL_CTX_FUNCTION(3)\fP callback allows the application +WARNING: The CURLOPT_SSL_CTX_FUNCTION(3) callback allows the application to reach in and modify SSL details in the connection without libcurl itself knowing anything about it, which then subsequently can lead to libcurl unknowingly reusing SSL connections with different properties. To remedy this -you may set \fICURLOPT_FORBID_REUSE(3)\fP from the callback function. +you may set CURLOPT_FORBID_REUSE(3) from the callback function. -WARNING: If you are using DNS-over-HTTPS (DoH) via \fICURLOPT_DOH_URL(3)\fP +WARNING: If you are using DNS-over-HTTPS (DoH) via CURLOPT_DOH_URL(3) then this callback is also called for those transfers and the curl handle is -set to an internal handle. \fBThis behavior is subject to change.\fP We -recommend before performing your transfer set \fICURLOPT_PRIVATE(3)\fP on your +set to an internal handle. **This behavior is subject to change.** We +recommend before performing your transfer set CURLOPT_PRIVATE(3) on your curl handle so you can identify it in the context callback. If you have a reason to modify DoH SSL context please let us know on the curl-library mailing list because we are considering removing this capability. -.SH DEFAULT + +# DEFAULT + NULL -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c /* OpenSSL specific */ #include @@ -102,14 +100,14 @@ static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm) */ PEM_read_bio_X509(bio, &cert, 0, NULL); if(!cert) - printf("PEM_read_bio_X509 failed...\\n"); + printf("PEM_read_bio_X509 failed...\n"); /* get a pointer to the X509 certificate store (which may be empty) */ store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx); /* add our certificate to this store */ if(X509_STORE_add_cert(store, cert) == 0) - printf("error adding certificate\\n"); + printf("error adding certificate\n"); /* decrease reference counts */ X509_free(cert); @@ -124,15 +122,15 @@ int main(void) CURL *ch; CURLcode rv; char *mypem = /* example CA cert PEM - shortened */ - "-----BEGIN CERTIFICATE-----\\n" - "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\\n" - "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\\n" - "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\\n" - "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\\n" - "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\\n" - "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\\n" - "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n" - "-----END CERTIFICATE-----\\n"; + "-----BEGIN CERTIFICATE-----\n" + "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\n" + "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\n" + "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\n" + "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\n" + "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\n" + "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\n" + "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\n" + "-----END CERTIFICATE-----\n"; curl_global_init(CURL_GLOBAL_ALL); ch = curl_easy_init(); @@ -145,24 +143,25 @@ int main(void) curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); rv = curl_easy_perform(ch); if(!rv) - printf("*** transfer succeeded ***\\n"); + printf("*** transfer succeeded ***\n"); else - printf("*** transfer failed ***\\n"); + printf("*** transfer failed ***\n"); curl_easy_cleanup(ch); curl_global_cleanup(); return rv; } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL, in 7.54.0 for mbedTLS, in 7.83.0 in BearSSL. Other SSL backends are not supported. -.SH RETURN VALUE + +# RETURN VALUE + CURLE_OK if supported; or an error such as: CURLE_NOT_BUILT_IN - Not supported by the SSL backend CURLE_UNKNOWN_OPTION -.SH "SEE ALSO" -.BR CURLOPT_SSL_CTX_DATA (3), -.BR CURLOPT_SSL_VERIFYPEER (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 deleted file mode 100644 index ef123896b54..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_EC_CURVES 3 "29 Aug 2020" libcurl libcurl -.SH NAME -CURLOPT_SSL_EC_CURVES \- key exchange curves -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_EC_CURVES, char *alg_list); -.fi -.SH DESCRIPTION -Pass a string as parameter with a colon delimited list of (EC) algorithms. This -option defines the client's key exchange algorithms in the SSL handshake (if -the SSL backend libcurl is built to use supports it). -.SH DEFAULT -"", embedded in SSL backend -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSL_EC_CURVES, "X25519:P-521"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.73.0. Supported by the OpenSSL backend. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSL_OPTIONS (3), -.BR CURLOPT_SSL_CIPHER_LIST (3), -.BR CURLOPT_TLS13_CIPHERS (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md new file mode 100644 index 00000000000..adfaae34cd4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md @@ -0,0 +1,61 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_EC_CURVES +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSL_CIPHER_LIST (3) + - CURLOPT_SSL_OPTIONS (3) + - CURLOPT_TLS13_CIPHERS (3) +--- + +# NAME + +CURLOPT_SSL_EC_CURVES - key exchange curves + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_EC_CURVES, char *alg_list); +~~~ + +# DESCRIPTION + +Pass a string as parameter with a colon delimited list of (EC) algorithms. This +option defines the client's key exchange algorithms in the SSL handshake (if +the SSL backend libcurl is built to use supports it). + +# DEFAULT + +"", embedded in SSL backend + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSL_EC_CURVES, "X25519:P-521"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.73.0. Supported by the OpenSSL backend. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 deleted file mode 100644 index 346ca32bf1b..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 +++ /dev/null @@ -1,62 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_ENABLE_ALPN 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_ENABLE_ALPN \- Application Layer Protocol Negotiation -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_ALPN, long npn); -.fi -.SH DESCRIPTION -Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This -option enables/disables ALPN in the SSL handshake (if the SSL backend libcurl -is built to use supports it), which can be used to negotiate http2. -.SH DEFAULT -1, enabled -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_ALPN, 0L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.36.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSL_ENABLE_NPN (3), -.BR CURLOPT_SSL_OPTIONS (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md new file mode 100644 index 00000000000..e1b456a060a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md @@ -0,0 +1,60 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_ENABLE_ALPN +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSL_ENABLE_NPN (3) + - CURLOPT_SSL_OPTIONS (3) +--- + +# NAME + +CURLOPT_SSL_ENABLE_ALPN - Application Layer Protocol Negotiation + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_ALPN, long npn); +~~~ + +# DESCRIPTION + +Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This +option enables/disables ALPN in the SSL handshake (if the SSL backend libcurl +is built to use supports it), which can be used to negotiate http2. + +# DEFAULT + +1, enabled + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_ALPN, 0L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.36.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 deleted file mode 100644 index 69fd82671a5..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 +++ /dev/null @@ -1,64 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_ENABLE_NPN 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_ENABLE_NPN \- use NPN -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_NPN, long npn); -.fi -.SH DESCRIPTION -Deprecated in 7.86.0. Setting this option has no function. - -Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This -option enables/disables NPN in the SSL handshake (if the SSL backend libcurl -is built to use supports it), which can be used to negotiate http2. -.SH DEFAULT -1, enabled -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_NPN, 1L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.36.0. Deprecated in 7.86.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSL_ENABLE_ALPN (3), -.BR CURLOPT_SSL_OPTIONS (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md new file mode 100644 index 00000000000..36221cabdd2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_ENABLE_NPN +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSL_ENABLE_ALPN (3) + - CURLOPT_SSL_OPTIONS (3) +--- + +# NAME + +CURLOPT_SSL_ENABLE_NPN - use NPN + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_NPN, long npn); +~~~ + +# DESCRIPTION + +Deprecated in 7.86.0. Setting this option has no function. + +Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This +option enables/disables NPN in the SSL handshake (if the SSL backend libcurl +is built to use supports it), which can be used to negotiate http2. + +# DEFAULT + +1, enabled + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_NPN, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.36.0. Deprecated in 7.86.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 deleted file mode 100644 index 34d6633fc80..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 +++ /dev/null @@ -1,64 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_FALSESTART 3 "14 Feb 2015" libcurl libcurl -.SH NAME -CURLOPT_SSL_FALSESTART \- TLS false start -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_FALSESTART, long enable); -.fi -.SH DESCRIPTION -Pass a long as parameter set to 1L to enable or 0 to disable. - -This option determines whether libcurl should 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. -.SH DEFAULT -0 -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_SSL_FALSESTART, 1L); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.42.0. This option is currently only supported by the Secure -Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backend. -.SH RETURN VALUE -Returns CURLE_OK if false start is supported by the SSL backend, otherwise -returns CURLE_NOT_BUILT_IN. -.SH SEE ALSO -.BR CURLOPT_TCP_FASTOPEN "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md new file mode 100644 index 00000000000..084728c704f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_FALSESTART +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TCP_FASTOPEN (3) +--- + +# NAME + +CURLOPT_SSL_FALSESTART - TLS false start + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_FALSESTART, long enable); +~~~ + +# DESCRIPTION + +Pass a long as parameter set to 1L to enable or 0 to disable. + +This option determines whether libcurl should 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. + +# DEFAULT + +0 + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_SSL_FALSESTART, 1L); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.42.0. This option is currently only supported by the Secure +Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backend. + +# RETURN VALUE + +Returns CURLE_OK if false start is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. diff --git a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md similarity index 60% rename from docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 rename to docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md index d131ac5d68b..ffc62c33c16 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md @@ -1,65 +1,67 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_OPTIONS 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_OPTIONS \- SSL behavior options -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_OPTIONS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSL_OPTIONS (3) + - CURLOPT_SSLVERSION (3) + - CURLOPT_SSL_CIPHER_LIST (3) +--- + +# NAME + +CURLOPT_SSL_OPTIONS - SSL behavior options + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_OPTIONS, long bitmask); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a long with a bitmask to tell libcurl about specific SSL behaviors. Available bits: -.IP CURLSSLOPT_ALLOW_BEAST + +## CURLSSLOPT_ALLOW_BEAST + Tells libcurl to not attempt to use any workarounds for a security flaw in the -SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, +SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, the SSL layer libcurl uses may use a work-around for this flaw although it might cause interoperability problems with some (older) SSL implementations. WARNING: avoiding this work-around lessens the security, and by setting this -option to 1 you ask for exactly that. This option is only supported for -Secure Transport and OpenSSL. -.IP CURLSSLOPT_NO_REVOKE +option to 1 you ask for exactly that. This option is only supported for Secure +Transport and OpenSSL. + +## CURLSSLOPT_NO_REVOKE + Tells libcurl to disable certificate revocation checks for those SSL backends where such behavior is present. This option is only supported for Schannel (the native Windows SSL library), with an exception in the case of Windows' Untrusted Publishers block list which it seems cannot be bypassed. (Added in 7.44.0) -.IP CURLSSLOPT_NO_PARTIALCHAIN + +## CURLSSLOPT_NO_PARTIALCHAIN + Tells libcurl to not accept "partial" certificate chains, which it otherwise does by default. This option is only supported for OpenSSL and fails the certificate verification if the chain ends with an intermediate certificate and not with a root cert. (Added in 7.68.0) -.IP CURLSSLOPT_REVOKE_BEST_EFFORT + +## CURLSSLOPT_REVOKE_BEST_EFFORT + Tells libcurl to ignore certificate revocation checks in case of missing or offline distribution points for those SSL backends where such behavior is present. This option is only supported for Schannel (the native Windows SSL -library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes +library). If combined with *CURLSSLOPT_NO_REVOKE*, the latter takes precedence. (Added in 7.70.0) -.IP CURLSSLOPT_NATIVE_CA + +## CURLSSLOPT_NATIVE_CA + Tell libcurl to use the operating system's native CA store for certificate verification. If you set this option and also set a CA certificate file or directory then during verification those certificates are searched in addition @@ -68,7 +70,9 @@ to the native CA store. Works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), macOS, Android and iOS (added in 8.3.0), with GnuTLS (added in 8.5.0) or on Windows when built to use OpenSSL (Added in 7.71.0). -.IP CURLSSLOPT_AUTO_CLIENT_CERT + +## CURLSSLOPT_AUTO_CLIENT_CERT + Tell libcurl to automatically locate and use a client certificate for authentication, when requested by the server. This option is only supported for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the @@ -76,12 +80,18 @@ default behavior in libcurl with Schannel. Since the server can request any certificate that supports client authentication in the OS certificate store it could be a privacy violation and unexpected. (Added in 7.77.0) -.SH DEFAULT + +# DEFAULT + 0 -.SH PROTOCOLS + +# PROTOCOLS + All TLS-based protocols -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -95,12 +105,12 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.25.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSL_OPTIONS (3), -.BR CURLOPT_SSL_CIPHER_LIST (3), -.BR CURLOPT_SSLVERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 deleted file mode 100644 index de2839098c3..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 +++ /dev/null @@ -1,67 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_SESSIONID_CACHE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_SESSIONID_CACHE \- use the SSL session-ID cache -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_SESSIONID_CACHE, - long enabled); -.SH DESCRIPTION -Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set -this to 1 to enable it. By default all transfers are done using the cache -enabled. While nothing ever should get hurt by attempting to reuse SSL -session-IDs, there seem to be or have been broken SSL implementations in the -wild that may require you to disable this in order for you to succeed. -.SH DEFAULT -1 -.SH PROTOCOLS -All TLS-based -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* switch off session-id use! */ - curl_easy_setopt(curl, CURLOPT_SSL_SESSIONID_CACHE, 0L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.16.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_DNS_CACHE_TIMEOUT (3), -.BR CURLOPT_MAXAGE_CONN (3), -.BR CURLOPT_MAXLIFETIME_CONN (3), -.BR CURLOPT_SSLVERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md new file mode 100644 index 00000000000..a6b3cf195b9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_SESSIONID_CACHE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DNS_CACHE_TIMEOUT (3) + - CURLOPT_MAXAGE_CONN (3) + - CURLOPT_MAXLIFETIME_CONN (3) + - CURLOPT_SSLVERSION (3) +--- + +# NAME + +CURLOPT_SSL_SESSIONID_CACHE - use the SSL session-ID cache + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_SESSIONID_CACHE, + long enabled); +~~~ + +# DESCRIPTION + +Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set +this to 1 to enable it. By default all transfers are done using the cache +enabled. While nothing ever should get hurt by attempting to reuse SSL +session-IDs, there seem to be or have been broken SSL implementations in the +wild that may require you to disable this in order for you to succeed. + +# DEFAULT + +1 + +# PROTOCOLS + +All TLS-based + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* switch off session-id use! */ + curl_easy_setopt(curl, CURLOPT_SSL_SESSIONID_CACHE, 0L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.16.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md similarity index 53% rename from docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 rename to docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md index 3bdf665de05..742b01b9ac4 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md @@ -1,38 +1,30 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_VERIFYHOST 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_VERIFYHOST \- verify the certificate's name against host -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_VERIFYHOST +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_PINNEDPUBLICKEY (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_SSL_VERIFYHOST - verify the certificate's name against host + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify); -.fi -.SH DESCRIPTION -Pass a long as parameter specifying what to \fIverify\fP. +~~~ + +# DESCRIPTION + +Pass a long as parameter specifying what to *verify*. This option determines whether libcurl verifies that the server cert is for the server it is known as. @@ -40,7 +32,7 @@ the server it is known as. When negotiating TLS and SSL connections, the server sends a certificate indicating its identity. -When \fICURLOPT_SSL_VERIFYHOST(3)\fP is 2, that certificate must indicate that +When CURLOPT_SSL_VERIFYHOST(3) is 2, that certificate must indicate that the server is the server to which you meant to connect, or the connection fails. Simply put, it means it has to have the same name in the certificate as is in the URL you operate against. @@ -49,24 +41,23 @@ Curl considers the server the intended one when the Common Name field or a Subject Alternate Name field in the certificate matches the host name in the URL to which you told Curl to connect. -If \fIverify\fP value is set to 1: +If *verify* value is set to 1: In 7.28.0 and earlier: treated as a debug option of some sorts, not supported anymore due to frequently leading to programmer mistakes. -From 7.28.1 to 7.65.3: setting it to 1 made \fIcurl_easy_setopt(3)\fP return +From 7.28.1 to 7.65.3: setting it to 1 made curl_easy_setopt(3) return an error and leaving the flag untouched. From 7.66.0: treats 1 and 2 the same. -When the \fIverify\fP value is 0, the connection succeeds regardless of the +When the *verify* value is 0, the connection succeeds regardless of the names in the certificate. Use that ability with caution! The default value for this option is 2. This option controls checking the server's certificate's claimed identity. -The server could be lying. To control lying, see -\fICURLOPT_SSL_VERIFYPEER(3)\fP. +The server could be lying. To control lying, see CURLOPT_SSL_VERIFYPEER(3). WARNING: disabling verification of the certificate allows bad guys to man-in-the-middle the communication without you knowing it. Disabling @@ -78,18 +69,26 @@ When libcurl uses secure protocols it trusts responses and allows for example HSTS and Alt-Svc information to be stored and used subsequently. Disabling certificate verification can make libcurl trust and use such information from malicious servers. -.SH LIMITATIONS -Secure Transport: If \fIverify\fP value is 0, then SNI is also disabled. SNI is + +# LIMITATIONS + +Secure Transport: If *verify* value is 0, then SNI is also disabled. SNI is a TLS extension that sends the hostname to the server. The server may use that information to do such things as sending back a specific certificate for the hostname, or forwarding the request to a specific origin server. Some hostnames may be inaccessible if SNI is not sent. -.SH DEFAULT + +# DEFAULT + 2 -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -102,14 +101,14 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + If built TLS enabled. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not. -If 1 is set as argument, \fICURLE_BAD_FUNCTION_ARGUMENT\fP is returned. -.SH "SEE ALSO" -.BR CURLOPT_CAINFO (3), -.BR CURLOPT_PINNEDPUBLICKEY (3), -.BR CURLOPT_SSL_VERIFYPEER (3) +If 1 is set as argument, *CURLE_BAD_FUNCTION_ARGUMENT* is returned. diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md similarity index 53% rename from docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 rename to docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md index a5ec49b0acb..7acadc8e7d4 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md @@ -1,37 +1,32 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_VERIFYPEER 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_VERIFYPEER \- verify the peer's SSL certificate -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_VERIFYPEER +Section: 3 +Source: libcurl +See-also: + - CURLINFO_CAINFO (3) + - CURLINFO_CAPATH (3) + - CURLOPT_CAINFO (3) + - CURLOPT_PROXY_SSL_VERIFYHOST (3) + - CURLOPT_PROXY_SSL_VERIFYPEER (3) + - CURLOPT_SSL_VERIFYHOST (3) +--- + +# NAME + +CURLOPT_SSL_VERIFYPEER - verify the peer's SSL certificate + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYPEER, long verify); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a long as parameter to enable or disable. This option determines whether curl verifies the authenticity of the peer's @@ -43,10 +38,10 @@ i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority (CA) certificates you supply. curl uses a default bundle of CA certificates (the path for that is determined at build time) and you can -specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option or the -\fICURLOPT_CAPATH(3)\fP option. +specify alternate certificates with the CURLOPT_CAINFO(3) option or the +CURLOPT_CAPATH(3) option. -When \fICURLOPT_SSL_VERIFYPEER(3)\fP is enabled, and the verification fails to +When CURLOPT_SSL_VERIFYPEER(3) is enabled, and the verification fails to prove that the certificate is signed by a CA, the connection fails. When this option is disabled (set to zero), the CA certificates are not loaded @@ -54,9 +49,9 @@ and the peer certificate verification is simply skipped. Authenticating the certificate is not enough to be sure about the server. You typically also want to ensure that the server is the server you mean to be -talking to. Use \fICURLOPT_SSL_VERIFYHOST(3)\fP for that. The check that the +talking to. Use CURLOPT_SSL_VERIFYHOST(3) for that. The check that the host name in the certificate is valid for the host name you are connecting to -is done independently of the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. +is done independently of the CURLOPT_SSL_VERIFYPEER(3) option. WARNING: disabling verification of the certificate allows bad guys to man-in-the-middle the communication without you knowing it. Disabling @@ -68,12 +63,18 @@ When libcurl uses secure protocols it trusts responses and allows for example HSTS and Alt-Svc information to be stored and used subsequently. Disabling certificate verification can make libcurl trust and use such information from malicious servers. -.SH DEFAULT + +# DEFAULT + 1 - enabled -.SH PROTOCOLS + +# PROTOCOLS + All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -86,15 +87,12 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + If built TLS enabled. -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_PROXY_SSL_VERIFYPEER (3), -.BR CURLOPT_PROXY_SSL_VERIFYHOST (3), -.BR CURLOPT_CAINFO (3), -.BR CURLINFO_CAINFO (3), -.BR CURLINFO_CAPATH (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 deleted file mode 100644 index 0bfe7da12c4..00000000000 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SSL_VERIFYSTATUS 3 "04 Dec 2014" libcurl libcurl -.SH NAME -CURLOPT_SSL_VERIFYSTATUS \- verify the certificate's status -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYSTATUS, long verify); -.fi -.SH DESCRIPTION -Pass a long as parameter set to 1 to enable or 0 to disable. - -This option determines whether libcurl verifies the status of the server cert -using the "Certificate Status Request" TLS extension (aka. OCSP stapling). - -Note that if this option is enabled but the server does not support the TLS -extension, the verification fails. -.SH DEFAULT -0 -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* ask for OCSP stapling! */ - curl_easy_setopt(curl, CURLOPT_SSL_VERIFYSTATUS, 1L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.41.0. This option is currently only supported by the OpenSSL and -GnuTLS TLS backends. -.SH RETURN VALUE -Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise -returns CURLE_NOT_BUILT_IN. -.SH "SEE ALSO" -.BR CURLOPT_SSL_VERIFYHOST (3), -.BR CURLOPT_SSL_VERIFYPEER (3), -.BR CURLOPT_CAINFO (3) diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md new file mode 100644 index 00000000000..66dbd7465fa --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SSL_VERIFYSTATUS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CAINFO (3) + - CURLOPT_SSL_VERIFYHOST (3) + - CURLOPT_SSL_VERIFYPEER (3) +--- + +# NAME + +CURLOPT_SSL_VERIFYSTATUS - verify the certificate's status + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYSTATUS, long verify); +~~~ + +# DESCRIPTION + +Pass a long as parameter set to 1 to enable or 0 to disable. + +This option determines whether libcurl verifies the status of the server cert +using the "Certificate Status Request" TLS extension (aka. OCSP stapling). + +Note that if this option is enabled but the server does not support the TLS +extension, the verification fails. + +# DEFAULT + +0 + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* ask for OCSP stapling! */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYSTATUS, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.41.0. This option is currently only supported by the OpenSSL and +GnuTLS TLS backends. + +# RETURN VALUE + +Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. diff --git a/docs/libcurl/opts/CURLOPT_STDERR.3 b/docs/libcurl/opts/CURLOPT_STDERR.3 deleted file mode 100644 index 79a97d45c7e..00000000000 --- a/docs/libcurl/opts/CURLOPT_STDERR.3 +++ /dev/null @@ -1,67 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_STDERR 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_STDERR \- redirect stderr to another stream -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STDERR, FILE *stream); -.fi -.SH DESCRIPTION -Pass a FILE * as parameter. Tell libcurl to use this \fIstream\fP instead of -stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE(3)\fP -data. - -If you are using libcurl as a Windows DLL, this option causes an exception and -a crash in the library since it cannot access a FILE * passed on from the -application. A work-around is to instead use \fICURLOPT_DEBUGFUNCTION(3)\fP. -.SH DEFAULT -stderr -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - FILE *filep = fopen("dump", "wb"); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_STDERR, filep); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_VERBOSE (3), -.BR CURLOPT_NOPROGRESS (3), -.BR CURLOPT_DEBUGFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_STDERR.md b/docs/libcurl/opts/CURLOPT_STDERR.md new file mode 100644 index 00000000000..a20e50366d2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_STDERR.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_STDERR +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_NOPROGRESS (3) + - CURLOPT_VERBOSE (3) +--- + +# NAME + +CURLOPT_STDERR - redirect stderr to another stream + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STDERR, FILE *stream); +~~~ + +# DESCRIPTION + +Pass a FILE * as parameter. Tell libcurl to use this *stream* instead of +stderr when showing the progress meter and displaying CURLOPT_VERBOSE(3) +data. + +If you are using libcurl as a Windows DLL, this option causes an exception and +a crash in the library since it cannot access a FILE * passed on from the +application. A work-around is to instead use CURLOPT_DEBUGFUNCTION(3). + +# DEFAULT + +stderr + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + FILE *filep = fopen("dump", "wb"); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_STDERR, filep); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 deleted file mode 100644 index 48276467cc4..00000000000 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 +++ /dev/null @@ -1,79 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_STREAM_DEPENDS 3 "13 Sep 2015" libcurl libcurl -.SH NAME -CURLOPT_STREAM_DEPENDS \- stream this transfer depends on -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS, - CURL *dephandle); -.fi -.SH DESCRIPTION -Pass a CURL * pointer in \fIdephandle\fP to identify the stream within the -same connection that this stream is depending upon. This option clears the -exclusive bit and is mutually exclusive to the -\fICURLOPT_STREAM_DEPENDS_E(3)\fP option. - -The spec says "Including a dependency expresses a preference to allocate -resources to the identified stream rather than to the dependent stream." - -This option can be set during transfer. - -\fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function -return an error. It must be another easy handle, and it also needs to be a -handle of a transfer that is about to be sent over the same HTTP/2 connection -for this option to have an actual effect. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP/2 -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - CURL *curl2 = curl_easy_init(); /* a second handle */ - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); - - /* the second depends on the first */ - curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); - curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS, curl); - - /* then add both to a multi handle and transfer them! */ - } -} -.fi -.SH AVAILABILITY -Added in 7.46.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PIPELINING (3), -.BR CURLOPT_HTTP_VERSION (3), -.BR CURLOPT_STREAM_DEPENDS_E (3), -.BR CURLOPT_STREAM_WEIGHT (3) diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md new file mode 100644 index 00000000000..ba2489a30a0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_STREAM_DEPENDS +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PIPELINING (3) + - CURLOPT_HTTP_VERSION (3) + - CURLOPT_STREAM_DEPENDS_E (3) + - CURLOPT_STREAM_WEIGHT (3) +--- + +# NAME + +CURLOPT_STREAM_DEPENDS - stream this transfer depends on + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS, + CURL *dephandle); +~~~ + +# DESCRIPTION + +Pass a CURL pointer in *dephandle* to identify the stream within the same +connection that this stream is depending upon. This option clears the +exclusive bit and is mutually exclusive to the CURLOPT_STREAM_DEPENDS_E(3) +option. + +The spec says "Including a dependency expresses a preference to allocate +resources to the identified stream rather than to the dependent stream." + +This option can be set during transfer. + +*dephandle* must not be the same as *handle*, that makes this function return +an error. It must be another easy handle, and it also needs to be a handle of +a transfer that is about to be sent over the same HTTP/2 connection for this +option to have an actual effect. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP/2 + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); /* a second handle */ + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); + + /* the second depends on the first */ + curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); + curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS, curl); + + /* then add both to a multi handle and transfer them! */ + } +} +~~~ + +# AVAILABILITY + +Added in 7.46.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 deleted file mode 100644 index c26ba812d3a..00000000000 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_STREAM_DEPENDS_E 3 "13 Sep 2015" libcurl libcurl -.SH NAME -CURLOPT_STREAM_DEPENDS_E \- stream this transfer depends on exclusively -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS_E, - CURL *dephandle); -.fi -.SH DESCRIPTION -Pass a CURL * pointer in \fIdephandle\fP to identify the stream within the -same connection that this stream is depending upon exclusively. That means it -depends on it and sets the Exclusive bit. - -The spec says "Including a dependency expresses a preference to allocate -resources to the identified stream rather than to the dependent stream." - -Setting a dependency with the exclusive flag for a reprioritized stream causes -all the dependencies of the new parent stream to become dependent on the -reprioritized stream. - -This option can be set during transfer. - -\fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function -return an error. It must be another easy handle, and it also needs to be a -handle of a transfer that is about to be sent over the same HTTP/2 connection -for this option to have an actual effect. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP/2 -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - CURL *curl2 = curl_easy_init(); /* a second handle */ - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); - - /* the second depends on the first */ - curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); - curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS_E, curl); - - /* then add both to a multi handle and transfer them! */ - } -} -.fi -.SH AVAILABILITY -Added in 7.46.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PIPELINING (3), -.BR CURLOPT_HTTP_VERSION (3), -.BR CURLOPT_STREAM_DEPENDS (3), -.BR CURLOPT_STREAM_WEIGHT (3) diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md new file mode 100644 index 00000000000..e8dbc113f94 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_STREAM_DEPENDS_E +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PIPELINING (3) + - CURLOPT_HTTP_VERSION (3) + - CURLOPT_STREAM_DEPENDS (3) + - CURLOPT_STREAM_WEIGHT (3) +--- + +# NAME + +CURLOPT_STREAM_DEPENDS_E - stream this transfer depends on exclusively + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS_E, + CURL *dephandle); +~~~ + +# DESCRIPTION + +Pass a CURL pointer in *dephandle* to identify the stream within the same +connection that this stream is depending upon exclusively. That means it +depends on it and sets the Exclusive bit. + +The spec says "Including a dependency expresses a preference to allocate +resources to the identified stream rather than to the dependent stream." + +Setting a dependency with the exclusive flag for a reprioritized stream causes +all the dependencies of the new parent stream to become dependent on the +reprioritized stream. + +This option can be set during transfer. + +*dephandle* must not be the same as *handle*, that makes this function return +an error. It must be another easy handle, and it also needs to be a handle of +a transfer that is about to be sent over the same HTTP/2 connection for this +option to have an actual effect. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP/2 + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); /* a second handle */ + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); + + /* the second depends on the first */ + curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); + curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS_E, curl); + + /* then add both to a multi handle and transfer them! */ + } +} +~~~ + +# AVAILABILITY + +Added in 7.46.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 deleted file mode 100644 index 7534d1d5928..00000000000 --- a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 +++ /dev/null @@ -1,83 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_STREAM_WEIGHT 3 "13 Sep 2015" libcurl libcurl -.SH NAME -CURLOPT_STREAM_WEIGHT \- numerical stream weight -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_WEIGHT, long weight); -.fi -.SH DESCRIPTION -Set the long \fIweight\fP to a number between 1 and 256. - -When using HTTP/2, this option sets the individual weight for this particular -stream used by the easy \fIhandle\fP. Setting and using weights only makes -sense and is only usable when doing multiple streams over the same -connections, which thus implies that you use \fICURLMOPT_PIPELINING(3)\fP. - -This option can be set during transfer and causes the updated weight info get -sent to the server the next time an HTTP/2 frame is sent to the server. - -See section 5.3 of RFC 7540 for protocol details. - -Streams with the same parent should be allocated resources proportionally -based on their weight. So if you have two streams going, stream A with weight -16 and stream B with weight 32, stream B gets two thirds (32/48) of the -available bandwidth (assuming the server can send off the data equally for -both streams). -.SH DEFAULT -If nothing is set, the HTTP/2 protocol itself uses its own default which is -16. -.SH PROTOCOLS -HTTP/2 -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - CURL *curl2 = curl_easy_init(); /* a second handle */ - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); - curl_easy_setopt(curl, CURLOPT_STREAM_WEIGHT, 10L); - - /* the second has twice the weight */ - curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); - curl_easy_setopt(curl2, CURLOPT_STREAM_WEIGHT, 20L); - - /* then add both to a multi handle and transfer them! */ - } -} -.fi -.SH AVAILABILITY -Added in 7.46.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLMOPT_PIPELINING (3), -.BR CURLOPT_PIPEWAIT (3), -.BR CURLOPT_STREAM_DEPENDS (3), -.BR CURLOPT_STREAM_DEPENDS_E (3) diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md new file mode 100644 index 00000000000..3e1e9d5b373 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md @@ -0,0 +1,81 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_STREAM_WEIGHT +Section: 3 +Source: libcurl +See-also: + - CURLMOPT_PIPELINING (3) + - CURLOPT_PIPEWAIT (3) + - CURLOPT_STREAM_DEPENDS (3) + - CURLOPT_STREAM_DEPENDS_E (3) +--- + +# NAME + +CURLOPT_STREAM_WEIGHT - numerical stream weight + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_WEIGHT, long weight); +~~~ + +# DESCRIPTION + +Set the long *weight* to a number between 1 and 256. + +When using HTTP/2, this option sets the individual weight for this particular +stream used by the easy *handle*. Setting and using weights only makes +sense and is only usable when doing multiple streams over the same +connections, which thus implies that you use CURLMOPT_PIPELINING(3). + +This option can be set during transfer and causes the updated weight info get +sent to the server the next time an HTTP/2 frame is sent to the server. + +See section 5.3 of RFC 7540 for protocol details. + +Streams with the same parent should be allocated resources proportionally +based on their weight. So if you have two streams going, stream A with weight +16 and stream B with weight 32, stream B gets two thirds (32/48) of the +available bandwidth (assuming the server can send off the data equally for +both streams). + +# DEFAULT + +If nothing is set, the HTTP/2 protocol itself uses its own default which is +16. + +# PROTOCOLS + +HTTP/2 + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + CURL *curl2 = curl_easy_init(); /* a second handle */ + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); + curl_easy_setopt(curl, CURLOPT_STREAM_WEIGHT, 10L); + + /* the second has twice the weight */ + curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); + curl_easy_setopt(curl2, CURLOPT_STREAM_WEIGHT, 20L); + + /* then add both to a multi handle and transfer them! */ + } +} +~~~ + +# AVAILABILITY + +Added in 7.46.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 deleted file mode 100644 index 15b73917d94..00000000000 --- a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 +++ /dev/null @@ -1,101 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_SUPPRESS_CONNECT_HEADERS 3 "13 February 2017" libcurl libcurl -.SH NAME -CURLOPT_SUPPRESS_CONNECT_HEADERS \- suppress proxy CONNECT response headers from user callbacks -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SUPPRESS_CONNECT_HEADERS, long onoff); -.fi -.SH DESCRIPTION -When \fICURLOPT_HTTPPROXYTUNNEL(3)\fP is used and a CONNECT request is made, -suppress proxy CONNECT response headers from the user callback functions -\fICURLOPT_HEADERFUNCTION(3)\fP and \fICURLOPT_WRITEFUNCTION(3)\fP. - -Proxy CONNECT response headers can complicate header processing since it's -essentially a separate set of headers. You can enable this option to suppress -those headers. - -For example let's assume an HTTPS URL is to be retrieved via CONNECT. On -success there would normally be two sets of headers, and each header line sent -to the header function and/or the write function. The data given to the -callbacks would look like this: - -.nf -HTTP/1.1 200 Connection established -{headers}... - -HTTP/1.1 200 OK -Content-Type: application/json -{headers}... - -{body}... -.fi - -However by enabling this option the CONNECT response headers are suppressed, so -the data given to the callbacks would look like this: - -.nf -HTTP/1.1 200 OK -Content-Type: application/json -{headers}... - -{body}... -.fi - -.SH DEFAULT -0 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - curl_easy_setopt(curl, CURLOPT_HEADER, 1L); - curl_easy_setopt(curl, CURLOPT_PROXY, "http://foo:3128"); - curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); - curl_easy_setopt(curl, CURLOPT_SUPPRESS_CONNECT_HEADERS, 1L); - - curl_easy_perform(curl); - - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.54.0 -.SH RETURN VALUE -CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. -.SH "SEE ALSO" -.BR CURLOPT_HEADER (3), -.BR CURLOPT_PROXY (3), -.BR CURLOPT_HTTPPROXYTUNNEL (3) diff --git a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md new file mode 100644 index 00000000000..19789de297a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md @@ -0,0 +1,103 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_SUPPRESS_CONNECT_HEADERS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADER (3) + - CURLOPT_HTTPPROXYTUNNEL (3) + - CURLOPT_PROXY (3) +--- + +# NAME + +CURLOPT_SUPPRESS_CONNECT_HEADERS - suppress proxy CONNECT response headers + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SUPPRESS_CONNECT_HEADERS, long onoff); +~~~ + +# DESCRIPTION + +When CURLOPT_HTTPPROXYTUNNEL(3) is used and a CONNECT request is made, +suppress proxy CONNECT response headers from the user callback functions +CURLOPT_HEADERFUNCTION(3) and CURLOPT_WRITEFUNCTION(3). + +Proxy CONNECT response headers can complicate header processing since it's +essentially a separate set of headers. You can enable this option to suppress +those headers. + +For example let's assume an HTTPS URL is to be retrieved via CONNECT. On +success there would normally be two sets of headers, and each header line sent +to the header function and/or the write function. The data given to the +callbacks would look like this: + +~~~c +HTTP/1.1 200 Connection established +{headers} +... + +HTTP/1.1 200 OK +Content-Type: application/json +{headers} +... + +{body} +... +~~~ + +However by enabling this option the CONNECT response headers are suppressed, +so the data given to the callbacks would look like this: + +~~~c +HTTP/1.1 200 OK +Content-Type: application/json +{headers} +... + +{body} +... +~~~ + +# DEFAULT + +0 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_HEADER, 1L); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://foo:3128"); + curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); + curl_easy_setopt(curl, CURLOPT_SUPPRESS_CONNECT_HEADERS, 1L); + + curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.54.0 + +# RETURN VALUE + +CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 deleted file mode 100644 index 53e0fc59d5e..00000000000 --- a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TCP_FASTOPEN 3 "16 Feb 2016" libcurl libcurl -.SH NAME -CURLOPT_TCP_FASTOPEN \- TCP Fast Open -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_FASTOPEN, long enable); -.fi -.SH DESCRIPTION -Pass a long as parameter set to 1L to enable or 0 to disable. - -TCP Fast Open (RFC 7413) is a mechanism that allows data to be carried in the -SYN and SYN-ACK packets and consumed by the receiving end during the initial -connection handshake, saving up to one full round-trip time (RTT). - -Beware: the TLS session cache does not work when TCP Fast Open is enabled. TCP -Fast Open is also known to be problematic on or across certain networks. -.SH DEFAULT -0 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.49.0. This option is currently only supported on Linux and macOS -10.11 or later. -.SH RETURN VALUE -Returns CURLE_OK if fast open is supported by the operating system, otherwise -returns CURLE_NOT_BUILT_IN. -.SH SEE ALSO -.BR CURLOPT_SSL_FALSESTART "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md new file mode 100644 index 00000000000..4db103b4b8e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TCP_FASTOPEN +Section: 3 +Source: libcurl +See-also: + - CURLOPT_SSL_FALSESTART (3) +--- + +# NAME + +CURLOPT_TCP_FASTOPEN - TCP Fast Open + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_FASTOPEN, long enable); +~~~ + +# DESCRIPTION + +Pass a long as parameter set to 1L to enable or 0 to disable. + +TCP Fast Open (RFC 7413) is a mechanism that allows data to be carried in the +SYN and SYN-ACK packets and consumed by the receiving end during the initial +connection handshake, saving up to one full round-trip time (RTT). + +Beware: the TLS session cache does not work when TCP Fast Open is enabled. TCP +Fast Open is also known to be problematic on or across certain networks. + +# DEFAULT + +0 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.49.0. This option is currently only supported on Linux and macOS +10.11 or later. + +# RETURN VALUE + +Returns CURLE_OK if fast open is supported by the operating system, otherwise +returns CURLE_NOT_BUILT_IN. diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 deleted file mode 100644 index 04e3ecb58af..00000000000 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TCP_KEEPALIVE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TCP_KEEPALIVE \- TCP keep-alive probing -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPALIVE, long probe); -.fi -.SH DESCRIPTION -Pass a long. If set to 1, TCP keepalive probes are used. The delay and -frequency of these probes can be controlled by the -\fICURLOPT_TCP_KEEPIDLE(3)\fP and \fICURLOPT_TCP_KEEPINTVL(3)\fP options, -provided the operating system supports them. Set to 0 (default behavior) to -disable keepalive probes -.SH DEFAULT -0 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* enable TCP keep-alive for this transfer */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); - - /* keep-alive idle time to 120 seconds */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); - - /* interval time between keep-alive probes: 60 seconds */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.25.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_TCP_KEEPIDLE (3), -.BR CURLOPT_TCP_KEEPINTVL (3), -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_MAX_RECV_SPEED_LARGE (3) diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md new file mode 100644 index 00000000000..09043199320 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TCP_KEEPALIVE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_MAX_RECV_SPEED_LARGE (3) + - CURLOPT_TCP_KEEPIDLE (3) + - CURLOPT_TCP_KEEPINTVL (3) +--- + +# NAME + +CURLOPT_TCP_KEEPALIVE - TCP keep-alive probing + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPALIVE, long probe); +~~~ + +# DESCRIPTION + +Pass a long. If set to 1, TCP keepalive probes are used. The delay and +frequency of these probes can be controlled by the +CURLOPT_TCP_KEEPIDLE(3) and CURLOPT_TCP_KEEPINTVL(3) options, +provided the operating system supports them. Set to 0 (default behavior) to +disable keepalive probes + +# DEFAULT + +0 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.25.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 deleted file mode 100644 index f845b73c569..00000000000 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TCP_KEEPIDLE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TCP_KEEPIDLE \- TCP keep-alive idle time wait -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPIDLE, long delay); -.fi -.SH DESCRIPTION -Pass a long. Sets the \fIdelay\fP, in seconds, to wait while the connection is -idle before sending keepalive probes. Not all operating systems support this -option. - -The maximum value this accepts is 2147483648. Any larger value is capped to -this amount. -.SH DEFAULT -60 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* enable TCP keep-alive for this transfer */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); - - /* set keep-alive idle time to 120 seconds */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); - - /* interval time between keep-alive probes: 60 seconds */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.25.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_TCP_KEEPALIVE (3), -.BR CURLOPT_TCP_KEEPINTVL (3) diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md new file mode 100644 index 00000000000..d8418ffb247 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TCP_KEEPIDLE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TCP_KEEPALIVE (3) + - CURLOPT_TCP_KEEPINTVL (3) +--- + +# NAME + +CURLOPT_TCP_KEEPIDLE - TCP keep-alive idle time wait + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPIDLE, long delay); +~~~ + +# DESCRIPTION + +Pass a long. Sets the *delay*, in seconds, to wait while the connection is +idle before sending keepalive probes. Not all operating systems support this +option. + +The maximum value this accepts is 2147483648. Any larger value is capped to +this amount. + +# DEFAULT + +60 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* set keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.25.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 deleted file mode 100644 index e3bbbc24d9a..00000000000 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TCP_KEEPINTVL 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TCP_KEEPINTVL \- TCP keep-alive interval -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPINTVL, long interval); -.fi -.SH DESCRIPTION -Pass a long. Sets the interval, in seconds, to wait between sending keepalive -probes. Not all operating systems support this option. (Added in 7.25.0) - -The maximum value this accepts is 2147483648. Any larger value is capped to -this amount. -.SH DEFAULT -60 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* enable TCP keep-alive for this transfer */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); - - /* set keep-alive idle time to 120 seconds */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); - - /* interval time between keep-alive probes: 60 seconds */ - curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_TCP_KEEPALIVE (3), -.BR CURLOPT_TCP_KEEPIDLE (3) diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md new file mode 100644 index 00000000000..d560cf51651 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TCP_KEEPINTVL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TCP_KEEPALIVE (3) + - CURLOPT_TCP_KEEPIDLE (3) +--- + +# NAME + +CURLOPT_TCP_KEEPINTVL - TCP keep-alive interval + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPINTVL, long interval); +~~~ + +# DESCRIPTION + +Pass a long. Sets the interval, in seconds, to wait between sending keepalive +probes. Not all operating systems support this option. (Added in 7.25.0) + +The maximum value this accepts is 2147483648. Any larger value is capped to +this amount. + +# DEFAULT + +60 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* set keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 deleted file mode 100644 index 6166f7847c0..00000000000 --- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TCP_NODELAY 3 "30 Jun 2016" libcurl libcurl -.SH NAME -CURLOPT_TCP_NODELAY \- the TCP_NODELAY option -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay); -.fi -.SH DESCRIPTION -Pass a long specifying whether the \fITCP_NODELAY\fP option is to be set or -cleared (1L = set, 0 = clear). The option is set by default. This has no -effect after the connection has been established. - -Setting this option to 1L disables TCP's Nagle algorithm on connections -created using this handle. The purpose of this algorithm is to try to minimize -the number of small packets on the network (where "small packets" means TCP -segments less than the Maximum Segment Size for the network). - -Maximizing the amount of data sent per TCP segment is good because it -amortizes the overhead of the send. However, in some cases small segments may -need to be sent without delay. This is less efficient than sending larger -amounts of data at a time, and can contribute to congestion on the network if -overdone. -.SH DEFAULT -1 -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* leave Nagle enabled */ - curl_easy_setopt(curl, CURLOPT_TCP_NODELAY, 0); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always. The default was changed to 1 from 0 in 7.50.2. -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_BUFFERSIZE (3), -.BR CURLOPT_SOCKOPTFUNCTION (3), -.BR CURLOPT_TCP_KEEPALIVE (3) diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md new file mode 100644 index 00000000000..7fe286d26d1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TCP_NODELAY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_BUFFERSIZE (3) + - CURLOPT_SOCKOPTFUNCTION (3) + - CURLOPT_TCP_KEEPALIVE (3) +--- + +# NAME + +CURLOPT_TCP_NODELAY - the TCP_NODELAY option + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay); +~~~ + +# DESCRIPTION + +Pass a long specifying whether the *TCP_NODELAY* option is to be set or +cleared (1L = set, 0 = clear). The option is set by default. This has no +effect after the connection has been established. + +Setting this option to 1L disables TCP's Nagle algorithm on connections +created using this handle. The purpose of this algorithm is to try to minimize +the number of small packets on the network (where "small packets" means TCP +segments less than the Maximum Segment Size for the network). + +Maximizing the amount of data sent per TCP segment is good because it +amortizes the overhead of the send. However, in some cases small segments may +need to be sent without delay. This is less efficient than sending larger +amounts of data at a time, and can contribute to congestion on the network if +overdone. + +# DEFAULT + +1 + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + /* leave Nagle enabled */ + curl_easy_setopt(curl, CURLOPT_TCP_NODELAY, 0); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always. The default was changed to 1 from 0 in 7.50.2. + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 deleted file mode 100644 index f42e5a42a36..00000000000 --- a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TELNETOPTIONS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TELNETOPTIONS \- set of telnet options -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TELNETOPTIONS, - struct curl_slist *cmds); -.fi -.SH DESCRIPTION -Provide a pointer to a curl_slist with variables to pass to the telnet -negotiations. The variables should be in the format . libcurl -supports the options \fBTTYPE\fP, \fBXDISPLOC\fP and \fBNEW_ENV\fP. See the -TELNET standard for details. -.SH DEFAULT -NULL -.SH PROTOCOLS -TELNET -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - struct curl_slist *options; - options = curl_slist_append(NULL, "TTTYPE=vt100"); - options = curl_slist_append(options, "USER=foobar"); - curl_easy_setopt(curl, CURLOPT_URL, "telnet://example.com/"); - curl_easy_setopt(curl, CURLOPT_TELNETOPTIONS, options); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - curl_slist_free_all(options); - } -} -.fi -.SH AVAILABILITY -Along with TELNET -.SH RETURN VALUE -Returns CURLE_OK if TELNET is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_HTTPHEADER (3), -.BR CURLOPT_QUOTE (3) diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md new file mode 100644 index 00000000000..e1db12ed8d9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TELNETOPTIONS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPHEADER (3) + - CURLOPT_QUOTE (3) +--- + +# NAME + +CURLOPT_TELNETOPTIONS - set of telnet options + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TELNETOPTIONS, + struct curl_slist *cmds); +~~~ + +# DESCRIPTION + +Provide a pointer to a curl_slist with variables to pass to the telnet +negotiations. The variables should be in the format . libcurl +supports the options **TTYPE**, **XDISPLOC** and **NEW_ENV**. See the +TELNET standard for details. + +# DEFAULT + +NULL + +# PROTOCOLS + +TELNET + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + struct curl_slist *options; + options = curl_slist_append(NULL, "TTTYPE=vt100"); + options = curl_slist_append(options, "USER=foobar"); + curl_easy_setopt(curl, CURLOPT_URL, "telnet://example.com/"); + curl_easy_setopt(curl, CURLOPT_TELNETOPTIONS, options); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + curl_slist_free_all(options); + } +} +~~~ + +# AVAILABILITY + +Along with TELNET + +# RETURN VALUE + +Returns CURLE_OK if TELNET is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 deleted file mode 100644 index 3b66a4ce3ae..00000000000 --- a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TFTP_BLKSIZE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TFTP_BLKSIZE \- TFTP block size -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_BLKSIZE, long blocksize); -.fi -.SH DESCRIPTION -Specify \fIblocksize\fP to use for TFTP data transmission. Valid range as per -RFC 2348 is 8-65464 bytes. The default of 512 bytes is used if this option is -not specified. The specified block size is only used if supported by the -remote server. If the server does not return an option acknowledgment or -returns an option acknowledgment with no block size, the default of 512 bytes -is used. -.SH DEFAULT -512 -.SH PROTOCOLS -TFTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/bootimage"); - /* try using larger blocks */ - curl_easy_setopt(curl, CURLOPT_TFTP_BLKSIZE, 2048L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_MAXFILESIZE (3) diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md new file mode 100644 index 00000000000..07cbebae405 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md @@ -0,0 +1,63 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TFTP_BLKSIZE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAXFILESIZE (3) +--- + +# NAME + +CURLOPT_TFTP_BLKSIZE - TFTP block size + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_BLKSIZE, long blocksize); +~~~ + +# DESCRIPTION + +Specify *blocksize* to use for TFTP data transmission. Valid range as per +RFC 2348 is 8-65464 bytes. The default of 512 bytes is used if this option is +not specified. The specified block size is only used if supported by the +remote server. If the server does not return an option acknowledgment or +returns an option acknowledgment with no block size, the default of 512 bytes +is used. + +# DEFAULT + +512 + +# PROTOCOLS + +TFTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/bootimage"); + /* try using larger blocks */ + curl_easy_setopt(curl, CURLOPT_TFTP_BLKSIZE, 2048L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 deleted file mode 100644 index 70d4c3f44a7..00000000000 --- a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TFTP_NO_OPTIONS 3 "23 Feb 2016" libcurl libcurl -.SH NAME -CURLOPT_TFTP_NO_OPTIONS \- send no TFTP options requests -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_NO_OPTIONS, long onoff); -.fi -.SH DESCRIPTION -Set \fIonoff\fP to 1L to exclude all TFTP options defined in RFC 2347, -RFC 2348 and RFC 2349 from read and write requests. - -This option improves interoperability with legacy servers that do not -acknowledge or properly implement TFTP options. When this option is used -\fICURLOPT_TFTP_BLKSIZE(3)\fP is ignored. -.SH DEFAULT -0 -.SH PROTOCOLS -TFTP -.SH EXAMPLE -.nf -size_t write_callback(char *ptr, size_t size, size_t nmemb, void *fp) -{ - return fwrite(ptr, size, nmemb, (FILE *)fp); -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - FILE *fp = fopen("foo.bin", "wb"); - if(fp) { - curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)fp); - curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); - - curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/foo.bin"); - - /* do not send TFTP options requests */ - curl_easy_setopt(curl, CURLOPT_TFTP_NO_OPTIONS, 1L); - - /* Perform the request */ - curl_easy_perform(curl); - - fclose(fp); - } - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.48.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH SEE ALSO -.BR CURLOPT_TFTP_BLKSIZE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md new file mode 100644 index 00000000000..fd4e4921ff2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md @@ -0,0 +1,78 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TFTP_NO_OPTIONS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TFTP_BLKSIZE (3) +--- + +# NAME + +CURLOPT_TFTP_NO_OPTIONS - send no TFTP options requests + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_NO_OPTIONS, long onoff); +~~~ + +# DESCRIPTION + +Set *onoff* to 1L to exclude all TFTP options defined in RFC 2347, +RFC 2348 and RFC 2349 from read and write requests. + +This option improves interoperability with legacy servers that do not +acknowledge or properly implement TFTP options. When this option is used +CURLOPT_TFTP_BLKSIZE(3) is ignored. + +# DEFAULT + +0 + +# PROTOCOLS + +TFTP + +# EXAMPLE + +~~~c +size_t write_callback(char *ptr, size_t size, size_t nmemb, void *fp) +{ + return fwrite(ptr, size, nmemb, (FILE *)fp); +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + FILE *fp = fopen("foo.bin", "wb"); + if(fp) { + curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)fp); + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); + + curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/foo.bin"); + + /* do not send TFTP options requests */ + curl_easy_setopt(curl, CURLOPT_TFTP_NO_OPTIONS, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + + fclose(fp); + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.48.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 b/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 deleted file mode 100644 index 14c901a1690..00000000000 --- a/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 +++ /dev/null @@ -1,74 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TIMECONDITION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TIMECONDITION \- select condition for a time request -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMECONDITION, long cond); -.fi -.SH DESCRIPTION -Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE(3)\fP time -value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP -or \fICURL_TIMECOND_IFUNMODSINCE\fP. - -The last modification time of a file is not always known and in such instances -this feature has no effect even if the given time condition would not have -been met. \fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_CONDITION_UNMET\fP -option can be used after a transfer to learn if a zero-byte successful -"transfer" was due to this condition not matching. -.SH DEFAULT -CURL_TIMECOND_NONE (0) -.SH PROTOCOLS -HTTP, FTP, RTSP, and FILE -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* January 1, 2020 is 1577833200 */ - curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); - - /* If-Modified-Since the above time stamp */ - curl_easy_setopt(curl, CURLOPT_TIMECONDITION, - (long)CURL_TIMECOND_IFMODSINCE); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_TIMEVALUE (3), -.BR CURLINFO_FILETIME (3) diff --git a/docs/libcurl/opts/CURLOPT_TIMECONDITION.md b/docs/libcurl/opts/CURLOPT_TIMECONDITION.md new file mode 100644 index 00000000000..80d93a516ba --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMECONDITION.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TIMECONDITION +Section: 3 +Source: libcurl +See-also: + - CURLINFO_FILETIME (3) + - CURLOPT_TIMEVALUE (3) +--- + +# NAME + +CURLOPT_TIMECONDITION - select condition for a time request + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMECONDITION, long cond); +~~~ + +# DESCRIPTION + +Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE(3) time +value is treated. You can set this parameter to *CURL_TIMECOND_IFMODSINCE* +or *CURL_TIMECOND_IFUNMODSINCE*. + +The last modification time of a file is not always known and in such instances +this feature has no effect even if the given time condition would not have +been met. curl_easy_getinfo(3) with the *CURLINFO_CONDITION_UNMET* +option can be used after a transfer to learn if a zero-byte successful +"transfer" was due to this condition not matching. + +# DEFAULT + +CURL_TIMECOND_NONE (0) + +# PROTOCOLS + +HTTP, FTP, RTSP, and FILE + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* January 1, 2020 is 1577833200 */ + curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); + + /* If-Modified-Since the above time stamp */ + curl_easy_setopt(curl, CURLOPT_TIMECONDITION, + (long)CURL_TIMECOND_IFMODSINCE); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 deleted file mode 100644 index 3d608bab4db..00000000000 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 +++ /dev/null @@ -1,92 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TIMEOUT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TIMEOUT \- maximum time the transfer is allowed to complete -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout); -.fi -.SH DESCRIPTION -Pass a long as parameter containing \fItimeout\fP - the maximum time in -seconds that you allow the entire transfer operation to take. The whole thing, -from start to end. Normally, name lookups can take a considerable time and -limiting operations risk aborting perfectly normal operations. - -\fICURLOPT_TIMEOUT_MS(3)\fP is the same function but set in milliseconds. - -If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the -value set last is used. - -Since this option puts a hard limit on how long time a request is allowed to -take, it has limited use in dynamic use cases with varying transfer -times. That is especially apparent when using the multi interface, which may -queue the transfer, and that time is included. You are advised to explore -\fICURLOPT_LOW_SPEED_LIMIT(3)\fP, \fICURLOPT_LOW_SPEED_TIME(3)\fP or using -\fICURLOPT_PROGRESSFUNCTION(3)\fP to implement your own timeout logic. - -The connection timeout set with \fICURLOPT_CONNECTTIMEOUT(3)\fP is included in -this general all-covering timeout. - -With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 3 and \fICURLOPT_TIMEOUT(3)\fP set -to 5, the operation can never last longer than 5 seconds. - -With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 4 and \fICURLOPT_TIMEOUT(3)\fP set -to 2, the operation can never last longer than 2 seconds. - -This option may cause libcurl to use the SIGALRM signal to timeout system -calls on builds not using asynch DNS. In unix-like systems, this might cause -signals to be used unless \fICURLOPT_NOSIGNAL(3)\fP is set. -.SH DEFAULT -Default timeout is 0 (zero) which means it never times out during transfer. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* complete within 20 seconds */ - curl_easy_setopt(curl, CURLOPT_TIMEOUT, 20L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative -value or a value that when converted to milliseconds is too large. -.SH "SEE ALSO" -.BR CURLOPT_CONNECTTIMEOUT (3), -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_TCP_KEEPALIVE (3), -.BR CURLOPT_TIMEOUT_MS (3) diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_TIMEOUT.md new file mode 100644 index 00000000000..02a3d3dbe45 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.md @@ -0,0 +1,90 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TIMEOUT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT (3) + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_TCP_KEEPALIVE (3) + - CURLOPT_TIMEOUT_MS (3) +--- + +# NAME + +CURLOPT_TIMEOUT - maximum time the transfer is allowed to complete + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout); +~~~ + +# DESCRIPTION + +Pass a long as parameter containing *timeout* - the maximum time in +seconds that you allow the entire transfer operation to take. The whole thing, +from start to end. Normally, name lookups can take a considerable time and +limiting operations risk aborting perfectly normal operations. + +CURLOPT_TIMEOUT_MS(3) is the same function but set in milliseconds. + +If both CURLOPT_TIMEOUT(3) and CURLOPT_TIMEOUT_MS(3) are set, the +value set last is used. + +Since this option puts a hard limit on how long time a request is allowed to +take, it has limited use in dynamic use cases with varying transfer +times. That is especially apparent when using the multi interface, which may +queue the transfer, and that time is included. You are advised to explore +CURLOPT_LOW_SPEED_LIMIT(3), CURLOPT_LOW_SPEED_TIME(3) or using +CURLOPT_PROGRESSFUNCTION(3) to implement your own timeout logic. + +The connection timeout set with CURLOPT_CONNECTTIMEOUT(3) is included in +this general all-covering timeout. + +With CURLOPT_CONNECTTIMEOUT(3) set to 3 and CURLOPT_TIMEOUT(3) set +to 5, the operation can never last longer than 5 seconds. + +With CURLOPT_CONNECTTIMEOUT(3) set to 4 and CURLOPT_TIMEOUT(3) set +to 2, the operation can never last longer than 2 seconds. + +This option may cause libcurl to use the SIGALRM signal to timeout system +calls on builds not using asynch DNS. In unix-like systems, this might cause +signals to be used unless CURLOPT_NOSIGNAL(3) is set. + +# DEFAULT + +Default timeout is 0 (zero) which means it never times out during transfer. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* complete within 20 seconds */ + curl_easy_setopt(curl, CURLOPT_TIMEOUT, 20L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative +value or a value that when converted to milliseconds is too large. diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 deleted file mode 100644 index a829881eb53..00000000000 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 +++ /dev/null @@ -1,66 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TIMEOUT_MS 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TIMEOUT_MS \- maximum time the transfer is allowed to complete -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT_MS, long timeout); -.fi -.SH DESCRIPTION -Pass a long as parameter containing \fItimeout\fP - the maximum time in -milliseconds that you allow the libcurl transfer operation to take. - -See \fICURLOPT_TIMEOUT(3)\fP for details. -.SH DEFAULT -Default timeout is 0 (zero) which means it never times out during transfer. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* complete within 20000 milliseconds */ - curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, 20000L); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_CONNECTTIMEOUT (3), -.BR CURLOPT_LOW_SPEED_LIMIT (3), -.BR CURLOPT_TCP_KEEPALIVE (3), -.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md new file mode 100644 index 00000000000..0bb037f7c17 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md @@ -0,0 +1,64 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TIMEOUT_MS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECTTIMEOUT (3) + - CURLOPT_LOW_SPEED_LIMIT (3) + - CURLOPT_TCP_KEEPALIVE (3) + - CURLOPT_TIMEOUT (3) +--- + +# NAME + +CURLOPT_TIMEOUT_MS - maximum time the transfer is allowed to complete + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT_MS, long timeout); +~~~ + +# DESCRIPTION + +Pass a long as parameter containing *timeout* - the maximum time in +milliseconds that you allow the libcurl transfer operation to take. + +See CURLOPT_TIMEOUT(3) for details. + +# DEFAULT + +Default timeout is 0 (zero) which means it never times out during transfer. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* complete within 20000 milliseconds */ + curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, 20000L); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 b/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 deleted file mode 100644 index cf899e0ca53..00000000000 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TIMEVALUE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TIMEVALUE \- time value for conditional -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE, long val); -.fi -.SH DESCRIPTION -Pass a long \fIval\fP as parameter. This should be the time counted as seconds -since 1 Jan 1970, and the time is used in a condition as specified with -\fICURLOPT_TIMECONDITION(3)\fP. - -On systems with 32 bit 'long' variables (such as Windows), this option cannot -set dates beyond the year 2038. Consider \fICURLOPT_TIMEVALUE_LARGE(3)\fP -instead. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP, FTP, RTSP, and FILE -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* January 1, 2020 is 1577833200 */ - curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); - - /* If-Modified-Since the above time stamp */ - curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_TIMECONDITION (3), -.BR CURLOPT_TIMEVALUE_LARGE (3) diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md new file mode 100644 index 00000000000..cc8f6032c86 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TIMEVALUE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TIMECONDITION (3) + - CURLOPT_TIMEVALUE_LARGE (3) +--- + +# NAME + +CURLOPT_TIMEVALUE - time value for conditional + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE, long val); +~~~ + +# DESCRIPTION + +Pass a long *val* as parameter. This should be the time counted as seconds +since 1 Jan 1970, and the time is used in a condition as specified with +CURLOPT_TIMECONDITION(3). + +On systems with 32 bit 'long' variables (such as Windows), this option cannot +set dates beyond the year 2038. Consider CURLOPT_TIMEVALUE_LARGE(3) +instead. + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP, FTP, RTSP, and FILE + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* January 1, 2020 is 1577833200 */ + curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); + + /* If-Modified-Since the above time stamp */ + curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 deleted file mode 100644 index e3b7759d524..00000000000 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TIMEVALUE_LARGE 3 "25 Jan 2018" libcurl libcurl -.SH NAME -CURLOPT_TIMEVALUE_LARGE \- time value for conditional -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE_LARGE, - curl_off_t val); -.fi -.SH DESCRIPTION -Pass a curl_off_t \fIval\fP as parameter. This should be the time counted as -seconds since 1 Jan 1970, and the time is used in a condition as specified -with \fICURLOPT_TIMECONDITION(3)\fP. - -The difference between this option and \fICURLOPT_TIMEVALUE(3)\fP is the type -of the argument. On systems where 'long' is only 32 bit wide, this option has -to be used to set dates beyond the year 2038. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP, FTP, RTSP, and FILE -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* January 1, 2020 is 1577833200 */ - curl_easy_setopt(curl, CURLOPT_TIMEVALUE_LARGE, (curl_off_t)1577833200); - - /* If-Modified-Since the above time stamp */ - curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.59.0. -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_TIMECONDITION (3), -.BR CURLOPT_TIMEVALUE (3), -.BR CURLINFO_FILETIME (3) diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md new file mode 100644 index 00000000000..1424f6617c9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TIMEVALUE_LARGE +Section: 3 +Source: libcurl +See-also: + - CURLINFO_FILETIME (3) + - CURLOPT_TIMECONDITION (3) + - CURLOPT_TIMEVALUE (3) +--- + +# NAME + +CURLOPT_TIMEVALUE_LARGE - time value for conditional + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE_LARGE, + curl_off_t val); +~~~ + +# DESCRIPTION + +Pass a curl_off_t *val* as parameter. This should be the time counted as +seconds since 1 Jan 1970, and the time is used in a condition as specified +with CURLOPT_TIMECONDITION(3). + +The difference between this option and CURLOPT_TIMEVALUE(3) is the type +of the argument. On systems where 'long' is only 32 bit wide, this option has +to be used to set dates beyond the year 2038. + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP, FTP, RTSP, and FILE + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* January 1, 2020 is 1577833200 */ + curl_easy_setopt(curl, CURLOPT_TIMEVALUE_LARGE, (curl_off_t)1577833200); + + /* If-Modified-Since the above time stamp */ + curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.59.0. + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 deleted file mode 100644 index d7450e15412..00000000000 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 +++ /dev/null @@ -1,81 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TLS13_CIPHERS 3 "25 May 2018" libcurl libcurl -.SH NAME -CURLOPT_TLS13_CIPHERS \- ciphers suites to use for TLS 1.3 -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLS13_CIPHERS, char *list); -.fi -.SH DESCRIPTION -Pass a char *, pointing to a null-terminated string holding the list of cipher -suites to use for the TLS 1.3 connection. The list must be syntactically -correct, it consists of one or more cipher suite strings separated by colons. - -Find more details about cipher lists 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, or Schannel. If you are using a different SSL backend you can try -setting TLS 1.3 cipher suites by using the \fICURLOPT_SSL_CIPHER_LIST(3)\fP -option. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL, use internal default -.SH PROTOCOLS -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_TLS13_CIPHERS, - "TLS_CHACHA20_POLY1305_SHA256"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.61.0 for OpenSSL. Available when built with OpenSSL >= 1.1.1. - -Added in 7.85.0 for Schannel. -.SH RETURN VALUE -Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), -.BR CURLOPT_PROXY_SSLVERSION (3), -.BR CURLOPT_PROXY_TLS13_CIPHERS (3), -.BR CURLOPT_SSL_CIPHER_LIST (3), -.BR CURLOPT_SSLVERSION (3), -.BR CURLOPT_USE_SSL (3) diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md new file mode 100644 index 00000000000..add1f2f8ea5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TLS13_CIPHERS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLVERSION (3) + - CURLOPT_PROXY_SSL_CIPHER_LIST (3) + - CURLOPT_PROXY_TLS13_CIPHERS (3) + - CURLOPT_SSLVERSION (3) + - CURLOPT_SSL_CIPHER_LIST (3) + - CURLOPT_USE_SSL (3) +--- + +# NAME + +CURLOPT_TLS13_CIPHERS - ciphers suites to use for TLS 1.3 + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLS13_CIPHERS, char *list); +~~~ + +# DESCRIPTION + +Pass a char pointer, pointing to a null-terminated string holding the list of +cipher suites to use for the TLS 1.3 connection. The list must be +syntactically correct, it consists of one or more cipher suite strings +separated by colons. + +Find more details about cipher lists 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, or Schannel. If you are using a different SSL backend you can try +setting TLS 1.3 cipher suites by using the CURLOPT_SSL_CIPHER_LIST(3) +option. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL, use internal default + +# PROTOCOLS + +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_TLS13_CIPHERS, + "TLS_CHACHA20_POLY1305_SHA256"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.61.0 for OpenSSL. Available when built with OpenSSL >= 1.1.1. + +Added in 7.85.0 for Schannel. + +# RETURN VALUE + +Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 deleted file mode 100644 index 3170bff2d2f..00000000000 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 +++ /dev/null @@ -1,72 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TLSAUTH_PASSWORD 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TLSAUTH_PASSWORD \- password to use for TLS authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_PASSWORD, char *pwd); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should point to the null-terminated password -to use for the TLS authentication method specified with the -\fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the -\fICURLOPT_TLSAUTH_USERNAME(3)\fP option also be set. - -The application does not have to keep the string around after setting this -option. - -This feature relies in TLS SRP which does not work with TLS 1.3. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS-based protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.21.4, with the OpenSSL and GnuTLS backends only -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), -.BR CURLOPT_TLSAUTH_TYPE (3), -.BR CURLOPT_TLSAUTH_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md new file mode 100644 index 00000000000..1d0e1d01dc5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md @@ -0,0 +1,70 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TLSAUTH_PASSWORD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_TLSAUTH_PASSWORD (3) + - CURLOPT_TLSAUTH_TYPE (3) + - CURLOPT_TLSAUTH_USERNAME (3) +--- + +# NAME + +CURLOPT_TLSAUTH_PASSWORD - password to use for TLS authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_PASSWORD, char *pwd); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should point to the null-terminated +password to use for the TLS authentication method specified with the +CURLOPT_TLSAUTH_TYPE(3) option. Requires that the +CURLOPT_TLSAUTH_USERNAME(3) option also be set. + +The application does not have to keep the string around after setting this +option. + +This feature relies in TLS SRP which does not work with TLS 1.3. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS-based protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.21.4, with the OpenSSL and GnuTLS backends only + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 deleted file mode 100644 index ec743c37216..00000000000 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 +++ /dev/null @@ -1,76 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TLSAUTH_TYPE 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TLSAUTH_TYPE \- TLS authentication methods -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_TYPE, char *type); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. The string should be -the method of the TLS authentication. Supported method is "SRP". - -.IP SRP -TLS-SRP authentication. Secure Remote Password authentication for TLS is -defined in RFC 5054 and provides mutual authentication if both sides have a -shared secret. To use TLS-SRP, you must also set the -\fICURLOPT_TLSAUTH_USERNAME(3)\fP and \fICURLOPT_TLSAUTH_PASSWORD(3)\fP -options. - -The application does not have to keep the string around after setting this -option. - -TLS SRP does not work with TLS 1.3. -.SH DEFAULT -blank -.SH PROTOCOLS -All TLS-based protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this -to work. Added in 7.21.4 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_TLSAUTH_USERNAME (3), -.BR CURLOPT_TLSAUTH_PASSWORD (3) diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md new file mode 100644 index 00000000000..f3e0803d4a5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TLSAUTH_TYPE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TLSAUTH_PASSWORD (3) + - CURLOPT_TLSAUTH_USERNAME (3) +--- + +# NAME + +CURLOPT_TLSAUTH_TYPE - TLS authentication methods + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_TYPE, char *type); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. The string should be +the method of the TLS authentication. Supported method is "SRP". + +## SRP + +TLS-SRP authentication. Secure Remote Password authentication for TLS is +defined in RFC 5054 and provides mutual authentication if both sides have a +shared secret. To use TLS-SRP, you must also set the +CURLOPT_TLSAUTH_USERNAME(3) and CURLOPT_TLSAUTH_PASSWORD(3) +options. + +The application does not have to keep the string around after setting this +option. + +TLS SRP does not work with TLS 1.3. + +# DEFAULT + +blank + +# PROTOCOLS + +All TLS-based protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this +to work. Added in 7.21.4 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 deleted file mode 100644 index a604c1ef0a1..00000000000 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 +++ /dev/null @@ -1,71 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TLSAUTH_USERNAME 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TLSAUTH_USERNAME \- user name to use for TLS authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_USERNAME, char *user); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should point to the null-terminated username -to use for the TLS authentication method specified with the -\fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the -\fICURLOPT_TLSAUTH_PASSWORD(3)\fP option also be set. - -The application does not have to keep the string around after setting this -option. - -This feature relies in TLS SRP which does not work with TLS 1.3. -.SH DEFAULT -NULL -.SH PROTOCOLS -All TLS-based protocols -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); - curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.21.4, with the OpenSSL and GnuTLS backends only -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_TLSAUTH_TYPE (3), -.BR CURLOPT_TLSAUTH_PASSWORD (3) diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md new file mode 100644 index 00000000000..1127046af60 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TLSAUTH_USERNAME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TLSAUTH_PASSWORD (3) + - CURLOPT_TLSAUTH_TYPE (3) +--- + +# NAME + +CURLOPT_TLSAUTH_USERNAME - user name to use for TLS authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_USERNAME, char *user); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should point to the null-terminated +username to use for the TLS authentication method specified with the +CURLOPT_TLSAUTH_TYPE(3) option. Requires that the +CURLOPT_TLSAUTH_PASSWORD(3) option also be set. + +The application does not have to keep the string around after setting this +option. + +This feature relies in TLS SRP which does not work with TLS 1.3. + +# DEFAULT + +NULL + +# PROTOCOLS + +All TLS-based protocols + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); + curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.21.4, with the OpenSSL and GnuTLS backends only + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_TRAILERDATA.3 b/docs/libcurl/opts/CURLOPT_TRAILERDATA.3 deleted file mode 100644 index d355232398f..00000000000 --- a/docs/libcurl/opts/CURLOPT_TRAILERDATA.3 +++ /dev/null @@ -1,63 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TRAILERDATA 3 "14 Aug 2018" libcurl libcurl -.SH NAME -CURLOPT_TRAILERDATA \- pointer passed to trailing headers callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERDATA, void *userdata); -.fi -.SH DESCRIPTION -Data pointer to be passed to the HTTP trailer callback function. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -struct MyData { - void *custom; -}; - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct MyData data; - curl_easy_setopt(curl, CURLOPT_TRAILERDATA, &data); - } -} -.fi - -A more complete example can be found in examples/http_trailers.html -.SH AVAILABILITY -This option was added in curl 7.64.0 and is present if HTTP support is enabled -.SH RETURN VALUE -Returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_TRAILERFUNCTION (3), -.BR CURLOPT_WRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_TRAILERDATA.md b/docs/libcurl/opts/CURLOPT_TRAILERDATA.md new file mode 100644 index 00000000000..304b408e26e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TRAILERDATA.md @@ -0,0 +1,59 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TRAILERDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TRAILERFUNCTION (3) + - CURLOPT_WRITEFUNCTION (3) +--- + +# NAME + +CURLOPT_TRAILERDATA - pointer passed to trailing headers callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERDATA, void *userdata); +~~~ + +# DESCRIPTION + +Data pointer to be passed to the HTTP trailer callback function. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +struct MyData { + void *custom; +}; + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct MyData data; + curl_easy_setopt(curl, CURLOPT_TRAILERDATA, &data); + } +} +~~~ + +# AVAILABILITY + +This option was added in curl 7.64.0 and is present if HTTP support is enabled + +# RETURN VALUE + +Returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 deleted file mode 100644 index 0d61d129103..00000000000 --- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 +++ /dev/null @@ -1,109 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TRAILERFUNCTION 3 "14 Aug 2018" libcurl libcurl -.SH NAME -CURLOPT_TRAILERFUNCTION \- callback for sending trailing headers -.SH SYNOPSIS -.nf -#include - -int curl_trailer_callback(struct curl_slist ** list, void *userdata); - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERFUNCTION, - curl_trailer_callback *func); -.fi -.SH DESCRIPTION -Pass a pointer to a callback function. - -This callback function is called once right before sending the final CR LF in -an HTTP chunked transfer to fill a list of trailing headers to be sent before -finishing the HTTP transfer. - -You can set the userdata argument with the \fICURLOPT_TRAILERDATA(3)\fP -option. - -The trailing headers included in the linked list must not be CRLF-terminated, -because libcurl adds the appropriate line termination characters after each -header item. - -If you use curl_slist_append to add trailing headers to the curl_slist then -libcurl duplicates the strings, and frees the curl_slist and the duplicates -once the trailers have been sent. - -If one of the trailing header fields is not formatted correctly it is ignored -and an info message is emitted. - -The return value can either be \fBCURL_TRAILERFUNC_OK\fP or -\fBCURL_TRAILERFUNC_ABORT\fP which would respectively instruct libcurl to -either continue with sending the trailers or to abort the request. - -If you set this option to NULL, then the transfer proceeds as usual -without any interruptions. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP -.SH EXAMPLE -#include - -static int trailer_cb(struct curl_slist **tr, void *data) -{ - /* libcurl frees the list */ - *tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff"); - return CURL_TRAILERFUNC_OK; -} - -CURL *curl = curl_easy_init(); -if(curl) { - /* Set the URL of the request */ - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* Now set it as a put */ - curl_easy_setopt(curl, CURLOPT_PUT, 1L); - - /* Assuming we have a function that returns the data to be pushed - Let that function be read_cb */ - curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); - - struct curl_slist *headers = NULL; - headers = curl_slist_append(headers, "Trailer: My-super-awesome-trailer"); - res = curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); - - /* Set the trailers filling callback */ - curl_easy_setopt(curl, CURLOPT_TRAILERFUNCTION, trailer_cb); - - /* Perform the transfer */ - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - - curl_slist_free_all(headers); -} -.SH AVAILABILITY -This option was added in curl 7.64.0 and is present if HTTP support is enabled -.SH RETURN VALUE -Returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_TRAILERDATA (3), -.BR CURLOPT_WRITEFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md new file mode 100644 index 00000000000..5d79214bf91 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md @@ -0,0 +1,110 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TRAILERFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TRAILERDATA (3) + - CURLOPT_WRITEFUNCTION (3) +--- + +# NAME + +CURLOPT_TRAILERFUNCTION - callback for sending trailing headers + +# SYNOPSIS + +~~~c +#include + +int curl_trailer_callback(struct curl_slist ** list, void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERFUNCTION, + curl_trailer_callback *func); +~~~ + +# DESCRIPTION + +Pass a pointer to a callback function. + +This callback function is called once right before sending the final CR LF in +an HTTP chunked transfer to fill a list of trailing headers to be sent before +finishing the HTTP transfer. + +You can set the userdata argument with the CURLOPT_TRAILERDATA(3) +option. + +The trailing headers included in the linked list must not be CRLF-terminated, +because libcurl adds the appropriate line termination characters after each +header item. + +If you use curl_slist_append(3) to add trailing headers to the *curl_slist* +then libcurl duplicates the strings, and frees the *curl_slist* once the +trailers have been sent. + +If one of the trailing header fields is not formatted correctly it is ignored +and an info message is emitted. + +The return value can either be **CURL_TRAILERFUNC_OK** or +**CURL_TRAILERFUNC_ABORT** which would respectively instruct libcurl to +either continue with sending the trailers or to abort the request. + +If you set this option to NULL, then the transfer proceeds as usual +without any interruptions. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP + +# EXAMPLE +~~~c +static int trailer_cb(struct curl_slist **tr, void *data) +{ + /* libcurl frees the list */ + *tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff"); + return CURL_TRAILERFUNC_OK; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + + /* Set the URL of the request */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + /* Now set it as a put */ + curl_easy_setopt(curl, CURLOPT_PUT, 1L); + + /* Assuming we have a function that returns the data to be pushed + Let that function be read_cb */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, trailer_cb); + + struct curl_slist *headers = NULL; + headers = curl_slist_append(headers, "Trailer: My-super-awesome-trailer"); + res = curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); + + /* Set the trailers filling callback */ + curl_easy_setopt(curl, CURLOPT_TRAILERFUNCTION, trailer_cb); + + /* Perform the transfer */ + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + + curl_slist_free_all(headers); + } +} +~~~ +# AVAILABILITY + +This option was added in curl 7.64.0 and is present if HTTP support is enabled. + +# RETURN VALUE + +Returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 deleted file mode 100644 index dff01dc8678..00000000000 --- a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 +++ /dev/null @@ -1,67 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TRANSFERTEXT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TRANSFERTEXT \- request a text based transfer for FTP -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFERTEXT, long text); -.fi -.SH DESCRIPTION -A parameter set to 1 tells the library to use ASCII mode for FTP transfers, -instead of the default binary transfer. For win32 systems it does not set the -stdout to binary mode. This option can be usable when transferring text data -between systems with different views on certain characters, such as newlines -or similar. - -libcurl does not do a complete ASCII conversion when doing ASCII transfers -over FTP. This is a known limitation/flaw that nobody has rectified. libcurl -simply sets the mode to ASCII and performs a standard transfer. -.SH DEFAULT -0, disabled -.SH PROTOCOLS -FTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/textfile"); - curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Along with FTP -.SH RETURN VALUE -Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CRLF (3) diff --git a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md new file mode 100644 index 00000000000..4f6d00485d8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md @@ -0,0 +1,65 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TRANSFERTEXT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CRLF (3) +--- + +# NAME + +CURLOPT_TRANSFERTEXT - request a text based transfer for FTP + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFERTEXT, long text); +~~~ + +# DESCRIPTION + +A parameter set to 1 tells the library to use ASCII mode for FTP transfers, +instead of the default binary transfer. For win32 systems it does not set the +stdout to binary mode. This option can be usable when transferring text data +between systems with different views on certain characters, such as newlines +or similar. + +libcurl does not do a complete ASCII conversion when doing ASCII transfers +over FTP. This is a known limitation/flaw that nobody has rectified. libcurl +simply sets the mode to ASCII and performs a standard transfer. + +# DEFAULT + +0, disabled + +# PROTOCOLS + +FTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/textfile"); + curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Along with FTP + +# RETURN VALUE + +Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 deleted file mode 100644 index c472b7a8859..00000000000 --- a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 +++ /dev/null @@ -1,70 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TRANSFER_ENCODING 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TRANSFER_ENCODING \- ask for HTTP Transfer Encoding -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFER_ENCODING, - long enable); -.fi -.SH DESCRIPTION -Pass a long set to 1L to \fIenable\fP or 0 to disable. - -Adds a request for compressed Transfer Encoding in the outgoing HTTP -request. If the server supports this and so desires, it can respond with the -HTTP response sent using a compressed Transfer-Encoding that is automatically -uncompressed by libcurl on reception. - -Transfer-Encoding differs slightly from the Content-Encoding you ask for with -\fICURLOPT_ACCEPT_ENCODING(3)\fP in that a Transfer-Encoding is strictly meant -to be for the transfer and thus MUST be decoded before the data arrives in the -client. Traditionally, Transfer-Encoding has been much less used and supported -by both HTTP clients and HTTP servers. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_TRANSFER_ENCODING, 1L); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.21.6 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_ACCEPT_ENCODING (3), -.BR CURLOPT_HTTP_TRANSFER_DECODING (3) diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md new file mode 100644 index 00000000000..7fd38487ad4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md @@ -0,0 +1,68 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_TRANSFER_ENCODING +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ACCEPT_ENCODING (3) + - CURLOPT_HTTP_TRANSFER_DECODING (3) +--- + +# NAME + +CURLOPT_TRANSFER_ENCODING - ask for HTTP Transfer Encoding + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFER_ENCODING, + long enable); +~~~ + +# DESCRIPTION + +Pass a long set to 1L to *enable* or 0 to disable. + +Adds a request for compressed Transfer Encoding in the outgoing HTTP +request. If the server supports this and so desires, it can respond with the +HTTP response sent using a compressed Transfer-Encoding that is automatically +uncompressed by libcurl on reception. + +Transfer-Encoding differs slightly from the Content-Encoding you ask for with +CURLOPT_ACCEPT_ENCODING(3) in that a Transfer-Encoding is strictly meant +to be for the transfer and thus MUST be decoded before the data arrives in the +client. Traditionally, Transfer-Encoding has been much less used and supported +by both HTTP clients and HTTP servers. + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_TRANSFER_ENCODING, 1L); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.21.6 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 deleted file mode 100644 index 534ae813b97..00000000000 --- a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 +++ /dev/null @@ -1,89 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_UNIX_SOCKET_PATH 3 "09 Oct 2014" libcurl libcurl -.SH NAME -CURLOPT_UNIX_SOCKET_PATH \- Unix domain socket -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNIX_SOCKET_PATH, char *path); -.fi -.SH DESCRIPTION -Enables the use of Unix domain sockets as connection endpoint and sets the -path to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are -disabled. - -When enabled, curl connects to the Unix domain socket instead of establishing -a TCP connection to the host. Since no network connection is created, curl -does not resolve the DNS hostname in the URL. - -The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms -it might be even less. - -Proxy and TCP options such as \fICURLOPT_TCP_NODELAY(3)\fP are not -supported. Proxy options such as \fICURLOPT_PROXY(3)\fP have no effect either -as these are TCP-oriented, and asking a proxy server to connect to a certain -Unix domain socket is not possible. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -Default is NULL, meaning that no Unix domain sockets are used. -.SH PROTOCOLS -All protocols except for FILE and FTP are supported in theory. HTTP, IMAP, -POP3 and SMTP should in particular work (including their SSL/TLS variants). -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_UNIX_SOCKET_PATH, "/tmp/httpd.sock"); - curl_easy_setopt(curl, CURLOPT_URL, "http://localhost/"); - - curl_easy_perform(curl); - } -} -.fi - -If you are on Linux and somehow have a need for paths larger than 107 bytes, -you can use the proc filesystem to bypass the limitation: - -.nf - int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY); - char path[108]; - snprintf(path, sizeof(path), "/proc/self/fd/%d/httpd.sock", dirfd); - curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path); - /* Be sure to keep dirfd valid until you discard the handle */ -.fi -.SH AVAILABILITY -Added in 7.40.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_ABSTRACT_UNIX_SOCKET (3), -.BR CURLOPT_OPENSOCKETFUNCTION (3), -.BR unix (7) diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md new file mode 100644 index 00000000000..0ef3ec17674 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md @@ -0,0 +1,87 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_UNIX_SOCKET_PATH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_ABSTRACT_UNIX_SOCKET (3) + - CURLOPT_OPENSOCKETFUNCTION (3) + - unix (7) +--- + +# NAME + +CURLOPT_UNIX_SOCKET_PATH - Unix domain socket + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNIX_SOCKET_PATH, char *path); +~~~ + +# DESCRIPTION + +Enables the use of Unix domain sockets as connection endpoint and sets the +path to *path*. If *path* is NULL, then Unix domain sockets are +disabled. + +When enabled, curl connects to the Unix domain socket instead of establishing +a TCP connection to the host. Since no network connection is created, curl +does not resolve the DNS hostname in the URL. + +The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms +it might be even less. + +Proxy and TCP options such as CURLOPT_TCP_NODELAY(3) are not +supported. Proxy options such as CURLOPT_PROXY(3) have no effect either +as these are TCP-oriented, and asking a proxy server to connect to a certain +Unix domain socket is not possible. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +Default is NULL, meaning that no Unix domain sockets are used. + +# PROTOCOLS + +All protocols except for FILE and FTP are supported in theory. HTTP, IMAP, +POP3 and SMTP should in particular work (including their SSL/TLS variants). + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_UNIX_SOCKET_PATH, "/tmp/httpd.sock"); + curl_easy_setopt(curl, CURLOPT_URL, "http://localhost/"); + + curl_easy_perform(curl); + } +} +~~~ + +If you are on Linux and somehow have a need for paths larger than 107 bytes, +you can use the proc filesystem to bypass the limitation: + +~~~c + int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY); + char path[108]; + snprintf(path, sizeof(path), "/proc/self/fd/%d/httpd.sock", dirfd); + curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path); + /* Be sure to keep dirfd valid until you discard the handle */ +~~~ + +# AVAILABILITY + +Added in 7.40.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 deleted file mode 100644 index d16f4eab53e..00000000000 --- a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_UNRESTRICTED_AUTH 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_UNRESTRICTED_AUTH \- send credentials to other hosts too -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNRESTRICTED_AUTH, - long goahead); -.SH DESCRIPTION -Set the long \fIgohead\fP parameter to 1L to make libcurl continue to send -authentication (user+password) credentials when following locations, even when -hostname changed. This option is meaningful only when setting -\fICURLOPT_FOLLOWLOCATION(3)\fP. - -Further, when this option is not used or set to \fB0L\fP, libcurl does not -send custom nor internally generated Authentication: headers on requests done -to other hosts than the one used for the initial URL. - -By default, libcurl only sends credentials and Authentication headers to the -initial host name as given in the original URL, to avoid leaking username + -password to other sites. - -This option should be used with caution: when curl follows redirects it -blindly fetches the next URL as instructed by the server. Setting -\fICURLOPT_UNRESTRICTED_AUTH(3)\fP to 1L therefore also makes curl trust the -server and sends possibly sensitive credentials to any host the server points -out. And then maybe again and again as the following hosts can keep -redirecting to new hosts. -.SH DEFAULT -0 -.SH PROTOCOLS -HTTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - curl_easy_setopt(curl, CURLOPT_UNRESTRICTED_AUTH, 1L); - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Along with HTTP -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_FOLLOWLOCATION (3), -.BR CURLOPT_USERPWD (3), -.BR CURLOPT_MAXREDIRS (3), -.BR CURLOPT_REDIR_PROTOCOLS_STR (3), -.BR CURLINFO_REDIRECT_COUNT (3) diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md new file mode 100644 index 00000000000..9dcfbf17565 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md @@ -0,0 +1,79 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_UNRESTRICTED_AUTH +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_COUNT (3) + - CURLOPT_FOLLOWLOCATION (3) + - CURLOPT_MAXREDIRS (3) + - CURLOPT_REDIR_PROTOCOLS_STR (3) + - CURLOPT_USERPWD (3) +--- + +# NAME + +CURLOPT_UNRESTRICTED_AUTH - send credentials to other hosts too + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNRESTRICTED_AUTH, + long goahead); +~~~ + +# DESCRIPTION + +Set the long *gohead* parameter to 1L to make libcurl continue to send +authentication (user+password) credentials when following locations, even when +hostname changed. This option is meaningful only when setting +CURLOPT_FOLLOWLOCATION(3). + +Further, when this option is not used or set to **0L**, libcurl does not +send custom nor internally generated Authentication: headers on requests done +to other hosts than the one used for the initial URL. + +By default, libcurl only sends credentials and Authentication headers to the +initial host name as given in the original URL, to avoid leaking username + +password to other sites. + +This option should be used with caution: when curl follows redirects it +blindly fetches the next URL as instructed by the server. Setting +CURLOPT_UNRESTRICTED_AUTH(3) to 1L therefore also makes curl trust the +server and sends possibly sensitive credentials to any host the server points +out. And then maybe again and again as the following hosts can keep +redirecting to new hosts. + +# DEFAULT + +0 + +# PROTOCOLS + +HTTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + curl_easy_setopt(curl, CURLOPT_UNRESTRICTED_AUTH, 1L); + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Along with HTTP + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 deleted file mode 100644 index 9af2e03ba33..00000000000 --- a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 +++ /dev/null @@ -1,85 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_UPKEEP_INTERVAL_MS 3 "31 Oct 2018" libcurl libcurl -.SH NAME -CURLOPT_UPKEEP_INTERVAL_MS \- connection upkeep interval -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPKEEP_INTERVAL_MS, - long upkeep_interval_ms); -.fi -.SH DESCRIPTION -Some protocols have "connection upkeep" mechanisms. These mechanisms usually -send some traffic on existing connections in order to keep them alive; this -can prevent connections from being closed due to overzealous firewalls, for -example. - -The user needs to explicitly call \fIcurl_easy_upkeep(3)\fP in order to -perform the upkeep work. - -Currently the only protocol with a connection upkeep mechanism is HTTP/2: when -the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP -is called, an HTTP/2 PING frame is sent on the connection. - -.SH DEFAULT -CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds) -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* Make a connection to an HTTP/2 server. */ - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* Set the interval to 30000ms / 30s */ - curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); - - curl_easy_perform(curl); - - /* Perform more work here. */ - - /* While the connection is being held open, curl_easy_upkeep() can be - called. If curl_easy_upkeep() is called and the time since the last - upkeep exceeds the interval, then an HTTP/2 PING is sent. */ - curl_easy_upkeep(curl); - - /* Perform more work here. */ - - /* always cleanup */ - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.62.0 -.SH RETURN VALUE -Returns CURLE_OK -.SH SEE ALSO -.BR CURLOPT_TCP_KEEPALIVE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md new file mode 100644 index 00000000000..283efa73e57 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md @@ -0,0 +1,82 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_UPKEEP_INTERVAL_MS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_TCP_KEEPALIVE (3) +--- + +# NAME + +CURLOPT_UPKEEP_INTERVAL_MS - connection upkeep interval + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPKEEP_INTERVAL_MS, + long upkeep_interval_ms); +~~~ + +# DESCRIPTION + +Some protocols have "connection upkeep" mechanisms. These mechanisms usually +send some traffic on existing connections in order to keep them alive; this +can prevent connections from being closed due to overzealous firewalls, for +example. + +The user needs to explicitly call curl_easy_upkeep(3) in order to +perform the upkeep work. + +Currently the only protocol with a connection upkeep mechanism is HTTP/2: when +the connection upkeep interval is exceeded and curl_easy_upkeep(3) +is called, an HTTP/2 PING frame is sent on the connection. + +# DEFAULT + +CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds) + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* Make a connection to an HTTP/2 server. */ + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the interval to 30000ms / 30s */ + curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); + + curl_easy_perform(curl); + + /* Perform more work here. */ + + /* While the connection is being held open, curl_easy_upkeep() can be + called. If curl_easy_upkeep() is called and the time since the last + upkeep exceeds the interval, then an HTTP/2 PING is sent. */ + curl_easy_upkeep(curl); + + /* Perform more work here. */ + + /* always cleanup */ + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.62.0 + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD.3 b/docs/libcurl/opts/CURLOPT_UPLOAD.3 deleted file mode 100644 index e02295e7038..00000000000 --- a/docs/libcurl/opts/CURLOPT_UPLOAD.3 +++ /dev/null @@ -1,99 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_UPLOAD 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_UPLOAD \- data upload -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD, long upload); -.fi -.SH DESCRIPTION -The long parameter \fIupload\fP set to 1 tells the library to prepare for and -perform an upload. The \fICURLOPT_READDATA(3)\fP and -\fICURLOPT_INFILESIZE(3)\fP or \fICURLOPT_INFILESIZE_LARGE(3)\fP options are -also interesting for uploads. If the protocol is HTTP, uploading means using -the PUT request unless you tell libcurl otherwise. - -Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. -You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. - -If you use PUT to an HTTP 1.1 server, you can upload data without knowing the -size before starting the transfer. The library enables this by adding a header -"Transfer-Encoding: chunked". With HTTP 1.0 or if you prefer not to use chunked -transfer, you must specify the size of the data with -\fICURLOPT_INFILESIZE(3)\fP or \fICURLOPT_INFILESIZE_LARGE(3)\fP. -.SH DEFAULT -0, default is download -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -static size_t read_cb(char *ptr, size_t size, size_t nmemb, void *userdata) -{ - FILE *src = userdata; - /* copy as much data as possible into the 'ptr' buffer, but no more than - 'size' * 'nmemb' bytes! */ - size_t retcode = fread(ptr, size, nmemb, src); - - return retcode; -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - FILE *src = fopen("local-file", "r"); - curl_off_t fsize; /* set this to the size of the input file */ - - /* we want to use our own read function */ - curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); - - /* enable uploading */ - curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); - - /* specify target */ - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); - - /* now specify which pointer to pass to our callback */ - curl_easy_setopt(curl, CURLOPT_READDATA, src); - - /* Set the size of the file to upload */ - curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); - - /* Now run off and do what you have been told! */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_PUT (3), -.BR CURLOPT_READFUNCTION (3), -.BR CURLOPT_INFILESIZE_LARGE (3) diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD.md b/docs/libcurl/opts/CURLOPT_UPLOAD.md new file mode 100644 index 00000000000..a54f2fd9fa7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_UPLOAD.md @@ -0,0 +1,97 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_UPLOAD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_INFILESIZE_LARGE (3) + - CURLOPT_PUT (3) + - CURLOPT_READFUNCTION (3) +--- + +# NAME + +CURLOPT_UPLOAD - data upload + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD, long upload); +~~~ + +# DESCRIPTION + +The long parameter *upload* set to 1 tells the library to prepare for and +perform an upload. The CURLOPT_READDATA(3) and +CURLOPT_INFILESIZE(3) or CURLOPT_INFILESIZE_LARGE(3) options are +also interesting for uploads. If the protocol is HTTP, uploading means using +the PUT request unless you tell libcurl otherwise. + +Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with CURLOPT_HTTPHEADER(3) as usual. + +If you use PUT to an HTTP 1.1 server, you can upload data without knowing the +size before starting the transfer. The library enables this by adding a header +"Transfer-Encoding: chunked". With HTTP 1.0 or if you prefer not to use chunked +transfer, you must specify the size of the data with +CURLOPT_INFILESIZE(3) or CURLOPT_INFILESIZE_LARGE(3). + +# DEFAULT + +0, default is download + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +static size_t read_cb(char *ptr, size_t size, size_t nmemb, void *userdata) +{ + FILE *src = userdata; + /* copy as much data as possible into the 'ptr' buffer, but no more than + 'size' * 'nmemb' bytes */ + size_t retcode = fread(ptr, size, nmemb, src); + + return retcode; +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + FILE *src = fopen("local-file", "r"); + curl_off_t fsize; /* set this to the size of the input file */ + + /* we want to use our own read function */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); + + /* enable uploading */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* specify target */ + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); + + /* now specify which pointer to pass to our callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, src); + + /* Set the size of the file to upload */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); + + /* Now run off and do what you have been told! */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 deleted file mode 100644 index 521daaee132..00000000000 --- a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_UPLOAD_BUFFERSIZE 3 "18 Aug 2018" libcurl libcurl -.SH NAME -CURLOPT_UPLOAD_BUFFERSIZE \- upload buffer size -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD_BUFFERSIZE, long size); -.fi -.SH DESCRIPTION -Pass a long specifying your preferred \fIsize\fP (in bytes) for the upload -buffer in libcurl. It makes libcurl uses a larger buffer that gets passed to -the next layer in the stack to get sent off. In some setups and for some -protocols, there is a huge performance benefit of having a larger upload -buffer. - -This is just treated as a request, not an order. You cannot be guaranteed to -actually get the given size. - -The upload buffer size is by default 64 kilobytes. The maximum buffer size -allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is -16 kilobytes. - -The upload buffer is allocated on-demand - so if the handle is not used for -upload, this buffer is not allocated at all. - -DO NOT set this option on a handle that is currently used for an active -transfer as that may lead to unintended consequences. -.SH DEFAULT -65536 bytes -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin"); - - /* ask libcurl to allocate a larger upload buffer */ - curl_easy_setopt(curl, CURLOPT_UPLOAD_BUFFERSIZE, 120000L); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.62.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_BUFFERSIZE (3), -.BR CURLOPT_READFUNCTION (3), -.BR CURLOPT_TCP_NODELAY (3) diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md new file mode 100644 index 00000000000..f32a45f98b4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_UPLOAD_BUFFERSIZE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_BUFFERSIZE (3) + - CURLOPT_READFUNCTION (3) + - CURLOPT_TCP_NODELAY (3) +--- + +# NAME + +CURLOPT_UPLOAD_BUFFERSIZE - upload buffer size + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD_BUFFERSIZE, long size); +~~~ + +# DESCRIPTION + +Pass a long specifying your preferred *size* (in bytes) for the upload +buffer in libcurl. It makes libcurl uses a larger buffer that gets passed to +the next layer in the stack to get sent off. In some setups and for some +protocols, there is a huge performance benefit of having a larger upload +buffer. + +This is just treated as a request, not an order. You cannot be guaranteed to +actually get the given size. + +The upload buffer size is by default 64 kilobytes. The maximum buffer size +allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is +16 kilobytes. + +The upload buffer is allocated on-demand - so if the handle is not used for +upload, this buffer is not allocated at all. + +DO NOT set this option on a handle that is currently used for an active +transfer as that may lead to unintended consequences. + +# DEFAULT + +65536 bytes + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin"); + + /* ask libcurl to allocate a larger upload buffer */ + curl_easy_setopt(curl, CURLOPT_UPLOAD_BUFFERSIZE, 120000L); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.62.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_URL.3 b/docs/libcurl/opts/CURLOPT_URL.md similarity index 50% rename from docs/libcurl/opts/CURLOPT_URL.3 rename to docs/libcurl/opts/CURLOPT_URL.md index 9ef6913d886..de7bbcf1fe7 100644 --- a/docs/libcurl/opts/CURLOPT_URL.3 +++ b/docs/libcurl/opts/CURLOPT_URL.md @@ -1,39 +1,36 @@ - -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_URL 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_URL \- URL for this transfer -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_URL +Section: 3 +Source: libcurl +See-also: + - CURLINFO_REDIRECT_URL (3) + - CURLOPT_CURLU (3) + - CURLOPT_FORBID_REUSE (3) + - CURLOPT_FRESH_CONNECT (3) + - CURLOPT_PATH_AS_IS (3) + - CURLOPT_PROTOCOLS (3) + - curl_easy_perform (3) + - curl_url_get (3) + - curl_url_set (3) +--- + +# NAME + +CURLOPT_URL - URL for this transfer + +# SYNOPSIS + +~~~c #include CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL); -.fi -.SH DESCRIPTION -Pass in a pointer to the \fIURL\fP to work with. The parameter should be a +~~~ + +# DESCRIPTION + +Pass in a pointer to the *URL* to work with. The parameter should be a char * to a null-terminated string which must be URL-encoded in the following format: @@ -42,39 +39,41 @@ scheme://host:port/path For a greater explanation of the format please see RFC 3986. libcurl does not validate the syntax or use the URL until the transfer is -started. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP might -still return \fICURLE_OK\fP. +started. Even if you set a crazy value here, curl_easy_setopt(3) might +still return *CURLE_OK*. If the given URL is missing a scheme name (such as "http://" or "ftp://" etc) then libcurl guesses based on the host. If the outermost subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol gets used, otherwise HTTP is used. Since 7.45.0 guessing can be disabled by setting a -default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details. +default protocol, see CURLOPT_DEFAULT_PROTOCOL(3) for details. Should the protocol, either as specified by the URL scheme or deduced by libcurl from the host name, not be supported by libcurl then -\fICURLE_UNSUPPORTED_PROTOCOL\fP is returned from either the -\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you -call them. Use \fIcurl_version_info(3)\fP for detailed information of which +*CURLE_UNSUPPORTED_PROTOCOL* is returned from either the +curl_easy_perform(3) or curl_multi_perform(3) functions when you +call them. Use curl_version_info(3) for detailed information of which protocols are supported by the build of libcurl you are using. -\fICURLOPT_PROTOCOLS_STR(3)\fP can be used to limit what protocols libcurl may +CURLOPT_PROTOCOLS_STR(3) can be used to limit what protocols libcurl may use for this transfer, independent of what libcurl has been compiled to support. That may be useful if you accept the URL from an external source and want to limit the accessibility. -The \fICURLOPT_URL(3)\fP string is ignored if \fICURLOPT_CURLU(3)\fP is set. +The CURLOPT_URL(3) string is ignored if CURLOPT_CURLU(3) is set. -Either \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP must be set before a +Either CURLOPT_URL(3) or CURLOPT_CURLU(3) must be set before a transfer is started. The application does not have to keep the string around after setting this option. -The parser used for handling the URL set with \fICURLOPT_URL(3)\fP is the same -that \fIcurl_url_set(3)\fP uses. -.SH ENCODING -The string pointed to in the \fICURLOPT_URL(3)\fP argument is generally +The parser used for handling the URL set with CURLOPT_URL(3) is the same +that curl_url_set(3) uses. + +# ENCODING + +The string pointed to in the CURLOPT_URL(3) argument is generally expected to be a sequence of characters using an ASCII compatible encoding. If libcurl is built with IDN support, the server name part of the URL can use @@ -83,10 +82,14 @@ UTF-8 (when winidn is used; or a Windows Unicode build using libidn2). If libcurl is built without IDN support, the server name is used exactly as specified when passed to the name resolver functions. -.SH DEFAULT + +# DEFAULT + There is no default URL. If this option is not set, no transfer can be performed. -.SH SECURITY CONCERNS + +# SECURITY CONCERNS + Applications may at times find it convenient to allow users to specify URLs for various purposes and that string would then end up fed to this option. @@ -104,15 +107,19 @@ custom port number can allow external users to play tricks with your local services. Accepting external URLs may also use other protocols than http:// or other -common ones. Restrict what accept with \fICURLOPT_PROTOCOLS(3)\fP. +common ones. Restrict what accept with CURLOPT_PROTOCOLS(3). User provided URLs can also be made to point to sites that redirect further on (possibly to other protocols too). Consider your -\fICURLOPT_FOLLOWLOCATION(3)\fP and \fICURLOPT_REDIR_PROTOCOLS(3)\fP settings. -.SH PROTOCOLS +CURLOPT_FOLLOWLOCATION(3) and CURLOPT_REDIR_PROTOCOLS(3) settings. + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURL *curl = curl_easy_init(); @@ -122,23 +129,17 @@ int main(void) curl_easy_perform(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + POP3 and SMTP were added in 7.31.0 -.SH RETURN VALUE + +# RETURN VALUE + Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -Note that \fIcurl_easy_setopt(3)\fP does not parse the given string so given a -bad URL, it is not detected until \fIcurl_easy_perform(3)\fP or similar is +Note that curl_easy_setopt(3) does not parse the given string so given a +bad URL, it is not detected until curl_easy_perform(3) or similar is called. -.SH "SEE ALSO" -.BR curl_easy_perform (3), -.BR curl_url_get (3), -.BR curl_url_set (3), -.BR CURLINFO_REDIRECT_URL (3), -.BR CURLOPT_CURLU (3), -.BR CURLOPT_FORBID_REUSE (3), -.BR CURLOPT_FRESH_CONNECT (3), -.BR CURLOPT_PATH_AS_IS (3), -.BR CURLOPT_PROTOCOLS (3) diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.3 b/docs/libcurl/opts/CURLOPT_USERAGENT.3 deleted file mode 100644 index 1ed5a7bc5f6..00000000000 --- a/docs/libcurl/opts/CURLOPT_USERAGENT.3 +++ /dev/null @@ -1,68 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_USERAGENT 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_USERAGENT \- HTTP user-agent header -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERAGENT, char *ua); -.fi -.SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It is used to set the -User-Agent: header field in the HTTP request sent to the remote server. You -can also set any custom header with \fICURLOPT_HTTPHEADER(3)\fP. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL, no User-Agent: header is used by default. -.SH PROTOCOLS -HTTP, HTTPS -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - curl_easy_setopt(curl, CURLOPT_USERAGENT, "Dark Secret Ninja/1.0"); - - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -As long as HTTP is supported -.SH RETURN VALUE -Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_CUSTOMREQUEST (3), -.BR CURLOPT_HTTPHEADER (3), -.BR CURLOPT_REFERER (3), -.BR CURLOPT_REQUEST_TARGET (3) diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.md b/docs/libcurl/opts/CURLOPT_USERAGENT.md new file mode 100644 index 00000000000..a5423def023 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USERAGENT.md @@ -0,0 +1,66 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_USERAGENT +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CUSTOMREQUEST (3) + - CURLOPT_HTTPHEADER (3) + - CURLOPT_REFERER (3) + - CURLOPT_REQUEST_TARGET (3) +--- + +# NAME + +CURLOPT_USERAGENT - HTTP user-agent header + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERAGENT, char *ua); +~~~ + +# DESCRIPTION + +Pass a pointer to a null-terminated string as parameter. It is used to set the +User-Agent: header field in the HTTP request sent to the remote server. You +can also set any custom header with CURLOPT_HTTPHEADER(3). + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL, no User-Agent: header is used by default. + +# PROTOCOLS + +HTTP, HTTPS + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + curl_easy_setopt(curl, CURLOPT_USERAGENT, "Dark Secret Ninja/1.0"); + + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +As long as HTTP is supported + +# RETURN VALUE + +Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_USERNAME.3 b/docs/libcurl/opts/CURLOPT_USERNAME.3 deleted file mode 100644 index a7e25e90b15..00000000000 --- a/docs/libcurl/opts/CURLOPT_USERNAME.3 +++ /dev/null @@ -1,93 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_USERNAME 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_USERNAME \- user name to use in authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERNAME, - char *username); -.SH DESCRIPTION -Pass a char * as parameter, which should be pointing to the null-terminated -user name to use for the transfer. - -\fICURLOPT_USERNAME(3)\fP sets the user name to be used in protocol -authentication. You should not use this option together with the (older) -\fICURLOPT_USERPWD(3)\fP option. - -When using Kerberos V5 authentication with a Windows based server, you should -include the domain name in order for the server to successfully obtain a -Kerberos Ticket. If you do not then the initial part of the authentication -handshake may fail. - -When using NTLM, the user name can be specified simply as the user name -without the domain name should the server be part of a single domain and -forest. - -To include the domain name use either Down-Level Logon Name or UPN (User -Principal Name) formats. For example, EXAMPLE\\user and user@example.com -respectively. - -Some HTTP servers (on Windows) support inclusion of the domain for Basic -authentication as well. - -To specify the password and login options, along with the user name, use the -\fICURLOPT_PASSWORD(3)\fP and \fICURLOPT_LOGIN_OPTIONS(3)\fP options. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -blank -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - curl_easy_setopt(curl, CURLOPT_USERNAME, "clark"); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.19.1 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_USERPWD (3), -.BR CURLOPT_PASSWORD (3), -.BR CURLOPT_HTTPAUTH (3), -.BR CURLOPT_PROXYAUTH (3) diff --git a/docs/libcurl/opts/CURLOPT_USERNAME.md b/docs/libcurl/opts/CURLOPT_USERNAME.md new file mode 100644 index 00000000000..f7481780197 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USERNAME.md @@ -0,0 +1,92 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_USERNAME +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HTTPAUTH (3) + - CURLOPT_PASSWORD (3) + - CURLOPT_PROXYAUTH (3) + - CURLOPT_USERPWD (3) +--- + +# NAME + +CURLOPT_USERNAME - user name to use in authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERNAME, + char *username); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should be pointing to the +null-terminated user name to use for the transfer. + +CURLOPT_USERNAME(3) sets the user name to be used in protocol +authentication. You should not use this option together with the (older) +CURLOPT_USERPWD(3) option. + +When using Kerberos V5 authentication with a Windows based server, you should +include the domain name in order for the server to successfully obtain a +Kerberos Ticket. If you do not then the initial part of the authentication +handshake may fail. + +When using NTLM, the user name can be specified simply as the user name +without the domain name should the server be part of a single domain and +forest. + +To include the domain name use either Down-Level Logon Name or UPN (User +Principal Name) formats. For example, **EXAMPLE\user** and +**user@example.com** respectively. + +Some HTTP servers (on Windows) support inclusion of the domain for Basic +authentication as well. + +To specify the password and login options, along with the user name, use the +CURLOPT_PASSWORD(3) and CURLOPT_LOGIN_OPTIONS(3) options. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +blank + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_USERNAME, "clark"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.19.1 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.3 b/docs/libcurl/opts/CURLOPT_USERPWD.3 deleted file mode 100644 index c63a98cc1d7..00000000000 --- a/docs/libcurl/opts/CURLOPT_USERPWD.3 +++ /dev/null @@ -1,100 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_USERPWD 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_USERPWD \- user name and password to use in authentication -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERPWD, char *userpwd); -.fi -.SH DESCRIPTION -Pass a char * as parameter, pointing to a null-terminated login details string -for the connection. The format of which is: [user name]:[password]. - -When using Kerberos V5 authentication with a Windows based server, you should -specify the user name part with the domain name in order for the server to -successfully obtain a Kerberos Ticket. If you do not then the initial part of -the authentication handshake may fail. - -When using NTLM, the user name can be specified simply as the user name -without the domain name should the server be part of a single domain and -forest. - -To specify the domain name use either Down-Level Logon Name or UPN (User -Principal Name) formats. For example, EXAMPLE\\user and user@example.com -respectively. - -Some HTTP servers (on Windows) support inclusion of the domain for Basic -authentication as well. - -When using HTTP and \fICURLOPT_FOLLOWLOCATION(3)\fP, libcurl might perform -several requests to possibly different hosts. libcurl only sends this user and -password information to hosts using the initial host name (unless -\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows redirects to -other hosts, it does not send the user and password to those. This is enforced -to prevent accidental information leakage. - -Use \fICURLOPT_HTTPAUTH(3)\fP to specify the authentication method for HTTP -based connections or \fICURLOPT_LOGIN_OPTIONS(3)\fP to control IMAP, POP3 and -SMTP options. - -The user and password strings are not URL decoded, so there is no way to send -in a user name containing a colon using this option. Use -\fICURLOPT_USERNAME(3)\fP for that, or include it in the URL. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -Most -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - - curl_easy_setopt(curl, CURLOPT_USERPWD, "clark:kent"); - - res = curl_easy_perform(curl); - - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK on success or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_USERNAME (3), -.BR CURLOPT_PASSWORD (3), -.BR CURLOPT_PROXYUSERPWD (3) diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.md b/docs/libcurl/opts/CURLOPT_USERPWD.md new file mode 100644 index 00000000000..262529055c9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USERPWD.md @@ -0,0 +1,98 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_USERPWD +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PASSWORD (3) + - CURLOPT_PROXYUSERPWD (3) + - CURLOPT_USERNAME (3) +--- + +# NAME + +CURLOPT_USERPWD - user name and password to use in authentication + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERPWD, char *userpwd); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, pointing to a null-terminated login details +string for the connection. The format of which is: [user name]:[password]. + +When using Kerberos V5 authentication with a Windows based server, you should +specify the user name part with the domain name in order for the server to +successfully obtain a Kerberos Ticket. If you do not then the initial part of +the authentication handshake may fail. + +When using NTLM, the user name can be specified simply as the user name +without the domain name should the server be part of a single domain and +forest. + +To specify the domain name use either Down-Level Logon Name or UPN (User +Principal Name) formats. For example **EXAMPLE\user** and **user@example.com** +respectively. + +Some HTTP servers (on Windows) support inclusion of the domain for Basic +authentication as well. + +When using HTTP and CURLOPT_FOLLOWLOCATION(3), libcurl might perform +several requests to possibly different hosts. libcurl only sends this user and +password information to hosts using the initial host name (unless +CURLOPT_UNRESTRICTED_AUTH(3) is set), so if libcurl follows redirects to +other hosts, it does not send the user and password to those. This is enforced +to prevent accidental information leakage. + +Use CURLOPT_HTTPAUTH(3) to specify the authentication method for HTTP +based connections or CURLOPT_LOGIN_OPTIONS(3) to control IMAP, POP3 and +SMTP options. + +The user and password strings are not URL decoded, so there is no way to send +in a user name containing a colon using this option. Use +CURLOPT_USERNAME(3) for that, or include it in the URL. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +Most + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); + + curl_easy_setopt(curl, CURLOPT_USERPWD, "clark:kent"); + + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_USE_SSL.3 b/docs/libcurl/opts/CURLOPT_USE_SSL.3 deleted file mode 100644 index 837415ad759..00000000000 --- a/docs/libcurl/opts/CURLOPT_USE_SSL.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_USE_SSL 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_USE_SSL \- request using SSL / TLS for the transfer -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USE_SSL, long level); -.fi -.SH DESCRIPTION -Pass a long using one of the values from below, to make libcurl use your -desired \fIlevel\fP of SSL for the transfer. - -These are all protocols that start out plain text and get "upgraded" to SSL -using the STARTTLS command. - -This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. -.IP CURLUSESSL_NONE -do not attempt to use SSL. -.IP CURLUSESSL_TRY -Try using SSL, proceed as normal otherwise. Note that server may close the -connection if the negotiation does not succeed. -.IP CURLUSESSL_CONTROL -Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. -.IP CURLUSESSL_ALL -Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. -.SH DEFAULT -CURLUSESSL_NONE -.SH PROTOCOLS -FTP, SMTP, POP3, IMAP, LDAP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/file.ext"); - - /* require use of SSL for this, or fail */ - curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.11.0. This option was known as CURLOPT_FTP_SSL up to 7.16.4, and -the constants were known as CURLFTPSSL_* -Handled by LDAP since 7.81.0. Fully supported by the OpenLDAP backend only. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_SSLVERSION (3), -.BR CURLOPT_PROXY_SSLVERSION (3), -.BR CURLOPT_SSL_OPTIONS (3) diff --git a/docs/libcurl/opts/CURLOPT_USE_SSL.md b/docs/libcurl/opts/CURLOPT_USE_SSL.md new file mode 100644 index 00000000000..3e227fcfd88 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USE_SSL.md @@ -0,0 +1,86 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_USE_SSL +Section: 3 +Source: libcurl +See-also: + - CURLOPT_PROXY_SSLVERSION (3) + - CURLOPT_SSLVERSION (3) + - CURLOPT_SSL_OPTIONS (3) +--- + +# NAME + +CURLOPT_USE_SSL - request using SSL / TLS for the transfer + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USE_SSL, long level); +~~~ + +# DESCRIPTION + +Pass a long using one of the values from below, to make libcurl use your +desired *level* of SSL for the transfer. + +These are all protocols that start out plain text and get "upgraded" to SSL +using the STARTTLS command. + +This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. + +## CURLUSESSL_NONE + +do not attempt to use SSL. + +## CURLUSESSL_TRY + +Try using SSL, proceed as normal otherwise. Note that server may close the +connection if the negotiation does not succeed. + +## CURLUSESSL_CONTROL + +Require SSL for the control connection or fail with *CURLE_USE_SSL_FAILED*. + +## CURLUSESSL_ALL + +Require SSL for all communication or fail with *CURLE_USE_SSL_FAILED*. + +# DEFAULT + +CURLUSESSL_NONE + +# PROTOCOLS + +FTP, SMTP, POP3, IMAP, LDAP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/file.ext"); + + /* require use of SSL for this, or fail */ + curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.11.0. This option was known as CURLOPT_FTP_SSL up to 7.16.4, and +the constants were known as CURLFTPSSL_* +Handled by LDAP since 7.81.0. Fully supported by the OpenLDAP backend only. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.3 b/docs/libcurl/opts/CURLOPT_VERBOSE.3 deleted file mode 100644 index db1a756a3ad..00000000000 --- a/docs/libcurl/opts/CURLOPT_VERBOSE.3 +++ /dev/null @@ -1,73 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_VERBOSE 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_VERBOSE \- verbose mode -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_VERBOSE, long onoff); -.fi -.SH DESCRIPTION -Set the \fIonoff\fP parameter to 1 to make the library display a lot of -verbose information about its operations on this \fIhandle\fP. Useful for -libcurl and/or protocol debugging and understanding. The verbose information -is sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP. - -You hardly ever want this enabled in production use, you almost always want -this used when you debug/report problems. - -To also get all the protocol data sent and received, consider using the -\fICURLOPT_DEBUGFUNCTION(3)\fP. -.SH DEFAULT -0, meaning disabled. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - - /* ask libcurl to show us the verbose output */ - curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); - - /* Perform the request */ - curl_easy_perform(curl); - } -} -.fi -.SH AVAILABILITY -Always -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_STDERR (3), -.BR CURLOPT_DEBUGFUNCTION (3), -.BR CURLOPT_ERRORBUFFER (3), -.BR curl_global_trace (3) diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.md b/docs/libcurl/opts/CURLOPT_VERBOSE.md new file mode 100644 index 00000000000..5ecc4b11aa5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_VERBOSE.md @@ -0,0 +1,71 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_VERBOSE +Section: 3 +Source: libcurl +See-also: + - CURLOPT_DEBUGFUNCTION (3) + - CURLOPT_ERRORBUFFER (3) + - CURLOPT_STDERR (3) + - curl_global_trace (3) +--- + +# NAME + +CURLOPT_VERBOSE - verbose mode + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_VERBOSE, long onoff); +~~~ + +# DESCRIPTION + +Set the *onoff* parameter to 1 to make the library display a lot of +verbose information about its operations on this *handle*. Useful for +libcurl and/or protocol debugging and understanding. The verbose information +is sent to stderr, or the stream set with CURLOPT_STDERR(3). + +You hardly ever want this enabled in production use, you almost always want +this used when you debug/report problems. + +To also get all the protocol data sent and received, consider using the +CURLOPT_DEBUGFUNCTION(3). + +# DEFAULT + +0, meaning disabled. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* ask libcurl to show us the verbose output */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* Perform the request */ + curl_easy_perform(curl); + } +} +~~~ + +# AVAILABILITY + +Always + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 deleted file mode 100644 index 75c5322f115..00000000000 --- a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 +++ /dev/null @@ -1,118 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_WILDCARDMATCH 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_WILDCARDMATCH \- directory wildcard transfers -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WILDCARDMATCH, long onoff); -.fi -.SH DESCRIPTION -Set \fIonoff\fP to 1 if you want to transfer multiple files according to a -file name pattern. The pattern can be specified as part of the -\fICURLOPT_URL(3)\fP option, using an \fBfnmatch\fP-like pattern (Shell -Pattern Matching) in the last part of URL (file name). - -By default, libcurl uses its internal wildcard matching implementation. You -can provide your own matching function by the -\fICURLOPT_FNMATCH_FUNCTION(3)\fP option. - -A brief introduction of its syntax follows: -.RS -.IP "* - ASTERISK" -.nf - ftp://example.com/some/path/*.txt -.fi -for all txt's from the root directory. Only two asterisks are allowed within -the same pattern string. -.RE -.RS -.IP "? - QUESTION MARK" -Question mark matches any (exactly one) character. -.nf - ftp://example.com/some/path/photo?.jpg -.fi -.RE -.RS -.IP "[ - BRACKET EXPRESSION" -The left bracket opens a bracket expression. The question mark and asterisk have -no special meaning in a bracket expression. Each bracket expression ends by the -right bracket and matches exactly one character. Some examples follow: - -\fB[a-zA-Z0\-9]\fP or \fB[f\-gF\-G]\fP \- character interval - -\fB[abc]\fP - character enumeration - -\fB[^abc]\fP or \fB[!abc]\fP - negation - -\fB[[:name:]]\fP class expression. Supported classes are -\fBalnum\fP,\fBlower\fP, \fBspace\fP, \fBalpha\fP, \fBdigit\fP, \fBprint\fP, -\fBupper\fP, \fBblank\fP, \fBgraph\fP, \fBxdigit\fP. - -\fB[][-!^]\fP - special case \- matches only '\-', ']', '[', '!' or '^'. These -characters have no special purpose. - -\fB[\\[\\]\\\\]\fP - escape syntax. Matches '[', ']' or '\e'. - -Using the rules above, a file name pattern can be constructed: -.nf - ftp://example.com/some/path/[a-z[:upper:]\\\\].jpg -.fi -.SH PROTOCOLS -This feature is only supported for FTP download. -.SH EXAMPLE -.nf - -extern long begin_cb(struct curl_fileinfo *, void *, int); -extern long end_cb(void *ptr); - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - /* turn on wildcard matching */ - curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); - - /* callback is called before download of concrete file started */ - curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, begin_cb); - - /* callback is called after data from the file have been transferred */ - curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, end_cb); - - /* See more on https://curl.se/libcurl/c/ftp-wildcard.html */ - } -} -.fi -.SH AVAILABILITY -Added in 7.21.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_CHUNK_BGN_FUNCTION (3), -.BR CURLOPT_CHUNK_END_FUNCTION (3), -.BR CURLOPT_FNMATCH_FUNCTION (3), -.BR CURLOPT_URL (3) diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md new file mode 100644 index 00000000000..4c8939bc666 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md @@ -0,0 +1,115 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_WILDCARDMATCH +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CHUNK_BGN_FUNCTION (3) + - CURLOPT_CHUNK_END_FUNCTION (3) + - CURLOPT_FNMATCH_FUNCTION (3) + - CURLOPT_URL (3) +--- + +# NAME + +CURLOPT_WILDCARDMATCH - directory wildcard transfers + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WILDCARDMATCH, long onoff); +~~~ + +# DESCRIPTION + +Set *onoff* to 1 if you want to transfer multiple files according to a +file name pattern. The pattern can be specified as part of the +CURLOPT_URL(3) option, using an **fnmatch**-like pattern (Shell +Pattern Matching) in the last part of URL (file name). + +By default, libcurl uses its internal wildcard matching implementation. You +can provide your own matching function by the +CURLOPT_FNMATCH_FUNCTION(3) option. + +A brief introduction of its syntax follows: + +## * - ASTERISK + +~~~c + ftp://example.com/some/path/*.txt +~~~ +for all txt's from the root directory. Only two asterisks are allowed within +the same pattern string. + +## ? - QUESTION MARK + +Question mark matches any (exactly one) character. +~~~c + ftp://example.com/some/path/photo?.jpg +~~~ + +## [ - BRACKET EXPRESSION + +The left bracket opens a bracket expression. The question mark and asterisk have +no special meaning in a bracket expression. Each bracket expression ends by the +right bracket and matches exactly one character. Some examples follow: + +**[a-zA-Z0-9]** or **[f-gF-G]** - character interval + +**[abc]** - character enumeration + +**[^abc]** or **[!abc]** - negation + +**[[:name:]]** class expression. Supported classes are +**alnum**,**lower**, **space**, **alpha**, **digit**, **print**, +**upper**, **blank**, **graph**, **xdigit**. + +**[][-!^]** - special case - matches only '-', ']', '[', '!' or '^'. These +characters have no special purpose. + +**[[]]** - escape syntax. Matches '[', ']' or 'e'. + +Using the rules above, a file name pattern can be constructed: +~~~c + ftp://example.com/some/path/[a-z[:upper:]\\].jpg +~~~ + +# PROTOCOLS + +This feature is only supported for FTP download. + +# EXAMPLE + +~~~c + +extern long begin_cb(struct curl_fileinfo *, void *, int); +extern long end_cb(void *ptr); + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + /* turn on wildcard matching */ + curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); + + /* callback is called before download of concrete file started */ + curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, begin_cb); + + /* callback is called after data from the file have been transferred */ + curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, end_cb); + + /* See more on https://curl.se/libcurl/c/ftp-wildcard.html */ + } +} +~~~ + +# AVAILABILITY + +Added in 7.21.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 deleted file mode 100644 index 6dc0995068e..00000000000 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_WRITEDATA 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_WRITEDATA \- pointer passed to the write callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer); -.fi -.SH DESCRIPTION -A data \fIpointer\fP to pass to the write callback. If you use the -\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you get in that -callback's fourth and last argument. If you do not use a write callback, you -must make \fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl passes this -to \fIfwrite(3)\fP when writing data. - -The internal \fICURLOPT_WRITEFUNCTION(3)\fP writes the data to the FILE * -given with this option, or to stdout if this option has not been set. - -If you are using libcurl as a Windows DLL, you \fBMUST\fP use a -\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you might experience -crashes. -.SH DEFAULT -By default, this is a FILE * to stdout. -.SH PROTOCOLS -Used for all protocols. -.SH EXAMPLE -A common technique is to use the write callback to store the incoming data -into a dynamically growing allocated buffer, and then this -\fICURLOPT_WRITEDATA(3)\fP is used to point to a struct or the buffer to store -data in. Like in the getinmemory example: -https://curl.se/libcurl/c/getinmemory.html -.SH AVAILABILITY -Available in all libcurl versions. This option was formerly known as -CURLOPT_FILE, the name \fICURLOPT_WRITEDATA(3)\fP was added in 7.9.7. -.SH RETURN VALUE -This returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_WRITEFUNCTION (3), -.BR CURLOPT_HEADERDATA (3), -.BR CURLOPT_READDATA (3) diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.md b/docs/libcurl/opts/CURLOPT_WRITEDATA.md new file mode 100644 index 00000000000..495c6bf9cfd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.md @@ -0,0 +1,63 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_WRITEDATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADERDATA (3) + - CURLOPT_READDATA (3) + - CURLOPT_WRITEFUNCTION (3) +--- + +# NAME + +CURLOPT_WRITEDATA - pointer passed to the write callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer); +~~~ + +# DESCRIPTION + +A data *pointer* to pass to the write callback. If you use the +CURLOPT_WRITEFUNCTION(3) option, this is the pointer you get in that +callback's fourth and last argument. If you do not use a write callback, you +must make *pointer* a 'FILE *' (cast to 'void *') as libcurl passes this +to *fwrite(3)* when writing data. + +The internal CURLOPT_WRITEFUNCTION(3) writes the data to the FILE * +given with this option, or to stdout if this option has not been set. + +If you are using libcurl as a Windows DLL, you **MUST** use a +CURLOPT_WRITEFUNCTION(3) if you set this option or you might experience +crashes. + +# DEFAULT + +By default, this is a FILE * to stdout. + +# PROTOCOLS + +Used for all protocols. + +# EXAMPLE + +A common technique is to use the write callback to store the incoming data +into a dynamically growing allocated buffer, and then this +CURLOPT_WRITEDATA(3) is used to point to a struct or the buffer to store +data in. Like in the getinmemory example: +https://curl.se/libcurl/c/getinmemory.html + +# AVAILABILITY + +Available in all libcurl versions. This option was formerly known as +CURLOPT_FILE, the name CURLOPT_WRITEDATA(3) was added in 7.9.7. + +# RETURN VALUE + +This returns CURLE_OK. diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md similarity index 51% rename from docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md index d992bde20b5..8957439d339 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md @@ -1,86 +1,84 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_WRITEFUNCTION 3 "16 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_WRITEFUNCTION \- callback for writing received data -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_WRITEFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_HEADERFUNCTION (3) + - CURLOPT_READFUNCTION (3) + - CURLOPT_WRITEDATA (3) +--- + +# NAME + +CURLOPT_WRITEFUNCTION - callback for writing received data + +# SYNOPSIS + +~~~c #include size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback); -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl as soon as there is data received that needs to be saved. For most transfers, this callback gets called -many times and each invoke delivers another chunk of data. \fIptr\fP points to -the delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is -always 1. +many times and each invoke delivers another chunk of data. *ptr* points to the +delivered data, and the size of that data is *nmemb*; *size* is always 1. + +The data passed to this function is not null-terminated. The callback function is passed as much data as possible in all invokes, but you must not make any assumptions. It may be one byte, it may be thousands. The maximum amount of body data that is be passed to the write -callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the -usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes -header data get passed to the write callback, you can get up to -\fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually -means 100K. +callback is defined in the curl.h header file: *CURL_MAX_WRITE_SIZE* (the +usual default is 16K). If CURLOPT_HEADER(3) is enabled, which makes header +data get passed to the write callback, you can get up to +*CURL_MAX_HTTP_HEADER* bytes of header data passed into it. This usually means +100K. This function may be called with zero bytes data if the transferred file is empty. -The data passed to this function is not null-terminated! - -Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option. +Set the *userdata* argument with the CURLOPT_WRITEDATA(3) option. Your callback should return the number of bytes actually taken care of. If that amount differs from the amount passed to your callback function, it signals an error condition to the library. This causes the transfer to get -aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. +aborted and the libcurl function used returns *CURLE_WRITE_ERROR*. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR (added in -7.87.0), which makes \fICURLE_WRITE_ERROR\fP get returned. +7.87.0), which makes *CURLE_WRITE_ERROR* get returned. If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this -transfer. See \fIcurl_easy_pause(3)\fP for further details. +transfer. See curl_easy_pause(3) for further details. Set this option to NULL to get the internal default function used instead of your callback. The internal default function writes the data to the FILE * -given with \fICURLOPT_WRITEDATA(3)\fP. +given with CURLOPT_WRITEDATA(3). -This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to +This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to do that. -.SH DEFAULT + +# DEFAULT + libcurl uses 'fwrite' as a callback by default. -.SH PROTOCOLS + +# PROTOCOLS + For all protocols -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c #include /* for realloc */ #include /* for memcpy */ @@ -127,12 +125,12 @@ int main(void) curl_easy_cleanup(curl); } } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0. -.SH RETURN VALUE + +# RETURN VALUE + This returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_WRITEDATA (3), -.BR CURLOPT_READFUNCTION (3), -.BR CURLOPT_HEADERFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 deleted file mode 100644 index 3031b9524fc..00000000000 --- a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_WS_OPTIONS 3 "10 Jun 2022" libcurl libcurl -.SH NAME -CURLOPT_WS_OPTIONS \- WebSocket behavior options -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WS_OPTIONS, long bitmask); -.fi -.SH DESCRIPTION -Pass a long with a bitmask to tell libcurl about specific WebSocket -behaviors. - -To detach a WebSocket connection and use the \fIcurl_ws_send(3)\fP and -\fIcurl_ws_recv(3)\fP functions after the HTTP upgrade procedure, set the -\fICURLOPT_CONNECT_ONLY(3)\fP option to 2L. - -Available bits in the bitmask -.IP "CURLWS_RAW_MODE (1)" -Deliver "raw" WebSocket traffic to the \fICURLOPT_WRITEFUNCTION(3)\fP -callback. - -In raw mode, libcurl does not handle pings or any other frame for the -application. -.SH DEFAULT -0 -.SH PROTOCOLS -WebSocket -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "ws://example.com/"); - /* tell curl we deal with all the WebSocket magic ourselves */ - curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, (long)CURLWS_RAW_MODE); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.86.0 -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR curl_ws_recv (3), -.BR curl_ws_send (3), -.BR CURLOPT_CONNECT_ONLY (3) diff --git a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md new file mode 100644 index 00000000000..04af5bca8c7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md @@ -0,0 +1,75 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_WS_OPTIONS +Section: 3 +Source: libcurl +See-also: + - CURLOPT_CONNECT_ONLY (3) + - curl_ws_recv (3) + - curl_ws_send (3) +--- + +# NAME + +CURLOPT_WS_OPTIONS - WebSocket behavior options + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WS_OPTIONS, long bitmask); +~~~ + +# DESCRIPTION + +Pass a long with a bitmask to tell libcurl about specific WebSocket +behaviors. + +To detach a WebSocket connection and use the curl_ws_send(3) and +curl_ws_recv(3) functions after the HTTP upgrade procedure, set the +CURLOPT_CONNECT_ONLY(3) option to 2L. + +Available bits in the bitmask + +## CURLWS_RAW_MODE (1) + +Deliver "raw" WebSocket traffic to the CURLOPT_WRITEFUNCTION(3) +callback. + +In raw mode, libcurl does not handle pings or any other frame for the +application. + +# DEFAULT + +0 + +# PROTOCOLS + +WebSocket + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ws://example.com/"); + /* tell curl we deal with all the WebSocket magic ourselves */ + curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, (long)CURLWS_RAW_MODE); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.86.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 deleted file mode 100644 index 4a03b9ccf45..00000000000 --- a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 +++ /dev/null @@ -1,82 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_XFERINFODATA 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_XFERINFODATA \- pointer passed to the progress callback -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFODATA, void *pointer); -.fi -.SH DESCRIPTION -Pass a \fIpointer\fP that is untouched by libcurl and passed as the first -argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION(3)\fP. - -This is an alias for \fICURLOPT_PROGRESSDATA(3)\fP. -.SH DEFAULT -The default value of this parameter is NULL. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct progress { - char *private; - size_t size; -}; - -static size_t progress_cb(void *clientp, - curl_off_t dltotal, - curl_off_t dlnow, - curl_off_t ultotal, - curl_off_t ulnow) -{ - struct progress *memory = clientp; - printf("private ptr: %p\\n", memory->private); - /* use the values */ - - return 0; /* all is good */ -} - -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - struct progress data; - - /* pass struct to callback */ - curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &data); - curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, progress_cb); - } -} -.fi -.SH AVAILABILITY -Added in 7.32.0 -.SH RETURN VALUE -Returns CURLE_OK -.SH "SEE ALSO" -.BR CURLOPT_NOPROGRESS (3), -.BR CURLOPT_VERBOSE (3), -.BR CURLOPT_XFERINFOFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.md b/docs/libcurl/opts/CURLOPT_XFERINFODATA.md new file mode 100644 index 00000000000..145057c5c47 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_XFERINFODATA.md @@ -0,0 +1,80 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_XFERINFODATA +Section: 3 +Source: libcurl +See-also: + - CURLOPT_NOPROGRESS (3) + - CURLOPT_VERBOSE (3) + - CURLOPT_XFERINFOFUNCTION (3) +--- + +# NAME + +CURLOPT_XFERINFODATA - pointer passed to the progress callback + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFODATA, void *pointer); +~~~ + +# DESCRIPTION + +Pass a *pointer* that is untouched by libcurl and passed as the first +argument in the progress callback set with CURLOPT_XFERINFOFUNCTION(3). + +This is an alias for CURLOPT_PROGRESSDATA(3). + +# DEFAULT + +The default value of this parameter is NULL. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct progress { + char *private; + size_t size; +}; + +static size_t progress_cb(void *clientp, + curl_off_t dltotal, + curl_off_t dlnow, + curl_off_t ultotal, + curl_off_t ulnow) +{ + struct progress *memory = clientp; + printf("private ptr: %p\n", memory->private); + /* use the values */ + + return 0; /* all is good */ +} + +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &data); + curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, progress_cb); + } +} +~~~ + +# AVAILABILITY + +Added in 7.32.0 + +# RETURN VALUE + +Returns CURLE_OK diff --git a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md similarity index 52% rename from docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 rename to docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md index 61521f391df..b965db591d9 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md @@ -1,32 +1,21 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_XFERINFOFUNCTION 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_XFERINFOFUNCTION \- progress meter callback -.SH SYNOPSIS -.nf +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_XFERINFOFUNCTION +Section: 3 +Source: libcurl +See-also: + - CURLOPT_NOPROGRESS (3) + - CURLOPT_XFERINFODATA (3) +--- + +# NAME + +CURLOPT_XFERINFOFUNCTION - progress meter callback + +# SYNOPSIS + +~~~c #include int progress_callback(void *clientp, @@ -37,8 +26,10 @@ int progress_callback(void *clientp, CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFOFUNCTION, progress_callback); -.fi -.SH DESCRIPTION +~~~ + +# DESCRIPTION + Pass a pointer to your callback function, which should match the prototype shown above. @@ -47,14 +38,14 @@ frequent interval. While data is being transferred it gets called frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second. -\fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA(3)\fP, it is not +*clientp* is the pointer set with CURLOPT_XFERINFODATA(3), it is not used by libcurl but is only passed along from the application to the callback. The callback gets told how much data libcurl is about to transfer and has -already transferred, in number of bytes. \fIdltotal\fP is the total number of -bytes libcurl expects to download in this transfer. \fIdlnow\fP is the number -of bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl -expects to upload in this transfer. \fIulnow\fP is the number of bytes +already transferred, in number of bytes. *dltotal* is the total number of +bytes libcurl expects to download in this transfer. *dlnow* is the number +of bytes downloaded so far. *ultotal* is the total number of bytes libcurl +expects to upload in this transfer. *ulnow* is the number of bytes uploaded so far. Unknown/unused argument values passed to the callback are set to zero (like if @@ -66,21 +57,27 @@ If your callback function returns CURL_PROGRESSFUNC_CONTINUE it makes libcurl to continue executing the default progress function. Returning any other non-zero value from this callback makes libcurl abort the -transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. +transfer and return *CURLE_ABORTED_BY_CALLBACK*. If you transfer data with the multi interface, this function is not called during periods of idleness unless you call the appropriate libcurl function that performs transfers. -\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually +CURLOPT_NOPROGRESS(3) must be set to 0 to make this function actually get called. -.SH DEFAULT + +# DEFAULT + By default, libcurl has an internal progress meter. That is rarely wanted by users. -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c struct progress { char *private; size_t size; @@ -93,7 +90,7 @@ static size_t progress_callback(void *clientp, curl_off_t ulnow) { struct progress *memory = clientp; - printf("my ptr: %p\\n", memory->private); + printf("my ptr: %p\n", memory->private); /* use the values */ @@ -112,11 +109,12 @@ int main(void) curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, progress_callback); } } -.fi -.SH AVAILABILITY -Added in 7.32.0. This callback replaces \fICURLOPT_PROGRESSFUNCTION(3)\fP -.SH RETURN VALUE +~~~ + +# AVAILABILITY + +Added in 7.32.0. This callback replaces CURLOPT_PROGRESSFUNCTION(3) + +# RETURN VALUE + Returns CURLE_OK. -.SH "SEE ALSO" -.BR CURLOPT_NOPROGRESS (3), -.BR CURLOPT_XFERINFODATA (3) diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 deleted file mode 100644 index 98ac90f1eba..00000000000 --- a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 +++ /dev/null @@ -1,69 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_XOAUTH2_BEARER 3 "19 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_XOAUTH2_BEARER \- OAuth 2.0 access token -.SH SYNOPSIS -.nf -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XOAUTH2_BEARER, char *token); -.fi -.SH DESCRIPTION -Pass a char * as parameter, which should point to the null-terminated OAuth -2.0 Bearer Access Token for use with HTTP, IMAP, LDAP, POP3 and SMTP servers -that support the OAuth 2.0 Authorization Framework. - -Note: For IMAP, LDAP, POP3 and SMTP, the user name used to generate the -Bearer Token should be supplied via the \fICURLOPT_USERNAME(3)\fP option. - -The application does not have to keep the string around after setting this -option. -.SH DEFAULT -NULL -.SH PROTOCOLS -HTTP, IMAP, LDAP, POP3 and SMTP -.SH EXAMPLE -.nf -int main(void) -{ - CURL *curl = curl_easy_init(); - if(curl) { - CURLcode res; - curl_easy_setopt(curl, CURLOPT_URL, "pop3://example.com/"); - curl_easy_setopt(curl, CURLOPT_XOAUTH2_BEARER, "1ab9cb22ba269a7"); - res = curl_easy_perform(curl); - curl_easy_cleanup(curl); - } -} -.fi -.SH AVAILABILITY -Added in 7.33.0. Support for OpenLDAP added in 7.82.0. -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. -.SH "SEE ALSO" -.BR CURLOPT_MAIL_AUTH (3), -.BR CURLOPT_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md new file mode 100644 index 00000000000..af91ea03e69 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md @@ -0,0 +1,67 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLOPT_XOAUTH2_BEARER +Section: 3 +Source: libcurl +See-also: + - CURLOPT_MAIL_AUTH (3) + - CURLOPT_USERNAME (3) +--- + +# NAME + +CURLOPT_XOAUTH2_BEARER - OAuth 2.0 access token + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XOAUTH2_BEARER, char *token); +~~~ + +# DESCRIPTION + +Pass a char pointer as parameter, which should point to the null-terminated +OAuth 2.0 Bearer Access Token for use with HTTP, IMAP, LDAP, POP3 and SMTP +servers that support the OAuth 2.0 Authorization Framework. + +Note: For IMAP, LDAP, POP3 and SMTP, the user name used to generate the +Bearer Token should be supplied via the CURLOPT_USERNAME(3) option. + +The application does not have to keep the string around after setting this +option. + +# DEFAULT + +NULL + +# PROTOCOLS + +HTTP, IMAP, LDAP, POP3 and SMTP + +# EXAMPLE + +~~~c +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "pop3://example.com/"); + curl_easy_setopt(curl, CURLOPT_XOAUTH2_BEARER, "1ab9cb22ba269a7"); + res = curl_easy_perform(curl); + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 7.33.0. Support for OpenLDAP added in 7.82.0. + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 deleted file mode 100644 index 174326cb1ee..00000000000 --- a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 +++ /dev/null @@ -1,80 +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 -.\" * -.\" ************************************************************************** -.TH CURLSHOPT_LOCKFUNC 3 "8 Aug 2003" libcurl libcurl -.SH NAME -CURLSHOPT_LOCKFUNC - mutex lock callback -.SH SYNOPSIS -.nf -#include - -void lockcb(CURL *handle, curl_lock_data data, curl_lock_access access, - void *clientp); - -CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_LOCKFUNC, lockcb); -.fi -.SH DESCRIPTION -Set a mutex lock callback for the share object, to allow it to get used by -multiple threads concurrently. There is a corresponding -\fICURLSHOPT_UNLOCKFUNC(3)\fP callback called when the mutex is again released. - -The \fIlockcb\fP argument must be a pointer to a function matching the -prototype shown above. The arguments to the callback are: - -\fIhandle\fP is the currently active easy handle in use when the share object -is intended to get used. - -The \fIdata\fP argument tells what kind of data libcurl wants to lock. Make -sure that the callback uses a different lock for each kind of data. - -\fIaccess\fP defines what access type libcurl wants, shared or single. - -\fIclientp\fP is the private pointer you set with \fICURLSHOPT_USERDATA(3)\fP. -This pointer is not used by libcurl itself. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -extern void mutex_lock(CURL *handle, curl_lock_data data, - curl_lock_access access, void *clientp); - -int main(void) -{ - CURLSHcode sh; - CURLSH *share = curl_share_init(); - sh = curl_share_setopt(share, CURLSHOPT_LOCKFUNC, mutex_lock); - if(sh) - printf("Error: %s\\n", curl_share_strerror(sh)); -} -.fi -.SH AVAILABILITY -Added in 7.10 -.SH RETURN VALUE -CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred. See \fIlibcurl-errors(3)\fP for the full list with -descriptions. -.SH "SEE ALSO" -.BR curl_share_cleanup (3), -.BR curl_share_init (3), -.BR curl_share_setopt (3), -.BR CURLSHOPT_UNLOCKFUNC (3) diff --git a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md new file mode 100644 index 00000000000..f41f86ebf2c --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md @@ -0,0 +1,77 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLSHOPT_LOCKFUNC +Section: 3 +Source: libcurl +See-also: + - CURLSHOPT_UNLOCKFUNC (3) + - curl_share_cleanup (3) + - curl_share_init (3) + - curl_share_setopt (3) +--- + +# NAME + +CURLSHOPT_LOCKFUNC - mutex lock callback + +# SYNOPSIS + +~~~c +#include + +void lockcb(CURL *handle, curl_lock_data data, curl_lock_access access, + void *clientp); + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_LOCKFUNC, lockcb); +~~~ + +# DESCRIPTION + +Set a mutex lock callback for the share object, to allow it to get used by +multiple threads concurrently. There is a corresponding +CURLSHOPT_UNLOCKFUNC(3) callback called when the mutex is again released. + +The *lockcb* argument must be a pointer to a function matching the +prototype shown above. The arguments to the callback are: + +*handle* is the currently active easy handle in use when the share object +is intended to get used. + +The *data* argument tells what kind of data libcurl wants to lock. Make +sure that the callback uses a different lock for each kind of data. + +*access* defines what access type libcurl wants, shared or single. + +*clientp* is the private pointer you set with CURLSHOPT_USERDATA(3). +This pointer is not used by libcurl itself. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +extern void mutex_lock(CURL *handle, curl_lock_data data, + curl_lock_access access, void *clientp); + +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_LOCKFUNC, mutex_lock); + if(sh) + printf("Error: %s\n", curl_share_strerror(sh)); +} +~~~ + +# AVAILABILITY + +Added in 7.10 + +# RETURN VALUE + +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred. See libcurl-errors(3) for the full list with +descriptions. diff --git a/docs/libcurl/opts/CURLSHOPT_SHARE.3 b/docs/libcurl/opts/CURLSHOPT_SHARE.md similarity index 52% rename from docs/libcurl/opts/CURLSHOPT_SHARE.3 rename to docs/libcurl/opts/CURLSHOPT_SHARE.md index 49f97604092..66ed27034ed 100644 --- a/docs/libcurl/opts/CURLSHOPT_SHARE.3 +++ b/docs/libcurl/opts/CURLSHOPT_SHARE.md @@ -1,57 +1,59 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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 -.\" * -.\" ************************************************************************** -.TH CURLSHOPT_SHARE 3 "8 Aug 2003" libcurl libcurl -.SH NAME +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLSHOPT_SHARE +Section: 3 +Source: libcurl +See-also: + - CURLSHOPT_UNSHARE (3) + - curl_share_cleanup (3) + - curl_share_init (3) + - curl_share_setopt (3) +--- + +# NAME + CURLSHOPT_SHARE - add data to share -.SH SYNOPSIS -.nf + +# SYNOPSIS + +~~~c #include CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_SHARE, long type); -.fi -.SH DESCRIPTION -The \fItype\fP parameter specifies what specific data that should be shared -and kept in the share object that was created with \fIcurl_share_init(3)\fP. -The given \fItype\fP must be be one of the values described below. You can set -\fICURLSHOPT_SHARE(3)\fP multiple times with different data arguments to have +~~~ + +# DESCRIPTION + +The *type* parameter specifies what specific data that should be shared +and kept in the share object that was created with curl_share_init(3). +The given *type* must be be one of the values described below. You can set +CURLSHOPT_SHARE(3) multiple times with different data arguments to have the share object share multiple types of data. Unset a type again by setting -\fICURLSHOPT_UNSHARE(3)\fP. -.IP CURL_LOCK_DATA_COOKIE +CURLSHOPT_UNSHARE(3). + +## CURL_LOCK_DATA_COOKIE + Cookie data is shared across the easy handles using this shared object. Note that this does not activate an easy handle's cookie handling. You can do that -separately by using \fICURLOPT_COOKIEFILE(3)\fP for example. -.IP CURL_LOCK_DATA_DNS +separately by using CURLOPT_COOKIEFILE(3) for example. + +## CURL_LOCK_DATA_DNS + Cached DNS hosts are shared across the easy handles using this shared object. Note that when you use the multi interface, all easy handles added to the same multi handle share DNS cache by default without using this option. -.IP CURL_LOCK_DATA_SSL_SESSION + +## CURL_LOCK_DATA_SSL_SESSION + SSL session IDs are shared across the easy handles using this shared object. This reduces the time spent in the SSL handshake when reconnecting to the same server. Note SSL session IDs are reused within the same easy handle by default. Note this symbol was added in 7.10.3 but was not implemented until 7.23.0. -.IP CURL_LOCK_DATA_CONNECT + +## CURL_LOCK_DATA_CONNECT + Put the connection cache in the share object and make all easy handles using this share object share the connection cache. @@ -62,12 +64,14 @@ get additional transfers added to them if the existing connection is held by the same multi or easy handle. libcurl does not support doing HTTP/2 streams in different threads using a shared connection. -Support for \fBCURL_LOCK_DATA_CONNECT\fP was added in 7.57.0, but the symbol +Support for **CURL_LOCK_DATA_CONNECT** was added in 7.57.0, but the symbol existed before this. Note that when you use the multi interface, all easy handles added to the same multi handle shares connection cache by default without using this option. -.IP CURL_LOCK_DATA_PSL + +## CURL_LOCK_DATA_PSL + The Public Suffix List stored in the share object is made available to all easy handle bound to the later. Since the Public Suffix List is periodically refreshed, this avoids updates in too many different contexts. @@ -76,33 +80,38 @@ Added in 7.61.0. Note that when you use the multi interface, all easy handles added to the same multi handle shares PSL cache by default without using this option. -.IP CURL_LOCK_DATA_HSTS + +## CURL_LOCK_DATA_HSTS + The in-memory HSTS cache. It is not supported to share the HSTS between multiple concurrent threads. Added in 7.88.0 -.SH PROTOCOLS + +# PROTOCOLS + All -.SH EXAMPLE -.nf + +# EXAMPLE + +~~~c int main(void) { CURLSHcode sh; CURLSH *share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE); if(sh) - printf("Error: %s\\n", curl_share_strerror(sh)); + printf("Error: %s\n", curl_share_strerror(sh)); } -.fi -.SH AVAILABILITY +~~~ + +# AVAILABILITY + Added in 7.10 -.SH RETURN VALUE + +# RETURN VALUE + CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred. See \fIlibcurl-errors(3)\fP for the full list with +error occurred. See libcurl-errors(3) for the full list with descriptions. -.SH "SEE ALSO" -.BR curl_share_cleanup (3), -.BR curl_share_init (3), -.BR curl_share_setopt (3), -.BR CURLSHOPT_UNSHARE (3) diff --git a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 deleted file mode 100644 index 1994b6fd9b3..00000000000 --- a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 +++ /dev/null @@ -1,75 +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 -.\" * -.\" ************************************************************************** -.TH CURLSHOPT_UNLOCKFUNC 3 "8 Aug 2003" libcurl libcurl -.SH NAME -CURLSHOPT_UNLOCKFUNC - mutex unlock callback -.SH SYNOPSIS -.nf -#include - -void unlockcb(CURL *handle, curl_lock_data data, void *clientp); - -CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNLOCKFUNC, unlockcb); -.fi -.SH DESCRIPTION -Set a mutex unlock callback for the share object. There is a corresponding -\fICURLSHOPT_LOCKFUNC(3)\fP callback called when the mutex is first locked. - -The \fIunlockcb\fP argument must be a pointer to a function matching the -prototype shown above. The arguments to the callback are: - -\fIhandle\fP is the currently active easy handle in use when the share object -is released. - -The \fIdata\fP argument tells what kind of data libcurl wants to unlock. Make -sure that the callback uses a different lock for each kind of data. - -\fIclientp\fP is the private pointer you set with \fICURLSHOPT_USERDATA(3)\fP. -This pointer is not used by libcurl itself. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -extern void mutex_unlock(CURL *, curl_lock_data, void *); - -int main(void) -{ - CURLSHcode sh; - CURLSH *share = curl_share_init(); - sh = curl_share_setopt(share, CURLSHOPT_UNLOCKFUNC, mutex_unlock); - if(sh) - printf("Error: %s\\n", curl_share_strerror(sh)); -} -.fi -.SH AVAILABILITY -Added in 7.10 -.SH RETURN VALUE -CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred. See \fIlibcurl-errors(3)\fP for the full list with -descriptions. -.SH "SEE ALSO" -.BR curl_share_cleanup (3), -.BR curl_share_init (3), -.BR curl_share_setopt (3), -.BR CURLSHOPT_LOCKFUNC (3) diff --git a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md new file mode 100644 index 00000000000..16f9a377e6a --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md @@ -0,0 +1,72 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLSHOPT_UNLOCKFUNC +Section: 3 +Source: libcurl +See-also: + - CURLSHOPT_LOCKFUNC (3) + - curl_share_cleanup (3) + - curl_share_init (3) + - curl_share_setopt (3) +--- + +# NAME + +CURLSHOPT_UNLOCKFUNC - mutex unlock callback + +# SYNOPSIS + +~~~c +#include + +void unlockcb(CURL *handle, curl_lock_data data, void *clientp); + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNLOCKFUNC, unlockcb); +~~~ + +# DESCRIPTION + +Set a mutex unlock callback for the share object. There is a corresponding +CURLSHOPT_LOCKFUNC(3) callback called when the mutex is first locked. + +The *unlockcb* argument must be a pointer to a function matching the +prototype shown above. The arguments to the callback are: + +*handle* is the currently active easy handle in use when the share object +is released. + +The *data* argument tells what kind of data libcurl wants to unlock. Make +sure that the callback uses a different lock for each kind of data. + +*clientp* is the private pointer you set with CURLSHOPT_USERDATA(3). +This pointer is not used by libcurl itself. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +extern void mutex_unlock(CURL *, curl_lock_data, void *); + +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_UNLOCKFUNC, mutex_unlock); + if(sh) + printf("Error: %s\n", curl_share_strerror(sh)); +} +~~~ + +# AVAILABILITY + +Added in 7.10 + +# RETURN VALUE + +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred. See libcurl-errors(3) for the full list with +descriptions. diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 b/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 deleted file mode 100644 index e0d252bf380..00000000000 --- a/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 +++ /dev/null @@ -1,77 +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 -.\" * -.\" ************************************************************************** -.TH CURLSHOPT_UNSHARE 3 "8 Aug 2003" libcurl libcurl -.SH NAME -CURLSHOPT_UNSHARE - remove data to share -.SH SYNOPSIS -.nf -#include - -CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNSHARE, long type); -.fi -.SH DESCRIPTION -The \fItype\fP parameter specifies what specific data that should no longer be -shared and kept in the share object that was created with -\fIcurl_share_init(3)\fP. In other words, stop sharing that data in this -shared object. The given \fItype\fP must be be one of the values described -below. You can set \fICURLSHOPT_UNSHARE(3)\fP multiple times with different -data arguments to remove multiple types from the shared object. Add data to -share again with \fICURLSHOPT_SHARE(3)\fP. -.IP CURL_LOCK_DATA_COOKIE -Cookie data is no longer shared across the easy handles using this shared -object. -.IP CURL_LOCK_DATA_DNS -Cached DNS hosts are no longer shared across the easy handles using this -shared object. -.IP CURL_LOCK_DATA_SSL_SESSION -SSL session IDs are no longer shared across the easy handles using this shared -object. -.IP CURL_LOCK_DATA_CONNECT -The connection cache is no longer shared. -.IP CURL_LOCK_DATA_PSL -The Public Suffix List is no longer shared. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -int main(void) -{ - CURLSHcode sh; - CURLSH *share = curl_share_init(); - sh = curl_share_setopt(share, CURLSHOPT_UNSHARE, CURL_LOCK_DATA_COOKIE); - if(sh) - printf("Error: %s\\n", curl_share_strerror(sh)); -} -.fi -.SH AVAILABILITY -Added in 7.10 -.SH RETURN VALUE -CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred. See \fIlibcurl-errors(3)\fP for the full list with -descriptions. -.SH "SEE ALSO" -.BR curl_share_cleanup (3), -.BR curl_share_init (3), -.BR curl_share_setopt (3), -.BR CURLSHOPT_SHARE (3) diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md new file mode 100644 index 00000000000..e3cf5988ceb --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md @@ -0,0 +1,84 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLSHOPT_UNSHARE +Section: 3 +Source: libcurl +See-also: + - CURLSHOPT_SHARE (3) + - curl_share_cleanup (3) + - curl_share_init (3) + - curl_share_setopt (3) +--- + +# NAME + +CURLSHOPT_UNSHARE - remove data to share + +# SYNOPSIS + +~~~c +#include + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNSHARE, long type); +~~~ + +# DESCRIPTION + +The *type* parameter specifies what specific data that should no longer be +shared and kept in the share object that was created with +curl_share_init(3). In other words, stop sharing that data in this +shared object. The given *type* must be be one of the values described +below. You can set CURLSHOPT_UNSHARE(3) multiple times with different +data arguments to remove multiple types from the shared object. Add data to +share again with CURLSHOPT_SHARE(3). + +## CURL_LOCK_DATA_COOKIE + +Cookie data is no longer shared across the easy handles using this shared +object. + +## CURL_LOCK_DATA_DNS + +Cached DNS hosts are no longer shared across the easy handles using this +shared object. + +## CURL_LOCK_DATA_SSL_SESSION + +SSL session IDs are no longer shared across the easy handles using this shared +object. + +## CURL_LOCK_DATA_CONNECT + +The connection cache is no longer shared. + +## CURL_LOCK_DATA_PSL + +The Public Suffix List is no longer shared. + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +int main(void) +{ + CURLSHcode sh; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_UNSHARE, CURL_LOCK_DATA_COOKIE); + if(sh) + printf("Error: %s\n", curl_share_strerror(sh)); +} +~~~ + +# AVAILABILITY + +Added in 7.10 + +# RETURN VALUE + +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred. See libcurl-errors(3) for the full list with +descriptions. diff --git a/docs/libcurl/opts/CURLSHOPT_USERDATA.3 b/docs/libcurl/opts/CURLSHOPT_USERDATA.3 deleted file mode 100644 index cb5347fe9a3..00000000000 --- a/docs/libcurl/opts/CURLSHOPT_USERDATA.3 +++ /dev/null @@ -1,65 +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 -.\" * -.\" ************************************************************************** -.TH CURLSHOPT_USERDATA 3 "8 Aug 2003" libcurl libcurl -.SH NAME -CURLSHOPT_USERDATA - pointer passed to the lock and unlock mutex callbacks -.SH SYNOPSIS -.nf -#include - -CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_USERDATA, void *clientp); -.fi -.SH DESCRIPTION -The \fIclientp\fP parameter is held verbatim by libcurl and is passed on as -the \fIclientp\fP argument to the callbacks set with -\fICURLSHOPT_LOCKFUNC(3)\fP and \fICURLSHOPT_UNLOCKFUNC(3)\fP. -.SH PROTOCOLS -All -.SH EXAMPLE -.nf -struct secrets { - void *custom; -}; - -int main(void) -{ - CURLSHcode sh; - struct secrets private_stuff; - CURLSH *share = curl_share_init(); - sh = curl_share_setopt(share, CURLSHOPT_USERDATA, &private_stuff); - if(sh) - printf("Error: %s\\n", curl_share_strerror(sh)); -} -.fi -.SH AVAILABILITY -Added in 7.10 -.SH RETURN VALUE -CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred. See \fIlibcurl-errors(3)\fP for the full list with -descriptions. -.SH "SEE ALSO" -.BR curl_share_cleanup (3), -.BR curl_share_init (3), -.BR curl_share_setopt (3), -.BR CURLSHOPT_LOCKFUNC (3) diff --git a/docs/libcurl/opts/CURLSHOPT_USERDATA.md b/docs/libcurl/opts/CURLSHOPT_USERDATA.md new file mode 100644 index 00000000000..d0ec7772de6 --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_USERDATA.md @@ -0,0 +1,62 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLSHOPT_USERDATA +Section: 3 +Source: libcurl +See-also: + - CURLSHOPT_LOCKFUNC (3) + - curl_share_cleanup (3) + - curl_share_init (3) + - curl_share_setopt (3) +--- + +# NAME + +CURLSHOPT_USERDATA - pointer passed to the lock and unlock mutex callbacks + +# SYNOPSIS + +~~~c +#include + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_USERDATA, void *clientp); +~~~ + +# DESCRIPTION + +The *clientp* parameter is held verbatim by libcurl and is passed on as +the *clientp* argument to the callbacks set with +CURLSHOPT_LOCKFUNC(3) and CURLSHOPT_UNLOCKFUNC(3). + +# PROTOCOLS + +All + +# EXAMPLE + +~~~c +struct secrets { + void *custom; +}; + +int main(void) +{ + CURLSHcode sh; + struct secrets private_stuff; + CURLSH *share = curl_share_init(); + sh = curl_share_setopt(share, CURLSHOPT_USERDATA, &private_stuff); + if(sh) + printf("Error: %s\n", curl_share_strerror(sh)); +} +~~~ + +# AVAILABILITY + +Added in 7.10 + +# RETURN VALUE + +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred. See libcurl-errors(3) for the full list with +descriptions. diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am index 250937fd168..42f9db4c5f8 100644 --- a/docs/libcurl/opts/Makefile.am +++ b/docs/libcurl/opts/Makefile.am @@ -26,38 +26,19 @@ AUTOMAKE_OPTIONS = foreign no-dependencies include Makefile.inc -man_DISTMANS = $(man_MANS:.3=.3.dist) +CURLPAGES = $(man_MANS:.3=.md) +CLEANFILES = $(man_MANS) +nodist_MANS = $(man_MANS) -HTMLPAGES = $(man_MANS:.3=.html) +EXTRA_DIST = $(CURLPAGES) CMakeLists.txt -PDFPAGES = $(man_MANS:.3=.pdf) +CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@ +CD2 = $(CD2_$(V)) +CD2_0 = @echo " RENDER " $@; +CD2_1 = +CD2_ = $(CD2_0) -CLEANFILES = $(HTMLPAGES) $(PDFPAGES) $(man_DISTMANS) +SUFFIXES = .3 .md -EXTRA_DIST = $(man_MANS) CMakeLists.txt -MAN2HTML= roffit --mandir=. $< >$@ - -SUFFIXES = .3 .html - -html: $(HTMLPAGES) - -.3.html: - $(MAN2HTML) - -pdf: $(PDFPAGES) - -.3.pdf: - @(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \ - groff -Tps -man $< >$$foo.ps; \ - ps2pdf $$foo.ps $@; \ - rm $$foo.ps; \ - echo "converted $< to $@") - -mancheck: - @(cd $(top_srcdir)/docs/libcurl/opts && ls `awk -F, '!/OBSOLETE/ && /^ CINIT/ { a=substr($$1, 9); print "CURLOPT_" a ".3"}' $(top_srcdir)/include/curl/curl.h`) - rm -f in_temp - @(for a in $(man_MANS); do echo $$a >>in_temp; done) - sort in_temp > in_makefile - ls CURL*.3 > in_directory - -diff -u in_makefile in_directory - rm in_temp in_directory in_makefile +.md.3: + $(CD2)$(CD2NROFF) diff --git a/docs/libcurl/opts/template.3 b/docs/libcurl/opts/template.3 deleted file mode 100644 index 495cb82e07b..00000000000 --- a/docs/libcurl/opts/template.3 +++ /dev/null @@ -1,41 +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 -.\" * -.\" ************************************************************************** -.\" -.TH CURLOPT_TEMPLATE 3 "17 Jun 2014" libcurl libcurl -.SH NAME -CURLOPT_TEMPLATE \- [short description] -.SH SYNOPSIS -#include - -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TEMPLATE, [argument]); -.SH DESCRIPTION -.SH DEFAULT -.SH PROTOCOLS -.SH EXAMPLE -.SH AVAILABILITY -.SH RETURN VALUE -Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -.SH "SEE ALSO" -.BR CURLOPT_STDERR (3), -.BR CURLOPT_DEBUGFUNCTION (3) diff --git a/docs/mk-ca-bundle.1 b/docs/mk-ca-bundle.1 deleted file mode 100644 index e6db0504c09..00000000000 --- a/docs/mk-ca-bundle.1 +++ /dev/null @@ -1,120 +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 -.\" * -.\" ************************************************************************** -.\" -.TH mk-ca-bundle 1 "24 Oct 2016" mk-ca-bundle mk-ca-bundle -.SH NAME -mk-ca-bundle \- convert Mozilla's certificate bundle to PEM format -.SH SYNOPSIS -mk-ca-bundle [options] -.I [outputfile] -.SH DESCRIPTION -The mk-ca-bundle tool downloads the \fIcertdata.txt\fP file from Mozilla's -source tree over HTTPS, then parses \fIcertdata.txt\fP and extracts -certificates into PEM format. By default, only CA root certificates trusted to -issue SSL server authentication certificates are extracted. These are then -processed with the OpenSSL command line tool to produce the final ca-bundle -file. - -The default \fIoutputfile\fP name is \fBca-bundle.crt\fP. By setting it to '-' -(a single dash) you will get the output sent to STDOUT instead of a file. - -The PEM format this scripts uses for output makes the result readily available -for use by just about all OpenSSL or GnuTLS powered applications, such as curl -and others. -.SH OPTIONS -The following options are supported: -.IP -b -backup an existing version of \fIoutputfilename\fP -.IP "-d [name]" -specify which Mozilla tree to pull \fIcertdata.txt\fP from (or a custom -URL). Valid names are: aurora, beta, central, Mozilla, nss, release -(default). They are shortcuts for which source tree to get the certificates -data from. -.IP -f -force rebuild even if \fIcertdata.txt\fP is current (Added in version 1.17) -.IP -i -print version info about used modules -.IP -k -Allow insecure data transfer. By default (since 1.27) this command will fail -if the HTTPS transfer fails. This overrides that decision (and opens for -man-in-the-middle attacks). -.IP -l -print license info about \fIcertdata.txt\fP -.IP -m -(Added in 1.26) Include meta data comments in the output. The meta data is -specific information about each certificate that is stored in the original -file as comments and using this option will make those comments get passed on -to the output file. The meta data is not parsed in any way by mk-ca-bundle. -.IP -n -no download of \fIcertdata.txt\fP (to use existing) -.IP "-p [purposes]:[levels]" -list of Mozilla trust purposes and levels for certificates to include in -output. Takes the form of a comma separated list of purposes, a colon, and a -comma separated list of levels. The default is to include all certificates -trusted to issue SSL Server certificates -(\fISERVER_AUTH:TRUSTED_DELEGATOR\fP). - -(Added in version 1.21, Perl only) - -Valid purposes are: -.RS -\fIALL\fP, \fIDIGITAL_SIGNATURE\fP, \fINON_REPUDIATION\fP, -\fIKEY_ENCIPHERMENT\fP, \fIDATA_ENCIPHERMENT\fP, \fIKEY_AGREEMENT\fP, -\fIKEY_CERT_SIGN\fP, \fICRL_SIGN\fP, \fISERVER_AUTH\fP (default), -\fICLIENT_AUTH\fP, \fICODE_SIGNING\fP, \fIEMAIL_PROTECTION\fP, -\fIIPSEC_END_SYSTEM\fP, \fIIPSEC_TUNNEL\fP, \fIIPSEC_USER\fP, -\fITIME_STAMPING\fP, \fISTEP_UP_APPROVED\fP -.RE -.IP -Valid trust levels are: -.RS -\fIALL\fP, \fITRUSTED_DELEGATOR\fP (default), \fINOT_TRUSTED\fP, \fIMUST_VERIFY_TRUST\fP, \fITRUSTED\fP -.RE -.IP -q -be really quiet (no progress output at all) -.IP -t -include plain text listing of certificates -.IP "-s [algorithms]" -comma separated list of signature algorithms with which to hash/fingerprint -each certificate and output when run in plain text mode. - -(Added in version 1.21, Perl only) - -Valid algorithms are: -.RS -ALL, NONE, MD5 (default), SHA1, SHA256, SHA384, SHA512 -.RE -.IP -u -unlink (remove) \fIcertdata.txt\fP after processing -.IP -v -be verbose and print out processed certificate authorities -.SH EXIT STATUS -Returns 0 on success. Returns 1 if it fails to download data. -.SH FILE FORMAT -The file format used by Mozilla for this trust information is documented here: -.nf -https://p11-glue.freedesktop.org/doc/storing-trust-policy/storing-trust-existing.html -.fi -.SH SEE ALSO -.BR curl (1) diff --git a/docs/mk-ca-bundle.md b/docs/mk-ca-bundle.md new file mode 100644 index 00000000000..bacfce08b23 --- /dev/null +++ b/docs/mk-ca-bundle.md @@ -0,0 +1,128 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: mk-ca-bundle +Section: 1 +Source: mk-ca-bundle +See-also: + - curl (1) +--- + +# NAME + +mk-ca-bundle - convert Mozilla's certificate bundle to PEM format + +# SYNOPSIS + +mk-ca-bundle [options] +*[outputfile]* + +# DESCRIPTION + +The mk-ca-bundle tool downloads the *certdata.txt* file from Mozilla's source +tree over HTTPS, then parses *certdata.txt* and extracts certificates into PEM +format. By default, only CA root certificates trusted to issue SSL server +authentication certificates are extracted. These are then processed with the +OpenSSL command line tool to produce the final ca-bundle file. + +The default *outputfile* name is **ca-bundle.crt**. By setting it to '-' (a +single dash) you will get the output sent to STDOUT instead of a file. + +The PEM format this scripts uses for output makes the result readily available +for use by just about all OpenSSL or GnuTLS powered applications, such as curl +and others. + +# OPTIONS + +The following options are supported: + +## -b + +backup an existing version of *outputfilename* + +## -d [name] + +specify which Mozilla tree to pull *certdata.txt* from (or a custom +URL). Valid names are: aurora, beta, central, Mozilla, nss, release +(default). They are shortcuts for which source tree to get the certificates +data from. + +## -f + +force rebuild even if *certdata.txt* is current (Added in version 1.17) + +## -i + +print version info about used modules + +## -k + +Allow insecure data transfer. By default (since 1.27) this command will fail +if the HTTPS transfer fails. This overrides that decision (and opens for +man-in-the-middle attacks). + +## -l + +print license info about *certdata.txt* + +## -m + +(Added in 1.26) Include meta data comments in the output. The meta data is +specific information about each certificate that is stored in the original +file as comments and using this option will make those comments get passed on +to the output file. The meta data is not parsed in any way by mk-ca-bundle. + +## -n + +no download of *certdata.txt* (to use existing) + +## -p [purposes]:[levels] + +list of Mozilla trust purposes and levels for certificates to include in +output. Takes the form of a comma separated list of purposes, a colon, and a +comma separated list of levels. The default is to include all certificates +trusted to issue SSL Server certificates (*SERVER_AUTH:TRUSTED_DELEGATOR*). + +Valid purposes are: *ALL*, *DIGITAL_SIGNATURE*, *NON_REPUDIATION*, +*KEY_ENCIPHERMENT*, *DATA_ENCIPHERMENT*, *KEY_AGREEMENT*, *KEY_CERT_SIGN*, +*CRL_SIGN*, *SERVER_AUTH* (default), *CLIENT_AUTH*, *CODE_SIGNING*, +*EMAIL_PROTECTION*, *IPSEC_END_SYSTEM*, *IPSEC_TUNNEL*, *IPSEC_USER*, +*TIME_STAMPING*, *STEP_UP_APPROVED* + +Valid trust levels are: *ALL*, *TRUSTED_DELEGATOR* (default), *NOT_TRUSTED*, +*MUST_VERIFY_TRUST*, *TRUSTED* + +## -q + +be really quiet (no progress output at all) + +## -t + +include plain text listing of certificates + +## -s [algorithms] + +comma separated list of signature algorithms with which to hash/fingerprint +each certificate and output when run in plain text mode. + +Valid algorithms are: +ALL, NONE, MD5 (default), SHA1, SHA256, SHA384, SHA512 + +## -u + +unlink (remove) *certdata.txt* after processing + +## -v + +be verbose and print out processed certificate authorities + +# EXIT STATUS + +Returns 0 on success. Returns 1 if it fails to download data. + +# FILE FORMAT + +The file format used by Mozilla for this trust information is documented here: +~~~c +https://p11-glue.freedesktop.org/doc/storing-trust-policy/storing-trust-existing.html +~~~ diff --git a/maketgz b/maketgz index a0fcd878f7d..4ebda82a993 100755 --- a/maketgz +++ b/maketgz @@ -145,13 +145,8 @@ fi ############################################################################ # -# Modify the man pages to display the version number and date. -# - -echo "update man pages" -./scripts/updatemanpages.pl $version >/dev/null - # make the generated file newer than the man page + touch src/tool_hugehelp.c ############################################################################ diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 9d69cff9c99..ae95e85acc9 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -22,8 +22,8 @@ # ########################################################################### -EXTRA_DIST = updatemanpages.pl coverage.sh completion.pl firefox-db2pem.sh \ - checksrc.pl mk-ca-bundle.pl schemetable.c +EXTRA_DIST = coverage.sh completion.pl firefox-db2pem.sh checksrc.pl \ + mk-ca-bundle.pl schemetable.c cd2nroff nroff2cd cdall cd2cd ZSH_FUNCTIONS_DIR = @ZSH_FUNCTIONS_DIR@ FISH_FUNCTIONS_DIR = @FISH_FUNCTIONS_DIR@ diff --git a/scripts/cd2cd b/scripts/cd2cd new file mode 100755 index 00000000000..a4de2f8757f --- /dev/null +++ b/scripts/cd2cd @@ -0,0 +1,226 @@ +#!/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 updates a curldown file to current/better curldown. + +Example: cd2cd [--in-place] > + +--in-place: if used, it replaces the original file with the cleaned up + version. When this is used, cd2cd accepts multiple files to work + on and it ignores errors on single files. + +=end comment +=cut + +my $cd2cd = "0.1"; # to keep check +my $dir; +my $extension; +my $inplace = 0; + +while(1) { + if($ARGV[0] eq "--in-place") { + shift @ARGV; + $inplace = 1; + } + else { + last; + } +} + + +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; + +sub outseealso { + my (@sa) = @_; + my $comma = 0; + my @o; + push @o, ".SH SEE ALSO\n"; + for my $s (sort @sa) { + push @o, sprintf "%s.BR $s", $comma ? ",\n": ""; + $comma = 1; + } + push @o, "\n"; + return @o; +} + +sub single { + my @head; + my @seealso; + my ($f)=@_; + my $title; + my $section; + my $source; + my $start = 0; + my $d; + my $line = 0; + open(F, "<:crlf", "$f") || + return 1; + while() { + $line++; + $d = $_; + if(!$start) { + if(/^---/) { + # header starts here + $start = 1; + push @head, $d; + } + next; + } + if(/^Title: *(.*)/i) { + $title=$1; + } + elsif(/^Section: *(.*)/i) { + $section=$1; + } + elsif(/^Source: *(.*)/i) { + $source=$1; + } + elsif(/^See-also: +(.*)/i) { + $salist = 0; + push @seealso, $1; + } + elsif(/^See-also: */i) { + if($seealso[0]) { + print STDERR "$f:$line:1:ERROR: bad See-Also, needs list\n"; + return 2; + } + $salist = 1; + } + elsif(/^ +- (.*)/i) { + # the only list we support is the see-also + if($salist) { + push @seealso, $1; + } + } + # REUSE-IgnoreStart + elsif(/^C: (.*)/i) { + $copyright=$1; + } + elsif(/^SPDX-License-Identifier: (.*)/i) { + $spdx=$1; + } + # REUSE-IgnoreEnd + elsif(/^---/) { + # end of the header section + if(!$title) { + print STDERR "ERROR: no 'Title:' in $f\n"; + return 1; + } + if(!$section) { + print STDERR "ERROR: no 'Section:' in $f\n"; + return 2; + } + if(!$seealso[0]) { + print STDERR "$f:$line:1:ERROR: no 'See-also:' 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:'$_';" + } + } + + if(!$start) { + print STDERR "$f:$line:1:ERROR: no header present\n"; + return 2; + } + + my @desc; + + push @desc, sprintf <, et al. +SPDX-License-Identifier: curl +Title: $title +Section: $section +Source: $source +HEAD + ; + push @desc, "See-also:\n"; + for my $s (sort @seealso) { + push @desc, " - $s\n" if($s); + } + push @desc, "---\n"; + + my $blankline = 0; + while() { + $d = $_; + $line++; + if($d =~ /^[ \t]*\n/) { + $blankline++; + } + else { + $blankline = 0; + } + # *italics* for curl symbol links get the asterisks removed + $d =~ s/\*((lib|)curl[^ ]*\(3\))\*/$1/gi; + + if(length($d) > 90) { + print STDERR "$f:$line:1:WARN: excessive line length\n"; + } + + push @desc, $d if($blankline < 2); + } + close(F); + + if($inplace) { + open(O, ">$f") || return 1; + print O @desc; + close(O); + } + else { + print @desc; + } + return 0; +} + +if($inplace) { + for my $a (@ARGV) { + # this ignores errors + single($a); + } +} +else { + exit single($ARGV[0]); +} diff --git a/scripts/cd2nroff b/scripts/cd2nroff new file mode 100755 index 00000000000..5d0bab8876b --- /dev/null +++ b/scripts/cd2nroff @@ -0,0 +1,331 @@ +#!/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 + +Converts a curldown file to nroff (man page). + +=end comment +=cut + +my $cd2nroff = "0.1"; # to keep check +my $dir; +my $extension; + +while(1) { + if($ARGV[0] eq "-d") { + shift @ARGV; + $dir = shift @ARGV; + } + elsif($ARGV[0] eq "-e") { + shift @ARGV; + $extension = shift @ARGV; + } + elsif($ARGV[0] eq "-h") { + print < Write the output to the file name from the meta-data in the + specified directory, instead of writing to stdout +-e If -d is used, this option can provide an added "extension", arbitrary + text really, to append to the file name. +-h This help text, +-v Show version then exit +HELP + ; + exit 0; + } + elsif($ARGV[0] eq "-v") { + print "cd2nroff version $cd2nroff\n"; + exit 0; + } + else { + last; + } +} + +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; + +sub outseealso { + my (@sa) = @_; + my $comma = 0; + my @o; + push @o, ".SH SEE ALSO\n"; + for my $s (sort @sa) { + push @o, sprintf "%s.BR $s", $comma ? ",\n": ""; + $comma = 1; + } + push @o, "\n"; + return @o; +} + +sub single { + my @seealso; + my ($f)=@_; + my $title; + my $section; + my $source; + my $start = 0; + my $errors; + my $fh; + if($f) { + open($fh, "<:crlf", "$f") || return 1; + } + else { + $fh = STDIN; + } + while(<$fh>) { + $line++; + if(!$start) { + if(/^---/) { + # header starts here + $start = 1; + } + next; + } + if(/^Title: *(.*)/i) { + $title=$1; + } + elsif(/^Section: *(.*)/i) { + $section=$1; + } + elsif(/^Source: *(.*)/i) { + $source=$1; + } + elsif(/^See-also: +(.*)/i) { + $salist = 0; + push @seealso, $1; + } + elsif(/^See-also: */i) { + if($seealso[0]) { + print STDERR "$f:$line:1:ERROR: bad See-Also, needs list\n"; + return 2; + } + $salist = 1; + } + elsif(/^ +- (.*)/i) { + # the only list we support is the see-also + if($salist) { + push @seealso, $1; + } + } + # REUSE-IgnoreStart + elsif(/^C: (.*)/i) { + $copyright=$1; + } + elsif(/^SPDX-License-Identifier: (.*)/i) { + $spdx=$1; + } + # REUSE-IgnoreEnd + elsif(/^---/) { + # end of the header section + if(!$title) { + print STDERR "ERROR: no 'Title:' in $f\n"; + return 1; + } + if(!$section) { + print STDERR "ERROR: no 'Section:' in $f\n"; + return 2; + } + if(!$seealso[0]) { + print STDERR "$f:$line:1:ERROR: no 'See-also:' 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:'$_';" + } + } + + if(!$start) { + print STDERR "$f:$line:1:ERROR: no header present\n"; + return 2; + } + + my @desc; + my $quote = 0; + my $blankline = 0; + my $header = 0; + + # cut off the leading path from the file name, if any + $f =~ s/^(.*[\\\/])//; + + push @desc, ".\\\" generated by cd2nroff $cd2nroff from $f\n"; + push @desc, ".TH $title $section \"$date\" $source\n"; + while(<$fh>) { + $line++; + + $d = $_; + + if($quote) { + if($quote == 4) { + # remove the indentation + if($d =~ /^ (.*)/) { + push @desc, "$1\n"; + next; + } + else { + # end of quote + $quote = 0; + push @desc, ".fi\n"; + next; + } + } + if(/^~~~/) { + # end of quote + $quote = 0; + push @desc, ".fi\n"; + next; + } + # convert single backslahes to doubles + $d =~ s/\\/\\\\/g; + # lines starting with a period needs it escaped + $d =~ s/^\./\\&./; + push @desc, $d; + next; + } + + # **bold** + $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g; + # *italics* + $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g; + + # mentions of curl symbols with man pages use italics by default + $d =~ s/((lib|)curl([^ ]*\(3\)))/\\fI$1\\fP/gi; + + # backticked becomes italics + $d =~ s/\`(.*?)\`/\\fI$1\\fP/g; + + if(/^## (.*)/) { + my $word = $1; + # if there are enclosing quotes, remove them first + $word =~ s/[\"\'](.*)[\"\']\z/$1/; + + # enclose in double quotes if there is a space present + if($word =~ / /) { + push @desc, ".IP \"$word\"\n"; + } + else { + push @desc, ".IP $word\n"; + } + $header = 1; + } + elsif(/^# (.*)/) { + my $word = $1; + # if there are enclosing quotes, remove them first + $word =~ s/[\"\'](.*)[\"\']\z/$1/; + push @desc, ".SH $word\n"; + $header = 1; + } + elsif(/^~~~c/) { + # start of a code section, not indented + $quote = 1; + push @desc, "\n" if($blankline && !$header); + $header = 0; + push @desc, ".nf\n"; + } + elsif(/^~~~/) { + # start of a quote section; not code, not indented + $quote = 1; + push @desc, "\n" if($blankline && !$header); + $header = 0; + push @desc, ".nf\n"; + } + elsif(/^ (.*)/) { + # quoted, indented by 4 space + $quote = 4; + push @desc, "\n" if($blankline && !$header); + $header = 0; + push @desc, ".nf\n$1\n"; + } + elsif(/^[ \t]*\n/) { + # count and ignore blank lines + $blankline++; + } + else { + # don't output newlines if this is the first content after a + # header + push @desc, "\n" if($blankline && !$header); + $blankline = 0; + $header = 0; + + # remove single line HTML comments + $d =~ s///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\\&\"/; + + # lines starting with a period needs it escaped + $d =~ s/^\./\\&./; + + if($d =~ /^(.*) /) { + printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n", + length($1); + $errors++; + } + if($d =~ /^[ \t]*\n/) { + # replaced away all contents + $blankline= 1; + } + else { + push @desc, $d; + } + } + } + close($fh); + push @desc, outseealso(@seealso); + if($dir) { + open(O, ">$dir/$title.$section$extension"); + print O @desc; + close(O); + } + else { + print @desc; + } + return $errors; +} + +exit single($ARGV[0]); diff --git a/scripts/cdall b/scripts/cdall new file mode 100755 index 00000000000..507ccc6be25 --- /dev/null +++ b/scripts/cdall @@ -0,0 +1,44 @@ +#!/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 +# +########################################################################### + +# provide all dir names to scan on the cmdline + +sub convert { + my ($dir)=@_; + opendir(my $dh, $dir) || die "could not open $dir"; + my @cd = grep { /\.md\z/ && -f "$dir/$_" } readdir($dh); + closedir $dh; + + for my $cd (@cd) { + my $nroff = "$cd"; + $nroff =~ s/\.md\z/.3/; + print "$dir/$cd = $dir/$nroff\n"; + system("./scripts/cd2nroff -d $dir $dir/$cd"); + } +} + +for my $d (sort @ARGV) { + convert($d); +} diff --git a/scripts/nroff2cd b/scripts/nroff2cd new file mode 100755 index 00000000000..500367f8149 --- /dev/null +++ b/scripts/nroff2cd @@ -0,0 +1,193 @@ +#!/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 converts an nroff file to curldown + +Example: cd2nroff [options] > + +Note: when converting .nf sections, this tool does not know if the +section is code or just regular quotes. It then assumes and uses ~~~c +for code. + +=end comment +=cut + +my $nroff2cd = "0.1"; # to keep check + +sub single { + my ($f)=@_; + open(F, "<:crlf", "$f") || + return 1; + my $line; + my $title; + my $section; + my $source; + my @seealso; + my @desc; + my $header; # non-zero when TH is passed + my $quote = 0; # quote state + while() { + $line++; + my $d = $_; + if($_ =~ /^.\\\"/) { + # a comment we can ignore + next; + } + if(!$header) { + if($d =~ /.so (.*)/) { + # this is basically an include, so do that + my $f = $1; + # remove leading directory + $f =~ s/(.*?\/)//; + close(F); + open(F, "<:crlf", "$f") || return 1; + } + if($d =~ /^\.TH ([^ ]*) (\d) \"(.*?)\" ([^ \n]*)/) { + # header, this needs to be the first thing after leading comments + $title = $1; + $section = $2; + # date is $3 + $source = $4; + # if there are enclosing quotes around source, remove them + $source =~ s/[\"\'](.*)[\"\']\z/$1/; + $header = 1; + + print <, et al. +SPDX-License-Identifier: curl +Title: $title +Section: $section +Source: $source +HEAD + ; + } + next; + } + + if($quote) { + if($d =~ /^\.SH/) { + #end of quote without an .fi + $quote = 0; + push @desc, "~~~\n"; + } + elsif($d =~ /^\.fi/) { + #end of quote + $quote = 0; + push @desc, "~~~\n"; + next; + } + else { + # double-backslashes converted to single ones + $d =~ s/\\\\/\\/g; + push @desc, $d; + next; + } + } + if($d =~ /^\.SH (.*)/) { + my $word = $1; + # if there are enclosing quotes, remove them first + $word =~ s/[\"\'](.*)[\"\']\z/$1/; + if($word eq "SEE ALSO") { + # we just slurp up this section + next; + } + push @desc, "\n# $word\n\n"; + } + elsif($d =~ /^\.(RS|RE)/) { + # ignore these + } + elsif($d =~ /^\.IP (.*)/) { + my $word = $1; + # if there are enclosing quotes, remove them first + $word =~ s/[\"\'](.*)[\"\']\z/$1/; + push @desc, "\n## $word\n\n"; + } + elsif($d =~ /^\.IP/) { + # .IP with no text we just skip + } + elsif($d =~ /^\.BR (.*)/) { + # only used for SEE ALSO + my $word = $1; + # remove trailing comma + $word =~ s/,\z//; + + for my $s (split(/,/, $word)) { + # remove all double quotes + $s =~ s/\"//g; + # tream leading whitespace + $s =~ s/^ +//g; + push @seealso, $s; + } + } + elsif($d =~ /^\.I (.*)/) { + push @desc, "*$1*\n"; + } + elsif($d =~ /^\.B (.*)/) { + push @desc, "**$1**\n"; + } + elsif($d =~ /^\.nf/) { + push @desc, "~~~c\n"; + $quote = 1; + } + else { + # embolden + $d =~ s/\\fB(.*?)\\fP/**$1**/g; + # links to "curl.*()" are left bare since cd2nroff handles them + # specially + $d =~ s/\\fI(curl.*?\(3\))\\fP/$1/ig; + # emphasize + $d =~ s/\\fI(.*?)\\fP/*$1*/g; + # emphasize on a split line + $d =~ s/\\fI/*/g; + # bold on a split line + $d =~ s/\\fB/**/g; + # remove backslash amp + $d =~ s/\\&//g; + # remove backslashes + $d =~ s/\\//g; + # fix single quotes + $d =~ s/\(aq/'/g; + # fix double quotes + $d =~ s/\(dq/\"/g; + push @desc, $d; + } + } + close(F); + + print "See-also:\n"; + for my $s (sort @seealso) { + print " - $s\n" if($s); + } + print "---\n"; + print @desc; + + return !$header; +} + +exit single($ARGV[0]); + diff --git a/scripts/updatemanpages.pl b/scripts/updatemanpages.pl deleted file mode 100755 index 58a8755e8b5..00000000000 --- a/scripts/updatemanpages.pl +++ /dev/null @@ -1,357 +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 -# -########################################################################### - -# Update man pages. - -use strict; -use warnings; -use Tie::File; - -# Data from the command line. - -my $curlver = $ARGV[0]; -my $curldate = $ARGV[1]; - -# Directories and extensions. - -my @dirlist = ("docs/", "docs/libcurl/", "docs/libcurl/opts/", "tests/"); -my @extlist = (".1", ".3"); -my @excludelist = ("mk-ca-bundle.1", "template.3"); - -# Subroutines - -sub printargs{ - # Print arguments and exit. - - print "usage: updatemanpages.pl \n"; - exit; -} - -sub getthline{ - # Process file looking for .TH section. - - my $filename = shift; - my $file_handle; - my $file_line; - - # Open the file. - - open($file_handle, $filename); - - # Look for the .TH section, process it into an array, - # modify it and write to file. - - tie(my @file_data, 'Tie::File', $filename); - foreach my $file_data_line(@file_data) { - if($file_data_line =~ /^.TH/) { - $file_line = $file_data_line; - last; - } - } - - # Close the file. - - close($file_handle); - return $file_line; -} - -sub extractth{ - # Extract .TH section as an array. - - my $input = shift; - - # Split the line into an array. - - my @tharray; - my $inputsize = length($input); - my $inputcurrent = ""; - my $quotemode = 0; - - for(my $inputseek = 0; $inputseek < $inputsize; $inputseek++) { - - if(substr($input, $inputseek, 1) eq " " && $quotemode eq 0) { - push(@tharray, $inputcurrent); - $inputcurrent = ""; - next; - } - - $inputcurrent = $inputcurrent . substr($input, $inputseek, 1); - - if(substr($input, $inputseek, 1) eq "\"") { - if($quotemode eq 0) { - $quotemode = 1; - } - else { - $quotemode = 0; - } - } - } - - if($inputcurrent ne "") { - push(@tharray, $inputcurrent); - } - - return @tharray; -} - -sub getdate{ - # Get the date from the .TH section. - - my $filename = shift; - my $thline; - my @tharray; - my $date = ""; - - $thline = getthline($filename); - - # Return nothing if there is no .TH section found. - - if(!$thline || $thline eq "") { - return ""; - } - - @tharray = extractth($thline); - - # Remove the quotes at the start and end. - - $date = substr($tharray[3], 1, -1); - return $date; -} - -sub processth{ - # Process .TH section. - - my $input = shift; - my $date = shift; - - # Split the line into an array. - - my @tharray = extractth($input); - - # Alter the date. - - my $itemdate = "\""; - $itemdate .= $date; - $itemdate .= "\""; - $tharray[3] = $itemdate; - - # Alter the item version. - - my $itemver = $tharray[4]; - my $itemname = ""; - - for(my $itemnameseek = 1; - $itemnameseek < length($itemver); - $itemnameseek++) { - if(substr($itemver, $itemnameseek, 1) eq " " || - substr($itemver, $itemnameseek, 1) eq "\"") { - last; - } - $itemname .= substr($itemver, $itemnameseek, 1); - } - - $itemver = "\""; - $itemver .= $itemname; - $itemver .= " "; - $itemver .= $curlver; - $itemver .= "\""; - - $tharray[4] = $itemver; - - my $thoutput = ""; - - foreach my $thvalue (@tharray) { - $thoutput .= $thvalue; - $thoutput .= " "; - } - $thoutput =~ s/\s+$//; - $thoutput .= "\n"; - - # Return updated string. - - return $thoutput; -} - -sub processfile{ - # Process file looking for .TH section. - - my $filename = shift; - my $date = shift; - my $file_handle; - my $file_dist_handle; - my $filename_dist; - - # Open a handle for the original file and a second file handle - # for the dist file. - - $filename_dist = $filename . ".dist"; - - open($file_handle, $filename); - open($file_dist_handle, ">" . $filename_dist); - - # Look for the .TH section, process it into an array, - # modify it and write to file. - - tie(my @file_data, 'Tie::File', $filename); - foreach my $file_data_line (@file_data) { - if($file_data_line =~ /^.TH/) { - my $file_dist_line = processth($file_data_line, $date); - print $file_dist_handle $file_dist_line . "\n"; - } - else { - print $file_dist_handle $file_data_line . "\n"; - } - } - - # Close the file. - - close($file_handle); - close($file_dist_handle); -} - -# Check that $curlver is set, otherwise print arguments and exit. - -if(!$curlver) { - printargs(); -} - -# check to see that the git command works, it requires git 2.6 something -my $gitcheck = `git log -1 --date="format:%B %d, %Y" $dirlist[0] 2>/dev/null`; -if(length($gitcheck) < 1) { - print "git version too old or $dirlist[0] is a bad argument\n"; - exit; -} - -# Look in each directory. - -my $dir_handle; - -foreach my $dirname (@dirlist) { - foreach my $extname (@extlist) { - # Go through the directory looking for files ending with - # the current extension. - - opendir($dir_handle, $dirname); - my @filelist = grep(/.$extname$/i, readdir($dir_handle)); - - foreach my $file (@filelist) { - # Skip if file is in exclude list. - - if(grep(/^$file$/, @excludelist)) { - next; - } - - # Load the file and get the date. - - my $filedate; - - # Check if dist version exists and load date from that - # file if it does. - - if(-e ($dirname . $file . ".dist")) { - $filedate = getdate(($dirname . $file . ".dist")); - } - else { - $filedate = getdate(($dirname . $file)); - } - - # Skip if value is empty. - - if(!$filedate || $filedate eq "") { - next; - } - - # Check the man page in the git repository. - - my $repodata = `LC_TIME=C git log -1 --date="format:%B %d, %Y" \\ - --since="$filedate" $dirname$file | grep ^Date:`; - - # If there is output then update the man page - # with the new date/version. - - # Process the file if there is output. - - if($repodata) { - my $thisdate; - if(!$curldate) { - if($repodata =~ /^Date: +(.*)/) { - $thisdate = $1; - } - else { - print STDERR "Warning: " . ($dirname . $file) . ": found no " . - "date\n"; - } - } - else { - $thisdate = $curldate; - } - processfile(($dirname . $file), $thisdate); - print $dirname . $file . " page updated to $thisdate\n"; - } - } - closedir($dir_handle); - } -} - -__END__ - -=pod - -=head1 updatemanpages.pl - -Updates the man pages with the version number and optional date. If the date -isn't provided, the last modified date from git is used. - -=head2 USAGE - -updatemanpages.pl version [date] - -=head3 version - -Specifies version (required) - -=head3 date - -Specifies date (optional) - -=head2 SETTINGS - -=head3 @dirlist - -Specifies the list of directories to look for files in. - -=head3 @extlist - -Specifies the list of files with extensions to process. - -=head3 @excludelist - -Specifies the list of files to not process. - -=head2 NOTES - -This script is used during maketgz. - -=cut diff --git a/tests/Makefile.am b/tests/Makefile.am index b1fc25b0f8c..a6d0708f72a 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -72,8 +72,6 @@ PERLFLAGS = -I$(srcdir) CLEANFILES = .http.pid .https.pid .ftp.pid .ftps.pid $(MANDISTPAGES) -MAN2HTML= roffit $< >$@ - curl: @cd $(top_builddir) && $(MAKE) @@ -123,16 +121,6 @@ torture-test: perlcheck all event-test: perlcheck all $(TEST) $(TEST_E) $(TFLAGS) -.1.html: - $(MAN2HTML) - -.1.pdf: - @(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \ - groff -Tps -man $< >$$foo.ps; \ - ps2pdf $$foo.ps $@; \ - rm $$foo.ps; \ - echo "converted $< to $@") - checksrc: (cd libtest && $(MAKE) checksrc) (cd unit && $(MAKE) checksrc) diff --git a/tests/data/test1140 b/tests/data/test1140 index fc2a08d0141..5f26c73f41e 100644 --- a/tests/data/test1140 +++ b/tests/data/test1140 @@ -19,7 +19,7 @@ Verify the nroff of man pages -%SRCDIR/test1140.pl %SRCDIR/../docs/ %SRCDIR/../docs/libcurl/*.3 %SRCDIR/../docs/libcurl/opts/*.3 %SRCDIR/../docs/*.1 +%SRCDIR/test1140.pl %PWD/../docs/ %PWD/../docs/libcurl/*.3 %PWD/../docs/libcurl/opts/*.3 %PWD/../docs/*.1 diff --git a/tests/data/test1173 b/tests/data/test1173 index c1dc5c22a8d..97d338df309 100644 --- a/tests/data/test1173 +++ b/tests/data/test1173 @@ -19,7 +19,7 @@ Man page syntax checks -%SRCDIR/test1173.pl %SRCDIR/../docs/libcurl/symbols-in-versions %SRCDIR/../docs/*.1 %SRCDIR/../docs/libcurl/*.3 %SRCDIR/../docs/libcurl/opts/*.3 +%SRCDIR/test1173.pl %SRCDIR/../docs/libcurl/symbols-in-versions %PWD/../docs/*.1 %PWD/../docs/libcurl/*.3 %PWD/../docs/libcurl/opts/*.3 diff --git a/tests/data/test1177 b/tests/data/test1177 index 75af5b4c722..6cc94a5b1d3 100644 --- a/tests/data/test1177 +++ b/tests/data/test1177 @@ -18,7 +18,7 @@ Verify that feature names and CURL_VERSION_* in lib and docs are in sync -%SRCDIR/test1177.pl %SRCDIR/../docs/libcurl/curl_version_info.3 %SRCDIR/../include/curl/curl.h %SRCDIR/../lib/version.c +%SRCDIR/test1177.pl %PWD/../docs/libcurl/curl_version_info.3 %SRCDIR/../include/curl/curl.h %SRCDIR/../lib/version.c diff --git a/tests/data/test1477 b/tests/data/test1477 index 554ac141f1e..a8c4659e4c8 100644 --- a/tests/data/test1477 +++ b/tests/data/test1477 @@ -17,7 +17,7 @@ Verify that error codes in headers and libcurl-errors.3 are in sync -%SRCDIR/test1477.pl %SRCDIR/.. +%SRCDIR/test1477.pl %SRCDIR/.. %PWD/.. diff --git a/tests/test1139.pl b/tests/test1139.pl index ce49a61ba8c..c86081431b5 100755 --- a/tests/test1139.pl +++ b/tests/test1139.pl @@ -67,7 +67,8 @@ sub scanmanpage { my ($file, @words) = @_; - open(my $mh, "<", "$file"); + open(my $mh, "<", "$file") || + die "could not open $file"; my @m; while(<$mh>) { if($_ =~ /^\.IP (.*)/) { @@ -128,7 +129,7 @@ sub scanmanpage { elsif($type eq "MOPT") { push @curlmopt, $opt, } - if(! -f "$root/docs/libcurl/opts/$opt.3") { + if(! -f "$buildroot/docs/libcurl/opts/$opt.3") { print STDERR "Missing $opt.3\n"; $errors++; } @@ -137,9 +138,9 @@ sub scanmanpage { } close($r); -scanmanpage("$root/docs/libcurl/curl_easy_setopt.3", @curlopt); -scanmanpage("$root/docs/libcurl/curl_easy_getinfo.3", @curlinfo); -scanmanpage("$root/docs/libcurl/curl_multi_setopt.3", @curlmopt); +scanmanpage("$buildroot/docs/libcurl/curl_easy_setopt.3", @curlopt); +scanmanpage("$buildroot/docs/libcurl/curl_easy_getinfo.3", @curlinfo); +scanmanpage("$buildroot/docs/libcurl/curl_multi_setopt.3", @curlmopt); # using this hash array, we can skip specific options my %opts = ( diff --git a/tests/test1140.pl b/tests/test1140.pl index 4dddf7cf1ba..b9438dec0cb 100755 --- a/tests/test1140.pl +++ b/tests/test1140.pl @@ -74,6 +74,7 @@ sub file { } if($str =~ /((libcurl|curl)([^ ]*))\(3\)/i) { my $man = "$1.3"; + $man =~ s/\\//g; # cut off backslashes if(!manpresent($man)) { print "error: $f:$line: referring to non-existing man page $man\n"; $errors++; @@ -92,6 +93,7 @@ sub file { my $i= $1; while($i =~ s/((lib|)curl([^ ]*)) *\"\(3\)(,|) *\" *//i ) { my $man = "$1.3"; + $man =~ s/\\//g; # cut off backslashes if(!manpresent($man)) { print "error: $f:$line: referring to non-existing man page $man\n"; $errors++; diff --git a/tests/test1177.pl b/tests/test1177.pl index 3c055d9b3d4..e989e3a8951 100755 --- a/tests/test1177.pl +++ b/tests/test1177.pl @@ -44,7 +44,7 @@ if($_ =~ / mask bit: (CURL_VERSION_[A-Z0-9_]+)/i) { $manversion{$1}++; } - if($_ =~ /^\.ip """([^"]+)"""/i) { + if($_ =~ /^\.ip (.*)/i) { $manname{$1}++; } } @@ -85,7 +85,7 @@ } } for my $n (keys %manname) { - if(!$sourcename{$n}) { + if(!$sourcename{$n} && ($n ne "\"no name\"")) { print STDERR "$manpage: $n is not in the source!\n"; $error++; } diff --git a/tests/test1275.pl b/tests/test1275.pl index 707f286cc76..63b74bf4e7f 100755 --- a/tests/test1275.pl +++ b/tests/test1275.pl @@ -30,7 +30,8 @@ my $errors; my %accepted=('curl' => 1, - 'libcurl' => 1); + 'libcurl' => 1, + 'c-ares' => 1); sub checkfile { my ($f) = @_; @@ -50,9 +51,9 @@ sub checkfile { $ignore ^= 1; } if(!$ignore) { - if(($prevl =~ /\.\z/) && ($line =~ /^( *)([a-z]+)/)) { + if(($prevl =~ /\.\z/) && ($line =~ /^( *)([a-z-]+)/)) { my ($prefix, $word) = ($1, $2); - if(!$accepted{$word}) { + if($word =~ /^[a-z]/ && !$accepted{$word}) { my $c = length($prefix); print STDERR "$f:$l:$c:error: lowercase $word after period\n"; @@ -62,14 +63,16 @@ sub checkfile { $errors++; } } - elsif($line =~ /^(.*)\. +([a-z]+)/) { + elsif($line =~ /^(.*)\. +([a-z-]+)/) { my ($prefix, $word) = ($1, $2); if(($prefix =~ /\.\.\z/) || ($prefix =~ /[0-9]\z/) || ($prefix =~ /e.g\z/) || ($prefix =~ /i.e\z/) || + ($prefix =~ /E.g\z/) || ($prefix =~ /etc\z/) || + ($word !~ /^[a-z]/) || $accepted{$word}) { } else { diff --git a/tests/test1477.pl b/tests/test1477.pl index 9c8f9e882dd..ad564b26d54 100755 --- a/tests/test1477.pl +++ b/tests/test1477.pl @@ -31,7 +31,8 @@ # we may get the dir roots pointed out my $root=$ARGV[0] || "."; -my $manpge = "$root/docs/libcurl/libcurl-errors.3"; +my $buildroot=$ARGV[1] || "."; +my $manpge = "$buildroot/docs/libcurl/libcurl-errors.3"; my $curlh = "$root/include/curl"; my $errors=0; From 16470178264210017005470c24d63d7911ce4bdf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 19 Jan 2024 16:18:40 +0100 Subject: [PATCH 199/509] mksymbolsmanpage.pl: provide references to where the symbol is used --- docs/libcurl/mksymbolsmanpage.pl | 228 ++++++++++++++++++++++++++++++- 1 file changed, 225 insertions(+), 3 deletions(-) diff --git a/docs/libcurl/mksymbolsmanpage.pl b/docs/libcurl/mksymbolsmanpage.pl index fb59eea7a89..d7b9a77e38f 100755 --- a/docs/libcurl/mksymbolsmanpage.pl +++ b/docs/libcurl/mksymbolsmanpage.pl @@ -64,6 +64,224 @@ HEADER ; +sub nameref { + my ($n)=@_; + if($n =~ /^CURLOPT_/) { + if($n eq "CURLOPT_RTSPHEADER") { + $n = "CURLOPT_HTTPHEADER"; + } + elsif($n eq "CURLOPT_WRITEHEADER") { + $n = "CURLOPT_HEADERDATA"; + } + elsif($n eq "CURLOPT_WRITEINFO") { + ; # now obsolete + } + else { + return "$n(3)"; + } + } + elsif($n =~ /^CURLMOPT_/) { + return "$n(3)"; + } + elsif($n =~ /^CURLINFO_/) { + my %infotypes = ( + 'CURLINFO_TEXT' => 1, + 'CURLINFO_HEADER_IN' => 1, + 'CURLINFO_HEADER_OUT' => 1, + 'CURLINFO_DATA_IN' => 1, + 'CURLINFO_DATA_OUT' => 1, + 'CURLINFO_SSL_DATA_IN' => 1, + 'CURLINFO_SSL_DATA_OUT' => 1, + ); + if($infotypes{$n}) { + return "CURLOPT_DEBUGFUNCTION(3)"; + } + } + elsif($n =~ /^CURLALTSVC_/) { + return "CURLOPT_ALTSVC_CTRL(3)"; + } + elsif($n =~ /^CURLAUTH_/) { + return "CURLOPT_HTTPAUTH(3)"; + } + elsif($n =~ /^CURLFORM_/) { + return "curl_formadd(3)"; + } + elsif($n =~ /^CURLKH/) { + return "CURLOPT_SSH_KEYFUNCTION(3)"; + } + elsif($n =~ /^CURLE_/) { + return "libcurl-errors(3)"; + } + elsif($n =~ /^CURLM_/) { + return "libcurl-errors(3)"; + } + elsif($n =~ /^CURLUE_/) { + return "libcurl-errors(3)"; + } + elsif($n =~ /^CURLHE_/) { + return "libcurl-errors(3)"; + } + elsif($n =~ /^CURLSHE_/) { + return "libcurl-errors(3)"; + } + elsif($n =~ /^CURLPROTO_/) { + return "CURLINFO_PROTOCOL(3)"; + } + elsif($n =~ /^CURLPX_/) { + return "CURLINFO_PROXY_ERROR(3)"; + } + elsif($n =~ /^CURLPROXY_/) { + return "CURLOPT_PROXYTYPE(3)"; + } + elsif($n =~ /^CURLSSLBACKEND_/) { + return "curl_global_sslset(3)"; + } + elsif($n =~ /^CURLSSLOPT_/) { + return "CURLOPT_SSL_OPTIONS(3)"; + } + elsif($n =~ /^CURLSSLSET_/) { + return "curl_global_sslset(3)"; + } + elsif($n =~ /^CURLUPART_/) { + return "curl_url_get(3)"; + } + elsif($n =~ /^CURLU_/) { + return "curl_url_get(3)"; + } + elsif($n =~ /^CURLVERSION_/) { + return "curl_version_info(3)"; + } + elsif($n =~ /^CURLSHOPT_/) { + if($n eq "CURLSHOPT_NONE") { + $n = "curl_share_setopt"; + } + return "$n(3)"; + } + elsif($n =~ /^CURLWS_/) { + return "curl_ws_send(3)"; + } + elsif($n =~ /^CURL_FORMADD_/) { + return "curl_formadd(3)"; + } + elsif($n =~ /^CURL_HTTPPOST_/) { + return "curl_formadd(3)"; + } + elsif($n =~ /^CURL_GLOBAL_/) { + return "curl_global_init(3)"; + } + elsif($n =~ /^CURL_HTTP_VERSION_/) { + return "CURLOPT_HTTP_VERSION(3)"; + } + elsif($n =~ /^CURL_LOCK_/) { + return "CURLSHOPT_SHARE(3)"; + } + elsif($n =~ /^CURL_SSLVERSION_/) { + return "CURLOPT_SSLVERSION(3)"; + } + elsif($n =~ /^CURL_VERSION_/) { + return "curl_version_info(3)"; + } + elsif($n =~ /^CURL_RTSPREQ_/) { + return "CURLOPT_RTSP_REQUEST(3)"; + } + elsif($n =~ /^CURLH_/) { + return "curl_easy_header(3)"; + } + elsif($n =~ /^CURL_TRAILERFUNC_/) { + return "CURLOPT_TRAILERFUNCTION(3)"; + } + elsif($n =~ /^CURLOT_/) { + return "curl_easy_option_next(3)"; + } + elsif($n =~ /^CURLFINFOFLAG_/) { + return "CURLOPT_CHUNK_BGN_FUNCTION(3)"; + } + elsif($n =~ /^CURLFILETYPE_/) { + return "CURLOPT_CHUNK_BGN_FUNCTION(3)"; + } + elsif($n =~ /^CURL_CHUNK_BGN_FUNC_/) { + return "CURLOPT_CHUNK_BGN_FUNCTION(3)"; + } + elsif($n =~ /^CURL_CHUNK_END_FUNC_/) { + return "CURLOPT_CHUNK_END_FUNCTION(3)"; + } + elsif($n =~ /^CURLSSH_AUTH_/) { + return "CURLOPT_SSH_AUTH_TYPES(3)"; + } + elsif($n =~ /^CURL_POLL_/) { + return "CURLMOPT_SOCKETFUNCTION(3)"; + } + elsif($n =~ /^CURLMSG_/) { + return "curl_multi_info_read(3)"; + } + elsif($n =~ /^CURLFTPAUTH_/) { + return "CURLOPT_FTPSSLAUTH(3)"; + } + elsif($n =~ /^CURLFTPMETHOD_/) { + return "CURLOPT_FTP_FILEMETHOD(3)"; + } + elsif($n =~ /^CURLFTPSSL_/) { + return "CURLOPT_USE_SSL(3)"; + } + elsif($n =~ /^CURLFTP_CREATE_/) { + return "CURLOPT_FTP_CREATE_MISSING_DIRS(3)"; + } + elsif($n =~ /^CURLGSSAPI_DELEGATION_/) { + return "CURLOPT_GSSAPI_DELEGATION(3)"; + } + elsif($n =~ /^CURLHEADER_/) { + return "CURLOPT_HEADEROPT(3)"; + } + elsif($n =~ /^CURLHSTS_/) { + return "CURLOPT_HSTS_CTRL(3)"; + } + elsif($n =~ /^CURLIOCMD_/) { + return "CURLOPT_IOCTLFUNCTION(3)"; + } + elsif($n =~ /^CURLIOE_/) { + return "CURLOPT_IOCTLFUNCTION(3)"; + } + elsif($n =~ /^CURLMIMEOPT_/) { + return "CURLOPT_MIME_OPTIONS(3)"; + } + elsif($n =~ /^CURLPAUSE_/) { + return "curl_easy_pause(3)"; + } + elsif($n =~ /^CURLPIPE_/) { + return "CURLMOPT_PIPELINING(3)"; + } + elsif($n =~ /^CURLSOCKTYPE_/) { + return "CURLOPT_SOCKOPTFUNCTION(3)"; + } + elsif($n =~ /^CURLSTS_/) { + return "CURLOPT_HSTSREADFUNCTION(3)"; + } + elsif($n =~ /^CURLUSESSL_/) { + return "CURLOPT_USE_SSL(3)"; + } + elsif($n =~ /^CURL_CSELECT_/) { + return "curl_multi_socket_action(3)"; + } + elsif($n =~ /^CURL_FNMATCHFUNC_/) { + return "CURLOPT_FNMATCH_FUNCTION(3)"; + } + elsif($n =~ /^CURL_HET_/) { + return "CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)"; + } + elsif($n =~ /^CURL_IPRESOLVE_/) { + return "CURLOPT_IPRESOLVE(3)"; + } + elsif($n =~ /^CURL_SEEKFUNC_/) { + return "CURLOPT_SEEKFUNCTION(3)"; + } + elsif($n =~ /^CURL_TIMECOND_/) { + return "CURLOPT_TIMECONDITION(3)"; + } + elsif($n =~ /^CURL_REDIR_POST_/) { + return "CURLOPT_POSTREDIR(3)"; + } +} + while() { if($_ =~ /^(CURL[A-Z0-9_.]*) *(.*)/i) { my ($symbol, $rest)=($1,$2); @@ -74,15 +292,19 @@ if($rest =~ s/^([0-9.]*) *//) { $dep = $1; } - if($rest =~ s/^([0-9.]*) *//) { + if($rest =~ s/^- *([0-9.]*)//) { $rem = $1; } print "\n## $symbol\nIntroduced in $intro."; if($dep) { - print " Deprecated since $dep."; + print " Deprecated since $dep."; } if($rem) { - print " Last used in $rem."; + print " Last used in $rem."; + } + my $see = $rem || $dep ? "" : nameref($symbol); + if($see) { + print " See $see."; } print "\n"; } From ea0b575dab86a3c44dd1d547dc500276266aa382 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Mon, 22 Jan 2024 07:49:08 +0100 Subject: [PATCH 200/509] cmake: use curldown to build man pages This throws away the previous HTML and PDF producers, to mimic what Makefile.am does as faithfully as possible. Closes #12753 --- docs/THANKS | 1 + docs/libcurl/CMakeLists.txt | 40 +++++++++++--------------------- docs/libcurl/opts/CMakeLists.txt | 13 +++++------ 3 files changed, 20 insertions(+), 34 deletions(-) diff --git a/docs/THANKS b/docs/THANKS index 88d924f63b3..8c3fd27ec3d 100644 --- a/docs/THANKS +++ b/docs/THANKS @@ -2355,6 +2355,7 @@ Richard Gorton Richard Gray Richard Hosking Richard Hsu +Richard Levitte Richard Marion Richard Michael Richard Moore diff --git a/docs/libcurl/CMakeLists.txt b/docs/libcurl/CMakeLists.txt index c83b5c91c4c..0d52a7e5675 100644 --- a/docs/libcurl/CMakeLists.txt +++ b/docs/libcurl/CMakeLists.txt @@ -27,41 +27,27 @@ include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") function(add_manual_pages _listname) foreach(_file IN LISTS ${_listname}) + set(_rofffile "${CMAKE_CURRENT_BINARY_DIR}/${_file}") if(_file STREQUAL "libcurl-symbols.3") # Special case, an auto-generated file. - set(_srcfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}") + string(REPLACE ".3" ".md" _mdfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}") else() - set(_srcfile "${CMAKE_CURRENT_SOURCE_DIR}/${_file}") + string(REPLACE ".3" ".md" _mdfile "${CMAKE_CURRENT_SOURCE_DIR}/${_file}") endif() - string(REPLACE ".3" ".html" _htmlfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}") - add_custom_command(OUTPUT "${_htmlfile}" - COMMAND roffit "--mandir=${CMAKE_CURRENT_SOURCE_DIR}" "${_srcfile}" > "${_htmlfile}" - DEPENDS "${_srcfile}" + add_custom_command(OUTPUT "${_rofffile}" + COMMAND ${PROJECT_SOURCE_DIR}/scripts/cd2nroff ${_mdfile} > ${_rofffile} + DEPENDS "${_mdfile}" VERBATIM ) - - string(REPLACE ".3" ".pdf" _pdffile "${CMAKE_CURRENT_BINARY_DIR}/${_file}") - string(REPLACE ".3" ".ps" _psfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}") - # XXX any reason why groff -Tpdf (for gropdf) is not used? - add_custom_command(OUTPUT "${_pdffile}" - COMMAND groff -Tps -man "${_srcfile}" > "${_psfile}" - COMMAND ps2pdf "${_psfile}" "${_pdffile}" - COMMAND "${CMAKE_COMMAND}" -E remove "${_psfile}" - DEPENDS "${_srcfile}" - #BYPRODUCTS "${_psfile}" - VERBATIM - ) - # "BYPRODUCTS" for add_custom_command requires CMake 3.2. For now hope that - # the temporary files are removed (i.e. the command is not interrupted). endforeach() endfunction() -add_custom_command(OUTPUT libcurl-symbols.3 +add_custom_command(OUTPUT libcurl-symbols.md COMMAND "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mksymbolsmanpage.pl" < - "${CMAKE_CURRENT_SOURCE_DIR}/symbols-in-versions" > libcurl-symbols.3 + "${CMAKE_CURRENT_SOURCE_DIR}/symbols-in-versions" > libcurl-symbols.md DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/symbols-in-versions" "${CMAKE_CURRENT_SOURCE_DIR}/mksymbolsmanpage.pl" @@ -69,10 +55,10 @@ add_custom_command(OUTPUT libcurl-symbols.3 ) add_manual_pages(man_MANS) - -string(REPLACE ".3" ".html" HTMLPAGES "${man_MANS}") -string(REPLACE ".3" ".pdf" PDFPAGES "${man_MANS}") -add_custom_target(html DEPENDS ${HTMLPAGES}) -add_custom_target(pdf DEPENDS ${PDFPAGES}) +add_custom_target(man ALL DEPENDS ${man_MANS}) +if(NOT CURL_DISABLE_INSTALL) + install(FILES "$" + DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) +endif() add_subdirectory(opts) diff --git a/docs/libcurl/opts/CMakeLists.txt b/docs/libcurl/opts/CMakeLists.txt index 152a08a3511..82844a2251a 100644 --- a/docs/libcurl/opts/CMakeLists.txt +++ b/docs/libcurl/opts/CMakeLists.txt @@ -26,10 +26,9 @@ transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc. include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") add_manual_pages(man_MANS) - -string(REPLACE ".3" ".html" HTMLPAGES "${man_MANS}") -string(REPLACE ".3" ".pdf" PDFPAGES "${man_MANS}") -add_custom_target(opts-html DEPENDS ${HTMLPAGES}) -add_custom_target(opts-pdf DEPENDS ${PDFPAGES}) -add_dependencies(html opts-html) -add_dependencies(pdf opts-pdf) +add_custom_target(opts-man DEPENDS ${man_MANS}) +add_dependencies(man opts-man) +if(NOT CURL_DISABLE_INSTALL) + install(FILES "$" + DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) +endif() From 3f08d80b2244524646ce86915c585509ac54fb4c Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 22 Jan 2024 23:16:54 +0100 Subject: [PATCH 201/509] cmake: add option to disable building docs --- docs/libcurl/CMakeLists.txt | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/libcurl/CMakeLists.txt b/docs/libcurl/CMakeLists.txt index 0d52a7e5675..a34d64e97ad 100644 --- a/docs/libcurl/CMakeLists.txt +++ b/docs/libcurl/CMakeLists.txt @@ -54,11 +54,13 @@ add_custom_command(OUTPUT libcurl-symbols.md VERBATIM ) -add_manual_pages(man_MANS) -add_custom_target(man ALL DEPENDS ${man_MANS}) -if(NOT CURL_DISABLE_INSTALL) - install(FILES "$" - DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) -endif() +if(BUILD_DOCS) + add_manual_pages(man_MANS) + add_custom_target(man ALL DEPENDS ${man_MANS}) + if(NOT CURL_DISABLE_INSTALL) + install(FILES "$" + DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) + endif() -add_subdirectory(opts) + add_subdirectory(opts) +endif() From c28e9478cb2548848eca9b765d0d409bfb18668c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 22 Jan 2024 23:54:08 +0100 Subject: [PATCH 202/509] openssl: when verifystatus fails, remove session id from cache To prevent that it gets used in a subsequent transfer that skips the verifystatus check since that check can't be done when the session id is reused. Reported-by: Hiroki Kurosawa Closes #12760 --- lib/vtls/openssl.c | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c index 0e36dc6aa7e..8d6087022b3 100644 --- a/lib/vtls/openssl.c +++ b/lib/vtls/openssl.c @@ -4351,6 +4351,20 @@ static CURLcode servercert(struct Curl_cfilter *cf, /* don't do this after Session ID reuse */ result = verifystatus(cf, data); if(result) { + /* when verifystatus failed, remove the session id from the cache again + if present */ + if(!Curl_ssl_cf_is_proxy(cf)) { + void *old_ssl_sessionid = NULL; + bool incache; + Curl_ssl_sessionid_lock(data); + incache = !(Curl_ssl_getsessionid(cf, data, &old_ssl_sessionid, NULL)); + if(incache) { + infof(data, "Remove session ID again from cache"); + Curl_ssl_delsessionid(data, old_ssl_sessionid); + } + Curl_ssl_sessionid_unlock(data); + } + X509_free(backend->server_cert); backend->server_cert = NULL; return result; From dfe34d255926088e596f34ada4b301c4481d0153 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 22 Jan 2024 14:36:50 +0000 Subject: [PATCH 203/509] CI: bump actions/cache from 3 to 4 Bumps [actions/cache](https://github.com/actions/cache) from 3 to 4. - [Release notes](https://github.com/actions/cache/releases) - [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md) - [Commits](https://github.com/actions/cache/compare/v3...v4) --- updated-dependencies: - dependency-name: actions/cache dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Closes #12756 --- .github/workflows/awslc.yml | 4 ++-- .github/workflows/linux.yml | 16 ++++++++-------- .github/workflows/ngtcp2-linux.yml | 10 +++++----- .github/workflows/quiche-linux.yml | 6 +++--- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/.github/workflows/awslc.yml b/.github/workflows/awslc.yml index b4011a42a71..48525164149 100644 --- a/.github/workflows/awslc.yml +++ b/.github/workflows/awslc.yml @@ -60,7 +60,7 @@ jobs: name: 'install prereqs and impacket' - name: cache awslc - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-awslc env: cache-name: cache-awslc @@ -119,7 +119,7 @@ jobs: name: 'install prereqs and impacket' - name: cache awslc - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-awslc env: cache-name: cache-awslc diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index ff0e310aa9d..0a3aecc6d7d 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -209,7 +209,7 @@ jobs: - name: cache bearssl if: contains(matrix.build.install_steps, 'bearssl') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-bearssl env: cache-name: cache-bearssl @@ -230,7 +230,7 @@ jobs: - name: cache libressl if: contains(matrix.build.install_steps, 'libressl') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-libressl env: cache-name: cache-libressl @@ -249,7 +249,7 @@ jobs: - name: cache mbedtls if: contains(matrix.build.install_steps, 'mbedtls') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-mbedtls env: cache-name: cache-mbedtls @@ -266,7 +266,7 @@ jobs: - name: cache openssl3 if: contains(matrix.build.install_steps, 'openssl3') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-openssl3 env: cache-name: cache-openssl3 @@ -284,7 +284,7 @@ jobs: - name: cache quictls if: contains(matrix.build.install_steps, 'quictls') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-quictls env: cache-name: cache-quictls @@ -302,7 +302,7 @@ jobs: - name: cache msh3 if: contains(matrix.build.install_steps, 'msh3') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-msh3 env: cache-name: cache-msh3 @@ -329,7 +329,7 @@ jobs: - name: cache rustls if: contains(matrix.build.install_steps, 'rustls') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-rustls env: cache-name: cache-rustls @@ -371,7 +371,7 @@ jobs: - name: cache mod_h2 if: contains(matrix.build.install_steps, 'pytest') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-mod_h2 env: cache-name: cache-mod_h2 diff --git a/.github/workflows/ngtcp2-linux.yml b/.github/workflows/ngtcp2-linux.yml index 84149f57c10..eab27846f1c 100644 --- a/.github/workflows/ngtcp2-linux.yml +++ b/.github/workflows/ngtcp2-linux.yml @@ -94,7 +94,7 @@ jobs: name: 'install prereqs and impacket, pytest, crypto, apache2' - name: cache quictls - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-quictls-no-deprecated env: cache-name: cache-quictls-no-deprecated @@ -118,7 +118,7 @@ jobs: - name: cache gnutls - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-gnutls env: cache-name: cache-gnutls @@ -146,7 +146,7 @@ jobs: - name: cache wolfssl - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-wolfssl env: cache-name: cache-wolfssl @@ -172,7 +172,7 @@ jobs: - name: cache nghttp3 - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-nghttp3 env: cache-name: cache-nghttp3 @@ -214,7 +214,7 @@ jobs: name: 'install nghttp2' - name: cache mod_h2 - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-mod_h2 env: cache-name: cache-mod_h2 diff --git a/.github/workflows/quiche-linux.yml b/.github/workflows/quiche-linux.yml index fd1740295ee..14b3073a30f 100644 --- a/.github/workflows/quiche-linux.yml +++ b/.github/workflows/quiche-linux.yml @@ -82,7 +82,7 @@ jobs: name: 'install prereqs and impacket, pytest, crypto' - name: cache nghttpx - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-nghttpx env: cache-name: cache-nghttpx @@ -126,7 +126,7 @@ jobs: name: 'install nghttp2' - name: cache quiche - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-quiche env: cache-name: cache-quiche @@ -154,7 +154,7 @@ jobs: name: 'build quiche and boringssl' - name: cache mod_h2 - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-mod_h2 env: cache-name: cache-mod_h2 From 2494b8dd5175cee7f2e43c7e449db918587b0c1e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 20 Jan 2024 23:18:43 +0100 Subject: [PATCH 204/509] docs/cmdline: change to .md for cmdline docs - switch all invidual files documenting command line options into .md, as the documentation is now markdown-looking. - made the parser treat 4-space indents as quotes - switch to building the curl.1 manpage using the "mainpage.idx" file, which lists the files to include to generate it, instead of using the previous page-footer/headers. Also, those files are now also .md ones, using the same format. I gave them underscore prefixes to make them sort separately: _NAME.md, _SYNOPSIS.md, _DESCRIPTION.md, _URL.md, _GLOBBING.md, _VARIABLES.md, _OUTPUT.md, _PROTOCOLS.md, _PROGRESS.md, _VERSION.md, _OPTIONS.md, _FILES.md, _ENVIRONMENT.md, _PROXYPREFIX.md, _EXITCODES.md, _BUGS.md, _AUTHORS.md, _WWW.md, _SEEALSO.md - updated test cases accordingly Closes #12751 --- .github/scripts/cleancmd.pl | 52 ++ .github/scripts/spellcheck.words | 2 + .github/workflows/linkcheck.yml | 5 + .github/workflows/spellcheck.yml | 6 + docs/cmdline-opts/MANPAGE.md | 48 +- docs/cmdline-opts/Makefile.am | 4 +- docs/cmdline-opts/Makefile.inc | 539 +++++++++--------- docs/cmdline-opts/_AUTHORS.md | 5 + docs/cmdline-opts/_BUGS.md | 5 + docs/cmdline-opts/_DESCRIPTION.md | 11 + docs/cmdline-opts/_ENVIRONMENT.md | 114 ++++ docs/cmdline-opts/_EXITCODES.md | 201 +++++++ docs/cmdline-opts/_FILES.md | 6 + docs/cmdline-opts/_GLOBBING.md | 40 ++ docs/cmdline-opts/_NAME.md | 4 + docs/cmdline-opts/_OPTIONS.md | 26 + docs/cmdline-opts/_OUTPUT.md | 11 + docs/cmdline-opts/_PROGRESS.md | 25 + docs/cmdline-opts/_PROTOCOLS.md | 51 ++ docs/cmdline-opts/_PROXYPREFIX.md | 22 + docs/cmdline-opts/_SEEALSO.md | 5 + docs/cmdline-opts/_SYNOPSIS.md | 5 + docs/cmdline-opts/_URL.md | 28 + docs/cmdline-opts/_VARIABLES.md | 44 ++ docs/cmdline-opts/_VERSION.md | 15 + docs/cmdline-opts/_WWW.md | 4 + ...-unix-socket.d => abstract-unix-socket.md} | 10 +- docs/cmdline-opts/{alt-svc.d => alt-svc.md} | 11 +- docs/cmdline-opts/{anyauth.d => anyauth.md} | 12 +- docs/cmdline-opts/{append.d => append.md} | 11 +- .../{aws-sigv4.d => aws-sigv4.md} | 11 +- docs/cmdline-opts/{basic.d => basic.md} | 10 +- .../{ca-native.d => ca-native.md} | 12 +- docs/cmdline-opts/{cacert.d => cacert.md} | 11 +- docs/cmdline-opts/{capath.d => capath.md} | 11 +- .../{cert-status.d => cert-status.md} | 10 +- .../{cert-type.d => cert-type.md} | 12 +- docs/cmdline-opts/{cert.d => cert.md} | 37 +- docs/cmdline-opts/{ciphers.d => ciphers.md} | 12 +- .../{compressed-ssh.d => compressed-ssh.md} | 10 +- .../{compressed.d => compressed.md} | 10 +- docs/cmdline-opts/{config.d => config.md} | 44 +- .../{connect-timeout.d => connect-timeout.md} | 14 +- docs/cmdline-opts/connect-to.d | 23 - docs/cmdline-opts/connect-to.md | 30 + .../{continue-at.d => continue-at.md} | 12 +- .../{cookie-jar.d => cookie-jar.md} | 12 +- docs/cmdline-opts/{cookie.d => cookie.md} | 15 +- .../{create-dirs.d => create-dirs.md} | 11 +- ...create-file-mode.d => create-file-mode.md} | 10 +- docs/cmdline-opts/{crlf.d => crlf.md} | 10 +- docs/cmdline-opts/{crlfile.d => crlfile.md} | 11 +- docs/cmdline-opts/{curves.d => curves.md} | 16 +- .../{data-ascii.d => data-ascii.md} | 12 +- .../{data-binary.d => data-binary.md} | 10 +- docs/cmdline-opts/{data-raw.d => data-raw.md} | 12 +- .../{data-urlencode.d => data-urlencode.md} | 17 +- docs/cmdline-opts/{data.d => data.md} | 16 +- .../{delegation.d => delegation.md} | 11 +- docs/cmdline-opts/{digest.d => digest.md} | 12 +- .../{disable-eprt.d => disable-eprt.md} | 11 +- .../{disable-epsv.d => disable-epsv.md} | 11 +- docs/cmdline-opts/{disable.d => disable.md} | 10 +- ...e-in-url.d => disallow-username-in-url.md} | 10 +- .../{dns-interface.d => dns-interface.md} | 11 +- .../{dns-ipv4-addr.d => dns-ipv4-addr.md} | 11 +- .../{dns-ipv6-addr.d => dns-ipv6-addr.md} | 11 +- .../{dns-servers.d => dns-servers.md} | 11 +- .../{doh-cert-status.d => doh-cert-status.md} | 10 +- .../{doh-insecure.d => doh-insecure.md} | 10 +- docs/cmdline-opts/{doh-url.d => doh-url.md} | 10 +- .../{dump-header.d => dump-header.md} | 10 +- docs/cmdline-opts/{egd-file.d => egd-file.md} | 10 +- docs/cmdline-opts/{engine.d => engine.md} | 11 +- .../{etag-compare.d => etag-compare.md} | 11 +- .../{etag-save.d => etag-save.md} | 10 +- ...pect100-timeout.d => expect100-timeout.md} | 10 +- .../{fail-early.d => fail-early.md} | 11 +- .../{fail-with-body.d => fail-with-body.md} | 11 +- docs/cmdline-opts/{fail.d => fail.md} | 11 +- .../{false-start.d => false-start.md} | 10 +- .../{form-escape.d => form-escape.md} | 10 +- .../{form-string.d => form-string.md} | 10 +- docs/cmdline-opts/{form.d => form.md} | 56 +- .../{ftp-account.d => ftp-account.md} | 10 +- ...e-to-user.d => ftp-alternative-to-user.md} | 11 +- .../{ftp-create-dirs.d => ftp-create-dirs.md} | 10 +- .../{ftp-method.d => ftp-method.md} | 14 +- docs/cmdline-opts/{ftp-pasv.d => ftp-pasv.md} | 10 +- docs/cmdline-opts/{ftp-port.d => ftp-port.md} | 17 +- docs/cmdline-opts/{ftp-pret.d => ftp-pret.md} | 11 +- ...ftp-skip-pasv-ip.d => ftp-skip-pasv-ip.md} | 10 +- ...ftp-ssl-ccc-mode.d => ftp-ssl-ccc-mode.md} | 10 +- .../{ftp-ssl-ccc.d => ftp-ssl-ccc.md} | 11 +- .../{ftp-ssl-control.d => ftp-ssl-control.md} | 14 +- docs/cmdline-opts/gen.pl | 426 +++++++++----- docs/cmdline-opts/{get.d => get.md} | 15 +- docs/cmdline-opts/{globoff.d => globoff.md} | 11 +- ...eout-ms.d => happy-eyeballs-timeout-ms.md} | 11 +- ...haproxy-clientip.d => haproxy-clientip.md} | 10 +- ...haproxy-protocol.d => haproxy-protocol.md} | 10 +- docs/cmdline-opts/{head.d => head.md} | 12 +- docs/cmdline-opts/{header.d => header.md} | 17 +- docs/cmdline-opts/{help.d => help.md} | 10 +- .../{hostpubmd5.d => hostpubmd5.md} | 16 +- .../{hostpubsha256.d => hostpubsha256.md} | 10 +- docs/cmdline-opts/{hsts.d => hsts.md} | 10 +- docs/cmdline-opts/{http0.9.d => http0.9.md} | 12 +- docs/cmdline-opts/{http1.0.d => http1.0.md} | 11 +- docs/cmdline-opts/{http1.1.d => http1.1.md} | 11 +- ...r-knowledge.d => http2-prior-knowledge.md} | 11 +- docs/cmdline-opts/{http2.d => http2.md} | 12 +- .../{http3-only.d => http3-only.md} | 12 +- docs/cmdline-opts/{http3.d => http3.md} | 11 +- ...tent-length.d => ignore-content-length.md} | 10 +- docs/cmdline-opts/{include.d => include.md} | 10 +- docs/cmdline-opts/{insecure.d => insecure.md} | 14 +- .../{interface.d => interface.md} | 12 +- .../{ipfs-gateway.d => ipfs-gateway.md} | 22 +- docs/cmdline-opts/{ipv4.d => ipv4.md} | 11 +- docs/cmdline-opts/{ipv6.d => ipv6.md} | 11 +- docs/cmdline-opts/{json.d => json.md} | 23 +- ...sion-cookies.d => junk-session-cookies.md} | 11 +- .../{keepalive-time.d => keepalive-time.md} | 17 +- docs/cmdline-opts/{key-type.d => key-type.md} | 10 +- docs/cmdline-opts/{key.d => key.md} | 17 +- docs/cmdline-opts/{krb.d => krb.md} | 11 +- docs/cmdline-opts/{libcurl.d => libcurl.md} | 10 +- .../{limit-rate.d => limit-rate.md} | 16 +- .../{list-only.d => list-only.md} | 11 +- .../{local-port.d => local-port.md} | 12 +- ...location-trusted.d => location-trusted.md} | 12 +- docs/cmdline-opts/{location.d => location.md} | 11 +- .../{login-options.d => login-options.md} | 19 +- .../{mail-auth.d => mail-auth.md} | 11 +- .../{mail-from.d => mail-from.md} | 11 +- ...t-allowfails.d => mail-rcpt-allowfails.md} | 10 +- .../{mail-rcpt.d => mail-rcpt.md} | 10 +- docs/cmdline-opts/mainpage.idx | 43 ++ docs/cmdline-opts/{manual.d => manual.md} | 12 +- .../{max-filesize.d => max-filesize.md} | 10 +- .../{max-redirs.d => max-redirs.md} | 10 +- docs/cmdline-opts/{max-time.d => max-time.md} | 15 +- docs/cmdline-opts/{metalink.d => metalink.md} | 10 +- .../{negotiate.d => negotiate.md} | 13 +- .../{netrc-file.d => netrc-file.md} | 12 +- .../{netrc-optional.d => netrc-optional.md} | 10 +- docs/cmdline-opts/{netrc.d => netrc.md} | 18 +- docs/cmdline-opts/{next.d => next.md} | 15 +- docs/cmdline-opts/{no-alpn.d => no-alpn.md} | 11 +- .../{no-buffer.d => no-buffer.md} | 10 +- .../{no-clobber.d => no-clobber.md} | 13 +- .../{no-keepalive.d => no-keepalive.md} | 10 +- docs/cmdline-opts/{no-npn.d => no-npn.md} | 11 +- ...-progress-meter.d => no-progress-meter.md} | 11 +- .../{no-sessionid.d => no-sessionid.md} | 10 +- docs/cmdline-opts/noproxy.d | 27 - docs/cmdline-opts/noproxy.md | 33 ++ docs/cmdline-opts/{ntlm-wb.d => ntlm-wb.md} | 13 +- docs/cmdline-opts/{ntlm.d => ntlm.md} | 10 +- .../{oauth2-bearer.d => oauth2-bearer.md} | 12 +- .../{output-dir.d => output-dir.md} | 11 +- docs/cmdline-opts/{output.d => output.md} | 30 +- docs/cmdline-opts/page-footer | 325 ----------- docs/cmdline-opts/page-header | 258 --------- ...llel-immediate.d => parallel-immediate.md} | 11 +- .../{parallel-max.d => parallel-max.md} | 10 +- docs/cmdline-opts/{parallel.d => parallel.md} | 11 +- docs/cmdline-opts/{pass.d => pass.md} | 11 +- .../{path-as-is.d => path-as-is.md} | 10 +- .../{pinnedpubkey.d => pinnedpubkey.md} | 12 +- docs/cmdline-opts/{post301.d => post301.md} | 12 +- docs/cmdline-opts/{post302.d => post302.md} | 12 +- docs/cmdline-opts/{post303.d => post303.md} | 12 +- docs/cmdline-opts/{preproxy.d => preproxy.md} | 11 +- .../{progress-bar.d => progress-bar.md} | 10 +- .../{proto-default.d => proto-default.md} | 11 +- .../{proto-redir.d => proto-redir.md} | 12 +- docs/cmdline-opts/{proto.d => proto.md} | 11 +- .../{proxy-anyauth.d => proxy-anyauth.md} | 12 +- .../{proxy-basic.d => proxy-basic.md} | 12 +- .../{proxy-ca-native.d => proxy-ca-native.md} | 12 +- .../{proxy-cacert.d => proxy-cacert.md} | 13 +- .../{proxy-capath.d => proxy-capath.md} | 12 +- .../{proxy-cert-type.d => proxy-cert-type.md} | 10 +- .../{proxy-cert.d => proxy-cert.md} | 10 +- .../{proxy-ciphers.d => proxy-ciphers.md} | 12 +- .../{proxy-crlfile.d => proxy-crlfile.md} | 11 +- .../{proxy-digest.d => proxy-digest.md} | 12 +- .../{proxy-header.d => proxy-header.md} | 14 +- .../{proxy-http2.d => proxy-http2.md} | 10 +- .../{proxy-insecure.d => proxy-insecure.md} | 11 +- .../{proxy-key-type.d => proxy-key-type.md} | 11 +- .../{proxy-key.d => proxy-key.md} | 11 +- .../{proxy-negotiate.d => proxy-negotiate.md} | 11 +- .../{proxy-ntlm.d => proxy-ntlm.md} | 11 +- .../{proxy-pass.d => proxy-pass.md} | 11 +- ...y-pinnedpubkey.d => proxy-pinnedpubkey.md} | 13 +- ...y-service-name.d => proxy-service-name.md} | 11 +- ...allow-beast.d => proxy-ssl-allow-beast.md} | 11 +- ...t-cert.d => proxy-ssl-auto-client-cert.md} | 11 +- ...tls13-ciphers.d => proxy-tls13-ciphers.md} | 12 +- ...oxy-tlsauthtype.d => proxy-tlsauthtype.md} | 11 +- ...oxy-tlspassword.d => proxy-tlspassword.md} | 11 +- .../{proxy-tlsuser.d => proxy-tlsuser.md} | 11 +- .../{proxy-tlsv1.d => proxy-tlsv1.md} | 10 +- .../{proxy-user.d => proxy-user.md} | 10 +- docs/cmdline-opts/{proxy.d => proxy.md} | 11 +- docs/cmdline-opts/{proxy1.0.d => proxy1.0.md} | 12 +- .../{proxytunnel.d => proxytunnel.md} | 10 +- docs/cmdline-opts/{pubkey.d => pubkey.md} | 10 +- docs/cmdline-opts/{quote.d => quote.md} | 10 +- .../{random-file.d => random-file.md} | 10 +- docs/cmdline-opts/{range.d => range.md} | 11 +- docs/cmdline-opts/{rate.d => rate.md} | 15 +- docs/cmdline-opts/{raw.d => raw.md} | 10 +- docs/cmdline-opts/{referer.d => referer.md} | 15 +- ...te-header-name.d => remote-header-name.md} | 10 +- .../{remote-name-all.d => remote-name-all.md} | 10 +- .../{remote-name.d => remote-name.md} | 12 +- .../{remote-time.d => remote-time.md} | 11 +- .../{remove-on-error.d => remove-on-error.md} | 10 +- .../{request-target.d => request-target.md} | 10 +- docs/cmdline-opts/{request.d => request.md} | 14 +- docs/cmdline-opts/{resolve.d => resolve.md} | 11 +- ...retry-all-errors.d => retry-all-errors.md} | 10 +- ...try-connrefused.d => retry-connrefused.md} | 11 +- .../{retry-delay.d => retry-delay.md} | 10 +- .../{retry-max-time.d => retry-max-time.md} | 10 +- docs/cmdline-opts/{retry.d => retry.md} | 10 +- .../{sasl-authzid.d => sasl-authzid.md} | 10 +- docs/cmdline-opts/{sasl-ir.d => sasl-ir.md} | 10 +- .../{service-name.d => service-name.md} | 11 +- .../{show-error.d => show-error.md} | 10 +- docs/cmdline-opts/{silent.d => silent.md} | 12 +- docs/cmdline-opts/{socks4.d => socks4.md} | 14 +- docs/cmdline-opts/{socks4a.d => socks4a.md} | 14 +- .../{socks5-basic.d => socks5-basic.md} | 12 +- ...cks5-gssapi-nec.d => socks5-gssapi-nec.md} | 10 +- ...api-service.d => socks5-gssapi-service.md} | 10 +- .../{socks5-gssapi.d => socks5-gssapi.md} | 12 +- .../{socks5-hostname.d => socks5-hostname.md} | 13 +- docs/cmdline-opts/{socks5.d => socks5.md} | 13 +- docs/cmdline-opts/speed-limit.d | 15 - docs/cmdline-opts/speed-limit.md | 23 + .../{speed-time.d => speed-time.md} | 11 +- .../{ssl-allow-beast.d => ssl-allow-beast.md} | 17 +- ...-client-cert.d => ssl-auto-client-cert.md} | 10 +- .../{ssl-no-revoke.d => ssl-no-revoke.md} | 10 +- docs/cmdline-opts/{ssl-reqd.d => ssl-reqd.md} | 11 +- ...est-effort.d => ssl-revoke-best-effort.md} | 11 +- docs/cmdline-opts/{ssl.d => ssl.md} | 12 +- docs/cmdline-opts/{sslv2.d => sslv2.md} | 11 +- docs/cmdline-opts/{sslv3.d => sslv3.md} | 11 +- docs/cmdline-opts/{stderr.d => stderr.md} | 11 +- .../{styled-output.d => styled-output.md} | 11 +- ...-headers.d => suppress-connect-headers.md} | 12 +- .../{tcp-fastopen.d => tcp-fastopen.md} | 10 +- .../{tcp-nodelay.d => tcp-nodelay.md} | 10 +- .../{telnet-option.d => telnet-option.md} | 16 +- .../{tftp-blksize.d => tftp-blksize.md} | 10 +- .../{tftp-no-options.d => tftp-no-options.md} | 10 +- .../{time-cond.d => time-cond.md} | 15 +- docs/cmdline-opts/{tls-max.d => tls-max.md} | 15 +- .../{tls13-ciphers.d => tls13-ciphers.md} | 12 +- .../{tlsauthtype.d => tlsauthtype.md} | 10 +- .../{tlspassword.d => tlspassword.md} | 10 +- docs/cmdline-opts/{tlsuser.d => tlsuser.md} | 10 +- docs/cmdline-opts/{tlsv1.0.d => tlsv1.0.md} | 10 +- docs/cmdline-opts/{tlsv1.1.d => tlsv1.1.md} | 11 +- docs/cmdline-opts/{tlsv1.2.d => tlsv1.2.md} | 11 +- docs/cmdline-opts/{tlsv1.3.d => tlsv1.3.md} | 11 +- docs/cmdline-opts/{tlsv1.d => tlsv1.md} | 11 +- .../{tr-encoding.d => tr-encoding.md} | 10 +- .../{trace-ascii.d => trace-ascii.md} | 11 +- .../{trace-config.d => trace-config.md} | 11 +- .../{trace-ids.d => trace-ids.md} | 11 +- .../{trace-time.d => trace-time.md} | 11 +- docs/cmdline-opts/{trace.d => trace.md} | 13 +- .../{unix-socket.d => unix-socket.md} | 10 +- .../{upload-file.d => upload-file.md} | 19 +- .../{url-query.d => url-query.md} | 19 +- docs/cmdline-opts/{url.d => url.md} | 11 +- .../{use-ascii.d => use-ascii.md} | 11 +- .../{user-agent.d => user-agent.md} | 11 +- docs/cmdline-opts/{user.d => user.md} | 15 +- docs/cmdline-opts/{variable.d => variable.md} | 10 +- docs/cmdline-opts/{verbose.d => verbose.md} | 13 +- docs/cmdline-opts/{version.d => version.md} | 73 +-- .../{write-out.d => write-out.md} | 151 ++--- docs/cmdline-opts/{xattr.d => xattr.md} | 16 +- tests/data/test1026 | 2 +- tests/data/test1478 | 2 +- tests/test1275.pl | 18 +- tests/test971.pl | 6 +- 295 files changed, 3961 insertions(+), 1832 deletions(-) create mode 100755 .github/scripts/cleancmd.pl create mode 100644 docs/cmdline-opts/_AUTHORS.md create mode 100644 docs/cmdline-opts/_BUGS.md create mode 100644 docs/cmdline-opts/_DESCRIPTION.md create mode 100644 docs/cmdline-opts/_ENVIRONMENT.md create mode 100644 docs/cmdline-opts/_EXITCODES.md create mode 100644 docs/cmdline-opts/_FILES.md create mode 100644 docs/cmdline-opts/_GLOBBING.md create mode 100644 docs/cmdline-opts/_NAME.md create mode 100644 docs/cmdline-opts/_OPTIONS.md create mode 100644 docs/cmdline-opts/_OUTPUT.md create mode 100644 docs/cmdline-opts/_PROGRESS.md create mode 100644 docs/cmdline-opts/_PROTOCOLS.md create mode 100644 docs/cmdline-opts/_PROXYPREFIX.md create mode 100644 docs/cmdline-opts/_SEEALSO.md create mode 100644 docs/cmdline-opts/_SYNOPSIS.md create mode 100644 docs/cmdline-opts/_URL.md create mode 100644 docs/cmdline-opts/_VARIABLES.md create mode 100644 docs/cmdline-opts/_VERSION.md create mode 100644 docs/cmdline-opts/_WWW.md rename docs/cmdline-opts/{abstract-unix-socket.d => abstract-unix-socket.md} (80%) rename docs/cmdline-opts/{alt-svc.d => alt-svc.md} (87%) rename docs/cmdline-opts/{anyauth.d => anyauth.md} (88%) rename docs/cmdline-opts/{append.d => append.md} (79%) rename docs/cmdline-opts/{aws-sigv4.d => aws-sigv4.md} (85%) rename docs/cmdline-opts/{basic.d => basic.md} (85%) rename docs/cmdline-opts/{ca-native.d => ca-native.md} (87%) rename docs/cmdline-opts/{cacert.d => cacert.md} (94%) rename docs/cmdline-opts/{capath.d => capath.md} (88%) rename docs/cmdline-opts/{cert-status.d => cert-status.md} (88%) rename docs/cmdline-opts/{cert-type.d => cert-type.md} (82%) rename docs/cmdline-opts/{cert.d => cert.md} (65%) rename docs/cmdline-opts/{ciphers.d => ciphers.md} (75%) rename docs/cmdline-opts/{compressed-ssh.d => compressed-ssh.md} (75%) rename docs/cmdline-opts/{compressed.d => compressed.md} (89%) rename docs/cmdline-opts/{config.d => config.md} (73%) rename docs/cmdline-opts/{connect-timeout.d => connect-timeout.md} (84%) delete mode 100644 docs/cmdline-opts/connect-to.d create mode 100644 docs/cmdline-opts/connect-to.md rename docs/cmdline-opts/{continue-at.d => continue-at.md} (88%) rename docs/cmdline-opts/{cookie-jar.d => cookie-jar.md} (90%) rename docs/cmdline-opts/{cookie.d => cookie.md} (93%) rename docs/cmdline-opts/{create-dirs.d => create-dirs.md} (85%) rename docs/cmdline-opts/{create-file-mode.d => create-file-mode.md} (78%) rename docs/cmdline-opts/{crlf.d => crlf.md} (78%) rename docs/cmdline-opts/{crlfile.d => crlfile.md} (78%) rename docs/cmdline-opts/{curves.d => curves.md} (66%) rename docs/cmdline-opts/{data-ascii.d => data-ascii.md} (68%) rename docs/cmdline-opts/{data-binary.d => data-binary.md} (90%) rename docs/cmdline-opts/{data-raw.d => data-raw.md} (74%) rename docs/cmdline-opts/{data-urlencode.d => data-urlencode.md} (86%) rename docs/cmdline-opts/{data.d => data.md} (90%) rename docs/cmdline-opts/{delegation.d => delegation.md} (85%) rename docs/cmdline-opts/{digest.d => digest.md} (80%) rename docs/cmdline-opts/{disable-eprt.d => disable-eprt.md} (89%) rename docs/cmdline-opts/{disable-epsv.d => disable-epsv.md} (85%) rename docs/cmdline-opts/{disable.d => disable.md} (87%) rename docs/cmdline-opts/{disallow-username-in-url.d => disallow-username-in-url.md} (77%) rename docs/cmdline-opts/{dns-interface.d => dns-interface.md} (79%) rename docs/cmdline-opts/{dns-ipv4-addr.d => dns-ipv4-addr.md} (78%) rename docs/cmdline-opts/{dns-ipv6-addr.d => dns-ipv6-addr.md} (77%) rename docs/cmdline-opts/{dns-servers.d => dns-servers.md} (77%) rename docs/cmdline-opts/{doh-cert-status.d => doh-cert-status.md} (69%) rename docs/cmdline-opts/{doh-insecure.d => doh-insecure.md} (70%) rename docs/cmdline-opts/{doh-url.d => doh-url.md} (87%) rename docs/cmdline-opts/{dump-header.d => dump-header.md} (87%) rename docs/cmdline-opts/{egd-file.d => egd-file.md} (83%) rename docs/cmdline-opts/{engine.d => engine.md} (82%) rename docs/cmdline-opts/{etag-compare.d => etag-compare.md} (86%) rename docs/cmdline-opts/{etag-save.d => etag-save.md} (81%) rename docs/cmdline-opts/{expect100-timeout.d => expect100-timeout.md} (85%) rename docs/cmdline-opts/{fail-early.d => fail-early.md} (90%) rename docs/cmdline-opts/{fail-with-body.d => fail-with-body.md} (87%) rename docs/cmdline-opts/{fail.d => fail.md} (89%) rename docs/cmdline-opts/{false-start.d => false-start.md} (86%) rename docs/cmdline-opts/{form-escape.d => form-escape.md} (75%) rename docs/cmdline-opts/{form-string.d => form-string.md} (87%) rename docs/cmdline-opts/{form.d => form.md} (75%) rename docs/cmdline-opts/{ftp-account.d => ftp-account.md} (77%) rename docs/cmdline-opts/{ftp-alternative-to-user.d => ftp-alternative-to-user.md} (78%) rename docs/cmdline-opts/{ftp-create-dirs.d => ftp-create-dirs.md} (77%) rename docs/cmdline-opts/{ftp-method.d => ftp-method.md} (80%) rename docs/cmdline-opts/{ftp-pasv.d => ftp-pasv.md} (86%) rename docs/cmdline-opts/{ftp-port.d => ftp-port.md} (84%) rename docs/cmdline-opts/{ftp-pret.d => ftp-pret.md} (79%) rename docs/cmdline-opts/{ftp-skip-pasv-ip.d => ftp-skip-pasv-ip.md} (84%) rename docs/cmdline-opts/{ftp-ssl-ccc-mode.d => ftp-ssl-ccc-mode.md} (78%) rename docs/cmdline-opts/{ftp-ssl-ccc.d => ftp-ssl-ccc.md} (80%) rename docs/cmdline-opts/{ftp-ssl-control.d => ftp-ssl-control.md} (66%) rename docs/cmdline-opts/{get.d => get.md} (79%) rename docs/cmdline-opts/{globoff.d => globoff.md} (83%) rename docs/cmdline-opts/{happy-eyeballs-timeout-ms.d => happy-eyeballs-timeout-ms.md} (87%) rename docs/cmdline-opts/{haproxy-clientip.d => haproxy-clientip.md} (92%) rename docs/cmdline-opts/{haproxy-protocol.d => haproxy-protocol.md} (85%) rename docs/cmdline-opts/{head.d => head.md} (83%) rename docs/cmdline-opts/{header.d => header.md} (93%) rename docs/cmdline-opts/{help.d => help.md} (89%) rename docs/cmdline-opts/{hostpubmd5.d => hostpubmd5.md} (52%) rename docs/cmdline-opts/{hostpubsha256.d => hostpubsha256.md} (77%) rename docs/cmdline-opts/{hsts.d => hsts.md} (92%) rename docs/cmdline-opts/{http0.9.d => http0.9.md} (84%) rename docs/cmdline-opts/{http1.0.d => http1.0.md} (80%) rename docs/cmdline-opts/{http1.1.d => http1.1.md} (77%) rename docs/cmdline-opts/{http2-prior-knowledge.d => http2-prior-knowledge.md} (83%) rename docs/cmdline-opts/{http2.d => http2.md} (88%) rename docs/cmdline-opts/{http3-only.d => http3-only.md} (89%) rename docs/cmdline-opts/{http3.d => http3.md} (92%) rename docs/cmdline-opts/{ignore-content-length.d => ignore-content-length.md} (84%) rename docs/cmdline-opts/{include.d => include.md} (91%) rename docs/cmdline-opts/{insecure.d => insecure.md} (90%) rename docs/cmdline-opts/{interface.d => interface.md} (80%) rename docs/cmdline-opts/{ipfs-gateway.d => ipfs-gateway.md} (70%) rename docs/cmdline-opts/{ipv4.d => ipv4.md} (82%) rename docs/cmdline-opts/{ipv6.d => ipv6.md} (82%) rename docs/cmdline-opts/{json.d => json.md} (75%) rename docs/cmdline-opts/{junk-session-cookies.d => junk-session-cookies.md} (78%) rename docs/cmdline-opts/{keepalive-time.d => keepalive-time.md} (65%) rename docs/cmdline-opts/{key-type.d => key-type.md} (81%) rename docs/cmdline-opts/{key.d => key.md} (74%) rename docs/cmdline-opts/{krb.d => krb.md} (82%) rename docs/cmdline-opts/{libcurl.d => libcurl.md} (83%) rename docs/cmdline-opts/{limit-rate.d => limit-rate.md} (86%) rename docs/cmdline-opts/{list-only.d => list-only.md} (93%) rename docs/cmdline-opts/{local-port.d => local-port.md} (70%) rename docs/cmdline-opts/{location-trusted.d => location-trusted.md} (73%) rename docs/cmdline-opts/{location.d => location.md} (94%) rename docs/cmdline-opts/{login-options.d => login-options.md} (65%) rename docs/cmdline-opts/{mail-auth.d => mail-auth.md} (74%) rename docs/cmdline-opts/{mail-from.d => mail-from.md} (68%) rename docs/cmdline-opts/{mail-rcpt-allowfails.d => mail-rcpt-allowfails.md} (84%) rename docs/cmdline-opts/{mail-rcpt.d => mail-rcpt.md} (85%) create mode 100644 docs/cmdline-opts/mainpage.idx rename docs/cmdline-opts/{manual.d => manual.md} (72%) rename docs/cmdline-opts/{max-filesize.d => max-filesize.md} (91%) rename docs/cmdline-opts/{max-redirs.d => max-redirs.md} (82%) rename docs/cmdline-opts/{max-time.d => max-time.md} (77%) rename docs/cmdline-opts/{metalink.d => metalink.md} (81%) rename docs/cmdline-opts/{negotiate.d => negotiate.md} (83%) rename docs/cmdline-opts/{netrc-file.d => netrc-file.md} (81%) rename docs/cmdline-opts/{netrc-optional.d => netrc-optional.md} (78%) rename docs/cmdline-opts/{netrc.d => netrc.md} (86%) rename docs/cmdline-opts/{next.d => next.md} (78%) rename docs/cmdline-opts/{no-alpn.d => no-alpn.md} (87%) rename docs/cmdline-opts/{no-buffer.d => no-buffer.md} (87%) rename docs/cmdline-opts/{no-clobber.d => no-clobber.md} (76%) rename docs/cmdline-opts/{no-keepalive.d => no-keepalive.md} (82%) rename docs/cmdline-opts/{no-npn.d => no-npn.md} (87%) rename docs/cmdline-opts/{no-progress-meter.d => no-progress-meter.md} (80%) rename docs/cmdline-opts/{no-sessionid.d => no-sessionid.md} (88%) delete mode 100644 docs/cmdline-opts/noproxy.d create mode 100644 docs/cmdline-opts/noproxy.md rename docs/cmdline-opts/{ntlm-wb.d => ntlm-wb.md} (62%) rename docs/cmdline-opts/{ntlm.d => ntlm.md} (89%) rename docs/cmdline-opts/{oauth2-bearer.d => oauth2-bearer.md} (80%) rename docs/cmdline-opts/{output-dir.d => output-dir.md} (82%) rename docs/cmdline-opts/{output.d => output.md} (67%) delete mode 100644 docs/cmdline-opts/page-footer delete mode 100644 docs/cmdline-opts/page-header rename docs/cmdline-opts/{parallel-immediate.d => parallel-immediate.md} (77%) rename docs/cmdline-opts/{parallel-max.d => parallel-max.md} (81%) rename docs/cmdline-opts/{parallel.d => parallel.md} (74%) rename docs/cmdline-opts/{pass.d => pass.md} (74%) rename docs/cmdline-opts/{path-as-is.d => path-as-is.md} (77%) rename docs/cmdline-opts/{pinnedpubkey.d => pinnedpubkey.md} (89%) rename docs/cmdline-opts/{post301.d => post301.md} (83%) rename docs/cmdline-opts/{post302.d => post302.md} (83%) rename docs/cmdline-opts/{post303.d => post303.md} (79%) rename docs/cmdline-opts/{preproxy.d => preproxy.md} (88%) rename docs/cmdline-opts/{progress-bar.d => progress-bar.md} (89%) rename docs/cmdline-opts/{proto-default.d => proto-default.md} (82%) rename docs/cmdline-opts/{proto-redir.d => proto-redir.md} (81%) rename docs/cmdline-opts/{proto.d => proto.md} (92%) rename docs/cmdline-opts/{proxy-anyauth.d => proxy-anyauth.md} (70%) rename docs/cmdline-opts/{proxy-basic.d => proxy-basic.md} (73%) rename docs/cmdline-opts/{proxy-ca-native.d => proxy-ca-native.md} (87%) rename docs/cmdline-opts/{proxy-cacert.d => proxy-cacert.md} (65%) rename docs/cmdline-opts/{proxy-capath.d => proxy-capath.md} (66%) rename docs/cmdline-opts/{proxy-cert-type.d => proxy-cert-type.md} (68%) rename docs/cmdline-opts/{proxy-cert.d => proxy-cert.md} (71%) rename docs/cmdline-opts/{proxy-ciphers.d => proxy-ciphers.md} (76%) rename docs/cmdline-opts/{proxy-crlfile.d => proxy-crlfile.md} (67%) rename docs/cmdline-opts/{proxy-digest.d => proxy-digest.md} (70%) rename docs/cmdline-opts/{proxy-header.d => proxy-header.md} (83%) rename docs/cmdline-opts/{proxy-http2.d => proxy-http2.md} (84%) rename docs/cmdline-opts/{proxy-insecure.d => proxy-insecure.md} (71%) rename docs/cmdline-opts/{proxy-key-type.d => proxy-key-type.md} (66%) rename docs/cmdline-opts/{proxy-key.d => proxy-key.md} (68%) rename docs/cmdline-opts/{proxy-negotiate.d => proxy-negotiate.md} (73%) rename docs/cmdline-opts/{proxy-ntlm.d => proxy-ntlm.md} (70%) rename docs/cmdline-opts/{proxy-pass.d => proxy-pass.md} (68%) rename docs/cmdline-opts/{proxy-pinnedpubkey.d => proxy-pinnedpubkey.md} (81%) rename docs/cmdline-opts/{proxy-service-name.d => proxy-service-name.md} (68%) rename docs/cmdline-opts/{proxy-ssl-allow-beast.d => proxy-ssl-allow-beast.md} (68%) rename docs/cmdline-opts/{proxy-ssl-auto-client-cert.d => proxy-ssl-auto-client-cert.md} (66%) rename docs/cmdline-opts/{proxy-tls13-ciphers.d => proxy-tls13-ciphers.md} (81%) rename docs/cmdline-opts/{proxy-tlsauthtype.d => proxy-tlsauthtype.md} (69%) rename docs/cmdline-opts/{proxy-tlspassword.d => proxy-tlspassword.md} (67%) rename docs/cmdline-opts/{proxy-tlsuser.d => proxy-tlsuser.md} (67%) rename docs/cmdline-opts/{proxy-tlsv1.d => proxy-tlsv1.md} (72%) rename docs/cmdline-opts/{proxy-user.d => proxy-user.md} (90%) rename docs/cmdline-opts/{proxy.d => proxy.md} (94%) rename docs/cmdline-opts/{proxy1.0.d => proxy1.0.md} (81%) rename docs/cmdline-opts/{proxytunnel.d => proxytunnel.md} (86%) rename docs/cmdline-opts/{pubkey.d => pubkey.md} (87%) rename docs/cmdline-opts/{quote.d => quote.md} (97%) rename docs/cmdline-opts/{random-file.d => random-file.md} (84%) rename docs/cmdline-opts/{range.d => range.md} (94%) rename docs/cmdline-opts/{rate.d => rate.md} (90%) rename docs/cmdline-opts/{raw.d => raw.md} (83%) rename docs/cmdline-opts/{referer.d => referer.md} (74%) rename docs/cmdline-opts/{remote-header-name.d => remote-header-name.md} (93%) rename docs/cmdline-opts/{remote-name-all.d => remote-name-all.md} (77%) rename docs/cmdline-opts/{remote-name.d => remote-name.md} (89%) rename docs/cmdline-opts/{remote-time.d => remote-time.md} (78%) rename docs/cmdline-opts/{remove-on-error.d => remove-on-error.md} (83%) rename docs/cmdline-opts/{request-target.d => request-target.md} (86%) rename docs/cmdline-opts/{request.d => request.md} (90%) rename docs/cmdline-opts/{resolve.d => resolve.md} (93%) rename docs/cmdline-opts/{retry-all-errors.d => retry-all-errors.md} (94%) rename docs/cmdline-opts/{retry-connrefused.d => retry-connrefused.md} (74%) rename docs/cmdline-opts/{retry-delay.d => retry-delay.md} (84%) rename docs/cmdline-opts/{retry-max-time.d => retry-max-time.md} (86%) rename docs/cmdline-opts/{retry.d => retry.md} (93%) rename docs/cmdline-opts/{sasl-authzid.d => sasl-authzid.md} (86%) rename docs/cmdline-opts/{sasl-ir.d => sasl-ir.md} (73%) rename docs/cmdline-opts/{service-name.d => service-name.md} (68%) rename docs/cmdline-opts/{show-error.d => show-error.md} (75%) rename docs/cmdline-opts/{silent.d => silent.md} (83%) rename docs/cmdline-opts/{socks4.d => socks4.md} (85%) rename docs/cmdline-opts/{socks4a.d => socks4a.md} (85%) rename docs/cmdline-opts/{socks5-basic.d => socks5-basic.md} (67%) rename docs/cmdline-opts/{socks5-gssapi-nec.d => socks5-gssapi-nec.md} (81%) rename docs/cmdline-opts/{socks5-gssapi-service.d => socks5-gssapi-service.md} (72%) rename docs/cmdline-opts/{socks5-gssapi.d => socks5-gssapi.md} (67%) rename docs/cmdline-opts/{socks5-hostname.d => socks5-hostname.md} (85%) rename docs/cmdline-opts/{socks5.d => socks5.md} (86%) delete mode 100644 docs/cmdline-opts/speed-limit.d create mode 100644 docs/cmdline-opts/speed-limit.md rename docs/cmdline-opts/{speed-time.d => speed-time.md} (83%) rename docs/cmdline-opts/{ssl-allow-beast.d => ssl-allow-beast.md} (57%) rename docs/cmdline-opts/{ssl-auto-client-cert.d => ssl-auto-client-cert.md} (81%) rename docs/cmdline-opts/{ssl-no-revoke.d => ssl-no-revoke.md} (82%) rename docs/cmdline-opts/{ssl-reqd.d => ssl-reqd.md} (88%) rename docs/cmdline-opts/{ssl-revoke-best-effort.d => ssl-revoke-best-effort.md} (78%) rename docs/cmdline-opts/{ssl.d => ssl.md} (89%) rename docs/cmdline-opts/{sslv2.d => sslv2.md} (83%) rename docs/cmdline-opts/{sslv3.d => sslv3.md} (83%) rename docs/cmdline-opts/{stderr.d => stderr.md} (78%) rename docs/cmdline-opts/{styled-output.d => styled-output.md} (83%) rename docs/cmdline-opts/{suppress-connect-headers.d => suppress-connect-headers.md} (77%) rename docs/cmdline-opts/{tcp-fastopen.d => tcp-fastopen.md} (82%) rename docs/cmdline-opts/{tcp-nodelay.d => tcp-nodelay.md} (83%) rename docs/cmdline-opts/{telnet-option.d => telnet-option.md} (68%) rename docs/cmdline-opts/{tftp-blksize.d => tftp-blksize.md} (77%) rename docs/cmdline-opts/{tftp-no-options.d => tftp-no-options.md} (79%) rename docs/cmdline-opts/{time-cond.d => time-cond.md} (84%) rename docs/cmdline-opts/{tls-max.d => tls-max.md} (81%) rename docs/cmdline-opts/{tls13-ciphers.d => tls13-ciphers.md} (82%) rename docs/cmdline-opts/{tlsauthtype.d => tlsauthtype.md} (87%) rename docs/cmdline-opts/{tlspassword.d => tlspassword.md} (79%) rename docs/cmdline-opts/{tlsuser.d => tlsuser.md} (79%) rename docs/cmdline-opts/{tlsv1.0.d => tlsv1.0.md} (87%) rename docs/cmdline-opts/{tlsv1.1.d => tlsv1.1.md} (85%) rename docs/cmdline-opts/{tlsv1.2.d => tlsv1.2.md} (85%) rename docs/cmdline-opts/{tlsv1.3.d => tlsv1.3.md} (84%) rename docs/cmdline-opts/{tlsv1.d => tlsv1.md} (83%) rename docs/cmdline-opts/{tr-encoding.d => tr-encoding.md} (81%) rename docs/cmdline-opts/{trace-ascii.d => trace-ascii.md} (89%) rename docs/cmdline-opts/{trace-config.d => trace-config.md} (86%) rename docs/cmdline-opts/{trace-ids.d => trace-ids.md} (76%) rename docs/cmdline-opts/{trace-time.d => trace-time.md} (72%) rename docs/cmdline-opts/{trace.d => trace.md} (84%) rename docs/cmdline-opts/{unix-socket.d => unix-socket.md} (74%) rename docs/cmdline-opts/{upload-file.d => upload-file.md} (86%) rename docs/cmdline-opts/{url-query.d => url-query.md} (69%) rename docs/cmdline-opts/{url.d => url.md} (92%) rename docs/cmdline-opts/{use-ascii.d => use-ascii.md} (79%) rename docs/cmdline-opts/{user-agent.d => user-agent.md} (86%) rename docs/cmdline-opts/{user.d => user.md} (91%) rename docs/cmdline-opts/{variable.d => variable.md} (95%) rename docs/cmdline-opts/{verbose.d => verbose.md} (90%) rename docs/cmdline-opts/{version.d => version.md} (77%) rename docs/cmdline-opts/{write-out.d => write-out.md} (86%) rename docs/cmdline-opts/{xattr.d => xattr.md} (60%) diff --git a/.github/scripts/cleancmd.pl b/.github/scripts/cleancmd.pl new file mode 100755 index 00000000000..5d0fe2b2fbb --- /dev/null +++ b/.github/scripts/cleancmd.pl @@ -0,0 +1,52 @@ +#!/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); + +open(O, ">$f") or die; +print O @out; +close(O); diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index 182a3bdb46c..e9ac0134f6f 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -50,6 +50,7 @@ backend backends backoff backticks +balancers Baratov basename bashrc @@ -445,6 +446,7 @@ Makefile makefiles malloc mallocs +manpage maprintf Marek Mavrogiannopoulos diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml index ec2813c3ed2..ba92efabb41 100644 --- a/.github/workflows/linkcheck.yml +++ b/.github/workflows/linkcheck.yml @@ -31,6 +31,11 @@ jobs: runs-on: ubuntu-latest steps: - 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/spellcheck.yml b/.github/workflows/spellcheck.yml index f08538ad5e4..a619fcc0469 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -57,6 +57,12 @@ jobs: perl -pi -e 's/\-\-[\a-z0-9-]*//ig' docs/curl.md perl -pi -e 's!https://[a-z0-9%/.-]*!!ig' docs/curl.md + - name: trim the cmdline docs markdown files + run: find docs/cmdline-opts -name "*.md" ! -name "_*" ! -name MANPAGE.md | xargs -n1 ./.github/scripts/cleancmd.pl + + - name: trim the cmdline docs markdown _*.md files + run: find docs/cmdline-opts -name "_*.md" | xargs -n1 ./.github/scripts/cleancmd.pl --no-header + - name: setup the custom wordlist run: grep -v '^#' .github/scripts/spellcheck.words > wordlist.txt diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 4896f8513ef..951cbe859ec 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -9,24 +9,38 @@ This 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`. +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. -Each file has a set of meta-data and a body of text. +The documentation files that do not document options have no meta-data part. + +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,7 +70,7 @@ 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. -Within the body, describe a lite of items like this: +Within the body, describe a list of items like this: ## item 1 description @@ -67,12 +83,20 @@ explicitly with an empty "header": ## -## Header and footer +### Headers + +The `#` header can be used by non-option files and it produces 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. -`page-header` is the file that is output before the generated options output -for the master man page. +### Variables -`page-footer` is appended after all the individual options. +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 diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index 5a8996bc227..6fff55f484f 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -28,7 +28,7 @@ MANPAGE = $(top_builddir)/docs/curl.1 include Makefile.inc -EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl $(OTHERPAGES) CMakeLists.txt +EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl $(SUPPORT) CMakeLists.txt mainpage.idx GEN = $(GN_$(V)) GN_0 = @echo " GENERATE" $@; @@ -37,5 +37,5 @@ GN_ = $(GN_0) all: $(MANPAGE) -$(MANPAGE): $(DPAGES) $(OTHERPAGES) Makefile.inc gen.pl +$(MANPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl $(GEN)(rm -f $(MANPAGE) && cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES) > $(builddir)/manpage.tmp && mv $(builddir)/manpage.tmp $(MANPAGE)) 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..cf30d47404b --- /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 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 + + 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 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". + +## `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 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. + +## `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..ac7ab5ca15e --- /dev/null +++ b/docs/cmdline-opts/_EXITCODES.md @@ -0,0 +1,201 @@ + + +# 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 user name, 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. +## 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..66fc5dbb7e7 --- /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" + +or you can get sequences of alphanumeric series by using [] as in: + + "ftp://ftp.example.com/file[1-100].txt" + +And with leading zeroes: + + "ftp://ftp.example.com/file[001-100].txt" + +Or 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..1b25566591f --- /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..80e36f10245 --- /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..b834f9ae36c --- /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 +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. +## 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..0084ec61283 --- /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 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. diff --git a/docs/cmdline-opts/_VARIABLES.md b/docs/cmdline-opts/_VARIABLES.md new file mode 100644 index 00000000000..0415fd78f24 --- /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 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. diff --git a/docs/cmdline-opts/_VERSION.md b/docs/cmdline-opts/_VERSION.md new file mode 100644 index 00000000000..4c759f14705 --- /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.md similarity index 80% rename from docs/cmdline-opts/abstract-unix-socket.d rename to docs/cmdline-opts/abstract-unix-socket.md index 5c2fd4a4762..27bc8cad6cb 100644 --- a/docs/cmdline-opts/abstract-unix-socket.d +++ b/docs/cmdline-opts/abstract-unix-socket.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: abstract-unix-socket @@ -6,10 +7,15 @@ 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 +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.md similarity index 87% rename from docs/cmdline-opts/alt-svc.d rename to docs/cmdline-opts/alt-svc.md index 276ac1b669d..0a0f17df5a2 100644 --- a/docs/cmdline-opts/alt-svc.d +++ b/docs/cmdline-opts/alt-svc.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: alt-svc @@ -6,10 +7,16 @@ 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 +See-also: + - resolve + - connect-to +Example: + - --alt-svc svc.txt $URL --- + +# `--alt-svc` + 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. diff --git a/docs/cmdline-opts/anyauth.d b/docs/cmdline-opts/anyauth.md similarity index 88% rename from docs/cmdline-opts/anyauth.d rename to docs/cmdline-opts/anyauth.md index 2498bdcd848..150e069e815 100644 --- a/docs/cmdline-opts/anyauth.d +++ b/docs/cmdline-opts/anyauth.md @@ -1,14 +1,22 @@ +--- 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 +See-also: + - proxy-anyauth + - basic + - digest +Example: + - --anyauth --user me:pwd $URL --- + +# `--anyauth` + 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 diff --git a/docs/cmdline-opts/append.d b/docs/cmdline-opts/append.md similarity index 79% rename from docs/cmdline-opts/append.d rename to docs/cmdline-opts/append.md index 7561c951c58..3d0030d6a73 100644 --- a/docs/cmdline-opts/append.d +++ b/docs/cmdline-opts/append.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Short: a @@ -5,11 +6,17 @@ 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 +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 diff --git a/docs/cmdline-opts/aws-sigv4.d b/docs/cmdline-opts/aws-sigv4.md similarity index 85% rename from docs/cmdline-opts/aws-sigv4.d rename to docs/cmdline-opts/aws-sigv4.md index 4b480f50cab..1b3909244f0 100644 --- a/docs/cmdline-opts/aws-sigv4.d +++ b/docs/cmdline-opts/aws-sigv4.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: aws-sigv4 @@ -6,10 +7,16 @@ 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 +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 diff --git a/docs/cmdline-opts/basic.d b/docs/cmdline-opts/basic.md similarity index 85% rename from docs/cmdline-opts/basic.d rename to docs/cmdline-opts/basic.md index cb0642620e5..34b019175bb 100644 --- a/docs/cmdline-opts/basic.d +++ b/docs/cmdline-opts/basic.md @@ -1,14 +1,20 @@ +--- 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 +See-also: + - proxy-basic +Example: + - -u name:password --basic $URL --- + +# `--basic` + 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 diff --git a/docs/cmdline-opts/ca-native.d b/docs/cmdline-opts/ca-native.md similarity index 87% rename from docs/cmdline-opts/ca-native.d rename to docs/cmdline-opts/ca-native.md index 9a8184c640f..d0b4bfa5a73 100644 --- a/docs/cmdline-opts/ca-native.d +++ b/docs/cmdline-opts/ca-native.md @@ -1,14 +1,22 @@ +--- 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 +See-also: + - cacert + - capath + - insecure +Example: + - --ca-native $URL --- + +# `--ca-native` + 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 diff --git a/docs/cmdline-opts/cacert.d b/docs/cmdline-opts/cacert.md similarity index 94% rename from docs/cmdline-opts/cacert.d rename to docs/cmdline-opts/cacert.md index 7b63f810bb0..7b1b2174ba6 100644 --- a/docs/cmdline-opts/cacert.d +++ b/docs/cmdline-opts/cacert.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: cacert @@ -5,11 +6,17 @@ 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 +See-also: + - capath + - insecure +Example: + - --cacert CA-file.txt $URL --- + +# `--cacert` + 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 diff --git a/docs/cmdline-opts/capath.d b/docs/cmdline-opts/capath.md similarity index 88% rename from docs/cmdline-opts/capath.d rename to docs/cmdline-opts/capath.md index 75e9f2e400a..ecd28df2413 100644 --- a/docs/cmdline-opts/capath.d +++ b/docs/cmdline-opts/capath.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: capath @@ -5,11 +6,17 @@ 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 +See-also: + - cacert + - insecure +Example: + - --capath /local/directory $URL --- + +# `--capath` + 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 diff --git a/docs/cmdline-opts/cert-status.d b/docs/cmdline-opts/cert-status.md similarity index 88% rename from docs/cmdline-opts/cert-status.d rename to docs/cmdline-opts/cert-status.md index e2d1d7aa249..bfbd3af835b 100644 --- a/docs/cmdline-opts/cert-status.d +++ b/docs/cmdline-opts/cert-status.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: cert-status @@ -5,10 +6,15 @@ 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 +See-also: + - pinnedpubkey +Example: + - --cert-status $URL --- + +# `--cert-status` + Tells curl to verify the status of the server certificate by using the Certificate Status Request (aka. OCSP stapling) TLS extension. diff --git a/docs/cmdline-opts/cert-type.d b/docs/cmdline-opts/cert-type.md similarity index 82% rename from docs/cmdline-opts/cert-type.d rename to docs/cmdline-opts/cert-type.md index cf9f17b7d5b..a0030a59dae 100644 --- a/docs/cmdline-opts/cert-type.d +++ b/docs/cmdline-opts/cert-type.md @@ -1,15 +1,23 @@ +--- 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 +See-also: + - cert + - key + - key-type +Example: + - --cert-type PEM --cert file $URL --- + +# `--cert-type` + Tells curl what type the provided client certificate is using. PEM, DER, ENG and P12 are recognized types. diff --git a/docs/cmdline-opts/cert.d b/docs/cmdline-opts/cert.md similarity index 65% rename from docs/cmdline-opts/cert.d rename to docs/cmdline-opts/cert.md index 56d0df7fdf8..6df5d0ebf7f 100644 --- a/docs/cmdline-opts/cert.d +++ b/docs/cmdline-opts/cert.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Short: E @@ -5,12 +6,19 @@ 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 +See-also: + - cert-type + - key + - key-type +Example: + - --cert certfile --key keyfile $URL --- + +# `--cert` + 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 @@ -19,10 +27,10 @@ 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. +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 @@ -37,13 +45,12 @@ 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 +(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*. +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.md similarity index 75% rename from docs/cmdline-opts/ciphers.d rename to docs/cmdline-opts/ciphers.md index a30902bdb87..9d7e0c6fe03 100644 --- a/docs/cmdline-opts/ciphers.d +++ b/docs/cmdline-opts/ciphers.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ciphers @@ -5,11 +6,18 @@ 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 +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: diff --git a/docs/cmdline-opts/compressed-ssh.d b/docs/cmdline-opts/compressed-ssh.md similarity index 75% rename from docs/cmdline-opts/compressed-ssh.d rename to docs/cmdline-opts/compressed-ssh.md index 897395677bc..c52e5a7a37a 100644 --- a/docs/cmdline-opts/compressed-ssh.d +++ b/docs/cmdline-opts/compressed-ssh.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: compressed-ssh @@ -5,9 +6,14 @@ 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 +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.md similarity index 89% rename from docs/cmdline-opts/compressed.d rename to docs/cmdline-opts/compressed.md index bb1d3baa744..35bbab81396 100644 --- a/docs/cmdline-opts/compressed.d +++ b/docs/cmdline-opts/compressed.md @@ -1,14 +1,20 @@ +--- 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 +See-also: + - compressed-ssh +Example: + - --compressed $URL --- + +# `--compressed` + Request a compressed response using one of the algorithms curl supports, and automatically decompress the content. diff --git a/docs/cmdline-opts/config.d b/docs/cmdline-opts/config.md similarity index 73% rename from docs/cmdline-opts/config.d rename to docs/cmdline-opts/config.md index c22a827f617..2f393e27e3b 100644 --- a/docs/cmdline-opts/config.d +++ b/docs/cmdline-opts/config.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: config @@ -5,11 +6,16 @@ Arg: Help: Read config from a file Short: K Category: curl -Example: --config file.txt $URL Added: 4.10 -See-also: disable 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. @@ -22,9 +28,9 @@ 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. +(=), 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. @@ -38,19 +44,19 @@ 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/" + url = "https://curl.se/docs/" - # --- Example file --- - # this is a comment - url = "example.com" - output = "curlhere.html" - user-agent = "superagent/1.0" + # --- 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 --- + # 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 @@ -62,11 +68,11 @@ config file is checked for in the following places in this order: 3) **"$HOME/.curlrc"** -4) Windows: **"%USERPROFILE%\\.curlrc"** +4) Windows: **"%USERPROFILE%\.curlrc"** -5) Windows: **"%APPDATA%\\.curlrc"** +5) Windows: **"%APPDATA%\.curlrc"** -6) Windows: **"%USERPROFILE%\\Application Data\\.curlrc"** +6) Windows: **"%USERPROFILE%\Application Data\.curlrc"** 7) Non-Windows: use getpwuid to find the home directory diff --git a/docs/cmdline-opts/connect-timeout.d b/docs/cmdline-opts/connect-timeout.md similarity index 84% rename from docs/cmdline-opts/connect-timeout.d rename to docs/cmdline-opts/connect-timeout.md index b3d19b3c332..f7281b09a94 100644 --- a/docs/cmdline-opts/connect-timeout.d +++ b/docs/cmdline-opts/connect-timeout.md @@ -1,16 +1,22 @@ +--- 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 +See-also: + - max-time +Example: + - --connect-timeout 20 $URL + - --connect-timeout 3.14 $URL --- -Maximum time in seconds that you allow curl's connection to take. This only + +# `--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. diff --git a/docs/cmdline-opts/connect-to.d b/docs/cmdline-opts/connect-to.d deleted file mode 100644 index f7da551592d..00000000000 --- a/docs/cmdline-opts/connect-to.d +++ /dev/null @@ -1,23 +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..7cd0aa857f2 --- /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 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 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.md similarity index 88% rename from docs/cmdline-opts/continue-at.d rename to docs/cmdline-opts/continue-at.md index a4fc1a96950..67a79fd70c9 100644 --- a/docs/cmdline-opts/continue-at.d +++ b/docs/cmdline-opts/continue-at.md @@ -1,16 +1,22 @@ +--- 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 +See-also: + - range +Example: + - -C - $URL + - -C 400 $URL --- + +# `--continue-at` + 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 diff --git a/docs/cmdline-opts/cookie-jar.d b/docs/cmdline-opts/cookie-jar.md similarity index 90% rename from docs/cmdline-opts/cookie-jar.d rename to docs/cmdline-opts/cookie-jar.md index 28738cac946..5453152e444 100644 --- a/docs/cmdline-opts/cookie-jar.d +++ b/docs/cmdline-opts/cookie-jar.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Short: c @@ -6,12 +7,17 @@ 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 +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. If no cookies are known, no data is diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.md similarity index 93% rename from docs/cmdline-opts/cookie.d rename to docs/cmdline-opts/cookie.md index 108846c062b..d0a6d353966 100644 --- a/docs/cmdline-opts/cookie.d +++ b/docs/cmdline-opts/cookie.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Short: b @@ -6,13 +7,19 @@ Arg: Protocols: HTTP Help: Send cookies from string/file Category: http -Example: -b "" $URL -Example: -b cookiefile $URL -Example: -b cookiefile -c cookiefile $URL -See-also: cookie-jar junk-session-cookies Added: 4.9 Multi: append +See-also: + - cookie-jar + - junk-session-cookies +Example: + - -b "" $URL + - -b cookiefile $URL + - -b cookiefile -c cookiefile $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". This makes curl use the diff --git a/docs/cmdline-opts/create-dirs.d b/docs/cmdline-opts/create-dirs.md similarity index 85% rename from docs/cmdline-opts/create-dirs.d rename to docs/cmdline-opts/create-dirs.md index 966b70384ee..de48807d4c7 100644 --- a/docs/cmdline-opts/create-dirs.d +++ b/docs/cmdline-opts/create-dirs.md @@ -1,13 +1,20 @@ +--- 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 +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 diff --git a/docs/cmdline-opts/create-file-mode.d b/docs/cmdline-opts/create-file-mode.md similarity index 78% rename from docs/cmdline-opts/create-file-mode.d rename to docs/cmdline-opts/create-file-mode.md index c0ebc08d449..c6467d15a4d 100644 --- a/docs/cmdline-opts/create-file-mode.d +++ b/docs/cmdline-opts/create-file-mode.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: create-file-mode @@ -5,11 +6,16 @@ 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 +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. diff --git a/docs/cmdline-opts/crlf.d b/docs/cmdline-opts/crlf.md similarity index 78% rename from docs/cmdline-opts/crlf.d rename to docs/cmdline-opts/crlf.md index ea7fb1526ab..81a14ef6fd9 100644 --- a/docs/cmdline-opts/crlf.d +++ b/docs/cmdline-opts/crlf.md @@ -1,14 +1,20 @@ +--- 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 +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)**. diff --git a/docs/cmdline-opts/crlfile.d b/docs/cmdline-opts/crlfile.md similarity index 78% rename from docs/cmdline-opts/crlfile.d rename to docs/cmdline-opts/crlfile.md index da0d239bad7..16bd7b35b98 100644 --- a/docs/cmdline-opts/crlfile.d +++ b/docs/cmdline-opts/crlfile.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: crlfile @@ -6,9 +7,15 @@ Protocols: TLS Help: Use this CRL list Added: 7.19.7 Category: tls -Example: --crlfile rejects.txt $URL -See-also: cacert capath 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.md similarity index 66% rename from docs/cmdline-opts/curves.d rename to docs/cmdline-opts/curves.md index 58d472d20df..99f1ad48a75 100644 --- a/docs/cmdline-opts/curves.d +++ b/docs/cmdline-opts/curves.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: curves @@ -6,14 +7,19 @@ 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 +See-also: + - ciphers +Example: + - --curves X25519 $URL --- + +# `--curves` + 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. +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 diff --git a/docs/cmdline-opts/data-ascii.d b/docs/cmdline-opts/data-ascii.md similarity index 68% rename from docs/cmdline-opts/data-ascii.d rename to docs/cmdline-opts/data-ascii.md index 5c7840bbc4f..124dee13c05 100644 --- a/docs/cmdline-opts/data-ascii.d +++ b/docs/cmdline-opts/data-ascii.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: data-ascii @@ -5,9 +6,16 @@ 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 +See-also: + - data-binary + - data-raw + - data-urlencode +Example: + - --data-ascii @file $URL --- + +# `--data-ascii` + This is just an alias for --data. diff --git a/docs/cmdline-opts/data-binary.d b/docs/cmdline-opts/data-binary.md similarity index 90% rename from docs/cmdline-opts/data-binary.d rename to docs/cmdline-opts/data-binary.md index 2cedda97b04..3d563fbdd7d 100644 --- a/docs/cmdline-opts/data-binary.d +++ b/docs/cmdline-opts/data-binary.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: data-binary @@ -5,11 +6,16 @@ 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 +See-also: + - data-ascii +Example: + - --data-binary @filename $URL --- + +# `--data-binary` + 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 diff --git a/docs/cmdline-opts/data-raw.d b/docs/cmdline-opts/data-raw.md similarity index 74% rename from docs/cmdline-opts/data-raw.d rename to docs/cmdline-opts/data-raw.md index e6a5a5b2b9e..2cb46938b52 100644 --- a/docs/cmdline-opts/data-raw.d +++ b/docs/cmdline-opts/data-raw.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: data-raw @@ -5,11 +6,16 @@ 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 +See-also: + - data +Example: + - --data-raw "hello" $URL + - --data-raw "@at@at@" $URL --- + +# `--data-raw` + This posts 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.md similarity index 86% rename from docs/cmdline-opts/data-urlencode.d rename to docs/cmdline-opts/data-urlencode.md index 51c0b4b7ce2..4d3f2981335 100644 --- a/docs/cmdline-opts/data-urlencode.d +++ b/docs/cmdline-opts/data-urlencode.md @@ -1,18 +1,25 @@ +--- 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 +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` + This posts data, similar to the other --data options with the exception that this performs URL-encoding. diff --git a/docs/cmdline-opts/data.d b/docs/cmdline-opts/data.md similarity index 90% rename from docs/cmdline-opts/data.d rename to docs/cmdline-opts/data.md index f1d67b95069..fb3b8487230 100644 --- a/docs/cmdline-opts/data.d +++ b/docs/cmdline-opts/data.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: data @@ -5,15 +6,22 @@ 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 +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 makes curl pass the data to the server using the diff --git a/docs/cmdline-opts/delegation.d b/docs/cmdline-opts/delegation.md similarity index 85% rename from docs/cmdline-opts/delegation.d rename to docs/cmdline-opts/delegation.md index 004514f37b9..3d6cff89974 100644 --- a/docs/cmdline-opts/delegation.d +++ b/docs/cmdline-opts/delegation.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: delegation @@ -5,11 +6,17 @@ 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 +See-also: + - insecure + - ssl +Example: + - --delegation "none" $URL --- + +# `--delegation` + Set LEVEL to tell the server what it is allowed to delegate when it comes to user credentials. diff --git a/docs/cmdline-opts/digest.d b/docs/cmdline-opts/digest.md similarity index 80% rename from docs/cmdline-opts/digest.d rename to docs/cmdline-opts/digest.md index f2ee551c5e3..f05c01fed08 100644 --- a/docs/cmdline-opts/digest.d +++ b/docs/cmdline-opts/digest.md @@ -1,15 +1,23 @@ +--- 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 +See-also: + - user + - proxy-digest + - anyauth +Example: + - -u name:password --digest $URL --- + +# `--digest` + 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/disable-eprt.d b/docs/cmdline-opts/disable-eprt.md similarity index 89% rename from docs/cmdline-opts/disable-eprt.d rename to docs/cmdline-opts/disable-eprt.md index b6d382bafaa..80ae0569119 100644 --- a/docs/cmdline-opts/disable-eprt.d +++ b/docs/cmdline-opts/disable-eprt.md @@ -1,14 +1,21 @@ +--- 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 +See-also: + - disable-epsv + - ftp-port +Example: + - --disable-eprt ftp://example.com/ --- + +# `--disable-eprt` + 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 diff --git a/docs/cmdline-opts/disable-epsv.d b/docs/cmdline-opts/disable-epsv.md similarity index 85% rename from docs/cmdline-opts/disable-epsv.d rename to docs/cmdline-opts/disable-epsv.md index f02df763da7..f4a8de8c04a 100644 --- a/docs/cmdline-opts/disable-epsv.d +++ b/docs/cmdline-opts/disable-epsv.md @@ -1,14 +1,21 @@ +--- 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 +See-also: + - disable-eprt + - ftp-port +Example: + - --disable-epsv ftp://example.com/ --- + +# `--disable-epsv` + 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. diff --git a/docs/cmdline-opts/disable.d b/docs/cmdline-opts/disable.md similarity index 87% rename from docs/cmdline-opts/disable.d rename to docs/cmdline-opts/disable.md index 979c039915a..e22a2bb4a0a 100644 --- a/docs/cmdline-opts/disable.d +++ b/docs/cmdline-opts/disable.md @@ -1,14 +1,20 @@ +--- 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 +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. diff --git a/docs/cmdline-opts/disallow-username-in-url.d b/docs/cmdline-opts/disallow-username-in-url.md similarity index 77% rename from docs/cmdline-opts/disallow-username-in-url.d rename to docs/cmdline-opts/disallow-username-in-url.md index 0e70ba91f64..faa4d8834fb 100644 --- a/docs/cmdline-opts/disallow-username-in-url.d +++ b/docs/cmdline-opts/disallow-username-in-url.md @@ -1,12 +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 -See-also: proto Category: curl -Example: --disallow-username-in-url $URL Multi: boolean +See-also: + - proto +Example: + - --disallow-username-in-url $URL --- + +# `--disallow-username-in-url` + 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/dns-interface.d b/docs/cmdline-opts/dns-interface.md similarity index 79% rename from docs/cmdline-opts/dns-interface.d rename to docs/cmdline-opts/dns-interface.md index fd924b897ae..afc5573e55a 100644 --- a/docs/cmdline-opts/dns-interface.d +++ b/docs/cmdline-opts/dns-interface.md @@ -1,16 +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 -See-also: dns-ipv4-addr dns-ipv6-addr Added: 7.33.0 Requires: c-ares Category: dns -Example: --dns-interface eth0 $URL Multi: single +See-also: + - dns-ipv4-addr + - dns-ipv6-addr +Example: + - --dns-interface eth0 $URL --- + +# `--dns-interface` + 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-ipv4-addr.d b/docs/cmdline-opts/dns-ipv4-addr.md similarity index 78% rename from docs/cmdline-opts/dns-ipv4-addr.d rename to docs/cmdline-opts/dns-ipv4-addr.md index 5930557397c..ff4163bc164 100644 --- a/docs/cmdline-opts/dns-ipv4-addr.d +++ b/docs/cmdline-opts/dns-ipv4-addr.md @@ -1,16 +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 -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 +See-also: + - dns-interface + - dns-ipv6-addr +Example: + - --dns-ipv4-addr 10.1.2.3 $URL --- + +# `--dns-ipv4-addr` + 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-ipv6-addr.d b/docs/cmdline-opts/dns-ipv6-addr.md similarity index 77% rename from docs/cmdline-opts/dns-ipv6-addr.d rename to docs/cmdline-opts/dns-ipv6-addr.md index a76120cdc12..7d4d1c1f571 100644 --- a/docs/cmdline-opts/dns-ipv6-addr.d +++ b/docs/cmdline-opts/dns-ipv6-addr.md @@ -1,16 +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 -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 +See-also: + - dns-interface + - dns-ipv4-addr +Example: + - --dns-ipv6-addr 2a04:4e42::561 $URL --- + +# `--dns-ipv6-addr` + 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-servers.d b/docs/cmdline-opts/dns-servers.md similarity index 77% rename from docs/cmdline-opts/dns-servers.d rename to docs/cmdline-opts/dns-servers.md index 96be0814143..3eab6668ded 100644 --- a/docs/cmdline-opts/dns-servers.d +++ b/docs/cmdline-opts/dns-servers.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: dns-servers @@ -7,10 +8,16 @@ Protocols: DNS 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 +See-also: + - dns-interface + - dns-ipv4-addr +Example: + - --dns-servers 192.168.0.1,192.168.0.2 $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 as *:* after each IP diff --git a/docs/cmdline-opts/doh-cert-status.d b/docs/cmdline-opts/doh-cert-status.md similarity index 69% rename from docs/cmdline-opts/doh-cert-status.d rename to docs/cmdline-opts/doh-cert-status.md index 37ae0f8274a..efa9da75c15 100644 --- a/docs/cmdline-opts/doh-cert-status.d +++ b/docs/cmdline-opts/doh-cert-status.md @@ -1,11 +1,17 @@ +--- 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 +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). diff --git a/docs/cmdline-opts/doh-insecure.d b/docs/cmdline-opts/doh-insecure.md similarity index 70% rename from docs/cmdline-opts/doh-insecure.d rename to docs/cmdline-opts/doh-insecure.md index dcc65fb6c9f..684428ddf7e 100644 --- a/docs/cmdline-opts/doh-insecure.d +++ b/docs/cmdline-opts/doh-insecure.md @@ -1,11 +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 -Example: --doh-insecure --doh-url https://doh.example $URL -See-also: doh-url 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.md similarity index 87% rename from docs/cmdline-opts/doh-url.d rename to docs/cmdline-opts/doh-url.md index 6d0dd1605ea..d12bf5194fa 100644 --- a/docs/cmdline-opts/doh-url.d +++ b/docs/cmdline-opts/doh-url.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: doh-url @@ -5,10 +6,15 @@ 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 +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. diff --git a/docs/cmdline-opts/dump-header.d b/docs/cmdline-opts/dump-header.md similarity index 87% rename from docs/cmdline-opts/dump-header.d rename to docs/cmdline-opts/dump-header.md index 42a79e7ddf6..42d3e85ed60 100644 --- a/docs/cmdline-opts/dump-header.d +++ b/docs/cmdline-opts/dump-header.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: dump-header @@ -5,12 +6,17 @@ 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 +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. diff --git a/docs/cmdline-opts/egd-file.d b/docs/cmdline-opts/egd-file.md similarity index 83% rename from docs/cmdline-opts/egd-file.d rename to docs/cmdline-opts/egd-file.md index 4543ecf15eb..b68b7d49670 100644 --- a/docs/cmdline-opts/egd-file.d +++ b/docs/cmdline-opts/egd-file.md @@ -1,15 +1,21 @@ +--- 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 +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. diff --git a/docs/cmdline-opts/engine.d b/docs/cmdline-opts/engine.md similarity index 82% rename from docs/cmdline-opts/engine.d rename to docs/cmdline-opts/engine.md index 1ebc779c0d8..511190023ef 100644 --- a/docs/cmdline-opts/engine.d +++ b/docs/cmdline-opts/engine.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: engine @@ -5,11 +6,17 @@ Arg: Help: Crypto engine to use Protocols: TLS Category: tls -Example: --engine flavor $URL Added: 7.9.3 -See-also: ciphers curves 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.md similarity index 86% rename from docs/cmdline-opts/etag-compare.d rename to docs/cmdline-opts/etag-compare.md index d3c48d17a65..11c1d0e875b 100644 --- a/docs/cmdline-opts/etag-compare.d +++ b/docs/cmdline-opts/etag-compare.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: etag-compare @@ -6,10 +7,16 @@ 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 +See-also: + - etag-save + - time-cond +Example: + - --etag-compare etag.txt $URL --- + +# `--etag-compare` + 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. diff --git a/docs/cmdline-opts/etag-save.d b/docs/cmdline-opts/etag-save.md similarity index 81% rename from docs/cmdline-opts/etag-save.d rename to docs/cmdline-opts/etag-save.md index 6295a9e3116..f6fb14a5154 100644 --- a/docs/cmdline-opts/etag-save.d +++ b/docs/cmdline-opts/etag-save.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: etag-save @@ -6,10 +7,15 @@ 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 +See-also: + - etag-compare +Example: + - --etag-save storetag.txt $URL --- + +# `--etag-save` + This option saves an HTTP ETag to the specified file. An ETag is a caching related header, usually returned in a response. diff --git a/docs/cmdline-opts/expect100-timeout.d b/docs/cmdline-opts/expect100-timeout.md similarity index 85% rename from docs/cmdline-opts/expect100-timeout.d rename to docs/cmdline-opts/expect100-timeout.md index f9a119bd979..9554568a777 100644 --- a/docs/cmdline-opts/expect100-timeout.d +++ b/docs/cmdline-opts/expect100-timeout.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: expect100-timeout @@ -5,11 +6,16 @@ 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 +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 diff --git a/docs/cmdline-opts/fail-early.d b/docs/cmdline-opts/fail-early.md similarity index 90% rename from docs/cmdline-opts/fail-early.d rename to docs/cmdline-opts/fail-early.md index 36b3309996b..b68160c2018 100644 --- a/docs/cmdline-opts/fail-early.d +++ b/docs/cmdline-opts/fail-early.md @@ -1,14 +1,21 @@ +--- 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 +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 diff --git a/docs/cmdline-opts/fail-with-body.d b/docs/cmdline-opts/fail-with-body.md similarity index 87% rename from docs/cmdline-opts/fail-with-body.d rename to docs/cmdline-opts/fail-with-body.md index dddb86e2296..e340cb0345b 100644 --- a/docs/cmdline-opts/fail-with-body.d +++ b/docs/cmdline-opts/fail-with-body.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: fail-with-body @@ -5,11 +6,17 @@ 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 +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 diff --git a/docs/cmdline-opts/fail.d b/docs/cmdline-opts/fail.md similarity index 89% rename from docs/cmdline-opts/fail.d rename to docs/cmdline-opts/fail.md index 8196a908dec..b8de4ebb253 100644 --- a/docs/cmdline-opts/fail.d +++ b/docs/cmdline-opts/fail.md @@ -1,16 +1,23 @@ +--- 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 +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 diff --git a/docs/cmdline-opts/false-start.d b/docs/cmdline-opts/false-start.md similarity index 86% rename from docs/cmdline-opts/false-start.d rename to docs/cmdline-opts/false-start.md index 73240492b96..d2697da5387 100644 --- a/docs/cmdline-opts/false-start.d +++ b/docs/cmdline-opts/false-start.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: false-start @@ -5,10 +6,15 @@ Help: Enable TLS False Start Protocols: TLS Added: 7.42.0 Category: tls -Example: --false-start $URL -See-also: tcp-fastopen Multi: boolean +See-also: + - tcp-fastopen +Example: + - --false-start $URL --- + +# `--false-start` + 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 diff --git a/docs/cmdline-opts/form-escape.d b/docs/cmdline-opts/form-escape.md similarity index 75% rename from docs/cmdline-opts/form-escape.d rename to docs/cmdline-opts/form-escape.md index 304bfe81497..62973f172af 100644 --- a/docs/cmdline-opts/form-escape.d +++ b/docs/cmdline-opts/form-escape.md @@ -1,13 +1,19 @@ +--- 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 +See-also: + - form +Example: + - --form-escape -F 'field\name=curl' -F 'file=@load"this' $URL --- + +# `--form-escape` + 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-string.d b/docs/cmdline-opts/form-string.md similarity index 87% rename from docs/cmdline-opts/form-string.d rename to docs/cmdline-opts/form-string.md index 6d7a500a447..d26c4714292 100644 --- a/docs/cmdline-opts/form-string.d +++ b/docs/cmdline-opts/form-string.md @@ -1,15 +1,21 @@ +--- 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 +See-also: + - form +Example: + - --form-string "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 diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.md similarity index 75% rename from docs/cmdline-opts/form.d rename to docs/cmdline-opts/form.md index ac0e4bfefb2..0ba552136fd 100644 --- a/docs/cmdline-opts/form.d +++ b/docs/cmdline-opts/form.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: form @@ -7,11 +8,18 @@ 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 +See-also: + - data + - form-string + - form-escape +Example: + - --form "name=curl" --form "file=@loadthis" $URL --- + +# `--form` + 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. @@ -37,38 +45,38 @@ 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 + 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/ + 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 + curl -F '=(;type=multipart/alternative' \ + -F '=plain text message' \ + -F '= 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 @@ -128,7 +136,7 @@ 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 + 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.md similarity index 77% rename from docs/cmdline-opts/ftp-account.d rename to docs/cmdline-opts/ftp-account.md index eb669c56280..2f336394330 100644 --- a/docs/cmdline-opts/ftp-account.d +++ b/docs/cmdline-opts/ftp-account.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-account @@ -6,9 +7,14 @@ 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 +See-also: + - user +Example: + - --ftp-account "mr.robot" ftp://example.com/ --- + +# `--ftp-account` + 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-alternative-to-user.d b/docs/cmdline-opts/ftp-alternative-to-user.md similarity index 78% rename from docs/cmdline-opts/ftp-alternative-to-user.d rename to docs/cmdline-opts/ftp-alternative-to-user.md index f030bcf5985..9bd3686001c 100644 --- a/docs/cmdline-opts/ftp-alternative-to-user.d +++ b/docs/cmdline-opts/ftp-alternative-to-user.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-alternative-to-user @@ -6,10 +7,16 @@ 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 +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 diff --git a/docs/cmdline-opts/ftp-create-dirs.d b/docs/cmdline-opts/ftp-create-dirs.md similarity index 77% rename from docs/cmdline-opts/ftp-create-dirs.d rename to docs/cmdline-opts/ftp-create-dirs.md index 7c64f0e21c9..5151e336c85 100644 --- a/docs/cmdline-opts/ftp-create-dirs.d +++ b/docs/cmdline-opts/ftp-create-dirs.md @@ -1,14 +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 -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 +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.md similarity index 80% rename from docs/cmdline-opts/ftp-method.d rename to docs/cmdline-opts/ftp-method.md index e3a08782b33..e4e3468588b 100644 --- a/docs/cmdline-opts/ftp-method.d +++ b/docs/cmdline-opts/ftp-method.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-method @@ -6,12 +7,17 @@ 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 +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: diff --git a/docs/cmdline-opts/ftp-pasv.d b/docs/cmdline-opts/ftp-pasv.md similarity index 86% rename from docs/cmdline-opts/ftp-pasv.d rename to docs/cmdline-opts/ftp-pasv.md index c43bf2beeac..265a8e4534c 100644 --- a/docs/cmdline-opts/ftp-pasv.d +++ b/docs/cmdline-opts/ftp-pasv.md @@ -1,14 +1,20 @@ +--- 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 +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. diff --git a/docs/cmdline-opts/ftp-port.d b/docs/cmdline-opts/ftp-port.md similarity index 84% rename from docs/cmdline-opts/ftp-port.d rename to docs/cmdline-opts/ftp-port.md index 3026778d968..e9ec59146fc 100644 --- a/docs/cmdline-opts/ftp-port.d +++ b/docs/cmdline-opts/ftp-port.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-port @@ -5,14 +6,20 @@ 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 +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 tells the server to connect back to the client's specified address and port, while passive mode asks the server @@ -37,7 +44,7 @@ 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 +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. diff --git a/docs/cmdline-opts/ftp-pret.d b/docs/cmdline-opts/ftp-pret.md similarity index 79% rename from docs/cmdline-opts/ftp-pret.d rename to docs/cmdline-opts/ftp-pret.md index 4bea99e6d84..accbc226dff 100644 --- a/docs/cmdline-opts/ftp-pret.d +++ b/docs/cmdline-opts/ftp-pret.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-pret @@ -5,10 +6,16 @@ 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 +See-also: + - ftp-port + - ftp-pasv +Example: + - --ftp-pret ftp://example.com/ --- + +# `--ftp-pret` + 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-skip-pasv-ip.d b/docs/cmdline-opts/ftp-skip-pasv-ip.md similarity index 84% rename from docs/cmdline-opts/ftp-skip-pasv-ip.d rename to docs/cmdline-opts/ftp-skip-pasv-ip.md index 3af9c6de4fe..ef94b34af17 100644 --- a/docs/cmdline-opts/ftp-skip-pasv-ip.d +++ b/docs/cmdline-opts/ftp-skip-pasv-ip.md @@ -1,14 +1,20 @@ +--- 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 +See-also: + - ftp-pasv +Example: + - --ftp-skip-pasv-ip ftp://example.com/ --- + +# `--ftp-skip-pasv-ip` + 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. diff --git a/docs/cmdline-opts/ftp-ssl-ccc-mode.d b/docs/cmdline-opts/ftp-ssl-ccc-mode.md similarity index 78% rename from docs/cmdline-opts/ftp-ssl-ccc-mode.d rename to docs/cmdline-opts/ftp-ssl-ccc-mode.md index ae9af9429d4..5f428dc0fa4 100644 --- a/docs/cmdline-opts/ftp-ssl-ccc-mode.d +++ b/docs/cmdline-opts/ftp-ssl-ccc-mode.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-ssl-ccc-mode @@ -5,11 +6,16 @@ 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 +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 diff --git a/docs/cmdline-opts/ftp-ssl-ccc.d b/docs/cmdline-opts/ftp-ssl-ccc.md similarity index 80% rename from docs/cmdline-opts/ftp-ssl-ccc.d rename to docs/cmdline-opts/ftp-ssl-ccc.md index 33ae83b1c95..d477606fe67 100644 --- a/docs/cmdline-opts/ftp-ssl-ccc.d +++ b/docs/cmdline-opts/ftp-ssl-ccc.md @@ -1,14 +1,21 @@ +--- 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 +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 diff --git a/docs/cmdline-opts/ftp-ssl-control.d b/docs/cmdline-opts/ftp-ssl-control.md similarity index 66% rename from docs/cmdline-opts/ftp-ssl-control.d rename to docs/cmdline-opts/ftp-ssl-control.md index b895779271c..ace1ab29fbd 100644 --- a/docs/cmdline-opts/ftp-ssl-control.d +++ b/docs/cmdline-opts/ftp-ssl-control.md @@ -1,3 +1,4 @@ +--- c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-ssl-control @@ -5,10 +6,15 @@ 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 +See-also: + - ssl +Example: + - --ftp-ssl-control ftp://example.com --- -Require SSL/TLS for the FTP login, clear for transfer. Allows secure -authentication, but non-encrypted data transfers for efficiency. Fails the + +# `--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 index 2766ca265bd..59c996d7be6 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -90,52 +90,8 @@ 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 { @@ -200,9 +156,173 @@ sub added { } } +sub render { + my ($fh, $f, $line) = @_; + my @desc; + my $tablemode = 0; + my $header = 0; + # if $top is TRUE, it means a top-level page and not a command line option + my $top = ($line == 1); + my $quote; + $start = 0; + + while(<$fh>) { + my $d = $_; + $line++; + if($d =~ /^\.(SH|BR|IP|B)/) { + print STDERR "$f:$line:1:ERROR: nroff instruction in input: \".$1\"\n"; + return 4; + } + if(/^ * SETUP[QUIC] --> HAPPY-EYEBALLS --> HTTP/3[2a04:4e42:c00::347]: * transfer ``` -And 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: +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 diff --git a/docs/MANUAL.md b/docs/MANUAL.md index d25d6ce7e1f..e7b4bb7af79 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -888,7 +888,7 @@ 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 +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`. You might want the `-N`/`--no-buffer` option to switch off the buffered output diff --git a/docs/NEW-PROTOCOL.md b/docs/NEW-PROTOCOL.md index a8b227d3c0b..223815b6d71 100644 --- a/docs/NEW-PROTOCOL.md +++ b/docs/NEW-PROTOCOL.md @@ -7,7 +7,7 @@ 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 diff --git a/docs/cmdline-opts/_GLOBBING.md b/docs/cmdline-opts/_GLOBBING.md index 66fc5dbb7e7..282356c3efb 100644 --- a/docs/cmdline-opts/_GLOBBING.md +++ b/docs/cmdline-opts/_GLOBBING.md @@ -8,15 +8,15 @@ 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: +Do sequences of alphanumeric series by using [] as in: "ftp://ftp.example.com/file[1-100].txt" -And with leading zeroes: +With leading zeroes: "ftp://ftp.example.com/file[001-100].txt" -Or with letters through the alphabet: +With letters through the alphabet: "ftp://ftp.example.com/file[a-z].txt" From 9a90c9dd64d2f03601833a70786d485851bd1b53 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 26 Jan 2024 10:10:11 +0100 Subject: [PATCH 237/509] vtls: receive max buffer - do not only receive one TLS record, but try to fill the passed buffer - consider <4K remaning space is "filled". Closes #12801 --- lib/vtls/vtls.c | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/lib/vtls/vtls.c b/lib/vtls/vtls.c index 7f6ce09d7cf..e928ba5d079 100644 --- a/lib/vtls/vtls.c +++ b/lib/vtls/vtls.c @@ -1715,18 +1715,34 @@ static ssize_t ssl_cf_recv(struct Curl_cfilter *cf, { struct cf_call_data save; ssize_t nread; + size_t ntotal = 0; CF_DATA_SAVE(save, cf, data); *err = CURLE_OK; - nread = Curl_ssl->recv_plain(cf, data, buf, len, err); - if(nread > 0) { - DEBUGASSERT((size_t)nread <= len); - } - else if(nread == 0) { - /* eof */ + /* Do receive until we fill the buffer somehwhat or EGAIN, error or EOF */ + while(!ntotal || (len - ntotal) > (4*1024)) { *err = CURLE_OK; + nread = Curl_ssl->recv_plain(cf, data, buf + ntotal, len - ntotal, err); + if(nread < 0) { + if(*err == CURLE_AGAIN && ntotal > 0) { + /* we EAGAINed after having reed data, return the success amount */ + *err = CURLE_OK; + break; + } + /* we have a an error to report */ + goto out; + } + else if(nread == 0) { + /* eof */ + break; + } + ntotal += (size_t)nread; + DEBUGASSERT((size_t)ntotal <= len); } - CURL_TRC_CF(data, cf, "cf_recv(len=%zu) -> %zd, %d", len, nread, *err); + nread = (ssize_t)ntotal; +out: + CURL_TRC_CF(data, cf, "cf_recv(len=%zu) -> %zd, %d", len, + nread, *err); CF_DATA_RESTORE(cf, save); return nread; } From a6c9a33bf80fd639af6c092ab9a17c1ff1981495 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 25 Jan 2024 15:06:44 +0100 Subject: [PATCH 238/509] file+ftp: use stack buffers instead of data->state.buffer Closes #12789 --- lib/file.c | 34 +++++++++++++++++++--------------- lib/ftp.c | 7 ++++--- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/lib/file.c b/lib/file.c index 73cd73a6679..b7ce3a8eda1 100644 --- a/lib/file.c +++ b/lib/file.c @@ -290,16 +290,15 @@ static CURLcode file_upload(struct Curl_easy *data) int fd; int mode; CURLcode result = CURLE_OK; - char *buf = data->state.buffer; + char buffer[8*1024], *uphere_save; curl_off_t bytecount = 0; struct_stat file_stat; - const char *buf2; + const char *sendbuf; /* * Since FILE: doesn't do the full init, we need to provide some extra * assignments here. */ - data->req.upload_fromhere = buf; if(!dir) return CURLE_FILE_COULDNT_READ_FILE; /* fix: better error code */ @@ -338,11 +337,15 @@ static CURLcode file_upload(struct Curl_easy *data) data->state.resume_from = (curl_off_t)file_stat.st_size; } + /* Yikes! Curl_fillreadbuffer uses data->req.upload_fromhere to READ + * client data to! Please, someone fix... */ + uphere_save = data->req.upload_fromhere; while(!result) { size_t nread; ssize_t nwrite; size_t readcount; - result = Curl_fillreadbuffer(data, data->set.buffer_size, &readcount); + data->req.upload_fromhere = buffer; + result = Curl_fillreadbuffer(data, sizeof(buffer), &readcount); if(result) break; @@ -356,19 +359,19 @@ static CURLcode file_upload(struct Curl_easy *data) if((curl_off_t)nread <= data->state.resume_from) { data->state.resume_from -= nread; nread = 0; - buf2 = buf; + sendbuf = buffer; } else { - buf2 = buf + data->state.resume_from; + sendbuf = buffer + data->state.resume_from; nread -= (size_t)data->state.resume_from; data->state.resume_from = 0; } } else - buf2 = buf; + sendbuf = buffer; /* write the data to the target */ - nwrite = write(fd, buf2, nread); + nwrite = write(fd, sendbuf, nread); if((size_t)nwrite != nread) { result = CURLE_SEND_ERROR; break; @@ -387,6 +390,7 @@ static CURLcode file_upload(struct Curl_easy *data) result = CURLE_ABORTED_BY_CALLBACK; close(fd); + data->req.upload_fromhere = uphere_save; return result; } @@ -413,7 +417,6 @@ static CURLcode file_do(struct Curl_easy *data, bool *done) curl_off_t expected_size = -1; bool size_known; bool fstated = FALSE; - char *buf = data->state.buffer; int fd; struct FILEPROTO *file; @@ -541,21 +544,22 @@ static CURLcode file_do(struct Curl_easy *data, bool *done) Curl_pgrsTime(data, TIMER_STARTTRANSFER); while(!result) { + char tmpbuf[8*1024]; ssize_t nread; /* Don't fill a whole buffer if we want less than all data */ size_t bytestoread; if(size_known) { - bytestoread = (expected_size < data->set.buffer_size) ? - curlx_sotouz(expected_size) : (size_t)data->set.buffer_size; + bytestoread = (expected_size < (curl_off_t)(sizeof(tmpbuf)-1)) ? + curlx_sotouz(expected_size) : (sizeof(tmpbuf)-1); } else - bytestoread = data->set.buffer_size-1; + bytestoread = sizeof(tmpbuf)-1; - nread = read(fd, buf, bytestoread); + nread = read(fd, tmpbuf, bytestoread); if(nread > 0) - buf[nread] = 0; + tmpbuf[nread] = 0; if(nread <= 0 || (size_known && (expected_size == 0))) break; @@ -563,7 +567,7 @@ static CURLcode file_do(struct Curl_easy *data, bool *done) if(size_known) expected_size -= nread; - result = Curl_client_write(data, CLIENTWRITE_BODY, buf, nread); + result = Curl_client_write(data, CLIENTWRITE_BODY, tmpbuf, nread); if(result) return result; diff --git a/lib/ftp.c b/lib/ftp.c index b0177df71d4..f62108234f6 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -1587,13 +1587,14 @@ static CURLcode ftp_state_ul_setup(struct Curl_easy *data, } /* seekerr == CURL_SEEKFUNC_CANTSEEK (can't seek to offset) */ do { + char scratch[4*1024]; size_t readthisamountnow = - (data->state.resume_from - passed > data->set.buffer_size) ? - (size_t)data->set.buffer_size : + (data->state.resume_from - passed > (curl_off_t)sizeof(scratch)) ? + sizeof(scratch) : curlx_sotouz(data->state.resume_from - passed); size_t actuallyread = - data->state.fread_func(data->state.buffer, 1, readthisamountnow, + data->state.fread_func(scratch, 1, readthisamountnow, data->state.in); passed += actuallyread; From a3a940702a7fca4719ec33730314c7dda0208486 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 26 Jan 2024 08:54:08 +0100 Subject: [PATCH 239/509] socks: reduce the buffer size to 600 (from 8K) This is malloc'ed memory and it does not more. Test 742 helps us verify this. Closes #12789 --- lib/socks.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/socks.c b/lib/socks.c index e9270735bf8..ecd2f7eab53 100644 --- a/lib/socks.c +++ b/lib/socks.c @@ -71,7 +71,7 @@ enum connect_t { CONNECT_DONE /* 17 connected fine to the remote or the SOCKS proxy */ }; -#define CURL_SOCKS_BUF_SIZE (8*1024) +#define CURL_SOCKS_BUF_SIZE 600 /* make sure we configure it not too low */ #if CURL_SOCKS_BUF_SIZE < 600 From 641257ea08fc613766fdf360da83a94f321aa337 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 26 Jan 2024 11:00:21 +0100 Subject: [PATCH 240/509] x509asn1: remove code for WANT_VERIFYHOST No code ever sets this anymore since we dropped gskit Follow-up to 78d6232f1f326b9ab4d Closes #12804 --- lib/vtls/x509asn1.c | 180 -------------------------------------------- 1 file changed, 180 deletions(-) diff --git a/lib/vtls/x509asn1.c b/lib/vtls/x509asn1.c index 4bfcba90545..492c3ed5994 100644 --- a/lib/vtls/x509asn1.c +++ b/lib/vtls/x509asn1.c @@ -1257,183 +1257,3 @@ CURLcode Curl_extract_certinfo(struct Curl_easy *data, #endif /* WANT_EXTRACT_CERTINFO */ #endif /* USE_GNUTLS or USE_WOLFSSL or USE_SCHANNEL or USE_SECTRANSP */ - -#ifdef WANT_VERIFYHOST - -static const char *checkOID(const char *beg, const char *end, - const char *oid) -{ - struct Curl_asn1Element e; - const char *ccp; - const char *p; - bool matched; - - /* Check if first ASN.1 element at `beg' is the given OID. - Return a pointer in the source after the OID if found, else NULL. */ - - ccp = getASN1Element(&e, beg, end); - if(!ccp || e.tag != CURL_ASN1_OBJECT_IDENTIFIER) - return NULL; - - p = OID2str(e.beg, e.end, FALSE); - if(!p) - return NULL; - - matched = !strcmp(p, oid); - free((char *) p); - return matched? ccp: NULL; -} - -CURLcode Curl_verifyhost(struct Curl_cfilter *cf, - struct Curl_easy *data, - const char *beg, const char *end) -{ - struct ssl_connect_data *connssl = cf->ctx; - struct ssl_primary_config *conn_config = Curl_ssl_cf_get_primary_config(cf); - struct Curl_X509certificate cert; - struct Curl_asn1Element dn; - struct Curl_asn1Element elem; - struct Curl_asn1Element ext; - struct Curl_asn1Element name; - const char *p; - const char *q; - char *dnsname; - int matched = -1; - size_t addrlen = (size_t) -1; - ssize_t len; - size_t hostlen; - -#ifdef ENABLE_IPV6 - struct in6_addr addr; -#else - struct in_addr addr; -#endif - - /* Verify that connection server matches info in X509 certificate at - `beg'..`end'. */ - - if(!conn_config->verifyhost) - return CURLE_OK; - - if(Curl_parseX509(&cert, beg, end)) - return CURLE_PEER_FAILED_VERIFICATION; - - hostlen = strlen(connssl->peer.hostname); - - /* Get the server IP address. */ -#ifdef ENABLE_IPV6 - if(cf->conn->bits.ipv6_ip && - Curl_inet_pton(AF_INET6, connssl->peer.hostname, &addr)) - addrlen = sizeof(struct in6_addr); - else -#endif - if(Curl_inet_pton(AF_INET, connssl->peer.hostname, &addr)) - addrlen = sizeof(struct in_addr); - - /* Process extensions. */ - for(p = cert.extensions.beg; p < cert.extensions.end && matched != 1;) { - p = getASN1Element(&ext, p, cert.extensions.end); - if(!p) - return CURLE_PEER_FAILED_VERIFICATION; - - /* Check if extension is a subjectAlternativeName. */ - ext.beg = checkOID(ext.beg, ext.end, sanOID); - if(ext.beg) { - ext.beg = getASN1Element(&elem, ext.beg, ext.end); - if(!ext.beg) - return CURLE_PEER_FAILED_VERIFICATION; - /* Skip critical if present. */ - if(elem.tag == CURL_ASN1_BOOLEAN) { - ext.beg = getASN1Element(&elem, ext.beg, ext.end); - if(!ext.beg) - return CURLE_PEER_FAILED_VERIFICATION; - } - /* Parse the octet string contents: is a single sequence. */ - if(!getASN1Element(&elem, elem.beg, elem.end)) - return CURLE_PEER_FAILED_VERIFICATION; - /* Check all GeneralNames. */ - for(q = elem.beg; matched != 1 && q < elem.end;) { - q = getASN1Element(&name, q, elem.end); - if(!q) - break; - switch(name.tag) { - case 2: /* DNS name. */ - len = utf8asn1str(&dnsname, CURL_ASN1_IA5_STRING, - name.beg, name.end); - if(len > 0 && (size_t)len == strlen(dnsname)) - matched = Curl_cert_hostcheck(dnsname, (size_t)len, - connssl->peer.hostname, hostlen); - else - matched = 0; - free(dnsname); - break; - - case 7: /* IP address. */ - matched = (size_t)(name.end - name.beg) == addrlen && - !memcmp(&addr, name.beg, addrlen); - break; - } - } - } - } - - switch(matched) { - case 1: - /* an alternative name matched the server hostname */ - infof(data, " subjectAltName: %s matched", connssl->dispname); - return CURLE_OK; - case 0: - /* an alternative name field existed, but didn't match and then - we MUST fail */ - infof(data, " subjectAltName does not match %s", connssl->dispname); - return CURLE_PEER_FAILED_VERIFICATION; - } - - /* Process subject. */ - name.header = NULL; - name.beg = name.end = ""; - q = cert.subject.beg; - /* we have to look to the last occurrence of a commonName in the - distinguished one to get the most significant one. */ - while(q < cert.subject.end) { - q = getASN1Element(&dn, q, cert.subject.end); - if(!q) - break; - for(p = dn.beg; p < dn.end;) { - p = getASN1Element(&elem, p, dn.end); - if(!p) - return CURLE_PEER_FAILED_VERIFICATION; - /* We have a DN's AttributeTypeAndValue: check it in case it's a CN. */ - elem.beg = checkOID(elem.beg, elem.end, cnOID); - if(elem.beg) - name = elem; /* Latch CN. */ - } - } - - /* Check the CN if found. */ - if(!getASN1Element(&elem, name.beg, name.end)) - failf(data, "SSL: unable to obtain common name from peer certificate"); - else { - len = utf8asn1str(&dnsname, elem.tag, elem.beg, elem.end); - if(len < 0) { - free(dnsname); - return CURLE_OUT_OF_MEMORY; - } - if(strlen(dnsname) != (size_t) len) /* Nul byte in string ? */ - failf(data, "SSL: illegal cert name field"); - else if(Curl_cert_hostcheck((const char *) dnsname, - len, connssl->peer.hostname, hostlen)) { - infof(data, " common name: %s (matched)", dnsname); - free(dnsname); - return CURLE_OK; - } - else - failf(data, "SSL: certificate subject name '%s' does not match " - "target host name '%s'", dnsname, connssl->dispname); - free(dnsname); - } - - return CURLE_PEER_FAILED_VERIFICATION; -} - -#endif /* WANT_VERIFYHOST */ From aee4ebe59161d0a5281743f96e7738ad97fe1cd4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 26 Jan 2024 10:46:17 +0100 Subject: [PATCH 241/509] krb5: add prototype to silence clang warnings on mvsnprintf() "error: format string is not a string literal" Follow-up to 09230127589eccc7 which made the warning appear Assisted-by: Viktor Szakats Closes #12803 --- lib/krb5.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/lib/krb5.c b/lib/krb5.c index b334ae2f401..4db19fb27fa 100644 --- a/lib/krb5.c +++ b/lib/krb5.c @@ -434,6 +434,9 @@ static char level_to_char(int level) /* Send an FTP command defined by |message| and the optional arguments. The function returns the ftp_code. If an error occurs, -1 is returned. */ +static int ftp_send_command(struct Curl_easy *data, const char *message, ...) + CURL_PRINTF(2, 3); + static int ftp_send_command(struct Curl_easy *data, const char *message, ...) { int ftp_code; From 81d2b871abd413eceae7d6758a70d794094f3880 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Sat, 27 Jan 2024 02:07:05 -0500 Subject: [PATCH 242/509] THANKS: add Alexander Bartel and Brennan Kinney They reported and investigated #10259 which was fixed by 7b2d98df. Ref: https://github.com/curl/curl/issues/10259 --- docs/THANKS | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/THANKS b/docs/THANKS index 8c3fd27ec3d..8e7cbe4b492 100644 --- a/docs/THANKS +++ b/docs/THANKS @@ -92,6 +92,7 @@ Alex Samorukov Alex Suykov Alex Vinnik Alex Xu +Alexander Bartel Alexander Beedie Alexander Chuykov Alexander Dyagilev @@ -373,6 +374,7 @@ Brandon Dong Brandon Wang BratSinot on github Brendan Jurd +Brennan Kinney Brent Beardsley Brian Akins Brian Bergeron From 98b41dd4bbf6c85deb7d8cfbf51f6a5ede026db4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 26 Jan 2024 11:30:25 +0100 Subject: [PATCH 243/509] x509asn1: reduce malloc in Curl_extract_certinfo Using dynbuf Closes #12808 --- lib/vtls/x509asn1.c | 75 ++++++++++++++++++++------------------------- 1 file changed, 34 insertions(+), 41 deletions(-) diff --git a/lib/vtls/x509asn1.c b/lib/vtls/x509asn1.c index 492c3ed5994..e49be0ab77f 100644 --- a/lib/vtls/x509asn1.c +++ b/lib/vtls/x509asn1.c @@ -877,23 +877,6 @@ int Curl_parseX509(struct Curl_X509certificate *cert, #ifdef WANT_EXTRACT_CERTINFO -/* - * Copy at most 64-characters, terminate with a newline and returns the - * effective number of stored characters. - */ -static size_t copySubstring(char *to, const char *from) -{ - size_t i; - for(i = 0; i < 64; i++) { - to[i] = *from; - if(!*from++) - break; - } - - to[i++] = '\n'; - return i; -} - static const char *dumpAlgo(struct Curl_asn1Element *param, const char *beg, const char *end) { @@ -1070,6 +1053,8 @@ static const char *DNtostr(struct Curl_asn1Element *dn) return buf; } +#define MAX_X509_CERT 100000 + CURLcode Curl_extract_certinfo(struct Curl_easy *data, int certnum, const char *beg, @@ -1078,13 +1063,11 @@ CURLcode Curl_extract_certinfo(struct Curl_easy *data, struct Curl_X509certificate cert; struct Curl_asn1Element param; const char *ccp; - char *cp1; - size_t cl1; - char *cp2; + char *certptr; + size_t clen; + struct dynbuf out; CURLcode result = CURLE_OK; unsigned int version; - size_t i; - size_t j; if(!data->set.ssl.certinfo) if(certnum) @@ -1222,10 +1205,11 @@ CURLcode Curl_extract_certinfo(struct Curl_easy *data, /* Generate PEM certificate. */ result = Curl_base64_encode(cert.certificate.beg, cert.certificate.end - cert.certificate.beg, - &cp1, &cl1); + &certptr, &clen); if(result) return result; - /* Compute the number of characters in final certificate string. Format is: + + /* Generate the final output certificate string. Format is: -----BEGIN CERTIFICATE-----\n \n . @@ -1233,24 +1217,33 @@ CURLcode Curl_extract_certinfo(struct Curl_easy *data, . -----END CERTIFICATE-----\n */ - i = 28 + cl1 + (cl1 + 64 - 1) / 64 + 26; - cp2 = malloc(i + 1); - if(!cp2) { - free(cp1); - return CURLE_OUT_OF_MEMORY; - } + + Curl_dyn_init(&out, MAX_X509_CERT); + /* Build the certificate string. */ - i = copySubstring(cp2, "-----BEGIN CERTIFICATE-----"); - for(j = 0; j < cl1; j += 64) - i += copySubstring(cp2 + i, cp1 + j); - i += copySubstring(cp2 + i, "-----END CERTIFICATE-----"); - cp2[i] = '\0'; - free(cp1); - if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, "Cert", cp2); - if(!certnum) - infof(data, "%s", cp2); - free(cp2); + result = Curl_dyn_add(&out, "-----BEGIN CERTIFICATE-----\n"); + if(!result) { + size_t j = 0; + + while(!result && (j < clen)) { + size_t chunksize = (clen - j) > 64 ? 64 : (clen - j); + result = Curl_dyn_addn(&out, &certptr[j], chunksize); + if(!result) + result = Curl_dyn_addn(&out, "\n", 1); + j += chunksize; + } + if(!result) + result = Curl_dyn_add(&out, "-----END CERTIFICATE-----\n"); + } + free(certptr); + if(!result) { + if(data->set.ssl.certinfo) + result = ssl_push_certinfo(data, certnum, "Cert", + Curl_dyn_ptr(&out)); + if(!certnum) + infof(data, "%s", Curl_dyn_ptr(&out)); + } + Curl_dyn_free(&out); return result; } From cd48e8f8a9fd231231bffe23f6f6e63cc1f5691f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 26 Jan 2024 11:49:21 +0100 Subject: [PATCH 244/509] x509asn1: make utf8asn1str() use dynbuf instead of malloc + memcpy Closes #12808 --- lib/vtls/x509asn1.c | 62 ++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 34 deletions(-) diff --git a/lib/vtls/x509asn1.c b/lib/vtls/x509asn1.c index e49be0ab77f..8407940ce34 100644 --- a/lib/vtls/x509asn1.c +++ b/lib/vtls/x509asn1.c @@ -97,6 +97,11 @@ #define CURL_ASN1_CHARACTER_STRING 29 #define CURL_ASN1_BMP_STRING 30 +/* Max sixes */ + +#define MAX_X509_STR 10000 +#define MAX_X509_CERT 100000 + #ifdef WANT_EXTRACT_CERTINFO /* ASN.1 OID table entry. */ struct Curl_OID { @@ -322,21 +327,20 @@ static const char *int2str(const char *beg, const char *end) } /* - * Perform a lazy conversion from an ASN.1 typed string to UTF8. Allocate the - * destination buffer dynamically. The allocation size will normally be too - * large: this is to avoid buffer overflows. - * Terminate the string with a nul byte and return the converted - * string length. + * Convert from an ASN.1 typed string to UTF8. + * + * The result is stored in a dynbuf that is inited by the user of this + * function. + * + * Return negative on error. */ static ssize_t -utf8asn1str(char **to, int type, const char *from, const char *end) +utf8asn1str(struct dynbuf *to, int type, const char *from, const char *end) { size_t inlength = end - from; int size = 1; - size_t outlength; - char *buf; + CURLcode result = CURLE_OK; - *to = NULL; switch(type) { case CURL_ASN1_BMP_STRING: size = 2; @@ -357,24 +361,18 @@ utf8asn1str(char **to, int type, const char *from, const char *end) if(inlength % size) return -1; /* Length inconsistent with character size. */ - if(inlength / size > (SIZE_T_MAX - 1) / 4) - return -1; /* Too big. */ - buf = malloc(4 * (inlength / size) + 1); - if(!buf) - return -1; /* Not enough memory. */ if(type == CURL_ASN1_UTF8_STRING) { /* Just copy. */ - outlength = inlength; - if(outlength) - memcpy(buf, from, outlength); + if(inlength) + result = Curl_dyn_addn(to, from, inlength); } else { - for(outlength = 0; from < end;) { - int charsize; - unsigned int wc; + while(!result && (from < end)) { + char buf[4]; /* decode buffer */ + int charsize = 1; + unsigned int wc = 0; - wc = 0; switch(size) { case 4: wc = (wc << 8) | *(const unsigned char *) from++; @@ -386,7 +384,6 @@ utf8asn1str(char **to, int type, const char *from, const char *end) default: /* case 1: */ wc = (wc << 8) | *(const unsigned char *) from++; } - charsize = 1; if(wc >= 0x00000080) { if(wc >= 0x00000800) { if(wc >= 0x00010000) { @@ -394,25 +391,23 @@ utf8asn1str(char **to, int type, const char *from, const char *end) free(buf); return -1; /* Invalid char. size for target encoding. */ } - buf[outlength + 3] = (char) (0x80 | (wc & 0x3F)); + buf[3] = (char) (0x80 | (wc & 0x3F)); wc = (wc >> 6) | 0x00010000; charsize++; } - buf[outlength + 2] = (char) (0x80 | (wc & 0x3F)); + buf[2] = (char) (0x80 | (wc & 0x3F)); wc = (wc >> 6) | 0x00000800; charsize++; } - buf[outlength + 1] = (char) (0x80 | (wc & 0x3F)); + buf[1] = (char) (0x80 | (wc & 0x3F)); wc = (wc >> 6) | 0x000000C0; charsize++; } - buf[outlength] = (char) wc; - outlength += charsize; + buf[0] = (char) wc; + result = Curl_dyn_addn(to, buf, charsize); } } - buf[outlength] = '\0'; - *to = buf; - return outlength; + return result ? (ssize_t) -1 : (ssize_t)Curl_dyn_len(to); } /* @@ -421,10 +416,11 @@ utf8asn1str(char **to, int type, const char *from, const char *end) */ static const char *string2str(int type, const char *beg, const char *end) { - char *buf; + struct dynbuf buf; + Curl_dyn_init(&buf, MAX_X509_STR); if(utf8asn1str(&buf, type, beg, end) < 0) return NULL; - return buf; + return Curl_dyn_ptr(&buf); } /* @@ -1053,8 +1049,6 @@ static const char *DNtostr(struct Curl_asn1Element *dn) return buf; } -#define MAX_X509_CERT 100000 - CURLcode Curl_extract_certinfo(struct Curl_easy *data, int certnum, const char *beg, From 623c3a8fa0bdb2751f14b3741760d81910b7ec64 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 26 Jan 2024 15:02:19 +0100 Subject: [PATCH 245/509] x509asn1: switch from malloc to dynbuf Closes #12808 --- lib/vtls/x509asn1.c | 599 +++++++++++++++++++++----------------------- 1 file changed, 291 insertions(+), 308 deletions(-) diff --git a/lib/vtls/x509asn1.c b/lib/vtls/x509asn1.c index 8407940ce34..da079361d2c 100644 --- a/lib/vtls/x509asn1.c +++ b/lib/vtls/x509asn1.c @@ -260,61 +260,61 @@ static const struct Curl_OID *searchOID(const char *oid) } /* - * Convert an ASN.1 Boolean value into its string representation. Return the - * dynamically allocated string, or NULL if source is not an ASN.1 Boolean - * value. + * Convert an ASN.1 Boolean value into its string representation. + * + * Return error code. */ -static const char *bool2str(const char *beg, const char *end) +static CURLcode bool2str(struct dynbuf *store, + const char *beg, const char *end) { if(end - beg != 1) - return NULL; - return strdup(*beg? "TRUE": "FALSE"); + return CURLE_BAD_FUNCTION_ARGUMENT; + return Curl_dyn_add(store, *beg? "TRUE": "FALSE"); } /* * Convert an ASN.1 octet string to a printable string. - * Return the dynamically allocated string, or NULL if an error occurs. + * + * Return error code. */ -static const char *octet2str(const char *beg, const char *end) +static CURLcode octet2str(struct dynbuf *store, + const char *beg, const char *end) { - struct dynbuf buf; - CURLcode result; - - Curl_dyn_init(&buf, 3 * CURL_ASN1_MAX + 1); - result = Curl_dyn_addn(&buf, "", 0); + CURLcode result = CURLE_OK; while(!result && beg < end) - result = Curl_dyn_addf(&buf, "%02x:", (unsigned char) *beg++); + result = Curl_dyn_addf(store, "%02x:", (unsigned char) *beg++); - return Curl_dyn_ptr(&buf); + return result; } -static const char *bit2str(const char *beg, const char *end) +static CURLcode bit2str(struct dynbuf *store, + const char *beg, const char *end) { - /* Convert an ASN.1 bit string to a printable string. - Return the dynamically allocated string, or NULL if an error occurs. */ + /* Convert an ASN.1 bit string to a printable string. */ if(++beg > end) - return NULL; - return octet2str(beg, end); + return CURLE_BAD_FUNCTION_ARGUMENT; + return octet2str(store, beg, end); } /* * Convert an ASN.1 integer value into its string representation. - * Return the dynamically allocated string, or NULL if source is not an - * ASN.1 integer value. + * + * Returns error. */ -static const char *int2str(const char *beg, const char *end) +static CURLcode int2str(struct dynbuf *store, + const char *beg, const char *end) { unsigned int val = 0; size_t n = end - beg; if(!n) - return NULL; + return CURLE_BAD_FUNCTION_ARGUMENT; if(n > 4) - return octet2str(beg, end); + return octet2str(store, beg, end); /* Represent integers <= 32-bit as a single value. */ if(*beg & 0x80) @@ -323,7 +323,7 @@ static const char *int2str(const char *beg, const char *end) do val = (val << 8) | *(const unsigned char *) beg++; while(beg < end); - return curl_maprintf("%s%x", val >= 10? "0x": "", val); + return Curl_dyn_addf(store, "%s%x", val >= 10? "0x": "", val); } /* @@ -332,9 +332,9 @@ static const char *int2str(const char *beg, const char *end) * The result is stored in a dynbuf that is inited by the user of this * function. * - * Return negative on error. + * Returns error. */ -static ssize_t +static CURLcode utf8asn1str(struct dynbuf *to, int type, const char *from, const char *end) { size_t inlength = end - from; @@ -356,11 +356,12 @@ utf8asn1str(struct dynbuf *to, int type, const char *from, const char *end) case CURL_ASN1_UTF8_STRING: break; default: - return -1; /* Conversion not supported. */ + return CURLE_BAD_FUNCTION_ARGUMENT; /* Conversion not supported. */ } if(inlength % size) - return -1; /* Length inconsistent with character size. */ + /* Length inconsistent with character size. */ + return CURLE_BAD_FUNCTION_ARGUMENT; if(type == CURL_ASN1_UTF8_STRING) { /* Just copy. */ @@ -389,7 +390,8 @@ utf8asn1str(struct dynbuf *to, int type, const char *from, const char *end) if(wc >= 0x00010000) { if(wc >= 0x00200000) { free(buf); - return -1; /* Invalid char. size for target encoding. */ + /* Invalid char. size for target encoding. */ + return CURLE_WEIRD_SERVER_REPLY; } buf[3] = (char) (0x80 | (wc & 0x3F)); wc = (wc >> 6) | 0x00010000; @@ -407,74 +409,32 @@ utf8asn1str(struct dynbuf *to, int type, const char *from, const char *end) result = Curl_dyn_addn(to, buf, charsize); } } - return result ? (ssize_t) -1 : (ssize_t)Curl_dyn_len(to); -} - -/* - * Convert an ASN.1 String into its UTF-8 string representation. - * Return the dynamically allocated string, or NULL if an error occurs. - */ -static const char *string2str(int type, const char *beg, const char *end) -{ - struct dynbuf buf; - Curl_dyn_init(&buf, MAX_X509_STR); - if(utf8asn1str(&buf, type, beg, end) < 0) - return NULL; - return Curl_dyn_ptr(&buf); -} - -/* - * Decimal ASCII encode unsigned integer `x' into the buflen sized buffer at - * buf. Return the total number of encoded digits, even if larger than - * `buflen'. - */ -static size_t encodeUint(char *buf, size_t buflen, unsigned int x) -{ - size_t i = 0; - unsigned int y = x / 10; - - if(y) { - i = encodeUint(buf, buflen, y); - x -= y * 10; - } - if(i < buflen) - buf[i] = (char) ('0' + x); - i++; - if(i < buflen) - buf[i] = '\0'; /* Store a terminator if possible. */ - return i; + return result; } /* * Convert an ASN.1 OID into its dotted string representation. - * Store the result in th `n'-byte buffer at `buf'. - * Return the converted string length, or 0 on errors. + * + * Return error code. */ -static size_t encodeOID(char *buf, size_t buflen, - const char *beg, const char *end) +static CURLcode encodeOID(struct dynbuf *store, + const char *beg, const char *end) { - size_t i; unsigned int x; unsigned int y; + CURLcode result = CURLE_OK; /* Process the first two numbers. */ y = *(const unsigned char *) beg++; x = y / 40; y -= x * 40; - i = encodeUint(buf, buflen, x); - if(i < buflen) - buf[i] = '.'; - i++; - if(i >= buflen) - i += encodeUint(NULL, 0, y); - else - i += encodeUint(buf + i, buflen - i, y); + + result = Curl_dyn_addf(store, "%u.%u", x, y); + if(result) + return result; /* Process the trailing numbers. */ while(beg < end) { - if(i < buflen) - buf[i] = '.'; - i++; x = 0; do { if(x & 0xFF000000) @@ -482,46 +442,42 @@ static size_t encodeOID(char *buf, size_t buflen, y = *(const unsigned char *) beg++; x = (x << 7) | (y & 0x7F); } while(y & 0x80); - if(i >= buflen) - i += encodeUint(NULL, 0, x); - else - i += encodeUint(buf + i, buflen - i, x); + result = Curl_dyn_addf(store, ".%u", x); } - if(i < buflen) - buf[i] = '\0'; - return i; + return result; } /* * Convert an ASN.1 OID into its dotted or symbolic string representation. - * Return the dynamically allocated string, or NULL if an error occurs. + * + * Return error code. */ -static const char *OID2str(const char *beg, const char *end, bool symbolic) +static CURLcode OID2str(struct dynbuf *store, + const char *beg, const char *end, bool symbolic) { - char *buf = NULL; + CURLcode result = CURLE_OK; if(beg < end) { - size_t buflen = encodeOID(NULL, 0, beg, end); - if(buflen) { - buf = malloc(buflen + 1); /* one extra for the zero byte */ - if(buf) { - encodeOID(buf, buflen, beg, end); - buf[buflen] = '\0'; - - if(symbolic) { - const struct Curl_OID *op = searchOID(buf); - if(op) { - free(buf); - buf = strdup(op->textoid); - } - } + if(symbolic) { + struct dynbuf buf; + Curl_dyn_init(&buf, MAX_X509_STR); + result = encodeOID(&buf, beg, end); + + if(!result) { + const struct Curl_OID *op = searchOID(Curl_dyn_ptr(&buf)); + if(op) + result = Curl_dyn_add(store, op->textoid); + Curl_dyn_free(&buf); } } + else + result = encodeOID(store, beg, end); } - return buf; + return result; } -static const char *GTime2str(const char *beg, const char *end) +static CURLcode GTime2str(struct dynbuf *store, + const char *beg, const char *end) { const char *tzp; const char *fracp; @@ -549,7 +505,7 @@ static const char *GTime2str(const char *beg, const char *end) sec2 = fracp[-1]; break; default: - return NULL; + return CURLE_BAD_FUNCTION_ARGUMENT; } /* Scan for timezone, measure fractional seconds. */ @@ -578,7 +534,8 @@ static const char *GTime2str(const char *beg, const char *end) } tzl = end - tzp; - return curl_maprintf("%.4s-%.2s-%.2s %.2s:%.2s:%c%c%s%.*s%s%.*s", + return Curl_dyn_addf(store, + "%.4s-%.2s-%.2s %.2s:%.2s:%c%c%s%.*s%s%.*s", beg, beg + 4, beg + 6, beg + 8, beg + 10, sec1, sec2, fracl? ".": "", (int)fracl, fracp, @@ -586,10 +543,12 @@ static const char *GTime2str(const char *beg, const char *end) } /* - * Convert an ASN.1 UTC time to a printable string. - * Return the dynamically allocated string, or NULL if an error occurs. + * Convert an ASN.1 UTC time to a printable string. + * + * Return error code. */ -static const char *UTime2str(const char *beg, const char *end) +static CURLcode UTime2str(struct dynbuf *store, + const char *beg, const char *end) { const char *tzp; size_t tzl; @@ -606,12 +565,12 @@ static const char *UTime2str(const char *beg, const char *end) case 2: break; default: - return NULL; + return CURLE_BAD_FUNCTION_ARGUMENT; } /* Process timezone. */ if(tzp >= end) - return NULL; + return CURLE_BAD_FUNCTION_ARGUMENT; if(*tzp == 'Z') { tzp = "GMT"; end = tzp + 3; @@ -620,7 +579,7 @@ static const char *UTime2str(const char *beg, const char *end) tzp++; tzl = end - tzp; - return curl_maprintf("%u%.2s-%.2s-%.2s %.2s:%.2s:%.2s %.*s", + return Curl_dyn_addf(store, "%u%.2s-%.2s-%.2s %.2s:%.2s:%.2s %.*s", 20 - (*beg >= '5'), beg, beg + 2, beg + 4, beg + 6, beg + 8, sec, (int)tzl, tzp); @@ -628,34 +587,45 @@ static const char *UTime2str(const char *beg, const char *end) /* * Convert an ASN.1 element to a printable string. - * Return the dynamically allocated string, or NULL if an error occurs. + * + * Return error */ -static const char *ASN1tostr(struct Curl_asn1Element *elem, int type) +static CURLcode ASN1tostr(struct dynbuf *store, + struct Curl_asn1Element *elem, int type) { + CURLcode result = CURLE_BAD_FUNCTION_ARGUMENT; if(elem->constructed) - return NULL; /* No conversion of structured elements. */ + return CURLE_OK; /* No conversion of structured elements. */ if(!type) type = elem->tag; /* Type not forced: use element tag as type. */ switch(type) { case CURL_ASN1_BOOLEAN: - return bool2str(elem->beg, elem->end); + result = bool2str(store, elem->beg, elem->end); + break; case CURL_ASN1_INTEGER: case CURL_ASN1_ENUMERATED: - return int2str(elem->beg, elem->end); + result = int2str(store, elem->beg, elem->end); + break; case CURL_ASN1_BIT_STRING: - return bit2str(elem->beg, elem->end); + result = bit2str(store, elem->beg, elem->end); + break; case CURL_ASN1_OCTET_STRING: - return octet2str(elem->beg, elem->end); + result = octet2str(store, elem->beg, elem->end); + break; case CURL_ASN1_NULL: - return strdup(""); + result = Curl_dyn_addn(store, "", 1); + break; case CURL_ASN1_OBJECT_IDENTIFIER: - return OID2str(elem->beg, elem->end, TRUE); + result = OID2str(store, elem->beg, elem->end, TRUE); + break; case CURL_ASN1_UTC_TIME: - return UTime2str(elem->beg, elem->end); + result = UTime2str(store, elem->beg, elem->end); + break; case CURL_ASN1_GENERALIZED_TIME: - return GTime2str(elem->beg, elem->end); + result = GTime2str(store, elem->beg, elem->end); + break; case CURL_ASN1_UTF8_STRING: case CURL_ASN1_NUMERIC_STRING: case CURL_ASN1_PRINTABLE_STRING: @@ -664,87 +634,96 @@ static const char *ASN1tostr(struct Curl_asn1Element *elem, int type) case CURL_ASN1_VISIBLE_STRING: case CURL_ASN1_UNIVERSAL_STRING: case CURL_ASN1_BMP_STRING: - return string2str(type, elem->beg, elem->end); + result = utf8asn1str(store, type, elem->beg, elem->end); + break; } - return NULL; /* Unsupported. */ + return result; } /* - * ASCII encode distinguished name at `dn' into the `buflen'-sized buffer at - * `buf'. + * ASCII encode distinguished name at `dn' into the store dynbuf. * - * Returns the total string length, even if larger than `buflen' or -1 on - * error. + * Returns error. */ -static ssize_t encodeDN(char *buf, size_t buflen, struct Curl_asn1Element *dn) +static CURLcode encodeDN(struct dynbuf *store, struct Curl_asn1Element *dn) { struct Curl_asn1Element rdn; struct Curl_asn1Element atv; struct Curl_asn1Element oid; struct Curl_asn1Element value; - size_t l = 0; const char *p1; const char *p2; const char *p3; const char *str; + CURLcode result = CURLE_OK; + bool added = FALSE; + struct dynbuf temp; + Curl_dyn_init(&temp, MAX_X509_STR); for(p1 = dn->beg; p1 < dn->end;) { p1 = getASN1Element(&rdn, p1, dn->end); - if(!p1) - return -1; + if(!p1) { + result = CURLE_BAD_FUNCTION_ARGUMENT; + goto error; + } for(p2 = rdn.beg; p2 < rdn.end;) { p2 = getASN1Element(&atv, p2, rdn.end); - if(!p2) - return -1; + if(!p2) { + result = CURLE_BAD_FUNCTION_ARGUMENT; + goto error; + } p3 = getASN1Element(&oid, atv.beg, atv.end); - if(!p3) - return -1; - if(!getASN1Element(&value, p3, atv.end)) - return -1; - str = ASN1tostr(&oid, 0); - if(!str) - return -1; + if(!p3) { + result = CURLE_BAD_FUNCTION_ARGUMENT; + goto error; + } + if(!getASN1Element(&value, p3, atv.end)) { + result = CURLE_BAD_FUNCTION_ARGUMENT; + goto error; + } + Curl_dyn_reset(&temp); + result = ASN1tostr(&temp, &oid, 0); + if(result) + goto error; + + str = Curl_dyn_ptr(&temp); /* Encode delimiter. If attribute has a short uppercase name, delimiter is ", ". */ - if(l) { - for(p3 = str; ISUPPER(*p3); p3++) - ; - for(p3 = (*p3 || p3 - str > 2)? "/": ", "; *p3; p3++) { - if(l < buflen) - buf[l] = *p3; - l++; - } + for(p3 = str; ISUPPER(*p3); p3++) + ; + if(added) { + if(p3 - str > 2) + result = Curl_dyn_addn(store, "/", 1); + else + result = Curl_dyn_addn(store, ", ", 2); + if(result) + goto error; } /* Encode attribute name. */ - for(p3 = str; *p3; p3++) { - if(l < buflen) - buf[l] = *p3; - l++; - } - free((char *) str); + result = Curl_dyn_add(store, str); + if(result) + goto error; /* Generate equal sign. */ - if(l < buflen) - buf[l] = '='; - l++; + result = Curl_dyn_addn(store, "=", 1); + if(result) + goto error; /* Generate value. */ - str = ASN1tostr(&value, 0); - if(!str) - return -1; - for(p3 = str; *p3; p3++) { - if(l < buflen) - buf[l] = *p3; - l++; - } - free((char *) str); + result = ASN1tostr(store, &value, 0); + if(result) + goto error; + Curl_dyn_reset(&temp); + added = TRUE; /* use separator for next */ } } +error: + Curl_dyn_free(&temp); - return l; + return result; } #endif /* WANT_EXTRACT_CERTINFO */ @@ -873,8 +852,9 @@ int Curl_parseX509(struct Curl_X509certificate *cert, #ifdef WANT_EXTRACT_CERTINFO -static const char *dumpAlgo(struct Curl_asn1Element *param, - const char *beg, const char *end) +static CURLcode dumpAlgo(struct dynbuf *store, + struct Curl_asn1Element *param, + const char *beg, const char *end) { struct Curl_asn1Element oid; @@ -882,14 +862,16 @@ static const char *dumpAlgo(struct Curl_asn1Element *param, beg = getASN1Element(&oid, beg, end); if(!beg) - return NULL; + return CURLE_BAD_FUNCTION_ARGUMENT; param->header = NULL; param->tag = 0; param->beg = param->end = end; - if(beg < end) - if(!getASN1Element(param, beg, end)) - return NULL; - return OID2str(oid.beg, oid.end, TRUE); + if(beg < end) { + const char *p = getASN1Element(param, beg, end); + if(!p) + return CURLE_BAD_FUNCTION_ARGUMENT; + } + return OID2str(store, oid.beg, oid.end, TRUE); } /* @@ -906,24 +888,47 @@ static CURLcode ssl_push_certinfo(struct Curl_easy *data, return Curl_ssl_push_certinfo_len(data, certnum, label, value, valuelen); } -/* return 0 on success, 1 on error */ -static int do_pubkey_field(struct Curl_easy *data, int certnum, - const char *label, struct Curl_asn1Element *elem) +/* + * This is a convenience function for push_certinfo_len that takes a + * dynbuf value. + * + * It also does the verbose output if !certnum. + */ +static CURLcode ssl_push_certinfo_dyn(struct Curl_easy *data, + int certnum, + const char *label, + struct dynbuf *ptr) { - const char *output; - CURLcode result = CURLE_OK; + size_t valuelen = Curl_dyn_len(ptr); + char *value = Curl_dyn_ptr(ptr); + + CURLcode result = Curl_ssl_push_certinfo_len(data, certnum, label, + value, valuelen); + + if(!certnum && !result) + infof(data, " %s: %s", label, value); + + return result; +} + +static CURLcode do_pubkey_field(struct Curl_easy *data, int certnum, + const char *label, + struct Curl_asn1Element *elem) +{ + CURLcode result; + struct dynbuf out; + + Curl_dyn_init(&out, MAX_X509_STR); /* Generate a certificate information record for the public key. */ - output = ASN1tostr(elem, 0); - if(output) { + result = ASN1tostr(&out, elem, 0); + if(!result) { if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, label, output); - if(!certnum && !result) - infof(data, " %s: %s", label, output); - free((char *) output); + result = ssl_push_certinfo_dyn(data, certnum, label, &out); + Curl_dyn_free(&out); } - return result ? 1 : 0; + return result; } /* return 0 on success, 1 on error */ @@ -1029,24 +1034,12 @@ static int do_pubkey(struct Curl_easy *data, int certnum, /* * Convert an ASN.1 distinguished name into a printable string. - * Return the dynamically allocated string, or NULL if an error occurs. + * Return error. */ -static const char *DNtostr(struct Curl_asn1Element *dn) +static CURLcode DNtostr(struct dynbuf *store, + struct Curl_asn1Element *dn) { - char *buf = NULL; - ssize_t buflen = encodeDN(NULL, 0, dn); - - if(buflen >= 0) { - buf = malloc(buflen + 1); - if(buf) { - if(encodeDN(buf, buflen + 1, dn) == -1) { - free(buf); - return NULL; - } - buf[buflen] = '\0'; - } - } - return buf; + return encodeDN(store, dn); } CURLcode Curl_extract_certinfo(struct Curl_easy *data, @@ -1056,17 +1049,19 @@ CURLcode Curl_extract_certinfo(struct Curl_easy *data, { struct Curl_X509certificate cert; struct Curl_asn1Element param; - const char *ccp; char *certptr; size_t clen; struct dynbuf out; CURLcode result = CURLE_OK; unsigned int version; + const char *ptr; + int rc; if(!data->set.ssl.certinfo) if(certnum) return CURLE_OK; + Curl_dyn_init(&out, MAX_X509_STR); /* Prepare the certificate information for curl_easy_getinfo(). */ /* Extract the certificate ASN.1 elements. */ @@ -1074,134 +1069,124 @@ CURLcode Curl_extract_certinfo(struct Curl_easy *data, return CURLE_PEER_FAILED_VERIFICATION; /* Subject. */ - ccp = DNtostr(&cert.subject); - if(!ccp) - return CURLE_OUT_OF_MEMORY; + result = DNtostr(&out, &cert.subject); + if(result) + goto done; if(data->set.ssl.certinfo) { - result = ssl_push_certinfo(data, certnum, "Subject", ccp); + result = ssl_push_certinfo_dyn(data, certnum, "Subject", &out); if(result) - return result; + goto done; } - if(!certnum) - infof(data, "%2d Subject: %s", certnum, ccp); - free((char *) ccp); + Curl_dyn_reset(&out); /* Issuer. */ - ccp = DNtostr(&cert.issuer); - if(!ccp) - return CURLE_OUT_OF_MEMORY; + result = DNtostr(&out, &cert.issuer); + if(result) + goto done; if(data->set.ssl.certinfo) { - result = ssl_push_certinfo(data, certnum, "Issuer", ccp); + result = ssl_push_certinfo_dyn(data, certnum, "Issuer", &out); + if(result) + goto done; } - if(!certnum) - infof(data, " Issuer: %s", ccp); - free((char *) ccp); - if(result) - return result; + Curl_dyn_reset(&out); /* Version (always fits in less than 32 bits). */ version = 0; - for(ccp = cert.version.beg; ccp < cert.version.end; ccp++) - version = (version << 8) | *(const unsigned char *) ccp; + for(ptr = cert.version.beg; ptr < cert.version.end; ptr++) + version = (version << 8) | *(const unsigned char *) ptr; if(data->set.ssl.certinfo) { - ccp = curl_maprintf("%x", version); - if(!ccp) - return CURLE_OUT_OF_MEMORY; - result = ssl_push_certinfo(data, certnum, "Version", ccp); - free((char *) ccp); + result = Curl_dyn_addf(&out, "%x", version); if(result) - return result; + goto done; + result = ssl_push_certinfo_dyn(data, certnum, "Version", &out); + if(result) + goto done; + Curl_dyn_reset(&out); } - if(!certnum) - infof(data, " Version: %u (0x%x)", version + 1, version); /* Serial number. */ - ccp = ASN1tostr(&cert.serialNumber, 0); - if(!ccp) - return CURLE_OUT_OF_MEMORY; - if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, "Serial Number", ccp); - if(!certnum) - infof(data, " Serial Number: %s", ccp); - free((char *) ccp); + result = ASN1tostr(&out, &cert.serialNumber, 0); if(result) - return result; + goto done; + if(data->set.ssl.certinfo) { + result = ssl_push_certinfo_dyn(data, certnum, "Serial Number", &out); + if(result) + goto done; + } + Curl_dyn_reset(&out); /* Signature algorithm .*/ - ccp = dumpAlgo(¶m, cert.signatureAlgorithm.beg, - cert.signatureAlgorithm.end); - if(!ccp) - return CURLE_OUT_OF_MEMORY; - if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, "Signature Algorithm", ccp); - if(!certnum) - infof(data, " Signature Algorithm: %s", ccp); - free((char *) ccp); + result = dumpAlgo(&out, ¶m, cert.signatureAlgorithm.beg, + cert.signatureAlgorithm.end); if(result) - return result; + goto done; + if(data->set.ssl.certinfo) { + result = ssl_push_certinfo_dyn(data, certnum, "Signature Algorithm", + &out); + if(result) + goto done; + } + Curl_dyn_reset(&out); /* Start Date. */ - ccp = ASN1tostr(&cert.notBefore, 0); - if(!ccp) - return CURLE_OUT_OF_MEMORY; - if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, "Start Date", ccp); - if(!certnum) - infof(data, " Start Date: %s", ccp); - free((char *) ccp); + result = ASN1tostr(&out, &cert.notBefore, 0); if(result) - return result; + goto done; + if(data->set.ssl.certinfo) { + result = ssl_push_certinfo_dyn(data, certnum, "Start Date", &out); + if(result) + goto done; + } + Curl_dyn_reset(&out); /* Expire Date. */ - ccp = ASN1tostr(&cert.notAfter, 0); - if(!ccp) - return CURLE_OUT_OF_MEMORY; - if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, "Expire Date", ccp); - if(!certnum) - infof(data, " Expire Date: %s", ccp); - free((char *) ccp); + result = ASN1tostr(&out, &cert.notAfter, 0); if(result) - return result; + goto done; + if(data->set.ssl.certinfo) { + result = ssl_push_certinfo_dyn(data, certnum, "Expire Date", &out); + if(result) + goto done; + } + Curl_dyn_reset(&out); /* Public Key Algorithm. */ - ccp = dumpAlgo(¶m, cert.subjectPublicKeyAlgorithm.beg, - cert.subjectPublicKeyAlgorithm.end); - if(!ccp) - return CURLE_OUT_OF_MEMORY; - if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, "Public Key Algorithm", - ccp); - if(!result) { - int ret; - if(!certnum) - infof(data, " Public Key Algorithm: %s", ccp); - ret = do_pubkey(data, certnum, ccp, ¶m, &cert.subjectPublicKey); - if(ret) - result = CURLE_OUT_OF_MEMORY; /* the most likely error */ - } - free((char *) ccp); + result = dumpAlgo(&out, ¶m, cert.subjectPublicKeyAlgorithm.beg, + cert.subjectPublicKeyAlgorithm.end); if(result) - return result; + goto done; + if(data->set.ssl.certinfo) { + result = ssl_push_certinfo_dyn(data, certnum, "Public Key Algorithm", + &out); + if(result) + goto done; + } + + rc = do_pubkey(data, certnum, Curl_dyn_ptr(&out), + ¶m, &cert.subjectPublicKey); + if(rc) { + result = CURLE_OUT_OF_MEMORY; /* the most likely error */ + goto done; + } + Curl_dyn_reset(&out); /* Signature. */ - ccp = ASN1tostr(&cert.signature, 0); - if(!ccp) - return CURLE_OUT_OF_MEMORY; - if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, "Signature", ccp); - if(!certnum) - infof(data, " Signature: %s", ccp); - free((char *) ccp); + result = ASN1tostr(&out, &cert.signature, 0); if(result) - return result; + goto done; + if(data->set.ssl.certinfo) { + result = ssl_push_certinfo_dyn(data, certnum, "Signature", &out); + if(result) + goto done; + } + Curl_dyn_reset(&out); /* Generate PEM certificate. */ result = Curl_base64_encode(cert.certificate.beg, cert.certificate.end - cert.certificate.beg, &certptr, &clen); if(result) - return result; + goto done; /* Generate the final output certificate string. Format is: -----BEGIN CERTIFICATE-----\n @@ -1212,7 +1197,7 @@ CURLcode Curl_extract_certinfo(struct Curl_easy *data, -----END CERTIFICATE-----\n */ - Curl_dyn_init(&out, MAX_X509_CERT); + Curl_dyn_reset(&out); /* Build the certificate string. */ result = Curl_dyn_add(&out, "-----BEGIN CERTIFICATE-----\n"); @@ -1230,13 +1215,11 @@ CURLcode Curl_extract_certinfo(struct Curl_easy *data, result = Curl_dyn_add(&out, "-----END CERTIFICATE-----\n"); } free(certptr); - if(!result) { + if(!result) if(data->set.ssl.certinfo) - result = ssl_push_certinfo(data, certnum, "Cert", - Curl_dyn_ptr(&out)); - if(!certnum) - infof(data, "%s", Curl_dyn_ptr(&out)); - } + result = ssl_push_certinfo_dyn(data, certnum, "Cert", &out); + +done: Curl_dyn_free(&out); return result; } From bdae275958613c256be99c8512e0b9f54e1ede8d Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 26 Jan 2024 09:21:37 +0100 Subject: [PATCH 246/509] mqtt, remove remaining use of data->state.buffer Closes #12799 --- lib/mqtt.c | 5 ++--- lib/mqtt.h | 1 + 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/mqtt.c b/lib/mqtt.c index 704ffaf60dd..5a9d6d0f10a 100644 --- a/lib/mqtt.c +++ b/lib/mqtt.c @@ -745,7 +745,6 @@ static CURLcode mqtt_doing(struct Curl_easy *data, bool *done) struct MQTT *mq = data->req.p.mqtt; ssize_t nread; curl_socket_t sockfd = conn->sock[FIRSTSOCKET]; - unsigned char *pkt = (unsigned char *)data->state.buffer; unsigned char byte; *done = FALSE; @@ -783,7 +782,7 @@ static CURLcode mqtt_doing(struct Curl_easy *data, bool *done) if(!nread) break; Curl_debug(data, CURLINFO_HEADER_IN, (char *)&byte, 1); - pkt[mq->npacket++] = byte; + mq->pkt_hd[mq->npacket++] = byte; } while((byte & 0x80) && (mq->npacket < 4)); if(nread && (byte & 0x80)) /* MQTT supports up to 127 * 128^0 + 127 * 128^1 + 127 * 128^2 + @@ -791,7 +790,7 @@ static CURLcode mqtt_doing(struct Curl_easy *data, bool *done) result = CURLE_WEIRD_SERVER_REPLY; if(result) break; - mq->remaining_length = mqtt_decode_len(&pkt[0], mq->npacket, NULL); + mq->remaining_length = mqtt_decode_len(mq->pkt_hd, mq->npacket, NULL); mq->npacket = 0; if(mq->remaining_length) { mqstate(data, mqtt->nextstate, MQTT_NOSTATE); diff --git a/lib/mqtt.h b/lib/mqtt.h index 84f177022eb..99ab12a98a4 100644 --- a/lib/mqtt.h +++ b/lib/mqtt.h @@ -57,6 +57,7 @@ struct MQTT { unsigned char firstbyte; size_t remaining_length; struct dynbuf recvbuf; + unsigned char pkt_hd[4]; /* for decoding the arriving packet length */ }; #endif /* HEADER_CURL_MQTT_H */ From 6422ab6745c37f491d83c897ddb70b1bf782790e Mon Sep 17 00:00:00 2001 From: Scarlett McAllister Date: Fri, 26 Jan 2024 21:10:49 -0400 Subject: [PATCH 247/509] _VARIABLES.md: add missing 'be' into the sentence Closes #12809 --- docs/cmdline-opts/_VARIABLES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cmdline-opts/_VARIABLES.md b/docs/cmdline-opts/_VARIABLES.md index 0415fd78f24..3e17bfdaeac 100644 --- a/docs/cmdline-opts/_VARIABLES.md +++ b/docs/cmdline-opts/_VARIABLES.md @@ -5,7 +5,7 @@ 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 +Variable contents can be 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 From 066ed4e51417492605ac3465cb052e62f322d78b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 27 Jan 2024 13:54:10 +0100 Subject: [PATCH 248/509] http: only act on 101 responses when they are HTTP/1.1 For 101 responses claiming to be any other protocol, bail out. This would previously trigger an assert. Add test 1704 to verify. Bug: https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=66184 Closes #12811 --- lib/http.c | 56 ++++++++++++++++++---------------- tests/data/Makefile.inc | 2 +- tests/data/test1704 | 66 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 26 deletions(-) create mode 100644 tests/data/test1704 diff --git a/lib/http.c b/lib/http.c index 0c2a4609035..679931e4b4a 100644 --- a/lib/http.c +++ b/lib/http.c @@ -4036,34 +4036,40 @@ static CURLcode http_rw_headers(struct Curl_easy *data, } break; case 101: - /* Switching Protocols */ - if(k->upgr101 == UPGR101_H2) { - /* Switching to HTTP/2 */ - DEBUGASSERT(conn->httpversion < 20); - infof(data, "Received 101, Switching to HTTP/2"); - k->upgr101 = UPGR101_RECEIVED; - - /* we'll get more headers (HTTP/2 response) */ - k->header = TRUE; - k->headerline = 0; /* restart the header line counter */ - switch_to_h2 = TRUE; - } + if(conn->httpversion == 11) { + /* Switching Protocols only allowed from HTTP/1.1 */ + if(k->upgr101 == UPGR101_H2) { + /* Switching to HTTP/2 */ + infof(data, "Received 101, Switching to HTTP/2"); + k->upgr101 = UPGR101_RECEIVED; + + /* we'll get more headers (HTTP/2 response) */ + k->header = TRUE; + k->headerline = 0; /* restart the header line counter */ + switch_to_h2 = TRUE; + } #ifdef USE_WEBSOCKETS - else if(k->upgr101 == UPGR101_WS) { - /* verify the response */ - result = Curl_ws_accept(data, buf, blen); - if(result) - return result; - k->header = FALSE; /* no more header to parse! */ - *pconsumed += blen; /* ws accept handled the data */ - blen = 0; - if(data->set.connect_only) - k->keepon &= ~KEEP_RECV; /* read no more content */ - } + else if(k->upgr101 == UPGR101_WS) { + /* verify the response */ + result = Curl_ws_accept(data, buf, blen); + if(result) + return result; + k->header = FALSE; /* no more header to parse! */ + *pconsumed += blen; /* ws accept handled the data */ + blen = 0; + if(data->set.connect_only) + k->keepon &= ~KEEP_RECV; /* read no more content */ + } #endif + else { + /* Not switching to another protocol */ + k->header = FALSE; /* no more header to parse! */ + } + } else { - /* Not switching to another protocol */ - k->header = FALSE; /* no more header to parse! */ + /* invalid for other HTTP versions */ + failf(data, "unexpected 101 response code"); + return CURLE_WEIRD_SERVER_REPLY; } break; default: diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 5b9e3a9ed21..c3d496f6468 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -215,7 +215,7 @@ test1670 test1671 \ \ test1680 test1681 test1682 test1683 \ \ -test1700 test1701 test1702 test1703 \ +test1700 test1701 test1702 test1703 test1704 \ \ test1800 test1801 \ \ diff --git a/tests/data/test1704 b/tests/data/test1704 new file mode 100644 index 00000000000..a8f285eeab2 --- /dev/null +++ b/tests/data/test1704 @@ -0,0 +1,66 @@ + + + +HTTP +HTTP GET +HTTP/2 + + + +# +# Server-side + + +HTTP/2 101 OK + +HTTP/1.1 200 OK +Date: Tue, 09 Nov 2010 14:49:00 GMT +Content-Length: 6 +Connection: close +Content-Type: text/html + +-maa- + + + +# +# Client-side + + +h2c + + +http + + +HTTP/1 doing HTTP/2 Upgrade: getting a HTTP/2 101 response + + +http://%HOSTIP:%HTTPPORT/%TESTNUMBER --http2 + + + +# +# Verify data after the test has been "shot" + + +^X-Forwarded-Proto:.* +^Via:.* + + +GET /%TESTNUMBER HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +User-Agent: curl/%VERSION +Accept: */* +Connection: Upgrade, HTTP2-Settings +Upgrade: h2c +HTTP2-Settings: AAMAAABkAAQAoAAAAAIAAAAA + + + +# CURLE_WEIRD_SERVER_REPLY (8) + +8 + + + From ecb5d6bee9da7a6a0687f4eed0798268cce87d46 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 27 Jan 2024 22:02:50 +0100 Subject: [PATCH 249/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 84 ++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 69 insertions(+), 15 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 2b7c8491a76..b9a14f459a6 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.6.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3073 + Contributors: 3078 This release includes the following changes: @@ -13,6 +13,8 @@ This release includes the following changes: o add CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add [39] o asyn-thread: use GetAddrInfoExW on >= Windows 8 [55] o configure: make libpsl detection failure cause error [109] + o docs/cmdline: change to .md for cmdline docs [77] + o docs: introduce "curldown" for libcurl man page format [102] o runtests: support -gl. Like -g but for lldb. [47] This release includes the following bugfixes: @@ -30,15 +32,17 @@ This release includes the following bugfixes: o cf-h1-proxy: no CURLOPT_USERAGENT in CONNECT with hyper [133] o cf-socket: show errno in tcpkeepalive error messages [120] o CI/distcheck: run full tests [31] + o CI: remove unnecessary OpenSSL 3 option `enable-tls1_3` [168] o cmake: add option to disable building docs o cmake: fix generation for system name iOS [53] o cmake: fix typo [5] o cmake: prefill/cache `HAVE_STRUCT_SOCKADDR_STORAGE` [45] + o cmake: rework options to enable curl and libcurl docs [161] o cmake: when USE_MANUAL=YES, build the curl.1 man page [113] - o cmdline-docs: use .IP consistently [13] o cmdline-opts/write-out.d: remove spurious double quotes o cmdline-opts: update availability for the *-ca-native options [66] o cmdline/gen: fix the sorting of the man page options [33] + o configure: add libngtcp2_crypto_boringssl detection [155] o configure: fix no default int compile error in ipv6 detection [69] o configure: when enabling QUIC, check that TLS supports QUIC [87] o connect: remove margin from eyeballer alloc [79] @@ -54,18 +58,22 @@ This release includes the following bugfixes: o CURLOPT_POSTFIELDS.3: fix incorrect C string escape in example [27] o CURLOPT_SSH_*_KEYFILE: clarify [57] o dist: add tests/errorcodes.pl to the tarball [6] - o docs/cmdline: change to .md for cmdline docs [77] o docs: clean up Protocols: for cmdline options [32] o docs: describe and highlight super cookies [80] - o docs: introduce "curldown" for libcurl man page format [102] + o docs: do not start lines/sentences with So, But nor And [140] + o docs: install curl.1 with cmake as well [166] o docs: mention env vars not used by schannel [124] o doh: remove unused local variable [34] o examples: add four new examples [99] + o file+ftp: use stack buffers instead of data->state.buffer [138] o ftp: handle the PORT parsing without allocation [44] o ftp: use dynbuf to store entrypath [83] o ftp: use memdup0 to store the OS from a SYST 215 response [82] + o ftpserver.pl: send 213 SIZE response without spurious newline o gen.pl: support ## for doing .IP in table-like lists [105] o gen: do italics/bold for a range of letters, not just single word [78] + o GHA: add a job scanning for "bad words" in markdown [164] + o GHA: bump ngtcp2, gnutls, mod_h2, quiche [158] o gnutls: fix build with --disable-verbose [3] o haproxy-clientip.d: document the arg [68] o headers: make sure the trailing newline is not stored [97] @@ -76,8 +84,13 @@ This release includes the following bugfixes: o http3/quiche: fix result code on a stream reset [91] o http3: initial support for OpenSSL 3.2 QUIC stack [110] o http: adjust_pollset fix [85] + o http: check for "Host:" case insensitively [154] o http: fix off-by-one error in request method length check [14] + o http: only act on 101 responses when they are HTTP/1.1 [98] + o http: remove comment reference to a removed solution [156] + o http: use stack scratch buffer [150] o http_proxy: a blank CURLOPT_USERAGENT should not be used in CONNECT [90] + o krb5: add prototype to silence clang warnings on mvsnprintf() [119] o lib: add debug log outputs for CURLE_BAD_FUNCTION_ARGUMENT [62] o lib: fix variable undeclared error caused by `infof` changes [2] o lib: reduce use of strncpy [30] @@ -94,30 +107,40 @@ This release includes the following bugfixes: o mime: use memdup0 instead of malloc + memcpy [63] o mksymbolsmanpage.pl: provide references to where the symbol is used o mprintf: overhaul and bugfixes [52] + o mqtt: use stack scratch buffer for recv+publish [148] o multi: remove total timer reset in file_do() while fetching file:// [89] o ngtcp2: put h3 at the front of alpn [58] + o ntlm_wb: do not use data->state.buffer any longer [151] o openldap: fix an LDAP crash [75] o openldap: fix STARTTLS [67] o openssl: re-match LibreSSL deinit with init [17] o openssl: when verifystatus fails, remove session id from cache [100] + o pingpong: stop using the download buffer [159] o pop3: replace calloc + memcpy with memdup0 [60] + o pytest: scorecard tracking CPU and RSS [157] o quiche: return CURLE_HTTP3 on send to invalid stream [65] o readwrite_data: loop less [21] o Revert "urldata: move async resolver state from easy handle to connectdata" [16] o rtsp: deal with borked server responses [129] o runtests: for mode="text" on , fix newlines on both parts [64] + o sasl: make login option string override http auth [142] o schannel: fix `-Warith-conversion` gcc 13 warning [28] o sectransp: do verify_cert without memdup for blobs [93] o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] o sendf: fix compiler warning with CURL_DISABLE_HEADERS_API [38] o setopt: clear mimepost when formp is freed [92] o setopt: use memdup0 when cloning COPYPOSTFIELDS [107] + o socks: fix generic output string to say SOCKS instead of SOCKS4 [144] + o socks: use own buffer instead of data->state.buffer [143] o ssh: fix namespace of two local macros [51] + o ssh: use stack scratch buffer for seeks [146] o strerror: repair get_winsock_error() [56] o system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers [9] o system_win32: fix a function pointer assignment warning [71] o telnet: use dynbuf instad of malloc for escape buffer [108] + o telnet: use stack scratch buffer for do [149] o tests/server: delete workaround for old-mingw [25] + o tests: avoid int/size_t conversion size/sign warnings [163] o tests: respect $TMPDIR when creating unix domain sockets [50] o tool: make parser reject blank arguments if not supported [86] o tool: prepend output_dir in header callback [95] @@ -133,16 +156,20 @@ This release includes the following bugfixes: o transfer: remove warning: Value stored to 'blen' is never read [136] o url: don't set default CA paths for Secure Transport backend [126] o url: for disabled protocols, mention if found in redirect [7] + o urlapi: remove assert [162] o verify-examples.pl: fail verification on unescaped backslash [72] o version: show only the libpsl version, not its dependencies [130] o vquic: extract TLS setup into own source [88] o vtls: fix missing multissl version info [73] + o vtls: receive max buffer [139] o vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY [41] o websockets: check for negative payload lengths [123] o websockets: refactor decode chain [122] o windows: delete redundant headers [43] o windows: simplify detecting and using system headers [10] o wolfssl: load certificate *chain* for PEM client certs [84] + o x509asn1: remove code for WANT_VERIFYHOST [132] + o x509asn1: switch from malloc to dynbuf [112] This release includes the following known bugs: @@ -161,16 +188,17 @@ advice from friends like these: bubbleguuum on github, Cajus Pollmeier, calvin2021y on github, Chara White, Chris Sauer, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, dependabot[bot], Dmitry Karpov, Gabe, Geeknik Labs, Gisle Vanem, - Hans-Christian Egtvedt, Harry Sintonen, Haydar Alaidrus, hgdagon on github, - Hiroki Kurosawa, iAroc on github, ivanfywang, janko-js on github, Jay Wu, - Jess Lowe, Karthikdasari0423 on github, Lealem Amedie, Lin Sun, Marcel Raad, - Mark Huang, Mark Sinkovics, Mauricio Scheffer, Michał Antoniak, Mike Hommey, - Mohammadreza Hendiani, Ozan Cansel, Patrick Monnerat, Pavel Pavlov, - Ray Satiro, RevaliQaQ on github, Richard Levitte, Sergey Bronnikov, - Sergey Markelov, sfan5 on github, Stefan Eissing, Tatsuhiko Miyagawa, Theo, - Thomas Ferguson, Viktor Szakats, Xi Ruoyao, Yadhu Krishna M, Yedaya Katsman, - Yifei Kong, YX Hao, zengwei, zengwei2000 - (60 contributors) + Graham Campbell, Hans-Christian Egtvedt, Harry Sintonen, Haydar Alaidrus, + hgdagon on github, Hiroki Kurosawa, iAroc on github, ivanfywang, + janko-js on github, Jay Wu, Jess Lowe, Karthikdasari0423 on github, + Lealem Amedie, Lin Sun, Marcel Raad, Mark Huang, Mark Sinkovics, + Mauricio Scheffer, Michał Antoniak, Mike Hommey, Mohammadreza Hendiani, + Ozan Cansel, Patrick Monnerat, Pavel Pavlov, promptfuzz_ on hackerone, + Ray Satiro, RevaliQaQ on github, Richard Levitte, Scarlett McAllister, + Sergey Bronnikov, Sergey Markelov, sfan5 on github, Stefan Eissing, + Tatsuhiko Miyagawa, Tatsuhiro Tsujikawa, Theo, Thomas Ferguson, + Viktor Szakats, Xi Ruoyao, Yadhu Krishna M, Yedaya Katsman, Yifei Kong, + YX Hao, zengwei, zengwei2000, ウさん (65 contributors) References to bug reports and discussions on issues: @@ -186,7 +214,6 @@ References to bug reports and discussions on issues: [10] = https://curl.se/bug/?i=12495 [11] = https://curl.se/bug/?i=12489 [12] = https://curl.se/bug/?i=12224 - [13] = https://curl.se/bug/?i=12535 [14] = https://curl.se/bug/?i=12534 [15] = https://curl.se/mail/archive-2023-12/0026.html [16] = https://curl.se/bug/?i=12524 @@ -271,6 +298,7 @@ References to bug reports and discussions on issues: [95] = https://curl.se/bug/?i=12614 [96] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65661 [97] = https://curl.se/mail/lib-2024-01/0019.html + [98] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=66184 [99] = https://curl.se/bug/?i=12671 [100] = https://curl.se/bug/?i=12760 [102] = https://curl.se/bug/?i=12730 @@ -282,10 +310,12 @@ References to bug reports and discussions on issues: [108] = https://curl.se/bug/?i=12652 [109] = https://curl.se/bug/?i=12661 [110] = https://curl.se/bug/?i=12734 + [112] = https://curl.se/bug/?i=12808 [113] = https://curl.se/bug/?i=12742 [115] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65839 [116] = https://curl.se/bug/?i=12727 [117] = https://curl.se/bug/?i=12720 + [119] = https://curl.se/bug/?i=12803 [120] = https://curl.se/bug/?i=12726 [121] = https://curl.se/bug/?i=12645 [122] = https://curl.se/bug/?i=12713 @@ -298,7 +328,31 @@ References to bug reports and discussions on issues: [129] = https://curl.se/bug/?i=12701 [130] = https://curl.se/bug/?i=12700 [131] = https://curl.se/bug/?i=12695 + [132] = https://curl.se/bug/?i=12804 [133] = https://curl.se/bug/?i=12697 [134] = https://curl.se/bug/?i=12691 [136] = https://curl.se/bug/?i=12693 [137] = https://curl.se/bug/?i=12480 + [138] = https://curl.se/bug/?i=12789 + [139] = https://curl.se/bug/?i=12801 + [140] = https://curl.se/bug/?i=12802 + [142] = https://curl.se/bug/?i=10259 + [143] = https://curl.se/bug/?i=12788 + [144] = https://curl.se/bug/?i=12797 + [146] = https://curl.se/bug/?i=12794 + [148] = https://curl.se/bug/?i=12792 + [149] = https://curl.se/bug/?i=12793 + [150] = https://curl.se/bug/?i=12791 + [151] = https://curl.se/bug/?i=12787 + [154] = https://curl.se/bug/?i=12784 + [155] = https://curl.se/bug/?i=12724 + [156] = https://curl.se/bug/?i=12785 + [157] = https://curl.se/bug/?i=12765 + [158] = https://curl.se/bug/?i=12778 + [159] = https://curl.se/bug/?i=12757 + [161] = https://curl.se/bug/?i=12773 + [162] = https://curl.se/bug/?i=12775 + [163] = https://curl.se/bug/?i=12768 + [164] = https://curl.se/bug/?i=12764 + [166] = https://curl.se/bug/?i=12759 + [168] = https://curl.se/bug/?i=12758 From 5b286c250829e06a135a6ba998e80beb7f43a734 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sat, 27 Jan 2024 17:40:38 +0000 Subject: [PATCH 250/509] build: delete/replace clang warning pragmas - delete redundant warning suppressions for `-Wformat-nonliteral`. This now relies on `CURL_PRINTF()` and it's theoratically possible that this macro isn't active but the warning is. We're ignoring this as a corner-case here. - replace two pragmas with code changes to avoid the warnings. Follow-up to aee4ebe59161d0a5281743f96e7738ad97fe1cd4 #12803 Follow-up to 09230127589eccc7e01c1a7217787ef8e64f3328 #12540 Follow-up to 3829759bd042c03225ae862062560f568ba1a231 #12489 Reviewed-by: Daniel Stenberg Closes #12812 --- lib/curl_trc.c | 21 --------------------- lib/dict.c | 7 ------- lib/dynbuf.c | 7 ------- lib/memdebug.c | 7 ------- lib/mime.c | 7 ------- src/tool_easysrc.c | 7 ------- src/tool_msgs.c | 7 ------- src/tool_setopt.c | 19 ++++--------------- tests/libtest/lib1560.c | 10 +--------- 9 files changed, 5 insertions(+), 87 deletions(-) diff --git a/lib/curl_trc.c b/lib/curl_trc.c index 1c49d553568..b8dccc41937 100644 --- a/lib/curl_trc.c +++ b/lib/curl_trc.c @@ -92,14 +92,7 @@ void Curl_failf(struct Curl_easy *data, const char *fmt, ...) int len; char error[CURL_ERROR_SIZE + 2]; va_start(ap, fmt); -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif len = mvsnprintf(error, CURL_ERROR_SIZE, fmt, ap); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif if(data->set.errorbuffer && !data->state.errorbuf) { strcpy(data->set.errorbuffer, error); @@ -125,14 +118,7 @@ void Curl_infof(struct Curl_easy *data, const char *fmt, ...) int len; char buffer[MAXINFO + 2]; va_start(ap, fmt); -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif len = mvsnprintf(buffer, MAXINFO, fmt, ap); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif va_end(ap); buffer[len++] = '\n'; buffer[len] = '\0'; @@ -150,14 +136,7 @@ void Curl_trc_cf_infof(struct Curl_easy *data, struct Curl_cfilter *cf, char buffer[MAXINFO + 2]; len = msnprintf(buffer, MAXINFO, "[%s] ", cf->cft->name); va_start(ap, fmt); -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif len += mvsnprintf(buffer + len, MAXINFO - len, fmt, ap); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif va_end(ap); buffer[len++] = '\n'; buffer[len] = '\0'; diff --git a/lib/dict.c b/lib/dict.c index 2d6e7e48c5c..323984822df 100644 --- a/lib/dict.c +++ b/lib/dict.c @@ -135,14 +135,7 @@ static CURLcode sendf(curl_socket_t sockfd, struct Curl_easy *data, char *sptr; va_list ap; va_start(ap, fmt); -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif s = vaprintf(fmt, ap); /* returns an allocated string */ -#ifdef __clang__ -#pragma clang diagnostic pop -#endif va_end(ap); if(!s) return CURLE_OUT_OF_MEMORY; /* failure */ diff --git a/lib/dynbuf.c b/lib/dynbuf.c index a6a71c5daa8..a4c599d10c7 100644 --- a/lib/dynbuf.c +++ b/lib/dynbuf.c @@ -204,14 +204,7 @@ CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap) return CURLE_OUT_OF_MEMORY; #else char *str; -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif str = vaprintf(fmt, ap); /* this allocs a new string to append */ -#ifdef __clang__ -#pragma clang diagnostic pop -#endif if(str) { CURLcode result = dyn_nappend(s, (unsigned char *)str, strlen(str)); diff --git a/lib/memdebug.c b/lib/memdebug.c index f3d48172333..fce933a3224 100644 --- a/lib/memdebug.c +++ b/lib/memdebug.c @@ -448,14 +448,7 @@ void curl_dbg_log(const char *format, ...) return; va_start(ap, format); -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif nchars = mvsnprintf(buf, LOGLINE_BUFSIZE, format, ap); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif va_end(ap); if(nchars > LOGLINE_BUFSIZE - 1) diff --git a/lib/mime.c b/lib/mime.c index e6553816fa3..d712331d040 100644 --- a/lib/mime.c +++ b/lib/mime.c @@ -1677,14 +1677,7 @@ CURLcode Curl_mime_add_header(struct curl_slist **slp, const char *fmt, ...) va_list ap; va_start(ap, fmt); -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif s = curl_mvaprintf(fmt, ap); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif va_end(ap); if(s) { diff --git a/src/tool_easysrc.c b/src/tool_easysrc.c index 8b9c68c91fe..6ef2be721cf 100644 --- a/src/tool_easysrc.c +++ b/src/tool_easysrc.c @@ -113,14 +113,7 @@ CURLcode easysrc_addf(struct slist_wc **plist, const char *fmt, ...) char *bufp; va_list ap; va_start(ap, fmt); -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif bufp = curlx_mvaprintf(fmt, ap); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif va_end(ap); if(!bufp) { ret = CURLE_OUT_OF_MEMORY; diff --git a/src/tool_msgs.c b/src/tool_msgs.c index d11c5186bfe..04fae58a9ba 100644 --- a/src/tool_msgs.c +++ b/src/tool_msgs.c @@ -53,14 +53,7 @@ static void voutf(struct GlobalConfig *config, char *ptr; char *print_buffer; -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif print_buffer = curlx_mvaprintf(fmt, ap); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif if(!print_buffer) return; len = strlen(print_buffer); diff --git a/src/tool_setopt.c b/src/tool_setopt.c index 1c3096b8b46..b41b6d1d263 100644 --- a/src/tool_setopt.c +++ b/src/tool_setopt.c @@ -240,22 +240,11 @@ static char *c_escape(const char *str, curl_off_t len) if(p && *p) result = curlx_dyn_addn(&escaped, to + 2 * (p - from), 2); else { - const char *format = "\\x%02x"; - - if(len > 1 && ISXDIGIT(s[1])) { - /* Octal escape to avoid >2 digit hex. */ - format = "\\%03o"; - } - -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif - result = curlx_dyn_addf(&escaped, format, + result = curlx_dyn_addf(&escaped, + /* Octal escape to avoid >2 digit hex. */ + (len > 1 && ISXDIGIT(s[1])) ? + "\\%03o" : "\\x%02x", (unsigned int) *(unsigned char *) s); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif } } } diff --git a/tests/libtest/lib1560.c b/tests/libtest/lib1560.c index 6e734d2bf2d..1509c76a7fd 100644 --- a/tests/libtest/lib1560.c +++ b/tests/libtest/lib1560.c @@ -1639,7 +1639,6 @@ static char bigpart[120000]; */ static int huge(void) { - const char *url = "%s://%s:%s@%s/%s?%s#%s"; const char *smallpart = "c"; int i; CURLU *urlp = curl_url(); @@ -1662,12 +1661,8 @@ static int huge(void) for(i = 0; i < 7; i++) { char *partp; -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif msnprintf(total, sizeof(total), - url, + "%s://%s:%s@%s/%s?%s#%s", (i == 0)? &bigpart[1] : smallpart, (i == 1)? &bigpart[1] : smallpart, (i == 2)? &bigpart[1] : smallpart, @@ -1675,9 +1670,6 @@ static int huge(void) (i == 4)? &bigpart[1] : smallpart, (i == 5)? &bigpart[1] : smallpart, (i == 6)? &bigpart[1] : smallpart); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif rc = curl_url_set(urlp, CURLUPART_URL, total, CURLU_NON_SUPPORT_SCHEME); if((!i && (rc != CURLUE_BAD_SCHEME)) || (i && rc)) { From 0f4c19b66ad5c646ebc3c4268a0f3ad9c15bf57c Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Wed, 24 Jan 2024 13:07:00 +0100 Subject: [PATCH 251/509] cmake: freshen up docs/INSTALL.cmake - Turn docs/INSTALL.cmake into a proper markdown file, docs/INSTALL-CMAKE.md - Move things around to divide the description into configuration, building and installing sections - Mention the more modern cmake options to configure, build and install, but also retain the older variants as fallbacks Closes #12772 --- .github/scripts/spellcheck.words | 2 + docs/INSTALL-CMAKE.md | 133 +++++++++++++++++++++++++++++++ docs/INSTALL.cmake | 89 --------------------- docs/Makefile.am | 2 +- 4 files changed, 136 insertions(+), 90 deletions(-) create mode 100644 docs/INSTALL-CMAKE.md delete mode 100644 docs/INSTALL.cmake diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index 974f029268a..4495454e174 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -111,6 +111,7 @@ clientp cliget closesocket CMake +CMake's cmake cmake's CMakeLists @@ -288,6 +289,7 @@ GSS GSSAPI GTFO Guenter +GUIs Gunderson Gustafsson gzip diff --git a/docs/INSTALL-CMAKE.md b/docs/INSTALL-CMAKE.md new file mode 100644 index 00000000000..6dad38740ac --- /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 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 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 will be 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 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. + +## 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/Makefile.am b/docs/Makefile.am index b3f2b07c8a2..fbe94c40e5f 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -72,7 +72,7 @@ EXTRA_DIST = \ HTTP3.md \ HYPER.md \ INSTALL \ - INSTALL.cmake \ + INSTALL-CMAKE.md \ INSTALL.md \ INTERNALS.md \ KNOWN_BUGS \ From cb343182b7181c6df57e7bb711e418ae447fd443 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Sun, 28 Jan 2024 00:06:37 +0000 Subject: [PATCH 252/509] build: delete/replace 3 more clang warning pragmas - tool_msgs: delete redundant `-Wformat-nonliteral` suppression pragma. - whitespace formatting in `mprintf.h`, lib518, lib537. - lib518: fix wrong variable in `sizeof()`. - lib518: bump variables to `rlim_t`. Follow-up to e2b394106d543c4615a60795b7fdce04bd4e5090 #1469 - lib518: sync error message with lib537 Follow-up to 365322b8bcf9efb6a361473d227b70f2032212ce - lib518, lib537: replace `-Wformat-nonliteral` suppression pragmas by reworking test code. Follow-up to 5b286c250829e06a135a6ba998e80beb7f43a734 #12812 Follow-up to aee4ebe59161d0a5281743f96e7738ad97fe1cd4 #12803 Follow-up to 09230127589eccc7e01c1a7217787ef8e64f3328 #12540 Follow-up to 3829759bd042c03225ae862062560f568ba1a231 #12489 Reviewed-by: Daniel Stenberg Closes #12814 --- include/curl/mprintf.h | 6 ++- src/tool_msgs.c | 7 --- tests/libtest/lib518.c | 111 ++++++++++++++++------------------------- tests/libtest/lib537.c | 94 ++++++++++++++-------------------- 4 files changed, 85 insertions(+), 133 deletions(-) diff --git a/include/curl/mprintf.h b/include/curl/mprintf.h index 30e5ffe50db..4f704548d19 100644 --- a/include/curl/mprintf.h +++ b/include/curl/mprintf.h @@ -46,13 +46,15 @@ extern "C" { #define CURL_TEMP_PRINTF(fmt, arg) #endif -CURL_EXTERN int curl_mprintf(const char *format, ...) CURL_TEMP_PRINTF(1, 2); +CURL_EXTERN int curl_mprintf(const char *format, ...) + CURL_TEMP_PRINTF(1, 2); CURL_EXTERN int curl_mfprintf(FILE *fd, const char *format, ...) CURL_TEMP_PRINTF(2, 3); CURL_EXTERN int curl_msprintf(char *buffer, const char *format, ...) CURL_TEMP_PRINTF(2, 3); CURL_EXTERN int curl_msnprintf(char *buffer, size_t maxlength, - const char *format, ...) CURL_TEMP_PRINTF(3, 4); + const char *format, ...) + CURL_TEMP_PRINTF(3, 4); CURL_EXTERN int curl_mvprintf(const char *format, va_list args) CURL_TEMP_PRINTF(1, 0); CURL_EXTERN int curl_mvfprintf(FILE *fd, const char *format, va_list args) diff --git a/src/tool_msgs.c b/src/tool_msgs.c index 04fae58a9ba..09c9310a523 100644 --- a/src/tool_msgs.c +++ b/src/tool_msgs.c @@ -124,14 +124,7 @@ void helpf(FILE *errors, const char *fmt, ...) va_start(ap, fmt); DEBUGASSERT(!strchr(fmt, '\n')); fputs("curl: ", errors); /* prefix it */ -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" -#endif vfprintf(errors, fmt, ap); -#ifdef __clang__ -#pragma clang diagnostic pop -#endif va_end(ap); fputs("\n", errors); /* newline it */ } diff --git a/tests/libtest/lib518.c b/tests/libtest/lib518.c index 04e3b5b9993..2000412392f 100644 --- a/tests/libtest/lib518.c +++ b/tests/libtest/lib518.c @@ -99,30 +99,35 @@ static int fopen_works(void) return ret; } -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" +static void rlim2str(char *buf, size_t len, rlim_t val) +{ +#ifdef RLIM_INFINITY + if(val == RLIM_INFINITY) { + msnprintf(buf, len, "INFINITY"); + return; + } +#endif +#ifdef HAVE_LONGLONG + if(sizeof(rlim_t) > sizeof(long)) + msnprintf(buf, len, "%llu", (unsigned long long)val); + else #endif + { + if(sizeof(rlim_t) < sizeof(long)) + msnprintf(buf, len, "%u", (unsigned int)val); + else + msnprintf(buf, len, "%lu", (unsigned long)val); + } +} static int rlimit(int keep_open) { - int nitems, i; + rlim_t nitems, i; int *memchunk = NULL; - char *fmt; struct rlimit rl; char strbuff[256]; char strbuff1[81]; char strbuff2[81]; - char fmt_u[] = "%u"; - char fmt_lu[] = "%lu"; -#ifdef HAVE_LONGLONG - char fmt_llu[] = "%llu"; - - if(sizeof(rl.rlim_max) > sizeof(long)) - fmt = fmt_llu; - else -#endif - fmt = (sizeof(rl.rlim_max) < sizeof(long))?fmt_u:fmt_lu; /* get initial open file limits */ @@ -134,20 +139,10 @@ static int rlimit(int keep_open) /* show initial open file limits */ -#ifdef RLIM_INFINITY - if(rl.rlim_cur == RLIM_INFINITY) - strcpy(strbuff, "INFINITY"); - else -#endif - msnprintf(strbuff, sizeof(strbuff), fmt, rl.rlim_cur); + rlim2str(strbuff, sizeof(strbuff), rl.rlim_cur); fprintf(stderr, "initial soft limit: %s\n", strbuff); -#ifdef RLIM_INFINITY - if(rl.rlim_max == RLIM_INFINITY) - strcpy(strbuff, "INFINITY"); - else -#endif - msnprintf(strbuff, sizeof(strbuff), fmt, rl.rlim_max); + rlim2str(strbuff, sizeof(strbuff), rl.rlim_max); fprintf(stderr, "initial hard limit: %s\n", strbuff); /* show our constants */ @@ -200,20 +195,10 @@ static int rlimit(int keep_open) /* show current open file limits */ -#ifdef RLIM_INFINITY - if(rl.rlim_cur == RLIM_INFINITY) - strcpy(strbuff, "INFINITY"); - else -#endif - msnprintf(strbuff, sizeof(strbuff), fmt, rl.rlim_cur); + rlim2str(strbuff, sizeof(strbuff), rl.rlim_cur); fprintf(stderr, "current soft limit: %s\n", strbuff); -#ifdef RLIM_INFINITY - if(rl.rlim_max == RLIM_INFINITY) - strcpy(strbuff, "INFINITY"); - else -#endif - msnprintf(strbuff, sizeof(strbuff), fmt, rl.rlim_max); + rlim2str(strbuff, sizeof(strbuff), rl.rlim_max); fprintf(stderr, "current hard limit: %s\n", strbuff); } /* (rl.rlim_cur != rl.rlim_max) */ @@ -240,8 +225,8 @@ static int rlimit(int keep_open) (rl.rlim_cur != RLIM_INFINITY) && #endif (rl.rlim_cur <= num_open.rlim_cur)) { - msnprintf(strbuff2, sizeof(strbuff2), fmt, rl.rlim_cur); - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_cur); + rlim2str(strbuff2, sizeof(strbuff2), rl.rlim_cur); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_cur); msnprintf(strbuff, sizeof(strbuff), "fds needed %s > system limit %s", strbuff1, strbuff2); store_errmsg(strbuff, 0); @@ -263,8 +248,8 @@ static int rlimit(int keep_open) if(nitems > 0x7fff) nitems = 0x40000; do { - num_open.rlim_max = sizeof(*memchunk) * (size_t)nitems; - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + num_open.rlim_max = sizeof(*memchunk) * nitems; + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "allocating memchunk %s byte array\n", strbuff); memchunk = malloc(sizeof(*memchunk) * (size_t)nitems); if(!memchunk) { @@ -292,7 +277,7 @@ static int rlimit(int keep_open) /* verify that we won't overflow size_t in malloc() */ if((size_t)(num_open.rlim_max) > ((size_t)-1) / sizeof(*fd)) { - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_max); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_max); msnprintf(strbuff, sizeof(strbuff), "unable to allocate an array for %s " "file descriptors, would overflow size_t", strbuff1); store_errmsg(strbuff, 0); @@ -303,7 +288,7 @@ static int rlimit(int keep_open) /* allocate array for file descriptors */ - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "allocating array for %s file descriptors\n", strbuff); fd = malloc(sizeof(*fd) * (size_t)(num_open.rlim_max)); @@ -323,7 +308,7 @@ static int rlimit(int keep_open) num_open.rlim_cur++) fd[num_open.rlim_cur] = -1; - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "trying to open %s file descriptors\n", strbuff); /* open a dummy descriptor */ @@ -351,21 +336,21 @@ static int rlimit(int keep_open) fd[num_open.rlim_cur] = -1; - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_cur); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_cur); msnprintf(strbuff, sizeof(strbuff), "dup() attempt %s failed", strbuff1); fprintf(stderr, "%s\n", strbuff); - msnprintf(strbuff1, sizeof(strbuff), fmt, num_open.rlim_cur); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_cur); msnprintf(strbuff, sizeof(strbuff), "fds system limit seems close to %s", - strbuff1); + strbuff1); fprintf(stderr, "%s\n", strbuff); num_open.rlim_max = NUM_NEEDED; - msnprintf(strbuff2, sizeof(strbuff2), fmt, num_open.rlim_max); - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_cur); + rlim2str(strbuff2, sizeof(strbuff2), num_open.rlim_max); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_cur); msnprintf(strbuff, sizeof(strbuff), "fds needed %s > system limit %s", - strbuff2, strbuff1); + strbuff2, strbuff1); store_errmsg(strbuff, 0); fprintf(stderr, "%s\n", msgbuff); @@ -377,12 +362,10 @@ static int rlimit(int keep_open) fd = NULL; free(memchunk); return -9; - } - } - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "%s file descriptors open\n", strbuff); #if !defined(HAVE_POLL_FINE) && !defined(USE_WINSOCK) @@ -401,7 +384,7 @@ static int rlimit(int keep_open) num_open.rlim_cur = FD_SETSIZE - SAFETY_MARGIN; if(num_open.rlim_max > num_open.rlim_cur) { msnprintf(strbuff, sizeof(strbuff), "select limit is FD_SETSIZE %d", - FD_SETSIZE); + FD_SETSIZE); store_errmsg(strbuff, 0); fprintf(stderr, "%s\n", msgbuff); close_file_descriptors(); @@ -416,7 +399,7 @@ static int rlimit(int keep_open) if((fd[rl.rlim_cur] > 0) && ((unsigned int)fd[rl.rlim_cur] > num_open.rlim_cur)) { msnprintf(strbuff, sizeof(strbuff), "select limit is FD_SETSIZE %d", - FD_SETSIZE); + FD_SETSIZE); store_errmsg(strbuff, 0); fprintf(stderr, "%s\n", msgbuff); close_file_descriptors(); @@ -437,13 +420,11 @@ static int rlimit(int keep_open) */ if(!fopen_works()) { - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_max); - msnprintf(strbuff, sizeof(strbuff), - "fopen fails with %s fds open()", - strbuff1); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_max); + msnprintf(strbuff, sizeof(strbuff), "fopen fails with %s fds open", + strbuff1); fprintf(stderr, "%s\n", msgbuff); - msnprintf(strbuff, sizeof(strbuff), - "fopen fails with lots of fds open()"); + msnprintf(strbuff, sizeof(strbuff), "fopen fails with lots of fds open"); store_errmsg(strbuff, 0); close_file_descriptors(); free(memchunk); @@ -464,10 +445,6 @@ static int rlimit(int keep_open) return 0; } -#ifdef __clang__ -#pragma clang diagnostic pop -#endif - int test(char *URL) { CURLcode res; diff --git a/tests/libtest/lib537.c b/tests/libtest/lib537.c index 51d6d03456b..b83e3ce3119 100644 --- a/tests/libtest/lib537.c +++ b/tests/libtest/lib537.c @@ -59,8 +59,8 @@ static void store_errmsg(const char *msg, int err) if(!err) msnprintf(msgbuff, sizeof(msgbuff), "%s", msg); else - msnprintf(msgbuff, sizeof(msgbuff), "%s, errno %d, %s", msg, err, - strerror(err)); + msnprintf(msgbuff, sizeof(msgbuff), "%s, errno %d, %s", msg, + err, strerror(err)); } static void close_file_descriptors(void) @@ -99,30 +99,35 @@ static int fopen_works(void) return ret; } -#ifdef __clang__ -#pragma clang diagnostic push -#pragma clang diagnostic ignored "-Wformat-nonliteral" +static void rlim2str(char *buf, size_t len, rlim_t val) +{ +#ifdef RLIM_INFINITY + if(val == RLIM_INFINITY) { + msnprintf(buf, len, "INFINITY"); + return; + } +#endif +#ifdef HAVE_LONGLONG + if(sizeof(rlim_t) > sizeof(long)) + msnprintf(buf, len, "%llu", (unsigned long long)val); + else #endif + { + if(sizeof(rlim_t) < sizeof(long)) + msnprintf(buf, len, "%u", (unsigned int)val); + else + msnprintf(buf, len, "%lu", (unsigned long)val); + } +} static int rlimit(int keep_open) { int *tmpfd; rlim_t nitems, i; int *memchunk = NULL; - char *fmt; struct rlimit rl; char strbuff[256]; char strbuff1[81]; - char fmt_u[] = "%u"; - char fmt_lu[] = "%lu"; -#ifdef HAVE_LONGLONG - char fmt_llu[] = "%llu"; - - if(sizeof(rl.rlim_max) > sizeof(long)) - fmt = fmt_llu; - else -#endif - fmt = (sizeof(rl.rlim_max) < sizeof(long))?fmt_u:fmt_lu; /* get initial open file limits */ @@ -134,20 +139,10 @@ static int rlimit(int keep_open) /* show initial open file limits */ -#ifdef RLIM_INFINITY - if(rl.rlim_cur == RLIM_INFINITY) - strcpy(strbuff, "INFINITY"); - else -#endif - msnprintf(strbuff, sizeof(strbuff), fmt, rl.rlim_cur); + rlim2str(strbuff, sizeof(strbuff), rl.rlim_cur); fprintf(stderr, "initial soft limit: %s\n", strbuff); -#ifdef RLIM_INFINITY - if(rl.rlim_max == RLIM_INFINITY) - strcpy(strbuff, "INFINITY"); - else -#endif - msnprintf(strbuff, sizeof(strbuff), fmt, rl.rlim_max); + rlim2str(strbuff, sizeof(strbuff), rl.rlim_max); fprintf(stderr, "initial hard limit: %s\n", strbuff); /* @@ -163,7 +158,7 @@ static int rlimit(int keep_open) #ifdef OPEN_MAX if((rl.rlim_cur > 0) && - (rl.rlim_cur < OPEN_MAX)) { + (rl.rlim_cur < OPEN_MAX)) { fprintf(stderr, "raising soft limit up to OPEN_MAX\n"); rl.rlim_cur = OPEN_MAX; if(setrlimit(RLIMIT_NOFILE, &rl) != 0) { @@ -194,20 +189,10 @@ static int rlimit(int keep_open) /* show current open file limits */ -#ifdef RLIM_INFINITY - if(rl.rlim_cur == RLIM_INFINITY) - strcpy(strbuff, "INFINITY"); - else -#endif - msnprintf(strbuff, sizeof(strbuff), fmt, rl.rlim_cur); + rlim2str(strbuff, sizeof(strbuff), rl.rlim_cur); fprintf(stderr, "current soft limit: %s\n", strbuff); -#ifdef RLIM_INFINITY - if(rl.rlim_max == RLIM_INFINITY) - strcpy(strbuff, "INFINITY"); - else -#endif - msnprintf(strbuff, sizeof(strbuff), fmt, rl.rlim_max); + rlim2str(strbuff, sizeof(strbuff), rl.rlim_max); fprintf(stderr, "current hard limit: %s\n", strbuff); } /* (rl.rlim_cur != rl.rlim_max) */ @@ -237,7 +222,7 @@ static int rlimit(int keep_open) nitems = 0x40000; do { num_open.rlim_max = sizeof(*memchunk) * nitems; - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "allocating memchunk %s byte array\n", strbuff); memchunk = malloc(sizeof(*memchunk) * (size_t)nitems); if(!memchunk) { @@ -280,7 +265,7 @@ static int rlimit(int keep_open) /* verify that we won't overflow size_t in malloc() */ if((size_t)(num_open.rlim_max) > ((size_t)-1) / sizeof(*fd)) { - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_max); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_max); msnprintf(strbuff, sizeof(strbuff), "unable to allocate an array for %s " "file descriptors, would overflow size_t", strbuff1); store_errmsg(strbuff, 0); @@ -292,8 +277,9 @@ static int rlimit(int keep_open) /* allocate array for file descriptors */ do { - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "allocating array for %s file descriptors\n", strbuff); + fd = malloc(sizeof(*fd) * (size_t)(num_open.rlim_max)); if(!fd) { fprintf(stderr, "fd, malloc() failed\n"); @@ -316,7 +302,7 @@ static int rlimit(int keep_open) num_open.rlim_cur++) fd[num_open.rlim_cur] = -1; - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "trying to open %s file descriptors\n", strbuff); /* open a dummy descriptor */ @@ -344,11 +330,11 @@ static int rlimit(int keep_open) fd[num_open.rlim_cur] = -1; - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_cur); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_cur); msnprintf(strbuff, sizeof(strbuff), "dup() attempt %s failed", strbuff1); fprintf(stderr, "%s\n", strbuff); - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_cur); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_cur); msnprintf(strbuff, sizeof(strbuff), "fds system limit seems close to %s", strbuff1); fprintf(stderr, "%s\n", strbuff); @@ -356,7 +342,7 @@ static int rlimit(int keep_open) num_open.rlim_max = num_open.rlim_cur - SAFETY_MARGIN; num_open.rlim_cur -= num_open.rlim_max; - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_cur); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_cur); msnprintf(strbuff, sizeof(strbuff), "closing %s file descriptors", strbuff1); fprintf(stderr, "%s\n", strbuff); @@ -368,7 +354,7 @@ static int rlimit(int keep_open) fd[num_open.rlim_cur] = -1; } - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "shrinking array for %s file descriptors\n", strbuff); /* we don't care if we can't shrink it */ @@ -380,12 +366,10 @@ static int rlimit(int keep_open) } break; - } - } - msnprintf(strbuff, sizeof(strbuff), fmt, num_open.rlim_max); + rlim2str(strbuff, sizeof(strbuff), num_open.rlim_max); fprintf(stderr, "%s file descriptors open\n", strbuff); #if !defined(HAVE_POLL_FINE) && !defined(USE_WINSOCK) @@ -440,7 +424,7 @@ static int rlimit(int keep_open) */ if(!fopen_works()) { - msnprintf(strbuff1, sizeof(strbuff1), fmt, num_open.rlim_max); + rlim2str(strbuff1, sizeof(strbuff1), num_open.rlim_max); msnprintf(strbuff, sizeof(strbuff), "fopen fails with %s fds open", strbuff1); fprintf(stderr, "%s\n", msgbuff); @@ -465,10 +449,6 @@ static int rlimit(int keep_open) return 0; } -#ifdef __clang__ -#pragma clang diagnostic pop -#endif - int test(char *URL) { CURLcode res; From 2bfbb538d0a54d3142b0a4b0005334a8237b996a Mon Sep 17 00:00:00 2001 From: Patrick Monnerat Date: Mon, 29 Jan 2024 12:10:17 +0100 Subject: [PATCH 253/509] OS400: sync ILE/RPG binding Also do not force git CRLF line endings on *.cmd files for OS400. Closes #12815 --- packages/OS400/.gitattributes | 6 ++++++ packages/OS400/curl.inc.in | 18 ++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 packages/OS400/.gitattributes diff --git a/packages/OS400/.gitattributes b/packages/OS400/.gitattributes new file mode 100644 index 00000000000..e9b8201b5ec --- /dev/null +++ b/packages/OS400/.gitattributes @@ -0,0 +1,6 @@ +# Copyright (C) Daniel Stenberg, , et al. +# +# SPDX-License-Identifier: curl + +# OS400 .cmd files are not windows scripts. +*.cmd text eol=auto diff --git a/packages/OS400/curl.inc.in b/packages/OS400/curl.inc.in index d1254ce49de..b3a4e9efd4c 100644 --- a/packages/OS400/curl.inc.in +++ b/packages/OS400/curl.inc.in @@ -667,6 +667,8 @@ d c 98 d CURLE_UNRECOVERABLE_POLL... d c 99 + d CURLE_TOO_LARGE... + d c 100 * /if not defined(CURL_NO_OLDIES) d CURLE_URL_MALFORMAT_USER... @@ -1655,6 +1657,10 @@ d c 00321 d CURLOPT_QUICK_EXIT... d c 00322 + d CURLOPT_HAPROXY_CLIENT_IP... + d c 10323 + d CURLOPT_SERVER_RESPONSE_TIMEOUT_MS... + d c 00324 * /if not defined(CURL_NO_OLDIES) d CURLOPT_FILE c 10001 @@ -1890,6 +1896,12 @@ d c X'0010003D' d CURLINFO_CAPATH... CURLINFO_STRING + 62 d c X'0010003E' + d CURLINFO_XFER_ID... CURLINFO_OFF_T + 63 + d c X'0060003F' + d CURLINFO_CONN_ID... CURLINFO_OFF_T + 64 + d c X'00600040' + d CURLINFO_QUEUE_TIME_T... CURLINFO_OFF_T + 65 + d c X'00600041' * d CURLINFO_HTTP_CODE... Old ...RESPONSE_CODE d c X'00200002' @@ -2251,6 +2263,8 @@ d c 29 d CURLUE_LACKS_IDN... d c 30 + d CURLUE_TOO_LARGE... + d c 31 * d CURLUPart s 10i 0 based(######ptr######) Enum d CURLUPART_URL c 0 @@ -3062,6 +3076,10 @@ d sockfd value like(curl_socket_t) d sockp * value void * * + d curl_multi_get_handles... + d pr * extproc('curl_multi_get_handles') CURL ** + d multi_handle * value CURLM * + * d curl_url pr * extproc('curl_url') CURLU * * d curl_url_cleanup... From 011325ff29638bfaa498c1a930950437c4e7dd62 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 26 Jan 2024 16:59:33 +0100 Subject: [PATCH 254/509] lib: error out on multissl + http3 Since the QUIC/h3 code has no knowledge or handling of multissl it might bring unintended consequences if we allow it. configure, cmake and curl_setup.h all now reject this combination. Assisted-by: Viktor Szakats Assisted-by: Gisle Vanem Ref: #12806 Closes #12807 --- CMakeLists.txt | 4 ++++ configure.ac | 3 +++ lib/curl_setup.h | 5 +++++ 3 files changed, 12 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index 6c7bd56254b..1b5ea67c2af 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -720,6 +720,10 @@ if(USE_MSH3) list(APPEND CURL_LIBS ${MSH3_LIBRARIES}) endif() +if(CURL_WITH_MULTI_SSL AND (USE_NGTCP2 OR USE_QUICHE OR USE_MSH3)) + 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() diff --git a/configure.ac b/configure.ac index 0737db045f0..be66be9e9df 100644 --- a/configure.ac +++ b/configure.ac @@ -4691,6 +4691,9 @@ fi 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 diff --git a/lib/curl_setup.h b/lib/curl_setup.h index 91e35f58b4d..703e903fa8f 100644 --- a/lib/curl_setup.h +++ b/lib/curl_setup.h @@ -829,6 +829,11 @@ int getpwuid_r(uid_t uid, struct passwd *pwd, char *buf, #if (defined(USE_NGTCP2) && defined(USE_NGHTTP3)) || \ (defined(USE_OPENSSL_QUIC) && defined(USE_NGHTTP3)) || \ defined(USE_QUICHE) || defined(USE_MSH3) + +#ifdef CURL_WITH_MULTI_SSL +#error "Multi-SSL combined with QUIC is not supported" +#endif + #define ENABLE_QUIC #define USE_HTTP3 #endif From 3e57bc2a84887eb96b0f47ccbe39aa5624192b8b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 29 Jan 2024 22:39:33 +0100 Subject: [PATCH 255/509] cd2nroff: fix duplicate output issue Assisted-by: Jay Satiro Fixes https://github.com/curl/curl-www/issues/321 Closes #12818 --- scripts/cd2nroff | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/scripts/cd2nroff b/scripts/cd2nroff index bbc7969a395..e8c8235dd2d 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -337,14 +337,12 @@ sub single { return $errors; } -$f = $ARGV[0]; -if(defined($f)) { - while($f) { - $r = single($f); +if(@ARGV) { + for my $f (@ARGV) { + my $r = single($f); if($r) { exit $r; } - $f = shift @ARGV; } } else { From f1041adff4922da0c04665b153188b9e55a9fd6d Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Mon, 29 Jan 2024 18:57:10 -0500 Subject: [PATCH 256/509] cd2nroff: use perl 'strict' and 'warnings' - Use strict and warnings pragmas. - If open() fails then show the reason. - Set STDIN io layer :crlf so that input is properly read on Windows. - When STDIN is used as input, the filename $f is now set to "STDIN". Various error messages in single() use $f for the filename and this way it is not undefined when STDIN. Closes https://github.com/curl/curl/pull/12819 --- scripts/cd2nroff | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/scripts/cd2nroff b/scripts/cd2nroff index e8c8235dd2d..17a83b49cbb 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -30,12 +30,15 @@ Converts a curldown file to nroff (man page). =end comment =cut +use strict; +use warnings; + my $cd2nroff = "0.1"; # to keep check my $dir; my $extension; my $keepfilename; -while(1) { +while(@ARGV) { if($ARGV[0] eq "-d") { shift @ARGV; $dir = shift @ARGV; @@ -95,18 +98,29 @@ sub outseealso { sub single { my @seealso; + my $d; my ($f)=@_; - my $title; + my $copyright; + my $errors = 0; + my $fh; + my $line; + my $salist; my $section; my $source; + my $spdx; my $start = 0; - my $errors; - my $fh; - if($f) { - open($fh, "<:crlf", "$f") || return 1; + my $title; + + if(defined($f)) { + if(!open($fh, "<:crlf", "$f")) { + print STDERR "Failed to open $f : $!\n"; + return 1; + } } else { - $fh = STDIN; + $f = "STDIN"; + $fh = \*STDIN; + binmode($fh, ":crlf"); } while(<$fh>) { $line++; @@ -320,14 +334,23 @@ sub single { } } } - close($fh); + if($fh != \*STDIN) { + close($fh); + } push @desc, outseealso(@seealso); if($dir) { if($keepfilename) { $title = $f; $title =~ s/\.[^.]*$//; } - open(O, ">$dir/$title.$section$extension"); + my $outfile = "$dir/$title.$section"; + if(defined($extension)) { + $outfile .= $extension; + } + if(!open(O, ">", $outfile)) { + print STDERR "Failed to open $outfile : $!\n"; + return 1; + } print O @desc; close(O); } From 41961913695732b04e27721d820d83e5bd1b5ba2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 31 Jan 2024 08:02:47 +0100 Subject: [PATCH 257/509] THANKS: new contributors from 8.5.0 --- docs/THANKS | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/THANKS b/docs/THANKS index 8e7cbe4b492..eee2ec51a4d 100644 --- a/docs/THANKS +++ b/docs/THANKS @@ -207,6 +207,7 @@ Andy Stamp Andy Tsouladze Angus Mackay anio on github +annalee anon00000000 on github anshnd on github Anssi Kolehmainen @@ -291,6 +292,7 @@ Basuke Suzuki baumanj on github bdry on github beckenc on github +Ben Ben Boeckel Ben Darnell Ben Fritz @@ -406,11 +408,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 @@ -443,6 +447,7 @@ Cering on github Cesar Eduardo Barros Chad Monroe Chandrakant Bagul +Chara White Charles Cazabon Charles Kerr Charles Romestant @@ -467,6 +472,7 @@ Chris Maltby Chris Mumford Chris Paulson-Ellis Chris Roberts +Chris Sauer Chris Smowton Chris Talbot Chris Young @@ -683,6 +689,7 @@ Denis Laxalde Denis Ollier Dennis Clarke Dennis Felsing +dependabot[bot] Derek Higgins Derzsi Dániel Desmond O. Chang @@ -945,6 +952,7 @@ FuccDucc on github Fujii Hironori fullincome on github fundawang on github +Gabe Gabriel Corona Gabriel Kuri Gabriel Simmer @@ -1057,6 +1065,7 @@ Hannes Magnusson Hanno Böck Hanno Kranzhoff Hans Steegers +Hans-Christian Egtvedt Hans-Christian Noren Egtvedt Hans-Jurgen May Hao Wu @@ -1068,6 +1077,7 @@ Harry Sarson Harry Sintonen Harshal Pradhan Hauke Duden +Haydar Alaidrus Hayden Roche He Qin Heikki Korpela @@ -1086,6 +1096,7 @@ Henry Ludemann Henry Roeland Herve Amblard HexTheDragon +hgdagon on github Hide Ishikawa Hidemoto Nakada highmtworks on github @@ -1119,6 +1130,7 @@ Ian Lynagh Ian Spence Ian Turner Ian Wilkes +iAroc on github iconoclasthero icy17 on github Ignacio Vazquez-Abrams @@ -1157,6 +1169,7 @@ Ishan SinghLevett Ithubg on github Ivan Avdeev Ivan Tsybulin +ivanfywang IvanoG on github Ivo Bellin Salarin iz8mbw on github @@ -1216,6 +1229,7 @@ Jan Venekamp Jan Verbeek Jan-Piet Mens JanB on github +janko-js on github Janne Blomqvist Janne Johansson Jared Jennings @@ -1237,6 +1251,7 @@ Javier Navarro Javier Sixto Jay Austin Jay Dommaschk +Jay Wu Jayesh A Shah Jaz Fresh JazJas on github @@ -1291,6 +1306,7 @@ Jerry Krinock Jerry Wu Jes Badwal Jesper Jensen +Jess Lowe Jesse Chisholm Jesse Noller Jesse Tan @@ -1602,6 +1618,7 @@ Lawrence Gripper Lawrence Matthews Lawrence Wagerfield Leah Neukirchen +Lealem Amedie Leandro Coutinho Legoff Vincent Lehel Bernadt @@ -1625,6 +1642,7 @@ LigH-de on github lijian996 on github Lijo Antony lilongyan-huawei on github +Lin Sun Linas Vepstas Lindley French Ling Thio @@ -1741,6 +1759,7 @@ Mark Davies Mark Dodgson Mark Gaiser Mark Hamilton +Mark Huang Mark Incley Mark Itzcovitz Mark Karpeles @@ -1749,6 +1768,7 @@ Mark Nottingham Mark Roszko Mark Salisbury Mark Seuffert +Mark Sinkovics Mark Snelling Mark Swaanenburg Mark Tully @@ -1837,6 +1857,7 @@ Matthias Naegler Mattias Fornander Matus Uzak Maurice Barnum +Mauricio Scheffer Mauro Iorio Mauro Rappa Maurício Meneghini Fauth @@ -1960,6 +1981,7 @@ Mohamed Lrhazi Mohamed Osama Mohammad AlSaleh Mohammad Hasbini +Mohammadreza Hendiani Mohammed Naser Mohun Biswas momala454 on github @@ -2111,6 +2133,7 @@ Oskar Liljeblad Oskar Sigvardsson Oumph on github ovidiu-benea on github +Ozan Cansel P R Schaffner Pablo Busse Palo Markovic @@ -2263,6 +2286,7 @@ Prithvi MK privetryan on github Priyanka Shah ProceduralMan on github +promptfuzz_ on hackerone Pronyushkin Petr Przemysław Tomaszewski pszemus on github @@ -2332,6 +2356,7 @@ Renaud Lehoux Rene Bernhardt Rene Rebe Reuven Wachtfogel +RevaliQaQ on github Reza Arbab Rianov Viacheslav Ricardo Cadime @@ -2514,6 +2539,7 @@ Saul good Saurav Babu sayrer on github SBKarr on github +Scarlett McAllister Scott Bailey Scott Barrett Scott Cantor @@ -2559,6 +2585,7 @@ SerusDev on github Seshubabu Pasam Seth Mos Sevan Janiyan +sfan5 on github Sgharat on github Sh Diao Shachaf Ben-Kiki @@ -2708,6 +2735,7 @@ Taneli Vähäkangas Tanguy Fautre Taras Kushnir tarek112 on github +Tatsuhiko Miyagawa Tatsuhiro Tsujikawa tawmoto on github tbugfinder on github @@ -2720,6 +2748,7 @@ thanhchungbtc on github The Infinnovation team TheAssassin on github TheKnarf on github +Theo Theodore Dubois therealhirudo on github Thiago Suchorski @@ -2727,6 +2756,7 @@ tholin on github Thomas Bouzerar Thomas Braun Thomas Danielsson +Thomas Ferguson Thomas Gamper Thomas Glanzmann Thomas Guillem @@ -2964,6 +2994,7 @@ x2018 on github Xavier Bouchoux XhmikosR on github XhstormR on github +Xi Ruoyao Xiang Xiao Xiangbin Li xianghongai on github @@ -2975,6 +3006,7 @@ xtonik on github xwxbug on github Xì Gà Yaakov Selkowitz +Yadhu Krishna M Yair Lenga Yang Tse Yaobin Wen @@ -2982,10 +3014,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 @@ -3013,6 +3047,8 @@ Zachary Seguin Zdenek Pavlas Zekun Ni zelinchen on github +zengwei +zengwei2000 Zenju on github Zero King Zespre Schmidt From 5ce164e0e9290c96eb7d502173426c0a135ec008 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 31 Jan 2024 08:02:47 +0100 Subject: [PATCH 258/509] RELEASE-NOTES: synced curl 8.6.0 --- RELEASE-NOTES | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index b9a14f459a6..0bb5a8d43ff 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -24,6 +24,7 @@ This release includes the following bugfixes: o appveyor: switch to out-of-tree builds [29] o asyn-ares: with modern c-ares, use its default timeout [127] o build: delete unused `HAVE_{GSSHEIMDAL,GSSMIT,HEIMDAL}` [4] + o build: delete/replace clang warning pragmas [111] o build: enable missing OpenSSF-recommended warnings, with fixes [11] o build: fix `-Wconversion`/`-Wsign-conversion` warnings [26] o build: fix Windows ADDRESS_FAMILY detection [35] @@ -32,10 +33,10 @@ This release includes the following bugfixes: o cf-h1-proxy: no CURLOPT_USERAGENT in CONNECT with hyper [133] o cf-socket: show errno in tcpkeepalive error messages [120] o CI/distcheck: run full tests [31] - o CI: remove unnecessary OpenSSL 3 option `enable-tls1_3` [168] o cmake: add option to disable building docs o cmake: fix generation for system name iOS [53] o cmake: fix typo [5] + o cmake: freshen up docs/INSTALL.cmake [101] o cmake: prefill/cache `HAVE_STRUCT_SOCKADDR_STORAGE` [45] o cmake: rework options to enable curl and libcurl docs [161] o cmake: when USE_MANUAL=YES, build the curl.1 man page [113] @@ -61,7 +62,7 @@ This release includes the following bugfixes: o docs: clean up Protocols: for cmdline options [32] o docs: describe and highlight super cookies [80] o docs: do not start lines/sentences with So, But nor And [140] - o docs: install curl.1 with cmake as well [166] + o docs: install curl.1 with cmake [166] o docs: mention env vars not used by schannel [124] o doh: remove unused local variable [34] o examples: add four new examples [99] @@ -92,6 +93,7 @@ This release includes the following bugfixes: o http_proxy: a blank CURLOPT_USERAGENT should not be used in CONNECT [90] o krb5: add prototype to silence clang warnings on mvsnprintf() [119] o lib: add debug log outputs for CURLE_BAD_FUNCTION_ARGUMENT [62] + o lib: error out on multissl + http3 [13] o lib: fix variable undeclared error caused by `infof` changes [2] o lib: reduce use of strncpy [30] o lib: rename Curl_strndup to Curl_memdup0 to avoid misunderstanding [36] @@ -115,6 +117,7 @@ This release includes the following bugfixes: o openldap: fix STARTTLS [67] o openssl: re-match LibreSSL deinit with init [17] o openssl: when verifystatus fails, remove session id from cache [100] + o OS400: sync ILE/RPG binding [114] o pingpong: stop using the download buffer [159] o pop3: replace calloc + memcpy with memdup0 [60] o pytest: scorecard tracking CPU and RSS [157] @@ -198,7 +201,8 @@ advice from friends like these: Sergey Bronnikov, Sergey Markelov, sfan5 on github, Stefan Eissing, Tatsuhiko Miyagawa, Tatsuhiro Tsujikawa, Theo, Thomas Ferguson, Viktor Szakats, Xi Ruoyao, Yadhu Krishna M, Yedaya Katsman, Yifei Kong, - YX Hao, zengwei, zengwei2000, ウさん (65 contributors) + YX Hao, zengwei, zengwei2000, ウさん + (65 contributors) References to bug reports and discussions on issues: @@ -214,6 +218,7 @@ References to bug reports and discussions on issues: [10] = https://curl.se/bug/?i=12495 [11] = https://curl.se/bug/?i=12489 [12] = https://curl.se/bug/?i=12224 + [13] = https://curl.se/bug/?i=12807 [14] = https://curl.se/bug/?i=12534 [15] = https://curl.se/mail/archive-2023-12/0026.html [16] = https://curl.se/bug/?i=12524 @@ -301,6 +306,7 @@ References to bug reports and discussions on issues: [98] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=66184 [99] = https://curl.se/bug/?i=12671 [100] = https://curl.se/bug/?i=12760 + [101] = https://curl.se/bug/?i=12772 [102] = https://curl.se/bug/?i=12730 [103] = https://curl.se/bug/?i=12754 [104] = https://curl.se/mail/lib-2024-01/0049.html @@ -310,8 +316,10 @@ References to bug reports and discussions on issues: [108] = https://curl.se/bug/?i=12652 [109] = https://curl.se/bug/?i=12661 [110] = https://curl.se/bug/?i=12734 + [111] = https://curl.se/bug/?i=12812 [112] = https://curl.se/bug/?i=12808 [113] = https://curl.se/bug/?i=12742 + [114] = https://curl.se/bug/?i=12815 [115] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65839 [116] = https://curl.se/bug/?i=12727 [117] = https://curl.se/bug/?i=12720 @@ -355,4 +363,3 @@ References to bug reports and discussions on issues: [163] = https://curl.se/bug/?i=12768 [164] = https://curl.se/bug/?i=12764 [166] = https://curl.se/bug/?i=12759 - [168] = https://curl.se/bug/?i=12758 From 843800297fdfdc2715cf0296c5ab07ba3f406091 Mon Sep 17 00:00:00 2001 From: Boris Verkhovskiy Date: Wed, 31 Jan 2024 01:34:19 -0800 Subject: [PATCH 259/509] form-string.md: correct the example Closes #12822 --- docs/cmdline-opts/form-string.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cmdline-opts/form-string.md b/docs/cmdline-opts/form-string.md index d26c4714292..15475cc3315 100644 --- a/docs/cmdline-opts/form-string.md +++ b/docs/cmdline-opts/form-string.md @@ -11,7 +11,7 @@ Multi: append See-also: - form Example: - - --form-string "data" $URL + - --form-string "name=data" $URL --- # `--form-string` From 2f3e7a26bc1b7b43e63aa014018746b6dbb72092 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 1 Feb 2024 09:34:41 +0100 Subject: [PATCH 260/509] tool_operate: do not set CURLOPT_QUICK_EXIT in debug builds Since it allows (small) memory leaks that interfere with torture tests and regular memory-leak checks. Reported-by: Dan Fandrich Fixes #12834 Closes #12835 --- src/tool_operate.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/tool_operate.c b/src/tool_operate.c index ba811d77331..86936ba5943 100644 --- a/src/tool_operate.c +++ b/src/tool_operate.c @@ -1274,6 +1274,7 @@ static CURLcode single_transfer(struct GlobalConfig *global, if(result && (use_proto == proto_ipfs || use_proto == proto_ipns)) break; +#ifndef DEBUGBUILD /* On most modern OSes, exiting works thoroughly, we'll clean everything up via exit(), so don't bother with slow cleanups. Crappy ones might need to skip this. @@ -1282,6 +1283,7 @@ static CURLcode single_transfer(struct GlobalConfig *global, result = curl_easy_setopt(curl, CURLOPT_QUICK_EXIT, 1L); if(result) break; +#endif if(!config->tcp_nodelay) my_setopt(curl, CURLOPT_TCP_NODELAY, 0L); From e75a48d2c32d92b0321fbb09c25885a706077201 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 31 Jan 2024 12:14:34 +0100 Subject: [PATCH 261/509] ntml_wb: fix buffer type typo Closes #12825 --- lib/curl_ntlm_wb.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/curl_ntlm_wb.c b/lib/curl_ntlm_wb.c index 0c7892ab702..acb0093956b 100644 --- a/lib/curl_ntlm_wb.c +++ b/lib/curl_ntlm_wb.c @@ -266,7 +266,7 @@ static CURLcode ntlm_wb_response(struct Curl_easy *data, struct ntlmdata *ntlm, size_t len_in = strlen(input), len_out = 0; struct dynbuf b; char *ptr = NULL; - usigned char buf[1024] + unsigned char buf[1024]; Curl_dyn_init(&b, MAX_NTLM_WB_RESPONSE); while(len_in > 0) { From 8243ad6458544031a99a2f852c67138882bb363d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 1 Feb 2024 09:36:19 +0100 Subject: [PATCH 262/509] asyn-thread: use wakeup_close to close the read descriptor Reported-by: Dan Fandrich Ref: #12834 Closes #12836 --- lib/asyn-thread.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/asyn-thread.c b/lib/asyn-thread.c index d4d382add9f..5b9d5049fc8 100644 --- a/lib/asyn-thread.c +++ b/lib/asyn-thread.c @@ -581,7 +581,7 @@ static void destroy_async_data(struct Curl_async *async) * before the FD is invalidated to avoid EBADF on EPOLL_CTL_DEL */ Curl_multi_closed(data, sock_rd); - sclose(sock_rd); + wakeup_close(sock_rd); #endif } async->tdata = NULL; From 5b50bf0cf6ff8ba5e231847315aadd16e572ad41 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 1 Feb 2024 10:53:29 +0100 Subject: [PATCH 263/509] cmdline-docs/Makefile: avoid using a fixed temp file name By appending the pid number two different runs at the same time will not trample over the same file. Reported-by: Jon Rumsey Fixes #12829 Closes #12839 --- docs/cmdline-opts/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index e9b35ac0526..08d19a01522 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -38,7 +38,7 @@ GN_ = $(GN_0) all: $(MANPAGE) $(MANPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl - $(GEN)(rm -f $(MANPAGE) && cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES) > $(builddir)/manpage.tmp && mv $(builddir)/manpage.tmp $(MANPAGE)) + $(GEN)(rm -f $(MANPAGE) && cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES) > $(builddir)/manpage.tmp.$$$$ && mv $(builddir)/manpage.tmp.$$$$ $(MANPAGE)) listhelp: ./gen.pl listhelp $(DPAGES) > $(top_builddir)/src/tool_listhelp.c From 26f79419eeb22b11cc2e305dc3fa92804b692a5b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 1 Feb 2024 14:47:09 +0100 Subject: [PATCH 264/509] RELEASE-NOTES: synced and bump to 8.6.1 for now --- RELEASE-NOTES | 352 ++--------------------------------------- include/curl/curlver.h | 6 +- 2 files changed, 18 insertions(+), 340 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 0bb5a8d43ff..f7bd00460be 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -1,6 +1,6 @@ -curl and libcurl 8.6.0 +curl and libcurl 8.6.1 - Public curl releases: 254 + Public curl releases: 255 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 @@ -8,171 +8,15 @@ curl and libcurl 8.6.0 This release includes the following changes: - o add CURLE_TOO_LARGE [48] - o add CURLINFO_QUEUE_TIME_T [76] - o add CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add [39] - o asyn-thread: use GetAddrInfoExW on >= Windows 8 [55] - o configure: make libpsl detection failure cause error [109] - o docs/cmdline: change to .md for cmdline docs [77] - o docs: introduce "curldown" for libcurl man page format [102] - o runtests: support -gl. Like -g but for lldb. [47] This release includes the following bugfixes: - o altsvc: free 'as' when returning error [23] - o appveyor: replace PowerShell with bash + parallel autotools [54] - o appveyor: switch to out-of-tree builds [29] - o asyn-ares: with modern c-ares, use its default timeout [127] - o build: delete unused `HAVE_{GSSHEIMDAL,GSSMIT,HEIMDAL}` [4] - o build: delete/replace clang warning pragmas [111] - o build: enable missing OpenSSF-recommended warnings, with fixes [11] - o build: fix `-Wconversion`/`-Wsign-conversion` warnings [26] - o build: fix Windows ADDRESS_FAMILY detection [35] - o build: more `-Wformat` fixes [40] - o build: remove redundant `CURL_PULL_*` settings [8] - o cf-h1-proxy: no CURLOPT_USERAGENT in CONNECT with hyper [133] - o cf-socket: show errno in tcpkeepalive error messages [120] - o CI/distcheck: run full tests [31] - o cmake: add option to disable building docs - o cmake: fix generation for system name iOS [53] - o cmake: fix typo [5] - o cmake: freshen up docs/INSTALL.cmake [101] - o cmake: prefill/cache `HAVE_STRUCT_SOCKADDR_STORAGE` [45] - o cmake: rework options to enable curl and libcurl docs [161] - o cmake: when USE_MANUAL=YES, build the curl.1 man page [113] - o cmdline-opts/write-out.d: remove spurious double quotes - o cmdline-opts: update availability for the *-ca-native options [66] - o cmdline/gen: fix the sorting of the man page options [33] - o configure: add libngtcp2_crypto_boringssl detection [155] - o configure: fix no default int compile error in ipv6 detection [69] - o configure: when enabling QUIC, check that TLS supports QUIC [87] - o connect: remove margin from eyeballer alloc [79] - o content_encoding: change return code to typedef'ed enum [94] - o cookie.d: document use of empty string to enable cookie engine [106] - o cookie: avoid fopen with empty file name [24] - o curl.h: CURLOPT_DNS_SERVERS is only available with c-ares [131] - o curl: show ipfs and ipns as supported "protocols" [15] - o curl_easy_getinfo.3: remove the wrong time value count [116] - o curl_multi_fdset.3: remove mention of null pointer support [134] - o CURLINFO_REFERER.3: clarify that it is the *request* header [70] - o CURLOPT_AUTOREFERER.3: mention CURLINFO_REFERER - o CURLOPT_POSTFIELDS.3: fix incorrect C string escape in example [27] - o CURLOPT_SSH_*_KEYFILE: clarify [57] - o dist: add tests/errorcodes.pl to the tarball [6] - o docs: clean up Protocols: for cmdline options [32] - o docs: describe and highlight super cookies [80] - o docs: do not start lines/sentences with So, But nor And [140] - o docs: install curl.1 with cmake [166] - o docs: mention env vars not used by schannel [124] - o doh: remove unused local variable [34] - o examples: add four new examples [99] - o file+ftp: use stack buffers instead of data->state.buffer [138] - o ftp: handle the PORT parsing without allocation [44] - o ftp: use dynbuf to store entrypath [83] - o ftp: use memdup0 to store the OS from a SYST 215 response [82] - o ftpserver.pl: send 213 SIZE response without spurious newline - o gen.pl: support ## for doing .IP in table-like lists [105] - o gen: do italics/bold for a range of letters, not just single word [78] - o GHA: add a job scanning for "bad words" in markdown [164] - o GHA: bump ngtcp2, gnutls, mod_h2, quiche [158] - o gnutls: fix build with --disable-verbose [3] - o haproxy-clientip.d: document the arg [68] - o headers: make sure the trailing newline is not stored [97] - o headers: remove assert from Curl_headers_push [115] - o hostip: return error immediately when Curl_ip2addr() fails [19] - o hsts: remove assert for zero length domain [96] - o http2: improved on_stream_close/data_done handling [49] - o http3/quiche: fix result code on a stream reset [91] - o http3: initial support for OpenSSL 3.2 QUIC stack [110] - o http: adjust_pollset fix [85] - o http: check for "Host:" case insensitively [154] - o http: fix off-by-one error in request method length check [14] - o http: only act on 101 responses when they are HTTP/1.1 [98] - o http: remove comment reference to a removed solution [156] - o http: use stack scratch buffer [150] - o http_proxy: a blank CURLOPT_USERAGENT should not be used in CONNECT [90] - o krb5: add prototype to silence clang warnings on mvsnprintf() [119] - o lib: add debug log outputs for CURLE_BAD_FUNCTION_ARGUMENT [62] - o lib: error out on multissl + http3 [13] - o lib: fix variable undeclared error caused by `infof` changes [2] - o lib: reduce use of strncpy [30] - o lib: rename Curl_strndup to Curl_memdup0 to avoid misunderstanding [36] - o lib: replace readwrite with write_resp [137] - o lib: strndup/memdup instead of malloc, memcpy and null-terminate [42] - o libssh2: use `libssh2_session_callback_set2()` with v1.11.1 [103] - o libssh: improve the deprecation warning dismissal [20] - o libssh: supress warnings without version check [18] - o Makefile.am: fix the MSVC project generation [22] - o Makefile.mk: drop Windows support [12] - o mbedtls: fix `-Wnull-dereference` and `-Wredundant-decls` [117] - o mbedtls: free the entropy when threaded [46] - o mime: use memdup0 instead of malloc + memcpy [63] - o mksymbolsmanpage.pl: provide references to where the symbol is used - o mprintf: overhaul and bugfixes [52] - o mqtt: use stack scratch buffer for recv+publish [148] - o multi: remove total timer reset in file_do() while fetching file:// [89] - o ngtcp2: put h3 at the front of alpn [58] - o ntlm_wb: do not use data->state.buffer any longer [151] - o openldap: fix an LDAP crash [75] - o openldap: fix STARTTLS [67] - o openssl: re-match LibreSSL deinit with init [17] - o openssl: when verifystatus fails, remove session id from cache [100] - o OS400: sync ILE/RPG binding [114] - o pingpong: stop using the download buffer [159] - o pop3: replace calloc + memcpy with memdup0 [60] - o pytest: scorecard tracking CPU and RSS [157] - o quiche: return CURLE_HTTP3 on send to invalid stream [65] - o readwrite_data: loop less [21] - o Revert "urldata: move async resolver state from easy handle to connectdata" [16] - o rtsp: deal with borked server responses [129] - o runtests: for mode="text" on , fix newlines on both parts [64] - o sasl: make login option string override http auth [142] - o schannel: fix `-Warith-conversion` gcc 13 warning [28] - o sectransp: do verify_cert without memdup for blobs [93] - o sectransp_ make TLSCipherNameForNumber() available in non-verbose config [1] - o sendf: fix compiler warning with CURL_DISABLE_HEADERS_API [38] - o setopt: clear mimepost when formp is freed [92] - o setopt: use memdup0 when cloning COPYPOSTFIELDS [107] - o socks: fix generic output string to say SOCKS instead of SOCKS4 [144] - o socks: use own buffer instead of data->state.buffer [143] - o ssh: fix namespace of two local macros [51] - o ssh: use stack scratch buffer for seeks [146] - o strerror: repair get_winsock_error() [56] - o system.h: sync mingw `CURL_TYPEOF_CURL_SOCKLEN_T` with other compilers [9] - o system_win32: fix a function pointer assignment warning [71] - o telnet: use dynbuf instad of malloc for escape buffer [108] - o telnet: use stack scratch buffer for do [149] - o tests/server: delete workaround for old-mingw [25] - o tests: avoid int/size_t conversion size/sign warnings [163] - o tests: respect $TMPDIR when creating unix domain sockets [50] - o tool: make parser reject blank arguments if not supported [86] - o tool: prepend output_dir in header callback [95] - o tool_getparam: bsearch cmdline options [74] - o tool_getparam: do not try to expand without an argument [59] - o tool_getparam: stop supporting `@filename` style for --cookie [121] - o tool_listhelp: regenerate after recent .d updates [61] - o tool_operate: make --remove-on-error only remove "real" files [125] - o tool_operate: stop setting the file comment on Amiga [128] - o transfer: adjust_pollset improvements [81] - o transfer: fix upload rate limiting, add test cases [37] - o transfer: make the select_bits_paused condition check both directions [104] - o transfer: remove warning: Value stored to 'blen' is never read [136] - o url: don't set default CA paths for Secure Transport backend [126] - o url: for disabled protocols, mention if found in redirect [7] - o urlapi: remove assert [162] - o verify-examples.pl: fail verification on unescaped backslash [72] - o version: show only the libpsl version, not its dependencies [130] - o vquic: extract TLS setup into own source [88] - o vtls: fix missing multissl version info [73] - o vtls: receive max buffer [139] - o vtls: remove the Curl_cft_ssl_proxy object if CURL_DISABLE_PROXY [41] - o websockets: check for negative payload lengths [123] - o websockets: refactor decode chain [122] - o windows: delete redundant headers [43] - o windows: simplify detecting and using system headers [10] - o wolfssl: load certificate *chain* for PEM client certs [84] - o x509asn1: remove code for WANT_VERIFYHOST [132] - o x509asn1: switch from malloc to dynbuf [112] + o cmdline-docs/Makefile: avoid using a fixed temp file name [5] + o asyn-thread: use wakeup_close to close the read descriptor [1] + o ntml_wb: fix buffer type typo [2] + o tool_operate: do not set CURLOPT_QUICK_EXIT in debug builds [3] + o form-string.md: correct the example [4] + --- new entries are listed above this --- This release includes the following known bugs: @@ -187,179 +31,13 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - Andy Alt, annalee, Baruch Siach, Ben, Boris Verkhovskiy, Brad Harder, - bubbleguuum on github, Cajus Pollmeier, calvin2021y on github, Chara White, - Chris Sauer, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, - dependabot[bot], Dmitry Karpov, Gabe, Geeknik Labs, Gisle Vanem, - Graham Campbell, Hans-Christian Egtvedt, Harry Sintonen, Haydar Alaidrus, - hgdagon on github, Hiroki Kurosawa, iAroc on github, ivanfywang, - janko-js on github, Jay Wu, Jess Lowe, Karthikdasari0423 on github, - Lealem Amedie, Lin Sun, Marcel Raad, Mark Huang, Mark Sinkovics, - Mauricio Scheffer, Michał Antoniak, Mike Hommey, Mohammadreza Hendiani, - Ozan Cansel, Patrick Monnerat, Pavel Pavlov, promptfuzz_ on hackerone, - Ray Satiro, RevaliQaQ on github, Richard Levitte, Scarlett McAllister, - Sergey Bronnikov, Sergey Markelov, sfan5 on github, Stefan Eissing, - Tatsuhiko Miyagawa, Tatsuhiro Tsujikawa, Theo, Thomas Ferguson, - Viktor Szakats, Xi Ruoyao, Yadhu Krishna M, Yedaya Katsman, Yifei Kong, - YX Hao, zengwei, zengwei2000, ウさん - (65 contributors) + Boris Verkhovskiy, Dan Fandrich, Daniel Stenberg, Jon Rumsey, Stefan Eissing + (5 contributors) References to bug reports and discussions on issues: - [1] = https://curl.se/bug/?i=12474 - [2] = https://curl.se/bug/?i=12470 - [3] = https://curl.se/bug/?i=12505 - [4] = https://curl.se/bug/?i=12506 - [5] = https://curl.se/bug/?i=12464 - [6] = https://curl.se/bug/?i=12462 - [7] = https://curl.se/bug/?i=12466 - [8] = https://curl.se/bug/?i=12502 - [9] = https://curl.se/bug/?i=12501 - [10] = https://curl.se/bug/?i=12495 - [11] = https://curl.se/bug/?i=12489 - [12] = https://curl.se/bug/?i=12224 - [13] = https://curl.se/bug/?i=12807 - [14] = https://curl.se/bug/?i=12534 - [15] = https://curl.se/mail/archive-2023-12/0026.html - [16] = https://curl.se/bug/?i=12524 - [17] = https://curl.se/bug/?i=12525 - [18] = https://curl.se/bug/?i=12523 - [19] = https://curl.se/bug/?i=12522 - [20] = https://curl.se/bug/?i=12519 - [21] = https://curl.se/bug/?i=12504 - [22] = https://curl.se/bug/?i=12564 - [23] = https://curl.se/bug/?i=12570 - [24] = https://curl.se/bug/?i=12514 - [25] = https://curl.se/bug/?i=12510 - [26] = https://curl.se/bug/?i=12557 - [27] = https://curl.se/bug/?i=12588 - [28] = https://curl.se/bug/?i=12616 - [29] = https://curl.se/bug/?i=12550 - [30] = https://curl.se/bug/?i=12499 - [31] = https://curl.se/bug/?i=12503 - [32] = https://curl.se/bug/?i=12496 - [33] = https://curl.se/mail/archive-2023-12/0014.html - [34] = https://curl.se/bug/?i=12491 - [35] = https://curl.se/bug/?i=12441 - [36] = https://curl.se/bug/?i=12490 - [37] = https://curl.se/bug/?i=12559 - [38] = https://curl.se/bug/?i=12485 - [39] = https://curl.se/bug/?i=12369 - [40] = https://curl.se/bug/?i=12540 - [41] = https://curl.se/bug/?i=12459 - [42] = https://curl.se/bug/?i=12453 - [43] = https://curl.se/bug/?i=12539 - [44] = https://curl.se/bug/?i=12456 - [45] = https://curl.se/bug/?i=12537 - [46] = https://curl.se/bug/?i=12584 - [47] = https://curl.se/bug/?i=12547 - [48] = https://curl.se/bug/?i=12269 - [49] = https://curl.se/bug/?i=10936 - [50] = https://curl.se/bug/?i=12545 - [51] = https://curl.se/bug/?i=12544 - [52] = https://curl.se/bug/?i=12561 - [53] = https://curl.se/bug/?i=12515 - [54] = https://curl.se/bug/?i=12560 - [55] = https://curl.se/bug/?i=12481 - [56] = https://curl.se/bug/?i=12578 - [57] = https://curl.se/bug/?i=12554 - [58] = https://curl.se/bug/?i=12576 - [59] = https://curl.se/bug/?i=12565 - [60] = https://curl.se/bug/?i=12650 - [61] = https://curl.se/bug/?i=12612 - [62] = https://curl.se/bug/?i=12658 - [63] = https://curl.se/bug/?i=12649 - [64] = https://curl.se/bug/?i=12612 - [65] = https://curl.se/bug/?i=12590 - [66] = https://curl.se/bug/?i=12613 - [67] = https://curl.se/bug/?i=12610 - [68] = https://curl.se/bug/?i=12611 - [69] = https://curl.se/bug/?i=12607 - [70] = https://curl.se/bug/?i=12605 - [71] = https://curl.se/bug/?i=12581 - [72] = https://curl.se/bug/?i=12589 - [73] = https://curl.se/bug/?i=12599 - [74] = https://curl.se/bug/?i=12631 - [75] = https://curl.se/bug/?i=12593 - [76] = https://curl.se/bug/?i=12368 - [77] = https://curl.se/bug/?i=12751 - [78] = https://curl.se/bug/?i=12689 - [79] = https://curl.se/bug/?i=12647 - [80] = https://curl.se/bug/?i=12687 - [81] = https://curl.se/bug/?i=12640 - [82] = https://curl.se/bug/?i=12639 - [83] = https://curl.se/bug/?i=12638 - [84] = https://curl.se/bug/?i=12634 - [85] = https://curl.se/bug/?i=12632 - [86] = https://curl.se/bug/?i=12620 - [87] = https://curl.se/bug/?i=12683 - [88] = https://curl.se/bug/?i=12678 - [89] = https://curl.se/bug/?i=12682 - [90] = https://curl.se/bug/?i=12680 - [91] = https://curl.se/bug/?i=12629 - [92] = https://curl.se/bug/?i=12608 - [93] = https://curl.se/bug/?i=12679 - [94] = https://curl.se/bug/?i=12618 - [95] = https://curl.se/bug/?i=12614 - [96] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65661 - [97] = https://curl.se/mail/lib-2024-01/0019.html - [98] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=66184 - [99] = https://curl.se/bug/?i=12671 - [100] = https://curl.se/bug/?i=12760 - [101] = https://curl.se/bug/?i=12772 - [102] = https://curl.se/bug/?i=12730 - [103] = https://curl.se/bug/?i=12754 - [104] = https://curl.se/mail/lib-2024-01/0049.html - [105] = https://curl.se/bug/?i=12667 - [106] = https://curl.se/bug/?i=12643 - [107] = https://curl.se/bug/?i=12651 - [108] = https://curl.se/bug/?i=12652 - [109] = https://curl.se/bug/?i=12661 - [110] = https://curl.se/bug/?i=12734 - [111] = https://curl.se/bug/?i=12812 - [112] = https://curl.se/bug/?i=12808 - [113] = https://curl.se/bug/?i=12742 - [114] = https://curl.se/bug/?i=12815 - [115] = https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=65839 - [116] = https://curl.se/bug/?i=12727 - [117] = https://curl.se/bug/?i=12720 - [119] = https://curl.se/bug/?i=12803 - [120] = https://curl.se/bug/?i=12726 - [121] = https://curl.se/bug/?i=12645 - [122] = https://curl.se/bug/?i=12713 - [123] = https://curl.se/bug/?i=12707 - [124] = https://curl.se/bug/?i=12711 - [125] = https://curl.se/bug/?i=12710 - [126] = https://curl.se/bug/?i=12704 - [127] = https://curl.se/bug/?i=12703 - [128] = https://curl.se/bug/?i=12709 - [129] = https://curl.se/bug/?i=12701 - [130] = https://curl.se/bug/?i=12700 - [131] = https://curl.se/bug/?i=12695 - [132] = https://curl.se/bug/?i=12804 - [133] = https://curl.se/bug/?i=12697 - [134] = https://curl.se/bug/?i=12691 - [136] = https://curl.se/bug/?i=12693 - [137] = https://curl.se/bug/?i=12480 - [138] = https://curl.se/bug/?i=12789 - [139] = https://curl.se/bug/?i=12801 - [140] = https://curl.se/bug/?i=12802 - [142] = https://curl.se/bug/?i=10259 - [143] = https://curl.se/bug/?i=12788 - [144] = https://curl.se/bug/?i=12797 - [146] = https://curl.se/bug/?i=12794 - [148] = https://curl.se/bug/?i=12792 - [149] = https://curl.se/bug/?i=12793 - [150] = https://curl.se/bug/?i=12791 - [151] = https://curl.se/bug/?i=12787 - [154] = https://curl.se/bug/?i=12784 - [155] = https://curl.se/bug/?i=12724 - [156] = https://curl.se/bug/?i=12785 - [157] = https://curl.se/bug/?i=12765 - [158] = https://curl.se/bug/?i=12778 - [159] = https://curl.se/bug/?i=12757 - [161] = https://curl.se/bug/?i=12773 - [162] = https://curl.se/bug/?i=12775 - [163] = https://curl.se/bug/?i=12768 - [164] = https://curl.se/bug/?i=12764 - [166] = https://curl.se/bug/?i=12759 + [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 diff --git a/include/curl/curlver.h b/include/curl/curlver.h index 316f39c4ec6..ed78adca570 100644 --- a/include/curl/curlver.h +++ b/include/curl/curlver.h @@ -32,13 +32,13 @@ /* This is the version number of the libcurl package from which this header file origins: */ -#define LIBCURL_VERSION "8.6.0-DEV" +#define LIBCURL_VERSION "8.6.1-DEV" /* The numeric version number is also available "in parts" by using these defines: */ #define LIBCURL_VERSION_MAJOR 8 #define LIBCURL_VERSION_MINOR 6 -#define LIBCURL_VERSION_PATCH 0 +#define LIBCURL_VERSION_PATCH 1 /* This is the numeric version of the libcurl version number, meant for easier parsing and comparisons by programs. The LIBCURL_VERSION_NUM define will @@ -59,7 +59,7 @@ CURL_VERSION_BITS() macro since curl's own configure script greps for it and needs it to contain the full number. */ -#define LIBCURL_VERSION_NUM 0x080600 +#define LIBCURL_VERSION_NUM 0x080601 /* * This is the date and time when the full source package was created. The From a911f4ffe66b42b4bbb4fae0e6b79484cbe80071 Mon Sep 17 00:00:00 2001 From: Jan Macku Date: Thu, 1 Feb 2024 14:18:12 +0100 Subject: [PATCH 265/509] docs: remove `mk-ca-bundle.1` from `man_MANS` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It was accidentally added in https://github.com/curl/curl/pull/12730 Co-authored-by: Lukáš Zaoral Signed-off-by: Jan Macku Follow-up to eefcc1bda4bccd800f5a56a0fe17a2f44a96e88b Closes #12843 --- docs/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index fbe94c40e5f..94cb8bc1d87 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -26,7 +26,7 @@ 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 mk-ca-bundle.1 +man_MANS = $(abs_builddir)/curl.1 noinst_man_MANS = curl.1 mk-ca-bundle.1 dist_man_MANS = curl-config.1 CURLPAGES = curl-config.md mk-ca-bundle.md From 627c8c598f2115deea7b3c38b56b0c42180f6714 Mon Sep 17 00:00:00 2001 From: Patrick Monnerat Date: Wed, 31 Jan 2024 14:04:41 +0100 Subject: [PATCH 266/509] OS400: avoid using awk in the build scripts Awk is a PASE program and its use may cause a failure depending on the CCSID of the calling script (IBM bug?). For this reason, revert to an sed-only solution to extract the exported symbols from the header files. Closes #12826 --- packages/OS400/make-lib.sh | 35 +++++++++++++++-------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/packages/OS400/make-lib.sh b/packages/OS400/make-lib.sh index 860cb5d76da..8179d816d57 100755 --- a/packages/OS400/make-lib.sh +++ b/packages/OS400/make-lib.sh @@ -98,26 +98,21 @@ fi # Gather the list of symbols to export. -# First use awk to pull all CURL_EXTERN function prototypes from -# the header files, pass through to sed to strip CURL_DEPRECATED(..) -# and CURL_TEMP_PRINTF(..) then back to awk to pull the string -# immediately to the left of a bracket stripping any spaces or *'s. - -EXPORTS=`awk '/^CURL_EXTERN/,/;/' \ - "${TOPDIR}"/include/curl/*.h \ - "${SCRIPTDIR}/ccsidcurl.h" | - sed 's/ CURL_DEPRECATED(.*)//g;s/ CURL_TEMP_PRINTF(.*)//g' | - awk '{br=index($0,"("); \ - if (br) { \ - for(c=br-1; ;c--) { \ - if (c==1) { \ - print substr($0,c,br-1); break \ - } else if (match(substr($0, c, br-c), "[ *]") != 0) { \ - print substr($0, c+1, br-c-1); break \ - } \ - } \ - } \ - }'` +# - Unfold lines from the header files so that they contain a semicolon. +# - Keep only CURL_EXTERN definitions. +# - Remove the CURL_DEPRECATED and CURL_TEMP_PRINTF macro calls. +# - Drop the parenthesized function arguments and what follows. +# - Keep the trailing function name only. + +EXPORTS=`cat "${TOPDIR}"/include/curl/*.h "${SCRIPTDIR}/ccsidcurl.h" | + sed -e 'H;s/.*//;x;s/\n//;s/.*/& /' \ + -e '/^CURL_EXTERN[[:space:]]/!d' \ + -e '/\;/!{x;d;}' \ + -e 's/ CURL_DEPRECATED([^)]*)//g' \ + -e 's/ CURL_TEMP_PRINTF([^)]*)//g' \ + -e 's/[[:space:]]*(.*$//' \ + -e 's/^.*[^A-Za-z0-9_]\([A-Za-z0-9_]*\)$/\1/'` + # Create the service program exportation file in DB2 member if needed. From 10491957e3d97dc298ffa1674b791ab69df62860 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 1 Feb 2024 11:28:22 +0100 Subject: [PATCH 267/509] ftp: treat a 226 arriving before data as a signal to read data For active mode transfers. Due to some interesting timing, curl can sometimes get the 226 (transfer complete) over the control channel first, before the data connection signals readability. If this happens, use that as a signal to check the data connection. Additionally, set the socket filter in listen mode *before* the PORT/EPRT command is issued, to reduce the risk that the little time gap could interfere. This issue never reproduced for me on Debian and takes several hundred rounds for me to trigger on my mac. Reported-by: Stefan Eissing Fixes #12823 Closes #12841 --- lib/ftp.c | 51 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 13 deletions(-) diff --git a/lib/ftp.c b/lib/ftp.c index f62108234f6..9c0f6fb1770 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -85,6 +85,14 @@ #define INET_ADDRSTRLEN 16 #endif +/* macro to check for a three-digit ftp status code at the start of the + given string */ +#define STATUSCODE(line) (ISDIGIT(line[0]) && ISDIGIT(line[1]) && \ + ISDIGIT(line[2])) + +/* macro to check for the last line in an FTP server response */ +#define LASTLINE(line) (STATUSCODE(line) && (' ' == line[3])) + #ifdef CURL_DISABLE_VERBOSE_STRINGS #define ftp_pasv_verbose(a,b,c,d) Curl_nop_stmt #endif @@ -412,8 +420,32 @@ static CURLcode ReceivedServerConnect(struct Curl_easy *data, bool *received) } if(response) { infof(data, "Ctrl conn has data while waiting for data conn"); + if(pp->overflow > 3) { + char *r = Curl_dyn_ptr(&pp->recvbuf); + + DEBUGASSERT((pp->overflow + pp->nfinal) <= + Curl_dyn_len(&pp->recvbuf)); + /* move over the most recently handled response line */ + r += pp->nfinal; + + if(LASTLINE(r)) { + int status = curlx_sltosi(strtol(r, NULL, 10)); + if(status == 226) { + /* funny timing situation where we get the final message on the + control connection before traffic on the data connection has been + noticed. Leave the 226 in there and use this as a trigger to read + the data socket. */ + infof(data, "Got 226 before data activity"); + *received = TRUE; + return CURLE_OK; + } + } + } + (void)Curl_GetFTPResponse(data, &nread, &ftpcode); + infof(data, "FTP code: %03d", ftpcode); + if(ftpcode/100 > 3) return CURLE_FTP_ACCEPT_FAILED; @@ -525,14 +557,6 @@ static CURLcode AllowServerConnect(struct Curl_easy *data, bool *connected) return result; } -/* macro to check for a three-digit ftp status code at the start of the - given string */ -#define STATUSCODE(line) (ISDIGIT(line[0]) && ISDIGIT(line[1]) && \ - ISDIGIT(line[2])) - -/* macro to check for the last line in an FTP server response */ -#define LASTLINE(line) (STATUSCODE(line) && (' ' == line[3])) - static bool ftp_endofresp(struct Curl_easy *data, struct connectdata *conn, char *line, size_t len, int *code) { @@ -1179,6 +1203,12 @@ static CURLcode ftp_state_use_port(struct Curl_easy *data, conn->bits.ftp_use_eprt = TRUE; #endif + /* Replace any filter on SECONDARY with one listening on this socket */ + result = Curl_conn_tcp_listen_set(data, conn, SECONDARYSOCKET, &portsock); + if(result) + goto out; + portsock = CURL_SOCKET_BAD; /* now held in filter */ + for(; fcmd != DONE; fcmd++) { if(!conn->bits.ftp_use_eprt && (EPRT == fcmd)) @@ -1252,11 +1282,6 @@ static CURLcode ftp_state_use_port(struct Curl_easy *data, /* store which command was sent */ ftpc->count1 = fcmd; - /* Replace any filter on SECONDARY with one listening on this socket */ - result = Curl_conn_tcp_listen_set(data, conn, SECONDARYSOCKET, &portsock); - if(result) - goto out; - portsock = CURL_SOCKET_BAD; /* now held in filter */ ftp_state(data, FTP_PORT); out: From b8c003832d730bb2f4b9de4204675ca5d9f7a903 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 1 Feb 2024 13:23:12 +0100 Subject: [PATCH 268/509] sendf: ignore response body to HEAD and mark the stream for close, but return OK since the response this far was ok - if headers were received. Partly because this is what curl has done traditionally. Test 499 verifies. Updates test 689. Reported-by: Sergey Bronnikov Bug: https://curl.se/mail/lib-2024-02/0000.html Closes #12842 --- lib/sendf.c | 3 ++ tests/data/Makefile.inc | 44 ++++++++++++++-------------- tests/data/test499 | 65 +++++++++++++++++++++++++++++++++++++++++ tests/data/test689 | 4 +-- 4 files changed, 92 insertions(+), 24 deletions(-) create mode 100644 tests/data/test499 diff --git a/lib/sendf.c b/lib/sendf.c index db3189a2980..60ac0742ccc 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -575,6 +575,9 @@ static CURLcode cw_download_write(struct Curl_easy *data, DEBUGF(infof(data, "did not want a BODY, but seeing %zu bytes", nbytes)); data->req.download_done = TRUE; + if(data->info.header_size) + /* if headers have been received, this is fine */ + return CURLE_OK; return CURLE_WEIRD_SERVER_REPLY; } diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index c3d496f6468..cd393da750f 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -75,28 +75,28 @@ test444 test445 test446 test447 test448 test449 test450 test451 test452 \ test453 test454 test455 test456 test457 test458 test459 test460 test461 \ \ test490 test491 test492 test493 test494 test495 test496 test497 test498 \ -\ -test500 test501 test502 test503 test504 test505 test506 test507 test508 \ -test509 test510 test511 test512 test513 test514 test515 test516 test517 \ -test518 test519 test520 test521 test522 test523 test524 test525 test526 \ -test527 test528 test529 test530 test531 test532 test533 test534 test535 \ - test537 test538 test539 test540 test541 test542 test543 test544 \ -test545 test546 test547 test548 test549 test550 test551 test552 test553 \ -test554 test555 test556 test557 test558 test559 test560 test561 test562 \ -test563 test564 test565 test566 test567 test568 test569 test570 test571 \ -test572 test573 test574 test575 test576 test577 test578 test579 test580 \ -test581 test582 test583 test584 test585 test586 test587 test588 test589 \ -test590 test591 test592 test593 test594 test595 test596 test597 test598 \ -test599 test600 test601 test602 test603 test604 test605 test606 test607 \ -test608 test609 test610 test611 test612 test613 test614 test615 test616 \ -test617 test618 test619 test620 test621 test622 test623 test624 test625 \ -test626 test627 test628 test629 test630 test631 test632 test633 test634 \ -test635 test636 test637 test638 test639 test640 test641 test642 test643 \ -test644 test645 test646 test647 test648 test649 test650 test651 test652 \ -test653 test654 test655 test656 test658 test659 test660 test661 test662 \ -test663 test664 test665 test666 test667 test668 test669 test670 test671 \ -test672 test673 test674 test675 test676 test677 test678 test679 test680 \ -test681 test682 test683 test684 test685 test686 test687 test688 test689 \ +test499 test500 test501 test502 test503 test504 test505 test506 test507 \ +test508 test509 test510 test511 test512 test513 test514 test515 test516 \ +test517 test518 test519 test520 test521 test522 test523 test524 test525 \ +test526 test527 test528 test529 test530 test531 test532 test533 test534 \ +test535 test537 test538 test539 test540 test541 test542 test543 \ +test544 test545 test546 test547 test548 test549 test550 test551 test552 \ +test553 test554 test555 test556 test557 test558 test559 test560 test561 \ +test562 test563 test564 test565 test566 test567 test568 test569 test570 \ +test571 test572 test573 test574 test575 test576 test577 test578 test579 \ +test580 test581 test582 test583 test584 test585 test586 test587 test588 \ +test589 test590 test591 test592 test593 test594 test595 test596 test597 \ +test598 test599 test600 test601 test602 test603 test604 test605 test606 \ +test607 test608 test609 test610 test611 test612 test613 test614 test615 \ +test616 test617 test618 test619 test620 test621 test622 test623 test624 \ +test625 test626 test627 test628 test629 test630 test631 test632 test633 \ +test634 test635 test636 test637 test638 test639 test640 test641 test642 \ +test643 test644 test645 test646 test647 test648 test649 test650 test651 \ +test652 test653 test654 test655 test656 test658 test659 test660 test661 \ +test662 test663 test664 test665 test666 test667 test668 test669 test670 \ +test671 test672 test673 test674 test675 test676 test677 test678 test679 \ +test680 test681 test682 test683 test684 test685 test686 test687 test688 \ +test689 \ \ test700 test701 test702 test703 test704 test705 test706 test707 test708 \ test709 test710 test711 test712 test713 test714 test715 test716 test717 \ diff --git a/tests/data/test499 b/tests/data/test499 new file mode 100644 index 00000000000..d4040b07ce9 --- /dev/null +++ b/tests/data/test499 @@ -0,0 +1,65 @@ + + + +HTTP +HTTP GET + + + +# +# Server-side + + +HTTP/1.1 200 OK +Date: Tue, 09 Nov 2010 14:49:00 GMT +Server: test-server/fake +Last-Modified: Tue, 13 Jun 2000 12:10:00 GMT +ETag: "21025-dc7-39462498" +Accept-Ranges: bytes +Content-Length: 6 +Connection: close +Content-Type: text/html +Funny-head: yesyes + +-foo- + + +HTTP/1.1 200 OK +Date: Tue, 09 Nov 2010 14:49:00 GMT +Server: test-server/fake +Last-Modified: Tue, 13 Jun 2000 12:10:00 GMT +ETag: "21025-dc7-39462498" +Accept-Ranges: bytes +Content-Length: 6 +Connection: close +Content-Type: text/html +Funny-head: yesyes + + + +# +# Client-side + + +http + + +HTTP HEAD to server still sending a body + + +http://%HOSTIP:%HTTPPORT/%TESTNUMBER -I + + + +# +# Verify data after the test has been "shot" + + +HEAD /%TESTNUMBER HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +User-Agent: curl/%VERSION +Accept: */* + + + + diff --git a/tests/data/test689 b/tests/data/test689 index 821556decfa..381ae225ae2 100644 --- a/tests/data/test689 +++ b/tests/data/test689 @@ -44,9 +44,9 @@ User-Agent: test567 Test-Number: 567 -# 8 == CURLE_WEIRD_SERVER_REPLY +# 85 == CURLE_RTSP_CSEQ_ERROR -8 +85 From a84ad94dd6b2c68ebc5f3bcbbd8ad12d5fbf2ffc Mon Sep 17 00:00:00 2001 From: Faraz Fallahi Date: Sat, 3 Feb 2024 16:20:35 -0800 Subject: [PATCH 269/509] connect.c: fix typo Closes #12858 --- lib/connect.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/connect.c b/lib/connect.c index 45743e98b52..55bd49d8d31 100644 --- a/lib/connect.c +++ b/lib/connect.c @@ -94,7 +94,7 @@ * infinite time left). If the value is negative, the timeout time has already * elapsed. * @param data the transfer to check on - * @param nowp timestamp to use for calculdation, NULL to use Curl_now() + * @param nowp timestamp to use for calculation, NULL to use Curl_now() * @param duringconnect TRUE iff connect timeout is also taken into account. * @unittest: 1303 */ From 541321507e386744c3ea1200cc83cc98338e27d7 Mon Sep 17 00:00:00 2001 From: Chris Webb Date: Sat, 3 Feb 2024 21:05:59 +0000 Subject: [PATCH 270/509] configure: add --disable-docs flag Building man pages from curldown sources now requires perl. Add a --disable-docs flag to configure to enable building and installing without documentation where perl is not available or man pages are not required. This is selected automatically (with a warning) when perl is not found by configure. Fixes #12832 Closes #12857 --- Makefile.am | 5 +++++ configure.ac | 34 ++++++++++++++++++++++++++++++++++ src/Makefile.am | 2 ++ 3 files changed, 41 insertions(+) diff --git a/Makefile.am b/Makefile.am index b56ca1a1eb2..6457d03dc43 100644 --- a/Makefile.am +++ b/Makefile.am @@ -241,10 +241,15 @@ 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) +endif # We extend the standard uninstall with a custom hook: uninstall-hook: diff --git a/configure.ac b/configure.ac index be66be9e9df..02c51c12eeb 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)" @@ -997,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 ********************************************************************** @@ -3753,6 +3776,16 @@ AC_PATH_PROG( PERL, perl, , $PATH:/usr/local/bin/perl:/usr/bin/:/usr/local/bin ) AC_SUBST(PERL) +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 + +dnl set variable for use in automakefile(s) +AM_CONDITIONAL(BUILD_DOCS, test x"$BUILD_DOCS" = x1) + AC_PATH_PROGS( NROFF, gnroff nroff, , $PATH:/usr/bin/:/usr/local/bin ) AC_SUBST(NROFF) @@ -4939,6 +4972,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} diff --git a/src/Makefile.am b/src/Makefile.am index 7a99c254803..713dacf130f 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -45,7 +45,9 @@ AM_CPPFLAGS = -I$(top_srcdir)/include \ bin_PROGRAMS = curl +if BUILD_DOCS SUBDIRS = ../docs +endif if USE_CPPFLAG_CURL_STATICLIB AM_CPPFLAGS += -DCURL_STATICLIB From 7e2c53f72bd4030f9e851123e554f0b8635d24bb Mon Sep 17 00:00:00 2001 From: Boris Verkhovskiy Date: Sat, 3 Feb 2024 01:05:16 -0800 Subject: [PATCH 271/509] proxy1.0.md: fix example Closes #12856 --- docs/cmdline-opts/proxy1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cmdline-opts/proxy1.0.md b/docs/cmdline-opts/proxy1.0.md index d7b7a43815f..4d3203a0325 100644 --- a/docs/cmdline-opts/proxy1.0.md +++ b/docs/cmdline-opts/proxy1.0.md @@ -12,7 +12,7 @@ See-also: - socks5 - preproxy Example: - - --proxy1.0 -x http://proxy $URL + - --proxy1.0 http://proxy $URL --- # `--proxy1.0` From 3ec85206ad9333df60781e3cd918104de85d8fcc Mon Sep 17 00:00:00 2001 From: Lars Kellogg-Stedman Date: Fri, 2 Feb 2024 12:51:19 -0500 Subject: [PATCH 272/509] ALTSVC.md: correct a typo The ALPN documentation erroneously referred to a "host number" instead of a "port number". Closes #12852 --- docs/ALTSVC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ALTSVC.md b/docs/ALTSVC.md index 18d2d2ad9f7..92343aee4de 100644 --- a/docs/ALTSVC.md +++ b/docs/ALTSVC.md @@ -28,7 +28,7 @@ space separated fields. 3. The port number for the source origin 4. The ALPN id for the destination host 5. The hostname for the destination host -6. The host number 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) From 8911d867198ff1149ccc8d0b4c4682ac97aa2c09 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 19:42:58 +0100 Subject: [PATCH 273/509] cookie.md: provide an example sending a fixed cookie Closes #12868 --- docs/cmdline-opts/cookie.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cmdline-opts/cookie.md b/docs/cmdline-opts/cookie.md index d0a6d353966..c4415bf80aa 100644 --- a/docs/cmdline-opts/cookie.md +++ b/docs/cmdline-opts/cookie.md @@ -16,6 +16,7 @@ Example: - -b "" $URL - -b cookiefile $URL - -b cookiefile -c cookiefile $URL + - -b name=Jane $URL --- # `--cookie` From 0dc036225b3013bf994da81fa44571bcfcecbe92 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 31 Jan 2024 16:30:54 +0100 Subject: [PATCH 274/509] HTTP/2: write response directly - use the new `Curl_xfer_write_resp()` to write incoming responses directly to the client - eliminates `stream->recvbuf` - memory consumption on parallel transfers minimized Closes #12828 --- lib/http2.c | 222 +++++++++++++++++++--------------------------------- 1 file changed, 82 insertions(+), 140 deletions(-) diff --git a/lib/http2.c b/lib/http2.c index c3157d1ef28..cb765b54b5a 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -169,10 +169,9 @@ static CURLcode h2_progress_egress(struct Curl_cfilter *cf, struct Curl_easy *data); /** - * All about the H3 internals of a stream + * All about the H2 internals of a stream */ -struct stream_ctx { - /*********** for HTTP/2 we store stream-local data here *************/ +struct h2_stream_ctx { int32_t id; /* HTTP/2 protocol identifier for stream */ struct bufq recvbuf; /* response buffer */ struct bufq sendbuf; /* request buffer */ @@ -181,6 +180,7 @@ struct stream_ctx { size_t resp_hds_len; /* amount of response header bytes in recvbuf */ size_t upload_blocked_len; curl_off_t upload_left; /* number of request bytes left to upload */ + curl_off_t nrcvd_data; /* number of DATA bytes received */ char **push_headers; /* allocated array */ size_t push_headers_used; /* number of entries filled in */ @@ -198,7 +198,8 @@ struct stream_ctx { buffered data in stream->sendbuf to upload. */ }; -#define H2_STREAM_CTX(d) ((struct stream_ctx *)(((d) && (d)->req.p.http)? \ +#define H2_STREAM_CTX(d) ((struct h2_stream_ctx *)(((d) && \ + (d)->req.p.http)? \ ((struct HTTP *)(d)->req.p.http)->h2_ctx \ : NULL)) #define H2_STREAM_LCTX(d) ((struct HTTP *)(d)->req.p.http)->h2_ctx @@ -210,7 +211,7 @@ struct stream_ctx { */ static void drain_stream(struct Curl_cfilter *cf, struct Curl_easy *data, - struct stream_ctx *stream) + struct h2_stream_ctx *stream) { unsigned char bits; @@ -229,10 +230,10 @@ static void drain_stream(struct Curl_cfilter *cf, static CURLcode http2_data_setup(struct Curl_cfilter *cf, struct Curl_easy *data, - struct stream_ctx **pstream) + struct h2_stream_ctx **pstream) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream; + struct h2_stream_ctx *stream; (void)cf; DEBUGASSERT(data); @@ -253,8 +254,6 @@ static CURLcode http2_data_setup(struct Curl_cfilter *cf, stream->id = -1; Curl_bufq_initp(&stream->sendbuf, &ctx->stream_bufcp, H2_STREAM_SEND_CHUNKS, BUFQ_OPT_NONE); - Curl_bufq_initp(&stream->recvbuf, &ctx->stream_bufcp, - H2_STREAM_RECV_CHUNKS, BUFQ_OPT_SOFT_LIMIT); Curl_h1_req_parse_init(&stream->h1, H1_PARSE_DEFAULT_MAX_LINE_LEN); Curl_dynhds_init(&stream->resp_trailers, 0, DYN_HTTP_REQUEST); stream->resp_hds_len = 0; @@ -265,6 +264,7 @@ static CURLcode http2_data_setup(struct Curl_cfilter *cf, stream->error = NGHTTP2_NO_ERROR; stream->local_window_size = H2_STREAM_WINDOW_SIZE; stream->upload_left = 0; + stream->nrcvd_data = 0; H2_STREAM_LCTX(data) = stream; *pstream = stream; @@ -275,7 +275,7 @@ static void http2_data_done(struct Curl_cfilter *cf, struct Curl_easy *data, bool premature) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); DEBUGASSERT(ctx); (void)premature; @@ -298,23 +298,12 @@ static void http2_data_done(struct Curl_cfilter *cf, stream->id, NGHTTP2_STREAM_CLOSED); flush_egress = TRUE; } - if(!Curl_bufq_is_empty(&stream->recvbuf)) { - /* Anything in the recvbuf is still being counted - * in stream and connection window flow control. Need - * to free that space or the connection window might get - * exhausted eventually. */ - nghttp2_session_consume(ctx->h2, stream->id, - Curl_bufq_len(&stream->recvbuf)); - /* give WINDOW_UPATE a chance to be sent, but ignore any error */ - flush_egress = TRUE; - } if(flush_egress) nghttp2_session_send(ctx->h2); } Curl_bufq_free(&stream->sendbuf); - Curl_bufq_free(&stream->recvbuf); Curl_h1_req_parse_free(&stream->h1); Curl_dynhds_free(&stream->resp_trailers); if(stream->push_headers) { @@ -411,7 +400,7 @@ static CURLcode cf_h2_ctx_init(struct Curl_cfilter *cf, bool via_h1_upgrade) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream; + struct h2_stream_ctx *stream; CURLcode result = CURLE_OUT_OF_MEMORY; int rc; nghttp2_session_callbacks *cbs = NULL; @@ -731,7 +720,7 @@ char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num) if(!h || !GOOD_EASY_HANDLE(h->data)) return NULL; else { - struct stream_ctx *stream = H2_STREAM_CTX(h->data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(h->data); if(stream && num < stream->push_headers_used) return stream->push_headers[num]; } @@ -743,7 +732,7 @@ char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num) */ char *curl_pushheader_byname(struct curl_pushheaders *h, const char *header) { - struct stream_ctx *stream; + struct h2_stream_ctx *stream; size_t len; size_t i; /* Verify that we got a good easy handle in the push header struct, @@ -783,7 +772,7 @@ static struct Curl_easy *h2_duphandle(struct Curl_cfilter *cf, (void)Curl_close(&second); } else { - struct stream_ctx *second_stream; + struct h2_stream_ctx *second_stream; second->req.p.http = http; http2_data_setup(cf, second, &second_stream); @@ -867,8 +856,8 @@ static int push_promise(struct Curl_cfilter *cf, CURL_TRC_CF(data, cf, "[%d] PUSH_PROMISE received", frame->promised_stream_id); if(data->multi->push_cb) { - struct stream_ctx *stream; - struct stream_ctx *newstream; + struct h2_stream_ctx *stream; + struct h2_stream_ctx *newstream; struct curl_pushheaders heads; CURLMcode rc; CURLcode result; @@ -967,18 +956,10 @@ static CURLcode recvbuf_write_hds(struct Curl_cfilter *cf, struct Curl_easy *data, const char *buf, size_t blen) { - struct stream_ctx *stream = H2_STREAM_CTX(data); - ssize_t nwritten; - CURLcode result; + bool done; (void)cf; - nwritten = Curl_bufq_write(&stream->recvbuf, - (const unsigned char *)buf, blen, &result); - if(nwritten < 0) - return result; - stream->resp_hds_len += (size_t)nwritten; - DEBUGASSERT((size_t)nwritten == blen); - return CURLE_OK; + return Curl_xfer_write_resp(data, (char *)buf, blen, FALSE, &done); } static CURLcode on_stream_frame(struct Curl_cfilter *cf, @@ -986,10 +967,9 @@ static CURLcode on_stream_frame(struct Curl_cfilter *cf, const nghttp2_frame *frame) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); int32_t stream_id = frame->hd.stream_id; CURLcode result; - size_t rbuflen; int rv; if(!stream) { @@ -999,9 +979,8 @@ static CURLcode on_stream_frame(struct Curl_cfilter *cf, switch(frame->hd.type) { case NGHTTP2_DATA: - rbuflen = Curl_bufq_len(&stream->recvbuf); - CURL_TRC_CF(data, cf, "[%d] DATA, buffered=%zu, window=%d/%d", - stream_id, rbuflen, + CURL_TRC_CF(data, cf, "[%d] DATA, window=%d/%d", + stream_id, nghttp2_session_get_stream_effective_recv_data_length( ctx->h2, stream->id), nghttp2_session_get_stream_effective_local_window_size( @@ -1018,20 +997,6 @@ static CURLcode on_stream_frame(struct Curl_cfilter *cf, if(frame->hd.flags & NGHTTP2_FLAG_END_STREAM) { drain_stream(cf, data, stream); } - else if(rbuflen > stream->local_window_size) { - int32_t wsize = nghttp2_session_get_stream_local_window_size( - ctx->h2, stream->id); - if(wsize > 0 && (uint32_t)wsize != stream->local_window_size) { - /* H2 flow control is not absolute, as the server might not have the - * same view, yet. When we receive more than we want, we enforce - * the local window size again to make nghttp2 send WINDOW_UPATEs - * accordingly. */ - nghttp2_session_set_local_window_size(ctx->h2, - NGHTTP2_FLAG_NONE, - stream->id, - stream->local_window_size); - } - } break; case NGHTTP2_HEADERS: if(stream->bodystarted) { @@ -1233,7 +1198,7 @@ static int on_frame_recv(nghttp2_session *session, const nghttp2_frame *frame, * servers send an explicit WINDOW_UPDATE, but not all seem to do that. * To be safe, we UNHOLD a stream in order not to stall. */ if(CURL_WANT_SEND(data)) { - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); if(stream) drain_stream(cf, data, stream); } @@ -1270,10 +1235,11 @@ static int on_data_chunk_recv(nghttp2_session *session, uint8_t flags, const uint8_t *mem, size_t len, void *userp) { struct Curl_cfilter *cf = userp; - struct stream_ctx *stream; + struct cf_h2_ctx *ctx = cf->ctx; + struct h2_stream_ctx *stream; struct Curl_easy *data_s; - ssize_t nwritten; CURLcode result; + bool done; (void)flags; DEBUGASSERT(stream_id); /* should never be a zero stream ID here */ @@ -1296,18 +1262,15 @@ static int on_data_chunk_recv(nghttp2_session *session, uint8_t flags, if(!stream) return NGHTTP2_ERR_CALLBACK_FAILURE; - nwritten = Curl_bufq_write(&stream->recvbuf, mem, len, &result); - if(nwritten < 0) { - if(result != CURLE_AGAIN) - return NGHTTP2_ERR_CALLBACK_FAILURE; + result = Curl_xfer_write_resp(data_s, (char *)mem, len, FALSE, &done); + if(result && result != CURLE_AGAIN) + return NGHTTP2_ERR_CALLBACK_FAILURE; - nwritten = 0; - } + nghttp2_session_consume(ctx->h2, stream_id, len); + stream->nrcvd_data += (curl_off_t)len; /* if we receive data for another handle, wake that up */ drain_stream(cf, data_s, stream); - - DEBUGASSERT((size_t)nwritten == len); return 0; } @@ -1316,7 +1279,7 @@ static int on_stream_close(nghttp2_session *session, int32_t stream_id, { struct Curl_cfilter *cf = userp; struct Curl_easy *data_s, *call_data = CF_DATA_CURRENT(cf); - struct stream_ctx *stream; + struct h2_stream_ctx *stream; int rv; (void)session; @@ -1374,7 +1337,7 @@ static int on_begin_headers(nghttp2_session *session, const nghttp2_frame *frame, void *userp) { struct Curl_cfilter *cf = userp; - struct stream_ctx *stream; + struct h2_stream_ctx *stream; struct Curl_easy *data_s = NULL; (void)cf; @@ -1403,7 +1366,7 @@ static int on_header(nghttp2_session *session, const nghttp2_frame *frame, void *userp) { struct Curl_cfilter *cf = userp; - struct stream_ctx *stream; + struct h2_stream_ctx *stream; struct Curl_easy *data_s; int32_t stream_id = frame->hd.stream_id; CURLcode result; @@ -1565,7 +1528,7 @@ static ssize_t req_body_read_callback(nghttp2_session *session, { struct Curl_cfilter *cf = userp; struct Curl_easy *data_s; - struct stream_ctx *stream = NULL; + struct h2_stream_ctx *stream = NULL; CURLcode result; ssize_t nread; (void)source; @@ -1667,7 +1630,7 @@ static CURLcode http2_data_done_send(struct Curl_cfilter *cf, { struct cf_h2_ctx *ctx = cf->ctx; CURLcode result = CURLE_OK; - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); if(!ctx || !ctx->h2 || !stream) goto out; @@ -1691,7 +1654,7 @@ static CURLcode http2_data_done_send(struct Curl_cfilter *cf, static ssize_t http2_handle_stream_close(struct Curl_cfilter *cf, struct Curl_easy *data, - struct stream_ctx *stream, + struct h2_stream_ctx *stream, CURLcode *err) { ssize_t rv = 0; @@ -1787,7 +1750,7 @@ static void h2_pri_spec(struct Curl_easy *data, nghttp2_priority_spec *pri_spec) { struct Curl_data_priority *prio = &data->set.priority; - struct stream_ctx *depstream = H2_STREAM_CTX(prio->parent); + struct h2_stream_ctx *depstream = H2_STREAM_CTX(prio->parent); int32_t depstream_id = depstream? depstream->id:0; nghttp2_priority_spec_init(pri_spec, depstream_id, sweight_wanted(data), @@ -1805,7 +1768,7 @@ static CURLcode h2_progress_egress(struct Curl_cfilter *cf, struct Curl_easy *data) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); int rv = 0; if(stream && stream->id > 0 && @@ -1838,40 +1801,26 @@ static CURLcode h2_progress_egress(struct Curl_cfilter *cf, } static ssize_t stream_recv(struct Curl_cfilter *cf, struct Curl_easy *data, - struct stream_ctx *stream, + struct h2_stream_ctx *stream, char *buf, size_t len, CURLcode *err) { struct cf_h2_ctx *ctx = cf->ctx; ssize_t nread = -1; + (void)buf; *err = CURLE_AGAIN; - if(!Curl_bufq_is_empty(&stream->recvbuf)) { - nread = Curl_bufq_read(&stream->recvbuf, - (unsigned char *)buf, len, err); - if(nread < 0) - goto out; - DEBUGASSERT(nread > 0); - } - - if(nread < 0) { - if(stream->closed) { - CURL_TRC_CF(data, cf, "[%d] returning CLOSE", stream->id); - nread = http2_handle_stream_close(cf, data, stream, err); - } - else if(stream->reset || - (ctx->conn_closed && Curl_bufq_is_empty(&ctx->inbufq)) || - (ctx->goaway && ctx->last_stream_id < stream->id)) { - CURL_TRC_CF(data, cf, "[%d] returning ERR", stream->id); - *err = stream->bodystarted? CURLE_PARTIAL_FILE : CURLE_RECV_ERROR; - nread = -1; - } - } - else if(nread == 0) { - *err = CURLE_AGAIN; + if(stream->closed) { + CURL_TRC_CF(data, cf, "[%d] returning CLOSE", stream->id); + nread = http2_handle_stream_close(cf, data, stream, err); + } + else if(stream->reset || + (ctx->conn_closed && Curl_bufq_is_empty(&ctx->inbufq)) || + (ctx->goaway && ctx->last_stream_id < stream->id)) { + CURL_TRC_CF(data, cf, "[%d] returning ERR", stream->id); + *err = stream->bodystarted? CURLE_PARTIAL_FILE : CURLE_RECV_ERROR; nread = -1; } -out: if(nread < 0 && *err != CURLE_AGAIN) CURL_TRC_CF(data, cf, "[%d] stream_recv(len=%zu) -> %zd, %d", stream->id, len, nread, *err); @@ -1879,10 +1828,11 @@ static ssize_t stream_recv(struct Curl_cfilter *cf, struct Curl_easy *data, } static CURLcode h2_progress_ingress(struct Curl_cfilter *cf, - struct Curl_easy *data) + struct Curl_easy *data, + size_t data_max_bytes) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream; + struct h2_stream_ctx *stream; CURLcode result = CURLE_OK; ssize_t nread; @@ -1899,16 +1849,17 @@ static CURLcode h2_progress_ingress(struct Curl_cfilter *cf, * all network input */ while(!ctx->conn_closed && Curl_bufq_is_empty(&ctx->inbufq)) { stream = H2_STREAM_CTX(data); - if(stream && (stream->closed || Curl_bufq_is_full(&stream->recvbuf))) { + if(stream && (stream->closed || !data_max_bytes)) { /* We would like to abort here and stop processing, so that * the transfer loop can handle the data/close here. However, * this may leave data in underlying buffers that will not * be consumed. */ if(!cf->next || !cf->next->cft->has_data_pending(cf->next, data)) - break; + drain_stream(cf, data, stream); + break; } - nread = Curl_bufq_slurp(&ctx->inbufq, nw_in_reader, cf, &result); + nread = Curl_bufq_sipn(&ctx->inbufq, 0, nw_in_reader, cf, &result); if(nread < 0) { if(result != CURLE_AGAIN) { failf(data, "Failed receiving HTTP2 data: %d(%s)", result, @@ -1923,8 +1874,9 @@ static CURLcode h2_progress_ingress(struct Curl_cfilter *cf, break; } else { - CURL_TRC_CF(data, cf, "[0] ingress: read %zd bytes", - nread); + CURL_TRC_CF(data, cf, "[0] ingress: read %zd bytes", nread); + data_max_bytes = (data_max_bytes > (size_t)nread)? + (data_max_bytes - (size_t)nread) : 0; } if(h2_process_pending_input(cf, data, &result)) @@ -1942,7 +1894,7 @@ static ssize_t cf_h2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, char *buf, size_t len, CURLcode *err) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); ssize_t nread = -1; CURLcode result; struct cf_call_data save; @@ -1966,7 +1918,7 @@ static ssize_t cf_h2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, goto out; if(nread < 0) { - *err = h2_progress_ingress(cf, data); + *err = h2_progress_ingress(cf, data, len); if(*err) goto out; @@ -2011,9 +1963,8 @@ static ssize_t cf_h2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, nread = -1; } CURL_TRC_CF(data, cf, "[%d] cf_recv(len=%zu) -> %zd %d, " - "buffered=%zu, window=%d/%d, connection %d/%d", + "window=%d/%d, connection %d/%d", stream->id, len, nread, *err, - Curl_bufq_len(&stream->recvbuf), nghttp2_session_get_stream_effective_recv_data_length( ctx->h2, stream->id), nghttp2_session_get_stream_effective_local_window_size( @@ -2025,12 +1976,12 @@ static ssize_t cf_h2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, return nread; } -static ssize_t h2_submit(struct stream_ctx **pstream, +static ssize_t h2_submit(struct h2_stream_ctx **pstream, struct Curl_cfilter *cf, struct Curl_easy *data, const void *buf, size_t len, CURLcode *err) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream = NULL; + struct h2_stream_ctx *stream = NULL; struct dynhds h2_headers; nghttp2_nv *nva = NULL; const void *body = NULL; @@ -2169,7 +2120,7 @@ static ssize_t cf_h2_send(struct Curl_cfilter *cf, struct Curl_easy *data, const void *buf, size_t len, CURLcode *err) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); struct cf_call_data save; int rv; ssize_t nwritten; @@ -2340,7 +2291,7 @@ static void cf_h2_adjust_pollset(struct Curl_cfilter *cf, sock = Curl_conn_cf_get_socket(cf, data); Curl_pollset_check(data, ps, sock, &want_recv, &want_send); if(want_recv || want_send) { - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); struct cf_call_data save; bool c_exhaust, s_exhaust; @@ -2387,7 +2338,7 @@ static CURLcode cf_h2_connect(struct Curl_cfilter *cf, goto out; } - result = h2_progress_ingress(cf, data); + result = h2_progress_ingress(cf, data, H2_CHUNK_SIZE); if(result) goto out; @@ -2441,7 +2392,7 @@ static CURLcode http2_data_pause(struct Curl_cfilter *cf, { #ifdef NGHTTP2_HAS_SET_LOCAL_WINDOW_SIZE struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); DEBUGASSERT(data); if(ctx && ctx->h2 && stream) { @@ -2526,11 +2477,10 @@ static bool cf_h2_data_pending(struct Curl_cfilter *cf, const struct Curl_easy *data) { struct cf_h2_ctx *ctx = cf->ctx; - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); if(ctx && (!Curl_bufq_is_empty(&ctx->inbufq) - || (stream && !Curl_bufq_is_empty(&stream->sendbuf)) - || (stream && !Curl_bufq_is_empty(&stream->recvbuf)))) + || (stream && !Curl_bufq_is_empty(&stream->sendbuf)))) return TRUE; return cf->next? cf->next->cft->has_data_pending(cf->next, data) : FALSE; } @@ -2615,7 +2565,8 @@ struct Curl_cftype Curl_cft_nghttp2 = { static CURLcode http2_cfilter_add(struct Curl_cfilter **pcf, struct Curl_easy *data, struct connectdata *conn, - int sockindex) + int sockindex, + bool via_h1_upgrade) { struct Curl_cfilter *cf = NULL; struct cf_h2_ctx *ctx; @@ -2630,8 +2581,9 @@ static CURLcode http2_cfilter_add(struct Curl_cfilter **pcf, if(result) goto out; + ctx = NULL; Curl_conn_cf_add(data, conn, sockindex, cf); - result = CURLE_OK; + result = cf_h2_ctx_init(cf, data, via_h1_upgrade); out: if(result) @@ -2641,7 +2593,8 @@ static CURLcode http2_cfilter_add(struct Curl_cfilter **pcf, } static CURLcode http2_cfilter_insert_after(struct Curl_cfilter *cf, - struct Curl_easy *data) + struct Curl_easy *data, + bool via_h1_upgrade) { struct Curl_cfilter *cf_h2 = NULL; struct cf_h2_ctx *ctx; @@ -2656,8 +2609,9 @@ static CURLcode http2_cfilter_insert_after(struct Curl_cfilter *cf, if(result) goto out; + ctx = NULL; Curl_conn_cf_insert_after(cf, cf_h2); - result = CURLE_OK; + result = cf_h2_ctx_init(cf_h2, data, via_h1_upgrade); out: if(result) @@ -2714,11 +2668,7 @@ CURLcode Curl_http2_switch(struct Curl_easy *data, DEBUGASSERT(!Curl_conn_is_http2(data, conn, sockindex)); DEBUGF(infof(data, "switching to HTTP/2")); - result = http2_cfilter_add(&cf, data, conn, sockindex); - if(result) - return result; - - result = cf_h2_ctx_init(cf, data, FALSE); + result = http2_cfilter_add(&cf, data, conn, sockindex, FALSE); if(result) return result; @@ -2741,15 +2691,11 @@ CURLcode Curl_http2_switch_at(struct Curl_cfilter *cf, struct Curl_easy *data) DEBUGASSERT(!Curl_cf_is_http2(cf, data)); - result = http2_cfilter_insert_after(cf, data); + result = http2_cfilter_insert_after(cf, data, FALSE); if(result) return result; cf_h2 = cf->next; - result = cf_h2_ctx_init(cf_h2, data, FALSE); - if(result) - return result; - cf->conn->httpversion = 20; /* we know we're on HTTP/2 now */ cf->conn->bits.multiplex = TRUE; /* at least potentially multiplexed */ cf->conn->bundle->multiuse = BUNDLE_MULTIPLEX; @@ -2774,17 +2720,13 @@ CURLcode Curl_http2_upgrade(struct Curl_easy *data, DEBUGF(infof(data, "upgrading to HTTP/2")); DEBUGASSERT(data->req.upgr101 == UPGR101_RECEIVED); - result = http2_cfilter_add(&cf, data, conn, sockindex); + result = http2_cfilter_add(&cf, data, conn, sockindex, TRUE); if(result) return result; DEBUGASSERT(cf->cft == &Curl_cft_nghttp2); ctx = cf->ctx; - result = cf_h2_ctx_init(cf, data, TRUE); - if(result) - return result; - if(nread > 0) { /* Remaining data from the protocol switch reply is already using * the switched protocol, ie. HTTP/2. We add that to the network @@ -2823,7 +2765,7 @@ CURLcode Curl_http2_upgrade(struct Curl_easy *data, CURLE_HTTP2_STREAM error! */ bool Curl_h2_http_1_1_error(struct Curl_easy *data) { - struct stream_ctx *stream = H2_STREAM_CTX(data); + struct h2_stream_ctx *stream = H2_STREAM_CTX(data); return (stream && stream->error == NGHTTP2_HTTP_1_1_REQUIRED); } From aefb0bde4e91291329fc08d03cd565e74c97f5ca Mon Sep 17 00:00:00 2001 From: Joel Depooter Date: Fri, 2 Feb 2024 17:58:04 -0800 Subject: [PATCH 275/509] docs: add missing slashes to SChannel client certificate documentation When setting the CURLOPT_SSLCERT option to a certificate thumprint, it is required to have a backslash between the "store location", "store name" and "thumbprint" tokens. These slashes were present in the previous documentation, but were missed in the transition to markdown documentation. Closes #12854 --- docs/libcurl/opts/CURLOPT_SSLCERT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.md b/docs/libcurl/opts/CURLOPT_SSLCERT.md index 21f052ff76d..8400e6e2a88 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.md @@ -36,9 +36,9 @@ in order to avoid confusion with a nickname. (Schannel only) Client certificates can be specified by a path expression to a certificate store. (You can import *PFX* to a store first). You can use -"" to refer to a certificate in the +"\\\\" to refer to a certificate in the system certificates store, for example, -**"CurrentUserMY934a7ac6f8a5d579285a74fa"**. The thumbprint is usually a SHA-1 +**"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"**. The 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**, From 5cc2b016c36aaf5a08e2feb7c068fca5bb0a8052 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 15:22:08 +0100 Subject: [PATCH 276/509] md4: include strdup.h for the memdup proto Reported-by: Erik Schnetter Fixes #12849 Closes #12863 --- lib/md4.c | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/md4.c b/lib/md4.c index 067c211e420..58dd1166cf9 100644 --- a/lib/md4.c +++ b/lib/md4.c @@ -28,6 +28,7 @@ #include +#include "strdup.h" #include "curl_md4.h" #include "warnless.h" From 75d79a4486b279100209ddf8c7fdb12955fb66e9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 19:24:50 +0100 Subject: [PATCH 277/509] tool_cb_hdr: only parse etag + content-disposition for 2xx ... and ignore them for other response codes. Reported-by: Harry Sintonen Closes #12866 --- src/tool_cb_hdr.c | 141 ++++++++++++++++++++++++---------------------- 1 file changed, 74 insertions(+), 67 deletions(-) diff --git a/src/tool_cb_hdr.c b/src/tool_cb_hdr.c index 30ee3b09c95..13fb76d6ade 100644 --- a/src/tool_cb_hdr.c +++ b/src/tool_cb_hdr.c @@ -105,12 +105,21 @@ size_t tool_header_cb(char *ptr, size_t size, size_t nmemb, void *userdata) (void)fflush(heads->stream); } - /* - * Write etag to file when --etag-save option is given. - */ - if(per->config->etag_save_file && etag_save->stream) { - /* match only header that start with etag (case insensitive) */ - if(curl_strnequal(str, "etag:", 5)) { + curl_easy_getinfo(per->curl, CURLINFO_SCHEME, &scheme); + scheme = proto_token(scheme); + if((scheme == proto_http || scheme == proto_https)) { + long response = 0; + curl_easy_getinfo(per->curl, CURLINFO_RESPONSE_CODE, &response); + + if(response/100 != 2) + /* only care about these headers in 2xx responses */ + ; + /* + * Write etag to file when --etag-save option is given. + */ + else if(per->config->etag_save_file && etag_save->stream && + /* match only header that start with etag (case insensitive) */ + checkprefix("etag:", str)) { const char *etag_h = &str[5]; const char *eot = end - 1; if(*eot == '\n') { @@ -128,77 +137,75 @@ size_t tool_header_cb(char *ptr, size_t size, size_t nmemb, void *userdata) } } } - } - /* - * This callback sets the filename where output shall be written when - * curl options --remote-name (-O) and --remote-header-name (-J) have - * been simultaneously given and additionally server returns an HTTP - * Content-Disposition header specifying a filename property. - */ + /* + * This callback sets the filename where output shall be written when + * curl options --remote-name (-O) and --remote-header-name (-J) have + * been simultaneously given and additionally server returns an HTTP + * Content-Disposition header specifying a filename property. + */ - curl_easy_getinfo(per->curl, CURLINFO_SCHEME, &scheme); - scheme = proto_token(scheme); - if(hdrcbdata->honor_cd_filename && - (cb > 20) && checkprefix("Content-disposition:", str) && - (scheme == proto_http || scheme == proto_https)) { - const char *p = str + 20; - - /* look for the 'filename=' parameter - (encoded filenames (*=) are not supported) */ - for(;;) { - char *filename; - size_t len; - - while((p < end) && *p && !ISALPHA(*p)) - p++; - if(p > end - 9) - break; + else if(hdrcbdata->honor_cd_filename && + (cb > 20) && checkprefix("Content-disposition:", str)) { + const char *p = str + 20; + + /* look for the 'filename=' parameter + (encoded filenames (*=) are not supported) */ + for(;;) { + char *filename; + size_t len; - if(memcmp(p, "filename=", 9)) { - /* no match, find next parameter */ - while((p < end) && *p && (*p != ';')) + while((p < end) && *p && !ISALPHA(*p)) p++; - if((p < end) && *p) - continue; - else + if(p > end - 9) break; - } - p += 9; - - /* this expression below typecasts 'cb' only to avoid - warning: signed and unsigned type in conditional expression - */ - len = (ssize_t)cb - (p - str); - filename = parse_filename(p, len); - if(filename) { - if(outs->stream) { - /* indication of problem, get out! */ - free(filename); - return CURL_WRITEFUNC_ERROR; - } - if(per->config->output_dir) { - outs->filename = aprintf("%s/%s", per->config->output_dir, filename); - free(filename); - if(!outs->filename) + if(memcmp(p, "filename=", 9)) { + /* no match, find next parameter */ + while((p < end) && *p && (*p != ';')) + p++; + if((p < end) && *p) + continue; + else + break; + } + p += 9; + + /* this expression below typecasts 'cb' only to avoid + warning: signed and unsigned type in conditional expression + */ + len = (ssize_t)cb - (p - str); + filename = parse_filename(p, len); + if(filename) { + if(outs->stream) { + /* indication of problem, get out! */ + free(filename); + return CURL_WRITEFUNC_ERROR; + } + + if(per->config->output_dir) { + outs->filename = aprintf("%s/%s", per->config->output_dir, + filename); + free(filename); + if(!outs->filename) + return CURL_WRITEFUNC_ERROR; + } + else + outs->filename = filename; + + outs->is_cd_filename = TRUE; + outs->s_isreg = TRUE; + outs->fopened = FALSE; + outs->alloc_filename = TRUE; + hdrcbdata->honor_cd_filename = FALSE; /* done now! */ + if(!tool_create_output_file(outs, per->config)) return CURL_WRITEFUNC_ERROR; } - else - outs->filename = filename; - - outs->is_cd_filename = TRUE; - outs->s_isreg = TRUE; - outs->fopened = FALSE; - outs->alloc_filename = TRUE; - hdrcbdata->honor_cd_filename = FALSE; /* done now! */ - if(!tool_create_output_file(outs, per->config)) - return CURL_WRITEFUNC_ERROR; + break; } - break; + if(!outs->stream && !tool_create_output_file(outs, per->config)) + return CURL_WRITEFUNC_ERROR; } - if(!outs->stream && !tool_create_output_file(outs, per->config)) - return CURL_WRITEFUNC_ERROR; } if(hdrcbdata->config->writeout) { char *value = memchr(ptr, ':', cb); From d6825df334def106f735ce7e0c1a2ea87bddffb0 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 5 Feb 2024 17:29:24 +0100 Subject: [PATCH 278/509] openssl-quic: check on Windows that socket conv to int is possible Fixes #12861 Closes #12865 --- lib/vquic/curl_osslq.c | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/lib/vquic/curl_osslq.c b/lib/vquic/curl_osslq.c index c499a004bf5..9766feb2114 100644 --- a/lib/vquic/curl_osslq.c +++ b/lib/vquic/curl_osslq.c @@ -1078,6 +1078,20 @@ static CURLcode cf_osslq_ctx_start(struct Curl_cfilter *cf, goto out; } + /* Type conversions, see #12861: OpenSSL wants an `int`, but on 64-bit + * Win32 systems, Microsoft defines SOCKET as `unsigned long long`. + */ +#if defined(_WIN32) && !defined(__LWIP_OPT_H__) && !defined(LWIP_HDR_OPT_H) + if(ctx->q.sockfd > INT_MAX) { + failf(data, "windows socket identifier larger than MAX_INT, " + "unable to set in OpenSSL dgram API."); + result = CURLE_QUIC_CONNECT_ERROR; + goto out; + } + bio = BIO_new_dgram((int)ctx->q.sockfd, BIO_NOCLOSE); +#else + bio = BIO_new_dgram(ctx->q.sockfd, BIO_NOCLOSE); +#endif bio = BIO_new_dgram(ctx->q.sockfd, BIO_NOCLOSE); if(!bio) { result = CURLE_OUT_OF_MEMORY; From a982d19ab924b36a22792252828cd41c5c7579f9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 23:46:26 +0100 Subject: [PATCH 279/509] THANKS: add Dmitry Tretyakov ... since I missed to give credit to the report in the fix of #12861 --- docs/THANKS | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/THANKS b/docs/THANKS index eee2ec51a4d..183836301df 100644 --- a/docs/THANKS +++ b/docs/THANKS @@ -738,6 +738,7 @@ Dmitry Mikhirev Dmitry Popov Dmitry Rechkin Dmitry S. Baikov +Dmitry Tretyakov Dmitry Wagin dnivras on github Dolbneff A.V From 577182a6df4e13e909706aaf4d23635617f1eedb Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 5 Feb 2024 17:02:21 +0100 Subject: [PATCH 280/509] configure: do not link with nghttp3 unless necessary Fixes #12833 Closes #12864 Reported-by: Ryan Carsten Schmidt --- configure.ac | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/configure.ac b/configure.ac index 02c51c12eeb..db291afb006 100644 --- a/configure.ac +++ b/configure.ac @@ -3124,9 +3124,10 @@ dnl ********************************************************************** OPT_NGHTTP3="yes" -if test "x$USE_NGTCP2" = "x" -a "$USE_OPENSSL_QUIC" = "x"; then +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, From bf411ccd0d5ccc01c647be612cac31c58227549a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 19:30:48 +0100 Subject: [PATCH 281/509] libcurl-security.md: Active FTP passes on the local IP address Reported-by: Harry Sintonen Closes #12867 --- docs/libcurl/libcurl-security.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/libcurl/libcurl-security.md b/docs/libcurl/libcurl-security.md index 09d63f4a868..019080d263d 100644 --- a/docs/libcurl/libcurl-security.md +++ b/docs/libcurl/libcurl-security.md @@ -363,6 +363,12 @@ instead of back to curl. The fact that FTP uses two connections makes it vulnerable in a way that is hard to avoid. +# Active FTP passes on the local IP address + +If you use curl/libcurl to do *active* FTP transfers, curl will pass on the +address of your local IP to the remote server - even when for example using a +SOCKS or HTTP proxy in between curl and the target server. + # Denial of Service A malicious server could cause libcurl to effectively hang by sending data From ad79612f97fadff3bfc4e36040fad0a825e07cd3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 00:14:44 +0100 Subject: [PATCH 282/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 44 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index f7bd00460be..7ba803f4996 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -8,15 +8,30 @@ curl and libcurl 8.6.1 This release includes the following changes: + o configure: add --disable-docs flag [16] This release includes the following bugfixes: - o cmdline-docs/Makefile: avoid using a fixed temp file name [5] + o ALTSVC.md: correct a typo [14] o asyn-thread: use wakeup_close to close the read descriptor [1] + o cmdline-docs/Makefile: avoid using a fixed temp file name [5] + o configure: do not link with nghttp3 unless necessary [7] + o connect.c: fix typo [17] + o cookie.md: provide an example sending a fixed cookie [13] + o docs: add missing slashes to SChannel client certificate documentation [11] + o docs: remove `mk-ca-bundle.1` from `man_MANS` [21] + o form-string.md: correct the example [4] + o ftp: treat a 226 arriving before data as a signal to read data [19] + o HTTP/2: write response directly [12] + o libcurl-security.md: Active FTP passes on the local IP address [6] + o md4: include strdup.h for the memdup proto [10] o ntml_wb: fix buffer type typo [2] + o openssl-quic: check on Windows that socket conv to int is possible [8] + o OS400: avoid using awk in the build scripts [20] + o proxy1.0.md: fix example [15] + o sendf: ignore response body to HEAD [18] + o tool_cb_hdr: only parse etag + content-disposition for 2xx [9] o tool_operate: do not set CURLOPT_QUICK_EXIT in debug builds [3] - o form-string.md: correct the example [4] - --- new entries are listed above this --- This release includes the following known bugs: @@ -31,8 +46,11 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - Boris Verkhovskiy, Dan Fandrich, Daniel Stenberg, Jon Rumsey, Stefan Eissing - (5 contributors) + Boris Verkhovskiy, Chris Webb, Dan Fandrich, Daniel Stenberg, + Dmitry Tretyakov, Erik Schnetter, Faraz Fallahi, Harry Sintonen, Jan Macku, + Joel Depooter, Jon Rumsey, Lars Kellogg-Stedman, Lukáš Zaoral, + Patrick Monnerat, Ryan Carsten Schmidt, Sergey Bronnikov, Stefan Eissing + (17 contributors) References to bug reports and discussions on issues: @@ -41,3 +59,19 @@ References to bug reports and discussions on issues: [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=12843 From 80944740e5bbc556dc9463513032fd0195629f6b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 00:00:35 +0100 Subject: [PATCH 283/509] docs: fix the --disable-docs for autotools Follow-up to 541321507e386 Closes #12870 --- docs/libcurl/Makefile.am | 6 ++++++ docs/libcurl/opts/Makefile.am | 5 +++++ 2 files changed, 11 insertions(+) diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 17b2bc80d04..1a70b967334 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -26,9 +26,11 @@ AUTOMAKE_OPTIONS = foreign no-dependencies SUBDIRS = opts +if BUILD_DOCS include Makefile.inc CURLPAGES = $(man_MANS:.3=.md) +endif m4macrodir = $(datadir)/aclocal dist_m4macro_DATA = libcurl.m4 @@ -39,6 +41,8 @@ nodist_MANS = $(man_MANS) EXTRA_DIST = $(CURLPAGES) ABI.md symbols-in-versions symbols.pl \ mksymbolsmanpage.pl CMakeLists.txt +if BUILD_DOCS + CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@ CD2 = $(CD2_$(V)) CD2_0 = @echo " RENDER " $@; @@ -52,3 +56,5 @@ libcurl-symbols.md: $(srcdir)/symbols-in-versions $(srcdir)/mksymbolsmanpage.pl .md.3: $(CD2)$(CD2NROFF) + +endif diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am index 42f9db4c5f8..111202ddd39 100644 --- a/docs/libcurl/opts/Makefile.am +++ b/docs/libcurl/opts/Makefile.am @@ -24,14 +24,18 @@ AUTOMAKE_OPTIONS = foreign no-dependencies +if BUILD_DOCS include Makefile.inc CURLPAGES = $(man_MANS:.3=.md) +endif CLEANFILES = $(man_MANS) nodist_MANS = $(man_MANS) EXTRA_DIST = $(CURLPAGES) CMakeLists.txt +if BUILD_DOCS + CD2NROFF = $(top_srcdir)/scripts/cd2nroff $< >$@ CD2 = $(CD2_$(V)) CD2_0 = @echo " RENDER " $@; @@ -42,3 +46,4 @@ SUFFIXES = .3 .md .md.3: $(CD2)$(CD2NROFF) +endif From d94733b4478a08a9ae9f9e60a1ee9148a867f6c5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 23:23:56 +0100 Subject: [PATCH 284/509] docs: make curldown do angle brackets like markdown Make sure we use \< and \> in markdown all over so that it renders correctly, on GitHub and elsewhere. cd2nroff now outputs a warning if it finds an unescaled angle bracket. Ref: #12854 Closes #12869 --- docs/CURLDOWN.md | 5 ++++ docs/libcurl/curl_easy_perform.md | 6 ++--- docs/libcurl/curl_easy_setopt.md | 8 +++---- docs/libcurl/curl_formadd.md | 5 ++-- docs/libcurl/curl_global_init_mem.md | 2 +- docs/libcurl/curl_share_cleanup.md | 6 ++--- docs/libcurl/curl_share_setopt.md | 4 ++-- docs/libcurl/curl_version_info.md | 4 ++-- docs/libcurl/curl_ws_send.md | 4 ++-- docs/libcurl/libcurl-errors.md | 4 ++-- docs/libcurl/libcurl-tutorial.md | 2 +- docs/libcurl/libcurl-url.md | 2 +- docs/libcurl/libcurl-ws.md | 2 +- docs/libcurl/opts/CURLOPT_FAILONERROR.md | 2 +- .../opts/CURLOPT_KEEP_SENDING_ON_ERROR.md | 2 +- docs/libcurl/opts/CURLOPT_MAIL_AUTH.md | 8 +++---- docs/libcurl/opts/CURLOPT_MAIL_FROM.md | 2 +- docs/libcurl/opts/CURLOPT_MAIL_RCPT.md | 13 +++++------ docs/libcurl/opts/CURLOPT_NETRC.md | 12 +++++----- .../opts/CURLOPT_PROXY_TLS13_CIPHERS.md | 2 +- docs/libcurl/opts/CURLOPT_QUOTE.md | 4 ++-- docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md | 4 ++-- docs/libcurl/opts/CURLOPT_SSLCERT.md | 23 ++++++++++--------- docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md | 6 ++--- docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md | 2 +- scripts/cd2nroff | 12 +++++++--- 26 files changed, 78 insertions(+), 68 deletions(-) diff --git a/docs/CURLDOWN.md b/docs/CURLDOWN.md index 2e89eed6a83..1eb3d8f4813 100644 --- a/docs/CURLDOWN.md +++ b/docs/CURLDOWN.md @@ -115,6 +115,11 @@ When generating the nroff output, the tooling will remove 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)` will automatically be rendered using italics in the output without having to enclose it with asterisks. This helps ensuring that diff --git a/docs/libcurl/curl_easy_perform.md b/docs/libcurl/curl_easy_perform.md index ff65a82ee7b..4f0989b9b6a 100644 --- a/docs/libcurl/curl_easy_perform.md +++ b/docs/libcurl/curl_easy_perform.md @@ -78,6 +78,6 @@ Always # RETURN VALUE CURLE_OK (0) means everything was OK, non-zero means an error occurred as -** defines - see libcurl-errors(3). If the CURLOPT_ERRORBUFFER(3) -was set with curl_easy_setopt(3) there is a readable error message stored in -the error buffer when non-zero is returned. +*\* defines - see libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) +was set with curl_easy_setopt(3) there is an error message stored in the error +buffer when non-zero is returned. diff --git a/docs/libcurl/curl_easy_setopt.md b/docs/libcurl/curl_easy_setopt.md index 5724b09cb10..76404ed2438 100644 --- a/docs/libcurl/curl_easy_setopt.md +++ b/docs/libcurl/curl_easy_setopt.md @@ -267,7 +267,7 @@ Fail on HTTP 4xx errors. CURLOPT_FAILONERROR(3) ## CURLOPT_KEEP_SENDING_ON_ERROR -Keep sending on HTTP >= 300 errors. CURLOPT_KEEP_SENDING_ON_ERROR(3) +Keep sending on HTTP \>= 300 errors. CURLOPT_KEEP_SENDING_ON_ERROR(3) # NETWORK OPTIONS @@ -826,7 +826,7 @@ Client CSEQ number. See CURLOPT_RTSP_CLIENT_CSEQ(3) ## CURLOPT_RTSP_SERVER_CSEQ -CSEQ number for RTSP Server->Client request. See CURLOPT_RTSP_SERVER_CSEQ(3) +CSEQ number for RTSP Server-\>Client request. See CURLOPT_RTSP_SERVER_CSEQ(3) ## CURLOPT_AWS_SIGV4 @@ -1366,8 +1366,8 @@ Always # RETURN VALUE *CURLE_OK* (zero) means that the option was set properly, non-zero means an -error occurred as ** defines. See the libcurl-errors(3) man page -for the full list with descriptions. +error occurred as *\* defines. See the libcurl-errors(3) man +page for the full list with descriptions. Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise curl_easy_setopt(3) returns **CURLE_BAD_FUNCTION_ARGUMENT** (added in 7.65.0). diff --git a/docs/libcurl/curl_formadd.md b/docs/libcurl/curl_formadd.md index 3793df8fa37..479f7f626c3 100644 --- a/docs/libcurl/curl_formadd.md +++ b/docs/libcurl/curl_formadd.md @@ -308,6 +308,5 @@ double quotes in field and file names are now escaped before transmission. # RETURN VALUE -0 means everything was OK, non-zero means an error occurred corresponding -to a CURL_FORMADD_* constant defined in -** +0 means everything was OK, non-zero means an error occurred corresponding to a +CURL_FORMADD_* constant defined in *\*. diff --git a/docs/libcurl/curl_global_init_mem.md b/docs/libcurl/curl_global_init_mem.md index 3bf468f18d5..96af23b05f7 100644 --- a/docs/libcurl/curl_global_init_mem.md +++ b/docs/libcurl/curl_global_init_mem.md @@ -92,4 +92,4 @@ Added in 7.12.0 # RETURN VALUE CURLE_OK (0) means everything was OK, non-zero means an error occurred as -** defines - see libcurl-errors(3). +*\* defines - see libcurl-errors(3). diff --git a/docs/libcurl/curl_share_cleanup.md b/docs/libcurl/curl_share_cleanup.md index 59126a145bc..f4220566da3 100644 --- a/docs/libcurl/curl_share_cleanup.md +++ b/docs/libcurl/curl_share_cleanup.md @@ -49,6 +49,6 @@ Added in 7.10 # RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred as ** defines. See the libcurl-errors(3) -man page for the full list with descriptions. If an error occurs, then the -share object is not deleted. +error occurred as *\* defines. See the libcurl-errors(3) man +page for the full list with descriptions. If an error occurs, then the share +object is not deleted. diff --git a/docs/libcurl/curl_share_setopt.md b/docs/libcurl/curl_share_setopt.md index 5ab95503be0..8caaaea9ad4 100644 --- a/docs/libcurl/curl_share_setopt.md +++ b/docs/libcurl/curl_share_setopt.md @@ -67,5 +67,5 @@ Added in 7.10 # RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non-zero means an -error occurred as ** defines. See the libcurl-errors(3) -man page for the full list with descriptions. +error occurred as *\* defines. See the libcurl-errors(3) man +page for the full list with descriptions. diff --git a/docs/libcurl/curl_version_info.md b/docs/libcurl/curl_version_info.md index 9fc764e1847..45e46a1b9e6 100644 --- a/docs/libcurl/curl_version_info.md +++ b/docs/libcurl/curl_version_info.md @@ -112,8 +112,8 @@ that you have a matching struct for in the header, as you tell libcurl your *version* is just an ascii string for the libcurl version. -*version_num* is a 24 bit number created like this: <8 bits major number> -| <8 bits minor number> | <8 bits patch number>. Version 7.9.8 is therefore +*version_num* is a 24 bit number created like this: \<8 bits major number\> | +\<8 bits minor number\> | \<8 bits patch number\>. Version 7.9.8 is therefore returned as 0x070908. *host* is an ascii string showing what host information that this libcurl diff --git a/docs/libcurl/curl_ws_send.md b/docs/libcurl/curl_ws_send.md index a5a056c9da8..e521ff20aa6 100644 --- a/docs/libcurl/curl_ws_send.md +++ b/docs/libcurl/curl_ws_send.md @@ -116,5 +116,5 @@ Added in 7.86.0. # RETURN VALUE *CURLE_OK* (zero) means that the data was sent properly, non-zero means an -error occurred as ** defines. See the libcurl-errors(3) -man page for the full list with descriptions. +error occurred as *\* defines. See the libcurl-errors(3) man +page for the full list with descriptions. diff --git a/docs/libcurl/libcurl-errors.md b/docs/libcurl/libcurl-errors.md index 2a7c8bf715f..eb75753b0fe 100644 --- a/docs/libcurl/libcurl-errors.md +++ b/docs/libcurl/libcurl-errors.md @@ -145,8 +145,8 @@ indicated unsuccessful completion of the command. ## CURLE_HTTP_RETURNED_ERROR (22) -This is returned if CURLOPT_FAILONERROR(3) is set TRUE and the HTTP -server returns an error code that is >= 400. +This is returned if CURLOPT_FAILONERROR(3) is set TRUE and the HTTP server +returns an error code that is \>= 400. ## CURLE_WRITE_ERROR (23) diff --git a/docs/libcurl/libcurl-tutorial.md b/docs/libcurl/libcurl-tutorial.md index 2bf5f05474a..de110bb30f7 100644 --- a/docs/libcurl/libcurl-tutorial.md +++ b/docs/libcurl/libcurl-tutorial.md @@ -461,7 +461,7 @@ proper way. This chapter thus includes examples using both different versions of HTTP POST that libcurl supports. The first version is the simple POST, the most common version, that most HTML -pages using the tag uses. We provide a pointer to the data and tell +pages using the \ tag uses. We provide a pointer to the data and tell libcurl to post it all to the remote site: ~~~c diff --git a/docs/libcurl/libcurl-url.md b/docs/libcurl/libcurl-url.md index a2948001aef..c7a9ca2bb04 100644 --- a/docs/libcurl/libcurl-url.md +++ b/docs/libcurl/libcurl-url.md @@ -24,7 +24,7 @@ The URL interface provides functions for parsing and generating URLs. # INCLUDE -You still only include in your code. +You still only include \ in your code. # CREATE diff --git a/docs/libcurl/libcurl-ws.md b/docs/libcurl/libcurl-ws.md index 40f7c039c60..5ba05d8faef 100644 --- a/docs/libcurl/libcurl-ws.md +++ b/docs/libcurl/libcurl-ws.md @@ -25,7 +25,7 @@ data. # INCLUDE -You still only include in your code. +You still only include \ in your code. # SETUP diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.md b/docs/libcurl/opts/CURLOPT_FAILONERROR.md index 7ea5cedc689..5eedf840f5b 100644 --- a/docs/libcurl/opts/CURLOPT_FAILONERROR.md +++ b/docs/libcurl/opts/CURLOPT_FAILONERROR.md @@ -12,7 +12,7 @@ See-also: # NAME -CURLOPT_FAILONERROR - request failure on HTTP response >= 400 +CURLOPT_FAILONERROR - request failure on HTTP response \>= 400 # SYNOPSIS diff --git a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md index 090a8fc2d20..e8471957abb 100644 --- a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md +++ b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md @@ -12,7 +12,7 @@ See-also: # NAME -CURLOPT_KEEP_SENDING_ON_ERROR - keep sending on early HTTP response >= 300 +CURLOPT_KEEP_SENDING_ON_ERROR - keep sending on early HTTP response \>= 300 # SYNOPSIS diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md index a5dbc7d79f6..172656defac 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md @@ -34,10 +34,10 @@ server acting in such an environment. If the application is operating as such and the AUTH address is not known or is invalid, then an empty string should be used for this parameter. -Unlike CURLOPT_MAIL_FROM(3) and CURLOPT_MAIL_RCPT(3), the address -should not be specified within a pair of angled brackets (<>). However, if an -empty string is used then a pair of brackets are sent by libcurl as required -by RFC 2554. +Unlike CURLOPT_MAIL_FROM(3) and CURLOPT_MAIL_RCPT(3), the address should not +be specified within a pair of angled brackets (\<\>). However, if an empty +string is used then a pair of brackets are sent by libcurl as required by RFC +2554. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md index c4984b056a2..5e83dbab3be 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md @@ -26,7 +26,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_FROM, char *from); Pass a pointer to a null-terminated string as parameter. This should be used to specify the sender's email address when sending SMTP mail with libcurl. -An originator email address should be specified with angled brackets (<>) +An originator email address should be specified with angled brackets (\<\>) around it, which if not specified are added automatically. If this parameter is not specified then an empty address is sent to the SMTP diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md index ce57074f01d..e1b3f1555a6 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md @@ -26,13 +26,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT, Pass a pointer to a linked list of recipients to pass to the server in your SMTP mail request. The linked list should be a fully valid list of -**struct curl_slist** structs properly filled in. Use -curl_slist_append(3) to create the list and curl_slist_free_all(3) -to clean up an entire list. +**struct curl_slist** structs properly filled in. Use curl_slist_append(3) to +create the list and curl_slist_free_all(3) to clean up an entire list. When performing a mail transfer, each recipient should be specified within a -pair of angled brackets (<>), however, should you not use an angled bracket as -the first character libcurl assumes you provided a single email address and +pair of angled brackets (\<\>), however, should you not use an angled bracket +as the first character libcurl assumes you provided a single email address and encloses that address within brackets for you. When performing an address verification (**VRFY** command), each recipient @@ -40,8 +39,8 @@ should be specified as the user name or user name and domain (as per Section 3.5 of RFC 5321). When performing a mailing list expand (**EXPN** command), each recipient -should be specified using the mailing list name, such as "Friends" or -"London-Office". +should be specified using the mailing list name, such as `Friends` or +`London-Office`. # DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_NETRC.md b/docs/libcurl/opts/CURLOPT_NETRC.md index 89a55b4d9b3..d5acdd5df37 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.md +++ b/docs/libcurl/opts/CURLOPT_NETRC.md @@ -76,7 +76,7 @@ and end with double quotes and support the escaped special letters ", n, r, and t. Quoted strings are the only way a space character can be used in a user name or password. -## machine +## machine \ Provides credentials for a host called **name**. libcurl searches the .netrc file for a machine token that matches the hostname specified in the URL. Once @@ -85,25 +85,25 @@ file is reached or another "machine" is encountered. ## default -This is the same as "machine" name except that default matches any name. There +This is the same as machine name except that default matches any name. There can be only one default token, and it must be after all machine tokens. To provide a default anonymous login for hosts that are not otherwise matched, add a line similar to this in the end: - default login anonymous password user@domain + default login anonymous password user@domain -## login +## login \ The user name string for the remote machine. -## password +## password \ Supply a password. If this token is present, curl supplies the specified string if the remote server requires a password as part of the login process. Note that if this token is present in the .netrc file you really should make sure the file is not readable by anyone besides the user. -## macdef +## macdef \ Define a macro. This feature is not supported by libcurl. In order for the rest of the .netrc to still work fine, libcurl properly skips every definition diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md index f3c5448f0a5..fd59de469e9 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md @@ -71,7 +71,7 @@ int main(void) # AVAILABILITY Added in 7.61.0. -Available when built with OpenSSL >= 1.1.1. +Available when built with OpenSSL \>= 1.1.1. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.md b/docs/libcurl/opts/CURLOPT_QUOTE.md index f57b45eec11..9ba912ba655 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.md +++ b/docs/libcurl/opts/CURLOPT_QUOTE.md @@ -57,7 +57,7 @@ path. e.g. rename with sftp using a quote command like this: ## 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 +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 @@ -89,7 +89,7 @@ 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 can be all sorts of date strings, see 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 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md index 521084388aa..819ea07d48b 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md @@ -24,8 +24,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SERVER_CSEQ, long cseq); # DESCRIPTION -Pass a long to set the CSEQ number to expect for the next RTSP Server->Client -request. **NOTE**: this feature (listening for Server requests) is +Pass a long to set the CSEQ number to expect for the next RTSP Server to +Client request. **NOTE**: this feature (listening for Server requests) is unimplemented. # DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.md b/docs/libcurl/opts/CURLOPT_SSLCERT.md index 8400e6e2a88..e1450835313 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.md @@ -25,25 +25,26 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT, char *cert); # DESCRIPTION Pass a pointer to a null-terminated string as parameter. The string should be -the filename of your client certificate. The default format is "P12" on Secure -Transport and "PEM" on other engines, and can be changed with +the filename of your client certificate. The default format is `P12` on Secure +Transport and `PEM` on other engines, and can be changed with CURLOPT_SSLCERTTYPE(3). With Secure Transport, this can also be the nickname of the certificate you wish to authenticate with as it is named in the security database. If you want -to use a file from the current directory, please precede it with "./" prefix, +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 can be specified by a path expression to a certificate store. (You can import *PFX* to a store first). You can use -"\\\\" to refer to a certificate in the -system certificates store, for example, -**"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"**. The 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**, -**LocalMachineEnterprise**. Schannel also support P12 certificate file, with -the string "P12" specified with CURLOPT_SSLCERTTYPE(3). +"\\\\\\\" to refer to a certificate +in the system certificates store, for example, +**"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"**. The 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**, **LocalMachineEnterprise**. Schannel also support +P12 certificate file, with the string `P12` specified with +CURLOPT_SSLCERTTYPE(3). When using a client certificate, you most likely also need to provide a private key with CURLOPT_SSLKEY(3). diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md index e1db12ed8d9..5fa6348381f 100644 --- a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md @@ -25,9 +25,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TELNETOPTIONS, # DESCRIPTION Provide a pointer to a curl_slist with variables to pass to the telnet -negotiations. The variables should be in the format . libcurl -supports the options **TTYPE**, **XDISPLOC** and **NEW_ENV**. See the -TELNET standard for details. +negotiations. The variables should be in the format \. libcurl +supports the options **TTYPE**, **XDISPLOC** and **NEW_ENV**. See the TELNET +standard for details. # DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md index add1f2f8ea5..d7c7a35106d 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md @@ -71,7 +71,7 @@ int main(void) # AVAILABILITY -Added in 7.61.0 for OpenSSL. Available when built with OpenSSL >= 1.1.1. +Added in 7.61.0 for OpenSSL. Available when built with OpenSSL \>= 1.1.1. Added in 7.85.0 for Schannel. diff --git a/scripts/cd2nroff b/scripts/cd2nroff index 17a83b49cbb..decaeca0a81 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -243,11 +243,20 @@ sub single { next; } + # remove single line HTML comments + $d =~ s///g; + # **bold** $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g; # *italics* $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g; + if($d =~ /[^\\][\<\>]/) { + print STDERR "$f:$line:1:WARN: un-escaped < or > used\n"; + } + # convert backslash-'<' or '> to just the second character + $d =~ s/\\([<<])/$1/g; + # mentions of curl symbols with man pages use italics by default $d =~ s/((lib|)curl([^ ]*\(3\)))/\\fI$1\\fP/gi; @@ -307,9 +316,6 @@ sub single { $blankline = 0; $header = 0; - # remove single line HTML comments - $d =~ s///g; - # quote minuses in the output $d =~ s/([^\\])-/$1\\-/g; # replace single quotes From 8050761e1a5288721215636ad81d8eb301cc98a4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 08:58:52 +0100 Subject: [PATCH 285/509] TODO: Support latest rustls Closes #12737 Closes #12874 --- docs/TODO | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/TODO b/docs/TODO index 162944360d9..045e5ed9783 100644 --- a/docs/TODO +++ b/docs/TODO @@ -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 Support latest rustls 14. GnuTLS 14.2 check connection @@ -922,6 +923,14 @@ https://datatracker.ietf.org/doc/html/rfc7685 https://github.com/curl/curl/issues/2299 +13.15 Support latest rustls + + The rustls backend does not build with the latest rustls-ffi version due to + API changes. Taking this bump should be a first step towards fixing the + remaining issues that still keeps the rustls backend experimental in curl. + + See https://github.com/curl/curl/issues/12737 + 14. GnuTLS 14.2 check connection From 174c89ec3f88ca710aa19de9b89371b55ee0e2d4 Mon Sep 17 00:00:00 2001 From: Peter Krefting Date: Fri, 2 Feb 2024 23:22:32 +0100 Subject: [PATCH 286/509] version: allow building with ancient libpsl The psl_check_version_number() API was added in libpsl 0.11.0. CentOS 7 ships with version 0.7.0 which lacks this API. Revert to using the older versioning API if we detect an old libpsl version. Follow-up to 72bd88adde0e8cf6e63644a7d6df1da01a399db4 Bug: https://curl.se/mail/archive-2024-02/0004.html Reported-by: Scott Mutter Closes #12872 --- lib/version.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lib/version.c b/lib/version.c index 01c2a315e5c..88f3696dec7 100644 --- a/lib/version.c +++ b/lib/version.c @@ -212,9 +212,15 @@ char *curl_version(void) #ifdef USE_LIBPSL { +#if defined(PSL_VERSION_MAJOR) && (PSL_VERSION_MAJOR > 0 || \ + PSL_VERSION_MINOR >= 11) int num = psl_check_version_number(0); msnprintf(psl_version, sizeof(psl_version), "libpsl/%d.%d.%d", num >> 16, (num >> 8) & 0xff, num & 0xff); +#else + msnprintf(psl_version, sizeof(psl_version), "libpsl/%s", + psl_get_version()); +#endif src[i++] = psl_version; } #endif From 4f794558777395608972a9b212526aa5aa616537 Mon Sep 17 00:00:00 2001 From: Jiawen Geng Date: Sun, 4 Feb 2024 17:19:46 +0800 Subject: [PATCH 287/509] docs: add necessary setup for nghttp3 Now nghttp3 has submodules https://github.com/ngtcp2/nghttp3/blob/main/.gitmodules Closes #12859 --- docs/HTTP3.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 851a0c46849..b09fb94e57f 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -58,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 From c177e1944c4e1e4ffac10856121a05830ccb6bce Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 1 Feb 2024 10:51:45 +0100 Subject: [PATCH 288/509] https-proxy: use IP address and cert with ip in alt names - improve info logging when peer verification fails to indicate if DNS name or ip address has been tried to match - add test case for contacting https proxy with ip address - add pytest env check on loaded credentials and re-issue when they are no longer valid - disable proxy ip address test for bearssl, since not supported there Ref: #12831 Closes #12838 --- lib/vtls/openssl.c | 6 ++++-- tests/http/test_10_proxy.py | 20 ++++++++++++++++++-- tests/http/testenv/certs.py | 23 +++++++++++++++++++---- tests/http/testenv/curl.py | 12 +++++++----- tests/http/testenv/env.py | 3 ++- 5 files changed, 50 insertions(+), 14 deletions(-) diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c index 8d6087022b3..c8ec76a1d13 100644 --- a/lib/vtls/openssl.c +++ b/lib/vtls/openssl.c @@ -2242,9 +2242,11 @@ CURLcode Curl_ossl_verifyhost(struct Curl_easy *data, struct connectdata *conn, /* an alternative name matched */ ; else if(dNSName || iPAddress) { - infof(data, " subjectAltName does not match %s", peer->dispname); + infof(data, " subjectAltName does not match %s %s", + peer->is_ip_address? "ip address" : "host name", peer->dispname); failf(data, "SSL: no alternative certificate subject name matches " - "target host name '%s'", peer->dispname); + "target %s '%s'", + peer->is_ip_address? "ip address" : "host name", peer->dispname); result = CURLE_PEER_FAILED_VERIFICATION; } else { diff --git a/tests/http/test_10_proxy.py b/tests/http/test_10_proxy.py index 0e4060b67c4..ad3a5990f1c 100644 --- a/tests/http/test_10_proxy.py +++ b/tests/http/test_10_proxy.py @@ -70,8 +70,7 @@ def test_10_01_proxy_http(self, env: Env, httpd, repeat): @pytest.mark.skipif(condition=not Env.curl_has_feature('HTTPS-proxy'), reason='curl lacks HTTPS-proxy support') @pytest.mark.parametrize("proto", ['http/1.1', 'h2']) - @pytest.mark.skipif(condition=not Env.have_nghttpx(), reason="no nghttpx available") - def test_10_02_proxys_down(self, env: Env, httpd, nghttpx_fwd, proto, repeat): + def test_10_02_proxys_down(self, env: Env, httpd, proto, repeat): if proto == 'h2' and not env.curl_uses_lib('nghttp2'): pytest.skip('only supported with nghttp2') curl = CurlClient(env=env) @@ -349,3 +348,20 @@ def test_10_13_noreuse_https(self, env: Env, httpd, nghttpx_fwd, tunnel, repeat) extra_args=x2_args) r2.check_response(count=2, http_status=200) assert r2.total_connects == 2 + + # download via https: proxy (no tunnel) using IP address + @pytest.mark.skipif(condition=not Env.curl_has_feature('HTTPS-proxy'), + reason='curl lacks HTTPS-proxy support') + @pytest.mark.skipif(condition=Env.curl_uses_lib('bearssl'), reason="ip address cert verification not supported") + @pytest.mark.parametrize("proto", ['http/1.1', 'h2']) + def test_10_14_proxys_ip_addr(self, env: Env, httpd, proto, repeat): + if proto == 'h2' and not env.curl_uses_lib('nghttp2'): + pytest.skip('only supported with nghttp2') + curl = CurlClient(env=env) + url = f'http://localhost:{env.http_port}/data.json' + xargs = curl.get_proxy_args(proto=proto, use_ip=True) + r = curl.http_download(urls=[url], alpn_proto='http/1.1', with_stats=True, + extra_args=xargs) + r.check_response(count=1, http_status=200, + protocol='HTTP/2' if proto == 'h2' else 'HTTP/1.1') + diff --git a/tests/http/testenv/certs.py b/tests/http/testenv/certs.py index f575a741294..cdbfed1fc2e 100644 --- a/tests/http/testenv/certs.py +++ b/tests/http/testenv/certs.py @@ -24,6 +24,7 @@ # ########################################################################### # +import ipaddress import os import re from datetime import timedelta, datetime @@ -79,6 +80,7 @@ def __init__(self, name: Optional[str] = None, valid_from: timedelta = timedelta(days=-1), valid_to: timedelta = timedelta(days=89), client: bool = False, + check_valid: bool = True, sub_specs: Optional[List['CertificateSpec']] = None): self._name = name self.domains = domains @@ -89,6 +91,7 @@ def __init__(self, name: Optional[str] = None, self.valid_from = valid_from self.valid_to = valid_to self.sub_specs = sub_specs + self.check_valid = check_valid @property def name(self) -> Optional[str]: @@ -202,7 +205,8 @@ def issue_cert(self, spec: CertificateSpec, creds = None if self._store: creds = self._store.load_credentials( - name=spec.name, key_type=key_type, single_file=spec.single_file, issuer=self) + name=spec.name, key_type=key_type, single_file=spec.single_file, + issuer=self, check_valid=spec.check_valid) if creds is None: creds = TestCA.create_credentials(spec=spec, issuer=self, key_type=key_type, valid_from=spec.valid_from, valid_to=spec.valid_to) @@ -303,13 +307,18 @@ def load_pem_pkey(self, fpath: str): def load_credentials(self, name: str, key_type=None, single_file: bool = False, - issuer: Optional[Credentials] = None): + issuer: Optional[Credentials] = None, + check_valid: bool = False): cert_file = self.get_cert_file(name=name, key_type=key_type) pkey_file = cert_file if single_file else self.get_pkey_file(name=name, key_type=key_type) comb_file = self.get_combined_file(name=name, key_type=key_type) if os.path.isfile(cert_file) and os.path.isfile(pkey_file): cert = self.load_pem_cert(cert_file) pkey = self.load_pem_pkey(pkey_file) + if check_valid and \ + ((cert.not_valid_after < datetime.now()) or + (cert.not_valid_before > datetime.now())): + return None creds = Credentials(name=name, cert=cert, pkey=pkey, issuer=issuer) creds.set_store(self) creds.set_files(cert_file, pkey_file, comb_file) @@ -426,6 +435,13 @@ def _add_ca_usages(csr: Any) -> Any: @staticmethod def _add_leaf_usages(csr: Any, domains: List[str], issuer: Credentials) -> Any: + names = [] + for name in domains: + try: + names.append(x509.IPAddress(ipaddress.ip_address(name))) + except: + names.append(x509.DNSName(name)) + return csr.add_extension( x509.BasicConstraints(ca=False, path_length=None), critical=True, @@ -435,8 +451,7 @@ def _add_leaf_usages(csr: Any, domains: List[str], issuer: Credentials) -> Any: x509.SubjectKeyIdentifier).value), critical=False ).add_extension( - x509.SubjectAlternativeName([x509.DNSName(domain) for domain in domains]), - critical=True, + x509.SubjectAlternativeName(names), critical=True, ).add_extension( x509.ExtendedKeyUsage([ ExtendedKeyUsageOID.SERVER_AUTH, diff --git a/tests/http/testenv/curl.py b/tests/http/testenv/curl.py index 45fef7fd949..bfd6fdefc70 100644 --- a/tests/http/testenv/curl.py +++ b/tests/http/testenv/curl.py @@ -393,20 +393,22 @@ def _mkpath(self, path): return os.makedirs(path) def get_proxy_args(self, proto: str = 'http/1.1', - proxys: bool = True, tunnel: bool = False): + proxys: bool = True, tunnel: bool = False, + use_ip: bool = False): + proxy_name = '127.0.0.1' if use_ip else self.env.proxy_domain if proxys: pport = self.env.pts_port(proto) if tunnel else self.env.proxys_port xargs = [ - '--proxy', f'https://{self.env.proxy_domain}:{pport}/', - '--resolve', f'{self.env.proxy_domain}:{pport}:127.0.0.1', + '--proxy', f'https://{proxy_name}:{pport}/', + '--resolve', f'{proxy_name}:{pport}:127.0.0.1', '--proxy-cacert', self.env.ca.cert_file, ] if proto == 'h2': xargs.append('--proxy-http2') else: xargs = [ - '--proxy', f'http://{self.env.proxy_domain}:{self.env.proxy_port}/', - '--resolve', f'{self.env.proxy_domain}:{self.env.proxy_port}:127.0.0.1', + '--proxy', f'http://{proxy_name}:{self.env.proxy_port}/', + '--resolve', f'{proxy_name}:{self.env.proxy_port}:127.0.0.1', ] if tunnel: xargs.append('--proxytunnel') diff --git a/tests/http/testenv/env.py b/tests/http/testenv/env.py index 7c5f7e31a0d..29f9726f7bd 100644 --- a/tests/http/testenv/env.py +++ b/tests/http/testenv/env.py @@ -31,6 +31,7 @@ import subprocess import sys from configparser import ConfigParser, ExtendedInterpolation +from datetime import timedelta from typing import Optional import pytest @@ -133,7 +134,7 @@ def __init__(self): self.cert_specs = [ CertificateSpec(domains=[self.domain1, 'localhost'], key_type='rsa2048'), CertificateSpec(domains=[self.domain2], key_type='rsa2048'), - CertificateSpec(domains=[self.proxy_domain], key_type='rsa2048'), + CertificateSpec(domains=[self.proxy_domain, '127.0.0.1'], key_type='rsa2048'), CertificateSpec(name="clientsX", sub_specs=[ CertificateSpec(name="user1", client=True), ]), From 755b31da10dacca94e0d00029a7306e09e3fe913 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 09:29:17 +0100 Subject: [PATCH 289/509] docs: add mk-ca-bundle.1 to dist ... which also makes it get built. But don't build this or curl-config.1 if build docs is disabled. Closes #12875 --- docs/Makefile.am | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 94cb8bc1d87..d9bdd176cce 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -24,11 +24,18 @@ AUTOMAKE_OPTIONS = foreign no-dependencies +if BUILD_DOCS +# if we disable man page building, ignore these +MK_CA_DOCS = mk-ca-bundle.1 +CURLCONF_DOCS = curl-config.1 +endif + + # 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 +noinst_man_MANS = curl.1 $(MK_CA_DOCS) +dist_man_MANS = $(CURLCONF_DOCS) $(MK_CA_DOCS) CURLPAGES = curl-config.md mk-ca-bundle.md # Build targets in this file (.) before cmdline-opts to ensure that @@ -36,7 +43,7 @@ CURLPAGES = curl-config.md mk-ca-bundle.md SUBDIRS = . cmdline-opts libcurl DIST_SUBDIRS = $(SUBDIRS) examples -CLEANFILES = $(man_MANS) curl.1 curl-config.1 mk-ca-bundle.1 +CLEANFILES = $(man_MANS) curl.1 $(CURLCONF_DOCS) $(MK_CA_DOCS) nodist_MANS = $(CLEANFILES) EXTRA_DIST = \ From a5c86203be4a2421f33bc50193107736ee26d0a4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 11:20:30 +0100 Subject: [PATCH 290/509] header.md: remove backslash, make nicer markdown - remove a leftover backslash before a dash - use backticks for "code" strings Closes #12877 --- docs/cmdline-opts/header.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cmdline-opts/header.md b/docs/cmdline-opts/header.md index 835ee61c879..13ca4cb3221 100644 --- a/docs/cmdline-opts/header.md +++ b/docs/cmdline-opts/header.md @@ -34,9 +34,9 @@ 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:". +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 @@ -49,7 +49,7 @@ 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:" +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 From bdb0bf4782e5b6912d283b0c3c1538d7e5eae06b Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 6 Feb 2024 13:04:24 +0000 Subject: [PATCH 291/509] cmake: fix function description in comment [ci skip] Closes #12879 --- CMake/Utilities.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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) From dc3eb678da50c4feba913aa6a075ecaec269141a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 23:43:41 +0100 Subject: [PATCH 292/509] badwords: use hostname, not host name and username, filename - consistently. Fixed the patterns in badwords.txt to catch these. Closes #12888 --- .github/scripts/badwords.txt | 11 +++++---- docs/CHECKSRC.md | 2 +- docs/FEATURES.md | 2 +- docs/HSTS.md | 2 +- docs/MANUAL.md | 10 ++++---- docs/TheArtOfHttpScripting.md | 2 +- docs/URL-SYNTAX.md | 6 ++--- docs/libcurl/curl_easy_setopt.md | 12 +++++----- docs/libcurl/curl_formadd.md | 12 +++++----- docs/libcurl/curl_mime_filename.md | 2 +- docs/libcurl/curl_mime_type.md | 2 +- docs/libcurl/curl_url_get.md | 8 +++---- docs/libcurl/libcurl-env.md | 8 +++---- docs/libcurl/libcurl-security.md | 24 +++++++++---------- docs/libcurl/libcurl-tutorial.md | 20 ++++++++-------- docs/libcurl/opts/CURLMOPT_PUSHDATA.md | 2 +- docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_ALTSVC.md | 2 +- .../opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md | 2 +- .../libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md | 3 +-- docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md | 2 +- docs/libcurl/opts/CURLOPT_HSTS.md | 4 ++-- docs/libcurl/opts/CURLOPT_HTTPAUTH.md | 2 +- docs/libcurl/opts/CURLOPT_IPRESOLVE.md | 2 +- docs/libcurl/opts/CURLOPT_MAIL_RCPT.md | 2 +- docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md | 2 +- docs/libcurl/opts/CURLOPT_NETRC.md | 20 ++++++++-------- docs/libcurl/opts/CURLOPT_NOPROXY.md | 9 ++++--- docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md | 6 ++--- docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md | 10 ++++---- .../opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md | 2 +- docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md | 2 +- docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md | 2 +- docs/libcurl/opts/CURLOPT_USERNAME.md | 13 +++++----- docs/libcurl/opts/CURLOPT_USERPWD.md | 15 ++++++------ docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md | 4 ++-- 37 files changed, 116 insertions(+), 117 deletions(-) diff --git a/.github/scripts/badwords.txt b/.github/scripts/badwords.txt index 0e6be76c6c0..216287f7fdf 100644 --- a/.github/scripts/badwords.txt +++ b/.github/scripts/badwords.txt @@ -23,14 +23,13 @@ isn't:is not a http: an http a ftp: an ftp url =URL -internet\W=Internet +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? -file name :filename \. So : Rewrite without "so" ? dir :directory you'd:you would @@ -38,8 +37,12 @@ you'll:you will can't:cannot that's:that is web page:webpage -host name\W:hostname -file name\W:filename +host name\b:hostname +host names\b:hostnames +file name\b:filename +file names\b:filenames +user name\b:username +user names\b:usernames didn't:did not doesn't:does not won't:will not diff --git a/docs/CHECKSRC.md b/docs/CHECKSRC.md index f73e7a8347a..0d6e58c1423 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 diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 4a589e1649e..bae38fb851e 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -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) diff --git a/docs/HSTS.md b/docs/HSTS.md index 5f0e6245971..d4e99044db3 100644 --- a/docs/HSTS.md +++ b/docs/HSTS.md @@ -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/MANUAL.md b/docs/MANUAL.md index e7b4bb7af79..04542b98753 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -824,17 +824,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 hostname 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 will not be done over +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. diff --git a/docs/TheArtOfHttpScripting.md b/docs/TheArtOfHttpScripting.md index 8607642f73c..0357e8c5d16 100644 --- a/docs/TheArtOfHttpScripting.md +++ b/docs/TheArtOfHttpScripting.md @@ -119,7 +119,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 diff --git a/docs/URL-SYNTAX.md b/docs/URL-SYNTAX.md index 011a32c3841..3ce2b64383b 100644 --- a/docs/URL-SYNTAX.md +++ b/docs/URL-SYNTAX.md @@ -147,7 +147,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 +184,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 @@ -357,7 +357,7 @@ file. If the path is omitted entirely then the directory listing for the root ## 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, diff --git a/docs/libcurl/curl_easy_setopt.md b/docs/libcurl/curl_easy_setopt.md index 76404ed2438..5e8313fae9a 100644 --- a/docs/libcurl/curl_easy_setopt.md +++ b/docs/libcurl/curl_easy_setopt.md @@ -435,15 +435,15 @@ Enable .netrc parsing. See CURLOPT_NETRC(3) ## CURLOPT_USERPWD -User name and password. See CURLOPT_USERPWD(3) +Username and password. See CURLOPT_USERPWD(3) ## CURLOPT_PROXYUSERPWD -Proxy user name and password. See CURLOPT_PROXYUSERPWD(3) +Proxy username and password. See CURLOPT_PROXYUSERPWD(3) ## CURLOPT_USERNAME -User name. See CURLOPT_USERNAME(3) +Username. See CURLOPT_USERNAME(3) ## CURLOPT_PASSWORD @@ -455,7 +455,7 @@ Login options. See CURLOPT_LOGIN_OPTIONS(3) ## CURLOPT_PROXYUSERNAME -Proxy user name. See CURLOPT_PROXYUSERNAME(3) +Proxy username. See CURLOPT_PROXYUSERNAME(3) ## CURLOPT_PROXYPASSWORD @@ -467,11 +467,11 @@ HTTP server authentication methods. See CURLOPT_HTTPAUTH(3) ## CURLOPT_TLSAUTH_USERNAME -TLS authentication user name. See CURLOPT_TLSAUTH_USERNAME(3) +TLS authentication username. See CURLOPT_TLSAUTH_USERNAME(3) ## CURLOPT_PROXY_TLSAUTH_USERNAME -Proxy TLS authentication user name. See CURLOPT_PROXY_TLSAUTH_USERNAME(3) +Proxy TLS authentication username. See CURLOPT_PROXY_TLSAUTH_USERNAME(3) ## CURLOPT_TLSAUTH_PASSWORD diff --git a/docs/libcurl/curl_formadd.md b/docs/libcurl/curl_formadd.md index 479f7f626c3..e2d1ad7f956 100644 --- a/docs/libcurl/curl_formadd.md +++ b/docs/libcurl/curl_formadd.md @@ -299,12 +299,12 @@ int main(void) # AVAILABILITY -Deprecated in 7.56.0. Before this release, field names were allowed to -contain zero-valued bytes. The pseudo-filename "-" to read stdin is -discouraged although still supported, but data is not read before being -actually sent: the effective data size can then not be automatically -determined, resulting in a chunked encoding transfer. Backslashes and -double quotes in field and file names are now escaped before transmission. +Deprecated in 7.56.0. Before this release, field names were allowed to contain +zero-valued bytes. The pseudo-filename "-" to read stdin is discouraged +although still supported, but data is not read before being actually sent: the +effective data size can then not be automatically determined, resulting in a +chunked encoding transfer. Backslashes and double quotes in field and +filenames are now escaped before transmission. # RETURN VALUE diff --git a/docs/libcurl/curl_mime_filename.md b/docs/libcurl/curl_mime_filename.md index 4fb6b0d5161..76c045bcb66 100644 --- a/docs/libcurl/curl_mime_filename.md +++ b/docs/libcurl/curl_mime_filename.md @@ -12,7 +12,7 @@ See-also: # NAME -curl_mime_filename - set a mime part's remote file name +curl_mime_filename - set a mime part's remote filename # SYNOPSIS diff --git a/docs/libcurl/curl_mime_type.md b/docs/libcurl/curl_mime_type.md index 3970ad88e29..cdb09f8a214 100644 --- a/docs/libcurl/curl_mime_type.md +++ b/docs/libcurl/curl_mime_type.md @@ -42,7 +42,7 @@ a default mime type is determined by the context: - application/form-data for an HTTP form post. -- If a remote filename is set, the mime type is taken from the file name +- If a remote filename is set, the mime type is taken from the filename extension, or application/octet-stream by default. - For a multipart part, multipart/mixed. diff --git a/docs/libcurl/curl_url_get.md b/docs/libcurl/curl_url_get.md index 2ea42181861..810e504c359 100644 --- a/docs/libcurl/curl_url_get.md +++ b/docs/libcurl/curl_url_get.md @@ -76,9 +76,9 @@ operation returns an error instead. ## CURLU_URLENCODE -If set, curl_url_get(3) URL encodes the hostname part when a full URL -is retrieved. If not set (default), libcurl returns the URL with the host name -"raw" to support IDN names to appear as-is. IDN host names are typically using +If set, curl_url_get(3) URL encodes the hostname part when a full URL is +retrieved. If not set (default), libcurl returns the URL with the hostname raw +to support IDN names to appear as-is. IDN hostnames are typically using non-ASCII bytes that otherwise gets percent-encoded. Note that even when not asking for URL encoding, the '%' (byte 37) is URL @@ -119,7 +119,7 @@ When asked to return the full URL, curl_url_get(3) returns a normalized and possibly cleaned up version using all available URL parts. We advise using the *CURLU_PUNYCODE* option to get the URL as "normalized" -as possible since IDN allows host names to be written in many different ways +as possible since IDN allows hostnames to be written in many different ways that still end up the same punycode version. ## CURLUPART_SCHEME diff --git a/docs/libcurl/libcurl-env.md b/docs/libcurl/libcurl-env.md index bd3e29c734e..c27f7cea202 100644 --- a/docs/libcurl/libcurl-env.md +++ b/docs/libcurl/libcurl-env.md @@ -65,7 +65,7 @@ only) in which the .netrc file is likely to exist. ## LOGNAME -User name to use when invoking the *ntlm-wb* tool, if *NTLMUSER* was +Username to use when invoking the *ntlm-wb* tool, if *NTLMUSER* was not set. ## NO_PROXY @@ -76,7 +76,7 @@ should not use a proxy. ## NTLMUSER -User name to use when invoking the *ntlm-wb* tool. +Username to use when invoking the *ntlm-wb* tool. ## SSLKEYLOGFILE @@ -90,8 +90,8 @@ precautions so that they are not stolen or otherwise inadvertently revealed. ## USER -User name to use when invoking the *ntlm-wb* tool, if *NTLMUSER* and -*LOGNAME* were not set. +Username to use when invoking the *ntlm-wb* tool, if *NTLMUSER* and *LOGNAME* +were not set. # Debug Variables diff --git a/docs/libcurl/libcurl-security.md b/docs/libcurl/libcurl-security.md index 019080d263d..da4ac73c6eb 100644 --- a/docs/libcurl/libcurl-security.md +++ b/docs/libcurl/libcurl-security.md @@ -218,15 +218,15 @@ information to be sent to an unknown second server. Applications can mitigate against this by disabling CURLOPT_FOLLOWLOCATION(3) and handling redirects itself, sanitizing where necessary. -Use of the CURLAUTH_ANY option to CURLOPT_HTTPAUTH(3) could result in -user name and password being sent in clear text to an HTTP server. Instead, -use CURLAUTH_ANYSAFE which ensures that the password is encrypted over the +Use of the CURLAUTH_ANY option to CURLOPT_HTTPAUTH(3) could result in username +and password being sent in clear text to an HTTP server. Instead, use +CURLAUTH_ANYSAFE which ensures that the password is encrypted over the network, or else fail the request. Use of the CURLUSESSL_TRY option to CURLOPT_USE_SSL(3) could result in -user name and password being sent in clear text to an FTP server. Instead, -use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else -fail the request. +username and password being sent in clear text to an FTP server. Instead, use +CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else fail +the request. # Cookies @@ -419,14 +419,14 @@ plain HTTP connection. Relatedly, be aware that in situations when you have problems with libcurl and ask someone for help, everything you reveal in order to get best possible help -might also impose certain security related risks. Host names, user names, -paths, operating system specifics, etc. (not to mention passwords of course) -may in fact be used by intruders to gain additional information of a potential +might also impose certain security related risks. Hostnames, usernames, paths, +operating system specifics, etc. (not to mention passwords of course) may in +fact be used by intruders to gain additional information of a potential target. Be sure to limit access to application logs if they could hold private or -security-related data. Besides the obvious candidates like user names and -passwords, things like URLs, cookies or even file names could also hold +security-related data. Besides the obvious candidates like usernames and +passwords, things like URLs, cookies or even filenames could also hold sensitive data. To avoid this problem, you must of course use your common sense. Often, you @@ -460,7 +460,7 @@ only the trusted and reliable helper program is invoked! # Secrets in memory -When applications pass user names, passwords or other sensitive data to +When applications pass usernames, passwords or other sensitive data to libcurl to be used for upcoming transfers, those secrets are kept around as-is in memory. In many cases they are stored in the heap for as long as the handle itself for which the options are set. diff --git a/docs/libcurl/libcurl-tutorial.md b/docs/libcurl/libcurl-tutorial.md index de110bb30f7..2952856de79 100644 --- a/docs/libcurl/libcurl-tutorial.md +++ b/docs/libcurl/libcurl-tutorial.md @@ -350,7 +350,7 @@ buffer. Returning 0 signals the end of the upload. # Passwords -Many protocols use or even require that user name and password are provided +Many protocols use or even require that username and password are provided to be able to download or upload the data of your choice. libcurl offers several ways to specify them. @@ -360,10 +360,10 @@ this: ~~~c protocol://user:password@example.com/path/ ~~~ -If you need any odd letters in your user name or password, you should enter +If you need any odd letters in your username or password, you should enter them URL encoded, as %XX where XX is a two-digit hexadecimal number. -libcurl also provides options to set various passwords. The user name and +libcurl also provides options to set various passwords. The username and password as shown embedded in the URL can instead get set with the CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a char * to a string in the format "user:password". In a manner like this: @@ -381,13 +381,13 @@ to the CURLOPT_USERPWD(3) option like this: curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); ~~~ -There is a long time Unix "standard" way of storing FTP user names and +There is a long time Unix "standard" way of storing FTP usernames and passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks the *%USERPROFILE% environment* variable if *%HOME%* is unset, and tries "_netrc" as name). The file should be made private so that only the user may read it (see also the "Security Considerations" chapter), as it might contain the password in plain text. libcurl has the ability to use this file to figure -out what set of user name and password to use for a particular host. As an +out what set of username and password to use for a particular host. As an extension to the normal functionality, libcurl also supports this file for non-FTP protocols such as HTTP. To make curl use this file, use the CURLOPT_NETRC(3) option: @@ -416,7 +416,7 @@ To pass the known private key password to libcurl: # HTTP Authentication -The previous chapter showed how to set user name and password for getting URLs +The previous chapter showed how to set username and password for getting URLs that require authentication. When using the HTTP protocol, there are many different ways a client can provide those credentials to the server and you can control which way libcurl uses them. The default HTTP authentication @@ -675,10 +675,10 @@ becomes: curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin); ~~~ -curl_mime_name(3) always copies the field name. The special file name -"-" is not supported by curl_mime_filename(3): to read an open file, use -a callback source using fread(). The transfer is be chunk-encoded since the -data size is unknown. +curl_mime_name(3) always copies the field name. The special filename "-" is +not supported by curl_mime_filename(3): to read an open file, use a callback +source using fread(). The transfer is be chunk-encoded since the data size is +unknown. ~~~c curl_formadd(&post, &last, diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md index 23e8785f20a..e8db6c8655e 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md +++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md @@ -42,7 +42,7 @@ HTTP(S) ~~~c #include -/* only allow pushes for file names starting with "push-" */ +/* only allow pushes for filenames starting with "push-" */ int push_callback(CURL *parent, CURL *easy, size_t num_headers, diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md index 903ac06fb48..2f08e72bd9c 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md @@ -103,7 +103,7 @@ HTTP(S) (HTTP/2 only) ~~~c #include -/* only allow pushes for file names starting with "push-" */ +/* only allow pushes for filenames starting with "push-" */ int push_callback(CURL *parent, CURL *easy, size_t num_headers, diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC.md b/docs/libcurl/opts/CURLOPT_ALTSVC.md index 6f6408474f0..e0db681b8d7 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC.md +++ b/docs/libcurl/opts/CURLOPT_ALTSVC.md @@ -13,7 +13,7 @@ See-also: # NAME -CURLOPT_ALTSVC - alt-svc cache file name +CURLOPT_ALTSVC - alt-svc cache filename # SYNOPSIS diff --git a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md index ddaaace893f..6c657169d74 100644 --- a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md +++ b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md @@ -34,7 +34,7 @@ curl_url_set(3) function. # DEFAULT -0 (disabled) - user names are allowed by default. +0 (disabled) - usernames are allowed by default. # PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md index 0199f525aae..3a24d509c6f 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md @@ -33,8 +33,7 @@ default, libcurl caches this info for 60 seconds. We recommend users not to tamper with this option unless strictly necessary. If you do, be careful of using large values that can make the cache size grow -significantly if many different host names are used within that timeout -period. +significantly if many different hostnames are used within that timeout period. The name resolve functions of various libc implementations do not re-read name server information unless explicitly told so (for example, by calling diff --git a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md index 070bdc5afc2..3a9c73a69e1 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md +++ b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md @@ -39,7 +39,7 @@ NULL # PROTOCOLS -All protocols except file:// - protocols that resolve host names. +All protocols except file:// - protocols that resolve hostnames. # EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md index f8941953bd9..575fb196618 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md +++ b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md @@ -24,7 +24,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ACCOUNT, char *account); # DESCRIPTION Pass a pointer to a null-terminated string (or NULL to disable). When an FTP -server asks for "account data" after user name and password has been provided, +server asks for "account data" after username and password has been provided, this data is sent off using the ACCT command. The application does not have to keep the string around after setting this diff --git a/docs/libcurl/opts/CURLOPT_HSTS.md b/docs/libcurl/opts/CURLOPT_HSTS.md index 83379f27068..7c15edabae1 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS.md +++ b/docs/libcurl/opts/CURLOPT_HSTS.md @@ -12,7 +12,7 @@ See-also: # NAME -CURLOPT_HSTS - HSTS cache file name +CURLOPT_HSTS - HSTS cache filename # SYNOPSIS @@ -55,7 +55,7 @@ currently no length or size limit. # DEFAULT -NULL, no file name +NULL, no filename # PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.md b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md index ca92f5eb098..2adacdd3f50 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.md +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md @@ -40,7 +40,7 @@ For authentication with a proxy, see CURLOPT_PROXYAUTH(3). HTTP Basic authentication. This is the default choice, and the only method that is in wide-spread use and supported virtually everywhere. This sends -the user name and password over the network in plain text, easily captured by +the username and password over the network in plain text, easily captured by others. ## CURLAUTH_DIGEST diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md index 7d06405ecdd..9eeabe84ed3 100644 --- a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md +++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md @@ -26,7 +26,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IPRESOLVE, long resolve); Allows an application to select what kind of IP addresses to use when establishing a connection or choosing one from the connection pool. This is -interesting when using host names that resolve to more than one IP family. +interesting when using hostnames that resolve to more than one IP family. If the URL provided for a transfer contains a numerical IP version as a host name, this option does not override or prohibit libcurl from using that IP diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md index e1b3f1555a6..47065d30d20 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md @@ -35,7 +35,7 @@ as the first character libcurl assumes you provided a single email address and encloses that address within brackets for you. When performing an address verification (**VRFY** command), each recipient -should be specified as the user name or user name and domain (as per Section +should be specified as the username or username plus domain (as per Section 3.5 of RFC 5321). When performing a mailing list expand (**EXPN** command), each recipient diff --git a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md index a8da7d7abd2..747eab24dfb 100644 --- a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md @@ -30,7 +30,7 @@ Available bits are: ## CURLMIMEOPT_FORMESCAPE -Tells libcurl to escape multipart form field and file names using the +Tells libcurl to escape multipart form field and filenames using the backslash-escaping algorithm rather than percent-encoding (HTTP only). Backslash-escaping consists in preceding backslashes and double quotes with diff --git a/docs/libcurl/opts/CURLOPT_NETRC.md b/docs/libcurl/opts/CURLOPT_NETRC.md index d5acdd5df37..580cdcd3b41 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.md +++ b/docs/libcurl/opts/CURLOPT_NETRC.md @@ -25,8 +25,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level); # DESCRIPTION This parameter controls the preference *level* of libcurl between using -user names and passwords from your *~/.netrc* file, relative to user names -and passwords in the URL supplied with CURLOPT_URL(3). +usernames and passwords from your *~/.netrc* file, relative to usernames and +passwords in the URL supplied with CURLOPT_URL(3). On Windows, libcurl uses the file as *%HOME%/_netrc*. If *%HOME%* is not set on Windows, libcurl falls back to *%USERPROFILE%*. @@ -34,11 +34,11 @@ not set on Windows, libcurl falls back to *%USERPROFILE%*. You can also tell libcurl a different filename to use with CURLOPT_NETRC_FILE(3). -libcurl uses a user name (and supplied or prompted password) supplied with +libcurl uses a username (and supplied or prompted password) supplied with CURLOPT_USERPWD(3) or CURLOPT_USERNAME(3) in preference to any of the options controlled by this parameter. -Only machine name, user name and password are taken into account (init macros +Only machine name, username and password are taken into account (init macros and similar things are not supported). libcurl does not verify that the file has the correct properties set (as the @@ -53,15 +53,15 @@ libcurl ignores the *.netrc* file. This is the default. ## CURL_NETRC_OPTIONAL (1) The use of the *.netrc* file is optional, and information in the URL is to -be preferred. The file is scanned for the host and user name (to find the -password only) or for the host only, to find the first user name and password +be preferred. The file is scanned for the host and username (to find the +password only) or for the host only, to find the first username and password after that *machine*, which ever information is not specified. ## CURL_NETRC_REQUIRED (2) The use of the *.netrc* file is required, and any credential information -present in the URL is ignored. The file is scanned for the host and user name -(to find the password only) or for the host only, to find the first user name +present in the URL is ignored. The file is scanned for the host and username +(to find the password only) or for the host only, to find the first username and password after that *machine*, which ever information is not specified. @@ -74,7 +74,7 @@ Each field is provided as a sequence of letters that ends with a space or newline. Starting in 7.84.0, libcurl also supports quoted strings. They start and end with double quotes and support the escaped special letters ", n, r, and t. Quoted strings are the only way a space character can be used in -a user name or password. +a username or password. ## machine \ @@ -94,7 +94,7 @@ add a line similar to this in the end: ## login \ -The user name string for the remote machine. +The username string for the remote machine. ## password \ diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.md b/docs/libcurl/opts/CURLOPT_NOPROXY.md index 91292e22ea2..9bb396548ae 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROXY.md +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.md @@ -25,18 +25,17 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROXY, char *noproxy); # DESCRIPTION Pass a pointer to a null-terminated string. The string consists of a comma -separated list of host names that do not require a proxy to get reached, even +separated list of hostnames that do not require a proxy to get reached, even if one is specified. The only wildcard available 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, "ample.com" would match ample.com, ample.com:80, and www.ample.com, but not www.example.com or ample.com.org. -Setting the *noproxy* string to "" (an empty string) explicitly enables -the proxy for all host names, even if there is an environment variable set for -it. +Setting the *noproxy* string to "" (an empty string) explicitly enables the +proxy for all hostnames, even if there is an environment variable set for it. -Enter IPv6 numerical addresses in the list of host names without enclosing +Enter IPv6 numerical addresses in the list of hostnames without enclosing brackets: "example.com,::1,localhost" diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md index f0d1dfc4d51..3a68275fbd0 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md @@ -13,7 +13,7 @@ See-also: # NAME -CURLOPT_PROXYUSERNAME - user name to use for proxy authentication +CURLOPT_PROXYUSERNAME - username to use for proxy authentication # SYNOPSIS @@ -27,9 +27,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERNAME, # DESCRIPTION Pass a char pointer as parameter, which should be pointing to the -null-terminated user name to use for the transfer. +null-terminated username to use for the transfer. -CURLOPT_PROXYUSERNAME(3) sets the user name to be used in protocol +CURLOPT_PROXYUSERNAME(3) sets the username to be used in protocol authentication with the proxy. To specify the proxy password use the CURLOPT_PROXYPASSWORD(3). diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md index 196d587e28c..34489d4993b 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md @@ -13,7 +13,7 @@ See-also: # NAME -CURLOPT_PROXYUSERPWD - user name and password to use for proxy authentication +CURLOPT_PROXYUSERPWD - username and password to use for proxy authentication # SYNOPSIS @@ -25,10 +25,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERPWD, char *userpwd); # DESCRIPTION -Pass a char pointer as parameter, which should be [user name]:[password] to -use for the connection to the HTTP proxy. Both the name and the password are -URL decoded before used, so to include for example a colon in the user name -you should encode it as %3A. (This is different to how CURLOPT_USERPWD(3) is +Pass a char pointer as parameter, which should be [username]:[password] to use +for the connection to the HTTP proxy. Both the name and the password are URL +decoded before used, so to include for example a colon in the username you +should encode it as %3A. (This is different to how CURLOPT_USERPWD(3) is used - beware.) Use CURLOPT_PROXYAUTH(3) to specify the authentication method. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md index 612ff4f9293..7c6ff6fbc99 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md @@ -13,7 +13,7 @@ See-also: # NAME -CURLOPT_PROXY_TLSAUTH_USERNAME - user name to use for proxy TLS authentication +CURLOPT_PROXY_TLSAUTH_USERNAME - username to use for proxy TLS authentication # SYNOPSIS diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md index 457ef99401a..bc581d911b8 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md @@ -27,7 +27,7 @@ Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) are allowed for SOCKS5 proxy authentication. The only supported flags are *CURLAUTH_BASIC*, which allows username/password authentication, *CURLAUTH_GSSAPI*, which allows GSS-API authentication, and -*CURLAUTH_NONE*, which allows no authentication. Set the actual user name and +*CURLAUTH_NONE*, which allows no authentication. Set the actual username and password with the CURLOPT_PROXYUSERPWD(3) option. # DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md index 1127046af60..e797499e7c3 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md @@ -11,7 +11,7 @@ See-also: # NAME -CURLOPT_TLSAUTH_USERNAME - user name to use for TLS authentication +CURLOPT_TLSAUTH_USERNAME - username to use for TLS authentication # SYNOPSIS diff --git a/docs/libcurl/opts/CURLOPT_USERNAME.md b/docs/libcurl/opts/CURLOPT_USERNAME.md index f7481780197..269b846094c 100644 --- a/docs/libcurl/opts/CURLOPT_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_USERNAME.md @@ -13,7 +13,7 @@ See-also: # NAME -CURLOPT_USERNAME - user name to use in authentication +CURLOPT_USERNAME - username to use in authentication # SYNOPSIS @@ -27,9 +27,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERNAME, # DESCRIPTION Pass a char pointer as parameter, which should be pointing to the -null-terminated user name to use for the transfer. +null-terminated username to use for the transfer. -CURLOPT_USERNAME(3) sets the user name to be used in protocol +CURLOPT_USERNAME(3) sets the username to be used in protocol authentication. You should not use this option together with the (older) CURLOPT_USERPWD(3) option. @@ -38,9 +38,8 @@ include the domain name in order for the server to successfully obtain a Kerberos Ticket. If you do not then the initial part of the authentication handshake may fail. -When using NTLM, the user name can be specified simply as the user name -without the domain name should the server be part of a single domain and -forest. +When using NTLM, the username can be specified simply as the username without +the domain name should the server be part of a single domain and forest. To include the domain name use either Down-Level Logon Name or UPN (User Principal Name) formats. For example, **EXAMPLE\user** and @@ -49,7 +48,7 @@ Principal Name) formats. For example, **EXAMPLE\user** and Some HTTP servers (on Windows) support inclusion of the domain for Basic authentication as well. -To specify the password and login options, along with the user name, use the +To specify the password and login options, along with the username, use the CURLOPT_PASSWORD(3) and CURLOPT_LOGIN_OPTIONS(3) options. The application does not have to keep the string around after setting this diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.md b/docs/libcurl/opts/CURLOPT_USERPWD.md index 01c65207a5d..e78e11ddb8f 100644 --- a/docs/libcurl/opts/CURLOPT_USERPWD.md +++ b/docs/libcurl/opts/CURLOPT_USERPWD.md @@ -12,7 +12,7 @@ See-also: # NAME -CURLOPT_USERPWD - user name and password to use in authentication +CURLOPT_USERPWD - username and password to use in authentication # SYNOPSIS @@ -25,16 +25,15 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERPWD, char *userpwd); # DESCRIPTION Pass a char pointer as parameter, pointing to a null-terminated login details -string for the connection. The format of which is: [user name]:[password]. +string for the connection. The format of which is: [username]:[password]. When using Kerberos V5 authentication with a Windows based server, you should -specify the user name part with the domain name in order for the server to +specify the username part with the domain name in order for the server to successfully obtain a Kerberos Ticket. If you do not then the initial part of the authentication handshake may fail. -When using NTLM, the user name can be specified simply as the user name -without the domain name should the server be part of a single domain and -forest. +When using NTLM, the username can be specified simply as the username without +the domain name should the server be part of a single domain and forest. To specify the domain name use either Down-Level Logon Name or UPN (User Principal Name) formats. For example **EXAMPLE\user** and **user@example.com** @@ -55,8 +54,8 @@ based connections or CURLOPT_LOGIN_OPTIONS(3) to control IMAP, POP3 and SMTP options. The user and password strings are not URL decoded, so there is no way to send -in a user name containing a colon using this option. Use -CURLOPT_USERNAME(3) for that, or include it in the URL. +in a username containing a colon using this option. Use CURLOPT_USERNAME(3) +for that, or include it in the URL. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md index af91ea03e69..d6cf901f444 100644 --- a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md @@ -27,8 +27,8 @@ Pass a char pointer as parameter, which should point to the null-terminated OAuth 2.0 Bearer Access Token for use with HTTP, IMAP, LDAP, POP3 and SMTP servers that support the OAuth 2.0 Authorization Framework. -Note: For IMAP, LDAP, POP3 and SMTP, the user name used to generate the -Bearer Token should be supplied via the CURLOPT_USERNAME(3) option. +Note: For IMAP, LDAP, POP3 and SMTP, the username used to generate the Bearer +Token should be supplied via the CURLOPT_USERNAME(3) option. The application does not have to keep the string around after setting this option. From 911fc964a1ade957881be18b868363829f830c78 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 18:07:07 +0100 Subject: [PATCH 293/509] cmdline-docs: quote and angle bracket cleanup - make sure angle brackets are escaped - remove a lot of superfluous double quotes - replace several double quotes with backticks To make nicer-looking markdown. Closes #12884 --- docs/cmdline-opts/MANPAGE.md | 3 +++ docs/cmdline-opts/_OPTIONS.md | 6 +++--- docs/cmdline-opts/_PROGRESS.md | 6 +++--- docs/cmdline-opts/_PROTOCOLS.md | 8 ++++---- docs/cmdline-opts/_URL.md | 2 +- docs/cmdline-opts/_VARIABLES.md | 12 ++++++------ docs/cmdline-opts/abstract-unix-socket.md | 4 ++-- docs/cmdline-opts/cert.md | 14 +++++++------- docs/cmdline-opts/data-urlencode.md | 4 ++-- docs/cmdline-opts/dns-interface.md | 6 +++--- docs/cmdline-opts/dns-servers.md | 8 ++++---- docs/cmdline-opts/form-string.md | 8 ++++---- docs/cmdline-opts/form.md | 8 ++++---- docs/cmdline-opts/ftp-port.md | 4 ++-- docs/cmdline-opts/gen.pl | 16 ++++++++++++---- docs/cmdline-opts/output.md | 8 ++++---- docs/cmdline-opts/quote.md | 4 ++-- docs/cmdline-opts/raw.md | 2 +- docs/cmdline-opts/referer.md | 10 +++++----- docs/cmdline-opts/remote-header-name.md | 4 ++-- docs/cmdline-opts/request-target.md | 2 +- docs/cmdline-opts/retry-all-errors.md | 2 +- docs/cmdline-opts/tftp-blksize.md | 6 +++--- docs/cmdline-opts/time-cond.md | 8 ++++---- docs/cmdline-opts/tlsauthtype.md | 4 ++-- docs/cmdline-opts/trace-ascii.md | 2 +- docs/cmdline-opts/trace-config.md | 4 ++-- docs/cmdline-opts/upload-file.md | 8 ++++---- docs/cmdline-opts/url.md | 4 ++-- docs/cmdline-opts/use-ascii.md | 2 +- docs/cmdline-opts/variable.md | 10 +++++----- docs/cmdline-opts/verbose.md | 7 +++---- docs/cmdline-opts/write-out.md | 2 +- src/tool_listhelp.c | 2 +- 34 files changed, 105 insertions(+), 95 deletions(-) diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 951cbe859ec..efacd6a3b23 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -83,6 +83,9 @@ explicitly with an empty "header": ## +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 produces a diff --git a/docs/cmdline-opts/_OPTIONS.md b/docs/cmdline-opts/_OPTIONS.md index 1b25566591f..8f388130aaa 100644 --- a/docs/cmdline-opts/_OPTIONS.md +++ b/docs/cmdline-opts/_OPTIONS.md @@ -7,7 +7,7 @@ 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 +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 @@ -16,11 +16,11 @@ 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 +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 +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/_PROGRESS.md b/docs/cmdline-opts/_PROGRESS.md index 80e36f10245..2775ec20065 100644 --- a/docs/cmdline-opts/_PROGRESS.md +++ b/docs/cmdline-opts/_PROGRESS.md @@ -14,12 +14,12 @@ 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. +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 +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 index b834f9ae36c..201c080b1b0 100644 --- a/docs/cmdline-opts/_PROTOCOLS.md +++ b/docs/cmdline-opts/_PROTOCOLS.md @@ -19,14 +19,14 @@ 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 +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). +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. diff --git a/docs/cmdline-opts/_URL.md b/docs/cmdline-opts/_URL.md index 0084ec61283..83ccfdd98df 100644 --- a/docs/cmdline-opts/_URL.md +++ b/docs/cmdline-opts/_URL.md @@ -7,7 +7,7 @@ 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. +`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 diff --git a/docs/cmdline-opts/_VARIABLES.md b/docs/cmdline-opts/_VARIABLES.md index 3e17bfdaeac..60ee6d00d14 100644 --- a/docs/cmdline-opts/_VARIABLES.md +++ b/docs/cmdline-opts/_VARIABLES.md @@ -2,14 +2,14 @@ # 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 +--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}}" (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 "\{{". +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 diff --git a/docs/cmdline-opts/abstract-unix-socket.md b/docs/cmdline-opts/abstract-unix-socket.md index 27bc8cad6cb..7078e642fd8 100644 --- a/docs/cmdline-opts/abstract-unix-socket.md +++ b/docs/cmdline-opts/abstract-unix-socket.md @@ -17,5 +17,5 @@ Example: # `--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. +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/cert.md b/docs/cmdline-opts/cert.md index 6df5d0ebf7f..b9630b958b5 100644 --- a/docs/cmdline-opts/cert.md +++ b/docs/cmdline-opts/cert.md @@ -27,28 +27,28 @@ 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, +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 +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 +`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. +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, +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*, diff --git a/docs/cmdline-opts/data-urlencode.md b/docs/cmdline-opts/data-urlencode.md index 4d3f2981335..733530a5700 100644 --- a/docs/cmdline-opts/data-urlencode.md +++ b/docs/cmdline-opts/data-urlencode.md @@ -23,8 +23,8 @@ Example: 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 +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 diff --git a/docs/cmdline-opts/dns-interface.md b/docs/cmdline-opts/dns-interface.md index afc5573e55a..ee2bb829ff6 100644 --- a/docs/cmdline-opts/dns-interface.md +++ b/docs/cmdline-opts/dns-interface.md @@ -18,6 +18,6 @@ Example: # `--dns-interface` -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). +Tell curl to 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-servers.md b/docs/cmdline-opts/dns-servers.md index 3eab6668ded..bf6ba3fe930 100644 --- a/docs/cmdline-opts/dns-servers.md +++ b/docs/cmdline-opts/dns-servers.md @@ -14,11 +14,11 @@ See-also: - 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 as *:* after each IP -address. +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/form-string.md b/docs/cmdline-opts/form-string.md index 15475cc3315..3c1f7b53275 100644 --- a/docs/cmdline-opts/form-string.md +++ b/docs/cmdline-opts/form-string.md @@ -17,7 +17,7 @@ Example: # `--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. +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.md b/docs/cmdline-opts/form.md index 0ba552136fd..3e3f475af8c 100644 --- a/docs/cmdline-opts/form.md +++ b/docs/cmdline-opts/form.md @@ -29,13 +29,13 @@ 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 +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 +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 diff --git a/docs/cmdline-opts/ftp-port.md b/docs/cmdline-opts/ftp-port.md index e9ec59146fc..370f68c1f46 100644 --- a/docs/cmdline-opts/ftp-port.md +++ b/docs/cmdline-opts/ftp-port.md @@ -23,8 +23,8 @@ Example: 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: +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) diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index f4dcce8aebb..9b3128444e7 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -288,11 +288,19 @@ sub render { } } - if(!$quote && ($d =~ /^(.*) /)) { - printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n", - length($1); - return 3; + if(!$quote) { + if($d =~ /^(.*) /) { + printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n", + length($1); + return 3; + } + elsif($d =~ /[^\\][\<\>]/) { + print STDERR "$f:$line:1:WARN: un-escaped < or > used\n"; + return 3; + } } + # convert backslash-'<' or '> to just the second character + $d =~ s/\\([<<])/$1/g; # quote minuses in the output $d =~ s/([^\\])-/$1\\-/g; # replace single quotes diff --git a/docs/cmdline-opts/output.md b/docs/cmdline-opts/output.md index 876c90c81da..2b2527663b6 100644 --- a/docs/cmdline-opts/output.md +++ b/docs/cmdline-opts/output.md @@ -21,10 +21,10 @@ Example: # `--output` -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: +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 file name. 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" diff --git a/docs/cmdline-opts/quote.md b/docs/cmdline-opts/quote.md index 3155f4eb2dc..06f6a50fa41 100644 --- a/docs/cmdline-opts/quote.md +++ b/docs/cmdline-opts/quote.md @@ -43,7 +43,7 @@ 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 can be all sorts of date strings, see the +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 @@ -69,7 +69,7 @@ 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 can be all sorts of date strings, see 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 diff --git a/docs/cmdline-opts/raw.md b/docs/cmdline-opts/raw.md index 9871b033eb7..ca63dc318ce 100644 --- a/docs/cmdline-opts/raw.md +++ b/docs/cmdline-opts/raw.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: raw -Help: Do HTTP "raw"; no transfer decoding +Help: Do HTTP raw; no transfer decoding Added: 7.16.2 Protocols: HTTP Category: http diff --git a/docs/cmdline-opts/referer.md b/docs/cmdline-opts/referer.md index 3120280ccd4..40a8dc6df09 100644 --- a/docs/cmdline-opts/referer.md +++ b/docs/cmdline-opts/referer.md @@ -20,8 +20,8 @@ Example: # `--referer` -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. +Sends 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.md b/docs/cmdline-opts/remote-header-name.md index c4cf514dbd1..d68e17b74b8 100644 --- a/docs/cmdline-opts/remote-header-name.md +++ b/docs/cmdline-opts/remote-header-name.md @@ -32,8 +32,8 @@ 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). +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 diff --git a/docs/cmdline-opts/request-target.md b/docs/cmdline-opts/request-target.md index 5b23630bff8..cc379229380 100644 --- a/docs/cmdline-opts/request-target.md +++ b/docs/cmdline-opts/request-target.md @@ -16,7 +16,7 @@ Example: # `--request-target` -Tells curl to use an alternative "target" (path) instead of using the path as +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 *". diff --git a/docs/cmdline-opts/retry-all-errors.md b/docs/cmdline-opts/retry-all-errors.md index c29911fca3c..d2f14e8085d 100644 --- a/docs/cmdline-opts/retry-all-errors.md +++ b/docs/cmdline-opts/retry-all-errors.md @@ -26,7 +26,7 @@ script. Please read the example below. 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 > +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. diff --git a/docs/cmdline-opts/tftp-blksize.md b/docs/cmdline-opts/tftp-blksize.md index b059d4b40ce..21d8476af06 100644 --- a/docs/cmdline-opts/tftp-blksize.md +++ b/docs/cmdline-opts/tftp-blksize.md @@ -16,6 +16,6 @@ Example: # `--tftp-blksize` -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. +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/time-cond.md b/docs/cmdline-opts/time-cond.md index 5b1c91eb014..44cb166349a 100644 --- a/docs/cmdline-opts/time-cond.md +++ b/docs/cmdline-opts/time-cond.md @@ -21,10 +21,10 @@ Example: # `--time-cond` Request a file that has been modified later than the given time and date, or -one that has been modified before that time. The can be all -sorts of date strings or if it does not match any internal ones, it is taken as -a filename and tries to get the modification date (mtime) from -instead. See the *curl_getdate(3)* man pages for date expression details. +one that has been modified before that time. The date expression can be all +sorts of date strings or if it does not match any internal ones, it is treated +as a filename and curl tries to get the modification date (mtime) from that +file instead. See the *curl_getdate(3)* man pages for date expression details. Start the date expression with a dash (-) to make it request for a document that is older than the given date/time, default is a document that is newer diff --git a/docs/cmdline-opts/tlsauthtype.md b/docs/cmdline-opts/tlsauthtype.md index dd268481462..10eccb29adc 100644 --- a/docs/cmdline-opts/tlsauthtype.md +++ b/docs/cmdline-opts/tlsauthtype.md @@ -16,8 +16,8 @@ Example: # `--tlsauthtype` -Set TLS authentication type. Currently, the only supported option is "SRP", +Set TLS authentication type. Currently, the only supported option is `SRP`, for TLS-SRP (RFC 5054). If --tlsuser and --tlspassword are specified but ---tlsauthtype is not, then this option defaults to "SRP". This option works +--tlsauthtype is not, then this option defaults to `SRP`. This option works only if the underlying libcurl is built with TLS-SRP support, which requires OpenSSL or GnuTLS with TLS-SRP support. diff --git a/docs/cmdline-opts/trace-ascii.md b/docs/cmdline-opts/trace-ascii.md index 209c7bd9775..130f708c1aa 100644 --- a/docs/cmdline-opts/trace-ascii.md +++ b/docs/cmdline-opts/trace-ascii.md @@ -19,7 +19,7 @@ Example: # `--trace-ascii` Enables a full trace dump of all incoming and outgoing data, including -descriptive information, to the given output file. Use "-" as filename to have +descriptive information, to the given output file. Use `-` as filename to have the output sent to stdout. This is similar to --trace, but leaves out the hex part and only shows the diff --git a/docs/cmdline-opts/trace-config.md b/docs/cmdline-opts/trace-config.md index 0bc9da101b0..0ab7dbe7202 100644 --- a/docs/cmdline-opts/trace-config.md +++ b/docs/cmdline-opts/trace-config.md @@ -22,7 +22,7 @@ Set configuration for trace output. A comma-separated list of components where detailed output can be made available from. Names are case-insensitive. Specify 'all' to enable all trace components. -In addition to trace component names, specify "ids" and "time" to -avoid extra --trace-ids or --trace-time parameters. +In addition to trace component names, specify `ids` and `time` to avoid extra +--trace-ids or --trace-time parameters. See the *curl_global_trace(3)* man page for more details. diff --git a/docs/cmdline-opts/upload-file.md b/docs/cmdline-opts/upload-file.md index 05ba2c97de0..60ee8531b8f 100644 --- a/docs/cmdline-opts/upload-file.md +++ b/docs/cmdline-opts/upload-file.md @@ -33,16 +33,16 @@ When putting the local file name at the end of the URL, curl ignores what is on the left side of any slash (/) or backslash (\) used in the file name and only appends what is on the right side of the rightmost such character. -Use the file name "-" (a single dash) to use stdin instead of a given file. -Alternately, the file name "." (a single period) may be specified instead of -"-" to use stdin in non-blocking mode to allow reading server output while +Use the file name `-` (a single dash) to use stdin instead of a given file. +Alternately, the file name `.` (a single period) may be specified instead of +`-` to use stdin in non-blocking mode to allow reading server output while stdin is being uploaded. If this option is used with a HTTP(S) URL, the PUT method is used. You can specify one --upload-file for each URL on the command line. Each --upload-file + URL pair specifies what to upload and to where. curl also -supports "globbing" of the --upload-file argument, meaning that you can upload +supports globbing of the --upload-file argument, meaning that you can upload multiple files to a single URL by using the same URL globbing style supported in the URL. diff --git a/docs/cmdline-opts/url.md b/docs/cmdline-opts/url.md index 0adfa743beb..671c376ec55 100644 --- a/docs/cmdline-opts/url.md +++ b/docs/cmdline-opts/url.md @@ -19,7 +19,7 @@ Example: Specify a URL to fetch. This option is mostly handy when you want to specify URL(s) in a config file. -If the given URL is missing a scheme name (such as "http://" or "ftp://" etc) +If the given URL is missing a scheme name (such as `http://` or `ftp://` etc) then curl makes a guess based on the host. If the outermost subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol is used, otherwise HTTP is used. Guessing can be avoided by providing a full URL @@ -29,5 +29,5 @@ including the scheme, or disabled by setting a default protocol (added in To control where this URL is written, use the --output or the --remote-name options. -**WARNING**: On Windows, particular file:// accesses can be converted to +**WARNING**: On Windows, particular `file://` accesses can be converted to network accesses by the operating system. Beware! diff --git a/docs/cmdline-opts/use-ascii.md b/docs/cmdline-opts/use-ascii.md index 4e2574a780c..96b1928103d 100644 --- a/docs/cmdline-opts/use-ascii.md +++ b/docs/cmdline-opts/use-ascii.md @@ -18,5 +18,5 @@ Example: # `--use-ascii` Enable ASCII transfer. For FTP, this can also be enforced by using a URL that -ends with ";type=A". This option causes data sent to stdout to be in text mode +ends with `;type=A`. This option causes data sent to stdout to be in text mode for win32 systems. diff --git a/docs/cmdline-opts/variable.md b/docs/cmdline-opts/variable.md index 14b895c7f5b..9da1d3feebf 100644 --- a/docs/cmdline-opts/variable.md +++ b/docs/cmdline-opts/variable.md @@ -15,22 +15,22 @@ Example: # `--variable` -Set a variable with "name=content" or "name@file" (where "file" can be stdin -if set to a single dash (-)). The name is a case sensitive identifier that +Set a variable with `name=content` or `name@file` (where `file` can be stdin +if set to a single dash (`-`)). The name is a case sensitive identifier that must consist of no other letters than a-z, A-Z, 0-9 or underscore. The specified content is then associated with this identifier. Setting the same variable name again overwrites the old contents with the new. The contents of a variable can be referenced in a later command line option -when that option name is prefixed with "--expand-", and the name is used as -"{{name}}" (without the quotes). +when that option name is prefixed with `--expand-`, and the name is used as +`{{name}}`. --variable can import environment variables into the name space. Opt to either require the environment variable to be set or provide a default value for the variable in case it is not already set. ---variable %name imports the variable called 'name' but exits with an error if +--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 the environment variable is not set, use --variable %name=content or --variable %name@content. Note that on some systems - but not all - diff --git a/docs/cmdline-opts/verbose.md b/docs/cmdline-opts/verbose.md index 21ecf6a9c0b..ebc039fc1af 100644 --- a/docs/cmdline-opts/verbose.md +++ b/docs/cmdline-opts/verbose.md @@ -21,10 +21,9 @@ Example: # `--verbose` Makes curl verbose during the operation. Useful for debugging and seeing -what's going on "under the hood". A line starting with '>' means "header data" -sent by curl, '<' means "header data" received by curl that is hidden in -normal cases, and a line starting with '*' means additional info provided by -curl. +what's going on under the hood. A line starting with \> means header data sent +by curl, \< means header data received by curl that is hidden in normal cases, +and a line starting with * means additional info provided by curl. If you only want HTTP headers in the output, --include or --dump-header might be more suitable options. diff --git a/docs/cmdline-opts/write-out.md b/docs/cmdline-opts/write-out.md index 53d40e84a6d..5af8ebbaba2 100644 --- a/docs/cmdline-opts/write-out.md +++ b/docs/cmdline-opts/write-out.md @@ -42,7 +42,7 @@ Select a specific target destination file to write the output to, by using output following that instruction is then written to that file. More than one *%output{}* instruction can be specified in the same write-out argument. If the file name cannot be created, curl leaves the output destination to the one -used prior to the *%output{}* instruction. Use *%output{>>name}* to append +used prior to the *%output{}* instruction. Use *%output{\>\>name}* to append data to an existing file. **NOTE:** diff --git a/src/tool_listhelp.c b/src/tool_listhelp.c index 32ed2533e18..23472f345a5 100644 --- a/src/tool_listhelp.c +++ b/src/tool_listhelp.c @@ -583,7 +583,7 @@ const struct helptxt helptext[] = { "Request rate for serial transfers", CURLHELP_CONNECTION}, {" --raw", - "Do HTTP \"raw\"; no transfer decoding", + "Do HTTP raw; no transfer decoding", CURLHELP_HTTP}, {"-e, --referer ", "Referrer URL", From 924e264bde94c4872caad103803c3ba2b6473972 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 18:09:11 -0500 Subject: [PATCH 294/509] tool_operate: change precedence of server Retry-After time MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - When calculating the retry time, no longer allow a server's requested Retry-After time to take precedence over a longer retry time (either default algorithmic or user-specified). Prior to this change the server's Retry-After time took precedence over curl's retry time in all cases, but that's not always practical for short Retry-After times depending on how busy the server is. Bug: https://curl.se/mail/archive-2024-01/0022.html Reported-by: Dirk Hünniger Closes https://github.com/curl/curl/pull/12871 --- src/tool_operate.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tool_operate.c b/src/tool_operate.c index 86936ba5943..5a5fc8745ed 100644 --- a/src/tool_operate.c +++ b/src/tool_operate.c @@ -554,7 +554,7 @@ static CURLcode post_per_transfer(struct GlobalConfig *global, /* store in a 'long', make sure it doesn't overflow */ if(retry_after > LONG_MAX/1000) sleeptime = LONG_MAX; - else + else if((retry_after * 1000) > sleeptime) sleeptime = (long)retry_after * 1000; /* milliseconds */ /* if adding retry_after seconds to the process would exceed the From 8f40b30c3132fa40d0ad17a76b614504452f54ce Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 17:39:04 +0100 Subject: [PATCH 295/509] KNOWN_BUGS: unicode on Windows Closes #11461 Closes #12231 Closes #12883 --- docs/KNOWN_BUGS | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index f91ff63bb64..70b21d31be2 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -44,6 +44,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 @@ -283,6 +284,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 From 142ac257b3242459b284020c59f1902b9687a954 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 6 Feb 2024 10:15:52 +0100 Subject: [PATCH 296/509] lib: convert Curl_get_line to use dynbuf Create the line in a dynbuf. Aborts the reading of the file on errors. Avoids having to always allocate maximum amount from the start. Avoids direct malloc. Closes #12846 --- lib/altsvc.c | 18 +++------- lib/cookie.c | 29 ++++------------ lib/curl_get_line.c | 55 +++++++++++++---------------- lib/curl_get_line.h | 7 ++-- lib/hsts.c | 17 +++------ lib/netrc.c | 10 ++++-- tests/unit/unit3200.c | 80 ++++++++++++++++++++++++------------------- 7 files changed, 96 insertions(+), 120 deletions(-) diff --git a/lib/altsvc.c b/lib/altsvc.c index e9f62bf0e0a..c12d7bda199 100644 --- a/lib/altsvc.c +++ b/lib/altsvc.c @@ -209,7 +209,6 @@ static CURLcode altsvc_add(struct altsvcinfo *asi, char *line) static CURLcode altsvc_load(struct altsvcinfo *asi, const char *file) { CURLcode result = CURLE_OK; - char *line = NULL; FILE *fp; /* we need a private copy of the file name so that the altsvc cache file @@ -221,11 +220,10 @@ static CURLcode altsvc_load(struct altsvcinfo *asi, const char *file) fp = fopen(file, FOPEN_READTEXT); if(fp) { - line = malloc(MAX_ALTSVC_LINE); - if(!line) - goto fail; - while(Curl_get_line(line, MAX_ALTSVC_LINE, fp)) { - char *lineptr = line; + struct dynbuf buf; + Curl_dyn_init(&buf, MAX_ALTSVC_LINE); + while(Curl_get_line(&buf, fp)) { + char *lineptr = Curl_dyn_ptr(&buf); while(*lineptr && ISBLANK(*lineptr)) lineptr++; if(*lineptr == '#') @@ -234,16 +232,10 @@ static CURLcode altsvc_load(struct altsvcinfo *asi, const char *file) altsvc_add(asi, lineptr); } - free(line); /* free the line buffer */ + Curl_dyn_free(&buf); /* free the line buffer */ fclose(fp); } return result; - -fail: - Curl_safefree(asi->filename); - free(line); - fclose(fp); - return CURLE_OUT_OF_MEMORY; } /* diff --git a/lib/cookie.c b/lib/cookie.c index dc319b61111..d10dd572baa 100644 --- a/lib/cookie.c +++ b/lib/cookie.c @@ -1205,7 +1205,6 @@ struct CookieInfo *Curl_cookie_init(struct Curl_easy *data, bool newsession) { struct CookieInfo *c; - char *line = NULL; FILE *handle = NULL; if(!inc) { @@ -1241,16 +1240,14 @@ struct CookieInfo *Curl_cookie_init(struct Curl_easy *data, c->running = FALSE; /* this is not running, this is init */ if(fp) { - - line = malloc(MAX_COOKIE_LINE); - if(!line) - goto fail; - while(Curl_get_line(line, MAX_COOKIE_LINE, fp)) { - char *lineptr = line; + struct dynbuf buf; + Curl_dyn_init(&buf, MAX_COOKIE_LINE); + while(Curl_get_line(&buf, fp)) { + char *lineptr = Curl_dyn_ptr(&buf); bool headerline = FALSE; - if(checkprefix("Set-Cookie:", line)) { + if(checkprefix("Set-Cookie:", lineptr)) { /* This is a cookie line, get it! */ - lineptr = &line[11]; + lineptr += 11; headerline = TRUE; while(*lineptr && ISBLANK(*lineptr)) lineptr++; @@ -1258,7 +1255,7 @@ struct CookieInfo *Curl_cookie_init(struct Curl_easy *data, Curl_cookie_add(data, c, headerline, TRUE, lineptr, NULL, NULL, TRUE); } - free(line); /* free the line buffer */ + Curl_dyn_free(&buf); /* free the line buffer */ /* * Remove expired cookies from the hash. We must make sure to run this @@ -1274,18 +1271,6 @@ struct CookieInfo *Curl_cookie_init(struct Curl_easy *data, c->running = TRUE; /* now, we're running */ return c; - -fail: - free(line); - /* - * Only clean up if we allocated it here, as the original could still be in - * use by a share handle. - */ - if(!inc) - Curl_cookie_cleanup(c); - if(handle) - fclose(handle); - return NULL; /* out of memory */ } /* diff --git a/lib/curl_get_line.c b/lib/curl_get_line.c index 686abe7511b..100207331d8 100644 --- a/lib/curl_get_line.c +++ b/lib/curl_get_line.c @@ -33,14 +33,16 @@ #include "memdebug.h" /* - * Curl_get_line() makes sure to only return complete whole lines that fit in - * 'len' bytes and end with a newline. + * Curl_get_line() makes sure to only return complete whole lines that end + * newlines. */ -char *Curl_get_line(char *buf, int len, FILE *input) +int Curl_get_line(struct dynbuf *buf, FILE *input) { - bool partial = FALSE; + CURLcode result; + char buffer[128]; + Curl_dyn_reset(buf); while(1) { - char *b = fgets(buf, len, input); + char *b = fgets(buffer, sizeof(buffer), input); if(b) { size_t rlen = strlen(b); @@ -48,39 +50,28 @@ char *Curl_get_line(char *buf, int len, FILE *input) if(!rlen) break; - if(b[rlen-1] == '\n') { - /* b is \n terminated */ - if(partial) { - partial = FALSE; - continue; - } - return b; - } - else if(feof(input)) { - if(partial) - /* Line is already too large to return, ignore rest */ - break; + result = Curl_dyn_addn(buf, b, rlen); + if(result) + /* too long line or out of memory */ + return 0; /* error */ - if(rlen + 1 < (size_t) len) { - /* b is EOF terminated, insert missing \n */ - b[rlen] = '\n'; - b[rlen + 1] = '\0'; - return b; - } - else - /* Maximum buffersize reached + EOF - * This line is impossible to add a \n to so we'll ignore it - */ - break; + else if(b[rlen-1] == '\n') + /* end of the line */ + return 1; /* all good */ + + else if(feof(input)) { + /* append a newline */ + result = Curl_dyn_addn(buf, "\n", 1); + if(result) + /* too long line or out of memory */ + return 0; /* error */ + return 1; /* all good */ } - else - /* Maximum buffersize reached */ - partial = TRUE; } else break; } - return NULL; + return 0; } #endif /* if not disabled */ diff --git a/lib/curl_get_line.h b/lib/curl_get_line.h index 0ff32c5c2cb..7907cde8808 100644 --- a/lib/curl_get_line.h +++ b/lib/curl_get_line.h @@ -24,8 +24,9 @@ * ***************************************************************************/ -/* get_line() makes sure to only return complete whole lines that fit in 'len' - * bytes and end with a newline. */ -char *Curl_get_line(char *buf, int len, FILE *input); +#include "dynbuf.h" + +/* Curl_get_line() returns complete lines that end with a newline. */ +int Curl_get_line(struct dynbuf *buf, FILE *input); #endif /* HEADER_CURL_GET_LINE_H */ diff --git a/lib/hsts.c b/lib/hsts.c index 8725a35c168..607755e6ba4 100644 --- a/lib/hsts.c +++ b/lib/hsts.c @@ -511,7 +511,6 @@ static CURLcode hsts_pull(struct Curl_easy *data, struct hsts *h) static CURLcode hsts_load(struct hsts *h, const char *file) { CURLcode result = CURLE_OK; - char *line = NULL; FILE *fp; /* we need a private copy of the file name so that the hsts cache file @@ -523,11 +522,10 @@ static CURLcode hsts_load(struct hsts *h, const char *file) fp = fopen(file, FOPEN_READTEXT); if(fp) { - line = malloc(MAX_HSTS_LINE); - if(!line) - goto fail; - while(Curl_get_line(line, MAX_HSTS_LINE, fp)) { - char *lineptr = line; + struct dynbuf buf; + Curl_dyn_init(&buf, MAX_HSTS_LINE); + while(Curl_get_line(&buf, fp)) { + char *lineptr = Curl_dyn_ptr(&buf); while(*lineptr && ISBLANK(*lineptr)) lineptr++; if(*lineptr == '#') @@ -536,15 +534,10 @@ static CURLcode hsts_load(struct hsts *h, const char *file) hsts_add(h, lineptr); } - free(line); /* free the line buffer */ + Curl_dyn_free(&buf); /* free the line buffer */ fclose(fp); } return result; - -fail: - Curl_safefree(h->filename); - fclose(fp); - return CURLE_OUT_OF_MEMORY; } /* diff --git a/lib/netrc.c b/lib/netrc.c index 038c6dca6a9..cd2a2844e23 100644 --- a/lib/netrc.c +++ b/lib/netrc.c @@ -53,6 +53,8 @@ enum host_lookup_state { #define NETRC_FAILED -1 #define NETRC_SUCCESS 0 +#define MAX_NETRC_LINE 4096 + /* * Returns zero on success. */ @@ -80,13 +82,14 @@ static int parsenetrc(const char *host, file = fopen(netrcfile, FOPEN_READTEXT); if(file) { bool done = FALSE; - char netrcbuffer[4096]; - int netrcbuffsize = (int)sizeof(netrcbuffer); + struct dynbuf buf; + Curl_dyn_init(&buf, MAX_NETRC_LINE); - while(!done && Curl_get_line(netrcbuffer, netrcbuffsize, file)) { + while(!done && Curl_get_line(&buf, file)) { char *tok; char *tok_end; bool quoted; + char *netrcbuffer = Curl_dyn_ptr(&buf); if(state == MACDEF) { if((netrcbuffer[0] == '\n') || (netrcbuffer[0] == '\r')) state = NOTHING; @@ -245,6 +248,7 @@ static int parsenetrc(const char *host, } /* while Curl_get_line() */ out: + Curl_dyn_free(&buf); if(!retcode) { /* success */ if(login_alloc) { diff --git a/tests/unit/unit3200.c b/tests/unit/unit3200.c index 0544bcc938d..6f508ce0702 100644 --- a/tests/unit/unit3200.c +++ b/tests/unit/unit3200.c @@ -69,7 +69,7 @@ static const char *filecontents[] = { "LINE1\n" C4096 "SOME EXTRA TEXT", - /* First and third line should be read */ + /* Only first should be read */ "LINE1\n" C4096 "SOME EXTRA TEXT\n" "LINE3\n", @@ -84,11 +84,13 @@ static const char *filecontents[] = { UNITTEST_START size_t i; + int rc = 0; for(i = 0; i < NUMTESTS; i++) { FILE *fp; - char buf[4096]; + struct dynbuf buf; int len = 4096; char *line; + Curl_dyn_init(&buf, len); fp = fopen(arg, "wb"); abort_unless(fp != NULL, "Cannot open testfile"); @@ -101,65 +103,73 @@ UNITTEST_START fprintf(stderr, "Test %zd...", i); switch(i) { case 0: - line = Curl_get_line(buf, len, fp); + rc = Curl_get_line(&buf, fp); + line = Curl_dyn_ptr(&buf); fail_unless(line && !strcmp("LINE1\n", line), - "First line failed (1)"); - line = Curl_get_line(buf, len, fp); + "First line failed (1)"); + rc = Curl_get_line(&buf, fp); + line = Curl_dyn_ptr(&buf); fail_unless(line && !strcmp("LINE2 NEWLINE\n", line), - "Second line failed (1)"); - line = Curl_get_line(buf, len, fp); - abort_unless(line == NULL, "Missed EOF (1)"); + "Second line failed (1)"); + rc = Curl_get_line(&buf, fp); + abort_unless(!Curl_dyn_len(&buf), "Missed EOF (1)"); break; case 1: - line = Curl_get_line(buf, len, fp); + rc = Curl_get_line(&buf, fp); + line = Curl_dyn_ptr(&buf); fail_unless(line && !strcmp("LINE1\n", line), - "First line failed (2)"); - line = Curl_get_line(buf, len, fp); + "First line failed (2)"); + rc = Curl_get_line(&buf, fp); + line = Curl_dyn_ptr(&buf); fail_unless(line && !strcmp("LINE2 NONEWLINE\n", line), - "Second line failed (2)"); - line = Curl_get_line(buf, len, fp); - abort_unless(line == NULL, "Missed EOF (2)"); + "Second line failed (2)"); + rc = Curl_get_line(&buf, fp); + abort_unless(!Curl_dyn_len(&buf), "Missed EOF (2)"); break; case 2: - line = Curl_get_line(buf, len, fp); + rc = Curl_get_line(&buf, fp); + line = Curl_dyn_ptr(&buf); fail_unless(line && !strcmp("LINE1\n", line), - "First line failed (3)"); - line = Curl_get_line(buf, len, fp); - fail_unless(line == NULL, - "Did not detect max read on EOF (3)"); + "First line failed (3)"); + rc = Curl_get_line(&buf, fp); + fail_unless(!Curl_dyn_len(&buf), + "Did not detect max read on EOF (3)"); break; case 3: - line = Curl_get_line(buf, len, fp); + rc = Curl_get_line(&buf, fp); + line = Curl_dyn_ptr(&buf); fail_unless(line && !strcmp("LINE1\n", line), - "First line failed (4)"); - line = Curl_get_line(buf, len, fp); - fail_unless(line == NULL, - "Did not ignore partial on EOF (4)"); + "First line failed (4)"); + rc = Curl_get_line(&buf, fp); + fail_unless(!Curl_dyn_len(&buf), + "Did not ignore partial on EOF (4)"); break; case 4: - line = Curl_get_line(buf, len, fp); + rc = Curl_get_line(&buf, fp); + line = Curl_dyn_ptr(&buf); fail_unless(line && !strcmp("LINE1\n", line), - "First line failed (5)"); - line = Curl_get_line(buf, len, fp); - fail_unless(line && !strcmp("LINE3\n", line), - "Third line failed (5)"); - line = Curl_get_line(buf, len, fp); - abort_unless(line == NULL, "Missed EOF (5)"); + "First line failed (5)"); + rc = Curl_get_line(&buf, fp); + fail_unless(!Curl_dyn_len(&buf), + "Did not bail out on too long line"); break; case 5: - line = Curl_get_line(buf, len, fp); + rc = Curl_get_line(&buf, fp); + line = Curl_dyn_ptr(&buf); fail_unless(line && !strcmp("LINE1\x1aTEST\n", line), - "Missed/Misinterpreted ^Z (6)"); - line = Curl_get_line(buf, len, fp); - abort_unless(line == NULL, "Missed EOF (6)"); + "Missed/Misinterpreted ^Z (6)"); + rc = Curl_get_line(&buf, fp); + abort_unless(!Curl_dyn_len(&buf), "Missed EOF (6)"); break; default: abort_unless(1, "Unknown case"); break; } + Curl_dyn_free(&buf); fclose(fp); fprintf(stderr, "OK\n"); } + return rc; UNITTEST_STOP #ifdef __GNUC__ From 1d96828582670dc173a5f755689f8d8ba27fcb2a Mon Sep 17 00:00:00 2001 From: Daniel Szmulewicz Date: Wed, 7 Feb 2024 20:13:14 +0800 Subject: [PATCH 297/509] CURLOPT_WRITEFUNCTION.md: typo fix The maximum amount of body data that is passed to the write callback is defined in the curl.h header file Closes #12889 --- docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md index 8957439d339..cd870dbf90a 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md @@ -38,7 +38,7 @@ The data passed to this function is not null-terminated. The callback function is passed as much data as possible in all invokes, but you must not make any assumptions. It may be one byte, it may be -thousands. The maximum amount of body data that is be passed to the write +thousands. The maximum amount of body data that is passed to the write callback is defined in the curl.h header file: *CURL_MAX_WRITE_SIZE* (the usual default is 16K). If CURLOPT_HEADER(3) is enabled, which makes header data get passed to the write callback, you can get up to From 0f0edc283c340e8ddddc763b48d2f835b2270ab4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 15:04:31 +0100 Subject: [PATCH 298/509] curl: exit on config file parser errors Like when trying to import an environment variable that does not exist. Also fix a bug for reading env variables when there is a default value set. Bug: https://curl.se/mail/archive-2024-02/0008.html Reported-by: Brett Buddin Add test 462 to verify. Closes #12862 --- src/tool_parsecfg.c | 9 +++++---- src/var.c | 17 +++++++++++++---- tests/data/Makefile.inc | 1 + tests/data/test462 | 39 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 58 insertions(+), 8 deletions(-) create mode 100644 tests/data/test462 diff --git a/src/tool_parsecfg.c b/src/tool_parsecfg.c index da48700663e..a07d4f07b68 100644 --- a/src/tool_parsecfg.c +++ b/src/tool_parsecfg.c @@ -125,11 +125,11 @@ int parseconfig(const char *filename, struct GlobalConfig *global) int lineno = 0; bool dashed_option; struct curlx_dynbuf buf; - bool fileerror; + bool fileerror = FALSE; curlx_dyn_init(&buf, MAX_CONFIG_LINE_LENGTH); DEBUGASSERT(filename); - while(my_get_line(file, &buf, &fileerror)) { + while(!rc && my_get_line(file, &buf, &fileerror)) { int res; bool alloced_param = FALSE; lineno++; @@ -264,8 +264,9 @@ int parseconfig(const char *filename, struct GlobalConfig *global) res != PARAM_VERSION_INFO_REQUESTED && res != PARAM_ENGINES_REQUESTED) { const char *reason = param2text(res); - warnf(operation->global, "%s:%d: warning: '%s' %s", - filename, lineno, option, reason); + errorf(operation->global, "%s:%d: '%s' %s", + filename, lineno, option, reason); + rc = res; } } diff --git a/src/var.c b/src/var.c index 388d45592f2..74410ad4e01 100644 --- a/src/var.c +++ b/src/var.c @@ -42,6 +42,7 @@ #include "memdebug.h" /* keep this as LAST include */ #define MAX_EXPAND_CONTENT 10000000 +#define MAX_VAR_LEN 128 /* max length of a name */ static char *Memdup(const char *data, size_t len) { @@ -233,7 +234,7 @@ ParameterError varexpand(struct GlobalConfig *global, line = &envp[2]; } else if(envp) { - char name[128]; + char name[MAX_VAR_LEN]; size_t nlen; size_t i; char *funcp; @@ -393,6 +394,7 @@ ParameterError setvariable(struct GlobalConfig *global, ParameterError err = PARAM_OK; bool import = FALSE; char *ge = NULL; + char buf[MAX_VAR_LEN]; if(*input == '%') { import = TRUE; @@ -402,12 +404,20 @@ ParameterError setvariable(struct GlobalConfig *global, while(*line && (ISALNUM(*line) || (*line == '_'))) line++; nlen = line - name; - if(!nlen || (nlen > 128)) { + if(!nlen || (nlen >= MAX_VAR_LEN)) { warnf(global, "Bad variable name length (%zd), skipping", nlen); return PARAM_OK; } if(import) { - ge = curl_getenv(name); + /* this does not use curl_getenv() because we want "" support for blank + content */ + if(*line) { + /* if there is a default action, we need to copy the name */ + memcpy(buf, name, nlen); + buf[nlen] = 0; + name = buf; + } + ge = getenv(name); if(!*line && !ge) { /* no assign, no variable, fail */ errorf(global, "Variable '%s' import fail, not set", name); @@ -459,6 +469,5 @@ ParameterError setvariable(struct GlobalConfig *global, if(contalloc) free(content); } - curl_free(ge); return err; } diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index cd393da750f..1475cc3b95e 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -73,6 +73,7 @@ test426 test427 test428 test429 test430 test431 test432 test433 test434 \ test435 test436 test437 test438 test439 test440 test441 test442 test443 \ test444 test445 test446 test447 test448 test449 test450 test451 test452 \ test453 test454 test455 test456 test457 test458 test459 test460 test461 \ +test462 \ \ test490 test491 test492 test493 test494 test495 test496 test497 test498 \ test499 test500 test501 test502 test503 test504 test505 test506 test507 \ diff --git a/tests/data/test462 b/tests/data/test462 new file mode 100644 index 00000000000..24c414ef3f1 --- /dev/null +++ b/tests/data/test462 @@ -0,0 +1,39 @@ + + + +variables +--config + + + +# +# Server-side + + + +# +# Client-side + + +none + + +Missing environment variables in config file + + +variable %MISSING +expand-data {{MISSING}} + + +http://%HOSTIP:%HTTPPORT/%TESTNUMBER -K %LOGDIR/cmd + + + +# +# Verify data after the test has been "shot" + + +26 + + + From 7cf8414fabc3063cc3d2121eacec4a6daa4164a8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2024 17:04:28 +0100 Subject: [PATCH 299/509] tests: support setting/using blank content env variables - test450: remove --config from the keywords - test2080: change return code - test428: add --config as a keyword - test428: disable on Windows due to CI problems --- tests/FILEFORMAT.md | 7 ++++++- tests/data/test2080 | Bin 20680 -> 20688 bytes tests/data/test428 | 9 +++++++++ tests/data/test450 | 1 - tests/runner.pm | 17 +++++++++++------ 5 files changed, 26 insertions(+), 8 deletions(-) diff --git a/tests/FILEFORMAT.md b/tests/FILEFORMAT.md index 5a8e7832323..b594fc11308 100644 --- a/tests/FILEFORMAT.md +++ b/tests/FILEFORMAT.md @@ -522,9 +522,14 @@ Brief test case description, shown when the test runs. ### `` variable1=contents1 variable2=contents2 + variable3 Set the given environment variables to the specified value before the actual -command is run. They are cleared again after the command has been run. +command is run. They are restored back to their former values again after the +command has been run. + +If the variable name has no assignment, no `=`, then that variable is just +deleted. ### `` Command line to run. diff --git a/tests/data/test2080 b/tests/data/test2080 index 7f08385b6f3e4626a0346347861893bfa2d8de14..c3792f43de0c73f74ebc8bbfe31ed70d9e6260c2 100644 GIT binary patch delta 71 zcmX@HknzGo#tp>*mZin1DGK=oC7Jno3YmEdB^jv-$@zI{ndu5?nK`KnnZ*hv`S}Vt b`FZJFHmOBL`9;b3DXDf`MrM*hM_?|3Yo HTTP variables +--config @@ -28,6 +29,14 @@ Funny-head: yesyes # # Client-side + +# For unknown reasons, a number of CI jobs on Appveyor keep returning NULL to +# getenv() for the blank environment variable which makes the test fail. +# Unfortunately, this makes me disable the test completely on Windows. + + +!win32 + http diff --git a/tests/data/test450 b/tests/data/test450 index a6fa641036d..5dcfb85ce67 100644 --- a/tests/data/test450 +++ b/tests/data/test450 @@ -2,7 +2,6 @@ HTTP ---config variables diff --git a/tests/runner.pm b/tests/runner.pm index c0fb40cb3db..645905e5f69 100644 --- a/tests/runner.pm +++ b/tests/runner.pm @@ -648,15 +648,15 @@ sub singletest_setenv { my @setenv = getpart("client", "setenv"); foreach my $s (@setenv) { chomp $s; - if($s =~ /([^=]*)=(.*)/) { + if($s =~ /([^=]*)(.*)/) { my ($var, $content) = ($1, $2); # remember current setting, to restore it once test runs $oldenv{$var} = ($ENV{$var})?"$ENV{$var}":'notset'; - # set new value - if(!$content) { - delete $ENV{$var} if($ENV{$var}); - } - else { + + if($content =~ /^=(.*)/) { + # assign it + $content = $1; + if($var =~ /^LD_PRELOAD/) { if(exe_ext('TOOL') && (exe_ext('TOOL') eq '.exe')) { logmsg "Skipping LD_PRELOAD due to lack of OS support\n" if($verbose); @@ -670,6 +670,11 @@ sub singletest_setenv { $ENV{$var} = "$content"; logmsg "setenv $var = $content\n" if($verbose); } + else { + # remove it + delete $ENV{$var} if($ENV{$var}); + } + } } if($proxy_address) { From ed09a99af57200643d5ae001e815eeab9ffe3f84 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 1 Feb 2024 18:15:50 +0100 Subject: [PATCH 300/509] vtls: revert "receive max buffer" + add test case - add test_05_04 for requests using http/1.0, http/1.1 and h2 against an Apache resource that does an unclean TLS shutdown. - revert special workarund in openssl.c for suppressing shutdown errors on multiplexed connections - vlts.c restore to its state before 9a90c9dd64d2f03601833a70786d485851bd1b53 Fixes #12885 Fixes #12844 Closes #12848 --- lib/vtls/vtls.c | 27 +++++-------------- tests/http/test_05_errors.py | 27 +++++++++++++++++++ tests/http/testenv/httpd.py | 7 ++++- .../http/testenv/mod_curltest/mod_curltest.c | 2 +- 4 files changed, 40 insertions(+), 23 deletions(-) diff --git a/lib/vtls/vtls.c b/lib/vtls/vtls.c index e928ba5d079..f654a9749cd 100644 --- a/lib/vtls/vtls.c +++ b/lib/vtls/vtls.c @@ -1715,32 +1715,17 @@ static ssize_t ssl_cf_recv(struct Curl_cfilter *cf, { struct cf_call_data save; ssize_t nread; - size_t ntotal = 0; CF_DATA_SAVE(save, cf, data); *err = CURLE_OK; - /* Do receive until we fill the buffer somehwhat or EGAIN, error or EOF */ - while(!ntotal || (len - ntotal) > (4*1024)) { + nread = Curl_ssl->recv_plain(cf, data, buf, len, err); + if(nread > 0) { + DEBUGASSERT((size_t)nread <= len); + } + else if(nread == 0) { + /* eof */ *err = CURLE_OK; - nread = Curl_ssl->recv_plain(cf, data, buf + ntotal, len - ntotal, err); - if(nread < 0) { - if(*err == CURLE_AGAIN && ntotal > 0) { - /* we EAGAINed after having reed data, return the success amount */ - *err = CURLE_OK; - break; - } - /* we have a an error to report */ - goto out; - } - else if(nread == 0) { - /* eof */ - break; - } - ntotal += (size_t)nread; - DEBUGASSERT((size_t)ntotal <= len); } - nread = (ssize_t)ntotal; -out: CURL_TRC_CF(data, cf, "cf_recv(len=%zu) -> %zd, %d", len, nread, *err); CF_DATA_RESTORE(cf, save); diff --git a/tests/http/test_05_errors.py b/tests/http/test_05_errors.py index b59f3f177a7..68e49f7362a 100644 --- a/tests/http/test_05_errors.py +++ b/tests/http/test_05_errors.py @@ -108,3 +108,30 @@ def test_05_03_required(self, env: Env, httpd, nghttpx, repeat): r.check_response(http_status=200, count=1) # check that we did a downgrade assert r.stats[0]['http_version'] == '1.1', r.dump_logs() + + # On the URL used here, Apache is doing an "unclean" TLS shutdown, + # meaning it sends no shutdown notice and just closes TCP. + # The HTTP response delivers a body without Content-Length. We expect: + # - http/1.0 to fail since it relies on a clean connection close to + # detect the end of the body + # - http/1.1 to work since it will used "chunked" transfer encoding + # and stop receiving when that signals the end + # - h2 to work since it will signal the end of the response before + # and not see the "unclean" close either + @pytest.mark.parametrize("proto", ['http/1.0', 'http/1.1', 'h2']) + def test_05_04_unclean_tls_shutdown(self, env: Env, httpd, nghttpx, repeat, proto): + if proto == 'h3' and not env.have_h3(): + pytest.skip("h3 not supported") + count = 10 if proto == 'h2' else 1 + curl = CurlClient(env=env) + url = f'https://{env.authority_for(env.domain1, proto)}'\ + f'/curltest/shutdown_unclean?id=[0-{count-1}]&chunks=4' + r = curl.http_download(urls=[url], alpn_proto=proto, extra_args=[ + '--parallel', + ]) + if proto == 'http/1.0': + r.check_exit_code(56) + else: + r.check_exit_code(0) + r.check_response(http_status=200, count=count) + diff --git a/tests/http/testenv/httpd.py b/tests/http/testenv/httpd.py index 79497c5b305..c04c22699a6 100644 --- a/tests/http/testenv/httpd.py +++ b/tests/http/testenv/httpd.py @@ -47,7 +47,7 @@ class Httpd: 'authn_core', 'authn_file', 'authz_user', 'authz_core', 'authz_host', 'auth_basic', 'auth_digest', - 'alias', 'env', 'filter', 'headers', 'mime', + 'alias', 'env', 'filter', 'headers', 'mime', 'setenvif', 'socache_shmcb', 'rewrite', 'http2', 'ssl', 'proxy', 'proxy_http', 'proxy_connect', 'mpm_event', @@ -389,6 +389,11 @@ def _curltest_conf(self, servername) -> List[str]: f' ', f' SetHandler curltest-1_1-required', f' ', + f' ', + f' SetHandler curltest-tweak', + f' SetEnv force-response-1.0 1', + f' ', + f' SetEnvIf Request_URI "/shutdown_unclean" ssl-unclean=1', ]) if self._auth_digest: lines.extend([ diff --git a/tests/http/testenv/mod_curltest/mod_curltest.c b/tests/http/testenv/mod_curltest/mod_curltest.c index ff1983d17fd..a066be52228 100644 --- a/tests/http/testenv/mod_curltest/mod_curltest.c +++ b/tests/http/testenv/mod_curltest/mod_curltest.c @@ -347,7 +347,7 @@ static int curltest_tweak_handler(request_rec *r) "request, %s", r->args? r->args : "(no args)"); r->status = http_status; r->clength = -1; - r->chunked = 1; + r->chunked = (r->proto_num >= HTTP_VERSION(1,1)); apr_table_setn(r->headers_out, "request-id", request_id); apr_table_unset(r->headers_out, "Content-Length"); /* Discourage content-encodings */ From d1c9f38b8c5c531e12166a6537d0ffab52ac197e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 7 Feb 2024 14:06:56 +0100 Subject: [PATCH 301/509] lib582: remove code causing warning that is never run The previous realloc code in this code could trigger a compiler warning, but since that code path cannot happen in normal circumstances it now instead exits with an error message there. Ref: #12887 Closes #12890 --- tests/libtest/lib582.c | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/tests/libtest/lib582.c b/tests/libtest/lib582.c index a50f8a429f7..8fe6402a49c 100644 --- a/tests/libtest/lib582.c +++ b/tests/libtest/lib582.c @@ -83,16 +83,10 @@ static void addFd(struct Sockets *sockets, curl_socket_t fd, const char *what) return; sockets->max_count = 20; } - else if(sockets->count + 1 > sockets->max_count) { - curl_socket_t *oldptr = sockets->sockets; - sockets->sockets = realloc(oldptr, sizeof(curl_socket_t) * - (sockets->max_count + 20)); - if(!sockets->sockets) { - /* cleanup in test_cleanup */ - sockets->sockets = oldptr; - return; - } - sockets->max_count += 20; + else if(sockets->count >= sockets->max_count) { + /* this can't happen in normal cases */ + fprintf(stderr, "too many file handles error\n"); + exit(2); } /* * Add file descriptor to array. From ef4bd8d6c0820ba96c37aae5857accad87ed9a90 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 7 Feb 2024 14:28:38 +0100 Subject: [PATCH 302/509] curl: when allocating variables, add the name into the struct This saves the name from being an extra separate allocation. Closes #12891 --- src/var.c | 34 ++++++++++++++-------------------- src/var.h | 2 +- 2 files changed, 15 insertions(+), 21 deletions(-) diff --git a/src/var.c b/src/var.c index 74410ad4e01..4dad09989dc 100644 --- a/src/var.c +++ b/src/var.c @@ -63,7 +63,6 @@ void varcleanup(struct GlobalConfig *global) struct var *t = list; list = list->next; free((char *)t->content); - free((char *)t->name); free(t); } } @@ -343,7 +342,7 @@ ParameterError varexpand(struct GlobalConfig *global, } /* - * Created in a way that is not revealing how variables is actually stored so + * Created in a way that is not revealing how variables are actually stored so * that we can improve this if we want better performance when managing many * at a later point. */ @@ -356,29 +355,24 @@ static ParameterError addvariable(struct GlobalConfig *global, { struct var *p; const struct var *check = varcontent(global, name, nlen); + DEBUGASSERT(nlen); if(check) notef(global, "Overwriting variable '%s'", check->name); - p = calloc(1, sizeof(struct var)); - if(!p) - return PARAM_NO_MEM; - - p->name = Memdup(name, nlen); - if(!p->name) - goto err; + p = calloc(1, sizeof(struct var) + nlen); + if(p) { + memcpy(p->name, name, nlen); - p->content = contalloc ? content: Memdup(content, clen); - if(!p->content) - goto err; - p->clen = clen; + p->content = contalloc ? content: Memdup(content, clen); + if(p->content) { + p->clen = clen; - p->next = global->variables; - global->variables = p; - return PARAM_OK; -err: - free((char *)p->content); - free((char *)p->name); - free(p); + p->next = global->variables; + global->variables = p; + return PARAM_OK; + } + free(p); + } return PARAM_NO_MEM; } diff --git a/src/var.h b/src/var.h index 4a71943a3c2..2ea9797275a 100644 --- a/src/var.h +++ b/src/var.h @@ -29,9 +29,9 @@ struct var { struct var *next; - const char *name; const char *content; size_t clen; /* content length */ + char name[1]; /* allocated as part of the struct */ }; struct GlobalConfig; From 505f43c9476da380055c63a02e4f2f0d3ed9ad7e Mon Sep 17 00:00:00 2001 From: Karthikdasari0423 <92445174+Karthikdasari0423@users.noreply.github.com> Date: Thu, 8 Feb 2024 13:32:05 +0530 Subject: [PATCH 303/509] HTTP3.md: remove quiche word in Openssl 3.2 Closes #12893 --- docs/HTTP3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/HTTP3.md b/docs/HTTP3.md index b09fb94e57f..5d41e705abf 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -198,7 +198,7 @@ Build curl: # OpenSSL version -quiche QUIC support is **EXPERIMENTAL** +QUIC support is **EXPERIMENTAL** Build OpenSSL 3.2.0 From cf5f604229bb9fab4421ec0e498aaf2767feb335 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 8 Feb 2024 07:58:09 +0100 Subject: [PATCH 304/509] docs: make sure curl.1 is included in dist tarballs Ref: https://github.com/curl/curl/issues/12832#issuecomment-1933271873 Closes #12892 --- docs/Makefile.am | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index d9bdd176cce..96c876019aa 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -34,7 +34,7 @@ endif # 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_DOCS) +noinst_man_MANS = $(MK_CA_DOCS) dist_man_MANS = $(CURLCONF_DOCS) $(MK_CA_DOCS) CURLPAGES = curl-config.md mk-ca-bundle.md @@ -133,3 +133,6 @@ curl-config.1: curl-config.md distclean: rm -f $(CLEANFILES) + +dist-hook: + cp $(builddir)/curl.1 $(builddir)/curl.1.dist From e52cddb956cb59ae04692901d6fbf670f5e115ab Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 8 Feb 2024 15:00:00 +0100 Subject: [PATCH 305/509] TODO: align the TOC with the header --- docs/TODO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TODO b/docs/TODO index 045e5ed9783..dafd87a2f60 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 From 5a4b2f93392c0fb1171dd17b67b05f39c6d45abc Mon Sep 17 00:00:00 2001 From: Karthikdasari0423 <92445174+Karthikdasari0423@users.noreply.github.com> Date: Thu, 8 Feb 2024 17:08:16 +0530 Subject: [PATCH 306/509] HTTP3.md: adjust the OpenSSL QUIC install instructions tried installing with old steps but failed tried with newly added setps and able to build ``` root@ubuntu:~/curl# ./src/curl -V /root/curl/src/.libs/curl: /lib/x86_64-linux-gnu/libssl.so.3: version `OPENSSL_3.2.0' not found (required by /root/curl/lib/.libs/libcurl.so.4) root@ubuntu:~/curl# ``` ``` root@ubuntu:~/curl# ./src/curl -V curl 8.6.1-DEV (x86_64-pc-linux-gnu) libcurl/8.6.1-DEV OpenSSL/3.2.0 zlib/1.2.11 brotli/1.0.9 libpsl/0.21.0 nghttp3/1.1.0 OpenLDAP/2.5.16 Release-Date: [unreleased] Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp Features: alt-svc AsynchDNS brotli HSTS HTTP3 HTTPS-proxy IPv6 Largefile libz NTLM PSL SSL threadsafe TLS-SRP UnixSockets root@ubuntu:~/curl# ``` Closes #12896 --- docs/HTTP3.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 5d41e705abf..75a92fa316e 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -206,6 +206,7 @@ Build OpenSSL 3.2.0 % 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 @@ -213,6 +214,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 @@ -224,7 +226,7 @@ Build curl: % git clone https://github.com/curl/curl % cd curl % autoreconf -fi - % ./configure --with-openssl= --with-openssl-quic --with-nghttp3= + % LDFLAGS="-Wl,-rpath,/lib" ./configure --with-openssl= --with-openssl-quic --with-nghttp3= % make % make install From 6984aa3a45a9a31b35e41e03e2dd32b8c2c97152 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 8 Feb 2024 17:52:29 +0100 Subject: [PATCH 307/509] ftp: tracing improvements - trace socketindex for connection filters when not the first - trace socket fd in tcp - trace pollset adjusts in vtls Closes #12902 --- lib/cf-socket.c | 11 +++++++---- lib/curl_trc.c | 6 +++++- lib/vtls/vtls.c | 4 ++++ 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/lib/cf-socket.c b/lib/cf-socket.c index 742902f1b9b..33ca7e78180 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -880,8 +880,9 @@ static ssize_t nw_in_read(void *reader_ctx, nread = -1; } } - CURL_TRC_CF(rctx->data, rctx->cf, "nw_in_read(len=%zu) -> %d, err=%d", - len, (int)nread, *err); + CURL_TRC_CF(rctx->data, rctx->cf, "nw_in_read(len=%zu, fd=%" + CURL_FORMAT_SOCKET_T ") -> %d, err=%d", + len, ctx->sock, (int)nread, *err); return nread; } @@ -1248,11 +1249,13 @@ static void cf_socket_adjust_pollset(struct Curl_cfilter *cf, if(ctx->sock != CURL_SOCKET_BAD) { if(!cf->connected) { Curl_pollset_set_out_only(data, ps, ctx->sock); - CURL_TRC_CF(data, cf, "adjust_pollset(!connected) -> %d socks", ps->num); + CURL_TRC_CF(data, cf, "adjust_pollset, !connected, POLLOUT fd=%" + CURL_FORMAT_SOCKET_T, ctx->sock); } else if(!ctx->active) { Curl_pollset_add_in(data, ps, ctx->sock); - CURL_TRC_CF(data, cf, "adjust_pollset(!active) -> %d socks", ps->num); + CURL_TRC_CF(data, cf, "adjust_pollset, !active, POLLIN fd=%" + CURL_FORMAT_SOCKET_T, ctx->sock); } } } diff --git a/lib/curl_trc.c b/lib/curl_trc.c index b8dccc41937..2f7fb65fdd0 100644 --- a/lib/curl_trc.c +++ b/lib/curl_trc.c @@ -134,7 +134,11 @@ void Curl_trc_cf_infof(struct Curl_easy *data, struct Curl_cfilter *cf, va_list ap; int len; char buffer[MAXINFO + 2]; - len = msnprintf(buffer, MAXINFO, "[%s] ", cf->cft->name); + if(cf->sockindex) + len = msnprintf(buffer, MAXINFO, "[%s-%d] ", + cf->cft->name, cf->sockindex); + else + len = msnprintf(buffer, MAXINFO, "[%s] ", cf->cft->name); va_start(ap, fmt); len += mvsnprintf(buffer + len, MAXINFO - len, fmt, ap); va_end(ap); diff --git a/lib/vtls/vtls.c b/lib/vtls/vtls.c index f654a9749cd..51596d80b8f 100644 --- a/lib/vtls/vtls.c +++ b/lib/vtls/vtls.c @@ -774,9 +774,13 @@ void Curl_ssl_adjust_pollset(struct Curl_cfilter *cf, struct Curl_easy *data, if(sock != CURL_SOCKET_BAD) { if(connssl->connecting_state == ssl_connect_2_writing) { Curl_pollset_set_out_only(data, ps, sock); + CURL_TRC_CF(data, cf, "adjust_pollset, POLLOUT fd=%" + CURL_FORMAT_SOCKET_T, sock); } else { Curl_pollset_set_in_only(data, ps, sock); + CURL_TRC_CF(data, cf, "adjust_pollset, POLLIN fd=%" + CURL_FORMAT_SOCKET_T, sock); } } } From e7fd32b9ac3b1f3bbc6fe4d90fda3ce9fb42b62f Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 6 Feb 2024 11:56:35 +0100 Subject: [PATCH 308/509] ftp: do lineend conversions in client writer - remove the ftp special handling from sendf.c - let ftp_do() add a client writer that does the linened conversions - change the lineend conversion to no longer modify the passed buffer, but write smaller chunks to the next cwriter instead. The inefficiency of this will be mitigated once we add output buffering for all client writes. Closes #12878 --- lib/ftp.c | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++ lib/sendf.c | 95 ------------------------------------------- lib/urldata.h | 2 - 3 files changed, 110 insertions(+), 97 deletions(-) diff --git a/lib/ftp.c b/lib/ftp.c index 9c0f6fb1770..e0590a61eb8 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -255,6 +255,98 @@ static void freedirs(struct ftp_conn *ftpc) Curl_safefree(ftpc->newhost); } +#ifdef CURL_DO_LINEEND_CONV +/*********************************************************************** + * + * Lineend Conversions + * On ASCII transfers, e.g. directory listings, we might get lines + * ending in '\r\n' and we prefer just '\n'. + * We might also get a lonely '\r' which we convert into a '\n'. + */ +struct ftp_cw_lc_ctx { + struct Curl_cwriter super; + bool newline_pending; +}; + +static CURLcode ftp_cw_lc_write(struct Curl_easy *data, + struct Curl_cwriter *writer, int type, + const char *buf, size_t blen) +{ + static char nl = '\n'; + struct ftp_cw_lc_ctx *ctx = (struct ftp_cw_lc_ctx *)writer; + + if(!(type & CLIENTWRITE_BODY) || + data->conn->proto.ftpc.transfertype != 'A') + return Curl_cwriter_write(data, writer->next, type, buf, blen); + + /* ASCII mode BODY data, convert lineends */ + while(blen) { + /* do not pass EOS when writing parts */ + int chunk_type = (type & ~CLIENTWRITE_EOS); + const char *cp; + size_t chunk_len; + CURLcode result; + + if(ctx->newline_pending) { + if(buf[0] != '\n') { + /* previous chunk ended in '\r' and we do not see a '\n' in this one, + * need to write a newline. */ + result = Curl_cwriter_write(data, writer->next, chunk_type, &nl, 1); + if(result) + return result; + } + /* either we just wrote the newline or it is part of the next + * chunk of bytes we write. */ + data->state.crlf_conversions++; + ctx->newline_pending = FALSE; + } + + cp = memchr(buf, '\r', blen); + if(!cp) + break; + + /* write the bytes before the '\r', excluding the '\r' */ + chunk_len = cp - buf; + if(chunk_len) { + result = Curl_cwriter_write(data, writer->next, chunk_type, + buf, chunk_len); + if(result) + return result; + } + /* skip the '\r', we now have a newline pending */ + buf = cp + 1; + blen = blen - chunk_len - 1; + ctx->newline_pending = TRUE; + } + + /* Any remaining data does not contain a '\r' */ + if(blen) { + DEBUGASSERT(!ctx->newline_pending); + return Curl_cwriter_write(data, writer->next, type, buf, blen); + } + else if(type & CLIENTWRITE_EOS) { + /* EndOfStream, if we have a trailing cr, now is the time to write it */ + if(ctx->newline_pending) { + ctx->newline_pending = FALSE; + data->state.crlf_conversions++; + return Curl_cwriter_write(data, writer->next, type, &nl, 1); + } + /* Always pass on the EOS type indicator */ + return Curl_cwriter_write(data, writer->next, type, buf, 0); + } + return CURLE_OK; +} + +static const struct Curl_cwtype ftp_cw_lc = { + "ftp-lineconv", + NULL, + Curl_cwriter_def_init, + ftp_cw_lc_write, + Curl_cwriter_def_close, + sizeof(struct ftp_cw_lc_ctx) +}; + +#endif /* CURL_DO_LINEEND_CONV */ /*********************************************************************** * * AcceptServerConnect() @@ -4035,6 +4127,24 @@ static CURLcode ftp_do(struct Curl_easy *data, bool *done) *done = FALSE; /* default to false */ ftpc->wait_data_conn = FALSE; /* default to no such wait */ +#ifdef CURL_DO_LINEEND_CONV + { + /* FTP data may need conversion. */ + struct Curl_cwriter *ftp_lc_writer; + + result = Curl_cwriter_create(&ftp_lc_writer, data, &ftp_cw_lc, + CURL_CW_CONTENT_DECODE); + if(result) + return result; + + result = Curl_cwriter_add(data, ftp_lc_writer); + if(result) { + Curl_cwriter_free(data, ftp_lc_writer); + return result; + } + } +#endif /* CURL_DO_LINEEND_CONV */ + if(data->state.wildcardmatch) { result = wc_statemach(data); if(data->wildcard->state == CURLWC_SKIP || diff --git a/lib/sendf.c b/lib/sendf.c index 60ac0742ccc..8accc179648 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -61,88 +61,6 @@ static CURLcode do_init_stack(struct Curl_easy *data); -#if defined(CURL_DO_LINEEND_CONV) && !defined(CURL_DISABLE_FTP) -/* - * convert_lineends() changes CRLF (\r\n) end-of-line markers to a single LF - * (\n), with special processing for CRLF sequences that are split between two - * blocks of data. Remaining, bare CRs are changed to LFs. The possibly new - * size of the data is returned. - */ -static size_t convert_lineends(struct Curl_easy *data, - char *startPtr, size_t size) -{ - char *inPtr, *outPtr; - - /* sanity check */ - if(!startPtr || (size < 1)) { - return size; - } - - if(data->state.prev_block_had_trailing_cr) { - /* The previous block of incoming data - had a trailing CR, which was turned into a LF. */ - if(*startPtr == '\n') { - /* This block of incoming data starts with the - previous block's LF so get rid of it */ - memmove(startPtr, startPtr + 1, size-1); - size--; - /* and it wasn't a bare CR but a CRLF conversion instead */ - data->state.crlf_conversions++; - } - data->state.prev_block_had_trailing_cr = FALSE; /* reset the flag */ - } - - /* find 1st CR, if any */ - inPtr = outPtr = memchr(startPtr, '\r', size); - if(inPtr) { - /* at least one CR, now look for CRLF */ - while(inPtr < (startPtr + size-1)) { - /* note that it's size-1, so we'll never look past the last byte */ - if(memcmp(inPtr, "\r\n", 2) == 0) { - /* CRLF found, bump past the CR and copy the NL */ - inPtr++; - *outPtr = *inPtr; - /* keep track of how many CRLFs we converted */ - data->state.crlf_conversions++; - } - else { - if(*inPtr == '\r') { - /* lone CR, move LF instead */ - *outPtr = '\n'; - } - else { - /* not a CRLF nor a CR, just copy whatever it is */ - *outPtr = *inPtr; - } - } - outPtr++; - inPtr++; - } /* end of while loop */ - - if(inPtr < startPtr + size) { - /* handle last byte */ - if(*inPtr == '\r') { - /* deal with a CR at the end of the buffer */ - *outPtr = '\n'; /* copy a NL instead */ - /* note that a CRLF might be split across two blocks */ - data->state.prev_block_had_trailing_cr = TRUE; - } - else { - /* copy last byte */ - *outPtr = *inPtr; - } - outPtr++; - } - if(outPtr < startPtr + size) - /* tidy up by null terminating the now shorter data */ - *outPtr = '\0'; - - return (outPtr - startPtr); - } - return size; -} -#endif /* CURL_DO_LINEEND_CONV && !CURL_DISABLE_FTP */ - /* * Curl_nwrite() is an internal write function that sends data to the * server. Works with a socket index for the connection. @@ -376,25 +294,12 @@ static CURLcode chop_write(struct Curl_easy *data, The bit pattern defines to what "streams" to write to. Body and/or header. The defines are in sendf.h of course. - - If CURL_DO_LINEEND_CONV is enabled, data is converted IN PLACE to the - local character encoding. This is a problem and should be changed in - the future to leave the original data alone. */ CURLcode Curl_client_write(struct Curl_easy *data, int type, char *buf, size_t blen) { CURLcode result; -#if !defined(CURL_DISABLE_FTP) && defined(CURL_DO_LINEEND_CONV) - /* FTP data may need conversion. */ - if((type & CLIENTWRITE_BODY) && - (data->conn->handler->protocol & PROTO_FAMILY_FTP) && - data->conn->proto.ftpc.transfertype == 'A') { - /* convert end-of-line markers */ - blen = convert_lineends(data, buf, blen); - } -#endif /* it is one of those, at least */ DEBUGASSERT(type & (CLIENTWRITE_BODY|CLIENTWRITE_HEADER|CLIENTWRITE_INFO)); /* BODY is only BODY (with optional EOS) */ diff --git a/lib/urldata.h b/lib/urldata.h index 9dcccc7039b..49aed15fda7 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1387,8 +1387,6 @@ struct UrlState { #if !defined(_WIN32) && !defined(MSDOS) && !defined(__EMX__) /* do FTP line-end conversions on most platforms */ #define CURL_DO_LINEEND_CONV - /* for FTP downloads: track CRLF sequences that span blocks */ - BIT(prev_block_had_trailing_cr); /* for FTP downloads: how many CRLFs did we converted to LFs? */ curl_off_t crlf_conversions; #endif From c54d0ff6b3b1d2ff64af48e8955ce63efd4d162f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 8 Feb 2024 23:41:50 +0100 Subject: [PATCH 309/509] write-out.md: clarify error handling details - it gets used even if the transfer fails - it does not cause error to be returned even if it fails Closes #12909 --- docs/cmdline-opts/write-out.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/cmdline-opts/write-out.md b/docs/cmdline-opts/write-out.md index 5af8ebbaba2..ac4b7d03ff3 100644 --- a/docs/cmdline-opts/write-out.md +++ b/docs/cmdline-opts/write-out.md @@ -18,10 +18,10 @@ Example: # `--write-out` Make curl display information on stdout after a completed transfer. The format -is a string that may contain plain text mixed with any number of -variables. The format can be specified as a literal "string", or you can have -curl read the format from a file with "@filename" and to tell curl to read the -format from stdin you write "@-". +is a string that may contain plain text mixed with any number of variables. +The format can be specified as a literal "string", or you can have curl read +the format from a file with "@filename" and to tell curl to read the format +from stdin you write "@-". The variables present in the output format are substituted by the value or text that curl thinks fit, as described below. All variables are specified as @@ -45,11 +45,17 @@ the file name cannot be created, curl leaves the output destination to the one used prior to the *%output{}* instruction. Use *%output{\>\>name}* to append data to an existing file. -**NOTE:** -In Windows the %-symbol is a special symbol used to expand environment -variables. In batch files all occurrences of % must be doubled when using this -option to properly escape. If this option is used at the command prompt then -the % cannot be escaped and unintended expansion is possible. +This output is done independently of if the file transfer was successful or +not. + +If the specified action or output specified with this option fails in any way, +it will not make curl return a (different) error. + +**NOTE:** On Windows, the %-symbol is a special symbol used to expand +environment variables. In batch files, all occurrences of % must be doubled +when using this option to properly escape. If this option is used at the +command prompt then the % cannot be escaped and unintended expansion is +possible. The variables available are: From 476adfeac019edec71d67e144f184f4dbf1a46fb Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 26 Jan 2024 12:05:08 +0100 Subject: [PATCH 310/509] multi: add xfer_buf to multi handle - can be borrowed by transfer during recv-write operation - needs to be released before borrowing again - adjustis size to `data->set.buffer_size` - used in transfer.c readwrite_data() Closes #12805 --- docs/libcurl/opts/CURLOPT_BUFFERSIZE.md | 5 ++ lib/conncache.c | 6 -- lib/easy.c | 1 - lib/multi.c | 78 ++++++++++++++++++++++--- lib/multihandle.h | 5 ++ lib/multiif.h | 24 ++++++++ lib/setopt.c | 3 - lib/transfer.c | 14 +++-- lib/url.c | 1 - lib/urldata.h | 1 - 10 files changed, 113 insertions(+), 25 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md index 1faebeef54b..b4759ea6534 100644 --- a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md @@ -42,6 +42,11 @@ transfer as that may lead to unintended consequences. The maximum size was 512kB until 7.88.0. +Starting in libcurl 8.7.0, there is just a single transfer buffer allocated +per multi handle. This buffer is used by all easy handles added to a multi +handle no matter how many parallel transfers there are. The buffer remains +allocated as long as there are active transfers. + # DEFAULT CURL_MAX_WRITE_SIZE (16kB) diff --git a/lib/conncache.c b/lib/conncache.c index 66f18ecb850..63128e1a343 100644 --- a/lib/conncache.c +++ b/lib/conncache.c @@ -395,8 +395,6 @@ bool Curl_conncache_return_conn(struct Curl_easy *data, important that details from this (unrelated) disconnect does not taint meta-data in the data handle. */ struct conncache *connc = data->state.conn_cache; - connc->closure_handle->state.buffer = data->state.buffer; - connc->closure_handle->set.buffer_size = data->set.buffer_size; Curl_disconnect(connc->closure_handle, conn_candidate, /* dead_connection */ FALSE); } @@ -522,12 +520,9 @@ Curl_conncache_extract_oldest(struct Curl_easy *data) void Curl_conncache_close_all_connections(struct conncache *connc) { struct connectdata *conn; - char buffer[READBUFFER_MIN + 1]; SIGPIPE_VARIABLE(pipe_st); if(!connc->closure_handle) return; - connc->closure_handle->state.buffer = buffer; - connc->closure_handle->set.buffer_size = READBUFFER_MIN; conn = conncache_find_first_connection(connc); while(conn) { @@ -541,7 +536,6 @@ void Curl_conncache_close_all_connections(struct conncache *connc) conn = conncache_find_first_connection(connc); } - connc->closure_handle->state.buffer = NULL; sigpipe_ignore(connc->closure_handle, &pipe_st); Curl_hostcache_clean(connc->closure_handle, diff --git a/lib/easy.c b/lib/easy.c index 067b6d7b69f..763d43b9259 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -1021,7 +1021,6 @@ struct Curl_easy *curl_easy_duphandle(struct Curl_easy *data) #ifndef CURL_DISABLE_COOKIES free(outcurl->cookies); #endif - free(outcurl->state.buffer); Curl_dyn_free(&outcurl->state.headerb); Curl_altsvc_cleanup(&outcurl->asi); Curl_hsts_cleanup(&outcurl->hsts); diff --git a/lib/multi.c b/lib/multi.c index 0926b0d85e9..48a92928c8d 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -94,6 +94,7 @@ static CURLMcode add_next_timeout(struct curltime now, static CURLMcode multi_timeout(struct Curl_multi *multi, long *timeout_ms); static void process_pending_handles(struct Curl_multi *multi); +static void multi_xfer_buf_free(struct Curl_multi *multi); #ifdef DEBUGBUILD static const char * const multi_statename[]={ @@ -189,6 +190,10 @@ static void mstate(struct Curl_easy *data, CURLMstate state /* changing to COMPLETED means there's one less easy handle 'alive' */ DEBUGASSERT(data->multi->num_alive > 0); data->multi->num_alive--; + if(!data->multi->num_alive) { + /* free the transfer buffer when we have no more active transfers */ + multi_xfer_buf_free(data->multi); + } } /* if this state has an init-function, run it */ @@ -784,7 +789,6 @@ static CURLcode multi_done(struct Curl_easy *data, data->state.lastconnect_id = -1; } - Curl_safefree(data->state.buffer); return result; } @@ -1891,12 +1895,9 @@ static CURLcode readrewind(struct Curl_easy *data) */ CURLcode Curl_preconnect(struct Curl_easy *data) { - if(!data->state.buffer) { - data->state.buffer = malloc(data->set.buffer_size + 1); - if(!data->state.buffer) - return CURLE_OUT_OF_MEMORY; - } - + /* this used to do data->state.buffer allocation, + maybe remove completely now? */ + (void)data; return CURLE_OK; } @@ -2450,7 +2451,6 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, { char *newurl = NULL; bool retry = FALSE; - DEBUGASSERT(data->state.buffer); /* check if over send speed */ send_timeout_ms = 0; if(data->set.max_send_speed) @@ -2883,6 +2883,7 @@ CURLMcode curl_multi_cleanup(struct Curl_multi *multi) Curl_free_multi_ssl_backend_data(multi->ssl_backend_data); #endif + multi_xfer_buf_free(multi); free(multi); return CURLM_OK; @@ -3819,3 +3820,64 @@ struct Curl_easy **curl_multi_get_handles(struct Curl_multi *multi) } return a; } + +CURLcode Curl_multi_xfer_buf_borrow(struct Curl_easy *data, + char **pbuf, size_t *pbuflen) +{ + DEBUGASSERT(data); + DEBUGASSERT(data->multi); + *pbuf = NULL; + *pbuflen = 0; + if(!data->multi) { + failf(data, "transfer has no multi handle"); + return CURLE_FAILED_INIT; + } + if(!data->set.buffer_size) { + failf(data, "transfer buffer size is 0"); + return CURLE_FAILED_INIT; + } + if(data->multi->xfer_buf_borrowed) { + failf(data, "attempt to borrow xfer_buf when already borrowed"); + return CURLE_AGAIN; + } + + if(data->multi->xfer_buf && + data->set.buffer_size > data->multi->xfer_buf_len) { + /* not large enough, get a new one */ + free(data->multi->xfer_buf); + data->multi->xfer_buf = NULL; + data->multi->xfer_buf_len = 0; + } + + if(!data->multi->xfer_buf) { + data->multi->xfer_buf = malloc((size_t)data->set.buffer_size); + if(!data->multi->xfer_buf) { + failf(data, "could not allocate xfer_buf of %zu bytes", + (size_t)data->set.buffer_size); + return CURLE_OUT_OF_MEMORY; + } + data->multi->xfer_buf_len = data->set.buffer_size; + } + + data->multi->xfer_buf_borrowed = TRUE; + *pbuf = data->multi->xfer_buf; + *pbuflen = data->multi->xfer_buf_len; + return CURLE_OK; +} + +void Curl_multi_xfer_buf_release(struct Curl_easy *data, char *buf) +{ + (void)buf; + DEBUGASSERT(data); + DEBUGASSERT(data->multi); + DEBUGASSERT(!buf || data->multi->xfer_buf == buf); + data->multi->xfer_buf_borrowed = FALSE; +} + +static void multi_xfer_buf_free(struct Curl_multi *multi) +{ + DEBUGASSERT(multi); + Curl_safefree(multi->xfer_buf); + multi->xfer_buf_len = 0; + multi->xfer_buf_borrowed = FALSE; +} diff --git a/lib/multihandle.h b/lib/multihandle.h index e03e382e28c..3cccd343fec 100644 --- a/lib/multihandle.h +++ b/lib/multihandle.h @@ -124,6 +124,10 @@ struct Curl_multi { times of all currently set timers */ struct Curl_tree *timetree; + /* buffer used for transfer data, lazy initialized */ + char *xfer_buf; /* the actual buffer */ + size_t xfer_buf_len; /* the allocated length */ + #if defined(USE_SSL) struct multi_ssl_backend_data *ssl_backend_data; #endif @@ -171,6 +175,7 @@ struct Curl_multi { #endif BIT(dead); /* a callback returned error, everything needs to crash and burn */ + BIT(xfer_buf_borrowed); /* xfer_buf is currently being borrowed */ #ifdef DEBUGBUILD BIT(warned); /* true after user warned of DEBUGBUILD */ #endif diff --git a/lib/multiif.h b/lib/multiif.h index 7a344fa9fd2..de2ffeb9f43 100644 --- a/lib/multiif.h +++ b/lib/multiif.h @@ -94,4 +94,28 @@ CURLMcode Curl_multi_add_perform(struct Curl_multi *multi, /* Return the value of the CURLMOPT_MAX_CONCURRENT_STREAMS option */ unsigned int Curl_multi_max_concurrent_streams(struct Curl_multi *multi); +/** + * Borrow the transfer buffer from the multi, suitable + * for the given transfer `data`. The buffer may only be used in one + * multi processing of the easy handle. It MUST be returned to the + * multi before it can be borrowed again. + * Pointers into the buffer remain only valid as long as it is borrowed. + * + * @param data the easy handle + * @param pbuf on return, the buffer to use or NULL on error + * @param pbuflen on return, the size of *pbuf or 0 on error + * @return CURLE_OK when buffer is available and is returned. + * CURLE_OUT_OF_MEMORy on failure to allocate the buffer, + * CURLE_FAILED_INIT if the easy handle is without multi. + * CURLE_AGAIN if the buffer is borrowed already. + */ +CURLcode Curl_multi_xfer_buf_borrow(struct Curl_easy *data, + char **pbuf, size_t *pbuflen); +/** + * Release the borrowed buffer. All references into the buffer become + * invalid after this. + * @param buf the buffer pointer borrowed for coding error checks. + */ +void Curl_multi_xfer_buf_release(struct Curl_easy *data, char *buf); + #endif /* HEADER_CURL_MULTIIF_H */ diff --git a/lib/setopt.c b/lib/setopt.c index a5270773f39..e5614cd3514 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -2210,9 +2210,6 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) * The application kindly asks for a differently sized receive buffer. * If it seems reasonable, we'll use it. */ - if(data->state.buffer) - return CURLE_BAD_FUNCTION_ARGUMENT; - arg = va_arg(param, long); if(arg > READBUFFER_MAX) diff --git a/lib/transfer.c b/lib/transfer.c index 3ae4b61c0ee..7d9fa6bd4f7 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -466,15 +466,18 @@ static CURLcode readwrite_data(struct Curl_easy *data, { struct connectdata *conn = data->conn; CURLcode result = CURLE_OK; - char *buf; - size_t blen; + char *buf, *xfer_buf; + size_t blen, xfer_blen; int maxloops = 10; curl_off_t total_received = 0; bool is_multiplex = FALSE; - DEBUGASSERT(data->state.buffer); *done = FALSE; + result = Curl_multi_xfer_buf_borrow(data, &xfer_buf, &xfer_blen); + if(result) + goto out; + /* This is where we loop until we have read everything there is to read or we get a CURLE_AGAIN */ do { @@ -489,8 +492,8 @@ static CURLcode readwrite_data(struct Curl_easy *data, is_multiplex = Curl_conn_is_multiplex(conn, FIRSTSOCKET); } - buf = data->state.buffer; - bytestoread = data->set.buffer_size; + buf = xfer_buf; + bytestoread = xfer_blen; /* Observe any imposed speed limit */ if(bytestoread && data->set.max_recv_speed) { @@ -564,6 +567,7 @@ static CURLcode readwrite_data(struct Curl_easy *data, } out: + Curl_multi_xfer_buf_release(data, xfer_buf); if(result) DEBUGF(infof(data, "readwrite_data() -> %d", result)); return result; diff --git a/lib/url.c b/lib/url.c index 36395a155fd..0f850992723 100644 --- a/lib/url.c +++ b/lib/url.c @@ -280,7 +280,6 @@ CURLcode Curl_close(struct Curl_easy **datap) data->state.referer = NULL; up_free(data); - Curl_safefree(data->state.buffer); Curl_dyn_free(&data->state.headerb); Curl_safefree(data->state.ulbuf); Curl_flush_cookies(data, TRUE); diff --git a/lib/urldata.h b/lib/urldata.h index 49aed15fda7..fabc30ea4b1 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1337,7 +1337,6 @@ struct UrlState { struct dynbuf headerb; /* buffer to store headers in */ struct curl_slist *hstslist; /* list of HSTS files set by curl_easy_setopt(HSTS) calls */ - char *buffer; /* download buffer */ char *ulbuf; /* allocated upload buffer or NULL */ curl_off_t current_speed; /* the ProgressShow() function sets this, bytes / second */ From d0a851feadb28bb808ae9fe4e2c53a1636ec4c00 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 9 Feb 2024 14:15:25 +0100 Subject: [PATCH 311/509] dist: make sure the http tests are in the tarball Fixes #12914 Reported-by: Fabian Vogt Closes #12917 --- tests/http/Makefile.am | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/tests/http/Makefile.am b/tests/http/Makefile.am index cce66daf895..d3a219d7a2d 100644 --- a/tests/http/Makefile.am +++ b/tests/http/Makefile.am @@ -24,6 +24,42 @@ SUBDIRS = clients +TESTENV = \ +testenv/__init__.py \ +testenv/caddy.py \ +testenv/certs.py \ +testenv/client.py \ +testenv/curl.py \ +testenv/env.py \ +testenv/httpd.py \ +testenv/mod_curltest/mod_curltest.c \ +testenv/nghttpx.py \ +testenv/ports.py \ +testenv/ws_echo_server.py + +EXTRA_DIST = \ +config.ini.in \ +conftest.py \ +requirements.txt \ +scorecard.py \ +test_01_basic.py \ +test_02_download.py \ +test_03_goaway.py \ +test_04_stuttered.py \ +test_05_errors.py \ +test_06_eyeballs.py \ +test_07_upload.py \ +test_08_caddy.py \ +test_09_push.py \ +test_10_proxy.py \ +test_11_unix.py \ +test_12_reuse.py \ +test_13_proxy_auth.py \ +test_14_auth.py \ +test_15_tracing.py \ +test_20_websockets.py \ +$(TESTENV) + clean-local: rm -rf *.pyc __pycache__ rm -rf gen From d8f01e098503b0e26ffba391fe9bf189b4b5d715 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 9 Feb 2024 13:10:08 +0100 Subject: [PATCH 312/509] ftp: fix socket wait activity in ftp_domore_getsock - when waiting on the data connection, always add the control socket to the pollset on state STOP or let the pingpong add the socket according to its needs. Reported-by: Fabian Vogt Fixes #12901 Closes #12913 --- lib/ftp.c | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/lib/ftp.c b/lib/ftp.c index e0590a61eb8..53445b3d5a5 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -937,24 +937,18 @@ static int ftp_domore_getsock(struct Curl_easy *data, * remote site, or we could wait for that site to connect to us. Or just * handle ordinary commands. */ - DEBUGF(infof(data, "ftp_domore_getsock()")); - if(conn->cfilter[SECONDARYSOCKET] - && !Curl_conn_is_connected(conn, SECONDARYSOCKET)) - return 0; if(FTP_STOP == ftpc->state) { - int bits = GETSOCK_READSOCK(0); - /* if stopped and still in this state, then we're also waiting for a connect on the secondary connection */ + DEBUGASSERT(conn->sock[SECONDARYSOCKET] != CURL_SOCKET_BAD || + (conn->cfilter[SECONDARYSOCKET] && + !Curl_conn_is_connected(conn, SECONDARYSOCKET))); socks[0] = conn->sock[FIRSTSOCKET]; - if(conn->sock[SECONDARYSOCKET] != CURL_SOCKET_BAD) { - socks[1] = conn->sock[SECONDARYSOCKET]; - bits |= GETSOCK_WRITESOCK(1) | GETSOCK_READSOCK(1); - } - - return bits; + /* An unconnected SECONDARY will add its socket by itself + * via its adjust_pollset() */ + return GETSOCK_READSOCK(0); } return Curl_pp_getsock(data, &conn->proto.ftpc.pp, socks); } From 07e5b3ea6012ec26ec6c9f4c01040e3b60640c8a Mon Sep 17 00:00:00 2001 From: MAntoniak <47522782+MAntoniak@users.noreply.github.com> Date: Thu, 8 Feb 2024 19:54:45 +0100 Subject: [PATCH 313/509] mbedtls: fix building when MBEDTLS_X509_REMOVE_INFO flag is defined Closes #12904 --- lib/vtls/mbedtls.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/vtls/mbedtls.c b/lib/vtls/mbedtls.c index 7d70de53bd2..d6c9bce25c9 100644 --- a/lib/vtls/mbedtls.c +++ b/lib/vtls/mbedtls.c @@ -775,6 +775,7 @@ mbed_connect_step2(struct Curl_cfilter *cf, struct Curl_easy *data) peercert = mbedtls_ssl_get_peer_cert(&backend->ssl); if(peercert && data->set.verbose) { +#ifndef MBEDTLS_X509_REMOVE_INFO const size_t bufsize = 16384; char *buffer = malloc(bufsize); @@ -787,6 +788,9 @@ mbed_connect_step2(struct Curl_cfilter *cf, struct Curl_easy *data) infof(data, "Unable to dump certificate information"); free(buffer); +#else + infof(data, "Unable to dump certificate information"); +#endif } if(pinnedpubkey) { From 05104f826e801b2af86f0230c3023e18b8c50a9a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 8 Feb 2024 15:11:55 +0100 Subject: [PATCH 314/509] configure: add warning for using TLS libraries without 1.3 support Closes #12900 --- configure.ac | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/configure.ac b/configure.ac index db291afb006..cd0e2d07d8d 100644 --- a/configure.ac +++ b/configure.ac @@ -4999,6 +4999,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! From f8513ee62ec72af996139d2756beeac8a828afd8 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Thu, 8 Feb 2024 22:45:55 +0100 Subject: [PATCH 315/509] cmake: add warning for using TLS libraries without 1.3 support Closes #12900 --- CMakeLists.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index 1b5ea67c2af..2194a6598a2 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -720,6 +720,12 @@ if(USE_MSH3) list(APPEND CURL_LIBS ${MSH3_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)) message(FATAL_ERROR "MultiSSL cannot be enabled with HTTP/3 and vice versa.") endif() From d7332e3e46c3ef401b34e6a1a129eb4dd846c452 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 4 Jan 2024 10:32:04 -0800 Subject: [PATCH 316/509] Revert "CI: run Circle macOS builds on x86 for now" This reverts commit 2683de3078eadc86d9b182e7417f4ee75a247e2c. ARM resources are now available in Circle CI, so run these builds on ARM again. This platform needs explicit paths set to libpsl and its dependency icu4c. Follow-up to 2683de30 Closes #12635 --- .circleci/config.yml | 137 +++++++++++++++++++++---------------------- 1 file changed, 68 insertions(+), 69 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index e7ddc27d196..e343ae17e1d 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,42 +57,42 @@ 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: @@ -103,35 +106,35 @@ commands: - 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: @@ -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 libpsl | 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,7 +240,8 @@ 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: @@ -324,15 +328,10 @@ jobs: - 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 @@ -340,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 @@ -351,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 @@ -362,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 @@ -373,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 @@ -384,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 @@ -395,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 @@ -406,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 @@ -417,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 @@ -428,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 @@ -439,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 @@ -450,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 @@ -494,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: + # macos-arm-http-libressl-http2: # jobs: - # - macos-x86-http-libressl-http2 + # - 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 From 089b4e36e4d2602167cb08ba87d92e1fac35ed24 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 9 Feb 2024 16:30:28 +0100 Subject: [PATCH 317/509] TODO: avoid nroff Instead of adjusting roffit, skip the nroff step. Closes #12919 --- docs/TODO | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/TODO b/docs/TODO index dafd87a2f60..ee537b913f3 100644 --- a/docs/TODO +++ b/docs/TODO @@ -177,7 +177,7 @@ 18.29 --retry and transfer timeouts 19. Build - 19.1 roffit + 19.1 avoid nroff 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 @@ -1289,13 +1289,15 @@ https://qa.mandriva.com/show_bug.cgi?id=22565 - 19. Build -19.1 roffit +19.1 avoid nroff - Consider extending 'roffit' to produce decent ASCII output, and use that - instead of (g)nroff when building src/tool_hugehelp.c + With the switch to the markdown-like documentation format since curl 8.6.0, + it should (with a manageable amount of work) be possible to render an ASCII + version of the man page without involving nroff and thus remove that + dependency for building the hugehelp file, used to build in the man page into + the curl command line tool. 19.2 Enable PIE and RELRO by default From 9b43dcdfd5a01cc2fc579aca560418cf7ac9570b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 9 Feb 2024 16:37:43 +0100 Subject: [PATCH 318/509] TODO: use pkg-config to find libpsl Closes #12919 --- docs/TODO | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/TODO b/docs/TODO index ee537b913f3..d2fd42ed969 100644 --- a/docs/TODO +++ b/docs/TODO @@ -183,6 +183,7 @@ 19.4 Package curl for Windows in a signed installer 19.5 make configure use --cache-file more and better 19.6 build curl with Windows Unicode support + 19.7 use pkg-config to find libpsl 20. Test suite 20.1 SSL tunnel @@ -1339,6 +1340,12 @@ See https://github.com/curl/curl/issues/7229 +19.7 use pkg-config to find libpsl + + When enabled in configure, libpsl is not found and picked up using details + with pkg-config, thus sometimes missing out on platform specific adjustments. + This should be fixed. + 20. Test suite 20.1 SSL tunnel From d900bd2066c6dfcdda824c00b5646c7e61405c77 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 9 Feb 2024 23:47:10 +0100 Subject: [PATCH 319/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 70 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 64 insertions(+), 6 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 7ba803f4996..5e58493b75d 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.6.1 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3078 + Contributors: 3090 This release includes the following changes: @@ -14,24 +14,52 @@ This release includes the following bugfixes: o ALTSVC.md: correct a typo [14] o asyn-thread: use wakeup_close to close the read descriptor [1] + o badwords: use hostname, not host name [46] + o cmake: add warning for using TLS libraries without 1.3 support [25] + o cmake: fix function description in comment [47] o cmdline-docs/Makefile: avoid using a fixed temp file name [5] + o cmdline-docs: quote and angle bracket cleanup [45] + o configure: add warning for using TLS libraries without 1.3 support [26] o configure: do not link with nghttp3 unless necessary [7] o connect.c: fix typo [17] o cookie.md: provide an example sending a fixed cookie [13] + o curl: exit on config file parser errors [40] + o curl: when allocating variables, add the name into the struct [37] + o CURLOPT_WRITEFUNCTION.md: typo fix [41] + o dist: make sure the http tests are in the tarball [29] o docs: add missing slashes to SChannel client certificate documentation [11] + o docs: add mk-ca-bundle.1 to dist [49] + o docs: add necessary setup for nghttp3 [51] + o docs: make curldown do angle brackets like markdown [54] + o docs: make sure curl.1 is included in dist tarballs [35] o docs: remove `mk-ca-bundle.1` from `man_MANS` [21] 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 header.md: remove backslash, make nicer markdown [48] o HTTP/2: write response directly [12] + o HTTP3.md: adjust the OpenSSL QUIC install instructions [34] + o https-proxy: use IP address and cert with ip in alt names [50] + o lib582: remove code causing warning that is never run [38] + o lib: convert Curl_get_line to use dynbuf [42] o libcurl-security.md: Active FTP passes on the local IP address [6] + o mbedtls: fix building when MBEDTLS_X509_REMOVE_INFO flag is defined [27] o md4: include strdup.h for the memdup proto [10] + o multi: add xfer_buf to multi handle [30] o ntml_wb: fix buffer type typo [2] o openssl-quic: check on Windows that socket conv to int is possible [8] o OS400: avoid using awk in the build scripts [20] o proxy1.0.md: fix example [15] o sendf: ignore response body to HEAD [18] + o tests: support setting/using blank content env variables o tool_cb_hdr: only parse etag + content-disposition for 2xx [9] + 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 version: allow building with ancient libpsl [52] + o vtls: revert "receive max buffer" + add test case [39] + o write-out.md: clarify error handling details [31] This release includes the following known bugs: @@ -46,11 +74,14 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - Boris Verkhovskiy, Chris Webb, Dan Fandrich, Daniel Stenberg, - Dmitry Tretyakov, Erik Schnetter, Faraz Fallahi, Harry Sintonen, Jan Macku, - Joel Depooter, Jon Rumsey, Lars Kellogg-Stedman, Lukáš Zaoral, - Patrick Monnerat, Ryan Carsten Schmidt, Sergey Bronnikov, Stefan Eissing - (17 contributors) + Boris Verkhovskiy, Brett Buddin, Chris Webb, Dan Fandrich, Daniel Stenberg, + Daniel Szmulewicz, Dirk Hünniger, Dmitry Tretyakov, Erik Schnetter, + Fabian Vogt, Faraz Fallahi, Harry Sintonen, Jan Macku, Jiawen Geng, + Joel Depooter, Jon Rumsey, Karthikdasari0423, Lars Kellogg-Stedman, + Lukáš Zaoral, Michał Antoniak, Patrick Monnerat, Peter Krefting, Ray Satiro, + Ryan Carsten Schmidt, Scott Mutter, Sergey Bronnikov, Stefan Eissing, + Viktor Szakats + (28 contributors) References to bug reports and discussions on issues: @@ -75,3 +106,30 @@ References to bug reports and discussions on issues: [19] = https://curl.se/bug/?i=12823 [20] = https://curl.se/bug/?i=12826 [21] = https://curl.se/bug/?i=12843 + [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 + [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 + [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=12875 + [50] = https://curl.se/bug/?i=12838 + [51] = https://curl.se/bug/?i=12859 + [52] = https://curl.se/mail/archive-2024-02/0004.html + [54] = https://curl.se/bug/?i=12869 From 922091c05cc2216a49dab955d990bf34edbc5ac5 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 9 Feb 2024 14:38:58 -0800 Subject: [PATCH 320/509] scripts: Fix cijobs.pl for Azure and GHA The spacing in the yaml files changed. --- scripts/cijobs.pl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/scripts/cijobs.pl b/scripts/cijobs.pl index 4c047973a93..150e2cb8f33 100755 --- a/scripts/cijobs.pl +++ b/scripts/cijobs.pl @@ -89,7 +89,7 @@ sub githubactions { $job{'install'} = $1; } elsif($m >= 0) { - if($_ =~ /^ - name: (.*)/) { + if($_ =~ /^ - name: (.*)/) { # matrix job #print "name: $1\n"; $job{'name'} = $1; @@ -165,7 +165,7 @@ sub azurepipelines { $job{'file'} = ".azure-pipelines.yml"; $job{'service'} = "azure"; while() { - if($_ =~ /^ vmImage: (.*)/) { + if($_ =~ /^ vmImage: (.*)/) { my $i = $1; if($i =~ /ubuntu/) { $os = "linux"; @@ -174,7 +174,7 @@ sub azurepipelines { $os = "windows"; } } - elsif($_ =~ /^- stage: (.*)/) { + elsif($_ =~ /^ - stage: (.*)/) { my $topname = $1; if($topname !~ /(windows|linux)/) { $job{'name'} = $topname; @@ -194,7 +194,7 @@ sub azurepipelines { $j = 0; } elsif($m >= 0) { - if($_ =~ /^ name: (.*)/) { + if($_ =~ /^ name: (.*)/) { # single matrix list entry job $j++; $job{'name'} = $1; @@ -205,7 +205,7 @@ sub azurepipelines { # disable matrix mode $m = -1; } - elsif($_ =~ /^ configure: (.*)/) { + elsif($_ =~ /^ configure: (.*)/) { $job{'configure'} = $1; $job{'line'}=$line; $job{'os'}=$os; From b08200d31c0b2d23cff27a5ddf4baeb966c85d59 Mon Sep 17 00:00:00 2001 From: Evgeny Grin Date: Thu, 8 Feb 2024 18:41:55 +0100 Subject: [PATCH 321/509] test1165: improve pattern matching * Fix excluded digits at the end of the symbols ('CURL_DISABLE_POP3' was checked as 'CURL_DISABLE_POP') Closes #12903 --- tests/test1165.pl | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/test1165.pl b/tests/test1165.pl index b6f3179cf75..bccbef9366c 100755 --- a/tests/test1165.pl +++ b/tests/test1165.pl @@ -44,7 +44,7 @@ sub scanconf { my ($f)=@_; open S, "<$f"; while() { - if(/(CURL_DISABLE_[A-Z_]+)/g) { + if(/(CURL_DISABLE_[A-Z0-9_]+)/g) { my ($sym)=($1); $disable{$sym} = 1; } @@ -67,9 +67,9 @@ sub scanconf_cmake { my ($f)=@_; open S, "<$f"; while() { - if(/(CURL_DISABLE_[A-Z_]+)/g) { + if(/(CURL_DISABLE_[A-Z0-9_]+)/g) { my ($sym)=($1); - if(not $sym =~ /(CURL_DISABLE_INSTALL|CURL_DISABLE_TESTS|CURL_DISABLE_SRP)/) { + if(not $sym =~ /^(CURL_DISABLE_INSTALL|CURL_DISABLE_TESTS|CURL_DISABLE_SRP)$/) { $disable_cmake{$sym} = 1; } } @@ -85,7 +85,7 @@ sub scan_file { my ($source)=@_; open F, "<$source"; while() { - while(s/(CURL_DISABLE_[A-Z_]+)//) { + while(s/(CURL_DISABLE_[A-Z0-9_]+)//) { my ($sym)=($1); $file{$sym} = $source; } @@ -115,7 +115,7 @@ sub scan_docs { my $line = 0; while() { $line++; - if(/^## `(CURL_DISABLE_[A-Z_]+)/g) { + if(/^## `(CURL_DISABLE_[A-Z0-9_]+)`/g) { my ($sym)=($1); $docs{$sym} = $line; } From 8436406a58b99570009ef0d56bd8770c94f69cfb Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 9 Feb 2024 17:23:55 -0800 Subject: [PATCH 322/509] CI: bump to actions/cache@v4 to avoid warning --- .github/workflows/osslq-linux.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/osslq-linux.yml b/.github/workflows/osslq-linux.yml index 997e35bab07..a15e28ccecf 100644 --- a/.github/workflows/osslq-linux.yml +++ b/.github/workflows/osslq-linux.yml @@ -83,7 +83,7 @@ jobs: - name: cache openssl3 if: contains(matrix.build.install_steps, 'openssl3') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-openssl3 env: cache-name: cache-openssl3 @@ -101,7 +101,7 @@ jobs: - name: cache quictls if: contains(matrix.build.install_steps, 'quictls') - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-quictls env: cache-name: cache-quictls @@ -110,7 +110,7 @@ jobs: key: ${{ runner.os }}-build-${{ env.cache-name }}-quictls-${{ env.quictls-version }} - name: cache quictls - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-quictls-no-deprecated env: cache-name: cache-quictls-no-deprecated @@ -134,7 +134,7 @@ jobs: - name: cache nghttp3 - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-nghttp3 env: cache-name: cache-nghttp3 @@ -176,7 +176,7 @@ jobs: name: 'install nghttp2' - name: cache mod_h2 - uses: actions/cache@v3 + uses: actions/cache@v4 id: cache-mod_h2 env: cache-name: cache-mod_h2 From f8bd04ec50ba0a4e100267dec6a0a07cf238859a Mon Sep 17 00:00:00 2001 From: MAntoniak <47522782+MAntoniak@users.noreply.github.com> Date: Thu, 8 Feb 2024 20:16:23 +0100 Subject: [PATCH 323/509] mbedtls: use mbedtls_ssl_conf_{min|max}_tls_version ... instead of the deprecated mbedtls_ssl_conf_{min|max}_version Closes #12905 --- lib/vtls/mbedtls.c | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/lib/vtls/mbedtls.c b/lib/vtls/mbedtls.c index d6c9bce25c9..0ef6df0ff0b 100644 --- a/lib/vtls/mbedtls.c +++ b/lib/vtls/mbedtls.c @@ -237,6 +237,23 @@ static const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_fr = #define PUB_DER_MAX_BYTES (RSA_PUB_DER_MAX_BYTES > ECP_PUB_DER_MAX_BYTES ? \ RSA_PUB_DER_MAX_BYTES : ECP_PUB_DER_MAX_BYTES) +#if MBEDTLS_VERSION_NUMBER >= 0x03020000 +static CURLcode mbedtls_version_from_curl( + mbedtls_ssl_protocol_version* mbedver, long version) +{ + switch(version) { + case CURL_SSLVERSION_TLSv1_0: + case CURL_SSLVERSION_TLSv1_1: + case CURL_SSLVERSION_TLSv1_2: + *mbedver = MBEDTLS_SSL_VERSION_TLS1_2; + return CURLE_OK; + case CURL_SSLVERSION_TLSv1_3: + break; + } + + return CURLE_SSL_CONNECT_ERROR; +} +#else static CURLcode mbedtls_version_from_curl(int *mbedver, long version) { #if MBEDTLS_VERSION_NUMBER >= 0x03000000 @@ -267,6 +284,7 @@ static CURLcode mbedtls_version_from_curl(int *mbedver, long version) return CURLE_SSL_CONNECT_ERROR; } +#endif static CURLcode set_ssl_version_min_max(struct Curl_cfilter *cf, struct Curl_easy *data) @@ -275,7 +293,10 @@ set_ssl_version_min_max(struct Curl_cfilter *cf, struct Curl_easy *data) struct mbed_ssl_backend_data *backend = (struct mbed_ssl_backend_data *)connssl->backend; struct ssl_primary_config *conn_config = Curl_ssl_cf_get_primary_config(cf); -#if MBEDTLS_VERSION_NUMBER >= 0x03000000 +#if MBEDTLS_VERSION_NUMBER >= 0x03020000 + mbedtls_ssl_protocol_version mbedtls_ver_min = MBEDTLS_SSL_VERSION_TLS1_2; + mbedtls_ssl_protocol_version mbedtls_ver_max = MBEDTLS_SSL_VERSION_TLS1_2; +#elif MBEDTLS_VERSION_NUMBER >= 0x03000000 int mbedtls_ver_min = MBEDTLS_SSL_MINOR_VERSION_3; int mbedtls_ver_max = MBEDTLS_SSL_MINOR_VERSION_3; #else @@ -313,10 +334,15 @@ set_ssl_version_min_max(struct Curl_cfilter *cf, struct Curl_easy *data) return result; } +#if MBEDTLS_VERSION_NUMBER >= 0x03020000 + mbedtls_ssl_conf_min_tls_version(&backend->config, mbedtls_ver_min); + mbedtls_ssl_conf_max_tls_version(&backend->config, mbedtls_ver_max); +#else mbedtls_ssl_conf_min_version(&backend->config, MBEDTLS_SSL_MAJOR_VERSION_3, mbedtls_ver_min); mbedtls_ssl_conf_max_version(&backend->config, MBEDTLS_SSL_MAJOR_VERSION_3, mbedtls_ver_max); +#endif return result; } From ed596eb40909d8df89f5849551cc4fcd468e08ca Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 10 Feb 2024 18:31:31 +0100 Subject: [PATCH 324/509] KNOWN_BUGS: FTP upload fails if remebered dir is deleted Closes #12181 Closes #12923 --- docs/KNOWN_BUGS | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 70b21d31be2..e5ff518e290 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -60,6 +60,7 @@ 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 remebered dir is deleted 7.3 FTP with NOBODY and FAILONERROR 7.4 FTP with ACCT 7.11 FTPS upload data loss with TLS 1.3 @@ -373,6 +374,14 @@ problems may have been fixed or changed somewhat since this was written. 7. FTP +7.1 FTP upload fails if remebered 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.3 FTP with NOBODY and FAILONERROR It seems sensible to be able to use CURLOPT_NOBODY and CURLOPT_FAILONERROR From 24d6c2889f15f5141ff8d37b59f9099e8aae0f38 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Fri, 9 Feb 2024 03:41:30 -0500 Subject: [PATCH 325/509] schannel: fix hang on unexpected server close - Treat TLS connection close (either due to a close_notify from the server or just closed due to receiving 0) as pending data. This is because in some cases schannel_recv knows the connection is closed but has to return actual pending data so it can't return 0 or an error to indicate no more data. In this case schannel_recv must be called again, which only happens if readwrite_data sees that there is still pending data. Prior to this change if the total size of the body that libcurl expected to receive from the server was unknown then it was possible under some network conditions that libcurl would hang waiting to receive more data, when in fact a close_notify alert indicating no more data would be sent was already processed. Fixes https://github.com/curl/curl/issues/12894 Closes https://github.com/curl/curl/pull/12910 --- lib/vtls/schannel.c | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/lib/vtls/schannel.c b/lib/vtls/schannel.c index 45c3373713c..d9d0b9f72d0 100644 --- a/lib/vtls/schannel.c +++ b/lib/vtls/schannel.c @@ -2133,7 +2133,6 @@ schannel_recv(struct Curl_cfilter *cf, struct Curl_easy *data, infof(data, "schannel: server indicated shutdown in a prior call"); goto cleanup; } - /* It's debatable what to return when !len. Regardless we can't return immediately because there may be data to decrypt (in the case we want to decrypt all encrypted cached data) so handle !len later in cleanup. @@ -2317,10 +2316,10 @@ schannel_recv(struct Curl_cfilter *cf, struct Curl_easy *data, /* In Windows 2000 SEC_I_CONTEXT_EXPIRED (close_notify) is not returned so we have to work around that in cleanup. */ backend->recv_sspi_close_notify = true; - if(!backend->recv_connection_closed) { + if(!backend->recv_connection_closed) backend->recv_connection_closed = true; - infof(data, "schannel: server closed the connection"); - } + infof(data, + "schannel: server close notification received (close_notify)"); goto cleanup; } } @@ -2443,7 +2442,10 @@ static bool schannel_data_pending(struct Curl_cfilter *cf, if(backend->ctxt) /* SSL/TLS is in use */ return (backend->decdata_offset > 0 || - (backend->encdata_offset > 0 && !backend->encdata_is_incomplete)); + (backend->encdata_offset > 0 && !backend->encdata_is_incomplete) || + backend->recv_connection_closed || + backend->recv_sspi_close_notify || + backend->recv_unrecoverable_err); else return FALSE; } From 5691a6cf363242da38bd7e469b13a2e741a295c6 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Fri, 9 Feb 2024 04:08:35 -0500 Subject: [PATCH 326/509] transfer: improve Windows SO_SNDBUF update limit - Change the 1 second SO_SNDBUF update limit from per transfer to per connection. Prior to this change many transfers over the same connection could cause many SO_SNDBUF updates made to that connection per second, which was unnecessary. Closes https://github.com/curl/curl/pull/12911 --- lib/transfer.c | 4 ++-- lib/urldata.h | 9 +++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/lib/transfer.c b/lib/transfer.c index 7d9fa6bd4f7..63a16ae86dd 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -781,9 +781,9 @@ static CURLcode readwrite_upload(struct Curl_easy *data, #if defined(_WIN32) && defined(USE_WINSOCK) { struct curltime n = Curl_now(); - if(Curl_timediff(n, k->last_sndbuf_update) > 1000) { + if(Curl_timediff(n, conn->last_sndbuf_update) > 1000) { win_update_buffer_size(conn->writesockfd); - k->last_sndbuf_update = n; + conn->last_sndbuf_update = n; } } #endif diff --git a/lib/urldata.h b/lib/urldata.h index fabc30ea4b1..21bc61348c9 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -721,10 +721,6 @@ struct SingleRequest { } p; #ifndef CURL_DISABLE_DOH struct dohdata *doh; /* DoH specific data for this request */ -#endif -#if defined(_WIN32) && defined(USE_WINSOCK) - struct curltime last_sndbuf_update; /* last time readwrite_upload called - win_update_buffer_size */ #endif char fread_eof[2]; /* the body read callback (index 0) returned EOF or the trailer read callback (index 1) returned EOF */ @@ -998,6 +994,11 @@ struct connectdata { CtxtHandle *sslContext; #endif +#if defined(_WIN32) && defined(USE_WINSOCK) + struct curltime last_sndbuf_update; /* last time readwrite_upload called + win_update_buffer_size */ +#endif + #ifdef USE_GSASL struct gsasldata gsasl; #endif From 30f1cb255b21417aa52db9654b0aab57619e13da Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 15 Feb 2024 16:04:40 -0800 Subject: [PATCH 327/509] CI: Bump the Circle CI base Ubuntu image to the latest 20.04 The previous ones are going to be removed soon, plus the new ones include all the fixes since then. --- .circleci/config.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index e343ae17e1d..9fc6127a1d9 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -246,7 +246,7 @@ commands: executors: ubuntu: machine: - image: ubuntu-2004:202010-01 + image: ubuntu-2004:2024.01.1 jobs: basic: @@ -307,7 +307,7 @@ jobs: arm: machine: - image: ubuntu-2004:202101-01 + image: ubuntu-2004:2024.01.1 resource_class: arm.medium steps: - checkout @@ -318,7 +318,7 @@ jobs: arm-cares: machine: - image: ubuntu-2004:202101-01 + image: ubuntu-2004:2024.01.1 resource_class: arm.medium steps: - checkout From e87751d69ac0a0f045f75327e1e4318867e69a05 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 13 Feb 2024 11:05:21 +0100 Subject: [PATCH 328/509] vtls: fix tls proxy peer verification - When verifying a proxy certificate for an ip address, use the correct ip family. Prior to this change the "connection" ip family was used, which was not necessarily the same. Reported-by: HsiehYuho@users.noreply.github.com Fixes https://github.com/curl/curl/issues/12831 Closes https://github.com/curl/curl/pull/12931 --- lib/urldata.h | 8 +++++++- lib/vtls/bearssl.c | 2 +- lib/vtls/openssl.c | 42 ++++++++++++++++++++++++++---------------- lib/vtls/schannel.c | 2 +- lib/vtls/sectransp.c | 2 +- lib/vtls/vtls.c | 24 +++++++++++++++--------- 6 files changed, 51 insertions(+), 29 deletions(-) diff --git a/lib/urldata.h b/lib/urldata.h index 21bc61348c9..66c8d107679 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -266,11 +266,17 @@ typedef enum { /* SSL backend-specific data; declared differently by each SSL backend */ struct ssl_backend_data; +typedef enum { + CURL_SSL_PEER_DNS, + CURL_SSL_PEER_IPV4, + CURL_SSL_PEER_IPV6 +} ssl_peer_type; + struct ssl_peer { char *hostname; /* hostname for verification */ char *dispname; /* display version of hostname */ char *sni; /* SNI version of hostname or NULL if not usable */ - BIT(is_ip_address); /* if hostname is an IPv4|6 address */ + ssl_peer_type type; /* type of the peer information */ }; struct ssl_primary_config { diff --git a/lib/vtls/bearssl.c b/lib/vtls/bearssl.c index 58394bab9a6..16f9c4e9276 100644 --- a/lib/vtls/bearssl.c +++ b/lib/vtls/bearssl.c @@ -707,7 +707,7 @@ static CURLcode bearssl_connect_step1(struct Curl_cfilter *cf, infof(data, VTLS_INFOF_ALPN_OFFER_1STR, proto.data); } - if(connssl->peer.is_ip_address) { + if(connssl->peer.type != CURL_SSL_PEER_DNS) { if(verifyhost) { failf(data, "BearSSL: " "host verification of IP address is not supported"); diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c index c8ec76a1d13..eda36606c56 100644 --- a/lib/vtls/openssl.c +++ b/lib/vtls/openssl.c @@ -2134,7 +2134,7 @@ CURLcode Curl_ossl_verifyhost(struct Curl_easy *data, struct connectdata *conn, struct ssl_peer *peer, X509 *server_cert) { bool matched = FALSE; - int target = GEN_DNS; /* target type, GEN_DNS or GEN_IPADD */ + int target; /* target type, GEN_DNS or GEN_IPADD */ size_t addrlen = 0; STACK_OF(GENERAL_NAME) *altnames; #ifdef ENABLE_IPV6 @@ -2149,19 +2149,28 @@ CURLcode Curl_ossl_verifyhost(struct Curl_easy *data, struct connectdata *conn, (void)conn; hostlen = strlen(peer->hostname); - if(peer->is_ip_address) { + switch(peer->type) { + case CURL_SSL_PEER_IPV4: + if(!Curl_inet_pton(AF_INET, peer->hostname, &addr)) + return CURLE_PEER_FAILED_VERIFICATION; + target = GEN_IPADD; + addrlen = sizeof(struct in_addr); + break; #ifdef ENABLE_IPV6 - if(conn->bits.ipv6_ip && - Curl_inet_pton(AF_INET6, peer->hostname, &addr)) { - target = GEN_IPADD; - addrlen = sizeof(struct in6_addr); - } - else + case CURL_SSL_PEER_IPV6: + if(!Curl_inet_pton(AF_INET6, peer->hostname, &addr)) + return CURLE_PEER_FAILED_VERIFICATION; + target = GEN_IPADD; + addrlen = sizeof(struct in6_addr); + break; #endif - if(Curl_inet_pton(AF_INET, peer->hostname, &addr)) { - target = GEN_IPADD; - addrlen = sizeof(struct in_addr); - } + case CURL_SSL_PEER_DNS: + target = GEN_DNS; + break; + default: + DEBUGASSERT(0); + failf(data, "unexpected ssl peer type: %d", peer->type); + return CURLE_PEER_FAILED_VERIFICATION; } /* get a "list" of alternative names */ @@ -2242,11 +2251,12 @@ CURLcode Curl_ossl_verifyhost(struct Curl_easy *data, struct connectdata *conn, /* an alternative name matched */ ; else if(dNSName || iPAddress) { - infof(data, " subjectAltName does not match %s %s", - peer->is_ip_address? "ip address" : "host name", peer->dispname); + const char *tname = (peer->type == CURL_SSL_PEER_DNS) ? "host name" : + (peer->type == CURL_SSL_PEER_IPV4) ? + "ipv4 address" : "ipv6 address"; + infof(data, " subjectAltName does not match %s %s", tname, peer->dispname); failf(data, "SSL: no alternative certificate subject name matches " - "target %s '%s'", - peer->is_ip_address? "ip address" : "host name", peer->dispname); + "target %s '%s'", tname, peer->dispname); result = CURLE_PEER_FAILED_VERIFICATION; } else { diff --git a/lib/vtls/schannel.c b/lib/vtls/schannel.c index d9d0b9f72d0..8736b9e28a0 100644 --- a/lib/vtls/schannel.c +++ b/lib/vtls/schannel.c @@ -1159,7 +1159,7 @@ schannel_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) } /* Warn if SNI is disabled due to use of an IP address */ - if(connssl->peer.is_ip_address) { + if(connssl->peer.type != CURL_SSL_PEER_DNS) { infof(data, "schannel: using IP address, SNI is not supported by OS."); } diff --git a/lib/vtls/sectransp.c b/lib/vtls/sectransp.c index 1f37305ce8a..67f534c675a 100644 --- a/lib/vtls/sectransp.c +++ b/lib/vtls/sectransp.c @@ -2008,7 +2008,7 @@ static CURLcode sectransp_connect_step1(struct Curl_cfilter *cf, return CURLE_SSL_CONNECT_ERROR; } - if(connssl->peer.is_ip_address) { + if(connssl->peer.type != CURL_SSL_PEER_DNS) { infof(data, "WARNING: using IP address, SNI is being disabled by " "the OS."); } diff --git a/lib/vtls/vtls.c b/lib/vtls/vtls.c index 51596d80b8f..d13a3cb1b78 100644 --- a/lib/vtls/vtls.c +++ b/lib/vtls/vtls.c @@ -1516,7 +1516,7 @@ void Curl_ssl_peer_cleanup(struct ssl_peer *peer) free(peer->sni); free(peer->hostname); peer->hostname = peer->sni = peer->dispname = NULL; - peer->is_ip_address = FALSE; + peer->type = CURL_SSL_PEER_DNS; } static void cf_close(struct Curl_cfilter *cf, struct Curl_easy *data) @@ -1530,18 +1530,23 @@ static void cf_close(struct Curl_cfilter *cf, struct Curl_easy *data) cf->connected = FALSE; } -static int is_ip_address(const char *hostname) +static ssl_peer_type get_peer_type(const char *hostname) { + if(hostname && hostname[0]) { #ifdef ENABLE_IPV6 - struct in6_addr addr; + struct in6_addr addr; #else - struct in_addr addr; + struct in_addr addr; #endif - return (hostname && hostname[0] && (Curl_inet_pton(AF_INET, hostname, &addr) + if(Curl_inet_pton(AF_INET, hostname, &addr)) + return CURL_SSL_PEER_IPV4; #ifdef ENABLE_IPV6 - || Curl_inet_pton(AF_INET6, hostname, &addr) + else if(Curl_inet_pton(AF_INET6, hostname, &addr)) { + return CURL_SSL_PEER_IPV6; + } #endif - )); + } + return CURL_SSL_PEER_DNS; } CURLcode Curl_ssl_peer_init(struct ssl_peer *peer, struct Curl_cfilter *cf) @@ -1570,6 +1575,7 @@ CURLcode Curl_ssl_peer_init(struct ssl_peer *peer, struct Curl_cfilter *cf) } /* change if ehostname changed */ + DEBUGASSERT(!ehostname || ehostname[0]); if(ehostname && (!peer->hostname || strcmp(ehostname, peer->hostname))) { Curl_ssl_peer_cleanup(peer); @@ -1589,8 +1595,8 @@ CURLcode Curl_ssl_peer_init(struct ssl_peer *peer, struct Curl_cfilter *cf) } peer->sni = NULL; - peer->is_ip_address = is_ip_address(peer->hostname)? TRUE : FALSE; - if(peer->hostname[0] && !peer->is_ip_address) { + peer->type = get_peer_type(peer->hostname); + if(peer->type == CURL_SSL_PEER_DNS && peer->hostname[0]) { /* not an IP address, normalize according to RCC 6066 ch. 3, * max len of SNI is 2^16-1, no trailing dot */ size_t len = strlen(peer->hostname); From b2497a8d15284dfef4fa7f032572e07b0b4b4720 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Sat, 10 Feb 2024 17:34:43 +0100 Subject: [PATCH 329/509] cmake: fix install for older CMake versions - Generate the docs install list by using a foreach loop instead of LIST:TRANSFORM since older CMake can't handle the latter. Reported-by: Dan Fandrich Fixes https://github.com/curl/curl/issues/12920 Closes https://github.com/curl/curl/pull/12922 --- docs/libcurl/CMakeLists.txt | 7 +++++-- docs/libcurl/opts/CMakeLists.txt | 7 +++++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/libcurl/CMakeLists.txt b/docs/libcurl/CMakeLists.txt index 6f0aa649022..0bc35fc9732 100644 --- a/docs/libcurl/CMakeLists.txt +++ b/docs/libcurl/CMakeLists.txt @@ -62,8 +62,11 @@ add_custom_command(OUTPUT libcurl-symbols.md add_manual_pages(man_MANS) add_custom_target(man ALL DEPENDS ${man_MANS}) if(NOT CURL_DISABLE_INSTALL) - install(FILES "$" - DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) + unset(_src) + foreach(_f ${man_MANS}) + list(APPEND _src "${CMAKE_CURRENT_BINARY_DIR}/${_f}") + endforeach() + install(FILES ${_src} DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) endif() add_subdirectory(opts) diff --git a/docs/libcurl/opts/CMakeLists.txt b/docs/libcurl/opts/CMakeLists.txt index 82844a2251a..a20d0b9bf9e 100644 --- a/docs/libcurl/opts/CMakeLists.txt +++ b/docs/libcurl/opts/CMakeLists.txt @@ -29,6 +29,9 @@ add_manual_pages(man_MANS) add_custom_target(opts-man DEPENDS ${man_MANS}) add_dependencies(man opts-man) if(NOT CURL_DISABLE_INSTALL) - install(FILES "$" - DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) + unset(_src) + foreach(_f ${man_MANS}) + list(APPEND _src "${CMAKE_CURRENT_BINARY_DIR}/${_f}") + endforeach() + install(FILES ${_src} DESTINATION ${CMAKE_INSTALL_MANDIR}/man3) endif() From 298c120b97c6565f2c053d11c12ccc2592dc40bd Mon Sep 17 00:00:00 2001 From: Evgeny Grin Date: Sun, 18 Feb 2024 11:36:27 +0500 Subject: [PATCH 330/509] checksrc.pl: fix handling .checksrc with CRLF - When parsing .checksrc chomp the (CR)LF line ending. Prior to this change on Windows checksrc.pl would not process the symbols in .checksrc properly, since many git repos in Windows use auto crlf to check out files with CRLF line endings. Closes https://github.com/curl/curl/pull/12924 --- scripts/checksrc.pl | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/checksrc.pl b/scripts/checksrc.pl index 76f4660816d..be085e06130 100755 --- a/scripts/checksrc.pl +++ b/scripts/checksrc.pl @@ -120,6 +120,7 @@ sub readlocalfile { open(my $rcfile, "<", "$dir/.checksrc") or return; while(<$rcfile>) { + $windows_os ? $_ =~ s/\r?\n$// : chomp; $i++; # Lines starting with '#' are considered comments From ee92f3d227a59221b94c537972ef985d9e225fd9 Mon Sep 17 00:00:00 2001 From: LeeRiva <76054616+LeeRiva@users.noreply.github.com> Date: Sun, 11 Feb 2024 22:52:12 +0100 Subject: [PATCH 331/509] CURLOPT_POSTQUOTE.md: fix typo Closes https://github.com/curl/curl/pull/12926 --- docs/libcurl/opts/CURLOPT_POSTQUOTE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md index 300a1f2c596..585d20619fc 100644 --- a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md +++ b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md @@ -25,7 +25,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTQUOTE, # DESCRIPTION Pass a pointer to a linked list of FTP or SFTP commands to pass to the server -after your FTP transfer request. The commands are only issues if no error +after your FTP transfer request. The commands are only issued if no error occur. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for CURLOPT_QUOTE(3). From 64283119fe66362c1d2650ac3c957b2b4ea7d788 Mon Sep 17 00:00:00 2001 From: Karthikdasari0423 <92445174+Karthikdasari0423@users.noreply.github.com> Date: Mon, 12 Feb 2024 15:22:39 +0530 Subject: [PATCH 332/509] HTTP3.md: always run nghttp3 submodule init - For consistency change all 'build nghttp3' commands to run submodule init after cloning, even if the branch does not have submodules. Follow-up to 5a4b2f93 and 4f794558. Closes https://github.com/curl/curl/pull/12928 --- docs/HTTP3.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 75a92fa316e..f16708983f7 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -102,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 @@ -143,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 From 0e2ffa3632d3fd481c75a36cc176ddb1614f8107 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 13 Feb 2024 11:39:06 +0100 Subject: [PATCH 333/509] file: use xfer buf for file:// transfers - For file:// transfers use the multi handle's transfer buffer for up- and downloads. Prior to this change a6c9a33 (precedes 8.6.0) changed the file:// transfers to use a smaller stack based buffer, and that caused a significant performance decrease in Windows. Bug: https://github.com/curl/curl/issues/12750#issuecomment-1920103086 Reported-by: edmcln@users.noreply.github.com Closes https://github.com/curl/curl/pull/12932 --- lib/file.c | 48 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 14 deletions(-) diff --git a/lib/file.c b/lib/file.c index b7ce3a8eda1..63089e0f2a9 100644 --- a/lib/file.c +++ b/lib/file.c @@ -59,6 +59,7 @@ #include "file.h" #include "speedcheck.h" #include "getinfo.h" +#include "multiif.h" #include "transfer.h" #include "url.h" #include "parsedate.h" /* for the week day and month names */ @@ -290,7 +291,9 @@ static CURLcode file_upload(struct Curl_easy *data) int fd; int mode; CURLcode result = CURLE_OK; - char buffer[8*1024], *uphere_save; + char *xfer_buf; + size_t xfer_blen; + char *uphere_save; curl_off_t bytecount = 0; struct_stat file_stat; const char *sendbuf; @@ -340,12 +343,18 @@ static CURLcode file_upload(struct Curl_easy *data) /* Yikes! Curl_fillreadbuffer uses data->req.upload_fromhere to READ * client data to! Please, someone fix... */ uphere_save = data->req.upload_fromhere; + + result = Curl_multi_xfer_buf_borrow(data, &xfer_buf, &xfer_blen); + if(result) + goto out; + while(!result) { size_t nread; ssize_t nwrite; size_t readcount; - data->req.upload_fromhere = buffer; - result = Curl_fillreadbuffer(data, sizeof(buffer), &readcount); + + data->req.upload_fromhere = xfer_buf; + result = Curl_fillreadbuffer(data, xfer_blen, &readcount); if(result) break; @@ -359,16 +368,16 @@ static CURLcode file_upload(struct Curl_easy *data) if((curl_off_t)nread <= data->state.resume_from) { data->state.resume_from -= nread; nread = 0; - sendbuf = buffer; + sendbuf = xfer_buf; } else { - sendbuf = buffer + data->state.resume_from; + sendbuf = xfer_buf + data->state.resume_from; nread -= (size_t)data->state.resume_from; data->state.resume_from = 0; } } else - sendbuf = buffer; + sendbuf = xfer_buf; /* write the data to the target */ nwrite = write(fd, sendbuf, nread); @@ -389,7 +398,9 @@ static CURLcode file_upload(struct Curl_easy *data) if(!result && Curl_pgrsUpdate(data)) result = CURLE_ABORTED_BY_CALLBACK; +out: close(fd); + Curl_multi_xfer_buf_release(data, xfer_buf); data->req.upload_fromhere = uphere_save; return result; @@ -419,6 +430,8 @@ static CURLcode file_do(struct Curl_easy *data, bool *done) bool fstated = FALSE; int fd; struct FILEPROTO *file; + char *xfer_buf; + size_t xfer_blen; *done = TRUE; /* unconditionally */ @@ -543,23 +556,26 @@ static CURLcode file_do(struct Curl_easy *data, bool *done) Curl_pgrsTime(data, TIMER_STARTTRANSFER); + result = Curl_multi_xfer_buf_borrow(data, &xfer_buf, &xfer_blen); + if(result) + goto out; + while(!result) { - char tmpbuf[8*1024]; ssize_t nread; /* Don't fill a whole buffer if we want less than all data */ size_t bytestoread; if(size_known) { - bytestoread = (expected_size < (curl_off_t)(sizeof(tmpbuf)-1)) ? - curlx_sotouz(expected_size) : (sizeof(tmpbuf)-1); + bytestoread = (expected_size < (curl_off_t)(xfer_blen-1)) ? + curlx_sotouz(expected_size) : (xfer_blen-1); } else - bytestoread = sizeof(tmpbuf)-1; + bytestoread = xfer_blen-1; - nread = read(fd, tmpbuf, bytestoread); + nread = read(fd, xfer_buf, bytestoread); if(nread > 0) - tmpbuf[nread] = 0; + xfer_buf[nread] = 0; if(nread <= 0 || (size_known && (expected_size == 0))) break; @@ -567,18 +583,22 @@ static CURLcode file_do(struct Curl_easy *data, bool *done) if(size_known) expected_size -= nread; - result = Curl_client_write(data, CLIENTWRITE_BODY, tmpbuf, nread); + result = Curl_client_write(data, CLIENTWRITE_BODY, xfer_buf, nread); if(result) - return result; + goto out; if(Curl_pgrsUpdate(data)) result = CURLE_ABORTED_BY_CALLBACK; else result = Curl_speedcheck(data, Curl_now()); + if(result) + goto out; } if(Curl_pgrsUpdate(data)) result = CURLE_ABORTED_BY_CALLBACK; +out: + Curl_multi_xfer_buf_release(data, xfer_buf); return result; } From 59e2c78af3a5588d6e6ae6d2223b222f067e054b Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 14 Feb 2024 16:27:23 +0100 Subject: [PATCH 334/509] http_chunks: fix the accounting of consumed bytes Prior to this change chunks were handled correctly although in verbose mode libcurl could incorrectly warn of "Leftovers after chunking" even if there were none. Reported-by: Michael Kaufmann Fixes https://github.com/curl/curl/issues/12937 Closes https://github.com/curl/curl/pull/12939 --- lib/http_chunks.c | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/lib/http_chunks.c b/lib/http_chunks.c index 039c179c44c..ad1ee9adab6 100644 --- a/lib/http_chunks.c +++ b/lib/http_chunks.c @@ -152,6 +152,7 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, ch->hexbuffer[ch->hexindex++] = *buf; buf++; blen--; + (*pconsumed)++; } else { char *endptr; @@ -189,6 +190,7 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, buf++; blen--; + (*pconsumed)++; break; case CHUNK_DATA: @@ -236,6 +238,7 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, } buf++; blen--; + (*pconsumed)++; break; case CHUNK_TRAILER: @@ -293,6 +296,7 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, } buf++; blen--; + (*pconsumed)++; break; case CHUNK_TRAILER_CR: @@ -300,6 +304,7 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, ch->state = CHUNK_TRAILER_POSTCR; buf++; blen--; + (*pconsumed)++; } else { ch->state = CHUNK_FAILED; @@ -320,6 +325,7 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, /* skip if CR */ buf++; blen--; + (*pconsumed)++; } /* now wait for the final LF */ ch->state = CHUNK_STOP; @@ -328,6 +334,7 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, case CHUNK_STOP: if(*buf == 0x0a) { blen--; + (*pconsumed)++; /* Record the length of any data left in the end of the buffer even if there's no more chunks to read */ ch->datasize = blen; From b4df2c9fe871d32daece72c8458b8f052640136c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 19 Feb 2024 08:34:37 +0100 Subject: [PATCH 335/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 40 +++++++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 5e58493b75d..bb7cc0cb291 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.6.1 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3090 + Contributors: 3094 This release includes the following changes: @@ -15,8 +15,10 @@ This release includes the following bugfixes: o ALTSVC.md: correct a typo [14] o asyn-thread: use wakeup_close to close the read descriptor [1] o badwords: use hostname, not host name [46] + o checksrc.pl: fix handling .checksrc with CRLF [43] o cmake: add warning for using TLS libraries without 1.3 support [25] o cmake: fix function description in comment [47] + o cmake: fix install for older CMake versions [53] o cmdline-docs/Makefile: avoid using a fixed temp file name [5] o cmdline-docs: quote and angle bracket cleanup [45] o configure: add warning for using TLS libraries without 1.3 support [26] @@ -25,6 +27,7 @@ This release includes the following bugfixes: o cookie.md: provide an example sending a fixed cookie [13] o curl: exit on config file parser errors [40] o curl: when allocating variables, add the name into the struct [37] + o CURLOPT_POSTQUOTE.md: fix typo [36] o CURLOPT_WRITEFUNCTION.md: typo fix [41] o dist: make sure the http tests are in the tarball [29] o docs: add missing slashes to SChannel client certificate documentation [11] @@ -33,6 +36,7 @@ This release includes the following bugfixes: o docs: make curldown do angle brackets like markdown [54] o docs: make sure curl.1 is included in dist tarballs [35] o docs: remove `mk-ca-bundle.1` from `man_MANS` [21] + o file: use xfer buf for file:// transfers [23] 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] @@ -41,23 +45,30 @@ This release includes the following bugfixes: o header.md: remove backslash, make nicer markdown [48] o HTTP/2: write response directly [12] o HTTP3.md: adjust the OpenSSL QUIC install instructions [34] + o http_chunks: fix the accounting of consumed bytes [22] o https-proxy: use IP address and cert with ip in alt names [50] o lib582: remove code causing warning that is never run [38] o lib: convert Curl_get_line to use dynbuf [42] o libcurl-security.md: Active FTP passes on the local IP address [6] o mbedtls: fix building when MBEDTLS_X509_REMOVE_INFO flag is defined [27] + o mbedtls: use mbedtls_ssl_conf_{min|max}_tls_version [59] o md4: include strdup.h for the memdup proto [10] o multi: add xfer_buf to multi handle [30] o ntml_wb: fix buffer type typo [2] o openssl-quic: check on Windows that socket conv to int is possible [8] o OS400: avoid using awk in the build scripts [20] o proxy1.0.md: fix example [15] + 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 test1165: improve pattern matching [60] o tests: support setting/using blank content env variables o tool_cb_hdr: only parse etag + content-disposition for 2xx [9] 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 transfer: improve Windows SO_SNDBUF update limit [56] o version: allow building with ancient libpsl [52] + o vtls: fix tls proxy peer verification [55] o vtls: revert "receive max buffer" + add test case [39] o write-out.md: clarify error handling details [31] @@ -74,14 +85,15 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - Boris Verkhovskiy, Brett Buddin, Chris Webb, Dan Fandrich, Daniel Stenberg, - Daniel Szmulewicz, Dirk Hünniger, Dmitry Tretyakov, Erik Schnetter, - Fabian Vogt, Faraz Fallahi, Harry Sintonen, Jan Macku, Jiawen Geng, - Joel Depooter, Jon Rumsey, Karthikdasari0423, Lars Kellogg-Stedman, - Lukáš Zaoral, Michał Antoniak, Patrick Monnerat, Peter Krefting, Ray Satiro, - Ryan Carsten Schmidt, Scott Mutter, Sergey Bronnikov, Stefan Eissing, - Viktor Szakats - (28 contributors) + Boris Verkhovskiy, Brett Buddin, Chris Webb, Dan Fandrich, Daniel Gustafsson, + Daniel Stenberg, Daniel Szmulewicz, Dirk Hünniger, Dmitry Tretyakov, + edmcln on github, Erik Schnetter, Evgeny Grin (Karlson2k), Fabian Vogt, + Faraz Fallahi, Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, + Joel Depooter, Jon Rumsey, Karthikdasari0423, Konstantin Vlasov, + Lars Kellogg-Stedman, LeeRiva, Lukáš Zaoral, Michael Kaufmann, + Michał Antoniak, Patrick Monnerat, Peter Krefting, Ray Satiro, + Richard Levitte, Ryan Carsten Schmidt, Scott Mutter, Sergey Bronnikov, + Stefan Eissing, Viktor Szakats References to bug reports and discussions on issues: @@ -106,6 +118,8 @@ References to bug reports and discussions on issues: [19] = https://curl.se/bug/?i=12823 [20] = https://curl.se/bug/?i=12826 [21] = https://curl.se/bug/?i=12843 + [22] = https://curl.se/bug/?i=12937 + [23] = https://curl.se/bug/?i=12750 [25] = https://curl.se/bug/?i=12900 [26] = https://curl.se/bug/?i=12900 [27] = https://curl.se/bug/?i=12904 @@ -117,12 +131,14 @@ References to bug reports and discussions on issues: [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 @@ -132,4 +148,10 @@ References to bug reports and discussions on issues: [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 + [59] = https://curl.se/bug/?i=12905 + [60] = https://curl.se/bug/?i=12903 From 50f65b4ef336b1589688aaa6e01a40f1711353d7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 19 Feb 2024 10:56:38 +0100 Subject: [PATCH 336/509] cd2nroff: remove backticks from titles --- scripts/cd2nroff | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/cd2nroff b/scripts/cd2nroff index decaeca0a81..02460cc9da5 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -266,7 +266,7 @@ sub single { if(/^## (.*)/) { my $word = $1; # if there are enclosing quotes, remove them first - $word =~ s/[\"\'](.*)[\"\']\z/$1/; + $word =~ s/[\"\'\`](.*)[\"\'\`]\z/$1/; # enclose in double quotes if there is a space present if($word =~ / /) { From 96af350661482b09447ba06038cbe086e118cf1b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 19 Feb 2024 10:56:14 +0100 Subject: [PATCH 337/509] libcurl-docs: cleanups CURLMOPT_SOCKETDATA.md: fix typo CURLMOPT_TIMERDATA.md: fix typo CURLOPT_COOKIELIST.m: quote strings CURLOPT_PREREQFUNCTION.md: quote variable names CURLOPT_TCP_NODELAY.md: rephrased to please spell checker CURLOPT_WILDCARDMATCH.md: rephrased libcurl-tutorial.md: use correct option name curl_global_init_mem.md: quote headers curl_easy_getinfo.md: use correct symbol names in headers curl_global_trace.md: quote some headers curl_ws_meta.md: quote struct field names libcurl-env.md: quote headers --- docs/libcurl/curl_easy_getinfo.md | 40 ++++++++++----------- docs/libcurl/curl_global_init_mem.md | 10 +++--- docs/libcurl/curl_global_trace.md | 10 +++--- docs/libcurl/curl_ws_meta.md | 17 +++++---- docs/libcurl/libcurl-env.md | 20 +++++------ docs/libcurl/libcurl-tutorial.md | 26 ++++++++------ docs/libcurl/opts/CURLMOPT_SOCKETDATA.md | 2 +- docs/libcurl/opts/CURLMOPT_TIMERDATA.md | 2 +- docs/libcurl/opts/CURLOPT_COOKIELIST.md | 16 ++++----- docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md | 10 +++--- docs/libcurl/opts/CURLOPT_TCP_NODELAY.md | 8 ++--- docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md | 4 +-- 12 files changed, 83 insertions(+), 82 deletions(-) diff --git a/docs/libcurl/curl_easy_getinfo.md b/docs/libcurl/curl_easy_getinfo.md index 3b98ea4ebb0..eb5608be9c1 100644 --- a/docs/libcurl/curl_easy_getinfo.md +++ b/docs/libcurl/curl_easy_getinfo.md @@ -388,59 +388,57 @@ See CURLINFO_XFER_ID(3) An overview of the time values available from curl_easy_getinfo(3) -~~~ -curl_easy_perform() - | - |--QUEUE_TIME - |--|--NAMELOOKUP - |--|--|--CONNECT - |--|--|--|--APPCONNECT - |--|--|--|--|--PRETRANSFER - |--|--|--|--|--|--STARTTRANSFER - |--|--|--|--|--|--|--TOTAL - |--|--|--|--|--|--|--REDIRECT -~~~ - -## QUEUE_TIME + curl_easy_perform() + | + |--QUEUE + |--|--NAMELOOKUP + |--|--|--CONNECT + |--|--|--|--APPCONNECT + |--|--|--|--|--PRETRANSFER + |--|--|--|--|--|--STARTTRANSFER + |--|--|--|--|--|--|--TOTAL + |--|--|--|--|--|--|--REDIRECT + +## CURLINFO_QUEUE_TIME CURLINFO_QUEUE_TIME_T(3). The time during which the transfer was held in a waiting queue before it could start for real. (Added in 8.6.0) -## NAMELOOKUP +## CURLINFO_NAMELOOKUP_TIME CURLINFO_NAMELOOKUP_TIME(3) and CURLINFO_NAMELOOKUP_TIME_T(3). The time it took from the start until the name resolving was completed. -## CONNECT +## CURLINFO_CONNECT_TIME CURLINFO_CONNECT_TIME(3) and CURLINFO_CONNECT_TIME_T(3). The time it took from the start until the connect to the remote host (or proxy) was completed. -## APPCONNECT +## CURLINFO_APPCONNECT_TIME CURLINFO_APPCONNECT_TIME(3) and CURLINFO_APPCONNECT_TIME_T(3). The time it took from the start until the SSL connect/handshake with the remote host was completed. (Added in 7.19.0) The latter is the integer version (measuring microseconds). (Added in 7.60.0) -## PRETRANSFER +## CURLINFO_PRETRANSFER_TIME CURLINFO_PRETRANSFER_TIME(3) and CURLINFO_PRETRANSFER_TIME_T(3). The time it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. -## STARTTRANSFER +## CURLINFO_STARTTRANSFER_TIME CURLINFO_STARTTRANSFER_TIME(3) and CURLINFO_STARTTRANSFER_TIME_T(3). The time it took from the start until the first byte is received by libcurl. -## TOTAL +## CURLINFO_TOTAL_TIME CURLINFO_TOTAL_TIME(3) and CURLINFO_TOTAL_TIME_T(3). Total time of the previous request. -## REDIRECT +## CURLINFO_REDIRECT_TIME CURLINFO_REDIRECT_TIME(3) and CURLINFO_REDIRECT_TIME_T(3). The time it took for all redirection steps include name lookup, connect, pretransfer and diff --git a/docs/libcurl/curl_global_init_mem.md b/docs/libcurl/curl_global_init_mem.md index 96af23b05f7..d4f24ac943e 100644 --- a/docs/libcurl/curl_global_init_mem.md +++ b/docs/libcurl/curl_global_init_mem.md @@ -40,23 +40,23 @@ default) so we strongly urge you to make your callback functions thread safe. All callback arguments must be set to valid function pointers. The prototypes for the given callbacks must match these: -## void *malloc_callback(size_t size); +## `void *malloc_callback(size_t size);` To replace malloc() -## void free_callback(void *ptr); +## `void free_callback(void *ptr);` To replace free() -## void *realloc_callback(void *ptr, size_t size); +## `void *realloc_callback(void *ptr, size_t size);` To replace realloc() -## char *strdup_callback(const char *str); +## `char *strdup_callback(const char *str);` To replace strdup() -## void *calloc_callback(size_t nmemb, size_t size); +## `void *calloc_callback(size_t nmemb, size_t size);` To replace calloc() diff --git a/docs/libcurl/curl_global_trace.md b/docs/libcurl/curl_global_trace.md index c9168352acd..aef2832fcef 100644 --- a/docs/libcurl/curl_global_trace.md +++ b/docs/libcurl/curl_global_trace.md @@ -65,23 +65,23 @@ on how to control that. # TRACE COMPONENTS -## tcp +## `tcp` Tracing of TCP socket handling: connect, reads, writes. -## ssl +## `ssl` Tracing of SSL/TLS operations, whichever SSL backend is used in your build. -## http/2 +## `http/2` Details about HTTP/2 handling: frames, events, I/O, etc. -## http/3 +## `http/3` Details about HTTP/3 handling: connect, frames, events, I/O etc. -## http-proxy +## `http-proxy` Involved when transfers are tunneled through an HTTP proxy. "h1-proxy" or "h2-proxy" are also involved, depending on the HTTP version negotiated with diff --git a/docs/libcurl/curl_ws_meta.md b/docs/libcurl/curl_ws_meta.md index 531791a519b..71fcb8b3174 100644 --- a/docs/libcurl/curl_ws_meta.md +++ b/docs/libcurl/curl_ws_meta.md @@ -51,25 +51,24 @@ struct curl_ws_frame { }; ~~~ -## age +## `age` This field specify the age of this struct. It is always zero for now. -## flags +## `flags` -This is a bitmask with individual bits set that describes the WebSocket -data. See the list below. +This is a bitmask with individual bits set that describes the WebSocket data. +See the list below. -## offset +## `offset` When this frame is a continuation of fragment data already delivered, this is the offset into the final fragment where this piece belongs. -## bytesleft +## `bytesleft` -If this is not a complete fragment, the *bytesleft* field informs about -how many additional bytes are expected to arrive before this fragment is -complete. +If this is not a complete fragment, the *bytesleft* field informs about how +many additional bytes are expected to arrive before this fragment is complete. # FLAGS diff --git a/docs/libcurl/libcurl-env.md b/docs/libcurl/libcurl-env.md index c27f7cea202..1205b8d391e 100644 --- a/docs/libcurl/libcurl-env.md +++ b/docs/libcurl/libcurl-env.md @@ -19,7 +19,7 @@ controls and changes behaviors. This is the full list of variables to set and description of what they do. Also note that curl, the command line tool, supports a set of additional environment variables independently of this. -## [scheme]_proxy +## `[scheme]_proxy` When libcurl is given a URL to use in a transfer, it first extracts the scheme part from the URL and checks if there is a given proxy set for that in its @@ -36,12 +36,12 @@ An exception exists for the WebSocket **ws** and **wss** URL schemes, where libcurl first checks **ws_proxy** or **wss_proxy** but if they are not set, it will fall back and try the http and https versions instead if set. -## ALL_PROXY +## `ALL_PROXY` This is a setting to set proxy for all URLs, independently of what scheme is being used. Note that the scheme specific variables overrides this one if set. -## CURL_SSL_BACKEND +## `CURL_SSL_BACKEND` When libcurl is built to support multiple SSL backends, it selects a specific backend at first use. If no selection is done by the program using libcurl, @@ -51,34 +51,34 @@ alternative makes libcurl stay with the default. SSL backend names (case-insensitive): BearSSL, GnuTLS, mbedTLS, nss, OpenSSL, rustls, Schannel, Secure-Transport, wolfSSL -## HOME +## `HOME` When the netrc feature is used (CURLOPT_NETRC(3)), this variable is checked as the primary way to find the "current" home directory in which the .netrc file is likely to exist. -## USERPROFILE +## `USERPROFILE` When the netrc feature is used (CURLOPT_NETRC(3)), this variable is checked as the secondary way to find the "current" home directory (on Windows only) in which the .netrc file is likely to exist. -## LOGNAME +## `LOGNAME` Username to use when invoking the *ntlm-wb* tool, if *NTLMUSER* was not set. -## NO_PROXY +## `NO_PROXY` This has the same functionality as the CURLOPT_NOPROXY(3) option: it gives libcurl a comma-separated list of hostname patterns for which libcurl should not use a proxy. -## NTLMUSER +## `NTLMUSER` Username to use when invoking the *ntlm-wb* tool. -## SSLKEYLOGFILE +## `SSLKEYLOGFILE` When set and libcurl runs with a SSL backend that supports this feature, libcurl saves SSL secrets into the given filename. Using those SSL secrets, @@ -88,7 +88,7 @@ analyze/view the traffic. These secrets and this file might be sensitive. Users are advised to take precautions so that they are not stolen or otherwise inadvertently revealed. -## USER +## `USER` Username to use when invoking the *ntlm-wb* tool, if *NTLMUSER* and *LOGNAME* were not set. diff --git a/docs/libcurl/libcurl-tutorial.md b/docs/libcurl/libcurl-tutorial.md index 2952856de79..c5e2ebca1a5 100644 --- a/docs/libcurl/libcurl-tutorial.md +++ b/docs/libcurl/libcurl-tutorial.md @@ -1021,14 +1021,16 @@ manners. You may need to change words, headers or various data. libcurl is your friend here too. -## CUSTOMREQUEST +## CURLOPT_CUSTOMREQUEST If just changing the actual HTTP request keyword is what you want, like when GET, HEAD or POST is not good enough for you, CURLOPT_CUSTOMREQUEST(3) is there for you. It is simple to use: + ~~~c curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); ~~~ + When using the custom request, you change the request keyword of the actual request you are performing. Thus, by default you make a GET request but you can also make a POST operation (as described before) and then replace the POST @@ -1141,20 +1143,20 @@ The option to enable headers or to run custom FTP commands may be useful to combine with CURLOPT_NOBODY(3). If this option is set, no actual file content transfer is performed. -## FTP Custom CUSTOMREQUEST +## FTP Custom CURLOPT_CUSTOMREQUEST If you do want to list the contents of an FTP directory using your own defined -FTP command, CURLOPT_CUSTOMREQUEST(3) does just that. "NLST" is the -default one for listing directories but you are free to pass in your idea of a -good alternative. +FTP command, CURLOPT_CUSTOMREQUEST(3) does just that. "NLST" is the default +one for listing directories but you are free to pass in your idea of a good +alternative. # Cookies Without Chocolate Chips In the HTTP sense, a cookie is a name with an associated value. A server sends the name and value to the client, and expects it to get sent back on every -subsequent request to the server that matches the particular conditions -set. The conditions include that the domain name and path match and that the -cookie has not become too old. +subsequent request to the server that matches the particular conditions set. +The conditions include that the domain name and path match and that the cookie +has not become too old. In real-world cases, servers send new cookies to replace existing ones to update them. Server use cookies to "track" users and to keep "sessions". @@ -1164,12 +1166,14 @@ they are sent from clients to servers with the Cookie: header. To just send whatever cookie you want to a server, you can use CURLOPT_COOKIE(3) to set a cookie string like this: + ~~~c curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); ~~~ -In many cases, that is not enough. You might want to dynamically save -whatever cookies the remote server passes to you, and make sure those cookies -are then used accordingly on later requests. + +In many cases, that is not enough. You might want to dynamically save whatever +cookies the remote server passes to you, and make sure those cookies are then +used accordingly on later requests. One way to do this, is to save all headers you receive in a plain file and when you make a request, you tell libcurl to read the previous headers to diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md index f4de8c331a1..20c3feeb266 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md @@ -28,7 +28,7 @@ A data *pointer* to pass to the socket callback set with the CURLMOPT_SOCKETFUNCTION(3) option. This pointer is not touched by libcurl but is only passed in as the socket -callbacks's **clientp** argument. +callback's **clientp** argument. # DEFAULT diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md index 13bbd925b35..08a940b9771 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md +++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md @@ -27,7 +27,7 @@ A data **pointer** to pass to the timer callback set with the CURLMOPT_TIMERFUNCTION(3) option. This pointer is not touched by libcurl but is only be passed in to the timer -callbacks's **clientp** argument. +callback's **clientp** argument. # DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.md b/docs/libcurl/opts/CURLOPT_COOKIELIST.md index 4c17bd4bc67..16298775ca0 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.md +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.md @@ -29,37 +29,37 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST, Pass a char pointer to a *cookie* string. Such a cookie can be either a single line in Netscape / Mozilla format or just -regular HTTP-style header (Set-Cookie: ...) format. This option also enables -the cookie engine. This adds that single cookie to the internal cookie store. +regular HTTP-style header (`Set-Cookie:`) format. This option also enables the +cookie engine. This adds that single cookie to the internal cookie store. We strongly advice against loading cookies from an HTTP header file, as that is an inferior data exchange format. Exercise caution if you are using this option and multiple transfers may -occur. If you use the Set-Cookie format and the string does not specify a +occur. If you use the `Set-Cookie` format and the string does not specify a domain, then the cookie is sent for any domain (even after redirects are followed) and cannot be modified by a server-set cookie. If a server sets a cookie of the same name (or maybe you have imported one) then both are sent on future transfers to that server, likely not what you intended. To address -these issues set a domain in Set-Cookie (doing that includes subdomains) or +these issues set a domain in `Set-Cookie` (doing that includes subdomains) or much better: use the Netscape file format. Additionally, there are commands available that perform actions if you pass in these exact strings: -## ALL +## `ALL` erases all cookies held in memory -## SESS +## `SESS` erases all session cookies held in memory -## FLUSH +## `FLUSH` writes all known cookies to the file specified by CURLOPT_COOKIEJAR(3) -## RELOAD +## `RELOAD` loads all cookies from the files specified by CURLOPT_COOKIEFILE(3) diff --git a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md index c8140849475..2c334d94a96 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md @@ -52,30 +52,30 @@ The callback function must return *CURL_PREREQFUNC_OK* on success, or This function is passed the following arguments: -## conn_primary_ip +## `conn_primary_ip` A null-terminated pointer to a C string containing the primary IP of the remote server established with this connection. For FTP, this is the IP for the control connection. IPv6 addresses are represented without surrounding brackets. -## conn_local_ip +## `conn_local_ip` A null-terminated pointer to a C string containing the originating IP for this connection. IPv6 addresses are represented without surrounding brackets. -## conn_primary_port +## `conn_primary_port` The primary port number on the remote server established with this connection. For FTP, this is the port for the control connection. This can be a TCP or a UDP port number depending on the protocol. -## conn_local_port +## `conn_local_port` The originating port number for this connection. This can be a TCP or a UDP port number depending on the protocol. -## clientp +## `clientp` The pointer you set with CURLOPT_PREREQDATA(3). diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md index 7fe286d26d1..2613e0a1645 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md @@ -28,10 +28,10 @@ Pass a long specifying whether the *TCP_NODELAY* option is to be set or cleared (1L = set, 0 = clear). The option is set by default. This has no effect after the connection has been established. -Setting this option to 1L disables TCP's Nagle algorithm on connections -created using this handle. The purpose of this algorithm is to try to minimize -the number of small packets on the network (where "small packets" means TCP -segments less than the Maximum Segment Size for the network). +Setting this option to 1L disables the Nagle algorithm on connections created +using this handle. The purpose of this algorithm is to minimize the number of +small packets on the network (where "small packets" means TCP segments less +than the Maximum Segment Size for the network). Maximizing the amount of data sent per TCP segment is good because it amortizes the overhead of the send. However, in some cases small segments may diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md index 75412656734..98c99441085 100644 --- a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md +++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md @@ -40,8 +40,8 @@ A brief introduction of its syntax follows: ftp://example.com/some/path/*.txt -for all txt's from the root directory. Only two asterisks are allowed within -the same pattern string. +matches all `.txt` files in the root directory. Only two asterisks are allowed +within the same pattern string. ## ? - QUESTION MARK From 8b1f3aa6087335456b6f16b039b983d14971d4b6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 19 Feb 2024 09:54:21 +0100 Subject: [PATCH 338/509] spellcheck.yml: remove .1/.3 handling, clean all man page .md files Since we generate all .1 and .3 files from markdown now, we can limit the spellcheck to the markdown versions only. Closes #12960 --- .github/scripts/cleancmd.pl | 8 +++-- .github/scripts/cleanspell.pl | 52 ++++++++++++++++++-------------- .github/scripts/spellcheck.words | 5 ++- .github/workflows/spellcheck.yml | 40 ++++++------------------ 4 files changed, 47 insertions(+), 58 deletions(-) diff --git a/.github/scripts/cleancmd.pl b/.github/scripts/cleancmd.pl index 5d0fe2b2fbb..fabcce23b98 100755 --- a/.github/scripts/cleancmd.pl +++ b/.github/scripts/cleancmd.pl @@ -47,6 +47,8 @@ } close(F); -open(O, ">$f") or die; -print O @out; -close(O); +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 06648a3f99f..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,25 +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/libcurl\\-(env|ws)//g; - $_ =~ s/(^|\W)((tftp|https|http|ftp):\/\/[a-z0-9\-._~%:\/?\#\[\]\@!\$&'()*+,;=]+)//gi; - print O $_; + $_ =~ 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 4495454e174..1c408f03aa2 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -39,6 +39,7 @@ auth autobuild autobuilds Autoconf +autoconf Automake Autotools autotools @@ -111,8 +112,8 @@ clientp cliget closesocket CMake -CMake's cmake +CMake's cmake's CMakeLists CodeQL @@ -283,6 +284,7 @@ GPL GPLed Greear groff +gsasl GSKit gskit GSS @@ -795,6 +797,7 @@ Tekniska testability TFTP tftp +threadsafe Tizen TLS tlsv diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index a619fcc0469..e78a36ca7ab 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -9,21 +9,17 @@ on: - master paths: - '**.md' - - '**.3' - - '**.1' - '**/spellcheck.yml' - '**/spellcheck.yaml' - - '**/wordlist.txt' + - '.github/scripts/*' pull_request: branches: - master paths: - '**.md' - - '**.3' - - '**.1' - '**/spellcheck.yml' - '**/spellcheck.yaml' - - '**/wordlist.txt' + - '.github/scripts/*' permissions: {} @@ -33,34 +29,16 @@ jobs: steps: - 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 --without-libpsl - 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: 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: 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: trim the cmdline docs markdown files - run: find docs/cmdline-opts -name "*.md" ! -name "_*" ! -name MANPAGE.md | xargs -n1 ./.github/scripts/cleancmd.pl - - - name: trim the cmdline docs markdown _*.md files + - name: trim cmdline docs markdown _*.md files run: find docs/cmdline-opts -name "_*.md" | xargs -n1 ./.github/scripts/cleancmd.pl --no-header - name: setup the custom wordlist From 33d3153de96beb1c925d4d0e1c76152b8db4fc8a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 19 Feb 2024 09:31:08 +0100 Subject: [PATCH 339/509] mk-ca-bundle.md: cleanups and polish Closes #12958 --- docs/mk-ca-bundle.md | 46 +++++++++++++++++++++----------------------- 1 file changed, 22 insertions(+), 24 deletions(-) diff --git a/docs/mk-ca-bundle.md b/docs/mk-ca-bundle.md index bacfce08b23..c0ffab30fd0 100644 --- a/docs/mk-ca-bundle.md +++ b/docs/mk-ca-bundle.md @@ -14,19 +14,18 @@ mk-ca-bundle - convert Mozilla's certificate bundle to PEM format # SYNOPSIS -mk-ca-bundle [options] -*[outputfile]* +mk-ca-bundle [options] [output] # DESCRIPTION -The mk-ca-bundle tool downloads the *certdata.txt* file from Mozilla's source -tree over HTTPS, then parses *certdata.txt* and extracts certificates into PEM -format. By default, only CA root certificates trusted to issue SSL server +This tool downloads the *certdata.txt* file from Mozilla's source tree over +HTTPS, then parses it and extracts the included certificates into PEM format. +By default, only CA root certificates trusted to issue SSL server authentication certificates are extracted. These are then processed with the -OpenSSL command line tool to produce the final ca-bundle file. +OpenSSL command line tool to produce the final ca-bundle output file. -The default *outputfile* name is **ca-bundle.crt**. By setting it to '-' (a -single dash) you will get the output sent to STDOUT instead of a file. +The default *output* name is **ca-bundle.crt**. By setting it to '-' (a single +dash) you will get the output sent to STDOUT instead of a file. The PEM format this scripts uses for output makes the result readily available for use by just about all OpenSSL or GnuTLS powered applications, such as curl @@ -38,14 +37,14 @@ The following options are supported: ## -b -backup an existing version of *outputfilename* +backup an existing version of *output* ## -d [name] -specify which Mozilla tree to pull *certdata.txt* from (or a custom -URL). Valid names are: aurora, beta, central, Mozilla, nss, release -(default). They are shortcuts for which source tree to get the certificates -data from. +specify which Mozilla tree to pull *certdata.txt* from (or a custom URL). +Valid names are: **aurora**, **beta**, **central**, **Mozilla**, **nss**, +**release** (default). They are shortcuts for which source tree to get the +certificate data from. ## -f @@ -74,7 +73,7 @@ to the output file. The meta data is not parsed in any way by mk-ca-bundle. ## -n -no download of *certdata.txt* (to use existing) +Do not download *certdata.txt* - use the existing. ## -p [purposes]:[levels] @@ -83,14 +82,14 @@ output. Takes the form of a comma separated list of purposes, a colon, and a comma separated list of levels. The default is to include all certificates trusted to issue SSL Server certificates (*SERVER_AUTH:TRUSTED_DELEGATOR*). -Valid purposes are: *ALL*, *DIGITAL_SIGNATURE*, *NON_REPUDIATION*, -*KEY_ENCIPHERMENT*, *DATA_ENCIPHERMENT*, *KEY_AGREEMENT*, *KEY_CERT_SIGN*, -*CRL_SIGN*, *SERVER_AUTH* (default), *CLIENT_AUTH*, *CODE_SIGNING*, -*EMAIL_PROTECTION*, *IPSEC_END_SYSTEM*, *IPSEC_TUNNEL*, *IPSEC_USER*, -*TIME_STAMPING*, *STEP_UP_APPROVED* +Valid purposes are: **ALL**, **DIGITAL_SIGNATURE**, **NON_REPUDIATION**, +**KEY_ENCIPHERMENT**, **DATA_ENCIPHERMENT**, **KEY_AGREEMENT**, +**KEY_CERT_SIGN**, **CRL_SIGN**, **SERVER_AUTH** (default), **CLIENT_AUTH**, +**CODE_SIGNING**, **EMAIL_PROTECTION**, **IPSEC_END_SYSTEM**, +**IPSEC_TUNNEL**, **IPSEC_USER**, **TIME_STAMPING**, **STEP_UP_APPROVED** -Valid trust levels are: *ALL*, *TRUSTED_DELEGATOR* (default), *NOT_TRUSTED*, -*MUST_VERIFY_TRUST*, *TRUSTED* +Valid trust levels are: **ALL**, **TRUSTED_DELEGATOR** (default), **NOT_TRUSTED**, +**MUST_VERIFY_TRUST**, **TRUSTED** ## -q @@ -102,7 +101,7 @@ include plain text listing of certificates ## -s [algorithms] -comma separated list of signature algorithms with which to hash/fingerprint +A comma separated list of signature algorithms with which to hash/fingerprint each certificate and output when run in plain text mode. Valid algorithms are: @@ -123,6 +122,5 @@ Returns 0 on success. Returns 1 if it fails to download data. # FILE FORMAT The file format used by Mozilla for this trust information is documented here: -~~~c + https://p11-glue.freedesktop.org/doc/storing-trust-policy/storing-trust-existing.html -~~~ From 5f48ba172edcf20660338672d3ffe27d28348d30 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 19 Feb 2024 16:50:30 +0100 Subject: [PATCH 340/509] BINDINGS: add mcurl, the python binding Ref: #12956 Closes #12962 --- docs/BINDINGS.md | 2 ++ 1 file changed, 2 insertions(+) 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) From 36401d0d4aff76a750769e06f2e47300205325b0 Mon Sep 17 00:00:00 2001 From: Ramiro Garcia <79334304+ranemirusG@users.noreply.github.com> Date: Mon, 19 Feb 2024 15:29:50 -0300 Subject: [PATCH 341/509] MANUAL.md: fix typo Closes #12965 --- docs/MANUAL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 04542b98753..86a007db68f 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -395,7 +395,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 From bdff974f4679407932f586b0d235797e215a9e07 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 13 Feb 2024 13:59:03 +0100 Subject: [PATCH 342/509] OpenSSL QUIC: adapt to v3.3.x - set our idle timeout as transport parameter - query negotiated idle timeout for connection alive checks - query number of available bidi streams on a connection - use write_ex2 with SSL_WRITE_FLAG_CONCLUDE to signal EOF on last chunk write, so stream close does not require an additional QUIC packet Closes #12933 --- lib/vquic/curl_osslq.c | 65 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 7 deletions(-) diff --git a/lib/vquic/curl_osslq.c b/lib/vquic/curl_osslq.c index 9766feb2114..ede60e29d8b 100644 --- a/lib/vquic/curl_osslq.c +++ b/lib/vquic/curl_osslq.c @@ -1109,6 +1109,16 @@ static CURLcode cf_osslq_ctx_start(struct Curl_cfilter *cf, goto out; } +#ifdef SSL_VALUE_QUIC_IDLE_TIMEOUT + /* Added in OpenSSL v3.3.x */ + if(!SSL_set_feature_request_uint(ctx->tls.ssl, SSL_VALUE_QUIC_IDLE_TIMEOUT, + CURL_QUIC_MAX_IDLE_MS)) { + CURL_TRC_CF(data, cf, "error setting idle timeout, "); + result = CURLE_FAILED_INIT; + goto out; + } +#endif + SSL_set_bio(ctx->tls.ssl, bio, bio); bio = NULL; SSL_set_connect_state(ctx->tls.ssl); @@ -1375,7 +1385,7 @@ static CURLcode h3_send_streams(struct Curl_cfilter *cf, size_t written; int eos, ok, rv; size_t total_len, acked_len = 0; - bool blocked = FALSE; + bool blocked = FALSE, eos_written = FALSE; n = nghttp3_conn_writev_stream(ctx->h3.conn, &stream_id, &eos, vec, ARRAYSIZE(vec)); @@ -1406,9 +1416,19 @@ static CURLcode h3_send_streams(struct Curl_cfilter *cf, for(i = 0; (i < n) && !blocked; ++i) { /* Without stream->s.ssl, we closed that already, so * pretend the write did succeed. */ +#ifdef SSL_WRITE_FLAG_CONCLUDE + /* Since OpenSSL v3.3.x, on last chunk set EOS if needed */ + uint64_t flags = (eos && ((i + 1) == n))? SSL_WRITE_FLAG_CONCLUDE : 0; + written = vec[i].len; + ok = !s->ssl || SSL_write_ex2(s->ssl, vec[i].base, vec[i].len, flags, + &written); + if(ok && flags & SSL_WRITE_FLAG_CONCLUDE) + eos_written = TRUE; +#else written = vec[i].len; ok = !s->ssl || SSL_write_ex(s->ssl, vec[i].base, vec[i].len, &written); +#endif if(ok) { /* As OpenSSL buffers the data, we count this as acknowledged * from nghttp3's point of view */ @@ -1440,6 +1460,7 @@ static CURLcode h3_send_streams(struct Curl_cfilter *cf, if(acked_len > 0 || (eos && !s->send_blocked)) { /* Since QUIC buffers the data written internally, we can tell * nghttp3 that it can move forward on it */ + ctx->q.last_io = Curl_now(); rv = nghttp3_conn_add_write_offset(ctx->h3.conn, s->id, acked_len); if(rv && rv != NGHTTP3_ERR_STREAM_NOT_FOUND) { failf(data, "nghttp3_conn_add_write_offset returned error: %s\n", @@ -1458,7 +1479,7 @@ static CURLcode h3_send_streams(struct Curl_cfilter *cf, "to QUIC, eos=%d", s->id, acked_len, total_len, eos); } - if(eos && !s->send_blocked) { + if(eos && !s->send_blocked && !eos_written) { /* wrote everything and H3 indicates end of stream */ CURL_TRC_CF(data, cf, "[%" PRId64 "] closing QUIC stream", s->id); SSL_stream_conclude(s->ssl, 0); @@ -1583,6 +1604,7 @@ static CURLcode cf_osslq_connect(struct Curl_cfilter *cf, if(err == 1) { /* connected */ ctx->handshake_at = now; + ctx->q.last_io = now; CURL_TRC_CF(data, cf, "handshake complete after %dms", (int)Curl_timediff(now, ctx->started_at)); result = cf_osslq_verify_peer(cf, data); @@ -1598,15 +1620,18 @@ static CURLcode cf_osslq_connect(struct Curl_cfilter *cf, int detail = SSL_get_error(ctx->tls.ssl, err); switch(detail) { case SSL_ERROR_WANT_READ: + ctx->q.last_io = now; CURL_TRC_CF(data, cf, "QUIC SSL_connect() -> WANT_RECV"); result = Curl_vquic_tls_before_recv(&ctx->tls, cf, data); goto out; case SSL_ERROR_WANT_WRITE: + ctx->q.last_io = now; CURL_TRC_CF(data, cf, "QUIC SSL_connect() -> WANT_SEND"); result = CURLE_OK; goto out; #ifdef SSL_ERROR_WANT_ASYNC case SSL_ERROR_WANT_ASYNC: + ctx->q.last_io = now; CURL_TRC_CF(data, cf, "QUIC SSL_connect() -> WANT_ASYNC"); result = CURLE_OK; goto out; @@ -2069,7 +2094,24 @@ static bool cf_osslq_conn_is_alive(struct Curl_cfilter *cf, if(!ctx->tls.ssl) goto out; - /* TODO: how to check negotiated connection idle time? */ +#ifdef SSL_VALUE_QUIC_IDLE_TIMEOUT + /* Added in OpenSSL v3.3.x */ + { + timediff_t idletime; + uint64_t idle_ms = ctx->max_idle_ms; + if(!SSL_get_value_uint(ctx->tls.ssl, SSL_VALUE_CLASS_FEATURE_NEGOTIATED, + SSL_VALUE_QUIC_IDLE_TIMEOUT, &idle_ms)) { + CURL_TRC_CF(data, cf, "error getting negotiated idle timeout, " + "assume connection is dead."); + goto out; + } + CURL_TRC_CF(data, cf, "negotiated idle timeout: %zums", (size_t)idle_ms); + idletime = Curl_timediff(Curl_now(), ctx->q.last_io); + if(idletime > 0 && (uint64_t)idletime > idle_ms) + goto out; + } + +#endif if(!cf->next || !cf->next->cft->is_alive(cf->next, data, input_pending)) goto out; @@ -2125,15 +2167,24 @@ static CURLcode cf_osslq_query(struct Curl_cfilter *cf, int query, int *pres1, void *pres2) { struct cf_osslq_ctx *ctx = cf->ctx; - struct cf_call_data save; switch(query) { case CF_QUERY_MAX_CONCURRENT: { - /* TODO: how to get this? */ - CF_DATA_SAVE(save, cf, data); +#ifdef SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL + /* Added in OpenSSL v3.3.x */ + uint64_t v; + if(!SSL_get_value_uint(ctx->tls.ssl, SSL_VALUE_CLASS_GENERIC, + SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL, &v)) { + CURL_TRC_CF(data, cf, "error getting available local bidi streams"); + return CURLE_HTTP3; + } + /* we report avail + in_use */ + v += CONN_INUSE(cf->conn); + *pres1 = (v > INT_MAX)? INT_MAX : (int)v; +#else *pres1 = 100; +#endif CURL_TRC_CF(data, cf, "query max_conncurrent -> %d", *pres1); - CF_DATA_RESTORE(cf, save); return CURLE_OK; } case CF_QUERY_CONNECT_REPLY_MS: From ab027d9cbcebf2aec1687dfef2b00ab32d39fb9c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 19 Feb 2024 09:32:07 +0100 Subject: [PATCH 343/509] docs: dist curl*.1 and install without perl Drop docs/mk-ca-bundle.1 from the tarball. It can be generated at will. Closes #12959 Fixes #12921 Reported-by: Michael Forney --- Makefile.am | 1 + docs/Makefile.am | 17 +++++++++-------- docs/libcurl/Makefile.am | 1 - docs/libcurl/opts/Makefile.am | 1 - 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/Makefile.am b/Makefile.am index 6457d03dc43..bc995f1ed56 100644 --- a/Makefile.am +++ b/Makefile.am @@ -249,6 +249,7 @@ install-data-hook: else install-data-hook: (cd include && $(MAKE) install) + (cd docs && $(MAKE) install) endif # We extend the standard uninstall with a custom hook: diff --git a/docs/Makefile.am b/docs/Makefile.am index 96c876019aa..7dff4336150 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -30,12 +30,7 @@ MK_CA_DOCS = mk-ca-bundle.1 CURLCONF_DOCS = curl-config.1 endif - -# 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 = $(MK_CA_DOCS) -dist_man_MANS = $(CURLCONF_DOCS) $(MK_CA_DOCS) +man_MANS = $(abs_builddir)/curl.1 curl-config.1 CURLPAGES = curl-config.md mk-ca-bundle.md # Build targets in this file (.) before cmdline-opts to ensure that @@ -43,11 +38,13 @@ CURLPAGES = curl-config.md mk-ca-bundle.md SUBDIRS = . cmdline-opts libcurl DIST_SUBDIRS = $(SUBDIRS) examples -CLEANFILES = $(man_MANS) curl.1 $(CURLCONF_DOCS) $(MK_CA_DOCS) -nodist_MANS = $(CLEANFILES) +if BUILD_DOCS +CLEANFILES = curl.1 mk-ca-bundle.1 curl-config.1 +endif EXTRA_DIST = \ $(CURLPAGES) \ + $(CURLCONF_DOCS) \ ALTSVC.md \ BINDINGS.md \ BUFREF.md \ @@ -112,6 +109,8 @@ CD2_ = $(CD2_0) SUFFIXES = .1 .md +all: $(MK_CA_DOCS) + # $(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 @@ -131,6 +130,8 @@ $(abs_builddir)/curl.1: curl-config.1: curl-config.md +mk-ca-bundle.1: mk-ca-bundle.md + distclean: rm -f $(CLEANFILES) diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 1a70b967334..d6e43149262 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -36,7 +36,6 @@ m4macrodir = $(datadir)/aclocal dist_m4macro_DATA = libcurl.m4 CLEANFILES = $(man_MANS) libcurl-symbols.md -nodist_MANS = $(man_MANS) EXTRA_DIST = $(CURLPAGES) ABI.md symbols-in-versions symbols.pl \ mksymbolsmanpage.pl CMakeLists.txt diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am index 111202ddd39..be877c52ef9 100644 --- a/docs/libcurl/opts/Makefile.am +++ b/docs/libcurl/opts/Makefile.am @@ -30,7 +30,6 @@ include Makefile.inc CURLPAGES = $(man_MANS:.3=.md) endif CLEANFILES = $(man_MANS) -nodist_MANS = $(man_MANS) EXTRA_DIST = $(CURLPAGES) CMakeLists.txt From 30a3880f6b57bf1a597b66de6191548f2725a7ee Mon Sep 17 00:00:00 2001 From: Evgeny Grin Date: Sat, 10 Feb 2024 19:28:27 +0100 Subject: [PATCH 344/509] curl_setup.h: add curl_uint64_t internal type The unsigned version of curl_off_t basically --- lib/curl_setup.h | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/lib/curl_setup.h b/lib/curl_setup.h index 703e903fa8f..644a8e2742d 100644 --- a/lib/curl_setup.h +++ b/lib/curl_setup.h @@ -266,6 +266,13 @@ #include +/* Helper macro to expand and concatenate two macros. + * Direct macros concatenation does not work because macros + * are not expanded before direct concatenation. + */ +#define CURL_CONC_MACROS_(A,B) A ## B +#define CURL_CONC_MACROS(A,B) CURL_CONC_MACROS_(A,B) + /* curl uses its own printf() function internally. It understands the GNU * format. Use this format, so that is matches the GNU format attribute we * use with the mingw compiler, allowing it to verify them at compile-time. @@ -495,6 +502,18 @@ #endif #define CURL_OFF_T_MIN (-CURL_OFF_T_MAX - CURL_OFF_T_C(1)) +#if (SIZEOF_CURL_OFF_T != 8) +# error "curl_off_t must be exactly 64 bits" +#else + typedef unsigned CURL_TYPEOF_CURL_OFF_T curl_uint64_t; +# ifndef CURL_SUFFIX_CURL_OFF_TU +# error "CURL_SUFFIX_CURL_OFF_TU must be defined" +# endif +# define CURL_UINT64_SUFFIX CURL_SUFFIX_CURL_OFF_TU +# define CURL_UINT64_C(val) CURL_CONC_MACROS(val,CURL_UINT64_SUFFIX) +# define CURL_UINT64_CAST(expr) ((curl_uint64_t)(expr)) +#endif + #if (SIZEOF_TIME_T == 4) # ifdef HAVE_TIME_T_UNSIGNED # define TIME_T_MAX UINT_MAX From cbe41d151d6a100c1f045eaf37ff06b2b2a7b382 Mon Sep 17 00:00:00 2001 From: Evgeny Grin Date: Wed, 7 Feb 2024 23:06:28 +0100 Subject: [PATCH 345/509] SHA-512/256: implement hash algorithm Closes #12897 --- lib/Makefile.inc | 2 + lib/curl_sha512_256.c | 601 ++++++++++++++++++++++++++++++++++++++++++ lib/curl_sha512_256.h | 44 ++++ tests/test1165.pl | 4 +- 4 files changed, 650 insertions(+), 1 deletion(-) create mode 100644 lib/curl_sha512_256.c create mode 100644 lib/curl_sha512_256.h diff --git a/lib/Makefile.inc b/lib/Makefile.inc index 627148abeb4..fc437ee9028 100644 --- a/lib/Makefile.inc +++ b/lib/Makefile.inc @@ -134,6 +134,7 @@ LIB_CFILES = \ curl_range.c \ curl_rtmp.c \ curl_sasl.c \ + curl_sha512_256.c \ curl_sspi.c \ curl_threads.c \ curl_trc.c \ @@ -277,6 +278,7 @@ LIB_HFILES = \ curl_setup.h \ curl_setup_once.h \ curl_sha256.h \ + curl_sha512_256.h \ curl_sspi.h \ curl_threads.h \ curl_trc.h \ diff --git a/lib/curl_sha512_256.c b/lib/curl_sha512_256.c new file mode 100644 index 00000000000..c15f625df9c --- /dev/null +++ b/lib/curl_sha512_256.c @@ -0,0 +1,601 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) Evgeny Grin (Karlson2k), . + * + * 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 "curl_setup.h" + +#if !defined(CURL_DISABLE_DIGEST_AUTH) && !defined(CURL_DISABLE_SHA512_256) + +#include "curl_sha512_256.h" +#include "warnless.h" + +/* ** This implementation of SHA-512/256 hash calculation was originally ** * + * ** written by Evgeny Grin (Karlson2k) for GNU libmicrohttpd. ** * + * ** The author ported the code to libcurl. The ported code is provided ** * + * ** under curl license. ** * + * ** This is a minimal version with minimal optimisations. Performance ** * + * ** can be significantly improved. Big-endian store and load macros ** * + * ** are obvious targets for optimisation. ** */ + +#ifdef __GNUC__ +# if defined(__has_attribute) && defined(__STDC_VERSION__) +# if __has_attribute(always_inline) && __STDC_VERSION__ >= 199901 +# define MHDX_INLINE inline __attribute__((always_inline)) +# endif +# endif +#endif + +#if !defined(MHDX_INLINE) && \ + defined(_MSC_VER) && !defined(__GNUC__) && !defined(__clang__) +# if _MSC_VER >= 1400 +# define MHDX_INLINE __forceinline +# else +# define MHDX_INLINE /* empty */ +# endif +#endif + +#if !defined(MHDX_INLINE) +# if defined(inline) + /* Assume that 'inline' macro was already defined correctly by + * the build system. */ +# define MHDX_INLINE inline +# elif defined(__cplusplus) + /* The code is compiled with C++ compiler. + * C++ always supports 'inline'. */ +# define MHDX_INLINE inline +# elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901 + /* C99 (and later) supports 'inline' keyword */ +# define MHDX_INLINE inline +# elif defined(__GNUC__) && __GNUC__ >= 3 + /* GCC supports '__inline__' as an extension */ +# define MHDX_INLINE __inline__ +# else +# define MHDX_INLINE /* empty */ +# endif +#endif + +/* Bits manipulation macros and functions. + Can be moved to other headers to reuse. */ + +#define MHDX_GET_64BIT_BE(ptr) \ + ( ((curl_uint64_t)(((const unsigned char*)(ptr))[0]) << 56) | \ + ((curl_uint64_t)(((const unsigned char*)(ptr))[1]) << 48) | \ + ((curl_uint64_t)(((const unsigned char*)(ptr))[2]) << 40) | \ + ((curl_uint64_t)(((const unsigned char*)(ptr))[3]) << 32) | \ + ((curl_uint64_t)(((const unsigned char*)(ptr))[4]) << 24) | \ + ((curl_uint64_t)(((const unsigned char*)(ptr))[5]) << 16) | \ + ((curl_uint64_t)(((const unsigned char*)(ptr))[6]) << 8) | \ + (curl_uint64_t)(((const unsigned char*)(ptr))[7]) ) + +#define MHDX_PUT_64BIT_BE(ptr,val) do { \ + ((unsigned char*)(ptr))[7]=(unsigned char)((curl_uint64_t)(val)); \ + ((unsigned char*)(ptr))[6]=(unsigned char)(((curl_uint64_t)(val)) >> 8); \ + ((unsigned char*)(ptr))[5]=(unsigned char)(((curl_uint64_t)(val)) >> 16); \ + ((unsigned char*)(ptr))[4]=(unsigned char)(((curl_uint64_t)(val)) >> 24); \ + ((unsigned char*)(ptr))[3]=(unsigned char)(((curl_uint64_t)(val)) >> 32); \ + ((unsigned char*)(ptr))[2]=(unsigned char)(((curl_uint64_t)(val)) >> 40); \ + ((unsigned char*)(ptr))[1]=(unsigned char)(((curl_uint64_t)(val)) >> 48); \ + ((unsigned char*)(ptr))[0]=(unsigned char)(((curl_uint64_t)(val)) >> 56); \ +} while(0) + +/* Defined as a function. The macro version may duplicate the binary code + * size as each argument is used twice, so if any calculation is used + * as an argument, the calculation could be done twice. */ +static MHDX_INLINE curl_uint64_t +MHDx_rotr64(curl_uint64_t value, unsigned int bits) +{ + bits %= 64; + if(0 == bits) + return value; + /* Defined in a form which modern compiler could optimise. */ + return (value >> bits) | (value << (64 - bits)); +} + +/* SHA-512/256 specific data */ + +/** + * Number of bits in single SHA-512/256 word. + */ +#define SHA512_256_WORD_SIZE_BITS 64 + +/** + * Number of bytes in single SHA-512/256 word. + */ +#define SHA512_256_BYTES_IN_WORD (SHA512_256_WORD_SIZE_BITS / 8) + +/** + * Hash is kept internally as 8 64-bit words. + * This is intermediate hash size, used during computing the final digest. + */ +#define SHA512_256_HASH_SIZE_WORDS 8 + +/** + * Size of SHA-512/256 resulting digest in bytes. + * This is the final digest size, not intermediate hash. + */ +#define SHA512_256_DIGEST_SIZE_WORDS (SHA512_256_HASH_SIZE_WORDS / 2) + +/** + * Size of SHA-512/256 resulting digest in bytes + * This is the final digest size, not intermediate hash. + */ +#define SHA512_256_DIGEST_SIZE \ + (SHA512_256_DIGEST_SIZE_WORDS * SHA512_256_BYTES_IN_WORD) + +/** + * Size of SHA-512/256 single processing block in bits. + */ +#define SHA512_256_BLOCK_SIZE_BITS 1024 + +/** + * Size of SHA-512/256 single processing block in bytes. + */ +#define SHA512_256_BLOCK_SIZE (SHA512_256_BLOCK_SIZE_BITS / 8) + +/** + * Size of SHA-512/256 single processing block in words. + */ +#define SHA512_256_BLOCK_SIZE_WORDS \ + (SHA512_256_BLOCK_SIZE_BITS / SHA512_256_WORD_SIZE_BITS) + + +/** + * SHA-512/256 calculation context + */ +struct Sha512_256Ctx +{ + /** + * Intermediate hash value + * The variable is properly aligned. Smart compiler + * may automatically use fast load/store instruction + * for big endian data on little endian machine. + */ + curl_uint64_t H[SHA512_256_HASH_SIZE_WORDS]; + /** + * SHA-512/256 input data buffer + * The buffer is properly aligned. Smart compiler + * may automatically use fast load/store instruction + * for big endian data on little endian machine. + */ + curl_uint64_t buffer[SHA512_256_BLOCK_SIZE_WORDS]; + /** + * The number of bytes, lower part + */ + curl_uint64_t count; + /** + * The number of bits, high part. + * Unlike lower part, this counts the number of bits, not bytes. + */ + curl_uint64_t count_bits_hi; +}; + + +/** + * Initialise structure for SHA-512/256 calculation. + * + * @param context the calculation context + * @return always CURLE_OK + */ +static CURLcode +MHDx_sha512_256_init(void *context) +{ + struct Sha512_256Ctx *const ctx = (struct Sha512_256Ctx *) context; + + /* Check whether the header and this file use the same numbers */ + DEBUGASSERT(SHA512_256_DIGEST_LENGTH == SHA512_256_DIGEST_SIZE); + + DEBUGASSERT(sizeof(curl_uint64_t) == 8); + + /* Initial hash values, see FIPS PUB 180-4 section 5.3.6.2 */ + /* Values generated by "IV Generation Function" as described in + * section 5.3.6 */ + ctx->H[0] = CURL_UINT64_C(0x22312194FC2BF72C); + ctx->H[1] = CURL_UINT64_C(0x9F555FA3C84C64C2); + ctx->H[2] = CURL_UINT64_C(0x2393B86B6F53B151); + ctx->H[3] = CURL_UINT64_C(0x963877195940EABD); + ctx->H[4] = CURL_UINT64_C(0x96283EE2A88EFFE3); + ctx->H[5] = CURL_UINT64_C(0xBE5E1E2553863992); + ctx->H[6] = CURL_UINT64_C(0x2B0199FC2C85B8AA); + ctx->H[7] = CURL_UINT64_C(0x0EB72DDC81C52CA2); + + /* Initialise number of bytes and high part of number of bits. */ + ctx->count = CURL_UINT64_C(0); + ctx->count_bits_hi = CURL_UINT64_C(0); + + return CURLE_OK; +} + + +/** + * Base of SHA-512/256 transformation. + * Gets full 128 bytes block of data and updates hash values; + * @param H hash values + * @param data the data buffer with #SHA512_256_BLOCK_SIZE bytes block + */ +static void +MHDx_sha512_256_transform(curl_uint64_t H[SHA512_256_HASH_SIZE_WORDS], + const void *data) +{ + /* Working variables, + see FIPS PUB 180-4 section 6.7, 6.4. */ + curl_uint64_t a = H[0]; + curl_uint64_t b = H[1]; + curl_uint64_t c = H[2]; + curl_uint64_t d = H[3]; + curl_uint64_t e = H[4]; + curl_uint64_t f = H[5]; + curl_uint64_t g = H[6]; + curl_uint64_t h = H[7]; + + /* Data buffer, used as a cyclic buffer. + See FIPS PUB 180-4 section 5.2.2, 6.7, 6.4. */ + curl_uint64_t W[16]; + + /* 'Ch' and 'Maj' macro functions are defined with + widely-used optimisation. + See FIPS PUB 180-4 formulae 4.8, 4.9. */ +#define Ch(x,y,z) ( (z) ^ ((x) & ((y) ^ (z))) ) +#define Maj(x,y,z) ( ((x) & (y)) ^ ((z) & ((x) ^ (y))) ) + /* Unoptimized (original) versions: */ +/* #define Ch(x,y,z) ( ( (x) & (y) ) ^ ( ~(x) & (z) ) ) */ +/* #define Maj(x,y,z) ( ((x) & (y)) ^ ((x) & (z)) ^ ((y) & (z)) ) */ + + /* Four 'Sigma' macro functions. + See FIPS PUB 180-4 formulae 4.10, 4.11, 4.12, 4.13. */ +#define SIG0(x) \ + ( MHDx_rotr64((x), 28) ^ MHDx_rotr64((x), 34) ^ MHDx_rotr64((x), 39) ) +#define SIG1(x) \ + ( MHDx_rotr64((x), 14) ^ MHDx_rotr64((x), 18) ^ MHDx_rotr64((x), 41) ) +#define sig0(x) \ + ( MHDx_rotr64((x), 1) ^ MHDx_rotr64((x), 8) ^ ((x) >> 7) ) +#define sig1(x) \ + ( MHDx_rotr64((x), 19) ^ MHDx_rotr64((x), 61) ^ ((x) >> 6) ) + + if(1) { + unsigned int t; + /* K constants array. + See FIPS PUB 180-4 section 4.2.3 for K values. */ + static const curl_uint64_t K[80] = + { CURL_UINT64_C(0x428a2f98d728ae22), CURL_UINT64_C(0x7137449123ef65cd), + CURL_UINT64_C(0xb5c0fbcfec4d3b2f), CURL_UINT64_C(0xe9b5dba58189dbbc), + CURL_UINT64_C(0x3956c25bf348b538), CURL_UINT64_C(0x59f111f1b605d019), + CURL_UINT64_C(0x923f82a4af194f9b), CURL_UINT64_C(0xab1c5ed5da6d8118), + CURL_UINT64_C(0xd807aa98a3030242), CURL_UINT64_C(0x12835b0145706fbe), + CURL_UINT64_C(0x243185be4ee4b28c), CURL_UINT64_C(0x550c7dc3d5ffb4e2), + CURL_UINT64_C(0x72be5d74f27b896f), CURL_UINT64_C(0x80deb1fe3b1696b1), + CURL_UINT64_C(0x9bdc06a725c71235), CURL_UINT64_C(0xc19bf174cf692694), + CURL_UINT64_C(0xe49b69c19ef14ad2), CURL_UINT64_C(0xefbe4786384f25e3), + CURL_UINT64_C(0x0fc19dc68b8cd5b5), CURL_UINT64_C(0x240ca1cc77ac9c65), + CURL_UINT64_C(0x2de92c6f592b0275), CURL_UINT64_C(0x4a7484aa6ea6e483), + CURL_UINT64_C(0x5cb0a9dcbd41fbd4), CURL_UINT64_C(0x76f988da831153b5), + CURL_UINT64_C(0x983e5152ee66dfab), CURL_UINT64_C(0xa831c66d2db43210), + CURL_UINT64_C(0xb00327c898fb213f), CURL_UINT64_C(0xbf597fc7beef0ee4), + CURL_UINT64_C(0xc6e00bf33da88fc2), CURL_UINT64_C(0xd5a79147930aa725), + CURL_UINT64_C(0x06ca6351e003826f), CURL_UINT64_C(0x142929670a0e6e70), + CURL_UINT64_C(0x27b70a8546d22ffc), CURL_UINT64_C(0x2e1b21385c26c926), + CURL_UINT64_C(0x4d2c6dfc5ac42aed), CURL_UINT64_C(0x53380d139d95b3df), + CURL_UINT64_C(0x650a73548baf63de), CURL_UINT64_C(0x766a0abb3c77b2a8), + CURL_UINT64_C(0x81c2c92e47edaee6), CURL_UINT64_C(0x92722c851482353b), + CURL_UINT64_C(0xa2bfe8a14cf10364), CURL_UINT64_C(0xa81a664bbc423001), + CURL_UINT64_C(0xc24b8b70d0f89791), CURL_UINT64_C(0xc76c51a30654be30), + CURL_UINT64_C(0xd192e819d6ef5218), CURL_UINT64_C(0xd69906245565a910), + CURL_UINT64_C(0xf40e35855771202a), CURL_UINT64_C(0x106aa07032bbd1b8), + CURL_UINT64_C(0x19a4c116b8d2d0c8), CURL_UINT64_C(0x1e376c085141ab53), + CURL_UINT64_C(0x2748774cdf8eeb99), CURL_UINT64_C(0x34b0bcb5e19b48a8), + CURL_UINT64_C(0x391c0cb3c5c95a63), CURL_UINT64_C(0x4ed8aa4ae3418acb), + CURL_UINT64_C(0x5b9cca4f7763e373), CURL_UINT64_C(0x682e6ff3d6b2b8a3), + CURL_UINT64_C(0x748f82ee5defb2fc), CURL_UINT64_C(0x78a5636f43172f60), + CURL_UINT64_C(0x84c87814a1f0ab72), CURL_UINT64_C(0x8cc702081a6439ec), + CURL_UINT64_C(0x90befffa23631e28), CURL_UINT64_C(0xa4506cebde82bde9), + CURL_UINT64_C(0xbef9a3f7b2c67915), CURL_UINT64_C(0xc67178f2e372532b), + CURL_UINT64_C(0xca273eceea26619c), CURL_UINT64_C(0xd186b8c721c0c207), + CURL_UINT64_C(0xeada7dd6cde0eb1e), CURL_UINT64_C(0xf57d4f7fee6ed178), + CURL_UINT64_C(0x06f067aa72176fba), CURL_UINT64_C(0x0a637dc5a2c898a6), + CURL_UINT64_C(0x113f9804bef90dae), CURL_UINT64_C(0x1b710b35131c471b), + CURL_UINT64_C(0x28db77f523047d84), CURL_UINT64_C(0x32caab7b40c72493), + CURL_UINT64_C(0x3c9ebe0a15c9bebc), CURL_UINT64_C(0x431d67c49c100d4c), + CURL_UINT64_C(0x4cc5d4becb3e42b6), CURL_UINT64_C(0x597f299cfc657e2a), + CURL_UINT64_C(0x5fcb6fab3ad6faec), CURL_UINT64_C(0x6c44198c4a475817)}; + + /* One step of SHA-512/256 computation, + see FIPS PUB 180-4 section 6.4.2 step 3. + * Note: this macro updates working variables in-place, without rotation. + * Note: the first (vH += SIG1(vE) + Ch(vE,vF,vG) + kt + wt) equals T1 in + FIPS PUB 180-4 section 6.4.2 step 3. + the second (vH += SIG0(vA) + Maj(vE,vF,vC) equals T1 + T2 in + FIPS PUB 180-4 section 6.4.2 step 3. + * Note: 'wt' must be used exactly one time in this macro as macro for + 'wt' calculation may change other data as well every time when + used. */ +#define SHA2STEP64(vA,vB,vC,vD,vE,vF,vG,vH,kt,wt) do { \ + (vD) += ((vH) += SIG1 ((vE)) + Ch ((vE),(vF),(vG)) + (kt) + (wt)); \ + (vH) += SIG0 ((vA)) + Maj ((vA),(vB),(vC)); } while (0) + + /* One step of SHA-512/256 computation with working variables rotation, + see FIPS PUB 180-4 section 6.4.2 step 3. + * Note: this version of macro reassign all working variable on + each step. */ +#define SHA2STEP64RV(vA,vB,vC,vD,vE,vF,vG,vH,kt,wt) do { \ + curl_uint64_t tmp_h_ = (vH); \ + SHA2STEP64((vA),(vB),(vC),(vD),(vE),(vF),(vG),tmp_h_,(kt),(wt)); \ + (vH) = (vG); \ + (vG) = (vF); \ + (vF) = (vE); \ + (vE) = (vD); \ + (vD) = (vC); \ + (vC) = (vB); \ + (vB) = (vA); \ + (vA) = tmp_h_; } while(0) + + /* Get value of W(t) from input data buffer for 0 <= t <= 15, + See FIPS PUB 180-4 section 6.2. + Input data must be read in big-endian bytes order, + see FIPS PUB 180-4 section 3.1.2. */ +#define SHA512_GET_W_FROM_DATA(buf,t) \ + MHDX_GET_64BIT_BE( \ + ((const unsigned char*) (buf)) + (t) * SHA512_256_BYTES_IN_WORD) + + /* During first 16 steps, before making any calculations on each step, + the W element is read from the input data buffer as big-endian value and + stored in the array of W elements. */ + for(t = 0; t < 16; ++t) { + SHA2STEP64RV(a, b, c, d, e, f, g, h, K[t], \ + W[t] = SHA512_GET_W_FROM_DATA(data, t)); + } + + /* 'W' generation and assignment for 16 <= t <= 79. + See FIPS PUB 180-4 section 6.4.2. + As only last 16 'W' are used in calculations, it is possible to + use 16 elements array of W as a cyclic buffer. + * Note: ((t-16) & 15) have same value as (t & 15) */ +#define Wgen(w,t) \ + CURL_UINT64_CAST( (w)[(t - 16) & 15] + sig1((w)[((t) - 2) & 15]) \ + + (w)[((t) - 7) & 15] + sig0((w)[((t) - 15) & 15]) ) + + /* During last 64 steps, before making any calculations on each step, + current W element is generated from other W elements of the cyclic + buffer and the generated value is stored back in the cyclic buffer. */ + for(t = 16; t < 80; ++t) { + SHA2STEP64RV(a, b, c, d, e, f, g, h, K[t], \ + W[t & 15] = Wgen(W, t)); + } + } + + /* Compute and store the intermediate hash. + See FIPS PUB 180-4 section 6.4.2 step 4. */ + H[0] += a; + H[1] += b; + H[2] += c; + H[3] += d; + H[4] += e; + H[5] += f; + H[6] += g; + H[7] += h; +} + + +/** + * Process portion of bytes. + * + * @param context the calculation context + * @param data bytes to add to hash + * @param length number of bytes in @a data + */ +static void +MHDx_sha512_256_update(void *context, + const unsigned char *data, + unsigned int length) +{ + unsigned int bytes_have; /**< Number of bytes in the context buffer */ + struct Sha512_256Ctx *const ctx = (struct Sha512_256Ctx *) context; + /* Required to mute Intel compiler warning */ + void *const ctx_buf = ctx->buffer; + + DEBUGASSERT((data != NULL) || (length == 0)); + + if(0 == length) + return; /* Shortcut, do nothing */ + + /* Note: (count & (SHA512_256_BLOCK_SIZE-1)) + equals (count % SHA512_256_BLOCK_SIZE) for this block size. */ + bytes_have = (unsigned int) (ctx->count & (SHA512_256_BLOCK_SIZE - 1)); + ctx->count += length; + if(CURL_UINT64_CAST(length) > ctx->count) + ctx->count_bits_hi += 1U << 3; /* Value wrap */ + ctx->count_bits_hi += ctx->count >> 61; + ctx->count &= CURL_UINT64_C(0x1FFFFFFFFFFFFFFF); + + if(0 != bytes_have) { + unsigned int bytes_left = SHA512_256_BLOCK_SIZE - bytes_have; + if(length >= bytes_left) { + /* Combine new data with data in the buffer and + process the full block. */ + memcpy(((unsigned char *) ctx_buf) + bytes_have, + data, + bytes_left); + data += bytes_left; + length -= bytes_left; + MHDx_sha512_256_transform(ctx->H, ctx->buffer); + bytes_have = 0; + } + } + + while(SHA512_256_BLOCK_SIZE <= length) { + /* Process any full blocks of new data directly, + without copying to the buffer. */ + MHDx_sha512_256_transform(ctx->H, data); + data += SHA512_256_BLOCK_SIZE; + length -= SHA512_256_BLOCK_SIZE; + } + + if(0 != length) { + /* Copy incomplete block of new data (if any) + to the buffer. */ + memcpy(((unsigned char *) ctx_buf) + bytes_have, data, length); + } +} + + + +/** + * Size of "length" insertion in bits. + * See FIPS PUB 180-4 section 5.1.2. + */ +#define SHA512_256_SIZE_OF_LEN_ADD_BITS 128 + +/** + * Size of "length" insertion in bytes. + */ +#define SHA512_256_SIZE_OF_LEN_ADD (SHA512_256_SIZE_OF_LEN_ADD_BITS / 8) + +/** + * Finalise SHA-512/256 calculation, return digest. + * + * @param context the calculation context + * @param[out] digest set to the hash, must be #SHA512_256_DIGEST_SIZE bytes + */ +static void +MHDx_sha512_256_finish(unsigned char *digest, + void *context) +{ + struct Sha512_256Ctx *const ctx = (struct Sha512_256Ctx *) context; + curl_uint64_t num_bits; /**< Number of processed bits */ + unsigned int bytes_have; /**< Number of bytes in the context buffer */ + /* Required to mute Intel compiler warning */ + void *const ctx_buf = ctx->buffer; + + + /* Memorise the number of processed bits. + The padding and other data added here during the postprocessing must + not change the amount of hashed data. */ + num_bits = ctx->count << 3; + + /* Note: (count & (SHA512_256_BLOCK_SIZE-1)) + equals (count % SHA512_256_BLOCK_SIZE) for this block size. */ + bytes_have = (unsigned int) (ctx->count & (SHA512_256_BLOCK_SIZE - 1)); + + /* Input data must be padded with a single bit "1", then with zeros and + the finally the length of data in bits must be added as the final bytes + of the last block. + See FIPS PUB 180-4 section 5.1.2. */ + + /* Data is always processed in form of bytes (not by individual bits), + therefore position of the first padding bit in byte is always + predefined (0x80). */ + /* Buffer always have space at least for one byte (as full buffers are + processed when formed). */ + ((unsigned char *) ctx_buf)[bytes_have++] = 0x80U; + + if(SHA512_256_BLOCK_SIZE - bytes_have < SHA512_256_SIZE_OF_LEN_ADD) { + /* No space in the current block to put the total length of message. + Pad the current block with zeros and process it. */ + if(bytes_have < SHA512_256_BLOCK_SIZE) + memset(((unsigned char *) ctx_buf) + bytes_have, 0, + SHA512_256_BLOCK_SIZE - bytes_have); + /* Process the full block. */ + MHDx_sha512_256_transform(ctx->H, ctx->buffer); + /* Start the new block. */ + bytes_have = 0; + } + + /* Pad the rest of the buffer with zeros. */ + memset(((unsigned char *) ctx_buf) + bytes_have, 0, + SHA512_256_BLOCK_SIZE - SHA512_256_SIZE_OF_LEN_ADD - bytes_have); + /* Put high part of number of bits in processed message and then lower + part of number of bits as big-endian values. + See FIPS PUB 180-4 section 5.1.2. */ + /* Note: the target location is predefined and buffer is always aligned */ + MHDX_PUT_64BIT_BE(((unsigned char *) ctx_buf) \ + + SHA512_256_BLOCK_SIZE \ + - SHA512_256_SIZE_OF_LEN_ADD, \ + ctx->count_bits_hi); + MHDX_PUT_64BIT_BE(((unsigned char *) ctx_buf) \ + + SHA512_256_BLOCK_SIZE \ + - SHA512_256_SIZE_OF_LEN_ADD \ + + SHA512_256_BYTES_IN_WORD, \ + num_bits); + /* Process the full final block. */ + MHDx_sha512_256_transform(ctx->H, ctx->buffer); + + /* Put in BE mode the leftmost part of the hash as the final digest. + See FIPS PUB 180-4 section 6.7. */ + + MHDX_PUT_64BIT_BE((digest + 0 * SHA512_256_BYTES_IN_WORD), ctx->H[0]); + MHDX_PUT_64BIT_BE((digest + 1 * SHA512_256_BYTES_IN_WORD), ctx->H[1]); + MHDX_PUT_64BIT_BE((digest + 2 * SHA512_256_BYTES_IN_WORD), ctx->H[2]); + MHDX_PUT_64BIT_BE((digest + 3 * SHA512_256_BYTES_IN_WORD), ctx->H[3]); + + /* Erase potentially sensitive data. */ + memset(ctx, 0, sizeof(struct Sha512_256Ctx)); +} + + +/** + * Compute SHA-512/256 hash for the given data in one function call + * @param[out] output the pointer to put the hash + * @param[in] input the pointer to the data to process + * @param input_size the size of the data pointed by @a input + * @return always #CURLE_OK + */ +CURLcode +Curl_sha512_256it(unsigned char *output, const unsigned char *input, + size_t input_size) +{ + struct Sha512_256Ctx ctx; + static const unsigned int max_step_size = (unsigned int)(-1); + + (void) MHDx_sha512_256_init(&ctx); /* Always succeed */ + + while(input_size >= max_step_size) { + MHDx_sha512_256_update(&ctx, (const void *) input, max_step_size); + input += max_step_size; + input_size -= max_step_size; + } + MHDx_sha512_256_update(&ctx, (const void *) input, + curlx_uztoui(input_size)); + + MHDx_sha512_256_finish(output, &ctx); + + return CURLE_OK; +} + + +const struct HMAC_params Curl_HMAC_SHA512_256[] = { + { + /* Initialize context procedure. */ + MHDx_sha512_256_init, + /* Update context with data. */ + MHDx_sha512_256_update, + /* Get final result procedure. */ + MHDx_sha512_256_finish, + /* Context structure size. */ + sizeof(struct Sha512_256Ctx), + /* Maximum key length (bytes). */ + SHA512_256_BLOCK_SIZE, + /* Result length (bytes). */ + SHA512_256_DIGEST_SIZE + } +}; + + +#endif /* !CURL_DISABLE_DIGEST_AUTH && !CURL_DISABLE_SHA512_256 */ diff --git a/lib/curl_sha512_256.h b/lib/curl_sha512_256.h new file mode 100644 index 00000000000..30a9f140ea7 --- /dev/null +++ b/lib/curl_sha512_256.h @@ -0,0 +1,44 @@ +#ifndef HEADER_CURL_SHA512_256_H +#define HEADER_CURL_SHA512_256_H +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) Evgeny Grin (Karlson2k), . + * + * 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 + * + ***************************************************************************/ + +#if !defined(CURL_DISABLE_DIGEST_AUTH) && !defined(CURL_DISABLE_SHA512_256) + +#include +#include "curl_hmac.h" + +#define CURL_HAVE_SHA512_256 + +extern const struct HMAC_params Curl_HMAC_SHA512_256[1]; + +#define SHA512_256_DIGEST_LENGTH 32 + +CURLcode +Curl_sha512_256it(unsigned char *output, const unsigned char *input, + size_t input_size); + +#endif /* !CURL_DISABLE_DIGEST_AUTH && !CURL_DISABLE_SHA512_256 */ + +#endif /* HEADER_CURL_SHA256_H */ diff --git a/tests/test1165.pl b/tests/test1165.pl index bccbef9366c..4045ef59b44 100755 --- a/tests/test1165.pl +++ b/tests/test1165.pl @@ -87,7 +87,9 @@ sub scan_file { while() { while(s/(CURL_DISABLE_[A-Z0-9_]+)//) { my ($sym)=($1); - $file{$sym} = $source; + if(not $sym =~ /^(CURL_DISABLE_SHA512_256)/) { # Skip this symbol, to be implemented + $file{$sym} = $source; + } } } close F; From 6d6113e122514f8ca3869a04177456e78bbe6666 Mon Sep 17 00:00:00 2001 From: Evgeny Grin Date: Wed, 7 Feb 2024 23:07:07 +0100 Subject: [PATCH 346/509] tests: add SHA-512/256 unit test --- tests/data/Makefile.inc | 2 +- tests/data/test1615 | 23 ++++++ tests/runtests.pl | 1 + tests/server/disabled.c | 4 + tests/unit/Makefile.inc | 4 +- tests/unit/unit1615.c | 159 ++++++++++++++++++++++++++++++++++++++++ 6 files changed, 191 insertions(+), 2 deletions(-) create mode 100644 tests/data/test1615 create mode 100644 tests/unit/unit1615.c diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 1475cc3b95e..546e4ad482d 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -203,7 +203,7 @@ test1566 test1567 test1568 test1569 test1570 \ test1590 test1591 test1592 test1593 test1594 test1595 test1596 test1597 \ \ test1600 test1601 test1602 test1603 test1604 test1605 test1606 test1607 \ -test1608 test1609 test1610 test1611 test1612 test1613 test1614 \ +test1608 test1609 test1610 test1611 test1612 test1613 test1614 test1615 \ \ test1620 test1621 \ \ diff --git a/tests/data/test1615 b/tests/data/test1615 new file mode 100644 index 00000000000..8eb06792e75 --- /dev/null +++ b/tests/data/test1615 @@ -0,0 +1,23 @@ + + + +unittest +SHA-512/256 + + + +# +# Client-side + + +none + + +unittest +sha512-256 + + +SHA-512/256 unit tests + + + diff --git a/tests/runtests.pl b/tests/runtests.pl index 17b0d3986c0..ddfab20e861 100755 --- a/tests/runtests.pl +++ b/tests/runtests.pl @@ -796,6 +796,7 @@ sub checksystemfeatures { $feature{"headers-api"} = 1; $feature{"xattr"} = 1; $feature{"large-time"} = 1; + $feature{"sha512-256"} = 1; # make each protocol an enabled "feature" for my $p (@protocols) { diff --git a/tests/server/disabled.c b/tests/server/disabled.c index 0b84134fc2d..fe500137d49 100644 --- a/tests/server/disabled.c +++ b/tests/server/disabled.c @@ -34,6 +34,7 @@ #include "curl_setup.h" #include "multihandle.h" /* for ENABLE_WAKEUP */ #include "tool_xattr.h" /* for USE_XATTR */ +#include "curl_sha512_256.h" /* for CURL_HAVE_SHA512_256 */ #include static const char *disabled[]={ @@ -99,6 +100,9 @@ static const char *disabled[]={ #endif #if (SIZEOF_TIME_T < 5) "large-time", +#endif +#ifndef CURL_HAVE_SHA512_256 + "sha512-256", #endif NULL }; diff --git a/tests/unit/Makefile.inc b/tests/unit/Makefile.inc index 36e922b2a20..3f63047f535 100644 --- a/tests/unit/Makefile.inc +++ b/tests/unit/Makefile.inc @@ -34,7 +34,7 @@ UNITPROGS = unit1300 unit1302 unit1303 unit1304 unit1305 unit1307 \ unit1330 unit1394 unit1395 unit1396 unit1397 unit1398 \ unit1399 \ unit1600 unit1601 unit1602 unit1603 unit1604 unit1605 unit1606 unit1607 \ - unit1608 unit1609 unit1610 unit1611 unit1612 unit1614 \ + unit1608 unit1609 unit1610 unit1611 unit1612 unit1614 unit1615 \ unit1620 unit1621 \ unit1650 unit1651 unit1652 unit1653 unit1654 unit1655 \ unit1660 unit1661 \ @@ -101,6 +101,8 @@ unit1612_SOURCES = unit1612.c $(UNITFILES) unit1614_SOURCES = unit1614.c $(UNITFILES) +unit1615_SOURCES = unit1615.c $(UNITFILES) + unit1620_SOURCES = unit1620.c $(UNITFILES) unit1621_SOURCES = unit1621.c $(UNITFILES) diff --git a/tests/unit/unit1615.c b/tests/unit/unit1615.c new file mode 100644 index 00000000000..444985b2a9c --- /dev/null +++ b/tests/unit/unit1615.c @@ -0,0 +1,159 @@ +/*************************************************************************** + * _ _ ____ _ + * Project ___| | | | _ \| | + * / __| | | | |_) | | + * | (__| |_| | _ <| |___ + * \___|\___/|_| \_\_____| + * + * Copyright (C) Daniel Stenberg, , et al. + * Copyright (C) Evgeny Grin (Karlson2k), . + * + * 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 "curlcheck.h" + +#include "curl_sha512_256.h" + +static CURLcode unit_setup(void) +{ + return CURLE_OK; +} + +static void unit_stop(void) +{ + +} + +UNITTEST_START + +#ifdef CURL_HAVE_SHA512_256 + + static const char test_str1[] = "1"; + static const unsigned char precomp_hash1[SHA512_256_DIGEST_LENGTH] = { + 0x18, 0xd2, 0x75, 0x66, 0xbd, 0x1a, 0xc6, 0x6b, 0x23, 0x32, 0xd8, + 0xc5, 0x4a, 0xd4, 0x3f, 0x7b, 0xb2, 0x20, 0x79, 0xc9, 0x06, 0xd0, + 0x5f, 0x49, 0x1f, 0x3f, 0x07, 0xa2, 0x8d, 0x5c, 0x69, 0x90 + }; + static const char test_str2[] = "hello-you-fool"; + static const unsigned char precomp_hash2[SHA512_256_DIGEST_LENGTH] = { + 0xaf, 0x6f, 0xb4, 0xb0, 0x13, 0x9b, 0xee, 0x13, 0xd1, 0x95, 0x3c, + 0xb8, 0xc7, 0xcd, 0x5b, 0x19, 0xf9, 0xcd, 0xcd, 0x21, 0xef, 0xdf, + 0xa7, 0x42, 0x5c, 0x07, 0x13, 0xea, 0xcc, 0x1a, 0x39, 0x76 + }; + static const char test_str3[] = "abc"; + static const unsigned char precomp_hash3[SHA512_256_DIGEST_LENGTH] = { + 0x53, 0x04, 0x8E, 0x26, 0x81, 0x94, 0x1E, 0xF9, 0x9B, 0x2E, 0x29, + 0xB7, 0x6B, 0x4C, 0x7D, 0xAB, 0xE4, 0xC2, 0xD0, 0xC6, 0x34, 0xFC, + 0x6D, 0x46, 0xE0, 0xE2, 0xF1, 0x31, 0x07, 0xE7, 0xAF, 0x23 + }; + static const char test_str4[] = ""; /* empty, zero size input */ + static const unsigned char precomp_hash4[SHA512_256_DIGEST_LENGTH] = { + 0xc6, 0x72, 0xb8, 0xd1, 0xef, 0x56, 0xed, 0x28, 0xab, 0x87, 0xc3, + 0x62, 0x2c, 0x51, 0x14, 0x06, 0x9b, 0xdd, 0x3a, 0xd7, 0xb8, 0xf9, + 0x73, 0x74, 0x98, 0xd0, 0xc0, 0x1e, 0xce, 0xf0, 0x96, 0x7a + }; + static const char test_str5[] = + "abcdefghijklmnopqrstuvwxyzzyxwvutsrqponMLKJIHGFEDCBA" \ + "abcdefghijklmnopqrstuvwxyzzyxwvutsrqponMLKJIHGFEDCBA"; + static const unsigned char precomp_hash5[SHA512_256_DIGEST_LENGTH] = { + 0xad, 0xe9, 0x5d, 0x55, 0x3b, 0x9e, 0x45, 0x69, 0xdb, 0x53, 0xa4, + 0x04, 0x92, 0xe7, 0x87, 0x94, 0xff, 0xc9, 0x98, 0x5f, 0x93, 0x03, + 0x86, 0x45, 0xe1, 0x97, 0x17, 0x72, 0x7c, 0xbc, 0x31, 0x15 + }; + static const char test_str6[] = + "/long/long/long/long/long/long/long/long/long/long/long" \ + "/long/long/long/long/long/long/long/long/long/long/long" \ + "/long/long/long/long/long/long/long/long/long/long/long" \ + "/long/long/long/long/long/long/long/long/long/long/long" \ + "/long/long/long/long/long/long/long/long/long/long/long" \ + "/long/long/long/long/long/long/long/long/long/long/long" \ + "/long/long/long/long/path?with%20some=parameters"; + static const unsigned char precomp_hash6[SHA512_256_DIGEST_LENGTH] = { + 0xbc, 0xab, 0xc6, 0x2c, 0x0a, 0x22, 0xd5, 0xcb, 0xac, 0xac, 0xe9, + 0x25, 0xcf, 0xce, 0xaa, 0xaf, 0x0e, 0xa1, 0xed, 0x42, 0x46, 0x8a, + 0xe2, 0x01, 0xee, 0x2f, 0xdb, 0x39, 0x75, 0x47, 0x73, 0xf1 + }; + static const char test_str7[] = "Simple string."; + static const unsigned char precomp_hash7[SHA512_256_DIGEST_LENGTH] = { + 0xde, 0xcb, 0x3c, 0x81, 0x65, 0x4b, 0xa0, 0xf5, 0xf0, 0x45, 0x6b, + 0x7e, 0x61, 0xf5, 0x0d, 0xf5, 0x38, 0xa4, 0xfc, 0xb1, 0x8a, 0x95, + 0xff, 0x59, 0xbc, 0x04, 0x82, 0xcf, 0x23, 0xb2, 0x32, 0x56 + }; + static const unsigned char test_seq8[]= { + 255, 254, 253, 252, 251, 250, 249, 248, 247, 246, 245, 244, 243, 242, + 241, 240, 239, 238, 237, 236, 235, 234, 233, 232, 231, 230, 229, 228, + 227, 226, 225, 224, 223, 222, 221, 220, 219, 218, 217, 216, 215, 214, + 213, 212, 211, 210, 209, 208, 207, 206, 205, 204, 203, 202, 201, 200, + 199, 198, 197, 196, 195, 194, 193, 192, 191, 190, 189, 188, 187, 186, + 185, 184, 183, 182, 181, 180, 179, 178, 177, 176, 175, 174, 173, 172, + 171, 170, 169, 168, 167, 166, 165, 164, 163, 162, 161, 160, 159, 158, + 157, 156, 155, 154, 153, 152, 151, 150, 149, 148, 147, 146, 145, 144, + 143, 142, 141, 140, 139, 138, 137, 136, 135, 134, 133, 132, 131, 130, + 129, 128, 127, 126, 125, 124, 123, 122, 121, 120, 119, 118, 117, 116, + 115, 114, 113, 112, 111, 110, 109, 108, 107, 106, 105, 104, 103, 102, + 101, 100, 99, 98, 97, 96, 95, 94, 93, 92, 91, 90, 89, 88, 87, 86, 85, + 84, 83, 82, 81, 80, 79, 78, 77, 76, 75, 74, 73, 72, 71, 70, 69, 68, 67, + 66, 65, 64, 63, 62, 61, 60, 59, 58, 57, 56, 55, 54, 53, 52, 51, 50, 49, + 48, 47, 46, 45, 44, 43, 42, 41, 40, 39, 38, 37, 36, 35, 34, 33, 32, 31, + 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, + 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1}; /* 255..1 sequence */ + static const unsigned char precomp_hash8[SHA512_256_DIGEST_LENGTH] = { + 0x22, 0x31, 0xf2, 0xa1, 0xb4, 0x89, 0xb2, 0x44, 0xf7, 0x66, 0xa0, + 0xb8, 0x31, 0xed, 0xb7, 0x73, 0x8a, 0x34, 0xdc, 0x11, 0xc8, 0x2c, + 0xf2, 0xb5, 0x88, 0x60, 0x39, 0x6b, 0x5c, 0x06, 0x70, 0x37 + }; + + unsigned char output_buf[SHA512_256_DIGEST_LENGTH]; + unsigned char *computed_hash; /* Just to mute compiler warning */ + + /* Mute compiler warnings in 'verify_memory' macros below */ + computed_hash = output_buf; + + Curl_sha512_256it(output_buf, (const unsigned char *) test_str1, + (sizeof(test_str1) / sizeof(char)) - 1); + verify_memory(computed_hash, precomp_hash1, SHA512_256_DIGEST_LENGTH); + + Curl_sha512_256it(output_buf, (const unsigned char *) test_str2, + (sizeof(test_str2) / sizeof(char)) - 1); + verify_memory(computed_hash, precomp_hash2, SHA512_256_DIGEST_LENGTH); + + Curl_sha512_256it(output_buf, (const unsigned char *) test_str3, + (sizeof(test_str3) / sizeof(char)) - 1); + verify_memory(computed_hash, precomp_hash3, SHA512_256_DIGEST_LENGTH); + + Curl_sha512_256it(output_buf, (const unsigned char *) test_str4, + (sizeof(test_str4) / sizeof(char)) - 1); + verify_memory(computed_hash, precomp_hash4, SHA512_256_DIGEST_LENGTH); + + Curl_sha512_256it(output_buf, (const unsigned char *) test_str5, + (sizeof(test_str5) / sizeof(char)) - 1); + verify_memory(computed_hash, precomp_hash5, SHA512_256_DIGEST_LENGTH); + + Curl_sha512_256it(output_buf, (const unsigned char *) test_str6, + (sizeof(test_str6) / sizeof(char)) - 1); + verify_memory(computed_hash, precomp_hash6, SHA512_256_DIGEST_LENGTH); + + Curl_sha512_256it(output_buf, (const unsigned char *) test_str7, + (sizeof(test_str7) / sizeof(char)) - 1); + verify_memory(computed_hash, precomp_hash7, SHA512_256_DIGEST_LENGTH); + + Curl_sha512_256it(output_buf, test_seq8, + sizeof(test_seq8) / sizeof(unsigned char)); + verify_memory(computed_hash, precomp_hash8, SHA512_256_DIGEST_LENGTH); + +#endif /* CURL_HAVE_SHA512_256 */ + + +UNITTEST_STOP From e3461bbd0599547740651279daec0861ade63ff0 Mon Sep 17 00:00:00 2001 From: Evgeny Grin Date: Thu, 8 Feb 2024 10:31:12 +0100 Subject: [PATCH 347/509] digest: support SHA-512/256 Also fix the tests. New implementation tested with GNU libmicrohttpd. The new numbers in tests are real SHA-512/256 numbers (not just some random ;) numbers ). --- lib/vauth/digest.c | 41 ++++++++++++++++++++++++++++++++--------- tests/data/test2060 | 3 ++- tests/data/test2062 | 3 ++- tests/data/test2065 | 3 ++- tests/data/test2068 | 3 ++- 5 files changed, 40 insertions(+), 13 deletions(-) diff --git a/lib/vauth/digest.c b/lib/vauth/digest.c index 416da0fcc73..417ee111f9c 100644 --- a/lib/vauth/digest.c +++ b/lib/vauth/digest.c @@ -38,6 +38,7 @@ #include "curl_hmac.h" #include "curl_md5.h" #include "curl_sha256.h" +#include "curl_sha512_256.h" #include "vtls/vtls.h" #include "warnless.h" #include "strtok.h" @@ -150,7 +151,7 @@ static void auth_digest_md5_to_ascii(unsigned char *source, /* 16 bytes */ msnprintf((char *) &dest[i * 2], 3, "%02x", source[i]); } -/* Convert sha256 chunk to RFC7616 -suitable ascii string */ +/* Convert sha256 or SHA-512/256 chunk to RFC7616 -suitable ascii string */ static void auth_digest_sha256_to_ascii(unsigned char *source, /* 32 bytes */ unsigned char *dest) /* 65 bytes */ { @@ -601,10 +602,20 @@ CURLcode Curl_auth_decode_digest_http_message(const char *chlg, digest->algo = ALGO_SHA256; else if(strcasecompare(content, "SHA-256-SESS")) digest->algo = ALGO_SHA256SESS; - else if(strcasecompare(content, "SHA-512-256")) + else if(strcasecompare(content, "SHA-512-256")) { +#ifdef CURL_HAVE_SHA512_256 digest->algo = ALGO_SHA512_256; - else if(strcasecompare(content, "SHA-512-256-SESS")) +#else /* ! CURL_HAVE_SHA512_256 */ + return CURLE_NOT_BUILT_IN; +#endif /* ! CURL_HAVE_SHA512_256 */ + } + else if(strcasecompare(content, "SHA-512-256-SESS")) { +#ifdef CURL_HAVE_SHA512_256 digest->algo = ALGO_SHA512_256SESS; +#else /* ! CURL_HAVE_SHA512_256 */ + return CURLE_NOT_BUILT_IN; +#endif /* ! CURL_HAVE_SHA512_256 */ + } else return CURLE_BAD_CONTENT_ENCODING; } @@ -957,12 +968,24 @@ CURLcode Curl_auth_create_digest_http_message(struct Curl_easy *data, outptr, outlen, auth_digest_md5_to_ascii, Curl_md5it); - DEBUGASSERT(digest->algo <= ALGO_SHA512_256SESS); - return auth_create_digest_http_message(data, userp, passwdp, - request, uripath, digest, - outptr, outlen, - auth_digest_sha256_to_ascii, - Curl_sha256it); + + if(digest->algo <= ALGO_SHA256SESS) + return auth_create_digest_http_message(data, userp, passwdp, + request, uripath, digest, + outptr, outlen, + auth_digest_sha256_to_ascii, + Curl_sha256it); +#ifdef CURL_HAVE_SHA512_256 + if(digest->algo <= ALGO_SHA512_256SESS) + return auth_create_digest_http_message(data, userp, passwdp, + request, uripath, digest, + outptr, outlen, + auth_digest_sha256_to_ascii, + Curl_sha512_256it); +#endif /* CURL_HAVE_SHA512_256 */ + + /* Should be unreachable */ + return CURLE_BAD_CONTENT_ENCODING; } /* diff --git a/tests/data/test2060 b/tests/data/test2060 index dc4223ec618..e1632a387d6 100644 --- a/tests/data/test2060 +++ b/tests/data/test2060 @@ -67,6 +67,7 @@ http !SSPI crypto proxy +sha512-256 HTTP POST --digest with PUT, resumed upload, modified method, SHA-512-256 and userhash=false @@ -92,7 +93,7 @@ Content-Length: 0 GET http://%HOSTIP:%HTTPPORT/%TESTNUMBER HTTP/1.1 Host: %HOSTIP:%HTTPPORT -Authorization: Digest username="auser", realm="testrealm", nonce="1053604144", uri="/%TESTNUMBER", response="3ce1e25ffa611bdbe90e2ab367b9602fa223db9f6de76ac667f0d6157e2178a6", algorithm=SHA-512-256 +Authorization: Digest username="auser", realm="testrealm", nonce="1053604144", uri="/%TESTNUMBER", response="691867f4a06c79fd0a175c1857e3df7015f6fff3ce8676497d2f1f805b5a8eca", algorithm=SHA-512-256 Content-Range: bytes 2-4/5 User-Agent: curl/%VERSION Accept: */* diff --git a/tests/data/test2062 b/tests/data/test2062 index b6a1e01f934..039354382da 100644 --- a/tests/data/test2062 +++ b/tests/data/test2062 @@ -54,6 +54,7 @@ http !SSPI crypto +sha512-256 HTTP with RFC7616 SHA-512-256 Digest authorization and userhash=false @@ -73,7 +74,7 @@ Accept: */* GET /%TESTNUMBER HTTP/1.1 Host: %HOSTIP:%HTTPPORT -Authorization: Digest username="testuser", realm="testrealm", nonce="1053604145", uri="/%TESTNUMBER", response="2af735ec3508f4dff99248ffbbe9de9002bfd7cc770cfa2b026cb334042a54e3", algorithm=SHA-512-256 +Authorization: Digest username="testuser", realm="testrealm", nonce="1053604145", uri="/%TESTNUMBER", response="9d3256ee6526ec40dd48743bb48e51ee9baba587c78f15c3a86166242150af98", algorithm=SHA-512-256 User-Agent: curl/%VERSION Accept: */* diff --git a/tests/data/test2065 b/tests/data/test2065 index 0b794302df6..4f3a510744c 100644 --- a/tests/data/test2065 +++ b/tests/data/test2065 @@ -54,6 +54,7 @@ http !SSPI crypto +sha512-256 HTTP with RFC7616 Digest authorization with bad password, SHA-512-256 and userhash=false @@ -73,7 +74,7 @@ Accept: */* GET /%TESTNUMBER HTTP/1.1 Host: %HOSTIP:%HTTPPORT -Authorization: Digest username="testuser", realm="testrealm", nonce="2053604145", uri="/%TESTNUMBER", response="5a5f20b0e601aeddc6f96422c2332d49ff431c49ab143b5f836ef76e9ac78f5e", algorithm=SHA-512-256 +Authorization: Digest username="testuser", realm="testrealm", nonce="2053604145", uri="/%TESTNUMBER", response="0373a49d7d352ff54884faaf762fc6c89281b4112ad8fcbbe1d1ee52dcf7a802", algorithm=SHA-512-256 User-Agent: curl/%VERSION Accept: */* diff --git a/tests/data/test2068 b/tests/data/test2068 index 429e5d56605..32afd26290a 100644 --- a/tests/data/test2068 +++ b/tests/data/test2068 @@ -52,6 +52,7 @@ http !SSPI crypto +sha512-256 HTTP POST --digest with SHA-512-256, userhash=false and user-specified Content-Length header @@ -76,7 +77,7 @@ Content-Type: application/x-www-form-urlencoded POST /%TESTNUMBER HTTP/1.1 Host: %HOSTIP:%HTTPPORT -Authorization: Digest username="auser", realm="testrealm", nonce="1053604144", uri="/%TESTNUMBER", response="4bc9c97a72f1856bcec9b0e1518c6b7ee28773f91357d56840bdc30bd89ca68f", algorithm=SHA-512-256 +Authorization: Digest username="auser", realm="testrealm", nonce="1053604144", uri="/%TESTNUMBER", response="0ba2f7ec8045446588eea82bb0c3812aedb05f4eac8883ea65040a52e9c5629e", algorithm=SHA-512-256 User-Agent: curl/%VERSION Accept: */* Content-Length: 11 From f0c446ab577e1452cd53f0c509720f697b1076f7 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 15 Feb 2024 16:39:40 +0100 Subject: [PATCH 348/509] websocket: fix curl_ws_recv() - when data arrived in several chunks, the collection into the passed buffer always started at offset 0, overwriting the data already there. adding test_20_07 to verify fix - debug environment var CURL_WS_CHUNK_SIZE can be used to influence the buffer chunk size used for en-/decoding. Closes #12945 --- docs/libcurl/libcurl-env-dbg.md | 5 +++++ lib/ws.c | 21 +++++++++++++++++---- tests/http/test_20_websockets.py | 11 +++++++++++ tests/http/testenv/client.py | 6 ++++-- 4 files changed, 37 insertions(+), 6 deletions(-) diff --git a/docs/libcurl/libcurl-env-dbg.md b/docs/libcurl/libcurl-env-dbg.md index 21b763bb4fc..21ed3bf25ae 100644 --- a/docs/libcurl/libcurl-env-dbg.md +++ b/docs/libcurl/libcurl-env-dbg.md @@ -116,3 +116,8 @@ Debug-version of the *ntlm-wb* executable. OpenLDAP tracing is enabled if this variable exists and its value is 1 or greater. There is a number of debug levels, refer to *openldap.c* comments. + +## CURL_WS_CHUNK_SIZE + +Used to influence the buffer chunk size used for WebSocket encoding and +decoding. diff --git a/lib/ws.c b/lib/ws.c index d9765182d95..f4675cec474 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -754,13 +754,26 @@ CURLcode Curl_ws_accept(struct Curl_easy *data, DEBUGASSERT(data->conn); ws = data->conn->proto.ws; if(!ws) { + size_t chunk_size = WS_CHUNK_SIZE; ws = calloc(1, sizeof(*ws)); if(!ws) return CURLE_OUT_OF_MEMORY; data->conn->proto.ws = ws; - Curl_bufq_init2(&ws->recvbuf, WS_CHUNK_SIZE, WS_CHUNK_COUNT, +#ifdef DEBUGBUILD + { + char *p = getenv("CURL_WS_CHUNK_SIZE"); + if(p) { + long l = strtol(p, NULL, 10); + if(l > 0 && l <= (1*1024*1024)) { + chunk_size = (size_t)l; + } + } + } +#endif + DEBUGF(infof(data, "WS, using chunk size %zu", chunk_size)); + Curl_bufq_init2(&ws->recvbuf, chunk_size, WS_CHUNK_COUNT, BUFQ_OPT_SOFT_LIMIT); - Curl_bufq_init2(&ws->sendbuf, WS_CHUNK_SIZE, WS_CHUNK_COUNT, + Curl_bufq_init2(&ws->sendbuf, chunk_size, WS_CHUNK_COUNT, BUFQ_OPT_SOFT_LIMIT); ws_dec_init(&ws->dec); ws_enc_init(&ws->enc); @@ -834,7 +847,7 @@ CURLcode Curl_ws_accept(struct Curl_easy *data, struct ws_collect { struct Curl_easy *data; - void *buffer; + unsigned char *buffer; size_t buflen; size_t bufidx; int frame_age; @@ -886,7 +899,7 @@ static ssize_t ws_client_collect(const unsigned char *buf, size_t buflen, return -1; } *err = CURLE_OK; - memcpy(ctx->buffer, buf, nwritten); + memcpy(ctx->buffer + ctx->bufidx, buf, nwritten); ctx->bufidx += nwritten; } return nwritten; diff --git a/tests/http/test_20_websockets.py b/tests/http/test_20_websockets.py index 4e70dcef003..eb9df306b31 100644 --- a/tests/http/test_20_websockets.py +++ b/tests/http/test_20_websockets.py @@ -129,3 +129,14 @@ def test_20_06_data_large(self, env: Env, ws_echo, repeat): url = f'ws://localhost:{env.ws_port}/' r = client.run(args=[url, str(65535 - 5), str(65535 + 5)]) r.check_exit_code(0) + + # the python websocket server does not like 'large' control frames + def test_20_07_data_large_small_recv(self, env: Env, ws_echo, repeat): + client = LocalClient(env=env, name='ws-data', run_env={ + 'CURL_WS_CHUNK_SIZE': '1024', + }) + if not client.exists(): + pytest.skip(f'example client not built: {client.name}') + url = f'ws://localhost:{env.ws_port}/' + r = client.run(args=[url, str(65535 - 5), str(65535 + 5)]) + r.check_exit_code(0) diff --git a/tests/http/testenv/client.py b/tests/http/testenv/client.py index 098e55b9cdc..e8ffb040aaf 100644 --- a/tests/http/testenv/client.py +++ b/tests/http/testenv/client.py @@ -45,10 +45,12 @@ class LocalClient: def __init__(self, name: str, env: Env, run_dir: Optional[str] = None, - timeout: Optional[float] = None): + timeout: Optional[float] = None, + run_env: Optional[Dict[str,str]] = None): self.name = name self.path = os.path.join(env.project_dir, f'tests/http/clients/{name}') self.env = env + self._run_env= run_env self._timeout = timeout if timeout else env.test_timeout self._curl = os.environ['CURL'] if 'CURL' in os.environ else env.curl self._run_dir = run_dir if run_dir else os.path.join(env.gen_dir, name) @@ -95,7 +97,7 @@ def run(self, args): with open(self._stderrfile, 'w') as cerr: p = subprocess.run(myargs, stderr=cerr, stdout=cout, cwd=self._run_dir, shell=False, - input=None, + input=None, env=self._run_env, timeout=self._timeout) exitcode = p.returncode except subprocess.TimeoutExpired: From f7e598791fc923d5b03a3f67009a516967177582 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 27 Nov 2023 11:30:25 +0100 Subject: [PATCH 349/509] DoH: add trace configuration - refs #12397 where it is dicussed how to en-/disable verbose output of DoH operations - introducing `struct curl_trc_feat` to track a curl feature for tracing - adding `data->state.feat` optionally pointing to the feature a transfer belongs to - adding trace functions and verbosity checks on features - using trace feature in DoH code - documenting `doh` as feature for `--trace-config` Closes #12411 --- docs/libcurl/curl_global_trace.md | 4 ++++ lib/curl_trc.c | 33 +++++++++++++++++++++++++------ lib/curl_trc.h | 18 ++++++++++++++--- lib/doh.c | 33 ++++++++++++++++++++----------- lib/doh.h | 2 ++ lib/urldata.h | 6 ++++++ 6 files changed, 76 insertions(+), 20 deletions(-) diff --git a/docs/libcurl/curl_global_trace.md b/docs/libcurl/curl_global_trace.md index aef2832fcef..56e320d0470 100644 --- a/docs/libcurl/curl_global_trace.md +++ b/docs/libcurl/curl_global_trace.md @@ -91,6 +91,10 @@ In order to find out all components involved in a transfer, run it with "all" configured. You can then see all names involved in your libcurl version in the trace. +## `doh` + +Tracing of DNS-over-HTTP operations to resolve hostnames. + # EXAMPLE ~~~c diff --git a/lib/curl_trc.c b/lib/curl_trc.c index 2f7fb65fdd0..fa6ad229bcb 100644 --- a/lib/curl_trc.c +++ b/lib/curl_trc.c @@ -36,6 +36,7 @@ #include "cf-socket.h" #include "connect.h" +#include "doh.h" #include "http2.h" #include "http_proxy.h" #include "cf-h1-proxy.h" @@ -113,12 +114,14 @@ void Curl_failf(struct Curl_easy *data, const char *fmt, ...) void Curl_infof(struct Curl_easy *data, const char *fmt, ...) { DEBUGASSERT(!strchr(fmt, '\n')); - if(data && data->set.verbose) { + if(Curl_trc_is_verbose(data)) { va_list ap; - int len; + int len = 0; char buffer[MAXINFO + 2]; + if(data->state.feat) + len = msnprintf(buffer, MAXINFO, "[%s] ", data->state.feat->name); va_start(ap, fmt); - len = mvsnprintf(buffer, MAXINFO, fmt, ap); + len += mvsnprintf(buffer + len, MAXINFO - len, fmt, ap); va_end(ap); buffer[len++] = '\n'; buffer[len] = '\0'; @@ -132,13 +135,16 @@ void Curl_trc_cf_infof(struct Curl_easy *data, struct Curl_cfilter *cf, DEBUGASSERT(cf); if(Curl_trc_cf_is_verbose(cf, data)) { va_list ap; - int len; + int len = 0; char buffer[MAXINFO + 2]; + if(data->state.feat) + len += msnprintf(buffer + len, MAXINFO - len, "[%s] ", + data->state.feat->name); if(cf->sockindex) - len = msnprintf(buffer, MAXINFO, "[%s-%d] ", + len += msnprintf(buffer + len, MAXINFO - len, "[%s-%d] ", cf->cft->name, cf->sockindex); else - len = msnprintf(buffer, MAXINFO, "[%s] ", cf->cft->name); + len += msnprintf(buffer + len, MAXINFO - len, "[%s] ", cf->cft->name); va_start(ap, fmt); len += mvsnprintf(buffer + len, MAXINFO - len, fmt, ap); va_end(ap); @@ -148,6 +154,12 @@ void Curl_trc_cf_infof(struct Curl_easy *data, struct Curl_cfilter *cf, } } +static struct curl_trc_feat *trc_feats[] = { +#ifndef CURL_DISABLE_DOH + &Curl_doh_trc, +#endif + NULL, +}; static struct Curl_cftype *cf_types[] = { &Curl_cft_tcp, @@ -219,6 +231,15 @@ CURLcode Curl_trc_opt(const char *config) break; } } + for(i = 0; trc_feats[i]; ++i) { + if(strcasecompare(token, "all")) { + trc_feats[i]->log_level = lvl; + } + else if(strcasecompare(token, trc_feats[i]->name)) { + trc_feats[i]->log_level = lvl; + break; + } + } token = strtok_r(NULL, ", ", &tok_buf); } free(tmp); diff --git a/lib/curl_trc.h b/lib/curl_trc.h index 3a5387a27a5..92b0533c03b 100644 --- a/lib/curl_trc.h +++ b/lib/curl_trc.h @@ -86,10 +86,21 @@ void Curl_failf(struct Curl_easy *data, #ifndef CURL_DISABLE_VERBOSE_STRINGS /* informational messages enabled */ -#define Curl_trc_is_verbose(data) ((data) && (data)->set.verbose) +struct curl_trc_feat { + const char *name; + int log_level; +}; + +#define Curl_trc_is_verbose(data) \ + ((data) && (data)->set.verbose && \ + (!(data)->state.feat || \ + ((data)->state.feat->log_level >= CURL_LOG_LVL_INFO))) #define Curl_trc_cf_is_verbose(cf, data) \ - ((data) && (data)->set.verbose && \ - (cf) && (cf)->cft->log_level >= CURL_LOG_LVL_INFO) + (Curl_trc_is_verbose(data) && \ + (cf) && (cf)->cft->log_level >= CURL_LOG_LVL_INFO) +#define Curl_trc_ft_is_verbose(data, ft) \ + (Curl_trc_is_verbose(data) && \ + (ft)->log_level >= CURL_LOG_LVL_INFO) /** * Output an informational message when transfer's verbose logging is enabled. @@ -109,6 +120,7 @@ void Curl_trc_cf_infof(struct Curl_easy *data, struct Curl_cfilter *cf, #define Curl_trc_is_verbose(d) ((void)(d), FALSE) #define Curl_trc_cf_is_verbose(x,y) ((void)(x), (void)(y), FALSE) +#define Curl_trc_ft_is_verbose(x,y) ((void)(x), (void)(y), FALSE) static void Curl_infof(struct Curl_easy *data, const char *fmt, ...) { diff --git a/lib/doh.c b/lib/doh.c index ef32d507df2..33e714166a4 100644 --- a/lib/doh.c +++ b/lib/doh.c @@ -69,7 +69,12 @@ static const char *doh_strerror(DOHcode code) return errors[code]; return "bad error code"; } -#endif + +struct curl_trc_feat Curl_doh_trc = { + "DoH", + CURL_LOG_LVL_NONE, +}; +#endif /* !CURL_DISABLE_VERBOSE_STRINGS */ /* @unittest 1655 */ @@ -189,9 +194,9 @@ static int doh_done(struct Curl_easy *doh, CURLcode result) struct dohdata *dohp = data->req.doh; /* so one of the DoH request done for the 'data' transfer is now complete! */ dohp->pending--; - infof(data, "a DoH request is completed, %u to go", dohp->pending); + infof(doh, "a DoH request is completed, %u to go", dohp->pending); if(result) - infof(data, "DoH request %s", curl_easy_strerror(result)); + infof(doh, "DoH request %s", curl_easy_strerror(result)); if(!dohp->pending) { /* DoH completed */ @@ -242,6 +247,9 @@ static CURLcode dohprobe(struct Curl_easy *data, the gcc typecheck helpers */ struct dynbuf *resp = &p->serverdoh; doh->state.internal = true; +#ifndef CURL_DISABLE_VERBOSE_STRINGS + doh->state.feat = &Curl_doh_trc; +#endif ERROR_CHECK_SETOPT(CURLOPT_URL, url); ERROR_CHECK_SETOPT(CURLOPT_DEFAULT_PROTOCOL, "https"); ERROR_CHECK_SETOPT(CURLOPT_WRITEFUNCTION, doh_write_cb); @@ -264,7 +272,7 @@ static CURLcode dohprobe(struct Curl_easy *data, ERROR_CHECK_SETOPT(CURLOPT_SHARE, data->share); if(data->set.err && data->set.err != stderr) ERROR_CHECK_SETOPT(CURLOPT_STDERR, data->set.err); - if(data->set.verbose) + if(Curl_trc_ft_is_verbose(data, &Curl_doh_trc)) ERROR_CHECK_SETOPT(CURLOPT_VERBOSE, 1L); if(data->set.no_signal) ERROR_CHECK_SETOPT(CURLOPT_NOSIGNAL, 1L); @@ -741,11 +749,11 @@ static void showdoh(struct Curl_easy *data, const struct dohentry *d) { int i; - infof(data, "TTL: %u seconds", d->ttl); + infof(data, "[DoH] TTL: %u seconds", d->ttl); for(i = 0; i < d->numaddr; i++) { const struct dohaddr *a = &d->addr[i]; if(a->type == DNS_TYPE_A) { - infof(data, "DoH A: %u.%u.%u.%u", + infof(data, "[DoH] A: %u.%u.%u.%u", a->ip.v4[0], a->ip.v4[1], a->ip.v4[2], a->ip.v4[3]); } @@ -754,9 +762,9 @@ static void showdoh(struct Curl_easy *data, char buffer[128]; char *ptr; size_t len; - msnprintf(buffer, 128, "DoH AAAA: "); - ptr = &buffer[10]; - len = 118; + len = msnprintf(buffer, 128, "[DoH] AAAA: "); + ptr = &buffer[len]; + len = sizeof(buffer) - len; for(j = 0; j < 16; j += 2) { size_t l; msnprintf(ptr, len, "%s%02x%02x", j?":":"", d->addr[i].ip.v6[j], @@ -950,8 +958,11 @@ CURLcode Curl_doh_is_resolved(struct Curl_easy *data, struct Curl_dns_entry *dns; struct Curl_addrinfo *ai; - infof(data, "DoH Host name: %s", dohp->host); - showdoh(data, &de); + + if(Curl_trc_ft_is_verbose(data, &Curl_doh_trc)) { + infof(data, "[DoH] Host name: %s", dohp->host); + showdoh(data, &de); + } result = doh2ai(&de, dohp->host, dohp->port, &ai); if(result) { diff --git a/lib/doh.h b/lib/doh.h index 7d7b694f33a..ffcf7a03356 100644 --- a/lib/doh.h +++ b/lib/doh.h @@ -120,6 +120,8 @@ void de_init(struct dohentry *d); void de_cleanup(struct dohentry *d); #endif +extern struct curl_trc_feat Curl_doh_trc; + #else /* if DoH is disabled */ #define Curl_doh(a,b,c,d) NULL #define Curl_doh_is_resolved(x,y) CURLE_COULDNT_RESOLVE_HOST diff --git a/lib/urldata.h b/lib/urldata.h index 66c8d107679..c0e64451987 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -53,6 +53,8 @@ #define PORT_GOPHER 70 #define PORT_MQTT 1883 +struct curl_trc_featt; + #ifdef USE_WEBSOCKETS /* CURLPROTO_GOPHERS (29) is the highest publicly used protocol bit number, * the rest are internal information. If we use higher bits we only do this on @@ -1446,6 +1448,10 @@ struct UrlState { CURLcode hresult; /* used to pass return codes back from hyper callbacks */ #endif +#ifndef CURL_DISABLE_VERBOSE_STRINGS + struct curl_trc_feat *feat; /* opt. trace feature transfer is part of */ +#endif + /* Dynamically allocated strings, MUST be freed before this struct is killed. */ struct dynamically_allocated_data { From d5b0fee39a7898dac42cb4fc64e35f5bc085e766 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 20 Feb 2024 11:48:27 +0100 Subject: [PATCH 350/509] sha512_256: remove the cast macro, minor language/format edits Follow-up to cbe41d151d6a100c Closes #12966 --- lib/curl_setup.h | 1 - lib/curl_sha512_256.c | 190 ++++++++++++++++++++---------------------- 2 files changed, 91 insertions(+), 100 deletions(-) diff --git a/lib/curl_setup.h b/lib/curl_setup.h index 644a8e2742d..286acc371f6 100644 --- a/lib/curl_setup.h +++ b/lib/curl_setup.h @@ -511,7 +511,6 @@ # endif # define CURL_UINT64_SUFFIX CURL_SUFFIX_CURL_OFF_TU # define CURL_UINT64_C(val) CURL_CONC_MACROS(val,CURL_UINT64_SUFFIX) -# define CURL_UINT64_CAST(expr) ((curl_uint64_t)(expr)) #endif #if (SIZEOF_TIME_T == 4) diff --git a/lib/curl_sha512_256.c b/lib/curl_sha512_256.c index c15f625df9c..cabea4349a9 100644 --- a/lib/curl_sha512_256.c +++ b/lib/curl_sha512_256.c @@ -87,16 +87,16 @@ ((curl_uint64_t)(((const unsigned char*)(ptr))[6]) << 8) | \ (curl_uint64_t)(((const unsigned char*)(ptr))[7]) ) -#define MHDX_PUT_64BIT_BE(ptr,val) do { \ - ((unsigned char*)(ptr))[7]=(unsigned char)((curl_uint64_t)(val)); \ - ((unsigned char*)(ptr))[6]=(unsigned char)(((curl_uint64_t)(val)) >> 8); \ - ((unsigned char*)(ptr))[5]=(unsigned char)(((curl_uint64_t)(val)) >> 16); \ - ((unsigned char*)(ptr))[4]=(unsigned char)(((curl_uint64_t)(val)) >> 24); \ - ((unsigned char*)(ptr))[3]=(unsigned char)(((curl_uint64_t)(val)) >> 32); \ - ((unsigned char*)(ptr))[2]=(unsigned char)(((curl_uint64_t)(val)) >> 40); \ - ((unsigned char*)(ptr))[1]=(unsigned char)(((curl_uint64_t)(val)) >> 48); \ - ((unsigned char*)(ptr))[0]=(unsigned char)(((curl_uint64_t)(val)) >> 56); \ -} while(0) +#define MHDX_PUT_64BIT_BE(ptr,val) do { \ + ((unsigned char*)(ptr))[7]=(unsigned char)((curl_uint64_t)(val)); \ + ((unsigned char*)(ptr))[6]=(unsigned char)(((curl_uint64_t)(val)) >> 8); \ + ((unsigned char*)(ptr))[5]=(unsigned char)(((curl_uint64_t)(val)) >> 16); \ + ((unsigned char*)(ptr))[4]=(unsigned char)(((curl_uint64_t)(val)) >> 24); \ + ((unsigned char*)(ptr))[3]=(unsigned char)(((curl_uint64_t)(val)) >> 32); \ + ((unsigned char*)(ptr))[2]=(unsigned char)(((curl_uint64_t)(val)) >> 40); \ + ((unsigned char*)(ptr))[1]=(unsigned char)(((curl_uint64_t)(val)) >> 48); \ + ((unsigned char*)(ptr))[0]=(unsigned char)(((curl_uint64_t)(val)) >> 56); \ + } while(0) /* Defined as a function. The macro version may duplicate the binary code * size as each argument is used twice, so if any calculation is used @@ -114,50 +114,49 @@ MHDx_rotr64(curl_uint64_t value, unsigned int bits) /* SHA-512/256 specific data */ /** - * Number of bits in single SHA-512/256 word. + * Number of bits in a single SHA-512/256 word. */ #define SHA512_256_WORD_SIZE_BITS 64 /** - * Number of bytes in single SHA-512/256 word. + * Number of bytes in a single SHA-512/256 word. */ #define SHA512_256_BYTES_IN_WORD (SHA512_256_WORD_SIZE_BITS / 8) /** * Hash is kept internally as 8 64-bit words. - * This is intermediate hash size, used during computing the final digest. + * This is the intermediate hash size, used during computing the final digest. */ #define SHA512_256_HASH_SIZE_WORDS 8 /** - * Size of SHA-512/256 resulting digest in bytes. + * Size of the SHA-512/256 resulting digest in bytes. * This is the final digest size, not intermediate hash. */ #define SHA512_256_DIGEST_SIZE_WORDS (SHA512_256_HASH_SIZE_WORDS / 2) /** - * Size of SHA-512/256 resulting digest in bytes + * Size of the SHA-512/256 resulting digest in bytes * This is the final digest size, not intermediate hash. */ #define SHA512_256_DIGEST_SIZE \ (SHA512_256_DIGEST_SIZE_WORDS * SHA512_256_BYTES_IN_WORD) /** - * Size of SHA-512/256 single processing block in bits. + * Size of the SHA-512/256 single processing block in bits. */ #define SHA512_256_BLOCK_SIZE_BITS 1024 /** - * Size of SHA-512/256 single processing block in bytes. + * Size of the SHA-512/256 single processing block in bytes. */ #define SHA512_256_BLOCK_SIZE (SHA512_256_BLOCK_SIZE_BITS / 8) /** - * Size of SHA-512/256 single processing block in words. + * Size of the SHA-512/256 single processing block in words. */ #define SHA512_256_BLOCK_SIZE_WORDS \ - (SHA512_256_BLOCK_SIZE_BITS / SHA512_256_WORD_SIZE_BITS) - + (SHA512_256_BLOCK_SIZE_BITS / SHA512_256_WORD_SIZE_BITS) /** * SHA-512/256 calculation context @@ -165,17 +164,15 @@ MHDx_rotr64(curl_uint64_t value, unsigned int bits) struct Sha512_256Ctx { /** - * Intermediate hash value - * The variable is properly aligned. Smart compiler - * may automatically use fast load/store instruction - * for big endian data on little endian machine. + * Intermediate hash value. The variable is properly aligned. Smart + * compilers may automatically use fast load/store instruction for big + * endian data on little endian machine. */ curl_uint64_t H[SHA512_256_HASH_SIZE_WORDS]; /** - * SHA-512/256 input data buffer - * The buffer is properly aligned. Smart compiler - * may automatically use fast load/store instruction - * for big endian data on little endian machine. + * SHA-512/256 input data buffer. The buffer is properly aligned. Smart + * compilers may automatically use fast load/store instruction for big + * endian data on little endian machine. */ curl_uint64_t buffer[SHA512_256_BLOCK_SIZE_WORDS]; /** @@ -183,8 +180,8 @@ struct Sha512_256Ctx */ curl_uint64_t count; /** - * The number of bits, high part. - * Unlike lower part, this counts the number of bits, not bytes. + * The number of bits, high part. Unlike lower part, this counts the number + * of bits, not bytes. */ curl_uint64_t count_bits_hi; }; @@ -227,14 +224,14 @@ MHDx_sha512_256_init(void *context) /** - * Base of SHA-512/256 transformation. - * Gets full 128 bytes block of data and updates hash values; + * Base of the SHA-512/256 transformation. + * Gets a full 128 bytes block of data and updates hash values; * @param H hash values * @param data the data buffer with #SHA512_256_BLOCK_SIZE bytes block */ static void MHDx_sha512_256_transform(curl_uint64_t H[SHA512_256_HASH_SIZE_WORDS], - const void *data) + const void *data) { /* Working variables, see FIPS PUB 180-4 section 6.7, 6.4. */ @@ -251,32 +248,28 @@ MHDx_sha512_256_transform(curl_uint64_t H[SHA512_256_HASH_SIZE_WORDS], See FIPS PUB 180-4 section 5.2.2, 6.7, 6.4. */ curl_uint64_t W[16]; - /* 'Ch' and 'Maj' macro functions are defined with - widely-used optimisation. + /* 'Ch' and 'Maj' macro functions are defined with widely-used optimisation. See FIPS PUB 180-4 formulae 4.8, 4.9. */ #define Ch(x,y,z) ( (z) ^ ((x) & ((y) ^ (z))) ) #define Maj(x,y,z) ( ((x) & (y)) ^ ((z) & ((x) ^ (y))) ) - /* Unoptimized (original) versions: */ -/* #define Ch(x,y,z) ( ( (x) & (y) ) ^ ( ~(x) & (z) ) ) */ -/* #define Maj(x,y,z) ( ((x) & (y)) ^ ((x) & (z)) ^ ((y) & (z)) ) */ /* Four 'Sigma' macro functions. See FIPS PUB 180-4 formulae 4.10, 4.11, 4.12, 4.13. */ -#define SIG0(x) \ +#define SIG0(x) \ ( MHDx_rotr64((x), 28) ^ MHDx_rotr64((x), 34) ^ MHDx_rotr64((x), 39) ) -#define SIG1(x) \ +#define SIG1(x) \ ( MHDx_rotr64((x), 14) ^ MHDx_rotr64((x), 18) ^ MHDx_rotr64((x), 41) ) -#define sig0(x) \ +#define sig0(x) \ ( MHDx_rotr64((x), 1) ^ MHDx_rotr64((x), 8) ^ ((x) >> 7) ) -#define sig1(x) \ +#define sig1(x) \ ( MHDx_rotr64((x), 19) ^ MHDx_rotr64((x), 61) ^ ((x) >> 6) ) if(1) { unsigned int t; /* K constants array. See FIPS PUB 180-4 section 4.2.3 for K values. */ - static const curl_uint64_t K[80] = - { CURL_UINT64_C(0x428a2f98d728ae22), CURL_UINT64_C(0x7137449123ef65cd), + static const curl_uint64_t K[80] = { + CURL_UINT64_C(0x428a2f98d728ae22), CURL_UINT64_C(0x7137449123ef65cd), CURL_UINT64_C(0xb5c0fbcfec4d3b2f), CURL_UINT64_C(0xe9b5dba58189dbbc), CURL_UINT64_C(0x3956c25bf348b538), CURL_UINT64_C(0x59f111f1b605d019), CURL_UINT64_C(0x923f82a4af194f9b), CURL_UINT64_C(0xab1c5ed5da6d8118), @@ -315,64 +308,64 @@ MHDx_sha512_256_transform(curl_uint64_t H[SHA512_256_HASH_SIZE_WORDS], CURL_UINT64_C(0x28db77f523047d84), CURL_UINT64_C(0x32caab7b40c72493), CURL_UINT64_C(0x3c9ebe0a15c9bebc), CURL_UINT64_C(0x431d67c49c100d4c), CURL_UINT64_C(0x4cc5d4becb3e42b6), CURL_UINT64_C(0x597f299cfc657e2a), - CURL_UINT64_C(0x5fcb6fab3ad6faec), CURL_UINT64_C(0x6c44198c4a475817)}; + CURL_UINT64_C(0x5fcb6fab3ad6faec), CURL_UINT64_C(0x6c44198c4a475817) + }; /* One step of SHA-512/256 computation, see FIPS PUB 180-4 section 6.4.2 step 3. - * Note: this macro updates working variables in-place, without rotation. - * Note: the first (vH += SIG1(vE) + Ch(vE,vF,vG) + kt + wt) equals T1 in - FIPS PUB 180-4 section 6.4.2 step 3. - the second (vH += SIG0(vA) + Maj(vE,vF,vC) equals T1 + T2 in - FIPS PUB 180-4 section 6.4.2 step 3. - * Note: 'wt' must be used exactly one time in this macro as macro for - 'wt' calculation may change other data as well every time when - used. */ + * Note: this macro updates working variables in-place, without rotation. + * Note: the first (vH += SIG1(vE) + Ch(vE,vF,vG) + kt + wt) equals T1 in + FIPS PUB 180-4 section 6.4.2 step 3. + the second (vH += SIG0(vA) + Maj(vE,vF,vC) equals T1 + T2 in + FIPS PUB 180-4 section 6.4.2 step 3. + * Note: 'wt' must be used exactly one time in this macro as macro for + 'wt' calculation may change other data as well every time when + used. */ #define SHA2STEP64(vA,vB,vC,vD,vE,vF,vG,vH,kt,wt) do { \ - (vD) += ((vH) += SIG1 ((vE)) + Ch ((vE),(vF),(vG)) + (kt) + (wt)); \ - (vH) += SIG0 ((vA)) + Maj ((vA),(vB),(vC)); } while (0) + (vD) += ((vH) += SIG1 ((vE)) + Ch ((vE),(vF),(vG)) + (kt) + (wt)); \ + (vH) += SIG0 ((vA)) + Maj ((vA),(vB),(vC)); } while (0) /* One step of SHA-512/256 computation with working variables rotation, - see FIPS PUB 180-4 section 6.4.2 step 3. - * Note: this version of macro reassign all working variable on - each step. */ -#define SHA2STEP64RV(vA,vB,vC,vD,vE,vF,vG,vH,kt,wt) do { \ - curl_uint64_t tmp_h_ = (vH); \ - SHA2STEP64((vA),(vB),(vC),(vD),(vE),(vF),(vG),tmp_h_,(kt),(wt)); \ - (vH) = (vG); \ - (vG) = (vF); \ - (vF) = (vE); \ - (vE) = (vD); \ - (vD) = (vC); \ - (vC) = (vB); \ - (vB) = (vA); \ - (vA) = tmp_h_; } while(0) - - /* Get value of W(t) from input data buffer for 0 <= t <= 15, - See FIPS PUB 180-4 section 6.2. - Input data must be read in big-endian bytes order, - see FIPS PUB 180-4 section 3.1.2. */ -#define SHA512_GET_W_FROM_DATA(buf,t) \ - MHDX_GET_64BIT_BE( \ - ((const unsigned char*) (buf)) + (t) * SHA512_256_BYTES_IN_WORD) - - /* During first 16 steps, before making any calculations on each step, - the W element is read from the input data buffer as big-endian value and + see FIPS PUB 180-4 section 6.4.2 step 3. This macro version reassigns + all working variables on each step. */ +#define SHA2STEP64RV(vA,vB,vC,vD,vE,vF,vG,vH,kt,wt) do { \ + curl_uint64_t tmp_h_ = (vH); \ + SHA2STEP64((vA),(vB),(vC),(vD),(vE),(vF),(vG),tmp_h_,(kt),(wt)); \ + (vH) = (vG); \ + (vG) = (vF); \ + (vF) = (vE); \ + (vE) = (vD); \ + (vD) = (vC); \ + (vC) = (vB); \ + (vB) = (vA); \ + (vA) = tmp_h_; } while(0) + + /* Get value of W(t) from input data buffer for 0 <= t <= 15, + See FIPS PUB 180-4 section 6.2. + Input data must be read in big-endian bytes order, + see FIPS PUB 180-4 section 3.1.2. */ +#define SHA512_GET_W_FROM_DATA(buf,t) \ + MHDX_GET_64BIT_BE( \ + ((const unsigned char*) (buf)) + (t) * SHA512_256_BYTES_IN_WORD) + + /* During first 16 steps, before making any calculation on each step, the + W element is read from the input data buffer as a big-endian value and stored in the array of W elements. */ for(t = 0; t < 16; ++t) { SHA2STEP64RV(a, b, c, d, e, f, g, h, K[t], \ W[t] = SHA512_GET_W_FROM_DATA(data, t)); } - /* 'W' generation and assignment for 16 <= t <= 79. - See FIPS PUB 180-4 section 6.4.2. - As only last 16 'W' are used in calculations, it is possible to - use 16 elements array of W as a cyclic buffer. - * Note: ((t-16) & 15) have same value as (t & 15) */ -#define Wgen(w,t) \ - CURL_UINT64_CAST( (w)[(t - 16) & 15] + sig1((w)[((t) - 2) & 15]) \ - + (w)[((t) - 7) & 15] + sig0((w)[((t) - 15) & 15]) ) + /* 'W' generation and assignment for 16 <= t <= 79. + See FIPS PUB 180-4 section 6.4.2. + As only the last 16 'W' are used in calculations, it is possible to + use 16 elements array of W as a cyclic buffer. + Note: ((t-16) & 15) have same value as (t & 15) */ +#define Wgen(w,t) \ + (curl_uint64_t)( (w)[(t - 16) & 15] + sig1((w)[((t) - 2) & 15]) \ + + (w)[((t) - 7) & 15] + sig0((w)[((t) - 15) & 15]) ) - /* During last 64 steps, before making any calculations on each step, + /* During the last 64 steps, before making any calculation on each step, current W element is generated from other W elements of the cyclic buffer and the generated value is stored back in the cyclic buffer. */ for(t = 16; t < 80; ++t) { @@ -403,12 +396,12 @@ MHDx_sha512_256_transform(curl_uint64_t H[SHA512_256_HASH_SIZE_WORDS], */ static void MHDx_sha512_256_update(void *context, - const unsigned char *data, - unsigned int length) + const unsigned char *data, + unsigned int length) { unsigned int bytes_have; /**< Number of bytes in the context buffer */ struct Sha512_256Ctx *const ctx = (struct Sha512_256Ctx *) context; - /* Required to mute Intel compiler warning */ + /* the void pointer here is required to mute Intel compiler warning */ void *const ctx_buf = ctx->buffer; DEBUGASSERT((data != NULL) || (length == 0)); @@ -417,10 +410,10 @@ MHDx_sha512_256_update(void *context, return; /* Shortcut, do nothing */ /* Note: (count & (SHA512_256_BLOCK_SIZE-1)) - equals (count % SHA512_256_BLOCK_SIZE) for this block size. */ + equals (count % SHA512_256_BLOCK_SIZE) for this block size. */ bytes_have = (unsigned int) (ctx->count & (SHA512_256_BLOCK_SIZE - 1)); ctx->count += length; - if(CURL_UINT64_CAST(length) > ctx->count) + if(length > ctx->count) ctx->count_bits_hi += 1U << 3; /* Value wrap */ ctx->count_bits_hi += ctx->count >> 61; ctx->count &= CURL_UINT64_C(0x1FFFFFFFFFFFFFFF); @@ -428,8 +421,8 @@ MHDx_sha512_256_update(void *context, if(0 != bytes_have) { unsigned int bytes_left = SHA512_256_BLOCK_SIZE - bytes_have; if(length >= bytes_left) { - /* Combine new data with data in the buffer and - process the full block. */ + /* Combine new data with data in the buffer and process the full + block. */ memcpy(((unsigned char *) ctx_buf) + bytes_have, data, bytes_left); @@ -476,15 +469,14 @@ MHDx_sha512_256_update(void *context, */ static void MHDx_sha512_256_finish(unsigned char *digest, - void *context) + void *context) { struct Sha512_256Ctx *const ctx = (struct Sha512_256Ctx *) context; curl_uint64_t num_bits; /**< Number of processed bits */ unsigned int bytes_have; /**< Number of bytes in the context buffer */ - /* Required to mute Intel compiler warning */ + /* the void pointer here is required to mute Intel compiler warning */ void *const ctx_buf = ctx->buffer; - /* Memorise the number of processed bits. The padding and other data added here during the postprocessing must not change the amount of hashed data. */ From cc04c7367740bb6db0e47368247b8b0c70c376cb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Feb 2024 08:38:53 +0100 Subject: [PATCH 351/509] CURLINFO_USED_PROXY: return bool whether the proxy was used Adds test536 to verify Closes #12719 --- docs/libcurl/curl_easy_getinfo.md | 4 ++ docs/libcurl/opts/CURLINFO_USED_PROXY.md | 69 +++++++++++++++++++ docs/libcurl/opts/Makefile.inc | 1 + docs/libcurl/symbols-in-versions | 1 + include/curl/curl.h | 3 +- lib/connect.c | 7 ++ lib/getinfo.c | 10 ++- lib/urldata.h | 1 + tests/data/Makefile.inc | 2 +- tests/data/test536 | 76 +++++++++++++++++++++ tests/libtest/Makefile.inc | 5 +- tests/libtest/lib536.c | 84 ++++++++++++++++++++++++ 12 files changed, 259 insertions(+), 4 deletions(-) create mode 100644 docs/libcurl/opts/CURLINFO_USED_PROXY.md create mode 100644 tests/data/test536 create mode 100644 tests/libtest/lib536.c diff --git a/docs/libcurl/curl_easy_getinfo.md b/docs/libcurl/curl_easy_getinfo.md index eb5608be9c1..bd18aa7c638 100644 --- a/docs/libcurl/curl_easy_getinfo.md +++ b/docs/libcurl/curl_easy_getinfo.md @@ -120,6 +120,10 @@ See CURLINFO_PRETRANSFER_TIME_T(3) Time during which this transfer was held in a waiting queue. See CURLINFO_QUEUE_TIME_T(3) +## CURLINFO_USED_PROXY + +Whether the proxy was used (Added in 8.7.0). See CURLINFO_USED_PROXY(3) + ## CURLINFO_STARTTRANSFER_TIME Time from start until just when the first byte is received. diff --git a/docs/libcurl/opts/CURLINFO_USED_PROXY.md b/docs/libcurl/opts/CURLINFO_USED_PROXY.md new file mode 100644 index 00000000000..98fafa78f1b --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_USED_PROXY.md @@ -0,0 +1,69 @@ +--- +c: Copyright (C) Daniel Stenberg, , et al. +SPDX-License-Identifier: curl +Title: CURLINFO_USED_PROXY +Section: 3 +Source: libcurl +See-also: + - CURLOPT_NOPROXY (3) + - CURLOPT_PROXY (3) + - curl_easy_getinfo (3) + - curl_easy_setopt (3) +--- + +# NAME + +CURLINFO_USED_PROXY - whether the transfer used a proxy + +# SYNOPSIS + +~~~c +#include + +CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_USED_PROXY, + long *authp); +~~~ + +# DESCRIPTION + +Pass a pointer to a long. It gets set to zero set if no proxy was used in the +previous transfer or a non-zero value if a proxy was used. + +# PROTOCOLS + +HTTP(S) + +# EXAMPLE + +~~~c +int main(int argc, char *argv[]) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); + curl_easy_setopt(curl, CURLOPT_NOPROXY, "example.com"); + + res = curl_easy_perform(curl); + + if(!res) { + /* extract the available proxy authentication types */ + long used; + res = curl_easy_getinfo(curl, CURLINFO_USED_PROXY, &used); + if(!res) { + printf("The proxy was %sused\n", used ? "": "NOT "); + } + } + curl_easy_cleanup(curl); + } +} +~~~ + +# AVAILABILITY + +Added in 8.7.0 + +# RETURN VALUE + +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc index be7035bf00d..7a292b81d51 100644 --- a/docs/libcurl/opts/Makefile.inc +++ b/docs/libcurl/opts/Makefile.inc @@ -95,6 +95,7 @@ man_MANS = \ CURLINFO_TLS_SSL_PTR.3 \ CURLINFO_TOTAL_TIME.3 \ CURLINFO_TOTAL_TIME_T.3 \ + CURLINFO_USED_PROXY.3 \ CURLINFO_XFER_ID.3 \ CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 \ CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 \ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index c20008a7313..a627dd68b6c 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -506,6 +506,7 @@ CURLINFO_TLS_SSL_PTR 7.48.0 CURLINFO_TOTAL_TIME 7.4.1 CURLINFO_TOTAL_TIME_T 7.61.0 CURLINFO_TYPEMASK 7.4.1 +CURLINFO_USED_PROXY 8.7.0 CURLINFO_XFER_ID 8.2.0 CURLIOCMD_NOP 7.12.3 CURLIOCMD_RESTARTREAD 7.12.3 diff --git a/include/curl/curl.h b/include/curl/curl.h index eb06022501c..b2377b7895b 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -2938,7 +2938,8 @@ typedef enum { CURLINFO_XFER_ID = CURLINFO_OFF_T + 63, CURLINFO_CONN_ID = CURLINFO_OFF_T + 64, CURLINFO_QUEUE_TIME_T = CURLINFO_OFF_T + 65, - CURLINFO_LASTONE = 65 + CURLINFO_USED_PROXY = CURLINFO_LONG + 66, + CURLINFO_LASTONE = 66 } CURLINFO; /* CURLINFO_RESPONSE_CODE is the new name for the option previously known as diff --git a/lib/connect.c b/lib/connect.c index 55bd49d8d31..5e0f8b23923 100644 --- a/lib/connect.c +++ b/lib/connect.c @@ -158,6 +158,13 @@ void Curl_persistconninfo(struct Curl_easy *data, struct connectdata *conn, data->info.conn_primary_port = conn->port; data->info.conn_remote_port = conn->remote_port; data->info.conn_local_port = local_port; + data->info.used_proxy = +#ifdef CURL_DISABLE_PROXY + 0 +#else + conn->bits.proxy +#endif + ; } static const struct Curl_addrinfo * diff --git a/lib/getinfo.c b/lib/getinfo.c index 2f74629e1e7..aaf17713f3e 100644 --- a/lib/getinfo.c +++ b/lib/getinfo.c @@ -180,7 +180,6 @@ static CURLcode getinfo_char(struct Curl_easy *data, CURLINFO info, *param_charp = NULL; #endif break; - default: return CURLE_UNKNOWN_OPTION; } @@ -334,6 +333,15 @@ static CURLcode getinfo_long(struct Curl_easy *data, CURLINFO info, case CURLINFO_PROTOCOL: *param_longp = data->info.conn_protocol; break; + case CURLINFO_USED_PROXY: + *param_longp = +#ifdef CURL_DISABLE_PROXY + 0 +#else + data->info.used_proxy +#endif + ; + break; default: return CURLE_UNKNOWN_OPTION; } diff --git a/lib/urldata.h b/lib/urldata.h index c0e64451987..5f61f26302b 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1167,6 +1167,7 @@ struct PureInfo { CURLproxycode pxcode; BIT(timecond); /* set to TRUE if the time condition didn't match, which thus made the document NOT get fetched */ + BIT(used_proxy); /* the transfer used a proxy */ }; diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 546e4ad482d..c20f90d945c 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -80,7 +80,7 @@ test499 test500 test501 test502 test503 test504 test505 test506 test507 \ test508 test509 test510 test511 test512 test513 test514 test515 test516 \ test517 test518 test519 test520 test521 test522 test523 test524 test525 \ test526 test527 test528 test529 test530 test531 test532 test533 test534 \ -test535 test537 test538 test539 test540 test541 test542 test543 \ +test535 test536 test537 test538 test539 test540 test541 test542 test543 \ test544 test545 test546 test547 test548 test549 test550 test551 test552 \ test553 test554 test555 test556 test557 test558 test559 test560 test561 \ test562 test563 test564 test565 test566 test567 test568 test569 test570 \ diff --git a/tests/data/test536 b/tests/data/test536 new file mode 100644 index 00000000000..dc78f2a6513 --- /dev/null +++ b/tests/data/test536 @@ -0,0 +1,76 @@ + + + +HTTP +HTTP GET +HTTP proxy +CURLOPT_PROXY +CURLOPT_NOBODY +CURLINFO_USED_PROXY + + + +# +# Server-side + + +HTTP/1.1 200 OK swsclose +Date: Tue, 09 Nov 2010 14:49:00 GMT +Server: test-server/fake +Last-Modified: Tue, 13 Jun 2000 12:10:00 GMT +ETag: "21025-dc7-39462498" +Accept-Ranges: bytes +Content-Length: 6 + +hello + + + +# +# Client-side + + +http + + +lib%TESTNUMBER + + +CURLINFO_USED_PROXY + + +# provides: +# 0 - the proxy URL +# 1 - the non-proxy using URL +# 2 - the CURLOPT_RESOLVE string to change IP for the name +# + +http://%HOSTIP:%HTTPPORT goingdirect.com:%HTTPPORT goingdirect.com:%HTTPPORT:%HOSTIP + + +proxy + + + +# +# Verify data after the test has been "shot" + + +GET http://usingproxy.com/ HTTP/1.1 +Host: usingproxy.com +Accept: */* +Proxy-Connection: Keep-Alive + +GET / HTTP/1.1 +Host: goingdirect.com:%HTTPPORT +Accept: */* + + + +hello +This used the proxy +hello +This DID NOT use the proxy + + + diff --git a/tests/libtest/Makefile.inc b/tests/libtest/Makefile.inc index c4d36a26b3f..1a61deb6234 100644 --- a/tests/libtest/Makefile.inc +++ b/tests/libtest/Makefile.inc @@ -42,7 +42,8 @@ noinst_PROGRAMS = chkhostname libauthretry libntlmconnect libprereq \ lib500 lib501 lib502 lib503 lib504 lib505 lib506 lib507 lib508 lib509 \ lib510 lib511 lib512 lib513 lib514 lib515 lib516 lib517 lib518 lib519 \ lib520 lib521 lib523 lib524 lib525 lib526 lib527 lib529 lib530 lib532 \ - lib533 lib537 lib539 lib540 lib541 lib542 lib543 lib544 lib545 \ + lib533 lib536 lib537 lib539 lib540 lib541 lib542 lib543 \ + lib544 lib545 \ lib547 lib548 lib549 lib552 lib553 lib554 lib555 lib556 lib557 lib558 \ lib559 lib560 lib562 lib564 lib565 lib566 lib567 lib568 lib569 lib570 \ lib571 lib572 lib573 lib574 lib575 lib576 lib578 lib579 lib582 \ @@ -168,6 +169,8 @@ lib532_CPPFLAGS = $(AM_CPPFLAGS) -DLIB532 lib533_SOURCES = lib533.c $(SUPPORTFILES) $(TESTUTIL) $(WARNLESS) lib533_LDADD = $(TESTUTIL_LIBS) +lib536_SOURCES = lib536.c $(SUPPORTFILES) + lib537_SOURCES = lib537.c $(SUPPORTFILES) $(WARNLESS) $(MULTIBYTE) lib539_SOURCES = lib539.c $(SUPPORTFILES) diff --git a/tests/libtest/lib536.c b/tests/libtest/lib536.c new file mode 100644 index 00000000000..7e53e225558 --- /dev/null +++ b/tests/libtest/lib536.c @@ -0,0 +1,84 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ +#include "test.h" + +#include "memdebug.h" + +#define WITH_PROXY "http://usingproxy.com/" +#define WITHOUT_PROXY libtest_arg2 + +static void proxystat(CURL *curl) +{ + long wasproxy; + if(!curl_easy_getinfo(curl, CURLINFO_USED_PROXY, &wasproxy)) { + printf("This %sthe proxy\n", wasproxy ? "used ": + "DID NOT use "); + } +} + +int test(char *URL) +{ + CURLcode res = CURLE_OK; + CURL *curl; + struct curl_slist *host = NULL; + + if(curl_global_init(CURL_GLOBAL_ALL) != CURLE_OK) { + fprintf(stderr, "curl_global_init() failed\n"); + return TEST_ERR_MAJOR_BAD; + } + + curl = curl_easy_init(); + if(!curl) { + fprintf(stderr, "curl_easy_init() failed\n"); + curl_global_cleanup(); + return TEST_ERR_MAJOR_BAD; + } + + host = curl_slist_append(NULL, libtest_arg3); + if(!host) + goto test_cleanup; + + test_setopt(curl, CURLOPT_RESOLVE, host); + test_setopt(curl, CURLOPT_PROXY, URL); + test_setopt(curl, CURLOPT_URL, WITH_PROXY); + test_setopt(curl, CURLOPT_NOPROXY, "goingdirect.com"); + test_setopt(curl, CURLOPT_VERBOSE, 1L); + + res = curl_easy_perform(curl); + if(!res) { + proxystat(curl); + test_setopt(curl, CURLOPT_URL, WITHOUT_PROXY); + res = curl_easy_perform(curl); + if(!res) + proxystat(curl); + } + +test_cleanup: + + curl_easy_cleanup(curl); + curl_slist_free_all(host); + curl_global_cleanup(); + + return (int)res; +} From ac208ccf6f073c0e3cd363f771cb28ea1200d59c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Feb 2024 08:38:53 +0100 Subject: [PATCH 352/509] write-out: add '%{proxy_used}' Returns 1 if the previous transfer used a proxy, otherwise 0. Useful to for example determine if a `NOPROXY` pattern matched the hostname or not. Extended test 970 and 972 --- docs/cmdline-opts/write-out.md | 5 +++++ src/tool_writeout.c | 1 + src/tool_writeout.h | 1 + tests/data/test970 | 2 +- tests/data/test972 | 2 +- 5 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/cmdline-opts/write-out.md b/docs/cmdline-opts/write-out.md index ac4b7d03ff3..068af7675a9 100644 --- a/docs/cmdline-opts/write-out.md +++ b/docs/cmdline-opts/write-out.md @@ -138,6 +138,11 @@ The rest of the output is only shown if the transfer returned a non-zero error. The result of the HTTPS proxy's SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.52.0) +## `proxy_used` +Returns 1 if the previous transfer used a proxy, otherwise 0. Useful to for +example determine if a `NOPROXY` pattern matched the hostname or not. (Added +in 8.7.0) + ## `redirect_url` When an HTTP request was made without --location to follow redirects (or when --max-redirs is met), this variable shows the actual URL a redirect diff --git a/src/tool_writeout.c b/src/tool_writeout.c index 981065c9ef6..b8bb174ec7c 100644 --- a/src/tool_writeout.c +++ b/src/tool_writeout.c @@ -95,6 +95,7 @@ static const struct writeoutvar variables[] = { {"onerror", VAR_ONERROR, CURLINFO_NONE, NULL}, {"proxy_ssl_verify_result", VAR_PROXY_SSL_VERIFY_RESULT, CURLINFO_PROXY_SSL_VERIFYRESULT, writeLong}, + {"proxy_used", VAR_PROXY_USED, CURLINFO_USED_PROXY, writeLong}, {"redirect_url", VAR_REDIRECT_URL, CURLINFO_REDIRECT_URL, writeString}, {"referer", VAR_REFERER, CURLINFO_REFERER, writeString}, {"remote_ip", VAR_PRIMARY_IP, CURLINFO_PRIMARY_IP, writeString}, diff --git a/src/tool_writeout.h b/src/tool_writeout.h index 4e690a65c94..0b9e3cbb1c5 100644 --- a/src/tool_writeout.h +++ b/src/tool_writeout.h @@ -79,6 +79,7 @@ typedef enum { VAR_PRIMARY_IP, VAR_PRIMARY_PORT, VAR_PROXY_SSL_VERIFY_RESULT, + VAR_PROXY_USED, VAR_REDIRECT_COUNT, VAR_REDIRECT_TIME, VAR_REDIRECT_URL, diff --git a/tests/data/test970 b/tests/data/test970 index 88ab796122d..94e00df1ce4 100644 --- a/tests/data/test970 +++ b/tests/data/test970 @@ -59,7 +59,7 @@ Accept: */* -{"certs":"","content_type":"text/html","conn_id":0,"errormsg":null,"exitcode":0,"filename_effective":"%LOGDIR/out%TESTNUMBER","ftp_entry_path":null,"http_code":200,"http_connect":0,"http_version":"1.1","local_ip":"127.0.0.1","local_port":13,"method":"GET","num_certs":0,"num_connects":1,"num_headers":9,"num_redirects":0,"proxy_ssl_verify_result":0,"redirect_url":null,"referer":null,"remote_ip":"%HOSTIP","remote_port":%HTTPPORT,"response_code":200,"scheme":"HTTP","size_download":445,"size_header":4019,"size_request":4019,"size_upload":0,"speed_download":13,"speed_upload":13,"ssl_verify_result":0,"time_appconnect":0.000013,"time_connect":0.000013,"time_namelookup":0.000013,"time_pretransfer":0.000013,"time_redirect":0.000013,"time_starttransfer":0.000013,"time_total":0.000013,"url":"http://%HOSTIP:%HTTPPORT/%TESTNUMBER","url.scheme":"http","url.user":null,"url.password":null,"url.options":null,"url.host":"%HOSTIP","url.port":"%HTTPPORT","url.path":"/%TESTNUMBER","url.query":null,"url.fragment":null,"url.zoneid":null,"urle.scheme":"http","urle.user":null,"urle.password":null,"urle.options":null,"urle.host":"%HOSTIP","urle.port":"%HTTPPORT","urle.path":"/%TESTNUMBER","urle.query":null,"urle.fragment":null,"urle.zoneid":null,"url_effective":"http://%HOSTIP:%HTTPPORT/%TESTNUMBER","urlnum":0,"xfer_id":0,"curl_version":"curl-unit-test-fake-version"} +{"certs":"","content_type":"text/html","conn_id":0,"errormsg":null,"exitcode":0,"filename_effective":"%LOGDIR/out%TESTNUMBER","ftp_entry_path":null,"http_code":200,"http_connect":0,"http_version":"1.1","local_ip":"127.0.0.1","local_port":13,"method":"GET","num_certs":0,"num_connects":1,"num_headers":9,"num_redirects":0,"proxy_ssl_verify_result":0,"proxy_used":0,"redirect_url":null,"referer":null,"remote_ip":"%HOSTIP","remote_port":%HTTPPORT,"response_code":200,"scheme":"HTTP","size_download":445,"size_header":4019,"size_request":4019,"size_upload":0,"speed_download":13,"speed_upload":13,"ssl_verify_result":0,"time_appconnect":0.000013,"time_connect":0.000013,"time_namelookup":0.000013,"time_pretransfer":0.000013,"time_redirect":0.000013,"time_starttransfer":0.000013,"time_total":0.000013,"url":"http://%HOSTIP:%HTTPPORT/%TESTNUMBER","url.scheme":"http","url.user":null,"url.password":null,"url.options":null,"url.host":"%HOSTIP","url.port":"%HTTPPORT","url.path":"/%TESTNUMBER","url.query":null,"url.fragment":null,"url.zoneid":null,"urle.scheme":"http","urle.user":null,"urle.password":null,"urle.options":null,"urle.host":"%HOSTIP","urle.port":"%HTTPPORT","urle.path":"/%TESTNUMBER","urle.query":null,"urle.fragment":null,"urle.zoneid":null,"url_effective":"http://%HOSTIP:%HTTPPORT/%TESTNUMBER","urlnum":0,"xfer_id":0,"curl_version":"curl-unit-test-fake-version"} diff --git a/tests/data/test972 b/tests/data/test972 index 1dc2eca342f..735c959976a 100644 --- a/tests/data/test972 +++ b/tests/data/test972 @@ -60,7 +60,7 @@ Accept: */* -{"certs":"","content_type":"text/html","conn_id":0,"errormsg":null,"exitcode":0,"filename_effective":"%LOGDIR/out972","ftp_entry_path":null,"http_code":200,"http_connect":0,"http_version":"1.1","local_ip":"%HOSTIP","local_port":13,"method":"GET","num_certs":0,"num_connects":1,"num_headers":9,"num_redirects":0,"proxy_ssl_verify_result":0,"redirect_url":null,"referer":null,"remote_ip":"%HOSTIP","remote_port":%HTTPPORT,"response_code":200,"scheme":"HTTP","size_download":445,"size_header":4019,"size_request":4019,"size_upload":0,"speed_download":13,"speed_upload":13,"ssl_verify_result":0,"time_appconnect":0.000013,"time_connect":0.000013,"time_namelookup":0.000013,"time_pretransfer":0.000013,"time_redirect":0.000013,"time_starttransfer":0.000013,"time_total":0.000013,"url":"http://%HOSTIP:%HTTPPORT/%TESTNUMBER","url.scheme":"http","url.user":null,"url.password":null,"url.options":null,"url.host":"%HOSTIP","url.port":"%HTTPPORT","url.path":"/%TESTNUMBER","url.query":null,"url.fragment":null,"url.zoneid":null,"urle.scheme":"http","urle.user":null,"urle.password":null,"urle.options":null,"urle.host":"%HOSTIP","urle.port":"%HTTPPORT","urle.path":"/%TESTNUMBER","urle.query":null,"urle.fragment":null,"urle.zoneid":null,"url_effective":"http://%HOSTIP:%HTTPPORT/%TESTNUMBER","urlnum":0,"xfer_id":0,"curl_version":"curl-unit-test-fake-version"} +{"certs":"","content_type":"text/html","conn_id":0,"errormsg":null,"exitcode":0,"filename_effective":"%LOGDIR/out972","ftp_entry_path":null,"http_code":200,"http_connect":0,"http_version":"1.1","local_ip":"%HOSTIP","local_port":13,"method":"GET","num_certs":0,"num_connects":1,"num_headers":9,"num_redirects":0,"proxy_ssl_verify_result":0,"proxy_used":0,"redirect_url":null,"referer":null,"remote_ip":"%HOSTIP","remote_port":%HTTPPORT,"response_code":200,"scheme":"HTTP","size_download":445,"size_header":4019,"size_request":4019,"size_upload":0,"speed_download":13,"speed_upload":13,"ssl_verify_result":0,"time_appconnect":0.000013,"time_connect":0.000013,"time_namelookup":0.000013,"time_pretransfer":0.000013,"time_redirect":0.000013,"time_starttransfer":0.000013,"time_total":0.000013,"url":"http://%HOSTIP:%HTTPPORT/%TESTNUMBER","url.scheme":"http","url.user":null,"url.password":null,"url.options":null,"url.host":"%HOSTIP","url.port":"%HTTPPORT","url.path":"/%TESTNUMBER","url.query":null,"url.fragment":null,"url.zoneid":null,"urle.scheme":"http","urle.user":null,"urle.password":null,"urle.options":null,"urle.host":"%HOSTIP","urle.port":"%HTTPPORT","urle.path":"/%TESTNUMBER","urle.query":null,"urle.fragment":null,"urle.zoneid":null,"url_effective":"http://%HOSTIP:%HTTPPORT/%TESTNUMBER","urlnum":0,"xfer_id":0,"curl_version":"curl-unit-test-fake-version"} From 32234ffcdc5170612606085b89a7095eae9d1b3b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Feb 2024 08:46:04 +0100 Subject: [PATCH 353/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index bb7cc0cb291..6be7f9b6868 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,17 +4,23 @@ curl and libcurl 8.6.1 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3094 + Contributors: 3095 This release includes the following changes: 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 + o DoH: add trace configuration [61] + o write-out: add '%{proxy_used}' This release includes the following bugfixes: o ALTSVC.md: correct a typo [14] 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 cd2nroff: remove backticks from titles o checksrc.pl: fix handling .checksrc with CRLF [43] o cmake: add warning for using TLS libraries without 1.3 support [25] o cmake: fix function description in comment [47] @@ -27,15 +33,15 @@ This release includes the following bugfixes: o cookie.md: provide an example sending a fixed cookie [13] o curl: exit on config file parser errors [40] o curl: when allocating variables, add the name into the struct [37] + o curl_setup.h: add curl_uint64_t internal type o CURLOPT_POSTQUOTE.md: fix typo [36] o CURLOPT_WRITEFUNCTION.md: typo fix [41] o dist: make sure the http tests are in the tarball [29] o docs: add missing slashes to SChannel client certificate documentation [11] - o docs: add mk-ca-bundle.1 to dist [49] o docs: add necessary setup for nghttp3 [51] + o docs: dist curl*.1 and install without perl [64] o docs: make curldown do angle brackets like markdown [54] o docs: make sure curl.1 is included in dist tarballs [35] - o docs: remove `mk-ca-bundle.1` from `man_MANS` [21] o file: use xfer buf for file:// transfers [23] o form-string.md: correct the example [4] o ftp: do lineend conversions in client writer [32] @@ -49,12 +55,15 @@ This release includes the following bugfixes: o https-proxy: use IP address and cert with ip in alt names [50] o lib582: remove code causing warning that is never run [38] o lib: convert Curl_get_line to use dynbuf [42] + o libcurl-docs: cleanups o libcurl-security.md: Active FTP passes on the local IP address [6] + o MANUAL.md: fix typo [66] o mbedtls: fix building when MBEDTLS_X509_REMOVE_INFO flag is defined [27] o mbedtls: use mbedtls_ssl_conf_{min|max}_tls_version [59] o md4: include strdup.h for the memdup proto [10] o multi: add xfer_buf to multi handle [30] 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 OS400: avoid using awk in the build scripts [20] o proxy1.0.md: fix example [15] @@ -70,6 +79,7 @@ This release includes the following bugfixes: o version: allow building with ancient libpsl [52] o vtls: fix tls proxy peer verification [55] o vtls: revert "receive max buffer" + add test case [39] + o websocket: fix curl_ws_recv() [62] o write-out.md: clarify error handling details [31] This release includes the following known bugs: @@ -90,10 +100,11 @@ advice from friends like these: edmcln on github, Erik Schnetter, Evgeny Grin (Karlson2k), Fabian Vogt, Faraz Fallahi, Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, Joel Depooter, Jon Rumsey, Karthikdasari0423, Konstantin Vlasov, - Lars Kellogg-Stedman, LeeRiva, Lukáš Zaoral, Michael Kaufmann, - Michał Antoniak, Patrick Monnerat, Peter Krefting, Ray Satiro, - Richard Levitte, Ryan Carsten Schmidt, Scott Mutter, Sergey Bronnikov, - Stefan Eissing, Viktor Szakats + Lars Kellogg-Stedman, LeeRiva, Lukáš Zaoral, Michael Forney, + Michael Kaufmann, Michał Antoniak, Patrick Monnerat, Peter Krefting, + Ramiro Garcia, Ray Satiro, Richard Levitte, Ryan Carsten Schmidt, + Scott Mutter, Sergey Bronnikov, Stefan Eissing, Viktor Szakats + (38 contributors) References to bug reports and discussions on issues: @@ -120,6 +131,7 @@ References to bug reports and discussions on issues: [21] = https://curl.se/bug/?i=12843 [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 @@ -155,3 +167,9 @@ References to bug reports and discussions on issues: [57] = https://curl.se/bug/?i=12894 [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 + [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 From 93d8e3564e85588796792aa6e3ba0c37de9ac752 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Feb 2024 09:34:41 +0100 Subject: [PATCH 354/509] curlver: bump to 8.7.0 for next release --- RELEASE-NOTES | 2 +- include/curl/curlver.h | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 6be7f9b6868..f386d71037d 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -1,4 +1,4 @@ -curl and libcurl 8.6.1 +curl and libcurl 8.7.0 Public curl releases: 255 Command line options: 258 diff --git a/include/curl/curlver.h b/include/curl/curlver.h index ed78adca570..52009e548bd 100644 --- a/include/curl/curlver.h +++ b/include/curl/curlver.h @@ -32,13 +32,13 @@ /* This is the version number of the libcurl package from which this header file origins: */ -#define LIBCURL_VERSION "8.6.1-DEV" +#define LIBCURL_VERSION "8.7.0-DEV" /* The numeric version number is also available "in parts" by using these defines: */ #define LIBCURL_VERSION_MAJOR 8 -#define LIBCURL_VERSION_MINOR 6 -#define LIBCURL_VERSION_PATCH 1 +#define LIBCURL_VERSION_MINOR 7 +#define LIBCURL_VERSION_PATCH 0 /* This is the numeric version of the libcurl version number, meant for easier parsing and comparisons by programs. The LIBCURL_VERSION_NUM define will @@ -59,7 +59,7 @@ CURL_VERSION_BITS() macro since curl's own configure script greps for it and needs it to contain the full number. */ -#define LIBCURL_VERSION_NUM 0x080601 +#define LIBCURL_VERSION_NUM 0x080700 /* * This is the date and time when the full source package was created. The From f274fc5c685ac245d1d2818046bbfb4b97685211 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 22 Feb 2024 09:01:06 +0100 Subject: [PATCH 355/509] multi: fix multi_sock handling of select_bits - OR the event bitmask to data->state.select_bits instead of overwriting them. They are cleared again on use. Reported-by: 5533asdg on github Fixes #12971 Closes #12972 --- lib/multi.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/multi.c b/lib/multi.c index 48a92928c8d..6efd164ee29 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -3243,7 +3243,7 @@ static CURLMcode multi_socket(struct Curl_multi *multi, if(data->conn && !(data->conn->handler->flags & PROTOPT_DIRLOCK)) /* set socket event bitmask if they're not locked */ - data->state.select_bits = (unsigned char)ev_bitmask; + data->state.select_bits |= (unsigned char)ev_bitmask; Curl_expire(data, 0, EXPIRE_RUN_NOW); } From 8e83b6b429b9129dd800ac375a6b179b19903bd4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 23 Feb 2024 10:11:11 +0100 Subject: [PATCH 356/509] THANKS: add bug reporter from #740 Ref: https://github.com/curl/curl/issues/740 --- docs/THANKS | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/THANKS b/docs/THANKS index 183836301df..84f3520a37e 100644 --- a/docs/THANKS +++ b/docs/THANKS @@ -47,6 +47,7 @@ ahodesuka on github ajak in #curl Ajit Dhumale Akhil Kedia +Akhilesh Nema Aki Koskinen Akos Pasztory Akshay Vernekar From 8dbc3c7a6bd5288ec1ba873620aafda5e27508f8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Feb 2024 16:34:35 +0100 Subject: [PATCH 357/509] BUG-BOUNTY.md: clarify that the curl security team decides Closes #12975 --- docs/BUG-BOUNTY.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/BUG-BOUNTY.md b/docs/BUG-BOUNTY.md index 3714efda524..f3fc1d82372 100644 --- a/docs/BUG-BOUNTY.md +++ b/docs/BUG-BOUNTY.md @@ -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 From 9b3f67e267d1fa8d7867655d133bdbf8830a0ab3 Mon Sep 17 00:00:00 2001 From: Fabrice Fontaine Date: Thu, 15 Feb 2024 20:59:25 +0100 Subject: [PATCH 358/509] configure.ac: find libpsl with pkg-config Find libpsl with pkg-config to avoid static build failures. Ref: http://autobuild.buildroot.org/results/1fb15e1a99472c403d0d3b1a688902f32e78d002 Signed-off-by: Fabrice Fontaine Closes #12947 --- configure.ac | 79 ++++++++++++++++++++++++++++++++++++++++++++-------- docs/TODO | 7 ----- 2 files changed, 67 insertions(+), 19 deletions(-) diff --git a/configure.ac b/configure.ac index cd0e2d07d8d..09d5364f4de 100644 --- a/configure.ac +++ b/configure.ac @@ -2075,19 +2075,74 @@ dnl ********************************************************************** dnl Check for libpsl dnl ********************************************************************** -AC_ARG_WITH(libpsl, - AS_HELP_STRING([--without-libpsl], - [disable support for libpsl]), - with_libpsl=$withval, - with_libpsl=yes) -curl_psl_msg="no (libpsl disabled)" -if test $with_libpsl != "no"; then - AC_SEARCH_LIBS(psl_builtin, psl, - [curl_psl_msg="enabled"; - AC_DEFINE([USE_LIBPSL], [1], [PSL support enabled]) - ], - [AC_MSG_ERROR([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"]) diff --git a/docs/TODO b/docs/TODO index d2fd42ed969..ee537b913f3 100644 --- a/docs/TODO +++ b/docs/TODO @@ -183,7 +183,6 @@ 19.4 Package curl for Windows in a signed installer 19.5 make configure use --cache-file more and better 19.6 build curl with Windows Unicode support - 19.7 use pkg-config to find libpsl 20. Test suite 20.1 SSL tunnel @@ -1340,12 +1339,6 @@ See https://github.com/curl/curl/issues/7229 -19.7 use pkg-config to find libpsl - - When enabled in configure, libpsl is not found and picked up using details - with pkg-config, thus sometimes missing out on platform specific adjustments. - This should be fixed. - 20. Test suite 20.1 SSL tunnel From 8d4ff40d7b22415d8d5eb0b0a266cad584d5ad99 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 23 Feb 2024 12:52:09 +0100 Subject: [PATCH 359/509] gen: make `\>` in input to render as plain '>' in output Reported-by: Gisle Vanem Fixes #12977 Closes #12978 --- docs/cmdline-opts/config.md | 6 +++--- docs/cmdline-opts/gen.pl | 34 +++++++++++++++++----------------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/cmdline-opts/config.md b/docs/cmdline-opts/config.md index 2f393e27e3b..fa206c43b80 100644 --- a/docs/cmdline-opts/config.md +++ b/docs/cmdline-opts/config.md @@ -28,9 +28,9 @@ 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. +(=), 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. diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index 9b3128444e7..17beab5b8bb 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -262,25 +262,9 @@ sub render { $d =~ s/`%VERSION`/$version/g; $d =~ s/`%GLOBALS`/$globals/g; - # convert single backslahes to doubles - $d =~ s/\\/\\\\/g; - # convert backticks to double quotes $d =~ s/\`/\"/g; - if(!$quote && $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; - } - } - if($d =~ /\(Added in ([0-9.]+)\)/i) { my $ver = $1; if(too_old($ver)) { @@ -300,7 +284,23 @@ sub render { } } # convert backslash-'<' or '> to just the second character - $d =~ s/\\([<<])/$1/g; + $d =~ s/\\([><])/$1/g; + # convert single backslash to double-backslash + $d =~ s/\\/\\\\/g; + + if(!$quote && $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 From d096809394013df674cb8b98aed6b17d47d949ac Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 23 Feb 2024 12:52:59 +0100 Subject: [PATCH 360/509] cd2nroff: gen: make `\>` in input to render as plain '>' in output The same (copy and pasted) fix/mistake as in gen.pl --- scripts/cd2nroff | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/cd2nroff b/scripts/cd2nroff index 02460cc9da5..96d2a367d6f 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -255,7 +255,7 @@ sub single { print STDERR "$f:$line:1:WARN: un-escaped < or > used\n"; } # convert backslash-'<' or '> to just the second character - $d =~ s/\\([<<])/$1/g; + $d =~ s/\\([<>])/$1/g; # mentions of curl symbols with man pages use italics by default $d =~ s/((lib|)curl([^ ]*\(3\)))/\\fI$1\\fP/gi; From e3a3bb371f055ba4272fc1eadd8bc1fb97d3bf14 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Fri, 16 Feb 2024 16:02:19 -0500 Subject: [PATCH 361/509] mprintf: fix format prefix I32/I64 for windows compilers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Support I32 & I64 (eg: %I64d) for all Win32 builds. Prior to this change mprintf support for the I format prefix, which is a Microsoft extension, was dependent on the compiler used. When Borland compiler support was removed in fd7ef00f the prefix was then no longer supported for that compiler; however since it's still possible to build with Borland I'm restoring support for the prefix in this way. Reported-by: Paweł Witas Fixes https://github.com/curl/curl/issues/12944 Closes https://github.com/curl/curl/pull/12950 --- lib/mprintf.c | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/lib/mprintf.c b/lib/mprintf.c index 63f7f2409ec..5695253eb3b 100644 --- a/lib/mprintf.c +++ b/lib/mprintf.c @@ -48,16 +48,6 @@ # endif #endif -/* - * Non-ANSI integer extensions - */ - -#if (defined(_WIN32_WCE)) || \ - (defined(__MINGW32__)) || \ - (defined(_MSC_VER) && (_MSC_VER >= 900) && (_INTEGRAL_MAX_BITS >= 64)) -# define MP_HAVE_INT_EXTENSIONS -#endif - /* * Max integer data types that mprintf.c is capable */ @@ -349,8 +339,9 @@ static int parsefmt(const char *format, case 'h': flags |= FLAGS_SHORT; break; -#if defined(MP_HAVE_INT_EXTENSIONS) +#if defined(_WIN32) || defined(_WIN32_WCE) case 'I': + /* Non-ANSI integer extensions I32 I64 */ if((fmt[0] == '3') && (fmt[1] == '2')) { flags |= FLAGS_LONG; fmt += 2; @@ -367,7 +358,7 @@ static int parsefmt(const char *format, #endif } break; -#endif +#endif /* _WIN32 || _WIN32_WCE */ case 'l': if(flags & FLAGS_LONG) flags |= FLAGS_LONGLONG; From 7448054c38c547af171cb1a8df4c5c08b9d86ae5 Mon Sep 17 00:00:00 2001 From: Scott Talbert Date: Fri, 23 Feb 2024 22:02:09 -0500 Subject: [PATCH 362/509] setopt: fix check for CURLOPT_PROXY_TLSAUTH_TYPE value Prior to this change CURLOPT_PROXY_TLSAUTH_TYPE would return CURLE_BAD_FUNCTION_ARGUMENT on any type other than NULL. Since there is only one type of TLS auth and it is also the default (SRP) the TLS auth would work anyway. Closes https://github.com/curl/curl/pull/12981 --- lib/setopt.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/setopt.c b/lib/setopt.c index e5614cd3514..6a4990cce67 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -2864,13 +2864,13 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) #endif case CURLOPT_TLSAUTH_TYPE: argptr = va_arg(param, char *); - if(argptr && !strncasecompare(argptr, "SRP", strlen("SRP"))) + if(argptr && !strcasecompare(argptr, "SRP")) return CURLE_BAD_FUNCTION_ARGUMENT; break; #ifndef CURL_DISABLE_PROXY case CURLOPT_PROXY_TLSAUTH_TYPE: argptr = va_arg(param, char *); - if(argptr || !strncasecompare(argptr, "SRP", strlen("SRP"))) + if(argptr && !strcasecompare(argptr, "SRP")) return CURLE_BAD_FUNCTION_ARGUMENT; break; #endif From f47487c219978cd9d9db34f7b1669e5e44051af1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 24 Feb 2024 22:38:22 +0100 Subject: [PATCH 363/509] libssh/libssh2: return error on too big range If trying to get the range 0 - 2^63 and the remote file is 2^63 bytes or larger. Fixes #12983 Closes #12984 --- lib/vssh/libssh.c | 2 ++ lib/vssh/libssh2.c | 2 ++ 2 files changed, 4 insertions(+) diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index c6dc63ae66f..02148d0c187 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -1665,6 +1665,8 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) size = 0; } else { + if((to - from) == CURL_OFF_T_MAX) + return CURLE_RANGE_ERROR; size = to - from + 1; } diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index e9dfef950d8..3a661f81eb2 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -2544,6 +2544,8 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) size = 0; } else { + if((to - from) == CURL_OFF_T_MAX) + return CURLE_RANGE_ERROR; size = to - from + 1; } From e2bd0c111e005d0505ab9457837fd370b6e66500 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 25 Feb 2024 22:52:40 +0100 Subject: [PATCH 364/509] strtoofft: fix the overflow check ... to not rely on wrapping, since it is an undefined behavior that is not what always might happen. This is in our private strtoff() parser function, used only on platforms without a native version. Reported-by: vulnerabilityspotter on hackerone Closes #12990 --- lib/strtoofft.c | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/lib/strtoofft.c b/lib/strtoofft.c index 077b25792e0..4a1d6438931 100644 --- a/lib/strtoofft.c +++ b/lib/strtoofft.c @@ -79,11 +79,10 @@ static int get_char(char c, int base); static curl_off_t strtooff(const char *nptr, char **endptr, int base) { char *end; - int is_negative = 0; - int overflow; + bool is_negative = FALSE; + bool overflow = FALSE; int i; curl_off_t value = 0; - curl_off_t newval; /* Skip leading whitespace. */ end = (char *)nptr; @@ -93,7 +92,7 @@ static curl_off_t strtooff(const char *nptr, char **endptr, int base) /* Handle the sign, if any. */ if(end[0] == '-') { - is_negative = 1; + is_negative = TRUE; end++; } else if(end[0] == '+') { @@ -129,19 +128,15 @@ static curl_off_t strtooff(const char *nptr, char **endptr, int base) } /* Loop handling digits. */ - value = 0; - overflow = 0; for(i = get_char(end[0], base); i != -1; end++, i = get_char(end[0], base)) { - newval = base * value + i; - if(newval < value) { - /* We've overflowed. */ - overflow = 1; + + if(value > (CURL_OFF_T_MAX - i) / base) { + overflow = TRUE; break; } - else - value = newval; + value = base * value + i; } if(!overflow) { From e3a4273c419b744316f0a7c97736408d5aa08a27 Mon Sep 17 00:00:00 2001 From: kpcyrd Date: Sun, 25 Feb 2024 21:50:18 +0100 Subject: [PATCH 365/509] rustls: make curl compile with 0.12.0 Closes #12989 --- .github/workflows/linux.yml | 2 +- docs/RUSTLS.md | 4 +-- docs/TODO | 9 ------ lib/vtls/rustls.c | 64 ++++++++++++++++++++++++++----------- 4 files changed, 48 insertions(+), 31 deletions(-) diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index b655c963798..3d447a871bc 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -48,7 +48,7 @@ env: 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: 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/TODO b/docs/TODO index ee537b913f3..f1b3ccd664c 100644 --- a/docs/TODO +++ b/docs/TODO @@ -126,7 +126,6 @@ 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 Support latest rustls 14. GnuTLS 14.2 check connection @@ -923,14 +922,6 @@ https://datatracker.ietf.org/doc/html/rfc7685 https://github.com/curl/curl/issues/2299 -13.15 Support latest rustls - - The rustls backend does not build with the latest rustls-ffi version due to - API changes. Taking this bump should be a first step towards fixing the - remaining issues that still keeps the rustls backend experimental in curl. - - See https://github.com/curl/curl/issues/12737 - 14. GnuTLS 14.2 check connection diff --git a/lib/vtls/rustls.c b/lib/vtls/rustls.c index d58970910c5..485b1d38905 100644 --- a/lib/vtls/rustls.c +++ b/lib/vtls/rustls.c @@ -7,6 +7,7 @@ * * Copyright (C) Jacob Hoffman-Andrews, * + * Copyright (C) kpcyrd, * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms @@ -373,7 +374,10 @@ cr_init_backend(struct Curl_cfilter *cf, struct Curl_easy *data, struct ssl_primary_config *conn_config = Curl_ssl_cf_get_primary_config(cf); struct rustls_connection *rconn = NULL; struct rustls_client_config_builder *config_builder = NULL; - struct rustls_root_cert_store *roots = NULL; + const struct rustls_root_cert_store *roots = NULL; + struct rustls_root_cert_store_builder *roots_builder = NULL; + struct rustls_web_pki_server_cert_verifier_builder *verifier_builder = NULL; + struct rustls_server_cert_verifier *server_cert_verifier = NULL; const struct curl_blob *ca_info_blob = conn_config->ca_info_blob; const char * const ssl_cafile = /* CURLOPT_CAINFO_BLOB overrides CURLOPT_CAINFO */ @@ -414,38 +418,60 @@ cr_init_backend(struct Curl_cfilter *cf, struct Curl_easy *data, hostname = "example.invalid"; } } - else if(ca_info_blob) { - roots = rustls_root_cert_store_new(); - - /* Enable strict parsing only if verification isn't disabled. */ - result = rustls_root_cert_store_add_pem(roots, ca_info_blob->data, - ca_info_blob->len, verifypeer); - if(result != RUSTLS_RESULT_OK) { - failf(data, "rustls: failed to parse trusted certificates from blob"); - rustls_root_cert_store_free(roots); - rustls_client_config_free( - rustls_client_config_builder_build(config_builder)); - return CURLE_SSL_CACERT_BADFILE; + else if(ca_info_blob || ssl_cafile) { + roots_builder = rustls_root_cert_store_builder_new(); + + if(ca_info_blob) { + /* Enable strict parsing only if verification isn't disabled. */ + result = rustls_root_cert_store_builder_add_pem(roots_builder, + ca_info_blob->data, + ca_info_blob->len, + verifypeer); + if(result != RUSTLS_RESULT_OK) { + failf(data, "rustls: failed to parse trusted certificates from blob"); + rustls_root_cert_store_builder_free(roots_builder); + rustls_client_config_free( + rustls_client_config_builder_build(config_builder)); + return CURLE_SSL_CACERT_BADFILE; + } + } + else if(ssl_cafile) { + /* Enable strict parsing only if verification isn't disabled. */ + result = rustls_root_cert_store_builder_load_roots_from_file( + roots_builder, ssl_cafile, verifypeer); + if(result != RUSTLS_RESULT_OK) { + failf(data, "rustls: failed to load trusted certificates"); + rustls_root_cert_store_builder_free(roots_builder); + rustls_client_config_free( + rustls_client_config_builder_build(config_builder)); + return CURLE_SSL_CACERT_BADFILE; + } } - result = rustls_client_config_builder_use_roots(config_builder, roots); - rustls_root_cert_store_free(roots); + result = rustls_root_cert_store_builder_build(roots_builder, &roots); + rustls_root_cert_store_builder_free(roots_builder); if(result != RUSTLS_RESULT_OK) { failf(data, "rustls: failed to load trusted certificates"); rustls_client_config_free( rustls_client_config_builder_build(config_builder)); return CURLE_SSL_CACERT_BADFILE; } - } - else if(ssl_cafile) { - result = rustls_client_config_builder_load_roots_from_file( - config_builder, ssl_cafile); + + verifier_builder = rustls_web_pki_server_cert_verifier_builder_new(roots); + + result = rustls_web_pki_server_cert_verifier_builder_build( + verifier_builder, &server_cert_verifier); + rustls_web_pki_server_cert_verifier_builder_free(verifier_builder); if(result != RUSTLS_RESULT_OK) { failf(data, "rustls: failed to load trusted certificates"); + rustls_server_cert_verifier_free(server_cert_verifier); rustls_client_config_free( rustls_client_config_builder_build(config_builder)); return CURLE_SSL_CACERT_BADFILE; } + + rustls_client_config_builder_set_server_verifier(config_builder, + server_cert_verifier); } backend->config = rustls_client_config_builder_build(config_builder); From e26c3625448af866387057fe7469359c7f19f00c Mon Sep 17 00:00:00 2001 From: MAntoniak <47522782+MAntoniak@users.noreply.github.com> Date: Fri, 9 Feb 2024 18:20:47 +0100 Subject: [PATCH 366/509] lib: remove curl_mimepart object when CURL_DISABLE_MIME Remove curl_mimepart object from UserDefined structure when CURL_DISABLE_MIME flag is active. Reduce size of UserDefined structure. Also remove unreachable code: when CURL_DISABLE_MIME is set, httpreq can never have HTTPREQ_POST_MIME value and the same goes for the CURL_DISABLE_FORM_API flag and the HTTPREQ_POST_FORM value Closes #12948 --- lib/http.c | 5 ++++- lib/imap.c | 8 +++++--- lib/multi.c | 6 +++++- lib/smtp.c | 6 ++++-- lib/url.c | 2 +- lib/urldata.h | 10 ++++++++++ 6 files changed, 29 insertions(+), 8 deletions(-) diff --git a/lib/http.c b/lib/http.c index 679931e4b4a..91520552410 100644 --- a/lib/http.c +++ b/lib/http.c @@ -2344,9 +2344,11 @@ CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, http->postsize = 0; switch(httpreq) { +#ifndef CURL_DISABLE_MIME case HTTPREQ_POST_MIME: data->state.mimepost = &data->set.mimepost; break; +#endif #ifndef CURL_DISABLE_FORM_API case HTTPREQ_POST_FORM: /* Convert the form structure into a mime structure, then keep @@ -2514,6 +2516,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, return result; break; +#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) case HTTPREQ_POST_FORM: case HTTPREQ_POST_MIME: /* This is form posting using mime data. */ @@ -2594,7 +2597,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, return result; break; - +#endif case HTTPREQ_POST: /* this is the simple POST, using x-www-form-urlencoded style */ diff --git a/lib/imap.c b/lib/imap.c index f9211d96629..50849eefc24 100644 --- a/lib/imap.c +++ b/lib/imap.c @@ -770,6 +770,7 @@ static CURLcode imap_perform_append(struct Curl_easy *data) return CURLE_URL_MALFORMAT; } +#ifndef CURL_DISABLE_MIME /* Prepare the mime data if some. */ if(data->set.mimepost.kind != MIMEKIND_NONE) { /* Use the whole structure as data. */ @@ -798,6 +799,7 @@ static CURLcode imap_perform_append(struct Curl_easy *data) data->state.fread_func = (curl_read_callback) Curl_mime_read; data->state.in = (void *) &data->set.mimepost; } +#endif /* Check we know the size of the upload */ if(data->state.infilesize < 0) { @@ -1513,10 +1515,10 @@ static CURLcode imap_done(struct Curl_easy *data, CURLcode status, } else if(!data->set.connect_only && !imap->custom && (imap->uid || imap->mindex || data->state.upload || - data->set.mimepost.kind != MIMEKIND_NONE)) { + IS_MIME_POST(data))) { /* Handle responses after FETCH or APPEND transfer has finished */ - if(!data->state.upload && data->set.mimepost.kind == MIMEKIND_NONE) + if(!data->state.upload && !IS_MIME_POST(data)) imap_state(data, IMAP_FETCH_FINAL); else { /* End the APPEND command first by sending an empty line */ @@ -1582,7 +1584,7 @@ static CURLcode imap_perform(struct Curl_easy *data, bool *connected, selected = TRUE; /* Start the first command in the DO phase */ - if(data->state.upload || data->set.mimepost.kind != MIMEKIND_NONE) + if(data->state.upload || IS_MIME_POST(data)) /* APPEND can be executed directly */ result = imap_perform_append(data); else if(imap->custom && (selected || !imap->mailbox)) diff --git a/lib/multi.c b/lib/multi.c index 6efd164ee29..7f7f1807f6b 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -1812,7 +1812,9 @@ static CURLcode protocol_connect(struct Curl_easy *data, */ static CURLcode readrewind(struct Curl_easy *data) { +#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) curl_mimepart *mimepart = &data->set.mimepost; +#endif DEBUGASSERT(data->conn); data->state.rewindbeforesend = FALSE; /* we rewind now */ @@ -1826,7 +1828,7 @@ static CURLcode readrewind(struct Curl_easy *data) /* We have sent away data. If not using CURLOPT_POSTFIELDS or CURLOPT_HTTPPOST, call app to rewind */ -#ifndef CURL_DISABLE_HTTP +#if !defined(CURL_DISABLE_HTTP) && !defined(CURL_DISABLE_MIME) if(data->conn->handler->protocol & PROTO_FAMILY_HTTP) { if(data->state.mimepost) mimepart = data->state.mimepost; @@ -1836,6 +1838,7 @@ static CURLcode readrewind(struct Curl_easy *data) (data->state.httpreq == HTTPREQ_GET) || (data->state.httpreq == HTTPREQ_HEAD)) ; /* no need to rewind */ +#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) else if(data->state.httpreq == HTTPREQ_POST_MIME || data->state.httpreq == HTTPREQ_POST_FORM) { CURLcode result = Curl_mime_rewind(mimepart); @@ -1844,6 +1847,7 @@ static CURLcode readrewind(struct Curl_easy *data) return result; } } +#endif else { if(data->set.seek_func) { int err; diff --git a/lib/smtp.c b/lib/smtp.c index bfe7b8f1273..0d18afc1c54 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -690,6 +690,7 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) } } +#ifndef CURL_DISABLE_MIME /* Prepare the mime data if some. */ if(data->set.mimepost.kind != MIMEKIND_NONE) { /* Use the whole structure as data. */ @@ -722,6 +723,7 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) data->state.fread_func = (curl_read_callback) Curl_mime_read; data->state.in = (void *) &data->set.mimepost; } +#endif /* Calculate the optional SIZE parameter */ if(conn->proto.smtpc.size_supported && data->state.infilesize > 0) { @@ -1410,7 +1412,7 @@ static CURLcode smtp_done(struct Curl_easy *data, CURLcode status, result = status; /* use the already set error code */ } else if(!data->set.connect_only && data->set.mail_rcpt && - (data->state.upload || data->set.mimepost.kind)) { + (data->state.upload || IS_MIME_POST(data))) { /* Calculate the EOB taking into account any terminating CRLF from the previous line of the email or the CRLF of the DATA command when there is "no mail data". RFC-5321, sect. 4.1.1.4. @@ -1502,7 +1504,7 @@ static CURLcode smtp_perform(struct Curl_easy *data, bool *connected, smtp->eob = 2; /* Start the first command in the DO phase */ - if((data->state.upload || data->set.mimepost.kind) && data->set.mail_rcpt) + if((data->state.upload || IS_MIME_POST(data)) && data->set.mail_rcpt) /* MAIL transfer */ result = smtp_perform_mail(data); else diff --git a/lib/url.c b/lib/url.c index 0f850992723..d6036c533b3 100644 --- a/lib/url.c +++ b/lib/url.c @@ -334,7 +334,7 @@ CURLcode Curl_close(struct Curl_easy **datap) } #endif -#ifndef CURL_DISABLE_HTTP +#if !defined(CURL_DISABLE_HTTP) && !defined(CURL_DISABLE_FORM_API) Curl_mime_cleanpart(data->state.formp); Curl_safefree(data->state.formp); #endif diff --git a/lib/urldata.h b/lib/urldata.h index 5f61f26302b..53d7709525d 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1429,8 +1429,10 @@ struct UrlState { this should be dealt with in pretransfer */ #ifndef CURL_DISABLE_HTTP curl_mimepart *mimepost; +#ifndef CURL_DISABLE_FORM_API curl_mimepart *formp; /* storage for old API form-posting, allocated on demand */ +#endif size_t trailers_bytes_sent; struct dynbuf trailers_buf; /* a buffer containing the compiled trailing headers */ @@ -1731,7 +1733,9 @@ struct UserDefined { curl_off_t set_resume_from; /* continue [ftp] transfer from here */ struct curl_slist *headers; /* linked list of extra headers */ struct curl_httppost *httppost; /* linked list of old POST data */ +#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) curl_mimepart mimepost; /* MIME/POST data. */ +#endif #ifndef CURL_DISABLE_TELNET struct curl_slist *telnet_options; /* linked list of telnet options */ #endif @@ -1944,6 +1948,12 @@ struct UserDefined { #endif }; +#ifndef CURL_DISABLE_MIME +#define IS_MIME_POST(a) ((a)->set.mimepost.kind != MIMEKIND_NONE) +#else +#define IS_MIME_POST(a) FALSE +#endif + struct Names { struct Curl_hash *hostcache; enum { From 5b41fac587b55b489bdf8355306472bf7315ffbc Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 6 Feb 2024 12:10:19 +0100 Subject: [PATCH 367/509] sendf: Curl_client_write(), make passed in buf const --- docs/CLIENT-WRITERS.md | 2 +- lib/sendf.c | 2 +- lib/sendf.h | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CLIENT-WRITERS.md b/docs/CLIENT-WRITERS.md index 7a928826caf..a2a175b72c5 100644 --- a/docs/CLIENT-WRITERS.md +++ b/docs/CLIENT-WRITERS.md @@ -14,7 +14,7 @@ With this naming established, client writers are concerned with writing response 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, char *buf, size_t blen); +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: diff --git a/lib/sendf.c b/lib/sendf.c index 8accc179648..f37cee5d935 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -296,7 +296,7 @@ static CURLcode chop_write(struct Curl_easy *data, The defines are in sendf.h of course. */ CURLcode Curl_client_write(struct Curl_easy *data, - int type, char *buf, size_t blen) + int type, const char *buf, size_t blen) { CURLcode result; diff --git a/lib/sendf.h b/lib/sendf.h index 7deae2ac3ca..4d4f01e4f58 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -55,7 +55,7 @@ * Write `len` bytes at `prt` to the client. `type` indicates what * kind of data is being written. */ -CURLcode Curl_client_write(struct Curl_easy *data, int type, char *ptr, +CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *ptr, size_t len) WARN_UNUSED_RESULT; /** From 2abfa3833b01dd909ab4bd6fbb3d2b54a5e31be7 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 6 Feb 2024 13:55:07 +0100 Subject: [PATCH 368/509] http: move headers collecting to writer - add a client writer that does "push" response headers written to the client if the headers api is enabled - remove special handling in sendf.c - needs to be installed very early on connection setup to catch CONNECT response headers Closes #12880 --- lib/headers.c | 61 ++++++++++++++++++++++++++++++++++++++++++++++++--- lib/headers.h | 7 ++++++ lib/http.c | 8 +++++++ lib/sendf.c | 27 ++++++++++------------- lib/sendf.h | 3 +++ lib/url.c | 3 +++ 6 files changed, 90 insertions(+), 19 deletions(-) diff --git a/lib/headers.c b/lib/headers.c index 8a3264ab566..0c53dec6840 100644 --- a/lib/headers.c +++ b/lib/headers.c @@ -27,6 +27,7 @@ #include "urldata.h" #include "strdup.h" #include "strcase.h" +#include "sendf.h" #include "headers.h" /* The last 3 #include files should be in this order */ @@ -337,14 +338,68 @@ CURLcode Curl_headers_push(struct Curl_easy *data, const char *header, } /* - * Curl_headers_init(). Init the headers subsystem. + * Curl_headers_reset(). Reset the headers subsystem. */ -static void headers_init(struct Curl_easy *data) +static void headers_reset(struct Curl_easy *data) { Curl_llist_init(&data->state.httphdrs, NULL); data->state.prevhead = NULL; } +struct hds_cw_collect_ctx { + struct Curl_cwriter super; +}; + +static CURLcode hds_cw_collect_write(struct Curl_easy *data, + struct Curl_cwriter *writer, int type, + const char *buf, size_t blen) +{ + if((type & CLIENTWRITE_HEADER) && !(type & CLIENTWRITE_STATUS)) { + unsigned char htype = (unsigned char) + (type & CLIENTWRITE_CONNECT ? CURLH_CONNECT : + (type & CLIENTWRITE_1XX ? CURLH_1XX : + (type & CLIENTWRITE_TRAILER ? CURLH_TRAILER : + CURLH_HEADER))); + CURLcode result = Curl_headers_push(data, buf, htype); + if(result) + return result; + } + return Curl_cwriter_write(data, writer->next, type, buf, blen); +} + +static const struct Curl_cwtype hds_cw_collect = { + "hds-collect", + NULL, + Curl_cwriter_def_init, + hds_cw_collect_write, + Curl_cwriter_def_close, + sizeof(struct hds_cw_collect_ctx) +}; + +CURLcode Curl_headers_init(struct Curl_easy *data) +{ + struct Curl_cwriter *writer; + CURLcode result; + + if(data->conn && (data->conn->handler->protocol & PROTO_FAMILY_HTTP)) { + /* avoid installing it twice */ + if(Curl_cwriter_get_by_name(data, hds_cw_collect.name)) + return CURLE_OK; + + result = Curl_cwriter_create(&writer, data, &hds_cw_collect, + CURL_CW_PROTOCOL); + if(result) + return result; + + result = Curl_cwriter_add(data, writer); + if(result) { + Curl_cwriter_free(data, writer); + return result; + } + } + return CURLE_OK; +} + /* * Curl_headers_cleanup(). Free all stored headers and associated memory. */ @@ -358,7 +413,7 @@ CURLcode Curl_headers_cleanup(struct Curl_easy *data) n = e->next; free(hs); } - headers_init(data); + headers_reset(data); return CURLE_OK; } diff --git a/lib/headers.h b/lib/headers.h index a5229ea22f0..d9813388c51 100644 --- a/lib/headers.h +++ b/lib/headers.h @@ -36,6 +36,12 @@ struct Curl_header_store { char buffer[1]; /* this is the raw header blob */ }; +/* + * Initialize header collecting for a transfer. + * Will add a client writer that catches CLIENTWRITE_HEADER writes. + */ +CURLcode Curl_headers_init(struct Curl_easy *data); + /* * Curl_headers_push() gets passed a full header to store. */ @@ -48,6 +54,7 @@ CURLcode Curl_headers_push(struct Curl_easy *data, const char *header, CURLcode Curl_headers_cleanup(struct Curl_easy *data); #else +#define Curl_headers_init(x) CURLE_OK #define Curl_headers_push(x,y,z) CURLE_OK #define Curl_headers_cleanup(x) Curl_nop_stmt #endif diff --git a/lib/http.c b/lib/http.c index 91520552410..5b4814cf8b4 100644 --- a/lib/http.c +++ b/lib/http.c @@ -73,6 +73,7 @@ #include "hostip.h" #include "dynhds.h" #include "http.h" +#include "headers.h" #include "select.h" #include "parsedate.h" /* for the week day and month names */ #include "strtoofft.h" @@ -3131,6 +3132,13 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) break; } + /* Add collecting of headers written to client. For a new connection, + * we might have done that already, but reuse + * or multiplex needs it here as well. */ + result = Curl_headers_init(data); + if(result) + goto fail; + http = data->req.p.http; DEBUGASSERT(http); diff --git a/lib/sendf.c b/lib/sendf.c index f37cee5d935..6c575083c3e 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -49,7 +49,6 @@ #include "select.h" #include "strdup.h" #include "http2.h" -#include "headers.h" #include "progress.h" #include "ws.h" @@ -256,21 +255,6 @@ static CURLcode chop_write(struct Curl_easy *data, len -= chunklen; } -#if !defined(CURL_DISABLE_HTTP) && !defined(CURL_DISABLE_HEADERS_API) - /* HTTP header, but not status-line */ - if((conn->handler->protocol & PROTO_FAMILY_HTTP) && - (type & CLIENTWRITE_HEADER) && !(type & CLIENTWRITE_STATUS) ) { - unsigned char htype = (unsigned char) - (type & CLIENTWRITE_CONNECT ? CURLH_CONNECT : - (type & CLIENTWRITE_1XX ? CURLH_1XX : - (type & CLIENTWRITE_TRAILER ? CURLH_TRAILER : - CURLH_HEADER))); - CURLcode result = Curl_headers_push(data, optr, htype); - if(result) - return result; - } -#endif - if(writeheader) { size_t wrote; @@ -674,6 +658,17 @@ CURLcode Curl_cwriter_add(struct Curl_easy *data, return CURLE_OK; } +struct Curl_cwriter *Curl_cwriter_get_by_name(struct Curl_easy *data, + const char *name) +{ + struct Curl_cwriter *writer; + for(writer = data->req.writer_stack; writer; writer = writer->next) { + if(!strcmp(name, writer->cwt->name)) + return writer; + } + return NULL; +} + void Curl_cwriter_remove_by_name(struct Curl_easy *data, const char *name) { diff --git a/lib/sendf.h b/lib/sendf.h index 4d4f01e4f58..1a4a68d8ea0 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -151,6 +151,9 @@ CURLcode Curl_cwriter_add(struct Curl_easy *data, void Curl_cwriter_remove_by_name(struct Curl_easy *data, const char *name); +struct Curl_cwriter *Curl_cwriter_get_by_name(struct Curl_easy *data, + const char *name); + /** * Convenience method for calling `writer->do_write()` that * checks for NULL writer. diff --git a/lib/url.c b/lib/url.c index d6036c533b3..21bd66b45e0 100644 --- a/lib/url.c +++ b/lib/url.c @@ -3848,6 +3848,9 @@ CURLcode Curl_setup_conn(struct Curl_easy *data, if(!conn->bits.reuse) result = Curl_conn_setup(data, conn, FIRSTSOCKET, conn->dns_entry, CURL_CF_SSL_DEFAULT); + if(!result) + result = Curl_headers_init(data); + /* not sure we need this flag to be passed around any more */ *protocol_done = FALSE; return result; From e925d0d1ff1df3764fc332853970f01ce9961dfc Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 6 Feb 2024 14:56:05 +0100 Subject: [PATCH 369/509] c-hyper: add header collection writer in hyper builds Closes #12880 --- lib/c-hyper.c | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index d02ecd73a7b..845c179392a 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -54,6 +54,7 @@ #include #include "urldata.h" #include "sendf.h" +#include "headers.h" #include "transfer.h" #include "multiif.h" #include "progress.h" @@ -887,6 +888,13 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) *done = TRUE; Curl_client_cleanup(data); + /* Add collecting of headers written to client. For a new connection, + * we might have done that already, but reuse + * or multiplex needs it here as well. */ + result = Curl_headers_init(data); + if(result) + return result; + infof(data, "Time for the Hyper dance"); memset(h, 0, sizeof(struct hyptransfer)); From 225455140310d1309f802dd8a6534e9cad71b137 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 16 Feb 2024 12:15:10 +0100 Subject: [PATCH 370/509] urldata: move authneg bit from conn to Curl_easy - from `conn->bits.authneg` to `data->req.authneg` - this is a property of the request about to be made and not a property of the connection - in multiuse connections, transfer could step on each others toes here potentially. Closes #12949 --- lib/c-hyper.c | 5 ++--- lib/http.c | 38 +++++++++++++++++++------------------- lib/urldata.h | 8 ++++---- 3 files changed, 25 insertions(+), 26 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index 845c179392a..f07dd6c0b19 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -696,7 +696,6 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, { size_t fillcount; struct Curl_easy *data = (struct Curl_easy *)userdata; - struct connectdata *conn = (struct connectdata *)data->conn; CURLcode result; (void)ctx; @@ -711,7 +710,7 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, return HYPER_POLL_PENDING; } - if(data->req.upload_chunky && conn->bits.authneg) { + if(data->req.upload_chunky && data->req.authneg) { fillcount = 0; data->req.upload_chunky = FALSE; result = CURLE_OK; @@ -1174,7 +1173,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) Curl_debug(data, CURLINFO_HEADER_OUT, (char *)"\r\n", 2); - if(data->req.upload_chunky && conn->bits.authneg) { + if(data->req.upload_chunky && data->req.authneg) { data->req.upload_chunky = TRUE; } else { diff --git a/lib/http.c b/lib/http.c index 5b4814cf8b4..dd1fc4ffa0e 100644 --- a/lib/http.c +++ b/lib/http.c @@ -447,7 +447,7 @@ static CURLcode http_perhapsrewind(struct Curl_easy *data, bytessent = data->req.writebytecount; - if(conn->bits.authneg) { + if(data->req.authneg) { /* This is a state where we are known to be negotiating and we don't send any data then. */ expectsend = 0; @@ -489,7 +489,7 @@ static CURLcode http_perhapsrewind(struct Curl_easy *data, data left to send, keep on sending. */ /* rewind data when completely done sending! */ - if(!conn->bits.authneg && (conn->writesockfd != CURL_SOCKET_BAD)) { + if(!data->req.authneg && (conn->writesockfd != CURL_SOCKET_BAD)) { data->state.rewindbeforesend = TRUE; infof(data, "Rewind stream before next send"); } @@ -517,7 +517,7 @@ static CURLcode http_perhapsrewind(struct Curl_easy *data, there is just a little (<2K) data left to send, keep on sending. */ /* rewind data when completely done sending! */ - if(!conn->bits.authneg && (conn->writesockfd != CURL_SOCKET_BAD)) { + if(!data->req.authneg && (conn->writesockfd != CURL_SOCKET_BAD)) { data->state.rewindbeforesend = TRUE; infof(data, "Rewind stream before next send"); } @@ -579,7 +579,7 @@ CURLcode Curl_http_auth_act(struct Curl_easy *data) if((data->state.aptr.user || data->set.str[STRING_BEARER]) && ((data->req.httpcode == 401) || - (conn->bits.authneg && data->req.httpcode < 300))) { + (data->req.authneg && data->req.httpcode < 300))) { pickhost = pickoneauth(&data->state.authhost, authmask); if(!pickhost) data->state.authproblem = TRUE; @@ -593,7 +593,7 @@ CURLcode Curl_http_auth_act(struct Curl_easy *data) #ifndef CURL_DISABLE_PROXY if(conn->bits.proxy_user_passwd && ((data->req.httpcode == 407) || - (conn->bits.authneg && data->req.httpcode < 300))) { + (data->req.authneg && data->req.httpcode < 300))) { pickproxy = pickoneauth(&data->state.authproxy, authmask & ~CURLAUTH_BEARER); if(!pickproxy) @@ -619,7 +619,7 @@ CURLcode Curl_http_auth_act(struct Curl_easy *data) } else if((data->req.httpcode < 300) && (!data->state.authhost.done) && - conn->bits.authneg) { + data->req.authneg) { /* no (known) authentication available, authentication is not "done" yet and no authentication seems to be required and @@ -864,10 +864,10 @@ Curl_http_output_auth(struct Curl_easy *data, (httpreq != HTTPREQ_HEAD)) { /* Auth is required and we are not authenticated yet. Make a PUT or POST with content-length zero as a "probe". */ - conn->bits.authneg = TRUE; + data->req.authneg = TRUE; } else - conn->bits.authneg = FALSE; + data->req.authneg = FALSE; return result; } @@ -1809,7 +1809,7 @@ CURLcode Curl_dynhds_add_custom(struct Curl_easy *data, /* this header is sent later */ hd_name_eq(name, namelen, STRCONST("Content-Type:"))) ; - else if(conn->bits.authneg && + else if(data->req.authneg && /* while doing auth neg, don't allow the custom length since we will force length zero then */ hd_name_eq(name, namelen, STRCONST("Content-Length:"))) @@ -1955,7 +1955,7 @@ CURLcode Curl_add_custom_headers(struct Curl_easy *data, /* this header is sent later */ checkprefix("Content-Type:", compare)) ; - else if(conn->bits.authneg && + else if(data->req.authneg && /* while doing auth neg, don't allow the custom length since we will force length zero then */ checkprefix("Content-Length:", compare)) @@ -2413,7 +2413,7 @@ CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, http->postsize < 0) || ((data->state.upload || httpreq == HTTPREQ_POST) && data->state.infilesize == -1))) { - if(conn->bits.authneg) + if(data->req.authneg) /* don't enable chunked during auth neg */ ; else if(Curl_use_http_1_1plus(data, conn)) { @@ -2476,13 +2476,13 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, switch(httpreq) { case HTTPREQ_PUT: /* Let's PUT the data to the server! */ - if(conn->bits.authneg) + if(data->req.authneg) http->postsize = 0; else http->postsize = data->state.infilesize; if((http->postsize != -1) && !data->req.upload_chunky && - (conn->bits.authneg || + (data->req.authneg || !Curl_checkheaders(data, STRCONST("Content-Length")))) { /* only add Content-Length if not uploading chunked */ result = Curl_dyn_addf(r, "Content-Length: %" CURL_FORMAT_CURL_OFF_T @@ -2521,7 +2521,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, case HTTPREQ_POST_FORM: case HTTPREQ_POST_MIME: /* This is form posting using mime data. */ - if(conn->bits.authneg) { + if(data->req.authneg) { /* nothing to post! */ result = Curl_dyn_addn(r, STRCONST("Content-Length: 0\r\n\r\n")); if(result) @@ -2602,7 +2602,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, case HTTPREQ_POST: /* this is the simple POST, using x-www-form-urlencoded style */ - if(conn->bits.authneg) + if(data->req.authneg) http->postsize = 0; else /* the size of the post body */ @@ -2612,7 +2612,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, we don't upload data chunked, as RFC2616 forbids us to set both kinds of headers (Transfer-Encoding: chunked and Content-Length) */ if((http->postsize != -1) && !data->req.upload_chunky && - (conn->bits.authneg || + (data->req.authneg || !Curl_checkheaders(data, STRCONST("Content-Length")))) { /* we allow replacing this header if not during auth negotiation, although it isn't very wise to actually set your own */ @@ -2708,7 +2708,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, if(result) return result; - if(data->req.upload_chunky && conn->bits.authneg) { + if(data->req.upload_chunky && data->req.authneg) { /* Chunky upload is selected and we're negotiating auth still, send end-of-data only */ result = Curl_dyn_addn(r, (char *)STRCONST("\x30\x0d\x0a\x0d\x0a")); @@ -2723,7 +2723,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, /* set the pointer to mark that we will send the post body using the read callback, but only if we're not in authenticate negotiation */ - if(!conn->bits.authneg) + if(!data->req.authneg) http->postdata = (char *)&http->postdata; } } @@ -4199,7 +4199,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, return result; if(k->httpcode >= 300) { - if((!conn->bits.authneg) && !conn->bits.close && + if((!data->req.authneg) && !conn->bits.close && !data->state.rewindbeforesend) { /* * General treatment of errors when about to send data. Including : diff --git a/lib/urldata.h b/lib/urldata.h index 53d7709525d..9955ab5ce03 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -527,10 +527,6 @@ struct ConnectBits { the TCP layer connect */ BIT(retry); /* this connection is about to get closed and then re-attempted at another connection. */ - BIT(authneg); /* TRUE when the auth phase has started, which means - that we are creating a request with an auth header, - but it is not the final request in the auth - negotiation. */ #ifndef CURL_DISABLE_FTP BIT(ftp_use_epsv); /* As set with CURLOPT_FTP_USE_EPSV, but if we find out EPSV doesn't work we disable it for the forthcoming @@ -753,6 +749,10 @@ struct SingleRequest { specific upload buffers. See readmoredata() in http.c for details. */ BIT(no_body); /* the response has no body */ + BIT(authneg); /* TRUE when the auth phase has started, which means + that we are creating a request with an auth header, + but it is not the final request in the auth + negotiation. */ }; /* From 463472a2d6e3301c1468b5323b856cb67a91f579 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 7 Feb 2024 12:05:05 +0100 Subject: [PATCH 371/509] lib: move client writer into own source Refactoring of the client writer that passes the data to the client/application's callback functions. - split out into own source cw-out.[ch] from sendf.c - move tempwrite and tempcount from data->state into the context of the client writer - redesign the 3 tempwrite dynbufs as a linked list of dynbufs. On paused transfers, this allows to "record" interleaved HEADER/BODY chunks to be "played back" in the same order on unpausing. - keep the overall size limit of all buffered data to DYN_PAUSE_BUFFER. On exceeding that, return CURLE_TOO_LARGE instead of CURLE_OUT_OF_MEMORY as before. - add method to be called when a transfer is DONE to allow writing of any data still buffered - when paused, record HEADER writes exactly as they come for later playback. HEADERs are documented to be written one-by-one. Closes #12898 --- lib/Makefile.inc | 2 + lib/cw-out.c | 437 +++++++++++++++++++++++++++++++++++++++++++++++ lib/cw-out.h | 53 ++++++ lib/easy.c | 5 +- lib/multi.c | 7 +- lib/sendf.c | 220 ++---------------------- lib/sendf.h | 14 +- lib/transfer.c | 7 + lib/transfer.h | 6 + lib/urldata.h | 14 -- 10 files changed, 538 insertions(+), 227 deletions(-) create mode 100644 lib/cw-out.c create mode 100644 lib/cw-out.h diff --git a/lib/Makefile.inc b/lib/Makefile.inc index fc437ee9028..ef3f8a0addc 100644 --- a/lib/Makefile.inc +++ b/lib/Makefile.inc @@ -138,6 +138,7 @@ LIB_CFILES = \ curl_sspi.c \ curl_threads.c \ curl_trc.c \ + cw-out.c \ dict.c \ doh.c \ dynbuf.c \ @@ -283,6 +284,7 @@ LIB_HFILES = \ curl_threads.h \ curl_trc.h \ curlx.h \ + cw-out.h \ dict.h \ doh.h \ dynbuf.h \ diff --git a/lib/cw-out.c b/lib/cw-out.c new file mode 100644 index 00000000000..b29b45665a8 --- /dev/null +++ b/lib/cw-out.c @@ -0,0 +1,437 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +#include "curl_setup.h" + +#include + +#include "urldata.h" +#include "cfilters.h" +#include "headers.h" +#include "multiif.h" +#include "sendf.h" +#include "cw-out.h" + +/* The last 3 #include files should be in this order */ +#include "curl_printf.h" +#include "curl_memory.h" +#include "memdebug.h" + + +/** + * OVERALL DESIGN of this client writer + * + * The 'cw-out' writer is supposed to be the last writer in a transfer's + * stack. It is always added when that stack is initialized. Its purpose + * is to pass BODY and HEADER bytes to the client-installed callback + * functions. + * + * These callback may return `CURL_WRITEFUNC_PAUSE` to indicate that the + * data had not been written and the whole transfer should stop receiving + * new data. Or at least, stop calling the functions. When the transfer + * is "unpaused" by the client, the previous data shall be passed as + * if nothing happened. + * + * The `cw-out` writer therefore manages buffers for bytes that could + * not be written. Data that was already in flight from the server also + * needs buffering on paused transfer when it arrives. + * + * In addition, the writer allows buffering of "small" body writes, + * so client functions are called less often. That is only enabled on a + * number of conditions. + * + * HEADER and BODY data may arrive in any order. For paused transfers, + * a list of `struct cw_out_buf` is kept for `cw_out_type` types. The + * list may be: [BODY]->[HEADER]->[BODY]->[HEADER].... + * When unpausing, this list is "played back" to the client callbacks. + * + * The amount of bytes being buffered is limited by `DYN_PAUSE_BUFFER` + * and when that is exceeded `CURLE_TOO_LARGE` is returned as error. + */ +typedef enum { + CW_OUT_NONE, + CW_OUT_BODY, + CW_OUT_HDS +} cw_out_type; + +struct cw_out_buf { + struct cw_out_buf *next; + struct dynbuf b; + cw_out_type type; +}; + +static struct cw_out_buf *cw_out_buf_create(cw_out_type otype) +{ + struct cw_out_buf *cwbuf = calloc(1, sizeof(*cwbuf)); + if(cwbuf) { + cwbuf->type = otype; + Curl_dyn_init(&cwbuf->b, DYN_PAUSE_BUFFER); + } + return cwbuf; +} + +static void cw_out_buf_free(struct cw_out_buf *cwbuf) +{ + if(cwbuf) { + Curl_dyn_free(&cwbuf->b); + free(cwbuf); + } +} + +struct cw_out_ctx { + struct Curl_cwriter super; + struct cw_out_buf *buf; +}; + +static CURLcode cw_out_write(struct Curl_easy *data, + struct Curl_cwriter *writer, int type, + const char *buf, size_t nbytes); +static void cw_out_close(struct Curl_easy *data, struct Curl_cwriter *writer); +static CURLcode cw_out_init(struct Curl_easy *data, + struct Curl_cwriter *writer); + +struct Curl_cwtype Curl_cwt_out = { + "cw-out", + NULL, + cw_out_init, + cw_out_write, + cw_out_close, + sizeof(struct cw_out_ctx) +}; + +static CURLcode cw_out_init(struct Curl_easy *data, + struct Curl_cwriter *writer) +{ + struct cw_out_ctx *ctx = (struct cw_out_ctx *)writer; + (void)data; + ctx->buf = NULL; + return CURLE_OK; +} + +static void cw_out_bufs_free(struct cw_out_ctx *ctx) +{ + while(ctx->buf) { + struct cw_out_buf *next = ctx->buf->next; + cw_out_buf_free(ctx->buf); + ctx->buf = next; + } +} + +static size_t cw_out_bufs_len(struct cw_out_ctx *ctx) +{ + struct cw_out_buf *cwbuf = ctx->buf; + size_t len = 0; + while(cwbuf) { + len += Curl_dyn_len(&cwbuf->b); + cwbuf = cwbuf->next; + } + return len; +} + +static void cw_out_close(struct Curl_easy *data, struct Curl_cwriter *writer) +{ + struct cw_out_ctx *ctx = (struct cw_out_ctx *)writer; + + (void)data; + cw_out_bufs_free(ctx); +} + +/** + * Return the current curl_write_callback and user_data for the buf type + */ +static void cw_get_writefunc(struct Curl_easy *data, cw_out_type otype, + curl_write_callback *pwcb, void **pwcb_data, + size_t *pmax_write, size_t *pmin_write) +{ + switch(otype) { + case CW_OUT_BODY: + *pwcb = data->set.fwrite_func; + *pwcb_data = data->set.out; + *pmax_write = CURL_MAX_WRITE_SIZE; + /* if we ever want buffering of BODY output, we can set `min_write` + * the preferred size. The default should always be to pass data + * to the client as it comes without delay */ + *pmin_write = 0; + break; + case CW_OUT_HDS: + *pwcb = data->set.fwrite_header? data->set.fwrite_header : + (data->set.writeheader? data->set.fwrite_func : NULL); + *pwcb_data = data->set.writeheader; + *pmax_write = 0; /* do not chunk-write headers, write them as they are */ + *pmin_write = 0; + break; + default: + *pwcb = NULL; + *pwcb_data = NULL; + *pmax_write = CURL_MAX_WRITE_SIZE; + *pmin_write = 0; + } +} + +static CURLcode cw_out_ptr_flush(struct cw_out_ctx *ctx, + struct Curl_easy *data, + cw_out_type otype, + bool flush_all, + const char *buf, size_t blen, + size_t *pconsumed) +{ + curl_write_callback wcb; + void *wcb_data; + size_t max_write, min_write; + size_t wlen, nwritten; + + (void)ctx; + /* write callbacks may get NULLed by the client between calls. */ + cw_get_writefunc(data, otype, &wcb, &wcb_data, &max_write, &min_write); + if(!wcb) { + *pconsumed = blen; + return CURLE_OK; + } + + *pconsumed = 0; + while(blen && !(data->req.keepon & KEEP_RECV_PAUSE)) { + if(!flush_all && blen < min_write) + break; + wlen = max_write? CURLMIN(blen, max_write) : blen; + Curl_set_in_callback(data, TRUE); + nwritten = wcb((char *)buf, 1, wlen, wcb_data); + Curl_set_in_callback(data, FALSE); + if(CURL_WRITEFUNC_PAUSE == nwritten) { + if(data->conn && data->conn->handler->flags & PROTOPT_NONETWORK) { + /* Protocols that work without network cannot be paused. This is + actually only FILE:// just now, and it can't pause since the + transfer isn't done using the "normal" procedure. */ + failf(data, "Write callback asked for PAUSE when not supported"); + return CURLE_WRITE_ERROR; + } + /* mark the connection as RECV paused */ + data->req.keepon |= KEEP_RECV_PAUSE; + break; + } + if(nwritten != wlen) { + failf(data, "Failure writing output to destination, " + "passed %zu returned %zu", wlen, nwritten); + return CURLE_WRITE_ERROR; + } + *pconsumed += nwritten; + blen -= nwritten; + buf += nwritten; + } + return CURLE_OK; +} + +static CURLcode cw_out_buf_flush(struct cw_out_ctx *ctx, + struct Curl_easy *data, + struct cw_out_buf *cwbuf, + bool flush_all) +{ + CURLcode result = CURLE_OK; + + if(Curl_dyn_len(&cwbuf->b)) { + size_t consumed; + + result = cw_out_ptr_flush(ctx, data, cwbuf->type, flush_all, + Curl_dyn_ptr(&cwbuf->b), + Curl_dyn_len(&cwbuf->b), + &consumed); + if(result) + return result; + + if(consumed) { + if(consumed == Curl_dyn_len(&cwbuf->b)) { + Curl_dyn_free(&cwbuf->b); + } + else { + DEBUGASSERT(consumed < Curl_dyn_len(&cwbuf->b)); + result = Curl_dyn_tail(&cwbuf->b, Curl_dyn_len(&cwbuf->b) - consumed); + if(result) + return result; + } + } + } + return result; +} + +static CURLcode cw_out_flush_chain(struct cw_out_ctx *ctx, + struct Curl_easy *data, + struct cw_out_buf **pcwbuf, + bool flush_all) +{ + struct cw_out_buf *cwbuf = *pcwbuf; + CURLcode result; + + if(!cwbuf) + return CURLE_OK; + if(data->req.keepon & KEEP_RECV_PAUSE) + return CURLE_OK; + + /* write the end of the chain until it blocks or gets empty */ + while(cwbuf->next) { + struct cw_out_buf **plast = &cwbuf->next; + while((*plast)->next) + plast = &(*plast)->next; + result = cw_out_flush_chain(ctx, data, plast, flush_all); + if(result) + return result; + if(*plast) { + /* could not write last, paused again? */ + DEBUGASSERT(data->req.keepon & KEEP_RECV_PAUSE); + return CURLE_OK; + } + } + + result = cw_out_buf_flush(ctx, data, cwbuf, flush_all); + if(result) + return result; + if(!Curl_dyn_len(&cwbuf->b)) { + cw_out_buf_free(cwbuf); + *pcwbuf = NULL; + } + return CURLE_OK; +} + +static CURLcode cw_out_append(struct cw_out_ctx *ctx, + cw_out_type otype, + const char *buf, size_t blen) +{ + if(cw_out_bufs_len(ctx) + blen > DYN_PAUSE_BUFFER) + return CURLE_TOO_LARGE; + + /* if we do not have a buffer, or it is of another type, make a new one. + * And for CW_OUT_HDS always make a new one, so we "replay" headers + * exactly as they came in */ + if(!ctx->buf || (ctx->buf->type != otype) || (otype == CW_OUT_HDS)) { + struct cw_out_buf *cwbuf = cw_out_buf_create(otype); + if(!cwbuf) + return CURLE_OUT_OF_MEMORY; + cwbuf->next = ctx->buf; + ctx->buf = cwbuf; + } + DEBUGASSERT(ctx->buf && (ctx->buf->type == otype)); + return Curl_dyn_addn(&ctx->buf->b, buf, blen); +} + +static CURLcode cw_out_do_write(struct cw_out_ctx *ctx, + struct Curl_easy *data, + cw_out_type otype, + bool flush_all, + const char *buf, size_t blen) +{ + CURLcode result; + + /* if we have buffered data and it is a different type than what + * we are writing now, try to flush all */ + if(ctx->buf && ctx->buf->type != otype) { + result = cw_out_flush_chain(ctx, data, &ctx->buf, TRUE); + if(result) + return result; + } + + if(ctx->buf) { + /* still have buffered data, append and flush */ + result = cw_out_append(ctx, otype, buf, blen); + if(result) + return result; + result = cw_out_flush_chain(ctx, data, &ctx->buf, flush_all); + if(result) + return result; + } + else { + /* nothing buffered, try direct write */ + size_t consumed; + result = cw_out_ptr_flush(ctx, data, otype, flush_all, + buf, blen, &consumed); + if(result) + return result; + if(consumed < blen) { + /* did not write all, append the rest */ + result = cw_out_append(ctx, otype, buf + consumed, blen - consumed); + if(result) + return result; + } + } + return CURLE_OK; +} + +static CURLcode cw_out_write(struct Curl_easy *data, + struct Curl_cwriter *writer, int type, + const char *buf, size_t blen) +{ + struct cw_out_ctx *ctx = (struct cw_out_ctx *)writer; + CURLcode result; + bool flush_all; + + flush_all = (type & CLIENTWRITE_EOS)? TRUE:FALSE; + if((type & CLIENTWRITE_BODY) || + ((type & CLIENTWRITE_HEADER) && data->set.include_header)) { + result = cw_out_do_write(ctx, data, CW_OUT_BODY, flush_all, buf, blen); + if(result) + return result; + } + + if(type & (CLIENTWRITE_HEADER|CLIENTWRITE_INFO)) { + result = cw_out_do_write(ctx, data, CW_OUT_HDS, flush_all, buf, blen); + if(result) + return result; + } + + return CURLE_OK; +} + +bool Curl_cw_out_is_paused(struct Curl_easy *data) +{ + struct Curl_cwriter *cw_out; + struct cw_out_ctx *ctx; + + cw_out = Curl_cwriter_get_by_type(data, &Curl_cwt_out); + if(!cw_out) + return FALSE; + + ctx = (struct cw_out_ctx *)cw_out; + return cw_out_bufs_len(ctx) > 0; +} + +static CURLcode cw_out_flush(struct Curl_easy *data, bool flush_all) +{ + struct Curl_cwriter *cw_out; + CURLcode result = CURLE_OK; + + cw_out = Curl_cwriter_get_by_type(data, &Curl_cwt_out); + if(cw_out) { + struct cw_out_ctx *ctx = (struct cw_out_ctx *)cw_out; + + result = cw_out_flush_chain(ctx, data, &ctx->buf, flush_all); + } + return result; +} + +CURLcode Curl_cw_out_flush(struct Curl_easy *data) +{ + return cw_out_flush(data, FALSE); +} + +CURLcode Curl_cw_out_done(struct Curl_easy *data) +{ + return cw_out_flush(data, TRUE); +} diff --git a/lib/cw-out.h b/lib/cw-out.h new file mode 100644 index 00000000000..c13e85380b7 --- /dev/null +++ b/lib/cw-out.h @@ -0,0 +1,53 @@ +#ifndef HEADER_CURL_CW_OUT_H +#define HEADER_CURL_CW_OUT_H +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +#include "curl_setup.h" + +#include "sendf.h" + +/** + * The client writer type "cw-out" that does the actual writing to + * the client callbacks. Intended to be the last installed in the + * client writer stack of a transfer. + */ +extern struct Curl_cwtype Curl_cwt_out; + +/** + * Return TRUE iff 'cw-out' client write has paused data. + */ +bool Curl_cw_out_is_paused(struct Curl_easy *data); + +/** + * Flush any buffered date to the client, chunk collation still applies. + */ +CURLcode Curl_cw_out_flush(struct Curl_easy *data); + +/** + * Mark EndOfStream reached and flush ALL data to the client. + */ +CURLcode Curl_cw_out_done(struct Curl_easy *data); + +#endif /* HEADER_CURL_CW_OUT_H */ diff --git a/lib/easy.c b/lib/easy.c index 763d43b9259..b2a66ad0fab 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -58,6 +58,7 @@ #include "multiif.h" #include "select.h" #include "cfilters.h" +#include "cw-out.h" #include "sendf.h" /* for failf function prototype */ #include "connect.h" /* for Curl_getconnectinfo */ #include "slist.h" @@ -1117,7 +1118,7 @@ CURLcode curl_easy_pause(struct Curl_easy *data, int action) if(!(newstate & KEEP_RECV_PAUSE)) { Curl_conn_ev_data_pause(data, FALSE); - result = Curl_client_unpause(data); + result = Curl_cw_out_flush(data); if(result) return result; } @@ -1141,7 +1142,7 @@ CURLcode curl_easy_pause(struct Curl_easy *data, int action) /* reset the too-slow time keeper */ data->state.keeps_speed.tv_sec = 0; - if(!data->state.tempcount) + if(!Curl_cw_out_is_paused(data)) /* if not pausing again, force a recv/send check of this connection as the data might've been read off the socket already */ data->state.select_bits = CURL_CSELECT_IN | CURL_CSELECT_OUT; diff --git a/lib/multi.c b/lib/multi.c index 7f7f1807f6b..1c8c362f18a 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -645,7 +645,7 @@ static CURLcode multi_done(struct Curl_easy *data, after an error was detected */ bool premature) { - CURLcode result; + CURLcode result, r2; struct connectdata *conn = data->conn; #if defined(DEBUGBUILD) && !defined(CURL_DISABLE_VERBOSE_STRINGS) @@ -696,6 +696,11 @@ static CURLcode multi_done(struct Curl_easy *data, result = CURLE_ABORTED_BY_CALLBACK; } + /* Make sure that transfer client writes are really done now. */ + r2 = Curl_xfer_write_done(data, premature); + if(r2 && !result) + result = r2; + /* Inform connection filters that this transfer is done */ Curl_conn_ev_data_done(data, premature); diff --git a/lib/sendf.c b/lib/sendf.c index 6c575083c3e..053d74a10c2 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -41,6 +41,7 @@ #include "cfilters.h" #include "connect.h" #include "content_encoding.h" +#include "cw-out.h" #include "vtls/vtls.h" #include "vssh/ssh.h" #include "easyif.h" @@ -133,147 +134,6 @@ CURLcode Curl_write(struct Curl_easy *data, return Curl_nwrite(data, num, mem, len, written); } -static CURLcode pausewrite(struct Curl_easy *data, - int type, /* what type of data */ - bool paused_body, - const char *ptr, - size_t len) -{ - /* signalled to pause sending on this connection, but since we have data - we want to send we need to dup it to save a copy for when the sending - is again enabled */ - struct SingleRequest *k = &data->req; - struct UrlState *s = &data->state; - unsigned int i; - bool newtype = TRUE; - - Curl_conn_ev_data_pause(data, TRUE); - - if(s->tempcount) { - for(i = 0; i< s->tempcount; i++) { - if(s->tempwrite[i].type == type && - !!s->tempwrite[i].paused_body == !!paused_body) { - /* data for this type exists */ - newtype = FALSE; - break; - } - } - DEBUGASSERT(i < 3); - if(i >= 3) - /* There are more types to store than what fits: very bad */ - return CURLE_OUT_OF_MEMORY; - } - else - i = 0; - - if(newtype) { - /* store this information in the state struct for later use */ - Curl_dyn_init(&s->tempwrite[i].b, DYN_PAUSE_BUFFER); - s->tempwrite[i].type = type; - s->tempwrite[i].paused_body = paused_body; - s->tempcount++; - } - - if(Curl_dyn_addn(&s->tempwrite[i].b, (unsigned char *)ptr, len)) - return CURLE_OUT_OF_MEMORY; - - /* mark the connection as RECV paused */ - k->keepon |= KEEP_RECV_PAUSE; - - return CURLE_OK; -} - - -/* chop_write() writes chunks of data not larger than CURL_MAX_WRITE_SIZE via - * client write callback(s) and takes care of pause requests from the - * callbacks. - */ -static CURLcode chop_write(struct Curl_easy *data, - int type, - bool skip_body_write, - char *optr, - size_t olen) -{ - struct connectdata *conn = data->conn; - curl_write_callback writeheader = NULL; - curl_write_callback writebody = NULL; - char *ptr = optr; - size_t len = olen; - void *writebody_ptr = data->set.out; - - if(!len) - return CURLE_OK; - - /* If reading is paused, append this data to the already held data for this - type. */ - if(data->req.keepon & KEEP_RECV_PAUSE) - return pausewrite(data, type, !skip_body_write, ptr, len); - - /* Determine the callback(s) to use. */ - if(!skip_body_write && - ((type & CLIENTWRITE_BODY) || - ((type & CLIENTWRITE_HEADER) && data->set.include_header))) { - writebody = data->set.fwrite_func; - } - if((type & (CLIENTWRITE_HEADER|CLIENTWRITE_INFO)) && - (data->set.fwrite_header || data->set.writeheader)) { - /* - * Write headers to the same callback or to the especially setup - * header callback function (added after version 7.7.1). - */ - writeheader = - data->set.fwrite_header? data->set.fwrite_header: data->set.fwrite_func; - } - - /* Chop data, write chunks. */ - while(len) { - size_t chunklen = len <= CURL_MAX_WRITE_SIZE? len: CURL_MAX_WRITE_SIZE; - - if(writebody) { - size_t wrote; - Curl_set_in_callback(data, true); - wrote = writebody(ptr, 1, chunklen, writebody_ptr); - Curl_set_in_callback(data, false); - - if(CURL_WRITEFUNC_PAUSE == wrote) { - if(conn->handler->flags & PROTOPT_NONETWORK) { - /* Protocols that work without network cannot be paused. This is - actually only FILE:// just now, and it can't pause since the - transfer isn't done using the "normal" procedure. */ - failf(data, "Write callback asked for PAUSE when not supported"); - return CURLE_WRITE_ERROR; - } - return pausewrite(data, type, TRUE, ptr, len); - } - if(wrote != chunklen) { - failf(data, "Failure writing output to destination"); - return CURLE_WRITE_ERROR; - } - } - - ptr += chunklen; - len -= chunklen; - } - - if(writeheader) { - size_t wrote; - - Curl_set_in_callback(data, true); - wrote = writeheader(optr, 1, olen, data->set.writeheader); - Curl_set_in_callback(data, false); - - if(CURL_WRITEFUNC_PAUSE == wrote) - return pausewrite(data, type, FALSE, optr, olen); - if(wrote != olen) { - failf(data, "Failed writing header"); - return CURLE_WRITE_ERROR; - } - } - - return CURLE_OK; -} - - /* Curl_client_write() sends data to the write callback(s) The bit pattern defines to what "streams" to write to. Body and/or header. @@ -303,42 +163,9 @@ CURLcode Curl_client_write(struct Curl_easy *data, return Curl_cwriter_write(data, data->req.writer_stack, type, buf, blen); } -CURLcode Curl_client_unpause(struct Curl_easy *data) -{ - CURLcode result = CURLE_OK; - - if(data->state.tempcount) { - /* there are buffers for sending that can be delivered as the receive - pausing is lifted! */ - unsigned int i; - unsigned int count = data->state.tempcount; - struct tempbuf writebuf[3]; /* there can only be three */ - - /* copy the structs to allow for immediate re-pausing */ - for(i = 0; i < data->state.tempcount; i++) { - writebuf[i] = data->state.tempwrite[i]; - Curl_dyn_init(&data->state.tempwrite[i].b, DYN_PAUSE_BUFFER); - } - data->state.tempcount = 0; - - for(i = 0; i < count; i++) { - /* even if one function returns error, this loops through and frees - all buffers */ - if(!result) - result = chop_write(data, writebuf[i].type, - !writebuf[i].paused_body, - Curl_dyn_ptr(&writebuf[i].b), - Curl_dyn_len(&writebuf[i].b)); - Curl_dyn_free(&writebuf[i].b); - } - } - return result; -} - void Curl_client_cleanup(struct Curl_easy *data) { struct Curl_cwriter *writer = data->req.writer_stack; - size_t i; while(writer) { data->req.writer_stack = writer->next; @@ -347,10 +174,6 @@ void Curl_client_cleanup(struct Curl_easy *data) writer = data->req.writer_stack; } - for(i = 0; i < data->state.tempcount; i++) { - Curl_dyn_free(&data->state.tempwrite[i].b); - } - data->state.tempcount = 0; data->req.bytecount = 0; data->req.headerline = 0; } @@ -388,26 +211,6 @@ void Curl_cwriter_def_close(struct Curl_easy *data, (void) writer; } -/* Real client writer to installed callbacks. */ -static CURLcode cw_client_write(struct Curl_easy *data, - struct Curl_cwriter *writer, int type, - const char *buf, size_t nbytes) -{ - (void)writer; - if(!nbytes) - return CURLE_OK; - return chop_write(data, type, FALSE, (char *)buf, nbytes); -} - -static const struct Curl_cwtype cw_client = { - "client", - NULL, - Curl_cwriter_def_init, - cw_client_write, - Curl_cwriter_def_close, - sizeof(struct Curl_cwriter) -}; - static size_t get_max_body_write_len(struct Curl_easy *data, curl_off_t limit) { if(limit != -1) { @@ -496,14 +299,14 @@ static CURLcode cw_download_write(struct Curl_easy *data, } } - /* Update stats, write and report progress */ - data->req.bytecount += nwrite; - ++data->req.bodywrites; - if(!data->req.ignorebody && nwrite) { + if(!data->req.ignorebody && (nwrite || (type & CLIENTWRITE_EOS))) { result = Curl_cwriter_write(data, writer->next, type, buf, nwrite); if(result) return result; } + /* Update stats, write and report progress */ + data->req.bytecount += nwrite; + ++data->req.bodywrites; result = Curl_pgrsSetDownloadCounter(data, data->req.bytecount); if(result) return result; @@ -615,7 +418,7 @@ static CURLcode do_init_stack(struct Curl_easy *data) DEBUGASSERT(!data->req.writer_stack); result = Curl_cwriter_create(&data->req.writer_stack, - data, &cw_client, CURL_CW_CLIENT); + data, &Curl_cwt_out, CURL_CW_CLIENT); if(result) return result; @@ -669,6 +472,17 @@ struct Curl_cwriter *Curl_cwriter_get_by_name(struct Curl_easy *data, return NULL; } +struct Curl_cwriter *Curl_cwriter_get_by_type(struct Curl_easy *data, + const struct Curl_cwtype *cwt) +{ + struct Curl_cwriter *writer; + for(writer = data->req.writer_stack; writer; writer = writer->next) { + if(writer->cwt == cwt) + return writer; + } + return NULL; +} + void Curl_cwriter_remove_by_name(struct Curl_easy *data, const char *name) { diff --git a/lib/sendf.h b/lib/sendf.h index 1a4a68d8ea0..e4dba9d78b7 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -58,13 +58,6 @@ CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *ptr, size_t len) WARN_UNUSED_RESULT; -/** - * For a paused transfer, there might be buffered data held back. - * Attempt to flush this data to the client. This *may* trigger - * another pause of the transfer. - */ -CURLcode Curl_client_unpause(struct Curl_easy *data); - /** * Free all resources related to client writing. */ @@ -148,6 +141,13 @@ size_t Curl_cwriter_count(struct Curl_easy *data, Curl_cwriter_phase phase); CURLcode Curl_cwriter_add(struct Curl_easy *data, struct Curl_cwriter *writer); +/** + * Look up an installed client writer on `data` by its type. + * @return first writer with that type or NULL + */ +struct Curl_cwriter *Curl_cwriter_get_by_type(struct Curl_easy *data, + const struct Curl_cwtype *cwt); + void Curl_cwriter_remove_by_name(struct Curl_easy *data, const char *name); diff --git a/lib/transfer.c b/lib/transfer.c index 63a16ae86dd..36ca444b195 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -63,6 +63,7 @@ #include "content_encoding.h" #include "hostip.h" #include "cfilters.h" +#include "cw-out.h" #include "transfer.h" #include "sendf.h" #include "speedcheck.h" @@ -1720,3 +1721,9 @@ CURLcode Curl_xfer_write_resp(struct Curl_easy *data, } return result; } + +CURLcode Curl_xfer_write_done(struct Curl_easy *data, bool premature) +{ + (void)premature; + return Curl_cw_out_done(data); +} diff --git a/lib/transfer.h b/lib/transfer.h index 0507f1a45f7..6de418c5644 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -85,4 +85,10 @@ Curl_setup_transfer (struct Curl_easy *data, disables */ ); +/** + * Multi has set transfer to DONE. Last chance to trigger + * missing response things like writing an EOS to the client. + */ +CURLcode Curl_xfer_write_done(struct Curl_easy *data, bool premature); + #endif /* HEADER_CURL_TRANSFER_H */ diff --git a/lib/urldata.h b/lib/urldata.h index 9955ab5ce03..59f290b7279 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1273,18 +1273,6 @@ struct Curl_data_priority { #endif }; -/* - * This struct is for holding data that was attempted to get sent to the user's - * callback but is held due to pausing. One instance per type (BOTH, HEADER, - * BODY). - */ -struct tempbuf { - struct dynbuf b; - int type; /* type of the 'tempwrite' buffer as a bitmask that is used with - Curl_client_write() */ - BIT(paused_body); /* if PAUSE happened before/during BODY write */ -}; - /* Timers */ typedef enum { EXPIRE_100_TIMEOUT, @@ -1362,8 +1350,6 @@ struct UrlState { int retrycount; /* number of retries on a new connection */ struct Curl_ssl_session *session; /* array of 'max_ssl_sessions' size */ long sessionage; /* number of the most recent session */ - struct tempbuf tempwrite[3]; /* BOTH, HEADER, BODY */ - unsigned int tempcount; /* number of entries in use in tempwrite, 0 - 3 */ int os_errno; /* filled in with errno whenever an error occurs */ char *scratch; /* huge buffer[set.buffer_size*2] for upload CRLF replacing */ long followlocation; /* redirect counter */ From 57446b67ba5f6f7cf46a6ca6109cfb94352b4a1a Mon Sep 17 00:00:00 2001 From: Louis Solofrizzo Date: Mon, 26 Feb 2024 12:07:22 +0100 Subject: [PATCH 372/509] lib: initialize output pointers to NULL before calling strto[ff,l,ul] In order to make MSAN happy: ==2200945==WARNING: MemorySanitizer: use-of-uninitialized-value #0 0x596f3b3ed246 in curlx_strtoofft [...]/libcurl/src/lib/strtoofft.c:239:11 #1 0x596f3b402156 in Curl_httpchunk_read [...]/libcurl/src/lib/http_chunks.c:149:12 #2 0x596f3b348550 in readwrite_data [...]/libcurl/src/lib/transfer.c:607:11 [...] ==2202041==WARNING: MemorySanitizer: use-of-uninitialized-value #0 0x5a3fab66a72a in Curl_parse_port [...]/libcurl/src/lib/urlapi.c:547:8 #1 0x5a3fab650645 in parse_authority [...]/libcurl/src/lib/urlapi.c:796:12 #2 0x5a3fab6740f6 in parseurl [...]/libcurl/src/lib/urlapi.c:1176:16 #3 0x5a3fab664fc5 in parseurl_and_replace [...]/libcurl/src/lib/urlapi.c:1342:12 [...] ==2202320==WARNING: MemorySanitizer: use-of-uninitialized-value #0 0x569076a0d6b0 in ipv4_normalize [...]/libcurl/src/lib/urlapi.c:683:12 #1 0x5690769f2820 in parse_authority [...]/libcurl/src/lib/urlapi.c:803:10 #2 0x569076a160f6 in parseurl [...]/libcurl/src/lib/urlapi.c:1176:16 #3 0x569076a06fc5 in parseurl_and_replace [...]/libcurl/src/lib/urlapi.c:1342:12 [...] Signed-off-by: Louis Solofrizzo Closes #12995 --- lib/strtoofft.c | 2 +- lib/urlapi.c | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/strtoofft.c b/lib/strtoofft.c index 4a1d6438931..580fd23bf1e 100644 --- a/lib/strtoofft.c +++ b/lib/strtoofft.c @@ -212,7 +212,7 @@ static int get_char(char c, int base) CURLofft curlx_strtoofft(const char *str, char **endp, int base, curl_off_t *num) { - char *end; + char *end = NULL; curl_off_t number; errno = 0; *num = 0; /* clear by default */ diff --git a/lib/urlapi.c b/lib/urlapi.c index 3cd0362c51d..dc42489722b 100644 --- a/lib/urlapi.c +++ b/lib/urlapi.c @@ -531,7 +531,7 @@ UNITTEST CURLUcode Curl_parse_port(struct Curl_URL *u, struct dynbuf *host, portptr = strchr(hostname, ':'); if(portptr) { - char *rest; + char *rest = NULL; long port; size_t keep = portptr - hostname; @@ -681,7 +681,7 @@ static int ipv4_normalize(struct dynbuf *host) return HOST_IPV6; while(!done) { - char *endp; + char *endp = NULL; unsigned long l; if(!ISDIGIT(*c)) /* most importantly this doesn't allow a leading plus or minus */ From 9c8968e43db86d3cb178a23416ac4e19d57e8b16 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Feb 2024 12:27:07 +0100 Subject: [PATCH 373/509] http_chunks: remove unused 'endptr' variable Closes #12996 --- lib/http_chunks.c | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/http_chunks.c b/lib/http_chunks.c index ad1ee9adab6..959edb2a4d0 100644 --- a/lib/http_chunks.c +++ b/lib/http_chunks.c @@ -155,7 +155,6 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, (*pconsumed)++; } else { - char *endptr; if(0 == ch->hexindex) { /* This is illegal data, we received junk where we expected a hexadecimal digit. */ @@ -167,7 +166,7 @@ static CURLcode httpchunk_readwrite(struct Curl_easy *data, /* blen and buf are unmodified */ ch->hexbuffer[ch->hexindex] = 0; - if(curlx_strtoofft(ch->hexbuffer, &endptr, 16, &ch->datasize)) { + if(curlx_strtoofft(ch->hexbuffer, NULL, 16, &ch->datasize)) { failf(data, "chunk hex-length not valid: '%s'", ch->hexbuffer); ch->state = CHUNK_FAILED; ch->last_code = CHUNKE_ILLEGAL_HEX; From b8ed0f8259ddf17133aa3e400e00856b7b6e8639 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Feb 2024 23:05:51 +0100 Subject: [PATCH 374/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 55 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 13 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index f386d71037d..a3115649a03 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.7.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3095 + Contributors: 3102 This release includes the following changes: @@ -20,6 +20,8 @@ This release includes the following bugfixes: 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 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 warning for using TLS libraries without 1.3 support [25] @@ -27,6 +29,7 @@ This release includes the following bugfixes: o cmake: fix install for older CMake versions [53] o cmdline-docs/Makefile: avoid using a fixed temp file name [5] o cmdline-docs: quote and angle bracket cleanup [45] + o configure.ac: find libpsl with pkg-config [79] o configure: add warning for using TLS libraries without 1.3 support [26] o configure: do not link with nghttp3 unless necessary [7] o connect.c: fix typo [17] @@ -48,34 +51,46 @@ This release includes the following bugfixes: 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: make `\>` in input to render as plain '>' in output [78] o header.md: remove backslash, make nicer markdown [48] o HTTP/2: write response directly [12] o HTTP3.md: adjust the OpenSSL QUIC install instructions [34] + o http: move headers collecting to writer [71] 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 lib582: remove code causing warning that is never run [38] o lib: convert Curl_get_line to use dynbuf [42] + o lib: initialize output pointers to NULL before calling strto[ff,l,ul] [63] + 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: use mbedtls_ssl_conf_{min|max}_tls_version [59] o md4: include strdup.h for the memdup proto [10] + 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 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 OS400: avoid using awk in the build scripts [20] o proxy1.0.md: fix example [15] + 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 strtoofft: fix the overflow check [74] o test1165: improve pattern matching [60] o tests: support setting/using blank content env variables o tool_cb_hdr: only parse etag + content-disposition for 2xx [9] 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 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 vtls: fix tls proxy peer verification [55] o vtls: revert "receive max buffer" + add test case [39] @@ -95,16 +110,18 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - Boris Verkhovskiy, Brett Buddin, Chris Webb, Dan Fandrich, Daniel Gustafsson, - Daniel Stenberg, Daniel Szmulewicz, Dirk Hünniger, Dmitry Tretyakov, - edmcln on github, Erik Schnetter, Evgeny Grin (Karlson2k), Fabian Vogt, - Faraz Fallahi, Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, - Joel Depooter, Jon Rumsey, Karthikdasari0423, Konstantin Vlasov, - Lars Kellogg-Stedman, LeeRiva, Lukáš Zaoral, Michael Forney, - Michael Kaufmann, Michał Antoniak, Patrick Monnerat, Peter Krefting, - Ramiro Garcia, Ray Satiro, Richard Levitte, Ryan Carsten Schmidt, - Scott Mutter, Sergey Bronnikov, Stefan Eissing, Viktor Szakats - (38 contributors) + 5533asdg on github, Boris Verkhovskiy, Brett Buddin, Chris Webb, + Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, Daniel Szmulewicz, + Dirk Hünniger, Dmitry Tretyakov, edmcln on github, Erik Schnetter, + Evgeny Grin (Karlson2k), Fabian Vogt, Fabrice Fontaine, Faraz Fallahi, + Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, + Joel Depooter, Jon Rumsey, Karthikdasari0423, Konstantin Vlasov, kpcyrd, + Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, Lukáš Zaoral, + Michael Forney, Michael Kaufmann, Michał Antoniak, Patrick Monnerat, + Paweł Witas, Peter Krefting, Ramiro Garcia, Ray Satiro, Richard Levitte, + Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, Sergey Bronnikov, + Stefan Eissing, Viktor Szakats, vulnerabilityspotter on hackerone + (46 contributors) References to bug reports and discussions on issues: @@ -128,7 +145,6 @@ References to bug reports and discussions on issues: [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=12843 [22] = https://curl.se/bug/?i=12937 [23] = https://curl.se/bug/?i=12750 [24] = https://curl.se/bug/?i=12719 @@ -156,7 +172,6 @@ References to bug reports and discussions on issues: [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=12875 [50] = https://curl.se/bug/?i=12838 [51] = https://curl.se/bug/?i=12859 [52] = https://curl.se/mail/archive-2024-02/0004.html @@ -165,11 +180,25 @@ References to bug reports and discussions on issues: [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 + [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 + [81] = https://curl.se/bug/?i=12971 From 5929822114ac19debd3d18e3146942b401c31740 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 14 Feb 2024 12:09:32 +0100 Subject: [PATCH 375/509] lib: send rework Curl_read/Curl_write clarifications - replace `Curl_read()`, `Curl_write()` and `Curl_nwrite()` to 1clarify when and at what level they operate - send/recv of transfer related data is now done via `Curl_xfer_send()/Curl_xfer_recv()` which no longer has socket/socketindex as parameter. It decides on the transfer setup of `conn->sockfd` and `conn->writesockfd` on which connection filter chain to operate. - send/recv on a specific connection filter chain is done via `Curl_conn_send()/Curl_conn_recv()` which get the socket index as parameter. - rename `Curl_setup_transfer()` to `Curl_xfer_setup()` for naming consistency - clarify that the special CURLE_AGAIN handling to return `CURLE_OK` with length 0 only applies to `Curl_xfer_send()` and CURLE_AGAIN is returned by all other send() variants. SingleRequest reshuffling - move functions into request.[ch] - differentiate between reset and free - add Curl_req_done() to perform last actions - add a send `bufq` to SingleRequest for future use in keeping upload data Closes #12963 --- lib/Makefile.inc | 2 + lib/c-hyper.c | 24 +++--- lib/c-hyper.h | 6 ++ lib/cf-h1-proxy.c | 9 +- lib/cf-haproxy.c | 14 ++- lib/cfilters.c | 72 ++++++++++++++-- lib/cfilters.h | 32 ++++++- lib/curl_rtmp.c | 4 +- lib/dict.c | 23 +++-- lib/easy.c | 35 +++----- lib/ftp.c | 25 +++--- lib/gopher.c | 6 +- lib/http.c | 24 +++--- lib/imap.c | 11 ++- lib/krb5.c | 17 ++-- lib/ldap.c | 2 +- lib/mqtt.c | 13 ++- lib/multi.c | 7 +- lib/openldap.c | 2 +- lib/pingpong.c | 27 ++++-- lib/pingpong.h | 2 +- lib/pop3.c | 5 +- lib/request.c | 108 ++++++++++++++++++++++++ lib/request.h | 192 ++++++++++++++++++++++++++++++++++++++++++ lib/rtsp.c | 4 +- lib/sendf.c | 112 +----------------------- lib/sendf.h | 20 +---- lib/smb.c | 11 +-- lib/smtp.c | 9 +- lib/telnet.c | 10 +-- lib/tftp.c | 4 +- lib/transfer.c | 68 +++++++++++++-- lib/transfer.h | 21 ++++- lib/url.c | 60 +++++-------- lib/url.h | 1 - lib/urldata.h | 122 +-------------------------- lib/vssh/libssh.c | 20 ++--- lib/vssh/libssh2.c | 26 +++--- lib/vssh/wolfssh.c | 10 +-- lib/ws.c | 13 +-- tests/unit/unit1620.c | 2 - 41 files changed, 687 insertions(+), 488 deletions(-) create mode 100644 lib/request.c create mode 100644 lib/request.h diff --git a/lib/Makefile.inc b/lib/Makefile.inc index ef3f8a0addc..400e2b1ac5e 100644 --- a/lib/Makefile.inc +++ b/lib/Makefile.inc @@ -201,6 +201,7 @@ LIB_CFILES = \ psl.c \ rand.c \ rename.c \ + request.c \ rtsp.c \ select.c \ sendf.c \ @@ -337,6 +338,7 @@ LIB_HFILES = \ psl.h \ rand.h \ rename.h \ + request.h \ rtsp.h \ select.h \ sendf.h \ diff --git a/lib/c-hyper.c b/lib/c-hyper.c index f07dd6c0b19..f8e36e909d0 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -53,6 +53,7 @@ #include #include "urldata.h" +#include "cfilters.h" #include "sendf.h" #include "headers.h" #include "transfer.h" @@ -74,7 +75,8 @@ typedef enum { size_t Curl_hyper_recv(void *userp, hyper_context *ctx, uint8_t *buf, size_t buflen) { - struct Curl_easy *data = userp; + struct hyp_io_ctx *io_ctx = userp; + struct Curl_easy *data = io_ctx->data; struct connectdata *conn = data->conn; CURLcode result; ssize_t nread; @@ -82,7 +84,8 @@ size_t Curl_hyper_recv(void *userp, hyper_context *ctx, (void)ctx; DEBUGF(infof(data, "Curl_hyper_recv(%zu)", buflen)); - result = Curl_read(data, conn->sockfd, (char *)buf, buflen, &nread); + result = Curl_conn_recv(data, io_ctx->sockindex, + (char *)buf, buflen, &nread); if(result == CURLE_AGAIN) { /* would block, register interest */ DEBUGF(infof(data, "Curl_hyper_recv(%zu) -> EAGAIN", buflen)); @@ -106,15 +109,14 @@ size_t Curl_hyper_recv(void *userp, hyper_context *ctx, size_t Curl_hyper_send(void *userp, hyper_context *ctx, const uint8_t *buf, size_t buflen) { - struct Curl_easy *data = userp; - struct connectdata *conn = data->conn; + struct hyp_io_ctx *io_ctx = userp; + struct Curl_easy *data = io_ctx->data; CURLcode result; ssize_t nwrote; DEBUGF(infof(data, "Curl_hyper_send(%zu)", buflen)); - result = Curl_write(data, conn->sockfd, (void *)buf, buflen, &nwrote); - if(!result && !nwrote) - result = CURLE_AGAIN; + result = Curl_conn_send(data, io_ctx->sockindex, + (void *)buf, buflen, &nwrote); if(result == CURLE_AGAIN) { DEBUGF(infof(data, "Curl_hyper_send(%zu) -> EAGAIN", buflen)); /* would block, register interest */ @@ -885,7 +887,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) may be parts of the request that is not yet sent, since we can deal with the rest of the request in the PERFORM phase. */ *done = TRUE; - Curl_client_cleanup(data); + Curl_cw_reset(data); /* Add collecting of headers written to client. For a new connection, * we might have done that already, but reuse @@ -939,7 +941,9 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) goto error; } /* tell Hyper how to read/write network data */ - hyper_io_set_userdata(io, data); + h->io_ctx.data = data; + h->io_ctx.sockindex = FIRSTSOCKET; + hyper_io_set_userdata(io, &h->io_ctx); hyper_io_set_read(io, Curl_hyper_recv); hyper_io_set_write(io, Curl_hyper_send); @@ -1200,7 +1204,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) if((httpreq == HTTPREQ_GET) || (httpreq == HTTPREQ_HEAD)) { /* HTTP GET/HEAD download */ Curl_pgrsSetUploadSize(data, 0); /* nothing */ - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); } conn->datastream = Curl_hyper_stream; if(data->state.expect100header) diff --git a/lib/c-hyper.h b/lib/c-hyper.h index 0c7de90b70b..4a07233078d 100644 --- a/lib/c-hyper.h +++ b/lib/c-hyper.h @@ -29,6 +29,11 @@ #include +struct hyp_io_ctx { + struct Curl_easy *data; + int sockindex; +}; + /* per-transfer data for the Hyper backend */ struct hyptransfer { hyper_waker *write_waker; @@ -36,6 +41,7 @@ struct hyptransfer { const hyper_executor *exec; hyper_waker *exp100_waker; hyper_waker *send_body_waker; + struct hyp_io_ctx io_ctx; }; size_t Curl_hyper_recv(void *userp, hyper_context *ctx, diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index 167e5315a84..b7afe27a3fe 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -366,7 +366,6 @@ static CURLcode recv_CONNECT_resp(struct Curl_cfilter *cf, { CURLcode result = CURLE_OK; struct SingleRequest *k = &data->req; - curl_socket_t tunnelsocket = Curl_conn_cf_get_socket(cf, data); char *linep; size_t line_len; int error, writetype; @@ -386,7 +385,7 @@ static CURLcode recv_CONNECT_resp(struct Curl_cfilter *cf, /* Read one byte at a time to avoid a race condition. Wait at most one second before looping to ensure continuous pgrsUpdates. */ - result = Curl_read(data, tunnelsocket, &byte, 1, &nread); + result = Curl_conn_recv(data, cf->sockindex, &byte, 1, &nread); if(result == CURLE_AGAIN) /* socket buffer drained, return */ return CURLE_OK; @@ -593,7 +592,9 @@ static CURLcode start_CONNECT(struct Curl_cfilter *cf, goto error; } /* tell Hyper how to read/write network data */ - hyper_io_set_userdata(io, data); + h->io_ctx.data = data; + h->io_ctx.sockindex = cf->sockindex; + hyper_io_set_userdata(io, &h->io_ctx); hyper_io_set_read(io, Curl_hyper_recv); hyper_io_set_write(io, Curl_hyper_send); conn->sockfd = tunnelsocket; @@ -1007,7 +1008,7 @@ static CURLcode cf_h1_proxy_connect(struct Curl_cfilter *cf, data->req.header = TRUE; /* assume header */ data->req.bytecount = 0; data->req.ignorebody = FALSE; - Curl_client_cleanup(data); + Curl_cw_reset(data); Curl_pgrsSetUploadCounter(data, 0); Curl_pgrsSetDownloadCounter(data, 0); diff --git a/lib/cf-haproxy.c b/lib/cf-haproxy.c index c062887bf39..652070e12dd 100644 --- a/lib/cf-haproxy.c +++ b/lib/cf-haproxy.c @@ -129,11 +129,17 @@ static CURLcode cf_haproxy_connect(struct Curl_cfilter *cf, case HAPROXY_SEND: len = Curl_dyn_len(&ctx->data_out); if(len > 0) { - ssize_t written = Curl_conn_send(data, cf->sockindex, - Curl_dyn_ptr(&ctx->data_out), - len, &result); - if(written < 0) + ssize_t written; + result = Curl_conn_send(data, cf->sockindex, + Curl_dyn_ptr(&ctx->data_out), + len, &written); + if(result == CURLE_AGAIN) { + result = CURLE_OK; + written = 0; + } + else if(result) goto out; + DEBUGASSERT(written >= 0); Curl_dyn_tail(&ctx->data_out, len - (size_t)written); if(Curl_dyn_len(&ctx->data_out) > 0) { result = CURLE_OK; diff --git a/lib/cfilters.c b/lib/cfilters.c index 823e90c3f2b..2bf1dd844f2 100644 --- a/lib/cfilters.c +++ b/lib/cfilters.c @@ -168,38 +168,46 @@ void Curl_conn_close(struct Curl_easy *data, int index) } } -ssize_t Curl_conn_recv(struct Curl_easy *data, int num, char *buf, - size_t len, CURLcode *code) +ssize_t Curl_cf_recv(struct Curl_easy *data, int num, char *buf, + size_t len, CURLcode *code) { struct Curl_cfilter *cf; DEBUGASSERT(data); DEBUGASSERT(data->conn); + *code = CURLE_OK; cf = data->conn->cfilter[num]; while(cf && !cf->connected) { cf = cf->next; } if(cf) { - return cf->cft->do_recv(cf, data, buf, len, code); + ssize_t nread = cf->cft->do_recv(cf, data, buf, len, code); + DEBUGASSERT(nread >= 0 || *code); + DEBUGASSERT(nread < 0 || !*code); + return nread; } failf(data, "recv: no filter connected"); *code = CURLE_FAILED_INIT; return -1; } -ssize_t Curl_conn_send(struct Curl_easy *data, int num, - const void *mem, size_t len, CURLcode *code) +ssize_t Curl_cf_send(struct Curl_easy *data, int num, + const void *mem, size_t len, CURLcode *code) { struct Curl_cfilter *cf; DEBUGASSERT(data); DEBUGASSERT(data->conn); + *code = CURLE_OK; cf = data->conn->cfilter[num]; while(cf && !cf->connected) { cf = cf->next; } if(cf) { - return cf->cft->do_send(cf, data, mem, len, code); + ssize_t nwritten = cf->cft->do_send(cf, data, mem, len, code); + DEBUGASSERT(nwritten >= 0 || *code); + DEBUGASSERT(nwritten < 0 || !*code || !len); + return nwritten; } failf(data, "send: no filter connected"); DEBUGASSERT(0); @@ -662,6 +670,58 @@ size_t Curl_conn_get_max_concurrent(struct Curl_easy *data, return (result || n <= 0)? 1 : (size_t)n; } +int Curl_conn_sockindex(struct Curl_easy *data, curl_socket_t sockfd) +{ + if(data && data->conn && + sockfd != CURL_SOCKET_BAD && sockfd == data->conn->sock[SECONDARYSOCKET]) + return SECONDARYSOCKET; + return FIRSTSOCKET; +} + +CURLcode Curl_conn_recv(struct Curl_easy *data, int sockindex, + char *buf, size_t blen, ssize_t *n) +{ + CURLcode result = CURLE_OK; + ssize_t nread; + + DEBUGASSERT(data->conn); + nread = data->conn->recv[sockindex](data, sockindex, buf, blen, &result); + DEBUGASSERT(nread >= 0 || result); + DEBUGASSERT(nread < 0 || !result); + *n = (nread >= 0)? (size_t)nread : 0; + return result; +} + +CURLcode Curl_conn_send(struct Curl_easy *data, int sockindex, + const void *buf, size_t blen, + ssize_t *pnwritten) +{ + ssize_t nwritten; + CURLcode result = CURLE_OK; + struct connectdata *conn; + + DEBUGASSERT(sockindex >= 0 && sockindex < 2); + DEBUGASSERT(pnwritten); + DEBUGASSERT(data); + DEBUGASSERT(data->conn); + conn = data->conn; +#ifdef CURLDEBUG + { + /* Allow debug builds to override this logic to force short sends + */ + char *p = getenv("CURL_SMALLSENDS"); + if(p) { + size_t altsize = (size_t)strtoul(p, NULL, 10); + if(altsize) + blen = CURLMIN(blen, altsize); + } + } +#endif + nwritten = conn->send[sockindex](data, sockindex, buf, blen, &result); + DEBUGASSERT((nwritten >= 0) || result); + *pnwritten = nwritten; + return result; +} void Curl_pollset_reset(struct Curl_easy *data, struct easy_pollset *ps) diff --git a/lib/cfilters.h b/lib/cfilters.h index f83842920bc..65ae3d4cbb3 100644 --- a/lib/cfilters.h +++ b/lib/cfilters.h @@ -405,8 +405,8 @@ void Curl_conn_adjust_pollset(struct Curl_easy *data, * actuel number of bytes copied or a negative value on error. * The error code is placed into `*code`. */ -ssize_t Curl_conn_recv(struct Curl_easy *data, int sockindex, char *buf, - size_t len, CURLcode *code); +ssize_t Curl_cf_recv(struct Curl_easy *data, int sockindex, char *buf, + size_t len, CURLcode *code); /** * Send `len` bytes of data from `buf` through the filter chain `sockindex` @@ -414,8 +414,8 @@ ssize_t Curl_conn_recv(struct Curl_easy *data, int sockindex, char *buf, * or a negative value on error. * The error code is placed into `*code`. */ -ssize_t Curl_conn_send(struct Curl_easy *data, int sockindex, - const void *buf, size_t len, CURLcode *code); +ssize_t Curl_cf_send(struct Curl_easy *data, int sockindex, + const void *buf, size_t len, CURLcode *code); /** * The easy handle `data` is being attached to `conn`. This does @@ -497,6 +497,30 @@ size_t Curl_conn_get_max_concurrent(struct Curl_easy *data, int sockindex); +/** + * Get the index of the given socket in the connection's sockets. + * Useful in calling `Curl_conn_send()/Curl_conn_recv()` with the + * correct socket index. + */ +int Curl_conn_sockindex(struct Curl_easy *data, curl_socket_t sockfd); + +/* + * Receive data on the connection, using FIRSTSOCKET/SECONDARYSOCKET. + * Will return CURLE_AGAIN iff blocked on receiving. + */ +CURLcode Curl_conn_recv(struct Curl_easy *data, int sockindex, + char *buf, size_t buffersize, + ssize_t *pnread); + +/* + * Send data on the connection, using FIRSTSOCKET/SECONDARYSOCKET. + * Will return CURLE_AGAIN iff blocked on sending. + */ +CURLcode Curl_conn_send(struct Curl_easy *data, int sockindex, + const void *buf, size_t blen, + ssize_t *pnwritten); + + void Curl_pollset_reset(struct Curl_easy *data, struct easy_pollset *ps); diff --git a/lib/curl_rtmp.c b/lib/curl_rtmp.c index 147b12a3ff4..b2f2adad8b1 100644 --- a/lib/curl_rtmp.c +++ b/lib/curl_rtmp.c @@ -265,10 +265,10 @@ static CURLcode rtmp_do(struct Curl_easy *data, bool *done) if(data->state.upload) { Curl_pgrsSetUploadSize(data, data->state.infilesize); - Curl_setup_transfer(data, -1, -1, FALSE, FIRSTSOCKET); + Curl_xfer_setup(data, -1, -1, FALSE, FIRSTSOCKET); } else - Curl_setup_transfer(data, FIRSTSOCKET, -1, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, FALSE, -1); *done = TRUE; return CURLE_OK; } diff --git a/lib/dict.c b/lib/dict.c index 323984822df..955290f4da5 100644 --- a/lib/dict.c +++ b/lib/dict.c @@ -122,11 +122,10 @@ static char *unescape_word(const char *input) } /* sendf() sends formatted data to the server */ -static CURLcode sendf(curl_socket_t sockfd, struct Curl_easy *data, - const char *fmt, ...) CURL_PRINTF(3, 4); +static CURLcode sendf(struct Curl_easy *data, + const char *fmt, ...) CURL_PRINTF(2, 3); -static CURLcode sendf(curl_socket_t sockfd, struct Curl_easy *data, - const char *fmt, ...) +static CURLcode sendf(struct Curl_easy *data, const char *fmt, ...) { ssize_t bytes_written; size_t write_len; @@ -146,7 +145,7 @@ static CURLcode sendf(curl_socket_t sockfd, struct Curl_easy *data, for(;;) { /* Write the buffer to the socket */ - result = Curl_write(data, sockfd, sptr, write_len, &bytes_written); + result = Curl_xfer_send(data, sptr, write_len, &bytes_written); if(result) break; @@ -178,8 +177,6 @@ static CURLcode dict_do(struct Curl_easy *data, bool *done) char *nthdef = NULL; /* This is not part of the protocol, but required by RFC 2229 */ CURLcode result; - struct connectdata *conn = data->conn; - curl_socket_t sockfd = conn->sock[FIRSTSOCKET]; char *path; @@ -228,7 +225,7 @@ static CURLcode dict_do(struct Curl_easy *data, bool *done) goto error; } - result = sendf(sockfd, data, + result = sendf(data, "CLIENT " LIBCURL_NAME " " LIBCURL_VERSION "\r\n" "MATCH " "%s " /* database */ @@ -243,7 +240,7 @@ static CURLcode dict_do(struct Curl_easy *data, bool *done) failf(data, "Failed sending DICT request"); goto error; } - Curl_setup_transfer(data, FIRSTSOCKET, -1, FALSE, -1); /* no upload */ + Curl_xfer_setup(data, FIRSTSOCKET, -1, FALSE, -1); /* no upload */ } else if(strncasecompare(path, DICT_DEFINE, sizeof(DICT_DEFINE)-1) || strncasecompare(path, DICT_DEFINE2, sizeof(DICT_DEFINE2)-1) || @@ -276,7 +273,7 @@ static CURLcode dict_do(struct Curl_easy *data, bool *done) goto error; } - result = sendf(sockfd, data, + result = sendf(data, "CLIENT " LIBCURL_NAME " " LIBCURL_VERSION "\r\n" "DEFINE " "%s " /* database */ @@ -289,7 +286,7 @@ static CURLcode dict_do(struct Curl_easy *data, bool *done) failf(data, "Failed sending DICT request"); goto error; } - Curl_setup_transfer(data, FIRSTSOCKET, -1, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, FALSE, -1); } else { @@ -302,7 +299,7 @@ static CURLcode dict_do(struct Curl_easy *data, bool *done) if(ppath[i] == ':') ppath[i] = ' '; } - result = sendf(sockfd, data, + result = sendf(data, "CLIENT " LIBCURL_NAME " " LIBCURL_VERSION "\r\n" "%s\r\n" "QUIT\r\n", ppath); @@ -311,7 +308,7 @@ static CURLcode dict_do(struct Curl_easy *data, bool *done) goto error; } - Curl_setup_transfer(data, FIRSTSOCKET, -1, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, FALSE, -1); } } diff --git a/lib/easy.c b/lib/easy.c index b2a66ad0fab..7ea1ce1f636 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -1038,7 +1038,7 @@ struct Curl_easy *curl_easy_duphandle(struct Curl_easy *data) */ void curl_easy_reset(struct Curl_easy *data) { - Curl_free_request_state(data); + Curl_req_reset(&data->req, data); /* zero out UserDefined data: */ Curl_freeset(data); @@ -1166,9 +1166,11 @@ CURLcode curl_easy_pause(struct Curl_easy *data, int action) } -static CURLcode easy_connection(struct Curl_easy *data, curl_socket_t *sfd, +static CURLcode easy_connection(struct Curl_easy *data, struct connectdata **connp) { + curl_socket_t sfd; + if(!data) return CURLE_BAD_FUNCTION_ARGUMENT; @@ -1178,9 +1180,9 @@ static CURLcode easy_connection(struct Curl_easy *data, curl_socket_t *sfd, return CURLE_UNSUPPORTED_PROTOCOL; } - *sfd = Curl_getconnectinfo(data, connp); + sfd = Curl_getconnectinfo(data, connp); - if(*sfd == CURL_SOCKET_BAD) { + if(sfd == CURL_SOCKET_BAD) { failf(data, "Failed to get recent socket"); return CURLE_UNSUPPORTED_PROTOCOL; } @@ -1196,7 +1198,6 @@ static CURLcode easy_connection(struct Curl_easy *data, curl_socket_t *sfd, CURLcode curl_easy_recv(struct Curl_easy *data, void *buffer, size_t buflen, size_t *n) { - curl_socket_t sfd; CURLcode result; ssize_t n1; struct connectdata *c; @@ -1204,7 +1205,7 @@ CURLcode curl_easy_recv(struct Curl_easy *data, void *buffer, size_t buflen, if(Curl_is_in_callback(data)) return CURLE_RECURSIVE_API_CALL; - result = easy_connection(data, &sfd, &c); + result = easy_connection(data, &c); if(result) return result; @@ -1214,7 +1215,7 @@ CURLcode curl_easy_recv(struct Curl_easy *data, void *buffer, size_t buflen, Curl_attach_connection(data, c); *n = 0; - result = Curl_read(data, sfd, buffer, buflen, &n1); + result = Curl_conn_recv(data, FIRSTSOCKET, buffer, buflen, &n1); if(result) return result; @@ -1226,11 +1227,10 @@ CURLcode curl_easy_recv(struct Curl_easy *data, void *buffer, size_t buflen, #ifdef USE_WEBSOCKETS CURLcode Curl_connect_only_attach(struct Curl_easy *data) { - curl_socket_t sfd; CURLcode result; struct connectdata *c = NULL; - result = easy_connection(data, &sfd, &c); + result = easy_connection(data, &c); if(result) return result; @@ -1251,13 +1251,12 @@ CURLcode Curl_connect_only_attach(struct Curl_easy *data) CURLcode Curl_senddata(struct Curl_easy *data, const void *buffer, size_t buflen, ssize_t *n) { - curl_socket_t sfd; CURLcode result; - ssize_t n1; struct connectdata *c = NULL; SIGPIPE_VARIABLE(pipe_st); - result = easy_connection(data, &sfd, &c); + *n = 0; + result = easy_connection(data, &c); if(result) return result; @@ -1266,20 +1265,12 @@ CURLcode Curl_senddata(struct Curl_easy *data, const void *buffer, needs to be reattached */ Curl_attach_connection(data, c); - *n = 0; sigpipe_ignore(data, &pipe_st); - result = Curl_write(data, sfd, buffer, buflen, &n1); + result = Curl_conn_send(data, FIRSTSOCKET, buffer, buflen, n); sigpipe_restore(&pipe_st); - if(n1 == -1) + if(result && result != CURLE_AGAIN) return CURLE_SEND_ERROR; - - /* detect EAGAIN */ - if(!result && !n1) - return CURLE_AGAIN; - - *n = n1; - return result; } diff --git a/lib/ftp.c b/lib/ftp.c index 53445b3d5a5..4deb841b3ae 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -151,7 +151,7 @@ static CURLcode wc_statemach(struct Curl_easy *data); static void wc_data_dtor(void *ptr); static CURLcode ftp_state_retr(struct Curl_easy *data, curl_off_t filesize); static CURLcode ftp_readresp(struct Curl_easy *data, - curl_socket_t sockfd, + int sockindex, struct pingpong *pp, int *ftpcode, size_t *size); @@ -581,12 +581,12 @@ static CURLcode InitiateTransfer(struct Curl_easy *data) /* set the SO_SNDBUF for the secondary socket for those who need it */ Curl_sndbufset(conn->sock[SECONDARYSOCKET]); - Curl_setup_transfer(data, -1, -1, FALSE, SECONDARYSOCKET); + Curl_xfer_setup(data, -1, -1, FALSE, SECONDARYSOCKET); } else { /* FTP download: */ - Curl_setup_transfer(data, SECONDARYSOCKET, - conn->proto.ftpc.retr_size_saved, FALSE, -1); + Curl_xfer_setup(data, SECONDARYSOCKET, + conn->proto.ftpc.retr_size_saved, FALSE, -1); } conn->proto.ftpc.pp.pending_resp = TRUE; /* expect server response */ @@ -664,13 +664,13 @@ static bool ftp_endofresp(struct Curl_easy *data, struct connectdata *conn, } static CURLcode ftp_readresp(struct Curl_easy *data, - curl_socket_t sockfd, + int sockindex, struct pingpong *pp, int *ftpcode, /* return the ftp-code if done */ size_t *size) /* size of the response */ { int code; - CURLcode result = Curl_pp_readresp(data, sockfd, pp, &code, size); + CURLcode result = Curl_pp_readresp(data, sockindex, pp, &code, size); #ifdef HAVE_GSSAPI { @@ -805,7 +805,7 @@ CURLcode Curl_GetFTPResponse(struct Curl_easy *data, break; } } - result = ftp_readresp(data, sockfd, pp, ftpcode, &nread); + result = ftp_readresp(data, FIRSTSOCKET, pp, ftpcode, &nread); if(result) break; @@ -1725,7 +1725,7 @@ static CURLcode ftp_state_ul_setup(struct Curl_easy *data, infof(data, "File already completely uploaded"); /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); /* Set ->transfer so that we won't get any error in * ftp_done() because we didn't transfer anything! */ @@ -2396,7 +2396,7 @@ static CURLcode ftp_state_retr(struct Curl_easy *data, if(ftp->downloadsize == 0) { /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); infof(data, "File already completely downloaded"); /* Set ->transfer so that we won't get any error in ftp_done() @@ -2803,7 +2803,6 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, struct connectdata *conn) { CURLcode result; - curl_socket_t sock = conn->sock[FIRSTSOCKET]; int ftpcode; struct ftp_conn *ftpc = &conn->proto.ftpc; struct pingpong *pp = &ftpc->pp; @@ -2813,7 +2812,7 @@ static CURLcode ftp_statemachine(struct Curl_easy *data, if(pp->sendleft) return Curl_pp_flushsend(data, pp); - result = ftp_readresp(data, sock, pp, &ftpcode, &nread); + result = ftp_readresp(data, FIRSTSOCKET, pp, &ftpcode, &nread); if(result) return result; @@ -3813,7 +3812,7 @@ static CURLcode ftp_do_more(struct Curl_easy *data, int *completep) } /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); if(!ftpc->wait_data_conn) { /* no waiting for the data connection so this is now complete */ @@ -4415,7 +4414,7 @@ static CURLcode ftp_dophase_done(struct Curl_easy *data, bool connected) if(ftp->transfer != PPTRANSFER_BODY) /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); else if(!connected) /* since we didn't connect now, we want do_more to get called */ conn->bits.do_more = TRUE; diff --git a/lib/gopher.c b/lib/gopher.c index 9ca08289eb1..e49da8147c9 100644 --- a/lib/gopher.c +++ b/lib/gopher.c @@ -185,7 +185,7 @@ static CURLcode gopher_do(struct Curl_easy *data, bool *done) if(strlen(sel) < 1) break; - result = Curl_nwrite(data, FIRSTSOCKET, sel, k, &amount); + result = Curl_xfer_send(data, sel, k, &amount); if(!result) { /* Which may not have written it all! */ result = Curl_client_write(data, CLIENTWRITE_HEADER, sel, amount); if(result) @@ -227,7 +227,7 @@ static CURLcode gopher_do(struct Curl_easy *data, bool *done) free(sel_org); if(!result) - result = Curl_nwrite(data, FIRSTSOCKET, "\r\n", 2, &amount); + result = Curl_xfer_send(data, "\r\n", 2, &amount); if(result) { failf(data, "Failed sending Gopher request"); return result; @@ -236,7 +236,7 @@ static CURLcode gopher_do(struct Curl_easy *data, bool *done) if(result) return result; - Curl_setup_transfer(data, FIRSTSOCKET, -1, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, FALSE, -1); return CURLE_OK; } #endif /* CURL_DISABLE_GOPHER */ diff --git a/lib/http.c b/lib/http.c index dd1fc4ffa0e..97ef4550f5e 100644 --- a/lib/http.c +++ b/lib/http.c @@ -1356,7 +1356,11 @@ CURLcode Curl_buffer_send(struct dynbuf *in, sendsize = (size_t)data->set.upload_buffer_size; } - result = Curl_nwrite(data, sockindex, ptr, sendsize, &amount); + result = Curl_conn_send(data, sockindex, ptr, sendsize, &amount); + if(result == CURLE_AGAIN) { + result = CURLE_OK; + amount = 0; + } if(!result) { /* @@ -2511,8 +2515,8 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, failf(data, "Failed sending PUT request"); else /* prepare for transfer */ - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, - http->postsize?FIRSTSOCKET:-1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, + http->postsize?FIRSTSOCKET:-1); if(result) return result; break; @@ -2534,7 +2538,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, failf(data, "Failed sending POST request"); else /* setup variables for the upcoming transfer */ - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); break; } @@ -2592,8 +2596,8 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, failf(data, "Failed sending POST request"); else /* prepare for transfer */ - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, - http->postsize?FIRSTSOCKET:-1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, + http->postsize?FIRSTSOCKET:-1); if(result) return result; @@ -2735,8 +2739,8 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, if(result) failf(data, "Failed sending HTTP POST request"); else - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, - http->postdata?FIRSTSOCKET:-1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, + http->postdata?FIRSTSOCKET:-1); break; default: @@ -2755,11 +2759,11 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, !(data->set.connect_only)) /* Set up the transfer for two-way since without CONNECT_ONLY set, this request probably wants to send data too post upgrade */ - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, FIRSTSOCKET); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, FIRSTSOCKET); #endif else /* HTTP GET/HEAD download: */ - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); } return result; diff --git a/lib/imap.c b/lib/imap.c index 50849eefc24..43ec83d09c6 100644 --- a/lib/imap.c +++ b/lib/imap.c @@ -1213,14 +1213,14 @@ static CURLcode imap_state_fetch_resp(struct Curl_easy *data, if(data->req.bytecount == size) /* The entire data is already transferred! */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); else { /* IMAP download */ data->req.maxdownload = size; /* force a recv/send check of this connection, as the data might've been read off the socket already */ data->state.select_bits = CURL_CSELECT_IN; - Curl_setup_transfer(data, FIRSTSOCKET, size, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, size, FALSE, -1); } } else { @@ -1268,7 +1268,7 @@ static CURLcode imap_state_append_resp(struct Curl_easy *data, int imapcode, Curl_pgrsSetUploadSize(data, data->state.infilesize); /* IMAP upload */ - Curl_setup_transfer(data, -1, -1, FALSE, FIRSTSOCKET); + Curl_xfer_setup(data, -1, -1, FALSE, FIRSTSOCKET); /* End of DO phase */ imap_state(data, IMAP_STOP); @@ -1299,7 +1299,6 @@ static CURLcode imap_statemachine(struct Curl_easy *data, struct connectdata *conn) { CURLcode result = CURLE_OK; - curl_socket_t sock = conn->sock[FIRSTSOCKET]; int imapcode; struct imap_conn *imapc = &conn->proto.imapc; struct pingpong *pp = &imapc->pp; @@ -1316,7 +1315,7 @@ static CURLcode imap_statemachine(struct Curl_easy *data, do { /* Read the response from the server */ - result = Curl_pp_readresp(data, sock, pp, &imapcode, &nread); + result = Curl_pp_readresp(data, FIRSTSOCKET, pp, &imapcode, &nread); if(result) return result; @@ -1694,7 +1693,7 @@ static CURLcode imap_dophase_done(struct Curl_easy *data, bool connected) if(imap->transfer != PPTRANSFER_BODY) /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); return CURLE_OK; } diff --git a/lib/krb5.c b/lib/krb5.c index 4db19fb27fa..885319e00fe 100644 --- a/lib/krb5.c +++ b/lib/krb5.c @@ -52,6 +52,7 @@ #include "ftp.h" #include "curl_gssapi.h" #include "sendf.h" +#include "transfer.h" #include "curl_krb5.h" #include "warnless.h" #include "strcase.h" @@ -90,8 +91,7 @@ static CURLcode ftpsend(struct Curl_easy *data, struct connectdata *conn, #ifdef HAVE_GSSAPI conn->data_prot = PROT_CMD; #endif - result = Curl_nwrite(data, FIRSTSOCKET, sptr, write_len, - &bytes_written); + result = Curl_xfer_send(data, sptr, write_len, &bytes_written); #ifdef HAVE_GSSAPI DEBUGASSERT(data_sec > PROT_NONE && data_sec < PROT_LAST); conn->data_prot = data_sec; @@ -470,7 +470,7 @@ socket_read(struct Curl_easy *data, int sockindex, void *to, size_t len) ssize_t nread = 0; while(len > 0) { - nread = Curl_conn_recv(data, sockindex, to_p, len, &result); + result = Curl_conn_recv(data, sockindex, to_p, len, &nread); if(nread > 0) { len -= nread; to_p += nread; @@ -497,8 +497,8 @@ socket_write(struct Curl_easy *data, int sockindex, const void *to, ssize_t written; while(len > 0) { - written = Curl_conn_send(data, sockindex, to_p, len, &result); - if(written > 0) { + result = Curl_conn_send(data, sockindex, to_p, len, &written); + if(!result && written > 0) { len -= written; to_p += written; } @@ -567,8 +567,11 @@ static ssize_t sec_recv(struct Curl_easy *data, int sockindex, *err = CURLE_OK; /* Handle clear text response. */ - if(conn->sec_complete == 0 || conn->data_prot == PROT_CLEAR) - return Curl_conn_recv(data, sockindex, buffer, len, err); + if(conn->sec_complete == 0 || conn->data_prot == PROT_CLEAR) { + ssize_t nread; + *err = Curl_conn_recv(data, sockindex, buffer, len, &nread); + return nread; + } if(conn->in_buffer.eof_flag) { conn->in_buffer.eof_flag = 0; diff --git a/lib/ldap.c b/lib/ldap.c index 4c04647f4f5..53497a5c41e 100644 --- a/lib/ldap.c +++ b/lib/ldap.c @@ -749,7 +749,7 @@ static CURLcode ldap_do(struct Curl_easy *data, bool *done) FREE_ON_WINLDAP(host); /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); connclose(conn, "LDAP connection always disable reuse"); return result; diff --git a/lib/mqtt.c b/lib/mqtt.c index 5a9d6d0f10a..b0aafc79707 100644 --- a/lib/mqtt.c +++ b/lib/mqtt.c @@ -120,7 +120,7 @@ static CURLcode mqtt_send(struct Curl_easy *data, CURLcode result = CURLE_OK; struct MQTT *mq = data->req.p.mqtt; ssize_t n; - result = Curl_nwrite(data, FIRSTSOCKET, buf, len, &n); + result = Curl_xfer_send(data, buf, len, &n); if(result) return result; Curl_debug(data, CURLINFO_HEADER_OUT, buf, (size_t)n); @@ -366,8 +366,7 @@ static CURLcode mqtt_recv_atleast(struct Curl_easy *data, size_t nbytes) ssize_t nread; DEBUGASSERT(nbytes - rlen < sizeof(readbuf)); - result = Curl_read(data, data->conn->sock[FIRSTSOCKET], - (char *)readbuf, nbytes - rlen, &nread); + result = Curl_xfer_recv(data, (char *)readbuf, nbytes - rlen, &nread); if(result) return result; DEBUGASSERT(nread >= 0); @@ -622,7 +621,6 @@ static CURLcode mqtt_read_publish(struct Curl_easy *data, bool *done) { CURLcode result = CURLE_OK; struct connectdata *conn = data->conn; - curl_socket_t sockfd = conn->sock[FIRSTSOCKET]; ssize_t nread; size_t remlen; struct mqtt_conn *mqtt = &conn->proto.mqtt; @@ -679,7 +677,7 @@ static CURLcode mqtt_read_publish(struct Curl_easy *data, bool *done) size_t rest = mq->npacket; if(rest > sizeof(buffer)) rest = sizeof(buffer); - result = Curl_read(data, sockfd, buffer, rest, &nread); + result = Curl_xfer_recv(data, buffer, rest, &nread); if(result) { if(CURLE_AGAIN == result) { infof(data, "EEEE AAAAGAIN"); @@ -744,7 +742,6 @@ static CURLcode mqtt_doing(struct Curl_easy *data, bool *done) struct mqtt_conn *mqtt = &conn->proto.mqtt; struct MQTT *mq = data->req.p.mqtt; ssize_t nread; - curl_socket_t sockfd = conn->sock[FIRSTSOCKET]; unsigned char byte; *done = FALSE; @@ -762,7 +759,7 @@ static CURLcode mqtt_doing(struct Curl_easy *data, bool *done) switch(mqtt->state) { case MQTT_FIRST: /* Read the initial byte only */ - result = Curl_read(data, sockfd, (char *)&mq->firstbyte, 1, &nread); + result = Curl_xfer_recv(data, (char *)&mq->firstbyte, 1, &nread); if(result) break; else if(!nread) { @@ -778,7 +775,7 @@ static CURLcode mqtt_doing(struct Curl_easy *data, bool *done) FALLTHROUGH(); case MQTT_REMAINING_LENGTH: do { - result = Curl_read(data, sockfd, (char *)&byte, 1, &nread); + result = Curl_xfer_recv(data, (char *)&byte, 1, &nread); if(!nread) break; Curl_debug(data, CURLINFO_HEADER_IN, (char *)&byte, 1); diff --git a/lib/multi.c b/lib/multi.c index 1c8c362f18a..c6869a3155c 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -706,9 +706,10 @@ static CURLcode multi_done(struct Curl_easy *data, process_pending_handles(data->multi); /* connection / multiplex */ - Curl_safefree(data->state.ulbuf); + if(!result) + result = Curl_req_done(&data->req, data, premature); - Curl_client_cleanup(data); + Curl_safefree(data->state.ulbuf); CONNCACHE_LOCK(data); Curl_detach_connection(data); @@ -1007,7 +1008,7 @@ static int connecting_getsock(struct Curl_easy *data, curl_socket_t *socks) { struct connectdata *conn = data->conn; (void)socks; - /* Not using `conn->sockfd` as `Curl_setup_transfer()` initializes + /* Not using `conn->sockfd` as `Curl_xfer_setup()` initializes * that *after* the connect. */ if(conn && conn->sock[FIRSTSOCKET] != CURL_SOCKET_BAD) { /* Default is to wait to something from the server */ diff --git a/lib/openldap.c b/lib/openldap.c index 1e60ff7387d..47266f64e44 100644 --- a/lib/openldap.c +++ b/lib/openldap.c @@ -916,7 +916,7 @@ static CURLcode oldap_do(struct Curl_easy *data, bool *done) else { lr->msgid = msgid; data->req.p.ldap = lr; - Curl_setup_transfer(data, FIRSTSOCKET, -1, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, FALSE, -1); *done = TRUE; } } diff --git a/lib/pingpong.c b/lib/pingpong.c index b976ffbeac5..c12f7cd7b63 100644 --- a/lib/pingpong.c +++ b/lib/pingpong.c @@ -199,8 +199,11 @@ CURLcode Curl_pp_vsendf(struct Curl_easy *data, #ifdef HAVE_GSSAPI conn->data_prot = PROT_CMD; #endif - result = Curl_nwrite(data, FIRSTSOCKET, s, write_len, &bytes_written); - if(result) + result = Curl_conn_send(data, FIRSTSOCKET, s, write_len, &bytes_written); + if(result == CURLE_AGAIN) { + bytes_written = 0; + } + else if(result) return result; #ifdef HAVE_GSSAPI data_sec = conn->data_prot; @@ -251,7 +254,7 @@ CURLcode Curl_pp_sendf(struct Curl_easy *data, struct pingpong *pp, } static CURLcode pingpong_read(struct Curl_easy *data, - curl_socket_t sockfd, + int sockindex, char *buffer, size_t buflen, ssize_t *nread) @@ -261,7 +264,7 @@ static CURLcode pingpong_read(struct Curl_easy *data, enum protection_level prot = data->conn->data_prot; data->conn->data_prot = PROT_CLEAR; #endif - result = Curl_read(data, sockfd, buffer, buflen, nread); + result = Curl_conn_recv(data, sockindex, buffer, buflen, nread); #ifdef HAVE_GSSAPI DEBUGASSERT(prot > PROT_NONE && prot < PROT_LAST); data->conn->data_prot = (unsigned char)prot; @@ -275,7 +278,7 @@ static CURLcode pingpong_read(struct Curl_easy *data, * Reads a piece of a server response. */ CURLcode Curl_pp_readresp(struct Curl_easy *data, - curl_socket_t sockfd, + int sockindex, struct pingpong *pp, int *code, /* return the server code if done */ size_t *size) /* size of the response */ @@ -300,7 +303,7 @@ CURLcode Curl_pp_readresp(struct Curl_easy *data, ssize_t gotbytes = 0; char buffer[900]; - result = pingpong_read(data, sockfd, buffer, sizeof(buffer), &gotbytes); + result = pingpong_read(data, sockindex, buffer, sizeof(buffer), &gotbytes); if(result == CURLE_AGAIN) return CURLE_OK; @@ -396,9 +399,15 @@ CURLcode Curl_pp_flushsend(struct Curl_easy *data, { /* we have a piece of a command still left to send */ ssize_t written; - CURLcode result = Curl_nwrite(data, FIRSTSOCKET, - pp->sendthis + pp->sendsize - pp->sendleft, - pp->sendleft, &written); + CURLcode result; + + result = Curl_conn_send(data, FIRSTSOCKET, + pp->sendthis + pp->sendsize - pp->sendleft, + pp->sendleft, &written); + if(result == CURLE_AGAIN) { + result = CURLE_OK; + written = 0; + } if(result) return result; diff --git a/lib/pingpong.h b/lib/pingpong.h index 006b9c5388f..28172c72842 100644 --- a/lib/pingpong.h +++ b/lib/pingpong.h @@ -132,7 +132,7 @@ CURLcode Curl_pp_vsendf(struct Curl_easy *data, * Reads a piece of a server response. */ CURLcode Curl_pp_readresp(struct Curl_easy *data, - curl_socket_t sockfd, + int sockindex, struct pingpong *pp, int *code, /* return the server code if done */ size_t *size); /* size of the response */ diff --git a/lib/pop3.c b/lib/pop3.c index cf25192828d..993b2e1c7f5 100644 --- a/lib/pop3.c +++ b/lib/pop3.c @@ -934,7 +934,7 @@ static CURLcode pop3_state_command_resp(struct Curl_easy *data, if(pop3->transfer == PPTRANSFER_BODY) { /* POP3 download */ - Curl_setup_transfer(data, FIRSTSOCKET, -1, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, FALSE, -1); if(pp->overflow) { /* The recv buffer contains data that is actually body content so send @@ -970,7 +970,6 @@ static CURLcode pop3_statemachine(struct Curl_easy *data, struct connectdata *conn) { CURLcode result = CURLE_OK; - curl_socket_t sock = conn->sock[FIRSTSOCKET]; int pop3code; struct pop3_conn *pop3c = &conn->proto.pop3c; struct pingpong *pp = &pop3c->pp; @@ -987,7 +986,7 @@ static CURLcode pop3_statemachine(struct Curl_easy *data, do { /* Read the response from the server */ - result = Curl_pp_readresp(data, sock, pp, &pop3code, &nread); + result = Curl_pp_readresp(data, FIRSTSOCKET, pp, &pop3code, &nread); if(result) return result; diff --git a/lib/request.c b/lib/request.c new file mode 100644 index 00000000000..933f8850c36 --- /dev/null +++ b/lib/request.c @@ -0,0 +1,108 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +#include "curl_setup.h" + +#include "urldata.h" +#include "dynbuf.h" +#include "doh.h" +#include "request.h" +#include "sendf.h" +#include "url.h" + +/* The last 3 #include files should be in this order */ +#include "curl_printf.h" +#include "curl_memory.h" +#include "memdebug.h" + +CURLcode Curl_req_init(struct SingleRequest *req) +{ + memset(req, 0, sizeof(*req)); + Curl_bufq_init2(&req->sendbuf, UPLOADBUFFER_DEFAULT, 1, + BUFQ_OPT_SOFT_LIMIT); + return CURLE_OK; +} + +CURLcode Curl_req_start(struct SingleRequest *req, + struct Curl_easy *data) +{ + req->start = Curl_now(); + Curl_cw_reset(data); + return CURLE_OK; +} + +CURLcode Curl_req_done(struct SingleRequest *req, + struct Curl_easy *data, bool aborted) +{ + (void)req; + /* TODO: add flush handling for client output */ + (void)aborted; + Curl_cw_reset(data); + return CURLE_OK; +} + +void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data) +{ + /* This is a bit ugly. `req->p` is a union and we assume we can + * free this safely without leaks. */ + Curl_safefree(req->p.http); + Curl_safefree(req->newurl); + Curl_cw_reset(data); + + Curl_bufq_reset(&req->sendbuf); + if(data->set.upload_buffer_size != req->sendbuf.chunk_size) { + Curl_bufq_free(&req->sendbuf); + Curl_bufq_init2(&req->sendbuf, data->set.upload_buffer_size, 1, + BUFQ_OPT_SOFT_LIMIT); + } + +#ifndef CURL_DISABLE_DOH + if(req->doh) { + Curl_close(&req->doh->probe[0].easy); + Curl_close(&req->doh->probe[1].easy); + } +#endif +} + +void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data) +{ + /* This is a bit ugly. `req->p` is a union and we assume we can + * free this safely without leaks. */ + Curl_safefree(req->p.http); + Curl_safefree(req->newurl); + Curl_bufq_free(&req->sendbuf); + Curl_cw_reset(data); + +#ifndef CURL_DISABLE_DOH + if(req->doh) { + Curl_close(&req->doh->probe[0].easy); + Curl_close(&req->doh->probe[1].easy); + Curl_dyn_free(&req->doh->probe[0].serverdoh); + Curl_dyn_free(&req->doh->probe[1].serverdoh); + curl_slist_free_all(req->doh->headers); + Curl_safefree(req->doh); + } +#endif +} + diff --git a/lib/request.h b/lib/request.h new file mode 100644 index 00000000000..c769e0e1ff6 --- /dev/null +++ b/lib/request.h @@ -0,0 +1,192 @@ +#ifndef HEADER_CURL_REQUEST_H +#define HEADER_CURL_REQUEST_H +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +/* This file is for lib internal stuff */ + +#include "curl_setup.h" + +#include "bufq.h" + +/* forward declarations */ +struct UserDefined; + +enum expect100 { + EXP100_SEND_DATA, /* enough waiting, just send the body now */ + EXP100_AWAITING_CONTINUE, /* waiting for the 100 Continue header */ + EXP100_SENDING_REQUEST, /* still sending the request but will wait for + the 100 header once done with the request */ + EXP100_FAILED /* used on 417 Expectation Failed */ +}; + +enum upgrade101 { + UPGR101_INIT, /* default state */ + UPGR101_WS, /* upgrade to WebSockets requested */ + UPGR101_H2, /* upgrade to HTTP/2 requested */ + UPGR101_RECEIVED, /* 101 response received */ + UPGR101_WORKING /* talking upgraded protocol */ +}; + + +/* + * Request specific data in the easy handle (Curl_easy). Previously, + * these members were on the connectdata struct but since a conn struct may + * now be shared between different Curl_easys, we store connection-specific + * data here. This struct only keeps stuff that's interesting for *this* + * request, as it will be cleared between multiple ones + */ +struct SingleRequest { + curl_off_t size; /* -1 if unknown at this point */ + curl_off_t maxdownload; /* in bytes, the maximum amount of data to fetch, + -1 means unlimited */ + curl_off_t bytecount; /* total number of bytes read */ + curl_off_t writebytecount; /* number of bytes written */ + + curl_off_t pendingheader; /* this many bytes left to send is actually + header and not body */ + struct curltime start; /* transfer started at this time */ + unsigned int headerbytecount; /* received server headers (not CONNECT + headers) */ + unsigned int allheadercount; /* all received headers (server + CONNECT) */ + unsigned int deductheadercount; /* this amount of bytes doesn't count when + we check if anything has been transferred + at the end of a connection. We use this + counter to make only a 100 reply (without + a following second response code) result + in a CURLE_GOT_NOTHING error code */ + int headerline; /* counts header lines to better track the + first one */ + curl_off_t offset; /* possible resume offset read from the + Content-Range: header */ + int httpcode; /* error code from the 'HTTP/1.? XXX' or + 'RTSP/1.? XXX' line */ + int keepon; + struct curltime start100; /* time stamp to wait for the 100 code from */ + enum expect100 exp100; /* expect 100 continue state */ + enum upgrade101 upgr101; /* 101 upgrade state */ + + /* Client Writer stack, handles trasnfer- and content-encodings, protocol + * checks, pausing by client callbacks. */ + struct Curl_cwriter *writer_stack; + struct bufq sendbuf; /* data which needs to be send to the server */ + time_t timeofdoc; + long bodywrites; + char *location; /* This points to an allocated version of the Location: + header data */ + char *newurl; /* Set to the new URL to use when a redirect or a retry is + wanted */ + + /* 'upload_present' is used to keep a byte counter of how much data there is + still left in the buffer, aimed for upload. */ + ssize_t upload_present; + + /* 'upload_fromhere' is used as a read-pointer when we uploaded parts of a + buffer, so the next read should read from where this pointer points to, + and the 'upload_present' contains the number of bytes available at this + position */ + char *upload_fromhere; + + /* Allocated protocol-specific data. Each protocol handler makes sure this + points to data it needs. */ + union { + struct FILEPROTO *file; + struct FTP *ftp; + struct HTTP *http; + struct IMAP *imap; + struct ldapreqinfo *ldap; + struct MQTT *mqtt; + struct POP3 *pop3; + struct RTSP *rtsp; + struct smb_request *smb; + struct SMTP *smtp; + struct SSHPROTO *ssh; + struct TELNET *telnet; + } p; +#ifndef CURL_DISABLE_DOH + struct dohdata *doh; /* DoH specific data for this request */ +#endif + char fread_eof[2]; /* the body read callback (index 0) returned EOF or + the trailer read callback (index 1) returned EOF */ +#ifndef CURL_DISABLE_COOKIES + unsigned char setcookies; +#endif + BIT(header); /* incoming data has HTTP header */ + BIT(content_range); /* set TRUE if Content-Range: was found */ + BIT(download_done); /* set to TRUE when download is complete */ + BIT(eos_written); /* iff EOS has been written to client */ + BIT(upload_done); /* set to TRUE when doing chunked transfer-encoding + upload and we're uploading the last chunk */ + BIT(ignorebody); /* we read a response-body but we ignore it! */ + BIT(http_bodyless); /* HTTP response status code is between 100 and 199, + 204 or 304 */ + BIT(chunk); /* if set, this is a chunked transfer-encoding */ + BIT(ignore_cl); /* ignore content-length */ + BIT(upload_chunky); /* set TRUE if we are doing chunked transfer-encoding + on upload */ + BIT(getheader); /* TRUE if header parsing is wanted */ + BIT(forbidchunk); /* used only to explicitly forbid chunk-upload for + specific upload buffers. See readmoredata() in http.c + for details. */ + BIT(no_body); /* the response has no body */ + BIT(authneg); /* TRUE when the auth phase has started, which means + that we are creating a request with an auth header, + but it is not the final request in the auth + negotiation. */ +}; + +/** + * Initialize the state of the request for first use. + */ +CURLcode Curl_req_init(struct SingleRequest *req); + +/** + * The request is about to start. + */ +CURLcode Curl_req_start(struct SingleRequest *req, + struct Curl_easy *data); + +/** + * The request is done. If not aborted, make sure that buffers are + * flushed to the client. + * @param req the request + * @param data the transfer + * @param aborted TRUE iff the request was aborted/errored + */ +CURLcode Curl_req_done(struct SingleRequest *req, + struct Curl_easy *data, bool aborted); + +/** + * Free the state of the request, not usable afterwards. + */ +void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data); + +/** + * Reset the state of the request for new use, given the + * settings. + */ +void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data); + + +#endif /* HEADER_CURL_REQUEST_H */ diff --git a/lib/rtsp.c b/lib/rtsp.c index 26f47353447..b4290246ac9 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -310,7 +310,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) } if(rtspreq == RTSPREQ_RECEIVE) { - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); return result; } @@ -573,7 +573,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) return result; } - Curl_setup_transfer(data, FIRSTSOCKET, -1, TRUE, putsize?FIRSTSOCKET:-1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, putsize?FIRSTSOCKET:-1); /* Increment the CSeq on success */ data->state.rtsp_next_client_CSeq++; diff --git a/lib/sendf.c b/lib/sendf.c index 053d74a10c2..54ed6fb2956 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -61,79 +61,6 @@ static CURLcode do_init_stack(struct Curl_easy *data); -/* - * Curl_nwrite() is an internal write function that sends data to the - * server. Works with a socket index for the connection. - * - * If the write would block (CURLE_AGAIN), it returns CURLE_OK and - * (*nwritten == 0). Otherwise we return regular CURLcode value. - */ -CURLcode Curl_nwrite(struct Curl_easy *data, - int sockindex, - const void *buf, - size_t blen, - ssize_t *pnwritten) -{ - ssize_t nwritten; - CURLcode result = CURLE_OK; - struct connectdata *conn; - - DEBUGASSERT(sockindex >= 0 && sockindex < 2); - DEBUGASSERT(pnwritten); - DEBUGASSERT(data); - DEBUGASSERT(data->conn); - conn = data->conn; -#ifdef CURLDEBUG - { - /* Allow debug builds to override this logic to force short sends - */ - char *p = getenv("CURL_SMALLSENDS"); - if(p) { - size_t altsize = (size_t)strtoul(p, NULL, 10); - if(altsize) - blen = CURLMIN(blen, altsize); - } - } -#endif - nwritten = conn->send[sockindex](data, sockindex, buf, blen, &result); - if(result == CURLE_AGAIN) { - nwritten = 0; - result = CURLE_OK; - } - else if(result) { - nwritten = -1; /* make sure */ - } - else { - DEBUGASSERT(nwritten >= 0); - } - - *pnwritten = nwritten; - return result; -} - -/* - * Curl_write() is an internal write function that sends data to the - * server. Works with plain sockets, SCP, SSL or kerberos. - * - * If the write would block (CURLE_AGAIN), we return CURLE_OK and - * (*written == 0). Otherwise we return regular CURLcode value. - */ -CURLcode Curl_write(struct Curl_easy *data, - curl_socket_t sockfd, - const void *mem, - size_t len, - ssize_t *written) -{ - struct connectdata *conn; - int num; - - DEBUGASSERT(data); - DEBUGASSERT(data->conn); - conn = data->conn; - num = (sockfd != CURL_SOCKET_BAD && sockfd == conn->sock[SECONDARYSOCKET]); - return Curl_nwrite(data, num, mem, len, written); -} - /* Curl_client_write() sends data to the write callback(s) The bit pattern defines to what "streams" to write to. Body and/or header. @@ -163,7 +90,7 @@ CURLcode Curl_client_write(struct Curl_easy *data, return Curl_cwriter_write(data, data->req.writer_stack, type, buf, blen); } -void Curl_client_cleanup(struct Curl_easy *data) +void Curl_cw_reset(struct Curl_easy *data) { struct Curl_cwriter *writer = data->req.writer_stack; @@ -499,40 +426,3 @@ void Curl_cwriter_remove_by_name(struct Curl_easy *data, } } -/* - * Internal read-from-socket function. This is meant to deal with plain - * sockets, SSL sockets and kerberos sockets. - * - * Returns a regular CURLcode value. - */ -CURLcode Curl_read(struct Curl_easy *data, /* transfer */ - curl_socket_t sockfd, /* read from this socket */ - char *buf, /* store read data here */ - size_t sizerequested, /* max amount to read */ - ssize_t *n) /* amount bytes read */ -{ - CURLcode result = CURLE_RECV_ERROR; - ssize_t nread = 0; - size_t bytesfromsocket = 0; - char *buffertofill = NULL; - struct connectdata *conn = data->conn; - - /* Set 'num' to 0 or 1, depending on which socket that has been sent here. - If it is the second socket, we set num to 1. Otherwise to 0. This lets - us use the correct ssl handle. */ - int num = (sockfd == conn->sock[SECONDARYSOCKET]); - - *n = 0; /* reset amount to zero */ - - bytesfromsocket = CURLMIN(sizerequested, (size_t)data->set.buffer_size); - buffertofill = buf; - - nread = conn->recv[num](data, num, buffertofill, bytesfromsocket, &result); - if(nread < 0) - goto out; - - *n += nread; - result = CURLE_OK; -out: - return result; -} diff --git a/lib/sendf.h b/lib/sendf.h index e4dba9d78b7..9d3d5946ab3 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -61,7 +61,7 @@ CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *ptr, /** * Free all resources related to client writing. */ -void Curl_client_cleanup(struct Curl_easy *data); +void Curl_cw_reset(struct Curl_easy *data); /** * Client Writers - a chain passing transfer BODY data to the client. @@ -175,22 +175,4 @@ void Curl_cwriter_def_close(struct Curl_easy *data, struct Curl_cwriter *writer); -/* internal read-function, does plain socket, SSL and krb4 */ -CURLcode Curl_read(struct Curl_easy *data, curl_socket_t sockfd, - char *buf, size_t buffersize, - ssize_t *n); - -/* internal write-function, does plain socket, SSL, SCP, SFTP and krb4 */ -CURLcode Curl_write(struct Curl_easy *data, - curl_socket_t sockfd, - const void *mem, size_t len, - ssize_t *written); - -/* internal write-function, using sockindex for connection destination */ -CURLcode Curl_nwrite(struct Curl_easy *data, - int sockindex, - const void *buf, - size_t blen, - ssize_t *pnwritten); - #endif /* HEADER_CURL_SENDF_H */ diff --git a/lib/smb.c b/lib/smb.c index 1d1867cc270..ae585b4c1ae 100644 --- a/lib/smb.c +++ b/lib/smb.c @@ -485,7 +485,6 @@ static CURLcode smb_connect(struct Curl_easy *data, bool *done) static CURLcode smb_recv_message(struct Curl_easy *data, void **msg) { struct connectdata *conn = data->conn; - curl_socket_t sockfd = conn->sock[FIRSTSOCKET]; struct smb_conn *smbc = &conn->proto.smbc; char *buf = smbc->recv_buf; ssize_t bytes_read; @@ -494,7 +493,7 @@ static CURLcode smb_recv_message(struct Curl_easy *data, void **msg) size_t len = MAX_MESSAGE_SIZE - smbc->got; CURLcode result; - result = Curl_read(data, sockfd, buf + smbc->got, len, &bytes_read); + result = Curl_xfer_recv(data, buf + smbc->got, len, &bytes_read); if(result) return result; @@ -568,8 +567,7 @@ static CURLcode smb_send(struct Curl_easy *data, ssize_t len, ssize_t bytes_written; CURLcode result; - result = Curl_nwrite(data, FIRSTSOCKET, data->state.ulbuf, - len, &bytes_written); + result = Curl_xfer_send(data, data->state.ulbuf, len, &bytes_written); if(result) return result; @@ -594,9 +592,8 @@ static CURLcode smb_flush(struct Curl_easy *data) if(!smbc->send_size) return CURLE_OK; - result = Curl_nwrite(data, FIRSTSOCKET, - data->state.ulbuf + smbc->sent, - len, &bytes_written); + result = Curl_xfer_send(data, data->state.ulbuf + smbc->sent, len, + &bytes_written); if(result) return result; diff --git a/lib/smtp.c b/lib/smtp.c index 0d18afc1c54..e10a00477b1 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -1164,7 +1164,7 @@ static CURLcode smtp_state_data_resp(struct Curl_easy *data, int smtpcode, Curl_pgrsSetUploadSize(data, data->state.infilesize); /* SMTP upload */ - Curl_setup_transfer(data, -1, -1, FALSE, FIRSTSOCKET); + Curl_xfer_setup(data, -1, -1, FALSE, FIRSTSOCKET); /* End of DO phase */ smtp_state(data, SMTP_STOP); @@ -1196,7 +1196,6 @@ static CURLcode smtp_statemachine(struct Curl_easy *data, struct connectdata *conn) { CURLcode result = CURLE_OK; - curl_socket_t sock = conn->sock[FIRSTSOCKET]; int smtpcode; struct smtp_conn *smtpc = &conn->proto.smtpc; struct pingpong *pp = &smtpc->pp; @@ -1212,7 +1211,7 @@ static CURLcode smtp_statemachine(struct Curl_easy *data, do { /* Read the response from the server */ - result = Curl_pp_readresp(data, sock, pp, &smtpcode, &nread); + result = Curl_pp_readresp(data, FIRSTSOCKET, pp, &smtpcode, &nread); if(result) return result; @@ -1434,7 +1433,7 @@ static CURLcode smtp_done(struct Curl_easy *data, CURLcode status, return CURLE_OUT_OF_MEMORY; /* Send the end of block data */ - result = Curl_write(data, conn->writesockfd, eob, len, &bytes_written); + result = Curl_xfer_send(data, eob, len, &bytes_written); if(result) { free(eob); return result; @@ -1595,7 +1594,7 @@ static CURLcode smtp_dophase_done(struct Curl_easy *data, bool connected) if(smtp->transfer != PPTRANSFER_BODY) /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); return CURLE_OK; } diff --git a/lib/telnet.c b/lib/telnet.c index 34dc5e80670..9b6ae3c611a 100644 --- a/lib/telnet.c +++ b/lib/telnet.c @@ -1270,8 +1270,8 @@ static CURLcode send_telnet_data(struct Curl_easy *data, break; default: /* write! */ bytes_written = 0; - result = Curl_nwrite(data, FIRSTSOCKET, outbuf + total_written, - outlen - total_written, &bytes_written); + result = Curl_xfer_send(data, outbuf + total_written, + outlen - total_written, &bytes_written); total_written += bytes_written; break; } @@ -1464,7 +1464,7 @@ static CURLcode telnet_do(struct Curl_easy *data, bool *done) } if(events.lNetworkEvents & FD_READ) { /* read data from network */ - result = Curl_read(data, sockfd, buffer, sizeof(buffer), &nread); + result = Curl_xfer_recv(data, buffer, sizeof(buffer), &nread); /* read would've blocked. Loop again */ if(result == CURLE_AGAIN) break; @@ -1545,7 +1545,7 @@ static CURLcode telnet_do(struct Curl_easy *data, bool *done) default: /* read! */ if(pfd[0].revents & POLLIN) { /* read data from network */ - result = Curl_read(data, sockfd, buffer, sizeof(buffer), &nread); + result = Curl_xfer_recv(data, buffer, sizeof(buffer), &nread); /* read would've blocked. Loop again */ if(result == CURLE_AGAIN) break; @@ -1635,7 +1635,7 @@ static CURLcode telnet_do(struct Curl_easy *data, bool *done) } #endif /* mark this as "no further transfer wanted" */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); return result; } diff --git a/lib/tftp.c b/lib/tftp.c index 4288110da66..1b487796056 100644 --- a/lib/tftp.c +++ b/lib/tftp.c @@ -1240,7 +1240,7 @@ static CURLcode tftp_multi_statemach(struct Curl_easy *data, bool *done) *done = (state->state == TFTP_STATE_FIN) ? TRUE : FALSE; if(*done) /* Tell curl we're done */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); } else { /* no timeouts to handle, check our socket */ @@ -1263,7 +1263,7 @@ static CURLcode tftp_multi_statemach(struct Curl_easy *data, bool *done) *done = (state->state == TFTP_STATE_FIN) ? TRUE : FALSE; if(*done) /* Tell curl we're done */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); } /* if rc == 0, then select() timed out */ } diff --git a/lib/transfer.c b/lib/transfer.c index 36ca444b195..1935909b91a 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -448,7 +448,7 @@ static ssize_t Curl_xfer_recv_resp(struct Curl_easy *data, return 0; } - *err = Curl_read(data, data->conn->sockfd, buf, blen, &nread); + *err = Curl_xfer_recv(data, buf, blen, &nread); if(*err) return -1; DEBUGASSERT(nread >= 0); @@ -770,12 +770,14 @@ static CURLcode readwrite_upload(struct Curl_easy *data, that instead of reading more data */ } + if(!Curl_bufq_is_empty(&k->sendbuf)) { + DEBUGASSERT(0); + } /* write to socket (send away data) */ - result = Curl_write(data, - conn->writesockfd, /* socket to send to */ - k->upload_fromhere, /* buffer pointer */ - k->upload_present, /* buffer size */ - &bytes_written); /* actually sent */ + result = Curl_xfer_send(data, + k->upload_fromhere, /* buffer pointer */ + k->upload_present, /* buffer size */ + &bytes_written); /* actually sent */ if(result) return result; @@ -1590,11 +1592,10 @@ CURLcode Curl_retry_request(struct Curl_easy *data, char **url) } /* - * Curl_setup_transfer() is called to setup some basic properties for the + * Curl_xfer_setup() is called to setup some basic properties for the * upcoming transfer. */ -void -Curl_setup_transfer( +void Curl_xfer_setup( struct Curl_easy *data, /* transfer */ int sockindex, /* socket index to read from or -1 */ curl_off_t size, /* -1 if unknown at this point */ @@ -1610,6 +1611,7 @@ Curl_setup_transfer( DEBUGASSERT(conn != NULL); DEBUGASSERT((sockindex <= 1) && (sockindex >= -1)); + DEBUGASSERT((writesockindex <= 1) && (writesockindex >= -1)); httpsending = ((conn->handler->protocol&PROTO_FAMILY_HTTP) && (http->sending == HTTPSEND_REQUEST)); @@ -1727,3 +1729,51 @@ CURLcode Curl_xfer_write_done(struct Curl_easy *data, bool premature) (void)premature; return Curl_cw_out_done(data); } + +CURLcode Curl_xfer_send(struct Curl_easy *data, + const void *buf, size_t blen, + ssize_t *pnwritten) +{ + CURLcode result; + int sockindex; + + if(!data || !data->conn) + return CURLE_FAILED_INIT; + /* FIXME: would like to enable this, but some protocols (MQTT) do not + * setup the transfer correctly, it seems + if(data->conn->writesockfd == CURL_SOCKET_BAD) { + failf(data, "transfer not setup for sending"); + DEBUGASSERT(0); + return CURLE_SEND_ERROR; + } */ + sockindex = ((data->conn->writesockfd != CURL_SOCKET_BAD) && + (data->conn->writesockfd == data->conn->sock[SECONDARYSOCKET])); + result = Curl_conn_send(data, sockindex, buf, blen, pnwritten); + if(result == CURLE_AGAIN) { + result = CURLE_OK; + *pnwritten = 0; + } + return result; +} + +CURLcode Curl_xfer_recv(struct Curl_easy *data, + char *buf, size_t blen, + ssize_t *pnrcvd) +{ + int sockindex; + + if(!data || !data->conn) + return CURLE_FAILED_INIT; + /* FIXME: would like to enable this, but some protocols (MQTT) do not + * setup the transfer correctly, it seems + if(data->conn->sockfd == CURL_SOCKET_BAD) { + failf(data, "transfer not setup for receiving"); + DEBUGASSERT(0); + return CURLE_RECV_ERROR; + } */ + sockindex = ((data->conn->sockfd != CURL_SOCKET_BAD) && + (data->conn->sockfd == data->conn->sock[SECONDARYSOCKET])); + if(data->set.buffer_size > 0 && (size_t)data->set.buffer_size < blen) + blen = (size_t)data->set.buffer_size; + return Curl_conn_recv(data, sockindex, buf, blen, pnrcvd); +} diff --git a/lib/transfer.h b/lib/transfer.h index 6de418c5644..917a3d23e4a 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -75,8 +75,7 @@ CURLcode Curl_xfer_write_resp(struct Curl_easy *data, bool is_eos, bool *done); /* This sets up a forthcoming transfer */ -void -Curl_setup_transfer (struct Curl_easy *data, +void Curl_xfer_setup(struct Curl_easy *data, int sockindex, /* socket index to read from or -1 */ curl_off_t size, /* -1 if unknown at this point */ bool getheader, /* TRUE if header parsing is wanted */ @@ -91,4 +90,22 @@ Curl_setup_transfer (struct Curl_easy *data, */ CURLcode Curl_xfer_write_done(struct Curl_easy *data, bool premature); +/** + * Send data on the socket/connection filter designated + * for transfer's outgoing data. + * Will return CURLE_OK on blocking with (*pnwritten == 0). + */ +CURLcode Curl_xfer_send(struct Curl_easy *data, + const void *buf, size_t blen, + ssize_t *pnwritten); + +/** + * Receive data on the socket/connection filter designated + * for transfer's incoming data. + * Will return CURLE_AGAIN on blocking with (*pnrcvd == 0). + */ +CURLcode Curl_xfer_recv(struct Curl_easy *data, + char *buf, size_t blen, + ssize_t *pnrcvd); + #endif /* HEADER_CURL_TRANSFER_H */ diff --git a/lib/url.c b/lib/url.c index 21bd66b45e0..ae976d7b11d 100644 --- a/lib/url.c +++ b/lib/url.c @@ -261,7 +261,7 @@ CURLcode Curl_close(struct Curl_easy **datap) free(data->state.range); /* freed here just in case DONE wasn't called */ - Curl_free_request_state(data); + Curl_req_free(&data->req, data); /* Close down all open SSL info and sessions */ Curl_ssl_close_all(data); @@ -269,10 +269,6 @@ CURLcode Curl_close(struct Curl_easy **datap) Curl_safefree(data->state.scratch); Curl_ssl_free_certinfo(data); - /* Cleanup possible redirect junk */ - free(data->req.newurl); - data->req.newurl = NULL; - if(data->state.referer_alloc) { Curl_safefree(data->state.referer); data->state.referer_alloc = FALSE; @@ -325,15 +321,6 @@ CURLcode Curl_close(struct Curl_easy **datap) Curl_safefree(data->state.aptr.proxyuser); Curl_safefree(data->state.aptr.proxypasswd); -#ifndef CURL_DISABLE_DOH - if(data->req.doh) { - Curl_dyn_free(&data->req.doh->probe[0].serverdoh); - Curl_dyn_free(&data->req.doh->probe[1].serverdoh); - curl_slist_free_all(data->req.doh->headers); - Curl_safefree(data->req.doh); - } -#endif - #if !defined(CURL_DISABLE_HTTP) && !defined(CURL_DISABLE_FORM_API) Curl_mime_cleanpart(data->state.formp); Curl_safefree(data->state.formp); @@ -519,9 +506,17 @@ CURLcode Curl_open(struct Curl_easy **curl) data->magic = CURLEASY_MAGIC_NUMBER; + result = Curl_req_init(&data->req); + if(result) { + DEBUGF(fprintf(stderr, "Error: request init failed\n")); + free(data); + return result; + } + result = Curl_resolver_init(data, &data->state.async.resolver); if(result) { DEBUGF(fprintf(stderr, "Error: resolver_init failed\n")); + Curl_req_free(&data->req, data); free(data); return result; } @@ -545,6 +540,7 @@ CURLcode Curl_open(struct Curl_easy **curl) Curl_resolver_cleanup(data->state.async.resolver); Curl_dyn_free(&data->state.headerb); Curl_freeset(data); + Curl_req_free(&data->req, data); free(data); data = NULL; } @@ -2054,24 +2050,6 @@ static CURLcode setup_connection_internals(struct Curl_easy *data, return CURLE_OK; } -/* - * Curl_free_request_state() should free temp data that was allocated in the - * Curl_easy for this single request. - */ - -void Curl_free_request_state(struct Curl_easy *data) -{ - Curl_safefree(data->req.p.http); - Curl_safefree(data->req.newurl); -#ifndef CURL_DISABLE_DOH - if(data->req.doh) { - Curl_close(&data->req.doh->probe[0].easy); - Curl_close(&data->req.doh->probe[1].easy); - } -#endif - Curl_client_cleanup(data); -} - #ifndef CURL_DISABLE_PROXY @@ -3609,7 +3587,7 @@ static CURLcode create_conn(struct Curl_easy *data, (void)conn->handler->done(data, result, FALSE); goto out; } - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); } /* since we skip do_init() */ @@ -3620,10 +3598,10 @@ static CURLcode create_conn(struct Curl_easy *data, #endif /* Setup filter for network connections */ - conn->recv[FIRSTSOCKET] = Curl_conn_recv; - conn->send[FIRSTSOCKET] = Curl_conn_send; - conn->recv[SECONDARYSOCKET] = Curl_conn_recv; - conn->send[SECONDARYSOCKET] = Curl_conn_send; + conn->recv[FIRSTSOCKET] = Curl_cf_recv; + conn->send[FIRSTSOCKET] = Curl_cf_send; + conn->recv[SECONDARYSOCKET] = Curl_cf_recv; + conn->send[SECONDARYSOCKET] = Curl_cf_send; conn->bits.tcp_fastopen = data->set.tcp_fastopen; /* Complete the easy's SSL configuration for connection cache matching */ @@ -3866,7 +3844,7 @@ CURLcode Curl_connect(struct Curl_easy *data, *asyncp = FALSE; /* assume synchronous resolves by default */ /* init the single-transfer specific data */ - Curl_free_request_state(data); + Curl_req_reset(&data->req, data); memset(&data->req, 0, sizeof(struct SingleRequest)); data->req.size = data->req.maxdownload = -1; data->req.no_body = data->set.opt_no_body; @@ -3935,12 +3913,14 @@ CURLcode Curl_init_do(struct Curl_easy *data, struct connectdata *conn) /* in HTTP lingo, no body means using the HEAD request... */ data->state.httpreq = HTTPREQ_HEAD; - k->start = Curl_now(); /* start time */ + result = Curl_req_start(&data->req, data); + if(result) + return result; + k->header = TRUE; /* assume header */ k->bytecount = 0; k->ignorebody = FALSE; - Curl_client_cleanup(data); Curl_speedinit(data); Curl_pgrsSetUploadCounter(data, 0); Curl_pgrsSetDownloadCounter(data, 0); diff --git a/lib/url.h b/lib/url.h index 7c1a29bc3cc..6d369508337 100644 --- a/lib/url.h +++ b/lib/url.h @@ -41,7 +41,6 @@ void Curl_disconnect(struct Curl_easy *data, struct connectdata *, bool dead_connection); CURLcode Curl_setup_conn(struct Curl_easy *data, bool *protocol_done); -void Curl_free_request_state(struct Curl_easy *data); CURLcode Curl_parse_login_details(const char *login, const size_t len, char **userptr, char **passwdptr, char **optionsptr); diff --git a/lib/urldata.h b/lib/urldata.h index 59f290b7279..3d68a60563a 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -143,6 +143,7 @@ typedef unsigned int curl_prot_t; #include "splay.h" #include "dynbuf.h" #include "dynhds.h" +#include "request.h" /* return the count of bytes sent, or -1 on error */ typedef ssize_t (Curl_send)(struct Curl_easy *data, /* transfer */ @@ -616,22 +617,6 @@ struct easy_pollset { unsigned char actions[MAX_SOCKSPEREASYHANDLE]; }; -enum expect100 { - EXP100_SEND_DATA, /* enough waiting, just send the body now */ - EXP100_AWAITING_CONTINUE, /* waiting for the 100 Continue header */ - EXP100_SENDING_REQUEST, /* still sending the request but will wait for - the 100 header once done with the request */ - EXP100_FAILED /* used on 417 Expectation Failed */ -}; - -enum upgrade101 { - UPGR101_INIT, /* default state */ - UPGR101_WS, /* upgrade to WebSockets requested */ - UPGR101_H2, /* upgrade to HTTP/2 requested */ - UPGR101_RECEIVED, /* 101 response received */ - UPGR101_WORKING /* talking upgraded protocol */ -}; - enum doh_slots { /* Explicit values for first two symbols so as to match hard-coded * constants in existing code @@ -650,111 +635,6 @@ enum doh_slots { DOH_PROBE_SLOTS }; -/* - * Request specific data in the easy handle (Curl_easy). Previously, - * these members were on the connectdata struct but since a conn struct may - * now be shared between different Curl_easys, we store connection-specific - * data here. This struct only keeps stuff that's interesting for *this* - * request, as it will be cleared between multiple ones - */ -struct SingleRequest { - curl_off_t size; /* -1 if unknown at this point */ - curl_off_t maxdownload; /* in bytes, the maximum amount of data to fetch, - -1 means unlimited */ - curl_off_t bytecount; /* total number of bytes read */ - curl_off_t writebytecount; /* number of bytes written */ - - curl_off_t pendingheader; /* this many bytes left to send is actually - header and not body */ - struct curltime start; /* transfer started at this time */ - unsigned int headerbytecount; /* received server headers (not CONNECT - headers) */ - unsigned int allheadercount; /* all received headers (server + CONNECT) */ - unsigned int deductheadercount; /* this amount of bytes doesn't count when - we check if anything has been transferred - at the end of a connection. We use this - counter to make only a 100 reply (without - a following second response code) result - in a CURLE_GOT_NOTHING error code */ - int headerline; /* counts header lines to better track the - first one */ - curl_off_t offset; /* possible resume offset read from the - Content-Range: header */ - int httpcode; /* error code from the 'HTTP/1.? XXX' or - 'RTSP/1.? XXX' line */ - int keepon; - struct curltime start100; /* time stamp to wait for the 100 code from */ - enum expect100 exp100; /* expect 100 continue state */ - enum upgrade101 upgr101; /* 101 upgrade state */ - - /* Client Writer stack, handles trasnfer- and content-encodings, protocol - * checks, pausing by client callbacks. */ - struct Curl_cwriter *writer_stack; - time_t timeofdoc; - long bodywrites; - char *location; /* This points to an allocated version of the Location: - header data */ - char *newurl; /* Set to the new URL to use when a redirect or a retry is - wanted */ - - /* 'upload_present' is used to keep a byte counter of how much data there is - still left in the buffer, aimed for upload. */ - ssize_t upload_present; - - /* 'upload_fromhere' is used as a read-pointer when we uploaded parts of a - buffer, so the next read should read from where this pointer points to, - and the 'upload_present' contains the number of bytes available at this - position */ - char *upload_fromhere; - - /* Allocated protocol-specific data. Each protocol handler makes sure this - points to data it needs. */ - union { - struct FILEPROTO *file; - struct FTP *ftp; - struct HTTP *http; - struct IMAP *imap; - struct ldapreqinfo *ldap; - struct MQTT *mqtt; - struct POP3 *pop3; - struct RTSP *rtsp; - struct smb_request *smb; - struct SMTP *smtp; - struct SSHPROTO *ssh; - struct TELNET *telnet; - } p; -#ifndef CURL_DISABLE_DOH - struct dohdata *doh; /* DoH specific data for this request */ -#endif - char fread_eof[2]; /* the body read callback (index 0) returned EOF or - the trailer read callback (index 1) returned EOF */ -#ifndef CURL_DISABLE_COOKIES - unsigned char setcookies; -#endif - BIT(header); /* incoming data has HTTP header */ - BIT(content_range); /* set TRUE if Content-Range: was found */ - BIT(download_done); /* set to TRUE when download is complete */ - BIT(eos_written); /* iff EOS has been written to client */ - BIT(upload_done); /* set to TRUE when doing chunked transfer-encoding - upload and we're uploading the last chunk */ - BIT(ignorebody); /* we read a response-body but we ignore it! */ - BIT(http_bodyless); /* HTTP response status code is between 100 and 199, - 204 or 304 */ - BIT(chunk); /* if set, this is a chunked transfer-encoding */ - BIT(ignore_cl); /* ignore content-length */ - BIT(upload_chunky); /* set TRUE if we are doing chunked transfer-encoding - on upload */ - BIT(getheader); /* TRUE if header parsing is wanted */ - BIT(forbidchunk); /* used only to explicitly forbid chunk-upload for - specific upload buffers. See readmoredata() in http.c - for details. */ - BIT(no_body); /* the response has no body */ - BIT(authneg); /* TRUE when the auth phase has started, which means - that we are creating a request with an auth header, - but it is not the final request in the auth - negotiation. */ -}; - /* * Specific protocol handler. */ diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index 02148d0c187..7cfc9502166 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -1349,9 +1349,9 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) Curl_pgrsSetUploadSize(data, data->state.infilesize); } /* upload data */ - Curl_setup_transfer(data, -1, -1, FALSE, FIRSTSOCKET); + Curl_xfer_setup(data, -1, -1, FALSE, FIRSTSOCKET); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->sockfd = conn->writesockfd; /* store this original bitmask setup to use later on if we can't @@ -1575,7 +1575,7 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) sshc->sftp_dir = NULL; /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); state(data, SSH_STOP); break; @@ -1720,14 +1720,14 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) /* Setup the actual download */ if(data->req.size == 0) { /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); infof(data, "File already completely downloaded"); state(data, SSH_STOP); break; } - Curl_setup_transfer(data, FIRSTSOCKET, data->req.size, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, data->req.size, FALSE, -1); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->writesockfd = conn->sockfd; /* we want to use the _receiving_ function even when the socket turns @@ -1849,9 +1849,9 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) } /* upload data */ - Curl_setup_transfer(data, -1, data->req.size, FALSE, FIRSTSOCKET); + Curl_xfer_setup(data, -1, data->req.size, FALSE, FIRSTSOCKET); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->sockfd = conn->writesockfd; /* store this original bitmask setup to use later on if we can't @@ -1893,9 +1893,9 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) /* download data */ bytecount = ssh_scp_request_get_size(sshc->scp_session); data->req.maxdownload = (curl_off_t) bytecount; - Curl_setup_transfer(data, FIRSTSOCKET, bytecount, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, bytecount, FALSE, -1); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->writesockfd = conn->sockfd; /* we want to use the _receiving_ function even when the socket turns diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index 3a661f81eb2..33dbe1c9200 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -2195,9 +2195,9 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) Curl_pgrsSetUploadSize(data, data->state.infilesize); } /* upload data */ - Curl_setup_transfer(data, -1, -1, FALSE, FIRSTSOCKET); + Curl_xfer_setup(data, -1, -1, FALSE, FIRSTSOCKET); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->sockfd = conn->writesockfd; if(result) { @@ -2448,7 +2448,7 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) Curl_safefree(sshp->readdir_longentry); /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); state(data, SSH_STOP); break; @@ -2590,14 +2590,14 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) /* Setup the actual download */ if(data->req.size == 0) { /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); infof(data, "File already completely downloaded"); state(data, SSH_STOP); break; } - Curl_setup_transfer(data, FIRSTSOCKET, data->req.size, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, data->req.size, FALSE, -1); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->writesockfd = conn->sockfd; /* we want to use the _receiving_ function even when the socket turns @@ -2741,9 +2741,9 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) /* upload data */ data->req.size = data->state.infilesize; Curl_pgrsSetUploadSize(data, data->state.infilesize); - Curl_setup_transfer(data, -1, -1, FALSE, FIRSTSOCKET); + Curl_xfer_setup(data, -1, -1, FALSE, FIRSTSOCKET); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->sockfd = conn->writesockfd; if(result) { @@ -2812,9 +2812,9 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) /* download data */ bytecount = (curl_off_t)sb.st_size; data->req.maxdownload = (curl_off_t)sb.st_size; - Curl_setup_transfer(data, FIRSTSOCKET, bytecount, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, bytecount, FALSE, -1); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->writesockfd = conn->sockfd; /* we want to use the _receiving_ function even when the socket turns @@ -3193,12 +3193,13 @@ static ssize_t ssh_tls_recv(libssh2_socket_t sock, void *buffer, struct connectdata *conn = data->conn; Curl_recv *backup = conn->recv[0]; struct ssh_conn *ssh = &conn->proto.sshc; + int socknum = Curl_conn_sockindex(data, sock); (void)flags; /* swap in the TLS reader function for this call only, and then swap back the SSH one again */ conn->recv[0] = ssh->tls_recv; - result = Curl_read(data, sock, buffer, length, &nread); + result = Curl_conn_recv(data, socknum, buffer, length, &nread); conn->recv[0] = backup; if(result == CURLE_AGAIN) return -EAGAIN; /* magic return code for libssh2 */ @@ -3217,12 +3218,13 @@ static ssize_t ssh_tls_send(libssh2_socket_t sock, const void *buffer, struct connectdata *conn = data->conn; Curl_send *backup = conn->send[0]; struct ssh_conn *ssh = &conn->proto.sshc; + int socknum = Curl_conn_sockindex(data, sock); (void)flags; /* swap in the TLS writer function for this call only, and then swap back the SSH one again */ conn->send[0] = ssh->tls_send; - result = Curl_write(data, sock, buffer, length, &nwrite); + result = Curl_conn_send(data, socknum, buffer, length, &nwrite); conn->send[0] = backup; if(result == CURLE_AGAIN) return -EAGAIN; /* magic return code for libssh2 */ diff --git a/lib/vssh/wolfssh.c b/lib/vssh/wolfssh.c index 7396791cecb..c6b94fd50d3 100644 --- a/lib/vssh/wolfssh.c +++ b/lib/vssh/wolfssh.c @@ -678,9 +678,9 @@ static CURLcode wssh_statemach_act(struct Curl_easy *data, bool *block) Curl_pgrsSetUploadSize(data, data->state.infilesize); } /* upload data */ - Curl_setup_transfer(data, -1, -1, FALSE, FIRSTSOCKET); + Curl_xfer_setup(data, -1, -1, FALSE, FIRSTSOCKET); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->sockfd = conn->writesockfd; if(result) { @@ -778,14 +778,14 @@ static CURLcode wssh_statemach_act(struct Curl_easy *data, bool *block) /* Setup the actual download */ if(data->req.size == 0) { /* no data to transfer */ - Curl_setup_transfer(data, -1, -1, FALSE, -1); + Curl_xfer_setup(data, -1, -1, FALSE, -1); infof(data, "File already completely downloaded"); state(data, SSH_STOP); break; } - Curl_setup_transfer(data, FIRSTSOCKET, data->req.size, FALSE, -1); + Curl_xfer_setup(data, FIRSTSOCKET, data->req.size, FALSE, -1); - /* not set by Curl_setup_transfer to preserve keepon bits */ + /* not set by Curl_xfer_setup to preserve keepon bits */ conn->writesockfd = conn->sockfd; /* we want to use the _receiving_ function even when the socket turns diff --git a/lib/ws.c b/lib/ws.c index f4675cec474..b2305932acc 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -1020,8 +1020,12 @@ static CURLcode ws_flush(struct Curl_easy *data, struct websocket *ws, while(Curl_bufq_peek(&ws->sendbuf, &out, &outlen)) { if(data->set.connect_only) result = Curl_senddata(data, out, outlen, &n); - else - result = Curl_write(data, data->conn->writesockfd, out, outlen, &n); + else { + result = Curl_xfer_send(data, out, outlen, &n); + if(!result && !n && outlen) + result = CURLE_AGAIN; + } + if(result) { if(result == CURLE_AGAIN) { if(!complete) { @@ -1086,8 +1090,7 @@ CURL_EXTERN CURLcode curl_ws_send(CURL *data, const void *buffer, /* raw mode sends exactly what was requested, and this is from within the write callback */ if(Curl_is_in_callback(data)) { - result = Curl_write(data, data->conn->writesockfd, buffer, buflen, - &nwritten); + result = Curl_xfer_send(data, buffer, buflen, &nwritten); } else result = Curl_senddata(data, buffer, buflen, &nwritten); @@ -1104,7 +1107,7 @@ CURL_EXTERN CURLcode curl_ws_send(CURL *data, const void *buffer, return result; /* TODO: the current design does not allow partial writes, afaict. - * It is not clear who the application is supposed to react. */ + * It is not clear how the application is supposed to react. */ space = Curl_bufq_space(&ws->sendbuf); DEBUGF(infof(data, "curl_ws_send(len=%zu), sendbuf len=%zu space %zu", buflen, Curl_bufq_len(&ws->sendbuf), space)); diff --git a/tests/unit/unit1620.c b/tests/unit/unit1620.c index 8b6f34ca7d7..dc3b3455afd 100644 --- a/tests/unit/unit1620.c +++ b/tests/unit/unit1620.c @@ -84,8 +84,6 @@ UNITTEST_START "Curl_free() did not set to NULL"); } - Curl_free_request_state(empty); - rc = Curl_close(&empty); fail_unless(rc == CURLE_OK, "Curl_close() failed"); From f73cb3ebd2eab3b2f3ef5a3402a0bbd5e13e2f47 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Feb 2024 22:27:07 +0100 Subject: [PATCH 376/509] CURLOPT_SSL_CTX_FUNCTION.md: no promises of lifetime after return ... and cleanup other language. Closes #12999 --- docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md | 73 ++++++++++--------- 1 file changed, 37 insertions(+), 36 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md index ae8b8bbadd3..35c8c0d6574 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md @@ -7,11 +7,12 @@ Source: libcurl See-also: - CURLOPT_SSL_CTX_DATA (3) - CURLOPT_SSL_VERIFYPEER (3) + - CURLOPT_CAINFO (3) --- # NAME -CURLOPT_SSL_CTX_FUNCTION - SSL context callback for OpenSSL, wolfSSL or mbedTLS +CURLOPT_SSL_CTX_FUNCTION - SSL context callback # SYNOPSIS @@ -26,49 +27,49 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION, # DESCRIPTION -This option only works for libcurl powered by OpenSSL, wolfSSL, mbedTLS or -BearSSL. If libcurl was built against another SSL library this functionality -is absent. - Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl just before the initialization of an SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behavior of the SSL -initialization. The *ssl_ctx* parameter is actually a pointer to the SSL -library's *SSL_CTX* for OpenSSL or wolfSSL, a pointer to -*mbedtls_ssl_config* for mbedTLS or a pointer to -*br_ssl_client_context* for BearSSL. If an error is returned from the -callback no attempt to establish a connection is made and the perform -operation returns the callback's error code. Set the *clientp* argument -with the CURLOPT_SSL_CTX_DATA(3) option. - -This function gets called on all new connections made to a server, during the -SSL negotiation. The *ssl_ctx* points to a newly initialized object each -time, but note the pointer may be the same as from a prior call. - -To use this properly, a non-trivial amount of knowledge of your SSL library is +initialization. The *ssl_ctx* parameter is a pointer to the SSL library's +*SSL_CTX* for OpenSSL or wolfSSL, a pointer to *mbedtls_ssl_config* for +mbedTLS or a pointer to *br_ssl_client_context* for BearSSL. If an error is +returned from the callback no attempt to establish a connection is made and +the perform operation returns the callback's error code. Set the *clientp* +argument passed in to this callback with the CURLOPT_SSL_CTX_DATA(3) option. + +This function gets called for all new connections made to a server, during the +SSL negotiation. While *ssl_ctx* points to a newly initialized object each +time, the pointer may still be the same as in a prior call. + +To use this callback, a non-trivial amount of knowledge of your SSL library is necessary. For example, you can use this function to call library-specific callbacks to add additional validation code for certificates, and even to change the actual URI of an HTTPS request. -For OpenSSL, asynchronous certificate verification via -*SSL_set_retry_verify* is supported. (Added in 8.3.0) +For OpenSSL, asynchronous certificate verification via *SSL_set_retry_verify* +is supported. (Added in 8.3.0) + +The CURLOPT_SSL_CTX_FUNCTION(3) callback allows the application to reach in +and modify SSL details in the connection without libcurl itself knowing +anything about it, which then subsequently can lead to libcurl unknowingly +reusing SSL connections with different properties. To remedy this you may set +CURLOPT_FORBID_REUSE(3) from the callback function. -WARNING: The CURLOPT_SSL_CTX_FUNCTION(3) callback allows the application -to reach in and modify SSL details in the connection without libcurl itself -knowing anything about it, which then subsequently can lead to libcurl -unknowingly reusing SSL connections with different properties. To remedy this -you may set CURLOPT_FORBID_REUSE(3) from the callback function. +If you are using DNS-over-HTTPS (DoH) via CURLOPT_DOH_URL(3) then this +callback is also called for those transfers and the curl handle is set to an +internal handle. **This behavior is subject to change.** We recommend setting +CURLOPT_PRIVATE(3) on your curl handle so you can identify it correctly in the +context callback. If you have a reason to modify DoH SSL context please let us +know on the curl-library mailing list because we are considering removing this +capability. -WARNING: If you are using DNS-over-HTTPS (DoH) via CURLOPT_DOH_URL(3) -then this callback is also called for those transfers and the curl handle is -set to an internal handle. **This behavior is subject to change.** We -recommend before performing your transfer set CURLOPT_PRIVATE(3) on your -curl handle so you can identify it in the context callback. If you have a -reason to modify DoH SSL context please let us know on the curl-library -mailing list because we are considering removing this capability. +libcurl does not guarantee the lifetime of the passed in object once this +callback function has returned. Your application must not assume that it can +keep using the SSL context or data derived from it once this function is +completed. # DEFAULT @@ -155,13 +156,13 @@ int main(void) # AVAILABILITY -Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL, in 7.54.0 for mbedTLS, -in 7.83.0 in BearSSL. Other SSL backends are not supported. +libcurl built with OpenSSL (added in 7.11.0), wolfSSL (added in 7.42.0), mbedTLS +(added in 7.54.0) or BearSSL (added in 7.83.0) + +No other SSL backend is supported. # RETURN VALUE CURLE_OK if supported; or an error such as: CURLE_NOT_BUILT_IN - Not supported by the SSL backend - -CURLE_UNKNOWN_OPTION From 2097a095c95e87d510ebeeaf211f893d5e688712 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 07:48:10 +0100 Subject: [PATCH 377/509] docs: use present tense avoid "will", detect "will" as a bad word in the CI Also line wrapped a bunch of paragraphs Closes #13001 --- .github/scripts/badwords.txt | 1 + docs/BUFQ.md | 93 +++++++++++------- docs/BUFREF.md | 3 +- docs/BUG-BOUNTY.md | 12 +-- docs/BUGS.md | 71 +++++++------- docs/CHECKSRC.md | 14 +-- docs/CIPHERS.md | 6 +- docs/CLIENT-WRITERS.md | 28 ++++-- docs/CODE_STYLE.md | 4 +- docs/CONNECTION-FILTERS.md | 125 +++++++++++++++++------- docs/CONTRIBUTE.md | 62 ++++++------ docs/CURLDOWN.md | 14 +-- docs/DEPRECATE.md | 4 +- docs/DYNBUF.md | 6 +- docs/EARLY-RELEASE.md | 2 +- docs/EXPERIMENTAL.md | 4 +- docs/GOVERNANCE.md | 32 +++---- docs/HELP-US.md | 17 ++-- docs/HSTS.md | 4 +- docs/HTTP-COOKIES.md | 21 ++-- docs/HTTP2.md | 24 ++--- docs/HTTP3.md | 31 +++--- docs/HYPER.md | 5 +- docs/INSTALL-CMAKE.md | 18 ++-- docs/INSTALL.md | 77 +++++++-------- docs/IPFS.md | 18 ++-- docs/MANUAL.md | 110 +++++++++++---------- docs/MQTT.md | 2 +- docs/NEW-PROTOCOL.md | 26 ++--- docs/PARALLEL-TRANSFERS.md | 6 +- docs/README.md | 6 +- docs/RELEASE-PROCEDURE.md | 5 +- docs/SECURITY-ADVISORY.md | 4 +- docs/SSL-PROBLEMS.md | 6 +- docs/SSLCERTS.md | 30 +++--- docs/TheArtOfHttpScripting.md | 159 +++++++++++++++---------------- docs/URL-SYNTAX.md | 36 ++++--- docs/VERSIONS.md | 8 +- docs/VULN-DISCLOSURE-POLICY.md | 10 +- docs/WEBSOCKET.md | 5 +- docs/curl-config.md | 26 ++--- docs/libcurl/ABI.md | 16 ++-- docs/libcurl/libcurl-env.md | 6 +- docs/libcurl/libcurl-security.md | 2 +- docs/mk-ca-bundle.md | 10 +- 45 files changed, 626 insertions(+), 543 deletions(-) diff --git a/.github/scripts/badwords.txt b/.github/scripts/badwords.txt index 216287f7fdf..36acde74461 100644 --- a/.github/scripts/badwords.txt +++ b/.github/scripts/badwords.txt @@ -47,3 +47,4 @@ 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/docs/BUFQ.md b/docs/BUFQ.md index 1a95a884c69..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,25 +98,39 @@ 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*. @@ -123,16 +140,16 @@ 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. It means that you will need other checks -to keep the `bufq` from growing ever larger and larger. +`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); @@ -140,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 f3fc1d82372..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). @@ -63,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 7333baafe5d..9a3a30add05 100644 --- a/docs/BUGS.md +++ b/docs/BUGS.md @@ -3,7 +3,7 @@ ## 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. Not to mention misfeatures. @@ -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 0d6e58c1423..fc500453591 100644 --- a/docs/CHECKSRC.md +++ b/docs/CHECKSRC.md @@ -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 f616f49725f..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. diff --git a/docs/CLIENT-WRITERS.md b/docs/CLIENT-WRITERS.md index a2a175b72c5..227e11db6ad 100644 --- a/docs/CLIENT-WRITERS.md +++ b/docs/CLIENT-WRITERS.md @@ -82,13 +82,27 @@ With these writers always in place, libcurl's protocol handlers automatically ha ## 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, there then will be a `Content-Encoding` header listing the encoding applied. If supported by `libcurl` it will then decompress the content before writing it out to the client. How does it do that? - -The HTTP protocol will add client writers in phase `CURL_CW_CONTENT_DECODE` on seeing such a header. For each encoding listed, it will add 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. So 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`. +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? diff --git a/docs/CODE_STYLE.md b/docs/CODE_STYLE.md index e6af36093d5..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,7 +218,7 @@ 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 is easy to tell what part of diff --git a/docs/CONNECTION-FILTERS.md b/docs/CONNECTION-FILTERS.md index a145d42c098..6c0ed2bc764 100644 --- a/docs/CONNECTION-FILTERS.md +++ b/docs/CONNECTION-FILTERS.md @@ -19,8 +19,8 @@ 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 @@ -33,9 +33,15 @@ 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. This allows stacking, as in: @@ -55,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: @@ -82,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: @@ -101,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, @@ -120,37 +144,58 @@ The `recv` implementation is equivalent. ## Filter Types -The currently existing filter types (curl 8.5.0) are: +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. +* `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. +* `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_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. +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. +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 a 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): +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` @@ -163,13 +208,19 @@ 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`. +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. +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 @@ -178,11 +229,19 @@ of an HTTP/2 request, invoke curl with: ``` > curl -v --trace-config ids,time,http/2 https://curl.se ``` -Which will give 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. + +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". +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". 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 @@ -190,7 +249,9 @@ 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. -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 will look like this: +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 diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md index 29d98cf1087..24928116c85 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 @@ -113,10 +113,10 @@ generated from the nroff/ASCII versions. 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 +131,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 +157,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 +219,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: @@ -248,10 +248,10 @@ 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 +302,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 index 1eb3d8f4813..061b7d58714 100644 --- a/docs/CURLDOWN.md +++ b/docs/CURLDOWN.md @@ -106,12 +106,12 @@ Write italics like: This is *italics*. Due to how man pages do not support backticks especially formatted, such -occurrences in the source will instead just use italics in the generated +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 will remove superfluous newlines, +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. @@ -121,10 +121,10 @@ 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)` will automatically be 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. +`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 fcbd92a31fd..6b6b5b46b8c 100644 --- a/docs/DEPRECATE.md +++ b/docs/DEPRECATE.md @@ -19,7 +19,7 @@ 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 will remove the support for NTLM_WB auth in April 2024. +curl removes the support for NTLM_WB auth in April 2024. ## space-separated `NOPROXY` patterns @@ -38,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/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/GOVERNANCE.md b/docs/GOVERNANCE.md index 0f7029e8276..4930b960424 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 @@ -172,9 +171,8 @@ 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 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/HSTS.md b/docs/HSTS.md index d4e99044db3..c1f433b2814 100644 --- a/docs/HSTS.md +++ b/docs/HSTS.md @@ -10,7 +10,7 @@ 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 hostname 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: @@ -22,7 +22,7 @@ HTTP-only requests to a hostname present in the cache will get internally ## 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 diff --git a/docs/HTTP-COOKIES.md b/docs/HTTP-COOKIES.md index a91e824d543..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,9 @@ 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 @@ -65,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 @@ -101,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` @@ -159,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 f16708983f7..758d8ab08c8 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -25,8 +25,8 @@ 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: @@ -273,11 +273,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)): @@ -314,10 +313,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 @@ -336,8 +335,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. @@ -345,9 +344,9 @@ 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. If those IP -addresses contain both IPv6 and IPv4, those attempts will happen, delayed, in +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 index 6dad38740ac..a606fcb21c2 100644 --- a/docs/INSTALL-CMAKE.md +++ b/docs/INSTALL-CMAKE.md @@ -9,11 +9,11 @@ # 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 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. +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. @@ -50,7 +50,7 @@ that is apart from the source tree. $ cmake -B . - Build in a separate directory (parallel to the curl source tree in this - example). The build directory will be created for you. + example). The build directory is created for you. $ cmake -B ../curl-build @@ -74,9 +74,9 @@ 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 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. +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` diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 336d654e086..703e59e51fb 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -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. 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 @@ -189,7 +189,7 @@ multi-threaded dynamic C runtime. 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` @@ -267,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) @@ -285,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 @@ -307,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: @@ -367,8 +368,8 @@ 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 is +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 @@ -376,7 +377,7 @@ install `libssl.a` and `libcrypto.a` to `$TOOLCHAIN/sysroot/usr/lib` and copy 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" ``` @@ -386,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 @@ -446,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: @@ -471,7 +472,7 @@ 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: @@ -533,12 +534,12 @@ 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). -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/IPFS.md b/docs/IPFS.md index aa3fb278c4e..65c0f5daded 100644 --- a/docs/IPFS.md +++ b/docs/IPFS.md @@ -60,21 +60,22 @@ 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 +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. Look for the file: `~/.ipfs/gateway`. If it can find that file then it +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 will 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 will not fallback to the other options if the +other gateway setting. curl does not fallback to the other options if the provided gateway did not work. ## Gateway redirects @@ -91,11 +92,12 @@ Which would be translated to: https://dweb.link/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi -Will redirect to: +redirects 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. +If you trust this behavior from your gateway of choice then passing the `-L` +option follows the redirect. ## Error messages and hints diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 86a007db68f..3ce869413f5 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -68,8 +68,7 @@ Get a webpage and store in a local file with a specific name: curl -o thatpage.html http://www.example.com/ 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 will -fail): +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`. @@ -257,11 +256,11 @@ 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/ @@ -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): @@ -354,9 +353,9 @@ 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 @@ -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,9 +548,9 @@ 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 @@ -592,9 +591,9 @@ 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 filename 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 @@ -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 @@ -830,7 +829,7 @@ set in (only an asterisk, `*` matches all hosts) NO_PROXY If the hostname 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 +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 @@ -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 -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/NEW-PROTOCOL.md b/docs/NEW-PROTOCOL.md index 223815b6d71..b70caa9445f 100644 --- a/docs/NEW-PROTOCOL.md +++ b/docs/NEW-PROTOCOL.md @@ -13,10 +13,10 @@ How do you proceed to add a new protocol and what are the 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 03ceb8f8290..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 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..2b5cbb88061 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 diff --git a/docs/SECURITY-ADVISORY.md b/docs/SECURITY-ADVISORY.md index 6344d222213..8d908a8ca54 100644 --- a/docs/SECURITY-ADVISORY.md +++ b/docs/SECURITY-ADVISORY.md @@ -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/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 7087e1eaf14..d1aca1a7b53 100644 --- a/docs/SSLCERTS.md +++ b/docs/SSLCERTS.md @@ -123,26 +123,26 @@ server, do one of the following: 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/TheArtOfHttpScripting.md b/docs/TheArtOfHttpScripting.md index 0357e8c5d16..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/ @@ -92,7 +91,7 @@ ## Host The hostname 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 + 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 @@ -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 @@ -339,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] @@ -354,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 @@ -409,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 @@ -419,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 @@ -447,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: @@ -469,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 @@ -549,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 \ @@ -568,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: @@ -586,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). @@ -627,18 +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 + 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 will not + `-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 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: + 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/ - curl will however still 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 @@ -649,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 @@ -675,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 3ce2b64383b..67f9bdbc649 100644 --- a/docs/URL-SYNTAX.md +++ b/docs/URL-SYNTAX.md @@ -30,8 +30,8 @@ same behavior! 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 hostname 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 @@ -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,7 +351,7 @@ 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 @@ -368,8 +367,8 @@ curl supports SMB version 1 (only) ## SMTP 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 will -attempt to resolve the local computer's hostname. However, this may not +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 a0086634a20..5f10bc8b6fd 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. @@ -108,7 +108,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 +255,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 c3967b8eab5..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. diff --git a/docs/curl-config.md b/docs/curl-config.md index efb92aa8000..2ab9e9b0206 100644 --- a/docs/curl-config.md +++ b/docs/curl-config.md @@ -38,10 +38,10 @@ libcurl. Currently that is only the include path to the curl include files. ## --checkfor [version] -Specify the oldest possible libcurl version string you want, and this -script will return 0 if the current installation is new enough or it -returns 1 and outputs a text saying that the current version is not new -enough. (Added in 7.15.4) +Specify the oldest possible libcurl version string you want, and this script +returns 0 if the current installation is new enough or it returns 1 and +outputs a text saying that the current version is not new enough. (Added in +7.15.4) ## --configure @@ -51,7 +51,7 @@ Displays the arguments given to configure when building curl. Lists what particular main features the installed libcurl was built with. At the time of writing, this list may include SSL, KRB4 or IPv6. Do not assume -any particular order. The keywords will be separated by newlines. There may be +any particular order. The keywords are separated by newlines. There may be none, one, or several keywords in the list. ## --help @@ -60,8 +60,8 @@ Displays the available options. ## --libs -Shows the complete set of libs and other linker options you will need in order -to link your application with libcurl. +Shows the complete set of libs and other linker options you need in order to +link your application with libcurl. ## --prefix @@ -74,19 +74,19 @@ on. The prefix is set with "configure --prefix". Lists what particular protocols the installed libcurl was built to support. At the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE, TELNET, LDAP, DICT and many more. Do not assume any particular order. The -protocols will be listed using uppercase and are separated by newlines. There -may be none, one, or several protocols in the list. (Added in 7.13.0) +protocols are listed using uppercase and are separated by newlines. There may +be none, one, or several protocols in the list. (Added in 7.13.0) ## --ssl-backends Lists the SSL backends that were enabled when libcurl was built. It might be -no, one or several names. If more than one name, they will appear -comma-separated. (Added in 7.58.0) +no, one or several names. If more than one name, they appear comma-separated. +(Added in 7.58.0) ## --static-libs -Shows the complete set of libs and other linker options you will need in order -to link your application with libcurl statically. (Added in 7.17.1) +Shows the complete set of libs and other linker options you need in order to +link your application with libcurl statically. (Added in 7.17.1) ## --version diff --git a/docs/libcurl/ABI.md b/docs/libcurl/ABI.md index 408ea1094d2..0ec9928b989 100644 --- a/docs/libcurl/ABI.md +++ b/docs/libcurl/ABI.md @@ -28,13 +28,13 @@ ABI - Application Binary Interface ## SONAME Bumps - Whenever there are changes done to the library that will cause an ABI - breakage, that may require your application to get attention or possibly be - changed to adhere to new things, we will bump the SONAME. Then the library - will get a different output name and thus can in fact be installed in - parallel with an older installed lib (on most systems). Thus, old - applications built against the previous ABI version will remain working and - using the older lib, while newer applications build and use the newer one. + Whenever there are changes done to the library that causes an ABI breakage, + that may require your application to get attention or possibly be changed to + adhere to new things, we bump the SONAME. Then the library gets a different + output name and thus can in fact be installed in parallel with an older + installed lib (on most systems). Thus, old applications built against the + previous ABI version remains working and using the older lib, while newer + applications build and use the newer one. During the first seven years of libcurl releases, there have only been four ABI breakages. @@ -46,7 +46,7 @@ ABI - Application Binary Interface Going to an older libcurl version from one you are currently using can be a tricky thing. Mostly we add features and options to newer libcurls as that - will not break ABI or hamper existing applications. This has the implication + does not break ABI or hamper existing applications. This has the implication that going backwards may get you in a situation where you pick a libcurl that does not support the options your application needs. Or possibly you even downgrade so far so you cross an ABI break border and thus a different diff --git a/docs/libcurl/libcurl-env.md b/docs/libcurl/libcurl-env.md index 1205b8d391e..30a57ff1acb 100644 --- a/docs/libcurl/libcurl-env.md +++ b/docs/libcurl/libcurl-env.md @@ -32,9 +32,9 @@ the **http_proxy** one which is only used lowercase. Note also that some systems actually have a case insensitive handling of environment variables and then of course **HTTP_PROXY** still works. -An exception exists for the WebSocket **ws** and **wss** URL schemes, -where libcurl first checks **ws_proxy** or **wss_proxy** but if they are -not set, it will fall back and try the http and https versions instead if set. +An exception exists for the WebSocket **ws** and **wss** URL schemes, where +libcurl first checks **ws_proxy** or **wss_proxy** but if they are not set, it +falls back and tries the http and https versions instead if set. ## `ALL_PROXY` diff --git a/docs/libcurl/libcurl-security.md b/docs/libcurl/libcurl-security.md index da4ac73c6eb..84103b9ab94 100644 --- a/docs/libcurl/libcurl-security.md +++ b/docs/libcurl/libcurl-security.md @@ -365,7 +365,7 @@ hard to avoid. # Active FTP passes on the local IP address -If you use curl/libcurl to do *active* FTP transfers, curl will pass on the +If you use curl/libcurl to do *active* FTP transfers, curl passes on the address of your local IP to the remote server - even when for example using a SOCKS or HTTP proxy in between curl and the target server. diff --git a/docs/mk-ca-bundle.md b/docs/mk-ca-bundle.md index c0ffab30fd0..8836305dc7c 100644 --- a/docs/mk-ca-bundle.md +++ b/docs/mk-ca-bundle.md @@ -25,7 +25,7 @@ authentication certificates are extracted. These are then processed with the OpenSSL command line tool to produce the final ca-bundle output file. The default *output* name is **ca-bundle.crt**. By setting it to '-' (a single -dash) you will get the output sent to STDOUT instead of a file. +dash) you get the output sent to STDOUT instead of a file. The PEM format this scripts uses for output makes the result readily available for use by just about all OpenSSL or GnuTLS powered applications, such as curl @@ -56,8 +56,8 @@ print version info about used modules ## -k -Allow insecure data transfer. By default (since 1.27) this command will fail -if the HTTPS transfer fails. This overrides that decision (and opens for +Allow insecure data transfer. By default (since 1.27) this command fails if +the HTTPS transfer fails. This overrides that decision (and opens for man-in-the-middle attacks). ## -l @@ -68,8 +68,8 @@ print license info about *certdata.txt* (Added in 1.26) Include meta data comments in the output. The meta data is specific information about each certificate that is stored in the original -file as comments and using this option will make those comments get passed on -to the output file. The meta data is not parsed in any way by mk-ca-bundle. +file as comments and using this option makes those comments get passed on to +the output file. The meta data is not parsed in any way by mk-ca-bundle. ## -n From 757dfdfb55a9dea43041b4ab4f1373d34c16dded Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Feb 2024 09:50:49 +0100 Subject: [PATCH 378/509] multi: make add_handle free any multi_easy If the easy handle that is being added to a multi handle has previously been used for curl_easy_perform(), there is a private multi handle here that we can kill off. While it flushes some caches etc for the easy handle would it be used for an easy interface transfer again after being used in the multi stack, this cleanup simplifies behavior and uses less memory. Closes #12992 --- lib/easy.c | 6 ++++-- lib/multi.c | 7 +++++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/lib/easy.c b/lib/easy.c index 7ea1ce1f636..e6bda9bc8b1 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -742,7 +742,6 @@ static CURLcode easy_perform(struct Curl_easy *data, bool events) multi = Curl_multi_handle(1, 3, 7); if(!multi) return CURLE_OUT_OF_MEMORY; - data->multi_easy = multi; } if(multi->in_callback) @@ -751,15 +750,18 @@ static CURLcode easy_perform(struct Curl_easy *data, bool events) /* Copy the MAXCONNECTS option to the multi handle */ curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)data->set.maxconnects); + data->multi_easy = NULL; /* pretend it does not exist */ mcode = curl_multi_add_handle(multi, data); if(mcode) { curl_multi_cleanup(multi); - data->multi_easy = NULL; if(mcode == CURLM_OUT_OF_MEMORY) return CURLE_OUT_OF_MEMORY; return CURLE_FAILED_INIT; } + /* assign this after curl_multi_add_handle() */ + data->multi_easy = multi; + sigpipe_ignore(data, &pipe_st); /* run the transfer */ diff --git a/lib/multi.c b/lib/multi.c index c6869a3155c..e0e871fe679 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -530,6 +530,13 @@ CURLMcode curl_multi_add_handle(struct Curl_multi *multi, multi->dead = FALSE; } + if(data->multi_easy) { + /* if this easy handle was previously used for curl_easy_perform(), there + is a private multi handle here that we can kill */ + curl_multi_cleanup(data->multi_easy); + data->multi_easy = NULL; + } + /* Initialize timeout list for this handle */ Curl_llist_init(&data->state.timeoutlist, NULL); From 37551535712c267141f425fcb56ec6c474e46123 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 15 Feb 2024 16:22:53 +0100 Subject: [PATCH 379/509] lib: Curl_read/Curl_write clarifications - replace `Curl_read()`, `Curl_write()` and `Curl_nwrite()` to clarify when and at what level they operate - send/recv of transfer related data is now done via `Curl_xfer_send()/Curl_xfer_recv()` which no longer has socket/socketindex as parameter. It decides on the transfer setup of `conn->sockfd` and `conn->writesockfd` on which connection filter chain to operate. - send/recv on a specific connection filter chain is done via `Curl_conn_send()/Curl_conn_recv()` which get the socket index as parameter. - rename `Curl_setup_transfer()` to `Curl_xfer_setup()` for naming consistency - clarify that the special CURLE_AGAIN hangling to return `CURLE_OK` with length 0 only applies to `Curl_xfer_send()` and CURLE_AGAIN is returned by all other send() variants. - fix a bug in websocket `curl_ws_recv()` that mixed up data when it arrived in more than a single chunk The method for sending not just raw bytes, but bytes that are either "headers" or "body". The send abstraction stack, to to bottom, now is: * `Curl_req_send()`: has parameter to indicate amount of header bytes, buffers all data. * `Curl_xfer_send()`: knows on which socket index to send, returns amount of bytes sent. * `Curl_conn_send()`: called with socket index, returns amount of bytes sent. In addition there is `Curl_req_flush()` for writing out all buffered bytes. `Curl_req_send()` is active for requests without body, `Curl_buffer_send()` still being used for others. This is because the special quirks need to be addressed in future parts: * `expect-100` handling * `Curl_fillreadbuffer()` needs to add directly to the new `data->req.sendbuf` * special body handlings, like `chunked` encodings and line end conversions will be moved into something like a Client Reader. In functions of the pattern `CURLcode xxx_send(..., ssize_t *written)`, replace the `ssize_t` with a `size_t`. It makes no sense to allow for negative values as the returned `CURLcode` already specifies error conditions. This allows easier handling of lengths without casting. Closes #12964 --- lib/c-hyper.c | 9 +-- lib/cf-h1-proxy.c | 7 +- lib/cf-haproxy.c | 5 +- lib/cfilters.c | 4 +- lib/cfilters.h | 2 +- lib/dict.c | 2 +- lib/easy.c | 6 +- lib/easyif.h | 2 +- lib/gopher.c | 4 +- lib/http.c | 90 +++++++++++------------ lib/http.h | 8 +-- lib/krb5.c | 8 +-- lib/mqtt.c | 4 +- lib/pingpong.c | 10 +-- lib/request.c | 173 +++++++++++++++++++++++++++++++++++++++++---- lib/request.h | 36 +++++++++- lib/rtsp.c | 5 +- lib/smb.c | 8 +-- lib/smtp.c | 3 +- lib/telnet.c | 12 ++-- lib/transfer.c | 34 ++++----- lib/transfer.h | 2 +- lib/url.c | 3 - lib/vssh/libssh2.c | 6 +- lib/ws.c | 13 ++-- 25 files changed, 314 insertions(+), 142 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index f8e36e909d0..ae51c5ca403 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -112,11 +112,13 @@ size_t Curl_hyper_send(void *userp, hyper_context *ctx, struct hyp_io_ctx *io_ctx = userp; struct Curl_easy *data = io_ctx->data; CURLcode result; - ssize_t nwrote; + size_t nwrote; DEBUGF(infof(data, "Curl_hyper_send(%zu)", buflen)); result = Curl_conn_send(data, io_ctx->sockindex, (void *)buf, buflen, &nwrote); + if(!result && !nwrote) + result = CURLE_AGAIN; if(result == CURLE_AGAIN) { DEBUGF(infof(data, "Curl_hyper_send(%zu) -> EAGAIN", buflen)); /* would block, register interest */ @@ -759,7 +761,6 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, */ static CURLcode bodysend(struct Curl_easy *data, - struct connectdata *conn, hyper_headers *headers, hyper_request *hyperreq, Curl_HttpReq httpreq) @@ -772,7 +773,7 @@ static CURLcode bodysend(struct Curl_easy *data, else { hyper_body *body; Curl_dyn_init(&req, DYN_HTTP_REQUEST); - result = Curl_http_bodysend(data, conn, &req, httpreq); + result = Curl_http_req_send(data, &req, httpreq); if(!result) result = Curl_hyper_header(data, headers, Curl_dyn_ptr(&req)); @@ -1171,7 +1172,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) if(result) goto error; - result = bodysend(data, conn, headers, req, httpreq); + result = bodysend(data, headers, req, httpreq); if(result) goto error; diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index b7afe27a3fe..6ca7babf8e6 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -212,6 +212,11 @@ static void tunnel_free(struct Curl_cfilter *cf, } } +static bool tunnel_want_send(struct h1_tunnel_state *ts) +{ + return (ts->tunnel_state == H1_TUNNEL_CONNECT); +} + #ifndef USE_HYPER static CURLcode start_CONNECT(struct Curl_cfilter *cf, struct Curl_easy *data, @@ -1032,7 +1037,7 @@ static void cf_h1_proxy_adjust_pollset(struct Curl_cfilter *cf, wait for the socket to become readable to be able to get the response headers or if we're still sending the request, wait for write. */ - if(ts->CONNECT.sending == HTTPSEND_REQUEST) + if(tunnel_want_send(ts)) Curl_pollset_set_out_only(data, ps, sock); else Curl_pollset_set_in_only(data, ps, sock); diff --git a/lib/cf-haproxy.c b/lib/cf-haproxy.c index 652070e12dd..90532952b18 100644 --- a/lib/cf-haproxy.c +++ b/lib/cf-haproxy.c @@ -129,7 +129,7 @@ static CURLcode cf_haproxy_connect(struct Curl_cfilter *cf, case HAPROXY_SEND: len = Curl_dyn_len(&ctx->data_out); if(len > 0) { - ssize_t written; + size_t written; result = Curl_conn_send(data, cf->sockindex, Curl_dyn_ptr(&ctx->data_out), len, &written); @@ -139,8 +139,7 @@ static CURLcode cf_haproxy_connect(struct Curl_cfilter *cf, } else if(result) goto out; - DEBUGASSERT(written >= 0); - Curl_dyn_tail(&ctx->data_out, len - (size_t)written); + Curl_dyn_tail(&ctx->data_out, len - written); if(Curl_dyn_len(&ctx->data_out) > 0) { result = CURLE_OK; goto out; diff --git a/lib/cfilters.c b/lib/cfilters.c index 2bf1dd844f2..4e4c8e569c0 100644 --- a/lib/cfilters.c +++ b/lib/cfilters.c @@ -694,7 +694,7 @@ CURLcode Curl_conn_recv(struct Curl_easy *data, int sockindex, CURLcode Curl_conn_send(struct Curl_easy *data, int sockindex, const void *buf, size_t blen, - ssize_t *pnwritten) + size_t *pnwritten) { ssize_t nwritten; CURLcode result = CURLE_OK; @@ -719,7 +719,7 @@ CURLcode Curl_conn_send(struct Curl_easy *data, int sockindex, #endif nwritten = conn->send[sockindex](data, sockindex, buf, blen, &result); DEBUGASSERT((nwritten >= 0) || result); - *pnwritten = nwritten; + *pnwritten = (nwritten < 0)? 0 : (size_t)nwritten; return result; } diff --git a/lib/cfilters.h b/lib/cfilters.h index 65ae3d4cbb3..92a2132fe0e 100644 --- a/lib/cfilters.h +++ b/lib/cfilters.h @@ -518,7 +518,7 @@ CURLcode Curl_conn_recv(struct Curl_easy *data, int sockindex, */ CURLcode Curl_conn_send(struct Curl_easy *data, int sockindex, const void *buf, size_t blen, - ssize_t *pnwritten); + size_t *pnwritten); void Curl_pollset_reset(struct Curl_easy *data, diff --git a/lib/dict.c b/lib/dict.c index 955290f4da5..f37767882e7 100644 --- a/lib/dict.c +++ b/lib/dict.c @@ -127,7 +127,7 @@ static CURLcode sendf(struct Curl_easy *data, static CURLcode sendf(struct Curl_easy *data, const char *fmt, ...) { - ssize_t bytes_written; + size_t bytes_written; size_t write_len; CURLcode result = CURLE_OK; char *s; diff --git a/lib/easy.c b/lib/easy.c index e6bda9bc8b1..6c932ad823c 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -1251,7 +1251,7 @@ CURLcode Curl_connect_only_attach(struct Curl_easy *data) * This is the private internal version of curl_easy_send() */ CURLcode Curl_senddata(struct Curl_easy *data, const void *buffer, - size_t buflen, ssize_t *n) + size_t buflen, size_t *n) { CURLcode result; struct connectdata *c = NULL; @@ -1283,13 +1283,13 @@ CURLcode Curl_senddata(struct Curl_easy *data, const void *buffer, CURLcode curl_easy_send(struct Curl_easy *data, const void *buffer, size_t buflen, size_t *n) { - ssize_t written = 0; + size_t written = 0; CURLcode result; if(Curl_is_in_callback(data)) return CURLE_RECURSIVE_API_CALL; result = Curl_senddata(data, buffer, buflen, &written); - *n = (size_t)written; + *n = written; return result; } diff --git a/lib/easyif.h b/lib/easyif.h index 64489529660..6ce3483c643 100644 --- a/lib/easyif.h +++ b/lib/easyif.h @@ -28,7 +28,7 @@ * Prototypes for library-wide functions provided by easy.c */ CURLcode Curl_senddata(struct Curl_easy *data, const void *buffer, - size_t buflen, ssize_t *n); + size_t buflen, size_t *n); #ifdef USE_WEBSOCKETS CURLcode Curl_connect_only_attach(struct Curl_easy *data); diff --git a/lib/gopher.c b/lib/gopher.c index e49da8147c9..e1a1ba64886 100644 --- a/lib/gopher.c +++ b/lib/gopher.c @@ -139,8 +139,8 @@ static CURLcode gopher_do(struct Curl_easy *data, bool *done) char *sel = NULL; char *sel_org = NULL; timediff_t timeout_ms; - ssize_t amount, k; - size_t len; + ssize_t k; + size_t amount, len; int what; *done = TRUE; /* unconditionally */ diff --git a/lib/http.c b/lib/http.c index 97ef4550f5e..77832d2a466 100644 --- a/lib/http.c +++ b/lib/http.c @@ -1174,6 +1174,7 @@ static bool http_should_fail(struct Curl_easy *data) return data->state.authproblem; } +#ifndef USE_HYPER /* * readmoredata() is a "fread() emulation" to provide POST and/or request * data. It is used when a huge POST is to be made and the entire chunk wasn't @@ -1238,17 +1239,16 @@ static size_t readmoredata(char *buffer, * * Returns CURLcode */ -CURLcode Curl_buffer_send(struct dynbuf *in, - struct Curl_easy *data, - struct HTTP *http, - /* add the number of sent bytes to this - counter */ - curl_off_t *bytes_written, - /* how much of the buffer contains body data */ - curl_off_t included_body_bytes, - int sockindex) +static CURLcode buffer_send(struct dynbuf *in, + struct Curl_easy *data, + struct HTTP *http, + /* add the number of sent bytes to this + counter */ + curl_off_t *bytes_written, + /* how much of the buffer contains body data */ + curl_off_t included_body_bytes) { - ssize_t amount; + size_t amount; CURLcode result; char *ptr; size_t size; @@ -1256,8 +1256,6 @@ CURLcode Curl_buffer_send(struct dynbuf *in, size_t sendsize; size_t headersize; - DEBUGASSERT(sockindex <= SECONDARYSOCKET && sockindex >= 0); - /* The looping below is required since we use non-blocking sockets, but due to the circumstances we will just loop and try again and again etc */ @@ -1356,11 +1354,7 @@ CURLcode Curl_buffer_send(struct dynbuf *in, sendsize = (size_t)data->set.upload_buffer_size; } - result = Curl_conn_send(data, sockindex, ptr, sendsize, &amount); - if(result == CURLE_AGAIN) { - result = CURLE_OK; - amount = 0; - } + result = Curl_xfer_send(data, ptr, sendsize, &amount); if(!result) { /* @@ -1443,6 +1437,11 @@ CURLcode Curl_buffer_send(struct dynbuf *in, /* end of the add_buffer functions */ /* ------------------------------------------------------------------------- */ +#else /* !USE_HYPER */ + /* In hyper, this is an ugly NOP */ +#define buffer_send(a,b,c,d,e) CURLE_OK + +#endif /* !USE_HYPER(else) */ @@ -1619,13 +1618,12 @@ static const char *get_http_string(const struct Curl_easy *data, #endif /* check and possibly add an Expect: header */ -static CURLcode expect100(struct Curl_easy *data, - struct connectdata *conn, - struct dynbuf *req) +static CURLcode expect100(struct Curl_easy *data, struct dynbuf *req) { CURLcode result = CURLE_OK; - if(!data->state.disableexpect && Curl_use_http_1_1plus(data, conn) && - (conn->httpversion < 20)) { + if(!data->state.disableexpect && + Curl_use_http_1_1plus(data, data->conn) && + (data->conn->httpversion < 20)) { /* if not doing HTTP 1.0 or version 2, or disabled explicitly, we add an Expect: 100-continue to the headers which actually speeds up post operations (as there is one packet coming back from the web server) */ @@ -2441,8 +2439,7 @@ CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, return result; } -static CURLcode addexpect(struct Curl_easy *data, struct connectdata *conn, - struct dynbuf *r) +static CURLcode addexpect(struct Curl_easy *data, struct dynbuf *r) { data->state.expect100header = FALSE; /* Avoid Expect: 100-continue if Upgrade: is used */ @@ -2459,24 +2456,22 @@ static CURLcode addexpect(struct Curl_easy *data, struct connectdata *conn, STRCONST("100-continue")); } else if(http->postsize > EXPECT_100_THRESHOLD || http->postsize < 0) - return expect100(data, conn, r); + return expect100(data, r); } return CURLE_OK; } -CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, +CURLcode Curl_http_req_send(struct Curl_easy *data, struct dynbuf *r, Curl_HttpReq httpreq) { #ifndef USE_HYPER /* Hyper always handles the body separately */ curl_off_t included_body = 0; -#else - /* from this point down, this function should not be used */ -#define Curl_buffer_send(a,b,c,d,e,f) CURLE_OK #endif CURLcode result = CURLE_OK; struct HTTP *http = data->req.p.http; + DEBUGASSERT(data->conn); switch(httpreq) { case HTTPREQ_PUT: /* Let's PUT the data to the server! */ @@ -2495,7 +2490,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, return result; } - result = addexpect(data, conn, r); + result = addexpect(data, r); if(result) return result; @@ -2508,9 +2503,8 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, Curl_pgrsSetUploadSize(data, http->postsize); /* this sends the buffer and frees all the buffer resources */ - result = Curl_buffer_send(r, data, data->req.p.http, - &data->info.request_size, 0, - FIRSTSOCKET); + result = buffer_send(r, data, data->req.p.http, + &data->info.request_size, 0); if(result) failf(data, "Failed sending PUT request"); else @@ -2531,9 +2525,8 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, if(result) return result; - result = Curl_buffer_send(r, data, data->req.p.http, - &data->info.request_size, 0, - FIRSTSOCKET); + result = buffer_send(r, data, data->req.p.http, + &data->info.request_size, 0); if(result) failf(data, "Failed sending POST request"); else @@ -2571,7 +2564,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, } #endif - result = addexpect(data, conn, r); + result = addexpect(data, r); if(result) return result; @@ -2589,9 +2582,8 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, http->sending = HTTPSEND_BODY; /* this sends the buffer and frees all the buffer resources */ - result = Curl_buffer_send(r, data, data->req.p.http, - &data->info.request_size, 0, - FIRSTSOCKET); + result = buffer_send(r, data, data->req.p.http, + &data->info.request_size, 0); if(result) failf(data, "Failed sending POST request"); else @@ -2633,7 +2625,7 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, return result; } - result = addexpect(data, conn, r); + result = addexpect(data, r); if(result) return result; @@ -2732,9 +2724,8 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, } } /* issue the request */ - result = Curl_buffer_send(r, data, data->req.p.http, - &data->info.request_size, included_body, - FIRSTSOCKET); + result = buffer_send(r, data, data->req.p.http, + &data->info.request_size, included_body); if(result) failf(data, "Failed sending HTTP POST request"); @@ -2749,13 +2740,12 @@ CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, return result; /* issue the request */ - result = Curl_buffer_send(r, data, data->req.p.http, - &data->info.request_size, 0, - FIRSTSOCKET); + result = Curl_req_send_hds(data, Curl_dyn_ptr(r), Curl_dyn_len(r)); + Curl_dyn_free(r); if(result) failf(data, "Failed sending HTTP request"); #ifdef USE_WEBSOCKETS - else if((conn->handler->protocol & (CURLPROTO_WS|CURLPROTO_WSS)) && + else if((data->conn->handler->protocol & (CURLPROTO_WS|CURLPROTO_WSS)) && !(data->set.connect_only)) /* Set up the transfer for two-way since without CONNECT_ONLY set, this request probably wants to send data too post upgrade */ @@ -3329,8 +3319,8 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) (httpreq == HTTPREQ_HEAD)) Curl_pgrsSetUploadSize(data, 0); /* nothing */ - /* bodysend takes ownership of the 'req' memory on success */ - result = Curl_http_bodysend(data, conn, &req, httpreq); + /* req_send takes ownership of the 'req' memory on success */ + result = Curl_http_req_send(data, &req, httpreq); } if(result) { Curl_dyn_free(&req); diff --git a/lib/http.h b/lib/http.h index ad2697c9e73..7991f938038 100644 --- a/lib/http.h +++ b/lib/http.h @@ -74,12 +74,6 @@ char *Curl_checkProxyheaders(struct Curl_easy *data, const char *thisheader, const size_t thislen); struct HTTP; /* see below */ -CURLcode Curl_buffer_send(struct dynbuf *in, - struct Curl_easy *data, - struct HTTP *http, - curl_off_t *bytes_written, - curl_off_t included_body_bytes, - int socketindex); CURLcode Curl_add_timecondition(struct Curl_easy *data, #ifndef USE_HYPER @@ -118,7 +112,7 @@ CURLcode Curl_transferencode(struct Curl_easy *data); CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, Curl_HttpReq httpreq, const char **teep); -CURLcode Curl_http_bodysend(struct Curl_easy *data, struct connectdata *conn, +CURLcode Curl_http_req_send(struct Curl_easy *data, struct dynbuf *r, Curl_HttpReq httpreq); bool Curl_use_http_1_1plus(const struct Curl_easy *data, const struct connectdata *conn); diff --git a/lib/krb5.c b/lib/krb5.c index 885319e00fe..309e12a58ae 100644 --- a/lib/krb5.c +++ b/lib/krb5.c @@ -66,7 +66,7 @@ static CURLcode ftpsend(struct Curl_easy *data, struct connectdata *conn, const char *cmd) { - ssize_t bytes_written; + size_t bytes_written; #define SBUF_SIZE 1024 char s[SBUF_SIZE]; size_t write_len; @@ -100,9 +100,9 @@ static CURLcode ftpsend(struct Curl_easy *data, struct connectdata *conn, if(result) break; - Curl_debug(data, CURLINFO_HEADER_OUT, sptr, (size_t)bytes_written); + Curl_debug(data, CURLINFO_HEADER_OUT, sptr, bytes_written); - if(bytes_written != (ssize_t)write_len) { + if(bytes_written != write_len) { write_len -= bytes_written; sptr += bytes_written; } @@ -494,7 +494,7 @@ socket_write(struct Curl_easy *data, int sockindex, const void *to, { const char *to_p = to; CURLcode result; - ssize_t written; + size_t written; while(len > 0) { result = Curl_conn_send(data, sockindex, to_p, len, &written); diff --git a/lib/mqtt.c b/lib/mqtt.c index b0aafc79707..9290da031ba 100644 --- a/lib/mqtt.c +++ b/lib/mqtt.c @@ -119,12 +119,12 @@ static CURLcode mqtt_send(struct Curl_easy *data, { CURLcode result = CURLE_OK; struct MQTT *mq = data->req.p.mqtt; - ssize_t n; + size_t n; result = Curl_xfer_send(data, buf, len, &n); if(result) return result; Curl_debug(data, CURLINFO_HEADER_OUT, buf, (size_t)n); - if(len != (size_t)n) { + if(len != n) { size_t nsend = len - n; char *sendleftovers = Curl_memdup(&buf[n], nsend); if(!sendleftovers) diff --git a/lib/pingpong.c b/lib/pingpong.c index c12f7cd7b63..7f240be9500 100644 --- a/lib/pingpong.c +++ b/lib/pingpong.c @@ -164,7 +164,7 @@ CURLcode Curl_pp_vsendf(struct Curl_easy *data, const char *fmt, va_list args) { - ssize_t bytes_written = 0; + size_t bytes_written = 0; size_t write_len; char *s; CURLcode result; @@ -211,9 +211,9 @@ CURLcode Curl_pp_vsendf(struct Curl_easy *data, conn->data_prot = (unsigned char)data_sec; #endif - Curl_debug(data, CURLINFO_HEADER_OUT, s, (size_t)bytes_written); + Curl_debug(data, CURLINFO_HEADER_OUT, s, bytes_written); - if(bytes_written != (ssize_t)write_len) { + if(bytes_written != write_len) { /* the whole chunk was not sent, keep it around and adjust sizes */ pp->sendthis = s; pp->sendsize = write_len; @@ -398,7 +398,7 @@ CURLcode Curl_pp_flushsend(struct Curl_easy *data, struct pingpong *pp) { /* we have a piece of a command still left to send */ - ssize_t written; + size_t written; CURLcode result; result = Curl_conn_send(data, FIRSTSOCKET, @@ -411,7 +411,7 @@ CURLcode Curl_pp_flushsend(struct Curl_easy *data, if(result) return result; - if(written != (ssize_t)pp->sendleft) { + if(written != pp->sendleft) { /* only a fraction was sent */ pp->sendleft -= written; } diff --git a/lib/request.c b/lib/request.c index 933f8850c36..334a0567398 100644 --- a/lib/request.c +++ b/lib/request.c @@ -27,8 +27,10 @@ #include "urldata.h" #include "dynbuf.h" #include "doh.h" +#include "progress.h" #include "request.h" #include "sendf.h" +#include "transfer.h" #include "url.h" /* The last 3 #include files should be in this order */ @@ -39,8 +41,6 @@ CURLcode Curl_req_init(struct SingleRequest *req) { memset(req, 0, sizeof(*req)); - Curl_bufq_init2(&req->sendbuf, UPLOADBUFFER_DEFAULT, 1, - BUFQ_OPT_SOFT_LIMIT); return CURLE_OK; } @@ -49,6 +49,20 @@ CURLcode Curl_req_start(struct SingleRequest *req, { req->start = Curl_now(); Curl_cw_reset(data); + if(!req->sendbuf_init) { + Curl_bufq_init2(&req->sendbuf, data->set.upload_buffer_size, 1, + BUFQ_OPT_SOFT_LIMIT); + req->sendbuf_init = TRUE; + } + else { + Curl_bufq_reset(&req->sendbuf); + if(data->set.upload_buffer_size != req->sendbuf.chunk_size) { + Curl_bufq_free(&req->sendbuf); + Curl_bufq_init2(&req->sendbuf, data->set.upload_buffer_size, 1, + BUFQ_OPT_SOFT_LIMIT); + } + } + return CURLE_OK; } @@ -56,33 +70,40 @@ CURLcode Curl_req_done(struct SingleRequest *req, struct Curl_easy *data, bool aborted) { (void)req; - /* TODO: add flush handling for client output */ - (void)aborted; + if(!aborted) + (void)Curl_req_flush(data); Curl_cw_reset(data); return CURLE_OK; } void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data) { + struct bufq savebuf; + bool save_init; + /* This is a bit ugly. `req->p` is a union and we assume we can * free this safely without leaks. */ Curl_safefree(req->p.http); Curl_safefree(req->newurl); Curl_cw_reset(data); - Curl_bufq_reset(&req->sendbuf); - if(data->set.upload_buffer_size != req->sendbuf.chunk_size) { - Curl_bufq_free(&req->sendbuf); - Curl_bufq_init2(&req->sendbuf, data->set.upload_buffer_size, 1, - BUFQ_OPT_SOFT_LIMIT); - } - #ifndef CURL_DISABLE_DOH if(req->doh) { Curl_close(&req->doh->probe[0].easy); Curl_close(&req->doh->probe[1].easy); } #endif + + savebuf = req->sendbuf; + save_init = req->sendbuf_init; + + memset(req, 0, sizeof(*req)); + data->req.size = data->req.maxdownload = -1; + data->req.no_body = data->set.opt_no_body; + if(save_init) { + req->sendbuf = savebuf; + req->sendbuf_init = save_init; + } } void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data) @@ -91,7 +112,8 @@ void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data) * free this safely without leaks. */ Curl_safefree(req->p.http); Curl_safefree(req->newurl); - Curl_bufq_free(&req->sendbuf); + if(req->sendbuf_init) + Curl_bufq_free(&req->sendbuf); Curl_cw_reset(data); #ifndef CURL_DISABLE_DOH @@ -106,3 +128,130 @@ void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data) #endif } +static CURLcode req_send(struct Curl_easy *data, + const char *buf, size_t blen, + size_t hds_len, size_t *pnwritten) +{ + CURLcode result = CURLE_OK; + + *pnwritten = 0; +#ifdef CURLDEBUG + { + /* Allow debug builds to override this logic to force short initial + sends + */ + char *p = getenv("CURL_SMALLREQSEND"); + if(p) { + size_t altsize = (size_t)strtoul(p, NULL, 10); + if(altsize && altsize < blen) + blen = altsize; + } + } +#endif + /* Make sure this doesn't send more body bytes than what the max send + speed says. The headers do not count to the max speed. */ + if(data->set.max_send_speed) { + size_t body_bytes = blen - hds_len; + if((curl_off_t)body_bytes > data->set.max_send_speed) + blen = hds_len + (size_t)data->set.max_send_speed; + } + + result = Curl_xfer_send(data, buf, blen, pnwritten); + if(!result && *pnwritten) { + if(hds_len) + Curl_debug(data, CURLINFO_HEADER_OUT, (char *)buf, + CURLMIN(hds_len, *pnwritten)); + if(*pnwritten > hds_len) { + size_t body_len = *pnwritten - hds_len; + Curl_debug(data, CURLINFO_DATA_OUT, (char *)buf + hds_len, body_len); + data->req.writebytecount += body_len; + Curl_pgrsSetUploadCounter(data, data->req.writebytecount); + } + } + return result; +} + +static CURLcode req_send_buffer_add(struct Curl_easy *data, + const char *buf, size_t blen, + size_t hds_len) +{ + CURLcode result = CURLE_OK; + ssize_t n; + n = Curl_bufq_write(&data->req.sendbuf, + (const unsigned char *)buf, blen, &result); + if(n < 0) + return result; + /* We rely on a SOFTLIMIT on sendbuf, so it can take all data in */ + DEBUGASSERT((size_t)n == blen); + data->req.sendbuf_hds_len += hds_len; + return CURLE_OK; +} + +static CURLcode req_send_buffer_flush(struct Curl_easy *data) +{ + CURLcode result = CURLE_OK; + const unsigned char *buf; + size_t blen; + + while(Curl_bufq_peek(&data->req.sendbuf, &buf, &blen)) { + size_t nwritten, hds_len = CURLMIN(data->req.sendbuf_hds_len, blen); + result = req_send(data, (const char *)buf, blen, hds_len, &nwritten); + if(result) + break; + + Curl_bufq_skip(&data->req.sendbuf, nwritten); + if(hds_len) + data->req.sendbuf_hds_len -= CURLMIN(hds_len, nwritten); + /* leave if we could not send all. Maybe network blocking or + * speed limits on transfer */ + if(nwritten < blen) + break; + } + return result; +} + +CURLcode Curl_req_flush(struct Curl_easy *data) +{ + CURLcode result; + + if(!data || !data->conn) + return CURLE_FAILED_INIT; + + if(!Curl_bufq_is_empty(&data->req.sendbuf)) { + result = req_send_buffer_flush(data); + if(result) + return result; + if(!Curl_bufq_is_empty(&data->req.sendbuf)) { + return CURLE_AGAIN; + } + } + return CURLE_OK; +} + +CURLcode Curl_req_send(struct Curl_easy *data, + const char *buf, size_t blen, + size_t hds_len) +{ + CURLcode result; + + if(!data || !data->conn) + return CURLE_FAILED_INIT; + + /* We always buffer and send from there. The reason is that on + * blocking, we can retry using the same memory address. This is + * important for TLS libraries that expect this. + * We *could* optimized for non-TLS transfers, but that would mean + * separate code paths and seems not worth it. */ + result = req_send_buffer_add(data, buf, blen, hds_len); + if(result) + return result; + result = req_send_buffer_flush(data); + if(result == CURLE_AGAIN) + result = CURLE_OK; + return result; +} + +bool Curl_req_want_send(struct Curl_easy *data) +{ + return data->req.sendbuf_init && !Curl_bufq_is_empty(&data->req.sendbuf); +} diff --git a/lib/request.h b/lib/request.h index c769e0e1ff6..54c784f6a88 100644 --- a/lib/request.h +++ b/lib/request.h @@ -64,7 +64,7 @@ struct SingleRequest { curl_off_t bytecount; /* total number of bytes read */ curl_off_t writebytecount; /* number of bytes written */ - curl_off_t pendingheader; /* this many bytes left to send is actually + size_t pendingheader; /* this many bytes left to send is actually header and not body */ struct curltime start; /* transfer started at this time */ unsigned int headerbytecount; /* received server headers (not CONNECT @@ -91,6 +91,7 @@ struct SingleRequest { * checks, pausing by client callbacks. */ struct Curl_cwriter *writer_stack; struct bufq sendbuf; /* data which needs to be send to the server */ + size_t sendbuf_hds_len; /* amount of header bytes in sendbuf */ time_t timeofdoc; long bodywrites; char *location; /* This points to an allocated version of the Location: @@ -100,7 +101,7 @@ struct SingleRequest { /* 'upload_present' is used to keep a byte counter of how much data there is still left in the buffer, aimed for upload. */ - ssize_t upload_present; + size_t upload_present; /* 'upload_fromhere' is used as a read-pointer when we uploaded parts of a buffer, so the next read should read from where this pointer points to, @@ -154,6 +155,7 @@ struct SingleRequest { that we are creating a request with an auth header, but it is not the final request in the auth negotiation. */ + BIT(sendbuf_init); /* sendbuf is initialized */ }; /** @@ -189,4 +191,34 @@ void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data); void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data); +/** + * Send request bytes for transfer. If not all could be sent + * they will be buffered. Use `Curl_req_flush()` to make sure + * bytes are really send. + * @param data the transfer making the request + * @param buf the bytes to send + * @param blen the number of bytes to send + * @param hds_len the number of bytes from the start that are headers + * @return CURLE_OK (on blocking with *pnwritten == 0) or error. + */ +CURLcode Curl_req_send(struct Curl_easy *data, + const char *buf, size_t blen, + size_t hds_len); + +/* Convenience for sending only header bytes */ +#define Curl_req_send_hds(data, buf, blen) \ + Curl_req_send((data), (buf), (blen), (blen)) + +/** + * Flush all buffered request bytes. + * @return CURLE_OK on success, CURLE_AGAIN if sending was blocked, + * or the error on the sending. + */ +CURLcode Curl_req_flush(struct Curl_easy *data); + +/** + * TRUE iff the request wants to send, e.g. has buffered bytes. + */ +bool Curl_req_want_send(struct Curl_easy *data); + #endif /* HEADER_CURL_REQUEST_H */ diff --git a/lib/rtsp.c b/lib/rtsp.c index b4290246ac9..a4c70a6b448 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -566,8 +566,9 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) } /* issue the request */ - result = Curl_buffer_send(&req_buffer, data, data->req.p.http, - &data->info.request_size, 0, FIRSTSOCKET); + result = Curl_req_send_hds(data, Curl_dyn_ptr(&req_buffer), + Curl_dyn_len(&req_buffer)); + Curl_dyn_free(&req_buffer); if(result) { failf(data, "Failed sending RTSP request"); return result; diff --git a/lib/smb.c b/lib/smb.c index ae585b4c1ae..72991f955ec 100644 --- a/lib/smb.c +++ b/lib/smb.c @@ -559,12 +559,12 @@ static void smb_format_message(struct Curl_easy *data, struct smb_header *h, h->pid = smb_swap16((unsigned short) pid); } -static CURLcode smb_send(struct Curl_easy *data, ssize_t len, +static CURLcode smb_send(struct Curl_easy *data, size_t len, size_t upload_size) { struct connectdata *conn = data->conn; struct smb_conn *smbc = &conn->proto.smbc; - ssize_t bytes_written; + size_t bytes_written; CURLcode result; result = Curl_xfer_send(data, data->state.ulbuf, len, &bytes_written); @@ -585,8 +585,8 @@ static CURLcode smb_flush(struct Curl_easy *data) { struct connectdata *conn = data->conn; struct smb_conn *smbc = &conn->proto.smbc; - ssize_t bytes_written; - ssize_t len = smbc->send_size - smbc->sent; + size_t bytes_written; + size_t len = smbc->send_size - smbc->sent; CURLcode result; if(!smbc->send_size) diff --git a/lib/smtp.c b/lib/smtp.c index e10a00477b1..ddee2223ac4 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -1395,8 +1395,7 @@ static CURLcode smtp_done(struct Curl_easy *data, CURLcode status, struct SMTP *smtp = data->req.p.smtp; struct pingpong *pp = &conn->proto.smtpc.pp; char *eob; - ssize_t len; - ssize_t bytes_written; + size_t len, bytes_written; (void)premature; diff --git a/lib/telnet.c b/lib/telnet.c index 9b6ae3c611a..56ee0855f0f 100644 --- a/lib/telnet.c +++ b/lib/telnet.c @@ -1231,20 +1231,24 @@ CURLcode telrcv(struct Curl_easy *data, static CURLcode send_telnet_data(struct Curl_easy *data, char *buffer, ssize_t nread) { - ssize_t i, outlen; + size_t i, outlen; unsigned char *outbuf; CURLcode result = CURLE_OK; - ssize_t bytes_written, total_written = 0; + size_t bytes_written; + size_t total_written = 0; struct connectdata *conn = data->conn; struct TELNET *tn = data->req.p.telnet; DEBUGASSERT(tn); + DEBUGASSERT(nread > 0); + if(nread < 0) + return CURLE_TOO_LARGE; if(memchr(buffer, CURL_IAC, nread)) { /* only use the escape buffer when necessary */ Curl_dyn_reset(&tn->out); - for(i = 0; i < nread && !result; i++) { + for(i = 0; i < (size_t)nread && !result; i++) { result = Curl_dyn_addn(&tn->out, &buffer[i], 1); if(!result && ((unsigned char)buffer[i] == CURL_IAC)) /* IAC is FF in hex */ @@ -1255,7 +1259,7 @@ static CURLcode send_telnet_data(struct Curl_easy *data, outbuf = Curl_dyn_uptr(&tn->out); } else { - outlen = nread; + outlen = (size_t)nread; outbuf = (unsigned char *)buffer; } while(!result && total_written < outlen) { diff --git a/lib/transfer.c b/lib/transfer.c index 1935909b91a..43d6f6f4b4c 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -607,7 +607,7 @@ static void win_update_buffer_size(curl_socket_t sockfd) #endif #define curl_upload_refill_watermark(data) \ - ((ssize_t)((data)->set.upload_buffer_size >> 5)) + ((size_t)((data)->set.upload_buffer_size >> 5)) /* * Send data to upload to the server, when the socket is writable. @@ -617,7 +617,7 @@ static CURLcode readwrite_upload(struct Curl_easy *data, int *didwhat) { ssize_t i, si; - ssize_t bytes_written; + size_t bytes_written; CURLcode result; ssize_t nread; /* number of bytes read */ bool sending_http_headers = FALSE; @@ -625,6 +625,14 @@ static CURLcode readwrite_upload(struct Curl_easy *data, *didwhat |= KEEP_SEND; + if(!(k->keepon & KEEP_SEND_PAUSE)) { + result = Curl_req_flush(data); + if(result == CURLE_AGAIN) /* unable to send all we have */ + return CURLE_OK; + else if(result) + return result; + } + do { curl_off_t nbody; ssize_t offset = 0; @@ -633,8 +641,8 @@ static CURLcode readwrite_upload(struct Curl_easy *data, k->upload_present < curl_upload_refill_watermark(data) && !k->upload_chunky &&/*(variable sized chunked header; append not safe)*/ !k->upload_done && /*!(k->upload_done once k->upload_present sent)*/ - !(k->writebytecount + k->upload_present - k->pendingheader == - data->state.infilesize)) { + !(k->writebytecount + (curl_off_t)k->upload_present - + (curl_off_t)k->pendingheader == data->state.infilesize)) { offset = k->upload_present; } @@ -770,9 +778,6 @@ static CURLcode readwrite_upload(struct Curl_easy *data, that instead of reading more data */ } - if(!Curl_bufq_is_empty(&k->sendbuf)) { - DEBUGASSERT(0); - } /* write to socket (send away data) */ result = Curl_xfer_send(data, k->upload_fromhere, /* buffer pointer */ @@ -793,9 +798,9 @@ static CURLcode readwrite_upload(struct Curl_easy *data, if(k->pendingheader) { /* parts of what was sent was header */ - curl_off_t n = CURLMIN(k->pendingheader, bytes_written); + size_t n = CURLMIN(k->pendingheader, bytes_written); /* show the data before we change the pointer upload_fromhere */ - Curl_debug(data, CURLINFO_HEADER_OUT, k->upload_fromhere, (size_t)n); + Curl_debug(data, CURLINFO_HEADER_OUT, k->upload_fromhere, n); k->pendingheader -= n; nbody = bytes_written - n; /* size of the written body part */ } @@ -1607,22 +1612,19 @@ void Curl_xfer_setup( struct SingleRequest *k = &data->req; struct connectdata *conn = data->conn; struct HTTP *http = data->req.p.http; - bool httpsending; + bool want_send = Curl_req_want_send(data); DEBUGASSERT(conn != NULL); DEBUGASSERT((sockindex <= 1) && (sockindex >= -1)); DEBUGASSERT((writesockindex <= 1) && (writesockindex >= -1)); - httpsending = ((conn->handler->protocol&PROTO_FAMILY_HTTP) && - (http->sending == HTTPSEND_REQUEST)); - - if(conn->bits.multiplex || conn->httpversion >= 20 || httpsending) { + if(conn->bits.multiplex || conn->httpversion >= 20 || want_send) { /* when multiplexing, the read/write sockets need to be the same! */ conn->sockfd = sockindex == -1 ? ((writesockindex == -1 ? CURL_SOCKET_BAD : conn->sock[writesockindex])) : conn->sock[sockindex]; conn->writesockfd = conn->sockfd; - if(httpsending) + if(want_send) /* special and very HTTP-specific */ writesockindex = FIRSTSOCKET; } @@ -1732,7 +1734,7 @@ CURLcode Curl_xfer_write_done(struct Curl_easy *data, bool premature) CURLcode Curl_xfer_send(struct Curl_easy *data, const void *buf, size_t blen, - ssize_t *pnwritten) + size_t *pnwritten) { CURLcode result; int sockindex; diff --git a/lib/transfer.h b/lib/transfer.h index 917a3d23e4a..81c70718077 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -97,7 +97,7 @@ CURLcode Curl_xfer_write_done(struct Curl_easy *data, bool premature); */ CURLcode Curl_xfer_send(struct Curl_easy *data, const void *buf, size_t blen, - ssize_t *pnwritten); + size_t *pnwritten); /** * Receive data on the socket/connection filter designated diff --git a/lib/url.c b/lib/url.c index ae976d7b11d..d72dfc773bb 100644 --- a/lib/url.c +++ b/lib/url.c @@ -3845,9 +3845,6 @@ CURLcode Curl_connect(struct Curl_easy *data, /* init the single-transfer specific data */ Curl_req_reset(&data->req, data); - memset(&data->req, 0, sizeof(struct SingleRequest)); - data->req.size = data->req.maxdownload = -1; - data->req.no_body = data->set.opt_no_body; /* call the stuff that needs to be called */ result = create_conn(data, &conn, asyncp); diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index 33dbe1c9200..36975420bc3 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -3213,7 +3213,7 @@ static ssize_t ssh_tls_send(libssh2_socket_t sock, const void *buffer, size_t length, int flags, void **abstract) { struct Curl_easy *data = (struct Curl_easy *)*abstract; - ssize_t nwrite; + size_t nwrite; CURLcode result; struct connectdata *conn = data->conn; Curl_send *backup = conn->send[0]; @@ -3230,8 +3230,8 @@ static ssize_t ssh_tls_send(libssh2_socket_t sock, const void *buffer, return -EAGAIN; /* magic return code for libssh2 */ else if(result) return -1; /* error */ - Curl_debug(data, CURLINFO_DATA_OUT, (char *)buffer, (size_t)nwrite); - return nwrite; + Curl_debug(data, CURLINFO_DATA_OUT, (char *)buffer, nwrite); + return (ssize_t)nwrite; } #endif diff --git a/lib/ws.c b/lib/ws.c index b2305932acc..37108946d41 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -1014,8 +1014,7 @@ static CURLcode ws_flush(struct Curl_easy *data, struct websocket *ws, if(!Curl_bufq_is_empty(&ws->sendbuf)) { CURLcode result; const unsigned char *out; - size_t outlen; - ssize_t n; + size_t outlen, n; while(Curl_bufq_peek(&ws->sendbuf, &out, &outlen)) { if(data->set.connect_only) @@ -1044,8 +1043,8 @@ static CURLcode ws_flush(struct Curl_easy *data, struct websocket *ws, } } else { - infof(data, "WS: flushed %zu bytes", (size_t)n); - Curl_bufq_skip(&ws->sendbuf, (size_t)n); + infof(data, "WS: flushed %zu bytes", n); + Curl_bufq_skip(&ws->sendbuf, n); } } } @@ -1058,8 +1057,8 @@ CURL_EXTERN CURLcode curl_ws_send(CURL *data, const void *buffer, unsigned int flags) { struct websocket *ws; - ssize_t nwritten, n; - size_t space; + ssize_t n; + size_t nwritten, space; CURLcode result; *sent = 0; @@ -1097,7 +1096,7 @@ CURL_EXTERN CURLcode curl_ws_send(CURL *data, const void *buffer, infof(data, "WS: wanted to send %zu bytes, sent %zu bytes", buflen, nwritten); - *sent = (nwritten >= 0)? (size_t)nwritten : 0; + *sent = nwritten; return result; } From f0eacd94476b431bcea565f8f94e62e336e4fde0 Mon Sep 17 00:00:00 2001 From: Andreas Kiefer Date: Mon, 26 Feb 2024 21:08:10 +0100 Subject: [PATCH 380/509] fopen: fix narrowing conversion warning on 32-bit Android This was fixed in commit 06dc599405f, but came back in commit 03cb1ff4d62. When building for 32-bit ARM or x86 Android, `st_mode` is defined as `unsigned int` instead of `mode_t`, resulting in a `-Wimplicit-int-conversion` clang warning because `mode_t` is `unsigned short`. Add a cast to silence the warning, but only for 32-bit Android builds, because other architectures and platforms are not affected. Ref: https://android.googlesource.com/platform/bionic/+/refs/tags/ndk-r25c/libc/include/sys/stat.h#86 Closes https://github.com/curl/curl/pull/12998 --- lib/fopen.c | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/lib/fopen.c b/lib/fopen.c index 851279fe12d..0bdf2e11b63 100644 --- a/lib/fopen.c +++ b/lib/fopen.c @@ -129,7 +129,12 @@ CURLcode Curl_fopen(struct Curl_easy *data, const char *filename, } result = CURLE_WRITE_ERROR; +#if (defined(ANDROID) || defined(__ANDROID__)) && \ + (defined(__i386__) || defined(__arm__)) + fd = open(tempstore, O_WRONLY | O_CREAT | O_EXCL, (mode_t)(0600|sb.st_mode)); +#else fd = open(tempstore, O_WRONLY | O_CREAT | O_EXCL, 0600|sb.st_mode); +#endif if(fd == -1) goto fail; From 17d302e56221f5040092db77d4f85086e8a20e0e Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Tue, 27 Feb 2024 15:43:56 +0100 Subject: [PATCH 381/509] setopt: Fix disabling all protocols When disabling all protocols without enabling any, the resulting set of allowed protocols remained the default set. Clearing the allowed set before inspecting the passed value from --proto make the set empty even in the errorpath of no protocols enabled. Co-authored-by: Dan Fandrich Reported-by: Dan Fandrich Reviewed-by: Daniel Stenberg Closes: #13004 --- lib/setopt.c | 16 ++++++++-------- tests/data/Makefile.inc | 2 +- tests/data/test1474 | 42 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 9 deletions(-) create mode 100644 tests/data/test1474 diff --git a/lib/setopt.c b/lib/setopt.c index 6a4990cce67..ce1321fc80b 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -155,6 +155,12 @@ static CURLcode setstropt_userpwd(char *option, char **userp, char **passwdp) static CURLcode protocol2num(const char *str, curl_prot_t *val) { + /* + * We are asked to cherry-pick protocols, so play it safe and disallow all + * protocols to start with, and re-add the wanted ones back in. + */ + *val = 0; + if(!str) return CURLE_BAD_FUNCTION_ARGUMENT; @@ -163,8 +169,6 @@ static CURLcode protocol2num(const char *str, curl_prot_t *val) return CURLE_OK; } - *val = 0; - do { const char *token = str; size_t tlen; @@ -2654,22 +2658,18 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) break; case CURLOPT_PROTOCOLS_STR: { - curl_prot_t prot; argptr = va_arg(param, char *); - result = protocol2num(argptr, &prot); + result = protocol2num(argptr, &data->set.allowed_protocols); if(result) return result; - data->set.allowed_protocols = prot; break; } case CURLOPT_REDIR_PROTOCOLS_STR: { - curl_prot_t prot; argptr = va_arg(param, char *); - result = protocol2num(argptr, &prot); + result = protocol2num(argptr, &data->set.redir_protocols); if(result) return result; - data->set.redir_protocols = prot; break; } diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index c20f90d945c..b80ffb618e5 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -187,7 +187,7 @@ test1439 test1440 test1441 test1442 test1443 test1444 test1445 test1446 \ test1447 test1448 test1449 test1450 test1451 test1452 test1453 test1454 \ test1455 test1456 test1457 test1458 test1459 test1460 test1461 test1462 \ test1463 test1464 test1465 test1466 test1467 test1468 test1469 test1470 \ -test1471 test1472 test1473 test1475 test1476 test1477 test1478 \ +test1471 test1472 test1473 test1474 test1475 test1476 test1477 test1478 \ \ test1500 test1501 test1502 test1503 test1504 test1505 test1506 test1507 \ test1508 test1509 test1510 test1511 test1512 test1513 test1514 test1515 \ diff --git a/tests/data/test1474 b/tests/data/test1474 new file mode 100644 index 00000000000..c66fa281048 --- /dev/null +++ b/tests/data/test1474 @@ -0,0 +1,42 @@ + + + +HTTP +HTTP GET +--proto + + + +# +# Server-side + + + + + +# +# Client-side + + +none + + +http + + +--proto -all disables all protocols + + +--proto -all http://%HOSTIP:%NOLISTENPORT/%TESTNUMBER + + + +# +# Verify data after the test has been "shot" + +# 1 - Protocol "http" disabled + +1 + + + From 6e494a2390702048e00e71e202e6210a8486c200 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 10:35:28 +0100 Subject: [PATCH 382/509] docs: more language cleanups - present tense - avoid bad words Closes #13003 --- .github/scripts/badwords.txt | 4 +- .github/workflows/badwords.yml | 2 +- docs/HTTP3.md | 6 ++- docs/MAIL-ETIQUETTE | 57 ++++++++++++------------- docs/SSLCERTS.md | 19 ++++----- docs/cmdline-opts/MANPAGE.md | 4 +- docs/cmdline-opts/_ENVIRONMENT.md | 12 +++--- docs/cmdline-opts/_EXITCODES.md | 2 +- docs/cmdline-opts/_URL.md | 4 +- docs/cmdline-opts/alt-svc.md | 10 ++--- docs/cmdline-opts/config.md | 2 +- docs/cmdline-opts/cookie-jar.md | 2 +- docs/cmdline-opts/cookie.md | 6 +-- docs/cmdline-opts/create-dirs.md | 2 +- docs/cmdline-opts/data.md | 10 ++--- docs/cmdline-opts/digest.md | 2 +- docs/cmdline-opts/doh-url.md | 2 +- docs/cmdline-opts/fail-early.md | 2 +- docs/cmdline-opts/form-escape.md | 2 +- docs/cmdline-opts/form.md | 6 +-- docs/cmdline-opts/ftp-account.md | 2 +- docs/cmdline-opts/ftp-port.md | 2 +- docs/cmdline-opts/hsts.md | 18 ++++---- docs/cmdline-opts/insecure.md | 8 ++-- docs/cmdline-opts/interface.md | 2 +- docs/cmdline-opts/ipfs-gateway.md | 14 +++--- docs/cmdline-opts/ipv4.md | 2 +- docs/cmdline-opts/ipv6.md | 2 +- docs/cmdline-opts/json.md | 8 ++-- docs/cmdline-opts/key.md | 4 +- docs/cmdline-opts/list-only.md | 8 ++-- docs/cmdline-opts/mail-rcpt.md | 8 ++-- docs/cmdline-opts/negotiate.md | 2 +- docs/cmdline-opts/netrc.md | 6 +-- docs/cmdline-opts/next.md | 2 +- docs/cmdline-opts/oauth2-bearer.md | 6 +-- docs/cmdline-opts/output.md | 2 +- docs/cmdline-opts/proto-default.md | 2 +- docs/cmdline-opts/proxy-user.md | 8 ++-- docs/cmdline-opts/pubkey.md | 4 +- docs/cmdline-opts/quote.md | 6 +-- docs/cmdline-opts/remote-header-name.md | 16 +++---- docs/cmdline-opts/remote-name-all.md | 4 +- docs/cmdline-opts/remote-name.md | 14 +++--- docs/cmdline-opts/request.md | 2 +- docs/cmdline-opts/retry-all-errors.md | 2 +- docs/cmdline-opts/socks4.md | 2 +- docs/cmdline-opts/socks4a.md | 2 +- docs/cmdline-opts/socks5-hostname.md | 4 +- docs/cmdline-opts/socks5.md | 2 +- docs/cmdline-opts/stderr.md | 2 +- docs/cmdline-opts/tlsuser.md | 2 +- docs/cmdline-opts/trace-ascii.md | 2 +- docs/cmdline-opts/trace.md | 2 +- docs/cmdline-opts/upload-file.md | 14 +++--- docs/cmdline-opts/user.md | 21 +++++---- docs/cmdline-opts/verbose.md | 2 +- docs/cmdline-opts/write-out.md | 12 +++--- src/tool_listhelp.c | 20 ++++----- 59 files changed, 198 insertions(+), 199 deletions(-) diff --git a/.github/scripts/badwords.txt b/.github/scripts/badwords.txt index 36acde74461..2942ce8d8a6 100644 --- a/.github/scripts/badwords.txt +++ b/.github/scripts/badwords.txt @@ -41,8 +41,8 @@ host name\b:hostname host names\b:hostnames file name\b:filename file names\b:filenames -user name\b:username -user names\b:usernames +\buser name\b:username +\buser names\b:usernames didn't:did not doesn't:does not won't:will not diff --git a/.github/workflows/badwords.yml b/.github/workflows/badwords.yml index fc0b52001b9..0165d9bfbe9 100644 --- a/.github/workflows/badwords.yml +++ b/.github/workflows/badwords.yml @@ -24,4 +24,4 @@ jobs: - uses: actions/checkout@v2 - name: check - run: ./.github/scripts/badwords.pl < .github/scripts/badwords.txt docs/*.md docs/libcurl/*.md docs/libcurl/opts/*.md + 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/docs/HTTP3.md b/docs/HTTP3.md index 758d8ab08c8..90f1c31e3da 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -196,7 +196,8 @@ 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 @@ -232,7 +233,8 @@ 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`. # msh3 (msquic) version 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/SSLCERTS.md b/docs/SSLCERTS.md index d1aca1a7b53..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`. @@ -107,9 +106,9 @@ server, do one of the following: 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) diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index efacd6a3b23..51310564fe7 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -22,8 +22,8 @@ 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. diff --git a/docs/cmdline-opts/_ENVIRONMENT.md b/docs/cmdline-opts/_ENVIRONMENT.md index cf30d47404b..af60ac8d0b8 100644 --- a/docs/cmdline-opts/_ENVIRONMENT.md +++ b/docs/cmdline-opts/_ENVIRONMENT.md @@ -23,9 +23,9 @@ SMTP, LDAP, etc. Sets the proxy server to use if no protocol-specific proxy is set. ## `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. +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 @@ -40,7 +40,7 @@ accesses the target URL directly, and accesses the target URL through the proxy. -The list of host names can also be include numerical IP addresses, and IPv6 +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 @@ -97,8 +97,8 @@ if Schannel is used as the TLS backend. 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 file name, curl stores TLS secrets +## `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 diff --git a/docs/cmdline-opts/_EXITCODES.md b/docs/cmdline-opts/_EXITCODES.md index ac7ab5ca15e..d7b71fda0da 100644 --- a/docs/cmdline-opts/_EXITCODES.md +++ b/docs/cmdline-opts/_EXITCODES.md @@ -135,7 +135,7 @@ Sending the data requires a rewind that failed. ## 66 Failed to initialize SSL Engine. ## 67 -The user name, password, or similar was not accepted and curl failed to log in. +The username, password, or similar was not accepted and curl failed to log in. ## 68 File not found on TFTP server. ## 69 diff --git a/docs/cmdline-opts/_URL.md b/docs/cmdline-opts/_URL.md index 83ccfdd98df..48ae02a556f 100644 --- a/docs/cmdline-opts/_URL.md +++ b/docs/cmdline-opts/_URL.md @@ -6,8 +6,8 @@ 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. +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 diff --git a/docs/cmdline-opts/alt-svc.md b/docs/cmdline-opts/alt-svc.md index 0a0f17df5a2..a30aff7b650 100644 --- a/docs/cmdline-opts/alt-svc.md +++ b/docs/cmdline-opts/alt-svc.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: alt-svc -Arg: +Arg: Protocols: HTTPS Help: Enable alt-svc with this cache file Added: 7.64.1 @@ -17,12 +17,12 @@ Example: # `--alt-svc` -This option enables the alt-svc parser in curl. If the file name points to an +This option enables the alt-svc parser in curl. If the filename 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. +cache is saved to the filename 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. +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/config.md b/docs/cmdline-opts/config.md index fa206c43b80..181825ac354 100644 --- a/docs/cmdline-opts/config.md +++ b/docs/cmdline-opts/config.md @@ -77,7 +77,7 @@ config file is checked for in the following places in this order: 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. +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/cookie-jar.md b/docs/cmdline-opts/cookie-jar.md index 5453152e444..f4331a48d2e 100644 --- a/docs/cmdline-opts/cookie-jar.md +++ b/docs/cmdline-opts/cookie-jar.md @@ -22,7 +22,7 @@ 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 filename 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 diff --git a/docs/cmdline-opts/cookie.md b/docs/cmdline-opts/cookie.md index c4415bf80aa..0676d80f17c 100644 --- a/docs/cmdline-opts/cookie.md +++ b/docs/cmdline-opts/cookie.md @@ -34,9 +34,9 @@ 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. If the file name is an empty string ("") and is the only cookie input, -curl will activate the cookie engine without any cookies. +If the filename is exactly a minus ("-"), curl instead 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. diff --git a/docs/cmdline-opts/create-dirs.md b/docs/cmdline-opts/create-dirs.md index de48807d4c7..fcbeb3343b6 100644 --- a/docs/cmdline-opts/create-dirs.md +++ b/docs/cmdline-opts/create-dirs.md @@ -18,7 +18,7 @@ Example: 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 +--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. diff --git a/docs/cmdline-opts/data.md b/docs/cmdline-opts/data.md index fb3b8487230..71dd36e046c 100644 --- a/docs/cmdline-opts/data.md +++ b/docs/cmdline-opts/data.md @@ -37,11 +37,11 @@ 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 +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 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 diff --git a/docs/cmdline-opts/digest.md b/docs/cmdline-opts/digest.md index f05c01fed08..5bba975de0d 100644 --- a/docs/cmdline-opts/digest.md +++ b/docs/cmdline-opts/digest.md @@ -20,4 +20,4 @@ Example: 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. +combination with the normal --user option to set username and password. diff --git a/docs/cmdline-opts/doh-url.md b/docs/cmdline-opts/doh-url.md index d12bf5194fa..23754cac19c 100644 --- a/docs/cmdline-opts/doh-url.md +++ b/docs/cmdline-opts/doh-url.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: doh-url Arg: -Help: Resolve host names over DoH +Help: Resolve hostnames over DoH Added: 7.62.0 Category: dns Multi: single diff --git a/docs/cmdline-opts/fail-early.md b/docs/cmdline-opts/fail-early.md index b68160c2018..40a2e012618 100644 --- a/docs/cmdline-opts/fail-early.md +++ b/docs/cmdline-opts/fail-early.md @@ -21,7 +21,7 @@ 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. +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 diff --git a/docs/cmdline-opts/form-escape.md b/docs/cmdline-opts/form-escape.md index 62973f172af..d405bef95cd 100644 --- a/docs/cmdline-opts/form-escape.md +++ b/docs/cmdline-opts/form-escape.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: form-escape -Help: Escape multipart form field/file names using backslash +Help: Escape multipart form field/filenames using backslash Protocols: HTTP Added: 7.81.0 Category: http upload diff --git a/docs/cmdline-opts/form.md b/docs/cmdline-opts/form.md index 3e3f475af8c..25b4bc73050 100644 --- a/docs/cmdline-opts/form.md +++ b/docs/cmdline-opts/form.md @@ -28,9 +28,9 @@ 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 +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. diff --git a/docs/cmdline-opts/ftp-account.md b/docs/cmdline-opts/ftp-account.md index 2f336394330..e275349dee0 100644 --- a/docs/cmdline-opts/ftp-account.md +++ b/docs/cmdline-opts/ftp-account.md @@ -16,5 +16,5 @@ Example: # `--ftp-account` -When an FTP server asks for "account data" after user name and password has +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-port.md b/docs/cmdline-opts/ftp-port.md index 370f68c1f46..c7fb37a843e 100644 --- a/docs/cmdline-opts/ftp-port.md +++ b/docs/cmdline-opts/ftp-port.md @@ -32,7 +32,7 @@ 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 -## host name +## hostname e.g. **my.host.domain** to specify the machine ## - diff --git a/docs/cmdline-opts/hsts.md b/docs/cmdline-opts/hsts.md index 82b61959a49..320377f463e 100644 --- a/docs/cmdline-opts/hsts.md +++ b/docs/cmdline-opts/hsts.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: hsts -Arg: +Arg: Protocols: HTTPS Help: Enable HSTS with this cache file Added: 7.74.0 @@ -16,17 +16,17 @@ Example: # `--hsts` -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. +This option enables 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 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 +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 "" file name (zero length) to avoid loading/saving and make curl -just handle HSTS in memory. +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/insecure.md b/docs/cmdline-opts/insecure.md index 1f5d048f7ce..b1c056b448b 100644 --- a/docs/cmdline-opts/insecure.md +++ b/docs/cmdline-opts/insecure.md @@ -24,14 +24,14 @@ 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: +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 host names and their public keys. +".ssh" subdirectory, which contains hostnames and their public keys. **WARNING**: using this option makes the transfer insecure. diff --git a/docs/cmdline-opts/interface.md b/docs/cmdline-opts/interface.md index 44221d366a8..c938fd2717b 100644 --- a/docs/cmdline-opts/interface.md +++ b/docs/cmdline-opts/interface.md @@ -16,7 +16,7 @@ Example: # `--interface` Perform an operation using a specified interface. You can enter interface -name, IP address or host name. An example could look like: +name, IP address or hostname. An example could look like: curl --interface eth0:1 https://www.example.com/ diff --git a/docs/cmdline-opts/ipfs-gateway.md b/docs/cmdline-opts/ipfs-gateway.md index 57c747b0cd9..63429d83d12 100644 --- a/docs/cmdline-opts/ipfs-gateway.md +++ b/docs/cmdline-opts/ipfs-gateway.md @@ -17,9 +17,9 @@ Example: # `--ipfs-gateway` -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. +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: @@ -29,11 +29,11 @@ If you run a local IPFS node, this gateway is by default available under 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 +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 will not notice this when using curl. A +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.md b/docs/cmdline-opts/ipv4.md index 49d4df9701f..70bbc0f11aa 100644 --- a/docs/cmdline-opts/ipv4.md +++ b/docs/cmdline-opts/ipv4.md @@ -20,5 +20,5 @@ Example: # `--ipv4` -This option tells curl to use IPv4 addresses only when resolving host names, +This option tells curl to use IPv4 addresses only when resolving hostnames, and not for example try IPv6. diff --git a/docs/cmdline-opts/ipv6.md b/docs/cmdline-opts/ipv6.md index 0612ec1bfd1..fbacbec3f7c 100644 --- a/docs/cmdline-opts/ipv6.md +++ b/docs/cmdline-opts/ipv6.md @@ -20,5 +20,5 @@ Example: # `--ipv6` -This option tells curl to use IPv6 addresses only when resolving host names, +This option tells curl to use IPv6 addresses only when resolving hostnames, and not for example try IPv4. diff --git a/docs/cmdline-opts/json.md b/docs/cmdline-opts/json.md index 03d064029bb..8056e62e7cf 100644 --- a/docs/cmdline-opts/json.md +++ b/docs/cmdline-opts/json.md @@ -31,10 +31,10 @@ works as a shortcut for passing on these three options: 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 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. diff --git a/docs/cmdline-opts/key.md b/docs/cmdline-opts/key.md index 1d3d7999650..80540ab9570 100644 --- a/docs/cmdline-opts/key.md +++ b/docs/cmdline-opts/key.md @@ -4,7 +4,7 @@ SPDX-License-Identifier: curl Long: key Arg: Protocols: TLS SSH -Help: Private key file name +Help: Private key filename Category: tls ssh Added: 7.9.3 Multi: single @@ -17,7 +17,7 @@ Example: # `--key` -Private key file name. Allows you to provide your private key in this separate +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`. diff --git a/docs/cmdline-opts/list-only.md b/docs/cmdline-opts/list-only.md index 4f688f7b8cc..52f0b6fc93c 100644 --- a/docs/cmdline-opts/list-only.md +++ b/docs/cmdline-opts/list-only.md @@ -28,10 +28,10 @@ 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. +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. (POP3) When retrieving a specific email from POP3, this switch forces a LIST command diff --git a/docs/cmdline-opts/mail-rcpt.md b/docs/cmdline-opts/mail-rcpt.md index 3f89feb23dd..bd787c2fa08 100644 --- a/docs/cmdline-opts/mail-rcpt.md +++ b/docs/cmdline-opts/mail-rcpt.md @@ -16,12 +16,12 @@ Example: # `--mail-rcpt` -Specify a single email address, user name or mailing list name. Repeat this +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 user name or user name and domain (as per Section 3.5 of -RFC 5321). (Added in 7.34.0) +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". diff --git a/docs/cmdline-opts/negotiate.md b/docs/cmdline-opts/negotiate.md index f55f9212d90..8f30888a824 100644 --- a/docs/cmdline-opts/negotiate.md +++ b/docs/cmdline-opts/negotiate.md @@ -24,5 +24,5 @@ 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 +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.md b/docs/cmdline-opts/netrc.md index dad3e6b00c4..b8b1b943670 100644 --- a/docs/cmdline-opts/netrc.md +++ b/docs/cmdline-opts/netrc.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: netrc Short: n -Help: Must read .netrc for user name and password +Help: Must read .netrc for username and password Category: curl Added: 4.6 Mutexed: netrc-file netrc-optional @@ -30,8 +30,8 @@ On Windows two filenames in the home directory are checked: *.netrc* and 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: +the machine host.domain.com with username 'myself' and password 'secret' could +look similar to: machine host.domain.com login myself diff --git a/docs/cmdline-opts/next.md b/docs/cmdline-opts/next.md index ef647b6ebf7..2f484f4c3b2 100644 --- a/docs/cmdline-opts/next.md +++ b/docs/cmdline-opts/next.md @@ -22,7 +22,7 @@ Example: 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 +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 diff --git a/docs/cmdline-opts/oauth2-bearer.md b/docs/cmdline-opts/oauth2-bearer.md index ebbcbeb5406..ee9ec5dccf1 100644 --- a/docs/cmdline-opts/oauth2-bearer.md +++ b/docs/cmdline-opts/oauth2-bearer.md @@ -19,7 +19,7 @@ Example: # `--oauth2-bearer` 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. +is used in conjunction with the username which can be specified as part of the +--url or --user options. -The Bearer Token and user name are formatted according to RFC 6750. +The Bearer Token and username are formatted according to RFC 6750. diff --git a/docs/cmdline-opts/output.md b/docs/cmdline-opts/output.md index 2b2527663b6..f7beaba6dd5 100644 --- a/docs/cmdline-opts/output.md +++ b/docs/cmdline-opts/output.md @@ -23,7 +23,7 @@ Example: 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 file name. That variable is then replaced with the +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" diff --git a/docs/cmdline-opts/proto-default.md b/docs/cmdline-opts/proto-default.md index 69a4c2cbe11..38d9dffebe4 100644 --- a/docs/cmdline-opts/proto-default.md +++ b/docs/cmdline-opts/proto-default.md @@ -23,5 +23,5 @@ An unknown or unsupported protocol causes error This option does not change the default proxy protocol (http). -Without this option set, curl guesses protocol based on the host name, see +Without this option set, curl guesses protocol based on the hostname, see --url for details. diff --git a/docs/cmdline-opts/proxy-user.md b/docs/cmdline-opts/proxy-user.md index 3f12369df7d..8ba19322006 100644 --- a/docs/cmdline-opts/proxy-user.md +++ b/docs/cmdline-opts/proxy-user.md @@ -11,16 +11,16 @@ Multi: single See-also: - proxy-pass Example: - - --proxy-user name:pwd -x proxy $URL + - --proxy-user smith:secret -x proxy $URL --- # `--proxy-user` -Specify the user name and password to use for proxy authentication. +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 user name and password -from your environment by specifying a single colon with this option: "-U :". +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 diff --git a/docs/cmdline-opts/pubkey.md b/docs/cmdline-opts/pubkey.md index b849bfe1d01..94e50e4e94c 100644 --- a/docs/cmdline-opts/pubkey.md +++ b/docs/cmdline-opts/pubkey.md @@ -4,7 +4,7 @@ SPDX-License-Identifier: curl Long: pubkey Arg: Protocols: SFTP SCP -Help: SSH Public key file name +Help: SSH Public key filename Category: sftp scp auth Added: 7.16.2 Multi: single @@ -16,7 +16,7 @@ Example: # `--pubkey` -Public key file name. Allows you to provide your public key in this separate +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 diff --git a/docs/cmdline-opts/quote.md b/docs/cmdline-opts/quote.md index 06f6a50fa41..4972c96f549 100644 --- a/docs/cmdline-opts/quote.md +++ b/docs/cmdline-opts/quote.md @@ -37,9 +37,9 @@ 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: +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 diff --git a/docs/cmdline-opts/remote-header-name.md b/docs/cmdline-opts/remote-header-name.md index d68e17b74b8..46b8ad288e3 100644 --- a/docs/cmdline-opts/remote-header-name.md +++ b/docs/cmdline-opts/remote-header-name.md @@ -18,19 +18,19 @@ Example: 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 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 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. +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 file name, so -this option may provide you with rather unexpected file names. +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). diff --git a/docs/cmdline-opts/remote-name-all.md b/docs/cmdline-opts/remote-name-all.md index 0688286283f..19f7de76798 100644 --- a/docs/cmdline-opts/remote-name-all.md +++ b/docs/cmdline-opts/remote-name-all.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: remote-name-all -Help: Use the remote file name for all URLs +Help: Use the remote filename for all URLs Added: 7.19.0 Category: output Multi: boolean @@ -15,6 +15,6 @@ Example: # `--remote-name-all` 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 +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.md b/docs/cmdline-opts/remote-name.md index 498bc31e77b..487799fafc9 100644 --- a/docs/cmdline-opts/remote-name.md +++ b/docs/cmdline-opts/remote-name.md @@ -24,13 +24,13 @@ 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. +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 file name. If it has %20 or other URL -encoded parts of the name, they end up as-is as file name. +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/request.md b/docs/cmdline-opts/request.md index ccfe99c7cc2..4a6304c1be5 100644 --- a/docs/cmdline-opts/request.md +++ b/docs/cmdline-opts/request.md @@ -34,7 +34,7 @@ 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 +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 diff --git a/docs/cmdline-opts/retry-all-errors.md b/docs/cmdline-opts/retry-all-errors.md index d2f14e8085d..6d3deebc76c 100644 --- a/docs/cmdline-opts/retry-all-errors.md +++ b/docs/cmdline-opts/retry-all-errors.md @@ -19,7 +19,7 @@ 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 +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 diff --git a/docs/cmdline-opts/socks4.md b/docs/cmdline-opts/socks4.md index 0971f2b5330..e74fa787ce0 100644 --- a/docs/cmdline-opts/socks4.md +++ b/docs/cmdline-opts/socks4.md @@ -18,7 +18,7 @@ Example: # `--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 host name +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. diff --git a/docs/cmdline-opts/socks4a.md b/docs/cmdline-opts/socks4a.md index 00e5a961705..49fb9a275a8 100644 --- a/docs/cmdline-opts/socks4a.md +++ b/docs/cmdline-opts/socks4a.md @@ -18,7 +18,7 @@ Example: # `--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 host name. +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` diff --git a/docs/cmdline-opts/socks5-hostname.md b/docs/cmdline-opts/socks5-hostname.md index d38e501ee3f..1a5e4c1b5e3 100644 --- a/docs/cmdline-opts/socks5-hostname.md +++ b/docs/cmdline-opts/socks5-hostname.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: socks5-hostname Arg: -Help: SOCKS5 proxy, pass host name to proxy +Help: SOCKS5 proxy, pass hostname to proxy Added: 7.18.0 Category: proxy Multi: single @@ -16,7 +16,7 @@ Example: # `--socks5-hostname` -Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If +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. diff --git a/docs/cmdline-opts/socks5.md b/docs/cmdline-opts/socks5.md index a1e1853607e..f17dfeb71fa 100644 --- a/docs/cmdline-opts/socks5.md +++ b/docs/cmdline-opts/socks5.md @@ -16,7 +16,7 @@ Example: # `--socks5` -Use the specified SOCKS5 proxy - but resolve the host name locally. If the +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. diff --git a/docs/cmdline-opts/stderr.md b/docs/cmdline-opts/stderr.md index 6c93dc8a301..bb42497de33 100644 --- a/docs/cmdline-opts/stderr.md +++ b/docs/cmdline-opts/stderr.md @@ -17,5 +17,5 @@ Example: # `--stderr` -Redirect all writes to stderr to the specified file instead. If the file name +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/tlsuser.md b/docs/cmdline-opts/tlsuser.md index 5ffbb670536..7f4636fa0a2 100644 --- a/docs/cmdline-opts/tlsuser.md +++ b/docs/cmdline-opts/tlsuser.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: tlsuser Arg: -Help: TLS user name +Help: TLS username Added: 7.21.4 Protocols: TLS Category: tls auth diff --git a/docs/cmdline-opts/trace-ascii.md b/docs/cmdline-opts/trace-ascii.md index 130f708c1aa..651540565b0 100644 --- a/docs/cmdline-opts/trace-ascii.md +++ b/docs/cmdline-opts/trace-ascii.md @@ -27,5 +27,5 @@ ASCII part of the dump. It makes smaller output that might be easier to read for untrained humans. Note that verbose output of curl activities and network traffic might contain -sensitive data, including user names, credentials or secret data content. Be +sensitive data, including usernames, credentials or secret data content. Be aware and be careful when sharing trace logs with others. diff --git a/docs/cmdline-opts/trace.md b/docs/cmdline-opts/trace.md index 90bb28f4f3a..ed9e681f329 100644 --- a/docs/cmdline-opts/trace.md +++ b/docs/cmdline-opts/trace.md @@ -26,5 +26,5 @@ the output sent to stdout. Use "%" as filename to have the output sent to stderr. Note that verbose output of curl activities and network traffic might contain -sensitive data, including user names, credentials or secret data content. Be +sensitive data, including usernames, credentials or secret data content. Be aware and be careful when sharing trace logs with others. diff --git a/docs/cmdline-opts/upload-file.md b/docs/cmdline-opts/upload-file.md index 60ee8531b8f..eb4b8b77661 100644 --- a/docs/cmdline-opts/upload-file.md +++ b/docs/cmdline-opts/upload-file.md @@ -26,19 +26,19 @@ This transfers the specified local file to the remote URL. If there is no file part in the specified URL, curl appends the local file name to the end of the URL before the operation starts. You must use a trailing slash (/) on the last directory to prove to curl that there is no -file name or curl thinks that your last directory name is the remote file name +filename or curl thinks that your last directory name is the remote filename to use. -When putting the local file name at the end of the URL, curl ignores what is -on the left side of any slash (/) or backslash (\) used in the file name and -only appends what is on the right side of the rightmost such character. +When putting the local filename at the end of the URL, curl ignores what is on +the left side of any slash (/) or backslash (\) used in the filename and only +appends what is on the right side of the rightmost such character. -Use the file name `-` (a single dash) to use stdin instead of a given file. -Alternately, the file name `.` (a single period) may be specified instead of +Use the filename `-` (a single dash) to use stdin instead of a given file. +Alternately, the filename `.` (a single period) may be specified instead of `-` to use stdin in non-blocking mode to allow reading server output while stdin is being uploaded. -If this option is used with a HTTP(S) URL, the PUT method is used. +If this option is used with an HTTP(S) URL, the PUT method is used. You can specify one --upload-file for each URL on the command line. Each --upload-file + URL pair specifies what to upload and to where. curl also diff --git a/docs/cmdline-opts/user.md b/docs/cmdline-opts/user.md index ee4610c0add..3a4f0445f50 100644 --- a/docs/cmdline-opts/user.md +++ b/docs/cmdline-opts/user.md @@ -17,13 +17,13 @@ Example: # `--user` -Specify the user name and password to use for server authentication. Overrides +Specify the username and password to use for server authentication. Overrides --netrc and --netrc-optional. -If you simply specify the user name, curl prompts for a password. +If you simply specify the username, curl prompts for a password. -The user name and passwords are split up on the first colon, which makes it -impossible to use a colon in the user name with this option. The password can, +The username and passwords are split up on the first colon, which makes it +impossible to use a colon in the username with this option. The password can, still. On systems where it works, curl hides the given option argument from process @@ -33,19 +33,18 @@ before cleared. Such sensitive data should be retrieved from a file instead or similar and never used in clear text in a command line. When using Kerberos V5 with a Windows based server you should include the -Windows domain name in the user name, in order for the server to successfully +Windows domain name in the username, in order for the server to successfully obtain a Kerberos Ticket. If you do not, then the initial authentication handshake may fail. -When using NTLM, the user name can be specified simply as the user name, -without the domain, if there is a single domain and forest in your setup -for example. +When using NTLM, the username can be specified simply as the username, without +the domain, if there is a single domain and forest in your setup for example. To specify the domain name use either Down-Level Logon Name or UPN (User Principal Name) formats. For example, EXAMPLE\user and user@example.com respectively. If you use a Windows SSPI-enabled curl binary and perform Kerberos V5, -Negotiate, NTLM or Digest 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 :". +Negotiate, NTLM or Digest authentication then you can tell curl to select the +username and password from your environment by specifying a single colon with +this option: "-u :". diff --git a/docs/cmdline-opts/verbose.md b/docs/cmdline-opts/verbose.md index ebc039fc1af..53096c5462f 100644 --- a/docs/cmdline-opts/verbose.md +++ b/docs/cmdline-opts/verbose.md @@ -32,5 +32,5 @@ If you think this option still does not give you enough details, consider using --trace or --trace-ascii instead. Note that verbose output of curl activities and network traffic might contain -sensitive data, including user names, credentials or secret data content. Be +sensitive data, including usernames, credentials or secret data content. Be aware and be careful when sharing trace logs with others. diff --git a/docs/cmdline-opts/write-out.md b/docs/cmdline-opts/write-out.md index 068af7675a9..6a75efeaee7 100644 --- a/docs/cmdline-opts/write-out.md +++ b/docs/cmdline-opts/write-out.md @@ -38,10 +38,10 @@ colon). The header contents are exactly as sent over the network, with leading and trailing whitespace trimmed (added in 7.84.0). Select a specific target destination file to write the output to, by using -*%output{name}* (added in curl 8.3.0) where *name* is the full file name. The +*%output{name}* (added in curl 8.3.0) where *name* is the full filename. The output following that instruction is then written to that file. More than one *%output{}* instruction can be specified in the same write-out argument. If -the file name cannot be created, curl leaves the output destination to the one +the filename cannot be created, curl leaves the output destination to the one used prior to the *%output{}* instruction. Use *%output{\>\>name}* to append data to an existing file. @@ -49,7 +49,7 @@ This output is done independently of if the file transfer was successful or not. If the specified action or output specified with this option fails in any way, -it will not make curl return a (different) error. +it does not make curl return a (different) error. **NOTE:** On Windows, the %-symbol is a special symbol used to expand environment variables. In batch files, all occurrences of % must be doubled @@ -74,9 +74,9 @@ The numerical exit code of the transfer. (Added in 7.75.0) ## `filename_effective` The ultimate filename that curl writes out to. This is only meaningful if curl -is told to write to a file with the --remote-name or --output -option. It's most useful in combination with the --remote-header-name -option. (Added in 7.26.0) +is told to write to a file with the --remote-name or --output option. It is +most useful in combination with the --remote-header-name option. (Added in +7.26.0) ## `ftp_entry_path` The initial path curl ended up in when logging on to the remote FTP diff --git a/src/tool_listhelp.c b/src/tool_listhelp.c index 23472f345a5..f2feb27185c 100644 --- a/src/tool_listhelp.c +++ b/src/tool_listhelp.c @@ -36,7 +36,7 @@ const struct helptxt helptext[] = { {" --abstract-unix-socket ", "Connect via abstract Unix domain socket", CURLHELP_CONNECTION}, - {" --alt-svc ", + {" --alt-svc ", "Enable alt-svc with this cache file", CURLHELP_HTTP}, {" --anyauth", @@ -163,7 +163,7 @@ const struct helptxt helptext[] = { "Allow insecure DoH server connections", CURLHELP_DNS | CURLHELP_TLS}, {" --doh-url ", - "Resolve host names over DoH", + "Resolve hostnames over DoH", CURLHELP_DNS}, {"-D, --dump-header ", "Write the received headers to ", @@ -199,7 +199,7 @@ const struct helptxt helptext[] = { "Specify multipart MIME data", CURLHELP_HTTP | CURLHELP_UPLOAD}, {" --form-escape", - "Escape multipart form field/file names using backslash", + "Escape multipart form field/filenames using backslash", CURLHELP_HTTP | CURLHELP_UPLOAD}, {" --form-string ", "Specify multipart MIME data", @@ -267,7 +267,7 @@ const struct helptxt helptext[] = { {" --hostpubsha256 ", "Acceptable SHA256 hash of the host public key", CURLHELP_SFTP | CURLHELP_SCP}, - {" --hsts ", + {" --hsts ", "Enable HSTS with this cache file", CURLHELP_HTTP}, {" --http0.9", @@ -322,7 +322,7 @@ const struct helptxt helptext[] = { "Interval time for keepalive probes", CURLHELP_CONNECTION}, {" --key ", - "Private key file name", + "Private key filename", CURLHELP_TLS | CURLHELP_SSH}, {" --key-type ", "Private key file type (DER/PEM/ENG)", @@ -382,7 +382,7 @@ const struct helptxt helptext[] = { "Use HTTP Negotiate (SPNEGO) authentication", CURLHELP_AUTH | CURLHELP_HTTP}, {"-n, --netrc", - "Must read .netrc for user name and password", + "Must read .netrc for username and password", CURLHELP_CURL}, {" --netrc-file ", "Specify FILE for netrc", @@ -568,7 +568,7 @@ const struct helptxt helptext[] = { "Operate through an HTTP proxy tunnel (using CONNECT)", CURLHELP_PROXY}, {" --pubkey ", - "SSH Public key file name", + "SSH Public key filename", CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_AUTH}, {"-Q, --quote ", "Send command(s) to server before transfer", @@ -595,7 +595,7 @@ const struct helptxt helptext[] = { "Write output to a file named as the remote file", CURLHELP_IMPORTANT | CURLHELP_OUTPUT}, {" --remote-name-all", - "Use the remote file name for all URLs", + "Use the remote filename for all URLs", CURLHELP_OUTPUT}, {"-R, --remote-time", "Set the remote file's time on the local output", @@ -664,7 +664,7 @@ const struct helptxt helptext[] = { "SOCKS5 proxy service name for GSS-API", CURLHELP_PROXY | CURLHELP_AUTH}, {" --socks5-hostname ", - "SOCKS5 proxy, pass host name to proxy", + "SOCKS5 proxy, pass hostname to proxy", CURLHELP_PROXY}, {"-Y, --speed-limit ", "Stop transfers slower than this", @@ -736,7 +736,7 @@ const struct helptxt helptext[] = { "TLS password", CURLHELP_TLS | CURLHELP_AUTH}, {" --tlsuser ", - "TLS user name", + "TLS username", CURLHELP_TLS | CURLHELP_AUTH}, {"-1, --tlsv1", "Use TLSv1.0 or greater", From f540e43b9db8a507e1afa83a66b059aff7c965f2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 12:29:27 +0100 Subject: [PATCH 383/509] examples: use present tense in comments remove "will" and some other word fixes Closes #13003 --- docs/examples/address-scope.c | 2 +- docs/examples/altsvc.c | 2 +- docs/examples/anyauthput.c | 2 +- docs/examples/cacertinmem.c | 21 ++++++++++----------- docs/examples/connect-to.c | 12 ++++++------ docs/examples/cookie_interface.c | 7 +++---- docs/examples/default-scheme.c | 2 +- docs/examples/ephiperfifo.c | 14 +++++++------- docs/examples/evhiperfifo.c | 4 ++-- docs/examples/externalsocket.c | 4 ++-- docs/examples/ftp-wildcard.c | 2 +- docs/examples/ftpgetresp.c | 4 ++-- docs/examples/ftpupload.c | 10 +++++----- docs/examples/ftpuploadfrommem.c | 4 ++-- docs/examples/ftpuploadresume.c | 10 ++++------ docs/examples/getinmemory.c | 2 +- docs/examples/getredirect.c | 2 +- docs/examples/getreferrer.c | 2 +- docs/examples/ghiper.c | 4 ++-- docs/examples/headerapi.c | 2 +- docs/examples/hiperfifo.c | 9 +++++---- docs/examples/hsts-preload.c | 2 +- docs/examples/http-options.c | 4 ++-- docs/examples/http-post.c | 4 ++-- docs/examples/http2-download.c | 6 +++--- docs/examples/http2-upload.c | 6 +++--- docs/examples/http3.c | 2 +- docs/examples/httpput-postfields.c | 2 +- docs/examples/httpput.c | 2 +- docs/examples/https.c | 6 +++--- docs/examples/imap-append.c | 2 +- docs/examples/imap-authzid.c | 2 +- docs/examples/imap-copy.c | 2 +- docs/examples/imap-fetch.c | 2 +- docs/examples/imap-list.c | 4 ++-- docs/examples/imap-multi.c | 2 +- docs/examples/imap-ssl.c | 8 ++++---- docs/examples/imap-tls.c | 12 ++++++------ docs/examples/localport.c | 4 ++-- docs/examples/maxconnects.c | 2 +- docs/examples/multi-app.c | 2 +- docs/examples/multi-debugcallback.c | 2 +- docs/examples/multi-event.c | 5 ++--- docs/examples/multi-legacy.c | 2 +- docs/examples/multi-single.c | 2 +- docs/examples/multi-uv.c | 5 ++--- docs/examples/parseurl.c | 4 ++-- docs/examples/persistent.c | 4 ++-- docs/examples/pop3-authzid.c | 2 +- docs/examples/pop3-list.c | 2 +- docs/examples/pop3-multi.c | 2 +- docs/examples/pop3-retr.c | 2 +- docs/examples/pop3-ssl.c | 8 ++++---- docs/examples/pop3-tls.c | 12 ++++++------ docs/examples/post-callback.c | 4 ++-- docs/examples/postinmemory.c | 7 +++---- docs/examples/postit2-formadd.c | 8 ++++---- docs/examples/postit2.c | 8 ++++---- docs/examples/range.c | 2 +- docs/examples/resolve.c | 8 ++++---- docs/examples/rtsp-options.c | 2 +- docs/examples/sendrecv.c | 3 +-- docs/examples/sftpget.c | 8 ++++---- docs/examples/shared-connection-cache.c | 6 +++--- docs/examples/simple.c | 2 +- docs/examples/simplepost.c | 5 ++--- docs/examples/simplessl.c | 4 ++-- docs/examples/smooth-gtk-thread.c | 4 ++-- docs/examples/smtp-authzid.c | 6 +++--- docs/examples/smtp-expn.c | 2 +- docs/examples/smtp-mail.c | 6 +++--- docs/examples/smtp-mime.c | 6 +++--- docs/examples/smtp-multi.c | 2 +- docs/examples/smtp-ssl.c | 10 +++++----- docs/examples/smtp-tls.c | 14 +++++++------- docs/examples/smtp-vrfy.c | 2 +- docs/examples/synctime.c | 8 ++++---- docs/examples/unixsocket.c | 2 +- docs/examples/usercertinmem.c | 5 ++--- docs/examples/websocket-cb.c | 2 +- docs/examples/websocket.c | 2 +- 81 files changed, 189 insertions(+), 198 deletions(-) diff --git a/docs/examples/address-scope.c b/docs/examples/address-scope.c index dc305a072ec..5650fdb230a 100644 --- a/docs/examples/address-scope.c +++ b/docs/examples/address-scope.c @@ -47,7 +47,7 @@ int main(void) my_scope_id = if_nametoindex("eth0"); curl_easy_setopt(curl, CURLOPT_ADDRESS_SCOPE, my_scope_id); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/altsvc.c b/docs/examples/altsvc.c index 28e9794e85c..2f70d05e1ab 100644 --- a/docs/examples/altsvc.c +++ b/docs/examples/altsvc.c @@ -44,7 +44,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, (long) CURLALTSVC_H1|CURLALTSVC_H2|CURLALTSVC_H3); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/anyauthput.c b/docs/examples/anyauthput.c index 156e8d15245..269e29cf566 100644 --- a/docs/examples/anyauthput.c +++ b/docs/examples/anyauthput.c @@ -100,7 +100,7 @@ int main(int argc, char **argv) fp = fopen(file, "rb"); fstat(FILENO(fp), &file_info); - /* In windows, this will init the winsock stuff */ + /* In windows, this inits the winsock stuff */ curl_global_init(CURL_GLOBAL_ALL); /* get a curl handle */ diff --git a/docs/examples/cacertinmem.c b/docs/examples/cacertinmem.c index 647b495b4c5..ff748db4b4c 100644 --- a/docs/examples/cacertinmem.c +++ b/docs/examples/cacertinmem.c @@ -139,7 +139,7 @@ int main(void) curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L); curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); - /* Turn off the default CA locations, otherwise libcurl will load CA + /* Turn off the default CA locations, otherwise libcurl loads CA * certificates from the locations that were detected/specified at * build-time */ @@ -155,19 +155,18 @@ int main(void) else printf("*** transfer failed ***\n"); - /* use a fresh connection (optional) - * this option seriously impacts performance of multiple transfers but - * it is necessary order to demonstrate this example. recall that the - * ssl ctx callback is only called _before_ an SSL connection is - * established, therefore it will not affect existing verified SSL - * connections already in the connection cache associated with this - * handle. normally you would set the ssl ctx function before making - * any transfers, and not use this option. + /* use a fresh connection (optional) this option seriously impacts + * performance of multiple transfers but it is necessary order to + * demonstrate this example. recall that the ssl ctx callback is only called + * _before_ an SSL connection is established, therefore it does not affect + * existing verified SSL connections already in the connection cache + * associated with this handle. normally you would set the ssl ctx function + * before making any transfers, and not use this option. */ curl_easy_setopt(ch, CURLOPT_FRESH_CONNECT, 1L); - /* second try: retrieve page using cacerts' certificate -> will succeed - * load the certificate by installing a function doing the necessary + /* second try: retrieve page using cacerts' certificate -> succeeds to load + * the certificate by installing a function doing the necessary * "modifications" to the SSL CONTEXT just before link init */ curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, sslctx_function); diff --git a/docs/examples/connect-to.c b/docs/examples/connect-to.c index fcdd2cc4ff7..ad1e3046496 100644 --- a/docs/examples/connect-to.c +++ b/docs/examples/connect-to.c @@ -22,7 +22,7 @@ * ***************************************************************************/ /* - * Use CURLOPT_CONNECT_TO to connect to "wrong" host name + * Use CURLOPT_CONNECT_TO to connect to "wrong" hostname * */ #include @@ -39,8 +39,8 @@ int main(void) request, PORT is the port of the request, CONNECT-TO-HOST is the host name to connect to, and CONNECT-TO-PORT is the port to connect to. */ - /* instead of curl.se:443, it will resolve and use example.com:443 but in - other aspects work as if it still is curl.se */ + /* instead of curl.se:443, it resolves and uses example.com:443 but in other + aspects work as if it still is curl.se */ struct curl_slist *host = curl_slist_append(NULL, "curl.se:443:example.com:443"); @@ -51,13 +51,13 @@ int main(void) curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/"); /* since this connects to the wrong host, checking the host name in the - server certificate will fail, so unless we disable the check libcurl + server certificate fails, so unless we disable the check libcurl returns CURLE_PEER_FAILED_VERIFICATION */ curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); /* Letting the wrong host name in the certificate be okay, the transfer - goes through but will (most likely) cause a 404 or similar because it - sends an unknown name in the Host: header field */ + goes through but (most likely) causes a 404 or similar because it sends + an unknown name in the Host: header field */ res = curl_easy_perform(curl); /* always cleanup */ diff --git a/docs/examples/cookie_interface.c b/docs/examples/cookie_interface.c index 12004983067..0cc47cff7fa 100644 --- a/docs/examples/cookie_interface.c +++ b/docs/examples/cookie_interface.c @@ -107,10 +107,9 @@ main(void) } /* HTTP-header style cookie. If you use the Set-Cookie format and do not - specify a domain then the cookie is sent for any domain and will not be - modified, likely not what you intended. Starting in 7.43.0 any-domain - cookies will not be exported either. For more information refer to the - CURLOPT_COOKIELIST documentation. + specify a domain then the cookie is sent for any domain and is not + modified, likely not what you intended. For more information refer to + the CURLOPT_COOKIELIST documentation. */ snprintf(nline, sizeof(nline), "Set-Cookie: OLD_PREF=3d141414bf4209321; " diff --git a/docs/examples/default-scheme.c b/docs/examples/default-scheme.c index 525dcc3c32a..13e1e08fcb3 100644 --- a/docs/examples/default-scheme.c +++ b/docs/examples/default-scheme.c @@ -43,7 +43,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/ephiperfifo.c b/docs/examples/ephiperfifo.c index 0ce68de5dd5..0c8a2692486 100644 --- a/docs/examples/ephiperfifo.c +++ b/docs/examples/ephiperfifo.c @@ -138,8 +138,8 @@ static void mcode_or_die(const char *where, CURLMcode code) static void timer_cb(GlobalInfo* g, int revents); -/* Update the timer after curl_multi library does it's thing. Curl will - * inform us through this callback what it wants the new timeout to be, +/* Update the timer after curl_multi library does its thing. Curl informs the + * application through this callback what it wants the new timeout to be, * after it does some work. */ static int multi_timer_cb(CURLM *multi, long timeout_ms, GlobalInfo *g) { @@ -228,9 +228,9 @@ static void timer_cb(GlobalInfo* g, int revents) if(err == -1) { /* Note that we may call the timer callback even if the timerfd is not * readable. It's possible that there are multiple events stored in the - * epoll buffer (i.e. the timer may have fired multiple times). The - * event count is cleared after the first call so future events in the - * epoll buffer will fail to read from the timer. */ + * epoll buffer (i.e. the timer may have fired multiple times). The event + * count is cleared after the first call so future events in the epoll + * buffer fails to read from the timer. */ if(errno == EAGAIN) { fprintf(MSG_OUT, "EAGAIN on tfd %d\n", g->tfd); return; @@ -386,8 +386,8 @@ static void new_conn(char *url, GlobalInfo *g) rc = curl_multi_add_handle(g->multi, conn->easy); mcode_or_die("new_conn: curl_multi_add_handle", rc); - /* note that the add_handle() will set a time-out to trigger soon so that - the necessary socket_action() call will be called by this app */ + /* note that the add_handle() sets a timeout to trigger soon so that the + * necessary socket_action() call gets called by this app */ } /* This gets called whenever data is received from the fifo */ diff --git a/docs/examples/evhiperfifo.c b/docs/examples/evhiperfifo.c index 17bff2b65ad..8997dff11de 100644 --- a/docs/examples/evhiperfifo.c +++ b/docs/examples/evhiperfifo.c @@ -364,8 +364,8 @@ static void new_conn(char *url, GlobalInfo *g) rc = curl_multi_add_handle(g->multi, conn->easy); mcode_or_die("new_conn: curl_multi_add_handle", rc); - /* note that the add_handle() will set a time-out to trigger soon so that - the necessary socket_action() call will be called by this app */ + /* note that add_handle() sets a timeout to trigger soon so that the + necessary socket_action() gets called */ } /* This gets called whenever data is received from the fifo */ diff --git a/docs/examples/externalsocket.c b/docs/examples/externalsocket.c index 9c343734436..21e9a9c477d 100644 --- a/docs/examples/externalsocket.c +++ b/docs/examples/externalsocket.c @@ -106,8 +106,8 @@ int main(void) curl = curl_easy_init(); if(curl) { /* - * Note that libcurl will internally think that you connect to the host - * and port that you specify in the URL option. + * Note that libcurl internally thinks that you connect to the host and + * port that you specify in the URL option. */ curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); diff --git a/docs/examples/ftp-wildcard.c b/docs/examples/ftp-wildcard.c index f8054324795..8a1b3c88f2f 100644 --- a/docs/examples/ftp-wildcard.c +++ b/docs/examples/ftp-wildcard.c @@ -70,7 +70,7 @@ int main(int argc, char **argv) /* callback is called after data from the file have been transferred */ curl_easy_setopt(handle, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded); - /* this callback will write contents into files */ + /* this callback writes contents into files */ curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_it); /* put transfer data into callbacks */ diff --git a/docs/examples/ftpgetresp.c b/docs/examples/ftpgetresp.c index 238885dfec8..33c26b380eb 100644 --- a/docs/examples/ftpgetresp.c +++ b/docs/examples/ftpgetresp.c @@ -47,10 +47,10 @@ int main(void) FILE *ftpfile; FILE *respfile; - /* local file name to store the file as */ + /* local filename to store the file as */ ftpfile = fopen(FTPBODY, "wb"); /* b is binary, needed on win32 */ - /* local file name to store the FTP server's response lines in */ + /* local filename to store the FTP server's response lines in */ respfile = fopen(FTPHEADERS, "wb"); /* b is binary, needed on win32 */ curl = curl_easy_init(); diff --git a/docs/examples/ftpupload.c b/docs/examples/ftpupload.c index 92bb0b8a0ba..d43f0902699 100644 --- a/docs/examples/ftpupload.c +++ b/docs/examples/ftpupload.c @@ -46,10 +46,10 @@ #define REMOTE_URL "ftp://example.com/" UPLOAD_FILE_AS #define RENAME_FILE_TO "renamed-and-fine.txt" -/* NOTE: if you want this example to work on Windows with libcurl as a - DLL, you MUST also provide a read callback with CURLOPT_READFUNCTION. - Failing to do so will give you a crash since a DLL may not use the - variable's memory when passed in to it from an app like this. */ +/* NOTE: if you want this example to work on Windows with libcurl as a DLL, + you MUST also provide a read callback with CURLOPT_READFUNCTION. Failing to + do so might give you a crash since a DLL may not use the variable's memory + when passed in to it from an app like this. */ static size_t read_callback(char *ptr, size_t size, size_t nmemb, void *stream) { unsigned long nread; @@ -90,7 +90,7 @@ int main(void) /* get a FILE * of the same file */ hd_src = fopen(LOCAL_FILE, "rb"); - /* In windows, this will init the winsock stuff */ + /* In windows, this inits the winsock stuff */ curl_global_init(CURL_GLOBAL_ALL); /* get a curl handle */ diff --git a/docs/examples/ftpuploadfrommem.c b/docs/examples/ftpuploadfrommem.c index 9613cca262f..699468d1ccf 100644 --- a/docs/examples/ftpuploadfrommem.c +++ b/docs/examples/ftpuploadfrommem.c @@ -76,7 +76,7 @@ int main(void) upload.readptr = data; upload.sizeleft = strlen(data); - /* In windows, this will init the winsock stuff */ + /* In windows, this inits the winsock stuff */ res = curl_global_init(CURL_GLOBAL_DEFAULT); /* Check for errors */ if(res != CURLE_OK) { @@ -111,7 +111,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)upload.sizeleft); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/ftpuploadresume.c b/docs/examples/ftpuploadresume.c index 42d31a2bbfb..d4063925dd4 100644 --- a/docs/examples/ftpuploadresume.c +++ b/docs/examples/ftpuploadresume.c @@ -112,12 +112,10 @@ static int upload(CURL *curlhandle, const char *remotepath, /* determine the length of the file already written */ /* - * With NOBODY and NOHEADER, libcurl will issue a SIZE - * command, but the only way to retrieve the result is - * to parse the returned Content-Length header. Thus, - * getcontentlengthfunc(). We need discardfunc() above - * because HEADER will dump the headers to stdout - * without it. + * With NOBODY and NOHEADER, libcurl issues a SIZE command, but the only + * way to retrieve the result is to parse the returned Content-Length + * header. Thus, getcontentlengthfunc(). We need discardfunc() above + * because HEADER dumps the headers to stdout without it. */ curl_easy_setopt(curlhandle, CURLOPT_NOBODY, 1L); curl_easy_setopt(curlhandle, CURLOPT_HEADER, 1L); diff --git a/docs/examples/getinmemory.c b/docs/examples/getinmemory.c index 8ec84142dbf..173247d9152 100644 --- a/docs/examples/getinmemory.c +++ b/docs/examples/getinmemory.c @@ -66,7 +66,7 @@ int main(void) struct MemoryStruct chunk; - chunk.memory = malloc(1); /* will be grown as needed by the realloc above */ + chunk.memory = malloc(1); /* grown as needed by the realloc above */ chunk.size = 0; /* no data at this point */ curl_global_init(CURL_GLOBAL_ALL); diff --git a/docs/examples/getredirect.c b/docs/examples/getredirect.c index 9163c9b079a..91c778d3c1b 100644 --- a/docs/examples/getredirect.c +++ b/docs/examples/getredirect.c @@ -41,7 +41,7 @@ int main(void) /* example.com is redirected, figure out the redirection! */ - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/getreferrer.c b/docs/examples/getreferrer.c index 6073f9fca46..c46f7825a0a 100644 --- a/docs/examples/getreferrer.c +++ b/docs/examples/getreferrer.c @@ -39,7 +39,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/referrer"); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/ghiper.c b/docs/examples/ghiper.c index 5a4f4a7057a..4510edae506 100644 --- a/docs/examples/ghiper.c +++ b/docs/examples/ghiper.c @@ -323,8 +323,8 @@ static void new_conn(char *url, GlobalInfo *g) rc = curl_multi_add_handle(g->multi, conn->easy); mcode_or_die("new_conn: curl_multi_add_handle", rc); - /* note that the add_handle() will set a time-out to trigger soon so that - the necessary socket_action() call will be called by this app */ + /* note that add_handle() sets a timeout to trigger soon so that the + necessary socket_action() gets called */ } /* This gets called by glib whenever data is received from the fifo */ diff --git a/docs/examples/headerapi.c b/docs/examples/headerapi.c index 4df6cbd6722..95c366884a4 100644 --- a/docs/examples/headerapi.c +++ b/docs/examples/headerapi.c @@ -51,7 +51,7 @@ int main(void) /* this example just ignores the content */ curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_cb); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/hiperfifo.c b/docs/examples/hiperfifo.c index 9fba341bb6d..bde30594f8d 100644 --- a/docs/examples/hiperfifo.c +++ b/docs/examples/hiperfifo.c @@ -358,8 +358,8 @@ static void new_conn(char *url, GlobalInfo *g) rc = curl_multi_add_handle(g->multi, conn->easy); mcode_or_die("new_conn: curl_multi_add_handle", rc); - /* note that the add_handle() will set a time-out to trigger soon so that - the necessary socket_action() call will be called by this app */ + /* note that the add_handle() sets a time-out to trigger soon so that + the necessary socket_action() gets called */ } /* This gets called whenever data is received from the fifo */ @@ -454,8 +454,9 @@ int main(int argc, char **argv) event_base_dispatch(g.evbase); - /* this, of course, will not get called since only way to stop this program - is via ctrl-C, but it is here to show how cleanup /would/ be done. */ + /* this, of course, does not get called since the only way to stop this + program is via ctrl-C, but it is here to show how cleanup /would/ be + done. */ clean_fifo(&g); event_del(&g.timer_event); event_base_free(g.evbase); diff --git a/docs/examples/hsts-preload.c b/docs/examples/hsts-preload.c index ee4253533e6..a25773f42dd 100644 --- a/docs/examples/hsts-preload.c +++ b/docs/examples/hsts-preload.c @@ -104,7 +104,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/http-options.c b/docs/examples/http-options.c index 964e0ef374f..586b55f12a5 100644 --- a/docs/examples/http-options.c +++ b/docs/examples/http-options.c @@ -42,10 +42,10 @@ int main(void) curl_easy_setopt(curl, CURLOPT_REQUEST_TARGET, "*"); /* if this operation fails, allow risking a memory leak and do quick exit - from libcurl as this will exit() anyway */ + from libcurl as this exits anyway */ curl_easy_setopt(curl, CURLOPT_QUICK_EXIT, 1L); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/http-post.c b/docs/examples/http-post.c index 2cacefee473..1ee9f69c0fd 100644 --- a/docs/examples/http-post.c +++ b/docs/examples/http-post.c @@ -33,7 +33,7 @@ int main(void) CURL *curl; CURLcode res; - /* In windows, this will init the winsock stuff */ + /* In windows, this inits the winsock stuff */ curl_global_init(CURL_GLOBAL_ALL); /* get a curl handle */ @@ -46,7 +46,7 @@ int main(void) /* Now specify the POST data */ curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "name=daniel&project=curl"); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/http2-download.c b/docs/examples/http2-download.c index 5da7ed6035a..c45a1c2d651 100644 --- a/docs/examples/http2-download.c +++ b/docs/examples/http2-download.c @@ -39,9 +39,9 @@ #include #ifndef CURLPIPE_MULTIPLEX -/* This little trick will just make sure that we do not enable pipelining for - libcurls old enough to not have this symbol. It is _not_ defined to zero in - a recent libcurl header. */ +/* This little trick makes sure that we do not enable pipelining for libcurls + old enough to not have this symbol. It is _not_ defined to zero in a recent + libcurl header. */ #define CURLPIPE_MULTIPLEX 0 #endif diff --git a/docs/examples/http2-upload.c b/docs/examples/http2-upload.c index dd63b8cd50f..56d0c982504 100644 --- a/docs/examples/http2-upload.c +++ b/docs/examples/http2-upload.c @@ -41,9 +41,9 @@ #include #ifndef CURLPIPE_MULTIPLEX -/* This little trick will just make sure that we do not enable pipelining for - libcurls old enough to not have this symbol. It is _not_ defined to zero in - a recent libcurl header. */ +/* This little trick makes sure that we do not enable pipelining for libcurls + old enough to not have this symbol. It is _not_ defined to zero in a recent + libcurl header. */ #define CURLPIPE_MULTIPLEX 0 #endif diff --git a/docs/examples/http3.c b/docs/examples/http3.c index 900e1192085..e278f2e313e 100644 --- a/docs/examples/http3.c +++ b/docs/examples/http3.c @@ -41,7 +41,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_HTTP_VERSION, (long)CURL_HTTP_VERSION_3); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/httpput-postfields.c b/docs/examples/httpput-postfields.c index 98d7c3d7423..e8a8de7a257 100644 --- a/docs/examples/httpput-postfields.c +++ b/docs/examples/httpput-postfields.c @@ -58,7 +58,7 @@ int main(int argc, char **argv) url = argv[1]; - /* In windows, this will init the winsock stuff */ + /* In windows, this inits the winsock stuff */ curl_global_init(CURL_GLOBAL_ALL); /* get a curl handle */ diff --git a/docs/examples/httpput.c b/docs/examples/httpput.c index b9a6c87b748..d26aa9e2506 100644 --- a/docs/examples/httpput.c +++ b/docs/examples/httpput.c @@ -82,7 +82,7 @@ int main(int argc, char **argv) an example! */ hd_src = fopen(file, "rb"); - /* In windows, this will init the winsock stuff */ + /* In windows, this inits the winsock stuff */ curl_global_init(CURL_GLOBAL_ALL); /* get a curl handle */ diff --git a/docs/examples/https.c b/docs/examples/https.c index 2a34e37d83e..c1cba877df6 100644 --- a/docs/examples/https.c +++ b/docs/examples/https.c @@ -57,8 +57,8 @@ int main(void) /* * If the site you are connecting to uses a different host name that what * they have mentioned in their server certificate's commonName (or - * subjectAltName) fields, libcurl will refuse to connect. You can skip - * this check, but this will make the connection less secure. + * subjectAltName) fields, libcurl refuses to connect. You can skip this + * check, but it makes the connection insecure. */ curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); #endif @@ -66,7 +66,7 @@ int main(void) /* cache the CA cert bundle in memory for a week */ curl_easy_setopt(curl, CURLOPT_CA_CACHE_TIMEOUT, 604800L); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/imap-append.c b/docs/examples/imap-append.c index 33566bb6430..1839deac1dd 100644 --- a/docs/examples/imap-append.c +++ b/docs/examples/imap-append.c @@ -99,7 +99,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will create a new message in folder "Sent". */ + /* This creates a new message in folder "Sent". */ curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/Sent"); /* In this case, we are using a callback function to specify the data. You diff --git a/docs/examples/imap-authzid.c b/docs/examples/imap-authzid.c index af073206452..eb615c6f3d5 100644 --- a/docs/examples/imap-authzid.c +++ b/docs/examples/imap-authzid.c @@ -53,7 +53,7 @@ int main(void) /* Force PLAIN authentication */ curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=PLAIN"); - /* This will fetch message 1 from the user's inbox */ + /* This fetches message 1 from the user's inbox */ curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX/;UID=1"); diff --git a/docs/examples/imap-copy.c b/docs/examples/imap-copy.c index 0920f09443b..a221be0ca8d 100644 --- a/docs/examples/imap-copy.c +++ b/docs/examples/imap-copy.c @@ -53,7 +53,7 @@ int main(void) /* Set the COPY command specifying the message ID and destination folder */ curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "COPY 1 FOLDER"); - /* Note that to perform a move operation you will need to perform the copy, + /* Note that to perform a move operation you need to perform the copy, * then mark the original mail as Deleted and EXPUNGE or CLOSE. Please see * imap-store.c for more information on deleting messages. */ diff --git a/docs/examples/imap-fetch.c b/docs/examples/imap-fetch.c index 3361d7cfe58..416fe880968 100644 --- a/docs/examples/imap-fetch.c +++ b/docs/examples/imap-fetch.c @@ -47,7 +47,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will fetch message 1 from the user's inbox */ + /* This fetches message 1 from the user's inbox */ curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX/;UID=1"); diff --git a/docs/examples/imap-list.c b/docs/examples/imap-list.c index 2f3780f2d0d..0253b543e6f 100644 --- a/docs/examples/imap-list.c +++ b/docs/examples/imap-list.c @@ -47,8 +47,8 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will list the folders within the user's mailbox. If you want to - * list the folders within a specific folder, for example the inbox, then + /* This lists the folders within the user's mailbox. If you want to list + * the folders within a specific folder, for example the inbox, then * specify the folder as a path in the URL such as /INBOX */ curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com"); diff --git a/docs/examples/imap-multi.c b/docs/examples/imap-multi.c index 6a5f4b070f6..42fa7381cd2 100644 --- a/docs/examples/imap-multi.c +++ b/docs/examples/imap-multi.c @@ -56,7 +56,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will fetch message 1 from the user's inbox */ + /* This fetches message 1 from the user's inbox */ curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX/;UID=1"); /* Tell the multi stack about our easy handle */ diff --git a/docs/examples/imap-ssl.c b/docs/examples/imap-ssl.c index e920720c013..a2774bea4ab 100644 --- a/docs/examples/imap-ssl.c +++ b/docs/examples/imap-ssl.c @@ -48,7 +48,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will fetch message 1 from the user's inbox. Note the use of + /* This fetches message 1 from the user's inbox. Note the use of * imaps:// rather than imap:// to request a SSL based connection. */ curl_easy_setopt(curl, CURLOPT_URL, "imaps://imap.example.com/INBOX/;UID=1"); @@ -67,13 +67,13 @@ int main(void) /* If the site you are connecting to uses a different host name that what * they have mentioned in their server certificate's commonName (or - * subjectAltName) fields, libcurl will refuse to connect. You can skip - * this check, but this will make the connection less secure. */ + * subjectAltName) fields, libcurl refuses to connect. You can skip this + * check, but it makes the connection insecure. */ #ifdef SKIP_HOSTNAME_VERIFICATION curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); #endif - /* Since the traffic will be encrypted, it is useful to turn on debug + /* Since the traffic is encrypted, it is useful to turn on debug * information within libcurl to see what is happening during the * transfer */ curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); diff --git a/docs/examples/imap-tls.c b/docs/examples/imap-tls.c index d98f5ef9f95..838923b334c 100644 --- a/docs/examples/imap-tls.c +++ b/docs/examples/imap-tls.c @@ -48,14 +48,14 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will fetch message 1 from the user's inbox */ + /* This fetches message 1 from the user's inbox */ curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX/;UID=1"); - /* In this example, we will start with a plain text connection, and upgrade - * to Transport Layer Security (TLS) using the STARTTLS command. Be careful - * of using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer - * will continue anyway - see the security discussion in the libcurl + /* In this example, we start with a plain text connection, and upgrade to + * Transport Layer Security (TLS) using the STARTTLS command. Be careful + * of using CURLUSESSL_TRY here, because if TLS upgrade fails, the + * transfer continues anyway - see the security discussion in the libcurl * tutorial for more details. */ curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); @@ -73,7 +73,7 @@ int main(void) * for more information. */ curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem"); - /* Since the traffic will be encrypted, it is useful to turn on debug + /* Since the traffic is encrypted, it is useful to turn on debug * information within libcurl to see what is happening during the * transfer */ curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); diff --git a/docs/examples/localport.c b/docs/examples/localport.c index 56e0b62cfba..7e88ce48a7c 100644 --- a/docs/examples/localport.c +++ b/docs/examples/localport.c @@ -38,8 +38,8 @@ int main(void) /* Try to use a local port number between 20000-20009 */ curl_easy_setopt(curl, CURLOPT_LOCALPORT, 20000L); /* 10 means number of attempts, which starts with the number set in - CURLOPT_LOCALPORT. The lowe value set, the smaller the change it will - work. */ + CURLOPT_LOCALPORT. The lower value set, the smaller the chance it + works. */ curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 10L); curl_easy_setopt(curl, CURLOPT_URL, "https://curl.se/"); diff --git a/docs/examples/maxconnects.c b/docs/examples/maxconnects.c index 84fefd7bc86..2e8e5b50a82 100644 --- a/docs/examples/maxconnects.c +++ b/docs/examples/maxconnects.c @@ -51,7 +51,7 @@ int main(void) while(urls[i]) { curl_easy_setopt(curl, CURLOPT_URL, urls[i]); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/multi-app.c b/docs/examples/multi-app.c index 3dbc46483e4..63918f182e7 100644 --- a/docs/examples/multi-app.c +++ b/docs/examples/multi-app.c @@ -60,7 +60,7 @@ int main(void) for(i = 0; ieasy_handle; @@ -155,8 +155,7 @@ static int start_timeout(CURLM *multi, long timeout_ms, void *userp) } else { if(timeout_ms == 0) - timeout_ms = 1; /* 0 means directly call socket_action, but we will do it - in a bit */ + timeout_ms = 1; /* 0 means call socket_action asap */ struct timeval tv; tv.tv_sec = timeout_ms / 1000; tv.tv_usec = (timeout_ms % 1000) * 1000; diff --git a/docs/examples/multi-legacy.c b/docs/examples/multi-legacy.c index f36139fe1d7..67575418e52 100644 --- a/docs/examples/multi-legacy.c +++ b/docs/examples/multi-legacy.c @@ -60,7 +60,7 @@ int main(void) for(i = 0; ieasy_handle; @@ -165,8 +165,7 @@ static int start_timeout(CURLM *multi, long timeout_ms, void *userp) } else { if(timeout_ms == 0) - timeout_ms = 1; /* 0 means directly call socket_action, but we will do it - in a bit */ + timeout_ms = 1; /* 0 means call socket_action asap */ uv_timer_start(&timeout, on_timeout, timeout_ms, 0); } return 0; diff --git a/docs/examples/parseurl.c b/docs/examples/parseurl.c index 688336f0256..8675adc6238 100644 --- a/docs/examples/parseurl.c +++ b/docs/examples/parseurl.c @@ -48,7 +48,7 @@ int main(void) if(uc) goto fail; - /* extract host name from the parsed URL */ + /* extract hostname from the parsed URL */ uc = curl_url_get(h, CURLUPART_HOST, &host, 0); if(!uc) { printf("Host name: %s\n", host); @@ -75,6 +75,6 @@ int main(void) } fail: - curl_url_cleanup(h); /* free url handle */ + curl_url_cleanup(h); /* free URL handle */ return 0; } diff --git a/docs/examples/persistent.c b/docs/examples/persistent.c index 51bd8c352c3..4be7d6f2af7 100644 --- a/docs/examples/persistent.c +++ b/docs/examples/persistent.c @@ -44,7 +44,7 @@ int main(void) /* get the first document */ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) @@ -55,7 +55,7 @@ int main(void) connection */ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/docs/"); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/pop3-authzid.c b/docs/examples/pop3-authzid.c index a948e95c63e..3281b322bb9 100644 --- a/docs/examples/pop3-authzid.c +++ b/docs/examples/pop3-authzid.c @@ -53,7 +53,7 @@ int main(void) /* Force PLAIN authentication */ curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=PLAIN"); - /* This will retrieve message 1 from the user's mailbox */ + /* This retrieves message 1 from the user's mailbox */ curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1"); /* Perform the retr */ diff --git a/docs/examples/pop3-list.c b/docs/examples/pop3-list.c index 2e8b3baee27..2cd44e41cdb 100644 --- a/docs/examples/pop3-list.c +++ b/docs/examples/pop3-list.c @@ -47,7 +47,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will list every message of the given mailbox */ + /* This lists every message of the given mailbox */ curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com"); /* Perform the list */ diff --git a/docs/examples/pop3-multi.c b/docs/examples/pop3-multi.c index b4fad19251f..54eb7ecc324 100644 --- a/docs/examples/pop3-multi.c +++ b/docs/examples/pop3-multi.c @@ -56,7 +56,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will retrieve message 1 from the user's mailbox */ + /* This retrieves message 1 from the user's mailbox */ curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1"); /* Tell the multi stack about our easy handle */ diff --git a/docs/examples/pop3-retr.c b/docs/examples/pop3-retr.c index 4940e078120..8e690f972f2 100644 --- a/docs/examples/pop3-retr.c +++ b/docs/examples/pop3-retr.c @@ -47,7 +47,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will retrieve message 1 from the user's mailbox */ + /* This retrieves message 1 from the user's mailbox */ curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1"); /* Perform the retr */ diff --git a/docs/examples/pop3-ssl.c b/docs/examples/pop3-ssl.c index e72cf6f38d1..dcc7992e418 100644 --- a/docs/examples/pop3-ssl.c +++ b/docs/examples/pop3-ssl.c @@ -48,7 +48,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will retrieve message 1 from the user's mailbox. Note the use of + /* This retrieves message 1 from the user's mailbox. Note the use of * pop3s:// rather than pop3:// to request a SSL based connection. */ curl_easy_setopt(curl, CURLOPT_URL, "pop3s://pop.example.com/1"); @@ -66,13 +66,13 @@ int main(void) /* If the site you are connecting to uses a different host name that what * they have mentioned in their server certificate's commonName (or - * subjectAltName) fields, libcurl will refuse to connect. You can skip - * this check, but this will make the connection less secure. */ + * subjectAltName) fields, libcurl refuses to connect. You can skip this + * check, but it makes the connection insecure. */ #ifdef SKIP_HOSTNAME_VERIFICATION curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); #endif - /* Since the traffic will be encrypted, it is useful to turn on debug + /* Since the traffic is encrypted, it is useful to turn on debug * information within libcurl to see what is happening during the * transfer */ curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); diff --git a/docs/examples/pop3-tls.c b/docs/examples/pop3-tls.c index 04e6e3b71fb..7c2d824d043 100644 --- a/docs/examples/pop3-tls.c +++ b/docs/examples/pop3-tls.c @@ -48,14 +48,14 @@ int main(void) curl_easy_setopt(curl, CURLOPT_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret"); - /* This will retrieve message 1 from the user's mailbox */ + /* This retrieves message 1 from the user's mailbox */ curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1"); - /* In this example, we will start with a plain text connection, and upgrade - * to Transport Layer Security (TLS) using the STLS command. Be careful of + /* In this example, we start with a plain text connection, and upgrade to + * Transport Layer Security (TLS) using the STLS command. Be careful of * using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer - * will continue anyway - see the security discussion in the libcurl - * tutorial for more details. */ + * continues anyway - see the security discussion in the libcurl tutorial + * for more details. */ curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); /* If your server does not have a valid certificate, then you can disable @@ -72,7 +72,7 @@ int main(void) * for more information. */ curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem"); - /* Since the traffic will be encrypted, it is useful to turn on debug + /* Since the traffic is encrypted, it is useful to turn on debug * information within libcurl to see what is happening during the * transfer */ curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); diff --git a/docs/examples/post-callback.c b/docs/examples/post-callback.c index a802c35825d..311bc3cae05 100644 --- a/docs/examples/post-callback.c +++ b/docs/examples/post-callback.c @@ -73,7 +73,7 @@ int main(void) wt.readptr = data; wt.sizeleft = strlen(data); - /* In windows, this will init the winsock stuff */ + /* In windows, this inits the winsock stuff */ res = curl_global_init(CURL_GLOBAL_DEFAULT); /* Check for errors */ if(res != CURLE_OK) { @@ -141,7 +141,7 @@ int main(void) } #endif - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/postinmemory.c b/docs/examples/postinmemory.c index 1610ad5a51b..cbdc77f75c7 100644 --- a/docs/examples/postinmemory.c +++ b/docs/examples/postinmemory.c @@ -63,7 +63,7 @@ int main(void) struct MemoryStruct chunk; static const char *postthis = "Field=1&Field=2&Field=3"; - chunk.memory = malloc(1); /* will be grown as needed by realloc above */ + chunk.memory = malloc(1); /* grown as needed by realloc above */ chunk.size = 0; /* no data at this point */ curl_global_init(CURL_GLOBAL_ALL); @@ -83,11 +83,10 @@ int main(void) curl_easy_setopt(curl, CURLOPT_POSTFIELDS, postthis); - /* if we do not provide POSTFIELDSIZE, libcurl will strlen() by - itself */ + /* if we do not provide POSTFIELDSIZE, libcurl calls strlen() by itself */ curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long)strlen(postthis)); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) { diff --git a/docs/examples/postit2-formadd.c b/docs/examples/postit2-formadd.c index 27761fcda39..02e50aa3d6d 100644 --- a/docs/examples/postit2-formadd.c +++ b/docs/examples/postit2-formadd.c @@ -27,17 +27,17 @@ */ /* - * Example code that uploads a file name 'foo' to a remote script that accepts + * Example code that uploads a filename 'foo' to a remote script that accepts * "HTML form based" (as described in RFC 1738) uploads using HTTP POST. * * Warning: this example uses the deprecated form api. See "postit2.c" * for a similar example using the mime api. * - * The imaginary form we will fill in looks like: + * The imaginary form we fill in looks like: * *
* Enter file: - * Enter file name: + * Enter filename: * *
*/ @@ -93,7 +93,7 @@ int main(int argc, char *argv[]) curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headerlist); curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/postit2.c b/docs/examples/postit2.c index a1fb12b0fcd..0f12cd47866 100644 --- a/docs/examples/postit2.c +++ b/docs/examples/postit2.c @@ -25,14 +25,14 @@ * HTTP Multipart formpost with file upload and two additional parts. * */ -/* Example code that uploads a file name 'foo' to a remote script that accepts +/* Example code that uploads a filename 'foo' to a remote script that accepts * "HTML form based" (as described in RFC 1738) uploads using HTTP POST. * - * The imaginary form we will fill in looks like: + * The imaginary form we fill in looks like: * *
* Enter file: - * Enter file name: + * Enter filename: * *
* @@ -85,7 +85,7 @@ int main(int argc, char *argv[]) curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headerlist); curl_easy_setopt(curl, CURLOPT_MIMEPOST, form); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/range.c b/docs/examples/range.c index 1a93f3676af..c8229fca4d4 100644 --- a/docs/examples/range.c +++ b/docs/examples/range.c @@ -22,7 +22,7 @@ * ***************************************************************************/ /* - * GET a range only of a HTTP resource + * GET a range only of an HTTP resource * */ #include diff --git a/docs/examples/resolve.c b/docs/examples/resolve.c index a16f4595451..6514e93d8d3 100644 --- a/docs/examples/resolve.c +++ b/docs/examples/resolve.c @@ -22,7 +22,7 @@ * ***************************************************************************/ /* - * Use CURLOPT_RESOLVE to feed custom IP addresses for given host name + port + * Use CURLOPT_RESOLVE to feed custom IP addresses for given hostname + port * number combinations. * */ @@ -35,9 +35,9 @@ int main(void) CURLcode res = CURLE_OK; /* Each single name resolve string should be written using the format - HOST:PORT:ADDRESS where HOST is the name libcurl will try to resolve, - PORT is the port number of the service where libcurl wants to connect to - the HOST and ADDRESS is the numerical IP address + HOST:PORT:ADDRESS where HOST is the name libcurl tries to resolve, PORT + is the port number of the service where libcurl wants to connect to the + HOST and ADDRESS is the numerical IP address */ struct curl_slist *host = curl_slist_append(NULL, "example.com:443:127.0.0.1"); diff --git a/docs/examples/rtsp-options.c b/docs/examples/rtsp-options.c index e4a623048e3..d1ddbf01ff2 100644 --- a/docs/examples/rtsp-options.c +++ b/docs/examples/rtsp-options.c @@ -41,7 +41,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_OPTIONS); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/sendrecv.c b/docs/examples/sendrecv.c index eabe0c2269b..0b7e86a3f09 100644 --- a/docs/examples/sendrecv.c +++ b/docs/examples/sendrecv.c @@ -100,8 +100,7 @@ int main(void) return 1; } - /* Extract the socket from the curl handle - we will need it for - waiting. */ + /* Extract the socket from the curl handle - we need it for waiting. */ res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); if(res != CURLE_OK) { diff --git a/docs/examples/sftpget.c b/docs/examples/sftpget.c index 992d607ef93..4d33939a40b 100644 --- a/docs/examples/sftpget.c +++ b/docs/examples/sftpget.c @@ -34,10 +34,10 @@ #undef DISABLE_SSH_AGENT /* - * This is an example showing how to get a single file from an SFTP server. - * It delays the actual destination file creation until the first write - * callback so that it will not create an empty file in case the remote file - * does not exist or something else fails. + * This is an example showing how to get a single file from an SFTP server. It + * delays the actual destination file creation until the first write callback + * so that it does not create an empty file in case the remote file does not + * exist or something else fails. */ struct FtpFile { diff --git a/docs/examples/shared-connection-cache.c b/docs/examples/shared-connection-cache.c index 26bfb1a4614..dc6805a9f19 100644 --- a/docs/examples/shared-connection-cache.c +++ b/docs/examples/shared-connection-cache.c @@ -57,8 +57,8 @@ int main(void) curl_share_setopt(share, CURLSHOPT_LOCKFUNC, my_lock); curl_share_setopt(share, CURLSHOPT_UNLOCKFUNC, my_unlock); - /* Loop the transfer and cleanup the handle properly every lap. This will - still reuse connections since the pool is in the shared object! */ + /* Loop the transfer and cleanup the handle properly every lap. This still + reuses connections since the pool is in the shared object! */ for(i = 0; i < 3; i++) { CURL *curl = curl_easy_init(); @@ -70,7 +70,7 @@ int main(void) /* use the share object */ curl_easy_setopt(curl, CURLOPT_SHARE, share); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/simple.c b/docs/examples/simple.c index 8579b0ba54c..53c8e4754f3 100644 --- a/docs/examples/simple.c +++ b/docs/examples/simple.c @@ -39,7 +39,7 @@ int main(void) /* example.com is redirected, so we tell libcurl to follow redirection */ curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/simplepost.c b/docs/examples/simplepost.c index 89435afa629..7ced982fe01 100644 --- a/docs/examples/simplepost.c +++ b/docs/examples/simplepost.c @@ -41,11 +41,10 @@ int main(void) curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, postthis); - /* if we do not provide POSTFIELDSIZE, libcurl will strlen() by - itself */ + /* if we do not provide POSTFIELDSIZE, libcurl calls strlen() by itself */ curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long)strlen(postthis)); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/simplessl.c b/docs/examples/simplessl.c index 9d933ce82c4..7145493a692 100644 --- a/docs/examples/simplessl.c +++ b/docs/examples/simplessl.c @@ -38,7 +38,7 @@ 3.2. set pEngine to the name of the crypto engine you use 3.3. set pKeyName to the key identifier you want to use 4. if you do not use a crypto engine: - 4.1. set pKeyName to the file name of your client key + 4.1. set pKeyName to the filename of your client key 4.2. if the format of the key file is DER, set pKeyType to "DER" !! verify of the server certificate is not implemented here !! @@ -124,7 +124,7 @@ int main(void) /* disconnect if we cannot validate server's cert */ curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/smooth-gtk-thread.c b/docs/examples/smooth-gtk-thread.c index 906660f9992..c53951262af 100644 --- a/docs/examples/smooth-gtk-thread.c +++ b/docs/examples/smooth-gtk-thread.c @@ -113,8 +113,8 @@ gboolean pulse_bar(gpointer data) gtk_progress_bar_pulse(GTK_PROGRESS_BAR (data)); gdk_threads_leave(); - /* Return true so the function will be called again; - * returning false removes this timeout function. + /* Return true so the function is called again; returning false removes this + * timeout function. */ return TRUE; } diff --git a/docs/examples/smtp-authzid.c b/docs/examples/smtp-authzid.c index dc24d7f4d5f..daaeab16943 100644 --- a/docs/examples/smtp-authzid.c +++ b/docs/examples/smtp-authzid.c @@ -115,8 +115,8 @@ int main(void) /* Force PLAIN authentication */ curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=PLAIN"); - /* Note that this option is not strictly required, omitting it will result - * in libcurl sending the MAIL FROM command with empty sender data. All + /* Note that this option is not strictly required, omitting it results in + * libcurl sending the MAIL FROM command with empty sender data. All * autoresponses should have an empty reverse-path, and should be directed * to the address in the reverse-path which triggered them. Otherwise, * they could cause an endless loop. See RFC 5321 Section 4.5.5 for more @@ -147,7 +147,7 @@ int main(void) /* Free the list of recipients */ curl_slist_free_all(recipients); - /* curl will not send the QUIT command until you call cleanup, so you + /* curl does not send the QUIT command until you call cleanup, so you * should be able to reuse this connection for additional messages * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and * calling curl_easy_perform() again. It may not be a good idea to keep diff --git a/docs/examples/smtp-expn.c b/docs/examples/smtp-expn.c index e61b6b4eeea..202d1d089fa 100644 --- a/docs/examples/smtp-expn.c +++ b/docs/examples/smtp-expn.c @@ -68,7 +68,7 @@ int main(void) /* Free the list of recipients */ curl_slist_free_all(recipients); - /* curl will not send the QUIT command until you call cleanup, so you + /* curl does not send the QUIT command until you call cleanup, so you * should be able to reuse this connection for additional requests. It may * not be a good idea to keep the connection open for a long time though * (more than a few minutes may result in the server timing out the diff --git a/docs/examples/smtp-mail.c b/docs/examples/smtp-mail.c index 742787824f0..29918de7ff9 100644 --- a/docs/examples/smtp-mail.c +++ b/docs/examples/smtp-mail.c @@ -101,8 +101,8 @@ int main(void) /* This is the URL for your mailserver */ curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com"); - /* Note that this option is not strictly required, omitting it will result - * in libcurl sending the MAIL FROM command with empty sender data. All + /* Note that this option is not strictly required, omitting it results in + * libcurl sending the MAIL FROM command with empty sender data. All * autoresponses should have an empty reverse-path, and should be directed * to the address in the reverse-path which triggered them. Otherwise, * they could cause an endless loop. See RFC 5321 Section 4.5.5 for more @@ -135,7 +135,7 @@ int main(void) /* Free the list of recipients */ curl_slist_free_all(recipients); - /* curl will not send the QUIT command until you call cleanup, so you + /* curl does not send the QUIT command until you call cleanup, so you * should be able to reuse this connection for additional messages * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and * calling curl_easy_perform() again. It may not be a good idea to keep diff --git a/docs/examples/smtp-mime.c b/docs/examples/smtp-mime.c index 36703a1d829..7a2a9c618b0 100644 --- a/docs/examples/smtp-mime.c +++ b/docs/examples/smtp-mime.c @@ -86,8 +86,8 @@ int main(void) /* This is the URL for your mailserver */ curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com"); - /* Note that this option is not strictly required, omitting it will result - * in libcurl sending the MAIL FROM command with empty sender data. All + /* Note that this option is not strictly required, omitting it results in + * libcurl sending the MAIL FROM command with empty sender data. All * autoresponses should have an empty reverse-path, and should be directed * to the address in the reverse-path which triggered them. Otherwise, * they could cause an endless loop. See RFC 5321 Section 4.5.5 for more @@ -150,7 +150,7 @@ int main(void) curl_slist_free_all(recipients); curl_slist_free_all(headers); - /* curl will not send the QUIT command until you call cleanup, so you + /* curl does not send the QUIT command until you call cleanup, so you * should be able to reuse this connection for additional messages * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and * calling curl_easy_perform() again. It may not be a good idea to keep diff --git a/docs/examples/smtp-multi.c b/docs/examples/smtp-multi.c index e5bc4011c18..8837c57fd87 100644 --- a/docs/examples/smtp-multi.c +++ b/docs/examples/smtp-multi.c @@ -103,7 +103,7 @@ int main(void) /* This is the URL for your mailserver */ curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com"); - /* Note that this option is not strictly required, omitting it will result in + /* Note that this option is not strictly required, omitting it results in * libcurl sending the MAIL FROM command with empty sender data. All * autoresponses should have an empty reverse-path, and should be directed * to the address in the reverse-path which triggered them. Otherwise, they diff --git a/docs/examples/smtp-ssl.c b/docs/examples/smtp-ssl.c index 89708408d74..150de9ceab3 100644 --- a/docs/examples/smtp-ssl.c +++ b/docs/examples/smtp-ssl.c @@ -117,14 +117,14 @@ int main(void) /* If the site you are connecting to uses a different host name that what * they have mentioned in their server certificate's commonName (or - * subjectAltName) fields, libcurl will refuse to connect. You can skip - * this check, but this will make the connection less secure. */ + * subjectAltName) fields, libcurl refuses to connect. You can skip this + * check, but it makes the connection insecure. */ #ifdef SKIP_HOSTNAME_VERIFICATION curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); #endif - /* Note that this option is not strictly required, omitting it will result - * in libcurl sending the MAIL FROM command with empty sender data. All + /* Note that this option is not strictly required, omitting it results in + * libcurl sending the MAIL FROM command with empty sender data. All * autoresponses should have an empty reverse-path, and should be directed * to the address in the reverse-path which triggered them. Otherwise, * they could cause an endless loop. See RFC 5321 Section 4.5.5 for more @@ -146,7 +146,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx); curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); - /* Since the traffic will be encrypted, it is useful to turn on debug + /* Since the traffic is encrypted, it is useful to turn on debug * information within libcurl to see what is happening during the * transfer */ curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); diff --git a/docs/examples/smtp-tls.c b/docs/examples/smtp-tls.c index 83aab69cbb6..fd4e385023a 100644 --- a/docs/examples/smtp-tls.c +++ b/docs/examples/smtp-tls.c @@ -105,10 +105,10 @@ int main(void) * matches your server configuration. */ curl_easy_setopt(curl, CURLOPT_URL, "smtp://mainserver.example.net:587"); - /* In this example, we will start with a plain text connection, and upgrade - * to Transport Layer Security (TLS) using the STARTTLS command. Be careful - * of using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer - * will continue anyway - see the security discussion in the libcurl + /* In this example, we start with a plain text connection, and upgrade to + * Transport Layer Security (TLS) using the STARTTLS command. Be careful + * of using CURLUSESSL_TRY here, because if TLS upgrade fails, the + * transfer continues anyway - see the security discussion in the libcurl * tutorial for more details. */ curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); @@ -125,8 +125,8 @@ int main(void) * for more information. */ curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem"); - /* Note that this option is not strictly required, omitting it will result - * in libcurl sending the MAIL FROM command with empty sender data. All + /* Note that this option is not strictly required, omitting it results in + * libcurl sending the MAIL FROM command with empty sender data. All * autoresponses should have an empty reverse-path, and should be directed * to the address in the reverse-path which triggered them. Otherwise, * they could cause an endless loop. See RFC 5321 Section 4.5.5 for more @@ -148,7 +148,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx); curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); - /* Since the traffic will be encrypted, it is useful to turn on debug + /* Since the traffic is encrypted, it is useful to turn on debug * information within libcurl to see what is happening during the * transfer. */ diff --git a/docs/examples/smtp-vrfy.c b/docs/examples/smtp-vrfy.c index 70da41b0658..0135efef2df 100644 --- a/docs/examples/smtp-vrfy.c +++ b/docs/examples/smtp-vrfy.c @@ -68,7 +68,7 @@ int main(void) /* Free the list of recipients */ curl_slist_free_all(recipients); - /* curl will not send the QUIT command until you call cleanup, so you + /* curl does not send the QUIT command until you call cleanup, so you * should be able to reuse this connection for additional requests. It may * not be a good idea to keep the connection open for a long time though * (more than a few minutes may result in the server timing out the diff --git a/docs/examples/synctime.c b/docs/examples/synctime.c index 2d7d523d50d..ab61b2fb009 100644 --- a/docs/examples/synctime.c +++ b/docs/examples/synctime.c @@ -50,7 +50,7 @@ * using HTTP protocol which has no problem with firewall/proxy. * * For this software to work, you should take note of these items. - * 1. Your firewall/proxy must allow your computer to surf internet. + * 1. Your firewall/proxy must allow your computer to surf Internet. * 2. Webserver system time must in sync with the NTP time server, * or at least provide an accurate time keeping. * 3. Webserver HTTP header does not provide the milliseconds units, @@ -59,7 +59,7 @@ * as Round-Trip delay time is not taken into consideration. * Compensation of network, firewall/proxy delay cannot be simply divide * the Round-Trip delay time by half. - * 5. Win32 SetSystemTime() API will set your computer clock according to + * 5. Win32 SetSystemTime() API sets your computer clock according to * GMT/UTC time. Therefore your computer timezone must be properly set. * 6. Webserver data should not be cached by the proxy server. Some * webserver provide Cache-Control to prevent caching. @@ -71,7 +71,7 @@ * tf.nist.gov/timefreq/service/firewall.htm * * Usage: - * This software will synchronise your computer clock only when you issue + * This software synchronises your computer clock only when you issue * it with --synctime. By default, it only display the webserver's clock. * * Written by: Frank (contributed to libcurl) @@ -171,7 +171,7 @@ size_t SyncTime_CURL_WriteHeader(void *ptr, size_t size, size_t nmemb, break; } } - AutoSyncTime = 3; /* Computer clock will be adjusted */ + AutoSyncTime = 3; /* Computer clock is adjusted */ } else { AutoSyncTime = 0; /* Error in sscanf() fields conversion */ diff --git a/docs/examples/unixsocket.c b/docs/examples/unixsocket.c index 53c5fd2de8a..90c655917da 100644 --- a/docs/examples/unixsocket.c +++ b/docs/examples/unixsocket.c @@ -53,7 +53,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_UNIX_SOCKET_PATH, PATH); #endif - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/usercertinmem.c b/docs/examples/usercertinmem.c index 12a2b7937bf..b35d982035e 100644 --- a/docs/examples/usercertinmem.c +++ b/docs/examples/usercertinmem.c @@ -199,8 +199,7 @@ int main(void) curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); curl_easy_setopt(ch, CURLOPT_SSLKEYTYPE, "PEM"); - /* first try: retrieve page without user certificate and key -> will fail - */ + /* first try: retrieve page without user certificate and key -> fails */ rv = curl_easy_perform(ch); if(rv == CURLE_OK) { printf("*** transfer succeeded ***\n"); @@ -209,7 +208,7 @@ int main(void) printf("*** transfer failed ***\n"); } - /* second try: retrieve page using user certificate and key -> will succeed + /* second try: retrieve page using user certificate and key -> succeeds * load the certificate and key by installing a function doing the necessary * "modifications" to the SSL CONTEXT just before link init */ diff --git a/docs/examples/websocket-cb.c b/docs/examples/websocket-cb.c index 7adbf4489dc..09d6c647dd1 100644 --- a/docs/examples/websocket-cb.c +++ b/docs/examples/websocket-cb.c @@ -54,7 +54,7 @@ int main(void) /* pass the easy handle to the callback */ curl_easy_setopt(curl, CURLOPT_WRITEDATA, curl); - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/examples/websocket.c b/docs/examples/websocket.c index dbcd044f5a4..039b4f8b958 100644 --- a/docs/examples/websocket.c +++ b/docs/examples/websocket.c @@ -113,7 +113,7 @@ int main(void) curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L); /* websocket style */ - /* Perform the request, res will get the return code */ + /* Perform the request, res gets the return code */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) From 01b42aa08bc12dc692a8ce712dce0da09ce9d227 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 17:41:40 +0100 Subject: [PATCH 384/509] TODO: Select signature algorithms Closes #12982 --- docs/TODO | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/TODO b/docs/TODO index f1b3ccd664c..49242227cf1 100644 --- a/docs/TODO +++ b/docs/TODO @@ -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 @@ -922,6 +923,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 From 26bccd631b2d06982911bef7d7d1e37ed9c672f5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 17:43:22 +0100 Subject: [PATCH 385/509] TODO: build HTTP/3 with OpenSSL and nghttp3 using cmake Closes #12988 --- docs/TODO | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/TODO b/docs/TODO index 49242227cf1..06257f53f7c 100644 --- a/docs/TODO +++ b/docs/TODO @@ -183,6 +183,7 @@ 19.4 Package curl for Windows in a signed installer 19.5 make configure use --cache-file more and better 19.6 build curl with Windows Unicode support + 19.7 build HTTP/3 with OpenSSL and nghttp3 using cmake 20. Test suite 20.1 SSL tunnel @@ -1339,6 +1340,10 @@ See https://github.com/curl/curl/issues/7229 +19.7 build HTTP/3 with OpenSSL and nghttp3 using cmake + + https://github.com/curl/curl/issues/12988 + 20. Test suite 20.1 SSL tunnel From 9342563ef2323258641d755c1a29965bd1102f66 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 17:44:55 +0100 Subject: [PATCH 386/509] KNOWN_BUGS: HTTP/2 prior knowledge over proxy Closes #12641 --- docs/KNOWN_BUGS | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index e5ff518e290..742e06f0e5b 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -105,6 +105,7 @@ 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 @@ -596,6 +597,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 From efda7eda6268f41dfd45afc7968ed3ceaacc87c3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 17:46:19 +0100 Subject: [PATCH 387/509] KNOWN_BUGS: Implicit FTPS upload timeout Closes #11720 --- docs/KNOWN_BUGS | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 742e06f0e5b..0e2fe3e9c70 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -61,6 +61,7 @@ problems may have been fixed or changed somewhat since this was written. 7. FTP 7.1 FTP upload fails if remebered dir is deleted + 7.2 Implicit FTPS upload timeout 7.3 FTP with NOBODY and FAILONERROR 7.4 FTP with ACCT 7.11 FTPS upload data loss with TLS 1.3 @@ -383,6 +384,10 @@ problems may have been fixed or changed somewhat since this was written. 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 From 745b99e1e841cd833bc0d02fcfbf9c0e538690b3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 17:48:18 +0100 Subject: [PATCH 388/509] KNOWN_BUGS: FTPS upload, FileZilla, GnuTLS and close_notify Closes #11383 --- docs/KNOWN_BUGS | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 0e2fe3e9c70..cc3e054eef6 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -64,6 +64,7 @@ problems may have been fixed or changed somewhat since this was written. 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 @@ -401,6 +402,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 From b8ad95bf391ca3f9fb5ae4b620592df1eea1a23b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2024 17:50:25 +0100 Subject: [PATCH 389/509] KNOWN_BUGS: IMAPS connection fails with rustls error Closes #10457 --- docs/KNOWN_BUGS | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index cc3e054eef6..9244dc5e32f 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -16,6 +16,7 @@ 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 @@ -136,6 +137,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 From 65405459d58abed6d5b6ea20ccdca972aa807f9c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 28 Feb 2024 08:02:49 +0100 Subject: [PATCH 390/509] getparam: make --ftp-ssl work again Follow-up to 9e4e527 which accidentally broke it Reported-by: Jordan Brown Fixes #13006 Closes #13007 --- src/tool_getparam.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 4c910fd73c9..23fe3106e6d 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -1593,6 +1593,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ url->flags |= GETOUT_URL; } break; + case C_FTP_SSL: /* --ftp-ssl */ case C_SSL: /* --ssl */ if(toggle && !feature_ssl) err = PARAM_LIBCURL_DOESNT_SUPPORT; @@ -1600,7 +1601,8 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ config->ftp_ssl = toggle; if(config->ftp_ssl) warnf(global, - "--ssl is an insecure option, consider --ssl-reqd instead"); + "--%s is an insecure option, consider --ssl-reqd instead", + a->lname); } break; case C_FTP_PASV: /* --ftp-pasv */ From 8d67c61c47a0dcc3e150d33ab941a205e76ce9eb Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Wed, 28 Feb 2024 11:28:10 +0100 Subject: [PATCH 391/509] curldown: Fix email address in Copyright The curldown conversion accidentally replaced daniel@haxx.se with just daniel.se. This reverts back to the proper email address in the curldown docs as well as in a few other stray places where it was incorrect (while unrelated to curldown). Reviewed-by: Daniel Stenberg Closes: #12997 --- docs/CURLDOWN.md | 2 +- docs/curl-config.md | 2 +- docs/libcurl/curl_easy_cleanup.md | 2 +- docs/libcurl/curl_easy_duphandle.md | 2 +- docs/libcurl/curl_easy_escape.md | 2 +- docs/libcurl/curl_easy_getinfo.md | 2 +- docs/libcurl/curl_easy_header.md | 2 +- docs/libcurl/curl_easy_init.md | 2 +- docs/libcurl/curl_easy_nextheader.md | 2 +- docs/libcurl/curl_easy_option_by_id.md | 2 +- docs/libcurl/curl_easy_option_by_name.md | 2 +- docs/libcurl/curl_easy_option_next.md | 2 +- docs/libcurl/curl_easy_pause.md | 2 +- docs/libcurl/curl_easy_perform.md | 2 +- docs/libcurl/curl_easy_recv.md | 2 +- docs/libcurl/curl_easy_reset.md | 2 +- docs/libcurl/curl_easy_send.md | 2 +- docs/libcurl/curl_easy_setopt.md | 2 +- docs/libcurl/curl_easy_strerror.md | 2 +- docs/libcurl/curl_easy_unescape.md | 2 +- docs/libcurl/curl_easy_upkeep.md | 2 +- docs/libcurl/curl_escape.md | 2 +- docs/libcurl/curl_formadd.md | 2 +- docs/libcurl/curl_formfree.md | 2 +- docs/libcurl/curl_formget.md | 2 +- docs/libcurl/curl_free.md | 2 +- docs/libcurl/curl_getdate.md | 2 +- docs/libcurl/curl_getenv.md | 2 +- docs/libcurl/curl_global_cleanup.md | 2 +- docs/libcurl/curl_global_init.md | 2 +- docs/libcurl/curl_global_init_mem.md | 2 +- docs/libcurl/curl_global_sslset.md | 2 +- docs/libcurl/curl_global_trace.md | 2 +- docs/libcurl/curl_mime_addpart.md | 2 +- docs/libcurl/curl_mime_data.md | 2 +- docs/libcurl/curl_mime_data_cb.md | 2 +- docs/libcurl/curl_mime_encoder.md | 2 +- docs/libcurl/curl_mime_filedata.md | 2 +- docs/libcurl/curl_mime_filename.md | 2 +- docs/libcurl/curl_mime_free.md | 2 +- docs/libcurl/curl_mime_headers.md | 2 +- docs/libcurl/curl_mime_init.md | 2 +- docs/libcurl/curl_mime_name.md | 2 +- docs/libcurl/curl_mime_subparts.md | 2 +- docs/libcurl/curl_mime_type.md | 2 +- docs/libcurl/curl_mprintf.md | 2 +- docs/libcurl/curl_multi_add_handle.md | 2 +- docs/libcurl/curl_multi_assign.md | 2 +- docs/libcurl/curl_multi_cleanup.md | 2 +- docs/libcurl/curl_multi_fdset.md | 2 +- docs/libcurl/curl_multi_get_handles.md | 2 +- docs/libcurl/curl_multi_info_read.md | 2 +- docs/libcurl/curl_multi_init.md | 2 +- docs/libcurl/curl_multi_perform.md | 2 +- docs/libcurl/curl_multi_poll.md | 2 +- docs/libcurl/curl_multi_remove_handle.md | 2 +- docs/libcurl/curl_multi_setopt.md | 2 +- docs/libcurl/curl_multi_socket.md | 2 +- docs/libcurl/curl_multi_socket_action.md | 2 +- docs/libcurl/curl_multi_socket_all.md | 2 +- docs/libcurl/curl_multi_strerror.md | 2 +- docs/libcurl/curl_multi_timeout.md | 2 +- docs/libcurl/curl_multi_wait.md | 2 +- docs/libcurl/curl_multi_wakeup.md | 2 +- docs/libcurl/curl_pushheader_byname.md | 2 +- docs/libcurl/curl_pushheader_bynum.md | 2 +- docs/libcurl/curl_share_cleanup.md | 2 +- docs/libcurl/curl_share_init.md | 2 +- docs/libcurl/curl_share_setopt.md | 2 +- docs/libcurl/curl_share_strerror.md | 2 +- docs/libcurl/curl_slist_append.md | 2 +- docs/libcurl/curl_slist_free_all.md | 2 +- docs/libcurl/curl_strequal.md | 2 +- docs/libcurl/curl_strnequal.md | 2 +- docs/libcurl/curl_unescape.md | 2 +- docs/libcurl/curl_url.md | 2 +- docs/libcurl/curl_url_cleanup.md | 2 +- docs/libcurl/curl_url_dup.md | 2 +- docs/libcurl/curl_url_get.md | 2 +- docs/libcurl/curl_url_set.md | 2 +- docs/libcurl/curl_url_strerror.md | 2 +- docs/libcurl/curl_version.md | 2 +- docs/libcurl/curl_version_info.md | 2 +- docs/libcurl/curl_ws_meta.md | 2 +- docs/libcurl/curl_ws_recv.md | 2 +- docs/libcurl/curl_ws_send.md | 2 +- docs/libcurl/libcurl-easy.md | 2 +- docs/libcurl/libcurl-env-dbg.md | 2 +- docs/libcurl/libcurl-env.md | 2 +- docs/libcurl/libcurl-errors.md | 2 +- docs/libcurl/libcurl-multi.md | 2 +- docs/libcurl/libcurl-security.md | 2 +- docs/libcurl/libcurl-share.md | 2 +- docs/libcurl/libcurl-thread.md | 2 +- docs/libcurl/libcurl-tutorial.md | 2 +- docs/libcurl/libcurl-url.md | 2 +- docs/libcurl/libcurl-ws.md | 2 +- docs/libcurl/libcurl.md | 2 +- docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md | 2 +- docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md | 2 +- docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_CAINFO.md | 2 +- docs/libcurl/opts/CURLINFO_CAPATH.md | 2 +- docs/libcurl/opts/CURLINFO_CERTINFO.md | 2 +- docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md | 2 +- docs/libcurl/opts/CURLINFO_CONNECT_TIME.md | 2 +- docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_CONN_ID.md | 2 +- docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md | 2 +- docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md | 2 +- docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md | 2 +- docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md | 2 +- docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md | 2 +- docs/libcurl/opts/CURLINFO_COOKIELIST.md | 2 +- docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md | 2 +- docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md | 2 +- docs/libcurl/opts/CURLINFO_FILETIME.md | 2 +- docs/libcurl/opts/CURLINFO_FILETIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md | 2 +- docs/libcurl/opts/CURLINFO_HEADER_SIZE.md | 2 +- docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md | 2 +- docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md | 2 +- docs/libcurl/opts/CURLINFO_HTTP_VERSION.md | 2 +- docs/libcurl/opts/CURLINFO_LASTSOCKET.md | 2 +- docs/libcurl/opts/CURLINFO_LOCAL_IP.md | 2 +- docs/libcurl/opts/CURLINFO_LOCAL_PORT.md | 2 +- docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md | 2 +- docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md | 2 +- docs/libcurl/opts/CURLINFO_OS_ERRNO.md | 2 +- docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md | 2 +- docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_PRIMARY_IP.md | 2 +- docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md | 2 +- docs/libcurl/opts/CURLINFO_PRIVATE.md | 2 +- docs/libcurl/opts/CURLINFO_PROTOCOL.md | 2 +- docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md | 2 +- docs/libcurl/opts/CURLINFO_PROXY_ERROR.md | 2 +- docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md | 2 +- docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md | 2 +- docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md | 2 +- docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_REDIRECT_URL.md | 2 +- docs/libcurl/opts/CURLINFO_REFERER.md | 2 +- docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md | 2 +- docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md | 2 +- docs/libcurl/opts/CURLINFO_RETRY_AFTER.md | 2 +- docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md | 2 +- docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md | 2 +- docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md | 2 +- docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md | 2 +- docs/libcurl/opts/CURLINFO_SCHEME.md | 2 +- docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md | 2 +- docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md | 2 +- docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md | 2 +- docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md | 2 +- docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md | 2 +- docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md | 2 +- docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md | 2 +- docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md | 2 +- docs/libcurl/opts/CURLINFO_SSL_ENGINES.md | 2 +- docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md | 2 +- docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md | 2 +- docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_TLS_SESSION.md | 2 +- docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md | 2 +- docs/libcurl/opts/CURLINFO_TOTAL_TIME.md | 2 +- docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md | 2 +- docs/libcurl/opts/CURLINFO_USED_PROXY.md | 2 +- docs/libcurl/opts/CURLINFO_XFER_ID.md | 2 +- docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md | 2 +- docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md | 2 +- docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md | 2 +- docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md | 2 +- docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md | 2 +- docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md | 2 +- docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md | 2 +- docs/libcurl/opts/CURLMOPT_PIPELINING.md | 2 +- docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md | 2 +- docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md | 2 +- docs/libcurl/opts/CURLMOPT_PUSHDATA.md | 2 +- docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md | 2 +- docs/libcurl/opts/CURLMOPT_SOCKETDATA.md | 2 +- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 2 +- docs/libcurl/opts/CURLMOPT_TIMERDATA.md | 2 +- docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md | 2 +- docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md | 2 +- docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md | 2 +- docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md | 2 +- docs/libcurl/opts/CURLOPT_ALTSVC.md | 2 +- docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md | 2 +- docs/libcurl/opts/CURLOPT_APPEND.md | 2 +- docs/libcurl/opts/CURLOPT_AUTOREFERER.md | 2 +- docs/libcurl/opts/CURLOPT_AWS_SIGV4.md | 2 +- docs/libcurl/opts/CURLOPT_BUFFERSIZE.md | 2 +- docs/libcurl/opts/CURLOPT_CAINFO.md | 2 +- docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md | 2 +- docs/libcurl/opts/CURLOPT_CAPATH.md | 2 +- docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md | 2 +- docs/libcurl/opts/CURLOPT_CERTINFO.md | 2 +- docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_CHUNK_DATA.md | 2 +- docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md | 2 +- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md | 2 +- docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md | 2 +- docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md | 2 +- docs/libcurl/opts/CURLOPT_CONNECT_TO.md | 2 +- docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_COOKIE.md | 2 +- docs/libcurl/opts/CURLOPT_COOKIEFILE.md | 2 +- docs/libcurl/opts/CURLOPT_COOKIEJAR.md | 2 +- docs/libcurl/opts/CURLOPT_COOKIELIST.md | 2 +- docs/libcurl/opts/CURLOPT_COOKIESESSION.md | 2 +- docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md | 2 +- docs/libcurl/opts/CURLOPT_CRLF.md | 2 +- docs/libcurl/opts/CURLOPT_CRLFILE.md | 2 +- docs/libcurl/opts/CURLOPT_CURLU.md | 2 +- docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md | 2 +- docs/libcurl/opts/CURLOPT_DEBUGDATA.md | 2 +- docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md | 2 +- docs/libcurl/opts/CURLOPT_DIRLISTONLY.md | 2 +- docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md | 2 +- docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md | 2 +- docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md | 2 +- docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md | 2 +- docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md | 2 +- docs/libcurl/opts/CURLOPT_DNS_SERVERS.md | 2 +- docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md | 2 +- docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md | 2 +- docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md | 2 +- docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md | 2 +- docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md | 2 +- docs/libcurl/opts/CURLOPT_DOH_URL.md | 2 +- docs/libcurl/opts/CURLOPT_EGDSOCKET.md | 2 +- docs/libcurl/opts/CURLOPT_ERRORBUFFER.md | 2 +- docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md | 2 +- docs/libcurl/opts/CURLOPT_FAILONERROR.md | 2 +- docs/libcurl/opts/CURLOPT_FILETIME.md | 2 +- docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md | 2 +- docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md | 2 +- docs/libcurl/opts/CURLOPT_FORBID_REUSE.md | 2 +- docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md | 2 +- docs/libcurl/opts/CURLOPT_FTPPORT.md | 2 +- docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md | 2 +- docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md | 2 +- docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md | 2 +- docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md | 2 +- docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md | 2 +- docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md | 2 +- docs/libcurl/opts/CURLOPT_HEADER.md | 2 +- docs/libcurl/opts/CURLOPT_HEADERDATA.md | 2 +- docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_HEADEROPT.md | 2 +- docs/libcurl/opts/CURLOPT_HSTS.md | 2 +- docs/libcurl/opts/CURLOPT_HSTSREADDATA.md | 2 +- docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md | 2 +- docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_HSTS_CTRL.md | 2 +- docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md | 2 +- docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md | 2 +- docs/libcurl/opts/CURLOPT_HTTPAUTH.md | 2 +- docs/libcurl/opts/CURLOPT_HTTPGET.md | 2 +- docs/libcurl/opts/CURLOPT_HTTPHEADER.md | 2 +- docs/libcurl/opts/CURLOPT_HTTPPOST.md | 2 +- docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md | 2 +- docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md | 2 +- docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md | 2 +- docs/libcurl/opts/CURLOPT_HTTP_VERSION.md | 2 +- docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md | 2 +- docs/libcurl/opts/CURLOPT_INFILESIZE.md | 2 +- docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md | 2 +- docs/libcurl/opts/CURLOPT_INTERFACE.md | 2 +- docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md | 2 +- docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_IOCTLDATA.md | 2 +- docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_IPRESOLVE.md | 2 +- docs/libcurl/opts/CURLOPT_ISSUERCERT.md | 2 +- docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md | 2 +- docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md | 2 +- docs/libcurl/opts/CURLOPT_KEYPASSWD.md | 2 +- docs/libcurl/opts/CURLOPT_KRBLEVEL.md | 2 +- docs/libcurl/opts/CURLOPT_LOCALPORT.md | 2 +- docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md | 2 +- docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md | 2 +- docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md | 2 +- docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md | 2 +- docs/libcurl/opts/CURLOPT_MAIL_AUTH.md | 2 +- docs/libcurl/opts/CURLOPT_MAIL_FROM.md | 2 +- docs/libcurl/opts/CURLOPT_MAIL_RCPT.md | 2 +- docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md | 2 +- docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md | 2 +- docs/libcurl/opts/CURLOPT_MAXCONNECTS.md | 2 +- docs/libcurl/opts/CURLOPT_MAXFILESIZE.md | 2 +- docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md | 2 +- docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md | 2 +- docs/libcurl/opts/CURLOPT_MAXREDIRS.md | 2 +- docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md | 2 +- docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md | 2 +- docs/libcurl/opts/CURLOPT_MIMEPOST.md | 2 +- docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md | 2 +- docs/libcurl/opts/CURLOPT_NETRC.md | 2 +- docs/libcurl/opts/CURLOPT_NETRC_FILE.md | 2 +- docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md | 2 +- docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md | 2 +- docs/libcurl/opts/CURLOPT_NOBODY.md | 2 +- docs/libcurl/opts/CURLOPT_NOPROGRESS.md | 2 +- docs/libcurl/opts/CURLOPT_NOPROXY.md | 2 +- docs/libcurl/opts/CURLOPT_NOSIGNAL.md | 2 +- docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md | 2 +- docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_PASSWORD.md | 2 +- docs/libcurl/opts/CURLOPT_PATH_AS_IS.md | 2 +- docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md | 2 +- docs/libcurl/opts/CURLOPT_PIPEWAIT.md | 2 +- docs/libcurl/opts/CURLOPT_PORT.md | 2 +- docs/libcurl/opts/CURLOPT_POST.md | 2 +- docs/libcurl/opts/CURLOPT_POSTFIELDS.md | 2 +- docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md | 2 +- docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md | 2 +- docs/libcurl/opts/CURLOPT_POSTQUOTE.md | 2 +- docs/libcurl/opts/CURLOPT_POSTREDIR.md | 2 +- docs/libcurl/opts/CURLOPT_PREQUOTE.md | 2 +- docs/libcurl/opts/CURLOPT_PREREQDATA.md | 2 +- docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_PRE_PROXY.md | 2 +- docs/libcurl/opts/CURLOPT_PRIVATE.md | 2 +- docs/libcurl/opts/CURLOPT_PROGRESSDATA.md | 2 +- docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_PROTOCOLS.md | 2 +- docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY.md | 2 +- docs/libcurl/opts/CURLOPT_PROXYAUTH.md | 2 +- docs/libcurl/opts/CURLOPT_PROXYHEADER.md | 2 +- docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md | 2 +- docs/libcurl/opts/CURLOPT_PROXYPORT.md | 2 +- docs/libcurl/opts/CURLOPT_PROXYTYPE.md | 2 +- docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md | 2 +- docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md | 2 +- docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md | 2 +- docs/libcurl/opts/CURLOPT_PUT.md | 2 +- docs/libcurl/opts/CURLOPT_QUICK_EXIT.md | 2 +- docs/libcurl/opts/CURLOPT_QUOTE.md | 2 +- docs/libcurl/opts/CURLOPT_RANDOM_FILE.md | 2 +- docs/libcurl/opts/CURLOPT_RANGE.md | 2 +- docs/libcurl/opts/CURLOPT_READDATA.md | 2 +- docs/libcurl/opts/CURLOPT_READFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md | 2 +- docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md | 2 +- docs/libcurl/opts/CURLOPT_REFERER.md | 2 +- docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md | 2 +- docs/libcurl/opts/CURLOPT_RESOLVE.md | 2 +- docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md | 2 +- docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_RESUME_FROM.md | 2 +- docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md | 2 +- docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md | 2 +- docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md | 2 +- docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md | 2 +- docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md | 2 +- docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md | 2 +- docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md | 2 +- docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md | 2 +- docs/libcurl/opts/CURLOPT_SASL_IR.md | 2 +- docs/libcurl/opts/CURLOPT_SEEKDATA.md | 2 +- docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md | 2 +- docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md | 2 +- docs/libcurl/opts/CURLOPT_SERVICE_NAME.md | 2 +- docs/libcurl/opts/CURLOPT_SHARE.md | 2 +- docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md | 2 +- docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md | 2 +- docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md | 2 +- docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md | 2 +- docs/libcurl/opts/CURLOPT_SSLCERT.md | 2 +- docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md | 2 +- docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md | 2 +- docs/libcurl/opts/CURLOPT_SSLENGINE.md | 2 +- docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md | 2 +- docs/libcurl/opts/CURLOPT_SSLKEY.md | 2 +- docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md | 2 +- docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md | 2 +- docs/libcurl/opts/CURLOPT_SSLVERSION.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md | 2 +- docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md | 2 +- docs/libcurl/opts/CURLOPT_STDERR.md | 2 +- docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md | 2 +- docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md | 2 +- docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md | 2 +- docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md | 2 +- docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md | 2 +- docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md | 2 +- docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md | 2 +- docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md | 2 +- docs/libcurl/opts/CURLOPT_TCP_NODELAY.md | 2 +- docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md | 2 +- docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md | 2 +- docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md | 2 +- docs/libcurl/opts/CURLOPT_TIMECONDITION.md | 2 +- docs/libcurl/opts/CURLOPT_TIMEOUT.md | 2 +- docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md | 2 +- docs/libcurl/opts/CURLOPT_TIMEVALUE.md | 2 +- docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md | 2 +- docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md | 2 +- docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md | 2 +- docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md | 2 +- docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md | 2 +- docs/libcurl/opts/CURLOPT_TRAILERDATA.md | 2 +- docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md | 2 +- docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md | 2 +- docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md | 2 +- docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md | 2 +- docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md | 2 +- docs/libcurl/opts/CURLOPT_UPLOAD.md | 2 +- docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md | 2 +- docs/libcurl/opts/CURLOPT_URL.md | 2 +- docs/libcurl/opts/CURLOPT_USERAGENT.md | 2 +- docs/libcurl/opts/CURLOPT_USERNAME.md | 2 +- docs/libcurl/opts/CURLOPT_USERPWD.md | 2 +- docs/libcurl/opts/CURLOPT_USE_SSL.md | 2 +- docs/libcurl/opts/CURLOPT_VERBOSE.md | 2 +- docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md | 2 +- docs/libcurl/opts/CURLOPT_WRITEDATA.md | 2 +- docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_WS_OPTIONS.md | 2 +- docs/libcurl/opts/CURLOPT_XFERINFODATA.md | 2 +- docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md | 2 +- docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md | 2 +- docs/libcurl/opts/CURLSHOPT_SHARE.md | 2 +- docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md | 2 +- docs/libcurl/opts/CURLSHOPT_UNSHARE.md | 2 +- docs/libcurl/opts/CURLSHOPT_USERDATA.md | 2 +- docs/mk-ca-bundle.md | 2 +- lib/easygetopt.c | 2 +- lib/easyoptions.c | 2 +- lib/optiontable.pl | 2 +- 501 files changed, 501 insertions(+), 501 deletions(-) diff --git a/docs/CURLDOWN.md b/docs/CURLDOWN.md index 061b7d58714..8440ef447d2 100644 --- a/docs/CURLDOWN.md +++ b/docs/CURLDOWN.md @@ -62,7 +62,7 @@ the nroff format does not carry a distinction. Each curldown starts with a header with meta-data: --- - c: Copyright (C) Daniel Stenberg, , et al. + c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_AWS_SIGV4 Section: 3 diff --git a/docs/curl-config.md b/docs/curl-config.md index 2ab9e9b0206..d82725082ab 100644 --- a/docs/curl-config.md +++ b/docs/curl-config.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl-config Section: 1 diff --git a/docs/libcurl/curl_easy_cleanup.md b/docs/libcurl/curl_easy_cleanup.md index bdbc058947f..3175d0b7cef 100644 --- a/docs/libcurl/curl_easy_cleanup.md +++ b/docs/libcurl/curl_easy_cleanup.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_cleanup Section: 3 diff --git a/docs/libcurl/curl_easy_duphandle.md b/docs/libcurl/curl_easy_duphandle.md index d7c5b03becd..babc222ef41 100644 --- a/docs/libcurl/curl_easy_duphandle.md +++ b/docs/libcurl/curl_easy_duphandle.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_duphandle Section: 3 diff --git a/docs/libcurl/curl_easy_escape.md b/docs/libcurl/curl_easy_escape.md index 655dbb44666..9ab8f3a679d 100644 --- a/docs/libcurl/curl_easy_escape.md +++ b/docs/libcurl/curl_easy_escape.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_escape Section: 3 diff --git a/docs/libcurl/curl_easy_getinfo.md b/docs/libcurl/curl_easy_getinfo.md index bd18aa7c638..8076dc84c80 100644 --- a/docs/libcurl/curl_easy_getinfo.md +++ b/docs/libcurl/curl_easy_getinfo.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_getinfo Section: 3 diff --git a/docs/libcurl/curl_easy_header.md b/docs/libcurl/curl_easy_header.md index 9c2d76ceaf0..ff3699b94ce 100644 --- a/docs/libcurl/curl_easy_header.md +++ b/docs/libcurl/curl_easy_header.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_header Section: 3 diff --git a/docs/libcurl/curl_easy_init.md b/docs/libcurl/curl_easy_init.md index a7465547fbe..c51e8c40d1a 100644 --- a/docs/libcurl/curl_easy_init.md +++ b/docs/libcurl/curl_easy_init.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_init Section: 3 diff --git a/docs/libcurl/curl_easy_nextheader.md b/docs/libcurl/curl_easy_nextheader.md index 7c7e151c33d..f7057af7f82 100644 --- a/docs/libcurl/curl_easy_nextheader.md +++ b/docs/libcurl/curl_easy_nextheader.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_nextheader Section: 3 diff --git a/docs/libcurl/curl_easy_option_by_id.md b/docs/libcurl/curl_easy_option_by_id.md index b1d6d421b7d..99ebb3461cc 100644 --- a/docs/libcurl/curl_easy_option_by_id.md +++ b/docs/libcurl/curl_easy_option_by_id.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_option_by_id Section: 3 diff --git a/docs/libcurl/curl_easy_option_by_name.md b/docs/libcurl/curl_easy_option_by_name.md index 86ccbd4da22..401fc02ff11 100644 --- a/docs/libcurl/curl_easy_option_by_name.md +++ b/docs/libcurl/curl_easy_option_by_name.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_option_by_name Section: 3 diff --git a/docs/libcurl/curl_easy_option_next.md b/docs/libcurl/curl_easy_option_next.md index f5da17cfcd2..d231c806846 100644 --- a/docs/libcurl/curl_easy_option_next.md +++ b/docs/libcurl/curl_easy_option_next.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_option_next Section: 3 diff --git a/docs/libcurl/curl_easy_pause.md b/docs/libcurl/curl_easy_pause.md index 03e6b917a67..ce3681a6395 100644 --- a/docs/libcurl/curl_easy_pause.md +++ b/docs/libcurl/curl_easy_pause.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_pause Section: 3 diff --git a/docs/libcurl/curl_easy_perform.md b/docs/libcurl/curl_easy_perform.md index 4f0989b9b6a..23320201da9 100644 --- a/docs/libcurl/curl_easy_perform.md +++ b/docs/libcurl/curl_easy_perform.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_perform Section: 3 diff --git a/docs/libcurl/curl_easy_recv.md b/docs/libcurl/curl_easy_recv.md index df210f71af2..249362c0601 100644 --- a/docs/libcurl/curl_easy_recv.md +++ b/docs/libcurl/curl_easy_recv.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_recv Section: 3 diff --git a/docs/libcurl/curl_easy_reset.md b/docs/libcurl/curl_easy_reset.md index c2aea6e10b2..a74eb7fef61 100644 --- a/docs/libcurl/curl_easy_reset.md +++ b/docs/libcurl/curl_easy_reset.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_reset Section: 3 diff --git a/docs/libcurl/curl_easy_send.md b/docs/libcurl/curl_easy_send.md index 725b05ca176..edeb65c5397 100644 --- a/docs/libcurl/curl_easy_send.md +++ b/docs/libcurl/curl_easy_send.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_send Section: 3 diff --git a/docs/libcurl/curl_easy_setopt.md b/docs/libcurl/curl_easy_setopt.md index 5e8313fae9a..843673a6218 100644 --- a/docs/libcurl/curl_easy_setopt.md +++ b/docs/libcurl/curl_easy_setopt.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_setopt Section: 3 diff --git a/docs/libcurl/curl_easy_strerror.md b/docs/libcurl/curl_easy_strerror.md index 218601a4446..265efc05148 100644 --- a/docs/libcurl/curl_easy_strerror.md +++ b/docs/libcurl/curl_easy_strerror.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_strerror Section: 3 diff --git a/docs/libcurl/curl_easy_unescape.md b/docs/libcurl/curl_easy_unescape.md index 4f9262b34ac..e397a1afa0c 100644 --- a/docs/libcurl/curl_easy_unescape.md +++ b/docs/libcurl/curl_easy_unescape.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_unescape Section: 3 diff --git a/docs/libcurl/curl_easy_upkeep.md b/docs/libcurl/curl_easy_upkeep.md index 2ad89d3bbc1..fd27f1042ed 100644 --- a/docs/libcurl/curl_easy_upkeep.md +++ b/docs/libcurl/curl_easy_upkeep.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_easy_upkeep Section: 3 diff --git a/docs/libcurl/curl_escape.md b/docs/libcurl/curl_escape.md index e5e7e92b745..1c06ab9f516 100644 --- a/docs/libcurl/curl_escape.md +++ b/docs/libcurl/curl_escape.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_escape Section: 3 diff --git a/docs/libcurl/curl_formadd.md b/docs/libcurl/curl_formadd.md index e2d1ad7f956..7cd89165ac0 100644 --- a/docs/libcurl/curl_formadd.md +++ b/docs/libcurl/curl_formadd.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_formadd Section: 3 diff --git a/docs/libcurl/curl_formfree.md b/docs/libcurl/curl_formfree.md index d2f90c03fba..65ff0e02926 100644 --- a/docs/libcurl/curl_formfree.md +++ b/docs/libcurl/curl_formfree.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_formfree Section: 3 diff --git a/docs/libcurl/curl_formget.md b/docs/libcurl/curl_formget.md index 7130ee937ee..6da9b0d69ec 100644 --- a/docs/libcurl/curl_formget.md +++ b/docs/libcurl/curl_formget.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_formget Section: 3 diff --git a/docs/libcurl/curl_free.md b/docs/libcurl/curl_free.md index 69639405560..d1a26b79528 100644 --- a/docs/libcurl/curl_free.md +++ b/docs/libcurl/curl_free.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_free Section: 3 diff --git a/docs/libcurl/curl_getdate.md b/docs/libcurl/curl_getdate.md index e4fbf039442..0a5ba446cce 100644 --- a/docs/libcurl/curl_getdate.md +++ b/docs/libcurl/curl_getdate.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_getdate Section: 3 diff --git a/docs/libcurl/curl_getenv.md b/docs/libcurl/curl_getenv.md index dbf326d11be..f4c72156dc1 100644 --- a/docs/libcurl/curl_getenv.md +++ b/docs/libcurl/curl_getenv.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_getenv Section: 3 diff --git a/docs/libcurl/curl_global_cleanup.md b/docs/libcurl/curl_global_cleanup.md index 5502e718d09..ae2380aac54 100644 --- a/docs/libcurl/curl_global_cleanup.md +++ b/docs/libcurl/curl_global_cleanup.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_global_cleanup Section: 3 diff --git a/docs/libcurl/curl_global_init.md b/docs/libcurl/curl_global_init.md index 5c00e862d3a..7382369f930 100644 --- a/docs/libcurl/curl_global_init.md +++ b/docs/libcurl/curl_global_init.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_global_init Section: 3 diff --git a/docs/libcurl/curl_global_init_mem.md b/docs/libcurl/curl_global_init_mem.md index d4f24ac943e..edc7563560e 100644 --- a/docs/libcurl/curl_global_init_mem.md +++ b/docs/libcurl/curl_global_init_mem.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_global_init_mem Section: 3 diff --git a/docs/libcurl/curl_global_sslset.md b/docs/libcurl/curl_global_sslset.md index 6f50867a1a0..25dde166bd6 100644 --- a/docs/libcurl/curl_global_sslset.md +++ b/docs/libcurl/curl_global_sslset.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_global_sslset Section: 3 diff --git a/docs/libcurl/curl_global_trace.md b/docs/libcurl/curl_global_trace.md index 56e320d0470..2b27401b389 100644 --- a/docs/libcurl/curl_global_trace.md +++ b/docs/libcurl/curl_global_trace.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_global_trace Section: 3 diff --git a/docs/libcurl/curl_mime_addpart.md b/docs/libcurl/curl_mime_addpart.md index f641abbcfde..dc11f10ccc5 100644 --- a/docs/libcurl/curl_mime_addpart.md +++ b/docs/libcurl/curl_mime_addpart.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_addpart Section: 3 diff --git a/docs/libcurl/curl_mime_data.md b/docs/libcurl/curl_mime_data.md index 15a1d2707cb..0733d01479e 100644 --- a/docs/libcurl/curl_mime_data.md +++ b/docs/libcurl/curl_mime_data.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_data Section: 3 diff --git a/docs/libcurl/curl_mime_data_cb.md b/docs/libcurl/curl_mime_data_cb.md index bd3c77ac504..e17866b95d1 100644 --- a/docs/libcurl/curl_mime_data_cb.md +++ b/docs/libcurl/curl_mime_data_cb.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_data_cb Section: 3 diff --git a/docs/libcurl/curl_mime_encoder.md b/docs/libcurl/curl_mime_encoder.md index 85dc3ac11e2..54850654735 100644 --- a/docs/libcurl/curl_mime_encoder.md +++ b/docs/libcurl/curl_mime_encoder.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_encoder Section: 3 diff --git a/docs/libcurl/curl_mime_filedata.md b/docs/libcurl/curl_mime_filedata.md index 07704120e3b..81441e39487 100644 --- a/docs/libcurl/curl_mime_filedata.md +++ b/docs/libcurl/curl_mime_filedata.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_filedata Section: 3 diff --git a/docs/libcurl/curl_mime_filename.md b/docs/libcurl/curl_mime_filename.md index 76c045bcb66..234fd2c6194 100644 --- a/docs/libcurl/curl_mime_filename.md +++ b/docs/libcurl/curl_mime_filename.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_filename Section: 3 diff --git a/docs/libcurl/curl_mime_free.md b/docs/libcurl/curl_mime_free.md index 5aa5b6aa15f..5b352dfbabe 100644 --- a/docs/libcurl/curl_mime_free.md +++ b/docs/libcurl/curl_mime_free.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_free Section: 3 diff --git a/docs/libcurl/curl_mime_headers.md b/docs/libcurl/curl_mime_headers.md index 4f6421abdd2..21d08986c2a 100644 --- a/docs/libcurl/curl_mime_headers.md +++ b/docs/libcurl/curl_mime_headers.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_headers Section: 3 diff --git a/docs/libcurl/curl_mime_init.md b/docs/libcurl/curl_mime_init.md index 0811bb3d8c6..db905c70482 100644 --- a/docs/libcurl/curl_mime_init.md +++ b/docs/libcurl/curl_mime_init.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_init Section: 3 diff --git a/docs/libcurl/curl_mime_name.md b/docs/libcurl/curl_mime_name.md index bd25033977d..3482a655573 100644 --- a/docs/libcurl/curl_mime_name.md +++ b/docs/libcurl/curl_mime_name.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_name Section: 3 diff --git a/docs/libcurl/curl_mime_subparts.md b/docs/libcurl/curl_mime_subparts.md index 4136a1b2a5d..8fb3f3ecad0 100644 --- a/docs/libcurl/curl_mime_subparts.md +++ b/docs/libcurl/curl_mime_subparts.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_subparts Section: 3 diff --git a/docs/libcurl/curl_mime_type.md b/docs/libcurl/curl_mime_type.md index cdb09f8a214..14cf4ca1dea 100644 --- a/docs/libcurl/curl_mime_type.md +++ b/docs/libcurl/curl_mime_type.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_mime_type Section: 3 diff --git a/docs/libcurl/curl_mprintf.md b/docs/libcurl/curl_mprintf.md index 5aca9e3f6be..658a2deff50 100644 --- a/docs/libcurl/curl_mprintf.md +++ b/docs/libcurl/curl_mprintf.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_printf Section: 3 diff --git a/docs/libcurl/curl_multi_add_handle.md b/docs/libcurl/curl_multi_add_handle.md index 3d6ba81fb1f..ab03bdd44f0 100644 --- a/docs/libcurl/curl_multi_add_handle.md +++ b/docs/libcurl/curl_multi_add_handle.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_add_handle Section: 3 diff --git a/docs/libcurl/curl_multi_assign.md b/docs/libcurl/curl_multi_assign.md index 3f01349cd0f..aa8d1bf5e7a 100644 --- a/docs/libcurl/curl_multi_assign.md +++ b/docs/libcurl/curl_multi_assign.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_assign Section: 3 diff --git a/docs/libcurl/curl_multi_cleanup.md b/docs/libcurl/curl_multi_cleanup.md index 9aa64a85c92..ed2b29a71a1 100644 --- a/docs/libcurl/curl_multi_cleanup.md +++ b/docs/libcurl/curl_multi_cleanup.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_cleanup Section: 3 diff --git a/docs/libcurl/curl_multi_fdset.md b/docs/libcurl/curl_multi_fdset.md index 37d5959d18e..bcdf15a83f5 100644 --- a/docs/libcurl/curl_multi_fdset.md +++ b/docs/libcurl/curl_multi_fdset.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_fdset Section: 3 diff --git a/docs/libcurl/curl_multi_get_handles.md b/docs/libcurl/curl_multi_get_handles.md index 0a7ff67caf1..de127bcc5ea 100644 --- a/docs/libcurl/curl_multi_get_handles.md +++ b/docs/libcurl/curl_multi_get_handles.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_get_handles Section: 3 diff --git a/docs/libcurl/curl_multi_info_read.md b/docs/libcurl/curl_multi_info_read.md index 23d515d8f81..f4b05bb73dd 100644 --- a/docs/libcurl/curl_multi_info_read.md +++ b/docs/libcurl/curl_multi_info_read.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_info_read Section: 3 diff --git a/docs/libcurl/curl_multi_init.md b/docs/libcurl/curl_multi_init.md index 0e91b57c178..c022c4416d6 100644 --- a/docs/libcurl/curl_multi_init.md +++ b/docs/libcurl/curl_multi_init.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_init Section: 3 diff --git a/docs/libcurl/curl_multi_perform.md b/docs/libcurl/curl_multi_perform.md index ecad22edf95..6c27eaf9cc8 100644 --- a/docs/libcurl/curl_multi_perform.md +++ b/docs/libcurl/curl_multi_perform.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_perform Section: 3 diff --git a/docs/libcurl/curl_multi_poll.md b/docs/libcurl/curl_multi_poll.md index b239f2836dc..7eadebc0eec 100644 --- a/docs/libcurl/curl_multi_poll.md +++ b/docs/libcurl/curl_multi_poll.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_poll Section: 3 diff --git a/docs/libcurl/curl_multi_remove_handle.md b/docs/libcurl/curl_multi_remove_handle.md index bb8ee1c7d30..da817cadb7f 100644 --- a/docs/libcurl/curl_multi_remove_handle.md +++ b/docs/libcurl/curl_multi_remove_handle.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_remove_handle Section: 3 diff --git a/docs/libcurl/curl_multi_setopt.md b/docs/libcurl/curl_multi_setopt.md index c0c8a3e6eeb..27f6dd4bec4 100644 --- a/docs/libcurl/curl_multi_setopt.md +++ b/docs/libcurl/curl_multi_setopt.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_setopt Section: 3 diff --git a/docs/libcurl/curl_multi_socket.md b/docs/libcurl/curl_multi_socket.md index ff465c359c7..fe376834b19 100644 --- a/docs/libcurl/curl_multi_socket.md +++ b/docs/libcurl/curl_multi_socket.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_socket Section: 3 diff --git a/docs/libcurl/curl_multi_socket_action.md b/docs/libcurl/curl_multi_socket_action.md index 8af17c83fb2..21880650753 100644 --- a/docs/libcurl/curl_multi_socket_action.md +++ b/docs/libcurl/curl_multi_socket_action.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_socket_action Section: 3 diff --git a/docs/libcurl/curl_multi_socket_all.md b/docs/libcurl/curl_multi_socket_all.md index ff465c359c7..fe376834b19 100644 --- a/docs/libcurl/curl_multi_socket_all.md +++ b/docs/libcurl/curl_multi_socket_all.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_socket Section: 3 diff --git a/docs/libcurl/curl_multi_strerror.md b/docs/libcurl/curl_multi_strerror.md index 5429e0e3487..590af13a3a5 100644 --- a/docs/libcurl/curl_multi_strerror.md +++ b/docs/libcurl/curl_multi_strerror.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_strerror Section: 3 diff --git a/docs/libcurl/curl_multi_timeout.md b/docs/libcurl/curl_multi_timeout.md index 83bad38455e..a8693d1c4fa 100644 --- a/docs/libcurl/curl_multi_timeout.md +++ b/docs/libcurl/curl_multi_timeout.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_timeout Section: 3 diff --git a/docs/libcurl/curl_multi_wait.md b/docs/libcurl/curl_multi_wait.md index 094ace386dd..526cef6bdaa 100644 --- a/docs/libcurl/curl_multi_wait.md +++ b/docs/libcurl/curl_multi_wait.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_wait Section: 3 diff --git a/docs/libcurl/curl_multi_wakeup.md b/docs/libcurl/curl_multi_wakeup.md index f6200c41e4d..fd9fa0569b8 100644 --- a/docs/libcurl/curl_multi_wakeup.md +++ b/docs/libcurl/curl_multi_wakeup.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_multi_wakeup Section: 3 diff --git a/docs/libcurl/curl_pushheader_byname.md b/docs/libcurl/curl_pushheader_byname.md index ecb031f9e95..b83ba55927a 100644 --- a/docs/libcurl/curl_pushheader_byname.md +++ b/docs/libcurl/curl_pushheader_byname.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_pushheader_byname Section: 3 diff --git a/docs/libcurl/curl_pushheader_bynum.md b/docs/libcurl/curl_pushheader_bynum.md index 537f06b1ce4..4ba20b673c0 100644 --- a/docs/libcurl/curl_pushheader_bynum.md +++ b/docs/libcurl/curl_pushheader_bynum.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_pushheader_bynum Section: 3 diff --git a/docs/libcurl/curl_share_cleanup.md b/docs/libcurl/curl_share_cleanup.md index f4220566da3..2f161149ba9 100644 --- a/docs/libcurl/curl_share_cleanup.md +++ b/docs/libcurl/curl_share_cleanup.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_share_cleanup Section: 3 diff --git a/docs/libcurl/curl_share_init.md b/docs/libcurl/curl_share_init.md index 553710727bd..6654f3c9b56 100644 --- a/docs/libcurl/curl_share_init.md +++ b/docs/libcurl/curl_share_init.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_share_init Section: 3 diff --git a/docs/libcurl/curl_share_setopt.md b/docs/libcurl/curl_share_setopt.md index 8caaaea9ad4..d21c1595fce 100644 --- a/docs/libcurl/curl_share_setopt.md +++ b/docs/libcurl/curl_share_setopt.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_share_setopt Section: 3 diff --git a/docs/libcurl/curl_share_strerror.md b/docs/libcurl/curl_share_strerror.md index 130d43b3bba..9e8ebe7272c 100644 --- a/docs/libcurl/curl_share_strerror.md +++ b/docs/libcurl/curl_share_strerror.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_share_strerror Section: 3 diff --git a/docs/libcurl/curl_slist_append.md b/docs/libcurl/curl_slist_append.md index 9773fd49416..2e8a54018ab 100644 --- a/docs/libcurl/curl_slist_append.md +++ b/docs/libcurl/curl_slist_append.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_slist_append Section: 3 diff --git a/docs/libcurl/curl_slist_free_all.md b/docs/libcurl/curl_slist_free_all.md index 928f306016f..1d73d7d71ee 100644 --- a/docs/libcurl/curl_slist_free_all.md +++ b/docs/libcurl/curl_slist_free_all.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_slist_free_all Section: 3 diff --git a/docs/libcurl/curl_strequal.md b/docs/libcurl/curl_strequal.md index 518faee6a23..76b08a978d7 100644 --- a/docs/libcurl/curl_strequal.md +++ b/docs/libcurl/curl_strequal.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_strequal Section: 3 diff --git a/docs/libcurl/curl_strnequal.md b/docs/libcurl/curl_strnequal.md index 518faee6a23..76b08a978d7 100644 --- a/docs/libcurl/curl_strnequal.md +++ b/docs/libcurl/curl_strnequal.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_strequal Section: 3 diff --git a/docs/libcurl/curl_unescape.md b/docs/libcurl/curl_unescape.md index 8ae9f508970..ad60150a381 100644 --- a/docs/libcurl/curl_unescape.md +++ b/docs/libcurl/curl_unescape.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_unescape Section: 3 diff --git a/docs/libcurl/curl_url.md b/docs/libcurl/curl_url.md index f71fb3580fe..3870073d615 100644 --- a/docs/libcurl/curl_url.md +++ b/docs/libcurl/curl_url.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_url Section: 3 diff --git a/docs/libcurl/curl_url_cleanup.md b/docs/libcurl/curl_url_cleanup.md index d0f85b69ca0..b64fc79e7a9 100644 --- a/docs/libcurl/curl_url_cleanup.md +++ b/docs/libcurl/curl_url_cleanup.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_url_cleanup Section: 3 diff --git a/docs/libcurl/curl_url_dup.md b/docs/libcurl/curl_url_dup.md index ea590ce836d..769a1c72dcb 100644 --- a/docs/libcurl/curl_url_dup.md +++ b/docs/libcurl/curl_url_dup.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_url_dup Section: 3 diff --git a/docs/libcurl/curl_url_get.md b/docs/libcurl/curl_url_get.md index 810e504c359..8722286faaa 100644 --- a/docs/libcurl/curl_url_get.md +++ b/docs/libcurl/curl_url_get.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_url_get Section: 3 diff --git a/docs/libcurl/curl_url_set.md b/docs/libcurl/curl_url_set.md index fe2f7ff9841..d02ec001879 100644 --- a/docs/libcurl/curl_url_set.md +++ b/docs/libcurl/curl_url_set.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_url_set Section: 3 diff --git a/docs/libcurl/curl_url_strerror.md b/docs/libcurl/curl_url_strerror.md index 26562aa2101..46971c65005 100644 --- a/docs/libcurl/curl_url_strerror.md +++ b/docs/libcurl/curl_url_strerror.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_url_strerror Section: 3 diff --git a/docs/libcurl/curl_version.md b/docs/libcurl/curl_version.md index 3a3cb359bf3..953252c2ca9 100644 --- a/docs/libcurl/curl_version.md +++ b/docs/libcurl/curl_version.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_version Section: 3 diff --git a/docs/libcurl/curl_version_info.md b/docs/libcurl/curl_version_info.md index 45e46a1b9e6..ded83910061 100644 --- a/docs/libcurl/curl_version_info.md +++ b/docs/libcurl/curl_version_info.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_version_info Section: 3 diff --git a/docs/libcurl/curl_ws_meta.md b/docs/libcurl/curl_ws_meta.md index 71fcb8b3174..49d987dae9c 100644 --- a/docs/libcurl/curl_ws_meta.md +++ b/docs/libcurl/curl_ws_meta.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_ws_meta Section: 3 diff --git a/docs/libcurl/curl_ws_recv.md b/docs/libcurl/curl_ws_recv.md index d801eddee20..e2b1b74ff45 100644 --- a/docs/libcurl/curl_ws_recv.md +++ b/docs/libcurl/curl_ws_recv.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_ws_recv Section: 3 diff --git a/docs/libcurl/curl_ws_send.md b/docs/libcurl/curl_ws_send.md index e521ff20aa6..f07a3ecc14b 100644 --- a/docs/libcurl/curl_ws_send.md +++ b/docs/libcurl/curl_ws_send.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: curl_ws_send Section: 3 diff --git a/docs/libcurl/libcurl-easy.md b/docs/libcurl/libcurl-easy.md index f456c97bec8..7dbc475eca4 100644 --- a/docs/libcurl/libcurl-easy.md +++ b/docs/libcurl/libcurl-easy.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl Section: 3 diff --git a/docs/libcurl/libcurl-env-dbg.md b/docs/libcurl/libcurl-env-dbg.md index 21ed3bf25ae..6a22a885f16 100644 --- a/docs/libcurl/libcurl-env-dbg.md +++ b/docs/libcurl/libcurl-env-dbg.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl-env-dbg Section: 3 diff --git a/docs/libcurl/libcurl-env.md b/docs/libcurl/libcurl-env.md index 30a57ff1acb..4df328ecdc7 100644 --- a/docs/libcurl/libcurl-env.md +++ b/docs/libcurl/libcurl-env.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl-env Section: 3 diff --git a/docs/libcurl/libcurl-errors.md b/docs/libcurl/libcurl-errors.md index eb75753b0fe..0d4ce51138e 100644 --- a/docs/libcurl/libcurl-errors.md +++ b/docs/libcurl/libcurl-errors.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl-errors Section: 3 diff --git a/docs/libcurl/libcurl-multi.md b/docs/libcurl/libcurl-multi.md index 3acd13ea638..e037394d925 100644 --- a/docs/libcurl/libcurl-multi.md +++ b/docs/libcurl/libcurl-multi.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl-multi Section: 3 diff --git a/docs/libcurl/libcurl-security.md b/docs/libcurl/libcurl-security.md index 84103b9ab94..0d71ca7b142 100644 --- a/docs/libcurl/libcurl-security.md +++ b/docs/libcurl/libcurl-security.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl-security Section: 3 diff --git a/docs/libcurl/libcurl-share.md b/docs/libcurl/libcurl-share.md index e244b9726d6..2d33f71eb0f 100644 --- a/docs/libcurl/libcurl-share.md +++ b/docs/libcurl/libcurl-share.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl-share Section: 3 diff --git a/docs/libcurl/libcurl-thread.md b/docs/libcurl/libcurl-thread.md index b3e9ecf82a9..6924eb355f3 100644 --- a/docs/libcurl/libcurl-thread.md +++ b/docs/libcurl/libcurl-thread.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl-thread Section: 3 diff --git a/docs/libcurl/libcurl-tutorial.md b/docs/libcurl/libcurl-tutorial.md index c5e2ebca1a5..54607af7206 100644 --- a/docs/libcurl/libcurl-tutorial.md +++ b/docs/libcurl/libcurl-tutorial.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl-tutorial Section: 3 diff --git a/docs/libcurl/libcurl-url.md b/docs/libcurl/libcurl-url.md index c7a9ca2bb04..c8d3f0b3c06 100644 --- a/docs/libcurl/libcurl-url.md +++ b/docs/libcurl/libcurl-url.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl Section: 3 diff --git a/docs/libcurl/libcurl-ws.md b/docs/libcurl/libcurl-ws.md index 5ba05d8faef..1668af44315 100644 --- a/docs/libcurl/libcurl-ws.md +++ b/docs/libcurl/libcurl-ws.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl Section: 3 diff --git a/docs/libcurl/libcurl.md b/docs/libcurl/libcurl.md index 1f7c97eaab0..f8ff15eb860 100644 --- a/docs/libcurl/libcurl.md +++ b/docs/libcurl/libcurl.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: libcurl Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md index 7e106ed0bc8..e041ff800c6 100644 --- a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md +++ b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_ACTIVESOCKET Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md index 17fb465801a..474c033c268 100644 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_APPCONNECT_TIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md index cc4f2b8589f..c2f9825b7b3 100644 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_APPCONNECT_TIME_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CAINFO.md b/docs/libcurl/opts/CURLINFO_CAINFO.md index 44b253967da..0cc3c0cd0da 100644 --- a/docs/libcurl/opts/CURLINFO_CAINFO.md +++ b/docs/libcurl/opts/CURLINFO_CAINFO.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CAINFO Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CAPATH.md b/docs/libcurl/opts/CURLINFO_CAPATH.md index 46499e7f675..c1f31578049 100644 --- a/docs/libcurl/opts/CURLINFO_CAPATH.md +++ b/docs/libcurl/opts/CURLINFO_CAPATH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CAPATH Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.md b/docs/libcurl/opts/CURLINFO_CERTINFO.md index d9cbc9306d9..a4125632972 100644 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.md +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CERTINFO Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md index aca04f1c9b9..38cd1ce2f3c 100644 --- a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md +++ b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONDITION_UNMET Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md index 1fde7669993..b1c58ad9e7a 100644 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONNECT_TIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md index cd72cdd077d..158b58d955a 100644 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONNECT_TIME_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONN_ID.md b/docs/libcurl/opts/CURLINFO_CONN_ID.md index d4791b42caf..8b6c21bc4d3 100644 --- a/docs/libcurl/opts/CURLINFO_CONN_ID.md +++ b/docs/libcurl/opts/CURLINFO_CONN_ID.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONN_ID Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md index 1e01419bdb1..155759b2b2a 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONTENT_LENGTH_DOWNLOAD Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md index 15016c84c13..fa4acf815dc 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONTENT_LENGTH_DOWNLOAD_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md index c90e19e72cb..24c26dbfb5a 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONTENT_LENGTH_UPLOAD Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md index 319a3345e86..4fe942c2735 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONTENT_LENGTH_UPLOAD_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md index b8745725109..b9bc4107dd6 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_CONTENT_TYPE Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_COOKIELIST.md b/docs/libcurl/opts/CURLINFO_COOKIELIST.md index 60ac0f036a6..bc01bbfe902 100644 --- a/docs/libcurl/opts/CURLINFO_COOKIELIST.md +++ b/docs/libcurl/opts/CURLINFO_COOKIELIST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_COOKIELIST Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md index da2e2a016fd..98ebde70e30 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_EFFECTIVE_METHOD Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md index 268ff2c67e8..8671535e03b 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_EFFECTIVE_URL Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.md b/docs/libcurl/opts/CURLINFO_FILETIME.md index 77ef534b414..59a61840e17 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME.md +++ b/docs/libcurl/opts/CURLINFO_FILETIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_FILETIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.md b/docs/libcurl/opts/CURLINFO_FILETIME_T.md index 62c5f3cb040..2f48b12e298 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME_T.md +++ b/docs/libcurl/opts/CURLINFO_FILETIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_FILETIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md index 344e1f17432..6cbd3c98603 100644 --- a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md +++ b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_FTP_ENTRY_PATH Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md index 67ccfc232d9..81ac85d6805 100644 --- a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md +++ b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_HEADER_SIZE Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md index 574e0a52b3e..6eed5bfe90f 100644 --- a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md +++ b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_HTTPAUTH_AVAIL Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md index ee3f0f65c7d..94cd449139d 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md +++ b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_HTTP_CONNECTCODE Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md index 994d7712c1c..71c318198a8 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md +++ b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_HTTP_VERSION Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_LASTSOCKET.md b/docs/libcurl/opts/CURLINFO_LASTSOCKET.md index b1619ebdbbd..da698172d32 100644 --- a/docs/libcurl/opts/CURLINFO_LASTSOCKET.md +++ b/docs/libcurl/opts/CURLINFO_LASTSOCKET.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_LASTSOCKET Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md index e70d0cf0419..9584243e580 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md +++ b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_LOCAL_IP Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md index 055fc2ee060..d7ae9a9a687 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md +++ b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_LOCAL_PORT Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md index 8cf425e0ffd..68e1aa9b013 100644 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_NAMELOOKUP_TIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md index a3fd4dd84f6..b97b584d3eb 100644 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_NAMELOOKUP_TIME_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md index 5127a0a32a7..053ab6ff5bf 100644 --- a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md +++ b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_NUM_CONNECTS Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_OS_ERRNO.md b/docs/libcurl/opts/CURLINFO_OS_ERRNO.md index 3fb69b43cfb..61c3348ad7b 100644 --- a/docs/libcurl/opts/CURLINFO_OS_ERRNO.md +++ b/docs/libcurl/opts/CURLINFO_OS_ERRNO.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_OS_ERRNO Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md index 8eda23a3c67..5dfd6c3f124 100644 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PRETRANSFER_TIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md index 50c515f3aa4..fb9be877328 100644 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PRETRANSFER_TIME_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md index 115113f3fd5..c5692f12667 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PRIMARY_IP Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md index 3d90b64ed9f..43ef2676311 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PRIMARY_PORT Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PRIVATE.md b/docs/libcurl/opts/CURLINFO_PRIVATE.md index 127049f7ede..42c96f0ea80 100644 --- a/docs/libcurl/opts/CURLINFO_PRIVATE.md +++ b/docs/libcurl/opts/CURLINFO_PRIVATE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PRIVATE Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PROTOCOL.md b/docs/libcurl/opts/CURLINFO_PROTOCOL.md index 9dfb2970fde..d15457b9d43 100644 --- a/docs/libcurl/opts/CURLINFO_PROTOCOL.md +++ b/docs/libcurl/opts/CURLINFO_PROTOCOL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PROTOCOL Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md index 0e9dbdcb505..f29f9245e92 100644 --- a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md +++ b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PROXYAUTH_AVAIL Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md index 01113c74075..d16668d8f4f 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md +++ b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PROXY_ERROR Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md index d97f5e78e48..f559badfa9f 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md +++ b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_PROXY_SSL_VERIFYRESULT Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md index 00454e75255..0fffb728560 100644 --- a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_QUEUE_TIME_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md index aa75bdb2205..e0749029fdb 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_REDIRECT_COUNT Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md index 26d9af2a0b0..6f742aba935 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_REDIRECT_TIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md index f4ee710895b..4b48a4f46c0 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_REDIRECT_TIME_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md index 8d7fc5c107d..1954351de34 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_REDIRECT_URL Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_REFERER.md b/docs/libcurl/opts/CURLINFO_REFERER.md index fabc652a7fd..fcb719e9c9d 100644 --- a/docs/libcurl/opts/CURLINFO_REFERER.md +++ b/docs/libcurl/opts/CURLINFO_REFERER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_REFERER Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md index 444f4ec236d..dd1f6011ca6 100644 --- a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md +++ b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_REQUEST_SIZE Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md index 43cf8378dad..72cc1449fe2 100644 --- a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md +++ b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_RESPONSE_CODE Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md index adc12007768..12e30375dfc 100644 --- a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md +++ b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_RETRY_AFTER Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md index 8b515b42799..68796760580 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_RTSP_CLIENT_CSEQ Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md index 9eb813aa4d4..c316f37ca81 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_RTSP_CSEQ_RECV Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md index 7826f8a3cfc..28bf6cd2c14 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_RTSP_SERVER_CSEQ Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md index 402a122f88c..48ebe207702 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_RTSP_SESSION_ID Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SCHEME.md b/docs/libcurl/opts/CURLINFO_SCHEME.md index db567fc98a7..c3f59a14197 100644 --- a/docs/libcurl/opts/CURLINFO_SCHEME.md +++ b/docs/libcurl/opts/CURLINFO_SCHEME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SCHEME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md index ff19908cfaf..e62f971af8e 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SIZE_DOWNLOAD Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md index f5468db9d1f..5603f5a89e0 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SIZE_DOWNLOAD_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md index 175fe718d18..19c594d30ab 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SIZE_UPLOAD Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md index 29874f9fdf1..66954a2de80 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SIZE_UPLOAD_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md index fe0766939c9..6ffef34c221 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SPEED_DOWNLOAD Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md index c8bc2f8671d..b801625444f 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SPEED_DOWNLOAD_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md index 11ce92923e9..ef9105babc9 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SPEED_UPLOAD Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md index 178e9a5269e..4398fc2ee11 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SPEED_UPLOAD_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md index 9dbb0a1d157..7f6127952f5 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md +++ b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SSL_ENGINES Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md index fdc38f016ee..270dacba739 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md +++ b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_SSL_VERIFYRESULT Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md index d7c1f0884bb..5fc6fac8c3f 100644 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_STARTTRANSFER_TIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md index 481c7f5bd62..814658c9b88 100644 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_STARTTRANSFER_TIME_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md index 98cc2d67c55..490e0bc2611 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_TLS_SESSION Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md index 4fc246adf71..6a54f01f798 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_TLS_SSL_PTR Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md index c6af1694ed6..8859f57f8dc 100644 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_TOTAL_TIME Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md index 488d5d3aacb..cbd8ddda3e8 100644 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_TOTAL_TIME_T Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_USED_PROXY.md b/docs/libcurl/opts/CURLINFO_USED_PROXY.md index 98fafa78f1b..9fc6836a0ac 100644 --- a/docs/libcurl/opts/CURLINFO_USED_PROXY.md +++ b/docs/libcurl/opts/CURLINFO_USED_PROXY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_USED_PROXY Section: 3 diff --git a/docs/libcurl/opts/CURLINFO_XFER_ID.md b/docs/libcurl/opts/CURLINFO_XFER_ID.md index b32a46b1238..68ec3e8eff7 100644 --- a/docs/libcurl/opts/CURLINFO_XFER_ID.md +++ b/docs/libcurl/opts/CURLINFO_XFER_ID.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLINFO_XFER_ID Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md index 127f4dd062b..5b8c606273f 100644 --- a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md +++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md index d3e7abaf00f..b550796990e 100644 --- a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md +++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md index 9a5457fa5ce..fbfa0c8b555 100644 --- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md +++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_MAXCONNECTS Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md index 2471994441a..a8e23f8ca0f 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_MAX_CONCURRENT_STREAMS Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md index 75c4768f6ec..3ccfe87f812 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_MAX_HOST_CONNECTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md index bad638e5f1a..fea5d513f67 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_MAX_PIPELINE_LENGTH Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md index 859bb2ad564..8cac3702bdd 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_MAX_TOTAL_CONNECTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.md b/docs/libcurl/opts/CURLMOPT_PIPELINING.md index 3df71b54fa5..2d171df3221 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_PIPELINING Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md index 226700806f7..87eb2c45bb2 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_PIPELINING_SERVER_BL Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md index a212c4f6341..00491ed8277 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_PIPELINING_SITE_BL Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md index e8db6c8655e..f634d3556d5 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md +++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_PUSHDATA Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md index 2f08e72bd9c..9ef51d50fe6 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_PUSHFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md index 20c3feeb266..1b4814c4bb8 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_SOCKETDATA Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index 5b34db5f374..207819f983b 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_SOCKETFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md index 08a940b9771..1632c720e5a 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md +++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_TIMERDATA Section: 3 diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md index 83a8fe7e08e..fa73266cbe5 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLMOPT_TIMERFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md index 33d2b7bcc1d..cd71bb19764 100644 --- a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md +++ b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ABSTRACT_UNIX_SOCKET Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md index 77615d886df..b51f45163cd 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ACCEPTTIMEOUT_MS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md index 9bba40d9d02..50e7eba942c 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md +++ b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ACCEPT_ENCODING Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md index 78526bd39f6..dc9f08a8602 100644 --- a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md +++ b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ADDRESS_SCOPE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC.md b/docs/libcurl/opts/CURLOPT_ALTSVC.md index e0db681b8d7..09f89a32145 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC.md +++ b/docs/libcurl/opts/CURLOPT_ALTSVC.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ALTSVC Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md index 538fc801aeb..b17e0c4615a 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md +++ b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ALTSVC_CTRL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_APPEND.md b/docs/libcurl/opts/CURLOPT_APPEND.md index d507c3812e8..a1d5176cb1e 100644 --- a/docs/libcurl/opts/CURLOPT_APPEND.md +++ b/docs/libcurl/opts/CURLOPT_APPEND.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_APPEND Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.md b/docs/libcurl/opts/CURLOPT_AUTOREFERER.md index d201a71ad6e..c9a4ce1fe2e 100644 --- a/docs/libcurl/opts/CURLOPT_AUTOREFERER.md +++ b/docs/libcurl/opts/CURLOPT_AUTOREFERER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_AUTOREFERER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md index e19741aa6df..a9e1acd25d0 100644 --- a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_AWS_SIGV4 Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md index b4759ea6534..3a2ddd8e345 100644 --- a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_BUFFERSIZE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.md b/docs/libcurl/opts/CURLOPT_CAINFO.md index c46073ff850..6955aaa6182 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CAINFO Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md index be30446ff23..4566eabc4b8 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CAINFO_BLOB Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.md b/docs/libcurl/opts/CURLOPT_CAPATH.md index ff1362f5232..3d6c3af64de 100644 --- a/docs/libcurl/opts/CURLOPT_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_CAPATH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CAPATH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md index ef52f976dd7..79133e81e90 100644 --- a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CA_CACHE_TIMEOUT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.md b/docs/libcurl/opts/CURLOPT_CERTINFO.md index a69e1e9503c..caaa9ea1900 100644 --- a/docs/libcurl/opts/CURLOPT_CERTINFO.md +++ b/docs/libcurl/opts/CURLOPT_CERTINFO.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CERTINFO Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md index a208c9bbe57..d349f2dbfd5 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CHUNK_BGN_FUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md index 3640ec8df15..eca85c873d8 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CHUNK_DATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md index 2d67afe20cf..0b228a73cce 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CHUNK_END_FUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md index 2dd74777b12..c15c51816e8 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CLOSESOCKETDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index e93e28c1efb..4e9f25579a9 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CLOSESOCKETFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md index 07513fdeea2..798c290bc8e 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CONNECTTIMEOUT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md index b8508e7de52..793b370126d 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CONNECTTIMEOUT_MS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md index 3312936afeb..ccb00fd23b2 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md +++ b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CONNECT_ONLY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_TO.md b/docs/libcurl/opts/CURLOPT_CONNECT_TO.md index 8aea3ffa947..ed0db591dbd 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_TO.md +++ b/docs/libcurl/opts/CURLOPT_CONNECT_TO.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CONNECT_TO Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md index 7460a1e9050..46b935dd734 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CONV_FROM_NETWORK_FUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md index 1f7d704e9c4..37abfc5b965 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CONV_FROM_UTF8_FUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md index 13d9da86755..97a8a6c1bed 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CONV_TO_NETWORK_FUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.md b/docs/libcurl/opts/CURLOPT_COOKIE.md index 4e2955d8aa4..5d34072af77 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIE.md +++ b/docs/libcurl/opts/CURLOPT_COOKIE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_COOKIE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.md b/docs/libcurl/opts/CURLOPT_COOKIEFILE.md index 87dce1b1aec..fa88c14db2c 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.md +++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_COOKIEFILE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.md b/docs/libcurl/opts/CURLOPT_COOKIEJAR.md index ec0d273eb15..05196abc4ba 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEJAR.md +++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_COOKIEJAR Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.md b/docs/libcurl/opts/CURLOPT_COOKIELIST.md index 16298775ca0..31fb8d24065 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.md +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_COOKIELIST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_COOKIESESSION.md b/docs/libcurl/opts/CURLOPT_COOKIESESSION.md index 6f49f025c32..33c8a2f5524 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIESESSION.md +++ b/docs/libcurl/opts/CURLOPT_COOKIESESSION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_COOKIESESSION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md index 911e081811a..430c53543ef 100644 --- a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md +++ b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_COPYPOSTFIELDS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CRLF.md b/docs/libcurl/opts/CURLOPT_CRLF.md index 1766c331281..b712902c0d0 100644 --- a/docs/libcurl/opts/CURLOPT_CRLF.md +++ b/docs/libcurl/opts/CURLOPT_CRLF.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CRLF Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.md b/docs/libcurl/opts/CURLOPT_CRLFILE.md index b800f8ce337..486383bf3ef 100644 --- a/docs/libcurl/opts/CURLOPT_CRLFILE.md +++ b/docs/libcurl/opts/CURLOPT_CRLFILE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CRLFILE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CURLU.md b/docs/libcurl/opts/CURLOPT_CURLU.md index a3eeb5c9b7d..53146bafe56 100644 --- a/docs/libcurl/opts/CURLOPT_CURLU.md +++ b/docs/libcurl/opts/CURLOPT_CURLU.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CURLU Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md index c4d4ec210e9..eda31d1e781 100644 --- a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md +++ b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_CUSTOMREQUEST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.md b/docs/libcurl/opts/CURLOPT_DEBUGDATA.md index cac58d99dff..ac924f79d7a 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGDATA.md +++ b/docs/libcurl/opts/CURLOPT_DEBUGDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DEBUGDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md index 1acf963ca49..a199648c13c 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DEBUGFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md index 88468f718f9..1ef732b6484 100644 --- a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md +++ b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DEFAULT_PROTOCOL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md index 29635622c8b..abeb6473d65 100644 --- a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md +++ b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DIRLISTONLY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md index 6c657169d74..ee06610ee0e 100644 --- a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md +++ b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DISALLOW_USERNAME_IN_URL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md index 3a24d509c6f..274dae6b1de 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DNS_CACHE_TIMEOUT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md index 3a9c73a69e1..f985adcc4f6 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md +++ b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DNS_INTERFACE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md index 69af83b6b05..2e6bf632981 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DNS_LOCAL_IP4 Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md index fb04ee899f1..babaf254b62 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DNS_LOCAL_IP6 Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md index 998257c7989..892817302fe 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md +++ b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DNS_SERVERS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md index f15abc9c74b..4224a592206 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md +++ b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DNS_SHUFFLE_ADDRESSES Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md index dfbc2291686..7b3193784dc 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md +++ b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DNS_USE_GLOBAL_CACHE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md index 051e6be530b..ed00377283c 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DOH_SSL_VERIFYHOST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md index e2a5a5e69c5..39caf19534a 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DOH_SSL_VERIFYPEER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md index 19489986ba8..ccc7b5d3d35 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DOH_SSL_VERIFYSTATUS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_DOH_URL.md b/docs/libcurl/opts/CURLOPT_DOH_URL.md index a2e46b4c0b6..22a6c7af667 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_URL.md +++ b/docs/libcurl/opts/CURLOPT_DOH_URL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_DOH_URL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md index a472f5ea5a8..d4ab6c614c3 100644 --- a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md +++ b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_EGDSOCKET Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md index ed5d361ef88..8caeec8b389 100644 --- a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md +++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ERRORBUFFER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md index 9458cfc63d5..41cc59a82d9 100644 --- a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_EXPECT_100_TIMEOUT_MS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.md b/docs/libcurl/opts/CURLOPT_FAILONERROR.md index 5eedf840f5b..894a5b46be8 100644 --- a/docs/libcurl/opts/CURLOPT_FAILONERROR.md +++ b/docs/libcurl/opts/CURLOPT_FAILONERROR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FAILONERROR Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FILETIME.md b/docs/libcurl/opts/CURLOPT_FILETIME.md index 01344910598..340f584d3a7 100644 --- a/docs/libcurl/opts/CURLOPT_FILETIME.md +++ b/docs/libcurl/opts/CURLOPT_FILETIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FILETIME Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md index 48b60723ab6..d56b9922edd 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FNMATCH_DATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md index 8ed13bfe6c8..5f087d7c1bd 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FNMATCH_FUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md index 9309dff2189..af3ddbec640 100644 --- a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md +++ b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FOLLOWLOCATION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md index 0e8a20607c6..a266863e595 100644 --- a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md +++ b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FORBID_REUSE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md index ccb85270d8f..aaadf345ed0 100644 --- a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md +++ b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FRESH_CONNECT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.md b/docs/libcurl/opts/CURLOPT_FTPPORT.md index 8e8710b0736..fac0ebd191f 100644 --- a/docs/libcurl/opts/CURLOPT_FTPPORT.md +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTPPORT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md index a6ddf2f7ac6..6097d43d7be 100644 --- a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md +++ b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTPSSLAUTH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md index 575fb196618..70061f0d9b6 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md +++ b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_ACCOUNT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md index 70f451d8426..a24b5326d0a 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md +++ b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_ALTERNATIVE_TO_USER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md index 07b6f68fd1e..891feb18979 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md +++ b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_CREATE_MISSING_DIRS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md index 34b55d659c0..31c4cfb174a 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md +++ b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_FILEMETHOD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md index bea622ac794..5d8e8cec1cf 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md +++ b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_SKIP_PASV_IP Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md index 71947c36ede..ea23e59672b 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md +++ b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_SSL_CCC Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md index 644f51aa9bf..a823e4d8db0 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_USE_EPRT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md index 985ca8ba3c1..9ac30fe7293 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_USE_EPSV Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md index f81ca4cf08b..a43cf10a507 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_FTP_USE_PRET Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md index 01c1d50622a..29245bd7063 100644 --- a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md +++ b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_GSSAPI_DELEGATION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md index 23299c736d9..87b1dee8522 100644 --- a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md index 51eb2656c5f..7fe1647c06e 100644 --- a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md +++ b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HAPROXYPROTOCOL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md index ac0da3a1ccc..19f3cca2f88 100644 --- a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md +++ b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HAPROXY_CLIENT_IP Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HEADER.md b/docs/libcurl/opts/CURLOPT_HEADER.md index d5e272ac548..ed3d88798bd 100644 --- a/docs/libcurl/opts/CURLOPT_HEADER.md +++ b/docs/libcurl/opts/CURLOPT_HEADER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HEADER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HEADERDATA.md b/docs/libcurl/opts/CURLOPT_HEADERDATA.md index 7f056361f19..83109af8231 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERDATA.md +++ b/docs/libcurl/opts/CURLOPT_HEADERDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HEADERDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md index eb14cdd6f80..41d02c3a620 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HEADERFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HEADEROPT.md b/docs/libcurl/opts/CURLOPT_HEADEROPT.md index bb3bcf41ccf..0b1d8b66460 100644 --- a/docs/libcurl/opts/CURLOPT_HEADEROPT.md +++ b/docs/libcurl/opts/CURLOPT_HEADEROPT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HEADEROPT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HSTS.md b/docs/libcurl/opts/CURLOPT_HSTS.md index 7c15edabae1..fe7106cad48 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS.md +++ b/docs/libcurl/opts/CURLOPT_HSTS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HSTS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md index 8fbb888d357..0d391318a4e 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md +++ b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HSTSREADDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md index cc221638c7e..763b81dce42 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HSTSREADFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md index b4486d7a3be..f871f1c495e 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HSTSWRITEDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md index ede35218cba..9d0dd3013ac 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HSTSWRITEFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md index d60e58f0f12..4a87adc54bc 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md +++ b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HSTS_CTRL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md index d3594926f5c..447fb6fc3c0 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md +++ b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTP09_ALLOWED Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md index b48faf6038e..167c26b2940 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md +++ b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTP200ALIASES Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.md b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md index 2adacdd3f50..cafa39cc58a 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.md +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTPAUTH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.md b/docs/libcurl/opts/CURLOPT_HTTPGET.md index d8b024d8eb4..9be9321775a 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPGET.md +++ b/docs/libcurl/opts/CURLOPT_HTTPGET.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTPGET Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.md b/docs/libcurl/opts/CURLOPT_HTTPHEADER.md index 0ccda775ef3..25895f23ab3 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.md +++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTPHEADER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.md b/docs/libcurl/opts/CURLOPT_HTTPPOST.md index 6fdfc170701..890bd8f6ff0 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.md +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTPPOST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md index bd67640b491..4f12811ae1c 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md +++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTPPROXYTUNNEL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md index b48c0f9fbdf..e0f010d66a0 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTP_CONTENT_DECODING Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md index ba83acaae1a..3c4e06be467 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTP_TRANSFER_DECODING Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md index 69dc48c611d..cab71fd65e0 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_HTTP_VERSION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md index d12b4912017..93ea4b6d2ce 100644 --- a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md +++ b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_IGNORE_CONTENT_LENGTH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.md b/docs/libcurl/opts/CURLOPT_INFILESIZE.md index eab597ff488..0d7924eab64 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE.md +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_INFILESIZE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md index 5f8a3386ff8..119d2322c16 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_INFILESIZE_LARGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.md b/docs/libcurl/opts/CURLOPT_INTERFACE.md index 24927fdf822..0cd3d44cf9a 100644 --- a/docs/libcurl/opts/CURLOPT_INTERFACE.md +++ b/docs/libcurl/opts/CURLOPT_INTERFACE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_INTERFACE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md index 64311f83cc2..7bb6059ad43 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_INTERLEAVEDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md index 5f8e999df94..758192f110d 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_INTERLEAVEFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_IOCTLDATA.md b/docs/libcurl/opts/CURLOPT_IOCTLDATA.md index 2490fbc7fcb..f34a35338c4 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLDATA.md +++ b/docs/libcurl/opts/CURLOPT_IOCTLDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_IOCTLDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md index 8804ae57845..a3e120f3a9a 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_IOCTLFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md index 9eeabe84ed3..a12629614bb 100644 --- a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md +++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_IPRESOLVE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md index 9b35d5d79c6..5b227a9d703 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ISSUERCERT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md index 4832f412567..26641312fb0 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_ISSUERCERT_BLOB Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md index e8471957abb..0c8b8a8ca41 100644 --- a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md +++ b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_KEEP_SENDING_ON_ERROR Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md index 7407f093934..ddc8546f92e 100644 --- a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md +++ b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_KEYPASSWD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_KRBLEVEL.md b/docs/libcurl/opts/CURLOPT_KRBLEVEL.md index cb8e276891d..a91f67e13a3 100644 --- a/docs/libcurl/opts/CURLOPT_KRBLEVEL.md +++ b/docs/libcurl/opts/CURLOPT_KRBLEVEL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_KRBLEVEL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORT.md b/docs/libcurl/opts/CURLOPT_LOCALPORT.md index 25a21c15e5e..0113e43c08b 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORT.md +++ b/docs/libcurl/opts/CURLOPT_LOCALPORT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_LOCALPORT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md index 52002079089..cd84649b0dd 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md +++ b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_LOCALPORTRANGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md index a57b446902b..8a4e7ebaf23 100644 --- a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_LOGIN_OPTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md index 99df9faed10..64fa45ed417 100644 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_LOW_SPEED_LIMIT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md index a3a9ef1ffef..e7aa94cee9a 100644 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_LOW_SPEED_TIME Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md index 172656defac..a3ef13b5a58 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAIL_AUTH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md index 5e83dbab3be..431d1b52bda 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAIL_FROM Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md index 47065d30d20..40f42cc3717 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAIL_RCPT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md index cf595e26b4b..83183ee1a7d 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAIL_RCPT_ALLOWFAILS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md index 3d0a9cb2a46..3b84dfdc056 100644 --- a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md +++ b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAXAGE_CONN Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md index 807df4da1fd..729fa2bae1c 100644 --- a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md +++ b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAXCONNECTS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md index a90c94b7dc3..6203bd05e29 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAXFILESIZE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md index 041282f4190..f750c43306b 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAXFILESIZE_LARGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md index f731ad9990e..429cf3945c5 100644 --- a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md +++ b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAXLIFETIME_CONN Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.md b/docs/libcurl/opts/CURLOPT_MAXREDIRS.md index 5ace67e42e7..136f9a6db80 100644 --- a/docs/libcurl/opts/CURLOPT_MAXREDIRS.md +++ b/docs/libcurl/opts/CURLOPT_MAXREDIRS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAXREDIRS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md index 646f301e44f..26080877d60 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAX_RECV_SPEED_LARGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md index 8b709ccb726..e8cf5081d23 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MAX_SEND_SPEED_LARGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.md b/docs/libcurl/opts/CURLOPT_MIMEPOST.md index 588b7e80328..f681c2a9092 100644 --- a/docs/libcurl/opts/CURLOPT_MIMEPOST.md +++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MIMEPOST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md index 747eab24dfb..7f97d78dfc0 100644 --- a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_MIME_OPTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_NETRC.md b/docs/libcurl/opts/CURLOPT_NETRC.md index 580cdcd3b41..023676d0ae8 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.md +++ b/docs/libcurl/opts/CURLOPT_NETRC.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_NETRC Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_NETRC_FILE.md b/docs/libcurl/opts/CURLOPT_NETRC_FILE.md index 62fe7a52152..cf27945e7a3 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC_FILE.md +++ b/docs/libcurl/opts/CURLOPT_NETRC_FILE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_NETRC_FILE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md index bb302d42bd0..733a042f7f5 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md +++ b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_NEW_DIRECTORY_PERMS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md index dd12c0bbdf1..f79a1937d74 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md +++ b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_NEW_FILE_PERMS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.md b/docs/libcurl/opts/CURLOPT_NOBODY.md index 9d63154c9d3..2b7f8967b43 100644 --- a/docs/libcurl/opts/CURLOPT_NOBODY.md +++ b/docs/libcurl/opts/CURLOPT_NOBODY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_NOBODY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_NOPROGRESS.md b/docs/libcurl/opts/CURLOPT_NOPROGRESS.md index e2845a96fcd..14478cf5423 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROGRESS.md +++ b/docs/libcurl/opts/CURLOPT_NOPROGRESS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_NOPROGRESS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.md b/docs/libcurl/opts/CURLOPT_NOPROXY.md index 9bb396548ae..f5416174927 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROXY.md +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_NOPROXY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.md b/docs/libcurl/opts/CURLOPT_NOSIGNAL.md index 50ae65ccade..6ed291dbea5 100644 --- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.md +++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_NOSIGNAL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md index f3e7ef85503..20446500567 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_OPENSOCKETDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md index 125ccff6887..a5a101aae40 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_OPENSOCKETFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PASSWORD.md index 9849802d12b..2551c46a45d 100644 --- a/docs/libcurl/opts/CURLOPT_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PASSWORD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PASSWORD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md index 49946917243..7f013f0b887 100644 --- a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md +++ b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PATH_AS_IS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md index 922e2a6d6b7..9d563195889 100644 --- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PINNEDPUBLICKEY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.md b/docs/libcurl/opts/CURLOPT_PIPEWAIT.md index 1be844dd042..0d7defa8d82 100644 --- a/docs/libcurl/opts/CURLOPT_PIPEWAIT.md +++ b/docs/libcurl/opts/CURLOPT_PIPEWAIT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PIPEWAIT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PORT.md b/docs/libcurl/opts/CURLOPT_PORT.md index 42dc80133b2..1cd40655b55 100644 --- a/docs/libcurl/opts/CURLOPT_PORT.md +++ b/docs/libcurl/opts/CURLOPT_PORT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PORT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_POST.md b/docs/libcurl/opts/CURLOPT_POST.md index 96fcd42de17..1e605eaeb09 100644 --- a/docs/libcurl/opts/CURLOPT_POST.md +++ b/docs/libcurl/opts/CURLOPT_POST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_POST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md index 409e4100afe..da71ecc5250 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_POSTFIELDS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md index d086809cba3..41648706b09 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_POSTFIELDSIZE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md index 36fc0ff959a..4f2c5ea3676 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_POSTFIELDSIZE_LARGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md index 585d20619fc..b8c41a83979 100644 --- a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md +++ b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_POSTQUOTE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_POSTREDIR.md b/docs/libcurl/opts/CURLOPT_POSTREDIR.md index 0ca04a98cb3..b25e335709e 100644 --- a/docs/libcurl/opts/CURLOPT_POSTREDIR.md +++ b/docs/libcurl/opts/CURLOPT_POSTREDIR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_POSTREDIR Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PREQUOTE.md b/docs/libcurl/opts/CURLOPT_PREQUOTE.md index e5192039dc7..129cd6c8e3f 100644 --- a/docs/libcurl/opts/CURLOPT_PREQUOTE.md +++ b/docs/libcurl/opts/CURLOPT_PREQUOTE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PREQUOTE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PREREQDATA.md b/docs/libcurl/opts/CURLOPT_PREREQDATA.md index 14ba8e302fe..c3b351d0516 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQDATA.md +++ b/docs/libcurl/opts/CURLOPT_PREREQDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PREREQDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md index 2c334d94a96..4df94cccde1 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PREREQFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PRE_PROXY.md b/docs/libcurl/opts/CURLOPT_PRE_PROXY.md index 1afe831e3ae..252abfbc23c 100644 --- a/docs/libcurl/opts/CURLOPT_PRE_PROXY.md +++ b/docs/libcurl/opts/CURLOPT_PRE_PROXY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PRE_PROXY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PRIVATE.md b/docs/libcurl/opts/CURLOPT_PRIVATE.md index 571a681b9d9..969f8584327 100644 --- a/docs/libcurl/opts/CURLOPT_PRIVATE.md +++ b/docs/libcurl/opts/CURLOPT_PRIVATE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PRIVATE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md index 276bee82743..01e006d4840 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md +++ b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROGRESSDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md index 19d84c88900..88e5b189b4c 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROGRESSFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.md b/docs/libcurl/opts/CURLOPT_PROTOCOLS.md index a4d1a5a7cd3..b9258892c5f 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS.md +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROTOCOLS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md index 9da056d2394..cc13c529a49 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROTOCOLS_STR Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY.md b/docs/libcurl/opts/CURLOPT_PROXY.md index 89c22df9bcd..fdc9878092f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.md b/docs/libcurl/opts/CURLOPT_PROXYAUTH.md index 8e6dc093b5e..b52346255d6 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYAUTH.md +++ b/docs/libcurl/opts/CURLOPT_PROXYAUTH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXYAUTH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXYHEADER.md b/docs/libcurl/opts/CURLOPT_PROXYHEADER.md index e44afdd1871..21494e15093 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYHEADER.md +++ b/docs/libcurl/opts/CURLOPT_PROXYHEADER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXYHEADER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md index 22520ea1161..bc931666f72 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXYPASSWORD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXYPORT.md b/docs/libcurl/opts/CURLOPT_PROXYPORT.md index 0cda8bb8fc0..d2193ff0968 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYPORT.md +++ b/docs/libcurl/opts/CURLOPT_PROXYPORT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXYPORT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXYTYPE.md index 4f06fe5508f..96d9269bfff 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXYTYPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXYTYPE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md index 3a68275fbd0..330a762d4ff 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXYUSERNAME Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md index 34489d4993b..7a49119c63b 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXYUSERPWD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md index 473083f35b4..dac73f38619 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_CAINFO Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md index bbf30cba3e6..2706dec1f19 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_CAINFO_BLOB Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md index 2253c9f26a5..6d649045fff 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_CAPATH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md index d12c298009d..51d1728eb4a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_CRLFILE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md index 3b289d2d4d9..093dadfd3b5 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_ISSUERCERT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md index ddd8cf5b4ee..4f4e153d440 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_ISSUERCERT_BLOB Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md index b29d95f07d3..7750dd24421 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_KEYPASSWD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md index 4db13652dbf..6d97bf48ac7 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_PINNEDPUBLICKEY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md index 73e5cb72ad9..57a8161e3fb 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SERVICE_NAME Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md index debc7ea8e7d..343d1363bab 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSLCERT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md index ce6c50887c8..f019d7c3563 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSLCERTTYPE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md index e880d38e085..7d6bc6fc869 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSLCERT_BLOB Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md index c8400db4431..0ef09a4d959 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSLKEY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md index 97960f43702..03264dbf31f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSLKEYTYPE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md index 48bb2e88aad..6771653245a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSLKEY_BLOB Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md index 6f159e87d02..f59240badb4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSLVERSION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md index d7626c3768e..11bce717c19 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSL_CIPHER_LIST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md index 30d6935a10c..a2aa05a49cb 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSL_OPTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md index fdb8249ff76..40c588b705f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSL_VERIFYHOST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md index f934ddeb7de..916ae90dd31 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_SSL_VERIFYPEER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md index fd59de469e9..605379a0162 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_TLS13_CIPHERS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md index 778d1b79ce3..e78859052be 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_TLSAUTH_PASSWORD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md index d4389188b06..85ee86d73ee 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_TLSAUTH_TYPE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md index 7c6ff6fbc99..a50c1d54769 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_TLSAUTH_USERNAME Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md index c0fed8b21e1..233cad72007 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PROXY_TRANSFER_MODE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_PUT.md b/docs/libcurl/opts/CURLOPT_PUT.md index 117eaedd7d4..7ba4fc6096b 100644 --- a/docs/libcurl/opts/CURLOPT_PUT.md +++ b/docs/libcurl/opts/CURLOPT_PUT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_PUT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md index 4159c02fb6f..b3fd105625f 100644 --- a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md +++ b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_QUICK_EXIT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.md b/docs/libcurl/opts/CURLOPT_QUOTE.md index 9ba912ba655..7efe0d8e2e8 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.md +++ b/docs/libcurl/opts/CURLOPT_QUOTE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_QUOTE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md index 7675461a2dc..0f05337fab2 100644 --- a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md +++ b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RANDOM_FILE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RANGE.md b/docs/libcurl/opts/CURLOPT_RANGE.md index 3f765bc61fa..a770c244f29 100644 --- a/docs/libcurl/opts/CURLOPT_RANGE.md +++ b/docs/libcurl/opts/CURLOPT_RANGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RANGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_READDATA.md b/docs/libcurl/opts/CURLOPT_READDATA.md index d7aa4ff9aca..94086647dd7 100644 --- a/docs/libcurl/opts/CURLOPT_READDATA.md +++ b/docs/libcurl/opts/CURLOPT_READDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_READDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.md b/docs/libcurl/opts/CURLOPT_READFUNCTION.md index 978440d138e..b7eddbc48b9 100644 --- a/docs/libcurl/opts/CURLOPT_READFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_READFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md index 4d06d465844..5c03460c50b 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_REDIR_PROTOCOLS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md index 9201a4b41f3..10a0f015ebc 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_REDIR_PROTOCOLS_STR Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_REFERER.md b/docs/libcurl/opts/CURLOPT_REFERER.md index 6af19cb01b7..fdf33903819 100644 --- a/docs/libcurl/opts/CURLOPT_REFERER.md +++ b/docs/libcurl/opts/CURLOPT_REFERER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_REFERER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md index cfc15d7b47e..0d72e146db7 100644 --- a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md +++ b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_REQUEST_TARGET Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.md b/docs/libcurl/opts/CURLOPT_RESOLVE.md index ce446bdbf89..39250f55ff0 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVE.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RESOLVE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md index f34cf8bd68f..219d0bd1ba2 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RESOLVER_START_DATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md index a9b49072630..e4d0a0b8e3f 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RESOLVER_START_FUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM.md b/docs/libcurl/opts/CURLOPT_RESUME_FROM.md index c8de1ee6bd5..fd3bee4d953 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM.md +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RESUME_FROM Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md index 950a4f496d1..e7e8d5dfe32 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RESUME_FROM_LARGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md index 6c83663dc67..d1ef05ea8a2 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RTSP_CLIENT_CSEQ Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md index d56b34dc905..a9ff2160703 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RTSP_REQUEST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md index 819ea07d48b..62b142205ff 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RTSP_SERVER_CSEQ Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md index 8af7f7c5963..1373c38231c 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RTSP_SESSION_ID Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md index e138a3cd9a0..8a28d72727c 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RTSP_STREAM_URI Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md index b8083967dc0..d33ddea8f10 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_RTSP_TRANSPORT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md index 5ff67c6ab45..b32732f262d 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md +++ b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SASL_AUTHZID Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SASL_IR.md b/docs/libcurl/opts/CURLOPT_SASL_IR.md index 204734d01e4..2e421da9a32 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_IR.md +++ b/docs/libcurl/opts/CURLOPT_SASL_IR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SASL_IR Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.md b/docs/libcurl/opts/CURLOPT_SEEKDATA.md index 9392c2366b6..84ea49f47fa 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKDATA.md +++ b/docs/libcurl/opts/CURLOPT_SEEKDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SEEKDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md index 102bdcfc721..2744df85337 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SEEKFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md index 5385d521ef4..e96dd473666 100644 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SERVER_RESPONSE_TIMEOUT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md index a7d9c913785..6cd4514a170 100644 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SERVER_RESPONSE_TIMEOUT_MS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md index 0e13ca712ad..9c772e98ec4 100644 --- a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md +++ b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SERVICE_NAME Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SHARE.md b/docs/libcurl/opts/CURLOPT_SHARE.md index 3c0e7d2595b..38d879328f7 100644 --- a/docs/libcurl/opts/CURLOPT_SHARE.md +++ b/docs/libcurl/opts/CURLOPT_SHARE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SHARE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md index f44bf532d9a..bde40109c85 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SOCKOPTDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md index f5de3168585..5538033b666 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SOCKOPTFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md index bc581d911b8..374d566fd34 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SOCKS5_AUTH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md index 08a1ced6a42..8c3891dfde2 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SOCKS5_GSSAPI_NEC Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md index 47f6e28db88..28062fc0c4d 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SOCKS5_GSSAPI_SERVICE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md index 205e94d1935..fb07fa4376f 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md +++ b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_AUTH_TYPES Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md index 5e2b2785d66..d784e3dc056 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_COMPRESSION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md index 39cbd0ddd27..7c22ff5dee6 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_KEYDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md index ed57975209f..40d720edf0e 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_HOSTKEYFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md index 4b78765016f..6f439522961 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md index 41562db6311..a4463e8ea45 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md index e90cace34f4..24249aa0415 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_KEYDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md index 5fc40060efa..90cd8bfb514 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_KEYFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md index 5a5fcbf33eb..1f1f2bc8d77 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_KNOWNHOSTS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md index e8a40079b56..11dda139798 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md +++ b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_PRIVATE_KEYFILE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md index 35d65ad93ed..9f110c7d6b6 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md +++ b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSH_PUBLIC_KEYFILE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.md b/docs/libcurl/opts/CURLOPT_SSLCERT.md index e1450835313..dda3b940294 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLCERT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md index 420ca4f86b8..948365b71b1 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLCERTTYPE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md index 1f3ed56ed4b..db54c40b11b 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLCERT_BLOB Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.md b/docs/libcurl/opts/CURLOPT_SSLENGINE.md index 45ccc42c5a1..f8b2a623e36 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE.md +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLENGINE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md index d082f7b54ae..2d7958522b8 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLENGINE_DEFAULT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.md b/docs/libcurl/opts/CURLOPT_SSLKEY.md index 292258fd78b..b130eb84cb9 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLKEY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md index b3f114109a6..a13865a9d30 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLKEYTYPE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md index 74425692bd9..35107700ac2 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLKEY_BLOB Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_SSLVERSION.md index f64a13b5fe0..08eee343367 100644 --- a/docs/libcurl/opts/CURLOPT_SSLVERSION.md +++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSLVERSION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md index c96c93f3e39..c07e7203a9b 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_CIPHER_LIST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md index 6e328a5bd40..b7d1325825f 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_CTX_DATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md index 35c8c0d6574..d2eb2b1bb35 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_CTX_FUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md index adfaae34cd4..49d216bee76 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md +++ b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_EC_CURVES Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md index e1b456a060a..1638942e475 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_ENABLE_ALPN Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md index 36221cabdd2..4e34e0764a5 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_ENABLE_NPN Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md index 084728c704f..1a1110acae0 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md +++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_FALSESTART Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md index ffc62c33c16..94732a967c7 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_OPTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md index a6b3cf195b9..0de33f1a0b7 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md +++ b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_SESSIONID_CACHE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md index 75648a11b5c..110cbd10600 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_VERIFYHOST Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md index c9884ceb9a1..5f0832738c1 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_VERIFYPEER Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md index 66dbd7465fa..3bc2c793cb0 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SSL_VERIFYSTATUS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_STDERR.md b/docs/libcurl/opts/CURLOPT_STDERR.md index a20e50366d2..d90df253bcc 100644 --- a/docs/libcurl/opts/CURLOPT_STDERR.md +++ b/docs/libcurl/opts/CURLOPT_STDERR.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_STDERR Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md index ba2489a30a0..b0f4c9f0ed9 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_STREAM_DEPENDS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md index e8dbc113f94..da83e93d47b 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_STREAM_DEPENDS_E Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md index 914a4263d18..af2ecff7c6c 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_STREAM_WEIGHT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md index 7301925854f..e1dd7e56ab8 100644 --- a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md +++ b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_SUPPRESS_CONNECT_HEADERS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md index 4db103b4b8e..c93d41f8ed1 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md +++ b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TCP_FASTOPEN Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md index 09043199320..17809794d9a 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TCP_KEEPALIVE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md index d8418ffb247..3e0db307d34 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TCP_KEEPIDLE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md index d560cf51651..f3a2b4df8e6 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TCP_KEEPINTVL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md index 2613e0a1645..a56401941d3 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TCP_NODELAY Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md index 5fa6348381f..281ad831526 100644 --- a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TELNETOPTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md index 07cbebae405..8772c51963a 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TFTP_BLKSIZE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md index fd4e4921ff2..9571ebd6964 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TFTP_NO_OPTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TIMECONDITION.md b/docs/libcurl/opts/CURLOPT_TIMECONDITION.md index 80d93a516ba..8b42fc8bbcc 100644 --- a/docs/libcurl/opts/CURLOPT_TIMECONDITION.md +++ b/docs/libcurl/opts/CURLOPT_TIMECONDITION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TIMECONDITION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_TIMEOUT.md index 02a3d3dbe45..960b7692c7d 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TIMEOUT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md index 0bb037f7c17..dbc6ccf72c6 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TIMEOUT_MS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md index cc8f6032c86..bdd519003b8 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TIMEVALUE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md index 1424f6617c9..1b01a6b2248 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TIMEVALUE_LARGE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md index d7c7a35106d..39dabc44559 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TLS13_CIPHERS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md index 1d0e1d01dc5..8f5c89d5822 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TLSAUTH_PASSWORD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md index f3e0803d4a5..066fc039464 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TLSAUTH_TYPE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md index e797499e7c3..9075163d88c 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TLSAUTH_USERNAME Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TRAILERDATA.md b/docs/libcurl/opts/CURLOPT_TRAILERDATA.md index 304b408e26e..28546ca78d6 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERDATA.md +++ b/docs/libcurl/opts/CURLOPT_TRAILERDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TRAILERDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md index 5d79214bf91..4eaee1f7d4c 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TRAILERFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md index 4f6d00485d8..7f4798e992f 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md +++ b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TRANSFERTEXT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md index 7fd38487ad4..52e37d61bb3 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md +++ b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_TRANSFER_ENCODING Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md index 0ef3ec17674..0783422b96f 100644 --- a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md +++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_UNIX_SOCKET_PATH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md index 53b584fd075..0ce080ae1ae 100644 --- a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_UNRESTRICTED_AUTH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md index 283efa73e57..11833c29e4b 100644 --- a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md +++ b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_UPKEEP_INTERVAL_MS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD.md b/docs/libcurl/opts/CURLOPT_UPLOAD.md index a54f2fd9fa7..0d4d8aadfdd 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD.md +++ b/docs/libcurl/opts/CURLOPT_UPLOAD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_UPLOAD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md index f32a45f98b4..0291fcf0056 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md +++ b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_UPLOAD_BUFFERSIZE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_URL.md b/docs/libcurl/opts/CURLOPT_URL.md index 3a0691bfc34..f0650a9e1c7 100644 --- a/docs/libcurl/opts/CURLOPT_URL.md +++ b/docs/libcurl/opts/CURLOPT_URL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_URL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.md b/docs/libcurl/opts/CURLOPT_USERAGENT.md index a5423def023..4547da53298 100644 --- a/docs/libcurl/opts/CURLOPT_USERAGENT.md +++ b/docs/libcurl/opts/CURLOPT_USERAGENT.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_USERAGENT Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_USERNAME.md b/docs/libcurl/opts/CURLOPT_USERNAME.md index 269b846094c..7c53fdf3a68 100644 --- a/docs/libcurl/opts/CURLOPT_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_USERNAME.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_USERNAME Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.md b/docs/libcurl/opts/CURLOPT_USERPWD.md index e78e11ddb8f..366593fbb9f 100644 --- a/docs/libcurl/opts/CURLOPT_USERPWD.md +++ b/docs/libcurl/opts/CURLOPT_USERPWD.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_USERPWD Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_USE_SSL.md b/docs/libcurl/opts/CURLOPT_USE_SSL.md index 3e227fcfd88..9cb5eb7ff40 100644 --- a/docs/libcurl/opts/CURLOPT_USE_SSL.md +++ b/docs/libcurl/opts/CURLOPT_USE_SSL.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_USE_SSL Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.md b/docs/libcurl/opts/CURLOPT_VERBOSE.md index 5ecc4b11aa5..83855be3b2d 100644 --- a/docs/libcurl/opts/CURLOPT_VERBOSE.md +++ b/docs/libcurl/opts/CURLOPT_VERBOSE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_VERBOSE Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md index 98c99441085..b0130dbed9b 100644 --- a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md +++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_WILDCARDMATCH Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.md b/docs/libcurl/opts/CURLOPT_WRITEDATA.md index 495c6bf9cfd..a4a4a238b80 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.md +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_WRITEDATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md index cd870dbf90a..6a7e023b90e 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_WRITEFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md index 04af5bca8c7..c1157e046e6 100644 --- a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_WS_OPTIONS Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.md b/docs/libcurl/opts/CURLOPT_XFERINFODATA.md index 145057c5c47..78616676c66 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFODATA.md +++ b/docs/libcurl/opts/CURLOPT_XFERINFODATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_XFERINFODATA Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md index b965db591d9..41bd89a2747 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_XFERINFOFUNCTION Section: 3 diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md index d6cf901f444..7f036d98c3d 100644 --- a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLOPT_XOAUTH2_BEARER Section: 3 diff --git a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md index f41f86ebf2c..47fbae963ab 100644 --- a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md +++ b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLSHOPT_LOCKFUNC Section: 3 diff --git a/docs/libcurl/opts/CURLSHOPT_SHARE.md b/docs/libcurl/opts/CURLSHOPT_SHARE.md index 66ed27034ed..8f742a40213 100644 --- a/docs/libcurl/opts/CURLSHOPT_SHARE.md +++ b/docs/libcurl/opts/CURLSHOPT_SHARE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLSHOPT_SHARE Section: 3 diff --git a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md index 16f9a377e6a..10db90ebce4 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md +++ b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLSHOPT_UNLOCKFUNC Section: 3 diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md index e3cf5988ceb..4a11bfa55dd 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md +++ b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLSHOPT_UNSHARE Section: 3 diff --git a/docs/libcurl/opts/CURLSHOPT_USERDATA.md b/docs/libcurl/opts/CURLSHOPT_USERDATA.md index d0ec7772de6..9349cebbcf6 100644 --- a/docs/libcurl/opts/CURLSHOPT_USERDATA.md +++ b/docs/libcurl/opts/CURLSHOPT_USERDATA.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: CURLSHOPT_USERDATA Section: 3 diff --git a/docs/mk-ca-bundle.md b/docs/mk-ca-bundle.md index 8836305dc7c..8a813099890 100644 --- a/docs/mk-ca-bundle.md +++ b/docs/mk-ca-bundle.md @@ -1,5 +1,5 @@ --- -c: Copyright (C) Daniel Stenberg, , et al. +c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Title: mk-ca-bundle Section: 1 diff --git a/lib/easygetopt.c b/lib/easygetopt.c index 2b8a521cd2e..a0239a89fba 100644 --- a/lib/easygetopt.c +++ b/lib/easygetopt.c @@ -5,7 +5,7 @@ * | (__| |_| | _ <| |___ * ___|___/|_| ______| * - * Copyright (C) Daniel Stenberg, , et al. + * 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 diff --git a/lib/easyoptions.c b/lib/easyoptions.c index da4c6111a3b..9c4438a100e 100644 --- a/lib/easyoptions.c +++ b/lib/easyoptions.c @@ -5,7 +5,7 @@ * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - * Copyright (C) Daniel Stenberg, , et al. + * 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 diff --git a/lib/optiontable.pl b/lib/optiontable.pl index 25d6a66debf..511322a3477 100755 --- a/lib/optiontable.pl +++ b/lib/optiontable.pl @@ -8,7 +8,7 @@ * | (__| |_| | _ <| |___ * \\___|\\___/|_| \\_\\_____| * - * Copyright (C) Daniel Stenberg, , et al. + * 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 From 9369c30cd87c041cf983bcdfabd1570980abbaf6 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 15 Feb 2024 16:22:53 +0100 Subject: [PATCH 392/509] lib: Curl_read/Curl_write clarifications - replace `Curl_read()`, `Curl_write()` and `Curl_nwrite()` to clarify when and at what level they operate - send/recv of transfer related data is now done via `Curl_xfer_send()/Curl_xfer_recv()` which no longer has socket/socketindex as parameter. It decides on the transfer setup of `conn->sockfd` and `conn->writesockfd` on which connection filter chain to operate. - send/recv on a specific connection filter chain is done via `Curl_conn_send()/Curl_conn_recv()` which get the socket index as parameter. - rename `Curl_setup_transfer()` to `Curl_xfer_setup()` for naming consistency - clarify that the special CURLE_AGAIN hangling to return `CURLE_OK` with length 0 only applies to `Curl_xfer_send()` and CURLE_AGAIN is returned by all other send() variants. - fix a bug in websocket `curl_ws_recv()` that mixed up data when it arrived in more than a single chunk (to be made into a sperate PR, also) Added as documented [in CLIENT-READER.md](https://github.com/curl/curl/blob/5b1f31dfbab8aef467c419c68aa06dc738cb75d4/docs/CLIENT-READERS.md). - old `Curl_buffer_send()` completely replaced by new `Curl_req_send()` - old `Curl_fillreadbuffer()` replaced with `Curl_client_read()` - HTTP chunked uploads are now formatted in a client reader added when needed. - FTP line-end conversions are done in a client reader added when needed. - when sending requests headers, remaining buffer space is filled with body data for sending in "one go". This is independent of the request body size. Resolves #12938 as now small and large requests have the same code path. Changes done to test cases: - test513: now fails before sending request headers as this initial "client read" triggers the setup fault. Behaves now the same as in hyper build - test547, test555, test1620: fix the length check in the lib code to only fail for reads *smaller* than expected. This was a bug in the test code that never triggered in the old implementation. Closes #12969 --- docs/CLIENT-READERS.md | 93 +++++++ docs/Makefile.am | 1 + lib/bufq.c | 21 ++ lib/bufq.h | 7 + lib/c-hyper.c | 102 ++----- lib/cf-h1-proxy.c | 2 +- lib/file.c | 12 +- lib/http.c | 554 ++++--------------------------------- lib/http.h | 8 +- lib/http_chunks.c | 191 +++++++++++++ lib/http_chunks.h | 7 + lib/request.c | 89 ++++-- lib/request.h | 24 +- lib/rtsp.c | 83 +++--- lib/sendf.c | 528 ++++++++++++++++++++++++++++++++++- lib/sendf.h | 105 ++++++- lib/smb.c | 5 +- lib/tftp.c | 9 +- lib/transfer.c | 343 +---------------------- lib/transfer.h | 2 - scripts/singleuse.pl | 2 + tests/data/test513 | 8 - tests/data/test579 | 2 + tests/http/test_14_auth.py | 4 +- tests/libtest/lib547.c | 2 +- tests/libtest/lib555.c | 2 +- 26 files changed, 1188 insertions(+), 1018 deletions(-) create mode 100644 docs/CLIENT-READERS.md diff --git a/docs/CLIENT-READERS.md b/docs/CLIENT-READERS.md new file mode 100644 index 00000000000..66cf09dda0f --- /dev/null +++ b/docs/CLIENT-READERS.md @@ -0,0 +1,93 @@ +# 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); +}; + +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. + +## 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: +* delegate the actual "rewinding" to the readers. The should know how it is done, eliminating the `readrewind.c` protocol specifics in `multi.c`. +* `expect-100` handling: place that into a HTTP specific reader at `CURL_CR_PROTOCOL` and eliminate the checks in the generic transfer parts. +* `eos` detection: `upload_done` is partly triggered now by comparing the number of bytes sent to a known size. This is no longer necessary since the core readers obey length restrictions. +* `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/Makefile.am b/docs/Makefile.am index 7dff4336150..b79ad24731f 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -56,6 +56,7 @@ EXTRA_DIST = \ CODE_OF_CONDUCT.md \ CODE_REVIEW.md \ CODE_STYLE.md \ + CLIENT-READERS.md \ CLIENT-WRITERS.md \ CONNECTION-FILTERS.md \ CONTRIBUTE.md \ diff --git a/lib/bufq.c b/lib/bufq.c index d03906d166d..4369fe0b268 100644 --- a/lib/bufq.c +++ b/lib/bufq.c @@ -417,6 +417,17 @@ ssize_t Curl_bufq_write(struct bufq *q, return nwritten; } +CURLcode Curl_bufq_cwrite(struct bufq *q, + const char *buf, size_t len, + size_t *pnwritten) +{ + ssize_t n; + CURLcode result; + n = Curl_bufq_write(q, (const unsigned char *)buf, len, &result); + *pnwritten = (n < 0)? 0 : (size_t)n; + return result; +} + ssize_t Curl_bufq_read(struct bufq *q, unsigned char *buf, size_t len, CURLcode *err) { @@ -440,6 +451,16 @@ ssize_t Curl_bufq_read(struct bufq *q, unsigned char *buf, size_t len, return nread; } +CURLcode Curl_bufq_cread(struct bufq *q, char *buf, size_t len, + size_t *pnread) +{ + ssize_t n; + CURLcode result; + n = Curl_bufq_read(q, (unsigned char *)buf, len, &result); + *pnread = (n < 0)? 0 : (size_t)n; + return result; +} + bool Curl_bufq_peek(struct bufq *q, const unsigned char **pbuf, size_t *plen) { diff --git a/lib/bufq.h b/lib/bufq.h index 089d61bfe42..027a2b6baf1 100644 --- a/lib/bufq.h +++ b/lib/bufq.h @@ -178,6 +178,10 @@ ssize_t Curl_bufq_write(struct bufq *q, const unsigned char *buf, size_t len, CURLcode *err); +CURLcode Curl_bufq_cwrite(struct bufq *q, + const char *buf, size_t len, + size_t *pnwritten); + /** * Read buf from the start of the buffer queue. The buf is copied * and the amount of copied bytes is returned. @@ -187,6 +191,9 @@ ssize_t Curl_bufq_write(struct bufq *q, ssize_t Curl_bufq_read(struct bufq *q, unsigned char *buf, size_t len, CURLcode *err); +CURLcode Curl_bufq_cread(struct bufq *q, char *buf, size_t len, + size_t *pnread); + /** * Peek at the head chunk in the buffer queue. Returns a pointer to * the chunk buf (at the current offset) and its length. Does not diff --git a/lib/c-hyper.c b/lib/c-hyper.c index ae51c5ca403..d12d6de153d 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -117,8 +117,6 @@ size_t Curl_hyper_send(void *userp, hyper_context *ctx, DEBUGF(infof(data, "Curl_hyper_send(%zu)", buflen)); result = Curl_conn_send(data, io_ctx->sockindex, (void *)buf, buflen, &nwrote); - if(!result && !nwrote) - result = CURLE_AGAIN; if(result == CURLE_AGAIN) { DEBUGF(infof(data, "Curl_hyper_send(%zu) -> EAGAIN", buflen)); /* would block, register interest */ @@ -659,48 +657,13 @@ static CURLcode request_target(struct Curl_easy *data, return result; } -static int uploadpostfields(void *userdata, hyper_context *ctx, - hyper_buf **chunk) -{ - struct Curl_easy *data = (struct Curl_easy *)userdata; - (void)ctx; - if(data->req.exp100 > EXP100_SEND_DATA) { - if(data->req.exp100 == EXP100_FAILED) - return HYPER_POLL_ERROR; - - /* still waiting confirmation */ - if(data->hyp.exp100_waker) - hyper_waker_free(data->hyp.exp100_waker); - data->hyp.exp100_waker = hyper_context_waker(ctx); - return HYPER_POLL_PENDING; - } - if(data->req.upload_done) - *chunk = NULL; /* nothing more to deliver */ - else { - /* send everything off in a single go */ - hyper_buf *copy = hyper_buf_copy(data->set.postfields, - (size_t)data->req.p.http->postsize); - if(copy) - *chunk = copy; - else { - data->state.hresult = CURLE_OUT_OF_MEMORY; - return HYPER_POLL_ERROR; - } - /* increasing the writebytecount here is a little premature but we - don't know exactly when the body is sent */ - data->req.writebytecount += (size_t)data->req.p.http->postsize; - Curl_pgrsSetUploadCounter(data, data->req.writebytecount); - data->req.upload_done = TRUE; - } - return HYPER_POLL_READY; -} - static int uploadstreamed(void *userdata, hyper_context *ctx, hyper_buf **chunk) { size_t fillcount; struct Curl_easy *data = (struct Curl_easy *)userdata; CURLcode result; + bool eos; (void)ctx; if(data->req.exp100 > EXP100_SEND_DATA) { @@ -714,32 +677,15 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, return HYPER_POLL_PENDING; } - if(data->req.upload_chunky && data->req.authneg) { - fillcount = 0; - data->req.upload_chunky = FALSE; - result = CURLE_OK; - } - else { - result = Curl_fillreadbuffer(data, data->set.upload_buffer_size, - &fillcount); - } + result = Curl_client_read(data, data->state.ulbuf, + data->set.upload_buffer_size, + &fillcount, &eos); if(result) { data->state.hresult = result; return HYPER_POLL_ERROR; } - if(!fillcount) { - if((data->req.keepon & KEEP_SEND_PAUSE) != KEEP_SEND_PAUSE) - /* done! */ - *chunk = NULL; - else { - /* paused, save a waker */ - if(data->hyp.send_body_waker) - hyper_waker_free(data->hyp.send_body_waker); - data->hyp.send_body_waker = hyper_context_waker(ctx); - return HYPER_POLL_PENDING; - } - } - else { + + if(fillcount) { hyper_buf *copy = hyper_buf_copy((uint8_t *)data->state.ulbuf, fillcount); if(copy) *chunk = copy; @@ -751,8 +697,19 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, don't know exactly when the body is sent */ data->req.writebytecount += fillcount; Curl_pgrsSetUploadCounter(data, data->req.writebytecount); + return HYPER_POLL_READY; + } + else if(eos) { + *chunk = NULL; + return HYPER_POLL_READY; + } + else { + /* paused, save a waker */ + if(data->hyp.send_body_waker) + hyper_waker_free(data->hyp.send_body_waker); + data->hyp.send_body_waker = hyper_context_waker(ctx); + return HYPER_POLL_PENDING; } - return HYPER_POLL_READY; } /* @@ -773,7 +730,7 @@ static CURLcode bodysend(struct Curl_easy *data, else { hyper_body *body; Curl_dyn_init(&req, DYN_HTTP_REQUEST); - result = Curl_http_req_send(data, &req, httpreq); + result = Curl_http_req_complete(data, &req, httpreq); if(!result) result = Curl_hyper_header(data, headers, Curl_dyn_ptr(&req)); @@ -782,18 +739,15 @@ static CURLcode bodysend(struct Curl_easy *data, body = hyper_body_new(); hyper_body_set_userdata(body, data); - if(data->set.postfields) - hyper_body_set_data_func(body, uploadpostfields); - else { - result = Curl_get_upload_buffer(data); - if(result) { - hyper_body_free(body); - return result; - } - /* init the "upload from here" pointer */ - data->req.upload_fromhere = data->state.ulbuf; - hyper_body_set_data_func(body, uploadstreamed); + result = Curl_get_upload_buffer(data); + if(result) { + hyper_body_free(body); + return result; } + /* init the "upload from here" pointer */ + data->req.upload_fromhere = data->state.ulbuf; + hyper_body_set_data_func(body, uploadstreamed); + if(HYPERE_OK != hyper_request_set_body(hyperreq, body)) { /* fail */ result = CURLE_OUT_OF_MEMORY; @@ -888,7 +842,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) may be parts of the request that is not yet sent, since we can deal with the rest of the request in the PERFORM phase. */ *done = TRUE; - Curl_cw_reset(data); + Curl_client_reset(data); /* Add collecting of headers written to client. For a new connection, * we might have done that already, but reuse diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index 6ca7babf8e6..280516061fc 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -1013,7 +1013,7 @@ static CURLcode cf_h1_proxy_connect(struct Curl_cfilter *cf, data->req.header = TRUE; /* assume header */ data->req.bytecount = 0; data->req.ignorebody = FALSE; - Curl_cw_reset(data); + Curl_client_reset(data); Curl_pgrsSetUploadCounter(data, 0); Curl_pgrsSetDownloadCounter(data, 0); diff --git a/lib/file.c b/lib/file.c index 63089e0f2a9..d3b08a81f0e 100644 --- a/lib/file.c +++ b/lib/file.c @@ -293,10 +293,10 @@ static CURLcode file_upload(struct Curl_easy *data) CURLcode result = CURLE_OK; char *xfer_buf; size_t xfer_blen; - char *uphere_save; curl_off_t bytecount = 0; struct_stat file_stat; const char *sendbuf; + bool eos = FALSE; /* * Since FILE: doesn't do the full init, we need to provide some extra @@ -340,21 +340,16 @@ static CURLcode file_upload(struct Curl_easy *data) data->state.resume_from = (curl_off_t)file_stat.st_size; } - /* Yikes! Curl_fillreadbuffer uses data->req.upload_fromhere to READ - * client data to! Please, someone fix... */ - uphere_save = data->req.upload_fromhere; - result = Curl_multi_xfer_buf_borrow(data, &xfer_buf, &xfer_blen); if(result) goto out; - while(!result) { + while(!result && !eos) { size_t nread; ssize_t nwrite; size_t readcount; - data->req.upload_fromhere = xfer_buf; - result = Curl_fillreadbuffer(data, xfer_blen, &readcount); + result = Curl_client_read(data, xfer_buf, xfer_blen, &readcount, &eos); if(result) break; @@ -401,7 +396,6 @@ static CURLcode file_upload(struct Curl_easy *data) out: close(fd); Curl_multi_xfer_buf_release(data, xfer_buf); - data->req.upload_fromhere = uphere_save; return result; } diff --git a/lib/http.c b/lib/http.c index 77832d2a466..870de3830cf 100644 --- a/lib/http.c +++ b/lib/http.c @@ -543,7 +543,7 @@ static CURLcode http_perhapsrewind(struct Curl_easy *data, closure so we can safely do the rewind right now */ } - if(bytessent) { + if(Curl_client_read_needs_rewind(data)) { /* mark for rewind since if we already sent something */ data->state.rewindbeforesend = TRUE; infof(data, "Please rewind output before next send"); @@ -1174,277 +1174,6 @@ static bool http_should_fail(struct Curl_easy *data) return data->state.authproblem; } -#ifndef USE_HYPER -/* - * readmoredata() is a "fread() emulation" to provide POST and/or request - * data. It is used when a huge POST is to be made and the entire chunk wasn't - * sent in the first send(). This function will then be called from the - * transfer.c loop when more data is to be sent to the peer. - * - * Returns the amount of bytes it filled the buffer with. - */ -static size_t readmoredata(char *buffer, - size_t size, - size_t nitems, - void *userp) -{ - struct HTTP *http = (struct HTTP *)userp; - struct Curl_easy *data = http->backup.data; - size_t fullsize = size * nitems; - - if(!http->postsize) - /* nothing to return */ - return 0; - - /* make sure that an HTTP request is never sent away chunked! */ - data->req.forbidchunk = (http->sending == HTTPSEND_REQUEST)?TRUE:FALSE; - - if(data->set.max_send_speed && - (data->set.max_send_speed < (curl_off_t)fullsize) && - (data->set.max_send_speed < http->postsize)) - /* speed limit */ - fullsize = (size_t)data->set.max_send_speed; - - else if(http->postsize <= (curl_off_t)fullsize) { - memcpy(buffer, http->postdata, (size_t)http->postsize); - fullsize = (size_t)http->postsize; - - if(http->backup.postsize) { - /* move backup data into focus and continue on that */ - http->postdata = http->backup.postdata; - http->postsize = http->backup.postsize; - data->state.fread_func = http->backup.fread_func; - data->state.in = http->backup.fread_in; - - http->sending++; /* move one step up */ - - http->backup.postsize = 0; - } - else - http->postsize = 0; - - return fullsize; - } - - memcpy(buffer, http->postdata, fullsize); - http->postdata += fullsize; - http->postsize -= fullsize; - - return fullsize; -} - -/* - * Curl_buffer_send() sends a header buffer and frees all associated - * memory. Body data may be appended to the header data if desired. - * - * Returns CURLcode - */ -static CURLcode buffer_send(struct dynbuf *in, - struct Curl_easy *data, - struct HTTP *http, - /* add the number of sent bytes to this - counter */ - curl_off_t *bytes_written, - /* how much of the buffer contains body data */ - curl_off_t included_body_bytes) -{ - size_t amount; - CURLcode result; - char *ptr; - size_t size; - struct connectdata *conn = data->conn; - size_t sendsize; - size_t headersize; - - /* The looping below is required since we use non-blocking sockets, but due - to the circumstances we will just loop and try again and again etc */ - - ptr = Curl_dyn_ptr(in); - size = Curl_dyn_len(in); - - headersize = size - (size_t)included_body_bytes; /* the initial part that - isn't body is header */ - - DEBUGASSERT(size > (size_t)included_body_bytes); - - if((conn->handler->flags & PROTOPT_SSL -#ifndef CURL_DISABLE_PROXY - || IS_HTTPS_PROXY(conn->http_proxy.proxytype) -#endif - ) - && conn->httpversion < 20) { - /* Make sure this doesn't send more body bytes than what the max send - speed says. The request bytes do not count to the max speed. - */ - if(data->set.max_send_speed && - (included_body_bytes > data->set.max_send_speed)) { - curl_off_t overflow = included_body_bytes - data->set.max_send_speed; - DEBUGASSERT((size_t)overflow < size); - sendsize = size - (size_t)overflow; - } - else - sendsize = size; - - /* OpenSSL is very picky and we must send the SAME buffer pointer to the - library when we attempt to re-send this buffer. Sending the same data - is not enough, we must use the exact same address. For this reason, we - must copy the data to the uploadbuffer first, since that is the buffer - we will be using if this send is retried later. - */ - result = Curl_get_upload_buffer(data); - if(result) { - /* malloc failed, free memory and return to the caller */ - Curl_dyn_free(in); - return result; - } - /* We never send more than upload_buffer_size bytes in one single chunk - when we speak HTTPS, as if only a fraction of it is sent now, this data - needs to fit into the normal read-callback buffer later on and that - buffer is using this size. - */ - if(sendsize > (size_t)data->set.upload_buffer_size) - sendsize = (size_t)data->set.upload_buffer_size; - - memcpy(data->state.ulbuf, ptr, sendsize); - ptr = data->state.ulbuf; - } - else { -#ifdef CURLDEBUG - /* Allow debug builds to override this logic to force short initial - sends - */ - char *p = getenv("CURL_SMALLREQSEND"); - if(p) { - size_t altsize = (size_t)strtoul(p, NULL, 10); - if(altsize) - sendsize = CURLMIN(size, altsize); - else - sendsize = size; - } - else -#endif - { - /* Make sure this doesn't send more body bytes than what the max send - speed says. The request bytes do not count to the max speed. - */ - if(data->set.max_send_speed && - (included_body_bytes > data->set.max_send_speed)) { - curl_off_t overflow = included_body_bytes - data->set.max_send_speed; - DEBUGASSERT((size_t)overflow < size); - sendsize = size - (size_t)overflow; - } - else - sendsize = size; - } - - /* We currently cannot send more that this for http here: - * - if sending blocks, it return 0 as amount - * - we then whisk aside the `in` into the `http` struct - * and install our own `data->state.fread_func` that - * on subsequent calls reads `in` empty. - * - when the whisked away `in` is empty, the `fread_func` - * is restored to its original state. - * The problem is that `fread_func` can only return - * `upload_buffer_size` lengths. If the send we do here - * is larger and blocks, we do re-sending with smaller - * amounts of data and connection filters do not like - * that. - */ - if(http && (sendsize > (size_t)data->set.upload_buffer_size)) - sendsize = (size_t)data->set.upload_buffer_size; - } - - result = Curl_xfer_send(data, ptr, sendsize, &amount); - - if(!result) { - /* - * Note that we may not send the entire chunk at once, and we have a set - * number of data bytes at the end of the big buffer (out of which we may - * only send away a part). - */ - /* how much of the header that was sent */ - size_t headlen = (size_t)amount>headersize ? headersize : (size_t)amount; - size_t bodylen = amount - headlen; - - /* this data _may_ contain binary stuff */ - Curl_debug(data, CURLINFO_HEADER_OUT, ptr, headlen); - if(bodylen) - /* there was body data sent beyond the initial header part, pass that on - to the debug callback too */ - Curl_debug(data, CURLINFO_DATA_OUT, ptr + headlen, bodylen); - - /* 'amount' can never be a very large value here so typecasting it so a - signed 31 bit value should not cause problems even if ssize_t is - 64bit */ - *bytes_written += (long)amount; - - if(http) { - /* if we sent a piece of the body here, up the byte counter for it - accordingly */ - data->req.writebytecount += bodylen; - Curl_pgrsSetUploadCounter(data, data->req.writebytecount); - - if((size_t)amount != size) { - /* The whole request could not be sent in one system call. We must - queue it up and send it later when we get the chance. We must not - loop here and wait until it might work again. */ - - size -= amount; - - ptr = Curl_dyn_ptr(in) + amount; - - /* backup the currently set pointers */ - http->backup.fread_func = data->state.fread_func; - http->backup.fread_in = data->state.in; - http->backup.postdata = http->postdata; - http->backup.postsize = http->postsize; - http->backup.data = data; - - /* set the new pointers for the request-sending */ - data->state.fread_func = (curl_read_callback)readmoredata; - data->state.in = (void *)http; - http->postdata = ptr; - http->postsize = (curl_off_t)size; - - /* this much data is remaining header: */ - data->req.pendingheader = headersize - headlen; - - http->send_buffer = *in; /* copy the whole struct */ - http->sending = HTTPSEND_REQUEST; - return CURLE_OK; - } - http->sending = HTTPSEND_BODY; - /* the full buffer was sent, clean up and return */ - } - else { - if((size_t)amount != size) - /* We have no continue-send mechanism now, fail. This can only happen - when this function is used from the CONNECT sending function. We - currently (stupidly) assume that the whole request is always sent - away in the first single chunk. - - This needs FIXing. - */ - return CURLE_SEND_ERROR; - } - } - Curl_dyn_free(in); - - /* no remaining header data */ - data->req.pendingheader = 0; - return result; -} - -/* end of the add_buffer functions */ -/* ------------------------------------------------------------------------- */ -#else /* !USE_HYPER */ - /* In hyper, this is an ugly NOP */ -#define buffer_send(a,b,c,d,e) CURLE_OK - -#endif /* !USE_HYPER(else) */ - - - /* * Curl_compareheader() * @@ -1648,51 +1377,6 @@ enum proxy_use { HEADER_CONNECT /* sending CONNECT to a proxy */ }; -/* used to compile the provided trailers into one buffer - will return an error code if one of the headers is - not formatted correctly */ -CURLcode Curl_http_compile_trailers(struct curl_slist *trailers, - struct dynbuf *b, - struct Curl_easy *handle) -{ - char *ptr = NULL; - CURLcode result = CURLE_OK; - const char *endofline_native = NULL; - const char *endofline_network = NULL; - - if( -#ifdef CURL_DO_LINEEND_CONV - (handle->state.prefer_ascii) || -#endif - (handle->set.crlf)) { - /* \n will become \r\n later on */ - endofline_native = "\n"; - endofline_network = "\x0a"; - } - else { - endofline_native = "\r\n"; - endofline_network = "\x0d\x0a"; - } - - while(trailers) { - /* only add correctly formatted trailers */ - ptr = strchr(trailers->data, ':'); - if(ptr && *(ptr + 1) == ' ') { - result = Curl_dyn_add(b, trailers->data); - if(result) - return result; - result = Curl_dyn_add(b, endofline_native); - if(result) - return result; - } - else - infof(handle, "Malformatted trailing header, skipping trailer"); - trailers = trailers->next; - } - result = Curl_dyn_add(b, endofline_network); - return result; -} - static bool hd_name_eq(const char *n1, size_t n1len, const char *n2, size_t n2len) { @@ -2461,13 +2145,9 @@ static CURLcode addexpect(struct Curl_easy *data, struct dynbuf *r) return CURLE_OK; } -CURLcode Curl_http_req_send(struct Curl_easy *data, - struct dynbuf *r, Curl_HttpReq httpreq) +CURLcode Curl_http_req_complete(struct Curl_easy *data, + struct dynbuf *r, Curl_HttpReq httpreq) { -#ifndef USE_HYPER - /* Hyper always handles the body separately */ - curl_off_t included_body = 0; -#endif CURLcode result = CURLE_OK; struct HTTP *http = data->req.p.http; @@ -2487,32 +2167,24 @@ CURLcode Curl_http_req_send(struct Curl_easy *data, result = Curl_dyn_addf(r, "Content-Length: %" CURL_FORMAT_CURL_OFF_T "\r\n", http->postsize); if(result) - return result; + goto out; } result = addexpect(data, r); if(result) - return result; + goto out; /* end of headers */ result = Curl_dyn_addn(r, STRCONST("\r\n")); if(result) - return result; + goto out; /* set the upload size to the progress meter */ Curl_pgrsSetUploadSize(data, http->postsize); - - /* this sends the buffer and frees all the buffer resources */ - result = buffer_send(r, data, data->req.p.http, - &data->info.request_size, 0); - if(result) - failf(data, "Failed sending PUT request"); + if(!http->postsize) + result = Client_reader_set_null(data); else - /* prepare for transfer */ - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, - http->postsize?FIRSTSOCKET:-1); - if(result) - return result; + result = Client_reader_set_fread(data, data->state.infilesize); break; #if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) @@ -2522,16 +2194,12 @@ CURLcode Curl_http_req_send(struct Curl_easy *data, if(data->req.authneg) { /* nothing to post! */ result = Curl_dyn_addn(r, STRCONST("Content-Length: 0\r\n\r\n")); + if(!result) + result = Client_reader_set_null(data); if(result) return result; - - result = buffer_send(r, data, data->req.p.http, - &data->info.request_size, 0); - if(result) - failf(data, "Failed sending POST request"); - else - /* setup variables for the upcoming transfer */ - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); + /* setup variables for the upcoming transfer */ + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); break; } @@ -2548,7 +2216,7 @@ CURLcode Curl_http_req_send(struct Curl_easy *data, "Content-Length: %" CURL_FORMAT_CURL_OFF_T "\r\n", http->postsize); if(result) - return result; + goto out; } #ifndef CURL_DISABLE_MIME @@ -2559,40 +2227,32 @@ CURLcode Curl_http_req_send(struct Curl_easy *data, for(hdr = data->state.mimepost->curlheaders; hdr; hdr = hdr->next) { result = Curl_dyn_addf(r, "%s\r\n", hdr->data); if(result) - return result; + goto out; } } #endif result = addexpect(data, r); if(result) - return result; + goto out; /* make the request end in a true CRLF */ result = Curl_dyn_addn(r, STRCONST("\r\n")); if(result) - return result; + goto out; /* set the upload size to the progress meter */ Curl_pgrsSetUploadSize(data, http->postsize); - - /* Read from mime structure. */ - data->state.fread_func = (curl_read_callback) Curl_mime_read; - data->state.in = (void *) data->state.mimepost; + if(!http->postsize) + result = Client_reader_set_null(data); + else { + /* Read from mime structure. We could do a special client reader + * for this, but replacing the callback seems to work fine. */ + data->state.fread_func = (curl_read_callback) Curl_mime_read; + data->state.in = (void *) data->state.mimepost; + result = Client_reader_set_fread(data, data->state.infilesize); + } http->sending = HTTPSEND_BODY; - - /* this sends the buffer and frees all the buffer resources */ - result = buffer_send(r, data, data->req.p.http, - &data->info.request_size, 0); - if(result) - failf(data, "Failed sending POST request"); - else - /* prepare for transfer */ - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, - http->postsize?FIRSTSOCKET:-1); - if(result) - return result; - break; #endif case HTTPREQ_POST: @@ -2615,147 +2275,53 @@ CURLcode Curl_http_req_send(struct Curl_easy *data, result = Curl_dyn_addf(r, "Content-Length: %" CURL_FORMAT_CURL_OFF_T "\r\n", http->postsize); if(result) - return result; + goto out; } if(!Curl_checkheaders(data, STRCONST("Content-Type"))) { result = Curl_dyn_addn(r, STRCONST("Content-Type: application/" "x-www-form-urlencoded\r\n")); if(result) - return result; + goto out; } result = addexpect(data, r); if(result) - return result; + goto out; -#ifndef USE_HYPER - /* With Hyper the body is always passed on separately */ - if(data->set.postfields) { - if(!data->state.expect100header && - (http->postsize < MAX_INITIAL_POST_SIZE)) { - /* if we don't use expect: 100 AND - postsize is less than MAX_INITIAL_POST_SIZE - - then append the post data to the HTTP request header. This limit - is no magic limit but only set to prevent really huge POSTs to - get the data duplicated with malloc() and family. */ - - /* end of headers! */ - result = Curl_dyn_addn(r, STRCONST("\r\n")); - if(result) - return result; + result = Curl_dyn_addn(r, STRCONST("\r\n")); + if(result) + goto out; - if(!data->req.upload_chunky) { - /* We're not sending it 'chunked', append it to the request - already now to reduce the number of send() calls */ - result = Curl_dyn_addn(r, data->set.postfields, - (size_t)http->postsize); - included_body = http->postsize; - } - else { - if(http->postsize) { - char chunk[16]; - /* Append the POST data chunky-style */ - msnprintf(chunk, sizeof(chunk), "%x\r\n", (int)http->postsize); - result = Curl_dyn_add(r, chunk); - if(!result) { - included_body = http->postsize + strlen(chunk); - result = Curl_dyn_addn(r, data->set.postfields, + if(!http->postsize) { + Curl_pgrsSetUploadSize(data, -1); + result = Client_reader_set_null(data); + } + else if(data->set.postfields) { /* we have the bytes */ + Curl_pgrsSetUploadSize(data, http->postsize); + result = Client_reader_set_buf(data, data->set.postfields, (size_t)http->postsize); - if(!result) - result = Curl_dyn_addn(r, STRCONST("\r\n")); - included_body += 2; - } - } - if(!result) { - result = Curl_dyn_addn(r, STRCONST("\x30\x0d\x0a\x0d\x0a")); - /* 0 CR LF CR LF */ - included_body += 5; - } - } - if(result) - return result; - /* Make sure the progress information is accurate */ - Curl_pgrsSetUploadSize(data, http->postsize); - } - else { - /* A huge POST coming up, do data separate from the request */ - http->postdata = data->set.postfields; - http->sending = HTTPSEND_BODY; - http->backup.data = data; - data->state.fread_func = (curl_read_callback)readmoredata; - data->state.in = (void *)http; - - /* set the upload size to the progress meter */ - Curl_pgrsSetUploadSize(data, http->postsize); - - /* end of headers! */ - result = Curl_dyn_addn(r, STRCONST("\r\n")); - if(result) - return result; - } } - else -#endif - { - /* end of headers! */ - result = Curl_dyn_addn(r, STRCONST("\r\n")); - if(result) - return result; - - if(data->req.upload_chunky && data->req.authneg) { - /* Chunky upload is selected and we're negotiating auth still, send - end-of-data only */ - result = Curl_dyn_addn(r, (char *)STRCONST("\x30\x0d\x0a\x0d\x0a")); - /* 0 CR LF CR LF */ - if(result) - return result; - } - - else if(data->state.infilesize) { - /* set the upload size to the progress meter */ - Curl_pgrsSetUploadSize(data, http->postsize?http->postsize:-1); - - /* set the pointer to mark that we will send the post body using the - read callback, but only if we're not in authenticate negotiation */ - if(!data->req.authneg) - http->postdata = (char *)&http->postdata; - } + else { /* we read the bytes from the callback */ + Curl_pgrsSetUploadSize(data, http->postsize); + result = Client_reader_set_fread(data, http->postsize); } - /* issue the request */ - result = buffer_send(r, data, data->req.p.http, - &data->info.request_size, included_body); - - if(result) - failf(data, "Failed sending HTTP POST request"); - else - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, - http->postdata?FIRSTSOCKET:-1); + http->sending = HTTPSEND_BODY; break; default: + /* HTTP GET/HEAD download, has no body, needs no Content-Length */ result = Curl_dyn_addn(r, STRCONST("\r\n")); - if(result) - return result; - - /* issue the request */ - result = Curl_req_send_hds(data, Curl_dyn_ptr(r), Curl_dyn_len(r)); - Curl_dyn_free(r); - if(result) - failf(data, "Failed sending HTTP request"); -#ifdef USE_WEBSOCKETS - else if((data->conn->handler->protocol & (CURLPROTO_WS|CURLPROTO_WSS)) && - !(data->set.connect_only)) - /* Set up the transfer for two-way since without CONNECT_ONLY set, this - request probably wants to send data too post upgrade */ - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, FIRSTSOCKET); -#endif - else - /* HTTP GET/HEAD download: */ - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); + if(!result) + result = Client_reader_set_null(data); + break; } +out: + if(!result) { + /* setup variables for the upcoming transfer */ + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, FIRSTSOCKET); + } return result; } @@ -3320,17 +2886,15 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) Curl_pgrsSetUploadSize(data, 0); /* nothing */ /* req_send takes ownership of the 'req' memory on success */ - result = Curl_http_req_send(data, &req, httpreq); + result = Curl_http_req_complete(data, &req, httpreq); + if(!result && data->req.upload_chunky) + result = Curl_httpchunk_add_reader(data); + if(!result) + result = Curl_req_send(data, &req); } - if(result) { - Curl_dyn_free(&req); + Curl_dyn_free(&req); + if(result) goto fail; - } - - if((http->postsize > -1) && - (http->postsize <= data->req.writebytecount) && - (http->sending != HTTPSEND_REQUEST)) - data->req.upload_done = TRUE; if(data->req.writebytecount) { /* if a request-body has been sent off, we make sure this progress is noted diff --git a/lib/http.h b/lib/http.h index 7991f938038..b7fb877e633 100644 --- a/lib/http.h +++ b/lib/http.h @@ -94,10 +94,6 @@ CURLcode Curl_dynhds_add_custom(struct Curl_easy *data, bool is_connect, struct dynhds *hds); -CURLcode Curl_http_compile_trailers(struct curl_slist *trailers, - struct dynbuf *buf, - struct Curl_easy *handle); - void Curl_http_method(struct Curl_easy *data, struct connectdata *conn, const char **method, Curl_HttpReq *); CURLcode Curl_http_useragent(struct Curl_easy *data); @@ -112,8 +108,8 @@ CURLcode Curl_transferencode(struct Curl_easy *data); CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, Curl_HttpReq httpreq, const char **teep); -CURLcode Curl_http_req_send(struct Curl_easy *data, - struct dynbuf *r, Curl_HttpReq httpreq); +CURLcode Curl_http_req_complete(struct Curl_easy *data, + struct dynbuf *r, Curl_HttpReq httpreq); bool Curl_use_http_1_1plus(const struct Curl_easy *data, const struct connectdata *conn); #ifndef CURL_DISABLE_COOKIES diff --git a/lib/http_chunks.c b/lib/http_chunks.c index 959edb2a4d0..3236c0e4730 100644 --- a/lib/http_chunks.c +++ b/lib/http_chunks.c @@ -27,10 +27,12 @@ #ifndef CURL_DISABLE_HTTP #include "urldata.h" /* it includes http_chunks.h */ +#include "curl_printf.h" #include "sendf.h" /* for the client write stuff */ #include "dynbuf.h" #include "content_encoding.h" #include "http.h" +#include "multiif.h" #include "strtoofft.h" #include "warnless.h" @@ -458,4 +460,193 @@ const struct Curl_cwtype Curl_httpchunk_unencoder = { sizeof(struct chunked_writer) }; +/* max length of a HTTP chunk that we want to generate */ +#define CURL_CHUNKED_MINLEN (1024) +#define CURL_CHUNKED_MAXLEN (64 * 1024) + +struct chunked_reader { + struct Curl_creader super; + struct bufq chunkbuf; + BIT(read_eos); /* we read an EOS from the next reader */ + BIT(eos); /* we have returned an EOS */ +}; + +static CURLcode cr_chunked_init(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct chunked_reader *ctx = (struct chunked_reader *)reader; + (void)data; + Curl_bufq_init2(&ctx->chunkbuf, CURL_CHUNKED_MAXLEN, 2, BUFQ_OPT_SOFT_LIMIT); + return CURLE_OK; +} + +static void cr_chunked_close(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct chunked_reader *ctx = (struct chunked_reader *)reader; + (void)data; + Curl_bufq_free(&ctx->chunkbuf); +} + +static CURLcode add_last_chunk(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct chunked_reader *ctx = (struct chunked_reader *)reader; + struct curl_slist *trailers = NULL, *tr; + CURLcode result; + size_t n; + int rc; + + if(!data->set.trailer_callback) { + return Curl_bufq_cwrite(&ctx->chunkbuf, STRCONST("0\r\n\r\n"), &n); + } + + result = Curl_bufq_cwrite(&ctx->chunkbuf, STRCONST("0\r\n"), &n); + if(result) + goto out; + + Curl_set_in_callback(data, true); + rc = data->set.trailer_callback(&trailers, data->set.trailer_data); + Curl_set_in_callback(data, false); + + if(rc != CURL_TRAILERFUNC_OK) { + failf(data, "operation aborted by trailing headers callback"); + result = CURLE_ABORTED_BY_CALLBACK; + goto out; + } + + for(tr = trailers; tr; tr = tr->next) { + /* only add correctly formatted trailers */ + char *ptr = strchr(tr->data, ':'); + if(!ptr || *(ptr + 1) != ' ') { + infof(data, "Malformatted trailing header, skipping trailer"); + continue; + } + + result = Curl_bufq_cwrite(&ctx->chunkbuf, tr->data, + strlen(tr->data), &n); + if(!result) + result = Curl_bufq_cwrite(&ctx->chunkbuf, STRCONST("\r\n"), &n); + if(result) + goto out; + } + + result = Curl_bufq_cwrite(&ctx->chunkbuf, STRCONST("\r\n"), &n); + +out: + curl_slist_free_all(trailers); + return result; +} + +static CURLcode add_chunk(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen) +{ + struct chunked_reader *ctx = (struct chunked_reader *)reader; + CURLcode result; + char tmp[CURL_CHUNKED_MINLEN]; + size_t nread; + bool eos; + + DEBUGASSERT(!ctx->read_eos); + blen = CURLMIN(blen, CURL_CHUNKED_MAXLEN); /* respect our buffer pref */ + if(blen < sizeof(tmp)) { + /* small read, make a chunk of decent size */ + buf = tmp; + blen = sizeof(tmp); + } + else { + /* larger read, make a chunk that will fit when read back */ + blen -= (8 + 2 + 2); /* deduct max overhead, 8 hex + 2*crlf */ + } + + result = Curl_creader_read(data, reader->next, buf, blen, &nread, &eos); + if(result) + return result; + if(eos) + ctx->read_eos = TRUE; + + if(nread) { + /* actually got bytes, wrap them into the chunkbuf */ + char hd[11] = ""; + int hdlen; + size_t n; + + hdlen = msnprintf(hd, sizeof(hd), "%zx\r\n", nread); + if(hdlen <= 0) + return CURLE_READ_ERROR; + /* On a soft-limited bufq, we do not need to check that all was written */ + result = Curl_bufq_cwrite(&ctx->chunkbuf, hd, hdlen, &n); + if(!result) + result = Curl_bufq_cwrite(&ctx->chunkbuf, buf, nread, &n); + if(!result) + result = Curl_bufq_cwrite(&ctx->chunkbuf, "\r\n", 2, &n); + if(result) + return result; + } + + if(ctx->read_eos) + return add_last_chunk(data, reader); + return CURLE_OK; +} + +static CURLcode cr_chunked_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *pnread, bool *peos) +{ + struct chunked_reader *ctx = (struct chunked_reader *)reader; + CURLcode result = CURLE_READ_ERROR; + + *pnread = 0; + *peos = ctx->eos; + + if(!ctx->eos) { + if(!ctx->read_eos && Curl_bufq_is_empty(&ctx->chunkbuf)) { + /* Still getting data form the next reader, buffer is empty */ + result = add_chunk(data, reader, buf, blen); + if(result) + return result; + } + + if(!Curl_bufq_is_empty(&ctx->chunkbuf)) { + result = Curl_bufq_cread(&ctx->chunkbuf, buf, blen, pnread); + if(!result && ctx->read_eos && Curl_bufq_is_empty(&ctx->chunkbuf)) { + /* no more data, read all, done. */ + ctx->eos = TRUE; + *peos = TRUE; + } + return result; + } + } + /* We may get here, because we are done or because callbacks paused */ + DEBUGASSERT(ctx->eos || !ctx->read_eos); + return CURLE_OK; +} + +/* HTTP chunked Transfer-Encoding encoder */ +const struct Curl_crtype Curl_httpchunk_encoder = { + "chunked", + cr_chunked_init, + cr_chunked_read, + cr_chunked_close, + Curl_creader_def_needs_rewind, + sizeof(struct chunked_reader) +}; + +CURLcode Curl_httpchunk_add_reader(struct Curl_easy *data) +{ + struct Curl_creader *reader = NULL; + CURLcode result; + + result = Curl_creader_create(&reader, data, &Curl_httpchunk_encoder, + CURL_CR_TRANSFER_ENCODE); + if(!result) + result = Curl_creader_add(data, reader); + + if(result && reader) + Curl_creader_free(data, reader); + return result; +} + #endif /* CURL_DISABLE_HTTP */ diff --git a/lib/http_chunks.h b/lib/http_chunks.h index 07f2984c36e..d3ecc36c77c 100644 --- a/lib/http_chunks.h +++ b/lib/http_chunks.h @@ -133,6 +133,13 @@ bool Curl_httpchunk_is_done(struct Curl_easy *data, struct Curl_chunker *ch); extern const struct Curl_cwtype Curl_httpchunk_unencoder; +extern const struct Curl_crtype Curl_httpchunk_encoder; + +/** + * Add a transfer-encoding "chunked" reader to the transfers reader stack + */ +CURLcode Curl_httpchunk_add_reader(struct Curl_easy *data); + #endif /* !CURL_DISABLE_HTTP */ #endif /* HEADER_CURL_HTTP_CHUNKS_H */ diff --git a/lib/request.c b/lib/request.c index 334a0567398..cd5170a3282 100644 --- a/lib/request.c +++ b/lib/request.c @@ -27,6 +27,7 @@ #include "urldata.h" #include "dynbuf.h" #include "doh.h" +#include "multiif.h" #include "progress.h" #include "request.h" #include "sendf.h" @@ -48,7 +49,7 @@ CURLcode Curl_req_start(struct SingleRequest *req, struct Curl_easy *data) { req->start = Curl_now(); - Curl_cw_reset(data); + Curl_client_reset(data); if(!req->sendbuf_init) { Curl_bufq_init2(&req->sendbuf, data->set.upload_buffer_size, 1, BUFQ_OPT_SOFT_LIMIT); @@ -72,7 +73,7 @@ CURLcode Curl_req_done(struct SingleRequest *req, (void)req; if(!aborted) (void)Curl_req_flush(data); - Curl_cw_reset(data); + Curl_client_reset(data); return CURLE_OK; } @@ -85,7 +86,7 @@ void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data) * free this safely without leaks. */ Curl_safefree(req->p.http); Curl_safefree(req->newurl); - Curl_cw_reset(data); + Curl_client_reset(data); #ifndef CURL_DISABLE_DOH if(req->doh) { @@ -114,7 +115,7 @@ void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data) Curl_safefree(req->newurl); if(req->sendbuf_init) Curl_bufq_free(&req->sendbuf); - Curl_cw_reset(data); + Curl_client_reset(data); #ifndef CURL_DISABLE_DOH if(req->doh) { @@ -171,22 +172,6 @@ static CURLcode req_send(struct Curl_easy *data, return result; } -static CURLcode req_send_buffer_add(struct Curl_easy *data, - const char *buf, size_t blen, - size_t hds_len) -{ - CURLcode result = CURLE_OK; - ssize_t n; - n = Curl_bufq_write(&data->req.sendbuf, - (const unsigned char *)buf, blen, &result); - if(n < 0) - return result; - /* We rely on a SOFTLIMIT on sendbuf, so it can take all data in */ - DEBUGASSERT((size_t)n == blen); - data->req.sendbuf_hds_len += hds_len; - return CURLE_OK; -} - static CURLcode req_send_buffer_flush(struct Curl_easy *data) { CURLcode result = CURLE_OK; @@ -200,8 +185,19 @@ static CURLcode req_send_buffer_flush(struct Curl_easy *data) break; Curl_bufq_skip(&data->req.sendbuf, nwritten); - if(hds_len) + if(hds_len) { data->req.sendbuf_hds_len -= CURLMIN(hds_len, nwritten); + if(!data->req.sendbuf_hds_len) { + /* all request headers sent */ + if(data->req.exp100 == EXP100_SENDING_REQUEST) { + /* We are now waiting for a reply from the server or + * a timeout on our side */ + data->req.exp100 = EXP100_AWAITING_CONTINUE; + data->req.start100 = Curl_now(); + Curl_expire(data, data->set.expect_100_timeout, EXPIRE_100_TIMEOUT); + } + } + } /* leave if we could not send all. Maybe network blocking or * speed limits on transfer */ if(nwritten < blen) @@ -228,9 +224,41 @@ CURLcode Curl_req_flush(struct Curl_easy *data) return CURLE_OK; } -CURLcode Curl_req_send(struct Curl_easy *data, - const char *buf, size_t blen, - size_t hds_len) +#ifndef USE_HYPER + +static CURLcode req_send_buffer_add(struct Curl_easy *data, + const char *buf, size_t blen, + size_t hds_len) +{ + CURLcode result = CURLE_OK; + ssize_t n; + n = Curl_bufq_write(&data->req.sendbuf, + (const unsigned char *)buf, blen, &result); + if(n < 0) + return result; + /* We rely on a SOFTLIMIT on sendbuf, so it can take all data in */ + DEBUGASSERT((size_t)n == blen); + data->req.sendbuf_hds_len += hds_len; + return CURLE_OK; +} + +static ssize_t add_from_client(void *reader_ctx, + unsigned char *buf, size_t buflen, + CURLcode *err) +{ + struct Curl_easy *data = reader_ctx; + size_t nread; + bool eos; + + *err = Curl_client_read(data, (char *)buf, buflen, &nread, &eos); + if(*err) + return -1; + if(eos) + data->req.eos_read = TRUE; + return (ssize_t)nread; +} + +CURLcode Curl_req_send(struct Curl_easy *data, struct dynbuf *buf) { CURLcode result; @@ -242,14 +270,25 @@ CURLcode Curl_req_send(struct Curl_easy *data, * important for TLS libraries that expect this. * We *could* optimized for non-TLS transfers, but that would mean * separate code paths and seems not worth it. */ - result = req_send_buffer_add(data, buf, blen, hds_len); + result = req_send_buffer_add(data, Curl_dyn_ptr(buf), Curl_dyn_len(buf), + Curl_dyn_len(buf)); if(result) return result; + + if((data->req.exp100 == EXP100_SEND_DATA) && + !Curl_bufq_is_full(&data->req.sendbuf)) { + ssize_t nread = Curl_bufq_sipn(&data->req.sendbuf, 0, + add_from_client, data, &result); + if(nread < 0 && result != CURLE_AGAIN) + return result; + } + result = req_send_buffer_flush(data); if(result == CURLE_AGAIN) result = CURLE_OK; return result; } +#endif /* !USE_HYPER */ bool Curl_req_want_send(struct Curl_easy *data) { diff --git a/lib/request.h b/lib/request.h index 54c784f6a88..e7af4a8e537 100644 --- a/lib/request.h +++ b/lib/request.h @@ -64,8 +64,6 @@ struct SingleRequest { curl_off_t bytecount; /* total number of bytes read */ curl_off_t writebytecount; /* number of bytes written */ - size_t pendingheader; /* this many bytes left to send is actually - header and not body */ struct curltime start; /* transfer started at this time */ unsigned int headerbytecount; /* received server headers (not CONNECT headers) */ @@ -87,9 +85,12 @@ struct SingleRequest { enum expect100 exp100; /* expect 100 continue state */ enum upgrade101 upgr101; /* 101 upgrade state */ - /* Client Writer stack, handles trasnfer- and content-encodings, protocol + /* Client Writer stack, handles transfer- and content-encodings, protocol * checks, pausing by client callbacks. */ struct Curl_cwriter *writer_stack; + /* Client Reader stack, handles transfer- and content-encodings, protocol + * checks, pausing by client callbacks. */ + struct Curl_creader *reader_stack; struct bufq sendbuf; /* data which needs to be send to the server */ size_t sendbuf_hds_len; /* amount of header bytes in sendbuf */ time_t timeofdoc; @@ -137,6 +138,7 @@ struct SingleRequest { BIT(content_range); /* set TRUE if Content-Range: was found */ BIT(download_done); /* set to TRUE when download is complete */ BIT(eos_written); /* iff EOS has been written to client */ + BIT(eos_read); /* iff EOS has been read from the client */ BIT(upload_done); /* set to TRUE when doing chunked transfer-encoding upload and we're uploading the last chunk */ BIT(ignorebody); /* we read a response-body but we ignore it! */ @@ -190,24 +192,18 @@ void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data); */ void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data); - +#ifndef USE_HYPER /** - * Send request bytes for transfer. If not all could be sent + * Send request headers. If not all could be sent * they will be buffered. Use `Curl_req_flush()` to make sure * bytes are really send. * @param data the transfer making the request - * @param buf the bytes to send - * @param blen the number of bytes to send - * @param hds_len the number of bytes from the start that are headers + * @param buf the complete header bytes, no body * @return CURLE_OK (on blocking with *pnwritten == 0) or error. */ -CURLcode Curl_req_send(struct Curl_easy *data, - const char *buf, size_t blen, - size_t hds_len); +CURLcode Curl_req_send(struct Curl_easy *data, struct dynbuf *buf); -/* Convenience for sending only header bytes */ -#define Curl_req_send_hds(data, buf, blen) \ - Curl_req_send((data), (buf), (blen), (blen)) +#endif /* !USE_HYPER */ /** * Flush all buffered request bytes. diff --git a/lib/rtsp.c b/lib/rtsp.c index a4c70a6b448..a0da9f138af 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -241,6 +241,8 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) const char *p_userpwd = NULL; *done = TRUE; + /* Initialize a dynamic send buffer */ + Curl_dyn_init(&req_buffer, DYN_RTSP_REQ_HEADER); rtsp->CSeq_sent = data->state.rtsp_next_client_CSeq; rtsp->CSeq_recv = 0; @@ -311,8 +313,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) if(rtspreq == RTSPREQ_RECEIVE) { Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); - - return result; + goto out; } p_session_id = data->set.str[STRING_RTSP_SESSION_ID]; @@ -320,7 +321,8 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) (rtspreq & ~(RTSPREQ_OPTIONS | RTSPREQ_DESCRIBE | RTSPREQ_SETUP))) { failf(data, "Refusing to issue an RTSP request [%s] without a session ID.", p_request); - return CURLE_BAD_FUNCTION_ARGUMENT; + result = CURLE_BAD_FUNCTION_ARGUMENT; + goto out; } /* Stream URI. Default to server '*' if not specified */ @@ -347,7 +349,8 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) else { failf(data, "Refusing to issue an RTSP SETUP without a Transport: header."); - return CURLE_BAD_FUNCTION_ARGUMENT; + result = CURLE_BAD_FUNCTION_ARGUMENT; + goto out; } p_transport = data->state.aptr.rtsp_transport; @@ -366,9 +369,10 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) data->state.aptr.accept_encoding = aprintf("Accept-Encoding: %s\r\n", data->set.str[STRING_ENCODING]); - if(!data->state.aptr.accept_encoding) - return CURLE_OUT_OF_MEMORY; - + if(!data->state.aptr.accept_encoding) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } p_accept_encoding = data->state.aptr.accept_encoding; } } @@ -390,7 +394,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) result = Curl_http_output_auth(data, conn, p_request, HTTPREQ_GET, p_stream_uri, FALSE); if(result) - return result; + goto out; p_proxyuserpwd = data->state.aptr.proxyuserpwd; p_userpwd = data->state.aptr.userpwd; @@ -424,23 +428,22 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) */ if(Curl_checkheaders(data, STRCONST("CSeq"))) { failf(data, "CSeq cannot be set as a custom header."); - return CURLE_RTSP_CSEQ_ERROR; + result = CURLE_RTSP_CSEQ_ERROR; + goto out; } if(Curl_checkheaders(data, STRCONST("Session"))) { failf(data, "Session ID cannot be set as a custom header."); - return CURLE_BAD_FUNCTION_ARGUMENT; + result = CURLE_BAD_FUNCTION_ARGUMENT; + goto out; } - /* Initialize a dynamic send buffer */ - Curl_dyn_init(&req_buffer, DYN_RTSP_REQ_HEADER); - result = Curl_dyn_addf(&req_buffer, "%s %s RTSP/1.0\r\n" /* Request Stream-URI RTSP/1.0 */ "CSeq: %ld\r\n", /* CSeq */ p_request, p_stream_uri, rtsp->CSeq_sent); if(result) - return result; + goto out; /* * Rather than do a normal alloc line, keep the session_id unformatted @@ -449,7 +452,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) if(p_session_id) { result = Curl_dyn_addf(&req_buffer, "Session: %s\r\n", p_session_id); if(result) - return result; + goto out; } /* @@ -481,17 +484,17 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) Curl_safefree(data->state.aptr.userpwd); if(result) - return result; + goto out; if((rtspreq == RTSPREQ_SETUP) || (rtspreq == RTSPREQ_DESCRIBE)) { result = Curl_add_timecondition(data, &req_buffer); if(result) - return result; + goto out; } result = Curl_add_custom_headers(data, FALSE, &req_buffer); if(result) - return result; + goto out; if(rtspreq == RTSPREQ_ANNOUNCE || rtspreq == RTSPREQ_SET_PARAMETER || @@ -500,13 +503,24 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) if(data->state.upload) { putsize = data->state.infilesize; data->state.httpreq = HTTPREQ_PUT; - + result = Client_reader_set_fread(data, putsize); + if(result) + goto out; } else { postsize = (data->state.infilesize != -1)? data->state.infilesize: (data->set.postfields? (curl_off_t)strlen(data->set.postfields):0); data->state.httpreq = HTTPREQ_POST; + if(postsize > 0 && data->set.postfields) + result = Client_reader_set_buf(data, data->set.postfields, + (size_t)postsize); + else if(!postsize) + result = Client_reader_set_null(data); + else + result = Client_reader_set_fread(data, postsize); + if(result) + goto out; } if(putsize > 0 || postsize > 0) { @@ -518,7 +532,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) "Content-Length: %" CURL_FORMAT_CURL_OFF_T"\r\n", (data->state.upload ? putsize : postsize)); if(result) - return result; + goto out; } if(rtspreq == RTSPREQ_SET_PARAMETER || @@ -528,7 +542,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) STRCONST("Content-Type: " "text/parameters\r\n")); if(result) - return result; + goto out; } } @@ -538,7 +552,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) STRCONST("Content-Type: " "application/sdp\r\n")); if(result) - return result; + goto out; } } @@ -550,31 +564,27 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) data->req.no_body = TRUE; } } + else { + result = Client_reader_set_null(data); + if(result) + goto out; + } /* RTSP never allows chunked transfer */ data->req.forbidchunk = TRUE; /* Finish the request buffer */ result = Curl_dyn_addn(&req_buffer, STRCONST("\r\n")); if(result) - return result; - - if(postsize > 0) { - result = Curl_dyn_addn(&req_buffer, data->set.postfields, - (size_t)postsize); - if(result) - return result; - } + goto out; /* issue the request */ - result = Curl_req_send_hds(data, Curl_dyn_ptr(&req_buffer), - Curl_dyn_len(&req_buffer)); - Curl_dyn_free(&req_buffer); + result = Curl_req_send(data, &req_buffer); if(result) { failf(data, "Failed sending RTSP request"); - return result; + goto out; } - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, putsize?FIRSTSOCKET:-1); + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, FIRSTSOCKET); /* Increment the CSeq on success */ data->state.rtsp_next_client_CSeq++; @@ -586,7 +596,8 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) if(Curl_pgrsUpdate(data)) result = CURLE_ABORTED_BY_CALLBACK; } - +out: + Curl_dyn_free(&req_buffer); return result; } diff --git a/lib/sendf.c b/lib/sendf.c index 54ed6fb2956..8fe9c756143 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -59,7 +59,7 @@ #include "memdebug.h" -static CURLcode do_init_stack(struct Curl_easy *data); +static CURLcode do_init_writer_stack(struct Curl_easy *data); /* Curl_client_write() sends data to the write callback(s) @@ -81,7 +81,7 @@ CURLcode Curl_client_write(struct Curl_easy *data, ((type & ~(CLIENTWRITE_INFO|CLIENTWRITE_EOS)) == 0)); if(!data->req.writer_stack) { - result = do_init_stack(data); + result = do_init_writer_stack(data); if(result) return result; DEBUGASSERT(data->req.writer_stack); @@ -90,16 +90,33 @@ CURLcode Curl_client_write(struct Curl_easy *data, return Curl_cwriter_write(data, data->req.writer_stack, type, buf, blen); } -void Curl_cw_reset(struct Curl_easy *data) +static void cl_reset_writer(struct Curl_easy *data) { struct Curl_cwriter *writer = data->req.writer_stack; - while(writer) { data->req.writer_stack = writer->next; writer->cwt->do_close(data, writer); free(writer); writer = data->req.writer_stack; } +} + +static void cl_reset_reader(struct Curl_easy *data) +{ + struct Curl_creader *reader = data->req.reader_stack; + while(reader) { + data->req.reader_stack = reader->next; + reader->crt->do_close(data, reader); + free(reader); + reader = data->req.reader_stack; + } +} + +void Curl_client_reset(struct Curl_easy *data) +{ + DEBUGF(infof(data, "Curl_client_reset()")); + cl_reset_reader(data); + cl_reset_writer(data); data->req.bytecount = 0; data->req.headerline = 0; @@ -338,7 +355,7 @@ size_t Curl_cwriter_count(struct Curl_easy *data, Curl_cwriter_phase phase) return n; } -static CURLcode do_init_stack(struct Curl_easy *data) +static CURLcode do_init_writer_stack(struct Curl_easy *data) { struct Curl_cwriter *writer; CURLcode result; @@ -374,7 +391,7 @@ CURLcode Curl_cwriter_add(struct Curl_easy *data, struct Curl_cwriter **anchor = &data->req.writer_stack; if(!*anchor) { - result = do_init_stack(data); + result = do_init_writer_stack(data); if(result) return result; } @@ -426,3 +443,502 @@ void Curl_cwriter_remove_by_name(struct Curl_easy *data, } } +CURLcode Curl_creader_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, size_t *nread, bool *eos) +{ + if(!reader) + return CURLE_READ_ERROR; + return reader->crt->do_read(data, reader, buf, blen, nread, eos); +} + +CURLcode Curl_creader_def_init(struct Curl_easy *data, + struct Curl_creader *reader) +{ + (void)data; + (void)reader; + return CURLE_OK; +} + +void Curl_creader_def_close(struct Curl_easy *data, + struct Curl_creader *reader) +{ + (void)data; + (void)reader; +} + +bool Curl_creader_def_needs_rewind(struct Curl_easy *data, + struct Curl_creader *reader) +{ + (void)data; + (void)reader; + return FALSE; +} + +struct cr_in_ctx { + struct Curl_creader super; + curl_off_t total_len; + curl_off_t read_len; + CURLcode error_result; + BIT(seen_eos); + BIT(errored); + BIT(has_used_cb); +}; + +static CURLcode cr_in_init(struct Curl_easy *data, struct Curl_creader *reader) +{ + struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + (void)data; + ctx->total_len = -1; + ctx->read_len = 0; + return CURLE_OK; +} + +/* Real client reader to installed client callbacks. */ +static CURLcode cr_in_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *pnread, bool *peos) +{ + struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + size_t nread; + + /* Once we have errored, we will return the same error forever */ + if(ctx->errored) { + *pnread = 0; + *peos = FALSE; + return ctx->error_result; + } + if(ctx->seen_eos) { + *pnread = 0; + *peos = TRUE; + return CURLE_OK; + } + /* respect length limitations */ + if(ctx->total_len >= 0) { + curl_off_t remain = ctx->total_len - ctx->read_len; + if(remain <= 0) + blen = 0; + else if(remain < (curl_off_t)blen) + blen = (size_t)remain; + } + nread = 0; + if(data->state.fread_func && blen) { + Curl_set_in_callback(data, true); + nread = data->state.fread_func(buf, 1, blen, data->state.in); + Curl_set_in_callback(data, false); + ctx->has_used_cb = TRUE; + } + + switch(nread) { + case 0: + if((ctx->total_len >= 0) && (ctx->read_len < ctx->total_len)) { + failf(data, "client read function EOF fail, only " + "only %"CURL_FORMAT_CURL_OFF_T"/%"CURL_FORMAT_CURL_OFF_T + " of needed bytes read", ctx->read_len, ctx->total_len); + return CURLE_READ_ERROR; + } + *pnread = 0; + *peos = TRUE; + ctx->seen_eos = TRUE; + break; + + case CURL_READFUNC_ABORT: + failf(data, "operation aborted by callback"); + *pnread = 0; + *peos = FALSE; + ctx->errored = TRUE; + ctx->error_result = CURLE_ABORTED_BY_CALLBACK; + return CURLE_ABORTED_BY_CALLBACK; + + case CURL_READFUNC_PAUSE: + if(data->conn->handler->flags & PROTOPT_NONETWORK) { + /* protocols that work without network cannot be paused. This is + actually only FILE:// just now, and it can't pause since the transfer + isn't done using the "normal" procedure. */ + failf(data, "Read callback asked for PAUSE when not supported"); + return CURLE_READ_ERROR; + } + /* CURL_READFUNC_PAUSE pauses read callbacks that feed socket writes */ + data->req.keepon |= KEEP_SEND_PAUSE; /* mark socket send as paused */ + *pnread = 0; + *peos = FALSE; + break; /* nothing was read */ + + default: + if(nread > blen) { + /* the read function returned a too large value */ + failf(data, "read function returned funny value"); + *pnread = 0; + *peos = FALSE; + ctx->errored = TRUE; + ctx->error_result = CURLE_READ_ERROR; + return CURLE_READ_ERROR; + } + ctx->read_len += nread; + *pnread = nread; + *peos = FALSE; + break; + } + DEBUGF(infof(data, "cr_in_read(len=%zu, total=%"CURL_FORMAT_CURL_OFF_T + ", read=%"CURL_FORMAT_CURL_OFF_T") -> %d, %zu, %d", + blen, ctx->total_len, ctx->read_len, CURLE_OK, *pnread, *peos)); + return CURLE_OK; +} + +static bool cr_in_needs_rewind(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + (void)data; + return ctx->has_used_cb; +} + +static const struct Curl_crtype cr_in = { + "cr-in", + cr_in_init, + cr_in_read, + Curl_creader_def_close, + cr_in_needs_rewind, + sizeof(struct cr_in_ctx) +}; + +CURLcode Curl_creader_create(struct Curl_creader **preader, + struct Curl_easy *data, + const struct Curl_crtype *crt, + Curl_creader_phase phase) +{ + struct Curl_creader *reader; + CURLcode result = CURLE_OUT_OF_MEMORY; + + DEBUGASSERT(crt->creader_size >= sizeof(struct Curl_creader)); + reader = (struct Curl_creader *) calloc(1, crt->creader_size); + if(!reader) + goto out; + + reader->crt = crt; + reader->phase = phase; + result = crt->do_init(data, reader); + +out: + *preader = result? NULL : reader; + if(result) + free(reader); + return result; +} + +void Curl_creader_free(struct Curl_easy *data, struct Curl_creader *reader) +{ + if(reader) { + reader->crt->do_close(data, reader); + free(reader); + } +} + +struct cr_lc_ctx { + struct Curl_creader super; + struct bufq buf; + BIT(read_eos); /* we read an EOS from the next reader */ + BIT(eos); /* we have returned an EOS */ +}; + +static CURLcode cr_lc_init(struct Curl_easy *data, struct Curl_creader *reader) +{ + struct cr_lc_ctx *ctx = (struct cr_lc_ctx *)reader; + (void)data; + Curl_bufq_init2(&ctx->buf, (16 * 1024), 1, BUFQ_OPT_SOFT_LIMIT); + return CURLE_OK; +} + +static void cr_lc_close(struct Curl_easy *data, struct Curl_creader *reader) +{ + struct cr_lc_ctx *ctx = (struct cr_lc_ctx *)reader; + (void)data; + Curl_bufq_free(&ctx->buf); +} + +/* client reader doing line end conversions. */ +static CURLcode cr_lc_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *pnread, bool *peos) +{ + struct cr_lc_ctx *ctx = (struct cr_lc_ctx *)reader; + CURLcode result; + size_t nread, i, start, n; + bool eos; + + if(ctx->eos) { + *pnread = 0; + *peos = TRUE; + return CURLE_OK; + } + + if(Curl_bufq_is_empty(&ctx->buf)) { + if(ctx->read_eos) { + ctx->eos = TRUE; + *pnread = 0; + *peos = TRUE; + return CURLE_OK; + } + /* Still getting data form the next reader, ctx->buf is empty */ + result = Curl_creader_read(data, reader->next, buf, blen, &nread, &eos); + if(result) + return result; + ctx->read_eos = eos; + + if(!nread || !memchr(buf, '\n', nread)) { + /* nothing to convert, return this right away */ + if(ctx->read_eos) + ctx->eos = TRUE; + *pnread = nread; + *peos = ctx->eos; + return CURLE_OK; + } + + /* at least one \n needs conversion to '\r\n', place into ctx->buf */ + for(i = start = 0; i < nread; ++i) { + if(buf[i] != '\n') + continue; + /* on a soft limit bufq, we do not need to check length */ + result = Curl_bufq_cwrite(&ctx->buf, buf + start, i - start, &n); + if(!result) + result = Curl_bufq_cwrite(&ctx->buf, STRCONST("\r\n"), &n); + if(result) + return result; + start = i + 1; + if(!data->set.crlf && (data->state.infilesize != -1)) { + /* we're here only because FTP is in ASCII mode... + bump infilesize for the LF we just added */ + data->state.infilesize++; + /* comment: this might work for FTP, but in HTTP we could not change + * the content length after having started the request... */ + } + } + } + + DEBUGASSERT(!Curl_bufq_is_empty(&ctx->buf)); + *peos = FALSE; + result = Curl_bufq_cread(&ctx->buf, buf, blen, pnread); + if(!result && ctx->read_eos && Curl_bufq_is_empty(&ctx->buf)) { + /* no more data, read all, done. */ + ctx->eos = TRUE; + *peos = TRUE; + } + return result; +} + +static const struct Curl_crtype cr_lc = { + "cr-lineconv", + cr_lc_init, + cr_lc_read, + cr_lc_close, + Curl_creader_def_needs_rewind, + sizeof(struct cr_lc_ctx) +}; + +static CURLcode cr_lc_add(struct Curl_easy *data) +{ + struct Curl_creader *reader = NULL; + CURLcode result; + + result = Curl_creader_create(&reader, data, &cr_lc, + CURL_CR_TRANSFER_ENCODE); + if(!result) + result = Curl_creader_add(data, reader); + + if(result && reader) + Curl_creader_free(data, reader); + return result; +} + +static CURLcode do_init_reader_stack(struct Curl_easy *data, + const struct Curl_crtype *crt, + struct Curl_creader **preader) +{ + CURLcode result; + + DEBUGASSERT(!data->req.reader_stack); + result = Curl_creader_create(preader, data, crt, CURL_CR_CLIENT); + if(result) + return result; + data->req.reader_stack = *preader; + + if(data->set.crlf +#ifdef CURL_DO_LINEEND_CONV + || data->state.prefer_ascii +#endif + ) { + result = cr_lc_add(data); + if(result) + return result; + } + + return result; +} + +CURLcode Client_reader_set_fread(struct Curl_easy *data, curl_off_t len) +{ + CURLcode result; + struct Curl_creader *r; + + cl_reset_reader(data); + result = do_init_reader_stack(data, &cr_in, &r); + if(!result && r) { + struct cr_in_ctx *ctx = (struct cr_in_ctx *)r; + DEBUGASSERT(r->crt == &cr_in); + ctx->total_len = len; + } + return result; +} + +CURLcode Curl_creader_add(struct Curl_easy *data, + struct Curl_creader *reader) +{ + CURLcode result; + struct Curl_creader **anchor = &data->req.reader_stack; + + if(!*anchor) { + result = Client_reader_set_fread(data, data->state.infilesize); + if(result) + return result; + } + + /* Insert the writer as first in its phase. + * Skip existing readers of lower phases. */ + while(*anchor && (*anchor)->phase < reader->phase) + anchor = &((*anchor)->next); + reader->next = *anchor; + *anchor = reader; + return CURLE_OK; +} + +CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen, + size_t *nread, bool *eos) +{ + CURLcode result; + + DEBUGASSERT(buf); + DEBUGASSERT(blen); + DEBUGASSERT(nread); + DEBUGASSERT(eos); + + if(!data->req.reader_stack) { + result = Client_reader_set_fread(data, data->state.infilesize); + if(result) + return result; + DEBUGASSERT(data->req.reader_stack); + } + + result = Curl_creader_read(data, data->req.reader_stack, buf, blen, + nread, eos); + return result; +} + +bool Curl_client_read_needs_rewind(struct Curl_easy *data) +{ + struct Curl_creader *reader = data->req.reader_stack; + while(reader) { + if(reader->crt->needs_rewind(data, reader)) + return TRUE; + reader = reader->next; + } + return FALSE; +} + +static CURLcode cr_null_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *pnread, bool *peos) +{ + (void)data; + (void)reader; + (void)buf; + (void)blen; + *pnread = 0; + *peos = TRUE; + return CURLE_OK; +} + +static const struct Curl_crtype cr_null = { + "cr-null", + Curl_creader_def_init, + cr_null_read, + Curl_creader_def_close, + Curl_creader_def_needs_rewind, + sizeof(struct Curl_creader) +}; + +CURLcode Client_reader_set_null(struct Curl_easy *data) +{ + struct Curl_creader *r; + + cl_reset_reader(data); + return do_init_reader_stack(data, &cr_null, &r); +} + +struct cr_buf_ctx { + struct Curl_creader super; + const char *buf; + size_t blen; + size_t index; +}; + +static CURLcode cr_buf_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *pnread, bool *peos) +{ + struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)reader; + size_t nread = ctx->blen - ctx->index; + + (void)data; + if(!nread || !ctx->buf) { + *pnread = 0; + *peos = TRUE; + } + else { + if(nread > blen) + nread = blen; + memcpy(buf, ctx->buf + ctx->index, nread); + *pnread = nread; + ctx->index += nread; + *peos = (ctx->index == ctx->blen); + } + return CURLE_OK; +} + +static bool cr_buf_needs_rewind(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)reader; + (void)data; + return ctx->index > 0; +} + +static const struct Curl_crtype cr_buf = { + "cr-buf", + Curl_creader_def_init, + cr_buf_read, + Curl_creader_def_close, + cr_buf_needs_rewind, + sizeof(struct cr_buf_ctx) +}; + +CURLcode Client_reader_set_buf(struct Curl_easy *data, + const char *buf, size_t blen) +{ + CURLcode result; + struct Curl_creader *r; + + cl_reset_reader(data); + result = do_init_reader_stack(data, &cr_buf, &r); + if(!result && r) { + struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)r; + DEBUGASSERT(r->crt == &cr_buf); + ctx->buf = buf; + ctx->blen = blen; + ctx->index = 0; + } + return result; +} diff --git a/lib/sendf.h b/lib/sendf.h index 9d3d5946ab3..7876dd99320 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -61,7 +61,7 @@ CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *ptr, /** * Free all resources related to client writing. */ -void Curl_cw_reset(struct Curl_easy *data); +void Curl_client_reset(struct Curl_easy *data); /** * Client Writers - a chain passing transfer BODY data to the client. @@ -175,4 +175,107 @@ void Curl_cwriter_def_close(struct Curl_easy *data, struct Curl_cwriter *writer); +/* Client Reader Type, provides the implementation */ +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); + size_t creader_size; /* sizeof() allocated struct Curl_creader */ +}; + +/* Phase a reader operates at. */ +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; + +/* Client reader instance */ +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 */ +}; + +/** + * Default implementations for do_init, do_write, do_close that + * do nothing and pass the data through. + */ +CURLcode Curl_creader_def_init(struct Curl_easy *data, + struct Curl_creader *reader); +void Curl_creader_def_close(struct Curl_easy *data, + struct Curl_creader *reader); +bool Curl_creader_def_needs_rewind(struct Curl_easy *data, + struct Curl_creader *reader); + +/** + * Convenience method for calling `reader->do_read()` that + * checks for NULL reader. + */ +CURLcode Curl_creader_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, size_t *nread, bool *eos); + +/** + * Create a new creader instance with given type and phase. Is not + * inserted into the writer chain by this call. + * Invokes `reader->do_init()`. + */ +CURLcode Curl_creader_create(struct Curl_creader **preader, + struct Curl_easy *data, + const struct Curl_crtype *cr_handler, + Curl_creader_phase phase); + +/** + * Free a creader instance. + * Invokes `reader->do_close()`. + */ +void Curl_creader_free(struct Curl_easy *data, struct Curl_creader *reader); + +/** + * Adds a reader to the transfer's reader chain. + * The readers `phase` determines where in the chain it is inserted. + */ +CURLcode Curl_creader_add(struct Curl_easy *data, + struct Curl_creader *reader); + +/** + * Read at most `blen` bytes at `buf` from the client. + * @param date the transfer to read client bytes for + * @param buf the memory location to read to + * @param blen the amount of memory at `buf` + * @param nread on return the number of bytes read into `buf` + * @param eos TRUE iff bytes are the end of data from client + * @return CURLE_OK on successful read (even 0 length) or error + */ +CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen, + size_t *nread, bool *eos) WARN_UNUSED_RESULT; + +/** + * TRUE iff client reader needs rewing before it can be used for + * a retry request. + */ +bool Curl_client_read_needs_rewind(struct Curl_easy *data); + +/** + * Set the client reader to provide 0 bytes, immediate EOS. + */ +CURLcode Client_reader_set_null(struct Curl_easy *data); + +/** + * Set the client reader the reads from fread callback. + */ +CURLcode Client_reader_set_fread(struct Curl_easy *data, curl_off_t len); + +/** + * Set the client reader the reads from the supplied buf (NOT COPIED). + */ +CURLcode Client_reader_set_buf(struct Curl_easy *data, + const char *buf, size_t blen); + #endif /* HEADER_CURL_SENDF_H */ diff --git a/lib/smb.c b/lib/smb.c index 72991f955ec..404dd84f43d 100644 --- a/lib/smb.c +++ b/lib/smb.c @@ -811,8 +811,9 @@ static CURLcode smb_send_and_recv(struct Curl_easy *data, void **msg) if(!smbc->send_size && smbc->upload_size) { size_t nread = smbc->upload_size > (size_t)data->set.upload_buffer_size ? (size_t)data->set.upload_buffer_size : smbc->upload_size; - data->req.upload_fromhere = data->state.ulbuf; - result = Curl_fillreadbuffer(data, nread, &nread); + bool eos; + + result = Curl_client_read(data, data->state.ulbuf, nread, &nread, &eos); if(result && result != CURLE_AGAIN) return result; if(!nread) diff --git a/lib/tftp.c b/lib/tftp.c index 1b487796056..a99fe1ddcf1 100644 --- a/lib/tftp.c +++ b/lib/tftp.c @@ -708,6 +708,8 @@ static CURLcode tftp_tx(struct tftp_state_data *state, tftp_event_t event) struct SingleRequest *k = &data->req; size_t cb; /* Bytes currently read */ char buffer[STRERROR_LEN]; + char *bufptr; + bool eos; switch(event) { @@ -771,13 +773,14 @@ static CURLcode tftp_tx(struct tftp_state_data *state, tftp_event_t event) * data block. * */ state->sbytes = 0; - state->data->req.upload_fromhere = (char *)state->spacket.data + 4; + bufptr = (char *)state->spacket.data + 4; do { - result = Curl_fillreadbuffer(data, state->blksize - state->sbytes, &cb); + result = Curl_client_read(data, bufptr, state->blksize - state->sbytes, + &cb, &eos); if(result) return result; state->sbytes += (int)cb; - state->data->req.upload_fromhere += cb; + bufptr += cb; } while(state->sbytes < state->blksize && cb); sbytes = sendto(state->sockfd, (void *) state->spacket.data, diff --git a/lib/transfer.c b/lib/transfer.c index 43d6f6f4b4c..cbda03a2e7a 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -125,250 +125,6 @@ CURLcode Curl_get_upload_buffer(struct Curl_easy *data) return CURLE_OK; } -#ifndef CURL_DISABLE_HTTP -/* - * This function will be called to loop through the trailers buffer - * until no more data is available for sending. - */ -static size_t trailers_read(char *buffer, size_t size, size_t nitems, - void *raw) -{ - struct Curl_easy *data = (struct Curl_easy *)raw; - struct dynbuf *trailers_buf = &data->state.trailers_buf; - size_t bytes_left = Curl_dyn_len(trailers_buf) - - data->state.trailers_bytes_sent; - size_t to_copy = (size*nitems < bytes_left) ? size*nitems : bytes_left; - if(to_copy) { - memcpy(buffer, - Curl_dyn_ptr(trailers_buf) + data->state.trailers_bytes_sent, - to_copy); - data->state.trailers_bytes_sent += to_copy; - } - return to_copy; -} - -static size_t trailers_left(void *raw) -{ - struct Curl_easy *data = (struct Curl_easy *)raw; - struct dynbuf *trailers_buf = &data->state.trailers_buf; - return Curl_dyn_len(trailers_buf) - data->state.trailers_bytes_sent; -} -#endif - -/* - * This function will call the read callback to fill our buffer with data - * to upload. - */ -CURLcode Curl_fillreadbuffer(struct Curl_easy *data, size_t bytes, - size_t *nreadp) -{ - size_t buffersize = bytes; - size_t nread; - curl_read_callback readfunc = NULL; - void *extra_data = NULL; - int eof_index = 0; - -#ifndef CURL_DISABLE_HTTP - if(data->state.trailers_state == TRAILERS_INITIALIZED) { - struct curl_slist *trailers = NULL; - CURLcode result; - int trailers_ret_code; - - /* at this point we already verified that the callback exists - so we compile and store the trailers buffer, then proceed */ - infof(data, - "Moving trailers state machine from initialized to sending."); - data->state.trailers_state = TRAILERS_SENDING; - Curl_dyn_init(&data->state.trailers_buf, DYN_TRAILERS); - - data->state.trailers_bytes_sent = 0; - Curl_set_in_callback(data, true); - trailers_ret_code = data->set.trailer_callback(&trailers, - data->set.trailer_data); - Curl_set_in_callback(data, false); - if(trailers_ret_code == CURL_TRAILERFUNC_OK) { - result = Curl_http_compile_trailers(trailers, &data->state.trailers_buf, - data); - } - else { - failf(data, "operation aborted by trailing headers callback"); - *nreadp = 0; - result = CURLE_ABORTED_BY_CALLBACK; - } - if(result) { - Curl_dyn_free(&data->state.trailers_buf); - curl_slist_free_all(trailers); - return result; - } - infof(data, "Successfully compiled trailers."); - curl_slist_free_all(trailers); - } -#endif - -#ifndef CURL_DISABLE_HTTP - /* if we are transmitting trailing data, we don't need to write - a chunk size so we skip this */ - if(data->req.upload_chunky && - data->state.trailers_state == TRAILERS_NONE) { - /* if chunked Transfer-Encoding */ - buffersize -= (8 + 2 + 2); /* 32bit hex + CRLF + CRLF */ - data->req.upload_fromhere += (8 + 2); /* 32bit hex + CRLF */ - } - - if(data->state.trailers_state == TRAILERS_SENDING) { - /* if we're here then that means that we already sent the last empty chunk - but we didn't send a final CR LF, so we sent 0 CR LF. We then start - pulling trailing data until we have no more at which point we - simply return to the previous point in the state machine as if - nothing happened. - */ - readfunc = trailers_read; - extra_data = (void *)data; - eof_index = 1; - } - else -#endif - { - readfunc = data->state.fread_func; - extra_data = data->state.in; - } - - if(!data->req.fread_eof[eof_index]) { - Curl_set_in_callback(data, true); - nread = readfunc(data->req.upload_fromhere, 1, buffersize, extra_data); - Curl_set_in_callback(data, false); - /* make sure the callback is not called again after EOF */ - data->req.fread_eof[eof_index] = !nread; - } - else - nread = 0; - - if(nread == CURL_READFUNC_ABORT) { - failf(data, "operation aborted by callback"); - *nreadp = 0; - return CURLE_ABORTED_BY_CALLBACK; - } - if(nread == CURL_READFUNC_PAUSE) { - struct SingleRequest *k = &data->req; - - if(data->conn->handler->flags & PROTOPT_NONETWORK) { - /* protocols that work without network cannot be paused. This is - actually only FILE:// just now, and it can't pause since the transfer - isn't done using the "normal" procedure. */ - failf(data, "Read callback asked for PAUSE when not supported"); - return CURLE_READ_ERROR; - } - - /* CURL_READFUNC_PAUSE pauses read callbacks that feed socket writes */ - k->keepon |= KEEP_SEND_PAUSE; /* mark socket send as paused */ - if(data->req.upload_chunky) { - /* Back out the preallocation done above */ - data->req.upload_fromhere -= (8 + 2); - } - *nreadp = 0; - - return CURLE_OK; /* nothing was read */ - } - else if(nread > buffersize) { - /* the read function returned a too large value */ - *nreadp = 0; - failf(data, "read function returned funny value"); - return CURLE_READ_ERROR; - } - -#ifndef CURL_DISABLE_HTTP - if(!data->req.forbidchunk && data->req.upload_chunky) { - /* if chunked Transfer-Encoding - * build chunk: - * - * CRLF - * CRLF - */ - /* On non-ASCII platforms the may or may not be - translated based on state.prefer_ascii while the protocol - portion must always be translated to the network encoding. - To further complicate matters, line end conversion might be - done later on, so we need to prevent CRLFs from becoming - CRCRLFs if that's the case. To do this we use bare LFs - here, knowing they'll become CRLFs later on. - */ - - bool added_crlf = FALSE; - int hexlen = 0; - const char *endofline_native; - const char *endofline_network; - - if( -#ifdef CURL_DO_LINEEND_CONV - (data->state.prefer_ascii) || -#endif - (data->set.crlf)) { - /* \n will become \r\n later on */ - endofline_native = "\n"; - endofline_network = "\x0a"; - } - else { - endofline_native = "\r\n"; - endofline_network = "\x0d\x0a"; - } - - /* if we're not handling trailing data, proceed as usual */ - if(data->state.trailers_state != TRAILERS_SENDING) { - char hexbuffer[11] = ""; - hexlen = msnprintf(hexbuffer, sizeof(hexbuffer), - "%zx%s", nread, endofline_native); - - /* move buffer pointer */ - data->req.upload_fromhere -= hexlen; - nread += hexlen; - - /* copy the prefix to the buffer, leaving out the NUL */ - memcpy(data->req.upload_fromhere, hexbuffer, hexlen); - - /* always append ASCII CRLF to the data unless - we have a valid trailer callback */ - if((nread-hexlen) == 0 && - data->set.trailer_callback != NULL && - data->state.trailers_state == TRAILERS_NONE) { - data->state.trailers_state = TRAILERS_INITIALIZED; - } - else { - memcpy(data->req.upload_fromhere + nread, - endofline_network, - strlen(endofline_network)); - added_crlf = TRUE; - } - } - - if(data->state.trailers_state == TRAILERS_SENDING && - !trailers_left(data)) { - Curl_dyn_free(&data->state.trailers_buf); - data->state.trailers_state = TRAILERS_DONE; - data->set.trailer_data = NULL; - data->set.trailer_callback = NULL; - /* mark the transfer as done */ - data->req.upload_done = TRUE; - infof(data, "Signaling end of chunked upload after trailers."); - } - else - if((nread - hexlen) == 0 && - data->state.trailers_state != TRAILERS_INITIALIZED) { - /* mark this as done once this chunk is transferred */ - data->req.upload_done = TRUE; - infof(data, - "Signaling end of chunked upload via terminating chunk."); - } - - if(added_crlf) - nread += strlen(endofline_network); /* for the added end of line */ - } -#endif - - *nreadp = nread; - - return CURLE_OK; -} - static int data_pending(struct Curl_easy *data) { struct connectdata *conn = data->conn; @@ -616,13 +372,12 @@ static CURLcode readwrite_upload(struct Curl_easy *data, struct connectdata *conn, int *didwhat) { - ssize_t i, si; size_t bytes_written; CURLcode result; ssize_t nread; /* number of bytes read */ - bool sending_http_headers = FALSE; struct SingleRequest *k = &data->req; + (void)conn; *didwhat |= KEEP_SEND; if(!(k->keepon & KEEP_SEND_PAUSE)) { @@ -636,13 +391,14 @@ static CURLcode readwrite_upload(struct Curl_easy *data, do { curl_off_t nbody; ssize_t offset = 0; + bool eos; if(0 != k->upload_present && k->upload_present < curl_upload_refill_watermark(data) && !k->upload_chunky &&/*(variable sized chunked header; append not safe)*/ !k->upload_done && /*!(k->upload_done once k->upload_present sent)*/ - !(k->writebytecount + (curl_off_t)k->upload_present - - (curl_off_t)k->pendingheader == data->state.infilesize)) { + !(k->writebytecount + (curl_off_t)k->upload_present == + data->state.infilesize)) { offset = k->upload_present; } @@ -661,10 +417,8 @@ static CURLcode readwrite_upload(struct Curl_easy *data, /* HTTP pollution, this should be written nicer to become more protocol agnostic. */ size_t fillcount; - struct HTTP *http = k->p.http; - if((k->exp100 == EXP100_SENDING_REQUEST) && - (http->sending == HTTPSEND_BODY)) { + if(k->exp100 == EXP100_SENDING_REQUEST) { /* If this call is to send body data, we must take some action: We have sent off the full HTTP 1.1 request, and we shall now go into the Expect: 100 state and await such a header */ @@ -677,18 +431,10 @@ static CURLcode readwrite_upload(struct Curl_easy *data, break; } - if(conn->handler->protocol&(PROTO_FAMILY_HTTP|CURLPROTO_RTSP)) { - if(http->sending == HTTPSEND_REQUEST) - /* We're sending the HTTP request headers, not the data. - Remember that so we don't change the line endings. */ - sending_http_headers = TRUE; - else - sending_http_headers = FALSE; - } - k->upload_fromhere += offset; - result = Curl_fillreadbuffer(data, data->set.upload_buffer_size-offset, - &fillcount); + result = Curl_client_read(data, k->upload_fromhere, + data->set.upload_buffer_size-offset, + &fillcount, &eos); k->upload_fromhere -= offset; if(result) return result; @@ -712,59 +458,6 @@ static CURLcode readwrite_upload(struct Curl_easy *data, /* store number of bytes available for upload */ k->upload_present = nread; - /* convert LF to CRLF if so asked */ - if((!sending_http_headers) && ( -#ifdef CURL_DO_LINEEND_CONV - /* always convert if we're FTPing in ASCII mode */ - (data->state.prefer_ascii) || -#endif - (data->set.crlf))) { - /* Do we need to allocate a scratch buffer? */ - if(!data->state.scratch) { - data->state.scratch = malloc(2 * data->set.upload_buffer_size); - if(!data->state.scratch) { - failf(data, "Failed to alloc scratch buffer"); - - return CURLE_OUT_OF_MEMORY; - } - } - - /* - * ASCII/EBCDIC Note: This is presumably a text (not binary) - * transfer so the data should already be in ASCII. - * That means the hex values for ASCII CR (0x0d) & LF (0x0a) - * must be used instead of the escape sequences \r & \n. - */ - if(offset) - memcpy(data->state.scratch, k->upload_fromhere, offset); - for(i = offset, si = offset; i < nread; i++, si++) { - if(k->upload_fromhere[i] == 0x0a) { - data->state.scratch[si++] = 0x0d; - data->state.scratch[si] = 0x0a; - if(!data->set.crlf) { - /* we're here only because FTP is in ASCII mode... - bump infilesize for the LF we just added */ - if(data->state.infilesize != -1) - data->state.infilesize++; - } - } - else - data->state.scratch[si] = k->upload_fromhere[i]; - } - - if(si != nread) { - /* only perform the special operation if we really did replace - anything */ - nread = si; - - /* upload from the new (replaced) buffer instead */ - k->upload_fromhere = data->state.scratch; - - /* set the new amount too */ - k->upload_present = nread; - } - } - #ifndef CURL_DISABLE_SMTP if(conn->handler->protocol & PROTO_FAMILY_SMTP) { result = Curl_smtp_escape_eob(data, nread, offset); @@ -796,17 +489,7 @@ static CURLcode readwrite_upload(struct Curl_easy *data, } #endif - if(k->pendingheader) { - /* parts of what was sent was header */ - size_t n = CURLMIN(k->pendingheader, bytes_written); - /* show the data before we change the pointer upload_fromhere */ - Curl_debug(data, CURLINFO_HEADER_OUT, k->upload_fromhere, n); - k->pendingheader -= n; - nbody = bytes_written - n; /* size of the written body part */ - } - else - nbody = bytes_written; - + nbody = bytes_written; if(nbody) { /* show the data before we change the pointer upload_fromhere */ Curl_debug(data, CURLINFO_DATA_OUT, @@ -1014,7 +697,6 @@ CURLcode Curl_readwrite(struct Curl_easy *data, * The transfer has been performed. Just make some general checks before * returning. */ - if(!(data->req.no_body) && (k->size != -1) && (k->bytecount != k->size) && #ifdef CURL_DO_LINEEND_CONV @@ -1587,8 +1269,7 @@ CURLcode Curl_retry_request(struct Curl_easy *data, char **url) transferred! */ - if((conn->handler->protocol&PROTO_FAMILY_HTTP) && - data->req.writebytecount) { + if(Curl_client_read_needs_rewind(data)) { data->state.rewindbeforesend = TRUE; infof(data, "state.rewindbeforesend = TRUE"); } @@ -1611,7 +1292,6 @@ void Curl_xfer_setup( { struct SingleRequest *k = &data->req; struct connectdata *conn = data->conn; - struct HTTP *http = data->req.p.http; bool want_send = Curl_req_want_send(data); DEBUGASSERT(conn != NULL); @@ -1664,8 +1344,7 @@ void Curl_xfer_setup( state info where we wait for the 100-return code */ if((data->state.expect100header) && - (conn->handler->protocol&PROTO_FAMILY_HTTP) && - (http->sending == HTTPSEND_BODY)) { + (conn->handler->protocol&PROTO_FAMILY_HTTP)) { /* wait with write until we either got 100-continue or a timeout */ k->exp100 = EXP100_AWAITING_CONTINUE; k->start100 = Curl_now(); diff --git a/lib/transfer.h b/lib/transfer.h index 81c70718077..a4af1899e51 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -48,8 +48,6 @@ CURLcode Curl_follow(struct Curl_easy *data, char *newurl, CURLcode Curl_readwrite(struct Curl_easy *data, bool *done); int Curl_single_getsock(struct Curl_easy *data, struct connectdata *conn, curl_socket_t *socks); -CURLcode Curl_fillreadbuffer(struct Curl_easy *data, size_t bytes, - size_t *nreadp); CURLcode Curl_retry_request(struct Curl_easy *data, char **url); bool Curl_meets_timecondition(struct Curl_easy *data, time_t timeofdoc); CURLcode Curl_get_upload_buffer(struct Curl_easy *data); diff --git a/scripts/singleuse.pl b/scripts/singleuse.pl index c4e1bed51ce..5124697a300 100755 --- a/scripts/singleuse.pl +++ b/scripts/singleuse.pl @@ -44,6 +44,8 @@ my %wl = ( 'curlx_uztoso' => 'cmdline tool use', 'Curl_xfer_write_resp' => 'internal api', + 'Curl_creader_def_init' => 'internal api', + 'Curl_creader_def_close' => 'internal api', ); my %api = ( diff --git a/tests/data/test513 b/tests/data/test513 index ae413bbc939..cc97336105c 100644 --- a/tests/data/test513 +++ b/tests/data/test513 @@ -34,14 +34,6 @@ http://%HOSTIP:%HTTPPORT/%TESTNUMBER # Verify data after the test has been "shot" -%if !hyper -POST /%TESTNUMBER HTTP/1.1 -Host: %HOSTIP:%HTTPPORT -Accept: */* -Content-Length: 1 -Content-Type: application/x-www-form-urlencoded - -%endif # 42 - aborted by callback diff --git a/tests/data/test579 b/tests/data/test579 index 476499ff075..68fce50d4d0 100644 --- a/tests/data/test579 +++ b/tests/data/test579 @@ -77,6 +77,8 @@ http://%HOSTIP:%HTTPPORT/%TESTNUMBER %LOGDIR/ip%TESTNUMBER Progress callback called with UL 0 out of 0 +Progress callback called with UL 5 out of 0 +Progress callback called with UL 0 out of 0 Progress callback called with UL 8 out of 0 Progress callback called with UL 16 out of 0 Progress callback called with UL 26 out of 0 diff --git a/tests/http/test_14_auth.py b/tests/http/test_14_auth.py index 6d3db593129..9fd120584a6 100644 --- a/tests/http/test_14_auth.py +++ b/tests/http/test_14_auth.py @@ -103,9 +103,9 @@ def test_14_04_digest_large_pw(self, env: Env, httpd, nghttpx, repeat, proto): def test_14_05_basic_large_pw(self, env: Env, httpd, nghttpx, repeat, proto): if proto == 'h3' and not env.have_h3(): pytest.skip("h3 not supported") - if proto == 'h3' and env.curl_uses_lib('quiche'): + if proto == 'h3' and not env.curl_uses_lib('ngtcp2'): # See - pytest.skip("quiche has problems with large requests") + pytest.skip("quiche/openssl-quic have problems with large requests") # just large enough that nghttp2 will submit password = 'x' * (47 * 1024) fdata = os.path.join(env.gen_dir, 'data-10m') diff --git a/tests/libtest/lib547.c b/tests/libtest/lib547.c index dbe657e9d31..e65f33b78b9 100644 --- a/tests/libtest/lib547.c +++ b/tests/libtest/lib547.c @@ -47,7 +47,7 @@ static size_t readcallback(char *ptr, } (*counter)++; /* bump */ - if(size * nmemb > strlen(UPLOADTHIS)) { + if(size * nmemb >= strlen(UPLOADTHIS)) { fprintf(stderr, "READ!\n"); strcpy(ptr, UPLOADTHIS); return strlen(UPLOADTHIS); diff --git a/tests/libtest/lib555.c b/tests/libtest/lib555.c index 6e3e30b1374..2e595b6863e 100644 --- a/tests/libtest/lib555.c +++ b/tests/libtest/lib555.c @@ -54,7 +54,7 @@ static size_t readcallback(char *ptr, } (*counter)++; /* bump */ - if(size * nmemb > strlen(uploadthis)) { + if(size * nmemb >= strlen(uploadthis)) { fprintf(stderr, "READ!\n"); strcpy(ptr, uploadthis); return strlen(uploadthis); From 32e0544dc8f5bcdbcff5a3305fe6b41cb303e3d2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 28 Feb 2024 11:40:04 +0100 Subject: [PATCH 393/509] cmdline-opts/_VERSION: provide %VERSION correctly ... so that it does not get included verbatim in the output. Fixes a regression shipped in 8.6.0. Also fix a format mistake in form.md Closes #13008 --- docs/cmdline-opts/_VERSION.md | 8 ++++---- docs/cmdline-opts/form.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/cmdline-opts/_VERSION.md b/docs/cmdline-opts/_VERSION.md index 4c759f14705..e0228fe9cdb 100644 --- a/docs/cmdline-opts/_VERSION.md +++ b/docs/cmdline-opts/_VERSION.md @@ -2,10 +2,10 @@ # 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. +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 diff --git a/docs/cmdline-opts/form.md b/docs/cmdline-opts/form.md index 25b4bc73050..44d958a4683 100644 --- a/docs/cmdline-opts/form.md +++ b/docs/cmdline-opts/form.md @@ -29,10 +29,10 @@ 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. +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. 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 From 50838095290cc6307893bb25ee62e87dc4d8d807 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 28 Feb 2024 13:20:59 +0100 Subject: [PATCH 394/509] tests: add test1598 for POST with trailers - test POST fields with trailers and chunked encoding Ref: #12938 Closes #13009 --- tests/data/Makefile.inc | 2 +- tests/data/test1598 | 59 ++++++++++++++++++++ tests/libtest/Makefile.inc | 5 +- tests/libtest/lib1598.c | 107 +++++++++++++++++++++++++++++++++++++ 4 files changed, 171 insertions(+), 2 deletions(-) create mode 100644 tests/data/test1598 create mode 100644 tests/libtest/lib1598.c diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index b80ffb618e5..2d2b87a8640 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -201,7 +201,7 @@ test1558 test1559 test1560 test1561 test1562 test1563 test1564 test1565 \ test1566 test1567 test1568 test1569 test1570 \ \ test1590 test1591 test1592 test1593 test1594 test1595 test1596 test1597 \ -\ +test1598 \ test1600 test1601 test1602 test1603 test1604 test1605 test1606 test1607 \ test1608 test1609 test1610 test1611 test1612 test1613 test1614 test1615 \ \ diff --git a/tests/data/test1598 b/tests/data/test1598 new file mode 100644 index 00000000000..eb0ade1040f --- /dev/null +++ b/tests/data/test1598 @@ -0,0 +1,59 @@ + + + +HTTP +HTTP POST +CURLOPT_HTTPTRAILER_FUNCTION +CURLOPT_HTTPTRAILER_DATA + + + +# Server-side + + +HTTP/1.0 200 OK swsclose +Date: Tue, 09 Nov 2010 14:49:00 GMT +Server: test-server/fake + + +# Client-side + + +http + + +http + + +HTTP POST with trailers at the end + + +lib%TESTNUMBER + + +http://%HOSTIP:%HTTPPORT/bzz/%TESTNUMBER + + +more than one byte + + + +# Verify data after the test has been "shot" + + +POST /bzz/%TESTNUMBER HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +Accept: */* +Trailer: my-super-awesome-trailer, my-other-awesome-trailer +Transfer-Encoding: chunked +Content-Type: application/x-www-form-urlencoded + +11 +xxx=yyy&aaa=bbbbb +0 +my-super-awesome-trailer: trail1 +my-other-awesome-trailer: trail2 + + + + diff --git a/tests/libtest/Makefile.inc b/tests/libtest/Makefile.inc index 1a61deb6234..32cc180b02b 100644 --- a/tests/libtest/Makefile.inc +++ b/tests/libtest/Makefile.inc @@ -62,7 +62,7 @@ noinst_PROGRAMS = chkhostname libauthretry libntlmconnect libprereq \ lib1540 lib1542 lib1543 lib1545 \ lib1550 lib1551 lib1552 lib1553 lib1554 lib1555 lib1556 lib1557 \ lib1558 lib1559 lib1560 lib1564 lib1565 lib1567 lib1568 lib1569 \ - lib1591 lib1592 lib1593 lib1594 lib1596 lib1597 \ + lib1591 lib1592 lib1593 lib1594 lib1596 lib1597 lib1598 \ \ lib1662 \ \ @@ -534,6 +534,9 @@ lib1596_CPPFLAGS = $(AM_CPPFLAGS) -DLIB1596 lib1597_SOURCES = lib1597.c $(SUPPORTFILES) $(TESTUTIL) $(WARNLESS) lib1597_LDADD = $(TESTUTIL_LIBS) +lib1598_SOURCES = lib1598.c $(SUPPORTFILES) $(TESTUTIL) $(WARNLESS) +lib1598_LDADD = $(TESTUTIL_LIBS) + lib1662_SOURCES = lib1662.c $(SUPPORTFILES) $(TESTUTIL) $(WARNLESS) lib1662_LDADD = $(TESTUTIL_LIBS) diff --git a/tests/libtest/lib1598.c b/tests/libtest/lib1598.c new file mode 100644 index 00000000000..63cdfcfb64c --- /dev/null +++ b/tests/libtest/lib1598.c @@ -0,0 +1,107 @@ +/*************************************************************************** + * _ _ ____ _ + * 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 + * + ***************************************************************************/ + +/* + * This unit test PUT http data over proxy. Proxy header will be different + * from server http header + */ + +#include "test.h" +#include +#include "memdebug.h" + +/* + * carefully not leak memory on OOM + */ +static int trailers_callback(struct curl_slist **list, void *userdata) +{ + struct curl_slist *nlist = NULL; + struct curl_slist *nlist2 = NULL; + (void)userdata; + nlist = curl_slist_append(*list, "my-super-awesome-trailer: trail1"); + if(nlist) + nlist2 = curl_slist_append(nlist, "my-other-awesome-trailer: trail2"); + if(nlist2) { + *list = nlist2; + return CURL_TRAILERFUNC_OK; + } + else { + curl_slist_free_all(nlist); + return CURL_TRAILERFUNC_ABORT; + } +} + +static const char *post_data = "xxx=yyy&aaa=bbbbb"; + +int test(char *URL) +{ + CURL *curl = NULL; + CURLcode res = CURLE_FAILED_INIT; + /* http and proxy header list */ + struct curl_slist *hhl = NULL, *list; + + if(curl_global_init(CURL_GLOBAL_ALL) != CURLE_OK) { + fprintf(stderr, "curl_global_init() failed\n"); + return TEST_ERR_MAJOR_BAD; + } + + + curl = curl_easy_init(); + if(!curl) { + fprintf(stderr, "curl_easy_init() failed\n"); + curl_global_cleanup(); + return TEST_ERR_MAJOR_BAD; + } + + hhl = curl_slist_append(hhl, "Trailer: my-super-awesome-trailer," + " my-other-awesome-trailer"); + if(!hhl) + goto test_cleanup; + if(hhl) { + list = curl_slist_append(hhl, "Transfer-Encoding: chunked"); + if(!list) + goto test_cleanup; + hhl = list; + } + + test_setopt(curl, CURLOPT_URL, URL); + test_setopt(curl, CURLOPT_HTTPHEADER, hhl); + test_setopt(curl, CURLOPT_POSTFIELDSIZE, strlen(post_data)); + test_setopt(curl, CURLOPT_POSTFIELDS, post_data); + test_setopt(curl, CURLOPT_TRAILERFUNCTION, trailers_callback); + test_setopt(curl, CURLOPT_TRAILERDATA, NULL); + test_setopt(curl, CURLOPT_VERBOSE, 1L); + + res = curl_easy_perform(curl); + +test_cleanup: + + curl_easy_cleanup(curl); + + curl_slist_free_all(hhl); + + curl_global_cleanup(); + + return (int)res; +} From dcf382453f44d7e86df984775342cbc433019ad4 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 29 Feb 2024 13:04:23 -0800 Subject: [PATCH 395/509] github/labeler: improve the match patterns --- .github/labeler.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/labeler.yml b/.github/labeler.yml index cef2789d84e..bd5a027c790 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -75,13 +75,13 @@ 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.*}' + - '{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.*}' + - '{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: @@ -93,7 +93,7 @@ documentation: - all: - changed-files: - any-glob-to-all-files: - - '{**/*.md,**/*.txt,**/*.1,**/*.3,CHANGES,docs/**,GIT-INFO,LICENSES/**,README,RELEASE-NOTES}' + - '{.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/**,GIT-INFO,LICENSES/**,README,RELEASE-NOTES,scripts/cd*}' - all-globs-to-all-files: # negative matches - '!**/CMakeLists.txt' @@ -127,7 +127,7 @@ 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}' + - '{.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: @@ -152,7 +152,7 @@ libcurl API: - changed-files: - any-glob-to-any-file: - 'docs/libcurl/ABI.md' - - 'docs/libcurl/curl_*.3' + - 'docs/libcurl/curl_*.md' - 'include/curl/**' logging: From 89733e2dd26b51c16b2c9f090881127dbba58ce8 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 8 Feb 2024 11:34:34 -0800 Subject: [PATCH 396/509] configure: build & install shell completions when enabled The --with-fish-functions-dir and --with-zsh-functions-dir options currently have no effect on a normal build because the scripts/ directory where they're used is not built. Add scripts/ to a normal build and change the completion options to default to off to preserve the existing behaviour. Closes: #12906 --- Makefile.am | 2 +- configure.ac | 10 ++++++---- scripts/Makefile.am | 12 ++++++++---- 3 files changed, 15 insertions(+), 9 deletions(-) diff --git a/Makefile.am b/Makefile.am index bc995f1ed56..5bb0e254822 100644 --- a/Makefile.am +++ b/Makefile.am @@ -134,7 +134,7 @@ CLEANFILES = $(VC14_LIBVCXPROJ) $(VC14_SRCVCXPROJ) \ bin_SCRIPTS = curl-config -SUBDIRS = lib src +SUBDIRS = lib src scripts DIST_SUBDIRS = $(SUBDIRS) tests packages scripts include docs pkgconfigdir = $(libdir)/pkgconfig diff --git a/configure.ac b/configure.ac index 09d5364f4de..c1877771927 100644 --- a/configure.ac +++ b/configure.ac @@ -3483,10 +3483,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) @@ -3497,6 +3497,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 @@ -3508,10 +3509,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 @@ -3527,6 +3528,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! diff --git a/scripts/Makefile.am b/scripts/Makefile.am index ae95e85acc9..690c328e281 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -40,7 +40,7 @@ $(ZSH_COMPLETION_FUNCTION_FILENAME): completion.pl if CROSSCOMPILING @echo "NOTICE: we can't generate zsh completion when cross-compiling!" else # if not cross-compiling: - @if ! test -x "$(PERL)"; then echo "No perl: can't install completion.pl"; exit 0; fi + @if ! test -x "$(PERL)"; then echo "No perl: can't install completion script"; exit 0; fi $(PERL) $(srcdir)/completion.pl --curl $(top_builddir)/src/curl$(EXEEXT) --shell zsh > $@ endif @@ -48,16 +48,20 @@ $(FISH_COMPLETION_FUNCTION_FILENAME): completion.pl if CROSSCOMPILING @echo "NOTICE: we can't generate fish completion when cross-compiling!" else # if not cross-compiling: - @if ! test -x "$(PERL)"; then echo "No perl: can't install completion.pl"; exit 0; fi + @if ! test -x "$(PERL)"; then echo "No perl: can't install completion scriptl"; exit 0; fi $(PERL) $(srcdir)/completion.pl --curl $(top_builddir)/src/curl$(EXEEXT) --shell fish > $@ endif install-data-local: if CROSSCOMPILING - @echo "NOTICE: we can't install zsh completion when cross-compiling!" + @echo "NOTICE: we can't install completion scripts when cross-compiling!" else # if not cross-compiling: +if USE_ZSH_COMPLETION $(MKDIR_P) $(DESTDIR)$(ZSH_FUNCTIONS_DIR) - $(MKDIR_P) $(DESTDIR)$(FISH_FUNCTIONS_DIR) $(INSTALL_DATA) $(ZSH_COMPLETION_FUNCTION_FILENAME) $(DESTDIR)$(ZSH_FUNCTIONS_DIR)/$(ZSH_COMPLETION_FUNCTION_FILENAME) +endif +if USE_FISH_COMPLETION + $(MKDIR_P) $(DESTDIR)$(FISH_FUNCTIONS_DIR) $(INSTALL_DATA) $(FISH_COMPLETION_FUNCTION_FILENAME) $(DESTDIR)$(FISH_FUNCTIONS_DIR)/$(FISH_COMPLETION_FUNCTION_FILENAME) endif +endif From 2cd78f525c714e59c54650f5182db65bdfaf6fe4 Mon Sep 17 00:00:00 2001 From: RainRat Date: Thu, 29 Feb 2024 11:55:28 -0800 Subject: [PATCH 397/509] misc: Fix typos in docs and lib This fixes miscellaneous typos and duplicated words in the docs, lib and test comments and a few user facing errorstrings. Author: RainRat on Github Reviewed-by: Daniel Gustafsson Reviewed-by: Dan Fandrich Closes: #13019 --- docs/CONNECTION-FILTERS.md | 2 +- docs/cmdline-opts/MANPAGE.md | 2 +- docs/cmdline-opts/_VARIABLES.md | 2 +- docs/cmdline-opts/gen.pl | 2 +- docs/cmdline-opts/resolve.md | 2 +- docs/examples/ghiper.c | 2 +- docs/libcurl/libcurl.m4 | 2 +- docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md | 2 +- docs/libcurl/opts/CURLSHOPT_SHARE.md | 2 +- docs/libcurl/opts/CURLSHOPT_UNSHARE.md | 2 +- lib/asyn-ares.c | 2 +- lib/cfilters.h | 2 +- lib/curl_des.c | 2 +- lib/hostip.c | 2 +- lib/http.c | 2 +- lib/mprintf.c | 2 +- lib/socks_gssapi.c | 2 +- lib/vquic/curl_ngtcp2.c | 2 +- lib/vquic/curl_osslq.c | 2 +- lib/vssh/libssh2.c | 2 +- scripts/cmp-config.pl | 2 +- tests/ftpserver.pl | 2 +- tests/http/test_14_auth.py | 2 +- tests/libtest/lib518.c | 2 +- tests/libtest/lib537.c | 2 +- tests/server/sockfilt.c | 2 +- 26 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/CONNECTION-FILTERS.md b/docs/CONNECTION-FILTERS.md index 6c0ed2bc764..06ec0293f7e 100644 --- a/docs/CONNECTION-FILTERS.md +++ b/docs/CONNECTION-FILTERS.md @@ -267,7 +267,7 @@ conn[curl.se] --> SETUP[TCP] --> HAPPY-EYEBALLS --> TCP[2a04:4e42:c00::347]:443 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. -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 and have happy eyeballing for QUIC: +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: ``` * create connection for --http3-only https://curl.se diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 51310564fe7..16c203608df 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -88,7 +88,7 @@ Angle brackets (`<>`) need to be escaped when used in text like `\<` and ### Headers -The `#` header can be used by non-option files and it produces produces a +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 diff --git a/docs/cmdline-opts/_VARIABLES.md b/docs/cmdline-opts/_VARIABLES.md index 60ee6d00d14..77e9523b9a9 100644 --- a/docs/cmdline-opts/_VARIABLES.md +++ b/docs/cmdline-opts/_VARIABLES.md @@ -41,4 +41,4 @@ as POST data: --expand-data "{{fix:trim:url}}" https://example.com/ -Command line variables and expansions were added in in 8.3.0. +Command line variables and expansions were added in 8.3.0. diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index 17beab5b8bb..9105529998f 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -897,7 +897,7 @@ sub mainpage { my $f = $_; chomp $f; if($f =~ /^#/) { - # stardard comment + # standard comment next; } if(/^%options/) { diff --git a/docs/cmdline-opts/resolve.md b/docs/cmdline-opts/resolve.md index c5c5eddd5d3..70d039aa8c3 100644 --- a/docs/cmdline-opts/resolve.md +++ b/docs/cmdline-opts/resolve.md @@ -43,4 +43,4 @@ 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. +Support for the '+' prefix was added in 7.75.0. diff --git a/docs/examples/ghiper.c b/docs/examples/ghiper.c index 4510edae506..ec7174ff7f6 100644 --- a/docs/examples/ghiper.c +++ b/docs/examples/ghiper.c @@ -22,7 +22,7 @@ * ***************************************************************************/ /* - * multi socket API usage together with with glib2 + * multi socket API usage together with glib2 * */ /* Example application source code using the multi socket interface to diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index e4a518b5ce1..044d7afbd93 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -169,7 +169,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], LIBS="$LIBCURL $LIBS" AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include ]],[[ -/* Try and use a few common options to force a failure if we are +/* Try to use a few common options to force a failure if we are missing symbols or cannot link. */ int x; curl_easy_setopt(NULL,CURLOPT_URL,NULL); diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md index a199648c13c..58eba18d521 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md @@ -73,7 +73,7 @@ The data is header (or header-like) data sent to the peer. ## CURLINFO_DATA_IN The data is the unprocessed protocol data received from the peer. Even if the -data is encoded or compressed, it is not not provided decoded nor decompressed +data is encoded or compressed, it is not provided decoded nor decompressed to this callback. If you need the data in decoded and decompressed form, use CURLOPT_WRITEFUNCTION(3). diff --git a/docs/libcurl/opts/CURLSHOPT_SHARE.md b/docs/libcurl/opts/CURLSHOPT_SHARE.md index 8f742a40213..7866640ccc6 100644 --- a/docs/libcurl/opts/CURLSHOPT_SHARE.md +++ b/docs/libcurl/opts/CURLSHOPT_SHARE.md @@ -27,7 +27,7 @@ CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_SHARE, long type); The *type* parameter specifies what specific data that should be shared and kept in the share object that was created with curl_share_init(3). -The given *type* must be be one of the values described below. You can set +The given *type* must be one of the values described below. You can set CURLSHOPT_SHARE(3) multiple times with different data arguments to have the share object share multiple types of data. Unset a type again by setting CURLSHOPT_UNSHARE(3). diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md index 4a11bfa55dd..e6c2340135d 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md +++ b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md @@ -28,7 +28,7 @@ CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNSHARE, long type); The *type* parameter specifies what specific data that should no longer be shared and kept in the share object that was created with curl_share_init(3). In other words, stop sharing that data in this -shared object. The given *type* must be be one of the values described +shared object. The given *type* must be one of the values described below. You can set CURLSHOPT_UNSHARE(3) multiple times with different data arguments to remove multiple types from the shared object. Add data to share again with CURLSHOPT_SHARE(3). diff --git a/lib/asyn-ares.c b/lib/asyn-ares.c index 76efba78ad5..2290a71ef46 100644 --- a/lib/asyn-ares.c +++ b/lib/asyn-ares.c @@ -850,7 +850,7 @@ CURLcode Curl_set_dns_servers(struct Curl_easy *data, /* If server is NULL or empty, this would purge all DNS servers * from ares library, which will cause any and all queries to fail. * So, just return OK if none are configured and don't actually make - * any changes to c-ares. This lets c-ares use it's defaults, which + * any changes to c-ares. This lets c-ares use its defaults, which * it gets from the OS (for instance from /etc/resolv.conf on Linux). */ if(!(servers && servers[0])) diff --git a/lib/cfilters.h b/lib/cfilters.h index 92a2132fe0e..c90b1f4bc2b 100644 --- a/lib/cfilters.h +++ b/lib/cfilters.h @@ -402,7 +402,7 @@ void Curl_conn_adjust_pollset(struct Curl_easy *data, /** * Receive data through the filter chain at `sockindex` for connection * `data->conn`. Copy at most `len` bytes into `buf`. Return the - * actuel number of bytes copied or a negative value on error. + * actual number of bytes copied or a negative value on error. * The error code is placed into `*code`. */ ssize_t Curl_cf_recv(struct Curl_easy *data, int sockindex, char *buf, diff --git a/lib/curl_des.c b/lib/curl_des.c index b77763f2684..f8d2b2cc696 100644 --- a/lib/curl_des.c +++ b/lib/curl_des.c @@ -36,7 +36,7 @@ * Curl_des_set_odd_parity() * * This is used to apply odd parity to the given byte array. It is typically - * used by when a cryptography engines doesn't have it's own version. + * used by when a cryptography engine doesn't have its own version. * * The function is a port of the Java based oddParity() function over at: * diff --git a/lib/hostip.c b/lib/hostip.c index 4f44d348f6e..442817d119f 100644 --- a/lib/hostip.c +++ b/lib/hostip.c @@ -288,7 +288,7 @@ static struct Curl_dns_entry *fetch_addr(struct Curl_easy *data, size_t entry_len = create_hostcache_id(hostname, 0, port, entry_id, sizeof(entry_id)); - /* See if its already in our dns cache */ + /* See if it's already in our dns cache */ dns = Curl_hash_pick(data->dns.hostcache, entry_id, entry_len + 1); /* No entry found in cache, check if we might have a wildcard entry */ diff --git a/lib/http.c b/lib/http.c index 870de3830cf..3f17f7cd92f 100644 --- a/lib/http.c +++ b/lib/http.c @@ -4125,7 +4125,7 @@ CURLcode Curl_http_write_resp(struct Curl_easy *data, blen -= consumed; buf += consumed; /* either all was consumed in header parsing, or we have data left - * and are done with heders, e.g. it is BODY data */ + * and are done with headers, e.g. it is BODY data */ DEBUGASSERT(!blen || !data->req.header); if(!data->req.header && (blen || is_eos)) { /* BODY data after header been parsed, write and consume */ diff --git a/lib/mprintf.c b/lib/mprintf.c index 5695253eb3b..4c60d13305b 100644 --- a/lib/mprintf.c +++ b/lib/mprintf.c @@ -642,7 +642,7 @@ static int parsefmt(const char *format, * On success, the input array describes the type of all arguments and their * values. * - * The function then iterates over the output sengments and outputs them one + * The function then iterates over the output segments and outputs them one * by one until done. Using the appropriate input arguments (if any). * * All output is sent to the 'stream()' callback, one byte at a time. diff --git a/lib/socks_gssapi.c b/lib/socks_gssapi.c index 243715055c2..c0b42b871a9 100644 --- a/lib/socks_gssapi.c +++ b/lib/socks_gssapi.c @@ -475,7 +475,7 @@ CURLcode Curl_SOCKS5_gssapi_negotiate(struct Curl_cfilter *cf, gss_recv_token.length, &actualread); if(result || (actualread != us_length)) { - failf(data, "Failed to receive GSS-API encryptrion type."); + failf(data, "Failed to receive GSS-API encryption type."); gss_release_buffer(&gss_status, &gss_recv_token); gss_delete_sec_context(&gss_status, &gss_context, NULL); return CURLE_COULDNT_CONNECT; diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index a26b3e429d2..7ef1b5e8407 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -1769,7 +1769,7 @@ static CURLcode cf_progress_egress(struct Curl_cfilter *cf, } /* In UDP, there is a maximum theoretical packet paload length and - * a minimum payload length that is "guarantueed" to work. + * a minimum payload length that is "guaranteed" to work. * To detect if this minimum payload can be increased, ngtcp2 sends * now and then a packet payload larger than the minimum. It that * is ACKed by the peer, both parties know that it works and diff --git a/lib/vquic/curl_osslq.c b/lib/vquic/curl_osslq.c index ede60e29d8b..1d78bd71711 100644 --- a/lib/vquic/curl_osslq.c +++ b/lib/vquic/curl_osslq.c @@ -426,7 +426,7 @@ static CURLcode cf_osslq_ssl_err(struct Curl_cfilter *cf, #endif else if((lib == ERR_LIB_SSL) && (reason == SSL_R_PROTOCOL_IS_SHUTDOWN)) { ctx->protocol_shutdown = TRUE; - err_descr = "QUIC connectin has been shut down"; + err_descr = "QUIC connection has been shut down"; result = def_result; } else { diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index 36975420bc3..073c6873db4 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -3272,7 +3272,7 @@ static CURLcode ssh_connect(struct Curl_easy *data, bool *done) #endif /* CURL_LIBSSH2_DEBUG */ /* libcurl MUST to set custom memory functions so that the kbd_callback - funciton's memory allocations can be properled freed */ + function's memory allocations can be properly freed */ sshc->ssh_session = libssh2_session_init_ex(my_libssh2_malloc, my_libssh2_free, my_libssh2_realloc, data); diff --git a/scripts/cmp-config.pl b/scripts/cmp-config.pl index e36fcdd3c40..ebd7c2fb235 100755 --- a/scripts/cmp-config.pl +++ b/scripts/cmp-config.pl @@ -31,7 +31,7 @@ exit; } -# this lists complete lines that will be removed from the the output if +# this lists complete lines that will be removed from the output if # matching my %remove = ( '#define _FILE_OFFSET_BITS 64' => 1, diff --git a/tests/ftpserver.pl b/tests/ftpserver.pl index e250aa1cb69..10abe418c23 100755 --- a/tests/ftpserver.pl +++ b/tests/ftpserver.pl @@ -672,7 +672,7 @@ sub protocolsetup { # Perform the disconnecgt handshake with sockfilt on the secondary connection # (the only connection we actively disconnect). -# This involves waiting for the disconnect acknowledgmeent after the DISC +# This involves waiting for the disconnect acknowledgment after the DISC # command, while throwing away anything else that might come in before # that. sub disc_handshake { diff --git a/tests/http/test_14_auth.py b/tests/http/test_14_auth.py index 9fd120584a6..b90817b62d7 100644 --- a/tests/http/test_14_auth.py +++ b/tests/http/test_14_auth.py @@ -133,7 +133,7 @@ def test_14_06_basic_very_large_pw(self, env: Env, httpd, nghttpx, repeat, proto r = curl.http_upload(urls=[url], data=f'@{fdata}', alpn_proto=proto, extra_args=[ '--basic', '--user', f'test:{password}' ]) - # Depending on protocl, we might have an error sending or + # Depending on protocol, we might have an error sending or # the server might shutdown the connection and we see the error # on receiving assert r.exit_code in [55, 56], f'{self.dump_logs()}' diff --git a/tests/libtest/lib518.c b/tests/libtest/lib518.c index 2000412392f..28a50b22a31 100644 --- a/tests/libtest/lib518.c +++ b/tests/libtest/lib518.c @@ -432,7 +432,7 @@ static int rlimit(int keep_open) } /* free the chunk of memory we were reserving so that it - becomes becomes available to the test */ + becomes available to the test */ free(memchunk); diff --git a/tests/libtest/lib537.c b/tests/libtest/lib537.c index b83e3ce3119..c35aea1b46e 100644 --- a/tests/libtest/lib537.c +++ b/tests/libtest/lib537.c @@ -436,7 +436,7 @@ static int rlimit(int keep_open) } /* free the chunk of memory we were reserving so that it - becomes becomes available to the test */ + becomes available to the test */ free(memchunk); diff --git a/tests/server/sockfilt.c b/tests/server/sockfilt.c index 0900f6564fb..dcfad555440 100644 --- a/tests/server/sockfilt.c +++ b/tests/server/sockfilt.c @@ -893,7 +893,7 @@ static int select_ws(int nfds, fd_set *readfds, fd_set *writefds, /* Perform the disconnect handshake with sockfilt - * This involves waiting for the disconnect acknowledgmeent after the DISC + * This involves waiting for the disconnect acknowledgment after the DISC * command, while throwing away anything else that might come in before * that. */ From 0f7aba83cc9a38d2f3dc0a4af505bdfab517619e Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 29 Feb 2024 23:38:22 -0800 Subject: [PATCH 398/509] configure: Don't make shell completions without perl The code that attempted to skip building the shell completions didn't work properly and tried to build them even if perl wasn't available. This step, as well as the install step, is now properly skipped without perl. Follow-up to 89733e2dd Closes #13022 --- scripts/Makefile.am | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 690c328e281..e3e056ca7a7 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -40,16 +40,16 @@ $(ZSH_COMPLETION_FUNCTION_FILENAME): completion.pl if CROSSCOMPILING @echo "NOTICE: we can't generate zsh completion when cross-compiling!" else # if not cross-compiling: - @if ! test -x "$(PERL)"; then echo "No perl: can't install completion script"; exit 0; fi - $(PERL) $(srcdir)/completion.pl --curl $(top_builddir)/src/curl$(EXEEXT) --shell zsh > $@ + if test -z "$(PERL)"; then echo "No perl: can't install completion script"; else \ + $(PERL) $(srcdir)/completion.pl --curl $(top_builddir)/src/curl$(EXEEXT) --shell zsh > $@ ; fi endif $(FISH_COMPLETION_FUNCTION_FILENAME): completion.pl if CROSSCOMPILING @echo "NOTICE: we can't generate fish completion when cross-compiling!" else # if not cross-compiling: - @if ! test -x "$(PERL)"; then echo "No perl: can't install completion scriptl"; exit 0; fi - $(PERL) $(srcdir)/completion.pl --curl $(top_builddir)/src/curl$(EXEEXT) --shell fish > $@ + if test -z "$(PERL)"; then echo "No perl: can't install completion script"; else \ + $(PERL) $(srcdir)/completion.pl --curl $(top_builddir)/src/curl$(EXEEXT) --shell fish > $@ ; fi endif install-data-local: @@ -57,11 +57,15 @@ if CROSSCOMPILING @echo "NOTICE: we can't install completion scripts when cross-compiling!" else # if not cross-compiling: if USE_ZSH_COMPLETION - $(MKDIR_P) $(DESTDIR)$(ZSH_FUNCTIONS_DIR) - $(INSTALL_DATA) $(ZSH_COMPLETION_FUNCTION_FILENAME) $(DESTDIR)$(ZSH_FUNCTIONS_DIR)/$(ZSH_COMPLETION_FUNCTION_FILENAME) + if test -n "$(PERL)"; then \ + $(MKDIR_P) $(DESTDIR)$(ZSH_FUNCTIONS_DIR); \ + $(INSTALL_DATA) $(ZSH_COMPLETION_FUNCTION_FILENAME) $(DESTDIR)$(ZSH_FUNCTIONS_DIR)/$(ZSH_COMPLETION_FUNCTION_FILENAME) ; \ + fi endif if USE_FISH_COMPLETION - $(MKDIR_P) $(DESTDIR)$(FISH_FUNCTIONS_DIR) - $(INSTALL_DATA) $(FISH_COMPLETION_FUNCTION_FILENAME) $(DESTDIR)$(FISH_FUNCTIONS_DIR)/$(FISH_COMPLETION_FUNCTION_FILENAME) + if test -n "$(PERL)"; then \ + $(MKDIR_P) $(DESTDIR)$(FISH_FUNCTIONS_DIR); \ + $(INSTALL_DATA) $(FISH_COMPLETION_FUNCTION_FILENAME) $(DESTDIR)$(FISH_FUNCTIONS_DIR)/$(FISH_COMPLETION_FUNCTION_FILENAME) ; \ + fi endif endif From 57777a262a48398ca41ad4e978882d093dd64727 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 10 Nov 2023 01:41:13 -0800 Subject: [PATCH 399/509] docs: Update minimal binary size in INSTALL.md Include more options to reduce binary size. --- docs/INSTALL.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 703e59e51fb..e8559ea4a78 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -461,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`, - ./configure CFLAGS='-Os' LDFLAGS='-Wl,-Bsymbolic'... +For example, this is how to combine a few of these options: + + ./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. @@ -474,7 +480,7 @@ 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 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) @@ -488,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) @@ -516,23 +526,14 @@ 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 results in a lower total size than dynamically linking. From dff74ae8bb274ebc9ffb43419481c85b9584eb41 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 1 Mar 2024 01:06:28 -0800 Subject: [PATCH 400/509] appveyor: Properly skip if only CircleCI is changed --- appveyor.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/appveyor.yml b/appveyor.yml index 039e040a15d..7fd1a6629cb 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -292,7 +292,7 @@ branches: skip_commits: files: - '.azure-pipelines.yml' - - '.circleci/**/*' + - '.circleci/*' - '.cirrus.yml' - '.github/**/*' - 'packages/**/*' From ddb87160f5ce72b7ce6c7395e9cd528617cd0e20 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 1 Mar 2024 01:07:02 -0800 Subject: [PATCH 401/509] ftp: Mark a const buffer as const --- lib/ftp.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ftp.c b/lib/ftp.c index 4deb841b3ae..8881bd364a3 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -272,7 +272,7 @@ static CURLcode ftp_cw_lc_write(struct Curl_easy *data, struct Curl_cwriter *writer, int type, const char *buf, size_t blen) { - static char nl = '\n'; + static const char nl = '\n'; struct ftp_cw_lc_ctx *ctx = (struct ftp_cw_lc_ctx *)writer; if(!(type & CLIENTWRITE_BODY) || From 9e2ee704940e4e8ba38ba770b86a79ec091990bf Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 29 Feb 2024 11:31:55 +0100 Subject: [PATCH 402/509] hyper: disable test1598 due to lack of trailer support Follow-up to 50838095 Closes #13016 --- tests/data/DISABLED | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/data/DISABLED b/tests/data/DISABLED index a98dc856683..be3b8b5d84e 100644 --- a/tests/data/DISABLED +++ b/tests/data/DISABLED @@ -77,6 +77,7 @@ 1533 1540 1591 +1598 1943 2301 2302 From a0cbe4b867571b7aa40459480430b1915979280d Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Thu, 29 Feb 2024 01:36:31 -0500 Subject: [PATCH 403/509] cmdline-opts/_EXITCODES: sync with libcurl-errors - Add error code 100 (CURLE_TOO_LARGE) to the list of error codes that can be returned by the curl tool. Closes https://github.com/curl/curl/pull/13015 --- docs/cmdline-opts/_EXITCODES.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/cmdline-opts/_EXITCODES.md b/docs/cmdline-opts/_EXITCODES.md index d7b71fda0da..c5a928b5904 100644 --- a/docs/cmdline-opts/_EXITCODES.md +++ b/docs/cmdline-opts/_EXITCODES.md @@ -196,6 +196,8 @@ Proxy handshake error. 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. From ab173d14437b4eea67bea139a5c28645d6b2ae88 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 1 Mar 2024 18:27:35 -0800 Subject: [PATCH 404/509] configure: Don't build shell completions when disabled With the recent changes to completion file building, the files were built always and only installation was selectively disabled. Now, when they are disabled they aren't even built, avoiding a build-time error in environments where it's not possible to run the curl binary that was just created (e.g. if library paths were not set up correctly). Follow-up to 0f7aba83c Reported-by: av223119 on github Fixes #13027 Closes #13030 --- scripts/Makefile.am | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/scripts/Makefile.am b/scripts/Makefile.am index e3e056ca7a7..4a30d41755d 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -29,13 +29,18 @@ ZSH_FUNCTIONS_DIR = @ZSH_FUNCTIONS_DIR@ FISH_FUNCTIONS_DIR = @FISH_FUNCTIONS_DIR@ PERL = @PERL@ +if USE_ZSH_COMPLETION ZSH_COMPLETION_FUNCTION_FILENAME = _curl +endif +if USE_FISH_COMPLETION FISH_COMPLETION_FUNCTION_FILENAME = curl.fish +endif CLEANFILES = $(ZSH_COMPLETION_FUNCTION_FILENAME) $(FISH_COMPLETION_FUNCTION_FILENAME) all-local: $(ZSH_COMPLETION_FUNCTION_FILENAME) $(FISH_COMPLETION_FUNCTION_FILENAME) +if USE_ZSH_COMPLETION $(ZSH_COMPLETION_FUNCTION_FILENAME): completion.pl if CROSSCOMPILING @echo "NOTICE: we can't generate zsh completion when cross-compiling!" @@ -43,7 +48,9 @@ else # if not cross-compiling: if test -z "$(PERL)"; then echo "No perl: can't install completion script"; else \ $(PERL) $(srcdir)/completion.pl --curl $(top_builddir)/src/curl$(EXEEXT) --shell zsh > $@ ; fi endif +endif +if USE_FISH_COMPLETION $(FISH_COMPLETION_FUNCTION_FILENAME): completion.pl if CROSSCOMPILING @echo "NOTICE: we can't generate fish completion when cross-compiling!" @@ -51,6 +58,7 @@ else # if not cross-compiling: if test -z "$(PERL)"; then echo "No perl: can't install completion script"; else \ $(PERL) $(srcdir)/completion.pl --curl $(top_builddir)/src/curl$(EXEEXT) --shell fish > $@ ; fi endif +endif install-data-local: if CROSSCOMPILING From b1005d127f164f49cf5aa08904b85194c5caf921 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 1 Mar 2024 09:12:50 +0100 Subject: [PATCH 405/509] bufq: writing into a softlimit queue cannot be partial - when unable to obtain a new chunk on a softlimit bufq, this is an allocation error and needs to be reported as such. - writes into a soflimit bufq never must be partial success Reported-by: Dan Fandrich Fixes #13020 Closes #13023 --- lib/bufq.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/bufq.c b/lib/bufq.c index 4369fe0b268..c3245516c9f 100644 --- a/lib/bufq.c +++ b/lib/bufq.c @@ -396,7 +396,7 @@ ssize_t Curl_bufq_write(struct bufq *q, while(len) { tail = get_non_full_tail(q); if(!tail) { - if(q->chunk_count < q->max_chunks) { + if((q->chunk_count < q->max_chunks) || (q->opts & BUFQ_OPT_SOFT_LIMIT)) { *err = CURLE_OUT_OF_MEMORY; return -1; } From ae7ad31be209b8c0168c213a4dbc4f869f177823 Mon Sep 17 00:00:00 2001 From: kpcyrd Date: Thu, 29 Feb 2024 16:01:03 +0100 Subject: [PATCH 406/509] rustls: fix two warnings related to number types Reported-by: Gisle Vanem Follow-up to #12989 Closes #13017 --- lib/vtls/rustls.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/vtls/rustls.c b/lib/vtls/rustls.c index 485b1d38905..367d7a5f409 100644 --- a/lib/vtls/rustls.c +++ b/lib/vtls/rustls.c @@ -292,7 +292,7 @@ cr_send(struct Curl_cfilter *cf, struct Curl_easy *data, DEBUGASSERT(backend); rconn = backend->conn; - CURL_TRC_CF(data, cf, "cf_send: %ld plain bytes", plainlen); + CURL_TRC_CF(data, cf, "cf_send: %zu plain bytes", plainlen); io_ctx.cf = cf; io_ctx.data = data; @@ -343,7 +343,7 @@ cr_send(struct Curl_cfilter *cf, struct Curl_easy *data, /* A server certificate verify callback for rustls that always returns RUSTLS_RESULT_OK, or in other words disable certificate verification. */ -static enum rustls_result +static uint32_t cr_verify_none(void *userdata UNUSED_PARAM, const rustls_verify_server_cert_params *params UNUSED_PARAM) { From 46aea3d990f3fd6149e89a4949ee999484273e4d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2024 08:19:12 +0100 Subject: [PATCH 407/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 60 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 47 insertions(+), 13 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index a3115649a03..6212f5e57a0 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.7.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3102 + Contributors: 3105 This release includes the following changes: @@ -20,6 +20,7 @@ This release includes the following bugfixes: 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 @@ -29,15 +30,22 @@ This release includes the following bugfixes: o cmake: fix install for older CMake versions [53] 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/_VERSION: provide %VERSION correctly [87] o configure.ac: find libpsl with pkg-config [79] 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 connect.c: fix typo [17] o cookie.md: provide an example sending a fixed cookie [13] o curl: exit on config file parser errors [40] 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 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 dist: make sure the http tests are in the tarball [29] o docs: add missing slashes to SChannel client certificate documentation [11] @@ -45,13 +53,18 @@ This release includes the following bugfixes: o docs: dist curl*.1 and install without perl [64] o docs: make curldown do angle brackets like markdown [54] 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: make `\>` in input to render as plain '>' in output [78] + o getparam: make --ftp-ssl work again [90] o header.md: remove backslash, make nicer markdown [48] o HTTP/2: write response directly [12] o HTTP3.md: adjust the OpenSSL QUIC install instructions [34] @@ -61,6 +74,7 @@ This release includes the following bugfixes: o https-proxy: use IP address and cert with ip in alt names [50] o lib582: remove code causing warning that is never run [38] o lib: convert Curl_get_line to use dynbuf [42] + o lib: Curl_read/Curl_write clarifications [101] o lib: initialize output pointers to NULL before calling strto[ff,l,ul] [63] o lib: remove curl_mimepart object when CURL_DISABLE_MIME [72] o libcurl-docs: cleanups @@ -70,9 +84,11 @@ This release includes the following bugfixes: o mbedtls: fix building when MBEDTLS_X509_REMOVE_INFO flag is defined [27] o mbedtls: use mbedtls_ssl_conf_{min|max}_tls_version [59] o md4: include strdup.h for the memdup proto [10] + o misc: fix typos in docs and lib [84] 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 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] @@ -83,6 +99,7 @@ This release includes the following bugfixes: 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 strtoofft: fix the overflow check [74] o test1165: improve pattern matching [60] o tests: support setting/using blank content env variables @@ -110,18 +127,19 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - 5533asdg on github, Boris Verkhovskiy, Brett Buddin, Chris Webb, - Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, Daniel Szmulewicz, - Dirk Hünniger, Dmitry Tretyakov, edmcln on github, Erik Schnetter, - Evgeny Grin (Karlson2k), Fabian Vogt, Fabrice Fontaine, Faraz Fallahi, - Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, - Joel Depooter, Jon Rumsey, Karthikdasari0423, Konstantin Vlasov, kpcyrd, - Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, Lukáš Zaoral, - Michael Forney, Michael Kaufmann, Michał Antoniak, Patrick Monnerat, - Paweł Witas, Peter Krefting, Ramiro Garcia, Ray Satiro, Richard Levitte, - Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, Sergey Bronnikov, - Stefan Eissing, Viktor Szakats, vulnerabilityspotter on hackerone - (46 contributors) + 5533asdg on github, Andreas Kiefer, av223119 on github, Boris Verkhovskiy, + Brett Buddin, Chris Webb, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, + Daniel Szmulewicz, Dirk Hünniger, Dmitry Tretyakov, edmcln on github, + Erik Schnetter, Evgeny Grin (Karlson2k), Fabian Vogt, Fabrice Fontaine, + Faraz Fallahi, Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, + Jiawen Geng, Joel Depooter, Jon Rumsey, Jordan Brown, Karthikdasari0423, + Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, + Lukáš Zaoral, Marcel Raad, Michael Forney, Michael Kaufmann, Michał Antoniak, + Patrick Monnerat, Paweł Witas, Peter Krefting, RainRat, Ramiro Garcia, + Ray Satiro, Richard Levitte, Ryan Carsten Schmidt, Scott Mutter, + Scott Talbert, Sergey Bronnikov, Stefan Eissing, Viktor Szakats, + vulnerabilityspotter on hackerone + (51 contributors) References to bug reports and discussions on issues: @@ -172,6 +190,7 @@ References to bug reports and discussions on issues: [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 @@ -190,6 +209,7 @@ References to bug reports and discussions on issues: [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 @@ -201,4 +221,18 @@ References to bug reports and discussions on issues: [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 + [83] = https://curl.se/bug/?i=13022 + [84] = https://curl.se/bug/?i=13019 + [85] = https://curl.se/bug/?i=12906 + [87] = https://curl.se/bug/?i=13008 + [89] = https://curl.se/bug/?i=12997 + [90] = https://curl.se/bug/?i=13006 + [97] = https://curl.se/bug/?i=13003 + [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 From e3905de8196d67b89df1602feb84c1f993211b20 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 28 Feb 2024 14:51:53 +0100 Subject: [PATCH 408/509] lib: further send/upload handling polish - Move all the "upload_done" handling to request.c - add possibility to abort sending of a request - add `Curl_req_done_sending()` for checks - transfer.c: readwrite_upload() now clean - removing data->state.ulbuf and data->req.upload_fromhere - as well as data->req.upload_present - set data->req.upload_done on having read all from the client and completely flushed the send buffer - tftp, remove setting of data->req.upload_fromhere - serves no purpose as `upload_present` is not set and the data itself is directly `sendto()` anyway - smtp, make upload EOB conversion a client reader - xfer_ulbuf addition - add xfer_ulbuf for borrowing, similar to xfer_buf - use in file upload - use in c-hyper body sending - h1-proxy, remove init of data->state.uilbuf that is never used - smb, add own send_buf instead of using data->state.ulbuf Closes #13010 --- lib/c-hyper.c | 54 ++++---- lib/cf-h1-proxy.c | 6 - lib/file.c | 16 +-- lib/http.c | 58 +++------ lib/http.h | 17 --- lib/multi.c | 66 +++++++++- lib/multihandle.h | 4 + lib/multiif.h | 25 ++++ lib/request.c | 118 +++++++++++++----- lib/request.h | 34 ++--- lib/rtsp.c | 4 +- lib/sendf.c | 6 +- lib/setopt.c | 1 - lib/smb.c | 33 ++--- lib/smb.h | 1 + lib/smtp.c | 310 ++++++++++++++++++++++++---------------------- lib/smtp.h | 13 -- lib/tftp.c | 2 - lib/transfer.c | 202 ++++-------------------------- lib/transfer.h | 6 +- lib/url.c | 1 - lib/urldata.h | 1 - 22 files changed, 464 insertions(+), 514 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index d12d6de153d..6bac1a35732 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -469,7 +469,7 @@ CURLcode Curl_hyper_stream(struct Curl_easy *data, infof(data, "Got 417 while waiting for a 100"); data->state.disableexpect = TRUE; data->req.newurl = strdup(data->state.url); - Curl_done_sending(data, k); + Curl_req_abort_sending(data); } result = status_line(data, conn, @@ -663,7 +663,10 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, size_t fillcount; struct Curl_easy *data = (struct Curl_easy *)userdata; CURLcode result; + char *xfer_ulbuf; + size_t xfer_ulblen; bool eos; + int rc = HYPER_POLL_ERROR; (void)ctx; if(data->req.exp100 > EXP100_SEND_DATA) { @@ -677,39 +680,44 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, return HYPER_POLL_PENDING; } - result = Curl_client_read(data, data->state.ulbuf, - data->set.upload_buffer_size, - &fillcount, &eos); - if(result) { - data->state.hresult = result; - return HYPER_POLL_ERROR; - } + result = Curl_multi_xfer_ulbuf_borrow(data, &xfer_ulbuf, &xfer_ulblen); + if(result) + goto out; + + result = Curl_client_read(data, xfer_ulbuf, xfer_ulblen, &fillcount, &eos); + if(result) + goto out; if(fillcount) { - hyper_buf *copy = hyper_buf_copy((uint8_t *)data->state.ulbuf, fillcount); + hyper_buf *copy = hyper_buf_copy((uint8_t *)xfer_ulbuf, fillcount); if(copy) *chunk = copy; else { - data->state.hresult = CURLE_OUT_OF_MEMORY; - return HYPER_POLL_ERROR; + result = CURLE_OUT_OF_MEMORY; + goto out; } /* increasing the writebytecount here is a little premature but we don't know exactly when the body is sent */ data->req.writebytecount += fillcount; Curl_pgrsSetUploadCounter(data, data->req.writebytecount); - return HYPER_POLL_READY; + rc = HYPER_POLL_READY; } else if(eos) { *chunk = NULL; - return HYPER_POLL_READY; + rc = HYPER_POLL_READY; } else { /* paused, save a waker */ if(data->hyp.send_body_waker) hyper_waker_free(data->hyp.send_body_waker); data->hyp.send_body_waker = hyper_context_waker(ctx); - return HYPER_POLL_PENDING; + rc = HYPER_POLL_PENDING; } + +out: + Curl_multi_xfer_ulbuf_release(data, xfer_ulbuf); + data->state.hresult = result; + return rc; } /* @@ -722,7 +730,6 @@ static CURLcode bodysend(struct Curl_easy *data, hyper_request *hyperreq, Curl_HttpReq httpreq) { - struct HTTP *http = data->req.p.http; CURLcode result = CURLE_OK; struct dynbuf req; if((httpreq == HTTPREQ_GET) || (httpreq == HTTPREQ_HEAD)) @@ -731,21 +738,21 @@ static CURLcode bodysend(struct Curl_easy *data, hyper_body *body; Curl_dyn_init(&req, DYN_HTTP_REQUEST); result = Curl_http_req_complete(data, &req, httpreq); + if(result) + return result; - if(!result) + /* if the "complete" above did produce more than the closing line, + parse the added headers */ + if(Curl_dyn_len(&req) != 2 || strcmp(Curl_dyn_ptr(&req), "\r\n")) { result = Curl_hyper_header(data, headers, Curl_dyn_ptr(&req)); + if(result) + return result; + } Curl_dyn_free(&req); body = hyper_body_new(); hyper_body_set_userdata(body, data); - result = Curl_get_upload_buffer(data); - if(result) { - hyper_body_free(body); - return result; - } - /* init the "upload from here" pointer */ - data->req.upload_fromhere = data->state.ulbuf; hyper_body_set_data_func(body, uploadstreamed); if(HYPERE_OK != hyper_request_set_body(hyperreq, body)) { @@ -753,7 +760,6 @@ static CURLcode bodysend(struct Curl_easy *data, result = CURLE_OUT_OF_MEMORY; } } - http->sending = HTTPSEND_BODY; return result; } diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index 280516061fc..deb94580bfb 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -114,18 +114,12 @@ static CURLcode tunnel_init(struct Curl_cfilter *cf, struct h1_tunnel_state **pts) { struct h1_tunnel_state *ts; - CURLcode result; if(cf->conn->handler->flags & PROTOPT_NOTCPPROXY) { failf(data, "%s cannot be done over CONNECT", cf->conn->handler->scheme); return CURLE_UNSUPPORTED_PROTOCOL; } - /* we might need the upload buffer for streaming a partial request */ - result = Curl_get_upload_buffer(data); - if(result) - return result; - ts = calloc(1, sizeof(*ts)); if(!ts) return CURLE_OUT_OF_MEMORY; diff --git a/lib/file.c b/lib/file.c index d3b08a81f0e..07d879dfd12 100644 --- a/lib/file.c +++ b/lib/file.c @@ -291,8 +291,8 @@ static CURLcode file_upload(struct Curl_easy *data) int fd; int mode; CURLcode result = CURLE_OK; - char *xfer_buf; - size_t xfer_blen; + char *xfer_ulbuf; + size_t xfer_ulblen; curl_off_t bytecount = 0; struct_stat file_stat; const char *sendbuf; @@ -340,7 +340,7 @@ static CURLcode file_upload(struct Curl_easy *data) data->state.resume_from = (curl_off_t)file_stat.st_size; } - result = Curl_multi_xfer_buf_borrow(data, &xfer_buf, &xfer_blen); + result = Curl_multi_xfer_ulbuf_borrow(data, &xfer_ulbuf, &xfer_ulblen); if(result) goto out; @@ -349,7 +349,7 @@ static CURLcode file_upload(struct Curl_easy *data) ssize_t nwrite; size_t readcount; - result = Curl_client_read(data, xfer_buf, xfer_blen, &readcount, &eos); + result = Curl_client_read(data, xfer_ulbuf, xfer_ulblen, &readcount, &eos); if(result) break; @@ -363,16 +363,16 @@ static CURLcode file_upload(struct Curl_easy *data) if((curl_off_t)nread <= data->state.resume_from) { data->state.resume_from -= nread; nread = 0; - sendbuf = xfer_buf; + sendbuf = xfer_ulbuf; } else { - sendbuf = xfer_buf + data->state.resume_from; + sendbuf = xfer_ulbuf + data->state.resume_from; nread -= (size_t)data->state.resume_from; data->state.resume_from = 0; } } else - sendbuf = xfer_buf; + sendbuf = xfer_ulbuf; /* write the data to the target */ nwrite = write(fd, sendbuf, nread); @@ -395,7 +395,7 @@ static CURLcode file_upload(struct Curl_easy *data) out: close(fd); - Curl_multi_xfer_buf_release(data, xfer_buf); + Curl_multi_xfer_ulbuf_release(data, xfer_ulbuf); return result; } diff --git a/lib/http.c b/lib/http.c index 3f17f7cd92f..65febe77f7a 100644 --- a/lib/http.c +++ b/lib/http.c @@ -1283,7 +1283,6 @@ CURLcode Curl_http_done(struct Curl_easy *data, if(!http) return CURLE_OK; - Curl_dyn_free(&http->send_buffer); Curl_dyn_reset(&data->state.headerb); Curl_hyper_done(data); Curl_ws_done(data); @@ -2151,6 +2150,12 @@ CURLcode Curl_http_req_complete(struct Curl_easy *data, CURLcode result = CURLE_OK; struct HTTP *http = data->req.p.http; + if(data->req.upload_chunky) { + result = Curl_httpchunk_add_reader(data); + if(result) + return result; + } + DEBUGASSERT(data->conn); switch(httpreq) { case HTTPREQ_PUT: /* Let's PUT the data to the server! */ @@ -2252,7 +2257,6 @@ CURLcode Curl_http_req_complete(struct Curl_easy *data, data->state.in = (void *) data->state.mimepost; result = Client_reader_set_fread(data, data->state.infilesize); } - http->sending = HTTPSEND_BODY; break; #endif case HTTPREQ_POST: @@ -2294,19 +2298,21 @@ CURLcode Curl_http_req_complete(struct Curl_easy *data, goto out; if(!http->postsize) { - Curl_pgrsSetUploadSize(data, -1); + Curl_pgrsSetUploadSize(data, 0); result = Client_reader_set_null(data); } - else if(data->set.postfields) { /* we have the bytes */ + else if(data->set.postfields) { Curl_pgrsSetUploadSize(data, http->postsize); - result = Client_reader_set_buf(data, data->set.postfields, - (size_t)http->postsize); + if(http->postsize > 0) + result = Client_reader_set_buf(data, data->set.postfields, + (size_t)http->postsize); + else + result = Client_reader_set_null(data); } else { /* we read the bytes from the callback */ Curl_pgrsSetUploadSize(data, http->postsize); result = Client_reader_set_fread(data, http->postsize); } - http->sending = HTTPSEND_BODY; break; default: @@ -2647,7 +2653,6 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) { struct connectdata *conn = data->conn; CURLcode result = CURLE_OK; - struct HTTP *http; Curl_HttpReq httpreq; const char *te = ""; /* transfer-encoding */ const char *request; @@ -2699,9 +2704,6 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) if(result) goto fail; - http = data->req.p.http; - DEBUGASSERT(http); - result = Curl_http_host(data, conn); if(result) goto fail; @@ -2880,7 +2882,6 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) result = Curl_add_custom_headers(data, FALSE, &req); if(!result) { - http->postdata = NULL; /* nothing to post at this point */ if((httpreq == HTTPREQ_GET) || (httpreq == HTTPREQ_HEAD)) Curl_pgrsSetUploadSize(data, 0); /* nothing */ @@ -2896,29 +2897,6 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) if(result) goto fail; - if(data->req.writebytecount) { - /* if a request-body has been sent off, we make sure this progress is noted - properly */ - Curl_pgrsSetUploadCounter(data, data->req.writebytecount); - if(Curl_pgrsUpdate(data)) - result = CURLE_ABORTED_BY_CALLBACK; - - if(!http->postsize) { - /* already sent the entire request body, mark the "upload" as - complete */ - infof(data, "upload completely sent off: %" CURL_FORMAT_CURL_OFF_T - " out of %" CURL_FORMAT_CURL_OFF_T " bytes", - data->req.writebytecount, http->postsize); - data->req.upload_done = TRUE; - data->req.keepon &= ~KEEP_SEND; /* we're done writing */ - data->req.exp100 = EXP100_SEND_DATA; /* already sent */ - Curl_expire_done(data, EXPIRE_100_TIMEOUT); - } - } - - if(data->req.upload_done) - Curl_conn_ev_data_done_send(data); - if((conn->httpversion >= 20) && data->req.upload_chunky) /* upload_chunky was set above to set up the request in a chunky fashion, but is disabled here again to avoid that the chunked encoded version is @@ -3782,7 +3760,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, * connection for closure after we've read the entire response. */ Curl_expire_done(data, EXPIRE_100_TIMEOUT); - if(!k->upload_done) { + if(!Curl_req_done_sending(data)) { if((k->httpcode == 417) && data->state.expect100header) { /* 417 Expectation Failed - try again without the Expect header */ @@ -3801,7 +3779,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, data->state.disableexpect = TRUE; DEBUGASSERT(!data->req.newurl); data->req.newurl = strdup(data->state.url); - Curl_done_sending(data, k); + Curl_req_abort_sending(data); } else if(data->set.http_keep_sending_on_error) { infof(data, "HTTP error before end of send, keep sending"); @@ -3813,10 +3791,9 @@ static CURLcode http_rw_headers(struct Curl_easy *data, else { infof(data, "HTTP error before end of send, stop sending"); streamclose(conn, "Stop sending data before everything sent"); - result = Curl_done_sending(data, k); + result = Curl_req_abort_sending(data); if(result) return result; - k->upload_done = TRUE; if(data->state.expect100header) k->exp100 = EXP100_FAILED; } @@ -3828,8 +3805,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, } } - if(data->state.rewindbeforesend && - (conn->writesockfd != CURL_SOCKET_BAD)) { + if(data->state.rewindbeforesend && !Curl_req_done_sending(data)) { /* We rewind before next send, continue sending now */ infof(data, "Keep sending data to get tossed away"); k->keepon |= KEEP_SEND; diff --git a/lib/http.h b/lib/http.h index b7fb877e633..fc058477d5f 100644 --- a/lib/http.h +++ b/lib/http.h @@ -189,27 +189,10 @@ CURLcode Curl_http_auth_act(struct Curl_easy *data); ***************************************************************************/ struct HTTP { curl_off_t postsize; /* off_t to handle large file sizes */ - const char *postdata; - struct back { - curl_read_callback fread_func; /* backup storage for fread pointer */ - void *fread_in; /* backup storage for fread_in pointer */ - const char *postdata; - curl_off_t postsize; - struct Curl_easy *data; - } backup; - - enum { - HTTPSEND_NADA, /* init */ - HTTPSEND_REQUEST, /* sending a request */ - HTTPSEND_BODY /* sending body */ - } sending; #ifndef CURL_DISABLE_HTTP void *h2_ctx; /* HTTP/2 implementation context */ void *h3_ctx; /* HTTP/3 implementation context */ - struct dynbuf send_buffer; /* used if the request couldn't be sent in one - chunk, points to an allocated send_buffer - struct */ #endif }; diff --git a/lib/multi.c b/lib/multi.c index e0e871fe679..3770ac607b5 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -94,7 +94,7 @@ static CURLMcode add_next_timeout(struct curltime now, static CURLMcode multi_timeout(struct Curl_multi *multi, long *timeout_ms); static void process_pending_handles(struct Curl_multi *multi); -static void multi_xfer_buf_free(struct Curl_multi *multi); +static void multi_xfer_bufs_free(struct Curl_multi *multi); #ifdef DEBUGBUILD static const char * const multi_statename[]={ @@ -192,7 +192,7 @@ static void mstate(struct Curl_easy *data, CURLMstate state data->multi->num_alive--; if(!data->multi->num_alive) { /* free the transfer buffer when we have no more active transfers */ - multi_xfer_buf_free(data->multi); + multi_xfer_bufs_free(data->multi); } } @@ -716,8 +716,6 @@ static CURLcode multi_done(struct Curl_easy *data, if(!result) result = Curl_req_done(&data->req, data, premature); - Curl_safefree(data->state.ulbuf); - CONNCACHE_LOCK(data); Curl_detach_connection(data); if(CONN_INUSE(conn)) { @@ -2900,7 +2898,7 @@ CURLMcode curl_multi_cleanup(struct Curl_multi *multi) Curl_free_multi_ssl_backend_data(multi->ssl_backend_data); #endif - multi_xfer_buf_free(multi); + multi_xfer_bufs_free(multi); free(multi); return CURLM_OK; @@ -3891,10 +3889,66 @@ void Curl_multi_xfer_buf_release(struct Curl_easy *data, char *buf) data->multi->xfer_buf_borrowed = FALSE; } -static void multi_xfer_buf_free(struct Curl_multi *multi) +CURLcode Curl_multi_xfer_ulbuf_borrow(struct Curl_easy *data, + char **pbuf, size_t *pbuflen) +{ + DEBUGASSERT(data); + DEBUGASSERT(data->multi); + *pbuf = NULL; + *pbuflen = 0; + if(!data->multi) { + failf(data, "transfer has no multi handle"); + return CURLE_FAILED_INIT; + } + if(!data->set.upload_buffer_size) { + failf(data, "transfer upload buffer size is 0"); + return CURLE_FAILED_INIT; + } + if(data->multi->xfer_ulbuf_borrowed) { + failf(data, "attempt to borrow xfer_ulbuf when already borrowed"); + return CURLE_AGAIN; + } + + if(data->multi->xfer_ulbuf && + data->set.upload_buffer_size > data->multi->xfer_ulbuf_len) { + /* not large enough, get a new one */ + free(data->multi->xfer_ulbuf); + data->multi->xfer_ulbuf = NULL; + data->multi->xfer_ulbuf_len = 0; + } + + if(!data->multi->xfer_ulbuf) { + data->multi->xfer_ulbuf = malloc((size_t)data->set.upload_buffer_size); + if(!data->multi->xfer_ulbuf) { + failf(data, "could not allocate xfer_ulbuf of %zu bytes", + (size_t)data->set.upload_buffer_size); + return CURLE_OUT_OF_MEMORY; + } + data->multi->xfer_ulbuf_len = data->set.upload_buffer_size; + } + + data->multi->xfer_ulbuf_borrowed = TRUE; + *pbuf = data->multi->xfer_ulbuf; + *pbuflen = data->multi->xfer_ulbuf_len; + return CURLE_OK; +} + +void Curl_multi_xfer_ulbuf_release(struct Curl_easy *data, char *buf) +{ + (void)buf; + DEBUGASSERT(data); + DEBUGASSERT(data->multi); + DEBUGASSERT(!buf || data->multi->xfer_ulbuf == buf); + data->multi->xfer_ulbuf_borrowed = FALSE; +} + +static void multi_xfer_bufs_free(struct Curl_multi *multi) { DEBUGASSERT(multi); Curl_safefree(multi->xfer_buf); multi->xfer_buf_len = 0; multi->xfer_buf_borrowed = FALSE; + Curl_safefree(multi->xfer_ulbuf); + multi->xfer_ulbuf_len = 0; + multi->xfer_ulbuf_borrowed = FALSE; } diff --git a/lib/multihandle.h b/lib/multihandle.h index 3cccd343fec..3156c83ad34 100644 --- a/lib/multihandle.h +++ b/lib/multihandle.h @@ -127,6 +127,9 @@ struct Curl_multi { /* buffer used for transfer data, lazy initialized */ char *xfer_buf; /* the actual buffer */ size_t xfer_buf_len; /* the allocated length */ + /* buffer used for upload data, lazy initialized */ + char *xfer_ulbuf; /* the actual buffer */ + size_t xfer_ulbuf_len; /* the allocated length */ #if defined(USE_SSL) struct multi_ssl_backend_data *ssl_backend_data; @@ -176,6 +179,7 @@ struct Curl_multi { BIT(dead); /* a callback returned error, everything needs to crash and burn */ BIT(xfer_buf_borrowed); /* xfer_buf is currently being borrowed */ + BIT(xfer_ulbuf_borrowed); /* xfer_buf is currently being borrowed */ #ifdef DEBUGBUILD BIT(warned); /* true after user warned of DEBUGBUILD */ #endif diff --git a/lib/multiif.h b/lib/multiif.h index de2ffeb9f43..37f7a442623 100644 --- a/lib/multiif.h +++ b/lib/multiif.h @@ -118,4 +118,29 @@ CURLcode Curl_multi_xfer_buf_borrow(struct Curl_easy *data, */ void Curl_multi_xfer_buf_release(struct Curl_easy *data, char *buf); +/** + * Borrow the upload buffer from the multi, suitable + * for the given transfer `data`. The buffer may only be used in one + * multi processing of the easy handle. It MUST be returned to the + * multi before it can be borrowed again. + * Pointers into the buffer remain only valid as long as it is borrowed. + * + * @param data the easy handle + * @param pbuf on return, the buffer to use or NULL on error + * @param pbuflen on return, the size of *pbuf or 0 on error + * @return CURLE_OK when buffer is available and is returned. + * CURLE_OUT_OF_MEMORy on failure to allocate the buffer, + * CURLE_FAILED_INIT if the easy handle is without multi. + * CURLE_AGAIN if the buffer is borrowed already. + */ +CURLcode Curl_multi_xfer_ulbuf_borrow(struct Curl_easy *data, + char **pbuf, size_t *pbuflen); + +/** + * Release the borrowed upload buffer. All references into the buffer become + * invalid after this. + * @param buf the upload buffer pointer borrowed for coding error checks. + */ +void Curl_multi_xfer_ulbuf_release(struct Curl_easy *data, char *buf); + #endif /* HEADER_CURL_MULTIIF_H */ diff --git a/lib/request.c b/lib/request.c index cd5170a3282..dfd96a6c491 100644 --- a/lib/request.c +++ b/lib/request.c @@ -25,6 +25,7 @@ #include "curl_setup.h" #include "urldata.h" +#include "cfilters.h" #include "dynbuf.h" #include "doh.h" #include "multiif.h" @@ -67,12 +68,14 @@ CURLcode Curl_req_start(struct SingleRequest *req, return CURLE_OK; } +static CURLcode req_flush(struct Curl_easy *data); + CURLcode Curl_req_done(struct SingleRequest *req, struct Curl_easy *data, bool aborted) { (void)req; if(!aborted) - (void)Curl_req_flush(data); + (void)req_flush(data); Curl_client_reset(data); return CURLE_OK; } @@ -129,9 +132,9 @@ void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data) #endif } -static CURLcode req_send(struct Curl_easy *data, - const char *buf, size_t blen, - size_t hds_len, size_t *pnwritten) +static CURLcode xfer_send(struct Curl_easy *data, + const char *buf, size_t blen, + size_t hds_len, size_t *pnwritten) { CURLcode result = CURLE_OK; @@ -180,7 +183,7 @@ static CURLcode req_send_buffer_flush(struct Curl_easy *data) while(Curl_bufq_peek(&data->req.sendbuf, &buf, &blen)) { size_t nwritten, hds_len = CURLMIN(data->req.sendbuf_hds_len, blen); - result = req_send(data, (const char *)buf, blen, hds_len, &nwritten); + result = xfer_send(data, (const char *)buf, blen, hds_len, &nwritten); if(result) break; @@ -206,7 +209,33 @@ static CURLcode req_send_buffer_flush(struct Curl_easy *data) return result; } -CURLcode Curl_req_flush(struct Curl_easy *data) +static CURLcode req_set_upload_done(struct Curl_easy *data) +{ + DEBUGASSERT(!data->req.upload_done); + data->req.upload_done = TRUE; + data->req.keepon &= ~KEEP_SEND; /* we're done sending */ + + /* FIXME: http specific stuff, need to go somewhere else */ + data->req.exp100 = EXP100_SEND_DATA; + Curl_expire_done(data, EXPIRE_100_TIMEOUT); + + if(data->req.upload_aborted) { + if(data->req.writebytecount) + infof(data, "abort upload after having sent %" CURL_FORMAT_CURL_OFF_T + " bytes", data->req.writebytecount); + else + infof(data, "abort upload"); + } + else if(data->req.writebytecount) + infof(data, "upload completely sent off: %" CURL_FORMAT_CURL_OFF_T + " bytes", data->req.writebytecount); + else + infof(data, "We are completely uploaded and fine"); + + return Curl_xfer_send_close(data); +} + +static CURLcode req_flush(struct Curl_easy *data) { CURLcode result; @@ -221,9 +250,30 @@ CURLcode Curl_req_flush(struct Curl_easy *data) return CURLE_AGAIN; } } + + if(!data->req.upload_done && data->req.eos_read && + Curl_bufq_is_empty(&data->req.sendbuf)) { + return req_set_upload_done(data); + } return CURLE_OK; } +static ssize_t add_from_client(void *reader_ctx, + unsigned char *buf, size_t buflen, + CURLcode *err) +{ + struct Curl_easy *data = reader_ctx; + size_t nread; + bool eos; + + *err = Curl_client_read(data, (char *)buf, buflen, &nread, &eos); + if(*err) + return -1; + if(eos) + data->req.eos_read = TRUE; + return (ssize_t)nread; +} + #ifndef USE_HYPER static CURLcode req_send_buffer_add(struct Curl_easy *data, @@ -242,22 +292,6 @@ static CURLcode req_send_buffer_add(struct Curl_easy *data, return CURLE_OK; } -static ssize_t add_from_client(void *reader_ctx, - unsigned char *buf, size_t buflen, - CURLcode *err) -{ - struct Curl_easy *data = reader_ctx; - size_t nread; - bool eos; - - *err = Curl_client_read(data, (char *)buf, buflen, &nread, &eos); - if(*err) - return -1; - if(eos) - data->req.eos_read = TRUE; - return (ssize_t)nread; -} - CURLcode Curl_req_send(struct Curl_easy *data, struct dynbuf *buf) { CURLcode result; @@ -275,22 +309,50 @@ CURLcode Curl_req_send(struct Curl_easy *data, struct dynbuf *buf) if(result) return result; - if((data->req.exp100 == EXP100_SEND_DATA) && - !Curl_bufq_is_full(&data->req.sendbuf)) { + return Curl_req_send_more(data); +} +#endif /* !USE_HYPER */ + +bool Curl_req_want_send(struct Curl_easy *data) +{ + return data->req.sendbuf_init && !Curl_bufq_is_empty(&data->req.sendbuf); +} + +bool Curl_req_done_sending(struct Curl_easy *data) +{ + if(data->req.upload_done) { + DEBUGASSERT(Curl_bufq_is_empty(&data->req.sendbuf)); + return TRUE; + } + return FALSE; +} + +CURLcode Curl_req_send_more(struct Curl_easy *data) +{ + CURLcode result; + + /* Fill our send buffer if more from client can be read and + * we are not in a "expect-100" situation. */ + if(!data->req.eos_read && !Curl_bufq_is_full(&data->req.sendbuf) && + (data->req.exp100 == EXP100_SEND_DATA)) { ssize_t nread = Curl_bufq_sipn(&data->req.sendbuf, 0, add_from_client, data, &result); if(nread < 0 && result != CURLE_AGAIN) return result; } - result = req_send_buffer_flush(data); + result = req_flush(data); if(result == CURLE_AGAIN) result = CURLE_OK; return result; } -#endif /* !USE_HYPER */ -bool Curl_req_want_send(struct Curl_easy *data) +CURLcode Curl_req_abort_sending(struct Curl_easy *data) { - return data->req.sendbuf_init && !Curl_bufq_is_empty(&data->req.sendbuf); + if(!data->req.upload_done) { + Curl_bufq_reset(&data->req.sendbuf); + data->req.upload_aborted = TRUE; + return req_set_upload_done(data); + } + return CURLE_OK; } diff --git a/lib/request.h b/lib/request.h index e7af4a8e537..91973d5dbc7 100644 --- a/lib/request.h +++ b/lib/request.h @@ -100,16 +100,6 @@ struct SingleRequest { char *newurl; /* Set to the new URL to use when a redirect or a retry is wanted */ - /* 'upload_present' is used to keep a byte counter of how much data there is - still left in the buffer, aimed for upload. */ - size_t upload_present; - - /* 'upload_fromhere' is used as a read-pointer when we uploaded parts of a - buffer, so the next read should read from where this pointer points to, - and the 'upload_present' contains the number of bytes available at this - position */ - char *upload_fromhere; - /* Allocated protocol-specific data. Each protocol handler makes sure this points to data it needs. */ union { @@ -139,8 +129,9 @@ struct SingleRequest { BIT(download_done); /* set to TRUE when download is complete */ BIT(eos_written); /* iff EOS has been written to client */ BIT(eos_read); /* iff EOS has been read from the client */ - BIT(upload_done); /* set to TRUE when doing chunked transfer-encoding - upload and we're uploading the last chunk */ + BIT(upload_done); /* set to TRUE when all request data has been sent */ + BIT(upload_aborted); /* set to TRUE when upload was aborted. Will also + * show `upload_done` as TRUE. */ BIT(ignorebody); /* we read a response-body but we ignore it! */ BIT(http_bodyless); /* HTTP response status code is between 100 and 199, 204 or 304 */ @@ -206,15 +197,26 @@ CURLcode Curl_req_send(struct Curl_easy *data, struct dynbuf *buf); #endif /* !USE_HYPER */ /** - * Flush all buffered request bytes. - * @return CURLE_OK on success, CURLE_AGAIN if sending was blocked, - * or the error on the sending. + * TRUE iff the request has sent all request headers and data. + */ +bool Curl_req_done_sending(struct Curl_easy *data); + +/* + * Read more from client and flush all buffered request bytes. + * @return CURLE_OK on success or the error on the sending. + * Never returns CURLE_AGAIN. */ -CURLcode Curl_req_flush(struct Curl_easy *data); +CURLcode Curl_req_send_more(struct Curl_easy *data); /** * TRUE iff the request wants to send, e.g. has buffered bytes. */ bool Curl_req_want_send(struct Curl_easy *data); +/** + * Stop sending any more request data to the server. + * Will clear the send buffer and mark request sending as done. + */ +CURLcode Curl_req_abort_sending(struct Curl_easy *data); + #endif /* HEADER_CURL_REQUEST_H */ diff --git a/lib/rtsp.c b/lib/rtsp.c index a0da9f138af..0d8009ad424 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -577,6 +577,8 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) if(result) goto out; + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, FIRSTSOCKET); + /* issue the request */ result = Curl_req_send(data, &req_buffer); if(result) { @@ -584,8 +586,6 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) goto out; } - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, FIRSTSOCKET); - /* Increment the CSeq on success */ data->state.rtsp_next_client_CSeq++; diff --git a/lib/sendf.c b/lib/sendf.c index 8fe9c756143..1b092f06b34 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -576,8 +576,10 @@ static CURLcode cr_in_read(struct Curl_easy *data, return CURLE_READ_ERROR; } ctx->read_len += nread; + if(ctx->total_len >= 0) + ctx->seen_eos = (ctx->read_len >= ctx->total_len); *pnread = nread; - *peos = FALSE; + *peos = ctx->seen_eos; break; } DEBUGF(infof(data, "cr_in_read(len=%zu, total=%"CURL_FORMAT_CURL_OFF_T @@ -743,7 +745,7 @@ static CURLcode cr_lc_add(struct Curl_easy *data) CURLcode result; result = Curl_creader_create(&reader, data, &cr_lc, - CURL_CR_TRANSFER_ENCODE); + CURL_CR_CONTENT_ENCODE); if(!result) result = Curl_creader_add(data, reader); diff --git a/lib/setopt.c b/lib/setopt.c index ce1321fc80b..8a5a5d7c33d 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -2239,7 +2239,6 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) arg = UPLOADBUFFER_MIN; data->set.upload_buffer_size = (unsigned int)arg; - Curl_safefree(data->state.ulbuf); /* force a realloc next opportunity */ break; case CURLOPT_NOSIGNAL: diff --git a/lib/smb.c b/lib/smb.c index 404dd84f43d..77d34e31c48 100644 --- a/lib/smb.c +++ b/lib/smb.c @@ -456,6 +456,9 @@ static CURLcode smb_connect(struct Curl_easy *data, bool *done) smbc->recv_buf = malloc(MAX_MESSAGE_SIZE); if(!smbc->recv_buf) return CURLE_OUT_OF_MEMORY; + smbc->send_buf = malloc(MAX_MESSAGE_SIZE); + if(!smbc->send_buf) + return CURLE_OUT_OF_MEMORY; /* Multiple requests are allowed with this connection */ connkeep(conn, "SMB default"); @@ -567,7 +570,7 @@ static CURLcode smb_send(struct Curl_easy *data, size_t len, size_t bytes_written; CURLcode result; - result = Curl_xfer_send(data, data->state.ulbuf, len, &bytes_written); + result = Curl_xfer_send(data, smbc->send_buf, len, &bytes_written); if(result) return result; @@ -592,7 +595,7 @@ static CURLcode smb_flush(struct Curl_easy *data) if(!smbc->send_size) return CURLE_OK; - result = Curl_xfer_send(data, data->state.ulbuf + smbc->sent, len, + result = Curl_xfer_send(data, smbc->send_buf + smbc->sent, len, &bytes_written); if(result) return result; @@ -608,13 +611,13 @@ static CURLcode smb_flush(struct Curl_easy *data) static CURLcode smb_send_message(struct Curl_easy *data, unsigned char cmd, const void *msg, size_t msg_len) { - CURLcode result = Curl_get_upload_buffer(data); - if(result) - return result; - smb_format_message(data, (struct smb_header *)data->state.ulbuf, + struct connectdata *conn = data->conn; + struct smb_conn *smbc = &conn->proto.smbc; + + smb_format_message(data, (struct smb_header *)smbc->send_buf, cmd, msg_len); - memcpy(data->state.ulbuf + sizeof(struct smb_header), - msg, msg_len); + DEBUGASSERT((sizeof(struct smb_header) + msg_len) <= MAX_MESSAGE_SIZE); + memcpy(smbc->send_buf + sizeof(struct smb_header), msg, msg_len); return smb_send(data, sizeof(struct smb_header) + msg_len, 0); } @@ -772,15 +775,14 @@ static CURLcode smb_send_read(struct Curl_easy *data) static CURLcode smb_send_write(struct Curl_easy *data) { + struct connectdata *conn = data->conn; + struct smb_conn *smbc = &conn->proto.smbc; struct smb_write *msg; struct smb_request *req = data->req.p.smb; curl_off_t offset = data->req.offset; curl_off_t upload_size = data->req.size - data->req.bytecount; - CURLcode result = Curl_get_upload_buffer(data); - if(result) - return result; - msg = (struct smb_write *)data->state.ulbuf; + msg = (struct smb_write *)smbc->send_buf; if(upload_size >= MAX_PAYLOAD_SIZE - 1) /* There is one byte of padding */ upload_size = MAX_PAYLOAD_SIZE - 1; @@ -809,11 +811,11 @@ static CURLcode smb_send_and_recv(struct Curl_easy *data, void **msg) /* Check if there is data in the transfer buffer */ if(!smbc->send_size && smbc->upload_size) { - size_t nread = smbc->upload_size > (size_t)data->set.upload_buffer_size ? - (size_t)data->set.upload_buffer_size : smbc->upload_size; + size_t nread = smbc->upload_size > (size_t)MAX_MESSAGE_SIZE ? + (size_t)MAX_MESSAGE_SIZE : smbc->upload_size; bool eos; - result = Curl_client_read(data, data->state.ulbuf, nread, &nread, &eos); + result = Curl_client_read(data, smbc->send_buf, nread, &nread, &eos); if(result && result != CURLE_AGAIN) return result; if(!nread) @@ -1131,6 +1133,7 @@ static CURLcode smb_disconnect(struct Curl_easy *data, Curl_safefree(smbc->share); Curl_safefree(smbc->domain); Curl_safefree(smbc->recv_buf); + Curl_safefree(smbc->send_buf); return CURLE_OK; } diff --git a/lib/smb.h b/lib/smb.h index 437f4a58a85..9ea2a8cc31c 100644 --- a/lib/smb.h +++ b/lib/smb.h @@ -42,6 +42,7 @@ struct smb_conn { unsigned int session_key; unsigned short uid; char *recv_buf; + char *send_buf; size_t upload_size; size_t send_size; size_t sent; diff --git a/lib/smtp.c b/lib/smtp.c index ddee2223ac4..605bb16eeb0 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -111,6 +111,7 @@ static CURLcode smtp_continue_auth(struct Curl_easy *data, const char *mech, const struct bufref *resp); static CURLcode smtp_cancel_auth(struct Curl_easy *data, const char *mech); static CURLcode smtp_get_message(struct Curl_easy *data, struct bufref *out); +static CURLcode cr_eob_add(struct Curl_easy *data); /* * SMTP protocol handler. @@ -618,7 +619,7 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) result = smtp_parse_address(data->set.str[STRING_MAIL_FROM], &address, &host); if(result) - return result; + goto out; /* Establish whether we should report SMTPUTF8 to the server for this mailbox as per RFC-6531 sect. 3.1 point 4 and sect. 3.4 */ @@ -642,8 +643,10 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) /* Null reverse-path, RFC-5321, sect. 3.6.3 */ from = strdup("<>"); - if(!from) - return CURLE_OUT_OF_MEMORY; + if(!from) { + result = CURLE_OUT_OF_MEMORY; + goto out; + } /* Calculate the optional AUTH parameter */ if(data->set.str[STRING_MAIL_AUTH] && conn->proto.smtpc.sasl.authused) { @@ -655,10 +658,8 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) converting the host name to an IDN A-label if necessary */ result = smtp_parse_address(data->set.str[STRING_MAIL_AUTH], &address, &host); - if(result) { - free(from); - return result; - } + if(result) + goto out; /* Establish whether we should report SMTPUTF8 to the server for this mailbox as per RFC-6531 sect. 3.1 point 4 and sect. 3.4 */ @@ -676,17 +677,14 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) /* An invalid mailbox was provided but we'll simply let the server worry about it */ auth = aprintf("<%s>", address); - - free(address); } else /* Empty AUTH, RFC-2554, sect. 5 */ auth = strdup("<>"); if(!auth) { - free(from); - - return CURLE_OUT_OF_MEMORY; + result = CURLE_OUT_OF_MEMORY; + goto out; } } @@ -710,12 +708,8 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) if(!result) result = Curl_mime_rewind(&data->set.mimepost); - if(result) { - free(from); - free(auth); - - return result; - } + if(result) + goto out; data->state.infilesize = Curl_mime_size(&data->set.mimepost); @@ -730,10 +724,8 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) size = aprintf("%" CURL_FORMAT_CURL_OFF_T, data->state.infilesize); if(!size) { - free(from); - free(auth); - - return CURLE_OUT_OF_MEMORY; + result = CURLE_OUT_OF_MEMORY; + goto out; } } @@ -754,6 +746,15 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) } } + /* Setup client reader for size and EOB conversion */ + result = Client_reader_set_fread(data, data->state.infilesize); + if(result) + goto out; + /* Add the client reader doing STMP EOB escaping */ + result = cr_eob_add(data); + if(result) + goto out; + /* Send the MAIL command */ result = Curl_pp_sendf(data, &conn->proto.smtpc.pp, "MAIL FROM:%s%s%s%s%s%s", @@ -765,6 +766,7 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) utf8 ? " SMTPUTF8" /* Internationalised mailbox */ : ""); /* included in our envelope */ +out: free(from); free(auth); free(size); @@ -1393,9 +1395,6 @@ static CURLcode smtp_done(struct Curl_easy *data, CURLcode status, CURLcode result = CURLE_OK; struct connectdata *conn = data->conn; struct SMTP *smtp = data->req.p.smtp; - struct pingpong *pp = &conn->proto.smtpc.pp; - char *eob; - size_t len, bytes_written; (void)premature; @@ -1411,46 +1410,6 @@ static CURLcode smtp_done(struct Curl_easy *data, CURLcode status, } else if(!data->set.connect_only && data->set.mail_rcpt && (data->state.upload || IS_MIME_POST(data))) { - /* Calculate the EOB taking into account any terminating CRLF from the - previous line of the email or the CRLF of the DATA command when there - is "no mail data". RFC-5321, sect. 4.1.1.4. - - Note: As some SSL backends, such as OpenSSL, will cause Curl_write() to - fail when using a different pointer following a previous write, that - returned CURLE_AGAIN, we duplicate the EOB now rather than when the - bytes written doesn't equal len. */ - if(smtp->trailing_crlf || !data->state.infilesize) { - eob = strdup(&SMTP_EOB[2]); - len = SMTP_EOB_LEN - 2; - } - else { - eob = strdup(SMTP_EOB); - len = SMTP_EOB_LEN; - } - - if(!eob) - return CURLE_OUT_OF_MEMORY; - - /* Send the end of block data */ - result = Curl_xfer_send(data, eob, len, &bytes_written); - if(result) { - free(eob); - return result; - } - - if(bytes_written != len) { - /* The whole chunk was not sent so keep it around and adjust the - pingpong structure accordingly */ - pp->sendthis = eob; - pp->sendsize = len; - pp->sendleft = len - bytes_written; - } - else { - /* Successfully sent so adjust the response timeout relative to now */ - pp->response = Curl_now(); - - free(eob); - } smtp_state(data, SMTP_POSTDATA); @@ -1818,108 +1777,159 @@ static CURLcode smtp_parse_address(const char *fqma, char **address, return result; } -CURLcode Curl_smtp_escape_eob(struct Curl_easy *data, - const ssize_t nread, - const ssize_t offset) +struct cr_eob_ctx { + struct Curl_creader super; + struct bufq buf; + size_t n_eob; /* how many EOB bytes we matched so far */ + size_t eob; /* Number of bytes of the EOB (End Of Body) that + have been received so far */ + BIT(read_eos); /* we read an EOS from the next reader */ + BIT(eos); /* we have returned an EOS */ +}; + +static CURLcode cr_eob_init(struct Curl_easy *data, + struct Curl_creader *reader) { - /* When sending a SMTP payload we must detect CRLF. sequences making sure - they are sent as CRLF.. instead, as a . on the beginning of a line will - be deleted by the server when not part of an EOB terminator and a - genuine CRLF.CRLF which isn't escaped will wrongly be detected as end of - data by the server - */ - ssize_t i; - ssize_t si; - struct SMTP *smtp = data->req.p.smtp; - char *scratch = data->state.scratch; - char *newscratch = NULL; - char *oldscratch = NULL; - size_t eob_sent; + struct cr_eob_ctx *ctx = (struct cr_eob_ctx *)reader; + (void)data; + /* The first char we read is the first on a line, as if we had + * read CRLF just before */ + ctx->n_eob = 2; + Curl_bufq_init2(&ctx->buf, (16 * 1024), 1, BUFQ_OPT_SOFT_LIMIT); + return CURLE_OK; +} - /* Do we need to allocate a scratch buffer? */ - if(!scratch || data->set.crlf) { - oldscratch = scratch; +static void cr_eob_close(struct Curl_easy *data, struct Curl_creader *reader) +{ + struct cr_eob_ctx *ctx = (struct cr_eob_ctx *)reader; + (void)data; + Curl_bufq_free(&ctx->buf); +} - scratch = newscratch = malloc(2 * data->set.upload_buffer_size); - if(!newscratch) { - failf(data, "Failed to alloc scratch buffer"); +/* this is the 5-bytes End-Of-Body marker for SMTP */ +#define SMTP_EOB "\r\n.\r\n" +#define SMTP_EOB_FIND_LEN 3 - return CURLE_OUT_OF_MEMORY; - } - } - DEBUGASSERT((size_t)data->set.upload_buffer_size >= (size_t)nread); - - /* Have we already sent part of the EOB? */ - eob_sent = smtp->eob; - - /* This loop can be improved by some kind of Boyer-Moore style of - approach but that is saved for later... */ - if(offset) - memcpy(scratch, data->req.upload_fromhere, offset); - for(i = offset, si = offset; i < nread; i++) { - if(SMTP_EOB[smtp->eob] == data->req.upload_fromhere[i]) { - smtp->eob++; - - /* Is the EOB potentially the terminating CRLF? */ - if(2 == smtp->eob || SMTP_EOB_LEN == smtp->eob) - smtp->trailing_crlf = TRUE; - else - smtp->trailing_crlf = FALSE; - } - else if(smtp->eob) { - /* A previous substring matched so output that first */ - memcpy(&scratch[si], &SMTP_EOB[eob_sent], smtp->eob - eob_sent); - si += smtp->eob - eob_sent; - - /* Then compare the first byte */ - if(SMTP_EOB[0] == data->req.upload_fromhere[i]) - smtp->eob = 1; - else - smtp->eob = 0; +/* client reader doing SMTP End-Of-Body escaping. */ +static CURLcode cr_eob_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *pnread, bool *peos) +{ + struct cr_eob_ctx *ctx = (struct cr_eob_ctx *)reader; + CURLcode result = CURLE_OK; + size_t nread, i, start, n; + bool eos; + + if(!ctx->read_eos && Curl_bufq_is_empty(&ctx->buf)) { + /* Get more and convert it when needed */ + result = Curl_creader_read(data, reader->next, buf, blen, &nread, &eos); + if(result) + return result; + + ctx->read_eos = eos; + if(nread) { + if(!ctx->n_eob && !memchr(buf, SMTP_EOB[0], nread)) { + /* not in the middle of a match, no EOB start found, just pass */ + *pnread = nread; + *peos = FALSE; + return CURLE_OK; + } + /* scan for EOB (continuation) and convert */ + for(i = start = 0; i < nread; ++i) { + if(ctx->n_eob >= SMTP_EOB_FIND_LEN) { + /* matched the EOB prefix and seeing additional char, add '.' */ + result = Curl_bufq_cwrite(&ctx->buf, buf + start, i - start, &n); + if(result) + return result; + result = Curl_bufq_cwrite(&ctx->buf, ".", 1, &n); + if(result) + return result; + ctx->n_eob = 0; + start = i; + if(data->state.infilesize > 0) + data->state.infilesize++; + } + + if(buf[i] != SMTP_EOB[ctx->n_eob]) + ctx->n_eob = 0; - eob_sent = 0; + if(buf[i] == SMTP_EOB[ctx->n_eob]) { + /* matching another char of the EOB */ + ++ctx->n_eob; + } + } - /* Reset the trailing CRLF flag as there was more data */ - smtp->trailing_crlf = FALSE; + /* add any remainder to buf */ + if(start < nread) { + result = Curl_bufq_cwrite(&ctx->buf, buf + start, nread - start, &n); + if(result) + return result; + } } - /* Do we have a match for CRLF. as per RFC-5321, sect. 4.5.2 */ - if(SMTP_EOB_FIND_LEN == smtp->eob) { - /* Copy the replacement data to the target buffer */ - memcpy(&scratch[si], &SMTP_EOB_REPL[eob_sent], - SMTP_EOB_REPL_LEN - eob_sent); - si += SMTP_EOB_REPL_LEN - eob_sent; - smtp->eob = 0; - eob_sent = 0; + if(ctx->read_eos) { + /* if we last matched a CRLF or if the data was empty, add ".\r\n" + * to end the body. If we sent something and it did not end with "\r\n", + * add "\r\n.\r\n" to end the body */ + const char *eob = SMTP_EOB; + switch(ctx->n_eob) { + case 2: + /* seen a CRLF at the end, just add the remainder */ + eob = &SMTP_EOB[2]; + break; + case 3: + /* ended with '\r\n.', we should escpe the last '.' */ + eob = "." SMTP_EOB; + break; + default: + break; + } + result = Curl_bufq_cwrite(&ctx->buf, eob, strlen(eob), &n); + if(result) + return result; } - else if(!smtp->eob) - scratch[si++] = data->req.upload_fromhere[i]; } - if(smtp->eob - eob_sent) { - /* A substring matched before processing ended so output that now */ - memcpy(&scratch[si], &SMTP_EOB[eob_sent], smtp->eob - eob_sent); - si += smtp->eob - eob_sent; + *peos = FALSE; + if(!Curl_bufq_is_empty(&ctx->buf)) { + result = Curl_bufq_cread(&ctx->buf, buf, blen, pnread); } + else + *pnread = 0; - /* Only use the new buffer if we replaced something */ - if(si != nread) { - /* Upload from the new (replaced) buffer instead */ - data->req.upload_fromhere = scratch; + if(ctx->read_eos && Curl_bufq_is_empty(&ctx->buf)) { + /* no more data, read all, done. */ + ctx->eos = TRUE; + } + *peos = ctx->eos; + DEBUGF(infof(data, "cr_eob_read(%zu) -> %d, %zd, %d", + blen, result, *pnread, *peos)); + return CURLE_OK; +} - /* Save the buffer so it can be freed later */ - data->state.scratch = scratch; +static const struct Curl_crtype cr_eob = { + "cr-smtp-eob", + cr_eob_init, + cr_eob_read, + cr_eob_close, + Curl_creader_def_needs_rewind, + sizeof(struct cr_eob_ctx) +}; - /* Free the old scratch buffer */ - free(oldscratch); +static CURLcode cr_eob_add(struct Curl_easy *data) +{ + struct Curl_creader *reader = NULL; + CURLcode result; - /* Set the new amount too */ - data->req.upload_present = si; - } - else - free(newscratch); + result = Curl_creader_create(&reader, data, &cr_eob, + CURL_CR_CONTENT_ENCODE); + if(!result) + result = Curl_creader_add(data, reader); - return CURLE_OK; + if(result && reader) + Curl_creader_free(data, reader); + return result; } #endif /* CURL_DISABLE_SMTP */ diff --git a/lib/smtp.h b/lib/smtp.h index 7a04c215499..7c2af680739 100644 --- a/lib/smtp.h +++ b/lib/smtp.h @@ -84,17 +84,4 @@ struct smtp_conn { extern const struct Curl_handler Curl_handler_smtp; extern const struct Curl_handler Curl_handler_smtps; -/* this is the 5-bytes End-Of-Body marker for SMTP */ -#define SMTP_EOB "\x0d\x0a\x2e\x0d\x0a" -#define SMTP_EOB_LEN 5 -#define SMTP_EOB_FIND_LEN 3 - -/* if found in data, replace it with this string instead */ -#define SMTP_EOB_REPL "\x0d\x0a\x2e\x2e" -#define SMTP_EOB_REPL_LEN 4 - -CURLcode Curl_smtp_escape_eob(struct Curl_easy *data, - const ssize_t nread, - const ssize_t offset); - #endif /* HEADER_CURL_SMTP_H */ diff --git a/lib/tftp.c b/lib/tftp.c index a99fe1ddcf1..ff2b7b7457b 100644 --- a/lib/tftp.c +++ b/lib/tftp.c @@ -452,8 +452,6 @@ static CURLcode tftp_send_first(struct tftp_state_data *state, if(data->state.upload) { /* If we are uploading, send an WRQ */ setpacketevent(&state->spacket, TFTP_EVENT_WRQ); - state->data->req.upload_fromhere = - (char *)state->spacket.data + 4; if(data->state.infilesize != -1) Curl_pgrsSetUploadSize(data, data->state.infilesize); } diff --git a/lib/transfer.c b/lib/transfer.c index cbda03a2e7a..e6153c6bea3 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -115,16 +115,6 @@ char *Curl_checkheaders(const struct Curl_easy *data, } #endif -CURLcode Curl_get_upload_buffer(struct Curl_easy *data) -{ - if(!data->state.ulbuf) { - data->state.ulbuf = malloc(data->set.upload_buffer_size); - if(!data->state.ulbuf) - return CURLE_OUT_OF_MEMORY; - } - return CURLE_OK; -} - static int data_pending(struct Curl_easy *data) { struct connectdata *conn = data->conn; @@ -330,17 +320,6 @@ static CURLcode readwrite_data(struct Curl_easy *data, return result; } -CURLcode Curl_done_sending(struct Curl_easy *data, - struct SingleRequest *k) -{ - k->keepon &= ~KEEP_SEND; /* we're done writing */ - - /* These functions should be moved into the handler struct! */ - Curl_conn_ev_data_done_send(data); - - return CURLE_OK; -} - #if defined(_WIN32) && defined(USE_WINSOCK) #ifndef SIO_IDEAL_SEND_BACKLOG_QUERY #define SIO_IDEAL_SEND_BACKLOG_QUERY 0x4004747B @@ -368,174 +347,37 @@ static void win_update_buffer_size(curl_socket_t sockfd) /* * Send data to upload to the server, when the socket is writable. */ -static CURLcode readwrite_upload(struct Curl_easy *data, - struct connectdata *conn, - int *didwhat) +static CURLcode readwrite_upload(struct Curl_easy *data, int *didwhat) { - size_t bytes_written; - CURLcode result; - ssize_t nread; /* number of bytes read */ - struct SingleRequest *k = &data->req; - - (void)conn; - *didwhat |= KEEP_SEND; - - if(!(k->keepon & KEEP_SEND_PAUSE)) { - result = Curl_req_flush(data); - if(result == CURLE_AGAIN) /* unable to send all we have */ - return CURLE_OK; - else if(result) - return result; - } - - do { - curl_off_t nbody; - ssize_t offset = 0; - bool eos; - - if(0 != k->upload_present && - k->upload_present < curl_upload_refill_watermark(data) && - !k->upload_chunky &&/*(variable sized chunked header; append not safe)*/ - !k->upload_done && /*!(k->upload_done once k->upload_present sent)*/ - !(k->writebytecount + (curl_off_t)k->upload_present == - data->state.infilesize)) { - offset = k->upload_present; - } - - /* only read more data if there's no upload data already - present in the upload buffer, or if appending to upload buffer */ - if(0 == k->upload_present || offset) { - result = Curl_get_upload_buffer(data); - if(result) - return result; - if(offset && k->upload_fromhere != data->state.ulbuf) - memmove(data->state.ulbuf, k->upload_fromhere, offset); - /* init the "upload from here" pointer */ - k->upload_fromhere = data->state.ulbuf; - - if(!k->upload_done) { - /* HTTP pollution, this should be written nicer to become more - protocol agnostic. */ - size_t fillcount; - - if(k->exp100 == EXP100_SENDING_REQUEST) { - /* If this call is to send body data, we must take some action: - We have sent off the full HTTP 1.1 request, and we shall now - go into the Expect: 100 state and await such a header */ - k->exp100 = EXP100_AWAITING_CONTINUE; /* wait for the header */ - k->keepon &= ~KEEP_SEND; /* disable writing */ - k->start100 = Curl_now(); /* timeout count starts now */ - *didwhat &= ~KEEP_SEND; /* we didn't write anything actually */ - /* set a timeout for the multi interface */ - Curl_expire(data, data->set.expect_100_timeout, EXPIRE_100_TIMEOUT); - break; - } - - k->upload_fromhere += offset; - result = Curl_client_read(data, k->upload_fromhere, - data->set.upload_buffer_size-offset, - &fillcount, &eos); - k->upload_fromhere -= offset; - if(result) - return result; - - nread = offset + fillcount; - } - else - nread = 0; /* we're done uploading/reading */ - - if(!nread && (k->keepon & KEEP_SEND_PAUSE)) { - /* this is a paused transfer */ - break; - } - if(nread <= 0) { - result = Curl_done_sending(data, k); - if(result) - return result; - break; - } + CURLcode result = CURLE_OK; - /* store number of bytes available for upload */ - k->upload_present = nread; + if((data->req.keepon & KEEP_SEND_PAUSE)) + return CURLE_OK; -#ifndef CURL_DISABLE_SMTP - if(conn->handler->protocol & PROTO_FAMILY_SMTP) { - result = Curl_smtp_escape_eob(data, nread, offset); - if(result) - return result; - } -#endif /* CURL_DISABLE_SMTP */ - } /* if 0 == k->upload_present or appended to upload buffer */ - else { - /* We have a partial buffer left from a previous "round". Use - that instead of reading more data */ - } + /* We should not get here when the sending is already done. It + * probably means that someone set `data-req.keepon |= KEEP_SEND` + * when it should not. */ + DEBUGASSERT(!Curl_req_done_sending(data)); - /* write to socket (send away data) */ - result = Curl_xfer_send(data, - k->upload_fromhere, /* buffer pointer */ - k->upload_present, /* buffer size */ - &bytes_written); /* actually sent */ + if(!Curl_req_done_sending(data)) { + *didwhat |= KEEP_SEND; + result = Curl_req_send_more(data); if(result) return result; #if defined(_WIN32) && defined(USE_WINSOCK) + /* FIXME: this looks like it would fit better into cf-socket.c + * but then I do not know enough Windows to say... */ { struct curltime n = Curl_now(); - if(Curl_timediff(n, conn->last_sndbuf_update) > 1000) { - win_update_buffer_size(conn->writesockfd); - conn->last_sndbuf_update = n; + if(Curl_timediff(n, data->conn->last_sndbuf_update) > 1000) { + win_update_buffer_size(data->conn->writesockfd); + data->conn->last_sndbuf_update = n; } } #endif - - nbody = bytes_written; - if(nbody) { - /* show the data before we change the pointer upload_fromhere */ - Curl_debug(data, CURLINFO_DATA_OUT, - &k->upload_fromhere[bytes_written - nbody], - (size_t)nbody); - - k->writebytecount += nbody; - Curl_pgrsSetUploadCounter(data, k->writebytecount); - } - - if((!k->upload_chunky || k->forbidchunk) && - (k->writebytecount == data->state.infilesize)) { - /* we have sent all data we were supposed to */ - k->upload_done = TRUE; - infof(data, "We are completely uploaded and fine"); - } - - if(k->upload_present != bytes_written) { - /* we only wrote a part of the buffer (if anything), deal with it! */ - - /* store the amount of bytes left in the buffer to write */ - k->upload_present -= bytes_written; - - /* advance the pointer where to find the buffer when the next send - is to happen */ - k->upload_fromhere += bytes_written; - } - else { - /* we've uploaded that buffer now */ - result = Curl_get_upload_buffer(data); - if(result) - return result; - k->upload_fromhere = data->state.ulbuf; - k->upload_present = 0; /* no more bytes left */ - - if(k->upload_done) { - result = Curl_done_sending(data, k); - if(result) - return result; - } - } - - - } while(0); /* just to break out from! */ - - return CURLE_OK; + } + return result; } static int select_bits_paused(struct Curl_easy *data, int select_bits) @@ -626,7 +468,7 @@ CURLcode Curl_readwrite(struct Curl_easy *data, if((k->keepon & KEEP_SEND) && (select_bits & CURL_CSELECT_OUT)) { /* write */ - result = readwrite_upload(data, conn, &didwhat); + result = readwrite_upload(data, &didwhat); if(result) goto out; } @@ -1458,3 +1300,9 @@ CURLcode Curl_xfer_recv(struct Curl_easy *data, blen = (size_t)data->set.buffer_size; return Curl_conn_recv(data, sockindex, buf, blen, pnrcvd); } + +CURLcode Curl_xfer_send_close(struct Curl_easy *data) +{ + Curl_conn_ev_data_done_send(data); + return CURLE_OK; +} diff --git a/lib/transfer.h b/lib/transfer.h index a4af1899e51..96e69988ad9 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -50,10 +50,6 @@ int Curl_single_getsock(struct Curl_easy *data, struct connectdata *conn, curl_socket_t *socks); CURLcode Curl_retry_request(struct Curl_easy *data, char **url); bool Curl_meets_timecondition(struct Curl_easy *data, time_t timeofdoc); -CURLcode Curl_get_upload_buffer(struct Curl_easy *data); - -CURLcode Curl_done_sending(struct Curl_easy *data, - struct SingleRequest *k); /** * Write the transfer raw response bytes, as received from the connection. @@ -106,4 +102,6 @@ CURLcode Curl_xfer_recv(struct Curl_easy *data, char *buf, size_t blen, ssize_t *pnrcvd); +CURLcode Curl_xfer_send_close(struct Curl_easy *data); + #endif /* HEADER_CURL_TRANSFER_H */ diff --git a/lib/url.c b/lib/url.c index d72dfc773bb..b3057659764 100644 --- a/lib/url.c +++ b/lib/url.c @@ -277,7 +277,6 @@ CURLcode Curl_close(struct Curl_easy **datap) up_free(data); Curl_dyn_free(&data->state.headerb); - Curl_safefree(data->state.ulbuf); Curl_flush_cookies(data, TRUE); Curl_altsvc_save(data, data->asi, data->set.str[STRING_ALTSVC]); Curl_altsvc_cleanup(&data->asi); diff --git a/lib/urldata.h b/lib/urldata.h index 3d68a60563a..0871e1348d5 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1215,7 +1215,6 @@ struct UrlState { struct dynbuf headerb; /* buffer to store headers in */ struct curl_slist *hstslist; /* list of HSTS files set by curl_easy_setopt(HSTS) calls */ - char *ulbuf; /* allocated upload buffer or NULL */ curl_off_t current_speed; /* the ProgressShow() function sets this, bytes / second */ From 945475750814e119f817ff73fb71f1435aee87b1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 3 Mar 2024 18:41:52 +0100 Subject: [PATCH 409/509] cookie: if psl fails, reject the cookie A libpsl install without data and no built-in database is now considered bad enough to reject all cookies since they cannot be checked. It is somewhat of a user error, but still. Reported-by: Dan Fandrich Closes #13033 --- lib/cookie.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/cookie.c b/lib/cookie.c index d10dd572baa..c1ed2913c40 100644 --- a/lib/cookie.c +++ b/lib/cookie.c @@ -426,6 +426,7 @@ static void remove_expired(struct CookieInfo *cookies) } } +#ifndef USE_LIBPSL /* Make sure domain contains a dot or is localhost. */ static bool bad_domain(const char *domain, size_t len) { @@ -443,6 +444,7 @@ static bool bad_domain(const char *domain, size_t len) } return TRUE; } +#endif /* RFC 6265 section 4.1.1 says a server should accept this range: @@ -1040,7 +1042,7 @@ Curl_cookie_add(struct Curl_easy *data, Curl_psl_release(data); } else - acceptable = !bad_domain(domain, strlen(domain)); + infof(data, "libpsl problem, rejecting cookie for satety"); } if(!acceptable) { From ee31f696902a1b4a80c29e18ad055b93ec08f4bf Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 4 Mar 2024 10:05:52 +0100 Subject: [PATCH 410/509] pytest: adapt to API change - pytest has changed the signature of the hook pytest_report_header() for some obscure reason and that change landed in our CI now - remove the changed param that we never used anyway Closes #13037 --- tests/conftest.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/conftest.py b/tests/conftest.py index 713a1742317..7ab6d7c9fe6 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -26,10 +26,10 @@ sys.path.append(os.path.join(os.path.dirname(__file__), 'http')) -import pytest from testenv import Env -def pytest_report_header(config, startdir): + +def pytest_report_header(config): # Env inits its base properties only once, we can report them here env = Env() report = [ From 36a95c516355f3fa965d873f02a52f16fab9f586 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 4 Mar 2024 14:31:36 +0000 Subject: [PATCH 411/509] build(deps): bump fsfe/reuse-action from 2 to 3 Bumps [fsfe/reuse-action](https://github.com/fsfe/reuse-action) from 2 to 3. - [Release notes](https://github.com/fsfe/reuse-action/releases) - [Commits](https://github.com/fsfe/reuse-action/compare/v2...v3) --- updated-dependencies: - dependency-name: fsfe/reuse-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/reuse.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/reuse.yml b/.github/workflows/reuse.yml index 27b33e2c8ab..0818bfaabf0 100644 --- a/.github/workflows/reuse.yml +++ b/.github/workflows/reuse.yml @@ -26,4 +26,4 @@ jobs: steps: - uses: actions/checkout@v4 - name: REUSE Compliance Check - uses: fsfe/reuse-action@v2 + uses: fsfe/reuse-action@v3 From e455490c3c424f3a93717540369f77df79da727d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2024 14:26:14 +0100 Subject: [PATCH 412/509] _VARIABLES.md: improve the description Closes #13040 --- docs/cmdline-opts/_VARIABLES.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/cmdline-opts/_VARIABLES.md b/docs/cmdline-opts/_VARIABLES.md index 77e9523b9a9..aa6a8ae4f73 100644 --- a/docs/cmdline-opts/_VARIABLES.md +++ b/docs/cmdline-opts/_VARIABLES.md @@ -26,15 +26,15 @@ set: 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. +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 sent -as POST data: +called "fix". Make sure that the content is trimmed and percent-encoded when +sent as POST data: --variable %HOME --expand-variable fix@{{HOME}}/.secret From 07b667567f63a1c30f6cfae1898af55cb6090906 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2024 10:07:07 +0100 Subject: [PATCH 413/509] smtp: free a temp resource The returned address needs to be freed. Follow-up to e3905de8196d67b89df1602feb84c1f993211b20 Spotted by Coverity Closes #13038 --- lib/smtp.c | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/smtp.c b/lib/smtp.c index 605bb16eeb0..a937fbf217c 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -677,6 +677,7 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) /* An invalid mailbox was provided but we'll simply let the server worry about it */ auth = aprintf("<%s>", address); + free(address); } else /* Empty AUTH, RFC-2554, sect. 5 */ From 6f685f04fd3780a19707703c4095db1d60035202 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2024 23:04:05 +0100 Subject: [PATCH 414/509] CONTRIBUTE: update the section on documentation format ... since most of it is markdown now. Closes #13046 --- .github/scripts/spellcheck.words | 1 + docs/CONTRIBUTE.md | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index 1c408f03aa2..d851228688f 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -451,6 +451,7 @@ makefiles malloc mallocs manpage +manpages maprintf Marek Mavrogiannopoulos diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md index 24928116c85..6288dac90d2 100644 --- a/docs/CONTRIBUTE.md +++ b/docs/CONTRIBUTE.md @@ -105,9 +105,10 @@ 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 From eb9166dc661a62f902d0834eb1877591881d65fe Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2024 15:16:11 +0100 Subject: [PATCH 415/509] gen.pl: make the "manpageification" faster The function that replaces occurances of "--longoption" with "-Z, --longoption" etc with the proper highlight applied, no longer loops over the options. Closes #13041 --- docs/cmdline-opts/_OPTIONS.md | 2 +- docs/cmdline-opts/gen.pl | 24 +++++++++++------------- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/cmdline-opts/_OPTIONS.md b/docs/cmdline-opts/_OPTIONS.md index 8f388130aaa..106298e7457 100644 --- a/docs/cmdline-opts/_OPTIONS.md +++ b/docs/cmdline-opts/_OPTIONS.md @@ -17,7 +17,7 @@ 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. +--**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 diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index 9105529998f..e7b621b2dc2 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -72,16 +72,23 @@ sub manpageify { my ($k)=@_; my $l; + my $trail; + # the matching pattern might include a trailing dot that cannot be part of + # the option name + if($k =~ s/\.$//) { + # cut off trailing dot + $trail = "."; + } my $klong = $k; # quote "bare" minuses in the long name $klong =~ s/-/\\-/g; - if($optlong{$k} ne "") { + if($optlong{$k}) { # both short + long - $l = "\\fI-".$optlong{$k}.", \\-\\-$klong\\fP"; + $l = "\\fI-".$optlong{$k}.", \\-\\-$klong\\fP$trail"; } else { # only long - $l = "\\fI\\-\\-$klong\\fP"; + $l = "\\fI\\-\\-$klong\\fP$trail"; } return $l; } @@ -289,16 +296,7 @@ sub render { $d =~ s/\\/\\\\/g; if(!$quote && $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; - } + $d =~ s/--([a-z0-9.-]+)/manpageify($1)/ge; } # quote minuses in the output From 065faf2f932d08a3278d832f21a60e1d1d517824 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 4 Mar 2024 17:12:42 +0000 Subject: [PATCH 416/509] openssl-quic: fix unity build, casing, indentation - rename static functions to avoid duplicate symbols in unity mode. - windows -> Windows/window in error message and comment. - fix indentation. Reviewed-by: Stefan Eissing Closes #13044 --- lib/vquic/curl_osslq.c | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/lib/vquic/curl_osslq.c b/lib/vquic/curl_osslq.c index 1d78bd71711..a09adcb6441 100644 --- a/lib/vquic/curl_osslq.c +++ b/lib/vquic/curl_osslq.c @@ -67,7 +67,7 @@ * Chunk size is large enough to take a full DATA frame */ #define H3_STREAM_WINDOW_SIZE (128 * 1024) #define H3_STREAM_CHUNK_SIZE (16 * 1024) -/* The pool keeps spares around and half of a full stream windows +/* The pool keeps spares around and half of a full stream window * seems good. More does not seem to improve performance. * The benefit of the pool is that stream buffer to not keep * spares. So memory consumption goes down when streams run empty, @@ -100,7 +100,7 @@ typedef unsigned long sslerr_t; static CURLcode cf_progress_ingress(struct Curl_cfilter *cf, struct Curl_easy *data); -static const char *SSL_ERROR_to_str(int err) +static const char *osslq_SSL_ERROR_to_str(int err) { switch(err) { case SSL_ERROR_NONE: @@ -139,7 +139,7 @@ static const char *SSL_ERROR_to_str(int err) } /* Return error string for last OpenSSL error */ -static char *ossl_strerror(unsigned long error, char *buf, size_t size) +static char *osslq_strerror(unsigned long error, char *buf, size_t size) { DEBUGASSERT(size); *buf = '\0'; @@ -381,8 +381,8 @@ static CURLcode cf_osslq_h3conn_add_stream(struct cf_osslq_h3conn *h3, } static CURLcode cf_osslq_ssl_err(struct Curl_cfilter *cf, - struct Curl_easy *data, - int detail, CURLcode def_result) + struct Curl_easy *data, + int detail, CURLcode def_result) { struct cf_osslq_ctx *ctx = cf->ctx; CURLcode result = def_result; @@ -421,7 +421,7 @@ static CURLcode cf_osslq_ssl_err(struct Curl_cfilter *cf, /* If client certificate is required, communicate the error to client */ result = CURLE_SSL_CLIENTCERT; - ossl_strerror(errdetail, ebuf, sizeof(ebuf)); + osslq_strerror(errdetail, ebuf, sizeof(ebuf)); } #endif else if((lib == ERR_LIB_SSL) && (reason == SSL_R_PROTOCOL_IS_SHUTDOWN)) { @@ -431,7 +431,7 @@ static CURLcode cf_osslq_ssl_err(struct Curl_cfilter *cf, } else { result = def_result; - ossl_strerror(errdetail, ebuf, sizeof(ebuf)); + osslq_strerror(errdetail, ebuf, sizeof(ebuf)); } /* detail is already set to the SSL error above */ @@ -451,7 +451,7 @@ static CURLcode cf_osslq_ssl_err(struct Curl_cfilter *cf, if(sockerr && detail == SSL_ERROR_SYSCALL) Curl_strerror(sockerr, extramsg, sizeof(extramsg)); failf(data, "QUIC connect: %s in connection to %s:%d (%s)", - extramsg[0] ? extramsg : SSL_ERROR_to_str(detail), + extramsg[0] ? extramsg : osslq_SSL_ERROR_to_str(detail), ctx->peer.dispname, r_port, r_ip); } else { @@ -976,7 +976,7 @@ static nghttp3_callbacks ngh3_callbacks = { }; static CURLcode cf_osslq_h3conn_init(struct cf_osslq_ctx *ctx, SSL *conn, - void *user_data) + void *user_data) { struct cf_osslq_h3conn *h3 = &ctx->h3; CURLcode result; @@ -1083,7 +1083,7 @@ static CURLcode cf_osslq_ctx_start(struct Curl_cfilter *cf, */ #if defined(_WIN32) && !defined(__LWIP_OPT_H__) && !defined(LWIP_HDR_OPT_H) if(ctx->q.sockfd > INT_MAX) { - failf(data, "windows socket identifier larger than MAX_INT, " + failf(data, "Windows socket identifier larger than MAX_INT, " "unable to set in OpenSSL dgram API."); result = CURLE_QUIC_CONNECT_ERROR; goto out; @@ -1170,7 +1170,7 @@ static ssize_t h3_quic_recv(void *reader_ctx, SSL_get_stream_read_error_code(x->s->ssl, &app_error_code); CURL_TRC_CF(x->data, x->cf, "[%" PRId64 "] h3_quic_recv -> RESET, " "rv=%d, app_err=%" PRIu64, - x->s->id, rv, app_error_code); + x->s->id, rv, app_error_code); if(app_error_code != NGHTTP3_H3_NO_ERROR) { x->s->reset = TRUE; } @@ -1443,7 +1443,7 @@ static CURLcode h3_send_streams(struct Curl_cfilter *cf, case SSL_ERROR_WANT_READ: /* QUIC blocked us from writing more */ CURL_TRC_CF(data, cf, "[%"PRId64"] send %zu bytes to QUIC blocked", - s->id, vec[i].len); + s->id, vec[i].len); written = 0; nghttp3_conn_block_stream(ctx->h3.conn, s->id); s->send_blocked = blocked = TRUE; From 9c7768cd8820c80a452211f88dd1339d41f22a80 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 4 Mar 2024 17:07:40 +0000 Subject: [PATCH 417/509] openssl-quic: fix BIO leak and Windows warning Caused by an accidentally duplicated line in d6825df334def106f735ce7e0c1a2ea87bddffb0. ``` .../lib/vquic/curl_osslq.c:1095:30: warning: implicit conversion loses integer precision: 'curl_socket_t' (aka 'unsigned long long') to 'int' [-Wshorten-64-to-32] 1095 | bio = BIO_new_dgram(ctx->q.sockfd, BIO_NOCLOSE); | ~~~~~~~~~~~~~ ~~~~~~~^~~~~~ 1 warning and 2 errors generated. ``` Reviewed-by: Stefan Eissing Closes #13043 --- lib/vquic/curl_osslq.c | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/vquic/curl_osslq.c b/lib/vquic/curl_osslq.c index a09adcb6441..0e5606d75e3 100644 --- a/lib/vquic/curl_osslq.c +++ b/lib/vquic/curl_osslq.c @@ -1092,7 +1092,6 @@ static CURLcode cf_osslq_ctx_start(struct Curl_cfilter *cf, #else bio = BIO_new_dgram(ctx->q.sockfd, BIO_NOCLOSE); #endif - bio = BIO_new_dgram(ctx->q.sockfd, BIO_NOCLOSE); if(!bio) { result = CURLE_OUT_OF_MEMORY; goto out; From 14bcea074a78227248b00bb6fb22462e0c1b65aa Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 29 Feb 2024 10:12:39 +0100 Subject: [PATCH 418/509] lib: enhance client reader resume + rewind - update client reader documentation - client reader, add rewind capabilities - tell creader to rewind on next start - Curl_client_reset() will keep reader for future rewind if requested - add Curl_client_cleanup() for freeing all resources independent of rewinds - add Curl_client_start() to trigger rewinds - move rewind code from multi.c to sendf.c and make part of "cr-in"'s implementation - http, move the "resume_from" handling into the client readers - the setup of a HTTP request is reshuffled to follow: * determine method, target, auth negotiation * install the client reader(s) for the request, including crlf conversions and "chunked" encoding * apply ranges to client reader * concat request headers, upgrades, cookies, etc. * complete request by determining Content-Length of installed readers in combination with method * send - add methods for client readers to * return the overall length they will generate (or -1 when unknown) * return the amount of data on the CLIENT level, so that expect-100 can decide if it want to apply itself * set a "resume_from" offset or fail if unsupported - struct HTTP has become largely empty now - rename `Client_reader_*` to `Curl_creader_*` Closes #13026 --- docs/CLIENT-READERS.md | 37 ++- lib/c-hyper.c | 14 +- lib/http.c | 499 +++++++++++++++++------------------------ lib/http.h | 13 +- lib/http_chunks.c | 12 + lib/multi.c | 90 -------- lib/request.c | 64 ++++-- lib/request.h | 3 +- lib/rtsp.c | 37 +-- lib/sendf.c | 348 ++++++++++++++++++++++++++-- lib/sendf.h | 78 ++++++- lib/smtp.c | 14 +- lib/transfer.c | 9 +- lib/urldata.h | 3 - scripts/singleuse.pl | 3 +- 15 files changed, 751 insertions(+), 473 deletions(-) diff --git a/docs/CLIENT-READERS.md b/docs/CLIENT-READERS.md index 66cf09dda0f..dec35b3282e 100644 --- a/docs/CLIENT-READERS.md +++ b/docs/CLIENT-READERS.md @@ -31,6 +31,11 @@ struct Curl_crtype { 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 { @@ -80,6 +85,36 @@ Implemented in `sendf.c` for phase `CURL_CR_CLIENT`, this reader get a buffer po 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. @@ -87,7 +122,5 @@ By adding the client reader interface, any protocol can control how/if it wants 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: -* delegate the actual "rewinding" to the readers. The should know how it is done, eliminating the `readrewind.c` protocol specifics in `multi.c`. * `expect-100` handling: place that into a HTTP specific reader at `CURL_CR_PROTOCOL` and eliminate the checks in the generic transfer parts. -* `eos` detection: `upload_done` is partly triggered now by comparing the number of bytes sent to a known size. This is no longer necessary since the core readers obey length restrictions. * `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/lib/c-hyper.c b/lib/c-hyper.c index 6bac1a35732..c59f2bf337b 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -363,7 +363,7 @@ CURLcode Curl_hyper_stream(struct Curl_easy *data, k->exp100 = EXP100_SEND_DATA; k->keepon |= KEEP_SEND; Curl_expire_done(data, EXPIRE_100_TIMEOUT); - infof(data, "Done waiting for 100-continue"); + infof(data, "Done waiting for 100-continue after %ldms", (long)ms); if(data->hyp.exp100_waker) { hyper_waker_wake(data->hyp.exp100_waker); data->hyp.exp100_waker = NULL; @@ -848,7 +848,9 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) may be parts of the request that is not yet sent, since we can deal with the rest of the request in the PERFORM phase. */ *done = TRUE; - Curl_client_reset(data); + result = Curl_client_start(data); + if(result) + return result; /* Add collecting of headers written to client. For a new connection, * we might have done that already, but reuse @@ -883,9 +885,9 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) return result; } - result = Curl_http_resume(data, conn, httpreq); + result = Curl_http_req_set_reader(data, httpreq, &te); if(result) - return result; + goto error; result = Curl_http_range(data, httpreq); if(result) @@ -1006,10 +1008,6 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) goto error; } - result = Curl_http_body(data, conn, httpreq, &te); - if(result) - goto error; - if(data->state.aptr.host) { result = Curl_hyper_header(data, headers, data->state.aptr.host); if(result) diff --git a/lib/http.c b/lib/http.c index 65febe77f7a..ec9e69f4f2f 100644 --- a/lib/http.c +++ b/lib/http.c @@ -430,50 +430,23 @@ static CURLcode http_perhapsrewind(struct Curl_easy *data, { struct HTTP *http = data->req.p.http; curl_off_t bytessent; - curl_off_t expectsend = -1; /* default is unknown */ + curl_off_t expectsend = Curl_creader_total_length(data); if(!http) /* If this is still NULL, we have not reach very far and we can safely skip this rewinding stuff */ return CURLE_OK; - switch(data->state.httpreq) { - case HTTPREQ_GET: - case HTTPREQ_HEAD: + if(!expectsend) + /* not sending any body */ return CURLE_OK; - default: - break; - } - - bytessent = data->req.writebytecount; - if(data->req.authneg) { - /* This is a state where we are known to be negotiating and we don't send - any data then. */ - expectsend = 0; - } - else if(!conn->bits.protoconnstart) { + if(!conn->bits.protoconnstart) /* HTTP CONNECT in progress: there is no body */ expectsend = 0; - } - else { - /* figure out how much data we are expected to send */ - switch(data->state.httpreq) { - case HTTPREQ_POST: - case HTTPREQ_PUT: - if(data->state.infilesize != -1) - expectsend = data->state.infilesize; - break; - case HTTPREQ_POST_FORM: - case HTTPREQ_POST_MIME: - expectsend = http->postsize; - break; - default: - break; - } - } - data->state.rewindbeforesend = FALSE; /* default */ + bytessent = data->req.writebytecount; + Curl_creader_set_rewind(data, FALSE); if((expectsend == -1) || (expectsend > bytessent)) { #if defined(USE_NTLM) @@ -490,7 +463,7 @@ static CURLcode http_perhapsrewind(struct Curl_easy *data, /* rewind data when completely done sending! */ if(!data->req.authneg && (conn->writesockfd != CURL_SOCKET_BAD)) { - data->state.rewindbeforesend = TRUE; + Curl_creader_set_rewind(data, TRUE); infof(data, "Rewind stream before next send"); } @@ -518,7 +491,7 @@ static CURLcode http_perhapsrewind(struct Curl_easy *data, /* rewind data when completely done sending! */ if(!data->req.authneg && (conn->writesockfd != CURL_SOCKET_BAD)) { - data->state.rewindbeforesend = TRUE; + Curl_creader_set_rewind(data, TRUE); infof(data, "Rewind stream before next send"); } @@ -543,9 +516,9 @@ static CURLcode http_perhapsrewind(struct Curl_easy *data, closure so we can safely do the rewind right now */ } - if(Curl_client_read_needs_rewind(data)) { + if(Curl_creader_needs_rewind(data)) { /* mark for rewind since if we already sent something */ - data->state.rewindbeforesend = TRUE; + Curl_creader_set_rewind(data, TRUE); infof(data, "Please rewind output before next send"); } @@ -604,7 +577,7 @@ CURLcode Curl_http_auth_act(struct Curl_easy *data) if(pickhost || pickproxy) { if((data->state.httpreq != HTTPREQ_GET) && (data->state.httpreq != HTTPREQ_HEAD) && - !data->state.rewindbeforesend) { + !Curl_creader_will_rewind(data)) { result = http_perhapsrewind(data, conn); if(result) return result; @@ -2021,13 +1994,11 @@ CURLcode Curl_http_target(struct Curl_easy *data, return result; } -CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, - Curl_HttpReq httpreq, const char **tep) +#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) +static CURLcode set_post_reader(struct Curl_easy *data, Curl_HttpReq httpreq) { - CURLcode result = CURLE_OK; - const char *ptr; - struct HTTP *http = data->req.p.http; - http->postsize = 0; + curl_off_t postsize = 0; + CURLcode result; switch(httpreq) { #ifndef CURL_DISABLE_MIME @@ -2056,6 +2027,7 @@ CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, #endif default: data->state.mimepost = NULL; + break; } #ifndef CURL_DISABLE_MIME @@ -2081,10 +2053,137 @@ CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, result = Curl_mime_rewind(data->state.mimepost); if(result) return result; - http->postsize = Curl_mime_size(data->state.mimepost); + postsize = Curl_mime_size(data->state.mimepost); } #endif + switch(httpreq) { + case HTTPREQ_POST_FORM: + case HTTPREQ_POST_MIME: + /* This is form posting using mime data. */ + data->state.infilesize = postsize; + if(!postsize) + result = Curl_creader_set_null(data); + else { + /* Read from mime structure. We could do a special client reader + * for this, but replacing the callback seems to work fine. */ + data->state.fread_func = (curl_read_callback) Curl_mime_read; + data->state.in = (void *) data->state.mimepost; + result = Curl_creader_set_fread(data, postsize); + } + return result; + default: + if(!postsize) + result = Curl_creader_set_null(data); + else + result = Curl_creader_set_fread(data, postsize); + return result; + } + /* never reached */ +} +#endif + +static CURLcode set_reader(struct Curl_easy *data, Curl_HttpReq httpreq) +{ + CURLcode result = CURLE_OK; + curl_off_t postsize = data->state.infilesize; + + DEBUGASSERT(data->conn); + + if(data->req.authneg) { + return Curl_creader_set_null(data); + } + + switch(httpreq) { + case HTTPREQ_PUT: /* Let's PUT the data to the server! */ + if(!postsize) + result = Curl_creader_set_null(data); + else + result = Curl_creader_set_fread(data, postsize); + return result; + +#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) + case HTTPREQ_POST_FORM: + case HTTPREQ_POST_MIME: + return set_post_reader(data, httpreq); +#endif + + case HTTPREQ_POST: + /* this is the simple POST, using x-www-form-urlencoded style */ + /* the size of the post body */ + if(!postsize) { + result = Curl_creader_set_null(data); + } + else if(data->set.postfields) { + if(postsize > 0) + result = Curl_creader_set_buf(data, data->set.postfields, + (size_t)postsize); + else + result = Curl_creader_set_null(data); + } + else { /* we read the bytes from the callback */ + result = Curl_creader_set_fread(data, postsize); + } + return result; + + default: + /* HTTP GET/HEAD download, has no body, needs no Content-Length */ + data->state.infilesize = 0; + return Curl_creader_set_null(data); + } + /* not reached */ +} + +static CURLcode http_resume(struct Curl_easy *data, Curl_HttpReq httpreq) +{ + if((HTTPREQ_POST == httpreq || HTTPREQ_PUT == httpreq) && + data->state.resume_from) { + /********************************************************************** + * Resuming upload in HTTP means that we PUT or POST and that we have + * got a resume_from value set. The resume value has already created + * a Range: header that will be passed along. We need to "fast forward" + * the file the given number of bytes and decrease the assume upload + * file size before we continue this venture in the dark lands of HTTP. + * Resuming mime/form posting at an offset > 0 has no sense and is ignored. + *********************************************************************/ + + if(data->state.resume_from < 0) { + /* + * This is meant to get the size of the present remote-file by itself. + * We don't support this now. Bail out! + */ + data->state.resume_from = 0; + } + + if(data->state.resume_from && !data->req.authneg) { + /* only act on the first request */ + CURLcode result; + result = Curl_creader_resume_from(data, data->state.resume_from); + if(result) { + failf(data, "Unable to resume from offset %" CURL_FORMAT_CURL_OFF_T, + data->state.resume_from); + return result; + } + } + } + return CURLE_OK; +} + +CURLcode Curl_http_req_set_reader(struct Curl_easy *data, + Curl_HttpReq httpreq, + const char **tep) +{ + CURLcode result = CURLE_OK; + const char *ptr; + + result = set_reader(data, httpreq); + if(result) + return result; + + result = http_resume(data, httpreq); + if(result) + return result; + ptr = Curl_checkheaders(data, STRCONST("Transfer-Encoding")); if(ptr) { /* Some kind of TE is requested, check if 'chunked' is chosen */ @@ -2093,18 +2192,14 @@ CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, STRCONST("Transfer-Encoding:"), STRCONST("chunked")); } else { - if((conn->handler->protocol & PROTO_FAMILY_HTTP) && - (((httpreq == HTTPREQ_POST_MIME || httpreq == HTTPREQ_POST_FORM) && - http->postsize < 0) || - ((data->state.upload || httpreq == HTTPREQ_POST) && - data->state.infilesize == -1))) { - if(data->req.authneg) - /* don't enable chunked during auth neg */ - ; - else if(Curl_use_http_1_1plus(data, conn)) { - if(conn->httpversion < 20) - /* HTTP, upload, unknown file size and not HTTP 1.0 */ - data->req.upload_chunky = TRUE; + curl_off_t req_clen = Curl_creader_total_length(data); + + if(req_clen < 0) { + /* indeterminate request content length */ + if(Curl_use_http_1_1plus(data, data->conn)) { + /* On HTTP/1.1, enable chunked, on HTTP/2 and later we do not + * need it */ + data->req.upload_chunky = (data->conn->httpversion < 20); } else { failf(data, "Chunky upload is not supported by HTTP 1.0"); @@ -2127,7 +2222,6 @@ static CURLcode addexpect(struct Curl_easy *data, struct dynbuf *r) data->state.expect100header = FALSE; /* Avoid Expect: 100-continue if Upgrade: is used */ if(data->req.upgr101 == UPGR101_INIT) { - struct HTTP *http = data->req.p.http; /* For really small puts we don't use Expect: headers at all, and for the somewhat bigger ones we allow the app to disable it. Just make sure that the expect100header is always set to the preferred value @@ -2138,8 +2232,11 @@ static CURLcode addexpect(struct Curl_easy *data, struct dynbuf *r) Curl_compareheader(ptr, STRCONST("Expect:"), STRCONST("100-continue")); } - else if(http->postsize > EXPECT_100_THRESHOLD || http->postsize < 0) - return expect100(data, r); + else { + curl_off_t client_len = Curl_creader_client_length(data); + if(client_len > EXPECT_100_THRESHOLD || client_len < 0) + return expect100(data, r); + } } return CURLE_OK; } @@ -2148,85 +2245,48 @@ CURLcode Curl_http_req_complete(struct Curl_easy *data, struct dynbuf *r, Curl_HttpReq httpreq) { CURLcode result = CURLE_OK; - struct HTTP *http = data->req.p.http; + curl_off_t req_clen; + DEBUGASSERT(data->conn); +#ifndef USE_HYPER if(data->req.upload_chunky) { result = Curl_httpchunk_add_reader(data); if(result) return result; } +#endif - DEBUGASSERT(data->conn); + /* Get the request body length that has been set up */ + req_clen = Curl_creader_total_length(data); switch(httpreq) { - case HTTPREQ_PUT: /* Let's PUT the data to the server! */ - - if(data->req.authneg) - http->postsize = 0; - else - http->postsize = data->state.infilesize; - - if((http->postsize != -1) && !data->req.upload_chunky && - (data->req.authneg || - !Curl_checkheaders(data, STRCONST("Content-Length")))) { - /* only add Content-Length if not uploading chunked */ - result = Curl_dyn_addf(r, "Content-Length: %" CURL_FORMAT_CURL_OFF_T - "\r\n", http->postsize); - if(result) - goto out; - } - - result = addexpect(data, r); - if(result) - goto out; - - /* end of headers */ - result = Curl_dyn_addn(r, STRCONST("\r\n")); - if(result) - goto out; - - /* set the upload size to the progress meter */ - Curl_pgrsSetUploadSize(data, http->postsize); - if(!http->postsize) - result = Client_reader_set_null(data); - else - result = Client_reader_set_fread(data, data->state.infilesize); - break; - + case HTTPREQ_PUT: + case HTTPREQ_POST: #if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) case HTTPREQ_POST_FORM: case HTTPREQ_POST_MIME: - /* This is form posting using mime data. */ - if(data->req.authneg) { - /* nothing to post! */ - result = Curl_dyn_addn(r, STRCONST("Content-Length: 0\r\n\r\n")); - if(!result) - result = Client_reader_set_null(data); - if(result) - return result; - /* setup variables for the upcoming transfer */ - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); - break; - } - - data->state.infilesize = http->postsize; - +#endif /* We only set Content-Length and allow a custom Content-Length if we don't upload data chunked, as RFC2616 forbids us to set both - kinds of headers (Transfer-Encoding: chunked and Content-Length) */ - if(http->postsize != -1 && !data->req.upload_chunky && - (!Curl_checkheaders(data, STRCONST("Content-Length")))) { + kinds of headers (Transfer-Encoding: chunked and Content-Length). + We do not override a custom "Content-Length" header, but during + authentication negotiation that header is suppressed. + */ + if(req_clen >= 0 && !data->req.upload_chunky && + (data->req.authneg || + !Curl_checkheaders(data, STRCONST("Content-Length")))) { /* we allow replacing this header if not during auth negotiation, although it isn't very wise to actually set your own */ result = Curl_dyn_addf(r, "Content-Length: %" CURL_FORMAT_CURL_OFF_T - "\r\n", http->postsize); - if(result) - goto out; + "\r\n", req_clen); } + if(result) + goto out; #ifndef CURL_DISABLE_MIME /* Output mime-generated headers. */ - { + if(data->state.mimepost && + ((httpreq == HTTPREQ_POST_FORM) || (httpreq == HTTPREQ_POST_MIME))) { struct curl_slist *hdr; for(hdr = data->state.mimepost->curlheaders; hdr; hdr = hdr->next) { @@ -2236,93 +2296,26 @@ CURLcode Curl_http_req_complete(struct Curl_easy *data, } } #endif - - result = addexpect(data, r); - if(result) - goto out; - - /* make the request end in a true CRLF */ - result = Curl_dyn_addn(r, STRCONST("\r\n")); - if(result) - goto out; - - /* set the upload size to the progress meter */ - Curl_pgrsSetUploadSize(data, http->postsize); - if(!http->postsize) - result = Client_reader_set_null(data); - else { - /* Read from mime structure. We could do a special client reader - * for this, but replacing the callback seems to work fine. */ - data->state.fread_func = (curl_read_callback) Curl_mime_read; - data->state.in = (void *) data->state.mimepost; - result = Client_reader_set_fread(data, data->state.infilesize); - } - break; -#endif - case HTTPREQ_POST: - /* this is the simple POST, using x-www-form-urlencoded style */ - - if(data->req.authneg) - http->postsize = 0; - else - /* the size of the post body */ - http->postsize = data->state.infilesize; - - /* We only set Content-Length and allow a custom Content-Length if - we don't upload data chunked, as RFC2616 forbids us to set both - kinds of headers (Transfer-Encoding: chunked and Content-Length) */ - if((http->postsize != -1) && !data->req.upload_chunky && - (data->req.authneg || - !Curl_checkheaders(data, STRCONST("Content-Length")))) { - /* we allow replacing this header if not during auth negotiation, - although it isn't very wise to actually set your own */ - result = Curl_dyn_addf(r, "Content-Length: %" CURL_FORMAT_CURL_OFF_T - "\r\n", http->postsize); - if(result) - goto out; - } - - if(!Curl_checkheaders(data, STRCONST("Content-Type"))) { - result = Curl_dyn_addn(r, STRCONST("Content-Type: application/" - "x-www-form-urlencoded\r\n")); - if(result) - goto out; + if(httpreq == HTTPREQ_POST) { + if(!Curl_checkheaders(data, STRCONST("Content-Type"))) { + result = Curl_dyn_addn(r, STRCONST("Content-Type: application/" + "x-www-form-urlencoded\r\n")); + if(result) + goto out; + } } - result = addexpect(data, r); if(result) goto out; - - result = Curl_dyn_addn(r, STRCONST("\r\n")); - if(result) - goto out; - - if(!http->postsize) { - Curl_pgrsSetUploadSize(data, 0); - result = Client_reader_set_null(data); - } - else if(data->set.postfields) { - Curl_pgrsSetUploadSize(data, http->postsize); - if(http->postsize > 0) - result = Client_reader_set_buf(data, data->set.postfields, - (size_t)http->postsize); - else - result = Client_reader_set_null(data); - } - else { /* we read the bytes from the callback */ - Curl_pgrsSetUploadSize(data, http->postsize); - result = Client_reader_set_fread(data, http->postsize); - } break; - default: - /* HTTP GET/HEAD download, has no body, needs no Content-Length */ - result = Curl_dyn_addn(r, STRCONST("\r\n")); - if(!result) - result = Client_reader_set_null(data); break; } + /* end of headers */ + result = Curl_dyn_addn(r, STRCONST("\r\n")); + Curl_pgrsSetUploadSize(data, req_clen); + out: if(!result) { /* setup variables for the upcoming transfer */ @@ -2427,7 +2420,7 @@ CURLcode Curl_http_range(struct Curl_easy *data, } else if((httpreq == HTTPREQ_POST || httpreq == HTTPREQ_PUT) && !Curl_checkheaders(data, STRCONST("Content-Range"))) { - + curl_off_t req_clen = Curl_creader_total_length(data); /* if a line like this was already allocated, free the previous one */ free(data->state.aptr.rangeline); @@ -2438,25 +2431,28 @@ CURLcode Curl_http_range(struct Curl_easy *data, data->state.aptr.rangeline = aprintf("Content-Range: bytes 0-%" CURL_FORMAT_CURL_OFF_T "/%" CURL_FORMAT_CURL_OFF_T "\r\n", - data->state.infilesize - 1, data->state.infilesize); + req_clen - 1, req_clen); } else if(data->state.resume_from) { /* This is because "resume" was selected */ - curl_off_t total_expected_size = - data->state.resume_from + data->state.infilesize; + /* TODO: not sure if we want to send this header during authentication + * negotiation, but test1084 checks for it. In which case we have a + * "null" client reader installed that gives an unexpected length. */ + curl_off_t total_len = data->req.authneg? + data->state.infilesize : + (data->state.resume_from + req_clen); data->state.aptr.rangeline = aprintf("Content-Range: bytes %s%" CURL_FORMAT_CURL_OFF_T "/%" CURL_FORMAT_CURL_OFF_T "\r\n", - data->state.range, total_expected_size-1, - total_expected_size); + data->state.range, total_len-1, total_len); } else { /* Range was selected and then we just pass the incoming range and append total size */ data->state.aptr.rangeline = aprintf("Content-Range: bytes %s/%" CURL_FORMAT_CURL_OFF_T "\r\n", - data->state.range, data->state.infilesize); + data->state.range, req_clen); } if(!data->state.aptr.rangeline) return CURLE_OUT_OF_MEMORY; @@ -2465,87 +2461,6 @@ CURLcode Curl_http_range(struct Curl_easy *data, return CURLE_OK; } -CURLcode Curl_http_resume(struct Curl_easy *data, - struct connectdata *conn, - Curl_HttpReq httpreq) -{ - if((HTTPREQ_POST == httpreq || HTTPREQ_PUT == httpreq) && - data->state.resume_from) { - /********************************************************************** - * Resuming upload in HTTP means that we PUT or POST and that we have - * got a resume_from value set. The resume value has already created - * a Range: header that will be passed along. We need to "fast forward" - * the file the given number of bytes and decrease the assume upload - * file size before we continue this venture in the dark lands of HTTP. - * Resuming mime/form posting at an offset > 0 has no sense and is ignored. - *********************************************************************/ - - if(data->state.resume_from < 0) { - /* - * This is meant to get the size of the present remote-file by itself. - * We don't support this now. Bail out! - */ - data->state.resume_from = 0; - } - - if(data->state.resume_from && !data->state.followlocation) { - /* only act on the first request */ - - /* Now, let's read off the proper amount of bytes from the - input. */ - int seekerr = CURL_SEEKFUNC_CANTSEEK; - if(conn->seek_func) { - Curl_set_in_callback(data, true); - seekerr = conn->seek_func(conn->seek_client, data->state.resume_from, - SEEK_SET); - Curl_set_in_callback(data, false); - } - - if(seekerr != CURL_SEEKFUNC_OK) { - curl_off_t passed = 0; - - if(seekerr != CURL_SEEKFUNC_CANTSEEK) { - failf(data, "Could not seek stream"); - return CURLE_READ_ERROR; - } - /* when seekerr == CURL_SEEKFUNC_CANTSEEK (can't seek to offset) */ - do { - char scratch[4*1024]; - size_t readthisamountnow = - (data->state.resume_from - passed > (curl_off_t)sizeof(scratch)) ? - sizeof(scratch) : - curlx_sotouz(data->state.resume_from - passed); - - size_t actuallyread = - data->state.fread_func(scratch, 1, readthisamountnow, - data->state.in); - - passed += actuallyread; - if((actuallyread == 0) || (actuallyread > readthisamountnow)) { - /* this checks for greater-than only to make sure that the - CURL_READFUNC_ABORT return code still aborts */ - failf(data, "Could only read %" CURL_FORMAT_CURL_OFF_T - " bytes from the input", passed); - return CURLE_READ_ERROR; - } - } while(passed < data->state.resume_from); - } - - /* now, decrease the size of the read */ - if(data->state.infilesize>0) { - data->state.infilesize -= data->state.resume_from; - - if(data->state.infilesize <= 0) { - failf(data, "File already completely uploaded"); - return CURLE_PARTIAL_FILE; - } - } - /* we've passed, proceed as normal */ - } - } - return CURLE_OK; -} - CURLcode Curl_http_firstwrite(struct Curl_easy *data, struct connectdata *conn, bool *done) @@ -2754,17 +2669,13 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) goto fail; #endif - result = Curl_http_body(data, conn, httpreq, &te); + result = Curl_http_req_set_reader(data, httpreq, &te); if(result) goto fail; p_accept = Curl_checkheaders(data, STRCONST("Accept"))?NULL:"Accept: */*\r\n"; - result = Curl_http_resume(data, conn, httpreq); - if(result) - goto fail; - result = Curl_http_range(data, httpreq); if(result) goto fail; @@ -2882,14 +2793,8 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) result = Curl_add_custom_headers(data, FALSE, &req); if(!result) { - if((httpreq == HTTPREQ_GET) || - (httpreq == HTTPREQ_HEAD)) - Curl_pgrsSetUploadSize(data, 0); /* nothing */ - /* req_send takes ownership of the 'req' memory on success */ result = Curl_http_req_complete(data, &req, httpreq); - if(!result && data->req.upload_chunky) - result = Curl_httpchunk_add_reader(data); if(!result) result = Curl_req_send(data, &req); } @@ -3736,7 +3641,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, if(k->httpcode >= 300) { if((!data->req.authneg) && !conn->bits.close && - !data->state.rewindbeforesend) { + !Curl_creader_will_rewind(data)) { /* * General treatment of errors when about to send data. Including : * "417 Expectation Failed", while waiting for 100-continue. @@ -3805,7 +3710,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, } } - if(data->state.rewindbeforesend && !Curl_req_done_sending(data)) { + if(Curl_creader_will_rewind(data) && !Curl_req_done_sending(data)) { /* We rewind before next send, continue sending now */ infof(data, "Keep sending data to get tossed away"); k->keepon |= KEEP_SEND; diff --git a/lib/http.h b/lib/http.h index fc058477d5f..c77d9c6ba5e 100644 --- a/lib/http.h +++ b/lib/http.h @@ -105,9 +105,9 @@ CURLcode Curl_http_statusline(struct Curl_easy *data, CURLcode Curl_http_header(struct Curl_easy *data, struct connectdata *conn, char *headp); CURLcode Curl_transferencode(struct Curl_easy *data); -CURLcode Curl_http_body(struct Curl_easy *data, struct connectdata *conn, - Curl_HttpReq httpreq, - const char **teep); +CURLcode Curl_http_req_set_reader(struct Curl_easy *data, + Curl_HttpReq httpreq, + const char **tep); CURLcode Curl_http_req_complete(struct Curl_easy *data, struct dynbuf *r, Curl_HttpReq httpreq); bool Curl_use_http_1_1plus(const struct Curl_easy *data, @@ -119,9 +119,6 @@ CURLcode Curl_http_cookies(struct Curl_easy *data, #else #define Curl_http_cookies(a,b,c) CURLE_OK #endif -CURLcode Curl_http_resume(struct Curl_easy *data, - struct connectdata *conn, - Curl_HttpReq httpreq); CURLcode Curl_http_range(struct Curl_easy *data, Curl_HttpReq httpreq); CURLcode Curl_http_firstwrite(struct Curl_easy *data, @@ -188,11 +185,11 @@ CURLcode Curl_http_auth_act(struct Curl_easy *data); * HTTP unique setup ***************************************************************************/ struct HTTP { - curl_off_t postsize; /* off_t to handle large file sizes */ - #ifndef CURL_DISABLE_HTTP void *h2_ctx; /* HTTP/2 implementation context */ void *h3_ctx; /* HTTP/3 implementation context */ +#else + char unused; #endif }; diff --git a/lib/http_chunks.c b/lib/http_chunks.c index 3236c0e4730..dbcc527630e 100644 --- a/lib/http_chunks.c +++ b/lib/http_chunks.c @@ -624,6 +624,15 @@ static CURLcode cr_chunked_read(struct Curl_easy *data, return CURLE_OK; } +static curl_off_t cr_chunked_total_length(struct Curl_easy *data, + struct Curl_creader *reader) +{ + /* this reader changes length depending on input */ + (void)data; + (void)reader; + return -1; +} + /* HTTP chunked Transfer-Encoding encoder */ const struct Curl_crtype Curl_httpchunk_encoder = { "chunked", @@ -631,6 +640,9 @@ const struct Curl_crtype Curl_httpchunk_encoder = { cr_chunked_read, cr_chunked_close, Curl_creader_def_needs_rewind, + cr_chunked_total_length, + Curl_creader_def_resume_from, + Curl_creader_def_rewind, sizeof(struct chunked_reader) }; diff --git a/lib/multi.c b/lib/multi.c index 3770ac607b5..0cf4723405f 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -1816,93 +1816,6 @@ static CURLcode protocol_connect(struct Curl_easy *data, return result; /* pass back status */ } -/* - * readrewind() rewinds the read stream. This is typically used for HTTP - * POST/PUT with multi-pass authentication when a sending was denied and a - * resend is necessary. - */ -static CURLcode readrewind(struct Curl_easy *data) -{ -#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) - curl_mimepart *mimepart = &data->set.mimepost; -#endif - DEBUGASSERT(data->conn); - - data->state.rewindbeforesend = FALSE; /* we rewind now */ - - /* explicitly switch off sending data on this connection now since we are - about to restart a new transfer and thus we want to avoid inadvertently - sending more data on the existing connection until the next transfer - starts */ - data->req.keepon &= ~KEEP_SEND; - - /* We have sent away data. If not using CURLOPT_POSTFIELDS or - CURLOPT_HTTPPOST, call app to rewind - */ -#if !defined(CURL_DISABLE_HTTP) && !defined(CURL_DISABLE_MIME) - if(data->conn->handler->protocol & PROTO_FAMILY_HTTP) { - if(data->state.mimepost) - mimepart = data->state.mimepost; - } -#endif - if(data->set.postfields || - (data->state.httpreq == HTTPREQ_GET) || - (data->state.httpreq == HTTPREQ_HEAD)) - ; /* no need to rewind */ -#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) - else if(data->state.httpreq == HTTPREQ_POST_MIME || - data->state.httpreq == HTTPREQ_POST_FORM) { - CURLcode result = Curl_mime_rewind(mimepart); - if(result) { - failf(data, "Cannot rewind mime/post data"); - return result; - } - } -#endif - else { - if(data->set.seek_func) { - int err; - - Curl_set_in_callback(data, true); - err = (data->set.seek_func)(data->set.seek_client, 0, SEEK_SET); - Curl_set_in_callback(data, false); - if(err) { - failf(data, "seek callback returned error %d", (int)err); - return CURLE_SEND_FAIL_REWIND; - } - } - else if(data->set.ioctl_func) { - curlioerr err; - - Curl_set_in_callback(data, true); - err = (data->set.ioctl_func)(data, CURLIOCMD_RESTARTREAD, - data->set.ioctl_client); - Curl_set_in_callback(data, false); - infof(data, "the ioctl callback returned %d", (int)err); - - if(err) { - failf(data, "ioctl callback returned error %d", (int)err); - return CURLE_SEND_FAIL_REWIND; - } - } - else { - /* If no CURLOPT_READFUNCTION is used, we know that we operate on a - given FILE * stream and we can actually attempt to rewind that - ourselves with fseek() */ - if(data->state.fread_func == (curl_read_callback)fread) { - if(-1 != fseek(data->state.in, 0, SEEK_SET)) - /* successful rewind */ - return CURLE_OK; - } - - /* no callback set or failure above, makes us fail at once */ - failf(data, "necessary data rewind wasn't possible"); - return CURLE_SEND_FAIL_REWIND; - } - } - return CURLE_OK; -} - /* * Curl_preconnect() is called immediately before a connect starts. When a * redirect is followed, this is then called multiple times during a single @@ -2169,9 +2082,6 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, break; case MSTATE_PROTOCONNECT: - if(data->state.rewindbeforesend) - result = readrewind(data); - if(!result && data->conn->bits.reuse) { /* ftp seems to hang when protoconnect on reused connection * since we handle PROTOCONNECT in general inside the filers, it diff --git a/lib/request.c b/lib/request.c index dfd96a6c491..d009eddb1c0 100644 --- a/lib/request.c +++ b/lib/request.c @@ -49,8 +49,13 @@ CURLcode Curl_req_init(struct SingleRequest *req) CURLcode Curl_req_start(struct SingleRequest *req, struct Curl_easy *data) { + CURLcode result; + req->start = Curl_now(); - Curl_client_reset(data); + result = Curl_client_start(data); + if(result) + return result; + if(!req->sendbuf_init) { Curl_bufq_init2(&req->sendbuf, data->set.upload_buffer_size, 1, BUFQ_OPT_SOFT_LIMIT); @@ -82,14 +87,15 @@ CURLcode Curl_req_done(struct SingleRequest *req, void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data) { - struct bufq savebuf; - bool save_init; + struct curltime t0 = {0, 0}; /* This is a bit ugly. `req->p` is a union and we assume we can * free this safely without leaks. */ Curl_safefree(req->p.http); Curl_safefree(req->newurl); Curl_client_reset(data); + if(req->sendbuf_init) + Curl_bufq_reset(&req->sendbuf); #ifndef CURL_DISABLE_DOH if(req->doh) { @@ -97,17 +103,45 @@ void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data) Curl_close(&req->doh->probe[1].easy); } #endif - - savebuf = req->sendbuf; - save_init = req->sendbuf_init; - - memset(req, 0, sizeof(*req)); - data->req.size = data->req.maxdownload = -1; - data->req.no_body = data->set.opt_no_body; - if(save_init) { - req->sendbuf = savebuf; - req->sendbuf_init = save_init; - } + /* Can no longer memset() this struct as we need to keep some state */ + req->size = -1; + req->maxdownload = -1; + req->bytecount = 0; + req->writebytecount = 0; + req->start = t0; + req->headerbytecount = 0; + req->allheadercount = 0; + req->deductheadercount = 0; + req->headerline = 0; + req->offset = 0; + req->httpcode = 0; + req->keepon = 0; + req->start100 = t0; + req->exp100 = EXP100_SEND_DATA; + req->upgr101 = UPGR101_INIT; + req->timeofdoc = 0; + req->bodywrites = 0; + req->location = NULL; + req->newurl = NULL; +#ifndef CURL_DISABLE_COOKIES + req->setcookies = 0; +#endif + req->header = FALSE; + req->content_range = FALSE; + req->download_done = FALSE; + req->eos_written = FALSE; + req->eos_read = FALSE; + req->upload_done = FALSE; + req->upload_aborted = FALSE; + req->ignorebody = FALSE; + req->http_bodyless = FALSE; + req->chunk = FALSE; + req->ignore_cl = FALSE; + req->upload_chunky = FALSE; + req->getheader = FALSE; + req->forbidchunk = FALSE; + req->no_body = data->set.opt_no_body; + req->authneg = FALSE; } void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data) @@ -118,7 +152,7 @@ void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data) Curl_safefree(req->newurl); if(req->sendbuf_init) Curl_bufq_free(&req->sendbuf); - Curl_client_reset(data); + Curl_client_cleanup(data); #ifndef CURL_DISABLE_DOH if(req->doh) { diff --git a/lib/request.h b/lib/request.h index 91973d5dbc7..fdfdb0bee23 100644 --- a/lib/request.h +++ b/lib/request.h @@ -119,8 +119,6 @@ struct SingleRequest { #ifndef CURL_DISABLE_DOH struct dohdata *doh; /* DoH specific data for this request */ #endif - char fread_eof[2]; /* the body read callback (index 0) returned EOF or - the trailer read callback (index 1) returned EOF */ #ifndef CURL_DISABLE_COOKIES unsigned char setcookies; #endif @@ -129,6 +127,7 @@ struct SingleRequest { BIT(download_done); /* set to TRUE when download is complete */ BIT(eos_written); /* iff EOS has been written to client */ BIT(eos_read); /* iff EOS has been read from the client */ + BIT(rewind_read); /* iff reader needs rewind at next start */ BIT(upload_done); /* set to TRUE when all request data has been sent */ BIT(upload_aborted); /* set to TRUE when upload was aborted. Will also * show `upload_done` as TRUE. */ diff --git a/lib/rtsp.c b/lib/rtsp.c index 0d8009ad424..7c3dd31a6e8 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -225,8 +225,6 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) Curl_RtspReq rtspreq = data->set.rtspreq; struct RTSP *rtsp = data->req.p.rtsp; struct dynbuf req_buffer; - curl_off_t postsize = 0; /* for ANNOUNCE and SET_PARAMETER */ - curl_off_t putsize = 0; /* for ANNOUNCE and SET_PARAMETER */ const char *p_request = NULL; const char *p_session_id = NULL; @@ -499,38 +497,41 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) if(rtspreq == RTSPREQ_ANNOUNCE || rtspreq == RTSPREQ_SET_PARAMETER || rtspreq == RTSPREQ_GET_PARAMETER) { + curl_off_t req_clen; /* request content length */ if(data->state.upload) { - putsize = data->state.infilesize; + req_clen = data->state.infilesize; data->state.httpreq = HTTPREQ_PUT; - result = Client_reader_set_fread(data, putsize); + result = Curl_creader_set_fread(data, req_clen); if(result) goto out; } else { - postsize = (data->state.infilesize != -1)? - data->state.infilesize: - (data->set.postfields? (curl_off_t)strlen(data->set.postfields):0); - data->state.httpreq = HTTPREQ_POST; - if(postsize > 0 && data->set.postfields) - result = Client_reader_set_buf(data, data->set.postfields, - (size_t)postsize); - else if(!postsize) - result = Client_reader_set_null(data); - else - result = Client_reader_set_fread(data, postsize); + if(data->set.postfields) { + size_t plen = strlen(data->set.postfields); + req_clen = (curl_off_t)plen; + result = Curl_creader_set_buf(data, data->set.postfields, plen); + } + else if(data->state.infilesize >= 0) { + req_clen = data->state.infilesize; + result = Curl_creader_set_fread(data, req_clen); + } + else { + req_clen = 0; + result = Curl_creader_set_null(data); + } if(result) goto out; } - if(putsize > 0 || postsize > 0) { + if(req_clen > 0) { /* As stated in the http comments, it is probably not wise to * actually set a custom Content-Length in the headers */ if(!Curl_checkheaders(data, STRCONST("Content-Length"))) { result = Curl_dyn_addf(&req_buffer, "Content-Length: %" CURL_FORMAT_CURL_OFF_T"\r\n", - (data->state.upload ? putsize : postsize)); + req_clen); if(result) goto out; } @@ -565,7 +566,7 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) } } else { - result = Client_reader_set_null(data); + result = Curl_creader_set_null(data); if(result) goto out; } diff --git a/lib/sendf.c b/lib/sendf.c index 1b092f06b34..f7e62dc3631 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -51,6 +51,7 @@ #include "strdup.h" #include "http2.h" #include "progress.h" +#include "warnless.h" #include "ws.h" /* The last 3 #include files should be in this order */ @@ -112,9 +113,9 @@ static void cl_reset_reader(struct Curl_easy *data) } } -void Curl_client_reset(struct Curl_easy *data) +void Curl_client_cleanup(struct Curl_easy *data) { - DEBUGF(infof(data, "Curl_client_reset()")); + DEBUGF(infof(data, "Curl_client_cleanup()")); cl_reset_reader(data); cl_reset_writer(data); @@ -122,6 +123,54 @@ void Curl_client_reset(struct Curl_easy *data) data->req.headerline = 0; } +void Curl_client_reset(struct Curl_easy *data) +{ + if(data->req.rewind_read) { + /* already requested */ + DEBUGF(infof(data, "Curl_client_reset(), will rewind_read")); + } + else { + DEBUGF(infof(data, "Curl_client_reset(), clear readers")); + cl_reset_reader(data); + } + cl_reset_writer(data); + + data->req.bytecount = 0; + data->req.headerline = 0; +} + +CURLcode Curl_client_start(struct Curl_easy *data) +{ + if(data->req.rewind_read) { + struct Curl_creader *r = data->req.reader_stack; + CURLcode result = CURLE_OK; + + DEBUGF(infof(data, "client start, rewind readers")); + while(r) { + result = r->crt->rewind(data, r); + if(result) { + failf(data, "rewind of client reader '%s' failed: %d", + r->crt->name, result); + return result; + } + r = r->next; + } + data->req.rewind_read = FALSE; + cl_reset_reader(data); + } + return CURLE_OK; +} + +bool Curl_creader_will_rewind(struct Curl_easy *data) +{ + return data->req.rewind_read; +} + +void Curl_creader_set_rewind(struct Curl_easy *data, bool enable) +{ + data->req.rewind_read = !!enable; +} + /* Write data using an unencoding writer stack. "nbytes" is not allowed to be 0. */ CURLcode Curl_cwriter_write(struct Curl_easy *data, @@ -475,8 +524,35 @@ bool Curl_creader_def_needs_rewind(struct Curl_easy *data, return FALSE; } +curl_off_t Curl_creader_def_total_length(struct Curl_easy *data, + struct Curl_creader *reader) +{ + return reader->next? + reader->next->crt->total_length(data, reader->next) : -1; +} + +CURLcode Curl_creader_def_resume_from(struct Curl_easy *data, + struct Curl_creader *reader, + curl_off_t offset) +{ + (void)data; + (void)reader; + (void)offset; + return CURLE_READ_ERROR; +} + +CURLcode Curl_creader_def_rewind(struct Curl_easy *data, + struct Curl_creader *reader) +{ + (void)data; + (void)reader; + return CURLE_OK; +} + struct cr_in_ctx { struct Curl_creader super; + curl_read_callback read_cb; + void *cb_user_data; curl_off_t total_len; curl_off_t read_len; CURLcode error_result; @@ -489,6 +565,8 @@ static CURLcode cr_in_init(struct Curl_easy *data, struct Curl_creader *reader) { struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; (void)data; + ctx->read_cb = data->state.fread_func; + ctx->cb_user_data = data->state.in; ctx->total_len = -1; ctx->read_len = 0; return CURLE_OK; @@ -523,9 +601,9 @@ static CURLcode cr_in_read(struct Curl_easy *data, blen = (size_t)remain; } nread = 0; - if(data->state.fread_func && blen) { + if(ctx->read_cb && blen) { Curl_set_in_callback(data, true); - nread = data->state.fread_func(buf, 1, blen, data->state.in); + nread = ctx->read_cb(buf, 1, blen, ctx->cb_user_data); Curl_set_in_callback(data, false); ctx->has_used_cb = TRUE; } @@ -596,12 +674,167 @@ static bool cr_in_needs_rewind(struct Curl_easy *data, return ctx->has_used_cb; } +static curl_off_t cr_in_total_length(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + (void)data; + return ctx->total_len; +} + +static CURLcode cr_in_resume_from(struct Curl_easy *data, + struct Curl_creader *reader, + curl_off_t offset) +{ + struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + int seekerr = CURL_SEEKFUNC_CANTSEEK; + + DEBUGASSERT(data->conn); + /* already started reading? */ + if(ctx->read_len) + return CURLE_READ_ERROR; + + if(data->conn->seek_func) { + Curl_set_in_callback(data, true); + seekerr = data->conn->seek_func(data->conn->seek_client, offset, SEEK_SET); + Curl_set_in_callback(data, false); + } + + if(seekerr != CURL_SEEKFUNC_OK) { + curl_off_t passed = 0; + + if(seekerr != CURL_SEEKFUNC_CANTSEEK) { + failf(data, "Could not seek stream"); + return CURLE_READ_ERROR; + } + /* when seekerr == CURL_SEEKFUNC_CANTSEEK (can't seek to offset) */ + do { + char scratch[4*1024]; + size_t readthisamountnow = + (offset - passed > (curl_off_t)sizeof(scratch)) ? + sizeof(scratch) : + curlx_sotouz(offset - passed); + size_t actuallyread; + + Curl_set_in_callback(data, true); + actuallyread = ctx->read_cb(scratch, 1, readthisamountnow, + ctx->cb_user_data); + Curl_set_in_callback(data, false); + + passed += actuallyread; + if((actuallyread == 0) || (actuallyread > readthisamountnow)) { + /* this checks for greater-than only to make sure that the + CURL_READFUNC_ABORT return code still aborts */ + failf(data, "Could only read %" CURL_FORMAT_CURL_OFF_T + " bytes from the input", passed); + return CURLE_READ_ERROR; + } + } while(passed < offset); + } + + /* now, decrease the size of the read */ + if(ctx->total_len > 0) { + ctx->total_len -= offset; + + if(ctx->total_len <= 0) { + failf(data, "File already completely uploaded"); + return CURLE_PARTIAL_FILE; + } + } + /* we've passed, proceed as normal */ + return CURLE_OK; +} + +static CURLcode cr_in_rewind(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + /* TODO: I wonder if we should rather give mime its own client + * reader type. This is messy. */ +#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) + curl_mimepart *mimepart = &data->set.mimepost; +#endif + + /* If we never invoked the callback, there is noting to rewind */ + if(!ctx->has_used_cb) + return CURLE_OK; + + /* We have sent away data. If not using CURLOPT_POSTFIELDS or + CURLOPT_HTTPPOST, call app to rewind + */ +#if !defined(CURL_DISABLE_HTTP) && !defined(CURL_DISABLE_MIME) + if(data->conn->handler->protocol & PROTO_FAMILY_HTTP) { + if(data->state.mimepost) + mimepart = data->state.mimepost; + } +#endif +#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) + if(ctx->read_cb == (curl_read_callback)Curl_mime_read) { + CURLcode result = Curl_mime_rewind(mimepart); + DEBUGF(infof(data, "cr_in, rewind mime/post data -> %d", result)); + if(result) { + failf(data, "Cannot rewind mime/post data"); + } + return result; + } +#endif + + /* With mime out of the way, handle "normal" fread callbacks */ + if(data->set.seek_func) { + int err; + + Curl_set_in_callback(data, true); + err = (data->set.seek_func)(data->set.seek_client, 0, SEEK_SET); + Curl_set_in_callback(data, false); + DEBUGF(infof(data, "cr_in, rewind via set.seek_func -> %d", err)); + if(err) { + failf(data, "seek callback returned error %d", (int)err); + return CURLE_SEND_FAIL_REWIND; + } + } + else if(data->set.ioctl_func) { + curlioerr err; + + Curl_set_in_callback(data, true); + err = (data->set.ioctl_func)(data, CURLIOCMD_RESTARTREAD, + data->set.ioctl_client); + Curl_set_in_callback(data, false); + DEBUGF(infof(data, "cr_in, rewind via set.ioctl_func -> %d", (int)err)); + if(err) { + failf(data, "ioctl callback returned error %d", (int)err); + return CURLE_SEND_FAIL_REWIND; + } + } + else { + /* If no CURLOPT_READFUNCTION is used, we know that we operate on a + given FILE * stream and we can actually attempt to rewind that + ourselves with fseek() */ + if(data->state.fread_func == (curl_read_callback)fread) { + int err = fseek(data->state.in, 0, SEEK_SET); + DEBUGF(infof(data, "cr_in, rewind via fseek -> %d(%d)", + (int)err, (int)errno)); + if(-1 != err) + /* successful rewind */ + return CURLE_OK; + } + + /* no callback set or failure above, makes us fail at once */ + failf(data, "necessary data rewind wasn't possible"); + return CURLE_SEND_FAIL_REWIND; + } + return CURLE_OK; +} + + static const struct Curl_crtype cr_in = { "cr-in", cr_in_init, cr_in_read, Curl_creader_def_close, cr_in_needs_rewind, + cr_in_total_length, + cr_in_resume_from, + cr_in_rewind, sizeof(struct cr_in_ctx) }; @@ -730,12 +963,24 @@ static CURLcode cr_lc_read(struct Curl_easy *data, return result; } +static curl_off_t cr_lc_total_length(struct Curl_easy *data, + struct Curl_creader *reader) +{ + /* this reader changes length depending on input */ + (void)data; + (void)reader; + return -1; +} + static const struct Curl_crtype cr_lc = { "cr-lineconv", cr_lc_init, cr_lc_read, cr_lc_close, Curl_creader_def_needs_rewind, + cr_lc_total_length, + Curl_creader_def_resume_from, + Curl_creader_def_rewind, sizeof(struct cr_lc_ctx) }; @@ -756,7 +1001,8 @@ static CURLcode cr_lc_add(struct Curl_easy *data) static CURLcode do_init_reader_stack(struct Curl_easy *data, const struct Curl_crtype *crt, - struct Curl_creader **preader) + struct Curl_creader **preader, + curl_off_t clen) { CURLcode result; @@ -766,11 +1012,13 @@ static CURLcode do_init_reader_stack(struct Curl_easy *data, return result; data->req.reader_stack = *preader; - if(data->set.crlf + /* if we do not have 0 length init, and crlf conversion is wanted, + * add the reader for it */ + if(clen && (data->set.crlf #ifdef CURL_DO_LINEEND_CONV || data->state.prefer_ascii #endif - ) { + )) { result = cr_lc_add(data); if(result) return result; @@ -779,13 +1027,13 @@ static CURLcode do_init_reader_stack(struct Curl_easy *data, return result; } -CURLcode Client_reader_set_fread(struct Curl_easy *data, curl_off_t len) +CURLcode Curl_creader_set_fread(struct Curl_easy *data, curl_off_t len) { CURLcode result; struct Curl_creader *r; cl_reset_reader(data); - result = do_init_reader_stack(data, &cr_in, &r); + result = do_init_reader_stack(data, &cr_in, &r, len); if(!result && r) { struct cr_in_ctx *ctx = (struct cr_in_ctx *)r; DEBUGASSERT(r->crt == &cr_in); @@ -801,7 +1049,7 @@ CURLcode Curl_creader_add(struct Curl_easy *data, struct Curl_creader **anchor = &data->req.reader_stack; if(!*anchor) { - result = Client_reader_set_fread(data, data->state.infilesize); + result = Curl_creader_set_fread(data, data->state.infilesize); if(result) return result; } @@ -826,7 +1074,7 @@ CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen, DEBUGASSERT(eos); if(!data->req.reader_stack) { - result = Client_reader_set_fread(data, data->state.infilesize); + result = Curl_creader_set_fread(data, data->state.infilesize); if(result) return result; DEBUGASSERT(data->req.reader_stack); @@ -837,7 +1085,7 @@ CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen, return result; } -bool Curl_client_read_needs_rewind(struct Curl_easy *data) +bool Curl_creader_needs_rewind(struct Curl_easy *data) { struct Curl_creader *reader = data->req.reader_stack; while(reader) { @@ -862,21 +1110,33 @@ static CURLcode cr_null_read(struct Curl_easy *data, return CURLE_OK; } +static curl_off_t cr_null_total_length(struct Curl_easy *data, + struct Curl_creader *reader) +{ + /* this reader changes length depending on input */ + (void)data; + (void)reader; + return 0; +} + static const struct Curl_crtype cr_null = { "cr-null", Curl_creader_def_init, cr_null_read, Curl_creader_def_close, Curl_creader_def_needs_rewind, + cr_null_total_length, + Curl_creader_def_resume_from, + Curl_creader_def_rewind, sizeof(struct Curl_creader) }; -CURLcode Client_reader_set_null(struct Curl_easy *data) +CURLcode Curl_creader_set_null(struct Curl_easy *data) { struct Curl_creader *r; cl_reset_reader(data); - return do_init_reader_stack(data, &cr_null, &r); + return do_init_reader_stack(data, &cr_null, &r, 0); } struct cr_buf_ctx { @@ -918,23 +1178,57 @@ static bool cr_buf_needs_rewind(struct Curl_easy *data, return ctx->index > 0; } +static curl_off_t cr_buf_total_length(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)reader; + (void)data; + return (curl_off_t)ctx->blen; +} + +static CURLcode cr_buf_resume_from(struct Curl_easy *data, + struct Curl_creader *reader, + curl_off_t offset) +{ + struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)reader; + size_t boffset; + + (void)data; + DEBUGASSERT(data->conn); + /* already started reading? */ + if(ctx->index) + return CURLE_READ_ERROR; + if(offset <= 0) + return CURLE_OK; + boffset = (size_t)offset; + if(boffset > ctx->blen) + return CURLE_READ_ERROR; + + ctx->buf += boffset; + ctx->blen -= boffset; + return CURLE_OK; +} + static const struct Curl_crtype cr_buf = { "cr-buf", Curl_creader_def_init, cr_buf_read, Curl_creader_def_close, cr_buf_needs_rewind, + cr_buf_total_length, + cr_buf_resume_from, + Curl_creader_def_rewind, sizeof(struct cr_buf_ctx) }; -CURLcode Client_reader_set_buf(struct Curl_easy *data, +CURLcode Curl_creader_set_buf(struct Curl_easy *data, const char *buf, size_t blen) { CURLcode result; struct Curl_creader *r; cl_reset_reader(data); - result = do_init_reader_stack(data, &cr_buf, &r); + result = do_init_reader_stack(data, &cr_buf, &r, blen); if(!result && r) { struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)r; DEBUGASSERT(r->crt == &cr_buf); @@ -944,3 +1238,25 @@ CURLcode Client_reader_set_buf(struct Curl_easy *data, } return result; } + +curl_off_t Curl_creader_total_length(struct Curl_easy *data) +{ + struct Curl_creader *r = data->req.reader_stack; + return r? r->crt->total_length(data, r) : -1; +} + +curl_off_t Curl_creader_client_length(struct Curl_easy *data) +{ + struct Curl_creader *r = data->req.reader_stack; + while(r && r->phase != CURL_CR_CLIENT) + r = r->next; + return r? r->crt->total_length(data, r) : -1; +} + +CURLcode Curl_creader_resume_from(struct Curl_easy *data, curl_off_t offset) +{ + struct Curl_creader *r = data->req.reader_stack; + while(r && r->phase != CURL_CR_CLIENT) + r = r->next; + return r? r->crt->resume_from(data, r, offset) : CURLE_READ_ERROR; +} diff --git a/lib/sendf.h b/lib/sendf.h index 7876dd99320..efb9628fc1b 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -61,8 +61,20 @@ CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *ptr, /** * Free all resources related to client writing. */ +void Curl_client_cleanup(struct Curl_easy *data); + +/** + * Reset readers and writer chains, keep rewind information + * when necessary. + */ void Curl_client_reset(struct Curl_easy *data); +/** + * A new request is starting, perform any ops like rewinding + * previous readers when needed. + */ +CURLcode Curl_client_start(struct Curl_easy *data); + /** * Client Writers - a chain passing transfer BODY data to the client. * Main application: HTTP and related protocols @@ -178,11 +190,16 @@ void Curl_cwriter_def_close(struct Curl_easy *data, /* Client Reader Type, provides the implementation */ struct Curl_crtype { const char *name; /* writer name. */ - CURLcode (*do_init)(struct Curl_easy *data, struct Curl_creader *writer); + CURLcode (*do_init)(struct Curl_easy *data, struct Curl_creader *reader); 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); size_t creader_size; /* sizeof() allocated struct Curl_creader */ }; @@ -212,6 +229,13 @@ void Curl_creader_def_close(struct Curl_easy *data, struct Curl_creader *reader); bool Curl_creader_def_needs_rewind(struct Curl_easy *data, struct Curl_creader *reader); +curl_off_t Curl_creader_def_total_length(struct Curl_easy *data, + struct Curl_creader *reader); +CURLcode Curl_creader_def_resume_from(struct Curl_easy *data, + struct Curl_creader *reader, + curl_off_t offset); +CURLcode Curl_creader_def_rewind(struct Curl_easy *data, + struct Curl_creader *reader); /** * Convenience method for calling `reader->do_read()` that @@ -260,22 +284,64 @@ CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen, * TRUE iff client reader needs rewing before it can be used for * a retry request. */ -bool Curl_client_read_needs_rewind(struct Curl_easy *data); +bool Curl_creader_needs_rewind(struct Curl_easy *data); + +/** + * TRUE iff client reader will rewind at next start + */ +bool Curl_creader_will_rewind(struct Curl_easy *data); + +/** + * En-/disable rewind of client reader at next start. + */ +void Curl_creader_set_rewind(struct Curl_easy *data, bool enable); + +/** + * Get the total length of bytes provided by the installed readers. + * This is independent of the amount already delivered and is calculated + * by all readers in the stack. If a reader like "chunked" or + * "crlf conversion" is installed, the returned length will be -1. + * @return -1 if length is indeterminate + */ +curl_off_t Curl_creader_total_length(struct Curl_easy *data); + +/** + * Get the total length of bytes provided by the reader at phase + * CURL_CR_CLIENT. This may not match the amount of bytes read + * for a request, depending if other, encoding readers are also installed. + * However it allows for rough estimation of the overall length. + * @return -1 if length is indeterminate + */ +curl_off_t Curl_creader_client_length(struct Curl_easy *data); + +/** + * Ask the installed reader at phase CURL_CR_CLIENT to start + * reading from the given offset. On success, this will reduce + * the `total_length()` by the amount. + * @param date the transfer to read client bytes for + * param offset the offset where to start reads from, negative + * values will be ignored. + * @return CURLE_OK if offset could be set + * CURLE_READ_ERROR if not supported by reader or seek/read failed + * of offset larger then total length + * CURLE_PARTIAL_FILE if offset led to 0 total length + */ +CURLcode Curl_creader_resume_from(struct Curl_easy *data, curl_off_t offset); /** * Set the client reader to provide 0 bytes, immediate EOS. */ -CURLcode Client_reader_set_null(struct Curl_easy *data); +CURLcode Curl_creader_set_null(struct Curl_easy *data); /** * Set the client reader the reads from fread callback. */ -CURLcode Client_reader_set_fread(struct Curl_easy *data, curl_off_t len); +CURLcode Curl_creader_set_fread(struct Curl_easy *data, curl_off_t len); /** * Set the client reader the reads from the supplied buf (NOT COPIED). */ -CURLcode Client_reader_set_buf(struct Curl_easy *data, - const char *buf, size_t blen); +CURLcode Curl_creader_set_buf(struct Curl_easy *data, + const char *buf, size_t blen); #endif /* HEADER_CURL_SENDF_H */ diff --git a/lib/smtp.c b/lib/smtp.c index a937fbf217c..43a85c97c17 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -748,7 +748,7 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) } /* Setup client reader for size and EOB conversion */ - result = Client_reader_set_fread(data, data->state.infilesize); + result = Curl_creader_set_fread(data, data->state.infilesize); if(result) goto out; /* Add the client reader doing STMP EOB escaping */ @@ -1909,12 +1909,24 @@ static CURLcode cr_eob_read(struct Curl_easy *data, return CURLE_OK; } +static curl_off_t cr_eob_total_length(struct Curl_easy *data, + struct Curl_creader *reader) +{ + /* this reader changes length depending on input */ + (void)data; + (void)reader; + return -1; +} + static const struct Curl_crtype cr_eob = { "cr-smtp-eob", cr_eob_init, cr_eob_read, cr_eob_close, Curl_creader_def_needs_rewind, + cr_eob_total_length, + Curl_creader_def_resume_from, + Curl_creader_def_rewind, sizeof(struct cr_eob_ctx) }; diff --git a/lib/transfer.c b/lib/transfer.c index e6153c6bea3..cd3bd37682d 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -982,6 +982,7 @@ CURLcode Curl_follow(struct Curl_easy *data, && !(data->set.keep_post & CURL_REDIR_POST_301)) { infof(data, "Switch from POST to GET"); data->state.httpreq = HTTPREQ_GET; + Curl_creader_set_rewind(data, FALSE); } break; case 302: /* Found */ @@ -1007,6 +1008,7 @@ CURLcode Curl_follow(struct Curl_easy *data, && !(data->set.keep_post & CURL_REDIR_POST_302)) { infof(data, "Switch from POST to GET"); data->state.httpreq = HTTPREQ_GET; + Curl_creader_set_rewind(data, FALSE); } break; @@ -1109,12 +1111,7 @@ CURLcode Curl_retry_request(struct Curl_easy *data, char **url) prevent i.e HTTP transfers to return error just because nothing has been transferred! */ - - - if(Curl_client_read_needs_rewind(data)) { - data->state.rewindbeforesend = TRUE; - infof(data, "state.rewindbeforesend = TRUE"); - } + Curl_creader_set_rewind(data, TRUE); } return CURLE_OK; } diff --git a/lib/urldata.h b/lib/urldata.h index 0871e1348d5..b9e57027580 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -1387,9 +1387,6 @@ struct UrlState { BIT(url_alloc); /* URL string is malloc()'ed */ BIT(referer_alloc); /* referer string is malloc()ed */ BIT(wildcard_resolve); /* Set to true if any resolve change is a wildcard */ - BIT(rewindbeforesend);/* TRUE when the sending couldn't be stopped even - though it will be discarded. We must call the data - rewind callback before trying to send again. */ BIT(upload); /* upload request */ BIT(internal); /* internal: true if this easy handle was created for internal use and the user does not have ownership of the diff --git a/scripts/singleuse.pl b/scripts/singleuse.pl index 5124697a300..3948d0a79a8 100755 --- a/scripts/singleuse.pl +++ b/scripts/singleuse.pl @@ -46,7 +46,8 @@ 'Curl_xfer_write_resp' => 'internal api', 'Curl_creader_def_init' => 'internal api', 'Curl_creader_def_close' => 'internal api', - ); + 'Curl_creader_def_total_length' => 'internal api', +); my %api = ( 'curl_easy_cleanup' => 'API', From a5dd9435ee835d133d11d3d4c26ab126319e6cdc Mon Sep 17 00:00:00 2001 From: Sebastian Neubauer Date: Tue, 5 Mar 2024 02:11:46 +0100 Subject: [PATCH 419/509] smpt: fix starttls In cases where the connection was fast, curl sometimes failed to open a connection. This fixes a regression of c2d973627bab12abc5486a3f3. The regression triggered in these steps: 1. Create an smtp connection 2. Use STARTTLS 3. Receive the response 4. We are inside the loop in `smtp_statemachine`, calling `smtp_state_starttls_resp` 5. In the good flow, we exit the loop, re-enter `smtp_statemachine` and run `smtp_perform_upgrade_tls` at the start of the function. In the bad flow, we stay in the while loop, calling `Curl_pp_readresp`, which reads part of the TLS handshake and things go wrong. The reason is that `Curl_pp_moredata` changed behavior and always returns `true`, so we stay in the loop in `smtp_statemachine`. With a slow connection `Curl_pp_readresp` cannot read new data and returns `CURL_AGAIN`, so we leave the loop and re-enter `smtp_statemachine`. With a fast connection, `Curl_pp_readresp` reads new data from the tcp connection, which is part of the TLS handshake. The fix is in `Curl_pp_moredata`, which needs to take the final line into account and return `false` if only the final line is stored. Closes #13048 --- lib/pingpong.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/pingpong.c b/lib/pingpong.c index 7f240be9500..81576c08c90 100644 --- a/lib/pingpong.c +++ b/lib/pingpong.c @@ -432,7 +432,7 @@ CURLcode Curl_pp_disconnect(struct pingpong *pp) bool Curl_pp_moredata(struct pingpong *pp) { - return (!pp->sendleft && Curl_dyn_len(&pp->recvbuf)); + return (!pp->sendleft && Curl_dyn_len(&pp->recvbuf) > pp->nfinal); } #endif From a54d0bdc653640d7272331a9fce1dcdd46fbf9cc Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 5 Mar 2024 10:52:04 +0000 Subject: [PATCH 420/509] KNOWN_BUGS: fix typo Reviewed-by: Daniel Stenberg Closes #13051 --- docs/KNOWN_BUGS | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 9244dc5e32f..a1cc620c159 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -61,7 +61,7 @@ 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 remebered dir is deleted + 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 @@ -382,7 +382,7 @@ problems may have been fixed or changed somewhat since this was written. 7. FTP -7.1 FTP upload fails if remebered dir is deleted +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 From df1fcb41e2a0816c1b024507cce03557d96dc473 Mon Sep 17 00:00:00 2001 From: Michael Kaufmann Date: Mon, 4 Mar 2024 18:15:08 +0100 Subject: [PATCH 421/509] http: better error message for HTTP/1.x response without status line If a response without a status line is received, and the connection is known to use HTTP/1.x (not HTTP/0.9), report the error "Invalid status line" instead of "Received HTTP/0.9 when not allowed". Closes #13045 --- lib/http.c | 8 +++++ tests/data/Makefile.inc | 1 + tests/data/test1479 | 67 +++++++++++++++++++++++++++++++++++++++++ tests/data/test1480 | 58 +++++++++++++++++++++++++++++++++++ 4 files changed, 134 insertions(+) create mode 100644 tests/data/test1479 create mode 100644 tests/data/test1480 diff --git a/lib/http.c b/lib/http.c index ec9e69f4f2f..e6375b92e10 100644 --- a/lib/http.c +++ b/lib/http.c @@ -3410,6 +3410,10 @@ static CURLcode http_rw_headers(struct Curl_easy *data, /* this is not the beginning of a protocol first header line */ k->header = FALSE; streamclose(conn, "bad HTTP: No end-of-message indicator"); + if(conn->httpversion >= 10) { + failf(data, "Invalid status line"); + return CURLE_WEIRD_SERVER_REPLY; + } if(!data->set.http09_allowed) { failf(data, "Received HTTP/0.9 when not allowed"); return CURLE_UNSUPPORTED_PROTOCOL; @@ -3443,6 +3447,10 @@ static CURLcode http_rw_headers(struct Curl_easy *data, if(st == STATUS_BAD) { streamclose(conn, "bad HTTP: No end-of-message indicator"); /* this is not the beginning of a protocol first header line */ + if(conn->httpversion >= 10) { + failf(data, "Invalid status line"); + return CURLE_WEIRD_SERVER_REPLY; + } if(!data->set.http09_allowed) { failf(data, "Received HTTP/0.9 when not allowed"); return CURLE_UNSUPPORTED_PROTOCOL; diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 2d2b87a8640..825b56815f8 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -188,6 +188,7 @@ test1447 test1448 test1449 test1450 test1451 test1452 test1453 test1454 \ test1455 test1456 test1457 test1458 test1459 test1460 test1461 test1462 \ test1463 test1464 test1465 test1466 test1467 test1468 test1469 test1470 \ test1471 test1472 test1473 test1474 test1475 test1476 test1477 test1478 \ +test1479 test1480 \ \ test1500 test1501 test1502 test1503 test1504 test1505 test1506 test1507 \ test1508 test1509 test1510 test1511 test1512 test1513 test1514 test1515 \ diff --git a/tests/data/test1479 b/tests/data/test1479 new file mode 100644 index 00000000000..9e22e77f4cc --- /dev/null +++ b/tests/data/test1479 @@ -0,0 +1,67 @@ + + + +HTTP +HTTP/0.9 + + + +# +# Server-side + + +HTTP/1.1 200 OK +Content-Length: 5 + +Data + + +Data +Data +Data + + + + + +# +# Client-side + + +http + + +HTTP/1.1 response followed by an HTTP/0.9 response over the same connection + + +http://%HOSTIP:%HTTPPORT/%TESTNUMBER http://%HOSTIP:%HTTPPORT/%TESTNUMBER0002 + + + +# +# Verify data after the test has been "shot" + + +GET /%TESTNUMBER HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +User-Agent: curl/%VERSION +Accept: */* + +GET /%TESTNUMBER0002 HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +User-Agent: curl/%VERSION +Accept: */* + + + +# Hyper curl returns unsupported protocol +# built-in curl returns weird_server_reply + +%if hyper +1 +%else +8 +%endif + + + diff --git a/tests/data/test1480 b/tests/data/test1480 new file mode 100644 index 00000000000..65e0d4a4082 --- /dev/null +++ b/tests/data/test1480 @@ -0,0 +1,58 @@ + + + +HTTP + + + +# +# Server-side + + +HTTP/1.1 100 Continue +Foo: Bar + +Data +Data +Data + + + + + +# +# Client-side + + +http + + +HTTP Continue response without final response + + +http://%HOSTIP:%HTTPPORT/%TESTNUMBER + + + +# +# Verify data after the test has been "shot" + + +GET /%TESTNUMBER HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +User-Agent: curl/%VERSION +Accept: */* + + + +# Hyper curl returns unsupported protocol +# built-in curl returns weird_server_reply + +%if hyper +1 +%else +8 +%endif + + + From c426277b591149e445ac5deb2663ab8b22245f26 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 5 Mar 2024 11:48:16 +0100 Subject: [PATCH 422/509] TIMER_STARTTRANSFER: set the same for everyone - set TIMER_STARTTRANSFER on seeing the first response bytes in the download client writer, not coming from a CONNECT - initialized the timer the same way for all protocols - remove explicit setting of TIMER_STARTTRANSFER in file.c and c-hyper.c Closes #13052 --- lib/c-hyper.c | 3 --- lib/file.c | 2 -- lib/sendf.c | 22 +++++++++++++--------- 3 files changed, 13 insertions(+), 14 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index c59f2bf337b..f11b126a571 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -155,9 +155,6 @@ static int hyper_each_header(void *userdata, return HYPER_ITER_BREAK; } - if(!data->req.bytecount) - Curl_pgrsTime(data, TIMER_STARTTRANSFER); - Curl_dyn_reset(&data->state.headerb); if(name_len) { if(Curl_dyn_addf(&data->state.headerb, "%.*s: %.*s\r\n", diff --git a/lib/file.c b/lib/file.c index 07d879dfd12..bee9e92ecaa 100644 --- a/lib/file.c +++ b/lib/file.c @@ -548,8 +548,6 @@ static CURLcode file_do(struct Curl_easy *data, bool *done) return CURLE_BAD_DOWNLOAD_RESUME; } - Curl_pgrsTime(data, TIMER_STARTTRANSFER); - result = Curl_multi_xfer_buf_borrow(data, &xfer_buf, &xfer_blen); if(result) goto out; diff --git a/lib/sendf.c b/lib/sendf.c index f7e62dc3631..22e2b8592ae 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -226,28 +226,32 @@ static size_t get_max_body_write_len(struct Curl_easy *data, curl_off_t limit) return SIZE_T_MAX; } +struct cw_download_ctx { + struct Curl_cwriter super; + BIT(started_response); +}; /* Download client writer in phase CURL_CW_PROTOCOL that * sees the "real" download body data. */ static CURLcode cw_download_write(struct Curl_easy *data, struct Curl_cwriter *writer, int type, const char *buf, size_t nbytes) { + struct cw_download_ctx *ctx = (struct cw_download_ctx *)writer; CURLcode result; size_t nwrite, excess_len = 0; + bool is_connect = !!(type & CLIENTWRITE_CONNECT); + + if(!is_connect && !ctx->started_response) { + Curl_pgrsTime(data, TIMER_STARTTRANSFER); + ctx->started_response = TRUE; + } if(!(type & CLIENTWRITE_BODY)) { - if((type & CLIENTWRITE_CONNECT) && data->set.suppress_connect_headers) + if(is_connect && data->set.suppress_connect_headers) return CURLE_OK; return Curl_cwriter_write(data, writer->next, type, buf, nbytes); } - if(!data->req.bytecount) { - Curl_pgrsTime(data, TIMER_STARTTRANSFER); - if(data->req.exp100 > EXP100_SEND_DATA) - /* set time stamp to compare with when waiting for the 100 */ - data->req.start100 = Curl_now(); - } - /* Here, we deal with REAL BODY bytes. All filtering and transfer * encodings have been applied and only the true content, e.g. BODY, * bytes are passed here. @@ -334,7 +338,7 @@ static const struct Curl_cwtype cw_download = { Curl_cwriter_def_init, cw_download_write, Curl_cwriter_def_close, - sizeof(struct Curl_cwriter) + sizeof(struct cw_download_ctx) }; /* RAW client writer in phase CURL_CW_RAW that From 8e741644a229c3791963b4f5cae1dcfccba842dd Mon Sep 17 00:00:00 2001 From: Tal Regev Date: Sun, 3 Mar 2024 21:57:03 +0200 Subject: [PATCH 423/509] cmake: add USE_OPENSSL_QUIC support Closes #13034 --- CMakeLists.txt | 17 +++++++++++++++-- docs/HTTP3.md | 9 +++++++++ lib/curl_config.h.cmake | 3 +++ 3 files changed, 27 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 2194a6598a2..0c5c039e7c6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -720,13 +720,26 @@ 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)) +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() @@ -1548,7 +1561,7 @@ if(NOT CURL_DISABLE_INSTALL) NOT CURL_DISABLE_HTTP AND NTLM_WB_ENABLED) _add_if("TLS-SRP" USE_TLS_SRP) _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 diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 90f1c31e3da..783ab101ffb 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -233,6 +233,15 @@ Build curl: % 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`. diff --git a/lib/curl_config.h.cmake b/lib/curl_config.h.cmake index 937b93edb6d..0f4db69820e 100644 --- a/lib/curl_config.h.cmake +++ b/lib/curl_config.h.cmake @@ -720,6 +720,9 @@ ${SIZEOF_TIME_T_CODE} /* to enable quiche */ #cmakedefine USE_QUICHE 1 +/* to enable openssl + nghttp3 */ +#cmakedefine USE_OPENSSL_QUIC 1 + /* Define to 1 if you have the quiche_conn_set_qlog_fd function. */ #cmakedefine HAVE_QUICHE_CONN_SET_QLOG_FD 1 From 4cea0982a0bdc5be9147bd6634872747f81225aa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Mar 2024 17:09:46 +0100 Subject: [PATCH 424/509] TODO: remove "build HTTP/3 with OpenSSL and nghttp3 using cmake" Follow-up to 8e741644a229c37 --- docs/TODO | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/TODO b/docs/TODO index 06257f53f7c..49242227cf1 100644 --- a/docs/TODO +++ b/docs/TODO @@ -183,7 +183,6 @@ 19.4 Package curl for Windows in a signed installer 19.5 make configure use --cache-file more and better 19.6 build curl with Windows Unicode support - 19.7 build HTTP/3 with OpenSSL and nghttp3 using cmake 20. Test suite 20.1 SSL tunnel @@ -1340,10 +1339,6 @@ See https://github.com/curl/curl/issues/7229 -19.7 build HTTP/3 with OpenSSL and nghttp3 using cmake - - https://github.com/curl/curl/issues/12988 - 20. Test suite 20.1 SSL tunnel From 6c632b216b4850253c15084fa3f1f71352931177 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Mar 2024 17:15:27 +0100 Subject: [PATCH 425/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 49 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 6212f5e57a0..cff167aaad4 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.7.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3105 + Contributors: 3108 This release includes the following changes: @@ -16,6 +16,7 @@ This release includes the following changes: This release includes the following bugfixes: + o _VARIABLES.md: improve the description [105] o ALTSVC.md: correct a typo [14] o asyn-thread: use wakeup_close to close the read descriptor [1] o badwords: use hostname, not host name [46] @@ -25,6 +26,7 @@ This release includes the following bugfixes: 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: fix function description in comment [47] o cmake: fix install for older CMake versions [53] @@ -39,7 +41,9 @@ This release includes the following bugfixes: o configure: Don't build shell completions when disabled [68] o configure: Don't make shell completions without perl [83] 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: when allocating variables, add the name into the struct [37] o curl_setup.h: add curl_uint64_t internal type @@ -63,11 +67,13 @@ This release includes the following bugfixes: 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 header.md: remove backslash, make nicer markdown [48] o HTTP/2: write response directly [12] 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: move headers collecting to writer [71] o http_chunks: fix the accounting of consumed bytes [22] o http_chunks: remove unused 'endptr' variable [58] @@ -75,6 +81,7 @@ This release includes the following bugfixes: o lib582: remove code causing warning that is never run [38] 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: remove curl_mimepart object when CURL_DISABLE_MIME [72] o libcurl-docs: cleanups @@ -92,17 +99,22 @@ This release includes the following bugfixes: 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 proxy1.0.md: fix example [15] + o pytest: adapt to API change [106] 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 smtp: fix STARTTLS [91] o strtoofft: fix the overflow check [74] 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 tool_cb_hdr: only parse etag + content-disposition for 2xx [9] o tool_operate: change precedence of server Retry-After time [44] o tool_operate: do not set CURLOPT_QUICK_EXIT in debug builds [3] @@ -129,17 +141,18 @@ advice from friends like these: 5533asdg on github, Andreas Kiefer, av223119 on github, Boris Verkhovskiy, Brett Buddin, Chris Webb, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, - Daniel Szmulewicz, Dirk Hünniger, Dmitry Tretyakov, edmcln on github, - Erik Schnetter, Evgeny Grin (Karlson2k), Fabian Vogt, Fabrice Fontaine, - Faraz Fallahi, Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, - Jiawen Geng, Joel Depooter, Jon Rumsey, Jordan Brown, Karthikdasari0423, - Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, - Lukáš Zaoral, Marcel Raad, Michael Forney, Michael Kaufmann, Michał Antoniak, - Patrick Monnerat, Paweł Witas, Peter Krefting, RainRat, Ramiro Garcia, - Ray Satiro, Richard Levitte, Ryan Carsten Schmidt, Scott Mutter, - Scott Talbert, Sergey Bronnikov, Stefan Eissing, Viktor Szakats, - vulnerabilityspotter on hackerone - (51 contributors) + Daniel Szmulewicz, dependabot[bot], Dirk Hünniger, Dmitry Tretyakov, + edmcln on github, Erik Schnetter, Evgeny Grin (Karlson2k), Fabian Vogt, + Fabrice Fontaine, Faraz Fallahi, Gisle Vanem, Harry Sintonen, + HsiehYuho on github, Jan Macku, Jiawen Geng, Joel Depooter, Jon Rumsey, + Jordan Brown, Karthikdasari0423, Konstantin Vlasov, kpcyrd, + Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, Lukáš Zaoral, Marcel Raad, + Michael Forney, Michael Kaufmann, Michał Antoniak, Patrick Monnerat, + Paweł Witas, Peter Krefting, RainRat, Ramiro Garcia, Ray Satiro, + Richard Levitte, Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, + Sebastian Neubauer, Sergey Bronnikov, Stefan Eissing, Tal Regev, + Viktor Szakats, vulnerabilityspotter on hackerone + (54 contributors) References to bug reports and discussions on issues: @@ -163,6 +176,7 @@ References to bug reports and discussions on issues: [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 @@ -223,12 +237,20 @@ References to bug reports and discussions on issues: [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 [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 [99] = https://curl.se/bug/?i=13004 [100] = https://curl.se/bug/?i=12998 @@ -236,3 +258,6 @@ References to bug reports and discussions on issues: [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 From 0ba47146f7ff3dedcf35f568be57d41d47c5bdfe Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 29 Feb 2024 10:12:39 +0100 Subject: [PATCH 426/509] mime: add client reader Add `mime` client reader. Encapsulates reading from mime parts, getting their length, rewinding and unpausing. - remove special mime handling from sendf.c and easy.c - add general "unpause" method to client readers - use new reader in http/imap/smtp - make some mime functions static that are now only used internally In addition: - remove flag 'forbidchunk' as no longer needed Closes #13039 --- lib/easy.c | 7 +- lib/http.c | 60 ++++++------ lib/http_chunks.c | 1 + lib/imap.c | 17 ++-- lib/mime.c | 226 +++++++++++++++++++++++++++++++++++++++++++++- lib/mime.h | 13 +-- lib/request.c | 1 - lib/request.h | 3 - lib/rtsp.c | 2 - lib/sendf.c | 124 ++++++++++++++----------- lib/sendf.h | 17 ++++ lib/smtp.c | 22 ++--- 12 files changed, 367 insertions(+), 126 deletions(-) diff --git a/lib/easy.c b/lib/easy.c index 6c932ad823c..dbc2e7f1791 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -1110,9 +1110,10 @@ CURLcode curl_easy_pause(struct Curl_easy *data, int action) /* Unpause parts in active mime tree. */ if((k->keepon & ~newstate & KEEP_SEND_PAUSE) && (data->mstate == MSTATE_PERFORMING || - data->mstate == MSTATE_RATELIMITING) && - data->state.fread_func == (curl_read_callback) Curl_mime_read) { - Curl_mime_unpause(data->state.in); + data->mstate == MSTATE_RATELIMITING)) { + result = Curl_creader_unpause(data); + if(result) + return result; } /* put it back in the keepon */ diff --git a/lib/http.c b/lib/http.c index e6375b92e10..88746eb579c 100644 --- a/lib/http.c +++ b/lib/http.c @@ -2030,47 +2030,41 @@ static CURLcode set_post_reader(struct Curl_easy *data, Curl_HttpReq httpreq) break; } + switch(httpreq) { + case HTTPREQ_POST_FORM: + case HTTPREQ_POST_MIME: + /* This is form posting using mime data. */ #ifndef CURL_DISABLE_MIME - if(data->state.mimepost) { - const char *cthdr = Curl_checkheaders(data, STRCONST("Content-Type")); + if(data->state.mimepost) { + const char *cthdr = Curl_checkheaders(data, STRCONST("Content-Type")); - /* Read and seek body only. */ - data->state.mimepost->flags |= MIME_BODY_ONLY; + /* Read and seek body only. */ + data->state.mimepost->flags |= MIME_BODY_ONLY; - /* Prepare the mime structure headers & set content type. */ + /* Prepare the mime structure headers & set content type. */ - if(cthdr) - for(cthdr += 13; *cthdr == ' '; cthdr++) - ; - else if(data->state.mimepost->kind == MIMEKIND_MULTIPART) - cthdr = "multipart/form-data"; + if(cthdr) + for(cthdr += 13; *cthdr == ' '; cthdr++) + ; + else if(data->state.mimepost->kind == MIMEKIND_MULTIPART) + cthdr = "multipart/form-data"; - curl_mime_headers(data->state.mimepost, data->set.headers, 0); - result = Curl_mime_prepare_headers(data, data->state.mimepost, cthdr, - NULL, MIMESTRATEGY_FORM); - curl_mime_headers(data->state.mimepost, NULL, 0); - if(!result) - result = Curl_mime_rewind(data->state.mimepost); - if(result) - return result; - postsize = Curl_mime_size(data->state.mimepost); - } + curl_mime_headers(data->state.mimepost, data->set.headers, 0); + result = Curl_mime_prepare_headers(data, data->state.mimepost, cthdr, + NULL, MIMESTRATEGY_FORM); + if(result) + return result; + curl_mime_headers(data->state.mimepost, NULL, 0); + result = Curl_creader_set_mime(data, data->state.mimepost); + if(result) + return result; + } + else #endif - - switch(httpreq) { - case HTTPREQ_POST_FORM: - case HTTPREQ_POST_MIME: - /* This is form posting using mime data. */ - data->state.infilesize = postsize; - if(!postsize) + { result = Curl_creader_set_null(data); - else { - /* Read from mime structure. We could do a special client reader - * for this, but replacing the callback seems to work fine. */ - data->state.fread_func = (curl_read_callback) Curl_mime_read; - data->state.in = (void *) data->state.mimepost; - result = Curl_creader_set_fread(data, postsize); } + data->state.infilesize = Curl_creader_total_length(data); return result; default: if(!postsize) diff --git a/lib/http_chunks.c b/lib/http_chunks.c index dbcc527630e..f9cb0741ea2 100644 --- a/lib/http_chunks.c +++ b/lib/http_chunks.c @@ -643,6 +643,7 @@ const struct Curl_crtype Curl_httpchunk_encoder = { cr_chunked_total_length, Curl_creader_def_resume_from, Curl_creader_def_rewind, + Curl_creader_def_unpause, sizeof(struct chunked_reader) }; diff --git a/lib/imap.c b/lib/imap.c index 43ec83d09c6..0e013e740ae 100644 --- a/lib/imap.c +++ b/lib/imap.c @@ -786,20 +786,19 @@ static CURLcode imap_perform_append(struct Curl_easy *data) result = Curl_mime_add_header(&data->set.mimepost.curlheaders, "Mime-Version: 1.0"); - /* Make sure we will read the entire mime structure. */ if(!result) - result = Curl_mime_rewind(&data->set.mimepost); - + result = Curl_creader_set_mime(data, &data->set.mimepost); if(result) return result; - - data->state.infilesize = Curl_mime_size(&data->set.mimepost); - - /* Read from mime structure. */ - data->state.fread_func = (curl_read_callback) Curl_mime_read; - data->state.in = (void *) &data->set.mimepost; + data->state.infilesize = Curl_creader_client_length(data); } + else #endif + { + result = Curl_creader_set_fread(data, data->state.infilesize); + if(result) + return result; + } /* Check we know the size of the upload */ if(data->state.infilesize < 0) { diff --git a/lib/mime.c b/lib/mime.c index d712331d040..cccf46f8975 100644 --- a/lib/mime.c +++ b/lib/mime.c @@ -74,6 +74,7 @@ static curl_off_t encoder_base64_size(curl_mimepart *part); static size_t encoder_qp_read(char *buffer, size_t size, bool ateof, curl_mimepart *part); static curl_off_t encoder_qp_size(curl_mimepart *part); +static curl_off_t mime_size(curl_mimepart *part); static const struct mime_encoder encoders[] = { {"binary", encoder_nop_read, encoder_nop_size}, @@ -1602,7 +1603,7 @@ size_t Curl_mime_read(char *buffer, size_t size, size_t nitems, void *instream) } /* Rewind mime stream. */ -CURLcode Curl_mime_rewind(curl_mimepart *part) +static CURLcode mime_rewind(curl_mimepart *part) { return mime_part_rewind(part) == CURL_SEEKFUNC_OK? CURLE_OK: CURLE_SEND_FAIL_REWIND; @@ -1634,7 +1635,7 @@ static curl_off_t multipart_size(curl_mime *mime) size = boundarysize; /* Final boundary - CRLF after headers. */ for(part = mime->firstpart; part; part = part->nextpart) { - curl_off_t sz = Curl_mime_size(part); + curl_off_t sz = mime_size(part); if(sz < 0) size = sz; @@ -1647,7 +1648,7 @@ static curl_off_t multipart_size(curl_mime *mime) } /* Get/compute mime size. */ -curl_off_t Curl_mime_size(curl_mimepart *part) +static curl_off_t mime_size(curl_mimepart *part) { curl_off_t size; @@ -1896,7 +1897,7 @@ CURLcode Curl_mime_prepare_headers(struct Curl_easy *data, } /* Recursively reset paused status in the given part. */ -void Curl_mime_unpause(curl_mimepart *part) +static void mime_unpause(curl_mimepart *part) { if(part) { if(part->lastreadstatus == CURL_READFUNC_PAUSE) @@ -1908,12 +1909,227 @@ void Curl_mime_unpause(curl_mimepart *part) curl_mimepart *subpart; for(subpart = mime->firstpart; subpart; subpart = subpart->nextpart) - Curl_mime_unpause(subpart); + mime_unpause(subpart); } } } } +struct cr_mime_ctx { + struct Curl_creader super; + curl_mimepart *part; + curl_off_t total_len; + curl_off_t read_len; + CURLcode error_result; + BIT(seen_eos); + BIT(errored); +}; + +static CURLcode cr_mime_init(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + (void)data; + ctx->total_len = -1; + ctx->read_len = 0; + return CURLE_OK; +} + +/* Real client reader to installed client callbacks. */ +static CURLcode cr_mime_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *pnread, bool *peos) +{ + struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + size_t nread; + + /* Once we have errored, we will return the same error forever */ + if(ctx->errored) { + *pnread = 0; + *peos = FALSE; + return ctx->error_result; + } + if(ctx->seen_eos) { + *pnread = 0; + *peos = TRUE; + return CURLE_OK; + } + /* respect length limitations */ + if(ctx->total_len >= 0) { + curl_off_t remain = ctx->total_len - ctx->read_len; + if(remain <= 0) + blen = 0; + else if(remain < (curl_off_t)blen) + blen = (size_t)remain; + } + nread = 0; + if(blen) { + nread = Curl_mime_read(buf, 1, blen, ctx->part); + } + + switch(nread) { + case 0: + if((ctx->total_len >= 0) && (ctx->read_len < ctx->total_len)) { + failf(data, "client mime read EOF fail, only " + "only %"CURL_FORMAT_CURL_OFF_T"/%"CURL_FORMAT_CURL_OFF_T + " of needed bytes read", ctx->read_len, ctx->total_len); + return CURLE_READ_ERROR; + } + *pnread = 0; + *peos = TRUE; + ctx->seen_eos = TRUE; + break; + + case CURL_READFUNC_ABORT: + failf(data, "operation aborted by callback"); + *pnread = 0; + *peos = FALSE; + ctx->errored = TRUE; + ctx->error_result = CURLE_ABORTED_BY_CALLBACK; + return CURLE_ABORTED_BY_CALLBACK; + + case CURL_READFUNC_PAUSE: + /* CURL_READFUNC_PAUSE pauses read callbacks that feed socket writes */ + data->req.keepon |= KEEP_SEND_PAUSE; /* mark socket send as paused */ + *pnread = 0; + *peos = FALSE; + break; /* nothing was read */ + + default: + if(nread > blen) { + /* the read function returned a too large value */ + failf(data, "read function returned funny value"); + *pnread = 0; + *peos = FALSE; + ctx->errored = TRUE; + ctx->error_result = CURLE_READ_ERROR; + return CURLE_READ_ERROR; + } + ctx->read_len += nread; + if(ctx->total_len >= 0) + ctx->seen_eos = (ctx->read_len >= ctx->total_len); + *pnread = nread; + *peos = ctx->seen_eos; + break; + } + DEBUGF(infof(data, "cr_mime_read(len=%zu, total=%"CURL_FORMAT_CURL_OFF_T + ", read=%"CURL_FORMAT_CURL_OFF_T") -> %d, %zu, %d", + blen, ctx->total_len, ctx->read_len, CURLE_OK, *pnread, *peos)); + return CURLE_OK; +} + +static bool cr_mime_needs_rewind(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + (void)data; + return ctx->read_len > 0; +} + +static curl_off_t cr_mime_total_length(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + (void)data; + return ctx->total_len; +} + +static CURLcode cr_mime_resume_from(struct Curl_easy *data, + struct Curl_creader *reader, + curl_off_t offset) +{ + struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + + if(offset > 0) { + curl_off_t passed = 0; + + do { + char scratch[4*1024]; + size_t readthisamountnow = + (offset - passed > (curl_off_t)sizeof(scratch)) ? + sizeof(scratch) : + curlx_sotouz(offset - passed); + size_t nread; + + nread = Curl_mime_read(scratch, 1, readthisamountnow, ctx->part); + passed += (curl_off_t)nread; + if((nread == 0) || (nread > readthisamountnow)) { + /* this checks for greater-than only to make sure that the + CURL_READFUNC_ABORT return code still aborts */ + failf(data, "Could only read %" CURL_FORMAT_CURL_OFF_T + " bytes from the mime post", passed); + return CURLE_READ_ERROR; + } + } while(passed < offset); + + /* now, decrease the size of the read */ + if(ctx->total_len > 0) { + ctx->total_len -= offset; + + if(ctx->total_len <= 0) { + failf(data, "Mime post already completely uploaded"); + return CURLE_PARTIAL_FILE; + } + } + /* we've passed, proceed as normal */ + } + return CURLE_OK; +} + +static CURLcode cr_mime_rewind(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + CURLcode result = mime_rewind(ctx->part); + if(result) + failf(data, "Cannot rewind mime/post data"); + return result; +} + +static CURLcode cr_mime_unpause(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + (void)data; + mime_unpause(ctx->part); + return CURLE_OK; +} + +static const struct Curl_crtype cr_mime = { + "cr-mime", + cr_mime_init, + cr_mime_read, + Curl_creader_def_close, + cr_mime_needs_rewind, + cr_mime_total_length, + cr_mime_resume_from, + cr_mime_rewind, + cr_mime_unpause, + sizeof(struct cr_mime_ctx) +}; + +CURLcode Curl_creader_set_mime(struct Curl_easy *data, curl_mimepart *part) +{ + struct Curl_creader *r; + struct cr_mime_ctx *ctx; + CURLcode result; + + result = Curl_creader_create(&r, data, &cr_mime, CURL_CR_CLIENT); + if(result) + return result; + ctx = (struct cr_mime_ctx *)r; + ctx->part = part; + /* Make sure we will read the entire mime structure. */ + result = mime_rewind(ctx->part); + if(result) { + Curl_creader_free(data, r); + return result; + } + ctx->total_len = mime_size(ctx->part); + + return Curl_creader_set(data, r); +} #else /* !CURL_DISABLE_MIME && (!CURL_DISABLE_HTTP || !CURL_DISABLE_SMTP || !CURL_DISABLE_IMAP) */ diff --git a/lib/mime.h b/lib/mime.h index a64f41d4b52..954b3ccf394 100644 --- a/lib/mime.h +++ b/lib/mime.h @@ -151,12 +151,15 @@ CURLcode Curl_mime_prepare_headers(struct Curl_easy *data, const char *contenttype, const char *disposition, enum mimestrategy strategy); -curl_off_t Curl_mime_size(struct curl_mimepart *part); size_t Curl_mime_read(char *buffer, size_t size, size_t nitems, void *instream); -CURLcode Curl_mime_rewind(struct curl_mimepart *part); const char *Curl_mime_contenttype(const char *filename); -void Curl_mime_unpause(struct curl_mimepart *part); + +/** + * Install a client reader as upload source that reads the given + * mime part. + */ +CURLcode Curl_creader_set_mime(struct Curl_easy *data, curl_mimepart *part); #else /* if disabled */ @@ -165,10 +168,8 @@ void Curl_mime_unpause(struct curl_mimepart *part); #define Curl_mime_duppart(x,y,z) CURLE_OK /* Nothing to duplicate. Succeed */ #define Curl_mime_set_subparts(a,b,c) CURLE_NOT_BUILT_IN #define Curl_mime_prepare_headers(a,b,c,d,e) CURLE_NOT_BUILT_IN -#define Curl_mime_size(x) (curl_off_t) -1 #define Curl_mime_read NULL -#define Curl_mime_rewind(x) ((void)x, CURLE_NOT_BUILT_IN) -#define Curl_mime_unpause(x) +#define Curl_creader_set_mime(x,y) ((void)x, CURLE_NOT_BUILT_IN) #endif diff --git a/lib/request.c b/lib/request.c index d009eddb1c0..ed4aa714c12 100644 --- a/lib/request.c +++ b/lib/request.c @@ -139,7 +139,6 @@ void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data) req->ignore_cl = FALSE; req->upload_chunky = FALSE; req->getheader = FALSE; - req->forbidchunk = FALSE; req->no_body = data->set.opt_no_body; req->authneg = FALSE; } diff --git a/lib/request.h b/lib/request.h index fdfdb0bee23..2298e79d732 100644 --- a/lib/request.h +++ b/lib/request.h @@ -139,9 +139,6 @@ struct SingleRequest { BIT(upload_chunky); /* set TRUE if we are doing chunked transfer-encoding on upload */ BIT(getheader); /* TRUE if header parsing is wanted */ - BIT(forbidchunk); /* used only to explicitly forbid chunk-upload for - specific upload buffers. See readmoredata() in http.c - for details. */ BIT(no_body); /* the response has no body */ BIT(authneg); /* TRUE when the auth phase has started, which means that we are creating a request with an auth header, diff --git a/lib/rtsp.c b/lib/rtsp.c index 7c3dd31a6e8..a0b978d92a6 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -571,8 +571,6 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) goto out; } - /* RTSP never allows chunked transfer */ - data->req.forbidchunk = TRUE; /* Finish the request buffer */ result = Curl_dyn_addn(&req_buffer, STRCONST("\r\n")); if(result) diff --git a/lib/sendf.c b/lib/sendf.c index 22e2b8592ae..81f2deabdc0 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -553,6 +553,14 @@ CURLcode Curl_creader_def_rewind(struct Curl_easy *data, return CURLE_OK; } +CURLcode Curl_creader_def_unpause(struct Curl_easy *data, + struct Curl_creader *reader) +{ + (void)data; + (void)reader; + return CURLE_OK; +} + struct cr_in_ctx { struct Curl_creader super; curl_read_callback read_cb; @@ -753,37 +761,11 @@ static CURLcode cr_in_rewind(struct Curl_easy *data, struct Curl_creader *reader) { struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; - /* TODO: I wonder if we should rather give mime its own client - * reader type. This is messy. */ -#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) - curl_mimepart *mimepart = &data->set.mimepost; -#endif /* If we never invoked the callback, there is noting to rewind */ if(!ctx->has_used_cb) return CURLE_OK; - /* We have sent away data. If not using CURLOPT_POSTFIELDS or - CURLOPT_HTTPPOST, call app to rewind - */ -#if !defined(CURL_DISABLE_HTTP) && !defined(CURL_DISABLE_MIME) - if(data->conn->handler->protocol & PROTO_FAMILY_HTTP) { - if(data->state.mimepost) - mimepart = data->state.mimepost; - } -#endif -#if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) - if(ctx->read_cb == (curl_read_callback)Curl_mime_read) { - CURLcode result = Curl_mime_rewind(mimepart); - DEBUGF(infof(data, "cr_in, rewind mime/post data -> %d", result)); - if(result) { - failf(data, "Cannot rewind mime/post data"); - } - return result; - } -#endif - - /* With mime out of the way, handle "normal" fread callbacks */ if(data->set.seek_func) { int err; @@ -839,6 +821,7 @@ static const struct Curl_crtype cr_in = { cr_in_total_length, cr_in_resume_from, cr_in_rewind, + Curl_creader_def_unpause, sizeof(struct cr_in_ctx) }; @@ -985,6 +968,7 @@ static const struct Curl_crtype cr_lc = { cr_lc_total_length, Curl_creader_def_resume_from, Curl_creader_def_rewind, + Curl_creader_def_unpause, sizeof(struct cr_lc_ctx) }; @@ -1004,18 +988,18 @@ static CURLcode cr_lc_add(struct Curl_easy *data) } static CURLcode do_init_reader_stack(struct Curl_easy *data, - const struct Curl_crtype *crt, - struct Curl_creader **preader, - curl_off_t clen) + struct Curl_creader *r) { - CURLcode result; + CURLcode result = CURLE_OK; + curl_off_t clen; + DEBUGASSERT(r); + DEBUGASSERT(r->crt); + DEBUGASSERT(r->phase == CURL_CR_CLIENT); DEBUGASSERT(!data->req.reader_stack); - result = Curl_creader_create(preader, data, crt, CURL_CR_CLIENT); - if(result) - return result; - data->req.reader_stack = *preader; + data->req.reader_stack = r; + clen = r->crt->total_length(data, r); /* if we do not have 0 length init, and crlf conversion is wanted, * add the reader for it */ if(clen && (data->set.crlf @@ -1035,15 +1019,16 @@ CURLcode Curl_creader_set_fread(struct Curl_easy *data, curl_off_t len) { CURLcode result; struct Curl_creader *r; + struct cr_in_ctx *ctx; + + result = Curl_creader_create(&r, data, &cr_in, CURL_CR_CLIENT); + if(result) + return result; + ctx = (struct cr_in_ctx *)r; + ctx->total_len = len; cl_reset_reader(data); - result = do_init_reader_stack(data, &cr_in, &r, len); - if(!result && r) { - struct cr_in_ctx *ctx = (struct cr_in_ctx *)r; - DEBUGASSERT(r->crt == &cr_in); - ctx->total_len = len; - } - return result; + return do_init_reader_stack(data, r); } CURLcode Curl_creader_add(struct Curl_easy *data, @@ -1067,6 +1052,21 @@ CURLcode Curl_creader_add(struct Curl_easy *data, return CURLE_OK; } +CURLcode Curl_creader_set(struct Curl_easy *data, struct Curl_creader *r) +{ + CURLcode result; + + DEBUGASSERT(r); + DEBUGASSERT(r->crt); + DEBUGASSERT(r->phase == CURL_CR_CLIENT); + + cl_reset_reader(data); + result = do_init_reader_stack(data, r); + if(result) + Curl_creader_free(data, r); + return result; +} + CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen, size_t *nread, bool *eos) { @@ -1132,15 +1132,21 @@ static const struct Curl_crtype cr_null = { cr_null_total_length, Curl_creader_def_resume_from, Curl_creader_def_rewind, + Curl_creader_def_unpause, sizeof(struct Curl_creader) }; CURLcode Curl_creader_set_null(struct Curl_easy *data) { struct Curl_creader *r; + CURLcode result; + + result = Curl_creader_create(&r, data, &cr_null, CURL_CR_CLIENT); + if(result) + return result; cl_reset_reader(data); - return do_init_reader_stack(data, &cr_null, &r, 0); + return do_init_reader_stack(data, r); } struct cr_buf_ctx { @@ -1222,6 +1228,7 @@ static const struct Curl_crtype cr_buf = { cr_buf_total_length, cr_buf_resume_from, Curl_creader_def_rewind, + Curl_creader_def_unpause, sizeof(struct cr_buf_ctx) }; @@ -1230,17 +1237,18 @@ CURLcode Curl_creader_set_buf(struct Curl_easy *data, { CURLcode result; struct Curl_creader *r; + struct cr_buf_ctx *ctx; + + result = Curl_creader_create(&r, data, &cr_buf, CURL_CR_CLIENT); + if(result) + return result; + ctx = (struct cr_buf_ctx *)r; + ctx->buf = buf; + ctx->blen = blen; + ctx->index = 0; cl_reset_reader(data); - result = do_init_reader_stack(data, &cr_buf, &r, blen); - if(!result && r) { - struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)r; - DEBUGASSERT(r->crt == &cr_buf); - ctx->buf = buf; - ctx->blen = blen; - ctx->index = 0; - } - return result; + return do_init_reader_stack(data, r); } curl_off_t Curl_creader_total_length(struct Curl_easy *data) @@ -1264,3 +1272,17 @@ CURLcode Curl_creader_resume_from(struct Curl_easy *data, curl_off_t offset) r = r->next; return r? r->crt->resume_from(data, r, offset) : CURLE_READ_ERROR; } + +CURLcode Curl_creader_unpause(struct Curl_easy *data) +{ + struct Curl_creader *reader = data->req.reader_stack; + CURLcode result = CURLE_OK; + + while(reader) { + result = reader->crt->unpause(data, reader); + if(result) + break; + reader = reader->next; + } + return result; +} diff --git a/lib/sendf.h b/lib/sendf.h index efb9628fc1b..2c5bc362086 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -187,6 +187,7 @@ void Curl_cwriter_def_close(struct Curl_easy *data, struct Curl_cwriter *writer); + /* Client Reader Type, provides the implementation */ struct Curl_crtype { const char *name; /* writer name. */ @@ -200,6 +201,7 @@ struct Curl_crtype { 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); + CURLcode (*unpause)(struct Curl_easy *data, struct Curl_creader *reader); size_t creader_size; /* sizeof() allocated struct Curl_creader */ }; @@ -236,6 +238,8 @@ CURLcode Curl_creader_def_resume_from(struct Curl_easy *data, curl_off_t offset); CURLcode Curl_creader_def_rewind(struct Curl_easy *data, struct Curl_creader *reader); +CURLcode Curl_creader_def_unpause(struct Curl_easy *data, + struct Curl_creader *reader); /** * Convenience method for calling `reader->do_read()` that @@ -268,6 +272,14 @@ void Curl_creader_free(struct Curl_easy *data, struct Curl_creader *reader); CURLcode Curl_creader_add(struct Curl_easy *data, struct Curl_creader *reader); +/** + * Set the given reader, which needs to be of type CURL_CR_CLIENT, + * as the new first reader. Discard any installed readers and init + * the reader chain anew. + * The function takes ownership of `r`. + */ +CURLcode Curl_creader_set(struct Curl_easy *data, struct Curl_creader *r); + /** * Read at most `blen` bytes at `buf` from the client. * @param date the transfer to read client bytes for @@ -328,6 +340,11 @@ curl_off_t Curl_creader_client_length(struct Curl_easy *data); */ CURLcode Curl_creader_resume_from(struct Curl_easy *data, curl_off_t offset); +/** + * Unpause all installed readers. + */ +CURLcode Curl_creader_unpause(struct Curl_easy *data); + /** * Set the client reader to provide 0 bytes, immediate EOS. */ diff --git a/lib/smtp.c b/lib/smtp.c index 43a85c97c17..2d853600831 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -705,20 +705,19 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) result = Curl_mime_add_header(&data->set.mimepost.curlheaders, "Mime-Version: 1.0"); - /* Make sure we will read the entire mime structure. */ if(!result) - result = Curl_mime_rewind(&data->set.mimepost); - + result = Curl_creader_set_mime(data, &data->set.mimepost); if(result) goto out; - - data->state.infilesize = Curl_mime_size(&data->set.mimepost); - - /* Read from mime structure. */ - data->state.fread_func = (curl_read_callback) Curl_mime_read; - data->state.in = (void *) &data->set.mimepost; + data->state.infilesize = Curl_creader_total_length(data); } + else #endif + { + result = Curl_creader_set_fread(data, data->state.infilesize); + if(result) + goto out; + } /* Calculate the optional SIZE parameter */ if(conn->proto.smtpc.size_supported && data->state.infilesize > 0) { @@ -747,10 +746,6 @@ static CURLcode smtp_perform_mail(struct Curl_easy *data) } } - /* Setup client reader for size and EOB conversion */ - result = Curl_creader_set_fread(data, data->state.infilesize); - if(result) - goto out; /* Add the client reader doing STMP EOB escaping */ result = cr_eob_add(data); if(result) @@ -1927,6 +1922,7 @@ static const struct Curl_crtype cr_eob = { cr_eob_total_length, Curl_creader_def_resume_from, Curl_creader_def_rewind, + Curl_creader_def_unpause, sizeof(struct cr_eob_ctx) }; From db5c9f4f9e0779b49624752b135281a0717b277b Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 5 Mar 2024 11:08:55 +0100 Subject: [PATCH 427/509] transfer.c: break receive loop in speed limited transfers - the change breaks looping in transfer.c receive for transfers that are speed limited on having gotten *some* bytes. - the overall speed limit timing is done in multi.c Reported-by: Dmitry Karpov Bug: https://curl.se/mail/lib-2024-03/0001.html Closes #13050 --- lib/transfer.c | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/lib/transfer.c b/lib/transfer.c index cd3bd37682d..669beebd3a6 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -242,13 +242,14 @@ static CURLcode readwrite_data(struct Curl_easy *data, buf = xfer_buf; bytestoread = xfer_blen; - /* Observe any imposed speed limit */ if(bytestoread && data->set.max_recv_speed) { - curl_off_t net_limit = data->set.max_recv_speed - total_received; - if(net_limit <= 0) + /* In case of speed limit on receiving: if this loop already got + * data, break out. If not, limit the amount of bytes to receive. + * The overall, timed, speed limiting is done in multi.c */ + if(total_received) break; - if((size_t)net_limit < bytestoread) - bytestoread = (size_t)net_limit; + if((size_t)data->set.max_recv_speed < bytestoread) + bytestoread = (size_t)data->set.max_recv_speed; } nread = Curl_xfer_recv_resp(data, buf, bytestoread, From cc6f2f0064b67ca8bfdc5d6f09c9e90e8d07cf6d Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 6 Mar 2024 10:15:15 +0100 Subject: [PATCH 428/509] http2: fix push discard - fix logic in discarding a failed pushed stream so that stream context is properly cleaned up Closes #13055 --- lib/http2.c | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/http2.c b/lib/http2.c index cb765b54b5a..c63ecd38371 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -839,9 +839,8 @@ static int set_transfer_url(struct Curl_easy *data, static void discard_newhandle(struct Curl_cfilter *cf, struct Curl_easy *newhandle) { - if(!newhandle->req.p.http) { + if(newhandle->req.p.http) { http2_data_done(cf, newhandle, TRUE); - newhandle->req.p.http = NULL; } (void)Curl_close(&newhandle); } From 2ca530d2fa649f8a7212c77218870ae456a914ce Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 6 Mar 2024 12:09:05 +0100 Subject: [PATCH 429/509] http: fix dead code in setting post client reader - postsize was always 0, thus the check's else never happened after the mime client reader was introduced Follow-up to 0ba47146f7ff3d Closes #13060 --- lib/http.c | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/lib/http.c b/lib/http.c index 88746eb579c..d50b099c77e 100644 --- a/lib/http.c +++ b/lib/http.c @@ -1997,7 +1997,6 @@ CURLcode Curl_http_target(struct Curl_easy *data, #if !defined(CURL_DISABLE_MIME) || !defined(CURL_DISABLE_FORM_API) static CURLcode set_post_reader(struct Curl_easy *data, Curl_HttpReq httpreq) { - curl_off_t postsize = 0; CURLcode result; switch(httpreq) { @@ -2066,12 +2065,9 @@ static CURLcode set_post_reader(struct Curl_easy *data, Curl_HttpReq httpreq) } data->state.infilesize = Curl_creader_total_length(data); return result; + default: - if(!postsize) - result = Curl_creader_set_null(data); - else - result = Curl_creader_set_fread(data, postsize); - return result; + return Curl_creader_set_null(data); } /* never reached */ } From 9978d40ddbd00abf219ec332f72b5b9e697e5941 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 6 Mar 2024 09:52:43 +0100 Subject: [PATCH 430/509] lib: add `void *ctx` to reader/writer instances - `struct Curl_cwriter` and `struct Curl_creader` now carry a `void *ctx` member that points to the instance as allocated. - using `r->ctx` and `w->ctx` as pointer to the instance specific struct that has been allocated Reported-by: Rudi Heitbaum Fixes #13035 Closes #13059 --- lib/cw-out.c | 6 +++--- lib/ftp.c | 2 +- lib/http_chunks.c | 16 +++++++-------- lib/mime.c | 16 +++++++-------- lib/sendf.c | 50 ++++++++++++++++++++++++++--------------------- lib/sendf.h | 16 +++++++++++++-- lib/smtp.c | 6 +++--- lib/ws.c | 6 +++--- 8 files changed, 68 insertions(+), 50 deletions(-) diff --git a/lib/cw-out.c b/lib/cw-out.c index b29b45665a8..25a27a68cd6 100644 --- a/lib/cw-out.c +++ b/lib/cw-out.c @@ -123,7 +123,7 @@ struct Curl_cwtype Curl_cwt_out = { static CURLcode cw_out_init(struct Curl_easy *data, struct Curl_cwriter *writer) { - struct cw_out_ctx *ctx = (struct cw_out_ctx *)writer; + struct cw_out_ctx *ctx = writer->ctx; (void)data; ctx->buf = NULL; return CURLE_OK; @@ -151,7 +151,7 @@ static size_t cw_out_bufs_len(struct cw_out_ctx *ctx) static void cw_out_close(struct Curl_easy *data, struct Curl_cwriter *writer) { - struct cw_out_ctx *ctx = (struct cw_out_ctx *)writer; + struct cw_out_ctx *ctx = writer->ctx; (void)data; cw_out_bufs_free(ctx); @@ -378,7 +378,7 @@ static CURLcode cw_out_write(struct Curl_easy *data, struct Curl_cwriter *writer, int type, const char *buf, size_t blen) { - struct cw_out_ctx *ctx = (struct cw_out_ctx *)writer; + struct cw_out_ctx *ctx = writer->ctx; CURLcode result; bool flush_all; diff --git a/lib/ftp.c b/lib/ftp.c index 8881bd364a3..2511bd4b611 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -273,7 +273,7 @@ static CURLcode ftp_cw_lc_write(struct Curl_easy *data, const char *buf, size_t blen) { static const char nl = '\n'; - struct ftp_cw_lc_ctx *ctx = (struct ftp_cw_lc_ctx *)writer; + struct ftp_cw_lc_ctx *ctx = writer->ctx; if(!(type & CLIENTWRITE_BODY) || data->conn->proto.ftpc.transfertype != 'A') diff --git a/lib/http_chunks.c b/lib/http_chunks.c index f9cb0741ea2..cfbd40bc286 100644 --- a/lib/http_chunks.c +++ b/lib/http_chunks.c @@ -394,7 +394,7 @@ struct chunked_writer { static CURLcode cw_chunked_init(struct Curl_easy *data, struct Curl_cwriter *writer) { - struct chunked_writer *ctx = (struct chunked_writer *)writer; + struct chunked_writer *ctx = writer->ctx; data->req.chunk = TRUE; /* chunks coming our way. */ Curl_httpchunk_init(data, &ctx->ch, FALSE); @@ -404,7 +404,7 @@ static CURLcode cw_chunked_init(struct Curl_easy *data, static void cw_chunked_close(struct Curl_easy *data, struct Curl_cwriter *writer) { - struct chunked_writer *ctx = (struct chunked_writer *)writer; + struct chunked_writer *ctx = writer->ctx; Curl_httpchunk_free(data, &ctx->ch); } @@ -412,7 +412,7 @@ static CURLcode cw_chunked_write(struct Curl_easy *data, struct Curl_cwriter *writer, int type, const char *buf, size_t blen) { - struct chunked_writer *ctx = (struct chunked_writer *)writer; + struct chunked_writer *ctx = writer->ctx; CURLcode result; size_t consumed; @@ -474,7 +474,7 @@ struct chunked_reader { static CURLcode cr_chunked_init(struct Curl_easy *data, struct Curl_creader *reader) { - struct chunked_reader *ctx = (struct chunked_reader *)reader; + struct chunked_reader *ctx = reader->ctx; (void)data; Curl_bufq_init2(&ctx->chunkbuf, CURL_CHUNKED_MAXLEN, 2, BUFQ_OPT_SOFT_LIMIT); return CURLE_OK; @@ -483,7 +483,7 @@ static CURLcode cr_chunked_init(struct Curl_easy *data, static void cr_chunked_close(struct Curl_easy *data, struct Curl_creader *reader) { - struct chunked_reader *ctx = (struct chunked_reader *)reader; + struct chunked_reader *ctx = reader->ctx; (void)data; Curl_bufq_free(&ctx->chunkbuf); } @@ -491,7 +491,7 @@ static void cr_chunked_close(struct Curl_easy *data, static CURLcode add_last_chunk(struct Curl_easy *data, struct Curl_creader *reader) { - struct chunked_reader *ctx = (struct chunked_reader *)reader; + struct chunked_reader *ctx = reader->ctx; struct curl_slist *trailers = NULL, *tr; CURLcode result; size_t n; @@ -542,7 +542,7 @@ static CURLcode add_chunk(struct Curl_easy *data, struct Curl_creader *reader, char *buf, size_t blen) { - struct chunked_reader *ctx = (struct chunked_reader *)reader; + struct chunked_reader *ctx = reader->ctx; CURLcode result; char tmp[CURL_CHUNKED_MINLEN]; size_t nread; @@ -595,7 +595,7 @@ static CURLcode cr_chunked_read(struct Curl_easy *data, char *buf, size_t blen, size_t *pnread, bool *peos) { - struct chunked_reader *ctx = (struct chunked_reader *)reader; + struct chunked_reader *ctx = reader->ctx; CURLcode result = CURLE_READ_ERROR; *pnread = 0; diff --git a/lib/mime.c b/lib/mime.c index cccf46f8975..48a1ad87c7a 100644 --- a/lib/mime.c +++ b/lib/mime.c @@ -1928,7 +1928,7 @@ struct cr_mime_ctx { static CURLcode cr_mime_init(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + struct cr_mime_ctx *ctx = reader->ctx; (void)data; ctx->total_len = -1; ctx->read_len = 0; @@ -1941,7 +1941,7 @@ static CURLcode cr_mime_read(struct Curl_easy *data, char *buf, size_t blen, size_t *pnread, bool *peos) { - struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + struct cr_mime_ctx *ctx = reader->ctx; size_t nread; /* Once we have errored, we will return the same error forever */ @@ -2022,7 +2022,7 @@ static CURLcode cr_mime_read(struct Curl_easy *data, static bool cr_mime_needs_rewind(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + struct cr_mime_ctx *ctx = reader->ctx; (void)data; return ctx->read_len > 0; } @@ -2030,7 +2030,7 @@ static bool cr_mime_needs_rewind(struct Curl_easy *data, static curl_off_t cr_mime_total_length(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + struct cr_mime_ctx *ctx = reader->ctx; (void)data; return ctx->total_len; } @@ -2039,7 +2039,7 @@ static CURLcode cr_mime_resume_from(struct Curl_easy *data, struct Curl_creader *reader, curl_off_t offset) { - struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + struct cr_mime_ctx *ctx = reader->ctx; if(offset > 0) { curl_off_t passed = 0; @@ -2080,7 +2080,7 @@ static CURLcode cr_mime_resume_from(struct Curl_easy *data, static CURLcode cr_mime_rewind(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + struct cr_mime_ctx *ctx = reader->ctx; CURLcode result = mime_rewind(ctx->part); if(result) failf(data, "Cannot rewind mime/post data"); @@ -2090,7 +2090,7 @@ static CURLcode cr_mime_rewind(struct Curl_easy *data, static CURLcode cr_mime_unpause(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_mime_ctx *ctx = (struct cr_mime_ctx *)reader; + struct cr_mime_ctx *ctx = reader->ctx; (void)data; mime_unpause(ctx->part); return CURLE_OK; @@ -2118,7 +2118,7 @@ CURLcode Curl_creader_set_mime(struct Curl_easy *data, curl_mimepart *part) result = Curl_creader_create(&r, data, &cr_mime, CURL_CR_CLIENT); if(result) return result; - ctx = (struct cr_mime_ctx *)r; + ctx = r->ctx; ctx->part = part; /* Make sure we will read the entire mime structure. */ result = mime_rewind(ctx->part); diff --git a/lib/sendf.c b/lib/sendf.c index 81f2deabdc0..ce9b2b07576 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -236,7 +236,7 @@ static CURLcode cw_download_write(struct Curl_easy *data, struct Curl_cwriter *writer, int type, const char *buf, size_t nbytes) { - struct cw_download_ctx *ctx = (struct cw_download_ctx *)writer; + struct cw_download_ctx *ctx = writer->ctx; CURLcode result; size_t nwrite, excess_len = 0; bool is_connect = !!(type & CLIENTWRITE_CONNECT); @@ -368,15 +368,18 @@ CURLcode Curl_cwriter_create(struct Curl_cwriter **pwriter, const struct Curl_cwtype *cwt, Curl_cwriter_phase phase) { - struct Curl_cwriter *writer; + struct Curl_cwriter *writer = NULL; CURLcode result = CURLE_OUT_OF_MEMORY; + void *p; DEBUGASSERT(cwt->cwriter_size >= sizeof(struct Curl_cwriter)); - writer = (struct Curl_cwriter *) calloc(1, cwt->cwriter_size); - if(!writer) + p = calloc(1, cwt->cwriter_size); + if(!p) goto out; + writer = (struct Curl_cwriter *)p; writer->cwt = cwt; + writer->ctx = p; writer->phase = phase; result = cwt->do_init(data, writer); @@ -575,7 +578,7 @@ struct cr_in_ctx { static CURLcode cr_in_init(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + struct cr_in_ctx *ctx = reader->ctx; (void)data; ctx->read_cb = data->state.fread_func; ctx->cb_user_data = data->state.in; @@ -590,7 +593,7 @@ static CURLcode cr_in_read(struct Curl_easy *data, char *buf, size_t blen, size_t *pnread, bool *peos) { - struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + struct cr_in_ctx *ctx = reader->ctx; size_t nread; /* Once we have errored, we will return the same error forever */ @@ -681,7 +684,7 @@ static CURLcode cr_in_read(struct Curl_easy *data, static bool cr_in_needs_rewind(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + struct cr_in_ctx *ctx = reader->ctx; (void)data; return ctx->has_used_cb; } @@ -689,7 +692,7 @@ static bool cr_in_needs_rewind(struct Curl_easy *data, static curl_off_t cr_in_total_length(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + struct cr_in_ctx *ctx = reader->ctx; (void)data; return ctx->total_len; } @@ -698,7 +701,7 @@ static CURLcode cr_in_resume_from(struct Curl_easy *data, struct Curl_creader *reader, curl_off_t offset) { - struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + struct cr_in_ctx *ctx = reader->ctx; int seekerr = CURL_SEEKFUNC_CANTSEEK; DEBUGASSERT(data->conn); @@ -760,7 +763,7 @@ static CURLcode cr_in_resume_from(struct Curl_easy *data, static CURLcode cr_in_rewind(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_in_ctx *ctx = (struct cr_in_ctx *)reader; + struct cr_in_ctx *ctx = reader->ctx; /* If we never invoked the callback, there is noting to rewind */ if(!ctx->has_used_cb) @@ -830,15 +833,18 @@ CURLcode Curl_creader_create(struct Curl_creader **preader, const struct Curl_crtype *crt, Curl_creader_phase phase) { - struct Curl_creader *reader; + struct Curl_creader *reader = NULL; CURLcode result = CURLE_OUT_OF_MEMORY; + void *p; DEBUGASSERT(crt->creader_size >= sizeof(struct Curl_creader)); - reader = (struct Curl_creader *) calloc(1, crt->creader_size); - if(!reader) + p = calloc(1, crt->creader_size); + if(!p) goto out; + reader = (struct Curl_creader *)p; reader->crt = crt; + reader->ctx = p; reader->phase = phase; result = crt->do_init(data, reader); @@ -866,7 +872,7 @@ struct cr_lc_ctx { static CURLcode cr_lc_init(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_lc_ctx *ctx = (struct cr_lc_ctx *)reader; + struct cr_lc_ctx *ctx = reader->ctx; (void)data; Curl_bufq_init2(&ctx->buf, (16 * 1024), 1, BUFQ_OPT_SOFT_LIMIT); return CURLE_OK; @@ -874,7 +880,7 @@ static CURLcode cr_lc_init(struct Curl_easy *data, struct Curl_creader *reader) static void cr_lc_close(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_lc_ctx *ctx = (struct cr_lc_ctx *)reader; + struct cr_lc_ctx *ctx = reader->ctx; (void)data; Curl_bufq_free(&ctx->buf); } @@ -885,7 +891,7 @@ static CURLcode cr_lc_read(struct Curl_easy *data, char *buf, size_t blen, size_t *pnread, bool *peos) { - struct cr_lc_ctx *ctx = (struct cr_lc_ctx *)reader; + struct cr_lc_ctx *ctx = reader->ctx; CURLcode result; size_t nread, i, start, n; bool eos; @@ -1024,7 +1030,7 @@ CURLcode Curl_creader_set_fread(struct Curl_easy *data, curl_off_t len) result = Curl_creader_create(&r, data, &cr_in, CURL_CR_CLIENT); if(result) return result; - ctx = (struct cr_in_ctx *)r; + ctx = r->ctx; ctx->total_len = len; cl_reset_reader(data); @@ -1161,7 +1167,7 @@ static CURLcode cr_buf_read(struct Curl_easy *data, char *buf, size_t blen, size_t *pnread, bool *peos) { - struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)reader; + struct cr_buf_ctx *ctx = reader->ctx; size_t nread = ctx->blen - ctx->index; (void)data; @@ -1183,7 +1189,7 @@ static CURLcode cr_buf_read(struct Curl_easy *data, static bool cr_buf_needs_rewind(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)reader; + struct cr_buf_ctx *ctx = reader->ctx; (void)data; return ctx->index > 0; } @@ -1191,7 +1197,7 @@ static bool cr_buf_needs_rewind(struct Curl_easy *data, static curl_off_t cr_buf_total_length(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)reader; + struct cr_buf_ctx *ctx = reader->ctx; (void)data; return (curl_off_t)ctx->blen; } @@ -1200,7 +1206,7 @@ static CURLcode cr_buf_resume_from(struct Curl_easy *data, struct Curl_creader *reader, curl_off_t offset) { - struct cr_buf_ctx *ctx = (struct cr_buf_ctx *)reader; + struct cr_buf_ctx *ctx = reader->ctx; size_t boffset; (void)data; @@ -1242,7 +1248,7 @@ CURLcode Curl_creader_set_buf(struct Curl_easy *data, result = Curl_creader_create(&r, data, &cr_buf, CURL_CR_CLIENT); if(result) return result; - ctx = (struct cr_buf_ctx *)r; + ctx = r->ctx; ctx->buf = buf; ctx->blen = blen; ctx->index = 0; diff --git a/lib/sendf.h b/lib/sendf.h index 2c5bc362086..a62cfe8c687 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -117,10 +117,16 @@ struct Curl_cwtype { size_t cwriter_size; /* sizeof() allocated struct Curl_cwriter */ }; -/* Client writer instance */ +/* Client writer instance, allocated on creation. + * `void *ctx` is the pointer from the allocation of + * the `struct Curl_cwriter` itself. This is suitable for "downcasting" + * by the writers implementation. See https://github.com/curl/curl/pull/13054 + * for the alignment problems that arise otherwise. + */ struct Curl_cwriter { const struct Curl_cwtype *cwt; /* type implementation */ struct Curl_cwriter *next; /* Downstream writer. */ + void *ctx; /* allocated instance pointer */ Curl_cwriter_phase phase; /* phase at which it operates */ }; @@ -214,10 +220,16 @@ typedef enum { CURL_CR_CLIENT /* data read from client */ } Curl_creader_phase; -/* Client reader instance */ +/* Client reader instance, allocated on creation. + * `void *ctx` is the pointer from the allocation of + * the `struct Curl_cwriter` itself. This is suitable for "downcasting" + * by the writers implementation. See https://github.com/curl/curl/pull/13054 + * for the alignment problems that arise otherwise. + */ struct Curl_creader { const struct Curl_crtype *crt; /* type implementation */ struct Curl_creader *next; /* Downstream reader. */ + void *ctx; Curl_creader_phase phase; /* phase at which it operates */ }; diff --git a/lib/smtp.c b/lib/smtp.c index 2d853600831..b32ef36e4b3 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -1786,7 +1786,7 @@ struct cr_eob_ctx { static CURLcode cr_eob_init(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_eob_ctx *ctx = (struct cr_eob_ctx *)reader; + struct cr_eob_ctx *ctx = reader->ctx; (void)data; /* The first char we read is the first on a line, as if we had * read CRLF just before */ @@ -1797,7 +1797,7 @@ static CURLcode cr_eob_init(struct Curl_easy *data, static void cr_eob_close(struct Curl_easy *data, struct Curl_creader *reader) { - struct cr_eob_ctx *ctx = (struct cr_eob_ctx *)reader; + struct cr_eob_ctx *ctx = reader->ctx; (void)data; Curl_bufq_free(&ctx->buf); } @@ -1812,7 +1812,7 @@ static CURLcode cr_eob_read(struct Curl_easy *data, char *buf, size_t blen, size_t *pnread, bool *peos) { - struct cr_eob_ctx *ctx = (struct cr_eob_ctx *)reader; + struct cr_eob_ctx *ctx = reader->ctx; CURLcode result = CURLE_OK; size_t nread, i, start, n; bool eos; diff --git a/lib/ws.c b/lib/ws.c index 37108946d41..263299761f8 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -363,7 +363,7 @@ struct ws_cw_ctx { static CURLcode ws_cw_init(struct Curl_easy *data, struct Curl_cwriter *writer) { - struct ws_cw_ctx *ctx = (struct ws_cw_ctx *)writer; + struct ws_cw_ctx *ctx = writer->ctx; (void)data; Curl_bufq_init2(&ctx->buf, WS_CHUNK_SIZE, 1, BUFQ_OPT_SOFT_LIMIT); return CURLE_OK; @@ -371,7 +371,7 @@ static CURLcode ws_cw_init(struct Curl_easy *data, static void ws_cw_close(struct Curl_easy *data, struct Curl_cwriter *writer) { - struct ws_cw_ctx *ctx = (struct ws_cw_ctx *)writer; + struct ws_cw_ctx *ctx = writer->ctx; (void) data; Curl_bufq_free(&ctx->buf); } @@ -423,7 +423,7 @@ static CURLcode ws_cw_write(struct Curl_easy *data, struct Curl_cwriter *writer, int type, const char *buf, size_t nbytes) { - struct ws_cw_ctx *ctx = (struct ws_cw_ctx *)writer; + struct ws_cw_ctx *ctx = writer->ctx; struct websocket *ws; CURLcode result; From f03c85635f35269f1f45b983bf216624f541760a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2024 17:22:17 +0100 Subject: [PATCH 431/509] docs: ascii version of manpage without nroff Create ASCII version of manpage without nroff - build src/tool_hugegelp.c from the ascii manpage - move the the manpage and the ascii version build to docs/cmdline-opts - remove all use of nroff from the build process - should make the build entirely reproducible (by avoiding nroff) - partly reverts 2620aa9 to build libcurl option man pages one by one in cmake because the appveyor builds got all crazy until I did The ASCII version of the manpage - is built with gen.pl, just like the manpage is - has a right-justified column making the appearance similar to the previous version - uses a 4-space indent per level (instead of the old version's 7) - does not do hyphenation of words (which nroff does) History We first made the curl build use nroff for building the hugehelp file in December 1998, for curl 5.2. Closes #13047 --- CMake/Macros.cmake | 29 --- CMakeLists.txt | 7 +- GIT-INFO | 10 +- Makefile.am | 2 +- configure.ac | 38 ---- docs/INTERNALS.md | 1 - docs/Makefile.am | 23 +-- docs/TODO | 9 - docs/cmdline-opts/CMakeLists.txt | 4 +- docs/cmdline-opts/Makefile.am | 20 ++- docs/cmdline-opts/_PROGRESS.md | 2 +- docs/cmdline-opts/gen.pl | 291 +++++++++++++++++++++++-------- docs/libcurl/CMakeLists.txt | 19 +- scripts/Makefile.am | 3 + scripts/cd2nroff | 2 +- src/CMakeLists.txt | 13 +- src/Makefile.am | 14 +- src/mkhelp.pl | 37 ---- tests/README.md | 1 - tests/data/test1140 | 2 +- tests/test1139.pl | 4 +- tests/test1140.pl | 4 +- 22 files changed, 279 insertions(+), 256 deletions(-) diff --git a/CMake/Macros.cmake b/CMake/Macros.cmake index 9ff62ea7295..d5439fcc04c 100644 --- a/CMake/Macros.cmake +++ b/CMake/Macros.cmake @@ -68,35 +68,6 @@ macro(curl_internal_test CURL_TEST) 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/CMakeLists.txt b/CMakeLists.txt index 0c5c039e7c6..083f2c5e413 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -312,13 +312,10 @@ option(ENABLE_CURL_MANUAL "to build the man page for curl and enable its -M/--ma if(ENABLE_CURL_MANUAL OR BUILD_LIBCURL_DOCS) if(PERL_FOUND) - curl_nroff_check() - if(NROFF_USEFUL) - set(HAVE_MANUAL_TOOLS ON) - endif() + set(HAVE_MANUAL_TOOLS ON) endif() if(NOT HAVE_MANUAL_TOOLS) - message(WARNING "Perl not found, or nroff not useful. Will not build manuals.") + message(WARNING "Perl not found. Will not build manuals.") endif() endif() diff --git a/GIT-INFO b/GIT-INFO index 62efbd938c0..6e2bfad5cff 100644 --- a/GIT-INFO +++ b/GIT-INFO @@ -36,9 +36,9 @@ following software installed: o libtool 1.4.2 (or later) o GNU m4 (required by autoconf) - o nroff + perl + o 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. + 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 5bb0e254822..658189e4702 100644 --- a/Makefile.am +++ b/Makefile.am @@ -134,7 +134,7 @@ CLEANFILES = $(VC14_LIBVCXPROJ) $(VC14_SRCVCXPROJ) \ bin_SCRIPTS = curl-config -SUBDIRS = lib src scripts +SUBDIRS = lib docs src scripts DIST_SUBDIRS = $(SUBDIRS) tests packages scripts include docs pkgconfigdir = $(libdir)/pkgconfig diff --git a/configure.ac b/configure.ac index c1877771927..49371a755e8 100644 --- a/configure.ac +++ b/configure.ac @@ -3826,10 +3826,6 @@ 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) @@ -3844,40 +3840,6 @@ fi dnl set variable for use in automakefile(s) AM_CONDITIONAL(BUILD_DOCS, test x"$BUILD_DOCS" = x1) -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) -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 ************************************************************************* dnl If the manual variable still is set, then we go with providing a built-in dnl manual 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/Makefile.am b/docs/Makefile.am index b79ad24731f..b3a098114f2 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -30,16 +30,14 @@ MK_CA_DOCS = mk-ca-bundle.1 CURLCONF_DOCS = curl-config.1 endif -man_MANS = $(abs_builddir)/curl.1 curl-config.1 +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 libcurl DIST_SUBDIRS = $(SUBDIRS) examples if BUILD_DOCS -CLEANFILES = curl.1 mk-ca-bundle.1 curl-config.1 +CLEANFILES = mk-ca-bundle.1 curl-config.1 endif EXTRA_DIST = \ @@ -112,20 +110,6 @@ SUFFIXES = .1 .md all: $(MK_CA_DOCS) -# $(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) - .md.1: $(CD2)$(CD2NROFF) @@ -135,6 +119,3 @@ mk-ca-bundle.1: mk-ca-bundle.md distclean: rm -f $(CLEANFILES) - -dist-hook: - cp $(builddir)/curl.1 $(builddir)/curl.1.dist diff --git a/docs/TODO b/docs/TODO index 49242227cf1..c82c78a537d 100644 --- a/docs/TODO +++ b/docs/TODO @@ -177,7 +177,6 @@ 18.29 --retry and transfer timeouts 19. Build - 19.1 avoid nroff 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 @@ -1291,14 +1290,6 @@ 19. Build -19.1 avoid nroff - - With the switch to the markdown-like documentation format since curl 8.6.0, - it should (with a manageable amount of work) be possible to render an ASCII - version of the man page without involving nroff and thus remove that - dependency for building the hugehelp file, used to build in the man page into - the curl command line tool. - 19.2 Enable PIE and RELRO by default Especially when having programs that execute curl via the command line, PIE diff --git a/docs/cmdline-opts/CMakeLists.txt b/docs/cmdline-opts/CMakeLists.txt index ee158df993a..6a3a1c5f6d2 100644 --- a/docs/cmdline-opts/CMakeLists.txt +++ b/docs/cmdline-opts/CMakeLists.txt @@ -21,7 +21,8 @@ # 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") @@ -29,6 +30,7 @@ include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") add_custom_command(OUTPUT "${MANPAGE}" COMMAND cd ${CMAKE_CURRENT_SOURCE_DIR} && "${PERL_EXECUTABLE}" "./gen.pl" mainpage ${DPAGES} > "${MANPAGE}" + COMMAND cd ${CMAKE_CURRENT_SOURCE_DIR} && "${PERL_EXECUTABLE}" "./gen.pl" ascii ${DPAGES} > "${ASCIIPAGE}" VERBATIM ) add_custom_target(generate-curl.1 ALL DEPENDS "${MANPAGE}") diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index 08d19a01522..476c932f22d 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -24,7 +24,10 @@ AUTOMAKE_OPTIONS = foreign no-dependencies -MANPAGE = $(top_builddir)/docs/curl.1 +MANPAGE = curl.1 +ASCIIPAGE = curl.txt + +man_MANS = $(MANPAGE) include Makefile.inc @@ -35,10 +38,21 @@ GN_0 = @echo " GENERATE" $@; GN_1 = GN_ = $(GN_0) -all: $(MANPAGE) +if BUILD_DOCS +CLEANFILES = $(MANPAGE) $(ASCIIPAGE) + +all: $(MANPAGE) $(ASCIIPAGE) + +endif $(MANPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl - $(GEN)(rm -f $(MANPAGE) && cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES) > $(builddir)/manpage.tmp.$$$$ && mv $(builddir)/manpage.tmp.$$$$ $(MANPAGE)) + $(GEN)(rm -f $(MANPAGE) && (cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES)) > manpage.tmp.$$$$ && mv manpage.tmp.$$$$ $(MANPAGE)) + +$(ASCIIPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl + $(GEN)(rm -f $(ASCIIPAGE) && (cd $(srcdir) && @PERL@ ./gen.pl ascii $(DPAGES)) > asciipage.tmp.$$$$ && mv asciipage.tmp.$$$$ $(ASCIIPAGE)) listhelp: ./gen.pl listhelp $(DPAGES) > $(top_builddir)/src/tool_listhelp.c + +dist-hook: $(MANPAGE) + cp $(MANPAGE) $(MANPAGE).dist diff --git a/docs/cmdline-opts/_PROGRESS.md b/docs/cmdline-opts/_PROGRESS.md index 2775ec20065..4cbbd8eb780 100644 --- a/docs/cmdline-opts/_PROGRESS.md +++ b/docs/cmdline-opts/_PROGRESS.md @@ -1,6 +1,6 @@ -# "PROGRESS METER" +# PROGRESS METER curl normally displays a progress meter during operations, indicating the amount of transferred data, transfer speeds and estimated time left, etc. The diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index e7b621b2dc2..eeaabd2ecdc 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -93,11 +93,115 @@ sub manpageify { return $l; } + +my $colwidth=78; # max number of columns + +sub justline { + my ($lvl, @line) = @_; + my $w = -1; + my $spaces = -1; + my $width = $colwidth - ($lvl * 4); + for(@line) { + $w += length($_); + $w++; + $spaces++; + } + my $inject = $width - $w; + my $ratio = 0; # stay at zero if no spaces at all + if($spaces) { + $ratio = $inject / $spaces; + } + my $spare = 0; + print ' ' x ($lvl * 4); + my $prev; + for(@line) { + while($spare >= 0.90) { + print " "; + $spare--; + } + printf "%s%s", $prev?" ":"", $_; + $prev = 1; + $spare += $ratio; + } + print "\n"; +} + +sub lastline { + my ($lvl, @line) = @_; + print ' ' x ($lvl * 4); + my $prev = 0; + for(@line) { + printf "%s%s", $prev?" ":"", $_; + $prev = 1; + } + print "\n"; +} + +sub outputpara { + my ($lvl, $f) = @_; + $f =~ s/\n/ /g; + + my $w = 0; + my @words = split(/ */, $f); + my $width = $colwidth - ($lvl * 4); + + my @line; + for my $e (@words) { + my $l = length($e); + my $spaces = scalar(@line); + if(($w + $l + $spaces) >= $width) { + justline($lvl, @line); + undef @line; + $w = 0; + } + + push @line, $e; + $w += $l; # new width + } + if($w) { + lastline($lvl, @line); + print "\n"; + } +} + sub printdesc { - my @desc = @_; - my $exam = 0; - for my $d (@desc) { - print $d; + my ($manpage, $baselvl, @desc) = @_; + + if($manpage) { + for my $d (@desc) { + print $d; + } + } + else { + my $p = -1; + my $para; + for my $l (@desc) { + my $lvl; + if($l !~ /^[\n\r]+/) { + # get the indent level off the string + $l =~ s/^\[([0-9q]*)\]//; + $lvl = $1; + } + if(($p =~ /q/) && ($lvl !~ /q/)) { + # the previous was quoted, this is not + print "\n"; + } + if($lvl != $p) { + outputpara($baselvl + $p, $para); + $para = ""; + } + if($lvl =~ /q/) { + # quoted, do not right-justify + chomp $l; + lastline($baselvl + $lvl + 1, $l); + } + else { + $para .= $l; + } + + $p = $lvl; + } + outputpara($baselvl + $p, $para); } } @@ -123,12 +227,13 @@ sub overrides { } sub protocols { - my ($standalone, $data)=@_; + my ($manpage, $standalone, $data)=@_; if($standalone) { return ".SH \"PROTOCOLS\"\n$data\n"; } else { - return "($data) "; + return " ($data) " if($manpage); + return "[1]($data) " if(!$manpage); } } @@ -164,13 +269,14 @@ sub added { } sub render { - my ($fh, $f, $line) = @_; + my ($manpage, $fh, $f, $line) = @_; my @desc; my $tablemode = 0; my $header = 0; # if $top is TRUE, it means a top-level page and not a command line option my $top = ($line == 1); my $quote; + my $level; $start = 0; while(<$fh>) { @@ -196,7 +302,8 @@ sub render { $blankline++; next; } - push @desc, ".SH $1\n"; + push @desc, ".SH $1\n" if($manpage); + push @desc, "[0]$1\n" if(!$manpage); next; } elsif(/^###/) { @@ -211,19 +318,24 @@ sub render { # remove backticks from headers $words =~ s/\`//g; - # if there is a space, it needs quotes - if($word =~ / /) { + # if there is a space, it needs quotes for man page + if(($word =~ / /) && $manpage) { $word = "\"$word\""; } + $level = 1; if($top == 1) { - push @desc, ".IP $word\n"; + push @desc, ".IP $word\n" if($manpage); + push @desc, "\n" if(!$manpage); + push @desc, "[1]$word\n" if(!$manpage); } else { if(!$tablemode) { - push @desc, ".RS\n"; + push @desc, ".RS\n" if($manpage); $tablemode = 1; } - push @desc, ".IP $word\n"; + push @desc, ".IP $word\n" if($manpage); + push @desc, "\n" if(!$manpage); + push @desc, "[1]$word\n" if(!$manpage); } $header = 1; next; @@ -236,7 +348,7 @@ sub render { if($tablemode) { # end of table push @desc, ".RE\n.IP\n"; - $tablmode = 0; + $tablemode = 0; } $header = 1; next; @@ -253,7 +365,7 @@ sub render { } elsif($d =~ /^ (.*)/) { my $word = $1; - if(!$quote) { + if(!$quote && $manpage) { push @desc, ".nf\n"; } $quote = 1; @@ -261,7 +373,7 @@ sub render { } elsif($quote && ($d !~ /^ (.*)/)) { # end of quote - push @desc, ".fi\n"; + push @desc, ".fi\n" if($manpage); $quote = 0; } @@ -293,40 +405,50 @@ sub render { # convert backslash-'<' or '> to just the second character $d =~ s/\\([><])/$1/g; # convert single backslash to double-backslash - $d =~ s/\\/\\\\/g; + $d =~ s/\\/\\\\/g if($manpage); - if(!$quote && $d =~ /--/) { - $d =~ s/--([a-z0-9.-]+)/manpageify($1)/ge; - } - # quote minuses in the output - $d =~ s/([^\\])-/$1\\-/g; - # replace single quotes - $d =~ s/\'/\\(aq/g; - # handle double quotes or periods first on the line - $d =~ s/^([\.\"])/\\&$1/; - # **bold** - $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g; - # *italics* - $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g; + if($manpage) { + if(!$quote && $d =~ /--/) { + $d =~ s/--([a-z0-9.-]+)/manpageify($1)/ge; + } + # quote minuses in the output + $d =~ s/([^\\])-/$1\\-/g; + # replace single quotes + $d =~ s/\'/\\(aq/g; + # handle double quotes or periods first on the line + $d =~ s/^([\.\"])/\\&$1/; + # **bold** + $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g; + # *italics* + $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g; + } + else { + # **bold** + $d =~ s/\*\*(\S.*?)\*\*/$1/g; + # *italics* + $d =~ s/\*(\S.*?)\*/$1/g; + } # trim trailing spaces $d =~ s/[ \t]+\z//; push @desc, "\n" if($blankline && !$header); $blankline = 0; - push @desc, $d; + push @desc, $d if($manpage); + my $qstr = $quote ? "q": ""; + push @desc, "[".(1 + $level)."$qstr]$d" if(!$manpage); $header = 0; } if($tablemode) { # end of table - push @desc, ".RE\n.IP\n"; + push @desc, ".RE\n.IP\n" if($manpage); } return @desc; } sub single { - my ($f, $standalone)=@_; + my ($manpage, $f, $standalone)=@_; my $fh; open($fh, "<:crlf", "$f") || return 1; @@ -476,7 +598,7 @@ sub single { return 2; } - my @desc = render($fh, $f, $line); + my @desc = render($manpage, $fh, $f, $line); close($fh); if($tablemode) { # end of table @@ -499,17 +621,21 @@ sub single { } # quote "bare" minuses in opt - $opt =~ s/-/\\-/g; + $opt =~ s/-/\\-/g if($manpage); 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 { + elsif($manpage) { print ".IP \"$opt\"\n"; } + else { + lastline(1, $opt); + } + my @leading; if($protocols) { - print protocols($standalone, $protocols); + push @leading, protocols($manpage, $standalone, $protocols); } if($standalone) { @@ -517,15 +643,15 @@ sub single { } if($experimental) { - print "**WARNING**: this option is experimental. Do not use in production.\n\n"; + push @leading, "**WARNING**: this option is experimental. Do not use in production.\n\n"; } - printdesc(@desc); - undef @desc; + my $pre = $manpage ? "\n": "[1]"; if($scope) { if($scope eq "global") { - print "\nThis option is global and does not need to be specified for each use of --next.\n"; + push @desc, "\n" if(!$manpage); + push @desc, "${pre}This 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"; @@ -533,13 +659,16 @@ sub single { } } + printdesc($manpage, 2, (@leading, @desc)); + undef @desc; + my @extra; if($multi eq "single") { - push @extra, "\nIf --$long is provided several times, the last set ". + push @extra, "${pre}If --$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"; + push @extra, "${pre}--$long can be used several times in a command line\n"; } elsif($multi eq "boolean") { my $rev = "no-$long"; @@ -549,13 +678,14 @@ sub single { $rev = $long; $rev =~ s/^no-//; } + my $dashes = $manpage ? "\\-\\-" : "--"; push @extra, - "\nProviding --$long multiple times has no extra effect.\n". - "Disable it again with \\-\\-$rev.\n"; + "${pre}Providing --$long multiple times has no extra effect.\n". + "Disable it again with $dashes$rev.\n"; } elsif($multi eq "mutex") { push @extra, - "\nProviding --$long multiple times has no extra effect.\n"; + "${pre}Providing --$long multiple times has no extra effect.\n"; } elsif($multi eq "custom") { ; # left for the text to describe @@ -565,7 +695,7 @@ sub single { return 2; } - printdesc(@extra); + printdesc($manpage, 2, @extra); my @foot; @@ -581,7 +711,7 @@ sub single { if(!$helplong{$k}) { print STDERR "$f:$line:1:WARN: see-also a non-existing option: $k\n"; } - my $l = manpageify($k); + my $l = $manpage ? manpageify($k) : "--$k"; my $sep = " and"; if($and && ($i < $and)) { $sep = ","; @@ -592,7 +722,7 @@ sub single { push @foot, seealso($standalone, $mstr); if($requires) { - my $l = manpageify($long); + my $l = $manpage ? manpageify($long) : "--$long"; push @foot, "$l requires that the underlying libcurl". " was built to support $requires. "; } @@ -603,7 +733,7 @@ sub single { if(!$helplong{$k}) { print STDERR "WARN: $f mutexes a non-existing option: $k\n"; } - my $l = manpageify($k); + my $l = $manpage ? manpageify($k) : "--$k"; $mstr .= sprintf "%s$l", $mstr?" and ":""; } push @foot, overrides($standalone, @@ -612,16 +742,26 @@ sub single { 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; - # convert single backslahes to doubles - $e =~ s/\\/\\\\/g; - print " curl $e\n"; + if($manpage) { + print "\nExample$s:\n"; + print ".nf\n"; + foreach my $e (@examples) { + $e =~ s!\$URL!https://example.com!g; + # convert single backslahes to doubles + $e =~ s/\\/\\\\/g; + print " curl $e\n"; + } + print ".fi\n"; + } + else { + my @ex; + push @ex, "[0q]Example$s:\n"; + foreach my $e (@examples) { + $e =~ s!\$URL!https://example.com!g; + push @ex, "[0q] curl $e\n"; + } + printdesc($manpage, 2, @ex); } - print ".fi\n"; } if($added) { push @foot, added($standalone, $added); @@ -629,8 +769,13 @@ sub single { if($foot[0]) { print "\n"; my $f = join("", @foot); - $f =~ s/ +\z//; # remove trailing space - print "$f\n"; + if($manpage) { + $f =~ s/ +\z//; # remove trailing space + print "$f\n"; + } + else { + printdesc($manpage, 2, "[1]$f"); + } } return 0; } @@ -695,12 +840,12 @@ sub indexoptions { } sub header { - my ($f)=@_; + my ($manpage, $f)=@_; my $fh; open($fh, "<:crlf", "$f"); - my @d = render($fh, $f, 1); + my @d = render($manpage, $fh, $f, 1); close($fh); - printdesc(@d); + printdesc($manpage, 0, @d); } sub listhelp { @@ -854,7 +999,8 @@ sub sortnames { } sub mainpage { - my (@files) = @_; + my ($manpage, @files) = @_; + # $manpage is 1 for nroff, 0 for ASCII my $ret; my $fh; open($fh, "<:crlf", "mainpage.idx") || @@ -889,7 +1035,7 @@ sub mainpage { .\\" .TH curl 1 "$date" "curl $version" "curl Manual" HEADER - ; + if ($manpage); while(<$fh>) { my $f = $_; @@ -901,12 +1047,12 @@ sub mainpage { if(/^%options/) { # output docs for all options foreach my $f (sort sortnames @files) { - $ret += single($f, 0); + $ret += single($manpage, $f, 0); } } else { # render the file - header($f); + header($manpage, $f); } } close($fh); @@ -937,7 +1083,12 @@ sub getargs { my ($f, @s) = @_; if($f eq "mainpage") { listglobals(@s); - mainpage(@s); + mainpage(1, @s); + return; + } + elsif($f eq "ascii") { + listglobals(@s); + mainpage(0, @s); return; } elsif($f eq "listhelp") { @@ -957,7 +1108,7 @@ sub getargs { return; } - print "Usage: gen.pl [files]\n"; + print "Usage: gen.pl [files]\n"; } #------------------------------------------------------------------------ diff --git a/docs/libcurl/CMakeLists.txt b/docs/libcurl/CMakeLists.txt index 0bc35fc9732..2aa051edd7d 100644 --- a/docs/libcurl/CMakeLists.txt +++ b/docs/libcurl/CMakeLists.txt @@ -26,26 +26,21 @@ transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc. include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") function(add_manual_pages _listname) - unset(_rofffiles) - unset(_mdfiles) foreach(_file IN LISTS ${_listname}) - list(APPEND _rofffiles "${CMAKE_CURRENT_BINARY_DIR}/${_file}") + set(_rofffile "${CMAKE_CURRENT_BINARY_DIR}/${_file}") if(_file STREQUAL "libcurl-symbols.3") # Special case, an auto-generated file. string(REPLACE ".3" ".md" _mdfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}") else() - string(REPLACE ".3" ".md" _mdfile "${_file}") + string(REPLACE ".3" ".md" _mdfile "${CMAKE_CURRENT_SOURCE_DIR}/${_file}") endif() - list(APPEND _mdfiles "${_mdfile}") + add_custom_command(OUTPUT "${_rofffile}" + COMMAND "${PERL_EXECUTABLE}" ${PROJECT_SOURCE_DIR}/scripts/cd2nroff ${_mdfile} > ${_rofffile} + DEPENDS "${_mdfile}" + VERBATIM + ) endforeach() - add_custom_command(OUTPUT ${_rofffiles} - WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} - COMMAND ${PROJECT_SOURCE_DIR}/scripts/cd2nroff -k -d "${CMAKE_CURRENT_BINARY_DIR}" ${_mdfiles} - DEPENDS ${_mdfiles} - VERBATIM - ) - endfunction() add_custom_command(OUTPUT libcurl-symbols.md diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 4a30d41755d..2d136d8ed37 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -77,3 +77,6 @@ if USE_FISH_COMPLETION fi endif endif + +distclean: + rm -f $(CLEANFILES) diff --git a/scripts/cd2nroff b/scripts/cd2nroff index 96d2a367d6f..5d699ca0fff 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -113,7 +113,7 @@ sub single { if(defined($f)) { if(!open($fh, "<:crlf", "$f")) { - print STDERR "Failed to open $f : $!\n"; + print STDERR "cd2nroff failed to open '$f' for reading: $!\n"; return 1; } } diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 5695670f075..cd1e9be446e 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -26,23 +26,18 @@ add_definitions(-DBUILDING_CURL) if(ENABLE_CURL_MANUAL AND HAVE_MANUAL_TOOLS) add_definitions("-DUSE_MANUAL") - # Use the C locale to ensure that only ASCII characters appear in the - # embedded text. NROFF and MANOPT are set in the parent CMakeLists.txt add_custom_command( OUTPUT tool_hugehelp.c COMMAND ${CMAKE_COMMAND} -E echo "#include \"tool_setup.h\"" > tool_hugehelp.c COMMAND ${CMAKE_COMMAND} -E echo "#ifndef HAVE_LIBZ" >> tool_hugehelp.c - COMMAND env LC_ALL=C "${NROFF}" ${NROFF_MANOPT} - "${CURL_BINARY_DIR}/docs/curl.1" | - "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" >> tool_hugehelp.c + COMMAND "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" < "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.txt" >> tool_hugehelp.c + COMMAND ${CMAKE_COMMAND} -E echo "#else" >> tool_hugehelp.c - COMMAND env LC_ALL=C "${NROFF}" ${NROFF_MANOPT} - "${CURL_BINARY_DIR}/docs/curl.1" | - "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" -c >> tool_hugehelp.c + COMMAND "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" -c < "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.txt" >> tool_hugehelp.c COMMAND ${CMAKE_COMMAND} -E echo "#endif /* HAVE_LIBZ */" >> tool_hugehelp.c DEPENDS generate-curl.1 - "${CURL_BINARY_DIR}/docs/curl.1" + "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.1" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" "${CMAKE_CURRENT_SOURCE_DIR}/tool_hugehelp.h" VERBATIM) diff --git a/src/Makefile.am b/src/Makefile.am index 713dacf130f..fcc9cfdf942 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -96,7 +96,7 @@ EXTRA_DIST = mkhelp.pl \ Makefile.mk curl.rc Makefile.inc CMakeLists.txt .checksrc # Use absolute directory to disable VPATH -MANPAGE=$(abs_top_builddir)/docs/curl.1 +ASCIIPAGE=$(abs_top_builddir)/docs/cmdline-opts/curl.txt MKHELP=$(top_srcdir)/src/mkhelp.pl HUGE=tool_hugehelp.c @@ -113,24 +113,24 @@ CS_ = $(CS_0) if USE_MANUAL # Here are the stuff to create a built-in manual -$(MANPAGE): +$(ASCIIPAGE): cd $(top_builddir)/docs && $(MAKE) if HAVE_LIBZ # This generates the tool_hugehelp.c file in both uncompressed and # compressed formats. -$(HUGE): $(MANPAGE) $(MKHELP) +$(HUGE): $(ASCIIPAGE) $(MKHELP) $(HUGECMD) (echo '#include "tool_setup.h"' > $(HUGE); \ echo '#ifndef HAVE_LIBZ' >> $(HUGE); \ - $(NROFF) $(MANPAGE) | $(PERL) $(MKHELP) >> $(HUGE); \ + $(PERL) $(MKHELP) < $(ASCIIPAGE) >> $(HUGE); \ echo '#else' >> $(HUGE); \ - $(NROFF) $(MANPAGE) | $(PERL) $(MKHELP) -c >> $(HUGE); \ + $(PERL) $(MKHELP) -c < $(ASCIIPAGE) >> $(HUGE); \ echo '#endif /* HAVE_LIBZ */' >> $(HUGE) ) else # HAVE_LIBZ # This generates the tool_hugehelp.c file uncompressed only -$(HUGE): $(MANPAGE) $(MKHELP) +$(HUGE): $(ASCIIPAGE) $(MKHELP) $(HUGECMD)(echo '#include "tool_setup.h"' > $(HUGE); \ - $(NROFF) $(MANPAGE) | $(PERL) $(MKHELP) >> $(HUGE) ) + $(PERL) $(MKHELP) < $(ASCIIPAGE) >> $(HUGE) ) endif else # USE_MANUAL diff --git a/src/mkhelp.pl b/src/mkhelp.pl index 91551cfb4da..5429160716f 100755 --- a/src/mkhelp.pl +++ b/src/mkhelp.pl @@ -44,45 +44,8 @@ my $olen=0; while () { my $line = $_; - - # this should be removed: - $line =~ s/(.|_)//g; - - # remove trailing CR from line. msysgit checks out files as line+CRLF - $line =~ s/\r$//; - - $line =~ s/\x1b\x5b[0-9]+m//g; # escape sequence - if($line =~ /^([ \t]*\n|curl)/i) { - # cut off headers and empty lines - $wline++; # count number of cut off lines - next; - } - - my $text = $line; - $text =~ s/^\s+//g; # cut off preceding... - $text =~ s/\s+$//g; # and trailing whitespaces - - $tlen = length($text); - - if($wline && ($olen == $tlen)) { - # if the previous line with contents was exactly as long as - # this line, then we ignore the newlines! - - # We do this magic because a header may abort a paragraph at - # any line, but we don't want that to be noticed in the output - # here - $wline=0; - } - $olen = $tlen; - - if($wline) { - # we only make one empty line max - $wline = 0; - push @out, "\n"; - } push @out, $line; } -push @out, "\n"; # just an extra newline print < -Verify the nroff of man pages +Verify the nroff of manpages diff --git a/tests/test1139.pl b/tests/test1139.pl index c86081431b5..2c56c3a7268 100755 --- a/tests/test1139.pl +++ b/tests/test1139.pl @@ -220,8 +220,8 @@ sub scanmanpage { ######################################################################### # parse the curl.1 man page, extract all documented command line options # The man page may or may not be rebuilt, so check both possible locations -open($r, "<", "$buildroot/docs/curl.1") || open($r, "<", "$root/docs/curl.1") || - die "no input file"; +open($r, "<", "$buildroot/docs/cmdline-opts/curl.1") || open($r, "<", "$root/docs/cmdline-opts/curl.1") || + die "failed getting curl.1"; my @manpage; # store all parsed parameters while(<$r>) { chomp; diff --git a/tests/test1140.pl b/tests/test1140.pl index b9438dec0cb..6ad346ea671 100755 --- a/tests/test1140.pl +++ b/tests/test1140.pl @@ -23,13 +23,13 @@ # ########################################################################### # -# scan nroff pages to find basic syntactic problems such as unbalanced \f +# scan manpages to find basic syntactic problems such as unbalanced \f # codes or references to non-existing curl man pages. my $docsroot = $ARGV[0]; if(!$docsroot || ($docsroot eq "-g")) { - print "Usage: nroff-scan.pl [nroff files]\n"; + print "Usage: test1140.pl [manpages]\n"; exit; } From 62c08d5d4a14578ce29684104160e643f64480b4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Mar 2024 17:32:00 +0100 Subject: [PATCH 432/509] mkhelp: simplify the generated hugehelp program Use a plain array and puts() every line, also allows us to provide the strings without ending newlines. - merge blank lines into the next one as a prefixed newline. - turn eight consecutive spaces into a tab (since they can only be on the left side of text) - the newly generated tool_hugehelp is 3K lines shorter and 50K smaller - modifies the top logo layout a little by reducing the indent Closes #13047 --- src/mkhelp.pl | 59 +++++++++++++++++++++++++++------------------------ 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/src/mkhelp.pl b/src/mkhelp.pl index 5429160716f..f1e1de1c665 100755 --- a/src/mkhelp.pl +++ b/src/mkhelp.pl @@ -35,11 +35,11 @@ shift @ARGV; } -push @out, " _ _ ____ _\n"; -push @out, " Project ___| | | | _ \\| |\n"; -push @out, " / __| | | | |_) | |\n"; -push @out, " | (__| |_| | _ <| |___\n"; -push @out, " \\___|\\___/|_| \\_\\_____|\n"; +push @out, " _ _ ____ _\n"; +push @out, " ___| | | | _ \\| |\n"; +push @out, " / __| | | | |_) | |\n"; +push @out, " | (__| |_| | _ <| |___\n"; +push @out, " \\___|\\___/|_| \\_\\_____|\n"; my $olen=0; while () { @@ -157,40 +157,43 @@ } else { print < 500) { - # terminate and make another fputs() call here - print ", stdout);\n fputs(\n"; - $outsize=length($new)+1; + if(!$n) { + $blank++; + } + else { + $n =~ s/ /\\t/g; + printf(" \"%s%s\",\n", $blank?"\\n":"", $n); + $blank = 0; } - printf("\"%s\\n\"\n", $new); - } -print ", stdout) ;\n}\n"; +print < Date: Sat, 2 Mar 2024 17:44:33 -0500 Subject: [PATCH 433/509] trace-config.md: remove the mutexed options list - Remove the rendered manpage message that says: "[--trace-config] is mutually exclusive to --trace and -v, --verbose". Actually it can be used with either of those options, which are mutually exclusive to each other but not to --trace-config. Ref: https://curl.se/docs/manpage.html#--trace-config Closes https://github.com/curl/curl/pull/13031 --- docs/cmdline-opts/trace-config.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/cmdline-opts/trace-config.md b/docs/cmdline-opts/trace-config.md index 0ab7dbe7202..d7c7e0daa42 100644 --- a/docs/cmdline-opts/trace-config.md +++ b/docs/cmdline-opts/trace-config.md @@ -4,7 +4,6 @@ SPDX-License-Identifier: curl Long: trace-config Arg: Help: Details to log in trace/verbose output -Mutexed: trace verbose Category: verbose Added: 8.3.0 Multi: append From 2ea178ace71e6747e7c2af1e1251440afc0294a8 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Sun, 3 Mar 2024 02:15:24 -0500 Subject: [PATCH 434/509] KNOWN_BUGS: FTPS server compatibility on Windows with Schannel - Remove "2.12 FTPS with Schannel times out file list operation" - Remove "7.12 FTPS directory listing hangs on Windows with Schannel" - Add "7.12 FTPS server compatibility on Windows with Schannel" This change adds a more generic bug description that explains FTPS with the latest curl and Schannel is not widely used and may have more bugs than other TLS backends. The two removed FTPS Schannel bugs can't be reproduced any longer and were likely fixed by 24d6c288. Ref: https://github.com/curl/curl/issues/5284 Ref: https://github.com/curl/curl/issues/9161 Ref: https://github.com/curl/curl/issues/12894 Closes https://github.com/curl/curl/pull/13032 --- docs/KNOWN_BUGS | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index a1cc620c159..eab7e638975 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -22,7 +22,6 @@ problems may have been fixed or changed somewhat since this was written. 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 @@ -171,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 @@ -431,9 +424,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 + + 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. - https://github.com/curl/curl/issues/9161 + 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 From ed97fe06acb27f66b6b8eff1f9669166e0bb9f50 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Wed, 6 Mar 2024 11:43:40 +0000 Subject: [PATCH 435/509] cmake: fix `CURL_WINDOWS_SSPI=ON` with Schannel disabled Prior to this change `CURL_WINDOWS_SSPI` was accidentally forced `OFF` when building without the Schannel TLS backend. This in turn may have caused Kerberos, SPNEGO and SSPI features disappearing even with `CURL_WINDOWS_SSPI=ON` set. This patch fixes it by using the `CURL_USE_SCHANNEL` setting as a default for `CURL_WINDOWS_SSPI`, but allowing a manual override. Also update the option text to better tell its purpose. Thanks-to: Andreas Loew Reviewed-by: Daniel Stenberg Ref: #13056 Closes #13061 --- CMakeLists.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 083f2c5e413..40c0f776510 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -393,8 +393,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) From 923f7f8ce51b7f2f20282883cdafeb283310f3d9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Mar 2024 15:39:09 +0100 Subject: [PATCH 436/509] paramhlp: fix CRLF-stripping files with "-d @file" All CR and LF bytes should be stripped, as documented, and all other bytes are inluded in the data. Starting now, it also excludes null bytes as they would otherwise also cut the data short. Reported-by: Simon K Fixes #13063 Closes #13064 --- docs/cmdline-opts/data.md | 4 +-- src/tool_paramhlp.c | 63 +++++++++++++++++++++++++++++++-------- 2 files changed, 53 insertions(+), 14 deletions(-) diff --git a/docs/cmdline-opts/data.md b/docs/cmdline-opts/data.md index 71dd36e046c..ebe2347d868 100644 --- a/docs/cmdline-opts/data.md +++ b/docs/cmdline-opts/data.md @@ -40,8 +40,8 @@ data pieces specified are merged with a separating &-symbol. Thus, using 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 and newlines are -stripped out. If you do not want the @ character to have a special +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 diff --git a/src/tool_paramhlp.c b/src/tool_paramhlp.c index 2725815000d..c26f6bbefd7 100644 --- a/src/tool_paramhlp.c +++ b/src/tool_paramhlp.c @@ -63,6 +63,33 @@ struct getout *new_getout(struct OperationConfig *config) return node; } +#define ISCRLF(x) (((x) == '\r') || ((x) == '\n') || ((x) == '\0')) + +/* memcrlf() has two modes. Both operate on a given memory area with + a specified size. + + countcrlf FALSE - return number of bytes from the start that DO NOT include + any CR or LF or NULL + + countcrlf TRUE - return number of bytes from the start that are ONLY CR or + LF or NULL. + +*/ +static size_t memcrlf(char *orig, + bool countcrlf, /* TRUE if we count CRLF, FALSE + if we count non-CRLF */ + size_t max) +{ + char *ptr = orig; + size_t total = max; + for(ptr = orig; max; max--, ptr++) { + bool crlf = ISCRLF(*ptr); + if(countcrlf ^ crlf) + return ptr - orig; + } + return total; /* no delimiter found */ +} + #define MAX_FILE2STRING (256*1024*1024) /* big enough ? */ ParameterError file2string(char **bufp, FILE *file) @@ -71,18 +98,30 @@ ParameterError file2string(char **bufp, FILE *file) DEBUGASSERT(MAX_FILE2STRING < INT_MAX); /* needs to fit in an int later */ curlx_dyn_init(&dyn, MAX_FILE2STRING); if(file) { - char buffer[256]; - - while(fgets(buffer, sizeof(buffer), file)) { - char *ptr = strchr(buffer, '\r'); - if(ptr) - *ptr = '\0'; - ptr = strchr(buffer, '\n'); - if(ptr) - *ptr = '\0'; - if(curlx_dyn_add(&dyn, buffer)) - return PARAM_NO_MEM; - } + do { + char buffer[4096]; + char *ptr; + size_t nread = fread(buffer, 1, sizeof(buffer), file); + if(ferror(file)) { + curlx_dyn_free(&dyn); + *bufp = NULL; + return PARAM_READ_ERROR; + } + ptr = buffer; + while(nread) { + size_t nlen = memcrlf(ptr, FALSE, nread); + if(curlx_dyn_addn(&dyn, ptr, nlen)) + return PARAM_NO_MEM; + nread -= nlen; + + if(nread) { + ptr += nlen; + nlen = memcrlf(ptr, TRUE, nread); + ptr += nlen; + nread -= nlen; + } + } + } while(!feof(file)); } *bufp = curlx_dyn_ptr(&dyn); return PARAM_OK; From 6a13d4d75c409120aa48af52fc730615835fcd66 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Mar 2024 22:44:41 +0100 Subject: [PATCH 437/509] test463: HTTP with -d @file with file containing CR, LF and null byte --- tests/data/Makefile.inc | 2 +- tests/data/test463 | Bin 0 -> 774 bytes 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 tests/data/test463 diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 825b56815f8..1a06adf37b9 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -73,7 +73,7 @@ test426 test427 test428 test429 test430 test431 test432 test433 test434 \ test435 test436 test437 test438 test439 test440 test441 test442 test443 \ test444 test445 test446 test447 test448 test449 test450 test451 test452 \ test453 test454 test455 test456 test457 test458 test459 test460 test461 \ -test462 \ +test462 test463 \ \ test490 test491 test492 test493 test494 test495 test496 test497 test498 \ test499 test500 test501 test502 test503 test504 test505 test506 test507 \ diff --git a/tests/data/test463 b/tests/data/test463 new file mode 100644 index 0000000000000000000000000000000000000000..27ecd4ba58007689a5763aae023118a92104024b GIT binary patch literal 774 zcmZWnQE!_t5Z<$;{)Zb?UaB%DTQn(%qIPN4L`#z>p?!DZ2v&)Wj0xr6?+j@=tuNrS z@4oxK?=G}h*+f(ru~4c^)9)4AMw_&X*gTFm-3K=7UCjKHh5X|+x)SreD8O_Z~9jrxwiho)*&O_PvuXpypM_C}O#_B^ADhp%Mqu>XbnvZ4Q14 zx0x)kkGfMr-Gx+A?P0pThUIS%Dg{*+1-!JD1o9pv?6TeY#v3fx5BG~LSyI+^{PTww zF|F{zHu}Qm29agDHeWJ%bmgv&C?@)FAmoUQh1>rDz!48PAI!=6#U>ay%A55z=7V^) zi&syNzh+y)I)l*hq`h#>kVN4dnPG}`J! z7m%1DyYX7AJW!;gDWoEiE{>Sn1^AZ*IBIUhY_2OCz$eP=iR}09_B5sdlG+q}@I2e@ z7V8zeOA;*U_KIJ9n)+yRzKYwDmPV9iAroPxR{YIxn#RwxIrs#KD$yyXv?dD4^UiYT R_{s2hT_lm8#qy8U{|hWH^N|1m literal 0 HcmV?d00001 From 296e855d364525b9775c68754499d1ff045d3a57 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 13 Feb 2024 06:45:57 +0100 Subject: [PATCH 438/509] cmake: fix libcurl.pc and curl-config library specifications Letting CMake figure out where libraries are located gives you full paths. When generating libcurl.pc and curl-config, getting libraries as full paths is unusual when one expects to get a list of -l. To meet expectations, an effort is made to convert the full paths into -l, possibly with -L before it. Fixes #6169 Fixes #12748 Closes #12930 --- CMakeLists.txt | 42 +++++++++++++++++++++++++++++++++++++++++- docs/KNOWN_BUGS | 9 --------- 2 files changed, 41 insertions(+), 10 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 40c0f776510..2c69e5628c8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1642,6 +1642,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}") @@ -1657,8 +1681,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/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index eab7e638975..beaa036231a 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -98,7 +98,6 @@ problems may have been fixed or changed somewhat since this was written. 15.3 unusable tool_hugehelp.c with MinGW 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 @@ -577,14 +576,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 From 1347cf255b6293730b506d63c583bb8ec6b63d4e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Mar 2024 09:28:06 +0100 Subject: [PATCH 439/509] GIT-INFO: convert to markdown Closes #13074 --- .github/labeler.yml | 2 +- .github/scripts/spellcheck.words | 2 ++ .reuse/dep5 | 2 +- GIT-INFO => GIT-INFO.md | 30 ++++++++++++++---------------- buildconf.bat | 2 +- docs/INSTALL.md | 4 ++-- projects/generate.bat | 2 +- 7 files changed, 22 insertions(+), 22 deletions(-) rename GIT-INFO => GIT-INFO.md (51%) diff --git a/.github/labeler.yml b/.github/labeler.yml index bd5a027c790..c22bd6e485f 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -93,7 +93,7 @@ documentation: - 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/**,GIT-INFO,LICENSES/**,README,RELEASE-NOTES,scripts/cd*}' + - '{.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' diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index d851228688f..ab7b18c1f5a 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -41,6 +41,7 @@ autobuilds Autoconf autoconf Automake +automake Autotools autotools AVR @@ -426,6 +427,7 @@ libssh libSSH libssh2 Libtool +libtool libuv libWebSocket libz diff --git a/.reuse/dep5 b/.reuse/dep5 index 60c9a012dd2..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 diff --git a/GIT-INFO b/GIT-INFO.md similarity index 51% rename from GIT-INFO rename to GIT-INFO.md index 6e2bfad5cff..825476c96ce 100644 --- a/GIT-INFO +++ b/GIT-INFO.md @@ -4,7 +4,7 @@ | (__| |_| | _ <| |___ \___|\___/|_| \_\_____| -GIT-INFO +# 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 @@ -13,32 +13,30 @@ inner sanctum. To build in environments that support configure, after having extracted everything from git, do this: -autoreconf -fi -./configure --with-openssl -make + autoreconf -fi + ./configure --with-openssl + make - Daniel uses a ./configure line similar to this for easier development: +Daniel uses a configure line similar to this for easier development: - ./configure --disable-shared --enable-debug --enable-maintainer-mode + ./configure --disable-shared --enable-debug --enable-maintainer-mode -In environments that don't support configure (i.e. Microsoft), do this: +In environments that don't support configure (i.e. Windows), do this: -buildconf.bat + buildconf.bat +## REQUIREMENTS -REQUIREMENTS - -For autoreconf and configure (not buildconf.bat) to work, you need the +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. +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/buildconf.bat b/buildconf.bat index 61536611858..afe59e50d72 100644 --- a/buildconf.bat +++ b/buildconf.bat @@ -38,7 +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 + if not exist GIT-INFO.md goto norepo rem Detect programs. HAVE_ rem When not found the variable is set undefined. The undefined pattern diff --git a/docs/INSTALL.md b/docs/INSTALL.md index e8559ea4a78..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 diff --git a/projects/generate.bat b/projects/generate.bat index a110adffc3d..9c41d34fb73 100644 --- a/projects/generate.bat +++ b/projects/generate.bat @@ -39,7 +39,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 + if not exist ..\GIT-INFO.md goto norepo :parseArgs if "%~1" == "" goto start From deca8039991886a559b67bcd6701db800a5cf764 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 6 Mar 2024 09:36:08 +0100 Subject: [PATCH 440/509] http2: push headers better cleanup - provide common cleanup method for push headers Closes #13054 --- lib/http2.c | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/lib/http2.c b/lib/http2.c index c63ecd38371..96868728a53 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -271,6 +271,15 @@ static CURLcode http2_data_setup(struct Curl_cfilter *cf, return CURLE_OK; } +static void free_push_headers(struct h2_stream_ctx *stream) +{ + size_t i; + for(i = 0; ipush_headers_used; i++) + free(stream->push_headers[i]); + Curl_safefree(stream->push_headers); + stream->push_headers_used = 0; +} + static void http2_data_done(struct Curl_cfilter *cf, struct Curl_easy *data, bool premature) { @@ -306,15 +315,7 @@ static void http2_data_done(struct Curl_cfilter *cf, Curl_bufq_free(&stream->sendbuf); Curl_h1_req_parse_free(&stream->h1); Curl_dynhds_free(&stream->resp_trailers); - if(stream->push_headers) { - /* if they weren't used and then freed before */ - for(; stream->push_headers_used > 0; --stream->push_headers_used) { - free(stream->push_headers[stream->push_headers_used - 1]); - } - free(stream->push_headers); - stream->push_headers = NULL; - } - + free_push_headers(stream); free(stream); H2_STREAM_LCTX(data) = NULL; } @@ -860,7 +861,6 @@ static int push_promise(struct Curl_cfilter *cf, struct curl_pushheaders heads; CURLMcode rc; CURLcode result; - size_t i; /* clone the parent */ struct Curl_easy *newhandle = h2_duphandle(cf, data); if(!newhandle) { @@ -905,11 +905,7 @@ static int push_promise(struct Curl_cfilter *cf, Curl_set_in_callback(data, false); /* free the headers again */ - for(i = 0; ipush_headers_used; i++) - free(stream->push_headers[i]); - free(stream->push_headers); - stream->push_headers = NULL; - stream->push_headers_used = 0; + free_push_headers(stream); if(rv) { DEBUGASSERT((rv > CURL_PUSH_OK) && (rv <= CURL_PUSH_ERROROUT)); @@ -1430,14 +1426,14 @@ static int on_header(nghttp2_session *session, const nghttp2_frame *frame, if(stream->push_headers_alloc > 1000) { /* this is beyond crazy many headers, bail out */ failf(data_s, "Too many PUSH_PROMISE headers"); - Curl_safefree(stream->push_headers); + free_push_headers(stream); return NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE; } stream->push_headers_alloc *= 2; - headp = Curl_saferealloc(stream->push_headers, - stream->push_headers_alloc * sizeof(char *)); + headp = realloc(stream->push_headers, + stream->push_headers_alloc * sizeof(char *)); if(!headp) { - stream->push_headers = NULL; + free_push_headers(stream); return NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE; } stream->push_headers = headp; From 9b81f1bef2e8a37a9a8dfc0338432ea2bedc6860 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Wed, 6 Mar 2024 22:24:56 +0000 Subject: [PATCH 441/509] cmake: enable `ENABLE_CURL_MANUAL` by default Meaning `curl.1` and `src/tool_hugehelp.c` are built by default, and `--manual` in curl tool is also enabled by default. This syncs behaviour with autotools. For a reproducible `curl.1`, `SOURCE_DATE_EPOCH` needs to be set to a consistent date, e.g. the timestamp of `CHANGES`. A pre-built manual (e.g. the one distributed in the official source tarball) will be ignored and rebuilt after this patch, unless explicitly disabling this option. Fixes #13028 Closes #13069 --- CMakeLists.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 2c69e5628c8..656aa7c740f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -307,8 +307,7 @@ endif() find_package(Perl) option(BUILD_LIBCURL_DOCS "to build libcurl man pages" ON) -# curl source release tarballs come with the curl man page pre-built. -option(ENABLE_CURL_MANUAL "to build the man page for curl and enable its -M/--manual option" OFF) +option(ENABLE_CURL_MANUAL "to build the man page for curl and enable its -M/--manual option" ON) if(ENABLE_CURL_MANUAL OR BUILD_LIBCURL_DOCS) if(PERL_FOUND) From 1e517e9f5cf11a360333ad5a3b1dec6401b27170 Mon Sep 17 00:00:00 2001 From: Evgeny Grin Date: Thu, 7 Mar 2024 01:35:31 +0100 Subject: [PATCH 442/509] digest: add check for hashing error Closes #13072 --- lib/vauth/digest.c | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/lib/vauth/digest.c b/lib/vauth/digest.c index 417ee111f9c..358bfb60c32 100644 --- a/lib/vauth/digest.c +++ b/lib/vauth/digest.c @@ -728,8 +728,10 @@ static CURLcode auth_create_digest_http_message( if(!hashthis) return CURLE_OUT_OF_MEMORY; - hash(hashbuf, (unsigned char *) hashthis, strlen(hashthis)); + result = hash(hashbuf, (unsigned char *) hashthis, strlen(hashthis)); free(hashthis); + if(result) + return result; convert_to_ascii(hashbuf, (unsigned char *)userh); } @@ -749,8 +751,10 @@ static CURLcode auth_create_digest_http_message( if(!hashthis) return CURLE_OUT_OF_MEMORY; - hash(hashbuf, (unsigned char *) hashthis, strlen(hashthis)); + result = hash(hashbuf, (unsigned char *) hashthis, strlen(hashthis)); free(hashthis); + if(result) + return result; convert_to_ascii(hashbuf, ha1); if(digest->algo & SESSION_ALGO) { @@ -759,8 +763,10 @@ static CURLcode auth_create_digest_http_message( if(!tmp) return CURLE_OUT_OF_MEMORY; - hash(hashbuf, (unsigned char *) tmp, strlen(tmp)); + result = hash(hashbuf, (unsigned char *) tmp, strlen(tmp)); free(tmp); + if(result) + return result; convert_to_ascii(hashbuf, ha1); } @@ -786,7 +792,11 @@ static CURLcode auth_create_digest_http_message( char hashed[65]; char *hashthis2; - hash(hashbuf, (const unsigned char *)"", 0); + result = hash(hashbuf, (const unsigned char *)"", 0); + if(result) { + free(hashthis); + return result; + } convert_to_ascii(hashbuf, (unsigned char *)hashed); hashthis2 = aprintf("%s:%s", hashthis, hashed); @@ -797,8 +807,10 @@ static CURLcode auth_create_digest_http_message( if(!hashthis) return CURLE_OUT_OF_MEMORY; - hash(hashbuf, (unsigned char *) hashthis, strlen(hashthis)); + result = hash(hashbuf, (unsigned char *) hashthis, strlen(hashthis)); free(hashthis); + if(result) + return result; convert_to_ascii(hashbuf, ha2); if(digest->qop) { @@ -812,8 +824,10 @@ static CURLcode auth_create_digest_http_message( if(!hashthis) return CURLE_OUT_OF_MEMORY; - hash(hashbuf, (unsigned char *) hashthis, strlen(hashthis)); + result = hash(hashbuf, (unsigned char *) hashthis, strlen(hashthis)); free(hashthis); + if(result) + return result; convert_to_ascii(hashbuf, request_digest); /* For test case 64 (snooped from a Mozilla 1.3a request) From 05268cf801a193b68411cfa298413c3e5ca79d4f Mon Sep 17 00:00:00 2001 From: "Evgeny Grin (Karlson2k)" Date: Thu, 7 Mar 2024 00:42:04 +0100 Subject: [PATCH 443/509] sha512_256: add support for GnuTLS and OpenSSL This is a follow-up for PR #12897. Add support for SHA-512/256 digest calculation by TLS backends. Currently only OpenSSL and GnuTLS (actually, nettle) support SHA-512/256. Closes #13070 --- lib/curl_sha512_256.c | 293 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 267 insertions(+), 26 deletions(-) diff --git a/lib/curl_sha512_256.c b/lib/curl_sha512_256.c index cabea4349a9..1dd07dbc6a3 100644 --- a/lib/curl_sha512_256.c +++ b/lib/curl_sha512_256.c @@ -29,6 +29,211 @@ #include "curl_sha512_256.h" #include "warnless.h" +/* The recommended order of the TLS backends: + * * OpenSSL + * * GnuTLS + * * wolfSSL + * * Schannel SSPI + * * SecureTransport (Darwin) + * * mbedTLS + * * BearSSL + * * rustls + * Skip the backend if it does not support the required algorithm */ + +#if defined(USE_OPENSSL) +# include +# if (!defined(LIBRESSL_VERSION_NUMBER) && \ + defined(OPENSSL_VERSION_NUMBER) && \ + (OPENSSL_VERSION_NUMBER >= 0x10100010L)) || \ + (defined(LIBRESSL_VERSION_NUMBER) && \ + (LIBRESSL_VERSION_NUMBER >= 0x3080000fL)) +# include +# if !defined(OPENSSL_NO_SHA) && !defined(OPENSSL_NO_SHA512) +# include +# define USE_OPENSSL_SHA512_256 1 +# define HAS_SHA512_256_IMPLEMENTATION 1 +# endif +# endif +#endif /* USE_OPENSSL */ + + +#if !defined(HAS_SHA512_256_IMPLEMENTATION) && defined(USE_GNUTLS) +# include +# if defined(SHA512_256_DIGEST_SIZE) +# define USE_GNUTLS_SHA512_256 1 +# define HAS_SHA512_256_IMPLEMENTATION 1 +# endif +#endif /* ! HAS_SHA512_256_IMPLEMENTATION && USE_GNUTLS */ + +#if defined(USE_OPENSSL_SHA512_256) + +/* OpenSSL does not provide macros for SHA-512/256 sizes */ + +/** + * Size of the SHA-512/256 single processing block in bytes. + */ +#define SHA512_256_BLOCK_SIZE 128 + +/** + * Size of the SHA-512/256 resulting digest in bytes. + * This is the final digest size, not intermediate hash. + */ +#define SHA512_256_DIGEST_SIZE SHA512_256_DIGEST_LENGTH + +/** + * Context type used for SHA-512/256 calculations + */ +typedef EVP_MD_CTX *Curl_sha512_256_ctx; + +/** + * Initialise structure for SHA-512/256 calculation. + * + * @param context the calculation context + * @return CURLE_OK if succeed, + * error code otherwise + */ +static CURLcode +Curl_sha512_256_init(void *context) +{ + Curl_sha512_256_ctx *const ctx = (Curl_sha512_256_ctx *)context; + + *ctx = EVP_MD_CTX_create(); + if(!*ctx) + return CURLE_OUT_OF_MEMORY; + + if(EVP_DigestInit_ex(*ctx, EVP_sha512_256(), NULL)) { + /* Check whether the header and this file use the same numbers */ + DEBUGASSERT(EVP_MD_CTX_size(*ctx) == SHA512_256_DIGEST_SIZE); + /* Check whether the block size is correct */ + DEBUGASSERT(EVP_MD_CTX_block_size(*ctx) == SHA512_256_BLOCK_SIZE); + + return CURLE_OK; /* Success */ + } + + /* Cleanup */ + EVP_MD_CTX_destroy(*ctx); + return CURLE_FAILED_INIT; +} + + +/** + * Process portion of bytes. + * + * @param context the calculation context + * @param data bytes to add to hash + * @return CURLE_OK if succeed, + * error code otherwise + */ +static CURLcode +Curl_sha512_256_update(void *context, + const unsigned char *data, + size_t length) +{ + Curl_sha512_256_ctx *const ctx = (Curl_sha512_256_ctx *)context; + + if(!EVP_DigestUpdate(*ctx, data, length)) + return CURLE_SSL_CIPHER; + + return CURLE_OK; +} + + +/** + * Finalise SHA-512/256 calculation, return digest. + * + * @param context the calculation context + * @param[out] digest set to the hash, must be #SHA512_256_DIGEST_SIZE bytes + * @return CURLE_OK if succeed, + * error code otherwise + */ +static CURLcode +Curl_sha512_256_finish(unsigned char *digest, + void *context) +{ + CURLcode ret; + Curl_sha512_256_ctx *const ctx = (Curl_sha512_256_ctx *)context; + + ret = EVP_DigestFinal_ex(*ctx, digest, NULL) ? CURLE_OK : CURLE_SSL_CIPHER; + + EVP_MD_CTX_destroy(*ctx); + *ctx = NULL; + + return ret; +} + +#elif defined(USE_GNUTLS_SHA512_256) + +/** + * Context type used for SHA-512/256 calculations + */ +typedef struct sha512_256_ctx Curl_sha512_256_ctx; + +/** + * Initialise structure for SHA-512/256 calculation. + * + * @param context the calculation context + * @return always CURLE_OK + */ +static CURLcode +Curl_sha512_256_init(void *context) +{ + Curl_sha512_256_ctx *const ctx = (Curl_sha512_256_ctx *)context; + + /* Check whether the header and this file use the same numbers */ + DEBUGASSERT(SHA512_256_DIGEST_LENGTH == SHA512_256_DIGEST_SIZE); + + sha512_256_init(ctx); + + return CURLE_OK; +} + + +/** + * Process portion of bytes. + * + * @param context the calculation context + * @param data bytes to add to hash + * @param length number of bytes in @a data + * @return always CURLE_OK + */ +static CURLcode +Curl_sha512_256_update(void *context, + const unsigned char *data, + size_t length) +{ + Curl_sha512_256_ctx *const ctx = (Curl_sha512_256_ctx *)context; + + DEBUGASSERT((data != NULL) || (length == 0)); + + sha512_256_update(ctx, length, (const uint8_t *)data); + + return CURLE_OK; +} + + +/** + * Finalise SHA-512/256 calculation, return digest. + * + * @param context the calculation context + * @param[out] digest set to the hash, must be #SHA512_256_DIGEST_SIZE bytes + * @return always CURLE_OK + */ +static CURLcode +Curl_sha512_256_finish(unsigned char *digest, + void *context) +{ + Curl_sha512_256_ctx *const ctx = (Curl_sha512_256_ctx *)context; + + sha512_256_digest(ctx, (size_t)SHA512_256_DIGEST_SIZE, (uint8_t *)digest); + + return CURLE_OK; +} + +#else /* No system or TLS backend SHA-512/256 implementation available */ + +/* Use local implementation */ +#define HAS_SHA512_256_IMPLEMENTATION 1 + /* ** This implementation of SHA-512/256 hash calculation was originally ** * * ** written by Evgeny Grin (Karlson2k) for GNU libmicrohttpd. ** * * ** The author ported the code to libcurl. The ported code is provided ** * @@ -130,7 +335,7 @@ MHDx_rotr64(curl_uint64_t value, unsigned int bits) #define SHA512_256_HASH_SIZE_WORDS 8 /** - * Size of the SHA-512/256 resulting digest in bytes. + * Size of the SHA-512/256 resulting digest in words. * This is the final digest size, not intermediate hash. */ #define SHA512_256_DIGEST_SIZE_WORDS (SHA512_256_HASH_SIZE_WORDS / 2) @@ -161,7 +366,7 @@ MHDx_rotr64(curl_uint64_t value, unsigned int bits) /** * SHA-512/256 calculation context */ -struct Sha512_256Ctx +struct mhdx_sha512_256ctx { /** * Intermediate hash value. The variable is properly aligned. Smart @@ -186,6 +391,11 @@ struct Sha512_256Ctx curl_uint64_t count_bits_hi; }; +/** + * Context type used for SHA-512/256 calculations + */ +typedef struct mhdx_sha512_256ctx Curl_sha512_256_ctx; + /** * Initialise structure for SHA-512/256 calculation. @@ -196,7 +406,7 @@ struct Sha512_256Ctx static CURLcode MHDx_sha512_256_init(void *context) { - struct Sha512_256Ctx *const ctx = (struct Sha512_256Ctx *) context; + struct mhdx_sha512_256ctx *const ctx = (struct mhdx_sha512_256ctx *) context; /* Check whether the header and this file use the same numbers */ DEBUGASSERT(SHA512_256_DIGEST_LENGTH == SHA512_256_DIGEST_SIZE); @@ -393,21 +603,22 @@ MHDx_sha512_256_transform(curl_uint64_t H[SHA512_256_HASH_SIZE_WORDS], * @param context the calculation context * @param data bytes to add to hash * @param length number of bytes in @a data + * @return always CURLE_OK */ -static void +static CURLcode MHDx_sha512_256_update(void *context, const unsigned char *data, - unsigned int length) + size_t length) { unsigned int bytes_have; /**< Number of bytes in the context buffer */ - struct Sha512_256Ctx *const ctx = (struct Sha512_256Ctx *) context; + struct mhdx_sha512_256ctx *const ctx = (struct mhdx_sha512_256ctx *)context; /* the void pointer here is required to mute Intel compiler warning */ void *const ctx_buf = ctx->buffer; DEBUGASSERT((data != NULL) || (length == 0)); if(0 == length) - return; /* Shortcut, do nothing */ + return CURLE_OK; /* Shortcut, do nothing */ /* Note: (count & (SHA512_256_BLOCK_SIZE-1)) equals (count % SHA512_256_BLOCK_SIZE) for this block size. */ @@ -446,6 +657,8 @@ MHDx_sha512_256_update(void *context, to the buffer. */ memcpy(((unsigned char *) ctx_buf) + bytes_have, data, length); } + + return CURLE_OK; } @@ -466,12 +679,13 @@ MHDx_sha512_256_update(void *context, * * @param context the calculation context * @param[out] digest set to the hash, must be #SHA512_256_DIGEST_SIZE bytes + * @return always CURLE_OK */ -static void +static CURLcode MHDx_sha512_256_finish(unsigned char *digest, void *context) { - struct Sha512_256Ctx *const ctx = (struct Sha512_256Ctx *) context; + struct mhdx_sha512_256ctx *const ctx = (struct mhdx_sha512_256ctx *)context; curl_uint64_t num_bits; /**< Number of processed bits */ unsigned int bytes_have; /**< Number of bytes in the context buffer */ /* the void pointer here is required to mute Intel compiler warning */ @@ -538,9 +752,18 @@ MHDx_sha512_256_finish(unsigned char *digest, MHDX_PUT_64BIT_BE((digest + 3 * SHA512_256_BYTES_IN_WORD), ctx->H[3]); /* Erase potentially sensitive data. */ - memset(ctx, 0, sizeof(struct Sha512_256Ctx)); + memset(ctx, 0, sizeof(struct mhdx_sha512_256ctx)); + + return CURLE_OK; } +/* Map to the local implementation */ +#define Curl_sha512_256_init MHDx_sha512_256_init +#define Curl_sha512_256_update MHDx_sha512_256_update +#define Curl_sha512_256_finish MHDx_sha512_256_finish + +#endif /* Local SHA-512/256 code */ + /** * Compute SHA-512/256 hash for the given data in one function call @@ -553,35 +776,54 @@ CURLcode Curl_sha512_256it(unsigned char *output, const unsigned char *input, size_t input_size) { - struct Sha512_256Ctx ctx; - static const unsigned int max_step_size = (unsigned int)(-1); + Curl_sha512_256_ctx ctx; + CURLcode res; + + res = Curl_sha512_256_init(&ctx); + if(res != CURLE_OK) + return res; - (void) MHDx_sha512_256_init(&ctx); /* Always succeed */ + res = Curl_sha512_256_update(&ctx, (const void *) input, input_size); - while(input_size >= max_step_size) { - MHDx_sha512_256_update(&ctx, (const void *) input, max_step_size); - input += max_step_size; - input_size -= max_step_size; + if(res != CURLE_OK) { + (void) Curl_sha512_256_finish(output, &ctx); + return res; } - MHDx_sha512_256_update(&ctx, (const void *) input, - curlx_uztoui(input_size)); - MHDx_sha512_256_finish(output, &ctx); + return Curl_sha512_256_finish(output, &ctx); +} - return CURLE_OK; +/* Wrapper function, takes 'unsigned int' as length type, returns void */ +static void +Curl_sha512_256_update_i(void *context, + const unsigned char *data, + unsigned int length) +{ + /* Hypothetically the function may fail, but assume it does not */ + (void) Curl_sha512_256_update(context, data, length); } +/* Wrapper function, returns void */ +static void +Curl_sha512_256_finish_v(unsigned char *result, + void *context) +{ + /* Hypothetically the function may fail, but assume it does not */ + (void) Curl_sha512_256_finish(result, context); +} + +/* Wrapper function, takes 'unsigned int' as length type, returns void */ const struct HMAC_params Curl_HMAC_SHA512_256[] = { { /* Initialize context procedure. */ - MHDx_sha512_256_init, + Curl_sha512_256_init, /* Update context with data. */ - MHDx_sha512_256_update, + Curl_sha512_256_update_i, /* Get final result procedure. */ - MHDx_sha512_256_finish, + Curl_sha512_256_finish_v, /* Context structure size. */ - sizeof(struct Sha512_256Ctx), + sizeof(Curl_sha512_256_ctx), /* Maximum key length (bytes). */ SHA512_256_BLOCK_SIZE, /* Result length (bytes). */ @@ -589,5 +831,4 @@ const struct HMAC_params Curl_HMAC_SHA512_256[] = { } }; - #endif /* !CURL_DISABLE_DIGEST_AUTH && !CURL_DISABLE_SHA512_256 */ From a89be3cdffda69011c8e90ab08f87eddb7b13790 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 7 Mar 2024 10:18:33 +0100 Subject: [PATCH 444/509] docs/cmdline-opts/.gitignore: ignore curl.txt Closes #13076 --- docs/cmdline-opts/.gitignore | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 docs/cmdline-opts/.gitignore diff --git a/docs/cmdline-opts/.gitignore b/docs/cmdline-opts/.gitignore new file mode 100644 index 00000000000..16213ffa1ea --- /dev/null +++ b/docs/cmdline-opts/.gitignore @@ -0,0 +1,5 @@ +# Copyright (C) Daniel Stenberg, , et al. +# +# SPDX-License-Identifier: curl + +curl.txt \ No newline at end of file From 8a9fbd6291bd5cd98d372ddd6dbb0e09d329b597 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 7 Mar 2024 09:23:11 +0100 Subject: [PATCH 445/509] ngtcp2: no recvbuf for stream - write response data directly to the transfer via `Curl_xfer_write_resp()` like we do in HTTP/2. Closes #13073 --- lib/vquic/curl_ngtcp2.c | 166 +++++++++------------------------------- 1 file changed, 38 insertions(+), 128 deletions(-) diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index 7ef1b5e8407..b49956ab389 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -58,6 +58,7 @@ #include "http1.h" #include "select.h" #include "inet_pton.h" +#include "transfer.h" #include "vquic.h" #include "vquic_int.h" #include "vquic-tls.h" @@ -145,11 +146,9 @@ struct cf_ngtcp2_ctx { struct h3_stream_ctx { int64_t id; /* HTTP/3 protocol identifier */ struct bufq sendbuf; /* h3 request body */ - struct bufq recvbuf; /* h3 response body */ struct h1_req_parser h1; /* h1 request parsing */ size_t sendbuf_len_in_flight; /* sendbuf amount "in flight" */ size_t upload_blocked_len; /* the amount written last and EGAINed */ - size_t recv_buf_nonflow; /* buffered bytes, not counting for flow control */ uint64_t error3; /* HTTP/3 stream error code */ curl_off_t upload_left; /* number of request bytes left to upload */ int status_code; /* HTTP status code */ @@ -190,11 +189,6 @@ static CURLcode h3_data_setup(struct Curl_cfilter *cf, Curl_bufq_initp(&stream->sendbuf, &ctx->stream_bufcp, H3_STREAM_SEND_CHUNKS, BUFQ_OPT_NONE); stream->sendbuf_len_in_flight = 0; - /* on recv, we need a flexible buffer limit since we also write - * headers to it that are not counted against the nghttp3 flow limits. */ - Curl_bufq_initp(&stream->recvbuf, &ctx->stream_bufcp, - H3_STREAM_RECV_CHUNKS, BUFQ_OPT_SOFT_LIMIT); - stream->recv_buf_nonflow = 0; Curl_h1_req_parse_init(&stream->h1, H1_PARSE_DEFAULT_MAX_LINE_LEN); H3_STREAM_LCTX(data) = stream; @@ -219,7 +213,6 @@ static void h3_data_done(struct Curl_cfilter *cf, struct Curl_easy *data) } Curl_bufq_free(&stream->sendbuf); - Curl_bufq_free(&stream->recvbuf); Curl_h1_req_parse_free(&stream->h1); free(stream); H3_STREAM_LCTX(data) = NULL; @@ -387,36 +380,6 @@ static int cb_handshake_completed(ngtcp2_conn *tconn, void *user_data) return 0; } -static void report_consumed_data(struct Curl_cfilter *cf, - struct Curl_easy *data, - size_t consumed) -{ - struct h3_stream_ctx *stream = H3_STREAM_CTX(data); - struct cf_ngtcp2_ctx *ctx = cf->ctx; - - if(!stream) - return; - /* the HTTP/1.1 response headers are written to the buffer, but - * consuming those does not count against flow control. */ - if(stream->recv_buf_nonflow) { - if(consumed >= stream->recv_buf_nonflow) { - consumed -= stream->recv_buf_nonflow; - stream->recv_buf_nonflow = 0; - } - else { - stream->recv_buf_nonflow -= consumed; - consumed = 0; - } - } - if(consumed > 0) { - CURL_TRC_CF(data, cf, "[%" PRId64 "] ACK %zu bytes of DATA", - stream->id, consumed); - ngtcp2_conn_extend_max_stream_offset(ctx->qconn, stream->id, - consumed); - ngtcp2_conn_extend_max_offset(ctx->qconn, consumed); - } -} - static int cb_recv_stream_data(ngtcp2_conn *tconn, uint32_t flags, int64_t stream_id, uint64_t offset, const uint8_t *buf, size_t buflen, @@ -796,49 +759,23 @@ static int cb_h3_stream_close(nghttp3_conn *conn, int64_t stream_id, return 0; } -/* - * write_resp_raw() copies response data in raw format to the `data`'s - * receive buffer. If not enough space is available, it appends to the - * `data`'s overflow buffer. - */ -static CURLcode write_resp_raw(struct Curl_cfilter *cf, - struct Curl_easy *data, - const void *mem, size_t memlen, - bool flow) +static CURLcode write_resp_hds(struct Curl_easy *data, + const char *buf, size_t blen) { - struct h3_stream_ctx *stream = H3_STREAM_CTX(data); - CURLcode result = CURLE_OK; - ssize_t nwritten; - - (void)cf; - if(!stream) { - return CURLE_RECV_ERROR; - } - nwritten = Curl_bufq_write(&stream->recvbuf, mem, memlen, &result); - if(nwritten < 0) { - return result; - } - - if(!flow) - stream->recv_buf_nonflow += (size_t)nwritten; - - if((size_t)nwritten < memlen) { - /* This MUST not happen. Our recbuf is dimensioned to hold the - * full max_stream_window and then some for this very reason. */ - DEBUGASSERT(0); - return CURLE_RECV_ERROR; - } - return result; + bool done; + return Curl_xfer_write_resp(data, (char *)buf, blen, FALSE, &done); } static int cb_h3_recv_data(nghttp3_conn *conn, int64_t stream3_id, - const uint8_t *buf, size_t buflen, + const uint8_t *buf, size_t blen, void *user_data, void *stream_user_data) { struct Curl_cfilter *cf = user_data; + struct cf_ngtcp2_ctx *ctx = cf->ctx; struct Curl_easy *data = stream_user_data; struct h3_stream_ctx *stream = H3_STREAM_CTX(data); CURLcode result; + bool done; (void)conn; (void)stream3_id; @@ -846,14 +783,19 @@ static int cb_h3_recv_data(nghttp3_conn *conn, int64_t stream3_id, if(!stream) return NGHTTP3_ERR_CALLBACK_FAILURE; - result = write_resp_raw(cf, data, buf, buflen, TRUE); + result = Curl_xfer_write_resp(data, (char *)buf, blen, FALSE, &done); if(result) { CURL_TRC_CF(data, cf, "[%" PRId64 "] DATA len=%zu, ERROR receiving %d", - stream->id, buflen, result); + stream->id, blen, result); return NGHTTP3_ERR_CALLBACK_FAILURE; } - CURL_TRC_CF(data, cf, "[%" PRId64 "] DATA len=%zu", stream->id, buflen); - h3_drain_stream(cf, data); + if(blen) { + CURL_TRC_CF(data, cf, "[%" PRId64 "] ACK %zu bytes of DATA", + stream->id, blen); + ngtcp2_conn_extend_max_stream_offset(ctx->qconn, stream->id, blen); + ngtcp2_conn_extend_max_offset(ctx->qconn, blen); + } + CURL_TRC_CF(data, cf, "[%" PRId64 "] DATA len=%zu", stream->id, blen); return 0; } @@ -888,7 +830,7 @@ static int cb_h3_end_headers(nghttp3_conn *conn, int64_t stream_id, if(!stream) return 0; /* add a CRLF only if we've received some headers */ - result = write_resp_raw(cf, data, "\r\n", 2, FALSE); + result = write_resp_hds(data, "\r\n", 2); if(result) { return -1; } @@ -934,7 +876,7 @@ static int cb_h3_recv_header(nghttp3_conn *conn, int64_t stream_id, ncopy = msnprintf(line, sizeof(line), "HTTP/3 %03d \r\n", stream->status_code); CURL_TRC_CF(data, cf, "[%" PRId64 "] status: %s", stream_id, line); - result = write_resp_raw(cf, data, line, ncopy, FALSE); + result = write_resp_hds(data, line, ncopy); if(result) { return -1; } @@ -944,19 +886,19 @@ static int cb_h3_recv_header(nghttp3_conn *conn, int64_t stream_id, CURL_TRC_CF(data, cf, "[%" PRId64 "] header: %.*s: %.*s", stream_id, (int)h3name.len, h3name.base, (int)h3val.len, h3val.base); - result = write_resp_raw(cf, data, h3name.base, h3name.len, FALSE); + result = write_resp_hds(data, (const char *)h3name.base, h3name.len); if(result) { return -1; } - result = write_resp_raw(cf, data, ": ", 2, FALSE); + result = write_resp_hds(data, ": ", 2); if(result) { return -1; } - result = write_resp_raw(cf, data, h3val.base, h3val.len, FALSE); + result = write_resp_hds(data, (const char *)h3val.base, h3val.len); if(result) { return -1; } - result = write_resp_raw(cf, data, "\r\n", 2, FALSE); + result = write_resp_hds(data, "\r\n", 2); if(result) { return -1; } @@ -1112,7 +1054,7 @@ static ssize_t recv_closed_stream(struct Curl_cfilter *cf, /* incoming data frames on the h3 stream */ static ssize_t cf_ngtcp2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, - char *buf, size_t len, CURLcode *err) + char *buf, size_t blen, CURLcode *err) { struct cf_ngtcp2_ctx *ctx = cf->ctx; struct h3_stream_ctx *stream = H3_STREAM_CTX(data); @@ -1121,6 +1063,7 @@ static ssize_t cf_ngtcp2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, struct pkt_io_ctx pktx; (void)ctx; + (void)buf; CF_DATA_SAVE(save, cf, data); DEBUGASSERT(cf->connected); @@ -1136,46 +1079,18 @@ static ssize_t cf_ngtcp2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, goto out; } - if(!Curl_bufq_is_empty(&stream->recvbuf)) { - nread = Curl_bufq_read(&stream->recvbuf, - (unsigned char *)buf, len, err); - if(nread < 0) { - CURL_TRC_CF(data, cf, "[%" PRId64 "] read recvbuf(len=%zu) " - "-> %zd, %d", stream->id, len, nread, *err); - goto out; - } - report_consumed_data(cf, data, nread); - } - if(cf_progress_ingress(cf, data, &pktx)) { *err = CURLE_RECV_ERROR; nread = -1; goto out; } - /* recvbuf had nothing before, maybe after progressing ingress? */ - if(nread < 0 && !Curl_bufq_is_empty(&stream->recvbuf)) { - nread = Curl_bufq_read(&stream->recvbuf, - (unsigned char *)buf, len, err); - if(nread < 0) { - CURL_TRC_CF(data, cf, "[%" PRId64 "] read recvbuf(len=%zu) " - "-> %zd, %d", stream->id, len, nread, *err); - goto out; - } - report_consumed_data(cf, data, nread); - } - - if(nread > 0) { - h3_drain_stream(cf, data); - } - else { - if(stream->closed) { - nread = recv_closed_stream(cf, data, stream, err); - goto out; - } - *err = CURLE_AGAIN; - nread = -1; + if(stream->closed) { + nread = recv_closed_stream(cf, data, stream, err); + goto out; } + *err = CURLE_AGAIN; + nread = -1; out: if(cf_progress_egress(cf, data, &pktx)) { @@ -1189,8 +1104,8 @@ static ssize_t cf_ngtcp2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, nread = -1; } } - CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_recv(len=%zu) -> %zd, %d", - stream? stream->id : -1, len, nread, *err); + CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_recv(blen=%zu) -> %zd, %d", + stream? stream->id : -1, blen, nread, *err); CF_DATA_RESTORE(cf, save); return nread; } @@ -1593,7 +1508,6 @@ static CURLcode cf_progress_ingress(struct Curl_cfilter *cf, struct cf_ngtcp2_ctx *ctx = cf->ctx; struct pkt_io_ctx local_pktx; size_t pkts_chunk = 128, i; - size_t pkts_max = 10 * pkts_chunk; CURLcode result = CURLE_OK; if(!pktx) { @@ -1608,17 +1522,13 @@ static CURLcode cf_progress_ingress(struct Curl_cfilter *cf, if(result) return result; - for(i = 0; i < pkts_max; i += pkts_chunk) { + for(i = 0; i < 4; ++i) { + if(i) + pktx_update_time(pktx, cf); pktx->pkt_count = 0; result = vquic_recv_packets(cf, data, &ctx->q, pkts_chunk, recv_pkt, pktx); - if(result) /* error */ - break; - if(pktx->pkt_count < pkts_chunk) /* got less than we could */ - break; - /* give egress a chance before we receive more */ - result = cf_progress_egress(cf, data, pktx); - if(result) /* error */ + if(result || !pktx->pkt_count) /* error or got nothing */ break; } return result; @@ -1857,9 +1767,9 @@ static CURLcode cf_progress_egress(struct Curl_cfilter *cf, static bool cf_ngtcp2_data_pending(struct Curl_cfilter *cf, const struct Curl_easy *data) { - const struct h3_stream_ctx *stream = H3_STREAM_CTX(data); (void)cf; - return stream && !Curl_bufq_is_empty(&stream->recvbuf); + (void)data; + return FALSE; } static CURLcode h3_data_pause(struct Curl_cfilter *cf, From 2c0f2e81634dac43ce0ecf850c19b10ac5ee8cfd Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 7 Mar 2024 10:08:35 +0100 Subject: [PATCH 446/509] hyper: implement unpausing via client reader Just a tidy up to contain 'ifdef' pollution of common code parts with implementation specifics. - remove the ifdef hyper unpausing in easy.c - add hyper client reader for CURL_CR_PROTOCOL phase that implements the unpause method for calling the hyper waker if it is set Closes #13075 --- lib/c-hyper.c | 64 +++++++++++++++++++++++++++++++++++++------- lib/easy.c | 10 ------- lib/sendf.c | 15 +++++++++++ lib/sendf.h | 4 +++ scripts/singleuse.pl | 1 + 5 files changed, 75 insertions(+), 19 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index f11b126a571..41d758170b0 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -67,6 +67,9 @@ #include "curl_memory.h" #include "memdebug.h" + +static CURLcode cr_hyper_add(struct Curl_easy *data); + typedef enum { USERDATA_NOT_SET = 0, /* for tasks with no userdata set; must be zero */ USERDATA_RESP_BODY @@ -718,14 +721,12 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, } /* - * bodysend() sets up headers in the outgoing request for an HTTP transfer that - * sends a body + * finalize_request() sets up last headers and optional body settings */ - -static CURLcode bodysend(struct Curl_easy *data, - hyper_headers *headers, - hyper_request *hyperreq, - Curl_HttpReq httpreq) +static CURLcode finalize_request(struct Curl_easy *data, + hyper_headers *headers, + hyper_request *hyperreq, + Curl_HttpReq httpreq) { CURLcode result = CURLE_OK; struct dynbuf req; @@ -757,7 +758,8 @@ static CURLcode bodysend(struct Curl_easy *data, result = CURLE_OUT_OF_MEMORY; } } - return result; + + return cr_hyper_add(data); } static CURLcode cookies(struct Curl_easy *data, @@ -1127,7 +1129,7 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) if(result) goto error; - result = bodysend(data, headers, req, httpreq); + result = finalize_request(data, headers, req, httpreq); if(result) goto error; @@ -1212,6 +1214,50 @@ void Curl_hyper_done(struct Curl_easy *data) hyper_waker_free(h->exp100_waker); h->exp100_waker = NULL; } + if(h->send_body_waker) { + hyper_waker_free(h->send_body_waker); + h->send_body_waker = NULL; + } +} + +static CURLcode cr_hyper_unpause(struct Curl_easy *data, + struct Curl_creader *reader) +{ + (void)reader; + if(data->hyp.send_body_waker) { + hyper_waker_wake(data->hyp.send_body_waker); + data->hyp.send_body_waker = NULL; + } + return CURLE_OK; +} + +/* Hyper client reader, handling unpausing */ +static const struct Curl_crtype cr_hyper_protocol = { + "cr-hyper", + Curl_creader_def_init, + Curl_creader_def_read, + Curl_creader_def_close, + Curl_creader_def_needs_rewind, + Curl_creader_def_total_length, + Curl_creader_def_resume_from, + Curl_creader_def_rewind, + cr_hyper_unpause, + sizeof(struct Curl_creader) +}; + +static CURLcode cr_hyper_add(struct Curl_easy *data) +{ + struct Curl_creader *reader = NULL; + CURLcode result; + + result = Curl_creader_create(&reader, data, &cr_hyper_protocol, + CURL_CR_PROTOCOL); + if(!result) + result = Curl_creader_add(data, reader); + + if(result && reader) + Curl_creader_free(data, reader); + return result; } #endif /* !defined(CURL_DISABLE_HTTP) && defined(USE_HYPER) */ diff --git a/lib/easy.c b/lib/easy.c index dbc2e7f1791..d41ca32d7f6 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -1126,16 +1126,6 @@ CURLcode curl_easy_pause(struct Curl_easy *data, int action) return result; } -#ifdef USE_HYPER - if(!(newstate & KEEP_SEND_PAUSE)) { - /* need to wake the send body waker */ - if(data->hyp.send_body_waker) { - hyper_waker_wake(data->hyp.send_body_waker); - data->hyp.send_body_waker = NULL; - } - } -#endif - /* if there's no error and we're not pausing both directions, we want to have this handle checked soon */ if((newstate & (KEEP_RECV_PAUSE|KEEP_SEND_PAUSE)) != diff --git a/lib/sendf.c b/lib/sendf.c index ce9b2b07576..5bec063d94c 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -523,6 +523,21 @@ void Curl_creader_def_close(struct Curl_easy *data, (void)reader; } +CURLcode Curl_creader_def_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *nread, bool *eos) +{ + if(reader->next) + return reader->next->crt->do_read(data, reader->next, buf, blen, + nread, eos); + else { + *nread = 0; + *eos = FALSE; + return CURLE_READ_ERROR; + } +} + bool Curl_creader_def_needs_rewind(struct Curl_easy *data, struct Curl_creader *reader) { diff --git a/lib/sendf.h b/lib/sendf.h index a62cfe8c687..1bcbb3fd01e 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -241,6 +241,10 @@ CURLcode Curl_creader_def_init(struct Curl_easy *data, struct Curl_creader *reader); void Curl_creader_def_close(struct Curl_easy *data, struct Curl_creader *reader); +CURLcode Curl_creader_def_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *nread, bool *eos); bool Curl_creader_def_needs_rewind(struct Curl_easy *data, struct Curl_creader *reader); curl_off_t Curl_creader_def_total_length(struct Curl_easy *data, diff --git a/scripts/singleuse.pl b/scripts/singleuse.pl index 3948d0a79a8..064990226a3 100755 --- a/scripts/singleuse.pl +++ b/scripts/singleuse.pl @@ -46,6 +46,7 @@ 'Curl_xfer_write_resp' => 'internal api', 'Curl_creader_def_init' => 'internal api', 'Curl_creader_def_close' => 'internal api', + 'Curl_creader_def_read' => 'internal api', 'Curl_creader_def_total_length' => 'internal api', ); From 835e4cb1d5d490ad68e29c3d2e9a3d67c6e7a8bf Mon Sep 17 00:00:00 2001 From: Robert Moreton Date: Mon, 26 Feb 2024 18:16:21 -0500 Subject: [PATCH 447/509] asyn-ares: fix data race warning - Store the c-ares version during global init. Prior to this change several threads could write the same data to a static int variable at the same time. Though in practice it's not a problem ThreadSanitizer may warn. Reported-by: Nikita Taranov Assisted-by: Jay Satiro Fixes #13065 Closes #13000 --- lib/asyn-ares.c | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/lib/asyn-ares.c b/lib/asyn-ares.c index 2290a71ef46..3d718b34178 100644 --- a/lib/asyn-ares.c +++ b/lib/asyn-ares.c @@ -122,6 +122,8 @@ struct thread_data { #define CARES_TIMEOUT_PER_ATTEMPT 2000 +static int ares_ver = 0; + /* * Curl_resolver_global_init() - the generic low-level asynchronous name * resolve API. Called from curl_global_init() to initialize global resolver @@ -134,6 +136,7 @@ int Curl_resolver_global_init(void) return CURLE_FAILED_INIT; } #endif + ares_version(&ares_ver); return CURLE_OK; } @@ -173,16 +176,8 @@ CURLcode Curl_resolver_init(struct Curl_easy *easy, void **resolver) int status; struct ares_options options; int optmask = ARES_OPT_SOCK_STATE_CB; - static int ares_ver = 0; options.sock_state_cb = sock_state_cb; options.sock_state_cb_data = easy; - if(ares_ver == 0) - ares_version(&ares_ver); - - if(ares_ver < 0x011400) { /* c-ares included similar change since 1.20.0 */ - options.timeout = CARES_TIMEOUT_PER_ATTEMPT; - optmask |= ARES_OPT_TIMEOUTMS; - } /* if c ares < 1.20.0: curl set timeout to CARES_TIMEOUT_PER_ATTEMPT (2s) @@ -193,6 +188,11 @@ CURLcode Curl_resolver_init(struct Curl_easy *easy, void **resolver) if c-ares >= 1.24.0, user can set the timeout via /etc/resolv.conf to overwrite c-ares' timeout. */ + DEBUGASSERT(ares_ver); + if(ares_ver < 0x011400) { + options.timeout = CARES_TIMEOUT_PER_ATTEMPT; + optmask |= ARES_OPT_TIMEOUTMS; + } status = ares_init_options((ares_channel*)resolver, &options, optmask); if(status != ARES_SUCCESS) { From a03b91e725375f167641f2227061ec270a31ae9e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Mar 2024 16:50:59 +0100 Subject: [PATCH 448/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 57 ++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 47 insertions(+), 10 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index cff167aaad4..2a3f05331b0 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.7.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3108 + Contributors: 3112 This release includes the following changes: @@ -18,6 +18,7 @@ This release includes the following bugfixes: o _VARIABLES.md: improve the description [105] 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] @@ -28,8 +29,11 @@ This release includes the following bugfixes: 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] @@ -51,9 +55,11 @@ This release includes the following bugfixes: 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 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 sure curl.1 is included in dist tarballs [35] @@ -70,15 +76,20 @@ This release includes the following bugfixes: 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 GIT-INFO: convert to markdown [114] o header.md: remove backslash, make nicer markdown [48] o HTTP/2: write response directly [12] + o http2: fix push discard [124] + o http2: push headers better cleanup [113] 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: move headers collecting to writer [71] 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 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] @@ -91,17 +102,21 @@ This release includes the following bugfixes: o mbedtls: fix building when MBEDTLS_X509_REMOVE_INFO flag is defined [27] 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 rustls: make curl compile with 0.12.0 [73] @@ -110,6 +125,7 @@ This release includes the following bugfixes: 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 strtoofft: fix the overflow check [74] o test1165: improve pattern matching [60] @@ -118,6 +134,8 @@ This release includes the following bugfixes: o tool_cb_hdr: only parse etag + content-disposition for 2xx [9] 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] @@ -141,18 +159,19 @@ advice from friends like these: 5533asdg on github, Andreas Kiefer, av223119 on github, Boris Verkhovskiy, Brett Buddin, Chris Webb, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, - Daniel Szmulewicz, dependabot[bot], Dirk Hünniger, Dmitry Tretyakov, - edmcln on github, Erik Schnetter, Evgeny Grin (Karlson2k), Fabian Vogt, - Fabrice Fontaine, Faraz Fallahi, Gisle Vanem, Harry Sintonen, + Daniel Szmulewicz, dependabot[bot], Dirk Hünniger, Dmitry Karpov, + Dmitry Tretyakov, edmcln on github, Erik Schnetter, Evgeny Grin (Karlson2k), + Fabian Vogt, Fabrice Fontaine, Faraz Fallahi, Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, Joel Depooter, Jon Rumsey, Jordan Brown, Karthikdasari0423, Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, Lukáš Zaoral, Marcel Raad, - Michael Forney, Michael Kaufmann, Michał Antoniak, Patrick Monnerat, - Paweł Witas, Peter Krefting, RainRat, Ramiro Garcia, Ray Satiro, - Richard Levitte, Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, - Sebastian Neubauer, Sergey Bronnikov, Stefan Eissing, Tal Regev, - Viktor Szakats, vulnerabilityspotter on hackerone - (54 contributors) + Michael Forney, Michael Kaufmann, Michał Antoniak, Nikita Taranov, + Patrick Monnerat, Paweł Witas, Peter Krefting, RainRat, Ramiro Garcia, + Ray Satiro, Richard Levitte, Robert Moreton, Rudi Heitbaum, + Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, Sebastian Neubauer, + Sergey Bronnikov, Simon K, Stefan Eissing, Tal Regev, Viktor Szakats, + vulnerabilityspotter on hackerone + (59 contributors) References to bug reports and discussions on issues: @@ -243,6 +262,7 @@ References to bug reports and discussions on issues: [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 @@ -252,6 +272,7 @@ References to bug reports and discussions on issues: [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 @@ -261,3 +282,19 @@ References to bug reports and discussions on issues: [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 + [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 + [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 + [124] = https://curl.se/bug/?i=13055 + [125] = https://curl.se/mail/lib-2024-03/0001.html + [126] = https://curl.se/bug/?i=13039 From cf3b60e9aa56fb1c82b90bbc0912e9453b06d48d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Mar 2024 17:40:29 +0100 Subject: [PATCH 449/509] KNOWN_BUGS: POP3 issue when reading small chunks Closes #12063 --- docs/KNOWN_BUGS | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index beaa036231a..f4ced4d84fd 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -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 @@ -204,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 From e55db0c8c74d6121b20d458eb5c6015e519fb302 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Thu, 7 Mar 2024 09:25:39 +0000 Subject: [PATCH 450/509] mkhelp: rename variable to fix compiler warnings ``` src\tool_operate.c(541,33): warning C4459: declaration of 'm' hides global declaration [_bld\src\curl.vcxproj] _bld\src\tool_hugehelp.c(8,27): see declaration of 'm' src\tool_paramhlp.c(307,14): warning C4459: declaration of 'm' hides global declaration [_bld\src\curl.vcxproj] src\tool_progress.c(118,16): warning C4459: declaration of 'm' hides global declaration [_bld\src\curl.vcxproj] src\tool_writeout.c(288,31): warning C4459: declaration of 'm' hides global declaration [_bld\src\curl.vcxproj] ``` Ref: https://ci.appveyor.com/project/curlorg/curl/builds/49348159/job/51ee75cd2n0wj6lc#L614 Reviewed-by: Daniel Stenberg Closes #13077 --- src/mkhelp.pl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/mkhelp.pl b/src/mkhelp.pl index f1e1de1c665..52b6e13e344 100755 --- a/src/mkhelp.pl +++ b/src/mkhelp.pl @@ -157,7 +157,7 @@ } else { print < Date: Thu, 7 Mar 2024 16:02:13 +0100 Subject: [PATCH 451/509] http2: memory errors in the push callbacks are fatal Use the correct nghttp2 error code accordingly. Closes #13081 --- lib/http2.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/http2.c b/lib/http2.c index 96868728a53..4183f08d0ba 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -1417,7 +1417,7 @@ static int on_header(nghttp2_session *session, const nghttp2_frame *frame, stream->push_headers = malloc(stream->push_headers_alloc * sizeof(char *)); if(!stream->push_headers) - return NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE; + return NGHTTP2_ERR_CALLBACK_FAILURE; stream->push_headers_used = 0; } else if(stream->push_headers_used == @@ -1427,14 +1427,14 @@ static int on_header(nghttp2_session *session, const nghttp2_frame *frame, /* this is beyond crazy many headers, bail out */ failf(data_s, "Too many PUSH_PROMISE headers"); free_push_headers(stream); - return NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE; + return NGHTTP2_ERR_CALLBACK_FAILURE; } stream->push_headers_alloc *= 2; headp = realloc(stream->push_headers, stream->push_headers_alloc * sizeof(char *)); if(!headp) { free_push_headers(stream); - return NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE; + return NGHTTP2_ERR_CALLBACK_FAILURE; } stream->push_headers = headp; } From aba98d2f1fee553bf042b053e76584e9f2f52e57 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Mar 2024 10:33:49 +0100 Subject: [PATCH 452/509] buildconf.bat: remove outdated groff/nroff use - don't try to generate the real hugehelp file, because it requires curl.txt which needs a build - don't attempt to do anything in a c-ares subdirectory Follow-up to f03c85635f35269 Closes #13078 --- buildconf.bat | 78 ++++++++------------------------------------------- 1 file changed, 12 insertions(+), 66 deletions(-) diff --git a/buildconf.bat b/buildconf.bat index afe59e50d72..532c9848d6b 100644 --- a/buildconf.bat +++ b/buildconf.bat @@ -40,18 +40,6 @@ rem rem Check we are running from a curl git repository if not exist GIT-INFO.md 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) - :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 From b4d73e67dc7e4ec0a62e24075fe865c75c777464 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Mar 2024 16:41:06 +0100 Subject: [PATCH 453/509] http2: minor tweaks to optimize two struct sizes - use BIT() instead of bool - place the struct fields in (roughly) size order Closes #13082 --- lib/http2.c | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/lib/http2.c b/lib/http2.c index 4183f08d0ba..60b924de062 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -121,7 +121,6 @@ static ssize_t populate_binsettings(uint8_t *binsettings, struct cf_h2_ctx { nghttp2_session *h2; - uint32_t max_concurrent_streams; /* The easy handle used in the current filter call, cleared at return */ struct cf_call_data call_data; @@ -130,6 +129,7 @@ struct cf_h2_ctx { struct bufc_pool stream_bufcp; /* spares for stream buffers */ size_t drain_total; /* sum of all stream's UrlState drain */ + uint32_t max_concurrent_streams; int32_t goaway_error; int32_t last_stream_id; BIT(conn_closed); @@ -172,7 +172,6 @@ static CURLcode h2_progress_egress(struct Curl_cfilter *cf, * All about the H2 internals of a stream */ struct h2_stream_ctx { - int32_t id; /* HTTP/2 protocol identifier for stream */ struct bufq recvbuf; /* response buffer */ struct bufq sendbuf; /* request buffer */ struct h1_req_parser h1; /* parsing the request */ @@ -189,13 +188,14 @@ struct h2_stream_ctx { int status_code; /* HTTP response status code */ uint32_t error; /* stream error code */ uint32_t local_window_size; /* the local recv window size */ - bool resp_hds_complete; /* we have a complete, final response */ - bool closed; /* TRUE on stream close */ - bool reset; /* TRUE on stream reset */ - bool close_handled; /* TRUE if stream closure is handled by libcurl */ - bool bodystarted; - bool send_closed; /* transfer is done sending, we might have still - buffered data in stream->sendbuf to upload. */ + int32_t id; /* HTTP/2 protocol identifier for stream */ + BIT(resp_hds_complete); /* we have a complete, final response */ + BIT(closed); /* TRUE on stream close */ + BIT(reset); /* TRUE on stream reset */ + BIT(close_handled); /* TRUE if stream closure is handled by libcurl */ + BIT(bodystarted); + BIT(send_closed); /* transfer is done sending, we might have still + buffered data in stream->sendbuf to upload. */ }; #define H2_STREAM_CTX(d) ((struct h2_stream_ctx *)(((d) && \ From 1ab2efb0efca290b4b19de654de9bdc3e0aec1c9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Mar 2024 22:30:50 +0100 Subject: [PATCH 454/509] test1140/1173: extend wildcards to find curl.1 ... in its new build path. Also update the test scripts to be more precise in error messages to help us understand CI errors better. Follow-up to f03c85635f35269f1 Ref: #13029 Closes #13083 --- tests/data/test1140 | 2 +- tests/data/test1173 | 2 +- tests/test1140.pl | 2 +- tests/test1173.pl | 3 ++- 4 files changed, 5 insertions(+), 4 deletions(-) diff --git a/tests/data/test1140 b/tests/data/test1140 index aec680ce5bc..2e4d8daf2f7 100644 --- a/tests/data/test1140 +++ b/tests/data/test1140 @@ -19,7 +19,7 @@ Verify the nroff of manpages -%SRCDIR/test1140.pl %PWD/../docs/ %PWD/../docs/libcurl/*.3 %PWD/../docs/libcurl/opts/*.3 %PWD/../docs/*.1 +%SRCDIR/test1140.pl %PWD/../docs/ %PWD/../docs/libcurl/*.3 %PWD/../docs/libcurl/opts/*.3 %PWD/../docs/*.1 %PWD/../docs/cmdline-opts/*.1 diff --git a/tests/data/test1173 b/tests/data/test1173 index 97d338df309..ff786c44bd4 100644 --- a/tests/data/test1173 +++ b/tests/data/test1173 @@ -19,7 +19,7 @@ Man page syntax checks -%SRCDIR/test1173.pl %SRCDIR/../docs/libcurl/symbols-in-versions %PWD/../docs/*.1 %PWD/../docs/libcurl/*.3 %PWD/../docs/libcurl/opts/*.3 +%SRCDIR/test1173.pl %SRCDIR/../docs/libcurl/symbols-in-versions %PWD/../docs/*.1 %PWD/../docs/cmdline-opts/*.1 %PWD/../docs/libcurl/*.3 %PWD/../docs/libcurl/opts/*.3 diff --git a/tests/test1140.pl b/tests/test1140.pl index 6ad346ea671..8e1f1229858 100755 --- a/tests/test1140.pl +++ b/tests/test1140.pl @@ -57,7 +57,7 @@ sub manpresent { sub file { my ($f) = @_; open(my $fh, "<", "$f") || - die "no file"; + die "test1140.pl could not open $f"; my $line = 1; while(<$fh>) { chomp; diff --git a/tests/test1173.pl b/tests/test1173.pl index 7457c7d44cb..bf03c98cd83 100755 --- a/tests/test1173.pl +++ b/tests/test1173.pl @@ -132,7 +132,8 @@ sub scanmanpage { my @separators; my @sepline; - open(my $m, "<", "$file") || die "no such file: $file"; + open(my $m, "<", "$file") || + die "test1173.pl could not open $file"; if($file =~ /[\/\\](CURL|curl_)[^\/\\]*.3/) { # This is a man page for libcurl. It requires an example! $reqex = 1; From 71681376d83449a00b5e3176fd1aa182ac2304cb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Mar 2024 23:25:07 +0100 Subject: [PATCH 455/509] docs/cmdline-opts: drop the curl.1 from the dist tarball Since it is no longer needed for building tool_hugehelp.c and all the docs is available in readable markdown format in the tarball, the peeps that don't want to build the manpage still do good. Removing it also fixes the complexity of out-of-tree builds when the curl.1 exists in the source tree. --- docs/cmdline-opts/Makefile.am | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index 476c932f22d..50d13527061 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -53,6 +53,3 @@ $(ASCIIPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl listhelp: ./gen.pl listhelp $(DPAGES) > $(top_builddir)/src/tool_listhelp.c - -dist-hook: $(MANPAGE) - cp $(MANPAGE) $(MANPAGE).dist From 800617fac8bfa9417224f83f639ecf6028a7a208 Mon Sep 17 00:00:00 2001 From: Marcel Raad Date: Fri, 8 Mar 2024 08:45:10 +0100 Subject: [PATCH 456/509] lib1598: fix `CURLOPT_POSTFIELDSIZE` usage It requires a `long` argument. Closes https://github.com/curl/curl/pull/13085 --- tests/libtest/lib1598.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/libtest/lib1598.c b/tests/libtest/lib1598.c index 63cdfcfb64c..c099116a86a 100644 --- a/tests/libtest/lib1598.c +++ b/tests/libtest/lib1598.c @@ -87,7 +87,7 @@ int test(char *URL) test_setopt(curl, CURLOPT_URL, URL); test_setopt(curl, CURLOPT_HTTPHEADER, hhl); - test_setopt(curl, CURLOPT_POSTFIELDSIZE, strlen(post_data)); + test_setopt(curl, CURLOPT_POSTFIELDSIZE, (long)strlen(post_data)); test_setopt(curl, CURLOPT_POSTFIELDS, post_data); test_setopt(curl, CURLOPT_TRAILERFUNCTION, trailers_callback); test_setopt(curl, CURLOPT_TRAILERDATA, NULL); From a586b8ca4045292bf2443098d7f1a93cfe2dc620 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 7 Mar 2024 11:05:53 +0100 Subject: [PATCH 457/509] lib: client reader polish - seek_func/seek_client, use transfer values only - remove copies held in `struct connectdata`, use only ever `data->set.seek_func` - resolves possible issues in multiuse connections - new mime post reader eliminates need to ever overwriting this - websockets, remove empty Curl_ws_done() function Closes #13079 --- lib/ftp.c | 6 +++--- lib/http.c | 5 ----- lib/sendf.c | 4 ++-- lib/url.c | 8 -------- lib/urldata.h | 2 -- lib/vssh/libssh.c | 6 +++--- lib/vssh/libssh2.c | 6 +++--- lib/vssh/wolfssh.c | 6 +++--- lib/ws.c | 5 ----- lib/ws.h | 2 -- 10 files changed, 14 insertions(+), 36 deletions(-) diff --git a/lib/ftp.c b/lib/ftp.c index 2511bd4b611..29a1476da4c 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -1683,10 +1683,10 @@ static CURLcode ftp_state_ul_setup(struct Curl_easy *data, append = TRUE; /* Let's read off the proper amount of bytes from the input. */ - if(conn->seek_func) { + if(data->set.seek_func) { Curl_set_in_callback(data, true); - seekerr = conn->seek_func(conn->seek_client, data->state.resume_from, - SEEK_SET); + seekerr = data->set.seek_func(data->set.seek_client, + data->state.resume_from, SEEK_SET); Curl_set_in_callback(data, false); } diff --git a/lib/http.c b/lib/http.c index d50b099c77e..058d079f498 100644 --- a/lib/http.c +++ b/lib/http.c @@ -1249,16 +1249,11 @@ CURLcode Curl_http_done(struct Curl_easy *data, data->state.authhost.multipass = FALSE; data->state.authproxy.multipass = FALSE; - /* set the proper values (possibly modified on POST) */ - conn->seek_func = data->set.seek_func; /* restore */ - conn->seek_client = data->set.seek_client; /* restore */ - if(!http) return CURLE_OK; Curl_dyn_reset(&data->state.headerb); Curl_hyper_done(data); - Curl_ws_done(data); if(status) return status; diff --git a/lib/sendf.c b/lib/sendf.c index 5bec063d94c..9610f70dad3 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -724,9 +724,9 @@ static CURLcode cr_in_resume_from(struct Curl_easy *data, if(ctx->read_len) return CURLE_READ_ERROR; - if(data->conn->seek_func) { + if(data->set.seek_func) { Curl_set_in_callback(data, true); - seekerr = data->conn->seek_func(data->conn->seek_client, offset, SEEK_SET); + seekerr = data->set.seek_func(data->set.seek_client, offset, SEEK_SET); Curl_set_in_callback(data, false); } diff --git a/lib/url.c b/lib/url.c index b3057659764..f457e276640 100644 --- a/lib/url.c +++ b/lib/url.c @@ -353,7 +353,6 @@ CURLcode Curl_init_userdefined(struct Curl_easy *data) set->fread_func_set = (curl_read_callback)fread; set->is_fread_set = 0; - set->seek_func = ZERO_NULL; set->seek_client = ZERO_NULL; set->filesize = -1; /* we don't know the size */ @@ -3765,13 +3764,6 @@ static CURLcode create_conn(struct Curl_easy *data, /* Continue connectdata initialization here. */ - /* - * Inherit the proper values from the urldata struct AFTER we have arranged - * the persistent connection stuff - */ - conn->seek_func = data->set.seek_func; - conn->seek_client = data->set.seek_client; - /************************************************************* * Resolve the address of the server or proxy *************************************************************/ diff --git a/lib/urldata.h b/lib/urldata.h index b9e57027580..2e3cf345cfc 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -874,8 +874,6 @@ struct connectdata { #endif /* however, some of them are ftp specific. */ struct Curl_llist easyq; /* List of easy handles using this connection */ - curl_seek_callback seek_func; /* function that seeks the input */ - void *seek_client; /* pointer to pass to the seek() above */ /*************** Request - specific items ************/ #if defined(USE_WINDOWS_SSPI) && defined(SECPKG_ATTR_ENDPOINT_BINDINGS) diff --git a/lib/vssh/libssh.c b/lib/vssh/libssh.c index 7cfc9502166..da7ce6ad989 100644 --- a/lib/vssh/libssh.c +++ b/lib/vssh/libssh.c @@ -1292,10 +1292,10 @@ static CURLcode myssh_statemach_act(struct Curl_easy *data, bool *block) position. */ if(data->state.resume_from > 0) { /* Let's read off the proper amount of bytes from the input. */ - if(conn->seek_func) { + if(data->set.seek_func) { Curl_set_in_callback(data, true); - seekerr = conn->seek_func(conn->seek_client, data->state.resume_from, - SEEK_SET); + seekerr = data->set.seek_func(data->set.seek_client, + data->state.resume_from, SEEK_SET); Curl_set_in_callback(data, false); } diff --git a/lib/vssh/libssh2.c b/lib/vssh/libssh2.c index 073c6873db4..3cfbe126c69 100644 --- a/lib/vssh/libssh2.c +++ b/lib/vssh/libssh2.c @@ -2142,10 +2142,10 @@ static CURLcode ssh_statemach_act(struct Curl_easy *data, bool *block) position. */ if(data->state.resume_from > 0) { /* Let's read off the proper amount of bytes from the input. */ - if(conn->seek_func) { + if(data->set.seek_func) { Curl_set_in_callback(data, true); - seekerr = conn->seek_func(conn->seek_client, data->state.resume_from, - SEEK_SET); + seekerr = data->set.seek_func(data->set.seek_client, + data->state.resume_from, SEEK_SET); Curl_set_in_callback(data, false); } diff --git a/lib/vssh/wolfssh.c b/lib/vssh/wolfssh.c index c6b94fd50d3..11275910a1f 100644 --- a/lib/vssh/wolfssh.c +++ b/lib/vssh/wolfssh.c @@ -625,10 +625,10 @@ static CURLcode wssh_statemach_act(struct Curl_easy *data, bool *block) if(data->state.resume_from > 0) { /* Let's read off the proper amount of bytes from the input. */ int seekerr = CURL_SEEKFUNC_OK; - if(conn->seek_func) { + if(data->set.seek_func) { Curl_set_in_callback(data, true); - seekerr = conn->seek_func(conn->seek_client, data->state.resume_from, - SEEK_SET); + seekerr = data->set.seek_func(data->set.seek_client, + data->state.resume_from, SEEK_SET); Curl_set_in_callback(data, false); } diff --git a/lib/ws.c b/lib/ws.c index 263299761f8..5bc5eccc48b 100644 --- a/lib/ws.c +++ b/lib/ws.c @@ -1163,11 +1163,6 @@ static CURLcode ws_setup_conn(struct Curl_easy *data, } -void Curl_ws_done(struct Curl_easy *data) -{ - (void)data; -} - static CURLcode ws_disconnect(struct Curl_easy *data, struct connectdata *conn, bool dead_connection) diff --git a/lib/ws.h b/lib/ws.h index 5f40d4528b5..baa77b44249 100644 --- a/lib/ws.h +++ b/lib/ws.h @@ -75,7 +75,6 @@ struct websocket { CURLcode Curl_ws_request(struct Curl_easy *data, REQTYPE *req); CURLcode Curl_ws_accept(struct Curl_easy *data, const char *mem, size_t len); -void Curl_ws_done(struct Curl_easy *data); extern const struct Curl_handler Curl_handler_ws; #ifdef USE_SSL @@ -85,7 +84,6 @@ extern const struct Curl_handler Curl_handler_wss; #else #define Curl_ws_request(x,y) CURLE_OK -#define Curl_ws_done(x) Curl_nop_stmt #define Curl_ws_free(x) Curl_nop_stmt #endif From 39173f66e541db909069a4ce30d7590b76041596 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 8 Mar 2024 11:09:48 +0100 Subject: [PATCH 458/509] VULN-DISCLOSURE-POLICY.md: update detail about CVE requests curl is a CNA now Closes #13088 --- .github/scripts/spellcheck.words | 1 + docs/VULN-DISCLOSURE-POLICY.md | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index ab7b18c1f5a..050513c76f2 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -117,6 +117,7 @@ cmake CMake's cmake's CMakeLists +CNA CodeQL codeql CODESET diff --git a/docs/VULN-DISCLOSURE-POLICY.md b/docs/VULN-DISCLOSURE-POLICY.md index 5f10bc8b6fd..f18db6d52fa 100644 --- a/docs/VULN-DISCLOSURE-POLICY.md +++ b/docs/VULN-DISCLOSURE-POLICY.md @@ -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. From 1ccf1cd9936dfa382fe1f061b639de20170bc8ea Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 8 Mar 2024 11:22:12 +0100 Subject: [PATCH 459/509] scripts/managen: the new name and home for the manpage generator It was previously docs/cmdline-opts/gen.pl Closes #13089 --- docs/cmdline-opts/CMakeLists.txt | 4 ++-- docs/cmdline-opts/MANPAGE.md | 9 +++++++-- docs/cmdline-opts/Makefile.am | 17 +++++++++++------ scripts/Makefile.am | 2 +- docs/cmdline-opts/gen.pl => scripts/managen | 6 +++--- src/tool_help.h | 3 +-- tests/data/test1478 | 2 +- 7 files changed, 26 insertions(+), 17 deletions(-) rename docs/cmdline-opts/gen.pl => scripts/managen (99%) diff --git a/docs/cmdline-opts/CMakeLists.txt b/docs/cmdline-opts/CMakeLists.txt index 6a3a1c5f6d2..99ec66c3188 100644 --- a/docs/cmdline-opts/CMakeLists.txt +++ b/docs/cmdline-opts/CMakeLists.txt @@ -29,8 +29,8 @@ transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc. include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake") add_custom_command(OUTPUT "${MANPAGE}" - COMMAND cd ${CMAKE_CURRENT_SOURCE_DIR} && "${PERL_EXECUTABLE}" "./gen.pl" mainpage ${DPAGES} > "${MANPAGE}" - COMMAND cd ${CMAKE_CURRENT_SOURCE_DIR} && "${PERL_EXECUTABLE}" "./gen.pl" ascii ${DPAGES} > "${ASCIIPAGE}" + 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 ALL DEPENDS "${MANPAGE}") diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 16c203608df..252e9e86a07 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -103,11 +103,16 @@ 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 50d13527061..81a4afe1bcf 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -31,13 +31,15 @@ man_MANS = $(MANPAGE) include Makefile.inc -EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl $(SUPPORT) CMakeLists.txt mainpage.idx +EXTRA_DIST = $(DPAGES) MANPAGE.md $(SUPPORT) CMakeLists.txt mainpage.idx GEN = $(GN_$(V)) GN_0 = @echo " GENERATE" $@; GN_1 = GN_ = $(GN_0) +MANAGEN=$(abs_top_srcdir)/scripts/managen + if BUILD_DOCS CLEANFILES = $(MANPAGE) $(ASCIIPAGE) @@ -45,11 +47,14 @@ all: $(MANPAGE) $(ASCIIPAGE) endif -$(MANPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl - $(GEN)(rm -f $(MANPAGE) && (cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES)) > manpage.tmp.$$$$ && mv manpage.tmp.$$$$ $(MANPAGE)) +$(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 gen.pl - $(GEN)(rm -f $(ASCIIPAGE) && (cd $(srcdir) && @PERL@ ./gen.pl ascii $(DPAGES)) > asciipage.tmp.$$$$ && mv asciipage.tmp.$$$$ $(ASCIIPAGE)) +$(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: - ./gen.pl listhelp $(DPAGES) > $(top_builddir)/src/tool_listhelp.c + $(MANAGEN) listhelp $(DPAGES) > $(top_builddir)/src/tool_listhelp.c + +listcats: + @$(MANAGEN) listcats $(DPAGES) diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 2d136d8ed37..ad48771942d 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -23,7 +23,7 @@ ########################################################################### EXTRA_DIST = coverage.sh completion.pl firefox-db2pem.sh checksrc.pl \ - mk-ca-bundle.pl schemetable.c cd2nroff nroff2cd cdall cd2cd + mk-ca-bundle.pl schemetable.c cd2nroff nroff2cd cdall cd2cd managen ZSH_FUNCTIONS_DIR = @ZSH_FUNCTIONS_DIR@ FISH_FUNCTIONS_DIR = @FISH_FUNCTIONS_DIR@ diff --git a/docs/cmdline-opts/gen.pl b/scripts/managen similarity index 99% rename from docs/cmdline-opts/gen.pl rename to scripts/managen index eeaabd2ecdc..d950bd5866e 100755 --- a/docs/cmdline-opts/gen.pl +++ b/scripts/managen @@ -27,7 +27,7 @@ This script generates the manpage. -Example: gen.pl [files] > curl.1 +Example: managen [files] > curl.1 Dev notes: @@ -1031,7 +1031,7 @@ sub mainpage { .\\" * .\\" ************************************************************************** .\\" -.\\" DO NOT EDIT. Generated by the curl project gen.pl man page generator. +.\\" DO NOT EDIT. Generated by the curl project managen man page generator. .\\" .TH curl 1 "$date" "curl $version" "curl Manual" HEADER @@ -1108,7 +1108,7 @@ sub getargs { return; } - print "Usage: gen.pl [files]\n"; + print "Usage: managen [files]\n"; } #------------------------------------------------------------------------ diff --git a/src/tool_help.h b/src/tool_help.h index a7906266e34..a05cd84581c 100644 --- a/src/tool_help.h +++ b/src/tool_help.h @@ -40,8 +40,7 @@ struct helptxt { /* * The bitmask output is generated with the following command ------------------------------------------------------------ - cd $srcroot/docs/cmdline-opts - ./gen.pl listcats *.d + make -C docs/cmdline-opts listcats */ #define CURLHELP_HIDDEN 1u << 0u diff --git a/tests/data/test1478 b/tests/data/test1478 index b489ac03894..c05766740bf 100644 --- a/tests/data/test1478 +++ b/tests/data/test1478 @@ -19,7 +19,7 @@ src/tool_listhelp.c is in sync with docs/cmdline-opts -%SRCDIR/../docs/cmdline-opts/gen.pl listhelp %SRCDIR/../docs/cmdline-opts/*.md +%SRCDIR/../scripts/managen listhelp %SRCDIR/../docs/cmdline-opts/*.md From fcef00db1a196864e411a60c07517702f2b4fa0f Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 8 Mar 2024 10:45:14 +0100 Subject: [PATCH 460/509] lib: keep conn IP information together new struct ip_quadruple for holding local/remote addr+port - used in data->info and conn and cf-socket.c - copy back and forth complete struct - add 'secondary' to conn - use secondary in reporting success for ftp 2nd connection Reported-by: DasKutti on github Fixes #13084 Closes #13090 --- lib/cf-haproxy.c | 8 ++-- lib/cf-socket.c | 82 +++++++++++++++++------------------------ lib/cf-socket.h | 9 ++--- lib/cfilters.c | 2 +- lib/conncache.c | 2 +- lib/connect.c | 20 +++++----- lib/connect.h | 3 +- lib/ftp.c | 8 ++-- lib/getinfo.c | 16 ++++---- lib/ldap.c | 14 +++---- lib/multi.c | 10 ++--- lib/socks.c | 4 +- lib/url.c | 39 +++++++++++--------- lib/url.h | 5 ++- lib/urldata.h | 39 ++++++++++---------- lib/vquic/curl_msh3.c | 21 ----------- lib/vquic/curl_ngtcp2.c | 11 ++---- lib/vquic/curl_osslq.c | 20 ++++------ lib/vquic/curl_quiche.c | 11 ++---- lib/vquic/vquic.c | 24 +++++------- 20 files changed, 148 insertions(+), 200 deletions(-) diff --git a/lib/cf-haproxy.c b/lib/cf-haproxy.c index 90532952b18..404392291cc 100644 --- a/lib/cf-haproxy.c +++ b/lib/cf-haproxy.c @@ -86,14 +86,14 @@ static CURLcode cf_haproxy_date_out_set(struct Curl_cfilter*cf, if(data->set.str[STRING_HAPROXY_CLIENT_IP]) client_ip = data->set.str[STRING_HAPROXY_CLIENT_IP]; else - client_ip = data->info.conn_local_ip; + client_ip = data->info.primary.local_ip; result = Curl_dyn_addf(&ctx->data_out, "PROXY %s %s %s %i %i\r\n", tcp_version, client_ip, - data->info.conn_primary_ip, - data->info.conn_local_port, - data->info.conn_primary_port); + data->info.primary.remote_ip, + data->info.primary.local_port, + data->info.primary.remote_port); #ifdef USE_UNIX_SOCKETS } diff --git a/lib/cf-socket.c b/lib/cf-socket.c index 33ca7e78180..1de51000627 100644 --- a/lib/cf-socket.c +++ b/lib/cf-socket.c @@ -776,10 +776,7 @@ struct cf_socket_ctx { struct Curl_sockaddr_ex addr; /* address to connect to */ curl_socket_t sock; /* current attempt socket */ struct bufq recvbuf; /* used when `buffer_recv` is set */ - char r_ip[MAX_IPADR_LEN]; /* remote IP as string */ - int r_port; /* remote port number */ - char l_ip[MAX_IPADR_LEN]; /* local IP as string */ - int l_port; /* local port number */ + struct ip_quadruple ip; /* The IP quadruple 2x(addr+port) */ struct curltime started_at; /* when socket was created */ struct curltime connected_at; /* when socket connected/got first byte */ struct curltime first_byte_at; /* when first byte was recvd */ @@ -941,7 +938,7 @@ static CURLcode set_local_ip(struct Curl_cfilter *cf, return CURLE_FAILED_INIT; } if(!Curl_addr2string((struct sockaddr*)&ssloc, slen, - ctx->l_ip, &ctx->l_port)) { + ctx->ip.local_ip, &ctx->ip.local_port)) { failf(data, "ssloc inet_ntop() failed with errno %d: %s", errno, Curl_strerror(errno, buffer, sizeof(buffer))); return CURLE_FAILED_INIT; @@ -962,7 +959,7 @@ static CURLcode set_remote_ip(struct Curl_cfilter *cf, /* store remote address and port used in this connection attempt */ if(!Curl_addr2string(&ctx->addr.sa_addr, ctx->addr.addrlen, - ctx->r_ip, &ctx->r_port)) { + ctx->ip.remote_ip, &ctx->ip.remote_port)) { char buffer[STRERROR_LEN]; ctx->error = errno; @@ -997,11 +994,11 @@ static CURLcode cf_socket_open(struct Curl_cfilter *cf, #ifdef ENABLE_IPV6 if(ctx->addr.family == AF_INET6) { set_ipv6_v6only(ctx->sock, 0); - infof(data, " Trying [%s]:%d...", ctx->r_ip, ctx->r_port); + infof(data, " Trying [%s]:%d...", ctx->ip.remote_ip, ctx->ip.remote_port); } else #endif - infof(data, " Trying %s:%d...", ctx->r_ip, ctx->r_port); + infof(data, " Trying %s:%d...", ctx->ip.remote_ip, ctx->ip.remote_port); #ifdef ENABLE_IPV6 is_tcp = (ctx->addr.family == AF_INET @@ -1167,9 +1164,9 @@ static CURLcode cf_tcp_connect(struct Curl_cfilter *cf, error = SOCKERRNO; set_local_ip(cf, data); CURL_TRC_CF(data, cf, "local address %s port %d...", - ctx->l_ip, ctx->l_port); + ctx->ip.local_ip, ctx->ip.local_port); if(-1 == rc) { - result = socket_connect_result(data, ctx->r_ip, error); + result = socket_connect_result(data, ctx->ip.remote_ip, error); goto out; } } @@ -1214,7 +1211,8 @@ static CURLcode cf_tcp_connect(struct Curl_cfilter *cf, { char buffer[STRERROR_LEN]; infof(data, "connect to %s port %u from %s port %d failed: %s", - ctx->r_ip, ctx->r_port, ctx->l_ip, ctx->l_port, + ctx->ip.remote_ip, ctx->ip.remote_port, + ctx->ip.local_ip, ctx->ip.local_port, Curl_strerror(ctx->error, buffer, sizeof(buffer))); } #endif @@ -1234,10 +1232,11 @@ static void cf_socket_get_host(struct Curl_cfilter *cf, const char **pdisplay_host, int *pport) { + struct cf_socket_ctx *ctx = cf->ctx; (void)data; *phost = cf->conn->host.name; *pdisplay_host = cf->conn->host.dispname; - *pport = cf->conn->port; + *pport = ctx->ip.remote_port; } static void cf_socket_adjust_pollset(struct Curl_cfilter *cf, @@ -1436,31 +1435,24 @@ static ssize_t cf_socket_recv(struct Curl_cfilter *cf, struct Curl_easy *data, return nread; } -static void conn_set_primary_ip(struct Curl_cfilter *cf, - struct Curl_easy *data) -{ - struct cf_socket_ctx *ctx = cf->ctx; - - (void)data; - DEBUGASSERT(sizeof(ctx->r_ip) == sizeof(cf->conn->primary_ip)); - memcpy(cf->conn->primary_ip, ctx->r_ip, sizeof(cf->conn->primary_ip)); -} - static void cf_socket_active(struct Curl_cfilter *cf, struct Curl_easy *data) { struct cf_socket_ctx *ctx = cf->ctx; /* use this socket from now on */ cf->conn->sock[cf->sockindex] = ctx->sock; - /* the first socket info gets set at conn and data */ + set_local_ip(cf, data); + if(cf->sockindex == SECONDARYSOCKET) + cf->conn->secondary = ctx->ip; + else + cf->conn->primary = ctx->ip; + /* the first socket info gets some specials */ if(cf->sockindex == FIRSTSOCKET) { cf->conn->remote_addr = &ctx->addr; #ifdef ENABLE_IPV6 cf->conn->bits.ipv6 = (ctx->addr.family == AF_INET6)? TRUE : FALSE; #endif - conn_set_primary_ip(cf, data); - set_local_ip(cf, data); - Curl_persistconninfo(data, cf->conn, ctx->l_ip, ctx->l_port); + Curl_persistconninfo(data, cf->conn, &ctx->ip); /* buffering is currently disabled by default because we have stalls * in parallel transfers where not all buffered data is consumed and no * socket events happen. @@ -1483,7 +1475,7 @@ static CURLcode cf_socket_cntrl(struct Curl_cfilter *cf, cf_socket_active(cf, data); break; case CF_CTRL_DATA_SETUP: - Curl_persistconninfo(data, cf->conn, ctx->l_ip, ctx->l_port); + Curl_persistconninfo(data, cf->conn, &ctx->ip); break; case CF_CTRL_FORGET_SOCKET: ctx->sock = CURL_SOCKET_BAD; @@ -1640,7 +1632,7 @@ static CURLcode cf_udp_setup_quic(struct Curl_cfilter *cf, #else rc = connect(ctx->sock, &ctx->addr.sa_addr, ctx->addr.addrlen); if(-1 == rc) { - return socket_connect_result(data, ctx->r_ip, SOCKERRNO); + return socket_connect_result(data, ctx->ip.remote_ip, SOCKERRNO); } ctx->sock_connected = TRUE; #endif @@ -1648,7 +1640,8 @@ static CURLcode cf_udp_setup_quic(struct Curl_cfilter *cf, CURL_TRC_CF(data, cf, "%s socket %" CURL_FORMAT_SOCKET_T " connected: [%s:%d] -> [%s:%d]", (ctx->transport == TRNSPRT_QUIC)? "QUIC" : "UDP", - ctx->sock, ctx->l_ip, ctx->l_port, ctx->r_ip, ctx->r_port); + ctx->sock, ctx->ip.local_ip, ctx->ip.local_port, + ctx->ip.remote_ip, ctx->ip.remote_port); (void)curlx_nonblock(ctx->sock, TRUE); switch(ctx->addr.family) { @@ -1698,7 +1691,7 @@ static CURLcode cf_udp_connect(struct Curl_cfilter *cf, goto out; CURL_TRC_CF(data, cf, "cf_udp_connect(), opened socket=%" CURL_FORMAT_SOCKET_T " (%s:%d)", - ctx->sock, ctx->l_ip, ctx->l_port); + ctx->sock, ctx->ip.local_ip, ctx->ip.local_port); } else { CURL_TRC_CF(data, cf, "cf_udp_connect(), opened socket=%" @@ -1894,8 +1887,8 @@ static void set_accepted_remote_ip(struct Curl_cfilter *cf, struct Curl_sockaddr_storage ssrem; curl_socklen_t plen; - ctx->r_ip[0] = 0; - ctx->r_port = 0; + ctx->ip.remote_ip[0] = 0; + ctx->ip.remote_port = 0; plen = sizeof(ssrem); memset(&ssrem, 0, plen); if(getpeername(ctx->sock, (struct sockaddr*) &ssrem, &plen)) { @@ -1905,14 +1898,14 @@ static void set_accepted_remote_ip(struct Curl_cfilter *cf, return; } if(!Curl_addr2string((struct sockaddr*)&ssrem, plen, - ctx->r_ip, &ctx->r_port)) { + ctx->ip.remote_ip, &ctx->ip.remote_port)) { failf(data, "ssrem inet_ntop() failed with errno %d: %s", errno, Curl_strerror(errno, buffer, sizeof(buffer))); return; } #else - ctx->r_ip[0] = 0; - ctx->r_port = 0; + ctx->ip.remote_ip[0] = 0; + ctx->ip.remote_port = 0; (void)data; #endif } @@ -1941,7 +1934,7 @@ CURLcode Curl_conn_tcp_accepted_set(struct Curl_easy *data, cf->connected = TRUE; CURL_TRC_CF(data, cf, "accepted_set(sock=%" CURL_FORMAT_SOCKET_T ", remote=%s port=%d)", - ctx->sock, ctx->r_ip, ctx->r_port); + ctx->sock, ctx->ip.remote_ip, ctx->ip.remote_port); return CURLE_OK; } @@ -1961,9 +1954,9 @@ CURLcode Curl_cf_socket_peek(struct Curl_cfilter *cf, struct Curl_easy *data, curl_socket_t *psock, const struct Curl_sockaddr_ex **paddr, - const char **pr_ip_str, int *pr_port, - const char **pl_ip_str, int *pl_port) + struct ip_quadruple *pip) { + (void)data; if(cf_is_socket(cf) && cf->ctx) { struct cf_socket_ctx *ctx = cf->ctx; @@ -1971,17 +1964,8 @@ CURLcode Curl_cf_socket_peek(struct Curl_cfilter *cf, *psock = ctx->sock; if(paddr) *paddr = &ctx->addr; - if(pr_ip_str) - *pr_ip_str = ctx->r_ip; - if(pr_port) - *pr_port = ctx->r_port; - if(pl_port ||pl_ip_str) { - set_local_ip(cf, data); - if(pl_ip_str) - *pl_ip_str = ctx->l_ip; - if(pl_port) - *pl_port = ctx->l_port; - } + if(pip) + *pip = ctx->ip; return CURLE_OK; } return CURLE_FAILED_INIT; diff --git a/lib/cf-socket.h b/lib/cf-socket.h index 87e0f30a251..058af500989 100644 --- a/lib/cf-socket.h +++ b/lib/cf-socket.h @@ -33,6 +33,7 @@ struct Curl_cfilter; struct Curl_easy; struct connectdata; struct Curl_sockaddr_ex; +struct ip_quadruple; /* * The Curl_sockaddr_ex structure is basically libcurl's external API @@ -153,18 +154,14 @@ CURLcode Curl_conn_tcp_accepted_set(struct Curl_easy *data, * The filter owns all returned values. * @param psock pointer to hold socket descriptor or NULL * @param paddr pointer to hold addr reference or NULL - * @param pr_ip_str pointer to hold remote addr as string or NULL - * @param pr_port pointer to hold remote port number or NULL - * @param pl_ip_str pointer to hold local addr as string or NULL - * @param pl_port pointer to hold local port number or NULL + * @param pip pointer to get IP quadruple or NULL * Returns error if the filter is of invalid type. */ CURLcode Curl_cf_socket_peek(struct Curl_cfilter *cf, struct Curl_easy *data, curl_socket_t *psock, const struct Curl_sockaddr_ex **paddr, - const char **pr_ip_str, int *pr_port, - const char **pl_ip_str, int *pl_port); + struct ip_quadruple *pip); extern struct Curl_cftype Curl_cft_tcp; extern struct Curl_cftype Curl_cft_udp; diff --git a/lib/cfilters.c b/lib/cfilters.c index 4e4c8e569c0..32329cfb448 100644 --- a/lib/cfilters.c +++ b/lib/cfilters.c @@ -67,7 +67,7 @@ void Curl_cf_def_get_host(struct Curl_cfilter *cf, struct Curl_easy *data, else { *phost = cf->conn->host.name; *pdisplay_host = cf->conn->host.dispname; - *pport = cf->conn->port; + *pport = cf->conn->primary.remote_port; } } diff --git a/lib/conncache.c b/lib/conncache.c index 63128e1a343..0d260908584 100644 --- a/lib/conncache.c +++ b/lib/conncache.c @@ -131,7 +131,7 @@ static void hashkey(struct connectdata *conn, char *buf, size_t len) #ifndef CURL_DISABLE_PROXY if(conn->bits.httpproxy && !conn->bits.tunnel_proxy) { hostname = conn->http_proxy.host.name; - port = conn->port; + port = conn->primary.remote_port; } else #endif diff --git a/lib/connect.c b/lib/connect.c index 5e0f8b23923..e457006c060 100644 --- a/lib/connect.c +++ b/lib/connect.c @@ -145,19 +145,19 @@ timediff_t Curl_timeleft(struct Curl_easy *data, /* Copies connection info into the transfer handle to make it available when the transfer handle is no longer associated with the connection. */ void Curl_persistconninfo(struct Curl_easy *data, struct connectdata *conn, - char *local_ip, int local_port) + struct ip_quadruple *ip) { - memcpy(data->info.conn_primary_ip, conn->primary_ip, MAX_IPADR_LEN); - if(local_ip && local_ip[0]) - memcpy(data->info.conn_local_ip, local_ip, MAX_IPADR_LEN); - else - data->info.conn_local_ip[0] = 0; + if(ip) + data->info.primary = *ip; + else { + memset(&data->info.primary, 0, sizeof(data->info.primary)); + data->info.primary.remote_port = -1; + data->info.primary.local_port = -1; + } data->info.conn_scheme = conn->handler->scheme; /* conn_protocol can only provide "old" protocols */ data->info.conn_protocol = (conn->handler->protocol) & CURLPROTO_MASK; - data->info.conn_primary_port = conn->port; data->info.conn_remote_port = conn->remote_port; - data->info.conn_local_port = local_port; data->info.used_proxy = #ifdef CURL_DISABLE_PROXY 0 @@ -728,7 +728,7 @@ static CURLcode is_connected(struct Curl_cfilter *cf, failf(data, "Failed to connect to %s port %u after " "%" CURL_FORMAT_TIMEDIFF_T " ms: %s", - hostname, conn->port, + hostname, conn->primary.remote_port, Curl_timediff(now, data->progress.t_startsingle), curl_easy_strerror(result)); @@ -918,7 +918,7 @@ static CURLcode cf_he_connect(struct Curl_cfilter *cf, if(cf->conn->handler->protocol & PROTO_FAMILY_SSH) Curl_pgrsTime(data, TIMER_APPCONNECT); /* we're connected already */ - Curl_verboseconnect(data, cf->conn); + Curl_verboseconnect(data, cf->conn, cf->sockindex); data->info.numconnects++; /* to track the # of connections made */ } break; diff --git a/lib/connect.h b/lib/connect.h index 58264bdba48..00efe6f34e4 100644 --- a/lib/connect.h +++ b/lib/connect.h @@ -30,6 +30,7 @@ #include "timeval.h" struct Curl_dns_entry; +struct ip_quadruple; /* generic function that returns how much time there's left to run, according to the timeouts set */ @@ -52,7 +53,7 @@ bool Curl_addr2string(struct sockaddr *sa, curl_socklen_t salen, char *addr, int *port); void Curl_persistconninfo(struct Curl_easy *data, struct connectdata *conn, - char *local_ip, int local_port); + struct ip_quadruple *ip); /* * Curl_conncontrol() marks the end of a connection/stream. The 'closeit' diff --git a/lib/ftp.c b/lib/ftp.c index 29a1476da4c..5bbdeb05404 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -1903,7 +1903,7 @@ static char *control_address(struct connectdata *conn) if(conn->bits.tunnel_proxy || conn->bits.socksproxy) return conn->host.name; #endif - return conn->primary_ip; + return conn->primary.remote_ip; } static bool match_pasv_6nums(const char *p, @@ -2040,14 +2040,14 @@ static CURLcode ftp_state_pasv_resp(struct Curl_easy *data, */ const char * const host_name = conn->bits.socksproxy ? conn->socks_proxy.host.name : conn->http_proxy.host.name; - rc = Curl_resolv(data, host_name, conn->port, FALSE, &addr); + rc = Curl_resolv(data, host_name, conn->primary.remote_port, FALSE, &addr); if(rc == CURLRESOLV_PENDING) /* BLOCKING, ignores the return code but 'addr' will be NULL in case of failure */ (void)Curl_resolver_wait_resolv(data, &addr); - connectport = - (unsigned short)conn->port; /* we connect to the proxy's port */ + /* we connect to the proxy's port */ + connectport = (unsigned short)conn->primary.remote_port; if(!addr) { failf(data, "Can't resolve proxy host %s:%hu", host_name, connectport); diff --git a/lib/getinfo.c b/lib/getinfo.c index aaf17713f3e..dd43643d8ba 100644 --- a/lib/getinfo.c +++ b/lib/getinfo.c @@ -76,10 +76,10 @@ CURLcode Curl_initinfo(struct Curl_easy *data) free(info->wouldredirect); info->wouldredirect = NULL; - info->conn_primary_ip[0] = '\0'; - info->conn_local_ip[0] = '\0'; - info->conn_primary_port = 0; - info->conn_local_port = 0; + info->primary.remote_ip[0] = '\0'; + info->primary.local_ip[0] = '\0'; + info->primary.remote_port = 0; + info->primary.local_port = 0; info->retry_after = 0; info->conn_scheme = 0; @@ -153,12 +153,12 @@ static CURLcode getinfo_char(struct Curl_easy *data, CURLINFO info, break; case CURLINFO_PRIMARY_IP: /* Return the ip address of the most recent (primary) connection */ - *param_charp = data->info.conn_primary_ip; + *param_charp = data->info.primary.remote_ip; break; case CURLINFO_LOCAL_IP: /* Return the source/local ip address of the most recent (primary) connection */ - *param_charp = data->info.conn_local_ip; + *param_charp = data->info.primary.local_ip; break; case CURLINFO_RTSP_SESSION_ID: *param_charp = data->set.str[STRING_RTSP_SESSION_ID]; @@ -284,11 +284,11 @@ static CURLcode getinfo_long(struct Curl_easy *data, CURLINFO info, break; case CURLINFO_PRIMARY_PORT: /* Return the (remote) port of the most recent (primary) connection */ - *param_longp = data->info.conn_primary_port; + *param_longp = data->info.primary.remote_port; break; case CURLINFO_LOCAL_PORT: /* Return the local port of the most recent (primary) connection */ - *param_longp = data->info.conn_local_port; + *param_longp = data->info.primary.local_port; break; case CURLINFO_PROXY_ERROR: *param_longp = (long)data->info.pxcode; diff --git a/lib/ldap.c b/lib/ldap.c index 53497a5c41e..394fd32d4a1 100644 --- a/lib/ldap.c +++ b/lib/ldap.c @@ -371,7 +371,7 @@ static CURLcode ldap_do(struct Curl_easy *data, bool *done) #ifdef HAVE_LDAP_SSL #ifdef USE_WIN32_LDAP /* Win32 LDAP SDK doesn't support insecure mode without CA! */ - server = ldap_sslinit(host, conn->port, 1); + server = ldap_sslinit(host, conn->primary.remote_port, 1); ldap_set_option(server, LDAP_OPT_SSL, LDAP_OPT_ON); #else int ldap_option; @@ -417,10 +417,10 @@ static CURLcode ldap_do(struct Curl_easy *data, bool *done) result = CURLE_SSL_CERTPROBLEM; goto quit; } - server = ldapssl_init(host, conn->port, 1); + server = ldapssl_init(host, conn->primary.remote_port, 1); if(!server) { failf(data, "LDAP local: Cannot connect to %s:%u", - conn->host.dispname, conn->port); + conn->host.dispname, conn->primary.remote_port); result = CURLE_COULDNT_CONNECT; goto quit; } @@ -458,10 +458,10 @@ static CURLcode ldap_do(struct Curl_easy *data, bool *done) result = CURLE_SSL_CERTPROBLEM; goto quit; } - server = ldap_init(host, conn->port); + server = ldap_init(host, conn->primary.remote_port); if(!server) { failf(data, "LDAP local: Cannot connect to %s:%u", - conn->host.dispname, conn->port); + conn->host.dispname, conn->primary.remote_port); result = CURLE_COULDNT_CONNECT; goto quit; } @@ -499,10 +499,10 @@ static CURLcode ldap_do(struct Curl_easy *data, bool *done) goto quit; } else { - server = ldap_init(host, conn->port); + server = ldap_init(host, conn->primary.remote_port); if(!server) { failf(data, "LDAP local: Cannot connect to %s:%u", - conn->host.dispname, conn->port); + conn->host.dispname, conn->primary.remote_port); result = CURLE_COULDNT_CONNECT; goto quit; } diff --git a/lib/multi.c b/lib/multi.c index 0cf4723405f..800a7c1e466 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -1987,7 +1987,7 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, hostname = conn->host.name; /* check if we have the name resolved by now */ - dns = Curl_fetch_addr(data, hostname, (int)conn->port); + dns = Curl_fetch_addr(data, hostname, conn->primary.remote_port); if(dns) { #ifdef CURLRES_ASYNCH @@ -2133,10 +2133,10 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, /* call the prerequest callback function */ Curl_set_in_callback(data, true); prereq_rc = data->set.fprereq(data->set.prereq_userp, - data->info.conn_primary_ip, - data->info.conn_local_ip, - data->info.conn_primary_port, - data->info.conn_local_port); + data->info.primary.remote_ip, + data->info.primary.local_ip, + data->info.primary.remote_port, + data->info.primary.local_port); Curl_set_in_callback(data, false); if(prereq_rc != CURL_PREREQFUNC_OK) { failf(data, "operation aborted by pre-request callback"); diff --git a/lib/socks.c b/lib/socks.c index ecd2f7eab53..bd5962a8701 100644 --- a/lib/socks.c +++ b/lib/socks.c @@ -341,7 +341,7 @@ static CURLproxycode do_SOCKS4(struct Curl_cfilter *cf, case CONNECT_RESOLVING: /* check if we have the name resolved by now */ - dns = Curl_fetch_addr(data, sx->hostname, (int)conn->port); + dns = Curl_fetch_addr(data, sx->hostname, conn->primary.remote_port); if(dns) { #ifdef CURLRES_ASYNCH @@ -1175,7 +1175,7 @@ static CURLcode socks_proxy_cf_connect(struct Curl_cfilter *cf, result = connect_SOCKS(cf, sx, data); if(!result && sx->state == CONNECT_DONE) { cf->connected = TRUE; - Curl_verboseconnect(data, conn); + Curl_verboseconnect(data, conn, cf->sockindex); socks_proxy_cf_free(cf); } diff --git a/lib/url.c b/lib/url.c index f457e276640..7c1621cf26a 100644 --- a/lib/url.c +++ b/lib/url.c @@ -1002,9 +1002,9 @@ ConnectionExists(struct Curl_easy *data, if(!canmultiplex) { if(Curl_resolver_asynch() && - /* primary_ip[0] is NUL only if the resolving of the name hasn't + /* remote_ip[0] is NUL only if the resolving of the name hasn't completed yet and until then we don't reuse this connection */ - !check->primary_ip[0]) + !check->primary.remote_ip[0]) continue; } @@ -1327,11 +1327,15 @@ ConnectionExists(struct Curl_easy *data, */ #ifndef CURL_DISABLE_VERBOSE_STRINGS void Curl_verboseconnect(struct Curl_easy *data, - struct connectdata *conn) + struct connectdata *conn, int sockindex) { - if(data->set.verbose) + if(data->set.verbose && sockindex == SECONDARYSOCKET) + infof(data, "Connected 2nd connection to %s port %u", + conn->secondary.remote_ip, conn->secondary.remote_port); + else infof(data, "Connected to %s (%s) port %u", - CURL_CONN_HOST_DISPNAME(conn), conn->primary_ip, conn->port); + CURL_CONN_HOST_DISPNAME(conn), conn->primary.remote_ip, + conn->primary.remote_port); } #endif @@ -1351,7 +1355,7 @@ static struct connectdata *allocate_conn(struct Curl_easy *data) conn->sockfd = CURL_SOCKET_BAD; conn->writesockfd = CURL_SOCKET_BAD; conn->connection_id = -1; /* no ID */ - conn->port = -1; /* unknown at this point */ + conn->primary.remote_port = -1; /* unknown at this point */ conn->remote_port = -1; /* unknown at this point */ /* Default protocol-independent behavior doesn't support persistent @@ -1964,7 +1968,7 @@ static CURLcode parseurlandfillconn(struct Curl_easy *data, } else { unsigned long port = strtoul(data->state.up.port, NULL, 10); - conn->port = conn->remote_port = + conn->primary.remote_port = conn->remote_port = (data->set.use_port && data->state.allow_port) ? data->set.use_port : curlx_ultous(port); } @@ -2040,10 +2044,10 @@ static CURLcode setup_connection_internals(struct Curl_easy *data, p = conn->handler; /* May have changed. */ } - if(conn->port < 0) + if(conn->primary.remote_port < 0) /* we check for -1 here since if proxy was detected already, this was very likely already set to the proxy port */ - conn->port = p->defport; + conn->primary.remote_port = p->defport; return CURLE_OK; } @@ -2289,8 +2293,9 @@ static CURLcode parse_proxy(struct Curl_easy *data, } if(port >= 0) { proxyinfo->port = port; - if(conn->port < 0 || sockstype || !conn->socks_proxy.host.rawalloc) - conn->port = port; + if(conn->primary.remote_port < 0 || sockstype || + !conn->socks_proxy.host.rawalloc) + conn->primary.remote_port = port; } /* now, clone the proxy host name */ @@ -3188,8 +3193,8 @@ static CURLcode resolve_proxy(struct Curl_easy *data, if(!conn->hostname_resolve) return CURLE_OUT_OF_MEMORY; - rc = Curl_resolv_timeout(data, conn->hostname_resolve, (int)conn->port, - &hostaddr, timeout_ms); + rc = Curl_resolv_timeout(data, conn->hostname_resolve, + conn->primary.remote_port, &hostaddr, timeout_ms); conn->dns_entry = hostaddr; if(rc == CURLRESOLV_PENDING) *async = TRUE; @@ -3219,7 +3224,7 @@ static CURLcode resolve_host(struct Curl_easy *data, /* If not connecting via a proxy, extract the port from the URL, if it is * there, thus overriding any defaults that might have been set above. */ - conn->port = conn->bits.conn_to_port ? conn->conn_to_port : + conn->primary.remote_port = conn->bits.conn_to_port ? conn->conn_to_port : conn->remote_port; /* Resolve target host right on */ @@ -3227,8 +3232,8 @@ static CURLcode resolve_host(struct Curl_easy *data, if(!conn->hostname_resolve) return CURLE_OUT_OF_MEMORY; - rc = Curl_resolv_timeout(data, conn->hostname_resolve, (int)conn->port, - &hostaddr, timeout_ms); + rc = Curl_resolv_timeout(data, conn->hostname_resolve, + conn->primary.remote_port, &hostaddr, timeout_ms); conn->dns_entry = hostaddr; if(rc == CURLRESOLV_PENDING) *async = TRUE; @@ -3565,7 +3570,7 @@ static CURLcode create_conn(struct Curl_easy *data, /* this is supposed to be the connect function so we better at least check that the file is present here! */ DEBUGASSERT(conn->handler->connect_it); - Curl_persistconninfo(data, conn, NULL, -1); + Curl_persistconninfo(data, conn, NULL); result = conn->handler->connect_it(data, &done); /* Setup a "faked" transfer that'll do nothing */ diff --git a/lib/url.h b/lib/url.h index 6d369508337..198a00ad172 100644 --- a/lib/url.h +++ b/lib/url.h @@ -58,9 +58,10 @@ const struct Curl_handler *Curl_getn_scheme_handler(const char *scheme, specified */ #ifdef CURL_DISABLE_VERBOSE_STRINGS -#define Curl_verboseconnect(x,y) Curl_nop_stmt +#define Curl_verboseconnect(x,y,z) Curl_nop_stmt #else -void Curl_verboseconnect(struct Curl_easy *data, struct connectdata *conn); +void Curl_verboseconnect(struct Curl_easy *data, struct connectdata *conn, + int sockindex); #endif #if defined(USE_HTTP2) || defined(USE_HTTP3) diff --git a/lib/urldata.h b/lib/urldata.h index 2e3cf345cfc..ef787972883 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -759,6 +759,13 @@ struct Curl_handler { #define CONNRESULT_NONE 0 /* No extra information. */ #define CONNRESULT_DEAD (1<<0) /* The connection is dead. */ +struct ip_quadruple { + char remote_ip[MAX_IPADR_LEN]; + char local_ip[MAX_IPADR_LEN]; + int remote_port; + int local_port; +}; + struct proxy_info { struct hostname host; int port; @@ -814,14 +821,13 @@ struct connectdata { struct proxy_info socks_proxy; struct proxy_info http_proxy; #endif - /* 'primary_ip' and 'primary_port' get filled with peer's numerical - ip address and port number whenever an outgoing connection is - *attempted* from the primary socket to a remote address. When more - than one address is tried for a connection these will hold data + /* 'primary' and 'secondary' get filled with IP quadruple + (local/remote numerical ip address and port) whenever a is *attempted*. + When more than one address is tried for a connection these will hold data for the last attempt. When the connection is actually established these are updated with data which comes directly from the socket. */ - - char primary_ip[MAX_IPADR_LEN]; + struct ip_quadruple primary; + struct ip_quadruple secondary; char *user; /* user name string, allocated */ char *passwd; /* password string, allocated */ char *options; /* options string, allocated */ @@ -967,7 +973,6 @@ struct connectdata { int socks5_gssapi_enctype; #endif /* The field below gets set in connect.c:connecthost() */ - int port; /* which port to use locally - to connect to */ int remote_port; /* the remote port, not the proxy port! */ int conn_to_port; /* the remote port to connect to. valid only if bits.conn_to_port is set */ @@ -1022,22 +1027,16 @@ struct PureInfo { curl_off_t retry_after; /* info from Retry-After: header */ unsigned int header_size; /* size of read header(s) in bytes */ - /* PureInfo members 'conn_primary_ip', 'conn_primary_port', 'conn_local_ip' - and, 'conn_local_port' are copied over from the connectdata struct in - order to allow curl_easy_getinfo() to return this information even when - the session handle is no longer associated with a connection, and also - allow curl_easy_reset() to clear this information from the session handle - without disturbing information which is still alive, and that might be - reused, in the connection cache. */ - - char conn_primary_ip[MAX_IPADR_LEN]; - int conn_primary_port; /* this is the destination port to the connection, - which might have been a proxy */ + /* PureInfo primary ip_quadruple is copied over from the connectdata + struct in order to allow curl_easy_getinfo() to return this information + even when the session handle is no longer associated with a connection, + and also allow curl_easy_reset() to clear this information from the + session handle without disturbing information which is still alive, and + that might be reused, in the connection cache. */ + struct ip_quadruple primary; int conn_remote_port; /* this is the "remote port", which is the port number of the used URL, independent of proxy or not */ - char conn_local_ip[MAX_IPADR_LEN]; - int conn_local_port; const char *conn_scheme; unsigned int conn_protocol; struct curl_certinfo certs; /* info about the certs. Asked for with diff --git a/lib/vquic/curl_msh3.c b/lib/vquic/curl_msh3.c index 7674bc1fcfe..a52bbdd061d 100644 --- a/lib/vquic/curl_msh3.c +++ b/lib/vquic/curl_msh3.c @@ -722,23 +722,6 @@ static bool cf_msh3_data_pending(struct Curl_cfilter *cf, return pending; } -static void cf_msh3_active(struct Curl_cfilter *cf, struct Curl_easy *data) -{ - struct cf_msh3_ctx *ctx = cf->ctx; - - /* use this socket from now on */ - cf->conn->sock[cf->sockindex] = ctx->sock[SP_LOCAL]; - /* the first socket info gets set at conn and data */ - if(cf->sockindex == FIRSTSOCKET) { - cf->conn->remote_addr = &ctx->addr; - #ifdef ENABLE_IPV6 - cf->conn->bits.ipv6 = (ctx->addr.family == AF_INET6)? TRUE : FALSE; - #endif - Curl_persistconninfo(data, cf->conn, ctx->l_ip, ctx->l_port); - } - ctx->active = TRUE; -} - static CURLcode h3_data_pause(struct Curl_cfilter *cf, struct Curl_easy *data, bool pause) @@ -785,10 +768,6 @@ static CURLcode cf_msh3_data_event(struct Curl_cfilter *cf, } } break; - case CF_CTRL_CONN_INFO_UPDATE: - CURL_TRC_CF(data, cf, "req: update info"); - cf_msh3_active(cf, data); - break; default: break; } diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index b49956ab389..54dfbeeaa79 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -1980,8 +1980,7 @@ static CURLcode cf_connect_start(struct Curl_cfilter *cf, if(result) return result; - Curl_cf_socket_peek(cf->next, data, &ctx->q.sockfd, - &sockaddr, NULL, NULL, NULL, NULL); + Curl_cf_socket_peek(cf->next, data, &ctx->q.sockfd, &sockaddr, NULL); if(!sockaddr) return CURLE_QUIC_CONNECT_ERROR; ctx->q.local_addrlen = sizeof(ctx->q.local_addr); @@ -2096,13 +2095,11 @@ static CURLcode cf_ngtcp2_connect(struct Curl_cfilter *cf, #ifndef CURL_DISABLE_VERBOSE_STRINGS if(result) { - const char *r_ip = NULL; - int r_port = 0; + struct ip_quadruple ip; - Curl_cf_socket_peek(cf->next, data, NULL, NULL, - &r_ip, &r_port, NULL, NULL); + Curl_cf_socket_peek(cf->next, data, NULL, NULL, &ip); infof(data, "QUIC connect to %s port %u failed: %s", - r_ip, r_port, curl_easy_strerror(result)); + ip.remote_ip, ip.remote_port, curl_easy_strerror(result)); } #endif if(!result && ctx->qconn) { diff --git a/lib/vquic/curl_osslq.c b/lib/vquic/curl_osslq.c index 0e5606d75e3..b638be3195b 100644 --- a/lib/vquic/curl_osslq.c +++ b/lib/vquic/curl_osslq.c @@ -443,16 +443,14 @@ static CURLcode cf_osslq_ssl_err(struct Curl_cfilter *cf, if(CURLE_SSL_CONNECT_ERROR == result && errdetail == 0) { char extramsg[80]=""; int sockerr = SOCKERRNO; - const char *r_ip = NULL; - int r_port = 0; + struct ip_quadruple ip; - Curl_cf_socket_peek(cf->next, data, NULL, NULL, - &r_ip, &r_port, NULL, NULL); + Curl_cf_socket_peek(cf->next, data, NULL, NULL, &ip); if(sockerr && detail == SSL_ERROR_SYSCALL) Curl_strerror(sockerr, extramsg, sizeof(extramsg)); failf(data, "QUIC connect: %s in connection to %s:%d (%s)", extramsg[0] ? extramsg : osslq_SSL_ERROR_to_str(detail), - ctx->peer.dispname, r_port, r_ip); + ctx->peer.dispname, ip.remote_port, ip.remote_ip); } else { /* Could be a CERT problem */ @@ -1039,7 +1037,6 @@ static CURLcode cf_osslq_ctx_start(struct Curl_cfilter *cf, CURLcode result; int rv; const struct Curl_sockaddr_ex *peer_addr = NULL; - int peer_port; BIO *bio = NULL; BIO_ADDR *baddr = NULL; @@ -1061,8 +1058,7 @@ static CURLcode cf_osslq_ctx_start(struct Curl_cfilter *cf, goto out; result = CURLE_QUIC_CONNECT_ERROR; - Curl_cf_socket_peek(cf->next, data, &ctx->q.sockfd, - &peer_addr, NULL, &peer_port, NULL, NULL); + Curl_cf_socket_peek(cf->next, data, &ctx->q.sockfd, &peer_addr, NULL); if(!peer_addr) goto out; @@ -1657,13 +1653,11 @@ static CURLcode cf_osslq_connect(struct Curl_cfilter *cf, #ifndef CURL_DISABLE_VERBOSE_STRINGS if(result) { - const char *r_ip = NULL; - int r_port = 0; + struct ip_quadruple ip; - Curl_cf_socket_peek(cf->next, data, NULL, NULL, - &r_ip, &r_port, NULL, NULL); + Curl_cf_socket_peek(cf->next, data, NULL, NULL, &ip); infof(data, "QUIC connect to %s port %u failed: %s", - r_ip, r_port, curl_easy_strerror(result)); + ip.remote_ip, ip.remote_port, curl_easy_strerror(result)); } #endif if(!result) diff --git a/lib/vquic/curl_quiche.c b/lib/vquic/curl_quiche.c index fcb0eb8f843..0763c083a20 100644 --- a/lib/vquic/curl_quiche.c +++ b/lib/vquic/curl_quiche.c @@ -1243,8 +1243,7 @@ static CURLcode cf_connect_start(struct Curl_cfilter *cf, if(result) return result; - Curl_cf_socket_peek(cf->next, data, &ctx->q.sockfd, - &sockaddr, NULL, NULL, NULL, NULL); + Curl_cf_socket_peek(cf->next, data, &ctx->q.sockfd, &sockaddr, NULL); ctx->q.local_addrlen = sizeof(ctx->q.local_addr); rv = getsockname(ctx->q.sockfd, (struct sockaddr *)&ctx->q.local_addr, &ctx->q.local_addrlen); @@ -1390,13 +1389,11 @@ static CURLcode cf_quiche_connect(struct Curl_cfilter *cf, out: #ifndef CURL_DISABLE_VERBOSE_STRINGS if(result && result != CURLE_AGAIN) { - const char *r_ip; - int r_port; + struct ip_quadruple ip; - Curl_cf_socket_peek(cf->next, data, NULL, NULL, - &r_ip, &r_port, NULL, NULL); + Curl_cf_socket_peek(cf->next, data, NULL, NULL, &ip); infof(data, "connect to %s port %u failed: %s", - r_ip, r_port, curl_easy_strerror(result)); + ip.remote_ip, ip.remote_port, curl_easy_strerror(result)); } #endif return result; diff --git a/lib/vquic/vquic.c b/lib/vquic/vquic.c index 612d25bb0af..066caf98667 100644 --- a/lib/vquic/vquic.c +++ b/lib/vquic/vquic.c @@ -370,12 +370,10 @@ static CURLcode recvmmsg_packets(struct Curl_cfilter *cf, goto out; } if(!cf->connected && SOCKERRNO == ECONNREFUSED) { - const char *r_ip = NULL; - int r_port = 0; - Curl_cf_socket_peek(cf->next, data, NULL, NULL, - &r_ip, &r_port, NULL, NULL); + struct ip_quadruple ip; + Curl_cf_socket_peek(cf->next, data, NULL, NULL, &ip); failf(data, "QUIC: connection to %s port %u refused", - r_ip, r_port); + ip.remote_ip, ip.remote_port); result = CURLE_COULDNT_CONNECT; goto out; } @@ -440,12 +438,10 @@ static CURLcode recvmsg_packets(struct Curl_cfilter *cf, goto out; } if(!cf->connected && SOCKERRNO == ECONNREFUSED) { - const char *r_ip = NULL; - int r_port = 0; - Curl_cf_socket_peek(cf->next, data, NULL, NULL, - &r_ip, &r_port, NULL, NULL); + struct ip_quadruple ip; + Curl_cf_socket_peek(cf->next, data, NULL, NULL, &ip); failf(data, "QUIC: connection to %s port %u refused", - r_ip, r_port); + ip.remote_ip, ip.remote_port); result = CURLE_COULDNT_CONNECT; goto out; } @@ -500,12 +496,10 @@ static CURLcode recvfrom_packets(struct Curl_cfilter *cf, goto out; } if(!cf->connected && SOCKERRNO == ECONNREFUSED) { - const char *r_ip = NULL; - int r_port = 0; - Curl_cf_socket_peek(cf->next, data, NULL, NULL, - &r_ip, &r_port, NULL, NULL); + struct ip_quadruple ip; + Curl_cf_socket_peek(cf->next, data, NULL, NULL, &ip); failf(data, "QUIC: connection to %s port %u refused", - r_ip, r_port); + ip.remote_ip, ip.remote_port); result = CURLE_COULDNT_CONNECT; goto out; } From cd937651448b0176dcda544eb6720cfe894573fb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Mar 2024 07:30:01 +0100 Subject: [PATCH 461/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 39 ++++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 2a3f05331b0..e45b371d2d5 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,15 +4,15 @@ curl and libcurl 8.7.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3112 + Contributors: 3113 This release includes the following changes: 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 + o digest: support SHA-512/256 [118] o DoH: add trace configuration [61] - o write-out: add '%{proxy_used}' + o write-out: add '%{proxy_used}' [24] This release includes the following bugfixes: @@ -80,6 +80,8 @@ This release includes the following bugfixes: o header.md: remove backslash, make nicer markdown [48] o HTTP/2: write response directly [12] 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 HTTP3.md: adjust the OpenSSL QUIC install instructions [34] o http: better error message for HTTP/1.x response without status line [86] @@ -88,12 +90,15 @@ This release includes the following bugfixes: 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 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: 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] @@ -141,6 +146,7 @@ This release includes the following bugfixes: o version: allow building with ancient libpsl [52] 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 write-out.md: clarify error handling details [31] @@ -159,19 +165,19 @@ advice from friends like these: 5533asdg on github, Andreas Kiefer, av223119 on github, Boris Verkhovskiy, Brett Buddin, Chris Webb, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, - Daniel Szmulewicz, dependabot[bot], Dirk Hünniger, Dmitry Karpov, - Dmitry Tretyakov, edmcln on github, Erik Schnetter, Evgeny Grin (Karlson2k), - Fabian Vogt, Fabrice Fontaine, Faraz Fallahi, Gisle Vanem, Harry Sintonen, - HsiehYuho on github, Jan Macku, Jiawen Geng, Joel Depooter, Jon Rumsey, - Jordan Brown, Karthikdasari0423, Konstantin Vlasov, kpcyrd, - Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, Lukáš Zaoral, Marcel Raad, - Michael Forney, Michael Kaufmann, Michał Antoniak, Nikita Taranov, - Patrick Monnerat, Paweł Witas, Peter Krefting, RainRat, Ramiro Garcia, - Ray Satiro, Richard Levitte, Robert Moreton, Rudi Heitbaum, + Daniel Szmulewicz, DasKutti on github, dependabot[bot], Dirk Hünniger, + Dmitry Karpov, Dmitry Tretyakov, edmcln on github, Erik Schnetter, + Evgeny Grin (Karlson2k), Fabian Vogt, Fabrice Fontaine, Faraz Fallahi, + Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, + Joel Depooter, Jon Rumsey, Jordan Brown, Karthikdasari0423, + Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, + Lukáš Zaoral, Marcel Raad, Michael Forney, Michael Kaufmann, Michał Antoniak, + Nikita Taranov, Patrick Monnerat, Paweł Witas, Peter Krefting, RainRat, + Ramiro Garcia, Ray Satiro, Richard Levitte, Robert Moreton, Rudi Heitbaum, Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, Sebastian Neubauer, Sergey Bronnikov, Simon K, Stefan Eissing, Tal Regev, Viktor Szakats, vulnerabilityspotter on hackerone - (59 contributors) + (60 contributors) References to bug reports and discussions on issues: @@ -283,6 +289,7 @@ References to bug reports and discussions on issues: [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 @@ -291,10 +298,16 @@ References to bug reports and discussions on issues: [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=13070 [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 + [128] = https://curl.se/bug/?i=13085 + [130] = https://curl.se/bug/?i=13082 + [132] = https://curl.se/bug/?i=13081 + [134] = https://curl.se/bug/?i=12063 From 6aeb729b5c0d2a4162aca0b58660edf9ef36f8f6 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 11 Mar 2024 09:50:55 +0100 Subject: [PATCH 462/509] request: clarify message when request has been sent off Change the "uploaded and fine" message for requests without a body Reported-by: Karthikdasari0423 on github Fixes #13093 Closes #13095 --- lib/request.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/request.c b/lib/request.c index ed4aa714c12..7d43acfcdd9 100644 --- a/lib/request.c +++ b/lib/request.c @@ -263,7 +263,9 @@ static CURLcode req_set_upload_done(struct Curl_easy *data) infof(data, "upload completely sent off: %" CURL_FORMAT_CURL_OFF_T " bytes", data->req.writebytecount); else - infof(data, "We are completely uploaded and fine"); + infof(data, Curl_creader_total_length(data)? + "We are completely uploaded and fine" : + "Request completely sent off"); return Curl_xfer_send_close(data); } From 4e4e8af1f6b45b365c2f9778371578c93cf3b244 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 11 Mar 2024 12:35:07 +0100 Subject: [PATCH 463/509] lib: move 'done' parameter to SingleRequests A transfer may do several `SingleRequest`s for its success. This happens regularly for authentication, follows and retries on failed connections. The "readwrite()" calls and functions connected to those carried a `bool *done` parameter to indicate that the current `SingleRequest` is over. This may happen before `upload_done` or `download_done` bits of `SingleRequest` are set. The problem with that is now `write_resp()` protocol handlers are invoked in places where the `bool *done` cannot be passed up to the caller. Instead of being a bool in the call chain, it needs to become a member of `SingleRequest`, reflecting its state. This removes the `bool *done` parameter and adds the `done` bit to `SingleRequest` instead. It adds `Curl_req_soft_reset()` for using a `SingleRequest` in a follow up, clearing `done` and other flags/counters. Closes #13096 --- lib/c-hyper.c | 16 ++++++---------- lib/c-hyper.h | 1 - lib/cf-h1-proxy.c | 11 +++++------ lib/easy.c | 2 +- lib/http.c | 26 ++++++++++---------------- lib/http.h | 10 +++------- lib/http2.c | 7 ++----- lib/multi.c | 11 +++++------ lib/request.c | 26 ++++++++++++++++++++++---- lib/request.h | 18 ++++++++++++++---- lib/rtsp.c | 14 ++++++-------- lib/transfer.c | 31 +++++++++++++++---------------- lib/transfer.h | 4 ++-- lib/url.c | 10 ++-------- lib/urldata.h | 3 +-- lib/vquic/curl_ngtcp2.c | 6 ++---- 16 files changed, 96 insertions(+), 100 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index 41d758170b0..70d60bab70a 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -207,7 +207,6 @@ static int hyper_body_chunk(void *userdata, const hyper_buf *chunk) CURLcode result = CURLE_OK; if(0 == k->bodywrites) { - bool done = FALSE; #if defined(USE_NTLM) struct connectdata *conn = data->conn; if(conn->bits.close && @@ -235,12 +234,12 @@ static int hyper_body_chunk(void *userdata, const hyper_buf *chunk) } if(data->state.hconnect && (data->req.httpcode/100 != 2) && data->state.authproxy.done) { - done = TRUE; + data->req.done = TRUE; result = CURLE_OK; } else - result = Curl_http_firstwrite(data, data->conn, &done); - if(result || done) { + result = Curl_http_firstwrite(data); + if(result || data->req.done) { infof(data, "Return early from hyper_body_chunk"); data->state.hresult = result; return HYPER_ITER_BREAK; @@ -338,7 +337,6 @@ static CURLcode empty_header(struct Curl_easy *data) CURLcode Curl_hyper_stream(struct Curl_easy *data, struct connectdata *conn, int *didwhat, - bool *done, int select_res) { hyper_response *resp = NULL; @@ -382,7 +380,6 @@ CURLcode Curl_hyper_stream(struct Curl_easy *data, h->write_waker = NULL; } - *done = FALSE; do { hyper_task_return_type t; task = hyper_executor_poll(h->exec); @@ -425,7 +422,7 @@ CURLcode Curl_hyper_stream(struct Curl_easy *data, break; } } - *done = TRUE; + data->req.done = TRUE; hyper_error_free(hypererr); break; } @@ -434,12 +431,11 @@ CURLcode Curl_hyper_stream(struct Curl_easy *data, hyper_task_free(task); if((userdata_t)userdata == USERDATA_RESP_BODY) { /* end of transfer */ - *done = TRUE; + data->req.done = TRUE; infof(data, "hyperstream is done"); if(!k->bodywrites) { /* hyper doesn't always call the body write callback */ - bool stilldone; - result = Curl_http_firstwrite(data, data->conn, &stilldone); + result = Curl_http_firstwrite(data); } break; } diff --git a/lib/c-hyper.h b/lib/c-hyper.h index 4a07233078d..a592abf91e2 100644 --- a/lib/c-hyper.h +++ b/lib/c-hyper.h @@ -51,7 +51,6 @@ size_t Curl_hyper_send(void *userp, hyper_context *ctx, CURLcode Curl_hyper_stream(struct Curl_easy *data, struct connectdata *conn, int *didwhat, - bool *done, int select_res); CURLcode Curl_hyper_header(struct Curl_easy *data, hyper_headers *headers, diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index deb94580bfb..57cf9a1ae11 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -832,9 +832,9 @@ static CURLcode recv_CONNECT_resp(struct Curl_cfilter *cf, int didwhat; (void)ts; - *done = FALSE; - result = Curl_hyper_stream(data, cf->conn, &didwhat, done, + result = Curl_hyper_stream(data, cf->conn, &didwhat, CURL_CSELECT_IN | CURL_CSELECT_OUT); + *done = data->req.done; if(result || !*done) return result; if(h->exec) { @@ -918,6 +918,7 @@ static CURLcode H1_CONNECT(struct Curl_cfilter *cf, * If the other side indicated a connection close, or if someone * else told us to close this connection, do so now. */ + Curl_req_soft_reset(&data->req, data); if(ts->close_connection || conn->bits.close) { /* Close this filter and the sub-chain, re-connect the * sub-chain and continue. Closing this filter will @@ -1003,10 +1004,8 @@ static CURLcode cf_h1_proxy_connect(struct Curl_cfilter *cf, *done = (result == CURLE_OK) && tunnel_is_established(cf->ctx); if(*done) { cf->connected = TRUE; - /* Restore `data->req` fields that may habe been touched */ - data->req.header = TRUE; /* assume header */ - data->req.bytecount = 0; - data->req.ignorebody = FALSE; + /* The real request will follow the CONNECT, reset request partially */ + Curl_req_soft_reset(&data->req, data); Curl_client_reset(data); Curl_pgrsSetUploadCounter(data, 0); Curl_pgrsSetDownloadCounter(data, 0); diff --git a/lib/easy.c b/lib/easy.c index d41ca32d7f6..dc4870608d4 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -1040,7 +1040,7 @@ struct Curl_easy *curl_easy_duphandle(struct Curl_easy *data) */ void curl_easy_reset(struct Curl_easy *data) { - Curl_req_reset(&data->req, data); + Curl_req_hard_reset(&data->req, data); /* zero out UserDefined data: */ Curl_freeset(data); diff --git a/lib/http.c b/lib/http.c index 058d079f498..52ae1ae69d9 100644 --- a/lib/http.c +++ b/lib/http.c @@ -2446,19 +2446,17 @@ CURLcode Curl_http_range(struct Curl_easy *data, return CURLE_OK; } -CURLcode Curl_http_firstwrite(struct Curl_easy *data, - struct connectdata *conn, - bool *done) +CURLcode Curl_http_firstwrite(struct Curl_easy *data) { + struct connectdata *conn = data->conn; struct SingleRequest *k = &data->req; - *done = FALSE; if(data->req.newurl) { if(conn->bits.close) { /* Abort after the headers if "follow Location" is set and we're set to close anyway. */ k->keepon &= ~KEEP_RECV; - *done = TRUE; + k->done = TRUE; return CURLE_OK; } /* We have a new url to load, but since we want to be able to reuse this @@ -2477,7 +2475,7 @@ CURLcode Curl_http_firstwrite(struct Curl_easy *data, streamclose(conn, "already downloaded"); /* Abort download */ k->keepon &= ~KEEP_RECV; - *done = TRUE; + k->done = TRUE; return CURLE_OK; } @@ -2495,7 +2493,7 @@ CURLcode Curl_http_firstwrite(struct Curl_easy *data, action for an HTTP/1.1 client */ if(!Curl_meets_timecondition(data, k->timeofdoc)) { - *done = TRUE; + k->done = TRUE; /* We're simulating an HTTP 304 from server so we return what should have been returned from the server */ data->info.httpcode = 304; @@ -3951,10 +3949,8 @@ static CURLcode http_rw_headers(struct Curl_easy *data, */ CURLcode Curl_http_write_resp_hds(struct Curl_easy *data, const char *buf, size_t blen, - size_t *pconsumed, - bool *done) + size_t *pconsumed) { - *done = FALSE; if(!data->req.header) { *pconsumed = 0; return CURLE_OK; @@ -3965,7 +3961,7 @@ CURLcode Curl_http_write_resp_hds(struct Curl_easy *data, result = http_rw_headers(data, buf, blen, pconsumed); if(!result && !data->req.header) { /* we have successfully finished parsing the HEADERs */ - result = Curl_http_firstwrite(data, data->conn, done); + result = Curl_http_firstwrite(data); if(!data->req.no_body && Curl_dyn_len(&data->state.headerb)) { /* leftover from parsing something that turned out not @@ -3983,16 +3979,14 @@ CURLcode Curl_http_write_resp_hds(struct Curl_easy *data, CURLcode Curl_http_write_resp(struct Curl_easy *data, const char *buf, size_t blen, - bool is_eos, - bool *done) + bool is_eos) { CURLcode result; size_t consumed; int flags; - *done = FALSE; - result = Curl_http_write_resp_hds(data, buf, blen, &consumed, done); - if(result || *done) + result = Curl_http_write_resp_hds(data, buf, blen, &consumed); + if(result || data->req.done) goto out; DEBUGASSERT(consumed <= blen); diff --git a/lib/http.h b/lib/http.h index c77d9c6ba5e..7ff61f5e57b 100644 --- a/lib/http.h +++ b/lib/http.h @@ -121,9 +121,7 @@ CURLcode Curl_http_cookies(struct Curl_easy *data, #endif CURLcode Curl_http_range(struct Curl_easy *data, Curl_HttpReq httpreq); -CURLcode Curl_http_firstwrite(struct Curl_easy *data, - struct connectdata *conn, - bool *done); +CURLcode Curl_http_firstwrite(struct Curl_easy *data); /* protocol-specific functions set up to be called by the main engine */ CURLcode Curl_http_setup_conn(struct Curl_easy *data, @@ -135,8 +133,7 @@ int Curl_http_getsock_do(struct Curl_easy *data, struct connectdata *conn, curl_socket_t *socks); CURLcode Curl_http_write_resp(struct Curl_easy *data, const char *buf, size_t blen, - bool is_eos, - bool *done); + bool is_eos); /* These functions are in http.c */ CURLcode Curl_http_input_auth(struct Curl_easy *data, bool proxy, @@ -197,8 +194,7 @@ CURLcode Curl_http_size(struct Curl_easy *data); CURLcode Curl_http_write_resp_hds(struct Curl_easy *data, const char *buf, size_t blen, - size_t *pconsumed, - bool *done); + size_t *pconsumed); /** * Curl_http_output_auth() setups the authentication headers for the diff --git a/lib/http2.c b/lib/http2.c index 60b924de062..115def26c39 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -951,10 +951,8 @@ static CURLcode recvbuf_write_hds(struct Curl_cfilter *cf, struct Curl_easy *data, const char *buf, size_t blen) { - bool done; - (void)cf; - return Curl_xfer_write_resp(data, (char *)buf, blen, FALSE, &done); + return Curl_xfer_write_resp(data, (char *)buf, blen, FALSE); } static CURLcode on_stream_frame(struct Curl_cfilter *cf, @@ -1234,7 +1232,6 @@ static int on_data_chunk_recv(nghttp2_session *session, uint8_t flags, struct h2_stream_ctx *stream; struct Curl_easy *data_s; CURLcode result; - bool done; (void)flags; DEBUGASSERT(stream_id); /* should never be a zero stream ID here */ @@ -1257,7 +1254,7 @@ static int on_data_chunk_recv(nghttp2_session *session, uint8_t flags, if(!stream) return NGHTTP2_ERR_CALLBACK_FAILURE; - result = Curl_xfer_write_resp(data_s, (char *)mem, len, FALSE, &done); + result = Curl_xfer_write_resp(data_s, (char *)mem, len, FALSE); if(result && result != CURLE_AGAIN) return NGHTTP2_ERR_CALLBACK_FAILURE; diff --git a/lib/multi.c b/lib/multi.c index 800a7c1e466..ed9cac79625 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -1843,7 +1843,6 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, bool async; bool protocol_connected = FALSE; bool dophase_done = FALSE; - bool done = FALSE; CURLMcode rc; CURLcode result = CURLE_OK; timediff_t recv_timeout_ms; @@ -2405,9 +2404,9 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, } /* read/write data if it is ready to do so */ - result = Curl_readwrite(data, &done); + result = Curl_readwrite(data); - if(done || (result == CURLE_RECV_ERROR)) { + if(data->req.done || (result == CURLE_RECV_ERROR)) { /* If CURLE_RECV_ERROR happens early enough, we assume it was a race * condition and the server closed the reused connection exactly when * we wanted to use it, so figure out if that is indeed the case. @@ -2422,7 +2421,7 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, /* if we are to retry, set the result to OK and consider the request as done */ result = CURLE_OK; - done = TRUE; + data->req.done = TRUE; } } else if((CURLE_HTTP2_STREAM == result) && @@ -2442,7 +2441,7 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, as done */ retry = TRUE; result = CURLE_OK; - done = TRUE; + data->req.done = TRUE; } else result = ret; @@ -2464,7 +2463,7 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi, Curl_posttransfer(data); multi_done(data, result, TRUE); } - else if(done) { + else if(data->req.done) { /* call this even if the readwrite function returned error */ Curl_posttransfer(data); diff --git a/lib/request.c b/lib/request.c index 7d43acfcdd9..2a92630d67d 100644 --- a/lib/request.c +++ b/lib/request.c @@ -46,12 +46,23 @@ CURLcode Curl_req_init(struct SingleRequest *req) return CURLE_OK; } -CURLcode Curl_req_start(struct SingleRequest *req, - struct Curl_easy *data) +CURLcode Curl_req_soft_reset(struct SingleRequest *req, + struct Curl_easy *data) { CURLcode result; - req->start = Curl_now(); + req->done = FALSE; + req->upload_done = FALSE; + req->download_done = FALSE; + req->ignorebody = FALSE; + req->bytecount = 0; + req->writebytecount = 0; + req->header = TRUE; /* assume header */ + req->headerline = 0; + req->headerbytecount = 0; + req->allheadercount = 0; + req->deductheadercount = 0; + result = Curl_client_start(data); if(result) return result; @@ -73,6 +84,13 @@ CURLcode Curl_req_start(struct SingleRequest *req, return CURLE_OK; } +CURLcode Curl_req_start(struct SingleRequest *req, + struct Curl_easy *data) +{ + req->start = Curl_now(); + return Curl_req_soft_reset(req, data); +} + static CURLcode req_flush(struct Curl_easy *data); CURLcode Curl_req_done(struct SingleRequest *req, @@ -85,7 +103,7 @@ CURLcode Curl_req_done(struct SingleRequest *req, return CURLE_OK; } -void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data) +void Curl_req_hard_reset(struct SingleRequest *req, struct Curl_easy *data) { struct curltime t0 = {0, 0}; diff --git a/lib/request.h b/lib/request.h index 2298e79d732..3b2462ee740 100644 --- a/lib/request.h +++ b/lib/request.h @@ -123,6 +123,9 @@ struct SingleRequest { unsigned char setcookies; #endif BIT(header); /* incoming data has HTTP header */ + BIT(done); /* request is done, e.g. no more send/recv should + * happen. This can be TRUE before `upload_done` or + * `download_done` is TRUE. */ BIT(content_range); /* set TRUE if Content-Range: was found */ BIT(download_done); /* set to TRUE when download is complete */ BIT(eos_written); /* iff EOS has been written to client */ @@ -153,11 +156,18 @@ struct SingleRequest { CURLcode Curl_req_init(struct SingleRequest *req); /** - * The request is about to start. + * The request is about to start. Record time and do a soft reset. */ CURLcode Curl_req_start(struct SingleRequest *req, struct Curl_easy *data); +/** + * The request may continue with a follow up. Reset + * members, but keep start time for overall duration calc. + */ +CURLcode Curl_req_soft_reset(struct SingleRequest *req, + struct Curl_easy *data); + /** * The request is done. If not aborted, make sure that buffers are * flushed to the client. @@ -174,10 +184,10 @@ CURLcode Curl_req_done(struct SingleRequest *req, void Curl_req_free(struct SingleRequest *req, struct Curl_easy *data); /** - * Reset the state of the request for new use, given the - * settings. + * Hard reset the state of the request to virgin state base on + * transfer settings. */ -void Curl_req_reset(struct SingleRequest *req, struct Curl_easy *data); +void Curl_req_hard_reset(struct SingleRequest *req, struct Curl_easy *data); #ifndef USE_HYPER /** diff --git a/lib/rtsp.c b/lib/rtsp.c index a0b978d92a6..d8545bfc9c6 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -70,8 +70,7 @@ static int rtsp_getsock_do(struct Curl_easy *data, static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, const char *buf, size_t blen, - bool is_eos, - bool *done); + bool is_eos); static CURLcode rtsp_setup_connection(struct Curl_easy *data, struct connectdata *conn); @@ -790,8 +789,7 @@ static CURLcode rtsp_filter_rtp(struct Curl_easy *data, static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, const char *buf, size_t blen, - bool is_eos, - bool *done) + bool is_eos) { struct rtsp_conn *rtspc = &(data->conn->proto.rtspc); CURLcode result = CURLE_OK; @@ -799,7 +797,6 @@ static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, if(!data->req.header) rtspc->in_header = FALSE; - *done = FALSE; if(!blen) { goto out; } @@ -823,7 +820,7 @@ static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, /* we want to parse headers, do so */ if(data->req.header && blen) { rtspc->in_header = TRUE; - result = Curl_http_write_resp_hds(data, buf, blen, &consumed, done); + result = Curl_http_write_resp_hds(data, buf, blen, &consumed); if(result) goto out; @@ -849,13 +846,14 @@ static CURLcode rtsp_rtp_write_resp(struct Curl_easy *data, } if(rtspc->state != RTP_PARSE_SKIP) - *done = FALSE; + data->req.done = FALSE; /* we SHOULD have consumed all bytes, unless the response is borked. * In which case we write out the left over bytes, letting the client * writer deal with it (it will report EXCESS and fail the transfer). */ DEBUGF(infof(data, "rtsp_rtp_write_resp(len=%zu, in_header=%d, done=%d " " rtspc->state=%d, req.size=%" CURL_FORMAT_CURL_OFF_T ")", - blen, rtspc->in_header, *done, rtspc->state, data->req.size)); + blen, rtspc->in_header, data->req.done, rtspc->state, + data->req.size)); if(!result && (is_eos || blen)) { result = Curl_client_write(data, CLIENTWRITE_BODY| (is_eos? CLIENTWRITE_EOS:0), diff --git a/lib/transfer.c b/lib/transfer.c index 669beebd3a6..ffe7adfc19f 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -209,7 +209,7 @@ static ssize_t Curl_xfer_recv_resp(struct Curl_easy *data, */ static CURLcode readwrite_data(struct Curl_easy *data, struct SingleRequest *k, - int *didwhat, bool *done) + int *didwhat) { struct connectdata *conn = data->conn; CURLcode result = CURLE_OK; @@ -219,8 +219,6 @@ static CURLcode readwrite_data(struct Curl_easy *data, curl_off_t total_received = 0; bool is_multiplex = FALSE; - *done = FALSE; - result = Curl_multi_xfer_buf_borrow(data, &xfer_buf, &xfer_blen); if(result) goto out; @@ -281,8 +279,8 @@ static CURLcode readwrite_data(struct Curl_easy *data, } total_received += blen; - result = Curl_xfer_write_resp(data, buf, blen, is_eos, done); - if(result || *done) + result = Curl_xfer_write_resp(data, buf, blen, is_eos); + if(result || data->req.done) goto out; /* if we are done, we stop receiving. On multiplexed connections, @@ -403,8 +401,7 @@ static int select_bits_paused(struct Curl_easy *data, int select_bits) * Curl_readwrite() is the low-level function to be called when data is to * be read and written to/from the connection. */ -CURLcode Curl_readwrite(struct Curl_easy *data, - bool *done) +CURLcode Curl_readwrite(struct Curl_easy *data) { struct connectdata *conn = data->conn; struct SingleRequest *k = &data->req; @@ -450,8 +447,8 @@ CURLcode Curl_readwrite(struct Curl_easy *data, #ifdef USE_HYPER if(conn->datastream) { - result = conn->datastream(data, conn, &didwhat, done, select_bits); - if(result || *done) + result = conn->datastream(data, conn, &didwhat, select_bits); + if(result || data->req.done) goto out; } else { @@ -460,8 +457,8 @@ CURLcode Curl_readwrite(struct Curl_easy *data, the stream was rewound (in which case we have data in a buffer) */ if((k->keepon & KEEP_RECV) && (select_bits & CURL_CSELECT_IN)) { - result = readwrite_data(data, k, &didwhat, done); - if(result || *done) + result = readwrite_data(data, k, &didwhat); + if(result || data->req.done) goto out; } @@ -561,8 +558,10 @@ CURLcode Curl_readwrite(struct Curl_easy *data, } } - /* Now update the "done" boolean we return */ - *done = (0 == (k->keepon&(KEEP_RECVBITS|KEEP_SENDBITS))) ? TRUE : FALSE; + /* If there is nothing more to send/recv, the request is done */ + if(0 == (k->keepon&(KEEP_RECVBITS|KEEP_SENDBITS))) + data->req.done = TRUE; + out: if(result) DEBUGF(infof(data, "Curl_readwrite() -> %d", result)); @@ -937,7 +936,7 @@ CURLcode Curl_follow(struct Curl_easy *data, data->state.url = newurl; data->state.url_alloc = TRUE; - + Curl_req_soft_reset(&data->req, data); infof(data, "Issue another request to this URL: '%s'", data->state.url); /* @@ -1209,14 +1208,14 @@ void Curl_xfer_setup( CURLcode Curl_xfer_write_resp(struct Curl_easy *data, char *buf, size_t blen, - bool is_eos, bool *done) + bool is_eos) { CURLcode result = CURLE_OK; if(data->conn->handler->write_resp) { /* protocol handlers offering this function take full responsibility * for writing all received download data to the client. */ - result = data->conn->handler->write_resp(data, buf, blen, is_eos, done); + result = data->conn->handler->write_resp(data, buf, blen, is_eos); } else { /* No special handling by protocol handler, write all received data diff --git a/lib/transfer.h b/lib/transfer.h index 96e69988ad9..e65b2b14721 100644 --- a/lib/transfer.h +++ b/lib/transfer.h @@ -45,7 +45,7 @@ typedef enum { CURLcode Curl_follow(struct Curl_easy *data, char *newurl, followtype type); -CURLcode Curl_readwrite(struct Curl_easy *data, bool *done); +CURLcode Curl_readwrite(struct Curl_easy *data); int Curl_single_getsock(struct Curl_easy *data, struct connectdata *conn, curl_socket_t *socks); CURLcode Curl_retry_request(struct Curl_easy *data, char **url); @@ -66,7 +66,7 @@ bool Curl_meets_timecondition(struct Curl_easy *data, time_t timeofdoc); */ CURLcode Curl_xfer_write_resp(struct Curl_easy *data, char *buf, size_t blen, - bool is_eos, bool *done); + bool is_eos); /* This sets up a forthcoming transfer */ void Curl_xfer_setup(struct Curl_easy *data, diff --git a/lib/url.c b/lib/url.c index 7c1621cf26a..5eefd2a8717 100644 --- a/lib/url.c +++ b/lib/url.c @@ -3839,8 +3839,8 @@ CURLcode Curl_connect(struct Curl_easy *data, *asyncp = FALSE; /* assume synchronous resolves by default */ - /* init the single-transfer specific data */ - Curl_req_reset(&data->req, data); + /* Set the request to virgin state based on transfer settings */ + Curl_req_hard_reset(&data->req, data); /* call the stuff that needs to be called */ result = create_conn(data, &conn, asyncp); @@ -3883,8 +3883,6 @@ CURLcode Curl_connect(struct Curl_easy *data, CURLcode Curl_init_do(struct Curl_easy *data, struct connectdata *conn) { - struct SingleRequest *k = &data->req; - /* if this is a pushed stream, we need this: */ CURLcode result = Curl_preconnect(data); if(result) @@ -3910,10 +3908,6 @@ CURLcode Curl_init_do(struct Curl_easy *data, struct connectdata *conn) if(result) return result; - k->header = TRUE; /* assume header */ - k->bytecount = 0; - k->ignorebody = FALSE; - Curl_speedinit(data); Curl_pgrsSetUploadCounter(data, 0); Curl_pgrsSetDownloadCounter(data, 0); diff --git a/lib/urldata.h b/lib/urldata.h index ef787972883..933a2e24700 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -163,7 +163,6 @@ typedef ssize_t (Curl_recv)(struct Curl_easy *data, /* transfer */ typedef CURLcode (*Curl_datastream)(struct Curl_easy *data, struct connectdata *conn, int *didwhat, - bool *done, int select_res); #endif @@ -703,7 +702,7 @@ struct Curl_handler { allow the protocol to do extra handling in writing response to the client. */ CURLcode (*write_resp)(struct Curl_easy *data, const char *buf, size_t blen, - bool is_eos, bool *done); + bool is_eos); /* This function can perform various checks on the connection. See CONNCHECK_* for more information about the checks that can be performed, diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index 54dfbeeaa79..4f5da87ab9d 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -762,8 +762,7 @@ static int cb_h3_stream_close(nghttp3_conn *conn, int64_t stream_id, static CURLcode write_resp_hds(struct Curl_easy *data, const char *buf, size_t blen) { - bool done; - return Curl_xfer_write_resp(data, (char *)buf, blen, FALSE, &done); + return Curl_xfer_write_resp(data, (char *)buf, blen, FALSE); } static int cb_h3_recv_data(nghttp3_conn *conn, int64_t stream3_id, @@ -775,7 +774,6 @@ static int cb_h3_recv_data(nghttp3_conn *conn, int64_t stream3_id, struct Curl_easy *data = stream_user_data; struct h3_stream_ctx *stream = H3_STREAM_CTX(data); CURLcode result; - bool done; (void)conn; (void)stream3_id; @@ -783,7 +781,7 @@ static int cb_h3_recv_data(nghttp3_conn *conn, int64_t stream3_id, if(!stream) return NGHTTP3_ERR_CALLBACK_FAILURE; - result = Curl_xfer_write_resp(data, (char *)buf, blen, FALSE, &done); + result = Curl_xfer_write_resp(data, (char *)buf, blen, FALSE); if(result) { CURL_TRC_CF(data, cf, "[%" PRId64 "] DATA len=%zu, ERROR receiving %d", stream->id, blen, result); From 3ccce37790428382d38c7c28e2aec05b20c31ba5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Mar 2024 22:39:22 +0100 Subject: [PATCH 464/509] tool_getparam: handle non-existing (out of range) short-options ... correctly, even when they follow an existing one without a space in between. Verify with test 467 Follow-up to 07dd60c05b Reported-by: Geeknik Labs Fixes #13101 Closes #13102 --- src/tool_getparam.c | 3 ++- tests/data/Makefile.inc | 2 +- tests/data/test467 | 31 +++++++++++++++++++++++++++++++ 3 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 tests/data/test467 diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 23fe3106e6d..52bb24959dd 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -1009,7 +1009,8 @@ static const struct LongShort *single(char letter) { static const struct LongShort *singles[128 - ' ']; /* ASCII => pointer */ static bool singles_done = FALSE; - DEBUGASSERT((letter < 127) && (letter > ' ')); + if((letter >= 127) || (letter <= ' ')) + return NULL; if(!singles_done) { unsigned int j; diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 1a06adf37b9..06bc5c54f96 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -73,7 +73,7 @@ test426 test427 test428 test429 test430 test431 test432 test433 test434 \ test435 test436 test437 test438 test439 test440 test441 test442 test443 \ test444 test445 test446 test447 test448 test449 test450 test451 test452 \ test453 test454 test455 test456 test457 test458 test459 test460 test461 \ -test462 test463 \ +test462 test463 test467 \ \ test490 test491 test492 test493 test494 test495 test496 test497 test498 \ test499 test500 test501 test502 test503 test504 test505 test506 test507 \ diff --git a/tests/data/test467 b/tests/data/test467 new file mode 100644 index 00000000000..4184ac062ca --- /dev/null +++ b/tests/data/test467 @@ -0,0 +1,31 @@ + + + +cmdline + + + +# +# Client-side + + +none + + +use a bad short option letter that does not exist (after one does exist) + + +# the second option is outside the normal accepted range + +curl -v http://example.com + + + +# +# Verify errorcode + + +2 + + + From 942896fdd1a3312540c8cbc181517beb81d21f1a Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Wed, 6 Mar 2024 19:18:46 -0500 Subject: [PATCH 465/509] mbedtls: properly cleanup the thread-shared entropy - Store the state of the thread-shared entropy for global init/cleanup. - Use curl's thread support of mbedtls for all Windows builds instead of just when the threaded resolver is used via USE_THREADS_WIN32. Prior to this change on global cleanup curl builds that have curl thread support for mbedtls freed the entropy (8b1d2298) but failed to mark that it had been freed, which caused problems on subsequent init + transfer. Bug: https://github.com/curl/curl/discussions/11919#discussioncomment-8687105 Reported-by: awesomekosm@users.noreply.github.com Closes https://github.com/curl/curl/pull/13071 --- lib/vtls/mbedtls.c | 30 +++++++++++++++++++++--------- lib/vtls/mbedtls_threadlock.c | 12 ++++++------ lib/vtls/mbedtls_threadlock.h | 2 +- 3 files changed, 28 insertions(+), 16 deletions(-) diff --git a/lib/vtls/mbedtls.c b/lib/vtls/mbedtls.c index 0ef6df0ff0b..3fefb612bd1 100644 --- a/lib/vtls/mbedtls.c +++ b/lib/vtls/mbedtls.c @@ -110,7 +110,8 @@ struct mbed_ssl_backend_data { }; /* apply threading? */ -#if defined(USE_THREADS_POSIX) || defined(USE_THREADS_WIN32) +#if (defined(USE_THREADS_POSIX) && defined(HAVE_PTHREAD_H)) || \ + defined(_WIN32) #define THREADING_SUPPORT #endif @@ -123,7 +124,6 @@ static mbedtls_entropy_context ts_entropy; static int entropy_init_initialized = 0; -/* start of entropy_init_mutex() */ static void entropy_init_mutex(mbedtls_entropy_context *ctx) { /* lock 0 = entropy_init_mutex() */ @@ -134,9 +134,18 @@ static void entropy_init_mutex(mbedtls_entropy_context *ctx) } Curl_mbedtlsthreadlock_unlock_function(0); } -/* end of entropy_init_mutex() */ -/* start of entropy_func_mutex() */ +static void entropy_cleanup_mutex(mbedtls_entropy_context *ctx) +{ + /* lock 0 = use same lock as init */ + Curl_mbedtlsthreadlock_lock_function(0); + if(entropy_init_initialized == 1) { + mbedtls_entropy_free(ctx); + entropy_init_initialized = 0; + } + Curl_mbedtlsthreadlock_unlock_function(0); +} + static int entropy_func_mutex(void *data, unsigned char *output, size_t len) { int ret; @@ -147,7 +156,6 @@ static int entropy_func_mutex(void *data, unsigned char *output, size_t len) return ret; } -/* end of entropy_func_mutex() */ #endif /* THREADING_SUPPORT */ @@ -377,7 +385,6 @@ mbed_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) } #ifdef THREADING_SUPPORT - entropy_init_mutex(&ts_entropy); mbedtls_ctr_drbg_init(&backend->ctr_drbg); ret = mbedtls_ctr_drbg_seed(&backend->ctr_drbg, entropy_func_mutex, @@ -1246,14 +1253,19 @@ static CURLcode mbedtls_connect(struct Curl_cfilter *cf, */ static int mbedtls_init(void) { - return Curl_mbedtlsthreadlock_thread_setup(); + if(!Curl_mbedtlsthreadlock_thread_setup()) + return 0; +#ifdef THREADING_SUPPORT + entropy_init_mutex(&ts_entropy); +#endif + return 1; } static void mbedtls_cleanup(void) { #ifdef THREADING_SUPPORT - mbedtls_entropy_free(&ts_entropy); -#endif /* THREADING_SUPPORT */ + entropy_cleanup_mutex(&ts_entropy); +#endif (void)Curl_mbedtlsthreadlock_thread_cleanup(); } diff --git a/lib/vtls/mbedtls_threadlock.c b/lib/vtls/mbedtls_threadlock.c index 22b1b221e7a..b96a904fcb1 100644 --- a/lib/vtls/mbedtls_threadlock.c +++ b/lib/vtls/mbedtls_threadlock.c @@ -26,12 +26,12 @@ #if defined(USE_MBEDTLS) && \ ((defined(USE_THREADS_POSIX) && defined(HAVE_PTHREAD_H)) || \ - defined(USE_THREADS_WIN32)) + defined(_WIN32)) #if defined(USE_THREADS_POSIX) && defined(HAVE_PTHREAD_H) # include # define MBEDTLS_MUTEX_T pthread_mutex_t -#elif defined(USE_THREADS_WIN32) +#elif defined(_WIN32) # define MBEDTLS_MUTEX_T HANDLE #endif @@ -59,7 +59,7 @@ int Curl_mbedtlsthreadlock_thread_setup(void) #if defined(USE_THREADS_POSIX) && defined(HAVE_PTHREAD_H) if(pthread_mutex_init(&mutex_buf[i], NULL)) return 0; /* pthread_mutex_init failed */ -#elif defined(USE_THREADS_WIN32) +#elif defined(_WIN32) mutex_buf[i] = CreateMutex(0, FALSE, 0); if(mutex_buf[i] == 0) return 0; /* CreateMutex failed */ @@ -80,7 +80,7 @@ int Curl_mbedtlsthreadlock_thread_cleanup(void) #if defined(USE_THREADS_POSIX) && defined(HAVE_PTHREAD_H) if(pthread_mutex_destroy(&mutex_buf[i])) return 0; /* pthread_mutex_destroy failed */ -#elif defined(USE_THREADS_WIN32) +#elif defined(_WIN32) if(!CloseHandle(mutex_buf[i])) return 0; /* CloseHandle failed */ #endif /* USE_THREADS_POSIX && HAVE_PTHREAD_H */ @@ -100,7 +100,7 @@ int Curl_mbedtlsthreadlock_lock_function(int n) "Error: mbedtlsthreadlock_lock_function failed\n")); return 0; /* pthread_mutex_lock failed */ } -#elif defined(USE_THREADS_WIN32) +#elif defined(_WIN32) if(WaitForSingleObject(mutex_buf[n], INFINITE) == WAIT_FAILED) { DEBUGF(fprintf(stderr, "Error: mbedtlsthreadlock_lock_function failed\n")); @@ -120,7 +120,7 @@ int Curl_mbedtlsthreadlock_unlock_function(int n) "Error: mbedtlsthreadlock_unlock_function failed\n")); return 0; /* pthread_mutex_unlock failed */ } -#elif defined(USE_THREADS_WIN32) +#elif defined(_WIN32) if(!ReleaseMutex(mutex_buf[n])) { DEBUGF(fprintf(stderr, "Error: mbedtlsthreadlock_unlock_function failed\n")); diff --git a/lib/vtls/mbedtls_threadlock.h b/lib/vtls/mbedtls_threadlock.h index 2b0bd41c8b9..c8557e723e9 100644 --- a/lib/vtls/mbedtls_threadlock.h +++ b/lib/vtls/mbedtls_threadlock.h @@ -29,7 +29,7 @@ #ifdef USE_MBEDTLS #if (defined(USE_THREADS_POSIX) && defined(HAVE_PTHREAD_H)) || \ - defined(USE_THREADS_WIN32) + defined(_WIN32) int Curl_mbedtlsthreadlock_thread_setup(void); int Curl_mbedtlsthreadlock_thread_cleanup(void); From 451a7a7aa23da0bd0236c82a01bb25747e359275 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Mar 2024 08:45:22 +0100 Subject: [PATCH 466/509] managen: remove space before protocols For options that are listed for specific protocols, the protocols (shown first within parentheses) are now output without the leading space in the manpage output. Closes #13105 --- scripts/managen | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/managen b/scripts/managen index d950bd5866e..ab96861b8f7 100755 --- a/scripts/managen +++ b/scripts/managen @@ -232,7 +232,7 @@ sub protocols { return ".SH \"PROTOCOLS\"\n$data\n"; } else { - return " ($data) " if($manpage); + return "($data) " if($manpage); return "[1]($data) " if(!$manpage); } } From e7219c2bdc253ea7f0b40846640c3b19aef9dd86 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Mar 2024 10:34:58 +0100 Subject: [PATCH 467/509] cmdline-opts: language cleanups Use imperative mood consistently for the first sentence describing an option. "Set this" instead "tell curl to set" or "this sets..." Plus some extra cleanups and rephrasing. Closes #13106 --- docs/cmdline-opts/MANPAGE.md | 2 +- docs/cmdline-opts/_PROTOCOLS.md | 4 +-- docs/cmdline-opts/alt-svc.md | 6 ++-- docs/cmdline-opts/anyauth.md | 8 ++--- docs/cmdline-opts/basic.md | 4 +-- docs/cmdline-opts/ca-native.md | 8 ++--- docs/cmdline-opts/cacert.md | 8 ++--- docs/cmdline-opts/capath.md | 14 ++++----- docs/cmdline-opts/cert-status.md | 6 ++-- docs/cmdline-opts/cert-type.md | 4 +-- docs/cmdline-opts/cert.md | 14 ++++----- docs/cmdline-opts/compressed-ssh.md | 4 +-- docs/cmdline-opts/config.md | 3 +- docs/cmdline-opts/connect-to.md | 16 +++++----- docs/cmdline-opts/continue-at.md | 10 +++---- docs/cmdline-opts/cookie-jar.md | 7 +++-- docs/cmdline-opts/cookie.md | 18 ++++++----- docs/cmdline-opts/curves.md | 8 ++--- docs/cmdline-opts/data-ascii.md | 2 +- docs/cmdline-opts/data-binary.md | 2 +- docs/cmdline-opts/data-raw.md | 4 +-- docs/cmdline-opts/data-urlencode.md | 30 +++++++++---------- docs/cmdline-opts/data.md | 2 +- docs/cmdline-opts/delegation.md | 3 +- docs/cmdline-opts/digest.md | 6 ++-- docs/cmdline-opts/disable-eprt.md | 10 +++---- docs/cmdline-opts/disable-epsv.md | 6 ++-- docs/cmdline-opts/disallow-username-in-url.md | 4 +-- docs/cmdline-opts/dns-interface.md | 6 ++-- docs/cmdline-opts/dns-ipv4-addr.md | 6 ++-- docs/cmdline-opts/dns-ipv6-addr.md | 6 ++-- docs/cmdline-opts/etag-compare.md | 5 ++-- docs/cmdline-opts/etag-save.md | 4 +-- docs/cmdline-opts/expect100-timeout.md | 8 ++--- docs/cmdline-opts/fail-with-body.md | 6 ++-- docs/cmdline-opts/fail.md | 4 +-- docs/cmdline-opts/false-start.md | 11 ++++--- docs/cmdline-opts/form-escape.md | 4 +-- docs/cmdline-opts/form.md | 24 +++++++-------- docs/cmdline-opts/ftp-method.md | 14 ++++----- docs/cmdline-opts/ftp-port.md | 8 ++--- docs/cmdline-opts/ftp-pret.md | 6 ++-- docs/cmdline-opts/ftp-skip-pasv-ip.md | 6 ++-- docs/cmdline-opts/globoff.md | 4 +-- docs/cmdline-opts/haproxy-protocol.md | 6 ++-- docs/cmdline-opts/help.md | 5 ++-- docs/cmdline-opts/hsts.md | 6 ++-- docs/cmdline-opts/http0.9.md | 2 +- docs/cmdline-opts/http1.0.md | 3 +- docs/cmdline-opts/http1.1.md | 2 +- docs/cmdline-opts/http2-prior-knowledge.md | 6 ++-- docs/cmdline-opts/http2.md | 2 +- docs/cmdline-opts/http3.md | 6 ++-- docs/cmdline-opts/ipv4.md | 4 +-- docs/cmdline-opts/ipv6.md | 4 +-- docs/cmdline-opts/keepalive-time.md | 15 +++++----- docs/cmdline-opts/limit-rate.md | 4 +-- docs/cmdline-opts/list-only.md | 13 ++++---- docs/cmdline-opts/location-trusted.md | 4 +-- docs/cmdline-opts/max-time.md | 6 ++-- docs/cmdline-opts/negotiate.md | 2 +- docs/cmdline-opts/netrc-file.md | 5 ++-- docs/cmdline-opts/netrc.md | 2 +- docs/cmdline-opts/next.md | 7 ++--- docs/cmdline-opts/ntlm.md | 2 +- docs/cmdline-opts/output-dir.md | 4 +-- docs/cmdline-opts/output.md | 5 ++++ docs/cmdline-opts/path-as-is.md | 6 ++-- docs/cmdline-opts/pinnedpubkey.md | 8 ++--- docs/cmdline-opts/post301.md | 10 +++---- docs/cmdline-opts/post302.md | 10 +++---- docs/cmdline-opts/post303.md | 7 ++--- docs/cmdline-opts/proto-default.md | 5 ++-- docs/cmdline-opts/proto-redir.md | 5 ++-- docs/cmdline-opts/proto.md | 6 ++-- docs/cmdline-opts/proxy-anyauth.md | 2 +- docs/cmdline-opts/proxy-basic.md | 6 ++-- docs/cmdline-opts/proxy-ca-native.md | 7 ++--- docs/cmdline-opts/proxy-digest.md | 4 +-- docs/cmdline-opts/proxy-http2.md | 4 +-- docs/cmdline-opts/proxy-negotiate.md | 6 ++-- docs/cmdline-opts/proxy-ntlm.md | 4 +-- docs/cmdline-opts/proxy-pinnedpubkey.md | 8 ++--- docs/cmdline-opts/proxy-service-name.md | 2 +- docs/cmdline-opts/proxy-tls13-ciphers.md | 6 ++-- docs/cmdline-opts/referer.md | 2 +- docs/cmdline-opts/remote-header-name.md | 7 ++--- docs/cmdline-opts/remote-name-all.md | 4 +-- docs/cmdline-opts/remove-on-error.md | 6 ++-- docs/cmdline-opts/request-target.md | 8 ++--- docs/cmdline-opts/resolve.md | 2 +- docs/cmdline-opts/service-name.md | 2 +- docs/cmdline-opts/socks5-basic.md | 6 ++-- docs/cmdline-opts/socks5-gssapi-service.md | 3 +- docs/cmdline-opts/socks5-gssapi.md | 8 ++--- docs/cmdline-opts/ssl-allow-beast.md | 7 ++--- docs/cmdline-opts/ssl-auto-client-cert.md | 8 ++--- docs/cmdline-opts/ssl-no-revoke.md | 5 ++-- docs/cmdline-opts/ssl-revoke-best-effort.md | 5 ++-- docs/cmdline-opts/styled-output.md | 2 +- docs/cmdline-opts/tftp-no-options.md | 8 ++--- docs/cmdline-opts/tlsv1.md | 4 +-- docs/cmdline-opts/trace-ascii.md | 4 +-- docs/cmdline-opts/trace.md | 4 +-- docs/cmdline-opts/upload-file.md | 2 +- docs/cmdline-opts/url-query.md | 6 ++-- docs/cmdline-opts/url.md | 3 +- docs/cmdline-opts/use-ascii.md | 6 ++-- docs/cmdline-opts/xattr.md | 10 +++---- tests/test1275.pl | 1 - 110 files changed, 332 insertions(+), 347 deletions(-) diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 252e9e86a07..1f9749bc51b 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -6,7 +6,7 @@ # 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. The `mainpage.idx` file lists all files that are rendered in that order to diff --git a/docs/cmdline-opts/_PROTOCOLS.md b/docs/cmdline-opts/_PROTOCOLS.md index 201c080b1b0..0d4c2374efa 100644 --- a/docs/cmdline-opts/_PROTOCOLS.md +++ b/docs/cmdline-opts/_PROTOCOLS.md @@ -45,7 +45,7 @@ curl supports SMB version 1 for upload and download. Uploading contents to an SMTP server means sending an email. With or without TLS. ## 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. +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/alt-svc.md b/docs/cmdline-opts/alt-svc.md index a30aff7b650..257f4d5b9cb 100644 --- a/docs/cmdline-opts/alt-svc.md +++ b/docs/cmdline-opts/alt-svc.md @@ -17,9 +17,9 @@ Example: # `--alt-svc` -This option enables the alt-svc parser in curl. 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. +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. diff --git a/docs/cmdline-opts/anyauth.md b/docs/cmdline-opts/anyauth.md index 150e069e815..31b27c4adea 100644 --- a/docs/cmdline-opts/anyauth.md +++ b/docs/cmdline-opts/anyauth.md @@ -17,10 +17,10 @@ Example: # `--anyauth` -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 +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 diff --git a/docs/cmdline-opts/basic.md b/docs/cmdline-opts/basic.md index 34b019175bb..abb516aa036 100644 --- a/docs/cmdline-opts/basic.md +++ b/docs/cmdline-opts/basic.md @@ -15,8 +15,8 @@ Example: # `--basic` -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 +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). diff --git a/docs/cmdline-opts/ca-native.md b/docs/cmdline-opts/ca-native.md index d0b4bfa5a73..aac7456e9bc 100644 --- a/docs/cmdline-opts/ca-native.md +++ b/docs/cmdline-opts/ca-native.md @@ -17,10 +17,10 @@ Example: # `--ca-native` -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. +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 diff --git a/docs/cmdline-opts/cacert.md b/docs/cmdline-opts/cacert.md index 7b1b2174ba6..3268f966def 100644 --- a/docs/cmdline-opts/cacert.md +++ b/docs/cmdline-opts/cacert.md @@ -17,10 +17,10 @@ Example: # `--cacert` -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. +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 diff --git a/docs/cmdline-opts/capath.md b/docs/cmdline-opts/capath.md index ecd28df2413..58919dd4ab1 100644 --- a/docs/cmdline-opts/capath.md +++ b/docs/cmdline-opts/capath.md @@ -17,12 +17,12 @@ Example: # `--capath` -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. +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.md b/docs/cmdline-opts/cert-status.md index bfbd3af835b..6d7b234bf7a 100644 --- a/docs/cmdline-opts/cert-status.md +++ b/docs/cmdline-opts/cert-status.md @@ -15,11 +15,11 @@ Example: # `--cert-status` -Tells curl to verify the status of the server certificate by using the -Certificate Status Request (aka. OCSP stapling) TLS extension. +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. +This support is currently only implemented in the OpenSSL and GnuTLS backends. diff --git a/docs/cmdline-opts/cert-type.md b/docs/cmdline-opts/cert-type.md index a0030a59dae..d78ab8fa441 100644 --- a/docs/cmdline-opts/cert-type.md +++ b/docs/cmdline-opts/cert-type.md @@ -18,8 +18,8 @@ Example: # `--cert-type` -Tells curl what type the provided client certificate is using. PEM, DER, ENG -and P12 are recognized types. +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 diff --git a/docs/cmdline-opts/cert.md b/docs/cmdline-opts/cert.md index b9630b958b5..715fcb831a4 100644 --- a/docs/cmdline-opts/cert.md +++ b/docs/cmdline-opts/cert.md @@ -19,13 +19,13 @@ Example: # `--cert` -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. +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, diff --git a/docs/cmdline-opts/compressed-ssh.md b/docs/cmdline-opts/compressed-ssh.md index c52e5a7a37a..b404f62d5d2 100644 --- a/docs/cmdline-opts/compressed-ssh.md +++ b/docs/cmdline-opts/compressed-ssh.md @@ -15,5 +15,5 @@ Example: # `--compressed-ssh` -Enables built-in SSH compression. -This is a request, not an order; the server may or may not do it. +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/config.md b/docs/cmdline-opts/config.md index 181825ac354..1281a3d9c9f 100644 --- a/docs/cmdline-opts/config.md +++ b/docs/cmdline-opts/config.md @@ -38,7 +38,8 @@ 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. +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 diff --git a/docs/cmdline-opts/connect-to.md b/docs/cmdline-opts/connect-to.md index 7cd0aa857f2..360ef0da203 100644 --- a/docs/cmdline-opts/connect-to.md +++ b/docs/cmdline-opts/connect-to.md @@ -16,14 +16,14 @@ Example: # `--connect-to` -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". +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 diff --git a/docs/cmdline-opts/continue-at.md b/docs/cmdline-opts/continue-at.md index 67a79fd70c9..978cafc01f7 100644 --- a/docs/cmdline-opts/continue-at.md +++ b/docs/cmdline-opts/continue-at.md @@ -17,10 +17,10 @@ Example: # `--continue-at` -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. +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 tell curl to automatically find out where/how to resume the +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.md b/docs/cmdline-opts/cookie-jar.md index f4331a48d2e..da2ac433281 100644 --- a/docs/cmdline-opts/cookie-jar.md +++ b/docs/cmdline-opts/cookie-jar.md @@ -20,9 +20,10 @@ Example: 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 filename to a single dash, "-", the cookies are written to stdout. +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 diff --git a/docs/cmdline-opts/cookie.md b/docs/cmdline-opts/cookie.md index 0676d80f17c..c61f9821578 100644 --- a/docs/cmdline-opts/cookie.md +++ b/docs/cmdline-opts/cookie.md @@ -22,27 +22,29 @@ Example: # `--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". This makes curl use 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 passed on. +similar, they all get this cookie header passed on. -If no '=' symbol is used in the argument, it is instead treated as a filename +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 exactly a minus ("-"), curl instead 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. +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 the file. To store cookies, use the --cookie-jar option. +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 diff --git a/docs/cmdline-opts/curves.md b/docs/cmdline-opts/curves.md index 99f1ad48a75..b701773641f 100644 --- a/docs/cmdline-opts/curves.md +++ b/docs/cmdline-opts/curves.md @@ -16,10 +16,10 @@ Example: # `--curves` -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` and `s_server` utilities. +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 diff --git a/docs/cmdline-opts/data-ascii.md b/docs/cmdline-opts/data-ascii.md index 124dee13c05..5763d81f193 100644 --- a/docs/cmdline-opts/data-ascii.md +++ b/docs/cmdline-opts/data-ascii.md @@ -18,4 +18,4 @@ Example: # `--data-ascii` -This is just an alias for --data. +This option is just an alias for --data. diff --git a/docs/cmdline-opts/data-binary.md b/docs/cmdline-opts/data-binary.md index 3d563fbdd7d..1ce53b32c67 100644 --- a/docs/cmdline-opts/data-binary.md +++ b/docs/cmdline-opts/data-binary.md @@ -16,7 +16,7 @@ Example: # `--data-binary` -This posts data exactly as specified with no extra processing whatsoever. +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 diff --git a/docs/cmdline-opts/data-raw.md b/docs/cmdline-opts/data-raw.md index 2cb46938b52..1033678bdea 100644 --- a/docs/cmdline-opts/data-raw.md +++ b/docs/cmdline-opts/data-raw.md @@ -17,5 +17,5 @@ Example: # `--data-raw` -This posts data similarly to --data but without the special -interpretation of the @ character. +Post data similarly to --data but without the special interpretation of the @ +character. diff --git a/docs/cmdline-opts/data-urlencode.md b/docs/cmdline-opts/data-urlencode.md index 733530a5700..2bd84f3f160 100644 --- a/docs/cmdline-opts/data-urlencode.md +++ b/docs/cmdline-opts/data-urlencode.md @@ -20,32 +20,32 @@ Example: # `--data-urlencode` -This posts data, similar to the other --data options with the exception -that this performs URL-encoding. +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 -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! +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 -This makes curl URL-encode the content and pass that on. The preceding = -symbol is not included in the data. +URL-encode the content and pass that on. The preceding `=` symbol is not +included in the data. ## 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. +URL-encode the content part and pass that on. Note that the name part is +expected to be URL-encoded already. ## @filename -This makes curl load data from the given file (including any newlines), -URL-encode that data and pass it on in the POST. +load data from the given file (including any newlines), URL-encode that data +and pass it on in the POST. ## 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. +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.md b/docs/cmdline-opts/data.md index ebe2347d868..6b6e70285e4 100644 --- a/docs/cmdline-opts/data.md +++ b/docs/cmdline-opts/data.md @@ -24,7 +24,7 @@ Example: 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 +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 diff --git a/docs/cmdline-opts/delegation.md b/docs/cmdline-opts/delegation.md index 3d6cff89974..c874a2b59d4 100644 --- a/docs/cmdline-opts/delegation.md +++ b/docs/cmdline-opts/delegation.md @@ -17,8 +17,7 @@ Example: # `--delegation` -Set LEVEL to tell the server what it is allowed to delegate when it -comes to user credentials. +Set LEVEL what curl is allowed to delegate when it comes to user credentials. ## none Do not allow any delegation. diff --git a/docs/cmdline-opts/digest.md b/docs/cmdline-opts/digest.md index 5bba975de0d..658932a5434 100644 --- a/docs/cmdline-opts/digest.md +++ b/docs/cmdline-opts/digest.md @@ -18,6 +18,6 @@ Example: # `--digest` -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 username and password. +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.md b/docs/cmdline-opts/disable-eprt.md index 80ae0569119..b6e6c6da239 100644 --- a/docs/cmdline-opts/disable-eprt.md +++ b/docs/cmdline-opts/disable-eprt.md @@ -16,11 +16,11 @@ Example: # `--disable-eprt` -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. +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. diff --git a/docs/cmdline-opts/disable-epsv.md b/docs/cmdline-opts/disable-epsv.md index f4a8de8c04a..7667c795fbb 100644 --- a/docs/cmdline-opts/disable-epsv.md +++ b/docs/cmdline-opts/disable-epsv.md @@ -16,9 +16,9 @@ Example: # `--disable-epsv` -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. +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. diff --git a/docs/cmdline-opts/disallow-username-in-url.md b/docs/cmdline-opts/disallow-username-in-url.md index faa4d8834fb..012f2d0dc80 100644 --- a/docs/cmdline-opts/disallow-username-in-url.md +++ b/docs/cmdline-opts/disallow-username-in-url.md @@ -14,5 +14,5 @@ Example: # `--disallow-username-in-url` -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. +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.md b/docs/cmdline-opts/dns-interface.md index ee2bb829ff6..aee7400bc5d 100644 --- a/docs/cmdline-opts/dns-interface.md +++ b/docs/cmdline-opts/dns-interface.md @@ -18,6 +18,6 @@ Example: # `--dns-interface` -Tell curl to 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). +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.md b/docs/cmdline-opts/dns-ipv4-addr.md index ff4163bc164..4a43cb1d900 100644 --- a/docs/cmdline-opts/dns-ipv4-addr.md +++ b/docs/cmdline-opts/dns-ipv4-addr.md @@ -18,6 +18,6 @@ Example: # `--dns-ipv4-addr` -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. +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.md b/docs/cmdline-opts/dns-ipv6-addr.md index 7d4d1c1f571..71123117678 100644 --- a/docs/cmdline-opts/dns-ipv6-addr.md +++ b/docs/cmdline-opts/dns-ipv6-addr.md @@ -18,6 +18,6 @@ Example: # `--dns-ipv6-addr` -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. +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/etag-compare.md b/docs/cmdline-opts/etag-compare.md index 11c1d0e875b..a695e55eae4 100644 --- a/docs/cmdline-opts/etag-compare.md +++ b/docs/cmdline-opts/etag-compare.md @@ -17,9 +17,8 @@ Example: # `--etag-compare` -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. +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 diff --git a/docs/cmdline-opts/etag-save.md b/docs/cmdline-opts/etag-save.md index f6fb14a5154..d642552ffc5 100644 --- a/docs/cmdline-opts/etag-save.md +++ b/docs/cmdline-opts/etag-save.md @@ -16,7 +16,7 @@ Example: # `--etag-save` -This option saves an HTTP ETag to the specified file. An ETag is a -caching related header, usually returned in a response. +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.md b/docs/cmdline-opts/expect100-timeout.md index 9554568a777..ce69227ad9c 100644 --- a/docs/cmdline-opts/expect100-timeout.md +++ b/docs/cmdline-opts/expect100-timeout.md @@ -18,8 +18,8 @@ Example: 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. +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. +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-with-body.md b/docs/cmdline-opts/fail-with-body.md index e340cb0345b..670959ba9bc 100644 --- a/docs/cmdline-opts/fail-with-body.md +++ b/docs/cmdline-opts/fail-with-body.md @@ -19,9 +19,9 @@ Example: 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. +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.md b/docs/cmdline-opts/fail.md index b8de4ebb253..8591e330db4 100644 --- a/docs/cmdline-opts/fail.md +++ b/docs/cmdline-opts/fail.md @@ -21,8 +21,8 @@ Example: 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. +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 diff --git a/docs/cmdline-opts/false-start.md b/docs/cmdline-opts/false-start.md index d2697da5387..f25af2374de 100644 --- a/docs/cmdline-opts/false-start.md +++ b/docs/cmdline-opts/false-start.md @@ -15,10 +15,9 @@ Example: # `--false-start` -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. +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. +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.md b/docs/cmdline-opts/form-escape.md index d405bef95cd..d2bd0d32b9a 100644 --- a/docs/cmdline-opts/form-escape.md +++ b/docs/cmdline-opts/form-escape.md @@ -15,5 +15,5 @@ Example: # `--form-escape` -Tells curl to pass on names of multipart form fields and files using -backslash-escaping instead of percent-encoding. +Pass on names of multipart form fields and files using backslash-escaping +instead of percent-encoding. diff --git a/docs/cmdline-opts/form.md b/docs/cmdline-opts/form.md index 44d958a4683..8a4c91e5ae1 100644 --- a/docs/cmdline-opts/form.md +++ b/docs/cmdline-opts/form.md @@ -20,12 +20,12 @@ Example: # `--form` -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 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 is the means to compose a multipart mail -message to transmit. +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 @@ -34,11 +34,11 @@ a file, prefix the filename with the symbol \<. The difference between @ and 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 +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. @@ -56,8 +56,8 @@ text field, but get the contents for it from a local file: curl -F "story= should be -one of: +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) diff --git a/docs/cmdline-opts/ftp-pret.md b/docs/cmdline-opts/ftp-pret.md index accbc226dff..48c48e3e77f 100644 --- a/docs/cmdline-opts/ftp-pret.md +++ b/docs/cmdline-opts/ftp-pret.md @@ -16,6 +16,6 @@ Example: # `--ftp-pret` -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. +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.md b/docs/cmdline-opts/ftp-skip-pasv-ip.md index ef94b34af17..dfa546d1d27 100644 --- a/docs/cmdline-opts/ftp-skip-pasv-ip.md +++ b/docs/cmdline-opts/ftp-skip-pasv-ip.md @@ -15,9 +15,9 @@ Example: # `--ftp-skip-pasv-ip` -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. +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). diff --git a/docs/cmdline-opts/globoff.md b/docs/cmdline-opts/globoff.md index dc3fc2ef885..1eca6dd0051 100644 --- a/docs/cmdline-opts/globoff.md +++ b/docs/cmdline-opts/globoff.md @@ -16,7 +16,7 @@ Example: # `--globoff` -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 +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/haproxy-protocol.md b/docs/cmdline-opts/haproxy-protocol.md index 0170039cd2f..26456c80bf4 100644 --- a/docs/cmdline-opts/haproxy-protocol.md +++ b/docs/cmdline-opts/haproxy-protocol.md @@ -15,9 +15,9 @@ Example: # `--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. +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/help.md b/docs/cmdline-opts/help.md index 6ef812d3dd7..7477a1e4074 100644 --- a/docs/cmdline-opts/help.md +++ b/docs/cmdline-opts/help.md @@ -16,10 +16,9 @@ Example: # `--help` -Usage help. This lists all curl command line options within the given -**category**. +Usage help. List all curl command line options within the given **category**. -If no argument is provided, curl displays only the most important command line +If no argument is provided, curl displays the most important command line arguments. For category **all**, curl displays help for all options. diff --git a/docs/cmdline-opts/hsts.md b/docs/cmdline-opts/hsts.md index 320377f463e..9cae80c2f30 100644 --- a/docs/cmdline-opts/hsts.md +++ b/docs/cmdline-opts/hsts.md @@ -16,9 +16,9 @@ Example: # `--hsts` -This option enables 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. +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 diff --git a/docs/cmdline-opts/http0.9.md b/docs/cmdline-opts/http0.9.md index a28961641cb..54ef3231564 100644 --- a/docs/cmdline-opts/http0.9.md +++ b/docs/cmdline-opts/http0.9.md @@ -18,7 +18,7 @@ Example: # `--http0.9` -Tells curl to be fine with HTTP version 0.9 response. +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 diff --git a/docs/cmdline-opts/http1.0.md b/docs/cmdline-opts/http1.0.md index fb7d907d808..b810ccf3b70 100644 --- a/docs/cmdline-opts/http1.0.md +++ b/docs/cmdline-opts/http1.0.md @@ -19,5 +19,4 @@ Example: # `--http1.0` -Tells curl to use HTTP version 1.0 instead of using its internally preferred -HTTP version. +Use HTTP version 1.0 instead of using its internally preferred HTTP version. diff --git a/docs/cmdline-opts/http1.1.md b/docs/cmdline-opts/http1.1.md index 3c4fe303a9e..a223da1f9de 100644 --- a/docs/cmdline-opts/http1.1.md +++ b/docs/cmdline-opts/http1.1.md @@ -18,4 +18,4 @@ Example: # `--http1.1` -Tells curl to use HTTP version 1.1. +Use HTTP version 1.1. This is the default with HTTP:// URLs. diff --git a/docs/cmdline-opts/http2-prior-knowledge.md b/docs/cmdline-opts/http2-prior-knowledge.md index 80a52141b4b..72701094172 100644 --- a/docs/cmdline-opts/http2-prior-knowledge.md +++ b/docs/cmdline-opts/http2-prior-knowledge.md @@ -19,7 +19,7 @@ Example: # `--http2-prior-knowledge` -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 +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.md b/docs/cmdline-opts/http2.md index db4cf346211..ae4d26974c8 100644 --- a/docs/cmdline-opts/http2.md +++ b/docs/cmdline-opts/http2.md @@ -20,7 +20,7 @@ Example: # `--http2` -Tells curl to use HTTP version 2. +Use HTTP/2. For HTTPS, this means curl negotiates HTTP/2 in the TLS handshake. curl does this by default. diff --git a/docs/cmdline-opts/http3.md b/docs/cmdline-opts/http3.md index d30c7bd9081..a1900655a0b 100644 --- a/docs/cmdline-opts/http3.md +++ b/docs/cmdline-opts/http3.md @@ -19,9 +19,9 @@ Example: # `--http3` -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. +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. diff --git a/docs/cmdline-opts/ipv4.md b/docs/cmdline-opts/ipv4.md index 70bbc0f11aa..b790cc65aaa 100644 --- a/docs/cmdline-opts/ipv4.md +++ b/docs/cmdline-opts/ipv4.md @@ -20,5 +20,5 @@ Example: # `--ipv4` -This option tells curl to use IPv4 addresses only when resolving hostnames, -and not for example try IPv6. +Use IPv4 addresses only when resolving hostnames, and not for example try +IPv6. diff --git a/docs/cmdline-opts/ipv6.md b/docs/cmdline-opts/ipv6.md index fbacbec3f7c..c33a24c3faa 100644 --- a/docs/cmdline-opts/ipv6.md +++ b/docs/cmdline-opts/ipv6.md @@ -20,5 +20,5 @@ Example: # `--ipv6` -This option tells curl to use IPv6 addresses only when resolving hostnames, -and not for example try IPv4. +Use IPv6 addresses only when resolving hostnames, and not for example try +IPv4. diff --git a/docs/cmdline-opts/keepalive-time.md b/docs/cmdline-opts/keepalive-time.md index ce3d0f0305d..41c09031ec5 100644 --- a/docs/cmdline-opts/keepalive-time.md +++ b/docs/cmdline-opts/keepalive-time.md @@ -16,13 +16,12 @@ Example: # `--keepalive-time` -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). -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. +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/limit-rate.md b/docs/cmdline-opts/limit-rate.md index ab94c2f2d9c..273a2ce5167 100644 --- a/docs/cmdline-opts/limit-rate.md +++ b/docs/cmdline-opts/limit-rate.md @@ -20,8 +20,8 @@ Example: # `--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 +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. diff --git a/docs/cmdline-opts/list-only.md b/docs/cmdline-opts/list-only.md index 52f0b6fc93c..5d8dde65c2d 100644 --- a/docs/cmdline-opts/list-only.md +++ b/docs/cmdline-opts/list-only.md @@ -17,23 +17,20 @@ Example: # `--list-only` -(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. +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. -(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 filenames. -(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. diff --git a/docs/cmdline-opts/location-trusted.md b/docs/cmdline-opts/location-trusted.md index 050cd9dbfd2..11c1486c97a 100644 --- a/docs/cmdline-opts/location-trusted.md +++ b/docs/cmdline-opts/location-trusted.md @@ -17,5 +17,5 @@ Example: 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). +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/max-time.md b/docs/cmdline-opts/max-time.md index ad8bdedc264..17938dcf235 100644 --- a/docs/cmdline-opts/max-time.md +++ b/docs/cmdline-opts/max-time.md @@ -18,9 +18,9 @@ Example: # `--max-time` -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). +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 diff --git a/docs/cmdline-opts/negotiate.md b/docs/cmdline-opts/negotiate.md index 8f30888a824..bba3f6a08cb 100644 --- a/docs/cmdline-opts/negotiate.md +++ b/docs/cmdline-opts/negotiate.md @@ -18,7 +18,7 @@ Example: # `--negotiate` -Enables Negotiate (SPNEGO) authentication. +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. diff --git a/docs/cmdline-opts/netrc-file.md b/docs/cmdline-opts/netrc-file.md index e37020ea8e9..841f23c48d9 100644 --- a/docs/cmdline-opts/netrc-file.md +++ b/docs/cmdline-opts/netrc-file.md @@ -18,8 +18,7 @@ Example: # `--netrc-file` -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. +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.md b/docs/cmdline-opts/netrc.md index b8b1b943670..4c07f9b75ee 100644 --- a/docs/cmdline-opts/netrc.md +++ b/docs/cmdline-opts/netrc.md @@ -18,7 +18,7 @@ Example: # `--netrc` -Makes curl scan the *.netrc* file in the user's home directory for login name +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 diff --git a/docs/cmdline-opts/next.md b/docs/cmdline-opts/next.md index 2f484f4c3b2..2cf65c65a8f 100644 --- a/docs/cmdline-opts/next.md +++ b/docs/cmdline-opts/next.md @@ -20,10 +20,9 @@ Example: # `--next` -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 usernames or custom requests -for each. +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 diff --git a/docs/cmdline-opts/ntlm.md b/docs/cmdline-opts/ntlm.md index c0a58a636b4..3faeed7d124 100644 --- a/docs/cmdline-opts/ntlm.md +++ b/docs/cmdline-opts/ntlm.md @@ -17,7 +17,7 @@ Example: # `--ntlm` -Enables NTLM authentication. The NTLM authentication method was designed by +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 diff --git a/docs/cmdline-opts/output-dir.md b/docs/cmdline-opts/output-dir.md index 9f494d87a4a..04d780f2986 100644 --- a/docs/cmdline-opts/output-dir.md +++ b/docs/cmdline-opts/output-dir.md @@ -16,8 +16,8 @@ Example: # `--output-dir` -This option specifies the directory in which files should be stored, when ---remote-name or --output are used. +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. diff --git a/docs/cmdline-opts/output.md b/docs/cmdline-opts/output.md index f7beaba6dd5..53f65832723 100644 --- a/docs/cmdline-opts/output.md +++ b/docs/cmdline-opts/output.md @@ -55,3 +55,8 @@ To suppress response bodies, you can redirect output to /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/path-as-is.md b/docs/cmdline-opts/path-as-is.md index 768faa50a72..f3a60cff245 100644 --- a/docs/cmdline-opts/path-as-is.md +++ b/docs/cmdline-opts/path-as-is.md @@ -14,6 +14,6 @@ Example: # `--path-as-is` -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. +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.md b/docs/cmdline-opts/pinnedpubkey.md index cdbd31dcac2..53c79912af1 100644 --- a/docs/cmdline-opts/pinnedpubkey.md +++ b/docs/cmdline-opts/pinnedpubkey.md @@ -17,10 +17,10 @@ Example: # `--pinnedpubkey` -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 ';'. +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 diff --git a/docs/cmdline-opts/post301.md b/docs/cmdline-opts/post301.md index 5a7ce063262..93c9c65f0f6 100644 --- a/docs/cmdline-opts/post301.md +++ b/docs/cmdline-opts/post301.md @@ -17,8 +17,8 @@ Example: # `--post301` -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. +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.md b/docs/cmdline-opts/post302.md index 7eefc0cd62c..93578be0cac 100644 --- a/docs/cmdline-opts/post302.md +++ b/docs/cmdline-opts/post302.md @@ -17,8 +17,8 @@ Example: # `--post302` -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. +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.md b/docs/cmdline-opts/post303.md index 4ea749c2e07..916e88a0b68 100644 --- a/docs/cmdline-opts/post303.md +++ b/docs/cmdline-opts/post303.md @@ -17,7 +17,6 @@ Example: # `--post303` -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. +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/proto-default.md b/docs/cmdline-opts/proto-default.md index 38d9dffebe4..209e5cdc83d 100644 --- a/docs/cmdline-opts/proto-default.md +++ b/docs/cmdline-opts/proto-default.md @@ -16,10 +16,9 @@ Example: # `--proto-default` -Tells curl to use *protocol* for any URL missing a scheme name. +Use *protocol* for any provided URL missing a scheme. -An unknown or unsupported protocol causes error -*CURLE_UNSUPPORTED_PROTOCOL* (1). +An unknown or unsupported protocol causes error *CURLE_UNSUPPORTED_PROTOCOL*. This option does not change the default proxy protocol (http). diff --git a/docs/cmdline-opts/proto-redir.md b/docs/cmdline-opts/proto-redir.md index f0a307a17ce..51fb7bd3a14 100644 --- a/docs/cmdline-opts/proto-redir.md +++ b/docs/cmdline-opts/proto-redir.md @@ -15,9 +15,8 @@ Example: # `--proto-redir` -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. +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: diff --git a/docs/cmdline-opts/proto.md b/docs/cmdline-opts/proto.md index a7045544965..704c6493cd5 100644 --- a/docs/cmdline-opts/proto.md +++ b/docs/cmdline-opts/proto.md @@ -16,9 +16,9 @@ Example: # `--proto` -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: +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 diff --git a/docs/cmdline-opts/proxy-anyauth.md b/docs/cmdline-opts/proxy-anyauth.md index dcb3952ef23..78e67ee7ce7 100644 --- a/docs/cmdline-opts/proxy-anyauth.md +++ b/docs/cmdline-opts/proxy-anyauth.md @@ -16,5 +16,5 @@ Example: # `--proxy-anyauth` -Tells curl to pick a suitable authentication method when communicating with +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.md b/docs/cmdline-opts/proxy-basic.md index 4262a74f9c3..2fae3d5b957 100644 --- a/docs/cmdline-opts/proxy-basic.md +++ b/docs/cmdline-opts/proxy-basic.md @@ -16,6 +16,6 @@ Example: # `--proxy-basic` -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. +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.md b/docs/cmdline-opts/proxy-ca-native.md index 071d04f936c..9f09cee0cb9 100644 --- a/docs/cmdline-opts/proxy-ca-native.md +++ b/docs/cmdline-opts/proxy-ca-native.md @@ -17,10 +17,9 @@ Example: # `--proxy-ca-native` -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. +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 diff --git a/docs/cmdline-opts/proxy-digest.md b/docs/cmdline-opts/proxy-digest.md index 052b67b7f73..4822c79bd7b 100644 --- a/docs/cmdline-opts/proxy-digest.md +++ b/docs/cmdline-opts/proxy-digest.md @@ -16,5 +16,5 @@ Example: # `--proxy-digest` -Tells curl to use HTTP Digest authentication when communicating with the given -proxy. Use --digest for enabling HTTP Digest with a remote host. +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-http2.md b/docs/cmdline-opts/proxy-http2.md index a5745f0868d..ca6a091f328 100644 --- a/docs/cmdline-opts/proxy-http2.md +++ b/docs/cmdline-opts/proxy-http2.md @@ -18,7 +18,7 @@ Example: # `--proxy-http2` -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. +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-negotiate.md b/docs/cmdline-opts/proxy-negotiate.md index 98e0bd37146..33ab1f99ae2 100644 --- a/docs/cmdline-opts/proxy-negotiate.md +++ b/docs/cmdline-opts/proxy-negotiate.md @@ -15,6 +15,6 @@ Example: # `--proxy-negotiate` -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. +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.md b/docs/cmdline-opts/proxy-ntlm.md index b3394f0744e..5e772cd6a1b 100644 --- a/docs/cmdline-opts/proxy-ntlm.md +++ b/docs/cmdline-opts/proxy-ntlm.md @@ -15,5 +15,5 @@ Example: # `--proxy-ntlm` -Tells curl to use HTTP NTLM authentication when communicating with the given -proxy. Use --ntlm for enabling NTLM with a remote host. +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-pinnedpubkey.md b/docs/cmdline-opts/proxy-pinnedpubkey.md index edf68cb0c63..6f0b52d3e6d 100644 --- a/docs/cmdline-opts/proxy-pinnedpubkey.md +++ b/docs/cmdline-opts/proxy-pinnedpubkey.md @@ -18,10 +18,10 @@ Example: # `--proxy-pinnedpubkey` -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 ';'. +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 diff --git a/docs/cmdline-opts/proxy-service-name.md b/docs/cmdline-opts/proxy-service-name.md index f1ee2649de4..534222f449e 100644 --- a/docs/cmdline-opts/proxy-service-name.md +++ b/docs/cmdline-opts/proxy-service-name.md @@ -16,4 +16,4 @@ Example: # `--proxy-service-name` -This option allows you to change the service name for proxy negotiation. +Set the service name for proxy negotiation. diff --git a/docs/cmdline-opts/proxy-tls13-ciphers.md b/docs/cmdline-opts/proxy-tls13-ciphers.md index c9202ae1afa..002fd0b0f4c 100644 --- a/docs/cmdline-opts/proxy-tls13-ciphers.md +++ b/docs/cmdline-opts/proxy-tls13-ciphers.md @@ -18,9 +18,9 @@ Example: # `--proxy-tls13-ciphers` -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: +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 diff --git a/docs/cmdline-opts/referer.md b/docs/cmdline-opts/referer.md index 40a8dc6df09..1fec2485012 100644 --- a/docs/cmdline-opts/referer.md +++ b/docs/cmdline-opts/referer.md @@ -20,7 +20,7 @@ Example: # `--referer` -Sends the referrer URL in the HTTP request. This can also be set with the +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 diff --git a/docs/cmdline-opts/remote-header-name.md b/docs/cmdline-opts/remote-header-name.md index 46b8ad288e3..88c2808a3fe 100644 --- a/docs/cmdline-opts/remote-header-name.md +++ b/docs/cmdline-opts/remote-header-name.md @@ -16,10 +16,9 @@ Example: # `--remote-header-name` -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 filename contains a path, that is stripped off before the -filename is used. +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. diff --git a/docs/cmdline-opts/remote-name-all.md b/docs/cmdline-opts/remote-name-all.md index 19f7de76798..92d348e27c2 100644 --- a/docs/cmdline-opts/remote-name-all.md +++ b/docs/cmdline-opts/remote-name-all.md @@ -14,7 +14,7 @@ Example: # `--remote-name-all` -This option changes 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 +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/remove-on-error.md b/docs/cmdline-opts/remove-on-error.md index 02ce99239a4..b0064ae3187 100644 --- a/docs/cmdline-opts/remove-on-error.md +++ b/docs/cmdline-opts/remove-on-error.md @@ -14,8 +14,8 @@ Example: # `--remove-on-error` -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. +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.md b/docs/cmdline-opts/request-target.md index cc379229380..442851148f9 100644 --- a/docs/cmdline-opts/request-target.md +++ b/docs/cmdline-opts/request-target.md @@ -16,10 +16,10 @@ Example: # `--request-target` -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 *". +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/resolve.md b/docs/cmdline-opts/resolve.md index 70d039aa8c3..6e0d393f54a 100644 --- a/docs/cmdline-opts/resolve.md +++ b/docs/cmdline-opts/resolve.md @@ -24,7 +24,7 @@ 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 +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. diff --git a/docs/cmdline-opts/service-name.md b/docs/cmdline-opts/service-name.md index 818dc4e7b1d..b39bad4f18f 100644 --- a/docs/cmdline-opts/service-name.md +++ b/docs/cmdline-opts/service-name.md @@ -16,4 +16,4 @@ Example: # `--service-name` -This option allows you to change the service name for SPNEGO. +Set the service name for SPNEGO. diff --git a/docs/cmdline-opts/socks5-basic.md b/docs/cmdline-opts/socks5-basic.md index bfadea6b449..ec80fa9edc9 100644 --- a/docs/cmdline-opts/socks5-basic.md +++ b/docs/cmdline-opts/socks5-basic.md @@ -14,6 +14,6 @@ Example: # `--socks5-basic` -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. +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-service.md b/docs/cmdline-opts/socks5-gssapi-service.md index c2ab2d93275..d847e65e247 100644 --- a/docs/cmdline-opts/socks5-gssapi-service.md +++ b/docs/cmdline-opts/socks5-gssapi-service.md @@ -15,5 +15,4 @@ Example: # `--socks5-gssapi-service` -The default service name for a socks server is **rcmd/server-fqdn**. This option -allows you to change it. +Set the service name for a socks server. Default is **rcmd/server-fqdn**. diff --git a/docs/cmdline-opts/socks5-gssapi.md b/docs/cmdline-opts/socks5-gssapi.md index 43ec56aa299..e17425431b3 100644 --- a/docs/cmdline-opts/socks5-gssapi.md +++ b/docs/cmdline-opts/socks5-gssapi.md @@ -14,7 +14,7 @@ Example: # `--socks5-gssapi` -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. +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/ssl-allow-beast.md b/docs/cmdline-opts/ssl-allow-beast.md index 6c144e765fc..29f2b450c2d 100644 --- a/docs/cmdline-opts/ssl-allow-beast.md +++ b/docs/cmdline-opts/ssl-allow-beast.md @@ -16,10 +16,9 @@ Example: # `--ssl-allow-beast` -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. +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.md b/docs/cmdline-opts/ssl-auto-client-cert.md index 8ed6fed22e2..4f0be5bd7e7 100644 --- a/docs/cmdline-opts/ssl-auto-client-cert.md +++ b/docs/cmdline-opts/ssl-auto-client-cert.md @@ -15,7 +15,7 @@ Example: # `--ssl-auto-client-cert` -(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. +(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.md b/docs/cmdline-opts/ssl-no-revoke.md index 3f1400cd4ea..16981f14d12 100644 --- a/docs/cmdline-opts/ssl-no-revoke.md +++ b/docs/cmdline-opts/ssl-no-revoke.md @@ -15,6 +15,5 @@ Example: # `--ssl-no-revoke` -(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. +(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-revoke-best-effort.md b/docs/cmdline-opts/ssl-revoke-best-effort.md index 77fb8767438..994e1f654c5 100644 --- a/docs/cmdline-opts/ssl-revoke-best-effort.md +++ b/docs/cmdline-opts/ssl-revoke-best-effort.md @@ -16,6 +16,5 @@ Example: # `--ssl-revoke-best-effort` -(Schannel) This option tells curl to ignore certificate revocation checks when -they failed due to missing/offline distribution points for the revocation check -lists. +(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/styled-output.md b/docs/cmdline-opts/styled-output.md index 1df472aedbc..bb324532bda 100644 --- a/docs/cmdline-opts/styled-output.md +++ b/docs/cmdline-opts/styled-output.md @@ -16,7 +16,7 @@ Example: # `--styled-output` -Enables the automatic use of bold font styles when writing HTTP headers to the +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 diff --git a/docs/cmdline-opts/tftp-no-options.md b/docs/cmdline-opts/tftp-no-options.md index 518816c2914..063da92edb4 100644 --- a/docs/cmdline-opts/tftp-no-options.md +++ b/docs/cmdline-opts/tftp-no-options.md @@ -15,8 +15,6 @@ Example: # `--tftp-no-options` -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. +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/tlsv1.md b/docs/cmdline-opts/tlsv1.md index bed9db09685..a3960e53edc 100644 --- a/docs/cmdline-opts/tlsv1.md +++ b/docs/cmdline-opts/tlsv1.md @@ -20,5 +20,5 @@ Example: # `--tlsv1` -Tells curl to use at least TLS version 1.x when negotiating with a remote TLS -server. That means TLS version 1.0 or higher +Use at least TLS version 1.x when negotiating with a remote TLS server. That +means TLS version 1.0 or higher diff --git a/docs/cmdline-opts/trace-ascii.md b/docs/cmdline-opts/trace-ascii.md index 651540565b0..34f4d9f41c7 100644 --- a/docs/cmdline-opts/trace-ascii.md +++ b/docs/cmdline-opts/trace-ascii.md @@ -18,8 +18,8 @@ Example: # `--trace-ascii` -Enables a full trace dump of all incoming and outgoing data, including -descriptive information, to the given output file. Use `-` as filename to have +Save a full trace dump of all incoming and outgoing data, including +descriptive information, in the given output file. Use `-` as filename to have the output sent to stdout. This is similar to --trace, but leaves out the hex part and only shows the diff --git a/docs/cmdline-opts/trace.md b/docs/cmdline-opts/trace.md index ed9e681f329..f6e3e4b55ae 100644 --- a/docs/cmdline-opts/trace.md +++ b/docs/cmdline-opts/trace.md @@ -20,8 +20,8 @@ Example: # `--trace` -Enables a full trace dump of all incoming and outgoing data, including -descriptive information, to the given output file. Use "-" as filename to have +Save a full trace dump of all incoming and outgoing data, including +descriptive information, in the given output file. Use "-" as filename to have the output sent to stdout. Use "%" as filename to have the output sent to stderr. diff --git a/docs/cmdline-opts/upload-file.md b/docs/cmdline-opts/upload-file.md index eb4b8b77661..74e7af3025f 100644 --- a/docs/cmdline-opts/upload-file.md +++ b/docs/cmdline-opts/upload-file.md @@ -21,7 +21,7 @@ Example: # `--upload-file` -This transfers the specified local file to the remote URL. +Upload the specified local file to the remote URL. If there is no file part in the specified URL, curl appends the local file name to the end of the URL before the operation starts. You must use a diff --git a/docs/cmdline-opts/url-query.md b/docs/cmdline-opts/url-query.md index 15e585773b1..43bf43d9325 100644 --- a/docs/cmdline-opts/url-query.md +++ b/docs/cmdline-opts/url-query.md @@ -21,9 +21,9 @@ Example: # `--url-query` -This option adds a piece of data, usually a name + value pair, to the end of -the URL query part. The syntax is identical to that used for --data-urlencode -with one extension: +Add a piece of data, usually a name + value pair, to the end of the URL query +part. The syntax is identical to that used for --data-urlencode with one +extension: If the argument starts with a '+' (plus), the rest of the string is provided as-is unencoded. diff --git a/docs/cmdline-opts/url.md b/docs/cmdline-opts/url.md index 671c376ec55..c3680b64184 100644 --- a/docs/cmdline-opts/url.md +++ b/docs/cmdline-opts/url.md @@ -16,8 +16,7 @@ Example: # `--url` -Specify a URL to fetch. This option is mostly handy when you want to specify -URL(s) in a config file. +Specify a URL to fetch. If the given URL is missing a scheme name (such as `http://` or `ftp://` etc) then curl makes a guess based on the host. If the outermost subdomain name diff --git a/docs/cmdline-opts/use-ascii.md b/docs/cmdline-opts/use-ascii.md index 96b1928103d..3586aa212a6 100644 --- a/docs/cmdline-opts/use-ascii.md +++ b/docs/cmdline-opts/use-ascii.md @@ -17,6 +17,6 @@ Example: # `--use-ascii` -Enable ASCII transfer. For FTP, this can also be enforced by using a URL that -ends with `;type=A`. This option causes data sent to stdout to be in text mode -for win32 systems. +Enable ASCII transfer mode. For FTP, this can also be enforced by using a URL +that ends with `;type=A`. This option causes data sent to stdout to be in text +mode for win32 systems. diff --git a/docs/cmdline-opts/xattr.md b/docs/cmdline-opts/xattr.md index a09819ced06..bfa74cf5aaa 100644 --- a/docs/cmdline-opts/xattr.md +++ b/docs/cmdline-opts/xattr.md @@ -16,8 +16,8 @@ Example: # `--xattr` -When saving output to a file, this option tells curl to store certain file -metadata in extended file attributes. Currently, the URL is stored in the -`xdg.origin.url` attribute and, for HTTP, the content type is stored in the -`mime_type` attribute. If the file system does not support extended -attributes, a warning is issued. +When saving output to a file, tell curl to store file metadata in extended +file attributes. Currently, the URL is stored in the `xdg.origin.url` +attribute and, for HTTP, the content type is stored in the `mime_type` +attribute. If the file system does not support extended attributes, a warning +is issued. diff --git a/tests/test1275.pl b/tests/test1275.pl index 082946a224f..5676a7637fd 100755 --- a/tests/test1275.pl +++ b/tests/test1275.pl @@ -51,7 +51,6 @@ sub checkfile { if(($l == 1) && ($line =~ /^---/)) { # first line is a meta-data divider, skip to the next one $metadata = 1; - print STDERR "skip meta-data in $f\n"; next; } elsif($metadata) { From 14d9afdfe72935df1078a97936e6406ee3e0a824 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 12 Mar 2024 12:04:27 +0000 Subject: [PATCH 468/509] tidy-up: one comment and EOF newlines Reviewed-by: Daniel Stenberg Closes #13108 --- docs/CLIENT-WRITERS.md | 1 - docs/CONNECTION-FILTERS.md | 1 - docs/cmdline-opts/.gitignore | 2 +- docs/libcurl/opts/CURLOPT_SEEKDATA.md | 1 - lib/vtls/mbedtls_threadlock.h | 2 +- scripts/nroff2cd | 1 - 6 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/CLIENT-WRITERS.md b/docs/CLIENT-WRITERS.md index 227e11db6ad..47e802f1215 100644 --- a/docs/CLIENT-WRITERS.md +++ b/docs/CLIENT-WRITERS.md @@ -115,4 +115,3 @@ That is why transfer decoding writers are added for phase `CURL_CW_TRANSFER_DECO 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/CONNECTION-FILTERS.md b/docs/CONNECTION-FILTERS.md index 06ec0293f7e..95b6d50d7a7 100644 --- a/docs/CONNECTION-FILTERS.md +++ b/docs/CONNECTION-FILTERS.md @@ -300,4 +300,3 @@ conn[curl.se] --> HTTPS-CONNECT --> NULL conn[curl.se] --> HTTPS-CONNECT --> SETUP[QUIC] --> HAPPY-EYEBALLS --> HTTP/3[151.101.1.91]:443 * transfer ``` - diff --git a/docs/cmdline-opts/.gitignore b/docs/cmdline-opts/.gitignore index 16213ffa1ea..8d42e2c53d5 100644 --- a/docs/cmdline-opts/.gitignore +++ b/docs/cmdline-opts/.gitignore @@ -2,4 +2,4 @@ # # SPDX-License-Identifier: curl -curl.txt \ No newline at end of file +curl.txt diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.md b/docs/libcurl/opts/CURLOPT_SEEKDATA.md index 84ea49f47fa..563db558d26 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKDATA.md +++ b/docs/libcurl/opts/CURLOPT_SEEKDATA.md @@ -68,4 +68,3 @@ int main(void) Added in 7.18.0 # RETURN VALUE - diff --git a/lib/vtls/mbedtls_threadlock.h b/lib/vtls/mbedtls_threadlock.h index c8557e723e9..484626852f5 100644 --- a/lib/vtls/mbedtls_threadlock.h +++ b/lib/vtls/mbedtls_threadlock.h @@ -43,7 +43,7 @@ int Curl_mbedtlsthreadlock_unlock_function(int n); #define Curl_mbedtlsthreadlock_lock_function(x) 1 #define Curl_mbedtlsthreadlock_unlock_function(x) 1 -#endif /* USE_THREADS_POSIX || USE_THREADS_WIN32 */ +#endif /* (USE_THREADS_POSIX && HAVE_PTHREAD_H) || _WIN32 */ #endif /* USE_MBEDTLS */ diff --git a/scripts/nroff2cd b/scripts/nroff2cd index 500367f8149..fdf5bde29d4 100755 --- a/scripts/nroff2cd +++ b/scripts/nroff2cd @@ -190,4 +190,3 @@ HEAD } exit single($ARGV[0]); - From aedbbdf18e689a5eee8dc39600914f5eda6c409c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Mar 2024 10:53:08 +0100 Subject: [PATCH 469/509] vquic-tls: return appropirate errors on wolfSSL errors Reported-by: Dexter Gerig Closes #13107 --- lib/vquic/vquic-tls.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/vquic/vquic-tls.c b/lib/vquic/vquic-tls.c index cc7794e405a..dbde21f476f 100644 --- a/lib/vquic/vquic-tls.c +++ b/lib/vquic/vquic-tls.c @@ -375,6 +375,7 @@ static CURLcode curl_wssl_init_ctx(struct quic_tls_ctx *ctx, char error_buffer[256]; ERR_error_string_n(ERR_get_error(), error_buffer, sizeof(error_buffer)); failf(data, "wolfSSL failed to set ciphers: %s", error_buffer); + result = CURLE_BAD_FUNCTION_ARGUMENT; goto out; } @@ -382,6 +383,7 @@ static CURLcode curl_wssl_init_ctx(struct quic_tls_ctx *ctx, conn_config->curves : (char *)QUIC_GROUPS) != 1) { failf(data, "wolfSSL failed to set curves"); + result = CURLE_BAD_FUNCTION_ARGUMENT; goto out; } @@ -392,6 +394,7 @@ static CURLcode curl_wssl_init_ctx(struct quic_tls_ctx *ctx, wolfSSL_CTX_set_keylog_callback(ctx->ssl_ctx, keylog_callback); #else failf(data, "wolfSSL was built without keylog callback"); + result = CURLE_NOT_BUILT_IN; goto out; #endif } @@ -414,6 +417,7 @@ static CURLcode curl_wssl_init_ctx(struct quic_tls_ctx *ctx, " CAfile: %s CApath: %s", ssl_cafile ? ssl_cafile : "none", ssl_capath ? ssl_capath : "none"); + result = CURLE_SSL_CACERT; goto out; } infof(data, " CAfile: %s", ssl_cafile ? ssl_cafile : "none"); From 181f5f3369ba35d25ee77d5e2fb253cd8650d921 Mon Sep 17 00:00:00 2001 From: Jay Satiro Date: Wed, 13 Mar 2024 02:03:18 -0400 Subject: [PATCH 470/509] vquic-tls: fix the error code returned for bad CA file - Return CURLE_SSL_CACERT_BADFILE if wolfSSL encounters a problem reading the cert file or path. This is a follow-up to the parent commit aedbbdf1. Reported-by: Karthikdasari0423@users.noreply.github.com Fixes https://github.com/curl/curl/issues/13115 --- lib/vquic/vquic-tls.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/vquic/vquic-tls.c b/lib/vquic/vquic-tls.c index dbde21f476f..ecba607a9ff 100644 --- a/lib/vquic/vquic-tls.c +++ b/lib/vquic/vquic-tls.c @@ -417,7 +417,7 @@ static CURLcode curl_wssl_init_ctx(struct quic_tls_ctx *ctx, " CAfile: %s CApath: %s", ssl_cafile ? ssl_cafile : "none", ssl_capath ? ssl_capath : "none"); - result = CURLE_SSL_CACERT; + result = CURLE_SSL_CACERT_BADFILE; goto out; } infof(data, " CAfile: %s", ssl_cafile ? ssl_cafile : "none"); From 0f4520adce2905feeeb24cde226161a9e50a9279 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 13 Mar 2024 13:23:38 +0100 Subject: [PATCH 471/509] GOVERNANCE: document the core team Closes #13118 --- docs/GOVERNANCE.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index 4930b960424..09723c4d0bb 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -107,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 From fb3c251ef798dfecc609e7fc511f6062a06753c2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 13 Mar 2024 13:26:07 +0100 Subject: [PATCH 472/509] SPONSORS: describe the basics Closes #13119 --- docs/Makefile.am | 1 + docs/SPONSORS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 docs/SPONSORS.md diff --git a/docs/Makefile.am b/docs/Makefile.am index b3a098114f2..3fadb765f5c 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -89,6 +89,7 @@ EXTRA_DIST = \ RUSTLS.md \ ROADMAP.md \ SECURITY-ADVISORY.md \ + SPONSORS.md \ SSL-PROBLEMS.md \ SSLCERTS.md \ THANKS \ 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! From 09f367977af2a9db785db76ef8beaef405ba492e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Mar 2024 12:56:39 +0100 Subject: [PATCH 473/509] GHA/linux: add sysctl trick to work-around GitHub runner issue The GitHub image runner update from 20240304.1.0 to 20240310.1 introduces a problem for clang-14. The issue is caused by incompatibility between llvm 14 provided in ubuntu-22.04 image and the much newer kernel configured with high-entropy ASLR. As a work-around, we issue a sysctl command to lower the entropy and get clang-14 to work again. URL: https://github.com/actions/runner-images/issues/9491 Closes #13124 --- .github/workflows/linux.yml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index 3d447a871bc..b033340842b 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -139,7 +139,7 @@ jobs: 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 + --without-ssl --without-zlib --without-brotli --without-zstd --without-libpsl --without-nghttp2 --enable-debug --enable-websockets singleuse: --unit - name: event-based @@ -197,6 +197,14 @@ jobs: - 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 From 40948189ffbb64e6e8629f1212947949ec901c8b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Mar 2024 13:58:45 +0100 Subject: [PATCH 474/509] curl: make --libcurl output better CURLOPT_*SSLVERSION The option is really two enums ORed together, so it needs special attention to make the code output nice. Added test 1481 to verify. Both the server and the proxy versions. Reported-by: Boris Verkhovskiy Fixes #13127 Closes #13129 --- src/tool_operate.c | 8 +-- src/tool_setopt.c | 54 ++++++++++++++++++ src/tool_setopt.h | 10 ++++ tests/data/Makefile.inc | 2 +- tests/data/test1481 | 118 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 187 insertions(+), 5 deletions(-) create mode 100644 tests/data/test1481 diff --git a/src/tool_operate.c b/src/tool_operate.c index 5a5fc8745ed..7e2c1eefe02 100644 --- a/src/tool_operate.c +++ b/src/tool_operate.c @@ -1763,11 +1763,11 @@ static CURLcode single_transfer(struct GlobalConfig *global, if(config->falsestart) my_setopt(curl, CURLOPT_SSL_FALSESTART, 1L); - my_setopt_enum(curl, CURLOPT_SSLVERSION, - config->ssl_version | config->ssl_version_max); + my_setopt_SSLVERSION(curl, CURLOPT_SSLVERSION, + config->ssl_version | config->ssl_version_max); if(config->proxy) - my_setopt_enum(curl, CURLOPT_PROXY_SSLVERSION, - config->proxy_ssl_version); + my_setopt_SSLVERSION(curl, CURLOPT_PROXY_SSLVERSION, + config->proxy_ssl_version); { long mask = diff --git a/src/tool_setopt.c b/src/tool_setopt.c index b41b6d1d263..656adbda8a2 100644 --- a/src/tool_setopt.c +++ b/src/tool_setopt.c @@ -107,6 +107,16 @@ const struct NameValue setopt_nv_CURL_SSLVERSION[] = { NVEND, }; +const struct NameValue setopt_nv_CURL_SSLVERSION_MAX[] = { + NV(CURL_SSLVERSION_MAX_NONE), + NV(CURL_SSLVERSION_MAX_DEFAULT), + NV(CURL_SSLVERSION_MAX_TLSv1_0), + NV(CURL_SSLVERSION_MAX_TLSv1_1), + NV(CURL_SSLVERSION_MAX_TLSv1_2), + NV(CURL_SSLVERSION_MAX_TLSv1_3), + NVEND, +}; + const struct NameValue setopt_nv_CURL_TIMECOND[] = { NV(CURL_TIMECOND_IFMODSINCE), NV(CURL_TIMECOND_IFUNMODSINCE), @@ -296,6 +306,50 @@ CURLcode tool_setopt_enum(CURL *curl, struct GlobalConfig *config, return ret; } +/* setopt wrapper for CURLOPT_SSLVERSION */ +CURLcode tool_setopt_SSLVERSION(CURL *curl, struct GlobalConfig *config, + const char *name, CURLoption tag, + long lval) +{ + CURLcode ret = CURLE_OK; + bool skip = FALSE; + + ret = curl_easy_setopt(curl, tag, lval); + if(!lval) + skip = TRUE; + + if(config->libcurl && !skip && !ret) { + /* we only use this for real if --libcurl was used */ + const struct NameValue *nv = NULL; + const struct NameValue *nv2 = NULL; + for(nv = setopt_nv_CURL_SSLVERSION; nv->name; nv++) { + if(nv->value == (lval & 0xffff)) + break; /* found it */ + } + for(nv2 = setopt_nv_CURL_SSLVERSION_MAX; nv2->name; nv2++) { + if(nv2->value == (lval & ~0xffff)) + break; /* found it */ + } + if(!nv->name) { + /* If no definition was found, output an explicit value. + * This could happen if new values are defined and used + * but the NameValue list is not updated. */ + CODE2("curl_easy_setopt(hnd, %s, %ldL);", name, lval); + } + else { + CODE3("curl_easy_setopt(hnd, %s, (long)(%s | %s));", + name, nv->name, nv2->name); + } + } + +#ifdef DEBUGBUILD + if(ret) + warnf(config, "option %s returned error (%d)", name, (int)ret); +#endif +nomem: + return ret; +} + /* setopt wrapper for bitmasks */ CURLcode tool_setopt_bitmask(CURL *curl, struct GlobalConfig *config, const char *name, CURLoption tag, diff --git a/src/tool_setopt.h b/src/tool_setopt.h index cd59a74cd8b..6588da9ced0 100644 --- a/src/tool_setopt.h +++ b/src/tool_setopt.h @@ -52,6 +52,7 @@ extern const struct NameValue setopt_nv_CURLPROXY[]; extern const struct NameValue setopt_nv_CURL_SOCKS_PROXY[]; extern const struct NameValue setopt_nv_CURL_HTTP_VERSION[]; extern const struct NameValue setopt_nv_CURL_SSLVERSION[]; +extern const struct NameValue setopt_nv_CURL_SSLVERSION_MAX[]; extern const struct NameValue setopt_nv_CURL_TIMECOND[]; extern const struct NameValue setopt_nv_CURLFTPSSL_CCC[]; extern const struct NameValue setopt_nv_CURLUSESSL[]; @@ -81,6 +82,9 @@ extern const struct NameValueUnsigned setopt_nv_CURLHSTS[]; CURLcode tool_setopt_enum(CURL *curl, struct GlobalConfig *config, const char *name, CURLoption tag, const struct NameValue *nv, long lval); +CURLcode tool_setopt_SSLVERSION(CURL *curl, struct GlobalConfig *config, + const char *name, CURLoption tag, + long lval); CURLcode tool_setopt_flags(CURL *curl, struct GlobalConfig *config, const char *name, CURLoption tag, const struct NameValue *nv, long lval); @@ -106,6 +110,9 @@ CURLcode tool_setopt(CURL *curl, bool str, struct GlobalConfig *global, #define my_setopt_enum(x,y,z) \ SETOPT_CHECK(tool_setopt_enum(x, global, #y, y, setopt_nv_ ## y, z), y) +#define my_setopt_SSLVERSION(x,y,z) \ + SETOPT_CHECK(tool_setopt_SSLVERSION(x, global, #y, y, z), y) + #define my_setopt_bitmask(x,y,z) \ SETOPT_CHECK(tool_setopt_bitmask(x, global, #y, y, setopt_nv_ ## y, z), y) @@ -132,6 +139,9 @@ CURLcode tool_setopt(CURL *curl, bool str, struct GlobalConfig *global, #define my_setopt_enum(x,y,z) \ SETOPT_CHECK(curl_easy_setopt(x, y, z), y) +#define my_setopt_SSLVERSION(x,y,z) \ + SETOPT_CHECK(curl_easy_setopt(x, y, z), y) + #define my_setopt_bitmask(x,y,z) \ SETOPT_CHECK(curl_easy_setopt(x, y, z), y) diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 06bc5c54f96..50b404b468b 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -188,7 +188,7 @@ test1447 test1448 test1449 test1450 test1451 test1452 test1453 test1454 \ test1455 test1456 test1457 test1458 test1459 test1460 test1461 test1462 \ test1463 test1464 test1465 test1466 test1467 test1468 test1469 test1470 \ test1471 test1472 test1473 test1474 test1475 test1476 test1477 test1478 \ -test1479 test1480 \ +test1479 test1480 test1481 \ \ test1500 test1501 test1502 test1503 test1504 test1505 test1506 test1507 \ test1508 test1509 test1510 test1511 test1512 test1513 test1514 test1515 \ diff --git a/tests/data/test1481 b/tests/data/test1481 new file mode 100644 index 00000000000..ca638f51309 --- /dev/null +++ b/tests/data/test1481 @@ -0,0 +1,118 @@ + + + +HTTP +HTTP GET +--libcurl + + + +# Server-side + + +HTTP/1.1 200 OK +Date: Thu, 29 Jul 2008 14:49:00 GMT +Server: test-server/fake +Content-Length: 0 +Connection: close + + + + +# Client-side + + +http + + +proxy +ssl + + +--libcurl with TLS version options + + +SSL_CERT_FILE= + + +http://moo/ --libcurl %LOGDIR/test%TESTNUMBER.c --tls-max 1.3 --proxy-tlsv1 -x http://%HOSTIP:%HTTPPORT + + + +# Verify data after the test has been "shot" + + +GET http://moo/ HTTP/1.1 +Host: moo +User-Agent: curl/%VERSION +Accept: */* +Proxy-Connection: Keep-Alive + + + +s/(USERAGENT, \")[^\"]+/${1}stripped/ +# CURLOPT_SSL_VERIFYPEER, SSH_KNOWNHOSTS and HTTP_VERSION vary with +# CURLOPT_INTERLEAVEDATA requires RTSP protocol +# configurations - just ignore them +$_ = '' if /CURLOPT_SSL_VERIFYPEER/ +$_ = '' if /CURLOPT_SSH_KNOWNHOSTS/ +$_ = '' if /CURLOPT_HTTP_VERSION/ +$_ = '' if /CURLOPT_HTTP09_ALLOWED/ +$_ = '' if /CURLOPT_INTERLEAVEDATA/ + + +/********* Sample code generated by the curl command line tool ********** + * All curl_easy_setopt() options are documented at: + * https://curl.se/libcurl/c/curl_easy_setopt.html + ************************************************************************/ +#include + +int main(int argc, char *argv[]) +{ + CURLcode ret; + CURL *hnd; + + hnd = curl_easy_init(); + curl_easy_setopt(hnd, CURLOPT_BUFFERSIZE, 102400L); + curl_easy_setopt(hnd, CURLOPT_URL, "http://moo/"); + curl_easy_setopt(hnd, CURLOPT_PROXY, "http://%HOSTIP:%HTTPPORT"); + curl_easy_setopt(hnd, CURLOPT_USERAGENT, "stripped"); + curl_easy_setopt(hnd, CURLOPT_MAXREDIRS, 50L); + curl_easy_setopt(hnd, CURLOPT_SSLVERSION, (long)(CURL_SSLVERSION_DEFAULT | CURL_SSLVERSION_MAX_TLSv1_3)); + curl_easy_setopt(hnd, CURLOPT_PROXY_SSLVERSION, (long)(CURL_SSLVERSION_TLSv1 | CURL_SSLVERSION_MAX_NONE)); + curl_easy_setopt(hnd, CURLOPT_VERBOSE, 1L); +%if ftp + curl_easy_setopt(hnd, CURLOPT_FTP_SKIP_PASV_IP, 1L); +%endif + curl_easy_setopt(hnd, CURLOPT_TCP_KEEPALIVE, 1L); + + /* Here is a list of options the curl code used that cannot get generated + as source easily. You may choose to either not use them or implement + them yourself. + + CURLOPT_WRITEDATA was set to an object pointer + CURLOPT_WRITEFUNCTION was set to a function pointer + CURLOPT_READDATA was set to an object pointer + CURLOPT_READFUNCTION was set to a function pointer + CURLOPT_SEEKDATA was set to an object pointer + CURLOPT_SEEKFUNCTION was set to a function pointer + CURLOPT_ERRORBUFFER was set to an object pointer + CURLOPT_STDERR was set to an object pointer + CURLOPT_DEBUGFUNCTION was set to a function pointer + CURLOPT_DEBUGDATA was set to an object pointer + CURLOPT_HEADERFUNCTION was set to a function pointer + CURLOPT_HEADERDATA was set to an object pointer + + */ + + ret = curl_easy_perform(hnd); + + curl_easy_cleanup(hnd); + hnd = NULL; + + return (int)ret; +} +/**** End of sample code ****/ + + + From 1356028f2c10f1bdd689bf18c41466d740e72c05 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Mar 2024 23:11:53 +0100 Subject: [PATCH 475/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 49 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index e45b371d2d5..0b278083529 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.7.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3113 + Contributors: 3115 This release includes the following changes: @@ -16,7 +16,6 @@ This release includes the following changes: This release includes the following bugfixes: - o _VARIABLES.md: improve the description [105] 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] @@ -37,6 +36,7 @@ This release includes the following bugfixes: 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 configure.ac: find libpsl with pkg-config [79] o configure: add warning for using TLS libraries without 1.3 support [26] @@ -49,6 +49,7 @@ This release includes the following bugfixes: 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] @@ -76,7 +77,9 @@ This release includes the following bugfixes: 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: fix push discard [124] @@ -99,12 +102,14 @@ This release includes the following bugfixes: 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: 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] @@ -124,6 +129,7 @@ This release includes the following bugfixes: 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 @@ -132,11 +138,13 @@ This release includes the following bugfixes: 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 test1165: improve pattern matching [60] o tests: support setting/using blank content env variables o TIMER_STARTTRANSFER: set the same for everyone [82] o tool_cb_hdr: only parse etag + content-disposition for 2xx [9] + 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] @@ -144,6 +152,7 @@ This release includes the following bugfixes: 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] @@ -163,21 +172,22 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - 5533asdg on github, Andreas Kiefer, av223119 on github, Boris Verkhovskiy, - Brett Buddin, Chris Webb, Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, - Daniel Szmulewicz, DasKutti on github, dependabot[bot], Dirk Hünniger, + 5533asdg on github, Andreas Kiefer, av223119 on github, + awesomekosm on github, Boris Verkhovskiy, Brett Buddin, Chris Webb, + Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, Daniel Szmulewicz, + DasKutti on github, dependabot[bot], Dexter Gerig, Dirk Hünniger, Dmitry Karpov, Dmitry Tretyakov, edmcln on github, Erik Schnetter, Evgeny Grin (Karlson2k), Fabian Vogt, Fabrice Fontaine, Faraz Fallahi, - Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, - Joel Depooter, Jon Rumsey, Jordan Brown, Karthikdasari0423, - Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, - Lukáš Zaoral, Marcel Raad, Michael Forney, Michael Kaufmann, Michał Antoniak, - Nikita Taranov, Patrick Monnerat, Paweł Witas, Peter Krefting, RainRat, - Ramiro Garcia, Ray Satiro, Richard Levitte, Robert Moreton, Rudi Heitbaum, - Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, Sebastian Neubauer, - Sergey Bronnikov, Simon K, Stefan Eissing, Tal Regev, Viktor Szakats, - vulnerabilityspotter on hackerone - (60 contributors) + Geeknik Labs, Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, + Jiawen Geng, Joel Depooter, Jon Rumsey, Jordan Brown, Karthikdasari0423, + Karthikdasari0423 on github, Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, + LeeRiva, Louis Solofrizzo, Lukáš Zaoral, Marcel Raad, Michael Forney, + Michael Kaufmann, Michał Antoniak, Nikita Taranov, Patrick Monnerat, + Paweł Witas, Peter Krefting, RainRat, Ramiro Garcia, Ray Satiro, + Richard Levitte, Robert Moreton, Rudi Heitbaum, Ryan Carsten Schmidt, + Scott Mutter, Scott Talbert, Sebastian Neubauer, Sergey Bronnikov, Simon K, + Stefan Eissing, Tal Regev, Viktor Szakats, vulnerabilityspotter on hackerone + (64 contributors) References to bug reports and discussions on issues: @@ -307,7 +317,16 @@ References to bug reports and discussions on issues: [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 + [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 From c765b04d114cdd982f93583bcb943dd828351733 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 8 Mar 2024 09:37:27 +0100 Subject: [PATCH 476/509] TLS: start shutdown only when peer did not already close MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - When curl sees a TCP close from the peer, do not start a TLS shutdown. TLS shutdown is a handshake and if the peer already closed the connection, it is not interested in participating. Reported-by: dfdity on github Assisted-by: Jiří Bok Assisted-by: Pēteris Caune Fixes #10290 Closes #13087 --- lib/cw-out.c | 2 +- lib/vtls/gtls.c | 4 +++- lib/vtls/openssl.c | 34 +++++++++++++++++++++++++++++++--- lib/vtls/rustls.c | 5 ++++- lib/vtls/vtls_int.h | 1 + lib/vtls/wolfssl.c | 5 ++++- 6 files changed, 44 insertions(+), 7 deletions(-) diff --git a/lib/cw-out.c b/lib/cw-out.c index 25a27a68cd6..c1688378179 100644 --- a/lib/cw-out.c +++ b/lib/cw-out.c @@ -231,7 +231,7 @@ static CURLcode cw_out_ptr_flush(struct cw_out_ctx *ctx, } if(nwritten != wlen) { failf(data, "Failure writing output to destination, " - "passed %zu returned %zu", wlen, nwritten); + "passed %zu returned %zd", wlen, nwritten); return CURLE_WRITE_ERROR; } *pconsumed += nwritten; diff --git a/lib/vtls/gtls.c b/lib/vtls/gtls.c index b95c5be3c5e..6eaa6a8f739 100644 --- a/lib/vtls/gtls.c +++ b/lib/vtls/gtls.c @@ -117,6 +117,8 @@ static ssize_t gtls_pull(void *s, void *buf, size_t blen) (CURLE_AGAIN == result)? EAGAIN : EINVAL); nread = -1; } + else if(nread == 0) + connssl->peer_closed = TRUE; return nread; } @@ -1489,7 +1491,7 @@ static int gtls_shutdown(struct Curl_cfilter *cf, bool done = FALSE; char buf[120]; - while(!done) { + while(!done && !connssl->peer_closed) { int what = SOCKET_READABLE(Curl_conn_cf_get_socket(cf, data), SSL_SHUTDOWN_TIMEOUT); if(what > 0) { diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c index eda36606c56..a3953f6c3f8 100644 --- a/lib/vtls/openssl.c +++ b/lib/vtls/openssl.c @@ -769,6 +769,9 @@ static int ossl_bio_cf_in_read(BIO *bio, char *buf, int blen) if(CURLE_AGAIN == result) BIO_set_retry_read(bio); } + else if(nread == 0) { + connssl->peer_closed = TRUE; + } /* Before returning server replies to the SSL instance, we need * to have setup the x509 store or verification will fail. */ @@ -1887,16 +1890,41 @@ static void ossl_close(struct Curl_cfilter *cf, struct Curl_easy *data) DEBUGASSERT(backend); if(backend->handle) { - if(cf->next && cf->next->connected) { + /* Send the TLS shutdown if we are still connected *and* if + * the peer did not already close the connection. */ + if(cf->next && cf->next->connected && !connssl->peer_closed) { char buf[1024]; int nread, err; long sslerr; /* Maybe the server has already sent a close notify alert. Read it to avoid an RST on the TCP connection. */ - (void)SSL_read(backend->handle, buf, (int)sizeof(buf)); ERR_clear_error(); - if(SSL_shutdown(backend->handle) == 1) { + nread = SSL_read(backend->handle, buf, (int)sizeof(buf)); + err = SSL_get_error(backend->handle, nread); + if(!nread && err == SSL_ERROR_ZERO_RETURN) { + CURLcode result; + ssize_t n; + size_t blen = sizeof(buf); + CURL_TRC_CF(data, cf, "peer has shutdown TLS"); + /* SSL_read() will not longer touch the socket, let's receive + * directly from the next filter to see if the underlying + * connection has also been closed. */ + n = Curl_conn_cf_recv(cf->next, data, buf, blen, &result); + if(!n) { + connssl->peer_closed = TRUE; + CURL_TRC_CF(data, cf, "peer closed connection"); + } + } + ERR_clear_error(); + if(connssl->peer_closed) { + /* As the peer closed, we do not expect it to read anything more we + * may send. It may be harmful, leading to TCP RST and delaying + * a lingering close. Just leave. */ + CURL_TRC_CF(data, cf, "not from sending TLS shutdown on " + "connection closed by peer"); + } + else if(SSL_shutdown(backend->handle) == 1) { CURL_TRC_CF(data, cf, "SSL shutdown finished"); } else { diff --git a/lib/vtls/rustls.c b/lib/vtls/rustls.c index 367d7a5f409..ceb26c5bd95 100644 --- a/lib/vtls/rustls.c +++ b/lib/vtls/rustls.c @@ -86,6 +86,7 @@ static int read_cb(void *userdata, uint8_t *buf, uintptr_t len, uintptr_t *out_n) { struct io_ctx *io_ctx = userdata; + struct ssl_connect_data *const connssl = io_ctx->cf->ctx; CURLcode result; int ret = 0; ssize_t nread = Curl_conn_cf_recv(io_ctx->cf->next, io_ctx->data, @@ -97,6 +98,8 @@ read_cb(void *userdata, uint8_t *buf, uintptr_t len, uintptr_t *out_n) else ret = EINVAL; } + else if(nread == 0) + connssl->peer_closed = TRUE; *out_n = (int)nread; return ret; } @@ -697,7 +700,7 @@ cr_close(struct Curl_cfilter *cf, struct Curl_easy *data) DEBUGASSERT(backend); - if(backend->conn) { + if(backend->conn && !connssl->peer_closed) { rustls_connection_send_close_notify(backend->conn); n = cr_send(cf, data, NULL, 0, &tmperr); if(n < 0) { diff --git a/lib/vtls/vtls_int.h b/lib/vtls/vtls_int.h index af7ae552edc..0361fa95a8d 100644 --- a/lib/vtls/vtls_int.h +++ b/lib/vtls/vtls_int.h @@ -76,6 +76,7 @@ struct ssl_connect_data { int port; /* remote port at origin */ BIT(use_alpn); /* if ALPN shall be used in handshake */ BIT(reused_session); /* session-ID was reused for this */ + BIT(peer_closed); /* peer has closed connection */ }; diff --git a/lib/vtls/wolfssl.c b/lib/vtls/wolfssl.c index a3c017ceaab..c264639bacd 100644 --- a/lib/vtls/wolfssl.c +++ b/lib/vtls/wolfssl.c @@ -321,6 +321,8 @@ static int wolfssl_bio_cf_in_read(WOLFSSL_BIO *bio, char *buf, int blen) wolfSSL_BIO_clear_retry_flags(bio); if(nread < 0 && CURLE_AGAIN == result) BIO_set_retry_read(bio); + else if(nread == 0) + connssl->peer_closed = TRUE; return (int)nread; } @@ -1059,7 +1061,8 @@ static void wolfssl_close(struct Curl_cfilter *cf, struct Curl_easy *data) /* Maybe the server has already sent a close notify alert. Read it to avoid an RST on the TCP connection. */ (void)wolfSSL_read(backend->handle, buf, (int)sizeof(buf)); - (void)wolfSSL_shutdown(backend->handle); + if(!connssl->peer_closed) + (void)wolfSSL_shutdown(backend->handle); wolfSSL_free(backend->handle); backend->handle = NULL; } From 6ea75877fa8e16584c14c180d27649a3cef33db6 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Thu, 14 Mar 2024 12:28:46 +0100 Subject: [PATCH 477/509] test 1541: verify getinfo values on first header callback Reported-by: chensong1211 on github Ref: #13125 Closes #13128 --- tests/data/Makefile.inc | 2 +- tests/data/test1541 | 73 ++++++++++++++ tests/libtest/Makefile.inc | 5 +- tests/libtest/lib1541.c | 196 ++++++++++++++++++------------------- 4 files changed, 172 insertions(+), 104 deletions(-) create mode 100644 tests/data/test1541 diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 50b404b468b..09675fd476d 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -195,7 +195,7 @@ test1508 test1509 test1510 test1511 test1512 test1513 test1514 test1515 \ test1516 test1517 test1518 test1519 test1520 test1521 test1522 test1523 \ test1524 test1525 test1526 test1527 test1528 test1529 test1530 test1531 \ test1532 test1533 test1534 test1535 test1536 test1537 test1538 test1539 \ -test1540 test1542 test1543 test1544 test1545 \ +test1540 test1541 test1542 test1543 test1544 test1545 \ \ test1550 test1551 test1552 test1553 test1554 test1555 test1556 test1557 \ test1558 test1559 test1560 test1561 test1562 test1563 test1564 test1565 \ diff --git a/tests/data/test1541 b/tests/data/test1541 new file mode 100644 index 00000000000..5094c3513cf --- /dev/null +++ b/tests/data/test1541 @@ -0,0 +1,73 @@ + + + +HTTP +HTTP GET +chunked Transfer-Encoding +Trailer: +DELAY + + + +# Server-side + + +HTTP/1.1 200 OK swsclose +Transfer-Encoding: chunked + +4 +data +5 +d474 + +0 + + + +CURLINFO_CONNECT_TIME_T on 1st header is OK +CURLINFO_PRETRANSFER_TIME_T on 1st header is OK +CURLINFO_STARTTRANSFER_TIME_T on 1st header is OK +CURLINFO_TOTAL_TIME_T on 1st header is OK +CURLINFO_APPCONNECT_TIME_T on 1st header is OK +CURLINFO_SPEED_DOWNLOAD_T on 1st header is OK +HTTP/1.1 200 OK swsclose +Transfer-Encoding: chunked + +datad474 +CURLINFO_CONNECT_TIME_T on done is OK +CURLINFO_PRETRANSFER_TIME_T on done is OK +CURLINFO_STARTTRANSFER_TIME_T on done is OK +CURLINFO_APPCONNECT_TIME_T on done is OK +CURLINFO_SPEED_DOWNLOAD_T on done is OK +CURLINFO_TOTAL_TIME_T on done is OK + + +writedelay: 10 + + +# Client-side + + +http + + +lib%TESTNUMBER + + +chunked with trailers and pausing the receive + + +http://%HOSTIP:%HTTPPORT/%TESTNUMBER + + + +# Verify data after the test has been "shot" + + +GET /%TESTNUMBER HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +Accept: */* + + + + diff --git a/tests/libtest/Makefile.inc b/tests/libtest/Makefile.inc index 32cc180b02b..9f7cec60274 100644 --- a/tests/libtest/Makefile.inc +++ b/tests/libtest/Makefile.inc @@ -59,7 +59,7 @@ noinst_PROGRAMS = chkhostname libauthretry libntlmconnect libprereq \ lib1518 lib1520 lib1521 lib1522 lib1523 \ lib1525 lib1526 lib1527 lib1528 lib1529 lib1530 lib1531 lib1532 lib1533 \ lib1534 lib1535 lib1536 lib1537 lib1538 lib1539 \ - lib1540 lib1542 lib1543 lib1545 \ + lib1540 lib1541 lib1542 lib1543 lib1545 \ lib1550 lib1551 lib1552 lib1553 lib1554 lib1555 lib1556 lib1557 \ lib1558 lib1559 lib1560 lib1564 lib1565 lib1567 lib1568 lib1569 \ lib1591 lib1592 lib1593 lib1594 lib1596 lib1597 lib1598 \ @@ -464,6 +464,9 @@ lib1539_CPPFLAGS = $(AM_CPPFLAGS) -DLIB1539 lib1540_SOURCES = lib1540.c $(SUPPORTFILES) $(TESTUTIL) $(WARNLESS) lib1540_LDADD = $(TESTUTIL_LIBS) +lib1541_SOURCES = lib1541.c $(SUPPORTFILES) $(TESTUTIL) $(WARNLESS) +lib1541_LDADD = $(TESTUTIL_LIBS) + lib1542_SOURCES = lib1542.c $(SUPPORTFILES) $(TESTUTIL) $(TSTTRACE) $(WARNLESS) lib1542_LDADD = $(TESTUTIL_LIBS) diff --git a/tests/libtest/lib1541.c b/tests/libtest/lib1541.c index 7146288683c..fdb8a04b579 100644 --- a/tests/libtest/lib1541.c +++ b/tests/libtest/lib1541.c @@ -21,140 +21,132 @@ * SPDX-License-Identifier: curl * ***************************************************************************/ -/* - * KNOW_BUGS "A shared connection cache is not thread-safe" - * - * This source code was used to verify shared connection cache but since this - * is a known issue the test is no longer built or run. This code is here to - * allow for testing once someone gets to work on fixing this. - */ #include "test.h" #include "testutil.h" #include "warnless.h" #include "memdebug.h" -#ifdef HAVE_PTHREAD_H -#include -#include - -/* number of threads to fire up in parallel */ -#define NUM_THREADS 67 - -/* for how many seconds each thread will loop */ -#define RUN_FOR_SECONDS 7 +struct transfer_status { + CURL *easy; + int hd_count; + int bd_count; + CURLcode result; +}; -static pthread_mutex_t connlock; +#define KN(a) a, #a -static size_t write_db(void *ptr, size_t size, size_t nmemb, void *data) +static int geterr(const char *name, CURLcode val, int lineno) { - /* not interested in the downloaded bytes, return the size */ - (void)ptr; /* unused */ - (void)data; /* unused */ - return (size_t)(size * nmemb); + printf("CURLINFO_%s returned %d, \"%s\" on line %d\n", + name, val, curl_easy_strerror(val), lineno); + return (int)val; } -static void lock_cb(CURL *handle, curl_lock_data data, - curl_lock_access access, void *userptr) +static void report_time(const char *key, const char *where, curl_off_t time, + bool ok) { - (void)access; /* unused */ - (void)userptr; /* unused */ - (void)handle; /* unused */ - (void)data; /* unused */ - pthread_mutex_lock(&connlock); + if(ok) + printf("%s on %s is OK\n", key, where); + else + printf("%s on %s is WRONG: %" CURL_FORMAT_CURL_OFF_T "\n", + key, where, time); } -static void unlock_cb(CURL *handle, curl_lock_data data, - void *userptr) +static void check_time(CURL *easy, int key, const char *name, + const char *where) { - (void)userptr; /* unused */ - (void)handle; /* unused */ - (void)data; /* unused */ - pthread_mutex_unlock(&connlock); + curl_off_t tval; + CURLcode res = curl_easy_getinfo(easy, (CURLINFO)key, &tval); + if(res) { + geterr(name, res, __LINE__); + } + else + report_time(name, where, tval, tval > 0); } -static void init_locks(void) +static void check_time0(CURL *easy, int key, const char *name, + const char *where) { - pthread_mutex_init(&connlock, NULL); + curl_off_t tval; + CURLcode res = curl_easy_getinfo(easy, (CURLINFO)key, &tval); + if(res) { + geterr(name, res, __LINE__); + } + else + report_time(name, where, tval, !tval); } -static void kill_locks(void) +static size_t header_callback(void *ptr, size_t size, size_t nmemb, + void *userp) { - pthread_mutex_destroy(&connlock); + struct transfer_status *st = (struct transfer_status *)userp; + size_t len = size * nmemb; + + (void)ptr; + if(!st->hd_count++) { + /* first header, check some CURLINFO value to be reported. See #13125 */ + check_time(st->easy, KN(CURLINFO_CONNECT_TIME_T), "1st header"); + check_time(st->easy, KN(CURLINFO_PRETRANSFER_TIME_T), "1st header"); + check_time(st->easy, KN(CURLINFO_STARTTRANSFER_TIME_T), "1st header"); + /* continuously updated */ + check_time(st->easy, KN(CURLINFO_TOTAL_TIME_T), "1st header"); + /* no SSL, must be 0 */ + check_time0(st->easy, KN(CURLINFO_APPCONNECT_TIME_T), "1st header"); + /* download not really started */ + check_time0(st->easy, KN(CURLINFO_SPEED_DOWNLOAD_T), "1st header"); + } + (void)fwrite(ptr, size, nmemb, stdout); + return len; } -struct initurl { - const char *url; - CURLSH *share; - int threadno; -}; - -static void *run_thread(void *ptr) +static size_t write_callback(void *ptr, size_t size, size_t nmemb, void *userp) { - struct initurl *u = (struct initurl *)ptr; - int i; - time_t end = time(NULL) + RUN_FOR_SECONDS; - - for(i = 0; time(NULL) < end; i++) { - CURL *curl = curl_easy_init(); - curl_easy_setopt(curl, CURLOPT_URL, u->url); - curl_easy_setopt(curl, CURLOPT_VERBOSE, 0L); - curl_easy_setopt(curl, CURLOPT_SHARE, u->share); - curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_db); - curl_easy_perform(curl); /* ignores error */ - curl_easy_cleanup(curl); - fprintf(stderr, "Thread %d transfer %d\n", u->threadno, i); - } + struct transfer_status *st = (struct transfer_status *)userp; - return NULL; + (void)ptr; + (void)st; + fwrite(ptr, size, nmemb, stdout); + return size * nmemb; } int test(char *URL) { - pthread_t tid[NUM_THREADS]; - int i; - CURLSH *share; - struct initurl url[NUM_THREADS]; - - /* Must initialize libcurl before any threads are started */ - curl_global_init(CURL_GLOBAL_ALL); - - share = curl_share_init(); - curl_share_setopt(share, CURLSHOPT_LOCKFUNC, lock_cb); - curl_share_setopt(share, CURLSHOPT_UNLOCKFUNC, unlock_cb); - curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); - - init_locks(); - - for(i = 0; i< NUM_THREADS; i++) { - int error; - url[i].url = URL; - url[i].share = share; - url[i].threadno = i; - error = pthread_create(&tid[i], NULL, run_thread, &url[i]); - if(0 != error) - fprintf(stderr, "Couldn't run thread number %d, errno %d\n", i, error); - else - fprintf(stderr, "Thread %d, gets %s\n", i, URL); - } + CURL *curls = NULL; + int res = 0; + struct transfer_status st; - /* now wait for all threads to terminate */ - for(i = 0; i< NUM_THREADS; i++) { - pthread_join(tid[i], NULL); - fprintf(stderr, "Thread %d terminated\n", i); - } + start_test_timing(); + + memset(&st, 0, sizeof(st)); + + global_init(CURL_GLOBAL_ALL); + + easy_init(curls); + st.easy = curls; /* to allow callbacks access */ + + easy_setopt(curls, CURLOPT_URL, URL); + easy_setopt(curls, CURLOPT_WRITEFUNCTION, write_callback); + easy_setopt(curls, CURLOPT_WRITEDATA, &st); + easy_setopt(curls, CURLOPT_HEADERFUNCTION, header_callback); + easy_setopt(curls, CURLOPT_HEADERDATA, &st); + + easy_setopt(curls, CURLOPT_NOPROGRESS, 0L); - kill_locks(); + res = curl_easy_perform(curls); - curl_share_cleanup(share); + check_time(curls, KN(CURLINFO_CONNECT_TIME_T), "done"); + check_time(curls, KN(CURLINFO_PRETRANSFER_TIME_T), "done"); + check_time(curls, KN(CURLINFO_STARTTRANSFER_TIME_T), "done"); + /* no SSL, must be 0 */ + check_time0(curls, KN(CURLINFO_APPCONNECT_TIME_T), "done"); + check_time(curls, KN(CURLINFO_SPEED_DOWNLOAD_T), "done"); + check_time(curls, KN(CURLINFO_TOTAL_TIME_T), "done"); + +test_cleanup: + + curl_easy_cleanup(curls); curl_global_cleanup(); - return 0; -} -#else /* without pthread, this test doesn't work */ -int test(char *URL) -{ - (void)URL; - return 0; + return (int)res; /* return the final return code */ } -#endif From 77b0571cdc941a974c50dc7ee334af0b41288cd8 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Wed, 13 Mar 2024 11:42:17 +0100 Subject: [PATCH 478/509] http: revisit http_perhapsrewind() - use facilities provided by client readers better - work also for non-uploading requests like GET/HEAD - update documentation Closes #13117 --- lib/cf-h1-proxy.c | 6 ++ lib/cf-h2-proxy.c | 11 +++- lib/http.c | 152 +++++++++++++++++----------------------------- 3 files changed, 73 insertions(+), 96 deletions(-) diff --git a/lib/cf-h1-proxy.c b/lib/cf-h1-proxy.c index 57cf9a1ae11..ed6322c10d0 100644 --- a/lib/cf-h1-proxy.c +++ b/lib/cf-h1-proxy.c @@ -237,6 +237,8 @@ static CURLcode start_CONNECT(struct Curl_cfilter *cf, http_minor = (cf->conn->http_proxy.proxytype == CURLPROXY_HTTP_1_0) ? 0 : 1; result = Curl_h1_req_write_head(req, http_minor, &ts->request_data); + if(!result) + result = Curl_creader_set_null(data); out: if(result) @@ -749,6 +751,10 @@ static CURLcode start_CONNECT(struct Curl_cfilter *cf, if(result) goto error; + result = Curl_creader_set_null(data); + if(result) + goto error; + sendtask = hyper_clientconn_send(client, req); if(!sendtask) { failf(data, "hyper_clientconn_send"); diff --git a/lib/cf-h2-proxy.c b/lib/cf-h2-proxy.c index f8f2f3c417d..78dc222fa8b 100644 --- a/lib/cf-h2-proxy.c +++ b/lib/cf-h2-proxy.c @@ -38,6 +38,7 @@ #include "http2.h" #include "http_proxy.h" #include "multiif.h" +#include "sendf.h" #include "cf-h2-proxy.h" /* The last 3 #include files should be in this order */ @@ -954,6 +955,9 @@ static CURLcode submit_CONNECT(struct Curl_cfilter *cf, struct httpreq *req = NULL; result = Curl_http_proxy_create_CONNECT(&req, cf, data, 2); + if(result) + goto out; + result = Curl_creader_set_null(data); if(result) goto out; @@ -1125,7 +1129,12 @@ static CURLcode cf_h2_proxy_connect(struct Curl_cfilter *cf, out: *done = (result == CURLE_OK) && (ts->state == H2_TUNNEL_ESTABLISHED); - cf->connected = *done; + if(*done) { + cf->connected = TRUE; + /* The real request will follow the CONNECT, reset request partially */ + Curl_req_soft_reset(&data->req, data); + Curl_client_reset(data); + } CF_DATA_RESTORE(cf, save); return result; } diff --git a/lib/http.c b/lib/http.c index 52ae1ae69d9..1d741fbd8d2 100644 --- a/lib/http.c +++ b/lib/http.c @@ -405,123 +405,88 @@ static bool pickoneauth(struct auth *pick, unsigned long mask) /* * http_perhapsrewind() * - * If we are doing POST or PUT { - * If we have more data to send { - * If we are doing NTLM { - * Keep sending since we must not disconnect - * } - * else { - * If there is more than just a little data left to send, close - * the current connection by force. - * } - * } - * If we have sent any data { - * If we don't have track of all the data { - * call app to tell it to rewind - * } - * else { - * rewind internally so that the operation can restart fine - * } - * } - * } + * The current request needs to be done again - maybe due to a follow + * or authentication negotiation. Check if: + * 1) a rewind of the data sent to the server is necessary + * 2) the current transfer should continue or be stopped early */ static CURLcode http_perhapsrewind(struct Curl_easy *data, struct connectdata *conn) { - struct HTTP *http = data->req.p.http; - curl_off_t bytessent; + curl_off_t bytessent = data->req.writebytecount; curl_off_t expectsend = Curl_creader_total_length(data); + curl_off_t upload_remain = (expectsend >= 0)? (expectsend - bytessent) : -1; + bool little_upload_remains = (upload_remain >= 0 && upload_remain < 2000); + bool needs_rewind = Curl_creader_needs_rewind(data); + /* By default, we'd like to abort the transfer when little or + * unknown amount remains. But this may be overridden by authentications + * further below! */ + bool abort_upload = (!data->req.upload_done && !little_upload_remains); + const char *ongoing_auth = NULL; + + /* We need a rewind before uploading client read data again. The + * checks below just influence of the upload is to be continued + * or aborted early. + * This depends on how much remains to be sent and in what state + * the authentication is. Some auth schemes such as NTLM do not work + * for a new connection. */ + if(needs_rewind) { + infof(data, "Need to rewind upload for next request"); + Curl_creader_set_rewind(data, TRUE); + } - if(!http) - /* If this is still NULL, we have not reach very far and we can safely - skip this rewinding stuff */ - return CURLE_OK; - - if(!expectsend) - /* not sending any body */ + if(conn->bits.close) + /* If we already decided to close this connection, we cannot veto. */ return CURLE_OK; - if(!conn->bits.protoconnstart) - /* HTTP CONNECT in progress: there is no body */ - expectsend = 0; - - bytessent = data->req.writebytecount; - Curl_creader_set_rewind(data, FALSE); - - if((expectsend == -1) || (expectsend > bytessent)) { + if(abort_upload) { + /* We'd like to abort the upload - but should we? */ #if defined(USE_NTLM) - /* There is still data left to send */ if((data->state.authproxy.picked == CURLAUTH_NTLM) || (data->state.authhost.picked == CURLAUTH_NTLM) || (data->state.authproxy.picked == CURLAUTH_NTLM_WB) || (data->state.authhost.picked == CURLAUTH_NTLM_WB)) { - if(((expectsend - bytessent) < 2000) || - (conn->http_ntlm_state != NTLMSTATE_NONE) || + ongoing_auth = "NTML"; + if((conn->http_ntlm_state != NTLMSTATE_NONE) || (conn->proxy_ntlm_state != NTLMSTATE_NONE)) { - /* The NTLM-negotiation has started *OR* there is just a little (<2K) - data left to send, keep on sending. */ - - /* rewind data when completely done sending! */ - if(!data->req.authneg && (conn->writesockfd != CURL_SOCKET_BAD)) { - Curl_creader_set_rewind(data, TRUE); - infof(data, "Rewind stream before next send"); - } - - return CURLE_OK; + /* The NTLM-negotiation has started, keep on sending. + * Need to do further work on same connection */ + abort_upload = FALSE; } - - if(conn->bits.close) - /* this is already marked to get closed */ - return CURLE_OK; - - infof(data, "NTLM send, close instead of sending %" - CURL_FORMAT_CURL_OFF_T " bytes", - (curl_off_t)(expectsend - bytessent)); } #endif #if defined(USE_SPNEGO) /* There is still data left to send */ if((data->state.authproxy.picked == CURLAUTH_NEGOTIATE) || (data->state.authhost.picked == CURLAUTH_NEGOTIATE)) { - if(((expectsend - bytessent) < 2000) || - (conn->http_negotiate_state != GSS_AUTHNONE) || + ongoing_auth = "NEGOTIATE"; + if((conn->http_negotiate_state != GSS_AUTHNONE) || (conn->proxy_negotiate_state != GSS_AUTHNONE)) { - /* The NEGOTIATE-negotiation has started *OR* - there is just a little (<2K) data left to send, keep on sending. */ - - /* rewind data when completely done sending! */ - if(!data->req.authneg && (conn->writesockfd != CURL_SOCKET_BAD)) { - Curl_creader_set_rewind(data, TRUE); - infof(data, "Rewind stream before next send"); - } - - return CURLE_OK; + /* The NEGOTIATE-negotiation has started, keep on sending. + * Need to do further work on same connection */ + abort_upload = FALSE; } - - if(conn->bits.close) - /* this is already marked to get closed */ - return CURLE_OK; - - infof(data, "NEGOTIATE send, close instead of sending %" - CURL_FORMAT_CURL_OFF_T " bytes", - (curl_off_t)(expectsend - bytessent)); } #endif + } - /* This is not NEGOTIATE/NTLM or many bytes left to send: close */ + if(abort_upload) { + if(upload_remain >= 0) + infof(data, "%s%sclose instead of sending %" + CURL_FORMAT_CURL_OFF_T " more bytes", + ongoing_auth? ongoing_auth : "", + ongoing_auth? " send, " : "", + upload_remain); + else + infof(data, "%s%sclose instead of sending unknown amount " + "of more bytes", + ongoing_auth? ongoing_auth : "", + ongoing_auth? " send, " : ""); + /* We decided to abort the ongoing transfer */ streamclose(conn, "Mid-auth HTTP and much data left to send"); + /* FIXME: questionable manipulation here, can we do this differently? */ data->req.size = 0; /* don't download any more than 0 bytes */ - - /* There still is data left to send, but this connection is marked for - closure so we can safely do the rewind right now */ - } - - if(Curl_creader_needs_rewind(data)) { - /* mark for rewind since if we already sent something */ - Curl_creader_set_rewind(data, TRUE); - infof(data, "Please rewind output before next send"); } - return CURLE_OK; } @@ -575,13 +540,10 @@ CURLcode Curl_http_auth_act(struct Curl_easy *data) #endif if(pickhost || pickproxy) { - if((data->state.httpreq != HTTPREQ_GET) && - (data->state.httpreq != HTTPREQ_HEAD) && - !Curl_creader_will_rewind(data)) { - result = http_perhapsrewind(data, conn); - if(result) - return result; - } + result = http_perhapsrewind(data, conn); + if(result) + return result; + /* In case this is GSS auth, the newurl field is already allocated so we must make sure to free it before allocating a new one. As figured out in bug #2284386 */ From 79cdae4fc7f3ffb1a9de1ddde15e39bfe39a992b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 15 Mar 2024 09:38:21 +0100 Subject: [PATCH 479/509] ipv6.md: mention IPv4 mapped addresses Reported-by: Josh Soref Assisted-by: Jay Satiro Fixes #13112 Closes #13131 --- docs/cmdline-opts/ipv6.md | 4 ++++ tests/test1275.pl | 3 ++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/cmdline-opts/ipv6.md b/docs/cmdline-opts/ipv6.md index c33a24c3faa..547f4917c2c 100644 --- a/docs/cmdline-opts/ipv6.md +++ b/docs/cmdline-opts/ipv6.md @@ -22,3 +22,7 @@ Example: 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/tests/test1275.pl b/tests/test1275.pl index 5676a7637fd..47ce7995789 100755 --- a/tests/test1275.pl +++ b/tests/test1275.pl @@ -31,6 +31,7 @@ my %accepted=('curl' => 1, 'libcurl' => 1, + 'macOS' => 1, 'c-ares' => 1); sub checkfile { @@ -65,7 +66,7 @@ sub checkfile { $ignore ^= 1; } if(!$ignore) { - if(($prevl =~ /\.\z/) && ($line =~ /^( *)([a-z-]+)/)) { + if(($prevl =~ /\.\z/) && ($line =~ /^( *)([a-z][A-Za-z-]*)/)) { my ($prefix, $word) = ($1, $2); if($word =~ /^[a-z]/ && !$accepted{$word}) { my $c = length($prefix); From 3d0fd382a29b95561b90b7ea3e7eb04dfdd43538 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Fri, 15 Mar 2024 10:10:13 +0100 Subject: [PATCH 480/509] mbedtls: fix pytest for newer versions Fix the expectations in pytest for newer versions of mbedtls Closes #13132 --- lib/vtls/mbedtls.c | 15 +++++++-------- tests/http/test_10_proxy.py | 8 ++++++-- tests/http/testenv/env.py | 14 +++++++++++--- 3 files changed, 24 insertions(+), 13 deletions(-) diff --git a/lib/vtls/mbedtls.c b/lib/vtls/mbedtls.c index 3fefb612bd1..5f07e78ef7c 100644 --- a/lib/vtls/mbedtls.c +++ b/lib/vtls/mbedtls.c @@ -687,14 +687,13 @@ mbed_connect_step1(struct Curl_cfilter *cf, struct Curl_easy *data) &backend->clicert, &backend->pk); } - if(connssl->peer.sni) { - if(mbedtls_ssl_set_hostname(&backend->ssl, connssl->peer.sni)) { - /* mbedtls_ssl_set_hostname() sets the name to use in CN/SAN checks and - the name to set in the SNI extension. So even if curl connects to a - host specified as an IP address, this function must be used. */ - failf(data, "Failed to set SNI"); - return CURLE_SSL_CONNECT_ERROR; - } + if(mbedtls_ssl_set_hostname(&backend->ssl, connssl->peer.sni? + connssl->peer.sni : connssl->peer.hostname)) { + /* mbedtls_ssl_set_hostname() sets the name to use in CN/SAN checks and + the name to set in the SNI extension. So even if curl connects to a + host specified as an IP address, this function must be used. */ + failf(data, "Failed to set SNI"); + return CURLE_SSL_CONNECT_ERROR; } #ifdef HAS_ALPN diff --git a/tests/http/test_10_proxy.py b/tests/http/test_10_proxy.py index ad3a5990f1c..c191432fb04 100644 --- a/tests/http/test_10_proxy.py +++ b/tests/http/test_10_proxy.py @@ -362,6 +362,10 @@ def test_10_14_proxys_ip_addr(self, env: Env, httpd, proto, repeat): xargs = curl.get_proxy_args(proto=proto, use_ip=True) r = curl.http_download(urls=[url], alpn_proto='http/1.1', with_stats=True, extra_args=xargs) - r.check_response(count=1, http_status=200, - protocol='HTTP/2' if proto == 'h2' else 'HTTP/1.1') + if env.curl_uses_lib('mbedtls') and \ + not env.curl_lib_version_at_least('mbedtls', '3.5.0'): + r.check_exit_code(60) # CURLE_PEER_FAILED_VERIFICATION + else: + r.check_response(count=1, http_status=200, + protocol='HTTP/2' if proto == 'h2' else 'HTTP/1.1') diff --git a/tests/http/testenv/env.py b/tests/http/testenv/env.py index 29f9726f7bd..a207059dcd5 100644 --- a/tests/http/testenv/env.py +++ b/tests/http/testenv/env.py @@ -185,15 +185,15 @@ def httpd_version(self): log.error(f'{self.apxs} failed to run: {e}') return self._httpd_version - def _versiontuple(self, v): + def versiontuple(self, v): v = re.sub(r'(\d+\.\d+(\.\d+)?)(-\S+)?', r'\1', v) return tuple(map(int, v.split('.'))) def httpd_is_at_least(self, minv): if self.httpd_version is None: return False - hv = self._versiontuple(self.httpd_version) - return hv >= self._versiontuple(minv) + hv = self.versiontuple(self.httpd_version) + return hv >= self.versiontuple(minv) def is_complete(self) -> bool: return os.path.isfile(self.httpd) and \ @@ -275,6 +275,14 @@ def curl_lib_version(libname: str) -> str: return lversion[len(prefix):] return 'unknown' + @staticmethod + def curl_lib_version_at_least(libname: str, min_version) -> str: + lversion = Env.curl_lib_version(libname) + if lversion != 'unknown': + return Env.CONFIG.versiontuple(min_version) <= \ + Env.CONFIG.versiontuple(lversion) + return False + @staticmethod def curl_os() -> str: return Env.CONFIG.curl_props['os'] From 80a3b830ccf7d40864bdabd16bbaff8cb4c9703b Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 11 Mar 2024 17:23:15 +0100 Subject: [PATCH 481/509] http: expect 100 rework Move all handling of HTTP's `Expect: 100-continue` feature into a client reader. Add sending flag `KEEP_SEND_TIMED` that triggers transfer sending on general events like a timer. HTTP installs a `CURL_CR_PROTOCOL` reader when announcing `Expect: 100-continue`. That reader works as follows: - on first invocation, records time, starts the `EXPIRE_100_TIMEOUT` timer, disables `KEEP_SEND`, enables `KEEP_SEND_TIMER` and returns 0, eos=FALSE like a paused upload. - on subsequent invocation it checks if the timer has expired. If so, it enables `KEEP_SEND` and switches to passing through reads to the underlying readers. Transfer handling's `readwrite()` will be invoked when a timer expires (like `EXPIRE_100_TIMEOUT`) or when data from the server arrives. Seeing `KEEP_SEND_TIMER`, it will try to upload more data, which triggers reading from the client readers again. Which then may lead to a new pausing or cause the upload to start. Flags and timestamps connected to this have been moved from `SingleRequest` into the reader's context. Closes #13110 --- lib/c-hyper.c | 60 +---- lib/c-hyper.h | 1 - lib/http.c | 237 +++++++++++++----- lib/http.h | 3 + lib/http_chunks.c | 1 + lib/mime.c | 1 + lib/request.c | 24 +- lib/request.h | 2 - lib/rtsp.c | 2 - lib/sendf.c | 33 +++ lib/sendf.h | 17 ++ lib/smtp.c | 1 + lib/transfer.c | 60 +---- lib/url.c | 1 - lib/urldata.h | 9 +- tests/http/test_07_upload.py | 27 ++ .../http/testenv/mod_curltest/mod_curltest.c | 11 +- 17 files changed, 301 insertions(+), 189 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index 70d60bab70a..78d4cd344c0 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -219,17 +219,16 @@ static int hyper_body_chunk(void *userdata, const hyper_buf *chunk) Curl_safefree(data->req.newurl); } #endif - if(data->state.expect100header) { - Curl_expire_done(data, EXPIRE_100_TIMEOUT); + if(Curl_http_exp100_is_selected(data)) { if(data->req.httpcode < 400) { - k->exp100 = EXP100_SEND_DATA; - if(data->hyp.exp100_waker) { - hyper_waker_wake(data->hyp.exp100_waker); - data->hyp.exp100_waker = NULL; + Curl_http_exp100_got100(data); + if(data->hyp.send_body_waker) { + hyper_waker_wake(data->hyp.send_body_waker); + data->hyp.send_body_waker = NULL; } } else { /* >= 4xx */ - k->exp100 = EXP100_FAILED; + Curl_req_abort_sending(data); } } if(data->state.hconnect && (data->req.httpcode/100 != 2) && @@ -353,20 +352,9 @@ CURLcode Curl_hyper_stream(struct Curl_easy *data, struct SingleRequest *k = &data->req; (void)conn; - if(k->exp100 > EXP100_SEND_DATA) { - struct curltime now = Curl_now(); - timediff_t ms = Curl_timediff(now, k->start100); - if(ms >= data->set.expect_100_timeout) { - /* we've waited long enough, continue anyway */ - k->exp100 = EXP100_SEND_DATA; - k->keepon |= KEEP_SEND; - Curl_expire_done(data, EXPIRE_100_TIMEOUT); - infof(data, "Done waiting for 100-continue after %ldms", (long)ms); - if(data->hyp.exp100_waker) { - hyper_waker_wake(data->hyp.exp100_waker); - data->hyp.exp100_waker = NULL; - } - } + if(data->hyp.send_body_waker) { + hyper_waker_wake(data->hyp.send_body_waker); + data->hyp.send_body_waker = NULL; } if(select_res & CURL_CSELECT_IN) { @@ -461,7 +449,7 @@ CURLcode Curl_hyper_stream(struct Curl_easy *data, reasonp = hyper_response_reason_phrase(resp); reason_len = hyper_response_reason_phrase_len(resp); - if(http_status == 417 && data->state.expect100header) { + if(http_status == 417 && Curl_http_exp100_is_selected(data)) { infof(data, "Got 417 while waiting for a 100"); data->state.disableexpect = TRUE; data->req.newurl = strdup(data->state.url); @@ -665,17 +653,6 @@ static int uploadstreamed(void *userdata, hyper_context *ctx, int rc = HYPER_POLL_ERROR; (void)ctx; - if(data->req.exp100 > EXP100_SEND_DATA) { - if(data->req.exp100 == EXP100_FAILED) - return HYPER_POLL_ERROR; - - /* still waiting confirmation */ - if(data->hyp.exp100_waker) - hyper_waker_free(data->hyp.exp100_waker); - data->hyp.exp100_waker = hyper_context_waker(ctx); - return HYPER_POLL_PENDING; - } - result = Curl_multi_xfer_ulbuf_borrow(data, &xfer_ulbuf, &xfer_ulblen); if(result) goto out; @@ -974,11 +951,6 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) goto error; } } - else { - if(!data->state.disableexpect) { - data->state.expect100header = TRUE; - } - } if(hyper_request_set_method(req, (uint8_t *)method, strlen(method))) { failf(data, "error setting method"); @@ -1158,13 +1130,10 @@ CURLcode Curl_http(struct Curl_easy *data, bool *done) if((httpreq == HTTPREQ_GET) || (httpreq == HTTPREQ_HEAD)) { /* HTTP GET/HEAD download */ Curl_pgrsSetUploadSize(data, 0); /* nothing */ - Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, -1); } + + Curl_xfer_setup(data, FIRSTSOCKET, -1, TRUE, FIRSTSOCKET); conn->datastream = Curl_hyper_stream; - if(data->state.expect100header) - /* Timeout count starts now since with Hyper we don't know exactly when - the full request has been sent. */ - data->req.start100 = Curl_now(); /* clear userpwd and proxyuserpwd to avoid reusing old credentials * from reused connections */ @@ -1206,10 +1175,6 @@ void Curl_hyper_done(struct Curl_easy *data) hyper_waker_free(h->write_waker); h->write_waker = NULL; } - if(h->exp100_waker) { - hyper_waker_free(h->exp100_waker); - h->exp100_waker = NULL; - } if(h->send_body_waker) { hyper_waker_free(h->send_body_waker); h->send_body_waker = NULL; @@ -1238,6 +1203,7 @@ static const struct Curl_crtype cr_hyper_protocol = { Curl_creader_def_resume_from, Curl_creader_def_rewind, cr_hyper_unpause, + Curl_creader_def_done, sizeof(struct Curl_creader) }; diff --git a/lib/c-hyper.h b/lib/c-hyper.h index a592abf91e2..89dd53b8fdb 100644 --- a/lib/c-hyper.h +++ b/lib/c-hyper.h @@ -39,7 +39,6 @@ struct hyptransfer { hyper_waker *write_waker; hyper_waker *read_waker; const hyper_executor *exec; - hyper_waker *exp100_waker; hyper_waker *send_body_waker; struct hyp_io_ctx io_ctx; }; diff --git a/lib/http.c b/lib/http.c index 1d741fbd8d2..43bc2fc96e7 100644 --- a/lib/http.c +++ b/lib/http.c @@ -102,6 +102,9 @@ */ static bool http_should_fail(struct Curl_easy *data); +static bool http_exp100_is_waiting(struct Curl_easy *data); +static CURLcode http_exp100_add_reader(struct Curl_easy *data); +static void http_exp100_send_anyway(struct Curl_easy *data); /* * HTTP handler interface. @@ -1275,31 +1278,6 @@ static const char *get_http_string(const struct Curl_easy *data, } #endif -/* check and possibly add an Expect: header */ -static CURLcode expect100(struct Curl_easy *data, struct dynbuf *req) -{ - CURLcode result = CURLE_OK; - if(!data->state.disableexpect && - Curl_use_http_1_1plus(data, data->conn) && - (data->conn->httpversion < 20)) { - /* if not doing HTTP 1.0 or version 2, or disabled explicitly, we add an - Expect: 100-continue to the headers which actually speeds up post - operations (as there is one packet coming back from the web server) */ - const char *ptr = Curl_checkheaders(data, STRCONST("Expect")); - if(ptr) { - data->state.expect100header = - Curl_compareheader(ptr, STRCONST("Expect:"), STRCONST("100-continue")); - } - else { - result = Curl_dyn_addn(req, STRCONST("Expect: 100-continue\r\n")); - if(!result) - data->state.expect100header = TRUE; - } - } - - return result; -} - enum proxy_use { HEADER_SERVER, /* direct to server */ HEADER_PROXY, /* regular request to proxy */ @@ -2164,26 +2142,39 @@ CURLcode Curl_http_req_set_reader(struct Curl_easy *data, return result; } -static CURLcode addexpect(struct Curl_easy *data, struct dynbuf *r) +static CURLcode addexpect(struct Curl_easy *data, struct dynbuf *r, + bool *announced_exp100) { - data->state.expect100header = FALSE; + CURLcode result; + char *ptr; + + *announced_exp100 = FALSE; /* Avoid Expect: 100-continue if Upgrade: is used */ - if(data->req.upgr101 == UPGR101_INIT) { - /* For really small puts we don't use Expect: headers at all, and for - the somewhat bigger ones we allow the app to disable it. Just make - sure that the expect100header is always set to the preferred value - here. */ - char *ptr = Curl_checkheaders(data, STRCONST("Expect")); - if(ptr) { - data->state.expect100header = - Curl_compareheader(ptr, STRCONST("Expect:"), - STRCONST("100-continue")); + if(data->req.upgr101 != UPGR101_INIT) + return CURLE_OK; + + /* For really small puts we don't use Expect: headers at all, and for + the somewhat bigger ones we allow the app to disable it. Just make + sure that the expect100header is always set to the preferred value + here. */ + ptr = Curl_checkheaders(data, STRCONST("Expect")); + if(ptr) { + *announced_exp100 = + Curl_compareheader(ptr, STRCONST("Expect:"), STRCONST("100-continue")); + } + else if(!data->state.disableexpect && + Curl_use_http_1_1plus(data, data->conn) && + (data->conn->httpversion < 20)) { + /* if not doing HTTP 1.0 or version 2, or disabled explicitly, we add an + Expect: 100-continue to the headers which actually speeds up post + operations (as there is one packet coming back from the web server) */ + curl_off_t client_len = Curl_creader_client_length(data); + if(client_len > EXPECT_100_THRESHOLD || client_len < 0) { + result = Curl_dyn_addn(r, STRCONST("Expect: 100-continue\r\n")); + if(result) + return result; + *announced_exp100 = TRUE; } - else { - curl_off_t client_len = Curl_creader_client_length(data); - if(client_len > EXPECT_100_THRESHOLD || client_len < 0) - return expect100(data, r); - } } return CURLE_OK; } @@ -2193,6 +2184,7 @@ CURLcode Curl_http_req_complete(struct Curl_easy *data, { CURLcode result = CURLE_OK; curl_off_t req_clen; + bool announced_exp100 = FALSE; DEBUGASSERT(data->conn); #ifndef USE_HYPER @@ -2251,7 +2243,7 @@ CURLcode Curl_http_req_complete(struct Curl_easy *data, goto out; } } - result = addexpect(data, r); + result = addexpect(data, r, &announced_exp100); if(result) goto out; break; @@ -2262,6 +2254,8 @@ CURLcode Curl_http_req_complete(struct Curl_easy *data, /* end of headers */ result = Curl_dyn_addn(r, STRCONST("\r\n")); Curl_pgrsSetUploadSize(data, req_clen); + if(announced_exp100) + result = http_exp100_add_reader(data); out: if(!result) { @@ -3434,11 +3428,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, k->headerline = 0; /* restart the header line counter */ /* if we did wait for this do enable write now! */ - if(k->exp100 > EXP100_SEND_DATA) { - k->exp100 = EXP100_SEND_DATA; - k->keepon |= KEEP_SEND; - Curl_expire_done(data, EXPIRE_100_TIMEOUT); - } + Curl_http_exp100_got100(data); break; case 101: if(conn->httpversion == 11) { @@ -3617,13 +3607,11 @@ static CURLcode http_rw_headers(struct Curl_easy *data, * request body has been sent we stop sending and mark the * connection for closure after we've read the entire response. */ - Curl_expire_done(data, EXPIRE_100_TIMEOUT); if(!Curl_req_done_sending(data)) { - if((k->httpcode == 417) && data->state.expect100header) { + if((k->httpcode == 417) && Curl_http_exp100_is_selected(data)) { /* 417 Expectation Failed - try again without the Expect header */ - if(!k->writebytecount && - k->exp100 == EXP100_AWAITING_CONTINUE) { + if(!k->writebytecount && http_exp100_is_waiting(data)) { infof(data, "Got HTTP failure 417 while waiting for a 100"); } else { @@ -3641,10 +3629,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, } else if(data->set.http_keep_sending_on_error) { infof(data, "HTTP error before end of send, keep sending"); - if(k->exp100 > EXP100_SEND_DATA) { - k->exp100 = EXP100_SEND_DATA; - k->keepon |= KEEP_SEND; - } + http_exp100_send_anyway(data); } else { infof(data, "HTTP error before end of send, stop sending"); @@ -3652,8 +3637,6 @@ static CURLcode http_rw_headers(struct Curl_easy *data, result = Curl_req_abort_sending(data); if(result) return result; - if(data->state.expect100header) - k->exp100 = EXP100_FAILED; } } break; @@ -4337,4 +4320,142 @@ void Curl_http_resp_free(struct http_resp *resp) } } +struct cr_exp100_ctx { + struct Curl_creader super; + struct curltime start; /* time started waiting */ + enum expect100 state; +}; + +/* Expect: 100-continue client reader, blocking uploads */ + +static void http_exp100_continue(struct Curl_easy *data, + struct Curl_creader *reader) +{ + struct cr_exp100_ctx *ctx = reader->ctx; + if(ctx->state > EXP100_SEND_DATA) { + ctx->state = EXP100_SEND_DATA; + data->req.keepon |= KEEP_SEND; + data->req.keepon &= ~KEEP_SEND_TIMED; + Curl_expire_done(data, EXPIRE_100_TIMEOUT); + } +} + +static CURLcode cr_exp100_read(struct Curl_easy *data, + struct Curl_creader *reader, + char *buf, size_t blen, + size_t *nread, bool *eos) +{ + struct cr_exp100_ctx *ctx = reader->ctx; + timediff_t ms; + + switch(ctx->state) { + case EXP100_SENDING_REQUEST: + /* We are now waiting for a reply from the server or + * a timeout on our side */ + DEBUGF(infof(data, "cr_exp100_read, start AWAITING_CONTINUE")); + ctx->state = EXP100_AWAITING_CONTINUE; + ctx->start = Curl_now(); + Curl_expire(data, data->set.expect_100_timeout, EXPIRE_100_TIMEOUT); + data->req.keepon &= ~KEEP_SEND; + data->req.keepon |= KEEP_SEND_TIMED; + *nread = 0; + *eos = FALSE; + return CURLE_OK; + case EXP100_FAILED: + DEBUGF(infof(data, "cr_exp100_read, expectation failed, error")); + *nread = 0; + *eos = FALSE; + return CURLE_READ_ERROR; + case EXP100_AWAITING_CONTINUE: + ms = Curl_timediff(Curl_now(), ctx->start); + if(ms < data->set.expect_100_timeout) { + DEBUGF(infof(data, "cr_exp100_read, AWAITING_CONTINUE, not expired")); + data->req.keepon &= ~KEEP_SEND; + data->req.keepon |= KEEP_SEND_TIMED; + *nread = 0; + *eos = FALSE; + return CURLE_OK; + } + /* we've waited long enough, continue anyway */ + http_exp100_continue(data, reader); + infof(data, "Done waiting for 100-continue"); + FALLTHROUGH(); + default: + DEBUGF(infof(data, "cr_exp100_read, pass through")); + return Curl_creader_read(data, reader->next, buf, blen, nread, eos); + } +} + +static void cr_exp100_done(struct Curl_easy *data, + struct Curl_creader *reader, int premature) +{ + struct cr_exp100_ctx *ctx = reader->ctx; + ctx->state = premature? EXP100_FAILED : EXP100_SEND_DATA; + data->req.keepon &= ~KEEP_SEND_TIMED; + Curl_expire_done(data, EXPIRE_100_TIMEOUT); +} + +static const struct Curl_crtype cr_exp100 = { + "cr-exp100", + Curl_creader_def_init, + cr_exp100_read, + Curl_creader_def_close, + Curl_creader_def_needs_rewind, + Curl_creader_def_total_length, + Curl_creader_def_resume_from, + Curl_creader_def_rewind, + Curl_creader_def_unpause, + cr_exp100_done, + sizeof(struct cr_exp100_ctx) +}; + +static CURLcode http_exp100_add_reader(struct Curl_easy *data) +{ + struct Curl_creader *reader = NULL; + CURLcode result; + + result = Curl_creader_create(&reader, data, &cr_exp100, + CURL_CR_PROTOCOL); + if(!result) + result = Curl_creader_add(data, reader); + if(!result) { + struct cr_exp100_ctx *ctx = reader->ctx; + ctx->state = EXP100_SENDING_REQUEST; + } + + if(result && reader) + Curl_creader_free(data, reader); + return result; +} + +void Curl_http_exp100_got100(struct Curl_easy *data) +{ + struct Curl_creader *r = Curl_creader_get_by_type(data, &cr_exp100); + if(r) + http_exp100_continue(data, r); +} + +static bool http_exp100_is_waiting(struct Curl_easy *data) +{ + struct Curl_creader *r = Curl_creader_get_by_type(data, &cr_exp100); + if(r) { + struct cr_exp100_ctx *ctx = r->ctx; + return (ctx->state == EXP100_AWAITING_CONTINUE); + } + return FALSE; +} + +static void http_exp100_send_anyway(struct Curl_easy *data) +{ + struct Curl_creader *r = Curl_creader_get_by_type(data, &cr_exp100); + if(r) + http_exp100_continue(data, r); +} + +bool Curl_http_exp100_is_selected(struct Curl_easy *data) +{ + struct Curl_creader *r = Curl_creader_get_by_type(data, &cr_exp100); + return r? TRUE : FALSE; +} + #endif /* CURL_DISABLE_HTTP */ diff --git a/lib/http.h b/lib/http.h index 7ff61f5e57b..63f104971ef 100644 --- a/lib/http.h +++ b/lib/http.h @@ -176,6 +176,9 @@ CURLcode Curl_http_auth_act(struct Curl_easy *data); version. This count includes CONNECT response headers. */ #define MAX_HTTP_RESP_HEADER_SIZE (300*1024) +bool Curl_http_exp100_is_selected(struct Curl_easy *data); +void Curl_http_exp100_got100(struct Curl_easy *data); + #endif /* CURL_DISABLE_HTTP */ /**************************************************************************** diff --git a/lib/http_chunks.c b/lib/http_chunks.c index cfbd40bc286..ac9d72470b9 100644 --- a/lib/http_chunks.c +++ b/lib/http_chunks.c @@ -644,6 +644,7 @@ const struct Curl_crtype Curl_httpchunk_encoder = { Curl_creader_def_resume_from, Curl_creader_def_rewind, Curl_creader_def_unpause, + Curl_creader_def_done, sizeof(struct chunked_reader) }; diff --git a/lib/mime.c b/lib/mime.c index 48a1ad87c7a..5bc6d389314 100644 --- a/lib/mime.c +++ b/lib/mime.c @@ -2106,6 +2106,7 @@ static const struct Curl_crtype cr_mime = { cr_mime_resume_from, cr_mime_rewind, cr_mime_unpause, + Curl_creader_def_done, sizeof(struct cr_mime_ctx) }; diff --git a/lib/request.c b/lib/request.c index 2a92630d67d..e62f58868c2 100644 --- a/lib/request.c +++ b/lib/request.c @@ -134,8 +134,6 @@ void Curl_req_hard_reset(struct SingleRequest *req, struct Curl_easy *data) req->offset = 0; req->httpcode = 0; req->keepon = 0; - req->start100 = t0; - req->exp100 = EXP100_SEND_DATA; req->upgr101 = UPGR101_INIT; req->timeofdoc = 0; req->bodywrites = 0; @@ -241,16 +239,6 @@ static CURLcode req_send_buffer_flush(struct Curl_easy *data) Curl_bufq_skip(&data->req.sendbuf, nwritten); if(hds_len) { data->req.sendbuf_hds_len -= CURLMIN(hds_len, nwritten); - if(!data->req.sendbuf_hds_len) { - /* all request headers sent */ - if(data->req.exp100 == EXP100_SENDING_REQUEST) { - /* We are now waiting for a reply from the server or - * a timeout on our side */ - data->req.exp100 = EXP100_AWAITING_CONTINUE; - data->req.start100 = Curl_now(); - Curl_expire(data, data->set.expect_100_timeout, EXPIRE_100_TIMEOUT); - } - } } /* leave if we could not send all. Maybe network blocking or * speed limits on transfer */ @@ -264,11 +252,9 @@ static CURLcode req_set_upload_done(struct Curl_easy *data) { DEBUGASSERT(!data->req.upload_done); data->req.upload_done = TRUE; - data->req.keepon &= ~KEEP_SEND; /* we're done sending */ + data->req.keepon &= ~(KEEP_SEND|KEEP_SEND_TIMED); /* we're done sending */ - /* FIXME: http specific stuff, need to go somewhere else */ - data->req.exp100 = EXP100_SEND_DATA; - Curl_expire_done(data, EXPIRE_100_TIMEOUT); + Curl_creader_done(data, data->req.upload_aborted); if(data->req.upload_aborted) { if(data->req.writebytecount) @@ -384,10 +370,8 @@ CURLcode Curl_req_send_more(struct Curl_easy *data) { CURLcode result; - /* Fill our send buffer if more from client can be read and - * we are not in a "expect-100" situation. */ - if(!data->req.eos_read && !Curl_bufq_is_full(&data->req.sendbuf) && - (data->req.exp100 == EXP100_SEND_DATA)) { + /* Fill our send buffer if more from client can be read. */ + if(!data->req.eos_read && !Curl_bufq_is_full(&data->req.sendbuf)) { ssize_t nread = Curl_bufq_sipn(&data->req.sendbuf, 0, add_from_client, data, &result); if(nread < 0 && result != CURLE_AGAIN) diff --git a/lib/request.h b/lib/request.h index 3b2462ee740..2513c2dfc19 100644 --- a/lib/request.h +++ b/lib/request.h @@ -81,8 +81,6 @@ struct SingleRequest { int httpcode; /* error code from the 'HTTP/1.? XXX' or 'RTSP/1.? XXX' line */ int keepon; - struct curltime start100; /* time stamp to wait for the 100 code from */ - enum expect100 exp100; /* expect 100 continue state */ enum upgrade101 upgr101; /* 101 upgrade state */ /* Client Writer stack, handles transfer- and content-encodings, protocol diff --git a/lib/rtsp.c b/lib/rtsp.c index d8545bfc9c6..98468517a1a 100644 --- a/lib/rtsp.c +++ b/lib/rtsp.c @@ -555,8 +555,6 @@ static CURLcode rtsp_do(struct Curl_easy *data, bool *done) goto out; } } - - data->state.expect100header = FALSE; /* RTSP posts are simple/small */ } else if(rtspreq == RTSPREQ_GET_PARAMETER) { /* Check for an empty GET_PARAMETER (heartbeat) request */ diff --git a/lib/sendf.c b/lib/sendf.c index 9610f70dad3..790195719ea 100644 --- a/lib/sendf.c +++ b/lib/sendf.c @@ -579,6 +579,14 @@ CURLcode Curl_creader_def_unpause(struct Curl_easy *data, return CURLE_OK; } +void Curl_creader_def_done(struct Curl_easy *data, + struct Curl_creader *reader, int premature) +{ + (void)data; + (void)reader; + (void)premature; +} + struct cr_in_ctx { struct Curl_creader super; curl_read_callback read_cb; @@ -840,6 +848,7 @@ static const struct Curl_crtype cr_in = { cr_in_resume_from, cr_in_rewind, Curl_creader_def_unpause, + Curl_creader_def_done, sizeof(struct cr_in_ctx) }; @@ -990,6 +999,7 @@ static const struct Curl_crtype cr_lc = { Curl_creader_def_resume_from, Curl_creader_def_rewind, Curl_creader_def_unpause, + Curl_creader_def_done, sizeof(struct cr_lc_ctx) }; @@ -1154,6 +1164,7 @@ static const struct Curl_crtype cr_null = { Curl_creader_def_resume_from, Curl_creader_def_rewind, Curl_creader_def_unpause, + Curl_creader_def_done, sizeof(struct Curl_creader) }; @@ -1250,6 +1261,7 @@ static const struct Curl_crtype cr_buf = { cr_buf_resume_from, Curl_creader_def_rewind, Curl_creader_def_unpause, + Curl_creader_def_done, sizeof(struct cr_buf_ctx) }; @@ -1307,3 +1319,24 @@ CURLcode Curl_creader_unpause(struct Curl_easy *data) } return result; } + +void Curl_creader_done(struct Curl_easy *data, int premature) +{ + struct Curl_creader *reader = data->req.reader_stack; + while(reader) { + reader->crt->done(data, reader, premature); + reader = reader->next; + } +} + +struct Curl_creader *Curl_creader_get_by_type(struct Curl_easy *data, + const struct Curl_crtype *crt) +{ + struct Curl_creader *r; + for(r = data->req.reader_stack; r; r = r->next) { + if(r->crt == crt) + return r; + } + return NULL; + +} diff --git a/lib/sendf.h b/lib/sendf.h index 1bcbb3fd01e..d736ce44add 100644 --- a/lib/sendf.h +++ b/lib/sendf.h @@ -208,6 +208,8 @@ struct Curl_crtype { struct Curl_creader *reader, curl_off_t offset); CURLcode (*rewind)(struct Curl_easy *data, struct Curl_creader *reader); CURLcode (*unpause)(struct Curl_easy *data, struct Curl_creader *reader); + void (*done)(struct Curl_easy *data, + struct Curl_creader *reader, int premature); size_t creader_size; /* sizeof() allocated struct Curl_creader */ }; @@ -256,6 +258,8 @@ CURLcode Curl_creader_def_rewind(struct Curl_easy *data, struct Curl_creader *reader); CURLcode Curl_creader_def_unpause(struct Curl_easy *data, struct Curl_creader *reader); +void Curl_creader_def_done(struct Curl_easy *data, + struct Curl_creader *reader, int premature); /** * Convenience method for calling `reader->do_read()` that @@ -361,6 +365,19 @@ CURLcode Curl_creader_resume_from(struct Curl_easy *data, curl_off_t offset); */ CURLcode Curl_creader_unpause(struct Curl_easy *data); +/** + * Tell all client readers that they are done. + */ +void Curl_creader_done(struct Curl_easy *data, int premature); + +/** + * Look up an installed client reader on `data` by its type. + * @return first reader with that type or NULL + */ +struct Curl_creader *Curl_creader_get_by_type(struct Curl_easy *data, + const struct Curl_crtype *crt); + + /** * Set the client reader to provide 0 bytes, immediate EOS. */ diff --git a/lib/smtp.c b/lib/smtp.c index b32ef36e4b3..20763c0c823 100644 --- a/lib/smtp.c +++ b/lib/smtp.c @@ -1923,6 +1923,7 @@ static const struct Curl_crtype cr_eob = { Curl_creader_def_resume_from, Curl_creader_def_rewind, Curl_creader_def_unpause, + Curl_creader_def_done, sizeof(struct cr_eob_ctx) }; diff --git a/lib/transfer.c b/lib/transfer.c index ffe7adfc19f..e31d1d6db83 100644 --- a/lib/transfer.c +++ b/lib/transfer.c @@ -463,7 +463,8 @@ CURLcode Curl_readwrite(struct Curl_easy *data) } /* If we still have writing to do, we check if we have a writable socket. */ - if((k->keepon & KEEP_SEND) && (select_bits & CURL_CSELECT_OUT)) { + if(((k->keepon & KEEP_SEND) && (select_bits & CURL_CSELECT_OUT)) || + (k->keepon & KEEP_SEND_TIMED)) { /* write */ result = readwrite_upload(data, &didwhat); @@ -476,31 +477,6 @@ CURLcode Curl_readwrite(struct Curl_easy *data) now = Curl_now(); if(!didwhat) { - /* no read no write, this is a timeout? */ - if(k->exp100 == EXP100_AWAITING_CONTINUE) { - /* This should allow some time for the header to arrive, but only a - very short time as otherwise it'll be too much wasted time too - often. */ - - /* Quoting RFC2616, section "8.2.3 Use of the 100 (Continue) Status": - - Therefore, when a client sends this header field to an origin server - (possibly via a proxy) from which it has never seen a 100 (Continue) - status, the client SHOULD NOT wait for an indefinite period before - sending the request body. - - */ - - timediff_t ms = Curl_timediff(now, k->start100); - if(ms >= data->set.expect_100_timeout) { - /* we've waited long enough, continue anyway */ - k->exp100 = EXP100_SEND_DATA; - k->keepon |= KEEP_SEND; - Curl_expire_done(data, EXPIRE_100_TIMEOUT); - infof(data, "Done waiting for 100-continue"); - } - } - result = Curl_conn_ev_data_idle(data); if(result) goto out; @@ -1172,36 +1148,8 @@ void Curl_xfer_setup( if(sockindex != -1) k->keepon |= KEEP_RECV; - if(writesockindex != -1) { - /* HTTP 1.1 magic: - - Even if we require a 100-return code before uploading data, we might - need to write data before that since the REQUEST may not have been - finished sent off just yet. - - Thus, we must check if the request has been sent before we set the - state info where we wait for the 100-return code - */ - if((data->state.expect100header) && - (conn->handler->protocol&PROTO_FAMILY_HTTP)) { - /* wait with write until we either got 100-continue or a timeout */ - k->exp100 = EXP100_AWAITING_CONTINUE; - k->start100 = Curl_now(); - - /* Set a timeout for the multi interface. Add the inaccuracy margin so - that we don't fire slightly too early and get denied to run. */ - Curl_expire(data, data->set.expect_100_timeout, EXPIRE_100_TIMEOUT); - } - else { - if(data->state.expect100header) - /* when we've sent off the rest of the headers, we must await a - 100-continue but first finish sending the request */ - k->exp100 = EXP100_SENDING_REQUEST; - - /* enable the write bit when we're not waiting for continue */ - k->keepon |= KEEP_SEND; - } - } /* if(writesockindex != -1) */ + if(writesockindex != -1) + k->keepon |= KEEP_SEND; } /* if(k->getheader || !data->req.no_body) */ } diff --git a/lib/url.c b/lib/url.c index 5eefd2a8717..224b9f3e2ba 100644 --- a/lib/url.c +++ b/lib/url.c @@ -3898,7 +3898,6 @@ CURLcode Curl_init_do(struct Curl_easy *data, struct connectdata *conn) } data->state.done = FALSE; /* *_done() is not called yet */ - data->state.expect100header = FALSE; if(data->req.no_body) /* in HTTP lingo, no body means using the HEAD request... */ diff --git a/lib/urldata.h b/lib/urldata.h index 933a2e24700..ce28f25bba5 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -579,6 +579,14 @@ struct hostname { #define KEEP_RECV_PAUSE (1<<4) /* reading is paused */ #define KEEP_SEND_PAUSE (1<<5) /* writing is paused */ +/* KEEP_SEND_TIMED is set when the transfer should attempt sending + * at timer (or other) events. A transfer waiting on a timer will + * remove KEEP_SEND to suppress POLLOUTs of the connection. + * Adding KEEP_SEND_TIMED will then attempt to send whenever the transfer + * enters the "readwrite" loop, e.g. when a timer fires. + * This is used in HTTP for 'Expect: 100-continue' waiting. */ +#define KEEP_SEND_TIMED (1<<6) + #define KEEP_RECVBITS (KEEP_RECV | KEEP_RECV_HOLD | KEEP_RECV_PAUSE) #define KEEP_SENDBITS (KEEP_SEND | KEEP_SEND_HOLD | KEEP_SEND_PAUSE) @@ -1364,7 +1372,6 @@ struct UrlState { BIT(authproblem); /* TRUE if there's some problem authenticating */ /* set after initial USER failure, to prevent an authentication loop */ BIT(wildcardmatch); /* enable wildcard matching */ - BIT(expect100header); /* TRUE if we added Expect: 100-continue */ BIT(disableexpect); /* TRUE if Expect: is disabled due to a previous 417 response */ BIT(use_range); diff --git a/tests/http/test_07_upload.py b/tests/http/test_07_upload.py index 94534ffb199..d7ff1682b7d 100644 --- a/tests/http/test_07_upload.py +++ b/tests/http/test_07_upload.py @@ -46,6 +46,7 @@ def _class_scope(self, env, httpd, nghttpx): env.make_data_file(indir=env.gen_dir, fname="data-63k", fsize=63*1024) env.make_data_file(indir=env.gen_dir, fname="data-64k", fsize=64*1024) env.make_data_file(indir=env.gen_dir, fname="data-100k", fsize=100*1024) + env.make_data_file(indir=env.gen_dir, fname="data-1m+", fsize=(1024*1024)+1) env.make_data_file(indir=env.gen_dir, fname="data-10m", fsize=10*1024*1024) httpd.clear_extra_configs() httpd.reload() @@ -501,3 +502,29 @@ def test_07_51_echo_speed_limit(self, env: Env, httpd, nghttpx, proto, repeat): up_speed = r.stats[0]['speed_upload'] assert (speed_limit * 0.5) <= up_speed <= (speed_limit * 1.5), f'{r.stats[0]}' + # upload larger data, triggering "Expect: 100-continue" code paths + @pytest.mark.parametrize("proto", ['http/1.1']) + def test_07_60_upload_exp100(self, env: Env, httpd, nghttpx, repeat, proto): + fdata = os.path.join(env.gen_dir, 'data-1m+') + read_delay = 1 + curl = CurlClient(env=env) + url = f'https://{env.authority_for(env.domain1, proto)}/curltest/put?id=[0-0]'\ + f'&read_delay={read_delay}s' + r = curl.http_put(urls=[url], fdata=fdata, alpn_proto=proto, extra_args=[ + '--expect100-timeout', f'{read_delay+1}' + ]) + r.check_stats(count=1, http_status=200, exitcode=0) + + # upload larger data, triggering "Expect: 100-continue" code paths + @pytest.mark.parametrize("proto", ['http/1.1']) + def test_07_61_upload_exp100_timeout(self, env: Env, httpd, nghttpx, repeat, proto): + fdata = os.path.join(env.gen_dir, 'data-1m+') + read_delay = 2 + curl = CurlClient(env=env) + url = f'https://{env.authority_for(env.domain1, proto)}/curltest/put?id=[0-0]'\ + f'&read_delay={read_delay}s' + r = curl.http_put(urls=[url], fdata=fdata, alpn_proto=proto, extra_args=[ + '--expect100-timeout', f'{read_delay-1}' + ]) + r.check_stats(count=1, http_status=200, exitcode=0) + diff --git a/tests/http/testenv/mod_curltest/mod_curltest.c b/tests/http/testenv/mod_curltest/mod_curltest.c index a066be52228..4736fefdb79 100644 --- a/tests/http/testenv/mod_curltest/mod_curltest.c +++ b/tests/http/testenv/mod_curltest/mod_curltest.c @@ -425,7 +425,7 @@ static int curltest_put_handler(request_rec *r) apr_off_t rbody_len = 0; const char *s_rbody_len; const char *request_id = "none"; - apr_time_t chunk_delay = 0; + apr_time_t read_delay = 0, chunk_delay = 0; apr_array_header_t *args = NULL; long l; int i; @@ -450,6 +450,12 @@ static int curltest_put_handler(request_rec *r) request_id = val; continue; } + else if(!strcmp("read_delay", arg)) { + rv = duration_parse(&read_delay, val, "s"); + if(APR_SUCCESS == rv) { + continue; + } + } else if(!strcmp("chunk_delay", arg)) { rv = duration_parse(&chunk_delay, val, "s"); if(APR_SUCCESS == rv) { @@ -478,6 +484,9 @@ static int curltest_put_handler(request_rec *r) ct = apr_table_get(r->headers_in, "content-type"); ap_set_content_type(r, ct? ct : "text/plain"); + if(read_delay) { + apr_sleep(read_delay); + } bb = apr_brigade_create(r->pool, c->bucket_alloc); /* copy any request body into the response */ if((rv = ap_setup_client_block(r, REQUEST_CHUNKED_DECHUNK))) goto cleanup; From b6006381fb9f397b765e8fcd88b1d5764fac0612 Mon Sep 17 00:00:00 2001 From: Evgeny Grin Date: Fri, 15 Mar 2024 13:11:53 +0100 Subject: [PATCH 482/509] curl_sha512_256: work around a NetBSD bug Based on Michael Kaufmann analysis and suggestion Closes #13133 --- lib/curl_sha512_256.c | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/lib/curl_sha512_256.c b/lib/curl_sha512_256.c index 1dd07dbc6a3..8af3839c5f7 100644 --- a/lib/curl_sha512_256.c +++ b/lib/curl_sha512_256.c @@ -153,7 +153,17 @@ Curl_sha512_256_finish(unsigned char *digest, CURLcode ret; Curl_sha512_256_ctx *const ctx = (Curl_sha512_256_ctx *)context; +#ifdef __NetBSD__ + /* Use a larger buffer to work around a bug in NetBSD: + https://gnats.netbsd.org/cgi-bin/query-pr-single.pl?number=58039 */ + unsigned char tmp_digest[SHA512_256_DIGEST_SIZE * 2]; + ret = EVP_DigestFinal_ex(*ctx, + tmp_digest, NULL) ? CURLE_OK : CURLE_SSL_CIPHER; + if(ret == CURLE_OK) + memcpy(digest, tmp_digest, SHA512_256_DIGEST_SIZE); +#else /* ! __NetBSD__ */ ret = EVP_DigestFinal_ex(*ctx, digest, NULL) ? CURLE_OK : CURLE_SSL_CIPHER; +#endif /* ! __NetBSD__ */ EVP_MD_CTX_destroy(*ctx); *ctx = NULL; From 6bd4ca0ef6da6ed38db62ac34eab502e9a582264 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 18 Mar 2024 23:01:22 +0100 Subject: [PATCH 483/509] tool_getparam: accept a blank -w "" Added test 468 to verify. Regression from 07bcae89d5d00 (shipped in 8.6.0) Reported-by: Thomas Pyle Fixes #13144 Closes #13145 --- src/tool_getparam.c | 2 +- tests/data/Makefile.inc | 2 +- tests/data/test468 | 60 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 tests/data/test468 diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 52bb24959dd..c6a9c935861 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -2658,7 +2658,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ warnf(global, "Failed to read %s", fname); } else - err = getstr(&config->writeout, nextarg, DENY_BLANK); + err = getstr(&config->writeout, nextarg, ALLOW_BLANK); break; case C_PREPROXY: /* --preproxy */ err = getstr(&config->preproxy, nextarg, DENY_BLANK); diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc index 09675fd476d..2f74f1bb594 100644 --- a/tests/data/Makefile.inc +++ b/tests/data/Makefile.inc @@ -73,7 +73,7 @@ test426 test427 test428 test429 test430 test431 test432 test433 test434 \ test435 test436 test437 test438 test439 test440 test441 test442 test443 \ test444 test445 test446 test447 test448 test449 test450 test451 test452 \ test453 test454 test455 test456 test457 test458 test459 test460 test461 \ -test462 test463 test467 \ +test462 test463 test467 test468 \ \ test490 test491 test492 test493 test494 test495 test496 test497 test498 \ test499 test500 test501 test502 test503 test504 test505 test506 test507 \ diff --git a/tests/data/test468 b/tests/data/test468 new file mode 100644 index 00000000000..0b06a4d32ee --- /dev/null +++ b/tests/data/test468 @@ -0,0 +1,60 @@ + + + +HTTP +--write-out +--config + + + +# +# Server-side + + +HTTP/1.1 200 OK +Date: Tue, 09 Nov 2010 14:49:00 GMT +Server: test-server/fake +Last-Modified: Tue, 13 Jun 2000 12:10:00 GMT +ETag: "21025-dc7-39462498" +Accept-Ranges: bytes +Content-Length: 6 +Connection: close +Content-Type: text/html +Funny-head: yesyes + +-foo- + + + +# +# Client-side + + +http + + +set -w in config, then reset -w to blank on cmdline + + +-w "output\n" + + +http://%HOSTIP:%HTTPPORT/%TESTNUMBER -K %LOGDIR/cmd%TESTNUMBER -w "" + + + +# +# Verify data after the test has been "shot" + + +GET /%TESTNUMBER HTTP/1.1 +Host: %HOSTIP:%HTTPPORT +User-Agent: curl/%VERSION +Accept: */* + + + +-foo- + + + From 522ea5420f57f354396eabf1d7f3a4188d58a8ce Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 18 Mar 2024 12:46:43 +0100 Subject: [PATCH 484/509] http: improve response header handling, save cpu cycles Saving some cpu cycles in http response header processing: - pass the length of the header line along - use string constant sizeof() instead of strlen() - check line length if prefix is possible - switch on first header char to limit checks Closes #13143 --- lib/c-hyper.c | 2 +- lib/http.c | 641 ++++++++++++++++++++++++++------------------------ lib/http.h | 2 +- lib/http2.c | 35 ++- lib/request.c | 36 ++- 5 files changed, 388 insertions(+), 328 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index 78d4cd344c0..55a68e3706b 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -171,7 +171,7 @@ static int hyper_each_header(void *userdata, len = Curl_dyn_len(&data->state.headerb); headp = Curl_dyn_ptr(&data->state.headerb); - result = Curl_http_header(data, data->conn, headp); + result = Curl_http_header(data, data->conn, headp, len); if(result) { data->state.hresult = result; return HYPER_ITER_BREAK; diff --git a/lib/http.c b/lib/http.c index 43bc2fc96e7..cacebeacfbf 100644 --- a/lib/http.c +++ b/lib/http.c @@ -2824,325 +2824,368 @@ checkprotoprefix(struct Curl_easy *data, struct connectdata *conn, return checkhttpprefix(data, s, len); } +/* HTTP header has field name `n` (a string constant) */ +#define HD_IS(hd, hdlen, n) \ + (((hdlen) >= (sizeof(n)-1)) && curl_strnequal((n), (hd), (sizeof(n)-1))) + +#define HD_VAL(hd, hdlen, n) \ + ((((hdlen) >= (sizeof(n)-1)) && \ + curl_strnequal((n), (hd), (sizeof(n)-1)))? (hd + (sizeof(n)-1)) : NULL) + +/* HTTP header has field name `n` (a string constant) and contains `v` + * (a string constant) in its value(s) */ +#define HD_IS_AND_SAYS(hd, hdlen, n, v) \ + (HD_IS(hd, hdlen, n) && \ + ((hdlen) > ((sizeof(n)-1) + (sizeof(v)-1))) && \ + Curl_compareheader(hd, STRCONST(n), STRCONST(v))) + /* * Curl_http_header() parses a single response header. */ CURLcode Curl_http_header(struct Curl_easy *data, struct connectdata *conn, - char *headp) + char *hd, size_t hdlen) { CURLcode result; struct SingleRequest *k = &data->req; - /* Check for Content-Length: header lines to get size */ - if(!k->http_bodyless && - !data->set.ignorecl && checkprefix("Content-Length:", headp)) { - curl_off_t contentlength; - CURLofft offt = curlx_strtoofft(headp + strlen("Content-Length:"), - NULL, 10, &contentlength); - - if(offt == CURL_OFFT_OK) { - k->size = contentlength; - k->maxdownload = k->size; + const char *v; + + switch(hd[0]) { + case 'a': + case 'A': +#ifndef CURL_DISABLE_ALTSVC + v = (data->asi && + ((conn->handler->flags & PROTOPT_SSL) || +#ifdef CURLDEBUG + /* allow debug builds to circumvent the HTTPS restriction */ + getenv("CURL_ALTSVC_HTTP") +#else + 0 +#endif + ))? HD_VAL(hd, hdlen, "Alt-Svc:") : NULL; + if(v) { + /* the ALPN of the current request */ + enum alpnid id = (conn->httpversion == 30)? ALPN_h3 : + (conn->httpversion == 20) ? ALPN_h2 : ALPN_h1; + return Curl_altsvc_parse(data, data->asi, v, id, conn->host.name, + curlx_uitous((unsigned int)conn->remote_port)); } - else if(offt == CURL_OFFT_FLOW) { - /* out of range */ - if(data->set.max_filesize) { - failf(data, "Maximum file size exceeded"); - return CURLE_FILESIZE_EXCEEDED; +#endif + break; + case 'c': + case 'C': + /* Check for Content-Length: header lines to get size */ + v = (!k->http_bodyless && !data->set.ignorecl)? + HD_VAL(hd, hdlen, "Content-Length:") : NULL; + if(v) { + curl_off_t contentlength; + CURLofft offt = curlx_strtoofft(v, NULL, 10, &contentlength); + + if(offt == CURL_OFFT_OK) { + k->size = contentlength; + k->maxdownload = k->size; } - streamclose(conn, "overflow content-length"); - infof(data, "Overflow Content-Length: value"); + else if(offt == CURL_OFFT_FLOW) { + /* out of range */ + if(data->set.max_filesize) { + failf(data, "Maximum file size exceeded"); + return CURLE_FILESIZE_EXCEEDED; + } + streamclose(conn, "overflow content-length"); + infof(data, "Overflow Content-Length: value"); + } + else { + /* negative or just rubbish - bad HTTP */ + failf(data, "Invalid Content-Length: value"); + return CURLE_WEIRD_SERVER_REPLY; + } + return CURLE_OK; } - else { - /* negative or just rubbish - bad HTTP */ - failf(data, "Invalid Content-Length: value"); - return CURLE_WEIRD_SERVER_REPLY; + v = (!k->http_bodyless && data->set.str[STRING_ENCODING])? + HD_VAL(hd, hdlen, "Content-Encoding:") : NULL; + if(v) { + /* + * Process Content-Encoding. Look for the values: identity, + * gzip, deflate, compress, x-gzip and x-compress. x-gzip and + * x-compress are the same as gzip and compress. (Sec 3.5 RFC + * 2616). zlib cannot handle compress. However, errors are + * handled further down when the response body is processed + */ + return Curl_build_unencoding_stack(data, v, FALSE); } - } - /* check for Content-Type: header lines to get the MIME-type */ - else if(checkprefix("Content-Type:", headp)) { - char *contenttype = Curl_copy_header_value(headp); - if(!contenttype) - return CURLE_OUT_OF_MEMORY; - if(!*contenttype) - /* ignore empty data */ - free(contenttype); - else { - Curl_safefree(data->info.contenttype); - data->info.contenttype = contenttype; + /* check for Content-Type: header lines to get the MIME-type */ + v = HD_VAL(hd, hdlen, "Content-Type:"); + if(v) { + char *contenttype = Curl_copy_header_value(hd); + if(!contenttype) + return CURLE_OUT_OF_MEMORY; + if(!*contenttype) + /* ignore empty data */ + free(contenttype); + else { + Curl_safefree(data->info.contenttype); + data->info.contenttype = contenttype; + } + return CURLE_OK; } - } -#ifndef CURL_DISABLE_PROXY - else if((conn->httpversion == 10) && - conn->bits.httpproxy && - Curl_compareheader(headp, - STRCONST("Proxy-Connection:"), - STRCONST("keep-alive"))) { - /* - * When an HTTP/1.0 reply comes when using a proxy, the - * 'Proxy-Connection: keep-alive' line tells us the - * connection will be kept alive for our pleasure. - * Default action for 1.0 is to close. - */ - connkeep(conn, "Proxy-Connection keep-alive"); /* don't close */ - infof(data, "HTTP/1.0 proxy connection set to keep alive"); - } - else if((conn->httpversion == 11) && - conn->bits.httpproxy && - Curl_compareheader(headp, - STRCONST("Proxy-Connection:"), - STRCONST("close"))) { - /* - * We get an HTTP/1.1 response from a proxy and it says it'll - * close down after this transfer. - */ - connclose(conn, "Proxy-Connection: asked to close after done"); - infof(data, "HTTP/1.1 proxy connection set close"); - } -#endif - else if((conn->httpversion == 10) && - Curl_compareheader(headp, - STRCONST("Connection:"), - STRCONST("keep-alive"))) { - /* - * An HTTP/1.0 reply with the 'Connection: keep-alive' line - * tells us the connection will be kept alive for our - * pleasure. Default action for 1.0 is to close. - * - * [RFC2068, section 19.7.1] */ - connkeep(conn, "Connection keep-alive"); - infof(data, "HTTP/1.0 connection set to keep alive"); - } - else if(Curl_compareheader(headp, - STRCONST("Connection:"), STRCONST("close"))) { - /* - * [RFC 2616, section 8.1.2.1] - * "Connection: close" is HTTP/1.1 language and means that - * the connection will close when this request has been - * served. - */ - streamclose(conn, "Connection: close used"); - } - else if(!k->http_bodyless && checkprefix("Transfer-Encoding:", headp)) { - /* One or more encodings. We check for chunked and/or a compression - algorithm. */ - /* - * [RFC 2616, section 3.6.1] A 'chunked' transfer encoding - * means that the server will send a series of "chunks". Each - * chunk starts with line with info (including size of the - * coming block) (terminated with CRLF), then a block of data - * with the previously mentioned size. There can be any amount - * of chunks, and a chunk-data set to zero signals the - * end-of-chunks. */ - - result = Curl_build_unencoding_stack(data, - headp + strlen("Transfer-Encoding:"), - TRUE); - if(result) - return result; - if(!k->chunk && data->set.http_transfer_encoding) { - /* if this isn't chunked, only close can signal the end of this transfer - as Content-Length is said not to be trusted for transfer-encoding! */ - connclose(conn, "HTTP/1.1 transfer-encoding without chunks"); - k->ignore_cl = TRUE; + if(HD_IS_AND_SAYS(hd, hdlen, "Connection:", "close")) { + /* + * [RFC 2616, section 8.1.2.1] + * "Connection: close" is HTTP/1.1 language and means that + * the connection will close when this request has been + * served. + */ + streamclose(conn, "Connection: close used"); + return CURLE_OK; } - } - else if(!k->http_bodyless && checkprefix("Content-Encoding:", headp) && - data->set.str[STRING_ENCODING]) { - /* - * Process Content-Encoding. Look for the values: identity, - * gzip, deflate, compress, x-gzip and x-compress. x-gzip and - * x-compress are the same as gzip and compress. (Sec 3.5 RFC - * 2616). zlib cannot handle compress. However, errors are - * handled further down when the response body is processed - */ - result = Curl_build_unencoding_stack(data, - headp + strlen("Content-Encoding:"), - FALSE); - if(result) - return result; - } - else if(checkprefix("Retry-After:", headp)) { - /* Retry-After = HTTP-date / delay-seconds */ - curl_off_t retry_after = 0; /* zero for unknown or "now" */ - /* Try it as a decimal number, if it works it is not a date */ - (void)curlx_strtoofft(headp + strlen("Retry-After:"), - NULL, 10, &retry_after); - if(!retry_after) { - time_t date = Curl_getdate_capped(headp + strlen("Retry-After:")); - if(-1 != date) - /* convert date to number of seconds into the future */ - retry_after = date - time(NULL); + if((conn->httpversion == 10) && + HD_IS_AND_SAYS(hd, hdlen, "Connection:", "keep-alive")) { + /* + * An HTTP/1.0 reply with the 'Connection: keep-alive' line + * tells us the connection will be kept alive for our + * pleasure. Default action for 1.0 is to close. + * + * [RFC2068, section 19.7.1] */ + connkeep(conn, "Connection keep-alive"); + infof(data, "HTTP/1.0 connection set to keep alive"); + return CURLE_OK; } - data->info.retry_after = retry_after; /* store it */ - } - else if(!k->http_bodyless && checkprefix("Content-Range:", headp)) { - /* Content-Range: bytes [num]- - Content-Range: bytes: [num]- - Content-Range: [num]- - Content-Range: [asterisk]/[total] - - The second format was added since Sun's webserver - JavaWebServer/1.1.1 obviously sends the header this way! - The third added since some servers use that! - The fourth means the requested range was unsatisfied. - */ - - char *ptr = headp + strlen("Content-Range:"); - - /* Move forward until first digit or asterisk */ - while(*ptr && !ISDIGIT(*ptr) && *ptr != '*') - ptr++; - - /* if it truly stopped on a digit */ - if(ISDIGIT(*ptr)) { - if(!curlx_strtoofft(ptr, NULL, 10, &k->offset)) { - if(data->state.resume_from == k->offset) - /* we asked for a resume and we got it */ - k->content_range = TRUE; + v = !k->http_bodyless? HD_VAL(hd, hdlen, "Content-Range:") : NULL; + if(v) { + /* Content-Range: bytes [num]- + Content-Range: bytes: [num]- + Content-Range: [num]- + Content-Range: [asterisk]/[total] + + The second format was added since Sun's webserver + JavaWebServer/1.1.1 obviously sends the header this way! + The third added since some servers use that! + The fourth means the requested range was unsatisfied. + */ + + const char *ptr = v; + + /* Move forward until first digit or asterisk */ + while(*ptr && !ISDIGIT(*ptr) && *ptr != '*') + ptr++; + + /* if it truly stopped on a digit */ + if(ISDIGIT(*ptr)) { + if(!curlx_strtoofft(ptr, NULL, 10, &k->offset)) { + if(data->state.resume_from == k->offset) + /* we asked for a resume and we got it */ + k->content_range = TRUE; + } } + else if(k->httpcode < 300) + data->state.resume_from = 0; /* get everything */ } - else if(k->httpcode < 300) - data->state.resume_from = 0; /* get everything */ - } -#if !defined(CURL_DISABLE_COOKIES) - else if(data->cookies && data->state.cookie_engine && - checkprefix("Set-Cookie:", headp)) { - /* If there is a custom-set Host: name, use it here, or else use real peer - host name. */ - const char *host = data->state.aptr.cookiehost? - data->state.aptr.cookiehost:conn->host.name; - const bool secure_context = - conn->handler->protocol&(CURLPROTO_HTTPS|CURLPROTO_WSS) || - strcasecompare("localhost", host) || - !strcmp(host, "127.0.0.1") || - !strcmp(host, "::1") ? TRUE : FALSE; - - Curl_share_lock(data, CURL_LOCK_DATA_COOKIE, - CURL_LOCK_ACCESS_SINGLE); - Curl_cookie_add(data, data->cookies, TRUE, FALSE, - headp + strlen("Set-Cookie:"), host, - data->state.up.path, secure_context); - Curl_share_unlock(data, CURL_LOCK_DATA_COOKIE); - } -#endif - else if(!k->http_bodyless && checkprefix("Last-Modified:", headp) && - (data->set.timecondition || data->set.get_filetime) ) { - k->timeofdoc = Curl_getdate_capped(headp + strlen("Last-Modified:")); - if(data->set.get_filetime) - data->info.filetime = k->timeofdoc; - } - else if((checkprefix("WWW-Authenticate:", headp) && - (401 == k->httpcode)) || - (checkprefix("Proxy-authenticate:", headp) && - (407 == k->httpcode))) { - - bool proxy = (k->httpcode == 407) ? TRUE : FALSE; - char *auth = Curl_copy_header_value(headp); - if(!auth) - return CURLE_OUT_OF_MEMORY; + break; + case 'l': + case 'L': + v = (!k->http_bodyless && + (data->set.timecondition || data->set.get_filetime))? + HD_VAL(hd, hdlen, "Last-Modified:") : NULL; + if(v) { + k->timeofdoc = Curl_getdate_capped(v); + if(data->set.get_filetime) + data->info.filetime = k->timeofdoc; + return CURLE_OK; + } + if((k->httpcode >= 300 && k->httpcode < 400) && + HD_IS(hd, hdlen, "Location:") && + !data->req.location) { + /* this is the URL that the server advises us to use instead */ + char *location = Curl_copy_header_value(hd); + if(!location) + return CURLE_OUT_OF_MEMORY; + if(!*location) + /* ignore empty data */ + free(location); + else { + data->req.location = location; - result = Curl_http_input_auth(data, proxy, auth); + if(data->set.http_follow_location) { + DEBUGASSERT(!data->req.newurl); + data->req.newurl = strdup(data->req.location); /* clone */ + if(!data->req.newurl) + return CURLE_OUT_OF_MEMORY; - free(auth); + /* some cases of POST and PUT etc needs to rewind the data + stream at this point */ + result = http_perhapsrewind(data, conn); + if(result) + return result; - if(result) + /* mark the next request as a followed location: */ + data->state.this_is_a_follow = TRUE; + } + } + } + break; + case 'p': + case 'P': +#ifndef CURL_DISABLE_PROXY + v = HD_VAL(hd, hdlen, "Proxy-Connection:"); + if(v) { + if((conn->httpversion == 10) && conn->bits.httpproxy && + HD_IS_AND_SAYS(hd, hdlen, "Proxy-Connection:", "keep-alive")) { + /* + * When an HTTP/1.0 reply comes when using a proxy, the + * 'Proxy-Connection: keep-alive' line tells us the + * connection will be kept alive for our pleasure. + * Default action for 1.0 is to close. + */ + connkeep(conn, "Proxy-Connection keep-alive"); /* don't close */ + infof(data, "HTTP/1.0 proxy connection set to keep alive"); + } + else if((conn->httpversion == 11) && conn->bits.httpproxy && + HD_IS_AND_SAYS(hd, hdlen, "Proxy-Connection:", "close")) { + /* + * We get an HTTP/1.1 response from a proxy and it says it'll + * close down after this transfer. + */ + connclose(conn, "Proxy-Connection: asked to close after done"); + infof(data, "HTTP/1.1 proxy connection set close"); + } + return CURLE_OK; + } +#endif + if((407 == k->httpcode) && HD_IS(hd, hdlen, "Proxy-authenticate:")) { + char *auth = Curl_copy_header_value(hd); + if(!auth) + return CURLE_OUT_OF_MEMORY; + result = Curl_http_input_auth(data, TRUE, auth); + free(auth); return result; - } + } #ifdef USE_SPNEGO - else if(checkprefix("Persistent-Auth:", headp)) { - struct negotiatedata *negdata = &conn->negotiate; - struct auth *authp = &data->state.authhost; - if(authp->picked == CURLAUTH_NEGOTIATE) { - char *persistentauth = Curl_copy_header_value(headp); - if(!persistentauth) - return CURLE_OUT_OF_MEMORY; - negdata->noauthpersist = checkprefix("false", persistentauth)? - TRUE:FALSE; - negdata->havenoauthpersist = TRUE; - infof(data, "Negotiate: noauthpersist -> %d, header part: %s", - negdata->noauthpersist, persistentauth); - free(persistentauth); + if(HD_IS(hd, hdlen, "Persistent-Auth:")) { + struct negotiatedata *negdata = &conn->negotiate; + struct auth *authp = &data->state.authhost; + if(authp->picked == CURLAUTH_NEGOTIATE) { + char *persistentauth = Curl_copy_header_value(hd); + if(!persistentauth) + return CURLE_OUT_OF_MEMORY; + negdata->noauthpersist = checkprefix("false", persistentauth)? + TRUE:FALSE; + negdata->havenoauthpersist = TRUE; + infof(data, "Negotiate: noauthpersist -> %d, header part: %s", + negdata->noauthpersist, persistentauth); + free(persistentauth); + } } - } #endif - else if((k->httpcode >= 300 && k->httpcode < 400) && - checkprefix("Location:", headp) && - !data->req.location) { - /* this is the URL that the server advises us to use instead */ - char *location = Curl_copy_header_value(headp); - if(!location) - return CURLE_OUT_OF_MEMORY; - if(!*location) - /* ignore empty data */ - free(location); - else { - data->req.location = location; - - if(data->set.http_follow_location) { - DEBUGASSERT(!data->req.newurl); - data->req.newurl = strdup(data->req.location); /* clone */ - if(!data->req.newurl) - return CURLE_OUT_OF_MEMORY; - - /* some cases of POST and PUT etc needs to rewind the data - stream at this point */ - result = http_perhapsrewind(data, conn); - if(result) - return result; - - /* mark the next request as a followed location: */ - data->state.this_is_a_follow = TRUE; + break; + case 'r': + case 'R': + v = HD_VAL(hd, hdlen, "Retry-After:"); + if(v) { + /* Retry-After = HTTP-date / delay-seconds */ + curl_off_t retry_after = 0; /* zero for unknown or "now" */ + /* Try it as a decimal number, if it works it is not a date */ + (void)curlx_strtoofft(v, NULL, 10, &retry_after); + if(!retry_after) { + time_t date = Curl_getdate_capped(v); + if(-1 != date) + /* convert date to number of seconds into the future */ + retry_after = date - time(NULL); } + data->info.retry_after = retry_after; /* store it */ + return CURLE_OK; } - } + break; + case 's': + case 'S': +#if !defined(CURL_DISABLE_COOKIES) + v = (data->cookies && data->state.cookie_engine)? + HD_VAL(hd, hdlen, "Set-Cookie:") : NULL; + if(v) { + /* If there is a custom-set Host: name, use it here, or else use + * real peer host name. */ + const char *host = data->state.aptr.cookiehost? + data->state.aptr.cookiehost:conn->host.name; + const bool secure_context = + conn->handler->protocol&(CURLPROTO_HTTPS|CURLPROTO_WSS) || + strcasecompare("localhost", host) || + !strcmp(host, "127.0.0.1") || + !strcmp(host, "::1") ? TRUE : FALSE; + Curl_share_lock(data, CURL_LOCK_DATA_COOKIE, + CURL_LOCK_ACCESS_SINGLE); + Curl_cookie_add(data, data->cookies, TRUE, FALSE, v, host, + data->state.up.path, secure_context); + Curl_share_unlock(data, CURL_LOCK_DATA_COOKIE); + return CURLE_OK; + } +#endif #ifndef CURL_DISABLE_HSTS - /* If enabled, the header is incoming and this is over HTTPS */ - else if(data->hsts && checkprefix("Strict-Transport-Security:", headp) && - ((conn->handler->flags & PROTOPT_SSL) || + /* If enabled, the header is incoming and this is over HTTPS */ + v = (data->hsts && + ((conn->handler->flags & PROTOPT_SSL) || #ifdef CURLDEBUG /* allow debug builds to circumvent the HTTPS restriction */ getenv("CURL_HSTS_HTTP") #else 0 #endif - )) { - CURLcode check = - Curl_hsts_parse(data->hsts, conn->host.name, - headp + strlen("Strict-Transport-Security:")); - if(check) - infof(data, "Illegal STS header skipped"); + ) + )? HD_VAL(hd, hdlen, "Strict-Transport-Security:") : NULL; + if(v) { + CURLcode check = + Curl_hsts_parse(data->hsts, conn->host.name, v); + if(check) + infof(data, "Illegal STS header skipped"); #ifdef DEBUGBUILD - else - infof(data, "Parsed STS header fine (%zu entries)", - data->hsts->list.size); -#endif - } + else + infof(data, "Parsed STS header fine (%zu entries)", + data->hsts->list.size); #endif -#ifndef CURL_DISABLE_ALTSVC - /* If enabled, the header is incoming and this is over HTTPS */ - else if(data->asi && checkprefix("Alt-Svc:", headp) && - ((conn->handler->flags & PROTOPT_SSL) || -#ifdef CURLDEBUG - /* allow debug builds to circumvent the HTTPS restriction */ - getenv("CURL_ALTSVC_HTTP") -#else - 0 + } #endif - )) { - /* the ALPN of the current request */ - enum alpnid id = (conn->httpversion == 30)? ALPN_h3 : - (conn->httpversion == 20) ? ALPN_h2 : ALPN_h1; - result = Curl_altsvc_parse(data, data->asi, - headp + strlen("Alt-Svc:"), - id, conn->host.name, - curlx_uitous((unsigned int)conn->remote_port)); - if(result) + break; + case 't': + case 'T': + v = !k->http_bodyless? HD_VAL(hd, hdlen, "Transfer-Encoding:") : NULL; + if(v) { + /* One or more encodings. We check for chunked and/or a compression + algorithm. */ + /* + * [RFC 2616, section 3.6.1] A 'chunked' transfer encoding + * means that the server will send a series of "chunks". Each + * chunk starts with line with info (including size of the + * coming block) (terminated with CRLF), then a block of data + * with the previously mentioned size. There can be any amount + * of chunks, and a chunk-data set to zero signals the + * end-of-chunks. */ + + result = Curl_build_unencoding_stack(data, v, TRUE); + if(result) + return result; + if(!k->chunk && data->set.http_transfer_encoding) { + /* if this isn't chunked, only close can signal the end of this + * transfer as Content-Length is said not to be trusted for + * transfer-encoding! */ + connclose(conn, "HTTP/1.1 transfer-encoding without chunks"); + k->ignore_cl = TRUE; + } + return CURLE_OK; + } + break; + case 'w': + case 'W': + if((401 == k->httpcode) && HD_IS(hd, hdlen, "WWW-Authenticate:")) { + char *auth = Curl_copy_header_value(hd); + if(!auth) + return CURLE_OUT_OF_MEMORY; + result = Curl_http_input_auth(data, FALSE, auth); + free(auth); return result; + } + break; } -#endif - else if(conn->handler->protocol & CURLPROTO_RTSP) { - result = Curl_rtsp_parseheader(data, headp); + + if(conn->handler->protocol & CURLPROTO_RTSP) { + result = Curl_rtsp_parseheader(data, hd); if(result) return result; } @@ -3317,7 +3360,8 @@ static CURLcode http_rw_headers(struct Curl_easy *data, struct connectdata *conn = data->conn; CURLcode result = CURLE_OK; struct SingleRequest *k = &data->req; - char *headp; + char *hd; + size_t hdlen; char *end_ptr; bool leftover_body = FALSE; @@ -3402,17 +3446,12 @@ static CURLcode http_rw_headers(struct Curl_easy *data, /* headers are in network encoding so use 0x0a and 0x0d instead of '\n' and '\r' */ - headp = Curl_dyn_ptr(&data->state.headerb); - if((0x0a == *headp) || (0x0d == *headp)) { - size_t headerlen; + hd = Curl_dyn_ptr(&data->state.headerb); + hdlen = Curl_dyn_len(&data->state.headerb); + if((0x0a == *hd) || (0x0d == *hd)) { bool switch_to_h2 = FALSE; /* Zero-length header line means end of headers! */ - if('\r' == *headp) - headp++; /* pass the \r byte */ - if('\n' == *headp) - headp++; /* pass the \n byte */ - if(100 <= k->httpcode && 199 >= k->httpcode) { /* "A user agent MAY ignore unexpected 1xx status responses." */ switch(k->httpcode) { @@ -3540,14 +3579,11 @@ static CURLcode http_rw_headers(struct Curl_easy *data, writetype = CLIENTWRITE_HEADER | ((k->httpcode/100 == 1) ? CLIENTWRITE_1XX : 0); - headerlen = Curl_dyn_len(&data->state.headerb); - result = Curl_client_write(data, writetype, - Curl_dyn_ptr(&data->state.headerb), - headerlen); + result = Curl_client_write(data, writetype, hd, hdlen); if(result) return result; - result = Curl_bump_headersize(data, headerlen, FALSE); + result = Curl_bump_headersize(data, hdlen, FALSE); if(result) return result; @@ -3713,7 +3749,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, * guarantees on future behaviors since it isn't within the protocol. */ int httpversion = 0; - char *p = headp; + char *p = hd; while(*p && ISBLANK(*p)) p++; @@ -3808,7 +3844,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, } } else if(conn->handler->protocol & CURLPROTO_RTSP) { - char *p = headp; + char *p = hd; while(*p && ISBLANK(*p)) p++; if(!strncmp(p, "RTSP/", 5)) { @@ -3851,7 +3887,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, if(result) return result; - result = Curl_http_header(data, conn, headp); + result = Curl_http_header(data, conn, hd, hdlen); if(result) return result; @@ -3861,16 +3897,13 @@ static CURLcode http_rw_headers(struct Curl_easy *data, if(k->httpcode/100 == 1) writetype |= CLIENTWRITE_1XX; - Curl_debug(data, CURLINFO_HEADER_IN, headp, - Curl_dyn_len(&data->state.headerb)); + Curl_debug(data, CURLINFO_HEADER_IN, hd, hdlen); - result = Curl_client_write(data, writetype, headp, - Curl_dyn_len(&data->state.headerb)); + result = Curl_client_write(data, writetype, hd, hdlen); if(result) return result; - result = Curl_bump_headersize(data, Curl_dyn_len(&data->state.headerb), - FALSE); + result = Curl_bump_headersize(data, hdlen, FALSE); if(result) return result; diff --git a/lib/http.h b/lib/http.h index 63f104971ef..047709f20fc 100644 --- a/lib/http.h +++ b/lib/http.h @@ -103,7 +103,7 @@ CURLcode Curl_http_target(struct Curl_easy *data, struct connectdata *conn, CURLcode Curl_http_statusline(struct Curl_easy *data, struct connectdata *conn); CURLcode Curl_http_header(struct Curl_easy *data, struct connectdata *conn, - char *headp); + char *headp, size_t hdlen); CURLcode Curl_transferencode(struct Curl_easy *data); CURLcode Curl_http_req_set_reader(struct Curl_easy *data, Curl_HttpReq httpreq, diff --git a/lib/http2.c b/lib/http2.c index 115def26c39..e1b05aaebb2 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -1970,7 +1970,8 @@ static ssize_t cf_h2_recv(struct Curl_cfilter *cf, struct Curl_easy *data, static ssize_t h2_submit(struct h2_stream_ctx **pstream, struct Curl_cfilter *cf, struct Curl_easy *data, - const void *buf, size_t len, CURLcode *err) + const void *buf, size_t len, + size_t *phdslen, CURLcode *err) { struct cf_h2_ctx *ctx = cf->ctx; struct h2_stream_ctx *stream = NULL; @@ -1983,6 +1984,7 @@ static ssize_t h2_submit(struct h2_stream_ctx **pstream, nghttp2_priority_spec pri_spec; ssize_t nwritten; + *phdslen = 0; Curl_dynhds_init(&h2_headers, 0, DYN_HTTP_REQUEST); *err = http2_data_setup(cf, data, &stream); @@ -1994,6 +1996,7 @@ static ssize_t h2_submit(struct h2_stream_ctx **pstream, nwritten = Curl_h1_req_parse_read(&stream->h1, buf, len, NULL, 0, err); if(nwritten < 0) goto out; + *phdslen = (size_t)nwritten; if(!stream->h1.done) { /* need more data */ goto out; @@ -2116,6 +2119,7 @@ static ssize_t cf_h2_send(struct Curl_cfilter *cf, struct Curl_easy *data, struct cf_call_data save; int rv; ssize_t nwritten; + size_t hdslen = 0; CURLcode result; int blocked = 0, was_blocked = 0; @@ -2179,11 +2183,12 @@ static ssize_t cf_h2_send(struct Curl_cfilter *cf, struct Curl_easy *data, } } else { - nwritten = h2_submit(&stream, cf, data, buf, len, err); + nwritten = h2_submit(&stream, cf, data, buf, len, &hdslen, err); if(nwritten < 0) { goto out; } DEBUGASSERT(stream); + DEBUGASSERT(hdslen <= (size_t)nwritten); } /* Call the nghttp2 send loop and flush to write ALL buffered data, @@ -2218,18 +2223,26 @@ static ssize_t cf_h2_send(struct Curl_cfilter *cf, struct Curl_easy *data, * frame buffer or our network out buffer. */ size_t rwin = nghttp2_session_get_stream_remote_window_size(ctx->h2, stream->id); - /* Whatever the cause, we need to return CURL_EAGAIN for this call. - * We have unwritten state that needs us being invoked again and EAGAIN - * is the only way to ensure that. */ - stream->upload_blocked_len = nwritten; + /* At the start of a stream, we are called with request headers + * and, possibly, parts of the body. Later, only body data. + * If we cannot send pure body data, we EAGAIN. If there had been + * header, we return that *they* have been written and remember the + * block on the data length only. */ + stream->upload_blocked_len = ((size_t)nwritten) - hdslen; CURL_TRC_CF(data, cf, "[%d] cf_send(len=%zu) BLOCK: win %u/%zu " - "blocked_len=%zu", + "hds_len=%zu blocked_len=%zu", stream->id, len, nghttp2_session_get_remote_window_size(ctx->h2), rwin, - nwritten); - *err = CURLE_AGAIN; - nwritten = -1; - goto out; + hdslen, stream->upload_blocked_len); + if(hdslen) { + *err = CURLE_OK; + nwritten = hdslen; + } + else { + *err = CURLE_AGAIN; + nwritten = -1; + goto out; + } } else if(should_close_session(ctx)) { /* nghttp2 thinks this session is done. If the stream has not been diff --git a/lib/request.c b/lib/request.c index e62f58868c2..b3b05824578 100644 --- a/lib/request.c +++ b/lib/request.c @@ -331,24 +331,38 @@ static CURLcode req_send_buffer_add(struct Curl_easy *data, return CURLE_OK; } -CURLcode Curl_req_send(struct Curl_easy *data, struct dynbuf *buf) +CURLcode Curl_req_send(struct Curl_easy *data, struct dynbuf *req) { CURLcode result; + const char *buf; + size_t blen, nwritten; if(!data || !data->conn) return CURLE_FAILED_INIT; - /* We always buffer and send from there. The reason is that on - * blocking, we can retry using the same memory address. This is - * important for TLS libraries that expect this. - * We *could* optimized for non-TLS transfers, but that would mean - * separate code paths and seems not worth it. */ - result = req_send_buffer_add(data, Curl_dyn_ptr(buf), Curl_dyn_len(buf), - Curl_dyn_len(buf)); - if(result) - return result; + buf = Curl_dyn_ptr(req); + blen = Curl_dyn_len(req); + if(!Curl_creader_total_length(data)) { + /* Request without body. Try to send directly from the buf given. */ + data->req.eos_read = TRUE; + result = xfer_send(data, buf, blen, blen, &nwritten); + if(result) + return result; + buf += nwritten; + blen -= nwritten; + } - return Curl_req_send_more(data); + if(blen) { + /* Either we have a request body, or we could not send the complete + * request in one go. Buffer the remainder and try to add as much + * body bytes as room is left in the buffer. Then flush. */ + result = req_send_buffer_add(data, buf, blen, blen); + if(result) + return result; + + return Curl_req_send_more(data); + } + return CURLE_OK; } #endif /* !USE_HYPER */ From fd1260d492f9fb4d16c5abd22a58de959f49dcf8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Mar 2024 11:27:42 +0100 Subject: [PATCH 485/509] CURLOPT_INTERFACE.md: remove spurious amp, add see-also Closes #13149 --- docs/libcurl/opts/CURLOPT_INTERFACE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.md b/docs/libcurl/opts/CURLOPT_INTERFACE.md index 0cd3d44cf9a..9f5822d495e 100644 --- a/docs/libcurl/opts/CURLOPT_INTERFACE.md +++ b/docs/libcurl/opts/CURLOPT_INTERFACE.md @@ -7,6 +7,7 @@ Source: libcurl See-also: - CURLOPT_SOCKOPTFUNCTION (3) - CURLOPT_TCP_NODELAY (3) + - CURLOPT_LOCALPORT (3) --- # NAME @@ -28,12 +29,12 @@ outgoing network interface. The name can be an interface name, an IP address, or a hostname. If the parameter starts with "if!" then it is treated only as an interface -name. If the parameter starts with &"host!" it is treated as either an IP +name. If the parameter starts with "host!" it is treated as either an IP address or a hostname. If "if!" is specified but the parameter does not match an existing interface, -*CURLE_INTERFACE_FAILED* is returned from the libcurl function used to -perform the transfer. +*CURLE_INTERFACE_FAILED* is returned from the libcurl function used to perform +the transfer. libcurl does not support using network interface names for this option on Windows. From e6af5652ec6641ab816bfbb646dfa321061ce799 Mon Sep 17 00:00:00 2001 From: Karlson2k Date: Wed, 20 Mar 2024 23:03:24 +0100 Subject: [PATCH 486/509] RELEASE-NOTES: corrected Corrected link for item 118 Closes #13157 --- RELEASE-NOTES | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index 0b278083529..c0f16e0bc73 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -308,7 +308,7 @@ References to bug reports and discussions on issues: [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=13070 + [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 From 33d9652a907910fafed41c25b5611831e903e944 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Mar 2024 08:28:56 +0100 Subject: [PATCH 487/509] RELEASE-NOTES: synced --- RELEASE-NOTES | 42 +++++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index c0f16e0bc73..aa7038ebd1a 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.7.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3115 + Contributors: 3120 This release includes the following changes: @@ -53,6 +53,7 @@ This release includes the following bugfixes: 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 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] @@ -88,11 +89,13 @@ This release includes the following bugfixes: o http2: push headers better cleanup [113] 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_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] @@ -109,6 +112,7 @@ This release includes the following bugfixes: 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] @@ -140,10 +144,13 @@ This release includes the following bugfixes: 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 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] @@ -173,21 +180,23 @@ This release would not have looked like this without help, code, reports and advice from friends like these: 5533asdg on github, Andreas Kiefer, av223119 on github, - awesomekosm on github, Boris Verkhovskiy, Brett Buddin, Chris Webb, - Dan Fandrich, Daniel Gustafsson, Daniel Stenberg, Daniel Szmulewicz, - DasKutti on github, dependabot[bot], Dexter Gerig, Dirk Hünniger, - Dmitry Karpov, Dmitry Tretyakov, edmcln on github, Erik Schnetter, - Evgeny Grin (Karlson2k), Fabian Vogt, Fabrice Fontaine, Faraz Fallahi, - Geeknik Labs, Gisle Vanem, Harry Sintonen, HsiehYuho on github, Jan Macku, - Jiawen Geng, Joel Depooter, Jon Rumsey, Jordan Brown, Karthikdasari0423, + awesomekosm on github, Boris Verkhovskiy, Brett Buddin, + chensong1211 on github, Chris Webb, Dan Fandrich, Daniel Gustafsson, + Daniel Stenberg, Daniel Szmulewicz, 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 Vogt, Fabrice Fontaine, Faraz Fallahi, Geeknik Labs, Gisle Vanem, + Harry Sintonen, HsiehYuho on github, Jan Macku, Jiawen Geng, Jiří Bok, + Joel Depooter, Jon Rumsey, Jordan Brown, Josh Soref, Karthikdasari0423, Karthikdasari0423 on github, Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, LeeRiva, Louis Solofrizzo, Lukáš Zaoral, Marcel Raad, Michael Forney, Michael Kaufmann, Michał Antoniak, Nikita Taranov, Patrick Monnerat, - Paweł Witas, Peter Krefting, RainRat, Ramiro Garcia, Ray Satiro, - Richard Levitte, Robert Moreton, Rudi Heitbaum, Ryan Carsten Schmidt, - Scott Mutter, Scott Talbert, Sebastian Neubauer, Sergey Bronnikov, Simon K, - Stefan Eissing, Tal Regev, Viktor Szakats, vulnerabilityspotter on hackerone - (64 contributors) + Paweł Witas, Pēteris Caune, Peter Krefting, RainRat, Ramiro Garcia, + Ray Satiro, Richard Levitte, Robert Moreton, Rudi Heitbaum, + Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, Sebastian Neubauer, + Sergey Bronnikov, Simon K, Stefan Eissing, Tal Regev, Thomas Pyle, + Viktor Szakats, vulnerabilityspotter on hackerone + (70 contributors) References to bug reports and discussions on issues: @@ -326,7 +335,14 @@ References to bug reports and discussions on issues: [133] = https://curl.se/bug/?i=13118 [134] = https://curl.se/bug/?i=12063 [135] = https://curl.se/bug/?i=13115 + [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 + [146] = https://curl.se/bug/?i=13132 + [147] = https://curl.se/bug/?i=13112 + [149] = https://curl.se/bug/?i=13128 + [150] = https://curl.se/bug/?i=10290 From 0c820427f2d38d2fc4e653aa3d058fc9135a9e50 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 20 Mar 2024 12:06:13 +0100 Subject: [PATCH 488/509] http2: remove the third (unused) argument from http2_data_done() Closes #13154 --- lib/http2.c | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/lib/http2.c b/lib/http2.c index e1b05aaebb2..f3d4d2e1112 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -280,14 +280,12 @@ static void free_push_headers(struct h2_stream_ctx *stream) stream->push_headers_used = 0; } -static void http2_data_done(struct Curl_cfilter *cf, - struct Curl_easy *data, bool premature) +static void http2_data_done(struct Curl_cfilter *cf, struct Curl_easy *data) { struct cf_h2_ctx *ctx = cf->ctx; struct h2_stream_ctx *stream = H2_STREAM_CTX(data); DEBUGASSERT(ctx); - (void)premature; if(!stream) return; @@ -841,7 +839,7 @@ static void discard_newhandle(struct Curl_cfilter *cf, struct Curl_easy *newhandle) { if(newhandle->req.p.http) { - http2_data_done(cf, newhandle, TRUE); + http2_data_done(cf, newhandle); } (void)Curl_close(&newhandle); } @@ -2466,10 +2464,10 @@ static CURLcode cf_h2_cntrl(struct Curl_cfilter *cf, result = http2_data_done_send(cf, data); break; case CF_CTRL_DATA_DETACH: - http2_data_done(cf, data, TRUE); + http2_data_done(cf, data); break; case CF_CTRL_DATA_DONE: - http2_data_done(cf, data, arg1 != 0); + http2_data_done(cf, data); break; default: break; From 0f08b43557df8151d0636f2f4e886db39be71887 Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Mon, 11 Mar 2024 17:23:15 +0100 Subject: [PATCH 489/509] http: separate response parsing from response action - move code that triggers on end-of-response into separate function from parsing - simplify some headp/headerlen usage - add `httpversion` to SingleRequest to indicate the version of the current response Closes #13134 --- lib/c-hyper.c | 7 +- lib/http.c | 648 ++++++++++++++++++++++++++------------------------ lib/request.h | 1 + 3 files changed, 339 insertions(+), 317 deletions(-) diff --git a/lib/c-hyper.c b/lib/c-hyper.c index 55a68e3706b..247d59f077f 100644 --- a/lib/c-hyper.c +++ b/lib/c-hyper.c @@ -274,14 +274,13 @@ static CURLcode status_line(struct Curl_easy *data, /* We need to set 'httpcodeq' for functions that check the response code in a single place. */ data->req.httpcode = http_status; - + data->req.httpversion = http_version == HYPER_HTTP_VERSION_1_1? 11 : + (http_version == HYPER_HTTP_VERSION_2 ? 20 : 10); if(data->state.hconnect) /* CONNECT */ data->info.httpproxycode = http_status; else { - conn->httpversion = - http_version == HYPER_HTTP_VERSION_1_1 ? 11 : - (http_version == HYPER_HTTP_VERSION_2 ? 20 : 10); + conn->httpversion = (unsigned char)data->req.httpversion; if(http_version == HYPER_HTTP_VERSION_1_0) data->state.httpwant = CURL_HTTP_VERSION_1_0; diff --git a/lib/http.c b/lib/http.c index cacebeacfbf..4de0e8e4403 100644 --- a/lib/http.c +++ b/lib/http.c @@ -3196,18 +3196,38 @@ CURLcode Curl_http_header(struct Curl_easy *data, struct connectdata *conn, * Called after the first HTTP response line (the status line) has been * received and parsed. */ - CURLcode Curl_http_statusline(struct Curl_easy *data, struct connectdata *conn) { struct SingleRequest *k = &data->req; + + switch(k->httpversion) { + case 10: + case 11: +#ifdef USE_HTTP2 + case 20: +#endif +#ifdef ENABLE_QUIC + case 30: +#endif + /* TODO: we should verify that responses do not switch major + * HTTP version of the connection. Now, it seems we might accept + * a HTTP/2 response on a HTTP/1.1 connection, which is wrong. */ + conn->httpversion = (unsigned char)k->httpversion; + break; + default: + failf(data, "Unsupported HTTP version (%u.%d) in response", + k->httpversion/10, k->httpversion%10); + return CURLE_UNSUPPORTED_PROTOCOL; + } + data->info.httpcode = k->httpcode; + data->info.httpversion = k->httpversion; + conn->httpversion = (unsigned char)k->httpversion; - data->info.httpversion = conn->httpversion; - if(!data->state.httpversion || - data->state.httpversion > conn->httpversion) + if(!data->state.httpversion || data->state.httpversion > k->httpversion) /* store the lowest server version we encounter */ - data->state.httpversion = conn->httpversion; + data->state.httpversion = (unsigned char)k->httpversion; /* * This code executes as part of processing the header. As a @@ -3224,25 +3244,23 @@ CURLcode Curl_http_statusline(struct Curl_easy *data, k->ignorebody = TRUE; /* Avoid appending error msg to good data. */ } - if(conn->httpversion == 10) { + if(k->httpversion == 10) { /* Default action for HTTP/1.0 must be to close, unless we get one of those fancy headers that tell us the server keeps it open for us! */ infof(data, "HTTP 1.0, assume close after body"); connclose(conn, "HTTP/1.0 close after body"); } - else if(conn->httpversion == 20 || + else if(k->httpversion == 20 || (k->upgr101 == UPGR101_H2 && k->httpcode == 101)) { DEBUGF(infof(data, "HTTP/2 found, allow multiplexing")); /* HTTP/2 cannot avoid multiplexing since it is a core functionality of the protocol */ conn->bundle->multiuse = BUNDLE_MULTIPLEX; } - else if(conn->httpversion >= 11 && - !conn->bits.close) { + else if(k->httpversion >= 11 && !conn->bits.close) { /* If HTTP version is >= 1.1 and connection is persistent */ - DEBUGF(infof(data, - "HTTP 1.1 or later with persistent connection")); + DEBUGF(infof(data, "HTTP 1.1 or later with persistent connection")); } k->http_bodyless = k->httpcode >= 100 && k->httpcode < 200; @@ -3350,6 +3368,287 @@ CURLcode Curl_bump_headersize(struct Curl_easy *data, } +static CURLcode http_on_response(struct Curl_easy *data, + const char *buf, size_t blen, + size_t *pconsumed) +{ + struct connectdata *conn = data->conn; + CURLcode result = CURLE_OK; + struct SingleRequest *k = &data->req; + bool switch_to_h2 = FALSE; + + (void)buf; /* not used without HTTP2 enabled */ + *pconsumed = 0; + + if(k->upgr101 == UPGR101_RECEIVED) { + /* supposedly upgraded to http2 now */ + if(conn->httpversion != 20) + infof(data, "Lying server, not serving HTTP/2"); + } + if(conn->httpversion < 20) { + conn->bundle->multiuse = BUNDLE_NO_MULTIUSE; + } + + if(k->httpcode < 100) { + failf(data, "Unsupported response code in HTTP response"); + return CURLE_UNSUPPORTED_PROTOCOL; + } + else if(k->httpcode < 200) { + /* "A user agent MAY ignore unexpected 1xx status responses." */ + switch(k->httpcode) { + case 100: + /* + * We have made an HTTP PUT or POST and this is 1.1-lingo + * that tells us that the server is OK with this and ready + * to receive the data. + * However, we'll get more headers now so we must get + * back into the header-parsing state! + */ + k->header = TRUE; + k->headerline = 0; /* restart the header line counter */ + + /* if we did wait for this do enable write now! */ + Curl_http_exp100_got100(data); + break; + case 101: + if(conn->httpversion == 11) { + /* Switching Protocols only allowed from HTTP/1.1 */ + if(k->upgr101 == UPGR101_H2) { + /* Switching to HTTP/2 */ + infof(data, "Received 101, Switching to HTTP/2"); + k->upgr101 = UPGR101_RECEIVED; + + /* we'll get more headers (HTTP/2 response) */ + k->header = TRUE; + k->headerline = 0; /* restart the header line counter */ + switch_to_h2 = TRUE; + } +#ifdef USE_WEBSOCKETS + else if(k->upgr101 == UPGR101_WS) { + /* verify the response */ + result = Curl_ws_accept(data, buf, blen); + if(result) + return result; + k->header = FALSE; /* no more header to parse! */ + *pconsumed += blen; /* ws accept handled the data */ + blen = 0; + if(data->set.connect_only) + k->keepon &= ~KEEP_RECV; /* read no more content */ + } +#endif + else { + /* Not switching to another protocol */ + k->header = FALSE; /* no more header to parse! */ + } + } + else { + /* invalid for other HTTP versions */ + failf(data, "unexpected 101 response code"); + return CURLE_WEIRD_SERVER_REPLY; + } + break; + default: + /* the status code 1xx indicates a provisional response, so + we'll get another set of headers */ + k->header = TRUE; + k->headerline = 0; /* restart the header line counter */ + break; + } + } + else { + /* k->httpcode >= 200, final response */ + k->header = FALSE; + + if(k->upgr101 == UPGR101_H2) { + /* A requested upgrade was denied, poke the multi handle to possibly + allow a pending pipewait to continue */ + Curl_multi_connchanged(data->multi); + } + + if((k->size == -1) && !k->chunk && !conn->bits.close && + (conn->httpversion == 11) && + !(conn->handler->protocol & CURLPROTO_RTSP) && + data->state.httpreq != HTTPREQ_HEAD) { + /* On HTTP 1.1, when connection is not to get closed, but no + Content-Length nor Transfer-Encoding chunked have been + received, according to RFC2616 section 4.4 point 5, we + assume that the server will close the connection to + signal the end of the document. */ + infof(data, "no chunk, no close, no size. Assume close to " + "signal end"); + streamclose(conn, "HTTP: No end-of-message indicator"); + } + } + + if(!k->header) { + result = Curl_http_size(data); + if(result) + return result; + } + + /* At this point we have some idea about the fate of the connection. + If we are closing the connection it may result auth failure. */ +#if defined(USE_NTLM) + if(conn->bits.close && + (((data->req.httpcode == 401) && + (conn->http_ntlm_state == NTLMSTATE_TYPE2)) || + ((data->req.httpcode == 407) && + (conn->proxy_ntlm_state == NTLMSTATE_TYPE2)))) { + infof(data, "Connection closure while negotiating auth (HTTP 1.0?)"); + data->state.authproblem = TRUE; + } +#endif +#if defined(USE_SPNEGO) + if(conn->bits.close && + (((data->req.httpcode == 401) && + (conn->http_negotiate_state == GSS_AUTHRECV)) || + ((data->req.httpcode == 407) && + (conn->proxy_negotiate_state == GSS_AUTHRECV)))) { + infof(data, "Connection closure while negotiating auth (HTTP 1.0?)"); + data->state.authproblem = TRUE; + } + if((conn->http_negotiate_state == GSS_AUTHDONE) && + (data->req.httpcode != 401)) { + conn->http_negotiate_state = GSS_AUTHSUCC; + } + if((conn->proxy_negotiate_state == GSS_AUTHDONE) && + (data->req.httpcode != 407)) { + conn->proxy_negotiate_state = GSS_AUTHSUCC; + } +#endif + + /* + * When all the headers have been parsed, see if we should give + * up and return an error. + */ + if(http_should_fail(data)) { + failf(data, "The requested URL returned error: %d", + k->httpcode); + return CURLE_HTTP_RETURNED_ERROR; + } + +#ifdef USE_WEBSOCKETS + /* All non-101 HTTP status codes are bad when wanting to upgrade to + websockets */ + if(data->req.upgr101 == UPGR101_WS) { + failf(data, "Refused WebSockets upgrade: %d", k->httpcode); + return CURLE_HTTP_RETURNED_ERROR; + } +#endif + + + /* Curl_http_auth_act() checks what authentication methods + * that are available and decides which one (if any) to + * use. It will set 'newurl' if an auth method was picked. */ + result = Curl_http_auth_act(data); + + if(result) + return result; + + if(k->httpcode >= 300) { + if((!data->req.authneg) && !conn->bits.close && + !Curl_creader_will_rewind(data)) { + /* + * General treatment of errors when about to send data. Including : + * "417 Expectation Failed", while waiting for 100-continue. + * + * The check for close above is done simply because of something + * else has already deemed the connection to get closed then + * something else should've considered the big picture and we + * avoid this check. + * + * rewindbeforesend indicates that something has told libcurl to + * continue sending even if it gets discarded + */ + + switch(data->state.httpreq) { + case HTTPREQ_PUT: + case HTTPREQ_POST: + case HTTPREQ_POST_FORM: + case HTTPREQ_POST_MIME: + /* We got an error response. If this happened before the whole + * request body has been sent we stop sending and mark the + * connection for closure after we've read the entire response. + */ + if(!Curl_req_done_sending(data)) { + if((k->httpcode == 417) && Curl_http_exp100_is_selected(data)) { + /* 417 Expectation Failed - try again without the Expect + header */ + if(!k->writebytecount && http_exp100_is_waiting(data)) { + infof(data, "Got HTTP failure 417 while waiting for a 100"); + } + else { + infof(data, "Got HTTP failure 417 while sending data"); + streamclose(conn, + "Stop sending data before everything sent"); + result = http_perhapsrewind(data, conn); + if(result) + return result; + } + data->state.disableexpect = TRUE; + DEBUGASSERT(!data->req.newurl); + data->req.newurl = strdup(data->state.url); + Curl_req_abort_sending(data); + } + else if(data->set.http_keep_sending_on_error) { + infof(data, "HTTP error before end of send, keep sending"); + http_exp100_send_anyway(data); + } + else { + infof(data, "HTTP error before end of send, stop sending"); + streamclose(conn, "Stop sending data before everything sent"); + result = Curl_req_abort_sending(data); + if(result) + return result; + } + } + break; + + default: /* default label present to avoid compiler warnings */ + break; + } + } + + if(Curl_creader_will_rewind(data) && !Curl_req_done_sending(data)) { + /* We rewind before next send, continue sending now */ + infof(data, "Keep sending data to get tossed away"); + k->keepon |= KEEP_SEND; + } + } + + if(!k->header) { + /* + * really end-of-headers. + * + * If we requested a "no body", this is a good time to get + * out and return home. + */ + if(data->req.no_body) + k->download_done = TRUE; + + /* If max download size is *zero* (nothing) we already have + nothing and can safely return ok now! But for HTTP/2, we'd + like to call http2_handle_stream_close to properly close a + stream. In order to do this, we keep reading until we + close the stream. */ + if(0 == k->maxdownload + && !Curl_conn_is_http2(data, conn, FIRSTSOCKET) + && !Curl_conn_is_http3(data, conn, FIRSTSOCKET)) + k->download_done = TRUE; + } + + if(switch_to_h2) { + /* Having handled the headers, we can do the HTTP/2 switch. + * Any remaining `buf` bytes are already HTTP/2 and passed to + * be processed. */ + result = Curl_http2_upgrade(data, conn, FIRSTSOCKET, buf, blen); + if(result) + return result; + *pconsumed += blen; + } + + return CURLE_OK; +} /* * Read any HTTP header lines from the server and pass them to the client app. */ @@ -3449,133 +3748,13 @@ static CURLcode http_rw_headers(struct Curl_easy *data, hd = Curl_dyn_ptr(&data->state.headerb); hdlen = Curl_dyn_len(&data->state.headerb); if((0x0a == *hd) || (0x0d == *hd)) { - bool switch_to_h2 = FALSE; - /* Zero-length header line means end of headers! */ - - if(100 <= k->httpcode && 199 >= k->httpcode) { - /* "A user agent MAY ignore unexpected 1xx status responses." */ - switch(k->httpcode) { - case 100: - /* - * We have made an HTTP PUT or POST and this is 1.1-lingo - * that tells us that the server is OK with this and ready - * to receive the data. - * However, we'll get more headers now so we must get - * back into the header-parsing state! - */ - k->header = TRUE; - k->headerline = 0; /* restart the header line counter */ - - /* if we did wait for this do enable write now! */ - Curl_http_exp100_got100(data); - break; - case 101: - if(conn->httpversion == 11) { - /* Switching Protocols only allowed from HTTP/1.1 */ - if(k->upgr101 == UPGR101_H2) { - /* Switching to HTTP/2 */ - infof(data, "Received 101, Switching to HTTP/2"); - k->upgr101 = UPGR101_RECEIVED; - - /* we'll get more headers (HTTP/2 response) */ - k->header = TRUE; - k->headerline = 0; /* restart the header line counter */ - switch_to_h2 = TRUE; - } -#ifdef USE_WEBSOCKETS - else if(k->upgr101 == UPGR101_WS) { - /* verify the response */ - result = Curl_ws_accept(data, buf, blen); - if(result) - return result; - k->header = FALSE; /* no more header to parse! */ - *pconsumed += blen; /* ws accept handled the data */ - blen = 0; - if(data->set.connect_only) - k->keepon &= ~KEEP_RECV; /* read no more content */ - } -#endif - else { - /* Not switching to another protocol */ - k->header = FALSE; /* no more header to parse! */ - } - } - else { - /* invalid for other HTTP versions */ - failf(data, "unexpected 101 response code"); - return CURLE_WEIRD_SERVER_REPLY; - } - break; - default: - /* the status code 1xx indicates a provisional response, so - we'll get another set of headers */ - k->header = TRUE; - k->headerline = 0; /* restart the header line counter */ - break; - } - } - else { - if(k->upgr101 == UPGR101_H2) { - /* A requested upgrade was denied, poke the multi handle to possibly - allow a pending pipewait to continue */ - Curl_multi_connchanged(data->multi); - } - k->header = FALSE; /* no more header to parse! */ - - if((k->size == -1) && !k->chunk && !conn->bits.close && - (conn->httpversion == 11) && - !(conn->handler->protocol & CURLPROTO_RTSP) && - data->state.httpreq != HTTPREQ_HEAD) { - /* On HTTP 1.1, when connection is not to get closed, but no - Content-Length nor Transfer-Encoding chunked have been - received, according to RFC2616 section 4.4 point 5, we - assume that the server will close the connection to - signal the end of the document. */ - infof(data, "no chunk, no close, no size. Assume close to " - "signal end"); - streamclose(conn, "HTTP: No end-of-message indicator"); - } - } - - if(!k->header) { - result = Curl_http_size(data); - if(result) - return result; - } - - /* At this point we have some idea about the fate of the connection. - If we are closing the connection it may result auth failure. */ -#if defined(USE_NTLM) - if(conn->bits.close && - (((data->req.httpcode == 401) && - (conn->http_ntlm_state == NTLMSTATE_TYPE2)) || - ((data->req.httpcode == 407) && - (conn->proxy_ntlm_state == NTLMSTATE_TYPE2)))) { - infof(data, "Connection closure while negotiating auth (HTTP 1.0?)"); - data->state.authproblem = TRUE; - } -#endif -#if defined(USE_SPNEGO) - if(conn->bits.close && - (((data->req.httpcode == 401) && - (conn->http_negotiate_state == GSS_AUTHRECV)) || - ((data->req.httpcode == 407) && - (conn->proxy_negotiate_state == GSS_AUTHRECV)))) { - infof(data, "Connection closure while negotiating auth (HTTP 1.0?)"); - data->state.authproblem = TRUE; - } - if((conn->http_negotiate_state == GSS_AUTHDONE) && - (data->req.httpcode != 401)) { - conn->http_negotiate_state = GSS_AUTHSUCC; - } - if((conn->proxy_negotiate_state == GSS_AUTHDONE) && - (data->req.httpcode != 407)) { - conn->proxy_negotiate_state = GSS_AUTHSUCC; - } -#endif + /* Empty header line means end of headers! */ + size_t consumed; /* now, only output this if the header AND body are requested: */ + Curl_debug(data, CURLINFO_HEADER_IN, hd, hdlen); + writetype = CLIENTWRITE_HEADER | ((k->httpcode/100 == 1) ? CLIENTWRITE_1XX : 0); @@ -3586,147 +3765,24 @@ static CURLcode http_rw_headers(struct Curl_easy *data, result = Curl_bump_headersize(data, hdlen, FALSE); if(result) return result; - - /* - * When all the headers have been parsed, see if we should give - * up and return an error. - */ - if(http_should_fail(data)) { - failf(data, "The requested URL returned error: %d", - k->httpcode); - return CURLE_HTTP_RETURNED_ERROR; - } - -#ifdef USE_WEBSOCKETS - /* All non-101 HTTP status codes are bad when wanting to upgrade to - websockets */ - if(data->req.upgr101 == UPGR101_WS) { - failf(data, "Refused WebSockets upgrade: %d", k->httpcode); - return CURLE_HTTP_RETURNED_ERROR; - } -#endif - + /* We are done with this line. We reset because response + * processing might switch to HTTP/2 and that might call us + * directly again. */ + Curl_dyn_reset(&data->state.headerb); data->req.deductheadercount = (100 <= k->httpcode && 199 >= k->httpcode)?data->req.headerbytecount:0; - /* Curl_http_auth_act() checks what authentication methods - * that are available and decides which one (if any) to - * use. It will set 'newurl' if an auth method was picked. */ - result = Curl_http_auth_act(data); - + /* analyze the response to find out what to do */ + result = http_on_response(data, buf, blen, &consumed); if(result) return result; + *pconsumed += consumed; + blen -= consumed; + buf += consumed; - if(k->httpcode >= 300) { - if((!data->req.authneg) && !conn->bits.close && - !Curl_creader_will_rewind(data)) { - /* - * General treatment of errors when about to send data. Including : - * "417 Expectation Failed", while waiting for 100-continue. - * - * The check for close above is done simply because of something - * else has already deemed the connection to get closed then - * something else should've considered the big picture and we - * avoid this check. - * - * rewindbeforesend indicates that something has told libcurl to - * continue sending even if it gets discarded - */ - - switch(data->state.httpreq) { - case HTTPREQ_PUT: - case HTTPREQ_POST: - case HTTPREQ_POST_FORM: - case HTTPREQ_POST_MIME: - /* We got an error response. If this happened before the whole - * request body has been sent we stop sending and mark the - * connection for closure after we've read the entire response. - */ - if(!Curl_req_done_sending(data)) { - if((k->httpcode == 417) && Curl_http_exp100_is_selected(data)) { - /* 417 Expectation Failed - try again without the Expect - header */ - if(!k->writebytecount && http_exp100_is_waiting(data)) { - infof(data, "Got HTTP failure 417 while waiting for a 100"); - } - else { - infof(data, "Got HTTP failure 417 while sending data"); - streamclose(conn, - "Stop sending data before everything sent"); - result = http_perhapsrewind(data, conn); - if(result) - return result; - } - data->state.disableexpect = TRUE; - DEBUGASSERT(!data->req.newurl); - data->req.newurl = strdup(data->state.url); - Curl_req_abort_sending(data); - } - else if(data->set.http_keep_sending_on_error) { - infof(data, "HTTP error before end of send, keep sending"); - http_exp100_send_anyway(data); - } - else { - infof(data, "HTTP error before end of send, stop sending"); - streamclose(conn, "Stop sending data before everything sent"); - result = Curl_req_abort_sending(data); - if(result) - return result; - } - } - break; - - default: /* default label present to avoid compiler warnings */ - break; - } - } - - if(Curl_creader_will_rewind(data) && !Curl_req_done_sending(data)) { - /* We rewind before next send, continue sending now */ - infof(data, "Keep sending data to get tossed away"); - k->keepon |= KEEP_SEND; - } - } - - if(!k->header) { - /* - * really end-of-headers. - * - * If we requested a "no body", this is a good time to get - * out and return home. - */ - if(data->req.no_body) - k->download_done = TRUE; - - /* If max download size is *zero* (nothing) we already have - nothing and can safely return ok now! But for HTTP/2, we'd - like to call http2_handle_stream_close to properly close a - stream. In order to do this, we keep reading until we - close the stream. */ - if(0 == k->maxdownload - && !Curl_conn_is_http2(data, conn, FIRSTSOCKET) - && !Curl_conn_is_http3(data, conn, FIRSTSOCKET)) - k->download_done = TRUE; - - Curl_debug(data, CURLINFO_HEADER_IN, - Curl_dyn_ptr(&data->state.headerb), - Curl_dyn_len(&data->state.headerb)); + if(!k->header || !blen) goto out; /* exit header line loop */ - } - - /* We continue reading headers, reset the line-based header */ - Curl_dyn_reset(&data->state.headerb); - if(switch_to_h2) { - /* Having handled the headers, we can do the HTTP/2 switch. - * Any remaining `buf` bytes are already HTTP/2 and passed to - * be processed. */ - result = Curl_http2_upgrade(data, conn, FIRSTSOCKET, buf, blen); - if(result) - return result; - *pconsumed += blen; - blen = 0; - } continue; } @@ -3740,6 +3796,8 @@ static CURLcode http_rw_headers(struct Curl_easy *data, /* This is the first header, it MUST be the error code line or else we consider this to be the body right away! */ bool fine_statusline = FALSE; + + k->httpversion = 0; /* Don't know yet */ if(conn->handler->protocol & PROTO_FAMILY_HTTP) { /* * https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.2 @@ -3748,7 +3806,6 @@ static CURLcode http_rw_headers(struct Curl_easy *data, * says. We allow any three-digit number here, but we cannot make * guarantees on future behaviors since it isn't within the protocol. */ - int httpversion = 0; char *p = hd; while(*p && ISBLANK(*p)) @@ -3760,7 +3817,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, p++; if((p[0] == '.') && (p[1] == '0' || p[1] == '1')) { if(ISBLANK(p[2])) { - httpversion = 10 + (p[1] - '0'); + k->httpversion = 10 + (p[1] - '0'); p += 3; if(ISDIGIT(p[0]) && ISDIGIT(p[1]) && ISDIGIT(p[2])) { k->httpcode = (p[0] - '0') * 100 + (p[1] - '0') * 10 + @@ -3780,7 +3837,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, case '3': if(!ISBLANK(p[1])) break; - httpversion = (*p - '0') * 10; + k->httpversion = (*p - '0') * 10; p += 2; if(ISDIGIT(p[0]) && ISDIGIT(p[1]) && ISDIGIT(p[2])) { k->httpcode = (p[0] - '0') * 100 + (p[1] - '0') * 10 + @@ -3797,49 +3854,15 @@ static CURLcode http_rw_headers(struct Curl_easy *data, } } - if(fine_statusline) { - if(k->httpcode < 100) { - failf(data, "Unsupported response code in HTTP response"); - return CURLE_UNSUPPORTED_PROTOCOL; - } - switch(httpversion) { - case 10: - case 11: -#ifdef USE_HTTP2 - case 20: -#endif -#ifdef ENABLE_QUIC - case 30: -#endif - conn->httpversion = (unsigned char)httpversion; - break; - default: - failf(data, "Unsupported HTTP version (%u.%d) in response", - httpversion/10, httpversion%10); - return CURLE_UNSUPPORTED_PROTOCOL; - } - - if(k->upgr101 == UPGR101_RECEIVED) { - /* supposedly upgraded to http2 now */ - if(conn->httpversion != 20) - infof(data, "Lying server, not serving HTTP/2"); - } - if(conn->httpversion < 20) { - conn->bundle->multiuse = BUNDLE_NO_MULTIUSE; - } - } - else { + if(!fine_statusline) { /* If user has set option HTTP200ALIASES, compare header line against list of aliases */ - statusline check = - checkhttpprefix(data, - Curl_dyn_ptr(&data->state.headerb), - Curl_dyn_len(&data->state.headerb)); + statusline check = checkhttpprefix(data, hd, hdlen); if(check == STATUS_DONE) { fine_statusline = TRUE; k->httpcode = 200; - conn->httpversion = 10; + k->httpversion = 10; } } } @@ -3860,7 +3883,7 @@ static CURLcode http_rw_headers(struct Curl_easy *data, p += 3; if(ISSPACE(*p)) { fine_statusline = TRUE; - conn->httpversion = 11; /* RTSP acts like HTTP 1.1 */ + k->httpversion = 11; /* RTSP acts like HTTP 1.1 */ } } } @@ -3892,13 +3915,12 @@ static CURLcode http_rw_headers(struct Curl_easy *data, return result; /* - * End of header-checks. Write them to the client. + * Taken in one (more) header. Write it to the client. */ - if(k->httpcode/100 == 1) - writetype |= CLIENTWRITE_1XX; - Curl_debug(data, CURLINFO_HEADER_IN, hd, hdlen); + if(k->httpcode/100 == 1) + writetype |= CLIENTWRITE_1XX; result = Curl_client_write(data, writetype, hd, hdlen); if(result) return result; diff --git a/lib/request.h b/lib/request.h index 2513c2dfc19..488fbdd4d91 100644 --- a/lib/request.h +++ b/lib/request.h @@ -78,6 +78,7 @@ struct SingleRequest { first one */ curl_off_t offset; /* possible resume offset read from the Content-Range: header */ + int httpversion; /* Version in response (09, 10, 11, etc.) */ int httpcode; /* error code from the 'HTTP/1.? XXX' or 'RTSP/1.? XXX' line */ int keepon; From 98f67a6145b4c5b2cae1e29870e06d2878bf750f Mon Sep 17 00:00:00 2001 From: Stefan Eissing Date: Tue, 19 Mar 2024 16:06:40 +0100 Subject: [PATCH 490/509] http2, http3: only return CURLE_PARTIAL_FILE when bytes were received - should resolve spurious pytest failures when stream were reset right after response header were received Clsoes #13151 --- lib/http2.c | 4 ++-- lib/vquic/curl_ngtcp2.c | 2 +- lib/vquic/curl_osslq.c | 2 +- lib/vquic/curl_quiche.c | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/http2.c b/lib/http2.c index f3d4d2e1112..99d7f3b0e25 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -1666,7 +1666,7 @@ static ssize_t http2_handle_stream_close(struct Curl_cfilter *cf, } else if(stream->reset) { failf(data, "HTTP/2 stream %u was reset", stream->id); - *err = stream->bodystarted? CURLE_PARTIAL_FILE : CURLE_RECV_ERROR; + *err = data->req.bytecount? CURLE_PARTIAL_FILE : CURLE_HTTP2; return -1; } @@ -1807,7 +1807,7 @@ static ssize_t stream_recv(struct Curl_cfilter *cf, struct Curl_easy *data, (ctx->conn_closed && Curl_bufq_is_empty(&ctx->inbufq)) || (ctx->goaway && ctx->last_stream_id < stream->id)) { CURL_TRC_CF(data, cf, "[%d] returning ERR", stream->id); - *err = stream->bodystarted? CURLE_PARTIAL_FILE : CURLE_RECV_ERROR; + *err = data->req.bytecount? CURLE_PARTIAL_FILE : CURLE_HTTP2; nread = -1; } diff --git a/lib/vquic/curl_ngtcp2.c b/lib/vquic/curl_ngtcp2.c index 4f5da87ab9d..6b6b8874cff 100644 --- a/lib/vquic/curl_ngtcp2.c +++ b/lib/vquic/curl_ngtcp2.c @@ -1032,7 +1032,7 @@ static ssize_t recv_closed_stream(struct Curl_cfilter *cf, if(stream->reset) { failf(data, "HTTP/3 stream %" PRId64 " reset by server", stream->id); - *err = stream->resp_hds_complete? CURLE_PARTIAL_FILE : CURLE_HTTP3; + *err = data->req.bytecount? CURLE_PARTIAL_FILE : CURLE_HTTP3; goto out; } else if(!stream->resp_hds_complete) { diff --git a/lib/vquic/curl_osslq.c b/lib/vquic/curl_osslq.c index b638be3195b..1d53e2c11dc 100644 --- a/lib/vquic/curl_osslq.c +++ b/lib/vquic/curl_osslq.c @@ -1917,7 +1917,7 @@ static ssize_t recv_closed_stream(struct Curl_cfilter *cf, if(stream->reset) { failf(data, "HTTP/3 stream %" PRId64 " reset by server", stream->s.id); - *err = stream->resp_hds_complete? CURLE_PARTIAL_FILE : CURLE_HTTP3; + *err = data->req.bytecount? CURLE_PARTIAL_FILE : CURLE_HTTP3; goto out; } else if(!stream->resp_hds_complete) { diff --git a/lib/vquic/curl_quiche.c b/lib/vquic/curl_quiche.c index 0763c083a20..2ebc50c6759 100644 --- a/lib/vquic/curl_quiche.c +++ b/lib/vquic/curl_quiche.c @@ -732,7 +732,7 @@ static ssize_t recv_closed_stream(struct Curl_cfilter *cf, if(stream->reset) { failf(data, "HTTP/3 stream %" PRId64 " reset by server", stream->id); - *err = stream->resp_got_header? CURLE_PARTIAL_FILE : CURLE_HTTP3; + *err = data->req.bytecount? CURLE_PARTIAL_FILE : CURLE_HTTP3; CURL_TRC_CF(data, cf, "[%" PRId64 "] cf_recv, was reset -> %d", stream->id, *err); } From b935fd4a07aa9dc0fa352b0a1d4822c4d901577b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Mar 2024 11:50:20 +0100 Subject: [PATCH 491/509] docs: make each libcurl man specify protocol(s) The mandatory header now has a mandatory list of protocols for which the manpage is relevant. Most man pages already has a "PROTOCOLS" section, but this introduces a stricter way to specify the relevant protocols. cd2nroff verifies that at least one protocol is mentioned (which can be `*`). This information is not used just yet, but A) the PROTOCOLS section can now instead get generated and get a unified wording across all manpages and B) this allows us to more reliably filter/search for protocol specific manpages/options. Closes #13166 --- docs/CURLDOWN.md | 7 +++++++ docs/libcurl/curl_easy_cleanup.md | 2 ++ docs/libcurl/curl_easy_duphandle.md | 2 ++ docs/libcurl/curl_easy_escape.md | 2 ++ docs/libcurl/curl_easy_getinfo.md | 2 ++ docs/libcurl/curl_easy_header.md | 2 ++ docs/libcurl/curl_easy_init.md | 2 ++ docs/libcurl/curl_easy_nextheader.md | 2 ++ docs/libcurl/curl_easy_option_by_id.md | 2 ++ docs/libcurl/curl_easy_option_by_name.md | 2 ++ docs/libcurl/curl_easy_option_next.md | 2 ++ docs/libcurl/curl_easy_pause.md | 2 ++ docs/libcurl/curl_easy_perform.md | 2 ++ docs/libcurl/curl_easy_recv.md | 2 ++ docs/libcurl/curl_easy_reset.md | 2 ++ docs/libcurl/curl_easy_send.md | 2 ++ docs/libcurl/curl_easy_setopt.md | 2 ++ docs/libcurl/curl_easy_strerror.md | 2 ++ docs/libcurl/curl_easy_unescape.md | 2 ++ docs/libcurl/curl_easy_upkeep.md | 2 ++ docs/libcurl/curl_escape.md | 2 ++ docs/libcurl/curl_formadd.md | 2 ++ docs/libcurl/curl_formfree.md | 2 ++ docs/libcurl/curl_formget.md | 2 ++ docs/libcurl/curl_free.md | 2 ++ docs/libcurl/curl_getdate.md | 2 ++ docs/libcurl/curl_getenv.md | 2 ++ docs/libcurl/curl_global_cleanup.md | 2 ++ docs/libcurl/curl_global_init.md | 2 ++ docs/libcurl/curl_global_init_mem.md | 2 ++ docs/libcurl/curl_global_sslset.md | 2 ++ docs/libcurl/curl_global_trace.md | 2 ++ docs/libcurl/curl_mime_addpart.md | 4 ++++ docs/libcurl/curl_mime_data.md | 4 ++++ docs/libcurl/curl_mime_data_cb.md | 4 ++++ docs/libcurl/curl_mime_encoder.md | 4 ++++ docs/libcurl/curl_mime_filedata.md | 4 ++++ docs/libcurl/curl_mime_filename.md | 4 ++++ docs/libcurl/curl_mime_free.md | 4 ++++ docs/libcurl/curl_mime_headers.md | 4 ++++ docs/libcurl/curl_mime_init.md | 4 ++++ docs/libcurl/curl_mime_name.md | 4 ++++ docs/libcurl/curl_mime_subparts.md | 4 ++++ docs/libcurl/curl_mime_type.md | 4 ++++ docs/libcurl/curl_mprintf.md | 2 ++ docs/libcurl/curl_multi_add_handle.md | 2 ++ docs/libcurl/curl_multi_assign.md | 2 ++ docs/libcurl/curl_multi_cleanup.md | 2 ++ docs/libcurl/curl_multi_fdset.md | 2 ++ docs/libcurl/curl_multi_get_handles.md | 2 ++ docs/libcurl/curl_multi_info_read.md | 2 ++ docs/libcurl/curl_multi_init.md | 2 ++ docs/libcurl/curl_multi_perform.md | 2 ++ docs/libcurl/curl_multi_poll.md | 2 ++ docs/libcurl/curl_multi_remove_handle.md | 2 ++ docs/libcurl/curl_multi_setopt.md | 2 ++ docs/libcurl/curl_multi_socket.md | 2 ++ docs/libcurl/curl_multi_socket_action.md | 2 ++ docs/libcurl/curl_multi_socket_all.md | 2 ++ docs/libcurl/curl_multi_strerror.md | 2 ++ docs/libcurl/curl_multi_timeout.md | 2 ++ docs/libcurl/curl_multi_wait.md | 2 ++ docs/libcurl/curl_multi_wakeup.md | 2 ++ docs/libcurl/curl_pushheader_byname.md | 2 ++ docs/libcurl/curl_pushheader_bynum.md | 2 ++ docs/libcurl/curl_share_cleanup.md | 2 ++ docs/libcurl/curl_share_init.md | 2 ++ docs/libcurl/curl_share_setopt.md | 2 ++ docs/libcurl/curl_share_strerror.md | 2 ++ docs/libcurl/curl_slist_append.md | 2 ++ docs/libcurl/curl_slist_free_all.md | 2 ++ docs/libcurl/curl_strequal.md | 2 ++ docs/libcurl/curl_strnequal.md | 2 ++ docs/libcurl/curl_unescape.md | 2 ++ docs/libcurl/curl_url.md | 2 ++ docs/libcurl/curl_url_cleanup.md | 2 ++ docs/libcurl/curl_url_dup.md | 2 ++ docs/libcurl/curl_url_get.md | 2 ++ docs/libcurl/curl_url_set.md | 2 ++ docs/libcurl/curl_url_strerror.md | 2 ++ docs/libcurl/curl_version.md | 2 ++ docs/libcurl/curl_version_info.md | 2 ++ docs/libcurl/curl_ws_meta.md | 2 ++ docs/libcurl/curl_ws_recv.md | 2 ++ docs/libcurl/curl_ws_send.md | 2 ++ docs/libcurl/libcurl-easy.md | 2 ++ docs/libcurl/libcurl-env-dbg.md | 2 ++ docs/libcurl/libcurl-env.md | 2 ++ docs/libcurl/libcurl-errors.md | 2 ++ docs/libcurl/libcurl-multi.md | 2 ++ docs/libcurl/libcurl-security.md | 2 ++ docs/libcurl/libcurl-share.md | 2 ++ docs/libcurl/libcurl-thread.md | 2 ++ docs/libcurl/libcurl-tutorial.md | 2 ++ docs/libcurl/libcurl-url.md | 2 ++ docs/libcurl/libcurl-ws.md | 2 ++ docs/libcurl/libcurl.md | 2 ++ docs/libcurl/mksymbolsmanpage.pl | 2 ++ docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md | 2 ++ docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md | 2 ++ .../opts/CURLINFO_APPCONNECT_TIME_T.md | 2 ++ docs/libcurl/opts/CURLINFO_CAINFO.md | 2 ++ docs/libcurl/opts/CURLINFO_CAPATH.md | 2 ++ docs/libcurl/opts/CURLINFO_CERTINFO.md | 2 ++ docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md | 2 ++ docs/libcurl/opts/CURLINFO_CONNECT_TIME.md | 2 ++ docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md | 2 ++ docs/libcurl/opts/CURLINFO_CONN_ID.md | 2 ++ .../opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md | 2 ++ .../CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md | 2 ++ .../opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md | 2 ++ .../opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md | 2 ++ docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md | 2 ++ docs/libcurl/opts/CURLINFO_COOKIELIST.md | 2 ++ .../libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md | 2 ++ docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md | 2 ++ docs/libcurl/opts/CURLINFO_FILETIME.md | 4 ++++ docs/libcurl/opts/CURLINFO_FILETIME_T.md | 4 ++++ docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md | 2 ++ docs/libcurl/opts/CURLINFO_HEADER_SIZE.md | 2 ++ docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md | 2 ++ .../libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md | 2 ++ docs/libcurl/opts/CURLINFO_HTTP_VERSION.md | 2 ++ docs/libcurl/opts/CURLINFO_LASTSOCKET.md | 2 ++ docs/libcurl/opts/CURLINFO_LOCAL_IP.md | 2 ++ docs/libcurl/opts/CURLINFO_LOCAL_PORT.md | 2 ++ docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md | 2 ++ .../opts/CURLINFO_NAMELOOKUP_TIME_T.md | 2 ++ docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md | 2 ++ docs/libcurl/opts/CURLINFO_OS_ERRNO.md | 2 ++ .../libcurl/opts/CURLINFO_PRETRANSFER_TIME.md | 2 ++ .../opts/CURLINFO_PRETRANSFER_TIME_T.md | 2 ++ docs/libcurl/opts/CURLINFO_PRIMARY_IP.md | 2 ++ docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md | 2 ++ docs/libcurl/opts/CURLINFO_PRIVATE.md | 2 ++ docs/libcurl/opts/CURLINFO_PROTOCOL.md | 2 ++ docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md | 2 ++ docs/libcurl/opts/CURLINFO_PROXY_ERROR.md | 2 ++ .../opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md | 2 ++ docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md | 2 ++ docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md | 2 ++ docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md | 2 ++ docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md | 2 ++ docs/libcurl/opts/CURLINFO_REDIRECT_URL.md | 2 ++ docs/libcurl/opts/CURLINFO_REFERER.md | 2 ++ docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md | 2 ++ docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md | 5 +++++ docs/libcurl/opts/CURLINFO_RETRY_AFTER.md | 2 ++ .../libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md | 2 ++ docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md | 2 ++ .../libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md | 2 ++ docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md | 2 ++ docs/libcurl/opts/CURLINFO_SCHEME.md | 2 ++ docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md | 2 ++ docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md | 2 ++ docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md | 2 ++ docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md | 2 ++ docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md | 2 ++ .../libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md | 2 ++ docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md | 2 ++ docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md | 2 ++ docs/libcurl/opts/CURLINFO_SSL_ENGINES.md | 2 ++ .../libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md | 2 ++ .../opts/CURLINFO_STARTTRANSFER_TIME.md | 2 ++ .../opts/CURLINFO_STARTTRANSFER_TIME_T.md | 2 ++ docs/libcurl/opts/CURLINFO_TLS_SESSION.md | 2 ++ docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md | 2 ++ docs/libcurl/opts/CURLINFO_TOTAL_TIME.md | 2 ++ docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md | 3 ++- docs/libcurl/opts/CURLINFO_USED_PROXY.md | 2 ++ docs/libcurl/opts/CURLINFO_XFER_ID.md | 2 ++ .../CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md | 2 ++ .../CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md | 2 ++ docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md | 2 ++ .../opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md | 2 ++ .../opts/CURLMOPT_MAX_HOST_CONNECTIONS.md | 2 ++ .../opts/CURLMOPT_MAX_PIPELINE_LENGTH.md | 2 ++ .../opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md | 2 ++ docs/libcurl/opts/CURLMOPT_PIPELINING.md | 2 ++ .../opts/CURLMOPT_PIPELINING_SERVER_BL.md | 2 ++ .../opts/CURLMOPT_PIPELINING_SITE_BL.md | 2 ++ docs/libcurl/opts/CURLMOPT_PUSHDATA.md | 2 ++ docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md | 2 ++ docs/libcurl/opts/CURLMOPT_SOCKETDATA.md | 2 ++ docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 2 ++ docs/libcurl/opts/CURLMOPT_TIMERDATA.md | 2 ++ docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md | 2 ++ .../opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md | 2 ++ docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md | 2 ++ docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md | 2 ++ docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md | 2 ++ docs/libcurl/opts/CURLOPT_ALTSVC.md | 2 ++ docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md | 2 ++ docs/libcurl/opts/CURLOPT_APPEND.md | 2 ++ docs/libcurl/opts/CURLOPT_AUTOREFERER.md | 2 ++ docs/libcurl/opts/CURLOPT_AWS_SIGV4.md | 2 ++ docs/libcurl/opts/CURLOPT_BUFFERSIZE.md | 2 ++ docs/libcurl/opts/CURLOPT_CAINFO.md | 2 ++ docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md | 2 ++ docs/libcurl/opts/CURLOPT_CAPATH.md | 2 ++ docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md | 2 ++ docs/libcurl/opts/CURLOPT_CERTINFO.md | 2 ++ .../opts/CURLOPT_CHUNK_BGN_FUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_CHUNK_DATA.md | 2 ++ .../opts/CURLOPT_CHUNK_END_FUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md | 2 ++ .../opts/CURLOPT_CLOSESOCKETFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md | 2 ++ .../libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md | 2 ++ docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md | 2 ++ docs/libcurl/opts/CURLOPT_CONNECT_TO.md | 2 ++ .../CURLOPT_CONV_FROM_NETWORK_FUNCTION.md | 2 ++ .../opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md | 2 ++ .../opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_COOKIE.md | 2 ++ docs/libcurl/opts/CURLOPT_COOKIEFILE.md | 2 ++ docs/libcurl/opts/CURLOPT_COOKIEJAR.md | 2 ++ docs/libcurl/opts/CURLOPT_COOKIELIST.md | 2 ++ docs/libcurl/opts/CURLOPT_COOKIESESSION.md | 2 ++ docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md | 2 ++ docs/libcurl/opts/CURLOPT_CRLF.md | 2 ++ docs/libcurl/opts/CURLOPT_CRLFILE.md | 2 ++ docs/libcurl/opts/CURLOPT_CURLU.md | 2 ++ docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md | 6 ++++++ docs/libcurl/opts/CURLOPT_DEBUGDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md | 2 ++ docs/libcurl/opts/CURLOPT_DIRLISTONLY.md | 4 ++++ .../opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md | 2 ++ .../libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md | 2 ++ docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md | 2 ++ docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md | 2 ++ docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md | 2 ++ docs/libcurl/opts/CURLOPT_DNS_SERVERS.md | 2 ++ .../opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md | 2 ++ .../opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md | 2 ++ .../opts/CURLOPT_DOH_SSL_VERIFYHOST.md | 2 ++ .../opts/CURLOPT_DOH_SSL_VERIFYPEER.md | 2 ++ .../opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md | 2 ++ docs/libcurl/opts/CURLOPT_DOH_URL.md | 2 ++ docs/libcurl/opts/CURLOPT_EGDSOCKET.md | 2 ++ docs/libcurl/opts/CURLOPT_ERRORBUFFER.md | 2 ++ .../opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md | 2 ++ docs/libcurl/opts/CURLOPT_FAILONERROR.md | 2 ++ docs/libcurl/opts/CURLOPT_FILETIME.md | 6 ++++++ docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md | 2 ++ docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md | 2 ++ docs/libcurl/opts/CURLOPT_FORBID_REUSE.md | 2 ++ docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md | 2 ++ docs/libcurl/opts/CURLOPT_FTPPORT.md | 2 ++ docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md | 2 ++ docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md | 2 ++ .../opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md | 2 ++ .../opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md | 2 ++ docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md | 2 ++ docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md | 2 ++ docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md | 2 ++ docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md | 2 ++ docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md | 2 ++ docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md | 2 ++ .../libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md | 2 ++ .../opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md | 2 ++ docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md | 2 ++ .../libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md | 2 ++ docs/libcurl/opts/CURLOPT_HEADER.md | 6 ++++++ docs/libcurl/opts/CURLOPT_HEADERDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md | 6 ++++++ docs/libcurl/opts/CURLOPT_HEADEROPT.md | 2 ++ docs/libcurl/opts/CURLOPT_HSTS.md | 2 ++ docs/libcurl/opts/CURLOPT_HSTSREADDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md | 2 ++ .../libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_HSTS_CTRL.md | 2 ++ docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md | 2 ++ docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md | 2 ++ docs/libcurl/opts/CURLOPT_HTTPAUTH.md | 2 ++ docs/libcurl/opts/CURLOPT_HTTPGET.md | 2 ++ docs/libcurl/opts/CURLOPT_HTTPHEADER.md | 4 ++++ docs/libcurl/opts/CURLOPT_HTTPPOST.md | 2 ++ docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md | 2 ++ .../opts/CURLOPT_HTTP_CONTENT_DECODING.md | 2 ++ .../opts/CURLOPT_HTTP_TRANSFER_DECODING.md | 2 ++ docs/libcurl/opts/CURLOPT_HTTP_VERSION.md | 2 ++ .../opts/CURLOPT_IGNORE_CONTENT_LENGTH.md | 3 +++ docs/libcurl/opts/CURLOPT_INFILESIZE.md | 2 ++ docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md | 2 ++ docs/libcurl/opts/CURLOPT_INTERFACE.md | 2 ++ docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md | 2 ++ .../opts/CURLOPT_INTERLEAVEFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_IOCTLDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_IPRESOLVE.md | 2 ++ docs/libcurl/opts/CURLOPT_ISSUERCERT.md | 2 ++ docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md | 2 ++ .../opts/CURLOPT_KEEP_SENDING_ON_ERROR.md | 2 ++ docs/libcurl/opts/CURLOPT_KEYPASSWD.md | 2 ++ docs/libcurl/opts/CURLOPT_KRBLEVEL.md | 2 ++ docs/libcurl/opts/CURLOPT_LOCALPORT.md | 2 ++ docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md | 2 ++ docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md | 5 +++++ docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md | 2 ++ docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md | 2 ++ docs/libcurl/opts/CURLOPT_MAIL_AUTH.md | 2 ++ docs/libcurl/opts/CURLOPT_MAIL_FROM.md | 2 ++ docs/libcurl/opts/CURLOPT_MAIL_RCPT.md | 2 ++ .../opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md | 2 ++ docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md | 2 ++ docs/libcurl/opts/CURLOPT_MAXCONNECTS.md | 2 ++ docs/libcurl/opts/CURLOPT_MAXFILESIZE.md | 2 ++ .../libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md | 4 ++++ docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md | 2 ++ docs/libcurl/opts/CURLOPT_MAXREDIRS.md | 2 ++ .../opts/CURLOPT_MAX_RECV_SPEED_LARGE.md | 2 ++ .../opts/CURLOPT_MAX_SEND_SPEED_LARGE.md | 2 ++ docs/libcurl/opts/CURLOPT_MIMEPOST.md | 4 ++++ docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md | 4 ++++ docs/libcurl/opts/CURLOPT_NETRC.md | 2 ++ docs/libcurl/opts/CURLOPT_NETRC_FILE.md | 2 ++ .../opts/CURLOPT_NEW_DIRECTORY_PERMS.md | 4 ++++ docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md | 4 ++++ docs/libcurl/opts/CURLOPT_NOBODY.md | 2 ++ docs/libcurl/opts/CURLOPT_NOPROGRESS.md | 2 ++ docs/libcurl/opts/CURLOPT_NOPROXY.md | 2 ++ docs/libcurl/opts/CURLOPT_NOSIGNAL.md | 2 ++ docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md | 2 ++ .../opts/CURLOPT_OPENSOCKETFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_PASSWORD.md | 2 ++ docs/libcurl/opts/CURLOPT_PATH_AS_IS.md | 2 ++ docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md | 2 ++ docs/libcurl/opts/CURLOPT_PIPEWAIT.md | 2 ++ docs/libcurl/opts/CURLOPT_PORT.md | 2 ++ docs/libcurl/opts/CURLOPT_POST.md | 2 ++ docs/libcurl/opts/CURLOPT_POSTFIELDS.md | 2 ++ docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md | 2 ++ .../opts/CURLOPT_POSTFIELDSIZE_LARGE.md | 2 ++ docs/libcurl/opts/CURLOPT_POSTQUOTE.md | 3 +++ docs/libcurl/opts/CURLOPT_POSTREDIR.md | 2 ++ docs/libcurl/opts/CURLOPT_PREQUOTE.md | 2 ++ docs/libcurl/opts/CURLOPT_PREREQDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_PRE_PROXY.md | 2 ++ docs/libcurl/opts/CURLOPT_PRIVATE.md | 2 ++ docs/libcurl/opts/CURLOPT_PROGRESSDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_PROTOCOLS.md | 2 ++ docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXYAUTH.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXYHEADER.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXYPORT.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXYTYPE.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md | 2 ++ .../libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md | 2 ++ .../opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md | 2 ++ .../opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md | 2 ++ .../opts/CURLOPT_PROXY_SERVICE_NAME.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md | 2 ++ .../libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md | 2 ++ .../opts/CURLOPT_PROXY_SSLCERT_BLOB.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md | 2 ++ .../libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md | 2 ++ docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md | 2 ++ .../opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md | 2 ++ .../libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md | 2 ++ .../opts/CURLOPT_PROXY_SSL_VERIFYHOST.md | 2 ++ .../opts/CURLOPT_PROXY_SSL_VERIFYPEER.md | 2 ++ .../opts/CURLOPT_PROXY_TLS13_CIPHERS.md | 2 ++ .../opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md | 2 ++ .../opts/CURLOPT_PROXY_TLSAUTH_TYPE.md | 2 ++ .../opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md | 2 ++ .../opts/CURLOPT_PROXY_TRANSFER_MODE.md | 2 ++ docs/libcurl/opts/CURLOPT_PUT.md | 2 ++ docs/libcurl/opts/CURLOPT_QUICK_EXIT.md | 2 ++ docs/libcurl/opts/CURLOPT_QUOTE.md | 3 +++ docs/libcurl/opts/CURLOPT_RANDOM_FILE.md | 2 ++ docs/libcurl/opts/CURLOPT_RANGE.md | 6 ++++++ docs/libcurl/opts/CURLOPT_READDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_READFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md | 2 ++ .../opts/CURLOPT_REDIR_PROTOCOLS_STR.md | 2 ++ docs/libcurl/opts/CURLOPT_REFERER.md | 2 ++ docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md | 2 ++ docs/libcurl/opts/CURLOPT_RESOLVE.md | 2 ++ .../opts/CURLOPT_RESOLVER_START_DATA.md | 2 ++ .../opts/CURLOPT_RESOLVER_START_FUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_RESUME_FROM.md | 2 ++ .../libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md | 2 ++ docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md | 2 ++ docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md | 2 ++ docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md | 2 ++ docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md | 2 ++ docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md | 2 ++ docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md | 2 ++ docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md | 2 ++ docs/libcurl/opts/CURLOPT_SASL_IR.md | 3 +++ docs/libcurl/opts/CURLOPT_SEEKDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md | 2 ++ .../opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md | 7 +++++++ .../CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md | 7 +++++++ docs/libcurl/opts/CURLOPT_SERVICE_NAME.md | 2 ++ docs/libcurl/opts/CURLOPT_SHARE.md | 2 ++ docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md | 2 ++ .../libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md | 2 ++ .../opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md | 2 ++ docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md | 3 +++ docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md | 3 +++ docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md | 3 +++ .../opts/CURLOPT_SSH_HOSTKEYFUNCTION.md | 3 +++ .../opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md | 3 +++ .../CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md | 3 +++ docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md | 3 +++ docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md | 3 +++ .../opts/CURLOPT_SSH_PRIVATE_KEYFILE.md | 3 +++ .../opts/CURLOPT_SSH_PUBLIC_KEYFILE.md | 3 +++ docs/libcurl/opts/CURLOPT_SSLCERT.md | 2 ++ docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md | 2 ++ docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md | 2 ++ docs/libcurl/opts/CURLOPT_SSLENGINE.md | 2 ++ .../libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md | 2 ++ docs/libcurl/opts/CURLOPT_SSLKEY.md | 2 ++ docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md | 2 ++ docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md | 2 ++ docs/libcurl/opts/CURLOPT_SSLVERSION.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md | 2 ++ .../opts/CURLOPT_SSL_SESSIONID_CACHE.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md | 2 ++ docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md | 2 ++ docs/libcurl/opts/CURLOPT_STDERR.md | 2 ++ docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md | 2 ++ docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md | 2 ++ docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md | 2 ++ .../opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md | 2 ++ docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md | 2 ++ docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md | 2 ++ docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md | 2 ++ docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md | 2 ++ docs/libcurl/opts/CURLOPT_TCP_NODELAY.md | 2 ++ docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md | 2 ++ docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md | 2 ++ docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md | 2 ++ docs/libcurl/opts/CURLOPT_TIMECONDITION.md | 2 ++ docs/libcurl/opts/CURLOPT_TIMEOUT.md | 2 ++ docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md | 2 ++ docs/libcurl/opts/CURLOPT_TIMEVALUE.md | 2 ++ docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md | 2 ++ docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md | 2 ++ docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md | 2 ++ docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md | 2 ++ docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md | 2 ++ docs/libcurl/opts/CURLOPT_TRAILERDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md | 2 ++ .../libcurl/opts/CURLOPT_TRANSFER_ENCODING.md | 2 ++ docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md | 2 ++ .../libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md | 2 ++ .../opts/CURLOPT_UPKEEP_INTERVAL_MS.md | 2 ++ docs/libcurl/opts/CURLOPT_UPLOAD.md | 2 ++ .../libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md | 2 ++ docs/libcurl/opts/CURLOPT_URL.md | 2 ++ docs/libcurl/opts/CURLOPT_USERAGENT.md | 2 ++ docs/libcurl/opts/CURLOPT_USERNAME.md | 2 ++ docs/libcurl/opts/CURLOPT_USERPWD.md | 2 ++ docs/libcurl/opts/CURLOPT_USE_SSL.md | 5 +++++ docs/libcurl/opts/CURLOPT_VERBOSE.md | 2 ++ docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md | 2 ++ docs/libcurl/opts/CURLOPT_WRITEDATA.md | 2 ++ docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_WS_OPTIONS.md | 2 ++ docs/libcurl/opts/CURLOPT_XFERINFODATA.md | 2 ++ docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md | 2 ++ docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md | 6 ++++++ docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md | 2 ++ docs/libcurl/opts/CURLSHOPT_SHARE.md | 2 ++ docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md | 2 ++ docs/libcurl/opts/CURLSHOPT_UNSHARE.md | 2 ++ docs/libcurl/opts/CURLSHOPT_USERDATA.md | 2 ++ scripts/cd2nroff | 20 ++++++++++++++++++- 498 files changed, 1117 insertions(+), 2 deletions(-) diff --git a/docs/CURLDOWN.md b/docs/CURLDOWN.md index 8440ef447d2..bcb53076307 100644 --- a/docs/CURLDOWN.md +++ b/docs/CURLDOWN.md @@ -67,6 +67,8 @@ Each curldown starts with a header with meta-data: Title: CURLOPT_AWS_SIGV4 Section: 3 Source: libcurl + Protocol: + - HTTP See-also: - CURLOPT_HEADEROPT (3) - CURLOPT_HTTPAUTH (3) @@ -75,6 +77,11 @@ Each curldown starts with a header with meta-data: 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) or `TLS`. + Following the header in the file, is the manual page using markdown-like syntax: diff --git a/docs/libcurl/curl_easy_cleanup.md b/docs/libcurl/curl_easy_cleanup.md index 3175d0b7cef..c91af97df10 100644 --- a/docs/libcurl/curl_easy_cleanup.md +++ b/docs/libcurl/curl_easy_cleanup.md @@ -10,6 +10,8 @@ See-also: - curl_easy_reset (3) - curl_multi_cleanup (3) - curl_multi_remove_handle (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_duphandle.md b/docs/libcurl/curl_easy_duphandle.md index babc222ef41..17a0bc7f6cf 100644 --- a/docs/libcurl/curl_easy_duphandle.md +++ b/docs/libcurl/curl_easy_duphandle.md @@ -9,6 +9,8 @@ See-also: - curl_easy_init (3) - curl_easy_reset (3) - curl_global_init (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_escape.md b/docs/libcurl/curl_easy_escape.md index 9ab8f3a679d..5a84ed2eb14 100644 --- a/docs/libcurl/curl_easy_escape.md +++ b/docs/libcurl/curl_easy_escape.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_easy_unescape (3) - curl_free (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_getinfo.md b/docs/libcurl/curl_easy_getinfo.md index 8076dc84c80..33c6d80e69e 100644 --- a/docs/libcurl/curl_easy_getinfo.md +++ b/docs/libcurl/curl_easy_getinfo.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_header.md b/docs/libcurl/curl_easy_header.md index ff3699b94ce..6bc74343672 100644 --- a/docs/libcurl/curl_easy_header.md +++ b/docs/libcurl/curl_easy_header.md @@ -10,6 +10,8 @@ See-also: - curl_easy_nextheader (3) - curl_easy_perform (3) - libcurl-errors (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/curl_easy_init.md b/docs/libcurl/curl_easy_init.md index c51e8c40d1a..68d42a9300d 100644 --- a/docs/libcurl/curl_easy_init.md +++ b/docs/libcurl/curl_easy_init.md @@ -11,6 +11,8 @@ See-also: - curl_easy_reset (3) - curl_global_init (3) - curl_multi_init (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_nextheader.md b/docs/libcurl/curl_easy_nextheader.md index f7057af7f82..683a9d9d125 100644 --- a/docs/libcurl/curl_easy_nextheader.md +++ b/docs/libcurl/curl_easy_nextheader.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_easy_header (3) - curl_easy_perform (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/curl_easy_option_by_id.md b/docs/libcurl/curl_easy_option_by_id.md index 99ebb3461cc..2c3f696fbb9 100644 --- a/docs/libcurl/curl_easy_option_by_id.md +++ b/docs/libcurl/curl_easy_option_by_id.md @@ -8,6 +8,8 @@ See-also: - curl_easy_option_by_name (3) - curl_easy_option_next (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_option_by_name.md b/docs/libcurl/curl_easy_option_by_name.md index 401fc02ff11..76a8083051d 100644 --- a/docs/libcurl/curl_easy_option_by_name.md +++ b/docs/libcurl/curl_easy_option_by_name.md @@ -8,6 +8,8 @@ See-also: - curl_easy_option_by_id (3) - curl_easy_option_next (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_option_next.md b/docs/libcurl/curl_easy_option_next.md index d231c806846..fcb6faf9d9f 100644 --- a/docs/libcurl/curl_easy_option_next.md +++ b/docs/libcurl/curl_easy_option_next.md @@ -8,6 +8,8 @@ See-also: - curl_easy_option_by_id (3) - curl_easy_option_by_name (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_pause.md b/docs/libcurl/curl_easy_pause.md index ce3681a6395..61230aed104 100644 --- a/docs/libcurl/curl_easy_pause.md +++ b/docs/libcurl/curl_easy_pause.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_easy_cleanup (3) - curl_easy_reset (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_perform.md b/docs/libcurl/curl_easy_perform.md index 23320201da9..443be532e3e 100644 --- a/docs/libcurl/curl_easy_perform.md +++ b/docs/libcurl/curl_easy_perform.md @@ -10,6 +10,8 @@ See-also: - curl_multi_add_handle (3) - curl_multi_perform (3) - libcurl-errors (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_recv.md b/docs/libcurl/curl_easy_recv.md index 249362c0601..950290a3a4c 100644 --- a/docs/libcurl/curl_easy_recv.md +++ b/docs/libcurl/curl_easy_recv.md @@ -9,6 +9,8 @@ See-also: - curl_easy_perform (3) - curl_easy_send (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_reset.md b/docs/libcurl/curl_easy_reset.md index a74eb7fef61..0e2e1b0870c 100644 --- a/docs/libcurl/curl_easy_reset.md +++ b/docs/libcurl/curl_easy_reset.md @@ -9,6 +9,8 @@ See-also: - curl_easy_duphandle (3) - curl_easy_init (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_send.md b/docs/libcurl/curl_easy_send.md index edeb65c5397..a0bd68e3455 100644 --- a/docs/libcurl/curl_easy_send.md +++ b/docs/libcurl/curl_easy_send.md @@ -9,6 +9,8 @@ See-also: - curl_easy_perform (3) - curl_easy_recv (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_setopt.md b/docs/libcurl/curl_easy_setopt.md index 843673a6218..582c461d4dd 100644 --- a/docs/libcurl/curl_easy_setopt.md +++ b/docs/libcurl/curl_easy_setopt.md @@ -13,6 +13,8 @@ See-also: - curl_easy_option_next (3) - curl_easy_reset (3) - curl_multi_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_strerror.md b/docs/libcurl/curl_easy_strerror.md index 265efc05148..d55c42a79ce 100644 --- a/docs/libcurl/curl_easy_strerror.md +++ b/docs/libcurl/curl_easy_strerror.md @@ -9,6 +9,8 @@ See-also: - curl_share_strerror (3) - curl_url_strerror (3) - libcurl-errors (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_unescape.md b/docs/libcurl/curl_easy_unescape.md index e397a1afa0c..ee0ab9b1fb4 100644 --- a/docs/libcurl/curl_easy_unescape.md +++ b/docs/libcurl/curl_easy_unescape.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_easy_escape (3) - curl_free (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_easy_upkeep.md b/docs/libcurl/curl_easy_upkeep.md index fd27f1042ed..a05e80909f4 100644 --- a/docs/libcurl/curl_easy_upkeep.md +++ b/docs/libcurl/curl_easy_upkeep.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TCP_KEEPIDLE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_escape.md b/docs/libcurl/curl_escape.md index 1c06ab9f516..3d29c310ddc 100644 --- a/docs/libcurl/curl_escape.md +++ b/docs/libcurl/curl_escape.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_free (3) - curl_unescape (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_formadd.md b/docs/libcurl/curl_formadd.md index 7cd89165ac0..0aefb26ee7f 100644 --- a/docs/libcurl/curl_formadd.md +++ b/docs/libcurl/curl_formadd.md @@ -8,6 +8,8 @@ See-also: - curl_easy_setopt (3) - curl_formfree (3) - curl_mime_init (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/curl_formfree.md b/docs/libcurl/curl_formfree.md index 65ff0e02926..1e0db8417d5 100644 --- a/docs/libcurl/curl_formfree.md +++ b/docs/libcurl/curl_formfree.md @@ -8,6 +8,8 @@ See-also: - curl_formadd (3) - curl_mime_free (3) - curl_mime_init (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/curl_formget.md b/docs/libcurl/curl_formget.md index 6da9b0d69ec..2ec8d119ccb 100644 --- a/docs/libcurl/curl_formget.md +++ b/docs/libcurl/curl_formget.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_formadd (3) - curl_mime_init (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/curl_free.md b/docs/libcurl/curl_free.md index d1a26b79528..7b1f706a884 100644 --- a/docs/libcurl/curl_free.md +++ b/docs/libcurl/curl_free.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_easy_escape (3) - curl_easy_unescape (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_getdate.md b/docs/libcurl/curl_getdate.md index 0a5ba446cce..f0bfea76fdb 100644 --- a/docs/libcurl/curl_getdate.md +++ b/docs/libcurl/curl_getdate.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_TIMEVALUE (3) - curl_easy_escape (3) - curl_easy_unescape (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_getenv.md b/docs/libcurl/curl_getenv.md index f4c72156dc1..a334479a4ff 100644 --- a/docs/libcurl/curl_getenv.md +++ b/docs/libcurl/curl_getenv.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - getenv (3C) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_global_cleanup.md b/docs/libcurl/curl_global_cleanup.md index ae2380aac54..3ae162a1add 100644 --- a/docs/libcurl/curl_global_cleanup.md +++ b/docs/libcurl/curl_global_cleanup.md @@ -8,6 +8,8 @@ See-also: - curl_global_init (3) - libcurl (3) - libcurl-thread (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_global_init.md b/docs/libcurl/curl_global_init.md index 7382369f930..84a081742a8 100644 --- a/docs/libcurl/curl_global_init.md +++ b/docs/libcurl/curl_global_init.md @@ -11,6 +11,8 @@ See-also: - curl_global_sslset (3) - curl_global_trace (3) - libcurl (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_global_init_mem.md b/docs/libcurl/curl_global_init_mem.md index edc7563560e..7a2c5b54f69 100644 --- a/docs/libcurl/curl_global_init_mem.md +++ b/docs/libcurl/curl_global_init_mem.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_global_cleanup (3) - curl_global_init (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_global_sslset.md b/docs/libcurl/curl_global_sslset.md index 25dde166bd6..14f05a75e8c 100644 --- a/docs/libcurl/curl_global_sslset.md +++ b/docs/libcurl/curl_global_sslset.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_global_init (3) - libcurl (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_global_trace.md b/docs/libcurl/curl_global_trace.md index 2b27401b389..5d9e8d5eaa6 100644 --- a/docs/libcurl/curl_global_trace.md +++ b/docs/libcurl/curl_global_trace.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_global_init (3) - libcurl (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_mime_addpart.md b/docs/libcurl/curl_mime_addpart.md index dc11f10ccc5..53aea78b812 100644 --- a/docs/libcurl/curl_mime_addpart.md +++ b/docs/libcurl/curl_mime_addpart.md @@ -15,6 +15,10 @@ See-also: - curl_mime_name (3) - curl_mime_subparts (3) - curl_mime_type (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_data.md b/docs/libcurl/curl_mime_data.md index 0733d01479e..a7f0571a9d4 100644 --- a/docs/libcurl/curl_mime_data.md +++ b/docs/libcurl/curl_mime_data.md @@ -9,6 +9,10 @@ See-also: - curl_mime_data_cb (3) - curl_mime_name (3) - curl_mime_type (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_data_cb.md b/docs/libcurl/curl_mime_data_cb.md index e17866b95d1..e63ae42f20d 100644 --- a/docs/libcurl/curl_mime_data_cb.md +++ b/docs/libcurl/curl_mime_data_cb.md @@ -9,6 +9,10 @@ See-also: - curl_mime_addpart (3) - curl_mime_data (3) - curl_mime_name (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_encoder.md b/docs/libcurl/curl_mime_encoder.md index 54850654735..8bd6bbdf24d 100644 --- a/docs/libcurl/curl_mime_encoder.md +++ b/docs/libcurl/curl_mime_encoder.md @@ -8,6 +8,10 @@ See-also: - curl_mime_addpart (3) - curl_mime_headers (3) - curl_mime_subparts (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_filedata.md b/docs/libcurl/curl_mime_filedata.md index 81441e39487..3f46409115e 100644 --- a/docs/libcurl/curl_mime_filedata.md +++ b/docs/libcurl/curl_mime_filedata.md @@ -9,6 +9,10 @@ See-also: - curl_mime_data (3) - curl_mime_filename (3) - curl_mime_name (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_filename.md b/docs/libcurl/curl_mime_filename.md index 234fd2c6194..d642a6683f7 100644 --- a/docs/libcurl/curl_mime_filename.md +++ b/docs/libcurl/curl_mime_filename.md @@ -8,6 +8,10 @@ See-also: - curl_mime_addpart (3) - curl_mime_data (3) - curl_mime_filedata (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_free.md b/docs/libcurl/curl_mime_free.md index 5b352dfbabe..92106c33bd4 100644 --- a/docs/libcurl/curl_mime_free.md +++ b/docs/libcurl/curl_mime_free.md @@ -7,6 +7,10 @@ Source: libcurl See-also: - curl_free (3) - curl_mime_init (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_headers.md b/docs/libcurl/curl_mime_headers.md index 21d08986c2a..77669ac5906 100644 --- a/docs/libcurl/curl_mime_headers.md +++ b/docs/libcurl/curl_mime_headers.md @@ -7,6 +7,10 @@ Source: libcurl See-also: - curl_mime_addpart (3) - curl_mime_name (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_init.md b/docs/libcurl/curl_mime_init.md index db905c70482..6702021ad0e 100644 --- a/docs/libcurl/curl_mime_init.md +++ b/docs/libcurl/curl_mime_init.md @@ -9,6 +9,10 @@ See-also: - curl_mime_addpart (3) - curl_mime_free (3) - curl_mime_subparts (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_name.md b/docs/libcurl/curl_mime_name.md index 3482a655573..7f0d308f463 100644 --- a/docs/libcurl/curl_mime_name.md +++ b/docs/libcurl/curl_mime_name.md @@ -8,6 +8,10 @@ See-also: - curl_mime_addpart (3) - curl_mime_data (3) - curl_mime_type (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_subparts.md b/docs/libcurl/curl_mime_subparts.md index 8fb3f3ecad0..9c57297afad 100644 --- a/docs/libcurl/curl_mime_subparts.md +++ b/docs/libcurl/curl_mime_subparts.md @@ -7,6 +7,10 @@ Source: libcurl See-also: - curl_mime_addpart (3) - curl_mime_init (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mime_type.md b/docs/libcurl/curl_mime_type.md index 14cf4ca1dea..59ac01950bc 100644 --- a/docs/libcurl/curl_mime_type.md +++ b/docs/libcurl/curl_mime_type.md @@ -8,6 +8,10 @@ See-also: - curl_mime_addpart (3) - curl_mime_data (3) - curl_mime_name (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/curl_mprintf.md b/docs/libcurl/curl_mprintf.md index 658a2deff50..b5afa896b8a 100644 --- a/docs/libcurl/curl_mprintf.md +++ b/docs/libcurl/curl_mprintf.md @@ -9,6 +9,8 @@ See-also: - printf (3) - sprintf (3) - vprintf (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_add_handle.md b/docs/libcurl/curl_multi_add_handle.md index ab03bdd44f0..cca2a693e31 100644 --- a/docs/libcurl/curl_multi_add_handle.md +++ b/docs/libcurl/curl_multi_add_handle.md @@ -10,6 +10,8 @@ See-also: - curl_multi_init (3) - curl_multi_setopt (3) - curl_multi_socket_action (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_assign.md b/docs/libcurl/curl_multi_assign.md index aa8d1bf5e7a..e58bc2283e5 100644 --- a/docs/libcurl/curl_multi_assign.md +++ b/docs/libcurl/curl_multi_assign.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_multi_setopt (3) - curl_multi_socket_action (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_cleanup.md b/docs/libcurl/curl_multi_cleanup.md index ed2b29a71a1..767b07b2f7b 100644 --- a/docs/libcurl/curl_multi_cleanup.md +++ b/docs/libcurl/curl_multi_cleanup.md @@ -9,6 +9,8 @@ See-also: - curl_easy_init (3) - curl_multi_get_handles (3) - curl_multi_init (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_fdset.md b/docs/libcurl/curl_multi_fdset.md index bcdf15a83f5..fa808b85583 100644 --- a/docs/libcurl/curl_multi_fdset.md +++ b/docs/libcurl/curl_multi_fdset.md @@ -11,6 +11,8 @@ See-also: - curl_multi_timeout (3) - curl_multi_wait (3) - select (2) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_get_handles.md b/docs/libcurl/curl_multi_get_handles.md index de127bcc5ea..e4bcfc332a6 100644 --- a/docs/libcurl/curl_multi_get_handles.md +++ b/docs/libcurl/curl_multi_get_handles.md @@ -9,6 +9,8 @@ See-also: - curl_multi_cleanup (3) - curl_multi_init (3) - curl_multi_remove_handle (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_info_read.md b/docs/libcurl/curl_multi_info_read.md index f4b05bb73dd..adb93ba5123 100644 --- a/docs/libcurl/curl_multi_info_read.md +++ b/docs/libcurl/curl_multi_info_read.md @@ -8,6 +8,8 @@ See-also: - curl_multi_cleanup (3) - curl_multi_init (3) - curl_multi_perform (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_init.md b/docs/libcurl/curl_multi_init.md index c022c4416d6..5462666de72 100644 --- a/docs/libcurl/curl_multi_init.md +++ b/docs/libcurl/curl_multi_init.md @@ -10,6 +10,8 @@ See-also: - curl_multi_add_handle (3) - curl_multi_cleanup (3) - curl_multi_get_handles (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_perform.md b/docs/libcurl/curl_multi_perform.md index 6c27eaf9cc8..de5b4207ba7 100644 --- a/docs/libcurl/curl_multi_perform.md +++ b/docs/libcurl/curl_multi_perform.md @@ -12,6 +12,8 @@ See-also: - curl_multi_init (3) - curl_multi_wait (3) - libcurl-errors (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_poll.md b/docs/libcurl/curl_multi_poll.md index 7eadebc0eec..d76545af1d8 100644 --- a/docs/libcurl/curl_multi_poll.md +++ b/docs/libcurl/curl_multi_poll.md @@ -9,6 +9,8 @@ See-also: - curl_multi_perform (3) - curl_multi_wait (3) - curl_multi_wakeup (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_remove_handle.md b/docs/libcurl/curl_multi_remove_handle.md index da817cadb7f..db9490a0a24 100644 --- a/docs/libcurl/curl_multi_remove_handle.md +++ b/docs/libcurl/curl_multi_remove_handle.md @@ -8,6 +8,8 @@ See-also: - curl_multi_add_handle (3) - curl_multi_cleanup (3) - curl_multi_init (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_setopt.md b/docs/libcurl/curl_multi_setopt.md index 27f6dd4bec4..75075b4c560 100644 --- a/docs/libcurl/curl_multi_setopt.md +++ b/docs/libcurl/curl_multi_setopt.md @@ -9,6 +9,8 @@ See-also: - curl_multi_info_read (3) - curl_multi_init (3) - curl_multi_socket (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_socket.md b/docs/libcurl/curl_multi_socket.md index fe376834b19..78ad91c0f05 100644 --- a/docs/libcurl/curl_multi_socket.md +++ b/docs/libcurl/curl_multi_socket.md @@ -10,6 +10,8 @@ See-also: - curl_multi_info_read (3) - curl_multi_init (3) - the hiperfifo.c example +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_socket_action.md b/docs/libcurl/curl_multi_socket_action.md index 21880650753..9d989a459b2 100644 --- a/docs/libcurl/curl_multi_socket_action.md +++ b/docs/libcurl/curl_multi_socket_action.md @@ -10,6 +10,8 @@ See-also: - curl_multi_info_read (3) - curl_multi_init (3) - the hiperfifo.c example +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_socket_all.md b/docs/libcurl/curl_multi_socket_all.md index fe376834b19..78ad91c0f05 100644 --- a/docs/libcurl/curl_multi_socket_all.md +++ b/docs/libcurl/curl_multi_socket_all.md @@ -10,6 +10,8 @@ See-also: - curl_multi_info_read (3) - curl_multi_init (3) - the hiperfifo.c example +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_strerror.md b/docs/libcurl/curl_multi_strerror.md index 590af13a3a5..be0710715bb 100644 --- a/docs/libcurl/curl_multi_strerror.md +++ b/docs/libcurl/curl_multi_strerror.md @@ -9,6 +9,8 @@ See-also: - curl_share_strerror (3) - curl_url_strerror (3) - libcurl-errors (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_timeout.md b/docs/libcurl/curl_multi_timeout.md index a8693d1c4fa..9a33d0c853a 100644 --- a/docs/libcurl/curl_multi_timeout.md +++ b/docs/libcurl/curl_multi_timeout.md @@ -9,6 +9,8 @@ See-also: - curl_multi_info_read (3) - curl_multi_setopt (3) - curl_multi_socket (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_wait.md b/docs/libcurl/curl_multi_wait.md index 526cef6bdaa..7a05974c8cb 100644 --- a/docs/libcurl/curl_multi_wait.md +++ b/docs/libcurl/curl_multi_wait.md @@ -8,6 +8,8 @@ See-also: - curl_multi_fdset (3) - curl_multi_perform (3) - curl_multi_poll (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_multi_wakeup.md b/docs/libcurl/curl_multi_wakeup.md index fd9fa0569b8..6b0ad97c4dd 100644 --- a/docs/libcurl/curl_multi_wakeup.md +++ b/docs/libcurl/curl_multi_wakeup.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_multi_poll (3) - curl_multi_wait (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_pushheader_byname.md b/docs/libcurl/curl_pushheader_byname.md index b83ba55927a..700f5110691 100644 --- a/docs/libcurl/curl_pushheader_byname.md +++ b/docs/libcurl/curl_pushheader_byname.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_PUSHFUNCTION (3) - curl_pushheader_bynum (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/curl_pushheader_bynum.md b/docs/libcurl/curl_pushheader_bynum.md index 4ba20b673c0..f39836fc59d 100644 --- a/docs/libcurl/curl_pushheader_bynum.md +++ b/docs/libcurl/curl_pushheader_bynum.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_PUSHFUNCTION (3) - curl_pushheader_byname (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/curl_share_cleanup.md b/docs/libcurl/curl_share_cleanup.md index 2f161149ba9..607bcd92629 100644 --- a/docs/libcurl/curl_share_cleanup.md +++ b/docs/libcurl/curl_share_cleanup.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_share_init (3) - curl_share_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_share_init.md b/docs/libcurl/curl_share_init.md index 6654f3c9b56..6c997ee6b15 100644 --- a/docs/libcurl/curl_share_init.md +++ b/docs/libcurl/curl_share_init.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_share_cleanup (3) - curl_share_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_share_setopt.md b/docs/libcurl/curl_share_setopt.md index d21c1595fce..c7722c7989e 100644 --- a/docs/libcurl/curl_share_setopt.md +++ b/docs/libcurl/curl_share_setopt.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_share_cleanup (3) - curl_share_init (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_share_strerror.md b/docs/libcurl/curl_share_strerror.md index 9e8ebe7272c..0e529ea5b50 100644 --- a/docs/libcurl/curl_share_strerror.md +++ b/docs/libcurl/curl_share_strerror.md @@ -9,6 +9,8 @@ See-also: - curl_multi_strerror (3) - curl_url_strerror (3) - libcurl-errors (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_slist_append.md b/docs/libcurl/curl_slist_append.md index 2e8a54018ab..adeb715039e 100644 --- a/docs/libcurl/curl_slist_append.md +++ b/docs/libcurl/curl_slist_append.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - curl_slist_free_all (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_slist_free_all.md b/docs/libcurl/curl_slist_free_all.md index 1d73d7d71ee..74c89079a6f 100644 --- a/docs/libcurl/curl_slist_free_all.md +++ b/docs/libcurl/curl_slist_free_all.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - curl_slist_append (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_strequal.md b/docs/libcurl/curl_strequal.md index 76b08a978d7..c86370147d4 100644 --- a/docs/libcurl/curl_strequal.md +++ b/docs/libcurl/curl_strequal.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - strcasecmp (3) - strcmp (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_strnequal.md b/docs/libcurl/curl_strnequal.md index 76b08a978d7..c86370147d4 100644 --- a/docs/libcurl/curl_strnequal.md +++ b/docs/libcurl/curl_strnequal.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - strcasecmp (3) - strcmp (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_unescape.md b/docs/libcurl/curl_unescape.md index ad60150a381..0a470ce1798 100644 --- a/docs/libcurl/curl_unescape.md +++ b/docs/libcurl/curl_unescape.md @@ -9,6 +9,8 @@ See-also: - curl_easy_escape (3) - curl_easy_unescape (3) - curl_free (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_url.md b/docs/libcurl/curl_url.md index 3870073d615..7b72b6c72bd 100644 --- a/docs/libcurl/curl_url.md +++ b/docs/libcurl/curl_url.md @@ -11,6 +11,8 @@ See-also: - curl_url_get (3) - curl_url_set (3) - curl_url_strerror (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_url_cleanup.md b/docs/libcurl/curl_url_cleanup.md index b64fc79e7a9..c7fe7b761b6 100644 --- a/docs/libcurl/curl_url_cleanup.md +++ b/docs/libcurl/curl_url_cleanup.md @@ -10,6 +10,8 @@ See-also: - curl_url_dup (3) - curl_url_get (3) - curl_url_set (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_url_dup.md b/docs/libcurl/curl_url_dup.md index 769a1c72dcb..da4e3f44314 100644 --- a/docs/libcurl/curl_url_dup.md +++ b/docs/libcurl/curl_url_dup.md @@ -10,6 +10,8 @@ See-also: - curl_url_cleanup (3) - curl_url_get (3) - curl_url_set (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_url_get.md b/docs/libcurl/curl_url_get.md index 8722286faaa..6db66dfcd98 100644 --- a/docs/libcurl/curl_url_get.md +++ b/docs/libcurl/curl_url_get.md @@ -11,6 +11,8 @@ See-also: - curl_url_dup (3) - curl_url_set (3) - curl_url_strerror (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_url_set.md b/docs/libcurl/curl_url_set.md index d02ec001879..cfd63a8b457 100644 --- a/docs/libcurl/curl_url_set.md +++ b/docs/libcurl/curl_url_set.md @@ -11,6 +11,8 @@ See-also: - curl_url_dup (3) - curl_url_get (3) - curl_url_strerror (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_url_strerror.md b/docs/libcurl/curl_url_strerror.md index 46971c65005..b3d27a22a1a 100644 --- a/docs/libcurl/curl_url_strerror.md +++ b/docs/libcurl/curl_url_strerror.md @@ -11,6 +11,8 @@ See-also: - curl_url_get (3) - curl_url_set (3) - libcurl-errors (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_version.md b/docs/libcurl/curl_version.md index 953252c2ca9..27f2320bf2d 100644 --- a/docs/libcurl/curl_version.md +++ b/docs/libcurl/curl_version.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - curl_version_info (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_version_info.md b/docs/libcurl/curl_version_info.md index ded83910061..bf1ca74171a 100644 --- a/docs/libcurl/curl_version_info.md +++ b/docs/libcurl/curl_version_info.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - curl_version (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/curl_ws_meta.md b/docs/libcurl/curl_ws_meta.md index 49d987dae9c..a60ce1d66a5 100644 --- a/docs/libcurl/curl_ws_meta.md +++ b/docs/libcurl/curl_ws_meta.md @@ -10,6 +10,8 @@ See-also: - curl_ws_recv (3) - curl_ws_send (3) - libcurl-ws (3) +Protocol: + - WS --- # NAME diff --git a/docs/libcurl/curl_ws_recv.md b/docs/libcurl/curl_ws_recv.md index e2b1b74ff45..c6740b8771a 100644 --- a/docs/libcurl/curl_ws_recv.md +++ b/docs/libcurl/curl_ws_recv.md @@ -10,6 +10,8 @@ See-also: - curl_easy_setopt (3) - curl_ws_send (3) - libcurl-ws (3) +Protocol: + - Ws --- # NAME diff --git a/docs/libcurl/curl_ws_send.md b/docs/libcurl/curl_ws_send.md index f07a3ecc14b..ddb4f87447f 100644 --- a/docs/libcurl/curl_ws_send.md +++ b/docs/libcurl/curl_ws_send.md @@ -10,6 +10,8 @@ See-also: - curl_easy_setopt (3) - curl_ws_recv (3) - libcurl-ws (3) +Protocol: + - WS --- # NAME diff --git a/docs/libcurl/libcurl-easy.md b/docs/libcurl/libcurl-easy.md index 7dbc475eca4..c37e7e37260 100644 --- a/docs/libcurl/libcurl-easy.md +++ b/docs/libcurl/libcurl-easy.md @@ -11,6 +11,8 @@ See-also: - libcurl (3) - libcurl-errors (3) - libcurl-multi (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-env-dbg.md b/docs/libcurl/libcurl-env-dbg.md index 6a22a885f16..1ed68657af4 100644 --- a/docs/libcurl/libcurl-env-dbg.md +++ b/docs/libcurl/libcurl-env-dbg.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - libcurl-env (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-env.md b/docs/libcurl/libcurl-env.md index 4df328ecdc7..5ebad896bbe 100644 --- a/docs/libcurl/libcurl-env.md +++ b/docs/libcurl/libcurl-env.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - libcurl-env-dbg (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-errors.md b/docs/libcurl/libcurl-errors.md index 0d4ce51138e..134718112e6 100644 --- a/docs/libcurl/libcurl-errors.md +++ b/docs/libcurl/libcurl-errors.md @@ -12,6 +12,8 @@ See-also: - curl_multi_strerror (3) - curl_share_strerror (3) - curl_url_strerror (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-multi.md b/docs/libcurl/libcurl-multi.md index e037394d925..d43cb61e8ac 100644 --- a/docs/libcurl/libcurl-multi.md +++ b/docs/libcurl/libcurl-multi.md @@ -8,6 +8,8 @@ See-also: - libcurl (3) - libcurl-easy (3) - libcurl-errors (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-security.md b/docs/libcurl/libcurl-security.md index 0d71ca7b142..a1e0af81fbf 100644 --- a/docs/libcurl/libcurl-security.md +++ b/docs/libcurl/libcurl-security.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - libcurl-thread (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-share.md b/docs/libcurl/libcurl-share.md index 2d33f71eb0f..726db8adf5e 100644 --- a/docs/libcurl/libcurl-share.md +++ b/docs/libcurl/libcurl-share.md @@ -11,6 +11,8 @@ See-also: - libcurl-easy (3) - libcurl-errors (3) - libcurl-multi (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-thread.md b/docs/libcurl/libcurl-thread.md index 6924eb355f3..cc55378c859 100644 --- a/docs/libcurl/libcurl-thread.md +++ b/docs/libcurl/libcurl-thread.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - libcurl-security (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-tutorial.md b/docs/libcurl/libcurl-tutorial.md index 54607af7206..afe9e288d6e 100644 --- a/docs/libcurl/libcurl-tutorial.md +++ b/docs/libcurl/libcurl-tutorial.md @@ -9,6 +9,8 @@ See-also: - libcurl-errors (3) - libcurl-multi (3) - libcurl-url (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-url.md b/docs/libcurl/libcurl-url.md index c8d3f0b3c06..3cda90539c3 100644 --- a/docs/libcurl/libcurl-url.md +++ b/docs/libcurl/libcurl-url.md @@ -12,6 +12,8 @@ See-also: - curl_url_get (3) - curl_url_set (3) - curl_url_strerror (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl-ws.md b/docs/libcurl/libcurl-ws.md index 1668af44315..7aa9857abb4 100644 --- a/docs/libcurl/libcurl-ws.md +++ b/docs/libcurl/libcurl-ws.md @@ -12,6 +12,8 @@ See-also: - curl_ws_meta (3) - curl_ws_recv (3) - curl_ws_send (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/libcurl.md b/docs/libcurl/libcurl.md index f8ff15eb860..1b3fa00d1e9 100644 --- a/docs/libcurl/libcurl.md +++ b/docs/libcurl/libcurl.md @@ -9,6 +9,8 @@ See-also: - libcurl-multi (3) - libcurl-security (3) - libcurl-thread (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/mksymbolsmanpage.pl b/docs/libcurl/mksymbolsmanpage.pl index d7b9a77e38f..90de3debb7b 100755 --- a/docs/libcurl/mksymbolsmanpage.pl +++ b/docs/libcurl/mksymbolsmanpage.pl @@ -40,6 +40,8 @@ Title: libcurl-symbols Section: 3 Source: libcurl +Protocol: + - * See-also: - libcurl (3) - libcurl-easy (3) diff --git a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md index e041ff800c6..a2877dc1394 100644 --- a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md +++ b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_CONNECT_ONLY (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md index 474c033c268..0ea124da564 100644 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_APPCONNECT_TIME_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md index c2f9825b7b3..a9986d22b28 100644 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_APPCONNECT_TIME (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CAINFO.md b/docs/libcurl/opts/CURLINFO_CAINFO.md index 0cc3c0cd0da..c0f86bf9df4 100644 --- a/docs/libcurl/opts/CURLINFO_CAINFO.md +++ b/docs/libcurl/opts/CURLINFO_CAINFO.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CAPATH (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CAPATH.md b/docs/libcurl/opts/CURLINFO_CAPATH.md index c1f31578049..611ce2bfc24 100644 --- a/docs/libcurl/opts/CURLINFO_CAPATH.md +++ b/docs/libcurl/opts/CURLINFO_CAPATH.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CAINFO (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.md b/docs/libcurl/opts/CURLINFO_CERTINFO.md index a4125632972..cedd57cfd70 100644 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.md +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CAPATH (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md index 38cd1ce2f3c..ed3654b6e88 100644 --- a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md +++ b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_TIMEVALUE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md index b1c58ad9e7a..acbd2732a67 100644 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CONNECT_TIME_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md index 158b58d955a..63abaf3d6f9 100644 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_CONNECTTIMEOUT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONN_ID.md b/docs/libcurl/opts/CURLINFO_CONN_ID.md index 8b6c21bc4d3..d09a3afa876 100644 --- a/docs/libcurl/opts/CURLINFO_CONN_ID.md +++ b/docs/libcurl/opts/CURLINFO_CONN_ID.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_XFER_ID (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md index 155759b2b2a..b25ddec8f97 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CONTENT_LENGTH_UPLOAD (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md index fa4acf815dc..0518fb9484d 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CONTENT_LENGTH_UPLOAD_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md index 24c26dbfb5a..51c26fd6ec6 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md index 4fe942c2735..23cfe03a5c3 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md index b9bc4107dd6..8427e6aa741 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md @@ -9,6 +9,8 @@ See-also: - curl_easy_getinfo (3) - curl_easy_header (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_COOKIELIST.md b/docs/libcurl/opts/CURLINFO_COOKIELIST.md index bc01bbfe902..4c538892b9a 100644 --- a/docs/libcurl/opts/CURLINFO_COOKIELIST.md +++ b/docs/libcurl/opts/CURLINFO_COOKIELIST.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_COOKIELIST (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md index 98ebde70e30..0b7b9c3c52f 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_FOLLOWLOCATION (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md index 8671535e03b..0dc2cc7d298 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_FOLLOWLOCATION (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.md b/docs/libcurl/opts/CURLINFO_FILETIME.md index 59a61840e17..bf6716b025f 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME.md +++ b/docs/libcurl/opts/CURLINFO_FILETIME.md @@ -8,6 +8,10 @@ See-also: - CURLOPT_FILETIME (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP + - FTP + - SFTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.md b/docs/libcurl/opts/CURLINFO_FILETIME_T.md index 2f48b12e298..2d86e3272c3 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME_T.md +++ b/docs/libcurl/opts/CURLINFO_FILETIME_T.md @@ -8,6 +8,10 @@ See-also: - CURLOPT_FILETIME (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP + - FTP + - SFTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md index 6cbd3c98603..1ef47542fc5 100644 --- a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md +++ b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md index 81ac85d6805..b6533fd678d 100644 --- a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md +++ b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_SIZE_DOWNLOAD (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md index 6eed5bfe90f..c03dcfe61e6 100644 --- a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md +++ b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_HTTPAUTH (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md index 94cd449139d..ea9e527eb53 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md +++ b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RESPONSE_CODE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md index 71c318198a8..6a8a0b28156 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md +++ b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RESPONSE_CODE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_LASTSOCKET.md b/docs/libcurl/opts/CURLINFO_LASTSOCKET.md index da698172d32..9b4a84cdffb 100644 --- a/docs/libcurl/opts/CURLINFO_LASTSOCKET.md +++ b/docs/libcurl/opts/CURLINFO_LASTSOCKET.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_CONNECT_ONLY (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md index 9584243e580..689a576a1b2 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md +++ b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_PRIMARY_IP (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md index d7ae9a9a687..5d9a77d92f0 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md +++ b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLINFO_LOCAL_PORT Section: 3 Source: libcurl +Protocol: + - TCP See-also: - CURLINFO_LOCAL_IP (3) - CURLINFO_PRIMARY_PORT (3) diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md index 68e1aa9b013..ccc45cdce9b 100644 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_NAMELOOKUP_TIME_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md index b97b584d3eb..7d11f75287b 100644 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_NAMELOOKUP_TIME (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md index 053ab6ff5bf..7f184e052a9 100644 --- a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md +++ b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_OS_ERRNO.md b/docs/libcurl/opts/CURLINFO_OS_ERRNO.md index 61c3348ad7b..bf5a6f6657c 100644 --- a/docs/libcurl/opts/CURLINFO_OS_ERRNO.md +++ b/docs/libcurl/opts/CURLINFO_OS_ERRNO.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md index 5dfd6c3f124..e7645d7f39c 100644 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_PRETRANSFER_TIME_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md index fb9be877328..7ecf4fc7a2e 100644 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_PRETRANSFER_TIME_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md index c5692f12667..3f9b918bb8b 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md @@ -10,6 +10,8 @@ See-also: - CURLINFO_PRIMARY_PORT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md index 43ef2676311..12f384da4e8 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_PRIMARY_IP (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PRIVATE.md b/docs/libcurl/opts/CURLINFO_PRIVATE.md index 42c96f0ea80..548eacf29b2 100644 --- a/docs/libcurl/opts/CURLINFO_PRIVATE.md +++ b/docs/libcurl/opts/CURLINFO_PRIVATE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PRIVATE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PROTOCOL.md b/docs/libcurl/opts/CURLINFO_PROTOCOL.md index d15457b9d43..0b213310fb7 100644 --- a/docs/libcurl/opts/CURLINFO_PROTOCOL.md +++ b/docs/libcurl/opts/CURLINFO_PROTOCOL.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RESPONSE_CODE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md index f29f9245e92..1c353453b2a 100644 --- a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md +++ b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_HTTPAUTH_AVAIL (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md index d16668d8f4f..73c21ccd839 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md +++ b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md @@ -9,6 +9,8 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) - libcurl-errors (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md index f559badfa9f..07bb011036d 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md +++ b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_SSL_VERIFYRESULT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md index 0fffb728560..a4375200038 100644 --- a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_TIMEOUT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md index e0749029fdb..38a0c908f29 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_FOLLOWLOCATION (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md index 6f742aba935..cd54bcb0832 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md @@ -10,6 +10,8 @@ See-also: - CURLINFO_REDIRECT_URL (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md index 4b48a4f46c0..da5b07b1081 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md @@ -10,6 +10,8 @@ See-also: - CURLINFO_REDIRECT_URL (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md index 1954351de34..d3db71a1f41 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_FOLLOWLOCATION (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_REFERER.md b/docs/libcurl/opts/CURLINFO_REFERER.md index fcb719e9c9d..7dca94bd8cd 100644 --- a/docs/libcurl/opts/CURLINFO_REFERER.md +++ b/docs/libcurl/opts/CURLINFO_REFERER.md @@ -9,6 +9,8 @@ See-also: - curl_easy_getinfo (3) - curl_easy_header (3) - curl_easy_setopt (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md index dd1f6011ca6..beae30a21e0 100644 --- a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md +++ b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_SIZE_DOWNLOAD_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md index 72cc1449fe2..9bf15306a69 100644 --- a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md +++ b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md @@ -8,6 +8,11 @@ See-also: - CURLINFO_HTTP_CONNECTCODE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - HTTP + - FTP + - SMTP + - LDAP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md index 12e30375dfc..1c06f77d9b5 100644 --- a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md +++ b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_HEADERFUNCTION (3) - CURLOPT_STDERR (3) - curl_easy_header (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md index 68796760580..3e7de2578c2 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_RTSP_SERVER_CSEQ (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md index c316f37ca81..241b65816d3 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RTSP_SERVER_CSEQ (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md index 28bf6cd2c14..e13bb918a21 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RTSP_CSEQ_RECV (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md index 48ebe207702..e046cce3f0a 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RTSP_CSEQ_RECV (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SCHEME.md b/docs/libcurl/opts/CURLINFO_SCHEME.md index c3f59a14197..fc5eaef2d3b 100644 --- a/docs/libcurl/opts/CURLINFO_SCHEME.md +++ b/docs/libcurl/opts/CURLINFO_SCHEME.md @@ -10,6 +10,8 @@ See-also: - CURLINFO_RESPONSE_CODE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md index e62f971af8e..fa74e4f00fe 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_MAXFILESIZE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md index 5603f5a89e0..55c9d5fef67 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_MAXFILESIZE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md index 19c594d30ab..c79b235da48 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_SIZE_UPLOAD_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md index 66954a2de80..a9ef09b4984 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_SIZE_UPLOAD (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md index 6ffef34c221..8662f2a0e3c 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_SPEED_UPLOAD (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md index b801625444f..3facdf5cbb2 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_SPEED_UPLOAD_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md index ef9105babc9..e787253234c 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_SPEED_DOWNLOAD_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md index 4398fc2ee11..806cc357d65 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_SPEED_DOWNLOAD_T (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md index 7f6127952f5..107bbc4673b 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md +++ b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_SSLENGINE (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md index 270dacba739..34fd445272f 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md +++ b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_PROXY_SSL_VERIFYRESULT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md index 5fc6fac8c3f..063cafe5212 100644 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_TIMEOUT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md index 814658c9b88..cb414e9219d 100644 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_TIMEOUT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md index 490e0bc2611..f7a6304d263 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_TLS_SSL_PTR (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md index 6a54f01f798..b3045bebbd9 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_TLS_SESSION (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md index 8859f57f8dc..51dcf2477ef 100644 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_TIMEOUT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md index cbd8ddda3e8..e45216d16cc 100644 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md @@ -9,8 +9,9 @@ See-also: - CURLOPT_TIMEOUT (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- - # NAME CURLINFO_TOTAL_TIME_T - get total time of previous transfer in microseconds diff --git a/docs/libcurl/opts/CURLINFO_USED_PROXY.md b/docs/libcurl/opts/CURLINFO_USED_PROXY.md index 9fc6836a0ac..55e00d1f3e4 100644 --- a/docs/libcurl/opts/CURLINFO_USED_PROXY.md +++ b/docs/libcurl/opts/CURLINFO_USED_PROXY.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_XFER_ID.md b/docs/libcurl/opts/CURLINFO_XFER_ID.md index 68ec3e8eff7..34f5b39fb87 100644 --- a/docs/libcurl/opts/CURLINFO_XFER_ID.md +++ b/docs/libcurl/opts/CURLINFO_XFER_ID.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CONN_ID (3) - curl_easy_getinfo (3) - curl_easy_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md index 5b8c606273f..c467d5c3201 100644 --- a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md +++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md @@ -8,6 +8,8 @@ See-also: - CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3) - CURLMOPT_MAX_PIPELINE_LENGTH (3) - CURLMOPT_PIPELINING (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md index b550796990e..8abfd99b865 100644 --- a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md +++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3) - CURLMOPT_PIPELINING (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md index fbfa0c8b555..0a7eb4965dd 100644 --- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md +++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_MAX_HOST_CONNECTIONS (3) - CURLOPT_MAXCONNECTS (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md index a8e23f8ca0f..65495ba8181 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_MAXCONNECTS (3) - CURLOPT_MAXCONNECTS (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md index 3ccfe87f812..ceb8850ed3e 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_MAXCONNECTS (3) - CURLMOPT_MAX_TOTAL_CONNECTIONS (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md index fea5d513f67..625e6564aa3 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_MAX_HOST_CONNECTIONS (3) - CURLMOPT_PIPELINING (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md index 8cac3702bdd..4d976429914 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_MAXCONNECTS (3) - CURLMOPT_MAX_HOST_CONNECTIONS (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.md b/docs/libcurl/opts/CURLMOPT_PIPELINING.md index 2d171df3221..4228baa3107 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.md @@ -11,6 +11,8 @@ See-also: - CURLMOPT_MAX_HOST_CONNECTIONS (3) - CURLMOPT_MAX_PIPELINE_LENGTH (3) - CURLMOPT_PIPELINING_SITE_BL (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md index 87eb2c45bb2..3af2b5ae6f6 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_PIPELINING (3) - CURLMOPT_PIPELINING_SITE_BL (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md index 00491ed8277..661edf2c25e 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_PIPELINING (3) - CURLMOPT_PIPELINING_SERVER_BL (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md index f634d3556d5..2372decdf37 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md +++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md @@ -9,6 +9,8 @@ See-also: - CURLMOPT_PUSHFUNCTION (3) - CURLOPT_PIPEWAIT (3) - RFC 7540 +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md index 9ef51d50fe6..3377081246e 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md @@ -9,6 +9,8 @@ See-also: - CURLMOPT_PUSHDATA (3) - CURLOPT_PIPEWAIT (3) - RFC 7540 +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md index 1b4814c4bb8..597f8625a79 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md @@ -8,6 +8,8 @@ See-also: - CURLMOPT_SOCKETFUNCTION (3) - CURLMOPT_TIMERFUNCTION (3) - curl_multi_socket_action (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index 207819f983b..d2f18244677 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -8,6 +8,8 @@ See-also: - CURLMOPT_SOCKETDATA (3) - CURLMOPT_TIMERFUNCTION (3) - curl_multi_socket_action (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md index 1632c720e5a..5b8092fdf8a 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md +++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_SOCKETFUNCTION (3) - CURLMOPT_TIMERFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md index fa73266cbe5..ee23505274a 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLMOPT_SOCKETFUNCTION (3) - CURLMOPT_TIMERDATA (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md index cd71bb19764..84884291c72 100644 --- a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md +++ b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_UNIX_SOCKET_PATH (3) - unix (7) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md index b51f45163cd..6e44c4c3e3f 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CONNECTTIMEOUT_MS (3) - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_STDERR (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md index 50e7eba942c..87be71032d4 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md +++ b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_HTTPHEADER (3) - CURLOPT_HTTP_CONTENT_DECODING (3) - CURLOPT_TRANSFER_ENCODING (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md index dc9f08a8602..6e977a861db 100644 --- a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md +++ b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_STDERR (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC.md b/docs/libcurl/opts/CURLOPT_ALTSVC.md index 09f89a32145..803561f42d9 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC.md +++ b/docs/libcurl/opts/CURLOPT_ALTSVC.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_CONNECT_TO (3) - CURLOPT_COOKIEFILE (3) - CURLOPT_RESOLVE (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md index b17e0c4615a..11250870c8b 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md +++ b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_ALTSVC (3) - CURLOPT_CONNECT_TO (3) - CURLOPT_RESOLVE (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_APPEND.md b/docs/libcurl/opts/CURLOPT_APPEND.md index a1d5176cb1e..81dd29594d6 100644 --- a/docs/libcurl/opts/CURLOPT_APPEND.md +++ b/docs/libcurl/opts/CURLOPT_APPEND.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DIRLISTONLY (3) - CURLOPT_RESUME_FROM (3) - CURLOPT_UPLOAD (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.md b/docs/libcurl/opts/CURLOPT_AUTOREFERER.md index c9a4ce1fe2e..a5ee9282a5a 100644 --- a/docs/libcurl/opts/CURLOPT_AUTOREFERER.md +++ b/docs/libcurl/opts/CURLOPT_AUTOREFERER.md @@ -10,6 +10,8 @@ See-also: - CURLINFO_REFERER (3) - CURLOPT_FOLLOWLOCATION (3) - CURLOPT_REFERER (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md index a9e1acd25d0..b9ed60334df 100644 --- a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_HTTPAUTH (3) - CURLOPT_HTTPHEADER (3) - CURLOPT_PROXYAUTH (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md index 3a2ddd8e345..68365479a68 100644 --- a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_MAX_RECV_SPEED_LARGE (3) - CURLOPT_UPLOAD_BUFFERSIZE (3) - CURLOPT_WRITEFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.md b/docs/libcurl/opts/CURLOPT_CAINFO.md index 6955aaa6182..2f5d2c84bde 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_CA_CACHE_TIMEOUT (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md index 4566eabc4b8..21a0724e656 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_CAINFO_BLOB Section: 3 Source: libcurl +Protocol: + - TLS See-also: - CURLOPT_CAINFO (3) - CURLOPT_CAPATH (3) diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.md b/docs/libcurl/opts/CURLOPT_CAPATH.md index 3d6c3af64de..6ee7ad6f641 100644 --- a/docs/libcurl/opts/CURLOPT_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_CAPATH.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_CAINFO (3) - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_STDERR (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md index 79133e81e90..b7121fa4bd1 100644 --- a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_CAPATH (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.md b/docs/libcurl/opts/CURLOPT_CERTINFO.md index caaa9ea1900..f8ade065f98 100644 --- a/docs/libcurl/opts/CURLOPT_CERTINFO.md +++ b/docs/libcurl/opts/CURLOPT_CERTINFO.md @@ -10,6 +10,8 @@ See-also: - CURLINFO_CERTINFO (3) - CURLOPT_CAINFO (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md index d349f2dbfd5..be42c2597ad 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_CHUNK_END_FUNCTION (3) - CURLOPT_WILDCARDMATCH (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md index eca85c873d8..43e01285a17 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_CHUNK_BGN_FUNCTION (3) - CURLOPT_WILDCARDMATCH (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md index 0b228a73cce..5ae6ff1920c 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_CHUNK_BGN_FUNCTION (3) - CURLOPT_WILDCARDMATCH (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md index c15c51816e8..c8d4fc81ac6 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_CLOSESOCKETFUNCTION (3) - CURLOPT_OPENSOCKETFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 4e9f25579a9..1eb634be07f 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_CLOSESOCKETDATA (3) - CURLOPT_OPENSOCKETFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md index 798c290bc8e..697bf4b5157 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_MAX_RECV_SPEED_LARGE (3) - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md index 793b370126d..1d5088f45cd 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CONNECTTIMEOUT (3) - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md index ccb00fd23b2..39496994e29 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md +++ b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_VERBOSE (3) - curl_easy_recv (3) - curl_easy_send (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_TO.md b/docs/libcurl/opts/CURLOPT_CONNECT_TO.md index ed0db591dbd..c85bdc5cffd 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_TO.md +++ b/docs/libcurl/opts/CURLOPT_CONNECT_TO.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_HTTPPROXYTUNNEL (3) - CURLOPT_RESOLVE (3) - CURLOPT_URL (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md index 46b935dd734..5dbb8336c13 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_CONV_FROM_UTF8_FUNCTION (3) - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md index 37abfc5b965..ca59dc5a6b7 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_CONV_FROM_UTF8_FUNCTION Section: 3 Source: libcurl +Protocol: + - * See-also: - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md index 97a8a6c1bed..cab8b15ae51 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) - CURLOPT_CONV_FROM_UTF8_FUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.md b/docs/libcurl/opts/CURLOPT_COOKIE.md index 5d34072af77..e9ad140004b 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIE.md +++ b/docs/libcurl/opts/CURLOPT_COOKIE.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_COOKIEJAR (3) - CURLOPT_COOKIELIST (3) - CURLOPT_HTTPHEADER (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.md b/docs/libcurl/opts/CURLOPT_COOKIEFILE.md index fa88c14db2c..018355ac095 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.md +++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_COOKIE (3) - CURLOPT_COOKIEJAR (3) - CURLOPT_COOKIESESSION (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.md b/docs/libcurl/opts/CURLOPT_COOKIEJAR.md index 05196abc4ba..21a86c5f468 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEJAR.md +++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_COOKIE (3) - CURLOPT_COOKIEFILE (3) - CURLOPT_COOKIELIST (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.md b/docs/libcurl/opts/CURLOPT_COOKIELIST.md index 31fb8d24065..acedd3cab69 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.md +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_COOKIE (3) - CURLOPT_COOKIEFILE (3) - CURLOPT_COOKIEJAR (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_COOKIESESSION.md b/docs/libcurl/opts/CURLOPT_COOKIESESSION.md index 33c8a2f5524..e319ceeeebf 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIESESSION.md +++ b/docs/libcurl/opts/CURLOPT_COOKIESESSION.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_COOKIE (3) - CURLOPT_COOKIEFILE (3) - CURLOPT_COOKIEJAR (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md index 430c53543ef..86a04332431 100644 --- a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md +++ b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_POSTFIELDS (3) - CURLOPT_POSTFIELDSIZE (3) - CURLOPT_UPLOAD (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CRLF.md b/docs/libcurl/opts/CURLOPT_CRLF.md index b712902c0d0..719b8a709a4 100644 --- a/docs/libcurl/opts/CURLOPT_CRLF.md +++ b/docs/libcurl/opts/CURLOPT_CRLF.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.md b/docs/libcurl/opts/CURLOPT_CRLFILE.md index 486383bf3ef..3ab78c377fb 100644 --- a/docs/libcurl/opts/CURLOPT_CRLFILE.md +++ b/docs/libcurl/opts/CURLOPT_CRLFILE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY_CRLFILE (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CURLU.md b/docs/libcurl/opts/CURLOPT_CURLU.md index 53146bafe56..ac9059f51d8 100644 --- a/docs/libcurl/opts/CURLOPT_CURLU.md +++ b/docs/libcurl/opts/CURLOPT_CURLU.md @@ -12,6 +12,8 @@ See-also: - curl_url_get (3) - curl_url_set (3) - curl_url_strerror (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md index eda31d1e781..3bbe39cb36e 100644 --- a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md +++ b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md @@ -9,6 +9,12 @@ See-also: - CURLOPT_HTTPHEADER (3) - CURLOPT_NOBODY (3) - CURLOPT_REQUEST_TARGET (3) +Protocol: + - HTTP + - FTP + - IMAP + - POP3 + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.md b/docs/libcurl/opts/CURLOPT_DEBUGDATA.md index ac924f79d7a..22c393c0093 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGDATA.md +++ b/docs/libcurl/opts/CURLOPT_DEBUGDATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_STDERR (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md index 58eba18d521..e6d22d8e95d 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_DEBUGDATA (3) - CURLOPT_VERBOSE (3) - curl_global_trace (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md index 1ef732b6484..da9fb9b1af2 100644 --- a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md +++ b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_PROTOCOL (3) - CURLINFO_SCHEME (3) - CURLOPT_URL (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md index abeb6473d65..61ab733f95a 100644 --- a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md +++ b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md @@ -7,6 +7,10 @@ Source: libcurl See-also: - CURLOPT_CUSTOMREQUEST (3) - CURLOPT_WILDCARDMATCH (3) +Protocol: + - FTP + - SFTP + - POP3 --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md index ee06610ee0e..8a5652331a3 100644 --- a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md +++ b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_URL (3) - curl_url_set (3) - libcurl-security (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md index 274dae6b1de..20a56b2b7f4 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_DNS_USE_GLOBAL_CACHE (3) - CURLOPT_MAXAGE_CONN (3) - CURLOPT_RESOLVE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md index f985adcc4f6..753a891a11b 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md +++ b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_DNS_LOCAL_IP6 (3) - CURLOPT_DNS_SERVERS (3) - CURLOPT_INTERFACE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md index 2e6bf632981..4a20703faac 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DNS_INTERFACE (3) - CURLOPT_DNS_LOCAL_IP6 (3) - CURLOPT_DNS_SERVERS (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md index babaf254b62..c6463cb02ae 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DNS_INTERFACE (3) - CURLOPT_DNS_LOCAL_IP4 (3) - CURLOPT_DNS_SERVERS (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md index 892817302fe..63a99f46ba5 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md +++ b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DNS_CACHE_TIMEOUT (3) - CURLOPT_DNS_LOCAL_IP4 (3) - CURLOPT_DNS_LOCAL_IP6 (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md index 4224a592206..b9ed92cff9c 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md +++ b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_DNS_CACHE_TIMEOUT (3) - CURLOPT_IPRESOLVE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md index 7b3193784dc..b742ed19321 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md +++ b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_DNS_CACHE_TIMEOUT (3) - CURLOPT_SHARE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md index ed00377283c..bdd0bc0f3a4 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md index 39caf19534a..e272b2c1ffe 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md @@ -12,6 +12,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md index ccc7b5d3d35..c51ff02fbb7 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DOH_SSL_VERIFYHOST (3) - CURLOPT_DOH_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYSTATUS (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DOH_URL.md b/docs/libcurl/opts/CURLOPT_DOH_URL.md index 22a6c7af667..3aa55c6038a 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_URL.md +++ b/docs/libcurl/opts/CURLOPT_DOH_URL.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DNS_CACHE_TIMEOUT (3) - CURLOPT_RESOLVE (3) - CURLOPT_VERBOSE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md index d4ab6c614c3..e91a8800d8b 100644 --- a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md +++ b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_RANDOM_FILE (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md index 8caeec8b389..c354b89bf7f 100644 --- a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md +++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md @@ -11,6 +11,8 @@ See-also: - curl_multi_strerror (3) - curl_share_strerror (3) - curl_url_strerror (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md index 41cc59a82d9..60c8fe4b727 100644 --- a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_HTTPPOST (3) - CURLOPT_POST (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.md b/docs/libcurl/opts/CURLOPT_FAILONERROR.md index 894a5b46be8..78a29278bb6 100644 --- a/docs/libcurl/opts/CURLOPT_FAILONERROR.md +++ b/docs/libcurl/opts/CURLOPT_FAILONERROR.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RESPONSE_CODE (3) - CURLOPT_HTTP200ALIASES (3) - CURLOPT_KEEP_SENDING_ON_ERROR (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_FILETIME.md b/docs/libcurl/opts/CURLOPT_FILETIME.md index 340f584d3a7..95a4d1b426c 100644 --- a/docs/libcurl/opts/CURLOPT_FILETIME.md +++ b/docs/libcurl/opts/CURLOPT_FILETIME.md @@ -7,6 +7,12 @@ Source: libcurl See-also: - CURLINFO_FILETIME (3) - curl_easy_getinfo (3) +Protocol: + - HTTP + - FTP + - SFTP + - FILE + - SMB --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md index d56b9922edd..0afd4b611f0 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_FNMATCH_FUNCTION (3) - CURLOPT_WILDCARDMATCH (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md index 5f087d7c1bd..58b6af1d134 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_FNMATCH_DATA (3) - CURLOPT_WILDCARDMATCH (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md index af3ddbec640..60aaf5293f6 100644 --- a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md +++ b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_POSTREDIR (3) - CURLOPT_PROTOCOLS (3) - CURLOPT_REDIR_PROTOCOLS (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md index a266863e595..8cd601cd546 100644 --- a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md +++ b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_FRESH_CONNECT (3) - CURLOPT_MAXCONNECTS (3) - CURLOPT_MAXLIFETIME_CONN (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md index aaadf345ed0..3010529f732 100644 --- a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md +++ b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FRESH_CONNECT Section: 3 Source: libcurl +Protocol: + - * See-also: - CURLOPT_FORBID_REUSE (3) - CURLOPT_MAXAGE_CONN (3) diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.md b/docs/libcurl/opts/CURLOPT_FTPPORT.md index fac0ebd191f..d83221c3123 100644 --- a/docs/libcurl/opts/CURLOPT_FTPPORT.md +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTPPORT Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_FTP_USE_EPRT (3) - CURLOPT_FTP_USE_EPSV (3) diff --git a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md index 6097d43d7be..a356a72e5dc 100644 --- a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md +++ b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTPSSLAUTH Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_FTP_SSL_CCC (3) - CURLOPT_USE_SSL (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md index 70061f0d9b6..0ce40000126 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md +++ b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTP_ACCOUNT Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_PASSWORD (3) - CURLOPT_USERNAME (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md index a24b5326d0a..ed91dc434ae 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md +++ b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTP_ALTERNATIVE_TO_USER Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_FTP_ACCOUNT (3) - CURLOPT_FTP_SKIP_PASV_IP (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md index 891feb18979..2fcf162269f 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md +++ b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTP_CREATE_MISSING_DIRS Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_FTP_FILEMETHOD (3) - CURLOPT_FTP_USE_EPSV (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md index 31c4cfb174a..df7648f1072 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md +++ b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTP_FILEMETHOD Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_DIRLISTONLY (3) - CURLOPT_FTP_SKIP_PASV_IP (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md index 5d8e8cec1cf..3c3e3965368 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md +++ b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTP_SKIP_PASV_IP Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_FTPPORT (3) - CURLOPT_FTP_USE_EPRT (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md index ea23e59672b..e6cff67af1b 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md +++ b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTP_SSL_CCC Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_FTPSSLAUTH (3) - CURLOPT_PROTOCOLS_STR (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md index a823e4d8db0..b6f178d4186 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTP_USE_EPRT Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_FTPPORT (3) - CURLOPT_FTP_USE_EPSV (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md index 9ac30fe7293..460f5d3bdb2 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_FTP_USE_EPSV Section: 3 Source: libcurl +Protocol: + - FTP See-also: - CURLOPT_FTPPORT (3) - CURLOPT_FTP_USE_EPRT (3) diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md index a43cf10a507..5130ee54856 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_FTP_USE_EPRT (3) - CURLOPT_FTP_USE_EPSV (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md index 29245bd7063..a04b556072b 100644 --- a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md +++ b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_GSSAPI_DELEGATION Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HTTPAUTH (3) - CURLOPT_PROXYAUTH (3) diff --git a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md index 87b1dee8522..d0ee69be46d 100644 --- a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS Section: 3 Source: libcurl +Protocol: + - * See-also: - CURLOPT_CONNECTTIMEOUT_MS (3) - CURLOPT_LOW_SPEED_LIMIT (3) diff --git a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md index 7fe1647c06e..2639ebcd702 100644 --- a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md +++ b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_PROXY (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md index 19f3cca2f88..88751a50384 100644 --- a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md +++ b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HAPROXY_CLIENT_IP Section: 3 Source: libcurl +Protocol: + - * See-also: - CURLOPT_HAPROXYPROTOCOL (3) - CURLOPT_PROXY (3) diff --git a/docs/libcurl/opts/CURLOPT_HEADER.md b/docs/libcurl/opts/CURLOPT_HEADER.md index ed3d88798bd..7dad63afe8e 100644 --- a/docs/libcurl/opts/CURLOPT_HEADER.md +++ b/docs/libcurl/opts/CURLOPT_HEADER.md @@ -4,6 +4,12 @@ SPDX-License-Identifier: curl Title: CURLOPT_HEADER Section: 3 Source: libcurl +Protocol: + - HTTP + - FTP + - IMAP + - POP3 + - SMTP See-also: - CURLOPT_HEADERFUNCTION (3) - CURLOPT_HTTPHEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_HEADERDATA.md b/docs/libcurl/opts/CURLOPT_HEADERDATA.md index 83109af8231..703197d9b88 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERDATA.md +++ b/docs/libcurl/opts/CURLOPT_HEADERDATA.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_HEADERFUNCTION (3) - CURLOPT_WRITEFUNCTION (3) - curl_easy_header (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md index 41d02c3a620..812355f400d 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md @@ -8,6 +8,12 @@ See-also: - CURLOPT_HEADERDATA (3) - CURLOPT_WRITEFUNCTION (3) - curl_easy_header (3) +Protocol: + - HTTP + - FTP + - POP3 + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_HEADEROPT.md b/docs/libcurl/opts/CURLOPT_HEADEROPT.md index 0b1d8b66460..6980a9e6545 100644 --- a/docs/libcurl/opts/CURLOPT_HEADEROPT.md +++ b/docs/libcurl/opts/CURLOPT_HEADEROPT.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HEADEROPT Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HTTPHEADER (3) - CURLOPT_PROXYHEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTS.md b/docs/libcurl/opts/CURLOPT_HSTS.md index fe7106cad48..84afddf34d8 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS.md +++ b/docs/libcurl/opts/CURLOPT_HSTS.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HSTS Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_ALTSVC (3) - CURLOPT_HSTS_CTRL (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md index 0d391318a4e..1232ed789b3 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md +++ b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HSTSREADDATA Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HSTS (3) - CURLOPT_HSTSREADFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md index 763b81dce42..c10f9b03349 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HSTSREADFUNCTION Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HSTS (3) - CURLOPT_HSTSREADDATA (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md index f871f1c495e..c0df683e40a 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HSTSWRITEDATA Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HSTS (3) - CURLOPT_HSTSREADDATA (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md index 9d0dd3013ac..faa6c8c9853 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HSTSWRITEFUNCTION Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HSTS (3) - CURLOPT_HSTSWRITEDATA (3) diff --git a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md index 4a87adc54bc..54bbe9540bb 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md +++ b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HSTS_CTRL Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_ALTSVC (3) - CURLOPT_CONNECT_TO (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md index 447fb6fc3c0..e3eb6b9de04 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md +++ b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTP09_ALLOWED Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HTTP_VERSION (3) - CURLOPT_SSLVERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md index 167c26b2940..db74c6f6cca 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md +++ b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTP200ALIASES Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HTTP09_ALLOWED (3) - CURLOPT_HTTP_VERSION (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.md b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md index cafa39cc58a..8b5336f65f9 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.md +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTPAUTH Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_PASSWORD (3) - CURLOPT_PROXYAUTH (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.md b/docs/libcurl/opts/CURLOPT_HTTPGET.md index 9be9321775a..1051fe8cdb3 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPGET.md +++ b/docs/libcurl/opts/CURLOPT_HTTPGET.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTPGET Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_NOBODY (3) - CURLOPT_POST (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.md b/docs/libcurl/opts/CURLOPT_HTTPHEADER.md index 25895f23ab3..84d729b0370 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.md +++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.md @@ -4,6 +4,10 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTPHEADER Section: 3 Source: libcurl +Protocol: + - HTTP + - SMTP + - IMAP See-also: - CURLOPT_CUSTOMREQUEST (3) - CURLOPT_HEADER (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.md b/docs/libcurl/opts/CURLOPT_HTTPPOST.md index 890bd8f6ff0..aa4ab542b81 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.md +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTPPOST Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_MIMEPOST (3) - CURLOPT_POST (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md index 4f12811ae1c..e2173796aeb 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md +++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTPPROXYTUNNEL Section: 3 Source: libcurl +Protocol: + - * See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYPORT (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md index e0f010d66a0..5e87fcfda5d 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTP_CONTENT_DECODING Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_ACCEPT_ENCODING (3) - CURLOPT_DEBUGFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md index 3c4e06be467..2031075fd02 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTP_TRANSFER_DECODING Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_ACCEPT_ENCODING (3) - CURLOPT_HTTP_CONTENT_DECODING (3) diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md index cab71fd65e0..a3902756059 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_HTTP_VERSION Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_ALTSVC (3) - CURLOPT_HTTP09_ALLOWED (3) diff --git a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md index 93ea4b6d2ce..cdaafcb4837 100644 --- a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md +++ b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md @@ -4,6 +4,9 @@ SPDX-License-Identifier: curl Title: CURLOPT_IGNORE_CONTENT_LENGTH Section: 3 Source: libcurl +Protocol: + - HTTP + - FTP See-also: - CURLOPT_HTTP_VERSION (3) - CURLOPT_MAXFILESIZE_LARGE (3) diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.md b/docs/libcurl/opts/CURLOPT_INFILESIZE.md index 0d7924eab64..2da76012188 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE.md +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CONTENT_LENGTH_UPLOAD_T (3) - CURLOPT_INFILESIZE_LARGE (3) - CURLOPT_UPLOAD (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md index 119d2322c16..a48500fcc96 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_CONTENT_LENGTH_UPLOAD_T (3) - CURLOPT_INFILESIZE (3) - CURLOPT_UPLOAD (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.md b/docs/libcurl/opts/CURLOPT_INTERFACE.md index 9f5822d495e..bccc91dabfd 100644 --- a/docs/libcurl/opts/CURLOPT_INTERFACE.md +++ b/docs/libcurl/opts/CURLOPT_INTERFACE.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_INTERFACE Section: 3 Source: libcurl +Protocol: + - * See-also: - CURLOPT_SOCKOPTFUNCTION (3) - CURLOPT_TCP_NODELAY (3) diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md index 7bb6059ad43..0e1f087937f 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_INTERLEAVEDATA Section: 3 Source: libcurl +Protocol: + - RTSP See-also: - CURLOPT_INTERLEAVEFUNCTION (3) - CURLOPT_RTSP_REQUEST (3) diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md index 758192f110d..0b353cc9629 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_INTERLEAVEDATA (3) - CURLOPT_RTSP_REQUEST (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_IOCTLDATA.md b/docs/libcurl/opts/CURLOPT_IOCTLDATA.md index f34a35338c4..19cd5b3745d 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLDATA.md +++ b/docs/libcurl/opts/CURLOPT_IOCTLDATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_IOCTLFUNCTION (3) - CURLOPT_SEEKFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md index a3e120f3a9a..d23d4ceb7e6 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_IOCTLFUNCTION Section: 3 Source: libcurl +Protocol: + - * See-also: - CURLOPT_IOCTLDATA (3) - CURLOPT_SEEKFUNCTION (3) diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md index a12629614bb..393fd0d4722 100644 --- a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md +++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_HTTP_VERSION (3) - CURLOPT_RESOLVE (3) - CURLOPT_SSLVERSION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md index 5b227a9d703..44fa216d68e 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CRLFILE (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md index 26641312fb0..4dba669943a 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_ISSUERCERT (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md index 0c8b8a8ca41..33ed1fb2122 100644 --- a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md +++ b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RESPONSE_CODE (3) - CURLOPT_FAILONERROR (3) - CURLOPT_HTTPHEADER (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md index ddc8546f92e..7043d3442ca 100644 --- a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md +++ b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_SSH_PRIVATE_KEYFILE (3) - CURLOPT_SSLKEY (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_KRBLEVEL.md b/docs/libcurl/opts/CURLOPT_KRBLEVEL.md index a91f67e13a3..84fa2a6288d 100644 --- a/docs/libcurl/opts/CURLOPT_KRBLEVEL.md +++ b/docs/libcurl/opts/CURLOPT_KRBLEVEL.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_KRBLEVEL (3) - CURLOPT_USE_SSL (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORT.md b/docs/libcurl/opts/CURLOPT_LOCALPORT.md index 0113e43c08b..01f70890378 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORT.md +++ b/docs/libcurl/opts/CURLOPT_LOCALPORT.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_LOCAL_PORT (3) - CURLOPT_INTERFACE (3) - CURLOPT_LOCALPORTRANGE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md index cd84649b0dd..432133188eb 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md +++ b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_INTERFACE (3) - CURLOPT_LOCALPORT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md index 8a4e7ebaf23..39235641849 100644 --- a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md @@ -7,6 +7,11 @@ Source: libcurl See-also: - CURLOPT_PASSWORD (3) - CURLOPT_USERNAME (3) +Protocol: + - IMAP + - LDAP + - POP3 + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md index 64fa45ed417..f9142ff47a2 100644 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_MAX_RECV_SPEED_LARGE (3) - CURLOPT_MAX_SEND_SPEED_LARGE (3) - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md index e7aa94cee9a..9a5c4fd01e2 100644 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md index a3ef13b5a58..456e8011bd1 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_MAIL_FROM (3) - CURLOPT_MAIL_RCPT (3) +Protocol: + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md index 431d1b52bda..45bd3ccf98d 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_MAIL_AUTH (3) - CURLOPT_MAIL_RCPT (3) +Protocol: + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md index 40f42cc3717..7dbb8cddcee 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_MAIL_AUTH (3) - CURLOPT_MAIL_FROM (3) +Protocol: + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md index 83183ee1a7d..13a3712d79f 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_MAIL_FROM (3) - CURLOPT_MAIL_RCPT (3) +Protocol: + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md index 3b84dfdc056..1854010b35a 100644 --- a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md +++ b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_FRESH_CONNECT (3) - CURLOPT_MAXLIFETIME_CONN (3) - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md index 729fa2bae1c..04c9d128196 100644 --- a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md +++ b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md @@ -9,6 +9,8 @@ See-also: - CURLMOPT_MAX_HOST_CONNECTIONS (3) - CURLMOPT_MAX_TOTAL_CONNECTIONS (3) - CURLOPT_MAXREDIRS (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md index 6203bd05e29..aba74ac811a 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_MAXFILESIZE_LARGE (3) - CURLOPT_MAX_RECV_SPEED_LARGE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md index f750c43306b..b1c36d6b02d 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md @@ -7,6 +7,10 @@ Source: libcurl See-also: - CURLOPT_MAXFILESIZE (3) - CURLOPT_MAX_RECV_SPEED_LARGE (3) +Protocol: + - FTP + - HTTP + - MQTT --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md index 429cf3945c5..fb82447ab49 100644 --- a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md +++ b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_FRESH_CONNECT (3) - CURLOPT_MAXAGE_CONN (3) - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.md b/docs/libcurl/opts/CURLOPT_MAXREDIRS.md index 136f9a6db80..93e44b94c56 100644 --- a/docs/libcurl/opts/CURLOPT_MAXREDIRS.md +++ b/docs/libcurl/opts/CURLOPT_MAXREDIRS.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_REDIRECT_COUNT (3) - CURLINFO_REDIRECT_URL (3) - CURLOPT_FOLLOWLOCATION (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md index 26080877d60..3449caa457c 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_MAX_SEND_SPEED_LARGE (3) - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md index e8cf5081d23..74da35216fa 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_MAX_RECV_SPEED_LARGE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.md b/docs/libcurl/opts/CURLOPT_MIMEPOST.md index f681c2a9092..5a81012aab0 100644 --- a/docs/libcurl/opts/CURLOPT_MIMEPOST.md +++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.md @@ -9,6 +9,10 @@ See-also: - CURLOPT_POSTFIELDS (3) - CURLOPT_PUT (3) - curl_mime_init (3) +Protocol: + - HTTP + - SMTP + - IMAP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md index 7f97d78dfc0..183285d5062 100644 --- a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md @@ -7,6 +7,10 @@ Source: libcurl See-also: - CURLOPT_HTTPPOST (3) - CURLOPT_MIMEPOST (3) +Protocol: + - HTTP + - IMAP + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_NETRC.md b/docs/libcurl/opts/CURLOPT_NETRC.md index 023676d0ae8..3b69e0dd7a8 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.md +++ b/docs/libcurl/opts/CURLOPT_NETRC.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_NETRC_FILE (3) - CURLOPT_USERNAME (3) - CURLOPT_USERPWD (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_NETRC_FILE.md b/docs/libcurl/opts/CURLOPT_NETRC_FILE.md index cf27945e7a3..faec392d404 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC_FILE.md +++ b/docs/libcurl/opts/CURLOPT_NETRC_FILE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_NETRC (3) - CURLOPT_PASSWORD (3) - CURLOPT_USERNAME (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md index 733a042f7f5..5ba477d2464 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md +++ b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md @@ -8,6 +8,10 @@ See-also: - CURLOPT_FTP_CREATE_MISSING_DIRS (3) - CURLOPT_NEW_FILE_PERMS (3) - CURLOPT_UPLOAD (3) +Protocol: + - SFTP + - SCP + - FILE --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md index f79a1937d74..6d8c1425760 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md +++ b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md @@ -7,6 +7,10 @@ Source: libcurl See-also: - CURLOPT_NEW_DIRECTORY_PERMS (3) - CURLOPT_UPLOAD (3) +Protocol: + - SFTP + - SCP + - FILE --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.md b/docs/libcurl/opts/CURLOPT_NOBODY.md index 2b7f8967b43..eb1cd36dadd 100644 --- a/docs/libcurl/opts/CURLOPT_NOBODY.md +++ b/docs/libcurl/opts/CURLOPT_NOBODY.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_POSTFIELDS (3) - CURLOPT_REQUEST_TARGET (3) - CURLOPT_UPLOAD (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_NOPROGRESS.md b/docs/libcurl/opts/CURLOPT_NOPROGRESS.md index 14478cf5423..a0b22873f32 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROGRESS.md +++ b/docs/libcurl/opts/CURLOPT_NOPROGRESS.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROGRESSFUNCTION (3) - CURLOPT_VERBOSE (3) - CURLOPT_XFERINFOFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.md b/docs/libcurl/opts/CURLOPT_NOPROXY.md index f5416174927..83d6058d0af 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROXY.md +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_NOPROXY Section: 3 Source: libcurl +Protocol: + - * See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYAUTH (3) diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.md b/docs/libcurl/opts/CURLOPT_NOSIGNAL.md index 6ed291dbea5..c4ed07504ff 100644 --- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.md +++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md index 20446500567..c7ebb902e09 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CLOSESOCKETFUNCTION (3) - CURLOPT_OPENSOCKETFUNCTION (3) - CURLOPT_SOCKOPTFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md index a5a101aae40..282ebfb92b3 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CLOSESOCKETFUNCTION (3) - CURLOPT_OPENSOCKETFUNCTION (3) - CURLOPT_SOCKOPTFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PASSWORD.md index 2551c46a45d..f50bf8fed95 100644 --- a/docs/libcurl/opts/CURLOPT_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PASSWORD.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXYAUTH (3) - CURLOPT_USERNAME (3) - CURLOPT_USERPWD (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md index 7f013f0b887..1dcd2489d0a 100644 --- a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md +++ b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_STDERR (3) - CURLOPT_URL (3) - curl_url_set (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md index 9d563195889..eb6c05c83ad 100644 --- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_CAPATH (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.md b/docs/libcurl/opts/CURLOPT_PIPEWAIT.md index 0d7defa8d82..9f039b6cf01 100644 --- a/docs/libcurl/opts/CURLOPT_PIPEWAIT.md +++ b/docs/libcurl/opts/CURLOPT_PIPEWAIT.md @@ -9,6 +9,8 @@ See-also: - CURLMOPT_PIPELINING (3) - CURLOPT_FORBID_REUSE (3) - CURLOPT_FRESH_CONNECT (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PORT.md b/docs/libcurl/opts/CURLOPT_PORT.md index 1cd40655b55..2dc6cfad03d 100644 --- a/docs/libcurl/opts/CURLOPT_PORT.md +++ b/docs/libcurl/opts/CURLOPT_PORT.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_PRIMARY_PORT (3) - CURLOPT_STDERR (3) - CURLOPT_URL (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_POST.md b/docs/libcurl/opts/CURLOPT_POST.md index 1e605eaeb09..d7e099870a8 100644 --- a/docs/libcurl/opts/CURLOPT_POST.md +++ b/docs/libcurl/opts/CURLOPT_POST.md @@ -4,6 +4,8 @@ SPDX-License-Identifier: curl Title: CURLOPT_POST Section: 3 Source: libcurl +Protocol: + - HTTP See-also: - CURLOPT_HTTPPOST (3) - CURLOPT_POSTFIELDS (3) diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md index da71ecc5250..f53a685b14f 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_POSTFIELDSIZE (3) - CURLOPT_READFUNCTION (3) - CURLOPT_UPLOAD (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md index 41648706b09..0334ae95f46 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_POSTFIELDS (3) - CURLOPT_POSTFIELDSIZE_LARGE (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md index 4f2c5ea3676..1de1c3a3ebc 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_COPYPOSTFIELDS (3) - CURLOPT_POSTFIELDS (3) - CURLOPT_POSTFIELDSIZE (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md index b8c41a83979..a4aa01923cd 100644 --- a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md +++ b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md @@ -7,6 +7,9 @@ Source: libcurl See-also: - CURLOPT_PREQUOTE (3) - CURLOPT_QUOTE (3) +Protocol: + - FTP + - SFTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_POSTREDIR.md b/docs/libcurl/opts/CURLOPT_POSTREDIR.md index b25e335709e..364b94dca26 100644 --- a/docs/libcurl/opts/CURLOPT_POSTREDIR.md +++ b/docs/libcurl/opts/CURLOPT_POSTREDIR.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_FOLLOWLOCATION (3) - CURLOPT_MAXREDIRS (3) - CURLOPT_POSTFIELDS (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PREQUOTE.md b/docs/libcurl/opts/CURLOPT_PREQUOTE.md index 129cd6c8e3f..c3bbb16abef 100644 --- a/docs/libcurl/opts/CURLOPT_PREQUOTE.md +++ b/docs/libcurl/opts/CURLOPT_PREQUOTE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_POSTQUOTE (3) - CURLOPT_QUOTE (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PREREQDATA.md b/docs/libcurl/opts/CURLOPT_PREREQDATA.md index c3b351d0516..a575e1563de 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQDATA.md +++ b/docs/libcurl/opts/CURLOPT_PREREQDATA.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_PRIMARY_IP (3) - CURLINFO_PRIMARY_PORT (3) - CURLOPT_PREREQFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md index 4df94cccde1..454935f82bb 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_PRIMARY_IP (3) - CURLINFO_PRIMARY_PORT (3) - CURLOPT_PREREQDATA (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PRE_PROXY.md b/docs/libcurl/opts/CURLOPT_PRE_PROXY.md index 252abfbc23c..146863472d9 100644 --- a/docs/libcurl/opts/CURLOPT_PRE_PROXY.md +++ b/docs/libcurl/opts/CURLOPT_PRE_PROXY.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_HTTPPROXYTUNNEL (3) - CURLOPT_PROXY (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PRIVATE.md b/docs/libcurl/opts/CURLOPT_PRIVATE.md index 969f8584327..cbe305efafd 100644 --- a/docs/libcurl/opts/CURLOPT_PRIVATE.md +++ b/docs/libcurl/opts/CURLOPT_PRIVATE.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_PRIVATE (3) - CURLOPT_STDERR (3) - CURLOPT_VERBOSE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md index 01e006d4840..b3ebd7dd7fa 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md +++ b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_PROGRESSFUNCTION (3) - CURLOPT_XFERINFOFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md index 88e5b189b4c..8f8fafffad5 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_NOPROGRESS (3) - CURLOPT_VERBOSE (3) - CURLOPT_XFERINFOFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.md b/docs/libcurl/opts/CURLOPT_PROTOCOLS.md index b9258892c5f..ca67d728e5f 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS.md +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DEFAULT_PROTOCOL (3) - CURLOPT_REDIR_PROTOCOLS (3) - CURLOPT_URL (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md index cc13c529a49..3b45e2f3c95 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_REDIR_PROTOCOLS_STR (3) - CURLOPT_URL (3) - curl_version_info (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY.md b/docs/libcurl/opts/CURLOPT_PROXY.md index fdc9878092f..cea12e94743 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PRE_PROXY (3) - CURLOPT_PROXYPORT (3) - CURLOPT_PROXYTYPE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.md b/docs/libcurl/opts/CURLOPT_PROXYAUTH.md index b52346255d6..58f6f0b6b29 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYAUTH.md +++ b/docs/libcurl/opts/CURLOPT_PROXYAUTH.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_PROXYPORT (3) - CURLOPT_PROXYTYPE (3) - CURLOPT_PROXYUSERPWD (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXYHEADER.md b/docs/libcurl/opts/CURLOPT_PROXYHEADER.md index 21494e15093..4f555925d54 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYHEADER.md +++ b/docs/libcurl/opts/CURLOPT_PROXYHEADER.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_HEADEROPT (3) - CURLOPT_HTTPHEADER (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md index bc931666f72..7b2535f091b 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PASSWORD (3) - CURLOPT_PROXYAUTH (3) - CURLOPT_PROXYUSERNAME (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXYPORT.md b/docs/libcurl/opts/CURLOPT_PROXYPORT.md index d2193ff0968..8f47c30e8a6 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYPORT.md +++ b/docs/libcurl/opts/CURLOPT_PROXYPORT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PORT (3) - CURLOPT_PROXY (3) - CURLOPT_PROXYTYPE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXYTYPE.md index 96d9269bfff..c9d98c2256d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXYTYPE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYPORT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md index 330a762d4ff..02fa29305f7 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXYAUTH (3) - CURLOPT_PROXYPASSWORD (3) - CURLOPT_USERNAME (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md index 7a49119c63b..530eec3be9e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXYPASSWORD (3) - CURLOPT_PROXYTYPE (3) - CURLOPT_PROXYUSERNAME (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md index dac73f38619..543f20d027e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md @@ -14,6 +14,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md index 2706dec1f19..8022dff2621 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md @@ -14,6 +14,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md index 6d649045fff..763214eecba 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_PROXY_CAINFO (3) - CURLOPT_PROXY_SSL_VERIFYHOST (3) - CURLOPT_STDERR (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md index 51d1728eb4a..47762dcac78 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md index 093dadfd3b5..3ffe995a6cb 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md index 4f4e153d440..34eb8a9c507 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md index 7750dd24421..b2c7255e0b4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY_SSLKEY (3) - CURLOPT_SSH_PRIVATE_KEYFILE (3) - CURLOPT_SSLKEY (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md index 6d97bf48ac7..8cfe5c34058 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_PROXY_CAPATH (3) - CURLOPT_PROXY_SSL_VERIFYHOST (3) - CURLOPT_PROXY_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md index 57a8161e3fb..157c62310e4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYTYPE (3) - CURLOPT_SERVICE_NAME (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md index 343d1363bab..9b0182b68e5 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY_SSLCERTTYPE (3) - CURLOPT_PROXY_SSLKEY (3) - CURLOPT_SSLCERT (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md index f019d7c3563..8d1f10b4dbc 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY_SSLCERT (3) - CURLOPT_PROXY_SSLKEY (3) - CURLOPT_SSLCERTTYPE (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md index 7d6bc6fc869..ca5e62119f1 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY_SSLCERTTYPE (3) - CURLOPT_PROXY_SSLKEY (3) - CURLOPT_SSLCERT_BLOB (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md index 0ef09a4d959..450fcb66ff4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSLCERT (3) - CURLOPT_SSLKEY (3) - CURLOPT_SSLKEYTYPE (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md index 03264dbf31f..ffd2e92d85f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY_SSLCERT (3) - CURLOPT_PROXY_SSLKEY (3) - CURLOPT_SSLKEYTYPE (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md index 6771653245a..ae941d17baf 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_SSLKEY (3) - CURLOPT_SSLKEYTYPE (3) - CURLOPT_SSLKEY_BLOB (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md index f59240badb4..ae9a8ab92f6 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_IPRESOLVE (3) - CURLOPT_SSLVERSION (3) - CURLOPT_USE_SSL (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md index 11bce717c19..4cb07789937 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSLVERSION (3) - CURLOPT_SSL_CIPHER_LIST (3) - CURLOPT_TLS13_CIPHERS (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md index a2aa05a49cb..b1fabdcd28f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY_SSL_CIPHER_LIST (3) - CURLOPT_SSLVERSION (3) - CURLOPT_SSL_CIPHER_LIST (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md index 40c588b705f..eb7b0db0488 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY_CAINFO (3) - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md index 916ae90dd31..0df8236a61f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md index 605379a0162..a6c429caf7e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSLVERSION (3) - CURLOPT_SSL_CIPHER_LIST (3) - CURLOPT_TLS13_CIPHERS (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md index e78859052be..8cb79bfa4c3 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY_TLSAUTH_USERNAME (3) - CURLOPT_TLSAUTH_TYPE (3) - CURLOPT_TLSAUTH_USERNAME (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md index 85ee86d73ee..03b4a2bae18 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY_TLSAUTH_USERNAME (3) - CURLOPT_TLSAUTH_PASSWORD (3) - CURLOPT_TLSAUTH_USERNAME (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md index a50c1d54769..59650227882 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PROXY_TLSAUTH_TYPE (3) - CURLOPT_TLSAUTH_PASSWORD (3) - CURLOPT_TLSAUTH_TYPE (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md index 233cad72007..b9f39be322e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_HTTPPROXYTUNNEL (3) - CURLOPT_PROXY (3) - CURLOPT_TRANSFERTEXT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PUT.md b/docs/libcurl/opts/CURLOPT_PUT.md index 7ba4fc6096b..c0cfb3802ab 100644 --- a/docs/libcurl/opts/CURLOPT_PUT.md +++ b/docs/libcurl/opts/CURLOPT_PUT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_MIMEPOST (3) - CURLOPT_POSTFIELDS (3) - CURLOPT_UPLOAD (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md index b3fd105625f..35681bfd95d 100644 --- a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md +++ b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_FAILONERROR (3) - CURLOPT_RESOLVE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.md b/docs/libcurl/opts/CURLOPT_QUOTE.md index 7efe0d8e2e8..098428a669d 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.md +++ b/docs/libcurl/opts/CURLOPT_QUOTE.md @@ -9,6 +9,9 @@ See-also: - CURLOPT_DIRLISTONLY (3) - CURLOPT_POSTQUOTE (3) - CURLOPT_PREQUOTE (3) +Protocol: + - FTP + - SFTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md index 0f05337fab2..c00bf38efaa 100644 --- a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md +++ b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_EGDSOCKET (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RANGE.md b/docs/libcurl/opts/CURLOPT_RANGE.md index a770c244f29..cbf77efcd84 100644 --- a/docs/libcurl/opts/CURLOPT_RANGE.md +++ b/docs/libcurl/opts/CURLOPT_RANGE.md @@ -9,6 +9,12 @@ See-also: - CURLOPT_MAXFILESIZE_LARGE (3) - CURLOPT_MAX_RECV_SPEED_LARGE (3) - CURLOPT_RESUME_FROM (3) +Protocol: + - HTTP + - FTP + - FILE + - RTSP + - SFTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_READDATA.md b/docs/libcurl/opts/CURLOPT_READDATA.md index 94086647dd7..f08cc692856 100644 --- a/docs/libcurl/opts/CURLOPT_READDATA.md +++ b/docs/libcurl/opts/CURLOPT_READDATA.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_READFUNCTION (3) - CURLOPT_WRITEDATA (3) - CURLOPT_WRITEFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.md b/docs/libcurl/opts/CURLOPT_READFUNCTION.md index b7eddbc48b9..cc794662599 100644 --- a/docs/libcurl/opts/CURLOPT_READFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_UPLOAD (3) - CURLOPT_UPLOAD_BUFFERSIZE (3) - CURLOPT_WRITEFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md index 5c03460c50b..1addcf6378a 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_DEFAULT_PROTOCOL (3) - CURLOPT_PROTOCOLS (3) - CURLOPT_REDIR_PROTOCOLS_STR (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md index 10a0f015ebc..e39f4bce3e0 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_PROTOCOLS (3) - CURLOPT_PROTOCOLS_STR (3) - CURLOPT_REDIR_PROTOCOLS (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_REFERER.md b/docs/libcurl/opts/CURLOPT_REFERER.md index fdf33903819..92f0c3693bb 100644 --- a/docs/libcurl/opts/CURLOPT_REFERER.md +++ b/docs/libcurl/opts/CURLOPT_REFERER.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_REFERER (3) - CURLOPT_HTTPHEADER (3) - CURLOPT_USERAGENT (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md index 0d72e146db7..43ee37f30bd 100644 --- a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md +++ b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_HTTPGET (3) - CURLOPT_PATH_AS_IS (3) - CURLOPT_URL (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.md b/docs/libcurl/opts/CURLOPT_RESOLVE.md index 39250f55ff0..4c72750cb62 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVE.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CONNECT_TO (3) - CURLOPT_DNS_CACHE_TIMEOUT (3) - CURLOPT_IPRESOLVE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md index 219d0bd1ba2..a90bddb73df 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_PREREQFUNCTION (3) - CURLOPT_RESOLVER_START_FUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md index e4d0a0b8e3f..01e34bd7051 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_PREREQFUNCTION (3) - CURLOPT_RESOLVER_START_DATA (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM.md b/docs/libcurl/opts/CURLOPT_RESUME_FROM.md index fd3bee4d953..ff296b23923 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM.md +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_INFILESIZE (3) - CURLOPT_RANGE (3) - CURLOPT_RESUME_FROM_LARGE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md index e7e8d5dfe32..f91a94e0502 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_INFILESIZE_LARGE (3) - CURLOPT_RANGE (3) - CURLOPT_RESUME_FROM (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md index d1ef05ea8a2..60594d88cab 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md @@ -9,6 +9,8 @@ See-also: - CURLINFO_RTSP_SERVER_CSEQ (3) - CURLOPT_RTSP_REQUEST (3) - CURLOPT_RTSP_SERVER_CSEQ (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md index a9ff2160703..ca41a59a9cc 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_RTSP_SESSION_ID (3) - CURLOPT_RTSP_STREAM_URI (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md index 62b142205ff..598a3cbbd2c 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_RTSP_SERVER_CSEQ (3) - CURLOPT_RTSP_CLIENT_CSEQ (3) - CURLOPT_RTSP_STREAM_URI (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md index 1373c38231c..952042136b2 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_RTSP_REQUEST (3) - CURLOPT_RTSP_STREAM_URI (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md index 8a28d72727c..af9af155139 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_RTSP_REQUEST (3) - CURLOPT_RTSP_TRANSPORT (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md index d33ddea8f10..5ae09410fd1 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_RTSP_REQUEST (3) - CURLOPT_RTSP_SESSION_ID (3) +Protocol: + - RTSP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md index b32732f262d..98b8ae3bd5d 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md +++ b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PASSWORD (3) - CURLOPT_USERNAME (3) - CURLOPT_USERPWD (3) +Protocol: + - IMAP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SASL_IR.md b/docs/libcurl/opts/CURLOPT_SASL_IR.md index 2e421da9a32..e99de653a98 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_IR.md +++ b/docs/libcurl/opts/CURLOPT_SASL_IR.md @@ -8,6 +8,9 @@ See-also: - CURLOPT_MAIL_AUTH (3) - CURLOPT_MAIL_FROM (3) - CURLOPT_SASL_AUTHZID (3) +Protocol: + - SMTP + - IMAP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.md b/docs/libcurl/opts/CURLOPT_SEEKDATA.md index 563db558d26..05c49d579df 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKDATA.md +++ b/docs/libcurl/opts/CURLOPT_SEEKDATA.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_IOCTLFUNCTION (3) - CURLOPT_SEEKFUNCTION (3) - CURLOPT_STDERR (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md index 2744df85337..c8c8bbffdda 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_IOCTLFUNCTION (3) - CURLOPT_SEEKDATA (3) - CURLOPT_STDERR (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md index e96dd473666..a90506d2e90 100644 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md @@ -8,6 +8,13 @@ See-also: - CURLOPT_CONNECTTIMEOUT (3) - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_TIMEOUT (3) +Protocol: + - FTP + - IMAP + - POP3 + - SMTP + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md index 6cd4514a170..27f95ac174c 100644 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md @@ -8,6 +8,13 @@ See-also: - CURLOPT_CONNECTTIMEOUT (3) - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_TIMEOUT (3) +Protocol: + - FTP + - IMAP + - POP3 + - SMTP + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md index 9c772e98ec4..769da3fef48 100644 --- a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md +++ b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYTYPE (3) - CURLOPT_PROXY_SERVICE_NAME (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SHARE.md b/docs/libcurl/opts/CURLOPT_SHARE.md index 38d879328f7..5256a4ebae9 100644 --- a/docs/libcurl/opts/CURLOPT_SHARE.md +++ b/docs/libcurl/opts/CURLOPT_SHARE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_COOKIE (3) - CURLSHOPT_SHARE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md index bde40109c85..cc09a80aa0b 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_OPENSOCKETFUNCTION (3) - CURLOPT_SOCKOPTFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md index 5538033b666..919161f0849 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_OPENSOCKETFUNCTION (3) - CURLOPT_SEEKFUNCTION (3) - CURLOPT_SOCKOPTDATA (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md index 374d566fd34..07aec2b443c 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYTYPE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md index 8c3891dfde2..028040d73a2 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_PROXY (3) - CURLOPT_SOCKS5_GSSAPI_SERVICE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md index 28062fc0c4d..67ede5a6aac 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYTYPE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md index fb07fa4376f..027a5129cb0 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md +++ b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md @@ -8,6 +8,9 @@ See-also: - CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3) - CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3) - CURLOPT_SSH_PUBLIC_KEYFILE (3) +Protocol: + - SFP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md index d784e3dc056..26b0ab2a904 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md @@ -7,6 +7,9 @@ Source: libcurl See-also: - CURLOPT_ACCEPT_ENCODING (3) - CURLOPT_TRANSFER_ENCODING (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md index 7c22ff5dee6..1cf56b33dd4 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md @@ -6,6 +6,9 @@ Section: 3 Source: libcurl See-also: - CURLOPT_SSH_HOSTKEYFUNCTION (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md index 40d720edf0e..d0d909248f8 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md @@ -7,6 +7,9 @@ Source: libcurl See-also: - CURLOPT_SSH_HOSTKEYDATA (3) - CURLOPT_SSH_KNOWNHOSTS (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md index 6f439522961..6dcf99e11a6 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md @@ -9,6 +9,9 @@ See-also: - CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3) - CURLOPT_SSH_KNOWNHOSTS (3) - CURLOPT_SSH_PUBLIC_KEYFILE (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md index a4463e8ea45..3cd506a246f 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md @@ -8,6 +8,9 @@ See-also: - CURLOPT_SSH_AUTH_TYPES (3) - CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3) - CURLOPT_SSH_PUBLIC_KEYFILE (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md index 24249aa0415..5a0838cc28e 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_SSH_KEYDATA (3) - CURLOPT_SSH_KNOWNHOSTS (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md index 90cd8bfb514..b8ed95e96d1 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md @@ -7,6 +7,9 @@ Source: libcurl See-also: - CURLOPT_SSH_KEYDATA (3) - CURLOPT_SSH_KNOWNHOSTS (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md index 1f1f2bc8d77..8905ccccc03 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md @@ -7,6 +7,9 @@ Source: libcurl See-also: - CURLOPT_SSH_AUTH_TYPES (3) - CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md index 11dda139798..f516501e8be 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md +++ b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md @@ -7,6 +7,9 @@ Source: libcurl See-also: - CURLOPT_SSH_AUTH_TYPES (3) - CURLOPT_SSH_PUBLIC_KEYFILE (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md index 9f110c7d6b6..62983eb23a6 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md +++ b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md @@ -7,6 +7,9 @@ Source: libcurl See-also: - CURLOPT_SSH_AUTH_TYPES (3) - CURLOPT_SSH_PRIVATE_KEYFILE (3) +Protocol: + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.md b/docs/libcurl/opts/CURLOPT_SSLCERT.md index dda3b940294..69d28672ba9 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_KEYPASSWD (3) - CURLOPT_SSLCERTTYPE (3) - CURLOPT_SSLKEY (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md index 948365b71b1..a8c7c589b4f 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_SSLCERT (3) - CURLOPT_SSLKEY (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md index db54c40b11b..ec37a145390 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_KEYPASSWD (3) - CURLOPT_SSLCERTTYPE (3) - CURLOPT_SSLKEY (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.md b/docs/libcurl/opts/CURLOPT_SSLENGINE.md index f8b2a623e36..96fe05b568f 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE.md +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_SSL_ENGINES (3) - CURLOPT_SSLENGINE_DEFAULT (3) - CURLOPT_SSLKEY (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md index 2d7958522b8..dc1851533f3 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_SSLCERT (3) - CURLOPT_SSLENGINE (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.md b/docs/libcurl/opts/CURLOPT_SSLKEY.md index b130eb84cb9..f6777bbc1aa 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_SSLCERT (3) - CURLOPT_SSLKEYTYPE (3) - CURLOPT_SSLKEY_BLOB (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md index a13865a9d30..27cfb37a546 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY_SSLKEYTYPE (3) - CURLOPT_SSLCERT (3) - CURLOPT_SSLKEY (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md index 35107700ac2..833a94a07bb 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_SSLKEY (3) - CURLOPT_SSLKEYTYPE (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_SSLVERSION.md index 08eee343367..5978cd3071c 100644 --- a/docs/libcurl/opts/CURLOPT_SSLVERSION.md +++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_IPRESOLVE (3) - CURLOPT_PROXY_SSLVERSION (3) - CURLOPT_USE_SSL (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md index c07e7203a9b..f337200be86 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSLVERSION (3) - CURLOPT_TLS13_CIPHERS (3) - CURLOPT_USE_SSL (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md index b7d1325825f..76483f41c54 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_SSLVERSION (3) - CURLOPT_SSL_CTX_FUNCTION (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md index d2eb2b1bb35..995f7295ea5 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_SSL_CTX_DATA (3) - CURLOPT_SSL_VERIFYPEER (3) - CURLOPT_CAINFO (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md index 49d216bee76..9b22633263e 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md +++ b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_SSL_CIPHER_LIST (3) - CURLOPT_SSL_OPTIONS (3) - CURLOPT_TLS13_CIPHERS (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md index 1638942e475..8ed88b6b370 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_SSL_ENABLE_NPN (3) - CURLOPT_SSL_OPTIONS (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md index 4e34e0764a5..869c70678e2 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_SSL_ENABLE_ALPN (3) - CURLOPT_SSL_OPTIONS (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md index 1a1110acae0..754c26fddef 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md +++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_TCP_FASTOPEN (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md index 94732a967c7..8fcc721fec1 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY_SSL_OPTIONS (3) - CURLOPT_SSLVERSION (3) - CURLOPT_SSL_CIPHER_LIST (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md index 0de33f1a0b7..677ef6ca276 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md +++ b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_MAXAGE_CONN (3) - CURLOPT_MAXLIFETIME_CONN (3) - CURLOPT_SSLVERSION (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md index 110cbd10600..e96e4be530c 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CAINFO (3) - CURLOPT_PINNEDPUBLICKEY (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md index 5f0832738c1..e636b166162 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYHOST (3) - CURLOPT_PROXY_SSL_VERIFYPEER (3) - CURLOPT_SSL_VERIFYHOST (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md index 3bc2c793cb0..392fc2f6786 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CAINFO (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_STDERR.md b/docs/libcurl/opts/CURLOPT_STDERR.md index d90df253bcc..58f6c39fa70 100644 --- a/docs/libcurl/opts/CURLOPT_STDERR.md +++ b/docs/libcurl/opts/CURLOPT_STDERR.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_NOPROGRESS (3) - CURLOPT_VERBOSE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md index b0f4c9f0ed9..4ad479c94ba 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_HTTP_VERSION (3) - CURLOPT_STREAM_DEPENDS_E (3) - CURLOPT_STREAM_WEIGHT (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md index da83e93d47b..dddd89c3872 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_HTTP_VERSION (3) - CURLOPT_STREAM_DEPENDS (3) - CURLOPT_STREAM_WEIGHT (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md index af2ecff7c6c..27684a6c1fa 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PIPEWAIT (3) - CURLOPT_STREAM_DEPENDS (3) - CURLOPT_STREAM_DEPENDS_E (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md index e1dd7e56ab8..2c6bdaad31d 100644 --- a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md +++ b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_HEADER (3) - CURLOPT_HTTPPROXYTUNNEL (3) - CURLOPT_PROXY (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md index c93d41f8ed1..bf85e1ffcf8 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md +++ b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_SSL_FALSESTART (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md index 17809794d9a..1ad0be145dd 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_MAX_RECV_SPEED_LARGE (3) - CURLOPT_TCP_KEEPIDLE (3) - CURLOPT_TCP_KEEPINTVL (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md index 3e0db307d34..3b0f48facaf 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TCP_KEEPINTVL (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md index f3a2b4df8e6..016f0b97c18 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TCP_KEEPIDLE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md index a56401941d3..84eb871e754 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_BUFFERSIZE (3) - CURLOPT_SOCKOPTFUNCTION (3) - CURLOPT_TCP_KEEPALIVE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md index 281ad831526..138c8a586e1 100644 --- a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_HTTPHEADER (3) - CURLOPT_QUOTE (3) +Protocol: + - TELNET --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md index 8772c51963a..810548d66b5 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_MAXFILESIZE (3) +Protocol: + - TFTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md index 9571ebd6964..93a0cbc27be 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_TFTP_BLKSIZE (3) +Protocol: + - TFTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TIMECONDITION.md b/docs/libcurl/opts/CURLOPT_TIMECONDITION.md index 8b42fc8bbcc..3c9d332153a 100644 --- a/docs/libcurl/opts/CURLOPT_TIMECONDITION.md +++ b/docs/libcurl/opts/CURLOPT_TIMECONDITION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLINFO_FILETIME (3) - CURLOPT_TIMEVALUE (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_TIMEOUT.md index 960b7692c7d..9364c8e3541 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TIMEOUT_MS (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md index dbc6ccf72c6..d01323015bd 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TIMEOUT (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md index bdd519003b8..03f7951ad5a 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_TIMECONDITION (3) - CURLOPT_TIMEVALUE_LARGE (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md index 1b01a6b2248..b12dc4eb0d0 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md @@ -8,6 +8,8 @@ See-also: - CURLINFO_FILETIME (3) - CURLOPT_TIMECONDITION (3) - CURLOPT_TIMEVALUE (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md index 39dabc44559..3b9eee82d4c 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_SSLVERSION (3) - CURLOPT_SSL_CIPHER_LIST (3) - CURLOPT_USE_SSL (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md index 8f5c89d5822..f2670815dda 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PROXY_TLSAUTH_PASSWORD (3) - CURLOPT_TLSAUTH_TYPE (3) - CURLOPT_TLSAUTH_USERNAME (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md index 066fc039464..fe7cdcd2fe4 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_TLSAUTH_PASSWORD (3) - CURLOPT_TLSAUTH_USERNAME (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md index 9075163d88c..b091ebfac4f 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_TLSAUTH_PASSWORD (3) - CURLOPT_TLSAUTH_TYPE (3) +Protocol: + - TLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TRAILERDATA.md b/docs/libcurl/opts/CURLOPT_TRAILERDATA.md index 28546ca78d6..380a57913df 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERDATA.md +++ b/docs/libcurl/opts/CURLOPT_TRAILERDATA.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_TRAILERFUNCTION (3) - CURLOPT_WRITEFUNCTION (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md index 4eaee1f7d4c..ebbb70bde5e 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_TRAILERDATA (3) - CURLOPT_WRITEFUNCTION (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md index 7f4798e992f..7a33a91f89c 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md +++ b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_CRLF (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md index 52e37d61bb3..7c5482d8908 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md +++ b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_ACCEPT_ENCODING (3) - CURLOPT_HTTP_TRANSFER_DECODING (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md index 0783422b96f..40fd80a182a 100644 --- a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md +++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_ABSTRACT_UNIX_SOCKET (3) - CURLOPT_OPENSOCKETFUNCTION (3) - unix (7) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md index 0ce080ae1ae..d6edd0714e0 100644 --- a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_MAXREDIRS (3) - CURLOPT_REDIR_PROTOCOLS_STR (3) - CURLOPT_USERPWD (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md index 11833c29e4b..6692920b754 100644 --- a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md +++ b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md @@ -6,6 +6,8 @@ Section: 3 Source: libcurl See-also: - CURLOPT_TCP_KEEPALIVE (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD.md b/docs/libcurl/opts/CURLOPT_UPLOAD.md index 0d4d8aadfdd..4fdd68a6380 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD.md +++ b/docs/libcurl/opts/CURLOPT_UPLOAD.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_INFILESIZE_LARGE (3) - CURLOPT_PUT (3) - CURLOPT_READFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md index 0291fcf0056..5c02c283bfc 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md +++ b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_BUFFERSIZE (3) - CURLOPT_READFUNCTION (3) - CURLOPT_TCP_NODELAY (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_URL.md b/docs/libcurl/opts/CURLOPT_URL.md index f0650a9e1c7..ac663c9a053 100644 --- a/docs/libcurl/opts/CURLOPT_URL.md +++ b/docs/libcurl/opts/CURLOPT_URL.md @@ -14,6 +14,8 @@ See-also: - curl_easy_perform (3) - curl_url_get (3) - curl_url_set (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.md b/docs/libcurl/opts/CURLOPT_USERAGENT.md index 4547da53298..e637e6a4993 100644 --- a/docs/libcurl/opts/CURLOPT_USERAGENT.md +++ b/docs/libcurl/opts/CURLOPT_USERAGENT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_HTTPHEADER (3) - CURLOPT_REFERER (3) - CURLOPT_REQUEST_TARGET (3) +Protocol: + - HTTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_USERNAME.md b/docs/libcurl/opts/CURLOPT_USERNAME.md index 7c53fdf3a68..054c250dce4 100644 --- a/docs/libcurl/opts/CURLOPT_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_USERNAME.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_PASSWORD (3) - CURLOPT_PROXYAUTH (3) - CURLOPT_USERPWD (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.md b/docs/libcurl/opts/CURLOPT_USERPWD.md index 366593fbb9f..2537ab23fc3 100644 --- a/docs/libcurl/opts/CURLOPT_USERPWD.md +++ b/docs/libcurl/opts/CURLOPT_USERPWD.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_PASSWORD (3) - CURLOPT_PROXYUSERPWD (3) - CURLOPT_USERNAME (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_USE_SSL.md b/docs/libcurl/opts/CURLOPT_USE_SSL.md index 9cb5eb7ff40..70fade3c3ce 100644 --- a/docs/libcurl/opts/CURLOPT_USE_SSL.md +++ b/docs/libcurl/opts/CURLOPT_USE_SSL.md @@ -8,6 +8,11 @@ See-also: - CURLOPT_PROXY_SSLVERSION (3) - CURLOPT_SSLVERSION (3) - CURLOPT_SSL_OPTIONS (3) +Protocol: + - FTP + - SMTP + - POP3 + - IMAP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.md b/docs/libcurl/opts/CURLOPT_VERBOSE.md index 83855be3b2d..492a1108ee4 100644 --- a/docs/libcurl/opts/CURLOPT_VERBOSE.md +++ b/docs/libcurl/opts/CURLOPT_VERBOSE.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_ERRORBUFFER (3) - CURLOPT_STDERR (3) - curl_global_trace (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md index b0130dbed9b..1dbcf68ff3f 100644 --- a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md +++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_CHUNK_END_FUNCTION (3) - CURLOPT_FNMATCH_FUNCTION (3) - CURLOPT_URL (3) +Protocol: + - FTP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.md b/docs/libcurl/opts/CURLOPT_WRITEDATA.md index a4a4a238b80..c42ac401c94 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.md +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_HEADERDATA (3) - CURLOPT_READDATA (3) - CURLOPT_WRITEFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md index 6a7e023b90e..448002353dc 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_HEADERFUNCTION (3) - CURLOPT_READFUNCTION (3) - CURLOPT_WRITEDATA (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md index c1157e046e6..1c3b8bcb33d 100644 --- a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_CONNECT_ONLY (3) - curl_ws_recv (3) - curl_ws_send (3) +Protocol: + - WS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.md b/docs/libcurl/opts/CURLOPT_XFERINFODATA.md index 78616676c66..09248e15bcd 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFODATA.md +++ b/docs/libcurl/opts/CURLOPT_XFERINFODATA.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_NOPROGRESS (3) - CURLOPT_VERBOSE (3) - CURLOPT_XFERINFOFUNCTION (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md index 41bd89a2747..f94971f520a 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md @@ -7,6 +7,8 @@ Source: libcurl See-also: - CURLOPT_NOPROGRESS (3) - CURLOPT_XFERINFODATA (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md index 7f036d98c3d..396948b49e1 100644 --- a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md @@ -7,6 +7,12 @@ Source: libcurl See-also: - CURLOPT_MAIL_AUTH (3) - CURLOPT_USERNAME (3) +Protocol: + - HTTP + - IMAP + - LDAP + - POP3 + - SMTP --- # NAME diff --git a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md index 47fbae963ab..fbfa2230796 100644 --- a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md +++ b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md @@ -9,6 +9,8 @@ See-also: - curl_share_cleanup (3) - curl_share_init (3) - curl_share_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLSHOPT_SHARE.md b/docs/libcurl/opts/CURLSHOPT_SHARE.md index 7866640ccc6..d2cfef1743f 100644 --- a/docs/libcurl/opts/CURLSHOPT_SHARE.md +++ b/docs/libcurl/opts/CURLSHOPT_SHARE.md @@ -9,6 +9,8 @@ See-also: - curl_share_cleanup (3) - curl_share_init (3) - curl_share_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md index 10db90ebce4..6853b676155 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md +++ b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md @@ -9,6 +9,8 @@ See-also: - curl_share_cleanup (3) - curl_share_init (3) - curl_share_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md index e6c2340135d..898e40bb08d 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md +++ b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md @@ -9,6 +9,8 @@ See-also: - curl_share_cleanup (3) - curl_share_init (3) - curl_share_setopt (3) +Protocol: + - * --- # NAME diff --git a/docs/libcurl/opts/CURLSHOPT_USERDATA.md b/docs/libcurl/opts/CURLSHOPT_USERDATA.md index 9349cebbcf6..3969e9e5a17 100644 --- a/docs/libcurl/opts/CURLSHOPT_USERDATA.md +++ b/docs/libcurl/opts/CURLSHOPT_USERDATA.md @@ -9,6 +9,8 @@ See-also: - curl_share_cleanup (3) - curl_share_init (3) - curl_share_setopt (3) +Protocol: + - * --- # NAME diff --git a/scripts/cd2nroff b/scripts/cd2nroff index 5d699ca0fff..35baa450f0f 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -98,6 +98,7 @@ sub outseealso { sub single { my @seealso; + my @proto; my $d; my ($f)=@_; my $copyright; @@ -105,6 +106,7 @@ sub single { my $fh; my $line; my $salist; + my $protolist; my $section; my $source; my $spdx; @@ -150,12 +152,24 @@ sub single { return 2; } $salist = 1; + $protolist = 0; + } + elsif(/^Protocol:/i) { + $salist = 0; + $protolist = 1; } elsif(/^ +- (.*)/i) { - # the only list we support is the see-also + # the only lists we support are see-also and protocol if($salist) { push @seealso, $1; } + elsif($protolist) { + push @proto, $1; + } + else { + print STDERR "$f:$line:1:ERROR: list item without owner?\n"; + return 2; + } } # REUSE-IgnoreStart elsif(/^C: (.*)/i) { @@ -187,6 +201,10 @@ sub single { print STDERR "$f:$line:1:ERROR: no 'SPDX-License-Identifier:' field present\n"; return 2; } + if(!$proto[0] && ($section == 3)) { + printf STDERR "$f:$line:1:ERROR: missing Protocol:\n"; + exit 2; + } last; } else { From 3ff3c0925d7a989c0c1bcc62b84a17cac7e1360d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Mar 2024 15:32:26 +0100 Subject: [PATCH 492/509] docs/libcurl: cleanups - CURLINFO_TLS_SESSION.md: remove mention of NSS - CURLINFO_TLS_SSL_PTR.md: remove NSS leftover - CURLOPT_CAINFO.md: drop mention of backends not supporting this - CURLOPT_CAPATH.md: wolfSSL also supports this Closes #13166 --- docs/libcurl/opts/CURLINFO_TLS_SESSION.md | 4 ++-- docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md | 4 ---- docs/libcurl/opts/CURLOPT_CAINFO.md | 4 +--- docs/libcurl/opts/CURLOPT_CAPATH.md | 3 +-- 4 files changed, 4 insertions(+), 11 deletions(-) diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md index f7a6304d263..edeabae10b1 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md @@ -69,8 +69,8 @@ int main(void) # AVAILABILITY -Added in 7.34.0. Deprecated since 7.48.0 and supported OpenSSL, GnuTLS, and -NSS only up until this version was released. +Added in 7.34.0. Deprecated since 7.48.0 and supported by OpenSSL and GnuTLS +only up until this version was released. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md index b3045bebbd9..a4a45d0f3aa 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md @@ -63,10 +63,6 @@ the active ("in use") SSL connection, with the following underlying types: **gnutls_session_t** -## NSS - -**PRFileDesc *** - ## OpenSSL CURLINFO_TLS_SESSION(3): **SSL_CTX *** diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.md b/docs/libcurl/opts/CURLOPT_CAINFO.md index 2f5d2c84bde..565e6c4274e 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO.md @@ -79,9 +79,7 @@ int main(void) # AVAILABILITY -For the SSL engines that do not support certificate files the -CURLOPT_CAINFO(3) option is ignored. Schannel support added in libcurl -7.60. +Schannel support added in libcurl 7.60. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.md b/docs/libcurl/opts/CURLOPT_CAPATH.md index 6ee7ad6f641..6c5d7e61940 100644 --- a/docs/libcurl/opts/CURLOPT_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_CAPATH.md @@ -67,8 +67,7 @@ int main(void) # AVAILABILITY -This option is supported by the OpenSSL, GnuTLS and mbedTLS (since 7.56.0) -backends. +This option is supported by the OpenSSL, GnuTLS, mbedTLS and wolfSSL backends. # RETURN VALUE From c5775007d358c842b076acd3418d920a9060694e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Mar 2024 15:46:32 +0100 Subject: [PATCH 493/509] docs/libcurl: add TLS backend info for all TLS options All man pages that are listed to be for TLS now must also specify exactly what TLS backends the option works for, or use All if they all work. cd2nroff makes sure this is done and that the listed backends exist. Closes #13168 --- docs/CURLDOWN.md | 18 +++- docs/libcurl/curl_ws_recv.md | 2 +- docs/libcurl/opts/CURLINFO_CAINFO.md | 2 + docs/libcurl/opts/CURLINFO_CAPATH.md | 5 + docs/libcurl/opts/CURLINFO_CERTINFO.md | 5 + .../opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md | 3 + docs/libcurl/opts/CURLINFO_SSL_ENGINES.md | 2 + .../libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md | 3 + docs/libcurl/opts/CURLINFO_TLS_SESSION.md | 3 + docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md | 8 ++ docs/libcurl/opts/CURLOPT_CAINFO.md | 2 + docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md | 8 ++ docs/libcurl/opts/CURLOPT_CAPATH.md | 5 + docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md | 2 + docs/libcurl/opts/CURLOPT_CERTINFO.md | 5 + docs/libcurl/opts/CURLOPT_CRLFILE.md | 4 + .../opts/CURLOPT_DOH_SSL_VERIFYHOST.md | 2 + .../opts/CURLOPT_DOH_SSL_VERIFYPEER.md | 2 + .../opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md | 3 + docs/libcurl/opts/CURLOPT_EGDSOCKET.md | 2 + docs/libcurl/opts/CURLOPT_ISSUERCERT.md | 3 + docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md | 2 + docs/libcurl/opts/CURLOPT_KEYPASSWD.md | 5 + docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md | 7 ++ docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md | 2 + .../libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md | 5 + docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md | 4 + docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md | 4 + docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md | 5 +- .../opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md | 2 + docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md | 5 + .../opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md | 5 + docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md | 7 ++ .../libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md | 7 ++ .../opts/CURLOPT_PROXY_SSLCERT_BLOB.md | 4 + docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md | 5 + docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md | 4 + .../libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md | 2 + docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md | 2 + .../opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md | 7 ++ .../libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md | 2 + .../opts/CURLOPT_PROXY_SSL_VERIFYHOST.md | 2 + .../opts/CURLOPT_PROXY_SSL_VERIFYPEER.md | 2 + .../opts/CURLOPT_PROXY_TLS13_CIPHERS.md | 4 + .../opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md | 3 + .../opts/CURLOPT_PROXY_TLSAUTH_TYPE.md | 3 + .../opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md | 3 + docs/libcurl/opts/CURLOPT_RANDOM_FILE.md | 2 + docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md | 2 +- docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md | 3 +- docs/libcurl/opts/CURLOPT_SSLCERT.md | 7 ++ docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md | 7 ++ docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md | 5 + docs/libcurl/opts/CURLOPT_SSLENGINE.md | 2 + .../libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md | 2 + docs/libcurl/opts/CURLOPT_SSLKEY.md | 5 + docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md | 4 + docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md | 2 + docs/libcurl/opts/CURLOPT_SSLVERSION.md | 2 + docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md | 7 ++ docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md | 5 + docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md | 5 + docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md | 3 + docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md | 2 + docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md | 2 + docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md | 2 + docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md | 2 + .../opts/CURLOPT_SSL_SESSIONID_CACHE.md | 2 + docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md | 2 + docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md | 2 + docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md | 3 + docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md | 4 + docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md | 3 + docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md | 3 + docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md | 3 + scripts/cd2nroff | 100 +++++++++++++++--- 76 files changed, 368 insertions(+), 17 deletions(-) diff --git a/docs/CURLDOWN.md b/docs/CURLDOWN.md index bcb53076307..d0305487ac3 100644 --- a/docs/CURLDOWN.md +++ b/docs/CURLDOWN.md @@ -72,6 +72,8 @@ Each curldown starts with a header with meta-data: See-also: - CURLOPT_HEADEROPT (3) - CURLOPT_HTTPAUTH (3) + TLS-backend: + - [name] --- All curldown files *must* have all the headers present and at least one @@ -80,7 +82,21 @@ All curldown files *must* have all the headers present and at least one 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) or `TLS`. +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 `*` 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: diff --git a/docs/libcurl/curl_ws_recv.md b/docs/libcurl/curl_ws_recv.md index c6740b8771a..38a8a2abc55 100644 --- a/docs/libcurl/curl_ws_recv.md +++ b/docs/libcurl/curl_ws_recv.md @@ -11,7 +11,7 @@ See-also: - curl_ws_send (3) - libcurl-ws (3) Protocol: - - Ws + - WS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CAINFO.md b/docs/libcurl/opts/CURLINFO_CAINFO.md index c0f86bf9df4..e9ba9d34328 100644 --- a/docs/libcurl/opts/CURLINFO_CAINFO.md +++ b/docs/libcurl/opts/CURLINFO_CAINFO.md @@ -10,6 +10,8 @@ See-also: - curl_easy_setopt (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CAPATH.md b/docs/libcurl/opts/CURLINFO_CAPATH.md index 611ce2bfc24..0c9e21dee89 100644 --- a/docs/libcurl/opts/CURLINFO_CAPATH.md +++ b/docs/libcurl/opts/CURLINFO_CAPATH.md @@ -10,6 +10,11 @@ See-also: - curl_easy_setopt (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - mbedTLS + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.md b/docs/libcurl/opts/CURLINFO_CERTINFO.md index cedd57cfd70..507c946e64a 100644 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.md +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.md @@ -10,6 +10,11 @@ See-also: - curl_easy_setopt (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - Schannel + - Secure Transport --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md index 07bb011036d..cf76cd24308 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md +++ b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md @@ -10,6 +10,9 @@ See-also: - curl_easy_setopt (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md index 107bbc4673b..1035bd3b01c 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md +++ b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md @@ -10,6 +10,8 @@ See-also: - curl_easy_setopt (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md index 34fd445272f..edee07e9960 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md +++ b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md @@ -10,6 +10,9 @@ See-also: - curl_easy_setopt (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md index edeabae10b1..ccdd1cc320e 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md @@ -10,6 +10,9 @@ See-also: - curl_easy_setopt (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md index a4a45d0f3aa..2ce6e232c45 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md @@ -10,6 +10,14 @@ See-also: - curl_easy_setopt (3) Protocol: - TLS +TLS-backend: + - BearSSL + - GnuTLS + - mbedTLS + - OpenSSL + - Schannel + - Secure Transport + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.md b/docs/libcurl/opts/CURLOPT_CAINFO.md index 565e6c4274e..38ef173ff80 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO.md @@ -13,6 +13,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md index 21a0724e656..17079321540 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md @@ -11,6 +11,14 @@ See-also: - CURLOPT_CAPATH (3) - CURLOPT_SSL_VERIFYHOST (3) - CURLOPT_SSL_VERIFYPEER (3) +TLS-backend: + - BearSSL + - OpenSSL + - mbedTLS + - rustls + - wolfSSL + - Secure Transport + - Schannel --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.md b/docs/libcurl/opts/CURLOPT_CAPATH.md index 6c5d7e61940..212b4876017 100644 --- a/docs/libcurl/opts/CURLOPT_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_CAPATH.md @@ -11,6 +11,11 @@ See-also: - CURLOPT_STDERR (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - mbedTLS + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md index b7121fa4bd1..d90b208e732 100644 --- a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md @@ -12,6 +12,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.md b/docs/libcurl/opts/CURLOPT_CERTINFO.md index f8ade065f98..7789b29881a 100644 --- a/docs/libcurl/opts/CURLOPT_CERTINFO.md +++ b/docs/libcurl/opts/CURLOPT_CERTINFO.md @@ -12,6 +12,11 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - Schannel + - Secure Transport --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.md b/docs/libcurl/opts/CURLOPT_CRLFILE.md index 3ab78c377fb..fc11ad25811 100644 --- a/docs/libcurl/opts/CURLOPT_CRLFILE.md +++ b/docs/libcurl/opts/CURLOPT_CRLFILE.md @@ -10,6 +10,10 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - GnuTLS + - mbedTLS + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md index bdd0bc0f3a4..21ac14d4dba 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md @@ -12,6 +12,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md index e272b2c1ffe..ca45ce3cd81 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md @@ -14,6 +14,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md index c51ff02fbb7..4b5d5bfca7a 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md @@ -10,6 +10,9 @@ See-also: - CURLOPT_SSL_VERIFYSTATUS (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md index e91a8800d8b..8106fce6304 100644 --- a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md +++ b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_RANDOM_FILE (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md index 44fa216d68e..559b8f224bf 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md @@ -10,6 +10,9 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md index 4dba669943a..51ed6a32e94 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md index 7043d3442ca..a8bc4702aef 100644 --- a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md +++ b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md @@ -9,6 +9,11 @@ See-also: - CURLOPT_SSLKEY (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - mbedTLS + - Schannel + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md index eb6c05c83ad..52ba595aef7 100644 --- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md @@ -11,6 +11,13 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - wolfSSL + - mbedTLS + - Secure Transport + - Schannel --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md index 543f20d027e..19214bd7e03 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md @@ -16,6 +16,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md index 8022dff2621..02d282abf7c 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md @@ -16,6 +16,11 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - rustls + - Secure Transport + - Schannel --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md index 763214eecba..526f2d26104 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md @@ -12,6 +12,10 @@ See-also: - CURLOPT_STDERR (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - mbedTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md index 47762dcac78..ffe28f9a776 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md @@ -11,6 +11,10 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - GnuTLS + - mbedTLS + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md index 3ffe995a6cb..1ec2b02eb22 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md @@ -12,6 +12,9 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME @@ -76,7 +79,7 @@ int main(void) # AVAILABILITY -Added in 7.71.0. This option is supported by the OpenSSL backends. +Added in 7.71.0. This option is supported by the OpenSSL and GnuTLS backends. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md index 34eb8a9c507..38728e51acb 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md @@ -12,6 +12,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md index b2c7255e0b4..351af0134b7 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md @@ -11,6 +11,11 @@ See-also: - CURLOPT_SSLKEY (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - mbedTLS + - Schannel + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md index 8cfe5c34058..61594d146e4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md @@ -12,6 +12,11 @@ See-also: - CURLOPT_PROXY_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - mbedTLS + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md index 9b0182b68e5..f3db4b9764f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md @@ -10,6 +10,13 @@ See-also: - CURLOPT_SSLCERT (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - mbedTLS + - Schannel + - Secure Transport + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md index 8d1f10b4dbc..b9a8705e999 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md @@ -10,6 +10,13 @@ See-also: - CURLOPT_SSLCERTTYPE (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - mbedTLS + - Schannel + - Secure Transport + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md index ca5e62119f1..a1534d15fc3 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md @@ -11,6 +11,10 @@ See-also: - CURLOPT_SSLCERT_BLOB (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - Schannel + - Secure Transport --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md index 450fcb66ff4..2cbb24e728a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md @@ -12,6 +12,11 @@ See-also: - CURLOPT_SSLKEYTYPE (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - mbedTLS + - Schannel + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md index ffd2e92d85f..7132cecf898 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md @@ -10,6 +10,10 @@ See-also: - CURLOPT_SSLKEYTYPE (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - BearSSL + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md index ae941d17baf..fe5d67d00d4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSLKEY_BLOB (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md index ae9a8ab92f6..91968e750db 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_USE_SSL (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md index 4cb07789937..b33136d9a8d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md @@ -12,6 +12,13 @@ See-also: - CURLOPT_TLS13_CIPHERS (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - BearSSL + - Schannel + - Secure Transport + - wolfSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md index b1fabdcd28f..0734c14d332 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_SSL_CIPHER_LIST (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md index eb7b0db0488..f183697f924 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md index 0df8236a61f..56527ce5ac1 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md index a6c429caf7e..a9ec3d1dd7e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md @@ -12,6 +12,10 @@ See-also: - CURLOPT_TLS13_CIPHERS (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - rustls + - Schannel --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md index 8cb79bfa4c3..df8d25a24c5 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md @@ -11,6 +11,9 @@ See-also: - CURLOPT_TLSAUTH_USERNAME (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md index 03b4a2bae18..ec5773b969a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md @@ -11,6 +11,9 @@ See-also: - CURLOPT_TLSAUTH_USERNAME (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md index 59650227882..edc70942f2b 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md @@ -11,6 +11,9 @@ See-also: - CURLOPT_TLSAUTH_TYPE (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md index c00bf38efaa..f2a7e8d2109 100644 --- a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md +++ b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_EGDSOCKET (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md index 027a5129cb0..669bd70a167 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md +++ b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3) - CURLOPT_SSH_PUBLIC_KEYFILE (3) Protocol: - - SFP + - SFTP - SCP --- diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md index 5a0838cc28e..fda68d5f094 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md @@ -8,7 +8,8 @@ See-also: - CURLOPT_SSH_KEYDATA (3) - CURLOPT_SSH_KNOWNHOSTS (3) Protocol: - - TLS + - SFTP + - SCP --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.md b/docs/libcurl/opts/CURLOPT_SSLCERT.md index 69d28672ba9..81616988204 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.md @@ -10,6 +10,13 @@ See-also: - CURLOPT_SSLKEY (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - mbedTLS + - Schannel + - Secure Transport + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md index a8c7c589b4f..5ec33af1d9f 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md @@ -9,6 +9,13 @@ See-also: - CURLOPT_SSLKEY (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS + - mbedTLS + - Schannel + - Secure Transport + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md index ec37a145390..5e4b0c956ce 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md @@ -10,6 +10,11 @@ See-also: - CURLOPT_SSLKEY (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - Secure Transport + - Schannel + - mbedTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.md b/docs/libcurl/opts/CURLOPT_SSLENGINE.md index 96fe05b568f..1ec52580784 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE.md +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSLKEY (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md index dc1851533f3..05f22d8962c 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_SSLENGINE (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.md b/docs/libcurl/opts/CURLOPT_SSLKEY.md index f6777bbc1aa..7ec6aa9cddb 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.md @@ -10,6 +10,11 @@ See-also: - CURLOPT_SSLKEY_BLOB (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - mbedTLS + - Schannel + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md index 27cfb37a546..453d8908dc8 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md @@ -10,6 +10,10 @@ See-also: - CURLOPT_SSLKEY (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - BearSSL + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md index 833a94a07bb..6aabd3fa33e 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_SSLKEYTYPE (3) Protocol: - TLS +TLS-backend: + - OpenSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_SSLVERSION.md index 5978cd3071c..073fc744719 100644 --- a/docs/libcurl/opts/CURLOPT_SSLVERSION.md +++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_USE_SSL (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md index f337200be86..0143c8dfb0c 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md @@ -12,6 +12,13 @@ See-also: - CURLOPT_USE_SSL (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - BearSSL + - Schannel + - Secure Transport + - wolfSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md index 76483f41c54..be7307f8a7e 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md @@ -9,6 +9,11 @@ See-also: - CURLOPT_SSL_CTX_FUNCTION (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - wolfSSL + - mbedTLS + - BearSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md index 995f7295ea5..76e2403ff84 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md @@ -10,6 +10,11 @@ See-also: - CURLOPT_CAINFO (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - wolfSSL + - mbedTLS + - BearSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md index 9b22633263e..17b2e846a21 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md +++ b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md @@ -10,6 +10,9 @@ See-also: - CURLOPT_TLS13_CIPHERS (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - wolfSSL --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md index 8ed88b6b370..49796496d88 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_SSL_OPTIONS (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md index 869c70678e2..a0a68c6af3d 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md @@ -9,6 +9,8 @@ See-also: - CURLOPT_SSL_OPTIONS (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md index 754c26fddef..106b6efc07a 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md +++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md @@ -8,6 +8,8 @@ See-also: - CURLOPT_TCP_FASTOPEN (3) Protocol: - TLS +TLS-backend: + - Secure Transport --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md index 8fcc721fec1..4e33aac1ed5 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSL_CIPHER_LIST (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md index 677ef6ca276..63eab608488 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md +++ b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md @@ -11,6 +11,8 @@ See-also: - CURLOPT_SSLVERSION (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md index e96e4be530c..4cee06f25ab 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md @@ -10,6 +10,8 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md index e636b166162..53c81c79aa5 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md @@ -13,6 +13,8 @@ See-also: - CURLOPT_SSL_VERIFYHOST (3) Protocol: - TLS +TLS-backend: + - All --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md index 392fc2f6786..dc051ef4af5 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md @@ -10,6 +10,9 @@ See-also: - CURLOPT_SSL_VERIFYPEER (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md index 3b9eee82d4c..5a65b433701 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md @@ -13,6 +13,10 @@ See-also: - CURLOPT_USE_SSL (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - rustls + - Schannel --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md index f2670815dda..8871526c237 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md @@ -10,6 +10,9 @@ See-also: - CURLOPT_TLSAUTH_USERNAME (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md index fe7cdcd2fe4..111b82d7cc7 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md @@ -9,6 +9,9 @@ See-also: - CURLOPT_TLSAUTH_USERNAME (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md index b091ebfac4f..80ea1a2a029 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md @@ -9,6 +9,9 @@ See-also: - CURLOPT_TLSAUTH_TYPE (3) Protocol: - TLS +TLS-backend: + - OpenSSL + - GnuTLS --- # NAME diff --git a/scripts/cd2nroff b/scripts/cd2nroff index 35baa450f0f..6356c9de9cb 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -96,17 +96,64 @@ sub outseealso { return @o; } +my %knownprotos = ( + 'DICT' => 1, + 'FILE' => 1, + 'FTP' => 1, + 'FTPS' => 1, + 'GOPHER' => 1, + 'GOPHERS' => 1, + 'HTTP' => 1, + 'HTTPS' => 1, + 'IMAP' => 1, + 'IMAPS' => 1, + 'LDAP' => 1, + 'LDAPS' => 1, + 'MQTT' => 1, + 'POP3' => 1, + 'POP3S' => 1, + 'RTMP' => 1, + 'RTMPS' => 1, + 'RTSP' => 1, + 'SCP' => 1, + 'SFTP' => 1, + 'SMB' => 1, + 'SMBS' => 1, + 'SMTP' => 1, + 'SMTPS' => 1, + 'TELNET' => 1, + 'TFTP' => 1, + 'WS' => 1, + 'WSS' => 1, + 'TLS' => 1, + 'TCP' => 1, + '*' => 1 + ); + +my %knowntls = ( + 'BearSSL' => 1, + 'GnuTLS' => 1, + 'mbedTLS' => 1, + 'OpenSSL' => 1, + 'rustls' => 1, + 'Schannel' => 1, + 'Secure Transport' => 1, + 'wolfSSL' => 1, + 'All' => 1, + ); + sub single { my @seealso; my @proto; + my @tls; my $d; my ($f)=@_; my $copyright; my $errors = 0; my $fh; my $line; - my $salist; - my $protolist; + my $list; + my $tlslist; my $section; my $source; my $spdx; @@ -143,7 +190,7 @@ sub single { $source=$1; } elsif(/^See-also: +(.*)/i) { - $salist = 0; + $list = 1; # 1 for see-also push @seealso, $1; } elsif(/^See-also: */i) { @@ -151,21 +198,25 @@ sub single { print STDERR "$f:$line:1:ERROR: bad See-Also, needs list\n"; return 2; } - $salist = 1; - $protolist = 0; + $list = 1; # 1 for see-also } elsif(/^Protocol:/i) { - $salist = 0; - $protolist = 1; + $list = 2; # 2 for protocol + } + elsif(/^TLS-backend:/i) { + $list = 3; # 3 for TLS backend } elsif(/^ +- (.*)/i) { # the only lists we support are see-also and protocol - if($salist) { + if($list == 1) { push @seealso, $1; } - elsif($protolist) { + elsif($list == 2) { push @proto, $1; } + elsif($list == 3) { + push @tls, $1; + } else { print STDERR "$f:$line:1:ERROR: list item without owner?\n"; return 2; @@ -201,9 +252,34 @@ sub single { print STDERR "$f:$line:1:ERROR: no 'SPDX-License-Identifier:' field present\n"; return 2; } - if(!$proto[0] && ($section == 3)) { - printf STDERR "$f:$line:1:ERROR: missing Protocol:\n"; - exit 2; + if($section == 3) { + if(!$proto[0]) { + printf STDERR "$f:$line:1:ERROR: missing Protocol:\n"; + exit 2; + } + my $tls = 0; + for my $p (@proto) { + if($p eq "TLS") { + $tls = 1; + } + if(!$knownprotos{$p}) { + printf STDERR "$f:$line:1:ERROR: invalid protocol used: $p:\n"; + exit 2; + } + } + # This is for TLS, require TLS-backend: + if($tls) { + if(!$tls[0]) { + printf STDERR "$f:$line:1:ERROR: missing TLS-backend:\n"; + exit 2; + } + for my $t (@tls) { + if(!$knowntls{$t}) { + printf STDERR "$f:$line:1:ERROR: invalid TLS backend: $t:\n"; + exit 2; + } + } + } } last; } From 7bc61bf4693c8e57ffb68b32357b26251a04b190 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 23 Mar 2024 00:36:50 +0100 Subject: [PATCH 494/509] CURLMOPT_MAX*: mention what happens if changed mid-transfer For CURLMOPT_MAXCONNECTS and CURLMOPT_MAX_HOST_CONNECTIONS Ref: #13158 Closes #13176 --- docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md | 5 +++++ .../opts/CURLMOPT_MAX_HOST_CONNECTIONS.md | 21 ++++++++++++------- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md index 0a7eb4965dd..317eea6d01b 100644 --- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md +++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md @@ -43,6 +43,11 @@ you should instead use the CURLOPT_MAXCONNECTS(3) option. See CURLMOPT_MAX_TOTAL_CONNECTIONS(3) for limiting the number of active connections. +Changing this value when there are transfers in progress is possible, and the +new value is then used the next time checks are performed. Lowering the value +does however not close down any active transfers, it simply does not allow new +ones to get made. + # DEFAULT See DESCRIPTION diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md index ceb8850ed3e..099efddc5cc 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md @@ -29,9 +29,9 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS, Pass a long to indicate **max**. The set number is used as the maximum amount of simultaneously open connections to a single host (a host being the same as a hostname + port number pair). For each new session to a host, libcurl might -open a new connection up to the limit set by -CURLMOPT_MAX_HOST_CONNECTIONS(3). When the limit is reached, new sessions are -kept pending until a connection becomes available. +open a new connection up to the limit set by CURLMOPT_MAX_HOST_CONNECTIONS(3). +When the limit is reached, new sessions are kept pending until a connection +becomes available. The default **max** value is 0, unlimited. This set limit is also used for proxy connections, and then the proxy is considered to be the host for which @@ -39,12 +39,17 @@ this limit counts. When more transfers are added to the multi handle than what can be performed due to the set limit, they are queued up waiting for their chance. When that -happens, the CURLOPT_TIMEOUT_MS(3) timeout is inclusive of the waiting -time, meaning that if you set a too narrow timeout in such a case the transfer -might never even start before it times out. +happens, the CURLOPT_TIMEOUT_MS(3) timeout is inclusive of the waiting time, +meaning that if you set a too narrow timeout in such a case the transfer might +never even start before it times out. -Even in the queued up situation, the CURLOPT_CONNECTTIMEOUT_MS(3) -timeout is however treated as a per-connect timeout. +Even in the queued up situation, the CURLOPT_CONNECTTIMEOUT_MS(3) timeout is +however treated as a per-connect timeout. + +Changing this value when there are transfers in progress is possible, and the +new value is then used the next time checks are performed. Lowering the value +does however not close down any active transfers, it simply does not allow new +ones to get made. # DEFAULT From e3fe020089e486fe7a4af8424c3e0ea648ed2b27 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 22 Mar 2024 23:48:54 +0100 Subject: [PATCH 495/509] docs/libcurl: generate PROTOCOLS from meta-data Remove the PROTOCOLS section from the source files completely and instead generate them based on the header data in the curldown files. It also generates TLS backend information for options marked for TLS as protocol. Closes #13175 --- docs/CURLDOWN.md | 2 +- docs/libcurl/curl_easy_cleanup.md | 2 +- docs/libcurl/curl_easy_duphandle.md | 2 +- docs/libcurl/curl_easy_escape.md | 2 +- docs/libcurl/curl_easy_getinfo.md | 2 +- docs/libcurl/curl_easy_init.md | 2 +- docs/libcurl/curl_easy_option_by_id.md | 2 +- docs/libcurl/curl_easy_option_by_name.md | 2 +- docs/libcurl/curl_easy_option_next.md | 2 +- docs/libcurl/curl_easy_pause.md | 2 +- docs/libcurl/curl_easy_perform.md | 2 +- docs/libcurl/curl_easy_recv.md | 2 +- docs/libcurl/curl_easy_reset.md | 2 +- docs/libcurl/curl_easy_send.md | 2 +- docs/libcurl/curl_easy_setopt.md | 2 +- docs/libcurl/curl_easy_strerror.md | 2 +- docs/libcurl/curl_easy_unescape.md | 2 +- docs/libcurl/curl_easy_upkeep.md | 2 +- docs/libcurl/curl_escape.md | 2 +- docs/libcurl/curl_free.md | 2 +- docs/libcurl/curl_getdate.md | 2 +- docs/libcurl/curl_getenv.md | 2 +- docs/libcurl/curl_global_cleanup.md | 2 +- docs/libcurl/curl_global_init.md | 2 +- docs/libcurl/curl_global_init_mem.md | 2 +- docs/libcurl/curl_global_sslset.md | 2 +- docs/libcurl/curl_global_trace.md | 2 +- docs/libcurl/curl_mprintf.md | 2 +- docs/libcurl/curl_multi_add_handle.md | 2 +- docs/libcurl/curl_multi_assign.md | 2 +- docs/libcurl/curl_multi_cleanup.md | 2 +- docs/libcurl/curl_multi_fdset.md | 2 +- docs/libcurl/curl_multi_get_handles.md | 2 +- docs/libcurl/curl_multi_info_read.md | 2 +- docs/libcurl/curl_multi_init.md | 2 +- docs/libcurl/curl_multi_perform.md | 2 +- docs/libcurl/curl_multi_poll.md | 2 +- docs/libcurl/curl_multi_remove_handle.md | 2 +- docs/libcurl/curl_multi_setopt.md | 2 +- docs/libcurl/curl_multi_socket.md | 2 +- docs/libcurl/curl_multi_socket_action.md | 2 +- docs/libcurl/curl_multi_socket_all.md | 2 +- docs/libcurl/curl_multi_strerror.md | 2 +- docs/libcurl/curl_multi_timeout.md | 2 +- docs/libcurl/curl_multi_wait.md | 2 +- docs/libcurl/curl_multi_wakeup.md | 2 +- docs/libcurl/curl_share_cleanup.md | 2 +- docs/libcurl/curl_share_init.md | 2 +- docs/libcurl/curl_share_setopt.md | 2 +- docs/libcurl/curl_share_strerror.md | 2 +- docs/libcurl/curl_slist_append.md | 2 +- docs/libcurl/curl_slist_free_all.md | 2 +- docs/libcurl/curl_strequal.md | 2 +- docs/libcurl/curl_strnequal.md | 2 +- docs/libcurl/curl_unescape.md | 2 +- docs/libcurl/curl_url.md | 2 +- docs/libcurl/curl_url_cleanup.md | 2 +- docs/libcurl/curl_url_dup.md | 2 +- docs/libcurl/curl_url_get.md | 2 +- docs/libcurl/curl_url_set.md | 2 +- docs/libcurl/curl_url_strerror.md | 2 +- docs/libcurl/curl_version.md | 2 +- docs/libcurl/curl_version_info.md | 2 +- docs/libcurl/libcurl-easy.md | 2 +- docs/libcurl/libcurl-env-dbg.md | 2 +- docs/libcurl/libcurl-env.md | 2 +- docs/libcurl/libcurl-errors.md | 2 +- docs/libcurl/libcurl-multi.md | 2 +- docs/libcurl/libcurl-security.md | 2 +- docs/libcurl/libcurl-share.md | 2 +- docs/libcurl/libcurl-thread.md | 2 +- docs/libcurl/libcurl-tutorial.md | 2 +- docs/libcurl/libcurl-url.md | 2 +- docs/libcurl/libcurl-ws.md | 2 +- docs/libcurl/libcurl.md | 2 +- docs/libcurl/mksymbolsmanpage.pl | 2 +- docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md | 6 +- docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md | 6 +- .../opts/CURLINFO_APPCONNECT_TIME_T.md | 6 +- docs/libcurl/opts/CURLINFO_CAINFO.md | 4 -- docs/libcurl/opts/CURLINFO_CAPATH.md | 4 -- docs/libcurl/opts/CURLINFO_CERTINFO.md | 4 -- docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md | 4 -- docs/libcurl/opts/CURLINFO_CONNECT_TIME.md | 6 +- docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md | 6 +- docs/libcurl/opts/CURLINFO_CONN_ID.md | 6 +- .../opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md | 6 +- .../CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md | 4 -- .../opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md | 6 +- .../opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md | 6 +- docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md | 4 -- docs/libcurl/opts/CURLINFO_COOKIELIST.md | 4 -- .../libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md | 4 -- docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md | 4 -- docs/libcurl/opts/CURLINFO_FILETIME.md | 4 -- docs/libcurl/opts/CURLINFO_FILETIME_T.md | 4 -- docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md | 4 -- docs/libcurl/opts/CURLINFO_HEADER_SIZE.md | 6 +- docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md | 4 -- .../libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md | 4 -- docs/libcurl/opts/CURLINFO_HTTP_VERSION.md | 4 -- docs/libcurl/opts/CURLINFO_LASTSOCKET.md | 6 +- docs/libcurl/opts/CURLINFO_LOCAL_IP.md | 6 +- docs/libcurl/opts/CURLINFO_LOCAL_PORT.md | 4 -- docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md | 6 +- .../opts/CURLINFO_NAMELOOKUP_TIME_T.md | 6 +- docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md | 6 +- docs/libcurl/opts/CURLINFO_OS_ERRNO.md | 6 +- .../libcurl/opts/CURLINFO_PRETRANSFER_TIME.md | 6 +- .../opts/CURLINFO_PRETRANSFER_TIME_T.md | 6 +- docs/libcurl/opts/CURLINFO_PRIMARY_IP.md | 6 +- docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md | 6 +- docs/libcurl/opts/CURLINFO_PRIVATE.md | 6 +- docs/libcurl/opts/CURLINFO_PROTOCOL.md | 6 +- docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md | 4 -- docs/libcurl/opts/CURLINFO_PROXY_ERROR.md | 6 +- .../opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md | 4 -- docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md | 6 +- docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md | 6 +- docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md | 4 -- docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md | 4 -- docs/libcurl/opts/CURLINFO_REDIRECT_URL.md | 4 -- docs/libcurl/opts/CURLINFO_REFERER.md | 4 -- docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md | 6 +- docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md | 4 -- docs/libcurl/opts/CURLINFO_RETRY_AFTER.md | 6 +- .../libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md | 4 -- docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md | 4 -- .../libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md | 4 -- docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md | 4 -- docs/libcurl/opts/CURLINFO_SCHEME.md | 6 +- docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md | 6 +- docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md | 6 +- docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md | 6 +- docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md | 6 +- docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md | 4 +- .../libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md | 4 +- docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md | 4 +- docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md | 4 +- docs/libcurl/opts/CURLINFO_SSL_ENGINES.md | 4 -- .../libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md | 4 -- .../opts/CURLINFO_STARTTRANSFER_TIME.md | 6 +- .../opts/CURLINFO_STARTTRANSFER_TIME_T.md | 6 +- docs/libcurl/opts/CURLINFO_TLS_SESSION.md | 4 -- docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md | 4 -- docs/libcurl/opts/CURLINFO_TOTAL_TIME.md | 6 +- docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md | 6 +- docs/libcurl/opts/CURLINFO_USED_PROXY.md | 6 +- docs/libcurl/opts/CURLINFO_XFER_ID.md | 6 +- .../CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md | 4 -- .../CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md | 4 -- docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md | 6 +- .../opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md | 4 -- .../opts/CURLMOPT_MAX_HOST_CONNECTIONS.md | 6 +- .../opts/CURLMOPT_MAX_PIPELINE_LENGTH.md | 6 +- .../opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md | 6 +- docs/libcurl/opts/CURLMOPT_PIPELINING.md | 4 -- .../opts/CURLMOPT_PIPELINING_SERVER_BL.md | 2 - .../opts/CURLMOPT_PIPELINING_SITE_BL.md | 4 -- docs/libcurl/opts/CURLMOPT_PUSHDATA.md | 4 -- docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md | 4 -- docs/libcurl/opts/CURLMOPT_SOCKETDATA.md | 6 +- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 6 +- docs/libcurl/opts/CURLMOPT_TIMERDATA.md | 6 +- docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md | 6 +- .../opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md | 6 +- docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md | 4 -- docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md | 4 -- docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md | 6 +- docs/libcurl/opts/CURLOPT_ALTSVC.md | 4 -- docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md | 4 -- docs/libcurl/opts/CURLOPT_APPEND.md | 4 -- docs/libcurl/opts/CURLOPT_AUTOREFERER.md | 4 -- docs/libcurl/opts/CURLOPT_AWS_SIGV4.md | 4 -- docs/libcurl/opts/CURLOPT_BUFFERSIZE.md | 6 +- docs/libcurl/opts/CURLOPT_CAINFO.md | 4 -- docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md | 4 -- docs/libcurl/opts/CURLOPT_CAPATH.md | 4 -- docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md | 4 -- docs/libcurl/opts/CURLOPT_CERTINFO.md | 8 +-- .../opts/CURLOPT_CHUNK_BGN_FUNCTION.md | 4 -- docs/libcurl/opts/CURLOPT_CHUNK_DATA.md | 4 -- .../opts/CURLOPT_CHUNK_END_FUNCTION.md | 4 -- docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md | 6 +- .../opts/CURLOPT_CLOSESOCKETFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md | 6 +- .../libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md | 6 +- docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md | 8 +-- docs/libcurl/opts/CURLOPT_CONNECT_TO.md | 6 +- .../CURLOPT_CONV_FROM_NETWORK_FUNCTION.md | 6 +- .../opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md | 6 +- .../opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_COOKIE.md | 4 -- docs/libcurl/opts/CURLOPT_COOKIEFILE.md | 4 -- docs/libcurl/opts/CURLOPT_COOKIEJAR.md | 4 -- docs/libcurl/opts/CURLOPT_COOKIELIST.md | 4 -- docs/libcurl/opts/CURLOPT_COOKIESESSION.md | 4 -- docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md | 4 -- docs/libcurl/opts/CURLOPT_CRLF.md | 6 +- docs/libcurl/opts/CURLOPT_CRLFILE.md | 4 -- docs/libcurl/opts/CURLOPT_CURLU.md | 6 +- docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md | 4 -- docs/libcurl/opts/CURLOPT_DEBUGDATA.md | 6 +- docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md | 6 +- docs/libcurl/opts/CURLOPT_DIRLISTONLY.md | 4 -- .../opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md | 6 +- .../libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md | 6 +- docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md | 6 +- docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md | 6 +- docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md | 6 +- docs/libcurl/opts/CURLOPT_DNS_SERVERS.md | 6 +- .../opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md | 6 +- .../opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md | 10 +--- .../opts/CURLOPT_DOH_SSL_VERIFYHOST.md | 4 -- .../opts/CURLOPT_DOH_SSL_VERIFYPEER.md | 4 -- .../opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md | 7 +-- docs/libcurl/opts/CURLOPT_DOH_URL.md | 6 +- docs/libcurl/opts/CURLOPT_EGDSOCKET.md | 7 +-- docs/libcurl/opts/CURLOPT_ERRORBUFFER.md | 6 +- .../opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md | 4 -- docs/libcurl/opts/CURLOPT_FAILONERROR.md | 4 -- docs/libcurl/opts/CURLOPT_FILETIME.md | 4 -- docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md | 4 -- docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md | 4 -- docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md | 4 -- docs/libcurl/opts/CURLOPT_FORBID_REUSE.md | 6 +- docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md | 6 +- docs/libcurl/opts/CURLOPT_FTPPORT.md | 4 -- docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md | 4 -- docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md | 4 -- .../opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md | 4 -- .../opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md | 4 -- docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md | 4 -- docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md | 4 -- docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md | 4 -- docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md | 2 - docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md | 4 -- docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md | 4 -- .../libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md | 4 -- .../opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md | 6 +- docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md | 6 +- .../libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md | 6 +- docs/libcurl/opts/CURLOPT_HEADER.md | 4 -- docs/libcurl/opts/CURLOPT_HEADERDATA.md | 6 +- docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md | 5 -- docs/libcurl/opts/CURLOPT_HEADEROPT.md | 4 -- docs/libcurl/opts/CURLOPT_HSTS.md | 4 -- docs/libcurl/opts/CURLOPT_HSTSREADDATA.md | 4 -- docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md | 4 -- docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md | 4 -- .../libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md | 4 -- docs/libcurl/opts/CURLOPT_HSTS_CTRL.md | 4 -- docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md | 4 -- docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md | 4 -- docs/libcurl/opts/CURLOPT_HTTPAUTH.md | 4 -- docs/libcurl/opts/CURLOPT_HTTPGET.md | 4 -- docs/libcurl/opts/CURLOPT_HTTPHEADER.md | 4 -- docs/libcurl/opts/CURLOPT_HTTPPOST.md | 4 -- docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md | 6 +- .../opts/CURLOPT_HTTP_CONTENT_DECODING.md | 4 -- .../opts/CURLOPT_HTTP_TRANSFER_DECODING.md | 4 -- docs/libcurl/opts/CURLOPT_HTTP_VERSION.md | 4 -- .../opts/CURLOPT_IGNORE_CONTENT_LENGTH.md | 4 -- docs/libcurl/opts/CURLOPT_INFILESIZE.md | 6 +- docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md | 6 +- docs/libcurl/opts/CURLOPT_INTERFACE.md | 6 +- docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md | 4 -- .../opts/CURLOPT_INTERLEAVEFUNCTION.md | 4 -- docs/libcurl/opts/CURLOPT_IOCTLDATA.md | 6 +- docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_IPRESOLVE.md | 6 +- docs/libcurl/opts/CURLOPT_ISSUERCERT.md | 4 -- docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md | 4 -- .../opts/CURLOPT_KEEP_SENDING_ON_ERROR.md | 4 -- docs/libcurl/opts/CURLOPT_KEYPASSWD.md | 4 -- docs/libcurl/opts/CURLOPT_KRBLEVEL.md | 4 -- docs/libcurl/opts/CURLOPT_LOCALPORT.md | 6 +- docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md | 6 +- docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md | 4 -- docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md | 6 +- docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md | 6 +- docs/libcurl/opts/CURLOPT_MAIL_AUTH.md | 4 -- docs/libcurl/opts/CURLOPT_MAIL_FROM.md | 4 -- docs/libcurl/opts/CURLOPT_MAIL_RCPT.md | 4 -- .../opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md | 4 -- docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md | 6 +- docs/libcurl/opts/CURLOPT_MAXCONNECTS.md | 6 +- docs/libcurl/opts/CURLOPT_MAXFILESIZE.md | 6 +- .../libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md | 4 -- docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md | 6 +- docs/libcurl/opts/CURLOPT_MAXREDIRS.md | 4 -- .../opts/CURLOPT_MAX_RECV_SPEED_LARGE.md | 6 +- .../opts/CURLOPT_MAX_SEND_SPEED_LARGE.md | 6 +- docs/libcurl/opts/CURLOPT_MIMEPOST.md | 4 -- docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md | 4 -- docs/libcurl/opts/CURLOPT_NETRC.md | 6 +- docs/libcurl/opts/CURLOPT_NETRC_FILE.md | 6 +- .../opts/CURLOPT_NEW_DIRECTORY_PERMS.md | 4 -- docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md | 4 -- docs/libcurl/opts/CURLOPT_NOBODY.md | 6 +- docs/libcurl/opts/CURLOPT_NOPROGRESS.md | 6 +- docs/libcurl/opts/CURLOPT_NOPROXY.md | 6 +- docs/libcurl/opts/CURLOPT_NOSIGNAL.md | 6 +- docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md | 6 +- .../opts/CURLOPT_OPENSOCKETFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_PASSWORD.md | 6 +- docs/libcurl/opts/CURLOPT_PATH_AS_IS.md | 6 +- docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md | 4 -- docs/libcurl/opts/CURLOPT_PIPEWAIT.md | 4 -- docs/libcurl/opts/CURLOPT_PORT.md | 6 +- docs/libcurl/opts/CURLOPT_POST.md | 4 -- docs/libcurl/opts/CURLOPT_POSTFIELDS.md | 4 -- docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md | 4 -- .../opts/CURLOPT_POSTFIELDSIZE_LARGE.md | 4 -- docs/libcurl/opts/CURLOPT_POSTQUOTE.md | 4 -- docs/libcurl/opts/CURLOPT_POSTREDIR.md | 4 -- docs/libcurl/opts/CURLOPT_PREQUOTE.md | 4 -- docs/libcurl/opts/CURLOPT_PREREQDATA.md | 6 +- docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_PRE_PROXY.md | 6 +- docs/libcurl/opts/CURLOPT_PRIVATE.md | 6 +- docs/libcurl/opts/CURLOPT_PROGRESSDATA.md | 6 +- docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_PROTOCOLS.md | 6 +- docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md | 6 +- docs/libcurl/opts/CURLOPT_PROXY.md | 6 +- docs/libcurl/opts/CURLOPT_PROXYAUTH.md | 6 +- docs/libcurl/opts/CURLOPT_PROXYHEADER.md | 6 +- docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md | 6 +- docs/libcurl/opts/CURLOPT_PROXYPORT.md | 6 +- docs/libcurl/opts/CURLOPT_PROXYTYPE.md | 6 +- docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md | 6 +- docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md | 6 +- docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md | 4 -- .../libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md | 4 -- docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md | 7 +-- docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md | 4 -- docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md | 4 -- .../opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md | 4 -- docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md | 4 -- .../opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md | 4 -- .../opts/CURLOPT_PROXY_SERVICE_NAME.md | 6 +- docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md | 4 -- .../libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md | 4 -- .../opts/CURLOPT_PROXY_SSLCERT_BLOB.md | 7 +-- docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md | 4 -- docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md | 4 -- .../libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md | 4 -- docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md | 4 -- .../opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md | 4 -- .../libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md | 4 -- .../opts/CURLOPT_PROXY_SSL_VERIFYHOST.md | 4 -- .../opts/CURLOPT_PROXY_SSL_VERIFYPEER.md | 4 -- .../opts/CURLOPT_PROXY_TLS13_CIPHERS.md | 4 -- .../opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md | 6 +- .../opts/CURLOPT_PROXY_TLSAUTH_TYPE.md | 4 -- .../opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md | 6 +- .../opts/CURLOPT_PROXY_TRANSFER_MODE.md | 6 +- docs/libcurl/opts/CURLOPT_PUT.md | 4 -- docs/libcurl/opts/CURLOPT_QUICK_EXIT.md | 6 +- docs/libcurl/opts/CURLOPT_QUOTE.md | 4 -- docs/libcurl/opts/CURLOPT_RANDOM_FILE.md | 7 +-- docs/libcurl/opts/CURLOPT_RANGE.md | 4 -- docs/libcurl/opts/CURLOPT_READDATA.md | 6 +- docs/libcurl/opts/CURLOPT_READFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md | 4 -- .../opts/CURLOPT_REDIR_PROTOCOLS_STR.md | 4 -- docs/libcurl/opts/CURLOPT_REFERER.md | 4 -- docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md | 4 -- docs/libcurl/opts/CURLOPT_RESOLVE.md | 6 +- .../opts/CURLOPT_RESOLVER_START_DATA.md | 6 +- .../opts/CURLOPT_RESOLVER_START_FUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_RESUME_FROM.md | 6 +- .../libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md | 6 +- docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md | 4 -- docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md | 4 -- docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md | 4 -- docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md | 4 -- docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md | 4 -- docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md | 4 -- docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md | 4 -- docs/libcurl/opts/CURLOPT_SASL_IR.md | 4 -- docs/libcurl/opts/CURLOPT_SEEKDATA.md | 6 +- docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md | 6 +- .../opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md | 4 -- .../CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md | 4 -- docs/libcurl/opts/CURLOPT_SERVICE_NAME.md | 11 ++-- docs/libcurl/opts/CURLOPT_SHARE.md | 6 +- docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md | 6 +- docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md | 6 +- .../libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md | 6 +- .../opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md | 6 +- docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md | 4 -- docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md | 4 -- docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md | 4 -- .../opts/CURLOPT_SSH_HOSTKEYFUNCTION.md | 4 -- .../opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md | 4 -- .../CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md | 4 -- docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md | 4 -- docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md | 4 -- docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md | 4 -- .../opts/CURLOPT_SSH_PRIVATE_KEYFILE.md | 4 -- .../opts/CURLOPT_SSH_PUBLIC_KEYFILE.md | 4 -- docs/libcurl/opts/CURLOPT_SSLCERT.md | 4 -- docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md | 4 -- docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md | 4 -- docs/libcurl/opts/CURLOPT_SSLENGINE.md | 6 +- .../libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md | 4 -- docs/libcurl/opts/CURLOPT_SSLKEY.md | 4 -- docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md | 4 -- docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md | 4 -- docs/libcurl/opts/CURLOPT_SSLVERSION.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md | 6 +- docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md | 10 +--- docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md | 4 -- .../opts/CURLOPT_SSL_SESSIONID_CACHE.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md | 4 -- docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md | 4 -- docs/libcurl/opts/CURLOPT_STDERR.md | 6 +- docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md | 4 -- docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md | 4 -- docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md | 4 -- .../opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md | 6 +- docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md | 6 +- docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md | 6 +- docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md | 6 +- docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md | 6 +- docs/libcurl/opts/CURLOPT_TCP_NODELAY.md | 6 +- docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md | 4 -- docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md | 4 -- docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md | 4 -- docs/libcurl/opts/CURLOPT_TIMECONDITION.md | 4 -- docs/libcurl/opts/CURLOPT_TIMEOUT.md | 6 +- docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md | 6 +- docs/libcurl/opts/CURLOPT_TIMEVALUE.md | 4 -- docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md | 4 -- docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md | 4 -- docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md | 4 -- docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md | 4 -- docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md | 4 -- docs/libcurl/opts/CURLOPT_TRAILERDATA.md | 4 -- docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md | 4 -- docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md | 6 +- .../libcurl/opts/CURLOPT_TRANSFER_ENCODING.md | 4 -- docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md | 7 +-- .../libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md | 4 -- .../opts/CURLOPT_UPKEEP_INTERVAL_MS.md | 6 +- docs/libcurl/opts/CURLOPT_UPLOAD.md | 6 +- .../libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md | 6 +- docs/libcurl/opts/CURLOPT_URL.md | 6 +- docs/libcurl/opts/CURLOPT_USERAGENT.md | 4 -- docs/libcurl/opts/CURLOPT_USERNAME.md | 6 +- docs/libcurl/opts/CURLOPT_USERPWD.md | 6 +- docs/libcurl/opts/CURLOPT_USE_SSL.md | 4 -- docs/libcurl/opts/CURLOPT_VERBOSE.md | 6 +- docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md | 4 -- docs/libcurl/opts/CURLOPT_WRITEDATA.md | 6 +- docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_WS_OPTIONS.md | 4 -- docs/libcurl/opts/CURLOPT_XFERINFODATA.md | 6 +- docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md | 6 +- docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md | 4 -- docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md | 6 +- docs/libcurl/opts/CURLSHOPT_SHARE.md | 6 +- docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md | 6 +- docs/libcurl/opts/CURLSHOPT_UNSHARE.md | 6 +- docs/libcurl/opts/CURLSHOPT_USERDATA.md | 6 +- scripts/cd2nroff | 55 ++++++++++++++++++- 476 files changed, 323 insertions(+), 1860 deletions(-) diff --git a/docs/CURLDOWN.md b/docs/CURLDOWN.md index d0305487ac3..8ee2f3ce4f4 100644 --- a/docs/CURLDOWN.md +++ b/docs/CURLDOWN.md @@ -85,7 +85,7 @@ 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 `*` or a list of what TLS backends that work with this +list, specifying `All` or a list of what TLS backends that work with this option. The available TLS backends are: - `BearSSL` diff --git a/docs/libcurl/curl_easy_cleanup.md b/docs/libcurl/curl_easy_cleanup.md index c91af97df10..e939dddc723 100644 --- a/docs/libcurl/curl_easy_cleanup.md +++ b/docs/libcurl/curl_easy_cleanup.md @@ -11,7 +11,7 @@ See-also: - curl_multi_cleanup (3) - curl_multi_remove_handle (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_duphandle.md b/docs/libcurl/curl_easy_duphandle.md index 17a0bc7f6cf..49d95ad9890 100644 --- a/docs/libcurl/curl_easy_duphandle.md +++ b/docs/libcurl/curl_easy_duphandle.md @@ -10,7 +10,7 @@ See-also: - curl_easy_reset (3) - curl_global_init (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_escape.md b/docs/libcurl/curl_easy_escape.md index 5a84ed2eb14..dfe4bf5f3ae 100644 --- a/docs/libcurl/curl_easy_escape.md +++ b/docs/libcurl/curl_easy_escape.md @@ -8,7 +8,7 @@ See-also: - curl_easy_unescape (3) - curl_free (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_getinfo.md b/docs/libcurl/curl_easy_getinfo.md index 33c6d80e69e..a4e4e4715d3 100644 --- a/docs/libcurl/curl_easy_getinfo.md +++ b/docs/libcurl/curl_easy_getinfo.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_init.md b/docs/libcurl/curl_easy_init.md index 68d42a9300d..9d282bdf3cd 100644 --- a/docs/libcurl/curl_easy_init.md +++ b/docs/libcurl/curl_easy_init.md @@ -12,7 +12,7 @@ See-also: - curl_global_init (3) - curl_multi_init (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_option_by_id.md b/docs/libcurl/curl_easy_option_by_id.md index 2c3f696fbb9..697fc7e5331 100644 --- a/docs/libcurl/curl_easy_option_by_id.md +++ b/docs/libcurl/curl_easy_option_by_id.md @@ -9,7 +9,7 @@ See-also: - curl_easy_option_next (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_option_by_name.md b/docs/libcurl/curl_easy_option_by_name.md index 76a8083051d..d03ff8b43d6 100644 --- a/docs/libcurl/curl_easy_option_by_name.md +++ b/docs/libcurl/curl_easy_option_by_name.md @@ -9,7 +9,7 @@ See-also: - curl_easy_option_next (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_option_next.md b/docs/libcurl/curl_easy_option_next.md index fcb6faf9d9f..42f4409b60a 100644 --- a/docs/libcurl/curl_easy_option_next.md +++ b/docs/libcurl/curl_easy_option_next.md @@ -9,7 +9,7 @@ See-also: - curl_easy_option_by_name (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_pause.md b/docs/libcurl/curl_easy_pause.md index 61230aed104..a185acd7949 100644 --- a/docs/libcurl/curl_easy_pause.md +++ b/docs/libcurl/curl_easy_pause.md @@ -8,7 +8,7 @@ See-also: - curl_easy_cleanup (3) - curl_easy_reset (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_perform.md b/docs/libcurl/curl_easy_perform.md index 443be532e3e..b24ae50db4c 100644 --- a/docs/libcurl/curl_easy_perform.md +++ b/docs/libcurl/curl_easy_perform.md @@ -11,7 +11,7 @@ See-also: - curl_multi_perform (3) - libcurl-errors (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_recv.md b/docs/libcurl/curl_easy_recv.md index 950290a3a4c..fa3c8f4c6e8 100644 --- a/docs/libcurl/curl_easy_recv.md +++ b/docs/libcurl/curl_easy_recv.md @@ -10,7 +10,7 @@ See-also: - curl_easy_send (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_reset.md b/docs/libcurl/curl_easy_reset.md index 0e2e1b0870c..1b09d12e774 100644 --- a/docs/libcurl/curl_easy_reset.md +++ b/docs/libcurl/curl_easy_reset.md @@ -10,7 +10,7 @@ See-also: - curl_easy_init (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_send.md b/docs/libcurl/curl_easy_send.md index a0bd68e3455..ff51eca843b 100644 --- a/docs/libcurl/curl_easy_send.md +++ b/docs/libcurl/curl_easy_send.md @@ -10,7 +10,7 @@ See-also: - curl_easy_recv (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_setopt.md b/docs/libcurl/curl_easy_setopt.md index 582c461d4dd..770fdc91bc7 100644 --- a/docs/libcurl/curl_easy_setopt.md +++ b/docs/libcurl/curl_easy_setopt.md @@ -14,7 +14,7 @@ See-also: - curl_easy_reset (3) - curl_multi_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_strerror.md b/docs/libcurl/curl_easy_strerror.md index d55c42a79ce..0555fe78352 100644 --- a/docs/libcurl/curl_easy_strerror.md +++ b/docs/libcurl/curl_easy_strerror.md @@ -10,7 +10,7 @@ See-also: - curl_url_strerror (3) - libcurl-errors (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_unescape.md b/docs/libcurl/curl_easy_unescape.md index ee0ab9b1fb4..00951d96ec3 100644 --- a/docs/libcurl/curl_easy_unescape.md +++ b/docs/libcurl/curl_easy_unescape.md @@ -8,7 +8,7 @@ See-also: - curl_easy_escape (3) - curl_free (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_easy_upkeep.md b/docs/libcurl/curl_easy_upkeep.md index a05e80909f4..eec4ed2f402 100644 --- a/docs/libcurl/curl_easy_upkeep.md +++ b/docs/libcurl/curl_easy_upkeep.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TCP_KEEPIDLE (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_escape.md b/docs/libcurl/curl_escape.md index 3d29c310ddc..d15a4debcce 100644 --- a/docs/libcurl/curl_escape.md +++ b/docs/libcurl/curl_escape.md @@ -8,7 +8,7 @@ See-also: - curl_free (3) - curl_unescape (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_free.md b/docs/libcurl/curl_free.md index 7b1f706a884..a758adf59d4 100644 --- a/docs/libcurl/curl_free.md +++ b/docs/libcurl/curl_free.md @@ -8,7 +8,7 @@ See-also: - curl_easy_escape (3) - curl_easy_unescape (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_getdate.md b/docs/libcurl/curl_getdate.md index f0bfea76fdb..4a3849d6966 100644 --- a/docs/libcurl/curl_getdate.md +++ b/docs/libcurl/curl_getdate.md @@ -10,7 +10,7 @@ See-also: - curl_easy_escape (3) - curl_easy_unescape (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_getenv.md b/docs/libcurl/curl_getenv.md index a334479a4ff..0092c676bce 100644 --- a/docs/libcurl/curl_getenv.md +++ b/docs/libcurl/curl_getenv.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - getenv (3C) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_global_cleanup.md b/docs/libcurl/curl_global_cleanup.md index 3ae162a1add..11adb2b55b5 100644 --- a/docs/libcurl/curl_global_cleanup.md +++ b/docs/libcurl/curl_global_cleanup.md @@ -9,7 +9,7 @@ See-also: - libcurl (3) - libcurl-thread (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_global_init.md b/docs/libcurl/curl_global_init.md index 84a081742a8..e48a1f36fed 100644 --- a/docs/libcurl/curl_global_init.md +++ b/docs/libcurl/curl_global_init.md @@ -12,7 +12,7 @@ See-also: - curl_global_trace (3) - libcurl (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_global_init_mem.md b/docs/libcurl/curl_global_init_mem.md index 7a2c5b54f69..229d4d606be 100644 --- a/docs/libcurl/curl_global_init_mem.md +++ b/docs/libcurl/curl_global_init_mem.md @@ -8,7 +8,7 @@ See-also: - curl_global_cleanup (3) - curl_global_init (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_global_sslset.md b/docs/libcurl/curl_global_sslset.md index 14f05a75e8c..1fdc2d3201c 100644 --- a/docs/libcurl/curl_global_sslset.md +++ b/docs/libcurl/curl_global_sslset.md @@ -8,7 +8,7 @@ See-also: - curl_global_init (3) - libcurl (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_global_trace.md b/docs/libcurl/curl_global_trace.md index 5d9e8d5eaa6..8aae45784c0 100644 --- a/docs/libcurl/curl_global_trace.md +++ b/docs/libcurl/curl_global_trace.md @@ -8,7 +8,7 @@ See-also: - curl_global_init (3) - libcurl (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_mprintf.md b/docs/libcurl/curl_mprintf.md index b5afa896b8a..b98bcec214f 100644 --- a/docs/libcurl/curl_mprintf.md +++ b/docs/libcurl/curl_mprintf.md @@ -10,7 +10,7 @@ See-also: - sprintf (3) - vprintf (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_add_handle.md b/docs/libcurl/curl_multi_add_handle.md index cca2a693e31..3f6120fc428 100644 --- a/docs/libcurl/curl_multi_add_handle.md +++ b/docs/libcurl/curl_multi_add_handle.md @@ -11,7 +11,7 @@ See-also: - curl_multi_setopt (3) - curl_multi_socket_action (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_assign.md b/docs/libcurl/curl_multi_assign.md index e58bc2283e5..dd32b36b05c 100644 --- a/docs/libcurl/curl_multi_assign.md +++ b/docs/libcurl/curl_multi_assign.md @@ -8,7 +8,7 @@ See-also: - curl_multi_setopt (3) - curl_multi_socket_action (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_cleanup.md b/docs/libcurl/curl_multi_cleanup.md index 767b07b2f7b..e8e02a4b064 100644 --- a/docs/libcurl/curl_multi_cleanup.md +++ b/docs/libcurl/curl_multi_cleanup.md @@ -10,7 +10,7 @@ See-also: - curl_multi_get_handles (3) - curl_multi_init (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_fdset.md b/docs/libcurl/curl_multi_fdset.md index fa808b85583..1fe6e1f6760 100644 --- a/docs/libcurl/curl_multi_fdset.md +++ b/docs/libcurl/curl_multi_fdset.md @@ -12,7 +12,7 @@ See-also: - curl_multi_wait (3) - select (2) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_get_handles.md b/docs/libcurl/curl_multi_get_handles.md index e4bcfc332a6..a0b4bfb9c5a 100644 --- a/docs/libcurl/curl_multi_get_handles.md +++ b/docs/libcurl/curl_multi_get_handles.md @@ -10,7 +10,7 @@ See-also: - curl_multi_init (3) - curl_multi_remove_handle (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_info_read.md b/docs/libcurl/curl_multi_info_read.md index adb93ba5123..0ba3ee352f3 100644 --- a/docs/libcurl/curl_multi_info_read.md +++ b/docs/libcurl/curl_multi_info_read.md @@ -9,7 +9,7 @@ See-also: - curl_multi_init (3) - curl_multi_perform (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_init.md b/docs/libcurl/curl_multi_init.md index 5462666de72..0431985576d 100644 --- a/docs/libcurl/curl_multi_init.md +++ b/docs/libcurl/curl_multi_init.md @@ -11,7 +11,7 @@ See-also: - curl_multi_cleanup (3) - curl_multi_get_handles (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_perform.md b/docs/libcurl/curl_multi_perform.md index de5b4207ba7..eebed6e7d0e 100644 --- a/docs/libcurl/curl_multi_perform.md +++ b/docs/libcurl/curl_multi_perform.md @@ -13,7 +13,7 @@ See-also: - curl_multi_wait (3) - libcurl-errors (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_poll.md b/docs/libcurl/curl_multi_poll.md index d76545af1d8..360e14d8e8c 100644 --- a/docs/libcurl/curl_multi_poll.md +++ b/docs/libcurl/curl_multi_poll.md @@ -10,7 +10,7 @@ See-also: - curl_multi_wait (3) - curl_multi_wakeup (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_remove_handle.md b/docs/libcurl/curl_multi_remove_handle.md index db9490a0a24..b026466acce 100644 --- a/docs/libcurl/curl_multi_remove_handle.md +++ b/docs/libcurl/curl_multi_remove_handle.md @@ -9,7 +9,7 @@ See-also: - curl_multi_cleanup (3) - curl_multi_init (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_setopt.md b/docs/libcurl/curl_multi_setopt.md index 75075b4c560..399060fc27b 100644 --- a/docs/libcurl/curl_multi_setopt.md +++ b/docs/libcurl/curl_multi_setopt.md @@ -10,7 +10,7 @@ See-also: - curl_multi_init (3) - curl_multi_socket (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_socket.md b/docs/libcurl/curl_multi_socket.md index 78ad91c0f05..4c85d01997b 100644 --- a/docs/libcurl/curl_multi_socket.md +++ b/docs/libcurl/curl_multi_socket.md @@ -11,7 +11,7 @@ See-also: - curl_multi_init (3) - the hiperfifo.c example Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_socket_action.md b/docs/libcurl/curl_multi_socket_action.md index 9d989a459b2..c7faa763726 100644 --- a/docs/libcurl/curl_multi_socket_action.md +++ b/docs/libcurl/curl_multi_socket_action.md @@ -11,7 +11,7 @@ See-also: - curl_multi_init (3) - the hiperfifo.c example Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_socket_all.md b/docs/libcurl/curl_multi_socket_all.md index 78ad91c0f05..4c85d01997b 100644 --- a/docs/libcurl/curl_multi_socket_all.md +++ b/docs/libcurl/curl_multi_socket_all.md @@ -11,7 +11,7 @@ See-also: - curl_multi_init (3) - the hiperfifo.c example Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_strerror.md b/docs/libcurl/curl_multi_strerror.md index be0710715bb..4b53d67874e 100644 --- a/docs/libcurl/curl_multi_strerror.md +++ b/docs/libcurl/curl_multi_strerror.md @@ -10,7 +10,7 @@ See-also: - curl_url_strerror (3) - libcurl-errors (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_timeout.md b/docs/libcurl/curl_multi_timeout.md index 9a33d0c853a..ed8a8acbce2 100644 --- a/docs/libcurl/curl_multi_timeout.md +++ b/docs/libcurl/curl_multi_timeout.md @@ -10,7 +10,7 @@ See-also: - curl_multi_setopt (3) - curl_multi_socket (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_wait.md b/docs/libcurl/curl_multi_wait.md index 7a05974c8cb..de8e0ff1f5c 100644 --- a/docs/libcurl/curl_multi_wait.md +++ b/docs/libcurl/curl_multi_wait.md @@ -9,7 +9,7 @@ See-also: - curl_multi_perform (3) - curl_multi_poll (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_multi_wakeup.md b/docs/libcurl/curl_multi_wakeup.md index 6b0ad97c4dd..cadaeaa31b8 100644 --- a/docs/libcurl/curl_multi_wakeup.md +++ b/docs/libcurl/curl_multi_wakeup.md @@ -8,7 +8,7 @@ See-also: - curl_multi_poll (3) - curl_multi_wait (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_share_cleanup.md b/docs/libcurl/curl_share_cleanup.md index 607bcd92629..36acc6f08b8 100644 --- a/docs/libcurl/curl_share_cleanup.md +++ b/docs/libcurl/curl_share_cleanup.md @@ -8,7 +8,7 @@ See-also: - curl_share_init (3) - curl_share_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_share_init.md b/docs/libcurl/curl_share_init.md index 6c997ee6b15..2e74dfed859 100644 --- a/docs/libcurl/curl_share_init.md +++ b/docs/libcurl/curl_share_init.md @@ -8,7 +8,7 @@ See-also: - curl_share_cleanup (3) - curl_share_setopt (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_share_setopt.md b/docs/libcurl/curl_share_setopt.md index c7722c7989e..166f5f6ba49 100644 --- a/docs/libcurl/curl_share_setopt.md +++ b/docs/libcurl/curl_share_setopt.md @@ -8,7 +8,7 @@ See-also: - curl_share_cleanup (3) - curl_share_init (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_share_strerror.md b/docs/libcurl/curl_share_strerror.md index 0e529ea5b50..9137115a224 100644 --- a/docs/libcurl/curl_share_strerror.md +++ b/docs/libcurl/curl_share_strerror.md @@ -10,7 +10,7 @@ See-also: - curl_url_strerror (3) - libcurl-errors (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_slist_append.md b/docs/libcurl/curl_slist_append.md index adeb715039e..dd3dabb7731 100644 --- a/docs/libcurl/curl_slist_append.md +++ b/docs/libcurl/curl_slist_append.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - curl_slist_free_all (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_slist_free_all.md b/docs/libcurl/curl_slist_free_all.md index 74c89079a6f..5f54fabc1f2 100644 --- a/docs/libcurl/curl_slist_free_all.md +++ b/docs/libcurl/curl_slist_free_all.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - curl_slist_append (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_strequal.md b/docs/libcurl/curl_strequal.md index c86370147d4..70de794aa5a 100644 --- a/docs/libcurl/curl_strequal.md +++ b/docs/libcurl/curl_strequal.md @@ -8,7 +8,7 @@ See-also: - strcasecmp (3) - strcmp (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_strnequal.md b/docs/libcurl/curl_strnequal.md index c86370147d4..70de794aa5a 100644 --- a/docs/libcurl/curl_strnequal.md +++ b/docs/libcurl/curl_strnequal.md @@ -8,7 +8,7 @@ See-also: - strcasecmp (3) - strcmp (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_unescape.md b/docs/libcurl/curl_unescape.md index 0a470ce1798..adcce8b14fd 100644 --- a/docs/libcurl/curl_unescape.md +++ b/docs/libcurl/curl_unescape.md @@ -10,7 +10,7 @@ See-also: - curl_easy_unescape (3) - curl_free (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_url.md b/docs/libcurl/curl_url.md index 7b72b6c72bd..acab43d88c8 100644 --- a/docs/libcurl/curl_url.md +++ b/docs/libcurl/curl_url.md @@ -12,7 +12,7 @@ See-also: - curl_url_set (3) - curl_url_strerror (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_url_cleanup.md b/docs/libcurl/curl_url_cleanup.md index c7fe7b761b6..ab0acdce877 100644 --- a/docs/libcurl/curl_url_cleanup.md +++ b/docs/libcurl/curl_url_cleanup.md @@ -11,7 +11,7 @@ See-also: - curl_url_get (3) - curl_url_set (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_url_dup.md b/docs/libcurl/curl_url_dup.md index da4e3f44314..43b54eb2988 100644 --- a/docs/libcurl/curl_url_dup.md +++ b/docs/libcurl/curl_url_dup.md @@ -11,7 +11,7 @@ See-also: - curl_url_get (3) - curl_url_set (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_url_get.md b/docs/libcurl/curl_url_get.md index 6db66dfcd98..2f3b89b5e50 100644 --- a/docs/libcurl/curl_url_get.md +++ b/docs/libcurl/curl_url_get.md @@ -12,7 +12,7 @@ See-also: - curl_url_set (3) - curl_url_strerror (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_url_set.md b/docs/libcurl/curl_url_set.md index cfd63a8b457..328937c690c 100644 --- a/docs/libcurl/curl_url_set.md +++ b/docs/libcurl/curl_url_set.md @@ -12,7 +12,7 @@ See-also: - curl_url_get (3) - curl_url_strerror (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_url_strerror.md b/docs/libcurl/curl_url_strerror.md index b3d27a22a1a..a57e19df1d2 100644 --- a/docs/libcurl/curl_url_strerror.md +++ b/docs/libcurl/curl_url_strerror.md @@ -12,7 +12,7 @@ See-also: - curl_url_set (3) - libcurl-errors (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_version.md b/docs/libcurl/curl_version.md index 27f2320bf2d..48a102f0995 100644 --- a/docs/libcurl/curl_version.md +++ b/docs/libcurl/curl_version.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - curl_version_info (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/curl_version_info.md b/docs/libcurl/curl_version_info.md index bf1ca74171a..43365ac6dc3 100644 --- a/docs/libcurl/curl_version_info.md +++ b/docs/libcurl/curl_version_info.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - curl_version (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-easy.md b/docs/libcurl/libcurl-easy.md index c37e7e37260..1286f41135d 100644 --- a/docs/libcurl/libcurl-easy.md +++ b/docs/libcurl/libcurl-easy.md @@ -12,7 +12,7 @@ See-also: - libcurl-errors (3) - libcurl-multi (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-env-dbg.md b/docs/libcurl/libcurl-env-dbg.md index 1ed68657af4..2ab8c2b9559 100644 --- a/docs/libcurl/libcurl-env-dbg.md +++ b/docs/libcurl/libcurl-env-dbg.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - libcurl-env (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-env.md b/docs/libcurl/libcurl-env.md index 5ebad896bbe..0db69ff958f 100644 --- a/docs/libcurl/libcurl-env.md +++ b/docs/libcurl/libcurl-env.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - libcurl-env-dbg (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-errors.md b/docs/libcurl/libcurl-errors.md index 134718112e6..af16b99dea6 100644 --- a/docs/libcurl/libcurl-errors.md +++ b/docs/libcurl/libcurl-errors.md @@ -13,7 +13,7 @@ See-also: - curl_share_strerror (3) - curl_url_strerror (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-multi.md b/docs/libcurl/libcurl-multi.md index d43cb61e8ac..cf3bc56931a 100644 --- a/docs/libcurl/libcurl-multi.md +++ b/docs/libcurl/libcurl-multi.md @@ -9,7 +9,7 @@ See-also: - libcurl-easy (3) - libcurl-errors (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-security.md b/docs/libcurl/libcurl-security.md index a1e0af81fbf..93a1161363c 100644 --- a/docs/libcurl/libcurl-security.md +++ b/docs/libcurl/libcurl-security.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - libcurl-thread (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-share.md b/docs/libcurl/libcurl-share.md index 726db8adf5e..f820967dfe9 100644 --- a/docs/libcurl/libcurl-share.md +++ b/docs/libcurl/libcurl-share.md @@ -12,7 +12,7 @@ See-also: - libcurl-errors (3) - libcurl-multi (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-thread.md b/docs/libcurl/libcurl-thread.md index cc55378c859..4ca783af1ab 100644 --- a/docs/libcurl/libcurl-thread.md +++ b/docs/libcurl/libcurl-thread.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - libcurl-security (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-tutorial.md b/docs/libcurl/libcurl-tutorial.md index afe9e288d6e..c51d9f13c33 100644 --- a/docs/libcurl/libcurl-tutorial.md +++ b/docs/libcurl/libcurl-tutorial.md @@ -10,7 +10,7 @@ See-also: - libcurl-multi (3) - libcurl-url (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-url.md b/docs/libcurl/libcurl-url.md index 3cda90539c3..e673873b43e 100644 --- a/docs/libcurl/libcurl-url.md +++ b/docs/libcurl/libcurl-url.md @@ -13,7 +13,7 @@ See-also: - curl_url_set (3) - curl_url_strerror (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl-ws.md b/docs/libcurl/libcurl-ws.md index 7aa9857abb4..25550ecd68a 100644 --- a/docs/libcurl/libcurl-ws.md +++ b/docs/libcurl/libcurl-ws.md @@ -13,7 +13,7 @@ See-also: - curl_ws_recv (3) - curl_ws_send (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/libcurl.md b/docs/libcurl/libcurl.md index 1b3fa00d1e9..9031451cc00 100644 --- a/docs/libcurl/libcurl.md +++ b/docs/libcurl/libcurl.md @@ -10,7 +10,7 @@ See-also: - libcurl-security (3) - libcurl-thread (3) Protocol: - - * + - All --- # NAME diff --git a/docs/libcurl/mksymbolsmanpage.pl b/docs/libcurl/mksymbolsmanpage.pl index 90de3debb7b..fc9a8b704ac 100755 --- a/docs/libcurl/mksymbolsmanpage.pl +++ b/docs/libcurl/mksymbolsmanpage.pl @@ -41,7 +41,7 @@ Section: 3 Source: libcurl Protocol: - - * + - All See-also: - libcurl (3) - libcurl-easy (3) diff --git a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md index a2877dc1394..92567e627d9 100644 --- a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md +++ b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -40,10 +40,6 @@ CURLOPT_CONNECT_ONLY(3), which skips the transfer phase. CURLINFO_ACTIVESOCKET(3) was added as a replacement for CURLINFO_LASTSOCKET(3) since that one is not working on all platforms. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md index 0ea124da564..a40f6d02e22 100644 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -37,10 +37,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md index a9986d22b28..0d61f05d209 100644 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CAINFO.md b/docs/libcurl/opts/CURLINFO_CAINFO.md index e9ba9d34328..ea61a1a7483 100644 --- a/docs/libcurl/opts/CURLINFO_CAINFO.md +++ b/docs/libcurl/opts/CURLINFO_CAINFO.md @@ -40,10 +40,6 @@ This is a path identifying a single file containing CA certificates. The **path** pointer is set to NULL if there is no default path. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CAPATH.md b/docs/libcurl/opts/CURLINFO_CAPATH.md index 0c9e21dee89..8b6f8bf7774 100644 --- a/docs/libcurl/opts/CURLINFO_CAPATH.md +++ b/docs/libcurl/opts/CURLINFO_CAPATH.md @@ -43,10 +43,6 @@ This is a path identifying a directory. The **path** pointer is set to NULL if there is no default path. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.md b/docs/libcurl/opts/CURLINFO_CERTINFO.md index 507c946e64a..633beed17be 100644 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.md +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.md @@ -50,10 +50,6 @@ items with textual information in the format "name:content" such as "Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on the SSL backend and the certificate. -# PROTOCOLS - -All TLS-based - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md index ed3654b6e88..00cbd5308ca 100644 --- a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md +++ b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.md @@ -36,10 +36,6 @@ gets a zero stored if the condition instead was met. This can also return 1 if the server responded with a 304 HTTP status code, for example after sending a custom "If-Match-*" header. -# PROTOCOLS - -HTTP and some - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md index acbd2732a67..7a5b4bdfcf0 100644 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -33,10 +33,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md index 63abaf3d6f9..00d582388d7 100644 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONN_ID.md b/docs/libcurl/opts/CURLINFO_CONN_ID.md index d09a3afa876..3face4207c6 100644 --- a/docs/libcurl/opts/CURLINFO_CONN_ID.md +++ b/docs/libcurl/opts/CURLINFO_CONN_ID.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ The connection id is unique among all connections using the same connection cache. This is implicitly the case for all connections in the same multi handle. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md index b25ddec8f97..0cb1b47d1b0 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ is the value read from the Content-Length: field. Since 7.19.4, this returns CURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3) is a newer replacement that returns a more sensible variable type. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md index 0518fb9484d..15b4f631fac 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md @@ -31,10 +31,6 @@ Pass a pointer to a *curl_off_t* to receive the content-length of the download. This is the value read from the Content-Length: field. Stores -1 if the size is not known. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md index 51c26fd6ec6..7cba9aa3397 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -33,10 +33,6 @@ Pass a pointer to a double to receive the specified size of the upload. Since CURLINFO_CONTENT_LENGTH_UPLOAD_T(3) is a newer replacement that returns a more sensible variable type. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md index 23cfe03a5c3..babd796e341 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -30,10 +30,6 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD_T, Pass a pointer to a *curl_off_t* to receive the specified size of the upload. Stores -1 if the size is not known. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md index 8427e6aa741..25cb737e05a 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md @@ -39,10 +39,6 @@ corresponding CURL handle. The modern way to get this header from a response is to instead use the curl_easy_header(3) function. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_COOKIELIST.md b/docs/libcurl/opts/CURLINFO_COOKIELIST.md index 4c538892b9a..64e9f4a6599 100644 --- a/docs/libcurl/opts/CURLINFO_COOKIELIST.md +++ b/docs/libcurl/opts/CURLINFO_COOKIELIST.md @@ -36,10 +36,6 @@ received) the 'struct curl_slist *' is made a NULL pointer. Since 7.43.0 cookies that were imported in the Set-Cookie format without a domain name are not exported by this option. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md index 0b7b9c3c52f..e10142f5d65 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md @@ -38,10 +38,6 @@ The **methodp** pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call curl_easy_cleanup(3) on the corresponding CURL handle. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md index 0dc2cc7d298..3892bd7bce4 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md @@ -35,10 +35,6 @@ The **urlp** pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call curl_easy_cleanup(3) on the corresponding CURL handle. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.md b/docs/libcurl/opts/CURLINFO_FILETIME.md index bf6716b025f..4e4d7f190f0 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME.md +++ b/docs/libcurl/opts/CURLINFO_FILETIME.md @@ -41,10 +41,6 @@ you this unconditionally gets a -1 back. Consider using CURLINFO_FILETIME_T(3) to be able to extract dates beyond the year 2038 on systems using 32 bit longs (Windows). -# PROTOCOLS - -HTTP(S), FTP(S), SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.md b/docs/libcurl/opts/CURLINFO_FILETIME_T.md index 2d86e3272c3..0ba24d61ffb 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME_T.md +++ b/docs/libcurl/opts/CURLINFO_FILETIME_T.md @@ -43,10 +43,6 @@ This option is an alternative to CURLINFO_FILETIME(3) to allow systems with 32 bit long variables to extract dates outside of the 32bit timestamp range. -# PROTOCOLS - -HTTP(S), FTP(S), SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md index 1ef47542fc5..2276a551387 100644 --- a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md +++ b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md @@ -34,10 +34,6 @@ The **path** pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call curl_easy_cleanup(3) on the corresponding CURL handle. -# PROTOCOLS - -FTP(S) and SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md index b6533fd678d..f60ab524586 100644 --- a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md +++ b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -33,10 +33,6 @@ received. Measured in number of bytes. The total includes the size of any received headers suppressed by CURLOPT_SUPPRESS_CONNECT_HEADERS(3). -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md index c03dcfe61e6..21d92c323e8 100644 --- a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md +++ b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.md @@ -32,10 +32,6 @@ method(s) available according to the previous response. The meaning of the bits is explained in the CURLOPT_HTTPAUTH(3) option for curl_easy_setopt(3). -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md index ea9e527eb53..d5fb41c3d5e 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md +++ b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.md @@ -30,10 +30,6 @@ Pass a pointer to a long to receive the last received HTTP proxy response code to a CONNECT request. The returned value is zero if no such response code was available. -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md index 6a8a0b28156..8ca341fe231 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md +++ b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.md @@ -31,10 +31,6 @@ connection done using this handle. The returned value is CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the version cannot be determined. -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_LASTSOCKET.md b/docs/libcurl/opts/CURLINFO_LASTSOCKET.md index 9b4a84cdffb..8e98df90e2a 100644 --- a/docs/libcurl/opts/CURLINFO_LASTSOCKET.md +++ b/docs/libcurl/opts/CURLINFO_LASTSOCKET.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -40,10 +40,6 @@ NOTE: this API is deprecated since it is not working on win64 where the SOCKET type is 64 bits large while its 'long' is 32 bits. Use the CURLINFO_ACTIVESOCKET(3) instead, if possible. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md index 689a576a1b2..d3e2118b1fb 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md +++ b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -37,10 +37,6 @@ The **ip** pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call curl_easy_cleanup(3) on the corresponding CURL handle. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md index 5d9a77d92f0..47034160053 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md +++ b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.md @@ -30,10 +30,6 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_PORT, long *portp); Pass a pointer to a long to receive the local port number of the most recent connection done with this **curl** handle. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md index ccc45cdce9b..29dd375a5fa 100644 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md index 7d11f75287b..eb0bae79707 100644 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md index 7f184e052a9..5488fcc4268 100644 --- a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md +++ b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.md @@ -8,7 +8,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -32,10 +32,6 @@ many times libcurl successfully reused existing connection(s) or not. See the connection options of curl_easy_setopt(3) to see how libcurl tries to make persistent connections to save time. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_OS_ERRNO.md b/docs/libcurl/opts/CURLINFO_OS_ERRNO.md index bf5a6f6657c..85084778a8e 100644 --- a/docs/libcurl/opts/CURLINFO_OS_ERRNO.md +++ b/docs/libcurl/opts/CURLINFO_OS_ERRNO.md @@ -8,7 +8,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -29,10 +29,6 @@ Pass a pointer to a long to receive the errno variable from a connect failure. Note that the value is only set on failure, it is not reset upon a successful operation. The number is OS and system specific. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md index e7645d7f39c..04adf5aa6ea 100644 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -39,10 +39,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md index 7ecf4fc7a2e..b1049a66308 100644 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -39,10 +39,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md index 3f9b918bb8b..31237f65660 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md @@ -11,7 +11,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ The **ip** pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call curl_easy_cleanup(3) on the corresponding CURL handle. -# PROTOCOLS - -All network based ones - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md index 12f384da4e8..a1de51db37b 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ If a proxy was used for the most recent transfer, this is the port number of the proxy, if no proxy was used it is the port number of the most recently accessed URL. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PRIVATE.md b/docs/libcurl/opts/CURLINFO_PRIVATE.md index 548eacf29b2..4a4d351500d 100644 --- a/docs/libcurl/opts/CURLINFO_PRIVATE.md +++ b/docs/libcurl/opts/CURLINFO_PRIVATE.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -31,10 +31,6 @@ associated with the curl handle (set with the CURLOPT_PRIVATE(3)). Please note that for internal reasons, the value is returned as a char pointer, although effectively being a 'void *'. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PROTOCOL.md b/docs/libcurl/opts/CURLINFO_PROTOCOL.md index 0b213310fb7..13c5973816c 100644 --- a/docs/libcurl/opts/CURLINFO_PROTOCOL.md +++ b/docs/libcurl/opts/CURLINFO_PROTOCOL.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -43,10 +43,6 @@ CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROTO_SMTP, CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP, CURLPROTO_MQTT ~~~ -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md index 1c353453b2a..823bdd38522 100644 --- a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md +++ b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.md @@ -32,10 +32,6 @@ method(s) available according to the previous response. The meaning of the bits is explained in the CURLOPT_PROXYAUTH(3) option for curl_easy_setopt(3). -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md index 73c21ccd839..1d8855f37ad 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md +++ b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.md @@ -10,7 +10,7 @@ See-also: - curl_easy_setopt (3) - libcurl-errors (3) Protocol: - - * + - All --- # NAME @@ -71,10 +71,6 @@ transfer returned a **CURLE_PROXY** error. That error code matches the The error code is zero (**CURLPX_OK**) if no response code was available. -# PROTOCOLS - -All that can be done over SOCKS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md index cf76cd24308..073de0aa535 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md +++ b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.md @@ -34,10 +34,6 @@ Pass a pointer to a long to receive the result of the certificate verification that was requested (using the CURLOPT_PROXY_SSL_VERIFYPEER(3) option. This is only used for HTTPS proxies. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md index a4375200038..c61ca2faa58 100644 --- a/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_QUEUE_TIME_T.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ connection etc due to set conditions and limits imposed by the application. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md index 38a0c908f29..bcfaa362d51 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -31,10 +31,6 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_COUNT, Pass a pointer to a long to receive the total number of redirections that were actually followed. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md index cd54bcb0832..202343d61ae 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.md @@ -36,10 +36,6 @@ the complete execution time for multiple redirections. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md index da5b07b1081..0ccafa0770a 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.md @@ -37,10 +37,6 @@ multiple redirections. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md index d3db71a1f41..70a4f6cc3bd 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.md @@ -37,10 +37,6 @@ figuring out the new URL. This URL is also set if the CURLOPT_MAXREDIRS(3) limit prevented a redirect to happen (since 7.54.1). -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_REFERER.md b/docs/libcurl/opts/CURLINFO_REFERER.md index 7dca94bd8cd..6850b6de78c 100644 --- a/docs/libcurl/opts/CURLINFO_REFERER.md +++ b/docs/libcurl/opts/CURLINFO_REFERER.md @@ -34,10 +34,6 @@ The **hdrp** pointer is NULL or points to private memory you MUST NOT free - it gets freed when you call curl_easy_cleanup(3) on the corresponding CURL handle. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md index beae30a21e0..89452d32bfb 100644 --- a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md +++ b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -31,10 +31,6 @@ Pass a pointer to a long to receive the total size of the issued requests. This is so far only for HTTP requests. Note that this may be more than one request if CURLOPT_FOLLOWLOCATION(3) is enabled. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md index 9bf15306a69..ea7d8f3f4bb 100644 --- a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md +++ b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.md @@ -37,10 +37,6 @@ no server response code has been received. Note that a proxy's CONNECT response should be read with CURLINFO_HTTP_CONNECTCODE(3) and not this. -# PROTOCOLS - -HTTP, FTP, SMTP and LDAP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md index 1c06f77d9b5..b194fc9224b 100644 --- a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md +++ b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_STDERR (3) - curl_easy_header (3) Protocol: - - * + - All --- # NAME @@ -39,10 +39,6 @@ or zero if there was no header or the header could not be parsed. Returns zero delay if there was no header. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md index 3e7de2578c2..d79e2cc7087 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.md @@ -31,10 +31,6 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CLIENT_CSEQ, Pass a pointer to a long to receive the next CSeq that is expected to be used by the application. -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md index 241b65816d3..3e9d17fccb6 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.md @@ -31,10 +31,6 @@ server. If your application encounters a *CURLE_RTSP_CSEQ_ERROR* then you may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this value. -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md index e13bb918a21..5b866c57136 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.md @@ -35,10 +35,6 @@ Listening for server initiated requests is not implemented! Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection. -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md index e046cce3f0a..24a2b1d5772 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md @@ -36,10 +36,6 @@ The **id** pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call curl_easy_cleanup(3) on the corresponding CURL handle. -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SCHEME.md b/docs/libcurl/opts/CURLINFO_SCHEME.md index fc5eaef2d3b..5b89bfc142b 100644 --- a/docs/libcurl/opts/CURLINFO_SCHEME.md +++ b/docs/libcurl/opts/CURLINFO_SCHEME.md @@ -11,7 +11,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -36,10 +36,6 @@ The **scheme** pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call curl_easy_cleanup(3) on the corresponding CURL handle. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md index fa74e4f00fe..6eaad7b7c9b 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.md @@ -11,7 +11,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -37,10 +37,6 @@ number. CURLINFO_SIZE_DOWNLOAD_T(3) is a newer replacement that returns a more sensible variable type. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md index 55c9d5fef67..9c2a9cea6a1 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.md @@ -11,7 +11,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ were downloaded. The amount is only for the latest transfer and gets reset again for each new transfer. This counts actual payload data, what's also commonly called body. All meta and header data is excluded from this amount. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md index c79b235da48..fa3989eed6b 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ uploaded. CURLINFO_SIZE_UPLOAD_T(3) is a newer replacement that returns a more sensible variable type. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md index a9ef09b4984..bea4078cacf 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -31,10 +31,6 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD_T, Pass a pointer to a *curl_off_t* to receive the total amount of bytes that were uploaded. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md index 8662f2a0e3c..98ada9adfba 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -34,8 +34,6 @@ measured for the complete download. Measured in bytes/second. CURLINFO_SPEED_DOWNLOAD_T(3) is a newer replacement that returns a more sensible variable type. -# PROTOCOLS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md index 3facdf5cbb2..a1f8178bda5 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -31,8 +31,6 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD_T, Pass a pointer to a *curl_off_t* to receive the average download speed that curl measured for the complete download. Measured in bytes/second. -# PROTOCOLS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md index e787253234c..f963eca1975 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -32,8 +32,6 @@ measured for the complete upload. Measured in bytes/second. CURLINFO_SPEED_UPLOAD_T(3) is a newer replacement that returns a more sensible variable type. -# PROTOCOLS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md index 806cc357d65..45cb6bf2d93 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -30,8 +30,6 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD_T, Pass a pointer to a *curl_off_t* to receive the average upload speed that curl measured for the complete upload. Measured in bytes/second. -# PROTOCOLS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md index 1035bd3b01c..9a410873404 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md +++ b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.md @@ -36,10 +36,6 @@ available at runtime. **NOTE:** you must call curl_slist_free_all(3) on the list pointer once you are done with it, as libcurl does not free this data for you. -# PROTOCOLS - -All TLS based ones. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md index edee07e9960..27cbfde71ab 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md +++ b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.md @@ -36,10 +36,6 @@ option). 0 is a positive result. Non-zero is an error. -# PROTOCOLS - -All using TLS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md index 063cafe5212..b58e41ac56e 100644 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -37,10 +37,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md index cb414e9219d..27c55bfc898 100644 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md index ccdd1cc320e..2dc710a4af3 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.md @@ -47,10 +47,6 @@ function *SSL_get_SSL_CTX(3)*. Therefore unless you need compatibility with older versions of libcurl use CURLINFO_TLS_SSL_PTR(3). Refer to that document for more information. -# PROTOCOLS - -All TLS-based - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md index 2ce6e232c45..097bf98b340 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.md @@ -131,10 +131,6 @@ How are you using this option? Are you affected by any of these limitations? Please let us know by making a comment at https://github.com/curl/curl/issues/685 -# PROTOCOLS - -All TLS-based - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md index 51dcf2477ef..0229605905c 100644 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md index e45216d16cc..0bff41bd40b 100644 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ When a redirect is followed, the time from each request is added together. See also the TIMES overview in the curl_easy_getinfo(3) man page. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_USED_PROXY.md b/docs/libcurl/opts/CURLINFO_USED_PROXY.md index 55e00d1f3e4..7b38ea02735 100644 --- a/docs/libcurl/opts/CURLINFO_USED_PROXY.md +++ b/docs/libcurl/opts/CURLINFO_USED_PROXY.md @@ -10,7 +10,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -31,10 +31,6 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_USED_PROXY, Pass a pointer to a long. It gets set to zero set if no proxy was used in the previous transfer or a non-zero value if a proxy was used. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLINFO_XFER_ID.md b/docs/libcurl/opts/CURLINFO_XFER_ID.md index 34f5b39fb87..0855ac9a1d6 100644 --- a/docs/libcurl/opts/CURLINFO_XFER_ID.md +++ b/docs/libcurl/opts/CURLINFO_XFER_ID.md @@ -9,7 +9,7 @@ See-also: - curl_easy_getinfo (3) - curl_easy_setopt (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ The transfer id is unique among all transfers performed using the same connection cache. This is implicitly the case for all transfers in the same multi handle. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md index c467d5c3201..e292792ee12 100644 --- a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md +++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md @@ -39,10 +39,6 @@ than CURLMOPT_MAX_PIPELINE_LENGTH(3). The default value is 0, which means that the penalization is inactive. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md index 8abfd99b865..8f0783b60be 100644 --- a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md +++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md @@ -38,10 +38,6 @@ CURLMOPT_MAX_PIPELINE_LENGTH(3). The default value is 0, which means that the size penalization is inactive. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md index 317eea6d01b..1e5a947ed1e 100644 --- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md +++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.md @@ -8,7 +8,7 @@ See-also: - CURLMOPT_MAX_HOST_CONNECTIONS (3) - CURLOPT_MAXCONNECTS (3) Protocol: - - * + - All --- # NAME @@ -52,10 +52,6 @@ ones to get made. See DESCRIPTION -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md index 65495ba8181..b8e7fefdb9c 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.md @@ -37,10 +37,6 @@ value passed here would be honored based on other system resources properties. 100 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md index 099efddc5cc..f798a462671 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.md @@ -8,7 +8,7 @@ See-also: - CURLMOPT_MAXCONNECTS (3) - CURLMOPT_MAX_TOTAL_CONNECTIONS (3) Protocol: - - * + - All --- # NAME @@ -55,10 +55,6 @@ ones to get made. 0 -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md index 625e6564aa3..84ab65e6201 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.md @@ -8,7 +8,7 @@ See-also: - CURLMOPT_MAX_HOST_CONNECTIONS (3) - CURLMOPT_PIPELINING (3) Protocol: - - * + - All --- # NAME @@ -42,10 +42,6 @@ CURLMOPT_MAX_PIPELINE_LENGTH(3). 5 -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md index 4d976429914..a227a9ccec3 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md +++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.md @@ -8,7 +8,7 @@ See-also: - CURLMOPT_MAXCONNECTS (3) - CURLMOPT_MAX_HOST_CONNECTIONS (3) Protocol: - - * + - All --- # NAME @@ -48,10 +48,6 @@ timeout is however treated as a per-connect timeout. The default value is 0, which means that there is no limit. It is then simply controlled by the number of easy handles added. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.md b/docs/libcurl/opts/CURLMOPT_PIPELINING.md index 4228baa3107..66570a8232f 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.md @@ -54,10 +54,6 @@ Since 7.62.0, **CURLPIPE_MULTIPLEX** is enabled by default. Before that, default was **CURLPIPE_NOTHING**. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md index 3af2b5ae6f6..0fc11fdc356 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.md @@ -43,8 +43,6 @@ Pass a NULL pointer to clear the block list. The default value is NULL, which means that there is no block list. -# PROTOCOLS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md index 661edf2c25e..dc009a27d04 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.md @@ -38,10 +38,6 @@ Pass a NULL pointer to clear the block list. The default value is NULL, which means that there is no block list. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md index 2372decdf37..23399d17d8f 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHDATA.md +++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.md @@ -35,10 +35,6 @@ libcurl itself, only passed on to the callback function. NULL -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md index 3377081246e..c8011283944 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.md @@ -96,10 +96,6 @@ All other return codes are reserved for future use. NULL, no callback -# PROTOCOLS - -HTTP(S) (HTTP/2 only) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md index 597f8625a79..7aea20c44d2 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.md @@ -9,7 +9,7 @@ See-also: - CURLMOPT_TIMERFUNCTION (3) - curl_multi_socket_action (3) Protocol: - - * + - All --- # NAME @@ -36,10 +36,6 @@ callback's **clientp** argument. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index d2f18244677..a16747c04af 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -9,7 +9,7 @@ See-also: - CURLMOPT_TIMERFUNCTION (3) - curl_multi_socket_action (3) Protocol: - - * + - All --- # NAME @@ -89,10 +89,6 @@ active transfer. It might soon be added again. NULL (no callback) -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md index 5b8092fdf8a..fb830b1fbfa 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.md +++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.md @@ -8,7 +8,7 @@ See-also: - CURLMOPT_SOCKETFUNCTION (3) - CURLMOPT_TIMERFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ callback's **clientp** argument. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md index ee23505274a..85f9957a731 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.md @@ -8,7 +8,7 @@ See-also: - CURLMOPT_SOCKETFUNCTION (3) - CURLMOPT_TIMERDATA (3) Protocol: - - * + - All --- # NAME @@ -63,10 +63,6 @@ callback with a zero timeout... NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md index 84884291c72..c34acbd63be 100644 --- a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md +++ b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_UNIX_SOCKET_PATH (3) - unix (7) Protocol: - - * + - All --- # NAME @@ -44,10 +44,6 @@ share the same storage and therefore only one of them can be set per handle. Default is NULL. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md index 6e44c4c3e3f..f1db8fa6907 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md @@ -33,10 +33,6 @@ server to connect back to libcurl when an active FTP connection is used. 60000 milliseconds -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md index 87be71032d4..c090ef31847 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md +++ b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md @@ -75,10 +75,6 @@ option. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md index 6e977a861db..24ea2e581b2 100644 --- a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md +++ b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_STDERR (3) Protocol: - - * + - All --- # NAME @@ -31,10 +31,6 @@ Pass a long specifying the scope id value to use when connecting to IPv6 address 0 -# PROTOCOLS - -All, when using IPv6 - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC.md b/docs/libcurl/opts/CURLOPT_ALTSVC.md index 803561f42d9..8ca2de4bece 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC.md +++ b/docs/libcurl/opts/CURLOPT_ALTSVC.md @@ -38,10 +38,6 @@ Specify a blank filename ("") to make libcurl not load from a file at all. NULL. The alt-svc cache is not read nor written to file. -# PROTOCOLS - -HTTPS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md index 11250870c8b..971f33fcbb7 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md +++ b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md @@ -72,10 +72,6 @@ CURLOPT_ALTSVC_CTRL(3) has a default value corresponding to CURLALTSVC_H1 | CURLALTSVC_H2 | CURLALTSVC_H3 - the HTTP/2 and HTTP/3 bits are only set if libcurl was built with support for those versions. -# PROTOCOLS - -HTTPS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_APPEND.md b/docs/libcurl/opts/CURLOPT_APPEND.md index 81dd29594d6..6c5142b4914 100644 --- a/docs/libcurl/opts/CURLOPT_APPEND.md +++ b/docs/libcurl/opts/CURLOPT_APPEND.md @@ -33,10 +33,6 @@ instead of overwrite it. This is only useful when uploading to an FTP site. 0 (disabled) -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.md b/docs/libcurl/opts/CURLOPT_AUTOREFERER.md index a5ee9282a5a..754dee3ba23 100644 --- a/docs/libcurl/opts/CURLOPT_AUTOREFERER.md +++ b/docs/libcurl/opts/CURLOPT_AUTOREFERER.md @@ -43,10 +43,6 @@ referer header after the transfer. 0, disabled -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md index b9ed60334df..adb6d6afdb1 100644 --- a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.md @@ -68,10 +68,6 @@ By default, the value of this parameter is NULL. Calling CURLOPT_HTTPAUTH(3) with CURLAUTH_AWS_SIGV4 is the same as calling this with **"aws:amz"** in parameter. -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md index 68365479a68..d2c13b6b309 100644 --- a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_UPLOAD_BUFFERSIZE (3) - CURLOPT_WRITEFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -53,10 +53,6 @@ allocated as long as there are active transfers. CURL_MAX_WRITE_SIZE (16kB) -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.md b/docs/libcurl/opts/CURLOPT_CAINFO.md index 38ef173ff80..87d1a8809f0 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO.md @@ -60,10 +60,6 @@ The default value for this can be figured out with CURLINFO_CAINFO(3). Built-in system specific. When curl is built with Secure Transport or Schannel, this option is not set by default. -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md index 17079321540..d650243253c 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md @@ -53,10 +53,6 @@ This option overrides CURLOPT_CAINFO(3). NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.md b/docs/libcurl/opts/CURLOPT_CAPATH.md index 212b4876017..08caf762ae2 100644 --- a/docs/libcurl/opts/CURLOPT_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_CAPATH.md @@ -50,10 +50,6 @@ The default value for this can be figured out with CURLINFO_CAPATH(3). A default path detected at build time. -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md index d90b208e732..aa479b6bec2 100644 --- a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md @@ -46,10 +46,6 @@ store remain forever. By default, libcurl caches this info for 24 hours. 86400 (24 hours) -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.md b/docs/libcurl/opts/CURLOPT_CERTINFO.md index 7789b29881a..71339cd0322 100644 --- a/docs/libcurl/opts/CURLOPT_CERTINFO.md +++ b/docs/libcurl/opts/CURLOPT_CERTINFO.md @@ -43,10 +43,6 @@ its option CURLINFO_CERTINFO(3). 0 -# PROTOCOLS - -All TLS-based - # EXAMPLE ~~~c @@ -88,9 +84,7 @@ int main(void) # AVAILABILITY -This option is supported by the OpenSSL, GnuTLS, Schannel and Secure -Transport backends. Schannel support added in 7.50.0. Secure Transport support -added in 7.79.0. +Schannel support added in 7.50.0. Secure Transport support added in 7.79.0. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md index be42c2597ad..01b6f78dc07 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.md @@ -83,10 +83,6 @@ Return *CURL_CHUNK_BGN_FUNC_OK* if everything is fine, NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md index 43e01285a17..b501138e9fd 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.md @@ -33,10 +33,6 @@ CURLOPT_CHUNK_END_FUNCTION(3). NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md index 5ae6ff1920c..295e29ea9d2 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.md @@ -41,10 +41,6 @@ Return *CURL_CHUNK_END_FUNC_OK* if everything is fine or NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md index c8d4fc81ac6..7353af9ae54 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_CLOSESOCKETFUNCTION (3) - CURLOPT_OPENSOCKETFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ CURLOPT_CLOSESOCKETFUNCTION(3). The default value of this parameter is NULL. -# PROTOCOLS - -All except file: - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 1eb634be07f..18e3bfe7124 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_CLOSESOCKETDATA (3) - CURLOPT_OPENSOCKETFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -45,10 +45,6 @@ closed. By default libcurl uses the standard socket close function. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md index 697bf4b5157..f8e51d88e2d 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_MAX_RECV_SPEED_LARGE (3) - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -60,10 +60,6 @@ signals to be used unless CURLOPT_NOSIGNAL(3) is set. 300 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md index 1d5088f45cd..1c22fd8727d 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -36,10 +36,6 @@ See CURLOPT_CONNECTTIMEOUT(3) for details. 300000 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md index 39496994e29..8fcb5a3b7d2 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md +++ b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.md @@ -10,7 +10,7 @@ See-also: - curl_easy_recv (3) - curl_easy_send (3) Protocol: - - * + - All --- # NAME @@ -54,10 +54,6 @@ curl_easy_recv(3) do not function. 0 -# PROTOCOLS - -HTTP, SMTP, POP3 and IMAP. For WS and WSS starting in 7.86.0. - # EXAMPLE ~~~c @@ -78,7 +74,7 @@ int main(void) # AVAILABILITY -Added in 7.15.2 +Added in 7.15.2. WS and WSS support added in 7.86.0. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_TO.md b/docs/libcurl/opts/CURLOPT_CONNECT_TO.md index c85bdc5cffd..4714cb2bd59 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_TO.md +++ b/docs/libcurl/opts/CURLOPT_CONNECT_TO.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_RESOLVE (3) - CURLOPT_URL (3) Protocol: - - * + - All --- # NAME @@ -79,10 +79,6 @@ a transfer before you call curl_slist_free_all(3) on the list. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md index 5dbb8336c13..6cde80b1fb2 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_CONV_FROM_UTF8_FUNCTION (3) - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) Protocol: - - * + - All --- # NAME @@ -72,10 +72,6 @@ You need to override these definitions if they are different on your system. NULL -# PROTOCOLS - -FTP, SMTP, IMAP, POP3 - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md index ca59dc5a6b7..60cdcd0ed11 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.md @@ -5,7 +5,7 @@ Title: CURLOPT_CONV_FROM_UTF8_FUNCTION Section: 3 Source: libcurl Protocol: - - * + - All See-also: - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) @@ -69,10 +69,6 @@ You need to override these definitions if they are different on your system. NULL -# PROTOCOLS - -TLS-based protocols. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md index cab8b15ae51..a8d22ed5429 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) - CURLOPT_CONV_FROM_UTF8_FUNCTION (3) Protocol: - - * + - All --- # NAME @@ -71,10 +71,6 @@ You need to override these definitions if they are different on your system. NULL -# PROTOCOLS - -FTP, SMTP, IMAP, POP3 - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.md b/docs/libcurl/opts/CURLOPT_COOKIE.md index e9ad140004b..7c6ae67c7d6 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIE.md +++ b/docs/libcurl/opts/CURLOPT_COOKIE.md @@ -69,10 +69,6 @@ ability to stop super cookies. PSL support is identified by the NULL, no cookies -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.md b/docs/libcurl/opts/CURLOPT_COOKIEFILE.md index 018355ac095..89ec0a43eb6 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.md +++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.md @@ -67,10 +67,6 @@ run. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.md b/docs/libcurl/opts/CURLOPT_COOKIEJAR.md index 21a86c5f468..f08e8078fb9 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEJAR.md +++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.md @@ -53,10 +53,6 @@ option. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.md b/docs/libcurl/opts/CURLOPT_COOKIELIST.md index acedd3cab69..7be0c1debb2 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.md +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.md @@ -69,10 +69,6 @@ loads all cookies from the files specified by CURLOPT_COOKIEFILE(3) NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_COOKIESESSION.md b/docs/libcurl/opts/CURLOPT_COOKIESESSION.md index e319ceeeebf..705b1b7d82d 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIESESSION.md +++ b/docs/libcurl/opts/CURLOPT_COOKIESESSION.md @@ -41,10 +41,6 @@ the same session. 0 -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md index 86a04332431..a483740146a 100644 --- a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md +++ b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md @@ -45,10 +45,6 @@ CURLOPT_COPYPOSTFIELDS(3) option is issued. NULL -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CRLF.md b/docs/libcurl/opts/CURLOPT_CRLF.md index 719b8a709a4..e49be9893a7 100644 --- a/docs/libcurl/opts/CURLOPT_CRLF.md +++ b/docs/libcurl/opts/CURLOPT_CRLF.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_CONV_FROM_NETWORK_FUNCTION (3) - CURLOPT_CONV_TO_NETWORK_FUNCTION (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ This is a legacy option of questionable use. 0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.md b/docs/libcurl/opts/CURLOPT_CRLFILE.md index fc11ad25811..b544f37771a 100644 --- a/docs/libcurl/opts/CURLOPT_CRLFILE.md +++ b/docs/libcurl/opts/CURLOPT_CRLFILE.md @@ -58,10 +58,6 @@ option. NULL -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CURLU.md b/docs/libcurl/opts/CURLOPT_CURLU.md index ac9059f51d8..2bb1e73a970 100644 --- a/docs/libcurl/opts/CURLOPT_CURLU.md +++ b/docs/libcurl/opts/CURLOPT_CURLU.md @@ -13,7 +13,7 @@ See-also: - curl_url_set (3) - curl_url_strerror (3) Protocol: - - * + - All --- # NAME @@ -46,10 +46,6 @@ updated contents is used. The default value of this parameter is NULL. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md index 3bbe39cb36e..62c8cf87c46 100644 --- a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md +++ b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md @@ -102,10 +102,6 @@ option. NULL -# PROTOCOLS - -HTTP, FTP, IMAP, POP3 and SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.md b/docs/libcurl/opts/CURLOPT_DEBUGDATA.md index 22c393c0093..0864388c2bc 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGDATA.md +++ b/docs/libcurl/opts/CURLOPT_DEBUGDATA.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_DEBUGFUNCTION (3) - CURLOPT_STDERR (3) Protocol: - - * + - All --- # NAME @@ -33,10 +33,6 @@ not used by libcurl, it is only passed to the callback. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md index e6d22d8e95d..a0927e20280 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.md @@ -11,7 +11,7 @@ See-also: - CURLOPT_VERBOSE (3) - curl_global_trace (3) Protocol: - - * + - All --- # NAME @@ -101,10 +101,6 @@ set CURLOPT_PRIVATE(3) on your handle. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md index da9fb9b1af2..7da62e18a43 100644 --- a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md +++ b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md @@ -9,7 +9,7 @@ See-also: - CURLINFO_SCHEME (3) - CURLOPT_URL (3) Protocol: - - * + - All --- # NAME @@ -55,10 +55,6 @@ option. NULL (make a guess based on the host) -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md index 61ab733f95a..8775d16f101 100644 --- a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md +++ b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.md @@ -50,10 +50,6 @@ effectively breaks that feature. 0, disabled -# PROTOCOLS - -FTP, SFTP and POP3 - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md index 8a5652331a3..788ef30185a 100644 --- a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md +++ b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md @@ -10,7 +10,7 @@ See-also: - curl_url_set (3) - libcurl-security (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ curl_url_set(3) function. 0 (disabled) - usernames are allowed by default. -# PROTOCOLS - -Several - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md index 20a56b2b7f4..ca0c896e403 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.md @@ -11,7 +11,7 @@ See-also: - CURLOPT_MAXAGE_CONN (3) - CURLOPT_RESOLVE (3) Protocol: - - * + - All --- # NAME @@ -54,10 +54,6 @@ Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds 60 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md index 753a891a11b..20dc86edc05 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md +++ b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_DNS_SERVERS (3) - CURLOPT_INTERFACE (3) Protocol: - - * + - All --- # NAME @@ -39,10 +39,6 @@ option. NULL -# PROTOCOLS - -All protocols except file:// - protocols that resolve hostnames. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md index 4a20703faac..67a6bd204d7 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_DNS_LOCAL_IP6 (3) - CURLOPT_DNS_SERVERS (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ option. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md index c6463cb02ae..332debd6b49 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_DNS_LOCAL_IP4 (3) - CURLOPT_DNS_SERVERS (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ option. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md index 63a99f46ba5..42874bd5335 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md +++ b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_DNS_LOCAL_IP4 (3) - CURLOPT_DNS_LOCAL_IP6 (3) Protocol: - - * + - All --- # NAME @@ -42,10 +42,6 @@ option. NULL - use system default -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md index b9ed92cff9c..33dcb0f060c 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md +++ b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_DNS_CACHE_TIMEOUT (3) - CURLOPT_IPRESOLVE (3) Protocol: - - * + - All --- # NAME @@ -46,10 +46,6 @@ performance impacts and may cause IPv4 to be used before IPv6 or vice versa. 0 (disabled) -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md index b742ed19321..616ddb9511b 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md +++ b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_DNS_CACHE_TIMEOUT (3) - CURLOPT_SHARE (3) Protocol: - - * + - All --- # NAME @@ -32,17 +32,13 @@ Pass a long. If the *enable* value is 1, it tells curl to use a global DNS cache that survives between easy handle creations and deletions. This is not thread-safe and this uses a global variable. -See CURLOPT_SHARE(3) and curl_share_init(3) for the correct way to -share DNS cache between transfers. +See CURLOPT_SHARE(3) and curl_share_init(3) for the correct way to share DNS +cache between transfers. # DEFAULT 0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md index 21ac14d4dba..4211f03cbfb 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md @@ -59,10 +59,6 @@ of the DoH server certificate. 2 -# PROTOCOLS - -DoH - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md index ca45ce3cd81..b35fa5272ec 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md @@ -71,10 +71,6 @@ the correct end-point. 1 -# PROTOCOLS - -DoH - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md index 4b5d5bfca7a..8135cb4c7c0 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md @@ -46,10 +46,6 @@ the verification fails. 0 -# PROTOCOLS - -DoH - # EXAMPLE ~~~c @@ -72,8 +68,7 @@ int main(void) # AVAILABILITY -Added in 7.76.0. This option is currently only supported by the OpenSSL, and -GnuTLS TLS backends. +Added in 7.76.0. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_DOH_URL.md b/docs/libcurl/opts/CURLOPT_DOH_URL.md index 3aa55c6038a..d382ca67d7c 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_URL.md +++ b/docs/libcurl/opts/CURLOPT_DOH_URL.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_RESOLVE (3) - CURLOPT_VERBOSE (3) Protocol: - - * + - All --- # NAME @@ -66,10 +66,6 @@ CURLOPT_FTPPORT(3), a proxy type set to **CURLPROXY_SOCKS4** or NULL - there is no default DoH URL. If this option is not set, libcurl uses the default name resolver. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md index 8106fce6304..32ae012e56c 100644 --- a/docs/libcurl/opts/CURLOPT_EGDSOCKET.md +++ b/docs/libcurl/opts/CURLOPT_EGDSOCKET.md @@ -38,10 +38,6 @@ option. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c @@ -60,8 +56,7 @@ int main(void) # AVAILABILITY -If built with TLS enabled. Only the OpenSSL backend uses this, and only with -OpenSSL versions before 1.1.0. +Only with OpenSSL versions before 1.1.0. This option was deprecated in 7.84.0. diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md index c354b89bf7f..7a90f1d6c3c 100644 --- a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md +++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.md @@ -12,7 +12,7 @@ See-also: - curl_share_strerror (3) - curl_url_strerror (3) Protocol: - - * + - All --- # NAME @@ -51,10 +51,6 @@ debug and trace why errors happen. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md index 60c8fe4b727..7f6f274b415 100644 --- a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md @@ -36,10 +36,6 @@ sent anyway. 1000 milliseconds -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.md b/docs/libcurl/opts/CURLOPT_FAILONERROR.md index 78a29278bb6..aabee4e4db0 100644 --- a/docs/libcurl/opts/CURLOPT_FAILONERROR.md +++ b/docs/libcurl/opts/CURLOPT_FAILONERROR.md @@ -45,10 +45,6 @@ get closed and *CURLE_HTTP_RETURNED_ERROR* is returned. 0, do not fail on error -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FILETIME.md b/docs/libcurl/opts/CURLOPT_FILETIME.md index 95a4d1b426c..1f4782e3e03 100644 --- a/docs/libcurl/opts/CURLOPT_FILETIME.md +++ b/docs/libcurl/opts/CURLOPT_FILETIME.md @@ -39,10 +39,6 @@ transfer to extract the received time (if any). 0 -# PROTOCOLS - -HTTP(S), FTP(S), SFTP, FILE, SMB(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md index 0afd4b611f0..33dce7b0cfc 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md @@ -33,10 +33,6 @@ the CURLOPT_FNMATCH_FUNCTION(3). NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md index 58b6af1d134..16526931e39 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md @@ -44,10 +44,6 @@ error occurred. NULL == an internal function for wildcard matching. -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md index 60aaf5293f6..9dee48befaf 100644 --- a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md +++ b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md @@ -65,10 +65,6 @@ would otherwise select internally. 0, disabled -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md index 8cd601cd546..bbd1c48f79f 100644 --- a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md +++ b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_MAXCONNECTS (3) - CURLOPT_MAXLIFETIME_CONN (3) Protocol: - - * + - All --- # NAME @@ -39,10 +39,6 @@ Set to 0 to have libcurl keep the connection open for possible later reuse 0 -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md index 3010529f732..f7ffbe89a52 100644 --- a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md +++ b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md @@ -5,7 +5,7 @@ Title: CURLOPT_FRESH_CONNECT Section: 3 Source: libcurl Protocol: - - * + - All See-also: - CURLOPT_FORBID_REUSE (3) - CURLOPT_MAXAGE_CONN (3) @@ -41,10 +41,6 @@ Set *fresh* to 0 to have libcurl attempt reusing an existing connection 0 -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.md b/docs/libcurl/opts/CURLOPT_FTPPORT.md index d83221c3123..869a862f92e 100644 --- a/docs/libcurl/opts/CURLOPT_FTPPORT.md +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.md @@ -70,10 +70,6 @@ option. NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md index a356a72e5dc..d40c75fe489 100644 --- a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md +++ b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md @@ -47,10 +47,6 @@ Try "AUTH TLS" first, and only if that fails try "AUTH SSL". CURLFTPAUTH_DEFAULT -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md index 0ce40000126..de6b2a50e6a 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md +++ b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md @@ -36,10 +36,6 @@ option. NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md index ed91dc434ae..7d334f54525 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md +++ b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.md @@ -41,10 +41,6 @@ option. NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md index 2fcf162269f..5a6dbf696d2 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md +++ b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.md @@ -55,10 +55,6 @@ but then another connection does **MKD** before this connection and thus CURLFTP_CREATE_DIR_NONE (0) -# PROTOCOLS - -FTP and SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md index df7648f1072..351dfe10e12 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md +++ b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.md @@ -56,10 +56,6 @@ compliant than 'nocwd' but without the full penalty of 'multicwd'. CURLFTPMETHOD_MULTICWD -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md index 3c3e3965368..cdec3371b8b 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md +++ b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.md @@ -42,10 +42,6 @@ This option has no effect if PORT, EPRT or EPSV is used instead of PASV. 1 since 7.74.0, was 0 before then. -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md index e6cff67af1b..6155c4aedb7 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md +++ b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.md @@ -49,10 +49,6 @@ Initiate the shutdown and wait for a reply. CURLFTPSSL_CCC_NONE -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md index b6f178d4186..54df9257394 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.md @@ -41,8 +41,6 @@ then. # DEFAULT -# PROTOCOLS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md index 460f5d3bdb2..41d8f9ed078 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.md @@ -41,10 +41,6 @@ If the server is an IPv6 host, this option has no effect. 1 -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md index 5130ee54856..1d9507c78b5 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.md @@ -34,10 +34,6 @@ no effect when using the active FTP transfers mode. 0 -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md index a04b556072b..01bf42d1716 100644 --- a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md +++ b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.md @@ -37,10 +37,6 @@ available at compile-time. CURLGSSAPI_DELEGATION_NONE -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md index d0ee69be46d..5f51f942294 100644 --- a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md @@ -5,7 +5,7 @@ Title: CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS Section: 3 Source: libcurl Protocol: - - * + - All See-also: - CURLOPT_CONNECTTIMEOUT_MS (3) - CURLOPT_LOW_SPEED_LIMIT (3) @@ -42,10 +42,6 @@ currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms. CURL_HET_DEFAULT (currently defined as 200L) -# PROTOCOLS - -All except FILE - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md index 2639ebcd702..da4f35ce52a 100644 --- a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md +++ b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - CURLOPT_PROXY (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ Most applications do not need this option. 0, do not send any HAProxy PROXY protocol header -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md index 88751a50384..fdb16fe6498 100644 --- a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md +++ b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md @@ -5,7 +5,7 @@ Title: CURLOPT_HAPROXY_CLIENT_IP Section: 3 Source: libcurl Protocol: - - * + - All See-also: - CURLOPT_HAPROXYPROTOCOL (3) - CURLOPT_PROXY (3) @@ -37,10 +37,6 @@ cannot use a specified address. NULL, no HAProxy header is sent -# PROTOCOLS - -HTTP, HAProxy PROTOCOL - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HEADER.md b/docs/libcurl/opts/CURLOPT_HEADER.md index 7dad63afe8e..09262f697c0 100644 --- a/docs/libcurl/opts/CURLOPT_HEADER.md +++ b/docs/libcurl/opts/CURLOPT_HEADER.md @@ -53,10 +53,6 @@ custom HTTP headers! 0 -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HEADERDATA.md b/docs/libcurl/opts/CURLOPT_HEADERDATA.md index 703197d9b88..84d232eb801 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERDATA.md +++ b/docs/libcurl/opts/CURLOPT_HEADERDATA.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_WRITEFUNCTION (3) - curl_easy_header (3) Protocol: - - * + - All --- # NAME @@ -43,10 +43,6 @@ this option or you might experience crashes. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md index 812355f400d..6668c82c2d0 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md @@ -100,11 +100,6 @@ although strictly they are just continuations of the previous lines. Nothing. -# PROTOCOLS - -Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3, -IMAP, SMTP and more. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HEADEROPT.md b/docs/libcurl/opts/CURLOPT_HEADEROPT.md index 6980a9e6545..833fda0631f 100644 --- a/docs/libcurl/opts/CURLOPT_HEADEROPT.md +++ b/docs/libcurl/opts/CURLOPT_HEADEROPT.md @@ -44,10 +44,6 @@ proxy and then CURLOPT_HTTPHEADER(3) headers only to the server. CURLHEADER_SEPARATE (changed in 7.42.1, used CURLHEADER_UNIFIED before then) -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HSTS.md b/docs/libcurl/opts/CURLOPT_HSTS.md index 84afddf34d8..b71476e5bc8 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS.md +++ b/docs/libcurl/opts/CURLOPT_HSTS.md @@ -59,10 +59,6 @@ currently no length or size limit. NULL, no filename -# PROTOCOLS - -HTTPS and HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md index 1232ed789b3..8c323098228 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md +++ b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.md @@ -38,10 +38,6 @@ do that. NULL -# PROTOCOLS - -This feature is only used for HTTP(S) transfer. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md index c10f9b03349..fe55ab8de80 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.md @@ -63,10 +63,6 @@ do that. NULL - no callback. -# PROTOCOLS - -This feature is only used for HTTP(S) transfer. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md index c0df683e40a..23c7302f0c1 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md @@ -38,10 +38,6 @@ do that. NULL -# PROTOCOLS - -This feature is only used for HTTP(S) transfer. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md index faa6c8c9853..8fa62151052 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.md @@ -67,10 +67,6 @@ do that. NULL - no callback. -# PROTOCOLS - -This feature is only used for HTTP(S) transfer. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md index 54bbe9540bb..dec7a38440b 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md +++ b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.md @@ -54,10 +54,6 @@ to the file when closing the handle. 0. HSTS is disabled by default. -# PROTOCOLS - -HTTPS and HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md index e3eb6b9de04..6312148c265 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md +++ b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.md @@ -38,10 +38,6 @@ curl allowed HTTP/0.9 responses by default before 7.66.0 Since 7.66.0, libcurl requires this option set to 1L to allow HTTP/0.9 responses. -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md index db74c6f6cca..4363ef44415 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md +++ b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md @@ -44,10 +44,6 @@ assumed to match HTTP 1.0 when an alias match. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.md b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md index 8b5336f65f9..9e29f7cae3a 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.md +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.md @@ -123,10 +123,6 @@ see CURLOPT_AWS_SIGV4(3). CURLAUTH_BASIC -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.md b/docs/libcurl/opts/CURLOPT_HTTPGET.md index 1051fe8cdb3..8f5c35463c1 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPGET.md +++ b/docs/libcurl/opts/CURLOPT_HTTPGET.md @@ -42,10 +42,6 @@ reset a handle to default method, consider curl_easy_reset(3). 0 -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.md b/docs/libcurl/opts/CURLOPT_HTTPHEADER.md index 84d729b0370..7f060ea897b 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.md +++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.md @@ -148,10 +148,6 @@ with the CURLOPT_UNRESTRICTED_AUTH(3) option. NULL -# PROTOCOLS - -HTTP, IMAP and SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.md b/docs/libcurl/opts/CURLOPT_HTTPPOST.md index aa4ab542b81..0c39471476c 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.md +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.md @@ -49,10 +49,6 @@ CURLOPT_NOBODY(3) to 0. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md index e2173796aeb..9591892df71 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md +++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md @@ -5,7 +5,7 @@ Title: CURLOPT_HTTPPROXYTUNNEL Section: 3 Source: libcurl Protocol: - - * + - All See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYPORT (3) @@ -49,10 +49,6 @@ rarely works through the proxy anyway). 0 -# PROTOCOLS - -All network protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md index 5e87fcfda5d..10ff5ab4d0a 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.md @@ -36,10 +36,6 @@ CURLOPT_ACCEPT_ENCODING(3) for that. 1 -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md index 2031075fd02..c0b88b83f72 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.md @@ -34,10 +34,6 @@ does chunked transfer decoding by default unless this option is set to zero. 1 -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md index a3902756059..88a7154b9f8 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md +++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.md @@ -89,10 +89,6 @@ Since curl 7.62.0: CURL_HTTP_VERSION_2TLS Before that: CURL_HTTP_VERSION_1_1 -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md index cdaafcb4837..a39573e6a68 100644 --- a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md +++ b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md @@ -45,10 +45,6 @@ Only use this option if strictly necessary. 0 -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.md b/docs/libcurl/opts/CURLOPT_INFILESIZE.md index 2da76012188..522bdb41a4d 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE.md +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_INFILESIZE_LARGE (3) - CURLOPT_UPLOAD (3) Protocol: - - * + - All --- # NAME @@ -50,10 +50,6 @@ and sending a different amount may lead to errors. Unset -# PROTOCOLS - -Many - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md index a48500fcc96..712cd58028a 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_INFILESIZE (3) - CURLOPT_UPLOAD (3) Protocol: - - * + - All --- # NAME @@ -47,10 +47,6 @@ and sending a different amount may lead to errors. Unset -# PROTOCOLS - -Many - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.md b/docs/libcurl/opts/CURLOPT_INTERFACE.md index bccc91dabfd..f79a43078eb 100644 --- a/docs/libcurl/opts/CURLOPT_INTERFACE.md +++ b/docs/libcurl/opts/CURLOPT_INTERFACE.md @@ -5,7 +5,7 @@ Title: CURLOPT_INTERFACE Section: 3 Source: libcurl Protocol: - - * + - All See-also: - CURLOPT_SOCKOPTFUNCTION (3) - CURLOPT_TCP_NODELAY (3) @@ -53,10 +53,6 @@ option. NULL, use whatever the TCP stack finds suitable -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md index 0e1f087937f..508c76f1331 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md @@ -34,10 +34,6 @@ anywhere. NULL -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md index 0b353cc9629..7d2e52857e4 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.md @@ -65,10 +65,6 @@ You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) NULL, the interleave data is then passed to the regular write function: CURLOPT_WRITEFUNCTION(3). -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_IOCTLDATA.md b/docs/libcurl/opts/CURLOPT_IOCTLDATA.md index 19cd5b3745d..ef33d7ce56a 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLDATA.md +++ b/docs/libcurl/opts/CURLOPT_IOCTLDATA.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_IOCTLFUNCTION (3) - CURLOPT_SEEKFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -32,10 +32,6 @@ argument in the ioctl callback set with CURLOPT_IOCTLFUNCTION(3). By default, the value of this parameter is NULL. -# PROTOCOLS - -Used with HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md index d23d4ceb7e6..75e04c3028f 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md @@ -5,7 +5,7 @@ Title: CURLOPT_IOCTLFUNCTION Section: 3 Source: libcurl Protocol: - - * + - All See-also: - CURLOPT_IOCTLDATA (3) - CURLOPT_SEEKFUNCTION (3) @@ -63,10 +63,6 @@ parameter is ignored when seeking. By default, this parameter is set to NULL. Not used. -# PROTOCOLS - -Used with HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md index 393fd0d4722..acf0b383055 100644 --- a/docs/libcurl/opts/CURLOPT_IPRESOLVE.md +++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_RESOLVE (3) - CURLOPT_SSLVERSION (3) Protocol: - - * + - All --- # NAME @@ -52,10 +52,6 @@ Uses only IPv6 addresses. CURL_IPRESOLVE_WHATEVER -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md index 559b8f224bf..f9000559ed4 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT.md +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT.md @@ -52,10 +52,6 @@ option. NULL -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md index 51ed6a32e94..142225da63a 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.md @@ -58,10 +58,6 @@ expects a filename as input. NULL -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md index 33ed1fb2122..6a48523e844 100644 --- a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md +++ b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.md @@ -41,10 +41,6 @@ Most applications do not need this option. 0, stop sending on error -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md index a8bc4702aef..408ccfbfb6e 100644 --- a/docs/libcurl/opts/CURLOPT_KEYPASSWD.md +++ b/docs/libcurl/opts/CURLOPT_KEYPASSWD.md @@ -42,10 +42,6 @@ option. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_KRBLEVEL.md b/docs/libcurl/opts/CURLOPT_KRBLEVEL.md index 84fa2a6288d..dfadcf436b7 100644 --- a/docs/libcurl/opts/CURLOPT_KRBLEVEL.md +++ b/docs/libcurl/opts/CURLOPT_KRBLEVEL.md @@ -38,10 +38,6 @@ option. NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORT.md b/docs/libcurl/opts/CURLOPT_LOCALPORT.md index 01f70890378..94b5d50f84e 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORT.md +++ b/docs/libcurl/opts/CURLOPT_LOCALPORT.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_INTERFACE (3) - CURLOPT_LOCALPORTRANGE (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ this option is set. Valid port numbers are 1 - 65535. 0, disabled - use whatever the system thinks is fine -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md index 432133188eb..4549cafe305 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md +++ b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_INTERFACE (3) - CURLOPT_LOCALPORT (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ setup failures. 1 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md index 39235641849..5c879603a1f 100644 --- a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md @@ -51,10 +51,6 @@ option. NULL -# PROTOCOLS - -Only IMAP, LDAP, POP3 and SMTP support login options. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md index f9142ff47a2..d0131a4eeba 100644 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_MAX_SEND_SPEED_LARGE (3) - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -37,10 +37,6 @@ slow and abort. 0, disabled -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md index 9a5c4fd01e2..06e38c194c6 100644 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ library to consider it too slow and abort. 0, disabled -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md index 456e8011bd1..afe62b91cce 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.md @@ -48,10 +48,6 @@ option. NULL -# PROTOCOLS - -SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md index 45bd3ccf98d..52a8e51fc49 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_FROM.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_FROM.md @@ -41,10 +41,6 @@ option. blank -# PROTOCOLS - -SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md index 7dbb8cddcee..98b640e2edb 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.md @@ -48,10 +48,6 @@ should be specified using the mailing list name, such as `Friends` or NULL -# PROTOCOLS - -SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md index 13a3712d79f..d315d2bc8e9 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.md @@ -44,10 +44,6 @@ RCPT TO command. 0 -# PROTOCOLS - -SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md index 1854010b35a..6d92fa4afb9 100644 --- a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md +++ b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_MAXLIFETIME_CONN (3) - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -43,10 +43,6 @@ cache that is older than this set *age*, it is closed instead. Default maximum age is set to 118 seconds. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md index 04c9d128196..cd8b18dd051 100644 --- a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md +++ b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.md @@ -10,7 +10,7 @@ See-also: - CURLMOPT_MAX_TOTAL_CONNECTIONS (3) - CURLOPT_MAXREDIRS (3) Protocol: - - * + - All --- # NAME @@ -48,10 +48,6 @@ CURLMOPT_MAXCONNECTS(3) option. 5 -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md index aba74ac811a..36159709a18 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_MAXFILESIZE_LARGE (3) - CURLOPT_MAX_RECV_SPEED_LARGE (3) Protocol: - - * + - All --- # NAME @@ -42,10 +42,6 @@ threshold. None -# PROTOCOLS - -FTP, HTTP and MQTT - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md index b1c36d6b02d..d11a56225f1 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.md @@ -44,10 +44,6 @@ threshold. None -# PROTOCOLS - -FTP, HTTP and MQTT - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md index fb82447ab49..79b87245b7f 100644 --- a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md +++ b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_MAXAGE_CONN (3) - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -45,10 +45,6 @@ If set to 0, this behavior is disabled: all connections are eligible for reuse. Default *maxlifetime* is 0 seconds (i.e., disabled). -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.md b/docs/libcurl/opts/CURLOPT_MAXREDIRS.md index 93e44b94c56..751b22ed0df 100644 --- a/docs/libcurl/opts/CURLOPT_MAXREDIRS.md +++ b/docs/libcurl/opts/CURLOPT_MAXREDIRS.md @@ -40,10 +40,6 @@ to get stuck in never-ending redirect loops. 30 (since 8.3.0), it was previously unlimited. -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md index 3449caa457c..9e08a68dc29 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_MAX_SEND_SPEED_LARGE (3) - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -43,10 +43,6 @@ This option does not affect transfer speeds done with FILE:// URLs. 0, disabled -# PROTOCOLS - -All but file:// - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md index 74da35216fa..d8927269ae5 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_LOW_SPEED_LIMIT (3) - CURLOPT_MAX_RECV_SPEED_LARGE (3) Protocol: - - * + - All --- # NAME @@ -44,10 +44,6 @@ This option does not affect transfer speeds done with FILE:// URLs. 0, disabled -# PROTOCOLS - -All except file:// - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.md b/docs/libcurl/opts/CURLOPT_MIMEPOST.md index 5a81012aab0..8a4edb10b9c 100644 --- a/docs/libcurl/opts/CURLOPT_MIMEPOST.md +++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.md @@ -43,10 +43,6 @@ When setting CURLOPT_MIMEPOST(3) to NULL, libcurl resets the request type for HTTP to the default to disable the POST. Typically that would mean it is reset to GET. Instead you should set a desired request method explicitly. -# PROTOCOLS - -HTTP, SMTP, IMAP. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md index 183285d5062..f1f5fe0da57 100644 --- a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md @@ -56,10 +56,6 @@ containing multipart form is sent, this is normally transmitted as 0, meaning disabled. -# PROTOCOLS - -HTTP, IMAP, SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_NETRC.md b/docs/libcurl/opts/CURLOPT_NETRC.md index 3b69e0dd7a8..6b5e1d2e8da 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.md +++ b/docs/libcurl/opts/CURLOPT_NETRC.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_USERNAME (3) - CURLOPT_USERPWD (3) Protocol: - - * + - All --- # NAME @@ -115,10 +115,6 @@ done with "macdef" that it finds. CURL_NETRC_IGNORED -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_NETRC_FILE.md b/docs/libcurl/opts/CURLOPT_NETRC_FILE.md index faec392d404..57b2acb7886 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC_FILE.md +++ b/docs/libcurl/opts/CURLOPT_NETRC_FILE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_PASSWORD (3) - CURLOPT_USERNAME (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ option. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md index 5ba477d2464..51863440e42 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md +++ b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.md @@ -38,10 +38,6 @@ this are *sftp://*, *scp://*, and *file://*. 0755 -# PROTOCOLS - -SFTP, SCP and FILE - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md index 6d8c1425760..a04b99585de 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md +++ b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.md @@ -36,10 +36,6 @@ The only protocols that can use this are *sftp://*, *scp://*, and *file://*. 0644 -# PROTOCOLS - -SFTP, SCP and FILE - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.md b/docs/libcurl/opts/CURLOPT_NOBODY.md index eb1cd36dadd..319b9ed6171 100644 --- a/docs/libcurl/opts/CURLOPT_NOBODY.md +++ b/docs/libcurl/opts/CURLOPT_NOBODY.md @@ -11,7 +11,7 @@ See-also: - CURLOPT_REQUEST_TARGET (3) - CURLOPT_UPLOAD (3) Protocol: - - * + - All --- # NAME @@ -49,10 +49,6 @@ URL you request). 0, the body is transferred -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_NOPROGRESS.md b/docs/libcurl/opts/CURLOPT_NOPROGRESS.md index a0b22873f32..6363b18c149 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROGRESS.md +++ b/docs/libcurl/opts/CURLOPT_NOPROGRESS.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_VERBOSE (3) - CURLOPT_XFERINFOFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -36,10 +36,6 @@ getting called. 1, meaning it normally runs without a progress meter. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.md b/docs/libcurl/opts/CURLOPT_NOPROXY.md index 83d6058d0af..1f181c78069 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROXY.md +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.md @@ -5,7 +5,7 @@ Title: CURLOPT_NOPROXY Section: 3 Source: libcurl Protocol: - - * + - All See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYAUTH (3) @@ -60,10 +60,6 @@ the same way. NULL -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.md b/docs/libcurl/opts/CURLOPT_NOSIGNAL.md index c4ed07504ff..7d147d0f931 100644 --- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.md +++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -48,10 +48,6 @@ raised. 0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md index c7ebb902e09..5118ffe96e1 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_OPENSOCKETFUNCTION (3) - CURLOPT_SOCKOPTFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ CURLOPT_OPENSOCKETFUNCTION(3). The default value of this parameter is NULL. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md index 282ebfb92b3..554ac882224 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_OPENSOCKETFUNCTION (3) - CURLOPT_SOCKOPTFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -75,10 +75,6 @@ The default behavior is the equivalent of this: return socket(addr->family, addr->socktype, addr->protocol); ~~~ -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PASSWORD.md index f50bf8fed95..3aa4489b68d 100644 --- a/docs/libcurl/opts/CURLOPT_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PASSWORD.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_USERNAME (3) - CURLOPT_USERPWD (3) Protocol: - - * + - All --- # NAME @@ -40,10 +40,6 @@ option. blank -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md index 1dcd2489d0a..0c04b862bc2 100644 --- a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md +++ b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_URL (3) - curl_url_set (3) Protocol: - - * + - All --- # NAME @@ -47,10 +47,6 @@ The corresponding flag for the curl_url_set(3) function is called 0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md index 52ba595aef7..357f387efcf 100644 --- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md @@ -57,10 +57,6 @@ option. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.md b/docs/libcurl/opts/CURLOPT_PIPEWAIT.md index 9f039b6cf01..6fdbcee84b8 100644 --- a/docs/libcurl/opts/CURLOPT_PIPEWAIT.md +++ b/docs/libcurl/opts/CURLOPT_PIPEWAIT.md @@ -52,10 +52,6 @@ and support level. 0 (off) -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PORT.md b/docs/libcurl/opts/CURLOPT_PORT.md index 2dc6cfad03d..15d57f503c2 100644 --- a/docs/libcurl/opts/CURLOPT_PORT.md +++ b/docs/libcurl/opts/CURLOPT_PORT.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_STDERR (3) - CURLOPT_URL (3) Protocol: - - * + - All --- # NAME @@ -45,10 +45,6 @@ and therefore using a port number lower than zero or over 65535 causes a By default this is 0 which makes it not used. This also makes port number zero impossible to set with this API. -# PROTOCOLS - -Used for all protocols that speak to a port number. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_POST.md b/docs/libcurl/opts/CURLOPT_POST.md index d7e099870a8..b2aef4f3091 100644 --- a/docs/libcurl/opts/CURLOPT_POST.md +++ b/docs/libcurl/opts/CURLOPT_POST.md @@ -71,10 +71,6 @@ you should set a new request type explicitly as described above. 0, disabled -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md index f53a685b14f..8dc30483582 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md @@ -71,10 +71,6 @@ CURLOPT_MIMEPOST(3) option combined with curl_mime_init(3). NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md index 0334ae95f46..6fa83fdef36 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md @@ -37,10 +37,6 @@ If you post more than 2GB, use CURLOPT_POSTFIELDSIZE_LARGE(3). -1 -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md index 1de1c3a3ebc..a7adceca569 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md @@ -37,10 +37,6 @@ CURLOPT_READFUNCTION(3) (if used) to signal the end of data. -1 -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md index a4aa01923cd..fbd55fc50b4 100644 --- a/docs/libcurl/opts/CURLOPT_POSTQUOTE.md +++ b/docs/libcurl/opts/CURLOPT_POSTQUOTE.md @@ -38,10 +38,6 @@ Disable this operation again by setting a NULL to this option. NULL -# PROTOCOLS - -SFTP and FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_POSTREDIR.md b/docs/libcurl/opts/CURLOPT_POSTREDIR.md index 364b94dca26..4f63fd1cd23 100644 --- a/docs/libcurl/opts/CURLOPT_POSTREDIR.md +++ b/docs/libcurl/opts/CURLOPT_POSTREDIR.md @@ -48,10 +48,6 @@ when setting CURLOPT_FOLLOWLOCATION(3). 0 -# PROTOCOLS - -HTTP(S) - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PREQUOTE.md b/docs/libcurl/opts/CURLOPT_PREQUOTE.md index c3bbb16abef..887845875a6 100644 --- a/docs/libcurl/opts/CURLOPT_PREQUOTE.md +++ b/docs/libcurl/opts/CURLOPT_PREQUOTE.md @@ -42,10 +42,6 @@ this option does not. NULL -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PREREQDATA.md b/docs/libcurl/opts/CURLOPT_PREREQDATA.md index a575e1563de..821451bed36 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQDATA.md +++ b/docs/libcurl/opts/CURLOPT_PREREQDATA.md @@ -9,7 +9,7 @@ See-also: - CURLINFO_PRIMARY_PORT (3) - CURLOPT_PREREQFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -33,10 +33,6 @@ argument in the pre-request callback set with CURLOPT_PREREQFUNCTION(3). NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md index 454935f82bb..0ddd412b99d 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md @@ -9,7 +9,7 @@ See-also: - CURLINFO_PRIMARY_PORT (3) - CURLOPT_PREREQDATA (3) Protocol: - - * + - All --- # NAME @@ -85,10 +85,6 @@ The pointer you set with CURLOPT_PREREQDATA(3). By default, this is NULL and unused. -# PROTOCOLS - -ALL - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PRE_PROXY.md b/docs/libcurl/opts/CURLOPT_PRE_PROXY.md index 146863472d9..746a80833ed 100644 --- a/docs/libcurl/opts/CURLOPT_PRE_PROXY.md +++ b/docs/libcurl/opts/CURLOPT_PRE_PROXY.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_HTTPPROXYTUNNEL (3) - CURLOPT_PROXY (3) Protocol: - - * + - All --- # NAME @@ -57,10 +57,6 @@ Default is NULL, meaning no pre proxy is used. When you set a hostname to use, do not assume that there is any particular single port number used widely for proxies. Specify it! -# PROTOCOLS - -All except file://. Note that some protocols do not work well over proxy. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PRIVATE.md b/docs/libcurl/opts/CURLOPT_PRIVATE.md index cbe305efafd..0af8fc2e859 100644 --- a/docs/libcurl/opts/CURLOPT_PRIVATE.md +++ b/docs/libcurl/opts/CURLOPT_PRIVATE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_STDERR (3) - CURLOPT_VERBOSE (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ never does anything with this data. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md index b3ebd7dd7fa..fc915750b34 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md +++ b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_PROGRESSFUNCTION (3) - CURLOPT_XFERINFOFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -32,10 +32,6 @@ argument in the progress callback set with CURLOPT_PROGRESSFUNCTION(3). The default value of this parameter is NULL. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md index 8f8fafffad5..7bf26d63721 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_VERBOSE (3) - CURLOPT_XFERINFOFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -77,10 +77,6 @@ get called. By default, libcurl has an internal progress meter. That is rarely wanted by users. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.md b/docs/libcurl/opts/CURLOPT_PROTOCOLS.md index ca67d728e5f..a63821713a0 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS.md +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_REDIR_PROTOCOLS (3) - CURLOPT_URL (3) Protocol: - - * + - All --- # NAME @@ -73,10 +73,6 @@ CURLPROTO_TFTP All protocols built-in. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md index 3b45e2f3c95..f004d8d778c 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md @@ -11,7 +11,7 @@ See-also: - CURLOPT_URL (3) - curl_version_info (3) Protocol: - - * + - All --- # NAME @@ -56,10 +56,6 @@ way to figure out the protocol used in a previous transfer. All protocols built-in -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY.md b/docs/libcurl/opts/CURLOPT_PROXY.md index cea12e94743..a48f54e3378 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_PROXYPORT (3) - CURLOPT_PROXYTYPE (3) Protocol: - - * + - All --- # NAME @@ -114,10 +114,6 @@ Default is NULL, meaning no proxy is used. When you set a hostname to use, do not assume that there is any particular single port number used widely for proxies. Specify it! -# PROTOCOLS - -All except file://. Note that some protocols do not work well over proxy. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.md b/docs/libcurl/opts/CURLOPT_PROXYAUTH.md index 58f6f0b6b29..ca5204e5ea9 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYAUTH.md +++ b/docs/libcurl/opts/CURLOPT_PROXYAUTH.md @@ -11,7 +11,7 @@ See-also: - CURLOPT_PROXYTYPE (3) - CURLOPT_PROXYUSERPWD (3) Protocol: - - * + - All --- # NAME @@ -43,10 +43,6 @@ CURLOPT_HTTPAUTH(3) man page. CURLAUTH_BASIC -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXYHEADER.md b/docs/libcurl/opts/CURLOPT_PROXYHEADER.md index 4f555925d54..8fbb964c338 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYHEADER.md +++ b/docs/libcurl/opts/CURLOPT_PROXYHEADER.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_HEADEROPT (3) - CURLOPT_HTTPHEADER (3) Protocol: - - * + - All --- # NAME @@ -44,10 +44,6 @@ Pass a NULL to this to reset back to no custom headers. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md index 7b2535f091b..f108bbf93eb 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_PROXYAUTH (3) - CURLOPT_PROXYUSERNAME (3) Protocol: - - * + - All --- # NAME @@ -40,10 +40,6 @@ option. blank -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXYPORT.md b/docs/libcurl/opts/CURLOPT_PROXYPORT.md index 8f47c30e8a6..2a5b796af2d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYPORT.md +++ b/docs/libcurl/opts/CURLOPT_PROXYPORT.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYTYPE (3) Protocol: - - * + - All --- # NAME @@ -40,10 +40,6 @@ than 65535. 0, not specified which makes it use the default port -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXYTYPE.md index c9d98c2256d..50af1d81907 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXYTYPE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYPORT (3) Protocol: - - * + - All --- # NAME @@ -70,10 +70,6 @@ the CURLOPT_PROXY(3) string. CURLPROXY_HTTP -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md index 02fa29305f7..a2b7b2aec38 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_PROXYPASSWORD (3) - CURLOPT_USERNAME (3) Protocol: - - * + - All --- # NAME @@ -43,10 +43,6 @@ option. blank -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md index 530eec3be9e..315761647c1 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_PROXYTYPE (3) - CURLOPT_PROXYUSERNAME (3) Protocol: - - * + - All --- # NAME @@ -42,10 +42,6 @@ option. This is NULL by default. -# PROTOCOLS - -Used with all protocols that can use a proxy - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md index 19214bd7e03..82b13617073 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md @@ -61,10 +61,6 @@ The default value for this can be figured out with CURLINFO_CAINFO(3). Built-in system specific -# PROTOCOLS - -Used with HTTPS proxy - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md index 02d282abf7c..dff93aab4d1 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.md @@ -57,10 +57,6 @@ This option overrides CURLOPT_PROXY_CAINFO(3). NULL -# PROTOCOLS - -Used with HTTPS proxy - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md index 526f2d26104..4a4f46d1470 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md @@ -47,10 +47,6 @@ The default value for this can be figured out with CURLINFO_CAPATH(3). NULL -# PROTOCOLS - -Everything used over an HTTPS proxy - # EXAMPLE ~~~c @@ -73,8 +69,7 @@ int main(void) Added in 7.52.0 -This option is supported by the OpenSSL, GnuTLS, and mbedTLS (since 7.56.0) -backends. +mbedTLS support added in 7.56.0. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md index ffe28f9a776..498259756b0 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md @@ -58,10 +58,6 @@ option. NULL -# PROTOCOLS - -Used with HTTPS proxy. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md index 1ec2b02eb22..33714c9e168 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md @@ -55,10 +55,6 @@ option. NULL -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md index 38728e51acb..d8bcf09e63a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.md @@ -59,10 +59,6 @@ instead expects a filename as input. NULL -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md index 351af0134b7..cb1e4beca48 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md @@ -46,10 +46,6 @@ option. NULL -# PROTOCOLS - -Used with HTTPS proxy - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md index 61594d146e4..a1a74258e34 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md @@ -53,10 +53,6 @@ option. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md index 157c62310e4..d1b9dd95bc1 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_PROXYTYPE (3) - CURLOPT_SERVICE_NAME (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ option. See above -# PROTOCOLS - -All network protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md index f3db4b9764f..4b510b26475 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md @@ -55,10 +55,6 @@ option. NULL -# PROTOCOLS - -Used with HTTPS proxy - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md index b9a8705e999..f14b73a19af 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md @@ -48,10 +48,6 @@ option. "PEM" -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md index a1534d15fc3..05a41b9e7d0 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.md @@ -49,10 +49,6 @@ expects a filename as input. NULL -# PROTOCOLS - -Used with HTTPS proxy - # EXAMPLE ~~~c @@ -82,8 +78,7 @@ int main(void) # AVAILABILITY -Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport and -Schannel backends. +Added in 7.71.0. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md index 2cbb24e728a..e954969ea49 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md @@ -49,10 +49,6 @@ option. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md index 7132cecf898..16ddd035f50 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md @@ -38,10 +38,6 @@ the format of your private key. Supported formats are "PEM", "DER" and "ENG". The application does not have to keep the string around after setting this option. -# PROTOCOLS - -Used with HTTPS proxy - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md index fe5d67d00d4..7f35544423d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.md @@ -42,10 +42,6 @@ setting this. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md index 91968e750db..9fb935f2434 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md @@ -98,10 +98,6 @@ inconsistent depending on the TLS library. CURL_SSLVERSION_DEFAULT -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md index b33136d9a8d..ce6a778b9e9 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md @@ -67,10 +67,6 @@ option. NULL, use internal default -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md index 0734c14d332..541b13cb8f4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.md @@ -91,10 +91,6 @@ could be a privacy violation and unexpected. 0 -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md index f183697f924..01cbdb913dc 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md @@ -64,10 +64,6 @@ of the proxy certificate. 2 -# PROTOCOLS - -All protocols when used over an HTTPS proxy. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md index 56527ce5ac1..86afeb72bfa 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md @@ -66,10 +66,6 @@ the correct end-point. 1 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md index a9ec3d1dd7e..90b6166efe5 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md @@ -53,10 +53,6 @@ option. NULL, use internal default -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md index df8d25a24c5..e45f69e9bf4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md @@ -43,10 +43,6 @@ option. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c @@ -68,7 +64,7 @@ int main(void) # AVAILABILITY -Added in 7.52.0, with the OpenSSL and GnuTLS backends only +Added in 7.52.0. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md index ec5773b969a..a10d78c5e12 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md @@ -50,10 +50,6 @@ option. blank -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md index edc70942f2b..8d7b221b89e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md @@ -43,10 +43,6 @@ option. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c @@ -68,7 +64,7 @@ int main(void) # AVAILABILITY -Added in 7.52.0, with the OpenSSL and GnuTLS backends only. +Added in 7.52.0. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md index b9f39be322e..5daf5df372d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md +++ b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_PROXY (3) - CURLOPT_TRANSFERTEXT (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ doing FTP via a proxy. Beware that not all proxies support this feature. 0, disabled -# PROTOCOLS - -FTP over proxy - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_PUT.md b/docs/libcurl/opts/CURLOPT_PUT.md index c0cfb3802ab..6eb3a6bb18f 100644 --- a/docs/libcurl/opts/CURLOPT_PUT.md +++ b/docs/libcurl/opts/CURLOPT_PUT.md @@ -37,10 +37,6 @@ This option is **deprecated** since version 7.12.1. Use CURLOPT_UPLOAD(3). 0, disabled -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md index 35681bfd95d..3e0d64ced88 100644 --- a/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md +++ b/docs/libcurl/opts/CURLOPT_QUICK_EXIT.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_FAILONERROR (3) - CURLOPT_RESOLVE (3) Protocol: - - * + - All --- # NAME @@ -37,10 +37,6 @@ possible (though short-lived) leak of associated resources. 0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.md b/docs/libcurl/opts/CURLOPT_QUOTE.md index 098428a669d..4bdc1913c4f 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.md +++ b/docs/libcurl/opts/CURLOPT_QUOTE.md @@ -127,10 +127,6 @@ See ln. NULL -# PROTOCOLS - -SFTP and FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md index f2a7e8d2109..6840fbc29fd 100644 --- a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md +++ b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.md @@ -38,10 +38,6 @@ option. NULL, not used -# PROTOCOLS - -All - # EXAMPLE ~~~c @@ -60,8 +56,7 @@ int main(void) # AVAILABILITY -If built with TLS enabled. Only the OpenSSL backend uses this, and only with -OpenSSL versions before 1.1.0. +Only with OpenSSL versions before 1.1.0. This option was deprecated in 7.84.0. diff --git a/docs/libcurl/opts/CURLOPT_RANGE.md b/docs/libcurl/opts/CURLOPT_RANGE.md index cbf77efcd84..0a8343db3af 100644 --- a/docs/libcurl/opts/CURLOPT_RANGE.md +++ b/docs/libcurl/opts/CURLOPT_RANGE.md @@ -58,10 +58,6 @@ option. NULL -# PROTOCOLS - -HTTP, FTP, FILE, RTSP and SFTP. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_READDATA.md b/docs/libcurl/opts/CURLOPT_READDATA.md index f08cc692856..20eb3c6d40b 100644 --- a/docs/libcurl/opts/CURLOPT_READDATA.md +++ b/docs/libcurl/opts/CURLOPT_READDATA.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_WRITEDATA (3) - CURLOPT_WRITEFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -42,10 +42,6 @@ might experience crashes. By default, this is a FILE * to stdin. -# PROTOCOLS - -This is used for all protocols when sending data. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.md b/docs/libcurl/opts/CURLOPT_READFUNCTION.md index cc794662599..06d2e638afc 100644 --- a/docs/libcurl/opts/CURLOPT_READFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.md @@ -12,7 +12,7 @@ See-also: - CURLOPT_UPLOAD_BUFFERSIZE (3) - CURLOPT_WRITEFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -74,10 +74,6 @@ and it allows for better error checking. The default internal read callback is fread(). -# PROTOCOLS - -This is used for all protocols when doing uploads. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md index 1addcf6378a..df6cb716355 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md @@ -83,10 +83,6 @@ HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 SMB and SMBS. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md index e39f4bce3e0..69c2e7c9f85 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md @@ -62,10 +62,6 @@ HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 SMB and SMBS. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_REFERER.md b/docs/libcurl/opts/CURLOPT_REFERER.md index 92f0c3693bb..f5ac9a8b341 100644 --- a/docs/libcurl/opts/CURLOPT_REFERER.md +++ b/docs/libcurl/opts/CURLOPT_REFERER.md @@ -38,10 +38,6 @@ option. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md index 43ee37f30bd..582b88fa1d7 100644 --- a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md +++ b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md @@ -37,10 +37,6 @@ other safe guards. That includes white space and control characters. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.md b/docs/libcurl/opts/CURLOPT_RESOLVE.md index 4c72750cb62..800e3a82dba 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVE.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_DNS_CACHE_TIMEOUT (3) - CURLOPT_IPRESOLVE (3) Protocol: - - * + - All --- # NAME @@ -73,10 +73,6 @@ number must exactly match what was added previously. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md index a90bddb73df..f1fdc4e980c 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_PREREQFUNCTION (3) - CURLOPT_RESOLVER_START_FUNCTION (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ CURLOPT_RESOLVER_START_FUNCTION(3). NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md index 01e34bd7051..3ff66168d65 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_PREREQFUNCTION (3) - CURLOPT_RESOLVER_START_DATA (3) Protocol: - - * + - All --- # NAME @@ -52,10 +52,6 @@ resolve to fail. NULL (No callback) -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM.md b/docs/libcurl/opts/CURLOPT_RESUME_FROM.md index ff296b23923..34f84e3b876 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM.md +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_RANGE (3) - CURLOPT_RESUME_FROM_LARGE (3) Protocol: - - * + - All --- # NAME @@ -43,10 +43,6 @@ CURLOPT_RESUME_FROM_LARGE(3) instead. 0, not used -# PROTOCOLS - -HTTP, FTP, SFTP, FILE - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md index f91a94e0502..7326a3df51f 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_RANGE (3) - CURLOPT_RESUME_FROM (3) Protocol: - - * + - All --- # NAME @@ -41,10 +41,6 @@ file to the remote target file. 0, not used -# PROTOCOLS - -HTTP, FTP, SFTP, FILE - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md index 60594d88cab..a02cd85ab38 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.md @@ -35,10 +35,6 @@ increments from this new number henceforth. 0 -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md index ca41a59a9cc..1a2603486d3 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.md @@ -111,10 +111,6 @@ application a chance to run. # DEFAULT -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md index 598a3cbbd2c..096132bb3fb 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.md @@ -34,10 +34,6 @@ unimplemented. 0 -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md index 952042136b2..39fd1621eb2 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md @@ -39,10 +39,6 @@ option. NULL -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md index af9af155139..ecd2eff2a44 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md @@ -43,10 +43,6 @@ option. "*" -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md index 5ae09410fd1..da98ee900be 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.md @@ -38,10 +38,6 @@ option. NULL -# PROTOCOLS - -RTSP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md index 98b8ae3bd5d..f7012f27e9b 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md +++ b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md @@ -43,10 +43,6 @@ access to, or a shared mailbox for example. blank -# PROTOCOLS - -IMAP, LDAP, POP3 and SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SASL_IR.md b/docs/libcurl/opts/CURLOPT_SASL_IR.md index e99de653a98..ebc4c4aff01 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_IR.md +++ b/docs/libcurl/opts/CURLOPT_SASL_IR.md @@ -46,10 +46,6 @@ SASL-IR CAPABILITY. 0 -# PROTOCOLS - -IMAP, POP3 and SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.md b/docs/libcurl/opts/CURLOPT_SEEKDATA.md index 05c49d579df..e660cb6a3a4 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKDATA.md +++ b/docs/libcurl/opts/CURLOPT_SEEKDATA.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_SEEKFUNCTION (3) - CURLOPT_STDERR (3) Protocol: - - * + - All --- # NAME @@ -34,10 +34,6 @@ CURLOPT_SEEKFUNCTION(3) option, this is the pointer you get as input. If you do not set this, NULL is passed to the callback. -# PROTOCOLS - -HTTP, FTP, SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md index c8c8bbffdda..ac37cc59697 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_SEEKDATA (3) - CURLOPT_STDERR (3) Protocol: - - * + - All --- # NAME @@ -65,10 +65,6 @@ many systems! By default, this is NULL and unused. -# PROTOCOLS - -HTTP, FTP, SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md index a90506d2e90..6c7d74fc8fc 100644 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT.md @@ -46,10 +46,6 @@ This option was formerly known as CURLOPT_FTP_RESPONSE_TIMEOUT. None -# PROTOCOLS - -FTP, IMAP, POP3, SMTP, and SSH - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md index 27f95ac174c..87e2820caa0 100644 --- a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md @@ -48,10 +48,6 @@ This is the millisecond version of CURLOPT_SERVER_RESPONSE_TIMEOUT(3). None -# PROTOCOLS - -FTP, IMAP, POP3, SMTP, and SSH - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md index 769da3fef48..8276253b5f6 100644 --- a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md +++ b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.md @@ -9,7 +9,12 @@ See-also: - CURLOPT_PROXYTYPE (3) - CURLOPT_PROXY_SERVICE_NAME (3) Protocol: - - * + - HTTP + - FTP + - IMAP + - POP3 + - SMTP + - LDAP --- # NAME @@ -38,10 +43,6 @@ option. See above -# PROTOCOLS - -HTTP, FTP, IMAP, LDAP, POP3 and SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SHARE.md b/docs/libcurl/opts/CURLOPT_SHARE.md index 5256a4ebae9..308d57af3a0 100644 --- a/docs/libcurl/opts/CURLOPT_SHARE.md +++ b/docs/libcurl/opts/CURLOPT_SHARE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_COOKIE (3) - CURLSHOPT_SHARE (3) Protocol: - - * + - All --- # NAME @@ -47,10 +47,6 @@ Set this option to NULL again to stop using that share object. NULL -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md index cc09a80aa0b..6780737459e 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_OPENSOCKETFUNCTION (3) - CURLOPT_SOCKOPTFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -32,10 +32,6 @@ argument in the sockopt callback set with CURLOPT_SOCKOPTFUNCTION(3). The default value of this parameter is NULL. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md index 919161f0849..e35934be195 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_SEEKFUNCTION (3) - CURLOPT_SOCKOPTDATA (3) Protocol: - - * + - All --- # NAME @@ -74,10 +74,6 @@ not attempt to connect (again). By default, this callback is NULL and unused. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md index 07aec2b443c..937da2c022e 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYTYPE (3) Protocol: - - * + - All --- # NAME @@ -36,10 +36,6 @@ password with the CURLOPT_PROXYUSERPWD(3) option. CURLAUTH_BASIC|CURLAUTH_GSSAPI -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md index 028040d73a2..b46713017b3 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_PROXY (3) - CURLOPT_SOCKS5_GSSAPI_SERVICE (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ negotiation. ? -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md index 67ede5a6aac..86879589bf2 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_PROXY (3) - CURLOPT_PROXYTYPE (3) Protocol: - - * + - All --- # NAME @@ -39,10 +39,6 @@ option. See above -# PROTOCOLS - -All network protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md index 669bd70a167..e83d0a08807 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md +++ b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.md @@ -40,10 +40,6 @@ authentication. CURLSSH_AUTH_ANY (all available) -# PROTOCOLS - -SFTP and SCP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md index 26b0ab2a904..884ef28e26a 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md @@ -35,10 +35,6 @@ may or may not do it. 0, disabled -# PROTOCOLS - -All SSH based protocols: SCP, SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md index 1cf56b33dd4..858c59e5e59 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md @@ -32,10 +32,6 @@ the callback set with CURLOPT_SSH_HOSTKEYFUNCTION(3). NULL -# PROTOCOLS - -SCP and SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md index d0d909248f8..2c12fb87747 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md @@ -58,10 +58,6 @@ the host key is rejected, the connection is canceled. NULL -# PROTOCOLS - -SCP and SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md index 6dcf99e11a6..fd045f9f3d5 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md @@ -43,10 +43,6 @@ option. NULL -# PROTOCOLS - -SCP and SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md index 3cd506a246f..15e12d3f651 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md @@ -36,10 +36,6 @@ does not match the hash the remote host provides. NULL -# PROTOCOLS - -SCP and SFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md index fda68d5f094..8e35a931575 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md @@ -33,10 +33,6 @@ callback set with CURLOPT_SSH_KEYFUNCTION(3). NULL -# PROTOCOLS - -SFTP and SCP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md index b8ed95e96d1..ce71cf419b7 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md @@ -109,10 +109,6 @@ up from scratch again. NULL -# PROTOCOLS - -SFTP and SCP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md index 8905ccccc03..86828c0a682 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md @@ -40,10 +40,6 @@ option. NULL -# PROTOCOLS - -SFTP and SCP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md index f516501e8be..fc24eb00be3 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md +++ b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.md @@ -47,10 +47,6 @@ option. As explained above -# PROTOCOLS - -SFTP and SCP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md index 62983eb23a6..0c27b7edfc7 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md +++ b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.md @@ -43,10 +43,6 @@ option. NULL -# PROTOCOLS - -SFTP and SCP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.md b/docs/libcurl/opts/CURLOPT_SSLCERT.md index 81616988204..f7d3b28f1e9 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.md @@ -65,10 +65,6 @@ option. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md index 5ec33af1d9f..debbcd1608f 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md @@ -47,10 +47,6 @@ option. "PEM" -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md index 5e4b0c956ce..80a50c72ff7 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.md @@ -49,10 +49,6 @@ expects a filename as input. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.md b/docs/libcurl/opts/CURLOPT_SSLENGINE.md index 1ec52580784..44cd44cbe84 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE.md +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE.md @@ -38,10 +38,6 @@ option. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c @@ -60,7 +56,7 @@ int main(void) # AVAILABILITY -Only if the SSL backend is OpenSSL built with engine support. +Only if OpenSSL is built with engine support. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md index 05f22d8962c..963b9c1afb5 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.md @@ -36,10 +36,6 @@ This option has no effect unless set after CURLOPT_SSLENGINE(3). None -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.md b/docs/libcurl/opts/CURLOPT_SSLKEY.md index 7ec6aa9cddb..f87e8eb6755 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.md @@ -46,10 +46,6 @@ option. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md index 453d8908dc8..182f7774870 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md @@ -45,10 +45,6 @@ option. "PEM" -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md index 6aabd3fa33e..4ef3b07514b 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.md @@ -43,10 +43,6 @@ filename as input. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.md b/docs/libcurl/opts/CURLOPT_SSLVERSION.md index 073fc744719..c483b826806 100644 --- a/docs/libcurl/opts/CURLOPT_SSLVERSION.md +++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.md @@ -111,10 +111,6 @@ inconsistent depending on the TLS library. CURL_SSLVERSION_DEFAULT -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md index 0143c8dfb0c..3bf09d8dbf0 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md @@ -69,10 +69,6 @@ option. NULL, use internal default -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md index be7307f8a7e..5e74f5a36df 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.md @@ -38,10 +38,6 @@ parameter. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c @@ -120,7 +116,7 @@ int main(void) # AVAILABILITY Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL, in 7.54.0 for mbedTLS, -in 7.83.0 in BearSSL. Other SSL backends are not supported. +in 7.83.0 in BearSSL. # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md index 76e2403ff84..64732c1a74b 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.md @@ -82,10 +82,6 @@ completed. NULL -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c @@ -163,10 +159,8 @@ int main(void) # AVAILABILITY -libcurl built with OpenSSL (added in 7.11.0), wolfSSL (added in 7.42.0), mbedTLS -(added in 7.54.0) or BearSSL (added in 7.83.0) - -No other SSL backend is supported. +OpenSSL (added in 7.11.0), wolfSSL (added in 7.42.0), mbedTLS (added in +7.54.0) or BearSSL (added in 7.83.0) # RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md index 17b2e846a21..e68ac37cdf2 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md +++ b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md @@ -37,10 +37,6 @@ the SSL backend libcurl is built to use supports it). "", embedded in SSL backend -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md index 49796496d88..f53a6fc8d8d 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.md @@ -35,10 +35,6 @@ is built to use supports it), which can be used to negotiate http2. 1, enabled -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md index a0a68c6af3d..26c79f33d2b 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.md @@ -37,10 +37,6 @@ is built to use supports it), which can be used to negotiate http2. 1, enabled -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md index 106b6efc07a..7758f0d9011 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md +++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md @@ -37,10 +37,6 @@ when performing a full handshake. 0 -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md index 4e33aac1ed5..ddf278e6f9c 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.md @@ -89,10 +89,6 @@ could be a privacy violation and unexpected. 0 -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md index 63eab608488..364eb04091e 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md +++ b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.md @@ -40,10 +40,6 @@ wild that may require you to disable this in order for you to succeed. 1 -# PROTOCOLS - -All TLS-based - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md index 4cee06f25ab..f432fecbd16 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md @@ -86,10 +86,6 @@ may be inaccessible if SNI is not sent. 2 -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md index 53c81c79aa5..214da41cf38 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md @@ -72,10 +72,6 @@ malicious servers. 1 - enabled -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md index dc051ef4af5..7f6b1a0191c 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.md @@ -41,10 +41,6 @@ extension, the verification fails. 0 -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_STDERR.md b/docs/libcurl/opts/CURLOPT_STDERR.md index 58f6c39fa70..f38aba25eee 100644 --- a/docs/libcurl/opts/CURLOPT_STDERR.md +++ b/docs/libcurl/opts/CURLOPT_STDERR.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_NOPROGRESS (3) - CURLOPT_VERBOSE (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ application. A work-around is to instead use CURLOPT_DEBUGFUNCTION(3). stderr -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md index 4ad479c94ba..7342f3bcf1b 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.md @@ -47,10 +47,6 @@ option to have an actual effect. NULL -# PROTOCOLS - -HTTP/2 - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md index dddd89c3872..8d109fb19bc 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.md @@ -50,10 +50,6 @@ option to have an actual effect. NULL -# PROTOCOLS - -HTTP/2 - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md index 27684a6c1fa..fdd2a184035 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md +++ b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.md @@ -50,10 +50,6 @@ streams). If nothing is set, the HTTP/2 protocol itself uses its own default which is 16. -# PROTOCOLS - -HTTP/2 - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md index 2c6bdaad31d..b6357b5035c 100644 --- a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md +++ b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_HTTPPROXYTUNNEL (3) - CURLOPT_PROXY (3) Protocol: - - * + - All --- # NAME @@ -70,10 +70,6 @@ Content-Type: application/json 0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md index bf85e1ffcf8..42b44a5674d 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md +++ b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - CURLOPT_SSL_FALSESTART (3) Protocol: - - * + - All --- # NAME @@ -37,10 +37,6 @@ Fast Open is also known to be problematic on or across certain networks. 0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md index 1ad0be145dd..e9e80ac6a5d 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_TCP_KEEPIDLE (3) - CURLOPT_TCP_KEEPINTVL (3) Protocol: - - * + - All --- # NAME @@ -37,10 +37,6 @@ disable keepalive probes 0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md index 3b0f48facaf..5f8841747d8 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TCP_KEEPINTVL (3) Protocol: - - * + - All --- # NAME @@ -36,10 +36,6 @@ this amount. 60 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md index 016f0b97c18..405b6ec8287 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TCP_KEEPIDLE (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ this amount. 60 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md index 84eb871e754..a5b15abbf1c 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_SOCKOPTFUNCTION (3) - CURLOPT_TCP_KEEPALIVE (3) Protocol: - - * + - All --- # NAME @@ -45,10 +45,6 @@ overdone. 1 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md index 138c8a586e1..9e45df837a7 100644 --- a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md @@ -35,10 +35,6 @@ standard for details. NULL -# PROTOCOLS - -TELNET - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md index 810548d66b5..1b5c9ae6fc8 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.md @@ -35,10 +35,6 @@ is used. 512 -# PROTOCOLS - -TFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md index 93a0cbc27be..953702696a8 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md @@ -35,10 +35,6 @@ CURLOPT_TFTP_BLKSIZE(3) is ignored. 0 -# PROTOCOLS - -TFTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TIMECONDITION.md b/docs/libcurl/opts/CURLOPT_TIMECONDITION.md index 3c9d332153a..b4bdb4fa2e4 100644 --- a/docs/libcurl/opts/CURLOPT_TIMECONDITION.md +++ b/docs/libcurl/opts/CURLOPT_TIMECONDITION.md @@ -39,10 +39,6 @@ option can be used after a transfer to learn if a zero-byte successful CURL_TIMECOND_NONE (0) -# PROTOCOLS - -HTTP, FTP, RTSP, and FILE - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.md b/docs/libcurl/opts/CURLOPT_TIMEOUT.md index 9364c8e3541..c35bb4076b5 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT.md +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TIMEOUT_MS (3) Protocol: - - * + - All --- # NAME @@ -61,10 +61,6 @@ signals to be used unless CURLOPT_NOSIGNAL(3) is set. Default timeout is 0 (zero) which means it never times out during transfer. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md index d01323015bd..8f13480d38f 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_TCP_KEEPALIVE (3) - CURLOPT_TIMEOUT (3) Protocol: - - * + - All --- # NAME @@ -36,10 +36,6 @@ See CURLOPT_TIMEOUT(3) for details. Default timeout is 0 (zero) which means it never times out during transfer. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md index 03f7951ad5a..5558e6d1776 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md @@ -37,10 +37,6 @@ instead. 0 -# PROTOCOLS - -HTTP, FTP, RTSP, and FILE - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md index b12dc4eb0d0..cd16c7589c5 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md @@ -39,10 +39,6 @@ to be used to set dates beyond the year 2038. 0 -# PROTOCOLS - -HTTP, FTP, RTSP, and FILE - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md index 5a65b433701..7794972436d 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md @@ -54,10 +54,6 @@ option. NULL, use internal default -# PROTOCOLS - -All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md index 8871526c237..6a9a8382959 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md @@ -43,10 +43,6 @@ This feature relies in TLS SRP which does not work with TLS 1.3. NULL -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md index 111b82d7cc7..0611334e494 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md @@ -48,10 +48,6 @@ TLS SRP does not work with TLS 1.3. blank -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md index 80ea1a2a029..c69ac816705 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md @@ -42,10 +42,6 @@ This feature relies in TLS SRP which does not work with TLS 1.3. NULL -# PROTOCOLS - -All TLS-based protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TRAILERDATA.md b/docs/libcurl/opts/CURLOPT_TRAILERDATA.md index 380a57913df..2eceb16e7a5 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERDATA.md +++ b/docs/libcurl/opts/CURLOPT_TRAILERDATA.md @@ -31,10 +31,6 @@ Data pointer to be passed to the HTTP trailer callback function. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md index ebbb70bde5e..a6cd7fa5f19 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.md @@ -59,10 +59,6 @@ without any interruptions. NULL -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c static int trailer_cb(struct curl_slist **tr, void *data) diff --git a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md index 7a33a91f89c..9506c96ed1f 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md +++ b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - CURLOPT_CRLF (3) Protocol: - - * + - All --- # NAME @@ -38,10 +38,6 @@ simply sets the mode to ASCII and performs a standard transfer. 0, disabled -# PROTOCOLS - -FTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md index 7c5482d8908..6494d45d477 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md +++ b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md @@ -43,10 +43,6 @@ by both HTTP clients and HTTP servers. 0 -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md index 40fd80a182a..fff993753a3 100644 --- a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md +++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_OPENSOCKETFUNCTION (3) - unix (7) Protocol: - - * + - All --- # NAME @@ -49,11 +49,6 @@ option. Default is NULL, meaning that no Unix domain sockets are used. -# PROTOCOLS - -All protocols except for FILE and FTP are supported in theory. HTTP, IMAP, -POP3 and SMTP should in particular work (including their SSL/TLS variants). - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md index d6edd0714e0..270ebd6546f 100644 --- a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md +++ b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md @@ -52,10 +52,6 @@ again and again as the following hosts can keep redirecting to new hosts. 0 -# PROTOCOLS - -HTTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md index 6692920b754..4813904d3a7 100644 --- a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md +++ b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md @@ -7,7 +7,7 @@ Source: libcurl See-also: - CURLOPT_TCP_KEEPALIVE (3) Protocol: - - * + - All --- # NAME @@ -41,10 +41,6 @@ is called, an HTTP/2 PING frame is sent on the connection. CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds) -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD.md b/docs/libcurl/opts/CURLOPT_UPLOAD.md index 4fdd68a6380..de64ada850e 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD.md +++ b/docs/libcurl/opts/CURLOPT_UPLOAD.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_PUT (3) - CURLOPT_READFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -45,10 +45,6 @@ CURLOPT_INFILESIZE(3) or CURLOPT_INFILESIZE_LARGE(3). 0, default is download -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md index 5c02c283bfc..e1cbf244ad7 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md +++ b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_READFUNCTION (3) - CURLOPT_TCP_NODELAY (3) Protocol: - - * + - All --- # NAME @@ -49,10 +49,6 @@ transfer as that may lead to unintended consequences. 65536 bytes -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_URL.md b/docs/libcurl/opts/CURLOPT_URL.md index ac663c9a053..2522d96bacf 100644 --- a/docs/libcurl/opts/CURLOPT_URL.md +++ b/docs/libcurl/opts/CURLOPT_URL.md @@ -15,7 +15,7 @@ See-also: - curl_url_get (3) - curl_url_set (3) Protocol: - - * + - All --- # NAME @@ -115,10 +115,6 @@ User provided URLs can also be made to point to sites that redirect further on (possibly to other protocols too). Consider your CURLOPT_FOLLOWLOCATION(3) and CURLOPT_REDIR_PROTOCOLS(3) settings. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.md b/docs/libcurl/opts/CURLOPT_USERAGENT.md index e637e6a4993..757f3edbdb1 100644 --- a/docs/libcurl/opts/CURLOPT_USERAGENT.md +++ b/docs/libcurl/opts/CURLOPT_USERAGENT.md @@ -38,10 +38,6 @@ option. NULL, no User-Agent: header is used by default. -# PROTOCOLS - -HTTP, HTTPS - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_USERNAME.md b/docs/libcurl/opts/CURLOPT_USERNAME.md index 054c250dce4..34d0a67930f 100644 --- a/docs/libcurl/opts/CURLOPT_USERNAME.md +++ b/docs/libcurl/opts/CURLOPT_USERNAME.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_PROXYAUTH (3) - CURLOPT_USERPWD (3) Protocol: - - * + - All --- # NAME @@ -60,10 +60,6 @@ option. blank -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.md b/docs/libcurl/opts/CURLOPT_USERPWD.md index 2537ab23fc3..726ec3e7201 100644 --- a/docs/libcurl/opts/CURLOPT_USERPWD.md +++ b/docs/libcurl/opts/CURLOPT_USERPWD.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_PROXYUSERPWD (3) - CURLOPT_USERNAME (3) Protocol: - - * + - All --- # NAME @@ -66,10 +66,6 @@ option. NULL -# PROTOCOLS - -Most - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_USE_SSL.md b/docs/libcurl/opts/CURLOPT_USE_SSL.md index 70fade3c3ce..acb99e080fd 100644 --- a/docs/libcurl/opts/CURLOPT_USE_SSL.md +++ b/docs/libcurl/opts/CURLOPT_USE_SSL.md @@ -58,10 +58,6 @@ Require SSL for all communication or fail with *CURLE_USE_SSL_FAILED*. CURLUSESSL_NONE -# PROTOCOLS - -FTP, SMTP, POP3, IMAP, LDAP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.md b/docs/libcurl/opts/CURLOPT_VERBOSE.md index 492a1108ee4..a144d29f9b1 100644 --- a/docs/libcurl/opts/CURLOPT_VERBOSE.md +++ b/docs/libcurl/opts/CURLOPT_VERBOSE.md @@ -10,7 +10,7 @@ See-also: - CURLOPT_STDERR (3) - curl_global_trace (3) Protocol: - - * + - All --- # NAME @@ -42,10 +42,6 @@ CURLOPT_DEBUGFUNCTION(3). 0, meaning disabled. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md index 1dbcf68ff3f..bfcc82fc770 100644 --- a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md +++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.md @@ -76,10 +76,6 @@ Using the rules above, a filename pattern can be constructed: ftp://example.com/some/path/[a-z[:upper:]\\].jpg -# PROTOCOLS - -This feature is only supported for FTP download. - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.md b/docs/libcurl/opts/CURLOPT_WRITEDATA.md index c42ac401c94..66744abbef2 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.md +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_READDATA (3) - CURLOPT_WRITEFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -43,10 +43,6 @@ crashes. By default, this is a FILE * to stdout. -# PROTOCOLS - -Used for all protocols. - # EXAMPLE A common technique is to use the write callback to store the incoming data diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md index 448002353dc..61a02c4c5e2 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_READFUNCTION (3) - CURLOPT_WRITEDATA (3) Protocol: - - * + - All --- # NAME @@ -74,10 +74,6 @@ do that. libcurl uses 'fwrite' as a callback by default. -# PROTOCOLS - -For all protocols - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md index 1c3b8bcb33d..23db0a47be4 100644 --- a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md +++ b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.md @@ -47,10 +47,6 @@ application. 0 -# PROTOCOLS - -WebSocket - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.md b/docs/libcurl/opts/CURLOPT_XFERINFODATA.md index 09248e15bcd..126dc11a469 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFODATA.md +++ b/docs/libcurl/opts/CURLOPT_XFERINFODATA.md @@ -9,7 +9,7 @@ See-also: - CURLOPT_VERBOSE (3) - CURLOPT_XFERINFOFUNCTION (3) Protocol: - - * + - All --- # NAME @@ -35,10 +35,6 @@ This is an alias for CURLOPT_PROGRESSDATA(3). The default value of this parameter is NULL. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md index f94971f520a..7fcd0e06d81 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.md @@ -8,7 +8,7 @@ See-also: - CURLOPT_NOPROGRESS (3) - CURLOPT_XFERINFODATA (3) Protocol: - - * + - All --- # NAME @@ -73,10 +73,6 @@ get called. By default, libcurl has an internal progress meter. That is rarely wanted by users. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md index 396948b49e1..8ae9901d6ab 100644 --- a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md @@ -43,10 +43,6 @@ option. NULL -# PROTOCOLS - -HTTP, IMAP, LDAP, POP3 and SMTP - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md index fbfa2230796..46e210ad5fc 100644 --- a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md +++ b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.md @@ -10,7 +10,7 @@ See-also: - curl_share_init (3) - curl_share_setopt (3) Protocol: - - * + - All --- # NAME @@ -48,10 +48,6 @@ sure that the callback uses a different lock for each kind of data. *clientp* is the private pointer you set with CURLSHOPT_USERDATA(3). This pointer is not used by libcurl itself. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLSHOPT_SHARE.md b/docs/libcurl/opts/CURLSHOPT_SHARE.md index d2cfef1743f..376d53cda82 100644 --- a/docs/libcurl/opts/CURLSHOPT_SHARE.md +++ b/docs/libcurl/opts/CURLSHOPT_SHARE.md @@ -10,7 +10,7 @@ See-also: - curl_share_init (3) - curl_share_setopt (3) Protocol: - - * + - All --- # NAME @@ -91,10 +91,6 @@ It is not supported to share the HSTS between multiple concurrent threads. Added in 7.88.0 -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md index 6853b676155..ae8ecb7796c 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md +++ b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.md @@ -10,7 +10,7 @@ See-also: - curl_share_init (3) - curl_share_setopt (3) Protocol: - - * + - All --- # NAME @@ -44,10 +44,6 @@ sure that the callback uses a different lock for each kind of data. *clientp* is the private pointer you set with CURLSHOPT_USERDATA(3). This pointer is not used by libcurl itself. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md index 898e40bb08d..69ee517c786 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNSHARE.md +++ b/docs/libcurl/opts/CURLSHOPT_UNSHARE.md @@ -10,7 +10,7 @@ See-also: - curl_share_init (3) - curl_share_setopt (3) Protocol: - - * + - All --- # NAME @@ -58,10 +58,6 @@ The connection cache is no longer shared. The Public Suffix List is no longer shared. -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/docs/libcurl/opts/CURLSHOPT_USERDATA.md b/docs/libcurl/opts/CURLSHOPT_USERDATA.md index 3969e9e5a17..9cd042ec509 100644 --- a/docs/libcurl/opts/CURLSHOPT_USERDATA.md +++ b/docs/libcurl/opts/CURLSHOPT_USERDATA.md @@ -10,7 +10,7 @@ See-also: - curl_share_init (3) - curl_share_setopt (3) Protocol: - - * + - All --- # NAME @@ -31,10 +31,6 @@ The *clientp* parameter is held verbatim by libcurl and is passed on as the *clientp* argument to the callbacks set with CURLSHOPT_LOCKFUNC(3) and CURLSHOPT_UNLOCKFUNC(3). -# PROTOCOLS - -All - # EXAMPLE ~~~c diff --git a/scripts/cd2nroff b/scripts/cd2nroff index 6356c9de9cb..b0e702a479d 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -96,6 +96,47 @@ sub outseealso { return @o; } +sub outprotocols { + my (@p) = @_; + my $comma = 0; + my @o; + push @o, ".SH PROTOCOLS\n"; + + if($p[0] eq "TLS") { + push @o, "All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc."; + } + else { + my @s = sort @p; + for my $e (sort @s) { + push @o, sprintf "%s$e", + $comma ? (($e eq $s[-1]) ? " and " : ", "): ""; + $comma = 1; + } + } + push @o, "\n"; + return @o; +} + +sub outtls { + my (@t) = @_; + my $comma = 0; + my @o; + if($t[0] eq "All") { + push @o, "\nAll TLS backends support this option."; + } + else { + push @o, "\nThis option works only with the following TLS backends:\n"; + my @s = sort @t; + for my $e (@s) { + push @o, sprintf "%s$e", + $comma ? (($e eq $s[-1]) ? " and " : ", "): ""; + $comma = 1; + } + } + push @o, "\n"; + return @o; +} + my %knownprotos = ( 'DICT' => 1, 'FILE' => 1, @@ -127,7 +168,7 @@ my %knownprotos = ( 'WSS' => 1, 'TLS' => 1, 'TCP' => 1, - '*' => 1 + 'All' => 1 ); my %knowntls = ( @@ -375,6 +416,18 @@ sub single { my $word = $1; # if there are enclosing quotes, remove them first $word =~ s/[\"\'](.*)[\"\']\z/$1/; + + if($word eq "PROTOCOLS") { + print STDERR "$f:$line:1:WARN: PROTOCOLS section in source file\n"; + } + elsif($word eq "EXAMPLE") { + # insert the generated PROTOCOLS section before EXAMPLE + push @desc, outprotocols(@proto); + + if($proto[0] eq "TLS") { + push @desc, outtls(@tls); + } + } push @desc, ".SH $word\n"; $header = 1; } From b564a5f5d5280387a88025c5f90260017847add4 Mon Sep 17 00:00:00 2001 From: Mohammadreza Hendiani Date: Fri, 22 Mar 2024 18:00:29 +0330 Subject: [PATCH 496/509] TODO: update 13.11 with more information Closes #13173 --- docs/TODO | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/TODO b/docs/TODO index c82c78a537d..159e2e87535 100644 --- a/docs/TODO +++ b/docs/TODO @@ -892,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 From 647e86a3efe1eea7a2a456c009cfe1eb55fe48eb Mon Sep 17 00:00:00 2001 From: Matt Jolly Date: Sun, 24 Mar 2024 19:00:09 +1000 Subject: [PATCH 497/509] curl-rustls.m4: add pkg-config support to rustls detection Based on the existing openssl pkg-config detection, this commit tries to use pkg-config to find `rustls` then falls back to the current approach if that fails. We use the following logic: - if no path is provided, just use pkg-config, if it's not there we have a problem! - if a path is provided, try pkg-config + if pkg-config fails, try and find rustls directly Closes #13179 --- m4/curl-rustls.m4 | 195 +++++++++++++++++++++++++++++++--------------- 1 file changed, 131 insertions(+), 64 deletions(-) diff --git a/m4/curl-rustls.m4 b/m4/curl-rustls.m4 index 75542e4a427..7c55230ef7e 100644 --- a/m4/curl-rustls.m4 +++ b/m4/curl-rustls.m4 @@ -28,83 +28,150 @@ dnl check for rustls dnl ---------------------------------------------------- if test "x$OPT_RUSTLS" != xno; then - _cppflags=$CPPFLAGS - _ldflags=$LDFLAGS ssl_msg= - if test X"$OPT_RUSTLS" != Xno; then + dnl backup the pre-ssl variables + CLEANLDFLAGS="$LDFLAGS" + CLEANCPPFLAGS="$CPPFLAGS" - if test "$OPT_RUSTLS" = "yes"; then - OPT_RUSTLS="" - fi + case $host_os in + darwin*) + LDFLAGS="$LDFLAGS -framework Security" + ;; + *) + ;; + esac + ## NEW CODE - case $host_os in - darwin*) - LDFLAGS="$LDFLAGS -framework Security" - ;; - *) - ;; - esac - - if test -z "$OPT_RUSTLS" ; then - dnl check for lib first without setting any new path - - AC_CHECK_LIB(rustls, rustls_client_session_read, - dnl librustls found, set the variable - [ - AC_DEFINE(USE_RUSTLS, 1, [if rustls is enabled]) - AC_SUBST(USE_RUSTLS, [1]) - RUSTLS_ENABLED=1 - USE_RUSTLS="yes" - ssl_msg="rustls" - test rustls != "$DEFAULT_SSL_BACKEND" || VALID_DEFAULT_SSL_BACKEND=yes - ], [], -lpthread -ldl -lm) - fi + dnl use pkg-config unless we have been given a path + dnl even then, try pkg-config first - if test "x$USE_RUSTLS" != "xyes"; then - dnl add the path and test again - addld=-L$OPT_RUSTLS/lib$libsuff - addcflags=-I$OPT_RUSTLS/include - rustlslib=$OPT_RUSTLS/lib$libsuff + case "$OPT_RUSTLS" in + yes) + dnl --with-rustls (without path) used + PKGTEST="yes" + PREFIX_RUSTLS= + ;; + *) + dnl check the provided --with-rustls path + PKGTEST="no" + PREFIX_RUSTLS=$OPT_RUSTLS - LDFLAGS="$LDFLAGS $addld" - if test "$addcflags" != "-I/usr/include"; then - CPPFLAGS="$CPPFLAGS $addcflags" + dnl Try pkg-config even when cross-compiling. Since we + dnl specify PKG_CONFIG_LIBDIR we are only looking where + dnl the user told us to look + + RUSTLS_PCDIR="$PREFIX_RUSTLS/lib/pkgconfig" + if test -f "$RUSTLS_PCDIR/rustls.pc"; then + AC_MSG_NOTICE([PKG_CONFIG_LIBDIR will be set to "$RUSTLS_PCDIR"]) + PKGTEST="yes" fi - AC_CHECK_LIB(rustls, rustls_connection_read, - [ - AC_DEFINE(USE_RUSTLS, 1, [if rustls is enabled]) - AC_SUBST(USE_RUSTLS, [1]) - RUSTLS_ENABLED=1 - USE_RUSTLS="yes" - ssl_msg="rustls" - test rustls != "$DEFAULT_SSL_BACKEND" || VALID_DEFAULT_SSL_BACKEND=yes - ], - AC_MSG_ERROR([--with-rustls was specified but could not find rustls.]), - -lpthread -ldl -lm) - fi + if test "$PKGTEST" != "yes"; then + # try lib64 instead + RUSTLS_PCDIR="$PREFIX_RUSTLS/lib64/pkgconfig" + if test -f "$RUSTLS_PCDIR/rustls.pc"; then + AC_MSG_NOTICE([PKG_CONFIG_LIBDIR will be set to "$RUSTLS_PCDIR"]) + PKGTEST="yes" + fi + fi + + if test "$PKGTEST" != "yes"; then + dnl pkg-config came up empty, use what we got + dnl via --with-rustls - if test "x$USE_RUSTLS" = "xyes"; then - AC_MSG_NOTICE([detected rustls]) - check_for_ca_bundle=1 - - LIBS="-lrustls -lpthread -ldl -lm $LIBS" - - if test -n "$rustlslib"; then - dnl when shared libs were found in a path that the run-time - dnl linker doesn't search through, we need to add it to - dnl CURL_LIBRARY_PATH to prevent further configure tests to fail - dnl due to this - if test "x$cross_compiling" != "xyes"; then - CURL_LIBRARY_PATH="$CURL_LIBRARY_PATH:$rustlslib" - export CURL_LIBRARY_PATH - AC_MSG_NOTICE([Added $rustlslib to CURL_LIBRARY_PATH]) + addld=-L$PREFIX_RUSTLS/lib$libsuff + addcflags=-I$PREFIX_RUSTLS/include + + LDFLAGS="$LDFLAGS $addld" + if test "$addcflags" != "-I/usr/include"; then + CPPFLAGS="$CPPFLAGS $addcflags" + fi + + AC_CHECK_LIB(rustls, rustls_connection_read, + [ + AC_DEFINE(USE_RUSTLS, 1, [if rustls is enabled]) + AC_SUBST(USE_RUSTLS, [1]) + RUSTLS_ENABLED=1 + USE_RUSTLS="yes" + ssl_msg="rustls" + test rustls != "$DEFAULT_SSL_BACKEND" || VALID_DEFAULT_SSL_BACKEND=yes + ], + AC_MSG_ERROR([--with-rustls was specified but could not find rustls.]), + -lpthread -ldl -lm) + + USE_RUSTLS="yes" + ssl_msg="rustls" + + LIB_RUSTLS="$PREFIX_RUSTLS/lib$libsuff" + if test "$PREFIX_RUSTLS" != "/usr" ; then + SSL_LDFLAGS="-L$LIB_RUSTLS" + SSL_CPPFLAGS="-I$PREFIX_RUSTLS/include" fi fi + ;; + esac + + if test "$PKGTEST" = "yes"; then + + CURL_CHECK_PKGCONFIG(rustls, [$RUSTLS_PCDIR]) + + if test "$PKGCONFIG" != "no" ; then + SSL_LIBS=`CURL_EXPORT_PCDIR([$RUSTLS_PCDIR]) dnl + $PKGCONFIG --libs-only-l --libs-only-other rustls 2>/dev/null` + + SSL_LDFLAGS=`CURL_EXPORT_PCDIR([$RUSTLS_PCDIR]) dnl + $PKGCONFIG --libs-only-L rustls 2>/dev/null` + + SSL_CPPFLAGS=`CURL_EXPORT_PCDIR([$RUSTLS_PCDIR]) dnl + $PKGCONFIG --cflags-only-I rustls 2>/dev/null` + + AC_SUBST(SSL_LIBS) + AC_MSG_NOTICE([pkg-config: SSL_LIBS: "$SSL_LIBS"]) + AC_MSG_NOTICE([pkg-config: SSL_LDFLAGS: "$SSL_LDFLAGS"]) + AC_MSG_NOTICE([pkg-config: SSL_CPPFLAGS: "$SSL_CPPFLAGS"]) + + LIB_RUSTLS=`echo $SSL_LDFLAGS | sed -e 's/^-L//'` + + dnl use the values pkg-config reported. This is here + dnl instead of below with CPPFLAGS and LDFLAGS because we only + dnl learn about this via pkg-config. If we only have + dnl the argument to --with-rustls we don't know what + dnl additional libs may be necessary. Hope that we + dnl don't need any. + LIBS="$SSL_LIBS $LIBS" + USE_RUSTLS="yes" + ssl_msg="rustls" + else + AC_MSG_ERROR([pkg-config: Could not find rustls]) fi - fi dnl rustls not disabled + else + dnl we did not use pkg-config, so we need to add the + dnl rustls lib to LIBS + LIBS="-lrustls -lpthread -ldl -lm $LIBS" + fi + + dnl finally, set flags to use this TLS backend + CPPFLAGS="$CLEAN_CPPFLAGS $SSL_CPPFLAGS" + LDFLAGS="$CLAN_LDFLAGS $SSL_LDFLAGS" + + if test "x$USE_RUSTLS" = "xyes"; then + AC_MSG_NOTICE([detected rustls]) + check_for_ca_bundle=1 + + if test -n "$LIB_RUSTLS"; then + dnl when shared libs were found in a path that the run-time + dnl linker does not search through, we need to add it to + dnl CURL_LIBRARY_PATH so that further configure tests do not + dnl fail due to this + if test "x$cross_compiling" != "xyes"; then + CURL_LIBRARY_PATH="$CURL_LIBRARY_PATH:$LIB_RUSTLS" + export CURL_LIBRARY_PATH + AC_MSG_NOTICE([Added $LIB_RUSTLS to CURL_LIBRARY_PATH]) + fi + fi + fi test -z "$ssl_msg" || ssl_backends="${ssl_backends:+$ssl_backends, }$ssl_msg" fi From fe9f68fa618f33f79cd626eaf69bb38cbf26affd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 25 Mar 2024 10:02:30 +0100 Subject: [PATCH 498/509] cmdline-opts: shorter help texts In an effort to increase the readability of the "--help all" output on narrow (80 column) terminals. Co-authored-by: Jay Satiro Closes #13169 --- docs/cmdline-opts/aws-sigv4.md | 4 +- docs/cmdline-opts/basic.md | 2 +- docs/cmdline-opts/ca-native.md | 2 +- docs/cmdline-opts/cert-status.md | 2 +- docs/cmdline-opts/connect-timeout.md | 4 +- docs/cmdline-opts/cookie-jar.md | 2 +- docs/cmdline-opts/cookie.md | 2 +- docs/cmdline-opts/crlfile.md | 2 +- docs/cmdline-opts/curves.md | 4 +- docs/cmdline-opts/digest.md | 2 +- docs/cmdline-opts/doh-cert-status.md | 11 +- docs/cmdline-opts/etag-compare.md | 12 +- docs/cmdline-opts/etag-save.md | 2 +- docs/cmdline-opts/fail-early.md | 2 +- docs/cmdline-opts/form-escape.md | 2 +- docs/cmdline-opts/ftp-pasv.md | 2 +- docs/cmdline-opts/ftp-port.md | 2 +- docs/cmdline-opts/ftp-ssl-control.md | 2 +- docs/cmdline-opts/globoff.md | 2 +- .../cmdline-opts/happy-eyeballs-timeout-ms.md | 4 +- docs/cmdline-opts/haproxy-clientip.md | 4 +- docs/cmdline-opts/hostpubmd5.md | 2 +- docs/cmdline-opts/hostpubsha256.md | 2 +- docs/cmdline-opts/include.md | 2 +- docs/cmdline-opts/libcurl.md | 2 +- docs/cmdline-opts/local-port.md | 4 +- docs/cmdline-opts/location-trusted.md | 2 +- docs/cmdline-opts/mail-rcpt-allowfails.md | 2 +- docs/cmdline-opts/max-time.md | 2 +- docs/cmdline-opts/ntlm-wb.md | 2 +- docs/cmdline-opts/ntlm.md | 2 +- docs/cmdline-opts/post301.md | 2 +- docs/cmdline-opts/post302.md | 2 +- docs/cmdline-opts/post303.md | 2 +- docs/cmdline-opts/proxy-ca-native.md | 2 +- docs/cmdline-opts/proxy-cacert.md | 2 +- docs/cmdline-opts/proxy-capath.md | 12 +- docs/cmdline-opts/proxy-digest.md | 2 +- docs/cmdline-opts/proxy-insecure.md | 14 +- docs/cmdline-opts/proxy-negotiate.md | 2 +- docs/cmdline-opts/proxy-ntlm.md | 2 +- .../proxy-ssl-auto-client-cert.md | 4 +- docs/cmdline-opts/proxy-tlsv1.md | 2 +- docs/cmdline-opts/proxytunnel.md | 2 +- docs/cmdline-opts/remote-name.md | 2 +- docs/cmdline-opts/remote-time.md | 2 +- docs/cmdline-opts/resolve.md | 2 +- docs/cmdline-opts/retry-all-errors.md | 2 +- docs/cmdline-opts/retry-connrefused.md | 2 +- docs/cmdline-opts/sasl-ir.md | 2 +- docs/cmdline-opts/socks5-basic.md | 2 +- docs/cmdline-opts/ssl-revoke-best-effort.md | 2 +- docs/cmdline-opts/ssl.md | 2 +- docs/cmdline-opts/sslv2.md | 2 +- docs/cmdline-opts/sslv3.md | 2 +- docs/cmdline-opts/tcp-nodelay.md | 2 +- docs/cmdline-opts/tls-max.md | 2 +- docs/cmdline-opts/tls13-ciphers.md | 2 +- docs/cmdline-opts/tlsv1.0.md | 2 +- docs/cmdline-opts/tlsv1.1.md | 2 +- docs/cmdline-opts/tlsv1.2.md | 2 +- docs/cmdline-opts/tlsv1.3.md | 2 +- docs/cmdline-opts/tlsv1.md | 2 +- docs/cmdline-opts/trace-ids.md | 2 +- docs/cmdline-opts/write-out.md | 2 +- src/tool_help.c | 22 ++- src/tool_listhelp.c | 142 +++++++++--------- tests/data/test1461 | 24 +-- tests/data/test1463 | 6 +- tests/data/test1464 | 6 +- 70 files changed, 215 insertions(+), 170 deletions(-) diff --git a/docs/cmdline-opts/aws-sigv4.md b/docs/cmdline-opts/aws-sigv4.md index 1b3909244f0..517cc1c5b08 100644 --- a/docs/cmdline-opts/aws-sigv4.md +++ b/docs/cmdline-opts/aws-sigv4.md @@ -3,8 +3,8 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: aws-sigv4 Protocols: HTTP -Arg: -Help: Use AWS V4 signature authentication +Arg: +Help: AWS V4 signature auth Category: auth http Added: 7.75.0 Multi: single diff --git a/docs/cmdline-opts/basic.md b/docs/cmdline-opts/basic.md index abb516aa036..16acd4cb603 100644 --- a/docs/cmdline-opts/basic.md +++ b/docs/cmdline-opts/basic.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: basic -Help: Use HTTP Basic Authentication +Help: HTTP Basic Authentication Protocols: HTTP Category: auth Added: 7.10.6 diff --git a/docs/cmdline-opts/ca-native.md b/docs/cmdline-opts/ca-native.md index aac7456e9bc..a771a7a8133 100644 --- a/docs/cmdline-opts/ca-native.md +++ b/docs/cmdline-opts/ca-native.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ca-native -Help: Use CA certificates from the native OS +Help: Load CA certs from the OS Protocols: TLS Category: tls Added: 8.2.0 diff --git a/docs/cmdline-opts/cert-status.md b/docs/cmdline-opts/cert-status.md index 6d7b234bf7a..8b6e57b9edf 100644 --- a/docs/cmdline-opts/cert-status.md +++ b/docs/cmdline-opts/cert-status.md @@ -4,7 +4,7 @@ SPDX-License-Identifier: curl Long: cert-status Protocols: TLS Added: 7.41.0 -Help: Verify the status of the server cert via OCSP-staple +Help: Verify server cert status OCSP-staple Category: tls Multi: boolean See-also: diff --git a/docs/cmdline-opts/connect-timeout.md b/docs/cmdline-opts/connect-timeout.md index f7281b09a94..e1400811e9d 100644 --- a/docs/cmdline-opts/connect-timeout.md +++ b/docs/cmdline-opts/connect-timeout.md @@ -2,8 +2,8 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: connect-timeout -Arg: -Help: Maximum time allowed for connection +Arg: +Help: Maximum time allowed to connect Category: connection Added: 7.7 Multi: single diff --git a/docs/cmdline-opts/cookie-jar.md b/docs/cmdline-opts/cookie-jar.md index da2ac433281..f993685916b 100644 --- a/docs/cmdline-opts/cookie-jar.md +++ b/docs/cmdline-opts/cookie-jar.md @@ -5,7 +5,7 @@ Short: c Long: cookie-jar Arg: Protocols: HTTP -Help: Write cookies to after operation +Help: Save cookies to after operation Category: http Added: 7.9 Multi: single diff --git a/docs/cmdline-opts/cookie.md b/docs/cmdline-opts/cookie.md index c61f9821578..cbc8b84572a 100644 --- a/docs/cmdline-opts/cookie.md +++ b/docs/cmdline-opts/cookie.md @@ -5,7 +5,7 @@ Short: b Long: cookie Arg: Protocols: HTTP -Help: Send cookies from string/file +Help: Send cookies from string/load from file Category: http Added: 4.9 Multi: append diff --git a/docs/cmdline-opts/crlfile.md b/docs/cmdline-opts/crlfile.md index 16bd7b35b98..a762af09f11 100644 --- a/docs/cmdline-opts/crlfile.md +++ b/docs/cmdline-opts/crlfile.md @@ -4,7 +4,7 @@ SPDX-License-Identifier: curl Long: crlfile Arg: Protocols: TLS -Help: Use this CRL list +Help: Certificate Revocation list Added: 7.19.7 Category: tls Multi: single diff --git a/docs/cmdline-opts/curves.md b/docs/cmdline-opts/curves.md index b701773641f..9473aeaa7a8 100644 --- a/docs/cmdline-opts/curves.md +++ b/docs/cmdline-opts/curves.md @@ -2,8 +2,8 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: curves -Arg: -Help: (EC) TLS key exchange algorithm(s) to request +Arg: +Help: (EC) TLS key exchange algorithms to request Protocols: TLS Added: 7.73.0 Category: tls diff --git a/docs/cmdline-opts/digest.md b/docs/cmdline-opts/digest.md index 658932a5434..04c5a79a964 100644 --- a/docs/cmdline-opts/digest.md +++ b/docs/cmdline-opts/digest.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: digest -Help: Use HTTP Digest Authentication +Help: HTTP Digest Authentication Protocols: HTTP Mutexed: basic ntlm negotiate Category: proxy auth http diff --git a/docs/cmdline-opts/doh-cert-status.md b/docs/cmdline-opts/doh-cert-status.md index efa9da75c15..920c5b435d5 100644 --- a/docs/cmdline-opts/doh-cert-status.md +++ b/docs/cmdline-opts/doh-cert-status.md @@ -2,7 +2,7 @@ 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 +Help: Verify DoH server cert status OCSP-staple Added: 7.76.0 Category: dns tls Multi: boolean @@ -15,3 +15,12 @@ Example: # `--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/etag-compare.md b/docs/cmdline-opts/etag-compare.md index a695e55eae4..d69cbdf34c4 100644 --- a/docs/cmdline-opts/etag-compare.md +++ b/docs/cmdline-opts/etag-compare.md @@ -3,7 +3,7 @@ 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 +Help: Load ETag from file Protocols: HTTP Added: 7.68.0 Category: http @@ -20,10 +20,8 @@ Example: 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. +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. +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.md b/docs/cmdline-opts/etag-save.md index d642552ffc5..aa346adad3b 100644 --- a/docs/cmdline-opts/etag-save.md +++ b/docs/cmdline-opts/etag-save.md @@ -3,7 +3,7 @@ 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 +Help: Parse incoming ETag and save to a file Protocols: HTTP Added: 7.68.0 Category: http diff --git a/docs/cmdline-opts/fail-early.md b/docs/cmdline-opts/fail-early.md index 40a2e012618..bb22e14707f 100644 --- a/docs/cmdline-opts/fail-early.md +++ b/docs/cmdline-opts/fail-early.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: fail-early -Help: Fail on first transfer error, do not continue +Help: Fail on first transfer error Added: 7.52.0 Category: curl Multi: boolean diff --git a/docs/cmdline-opts/form-escape.md b/docs/cmdline-opts/form-escape.md index d2bd0d32b9a..083c29e16ba 100644 --- a/docs/cmdline-opts/form-escape.md +++ b/docs/cmdline-opts/form-escape.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: form-escape -Help: Escape multipart form field/filenames using backslash +Help: Escape form fields using backslash Protocols: HTTP Added: 7.81.0 Category: http upload diff --git a/docs/cmdline-opts/ftp-pasv.md b/docs/cmdline-opts/ftp-pasv.md index 265a8e4534c..964f9769ae5 100644 --- a/docs/cmdline-opts/ftp-pasv.md +++ b/docs/cmdline-opts/ftp-pasv.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-pasv -Help: Use PASV/EPSV instead of PORT +Help: Send PASV/EPSV instead of PORT Protocols: FTP Added: 7.11.0 Category: ftp diff --git a/docs/cmdline-opts/ftp-port.md b/docs/cmdline-opts/ftp-port.md index 6ac296e2f1b..ff6d41c131f 100644 --- a/docs/cmdline-opts/ftp-port.md +++ b/docs/cmdline-opts/ftp-port.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ftp-port Arg:
-Help: Use PORT instead of PASV +Help: Send PORT instead of PASV Short: P Protocols: FTP Category: ftp diff --git a/docs/cmdline-opts/ftp-ssl-control.md b/docs/cmdline-opts/ftp-ssl-control.md index ace1ab29fbd..a68359a7b63 100644 --- a/docs/cmdline-opts/ftp-ssl-control.md +++ b/docs/cmdline-opts/ftp-ssl-control.md @@ -2,7 +2,7 @@ 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 +Help: Require TLS for login, clear for transfer Protocols: FTP Added: 7.16.0 Category: ftp tls diff --git a/docs/cmdline-opts/globoff.md b/docs/cmdline-opts/globoff.md index 1eca6dd0051..3c8c341439d 100644 --- a/docs/cmdline-opts/globoff.md +++ b/docs/cmdline-opts/globoff.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: globoff Short: g -Help: Disable URL sequences and ranges using {} and [] +Help: Disable URL globbing with {} and [] Category: curl Added: 7.6 Multi: boolean diff --git a/docs/cmdline-opts/happy-eyeballs-timeout-ms.md b/docs/cmdline-opts/happy-eyeballs-timeout-ms.md index 0ee2cd7275e..8370ee92bbe 100644 --- a/docs/cmdline-opts/happy-eyeballs-timeout-ms.md +++ b/docs/cmdline-opts/happy-eyeballs-timeout-ms.md @@ -2,8 +2,8 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: happy-eyeballs-timeout-ms -Arg: -Help: Time for IPv6 before trying IPv4 +Arg: +Help: Time for IPv6 before IPv4 Added: 7.59.0 Category: connection Multi: single diff --git a/docs/cmdline-opts/haproxy-clientip.md b/docs/cmdline-opts/haproxy-clientip.md index 470d556f068..fde085a9769 100644 --- a/docs/cmdline-opts/haproxy-clientip.md +++ b/docs/cmdline-opts/haproxy-clientip.md @@ -2,8 +2,8 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: haproxy-clientip -Arg: -Help: Sets client IP in HAProxy PROXY protocol v1 header +Arg: +Help: Set address in HAProxy PROXY Protocols: HTTP Added: 8.2.0 Category: http proxy diff --git a/docs/cmdline-opts/hostpubmd5.md b/docs/cmdline-opts/hostpubmd5.md index 15add357d30..7dc873254fc 100644 --- a/docs/cmdline-opts/hostpubmd5.md +++ b/docs/cmdline-opts/hostpubmd5.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: hostpubmd5 Arg: -Help: Acceptable MD5 hash of the host public key +Help: Acceptable MD5 hash of host public key Protocols: SFTP SCP Added: 7.17.1 Category: sftp scp diff --git a/docs/cmdline-opts/hostpubsha256.md b/docs/cmdline-opts/hostpubsha256.md index b1faaf86964..8ec080551d8 100644 --- a/docs/cmdline-opts/hostpubsha256.md +++ b/docs/cmdline-opts/hostpubsha256.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: hostpubsha256 Arg: -Help: Acceptable SHA256 hash of the host public key +Help: Acceptable SHA256 hash of host public key Protocols: SFTP SCP Added: 7.80.0 Category: sftp scp diff --git a/docs/cmdline-opts/include.md b/docs/cmdline-opts/include.md index aedf5da0bb3..c4f6beb81cd 100644 --- a/docs/cmdline-opts/include.md +++ b/docs/cmdline-opts/include.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: include Short: i -Help: Include protocol response headers in the output +Help: Include response headers in output Protocols: HTTP FTP Category: important verbose Added: 4.8 diff --git a/docs/cmdline-opts/libcurl.md b/docs/cmdline-opts/libcurl.md index 4b3c13d4c67..eeae596d0a5 100644 --- a/docs/cmdline-opts/libcurl.md +++ b/docs/cmdline-opts/libcurl.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: libcurl Arg: -Help: Dump libcurl equivalent code of this command line +Help: Generate libcurl code for this command line Added: 7.16.1 Category: curl Multi: single diff --git a/docs/cmdline-opts/local-port.md b/docs/cmdline-opts/local-port.md index ef01a7c04ff..b8c0d3fda1b 100644 --- a/docs/cmdline-opts/local-port.md +++ b/docs/cmdline-opts/local-port.md @@ -2,8 +2,8 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: local-port -Arg: -Help: Force use of RANGE for local port numbers +Arg: +Help: Use a local port number within RANGE Added: 7.15.2 Category: connection Multi: single diff --git a/docs/cmdline-opts/location-trusted.md b/docs/cmdline-opts/location-trusted.md index 11c1486c97a..4f4e7def57a 100644 --- a/docs/cmdline-opts/location-trusted.md +++ b/docs/cmdline-opts/location-trusted.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: location-trusted -Help: Like --location, and send auth to other hosts +Help: Like --location, but send auth to other hosts Protocols: HTTP Category: http auth Added: 7.10.4 diff --git a/docs/cmdline-opts/mail-rcpt-allowfails.md b/docs/cmdline-opts/mail-rcpt-allowfails.md index 1b670adb095..a82948bbc4f 100644 --- a/docs/cmdline-opts/mail-rcpt-allowfails.md +++ b/docs/cmdline-opts/mail-rcpt-allowfails.md @@ -2,7 +2,7 @@ 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 +Help: Allow RCPT TO command to fail Protocols: SMTP Added: 7.69.0 Category: smtp diff --git a/docs/cmdline-opts/max-time.md b/docs/cmdline-opts/max-time.md index 17938dcf235..9102442aa9d 100644 --- a/docs/cmdline-opts/max-time.md +++ b/docs/cmdline-opts/max-time.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: max-time Short: m -Arg: +Arg: Help: Maximum time allowed for transfer Category: connection Added: 4.0 diff --git a/docs/cmdline-opts/ntlm-wb.md b/docs/cmdline-opts/ntlm-wb.md index bc75dda5be9..c5bcd4bfdc0 100644 --- a/docs/cmdline-opts/ntlm-wb.md +++ b/docs/cmdline-opts/ntlm-wb.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ntlm-wb -Help: Use HTTP NTLM authentication with winbind +Help: HTTP NTLM authentication with winbind Protocols: HTTP Category: auth http Added: 7.22.0 diff --git a/docs/cmdline-opts/ntlm.md b/docs/cmdline-opts/ntlm.md index 3faeed7d124..b37716bcaa7 100644 --- a/docs/cmdline-opts/ntlm.md +++ b/docs/cmdline-opts/ntlm.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ntlm -Help: Use HTTP NTLM authentication +Help: HTTP NTLM authentication Mutexed: basic negotiate digest anyauth Protocols: HTTP Requires: TLS diff --git a/docs/cmdline-opts/post301.md b/docs/cmdline-opts/post301.md index 93c9c65f0f6..d9506f7dfe3 100644 --- a/docs/cmdline-opts/post301.md +++ b/docs/cmdline-opts/post301.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: post301 -Help: Do not switch to GET after following a 301 +Help: Do not switch to GET after a 301 redirect Protocols: HTTP Added: 7.17.1 Category: http post diff --git a/docs/cmdline-opts/post302.md b/docs/cmdline-opts/post302.md index 93578be0cac..9b2c2f658d7 100644 --- a/docs/cmdline-opts/post302.md +++ b/docs/cmdline-opts/post302.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: post302 -Help: Do not switch to GET after following a 302 +Help: Do not switch to GET after a 302 redirect Protocols: HTTP Added: 7.19.1 Category: http post diff --git a/docs/cmdline-opts/post303.md b/docs/cmdline-opts/post303.md index 916e88a0b68..63dc0d7956b 100644 --- a/docs/cmdline-opts/post303.md +++ b/docs/cmdline-opts/post303.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: post303 -Help: Do not switch to GET after following a 303 +Help: Do not switch to GET after a 303 redirect Protocols: HTTP Added: 7.26.0 Category: http post diff --git a/docs/cmdline-opts/proxy-ca-native.md b/docs/cmdline-opts/proxy-ca-native.md index 9f09cee0cb9..6158b6cf6f4 100644 --- a/docs/cmdline-opts/proxy-ca-native.md +++ b/docs/cmdline-opts/proxy-ca-native.md @@ -2,7 +2,7 @@ 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 +Help: Load CA certs from the OS to verify proxy Protocols: TLS Category: tls Added: 8.2.0 diff --git a/docs/cmdline-opts/proxy-cacert.md b/docs/cmdline-opts/proxy-cacert.md index b3a038a591f..ec0dd9f1432 100644 --- a/docs/cmdline-opts/proxy-cacert.md +++ b/docs/cmdline-opts/proxy-cacert.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: proxy-cacert -Help: CA certificate to verify peer against for proxy +Help: CA certificates to verify proxy against Arg: Added: 7.52.0 Category: proxy tls diff --git a/docs/cmdline-opts/proxy-capath.md b/docs/cmdline-opts/proxy-capath.md index 62a25a0df55..bc2c7b56f59 100644 --- a/docs/cmdline-opts/proxy-capath.md +++ b/docs/cmdline-opts/proxy-capath.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: proxy-capath -Help: CA directory to verify peer against for proxy +Help: CA directory to verify proxy against Arg: Added: 7.52.0 Category: proxy tls @@ -18,3 +18,13 @@ Example: # `--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-digest.md b/docs/cmdline-opts/proxy-digest.md index 4822c79bd7b..77b88d7e4bd 100644 --- a/docs/cmdline-opts/proxy-digest.md +++ b/docs/cmdline-opts/proxy-digest.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: proxy-digest -Help: Use Digest authentication on the proxy +Help: Digest auth with the proxy Category: proxy tls Added: 7.12.0 Multi: mutex diff --git a/docs/cmdline-opts/proxy-insecure.md b/docs/cmdline-opts/proxy-insecure.md index 3e174428a91..5796c36237d 100644 --- a/docs/cmdline-opts/proxy-insecure.md +++ b/docs/cmdline-opts/proxy-insecure.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: proxy-insecure -Help: Do HTTPS proxy connections without verifying the proxy +Help: Skip HTTPS proxy cert verification Added: 7.52.0 Category: proxy tls Multi: boolean @@ -16,3 +16,15 @@ Example: # `--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-negotiate.md b/docs/cmdline-opts/proxy-negotiate.md index 33ab1f99ae2..9bedf5dc4aa 100644 --- a/docs/cmdline-opts/proxy-negotiate.md +++ b/docs/cmdline-opts/proxy-negotiate.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: proxy-negotiate -Help: Use HTTP Negotiate (SPNEGO) authentication on the proxy +Help: HTTP Negotiate (SPNEGO) auth with the proxy Added: 7.17.1 Category: proxy auth Multi: mutex diff --git a/docs/cmdline-opts/proxy-ntlm.md b/docs/cmdline-opts/proxy-ntlm.md index 5e772cd6a1b..f8375a620e5 100644 --- a/docs/cmdline-opts/proxy-ntlm.md +++ b/docs/cmdline-opts/proxy-ntlm.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: proxy-ntlm -Help: Use NTLM authentication on the proxy +Help: NTLM authentication with the proxy Category: proxy auth Added: 7.10.7 Multi: mutex diff --git a/docs/cmdline-opts/proxy-ssl-auto-client-cert.md b/docs/cmdline-opts/proxy-ssl-auto-client-cert.md index f3e77158d1e..578a7a6417c 100644 --- a/docs/cmdline-opts/proxy-ssl-auto-client-cert.md +++ b/docs/cmdline-opts/proxy-ssl-auto-client-cert.md @@ -2,7 +2,7 @@ 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) +Help: Auto client certificate for proxy Added: 7.77.0 Category: proxy tls Multi: boolean @@ -16,3 +16,5 @@ Example: # `--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-tlsv1.md b/docs/cmdline-opts/proxy-tlsv1.md index b7b09ee473b..0dda72f4b69 100644 --- a/docs/cmdline-opts/proxy-tlsv1.md +++ b/docs/cmdline-opts/proxy-tlsv1.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: proxy-tlsv1 -Help: Use TLSv1 for HTTPS proxy +Help: TLSv1 for HTTPS proxy Added: 7.52.0 Category: proxy tls auth Multi: mutex diff --git a/docs/cmdline-opts/proxytunnel.md b/docs/cmdline-opts/proxytunnel.md index 74faa681a91..169d2ad8bc4 100644 --- a/docs/cmdline-opts/proxytunnel.md +++ b/docs/cmdline-opts/proxytunnel.md @@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: proxytunnel Short: p -Help: Operate through an HTTP proxy tunnel (using CONNECT) +Help: HTTP proxy tunnel (using CONNECT) Category: proxy Added: 7.3 Multi: boolean diff --git a/docs/cmdline-opts/remote-name.md b/docs/cmdline-opts/remote-name.md index 487799fafc9..5d2fcdcb2b6 100644 --- a/docs/cmdline-opts/remote-name.md +++ b/docs/cmdline-opts/remote-name.md @@ -3,7 +3,7 @@ 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 +Help: Write output to file named as remote file Category: important output Added: 4.0 Multi: append diff --git a/docs/cmdline-opts/remote-time.md b/docs/cmdline-opts/remote-time.md index b010bc1308c..7c5d21f0367 100644 --- a/docs/cmdline-opts/remote-time.md +++ b/docs/cmdline-opts/remote-time.md @@ -3,7 +3,7 @@ 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 +Help: Set remote file's time on local output Category: output Added: 7.9 Multi: boolean diff --git a/docs/cmdline-opts/resolve.md b/docs/cmdline-opts/resolve.md index 6e0d393f54a..ca1f930fcd2 100644 --- a/docs/cmdline-opts/resolve.md +++ b/docs/cmdline-opts/resolve.md @@ -3,7 +3,7 @@ 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 +Help: Resolve host+port to address Added: 7.21.3 Category: connection dns Multi: append diff --git a/docs/cmdline-opts/retry-all-errors.md b/docs/cmdline-opts/retry-all-errors.md index 6d3deebc76c..230e730678e 100644 --- a/docs/cmdline-opts/retry-all-errors.md +++ b/docs/cmdline-opts/retry-all-errors.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: retry-all-errors -Help: Retry all errors (use with --retry) +Help: Retry all errors (with --retry) Added: 7.71.0 Category: curl Multi: boolean diff --git a/docs/cmdline-opts/retry-connrefused.md b/docs/cmdline-opts/retry-connrefused.md index 975dc097a70..22345cd8818 100644 --- a/docs/cmdline-opts/retry-connrefused.md +++ b/docs/cmdline-opts/retry-connrefused.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: retry-connrefused -Help: Retry on connection refused (use with --retry) +Help: Retry on connection refused (with --retry) Added: 7.52.0 Category: curl Multi: boolean diff --git a/docs/cmdline-opts/sasl-ir.md b/docs/cmdline-opts/sasl-ir.md index 56732807d48..b11137df0a6 100644 --- a/docs/cmdline-opts/sasl-ir.md +++ b/docs/cmdline-opts/sasl-ir.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: sasl-ir -Help: Enable initial response in SASL authentication +Help: Initial response in SASL authentication Added: 7.31.0 Category: auth Multi: boolean diff --git a/docs/cmdline-opts/socks5-basic.md b/docs/cmdline-opts/socks5-basic.md index ec80fa9edc9..dc2a5532f11 100644 --- a/docs/cmdline-opts/socks5-basic.md +++ b/docs/cmdline-opts/socks5-basic.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: socks5-basic -Help: Enable username/password auth for SOCKS5 proxies +Help: Username/password auth for SOCKS5 proxies Added: 7.55.0 Category: proxy auth Multi: mutex diff --git a/docs/cmdline-opts/ssl-revoke-best-effort.md b/docs/cmdline-opts/ssl-revoke-best-effort.md index 994e1f654c5..0257e05f47e 100644 --- a/docs/cmdline-opts/ssl-revoke-best-effort.md +++ b/docs/cmdline-opts/ssl-revoke-best-effort.md @@ -2,7 +2,7 @@ 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) +Help: Ignore missing cert CRL dist points Added: 7.70.0 Protocols: TLS Category: tls diff --git a/docs/cmdline-opts/ssl.md b/docs/cmdline-opts/ssl.md index 9a78ae3a26e..73fa96ad641 100644 --- a/docs/cmdline-opts/ssl.md +++ b/docs/cmdline-opts/ssl.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: ssl -Help: Try SSL/TLS +Help: Try enabling TLS Protocols: FTP IMAP POP3 SMTP LDAP Added: 7.20.0 Category: tls diff --git a/docs/cmdline-opts/sslv2.md b/docs/cmdline-opts/sslv2.md index 05fe938bab3..3bd36f02cd4 100644 --- a/docs/cmdline-opts/sslv2.md +++ b/docs/cmdline-opts/sslv2.md @@ -8,7 +8,7 @@ Protocols: SSL Added: 5.9 Mutexed: sslv3 tlsv1 tlsv1.1 tlsv1.2 Requires: TLS -Help: Use SSLv2 +Help: SSLv2 Category: tls Multi: mutex See-also: diff --git a/docs/cmdline-opts/sslv3.md b/docs/cmdline-opts/sslv3.md index 343f628a5f9..32d4c120669 100644 --- a/docs/cmdline-opts/sslv3.md +++ b/docs/cmdline-opts/sslv3.md @@ -8,7 +8,7 @@ Protocols: SSL Added: 5.9 Mutexed: sslv2 tlsv1 tlsv1.1 tlsv1.2 Requires: TLS -Help: Use SSLv3 +Help: SSLv3 Category: tls Multi: mutex See-also: diff --git a/docs/cmdline-opts/tcp-nodelay.md b/docs/cmdline-opts/tcp-nodelay.md index 9a6df8d62cc..6944d70142b 100644 --- a/docs/cmdline-opts/tcp-nodelay.md +++ b/docs/cmdline-opts/tcp-nodelay.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: tcp-nodelay -Help: Use the TCP_NODELAY option +Help: Set TCP_NODELAY Added: 7.11.2 Category: connection Multi: boolean diff --git a/docs/cmdline-opts/tls-max.md b/docs/cmdline-opts/tls-max.md index a815d21d6bf..87233c75ac0 100644 --- a/docs/cmdline-opts/tls-max.md +++ b/docs/cmdline-opts/tls-max.md @@ -7,7 +7,7 @@ Tags: Versions Protocols: TLS Added: 7.54.0 Requires: TLS -Help: Set maximum allowed TLS version +Help: Maximum allowed TLS version Category: tls Multi: single See-also: diff --git a/docs/cmdline-opts/tls13-ciphers.md b/docs/cmdline-opts/tls13-ciphers.md index 2f68a6195bd..55145aacf9c 100644 --- a/docs/cmdline-opts/tls13-ciphers.md +++ b/docs/cmdline-opts/tls13-ciphers.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: tls13-ciphers -Arg: +Arg: help: TLS 1.3 cipher suites to use Protocols: TLS Category: tls diff --git a/docs/cmdline-opts/tlsv1.0.md b/docs/cmdline-opts/tlsv1.0.md index 01aa0aea0d6..66ca32389ef 100644 --- a/docs/cmdline-opts/tlsv1.0.md +++ b/docs/cmdline-opts/tlsv1.0.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: tlsv1.0 -Help: Use TLSv1.0 or greater +Help: TLSv1.0 or greater Protocols: TLS Added: 7.34.0 Category: tls diff --git a/docs/cmdline-opts/tlsv1.1.md b/docs/cmdline-opts/tlsv1.1.md index b0d17838c87..577b7c7a501 100644 --- a/docs/cmdline-opts/tlsv1.1.md +++ b/docs/cmdline-opts/tlsv1.1.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: tlsv1.1 -Help: Use TLSv1.1 or greater +Help: TLSv1.1 or greater Protocols: TLS Added: 7.34.0 Category: tls diff --git a/docs/cmdline-opts/tlsv1.2.md b/docs/cmdline-opts/tlsv1.2.md index b39c9abcafa..0132074e3c2 100644 --- a/docs/cmdline-opts/tlsv1.2.md +++ b/docs/cmdline-opts/tlsv1.2.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: tlsv1.2 -Help: Use TLSv1.2 or greater +Help: TLSv1.2 or greater Protocols: TLS Added: 7.34.0 Category: tls diff --git a/docs/cmdline-opts/tlsv1.3.md b/docs/cmdline-opts/tlsv1.3.md index 537b372a1c4..6c65f59de65 100644 --- a/docs/cmdline-opts/tlsv1.3.md +++ b/docs/cmdline-opts/tlsv1.3.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: tlsv1.3 -Help: Use TLSv1.3 or greater +Help: TLSv1.3 or greater Protocols: TLS Added: 7.52.0 Category: tls diff --git a/docs/cmdline-opts/tlsv1.md b/docs/cmdline-opts/tlsv1.md index a3960e53edc..c6fc9e9230b 100644 --- a/docs/cmdline-opts/tlsv1.md +++ b/docs/cmdline-opts/tlsv1.md @@ -8,7 +8,7 @@ Protocols: TLS Added: 7.9.2 Mutexed: tlsv1.1 tlsv1.2 tlsv1.3 Requires: TLS -Help: Use TLSv1.0 or greater +Help: TLSv1.0 or greater Category: tls Multi: mutex See-also: diff --git a/docs/cmdline-opts/trace-ids.md b/docs/cmdline-opts/trace-ids.md index 43774d37204..bf54ecb3427 100644 --- a/docs/cmdline-opts/trace-ids.md +++ b/docs/cmdline-opts/trace-ids.md @@ -2,7 +2,7 @@ c: Copyright (C) Daniel Stenberg, , et al. SPDX-License-Identifier: curl Long: trace-ids -Help: Add transfer and connection identifiers to trace/verbose output +Help: Transfer + connection ids in verbose output Added: 8.2.0 Category: verbose Multi: boolean diff --git a/docs/cmdline-opts/write-out.md b/docs/cmdline-opts/write-out.md index 6a75efeaee7..bb1422c99e3 100644 --- a/docs/cmdline-opts/write-out.md +++ b/docs/cmdline-opts/write-out.md @@ -4,7 +4,7 @@ SPDX-License-Identifier: curl Long: write-out Short: w Arg: -Help: Use output FORMAT after completion +Help: Output FORMAT after completion Category: verbose Added: 6.5 Multi: single diff --git a/src/tool_help.c b/src/tool_help.c index 04ac2453707..26ceea3dd1a 100644 --- a/src/tool_help.c +++ b/src/tool_help.c @@ -73,6 +73,11 @@ static const struct category_descriptors categories[] = { {NULL, NULL, CURLHELP_HIDDEN} }; +#ifdef _WIN32 +#define BORDER 78 +#else +#define BORDER 79 +#endif static void print_category(curlhelp_t category) { @@ -91,12 +96,21 @@ static void print_category(curlhelp_t category) if(len > longdesc) longdesc = len; } - if(longopt + longdesc > 80) - longopt = 80 - longdesc; - + if(longopt + longdesc >= BORDER) { + longdesc -= 3; + longopt = BORDER -1 - longdesc; + } for(i = 0; helptext[i].opt; ++i) if(helptext[i].categories & category) { - printf(" %-*s %s\n", (int)longopt, helptext[i].opt, helptext[i].desc); + int opt = (int)longopt; + size_t desclen = strlen(helptext[i].desc); + if(opt + desclen >= (BORDER -1)) { + if(desclen < (BORDER -1)) + opt = (BORDER -2) - (int)desclen; + else + opt = 0; + } + printf(" %-*s %s\n", opt, helptext[i].opt, helptext[i].desc); } } diff --git a/src/tool_listhelp.c b/src/tool_listhelp.c index f2feb27185c..5d936440544 100644 --- a/src/tool_listhelp.c +++ b/src/tool_listhelp.c @@ -45,14 +45,14 @@ const struct helptxt helptext[] = { {"-a, --append", "Append to target file when uploading", CURLHELP_FTP | CURLHELP_SFTP}, - {" --aws-sigv4 ", - "Use AWS V4 signature authentication", + {" --aws-sigv4 ", + "AWS V4 signature auth", CURLHELP_AUTH | CURLHELP_HTTP}, {" --basic", - "Use HTTP Basic Authentication", + "HTTP Basic Authentication", CURLHELP_AUTH}, {" --ca-native", - "Use CA certificates from the native OS", + "Load CA certs from the OS", CURLHELP_TLS}, {" --cacert ", "CA certificate to verify peer against", @@ -64,7 +64,7 @@ const struct helptxt helptext[] = { "Client certificate file and password", CURLHELP_TLS}, {" --cert-status", - "Verify the status of the server cert via OCSP-staple", + "Verify server cert status OCSP-staple", CURLHELP_TLS}, {" --cert-type ", "Certificate type (DER/PEM/ENG/P12)", @@ -81,8 +81,8 @@ const struct helptxt helptext[] = { {"-K, --config ", "Read config from a file", CURLHELP_CURL}, - {" --connect-timeout ", - "Maximum time allowed for connection", + {" --connect-timeout ", + "Maximum time allowed to connect", CURLHELP_CONNECTION}, {" --connect-to ", "Connect to host", @@ -91,10 +91,10 @@ const struct helptxt helptext[] = { "Resumed transfer offset", CURLHELP_CONNECTION}, {"-b, --cookie ", - "Send cookies from string/file", + "Send cookies from string/load from file", CURLHELP_HTTP}, {"-c, --cookie-jar ", - "Write cookies to after operation", + "Save cookies to after operation", CURLHELP_HTTP}, {" --create-dirs", "Create necessary local directory hierarchy", @@ -106,10 +106,10 @@ const struct helptxt helptext[] = { "Convert LF to CRLF in upload", CURLHELP_FTP | CURLHELP_SMTP}, {" --crlfile ", - "Use this CRL list", + "Certificate Revocation list", CURLHELP_TLS}, - {" --curves ", - "(EC) TLS key exchange algorithm(s) to request", + {" --curves ", + "(EC) TLS key exchange algorithms to request", CURLHELP_TLS}, {"-d, --data ", "HTTP POST data", @@ -130,7 +130,7 @@ const struct helptxt helptext[] = { "GSS-API delegation permission", CURLHELP_AUTH}, {" --digest", - "Use HTTP Digest Authentication", + "HTTP Digest Authentication", CURLHELP_PROXY | CURLHELP_AUTH | CURLHELP_HTTP}, {"-q, --disable", "Disable .curlrc", @@ -157,7 +157,7 @@ const struct helptxt helptext[] = { "DNS server addrs to use", CURLHELP_DNS}, {" --doh-cert-status", - "Verify the status of the DoH server cert via OCSP-staple", + "Verify DoH server cert status OCSP-staple", CURLHELP_DNS | CURLHELP_TLS}, {" --doh-insecure", "Allow insecure DoH server connections", @@ -175,10 +175,10 @@ const struct helptxt helptext[] = { "Crypto engine to use", CURLHELP_TLS}, {" --etag-compare ", - "Pass an ETag from a file as a custom header", + "Load ETag from file", CURLHELP_HTTP}, {" --etag-save ", - "Parse ETag from a request and save it to a file", + "Parse incoming ETag and save to a file", CURLHELP_HTTP}, {" --expect100-timeout ", "How long to wait for 100-continue", @@ -187,7 +187,7 @@ const struct helptxt helptext[] = { "Fail fast with no output on HTTP errors", CURLHELP_IMPORTANT | CURLHELP_HTTP}, {" --fail-early", - "Fail on first transfer error, do not continue", + "Fail on first transfer error", CURLHELP_CURL}, {" --fail-with-body", "Fail on HTTP errors but save the body", @@ -199,7 +199,7 @@ const struct helptxt helptext[] = { "Specify multipart MIME data", CURLHELP_HTTP | CURLHELP_UPLOAD}, {" --form-escape", - "Escape multipart form field/filenames using backslash", + "Escape form fields using backslash", CURLHELP_HTTP | CURLHELP_UPLOAD}, {" --form-string ", "Specify multipart MIME data", @@ -217,10 +217,10 @@ const struct helptxt helptext[] = { "Control CWD usage", CURLHELP_FTP}, {" --ftp-pasv", - "Use PASV/EPSV instead of PORT", + "Send PASV/EPSV instead of PORT", CURLHELP_FTP}, {"-P, --ftp-port
", - "Use PORT instead of PASV", + "Send PORT instead of PASV", CURLHELP_FTP}, {" --ftp-pret", "Send PRET before PASV", @@ -235,19 +235,19 @@ const struct helptxt helptext[] = { "Set CCC mode", CURLHELP_FTP | CURLHELP_TLS}, {" --ftp-ssl-control", - "Require SSL/TLS for FTP login, clear for transfer", + "Require TLS for login, clear for transfer", CURLHELP_FTP | CURLHELP_TLS}, {"-G, --get", "Put the post data in the URL and use GET", CURLHELP_HTTP | CURLHELP_UPLOAD}, {"-g, --globoff", - "Disable URL sequences and ranges using {} and []", + "Disable URL globbing with {} and []", CURLHELP_CURL}, - {" --happy-eyeballs-timeout-ms ", - "Time for IPv6 before trying IPv4", + {" --happy-eyeballs-timeout-ms ", + "Time for IPv6 before IPv4", CURLHELP_CONNECTION}, - {" --haproxy-clientip ", - "Sets client IP in HAProxy PROXY protocol v1 header", + {" --haproxy-clientip ", + "Set address in HAProxy PROXY", CURLHELP_HTTP | CURLHELP_PROXY}, {" --haproxy-protocol", "Send HAProxy PROXY protocol v1 header", @@ -262,10 +262,10 @@ const struct helptxt helptext[] = { "Get help for commands", CURLHELP_IMPORTANT | CURLHELP_CURL}, {" --hostpubmd5 ", - "Acceptable MD5 hash of the host public key", + "Acceptable MD5 hash of host public key", CURLHELP_SFTP | CURLHELP_SCP}, {" --hostpubsha256 ", - "Acceptable SHA256 hash of the host public key", + "Acceptable SHA256 hash of host public key", CURLHELP_SFTP | CURLHELP_SCP}, {" --hsts ", "Enable HSTS with this cache file", @@ -295,7 +295,7 @@ const struct helptxt helptext[] = { "Ignore the size of the remote resource", CURLHELP_HTTP | CURLHELP_FTP}, {"-i, --include", - "Include protocol response headers in the output", + "Include response headers in output", CURLHELP_IMPORTANT | CURLHELP_VERBOSE}, {"-k, --insecure", "Allow insecure server connections", @@ -331,7 +331,7 @@ const struct helptxt helptext[] = { "Enable Kerberos with security ", CURLHELP_FTP}, {" --libcurl ", - "Dump libcurl equivalent code of this command line", + "Generate libcurl code for this command line", CURLHELP_CURL}, {" --limit-rate ", "Limit transfer speed to RATE", @@ -339,14 +339,14 @@ const struct helptxt helptext[] = { {"-l, --list-only", "List only mode", CURLHELP_FTP | CURLHELP_POP3 | CURLHELP_SFTP}, - {" --local-port ", - "Force use of RANGE for local port numbers", + {" --local-port ", + "Use a local port number within RANGE", CURLHELP_CONNECTION}, {"-L, --location", "Follow redirects", CURLHELP_HTTP}, {" --location-trusted", - "Like --location, and send auth to other hosts", + "Like --location, but send auth to other hosts", CURLHELP_HTTP | CURLHELP_AUTH}, {" --login-options ", "Server login options", @@ -361,7 +361,7 @@ const struct helptxt helptext[] = { "Mail to this address", CURLHELP_SMTP}, {" --mail-rcpt-allowfails", - "Allow RCPT TO command to fail for some recipients", + "Allow RCPT TO command to fail", CURLHELP_SMTP}, {"-M, --manual", "Display the full manual", @@ -372,7 +372,7 @@ const struct helptxt helptext[] = { {" --max-redirs ", "Maximum number of redirects allowed", CURLHELP_HTTP}, - {"-m, --max-time ", + {"-m, --max-time ", "Maximum time allowed for transfer", CURLHELP_CONNECTION}, {" --metalink", @@ -418,10 +418,10 @@ const struct helptxt helptext[] = { "List of hosts which do not use proxy", CURLHELP_PROXY}, {" --ntlm", - "Use HTTP NTLM authentication", + "HTTP NTLM authentication", CURLHELP_AUTH | CURLHELP_HTTP}, {" --ntlm-wb", - "Use HTTP NTLM authentication with winbind", + "HTTP NTLM authentication with winbind", CURLHELP_AUTH | CURLHELP_HTTP}, {" --oauth2-bearer ", "OAuth 2 Bearer Token", @@ -451,13 +451,13 @@ const struct helptxt helptext[] = { "FILE/HASHES Public key to verify peer against", CURLHELP_TLS}, {" --post301", - "Do not switch to GET after following a 301", + "Do not switch to GET after a 301 redirect", CURLHELP_HTTP | CURLHELP_POST}, {" --post302", - "Do not switch to GET after following a 302", + "Do not switch to GET after a 302 redirect", CURLHELP_HTTP | CURLHELP_POST}, {" --post303", - "Do not switch to GET after following a 303", + "Do not switch to GET after a 303 redirect", CURLHELP_HTTP | CURLHELP_POST}, {" --preproxy [protocol://]host[:port]", "Use this proxy first", @@ -484,13 +484,13 @@ const struct helptxt helptext[] = { "Use Basic authentication on the proxy", CURLHELP_PROXY | CURLHELP_AUTH}, {" --proxy-ca-native", - "Use CA certificates from the native OS for proxy", + "Load CA certs from the OS to verify proxy", CURLHELP_TLS}, {" --proxy-cacert ", - "CA certificate to verify peer against for proxy", + "CA certificates to verify proxy against", CURLHELP_PROXY | CURLHELP_TLS}, {" --proxy-capath ", - "CA directory to verify peer against for proxy", + "CA directory to verify proxy against", CURLHELP_PROXY | CURLHELP_TLS}, {" --proxy-cert ", "Set client certificate for proxy", @@ -505,7 +505,7 @@ const struct helptxt helptext[] = { "Set a CRL list for proxy", CURLHELP_PROXY | CURLHELP_TLS}, {" --proxy-digest", - "Use Digest authentication on the proxy", + "Digest auth with the proxy", CURLHELP_PROXY | CURLHELP_TLS}, {" --proxy-header
", "Pass custom header(s) to proxy", @@ -514,7 +514,7 @@ const struct helptxt helptext[] = { "Use HTTP/2 with HTTPS proxy", CURLHELP_HTTP | CURLHELP_PROXY}, {" --proxy-insecure", - "Do HTTPS proxy connections without verifying the proxy", + "Skip HTTPS proxy cert verification", CURLHELP_PROXY | CURLHELP_TLS}, {" --proxy-key ", "Private key for HTTPS proxy", @@ -523,10 +523,10 @@ const struct helptxt helptext[] = { "Private key file type for proxy", CURLHELP_PROXY | CURLHELP_TLS}, {" --proxy-negotiate", - "Use HTTP Negotiate (SPNEGO) authentication on the proxy", + "HTTP Negotiate (SPNEGO) auth with the proxy", CURLHELP_PROXY | CURLHELP_AUTH}, {" --proxy-ntlm", - "Use NTLM authentication on the proxy", + "NTLM authentication with the proxy", CURLHELP_PROXY | CURLHELP_AUTH}, {" --proxy-pass ", "Pass phrase for the private key for HTTPS proxy", @@ -541,7 +541,7 @@ const struct helptxt helptext[] = { "Allow security flaw for interop for HTTPS proxy", CURLHELP_PROXY | CURLHELP_TLS}, {" --proxy-ssl-auto-client-cert", - "Use auto client certificate for proxy (Schannel)", + "Auto client certificate for proxy", CURLHELP_PROXY | CURLHELP_TLS}, {" --proxy-tls13-ciphers ", "TLS 1.3 proxy cipher suites", @@ -556,7 +556,7 @@ const struct helptxt helptext[] = { "TLS username for HTTPS proxy", CURLHELP_PROXY | CURLHELP_TLS | CURLHELP_AUTH}, {" --proxy-tlsv1", - "Use TLSv1 for HTTPS proxy", + "TLSv1 for HTTPS proxy", CURLHELP_PROXY | CURLHELP_TLS | CURLHELP_AUTH}, {"-U, --proxy-user ", "Proxy user and password", @@ -565,7 +565,7 @@ const struct helptxt helptext[] = { "Use HTTP/1.0 proxy on given port", CURLHELP_PROXY}, {"-p, --proxytunnel", - "Operate through an HTTP proxy tunnel (using CONNECT)", + "HTTP proxy tunnel (using CONNECT)", CURLHELP_PROXY}, {" --pubkey ", "SSH Public key filename", @@ -592,13 +592,13 @@ const struct helptxt helptext[] = { "Use the header-provided filename", CURLHELP_OUTPUT}, {"-O, --remote-name", - "Write output to a file named as the remote file", + "Write output to file named as remote file", CURLHELP_IMPORTANT | CURLHELP_OUTPUT}, {" --remote-name-all", "Use the remote filename for all URLs", CURLHELP_OUTPUT}, {"-R, --remote-time", - "Set the remote file's time on the local output", + "Set remote file's time on local output", CURLHELP_OUTPUT}, {" --remove-on-error", "Remove output file on errors", @@ -610,16 +610,16 @@ const struct helptxt helptext[] = { "Specify the target for this request", CURLHELP_HTTP}, {" --resolve <[+]host:port:addr[,addr]...>", - "Resolve the host+port to this address", + "Resolve host+port to address", CURLHELP_CONNECTION | CURLHELP_DNS}, {" --retry ", "Retry request if transient problems occur", CURLHELP_CURL}, {" --retry-all-errors", - "Retry all errors (use with --retry)", + "Retry all errors (with --retry)", CURLHELP_CURL}, {" --retry-connrefused", - "Retry on connection refused (use with --retry)", + "Retry on connection refused (with --retry)", CURLHELP_CURL}, {" --retry-delay ", "Wait time between retries", @@ -631,7 +631,7 @@ const struct helptxt helptext[] = { "Identity for SASL PLAIN authentication", CURLHELP_AUTH}, {" --sasl-ir", - "Enable initial response in SASL authentication", + "Initial response in SASL authentication", CURLHELP_AUTH}, {" --service-name ", "SPNEGO service name", @@ -652,7 +652,7 @@ const struct helptxt helptext[] = { "SOCKS5 proxy on given host + port", CURLHELP_PROXY}, {" --socks5-basic", - "Enable username/password auth for SOCKS5 proxies", + "Username/password auth for SOCKS5 proxies", CURLHELP_PROXY | CURLHELP_AUTH}, {" --socks5-gssapi", "Enable GSS-API auth for SOCKS5 proxies", @@ -673,7 +673,7 @@ const struct helptxt helptext[] = { "Trigger 'speed-limit' abort after this time", CURLHELP_CONNECTION}, {" --ssl", - "Try SSL/TLS", + "Try enabling TLS", CURLHELP_TLS}, {" --ssl-allow-beast", "Allow security flaw to improve interop", @@ -688,13 +688,13 @@ const struct helptxt helptext[] = { "Require SSL/TLS", CURLHELP_TLS}, {" --ssl-revoke-best-effort", - "Ignore missing/offline cert CRL dist points (Schannel)", + "Ignore missing cert CRL dist points", CURLHELP_TLS}, {"-2, --sslv2", - "Use SSLv2", + "SSLv2", CURLHELP_TLS}, {"-3, --sslv3", - "Use SSLv3", + "SSLv3", CURLHELP_TLS}, {" --stderr ", "Where to redirect stderr", @@ -709,7 +709,7 @@ const struct helptxt helptext[] = { "Use TCP Fast Open", CURLHELP_CONNECTION}, {" --tcp-nodelay", - "Use the TCP_NODELAY option", + "Set TCP_NODELAY", CURLHELP_CONNECTION}, {"-t, --telnet-option ", "Set telnet option", @@ -724,9 +724,9 @@ const struct helptxt helptext[] = { "Transfer based on a time condition", CURLHELP_HTTP | CURLHELP_FTP}, {" --tls-max ", - "Set maximum allowed TLS version", + "Maximum allowed TLS version", CURLHELP_TLS}, - {" --tls13-ciphers ", + {" --tls13-ciphers ", "TLS 1.3 cipher suites to use", CURLHELP_TLS}, {" --tlsauthtype ", @@ -739,19 +739,19 @@ const struct helptxt helptext[] = { "TLS username", CURLHELP_TLS | CURLHELP_AUTH}, {"-1, --tlsv1", - "Use TLSv1.0 or greater", + "TLSv1.0 or greater", CURLHELP_TLS}, {" --tlsv1.0", - "Use TLSv1.0 or greater", + "TLSv1.0 or greater", CURLHELP_TLS}, {" --tlsv1.1", - "Use TLSv1.1 or greater", + "TLSv1.1 or greater", CURLHELP_TLS}, {" --tlsv1.2", - "Use TLSv1.2 or greater", + "TLSv1.2 or greater", CURLHELP_TLS}, {" --tlsv1.3", - "Use TLSv1.3 or greater", + "TLSv1.3 or greater", CURLHELP_TLS}, {" --tr-encoding", "Request compressed transfer encoding", @@ -766,7 +766,7 @@ const struct helptxt helptext[] = { "Details to log in trace/verbose output", CURLHELP_VERBOSE}, {" --trace-ids", - "Add transfer and connection identifiers to trace/verbose output", + "Transfer + connection ids in verbose output", CURLHELP_VERBOSE}, {" --trace-time", "Add time stamps to trace/verbose output", @@ -802,7 +802,7 @@ const struct helptxt helptext[] = { "Show version number and quit", CURLHELP_IMPORTANT | CURLHELP_CURL}, {"-w, --write-out ", - "Use output FORMAT after completion", + "Output FORMAT after completion", CURLHELP_VERBOSE}, {" --xattr", "Store metadata in extended file attributes", diff --git a/tests/data/test1461 b/tests/data/test1461 index e25e29f39e6..424af943fc9 100644 --- a/tests/data/test1461 +++ b/tests/data/test1461 @@ -32,18 +32,18 @@ curl important --help Usage: curl [options...] - -d, --data HTTP POST data - -f, --fail Fail fast with no output on HTTP errors - -h, --help Get help for commands - -i, --include Include protocol response headers in the output - -o, --output Write to file instead of stdout - -O, --remote-name Write output to a file named as the remote file - -s, --silent Silent mode - -T, --upload-file Transfer local FILE to destination - -u, --user Server user and password - -A, --user-agent Send User-Agent to server - -v, --verbose Make the operation more talkative - -V, --version Show version number and quit + -d, --data HTTP POST data + -f, --fail Fail fast with no output on HTTP errors + -h, --help Get help for commands + -i, --include Include response headers in output + -o, --output Write to file instead of stdout + -O, --remote-name Write output to file named as remote file + -s, --silent Silent mode + -T, --upload-file Transfer local FILE to destination + -u, --user Server user and password + -A, --user-agent Send User-Agent to server + -v, --verbose Make the operation more talkative + -V, --version Show version number and quit This is not the full help, this menu is stripped into categories. Use "--help category" to get an overview of all categories. diff --git a/tests/data/test1463 b/tests/data/test1463 index c59ac552b81..254b51b2227 100644 --- a/tests/data/test1463 +++ b/tests/data/test1463 @@ -37,9 +37,9 @@ curl file category --help Usage: curl [options...] file: FILE protocol options - --create-file-mode File mode for created files - -I, --head Show document info only - -r, --range Retrieve only the bytes within RANGE + --create-file-mode File mode for created files + -I, --head Show document info only + -r, --range Retrieve only the bytes within RANGE diff --git a/tests/data/test1464 b/tests/data/test1464 index 091933df2d4..6a0af34c29a 100644 --- a/tests/data/test1464 +++ b/tests/data/test1464 @@ -37,9 +37,9 @@ curl file category --help with lower/upper mix Usage: curl [options...] file: FILE protocol options - --create-file-mode File mode for created files - -I, --head Show document info only - -r, --range Retrieve only the bytes within RANGE + --create-file-mode File mode for created files + -I, --head Show document info only + -r, --range Retrieve only the bytes within RANGE From 0aaea582e0ec2a610457bad3584344e443f4b4fa Mon Sep 17 00:00:00 2001 From: Fabian Keil Date: Sun, 17 Mar 2024 14:30:33 +0100 Subject: [PATCH 499/509] wolfSSL: do not call the stub function wolfSSL_BIO_set_init() Calling the function isn't necessary and causes the build to fail when wolfSSL has been compiled with NO_WOLFSSL_STUB: Making all in opts CCLD curl ld: error: undefined symbol: wolfSSL_BIO_set_init >>> referenced by wolfssl.c:235 (vtls/wolfssl.c:235) >>> libcurl_la-wolfssl.o:(wolfssl_bio_cf_create) in archive ../lib/.libs/libcurl.a cc: error: linker command failed with exit code 1 (use -v to see invocation) *** Error code 1 Closes #13164 --- lib/vtls/wolfssl.c | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/vtls/wolfssl.c b/lib/vtls/wolfssl.c index c264639bacd..3187bb8df79 100644 --- a/lib/vtls/wolfssl.c +++ b/lib/vtls/wolfssl.c @@ -232,7 +232,6 @@ static const struct group_name_map gnm[] = { static int wolfssl_bio_cf_create(WOLFSSL_BIO *bio) { wolfSSL_BIO_set_shutdown(bio, 1); - wolfSSL_BIO_set_init(bio, 1); wolfSSL_BIO_set_data(bio, NULL); return 1; } From 57656835ec198a218a415698337033c891cdcb45 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 23 Mar 2024 14:43:35 +0100 Subject: [PATCH 500/509] DISTROS: add document with distro pointers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. Assisted-by: Alan Coopersmith Assisted-by: Andrew Kaster Assisted-by: Andy Fiddaman Assisted-by: Arjan van de Ven Assisted-by: Brian Clemens Assisted-by: chrysos349 on github Assisted-by: Dan Fandrich Assisted-by: Dan McDonald Assisted-by: Gaelan Steele Assisted-by: graywolf on github Assisted-by: Jan Macku Assisted-by: John Marshall Assisted-by: Jonathan Perkin Assisted-by: Kevin Daudt Assisted-by: Marcus Müller Assisted-by: Michał Górny Assisted-by: Outvi V Assisted-by: Ross Burton Assisted-by: Sean Molenaar Assisted-by: Till Wegmüller Assisted-by: Viktor Szakats Assisted-by: Winni Neessen Closes #13178 --- .github/scripts/spellcheck.yaml | 2 +- .github/workflows/proselint.yml | 2 +- docs/DISTROS.md | 233 ++++++++++++++++++++++++++++++++ docs/Makefile.am | 1 + 4 files changed, 236 insertions(+), 2 deletions(-) create mode 100644 docs/DISTROS.md diff --git a/.github/scripts/spellcheck.yaml b/.github/scripts/spellcheck.yaml index 5cf4f9a016a..97d5d33053a 100644 --- a/.github/scripts/spellcheck.yaml +++ b/.github/scripts/spellcheck.yaml @@ -29,4 +29,4 @@ matrix: - 'strong' - 'em' sources: - - '**/*.md|!docs/BINDINGS.md' + - '**/*.md|!docs/BINDINGS.md|!docs/DISTROS.md' diff --git a/.github/workflows/proselint.yml b/.github/workflows/proselint.yml index 87126672224..4a0ae6f1f49 100644 --- a/.github/workflows/proselint.yml +++ b/.github/workflows/proselint.yml @@ -49,7 +49,7 @@ jobs: JSON - name: check prose - run: a=`git ls-files '*.md' | grep -v docs/CHECKSRC.md` && proselint $a README + 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 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/Makefile.am b/docs/Makefile.am index 3fadb765f5c..ca7b0833434 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -61,6 +61,7 @@ EXTRA_DIST = \ CURL-DISABLE.md \ CURLDOWN.md \ DEPRECATE.md \ + DISTROS.md \ DYNBUF.md \ EARLY-RELEASE.md \ EXPERIMENTAL.md \ From 47da1f289c276bec34d40d0ab7f634ad7b9a7659 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 26 Mar 2024 00:32:56 +0100 Subject: [PATCH 501/509] http: remove stale comment about rewindbeforesend ... because that struct field exists no more. Follow-up to 14bcea074a782272. Closes #13187 --- lib/http.c | 2 -- 1 file changed, 2 deletions(-) diff --git a/lib/http.c b/lib/http.c index 4de0e8e4403..92c04e69cd8 100644 --- a/lib/http.c +++ b/lib/http.c @@ -3557,8 +3557,6 @@ static CURLcode http_on_response(struct Curl_easy *data, * something else should've considered the big picture and we * avoid this check. * - * rewindbeforesend indicates that something has told libcurl to - * continue sending even if it gets discarded */ switch(data->state.httpreq) { From 1b2978403fe3f62f14102613417c92f74c137ec0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 26 Mar 2024 10:56:08 +0100 Subject: [PATCH 502/509] CURLOPT_POSTFIELDS.md: used for MQTT as well Closes #13189 --- docs/libcurl/opts/CURLOPT_POSTFIELDS.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md index 8dc30483582..11f64d7f790 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.md +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.md @@ -12,6 +12,7 @@ See-also: - CURLOPT_UPLOAD (3) Protocol: - HTTP + - MQTT --- # NAME @@ -29,9 +30,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata); # DESCRIPTION Pass a char pointer as parameter, pointing to the data buffer to use in an -HTTP POST operation. The data must be formatted and encoded the way you want -the server to receive it. libcurl does not convert or encode it in any -way. For example, the web server may assume that this data is URL encoded. +HTTP POST operation or an MQTT subscribe. The data must be formatted and +encoded the way you want the server to receive it. libcurl does not convert or +encode it in any way. For example, a web server may assume that this data is +URL encoded. The data pointed to is NOT copied by the library: as a consequence, it must be preserved by the calling application until the associated transfer finishes. @@ -49,10 +51,10 @@ necessary. It returns a pointer to an encoded string that can be passed as Using CURLOPT_POSTFIELDS(3) implies setting CURLOPT_POST(3) to 1. -If CURLOPT_POSTFIELDS(3) is explicitly set to NULL then libcurl gets the -POST data from the read callback. If you want to send a zero-byte POST set -CURLOPT_POSTFIELDS(3) to an empty string, or set CURLOPT_POST(3) -to 1 and CURLOPT_POSTFIELDSIZE(3) to 0. +If CURLOPT_POSTFIELDS(3) is explicitly set to NULL then libcurl gets the POST +data from the read callback. To send a zero-length (empty) POST, set +CURLOPT_POSTFIELDS(3) to an empty string, or set CURLOPT_POST(3) to 1 and +CURLOPT_POSTFIELDSIZE(3) to 0. libcurl assumes this option points to a null-terminated string unless you also set CURLOPT_POSTFIELDSIZE(3) to specify the length of the provided data, From b447a77502597a7e434d5fae803439d1e8cf5520 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Mar 2024 07:46:15 +0100 Subject: [PATCH 503/509] THANKS: new contributors from the 8.7.0 release --- docs/THANKS | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/docs/THANKS b/docs/THANKS index 84f3520a37e..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 @@ -53,6 +54,7 @@ Akos Pasztory Akshay Vernekar Alain Danteny Alain Miniussi +Alan Coopersmith Alan Jenkins Alan Pinstein Albert Chin-A-Young @@ -156,6 +158,7 @@ Andreas Falkenhahn Andreas Farber Andreas Fischer Andreas Huebner +Andreas Kiefer Andreas Kostyrka Andreas Malzahn Andreas Ntaflos @@ -187,6 +190,7 @@ Andrew de los Reyes Andrew Francis Andrew Fuller Andrew Ishchuk +Andrew Kaster Andrew Krieger Andrew Kurushin Andrew Lambert @@ -239,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 @@ -263,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 @@ -379,12 +386,14 @@ 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 @@ -454,6 +463,7 @@ Charles Kerr Charles Romestant Charlie C Chen Prog +chensong1211 on github Cherish98 on github Chester Liu Chih-Chung Chang @@ -476,6 +486,7 @@ Chris Roberts Chris Sauer Chris Smowton Chris Talbot +Chris Webb Chris Young Christian Fillion Christian Grothoff @@ -503,6 +514,7 @@ Christopher R. Palmer Christopher Reid Christopher Sauer Christopher Stone +chrysos349 on github Chungtsun Li Ciprian Badescu civodul on github @@ -576,6 +588,7 @@ Dan Fandrich Dan Johnson Dan Kenigsberg Dan Locks +Dan McDonald Dan McNulty Dan Nelson Dan Petitt @@ -609,6 +622,7 @@ Daniel Shahaf Daniel Silverstone Daniel Steinberg Daniel Stenberg +Daniel Szmulewicz Daniel Theron Daniel Valenzuela Daniel Woelfel @@ -619,6 +633,7 @@ Darryl House Darshan Mody Darío Hereñú dasimx on github +DasKutti on github Dave Cottlehuber Dave Dribin Dave Halbakken @@ -690,12 +705,13 @@ Denis Laxalde Denis Ollier Dennis Clarke Dennis Felsing -dependabot[bot] Derek Higgins Derzsi Dániel Desmond O. Chang destman on github Detlef Schmier +Dexter Gerig +dfdity on github Dheeraj Sangamkar Didier Brisebourg Diego Bes @@ -715,6 +731,7 @@ Diogo Teles Sant'Anna Dion Williams Dirk Eddelbuettel Dirk Feytons +Dirk Hünniger Dirk Manske Dirk Rosenkranz Dirk Wetter @@ -790,6 +807,7 @@ ed0d2b2ce19451f2 Eddie Lumpkin Edgaras Janušauskas Edin Kadribasic +edmcln on github Edmond Yu Edoardo Lolletti Eduard Bloch @@ -862,6 +880,7 @@ Erik Janssen Erik Johansson Erik Minekus Erik Olsson +Erik Schnetter Erik Stenlund Ernest Beinrohr Ernst Sjöstrand @@ -886,6 +905,7 @@ Fabian Frank Fabian Hiernaux Fabian Keil Fabian Ruff +Fabian Vogt Fabian Yamaguchi Fabrice Fontaine Fabrizio Ammollo @@ -959,6 +979,7 @@ Gabriel Corona Gabriel Kuri Gabriel Simmer Gabriel Sjoberg +Gaelan Steele Gambit Communications Ganesh Kamath gaoxingwang on github @@ -1020,6 +1041,7 @@ Gou Lingfeng Graham Campbell Grant Erickson Grant Pannell +graywolf on github Greg Hewgill Greg Morse Greg Onufer @@ -1113,6 +1135,7 @@ Hongyi Zhao Howard Blaise Howard Chu hsiao yi +HsiehYuho on github htasta on github Hubert Kario Hugh Macdonald @@ -1314,6 +1337,7 @@ Jesse Noller Jesse Tan jethrogb on github jhoyla on github +Jiawen Geng Jie He Jiehong on github Jilayne Lovejoy @@ -1329,6 +1353,7 @@ Jiri Dvorak Jiri Hruska Jiri Jaburek Jishan Shaikh +Jiří Bok Jiří Malák jmdavitt on github jnbr on github @@ -1418,6 +1443,7 @@ Jonathan Cardoso Machado Jonathan Hseu Jonathan Moerman Jonathan Nieder +Jonathan Perkin Jonathan Watt Jonathan Wernberg Jongki Suwandi @@ -1538,6 +1564,7 @@ Kev Jackson Kevin Adler Kevin Baughman Kevin Burke +Kevin Daudt Kevin Fisk Kevin Ji Kevin Lussier @@ -1565,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 @@ -1608,6 +1637,7 @@ Lars Francke Lars Gustafsson Lars J. Aas Lars Johannesen +Lars Kellogg-Stedman Lars Nilsson Lars Torben Wilson Lau @@ -1622,6 +1652,7 @@ Lawrence Wagerfield Leah Neukirchen Lealem Amedie Leandro Coutinho +LeeRiva Legoff Vincent Lehel Bernadt Leif W @@ -1668,6 +1699,7 @@ Loic Dachary LoRd_MuldeR Loren Kirkby Lorenzo Miniero +Louis Solofrizzo Loïc Yhuel lRoccoon on github Luan Cestari @@ -1692,6 +1724,7 @@ Luke Amery Luke Call Luke Dashjr Luke Granger-Brown +Lukáš Zaoral luminixinc on github Luo Jinghua Luong Dinh Dung @@ -1748,6 +1781,7 @@ Marco Maggi Marcos Diazr Marcus Hoffmann Marcus Klein +Marcus Müller Marcus Sundberg Marcus T Marcus Webster @@ -2062,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 @@ -2134,6 +2169,7 @@ Oscar Norlander Oskar Liljeblad Oskar Sigvardsson Oumph on github +Outvi V ovidiu-benea on github Ozan Cansel P R Schaffner @@ -2200,6 +2236,7 @@ Pawel A. Gajda Pawel Kierski Paweł Kowalski Paweł Wegner +Paweł Witas PBudmark on github Pedro Henrique Pedro Larroy @@ -2221,6 +2258,7 @@ Peter Goodman Peter Heuchert Peter Hjalmarsson Peter Korsgaard +Peter Krefting Peter Körner Peter Lamare Peter Lamberg @@ -2295,6 +2333,7 @@ pszemus on github pszlazak on github puckipedia on github Puneet Pawaia +Pēteris Caune qiandu2006 on github Quagmire Quanah Gibson-Mount @@ -2317,6 +2356,7 @@ Rainer Canavan Rainer Jung Rainer Koenig Rainer Müller +RainRat Raito Bezarius Rajesh Naganathan Rajkumar Mandal @@ -2325,6 +2365,7 @@ Ralph Beckmann Ralph Langendam Ralph Mitchell Ram Krushna Mishra +Ramiro Garcia ramsay-jones on github Ran Mozes RanBarLavie on github @@ -2430,6 +2471,7 @@ Robert Foreman Robert Iakobashvili Robert Kolcun Robert Linden +Robert Moreton Robert Olson Robert Prag Robert Ronto @@ -2478,6 +2520,7 @@ roughtex on github Roy Bellingan Roy Li Roy Shan +Rudi Heitbaum Rui LIU Rui Pinheiro Rune Kleveland @@ -2490,6 +2533,7 @@ RuurdBeerstra on github rwmjones on github Ryan Beck-Buysse Ryan Braud +Ryan Carsten Schmidt Ryan Chan Ryan Mast Ryan Nelson @@ -2547,6 +2591,8 @@ Scott Barrett Scott Cantor Scott Davis Scott McCreary +Scott Mutter +Scott Talbert sd0 on hackerone Sean Boudreau Sean Burford @@ -2557,6 +2603,7 @@ Sean Molenaar Sebastiaan van Erk Sebastian Haglund Sebastian Mundry +Sebastian Neubauer Sebastian Pohlschmidt Sebastian Rasmussen Sebastian Sterk @@ -2620,6 +2667,7 @@ Simon Chalifoux Simon Dick Simon H. Simon Josefsson +Simon K Simon Legner Simon Liu Simon Warta @@ -2733,6 +2781,7 @@ T200proX7 on github Tadej Vengust Tae Hyoung Ahn Taiyu Len +Tal Regev Taneli Vähäkangas Tanguy Fautre Taras Kushnir @@ -2768,6 +2817,7 @@ Thomas L. Shinnick Thomas Lopatic Thomas M. DuBuisson Thomas Petazzoni +Thomas Pyle Thomas Ruecker Thomas Schwinge Thomas Taylor @@ -2780,6 +2830,7 @@ Thorsten Klein Thorsten Schöning Tiit Pikma Till Maas +Till Wegmüller Tim Ansell Tim Baker Tim Bartley @@ -2950,6 +3001,7 @@ Vojtěch Král Volker Schmid Vsevolod Novikov vshmuk on hackerone +vulnerabilityspotter on hackerone vvb2060 vvb2060 on github Vyron Tsingaras @@ -2983,6 +3035,7 @@ William A. Rowe Jr William Ahern William Desportes William Tang +Winni Neessen wmsch on github wncboy on github Wojciech Zwiefka From 72cf468d459d29e5366e416c014faaaf281dfa2d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Mar 2024 07:46:15 +0100 Subject: [PATCH 504/509] RELEASE-NOTES: synced curl 8.7.0 release --- RELEASE-NOTES | 67 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 18 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index aa7038ebd1a..620578ab34c 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -4,7 +4,7 @@ curl and libcurl 8.7.0 Command line options: 258 curl_easy_setopt() options: 304 Public functions in libcurl: 93 - Contributors: 3120 + Contributors: 3134 This release includes the following changes: @@ -38,12 +38,14 @@ This release includes the following bugfixes: 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 configure.ac: find libpsl with pkg-config [79] + 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] @@ -53,17 +55,22 @@ This release includes the following bugfixes: 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] @@ -83,14 +90,18 @@ This release includes the following bugfixes: 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] @@ -149,6 +160,7 @@ This release includes the following bugfixes: 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] @@ -164,6 +176,7 @@ This release includes the following bugfixes: 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: @@ -179,24 +192,29 @@ Planned upcoming removals include: This release would not have looked like this without help, code, reports and advice from friends like these: - 5533asdg on github, Andreas Kiefer, av223119 on github, - awesomekosm on github, Boris Verkhovskiy, Brett Buddin, - chensong1211 on github, Chris Webb, Dan Fandrich, Daniel Gustafsson, - Daniel Stenberg, Daniel Szmulewicz, 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 Vogt, Fabrice Fontaine, Faraz Fallahi, Geeknik Labs, Gisle Vanem, + 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, Jon Rumsey, Jordan Brown, Josh Soref, Karthikdasari0423, - Karthikdasari0423 on github, Konstantin Vlasov, kpcyrd, Lars Kellogg-Stedman, - LeeRiva, Louis Solofrizzo, Lukáš Zaoral, Marcel Raad, Michael Forney, - Michael Kaufmann, Michał Antoniak, Nikita Taranov, Patrick Monnerat, - Paweł Witas, Pēteris Caune, Peter Krefting, RainRat, Ramiro Garcia, - Ray Satiro, Richard Levitte, Robert Moreton, Rudi Heitbaum, - Ryan Carsten Schmidt, Scott Mutter, Scott Talbert, Sebastian Neubauer, + 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, - Viktor Szakats, vulnerabilityspotter on hackerone - (70 contributors) + Till Wegmüller, Viktor Szakats, vulnerabilityspotter on hackerone, + Winni Neessen + (92 contributors) References to bug reports and discussions on issues: @@ -335,6 +353,7 @@ References to bug reports and discussions on issues: [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 @@ -342,7 +361,19 @@ References to bug reports and discussions on issues: [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 From de7b3e89218467159a7af72d58cea8425946e97d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Mar 2024 08:11:20 +0100 Subject: [PATCH 505/509] RELEASE-PROCEDURE: remove old release dates, add new pending ones --- docs/RELEASE-PROCEDURE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/RELEASE-PROCEDURE.md b/docs/RELEASE-PROCEDURE.md index 2b5cbb88061..e48a4d28a22 100644 --- a/docs/RELEASE-PROCEDURE.md +++ b/docs/RELEASE-PROCEDURE.md @@ -106,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 From 022da4d64c6a60da18a141a03da4d3a7591e39fe Mon Sep 17 00:00:00 2001 From: Yifei Kong Date: Sun, 28 Apr 2024 22:15:55 +0800 Subject: [PATCH 506/509] WIP: save at 2024-04-28 22:15:55 --- export.sh | 2 +- lib/easy.c | 5 ++++- lib/http2.c | 4 +++- lib/impersonate.c | 5 +++++ 4 files changed, 13 insertions(+), 3 deletions(-) diff --git a/export.sh b/export.sh index 34b44cd2aae..c237ee2ada8 100755 --- a/export.sh +++ b/export.sh @@ -1,4 +1,4 @@ #!/bin/bash -git df curl-8_5_0 > chrome.patch +git df curl-8_7_1 > chrome.patch mv chrome.patch ../curl-impersonate/chrome/patches/curl-impersonate.patch diff --git a/lib/easy.c b/lib/easy.c index 7a12d9c4d68..ac45a7da38f 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -485,6 +485,10 @@ CURLcode _do_impersonate(struct Curl_easy *data, ret = curl_easy_setopt(data, CURLOPT_TLS_EXTENSION_ORDER, opts->tls_extension_order); } + if(opts->http2_stream_weight) { + ret = curl_easy_setopt(data, CURLOPT_STREAM_WEIGHT, opts->http2_stream_weight); + } + /* Always enable all supported compressions. */ ret = curl_easy_setopt(data, CURLOPT_ACCEPT_ENCODING, ""); if(ret) @@ -1274,7 +1278,6 @@ void curl_easy_reset(struct Curl_easy *data) char *env_target; char *env_headers; - Curl_free_request_state(data); Curl_req_hard_reset(&data->req, data); /* zero out UserDefined data: */ diff --git a/lib/http2.c b/lib/http2.c index 9bf0653d78b..324a12fffa5 100644 --- a/lib/http2.c +++ b/lib/http2.c @@ -1876,7 +1876,8 @@ static ssize_t http2_handle_stream_close(struct Curl_cfilter *cf, * instead of NGINX default stream weight. */ #define CHROME_DEFAULT_STREAM_WEIGHT (256) -#define FIREFOX_DEFAULT_STREAM_WEIGHT (42) +#define SAFARI_DEFAULT_STREAM_WEIGHT (255) +#define FIREFOX_DEFAULT_STREAM_WEIGHT (42) static int sweight_wanted(const struct Curl_easy *data) { @@ -1913,6 +1914,7 @@ static void h2_pri_spec(struct Curl_easy *data, struct h2_stream_ctx *depstream = H2_STREAM_CTX(prio->parent); int32_t depstream_id = depstream? depstream->id:0; // int32_t depstream_id = depstream? depstream->id:FIREFOX_DEFAULT_STREAM_DEP; + /* curl-impersonate: Set stream exclusive flag to true. */ int exclusive = 1; nghttp2_priority_spec_init(pri_spec, depstream_id, diff --git a/lib/impersonate.c b/lib/impersonate.c index ef202303306..3f8ec2bf22c 100644 --- a/lib/impersonate.c +++ b/lib/impersonate.c @@ -690,6 +690,7 @@ const struct impersonate_opts impersonations[] = { .http2_settings = "4:4194304;3:100", .http2_window_update = 10485760, .http2_pseudo_headers_order = "mspa", + .http2_stream_weight = 255, .tls_extension_order = NULL, .tls_grease = true }, @@ -745,6 +746,7 @@ const struct impersonate_opts impersonations[] = { .http2_settings = "4:4194304;3:100", .http2_window_update = 10485760, .http2_pseudo_headers_order = "mspa", + .http2_stream_weight = 255, .tls_extension_order = NULL, .tls_grease = true }, @@ -803,6 +805,7 @@ const struct impersonate_opts impersonations[] = { .http2_settings = "2:0;4:2097152;3:100", .http2_window_update = 10485760, .http2_pseudo_headers_order = "mspa", + .http2_stream_weight = 255, .tls_extension_order = NULL, .tls_grease = true }, @@ -861,6 +864,7 @@ const struct impersonate_opts impersonations[] = { .http2_settings = "2:0;4:4194304;3:100", .http2_window_update = 10485760, .http2_pseudo_headers_order = "mspa", + .http2_stream_weight = 255, .tls_extension_order = NULL, .tls_grease = true }, @@ -919,6 +923,7 @@ const struct impersonate_opts impersonations[] = { .http2_settings = "2:0;4:4194304;3:100", .http2_window_update = 10485760, .http2_pseudo_headers_order = "mspa", + .http2_stream_weight = 255, .tls_extension_order = NULL, .tls_grease = true }, From 587dea832a112ceab1f408cfceba2ecc24b76e7e Mon Sep 17 00:00:00 2001 From: Yifei Kong Date: Mon, 29 Apr 2024 14:02:17 +0800 Subject: [PATCH 507/509] WIP: save at 2024-04-29 14:02:17 --- export.sh | 5 +++++ lib/impersonate.h | 1 + src/tool_getparam.c | 22 ++++++++++++++++------ 3 files changed, 22 insertions(+), 6 deletions(-) diff --git a/export.sh b/export.sh index c237ee2ada8..7bced68790c 100755 --- a/export.sh +++ b/export.sh @@ -1,4 +1,9 @@ #!/bin/bash +# TODO: use cmake to generate mingw makefile, see: +# +# 1. https://github.com/curl/curl/pull/13244/files +# 2. https://everything.curl.dev/build/windows.html + git df curl-8_7_1 > chrome.patch mv chrome.patch ../curl-impersonate/chrome/patches/curl-impersonate.patch diff --git a/lib/impersonate.h b/lib/impersonate.h index a9e1e4b45a9..904d00dbe3e 100644 --- a/lib/impersonate.h +++ b/lib/impersonate.h @@ -37,6 +37,7 @@ struct impersonate_opts { const char *ech; const char *tls_extension_order; bool tls_grease; + int http2_stream_weight; /* Other TLS options will come here in the future once they are * configurable through curl_easy_setopt() */ }; diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 15e2ccdf4a5..2f586256f10 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -77,6 +77,7 @@ static ParameterError getstr(char **str, const char *val, bool allowblank) typedef enum { C_ABSTRACT_UNIX_SOCKET, C_ALPN, + C_ALPS, C_ALT_SVC, C_ANYAUTH, C_APPEND, @@ -87,6 +88,7 @@ typedef enum { C_CACERT, C_CAPATH, C_CERT, + C_CERT_COMPRESSION, C_CERT_STATUS, C_CERT_TYPE, C_CIPHERS, @@ -123,6 +125,7 @@ typedef enum { C_DOH_INSECURE, C_DOH_URL, C_DUMP_HEADER, + C_ECH, C_EGD_FILE, C_ENGINE, C_EPRT, @@ -166,6 +169,10 @@ typedef enum { C_HTTP1_1, C_HTTP2, C_HTTP2_PRIOR_KNOWLEDGE, + C_HTTP2_PSEUDO_HEADERS_ORDER, + C_HTTP2_SETTINGS, + C_HTTP2_WINDOW_UPDATE, + C_HTTP2_STREAMS, C_HTTP3, C_HTTP3_ONLY, C_IGNORE_CONTENT_LENGTH, @@ -283,6 +290,7 @@ typedef enum { C_SESSIONID, C_SHOW_ERROR, C_SILENT, + C_SIGNATURE_HASHES, C_SOCKS4, C_SOCKS4A, C_SOCKS5, @@ -312,6 +320,10 @@ typedef enum { C_TFTP_NO_OPTIONS, C_TIME_COND, C_TLS_MAX, + C_TLS_SESSION_TICKET, + C_TLS_EXTENSION_ORDER, + C_TLS_PERMUTE_EXTENSIONS, + C_TLS_GREASE, C_TLS13_CIPHERS, C_TLSAUTHTYPE, C_TLSPASSWORD, @@ -369,7 +381,7 @@ static const struct LongShort aliases[]= { {"cacert", ARG_FILE, ' ', C_CACERT}, {"capath", ARG_FILE, ' ', C_CAPATH}, {"cert", ARG_FILE, 'E', C_CERT}, - {"cert-compression", ARG_STRG, ' ', C_CERT_CERT_COMPRESSION}, // curl-impersonate + {"cert-compression", ARG_STRG, ' ', C_CERT_COMPRESSION}, // curl-impersonate {"cert-status", ARG_BOOL, ' ', C_CERT_STATUS}, {"cert-type", ARG_STRG, ' ', C_CERT_TYPE}, {"ciphers", ARG_STRG, ' ', C_CIPHERS}, @@ -1888,9 +1900,8 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ case C_TLS_PERMUTE_EXTENSIONS: /* --tls-permute-extensions curl-impersonate */ config->ssl_permute_extensions = toggle; break; - case C_TLS_EXTENSION_ORDER: /* --tls-permute-extensions curl-impersonate */ + case C_TLS_EXTENSION_ORDER: /* --tls-extension-order curl-impersonate */ err = getstr(&config->tls_extension_order, nextarg, ALLOW_BLANK); - if(err) return err; break; case C_TLS_GREASE: /* --tls-grease curl-impersonate */ config->tls_grease = toggle; @@ -1953,7 +1964,6 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ if(!feature_http2) return PARAM_LIBCURL_DOESNT_SUPPORT; err = getstr(&config->http2_settings, nextarg, ALLOW_BLANK); - if(err) return err; break; case C_HTTP2_WINDOW_UPDATE: /* --http2-window-update curl-impersonate */ if(!feature_http2) @@ -2093,7 +2103,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ } else { /* Simple case: just a string, with a keyword */ - getStr(&config->ech, nextarg, ALLOW_BLANK); + getstr(&config->ech, nextarg, ALLOW_BLANK); } break; #endif @@ -2116,7 +2126,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ GetFileAndPassword(nextarg, &config->cert, &config->key_passwd); break; case C_CERT_COMPRESSION: /* --cert-compression curl-impersonate */ - err = getstr(nextarg, &config->ssl_cert_compression ALLOW_BLANK); + err = getstr(nextarg, &config->ssl_cert_compression, ALLOW_BLANK); break; case C_CACERT: /* --cacert */ err = getstr(&config->cacert, nextarg, DENY_BLANK); From c29c35ae70560f5caebc7f1157be878363785105 Mon Sep 17 00:00:00 2001 From: Yifei Kong Date: Sun, 5 May 2024 19:28:41 +0800 Subject: [PATCH 508/509] Fix bugs in getparam --- lib/easy.c | 4 ++-- lib/easyoptions.c | 2 +- lib/url.c | 1 + lib/urldata.h | 4 +++- src/tool_cfgable.c | 5 ++--- src/tool_getparam.c | 12 ++++++------ 6 files changed, 15 insertions(+), 13 deletions(-) diff --git a/lib/easy.c b/lib/easy.c index ac45a7da38f..51d4d40cc10 100644 --- a/lib/easy.c +++ b/lib/easy.c @@ -349,7 +349,7 @@ CURLsslset curl_global_sslset(curl_sslbackend id, const char *name, * curl-impersonate: * Actually call curl_easy_setopt() with all the needed options * */ -CURLcode _do_impersonate(struct Curl_easy *data, +static CURLcode _do_impersonate(struct Curl_easy *data, const struct impersonate_opts *opts, int default_headers) { @@ -359,7 +359,7 @@ CURLcode _do_impersonate(struct Curl_easy *data, if(opts->target == NULL) { DEBUGF(fprintf(stderr, "Error: unknown impersonation target '%s'\n", - target)); + opts->target)); return CURLE_BAD_FUNCTION_ARGUMENT; } diff --git a/lib/easyoptions.c b/lib/easyoptions.c index 608a4f5493a..1869a5878f5 100644 --- a/lib/easyoptions.c +++ b/lib/easyoptions.c @@ -389,6 +389,6 @@ struct curl_easyoption Curl_easyopts[] = { */ int Curl_easyopts_check(void) { - return ((CURLOPT_LASTENTRY%10000) != (1100 + 1)); + return ((CURLOPT_LASTENTRY%10000) != (1012 + 1)); } #endif diff --git a/lib/url.c b/lib/url.c index 4027f44d5d7..db07bfa4086 100644 --- a/lib/url.c +++ b/lib/url.c @@ -473,6 +473,7 @@ CURLcode Curl_init_userdefined(struct Curl_easy *data) set->tcp_nodelay = TRUE; set->ssl_enable_alpn = TRUE; set->ssl_enable_ticket = TRUE; + set->tls_grease = TRUE; set->expect_100_timeout = 1000L; /* Wait for a second by default. */ set->sep_headers = TRUE; /* separated header lists by default */ set->buffer_size = READBUFFER_SIZE; diff --git a/lib/urldata.h b/lib/urldata.h index 447e24d2a31..90e1c09d805 100644 --- a/lib/urldata.h +++ b/lib/urldata.h @@ -316,6 +316,7 @@ struct ssl_primary_config { BIT(verifyhost); /* set TRUE if CN/SAN must match hostname */ BIT(verifystatus); /* set TRUE if certificate status must be checked */ BIT(sessionid); /* cache session IDs or not */ + // BIT(grease); /* grease enabled? */ }; struct ssl_config_data { @@ -559,6 +560,7 @@ struct ConnectBits { BIT(tls_enable_alps); /* TLS ALPS extension? */ BIT(tls_enable_ticket); /* TLS session ticket extension? */ BIT(tls_permute_extensions); /* TLS extension permutations */ + BIT(tls_grease); /* TLS grease? */ #ifndef CURL_DISABLE_DOH BIT(doh); #endif @@ -1829,6 +1831,7 @@ struct UserDefined { BIT(ssl_enable_alps);/* TLS ALPS extension? */ BIT(ssl_enable_ticket); /* TLS session ticket extension */ BIT(ssl_permute_extensions); /* TLS Permute extensions */ + BIT(tls_grease); /* TLS grease? */ BIT(path_as_is); /* allow dotdots? */ BIT(pipewait); /* wait for multiplex status before starting a new connection */ @@ -1853,7 +1856,6 @@ struct UserDefined { int tls_ech; /* TLS ECH configuration */ #endif int http2_window_update; - BIT(tls_grease); }; #ifndef CURL_DISABLE_MIME diff --git a/src/tool_cfgable.c b/src/tool_cfgable.c index 8e92fe0ad09..e46fd753948 100644 --- a/src/tool_cfgable.c +++ b/src/tool_cfgable.c @@ -96,15 +96,14 @@ static void free_config_fields(struct OperationConfig *config) Curl_safefree(config->proto_str); Curl_safefree(config->proto_redir_str); - // Impersonate + // curl-impersonate Curl_safefree(config->ssl_sig_hash_algs); Curl_safefree(config->ssl_cert_compression); Curl_safefree(config->http2_pseudo_headers_order); Curl_safefree(config->http2_settings); Curl_safefree(config->http2_streams); Curl_safefree(config->tls_extension_order); - // End Impersonate - + urlnode = config->url_list; while(urlnode) { struct getout *next = urlnode->next; diff --git a/src/tool_getparam.c b/src/tool_getparam.c index 2f586256f10..bdc9b4df64d 100644 --- a/src/tool_getparam.c +++ b/src/tool_getparam.c @@ -466,8 +466,8 @@ static const struct LongShort aliases[]= { {"http2-prior-knowledge", ARG_NONE, ' ', C_HTTP2_PRIOR_KNOWLEDGE}, {"http2-pseudo-headers-order", ARG_STRG, ' ', C_HTTP2_PSEUDO_HEADERS_ORDER}, // curl-impersonate {"http2-settings", ARG_STRG, ' ', C_HTTP2_SETTINGS}, // curl-impersonate - {"http2-window-update", ARG_STRG, ' ', C_HTTP2_WINDOW_UPDATE}, // curl-impersonate {"http2-streams", ARG_STRG, ' ', C_HTTP2_STREAMS}, // curl-impersonate + {"http2-window-update", ARG_STRG, ' ', C_HTTP2_WINDOW_UPDATE}, // curl-impersonate {"http3", ARG_NONE, ' ', C_HTTP3}, {"http3-only", ARG_NONE, ' ', C_HTTP3_ONLY}, {"ignore-content-length", ARG_BOOL, ' ', C_IGNORE_CONTENT_LENGTH}, @@ -584,8 +584,8 @@ static const struct LongShort aliases[]= { {"service-name", ARG_STRG, ' ', C_SERVICE_NAME}, {"sessionid", ARG_BOOL, ' ', C_SESSIONID}, {"show-error", ARG_BOOL, 'S', C_SHOW_ERROR}, - {"silent", ARG_BOOL, 's', C_SILENT}, {"signature-hashes", ARG_STRG, ' ', C_SIGNATURE_HASHES}, // curl-impersonate + {"silent", ARG_BOOL, 's', C_SILENT}, {"socks4", ARG_STRG, ' ', C_SOCKS4}, {"socks4a", ARG_STRG, ' ', C_SOCKS4A}, {"socks5", ARG_STRG, ' ', C_SOCKS5}, @@ -614,11 +614,11 @@ static const struct LongShort aliases[]= { {"tftp-blksize", ARG_STRG, ' ', C_TFTP_BLKSIZE}, {"tftp-no-options", ARG_BOOL, ' ', C_TFTP_NO_OPTIONS}, {"time-cond", ARG_STRG, 'z', C_TIME_COND}, - {"tls-max", ARG_STRG, ' ', C_TLS_MAX}, - {"tls-session-ticket", ARG_BOOL, ' ', C_TLS_SESSION_TICKET}, // curl-impersonate - {"tls-permute-extensions", ARG_BOOL, ' ', C_TLS_PERMUTE_EXTENSIONS}, // curl-impersonate {"tls-extension-order", ARG_STRG, ' ', C_TLS_EXTENSION_ORDER}, // curl-impersonate {"tls-grease", ARG_BOOL, ' ', C_TLS_GREASE}, // curl-impersonate + {"tls-max", ARG_STRG, ' ', C_TLS_MAX}, + {"tls-permute-extensions", ARG_BOOL, ' ', C_TLS_PERMUTE_EXTENSIONS}, // curl-impersonate + {"tls-session-ticket", ARG_BOOL, ' ', C_TLS_SESSION_TICKET}, // curl-impersonate {"tls13-ciphers", ARG_STRG, ' ', C_TLS13_CIPHERS}, {"tlsauthtype", ARG_STRG, ' ', C_TLSAUTHTYPE}, {"tlspassword", ARG_STRG, ' ', C_TLSPASSWORD}, @@ -2126,7 +2126,7 @@ ParameterError getparameter(const char *flag, /* f or -long-flag */ GetFileAndPassword(nextarg, &config->cert, &config->key_passwd); break; case C_CERT_COMPRESSION: /* --cert-compression curl-impersonate */ - err = getstr(nextarg, &config->ssl_cert_compression, ALLOW_BLANK); + err = getstr(&config->ssl_cert_compression, nextarg, ALLOW_BLANK); break; case C_CACERT: /* --cacert */ err = getstr(&config->cacert, nextarg, DENY_BLANK); From 2062025876bad80443d35021ad0175e055ac74cd Mon Sep 17 00:00:00 2001 From: Yifei Kong Date: Mon, 6 May 2024 15:36:10 +0800 Subject: [PATCH 509/509] backport curl br encoding patch --- configure.ac | 4 ++-- lib/content_encoding.c | 10 +++++----- tests/http/test_02_download.py | 13 +++++++++++++ tests/http/testenv/env.py | 7 ++++++- tests/http/testenv/httpd.py | 20 ++++++++++++++++++++ 5 files changed, 46 insertions(+), 8 deletions(-) diff --git a/configure.ac b/configure.ac index d6ac9771237..a19c12b95d2 100644 --- a/configure.ac +++ b/configure.ac @@ -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 diff --git a/lib/content_encoding.c b/lib/content_encoding.c index c1abf24e8c0..8e926dd2ecd 100644 --- a/lib/content_encoding.c +++ b/lib/content_encoding.c @@ -300,7 +300,7 @@ static CURLcode deflate_do_write(struct Curl_easy *data, struct zlib_writer *zp = (struct zlib_writer *) writer; z_stream *z = &zp->z; /* zlib state structure */ - if(!(type & CLIENTWRITE_BODY)) + if(!(type & CLIENTWRITE_BODY) || !nbytes) return Curl_cwriter_write(data, writer->next, type, buf, nbytes); /* Set the compressed input when this function is called */ @@ -457,7 +457,7 @@ static CURLcode gzip_do_write(struct Curl_easy *data, struct zlib_writer *zp = (struct zlib_writer *) writer; z_stream *z = &zp->z; /* zlib state structure */ - if(!(type & CLIENTWRITE_BODY)) + if(!(type & CLIENTWRITE_BODY) || !nbytes) return Curl_cwriter_write(data, writer->next, type, buf, nbytes); if(zp->zlib_init == ZLIB_INIT_GZIP) { @@ -669,7 +669,7 @@ static CURLcode brotli_do_write(struct Curl_easy *data, CURLcode result = CURLE_OK; BrotliDecoderResult r = BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT; - if(!(type & CLIENTWRITE_BODY)) + if(!(type & CLIENTWRITE_BODY) || !nbytes) return Curl_cwriter_write(data, writer->next, type, buf, nbytes); if(!bp->br) @@ -762,7 +762,7 @@ static CURLcode zstd_do_write(struct Curl_easy *data, ZSTD_outBuffer out; size_t errorCode; - if(!(type & CLIENTWRITE_BODY)) + if(!(type & CLIENTWRITE_BODY) || !nbytes) return Curl_cwriter_write(data, writer->next, type, buf, nbytes); if(!zp->decomp) { @@ -916,7 +916,7 @@ static CURLcode error_do_write(struct Curl_easy *data, (void) buf; (void) nbytes; - if(!(type & CLIENTWRITE_BODY)) + if(!(type & CLIENTWRITE_BODY) || !nbytes) return Curl_cwriter_write(data, writer->next, type, buf, nbytes); failf(data, "Unrecognized content encoding type. " diff --git a/tests/http/test_02_download.py b/tests/http/test_02_download.py index 4db9c9d36e9..395fc862f2f 100644 --- a/tests/http/test_02_download.py +++ b/tests/http/test_02_download.py @@ -394,6 +394,19 @@ def test_02_27_paused_no_cl(self, env: Env, httpd, nghttpx, repeat): r = client.run(args=[url]) r.check_exit_code(0) + @pytest.mark.parametrize("proto", ['http/1.1', 'h2', 'h3']) + def test_02_28_get_compressed(self, env: Env, httpd, nghttpx, repeat, proto): + if proto == 'h3' and not env.have_h3(): + pytest.skip("h3 not supported") + count = 1 + urln = f'https://{env.authority_for(env.domain1brotli, proto)}/data-100k?[0-{count-1}]' + curl = CurlClient(env=env) + r = curl.http_download(urls=[urln], alpn_proto=proto, extra_args=[ + '--compressed' + ]) + r.check_exit_code(code=0) + r.check_response(count=count, http_status=200) + def check_downloads(self, client, srcfile: str, count: int, complete: bool = True): for i in range(count): diff --git a/tests/http/testenv/env.py b/tests/http/testenv/env.py index a207059dcd5..13c5d6bd46e 100644 --- a/tests/http/testenv/env.py +++ b/tests/http/testenv/env.py @@ -129,10 +129,11 @@ def __init__(self): self.htdocs_dir = os.path.join(self.gen_dir, 'htdocs') self.tld = 'http.curl.se' self.domain1 = f"one.{self.tld}" + self.domain1brotli = f"brotli.one.{self.tld}" self.domain2 = f"two.{self.tld}" self.proxy_domain = f"proxy.{self.tld}" self.cert_specs = [ - CertificateSpec(domains=[self.domain1, 'localhost'], key_type='rsa2048'), + CertificateSpec(domains=[self.domain1, self.domain1brotli, 'localhost'], key_type='rsa2048'), CertificateSpec(domains=[self.domain2], key_type='rsa2048'), CertificateSpec(domains=[self.proxy_domain, '127.0.0.1'], key_type='rsa2048'), CertificateSpec(name="clientsX", sub_specs=[ @@ -376,6 +377,10 @@ def htdocs_dir(self) -> str: def domain1(self) -> str: return self.CONFIG.domain1 + @property + def domain1brotli(self) -> str: + return self.CONFIG.domain1brotli + @property def domain2(self) -> str: return self.CONFIG.domain2 diff --git a/tests/http/testenv/httpd.py b/tests/http/testenv/httpd.py index c04c22699a6..b8615875a9a 100644 --- a/tests/http/testenv/httpd.py +++ b/tests/http/testenv/httpd.py @@ -50,6 +50,7 @@ class Httpd: 'alias', 'env', 'filter', 'headers', 'mime', 'setenvif', 'socache_shmcb', 'rewrite', 'http2', 'ssl', 'proxy', 'proxy_http', 'proxy_connect', + 'brotli', 'mpm_event', ] COMMON_MODULES_DIRS = [ @@ -203,6 +204,7 @@ def _mkpath(self, path): def _write_config(self): domain1 = self.env.domain1 + domain1brotli = self.env.domain1brotli creds1 = self.env.get_credentials(domain1) domain2 = self.env.domain2 creds2 = self.env.get_credentials(domain2) @@ -285,6 +287,24 @@ def _write_config(self): f'', f'', ]) + # Alternate to domain1 with BROTLI compression + conf.extend([ # https host for domain1, h1 + h2 + f'', + f' ServerName {domain1brotli}', + f' Protocols h2 http/1.1', + f' SSLEngine on', + f' SSLCertificateFile {creds1.cert_file}', + f' SSLCertificateKeyFile {creds1.pkey_file}', + f' DocumentRoot "{self._docs_dir}"', + f' SetOutputFilter BROTLI_COMPRESS', + ]) + conf.extend(self._curltest_conf(domain1)) + if domain1 in self._extra_configs: + conf.extend(self._extra_configs[domain1]) + conf.extend([ + f'', + f'', + ]) conf.extend([ # https host for domain2, no h2 f'', f' ServerName {domain2}',