docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2014, 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "May 05, 2017" "libcurl 7.59.0" "curl_easy_setopt options"
  24
  25 .SH NAME
  26 CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing dirs for FTP and SFTP
  27 .SH SYNOPSIS
  28 .nf
  29 #include <curl/curl.h>
  30
  31 typedef enum {
  32   CURLFTP_CREATE_DIR_NONE,
  33   CURLFTP_CREATE_DIR,
  34   CURLFTP_CREATE_DIR_RETRY
  35 } curl_ftpcreatedir;
  36
  37 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS,
  38                           long create);
  39 .SH DESCRIPTION
  40 Pass a long telling libcurl to \fIcreate\fP the dir. If the value is
  41 \fICURLFTP_CREATE_DIR\fP (1), libcurl will attempt to create any remote
  42 directory that it fails to "move" into.
  43
  44 For FTP requests, that means a CWD command fails. CWD being the command that
  45 changes working directory.
  46
  47 For SFTP requests, libcurl will attempt to create the remote directory if it
  48 can't obtain a handle to the target-location. The creation will fail if a file
  49 of the same name as the directory to create already exists or lack of
  50 permissions prevents creation.
  51
  52 Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to
  53 retry the CWD command again if the subsequent MKD command fails. This is
  54 especially useful if you're doing many simultaneous connections against the
  55 same server and they all have this option enabled, as then CWD may first fail
  56 but then another connection does MKD before this connection and thus MKD fails
  57 but trying CWD works!
  58 .SH DEFAULT
  59 CURLFTP_CREATE_DIR_NONE (0)
  60 .SH PROTOCOLS
  61 FTP and SFTP
  62 .SH EXAMPLE
  63 .nf
  64 CURL *curl = curl_easy_init();
  65 if(curl) {
  66   curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/non-existing/new.txt");
  67   curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS,
  68                          CURLFTP_CREATE_DIR_RETRY);
  69
  70   ret = curl_easy_perform(curl);
  71
  72   curl_easy_cleanup(curl);
  73 }
  74 .fi
  75 .SH AVAILABILITY
  76 Added in 7.10.7. SFTP support added in 7.16.3. The retry option was added in
  77 7.19.4.
  78 .SH RETURN VALUE
  79 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the
  80 create value is not.
  81 .SH "SEE ALSO"
  82 .BR CURLOPT_FTP_FILEMETHOD "(3), " CURLOPT_FTP_USE_EPSV "(3), "