Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all bug

NAME

       ssh_channel - -behaviour(ssh_channel).

DESCRIPTION

       SSH  services  (clients and servers) are implemented as channels that are multiplexed over
       an SSH connection and communicates over the  SSH Connection Protocol. This module provides
       a  callback API that takes care of generic channel aspects, such as flow control and close
       messages. It lets the callback functions take care of the service  (application)  specific
       parts. This behavior also ensures that the channel process honors the principal of an OTP-
       process so that it can be part of a supervisor tree. This  is  a  requirement  of  channel
       processes  implementing  a subsystem that will be added to the ssh applications supervisor
       tree.

   Note:
       When  implementing  an  ssh  subsystem,  use  -behaviour(ssh_daemon_channel)  instead   of
       -behaviour(ssh_channel).  The  reason  is  that  the  only relevant callback functions for
       subsystems  are  init/1,  handle_ssh_msg/2,  handle_msg/2,  and   terminate/2.   So,   the
       ssh_daemon_channel behaviour is a limited version of the ssh_channel behaviour.

DATA TYPES

       Type  definitions that are used more than once in this module, or abstractions to indicate
       the intended use of the data type, or both:

         boolean() =:
           true | false

         string() =:
           list of ASCII characters

         timeout() =:
           infinity | integer() in milliseconds

         ssh_connection_ref() =:
           opaque() -as returned by ssh:connect/3 or sent to an SSH channel process

         ssh_channel_id() =:
           integer()

         ssh_data_type_code() =:
           1 ("stderr") | 0 ("normal") are the valid values, see RFC 4254 Section 5.2

EXPORTS

       call(ChannelRef, Msg) ->
       call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason}

              Types:

                 ChannelRef = pid()
                   As returned by ssh_channel:start_link/4
                 Msg = term()
                 Timeout = timeout()
                 Reply = term()
                 Reason = closed | timeout

              Makes a synchronous call to the channel process by sending a  message  and  waiting
              until a reply arrives, or a time-out occurs. The channel calls Module:handle_call/3
              to handle the message. If the channel process does not exist,  {error,  closed}  is
              returned.

       cast(ChannelRef, Msg) -> ok

              Types:

                 ChannelRef = pid()
                   As returned by ssh_channel:start_link/4
                 Msg = term()

              Sends  an  asynchronous  message to the channel process and returns ok immediately,
              ignoring if the destination node or channel process does  not  exist.  The  channel
              calls Module:handle_cast/2 to handle the message.

       enter_loop(State) -> _

              Types:

                 State = term()
                   as returned by ssh_channel:init/1

              Makes  an  existing  process  an  ssh_channel process. Does not return, instead the
              calling  process  enters  the  ssh_channel  process  receive  loop  and  become  an
              ssh_channel  process.  The  process  must  have been started using one of the start
              functions in proc_lib, see the proc_lib(3erl) manual page in STDLIB.  The  user  is
              responsible for any initialization of the process and must call ssh_channel:init/1.

       init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason}

              Types:

                 Options = [{Option, Value}]
                 State = term()
                 Timeout = timeout()
                 Reason = term()

              The following options must be present:

                {channel_cb, atom()}:
                  The module that implements the channel behaviour.

                {init_args(), list()}:
                  The list of arguments to the init function of the callback module.

                {cm, connection_ref()}:
                  Reference to the ssh connection as returned by ssh:connect/3

                {channel_id, channel_id()}:
                  Id of the ssh channel.

          Note:
              This  function  is  normally not called by the user. The user only needs to call if
              the channel process needs to be started with help of proc_lib  instead  of  calling
              ssh_channel:start/4 or ssh_channel:start_link/4.

       reply(Client, Reply) -> _

              Types:

                 Client = opaque()
                 Reply = term()

              This  function  can  be  used  by a channel to send a reply to a client that called
              call/[2,3]  when  the  reply  cannot  be   defined   in   the   return   value   of
              Module:handle_call/3.

              Client  must  be the From argument provided to the callback function handle_call/3.
              Reply is an arbitrary term, which is given back to the client as the  return  value
              of ssh_channel:call/[2,3].

       start(SshConnection, ChannelId, ChannelCb, CbInitArgs) ->
       start_link(SshConnection,  ChannelId, ChannelCb, CbInitArgs) -> {ok, ChannelRef} | {error,
       Reason}

              Types:

                 SshConnection = ssh_connection_ref()
                 ChannelId = ssh_channel_id()
                   As returned by  ssh_connection:session_channel/[2,4].
                 ChannelCb = atom()
                   Name of the module implementing the service-specific parts of the channel.
                 CbInitArgs = [term()]
                   Argument list for the init function in the callback module.
                 ChannelRef = pid()

              Starts a process that handles an SSH channel. It is called internally, by  the  ssh
              daemon,  or  explicitly  by  the  ssh client implementations. The behavior sets the
              trap_exit flag to true.

