Provided by: erlang-manpages_22.2.7+dfsg-1_all bug

NAME

       ct_telnet - Common Test specific layer on top of Telnet client ct_telnet_client.erl

DESCRIPTION

       Common Test specific layer on top of Telnet client ct_telnet_client.erl.

       Use  this  module to set up Telnet connections, send commands, and perform string matching
       on the result. For information about how  to  use  ct_telnet  and  configure  connections,
       specifically for UNIX hosts, see the unix_telnet manual page.

       Default values defined in ct_telnet:

         * Connection timeout (time to wait for connection) = 10 seconds

         * Command timeout (time to wait for a command to return) = 10 seconds

         * Max number of reconnection attempts = 3

         * Reconnection interval (time to wait in between reconnection attempts) = 5 seconds

         * Keep alive (sends NOP to the server every 8 sec if connection is idle) = true

         * Polling limit (max number of times to poll to get a remaining string terminated) = 0

         * Polling interval (sleep time between polls) = 1 second

         * The TCP_NODELAY option for the telnet socket is disabled (set to false) per default

       These parameters can be modified by the user with the following configuration term:

        {telnet_settings, [{connect_timeout,Millisec},
                           {command_timeout,Millisec},
                           {reconnection_attempts,N},
                           {reconnection_interval,Millisec},
                           {keep_alive,Bool},
                           {poll_limit,N},
                           {poll_interval,Millisec},
                           {tcp_nodelay,Bool}]}.

       Millisec = integer(), N = integer()

       Enter  the telnet_settings term in a configuration file included in the test and ct_telnet
       retrieves the information automatically.

       keep_alive can be specified per connection, if necessary. For details, see unix_telnet.

