1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_FTP_CREATE_MISSING_DIRS
5Section: 3
6Source: libcurl
7Protocol:
8  - FTP
9See-also:
10  - CURLOPT_FTP_FILEMETHOD (3)
11  - CURLOPT_FTP_USE_EPSV (3)
12Added-in: 7.10.7
13---
14
15# NAME
16
17CURLOPT_FTP_CREATE_MISSING_DIRS - create missing directories for FTP and SFTP
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24typedef enum {
25  CURLFTP_CREATE_DIR_NONE,
26  CURLFTP_CREATE_DIR,
27  CURLFTP_CREATE_DIR_RETRY
28} curl_ftpcreatedir;
29
30CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS,
31                          long create);
32~~~
33
34# DESCRIPTION
35
36Pass a long telling libcurl to *create* the dir. If the value is
37*CURLFTP_CREATE_DIR* (1), libcurl may create any remote directory that it
38fails to "move" into.
39
40For FTP requests, that means a CWD command fails. CWD being the command that
41changes working directory.
42
43For SFTP requests, libcurl may create the remote directory if it cannot obtain
44a handle to the target-location. The creation fails if a file of the same name
45as the directory to create already exists or lack of permissions prevents
46creation.
47
48Setting *create* to *CURLFTP_CREATE_DIR_RETRY* (2), tells libcurl to
49retry the CWD command again if the subsequent **MKD** command fails. This is
50especially useful if you are doing many simultaneous connections against the
51same server and they all have this option enabled, as then CWD may first fail
52but then another connection does **MKD** before this connection and thus
53**MKD** fails but trying CWD works.
54
55# DEFAULT
56
57CURLFTP_CREATE_DIR_NONE (0)
58
59# %PROTOCOLS%
60
61# EXAMPLE
62
63~~~c
64int main(void)
65{
66  CURL *curl = curl_easy_init();
67  if(curl) {
68    CURLcode res;
69    curl_easy_setopt(curl, CURLOPT_URL,
70                     "ftp://example.com/non-existing/new.txt");
71    curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS,
72                     (long)CURLFTP_CREATE_DIR_RETRY);
73
74    res = curl_easy_perform(curl);
75
76    curl_easy_cleanup(curl);
77  }
78}
79~~~
80
81# %AVAILABILITY%
82
83# RETURN VALUE
84
85Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the
86create value is not.
87