From 2e4074c953e96cadc3182454fd437f9a348e37ce Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Sep 2017 09:20:24 +0200 Subject: [PATCH] docs: curl_mime_*.3 man page formatting edits --- docs/libcurl/curl_mime_addpart.3 | 8 +++----- docs/libcurl/curl_mime_data.3 | 8 ++++---- docs/libcurl/curl_mime_data_cb.3 | 26 +++++++++++++++----------- docs/libcurl/curl_mime_filedata.3 | 11 ++++++----- docs/libcurl/curl_mime_filename.3 | 13 ++++++------- docs/libcurl/curl_mime_free.3 | 8 ++++---- docs/libcurl/curl_mime_headers.3 | 10 +++++----- docs/libcurl/curl_mime_init.3 | 9 +++++---- docs/libcurl/curl_mime_name.3 | 18 ++++++++++-------- docs/libcurl/curl_mime_subparts.3 | 9 ++++----- docs/libcurl/curl_mime_type.3 | 13 +++++++------ docs/libcurl/opts/CURLOPT_MIMEPOST.3 | 6 +++--- 12 files changed, 72 insertions(+), 67 deletions(-) diff --git a/docs/libcurl/curl_mime_addpart.3 b/docs/libcurl/curl_mime_addpart.3 index 4a86f3813..7bdd43d72 100644 --- a/docs/libcurl/curl_mime_addpart.3 +++ b/docs/libcurl/curl_mime_addpart.3 @@ -28,18 +28,16 @@ curl_mime_addpart - append a new empty part to a mime structure .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. +\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given +mime structure and returns a handle to it. The returned part handle can +subsequently be populated 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)," diff --git a/docs/libcurl/curl_mime_data.3 b/docs/libcurl/curl_mime_data.3 index 85aee65e4..c458f2d38 100644 --- a/docs/libcurl/curl_mime_data.3 +++ b/docs/libcurl/curl_mime_data.3 @@ -29,7 +29,7 @@ curl_mime_data - set a mime part's body data from memory .BI ", size_t " datasize ");" .ad .SH DESCRIPTION -curl_mime_data() sets a mime part's body content from memory data. +\fIcurl_mime_data(3)\fP 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. @@ -43,13 +43,13 @@ 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. - +\fIcurl_mime_data_cb(3)\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)" +.BR curl_mime_name "(3)" +.BR curl_mime_type "(3)" diff --git a/docs/libcurl/curl_mime_data_cb.3 b/docs/libcurl/curl_mime_data_cb.3 index 64e5c7dc0..d0a0c14b1 100644 --- a/docs/libcurl/curl_mime_data_cb.3 +++ b/docs/libcurl/curl_mime_data_cb.3 @@ -38,20 +38,24 @@ void freefunc(void *arg); .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. +\fIcurl_mime_data_cb(3)\fP 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. + +\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. +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 diff --git a/docs/libcurl/curl_mime_filedata.3 b/docs/libcurl/curl_mime_filedata.3 index 71562edd0..e70e3b269 100644 --- a/docs/libcurl/curl_mime_filedata.3 +++ b/docs/libcurl/curl_mime_filedata.3 @@ -29,17 +29,18 @@ curl_mime_filedata - set a mime part's body data from a file contents .BI " const char * " filename ");" .ad .SH DESCRIPTION -curl_mime_filedata() sets a mime part's body content from the named file's -contents. +\fIcurl_mime_filedata(3)\fP 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. -Filename storage can be safely be reused after this call. +be NULL to detach previous part contents settings. 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(). +overriden by a subsequent call to \fIcurl_mime_filename(3)\fP. Setting a part's contents twice is valid: only the value set by the last call is retained. diff --git a/docs/libcurl/curl_mime_filename.3 b/docs/libcurl/curl_mime_filename.3 index 4c09402aa..db4482cdd 100644 --- a/docs/libcurl/curl_mime_filename.3 +++ b/docs/libcurl/curl_mime_filename.3 @@ -29,10 +29,10 @@ curl_mime_filename - set a mime part's remote file name .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. +\fIcurl_mime_filename(3)\fP 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 @@ -41,11 +41,10 @@ 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)" +.BR curl_mime_addpart "(3) " +.BR curl_mime_filedata "(3) " diff --git a/docs/libcurl/curl_mime_free.3 b/docs/libcurl/curl_mime_free.3 index 87fea127b..9394b5748 100644 --- a/docs/libcurl/curl_mime_free.3 +++ b/docs/libcurl/curl_mime_free.3 @@ -28,10 +28,10 @@ curl_mime_free - free a previously built mime structure .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. +\fIcurl_mime_free(3)\fP 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 diff --git a/docs/libcurl/curl_mime_headers.3 b/docs/libcurl/curl_mime_headers.3 index 368c4d26c..34e623ae0 100644 --- a/docs/libcurl/curl_mime_headers.3 +++ b/docs/libcurl/curl_mime_headers.3 @@ -29,22 +29,22 @@ curl_mime_headers - set a mime part's custom headers .BI "struct curl_slist * " headers ", int " take_ownership ");" .ad .SH DESCRIPTION -curl_mime_headers() sets a mime part's custom headers. +\fIcurl_mime_headers(3)\fP 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. + +\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 index 601123c41..031c62b65 100644 --- a/docs/libcurl/curl_mime_init.3 +++ b/docs/libcurl/curl_mime_init.3 @@ -28,10 +28,11 @@ curl_mime_init - create a mime handle .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. +\fIcurl_mime_init(3)\fP 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(3)\fP within a \fIcurl_easy_setopt(3)\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. diff --git a/docs/libcurl/curl_mime_name.3 b/docs/libcurl/curl_mime_name.3 index 25b4b35c6..71c9d8a1e 100644 --- a/docs/libcurl/curl_mime_name.3 +++ b/docs/libcurl/curl_mime_name.3 @@ -29,24 +29,26 @@ curl_mime_name - set a mime part's name .BI ", size_t " namesize ");" .ad .SH DESCRIPTION -curl_mime_name() sets a mime part's name. This is the way HTTP form fields are -named. +\fIcurl_mime_name(3)\fP 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 \fICURL_ZERO_TERMINATED\fP 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. - +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)" +.BR curl_mime_data "(3)" +.BR curl_mime_type "(3)" diff --git a/docs/libcurl/curl_mime_subparts.3 b/docs/libcurl/curl_mime_subparts.3 index 3c607c586..13d34c361 100644 --- a/docs/libcurl/curl_mime_subparts.3 +++ b/docs/libcurl/curl_mime_subparts.3 @@ -29,24 +29,23 @@ curl_mime_subparts - set subparts of a multipart mime part .BI "curl_mime * " subparts ");" .ad .SH DESCRIPTION -curl_mime_subparts() sets a multipart mime part's content from a mime +\fIcurl_mime_subparts(3)\fP 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. +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 index 0c6cd3d6b..6907b9462 100644 --- a/docs/libcurl/curl_mime_type.3 +++ b/docs/libcurl/curl_mime_type.3 @@ -29,15 +29,16 @@ curl_mime_type - set a mime part's content type .BI "const char * " mimetype ");" .ad .SH DESCRIPTION -curl_mime_type() sets a mime part's content type. +\fIcurl_mime_type(3)\fP 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. +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: @@ -52,11 +53,11 @@ extension, or application/octet-stream by default. - 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)" +.BR curl_mime_name "(3)" +.BR curl_mime_data "(3)" diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 index a3a964f7f..dd64c4b17 100644 --- a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 +++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 @@ -31,13 +31,13 @@ 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. +Pass a mime handle previously obtained from \fIcurl_mime_init(3)\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. +This option is the preferred way of posting an HTTP form, replacing and +extending the deprecated \fICURLOPT_HTTPPOST(3)\fP option. .SH PROTOCOLS HTTP, SMTP, IMAP. .SH AVAILABILITY