ct_ssh(3erl)
💅 ct_ssh(3erl) — Erlang Module Definition: the SSH/SFTP bestie module 🦋
okay so real talk, this is ct_ssh(3erl), and it's genuinely one of those pages you're gonna want bookmarked because it's so much. It's the manual page for the Common Test SSH/SFTP client module, and honestly? iconic. Let's get into it ✨
✨ NAME ✨
ct_ssh — SSH/SFTP client module. That's it. That's the whole vibe. 🌸
🌈 DESCRIPTION 🌈
ct_ssh is an SSH/SFTP client module, no cap. 💅
This module uses application SSH, which provides detailed information about, for example, functions, types, and options. So like, if you need the deep lore, that's where it lives.
Now, this part is important and I need you to pay attention, bestie 👀 — argument Server in the SFTP functions is only to be used for SFTP sessions that have been started on existing SSH connections (that is, when the original connection type is ssh). Whenever the connection type is sftp, use the SSH connection reference only. Do not come for me if you mix these up, that's on you 🙈
The following options are valid for specifying an SSH/SFTP connection (that is, they can be used as configuration elements):
[{ConnType, Addr},
{port, Port},
{user, UserName}
{password, Pwd}
{user_dir, String}
{public_key_alg, PubKeyAlg}
{connect_timeout, Timeout}
{key_cb, KeyCallbackMod}]where ConnType = ssh | sftp.
For other types, see ssh(3erl).
✨ bestie PSA: all time-out parameters in ct_ssh functions are values in milliseconds. not seconds. not vibes. milliseconds. 💖
🎀 DATA TYPES 🎀
🌟 connection() = handle() | target_name()
For target_name, see module ct. That's the alias situation, iykyk.
🌟 handle() = handle()
Handle for a specific SSH/SFTP connection, see module ct. Yeah it's the same name twice, don't @ me, that's just how it's written 💀
🌟 ssh_sftp_return() = term()
Return value from an ssh_sftp function. term(), the most free-spirited type in the game 👑
🚀 EXPORTS 🚀
🐚 apread(SSH, Handle, Position, Length) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
🐚 apread(SSH, Server, Handle, Position, Length) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). (yes this is the Server flavor — remember the rule from up top, the Server one is for SFTP sessions started on existing SSH connections where the original connection type is ssh 🫶)
🐚 apwrite(SSH, Handle, Position, Data) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
🐚 apwrite(SSH, Server, Handle, Position, Data) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
🐚 aread(SSH, Handle, Len) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
🐚 aread(SSH, Server, Handle, Len) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
🐚 awrite(SSH, Handle, Data) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
🐚 awrite(SSH, Server, Handle, Data) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
🐚 close(SSH, Handle) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). closing time, bye bestie 👋
🐚 close(SSH, Server, Handle) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 👋
🔌 connect(KeyOrName) -> {ok, Handle} | {error, Reason}
Equivalent to ct_ssh:connect(KeyOrName, host, []). that's it, that's the shortcut 🎀
🔌 connect(KeyOrName, ConnType) -> {ok, Handle} | {error, Reason}
Equivalent to ct_ssh:connect(KeyOrName, ConnType, []). 🎀
🔌 connect(KeyOrName, ConnType, ExtraOpts) -> {ok, Handle} | {error, Reason}
Types:
KeyOrName = Key | Name
Key = atom()
Name = target_name()
ConnType = ssh | sftp | host
ExtraOpts = ssh_connect_options()
Handle = handle()
Reason = term()Opens an SSH or SFTP connection using the information associated with KeyOrName.
If Name (an alias name for Key) is used to identify the connection, this name can be used as connection reference for subsequent calls. Only one open connection at a time associated with Name is possible. So like, one at a time, bestie, no hoarding 🙅♀️
If Key is used, the returned handle must be used for subsequent calls (multiple connections can be opened using the configuration data specified by Key). Now that's main character energy — multiple connections, all from the same config data 👑
For information on how to create a new Name, see ct:require/2.
For target_name, see module ct.
ConnType always overrides the type specified in the address tuple in the configuration data (and in ExtraOpts). Periodt. So it is possible to, for example, open an SFTP connection directly using data originally specifying an SSH connection. Glow-up arc fr fr ✨
Value host means that the connection type specified by the host option (either in the configuration data or in ExtraOpts) is used.
ExtraOpts (optional) are extra SSH options to be added to the configuration data for KeyOrName. The extra options override any existing options with the same key in the configuration data. For details on valid SSH options, see application SSH. 🫶
🗂️ del_dir(SSH, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
🗂️ del_dir(SSH, Server, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
🗑️ delete(SSH, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
🗑️ delete(SSH, Server, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
🔌 disconnect(SSH) -> ok | {error, Reason}
Types:
SSH = connection()
Reason = term()Closes an SSH/SFTP connection. wrapping it up, politely, as one does 💅
💻 exec(SSH, Command) -> {ok, Data} | {error, Reason}
Equivalent to ct_ssh:exec(SSH, Command, DefaultTimeout). yes, there's a DefaultTimeout, and yes it's in milliseconds, we covered that 🌸
💻 exec(SSH, Command, Timeout) -> {ok, Data} | {error, Reason}
Types:
SSH = connection()
Command = string()
Timeout = integer()
Data = list()
Reason = term()Requests server to perform Command. A session channel is opened automatically for the request. Data is received from the server as a result of the command. automatic channel? we love a self-sufficient queen 👑
💻 exec(SSH, ChannelId, Command, Timeout) -> {ok, Data} | {error, Reason}
Types:
SSH = connection()
ChannelId = integer()
Command = string()
Timeout = integer()
Data = list()
Reason = term()Requests server to perform Command. A previously opened session channel is used for the request. Data is received from the server as a result of the command. this one's the reuse era, sustainable icon 🌱
📄 get_file_info(SSH, Handle) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
📄 get_file_info(SSH, Server, Handle) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
📁 list_dir(SSH, Path) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
📁 list_dir(SSH, Server, Path) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
📂 make_dir(SSH, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). manifesting that directory into existence 🕯️
📂 make_dir(SSH, Server, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
🔗 make_symlink(SSH, Name, Target) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
🔗 make_symlink(SSH, Server, Name, Target) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
📖 open(SSH, File, Mode) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
📖 open(SSH, Server, File, Mode) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
📂 opendir(SSH, Path) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). 💫
📂 opendir(SSH, Server, Path) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). ✨
📍 position(SSH, Handle, Location) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl). and no, this isn't me signing off — the list literally keeps going, part 2 is right there bestie 💅🦋
...and yep, for information and other types, see ssh_sftp(3erl) ✨ (that's the tail of the previous one — we're rolling straight into the next, no brakes 🚗💨)
position(SSH, Server, Handle, Location) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 💅
pread(SSH, Handle, Position, Length) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) — this is the version where the Server is already implied, bestie 🫶
pread(SSH, Server, Handle, Position, Length) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()Same energy, except you gotta name your Server out loud. For information and other types, see ssh_sftp(3erl) 🌸
pwrite(SSH, Handle, Position, Data) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 💖
pwrite(SSH, Server, Handle, Position, Data) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 💖 (yes, with the Server this time — she's specific)
read(SSH, Handle, Len) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) ✨
read(SSH, Server, Handle, Len) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) ✨
read_file(SSH, File) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 📖
read_file(SSH, Server, File) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 📖 (with the Server named, obvs)
read_file_info(SSH, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🎀
read_file_info(SSH, Server, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🎀
read_link(SSH, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🦋
read_link(SSH, Server, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🦋
read_link_info(SSH, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🔥
read_link_info(SSH, Server, Name) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🔥
receive_response(SSH, ChannelId) -> {ok, Data} | {error, Reason}
Equivalent to ct_ssh:receive_response(SSH, ChannelId, close) 👑
receive_response(SSH, ChannelId, End) -> {ok, Data} | {error, Reason}
Equivalent to ct_ssh:receive_response(SSH, ChannelId, End, DefaultTimeout) ⏰
receive_response(SSH, ChannelId, End, Timeout) -> {ok, Data} | {timeout, Data} | {error, Reason}
Types:
SSH = connection()
ChannelId = integer()
End = Fun | close | timeout
Timeout = integer()
Data = list()
Reason = term()Receives expected data from the server on the specified session channel 💌
- If
End == close— the data gets handed back to you when the server closes the channel. If a time-out sneaks in before that happens, the function returns{timeout,Data}(whereDatais everything it managed to collect so far 😭). - If
End == timeout— a time-out is expected, and you get{ok,Data}both when the time-out hits and when the channel gets closed. - If
Endis a fun — that fun gets called with one argument: the data value inside a receivedssh_cmmessage (seessh_connection(3erl)). The fun is supposed to return eithertrueto end the receiving operation (and get all the so-far-collected data back), orfalseto keep waiting for more data from the server. And even if you supply a fun, the function still returns immediately if the server closes the channel — so no lurking forever, bestie 🫶
rename(SSH, OldName, NewName) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🌈
rename(SSH, Server, OldName, NewName) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🌈
send(SSH, ChannelId, Data) -> ok | {error, Reason}
Equivalent to ct_ssh:send(SSH, ChannelId, 0, Data, DefaultTimeout) 📨
send(SSH, ChannelId, Data, Timeout) -> ok | {error, Reason}
Equivalent to ct_ssh:send(SSH, ChannelId, 0, Data, Timeout) 📨
send(SSH, ChannelId, Type, Data, Timeout) -> ok | {error, Reason}
Types:
SSH = connection()
ChannelId = integer()
Type = integer()
Data = list()
Timeout = integer()
Reason = term()Sends data to the server on the specified session channel 💫
send_and_receive(SSH, ChannelId, Data) -> {ok, Data} | {error, Reason}
Equivalent to ct_ssh:send_and_receive(SSH, ChannelId, Data, close) 🎀
send_and_receive(SSH, ChannelId, Data, End) -> {ok, Data} | {error, Reason}
Equivalent to ct_ssh;send_and_receive(SSH, ChannelId, 0, Data, End, DefaultTimeout) 🙈
ok so yes, that really is a;in there and not a:— the page prints it exactly like that, so type it as shown, bestie. Not me side-eyeing the typo 💀
send_and_receive(SSH, ChannelId, Data, End, Timeout) -> {ok, Data} | {error, Reason}
Equivalent to ct_ssh:send_and_receive(SSH, ChannelId, 0, Data, End, Timeout) 🎀
send_and_receive(SSH, ChannelId, Type, Data, End, Timeout) -> {ok, Data} | {error, Reason}
Types:
SSH = connection()
ChannelId = integer()
Type = integer()
Data = list()
End = Fun | close | timeout
Timeout = integer()
Reason = term()Sends data to the server on the specified session channel, then waits to receive the server response 🫡
For the details on the argument End, see ct_ssh:receive_response/4 — that's where all the Fun / close / timeout lore lives, iykyk.
session_close(SSH, ChannelId) -> ok | {error, Reason}
Types:
SSH = connection()
ChannelId = integer()
Reason = term()Closes an SSH session channel. Bye bestie 👋💅
session_open(SSH) -> {ok, ChannelId} | {error, Reason}
Equivalent to ct_ssh:session_open(SSH, DefaultTimeout) ⏳
session_open(SSH, Timeout) -> {ok, ChannelId} | {error, Reason}
Types:
SSH = connection()
Timeout = integer()
ChannelId = integer()
Reason = term()Opens a channel for an SSH session 🚪✨
sftp_connect(SSH) -> {ok, Server} | {error, Reason}
Types:
SSH = connection()
Server = pid()
Reason = term()Starts an SFTP session on an already existing SSH connection 🌸 The Server identifies the new session, and you must specify it whenever SFTP requests are to be sent — don't forget her, she's the main character of the sftp saga 👑
shell(SSH, ChannelId) -> ok | {error, Reason}
Equivalent to ct_ssh:shell(SSH, ChannelId, DefaultTimeout) 🐚
shell(SSH, ChannelId, Timeout) -> ok | {error, Reason}
Types:
SSH = connection()
ChannelId = integer()
Timeout = integer()
Reason = term()Requests that the user default shell (typically defined in /etc/passwd on Unix systems) is executed at the server end 🖥️✨
subsystem(SSH, ChannelId, Subsystem) -> Status | {error, Reason}
Equivalent to ct_ssh:subsystem(SSH, ChannelId, Subsystem, DefaultTimeout) ⭐
subsystem(SSH, ChannelId, Subsystem, Timeout) -> Status | {error, Reason}
Types:
SSH = connection()
ChannelId = integer()
Subsystem = string()
Timeout = integer()
Status = success | failure
Reason = term()Sends a request to execute a predefined subsystem 🌈
write(SSH, Handle, Data) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) ✍️
write(SSH, Server, Handle, Data) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) ✍️ (with the Server, as ever)
write_file(SSH, File, Iolist) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🍓
write_file(SSH, Server, File, Iolist) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🍓
write_file_info(SSH, Name, Info) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()For information and other types, see ssh_sftp(3erl) 🧚
write_file_info(SSH, Server, Name, Info) -> Result
Types:
SSH = connection()
Result = ssh_sftp_return() | {error, Reason}
Reason = term()🔗 SEE ALSO-ish 💅
okay so real talk, if you're looking for info and other types, bestie, you go see ssh_sftp(3erl) — that's the one. no cap, it's right there and it's got the rest of the lore you need 🫶
🎀 that's a wrap, gorgeous 🎀
and that's literally the whole page, you ate that 💖 this little gem comes to you from Ericsson AB as part of common_test 1.24.0.1, filed under ct_ssh(3erl) — iconic source, iconic version, whole page served fresh ✨ go forth and ssh responsibly, mwah 💅🌸
📦 where this page comes from
- ubuntu noble: erlang-manpages 1:25.3.2.8+dfsg-1ubuntu4 · Apache-2.0
- ubuntu noble: erlang-manpages 1:25.3.2.8+dfsg-1ubuntu4.8 · Apache-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms