From 2494b8dd5175cee7f2e43c7e449db918587b0c1e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 20 Jan 2024 23:18:43 +0100 Subject: [PATCH] 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 | 430 +++++++++----- 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, 3963 insertions(+), 1834 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 0000000000..5d0fe2b2fb --- /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 182a3bdb46..e9ac0134f6 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 ec2813c3ed..ba92efabb4 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 f08538ad5e..a619fcc046 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 4896f8513e..951cbe859e 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 and a body of text. +Each file has a set of meta-data in the top of the file, followed by a body of +text. + +The documentation files that do not document options have no meta-data part. + +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 -`page-header` is the file that is output before the generated options output -for the master man page. +The `#` header can be used by non-option files and it produces produces a +`.SH` output. -`page-footer` is appended after all the individual options. +If the `#` header is used for a command line option file, that header is +simply ignored in the generated output. It can still serve a purpose in the +source file as it helps the user identify what option the file is for. + +### Variables + +There are three different "variables" that can be used when creating the +output. They need to be written within backticks in the source file (to escape +getting spellchecked by CI jobs): `%DATE`, `%VERSION` and `%GLOBALS`. ## Generate diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index 5a8996bc22..6fff55f484 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 a7c92f2646..428cc3bab2 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 0000000000..0c9bfb9538 --- /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 0000000000..45630d4352 --- /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 0000000000..3e06c1b38f --- /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 0000000000..cf30d47404 --- /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 0000000000..ac7ab5ca15 --- /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 0000000000..8c5d3faa7b --- /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 0000000000..66fc5dbb7e --- /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 0000000000..b0d8916144 --- /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 0000000000..1b25566591 --- /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 0000000000..32a5457afc --- /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 0000000000..80e36f1024 --- /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 0000000000..b834f9ae36 --- /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 0000000000..297b56c4b6 --- /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 0000000000..f4d0b55cfc --- /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 0000000000..3815877448 --- /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 0000000000..0084ec6128 --- /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 0000000000..0415fd78f2 --- /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 0000000000..4c759f1470 --- /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 0000000000..35d946697f --- /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 5c2fd4a476..27bc8cad6c 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 276ac1b669..0a0f17df5a 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 2498bdcd84..150e069e81 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 7561c951c5..3d0030d6a7 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 4b480f50ca..1b3909244f 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 cb0642620e..34b019175b 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 9a8184c640..d0b4bfa5a7 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 7b63f810bb..7b1b2174ba 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 75e9f2e400..ecd28df241 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 e2d1d7aa24..bfbd3af835 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 cf9f17b7d5..a0030a59da 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 56d0df7fdf..6df5d0ebf7 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 a30902bdb8..9d7e0c6fe0 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 897395677b..c52e5a7a37 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 bb1d3baa74..35bbab8139 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 c22a827f61..2f393e27e3 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 b3d19b3c33..f7281b09a9 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 f7da551592..0000000000 --- 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 0000000000..7cd0aa857f --- /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 a4fc1a9695..67a79fd70c 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 28738cac94..5453152e44 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 108846c062..d0a6d35396 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 966b70384e..de48807d4c 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 c0ebc08d44..c6467d15a4 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 ea7fb1526a..81a14ef6fd 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 da0d239bad..16bd7b35b9 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 58d472d20d..99f1ad48a7 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 5c7840bbc4..124dee13c0 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 2cedda97b0..3d563fbdd7 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 e6a5a5b2b9..2cb46938b5 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 51c0b4b7ce..4d3f298133 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 f1d67b9506..fb3b848723 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 004514f37b..3d6cff8997 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 f2ee551c5e..f05c01fed0 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 b6d382bafa..80ae056911 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 f02df763da..f4a8de8c04 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 979c039915..e22a2bb4a0 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 0e70ba91f6..faa4d8834f 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 fd924b897a..afc5573e55 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 5930557397..ff4163bc16 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 a76120cdc1..7d4d1c1f57 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 96be081414..3eab6668de 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 37ae0f8274..efa9da75c1 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 dcc65fb6c9..684428ddf7 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 6d0dd1605e..d12bf5194f 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 42a79e7ddf..42d3e85ed6 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 4543ecf15e..b68b7d4967 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 1ebc779c0d..511190023e 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 d3c48d17a6..11c1d0e875 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 6295a9e311..f6fb14a515 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 f9a119bd97..9554568a77 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 36b3309996..b68160c201 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 dddb86e229..e340cb0345 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 8196a908de..b8de4ebb25 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 73240492b9..d2697da538 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 304bfe8149..62973f172a 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 6d7a500a44..d26c471429 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 ac0e4bfefb..0ba552136f 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 eb669c5628..2f33639433 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 f030bcf598..9bd3686001 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 7c64f0e21c..5151e336c8 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 e3a08782b3..e4e3468588 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 c43bf2beea..265a8e4534 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 3026778d96..e9ec59146f 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 4bea99e6d8..accbc226df 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 3af9c6de4f..ef94b34af1 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 ae9af9429d..5f428dc0fa 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 33ae83b1c9..d477606fe6 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 b895779271..ace1ab29fb 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 2766ca265b..59c996d7be 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(/^ *