1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_WILDCARDMATCH
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CHUNK_BGN_FUNCTION (3)
9  - CURLOPT_CHUNK_END_FUNCTION (3)
10  - CURLOPT_FNMATCH_FUNCTION (3)
11  - CURLOPT_URL (3)
12Protocol:
13  - FTP
14Added-in: 7.21.0
15---
16
17# NAME
18
19CURLOPT_WILDCARDMATCH - directory wildcard transfers
20
21# SYNOPSIS
22
23~~~c
24#include <curl/curl.h>
25
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WILDCARDMATCH, long onoff);
27~~~
28
29# DESCRIPTION
30
31Set *onoff* to 1 if you want to transfer multiple files according to a
32filename pattern. The pattern can be specified as part of the CURLOPT_URL(3)
33option, using an **fnmatch**-like pattern (Shell Pattern Matching) in the last
34part of URL (filename).
35
36By default, libcurl uses its internal wildcard matching implementation. You
37can provide your own matching function by the
38CURLOPT_FNMATCH_FUNCTION(3) option.
39
40A brief introduction of its syntax follows:
41
42## * - ASTERISK
43
44    ftp://example.com/some/path/*.txt
45
46matches all `.txt` files in the root directory. Only two asterisks are allowed
47within the same pattern string.
48
49## ? - QUESTION MARK
50
51Question mark matches any (exactly one) character.
52
53    ftp://example.com/some/path/photo?.jpg
54
55## [ - BRACKET EXPRESSION
56
57The left bracket opens a bracket expression. The question mark and asterisk have
58no special meaning in a bracket expression. Each bracket expression ends by the
59right bracket and matches exactly one character. Some examples follow:
60
61**[a-zA-Z0-9]** or **[f-gF-G]** - character interval
62
63**[abc]** - character enumeration
64
65**[^abc]** or **[!abc]** - negation
66
67**[[:name:]]** class expression. Supported classes are **alnum**,**lower**,
68**space**, **alpha**, **digit**, **print**, **upper**, **blank**, **graph**,
69**xdigit**.
70
71**[][-!^]** - special case - matches only '-', ']', '[', '!' or '^'. These
72characters have no special purpose.
73
74**[[]]** - escape syntax. Matches '[', ']' or 'e'.
75
76Using the rules above, a filename pattern can be constructed:
77
78    ftp://example.com/some/path/[a-z[:upper:]\\].jpg
79
80# %PROTOCOLS%
81
82# EXAMPLE
83
84~~~c
85extern long begin_cb(struct curl_fileinfo *, void *, int);
86extern long end_cb(void *ptr);
87
88int main(void)
89{
90  CURL *curl = curl_easy_init();
91  if(curl) {
92    /* turn on wildcard matching */
93    curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L);
94
95    /* callback is called before download of concrete file started */
96    curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, begin_cb);
97
98    /* callback is called after data from the file have been transferred */
99    curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, end_cb);
100
101    /* See more on https://curl.se/libcurl/c/ftp-wildcard.html */
102  }
103}
104~~~
105
106# %AVAILABILITY%
107
108# RETURN VALUE
109
110Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
111