From: Daniel Stenberg Date: Mon, 1 Jul 2024 08:37:43 +0000 (+0200) Subject: docs: misc language polish X-Git-Tag: curl-8_9_0~145 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=816ac2a866dd075e07940c2d93eb99be087138df;p=thirdparty%2Fcurl.git docs: misc language polish - CURLINFO_FILETIME*: improve language - add '32bit' and '64bit' as bad words, use 32-bit and 64-bit - mksymbolsmanpage.pl: avoid "will" Closes #14070 --- diff --git a/.github/scripts/badwords.txt b/.github/scripts/badwords.txt index 321bebb2a7..3069641cc4 100644 --- a/.github/scripts/badwords.txt +++ b/.github/scripts/badwords.txt @@ -58,3 +58,9 @@ doesn't:does not won't:will not couldn't:could not \bwill\b:rewrite to present tense +32bit=32-bit +64bit=64-bit +32 bit\b=32-bit +64 bit\b=64-bit +64-bits:64 bits or 64-bit +32-bits:32 bits or 32-bit diff --git a/docs/CODE_REVIEW.md b/docs/CODE_REVIEW.md index b78992a3e7..bee26a3f34 100644 --- a/docs/CODE_REVIEW.md +++ b/docs/CODE_REVIEW.md @@ -141,13 +141,13 @@ data. Where it comes from and where it goes. `size_t` is not a fixed size. `time_t` can be signed or unsigned and have different sizes. Relying on variable sizes is a red flag. -Also remember that endianness and >= 32 bit accesses to unaligned addresses +Also remember that endianness and >= 32-bit accesses to unaligned addresses are problematic areas. ## Integer overflows -Be careful about integer overflows. Some variable types can be either 32 bit -or 64 bit. Integer overflows must be detected and acted on *before* they +Be careful about integer overflows. Some variable types can be either 32-bit +or 64-bit. Integer overflows must be detected and acted on *before* they happen. ## Dangerous use of functions diff --git a/docs/DEPRECATE.md b/docs/DEPRECATE.md index 073bc94e3a..c38b66cace 100644 --- a/docs/DEPRECATE.md +++ b/docs/DEPRECATE.md @@ -29,7 +29,7 @@ May 2025 are: BearSSL and Secure Transport. - axTLS - PolarSSL - NPN - - Support for systems without 64 bit data types + - Support for systems without 64-bit data types - NSS - gskit - mingw v1 diff --git a/docs/FAQ b/docs/FAQ index 0303a262a8..f7fdfcc378 100644 --- a/docs/FAQ +++ b/docs/FAQ @@ -56,7 +56,7 @@ FAQ 4. Running Problems 4.2 Why do I get problems when I use & or % in the URL? 4.3 How can I use {, }, [ or ] to specify multiple URLs? - 4.4 Why do I get downloaded data even though the web page does not exist? + 4.4 Why do I get downloaded data even though the webpage does not exist? 4.5 Why do I get return code XXX from an HTTP server? 4.5.1 "400 Bad Request" 4.5.2 "401 Unauthorized" @@ -65,7 +65,7 @@ FAQ 4.5.5 "405 Method Not Allowed" 4.5.6 "301 Moved Permanently" 4.6 Can you tell me what error code 142 means? - 4.7 How do I keep user names and passwords secret in curl command lines? + 4.7 How do I keep usernames and passwords secret in curl command lines? 4.8 I found a bug 4.9 curl cannot authenticate to a server that requires NTLM? 4.10 My HTTP request using HEAD, PUT or DELETE does not work @@ -89,7 +89,7 @@ FAQ 5.6 What about Keep-Alive or persistent connections? 5.7 Link errors when building libcurl on Windows 5.8 libcurl.so.X: open failed: No such file or directory - 5.9 How does libcurl resolve host names? + 5.9 How does libcurl resolve hostnames? 5.10 How do I prevent libcurl from writing the response to stdout? 5.11 How do I make libcurl not receive the whole HTTP response? 5.12 Can I make libcurl fake or hide my real IP address? @@ -624,7 +624,7 @@ FAQ 3.14 Does curl support JavaScript or PAC (automated proxy config)? - Many web pages do magic stuff using embedded JavaScript. curl and libcurl + Many webpages do magic stuff using embedded JavaScript. curl and libcurl have no built-in support for that, so it will be treated just like any other contents. @@ -722,7 +722,7 @@ FAQ curl --header "Host: www.example.com" http://127.0.0.1/ - You can also opt to add faked host name entries to curl with the --resolve + You can also opt to add faked hostname entries to curl with the --resolve option. That has the added benefit that things like redirects will also work properly. The above operation would instead be done as: @@ -771,11 +771,10 @@ FAQ [WHATEVER]. This way you can for example send a DELETE by doing "curl -X DELETE [URL]". - It is thus pointless to do "curl -XGET [URL]" as GET would be used - anyway. In the same vein it is pointless to do "curl -X POST -d data - [URL]"... But you can make a fun and somewhat rare request that sends a - request-body in a GET request with something like "curl -X GET -d data - [URL]" + It is thus pointless to do "curl -XGET [URL]" as GET would be used anyway. + In the same vein it is pointless to do "curl -X POST -d data [URL]". You can + make a fun and somewhat rare request that sends a request-body in a GET + request with something like "curl -X GET -d data [URL]" Note that -X does not actually change curl's behavior as it only modifies the actual string sent in the request, but that may of course trigger a @@ -822,7 +821,7 @@ FAQ curl -g 'www.example.com/weirdname[].html' - 4.4 Why do I get downloaded data even though the web page does not exist? + 4.4 Why do I get downloaded data even though the webpage does not exist? curl asks remote servers for the page you specify. If the page does not exist at the server, the HTTP protocol defines how the server should respond and @@ -883,7 +882,7 @@ FAQ appreciate a detailed bug report from you that describes how we could go ahead and repeat this. - 4.7 How do I keep user names and passwords secret in curl command lines? + 4.7 How do I keep usernames and passwords secret in curl command lines? This problem has two sides: @@ -1100,7 +1099,7 @@ FAQ When doing HTTP transfers, curl will perform exactly what you are asking it to do and if successful it will not return an error. You can use curl to test your web server's "file not found" page (that gets 404 back), you can - use it to check your authentication protected web pages (that gets a 401 + use it to check your authentication protected webpages (that gets a 401 back) and so on. The specific HTTP response code does not constitute a problem or error for @@ -1192,7 +1191,7 @@ FAQ 5.6 What about Keep-Alive or persistent connections? curl and libcurl have excellent support for persistent connections when - transferring several files from the same server. curl will attempt to reuse + transferring several files from the same server. curl will attempt to reuse connections for all URLs specified on the same command line/config file, and libcurl will reuse connections for all transfers that are made using the same libcurl handle. @@ -1252,14 +1251,14 @@ FAQ 'man ld.so' and 'man ld' will tell you more details - 5.9 How does libcurl resolve host names? + 5.9 How does libcurl resolve hostnames? libcurl supports a large number of name resolve functions. One of them is picked at build-time and will be used unconditionally. Thus, if you want to change name resolver function you must rebuild libcurl and tell it to use a different function. - - The non-IPv6 resolver that can use one of four different host name resolve + - The non-IPv6 resolver that can use one of four different hostname resolve calls (depending on what your system supports): A - gethostbyname() diff --git a/docs/libcurl/curl_getdate.md b/docs/libcurl/curl_getdate.md index 0dae3dc1d1..72cb60199a 100644 --- a/docs/libcurl/curl_getdate.md +++ b/docs/libcurl/curl_getdate.md @@ -122,12 +122,12 @@ Always This function returns -1 when it fails to parse the date string. Otherwise it returns the number of seconds as described. -On systems with a signed 32 bit time_t: if the year is larger than 2037 or +On systems with a signed 32-bit time_t: if the year is larger than 2037 or less than 1903, this function returns -1. -On systems with an unsigned 32 bit time_t: if the year is larger than 2106 or +On systems with an unsigned 32-bit time_t: if the year is larger than 2106 or less than 1970, this function returns -1. -On systems with 64 bit time_t: if the year is less than 1583, this function +On systems with 64-bit time_t: if the year is less than 1583, this function returns -1. (The Gregorian calendar was first introduced 1582 so no "real" dates in this way of doing dates existed before then.) diff --git a/docs/libcurl/mksymbolsmanpage.pl b/docs/libcurl/mksymbolsmanpage.pl index fc9a8b704a..1cccb4f3ee 100755 --- a/docs/libcurl/mksymbolsmanpage.pl +++ b/docs/libcurl/mksymbolsmanpage.pl @@ -60,7 +60,7 @@ since that version no new code should be written to use the symbol as it is marked for getting removed in a future. The last version that featured the specific symbol. Using the symbol in source -code will make it no longer compile error-free after that specified version. +code makes it no longer compile error-free after that specified version. This man page is automatically generated from the symbols-in-versions file. HEADER diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.md b/docs/libcurl/opts/CURLINFO_FILETIME.md index 4e4d7f190f..9f0544d585 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME.md +++ b/docs/libcurl/opts/CURLINFO_FILETIME.md @@ -34,12 +34,11 @@ in number of seconds since January 1 1970 in the GMT/UTC time zone. If you get hide it or the server does not support the command that tells document time etc) and the time of the document is unknown. -You must tell libcurl to collect this information before the transfer is made, -by using the CURLOPT_FILETIME(3) option to curl_easy_setopt(3) or -you this unconditionally gets a -1 back. +You must ask libcurl to collect this information before the transfer is made, +by using the CURLOPT_FILETIME(3) option or you unconditionally get a -1 back. -Consider using CURLINFO_FILETIME_T(3) to be able to extract dates beyond -the year 2038 on systems using 32 bit longs (Windows). +Consider CURLINFO_FILETIME_T(3) instead to be able to extract dates beyond the +year 2038 on systems using 32-bit longs (Windows). # EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.md b/docs/libcurl/opts/CURLINFO_FILETIME_T.md index 0ba24d61ff..94ddbba945 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME_T.md +++ b/docs/libcurl/opts/CURLINFO_FILETIME_T.md @@ -30,18 +30,16 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME_T, # DESCRIPTION Pass a pointer to a curl_off_t to receive the remote time of the retrieved -document in number of seconds since January 1 1970 in the GMT/UTC time -zone. If you get -1, it can be because of many reasons (it might be unknown, -the server might hide it or the server does not support the command that tells +document in number of seconds since January 1 1970 in the GMT/UTC time zone. +If you get -1, it can be because of many reasons (it might be unknown, the +server might hide it or the server does not support the command that tells document time etc) and the time of the document is unknown. You must ask libcurl to collect this information before the transfer is made, -by using the CURLOPT_FILETIME(3) option to curl_easy_setopt(3) or -you unconditionally get a -1 back. +by using the CURLOPT_FILETIME(3) option or you unconditionally get a -1 back. -This option is an alternative to CURLINFO_FILETIME(3) to allow systems -with 32 bit long variables to extract dates outside of the 32bit timestamp -range. +This option is an alternative to CURLINFO_FILETIME(3) to allow systems with 32 +bit long variables to extract dates outside of the 32-bit timestamp range. # EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md index 5558e6d177..231756d578 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE.md +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE.md @@ -29,7 +29,7 @@ Pass a long *val* as parameter. This should be the time counted as seconds since 1 Jan 1970, and the time is used in a condition as specified with CURLOPT_TIMECONDITION(3). -On systems with 32 bit 'long' variables (such as Windows), this option cannot +On systems with 32-bit 'long' variables (such as Windows), this option cannot set dates beyond the year 2038. Consider CURLOPT_TIMEVALUE_LARGE(3) instead. diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md index cd16c7589c..6368743d13 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md @@ -31,9 +31,9 @@ Pass a curl_off_t *val* as parameter. This should be the time counted as seconds since 1 Jan 1970, and the time is used in a condition as specified with CURLOPT_TIMECONDITION(3). -The difference between this option and CURLOPT_TIMEVALUE(3) is the type -of the argument. On systems where 'long' is only 32 bit wide, this option has -to be used to set dates beyond the year 2038. +The difference between this option and CURLOPT_TIMEVALUE(3) is the type of the +argument. On systems where 'long' is only 32 bits wide, this option has to be +used to set dates beyond the year 2038. # DEFAULT diff --git a/lib/asyn-thread.c b/lib/asyn-thread.c index 9aff8bf6a4..638b2d016b 100644 --- a/lib/asyn-thread.c +++ b/lib/asyn-thread.c @@ -862,7 +862,7 @@ CURLcode Curl_resolver_is_resolved(struct Curl_easy *data, } else { /* poll for name lookup done with exponential backoff up to 250ms */ - /* should be fine even if this converts to 32 bit */ + /* should be fine even if this converts to 32-bit */ timediff_t elapsed = Curl_timediff(Curl_now(), data->progress.t_startsingle); if(elapsed < 0) diff --git a/lib/curl_ntlm_core.c b/lib/curl_ntlm_core.c index db27972db9..a5b0a89753 100644 --- a/lib/curl_ntlm_core.c +++ b/lib/curl_ntlm_core.c @@ -158,7 +158,7 @@ static void setup_des_key(const unsigned char *key_56, { DES_cblock key; - /* Expand the 56-bit key to 64-bits */ + /* Expand the 56-bit key to 64 bits */ extend_key_56_to_64(key_56, (char *) &key); /* Set the key parity to odd */ @@ -175,7 +175,7 @@ static void setup_des_key(const unsigned char *key_56, { char key[8]; - /* Expand the 56-bit key to 64-bits */ + /* Expand the 56-bit key to 64 bits */ extend_key_56_to_64(key_56, key); /* Set the key parity to odd */ @@ -193,7 +193,7 @@ static bool encrypt_des(const unsigned char *in, unsigned char *out, mbedtls_des_context ctx; char key[8]; - /* Expand the 56-bit key to 64-bits */ + /* Expand the 56-bit key to 64 bits */ extend_key_56_to_64(key_56, key); /* Set the key parity to odd */ @@ -214,7 +214,7 @@ static bool encrypt_des(const unsigned char *in, unsigned char *out, size_t out_len; CCCryptorStatus err; - /* Expand the 56-bit key to 64-bits */ + /* Expand the 56-bit key to 64 bits */ extend_key_56_to_64(key_56, key); /* Set the key parity to odd */ @@ -240,7 +240,7 @@ static bool encrypt_des(const unsigned char *in, unsigned char *out, ctl.Func_ID = ENCRYPT_ONLY; ctl.Data_Len = sizeof(key); - /* Expand the 56-bit key to 64-bits */ + /* Expand the 56-bit key to 64 bits */ extend_key_56_to_64(key_56, ctl.Crypto_Key); /* Set the key parity to odd */ @@ -278,7 +278,7 @@ static bool encrypt_des(const unsigned char *in, unsigned char *out, blob.hdr.aiKeyAlg = CALG_DES; blob.len = sizeof(blob.key); - /* Expand the 56-bit key to 64-bits */ + /* Expand the 56-bit key to 64 bits */ extend_key_56_to_64(key_56, blob.key); /* Set the key parity to odd */ diff --git a/lib/curl_setup.h b/lib/curl_setup.h index d47842d9ba..1fc0dc683e 100644 --- a/lib/curl_setup.h +++ b/lib/curl_setup.h @@ -447,7 +447,7 @@ #endif #ifndef SIZEOF_TIME_T -/* assume default size of time_t to be 32 bit */ +/* assume default size of time_t to be 32 bits */ #define SIZEOF_TIME_T 4 #endif diff --git a/lib/getinfo.c b/lib/getinfo.c index e5012f2c9d..9ca02889c6 100644 --- a/lib/getinfo.c +++ b/lib/getinfo.c @@ -277,8 +277,8 @@ static CURLcode getinfo_long(struct Curl_easy *data, CURLINFO info, case CURLINFO_LASTSOCKET: sockfd = Curl_getconnectinfo(data, NULL); - /* note: this is not a good conversion for systems with 64 bit sockets and - 32 bit longs */ + /* note: this is not a good conversion for systems with 64-bit sockets and + 32-bit longs */ if(sockfd != CURL_SOCKET_BAD) *param_longp = (long)sockfd; else diff --git a/lib/http_chunks.h b/lib/http_chunks.h index d3ecc36c77..0d87ee4df5 100644 --- a/lib/http_chunks.h +++ b/lib/http_chunks.h @@ -33,7 +33,7 @@ struct connectdata; /* * The longest possible hexadecimal number we support in a chunked transfer. * Neither RFC2616 nor the later HTTP specs define a maximum chunk size. - * For 64 bit curl_off_t we support 16 digits. For 32 bit, 8 digits. + * For 64-bit curl_off_t we support 16 digits. For 32-bit, 8 digits. */ #define CHUNK_MAXNUM_LEN (SIZEOF_CURL_OFF_T * 2) diff --git a/lib/multi.c b/lib/multi.c index 2139565189..7dbb5e69ff 100644 --- a/lib/multi.c +++ b/lib/multi.c @@ -3406,8 +3406,8 @@ static CURLMcode multi_timeout(struct Curl_multi *multi, if(Curl_splaycomparekeys(multi->timetree->key, now) > 0) { /* some time left before expiration */ timediff_t diff = Curl_timediff_ceil(multi->timetree->key, now); - /* this should be safe even on 32 bit archs, as we don't use that - overly long timeouts */ + /* this should be safe even on 32-bit archs, as we don't use that overly + long timeouts */ *timeout_ms = (long)diff; } else @@ -3572,7 +3572,7 @@ void Curl_expire(struct Curl_easy *data, timediff_t milli, expire_id id) DEBUGASSERT(id < EXPIRE_LAST); set = Curl_now(); - set.tv_sec += (time_t)(milli/1000); /* might be a 64 to 32 bit conversion */ + set.tv_sec += (time_t)(milli/1000); /* might be a 64 to 32 bits conversion */ set.tv_usec += (int)(milli%1000)*1000; if(set.tv_usec >= 1000000) { diff --git a/lib/parsedate.c b/lib/parsedate.c index 1a7195b16a..add70461db 100644 --- a/lib/parsedate.c +++ b/lib/parsedate.c @@ -521,13 +521,13 @@ static int parsedate(const char *date, time_t *output) #if (SIZEOF_TIME_T < 5) #ifdef HAVE_TIME_T_UNSIGNED - /* an unsigned 32 bit time_t can only hold dates to 2106 */ + /* an unsigned 32-bit time_t can only hold dates to 2106 */ if(yearnum > 2105) { *output = TIME_T_MAX; return PARSEDATE_LATER; } #else - /* a signed 32 bit time_t can only hold dates to the beginning of 2038 */ + /* a signed 32-bit time_t can only hold dates to the beginning of 2038 */ if(yearnum > 2037) { *output = TIME_T_MAX; return PARSEDATE_LATER; @@ -549,7 +549,7 @@ static int parsedate(const char *date, time_t *output) return PARSEDATE_FAIL; /* clearly an illegal date */ /* time2epoch() returns a time_t. time_t is often 32 bits, sometimes even on - architectures that feature 64 bit 'long' but ultimately time_t is the + architectures that feature a 64 bits 'long' but ultimately time_t is the correct data type to use. */ t = time2epoch(secnum, minnum, hournum, mdaynum, monnum, yearnum); diff --git a/lib/setopt.c b/lib/setopt.c index 188ecb2756..9a6ff0b510 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -2667,7 +2667,7 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) /* * Use this scope id when using IPv6 * We always get longs when passed plain numericals so we should check - * that the value fits into an unsigned 32 bit integer. + * that the value fits into an unsigned 32-bit integer. */ uarg = va_arg(param, unsigned long); #if SIZEOF_LONG > 4 diff --git a/lib/setup-vms.h b/lib/setup-vms.h index ea3936c708..fc21560284 100644 --- a/lib/setup-vms.h +++ b/lib/setup-vms.h @@ -144,7 +144,7 @@ static struct passwd *vms_getpwuid(uid_t uid) { struct passwd *my_passwd; -/* Hack needed to support 64 bit builds, decc_getpwnam is 32 bit only */ +/* Hack needed to support 64-bit builds, decc_getpwnam is 32-bit only */ #ifdef __DECC # if __INITIAL_POINTER_SIZE __char_ptr32 unix_path; diff --git a/lib/strtoofft.h b/lib/strtoofft.h index 34d293ba38..71808b719c 100644 --- a/lib/strtoofft.h +++ b/lib/strtoofft.h @@ -30,7 +30,7 @@ * Determine which string to integral data type conversion function we use * to implement string conversion to our curl_off_t integral data type. * - * Notice that curl_off_t might be 64 or 32 bit wide, and that it might use + * Notice that curl_off_t might be 64 or 32 bits wide, and that it might use * an underlying data type which might be 'long', 'int64_t', 'long long' or * '__int64' and more remotely other data types. * diff --git a/lib/timediff.h b/lib/timediff.h index fb318d4f2b..1ffa59e77f 100644 --- a/lib/timediff.h +++ b/lib/timediff.h @@ -26,7 +26,7 @@ #include "curl_setup.h" -/* Use a larger type even for 32 bit time_t systems so that we can keep +/* Use a larger type even for 32-bit time_t systems so that we can keep microsecond accuracy in it */ typedef curl_off_t timediff_t; #define CURL_FORMAT_TIMEDIFF_T CURL_FORMAT_CURL_OFF_T diff --git a/lib/ws.h b/lib/ws.h index baa77b4424..398900cc3f 100644 --- a/lib/ws.h +++ b/lib/ws.h @@ -57,7 +57,7 @@ struct ws_encoder { curl_off_t payload_len; /* payload length of current frame */ curl_off_t payload_remain; /* remaining payload of current */ unsigned int xori; /* xor index */ - unsigned char mask[4]; /* 32 bit mask for this connection */ + unsigned char mask[4]; /* 32-bit mask for this connection */ unsigned char firstbyte; /* first byte of frame we encode */ bool contfragment; /* set TRUE if the previous fragment sent was not final */ };