.\" generated by cd2nroff 0.1 from CURLMOPT_PUSHFUNCTION.md
.TH CURLMOPT_PUSHFUNCTION 3 "2026-10-22" libcurl
.SH NAME
CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes
.SH SYNOPSIS
.nf
#include <curl/curl.h>

int curl_push_callback(CURL *parent,
                       CURL *easy,
                       size_t num_headers,
                       struct curl_pushheaders *headers,
                       void *clientp);

CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
                            curl_push_callback func);
.fi
.SH DESCRIPTION
This callback gets called when a new HTTP/2 stream is being pushed by the
server (using the PUSH_PROMISE frame). If no push callback is set, all offered
pushes are denied automatically.
.SH CALLBACK DESCRIPTION
The callback gets its arguments like this:

\fIparent\fP is the handle of the stream on which this push arrives. The new
handle has the following options duplicated from the parent:
\fICURLOPT_WRITEFUNCTION(3)\fP, \fICURLOPT_WRITEDATA(3)\fP, \fICURLOPT_HEADERFUNCTION(3)\fP,
\fICURLOPT_HEADERDATA(3)\fP, \fICURLOPT_DEBUGFUNCTION(3)\fP, \fICURLOPT_DEBUGDATA(3)\fP,
\fICURLOPT_PROGRESSFUNCTION(3)\fP, \fICURLOPT_XFERINFOFUNCTION(3)\fP,
\fICURLOPT_PROGRESSDATA(3)\fP and \fICURLOPT_XFERINFODATA(3)\fP.

It is then up to the application to alter/set any options if desired.

\fIeasy\fP is a newly created handle that represents this upcoming transfer.

\fInum_headers\fP is the number of name+value pairs that was received and can
be accessed

\fIheaders\fP is a handle used to access push headers using the accessor
functions described below. This only accesses and provides the PUSH_PROMISE
headers, the normal response headers are provided in the header callback as
usual.

\fIclientp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP

If the callback returns CURL_PUSH_OK, the new easy handle is added to the
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: \fIcurl_pushheader_byname(3)\fP and
\fIcurl_pushheader_bynum(3)\fP. The normal response headers are passed to the header
callback for pushed streams like 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,
the ownership of the curl handle has been taken over by the application.
.IP "CURL_PUSH_DENY (1)"
The callback denies the stream and no data reaches the application, the easy
handle is destroyed by libcurl.
.IP "CURL_PUSH_ERROROUT (2)"
Returning this code rejects the pushed stream and returns an error back on the
parent stream making it get closed with an error. (Added in 7.72.0)
.IP *
All other return codes are reserved for future use.
.SH DEFAULT
NULL, no callback
.SH PROTOCOLS
This functionality affects http only
.SH EXAMPLE
.nf
#include <string.h>

/* only allow pushes for filenames starting with "push-" */
static int 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;
}

int main(void)
{
  int counter;
  CURLM *multi = curl_multi_init();
  curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
  curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
}
.fi
.SH AVAILABILITY
Added in curl 7.44.0
.SH RETURN VALUE
\fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error.

CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR CURLMOPT_PIPELINING (3),
.BR CURLMOPT_PUSHDATA (3),
.BR CURLOPT_PIPEWAIT (3),
.BR RFC 7540