---
name: "CURLMOPT_PUSHFUNCTION"
section: "3"
platform: "linux"
package: "curl"
version: "8.23.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/CURLMOPT_PUSHFUNCTION"
---

# CURLMOPT\_PUSHFUNCTION(3)

callback that approves or denies server pushes

## NAME

CURLMOPT\_PUSHFUNCTION - callback that approves or denies server pushes

## SYNOPSIS

```
#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);
```

## 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.

## CALLBACK DESCRIPTION

The callback gets its arguments like this:

*parent* is the handle of the stream on which this push arrives. The new handle has the following options duplicated from the parent: *[CURLOPT\_WRITEFUNCTION(3)](/CURLOPT_WRITEFUNCTION/3.md)*, *[CURLOPT\_WRITEDATA(3)](/CURLOPT_WRITEDATA/3.md)*, *[CURLOPT\_HEADERFUNCTION(3)](/CURLOPT_HEADERFUNCTION/3.md)*, *[CURLOPT\_HEADERDATA(3)](/CURLOPT_HEADERDATA/3.md)*, *[CURLOPT\_DEBUGFUNCTION(3)](/CURLOPT_DEBUGFUNCTION/3.md)*, *[CURLOPT\_DEBUGDATA(3)](/CURLOPT_DEBUGDATA/3.md)*, *[CURLOPT\_PROGRESSFUNCTION(3)](/CURLOPT_PROGRESSFUNCTION/3.md)*, *[CURLOPT\_XFERINFOFUNCTION(3)](/CURLOPT_XFERINFOFUNCTION/3.md)*, *[CURLOPT\_PROGRESSDATA(3)](/CURLOPT_PROGRESSDATA/3.md)* and *[CURLOPT\_XFERINFODATA(3)](/CURLOPT_XFERINFODATA/3.md)*.

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

*easy* is a newly created handle that represents this upcoming transfer.

*num\_headers* is the number of name+value pairs that was received and can be accessed

*headers* 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.

*clientp* is the pointer set with *[CURLMOPT\_PUSHDATA(3)](/CURLMOPT_PUSHDATA/3.md)*

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: *[curl\_pushheader\_byname(3)](/curl_pushheader_byname/3.md)* and *[curl\_pushheader\_bynum(3)](/curl_pushheader_bynum/3.md)*. 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 *[curl\_easy\_header(3)](/curl_easy_header/3.md)*, introduced in later libcurl versions.

## CALLBACK RETURN VALUE

- 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.

- CURL\_PUSH\_DENY (1)

  The callback denies the stream and no data reaches the application, the easy handle is destroyed by libcurl.

- 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)

- \*

  All other return codes are reserved for future use.

## DEFAULT

NULL, no callback

## PROTOCOLS

This functionality affects http only

## EXAMPLE

```
#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);
}
```

## AVAILABILITY

Added in curl 7.44.0

## RETURN VALUE

*[curl\_multi\_setopt(3)](/curl_multi_setopt/3.md)* returns a CURLMcode indicating success or error.

CURLM\_OK (0) means everything was OK, non-zero means an error occurred, see *[libcurl-errors(3)](/libcurl-errors/3.md)*.

## SEE ALSO

[**CURLMOPT\_PIPELINING**(3)](/CURLMOPT_PIPELINING/3.md), [**CURLMOPT\_PUSHDATA**(3)](/CURLMOPT_PUSHDATA/3.md), [**CURLOPT\_PIPEWAIT**(3)](/CURLOPT_PIPEWAIT/3.md), **RFC**7540