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