CURLOPT_DIRLISTONLY(3)

💅 CURLOPT_DIRLISTONLY(3) — the "just gimme the names bestie" option ✨

okay so real talk, this is a page from the libcurl manual (yes, Library Functions Manual, the whole thing), and it's about one tiny little option that makes directory listings so much chiller. sit down, grab a strawberry drink 🍓, let's go.

---

🌸 NAME 🌸

CURLOPT_DIRLISTONLY — ask for names only in a directory listing. that's it. that's the whole vibe. names only, no extra.

---

🎀 SYNOPSIS 🎀

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DIRLISTONLY, long listonly);

---

🦋 DESCRIPTION 🦋

so for FTP and SFTP based URLs, setting this parameter to 1 tells the library to list the names of files in a directory, instead of doing a whole full directory listing that would normally include file sizes, dates, etc. like, the full thing. this is the "just the names please, i don't need the lore" mode. iconic behavior honestly 💅

for POP3, a parameter of 1 tells the library to list the email message or messages on the POP3 server. this can be used to change the default behavior of libcurl, when combined with a URL that contains a message ID, to perform a "scan listing" which can then be used to determine the size of an email. lowkey useful fr.

for FILE, this option has no effect yet as directories are always listed in this mode. so like... it's giving "no thoughts, head empty" for FILE. nothing happens 🫶

Note: for FTP this causes a NLST command to be sent to the FTP server. beware that some FTP servers list only files in their response to NLST; they might not include subdirectories and symbolic links. so if you're missing stuff, it's not you, it's the server. sorry bestie 😭

setting this option to 1 also implies a directory listing even if the URL does not end with a slash, which otherwise is necessary. the slash is optional now, we LOVE a flexible king 👑

Do not use this option if you also use CURLOPT_WILDCARDMATCH(3) as it effectively breaks that feature. like genuinely breaks it. don't. i'm serious 🙈

---

✨ DEFAULT ✨

0, disabled. (off by default, as she should be 💜)

---

🌈 PROTOCOLS 🌈

this functionality affects ftp, pop3 and sftp. that's the whole squad 🧚

---

💖 EXAMPLE 💖

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/");

    /* list only */
    curl_easy_setopt(curl, CURLOPT_DIRLISTONLY, 1L);

    result = curl_easy_perform(curl);

    curl_easy_cleanup(curl);
  }
}

not me writing a whole main function just to demonstrate names-only mode 😭 but look at her go. 1L note the L, it's a long, don't @ me.

---

⭐ HISTORY ⭐

this option was known as CURLOPT_FTPLISTONLY up to 7.16.4. so if you see that name in old code, that's her before the rebrand, it's the same girl 💀

POP3 is supported since 7.21.5. noted, timestamped, on the record 🎀

---

🔥 AVAILABILITY 🔥

added in curl 7.17.0. vintage but still serving 👑

---

💀 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). so like, 0 = slay, anything else = go read the error page bestie 😭

---

🫶 SEE ALSO 🫶

• CURLOPT_CUSTOMREQUEST(3)
• CURLOPT_WILDCARDMATCH(3)

---

and that's the whole page!! 💖✨ mwah ily, go list some directories responsibly 🦋

this little love letter was brought to you by libcurl, dated 2026-10-12 — same energy, same facts, all the vibes. periodt 💅