libssh2_sftp_rename_ex(3)

✨ libssh2_sftp_rename_ex — rename an SFTP file ✨

okay bestie, welcome to the libssh2 manual, page libssh2_sftp_rename_ex(3). this is the glow-up your remote filenames have been waiting for 💅

🌸 NAME 🌸

libssh2_sftp_rename_ex — rename an SFTP file

🦋 SYNOPSIS 🦋

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

int
libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp,
                       const char *source_filename,
                       unsigned int source_filename_len,
                       const char *dest_filename,
                       unsigned int dest_filename_len,
                       long flags);

int
libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp,
                       const char *source_filename,
                       const char *dest_filename);

two whole flavours, and you get to pick. iconic of them tbh 🫶

💖 DESCRIPTION 💖

• sftp — the SFTP instance, as returned by libssh2_sftp_init(3). yes, you gotta have one, it's the whole vibe.
• sourcefile — path and name of the existing filesystem entry. the thing that's currently sitting there being itself.
• sourcefile_len — length of the path and name of the existing filesystem entry.
• destfile — path and name of the target filesystem entry. where it's headed, main character relocation.
• destfile_len — length of the path and name of the target filesystem entry.
• flags — a bitmask of flags made up of the LIBSSH2_SFTP_RENAME_* constants.

so like. this renames a filesystem object on the remote filesystem. the semantics of this command typically include the ability to move a filesystem object between folders and/or filesystem mounts — so it's not just a lil rename, it can literally relocate across mounts, no cap.

🚨 if the LIBSSH2_SFTP_RENAME_OVERWRITE flag is not set and the destfile entry already exists, the operation will fail. periodt. it's not gonna quietly clobber anything for you.

and the other two flags? using them is a preference, not a requirement — they signal you'd like the remote end to perform an atomic rename operation and/or use native system calls when possible. it's giving "asking nicely", not "demanding". 🙈

⭐ RETURN VALUE ⭐

returns 0 on success, or a negative number on failure. it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block.

and listen — while LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. it's just the "not right now bestie, try again later" of error codes. don't panic. 💜

💀 ERRORS 💀

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed.
• 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 the timeout one is just vibes and a dash, that's literally all the original gives us, we do not make things up here 🎀)

🌈 SEE ALSO 🌈

• libssh2_sftp_init(3)

and that's the whole page, bestie — go forth and rename things with confidence 🦋✨

libssh2 0.15 · 1 Jun 2007 — yeah she's vintage, she's a classic, she still slays 💅👑