= gun:headers(3)

== Name

gun:headers - Initiate the given request

== Description

[source,erlang]
----
headers(ConnPid, Method, Path, Headers)
    -> headers(ConnPid, Method, Path, Headers, #{})

headers(ConnPid, Method, Path, Headers, ReqOpts)
    -> StreamRef

ConnPid   :: pid()
Method    :: binary()
Path      :: iodata()
Headers   :: gun:req_headers()
ReqOpts   :: gun:req_opts()
StreamRef :: gun:stream_ref()
----

Initiate the given request.

This is a general purpose function that should only be
used when other method-specific functions do not apply.

The function `headers/4,5` initiates a request but does
not send the request body. It must be sent separately
using link:man:gun:data(3)[gun:data(3)].

== Arguments

ConnPid::

The pid of the Gun connection process.

Method::

Method to be used for the request.

Path::

Path to the resource.

Headers::

Additional request headers.

ReqOpts::

Request options.

== Return value

A reference that identifies the newly created stream is
returned. It is this reference that must be passed in
subsequent calls and will be received in messages related
to this new stream.

== Changelog

* *2.0*: Function introduced.

== Examples

.Initiate a request
[source,erlang]
----
StreamRef = gun:headers(ConnPid, <<"PUT">>,
    "/lang/fr_FR/hello",
    [{<<"content-type">>, <<"text/plain">>}]).
----

== See also

link:man:gun(3)[gun(3)],
link:man:gun:request(3)[gun:request(3)],
link:man:gun:await(3)[gun:await(3)],
link:man:gun:await_body(3)[gun:await_body(3)],
link:man:gun_push(3)[gun_push(3)],
link:man:gun_inform(3)[gun_inform(3)],
link:man:gun_response(3)[gun_response(3)],
link:man:gun_data(3)[gun_data(3)]