Provided by: erlang-manpages_16.b.3-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 via the  SSH Connection Protocol. This module  provides
       a  callback  API that takes care of generic channel aspects such as flow control and close
       messages and 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  use  the  -behaviour(ssh_daemon_channel).  instead  of
       -behaviour(ssh_channel).  as  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 limited version of the ssh_channel behaviour.

DATA TYPES

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

       boolean() = true | false

       string() = list of ASCII characters

       timeout() = infinity | integer() - in milliseconds.

       ssh_connection_ref() - opaque to the user 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 currently 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 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   timeout   occurs.   The  channel  will  call
              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
              will call 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 will enter 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  proc_lib(3erl).  The  user  is  responsible  for  any
              initialization of the process and needs to 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 callback module's init function.

                {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
              for some reason 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 to the user, see explanation below
                 Reply = term()

              This  function can be used by a channel to explicitly 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 will be 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   cannot   be   defined   in   the   return    value    of
                   ssh_connection:session_channel/[2,4]
                 ChannelCb = atom()
                    The  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 processes that handles an SSH channel. It will be called internally by the
              SSH  daemon  or explicitly by the SSH client implementations. The behavior will set
              the trap_exit flag to true.

 CALLBACK TIMEOUTS
       The timeout values that may be returned by the callback functions has the  same  semantics
       as   in   a   gen_server   If   the   timeout   occurs  handle_msg/2  will  be  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()
                   The 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 should update its internal
              state   during   a   release   upgrade/downgrade,   i.e.   when   the   instruction
              {update,Module,Change,...}  where  Change={advanced,Extra}  is  given  in the appup
              file. See OTP Design Principles for more information.

          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. It could be possible to upgrade  the  subsystem
              channels, when upgrading the user application, if the callback functions can handle
              two versions of the state, but this function can not 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 timeouts see the section CALLBACK TIMEOUTS.

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

              Types:

                 Msg = term()
                 From = opaque to the user should 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 timeouts see the 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 ssh_channel:cast/2

              For more detailed information on timeouts see the section CALLBACK TIMEOUTS.

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

              Types:

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

              Handle other messages than ssh connection protocol, call or cast messages  sent  to
              the channel.

              Possible erlang 'EXIT'-messages should be handled by this function and all channels
              should handle the following message.

                {ssh_channel_up, ssh_channel_id(), ssh_connection_ref()}:
                  This is the first messages that will be received by the  channel,  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 just 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.

              The following message is completely taken care of by the SSH channel behavior

                {closed, ssh_channel_id()}:
                   The channel behavior will send a close message to the other  side  if  such  a
                  message  has  not  already been sent and then terminate 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  will be called if it has not been
              called earlier. This function should do any necessary cleaning up. When it returns,
              the channel process terminates with reason Reason. The return value is ignored.