Description:
------------
I believe something not unlike this should appear in the manual.

I'm not quite up to speed on adding it myself.

Sorry.



CURLOPT_BINARYTRANSER
This option is not documented by the curl package because it is a PHP-specific option.
[nb: This is the crucial reason why I think php.net should document it more than the rest of CURLOPT_*]

It should be set to TRUE when using curl to retrieve binary data such as images, zip files, etc.
It should remain set to FALSE (the default) to retrieve plain text such as HTML or .txt

Example:
<?php
  $curl = curl_init();
  
  //Normal retrieval of text:
  curl_setopt($curl, CURLOPT_URL, 'http://php.net/');
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
  $html = curl_exec($curl);
  echo 'html is: ', htmlentities(substr($html, 0, 4)), ' ... ', htmlentities(substr($html, -7)), "<br />\n";
  
  //Retrieval of an image (or other binary data):
  curl_setopt($curl, CURLOPT_URL, 'http://static.php.net/www.php.net/images/php.gif');
  curl_setopt($curl, CURLOPT_BINARYTRANSFER, 1);
  $image = curl_exec($curl);
  echo 'image is: ', htmlentities(substr($image, 0, 4)), "...<br />\n";
  
  //Switch back to normal text:
  curl_setopt($curl, CURLOPT_URL, 'http://php.net/');
  curl_setopt($curl, CURLOPT_BINARYTRANSFER, 1);
  $html = curl_exec($curl);
  echo 'html is: ', htmlentities(substr($html, 0, 4)), ' ... ', htmlentities(substr($html, -7)), "<br />\n";
?>

NOTE:
Some versions of PHP were known to be buggy when switching CURLOPT_BINARYTRANSFER through false/true/false settings in the same curl handle.
See http://bugs.php.net/bug.php?id=37061


Reproduce code:
---------------
I spent a fair amount of time on the curl site trying to find this CURLOPT_BINARYTRANSFER

I also spent a fair amount of Googling and asking on the mailing list.

It took several days of effort to realize that it just plain wasn't really documented well anywhere.


Expected result:
----------------
Since this option is introduced by PHP source and is php-specific I expected to see it documented on php.net