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