libssh2_sftp_open_ex_r(3)

💖 libssh2_sftp_open_ex_r — the manual page, but make it make sense 💖

okay bestie, sit down, hydrate, and let me tell you about the cutest little file-opener in the whole libssh2 family. this is part of the libssh2 manual, and we're talking about libssh2_sftp_open_ex_r(3) — the one with the little _r at the end, which is the reentrant-ish flavor of opening stuff over SFTP. ✨

---

✨ NAME ✨

libssh2_sftp_open_ex_r — open filehandle for file on SFTP.

like. it opens a file. over SFTP. and hands you a handle. that's the whole vibe. 🫶

---

🌸 SYNOPSIS 🌸

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

LIBSSH2_SFTP_HANDLE *
libssh2_sftp_open_ex_r(LIBSSH2_SFTP *sftp, const char *filename,
                       size_t filename_len,
                       unsigned long flags,
                       long mode,
                       int open_type,
                       LIBSSH2_SFTP_ATTRIBUTES *attrs);

no cap, that's a lot of arguments. seven of them. she's high maintenance but she delivers. 💅

---

🦋 DESCRIPTION 🦋

okay so here's the whole cast of characters, one by one:

• sftp — your SFTP instance, as returned by libssh2_sftp_init(3). this is your main character, everything happens inside her.
• filename — the remote file/directory resource you wanna open. literally just the path, bestie.
• filename_len — the length of filename. yes, they make you pass it yourself. it's giving old-school C, we move.
• flags — any reasonable combination of the LIBSSH2_FXF_* constants, and ooooh there are options:
  • LIBSSH2_FXF_READ — open the file for reading. 📖
  • LIBSSH2_FXF_WRITE — open the file for writing. and if you specify both this and LIBSSH2_FXF_READ, the file gets opened for both reading and writing. multitasking queen. 👑
  • LIBSSH2_FXF_APPEND — force all writes to append data at the end of the file. no cutting in line. 🚫
  • LIBSSH2_FXF_CREAT — if this flag is specified, then a new file will be created if one does not already exist (and if LIBSSH2_FXF_TRUNC is specified, the new file will be truncated to zero length if it previously exists).
  • LIBSSH2_FXF_TRUNC — forces an existing file with the same name to be truncated to zero length when creating a file by specifying LIBSSH2_FXF_CREAT. ⚠️ and listen: LIBSSH2_FXF_CREAT MUST also be specified if this flag is used. must. not "should". MUST. periodt.
  • LIBSSH2_FXF_EXCL — causes the request to fail if the named file already exists. 💀 and again: LIBSSH2_FXF_CREAT MUST also be specified if this flag is used. same energy.
• mode — the POSIX file permissions to assign if the file is being newly created. peep the LIBSSH2_SFTP_S_* convenience defines in <libssh2_sftp.h> for the sauce. 🔥
• open_type — either of LIBSSH2_SFTP_OPENFILE (to open a file) or LIBSSH2_SFTP_OPENDIR (to open a directory). pick your fighter. ✨
• attrs — a pointer to a LIBSSH2_SFTP_ATTRIBUTES struct. see libssh2_sftp_fstat_ex for the detailed usage, because she's got lore.

---

💜 RETURN VALUE 💜

a pointer to the newly created LIBSSH2_SFTP_HANDLE instance — yay, iconic, we love her 🎀 — or NULL on failure. 😭 (and if you got NULL, go read the errors section, bestie, don't just sit there.)

---

🍓 ERRORS 🍓

here's the ✨vibe check✨ of things that can go wrong:

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed. the malloc said no. 🙈
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket.
• LIBSSH2_ERROR_SOCKET_TIMEOUT —
• 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. (yes that's "errorcode" as one word, we don't make the rules)
• LIBSSH2_ERROR_EAGAIN — marked for non-blocking I/O but the call would block. this one is not an L, it's just "try again later", okay? 🫶

---

🌈 AVAILABILITY 🌈

added in libssh2 1.11.0. so if you're on something older and it's not linking, that's why. not your fault. iykyk. ⭐

---

🧚 SEE ALSO 🧚

• libssh2_sftp_close_handle(3)
• libssh2_sftp_fstat_ex(3)

go read those too, they're the supporting cast and they ate. 💅

---

okay that's the whole page!! mwah 💋 this gem was brought to you by libssh2, dated 10 Apr 2023 — so like, bookmark it, screenshot it, send it to the group chat, and go open some files responsibly. no cap, you've got this. 🌸🦋✨