CALLBACK TIME-OUTS

       The time-out values that can be returned by the callback functions have the same semantics
       as  in a gen_server. If the time-out occurs, handle_msg/2 is called as handle_msg(timeout,
       State).

EXPORTS

       Module:code_change(OldVsn, State, Extra) -> {ok, NewState}

              Types:

                 OldVsn = term()
                   In the case of an upgrade, OldVsn is Vsn, and in  the  case  of  a  downgrade,
                   OldVsn  is  {down,Vsn}.  Vsn  is  defined  by  the vsn attribute(s) of the old
                   version of the callback module Module. If no such attribute  is  defined,  the
                   version is the checksum of the BEAM file.
                 State = term()
                   Internal state of the channel.
                 Extra = term()
                   Passed "as-is" from the {advanced,Extra} part of the update instruction.

              Converts process state when code is changed.

              This  function is called by a client-side channel when it is to update its internal
              state during a  release  upgrade  or  downgrade,  that  is,  when  the  instruction
              {update,Module,Change,...},  where  Change={advanced,Extra},  is given in the appup
              file. For more information, refer to Section 9.11.6 Release  Handling  Instructions
              in the System Documentation.

          Note:
              Soft  upgrade  according to the OTP release concept is not straight forward for the
              server side, as subsystem channel processes are spawned by the ssh application  and
              hence  added  to  its  supervisor tree. The subsystem channels can be upgraded when
              upgrading the user application, if the callback functions can handle  two  versions
              of the state, but this function cannot be used in the normal way.

       Module:init(Args) -> {ok, State} | {ok, State, timeout()} | {stop, Reason}

              Types:

                 Args = term()
                   Last argument to ssh_channel:start_link/4.
                 State = term()
                 Reason = term()

              Makes  necessary  initializations  and  returns  the  initial  channel state if the
              initializations succeed.

              For more detailed information on time-outs, see Section CALLBACK TIME-OUTS.

       Module:handle_call(Msg, From, State) -> Result

              Types:

                 Msg = term()
                 From = opaque()
                   Is to be used as argument to ssh_channel:reply/2
                 State = term()
                 Result = {reply, Reply,  NewState}  |  {reply,  Reply,  NewState,  timeout()}  |
                 {noreply,  NewState}  |  {noreply , NewState, timeout()} | {stop, Reason, Reply,
                 NewState} | {stop, Reason, NewState}
                 Reply = term()
                   Will be the return value of ssh_channel:call/[2,3]
                 NewState = term()
                 Reason = term()

              Handles messages sent by calling ssh_channel:call/[2,3]

              For more detailed information on time-outs,, see Section CALLBACK TIME-OUTS.

       Module:handle_cast(Msg, State) -> Result

              Types:

                 Msg = term()
                 State = term()
                 Result = {noreply, NewState} | {noreply, NewState, timeout()} |  {stop,  Reason,
                 NewState}
                 NewState = term()
                 Reason = term()

              Handles messages sent by calling ssh_channel:cast/2.

              For more detailed information on time-outs, see Section CALLBACK TIME-OUTS.

       Module:handle_msg(Msg, State) -> {ok, State} | {stop, ChannelId, State}

              Types:

                 Msg = timeout | term()
                 ChannelId = ssh_channel_id()
                 State = term()

              Handles other messages than SSH Connection Protocol, call, or cast messages sent to
              the channel.

              Possible Erlang 'EXIT' messages is to be handled by this function and all  channels
              are to handle the following message.

                {ssh_channel_up, ssh_channel_id(), ssh_connection_ref()}:
                  This is the first message that the channel receives. It is sent just before the
                  ssh_channel:init/1 function returns successfully. This is especially useful  if
                  the  server  wants  to  send  a message to the client without first receiving a
                  message from it. If the message is not useful  for  your  particular  scenario,
                  ignore it by immediately returning {ok, State}.

       Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, ChannelId, State}

              Types:

                 Msg = ssh_connection:event()
                 ChannelId = ssh_channel_id()
                 State = term()

              Handles  SSH Connection Protocol messages that may need service-specific attention.
              For details, see  ssh_connection:event().

              The following message is taken care of by the ssh_channel behavior.

                {closed, ssh_channel_id()}:
                  The channel behavior sends a close message to the other side, if such a message
                  has not already been sent. Then it terminates the channel with reason normal.

       Module:terminate(Reason, State) -> _

              Types:

                 Reason = term()
                 State = term()

              This  function is called by a channel process when it is about to terminate. Before
              this function is called,  ssh_connection:close/2  is called, if  it  has  not  been
              called  earlier. This function does any necessary cleaning up. When it returns, the
              channel process terminates with reason Reason. The return value is ignored.