luo980/curl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

curl_pushheader_byname/bynum.3: document in their own man pages

Browse Source 
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
This commit is contained in:
Daniel Stenberg 2023-06-09 12:38:25 +02:00
parent 6e26666d6b
commit 259ee6defc
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
5 changed files with 159 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/scripts/cleanspell.pl vendored
View File

@ -69,6 +69,7 @@ while(<F>) {
$_ =~ 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 $_;

2
docs/libcurl/Makefile.inc
View File

@ -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 \

80
docs/libcurl/curl_pushheader_byname.3 Normal file
View File

@ -0,0 +1,80 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, 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 <curl/curl.h>
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), "

70
docs/libcurl/curl_pushheader_bynum.3 Normal file
View File

@ -0,0 +1,70 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, 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 <curl/curl.h>
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),"

20
docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3
View File

@ -29,9 +29,6 @@ CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes
.nf
#include <curl/curl.h>
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,