From: Daniel Stenberg Date: Sat, 29 Jun 2024 22:08:06 +0000 (+0200) Subject: docs/libcurl: polish the single-line descriptions X-Git-Tag: curl-8_9_0~153 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=29789ae312c42c8a2fb034274a262a5fcd214d12;p=thirdparty%2Fcurl.git docs/libcurl: polish the single-line descriptions - use imperative form - use lowercase - no period - unify some phrases - fix curl_multi_socket and curl_multi_socket_all to keep their own descriptions Closes #14062 --- diff --git a/docs/libcurl/curl_easy_cleanup.md b/docs/libcurl/curl_easy_cleanup.md index e939dddc72..1ce8162d31 100644 --- a/docs/libcurl/curl_easy_cleanup.md +++ b/docs/libcurl/curl_easy_cleanup.md @@ -16,7 +16,7 @@ Protocol: # NAME -curl_easy_cleanup - End a libcurl easy handle +curl_easy_cleanup - free an easy handle # SYNOPSIS diff --git a/docs/libcurl/curl_easy_duphandle.md b/docs/libcurl/curl_easy_duphandle.md index 49d95ad989..8c8999cdb3 100644 --- a/docs/libcurl/curl_easy_duphandle.md +++ b/docs/libcurl/curl_easy_duphandle.md @@ -15,7 +15,7 @@ Protocol: # NAME -curl_easy_duphandle - Clone a libcurl session handle +curl_easy_duphandle - clone an easy handle # SYNOPSIS diff --git a/docs/libcurl/curl_easy_escape.md b/docs/libcurl/curl_easy_escape.md index dfe4bf5f3a..272d607171 100644 --- a/docs/libcurl/curl_easy_escape.md +++ b/docs/libcurl/curl_easy_escape.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_easy_escape - URL encodes the given string +curl_easy_escape - URL encode a string # SYNOPSIS diff --git a/docs/libcurl/curl_easy_init.md b/docs/libcurl/curl_easy_init.md index 9d282bdf3c..f8ffd95b50 100644 --- a/docs/libcurl/curl_easy_init.md +++ b/docs/libcurl/curl_easy_init.md @@ -17,7 +17,7 @@ Protocol: # NAME -curl_easy_init - Start a libcurl easy session +curl_easy_init - create an easy handle # SYNOPSIS diff --git a/docs/libcurl/curl_easy_unescape.md b/docs/libcurl/curl_easy_unescape.md index 00951d96ec..a99b4e30f6 100644 --- a/docs/libcurl/curl_easy_unescape.md +++ b/docs/libcurl/curl_easy_unescape.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_easy_unescape - URL decodes the given string +curl_easy_unescape - URL decode a string # SYNOPSIS diff --git a/docs/libcurl/curl_easy_upkeep.md b/docs/libcurl/curl_easy_upkeep.md index eec4ed2f40..c1c7c4a471 100644 --- a/docs/libcurl/curl_easy_upkeep.md +++ b/docs/libcurl/curl_easy_upkeep.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_easy_upkeep - Perform any connection upkeep checks. +curl_easy_upkeep - keep existing connections alive # SYNOPSIS diff --git a/docs/libcurl/curl_escape.md b/docs/libcurl/curl_escape.md index d15a4debcc..4ec3fec91c 100644 --- a/docs/libcurl/curl_escape.md +++ b/docs/libcurl/curl_escape.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_escape - URL encodes the given string +curl_escape - URL encode a string # SYNOPSIS diff --git a/docs/libcurl/curl_formget.md b/docs/libcurl/curl_formget.md index 2ec8d119cc..ba8f3b1e25 100644 --- a/docs/libcurl/curl_formget.md +++ b/docs/libcurl/curl_formget.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_formget - serialize a previously built multipart form POST chain +curl_formget - serialize a multipart form POST chain # SYNOPSIS diff --git a/docs/libcurl/curl_getdate.md b/docs/libcurl/curl_getdate.md index 8df080ce9f..0dae3dc1d1 100644 --- a/docs/libcurl/curl_getdate.md +++ b/docs/libcurl/curl_getdate.md @@ -15,7 +15,7 @@ Protocol: # NAME -curl_getdate - Convert a date string to number of seconds +curl_getdate - convert date string to number of seconds # SYNOPSIS diff --git a/docs/libcurl/curl_global_init.md b/docs/libcurl/curl_global_init.md index e48a1f36fe..bc78d4cdc6 100644 --- a/docs/libcurl/curl_global_init.md +++ b/docs/libcurl/curl_global_init.md @@ -17,7 +17,7 @@ Protocol: # NAME -curl_global_init - Global libcurl initialization +curl_global_init - global libcurl initialization # SYNOPSIS diff --git a/docs/libcurl/curl_global_init_mem.md b/docs/libcurl/curl_global_init_mem.md index 229d4d606b..04e4447814 100644 --- a/docs/libcurl/curl_global_init_mem.md +++ b/docs/libcurl/curl_global_init_mem.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_global_init_mem - Global libcurl initialization with memory callbacks +curl_global_init_mem - global libcurl initialization with memory callbacks # SYNOPSIS diff --git a/docs/libcurl/curl_global_sslset.md b/docs/libcurl/curl_global_sslset.md index 1fdc2d3201..f688ed2b9c 100644 --- a/docs/libcurl/curl_global_sslset.md +++ b/docs/libcurl/curl_global_sslset.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_global_sslset - Select SSL backend to use with libcurl +curl_global_sslset - select SSL backend to use # SYNOPSIS diff --git a/docs/libcurl/curl_multi_fdset.md b/docs/libcurl/curl_multi_fdset.md index 78299610c2..640008d36c 100644 --- a/docs/libcurl/curl_multi_fdset.md +++ b/docs/libcurl/curl_multi_fdset.md @@ -18,7 +18,7 @@ Protocol: # NAME -curl_multi_fdset - extracts file descriptor information from a multi handle +curl_multi_fdset - extract file descriptor information from a multi handle # SYNOPSIS diff --git a/docs/libcurl/curl_multi_get_handles.md b/docs/libcurl/curl_multi_get_handles.md index a0b4bfb9c5..a2544b433d 100644 --- a/docs/libcurl/curl_multi_get_handles.md +++ b/docs/libcurl/curl_multi_get_handles.md @@ -15,7 +15,7 @@ Protocol: # NAME -curl_multi_get_handles - returns all added easy handles +curl_multi_get_handles - return all added easy handles # SYNOPSIS diff --git a/docs/libcurl/curl_multi_perform.md b/docs/libcurl/curl_multi_perform.md index eebed6e7d0..c49336b00c 100644 --- a/docs/libcurl/curl_multi_perform.md +++ b/docs/libcurl/curl_multi_perform.md @@ -18,7 +18,7 @@ Protocol: # NAME -curl_multi_perform - reads/writes available data from easy handles +curl_multi_perform - run all transfers until it would block # SYNOPSIS diff --git a/docs/libcurl/curl_multi_poll.md b/docs/libcurl/curl_multi_poll.md index aea2baaad9..8fe6a96794 100644 --- a/docs/libcurl/curl_multi_poll.md +++ b/docs/libcurl/curl_multi_poll.md @@ -15,7 +15,7 @@ Protocol: # NAME -curl_multi_poll - polls on all easy handles in a multi handle +curl_multi_poll - poll on all easy handles in a multi handle # SYNOPSIS diff --git a/docs/libcurl/curl_multi_socket.md b/docs/libcurl/curl_multi_socket.md index 4c85d01997..c016a3c216 100644 --- a/docs/libcurl/curl_multi_socket.md +++ b/docs/libcurl/curl_multi_socket.md @@ -16,7 +16,7 @@ Protocol: # NAME -curl_multi_socket - reads/writes available data +curl_multi_socket - read/write available data # SYNOPSIS @@ -24,47 +24,37 @@ curl_multi_socket - reads/writes available data #include CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd, int *running_handles); - -CURLMcode curl_multi_socket_all(CURLM *multi_handle, - int *running_handles); ~~~ # DESCRIPTION -These functions are deprecated. Do not use. See -curl_multi_socket_action(3) instead. +This function is deprecated. Do not use. See curl_multi_socket_action(3) +instead. At return, the integer **running_handles** points to contains the number of still running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. Note that when you call -curl_multi_socket_action(3) on a specific socket and the counter -decreases by one, it DOES NOT necessarily mean that this exact socket/transfer -is the one that completed. Use curl_multi_info_read(3) to figure out -which easy handle that completed. - -The curl_multi_socket_action(3) functions inform the application about -updates in the socket (file descriptor) status by doing none, one, or multiple -calls to the socket callback function set with the -CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They -update the status with changes since the previous time the callback was -called. - -Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option -with curl_multi_setopt(3). Your application then gets called with -information on how long to wait for socket actions at most before doing the -timeout action: call the curl_multi_socket_action(3) function with the -**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the -curl_multi_timeout(3) function to poll the value at any given time, but -for an event-based system using the callback is far better than relying on -polling the timeout value. +curl_multi_socket(3) on a specific socket and the counter decreases by one, it +DOES NOT necessarily mean that this exact socket/transfer is the one that +completed. Use curl_multi_info_read(3) to figure out which easy handle that +completed. + +The curl_multi_socket(3) functions inform the application about updates in the +socket (file descriptor) status by doing none, one, or multiple calls to the +socket callback function set with the CURLMOPT_SOCKETFUNCTION(3) option to +curl_multi_setopt(3). They update the status with changes since the previous +time the callback was called. + +Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option with +curl_multi_setopt(3). Your application then gets called with information on +how long to wait for socket actions at most before doing the timeout action: +call the curl_multi_socket_action(3) function with the **sockfd** argument set +to CURL_SOCKET_TIMEOUT. You can also use the curl_multi_timeout(3) function to +poll the value at any given time, but for an event-based system using the +callback is far better than relying on polling the timeout value. Usage of curl_multi_socket(3) is deprecated, whereas the function is -equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to -0. - -Force libcurl to (re-)check all its internal sockets and transfers instead of -just a single one by calling curl_multi_socket_all(3). Note that there -should not be any reason to use this function. +equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to 0. # EXAMPLE @@ -86,8 +76,7 @@ int main(void) This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0. -curl_multi_socket(3) is deprecated, use -curl_multi_socket_action(3) instead! +curl_multi_socket(3) is deprecated, use curl_multi_socket_action(3) instead! # RETURN VALUE diff --git a/docs/libcurl/curl_multi_socket_action.md b/docs/libcurl/curl_multi_socket_action.md index c7faa76372..7b547cfa45 100644 --- a/docs/libcurl/curl_multi_socket_action.md +++ b/docs/libcurl/curl_multi_socket_action.md @@ -16,7 +16,7 @@ Protocol: # NAME -curl_multi_socket_action - reads/writes available data given an action +curl_multi_socket_action - read/write available data given an action # SYNOPSIS diff --git a/docs/libcurl/curl_multi_socket_all.md b/docs/libcurl/curl_multi_socket_all.md index 4c85d01997..6b95fc3932 100644 --- a/docs/libcurl/curl_multi_socket_all.md +++ b/docs/libcurl/curl_multi_socket_all.md @@ -16,14 +16,12 @@ Protocol: # NAME -curl_multi_socket - reads/writes available data +curl_multi_socket_all - reads/writes available data for all easy handles # SYNOPSIS ~~~c #include -CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd, - int *running_handles); CURLMcode curl_multi_socket_all(CURLM *multi_handle, int *running_handles); @@ -31,62 +29,34 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle, # DESCRIPTION -These functions are deprecated. Do not use. See -curl_multi_socket_action(3) instead. +This function is deprecated. Do not use. See curl_multi_socket_action(3) +instead. At return, the integer **running_handles** points to contains the number of still running easy handles within the multi handle. When this number reaches -zero, all transfers are complete/done. Note that when you call -curl_multi_socket_action(3) on a specific socket and the counter -decreases by one, it DOES NOT necessarily mean that this exact socket/transfer -is the one that completed. Use curl_multi_info_read(3) to figure out -which easy handle that completed. - -The curl_multi_socket_action(3) functions inform the application about -updates in the socket (file descriptor) status by doing none, one, or multiple -calls to the socket callback function set with the -CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They -update the status with changes since the previous time the callback was -called. - -Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option -with curl_multi_setopt(3). Your application then gets called with -information on how long to wait for socket actions at most before doing the -timeout action: call the curl_multi_socket_action(3) function with the -**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the -curl_multi_timeout(3) function to poll the value at any given time, but -for an event-based system using the callback is far better than relying on -polling the timeout value. - -Usage of curl_multi_socket(3) is deprecated, whereas the function is -equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to -0. +zero, all transfers are complete/done. Force libcurl to (re-)check all its internal sockets and transfers instead of -just a single one by calling curl_multi_socket_all(3). Note that there -should not be any reason to use this function. +just a single one by calling curl_multi_socket_all(3). Note that there should +not be any reason to use this function. # EXAMPLE ~~~c int main(void) { - /* the event-library gets told when there activity on the socket 'fd', - which we translate to a call to curl_multi_socket_action() */ int running; int rc; - int fd; CURLM *multi; - rc = curl_multi_socket(multi, fd, &running); + rc = curl_multi_socket_all(multi, &running); } ~~~ # AVAILABILITY -This function was added in libcurl 7.15.4, and is deemed stable since -7.16.0. +This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0. -curl_multi_socket(3) is deprecated, use +curl_multi_socket_all(3) is deprecated, use curl_multi_socket_action(3) instead! # RETURN VALUE diff --git a/docs/libcurl/curl_multi_wait.md b/docs/libcurl/curl_multi_wait.md index 7440d7b3d9..d86b7d4ebe 100644 --- a/docs/libcurl/curl_multi_wait.md +++ b/docs/libcurl/curl_multi_wait.md @@ -14,7 +14,7 @@ Protocol: # NAME -curl_multi_wait - polls on all easy handles in a multi handle +curl_multi_wait - poll on all easy handles in a multi handle # SYNOPSIS diff --git a/docs/libcurl/curl_multi_waitfds.md b/docs/libcurl/curl_multi_waitfds.md index 3e4c260915..c2231b9597 100644 --- a/docs/libcurl/curl_multi_waitfds.md +++ b/docs/libcurl/curl_multi_waitfds.md @@ -15,7 +15,7 @@ Protocol: # NAME -curl_multi_waitfds - extracts file descriptor information from a multi handle +curl_multi_waitfds - extract file descriptor information from a multi handle # SYNOPSIS diff --git a/docs/libcurl/curl_multi_wakeup.md b/docs/libcurl/curl_multi_wakeup.md index cadaeaa31b..26a013454e 100644 --- a/docs/libcurl/curl_multi_wakeup.md +++ b/docs/libcurl/curl_multi_wakeup.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_multi_wakeup - wakes up a sleeping curl_multi_poll call +curl_multi_wakeup - wake up a sleeping curl_multi_poll call # SYNOPSIS diff --git a/docs/libcurl/curl_share_cleanup.md b/docs/libcurl/curl_share_cleanup.md index 36acc6f08b..4173abf1d5 100644 --- a/docs/libcurl/curl_share_cleanup.md +++ b/docs/libcurl/curl_share_cleanup.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_share_cleanup - Clean up a shared object +curl_share_cleanup - close a shared object # SYNOPSIS diff --git a/docs/libcurl/curl_share_init.md b/docs/libcurl/curl_share_init.md index 2e74dfed85..ab8d574a4c 100644 --- a/docs/libcurl/curl_share_init.md +++ b/docs/libcurl/curl_share_init.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_share_init - Create a shared object +curl_share_init - create a share object # SYNOPSIS diff --git a/docs/libcurl/curl_share_setopt.md b/docs/libcurl/curl_share_setopt.md index 166f5f6ba4..c2ef90d4f4 100644 --- a/docs/libcurl/curl_share_setopt.md +++ b/docs/libcurl/curl_share_setopt.md @@ -13,7 +13,7 @@ Protocol: # NAME -curl_share_setopt - Set options for a shared object +curl_share_setopt - set options for a shared object # SYNOPSIS diff --git a/docs/libcurl/curl_unescape.md b/docs/libcurl/curl_unescape.md index adcce8b14f..6eda0e70b0 100644 --- a/docs/libcurl/curl_unescape.md +++ b/docs/libcurl/curl_unescape.md @@ -15,7 +15,7 @@ Protocol: # NAME -curl_unescape - URL decodes the given string +curl_unescape - URL decode a string # SYNOPSIS diff --git a/docs/libcurl/curl_url.md b/docs/libcurl/curl_url.md index acab43d88c..708f0ce7d7 100644 --- a/docs/libcurl/curl_url.md +++ b/docs/libcurl/curl_url.md @@ -17,7 +17,7 @@ Protocol: # NAME -curl_url - returns a new URL handle +curl_url - create a URL handle # SYNOPSIS