<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
<meta name="generator" content="Hugo 0.30.2" />
<title>Nine Nines: cowboy_req:read_urlencoded_body(3)</title>
<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'>
<link href="/css/99s.css?r=1" rel="stylesheet">
<link rel="shortcut icon" href="/img/ico/favicon.ico">
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png">
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png">
<link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png">
</head>
<body class="">
<header id="page-head">
<div id="topbar" class="container">
<div class="row">
<div class="span2">
<h1 id="logo"><a href="/" title="99s">99s</a></h1>
</div>
<div class="span10">
<div id="side-header">
<nav>
<ul>
<li><a title="Hear my thoughts" href="/articles">Articles</a></li>
<li><a title="Watch my talks" href="/talks">Talks</a></li>
<li class="active"><a title="Read the docs" href="/docs">Documentation</a></li>
<li><a title="Request my services" href="/services">Consulting & Training</a></li>
</ul>
</nav>
<ul id="social">
<li>
<a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a>
</li>
<li>
<a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a>
</li>
<li>
<a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a>
</li>
</ul>
</div>
</div>
</div>
</div>
</header>
<div id="contents" class="two_col">
<div class="container">
<div class="row">
<div id="docs" class="span9 maincol">
<h1 class="lined-header"><span>cowboy_req:read_urlencoded_body(3)</span></h1>
<div class="sect1">
<h2 id="_name">Name</h2>
<div class="sectionbody">
<div class="paragraph"><p>cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_description">Description</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
<span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span>, #{})
<span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
<span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>}
<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()
<span style="color: #009900">Body</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div>
<div class="paragraph"><p>Read and parse a urlencoded request body.</p></div>
<div class="paragraph"><p>This function reads the request body and parses it as
<code>application/x-www-form-urlencoded</code>. It returns a list
of key/values.</p></div>
<div class="paragraph"><p>The urlencoded media type is used by Web browsers when
submitting HTML forms using the POST method.</p></div>
<div class="paragraph"><p>Cowboy needs to read the full body before parsing. By default
it will read bodies of size up to 64KB. It is possible to
provide options to read larger bodies if required.</p></div>
<div class="paragraph"><p>Cowboy will automatically handle protocol details including
the expect header, chunked transfer-encoding and others.</p></div>
<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length
header if it was not previously provided.</p></div>
<div class="paragraph"><p>This function can only be called once. Calling it again will
result in undefined behavior.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_arguments">Arguments</h2>
<div class="sectionbody">
<div class="dlist"><dl>
<dt class="hdlist1">
Req
</dt>
<dd>
<p>
The Req object.
</p>
</dd>
<dt class="hdlist1">
Opts
</dt>
<dd>
<p>
A map of body reading options. Please refer to
<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
for details about each option.
</p>
<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code>
to 5 seconds.</p></div>
</dd>
</dl></div>
</div>
</div>
<div class="sect1">
<h2 id="_return_value">Return value</h2>
<div class="sectionbody">
<div class="paragraph"><p>An <code>ok</code> tuple is returned containing a list of key/values found
in the body.</p></div>
<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
onward. It contains a more up to date representation of the request.
For example it may have an added content-length header once the
body has been read.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_changelog">Changelog</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
<strong>2.0</strong>: Function introduced. Replaces <code>body_qs/1,2</code>.
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_examples">Examples</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="title">Read a urlencoded body</div>
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>),
{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #993399">1</span>, <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div>
<div class="listingblock">
<div class="title">Allow large urlencoded bodies</div>
<div class="content"><!-- Generator: GNU source-highlight 3.1.8
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_urlencoded_body</span></span>(<span style="color: #009900">Req0</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">1000000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">See also</h2>
<div class="sectionbody">
<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
</div>
</div>
</div>
<div class="span3 sidecol">
<h3>
Cowboy
2.2
Function Reference
</h3>
<ul>
<li><a href="/docs/en/cowboy/2.2/guide">User Guide</a></li>
<li><a href="/docs/en/cowboy/2.2/manual">Function Reference</a></li>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/cowboy/2.2/manual">2.2</a></li>
<li><a href="/docs/en/cowboy/2.1/manual">2.1</a></li>
<li><a href="/docs/en/cowboy/2.0/manual">2.0</a></li>
<li><a href="/docs/en/cowboy/1.0/manual">1.0</a></li>
</ul>
</div>
</div>
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="span6">
<p id="scroll-top"><a href="#">↑ Scroll to top</a></p>
<nav>
<ul>
<li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li>
</ul>
</nav>
</div>
<div class="span6 credits">
<p><img src="/img/footer_logo.png"></p>
<p>Copyright © Loïc Hoguin 2012-2016</p>
</div>
</div>
</div>
</footer>
<script src="/js/custom.js"></script>
</body>
</html>
