Skip to content

Commit

Permalink
curl_pushheader_byname/bynum.3: document in their own man pages
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@bagder
bagder committed Jun 9, 2023
1 parent 6e26666 commit 259ee6d
Show file tree
Hide file tree
Showing 5 changed files with 159 additions and 14 deletions.
1 change: 1 addition & 0 deletions .github/scripts/cleanspell.pl
View file
Expand Up @@ -69,6 +69,7 @@
$_ =~ 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 $_;
Expand Down
2 changes: 2 additions & 0 deletions docs/libcurl/Makefile.inc
View file
Expand Up @@ -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 \
Expand Down
80 changes: 80 additions & 0 deletions docs/libcurl/curl_pushheader_byname.3
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 changes: 70 additions & 0 deletions docs/libcurl/curl_pushheader_bynum.3
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 changes: 6 additions & 14 deletions docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3
View file
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down

0 comments on commit 259ee6d

Please sign in to comment.