LOGGING

       The default logging  behavior  of  ct_telnet  is  to  print  information  about  performed
       operations,  commands,  and  their  corresponding  results  to the test case HTML log. The
       following is not printed to the HTML log: text strings sent from the  Telnet  server  that
       are  not explicitly received by a ct_telnet function, such as expect/3. However, ct_telnet
       can be configured to use a special purpose event handler,  implemented  in  ct_conn_log_h,
       for  logging  all  Telnet  traffic.  To use this handler, install a Common Test hook named
       cth_conn_log. Example (using the test suite information function):

        suite() ->
            [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].

       conn_mod() is the name of the Common Test module  implementing  the  connection  protocol,
       that is, ct_telnet.

       The cth_conn_log hook performs unformatted logging of Telnet data to a separate text file.
       All Telnet communication is captured and printed, including any data sent from the server.
       The link to this text file is located at the top of the test case HTML log.

       By  default, data for all Telnet connections is logged in one common file (named default),
       which can get messy, for example, if multiple Telnet sessions  are  running  in  parallel.
       Therefore  a  separate log file can be created for each connection. To configure this, use
       hook option hosts and list the names of the servers/connections to be used in  the  suite.
       The connections must be named for this to work (see ct_telnet:open/1,2,3,4).

       Hook option log_type can be used to change the cth_conn_log behavior. The default value of
       this option is raw, which results in the behavior described above. If the value is set  to
       html, all Telnet communication is printed to the test case HTML log instead.

       All cth_conn_log hook options described can also be specified in a configuration file with
       configuration variable ct_conn_log.

       Example:

        {ct_conn_log, [{ct_telnet,[{log_type,raw},
                                   {hosts,[key_or_name()]}]}]}

   Note:
       Hook options specified in a configuration file overwrite any hard-coded  hook  options  in
       the test suite.

       Logging Example:

       The  following  ct_hooks  statement causes printing of Telnet traffic to separate logs for
       the connections server1 and server2. Traffic for any other connections is  logged  in  the
       default Telnet log.

        suite() ->
            [{ct_hooks,
              [{cth_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}]}].

       As  previously  explained,  this  specification  can also be provided by an entry like the
       following in a configuration file:

        {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.

       In this case the ct_hooks statement in the test suite can look as follows:

        suite() ->
            [{ct_hooks, [{cth_conn_log, []}]}].

DATA TYPES

         connection() = handle() | {target_name(), connection_type()} | target_name():

           For target_name(), see module ct.

         connection_type() = telnet | ts1 | ts2:

         handle() = handle():

           Handle for a specific Telnet connection, see module ct.

         prompt_regexp() = string():

           Regular expression matching all possible prompts for a specific  target  type.  regexp
           must  not  have any groups, that is, when matching, re:run/3 (in STDLIB) must return a
           list with one single element.

EXPORTS

       close(Connection) -> ok | {error, Reason}

              Types:

                 Connection = connection()
                 Reason = term()

              Closes the Telnet connection and stops the process managing it.

              A connection can be associated with a target name and/or a  handle.  If  Connection
              has  no  associated  target  name, it can only be closed with the handle value (see
              ct_telnet:open/4).

       cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}

              Equivalent to ct_telnet:cmd(Connection, Cmd, []).

       cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}

              Types:

                 Connection = connection()
                 Cmd = string()
                 Opts = [Opt]
                 Opt = {timeout, timeout()} | {newline, boolean() | string()}
                 Data = [string()]
                 Reason = term()

              Sends a command through Telnet and waits for prompt.

              By default, this function adds "\n" to the end of the specified command. If this is
              not  desired,  use  option  {newline,false}.  This  is necessary, for example, when
              sending Telnet command sequences  prefixed  with  character  Interpret  As  Command
              (IAC). Option {newline,string()} can also be used if a different line end than "\n"
              is required, for instance {newline,"\r\n"}, to add both carriage return and newline
              characters.

              Option  timeout  specifies  how  long  the client must wait for prompt. If the time
              expires, the function returns {error,timeout}. For information  about  the  default
              value  for  the command timeout, see the list of default values in the beginning of
              this module.

       cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}

              Equivalent to ct_telnet:cmdf(Connection, CmdFormat, Args, []).

       cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}

              Types:

                 Connection = connection()
                 CmdFormat = string()
                 Args = list()
                 Opts = [Opt]
                 Opt = {timeout, timeout()} | {newline, boolean() | string()}
                 Data = [string()]
                 Reason = term()

              Sends a Telnet command and waits for prompt (uses a format string  and  a  list  of
              arguments to build the command).

              For details, see ct_telnet:cmd/3.

       expect(Connection, Patterns) -> term()

              Equivalent to ct_telnet:expect(Connections, Patterns, []).

       expect(Connection,  Patterns, Opts) -> {ok, Match} | {ok, MatchList, HaltReason} | {error,
       Reason}

              Types:

                 Connection = connection()
                 Patterns = Pattern | [Pattern]
                 Pattern = string() | {Tag, string()} | prompt | {prompt, Prompt}
                 Prompt = string()
                 Tag = term()
                 Opts = [Opt]
                 Opt = {idle_timeout, IdleTimeout} | {total_timeout,  TotalTimeout}  |  repeat  |
                 {repeat,  N} | sequence | {halt, HaltPatterns} | ignore_prompt | no_prompt_check
                 | wait_for_prompt | {wait_for_prompt, Prompt}
                 IdleTimeout = infinity | integer()
                 TotalTimeout = infinity | integer()
                 N = integer()
                 HaltPatterns = Patterns
                 MatchList = [Match]
                 Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}
                 RxMatch = [string()]
                 HaltReason = done | Match
                 Reason = timeout | {prompt, Prompt}

              Gets data from Telnet and waits for the expected pattern.

              Pattern can be a POSIX regular expression. The function returns when a  pattern  is
              successfully matched (at least one, in the case of multiple patterns).

              RxMatch  is  a  list of matched strings. It looks as follows [FullMatch, SubMatch1,
              SubMatch2, ...], where FullMatch  is  the  string  matched  by  the  whole  regular
              expression,  and  SubMatchN  is  the  string  that  matched subexpression number N.
              Subexpressions are denoted with '(' ')' in the regular expression.

              If a Tag is specified, the returned Match also includes the matched Tag. Otherwise,
              only RxMatch is returned.

              Options:

                idle_timeout:
                  Indicates  that the function must return if the Telnet client is idle (that is,
                  if no data is received) for more than IdleTimeout milliseconds.  Default  time-
                  out is 10 seconds.

                total_timeout:
                  Sets  a  time  limit  for  the  complete  expect  operation. After TotalTimeout
                  milliseconds, {error,timeout} is returned. Default is  infinity  (that  is,  no
                  time limit).

                ignore_prompt | no_prompt_check:
                  >The  function  returns  when  a prompt is received, even if no pattern has yet
                  been matched, and {error,{prompt,Prompt}} is returned. However,  this  behavior
                  can  be  modified  with  option  ignore_prompt or option no_prompt_check, which
                  tells expect to return only when a match is found or after a time-out.

                ignore_prompt:
                  ct_telnet ignores any prompt found. This option is useful if data sent  by  the
                  server   can   include  a  pattern  matching  prompt  regexp  (as  returned  by
                  TargedMod:get_prompt_regexp/0), but is not to not cause the function to return.

                no_prompt_check:
                  ct_telnet does not search for a prompt at all. This is useful if, for  example,
                  Pattern itself matches the prompt.

                wait_for_prompt:
                  Forces  ct_telnet  to wait until the prompt string is received before returning
                  (even if a pattern  has  already  been  matched).  This  is  equal  to  calling
                  expect(Conn,  Patterns++[{prompt,Prompt}], [sequence|Opts]). Notice that option
                  idle_timeout and total_timeout can abort the operation of waiting for prompt.

                repeat | repeat, N:
                  The pattern(s)  must  be  matched  multiple  times.  If  N  is  specified,  the
                  pattern(s)  are  matched  N  times, and the function returns HaltReason = done.
                  This option can be interrupted by one or more HaltPatterns. MatchList is always
                  returned,  that  is, a list of Match instead of only one Match. Also HaltReason
                  is returned.

                sequence:
                  All patterns must be matched in a sequence. A match is not concluded until  all
                  patterns   are  matched.  This  option  can  be  interrupted  by  one  or  more
                  HaltPatterns. MatchList is always returned, that is, a list of Match instead of
                  only one Match. Also HaltReason is returned.

              Example 1:

               expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[sequence,{halt,[{nnn,"NNN"}]}])

              First this tries to match "ABC", and then "XYZ", but if "NNN" appears, the function
              returns {error,{nnn,["NNN"]}}. If both "ABC" and "XYZ" are  matched,  the  function
              returns {ok,[AbcMatch,XyzMatch]}.

              Example 2:

               expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[{repeat,2},{halt,[{nnn,"NNN"}]}])

              This  tries  to  match "ABC" or "XYZ" twice. If "NNN" appears, the function returns
              HaltReason = {nnn,["NNN"]}.

              Options repeat and sequence can be combined to match a sequence multiple times.

       get_data(Connection) -> {ok, Data} | {error, Reason}

              Types:

                 Connection = connection()
                 Data = [string()]
                 Reason = term()

              Gets all data received by the Telnet client since the last command was  sent.  Only
              newline-terminated  strings  are  returned. If the last received string has not yet
              been terminated, the connection can be polled automatically  until  the  string  is
              complete.

              The  polling  feature  is  controlled  by  the  configuration values poll_limit and
              poll_interval and is by default disabled. This means that the function  immediately
              returns  all  complete strings received and saves a remaining non-terminated string
              for a later get_data call.

       open(Name) -> {ok, Handle} | {error, Reason}

              Equivalent to ct_telnet:open(Name, telnet).

       open(Name, ConnType) -> {ok, Handle} | {error, Reason}

              Types:

                 Name = target_name()
                 ConnType = connection_type()
                 Handle = handle()
                 Reason = term()

              Opens a Telnet connection to the specified target host.

       open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}

              Equivalent to ct_telnet:ct_telnet:open(KeyOrName, ConnType, TargetMod, []).

       open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}

              Types:

                 KeyOrName = Key | Name
                 Key = atom()
                 Name = target_name()
                 ConnType = connection_type()
                 TargetMod = atom()
                 Extra = term()
                 Handle = handle()
                 Reason = term()

              Opens a Telnet connection to the specified target host.

              The target data  must  exist  in  a  configuration  file.  The  connection  can  be
              associated with Name and/or the returned Handle. To allocate a name for the target,
              use one of the following alternatives:

                * ct:require/2 in a test case

                * A require statement in the suite information function (suite/0)

                * A require statement in a test case information function

              If you want the connection to be associated with Handle only (if you, for  example,
              need  to  open multiple connections to a host), use Key, the configuration variable
              name, to specify the target. Notice that a connection without an associated  target
              name can only be closed with the Handle value.

              TargetMod  is  a  module  that  exports  the functions connect(Ip, Port, KeepAlive,
              Extra)  and  get_prompt_regexp()  for  the  specified  TargetType   (for   example,
              unix_telnet).

              For target_name(), see module ct.

              See also ct:require/2.

       send(Connection, Cmd) -> ok | {error, Reason}

              Equivalent to ct_telnet:send(Connection, Cmd, []).

       send(Connection, Cmd, Opts) -> ok | {error, Reason}

              Types:

                 Connection = connection()
                 Cmd = string()
                 Opts = [Opt]
                 Opt = {newline, boolean() | string()}
                 Reason = term()

              Sends a Telnet command and returns immediately.

              By default, this function adds "\n" to the end of the specified command. If this is
              not desired, option {newline,false} can be used. This is  necessary,  for  example,
              when  sending Telnet command sequences prefixed with character Interpret As Command
              (IAC). Option {newline,string()} can also be used if a different line end than "\n"
              is required, for instance {newline,"\r\n"}, to add both carriage return and newline
              characters.

              The resulting output from the command can  be  read  with  ct_telnet:get_data/2  or
              ct_telnet:expect/2,3.

       sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}

              Equivalent to ct_telnet:sendf(Connection, CmdFormat, Args, []).

       sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}

              Types:

                 Connection = connection()
                 CmdFormat = string()
                 Args = list()
                 Opts = [Opt]
                 Opt = {newline, boolean() | string()}
                 Reason = term()

              Sends  a Telnet command and returns immediately (uses a format string and a list of
              arguments to build the command).

              For details, see ct_telnet:send/3.

SEE ALSO

       unix_telnet