From: Daniel Stenberg Date: Fri, 9 Jun 2023 10:38:25 +0000 (+0200) Subject: curl_pushheader_byname/bynum.3: document in their own man pages X-Git-Tag: curl-8_2_0~127 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=259ee6defc33a53dfa5e2ef0d640437571c11efa;p=thirdparty%2Fcurl.git curl_pushheader_byname/bynum.3: document in their own man pages These two functions were added in 7.44.0 when CURLMOPT_PUSHFUNCTION was introduced but always lived a life in the shadows, embedded in the CURLMOPT_PUSHFUNCTION man page. Until now. It makes better sense and gives more visibility to document them in their own stand-alone man pages. Closes #11286 --- diff --git a/.github/scripts/cleanspell.pl b/.github/scripts/cleanspell.pl index a9c85f2f30..a7f19c5628 100755 --- a/.github/scripts/cleanspell.pl +++ b/.github/scripts/cleanspell.pl @@ -69,6 +69,7 @@ while() { $_ =~ s/curl_mime_(subparts|addpart|filedata|data_cb)//g; $_ =~ s/curl_ws_(send|recv|meta)//g; $_ =~ s/curl_url_(dup)//g; + $_ =~ s/curl_pushheader_by(name|num)//g; $_ =~ s/libcurl-env//g; $_ =~ s/(^|\W)((tftp|https|http|ftp):\/\/[a-z0-9\-._~%:\/?\#\[\]\@!\$&'()*+,;=]+)//gi; print O $_; diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc index a815d0796d..d25f94f4dc 100644 --- a/docs/libcurl/Makefile.inc +++ b/docs/libcurl/Makefile.inc @@ -85,6 +85,8 @@ man_MANS = \ curl_multi_timeout.3 \ curl_multi_wakeup.3 \ curl_multi_wait.3 \ + curl_pushheader_bynum.3 \ + curl_pushheader_byname.3 \ curl_share_cleanup.3 \ curl_share_init.3 \ curl_share_setopt.3 \ diff --git a/docs/libcurl/curl_pushheader_byname.3 b/docs/libcurl/curl_pushheader_byname.3 new file mode 100644 index 0000000000..683a48d825 --- /dev/null +++ b/docs/libcurl/curl_pushheader_byname.3 @@ -0,0 +1,80 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * SPDX-License-Identifier: curl +.\" * +.\" ************************************************************************** +.TH curl_pushheader_byname 3 "9 Jun 2023" "libcurl" "libcurl" +.SH NAME +curl_pushheader_byname - get a push header by name +.SH SYNOPSIS +.nf +#include + +char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name); +.fi +.SH DESCRIPTION +This is a function that is only functional within a +\fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it +elsewhere and it has no function then. + +It returns the value for the given header field name (or NULL) for the +incoming server push request. This is a shortcut so that the application does +not have to loop through all headers to find the one it is interested in. The +data this function points to will be freed when this callback returns. If more +than one header field use the same name, this returns only the first one. + +.SH EXAMPLE +.nf +int curl_push_callback(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp) +{ + char *headp; + int *transfers = (int *)clientp; + FILE *out; + headp = curl_pushheader_byname(headers, ":path"); + if(headp && !strncmp(headp, "/push-", 6)) { + fprintf(stderr, "The PATH is %s\\n", headp); + + /* save the push here */ + out = fopen("pushed-stream", "wb"); + + /* write to this file */ + curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); + + (*transfers)++; /* one more */ + + return CURL_PUSH_OK; + } + return CURL_PUSH_DENY; +} + +curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, curl_push_callback); +curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); +.fi +.SH AVAILABILITY +Added in 7.44.0 +.SH RETURN VALUE +Returns a pointer to the header field content or NULL. +.SH "SEE ALSO" +.BR CURLMOPT_PUSHFUNCTION "(3)," curl_pushheader_bynum "(3), " diff --git a/docs/libcurl/curl_pushheader_bynum.3 b/docs/libcurl/curl_pushheader_bynum.3 new file mode 100644 index 0000000000..a51b8d73e2 --- /dev/null +++ b/docs/libcurl/curl_pushheader_bynum.3 @@ -0,0 +1,70 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * SPDX-License-Identifier: curl +.\" * +.\" ************************************************************************** +.TH curl_pushheader_bynum 3 "9 Jun 2023" "libcurl" "libcurl" +.SH NAME +curl_pushheader_bynum - get a push header by index +.SH SYNOPSIS +.nf +#include + +char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num); +.fi +.SH DESCRIPTION +This is a function that is only functional within a +\fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it +elsewhere and it has no function then. + +It returns the value for the header field at the given index \fBnum\fP, for +the incoming server push request or NULL. The data pointed will be freed when +this callback returns. The returned pointer points to a "name:value" string +that will be freed when this callback returns. + +.SH EXAMPLE +.nf +/* output all the incoming push request headers */ +int curl_push_callback(CURL *parent, + CURL *easy, + size_t num_headers, + struct curl_pushheaders *headers, + void *clientp) +{ + sizt_t i = 0; + char *field; + do { + field = curl_pushheader_bynum(headers, i); + if(field) + fprintf(stderr, "Push header: %s\\n", field); + i++; + } while(field); + return CURL_PUSH_OK; /* permission granted */ +} + +curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, curl_push_callback); +.fi +.SH AVAILABILITY +Added in 7.44.0 +.SH RETURN VALUE +Returns a pointer to the header field content or NULL. +.SH "SEE ALSO" +.BR CURLMOPT_PUSHFUNCTION "(3)," curl_pushheader_byname "(3)," diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 index a3fc7f2281..5bfe50027b 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 @@ -29,9 +29,6 @@ CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes .nf #include -char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num); -char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name); - int curl_push_callback(CURL *parent, CURL *easy, size_t num_headers, @@ -70,17 +67,12 @@ multi handle, the callback must not do that by itself. The callback can access PUSH_PROMISE headers with two accessor functions. These functions can only be used from within this callback and they -can only access the PUSH_PROMISE headers. The normal response headers will be -passed to the header callback for pushed streams just as for normal streams. -.IP curl_pushheader_bynum -Returns the header at index \fInum\fP (or NULL). The returned pointer points -to a "name:value" string that will be freed when this callback returns. -.IP curl_pushheader_byname -Returns the value for the given header name (or NULL). This is a shortcut so -that the application does not have to loop through all headers to find the one -it is interested in. The data pointed will be freed when this callback -returns. If more than one header field use the same name, this returns only -the first one. +can only access the PUSH_PROMISE headers: \fIcurl_pushheader_byname(3)\fP and +\fIcurl_pushheader_bynum(3)\fP. The normal response headers will be passed to +the header callback for pushed streams just as for normal streams. + +The header fields can also be accessed with \fIcurl_easy_header(3)\fP, +introduced in later libcurl versions. .SH CALLBACK RETURN VALUE .IP "CURL_PUSH_OK (0)" The application has accepted the stream and it can now start receiving data,