.TH ct_telnet 3 "common_test  1.3.2" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
ct_telnet \- Common Test specific layer on top of telnet client ct_telnet_client\&.erl\&.
.SH DESCRIPTION
.LP
Common Test specific layer on top of telnet client ct_telnet_client\&.erl
.LP
Use this module to set up telnet connections, send commands and perform string matching on the result\&. (See the \fIunix_telnet\fR manual page for information about how ct_telnet may be used specifically with unix hosts\&.)
.LP
The rx driver used by ct_telnet for handling regular expressions is currently only ported to Unix and Linux and will not work on Windows!
.LP
The following default values are defined in ct_telnet:

.nf
   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)
   
.fi
.LP
These parameters can be altered by the user with the following configuration term:

.nf
   {telnet_settings, [{connect_timeout,Millisec},
                      {command_timeout,Millisec},
                      {reconnection_attempts,N},
                      {reconnection_interval,Millisec}]}\&.
   
.fi
.LP
\fIMillisec = integer(), N = integer()\fR
.LP
Enter the \fItelnet_settings\fR term in a configuration file included in the test and ct_telnet will retrieve the information automatically\&.

.SH DATA TYPES
.RS 2
.TP 4
.B
\fIconnection() = handle() | {target_name() (see module ct), connection_type()} | target_name() (see module ct)\fR:

.TP 4
.B
\fIconnection_type() = telnet | ts1 | ts2\fR:

.TP 4
.B
\fIhandle() = handle() (see module ct_gen_conn)\fR:

.RS 4
.LP
Handle for a specific telnet connection\&.
.LP

.RE
.TP 4
.B
\fIprompt_regexp() = string()\fR:

.RS 4
.LP
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, rx:match shall return a list with one single element\&. 
.LP

.RE
.RE
.SH EXPORTS
.LP
.B
close(Connection) -> ok | {error, Reason}
.br
.RS
.TP
Types
Connection = connection() (see module ct_telnet)
.br
.RE
.RS
.LP
Close the telnet connection and stop the process managing it\&.
.RE
.LP
.B
cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}
.br
.RS
.LP
Equivalent to cmd(Connection, Cmd, DefaultTimeout)\&.
.RE
.LP
.B
cmd(Connection, Cmd, Timeout) -> {ok, Data} | {error, Reason}
.br
.RS
.TP
Types
Connection = connection() (see module ct_telnet)
.br
Cmd = string()
.br
Timeout = integer()
.br
Data = [string()]
.br
.RE
.RS
.LP
Send a command via telnet and wait for prompt\&.
.RE
.LP
.B
cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}
.br
.RS
.LP
Equivalent to cmdf(Connection, CmdFormat, Args, DefaultTimeout)\&.
.RE
.LP
.B
cmdf(Connection, CmdFormat, Args, Timeout) -> {ok, Data} | {error, Reason}
.br
.RS
.TP
Types
Connection = connection() (see module ct_telnet)
.br
CmdFormat = string()
.br
Args = list()
.br
Timeout = integer()
.br
Data = [string()]
.br
.RE
.RS
.LP
Send a telnet command and wait for prompt (uses a format string and list of arguments to build the command)\&. -----------------------------------------------------------------
.RE
.LP
.B
cont_log() -> term()
.br
.RS
.RE
.LP
.B
end_log() -> term()
.br
.RS
.RE
.LP
.B
expect(Connection, Patterns) -> term()
.br
.RS
.LP
Equivalent to expect(Connections, Patterns, [])\&.
.RE
.LP
.B
expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList, HaltReason} | {error, Reason}
.br
.RS
.TP
Types
Connection = connection() (see module ct_telnet)
.br
Patterns = Pattern | [Pattern]
.br
Pattern = string() | {Tag, string()} | prompt | {prompt, Prompt}
.br
Prompt = string()
.br
Tag = term()
.br
Opts = [Opt]
.br
Opt = {timeout, Timeout} | repeat | {repeat, N} | sequence | {halt, HaltPatterns} | ignore_prompt
.br
Timeout = integer()
.br
N = integer()
.br
HaltPatterns = Patterns
.br
MatchList = [Match]
.br
Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}
.br
RxMatch = [string()]
.br
HaltReason = done | Match
.br
Reason = timeout | {prompt, Prompt}
.br
.RE
.RS
.LP
Get data from telnet and wait for the expected pattern\&.
.LP
\fIPattern\fR can be a POSIX regular expression\&. If more than one pattern is given, the function returns when the first match is found\&.
.LP
\fIRxMatch\fR is a list of matched strings\&. It looks like this: \fI[FullMatch, SubMatch1, SubMatch2, \&.\&.\&.]\fR where \fIFullMatch\fR is the string matched by the whole regular expression and \fISubMatchN\fR is the string that matched subexpression no \fIN\fR\&. Subexpressions are denoted with \&'(\&' \&')\&' in the regular expression
.LP
If a \fITag\fR is given, the returned \fIMatch\fR will also include the matched \fITag\fR\&. Else, only \fIRxMatch\fR is returned\&.
.LP
The function will always return when a prompt is found, unless the \fIignore_prompt\fR options is used\&.
.LP
The \fItimeout\fR option indicates that the function shall return if the telnet client is idle (i\&.e\&. if no data is received) for more than \fITimeout\fR milliseconds\&. Default timeout is 10 seconds\&.
.LP
The \fIrepeat\fR option indicates that the pattern(s) shall be matched multiple times\&. If \fIN\fR is given, the pattern(s) will be matched \fIN\fR times, and the function will return with \fIHaltReason = done\fR\&.
.LP
The \fIsequence\fR option indicates that all patterns shall be matched in a sequence\&. A match will not be concluded untill all patterns are matched\&.
.LP
Both \fIrepeat\fR and \fIsequence\fR can be interrupted by one or more \fIHaltPatterns\fR\&. When \fIsequence\fR or \fIrepeat\fR is used, there will always be a \fIMatchList\fR returned, i\&.e\&. a list of \fIMatch\fR instead of only one \fIMatch\fR\&. There will also be a \fIHaltReason\fR returned\&.
.LP
\fIExamples:\fR
.br
 \fIexpect(Connection, [{abc, "ABC"}, {xyz, "XYZ"}], [sequence, {halt, [{nnn, "NNN"}]}])\&.\fR
