libssh2_sftp_mkdir_ex(3)

💖 libssh2_sftp_mkdir_ex — create a directory on the remote file system 💖

okay bestie, this is a page from the libssh2 manual (that's the manual name btw, we're in the libssh2 section 3 girlies). Sit down, grab a lil snack 🍓, and let's make some folders on a remote machine together. no cap.

---

✨ NAME ✨

libssh2_sftp_mkdir_ex — create a directory on the remote file system

literally that's it, that's the whole job. make a folder. remote. slay.

---

🌸 SYNOPSIS 🌸

#include <libssh2.h>
#include <libssh2_sftp.h>

int
libssh2_sftp_mkdir_ex(LIBSSH2_SFTP *sftp,
                      const char *path, unsigned int path_len,
                      long mode);

int
libssh2_sftp_mkdir(LIBSSH2_SFTP *sftp,
                   const char *path,
                   long mode);

so there's the ✨extra✨ version with path_len, and then the lil convenience one without it. both iconic, both valid. 💅

---

🦋 DESCRIPTION 🦋

okay so let's break down the arguments, one by one, because every single one matters:

• sftp — the SFTP instance, as returned by libssh2_sftp_init(3). you gotta have one of these first, it's giving "you can't sit with us until you init."
• path — the full path of the new directory you wanna create. 🎀 heads up though: the new directory's parents must all exist before you make this call. so if you're making /a/b/c, then /a and /a/b need to already be there. no auto-magic recursive mkdir here, sorry babe. 😭
• path_len — the length of that full path of the new directory you're creating. yes, you gotta tell it how long your string is. it's a whole thing.
• mode — the directory creation mode (e.g. 0755). classic permissions moment.

and then, like, it creates a directory on the remote file system. that's the vibe. that's the whole point. 👑

---

🫶 RETURN VALUE 🫶

• returns 0 on success ✨
• returns a negative number on failure 😭
• returns LIBSSH2_ERROR_EAGAIN when it would otherwise block.

and listen, real talk: while LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. it's just the "not right now, come back later" energy. don't panic, bestie. 🧚

---

💀 ERRORS 💀

here's the roster of things that can go wrong:

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed.
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket.
• LIBSSH2_ERROR_SOCKET_TIMEOUT — (yeah, that one just sits there, no explanation given, it's mysterious like that 🕵️)
• LIBSSH2_ERROR_SFTP_PROTOCOL — an invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server.

lowkey if you see any of these, something's not giving. check your socket, check your server, check your whole life. 🌈

---

👑 SEE ALSO 👑

• libssh2_sftp_open_ex(3)

go read that one too, it's part of the fam. iykyk. 💜

---

🎀 cute lil sign-off 🎀

this page came to you from libssh2 0.15, dated 1 Jun 2007 — yes, she's an elder icon and she still ate. now go forth and make directories, bestie. mwah. 💅✨🦋