libssh2_scp_send_ex(3)

💖 libssh2_scp_send_ex — bestie's guide to yeeting a file over SCP 💖

okay so this is a page from the libssh2 manual, and the function in question is libssh2_scp_send_ex(3). she's a classic, she's an icon, and she is also lowkey retired, which we'll get into. let's go 🫶

✨ SYNOPSIS ✨

#include <libssh2.h>

LIBSSH2_CHANNEL *
libssh2_scp_send_ex(LIBSSH2_SESSION *session, const char *path, int mode,
                    size_t size, long mtime, long atime);

look at her. five arguments. very main character energy. 👑

🌸 DESCRIPTION 🌸

so like. real talk first. this function has been deemed deprecated since libssh2 1.2.6. not me being the bearer of bad news 😭. the glow-up replacement is libssh2_scp_send64(3) — go check her out, she's the moment.

what this one does is send a file to the remote host via SCP. that's the whole vibe. ✨

and here's what each lil argument is giving:

• session — the Session instance, as returned by libssh2_session_init_ex(3). your whole connection lives here basically.
• path — the full path and filename of the file to transfer to. i.e. the remote file name. not the local one, bestie, don't get it twisted 🙈
• mode — the file access mode to create the file with.
• size — the size of the file being transmitted. and okay this is the strict part: it must be known ahead of time precisely. like, exactly exactly. no vibes-based estimating here, she will notice. 💀
• mtime — the mtime to assign to the file being created.
• atime — the atime to assign to the file being created. and here's a cute lil trick: set this and mtime both to zero and you're telling the remote host "just use the current time bestie" ⏰✨

🎀 RETURN VALUE 🎀

you get back a pointer to a newly allocated LIBSSH2_CHANNEL instance. fresh out the box, brand new, slay.

or, if things go sideways, you get NULL. that's the error signal. no in-between. 💅

💀 ERRORS 💀

here's the roster of ways this can go wrong, and what each one means:

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed. the malloc said "no ma'am".
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket. the socket is not cooperating 😭
• LIBSSH2_ERROR_SCP_PROTOCOL — yeah so this one is listed in the original with literally nothing after it. no explanation given, just the name. mysterious. iconic honestly. 🕵️‍♀️
• LIBSSH2_ERROR_EAGAIN — marked for non-blocking I/O but the call would block. she'd have to wait, and she simply will not. 🙅‍♀️

🦋 AVAILABILITY 🦋

this function was marked deprecated in libssh2 1.2.6, because libssh2_scp_send64(3) has been introduced to replace this function. so like, she's still here, she still works, but the group chat has moved on. use the new one if you're starting fresh, fr fr. 🌈

👑 SEE ALSO 👑

• libssh2_channel_open_ex(3)

and that's the page, bestie!! you ate that. go forth and transfer files responsibly 💖✨

libssh2 0.15 · 1 Jun 2007 — yeah she's an elder, a vintage queen, and we respect her era 🎀🫶