.br
 will try to match "ABC" first and then "XYZ", but if "NNN" appears the function will return \fI{error, {nnn, ["NNN"]}}\fR\&. If both "ABC" and "XYZ" are matched, the function will return \fI{ok, [AbcMatch, XyzMatch]}\fR\&.
.LP
\fIexpect(Connection, [{abc, "ABC"}, {xyz, "XYZ"}], [{repeat, 2}, {halt, [{nnn, "NNN"}]}])\&.\fR
.br
 will try to match "ABC" or "XYZ" twice\&. If "NNN" appears the function will return with \fIHaltReason = {nnn, ["NNN"]}\fR\&.
.LP
The \fIrepeat\fR and \fIsequence\fR options can be combined in order to match a sequence multiple times\&.
.RE
.LP
.B
get_data(Connection) -> {ok, Data} | {error, Reason}
.br
.RS
.TP
Types
Connection = connection() (see module ct_telnet)
.br
Data = [string()]
.br
.RE
.RS
.LP
Get all data which has been received by the telnet client since last command was sent\&.
.RE
.LP
.B
open(Name) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Equivalent to open(Name, telnet)\&.
.RE
.LP
.B
open(Name, ConnType) -> {ok, Handle} | {error, Reason}
.br
.RS
.TP
Types
Name = target_name()
.br
ConnType = connection_type() (see module ct_telnet)
.br
Handle = handle() (see module ct_telnet)
.br
.RE
.RS
.LP
Open a telnet connection to a node\&.
.RE
.LP
.B
open(Name, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
.br
.RS
.LP
Equivalent to open(Name, ConnType, TargetMod, [])\&.
.RE
.LP
.B
open(Name, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}
.br
.RS
.TP
Types
Name = target_name() (see module ct)
.br
ConnType = connection_type()
.br
TargetMod = atom()
.br
Extra = term()
.br
Handle = handle()
.br
.RE
.RS
.LP
Open a telnet connection to the specified target\&.
.LP
The target must exist in a config file, and \fIName\fR is the name allocated to the target - either with \fIct:require/2\fR or with a \fIrequire\fR statement in the test suite default data or the test case info function\&.
.LP
\fITargetMod\fR is a module which exports the functions \fIconnect(Ip, Port, Extra)\fR and \fIget_prompt_regexp()\fR for the given \fITargetType\fR\&.
.RE
.LP
.B
send(Connection, Cmd) -> ok | {error, Reason}
.br
.RS
.TP
Types
Connection = connection() (see module ct_telnet)
.br
Cmd = string()
.br
.RE
.RS
.LP
Send a telnet command and return immediately\&.
.LP
The resulting output from the command can be read with \fIget_data/1\fR or \fIexpect/2/3\fR\&.
.RE
.LP
.B
sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}
.br
.RS
.TP
Types
Connection = connection() (see module ct_telnet)
.br
CmdFormat = string()
.br
Args = list()
.br
.RE
.RS
.LP
Send a telnet command and return immediately (uses a format string and a list of arguments to build the command)\&.
.RE
.SH SEE ALSO
.LP
unix_telnet