Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_URL.3, revision 1.1.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: .\"
23: .TH CURLOPT_URL 3 "March 09, 2020" "libcurl 7.70.0" "curl_easy_setopt options"
24:
25: .SH NAME
26: CURLOPT_URL \- provide the URL to use in the request
27: .SH SYNOPSIS
28: #include <curl/curl.h>
29:
30: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);
31: .SH DESCRIPTION
32: Pass in a pointer to the \fIURL\fP to work with. The parameter should be a
33: char * to a zero terminated string which must be URL-encoded in the following
34: format:
35:
36: scheme://host:port/path
37:
38: For a greater explanation of the format please see RFC3986.
39:
40: libcurl doesn't validate the syntax or use this variable until the transfer is
41: issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
42: still return \fICURLE_OK\fP.
43:
44: If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
45: then libcurl will make a guess based on the host. If the outermost sub-domain
46: name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be
47: used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by
48: setting a default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details.
49:
50: Should the protocol, either that specified by the scheme or deduced by libcurl
51: from the host name, not be supported by libcurl then
52: \fICURLE_UNSUPPORTED_PROTOCOL\fP will be returned from either the
53: \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you
54: call them. Use \fIcurl_version_info(3)\fP for detailed information of which
55: protocols are supported by the build of libcurl you are using.
56:
57: \fICURLOPT_PROTOCOLS(3)\fP can be used to limit what protocols libcurl will
58: use for this transfer, independent of what libcurl has been compiled to
59: support. That may be useful if you accept the URL from an external source and
60: want to limit the accessibility.
61:
62: The \fICURLOPT_URL(3)\fP string will be ignored if \fICURLOPT_CURLU(3)\fP is
63: set.
64:
65: \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a
66: transfer is started.
67:
68: The host part of the URL contains the address of the server that you want to
69: connect to. This can be the fully qualified domain name of the server, the
70: local network name of the machine on your network or the IP address of the
71: server or machine represented by either an IPv4 or IPv6 address. For example:
72:
73: http://www.example.com/
74:
75: http://hostname/
76:
77: http://192.168.0.1/
78:
79: http://[2001:1890:1112:1::20]/
80:
81: It is also possible to specify the user name, password and any supported login
82: options as part of the host, for the following protocols, when connecting to
83: servers that require authentication:
84:
85: http://user:password@www.example.com
86:
87: ftp://user:password@ftp.example.com
88:
89: smb://domain%2fuser:password@server.example.com
90:
91: imap://user:password;options@mail.example.com
92:
93: pop3://user:password;options@mail.example.com
94:
95: smtp://user:password;options@mail.example.com
96:
97: At present only IMAP, POP3 and SMTP support login options as part of the host.
98: For more information about the login options in URL syntax please see RFC2384,
99: RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0).
100:
101: The port is optional and when not specified libcurl will use the default port
102: based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25
103: for SMTP, etc. The following examples show how to specify the port:
104:
105: http://www.example.com:8080/ - This will connect to a web server using port
106: 8080 rather than 80.
107:
108: smtp://mail.example.com:587/ - This will connect to a SMTP server on the
109: alternative mail port.
110:
111: The path part of the URL is protocol specific and whilst some examples are
112: given below this list is not conclusive:
113:
114: .IP HTTP
115: The path part of an HTTP request specifies the file to retrieve and from what
116: directory. If the directory is not specified then the web server's root
117: directory is used. If the file is omitted then the default document will be
118: retrieved for either the directory specified or the root directory. The exact
119: resource returned for each URL is entirely dependent on the server's
120: configuration.
121:
122: http://www.example.com - This gets the main page from the web server.
123:
124: http://www.example.com/index.html - This returns the main page by explicitly
125: requesting it.
126:
127: http://www.example.com/contactus/ - This returns the default document from
128: the contactus directory.
129:
130: .IP FTP
131: The path part of an FTP request specifies the file to retrieve and from what
132: directory. If the file part is omitted then libcurl downloads the directory
133: listing for the directory specified. If the directory is omitted then
134: the directory listing for the root / home directory will be returned.
135:
136: ftp://ftp.example.com - This retrieves the directory listing for the root
137: directory.
138:
139: ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the
140: root directory.
141:
142: ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the
143: libcurl directory.
144:
145: ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt
146: file from the user's home directory. When a username and password is
147: specified, everything that is specified in the path part is relative to the
148: user's home directory. To retrieve files from the root directory or a
149: directory underneath the root directory then the absolute path must be
150: specified by prepending an additional forward slash to the beginning of the
151: path.
152:
153: ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt
154: from the root directory when logging in as a specified user.
155:
156: .IP FILE
157: When a FILE:// URL is accessed on Windows systems, it can be crafted in a way
158: so that Windows attempts to connect to a (remote) machine when curl wants to
159: read or write such a path.
160: .IP SMTP
161: The path part of a SMTP request specifies the host name to present during
162: communication with the mail server. If the path is omitted then libcurl will
163: attempt to resolve the local computer's host name. However, this may not
164: return the fully qualified domain name that is required by some mail servers
165: and specifying this path allows you to set an alternative name, such as
166: your machine's fully qualified domain name, which you might have obtained
167: from an external function such as gethostname or getaddrinfo.
168:
169: smtp://mail.example.com - This connects to the mail server at example.com and
170: sends your local computer's host name in the HELO / EHLO command.
171:
172: smtp://mail.example.com/client.example.com - This will send client.example.com in
173: the HELO / EHLO command to the mail server at example.com.
174:
175: .IP POP3
176: The path part of a POP3 request specifies the message ID to retrieve. If the
177: ID is not specified then a list of waiting messages is returned instead.
178:
179: pop3://user:password@mail.example.com - This lists the available messages for
180: the user
181:
182: pop3://user:password@mail.example.com/1 - This retrieves the first message for
183: the user
184:
185: .IP IMAP
186: The path part of an IMAP request not only specifies the mailbox to list (Added
187: in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the
188: mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets
189: (Added in 7.37.0) of the message to fetch and to specify what messages to
190: search for (Added in 7.37.0).
191:
192: imap://user:password@mail.example.com - Performs a top level folder list
193:
194: imap://user:password@mail.example.com/INBOX - Performs a folder list on the
195: user's inbox
196:
197: imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox
198: and fetches message with uid = 1
199:
200: imap://user:password@mail.example.com/INBOX/;MAILINDEX=1 - Selects the user's inbox
201: and fetches the first message in the mail box
202:
203: imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects
204: the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches
205: message 2 if it is
206:
207: imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the
208: user's inbox and fetches the text portion of message 3
209:
210: imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects
211: the user's inbox and fetches the first 1024 octets of message 4
212:
213: imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and
214: checks for NEW messages
215:
216: imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the
217: user's inbox and searches for messages containing "shadows" in the subject
218: line
219:
220: For more information about the individual components of an IMAP URL please
221: see RFC5092.
222:
223: .IP SCP
224: The path part of a SCP request specifies the file to retrieve and from what
225: directory. The file part may not be omitted. The file is taken as an absolute
226: path from the root directory on the server. To specify a path relative to the
227: user's home directory on the server, prepend ~/ to the path portion. If the
228: user name is not embedded in the URL, it can be set with the
229: \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
230:
231: scp://user@example.com/etc/issue - This specifies the file /etc/issue
232:
233: scp://example.com/~/my-file - This specifies the file my-file in the
234: user's home directory on the server
235: .IP SFTP
236: The path part of a SFTP request specifies the file to retrieve and from what
237: directory. If the file part is omitted then libcurl downloads the directory
238: listing for the directory specified. If the path ends in a / then a directory
239: listing is returned instead of a file. If the path is omitted entirely then
240: the directory listing for the root / home directory will be returned. If the
241: user name is not embedded in the URL, it can be set with the
242: \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option.
243:
244: sftp://user:password@example.com/etc/issue - This specifies the file
245: /etc/issue
246:
247: sftp://user@example.com/~/my-file - This specifies the file my-file in the
248: user's home directory
249:
250: sftp://ssh.example.com/~/Documents/ - This requests a directory listing
251: of the Documents directory under the user's home directory
252:
253: .IP SMB
254: The path part of a SMB request specifies the file to retrieve and from what
255: share and directory or the share to upload to and as such, may not be omitted.
256: If the user name is not embedded in the URL, it can be set with the
257: \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. If the user name
258: is embedded in the URL then it must contain the domain name and as such, the
259: backslash must be URL encoded as %2f.
260:
261: smb://server.example.com/files/issue - This specifies the file "issue" located
262: in the root of the "files" share
263:
264: smb://server.example.com/files/ -T issue - This specifies the file "issue" will
265: be uploaded to the root of the "files" share.
266:
267: curl supports SMB version 1 (only)
268: .IP LDAP
269: The path part of a LDAP request can be used to specify the: Distinguished
270: Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field
271: is separated by a question mark and when that field is not required an empty
272: string with the question mark separator should be included.
273:
274: ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search
275: with the DN as My Organisation.
276:
277: ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform
278: the same search but will only return postalAddress attributes.
279:
280: ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN
281: and requests information about the rootDomainNamingContext attribute for an
282: Active Directory server.
283:
284: For more information about the individual components of a LDAP URL please
285: see RFC4516.
286: .IP RTMP
287: There's no official URL spec for RTMP so libcurl uses the URL syntax supported
288: by the underlying librtmp library. It has a syntax where it wants a
289: traditional URL, followed by a space and a series of space-separated
290: name=value pairs.
291:
292: While space is not typically a "legal" letter, libcurl accepts them. When a
293: user wants to pass in a '#' (hash) character it will be treated as a fragment
294: and get cut off by libcurl if provided literally. You will instead have to
295: escape it by providing it as backslash and its ASCII value in hexadecimal:
296: "\\23".
297:
298: .RS 0
299: The application does not have to keep the string around after setting this
300: option.
301: .SH ENCODING
302: The string pointed to in the \fICURLOPT_URL(3)\fP argument is generally
303: expected to be a sequence of characters using an ASCII compatible encoding.
304:
305: If libcurl is built with IDN support, the server name part of the URL can use
306: an "international name" by using the current encoding (according to locale) or
307: UTF-8 (when winidn is used).
308:
309: If libcurl is built without IDN support, the server name is used exactly as
310: specified when passed to the name resolver functions.
311: .SH DEFAULT
312: There is no default URL. If this option isn't set, no transfer can be
313: performed.
314: .SH SECURITY CONCERNS
315: Applications may at times find it convenient to allow users to specify URLs
316: for various purposes and that string would then end up fed to this option.
317:
318: Getting a URL from an external untrusted party will bring reasons for several
319: security concerns:
320:
321: If you have an application that runs as or in a server application, getting an
322: unfiltered URL can easily trick your application to access a local resource
323: instead of a remote. Protecting yourself against localhost accesses is very
324: hard when accepting user provided URLs.
325:
326: Such custom URLs can also access other ports than you planned as port numbers
327: are part of the regular URL format. The combination of a local host and a
328: custom port number can allow external users to play tricks with your local
329: services.
330:
331: Accepting external URLs may also use other protocols than http:// or other
332: common ones. Restrict what accept with \fICURLOPT_PROTOCOLS(3)\fP.
333:
334: User provided URLs can also be made to point to sites that redirect further on
335: (possibly to other protocols too). Consider your
336: \fICURLOPT_FOLLOWLOCATION(3)\fP and \fICURLOPT_REDIR_PROTOCOLS(3)\fP settings.
337: .SH PROTOCOLS
338: All
339: .SH EXAMPLE
340: .nf
341: CURL *curl = curl_easy_init();
342: if(curl) {
343: curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
344:
345: curl_easy_perform(curl);
346: }
347: .fi
348: .SH AVAILABILITY
349: POP3 and SMTP were added in 7.31.0
350: .SH RETURN VALUE
351: Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
352: heap space.
353:
354: Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so
355: given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or
356: similar is called.
357: .SH "SEE ALSO"
358: .BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), "
359: .BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), "
360: .BR curl_easy_perform "(3), "
361: .BR CURLINFO_REDIRECT_URL "(3), " CURLOPT_PATH_AS_IS "(3), " CURLOPT_CURLU "(3), "
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to CURLOPT_URL.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts