On Thu, 31 Aug 2006, Mohun Biswas wrote:

> I do think this man page might benefit from a bit of grouping, or another
> way of clarifying which options go together.

Oh yeah. It is not very clear nor easy to read.

> 1. It appears that "filename" attributes are silently converted to lower
> case and basenamed. I.e. 'curl_formadd(CURLFORM_FILENAME, "/FOO/BAR")'
> results in "bar" being sent to the server according to my network analyzer.
> I took a quick look at RFCs 2388 and 2184 but didn't see this as a
> requirement anywhere. Is it?

No it isn't. I'd say it is a bug. But I can't see any code that lowercases the
string?

The stripping off the path is done for CURLFORM_FILE and it just happens to be
done for all file names, independently of how they are set. We should fix
this.

> 2. Some combinations are illegal yet not clearly shown so. For instance I
> have a buffer which I want to send as a file upload part but I need to free
> my copy before the transfer. Thus I want COPYCONTENTS (as opposed to
> PTRCONTENTS) behavior. I tried this combo:
>
> curl_formadd(&formpost, &lastpost,
> CURLFORM_CONTENTTYPE, "application/text; charset=UTF-8",
> CURLFORM_COPYNAME, partname,
> CURLFORM_FILENAME, filename, // seems not allowed
> CURLFORM_COPYCONTENTS, buf,
> CURLFORM_CONTENTSLENGTH, bytelen(buf),
> CURLFORM_END);
>
> which resulted in an empty form. Taking away CURLFORM_FILENAME made it work
> (as a non-file part). There seems to be no way to get COPY behavior for a
> file part using a pre-existing buffer.

FILENAME was added meant for the case where you use FILE but want to show
another file name in the part than what you use locally.

This example snippet does no file upload so setting file name for it makes
little sense. Of course creating an empty form is never the right thing to do.
It should either create a form as good as possible or return an error
indicating what the problem is.

> 3. Speaking of COPY behavior, I *suspect* the contract is that when you ask
> libcurl to copy contents for you they will be freed by curl_formfree(). But
> this is nowhere stated explicitly, at least not in the curl_formadd page.

Yes, that's exactly how it is (supposed to be).

> I would be happy to try contributing a doc patch to improve this once I
> understand it sufficiently.

I'm sure I'm not the only one who'd welcome such a contribution!

-- 
  Commercial curl and libcurl Technical Support: http://haxx.se/curl.html