-spec adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
                       when
                           ConnectionRef :: ssh:connection_ref(),
                           ChannelId :: ssh:channel_id(),
                           NumOfBytes :: integer().

Adjusts the SSH flow control window. This is to be done by both the client- and server-side channel processes.

Note

Channels implemented with the ssh_client_channel behavior do not normally need to call this function as flow control is handled by the behavior. The behavior adjusts the window every time the callback handle_ssh_msg/2 returns after processing channel data.

-spec close(ConnectionRef, ChannelId) -> ok
               when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id().

A server- or client-channel process can choose to close their session by sending a close event.

Note

This function is called by the ssh_client_channel behavior when the channel is terminated, see ssh_client_channel. Thus, channels implemented with the behavior are not to call this function explicitly.

-spec exec(ConnectionRef, ChannelId, Command, Timeout) -> result()
              when
                  ConnectionRef :: ssh:connection_ref(),
                  ChannelId :: ssh:channel_id(),
                  Command :: string(),
                  Timeout :: timeout().

Is to be called by a client-channel process to request that the server starts executing the given command. The result is several messages according to the following pattern. The last message is a channel close message, as the exec request is a one-time execution that closes the channel when it is done.

• N x data message(s) - The result of executing the command can be only one line or thousands of lines depending on the command.

• 0 or 1 x eof message - Indicates that no more data is to be sent.

• 0 or 1 x exit signal message - Not all systems send signals. For details on valid string values, see RFC 4254, Section 6.10

• 0 or 1 x exit status message - It is recommended by the SSH Connection Protocol to send this message, but that is not always the case.

• 1 x closed status message - Indicates that the ssh_client_channel started for the execution of the command has now been shut down.

See the User's Guide section on One-Time Execution for examples.

-spec exit_status(ConnectionRef, ChannelId, Status) -> ok
                     when
                         ConnectionRef :: ssh:connection_ref(),
                         ChannelId :: ssh:channel_id(),
                         Status :: integer().

Is to be called by a server-channel process to send the exit status of a command to the client.

-spec ptty_alloc(ConnectionRef, ChannelId, Options) -> result()
                    when
                        ConnectionRef :: ssh:connection_ref(),
                        ChannelId :: ssh:channel_id(),
                        Options :: proplists:proplist().

Equivalent to ptty_alloc/4.

-spec ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> result()
                    when
                        ConnectionRef :: ssh:connection_ref(),
                        ChannelId :: ssh:channel_id(),
                        Options :: proplists:proplist(),
                        Timeout :: timeout().

Sends an SSH Connection Protocol pty_req, to allocate a pseudo-terminal. Is to be called by an SSH client process.

Options:

• {term, string()} - Defaults to os:getenv("TERM") or vt100 if it is undefined.

• {width, integer()} - Defaults to 80 if pixel_width is not defined.

• {height, integer()} - Defaults to 24 if pixel_height is not defined.

• {pixel_width, integer()} - Is disregarded if width is defined.

• {pixel_height, integer()} - Is disregarded if height is defined.

• {pty_opts, [{posix_atom(), integer()}]} - Option can be an empty list. Otherwise, see possible POSIX names in Section 8 in RFC 4254.

-spec reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok
                       when
                           ConnectionRef :: ssh:connection_ref(),
                           WantReply :: boolean(),
                           Status :: req_status(),
                           ChannelId :: ssh:channel_id().

Sends status replies to requests where the requester has stated that it wants a status report, that is, WantReply = true. If WantReply is false, calling this function becomes a "noop". Is to be called while handling an SSH Connection Protocol message containing a WantReply boolean value.

-spec send(connection_ref(), channel_id(), iodata()) -> ok | {error, reason()}.

Equivalent to send/5.

-spec send(connection_ref(), channel_id(), iodata(), timeout()) -> ok | {error, reason()};
          (connection_ref(), channel_id(), ssh_data_type_code(), iodata()) -> ok | {error, reason()}.

Depending on input arguments equivalent to one of send/5 calls specified below.

Equivalent to send(ConnectionRef, ChannelId, 0, Data, TimeOut) if called with TimeOut being integer.

Equivalent to send(ConnectionRef, ChannelId, 0, Data, infinity) if called with TimeOut being infinity atom.

Equivalent to send(ConnectionRef, ChannelId, Type, Data, infinity) if called with last argument which is not integer or infinity atom.

-spec send(connection_ref(), channel_id(), ssh_data_type_code(), iodata(), timeout()) ->
              ok | {error, reason()}.

Is to be called by client- and server-channel processes to send data to each other.

The function subsystem/4 and subsequent calls of send/3,4,5 must be executed in the same process.

-spec send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}
                  when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id().

Sends EOF on channel ChannelId.

-spec session_channel(ConnectionRef, Timeout) -> Result
                         when
                             ConnectionRef :: ssh:connection_ref(),
                             Timeout :: timeout(),
                             Result :: {ok, ssh:channel_id()} | {error, reason()}.

Equivalent to session_channel/4.

-spec session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> Result
                         when
                             ConnectionRef :: ssh:connection_ref(),
                             InitialWindowSize :: pos_integer() | undefined,
                             MaxPacketSize :: pos_integer() | undefined,
                             Timeout :: timeout(),
                             Result :: {ok, ssh:channel_id()} | {error, reason()}.

Opens a channel for an SSH session. The channel id returned from this function is the id used as input to the other functions in this module.

-spec setenv(ConnectionRef, ChannelId, Var, Value, Timeout) -> success
                when
                    ConnectionRef :: ssh:connection_ref(),
                    ChannelId :: ssh:channel_id(),
                    Var :: string(),
                    Value :: string(),
                    Timeout :: timeout().

Environment variables can be passed before starting the shell/command. Is to be called by a client channel processes.

-spec shell(ConnectionRef, ChannelId) -> Result
               when
                   ConnectionRef :: ssh:connection_ref(),
                   ChannelId :: ssh:channel_id(),
                   Result :: ok | success | failure | {error, timeout}.

Is to be called by a client channel process to request that the user default shell (typically defined in /etc/passwd in Unix systems) is executed at the server end.

Note: the return value is ok instead of success unlike in other functions in this module. This is a fault that was introduced so long ago that any change would break a large number of existing software.

-spec subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> result()
                   when
                       ConnectionRef :: ssh:connection_ref(),
                       ChannelId :: ssh:channel_id(),
                       Subsystem :: string(),
                       Timeout :: timeout().

Is to be called by a client-channel process for requesting to execute a predefined subsystem on the server.

The function subsystem/4 and subsequent calls of send/3,4,5 must be executed in the same process.