1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_DIRLISTONLY 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_CUSTOMREQUEST (3) 9 - CURLOPT_WILDCARDMATCH (3) 10Protocol: 11 - FTP 12 - SFTP 13 - POP3 14--- 15 16# NAME 17 18CURLOPT_DIRLISTONLY - ask for names only in a directory listing 19 20# SYNOPSIS 21 22~~~c 23#include <curl/curl.h> 24 25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DIRLISTONLY, long listonly); 26~~~ 27 28# DESCRIPTION 29 30For FTP and SFTP based URLs a parameter set to 1 tells the library to list the 31names of files in a directory, rather than performing a full directory listing 32that would normally include file sizes, dates etc. 33 34For POP3 a parameter of 1 tells the library to list the email message or 35messages on the POP3 server. This can be used to change the default behavior 36of libcurl, when combined with a URL that contains a message ID, to perform a 37"scan listing" which can then be used to determine the size of an email. 38 39For FILE, this option has no effect yet as directories are always listed in 40this mode. 41 42Note: For FTP this causes a NLST command to be sent to the FTP server. Beware 43that some FTP servers list only files in their response to NLST; they might 44not include subdirectories and symbolic links. 45 46Setting this option to 1 also implies a directory listing even if the URL 47does not end with a slash, which otherwise is necessary. 48 49Do not use this option if you also use CURLOPT_WILDCARDMATCH(3) as it 50effectively breaks that feature. 51 52# DEFAULT 53 540, disabled 55 56# EXAMPLE 57 58~~~c 59int main(void) 60{ 61 CURL *curl = curl_easy_init(); 62 if(curl) { 63 CURLcode res; 64 curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/"); 65 66 /* list only */ 67 curl_easy_setopt(curl, CURLOPT_DIRLISTONLY, 1L); 68 69 res = curl_easy_perform(curl); 70 71 curl_easy_cleanup(curl); 72 } 73} 74~~~ 75 76# AVAILABILITY 77 78This option was known as CURLOPT_FTPLISTONLY up to 7.16.4. POP3 is supported 79since 7.21.5. 80 81# RETURN VALUE 82 83Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 84