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