<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.curl-setopt" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>curl_setopt</refname>
<refpurpose>Set an option for a cURL transfer</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>curl_setopt</methodname>
<methodparam><type>resource</type><parameter>ch</parameter></methodparam>
<methodparam><type>int</type><parameter>option</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<para>
Sets an option on the given cURL session handle.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
&curl.ch.description;
<varlistentry>
<term><parameter>option</parameter></term>
<listitem>
<para>
The <literal>CURLOPT_XXX</literal> option to set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
The value to be set on <parameter>option</parameter>.
</para>
<para>
<parameter>value</parameter> should be a <type>bool</type> for the
following values of the <parameter>option</parameter> parameter:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry valign="top">Option</entry>
<entry valign="top">Set <parameter>value</parameter> to</entry>
<entry valign="top">Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top"><constant>CURLOPT_AUTOREFERER</constant></entry>
<entry valign="top">
&true; to automatically set the <literal>Referer:</literal> field in
requests where it follows a <literal>Location:</literal> redirect.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_BINARYTRANSFER</constant></entry>
<entry valign="top">
&true; to return the raw output when
<constant>CURLOPT_RETURNTRANSFER</constant> is used.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_COOKIESESSION</constant></entry>
<entry valign="top">
&true; to mark this as a new cookie "session". It will force libcurl
to ignore all cookies it is about to load that are "session cookies"
from the previous session. By default, libcurl always stores and
loads all cookies, independent if they are session cookies or not.
Session cookies are cookies without expiry date and they are meant
to be alive and existing for this "session" only.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_CERTINFO</constant></entry>
<entry valign="top">
&true; to output SSL certification information to <literal>STDERR</literal>
on secure transfers.
</entry>
<entry valign="top">
Available since PHP 5.3.2. Requires <constant>CURLOPT_VERBOSE</constant> to be
on to have an effect.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_CRLF</constant></entry>
<entry valign="top">
&true; to convert Unix newlines to CRLF newlines
on transfers.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_DNS_USE_GLOBAL_CACHE</constant></entry>
<entry valign="top">
&true; to use a global DNS cache. This option is
not thread-safe and is enabled by default.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FAILONERROR</constant></entry>
<entry valign="top">
&true; to fail silently if the HTTP code returned
is greater than or equal to 400. The default behavior is to return
the page normally, ignoring the code.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FILETIME</constant></entry>
<entry valign="top">
&true; to attempt to retrieve the modification
date of the remote document. This value can be retrieved using
the <parameter>CURLINFO_FILETIME</parameter> option with
<function>curl_getinfo</function>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FOLLOWLOCATION</constant></entry>
<entry valign="top">
&true; to follow any
<literal>"Location: "</literal> header that the server sends as
part of the HTTP header (note this is recursive, PHP will follow as
many <literal>"Location: "</literal> headers that it is sent,
unless <constant>CURLOPT_MAXREDIRS</constant> is set).
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FORBID_REUSE</constant></entry>
<entry valign="top">
&true; to force the connection to explicitly
close when it has finished processing, and not be pooled for reuse.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FRESH_CONNECT</constant></entry>
<entry valign="top">
&true; to force the use of a new connection
instead of a cached one.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FTP_USE_EPRT</constant></entry>
<entry valign="top">
&true; to use EPRT (and LPRT) when doing active
FTP downloads. Use &false; to disable EPRT and LPRT and use PORT
only.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FTP_USE_EPSV</constant></entry>
<entry valign="top">
&true; to first try an EPSV command for FTP
transfers before reverting back to PASV. Set to &false;
to disable EPSV.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FTPAPPEND</constant></entry>
<entry valign="top">
&true; to append to the remote file instead of
overwriting it.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FTPASCII</constant></entry>
<entry valign="top">
An alias of
<constant>CURLOPT_TRANSFERTEXT</constant>. Use that instead.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FTPLISTONLY</constant></entry>
<entry valign="top">
&true; to only list the names of an FTP
directory.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_HEADER</constant></entry>
<entry valign="top">
&true; to include the header in the output.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry><constant>CURLINFO_HEADER_OUT</constant></entry>
<entry valign="top">
&true; to track the handle's request string.
</entry>
<entry valign="top">
Available since PHP 5.1.3. The <constant>CURLINFO_</constant>
prefix is intentional.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_HTTPGET</constant></entry>
<entry valign="top">
&true; to reset the HTTP request method to GET.
Since GET is the default, this is only necessary if the request
method has been changed.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_HTTPPROXYTUNNEL</constant></entry>
<entry valign="top">
&true; to tunnel through a given HTTP proxy.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_MUTE</constant></entry>
<entry valign="top">
&true; to be completely silent with regards to
the cURL functions.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_NETRC</constant></entry>
<entry valign="top">
&true; to scan the <filename>~/.netrc</filename>
file to find a username and password for the remote site that
a connection is being established with.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_NOBODY</constant></entry>
<entry valign="top">
&true; to exclude the body from the output.
Request method is then set to HEAD. Changing this to &false; does
not change it to GET.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_NOPROGRESS</constant></entry>
<entry valign="top"><para>
&true; to disable the progress meter for cURL transfers.
<note>
<para>
PHP automatically sets this option to &true;, this should only be
changed for debugging purposes.
</para>
</note>
</para></entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_NOSIGNAL</constant></entry>
<entry valign="top">
&true; to ignore any cURL function that causes a
signal to be sent to the PHP process. This is turned on by default
in multi-threaded SAPIs so timeout options can still be used.
</entry>
<entry valign="top">
Added in cURL 7.10.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_POST</constant></entry>
<entry valign="top">
&true; to do a regular HTTP POST. This POST is the
normal <literal>application/x-www-form-urlencoded</literal> kind,
most commonly used by HTML forms.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PUT</constant></entry>
<entry valign="top">
&true; to HTTP PUT a file. The file to PUT must
be set with <constant>CURLOPT_INFILE</constant> and
<constant>CURLOPT_INFILESIZE</constant>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_RETURNTRANSFER</constant></entry>
<entry valign="top">
&true; to return the transfer as a string of the
return value of <function>curl_exec</function> instead of outputting
it out directly.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSL_VERIFYPEER</constant></entry>
<entry valign="top">
&false; to stop cURL from verifying the peer's
certificate. Alternate certificates to verify against can be
specified with the <constant>CURLOPT_CAINFO</constant> option
or a certificate directory can be specified with the
<constant>CURLOPT_CAPATH</constant> option.
<constant>CURLOPT_SSL_VERIFYHOST</constant> may also need to be
&true; or &false; if
<constant>CURLOPT_SSL_VERIFYPEER</constant> is disabled (it
defaults to 2).
</entry>
<entry valign="top">
&true; by default as of cURL 7.10. Default bundle installed as of
cURL 7.10.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_TRANSFERTEXT</constant></entry>
<entry valign="top">
&true; to use ASCII mode for FTP transfers.
For LDAP, it retrieves data in plain text instead of HTML. On
Windows systems, it will not set <literal>STDOUT</literal> to binary
mode.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_UNRESTRICTED_AUTH</constant></entry>
<entry valign="top">
&true; to keep sending the username and password
when following locations (using
<constant>CURLOPT_FOLLOWLOCATION</constant>), even when the
hostname has changed.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_UPLOAD</constant></entry>
<entry valign="top">
&true; to prepare for an upload.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_VERBOSE</constant></entry>
<entry valign="top">
&true; to output verbose information. Writes
output to <literal>STDERR</literal>, or the file specified using
<constant>CURLOPT_STDERR</constant>.
</entry>
<entry valign="top">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
<parameter>value</parameter> should be an <type>integer</type> for the
following values of the <parameter>option</parameter> parameter:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Option</entry>
<entry>Set <parameter>value</parameter> to</entry>
<entry>Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top"><constant>CURLOPT_BUFFERSIZE</constant></entry>
<entry valign="top">
The size of the buffer to use for each read. There is no guarantee
this request will be fulfilled, however.
</entry>
<entry valign="top">
Added in cURL 7.10.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_CLOSEPOLICY</constant></entry>
<entry valign="top">
Either
<parameter>CURLCLOSEPOLICY_LEAST_RECENTLY_USED</parameter> or
<parameter>CURLCLOSEPOLICY_OLDEST</parameter>.
There are three other <literal>CURLCLOSEPOLICY_</literal>
constants, but cURL does not support them yet.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry><constant>CURLOPT_CONNECTTIMEOUT</constant></entry>
<entry valign="top">
The number of seconds to wait while trying to connect. Use 0 to
wait indefinitely.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_CONNECTTIMEOUT_MS</constant></entry>
<entry valign="top">
The number of milliseconds to wait while trying to connect. Use 0 to
wait indefinitely.
</entry>
<entry valign="top">
Added in cURL 7.16.2. Available since PHP 5.2.3.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_DNS_CACHE_TIMEOUT</constant></entry>
<entry valign="top">
The number of seconds to keep DNS entries in memory. This
option is set to 120 (2 minutes) by default.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FTPSSLAUTH</constant></entry>
<entry valign="top">
The FTP authentication method (when is activated):
<literal>CURLFTPAUTH_SSL</literal> (try SSL first),
<literal>CURLFTPAUTH_TLS</literal> (try TLS first), or
<literal>CURLFTPAUTH_DEFAULT</literal> (let cURL decide).
</entry>
<entry valign="top">
Added in cURL 7.12.2.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_HTTP_VERSION</constant></entry>
<entry valign="top">
<parameter>CURL_HTTP_VERSION_NONE</parameter> (default, lets CURL
decide which version to use),
<parameter>CURL_HTTP_VERSION_1_0</parameter> (forces HTTP/1.0),
or <parameter>CURL_HTTP_VERSION_1_1</parameter> (forces HTTP/1.1).
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_HTTPAUTH</constant></entry>
<entry valign="top">
<para>
The HTTP authentication method(s) to use. The options are:
<parameter>CURLAUTH_BASIC</parameter>,
<parameter>CURLAUTH_DIGEST</parameter>,
<parameter>CURLAUTH_GSSNEGOTIATE</parameter>,
<parameter>CURLAUTH_NTLM</parameter>,
<parameter>CURLAUTH_ANY</parameter>, and
<parameter>CURLAUTH_ANYSAFE</parameter>.
</para>
<para>
The bitwise <literal>|</literal> (or) operator can be used to combine
more than one method. If this is done, cURL will poll the server to see
what methods it supports and pick the best one.
</para>
<para>
<parameter>CURLAUTH_ANY</parameter> is an alias for
<literal>CURLAUTH_BASIC | CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM</literal>.
</para>
<para>
<parameter>CURLAUTH_ANYSAFE</parameter> is an alias for
<literal>CURLAUTH_DIGEST | CURLAUTH_GSSNEGOTIATE | CURLAUTH_NTLM</literal>.
</para>
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_INFILESIZE</constant></entry>
<entry valign="top">
The expected size, in bytes, of the file when uploading a file to a
remote site.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_LOW_SPEED_LIMIT</constant></entry>
<entry valign="top">
The transfer speed, in bytes per second, that the transfer should be
below during the count of <constant>CURLOPT_LOW_SPEED_TIME</constant>
seconds before PHP considers the transfer too slow and aborts.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_LOW_SPEED_TIME</constant></entry>
<entry valign="top">
The number of seconds the transfer speed should be below
<constant>CURLOPT_LOW_SPEED_LIMIT</constant> before PHP considers
the transfer too slow and aborts.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_MAXCONNECTS</constant></entry>
<entry valign="top">
The maximum amount of persistent connections that are allowed.
When the limit is reached,
<constant>CURLOPT_CLOSEPOLICY</constant> is used to determine
which connection to close.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_MAXREDIRS</constant></entry>
<entry valign="top">
The maximum amount of HTTP redirections to follow. Use this option
alongside <constant>CURLOPT_FOLLOWLOCATION</constant>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PORT</constant></entry>
<entry valign="top">
An alternative port number to connect to.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PROTOCOLS</constant></entry>
<entry valign="top">
<para>
Bitmask of <constant>CURLPROTO_*</constant> values. If used, this bitmask
limits what protocols libcurl may use in the transfer. This allows you to have
a libcurl built to support a wide range of protocols but still limit specific
transfers to only be allowed to use a subset of them. By default libcurl will
accept all protocols it supports.
See also <constant>CURLOPT_REDIR_PROTOCOLS</constant>.
</para>
<para>
Valid protocol options are:
<parameter>CURLPROTO_HTTP</parameter>,
<parameter>CURLPROTO_HTTPS</parameter>,
<parameter>CURLPROTO_FTP</parameter>,
<parameter>CURLPROTO_FTPS</parameter>,
<parameter>CURLPROTO_SCP</parameter>,
<parameter>CURLPROTO_SFTP</parameter>,
<parameter>CURLPROTO_TELNET</parameter>,
<parameter>CURLPROTO_LDAP</parameter>,
<parameter>CURLPROTO_LDAPS</parameter>,
<parameter>CURLPROTO_DICT</parameter>,
<parameter>CURLPROTO_FILE</parameter>,
<parameter>CURLPROTO_TFTP</parameter>,
<parameter>CURLPROTO_ALL</parameter>
</para>
</entry>
<entry valign="top">
Added in cURL 7.19.4.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PROXYAUTH</constant></entry>
<entry valign="top">
The HTTP authentication method(s) to use for the proxy connection.
Use the same bitmasks as described in
<constant>CURLOPT_HTTPAUTH</constant>. For proxy authentication,
only <parameter>CURLAUTH_BASIC</parameter> and
<parameter>CURLAUTH_NTLM</parameter> are currently supported.
</entry>
<entry valign="top">
Added in cURL 7.10.7.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PROXYPORT</constant></entry>
<entry valign="top">
The port number of the proxy to connect to. This port number can
also be set in <constant>CURLOPT_PROXY</constant>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PROXYTYPE</constant></entry>
<entry valign="top">
Either <parameter>CURLPROXY_HTTP</parameter> (default) or
<parameter>CURLPROXY_SOCKS5</parameter>.
</entry>
<entry valign="top">
Added in cURL 7.10.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_REDIR_PROTOCOLS</constant></entry>
<entry valign="top">
Bitmask of <constant>CURLPROTO_*</constant> values. If used, this bitmask
limits what protocols libcurl may use in a transfer that it follows to in
a redirect when <constant>CURLOPT_FOLLOWLOCATION</constant> is enabled.
This allows you to limit specific transfers to only be allowed to use a subset
of protocols in redirections. By default libcurl will allow all protocols
except for FILE and SCP. This is a difference compared to pre-7.19.4 versions
which unconditionally would follow to all protocols supported.
See also <constant>CURLOPT_PROTOCOLS</constant> for protocol constant values.
</entry>
<entry valign="top">
Added in cURL 7.19.4.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_RESUME_FROM</constant></entry>
<entry valign="top">
The offset, in bytes, to resume a transfer from.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSL_VERIFYHOST</constant></entry>
<entry valign="top">
1 to check the existence of a common name in the
SSL peer certificate. 2 to check the existence of
a common name and also verify that it matches the hostname
provided.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLVERSION</constant></entry>
<entry valign="top">
The SSL version (2 or 3) to use. By default PHP will try to determine
this itself, although in some cases this must be set manually.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_TIMECONDITION</constant></entry>
<entry valign="top">
How <constant>CURLOPT_TIMEVALUE</constant> is treated.
Use <parameter>CURL_TIMECOND_IFMODSINCE</parameter> to return the
page only if it has been modified since the time specified in
<constant>CURLOPT_TIMEVALUE</constant>. If it hasn't been modified,
a <literal>"304 Not Modified"</literal> header will be returned
assuming <constant>CURLOPT_HEADER</constant> is &true;.
Use <parameter>CURL_TIMECOND_IFUNMODSINCE</parameter> for the reverse
effect. <parameter>CURL_TIMECOND_IFMODSINCE</parameter> is the
default.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_TIMEOUT</constant></entry>
<entry valign="top">
The maximum number of seconds to allow cURL functions to execute.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_TIMEOUT_MS</constant></entry>
<entry valign="top">
The maximum number of milliseconds to allow cURL functions to
execute.
</entry>
<entry valign="top">
Added in cURL 7.16.2. Available since PHP 5.2.3.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_TIMEVALUE</constant></entry>
<entry valign="top">
The time in seconds since January 1st, 1970. The time will be used
by <constant>CURLOPT_TIMECONDITION</constant>. By default,
<parameter>CURL_TIMECOND_IFMODSINCE</parameter> is used.
</entry>
<entry valign="top">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
<parameter>value</parameter> should be a <type>string</type> for the
following values of the <parameter>option</parameter> parameter:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Option</entry>
<entry>Set <parameter>value</parameter> to</entry>
<entry>Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top"><constant>CURLOPT_CAINFO</constant></entry>
<entry valign="top">
The name of a file holding one or more certificates to verify the
peer with. This only makes sense when used in combination with
<constant>CURLOPT_SSL_VERIFYPEER</constant>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_CAPATH</constant></entry>
<entry valign="top">
A directory that holds multiple CA certificates. Use this option
alongside <constant>CURLOPT_SSL_VERIFYPEER</constant>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_COOKIE</constant></entry>
<entry valign="top">
The contents of the <literal>"Cookie: "</literal> header to be
used in the HTTP request.
Note that multiple cookies are separated with a semicolon followed
by a space (e.g., "<literal>fruit=apple; colour=red</literal>")
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_COOKIEFILE</constant></entry>
<entry valign="top">
The name of the file containing the cookie data. The cookie file can
be in Netscape format, or just plain HTTP-style headers dumped into
a file.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_COOKIEJAR</constant></entry>
<entry valign="top">
The name of a file to save all internal cookies to when the handle is closed,
e.g. after a call to curl_close.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_CUSTOMREQUEST</constant></entry>
<entry valign="top"><para>
A custom request method to use instead of
<literal>"GET"</literal> or <literal>"HEAD"</literal> when doing
a HTTP request. This is useful for doing
<literal>"DELETE"</literal> or other, more obscure HTTP requests.
Valid values are things like <literal>"GET"</literal>,
<literal>"POST"</literal>, <literal>"CONNECT"</literal> and so on;
i.e. Do not enter a whole HTTP request line here. For instance,
entering <literal>"GET /index.html HTTP/1.0\r\n\r\n"</literal>
would be incorrect.
<note>
<para>
Don't do this without making sure the server supports the custom
request method first.
</para>
</note>
</para></entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_EGDSOCKET</constant></entry>
<entry valign="top">
Like <constant>CURLOPT_RANDOM_FILE</constant>, except a filename
to an Entropy Gathering Daemon socket.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_ENCODING</constant></entry>
<entry valign="top">
The contents of the <literal>"Accept-Encoding: "</literal> header.
This enables decoding of the response. Supported encodings are
<literal>"identity"</literal>, <literal>"deflate"</literal>, and
<literal>"gzip"</literal>. If an empty string, <literal>""</literal>,
is set, a header containing all supported encoding types is sent.
</entry>
<entry valign="top">
Added in cURL 7.10.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_FTPPORT</constant></entry>
<entry valign="top">
The value which will be used to get the IP address to use
for the FTP "POST" instruction. The "POST" instruction tells
the remote server to connect to our specified IP address. The
string may be a plain IP address, a hostname, a network
interface name (under Unix), or just a plain '-' to use the
systems default IP address.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_INTERFACE</constant></entry>
<entry valign="top">
The name of the outgoing network interface to use. This can be an
interface name, an IP address or a host name.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_KRB4LEVEL</constant></entry>
<entry valign="top">
The KRB4 (Kerberos 4) security level. Any of the following values
(in order from least to most powerful) are valid:
<literal>"clear"</literal>,
<literal>"safe"</literal>,
<literal>"confidential"</literal>,
<literal>"private".</literal>.
If the string does not match one of these,
<literal>"private"</literal> is used. Setting this option to &null;
will disable KRB4 security. Currently KRB4 security only works
with FTP transactions.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_POSTFIELDS</constant></entry>
<entry valign="top">
<simpara>
The full data to post in a HTTP "POST" operation.
To post a file, prepend a filename with <literal>@</literal> and
use the full path. This can either be passed as a urlencoded
string like '<literal>para1=val1&para2=val2&...</literal>'
or as an array with the field name as key and field data as value.
If <parameter>value</parameter> is an array, the
<literal>Content-Type</literal> header will be set to
<literal>multipart/form-data</literal>.
</simpara>
<simpara>
As of PHP 5.2.0, files thats passed to this option with the
<literal>@</literal> prefix must be in array form to work.
</simpara>
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PROXY</constant></entry>
<entry valign="top">
The HTTP proxy to tunnel requests through.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PROXYUSERPWD</constant></entry>
<entry valign="top">
A username and password formatted as
<literal>"[username]:[password]"</literal> to use for the
connection to the proxy.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_RANDOM_FILE</constant></entry>
<entry valign="top">
A filename to be used to seed the random number generator for SSL.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_RANGE</constant></entry>
<entry valign="top">
Range(s) of data to retrieve in the format
<literal>"X-Y"</literal> where X or Y are optional. HTTP transfers
also support several intervals, separated with commas in the format
<literal>"X-Y,N-M"</literal>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_REFERER</constant></entry>
<entry valign="top">
The contents of the <literal>"Referer: "</literal> header to be used
in a HTTP request.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSL_CIPHER_LIST</constant></entry>
<entry valign="top">
A list of ciphers to use for SSL. For example,
<literal>RC4-SHA</literal> and <literal>TLSv1</literal> are valid
cipher lists.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLCERT</constant></entry>
<entry valign="top">
The name of a file containing a PEM formatted certificate.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLCERTPASSWD</constant></entry>
<entry valign="top">
The password required to use the
<constant>CURLOPT_SSLCERT</constant> certificate.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLCERTTYPE</constant></entry>
<entry valign="top">
The format of the certificate. Supported formats are
<literal>"PEM"</literal> (default), <literal>"DER"</literal>,
and <literal>"ENG"</literal>.
</entry>
<entry valign="top">
Added in cURL 7.9.3.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLENGINE</constant></entry>
<entry valign="top">
The identifier for the crypto engine of the private SSL key
specified in <constant>CURLOPT_SSLKEY</constant>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLENGINE_DEFAULT</constant></entry>
<entry valign="top">
The identifier for the crypto engine used for asymmetric crypto
operations.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLKEY</constant></entry>
<entry valign="top">
The name of a file containing a private SSL key.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLKEYPASSWD</constant></entry>
<entry valign="top"><para>
The secret password needed to use the private SSL key specified in
<constant>CURLOPT_SSLKEY</constant>.
<note>
<para>
Since this option contains a sensitive password, remember to keep
the PHP script it is contained within safe.
</para>
</note>
</para></entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_SSLKEYTYPE</constant></entry>
<entry valign="top">
The key type of the private SSL key specified in
<constant>CURLOPT_SSLKEY</constant>. Supported key types are
<literal>"PEM"</literal> (default), <literal>"DER"</literal>,
and <literal>"ENG"</literal>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_URL</constant></entry>
<entry valign="top">
The URL to fetch. This can also be set when initializing a
session with <function>curl_init</function>.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_USERAGENT</constant></entry>
<entry valign="top">
The contents of the <literal>"User-Agent: "</literal> header to be
used in a HTTP request.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_USERPWD</constant></entry>
<entry valign="top">
A username and password formatted as
<literal>"[username]:[password]"</literal> to use for the
connection.
</entry>
<entry valign="top">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
<parameter>value</parameter> should be an array for the
following values of the <parameter>option</parameter> parameter:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Option</entry>
<entry>Set <parameter>value</parameter> to</entry>
<entry>Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top"><constant>CURLOPT_HTTP200ALIASES</constant></entry>
<entry valign="top">
An array of HTTP 200 responses that will be treated as valid
responses and not as errors.
</entry>
<entry valign="top">
Added in cURL 7.10.3.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_HTTPHEADER</constant></entry>
<entry valign="top">
An array of HTTP header fields to set, in the format
<code>
array('Content-type: text/plain', 'Content-length: 100')
</code>
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_POSTQUOTE</constant></entry>
<entry valign="top">
An array of FTP commands to execute on the server after the FTP
request has been performed.
</entry>
<entry valign="top">
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_QUOTE</constant></entry>
<entry valign="top">
An array of FTP commands to execute on the server prior to the FTP
request.
</entry>
<entry valign="top">
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
<parameter>value</parameter> should be a stream resource (using
<function>fopen</function>, for example) for the following values of the
<parameter>option</parameter> parameter:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Option</entry>
<entry>Set <parameter>value</parameter> to</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top"><constant>CURLOPT_FILE</constant></entry>
<entry valign="top">
The file that the transfer should be written to. The default
is <literal>STDOUT</literal> (the browser window).
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_INFILE</constant></entry>
<entry valign="top">
The file that the transfer should be read from when uploading.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_STDERR</constant></entry>
<entry valign="top">
An alternative location to output errors to instead of
<literal>STDERR</literal>.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_WRITEHEADER</constant></entry>
<entry valign="top">
The file that the header part of the transfer is written to.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
<parameter>value</parameter> should be a string that is the name of a valid
callback function for the following values of the
<parameter>option</parameter> parameter:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Option</entry>
<entry>Set <parameter>value</parameter> to</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top"><constant>CURLOPT_HEADERFUNCTION</constant></entry>
<entry valign="top">
The name of a callback function where the callback function takes
two parameters. The first is the cURL resource, the second is a
string with the header data to be written. The header data must
be written when using this callback function. Return the number of
bytes written.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PASSWDFUNCTION</constant></entry>
<entry valign="top">
The name of a callback function where the callback function takes
three parameters. The first is the cURL resource, the second is a
string containing a password prompt, and the third is the maximum
password length. Return the string containing the password.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_PROGRESSFUNCTION</constant></entry>
<entry valign="top">
The name of a callback function where the callback function takes
three parameters. The first is the cURL resource, the second is a
file-descriptor resource, and the third is length. Return the
string containing the data.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_READFUNCTION</constant></entry>
<entry valign="top">
The name of a callback function where the callback function takes
two parameters. The first is the cURL resource, and the second is a
string with the data to be read. The data must be read by using this
callback function. Return the number of bytes read. Return 0 to signal
<literal>EOF</literal>.
</entry>
</row>
<row>
<entry valign="top"><constant>CURLOPT_WRITEFUNCTION</constant></entry>
<entry valign="top">
The name of a callback function where the callback function takes
two parameters. The first is the cURL resource, and the second is a
string with the data to be written. The data must be saved by using
this callback function. It must return the exact number of bytes written
or the transfer will be aborted with an error.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.2.10</entry>
<entry>
Introduced <constant>CURLOPT_PROTOCOLS</constant>, and
<constant>CURLOPT_REDIR_PROTOCOLS</constant>.
</entry>
</row>
<row>
<entry>5.1.0</entry>
<entry>
Introduced <constant>CURLOPT_AUTOREFERER</constant>,
<constant>CURLOPT_BINARYTRANSFER</constant>,
<constant>CURLOPT_FTPSSLAUTH</constant>,
<constant>CURLOPT_PROXYAUTH</constant>, and
<constant>CURLOPT_TIMECONDITION</constant>.
</entry>
</row>
<row>
<entry>5.0.0</entry>
<entry>
Introduced <constant>CURLOPT_FTP_USE_EPRT</constant>,
<constant>CURLOPT_NOSIGNAL</constant>,
<constant>CURLOPT_UNRESTRICTED_AUTH</constant>,
<constant>CURLOPT_BUFFERSIZE</constant>,
<constant>CURLOPT_HTTPAUTH</constant>,
<constant>CURLOPT_PROXYPORT</constant>,
<constant>CURLOPT_PROXYTYPE</constant>,
<constant>CURLOPT_SSLCERTTYPE</constant>, and
<constant>CURLOPT_HTTP200ALIASES</constant>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Initializing a new cURL session and fetching a web page</title>
<programlisting role="php">
<![CDATA[
<?php
// create a new cURL resource
$ch = curl_init();
// set URL and other appropriate options
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, false);
// grab URL and pass it to the browser
curl_exec($ch);
// close cURL resource, and free up system resources
curl_close($ch);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Uploading file</title>
<programlisting role="php">
<![CDATA[
<?php
/* http://localhost/upload.php:
print_r($_POST);
print_r($_FILES);
*/
$ch = curl_init();
$data = array('name' => 'Foo', 'file' => '@/home/user/test.png');
curl_setopt($ch, CURLOPT_URL, 'http://localhost/upload.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_exec($ch);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Array
(
[name] => Foo
)
Array
(
[file] => Array
(
[name] => test.png
[type] => image/png
[tmp_name] => /tmp/phpcpjNeQ
[error] => 0
[size] => 279
)
)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
Passing an array to <constant>CURLOPT_POSTFIELDS</constant> will
encode the data as <emphasis>multipart/form-data</emphasis>,
while passing a URL-encoded string will encode the data as
<emphasis>application/x-www-form-urlencoded</emphasis>.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>curl_setopt_array</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->