ct_telnet(3erl) 					     Erlang Module Definition						   ct_telnet(3erl)

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. See the unix_telnet manual page for
       information about how to use ct_telnet, and configure connections, specifically for unix hosts.

       The following default values are defined in ct_telnet:

	  Connection timeout = 10 sec (time to wait for connection)
	  Command timeout = 10 sec (time to wait for a command to return)
	  Max no of reconnection attempts = 3
	  Reconnection interval = 5 sek (time to wait in between reconnection attempts)
	  Keep alive = true (will send NOP to the server every 10 sec if connection is idle)

       These parameters can be altered 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}]}.

       Millisec = integer(), N = integer()

       Enter the telnet_settings term in a configuration file included in the test and ct_telnet will retrieve the information automatically. Note
       that keep_alive may be specified per connection if required. See unix_telnet for details.

DATA TYPES

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

	 connection_type() = telnet | ts1 | ts2 :

	 handle() = handle() (see module ct_gen_conn) :

	   Handle for a specific telnet connection.

	 prompt_regexp() = string() :

	   A  regular  expression  which matches all possible prompts for a specific type of target. The regexp must not have any groups i.e. when
	   matching, re:run/3 shall return a list with one single element.

EXPORTS

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

	      Types  Connection = connection() (see module ct_telnet)

	      Close the telnet connection and stop the process managing it.

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

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

	      Equivalent to cmd(Connection, Cmd, DefaultTimeout) .

       cmd(Connection, Cmd, Timeout) -> term()

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

	      Equivalent to cmdf(Connection, CmdFormat, Args, DefaultTimeout) .

       cmdf(Connection, CmdFormat, Args, Timeout) -> term()

       cont_log(Str, Args) -> term()

       end_log() -> term()

       expect(Connection, Patterns) -> term()

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

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

	      Types  Connection = connection() (see module ct_telnet)
		     Patterns = Pattern | [Pattern]
		     Pattern = string() | {Tag, string()} | prompt | {prompt, Prompt}
		     Prompt = string()
		     Tag = term()
		     Opts = [Opt]
		     Opt = {timeout, Timeout} | repeat | {repeat, N} | sequence | {halt, HaltPatterns} | ignore_prompt
		     Timeout = integer()
		     N = integer()
		     HaltPatterns = Patterns
		     MatchList = [Match]
		     Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}
		     RxMatch = [string()]
		     HaltReason = done | Match
		     Reason = timeout | {prompt, Prompt}

	      Get data from telnet and wait for the expected pattern.

	      Pattern can be a POSIX regular expression. If more than one pattern is given, the function returns when the first match is found.

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

	      If a Tag is given, the returned Match will also include the matched Tag . Else, only RxMatch is returned.

	      The function will always return when a prompt is found, unless the ignore_prompt options is used.

	      The timeout option indicates that the function shall return if the telnet client is idle (i.e. if no data is received) for more than
	      Timeout milliseconds. Default timeout is 10 seconds.

	      The repeat option indicates that the pattern(s) shall be matched multiple times. If N is given, the pattern(s)  will  be	matched  N
	      times, and the function will return with HaltReason = done .

	      The  sequence  option  indicates that all patterns shall be matched in a sequence. A match will not be concluded untill all patterns
	      are matched.

	      Both repeat and sequence can be interrupted by one or more HaltPatterns . When sequence or repeat is used, there will  always  be  a
	      MatchList returned, i.e. a list of Match instead of only one Match . There will also be a HaltReason returned.

	      Examples:
	      expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}], [sequence,{halt,[{nnn,"NNN"}]}]).
	      will  try  to  match "ABC" first and then "XYZ", but if "NNN" appears the function will return {error,{nnn,["NNN"]}} . If both "ABC"
	      and "XYZ" are matched, the function will return {ok,[AbcMatch,XyzMatch]} .

	      expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}], [{repeat,2},{halt,[{nnn,"NNN"}]}]).
	      will try to match "ABC" or "XYZ" twice. If "NNN" appears the function will return with HaltReason = {nnn,["NNN"]} .

	      The repeat and sequence options can be combined in order to match a sequence multiple times.

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

	      Types  Connection = connection() (see module ct_telnet)
		     Data = [string()]

	      Get all data which has been received by the telnet client since last command was sent.

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

	      Equivalent to open(Name, telnet) .

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

	      Types  Name = target_name()
		     ConnType = connection_type() (see module ct_telnet)
		     Handle = handle() (see module ct_telnet)

	      Open a telnet connection to the specified target host.

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

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

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

	      Types  KeyOrName = Key | Name
		     Key = atom()
		     Name = target_name() (see module ct)
		     ConnType = connection_type()
		     TargetMod = atom()
		     Extra = term()
		     Handle = handle()

	      Open a telnet connection to the specified target host.

	      The target data must exist in a configuration file. The connection may be associated with either Name and/or the returned  Handle  .
	      To  allocate a name for the target, use ct:require/2 in a test case, or use a require statement in the suite info function ( suite/0
	      ), or in a test case info function. If you want the connection to be associated with Handle only (in case you need to open  multiple
	      connections  to a host for example), simply use Key , the configuration variable name, to specify the target. Note that a connection
	      that has no associated target name can only be closed with the handle value.

	      TargetMod is a module which exports the functions connect(Ip,Port,KeepAlive,Extra) and get_prompt_regexp() for the given	TargetType
	      (e.g. unix_telnet ).

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

	      Types  Connection = connection() (see module ct_telnet)
		     Cmd = string()

	      Send a telnet command and return immediately.

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

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

	      Types  Connection = connection() (see module ct_telnet)
		     CmdFormat = string()
		     Args = list()

	      Send a telnet command and return immediately (uses a format string and a list of arguments to build the command).

SEE ALSO

       unix_telnet

AUTHORS

       <>

								 common_test 1.5.3						   ct_telnet(3erl)