1 files changed, 71 insertions, 0 deletions
diff --git a/doc/src/manual/ranch.recv_proxy_header.asciidoc b/doc/src/manual/ranch.recv_proxy_header.asciidoc
new file mode 100644
index 0000000..9f23bde
--- /dev/null
+++ b/doc/src/manual/ranch.recv_proxy_header.asciidoc
@@ -0,0 +1,71 @@
+= ranch:recv_proxy_header(3)
+
+== Name
+
+ranch:recv_proxy_header - Receive the PROXY protocol header
+
+== Description
+
+[source,erlang]
+----
+recv_proxy_header(ranch:ref(), timeout())
+    -> {ok, ranch_proxy_header:proxy_info()}
+     | {error, Reason :: atom()}
+     | {error, protocol_error, HumanReadable :: atom()}
+----
+
+Receive the PROXY protocol header.
+
+This function must be called before `ranch:handshake/1,2`
+on newly accepted connections to read and parse the PROXY
+protocol header, if any.
+
+== Arguments
+
+Ref::
+
+The listener name.
+
+Timeout::
+
+Receive timeout in milliseconds.
+
+== Return value
+
+An `ok` tuple is returned containing PROXY header information
+on success.
+
+An `error` 2-tuple is returned when a socket error occurs.
+
+An `error` 3-tuple is returned when a protocol error occurs
+and Ranch was not able to parse the PROXY header information.
+The third element contains a human-readable description of
+the error.
+
+== Changelog
+
+* *1.7*: Function introduced.
+
+== Examples
+
+.Receive the PROXY protocol header
+[source,erlang]
+----
+start_link(Ref, _, Transport, Opts) ->
+    Pid = proc_lib:spawn_link(?MODULE, init,
+        [Ref, Transport, Opts]),
+    {ok, Pid}.
+
+init(Ref, Transport, Opts) ->
+    {ok, ProxyInfo} = ranch:recv_proxy_header(Ref, 1000),
+    {ok, Socket} = ranch:handshake(Ref),
+    loop(#state{ref=Ref, socket=Socket, transport=Transport,
+        proxy_info=ProxyInfo, opts=Opts}).
+----
+
+== See also
+
+link:man:ranch:start_listener(3)[ranch:start_listener(3)],
+link:man:ranch:handshake(3)[ranch:handshake(3)],
+link:man:ranch:remove_connection(3)[ranch:remove_connection(3)],
+link:man:ranch(3)[ranch(3)]