romenskiy2012/curl

mirror of https://github.com/curl/curl.git synced 2026-06-09 18:14:15 +03:00

docs: add CURLOPT type change history, drop casts where present

Some CURLOPT constants defined in the curl public headers were initially
enums (= ints), or macros with bare numeric values. Recent curl releases
upgraded them to `long` constants, to make them pass correctly to
`curl_easy_setop()` by default, i.e. without requiring a `(long)` cast.

This patch drops such casts from the examples embedded in the docs. At
the same time it documents which curl release made them `long` types,
to keep them useful when working with previous libcurl versions.

Also:
- drop a `(long)` cast that was never necessary.
- CURLOPT_ALTSVC_CTRL.md: bump local copy of macros to long.
- test1119: make it ignore symbols ending with an underscore, to skip
  wildcard, e.g. `**CURLAUTH_***`.

Closes #18130

2025-08-02 00:05:33 +02:00

2.3 KiB

Raw Blame History

SPDX-License-Identifier

Title

Section

Source

Protocol

See-also

Added-in

curl

CURLOPT_FTP_CREATE_MISSING_DIRS

libcurl

FTP

CURLOPT_FTP_FILEMETHOD (3)

CURLOPT_FTP_USE_EPSV (3)

7.10.7

NAME

CURLOPT_FTP_CREATE_MISSING_DIRS - create missing directories for FTP and SFTP

SYNOPSIS

#include <curl/curl.h>

#define CURLFTP_CREATE_DIR_NONE  0L
#define CURLFTP_CREATE_DIR       1L
#define CURLFTP_CREATE_DIR_RETRY 2L

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS,
                          long create);

DESCRIPTION

Pass a long telling libcurl to create the dir. If the value is CURLFTP_CREATE_DIR (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 create to CURLFTP_CREATE_DIR_RETRY (2), tells libcurl to retry the CWD command again if the subsequent MKD 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 MKD before this connection and thus MKD fails but trying CWD works.

DEFAULT

CURLFTP_CREATE_DIR_NONE (0)

%PROTOCOLS%

EXAMPLE

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,
                     CURLFTP_CREATE_DIR_RETRY);

    res = curl_easy_perform(curl);

    curl_easy_cleanup(curl);
  }
}

HISTORY

CURLFTP_CREATE_* enums became long types in 8.16.0, prior to this version a long cast was necessary when passed to curl_easy_setopt(3).

%AVAILABILITY%

RETURN VALUE

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

2.3 KiB Raw Blame History