mirror of
https://github.com/curl/curl.git
synced 2025-03-31 16:00:35 +08:00
docs: minor polish
- "an HTTP*" (not "a") - remove a few contractions - remove a spurious "a" - reduce use of "I" in texts Closes #11040
This commit is contained in:
parent
bb0b245cc1
commit
4578ada4a0
@ -64,7 +64,7 @@ resolution screens:
|
||||
newspapers have used columns for decades or centuries.
|
||||
|
||||
2. Narrower columns allow developers to easier show multiple pieces of code
|
||||
next to each other in different windows. I often have two or three source
|
||||
next to each other in different windows. It allows two or three source
|
||||
code windows next to each other on the same screen - as well as multiple
|
||||
terminal and debugging windows.
|
||||
|
||||
|
@ -25,7 +25,7 @@ Curl_easy *data connectdata *conn cf-ssl cf-socket
|
||||
|
||||
While connection filters all do different things, they look the same from the "outside". The code in `data` and `conn` does not really know **which** filters are installed. `conn` just writes into the first filter, whatever that is.
|
||||
|
||||
Same is true for filters. Each filter has a pointer to the `next` filter. When SSL has encrypted the data, it does not write to a socket, it writes to the next filter. If that is indeed a socket, or a file, or a HTTP/2 connection is of no concern to the SSL filter.
|
||||
Same is true for filters. Each filter has a pointer to the `next` filter. When SSL has encrypted the data, it does not write to a socket, it writes to the next filter. If that is indeed a socket, or a file, or an HTTP/2 connection is of no concern to the SSL filter.
|
||||
|
||||
And this allows the stacking, as in:
|
||||
|
||||
@ -91,13 +91,13 @@ struct Curl_cfilter {
|
||||
BIT(connected); /* != 0 iff this filter is connected */
|
||||
};
|
||||
```
|
||||
The filter type `cft` is a singleton, one static struct for each type of filter. The `ctx` is where a filter will hold its specific data. That varies by filter type. A http-proxy filter will keep the ongoing state of the CONNECT here, but free it after its has been established. The SSL filter will keep the `SSL*` (if OpenSSL is used) here until the connection is closed. So, this varies.
|
||||
The filter type `cft` is a singleton, one static struct for each type of filter. The `ctx` is where a filter will hold its specific data. That varies by filter type. An http-proxy filter will keep the ongoing state of the CONNECT here, but free it after its has been established. The SSL filter will keep the `SSL*` (if OpenSSL is used) here until the connection is closed. So, this varies.
|
||||
|
||||
`conn` is a reference to the connection this filter belongs to, so nothing extra besides the pointer itself.
|
||||
|
||||
Several things, that before were kept in `struct connectdata`, will now go into the `filter->ctx` *when needed*. So, the memory footprint for connections that do *not* use a http proxy, or socks, or https will be lower.
|
||||
Several things, that before were kept in `struct connectdata`, will now go into the `filter->ctx` *when needed*. So, the memory footprint for connections that do *not* use an http proxy, or socks, or https will be lower.
|
||||
|
||||
As to transfer efficiency, writing and reading through a filter comes at near zero cost *if the filter does not transform the data*. A http proxy or socks filter, once it is connected, will just pass the calls through. Those filters implementations will look like this:
|
||||
As to transfer efficiency, writing and reading through a filter comes at near zero cost *if the filter does not transform the data*. An http proxy or socks filter, once it is connected, will just pass the calls through. Those filters implementations will look like this:
|
||||
|
||||
```
|
||||
ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
|
||||
|
@ -205,9 +205,9 @@ A short guide to how to write git commit messages in the curl project.
|
||||
followed by an -- empty line -- ]
|
||||
[Bug: URL to the source of the report or more related discussion; use Fixes
|
||||
for GitHub issues instead when that is appropriate]
|
||||
[Approved-by: John Doe - credit someone who approved the PR; if you're
|
||||
[Approved-by: John Doe - credit someone who approved the PR; if you are
|
||||
committing this for someone else using --author=... you don't need this
|
||||
as you're implicitly approving it by committing]
|
||||
as you are implicitly approving it by committing]
|
||||
[Authored-by: John Doe - credit the original author of the code; only use
|
||||
this if you can't use "git commit --author=..."]
|
||||
{Signed-off-by: John Doe - we don't use this, but don't bother removing it]
|
||||
|
@ -275,7 +275,7 @@ The `happy-eyeballs-timeout-ms` value is the **hard** timeout, meaning after tha
|
||||
|
||||
So, without you specifying anything, the hard timeout is 200ms and the soft is 100ms:
|
||||
|
||||
* Ideally, the whole QUIC handshake happens and curl has a HTTP/3 connection in less than 100ms.
|
||||
* Ideally, the whole QUIC handshake happens and curl has an HTTP/3 connection in less than 100ms.
|
||||
* When QUIC is not supported (or UDP does not work for this network path), no reply is seen and the HTTP/2 TLS+TCP connection starts 100ms later.
|
||||
* In the worst case, UDP replies start before 100ms, but drag on. This will start the TLS+TCP connection after 200ms.
|
||||
* When the QUIC handshake fails, the TLS+TCP connection is attempted right away. For example, when the QUIC server presents the wrong certificate.
|
||||
@ -300,8 +300,8 @@ ones. You can easily create huge local files like `truncate -s=8G 8GB` - they
|
||||
are huge but do not occupy that much space on disk since they are just big
|
||||
holes.
|
||||
|
||||
In my Debian setup I just installed **apache2**. It runs on port 80 and has a
|
||||
document root in `/var/www/html`. I can get the 8GB file from it with `curl
|
||||
In a Debian setup you can install **apache2**. It runs on port 80 and has a
|
||||
document root in `/var/www/html`. Download the 8GB file from apache with `curl
|
||||
localhost/8GB -o dev/null`
|
||||
|
||||
In this description we setup and run an HTTP/3 reverse-proxy in front of the
|
||||
|
@ -423,7 +423,7 @@ OpenSSL, follow the OpenSSL build instructions and then install `libssl.a` and
|
||||
OpenSSL like this:
|
||||
|
||||
```bash
|
||||
LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you'll need to the SSL/TLS layer's transtive dependencies if you're linking statically.
|
||||
LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you will need to the SSL/TLS layer's transtive dependencies if you are linking statically.
|
||||
./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN/sysroot/usr"
|
||||
```
|
||||
|
||||
|
@ -786,18 +786,16 @@ by default.
|
||||
Default protocol version used by curl is LDAP version 3. Version 2 will be
|
||||
used as a fallback mechanism in case version 3 fails to connect.
|
||||
|
||||
LDAP is a complex thing and writing an LDAP query is not an easy task. I do
|
||||
advise you to dig up the syntax description for that elsewhere. One such place
|
||||
might be: [RFC 2255, The LDAP URL Format](https://curl.se/rfc/rfc2255.txt)
|
||||
LDAP is a complex thing and writing an LDAP query is not an easy
|
||||
task. Familiarize yourself with the exact syntax description elsewhere. One
|
||||
such place might be: [RFC 2255, The LDAP URL
|
||||
Format](https://curl.se/rfc/rfc2255.txt)
|
||||
|
||||
To show you an example, this is how I can get all people from my local LDAP
|
||||
server that has a certain sub-domain in their email address:
|
||||
To show you an example, this is how to get all people from an LDAP server that
|
||||
has a certain sub-domain in their email address:
|
||||
|
||||
curl -B "ldap://ldap.frontec.se/o=frontec??sub?mail=*sth.frontec.se"
|
||||
|
||||
If I want the same info in HTML format, I can get it by not using the `-B`
|
||||
(enforce ASCII) flag.
|
||||
|
||||
You also can use authentication when accessing LDAP catalog:
|
||||
|
||||
curl -u user:passwd "ldap://ldap.frontec.se/o=frontec??sub?mail=*"
|
||||
|
@ -11,8 +11,9 @@
|
||||
|
||||
Curl is a command line tool for doing all sorts of URL manipulations and
|
||||
transfers, but this particular document will focus on how to use it when
|
||||
doing HTTP requests for fun and profit. I will assume that you know how to
|
||||
invoke `curl --help` or `curl --manual` to get basic information about it.
|
||||
doing HTTP requests for fun and profit. This documents assumes that you know
|
||||
how to invoke `curl --help` or `curl --manual` to get basic information about
|
||||
it.
|
||||
|
||||
Curl is not written to do everything for you. It makes the requests, it gets
|
||||
the data, it sends data and it retrieves the information. You probably need
|
||||
|
@ -12,7 +12,7 @@ Category: http proxy
|
||||
Example: --proxy-http2 -x proxy $URL
|
||||
Multi: boolean
|
||||
---
|
||||
Tells curl to try negotiate HTTP version 2 with a HTTPS proxy. The proxy might
|
||||
Tells curl to try negotiate HTTP version 2 with an HTTPS proxy. The proxy might
|
||||
still only offer HTTP/1 and then curl will stick to using that version.
|
||||
|
||||
This has no effect for any other kinds of proxies.
|
||||
|
@ -34,7 +34,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename);
|
||||
.SH DESCRIPTION
|
||||
Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as
|
||||
the Alt-Svc cache to read existing cache contents from and possibly also write
|
||||
it back to a after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in
|
||||
it back to after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in
|
||||
\fICURLOPT_ALTSVC_CTRL(3)\fP.
|
||||
|
||||
Specify a blank file name ("") to make libcurl not load from a file at all.
|
||||
|
@ -99,7 +99,7 @@ method special. This method cannot be combined with other auth types.
|
||||
A sha256 checksum of the request payload is used as input to the signature
|
||||
calculation. For POST requests, this is a checksum of the provided
|
||||
\fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer.
|
||||
For requests like PUT, you can provide your own checksum in a HTTP header named
|
||||
For requests like PUT, you can provide your own checksum in an HTTP header named
|
||||
\fBx-provider2-content-sha256\fP.
|
||||
.PP
|
||||
For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request
|
||||
|
@ -124,7 +124,7 @@ Since 7.21.7 the proxy string supports the socks protocols as "schemes".
|
||||
Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
|
||||
error.
|
||||
|
||||
curl built to use NSS cannot connect to a HTTPS server over a unix domain
|
||||
curl built to use NSS cannot connect to an HTTPS server over a unix domain
|
||||
socket.
|
||||
.SH RETURN VALUE
|
||||
Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
|
||||
|
Loading…
x
Reference in New Issue
Block a user