libssh2_sftp_symlink_ex(3)

💖 libssh2_sftp_symlink_ex(3) 💖

okay bestie, welcome to the libssh2 manual, this one's about symbolic links and she does BOTH jobs: reading them AND setting them. main character energy fr fr 🦋

---

✨ NAME ✨

libssh2_sftp_symlink_ex — read or set a symbolic link 🎀

---

✨ SYNOPSIS ✨

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

int
libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path,
                        unsigned int path_len, char *target,
                        unsigned int target_len, int link_type);

---

✨ DESCRIPTION ✨

So basically this function does the whole symlink thing on the remote side — it either creates a symlink or reads out symlink info from over there. Slay. 💅

• sftp — the SFTP instance, the one you got back from libssh2_sftp_init(3) 💫
• path — the remote filesystem object you're either creating a symlink from, or resolving. pick your fighter.
• path_len — how long that remote filesystem object's name is (the one you're creating a symlink from or resolving).
• target — a pointer to a buffer. and here's the tea: what this buffer is FOR totally depends on what link_type is set to 👀
  • LIBSSH2_SFTP_SYMLINK — the remote filesystem object to link to.
  • LIBSSH2_SFTP_READLINK — a pre-allocated buffer that the symlink target gets resolved into.
  • LIBSSH2_SFTP_REALPATH — a pre-allocated buffer that the realpath target gets resolved into.
• target_len — the length of the name of the remote filesystem target object.
• link_type — one of those three constants we just talked about, and it decides the entire resulting behavior of this function. no pressure bestie 😭

These are convenience macros, and honestly they're the ones you'll actually be using:

• libssh2_sftp_symlink(3) : creates a symbolic link between two filesystem objects.
• libssh2_sftp_readlink(3) : resolves a symbolic link filesystem object to its next target.
• libssh2_sftp_realpath(3) : resolves a complex, relative, or symlinked filepath to its effective target.

---

✨ RETURN VALUE ✨

it depends on the vibe you picked:

• With LIBSSH2_SFTP_SYMLINK, it returns 0 on success, or negative on failure.
• With LIBSSH2_SFTP_READLINK or LIBSSH2_SFTP_REALPATH, it returns the number of bytes it copied into the target buffer (not counting the terminating zero), or negative on failure.

It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. And yes, LIBSSH2_ERROR_EAGAIN is a negative number, but ngl it's not really a failure per se, don't panic 🫶

From 1.2.8, LIBSSH2_ERROR_BUFFER_TOO_SMALL gets returned if the given target buffer is too small to fit the requested object name.

---

💀 BUG 💀

Passing in a too small buffer when receiving data only results in libssh2 1.2.7 or earlier to not copy the entire data amount, and it is not possible for the application to tell when it happens!

that's it, that's the bug. silently truncating and refusing to tell you? it's giving toxic. 😭

---

✨ ERRORS ✨

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed. rip. 💀
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket.
• LIBSSH2_ERROR_SOCKET_TIMEOUT — (no description given, she'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.

---

✨ SEE ALSO ✨

• libssh2_sftp_init(3)

---

okay that's the whole page bestie, go forth and symlink responsibly 🌈⭐

libssh2 0.15 · 1 Jun 2007 — yeah she's vintage, but she ate and left no crumbs 👑💖