.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "December 04, 2023" "ibcurl 8.5.0" libcurl

.SH NAME
CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing directories for FTP and SFTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>

typedef enum {
  CURLFTP_CREATE_DIR_NONE,
  CURLFTP_CREATE_DIR,
  CURLFTP_CREATE_DIR_RETRY
} curl_ftpcreatedir;

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS,
                          long create);
.SH DESCRIPTION
Pass a long telling libcurl to \fIcreate\fP the dir. If the value is
\fICURLFTP_CREATE_DIR\fP (1), libcurl may create any remote directory that it
fails to "move" into.

For FTP requests, that means a CWD command fails. CWD being the command that
changes working directory.

For SFTP requests, libcurl may create the remote directory if it cannot obtain
a handle to the target-location. The creation fails if a file of the same name
as the directory to create already exists or lack of permissions prevents
creation.

Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to
retry the CWD command again if the subsequent \fBMKD\fP command fails. This is
especially useful if you are doing many simultaneous connections against the
same server and they all have this option enabled, as then CWD may first fail
but then another connection does \fBMKD\fP before this connection and thus
\fBMKD\fP fails but trying CWD works!
.SH DEFAULT
CURLFTP_CREATE_DIR_NONE (0)
.SH PROTOCOLS
FTP and SFTP
.SH EXAMPLE
.nf
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode res;
    curl_easy_setopt(curl, CURLOPT_URL,
                     "ftp://example.com/non-existing/new.txt");
    curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS,
                     (long)CURLFTP_CREATE_DIR_RETRY);

    res = curl_easy_perform(curl);

    curl_easy_cleanup(curl);
  }
}
.fi
.SH AVAILABILITY
Added in 7.10.7. SFTP support added in 7.16.3. The retry option was added in
7.19.4.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the
create value is not.
.SH "SEE ALSO"
.BR CURLOPT_FTP_FILEMETHOD (3),
.BR CURLOPT_FTP_USE_EPSV (3)