libssh2_sftp_posix_rename_ex(3)

💅 libssh2_sftp_posix_rename_ex — the glow-up rename, bestie

okay so this is the libssh2_sftp_posix_rename_ex(3) page from the libssh2 manual, and it's literally the one you want when you need a rename that actually behaves. sit with me, we're gonna go through it together 🫶

✨ NAME ✨

libssh2_sftp_posix_rename_ex — rename an SFTP file using POSIX semantics. no cap, that's the whole vibe.

🌸 SYNOPSIS 🌸

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

int
libssh2_sftp_posix_rename_ex(LIBSSH2_SFTP *sftp,
                             const char *source_filename,
                             size_t source_filename_len,
                             const char *dest_filename,
                             size_t dest_filename_len);

🦋 DESCRIPTION 🦋

okay so here's the cast, one by one 💖

• sftp — the SFTP instance, as returned by libssh2_sftp_init(3). your main character.
• sourcefile — path and name of the existing filesystem entry. the thing that's already there.
• 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 going.
• destfile_len — length of the path and name of the target filesystem entry.

so this function implements the posix-rename@openssh.com extension, and honestly? it's giving useful. like, when you're moving files across filesystems on a remote server, this is the one you want 🔥.

here's the tea though: SSH_FXP_RENAME does not specify a specific implementation, and many servers will attempt to user hard links when moving files using SSH_FXP_RENAME. so you can't just assume it's doing the nice thing. rude, honestly.

and if the server does not support posix-rename@openssh.com, this function will return LIBSSH2_FX_OP_UNSUPPORTED and you can call libssh2_sftp_rename_ex (3) as a backup. always have a backup plan, bestie 🙈

👑 RETURN VALUE 👑

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

and yes, LIBSSH2_ERROR_EAGAIN is a negative number, but it is not really a failure per se. it's just... not yet. don't panic, don't spiral, just try again later 💜

💀 ERRORS 💀

the mood-killers, listed for your convenience:

• LIBSSH2_FX_OP_UNSUPPORTED — Server does not support posix-rename@openssh.com
• 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.

🎀 SEE ALSO 🎀

• libssh2_sftp_init(3)

and that's the whole page, periodt 💅 go rename something responsibly. this was libssh2 version 1.11.1, dated 9 May 2024 — mwah, love that for us 🌈⭐🍓