diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libcurl/Makefile.inc | 6 | ||||
| -rw-r--r-- | docs/libcurl/curl_easy_setopt.3 | 2 | ||||
| -rw-r--r-- | docs/libcurl/curl_formadd.3 | 11 | ||||
| -rw-r--r-- | docs/libcurl/curl_formfree.3 | 8 | ||||
| -rw-r--r-- | docs/libcurl/curl_formget.3 | 7 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_addpart.3 | 52 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_data.3 | 54 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_data_cb.3 | 154 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_filedata.3 | 55 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_filename.3 | 51 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_free.3 | 48 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_headers.3 | 50 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_init.3 | 68 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_name.3 | 52 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_subparts.3 | 52 | ||||
| -rw-r--r-- | docs/libcurl/curl_mime_type.3 | 62 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_HTTPPOST.3 | 11 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_MIMEPOST.3 | 52 | ||||
| -rw-r--r-- | docs/libcurl/opts/Makefile.inc | 1 | ||||
| -rw-r--r-- | docs/libcurl/symbols-in-versions | 1 |
20 files changed, 784 insertions, 13 deletions
diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc index 580fe563f..2414ecc12 100644 --- a/docs/libcurl/Makefile.inc +++ b/docs/libcurl/Makefile.inc @@ -17,4 +17,8 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \ curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 \ curl_multi_socket_action.3 curl_multi_wait.3 libcurl-symbols.3 \ - libcurl-thread.3 curl_multi_socket_all.3 curl_global_sslset.3 + libcurl-thread.3 curl_multi_socket_all.3 curl_global_sslset.3 \ + curl_mime_init.3 curl_mime_free.3 curl_mime_addpart.3 curl_mime_name.3 \ + curl_mime_data.3 curl_mime_data_cb.3 curl_mime_filedata.3 \ + curl_mime_filename.3 curl_mime_subparts.3 \ + curl_mime_type.3 curl_mime_headers.3 diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 01dfa85b6..2982056f0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -411,6 +411,8 @@ Size of file to send. \fICURLOPT_INFILESIZE(3)\fP Size of file to send. \fICURLOPT_INFILESIZE_LARGE(3)\fP .IP CURLOPT_UPLOAD Upload data. See \fICURLOPT_UPLOAD(3)\fP +.IP CURLOPT_MIMEPOST +Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP .IP CURLOPT_MAXFILESIZE Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP .IP CURLOPT_MAXFILESIZE_LARGE diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 5d1faa532..652663b7c 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -29,6 +29,8 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .BI "struct curl_httppost ** " lastitem, " ...);" .ad .SH DESCRIPTION +This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead! + curl_formadd() is used to append sections when building a multipart/formdata HTTP POST (sometimes referred to as RFC2388-style posts). Append one section at a time until you've added all the sections you want included and then you @@ -169,6 +171,8 @@ the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after you've called \fIcurl_easy_cleanup(3)\fP for the curl handle. See example below. +.SH AVAILABILITY +Deprecated in 7.56.0. .SH RETURN VALUE 0 means everything was ok, non-zero means an error occurred corresponding to a CURL_FORMADD_* constant defined in @@ -254,5 +258,6 @@ to a CURL_FORMADD_* constant defined in curl_easy_setopt(curl, CURLOPT_HTTPPOST, post); .SH "SEE ALSO" -.BR curl_easy_setopt "(3), " -.BR curl_formfree "(3)" +.BR curl_easy_setopt "(3)," +.BR curl_formfree "(3)," +.BR curl_mime_init "(3)" diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index a2536cd9e..dd00494be 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -28,6 +28,8 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain .BI "void curl_formfree(struct curl_httppost *" form); .ad .SH DESCRIPTION +This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead! + curl_formfree() is used to clean up data previously built/appended with \fIcurl_formadd(3)\fP. This must be called when the data has been used, which typically means after \fIcurl_easy_perform(3)\fP has been called. @@ -38,7 +40,9 @@ the \fIcurl_formadd(3)\fP invoke(s). \fBform\fP is the pointer as returned from a previous call to \fIcurl_formadd(3)\fP and may be NULL. +.SH AVAILABILITY +Deprecated in 7.56.0. .SH RETURN VALUE None .SH "SEE ALSO" -.BR curl_formadd "(3) " +.BR curl_formadd "(3), " curl_mime_init "(3), " curl_mime_free "(3)" diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index 635c487f5..0d947253a 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -65,6 +65,7 @@ request as only then will libcurl get the actual read callback to use! return total_size; } .SH AVAILABILITY -This function was added in libcurl 7.15.5 +This function was added in libcurl 7.15.5. The form API is deprecated in +libcurl 7.56.0. .SH "SEE ALSO" -.BR curl_formadd "(3) " +.BR curl_formadd "(3), " curl_mime_init "(3)" diff --git a/docs/libcurl/curl_mime_addpart.3 b/docs/libcurl/curl_mime_addpart.3 new file mode 100644 index 000000000..4a86f3813 --- /dev/null +++ b/docs/libcurl/curl_mime_addpart.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_addpart 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_addpart - append a new empty part to a mime structure +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "curl_mimepart * curl_mime_addpart(curl_mime * " mime ");" +.ad +.SH DESCRIPTION +curl_mime_addpart() appends a new empty part to the given mime structure and +returns a handle to it. +The returned part can be subsequently filled using functions from the mime API. + +\fImime\fP is the handle of the mime structure in which the new part must be +appended. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +A mime part structure handle, or NULL upon failure. + +.SH "SEE ALSO" +.BR curl_mime_init "(3)," +.BR curl_mime_name "(3)," +.BR curl_mime_data "(3)," +.BR curl_mime_data_cb "(3)," +.BR curl_mime_filedata "(3)," +.BR curl_mime_filename "(3)," +.BR curl_mime_subparts "(3)," +.BR curl_mime_type "(3)," +.BR curl_mime_headers "(3)" diff --git a/docs/libcurl/curl_mime_data.3 b/docs/libcurl/curl_mime_data.3 new file mode 100644 index 000000000..4ce41c38a --- /dev/null +++ b/docs/libcurl/curl_mime_data.3 @@ -0,0 +1,54 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_data 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_data - set a mime part's body data from memory +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "CURLcode curl_mime_data(curl_mimepart * " part ", const char * " data +.BI ", ssize_t " datasize ");" +.ad +.SH DESCRIPTION +curl_mime_data() sets a mime part's body content from memory data. + +\fIdata\fP points to the data bytes: those are copied to the part and their +storage may safely be reused after call. +\fIdatasize\fP is the number of data bytes: it can be set to -1 to indicate +\fIdata\fP is a nul-terminated character string. +\fIpart\fP is the part's to assign contents to. + +Setting a part's contents twice is valid: only the value set by the last call +is retained. It is possible to unassign part's contents by setting +\fIdata\fP to NULL. + +Setting very large data is memory consuming: one might consider using +\fIcurl_mime_data_cb\fP() in such a case. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)," +.BR curl_mime_data_cb "(3)" diff --git a/docs/libcurl/curl_mime_data_cb.3 b/docs/libcurl/curl_mime_data_cb.3 new file mode 100644 index 000000000..64e5c7dc0 --- /dev/null +++ b/docs/libcurl/curl_mime_data_cb.3 @@ -0,0 +1,154 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_data_cb 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_data_cb - set a callback-based data source for a mime part's body +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg); +.br +int seekfunc(void *arg, curl_off_t offset, int origin); +.br +void freefunc(void *arg); +.sp +.BI "CURLcode curl_mime_data(curl_mimepart * " part ", curl_off_t " datasize , +.br +.BI " curl_read_callback " readfunc ", curl_seek_callback " seekfunc , +.br +.BI " curl_free_callback " freefunc ", void * " arg ");" +.ad +.SH DESCRIPTION +curl_mime_data_cb() sets the data source of a mime part's body content from +a data read callback function. + +\fIpart\fP is the part's to assign contents to. +\fIreadfunc\fP is a pointer to a data read callback function, with a +signature as shown by the above prototype. It may not be set to NULL. +\fIseekfunc\fP is a pointer to a seek callback function, with a +signature as shown by the above prototype. This function will be used upon +resending data (i.e.: after a redirect); this pointer may be set to NULL, +in which case a resend is not possible. +\fIfreefunc\fP is a pointer to a user resource freeing callback function, with +a signature as shown by the above prototype. If no resource is to be freed, +it may safely be set to NULL. This function will be called upon mime +structure freeing. +\fIarg\fP is a user defined argument to callback functions. + +The read callback function gets called by libcurl as soon as it needs to +read data in order to send it to the peer - like if you ask it to upload or +post data to the server. The data area pointed at by the pointer \fIbuffer\fP +should be filled up with at most \fIsize\fP multiplied with \fInmemb\fP number +of bytes by your function. + +Your read function must then return the actual number of bytes that it stored +in that memory area. Returning 0 will signal end-of-file to the library and +cause it to stop the current transfer. + +If you stop the current transfer by returning 0 "pre-maturely" (i.e before the +server expected it, like when you've said you will upload N bytes and you +upload less than N bytes), you may experience that the server "hangs" waiting +for the rest of the data that won't come. + +The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current +operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error +code from the transfer. + +The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this +connection to pause. See \fIcurl_easy_pause(3)\fP for further details. + +The seek function gets called by libcurl to rewind input stream data or to +seek to a certain position. The function shall work like fseek(3) or lseek(3) +and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, +although libcurl currently only passes SEEK_SET. + +The callback function must return \fICURL_SEEKFUNC_OK\fP on success, +\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or +\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl +is free to work around the problem if possible. The latter can sometimes be +done by instead reading from the input or similar. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. +.SH EXAMPLE +Sending a huge data string will cause the same amount of memory to be +allocated: to avoid overhead resources consumption, one might want to use a +callback source to avoid data duplication. In this case, original data +must be retained until after the transfer terminates. +.nf + +char hugedata[512000]; + +struct ctl { + char *buffer; + curl_off_t size; + curl_off_t position; +}; + +size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg) +{ + struct ctl *p = (struct ctl *) arg; + curl_off_t sz = p->size - p->position; + + nitems *= size; + if(sz > nitems) + sz = nitems; + if(sz) + memcpy(buffer, p->buffer + p->position, sz); + p->position += sz; + return sz; +} + +int seek_callback(void *arg, curl_off_t offset, int origin) +{ + struct ctl *p = (struct ctl *) arg; + + switch(origin) { + case SEEK_END: + offset += p->size; + break; + case SEEK_CUR: + offset += p->position; + break; + } + + if(offset < 0) + return CURL_SEEKFUNC_FAIL; + p->position = offset; + return CURL_SEEKFUNC_OK; +} + + CURL *easy = curl_easy_init(); + curl_mime *mime = curl_mime_init(easy); + curl_mimepart *part = curl_mime_addpart(mime); + struct ctl hugectl; + + hugectl.buffer = hugedata; + hugectl.size = sizeof hugedata; + hugectl.position = 0; + curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL, + &hugectl); + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)" diff --git a/docs/libcurl/curl_mime_filedata.3 b/docs/libcurl/curl_mime_filedata.3 new file mode 100644 index 000000000..fcd86cc18 --- /dev/null +++ b/docs/libcurl/curl_mime_filedata.3 @@ -0,0 +1,55 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_filedata 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_filedata - set a mime part's body data from a file contents +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "CURLcode curl_mime_filedata(curl_mimepart * " part , +.BI " const char * " filename ");" +.ad +.SH DESCRIPTION +curl_mime_filedata() sets a mime part's body content from the named file's +contents. + +\fIpart\fP is the part's to assign contents to. +\fIfilename\fP points to the nul-terminated file's path name. The pointer can +be NULL to detach previous part contents settings. +If \fIfilename\fP is "-", part contents data will be read from stdin. +Filename storage can be safely be reused after this call. + +As a side effect, the part's remote file name is set to the base name of the +given \fIfilename\fP if it is a valid named file. This can be undone or +overriden by a subsequent call to \fIcurl_mime_filename\fP(). + +Setting a part's contents twice is valid: only the value set by the last call +is retained. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)," +.BR curl_mime_filename "(3)" diff --git a/docs/libcurl/curl_mime_filename.3 b/docs/libcurl/curl_mime_filename.3 new file mode 100644 index 000000000..4c09402aa --- /dev/null +++ b/docs/libcurl/curl_mime_filename.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_filename 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_filename - set a mime part's remote file name +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "CURLcode curl_mime_filename(curl_mimepart * " part , +.BI "const char * " filename ");" +.ad +.SH DESCRIPTION +curl_mime_filename() sets a mime part's remote file name. When remote file +name is set, content data is processed as a file, whatever is the part's +content source. A part's remote file name is transmitted to the server in +the associated Content-Disposition generated header. + +\fIpart\fP is the part's handle to assign the remote file name to. +\fIfilename\fP points to the nul-terminated file name string; it may be set to +NULL to remove a previously attached remote file name. + +The remote file name string is copied into the part, thus the associated +storage may safely be released or reused after call. Setting a part's file +name twice is valid: only the value set by the last call is retained. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)" diff --git a/docs/libcurl/curl_mime_free.3 b/docs/libcurl/curl_mime_free.3 new file mode 100644 index 000000000..87fea127b --- /dev/null +++ b/docs/libcurl/curl_mime_free.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_free 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_free - free a previously built mime structure +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "void curl_mime_free(curl_mime *" mime); +.ad +.SH DESCRIPTION +curl_mime_free() is used to clean up data previously built/appended with +\fIcurl_mime_addpart(3)\fP and other mime-handling functions. +This must be called when the data has been used, which +typically means after \fIcurl_easy_perform(3)\fP has been called. + +The handle to free is the one you passed to +the \fICURLOPT_MIMEPOST(3)\fP option: attached subparts mime structures must +not be explicitly freed as they are by the top structure freeing. + +\fBmime\fP is the handle as returned from a previous call to +\fIcurl_mime_init(3)\fP and may be NULL. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +None +.SH "SEE ALSO" +.BR curl_mime_init "(3)" diff --git a/docs/libcurl/curl_mime_headers.3 b/docs/libcurl/curl_mime_headers.3 new file mode 100644 index 000000000..368c4d26c --- /dev/null +++ b/docs/libcurl/curl_mime_headers.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_headers 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_headers - set a mime part's custom headers +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "CURLcode curl_mime_headers(curl_mimepart * " part , +.BI "struct curl_slist * " headers ", int " take_ownership ");" +.ad +.SH DESCRIPTION +curl_mime_headers() sets a mime part's custom headers. + +\fIpart\fP is the part's handle to assign the custom headers list to. +\fIheaders\fP is the head of a list of custom headers; it may be set to +NULL to remove a previously attached custom header list. +\fItake_ownership\fP: when non-zero, causes the list to be freed upon +replacement or mime structure deletion; in this case the list must not be +freed explicitly. + +Setting a part's custom headers list twice is valid: only the value set by +the last call is retained. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)" diff --git a/docs/libcurl/curl_mime_init.3 b/docs/libcurl/curl_mime_init.3 new file mode 100644 index 000000000..601123c41 --- /dev/null +++ b/docs/libcurl/curl_mime_init.3 @@ -0,0 +1,68 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_init 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_init - create a mime handle +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "curl_mime * curl_mime_init(CURL * " easy_handle ");" +.ad +.SH DESCRIPTION +curl_mime_init() creates a handle to a new empty mime structure intended to be +used with \fIeasy_handle\fP. This mime structure can be subsequently filled +using the mime API, then attached to \fIeasy_handle\fP using option +\fICURLOPT_MIMEPOST\fP within a \fIcurl_easy_setopt\fP() call. + +Using a mime handle is the recommended way to post an HTTP form, format and +send a multi-part e-mail with SMTP or upload such an e-mail to an IMAP server. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +A mime struct handle, or NULL upon failure. +.SH EXAMPLE +.nf + + CURL *easy = curl_easy_init(); + struct curl_mime *mime; + struct mimepart *part; + + /* Build an HTTP form with a single field named "data", */ + mime = curl_mime_init(easy); + part = curl_mime_addpart(mime); + curl_mime_data(part, "This is the field data", -1); + curl_mime_name(part, "data", -1); + + /* Post and send it. */ + curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); + curl_easy_setopt(easy, CURLOPT_URL, "http://example.com"); + curl_easy_perform(easy); + + /* Clean-up. */ + curl_easy_cleanup(easy); + curl_mime_free(mime); + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)," +.BR curl_mime_free "(3)," +.BR CURLOPT_MIMEPOST "(3)" diff --git a/docs/libcurl/curl_mime_name.3 b/docs/libcurl/curl_mime_name.3 new file mode 100644 index 000000000..5ef7c887f --- /dev/null +++ b/docs/libcurl/curl_mime_name.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_name 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_name - set a mime part's name +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "CURLcode curl_mime_name(curl_mimepart * " part ", const char * " name +.BI ", ssize_t " namesize ");" +.ad +.SH DESCRIPTION +curl_mime_name() sets a mime part's name. This is the way HTTP form fields are +named. + +\fIname\fP points to the name byte string; the string may contain nul bytes +unless \fInamesize\fP is -1. +\fInamesize\fP is the name length: it can be set to -1 to indicate +\fIname\fP is a nul-terminated string. +\fIpart\fP is the part's handle to assign a name to. + +The name string is copied into the part, thus the associated storage may safely +be released or reused after call. Setting a part's name twice is valid: +only the value set by the last call is retained. It is possible to "unname" +a part by setting \fIname\fP to NULL. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)" diff --git a/docs/libcurl/curl_mime_subparts.3 b/docs/libcurl/curl_mime_subparts.3 new file mode 100644 index 000000000..3c607c586 --- /dev/null +++ b/docs/libcurl/curl_mime_subparts.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_subparts 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_subparts - set subparts of a multipart mime part +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "CURLcode curl_mime_subparts(curl_mimepart * " part , +.BI "curl_mime * " subparts ");" +.ad +.SH DESCRIPTION +curl_mime_subparts() sets a multipart mime part's content from a mime +structure. + +\fIpart\fP is a handle to the multipart part. +\fIsubparts\fP is a mime structure handle holding the subparts. After +\fIcurl_mime_subparts\fP succeeds, the mime structure handle belongs to the +multipart part and must not be freed explicitly. It may however be updated +by subsequent calls to mime API functions. + +Setting a part's contents twice is valid: only the value set by the last call +is retained. It is possible to unassign previous part's contents by setting +\fIsubparts\fP to NULL. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)," +.BR curl_mime_init "(3)" diff --git a/docs/libcurl/curl_mime_type.3 b/docs/libcurl/curl_mime_type.3 new file mode 100644 index 000000000..0c6cd3d6b --- /dev/null +++ b/docs/libcurl/curl_mime_type.3 @@ -0,0 +1,62 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_mime_type 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" +.SH NAME +curl_mime_type - set a mime part's content type +.SH SYNOPSIS +.B #include <curl/curl.h> +.sp +.BI "CURLcode curl_mime_type(curl_mimepart * " part , +.BI "const char * " mimetype ");" +.ad +.SH DESCRIPTION +curl_mime_type() sets a mime part's content type. + +\fIpart\fP is the part's handle to assign the content type to. +\fImimetype\fP points to the nul-terminated file mime type string; it may be +set to NULL to remove a previously attached mime type. + +The mime type string is copied into the part, thus the associated +storage may safely be released or reused after call. Setting a part's type +twice is valid: only the value set by the last call is retained. + +In the absence of a mime type and if needed by the protocol specifications, +a default mime type is determined by the context: +.br +- If set as a custom header, use this value. +.br +- application/form-data for a HTTP form post. +.br +- If a remote file name is set, the mime type is taken from the file name +extension, or application/octet-stream by default. +.br +- For a multipart part, multipart/mixed. +.br +- text/plain in other cases. + +.SH AVAILABILITY +As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0. +.SH RETURN VALUE +CURLE_OK or a CURL error code upon failure. + +.SH "SEE ALSO" +.BR curl_mime_addpart "(3)" diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 index 974f9f37a..68a15d816 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -42,6 +42,9 @@ You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP. When setting \fICURLOPT_HTTPPOST(3)\fP, it will automatically set \fICURLOPT_NOBODY(3)\fP to 0. + +This option is deprecated! Do not use it. Use \fICURLOPT_MIMEPOST(3)\fP +instead after having prepared mime data. .SH DEFAULT NULL .SH PROTOCOLS @@ -71,9 +74,9 @@ curl_formadd(&formpost, CURLFORM_END); .fi .SH AVAILABILITY -As long as HTTP is enabled +As long as HTTP is enabled. Deprecated in 7.56.0. .SH RETURN VALUE Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" -.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POST "(3), " -.BR curl_formadd "(3), " curl_formfree "(3), " +.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POST "(3), " CURLOPT_MIMEPOST "(3)," +.BR curl_formadd "(3), " curl_formfree "(3), " curl_mime_init "(3)" diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 new file mode 100644 index 000000000..a3a964f7f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_MIMEPOST 3 "22 Aug 2017" "libcurl 7.56.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MIMEPOST \- set post/send data from mime structure +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +curl_mime *mime; + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIMEPOST, mime); +.SH DESCRIPTION +Pass a mime handle previously obtained from \fIcurl_mime_init()\fP. + +This setting is supported by the HTTP protocol to post forms and by the +SMTP and IMAP protocols to provide the e-mail data to send/upload. + +This option is the preferred way of posting an HTTP form, replacing +and extending the deprecated \fICURLOPT_HTTPPOST\fP option. +.SH PROTOCOLS +HTTP, SMTP, IMAP. +.SH AVAILABILITY +Since 7.56.0. +.SH RETURN VALUE +This will return CURLE_OK. +.SH EXAMPLE +Using this option implies the use of several mime structure building +functions: see https://curl.haxx.se/libcurl/c/smtp-mime.html for a complete +example. +.SH "SEE ALSO" +.BR curl_mime_init "(3)" diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc index ad09dce2d..f710b5eb3 100644 --- a/docs/libcurl/opts/Makefile.inc +++ b/docs/libcurl/opts/Makefile.inc @@ -175,6 +175,7 @@ man_MANS = \ CURLOPT_MAXREDIRS.3 \ CURLOPT_MAX_RECV_SPEED_LARGE.3 \ CURLOPT_MAX_SEND_SPEED_LARGE.3 \ + CURLOPT_MIMEPOST.3 \ CURLOPT_NETRC.3 \ CURLOPT_NETRC_FILE.3 \ CURLOPT_NEW_DIRECTORY_PERMS.3 \ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 1a539d440..9ef7148c8 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -441,6 +441,7 @@ CURLOPT_MAXFILESIZE_LARGE 7.11.0 CURLOPT_MAXREDIRS 7.5 CURLOPT_MAX_RECV_SPEED_LARGE 7.15.5 CURLOPT_MAX_SEND_SPEED_LARGE 7.15.5 +CURLOPT_MIMEPOST 7.56.0 CURLOPT_MUTE 7.1 7.8 7.15.5 CURLOPT_NETRC 7.1 CURLOPT_NETRC_FILE 7.11.0 |