Return to curl_url_set.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

Annotation of embedaddon/curl/docs/libcurl/curl_url_set.3, revision 1.1

1.1     ! misho       1: .\" **************************************************************************
        !             2: .\" *                                  _   _ ____  _
        !             3: .\" *  Project                     ___| | | |  _ \| |
        !             4: .\" *                             / __| | | | |_) | |
        !             5: .\" *                            | (__| |_| |  _ <| |___
        !             6: .\" *                             \___|\___/|_| \_\_____|
        !             7: .\" *
        !             8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
        !             9: .\" *
        !            10: .\" * This software is licensed as described in the file COPYING, which
        !            11: .\" * you should have received as part of this distribution. The terms
        !            12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
        !            13: .\" *
        !            14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
        !            15: .\" * copies of the Software, and permit persons to whom the Software is
        !            16: .\" * furnished to do so, under the terms of the COPYING file.
        !            17: .\" *
        !            18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
        !            19: .\" * KIND, either express or implied.
        !            20: .\" *
        !            21: .\" **************************************************************************
        !            22: .TH curl_url_set 3 "January 05, 2020" "libcurl 7.70.0" "libcurl Manual"
        !            23: 
        !            24: .SH NAME
        !            25: curl_url_set - set a URL part
        !            26: .SH SYNOPSIS
        !            27: .B #include <curl/curl.h>
        !            28: 
        !            29: CURLUcode curl_url_set(CURLU *url,
        !            30:                        CURLUPart part,
        !            31:                        const char *content,
        !            32:                        unsigned int flags)
        !            33: .fi
        !            34: .SH DESCRIPTION
        !            35: Given the \fIurl\fP handle of an already parsed URL, this function lets the
        !            36: user set/update individual pieces of it.
        !            37: 
        !            38: The \fIpart\fP argument should identify the particular URL part (see list
        !            39: below) to set or change, with \fIcontent\fP pointing to a zero terminated
        !            40: string with the new contents for that URL part. The contents should be in the
        !            41: form and encoding they'd use in a URL: URL encoded.
        !            42: 
        !            43: Setting a part to a NULL pointer will effectively remove that part's contents
        !            44: from the CURLU handle.
        !            45: 
        !            46: The \fIflags\fP argument is a bitmask with independent features.
        !            47: .SH PARTS
        !            48: .IP CURLUPART_URL
        !            49: Allows the full URL of the handle to be replaced. If the handle already is
        !            50: populated with a URL, the new URL can be relative to the previous.
        !            51: 
        !            52: When successfully setting a new URL, relative or absolute, the handle contents
        !            53: will be replaced with the information of the newly set URL.
        !            54: 
        !            55: Pass a pointer to a zero terminated string to the \fIurl\fP parameter. The
        !            56: string must point to a correctly formatted "RFC 3986+" URL or be a NULL
        !            57: pointer.
        !            58: .IP CURLUPART_SCHEME
        !            59: Scheme cannot be URL decoded on set.
        !            60: .IP CURLUPART_USER
        !            61: .IP CURLUPART_PASSWORD
        !            62: .IP CURLUPART_OPTIONS
        !            63: .IP CURLUPART_HOST
        !            64: The host name. If it is IDNA the string must then be encoded as your locale
        !            65: says or UTF-8 (when WinIDN is used). If it is a bracketed IPv6 numeric address
        !            66: it may contain a zone id (or you can use CURLUPART_ZONEID).
        !            67: .IP CURLUPART_ZONEID
        !            68: If the host name is a numeric IPv6 address, this field can also be set.
        !            69: .IP CURLUPART_PORT
        !            70: Port cannot be URL encoded on set. The given port number is provided as a
        !            71: string and the decimal number must be between 1 and 65535. Anything else will
        !            72: return an error.
        !            73: .IP CURLUPART_PATH
        !            74: If a path is set in the URL without a leading slash, a slash will be inserted
        !            75: automatically when this URL is read from the handle.
        !            76: .IP CURLUPART_QUERY
        !            77: The query part will also get spaces converted to pluses when asked to URL
        !            78: encode on set with the CURLU_URLENCODE bit.
        !            79: 
        !            80: If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part will
        !            81: be appended on the end of the existing query - and if the previous part didn't
        !            82: end with an ampersand (&), an ampersand will be inserted before the new
        !            83: appended part.
        !            84: 
        !            85: When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the
        !            86: first '=' symbol will not be URL encoded.
        !            87: 
        !            88: The question mark in the URL is not part of the actual query contents.
        !            89: .IP CURLUPART_FRAGMENT
        !            90: The hash sign in the URL is not part of the actual fragment contents.
        !            91: .SH FLAGS
        !            92: The flags argument is zero, one or more bits set in a bitmask.
        !            93: .IP CURLU_NON_SUPPORT_SCHEME
        !            94: If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme.
        !            95: .IP CURLU_URLENCODE
        !            96: When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for
        !            97: scheme, port and URL.
        !            98: 
        !            99: When setting the path component with URL encoding enabled, the slash character
        !           100: will be skipped.
        !           101: 
        !           102: The query part gets space-to-plus conversion before the URL conversion.
        !           103: 
        !           104: This URL encoding is charset unaware and will convert the input on a
        !           105: byte-by-byte manner.
        !           106: .IP CURLU_DEFAULT_SCHEME
        !           107: If set, will make libcurl allow the URL to be set without a scheme and then
        !           108: sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP
        !           109: option if both are set.
        !           110: .IP CURLU_GUESS_SCHEME
        !           111: If set, will make libcurl allow the URL to be set without a scheme and it
        !           112: instead "guesses" which scheme that was intended based on the host name.  If
        !           113: the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then
        !           114: that scheme will be used, otherwise it picks HTTP. Conflicts with the
        !           115: \fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set.
        !           116: .IP CURLU_NO_AUTHORITY
        !           117: If set, skips authority checks. The RFC allows individual schemes to omit the
        !           118: host part (normally the only mandatory part of the authority), but libcurl
        !           119: cannot know whether this is permitted for custom schemes. Specifying the flag
        !           120: permits empty authority sections, similar to how file scheme is handled.
        !           121: 
        !           122: .SH RETURN VALUE
        !           123: Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
        !           124: fine.
        !           125: 
        !           126: A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
        !           127: part, must be shorter than 8000000 bytes otherwise it returns
        !           128: \fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0).
        !           129: 
        !           130: If this function returns an error, no URL part is returned.
        !           131: .SH EXAMPLE
        !           132: .nf
        !           133:   CURLUcode rc;
        !           134:   CURLU *url = curl_url();
        !           135:   rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
        !           136:   if(!rc) {
        !           137:     char *scheme;
        !           138:     /* change it to an FTP URL */
        !           139:     rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
        !           140:   }
        !           141:   curl_url_cleanup(url);
        !           142: .fi
        !           143: .SH AVAILABILITY
        !           144: Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
        !           145: .SH "SEE ALSO"
        !           146: .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
        !           147: .BR curl_url_dup "(3), "