libssh2_sftp_open_ex(3)

✨ libssh2_sftp_open_ex(3) ✨

okay bestie, welcome to the libssh2 manual page for libssh2_sftp_open_ex 💖 pull up a chair, grab a strawberry 🍓, we're opening filehandles today and honestly? iconic behaviour.

🌸 NAME 🌸

libssh2_sftp_open_ex — open a filehandle for a file on SFTP. that's it, that's the whole vibe. it's giving "let me in" 💅

🦋 SYNOPSIS 🦋

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

LIBSSH2_SFTP_HANDLE *
libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, const char *filename,
                     unsigned int filename_len,
                     unsigned long flags,
                     long mode,
                     int open_type);

look at her. six arguments. she's a handful and we love her for it 😭🫶

✨ DESCRIPTION ✨

let's go arg by arg, no cap, because every single one matters:

• sftp — the SFTP instance you already got back from libssh2_sftp_init(3). your main character. your ride or die.
• filename — the remote file/directory resource you wanna open. remote, bestie. we're not on your laptop rn 🌈
• filename_len — the length of filename. yes you have to say it out loud. she doesn't measure for you, that's just her vibe.
• flags — any reasonable combination of the LIBSSH2_FXF_* constants, listed below in full because we don't skip:
  • LIBSSH2_FXF_READ — open the file for reading. just reading. a lil peek 👀
  • LIBSSH2_FXF_WRITE — open the file for writing. and listen: 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 the line, everyone goes to the back 🎀
  • LIBSSH2_FXF_CREAT, — if this flag is specified, then a new file will be created if one does not already exist (if LIBSSH2_FXF_TRUNC is specified, the new file will be truncated to zero length if it previously exists). brand new file, fresh start, glow up 🌱
  • 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 heads up: LIBSSH2_FXF_CREAT MUST also be specified if this flag is used. no CREAT, no TRUNC, that's the rule 📢
  • 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. she's exclusive, literally 💅
• mode — POSIX file permissions to assign if the file is being newly created. see the LIBSSH2_SFTP_S_* convenience defines in <libssh2_sftp.h>. only kicks in for fresh files, so don't stress about it otherwise ✨
• open_type — either of LIBSSH2_SFTP_OPENFILE (to open a file) or LIBSSH2_SFTP_OPENDIR (to open a directory). pick your fighter: file or folder, no in-between 🦋

🔥 RETURN VALUE 🔥

a pointer to the newly created LIBSSH2_SFTP_HANDLE instance 🎀 or NULL on failure 😭. that's the whole story.

💀 ERRORS 💀

here's the drama list, every single one, no skipping:

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed.
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket.
• LIBSSH2_ERROR_SOCKET_TIMEOUT — (yes, that's genuinely all it says. mysterious. we stan a cryptic icon 🙈)
• 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.
• LIBSSH2_ERROR_EAGAIN — marked for non-blocking I/O but the call would block.

real talk bestie: if you see LIBSSH2_ERROR_EAGAIN on a non-blocking setup, that is not the end of the world, it's just her saying "not right now, try again later" 💖

🌈 SEE ALSO 🌈

• libssh2_sftp_close_handle(3) — because you gotta close what you open, periodt 🫶

and that's the page, bestie!! this was the libssh2 manual, version 0.15, dated 1 Jun 2007 — yes she's vintage, she's a classic, she ate and left no crumbs 👑✨ go forth and open those filehandles, you absolute legend 💅🎀