Provided by: erlang-manpages_25.2.3+dfsg-1_all bug

NAME

       ssh_client_channel - -behaviour(ssh_client_channel). (Replaces ssh_channel)

DESCRIPTION

   Note:
       This module replaces ssh_channel.

       The  old  module  is  still  available  for  compatibility, but should not be used for new
       programs. The old module will not be maintained except for some error corrections

       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  for  clients,  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  a  ssh  subsystem  for  daemons,  use  -behaviour(ssh_server_channel)
       (Replaces ssh_daemon_channel) instead.

   Dont:
       Functions in this module are not supposed to be called outside a module implementing  this
       behaviour!

EXPORTS

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

              Types:

                 ChannelRef = pid()
                   As returned by 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 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 init/1

              Makes an existing process an  ssh_client_channel  (replaces  ssh_channel)  process.
              Does  not  return,  instead  the  calling  process  enters  the  ssh_client_channel
              (replaces ssh_channel)  process  receive  loop  and  become  an  ssh_client_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 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, ssh:connection_ref()}:
                  Reference to the ssh connection as returned by ssh:connect/3.

                {channel_id, ssh:channel_id()}:
                  Id of the ssh channel as returned by ssh_connection:session_channel/2,4.

          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
              start/4 or 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 call/[2,3].

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

              Types:

                 SshConnection = ssh:connection_ref()
                   As returned by ssh:connect/3
                 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 FUNCTIONS

       The following functions are to be exported from a ssh_client_channel callback module.

       The timeout 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 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 timeouts.

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

              Types:

                 Msg = term()
                 From = opaque()
                   Is to be used as argument to 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 call/[2,3]
                 NewState = term()
                 Reason = term()

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

              For more detailed information on time-outs,, see Section Callback timeouts.

       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 cast/2.

              For more detailed information on time-outs, see Section Callback timeouts.

       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
                  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_client_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.